@nocobase/app-cli-client 0.0.0-stage → 0.1.0-beta.1

package/README.md

@@ -1,3 +1,25 @@
-# Temporary Holding Version
+# @nocobase/app-cli-client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A command line for a NocoBase application, branded by the application: it signs in to a server and runs the business commands the server's command manifest (`GET /api/cli/manifest`) publishes for the caller, each a request to one API route. An application declares its brand under `nocobase.cli` in its `package.json` (`AppCliBrand`), and `nocobase cli build` and `nocobase cli link` of `@nocobase/app-cli` package it with an entry that calls `runAppCliPackage`, which reads the brand back from the packaged CLI's own `package.json` and runs it with `selfUpdate` on; an application's `acme` is made this way. A CLI may instead call `runAppCli` with an `AppCliConfig` of its own and add static commands.
+
+```ts
+import { runAppCli } from '@nocobase/app-cli-client';
+
+await runAppCli(
+  {
+    bin: 'acme',
+    displayName: 'Acme',
+    stateDir: '.acme',
+    homeEnv: 'ACME_HOME',
+    envPrefix: 'ACME',
+    runCredentialsFile: '.acme/run.json',
+  },
+  process.argv.slice(2),
+);
+```
+
+An application whose install script (`/api/agents/dist/installScript` of `@nocobase/app-plugin-agents`) installs its CLI names `selfUpdate` in the configuration, with the root of the CLI's package as it runs (`packageRoot`). The CLI then has `<bin> update`, which asks the signed-in server for the newest version it serves for this platform (`selfUpdate.product`, the command name by default), checks its SHA-256 and switches `<prefix>/current` to it, keeping the previous version; business commands and `login` say on stderr when a newer version is served, asking at most every 12 hours (`<state dir>/cache/update.json`). An installation the script made for the runner (`install.json` `mode: runner`) is the runner's, which updates itself, so `update` refuses it. `@nocobase/app-cli-client/install` is that installation layout (`<prefix>/versions/<version>`, `current`, `install.json`) and the update itself, without reading any CLI configuration, so a runner shares it.
+
+`@nocobase/app-cli-client/request` exports `fillRequest`, which turns a manifest command and the values of its parameters into the request it makes. It imports nothing else, so a server that calls its own routes the way the CLI does, such as an online agent's tools in `@nocobase/app-plugin-agents`, builds the same request.
+
+`@nocobase/app-cli-client/parse` is how the CLI reads a business command's line, with no file, environment or terminal of its own: `parseCommandLine(command, argv, { bin, io })` takes a manifest command and the words after its name, and answers the values of its parameters, the body read from `--file` and the files to send, or throws a `CliParseError` carrying the cli-envelope's `code`, message, suggestions and exit code. The `io` (`CliParseIo`) reads text files and environment variables, and optionally finds files to send (`file`, `changed`) and asks for a missing value (`ask`); a flag that sends a file is refused with `FILES_UNAVAILABLE` where `file` is absent. It also renders a command's help and an area's command list from the manifest (`renderCommandHelp`, `renderTopicHelp`) and maps a failed request to the CLI's exit code (`apiExitCode`). The CLI uses it over this machine, and the `acme` command of an online run's shell in `@nocobase/app-plugin-agents` over that shell, so both read a line the same way.

package/dist/brand.d.ts

