@nocobase/app-skills 0.1.0-beta.28 → 0.1.0-beta.29
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
|
@@ -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
|
|