@nocobase/app-cli-distribution 0.1.0-beta.0 → 0.1.0-beta.1

package/README.md

@@ -43,9 +43,37 @@ app.route('/api/agents/dist', distribution);
 
 No artifact is public by default. `admissions` are ordered asynchronous handlers: return `false` when the handler recognizes no credential, return `true` after authorizing it, and throw on an invalid recognized credential. An error never falls through to another handler or a signed-in session. After every handler declines, `fallback` may authorize through the host. With neither an accepting handler nor a fallback, requests receive 401 `UNAUTHORIZED` in the existing `agents` error domain. Never use download credentials as business login credentials.
 
-The package implements no public-download strategy or signed credential protocol. A host can write its own authorization middleware, which makes its security policy the host's responsibility. Choosing Main's policy, any public access, and any new persistent token store require a separate product decision. This package does not select one or create a table.
+The package implements no anonymous artifact admission or signed credential protocol. A host can write its own authorization middleware, which makes its security policy the host's responsibility. Choosing Main's policy, any public access, and any new persistent token store require a separate product decision. This package does not select one or create a table.
 
-`createInstallRoutes` serves a public script containing no credential. The CLI-only script accepts `--token`, `--server`, `--prefix`, `--bin-dir`, `--dry-run`, `-h` and `--help`; it sends the token in `x-nocobase-download-token`. A session-only host can resolve/download/update through its authenticated clients, but must supply an installation credential admission if it wants this token-based one-line installation. The `InstallScriptExtensions.credentials` hook may implement another host-approved installation transport. No Runner flags, registration or services are in the default script.
+`createInstallRoutes` and `installScript` keep the protected CLI installation protocol unchanged. They accept `--token`, `--server`, `--prefix`, `--bin-dir`, `--dry-run`, `-h` and `--help`, and send `x-nocobase-download-token`. Agents and its Runner extensions keep using these original entry points. The script implementation and extension contract are not shared with public-mode generation.
+
+## Independent public installer
+
+A host that deliberately serves its own CLI artifacts publicly imports a separate entry:
+
+```ts
+import {
+  publicInstallScript,
+  createPublicInstallRoutes,
+} from '@nocobase/app-cli-distribution/public-install';
+
+// Either render the script in the host's own route:
+const script = publicInstallScript({
+  cli: 'acme',
+  server: 'https://example.com/platform/main',
+});
+// Or mount this router alongside that host's public artifact router:
+const installation = createPublicInstallRoutes({
+  cli: () => 'acme',
+  publicBasePath: '/platform/main',
+});
+```
+
+Mount the router at the host's existing `/api/agents/dist` prefix, choosing one installation router. This script has no token parsing, credential header, Runner registration, service installation or extension hooks. It independently handles server/prefix/bin-dir/dry-run, platform/tool checks, anonymous resolution/download, SHA-256 verification, installation metadata, version activation, command links and the next login instruction. It requires Node.js 24+, curl, tar and a SHA-256 tool on macOS/Linux (Windows through WSL); npm is required only for an npm resolution. It reuses the stateless npm launcher and requested-server helper, not the protected script's text. Relative installation paths become absolute, and metadata remains valid for paths containing quotes. Dry-run resolves metadata but performs no download or installation writes. Exit 0 indicates success/help/dry-run, 2 invalid usage/address and 1 runtime/prerequisite/resolution/checksum failures; a failing external install tool may retain its own nonzero code.
+
+The host must separately configure anonymous artifact admission, restricted to its CLI product, for example `products: ['acme']` with `admissions: [async () => true]`. The new script does not change artifact authorization. A protected response fails even if an older CLI is present. Keep deployment configuration, database files and credentials out of the public archive.
+
+Existing `<cli> update` already consumes the same resolution/file endpoints after selecting its signed-in profile, and needs no download token when those endpoints are public. No `publicUpdates` brand option or `update --server` extension is provided. A never-signed-in installation can rerun the public installer; normal business use still begins with native login. The old update command, protected distribution targets and Runner ownership remain unchanged.
 
 ## Optional stateful download tokens
 
