@nocobase/app-skills 0.1.0-beta.29 → 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 CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nocobase/app-skills",
3
- "version": "0.1.0-beta.29",
3
+ "version": "0.1.0-beta.30",
4
4
  "description": "Agent Skills for developing, upgrading and deploying NocoBase applications.",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -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
- | Write server and migration tests, choose a test layer, verify before finishing | [testing and verification](references/testing.md) |
108
- | Run a CLI command: configure, migrate, manage plugins, read the data model | [the command line](references/cli.md) |
109
- | Add or change an application command under `cli/commands/` | [adding an application command](references/commands.md) |
110
- | Understand behavior inherited from an official application template | [template variants](references/template-variants.md) |
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.
@@ -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