refactor: refactoring core

.claude/skills/teable-v2-package-guide/SKILL.md

@@ -0,0 +1,209 @@
+# Teable V2 Package Creation Guide
+
+## When to Use This Skill
+
+Use this skill when you need to:
+- Create a new v2 package
+- Configure package.json for v2 packages
+- Set up TypeScript configuration
+- Understand the v2 package conventions
+
+## Package Location
+
+All v2 packages are located in `packages/v2/` directory.
+
+## Creating a New Package
+
+### 1. Directory Structure
+
+```
+packages/v2/<package-name>/
+├── src/
+│   └── index.ts          # Main entry point
+├── package.json
+├── tsconfig.json
+├── tsconfig.build.json
+└── tsdown.config.ts      # Optional, for custom build config
+```
+
+### 2. Package.json Configuration
+
+**IMPORTANT: Development-Friendly Exports**
+
+The key to avoiding rebuilds during development is the `exports` configuration:
+
+```json
+{
+  "name": "@teable/v2-<package-name>",
+  "version": "0.0.0",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts",
+      "module": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsdown --tsconfig tsconfig.build.json",
+    "dev": "tsdown --tsconfig tsconfig.build.json --watch",
+    "clean": "rimraf ./dist ./coverage ./tsconfig.tsbuildinfo ./tsconfig.build.tsbuildinfo ./.eslintcache",
+    "lint": "eslint . --ext .ts,.js,.mjs,.cjs,.mts,.cts --cache --cache-location ../../../.cache/eslint/v2-<package-name>.eslintcache",
+    "typecheck": "tsc --project ./tsconfig.json --noEmit",
+    "test-unit": "vitest run --silent",
+    "test-unit-cover": "pnpm test-unit --coverage",
+    "fix-all-files": "eslint . --ext .ts,.js,.mjs,.cjs,.mts,.cts --fix"
+  },
+  "dependencies": {
+    // Add your dependencies here
+  },
+  "devDependencies": {
+    "@teable/v2-tsdown-config": "workspace:*",
+    "@teable/eslint-config-bases": "workspace:^",
+    "@types/node": "22.18.0",
+    "@vitest/coverage-v8": "4.0.16",
+    "eslint": "8.57.0",
+    "prettier": "3.2.5",
+    "rimraf": "5.0.5",
+    "tsdown": "0.18.1",
+    "typescript": "5.4.3",
+    "vite-tsconfig-paths": "4.3.2",
+    "vitest": "4.0.16"
+  }
+}
+```
+
+### Key Export Configuration Explained
+
+```json
+"exports": {
+  ".": {
+    "types": "./src/index.ts",     // TypeScript types from source
+    "import": "./src/index.ts",    // ESM import uses source directly
+    "module": "./dist/index.js",   // Bundlers use built output
+    "require": "./dist/index.cjs"  // CommonJS uses built output
+  }
+}
+```
+
+**Why this works:**
+- `types` and `import` point to `./src/index.ts` - this allows other packages to import TypeScript source directly during development
+- `module` and `require` point to `./dist/` - this is used by bundlers and production builds
+- No rebuild needed when you change source code - other packages see changes immediately
+
+### 3. TypeScript Configuration
+
+**tsconfig.json** (for development/typechecking):
+```json
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "types": ["node"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}
+```
+
+**tsconfig.build.json** (for building):
+```json
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "exclude": ["node_modules", "dist", "**/*.spec.ts", "**/*.test.ts"]
+}
+```
+
+### 4. Build Configuration (Optional)
+
+**tsdown.config.ts**:
+```typescript
+import { defineConfig } from '@teable/v2-tsdown-config';
+
+export default defineConfig();
+```
+
+## Common Patterns
+
+### Workspace Dependencies
+
+Use `workspace:*` for internal dependencies:
+```json
+"dependencies": {
+  "@teable/v2-core": "workspace:*",
+  "@teable/v2-di": "workspace:*"
+}
+```
+
+### Dependency Injection
+
+V2 packages use `@teable/v2-di` for DI:
+```typescript
+import { injectable, inject } from '@teable/v2-di';
+
+@injectable()
+export class MyService {
+  constructor(
+    @inject(someToken) private readonly dependency: SomeDependency
+  ) {}
+}
+```
+
+### Error Handling
+
+Use `neverthrow` for Result types:
+```typescript
+import { ok, err, Result } from 'neverthrow';
+import { domainError, type DomainError } from '@teable/v2-core';
+
+function doSomething(): Result<Data, DomainError> {
+  if (error) {
+    return err(domainError.invariant({ message: 'Something went wrong' }));
+  }
+  return ok(data);
+}
+```
+
+## Checklist for New Package
+
+- [ ] Create directory `packages/v2/<package-name>/`
+- [ ] Create `src/index.ts` with exports
+- [ ] Configure `package.json` with correct exports (pointing to source)
+- [ ] Create `tsconfig.json` and `tsconfig.build.json`
+- [ ] Add to root `pnpm-workspace.yaml` if needed
+- [ ] Run `pnpm install` to link workspace dependencies
+- [ ] Verify imports work without building: `pnpm typecheck`
+
+## Troubleshooting
+
+### "Cannot find module" errors
+1. Check that `exports` in `package.json` points to correct paths
+2. Ensure `types` field points to `src/index.ts`
+3. Run `pnpm install` to refresh workspace links
+
+### Changes not reflected in other packages
+1. Verify `exports.import` points to `./src/index.ts` (not `./dist/`)
+2. Check if the consuming package has cached the old build
+3. Restart TypeScript server in your IDE
+
+### Build errors
+1. Ensure `tsconfig.build.json` excludes test files
+2. Check that all dependencies are properly declared
+3. Run `pnpm clean` before rebuilding

