@terreno/mcp 57.21.0 → 58.0.0-beta.1

package/src/docs/versioned/next/how-to/add-feature-flags.md

@@ -54,49 +54,66 @@ After adding the backend routes, regenerate the SDK so the frontend can call the
 cd your-frontend && bun run sdk
 ```
 
-Regeneration may emit a hook for `/feature-flags/flagConfiguration`; prefer **`useTerrenoFeatureFlags`** / **`useFeatureFlags`** from `@terreno/rtk` so OpenFeature domain, cache keying, and optional socket refetch stay consistent.
+Regeneration may emit a hook for `/feature-flags/flagConfiguration`; prefer **`useTerrenoFeatureFlags`** / **`useFeatureFlags`** from `@terreno/syncdb/flags` so the OpenFeature domain, per-user refetch, and socket refresh stay consistent.
 
 ### 4. Use feature flags in the frontend
 
-**Recommended (OpenFeature):** add `@openfeature/react-sdk` to the app, wrap the tree (or the subtree that reads flags) in `<OpenFeatureProvider domain="feature-flags">`, and call `useTerrenoFeatureFlags(terrenoApi, {userId, socket})` once after auth so the OpenFeature client receives `GET /feature-flags/flagConfiguration`. Then use standard hooks such as `useBooleanFlagValue` / `useStringFlagValue` / `FeatureFlag`.
+Add `@openfeature/web-sdk` and `@openfeature/react-sdk` to the app (`catalog:` versions). Both
+hooks come from `@terreno/syncdb/flags`, fetch through the request client from
+`ApiClientProvider`, and refetch when the server pushes `featureFlagsChanged` on the syncdb
+socket.
 
-**Back-compat:** `useFeatureFlags(terrenoApi)` from `@terreno/rtk` still returns `{flags, getFlag, getVariant, isLoading, …}` with the same semantics as before; it uses `/flagConfiguration` under the hood. You do not need to call a generated RTK hook for `/flagConfiguration` directly.
+**Recommended (OpenFeature):** wrap the tree that reads flags in
+`<OpenFeatureProvider domain="feature-flags">` and call `useTerrenoFeatureFlags` once after
+auth. Pass your `syncDb` as `socket` when this component sits above `SyncDbProvider`. Then read
+values with `useBooleanFlagValue` / `useStringFlagValue` / `FeatureFlag`.
+
+```typescript
+import {OpenFeatureProvider} from "@openfeature/react-sdk";
+import {useTerrenoFeatureFlags} from "@terreno/syncdb/flags";
+import {syncDb} from "@/store/syncdb";
+
+const FlagsBridge: React.FC<{children: React.ReactNode; userId?: string}> = ({
+  children,
+  userId,
+}) => {
+  useTerrenoFeatureFlags({skip: !userId, socket: syncDb, userId});
+  return <OpenFeatureProvider domain="feature-flags">{children}</OpenFeatureProvider>;
+};
+```
 
 ```typescript
 import {useBooleanFlagValue} from "@openfeature/react-sdk";
-import {useTerrenoFeatureFlags, useSelectCurrentUserId} from "@terreno/rtk";
-import {terrenoApi} from "@/store/sdk";
 
 const GatedBanner: React.FC = () => {
-  const userId = useSelectCurrentUserId();
-  useTerrenoFeatureFlags(terrenoApi, {userId, skip: !userId});
   const showBanner = useBooleanFlagValue("new-ui", false);
   return showBanner ? <NewUI /> : null;
 };
 ```
 
+**Flat accessors:** `useFeatureFlags` returns `{flags, getFlag, getVariant, isLoading, error,
+refetch}`. Screens below the bridge can pass `socket: null` — they share the bridge's cached
+query, so its refetch updates them too.
+
 ```typescript
-import {useFeatureFlags} from "@terreno/rtk";
-import {terrenoApi} from "@/store/sdk";
+import {useFeatureFlags} from "@terreno/syncdb/flags";
 