@@ -0,0 +1,52 @@
+import type { AppCliAuth, AppCliConfig } from './config.ts';
+/** `nocobase.cli` in an application's `package.json`. */
+export interface AppCliBrand {
+    /** The command, such as `acme`; also the product the application serves it as. */
+    readonly bin: string;
+    /** The application's name in messages, such as `Acme`; `bin` when left out. */
+    readonly displayName?: string;
+    /** The root help's description; the packaged CLI's `description` when left out. */
+    readonly description?: string;
+    /** The directory under the home directory the CLI keeps its state in; `.<bin>` when left out. */
+    readonly stateDir?: string;
+    /** An environment variable that moves the state directory, such as `ACME_HOME`. */
+    readonly homeEnv?: string;
+    /** The prefix of the environment variables that act without signing in, such as `ACME` for `ACME_SERVER`. */
+    readonly envPrefix?: string;
+    /** An environment variable whose value `off` turns the keychain off, such as `ACME_KEYCHAIN`. */
+    readonly keychainEnv?: string;
+    /** The keychain service of the person's credential; `<bin>-cli` when left out. */
+    readonly keychainService?: string;
+    /** Where a runner puts a run's credentials, relative to the run's directory; `<stateDir>/run.json` when left out. */
+    readonly runCredentialsFile?: string;
+    /** Shown as `<bin> login --server <example>`. */
+    readonly exampleServer?: string;
+    /** Signing in through the browser: the device authorization client id the server accepts, and its routes. */
+    readonly auth?: AppCliAuth;
+    /** The command manifest's path below the server's address; `CLI_ROUTES.manifest` when left out. */
+    readonly manifestPath?: string;
+    /**
+     * Skill directories, relative to the application, that the packaged CLI ships in its `skills/` (each a directory with
+     * a `SKILL.md`, or a directory of them): the runner gives them to every run whose CLI it is. Read when packaging only.
+     */
+    readonly skills?: readonly string[];
+    /** The packaged CLI's version; the application's when left out. Read when packaging only. */
+    readonly version?: string;
+}
+/** What a packaged CLI is, beside its brand. */
+export interface AppCliPackageInfo {
+    /** The root of the packaged CLI, `<prefix>/versions/<version>` once the install script installed it. */
+    readonly packageRoot: string;
+    readonly version: string;
+    readonly description?: string;
+}
+/** The configuration a packaged CLI runs with. */
+export declare function appCliConfigOf(brand: AppCliBrand, info: AppCliPackageInfo): AppCliConfig;
+/** The brand and package information of the packaged CLI at `packageRoot`, from its `package.json`. */
+export declare function readAppCliPackage(packageRoot: string): {
+    brand: AppCliBrand;
+    info: AppCliPackageInfo;
+};
+/** Runs the packaged CLI at `packageRoot`: the entry `nocobase cli build` and `nocobase cli link` generate. */
+export declare function runAppCliPackage(packageRoot: string, argv?: string[]): Promise<void>;
+//# sourceMappingURL=brand.d.ts.map

package/dist/brand.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"brand.d.ts","sourceRoot":"","sources":["../src/brand.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAG5D,yDAAyD;AACzD,MAAM,WAAW,WAAW;IAC1B,kFAAkF;IAClF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,+EAA+E;IAC/E,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,mFAAmF;IACnF,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,iGAAiG;IACjG,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,mFAAmF;IACnF,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,6GAA6G;IAC7G,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,iGAAiG;IACjG,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,kFAAkF;IAClF,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,qHAAqH;IACrH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,iDAAiD;IACjD,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,6GAA6G;IAC7G,QAAQ,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC;IAC3B,mGAAmG;IACnG,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,6FAA6F;IAC7F,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,gDAAgD;AAChD,MAAM,WAAW,iBAAiB;IAChC,wGAAwG;IACxG,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,kDAAkD;AAClD,wBAAgB,cAAc,CAC5B,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE,iBAAiB,GACtB,YAAY,CA4Bd;AAQD,uGAAuG;AACvG,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG;IACtD,KAAK,EAAE,WAAW,CAAC;IACnB,IAAI,EAAE,iBAAiB,CAAC;CACzB,CAwBA;AAED,+GAA+G;AAC/G,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,MAAM,EACnB,IAAI,GAAE,MAAM,EAA0B,GACrC,OAAO,CAAC,IAAI,CAAC,CAGf"}

package/dist/brand.js

