@nocobase/app-skills 0.1.0-beta.47 → 0.1.0-beta.49
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 +2 -2
- package/skills/nocobase-app-development/SKILL.md +2 -0
- package/skills/nocobase-app-development/references/app-structure.md +4 -0
- package/skills/nocobase-app-development/references/frontend/frontend-dev.md +14 -0
- package/skills/nocobase-app-development/references/frontend/ui-workflow.md +2 -0
- package/skills/nocobase-app-development/references/lifecycle.md +1 -1
- package/skills/nocobase-deployment/SKILL.md +4 -0
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@nocobase/app-skills",
|
|
3
|
-
"version": "0.1.0-beta.
|
|
3
|
+
"version": "0.1.0-beta.49",
|
|
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.
|
|
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.
|
|
@@ -43,6 +43,10 @@ A feature with a page and an API touches five places: a migration for the table,
|
|
|
43
43
|
|
|
44
44
|
Editable module defaults live in `server/config/` and are collected by `defaultAppConfigs` in its `index.ts`; `server/config.ts` loads the configuration file. Each section declares the environment variables that set it in `env` of its `defineAppConfig`, with a `description` and, where it applies, `secret`, `required`, `generate` or `firstStartOnly` in the helper's second argument; `pnpm nocobase config env` lists them all, `pnpm nocobase config variables` describes each, and `pnpm build` writes that description to `dist/variables.json` for whoever deploys the build. `server/config/database.ts` maps `DB_*` onto the main connection and `server/config/users.ts` maps `INITIAL_ADMIN_*` onto the initial administrator. `config.yml` is read as written: a `${NAME}` in it is not expanded. [Services and jobs](services-and-jobs.md#application-code-configuration) shows how a module declares and reads its configuration.
|
|
45
45
|
|
|
46
|
+
### Knowledge indexing
|
|
47
|
+
|
|
48
|
+
`server/config/knowledge.ts` registers the plugin's pure `defineKnowledgeConfig()` factory. Declare server-only instances under `knowledge.indexing` in `config.yml`; `config.example.yml` shows `sqlite-vec` and `pgvector`, private connection/TLS fields and the optional `knowledge.jobs` host configuration selector. Leave the selector omitted to follow the host default. Instance definitions do not enable indexing: the Knowledge global index dialog owns the instance/model selection and explicit all-space rebuild confirmation. Do not put model selection or per-space overrides in deployment YAML, reuse Agents vector collections, or insert literal `${NAME}` placeholders expecting expansion. A custom indexing extension must be passed to both `defineKnowledgeConfig` and `createKnowledgePlugin`.
|
|
49
|
+
|
|
46
50
|
### File storage
|
|
47
51
|
|
|
48
52
|
Configure storage in `server/config/drive.ts`, with serializable overrides in `config.yml`. Keep the default `DriveProvider` and resolve `driveManagerToken` from `@nocobase/app-server/drive`; File Repository uses the same manager. Read `.agents/skills/nocobase-drive/SKILL.md` for the `fs`, `s3`, and `oss` configuration guides, custom driver factories, URL behavior, and release artifact limitations. That Skill ships with `@nocobase/drive` and is synchronized from the installed package.
|
|
@@ -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 |
|
|
@@ -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
|
|
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
|
|
|
@@ -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).
|