@nocobase/app-skills 0.1.0-beta.50 → 0.1.0-beta.52

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.50",
3
+ "version": "0.1.0-beta.52",
4
4
  "description": "Agent Skills for developing, upgrading and deploying NocoBase applications.",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -37,7 +37,7 @@ Do not infer the application's capabilities from a template name or from this Sk
37
37
 
38
38
  ## The one rule that decides most tasks
39
39
 
40
- Build the feature in the application. Do not run a plugin generator, create a `packages/plugins/` directory, or write a `defineServerPlugin()` declaration for this application's own feature. Create a plugin only when the user explicitly asks for an independently published, reusable package.
40
+ Build the feature in the application. Do not run a plugin generator, create a `packages/plugins/` directory, or write a `defineServerPlugin()` declaration for this application's own feature. Create a plugin only when the user explicitly asks for an independently published, reusable package. Ordinary internal workspace packages for shared code are different: when the application needs them, follow [internal workspace packages](references/dependencies.md#internal-workspace-packages), keeping one application at the workspace root with internal packages under `packages/`. The [runnable package example](references/internal-package-example.md) supplies complete configuration and explains declaration watching.
41
41
 
42
42
  ## Check the installed plugins first
43
43
 
@@ -48,3 +48,37 @@ Declare such a package in `dependencies` when you write the code; nothing will r
48
48
  Node ABI to major version: 115 is Node 20, 127 is 22, 137 is 24, 147 is 26.
49
49
 
50
50
  `pnpm build` targets the machine it runs on, so `pnpm build && pnpm start` works. A deployment build says where it is going: `--target linux-x64`, `--target linux-arm64`, `--target linux-x64-musl`, plus `--node-version` when the server's Node major differs. A `.node` binary must match the target platform, architecture, and C library; addons using the Node ABI must also match its version. `pg`, `mysql2`, and `tedious` are plain JavaScript, so an application using only those is portable as built. The Finishing section of [the Skill](../SKILL.md#finishing) and the `nocobase-deployment` Skill cover build targets in full.
51
+
52
+ ## Internal workspace packages
53
+
54
+ An application may own a pnpm workspace without moving its `client/`, `server/`, `cli/` or `database/`. Declare `packages: ['packages/*']` in its root `pnpm-workspace.yaml`, preserving existing settings, and put ordinary shared packages below `packages/`. Use unique package names and explicit `workspace:*` references: server imports belong in the application's `dependencies`, client-only imports in `devDependencies`. Internal packages can be private; sharing code does not require a plugin or an npm release. Never import a sibling package through a relative filesystem path.
55
+
56
+ The supported layout is one application at the root with internal packages below `packages/`; this is not a general multi-application monorepo workflow. Use the [runnable internal-package example](internal-package-example.md) for complete source, configuration, scripts, application imports and declaration watching.
57
+
58
+ Use `src/` for an ordinary package's sources. Prefer source imports during development, with compiled declarations for typechecking and compiled imports for deployment. For example:
59
+
60
+ ```json
61
+ {
62
+ "name": "@my-app/shared",
63
+ "version": "0.0.1",
64
+ "private": true,
65
+ "type": "module",
66
+ "files": ["dist"],
67
+ "exports": {
68
+ ".": { "types": "./dist/index.d.ts", "import": "./src/index.ts" }
69
+ },
70
+ "publishConfig": {
71
+ "exports": {
72
+ ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" }
73
+ }
74
+ }
75
+ }
76
+ ```
77
+
78
+ `publishConfig.exports` also tells the application build which exports to put in its vendored deployment copy; it does not require publishing. Give the package a `build` script that emits JavaScript and declarations into `dist`, plus `lint`, `typecheck`, `test`, `check` and `fix` scripts using `@nocobase/dev-config`. Install the package's build tooling as its own development dependencies. Keep React and identity-sensitive NocoBase runtimes as peers, supplied by the application. Browser packages must not expose server-only imports through their client entry.
79
+
80
+ Run `pnpm install` once at the application root. Build a new package before standalone typechecking needs its declarations. When runtime imports point to `src` but types point to `dist`, keep a declaration watcher running (`tsc --emitDeclarationOnly --watch`); otherwise exported type changes leave consumers checking stale declarations. During `pnpm dev`, Vite loads linked client sources and the server watches reachable internal workspace packages, including transitive ones, under `src/`, `server/`, `database/` and `shared/`; it also watches compiled `dist/` for packages that choose compiled exports. Such packages need their own build watcher running separately. Restart development after adding a package or changing the dependency graph so the watch set is recalculated.
81
+
82
+ `pnpm build` builds workspace dependencies before application typechecking and client bundling. The deployment includes runtime workspace packages and their transitive runtime dependencies under `dist/vendor`, using their compiled exports. Keep runtime assets in `dist` or in literal paths named by `files`; glob patterns in `files` are not copied by the deployment builder. Verify a deployment outside the source workspace. Do not run a recursive build that also selects the root application while its own build is rebuilding dependencies; an external topological build may set `NOCOBASE_SKIP_WORKSPACE_DEPENDENCY_BUILD=1` once it owns that ordering.
83
+
84
+ Each internal package owns its checks. Current templates exclude `packages/` from root linting and formatting and run the packages' `check` scripts through `pnpm check:packages` before the application checks. During a template upgrade, retain internal packages, their `workspace:` dependencies and custom workspace patterns, then reinstall at the application root and check the affected packages and application together.
@@ -14,6 +14,8 @@ With `PROXY_TARGET_URL`, the local Hono server is skipped and Vite becomes the l
14
14
 