@@ -0,0 +1,61 @@
+// An application's CLI as its `package.json` declares it, under `nocobase.cli`: the JSON a packaged CLI carries in its
+// own `package.json` (`nocobase cli build` and `nocobase cli link` of `@nocobase/app-cli` write it), which
+// `runAppCliPackage` turns into the `AppCliConfig` it runs with. Only plain data: everything a function would decide
+// is derived here, such as `selfUpdate`, which a packaged CLI always has.
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { runAppCli } from "./run.js";
+/** The configuration a packaged CLI runs with. */
+export function appCliConfigOf(brand, info) {
+    const stateDir = brand.stateDir ?? `.${brand.bin}`;
+    const description = brand.description ?? info.description;
+    return {
+        bin: brand.bin,
+        displayName: brand.displayName ?? brand.bin,
+        stateDir,
+        runCredentialsFile: brand.runCredentialsFile ?? path.posix.join(stateDir, 'run.json'),
+        ...(brand.homeEnv === undefined ? {} : { homeEnv: brand.homeEnv }),
+        ...(brand.envPrefix === undefined ? {} : { envPrefix: brand.envPrefix }),
+        ...(brand.keychainEnv === undefined
+            ? {}
+            : { keychainEnv: brand.keychainEnv }),
+        ...(brand.keychainService === undefined
+            ? {}
+            : { keychainService: brand.keychainService }),
+        ...(brand.exampleServer === undefined
+            ? {}
+            : { exampleServer: brand.exampleServer }),
+        ...(brand.auth === undefined ? {} : { auth: brand.auth }),
+        ...(brand.manifestPath === undefined
+            ? {}
+            : { manifestPath: brand.manifestPath }),
+        ...(description === undefined ? {} : { description }),
+        version: info.version,
+        selfUpdate: { packageRoot: info.packageRoot, product: brand.bin },
+    };
+}
+/** The brand and package information of the packaged CLI at `packageRoot`, from its `package.json`. */
+export function readAppCliPackage(packageRoot) {
+    const manifest = JSON.parse(readFileSync(path.join(packageRoot, 'package.json'), 'utf8'));
+    const brand = manifest.nocobase?.cli;
+    if (brand === undefined ||
+        typeof brand !== 'object' ||
+        typeof brand.bin !== 'string')
+        throw new Error(`${path.join(packageRoot, 'package.json')} names no CLI under nocobase.cli.`);
+    return {
+        brand,
+        info: {
+            packageRoot,
+            version: typeof manifest.version === 'string' ? manifest.version : '0.0.0',
+            ...(typeof manifest.description === 'string'
+                ? { description: manifest.description }
+                : {}),
+        },
+    };
+}
+/** Runs the packaged CLI at `packageRoot`: the entry `nocobase cli build` and `nocobase cli link` generate. */
+export async function runAppCliPackage(packageRoot, argv = process.argv.slice(2)) {
+    const { brand, info } = readAppCliPackage(packageRoot);
+    await runAppCli(appCliConfigOf(brand, info), argv);
+}
+//# sourceMappingURL=brand.js.map

package/dist/brand.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"brand.js","sourceRoot":"","sources":["../src/brand.ts"],"names":[],"mappings":"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"}

package/dist/commands.d.ts

@@ -0,0 +1,9 @@
+import type { Command } from '@oclif/core';
+import type { AppCliConfig } from './config.ts';
+export declare const COMMANDS: Record<string, Command.Class>;
+/** The topics of the static commands, for help. */
+export declare const STATIC_TOPICS: Readonly<Record<string, {
+    description: string;
+}>>;
+export declare function defineCommands(config: AppCliConfig, extra?: Readonly<Record<string, Command.Class>>): void;
+//# sourceMappingURL=commands.d.ts.map

package/dist/commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../src/commands.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAG3C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAQhD,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,CAAM,CAAC;AAE1D,mDAAmD;AACnD,eAAO,MAAM,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE;IAAE,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,CAKzE,CAAC;AAEJ,wBAAgB,cAAc,CAC5B,MAAM,EAAE,YAAY,EACpB,KAAK,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,CAAM,GAClD,IAAI,CAiBN"}

package/dist/commands.js

@@ -0,0 +1,30 @@
+import { completionCommands } from "./completion.js";
+import { docsCommand } from "./docs.js";
+import { loginCommand } from "./login.js";
+import { logoutCommand } from "./logout.js";
+import { profileCommands } from "./profile.js";
+import { updateCommand } from "./update.js";
+import { whoamiCommand } from "./whoami.js";
+export const COMMANDS = {};
+/** The topics of the static commands, for help. */
+export const STATIC_TOPICS = {
+    profile: {
+        description: 'The servers you are signed in to, one profile each.',
+    },
+};
+export function defineCommands(config, extra = {}) {
+    for (const key of Object.keys(COMMANDS))
+        delete COMMANDS[key];
+    Object.assign(COMMANDS, {
+        login: loginCommand(config),
+        logout: logoutCommand(config),
+        whoami: whoamiCommand(config),
+        docs: docsCommand(config),
+        ...profileCommands(config),
+        ...completionCommands(config),
+        ...(config.selfUpdate === undefined
+            ? {}
+            : { update: updateCommand(config) }),
+    }, extra);
+}
+//# sourceMappingURL=commands.js.map