@@ -77,4 +105,4 @@ The new package's host tests exercise protected defaults, an explicit session po
 
 The extraction adds no database query, write, lock or transaction to an Agents request and no polling or Runner claim work. Token mint remains one insert/transaction; metadata admission one read/transaction plus a conditional update when binding; a token file request remains two reads/transactions and one conditional counting update. The product restriction adds an in-memory membership check. No independent-host database or jobs are required.
 
-Main integration and UI, its authorization choice, signed tokens/public downloads, token cleanup, mode switching between independent distribution and Agents, and the client's full-buffer update download remain separate work. One router owns `/api/agents/dist` in a host; do not register both independent distribution and Agents at that prefix.
+Main integration and UI, host authorization choices, token cleanup, mode switching between independent distribution and Agents, and the client's full-buffer update download remain separate work. One router owns `/api/agents/dist` in a host; do not register both independent distribution and Agents at that prefix.

package/dist/public-install.d.ts

@@ -0,0 +1,17 @@
+import { type DescribeRouteOptions } from '@nocobase/app-server/router';
+import { Hono } from 'hono';
+export interface PublicInstallScriptOptions {
+    readonly cli: string;
+    readonly server?: string;
+}
+/** A separate CLI-only installer. It neither changes nor extends the protected installation protocol. */
+export declare function publicInstallScript(options: PublicInstallScriptOptions): string;
+export interface PublicInstallRoutesOptions {
+    readonly cli: () => string;
+    readonly publicOrigin?: () => string | undefined;
+    readonly publicBasePath?: string;
+    readonly openapi?: DescribeRouteOptions;
+}
+/** Mount explicitly alongside a host's independently configured public artifact admission. */
+export declare function createPublicInstallRoutes(options: PublicInstallRoutesOptions): Hono;
+//# sourceMappingURL=public-install.d.ts.map

package/dist/public-install.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"public-install.d.ts","sourceRoot":"","sources":["../src/public-install.ts"],"names":[],"mappings":"AAEA,OAAO,EAIL,KAAK,oBAAoB,EAC1B,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAK5B,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,yGAAyG;AACzG,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,0BAA0B,GAClC,MAAM,CAWR;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,GAAG,EAAE,MAAM,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IACjD,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,OAAO,CAAC,EAAE,oBAAoB,CAAC;CACzC;AAED,8FAA8F;AAC9F,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,0BAA0B,GAClC,IAAI,CAgCN"}

package/dist/public-install.js

