@nocobase/app-skills 0.1.0-beta.42 → 0.1.0-beta.43
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 +1 -1
- package/skills/nocobase-app-development/SKILL.md +2 -0
- package/skills/nocobase-app-development/references/authorization.md +8 -0
- package/skills/nocobase-app-development/references/commands.md +1 -1
- package/skills/nocobase-app-development/references/frontend/references/testing.md +2 -0
- package/skills/nocobase-app-development/references/frontend/references/ui-library.md +3 -2
- package/skills/nocobase-app-development/references/system-settings.md +4 -0
- package/skills/nocobase-app-development/references/testing/cli/command.md +3 -5
- package/skills/nocobase-app-development/references/testing.md +6 -0
package/package.json
CHANGED
|
@@ -64,6 +64,8 @@ For notification configuration or sending, follow the notification plugin Skill:
|
|
|
64
64
|
|
|
65
65
|
Install, update and customize plugins, and remove a direct NocoBase package, as [plugins](references/plugins.md) describes: `pnpm nocobase plugin register`, `plugin update` and `package remove` keep the manifest, the lockfile, the composition roots and the synchronized Skills consistent, so never hand-edit only one of them.
|
|
66
66
|
|
|
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
|
+
|
|
67
69
|
## Deliver system administration by default
|
|
68
70
|
|
|
69
71
|
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.
|
|
@@ -33,3 +33,11 @@ Test an ordinary user with no grant, page-only and action-only grants, rows owne
|
|
|
33
33
|
Explain to the user which business decisions were implemented, which settings they can maintain and which changes require development. Use the authorization Skill’s bundled quote/project/delivery workflow as the implementation reference, but do not copy demo credentials, fixed record IDs or reset endpoints into the App.
|
|
34
34
|
|
|
35
35
|
For a custom initial administrator, configure `users.initialAdmin` before the first seed run; see the authentication plugin Skill for its username/password contract. Omitting the node preserves the legacy account. The authentication seed creates the account only in an empty user table, and the authorization seed assigns root using the same configured username. Do not reset credentials at startup.
|
|
36
|
+
|
|
37
|
+
## Visible and manageable assignments
|
|
38
|
+
|
|
39
|
+
Default to named users selected through User management → Assign roles. Do not infer that all signed-in users should inherit a new business role. In particular, never seed a business permission set onto `authenticated:*`, add business grants to the platform member role, or reapply assignments at startup to make a feature accessible. A role editor lists that role's grants; unchecked actions are not denials of grants inherited from other sources. Inspect effective assignments before interpreting a permission test.
|
|
40
|
+
|
|
41
|
+
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
|
+
|
|
43
|
+
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.
|
|
@@ -115,7 +115,7 @@ expect(run.json()).toMatchObject({
|
|
|
115
115
|
|
|
116
116
|
`bindAppCommand()` pins the command to a fixture application, the way the runner would point it at the one it located; `id` is the id the runner would give it, colon-separated, so the document names the command. Pass `loadRuntime` and `createApp` as well to replace the application with a stub. `runAppCommand()` returns what `run()` returned as `result`, what escaped it as `error`, the `exitCode`, the captured `stdout` and `stderr`, and `json()` for the `--json` document. Assert on those rather than on printed text.
|
|
117
117
|
|
|
118
|
-
|
|
118
|
+
For a command that opens a real application, use `createTestAppConfig()` and `bindTestAppCommand()` from the same entry. They isolate its databases and storage; call `config.dispose()` after the command finishes. Follow the [complete database command example](testing/cli/command.md) for schema preparation and cleanup; use the [file-command example](testing/cli/files.md) for temporary output directories. A custom `loadRuntime` replaces the conventional loader and must arrange its own isolation: pass `config.path` as `configPath` and direct runtime storage into the fixture directory itself. The conventional loader runs through Node; a TypeScript application using `.js` import specifiers needs a compatible loader, compiled modules, or explicit imports of its runtime and app factory supplied through `loadRuntime` and `createApp`.
|
|
119
119
|
|
|
120
120
|
## Example
|
|
121
121
|
|
|
@@ -31,6 +31,8 @@ For a page or component that uses application services, start from the [complete
|
|
|
31
31
|
|
|
32
32
|
The template's local Vitest inline rules transform client plugins in any scope, including `@acme/app-plugin-*`, alongside `app-client` and the client test helper. Preserve that scope coverage when changing the configuration so installed plugins share application contexts and service tokens. Keep server and database modules external. The shared React preset handles native router resolution; preserve its package export conditions and router externalization when adjusting local rules.
|
|
33
33
|
|
|
34
|
+
`renderWithApp()` takes an application-relative `route`: use `/orders` for `/main/orders` under a server mounted at `/main`; router links and navigation include that mount path. Its returned `rerender()` preserves providers, translations and component state. Initialization failures remove the helper's runtime configuration immediately without removing configuration supplied by the test.
|
|
35
|
+
|
|
34
36
|
For anything else, start from the test that already sets it up:
|
|
35
37
|
|
|
36
38
|
- **A second language**: pass the `client/locales/index.ts` loader map and switch with `changeLanguage` inside `act`, as the next section shows; `tests/components/primitive-labels.test.tsx` renders in Chinese from the start with `locale: 'zh-CN'`.
|
|
@@ -147,14 +147,15 @@ A compact permission workspace with category navigation, individual action check
|
|
|
147
147
|
|
|
148
148
|
### role-list
|
|
149
149
|
|
|
150
|
-
A
|
|
150
|
+
A role administration table built with the standard DataTable: localized column headers, sortable names and identifiers, protected/custom badges, and pagination. The host supplies authorized rows and edit destinations. Preinstalled in both application templates.
|
|
151
151
|
|
|
152
152
|
- Kind: component
|
|
153
153
|
- Install: `yes n | pnpm exec shadcn add @nocobase/role-list`
|
|
154
154
|
- Installs to: `client/components/role-list.tsx`
|
|
155
155
|
- Plugin dependencies: none
|
|
156
|
+
- Also installs: `@nocobase/data-table`
|
|
156
157
|
- Example: `@nocobase/role-list-demo` (`pnpm exec shadcn view @nocobase/role-list-demo`)
|
|
157
|
-
- After installing: Render inside a React Router
|
|
158
|
+
- After installing: Render inside a React Router and the application i18n provider. Supply roles with key, localized title, edit destination (to) and protected state. Pass localized labels for name, key, type, protected and custom, plus an optional ariaLabel. Uses the shared DataTable for table semantics, sorting and pagination. The host owns loading, empty/error states, filtering and authorization. Existing apps must update the installed role-list component, its data-table dependency and caller labels together.
|
|
158
159
|
|
|
159
160
|
### default-access-editor
|
|
160
161
|
|
|
@@ -93,3 +93,7 @@ Organize the role catalog around page access, business operations, users/account
|
|
|
93
93
|
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.
|
|
94
94
|
|
|
95
95
|
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.
|
|
96
|
+
|
|
97
|
+
## Role assignment visibility
|
|
98
|
+
|
|
99
|
+
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).
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# CLI example: run a command on an isolated application database
|
|
2
2
|
|
|
3
|
-
Use `bindTestAppCommand()` when a command opens the application. It binds the command to the configuration from `createTestAppConfig()`, so the command reads the test's databases. `runAppCommand()` captures the result, exit code and JSON output without spawning the CLI runner.
|
|
3
|
+
Use `bindTestAppCommand()` when a command opens the application. It binds the command to the configuration from `createTestAppConfig()`, so the command reads the test's databases and the conventional runtime uses storage under `config.directory`. `runAppCommand()` captures the result, exit code and JSON output without spawning the CLI runner.
|
|
4
4
|
|
|
5
5
|
For a complete command that works with files and needs no application database, start with [file output, dry runs and failures](files.md).
|
|
6
6
|
|
|
@@ -67,7 +67,7 @@ import {
|
|
|
67
67
|
createTestAppConfig,
|
|
68
68
|
runAppCommand,
|
|
69
69
|
} from '@nocobase/app-testing/cli';
|
|
70
|
-
import { expect, it
|
|
70
|
+
import { expect, it } from 'vitest';
|
|
71
71
|
import CountNotes from '../fixtures/count-notes-command.js';
|
|
72
72
|
import { noteMigrations } from '../helpers/testing-notes.js';
|
|
73
73
|
import packageMetadata from '../../package.json' with { type: 'json' };
|
|
@@ -102,7 +102,6 @@ it.each([0, 2])('counts %i prepared records', async (count) => {
|
|
|
102
102
|
},
|
|
103
103
|
});
|
|
104
104
|
try {
|
|
105
|
-
vi.stubEnv('APP_STORAGE_DIR', path.join(config.directory, 'storage'));
|
|
106
105
|
const database = await config.testDatabases.open({
|
|
107
106
|
migrations: noteMigrations,
|
|
108
107
|
});
|
|
@@ -134,7 +133,6 @@ it.each([0, 2])('counts %i prepared records', async (count) => {
|
|
|
134
133
|
result: { count },
|
|
135
134
|
});
|
|
136
135
|
} finally {
|
|
137
|
-
vi.unstubAllEnvs();
|
|
138
136
|
await config.dispose();
|
|
139
137
|
}
|
|
140
138
|
});
|
|
@@ -144,7 +142,7 @@ The test's preparation step and the command's startup must both know the fixture
|
|
|
144
142
|
|
|
145
143
|
`config.testDatabases.open()` resets and opens the provisioned databases before preparing the row. The returned handle does not own those databases, so `database.destroy()` closes the preparation connections while leaving the row for the command. `config.dispose()` is the owner cleanup: it drops the databases after the command has closed its application. Do not open the preparation handle again after running the command to inspect its writes; opening it resets the schema.
|
|
146
144
|
|
|
147
|
-
|
|
145
|
+
`bindTestAppCommand()` keeps the conventional runtime's storage under the same temporary directory without changing `process.env`; `config.dispose()` removes it after the command closes. A custom `loadRuntime` bypasses that loader and must pass `config.path` as `configPath` and set `env: { APP_STORAGE_DIR: path.join(config.directory, 'storage') }` when calling `resolveStandaloneAppRuntime()`. Run these command cases sequentially because `runAppCommand()` captures process-wide streams. A successful `runAppCommand()` has `exitCode: undefined`, which means zero; normalize it when asserting.
|
|
148
146
|
|
|
149
147
|
## Run and check
|
|
150
148
|
|
|
@@ -238,3 +238,9 @@ Do not delete or rebuild a running development server's cache. For an already co
|
|
|
238
238
|
Application server source supports extensionless relative imports. Keep `module: "ESNext"`, `moduleResolution: "Bundler"`, and `tsc-alias.resolveFullPaths: true` in `tsconfig.server.json`. Development uses `tsx`; production builds run `tsc-alias` after `tsc` to complete ESM paths, before build hooks run. When changing this configuration, verify the compiled output with plain Node and no source files or TypeScript loader.
|
|
239
239
|
|
|
240
240
|
Vite configuration imports the proxy helpers from `@nocobase/app-cli/dev/proxy`. Watcher, proxy, supervisor and build-step unit tests live in `app-cli`; templates verify their composition and Vite integration.
|
|
241
|
+
|
|
242
|
+
## Permission assignment acceptance
|
|
243
|
+
|
|
244
|
+
Run the template's `tests/logic/authorization-assignment-safety.test.ts` after installing the real application migrations/seeds in isolated test storage. Retain it as business features are added: it catches unexpected wildcard role assignments and business grants hidden in the inherited member role. Do not treat a source-code scan as proof of the resulting assignments. See [assignment safety](authorization.md#visible-and-manageable-assignments) for intentional global defaults and the limits of the initialized-state check.
|
|
245
|
+
|
|
246
|
+
For an ordinary identity assigned only the intended business role, enumerate direct and inherited grant sources, confirm visible menus/buttons match effective access, and exercise forbidden direct API requests. Test page-only versus action-only access separately. If a global default is explicitly requested, test its authorized administration control, inherited-role display and revocation while preserving independent direct grants. Never silently assign all authenticated users a role to make an acceptance test pass.
|