15
15
  Changes to `.env` and `.env.local` (including creation, atomic replacement, and deletion) restart the full development run after its previous processes exit. The new run reloads environment files, ports, proxy settings, and startup hooks; explicit shell variables still take precedence. Use the newly printed URL if the port or base path changes. This also applies in proxy mode. `config.yml` changes restart only the local server. `NOCOBASE_STRICT_STARTUP=true` disables both automatic restarts.
16
16
 
17
+ In normal watch mode the public entry port stays open while the application backend restarts on a private loopback port. New connections wait up to 30 seconds for that backend, so shared-package edits can update client modules even during a server restart. Requests already sent to the old backend are never replayed; a pending API call or realtime connection can still be interrupted. Keep using the printed `Local:` URL rather than the private backend port. Strict startup and remote-backend mode do not use this connection proxy.
18
+
17
19
  Changes to `package.json`, the lockfile, and the package manager's install state restart the local server once they have been quiet for a few seconds. An install writes several of them over as long as fetching and linking take, so restarting on the first write would bring the server back against a half-installed `node_modules` — and the next write would arrive while it was still shutting down, which is where the watcher escalates to SIGKILL. Waiting for quiet turns one install into one restart.
18
20
 
19
21
  ## One development server per application
@@ -38,7 +40,7 @@ For local client debugging against another running application, use `PROXY_TARGE
38
40
 
39
41
  The proxy maps same-origin browser HTTP and WebSocket Origin headers to the target origin, with matching Referer paths mapped to the target app base. It preserves foreign origins and does not add missing Origin headers. Keep backend origin checks enabled. Test browser handshakes with an explicit Origin; an Origin-less Node WebSocket test does not verify browser compatibility. Production does not use this Vite adaptation: configure `APP_PUBLIC_ORIGIN` and preserve public Host/protocol information through the reverse proxy.
40
42
 
41
- Use `APP_SERVER_PORT` for the local entry port in both development modes. With `PROXY_TARGET_URL` it selects Vite's preferred port, defaulting to 5173; without it, it selects the local backend port, defaulting to 13000, and Vite still starts from 5173. If occupied, the port advances automatically. Open the printed Local URL and keep the remote service address in `PROXY_TARGET_URL`; this variable does not change it.
43
+ Use `APP_SERVER_PORT` for the local entry port in both development modes. With `PROXY_TARGET_URL` it selects Vite's preferred port, defaulting to 5173; without it, it selects the public application port, defaulting to 13000, and Vite still starts from 5173. If occupied, the port advances automatically. Open the printed Local URL and keep the remote service address in `PROXY_TARGET_URL`; this variable does not change it.
42
44
 
43
45
  ## Development logging
44
46
 
@@ -309,7 +309,7 @@ The shell header shows the current page's breadcrumb after the sidebar toggle, o
309
309
 
310
310
  - It is a muted text link with an arrow and "Back" (`navigation.back`), turning to the foreground on hover.
311
311
  - By default it leads to the parent route and keeps the query string, as closing an overlay does: from `/projects/import?status=active` it returns to `/projects?status=active`, and the list keeps its search and filters. The parent is found by route, not by path segment, so a child route with a two-segment path returns to its parent too.
312
- - **The query string it keeps is the current one.** The page it returns to gets its search and filters back only if every link on the way down carried them: a link into a page below another one forwards `location.search` whole, never a selection of it. Whatever the page being left wrote there goes back too, unless the page removes it: a page that writes parameters of its own, itself or in its tabs (the Orders tab's `ordersQ`), passes `to` with those parameters removed — `<BackButton to={{ pathname: '..', search: withoutParams(location.search, CUSTOMER_PAGE_PARAMS) }} />`, with `withoutParams` from [`example/url-search.md`](example/url-search.md) — so the list gets exactly its own back, and the next customer does not open with the previous one's order search. `..` still follows the parent route the page was opened from.
312
+ - When the shell has visited the parent, the default back link restores that parent's recorded query, including an explicitly empty query. Without a recorded parent (including a direct detail URL or reload), **the fallback query string is the current one.** The page it returns to gets its search and filters back only if every link on the way down carried them: a link into a page below another one forwards `location.search` whole, never a selection of it. Whatever the page being left wrote there goes back too, unless the page removes it: a page that writes parameters of its own, itself or in its tabs (the Orders tab's `ordersQ`), passes `to` with those parameters removed — `<BackButton to={{ pathname: '..', search: withoutParams(location.search, CUSTOMER_PAGE_PARAMS) }} />`, with `withoutParams` from [`example/url-search.md`](example/url-search.md) — so the list gets exactly its own back, and the next customer does not open with the previous one's order search. `..` still follows the parent route the page was opened from.
313
313
  - `to` sends it elsewhere, for a page that belongs to exactly one parent, such as a record page declared beside its list: `<BackButton to={{ pathname: '/customers', search: location.search }} />`. For a module reused under several parents — a record's page opened from another page as well (["The same detail page over another page" in `child-routes.md`](child-routes.md#the-same-detail-page-over-another-page)) — omit it, or keep `..` as its `pathname` when only the query string changes, as the previous point does, so the back button follows the parent route it was opened from; a hard-coded path sends a user who came from elsewhere to a page they were not on. `children` replaces the label; keep "Back" unless the destination needs naming.
314
314
  - It navigates rather than going back in the browser history, which a page opened from a link or a refresh does not have, and it replaces the history entry, as closing an overlay does: the browser's Back then does not reopen the page just left, such as a form that would come back empty.
315
315
 
@@ -321,7 +321,7 @@ By default the trail is generated from the matched route levels:
321
321
 
322
322
  - A route with `breadcrumb` is a level, titled by it; a menu page (`navigation` with a component) without one is a level titled by its `navigation.title`. Tab, dialog and drawer routes declare neither and add no level, so an overlay leaves the page beneath as the current level.
323
323
  - A level the viewer may not open is left out, so a denied page's title never shows.
324
- - Earlier page levels link to their actual URLs, without query string; a group without a component is plain text. The last level is the current page and is not a link.
324
+ - Earlier page levels link to their actual URLs with the query recorded when that ancestor was last visited in the current route ancestry. This restores its search, filters and page without copying detail-only parameters. An ancestor never visited in this mounted shell (for example, a direct detail URL or a reload) links without a query; use an explicit `usePageBreadcrumb` destination when a deep link must carry a known parent query. A group without a component is plain text. The last level is the current page and is not a link.
325
325
  - `breadcrumb.title` is a static translation key and names the kind of page ("Project details"), so it can sit on a path with parameters and is known before anything loads.
326
326
 
327
327
  A page whose trail names records, or should lead back with the parent's search, declares its whole trail with `usePageBreadcrumb` from `@nocobase/app-client`, the page itself last:
@@ -288,6 +288,20 @@ Theme-aware, read-only lifecycle diagram using React Flow and ELK. Shows the cur
288
288
  - Example: `@nocobase/lifecycle-diagram-demo` (`pnpm exec shadcn view @nocobase/lifecycle-diagram-demo`)
289
289
  - After installing: Pass description.description from useLifecycle/createLifecycleHook, currentState from view.record, availableTransitions filtered from view.available, and history from view.history.transitions. History matches the exact transition/source/destination; current state alone never implies a visited path. Pass a translated endLabel for separate decorative markers on explicit final states. Defaults to direction DOWN, autoHeight and initialMinZoom 0.7 for readable vertical page reading. The Fit control still shows the entire graph; an explicit initialMinZoom overrides the default. Override direction and autoHeight explicitly for compact canvases. stateActions supplies explicit configuration buttons; nodeDescription displays real policy summaries. Translate ariaLabel, stateLabel and transitionLabel; append a gear to automatic transition labels if needed. Edges are solid with inline labels and subdued neutral strokes; current/visited/available highlights use the application primary theme token. Current nodes have a stronger border and ring; icons, top accents and status footers distinguish current, visited and configurable nodes using theme tokens. onStateClick/onTransitionClick open details and never fire transitions. Keep toMermaid for documentation/export. Pass configuration={label, canConfigure, onConfigure} for automatic Configure buttons on authorized bound states and configuration selection on bound transitions. onConfigure receives the exact target and permitted bound fields grouped by native parameter key; connect the existing real editor and API. canConfigure is required and is only a UI affordance. Explicit direction/style overrides are reserved for user-requested customization; Mermaid is documentation/export only.
290
290
 
291
+ ## File
292
+
293
+ ### file-component-ui
294
+
295
+ Application-owned upload, list, thumbnail, and preview components for business file endpoints.
296
+
297
+ - Kind: block
298
+ - Install: `yes n | pnpm exec shadcn add @nocobase/file-component-ui`
299
+ - Installs to: `client/extensions/nocobase-file-component-ui/`
300
+ - Plugin dependencies: `@nocobase/app-plugin-file`
301
+ - Also installs: `@nocobase/attachment-list`
302
+ - Example: `@nocobase/file-component-ui-demo` (`pnpm exec shadcn view @nocobase/file-component-ui-demo`)
303
+ - After installing: Requires the File plugin services and your own authorized file repository. Pass a ClientFileRepository to FileUploadField. Merge locales/ into application locales. The default template preinstalls this block; reconcile existing copies instead of overwriting them.
304
+
291
305
  ## Inbox
292
306
 
293
307
  ### inbox
@@ -313,6 +327,19 @@ A header button linking to the inbox, with an amber badge for what waits on the
313
327
  - Example: `@nocobase/inbox-button-demo` (`pnpm exec shadcn view @nocobase/inbox-button-demo`)
314
328
  - After installing: Render <InboxButton badge={inboxBadge(waiting, unread)} /> inside a TooltipProvider, with inboxBadge from #components/inbox-badge, waiting what your inbox counts as waiting (0 without decisions) and unread from useInboxUnreadCount() of @nocobase/app-plugin-notification-in-app/client/inbox; useDocumentTitleBadge(badge?.text ?? null) prefixes the tab title. Add the inboxButton.* keys its README lists to client/locales/.
315
329
 
330
+ ## Notification
331
+
332
+ ### notification-logs-ui
333
+
334
+ Application-owned delivery and provider attempt log components backed by the NocoBase notification API.
335
+
336
+ - Kind: block
337
+ - Install: `yes n | pnpm exec shadcn add @nocobase/notification-logs-ui`
338
+ - Installs to: `client/extensions/nocobase-notification-logs-ui/`
339
+ - Plugin dependencies: none
340
+ - Example: `@nocobase/notification-logs-ui-demo` (`pnpm exec shadcn view @nocobase/notification-logs-ui-demo`)
341
+ - After installing: Requires the Notification server plugin and authorized access to GET /api/notifications/logs. Mount NotificationLogsPage in an application-owned route and merge locales/ into application locales. Shows the newest 100 logs; adds no route or permissions.
342
+
316
343
  ## Other
317
344
 
318
345
  ### data-table
@@ -0,0 +1,48 @@
1
+ # A runnable internal package
2
+
3
+ This example supports one application at the workspace root, with private shared packages below `packages/`. It does not establish a general multi-application monorepo workflow. Custom workspace patterns are preserved during creation and upgrades, but the automatic internal-source watches and template package checks target `packages/`; a different layout needs its own watching and checks.
4
+
5
+ Run the [example creator](../scripts/create-internal-package.mjs) from an installed application root:
6
+
7
+ ```bash
8
+ node .agents/skills/nocobase-app-development/scripts/create-internal-package.mjs
9
+ ```
10
+
11
+ It creates `packages/shared` and refuses to overwrite it. The generated package includes `src/index.ts`, a behavior test, `tsconfig.json`, ESLint and Vitest configurations, ignore files, and `build`, `dev:types`, `typecheck`, `lint`, `format`, `test`, `check` and `fix` scripts. Tooling dependencies use the application's installed versions, including `@nocobase/dev-config`; no registry lookup chooses unrelated newer versions. The sample has no Node-only runtime imports, so its `greet` function and `Greeting` type work in both application halves. Adapt the package name and behavior to the application after trying it.
12
+
13
+ Ensure `pnpm-workspace.yaml` includes `packages/*`, retaining its other settings. Add `"@my-app/shared": "workspace:*"` to the application's `dependencies` for this shared server/client example. A client-only package belongs in `devDependencies`. Then run:
14
+
15
+ ```bash
16
+ pnpm install
17
+ pnpm --filter @my-app/shared fix
18
+ pnpm --filter @my-app/shared build
19
+ pnpm check:packages
20
+ ```
21
+
22
+ Import by package name from either `client/` or `server/`:
23
+
24
+ ```ts
25
+ import { greet, type Greeting } from '@my-app/shared';
26
+
27
+ const greeting: Greeting = greet('Ada');
28
+ ```
29
+
30
+ Use `greeting.message` in the feature that consumes it; keep user-visible application copy in the application's translations. The package exports `src/index.ts` at development runtime and `dist/index.d.ts` to TypeScript. Its `publishConfig.exports` directs deployment imports to `dist/index.js`; it remains private and needs no publishing or plugin registration.
31
+
32
+ ## Keep declarations current
33
+
34
+ Build once before the application's first standalone typecheck. During development, run this in a separate terminal alongside `pnpm dev`:
35
+
36
+ ```bash
37
+ pnpm --filter @my-app/shared dev:types
38
+ ```
39
+
40
+ Vite and tsx read the changed source immediately, while application typechecking reads the generated declarations. Without the declaration watcher, changing an exported type can leave the editor and `pnpm typecheck` checking the previous API even though the runtime uses the new code. Wait for the watcher to finish without errors before checking consumers; a failed emit can leave older declarations on disk. With several packages, start their declaration watchers and build dependencies in order before the first consumer check. Packages using compiled runtime exports need a full `tsc --watch` build instead of declaration-only emission.
41
+
42
+ Restart `pnpm dev` after adding a package or changing workspace dependencies, because the server's explicit watch set is calculated at startup. `pnpm build` builds workspace dependencies before typechecking and bundling the application; the one-shot deployment build does not need these watchers.
43
+
44
+ ## Verify the consuming application
45
+
46
+ Run `pnpm check:packages` and the application's scoped checks after wiring in the imports. The template check reports any selected internal package without a non-empty `check` script before running any package checks; an empty `packages/` layout succeeds. To verify a changed exported type, add a required field to `Greeting`, update `greet`, wait for declaration generation, and confirm an application assignment that omits the new field fails typechecking. Repair the consumer before continuing.
47
+
48
+ For runtime acceptance, exercise a real frontend use and server response before and after editing `greet`, then build with `pnpm build --tar` and run the extracted archive outside the source workspace with the original sources unavailable. Verify the consuming feature there as well as the health endpoint. Follow the deployment Skill for configuration and database isolation; a successful health response alone cannot prove the internal package was included.
@@ -0,0 +1,87 @@
1
+ import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
2
+ import path from 'node:path';
3
+
4
+ // Run from an installed application. Resolve tooling versions before creating anything.
5
+ const root = process.cwd();
6
+ const tooling = [
7
+ '@nocobase/dev-config',
8
+ '@types/node',
9
+ 'typescript',
10
+ 'eslint',
11
+ 'prettier',
12
+ 'vitest',
13
+ ];
14
+ const devDependencies = Object.fromEntries(
15
+ tooling.map((name) => {
16
+ const manifest = JSON.parse(
17
+ readFileSync(
18
+ path.join(root, 'node_modules', name, 'package.json'),
19
+ 'utf8',
20
+ ),
21
+ );
22
+ return [name, manifest.version];
23
+ }),
24
+ );
25
+ const directory = path.join(root, 'packages/shared');
26
+ mkdirSync(path.dirname(directory), { recursive: true });
27
+ // Refuse to replace an existing package, even an empty directory.
28
+ mkdirSync(directory);
29
+ const files = {
30
+ 'package.json': {
31
+ name: '@my-app/shared',
32
+ version: '0.0.1',
33
+ private: true,
34
+ type: 'module',
35
+ files: ['dist'],
36
+ exports: { '.': { types: './dist/index.d.ts', import: './src/index.ts' } },
37
+ publishConfig: {
38
+ exports: {
39
+ '.': { types: './dist/index.d.ts', import: './dist/index.js' },
40
+ },
41
+ },
42
+ prettier: '@nocobase/dev-config/prettier',
43
+ scripts: {
44
+ build: 'tsc -p tsconfig.json',
45
+ 'dev:types':
46
+ 'tsc -p tsconfig.json --emitDeclarationOnly --watch --preserveWatchOutput',
47
+ typecheck: 'tsc -p tsconfig.json --noEmit',
48
+ lint: 'eslint . --max-warnings 0',
49
+ 'lint:fix': 'eslint . --fix --max-warnings 0',
50
+ format: 'prettier . --write',
51
+ 'format:check': 'prettier . --check',
52
+ test: 'vitest run',
53
+ check:
54
+ 'pnpm lint && pnpm format:check && pnpm typecheck && pnpm test && pnpm build',
55
+ fix: 'pnpm lint:fix && pnpm format',
56
+ },
57
+ devDependencies,
58
+ },
59
+ 'tsconfig.json': {
60
+ extends: '@nocobase/dev-config/tsconfig/server-library.json',
61
+ compilerOptions: { rootDir: 'src', outDir: 'dist' },
62
+ include: ['src'],
63
+ },
64
+ 'eslint.config.js':
65
+ "import { createNodeLibraryConfig } from '@nocobase/dev-config/eslint';\nexport default createNodeLibraryConfig();\n",
66
+ 'vitest.config.ts':
67
+ "import { createNodeVitestConfig } from '@nocobase/dev-config/vitest/node';\nexport default createNodeVitestConfig();\n",
68
+ '.prettierignore': 'dist/\nnode_modules/\ncoverage/\n',
69
+ '.gitignore': 'dist/\nnode_modules/\ncoverage/\n',
70
+ 'src/index.ts':
71
+ 'export interface Greeting {\n message: string;\n}\n\nexport function greet(name: string): Greeting {\n return { message: `Hello, ${name}!` };\n}\n',
72
+ 'tests/greet.test.ts':
73
+ "import { expect, it } from 'vitest';\nimport { greet } from '../src/index.ts';\n\nit('greets the requested person', () => {\n expect(greet('Ada')).toEqual({ message: 'Hello, Ada!' });\n});\n",
74
+ };
75
+ for (const [relative, contents] of Object.entries(files)) {
76
+ const file = path.join(directory, relative);
77
+ mkdirSync(path.dirname(file), { recursive: true });
78
+ writeFileSync(
79
+ file,
80
+ typeof contents === 'string'
81
+ ? contents
82
+ : `${JSON.stringify(contents, null, 2)}\n`,
83
+ );
84
+ }
85
+ console.log(
86
+ 'Created packages/shared. Add @my-app/shared: workspace:* to the application dependencies, then run pnpm install and pnpm --filter @my-app/shared fix.',
87
+ );
@@ -100,6 +100,8 @@ When BASE → TARGET changes Realtime contracts, read [Realtime upgrades](refere
100
100
 
101
101
  When BASE → TARGET changes notification contracts, read [Notification upgrades](references/notification-upgrade.md) during planning. Include application-owned test-send forms, API clients, permissions, log pages, E2E fixtures and custom channel extensions in step 5; distinguish removed TestAdapter APIs from deprecated registration and configuration APIs that remain compatible.
102
102
 
103
+ When the template changes list-return behavior, read [list navigation upgrades](references/list-navigation-upgrade.md). Merge the routing context, breadcrumb and back-link sources together, and examine application-owned detail links and forms; updating dependencies alone does not update these copied sources.
104
+
103
105
  Then ask the project which of those files it has also touched:
104
106
 
105
107
  ```bash
@@ -50,6 +50,10 @@ When a compatible newer version of the retaining dependency is available within
50
50
 
51
51
  After resolving the conflict, rerun `pnpm nocobase skills sync` and all Finish checks. Confirm the affected paths use a compatible shared package resolution; unrelated packages may legitimately retain multiple versions. A remaining type error without duplicate package resolutions needs investigation as a source or API compatibility issue.
52
52
 
53
+ ## Internal workspace packages
54
+
55
+ When the application owns `packages/`, preserve those directories and their `workspace:` dependency ranges while reconciling the root template. Preserve custom `packages` patterns and installation settings in `pnpm-workspace.yaml`; add `packages/*` only when internal packages need it and no existing pattern includes them. Keep a single root lockfile. New template check scripts may delegate to internal packages, so ensure those packages provide their own checks and run them as well as the application checks. See the development Skill's [internal workspace package contract](../../nocobase-app-development/references/dependencies.md#internal-workspace-packages).
56
+
53
57
  ## Generated configuration and committed examples
54
58
 
55
59
  `config.yml` holds real settings and generated secrets. A template may also generate `.env` for build-time deployment facts. These live files are gitignored, were written by `pnpm nocobase config init` and the generator rather than copied from the template, and are absent from the release diff. Never print or replace them as part of the merge. `config init` refuses to overwrite an existing configuration, so it is safe to run during an upgrade; `--force` replaces one and is never part of a merge.
@@ -271,3 +275,7 @@ Reconcile `client/pages/settings/page-permissions.ts`, the role form's catalog a
271
275
  Reconcile the catalog descriptions, individual account-permission groups, category names without counts, individual action controls and labelled multi-scope summaries with the role form and locale updates. A display resource may share a stored resource ID with another display group: resolve a changed row by resource type, resource ID and action together, so later groups remain editable. Preserve all registered action IDs and existing unknown or structured policies. Update the authorization and Agent plugins together when adopting their new catalog labels, action-description metadata and administrative placement. An empty scope means no additional record access; retain default access, sharing and restriction behavior.
272
276
 
273
277
  Keep empty-scope explanations in the range help tooltip rather than a permanent paragraph under every select. Reconcile the Tooltip primitive, scope hint label binding and localized text together; keyboard focus and touch activation must expose the same explanation without changing grants.
278
+
279
+ ## Explicit Member assignments
280
+
281
+ When upgrading to the explicit Member role behavior, upgrade Authentication, Authorization, and Users together and stop old account writers before `pnpm nocobase db apply`. The Authorization seed preserves existing Member access as direct assignments before removing its global assignment; do not edit old tasks or recreate the old association. Merge the prepared user form, list, and settings translations separately. Use the new role-scope `defaultValue` only on creation, respect explicit empty arrays, and never restore Member during profile edits. Verify role removal through a direct API request and a fresh login. Recover with the database backup and matching old packages, not an inverse role assignment script.
@@ -0,0 +1,18 @@
1
+ # Preserving list state during template upgrades
2
+
3
+ The Default and Examples templates ship application-owned routing and component source. A package-only dependency update does not change an existing application's list navigation. Use the BASE / TARGET / PROJECT comparison in the upgrade Skill; keep the application's route ids, permission declarations, custom columns, filters, detail content and data.
4
+
5
+ ## Merge the behavior together
6
+
7
+ - Compare `client/routing/route-context.tsx`, `client/components/breadcrumbs.tsx` and `client/components/back-button.tsx` together. The route-tree provider records queries only for visited pages in the active ancestry, and the default breadcrumb/back links use the destination's query rather than a child's query. Retain the provider inside the router and outside the changing page content.
8
+ - Compare both templates' prepared `client/pages/settings/role-form.tsx`. Resolve the parent route with `useResolvedPath('..')` rather than hard-coding `/settings/roles`; prepared management routes may be registered at `/roles` or under another parent. Preserve the query for return, cancel and successful save.
9
+ - Review application-owned lists and detail pages even when they have no template counterpart. Keep committed search, filters and pagination in the URL and drive controls and requests from that same state. Continue forwarding the list query to child links for browser history and reloads; remove child-only parameters on an explicit return destination. Preserve intentional `BackButton to` and `usePageBreadcrumb` destinations, which remain application-owned overrides.
10
+ - A direct detail URL or reload has no remembered ancestor visit. Default breadcrumbs then use the ancestor's path without borrowing detail parameters; the default back link retains its existing current-query fallback. Use an explicit destination for a known parent query in a custom deep-link flow. There is no database migration, persistent preference or cross-session state cache for this behavior.
11
+
12
+ ## Verify the upgraded application
13
+
14
+ Record the exact source template, BASE release, TARGET release (or explicitly identified unpublished candidate commit), upgrade branch and original application commit. Do not claim an unpublished candidate is a released upgrade or advance template provenance to a release that does not exist.
15
+
16
+ For both a newly generated app and the existing app after the source merge, search and filter enough records to reach page two, open a detail, and return through the breadcrumb, default back link and browser Back. Compare the URL, controls, page number and visible record ids; repeat the navigation. Check nested detail filters, unrelated lists, empty queries, changed/cleared filters, deep links, and role create/edit cancel and save. Verify custom columns, filter semantics, detail behavior and permission boundaries remain unchanged. Do not replace a real application's upgrade acceptance with a synthetic fixture; label fixtures and any unverified application-specific behavior.
17
+
18
+ Support is established for the template origins and baseline releases actually inspected and tested. Unknown template ancestry or independently rewritten navigation requires investigation; do not promise that every historical or custom application inherits the fix automatically.