.claude/skills/teable-v2-table-template/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: teable-v2-table-template
+description: Create or update Teable v2 table templates in packages/v2/table-templates (template seeds, fields, records, and exports).
+---
+
+# Teable v2 Table Template Skill
+
+Use this skill when you need to add or modify table templates in the v2 codebase. Templates live in `packages/v2/table-templates/src/index.ts`.
+
+## Quick workflow
+
+1. Open the template source file: `packages/v2/table-templates/src/index.ts`.
+2. Add a seed builder:
+   - Single table: create a `createXSeed(): SingleTableSeed`.
+   - Multi table: create a `createXTemplateSeed(): TemplateSeed`.
+3. Use helpers for IDs and select options:
+   - `createFieldId()` for field IDs
+   - `createTableId()` if you must predefine table IDs
+   - `createSelectOption()` for single/multi-select choices
+4. Create the template definition:
+   - Single table: `singleTable(key, name, description, createXSeed, defaultRecordCount)`
+   - Multi table: `createTemplate(key, name, description, createXTemplateSeed, defaultRecordCount)`
+5. Export the template and add it to `tableTemplates` array.
+6. If you need a field-only helper, export `createXFields = () => createXSeed().fields;`.
+
+## Notes and conventions
+
+- Keep templates in `packages/v2/table-templates/src/index.ts` (this package is the single source of truth).
+- The `createInput` generator in `TableTemplateDefinition` handles optional record seeding and name prefixing. You only need to supply seed fields and records.
+- Prefer `singleTable(...)` unless the template truly needs multiple tables (e.g., CRM with Companies + Contacts).
+- Use string keys that are stable and URL-safe (e.g., `content-calendar`, `bug-triage`).
+- When seeding records, keep records small and representative; use `normalizeTemplateRecords` behavior to cap or pad.
+- New templates should cover as many field types as possible, as long as the business context makes sense (use `allFieldTypesTemplate` for inspiration).
+
+## Example pattern
+
+```ts
+const createMyTemplateSeed = (): SingleTableSeed => {
+  const nameFieldId = createFieldId();
+  return {
+    fields: [{ type: 'singleLineText', id: nameFieldId, name: 'Name' }],
+    records: [{ fields: { [nameFieldId]: 'Example' } }],
+  };
+};
+
+export const myTemplate = singleTable(
+  'my-template',
+  'My Template',
+  'Short description.',
+  createMyTemplateSeed,
+  1
+);
+
+export const tableTemplates = [
+  // ...existing templates,
+  myTemplate,
+] as const;
+```
+
+## References
+
+- Source of truth: `packages/v2/table-templates/src/index.ts`
+- Package note: `packages/v2/table-templates/ARCHITECTURE.md`
+- E2E contract: ensure `creates tables for every template with seeded records` passes in `packages/v2/e2e`.
+- Suggested run: `pnpm -C packages/v2/e2e test -- --runInBand --testNamePattern "creates tables for every template with seeded records"`