package/dist/commands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.js","sourceRoot":"","sources":["../src/commands.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAErD,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,MAAM,CAAC,MAAM,QAAQ,GAAkC,EAAE,CAAC;AAE1D,mDAAmD;AACnD,MAAM,CAAC,MAAM,aAAa,GACxB;IACE,OAAO,EAAE;QACP,WAAW,EAAE,qDAAqD;KACnE;CACF,CAAC;AAEJ,MAAM,UAAU,cAAc,CAC5B,MAAoB,EACpB,QAAiD,EAAE;IAEnD,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC;QAAE,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC;IAC9D,MAAM,CAAC,MAAM,CACX,QAAQ,EACR;QACE,KAAK,EAAE,YAAY,CAAC,MAAM,CAAC;QAC3B,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC;QAC7B,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC;QAC7B,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC;QACzB,GAAG,eAAe,CAAC,MAAM,CAAC;QAC1B,GAAG,kBAAkB,CAAC,MAAM,CAAC;QAC7B,GAAG,CAAC,MAAM,CAAC,UAAU,KAAK,SAAS;YACjC,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC,EAAE,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,EAAE,CAAC;KACvC,EACD,KAAK,CACN,CAAC;AACJ,CAAC"}

package/dist/completion.d.ts

@@ -0,0 +1,13 @@
+import { type Command } from '@oclif/core';
+import type { AppCliConfig } from './config.ts';
+import { type CliCommand } from './dynamic/manifest.ts';
+export declare const SHELLS: readonly string[];
+/** The script for `shell`, which calls `<bin> __complete -- <words…> <current>`. */
+export declare function completionScript(bin: string, shell: string): string;
+/**
+ * The words that may complete `current` after `words`: the next word of a command, a command's flags, or the values
+ * of the flag before it. `statics` are the static commands' ids (`profile:use`) with their flags.
+ */
+export declare function completeLine(words: readonly string[], current: string, statics: ReadonlyMap<string, readonly string[]>, commands: readonly CliCommand[]): string[];
+export declare function completionCommands(app: AppCliConfig): Record<string, Command.Class>;
+//# sourceMappingURL=completion.d.ts.map

package/dist/completion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"completion.d.ts","sourceRoot":"","sources":["../src/completion.ts"],"names":[],"mappings":"AAGA,OAAO,EAAiC,KAAK,OAAO,EAAE,MAAM,aAAa,CAAC;AAE1E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAsB,KAAK,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAK5E,eAAO,MAAM,MAAM,EAAE,SAAS,MAAM,EAA4B,CAAC;AAEjE,oFAAoF;AACpF,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAyBnE;AAwBD;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,EAC/C,QAAQ,EAAE,SAAS,UAAU,EAAE,GAC9B,MAAM,EAAE,CAoCV;AAED,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,YAAY,GAChB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,CA2D/B"}

package/dist/completion.js