@@ -0,0 +1,164 @@
+import { DIST_PRODUCT_PATTERN } from '@nocobase/agent-protocol';
+import { npmLauncherScript } from '@nocobase/app-cli-client/install';
+import { apiErrorResponse, cliRoute, describeRoute, } from '@nocobase/app-server/router';
+import { Hono } from 'hono';
+import { requestedServer } from './install.js';
+const SAFE_SERVER = /^https?:\/\/[A-Za-z0-9.:[\]_-]+(?:\/[A-Za-z0-9._~/-]*)?$/u;
+/** A separate CLI-only installer. It neither changes nor extends the protected installation protocol. */
+export function publicInstallScript(options) {
+    if (!DIST_PRODUCT_PATTERN.test(options.cli) ||
+        options.cli === 'nocobase-runner')
+        throw new Error(`Not a CLI command name: ${options.cli}`);
+    const server = options.server ?? '';
+    return PUBLIC_INSTALL_SCRIPT.replaceAll('@CLI@', options.cli).replace('@DEFAULT_SERVER@', SAFE_SERVER.test(server) ? server.replace(/\/+$/u, '') : '');
+}
+/** Mount explicitly alongside a host's independently configured public artifact admission. */
+export function createPublicInstallRoutes(options) {
+    return new Hono().get('/installScript', describeRoute(options.openapi ?? {
+        tags: ['CliDistribution'],
+        summary: 'Get the public CLI install script',
+        operationId: 'cliDistributionPublicInstallScript',
+        ...cliRoute(false),
+        security: [],
+        responses: {
+            200: {
+                description: 'A public CLI-only POSIX shell script.',
+                content: { 'text/x-shellscript': { schema: { type: 'string' } } },
+            },
+            500: apiErrorResponse(500),
+        },
+    }), (context) => context.body(publicInstallScript({
+        cli: options.cli(),
+        server: requestedServer(context, options),
+    }), 200, {
+        'content-type': 'text/x-shellscript; charset=utf-8',
+        'cache-control': 'no-cache',
+    }));
+}
+// Kept independent of the protected script and its extension points, intentionally allowing some duplication.
+const PUBLIC_INSTALL_SCRIPT = `#!/bin/sh
+# Installs the publicly downloadable @CLI@ CLI. Business access requires a separate login.
+set -eu
+usage() {
+  cat <<'USAGE'
+Usage: install.sh [--server <url>] [--prefix <dir>] [--bin-dir <dir>] [--dry-run]
+
+Requires Node.js 24+, curl, tar and a SHA-256 tool. Supports macOS/Linux and Windows through WSL.
+USAGE
+}
+cli=@CLI@
+server="@DEFAULT_SERVER@"
+prefix="\${NOCOBASE_CLI_INSTALL_DIR:-}"
+bin_dir="\${NOCOBASE_CLI_BIN_DIR:-}"
+dry_run=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --server|--prefix|--bin-dir)
+      [ $# -ge 2 ] && [ -n "$2" ] || { usage >&2; exit 2; }
+      case "$1" in
+        --server) server="$2" ;;
+        --prefix) prefix="$2" ;;
+        --bin-dir) bin_dir="$2" ;;
+      esac
+      shift 2 ;;
+    --dry-run) dry_run=1; shift ;;
+    -h|--help) usage; exit 0 ;;
+    *) echo 'Unknown installation option.' >&2; usage >&2; exit 2 ;;
+  esac
+done
+[ -n "$server" ] || { usage >&2; exit 2; }
+say() { printf '%s\\n' "$*"; }
+fail() { printf '%s install: %s\\n' "$cli" "$*" >&2; exit 1; }
+run() { if [ "$dry_run" = 1 ]; then say "+ $*"; else "$@"; fi; }
+case "$(uname -s)" in
+  Darwin) os=darwin ;;
+  Linux) os=linux ;;
+  *) fail 'Use macOS, Linux or WSL.' ;;
+esac
+case "$(uname -m)" in
+  arm64|aarch64) arch=arm64 ;;
+  x86_64|amd64) arch=x64 ;;
+  *) fail 'Unsupported processor.' ;;
+esac
+target="\${NOCOBASE_CLI_TARGET:-$os-$arch}"
+node_bin="$(command -v node 2>/dev/null || true)"
+[ -n "$node_bin" ] || fail 'Node.js 24 or newer is required.'
+node_version="$("$node_bin" -p 'process.versions.node' 2>/dev/null || true)"
+case "$node_version" in ''|*[!0-9.]*) fail 'Node.js 24 or newer is required.' ;; esac
+[ "\${node_version%%.*}" -ge 24 ] || fail 'Node.js 24 or newer is required.'
+# Validate without printing an invalid address, which could accidentally contain a credential.
+server="$("$node_bin" -e 'try { const u = new URL(process.argv[1]); if (!["http:", "https:"].includes(u.protocol) || u.username || u.password || u.search || u.hash) throw Error(); console.log(u.href.replace(/\\/+$/, "")); } catch { process.exit(2); }' "$server")" || { echo 'Use an HTTP(S) application URL without credentials, query or fragment.' >&2; exit 2; }
+prefix="\${prefix:-$HOME/.local/share/$cli}"
+bin_dir="\${bin_dir:-$HOME/.local/bin}"
+prefix="$("$node_bin" -e 'console.log(require("node:path").resolve(process.argv[1]))' "$prefix")"
+bin_dir="$("$node_bin" -e 'console.log(require("node:path").resolve(process.argv[1]))' "$bin_dir")"
+command -v curl >/dev/null 2>&1 || fail 'curl is required.'
+command -v tar >/dev/null 2>&1 || fail 'tar is required.'
+if command -v sha256sum >/dev/null 2>&1; then
+  sha256() { sha256sum "$1" | cut -d ' ' -f 1; }
+elif command -v shasum >/dev/null 2>&1; then
+  sha256() { shasum -a 256 "$1" | cut -d ' ' -f 1; }
+else
+  fail 'sha256sum or shasum is required.'
+fi
+tmp="$(mktemp -d)"
+trap 'rm -rf "$tmp"' EXIT INT TERM
+field() { sed -n "s/^$1=//p" "$tmp/resolve" | head -n 1; }
+status="$(curl -sS -o "$tmp/resolve" -w '%{http_code}' "$server/api/agents/dist/products/$cli/targets/$target?format=env&accept=npm")" || fail 'Could not reach the application.'
+[ "$status" = 200 ] || fail "The application answered $status while resolving the CLI."
+version="$(field version)"
+case "$version" in ''|.|..|*[!0-9A-Za-z.+-]*) fail 'The application named an unexpected version.' ;; esac
+kind="$(field kind)"
+dest="$prefix/versions/$version"
+if [ "$kind" = npm ]; then
+  package="$(field package)"
+  case "$package" in ''|*[!0-9a-z@/._~-]*) fail 'The application named an unexpected npm package.' ;; esac
+  npm_bin="\${NOCOBASE_NPM:-$(command -v npm 2>/dev/null || true)}"
+  [ -n "$npm_bin" ] && [ -x "$npm_bin" ] || fail 'npm is required for this package.'
+else
+  url="$(field url)"
+  checksum="$(field sha256)"
+  case "$url" in /*) ;; *) fail 'The application named an unexpected download.' ;; esac
+  case "$checksum" in *[!0-9a-f]*|'') fail 'The application named an unexpected checksum.' ;; esac
+fi
+if [ ! -x "$dest/bin/$cli" ]; then
+  if [ "$kind" = npm ]; then
+    run rm -rf "$dest.partial"
+    run mkdir -p "$dest.partial"
+    run "$npm_bin" install --prefix "$dest.partial" --no-save --no-audit --no-fund --omit=optional "$package@$version"
+    if [ "$dry_run" = 0 ]; then
+      [ -e "$dest.partial/node_modules/.bin/$cli" ] || fail 'The package provides no CLI command.'
+      mkdir -p "$dest.partial/bin"
+      cat <<'LAUNCHER' >"$dest.partial/bin/$cli"
+${npmLauncherScript()}LAUNCHER
+      chmod 755 "$dest.partial/bin/$cli"
+    fi
+    run mv "$dest.partial" "$dest"
+  else
+    run curl -fSL --progress-bar -o "$tmp/cli.tar.gz" "$server$url" || fail 'CLI download failed.'
+    if [ "$dry_run" = 0 ]; then
+      actual="$(sha256 "$tmp/cli.tar.gz")"
+      [ "$actual" = "$checksum" ] || fail 'The download does not match its SHA-256.'
+      say 'Checksum verified.'
+    fi
+    run rm -rf "$dest.partial"
+    run mkdir -p "$dest.partial"
+    run tar -xzf "$tmp/cli.tar.gz" -C "$dest.partial" --strip-components=1 || fail 'Could not unpack the CLI archive.'
+    if [ "$dry_run" = 0 ]; then
+      [ -x "$dest.partial/bin/$cli" ] || fail 'The archive provides no CLI command.'
+    fi
+    run mv "$dest.partial" "$dest"
+  fi
+fi
+run ln -sfn "versions/$version" "$prefix/current"
+run ln -sfn "$node_bin" "$prefix/node"
+run mkdir -p "$bin_dir"
+run ln -sfn "$prefix/current/bin/$cli" "$bin_dir/$cli"
+if [ "$dry_run" = 0 ]; then
+  "$node_bin" -e 'console.log(JSON.stringify({prefix: process.argv[1], binLink: process.argv[2], mode: "cli"}, null, 2))' "$prefix" "$bin_dir/$cli" >"$prefix/install.json"
+fi
+if [ "$dry_run" = 1 ]; then say 'Dry run: no installation was changed.'; else say "$cli is installed: $bin_dir/$cli"; fi
+case ":$PATH:" in *":$bin_dir:"*) ;; *) say "Add $bin_dir to your PATH." ;; esac
+say "Next: $cli login --server $server"
+`;
+//# sourceMappingURL=public-install.js.map