.claude/skills/teable-v2-test-debug/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: teable-v2-test-debug
+description: Debug Teable v2 tests and failing test cases by prioritizing data reproduction and inspection. Use when asked to debug a test file/spec (unit, integration, or e2e) in packages/v2/*, especially when failures might be caused by table schema, relations, or stored/computed data drift; workflow uses v2-devtools CLI to create a similar table first, then inspects real DB data/relations, and only then reviews code logic.
+---
+
+# Teable V2 Test Debug
+
+## Overview
+
+Follow a data-first debugging workflow for Teable v2 tests. The default order is: reproduce data with devtools, inspect real DB data/relations, then analyze code logic.
+
+## Workflow: Data-first test debugging
+
+### 1) Capture failure context
+
+- Identify the failing test name, file path, and the exact assertion that failed.
+- Note the expected vs actual values and any IDs shown in logs (base/table/field/record).
+- If the failure is e2e or integration, confirm which base or seed data was used.
+
+### 2) Reproduce with devtools first (create similar table)
+
+- Use the v2-devtools CLI to create a minimal table that mirrors the test schema.
+- Prefer CLI-based table creation and mock data over hand-written SQL.
+- If the schema is complex, build only the fields involved in the failing assertion.
+
+Common commands:
+
+```bash
+# Get field schema documentation before creating tables
+pnpm --filter @teable/v2-devtools cli tables describe-schema
+
+# Create a table with minimal fields
+pnpm --filter @teable/v2-devtools cli tables create --base-id bse... --name "Test Table" --fields '[{"type":"singleLineText","name":"Name","isPrimary":true}]'
+
+# Generate mock records if data shape matters
+pnpm --filter @teable/v2-devtools cli mock generate --table-id tbl... --count 10 --seed 12345
+```
+
+If the v2-devtools skill exists, open `/Users/nichenqin/projects/teable/.codex/skills/teable-v2-devtools/SKILL.md` for the full command reference and validation rules.
+
+### 3) Inspect real DB data and relations
+
+- Compare application layer vs underlying data first; use stored/computed modes.
+- Inspect dependencies and relations to confirm lookup/rollup/formula inputs.
+- Validate schema constraints if missing indexes or FK columns are suspected.
+
+Common commands:
+
+```bash
+# App-layer data (stored/computed) vs underlying
+pnpm --filter @teable/v2-devtools cli records list --table-id tbl... --mode stored --limit 10
+pnpm --filter @teable/v2-devtools cli records list --table-id tbl... --mode computed --limit 10
+pnpm --filter @teable/v2-devtools cli underlying records --table-id tbl... --limit 10
+
+# Inspect a field and its dependencies
+pnpm --filter @teable/v2-devtools cli underlying field --field-id fld...
+pnpm --filter @teable/v2-devtools cli relations --field-id fld... --direction up --level 2
+
+# Check schema integrity if queries are slow or failing
+pnpm --filter @teable/v2-devtools cli schema table --table-id tbl...
+```
+
+### 4) Only then review code logic
+
+- Map the observed data mismatch back to the handler, visitor, or mapper.
+- Verify spec/visitor logic before touching application wiring.
+- If the bug is only reproducible with real DB data, prefer adjusting fixtures or seeding rather than altering logic.
+
+### 5) Decide next action
+
+- If app-layer vs underlying differs, focus on computed/stored pipeline and mappers.
+- If dependencies are wrong, fix field definitions or relation setup first.
+- If reproduction fails on minimal data, debug core logic with a tight fixture.