@nocobase/app-skills 0.1.0-beta.39 → 0.1.0-beta.41

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nocobase/app-skills",
3
- "version": "0.1.0-beta.39",
3
+ "version": "0.1.0-beta.41",
4
4
  "description": "Agent Skills for developing, upgrading and deploying NocoBase applications.",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -18,7 +18,7 @@
18
18
  "devDependencies": {
19
19
  "@playwright/test": "^1.62.1",
20
20
  "prettier": "^3.9.6",
21
- "@nocobase/dev-config": "0.1.0-beta.23"
21
+ "@nocobase/dev-config": "0.1.0-beta.24"
22
22
  },
23
23
  "peerDependencies": {
24
24
  "@playwright/test": "^1.62.1",
@@ -41,16 +41,17 @@ Build the feature in the application. Do not run a plugin generator, create a `p
41
41
 
42
42
  NocoBase packages may publish Skills under `.agents/skills/`. Current application templates run `pnpm nocobase skills sync` automatically through `postinstall`; run it manually if install scripts were disabled or that directory is missing or stale. Confirm that the package is a direct `@nocobase/*` dependency or a registered plugin before relying on its Skill. The common capability mappings are:
43
43
 
44
- | The requirement sounds like | Read the Skill for |
45
- | --------------------------------------------------------- | ------------------------------------- |
46
- | Email, IM, or in-app messages | `@nocobase/app-plugin-notification` |
47
- | Roles, permissions, per-user or per-record access | `@nocobase/app-plugin-authorization` |
48
- | Sign-in, registration, sessions | `@nocobase/app-plugin-authentication` |
49
- | File upload and metadata through Repository | `@nocobase/app-plugin-file` |
50
- | File storage, disk configuration, or custom drivers | `@nocobase/drive` |
51
- | Translated text and language switching | `@nocobase/app-plugin-i18n` |
52
- | User administration and application-owned role assignment | `@nocobase/app-plugin-users` |
53
- | Reading or writing data, schema changes, migrations | `@nocobase/db` |
44
+ | The requirement sounds like | Read the Skill for |
45
+ | -------------------------------------------------------------- | ------------------------------------------ |
46
+ | Email, IM, or in-app messages | `@nocobase/app-plugin-notification` |
47
+ | Roles, permissions, per-user or per-record access | `@nocobase/app-plugin-authorization` |
48
+ | Sign-in, registration, sessions | `@nocobase/app-plugin-authentication` |
49
+ | File upload and metadata through Repository | `@nocobase/app-plugin-file` |
50
+ | File storage, disk configuration, or custom drivers | `@nocobase/drive` |
51
+ | Translated text and language switching | `@nocobase/app-plugin-i18n` |
52
+ | User administration and application-owned role assignment | `@nocobase/app-plugin-users` |
53
+ | Live updates, snapshot recovery and replacing business polling | `@nocobase/realtime` (`nocobase-realtime`) |
54
+ | Reading or writing data, schema changes, migrations | `@nocobase/db` |
54
55
 
55
56
  Read the relevant Skill before writing the feature, but treat this table as a map rather than an installed-package list. Implementing a permission system, a notification sender, or a scheduler by hand when a registered plugin provides one is the most expensive mistake available here.
56
57
 
@@ -194,7 +195,7 @@ These cause real damage and appear in every reference:
194
195
  - **Let the owning page supply `PageContainer`.** One per page; inline child pages and tabs use the parent's, covering child pages add their own, overlays use their own container. See [section 2 of pages and routes](references/frontend/references/page.md#2-the-page-component).
195
196
  - **Visual consistency is application-wide.** Restyling only your part is a defect. Change the design tokens if a change is needed.
196
197
  - **Route paths never include the deployment base path.** The runtime restores it.
197
- - **Route navigation creates sidebar entries.** Declare `navigation` in `client/routes.ts`. Refine resources create no menu entries and, with no data provider registered, load nothing; pages load data with `useApiClient` (see [calling the API](references/frontend/references/api.md)).
198
+ - **Route navigation creates sidebar entries.** Declare `navigation` in `client/routes.ts`; pages load data with `useApiClient` (see [calling the API](references/frontend/references/api.md)).
198
199
  - **Reach for the built-in mechanism first.** Changing framework structure is allowed when nothing else fits — comment it and record it in `.agents/rules/`.
199
200
  - **Tests live in `tests/`,** never beside the source; browser tests against a running application go in `tests/playwright/`.
200
201
  - **Remove direct NocoBase packages with `package remove` after reviewing their usage.** Do not hand-delete only the manifest entry or leave synchronized Skills and plugin registrations behind.
@@ -51,7 +51,7 @@ Configure storage in `server/config/drive.ts`, with serializable overrides in `c
51
51
 
52
52
  `client/routing/`, `client/layouts/`, `client/theme/`, the server entry points, the `package.json` scripts that call `nocobase`, and the tsconfigs are the scaffolding the template provides. It is still this application's own source — it shipped to the user and they may change it — but it is the part the template evolves, so an edit there is what a future upgrade has to reconcile. [Customizing the shell](frontend/references/shell.md) lists the shell behaviors to keep.
53
53
 
54
- Prefer the mechanism the system already provides. Declare a page in `client/routes.ts` and add `navigation` when it needs a menu entry. Refine resources add no menu entries and, with no data provider registered, load nothing; pages load data through `useApiClient`. A page uses `authz` to restrict access; a plugin page is customized through an option or an override. Before editing the shell to add a menu, check the route and its `navigation` declaration.
54
+ Prefer the mechanism the system already provides. Declare a page in `client/routes.ts` and add `navigation` when it needs a menu entry; pages load data through `useApiClient`. A page uses `authz` to restrict access; a plugin page is customized through an option or an override. Before editing the shell to add a menu, check the route and its `navigation` declaration.
55
55
 
56
56
  When the built-in mechanism genuinely cannot express what is being asked, changing this structure is a legitimate answer — not a last resort to apologize for. Do it deliberately, and leave the next agent enough to work with:
57
57
 
@@ -59,7 +59,7 @@ An external connection's metadata — titles, descriptions and relations its sch
59
59
 
60
60
  ## A command line of the application's own
61
61
 
62
- Besides `pnpm nocobase`, an application may give the people and agents who use it a CLI of its own, such as `acme`: `@nocobase/app-cli-client` under the application's name, which signs in to the running application and runs the business commands its API publishes (`GET /api/cli/manifest`). No template declares one. To add it, put `"nocobase": { "cli": { "bin": "<command>", "displayName": "<Name>" } }` in `package.json` (the fields are in `@nocobase/app-cli`'s README: the state directory, the environment prefix, the device sign-in client id, the Skill directories it ships to runners, …) and add `@nocobase/app-cli-client` to `devDependencies`. `pnpm nocobase cli link` makes it a command in `node_modules/.bin`; `pnpm nocobase cli build` packs it into standalone tarballs that bundle Node.js, one per platform (`--targets`), in `storage/runners/dist`, which the agents plugin serves to its install script and to runners, and `cli build --runner` packs the runner (`nocobase-runner`, from `@nocobase/agent-runner`) beside it. `--universal` packs one more tarball, `<product>-v<version>-universal.tar.gz`, which carries no Node.js and runs on the machine's own Node.js 24 or newer; alone, without `--targets`, it packs only that one and downloads no Node. It is served to every platform without a tarball of its own, and the install script checks for Node.js 24 before installing it. An application can also serve no tarball at all and name the exact npm versions of its CLI package and `@nocobase/agent-runner` instead (`agents.dist.npm`), which machines install with their own Node.js 24 and npm; the agents plugin's Skill covers both. In production a CI job builds them and mounts them into that storage; do not commit them or bake them into an image.
62
+ Besides `pnpm nocobase`, an application may give the people and agents who use it a CLI of its own, such as `acme`: `@nocobase/app-cli-client` under the application's name, which signs in to the running application and runs the business commands its API publishes (`GET /api/cli/manifest`). The Examples template declares `nocobase-examples` for its Runner chat demonstration; Default leaves this optional. To add it, put `"nocobase": { "cli": { "bin": "<command>", "displayName": "<Name>" } }` in `package.json` (the fields are in `@nocobase/app-cli`'s README: the state directory, the environment prefix, the device sign-in client id, the Skill directories it ships to runners, …) and add `@nocobase/app-cli-client` to `devDependencies`. `pnpm nocobase cli link` makes it a command in `node_modules/.bin`; `pnpm nocobase cli build` packs it into standalone tarballs that bundle Node.js, one per platform (`--targets`), in `storage/runners/dist`, which the agents plugin serves to its install script and to runners, and `cli build --runner` packs the runner (`nocobase-runner`, from `@nocobase/agent-runner`) beside it. `--universal` packs one more tarball, `<product>-v<version>-universal.tar.gz`, which carries no Node.js and runs on the machine's own Node.js 24 or newer; alone, without `--targets`, it packs only that one and downloads no Node. It is served to every platform without a tarball of its own, and the install script checks for Node.js 24 before installing it. An application can also serve no tarball at all and name the exact npm versions of its CLI package and `@nocobase/agent-runner` instead (`agents.dist.npm`), which machines install with their own Node.js 24 and npm; the agents plugin's Skill covers both. In production a CI job builds them and mounts them into that storage; do not commit them or bake them into an image.
63
63
 
64
64
  ## The application's own commands
65
65
 
@@ -230,9 +230,11 @@ export async function uploadProjectAttachment(
230
230
 
231
231
  ## Loading data in a component
232
232
 
233
- Data reloads when the user acts (a search, "Retry", a refresh button) or after the page's own writes. Pushing server changes to open pages needs server-side events as well; `@nocobase/app-client` exports `realtimeClientToken`, and the one realtime feature the template ships, the in-app inbox, is documented in the `nocobase-app-plugin-notification-in-app` Skill. Read it before building live updates.
233
+ For live updates, read the installed `nocobase-realtime` Skill in `.agents/skills/` for server authorization, snapshot recovery, retries, distributed delivery and polling decisions.
234
234
 
235
- There is no shared data-loading hook; write it directly in the component: `useApiClient()` + `useEffect` + `AbortController`. Do not reach for the data hooks of the installed Refine packages (`useList`, `useTable`, `useForm` from `@refinedev/*`) or for TanStack Query: the application registers no Refine data provider, so those hooks have nothing to call, and one loading pattern across pages keeps states and errors consistent. The application shell mounts Refine and `client/service-provider.ts` can register Refine resources, which only describe records to code that opts into Refine; without a data provider they load nothing, and they never add menu entries. Add a data provider only when the user asks to adopt Refine's data hooks across the application. The component below loads a project by id and displays it, covering loading, retry after failure, record not found, no permission and empty values (`client/pages/projects/project-summary.tsx`):
235
+ Data reloads when the user acts (a search, "Retry", a refresh button) or after the page's own writes. For live updates, declare the server Topic during provider boot and reuse the host client through `useRealtimeTopic` or `useRealtimeRefresh` from `@nocobase/app-client`. A watch's `onReady` runs after that Topic is acknowledged, including reconnects; `onOpen` only describes the transport. Refresh authoritative API data on readiness because disconnected events are not replayed. Use `enabled: false` for inactive pages, return the refresh promise for burst coalescing and one in-flight follow-up, and use `refreshRealtimeQueries(queryClient, filters, signal)` for TanStack Query snapshots. It matches exact keys, prefixes and predicates, waits for pre-event reads (including initial loading), and follows them with a fresh read without repeatedly cancelling slow requests. Bare `invalidateQueries` with `cancelRefetch: false` can reuse a pre-event response and lose the change. For lower-level code, resolve `realtimeClientToken` and call `watch(topic, { onEvent, onReady, onError })`; close its handle on cleanup. Personal inbox usage is documented in the `nocobase-app-plugin-notification-in-app` Skill.
236
+
237
+ There is no shared data-loading hook; write it directly in the component: `useApiClient()` + `useEffect` + `AbortController`. Do not reach for TanStack Query in a page: one loading pattern across pages keeps states and errors consistent. The component below loads a project by id and displays it, covering loading, retry after failure, record not found, no permission and empty values (`client/pages/projects/project-summary.tsx`):
236
238
 
237
239
  ```tsx
238
240
  // client/pages/projects/project-summary.tsx (excerpt; the complete file is in example/project-summary.md)
@@ -278,7 +278,7 @@ Write `navigation` on the route. The application sidebar reads its menu entries
278
278
  - Pages that should not appear in the menu (details, tab content and so on) have no `navigation`. When such a page is open, the menu highlights the nearest ancestor that has a menu entry.
279
279
  - **A path with a parameter (`:projectId`) cannot have `navigation`**; registration raises an error, because a menu entry must point to a fixed URL (wildcards are rejected on every route, [section 1](#1-declare-the-route)).
280
280
  - Navigation group: write only `name`, `navigation` and `children`, without `componentLoader`. For groups and clickable parents, see [`child-routes.md`](child-routes.md).
281
- - Do not change the shell (`client/layouts/`) or the ServiceProvider to add a menu entry, and do not add a Refine resource for a menu. Refine resources produce no menu entries (see ["Loading data in a component" in `api.md`](api.md#loading-data-in-a-component) for what they are for); the home page entry is declared in the routes as well.
281
+ - Do not change the shell (`client/layouts/`) or the ServiceProvider to add a menu entry; the home page entry is declared in the routes as well.
282
282
  - A new page with a menu entry usually touches four places: `client/routes.ts`, the page component, `client/locales/` and, for an App page that requires sign-in, the page grant list in `tests/logic/client-routes.test.ts` ([section 12](#12-update-the-route-test)).
283
283
 
284
284
  ### A count beside an entry
@@ -403,7 +403,7 @@ export function ExportProjectsButton({
403
403
  - Use it for page permissions too, for example for an entry on the home page that points to a page: `useCan({ resource: { type: 'page', id: 'projects' }, action: 'access' })`. A route's `authz` uses the same `{ resource: { type, id }, action }`.
404
404
  - **`useCan` answers "does this user have this feature", not "can this record be acted on"**. For actions that depend on record state or data scope, the server returns the actions available for each record in the list or detail response, and the UI shows them accordingly; the endpoint checks again when it executes.
405
405
  - Hide actions the user has no permission for; disable actions that are temporarily unavailable and explain why in a tooltip (guideline I7).
406
- - In a component, get the authorization client with `useAuthorizationClient()`; outside React, resolve `authorizationClientToken` from the application container and call `client.can({ resource, action })`. When state you maintain yourself must reload after permissions change, use `useAuthorizationRevision()`. Do not use Refine's permission configuration or a global authorization client, and do not store permission results in module-level variables (they linger after switching accounts).
406
+ - In a component, get the authorization client with `useAuthorizationClient()`; outside React, resolve `authorizationClientToken` from the application container and call `client.can({ resource, action })`. When state you maintain yourself must reload after permissions change, use `useAuthorizationRevision()`. Do not use a global authorization client, and do not store permission results in module-level variables (they linger after switching accounts).
407
407
  - **Hiding something in the UI does not replace endpoint authorization.**
408
408
  - When the business has different job responsibilities, data scopes or field permissions, read the `nocobase-app-plugin-authorization` Skill first, then design the pages, business actions and record scopes.
409
409
 
@@ -96,6 +96,8 @@ diff -rq "$WORK/$BASE" "$WORK/$TARGET"
96
96
 
97
97
  When the upgrade changes application migrations or registered plugins that supply migrations, read [database upgrades](references/database-upgrades.md) during planning, before starting the target application. Review the affected packages' upgrade notes as well as the template diff: a dependency update can change database behavior without adding a migration file to the application. Include any documented checksum correction, data prerequisite, and irreversible migration in the upgrade and recovery plan. A Git branch protects source, not the database.
98
98
 
99
+ When BASE → TARGET changes Realtime contracts, read [Realtime upgrades](references/realtime-upgrade.md) during planning and include application-owned consumers, custom plugins, workers and transport/test adapters in step 5. Topic authorization, ignored publication promises and recovery gaps can survive type checking; use the actual package contracts and project usage to decide which migration steps apply.
100
+
99
101
  Then ask the project which of those files it has also touched:
100
102
 
101
103
  ```bash
@@ -159,6 +161,8 @@ pnpm typecheck && pnpm test && pnpm lint && pnpm build
159
161
 
160
162
  `typecheck` is doing real work here — it catches the broken import a removal left behind. Before starting the application against retained data, complete the applicable [database upgrade checks](references/database-upgrades.md); startup may apply migrations automatically. Then run the application and check what the delta touched: sign-in, the user's pages, navigation, locale switching, any new migration. Passing commands are not evidence the application still behaves. For a theme or shell change, also complete the [theme upgrade checks](references/theme-upgrade.md); token changes alone do not verify the application-owned consumers.
161
163
 
164
+ For a Realtime contract change, complete the applicable [Realtime acceptance checks](references/realtime-upgrade.md#verify-the-migrated-application), including access denial, reconnect catch-up and publication failure; a connected socket alone is insufficient evidence.
165
+
162
166
  Report the range merged, how each contested file was decided, any manual actions and their validation, and how to roll back.
163
167
 
164
168
  ## Crossing several releases
@@ -170,7 +170,7 @@ Legacy application-owned guidance, when present
170
170
 
171
171
  An application from before `@nocobase/app-cli` took over the whole command line depends on `@nocobase/nb3-cli` and, usually, `@nocobase/app-tools`. Neither is published any more, so the upgrade has to move to the new layout in one step; there is no compatibility period.
172
172
 
173
- 1. In `package.json`, remove `@nocobase/nb3-cli` and `@nocobase/app-tools`, keep `@nocobase/app-cli` in `dependencies` at the target template's range, and add the development tools it expects the application to provide to `devDependencies` — `typescript`, `tsx`, `vite`, `prettier`, `tar`, `@refinedev/cli`, `tsc-alias` and `@nocobase/dev-config`, taking the target template's ranges.
173
+ 1. In `package.json`, remove `@nocobase/nb3-cli` and `@nocobase/app-tools`, keep `@nocobase/app-cli` in `dependencies` at the target template's range, and add the development tools it expects the application to provide to `devDependencies` — `typescript`, `tsx`, `vite`, `prettier`, `tar`, `tsc-alias` and `@nocobase/dev-config`, taking the target template's ranges.
174
174
  2. Replace `scripts` with the target template's: `postinstall`, `dev`, `build` and `start` run `nocobase …`, and the quality scripts stay. Delete the command aliases (`config:*`, `db:*`, `migrate`, `seed`, `collections:generate`, `plugin:*`, `package:remove`, `skills:sync`, `upload`, `deploy`, `server:deps:*`, `nocobase`); each is now `pnpm nocobase <topic> <command>`. Keep scripts the user added that are not aliases, and ask before dropping one they redefined.
175
175
  3. If the application published to a Hub (it had `upload` and `deploy`), those commands have no replacement; see [Hub publishing](#hub-publishing).
176
176
  4. Delete `scripts/dev.mjs`, `scripts/build.mjs`, `scripts/start.mjs` and `scripts/server-deps.mjs`, and `cli/index.ts`. Compare any locally modified script first and move application-specific behavior into a plugin build or dev hook.
@@ -221,6 +221,18 @@ The release that stops shipping `DataTable` and `DatePicker` shows their files a
221
221
  1. Search the application for imports of each file and primitive and of each package before removing any of them, as [step 5](../SKILL.md#5-check-what-the-diff-cannot-show) describes. A file something still imports stays as application-owned code, together with the primitives and packages it needs; nothing about it has to change. Remove only what nothing imports.
222
222
  2. Keep the `dataTable` and `datePicker` keys in the locale files; the target template keeps them.
223
223
 
224
+ ## Refine removed from the client runtime
225
+
226
+ The release in which `@nocobase/app-client` 4 drops Refine removes `app.refine`, `app.refineConfig`, `runWithProviderContext`, `runWithProviderContextAsync` and the `AppClientRefine*` types, `@nocobase/i18n/client` drops `createRefineI18nProvider` and its types, and `@nocobase/app-plugin-repository-example` drops its `./client/providers` export. The application shell no longer mounts `<Refine>`; `AppClientProviders` creates the TanStack Query cache Refine used to create, in the same place, so pages and plugins that call `useQuery` or `useQueryClient()` keep working without a provider of their own. `nocobase build` runs `vite build` for the client where it ran `refine build`. Every application generated before this release carries a call the new types reject, so `pnpm typecheck`, and with it `pnpm build`, fails until it is removed.
227
+
228
+ Make these changes together, before the [Finish step](../SKILL.md#8-finish) installs dependencies:
229
+
230
+ 1. In `client/service-provider.ts`, delete `this.app.refine.setOptions({ title: { text: title } })`; the `document.title` lines beside it are what set the title and stay. An application from the Examples template also deletes the `this.app.refine.addResources([...])` call. `grep -rn "app\.refine\|refineConfig\|AppClientRefine\|runWithProviderContext\|RefineI18nProvider\|repository-example/client/providers" client/ tests/` lists any other call: a resource, option or provider set this way was never read by anything but Refine, so the call goes without a replacement. A test asserting `app.refineConfig.options?.title` asserts `document.title` instead, as the target's `tests/components/app-title.test.tsx` does.
231
+ 2. In `package.json`, remove `@refinedev/cli`, `@refinedev/core`, `@refinedev/react-hook-form`, `@refinedev/react-router` and `@refinedev/react-table` from `devDependencies`, and take the target's range for `@tanstack/react-query`. Remove `<Refine>` from any test fixture that wraps a component in it, such as `tests/fixtures/theme-tokens.tsx`.
232
+ 3. Search for imports from `@refinedev/` in `client/` before removing the packages. An application that adopted Refine's data hooks with a data provider of its own keeps those packages and mounts `<Refine>` itself in an `application`-layer entry of `client/react-providers.ts`, passing what the old shell passed: its data provider, `routerProvider` from `@refinedev/react-router`, and `options={{ syncWithLocation: true, disableTelemetry: true }}`. Refine's data hooks call TanStack Query's hooks, which read the nearest `QueryClientProvider`, so when a page calls them they use the cache around the routes, as they did before. Refine's own `authProvider` invalidates the cache Refine creates for itself, which pages do not read. Resolve a single copy of `@tanstack/react-query`, since the hooks of a second copy read another context and find no cache. An application that relied on Refine's translations also passes an `i18nProvider` of its own, because `createRefineI18nProvider` is no longer exported from `@nocobase/i18n/client`.
233
+
234
+ After the Finish step, run `pnpm typecheck`, `pnpm test` and `pnpm build`, then open a page that loads data and, when the application has one, the inbox.
235
+
224
236
  ## Hub publishing
225
237
 
226
238
  NocoBase Hub is discontinued, and with it `@nocobase/hub-cli` and the `pnpm nocobase hub` commands. An application that depends on `@nocobase/hub-cli`, sets `"nocobase": { "cli": { "publishing": true } }`, or runs `release upload`, `release deploy`, `hub upload` or `hub deploy` in CI or scripts published to a Hub. An application with none of these needs none of the steps below.
@@ -0,0 +1,61 @@
1
+ # Realtime upgrades
2
+
3
+ ## Decide which changes apply
4
+
5
+ Use this reference when BASE → TARGET changes the Realtime contracts used by the application or its plugins. The declared-topic contract was introduced on the `@nocobase/app-server` 3.0.0 prerelease line: undeclared topics are rejected, server publication and subscription authorization are asynchronous, and publication returns an event receipt. Check the actual BASE and TARGET declarations and release notes; the application may already have adopted these contracts. Do not infer compatibility from the template version or require every `@nocobase/*` package to share the same major version.
6
+
7
+ Resolve the compatible package set from the target template, including `@nocobase/app-server`, `@nocobase/app-client`, `@nocobase/realtime`, the WebSocket adapter and affected plugins. Before installation, inspect `skills/nocobase-realtime/SKILL.md` and its references in the exact target `@nocobase/realtime` tarball, together with its README and `docs/distributed.md`. After installation and `pnpm nocobase skills sync`, use `.agents/skills/nocobase-realtime/SKILL.md` when available. A currently installed Skill can describe BASE; do not treat it as the authority for TARGET or edit synchronized copies. The target declarations govern exact signatures and options.
8
+
9
+ Apply only the differences the application still needs. A patch that fixes refresh internals without changing a consumed contract needs no source migration. This API migration does not itself require a database change; review any separate plugin migrations through the upgrade Skill's database workflow.
10
+
11
+ ## Inventory application-owned consumers
12
+
13
+ Search the application's source and custom plugin/worker repositories, including test helpers and transport adapters. This initial search finds service imports, declarations, publication-result assumptions, readiness listeners and polling consumers; follow aliases and wrappers from the hits rather than treating a zero-result search as proof of compatibility:
14
+
15
+ ```bash
16
+ rg -n '(@nocobase/(realtime|app-server/realtime)|realtimeServiceToken|realtimeClientToken|useRealtime|refreshRealtimeQueries|createRealtimeRefresh|defineTopic|registerTopic|subscriberCount|subscriptionCount|onTopicSubscriptionChange|onOpen|onReady|refetchInterval|setInterval)' . --glob '*.{ts,tsx,js,jsx,mts,cts,mjs,cjs}' --glob '!node_modules/**' --glob '!dist/**' --glob '!pnpm-lock.yaml'
17
+ ```
18
+
19
+ For each consumer, identify the topic and its declaration owner, publisher, audience/resource policy, authoritative snapshot or persisted cursor, and recovery path. Follow publication wrappers through transactions, jobs and failure handlers. Include owned packages outside this directory; report inaccessible external plugin code as an unverified compatibility dependency. Put required adaptations and any unresolved access policy in the upgrade plan before editing.
20
+
21
+ ## Migrate server contracts
22
+
23
+ | Existing assumption or use | Required adaptation when the target changes this contract |
24
+ | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
25
+ | Any valid topic string can be published or subscribed to | Declare static topics with `defineTopic`/`registerTopic` and dynamic resource families with `defineTopicFamily` during provider boot, before subscriptions. Keep a single declaration owner and release its handles at shutdown. Validate existing dynamic IDs against the target's topic format. |
26
+ | A topic name or signed-in socket proves resource access | Preserve the intended audience. A user topic derives its subscriber from the authenticated principal; a resource family reuses the snapshot endpoint's access policy before subscription and delivery. `audience: 'public'` alone does not require authentication or resource permission. Do not remove restrictions to make a migrated subscription succeed. |
27
+ | Server operations finish synchronously | Await server `publish`, topic `publish`/`publishFor`, `subscribe`, `handleClientMessage`, `disconnectUser` and service `close` where owned; update adapters and mocks accordingly. Await `disconnectSession` if used. Host applications retain `realtimeServiceToken` from `@nocobase/app-server/realtime`; the host owns service setup/shutdown. Standalone services own `setup()` and `close()`. Topic-handle `close()` and browser subscription cleanup remain synchronous. |
28
+ | A surrounding synchronous `try/catch` handles announcement failure | Await publication inside the handler or attach an explicit rejection handler. Publish after the transaction commits. A best-effort announcement failure must not turn an already committed write into a failed HTTP response or cause the business write to repeat. Use the domain's durable outbox/job when retries are required. |
29
+ | `publish()` returns `{ topic, subscriberCount }` or proves delivery | Consume `{ eventId, topic }` for tracing. The promise means broker admission, not browser processing. Local subscription counts and `flush()` cannot prove remote delivery; remove local-subscriber guards that suppress cross-process publication. Use persisted revisions/cursors for business ordering and gap recovery. |
30
+ | Payloads are accepted whenever `JSON.stringify` succeeds | Send finite, acyclic JSON with plain objects and dense arrays. Convert dates to ISO strings and domain objects to explicit data; reject or deliberately map `undefined`, non-finite numbers, functions, accessors, symbols and unsupported objects. Test representative payloads against target validation and size limits even with no subscribers. |
31
+
32
+ For concrete declarations, transaction boundaries and adapter options, follow the target Realtime Skill's server reference. Do not replace the host service with another instance merely because its implementation moved to `@nocobase/realtime/server`.
33
+
34
+ ## Migrate browser recovery and test doubles
35
+
36
+ `subscribe(topic, listener)` still returns a cleanup function. Keep it where event-only consumption is sufficient; use `watch` or the host hooks when a consumer needs acknowledged readiness or per-topic errors. Read an authoritative snapshot after each topic's `onReady`, including the first subscription and reconnect. Keep `onOpen` for transport/identity work. Reconnect on sign-in, sign-out or session replacement, and clear account-bound caches; a replacement account must not reuse the former account's socket or data.
37
+
38
+ For query-backed pages, use the target's `refreshRealtimeQueries` with `useRealtimeRefresh` or `createRealtimeRefresh` where appropriate. Return the actual refresh promise so reads started before an event receive a follow-up read and failures remain observable. Preserve a usable snapshot during transient failures, clear protected data after HTTP 401/403, and keep subscription errors separate from snapshot errors. The query helper clears denied query snapshots; direct state readers must clear their own protected data and guard late responses.
39
+
40
+ When adopting the refresh scheduler, wire the existing Refresh/Try again action to its `retry()`. Retry exhaustion is not reset by another event. Topic readiness and manual retry can start a new attempt; foreground/online recovery applies to transient failures. Preserve failed work when batching later events. Follow the target Realtime Skill's client reference for retry options and cleanup rather than duplicating the scheduler in application code.
41
+
42
+ Update test doubles to return publication promises and correlate subscription acknowledgements/errors and heartbeat replies with their request IDs. An open fake socket without acknowledgements no longer proves subscription readiness. Test publication admission separately from delivery; `flush()` can wait for local queues in tests, while remote delivery needs an observed recipient.
43
+
44
+ ## Preserve recovery during rollout
45
+
46
+ Keep recovery polling until all relevant producers announce changes and disconnected clients can reconcile from durable data. External changes, time-based expiry and failed best-effort announcements may still require a suitable reconciliation interval. Replacing every poll is not a prerequisite for this upgrade.
47
+
48
+ The default memory broker is local to one service. For an existing multi-process deployment, verify the target adapter and application namespace across web processes and workers; a shared namespace alone does not distribute events. If Redis fan-out is used, follow the target package's distributed guide and verify broker recovery. Pub/Sub supplies no replay. During a mixed-version rollout, old browsers may not understand `resync`; retain periodic reconciliation or arrange a client reload, and verify the actual client/server combination instead of assuming wire compatibility.
49
+
50
+ ## Verify the migrated application
51
+
52
+ Run the upgrade Skill's package checks, then exercise affected application behavior. Select the cases that match the migrated consumers and record skipped or unavailable scenarios explicitly:
53
+
54
+ - **Declarations and access:** Known topics receive updates for authorized users; undeclared topics, anonymous callers to authenticated topics and unauthorized resource subscriptions are denied. Revoking resource access stops subsequent delivery. Existing grants and private payload boundaries remain intact.
55
+ - **Committed writes:** A rolled-back transaction announces no change. A successful write still succeeds when best-effort publication rejects, with the failure handled and recovery available. Valid production payloads pass, invalid or oversized payloads fail without unhandled rejections, including with zero subscribers.
56
+ - **Readiness and catch-up:** Change data while a client is disconnected, reconnect, and verify its snapshot after acknowledged readiness without requiring another mutation. Deliver an event while an earlier read is pending and verify that the final UI reflects the newer data.
57
+ - **Failure recovery:** A transient snapshot error recovers without a new event. After automatic retries are exhausted, the existing manual action recovers without restarting the business job. HTTP 401/403 stops automatic retries and clears protected snapshots; subscription refusal is reported separately.
58
+ - **Identity and cleanup:** Sign out and sign in as another account; neither old events nor cached private data appear. Navigating away releases watches/timers, and late reads cannot overwrite the new page or account.
59
+ - **Distributed use, when applicable:** A worker with no local subscribers reaches a browser on another process. Separate application namespaces remain isolated. After broker recovery, current clients reauthorize and catch up; the rollout's old-client fallback also recovers. Record which topology was actually exercised.
60
+
61
+ Report the contracts changed, custom consumers migrated, applicable checks and remaining compatibility gaps alongside the template version range and rollback plan. Type checking or a healthy WebSocket alone does not establish upgrade success.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: nocobase-deployment
3
- description: Plan, build, deploy, verify, upgrade, and troubleshoot NocoBase 3 applications in production, including standalone Node.js and Docker deployments. Use when an application must move from source to a production environment or when a deployment failure needs diagnosis.
3
+ description: Plan, build, deploy, verify, upgrade, and troubleshoot NocoBase 3 applications on an existing Studio or a standalone Node.js or Docker server. Use when an application must move from source to a deployment environment or when a deployment failure needs diagnosis.
4
4
  ---
5
5
 
6
6
  # NocoBase production deployment
@@ -13,7 +13,7 @@ Do not treat a process being healthy as proof that the application is usable. A
13
13
 
14
14
  Before building or changing a server, record:
15
15
 
16
- - The deployment mode: standalone Node.js managed by app-installer, standalone Node.js by hand, or standalone Docker.
16
+ - The deployment mode: an App managed by an existing Studio, standalone Node.js managed by app-installer, standalone Node.js by hand, or standalone Docker.
17
17
  - The source revision, application version, Node.js and pnpm versions, target CPU/OS/libc, and the destination host.
18
18
  - Whether the destination uses the existing database and storage, a new database, or a restore. Business data is not included in `dist`, `dist.tar.gz`, or a Docker image.
19
19
  - The application base path, public origin, database type, external services, reverse proxy, persistent directories, and service identity.
@@ -21,6 +21,14 @@ Before building or changing a server, record:
21
21
 
22
22
  Do not run production writes, migrations, seeds, uploads, deployments, or destructive removal until the target and the user's authorization are explicit. If the target or data plan is unresolved, stop and ask for it.
23
23
 
24
+ ## Deploy to an existing Studio
25
+
26
+ When the user asks to deploy this application to an existing NocoBase Studio, read [Deploy to Studio](references/deploy-to-studio.md) before building. It covers installing and signing in with the target Studio's `nb-studio` CLI, choosing an upload route, deploying and verifying the application. The application being deployed does not need its own business CLI.
27
+
28
+ Confirm the source application, target Studio, App ID and environment. A source directory, deployment directory and App ID can have different names; do not infer application identity from one of them. Follow the reference for Studio-managed configuration, storage and deployment; use the shared artifact and verification guidance below where applicable, not the standalone installation commands.
29
+
30
+ Deploying Studio itself to a server follows the standalone deployment workflow below.
31
+
24
32
  ## Prepare the source and artifact
25
33
 
26
34
  In the application project root, use the project's lockfile and declared pnpm version:
@@ -0,0 +1,146 @@
1
+ # Deploy an application to Studio
2
+
3
+ Use this workflow to deploy the current application to an existing NocoBase Studio. Keep application sources and build tools on the development or CI machine; Studio receives the deployment artifact. `pnpm nocobase` builds and maintains the source application, while `nb-studio` manages the destination. The application does not need a business CLI of its own.
4
+
5
+ ## 1. Identify the application and destination
6
+
7
+ Inspect the application's `package.json`, build configuration and working tree. Record:
8
+
9
+ - Source directory, package name, version and commit; note uncommitted changes.
10
+ - Studio URL, including its mount path, and CLI profile.
11
+ - App ID and target environment.
12
+ - First installation or update; existing data and storage to preserve.
13
+ - Public application URL, database and required external services.
14
+
15
+ Reuse values already supplied by the user. Ask only for unresolved information that changes the deployment target or data operation. Do not infer the application from a directory name or deploy whichever repository happens to be current after switching workspaces.
16
+
17
+ For multiple destinations, record each separately. Reuse one artifact only when their runtime requirements match. The Studio URL is the management endpoint; the deployed App's public URL is separate and comes from its environment.
18
+
19
+ ## 2. Prepare the Studio CLI
20
+
21
+ Check whether `nb-studio` is installed:
22
+
23
+ ```bash
24
+ command -v nb-studio
25
+ nb-studio --version
26
+ ```
27
+
28
+ If missing, obtain the installation command from the target Studio's **Use Studio in your agent** entry. Its command contains a short-lived download token. Use the command that Studio provides; do not invent a token or assume `@nocobase/studio-cli` is published to npm. The install script is served at `<studio-url>/api/agents/dist/installScript`, including the Studio mount path.
29
+
30
+ The currently served universal CLI package requires Node.js 24 or newer. Follow the installer's prerequisite checks and PATH instructions. A download token installs the CLI; it is not a login credential. Install the CLI once, then use profiles for separate Studio instances.
31
+
32
+ For a local coding agent, install the CLI's packaged Skill when needed:
33
+
34
+ ```bash
35
+ nb-studio skills install
36
+ ```
37
+
38
+ Use `--tool codex`, `--tool claude` or `--tool all` when the target tools are known. Read the installed `nb-studio-cli` Skill for command discovery and authentication rules. Inside a Studio agent run, reuse the supplied CLI, Skill and run identity rather than installing another copy or signing in as a person.
39
+
40
+ ## 3. Sign in and inspect the destination
41
+
42
+ For a person's local deployment, use an explicit profile for every destination:
43
+
44
+ ```bash
45
+ nb-studio --profile <profile> login --server <studio-url>
46
+ nb-studio --profile <profile> whoami
47
+ ```
48
+
49
+ The person must approve the device code in the browser. Never approve it on their behalf. If the existing profile is already authenticated to the correct server, reuse it; inspect its identity before starting another login. A Studio agent run keeps its supplied identity and permission limits.
50
+
51
+ For CI, use the organization's authorized CI credential through the documented environment variables or stdin mechanism. Keep credentials out of command arguments, logs and deployment reports. A missing or expired credential requires the supported login or credential setup; do not create a key to work around it.
52
+
53
+ Business commands come from the server. Inspect their documentation before using unfamiliar arguments:
54
+
55
+ ```bash
56
+ nb-studio --profile <profile> docs app
57
+ nb-studio --profile <profile> docs env
58
+ nb-studio --profile <profile> docs deploy
59
+ nb-studio --profile <profile> docs release
60
+ ```
61
+
62
+ Inspect the existing App and environment before creating or updating them. Determine:
63
+
64
+ - Whether the environment accepts archives or container images.
65
+ - Its target platform and runtime requirements.
66
+ - Whether deployment requires approval and what the caller may do.
67
+ - Required variables, configuration and available storage, including room for unpacking, retained releases and backups.
68
+ - Whether the App is connected to a repository whose commit Studio can verify.
69
+
70
+ An App Host running inside a container can still be an in-process environment. Do not infer its artifact type from the presence of Docker on the server. Do not select a different environment just to avoid an approval or artifact requirement. For a new App, use the documented creation route appropriate to the chosen upload workflow; repository-backed `app ensure` has repository prerequisites too.
71
+
72
+ ## 4. Build and configure
73
+
74
+ Follow the parent deployment Skill and the application's build instructions. For a compatible Linux x64 Node.js 24 archive target, for example:
75
+
76
+ ```bash
77
+ pnpm build --target linux-x64 --node-version 24 --tar
78
+ ```
79
+
80
+ Inspect `storage/exports/dist.tar.gz` and record its SHA256, package identity, version, build target and source revision. The archive carries application code and dependencies, not the development database, secrets or uploaded files. For an image environment, follow its image build, registry and release registration workflow instead; the archive commands below do not deploy an image.
81
+
82
+ Configure required App or environment variables through Studio's supported interfaces. Preserve existing secrets and data during updates. Initial administrator variables initialize a new account; they do not reset an existing account's password. Follow the application's sample-data setting rather than silently enabling examples.
83
+
84
+ Before an update, review migrations and establish the database and file backup and restore procedure for this App. Do not assume that Studio's own backup covers every hosted App, or that switching releases restores business data. Required variable declarations may become available only after upload; inspect them then and resolve missing values before deployment.
85
+
86
+ ## 5. Choose the upload and deployment route
87
+
88
+ ### Repository-backed build
89
+
90
+ When Studio knows the repository and can verify the source commit, use the documented build deployment command for an App that exists in the intended environment:
91
+
92
+ ```bash
93
+ nb-studio --profile <profile> deploy \
94
+ --app <app-id> \
95
+ --repository <owner/repo> \
96
+ --sha <source-commit> \
97
+ --file storage/exports/dist.tar.gz \
98
+ --json
99
+ ```
100
+
101
+ Outside CI, supply repository and commit explicitly. Do not invent a commit or claim that an artifact from a dirty working tree exactly matches it. `release upload` also uses Studio's verified-build route; it is not a fallback for a missing repository.
102
+
103
+ ### Manual archive without a connected repository
104
+
105
+ Do not repeatedly retry the verified-build route after `REPOSITORY_NOT_FOUND`. Do not connect a repository merely to bypass this prerequisite. Use Studio's release upload page or the documented application-level upload API within the caller's permissions. Read the target server's authenticated OpenAPI document at `<studio-url>/api/swagger` first.
106
+
107
+ The current API workflow is:
108
+
109
+ 1. Create an upload ticket with `POST /api/releases/apps/{appId}/uploadTickets`, requesting upload only (`deploy: false`).
110
+ 2. Upload the archive to the ticket's returned path using the ticket credential as `Authorization: Bearer <ticket>`, with the binary body and content type the API declares. Resolve the returned path against the documented API base; do not assume it already contains `/api` or the Studio mount path.
111
+ 3. Supply `X-Artifact-SHA256` and `X-Release-Deploy: false` so integrity is checked and deployment remains a separate step.
112
+ 4. Record the returned Release ID, inspect required variables and complete configuration.
113
+ 5. Deploy that release through the CLI, or request deployment when approval is required.
114
+
115
+ Prefix API paths with the Studio URL, including its mount path. Use an authorized authentication mechanism for the ticket request. Do not depend on reading `~/.nb-studio/config.json`: credentials may live in the system keychain, and its storage format is not an integration API. If no supported API credential is available, use the authenticated upload page or obtain the required credential through the supported setup.
116
+
117
+ The current application-level upload routes are not exposed as ordinary CLI commands. Do not invent a command or describe this route as CLI-only. An upload ticket does not grant permission to bypass a protected environment.
118
+
119
+ ### Existing release
120
+
121
+ For an unprotected environment:
122
+
123
+ ```bash
124
+ nb-studio --profile <profile> app deploy <app-id> \
125
+ --release <release-id> --wait true --json
126
+ ```
127
+
128
+ For a protected environment, follow the documented deployment-request flow. A pending approval is not a completed deployment, and approval rules must not be bypassed.
129
+
130
+ Release and Deployment IDs belong to their Studio instance. Never reuse an ID from another destination, even when both uploaded the same archive.
131
+
132
+ ## 6. Verify and report
133
+
134
+ Inspect the command's JSON result, deployment status and logs. An accepted upload, created release or timed-out wait does not prove deployment succeeded. After a timeout or uncertain response, inspect existing releases and deployments before retrying. Do not start a competing deployment.
135
+
136
+ Verify through the public application URL:
137
+
138
+ - Health endpoint and expected App identity.
139
+ - Static assets, page refresh, API requests and WebSocket connections.
140
+ - Sign-in and the relevant permission boundary.
141
+ - A representative business operation.
142
+ - Required data and file persistence, with restart verification when applicable. Prefer the App's restart operation; restarting Studio may interrupt other hosted Apps.
143
+
144
+ Use the parent Skill's verification guidance for the change being made. Reuse build checks for the same artifact, but verify each destination independently and report partial success explicitly. Keep external services or scheduled behavior that were not exercised separate from successful checks.
145
+
146
+ Record the destination, App and environment, artifact SHA256, source revision, Release ID, Deployment ID, public URL, verification results and unresolved items. Never include credentials. Do not report a deployment as complete while it is awaiting approval, still running, or failing its required verification.