-const LegacyStyle: React.FC = () => {
-  const {getFlag, isLoading} = useFeatureFlags(terrenoApi);
+const LegacyStyle: React.FC<{userId?: string}> = ({userId}) => {
+  const {getFlag, isLoading} = useFeatureFlags({skip: !userId, socket: null, userId});
 
   if (isLoading) {
     return <Spinner />;
   }
 
-  const showNewUI = getFlag("new-ui");
-
-  return showNewUI ? <NewUI /> : <OldUI />;
+  return getFlag("new-ui") ? <NewUI /> : <OldUI />;
 };
 ```
 
 ### 4b. Live updates (optional)
 
-To push flag changes to open clients without a refresh, pass **`liveUpdates`** when constructing `FeatureFlagsApp` (see `example-backend/src/server.ts`): Mongoose **`FeatureFlag.watch()`** drives a Socket.io broadcast. **MongoDB must run as a replica set** (a single-node replica set is enough); standalone instances cannot use change streams, and the plugin logs a warning if `watch()` fails.
+To push flag changes to open clients without a refresh, pass **`liveUpdates`** when constructing `FeatureFlagsApp` (see `example-backend/src/server.ts`): Mongoose **`FeatureFlag.watch()`** drives a Socket.io broadcast. Point `socketIoServer` at `() => realtimeApp.getIo()` so the push goes out on the socket the syncdb client already holds. **MongoDB must run as a replica set** (a single-node replica set is enough); standalone instances cannot use change streams, and the plugin logs a warning if `watch()` fails.
 
-On the client, pass the same Socket.io **client** into `useTerrenoFeatureFlags` / `useFeatureFlags` as `socket`; the hook listens for `featureFlagsChanged` (or `socketEventName`) and refetches `/flagConfiguration`. The event payload is only `{ key: string }` — the same flag keys are already returned to every authenticated user in `/flagConfiguration`, so this is not considered a new exposure.
+On the client there is nothing extra to wire: `useTerrenoFeatureFlags` listens for `featureFlagsChanged` (or `socketEventName`) through `syncDb.onSocketEvent` and refetches `/flagConfiguration`. The app opens no second socket. The event payload is only `{ key: string }` — the same flag keys are already returned to every authenticated user in `/flagConfiguration`, so this is not considered a new exposure.
 
 ### 5. Create flags via the admin panel
 
@@ -111,23 +128,31 @@ Navigate to the admin panel in your app. The "Feature Flags" card appears automa
 
 ## Migrating from `GET …/evaluate` (OpenFeature)
 
-Terreno's feature-flag stack uses **OpenFeature** (`@terreno/feature-flags` on the server, `@terreno/rtk` on the client). Use this checklist if you upgrade from a Terreno release that only documented `GET …/evaluate`.
+Terreno's feature-flag stack uses **OpenFeature** (`@terreno/feature-flags` on the server, `@terreno/syncdb/flags` on the client). Use this checklist if you upgrade from a Terreno release that only documented `GET …/evaluate`.
 
 ### Backend (`@terreno/feature-flags`)
 
 1. Keep **`FeatureFlagsApp`** registered as before; admin CRUD is unchanged.
 2. Prefer authenticated clients calling **`GET {basePath}/flagConfiguration`** — the JSON body matches OpenFeature's static configuration shape (for `TypedInMemoryProvider` on the client).
-3. **`GET {basePath}/evaluate`** still returns the legacy `Record<key, boolean | string | null>` map but is **deprecated** (`Deprecation: true`, `Sunset` header). Migrate direct HTTP or hand-written clients to `/flagConfiguration`, or rely on `@terreno/rtk` hooks below.
+3. **`GET {basePath}/evaluate`** still returns the legacy `Record<key, boolean | string | null>` map but is **deprecated** (`Deprecation: true`, `Sunset` header). Migrate direct HTTP or hand-written clients to `/flagConfiguration`, or rely on the `@terreno/syncdb/flags` hooks below.
 4. **`FeatureFlag`** documents gain optional **`defaultVariant`** (boolean: `"on"` / `"off"`; variant: a key from `variants`). Omitted values are filled on save. For existing databases, run a one-off backfill or reuse the pattern in `example-backend/src/scripts/seed-feature-flags.ts`.
 5. **Live updates (optional):** pass `liveUpdates: { socketIoServer: io | () => io }` to `FeatureFlagsApp`. MongoDB must run as a **replica set** (a single-node replica set is enough) so Mongoose change streams work.
 
-### Frontend (`@terreno/rtk` + OpenFeature)
-
-1. **`useFeatureFlags(terrenoApi, …)`** — no code changes required for the common case; it already uses `/flagConfiguration` and keeps `{ flags, getFlag, getVariant, isLoading, refetch }`.
-2. **OpenFeature React hooks** (`useBooleanFlagValue`, `useStringFlagValue`, `<FeatureFlag>`, …): add **`@openfeature/react-sdk`** and **`@openfeature/web-sdk`** to your app (align versions with `@terreno/rtk` **peerDependencies** and the root **`catalog`**).
-3. Wrap the UI that reads flags in **`<OpenFeatureProvider domain="feature-flags">`** (or the same `domain` you pass into the hook).
-4. After auth, call **`useTerrenoFeatureFlags(terrenoApi, { userId, skip, socket, … })`** once under your Redux `Provider` so OpenFeature is populated before hooks read flag values.
-5. **Regenerate the OpenAPI SDK** after the backend exposes the new route: `cd your-frontend && bun run sdk`. Prefer **`useTerrenoFeatureFlags` / `useFeatureFlags`** over calling a generated `flagConfiguration` hook directly, so domain, cache keys, and optional socket refetch stay consistent.
+### Frontend (`@terreno/syncdb/flags` + OpenFeature)
+
+1. Replace the Terreno 57 `useFeatureFlags(terrenoApi, options)` with
+   `useFeatureFlags(options)` from `@terreno/syncdb/flags`. The result shape is unchanged:
+   `{flags, getFlag, getVariant, isLoading, error, refetch}`. The legacy string `basePath`
+   argument is gone; pass `{basePath}`.
+2. Replace `useTerrenoFeatureFlags(terrenoApi, {socket, ...})` with
+   `useTerrenoFeatureFlags({socket: syncDb, ...})`. `socket` is now your `SyncDb` client, not a
+   Socket.io client, and defaults to the `SyncDbProvider` client.
+3. Drop `useSocketConnection` and `useRealtimeDebug`. Listen for other server events with
+   `useSocketEvent` from `@terreno/syncdb/react` (see
+   [WebSocket integration](./websocket-integration.md)).
+4. Keep `@openfeature/web-sdk` and `@openfeature/react-sdk` in the app (`catalog:` versions) and
+   wrap the UI that reads flags in `<OpenFeatureProvider domain="feature-flags">`.
+5. Mount the hooks under `ApiClientProvider`, or pass `client`.
 
 ### Further reading
 

package/src/docs/versioned/next/how-to/add-organizations.md

@@ -173,7 +173,8 @@ exactly one administered organization may omit it; Terreno infers that org.
 Operators and superadmins must select an org.
 
 Frontend admin hosts use `OrgContextProvider` + `OrgSwitcher`.
-`useAdminApi` adds the selected organization header automatically.
+`useAdminModelApi` and the built-in admin screens add the selected organization
+header automatically.
 
 Disabled organizations are excluded from `/orgs/mine` and cannot be selected as
 tenant context. Operators re-enable them from the organization directory UI or

package/src/docs/versioned/next/how-to/admin-custom-home.md

@@ -25,8 +25,14 @@ Built-in IDs include `modelStats`, `modelsGrid`, `scriptRunner`, `versionConfig`
 For an app-specific widget, implement `AdminHomeWidgetProps` and register it:
 
 ```tsx
-<AdminProvider widgets={{home: {operationsSummary: OperationsSummary}}} api={api}>
-  <AdminHome api={api} />
+<AdminProvider
+  apiBase="/admin"
+  apiOrigin={baseUrl}
+  getAuthHeaders={getAdminAuthHeaders}
+  routeBase="/admin"
+  widgets={{home: {operationsSummary: OperationsSummary}}}
+>
+  <AdminHome />
 </AdminProvider>
 ```
 

package/src/docs/versioned/next/how-to/admin-custom-widget.md

@@ -33,7 +33,6 @@ const RichTextWidget: React.FC<AdminFieldWidgetProps> = ({
 
 ```tsx
 <AdminProvider
-  api={api}
   apiBase="/admin"
   routeBase="/admin"
   widgets={{fields: {"rich-text": RichTextWidget}}}

package/src/docs/versioned/next/how-to/agent-ui-asks.md

@@ -248,9 +248,9 @@ use uploads, or lower the per-file cap with `asks: {maxFileSizeBytes: 5_000_000}
    <GPTChat resolveAskFiles={resolveAskFiles} {...chatProps} />;
    ```
 
-   `postFilesUpload` is an RTK Query mutation in `example-frontend/store/sdk.ts` whose body is a
-   `FormData` with a `file` part; the base query sends it with the session token. The generated
-   SDK has no file endpoints, because `/files/*` exists only on a server with a bucket.
+   `usePostFilesUploadMutation` is a generated hook in `example-frontend/store/apiSdk.ts` whose
+   body is a `FormData` with a `file` part; the request client sends it with the session token.
+   `/files/*` exists only on a server with a bucket.
    `createAskFileUploader` (in `gptAsks.ts`) returns `undefined` on 404, the upload's `id` and
    `size` on success, and throws with the server's detail otherwise (such as 401 when the session
    has ended), so the ask stays open. See `example-frontend/app/(tabs)/ai.tsx`.
