@nocobase/app-skills 0.1.0-beta.46 → 0.1.0-beta.48

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.46",
3
+ "version": "0.1.0-beta.48",
4
4
  "description": "Agent Skills for developing, upgrading and deploying NocoBase applications.",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -18,7 +18,7 @@
18
18
  "devDependencies": {
19
19
  "@playwright/test": "^1.62.1",
20
20
  "prettier": "^3.9.6",
21
- "@nocobase/dev-config": "0.1.0-beta.24"
21
+ "@nocobase/dev-config": "0.1.0-beta.25"
22
22
  },
23
23
  "peerDependencies": {
24
24
  "@playwright/test": "^1.62.1",
@@ -17,6 +17,8 @@ Do not use it to develop a published plugin package. Plugin development has its
17
17
 
18
18
  Do not use it to upgrade the template this application was generated from, which is also how the application moves to a newer NocoBase version when the user asks to upgrade NocoBase or its core. That is `.agents/skills/nocobase-app-upgrade/`, which reconciles a newer template release against the application without reverting the user's work.
19
19
 
20
+ Check [browser API compatibility](references/frontend/frontend-dev.md#browser-api-compatibility) for direct calls and third-party integrations. HTTPS-only APIs require capability detection and a clear user-facing explanation when unavailable. UUID generation and copying text must support HTTP; use `createUuid()` and `copyText()` from `@nocobase/app-client`.
21
+
20
22
  ## Before you start
21
23
 
22
24
  Read the application's `AGENTS.md` first for the rules that apply everywhere, and the `.agents/rules/` files its index points to for your task. This Skill's references are the detail behind it. Before running any `pnpm nocobase` command, read [the command line](references/cli.md): it maps tasks to commands and states the flags an agent must not add on its own.
@@ -66,6 +68,14 @@ Install, update and customize plugins, and remove a direct NocoBase package, as
66
68
 
67
69
  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
70
 
71
+ ## Choose sample data or a demo system
72
+
73
+ 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.
74
+
75
+ 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.
76
+
77
+ 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.
78
+
69
79
  ## Deliver system administration by default
70
80
 
71
81
  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.
@@ -34,6 +34,20 @@ Conventions every page follows, each explained in its home:
34
34
  - Toasts with `useToaster()` from `@nocobase/app-client`, never a second `Toaster` (["Toasts" in `references/api.md`](references/api.md#toasts)).
35
35
  - Every user-visible string through a translation key ([`references/i18n.md`](references/i18n.md)).
36
36
 
37
+ ## Browser API compatibility
38
+
39
+ Check browser support and secure-context requirements before choosing a browser API, including APIs called by third-party libraries. HTTPS-only APIs are allowed when a feature needs them: detect availability and permission failures, and show a localized explanation of the requirement and how the user can proceed. Keep unrelated actions working. Do not silently do nothing or show a success message when an API is unavailable. A LAN IP served over HTTP is not a secure context, while localhost is treated as trustworthy, so test the unavailable state instead of relying on localhost alone.
40
+
41
+ UUID generation and copying text must work on ordinary HTTP, including LAN IP access. Use the public `createUuid()` and `copyText()` utilities from `@nocobase/app-client` rather than duplicating browser-specific implementations in pages. `createUuid()` returns a cryptographically random UUID v4 using `crypto.getRandomValues`, with the standard version, variant and encoding; it does not require `crypto.randomUUID`. Server-side `node:crypto` is unaffected.
42
+
43
+ ### Copy and clipboard actions
44
+
45
+ Call `copyText(text)` directly from the user's click handler and await its boolean result. It uses the [Clipboard API](https://developer.mozilla.org/en-US/docs/Web/API/Clipboard/writeText) when available and falls back to selection-based copying on HTTP or after a rejected write. It returns `false` when programmatic copying is refused or unsupported. Only show a copied confirmation when it returns `true`; on `false`, present the exact text in a selectable field with localized manual-copy instructions. Do not use optional chaining on `navigator.clipboard` that silently skips copying.
46
+
47
+ For a dialog or other focus trap, pass `copyText(text, { container: dialogElement })` when the trigger does not take focus. Otherwise the helper selects the nearest dialog containing the active element, or the document body. Its temporary field is removed and the previous focus and selection are restored. The HTTP fallback uses the [deprecated `document.execCommand('copy')` compatibility mechanism](https://developer.mozilla.org/en-US/docs/Web/API/Document/execCommand); browser policy can still reject it, so keep the manual-copy path.
48
+
49
+ Verify UUID generation and copy actions on a non-secure HTTP origin where `window.isSecureContext` is `false`, including missing clipboard APIs, permission denial and copying from a dialog. Verify copied content by pasting into a normal input, including multiline and non-ASCII text; do not rely only on another secure-context-only API such as `navigator.clipboard.readText()`. For other HTTPS-only features, test the unavailable/denied state and its user-facing explanation as well as the supported path. Report browser checks that could not be performed.
50
+
37
51
  ## Look up by task
38
52
 
39
53
  | Task | Read |
@@ -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
 
@@ -8,6 +8,8 @@ This is the entry point for the application's frontend work: read it before writ
8
8
 
9
9
  What the interface should look like is in [`ui-guidelines.md`](ui-guidelines.md); how to write the code is in [`frontend-dev.md`](frontend-dev.md). Paths in this document are relative to its own directory: [`ui-guidelines.md`](ui-guidelines.md) and [`frontend-dev.md`](frontend-dev.md) sit beside it, the topic references are under `references/`, the record templates and reviewer prompts are under `templates/`, and the screenshot tool is under `scripts/`.
10
10
 
11
+ Every workflow follows [browser API compatibility](frontend-dev.md#browser-api-compatibility): explain unavailable HTTPS-only capabilities to users, and verify that UUID generation and copy actions work on ordinary HTTP through the shared `@nocobase/app-client` utilities.
12
+
11
13
  ## Choosing a workflow
12
14
 
13
15
  Decide before you start, and say in one sentence in your reply which workflow you are following and why.
@@ -399,7 +399,7 @@ return view.available.map((transition) => (
399
399
 
400
400
  Render the buttons from `view.available`, never from a hard-coded state check, so the page and the server use the same judgement. Translate titles and blocker messages by their stable `name` and `code`, as every user-visible string goes through a translation key. `fire` sends a fresh `requestId` and the version on screen; on `CONFLICT` tell the person the record changed and reload rather than retrying. On `INVALID_INPUT`, mark the fields in `error.problems`. The hook refreshes every 4 seconds by default; `refreshMs` changes it. Follow [the frontend workflow](frontend/ui-workflow.md) for the page itself.
401
401
 
402
- For browser request IDs, prefer the built-in lifecycle client, which already handles environments without `crypto.randomUUID()`. Custom submissions and parameter saves must not call it unconditionally: it requires a secure context and can be unavailable on HTTP test hosts. Use a shared helper that falls back to `crypto.getRandomValues(new Uint8Array(16))`, encoded as hex, or an existing HTTP-compatible ID utility. Generate one key per logical operation and reuse it with the same payload for transport retries; changed input or a new decision needs a new key. Verify submission with `randomUUID` unavailable, not only on localhost or HTTPS.
402
+ For browser request IDs, prefer the built-in lifecycle client, which already handles environments without `crypto.randomUUID()`. Custom submissions and parameter saves follow [browser API compatibility](frontend/frontend-dev.md#browser-api-compatibility), including regression coverage with `randomUUID` unavailable. Generate one key per logical operation and reuse it with the same payload for transport retries; changed input or a new decision needs a new key.
403
403
 
404
404
  ## 6. Tests
405
405
 
@@ -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
 
@@ -119,6 +119,10 @@ Bind-mount the complete runtime configuration read-only at `/app/config.yml` and
119
119
 
120
120
  ## Verify the deployed application
121
121
 
122
+ Use the intended public origin for browser checks, including its scheme, host and base path. Follow [browser API compatibility](../nocobase-app-development/references/frontend/frontend-dev.md#browser-api-compatibility): UUID generation and copying text must work on ordinary HTTP, while other HTTPS-only capabilities must explain their requirements to users when unavailable. Verify those HTTP-compatible actions and unavailable-feature messages on an origin where `window.isSecureContext` is `false`; localhost and HTTPS can mask incompatibilities. Exercise actions through completion and inspect browser errors; a loaded page or healthy server is insufficient.
123
+
124
+ When the application offers copy buttons, include [copy and clipboard verification](../nocobase-app-development/references/frontend/frontend-dev.md#copy-and-clipboard-actions): copy from a representative page or dialog and paste into a normal input on HTTP. A success toast alone is not evidence that the clipboard changed.
125
+
122
126
  Collect evidence for each item:
123
127
 
124
128
  1. The process or container reports ready. The application answers `GET <APP_BASE_PATH>/api/healthz` with a JSON object whose `ok` is `true` (alongside the app name and base path).