package/dist/public-install.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"public-install.js","sourceRoot":"","sources":["../src/public-install.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AACrE,OAAO,EACL,gBAAgB,EAChB,QAAQ,EACR,aAAa,GAEd,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/C,MAAM,WAAW,GAAG,2DAA2D,CAAC;AAOhF,yGAAyG;AACzG,MAAM,UAAU,mBAAmB,CACjC,OAAmC;IAEnC,IACE,CAAC,oBAAoB,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC;QACvC,OAAO,CAAC,GAAG,KAAK,iBAAiB;QAEjC,MAAM,IAAI,KAAK,CAAC,2BAA2B,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IAC5D,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC;IACpC,OAAO,qBAAqB,CAAC,UAAU,CAAC,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,OAAO,CACnE,kBAAkB,EAClB,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAC5D,CAAC;AACJ,CAAC;AASD,8FAA8F;AAC9F,MAAM,UAAU,yBAAyB,CACvC,OAAmC;IAEnC,OAAO,IAAI,IAAI,EAAE,CAAC,GAAG,CACnB,gBAAgB,EAChB,aAAa,CACX,OAAO,CAAC,OAAO,IAAI;QACjB,IAAI,EAAE,CAAC,iBAAiB,CAAC;QACzB,OAAO,EAAE,mCAAmC;QAC5C,WAAW,EAAE,oCAAoC;QACjD,GAAG,QAAQ,CAAC,KAAK,CAAC;QAClB,QAAQ,EAAE,EAAE;QACZ,SAAS,EAAE;YACT,GAAG,EAAE;gBACH,WAAW,EAAE,uCAAuC;gBACpD,OAAO,EAAE,EAAE,oBAAoB,EAAE,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE;aAClE;YACD,GAAG,EAAE,gBAAgB,CAAC,GAAG,CAAC;SAC3B;KACF,CACF,EACD,CAAC,OAAO,EAAE,EAAE,CACV,OAAO,CAAC,IAAI,CACV,mBAAmB,CAAC;QAClB,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE;QAClB,MAAM,EAAE,eAAe,CAAC,OAAO,EAAE,OAAO,CAAC;KAC1C,CAAC,EACF,GAAG,EACH;QACE,cAAc,EAAE,mCAAmC;QACnD,eAAe,EAAE,UAAU;KAC5B,CACF,CACJ,CAAC;AACJ,CAAC;AAED,8GAA8G;AAC9G,MAAM,qBAAqB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA8F5B,iBAAiB,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8BpB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nocobase/app-cli-distribution",
-  "version": "0.1.0-beta.0",
+  "version": "0.1.0-beta.1",
   "description": "Composable server-side CLI artifact distribution and installation.",
   "license": "Apache-2.0",
   "type": "module",
@@ -15,6 +15,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./public-install": {
+      "types": "./dist/public-install.d.ts",
+      "import": "./dist/public-install.js"
     }
   },
   "files": [
@@ -27,10 +31,10 @@
     "hono": "^4.13.2",
     "zod": "^4.6.6",
     "@nocobase/agent-protocol": "^0.1.0-beta.19",
-    "@nocobase/app-cli-client": "^0.1.0-beta.21"
+    "@nocobase/app-cli-client": "^0.1.0-beta.22"
   },
   "peerDependencies": {
-    "@nocobase/app-server": "^5.0.0-beta.5"
+    "@nocobase/app-server": "^5.0.0-beta.6"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",