@@ -297,9 +297,9 @@ answer as two rows, and ratings are sent by message index.
 
 A turn can stream only `{done}`, for example when the server cancels a second ask because one is
 already pending. Reload the conversation with `GET /gpt/histories/:id` when a turn streamed nothing
-visible, or when `done.pendingAsk` names an ask the stream did not send. The `@terreno/rtk` base
-query returns the `data` of single-document responses, so an RTK query for that route resolves to
-the history itself, not `{data}` (see [emptyApi](../reference/legacy/rtk.md#emptyapi--emptysplitapi)).
+visible, or when `done.pendingAsk` names an ask the stream did not send. The `@terreno/syncdb/api`
+request client unwraps the `data` of single-document responses, so `apiClient.request` for that
+route resolves to the history itself, not `{data}` (see [API client](../reference/syncdb.md#api-client)).
 
 Refetch the history list after a turn that streams ask events or reloads the conversation. The
 example app reopens a conversation from the list's cached rows, which still hold the pending ask.

package/src/docs/versioned/next/how-to/build-admin-screens.md

@@ -25,7 +25,6 @@ Embedded app (`example-frontend`):
 const syncConflicts = useConflicts();
 
 <AdminProvider
-  api={api}
   apiBase="/admin"
   apiOrigin={baseUrl}
   getAuthHeaders={getAdminAuthHeaders}
@@ -35,7 +34,6 @@ const syncConflicts = useConflicts();
   widgets={{screens: {"sync-lab": SyncLabScreen}}}
 >
   <AdminShellLayout
-    api={api}
     apiBase="/admin"
     configurationPath="/admin/configuration"
     rolesPath="/roles"
@@ -53,8 +51,8 @@ store name and `windowCollections` set; do not mix admin rows into the owner/ten
 product store. Start that client after `canOpenAdminPage` succeeds, block the admin
 shell until `start()` resolves, and call `stop()` when the admin layout unmounts.
 
-Gate entry with `canOpenAdminPage` from `@terreno/rtk` (`admin:access`). Do not
-rely on `user.admin` alone when RBAC is on. Import `baseUrl` from `@terreno/rtk`
+Gate entry with `canOpenAdminPage` from `@terreno/syncdb/app` (`admin:access`). Do not
+rely on `user.admin` alone when RBAC is on. Import `baseUrl` from `@terreno/syncdb/config`
 and pass it as `apiOrigin` so admin RPC (`GET /admin/config`, `/rbac/roles`, …)
 hits the API instead of the Expo web origin.
 
@@ -123,11 +121,15 @@ for those paths. Otherwise `[model]/[id]` treats the id as a generic document.
 
 ## 5. Fetch data the admin way
 
+- Every admin request goes through the `AdminProvider` fetch client. Admin
+  components take no `api` prop.
 - String-`_id` collections configured with `adminBroadcast` use windowed syncdb
-  when the host passes `syncDb` plus fetch auth.
-- ObjectId model CRUD and API-only hosts keep `useAdminApi`.
-- Bulk patch remains server-side: native admin fetch for windowed hosts, RTK fallback otherwise.
-- Admin RPC uses the host-bound native fetch client. Do not add axios.
+  when the host passes `syncDb`.
+- ObjectId and API-only models use fetch CRUD. Custom screens call
+  `useAdminModelApi(routePath, modelName)` for list/read/create/update/delete.
+- Bulk patch stays server-side at `{routePath}/bulk-patch` for every model.
+- Custom admin RPC uses `useAdminRpc` + `useAdminRpcQuery` / `useAdminRpcMutation`.
+  Do not add axios or a second request client.
 
 ## 6. Sidebar and grouping
 

package/src/docs/versioned/next/how-to/build-for-web.md

@@ -26,7 +26,7 @@ bun expo export --platform web
 
 ### Alternative: `app.json` `extra.BASE_URL`
 
-`@terreno/rtk` resolves the API base from `expo-constants` `extra.BASE_URL` and `EXPO_PUBLIC_API_URL` (see `rtk/src/constants.ts` `resolveBaseUrls`). Priority in **production** builds:
+`@terreno/syncdb/config` resolves the API base from `expo-constants` `extra.BASE_URL` and `EXPO_PUBLIC_API_URL` (see `syncdb/src/config/resolveBaseUrls.ts`). Priority in **production** builds:
 
 1. `EXPO_PUBLIC_API_URL` environment variable (set before export)
 2. `extra.BASE_URL` in app config (when env var is unset)

package/src/docs/versioned/next/how-to/call-external-apis.md

@@ -10,7 +10,7 @@ How to talk to third-party HTTP APIs (payment processors, health integrations, m
 | Calling an external service through its own SDK (Twilio, Google APIs, Stripe) | `withApiErrorHandling` around the SDK calls — the SDK owns transport, you standardize failures |
 | Logging or classifying a caught error from any external call | `normalizeApiError` |
 | Surfacing an external failure to your API's consumers from a route handler | `withApiErrorHandling` with `rethrowAs: "apiError"` |
-| Making internal requests to your own `@terreno/api` backend | None of these — use `@terreno/rtk` on the frontend or direct function calls on the backend |
+| Making internal requests to your own `@terreno/api` backend | None of these — use the generated `store/apiSdk.ts` hooks (`@terreno/syncdb/api` request client) or syncdb collection hooks on the frontend, or direct function calls on the backend |
 
 **Rule of thumb:** any file that would otherwise contain `axios.create(...)` plus a token variable plus a `try/catch → axios.isAxiosError → log → throw` block should use these utilities instead.
 
@@ -92,7 +92,7 @@ Note the hook's output classification also feeds the client's retry decision —
 
 ## When not to use this
 
-- **Your own backend's routes** — use the generated `@terreno/rtk` SDK (frontend) or call the function directly (backend).
+- **Your own backend's routes** — use syncdb collection hooks or the generated `store/apiSdk.ts` hooks (frontend) or call the function directly (backend).
 - **SDK-managed transport** (Twilio, googleapis) — don't fight the SDK's HTTP layer; adopt only `normalizeApiError`/`withApiErrorHandling` for consistent failure handling.
 - **Webhook notifiers** — `sendToSlack`/`sendToGoogleChat`/`sendToZoom` post to a fixed webhook. Slack channel creation, invites, and bot posts use `createSlackPrivateChannel`, `inviteSlackUsersToChannel`, and `postSlackMessage` with `SLACK_BOT_TOKEN`. See [Webhooks & Notifications](../reference/api.md#webhooks--notifications).
 

package/src/docs/versioned/next/how-to/circleci.md

@@ -47,6 +47,13 @@ list pipelines on the slug above.
 | `.circleci/config.yml` | Setup workflow + `path-filtering` (this is the live config) |
 | `.circleci/continue-config.yml` | Real jobs/workflows gated by those params |
 
+## Bun version is pinned
+
+`install_bun_and_deps` pins Bun with `node/install-bun` `version`. Bun 1.4.4 reports
+lower line coverage than 1.4.2 for the same tests, which fails the 95% package
+coverage gates. Bump the pin together with the local toolchain and re-run
+`bun run test:coverage` in each package first.
+
 ## Bun install is uncached
 
 `install_bun_and_deps` runs `bun install --frozen-lockfile` with
@@ -87,8 +94,8 @@ The example-backend Docker job runs only when its image recipe changes
 (`Dockerfile`, `.dockerignore`, package manifests, or `bun.lock`). API/source
 changes are covered by preview CD builds and do not start a duplicate image job.
 
-UI, RTK, and admin-frontend changes do **not** start `example-backend-ci`.
-Those packages are covered by `ui-ci` / `rtk-ci` / `packages-ci` plus e2e and
+UI, syncdb, and admin-frontend changes do **not** start `example-backend-ci`.
+Those packages are covered by `ui-ci` / `syncdb-ci` / `packages-ci` plus e2e and
 admin-spa. `new-file-coverage` starts on package `src/` (and example app
 runtime paths including `example-frontend/components/`), not on every `*.ts`
 file in the repo (Playwright specs no longer compile the world). Package CI
@@ -169,13 +176,13 @@ non-PR branch builds.
 | Path (examples) | Parameter | PR job | `master` job |
 | --- | --- | --- | --- |
 | `demo/**`, `ui/**` | `run-deploy-demo` | `deploy-demo-preview` | `deploy-demo` |
-| `example-frontend/**`, `admin-frontend/**`, `rtk/**`, `ui/**`, `ai/**`, `blocks/**`, `syncdb/**`, `bun.lock` | `run-deploy-frontend` | `deploy-frontend-preview` | `deploy-frontend` |
+| `example-frontend/**`, `admin-frontend/**`, `ui/**`, `ai/**`, `blocks/**`, `syncdb/**`, `bun.lock` | `run-deploy-frontend` | `deploy-frontend-preview` | `deploy-frontend` |
 | `docs/**`, `website/**` | `run-deploy-docs` | `deploy-docs-preview` | `deploy-docs` |
 | `example-backend/**`, `api/**`, `comms/**`, `jobs/**`, `admin-spa/**`, `feature-flags/**`, `announcements/**`, plus every frontend path above | `run-cd-backend` | `gcp-cd-preview` | `gcp-cd-prod` |
 | `terraform/**`, `infra/**` | `run-cd-terraform` | `gcp-cd-preview` | `gcp-cd-prod` |
 | `mcp-server/**`, `ui/**` | `run-cd-mcp` | _(none)_ | `gcp-cd-prod` (runs `mcp-server` `test:ci` first) |
 
-The backend image bundles the admin SPA (ui, rtk, admin-frontend, syncdb), so
+The backend image bundles the admin SPA (ui, admin-frontend, syncdb), so
 those paths redeploy the backend too. Every frontend PR preview therefore gets
 an isolated `pr-N` backend: `deploy-frontend-preview` always points
 `EXPO_PUBLIC_API_URL` at it (the prod backend rejects preview CORS) and waits
@@ -283,7 +290,7 @@ ambient OIDC token for GCP impersonation.
 Branch protection must require the CircleCI job names below. Remove disabled
 GitHub check names or pull requests will wait for checks that can no longer run.
 
-Dedicated package jobs (`api-ci`, `ai-ci`, `blocks-ci`, `rtk-ci`, `ui-ci`, `syncdb-ci`,
+Dedicated package jobs (`api-ci`, `ai-ci`, `blocks-ci`, `ui-ci`, `syncdb-ci`,
 `comms-ci`, `mcp-server-ci`, `admin-spa-ci`) run `bun run test:coverage`
 (`scripts/check-coverage.ts`, 95% functions and lines). Isolated `syncdb` tests
 are included by that script. Published packages without a dedicated workflow
@@ -305,7 +312,6 @@ the same commands through the parameterized `packages-ci` job, gated by
 | Admin frontend lint, compile, coverage | `packages-ci` (`admin-frontend`) |
 | Run all tests (AI CI) | `ai-ci` |
 | Lint, compile, and test blocks | `blocks-ci` |
-| RTK Lint and Build | `rtk-ci` |
 | Syncdb Lint, Build, and Tests | `syncdb-ci` |
 | UI Lint, Build, Types, and Tests + demo typecheck | `ui-ci` |
 | Demo Lint and TypeScript Check | `ui-demo-ci` (demo-only PRs) |