@nocobase/app-skills 0.1.0-beta.45 → 0.1.0-beta.47

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.45",
3
+ "version": "0.1.0-beta.47",
4
4
  "description": "Agent Skills for developing, upgrading and deploying NocoBase applications.",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -66,6 +66,14 @@ Install, update and customize plugins, and remove a direct NocoBase package, as
66
66
 
67
67
  Business role assignments must be visible and editable through administration. Default to explicit users; do not assign application roles to every authenticated identity or broaden the inherited member role merely to enable a feature. Follow [permission assignment safety](references/authorization.md#visible-and-manageable-assignments) and run the template's initialized-assignment guard before delivery.
68
68
 
69
+ ## Choose sample data or a demo system
70
+
71
+ A request to add example customers, orders or tasks normally means sample data in the existing application. Use `sample: true` seeds or `sampleDataToken`; see [sample data and demo systems](references/migrations.md#sample-data-and-demo-systems). Keep required initialization data in ordinary seeds. Do not infer an isolated demo deployment from the words "demo data" alone.
72
+
73
+ A dedicated demo system has its own database and storage, repeatable business-data generation/clear/reset, visitor write policies and optional simulated external or Agent execution. For that requirement, follow the `nocobase-app-plugin-demo-mode` Skill. If `@nocobase/app-plugin-demo-mode` is not yet a dependency, register it with `pnpm nocobase plugin register demo-mode`, which also synchronizes its Skill; the Skill exists in the application only after synchronization. The plugin supplies the environment mechanisms; the application supplies its dataset, cleanup, management UI and any simulation adapters. Sample data alone supplies none of those operating policies. Use the user's stated deployment and lifecycle requirements to choose; if the intended scope remains ambiguous, clarify it before adding full-business cleanup or changing the environment mode. A trial, staging or customer environment where users keep their data, a provider's sandbox credentials and an in-app presentation mode are not demo systems.
74
+
75
+ When the application already depends on `@nocobase/app-plugin-demo-mode`, a change that adds business collections, outbound integrations or background jobs also updates the demo dataset's cleanup and adapters; follow that Skill's maintenance section.
76
+
69
77
  ## Deliver system administration by default
70
78
 
71
79
  When a user asks you to build a complete application, deliver a usable System management navigation section and administration pages alongside the business features, unless the user explicitly excludes them or requests a narrower deliverable such as an API-only service or a prototype explicitly limited to business screens. Users do not need to request administration pages individually. Include user management and role and permission management by default. Place workflow management, background tasks and other applicable administration entries directly under System management as siblings; show execution status, failures and supported recovery actions within each capability's pages, without an additional Operational monitoring group. Reuse existing pages and installed plugins, and implement missing application-owned pages. Read [system administration](references/system-administration.md) for the baseline, capability-specific pages and acceptance criteria. For a focused feature change, extend existing administration where that feature requires it.
@@ -24,7 +24,11 @@ Every `server/routes/` endpoint installs authentication and authorization. A bus
24
24
 
25
25
  Declare `authz` on the first page of every path in `client/routes.ts`: `{ resource: { type: 'page', id }, action: 'access' }` for a business page, the page's `settings` item for a configuration page, `'unrestricted'` for a root-only page, or `'skip'` explicitly; nothing is inferred from the route name. Nested pages inherit it; an omitted value on a first page defaults to `'unrestricted'` for protected pages and `'skip'` otherwise, with a development warning. Use `useCan({ resource, action })` for button visibility and server-computed eligibility for record-sensitive actions. Keep pending/failed checks closed and refresh after permission changes. Client visibility does not enforce the API. The authorization Skill’s `references/client-development.md` includes the component, relation controls and settings lifecycle; all required APIs are bundled in that Skill rather than external package documentation.
26
26
 
27
- The permission workspace edits page grants, business actions with their data scopes, and settings items. Field and relation capabilities are code-owned. A new field or workflow must update its declaration and enforcement; it is not an administrator entering arbitrary database grants. Follow the dedicated Skill for custom record access, multi-table transactions, relation targets, protected assignments and last-administrator checks.
27
+ The permission workspace edits page grants, business actions with their data scopes, and settings items. Build it with the permission UI Registry, selecting and composing only the actual application capabilities that administrators need to configure. Registry supplies no fixed business catalog: use application-owned composition, such as `client/pages/settings/permission-workspace.ts`, and do not directly render every capability returned by options. Use `permissionWorkspaceSelection` for explicit resource/action opt-in. A setting also requires its real registered configuration page and a matching server action; omit empty categories. Do not add a default System and tools category or unused settings controls. Show arbitrary operations as individually labeled draft checkboxes, their descriptions and named data ranges; keep Save in the host form and preserve undisplayed grants. Field and relation capabilities are code-owned. A new field or workflow must update its declaration and enforcement; it is not an administrator entering arbitrary database grants. Follow the dedicated Skill for custom record access, multi-table transactions, relation targets, protected assignments and last-administrator checks.
28
+
29
+ Before accepting a new application's permission workspace, write an operation-to-permission map for every business action: the user-visible entry or button, request endpoint, stable composite resource/action, server enforcement point, affected existing records and named data scopes. Group internal writes only when they form one indivisible user operation; split independently assignable actions such as approve, reject and return even if they share a page or collection. Use the same action for the same operation on list and detail pages. Compare the map with the rendered editor: every configurable row must correspond to an implemented operation, and every independently configurable operation must have a row. A display label or Registry selection cannot repair a bundled server permission.
30
+
31
+ Treat that map as an acceptance gate, not merely design notes. For each action, verify with an ordinary user that its grant enables the matching button and direct request, that an unrelated sibling remains denied, and that page access alone and action access alone do not bypass the other boundary. Check existing-record and related-record scopes, state eligibility, and create actions without a meaningless new-record range selector. Record any intentionally combined operations and why they must be assigned together. Do not declare the permission design complete from a screenshot of the editor alone.
28
32
 
29
33
  ## Verify and explain
30
34
 
@@ -41,3 +45,7 @@ Default to named users selected through User management → Assign roles. Do not
41
45
  A global default is supported only when the user explicitly requests it and the application delivers an authorized administration control to inspect its recipient population, change the default role and revoke that assignment. User access details must distinguish direct roles from inherited roles and link to the source. If those controls are unavailable, explain the limitation and use explicit user assignments instead. Never invent a configuration flag, seed-only setting or undocumented SQL instruction as the administrator's normal adjustment interface.
42
46
 
43
47
  Retain and run `pnpm exec vitest run tests/logic/authorization-assignment-safety.test.ts` from the template. The test starts the real application on an isolated database, including registered migrations/seeds, and checks actual global assignments and member grants rather than searching source literals. When adding a genuinely requested global default, extend the expected baseline narrowly only after delivering the management UI and testing its visibility, update, revocation and authorization. Record that deliberate exception with the feature's tests; never delete or skip the guard. This test covers initialized state, not every later administrative write or custom subject resolver; also test effective access and direct API denials with ordinary identities.
48
+
49
+ For page-access presentation, compose `section.navigation` from the application's complete runtime menu hierarchy and its existing navigation transforms, without filtering the catalog by the signed-in editor's own visible menus. Reference stable page row ids, deduplicate inherited/shared page grants, retain independently protected non-menu pages, and keep flat menus at one level. Structural groups only expand/collapse; actual parent pages and child pages have independent checkboxes. Searching retains ancestor context and never changes grants. See the permission-editor Registry contract for its optional navigation nodes and translated disclosure labels. The page-access tree contains business pages only. Group all actual system-settings pages and operations, including user management and business configuration, under Configuration permissions; preserve original row ids and grants, avoid duplicate page controls or category-jump placeholders, and explain the boundary in section descriptions.
50
+
51
+ Keep action tiles at the same column width before and after selection. Named ranges stack within the owning tile; show each distinct empty-range explanation visibly once rather than relying only on tooltips. Label an empty range Use default rules and explain that this role adds no records, while effective access also depends on other roles and default, sharing and restriction rules. Preserve native custom filters and separate parameter/help controls. Declare only the collections and writes the operation actually needs; do not attach every collection to every action. Application selection can explicitly move individual supported composite actions into Configuration permissions when their real application-owned configuration pages exist. Preserve resource/action IDs, scope values and hidden grants, and resolve native filter definitions by both resource and action when one composite appears in multiple categories. Removing declared scopes requires a separate compatibility change for stored grants and rules; never silently replace removed or empty values with All records.
@@ -30,14 +30,14 @@ An agent's runs on one subject: a compact side-column log with a live timer, an
30
30
 
31
31
  ### agent-composer
32
32
 
33
- The message box for talking to an agent: page-context chips inside it, files to send (attach, paste, drop, uploaded before sending), Enter to send, Stop while the agent works, and a toolbar slot for a picker such as the agent's. Use it wherever a person writes to an agent. Presentational: context chips, drafts and focus come from the agents plugin's chat hooks (@nocobase/app-plugin-agents/client/chat) through optional props.
33
+ The message box for talking to an agent: page-context chips inside it (each can open a preview of what it carries), files to send (attach, paste, drop, uploaded before sending), Enter to send, Stop while the agent works, and a toolbar slot for a picker such as the agent's. Use it wherever a person writes to an agent. Presentational: context chips, drafts and focus come from the agents plugin's chat hooks (@nocobase/app-plugin-agents/client/chat) through optional props.
34
34
 
35
35
  - Kind: component
36
36
  - Install: `yes n | pnpm exec shadcn add @nocobase/agent-composer`
37
37
  - Installs to: `client/components/agent-composer.tsx`
38
38
  - Plugin dependencies: `@nocobase/app-plugin-agents`
39
39
  - Example: `@nocobase/agent-composer-demo` (`pnpm exec shadcn view @nocobase/agent-composer-demo`)
40
- - After installing: Pass onSend (return true, or a promise of true, once the message is taken), and optionally running, onStop, toolbar and notice; pass attachments (upload, and optionally discard and registerAdd; useChatAttachments of @nocobase/app-plugin-agents/client/chat uploads to the plugin) to send files; wire context (chips from contextChips and buildPageContext of @nocobase/app-plugin-agents/client/chat), draft and registerFocus from the chat panel when it sits in one. Every word comes from the labels prop, English by default.
40
+ - After installing: Pass onSend (return true, or a promise of true, once the message is taken), and optionally running, onStop, toolbar and notice; pass attachments (upload, and optionally discard and registerAdd; useChatAttachments of @nocobase/app-plugin-agents/client/chat uploads to the plugin) to send files; wire context (chips from contextChips and buildPageContext of @nocobase/app-plugin-agents/client/chat, and optionally inspect, which makes each chip open a preview of what it carries), draft and registerFocus from the chat panel when it sits in one. Every word comes from the labels prop, English by default.
41
41
 
42
42
  ### agent-picker
43
43
 
@@ -52,7 +52,7 @@ The one way to pick an agent: a trigger with the agent's avatar (availability do
52
52
 
53
53
  ### agent-chat
54
54
 
55
- The agents' chat: a side panel beside the content area with the conversation, live steps, a composer with page-context chips and files to send (attach, paste, drop), the agent picker, the history, a full-page conversation view, and header, floating and Ask agent launchers. Use it to let people talk to agents from any page. Wired to the headless hooks of @nocobase/app-plugin-agents/client/chat.
55
+ The agents' chat: a side panel beside the content area, switching between the online agent and runner agents when both are configured, with the conversation, live steps, a composer with page-context chips and files to send (attach, paste, drop), the agent picker, the history, a full-page conversation view, and header, floating and Ask agent launchers. Use it to let people talk to agents from any page. Wired to the headless hooks of @nocobase/app-plugin-agents/client/chat.
56
56
 
57
57
  - Kind: block
58
58
  - Install: `yes n | pnpm exec shadcn add @nocobase/agent-chat`
@@ -60,7 +60,7 @@ The agents' chat: a side panel beside the content area with the conversation, li
60
60
  - Plugin dependencies: `@nocobase/app-plugin-agents`
61
61
  - Also installs: `@nocobase/markdown-view`, `@nocobase/agent-run-history`, `@nocobase/agent-composer`, `@nocobase/agent-picker`, `@nocobase/attachment-list`
62
62
  - Example: `@nocobase/agent-chat-demo` (`pnpm exec shadcn view @nocobase/agent-chat-demo`)
63
- - After installing: Requires the agents plugin (and the file plugin on the server for files sent in chat): wrap the routes in ChatProvider from @nocobase/app-plugin-agents/client/chat (pass conversationPath when ChatConversationPage has a route such as /chat/:conversationId), optionally with ChatExtensionsContext for cards among the messages. Render ChatPanel as a sibling of <main> inside a `relative flex` row, ChatHeaderButton in the header and ChatFloatingButton anywhere; add the plugin's chatLinkRoutes(base) for links that open the panel; spread locales/ into client/locales/.
63
+ - After installing: Requires the agents plugin (and the file plugin on the server for files sent in chat): wrap the routes in ChatProvider from @nocobase/app-plugin-agents/client/chat (pass memoryScope, the signed-in person's id, so a new conversation starts with the agent they used last; pass conversationPath when ChatConversationPage has a route such as /chat/:conversationId), optionally with ChatExtensionsContext for cards among the messages. Render ChatPanel as a sibling of <main> inside a `relative flex` row, ChatHeaderButton in the header and ChatFloatingButton anywhere; add the plugin's chatLinkRoutes(base) for links that open the panel; spread locales/ into client/locales/.
64
64
 
65
65
  ## Approval
66
66
 
@@ -136,14 +136,15 @@ The /device page where a signed-in person approves or denies the sign-in of a CL
136
136
 
137
137
  ### permission-editor
138
138
 
139
- A compact permission workspace with category navigation, individual action checkboxes, scoped data controls and accessible scope help.
139
+ A controlled permission workspace with category navigation, application-owned menu trees, compact action tiles and named data scopes.
140
140
 
141
141
  - Kind: component
142
142
  - Install: `yes n | pnpm exec shadcn add @nocobase/permission-editor`
143
143
  - Installs to: `client/components/permission-editor.tsx`, `client/components/permission-filter.tsx`
144
144
  - Plugin dependencies: none
145
+ - Also installs: `@nocobase/long-text`
145
146
  - Example: `@nocobase/permission-editor-demo` (`pnpm exec shadcn view @nocobase/permission-editor-demo`)
146
- - After installing: Map your permissions to sections of groups of rows; each row has an id, a label, an optional hint, whether it is enabled, and optionally the levels it can reach and the current one. onEnabledChange and onLevelChange report changes by row id. Every word comes through props, English by default. Resource groups render as compact rows with wrapping action checkboxes. Optional row.scopes bind independent scope selectors to their owning action. Actions are configured individually; category names and groups omit authorization counts and bulk selection. Filtering never mutates the draft. Use scope.hint for contextual scope help shown on hover, keyboard focus or tap, and labels.scopeHintFor for the accessible trigger name. Use group.accessOnly for a page with a single access action to show one title checkbox without redundant action text. Provide scope.configuration for parameterized scopes; PermissionFilter edits validated condition drafts and keeps role saving in the host form. Never save customFilter as a bare key: bind its native params.filter object.
147
+ - After installing: The application owns the exposed permission catalog, its business grouping, labels and persistence. Pass sections of groups of rows; the component has no built-in business or system permissions and never discovers or requests them. Preserve caller action order, including non-CRUD operations. Each row shows a checkbox, its title and optional hint; enabled scoped actions show every independently named range directly. onEnabledChange and onLevelChange report only explicit draft edits by stable row or scope id. The host owns loading, validation, Save, conflicts and preservation of grants absent from the visible catalog. Installing a plugin or receiving a capability in options does not opt it into this form: select only actual application features and supported actions in application-owned composition code. Settings require explicit app opt-in, an actual registered configuration page and matching server capability/action together; neither installed plugins nor a catalog entry alone are sufficient. Keep the original category navigation (left-side desktop, horizontal narrow layout), show one category by default and matching categories during global filtering; search and enabled-only filters never change grants. Do not supply a default System and tools section or copy demo permissions into an application. Set group.accessOnly for a page with one access action. Supply scope.configuration for parameterized filters, scope.hint for contextual help, and translated labels including emptyDescription, readOnly and managedPermission. Full-width descriptions use LongText and narrow tile descriptions use LongTextPreview; disabled controls have visible explanations. Existing apps reconcile the component, its LongText and Empty dependencies, application catalog adapter and host bindings through a normal source upgrade. Preserve unknown policies and native filter parameters. For page access, pass section.navigation as application-owned nodes with id, label, optional rowId and children. References use the existing flat row ids; a structural menu group has no grant. Single-level menus stay flat; a parent page and its children use independent checkboxes for staged authorization. Disclosure only changes presentation. Search includes ancestor names and retains their paths; filtering expands matching branches and Clear restores collapse state. The host adapter uses the complete runtime menu tree and its navigation transforms, deduplicates inherited page grants, and retains independent non-menu pages. Supply translated expandGroup and collapseGroup callbacks. Never infer authorization inheritance or grant every child when opening a menu group. All page grants, business actions and settings permissions use Checkbox to edit the host draft. The enabled-only filter also uses Checkbox and changes presentation immediately without editing grants. The page-access tree contains business pages only. Compose every actual system-settings page and operation, including user management and business configuration, under Configuration permissions. Preserve original row ids and grants when reclassifying existing controls, and do not duplicate these entries as page checkboxes or category-jump placeholders. Explain this boundary in the application-supplied section descriptions. Map each independently assignable business operation to its actual UI entry, server request, affected fields and record scopes. Use actual operation labels, reuse a permission across equivalent entry points, and separate steps such as Approve and Reject instead of bundling them behind Manage. Page access, record viewing and lifecycle eligibility are separate; read lists do not require unrelated write permissions. Enforce the matching action and all affected record scopes server-side, including operation-scoped related-record pickers. When splitting existing actions, update backend enforcement, frontend availability and the application selection together and migrate grants and default, sharing and restriction rules without widening scopes or changing history. See the authorization Registry README for the full contract. For Create operations, hide the selector for the newly created record because no existing row can be selected; retain the source catalog and stored hidden policy values. If creation reads an existing related record, keep that related range visible and label its actual purpose. Localize custom-filter field captions by collection while preserving field identifiers and saved conditions. The application adapter decides this presentation from its real operations; the Registry supplies no fixed business fields.
147
148
 
148
149
  ### role-list
149
150
 
@@ -159,14 +160,14 @@ A role administration table built with the standard DataTable: localized column
159
160
 
160
161
  ### default-access-editor
161
162
 
162
- Controlled default data scope rule fields with business-object selection, independent operation scopes and native custom-filter slots. The host supplies current rules and performs authorized writes. Preinstalled in both application templates.
163
+ Controlled default data scope fields grouped by operation, with independently named ranges and native custom-filter slots. The host supplies localized business captions, current rules and authorized writes.
163
164
 
164
165
  - Kind: component
165
166
  - Install: `yes n | pnpm exec shadcn add @nocobase/default-access-editor`
166
167
  - Installs to: `client/components/default-access-editor.tsx`
167
168
  - Plugin dependencies: none
168
169
  - Example: `@nocobase/default-access-editor-demo` (`pnpm exec shadcn view @nocobase/default-access-editor-demo`)
169
- - After installing: Pass localized labels, a stable rule key, resource choices and scope controls. Explain that default data scopes combine with role-granted scopes for users who already hold the operation permission, and that restriction rules still constrain final access. The host loads authorization/defaultAccess and authorization/defaultAccess/options, enforces settings:authorization.default-access read/create/update/delete, and owns draft preservation, custom filters, validation, confirmation and writes. Existing apps reconcile the editor, default-access pages/model/routes, locales and contextual role-form link from the updated template. No existing rule is seeded or rewritten on upgrade. Both templates expose one Permission management sidebar entry with Roles and permissions and Default data scopes tabs, without changing their route ids, URLs, settings guards or stored rules. This navigation organization does not add sharing or restriction editors.
170
+ - After installing: Pass localized labels, a stable rule key, resource choices and scope controls. Explain that default data scopes combine with role-granted scopes for users who already hold the operation permission, and that restriction rules still constrain final access. The host loads authorization/defaultAccess and authorization/defaultAccess/options, enforces settings:authorization.default-access read/create/update/delete, and owns draft preservation, custom filters, validation, confirmation and writes. Existing apps reconcile the editor, default-access pages/model/routes, locales from the updated template. No existing rule is seeded or rewritten on upgrade. Both templates expose one Permission management sidebar entry with Roles and permissions and Default data scopes tabs, without changing their route ids, URLs, settings guards or stored rules. This navigation organization does not add sharing or restriction editors. Keep global default data scopes in the Permission management tabs and omit the contextual shortcut from role editors to avoid confusing global rules with the current role’s scopes. Group scopes with the same stable actionId under one operation heading; each scope retains its independent id, selection, filter and error. The application shares scope captions with its role permission adapter rather than exposing collection identifiers, and preserves original resource/action/scope keys and stored rules.
170
171
 
171
172
  ## Data display
172
173
 
@@ -238,9 +238,14 @@ async function shoot(options) {
238
238
  }
239
239
  const locale = shot.locale ?? spec.locale;
240
240
  if (locale) {
241
- await context.addInitScript((value) => {
242
- window.localStorage.setItem('nocobase.locale', value);
243
- }, locale);
241
+ const basePath = new URL(base).pathname.replace(/^\/+|\/+$/gu, '');
242
+ const appBase = basePath ? `/${basePath}/` : '/';
243
+ await context.addInitScript(
244
+ ({ value, key }) => {
245
+ window.localStorage.setItem(key, value);
246
+ },
247
+ { value: locale, key: `nocobase.locale:${appBase}` },
248
+ );
244
249
  }
245
250
  // Save the color mode and preset the way the Appearance popover does, under keys scoped to the deployment base
246
251
  // path (client/theme/theme-preferences.ts), so a default in config.yml does not override the requested look.
@@ -35,7 +35,7 @@ It defaults to `en-US`, and `APP_DEFAULT_LOCALE` overrides it. A value the appli
35
35
 
36
36
  The browser resolves its startup language as: the visitor's saved choice in `localStorage` → `i18n.defaultLocale` → `en-US`. The browser's own `navigator.language` is deliberately not consulted — the language an application starts in is the product's decision, not the visitor's operating system's. A default is never written to storage as though the visitor had chosen it, so changing configuration still reaches anyone who has not picked a language. Refresh after changing it.
37
37
 
38
- Switching language in the interface remains a user-level choice: it writes `localStorage` and the server session, and never changes `defaultLocale`.
38
+ Switching language in the interface remains a user-level choice: it writes `localStorage` and the server session, and never changes `defaultLocale`. Browser preferences and default language-session cookie names are scoped to the application's full public mount path. Existing applications must merge their copied session and root-path configuration as well as update dependencies; follow [application cookie isolation](../../nocobase-app-upgrade/references/application-cookie-isolation.md).
39
39
 
40
40
  ## What an untranslated key falls back to
41
41
 
@@ -18,7 +18,13 @@ This applies pending migrations and then pending seeds for `database.default`, i
18
18
 
19
19
  Seeds are the second half of that run, so the structure a seed writes into must already exist from an earlier migration. Keep seed data fixed and reproducible — no current timestamps or random values in identifying fields — and never let a repeat run silently overwrite data a user has edited.
20
20
 
21
- Sample data is not required data. Put it in the same `seeds` directory as `defineSeed({ name, sample: true, run })`, or, when it has to go through plugins' services, register it on `sampleDataToken` from `@nocobase/app-server/sample-data` in a service provider's `boot()`; `.agents/skills/nocobase-db/SKILL.md` section 2 has the details. Both load only while the run installs the connection — it held no migration or seed history, or `db reset` rebuilt it — with `app.sampleData` set (`APP_SAMPLE_DATA=true`); otherwise they are recorded as skipped. The seeds entry of a run reports `freshInstall` and, when it skipped any, `skippedSamples`. `pnpm nocobase db sample` runs what was skipped, in development only: a built `dist/` refuses it.
21
+ ## Sample data and demo systems
22
+
23
+ Sample data is optional example content for exploring or developing an application, such as fictional customers and related orders. It does not enable read-only protection, recurring resets, demo-account management or external-call simulation. Required system records still belong in ordinary seeds.
24
+
25
+ Use `@nocobase/app-plugin-demo-mode` when the requirement is a dedicated demo system with a separate database and storage, repeatable data lifecycle, visitor write policies and optional Agent or external-call simulation. Follow that installed plugin's Skill for its application-owned dataset and full-business cleanup contract. A request for a few example records does not require this plugin. Both mechanisms can use the same fictional story or application fixture helpers, but keep their execution and cleanup lifecycles separate; do not register the same data-generation routine in both paths and run it twice.
26
+
27
+ Put sample data in the same `seeds` directory as `defineSeed({ name, sample: true, run })`, or, when it has to go through plugins' services, register it on `sampleDataToken` from `@nocobase/app-server/sample-data` in a service provider's `boot()`; `.agents/skills/nocobase-db/SKILL.md` section 2 has the details. Both load only while the run installs the connection — it held no migration or seed history, or `db reset` rebuilt it — with `app.sampleData` set (`APP_SAMPLE_DATA=true`); otherwise they are recorded as skipped. The seeds entry of a run reports `freshInstall` and, when it skipped any, `skippedSamples`. `pnpm nocobase db sample` runs what was skipped, in development only: a built `dist/` refuses it.
22
28
 
23
29
  ## Multiple connections
24
30
 
@@ -92,18 +92,24 @@ Before finishing, map each used capability to its working management entry, rout
92
92
 
93
93
  The templates preinstall `#components/role-list` from the UI Registry. Keep role administration as a compact content list: body-sized names, muted identifiers and small protected/custom labels, with identifiers below names only in narrow containers. Reuse `RoleList` with localized labels and edit destinations; keep loading, empty/error states, search, sorting and authorization in the owning page. Do not turn each role into a heading or a padded card. For an existing application, reconcile the component together with its role-page integration through the template upgrade workflow, preserving application-specific fields and behavior.
94
94
 
95
- Organize the role catalog around page access, business operations, users/accounts and system/tools. A page grant opens a page without granting its data or operations. Plugins register meaningful titles and action descriptions and explicitly place administrative capabilities; keep resource/action IDs stable when changing labels or grouping. User account actions are reviewed individually in information, security and role-assignment groups. Category navigation shows names only; omit group Select all controls and authorization counts. Do not add repetitive help disclosures to each checkbox. An empty composite data range grants no additional record access; default access, sharing and restriction rules may still apply, so do not label it as an effective denial. Show the names and selected values of multiple ranges in their collapsed summary.
95
+ The application owns its role editor's visible catalog. Use the permission UI Registry to compose only the actual pages, business operations and settings that administrators need to configure, with application-defined categories and groups. Treat server options as available capabilities, not an instruction to show everything; installing a plugin does not automatically expose its configuration permissions. Adapt `client/pages/settings/permission-workspace.ts` as the business is built. Use `permissionWorkspaceSelection` for explicit resource/action opt-in. A setting also requires its real registered configuration page and a matching server action; omit empty categories. Do not add a default System and tools category or copy demo catalogs. Preserve stable resource/action IDs. Display one left-side checkbox per action, its name and description, and every independently named data range directly within their owning action tile. Keep the original category navigation; preserve caller ordering rather than forcing CRUD columns. No group Select all controls or authorization counts. Changes remain a draft until the host Save. An empty composite range grants no additional records from this role; default access, sharing and restrictions still participate in final access. Preserve hidden grants and unrecognized policy parameters.
96
+
97
+ Match business permission rows to independently assignable operations that actually exist in the application. Keep titles aligned with operation buttons, explain their effects and expose only the ranges they use. Page access, record viewing and lifecycle transitions remain separate; read lists do not require unrelated write permissions. Reuse an action across equivalent entry points, while independently assignable steps such as Approve and Reject have distinct server checks. State, actor and concurrency guards still apply. Splitting an existing bundled action requires corresponding frontend checks and a compatible migration of grants and action-specific rules, preserving ranges and historical data. See the authorization Skill's client-development reference for the full contract.
98
+
99
+ For Create actions, use `hiddenActionScopes` to omit a selector for the new record while retaining its registered and stored scope. Keep selectors for existing related records, label them with `actionScopeTitles`, and supply localized filter captions by collection through `filterFieldTitles` values or translation keys. The template adapter makes these presentation choices without changing authorization IDs, field paths or saved filters.
96
100
 
97
101
  ## Default data scope administration
98
102
 
99
103
  When the application exposes role management and uses the Default Access plugin, include the template's `/default-access` system settings contribution and its create/details child routes. The default template supplies this in `client/pages/settings/routes.ts`; Examples registers it under System management. Show one Permission management sidebar entry with Roles and permissions and Default data scopes as URL-backed tabs, leaving Users as a sibling. The application navigation transform selects the first readable tab and represents both existing routes with one entry. Keep existing paths, route ids and authorization requirements; do not add placeholder entries for rule editors the application does not expose. The list and form call `authorization/defaultAccess` and `/options`, with the existing `settings:authorization.default-access` read/create/update/delete requirements. Read permission allows full inspection; only create/update/delete permit writes. Use the Registry `default-access-editor` for the controlled fields and `PermissionFilter` for native custom conditions. Explain that baseline ranges apply to identities already holding an operation and remain subject to restrictions. Never equate a baseline rule with granting the operation itself.
100
104
 
101
- On template upgrades reconcile the editor, list/form/model, route contribution, contextual role-form link, filter-label helper and locales. Preserve stored rule keys, resources, actions, record IDs and filter parameters; do not seed, rewrite or select All records during browsing or upgrades. Unknown metadata stays visible and read-only. The existing API has no atomic revision precondition, so re-read the target before replacing actions or deleting and refuse a detected stale edit.
105
+ On template upgrades reconcile the editor, list/form/model, route contribution, filter-label helper and locales. Preserve stored rule keys, resources, actions, record IDs and filter parameters; do not seed, rewrite or select All records during browsing or upgrades. Unknown metadata stays visible and read-only. The existing API has no atomic revision precondition, so re-read the target before replacing actions or deleting and refuse a detected stale edit.
102
106
 
103
107
  ## Role assignment visibility
104
108
 
105
109
  Every application-owned role assignment created during building must be inspectable and adjustable in administration. Prefer explicit per-user assignments through the prepared User management page. Global defaults require an explicit user requirement and a protected control to inspect/change/remove the default, plus inherited-role source visibility in user details. Do not seed an invisible all-authenticated business role or present only direct roles as effective access. See [assignment safety](authorization.md#visible-and-manageable-assignments).
106
110
 
111
+ Keep default data scopes in the Permission management tabs; omit a contextual Manage default data scopes link from the role editor so global rules are not mistaken for the current role’s scopes.
112
+
107
113
  ## Contextual settings navigation
108
114
 
109
115
  Reuse the prepared Users page for role membership rather than creating another member editor. Link with both `roleScope` and `role` (for example `/settings/users?roleScope=app&role=equipment-manager`) and an encoded `returnTo` containing the current application-relative workflow URL, including its filters. The page applies the paired server filters and preserves context across search, details, edits and clearing filters. A single role key without its scope is invalid. Configuration is an explicit member assignment, never an automatic grant based on a URL filter. Display labels from `users/options`, translated through their declared namespace, while retaining unknown keys and unchanged assignment values.
@@ -0,0 +1,55 @@
1
+ # Isolate application cookies on a shared host
2
+
3
+ Applications mounted at different public paths need distinct language-session and authentication cookie names, including when one application is mounted at `/` or beneath another. The defaults use the full public path, preserve case and punctuation, and normalize leading/trailing slashes. Authentication also retains its public-port or standalone-listen-port distinction. An internal proxy path or the last path segment is not an application identity.
4
+
5
+ Updating dependencies alone does not update the template source copied into an existing application. Merge the following edits into each application's source, keeping its unrelated configuration. Apply them in both Default-derived and Examples-derived applications; do not copy one application's live configuration or keys into another.
6
+
7
+ ## Apply the source changes
8
+
9
+ 1. Upgrade the application's matching framework and authentication dependencies to a release containing this fix through the normal template upgrade workflow. `@nocobase/app-server/support` must export `createAppCookieScope` before using the following source. Keep the existing package placement in `dependencies` or `devDependencies`.
10
+ 2. In `server/config/session.ts`, import the shared path functions and add `routing` to the existing defaults callback. Replace only the default cookie name and path; retain the other session options, stores and environment mappings:
11
+
12
+ ```ts
13
+ import {
14
+ createAppCookieScope,
15
+ normalizeBasePath,
16
+ } from '@nocobase/app-server/support';
17
+
18
+ // Inside defineAppConfig, preserving the other defaults:
19
+ defaults: ({ paths, env, routing }) => ({
20
+ // Keep the existing enabled/default/store/lifetime settings here.
21
+ cookie: {
22
+ name: `nocobase_session_${createAppCookieScope(routing.publicBasePath)}`,
23
+ path: normalizeBasePath(routing.publicBasePath) || '/',
24
+ // Keep the existing secure/httpOnly/sameSite and other attributes here.
25
+ },
26
+ }),
27
+ ```
28
+
29
+ 3. In `server/config/app.ts`, preserve an explicit root mount. Replace `normalizeBasePath(routing.publicBasePath || '/main')` with `normalizeBasePath(routing.publicBasePath)`. The runtime already supplies `/main` when no mount path was configured; an empty path means the origin root. Keep the existing name and public API URL derivation.
30
+ 4. Review explicit overrides in the application's deployment configuration and `server/config/auth.ts`. `session.cookie.name/path`, `auth.advanced.cookiePrefix`, `auth.advanced.cookies` and cookie attribute overrides still win over defaults. A fixed old name or shared prefix opts out of automatic isolation: give every overlapping application a unique value, or remove the override to use the new defaults. Do not automatically erase an intentional customization.
31
+ 5. Run the application checks and build, then restart through the normal deployment process:
32
+
33
+ ```bash
34
+ pnpm nocobase config check
35
+ pnpm typecheck
36
+ pnpm lint
37
+ pnpm test
38
+ pnpm build
39
+ ```
40
+
41
+ If merging the template's regression tests, include `tests/logic/session-isolation.test.ts`; it uses the application's own configuration and shared synthetic test keys/storage to test the cookie boundary. Never point it at deployment sessions or databases.
42
+
43
+ ## Expected upgrade behavior
44
+
45
+ Default login cookies change names, so visitors sign in again once. Language preferences in browser storage are also scoped to the application; an old shared preference is ignored and each application initially uses its own default language. The existing browser-to-server synchronization creates the new language session.
46
+
47
+ Old cookies are not read, migrated or proactively deleted. Old server records expire according to their existing policy rather than being revoked in bulk. A rollback can recognize the previous login cookies again. Explicit authentication names that remain unchanged do not require a new login solely because of this fix.
48
+
49
+ ## Verify the deployment
50
+
51
+ Use one browser profile to visit sibling paths, a root application and a child, nested applications, and applications with the same final path segment. Sign in to each, switch their languages independently, refresh a deep route, and sign out of one. The other applications must retain their login and server language. A child without its own cookie must ignore a parent's cookie even though the browser sends it with the request.
52
+
53
+ In the browser's network/storage tools, check that language-session names start with `nocobase_session_` followed by the encoded full path, authentication names include `__` followed by that same scope, and paths match each application's public mount (`/` at the root). For example `/team/crm` uses scope `%2Fteam%2Fcrm`; `/crm` uses `%2Fcrm`. Check sign-out and session clearing delete only that application's names and leave old or sibling cookies intact. Do not copy cookie values into verification reports.
54
+
55
+ No database migration, additional endpoint or request is required. This prevents accidental session reuse between applications; paths on the same origin are not a security boundary against a malicious application.
@@ -1,5 +1,7 @@
1
1
  # Edge cases
2
2
 
3
+ For language and login isolation between applications on one host, merge the copied template configuration as well as the dependency update. Follow [application cookie isolation](application-cookie-isolation.md) for the exact source edits, preserved overrides, one-time login reset and verification steps.
4
+
3
5
  Things that are not ordinary source and do not follow the file-by-file process in `SKILL.md`.
4
6
 
5
7
  ## `package.json`