new-feature
End-to-end checklist for adding a feature to tereo — declaration, schema, routes, audit and events, OpenAPI, tests, docs, SDK and UI
SKILL.md.claude/skills/new-feature/SKILL.md
GitHubNew Feature Checklist
End-to-end guide for adding $ARGUMENTS to tereo.
Core is one service, packages/tereo (port 4001), with one Postgres
database and a schema per area (auth, files, webhooks, audit, plus core).
All paths below are relative to packages/tereo unless they start with
packages/. Commands are in the dev skill.
Step 1: Declaration (src/definitions/)
Core's permissions, system roles, buckets and event types are declared, not
seeded: CORE_DECLARATION (definitions/declaration.ts) is registered by
registerCore() on every start. Removing an item retires it a day later. Admins
never create permissions or edit system roles.
- Permissions →
definitions/permissions.ts- Add a group with
domainPermissions(domain, displayName, description, actions?)(generatesdomain.read|write|delete|admin; pass a subset, or includearchive), or explicit entries for one-off names (services.approve,webhooks.emit) - Spread the group into
PERMISSION_CATALOG - Add constants to
PERMISSIONSif call sites use them - Hierarchy:
writeincludesread,deleteincludeswrite,adminincludes all
- Add a group with
- System roles →
definitions/roles.ts(ROLES) — only if an existing role (admin,platform_admin, the*_adminroles) shouldn't simply cover it - Buckets core itself writes →
definitions/buckets.ts(BUCKETS) - Webhook event types →
definitions/eventTypes.ts(EVENT_TYPES), format<area>.<resource>.<verb>(e.g.auth.organization.created).emitTxthrows on any event type not listed here - Never declare under a namespace an app service owns — app services declare
their own in provisioning documents (
docs/provisioning.md)
Step 2: Database model (prisma/schema.prisma)
- Add the model under its area's section, with
@@schema("<area>")and@@map("snake_case_table"); columns get@map("snake_case")id String @id @default(uuid(7)) @db.UuidorganizationId String @map("organization_id") @db.Uuidwith a relation toOrganization(onDelete: Restrict) when the row is tenant-scoped- Every "who" column (
createdBy,userId, …) is@db.Uuidwith a relation toUser(onDelete: Restrict). Clients act as their service-account user; core acts asSYSTEM_USER_ID(definitions/systemUser.ts) createdAt DateTime @default(now()) @map("created_at"),updatedAt DateTime @updatedAt @map("updated_at")- Things that are retired get
archivedAt DateTime? @map("archived_at")— users and organizations are deactivated or archived, never deleted @@indexthe foreign keys and the columns lists filter on
-
npx prisma migrate dev --create-only --name <name> - Append raw SQL only for what Prisma can't express — range partitioning,
partial and opclass indexes, CHECK constraints. On
audit_log_entries/webhook_deliveries, delete only the PK-reset statement Prisma emits - Raw SQL anywhere names tables with their schema (
"files"."objects") — there is nopublicschema -
npx prisma migrate deploy,npx prisma generate - DB functions in
src/utils/db/<resource>.ts(get, getPaginated, create, update, …), each taking an optionaltx?: Prisma.TransactionClient; add the module to the default export insrc/utils/db/index.ts. ThrowNotFoundErroretc. fromsrc/utils/errors.tshere, asutils/db/organizations.tsdoes - Seed data, if any, goes in
src/scripts/seed.tsand must stay idempotent
Step 3: Routes (src/routes/)
The folder tree mirrors the URL: the protocol endpoints at the root (oauth/, well-known/,
wired in routes/index.ts); everything else is core's API under v1/ (v1/account/, v1/admin/,
v1/setup/, v1/files/, v1/webhooks/, v1/audit/), wired in
routes/v1/index.ts. A new API route goes under routes/v1/. Follow the routes skill for
where each file goes and the registration order — tests/conventions/routeLayout.unit.test.ts enforces the layout.
-
routes/<…>/<resources>/schemas.ts— Zod schemas: create/update bodies,:idparams, and the list query viacreateCursorQuerySchema()fromutils/parseQueryString.ts -
routes/<…>/<resources>/controllers.ts— handlersvalidateBody/validateParams/validateQueryfromutils/validateReq.tsvalidateUser(req)frommiddleware/auth.tsfor the caller- Call
db.<resource>.*, not Prisma directly - Throw the error classes from
utils/errors.ts— neverres.status(400).json(...) - Lists:
applyCursorToWhere+buildCursorPageResponsefromutils/cursor.ts; shape responses with aformat*function inutils/transformers.ts
-
routes/<…>/<resources>/index.ts— the router. Item routes go in a singular subfolder (<resource>/index.ts,Router({ mergeParams: true })) mounted withrouter.use("/:id", …); seeroutes/v1/admin/services/requireAuthon the parent router (admin/,files/,webhooks/, andaudit/index files already apply it)requirePermission("<name>")on every route
- Mount the router in its parent
index.ts - ESM:
.json every relative import, directory imports included (./services/index.js) - Imports sorted by the repo rule —
npm run sort-imports
Step 4: Audit and webhooks — in the transaction
- Wrap each mutation in
db.$transaction(async (tx) => { … }) -
logAuditTx(tx, { auth, organizationId, action, entityType, entityId, entityName, changes?, metadata? })fromutils/outbox.ts—actionisCREATE | UPDATE | DELETE | MERGE | ARCHIVE | RESTORE - For updates,
computeChanges(old, new)(same file) forchanges -
emitTx(tx, { organizationId, eventType, entityType, entityId, data })— writescore.outbox; the worker's reaper fans it out after commit - Both commit or roll back with the business write. No fire-and-forget calls for anything that must happen
Pattern: routes/v1/admin/organizations/controllers.ts (createOrganization).
Step 5: OpenAPI (openapi/)
One spec covers every area; files are split by area (auth, files, webhooks, audit).
- Path file:
openapi/paths/<area>/<resource>.yaml(admin auth routes live inopenapi/paths/auth/admin/), keyed by the full path including the mount (/v1/files/buckets/{name},/v1/webhooks/webhooks) - Schemas:
openapi/components/<area>/schemas.yaml(shared responses, parameters and headers are inopenapi/components/*.yaml) - Reference the path in the root
openapi/openapi.yaml, and tag it with a tag from that area'sx-tagGroupsentry - Every operation declares
security— the root'sBearerAuthapplies to any that doesn't, so a public one must saysecurity: [] - Lint and re-bundle from
packages/tereo:npm run openapi:build
Step 6: Tests (src/tests/routes/<URL path>/)
One suite against one server; globalSetup migrates and seeds <db>_test.
-
src/tests/routes/<URL path>/<folder>.test.ts, plus.validation.unitand.permissionsfiles assrc/tests/README.mdsays; tags one per line - Real users and tokens — no test-mode shortcut:
getTestPrincipalToken({ permissions: [...], organizationId?, userId? })fromtests/support/principals.ts; area helpers intests/support/<area>.ts - Permissions, roles and event types a test needs that aren't core's: make
them under the test service (
ensurePermission,TEST_SERVICE_IDfromtests/support/testService.ts), never under core — core's declaration would retire them - Cover: create, read, update, delete/archive, list with cursor pagination
- Cover: 403 without the permission, 400 on bad input, 404 on unknown ids
- Assert the audit entry and the outbox row where the mutation writes them
- Clean up what the file creates (
afterAll, or the area'scleanupAllTestEntities)
Step 7: SDK (packages/tereo-sdk) — if app services need it
- Request in
src/requests/<area>/<resource>/index.tsusingtryHandleRequestwithCORE_CLIENT(seerequests/auth/organizations/index.ts); export it from the area'sindex.ts - Types in
src/requests/<area>/types.tsorsrc/types/<area>.ts - Method on the area client in
src/clients/<area>.ts, reachable fromcreateCoreClient(src/coreClient.ts) - Tests in
src/tests/ -
npm run version-plan— the SDK is a released library
Step 8: UI
The admin app is packages/tereo-ui (Vite + React):
- Build any screen from
@kosmeo-ui/reactprimitives (Page,InfiniteScroll+useInfiniteCursor,Modal,BorderedSection,DetailField) - A missing primitive goes into
@kosmeo-ui/reactupstream, not a one-off here - Put the screen in its feature folder (
src/features/<area>/), export what other features need from the feature'sindex.ts, and add its route undersrc/app/routes/ - Gate it on the permission the API requires, as the existing sidebars and routes do
Step 9: Documentation
-
packages/tereo/docs/<area>.md(auth,files,webhooks,audit,registry,telemetry) — new resource, endpoints, permissions, events - Root
CLAUDE.md/README.mdif layout, conventions or the "Current state" section changed
Step 10: Finalize
-
npm run formatandnpm run sort-imports -
npm run lintandnpm run check -
npm run test:unitplus the feature's ownintfiles inpackages/tereo(the full suite runs in CI, or once at the end withdocker/test/run.sh);npx nx run @tereo-io/sdk:testif the SDK changed -
npm run version-planif@tereo-io/sdk,tereoortereo-uichanged