@terreno/mcp 0.31.0 → 56.0.0-beta.2

package/src/docs/versioned/next/tasks/rtk-to-syncdb-migration-docs.md

@@ -2,9 +2,9 @@
 
 See: [`docs/implementationPlans/rtk-to-syncdb-migration-docs.md`](../implementationPlans/rtk-to-syncdb-migration-docs.md)
 
-**RTK deprecation flag:** **Blocked.** Do not start any task in this file until a `@terreno/syncdb` package is merged into `master`. PR [#869](https://github.com/flourishhealth/terreno/pull/869) was the delivery vehicle but is **closed, not merged** (checked 2026-08-09) and no `syncdb/` package exists on `master`. Verify with `git log --oneline master | rg -i syncdb` before beginning.
+**RTK deprecation flag:** **Unblocked on `release-56.0.0`.** `@terreno/syncdb` lives on the `release-56.0.0` launch branch (`syncdb/`), not `master` and not PR #869 (closed). This work is authored on and targets `release-56.0.0`. Verify with `git ls-tree origin/release-56.0.0 --name-only | rg -i syncdb`.
 
-**Migration strategy (decision M6, reaffirmed 2026-08-09):** this IP ships *context for an AI agent to perform the migration*, not a migration script or codemod. The deliverables are the syncdb reference, a guide built from verified before/after pairs, and the `upgrading-terreno` skill that drives an agent through a per-screen `USE_SYNCDB` rollout. See the "Migration strategy: AI-context-first" section in the IP. Do not author a codemod as the primary path.
+**Migration strategy (decision M6, reaffirmed 2026-08-09):** ship *context for an AI agent to perform the migration* (syncdb reference + verified before/after pairs + the `upgrading-terreno` skill), not a codemod. See the "Migration strategy: AI-context-first" section in the IP.
 
 ## Instructions for the implementing agent
 
@@ -16,19 +16,19 @@ See: [`docs/implementationPlans/rtk-to-syncdb-migration-docs.md`](../implementat
 
 ## Phase 1: Reconcile with merged #869
 
-- [ ] **Task 1.1**: Inventory the merged syncdb public API
+- [x] **Task 1.1**: Inventory the merged syncdb public API
   - Description: Read the merged `syncdb/src/index.ts` and every module it re-exports. Produce `docs/implementationPlans/syncdb-api-inventory.md` (a temporary working document, deleted in Task 6.6) listing every exported symbol with its signature, a one-line description, and the source file. Separately list: the client config options, every React hook, every client method, the conflict-resolution API, the sync-status API, and the codegen CLI surface. Also record whether local-first is the only mode or an opt-in (IP blocking question M7) and whether `bun run sdk` still works (M5).
   - Files: `docs/implementationPlans/syncdb-api-inventory.md` (new, temporary)
   - Depends on: PR #869 merged
   - Acceptance: every symbol in the inventory is greppable in `syncdb/src/`; M5 and M7 are answered with a file-and-line citation.
 
-- [ ] **Task 1.2**: Correct the IP surface map against reality
+- [x] **Task 1.2**: Correct the IP surface map against reality
   - Description: Compare the inventory from Task 1.1 to the "Documentation surface map" and "Known RTK-shaped surfaces" tables in the IP and in `docs/implementationPlans/oss-launch-program.md`. Update both files where reality differs. Add rows for any surface #869 introduced that neither table anticipated (for example new socket events, new backend routes under `api/src/sync/`, `excludeArchivedPlugin`, tenant/organization permission helpers). Report the deltas in the PR body.
   - Files: `docs/implementationPlans/rtk-to-syncdb-migration-docs.md`, `docs/implementationPlans/oss-launch-program.md`
   - Depends on: Task 1.1
   - Acceptance: both surface maps match the merged code; every added row cites a file path; the PR body lists what changed from the pre-merge hypothesis.
 
-- [ ] **Task 1.3**: Capture the reference migration from #869
+- [x] **Task 1.3**: Capture the reference migration from #869
   - Description: `git log` the #869 merge and extract the diff for `example-frontend` — the actual RTK → syncdb migration of the todos flow. Save the before/after pairs (store setup, one read hook, one write hook, conflict UI, sync status UI) into the working inventory doc. These become the code samples for the migration guide. Note anything the reference migration did *not* cover (auth, feature flags, other screens).
   - Files: `docs/implementationPlans/syncdb-api-inventory.md`
   - Depends on: Task 1.1
@@ -36,7 +36,7 @@ See: [`docs/implementationPlans/rtk-to-syncdb-migration-docs.md`](../implementat
 
 ## Phase 2: Reference documentation
 
-- [ ] **Task 2.1**: Write `docs/reference/syncdb.md`
+- [x] **Task 2.1**: Write `docs/reference/syncdb.md`
   - Description: New reference page following the structure of `docs/reference/rtk.md` (read it first for tone and section ordering). Sections: installation and peer dependencies; `createSyncDbClient` config table (every option, type, default, description); provider setup; read hooks; mutation hooks; conflict API; sync-status API; the Redux bridge if it shipped; codegen; environment variables. Every option in the config table must come from the inventory. Include a runnable example per hook.
   - Files: `docs/reference/syncdb.md` (new)
   - Depends on: Task 1.1
@@ -56,25 +56,25 @@ See: [`docs/implementationPlans/rtk-to-syncdb-migration-docs.md`](../implementat
 
 ## Phase 3: Migration guide
 
-- [ ] **Task 3.1**: Draft the migration guide skeleton with verified samples
+- [x] **Task 3.1**: Draft the migration guide skeleton with verified samples
   - Description: Create `docs/how-to/migrate-rtk-to-syncdb.md` with the eleven sections from the IP. Populate sections 2–4 (install/configure, reads, writes) using the before/after pairs captured in Task 1.3. For section 4, explicitly list the RTK-era code that should be **deleted** after migrating (manual optimistic updates, `isLoading` spinners on writes, refetch-after-mutate patterns) — this is the part consumers get wrong.
   - Files: `docs/how-to/migrate-rtk-to-syncdb.md` (new)
   - Depends on: Task 1.3, Task 2.1
   - Acceptance: sections 1–4 complete; every code block traceable to a real file; section 4 has a "delete this" list.
 
-- [ ] **Task 3.2**: Document conflicts and sync status
+- [x] **Task 3.2**: Document conflicts and sync status
   - Description: Complete sections 5 and 6. Explain what a conflict is in this system, exactly when one is produced (cite the server-side 409/nack path in `api/src/sync/`), the two v1 resolution strategies, and the minimum UI a consumer must build. For sync status, show how to replace request-level loading UX with sync-state UX. Use the `example-frontend` implementation as the reference; if it has no conflict UI, say so and link a follow-up issue rather than inventing one.
   - Files: `docs/how-to/migrate-rtk-to-syncdb.md`
   - Depends on: Task 3.1
   - Acceptance: the conflict trigger is cited to a source file; both strategies documented; the minimum-UI requirement is concrete (named components or hooks).
 
-- [ ] **Task 3.3**: Document the auth migration
+- [x] **Task 3.3**: Document the auth migration
   - Description: Complete section 7. Cover: `generateAuthSlice` → Better Auth session, token storage differences on native versus web, the socket auth handshake changes from #869 (pluggable socket auth, Better Auth bearer sessions, session revalidation, `sync:auth-expired`), required backend config (`BETTER_AUTH_SECRET`, `BETTER_AUTH_URL`, `trustedOrigins`), and the cross-domain cookie requirements. State clearly that auth can be migrated *before* the data layer (IP question M3) and give the two-step order.
   - Files: `docs/how-to/migrate-rtk-to-syncdb.md`
   - Depends on: Task 3.2
   - Acceptance: every env var named exists in `docs/reference/environment-variables.md` after this IP; the `sync:auth-expired` event is cited to source; the two-step order is stated in the first paragraph of the section.
 
-- [ ] **Task 3.4**: Document codegen, feature flags, rollback, and the checklist
+- [x] **Task 3.4**: Document codegen, feature flags, rollback, and the checklist
   - Description: Complete sections 8–11. Codegen: whether `bun run sdk` is unchanged (answer from Task 1.1), what the generated file looks like now, and the update to `openapi-config.ts`. Feature flags: how the OpenFeature provider is fed post-migration. Rollback: per-screen rollback via `USE_SYNCDB` and what state is left behind (IndexedDB contents, outbox entries) when rolling back. Checklist: a copy-pasteable ordered checklist covering everything in sections 1–10.
   - Files: `docs/how-to/migrate-rtk-to-syncdb.md`, `docs/how-to/README.md`
   - Depends on: Task 3.3

package/src/docs/versioned/next/tasks/syncdb-codegen.md

@@ -0,0 +1,65 @@
+# Task List: @terreno/syncdb-codegen
+
+Paired with [docs/implementationPlans/syncdb-codegen.md](../implementationPlans/syncdb-codegen.md). Each task is independently implementable and testable.
+
+## Phase 1: syncdb runtime
+
+- [ ] **Task 1.1**: Per-mutation `maxAttempts` plumbing
+  - Description: Add optional `maxAttempts` to `MutateArgs`, store it as an optional cell on the outbox row, and have the replay coordinator's `error`-nack branch use `row.maxAttempts ?? MAX_ERROR_NACK_ATTEMPTS` when deciding terminal failure. Missing cell keeps current behavior.
+  - Files: `syncdb/src/client.ts`, `syncdb/src/mutations/outbox.ts`, `syncdb/src/storage/schema.ts`, `syncdb/src/sync/replayCoordinator.ts`, `syncdb/src/sync/replayCoordinator.test.ts`, `syncdb/src/mutations/outbox.test.ts`
+  - Depends on: none
+  - Acceptance: `maxAttempts: 1` fails terminally after one error nack; omitted preserves 5-attempt exponential backoff; existing tests unchanged.
+
+- [ ] **Task 1.2**: `createCollectionHooks` factory
+  - Description: New `createCollectionHooks<TData, TCreate, TUpdate>({collection, retries})` in `@terreno/syncdb/react` returning the five per-operation hooks `{useListQuery, useReadQuery, useCreateMutation, useUpdateMutation, useDeleteMutation}`. Read hooks delegate to the existing `useQuery`/`useEntity`; mutation hooks return one-element `[trigger]` tuples (RTK call-site parity) whose triggers wrap `client.mutate`, mapping `retries` (false → 1, number → n, omitted → undefined) to `maxAttempts`.
+  - Files: `syncdb/src/react/collectionHooks.ts` (new), `syncdb/src/react/collectionHooks.test.tsx` (new), `syncdb/src/react/index.ts`
+  - Depends on: Task 1.1
+  - Acceptance: factory hooks behave identically to direct hook calls; `const [create] = useCreateMutation()` destructuring compiles and works; typed create/update payloads compile; `retries` reaches the outbox row.
+
+## Phase 2: OpenAPI extension in @terreno/api
+
+- [ ] **Task 2.1**: Emit `x-terreno-sync` on list operations
+  - Description: When `modelRouter` options include `sync`, the list operation's OpenAPI object gains `"x-terreno-sync": {collection, scope}` where `collection` is the route path without the leading slash and `scope` is the scope type ("owner" | "tenant" | "broadcast" | "custom").
+  - Files: `api/src/openApi.ts`, `api/src/openApi.test.ts` (or the existing spec-generation test file)
+  - Depends on: none
+  - Acceptance: spec for a synced model contains the extension with correct collection tag and scope; non-synced routes contain no extension; RTK codegen output for example-frontend is unchanged.
+
+## Phase 3: codegen package
+
+- [ ] **Task 3.1**: Package scaffold
+  - Description: New `syncdb-codegen/` workspace package (`@terreno/syncdb-codegen`) with bin `terreno-syncdb-codegen` (`#!/usr/bin/env bun`), `compile`, `test`, `lint`, and `build:binary` (`bun build --compile src/cli.ts --outfile dist/terreno-syncdb-codegen`) scripts, modeled on `syncdb/` + the `mcp-server` bin pattern.
+  - Files: `syncdb-codegen/package.json` (new), `syncdb-codegen/tsconfig.json` (new), `syncdb-codegen/biome.jsonc` (new), root `package.json` (workspaces + `syncdb-codegen:compile`/`syncdb-codegen:test` scripts)
+  - Depends on: none
+  - Acceptance: `bun run syncdb-codegen:compile` and `bun run lint` pass from the repo root.
+
+- [ ] **Task 3.2**: Spec loading and collection discovery
+  - Description: Load the OpenAPI document from a URL or file path; walk `paths` for `x-terreno-sync` extensions; resolve each collection's entity schema (list response `data` items ref), create body, and update body schema refs; apply `--collections` as filter or fallback; fail with an actionable error when no collections resolve.
+  - Files: `syncdb-codegen/src/loadSpec.ts` (new), `syncdb-codegen/src/discoverCollections.ts` (new), tests, `syncdb-codegen/src/fixtures/openapi.example.json` (new, captured from example-backend)
+  - Depends on: Task 2.1, Task 3.1
+  - Acceptance: fixture spec yields `[{collection: "todos", entityRef, createRef, updateRef}]`; missing extensions + no flag exits non-zero.
+
+- [ ] **Task 3.3**: Type and SDK emitters
+  - Description: Emit TS interfaces from the OpenAPI schema subset produced by `mongoose-to-swagger` (objects, primitives, string-union enums, arrays, `$ref`, required lists), then assemble the output file: generated header, interfaces, `SYNC_COLLECTIONS as const`, and one destructured `createCollectionHooks` block per collection renaming the factory keys to RTK-style hook names (`useListQuery: useGetTodosQuery`, `useReadQuery: useGetTodosByIdQuery`, `useCreateMutation: usePostTodosMutation`, `useUpdateMutation: usePatchTodosByIdMutation`, `useDeleteMutation: useDeleteTodosByIdMutation`), with per-collection `retries` overrides from `--config` JSON applied. Name derivation must match `@rtk-query/codegen-openapi`'s pascal-case of the route path. Format via `bunx biome check --write` when available; `--no-format` skips.
+  - Files: `syncdb-codegen/src/emitTypes.ts` (new), `syncdb-codegen/src/emitSdk.ts` (new), snapshot tests
+  - Depends on: Task 3.2
+  - Acceptance: snapshot output type-checks; emitted hook names for the todos fixture are byte-identical to the RTK-generated names in `example-frontend/store/openApiSdk.ts`; `{overrides: {todos: {retries: false}}}` appears as `retries: false` in the emitted factory call.
+
+- [ ] **Task 3.4**: CLI entry and binary build
+  - Description: `cli.ts` wires arg parsing (`util.parseArgs`) → load → discover → emit → write, with clear usage/error output and non-zero exit codes. Verify `build:binary` produces a standalone executable with identical output.
+  - Files: `syncdb-codegen/src/cli.ts` (new), `syncdb-codegen/src/cli.test.ts` (new)
+  - Depends on: Task 3.3
+  - Acceptance: `terreno-syncdb-codegen --schema fixtures/openapi.example.json --out /tmp/out.ts` succeeds; missing required args print usage and exit 1; compiled binary output matches bin output byte-for-byte.
+
+## Phase 4: Integration and docs
+
+- [ ] **Task 4.1**: example-frontend integration
+  - Description: Add `sync-sdk` script and `syncdb-codegen.json`, check in generated `store/syncDbSdk.ts`, source `SYNC_COLLECTIONS` from it in `store/syncdb.ts`, and migrate `SyncTodosScreen` to the generated hooks (`useGetTodosQuery`, `usePostTodosMutation`, `usePatchTodosByIdMutation`, `useDeleteTodosByIdMutation`; delete the local `SyncTodo` interface). Imports come from `@/store/syncDbSdk` — never re-export these alongside `openApiSdk.ts` from a shared barrel, since the names intentionally collide.
+  - Files: `example-frontend/package.json`, `example-frontend/syncdb-codegen.json` (new), `example-frontend/store/syncDbSdk.ts` (generated), `example-frontend/store/syncdb.ts`, `example-frontend/components/SyncTodosScreen.tsx`
+  - Depends on: Task 1.2, Task 3.4
+  - Acceptance: `bun run sync-sdk` regenerates with no diff against an unchanged backend; syncdb Playwright e2e suite passes; `compile` passes.
+
+- [ ] **Task 4.2**: Documentation
+  - Description: Codegen section in `syncdb/README.md`, new `syncdb-codegen/README.md` (args, config format, custom-hooks pattern via `createCollectionHooks`), and a note in the RTK migration guide pointing at generated hooks.
+  - Files: `syncdb/README.md`, `syncdb-codegen/README.md` (new), `docs/how-to/migrate-rtk-to-syncdb.md`
+  - Depends on: Task 4.1
+  - Acceptance: docs cover install, generation, custom hooks, and retries overrides; examples compile as written.