@nocobase/app-skills 0.1.0-beta.28 → 0.1.0-beta.30
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 +26 -17
- package/skills/nocobase-app-development/references/cli.md +3 -2
- package/skills/nocobase-app-development/references/frontend/references/styling.md +2 -0
- package/skills/nocobase-app-development/references/frontend/references/ui-library.md +25 -0
- package/skills/nocobase-app-development/references/lifecycle.md +10 -0
- package/skills/nocobase-deployment/SKILL.md +2 -0
package/package.json
CHANGED
|
@@ -91,23 +91,24 @@ The handbook's "Look up by task" table routes each frontend task to the sections
|
|
|
91
91
|
|
|
92
92
|
Read the page for the task in front of you. Do not read all of them.
|
|
93
93
|
|
|
94
|
-
| Task | Read
|
|
95
|
-
| ---------------------------------------------------------------------------------------------------------------------- |
|
|
96
|
-
| Anything under `client/`: pages, routes, components, styling, forms, API calls, copy, frontend tests | [frontend workflow](references/frontend/ui-workflow.md), which routes to the [frontend handbook](references/frontend/frontend-dev.md), the theme reference or the worked example
|
|
97
|
-
| Add an API endpoint, a webhook, or a callback; authenticate and authorize it | [server routes](references/server-routes.md)
|
|
98
|
-
| Name an endpoint, shape its response or errors, validate its input, paginate a list, document it in the API document | [HTTP API design](references/http-api.md)
|
|
99
|
-
| Query or write data, resolve the database, work with transactions | [database and data access](references/database-and-data.md)
|
|
100
|
-
| Create a table, alter a column, add an index, write required initial data | [migrations and seeds](references/migrations.md)
|
|
101
|
-
| Switch the database, register a dialect, add a second connection | [database connections](references/database-connections.md)
|
|
102
|
-
| Translate server-produced text, add a language, set the default language | [internationalization](references/i18n.md)
|
|
103
|
-
| Departments, positions or another organisation dimension that permission sets are assigned to | [organisation dimension](references/organization.md)
|
|
104
|
-
| Design who gets what across departments, heads and cross-department work | [organisation permission design](references/organization/permission-design.md)
|
|
105
|
-
| Add a reusable service, share it across routes, run background or scheduled work | [services and jobs](references/services-and-jobs.md)
|
|
106
|
-
| A record that moves through stages defined in code: approvals, tickets, orders, timeouts, effects after a state change | [record lifecycles](references/lifecycle.md)
|
|
107
|
-
|
|
|
108
|
-
|
|
|
109
|
-
|
|
|
110
|
-
|
|
|
94
|
+
| Task | Read |
|
|
95
|
+
| ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
96
|
+
| Anything under `client/`: pages, routes, components, styling, forms, API calls, copy, frontend tests | [frontend workflow](references/frontend/ui-workflow.md), which routes to the [frontend handbook](references/frontend/frontend-dev.md), the theme reference or the worked example |
|
|
97
|
+
| Add an API endpoint, a webhook, or a callback; authenticate and authorize it | [server routes](references/server-routes.md) |
|
|
98
|
+
| Name an endpoint, shape its response or errors, validate its input, paginate a list, document it in the API document | [HTTP API design](references/http-api.md) |
|
|
99
|
+
| Query or write data, resolve the database, work with transactions | [database and data access](references/database-and-data.md) |
|
|
100
|
+
| Create a table, alter a column, add an index, write required initial data | [migrations and seeds](references/migrations.md) |
|
|
101
|
+
| Switch the database, register a dialect, add a second connection | [database connections](references/database-connections.md) |
|
|
102
|
+
| Translate server-produced text, add a language, set the default language | [internationalization](references/i18n.md) |
|
|
103
|
+
| Departments, positions or another organisation dimension that permission sets are assigned to | [organisation dimension](references/organization.md) |
|
|
104
|
+
| Design who gets what across departments, heads and cross-department work | [organisation permission design](references/organization/permission-design.md) |
|
|
105
|
+
| Add a reusable service, share it across routes, run background or scheduled work | [services and jobs](references/services-and-jobs.md) |
|
|
106
|
+
| A record that moves through stages defined in code: approvals, tickets, orders, timeouts, effects after a state change | [record lifecycles](references/lifecycle.md) |
|
|
107
|
+
| Flowcharts, process diagrams or lifecycle state diagrams | Use UI Library `@nocobase/flow-diagram` for generic graphs and `@nocobase/lifecycle-diagram` for lifecycle descriptions; see [diagram guidance](references/lifecycle.md#draw-an-interactive-lifecycle-diagram) and the [UI catalog](references/frontend/references/ui-library.md#diagrams). Preserve their application theme tokens. |
|
|
108
|
+
| Write server and migration tests, choose a test layer, verify before finishing | [testing and verification](references/testing.md) |
|
|
109
|
+
| Run a CLI command: configure, migrate, manage plugins, read the data model | [the command line](references/cli.md) |
|
|
110
|
+
| Add or change an application command under `cli/commands/` | [adding an application command](references/commands.md) |
|
|
111
|
+
| Understand behavior inherited from an official application template | [template variants](references/template-variants.md) |
|
|
111
112
|
|
|
112
113
|
A feature with a page and an API usually needs migrations, server routes, and a frontend change that follows the frontend workflow.
|
|
113
114
|
|
|
@@ -183,6 +184,14 @@ These cause real damage and appear in every reference:
|
|
|
183
184
|
- **Tests live in `tests/`,** never beside the source; browser tests against a running application go in `tests/playwright/`.
|
|
184
185
|
- **Remove direct NocoBase packages with `package remove` after reviewing their usage.** Do not hand-delete only the manifest entry or leave synchronized Skills and plugin registrations behind.
|
|
185
186
|
|
|
187
|
+
## Application access URLs
|
|
188
|
+
|
|
189
|
+
When reporting or opening this application's address, use the `Local:` URL printed by `pnpm dev`, including the application base path. In normal full-stack development, the Hono server proxies Vite: the user-facing entry uses the server port (`APP_SERVER_PORT`, default 13000), while Vite's port (normally 5173) serves the frontend development process. A response from Vite alone does not verify the application entry.
|
|
190
|
+
|
|
191
|
+
For an existing run without available startup output, identify its process and working directory, confirm the actual server listening port and configured base path, and check that URL before sharing it. Occupied ports advance automatically, so do not assume defaults. Report when the run belongs to another checkout. Use a host reachable by the user; `localhost` refers to the machine where the browser runs.
|
|
192
|
+
|
|
193
|
+
With `PROXY_TARGET_URL`, the local Hono server is skipped and Vite becomes the local application entry. Use the printed `Local:` URL in this mode too; `APP_SERVER_PORT` selects its local port (default 5173). See the remote backend development guidance below.
|
|
194
|
+
|
|
186
195
|
## Development file watching
|
|
187
196
|
|
|
188
197
|
`pnpm dev` checks native file watching before starting its children. If watcher resources are exhausted or native events are unavailable, it uses polling for client and server hot updates and disables agent annotations for that run, with a warning. An explicit `CHOKIDAR_USEPOLLING=true` selects the same mode. Configuration files use stat polling so atomic saves and newly created files restart the server without native directory watchers.
|
|
@@ -34,12 +34,13 @@ Write `pnpm nocobase`, not a bare `nocobase`: a machine may have an unrelated gl
|
|
|
34
34
|
| Refresh `.agents/skills/` after an install or upgrade | `pnpm nocobase skills sync` |
|
|
35
35
|
| Build for another platform, or re-check an existing `dist/` | `pnpm build --target <platform>`; `pnpm nocobase dist retarget`, `dist check` |
|
|
36
36
|
| Give the application a command line of its own, for people and agents | declare `nocobase.cli` in `package.json`, then `pnpm nocobase cli link`; see below |
|
|
37
|
-
| Pack that CLI, or the agent runner, for the application to serve | `pnpm nocobase cli build`, `pnpm nocobase cli build --runner`
|
|
37
|
+
| Pack that CLI, or the agent runner, for the application to serve | `pnpm nocobase cli build`, `pnpm nocobase cli build --runner`, `--universal` |
|
|
38
38
|
|
|
39
39
|
Every command listed takes `--connection <name>` or `--all` where connections apply; without either it acts on the default connection.
|
|
40
40
|
|
|
41
41
|
## Conventions an agent relies on
|
|
42
42
|
|
|
43
|
+
- **Verify the browser-facing origin before handing over a running application.** Set `app.publicOrigin` to the protocol, host and port the user actually opens, without the application's base path. On a remote development machine, inspect its LAN address or use the established domain instead of assuming `localhost`. An explicit `APP_PUBLIC_ORIGIN` overrides the file, including values in `.env` and `.env.local`; `pnpm dev` must not supply a fallback that overrides the configured origin. Verify an authentication request with the intended browser Origin as well as the page and health endpoint: those two GET requests alone cannot reveal a rejected login origin. `403 INVALID_ORIGIN` means the access address is not trusted; correct the origin configuration rather than disabling origin checks or trusting every host.
|
|
43
44
|
- **`--json`** prints one JSON document on stdout, success or failure, the same shape for every command: `{ schemaVersion, ok, command, status, result | error, warnings }`. `status` is `success`, `success-noop` (nothing needed changing: a dry run, or a run that found nothing to do), `partial-success` or `failure`. Read `result` on success; on failure read `error.code`, `error.suggestions` — each a `message` and, where the next step is a command, a `run` with its `command` and `args`, which names `node <dist>/cli/index.js` rather than `pnpm nocobase` in a built `dist/` — and `error.details`. Read `warnings` too, and check the exit code rather than parsing text. `NOCOBASE_CONTENT_TYPE=json` turns `--json` on for every command in a session. What the application logs while a command runs, and a command's progress, go to stderr, also under `--json`. When a command fails for a reason its message does not explain, rerun it with `NOCOBASE_CLI_DEBUG=1` to print the error behind it, redacted, on stderr; do not paste that output anywhere public without reading it.
|
|
44
45
|
- **Invalid usage** — a flag or argument the command rejects, or a command that does not exist — fails with `error.code` `INVALID_USAGE`, and its suggestions name the flag or command that was probably meant. Check that suggestion against the task before running it. The message names flags, arguments and allowed values but never repeats a value that was typed, since a mistyped line can carry a secret; compare it with the line you ran.
|
|
45
46
|
- **Exit codes** are `0` for success, `1` for a runtime failure and `2` for invalid usage. Keep a non-zero exit visible in your report; do not rerun until it passes by changing flags.
|
|
@@ -58,7 +59,7 @@ An external connection's metadata — titles, descriptions and relations its sch
|
|
|
58
59
|
|
|
59
60
|
## A command line of the application's own
|
|
60
61
|
|
|
61
|
-
Besides `pnpm nocobase`, an application may give the people and agents who use it a CLI of its own, such as `acme`: `@nocobase/app-cli-client` under the application's name, which signs in to the running application and runs the business commands its API publishes (`GET /api/cli/manifest`). No template declares one. To add it, put `"nocobase": { "cli": { "bin": "<command>", "displayName": "<Name>" } }` in `package.json` (the fields are in `@nocobase/app-cli`'s README: the state directory, the environment prefix, the device sign-in client id, the Skill directories it ships to runners, …) and add `@nocobase/app-cli-client` to `devDependencies`. `pnpm nocobase cli link` makes it a command in `node_modules/.bin`; `pnpm nocobase cli build` packs it into standalone tarballs in `storage/runners/dist`, which the agents plugin serves to its install script and to runners, and `cli build --runner` packs the runner (`nocobase-runner`, from `@nocobase/agent-runner`) beside it. In production a CI job builds them and mounts them into that storage; do not commit them or bake them into an image.
|
|
62
|
+
Besides `pnpm nocobase`, an application may give the people and agents who use it a CLI of its own, such as `acme`: `@nocobase/app-cli-client` under the application's name, which signs in to the running application and runs the business commands its API publishes (`GET /api/cli/manifest`). No template declares one. To add it, put `"nocobase": { "cli": { "bin": "<command>", "displayName": "<Name>" } }` in `package.json` (the fields are in `@nocobase/app-cli`'s README: the state directory, the environment prefix, the device sign-in client id, the Skill directories it ships to runners, …) and add `@nocobase/app-cli-client` to `devDependencies`. `pnpm nocobase cli link` makes it a command in `node_modules/.bin`; `pnpm nocobase cli build` packs it into standalone tarballs that bundle Node.js, one per platform (`--targets`), in `storage/runners/dist`, which the agents plugin serves to its install script and to runners, and `cli build --runner` packs the runner (`nocobase-runner`, from `@nocobase/agent-runner`) beside it. `--universal` packs one more tarball, `<product>-v<version>-universal.tar.gz`, which carries no Node.js and runs on the machine's own Node.js 24 or newer; alone, without `--targets`, it packs only that one and downloads no Node. It is served to every platform without a tarball of its own, and the install script checks for Node.js 24 before installing it. An application can also serve no tarball at all and name the exact npm versions of its CLI package and `@nocobase/agent-runner` instead (`agents.dist.npm`), which machines install with their own Node.js 24 and npm; the agents plugin's Skill covers both. In production a CI job builds them and mounts them into that storage; do not commit them or bake them into an image.
|
|
62
63
|
|
|
63
64
|
## The application's own commands
|
|
64
65
|
|
|
@@ -92,6 +92,8 @@ For the "More" menu in table rows, see [`table.md`](table.md).
|
|
|
92
92
|
|
|
93
93
|
## 3. Use shadcn
|
|
94
94
|
|
|
95
|
+
For flowcharts and process diagrams, reuse UI Library `@nocobase/flow-diagram` (React Flow + ELK); for `@nocobase/lifecycle` descriptions use `@nocobase/lifecycle-diagram`. Both inherit the application theme, including its primary color. See [diagram setup and execution highlights](../../lifecycle.md#draw-an-interactive-lifecycle-diagram) and the [offline catalog](ui-library.md#diagrams) before writing a custom canvas.
|
|
96
|
+
|
|
95
97
|
The template ships only the primitives its shell and compositions use ([section 1 of `shadcn.md`](shadcn.md#1-what-the-template-ships-and-how-to-add-the-rest)). First check whether `client/components/ui/` has the component you need. If it does not, add it from the shadcn registry:
|
|
96
98
|
|
|
97
99
|
```bash
|
|
@@ -216,6 +216,31 @@ A Markdown-in, Markdown-out rich text editor on official Tiptap extensions, with
|
|
|
216
216
|
- Example: `@nocobase/rich-text-editor-demo` (`pnpm exec shadcn view @nocobase/rich-text-editor-demo`)
|
|
217
217
|
- After installing: Give value and onChange (Markdown). onMentionSearch answers candidates for @query; mentions are stored as [@Name](mention://<kind>/<id>). onUpload stores a pasted or dropped file and answers its URL. extensions adds to or overrides richTextExtensions(); toolbar takes a render function, and RichTextToolbar, RichTextToolbarButton, RichTextInlineTools and RichTextBlockTools compose your own. Every word comes from labels, English by default.
|
|
218
218
|
|
|
219
|
+
## Diagrams
|
|
220
|
+
|
|
221
|
+
### flow-diagram
|
|
222
|
+
|
|
223
|
+
Read-only React Flow canvas with ELK orthogonal routing for directed graphs, including branches, cycles, parallel edges and self-loops. Use for interactive process views; pass nodes, edges and detail callbacks.
|
|
224
|
+
|
|
225
|
+
- Kind: component
|
|
226
|
+
- Install: `yes n | pnpm exec shadcn add @nocobase/flow-diagram`
|
|
227
|
+
- Installs to: `client/components/flow-diagram.tsx`, `client/components/flow-layout.ts`, `client/components/flow-diagram-css.d.ts`
|
|
228
|
+
- Plugin dependencies: none
|
|
229
|
+
- Example: `@nocobase/flow-diagram-demo` (`pnpm exec shadcn view @nocobase/flow-diagram-demo`)
|
|
230
|
+
- After installing: Pass nodes and edges with unique ids, an ariaLabel and either a bounded canvas height or autoHeight. Use direction DOWN with autoHeight for detailed page diagrams; height follows the full layout including outer routes and labels. The default node is 200×64 canvas units; set width/height for richer renderNode content. direction is RIGHT or DOWN. onNodeClick/onEdgeClick open your details; onLayoutError reports invalid graph or layout failures. Translate flowDiagram.empty, loading, failed, nodeHelp and edgeHelp; see the components README. Includes React Flow CSS. Uses application primary/card/foreground/border tokens in light and dark themes. Ordinary edges are subdued, solid and labeled directly on the route. Set visited on nodes/edges for actual history and highlighted for the current node or available edges; current nodes have a stronger fill and ring. ELK optimizes port order to reduce crossings. Decorative nodes/edges are not focusable or selectable.
|
|
231
|
+
|
|
232
|
+
### lifecycle-diagram
|
|
233
|
+
|
|
234
|
+
Theme-aware, read-only lifecycle diagram using React Flow and ELK. Shows the current state, actual execution history, available transitions and optional end markers, with clickable state/transition details.
|
|
235
|
+
|
|
236
|
+
- Kind: component
|
|
237
|
+
- Install: `yes n | pnpm exec shadcn add @nocobase/lifecycle-diagram`
|
|
238
|
+
- Installs to: `client/components/lifecycle-diagram.tsx`, `client/components/lifecycle-diagram-model.ts`
|
|
239
|
+
- Plugin dependencies: none
|
|
240
|
+
- Also installs: `@nocobase/flow-diagram`
|
|
241
|
+
- Example: `@nocobase/lifecycle-diagram-demo` (`pnpm exec shadcn view @nocobase/lifecycle-diagram-demo`)
|
|
242
|
+
- After installing: Pass description.description from useLifecycle/createLifecycleHook, currentState from view.record, availableTransitions filtered from view.available, and history from view.history.transitions. History matches the exact transition/source/destination; current state alone never implies a visited path. Pass a translated endLabel for separate decorative markers on explicit final states. For detailed page diagrams use direction DOWN and autoHeight. Translate ariaLabel, stateLabel and transitionLabel; append a gear to automatic transition labels if needed. Edges are solid with inline labels and subdued neutral strokes; current/visited/available highlights use the application primary theme token. Current nodes have a stronger fill and ring, visited nodes a light fill, with no extra visited label. onStateClick/onTransitionClick open details and never fire transitions. Keep toMermaid for documentation/export.
|
|
243
|
+
|
|
219
244
|
## Inbox
|
|
220
245
|
|
|
221
246
|
### inbox
|
|
@@ -426,3 +426,13 @@ States, transition, lifecycle and effect names are stored in the database. Addin
|
|
|
426
426
|
| `INVALID_SET` on create | `values` set the state, timestamp or version; pass `{ state }` to `create()` to start in another initial state |
|
|
427
427
|
|
|
428
428
|
The installed package's README lists its entries; the full guide, design notes and 28 worked recipes are in `packages/libs/lifecycle/docs/` of the NocoBase repository, and `packages/examples/app-plugin-lifecycle-example` and `packages/examples/app-plugin-office-flows-example` are complete working code.
|
|
429
|
+
|
|
430
|
+
## Draw an interactive lifecycle diagram
|
|
431
|
+
|
|
432
|
+
When a page needs a lifecycle diagram, use the UI Library's `@nocobase/lifecycle-diagram` component (React Flow + ELK) instead of building a canvas or turning Mermaid source into an interactive view. Read `pnpm exec shadcn view @nocobase/lifecycle-diagram-demo`, then install with `yes n | pnpm exec shadcn add @nocobase/lifecycle-diagram` and format the created files. It includes `@nocobase/flow-diagram`, which is also available alone for a generic directed graph. Follow [the UI Library guidance](frontend/references/styling.md#3-use-shadcn) and its [offline catalog](frontend/references/ui-library.md) for discovery and installation.
|
|
433
|
+
|
|
434
|
+
Import `LifecycleDiagram` from `#components/lifecycle-diagram`. Pass the hook's `description.description`, an `ariaLabel`, `currentState: view.record.status` (use the lifecycle's own state field), and `availableTransitions: view.available.filter((item) => item.allowed).map((item) => item.name)`. Translate labels by stable state/transition names with `stateLabel` and `transitionLabel`; add the shared `flowDiagram` keys to your locale resources. Use `onStateClick` and `onTransitionClick` to open details, including effects, triggers and continuations from the description. Definitions remain in source and clicking the diagram never fires a transition; action buttons still follow `view.available`. Pass `history={view.history.transitions}` for visited paths; the component matches the exact transition, source and destination, including retries. `visitedStates` supplements node highlights only; never infer a traversed edge from the current state or visited endpoints. Pass a translated `endLabel` to display a separate decorative end marker after each explicit final state, without treating every state lacking outgoing transitions as final. Keep `toMermaid()` for documentation and export.
|
|
435
|
+
|
|
436
|
+
For detailed page diagrams, prefer `direction="DOWN" autoHeight`: the canvas grows with the full layout, including outer routes and labels. A wide graph fitted into a short fixed-height panel makes its labels unreadable. Check the actual lifecycle definition in the target page, rather than judging a simple preview alone.
|
|
437
|
+
|
|
438
|
+
Preserve the component’s application theme tokens: `--primary` for current, visited and available highlights, subdued neutral strokes for other edges, and card/foreground/border tokens for the canvas and labels. Current nodes have a stronger fill and ring, visited nodes a light fill, with no extra “visited” label. Labels stay on the routes; automatic transitions remain solid and may show `⚙` through `transitionLabel`. Do not introduce a separate palette or hard-coded accent color. Check light/dark themes and a changed application primary color when customizing the rendering.
|
|
@@ -97,6 +97,8 @@ npx --registry=https://registry.npmjs.org @nocobase/app-installer install /srv/n
|
|
|
97
97
|
npx --registry=https://registry.npmjs.org @nocobase/app-installer upgrade --dir /srv/nocobase/crm --archive /tmp/crm.tar.gz
|
|
98
98
|
```
|
|
99
99
|
|
|
100
|
+
Published product applications can also be deployed with an app-installer version whose `--help` offers `--app`: `install /srv/nocobase/studio --app studio` is equivalent to `--app @nocobase/studio`. This route needs pnpm 11+ and builds the published package on the server without a repository checkout, preserving its identity and version. An npm installation upgrades the same package with `upgrade --dir <root>` (latest), `--to <version or tag>`, or `--rebuild` (installed version). Read `source.kind` in `status` before choosing the upgrade command; an archive installation still needs `--archive`. The same persistent configuration, backup and rollback rules apply.
|
|
101
|
+
|
|
100
102
|
`install --base-path /crm` chooses the mount path and writes it to `app.env` as `APP_BASE_PATH`; without it the server default `/main` applies. Upgrades keep the path `app.env` names, and editing it there moves the application on its next start. The installer refuses an archive for another application, an older version or another machine. The same version built again deploys as a new release, so the version need not be bumped for each deployment. An archive from an `@nocobase/app-cli` that predates relocatable builds has its mount path compiled in and runs only at that path, so a mismatch is refused with `BASE_PATH_MISMATCH`; one older still, which records no build time, or a release whose `@nocobase/app-server` predates `APP_STORAGE_DIR`, is refused: upgrade the project's NocoBase packages and build again. Each application on the server gets its own directory, port and pm2 process.
|
|
101
103
|
|
|
102
104
|
### Standalone Docker
|