@nocobase/app-skills 0.1.0-beta.40 → 0.1.0-beta.41

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.40",
3
+ "version": "0.1.0-beta.41",
4
4
  "description": "Agent Skills for developing, upgrading and deploying NocoBase applications.",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -59,7 +59,7 @@ An external connection's metadata — titles, descriptions and relations its sch
59
59
 
60
60
  ## A command line of the application's own
61
61
 
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
+ 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`). The Examples template declares `nocobase-examples` for its Runner chat demonstration; Default leaves this optional. 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.
63
63
 
64
64
  ## The application's own commands
65
65
 
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: nocobase-deployment
3
- description: Plan, build, deploy, verify, upgrade, and troubleshoot NocoBase 3 applications in production, including standalone Node.js and Docker deployments. Use when an application must move from source to a production environment or when a deployment failure needs diagnosis.
3
+ description: Plan, build, deploy, verify, upgrade, and troubleshoot NocoBase 3 applications on an existing Studio or a standalone Node.js or Docker server. Use when an application must move from source to a deployment environment or when a deployment failure needs diagnosis.
4
4
  ---
5
5
 
6
6
  # NocoBase production deployment
@@ -13,7 +13,7 @@ Do not treat a process being healthy as proof that the application is usable. A
13
13
 
14
14
  Before building or changing a server, record:
15
15
 
16
- - The deployment mode: standalone Node.js managed by app-installer, standalone Node.js by hand, or standalone Docker.
16
+ - The deployment mode: an App managed by an existing Studio, standalone Node.js managed by app-installer, standalone Node.js by hand, or standalone Docker.
17
17
  - The source revision, application version, Node.js and pnpm versions, target CPU/OS/libc, and the destination host.
18
18
  - Whether the destination uses the existing database and storage, a new database, or a restore. Business data is not included in `dist`, `dist.tar.gz`, or a Docker image.
19
19
  - The application base path, public origin, database type, external services, reverse proxy, persistent directories, and service identity.
@@ -21,6 +21,14 @@ Before building or changing a server, record:
21
21
 
22
22
  Do not run production writes, migrations, seeds, uploads, deployments, or destructive removal until the target and the user's authorization are explicit. If the target or data plan is unresolved, stop and ask for it.
23
23
 
24
+ ## Deploy to an existing Studio
25
+
26
+ When the user asks to deploy this application to an existing NocoBase Studio, read [Deploy to Studio](references/deploy-to-studio.md) before building. It covers installing and signing in with the target Studio's `nb-studio` CLI, choosing an upload route, deploying and verifying the application. The application being deployed does not need its own business CLI.
27
+
28
+ Confirm the source application, target Studio, App ID and environment. A source directory, deployment directory and App ID can have different names; do not infer application identity from one of them. Follow the reference for Studio-managed configuration, storage and deployment; use the shared artifact and verification guidance below where applicable, not the standalone installation commands.
29
+
30
+ Deploying Studio itself to a server follows the standalone deployment workflow below.
31
+
24
32
  ## Prepare the source and artifact
25
33
 
26
34
  In the application project root, use the project's lockfile and declared pnpm version:
@@ -0,0 +1,146 @@
1
+ # Deploy an application to Studio
2
+
3
+ Use this workflow to deploy the current application to an existing NocoBase Studio. Keep application sources and build tools on the development or CI machine; Studio receives the deployment artifact. `pnpm nocobase` builds and maintains the source application, while `nb-studio` manages the destination. The application does not need a business CLI of its own.
4
+
5
+ ## 1. Identify the application and destination
6
+
7
+ Inspect the application's `package.json`, build configuration and working tree. Record:
8
+
9
+ - Source directory, package name, version and commit; note uncommitted changes.
10
+ - Studio URL, including its mount path, and CLI profile.
11
+ - App ID and target environment.
12
+ - First installation or update; existing data and storage to preserve.
13
+ - Public application URL, database and required external services.
14
+
15
+ Reuse values already supplied by the user. Ask only for unresolved information that changes the deployment target or data operation. Do not infer the application from a directory name or deploy whichever repository happens to be current after switching workspaces.
16
+
17
+ For multiple destinations, record each separately. Reuse one artifact only when their runtime requirements match. The Studio URL is the management endpoint; the deployed App's public URL is separate and comes from its environment.
18
+
19
+ ## 2. Prepare the Studio CLI
20
+
21
+ Check whether `nb-studio` is installed:
22
+
23
+ ```bash
24
+ command -v nb-studio
25
+ nb-studio --version
26
+ ```
27
+
28
+ If missing, obtain the installation command from the target Studio's **Use Studio in your agent** entry. Its command contains a short-lived download token. Use the command that Studio provides; do not invent a token or assume `@nocobase/studio-cli` is published to npm. The install script is served at `<studio-url>/api/agents/dist/installScript`, including the Studio mount path.
29
+
30
+ The currently served universal CLI package requires Node.js 24 or newer. Follow the installer's prerequisite checks and PATH instructions. A download token installs the CLI; it is not a login credential. Install the CLI once, then use profiles for separate Studio instances.
31
+
32
+ For a local coding agent, install the CLI's packaged Skill when needed:
33
+
34
+ ```bash
35
+ nb-studio skills install
36
+ ```
37
+
38
+ Use `--tool codex`, `--tool claude` or `--tool all` when the target tools are known. Read the installed `nb-studio-cli` Skill for command discovery and authentication rules. Inside a Studio agent run, reuse the supplied CLI, Skill and run identity rather than installing another copy or signing in as a person.
39
+
40
+ ## 3. Sign in and inspect the destination
41
+
42
+ For a person's local deployment, use an explicit profile for every destination:
43
+
44
+ ```bash
45
+ nb-studio --profile <profile> login --server <studio-url>
46
+ nb-studio --profile <profile> whoami
47
+ ```
48
+
49
+ The person must approve the device code in the browser. Never approve it on their behalf. If the existing profile is already authenticated to the correct server, reuse it; inspect its identity before starting another login. A Studio agent run keeps its supplied identity and permission limits.
50
+
51
+ For CI, use the organization's authorized CI credential through the documented environment variables or stdin mechanism. Keep credentials out of command arguments, logs and deployment reports. A missing or expired credential requires the supported login or credential setup; do not create a key to work around it.
52
+
53
+ Business commands come from the server. Inspect their documentation before using unfamiliar arguments:
54
+
55
+ ```bash
56
+ nb-studio --profile <profile> docs app
57
+ nb-studio --profile <profile> docs env
58
+ nb-studio --profile <profile> docs deploy
59
+ nb-studio --profile <profile> docs release
60
+ ```
61
+
62
+ Inspect the existing App and environment before creating or updating them. Determine:
63
+
64
+ - Whether the environment accepts archives or container images.
65
+ - Its target platform and runtime requirements.
66
+ - Whether deployment requires approval and what the caller may do.
67
+ - Required variables, configuration and available storage, including room for unpacking, retained releases and backups.
68
+ - Whether the App is connected to a repository whose commit Studio can verify.
69
+
70
+ An App Host running inside a container can still be an in-process environment. Do not infer its artifact type from the presence of Docker on the server. Do not select a different environment just to avoid an approval or artifact requirement. For a new App, use the documented creation route appropriate to the chosen upload workflow; repository-backed `app ensure` has repository prerequisites too.
71
+
72
+ ## 4. Build and configure
73
+
74
+ Follow the parent deployment Skill and the application's build instructions. For a compatible Linux x64 Node.js 24 archive target, for example:
75
+
76
+ ```bash
77
+ pnpm build --target linux-x64 --node-version 24 --tar
78
+ ```
79
+
80
+ Inspect `storage/exports/dist.tar.gz` and record its SHA256, package identity, version, build target and source revision. The archive carries application code and dependencies, not the development database, secrets or uploaded files. For an image environment, follow its image build, registry and release registration workflow instead; the archive commands below do not deploy an image.
81
+
82
+ Configure required App or environment variables through Studio's supported interfaces. Preserve existing secrets and data during updates. Initial administrator variables initialize a new account; they do not reset an existing account's password. Follow the application's sample-data setting rather than silently enabling examples.
83
+
84
+ Before an update, review migrations and establish the database and file backup and restore procedure for this App. Do not assume that Studio's own backup covers every hosted App, or that switching releases restores business data. Required variable declarations may become available only after upload; inspect them then and resolve missing values before deployment.
85
+
86
+ ## 5. Choose the upload and deployment route
87
+
88
+ ### Repository-backed build
89
+
90
+ When Studio knows the repository and can verify the source commit, use the documented build deployment command for an App that exists in the intended environment:
91
+
92
+ ```bash
93
+ nb-studio --profile <profile> deploy \
94
+ --app <app-id> \
95
+ --repository <owner/repo> \
96
+ --sha <source-commit> \
97
+ --file storage/exports/dist.tar.gz \
98
+ --json
99
+ ```
100
+
101
+ Outside CI, supply repository and commit explicitly. Do not invent a commit or claim that an artifact from a dirty working tree exactly matches it. `release upload` also uses Studio's verified-build route; it is not a fallback for a missing repository.
102
+
103
+ ### Manual archive without a connected repository
104
+
105
+ Do not repeatedly retry the verified-build route after `REPOSITORY_NOT_FOUND`. Do not connect a repository merely to bypass this prerequisite. Use Studio's release upload page or the documented application-level upload API within the caller's permissions. Read the target server's authenticated OpenAPI document at `<studio-url>/api/swagger` first.
106
+
107
+ The current API workflow is:
108
+
109
+ 1. Create an upload ticket with `POST /api/releases/apps/{appId}/uploadTickets`, requesting upload only (`deploy: false`).
110
+ 2. Upload the archive to the ticket's returned path using the ticket credential as `Authorization: Bearer <ticket>`, with the binary body and content type the API declares. Resolve the returned path against the documented API base; do not assume it already contains `/api` or the Studio mount path.
111
+ 3. Supply `X-Artifact-SHA256` and `X-Release-Deploy: false` so integrity is checked and deployment remains a separate step.
112
+ 4. Record the returned Release ID, inspect required variables and complete configuration.
113
+ 5. Deploy that release through the CLI, or request deployment when approval is required.
114
+
115
+ Prefix API paths with the Studio URL, including its mount path. Use an authorized authentication mechanism for the ticket request. Do not depend on reading `~/.nb-studio/config.json`: credentials may live in the system keychain, and its storage format is not an integration API. If no supported API credential is available, use the authenticated upload page or obtain the required credential through the supported setup.
116
+
117
+ The current application-level upload routes are not exposed as ordinary CLI commands. Do not invent a command or describe this route as CLI-only. An upload ticket does not grant permission to bypass a protected environment.
118
+
119
+ ### Existing release
120
+
121
+ For an unprotected environment:
122
+
123
+ ```bash
124
+ nb-studio --profile <profile> app deploy <app-id> \
125
+ --release <release-id> --wait true --json
126
+ ```
127
+
128
+ For a protected environment, follow the documented deployment-request flow. A pending approval is not a completed deployment, and approval rules must not be bypassed.
129
+
130
+ Release and Deployment IDs belong to their Studio instance. Never reuse an ID from another destination, even when both uploaded the same archive.
131
+
132
+ ## 6. Verify and report
133
+
134
+ Inspect the command's JSON result, deployment status and logs. An accepted upload, created release or timed-out wait does not prove deployment succeeded. After a timeout or uncertain response, inspect existing releases and deployments before retrying. Do not start a competing deployment.
135
+
136
+ Verify through the public application URL:
137
+
138
+ - Health endpoint and expected App identity.
139
+ - Static assets, page refresh, API requests and WebSocket connections.
140
+ - Sign-in and the relevant permission boundary.
141
+ - A representative business operation.
142
+ - Required data and file persistence, with restart verification when applicable. Prefer the App's restart operation; restarting Studio may interrupt other hosted Apps.
143
+
144
+ Use the parent Skill's verification guidance for the change being made. Reuse build checks for the same artifact, but verify each destination independently and report partial success explicitly. Keep external services or scheduled behavior that were not exercised separate from successful checks.
145
+
146
+ Record the destination, App and environment, artifact SHA256, source revision, Release ID, Deployment ID, public URL, verification results and unresolved items. Never include credentials. Do not report a deployment as complete while it is awaiting approval, still running, or failing its required verification.