@@ -0,0 +1,157 @@
+// Shell completion: `<bin> completion zsh|bash|fish` prints a script that asks `<bin> __complete` for the words that
+// may come next. Those come from the static commands and the cached command manifest (`dynamic/manifest.ts`), never
+// from the network, so completing is quick and works offline; the cache is refreshed by any command that runs.
+import { Args, Command as OclifCommand } from '@oclif/core';
+import { readCachedManifest } from "./dynamic/manifest.js";
+import { peekSession } from "./dynamic/session.js";
+import { AppCommand } from "./lib/command.js";
+import { GLOBAL_FLAG_HELP } from "./lib/globals.js";
+export const SHELLS = ['zsh', 'bash', 'fish'];
+/** The script for `shell`, which calls `<bin> __complete -- <words…> <current>`. */
+export function completionScript(bin, shell) {
+    const fn = `_${bin.replace(/[^A-Za-z0-9_]/gu, '_')}`;
+    switch (shell) {
+        case 'zsh':
+            return `#compdef ${bin}
+${fn}() {
+  local -a completions
+  completions=("\${(@f)$(${bin} __complete -- "\${(@)words[2,CURRENT-1]}" "\${words[CURRENT]}" 2>/dev/null)}")
+  compadd -a completions
+}
+compdef ${fn} ${bin}
+`;
+        case 'bash':
+            return `${fn}() {
+  local IFS=$'\\n'
+  COMPREPLY=($(${bin} __complete -- "\${COMP_WORDS[@]:1:COMP_CWORD-1}" "\${COMP_WORDS[COMP_CWORD]}" 2>/dev/null))
+}
+complete -o default -F ${fn} ${bin}
+`;
+        case 'fish':
+            return `complete -c ${bin} -f -a '(${bin} __complete -- (commandline -opc)[2..-1] (commandline -ct) 2>/dev/null)'
+`;
+        default:
+            throw new Error(`Not a shell: ${shell}`);
+    }
+}
+const GLOBAL_FLAGS = GLOBAL_FLAG_HELP.flatMap(([flag]) => flag
+    .split(/,\s*/u)
+    .map((part) => part.split(' ')[0])
+    .filter((part) => part.startsWith('--')));
+/** The flags of a manifest command, as typed. */
+function flagsOf(command) {
+    const flags = [];
+    for (const parameter of command.parameters) {
+        if (parameter.position !== undefined)
+            continue;
+        flags.push(`--${parameter.name}`);
+        if (parameter.contentFile)
+            flags.push(`--${parameter.name}-file`);
+    }
+    if (command.parameters.some((parameter) => parameter.fromEnv !== undefined))
+        flags.push('--from-env');
+    if (command.body?.file)
+        flags.push(`--${command.body.file}`);
+    if (command.output.kind === 'download')
+        flags.push('--out');
+    return flags;
+}
+/**
+ * The words that may complete `current` after `words`: the next word of a command, a command's flags, or the values
+ * of the flag before it. `statics` are the static commands' ids (`profile:use`) with their flags.
+ */
+export function completeLine(words, current, statics, commands) {
+    const typed = words.filter((word) => !word.startsWith('-'));
+    const byId = new Map(commands.map((command) => [command.id, command]));
+    let resolved;
+    for (let count = typed.length; count > 0 && !resolved; count -= 1) {
+        const id = typed.slice(0, count).join(':');
+        const command = byId.get(id);
+        if (command)
+            resolved = { flags: flagsOf(command), command };
+        else if (statics.has(id))
+            resolved = { flags: statics.get(id) };
+    }
+    if (resolved) {
+        const previous = words.at(-1);
+        const flag = previous?.startsWith('--')
+            ? resolved.command?.parameters.find((parameter) => `--${parameter.name}` === previous)
+            : undefined;
+        if (flag && flag.type !== 'boolean' && !current.startsWith('-'))
+            return (flag.enum ?? []).filter((value) => value.startsWith(current));
+        if (current !== '' && !current.startsWith('-'))
+            return [];
+        return [...new Set([...resolved.flags, ...GLOBAL_FLAGS])]
+            .filter((candidate) => candidate.startsWith(current))
+            .sort();
+    }
+    const ids = [...statics.keys(), ...commands.map((command) => command.id)].map((id) => id.split(':'));
+    const next = new Set();
+    for (const id of ids) {
+        if (id.length <= typed.length)
+            continue;
+        if (typed.every((word, index) => id[index] === word)) {
+            const word = id[typed.length];
+            if (word.startsWith(current) && !word.startsWith('_'))
+                next.add(word);
+        }
+    }
+    return [...next].sort();
+}
+export function completionCommands(app) {
+    class Completion extends AppCommand {
+        static summary = 'Print a shell completion script.';
+        static description = 'Completes commands and flags from the commands the server last offered you (the cached manifest), so it ' +
+            'works offline and follows your permissions after any command has run.\n\n' +
+            `zsh:  ${app.bin} completion zsh > "\${fpath[1]}/_${app.bin}"   (or: source <(${app.bin} completion zsh) in ~/.zshrc)\n` +
+            `bash: source <(${app.bin} completion bash)   in ~/.bashrc\n` +
+            `fish: ${app.bin} completion fish > ~/.config/fish/completions/${app.bin}.fish`;
+        static args = {
+            shell: Args.string({
+                description: 'The shell.',
+                options: [...SHELLS],
+                required: true,
+            }),
+        };
+        static examples = [`<%= config.bin %> completion zsh`];
+        async run() {
+            const { args } = await this.parse(Completion);
+            const script = completionScript(app.bin, args.shell);
+            if (!this.jsonEnabled())
+                process.stdout.write(script);
+            return { shell: args.shell, script };
+        }
+    }
+    // Not an AppCommand: it prints bare words for a shell, and never fails loudly.
+    class Complete extends OclifCommand {
+        static hidden = true;
+        static strict = false;
+        static summary = 'Answer a completion script.';
+        async run() {
+            const argv = [...this.argv];
+            if (argv[0] === '--')
+                argv.shift();
+            const current = argv.pop() ?? '';
+            const statics = new Map();
+            for (const command of this.config.commands) {
+                if (command.hidden)
+                    continue;
+                statics.set(command.id, Object.keys(command.flags ?? {}).map((name) => `--${name}`));
+            }
+            let commands;
+            try {
+                const session = await peekSession();
+                commands = session
+                    ? ((await readCachedManifest(session))?.commands ?? [])
+                    : [];
+            }
+            catch {
+                commands = [];
+            }
+            for (const word of completeLine(argv, current, statics, commands))
+                process.stdout.write(`${word}\n`);
+        }
+    }
+    return { completion: Completion, __complete: Complete };
+}
+//# sourceMappingURL=completion.js.map

