teableio_teable/agents.md

Teable v2 agent guide

DDD/domain-model guidance has moved to the skill teable-ddd-domain-model in .codex/skills/teable-ddd-domain-model. Use that skill for any v2/core domain, specification, or aggregate changes.

Git hygiene

• Ignore git changes that you did not make by default; never revert unknown/unrelated modifications unless explicitly instructed.

v2 API contracts (HTTP)

For HTTP-ish integrations, keep framework-independent contracts/mappers in packages/v2/contract-http:

• Define API paths (e.g. /tables) as constants.
• Use action-style paths with camelCase action names (e.g. /tables/create, /tables/get, /tables/rename); avoid RESTful nested resources like /bases/{baseId}/tables/{tableId}.
• Re-export command input schemas (zod) for route-level validation if needed.
• Keep DTO types + domain-to-DTO mappers here.
• Router packages (e.g. @teable/v2-contract-http-express, @teable/v2-contract-http-fastify) should be thin adapters that only:
  • parse JSON/body
  • create a container
  • resolve handlers
  • call the endpoint executor/mappers from @teable/v2-contract-http
• OpenAPI is generated from the ts-rest contract via @teable/v2-contract-http-openapi.

UI components (frontend)

• In app UIs (e.g. apps/playground), use shadcn wrappers from apps/playground/src/components/ui/* (or @teable/ui-lib) instead of importing Radix primitives directly.
• If a shadcn wrapper is missing, add it under apps/playground/src/components/ui before using the primitive.

Dependency injection (DI)

• Do not import tsyringe / reflect-metadata directly anywhere; use @teable/v2-di.
• Do not use DI inside v2/core/src/domain/**; DI is only for application wiring (e.g. v2/core/src/commands/**).
• Prefer constructor injection with explicit tokens for ports (interfaces).
• Provide environment-level composition roots as separate packages (e.g. @teable/v2-container-node, @teable/v2-container-browser) that register all port implementations.

Build tooling (v2)

• v2 packages build with tsdown (not tsc emit). tsc is used only for typecheck (--noEmit).
• Each v2 package has a local tsdown.config.ts that extends the shared base config from @teable/v2-tsdown-config.
• Outputs are written to dist/ (ESM .js + .d.ts), and workspace deps (@teable/v2-*) are kept external (no bundling across packages).

Source visibility (v2 packages)

All v2 packages must support source visibility to allow consumers to reference TypeScript sources without building dist/ outputs. This is required for development workflows, testing, and tools like Vitest/Vite that can consume TypeScript directly.

Required configuration:

• In package.json:
  • Set types field to "src/index.ts" (not "dist/index.d.ts")
  • Set exports["."].types to "./src/index.ts" (not "./dist/index.d.ts")
  • Set exports["."].import to "./src/index.ts" (not "./dist/index.js") to allow Vite/Vitest to use source files directly
  • Keep exports["."].require pointing to "./dist/index.cjs" for CommonJS compatibility
  • Include "src" in the files array (in addition to "dist")
• In tsconfig.json:
  • Map workspace dependencies to their src paths in compilerOptions.paths (e.g. "@teable/v2-core": ["../core/src"])
  • Include those source paths in the include array

Example package.json configuration:

{
  "types": "src/index.ts",
  "exports": {
    ".": {
      "types": "./src/index.ts",
      "import": "./src/index.ts",
      "require": "./dist/index.cjs"
    }
  },
  "files": ["dist", "src"]
}

Note: Since v2 packages are workspace-only ("private": true) and not published to npm, pointing import to source files is safe. Vite/Vitest can process TypeScript files directly, enabling faster development cycles without requiring dist/ to be built first.