package/dist/completion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"completion.js","sourceRoot":"","sources":["../src/completion.ts"],"names":[],"mappings":"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"}

package/dist/config.d.ts

@@ -0,0 +1,100 @@
+export interface AppCliConfig {
+    /** The command name, such as `acme`. */
+    readonly bin: string;
+    /** The application's name in messages, such as `Acme`. */
+    readonly displayName: string;
+    /** The directory under the home directory the CLI keeps its state in, such as `.acme`. */
+    readonly stateDir: string;
+    /** An environment variable that moves the state directory, such as `ACME_HOME`; tests use it. */
+    readonly homeEnv?: string;
+    /**
+     * Where a runner puts a run's credentials, relative to the run's working directory, such as `.acme/run.json`. The CLI
+     * finds the nearest one at or above its working directory and then acts as the run.
+     */
+    readonly runCredentialsFile: string;
+    /**
+     * The keychain service the person's credential (the session `login` signed in, or an API key) is kept under; `cliKeychainService(bin)` by default, such as `acme-cli`,
+     * which is also what a runner keeps agents away from.
+     */
+    readonly keychainService?: string;
+    /** An environment variable whose value `off` turns the keychain off, such as `ACME_KEYCHAIN`; the credential then goes into `config.json`. */
+    readonly keychainEnv?: string;
+    /**
+     * The prefix of the environment variables that act without signing in, such as `ACME` for `ACME_SERVER`,
+     * `ACME_API_KEY` and `ACME_PROFILE`; none are read without one.
+     */
+    readonly envPrefix?: string;
+    /**
+     * Signing in through the browser (`<bin> login` without a key), when the server offers it: Better Auth's device
+     * authorization (`deviceAuthorization()` and `bearer()` on the server).
+     */
+    readonly auth?: AppCliAuth;
+    /** The manifest path relative to the server's address; `CLI_ROUTES.manifest` by default. */
+    readonly manifestPath?: string;
+    /** Shown as `acme login --server <example>`. */
+    readonly exampleServer?: string;
+    /** What `--version` prints; this package's own version when left out. */
+    readonly version?: string;
+    /** The root help's description. */
+    readonly description?: string;
+    /**
+     * Asked, as the signed-in person, after `login` and after each business command's manifest fetch: a line saying a
+     * newer CLI is available, printed on stderr once, or undefined. It should be quick and remember what it found;
+     * whatever it throws is ignored.
+     */
+    readonly updateHint?: (session: AppCliSession) => Promise<string | undefined>;
+    /**
+     * How the CLI updates itself when the application's install script installed it: `<bin> update`, and the hint that a
+     * newer version is served when `updateHint` is left out (`update.ts`). Without it the CLI has no `update`.
+     */
+    readonly selfUpdate?: AppCliSelfUpdate;
+}
+/** What `<bin> update` needs to know of the CLI's own installation. */
+export interface AppCliSelfUpdate {
+    /**
+     * The root of the CLI's package as it runs, which is `<prefix>/versions/<version>` when the install script installed
+     * it (`install.ts`).
+     */
+    readonly packageRoot: string;
+    /** The product the application serves the CLI as (`DIST_ROUTES.resolve`); `bin` by default. */
+    readonly product?: string;
+}
+/** Where the signed-in person's requests go, and the headers that authenticate them. */
+export interface AppCliSession {
+    /** As configured: `https://host/app`. */
+    readonly server: string;
+    readonly headers: Readonly<Record<string, string>>;
+}
+/** The client id a CLI sends when its configuration names none. */
+export declare const DEFAULT_CLI_CLIENT_ID = "nocobase-cli";
+/** Better Auth's routes below the server's address, unless the configuration names others. */
+export declare const DEFAULT_AUTH_BASE_PATH = "/api/auth";
+/**
+ * How the CLI signs in through the browser (RFC 8628, Better Auth's `deviceAuthorization()`): it asks
+ * `<basePath>/device/code` for a code, the person approves it on the page the server names, and
+ * `<basePath>/device/token` answers a session token the CLI then sends as `Authorization: Bearer`; `logout` signs that
+ * session out (`<basePath>/sign-out`).
+ */
+export interface AppCliAuth {
+    /** The client id the server's `validateClient` accepts, such as `acme`; `DEFAULT_CLI_CLIENT_ID` when left out. */
+    readonly clientId?: string;
+    /** Better Auth's routes, relative to the server's address; `DEFAULT_AUTH_BASE_PATH` when left out. */
+    readonly basePath?: string;
+}
+/** The client id of `auth`. */
+export declare function cliClientIdOf(auth: AppCliAuth): string;
+/** `route` below Better Auth's base path, such as `/api/auth/device/code`. */
+export declare function authRouteOf(auth: AppCliAuth | undefined, route: string): string;
+export declare function configureAppCli(config: AppCliConfig): void;
+export declare function appCliConfig(): AppCliConfig;
+export declare function manifestPathOf(config: AppCliConfig): string;
+export interface AppCliPaths {
+    home: string;
+    /** The signed-in user and where their key is kept (0600). */
+    userConfig: string;
+    /** Cached command manifests. */
+    manifestCache: string;
+}
+export declare function appCliHome(config?: AppCliConfig, env?: NodeJS.ProcessEnv): string;
+export declare function appCliPaths(home?: string): AppCliPaths;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,YAAY;IAC3B,wCAAwC;IACxC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,0DAA0D;IAC1D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,0FAA0F;IAC1F,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,iGAAiG;IACjG,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC;;;OAGG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,8IAA8I;IAC9I,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC;IAC3B,4FAA4F;IAC5F,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,gDAAgD;IAChD,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,yEAAyE;IACzE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,mCAAmC;IACnC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAC9E;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,gBAAgB,CAAC;CACxC;AAED,uEAAuE;AACvE,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,+FAA+F;IAC/F,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,wFAAwF;AACxF,MAAM,WAAW,aAAa;IAC5B,yCAAyC;IACzC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACpD;AAED,mEAAmE;AACnE,eAAO,MAAM,qBAAqB,iBAAiB,CAAC;AAEpD,8FAA8F;AAC9F,eAAO,MAAM,sBAAsB,cAAc,CAAC;AAElD;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,kHAAkH;IAClH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,sGAAsG;IACtG,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,+BAA+B;AAC/B,wBAAgB,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAEtD;AAED,8EAA8E;AAC9E,wBAAgB,WAAW,CACzB,IAAI,EAAE,UAAU,GAAG,SAAS,EAC5B,KAAK,EAAE,MAAM,GACZ,MAAM,CAER;AAID,wBAAgB,eAAe,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAE1D;AAED,wBAAgB,YAAY,IAAI,YAAY,CAI3C;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAE3D;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,UAAU,EAAE,MAAM,CAAC;IACnB,gCAAgC;IAChC,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,wBAAgB,UAAU,CACxB,MAAM,GAAE,YAA6B,EACrC,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,CAMR;AAED,wBAAgB,WAAW,CAAC,IAAI,GAAE,MAAqB,GAAG,WAAW,CAMpE"}

package/dist/config.js

@@ -0,0 +1,43 @@
+// What makes the client an application's CLI: its command name, where it keeps state, and which file a run's
+// credentials are in. `runAppCli` takes one of these; everything else in src/client/ reads it through `appCliConfig()`.
+import os from 'node:os';
+import path from 'node:path';
+import { CLI_ROUTES } from '@nocobase/agent-protocol';
+/** The client id a CLI sends when its configuration names none. */
+export const DEFAULT_CLI_CLIENT_ID = 'nocobase-cli';
+/** Better Auth's routes below the server's address, unless the configuration names others. */
+export const DEFAULT_AUTH_BASE_PATH = '/api/auth';
+/** The client id of `auth`. */
+export function cliClientIdOf(auth) {
+    return auth.clientId ?? DEFAULT_CLI_CLIENT_ID;
+}
+/** `route` below Better Auth's base path, such as `/api/auth/device/code`. */
+export function authRouteOf(auth, route) {
+    return `${(auth?.basePath ?? DEFAULT_AUTH_BASE_PATH).replace(/\/+$/u, '')}${route}`;
+}
+let current;
+export function configureAppCli(config) {
+    current = config;
+}
+export function appCliConfig() {
+    if (current === undefined)
+        throw new Error('The CLI was started without runAppCli().');
+    return current;
+}
+export function manifestPathOf(config) {
+    return config.manifestPath ?? CLI_ROUTES.manifest;
+}
+export function appCliHome(config = appCliConfig(), env = process.env) {
+    const configured = config.homeEnv === undefined ? undefined : env[config.homeEnv];
+    return configured !== undefined && configured !== ''
+        ? path.resolve(configured)
+        : path.join(os.homedir(), config.stateDir);
+}
+export function appCliPaths(home = appCliHome()) {
+    return {
+        home,
+        userConfig: path.join(home, 'config.json'),
+        manifestCache: path.join(home, 'cache', 'manifests'),
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,6GAA6G;AAC7G,wHAAwH;AACxH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAwEtD,mEAAmE;AACnE,MAAM,CAAC,MAAM,qBAAqB,GAAG,cAAc,CAAC;AAEpD,8FAA8F;AAC9F,MAAM,CAAC,MAAM,sBAAsB,GAAG,WAAW,CAAC;AAelD,+BAA+B;AAC/B,MAAM,UAAU,aAAa,CAAC,IAAgB;IAC5C,OAAO,IAAI,CAAC,QAAQ,IAAI,qBAAqB,CAAC;AAChD,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,WAAW,CACzB,IAA4B,EAC5B,KAAa;IAEb,OAAO,GAAG,CAAC,IAAI,EAAE,QAAQ,IAAI,sBAAsB,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC;AACtF,CAAC;AAED,IAAI,OAAiC,CAAC;AAEtC,MAAM,UAAU,eAAe,CAAC,MAAoB;IAClD,OAAO,GAAG,MAAM,CAAC;AACnB,CAAC;AAED,MAAM,UAAU,YAAY;IAC1B,IAAI,OAAO,KAAK,SAAS;QACvB,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;IAC9D,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,MAAoB;IACjD,OAAO,MAAM,CAAC,YAAY,IAAI,UAAU,CAAC,QAAQ,CAAC;AACpD,CAAC;AAUD,MAAM,UAAU,UAAU,CACxB,SAAuB,YAAY,EAAE,EACrC,MAAyB,OAAO,CAAC,GAAG;IAEpC,MAAM,UAAU,GACd,MAAM,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACjE,OAAO,UAAU,KAAK,SAAS,IAAI,UAAU,KAAK,EAAE;QAClD,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC;QAC1B,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;AAC/C,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,OAAe,UAAU,EAAE;IACrD,OAAO;QACL,IAAI;QACJ,UAAU,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,aAAa,CAAC;QAC1C,aAAa,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,WAAW,CAAC;KACrD,CAAC;AACJ,CAAC"}

package/dist/docs.d.ts

@@ -0,0 +1,9 @@
+import { type Command } from '@oclif/core';
+import type { AppCliConfig } from './config.ts';
+import type { CliCommand, CliManifest } from './dynamic/manifest.ts';
+/** A command's documentation as text. */
+export declare function commandDocs(command: CliCommand, bin: string): string;
+/** How the CLI works, and the commands by area. */
+export declare function overviewDocs(manifest: CliManifest, app: AppCliConfig): string;
+export declare function docsCommand(app: AppCliConfig): Command.Class;
+//# sourceMappingURL=docs.d.ts.map

package/dist/docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../src/docs.ts"],"names":[],"mappings":"AAGA,OAAO,EAAc,KAAK,OAAO,EAAE,MAAM,aAAa,CAAC;AAIvD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAMhD,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAqBrE,yCAAyC;AACzC,wBAAgB,WAAW,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CA2BpE;AAED,mDAAmD;AACnD,wBAAgB,YAAY,CAAC,QAAQ,EAAE,WAAW,EAAE,GAAG,EAAE,YAAY,GAAG,MAAM,CA4B7E;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,KAAK,CA2E5D"}