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

package/dist/docs.js

@@ -0,0 +1,146 @@
+// `<bin> docs [command]`: a command's documentation, read from the server's manifest (or the cached one offline): its
+// help with what it answers, who may run it and the action it needs, and its examples; without a command, how the CLI
+// works and the commands by area. `--json` answers the same as data.
+import { Args, Help } from '@oclif/core';
+import { EXIT_CODES } from '@nocobase/agent-protocol';
+import { loadDynamic, resolveCommand, withheldCommand, } from "./dynamic/index.js";
+import { renderCommandHelp } from "./dynamic/output.js";
+import { AppCommand, UsageError } from "./lib/command.js";
+import { GLOBAL_FLAG_HELP } from "./lib/globals.js";
+const words = (id) => id.split(':').join(' ');
+/** What the command answers, in words. */
+function outputText(command) {
+    switch (command.output.kind) {
+        case 'list':
+            return `A list${command.output.columns?.length ? `, shown as a table of ${command.output.columns.join(', ')}` : ''}; \`--json\` has every field in \`result.data\` and paging in \`result.meta\`.`;
+        case 'download':
+            return 'A file, saved in the current directory under its own name or where `--out` says; `--json` answers where it went.';
+        case 'empty':
+            return 'Nothing: "Done." on success.';
+        default:
+            return 'One record, field by field; `--json` has it in `result.data`.';
+    }
+}
+/** A command's documentation as text. */
+export function commandDocs(command, bin) {
+    const who = command.identities.includes('run')
+        ? command.identities.includes('person')
+            ? 'People, and agents in a run'
+            : 'Only agents in a run'
+        : 'People (a sign-in or an API key)';
+    return [
+        renderCommandHelp(command),
+        '',
+        'OUTPUT',
+        `  ${outputText(command)}`,
+        '',
+        'WHO',
+        `  ${who}${command.action ? `, holding the action ${command.action}` : ''}.`,
+        ...(command.confirm
+            ? [
+                '',
+                'CONFIRMATION',
+                `  Asks "${command.confirm}" unless --yes is given.`,
+            ]
+            : []),
+        '',
+        'REQUEST',
+        `  ${command.method} ${command.path}${command.operationId ? ` (${command.operationId})` : ''}`,
+        '',
+        `Run \`${bin} ${words(command.id)} --json\` for the result as one JSON document.`,
+    ].join('\n');
+}
+/** How the CLI works, and the commands by area. */
+export function overviewDocs(manifest, app) {
+    const areas = new Map();
+    for (const command of manifest.commands) {
+        const area = command.id.split(':')[0];
+        areas.set(area, (areas.get(area) ?? 0) + 1);
+    }
+    const width = Math.max(...[...areas.keys()].map((area) => area.length), 4);
+    return [
+        `${app.displayName} on the command line: every command below is one API route, offered to ${manifest.identity.displayName}.`,
+        '',
+        'GETTING ABOUT',
+        `  ${app.bin} <area> --help              the commands of an area`,
+        `  ${app.bin} docs <command words>       a command's arguments, output, permission and examples`,
+        `  ${app.bin} whoami [--missing]         who you act as, and what needs an action you lack`,
+        `  ${app.bin} login | logout | profile   signing in, one profile per server`,
+        `  ${app.bin} completion zsh|bash|fish   shell completion`,
+        '',
+        'GLOBAL FLAGS',
+        ...GLOBAL_FLAG_HELP.map(([flag, text]) => `  ${flag.padEnd(18)}  ${text}`),
+        '',
+        'AREAS',
+        ...[...areas]
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([area, count]) => `  ${area.padEnd(width)}  ${count} command${count === 1 ? '' : 's'}`),
+    ].join('\n');
+}
+export function docsCommand(app) {
+    return class Docs extends AppCommand {
+        static summary = 'Show the documentation of a command, or of the CLI.';
+        static strict = false;
+        static args = {
+            command: Args.string({
+                description: "The command's words, such as `issue comment add`.",
+            }),
+        };
+        static examples = [
+            '<%= config.bin %> docs',
+            '<%= config.bin %> docs issue comment add',
+            '<%= config.bin %> docs issue comment add --json',
+        ];
+        async run() {
+            const { argv } = await this.parse(Docs);
+            const typed = argv.filter((word) => !word.startsWith('-'));
+            const id = typed.join(':');
+            const own = this.config.findCommand(id);
+            if (typed.length > 0 && own && !own.hidden) {
+                if (!this.jsonEnabled())
+                    await new Help(this.config).showHelp(typed);
+                return {
+                    command: own.id,
+                    summary: own.summary ?? null,
+                    description: own.description ?? null,
+                    examples: (own.examples ?? []).map(String),
+                    flags: Object.keys(own.flags ?? {}),
+                };
+            }
+            const context = await loadDynamic({ offline: true });
+            if (!context)
+                throw new UsageError(`Not signed in: the commands come from the server. Run \`${app.bin} login\` first.`, EXIT_CODES.auth);
+            if (typed.length === 0) {
+                this.log(overviewDocs(context.manifest, app));
+                return {
+                    identity: context.manifest.identity,
+                    commands: context.manifest.commands.map((command) => ({
+                        command: words(command.id),
+                        summary: command.summary,
+                    })),
+                };
+            }
+            const resolved = resolveCommand(context.manifest, typed);
+            if (!resolved) {
+                const withheld = withheldCommand(context.manifest, typed);
+                if (withheld)
+                    throw withheld;
+                const area = context.manifest.commands.filter((command) => command.id.startsWith(`${id}:`));
+                if (area.length === 0)
+                    throw new UsageError(`No command \`${app.bin} ${typed.join(' ')}\`. \`${app.bin} docs\` lists the areas.`, EXIT_CODES.notFound);
+                for (const command of area)
+                    this.log(`${app.bin} ${words(command.id).padEnd(32)}  ${command.summary}`);
+                return {
+                    commands: area.map((command) => ({
+                        command: words(command.id),
+                        summary: command.summary,
+                    })),
+                };
+            }
+            const text = commandDocs(resolved.command, app.bin);
+            this.log(text);
+            return { command: resolved.command, text };
+        }
+    };
+}
+//# sourceMappingURL=docs.js.map

package/dist/docs.js.map

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

package/dist/dynamic/execute.d.ts

@@ -0,0 +1,24 @@
+import { type DownloadResult } from '@nocobase/agent-protocol';
+/** A saved download: where it went, and a line saying so. */
+export interface Saved {
+    readonly data: DownloadResult;
+    readonly message: string;
+}
+export declare function send(url: URL, init: RequestInit, options: {
+    readonly fetch?: typeof fetch;
+    readonly timeoutMs?: number;
+}): Promise<unknown>;
+/** The file name a `content-disposition` gives, reduced to a plain name; `file` when it gives none. */
+export declare function filenameOf(disposition: string | null): string;
+/**
+ * Where a download goes: `out` when it names a file, inside it when it is a directory, the working directory
+ * otherwise. Only a file named outright is replaced; a name taken in a directory gets ` (2)`, ` (3)`… before its
+ * extension.
+ */
+export declare function downloadTarget(filename: string, out: string | undefined, cwd?: string): Promise<string>;
+/** Saves the file a `download` command answered where `out` says; a refusal is the error body as for any command. */
+export declare function download(url: URL, init: RequestInit, out: string | undefined, options: {
+    readonly fetch?: typeof fetch;
+    readonly timeoutMs?: number;
+}): Promise<Saved>;
+//# sourceMappingURL=execute.d.ts.map

package/dist/dynamic/execute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../../src/dynamic/execute.ts"],"names":[],"mappings":"AAUA,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAI9E,6DAA6D;AAC7D,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,wBAAsB,IAAI,CACxB,GAAG,EAAE,GAAG,EACR,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE;IAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GACtE,OAAO,CAAC,OAAO,CAAC,CAsClB;AAED,uGAAuG;AACvG,wBAAgB,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAoB7D;AAQD;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,GAAG,GAAE,MAAsB,GAC1B,OAAO,CAAC,MAAM,CAAC,CAUjB;AAED,qHAAqH;AACrH,wBAAsB,QAAQ,CAC5B,GAAG,EAAE,GAAG,EACR,IAAI,EAAE,WAAW,EACjB,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,OAAO,EAAE;IAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GACtE,OAAO,CAAC,KAAK,CAAC,CAiEhB"}

package/dist/dynamic/execute.js

@@ -0,0 +1,125 @@
+// Sending a command's request and reading its answer: `send` answers the parsed JSON body or throws the standard
+// error body as an `AppApiError`; `download` saves a file the request answers where `--out` says, never overwriting a
+// file unless that is the path given.
+import { createWriteStream } from 'node:fs';
+import { rename, rm, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { readErrorBody } from '@nocobase/agent-protocol';
+import { AppApiError } from "../lib/http.js";
+export async function send(url, init, options) {
+    let response;
+    try {
+        response = await (options.fetch ?? fetch)(url, {
+            ...init,
+            signal: AbortSignal.timeout(options.timeoutMs ?? 120_000),
+        });
+    }
+    catch (error) {
+        throw new AppApiError(0, 'NETWORK', `Could not reach ${url.origin}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const text = await response.text().catch(() => '');
+    let parsed;
+    try {
+        parsed = text === '' ? undefined : JSON.parse(text);
+    }
+    catch {
+        parsed = undefined;
+    }
+    if (!response.ok) {
+        const error = readErrorBody(parsed);
+        if (error)
+            throw new AppApiError(response.status, error.reason, error.message, error.metadata, error.status);
+        throw new AppApiError(response.status, `HTTP_${response.status}`, `${init.method ?? 'GET'} ${url.pathname} answered ${response.status}`);
+    }
+    return parsed;
+}
+/** The file name a `content-disposition` gives, reduced to a plain name; `file` when it gives none. */
+export function filenameOf(disposition) {
+    const extended = /filename\*\s*=\s*(?:UTF-8|utf-8)''([^;]+)/u.exec(disposition ?? '');
+    const plain = /filename\s*=\s*"?([^";]+)"?/u.exec(disposition ?? '');
+    const name = (() => {
+        try {
+            return extended?.[1]
+                ? decodeURIComponent(extended[1])
+                : (plain?.[1] ?? '');
+        }
+        catch {
+            return plain?.[1] ?? '';
+        }
+    })();
+    // Never a path: only the last segment, without controls, and never `.` or `..`.
+    const base = (name.split(/[\\/]/u).pop() ?? '')
+        // eslint-disable-next-line no-control-regex -- Strip controls from a name the server sent.
+        .replace(/[\u0000-\u001f\u007f]/gu, '')
+        .trim();
+    return base && base !== '.' && base !== '..' ? base : 'file';
+}
+const exists = (file) => stat(file).then(() => true, () => false);
+/**
+ * Where a download goes: `out` when it names a file, inside it when it is a directory, the working directory
+ * otherwise. Only a file named outright is replaced; a name taken in a directory gets ` (2)`, ` (3)`… before its
+ * extension.
+ */
+export async function downloadTarget(filename, out, cwd = process.cwd()) {
+    const info = out ? await stat(out).catch(() => undefined) : undefined;
+    if (out && !info?.isDirectory())
+        return out;
+    const dir = out ?? cwd;
+    const ext = path.extname(filename);
+    const stem = filename.slice(0, filename.length - ext.length);
+    let candidate = path.join(dir, filename);
+    for (let n = 2; await exists(candidate); n += 1)
+        candidate = path.join(dir, `${stem} (${n})${ext}`);
+    return candidate;
+}
+/** Saves the file a `download` command answered where `out` says; a refusal is the error body as for any command. */
+export async function download(url, init, out, options) {
+    let response;
+    try {
+        response = await (options.fetch ?? fetch)(url, {
+            ...init,
+            signal: AbortSignal.timeout(options.timeoutMs ?? 30 * 60_000),
+        });
+    }
+    catch (error) {
+        throw new AppApiError(0, 'NETWORK', `Could not reach ${url.origin}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!response.ok || !response.body) {
+        const text = await response.text().catch(() => '');
+        let parsed;
+        try {
+            parsed = text === '' ? undefined : JSON.parse(text);
+        }
+        catch {
+            parsed = undefined;
+        }
+        const error = readErrorBody(parsed);
+        if (error)
+            throw new AppApiError(response.status, error.reason, error.message, error.metadata, error.status);
+        throw new AppApiError(response.status, `HTTP_${response.status}`, `${init.method ?? 'GET'} ${url.pathname} answered ${response.status}`);
+    }
+    const filename = filenameOf(response.headers.get('content-disposition'));
+    const target = await downloadTarget(filename, out);
+    // Written beside the target and moved into place, so a broken download never leaves half a file under its name.
+    const partial = `${target}.part-${process.pid}`;
+    try {
+        await pipeline(Readable.fromWeb(response.body), createWriteStream(partial, { flags: 'wx' }));
+        await rename(partial, target);
+    }
+    catch (error) {
+        await rm(partial, { force: true });
+        throw new AppApiError(0, 'DOWNLOAD_FAILED', `Could not save ${filename} to ${target}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const size = (await stat(target)).size;
+    const data = {
+        path: target,
+        filename,
+        mimeType: response.headers.get('content-type')?.split(';')[0]?.trim() ??
+            'application/octet-stream',
+        size,
+    };
+    return { data, message: `Saved ${filename} (${size} bytes) to ${target}.` };
+}
+//# sourceMappingURL=execute.js.map

package/dist/dynamic/execute.js.map

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

package/dist/dynamic/files.d.ts

@@ -0,0 +1,21 @@
+/** Where to look and what to send, as the manifest describes it. */
+export interface ChangedFilesSpec {
+    /** Relative, such as `.nocobase-runner/knowledge`. */
+    readonly dir: string;
+    /** Inside `dir`: a JSON array of `{ path, hash }`. */
+    readonly manifest: string;
+    readonly maxBytes: number;
+    readonly maxFiles: number;
+    /** Extensions such as `.md`; any when absent. */
+    readonly accept?: readonly string[];
+}
+/** A file on this machine and the name it is sent under. */
+export interface LocalFile {
+    readonly path: string;
+    /** Its base name, or for a changed file its path inside the directory. */
+    readonly name: string;
+    readonly size: number;
+}
+/** The files of the directory that differ from its manifest, or that it does not list; `flag` names them in errors. */
+export declare function changedFiles(spec: ChangedFilesSpec, flag: string, cwd: string): Promise<LocalFile[]>;
+//# sourceMappingURL=files.d.ts.map

package/dist/dynamic/files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"files.d.ts","sourceRoot":"","sources":["../../src/dynamic/files.ts"],"names":[],"mappings":"AAYA,oEAAoE;AACpE,MAAM,WAAW,gBAAgB;IAC/B,sDAAsD;IACtD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,iDAAiD;IACjD,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,4DAA4D;AAC5D,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAgCD,uHAAuH;AACvH,wBAAsB,YAAY,CAChC,IAAI,EAAE,gBAAgB,EACtB,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,SAAS,EAAE,CAAC,CA6CtB"}

package/dist/dynamic/files.js

@@ -0,0 +1,79 @@
+// The changed files of a directory on this machine (`changed` on a manifest parameter): found at the working
+// directory or above it, compared with the manifest the directory holds by SHA-256, and sent with the request as
+// multipart parts named by their paths inside the directory.
+import { createHash } from 'node:crypto';
+import { readdir, readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { EXIT_CODES } from '@nocobase/agent-protocol';
+import { UsageError } from "../lib/command.js";
+import { accepts } from "../parse/arguments.js";
+const invalid = (message) => new UsageError(message, EXIT_CODES.validation);
+/** `dir` at `cwd` or the nearest directory above it; undefined when there is none. */
+async function findUp(cwd, dir) {
+    for (let current = path.resolve(cwd);;) {
+        const candidate = path.join(current, dir);
+        if ((await stat(candidate).catch(() => undefined))?.isDirectory())
+            return candidate;
+        const parent = path.dirname(current);
+        if (parent === current)
+            return undefined;
+        current = parent;
+    }
+}
+/** Every file under `root` except names starting with a dot, by its path inside `root` with `/` separators. */
+async function filesUnder(root, inside = '') {
+    const entries = await readdir(path.join(root, inside), {
+        withFileTypes: true,
+    });
+    const found = [];
+    for (const entry of entries) {
+        if (entry.name.startsWith('.'))
+            continue;
+        const relative = inside ? `${inside}/${entry.name}` : entry.name;
+        if (entry.isDirectory())
+            found.push(...(await filesUnder(root, relative)));
+        else if (entry.isFile())
+            found.push(relative);
+    }
+    return found.sort();
+}
+/** The files of the directory that differ from its manifest, or that it does not list; `flag` names them in errors. */
+export async function changedFiles(spec, flag, cwd) {
+    const root = await findUp(cwd, spec.dir);
+    if (!root)
+        throw invalid(`--${flag}: no ${spec.dir} directory here or above; this run has none.`);
+    let listed;
+    try {
+        const manifest = JSON.parse(await readFile(path.join(root, spec.manifest), 'utf8'));
+        if (!Array.isArray(manifest))
+            throw new Error('not a list');
+        listed = new Map(manifest.flatMap((entry) => {
+            const item = entry;
+            return typeof item.path === 'string' && typeof item.hash === 'string'
+                ? [[item.path, item.hash]]
+                : [];
+        }));
+    }
+    catch {
+        throw invalid(`--${flag}: cannot read ${path.join(spec.dir, spec.manifest)}.`);
+    }
+    const changed = [];
+    for (const relative of await filesUnder(root)) {
+        if (spec.accept && !accepts(spec.accept, relative))
+            continue;
+        const full = path.join(root, relative);
+        const bytes = await readFile(full);
+        const hash = createHash('sha256').update(bytes).digest('hex');
+        if (listed.get(relative) === hash)
+            continue;
+        if (bytes.length > spec.maxBytes)
+            throw invalid(`${path.join(spec.dir, relative)} is larger than ${spec.maxBytes} bytes.`);
+        changed.push({ path: full, name: relative, size: bytes.length });
+    }
+    if (changed.length === 0)
+        throw invalid(`--${flag}: nothing changed in ${spec.dir}.`);
+    if (changed.length > spec.maxFiles)
+        throw invalid(`--${flag}: ${changed.length} files changed in ${spec.dir}; send at most ${spec.maxFiles} at once (${changed.map((file) => file.name).join(', ')}).`);
+    return changed;
+}
+//# sourceMappingURL=files.js.map

package/dist/dynamic/files.js.map

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

package/dist/dynamic/help.d.ts

@@ -0,0 +1,6 @@
+import { Help } from '@oclif/core';
+export default class AppCliHelp extends Help {
+    showHelp(argv: string[]): Promise<void>;
+    private showBusinessCommands;
+}
+//# sourceMappingURL=help.d.ts.map

package/dist/dynamic/help.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../../src/dynamic/help.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAOnC,MAAM,CAAC,OAAO,OAAO,UAAW,SAAQ,IAAI;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;YA4BxC,oBAAoB;CAYnC"}

package/dist/dynamic/help.js

@@ -0,0 +1,42 @@
+// The CLI's help class. oclif renders help itself and refuses a command it does not know, so `<bin> issue comment add
+// --help` would never reach the manifest: this class answers the static commands as oclif does, and the business
+// commands (and their topics) from the manifest. The root help lists the business commands too, when the manifest can
+// be had.
+import { Help } from '@oclif/core';
+import { GLOBAL_FLAG_HELP } from "../lib/globals.js";
+import { renderCommandList } from "./output.js";
+import { getOriginalArgv, loadDynamic, runDynamic } from "./index.js";
+import { leadingWords } from "./parse.js";
+export default class AppCliHelp extends Help {
+    async showHelp(argv) {
+        const words = leadingWords(argv.filter((word) => word !== '--help' && word !== '-h'));
+        const id = words.join(':');
+        if (words.length === 0 ||
+            this.config.findCommand(id) !== undefined ||
+            this.config.findTopic(id) !== undefined) {
+            await super.showHelp(argv);
+            if (words.length === 0) {
+                await this.showBusinessCommands();
+                this.log(`\nGLOBAL FLAGS\n${GLOBAL_FLAG_HELP.map(([flag, text]) => `  ${flag.padEnd(18)}  ${text}`).join('\n')}`);
+            }
+            return;
+        }
+        // oclif's argv may have lost words with `:` in them; the original line is exact.
+        const original = getOriginalArgv();
+        await runDynamic(original.includes('--help') || original.includes('-h')
+            ? original
+            : [...words, '--help']);
+    }
+    async showBusinessCommands() {
+        try {
+            const context = await loadDynamic({ offline: true });
+            const list = context ? renderCommandList(context.manifest) : undefined;
+            if (list)
+                this.log(`\nBUSINESS COMMANDS (from ${context.session.server})\n${list}`);
+        }
+        catch {
+            // Without a server, the static commands are the whole help.
+        }
+    }
+}
+//# sourceMappingURL=help.js.map

package/dist/dynamic/help.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.js","sourceRoot":"","sources":["../../src/dynamic/help.ts"],"names":[],"mappings":"AAAA,sHAAsH;AACtH,iHAAiH;AACjH,sHAAsH;AACtH,UAAU;AACV,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAEnC,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACtE,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C,MAAM,CAAC,OAAO,OAAO,UAAW,SAAQ,IAAI;IACjC,KAAK,CAAC,QAAQ,CAAC,IAAc;QACpC,MAAM,KAAK,GAAG,YAAY,CACxB,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,CAAC,CAC1D,CAAC;QACF,MAAM,EAAE,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC3B,IACE,KAAK,CAAC,MAAM,KAAK,CAAC;YAClB,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC,KAAK,SAAS;YACzC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,KAAK,SAAS,EACvC,CAAC;YACD,MAAM,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;YAC3B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACvB,MAAM,IAAI,CAAC,oBAAoB,EAAE,CAAC;gBAClC,IAAI,CAAC,GAAG,CACN,mBAAmB,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,KAAK,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACxG,CAAC;YACJ,CAAC;YACD,OAAO;QACT,CAAC;QACD,iFAAiF;QACjF,MAAM,QAAQ,GAAG,eAAe,EAAE,CAAC;QACnC,MAAM,UAAU,CACd,QAAQ,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC;YACpD,CAAC,CAAC,QAAQ;YACV,CAAC,CAAC,CAAC,GAAG,KAAK,EAAE,QAAQ,CAAC,CACzB,CAAC;IACJ,CAAC;IAEO,KAAK,CAAC,oBAAoB;QAChC,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;YACrD,MAAM,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC,iBAAiB,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;YACvE,IAAI,IAAI;gBACN,IAAI,CAAC,GAAG,CACN,6BAA6B,OAAQ,CAAC,OAAO,CAAC,MAAM,MAAM,IAAI,EAAE,CACjE,CAAC;QACN,CAAC;QAAC,MAAM,CAAC;YACP,4DAA4D;QAC9D,CAAC;IACH,CAAC;CACF"}

package/dist/dynamic/index.d.ts

@@ -0,0 +1,34 @@
+import { CliCommandError } from '../lib/envelope.ts';
+import { type CliCommand, type CliManifest } from './manifest.ts';
+import { type Session } from './session.ts';
+/** Records the argv the CLI was started with (`runAppCli`). */
+export declare function setOriginalArgv(argv: readonly string[]): void;
+export declare function getOriginalArgv(): readonly string[];
+/**
+ * Why a command the line names is not offered, when the server describes it: another identity's, or needing an
+ * action the caller does not hold. Undefined when the server knows no such command.
+ */
+export declare function withheldCommand(manifest: CliManifest, argv: readonly string[]): CliCommandError | undefined;
+export interface DynamicContext {
+    readonly session: Session;
+    readonly manifest: CliManifest;
+}
+/** The session and its manifest, or undefined when the CLI is neither in a run nor signed in. */
+export declare function loadDynamic(options?: {
+    readonly offline?: boolean;
+}): Promise<DynamicContext | undefined>;
+export interface Resolved {
+    readonly command: CliCommand;
+    /** What follows the command's words. */
+    readonly rest: readonly string[];
+}
+/**
+ * The manifest command the line starts with, by its longest match. oclif splits words holding `:` and folds positional
+ * words into the command id, so the original argv is the only exact source.
+ */
+export declare function resolveCommand(manifest: CliManifest, argv: readonly string[]): Resolved | undefined;
+/** The help for a business command or a topic of them; undefined when the manifest has neither. */
+export declare function dynamicHelp(manifest: CliManifest, argv: readonly string[]): string | undefined;
+/** Runs the business command `argv` names; writes its output; throws a `CLIError` on failure. */
+export declare function runDynamic(argv: readonly string[], write?: (text: string) => void): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/dynamic/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/dynamic/index.ts"],"names":[],"mappings":"AAaA,OAAO,EACL,eAAe,EAGhB,MAAM,oBAAoB,CAAC;AAI5B,OAAO,EAAgB,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AAIhF,OAAO,EAAkB,KAAK,OAAO,EAAE,MAAM,cAAc,CAAC;AAI5D,+DAA+D;AAC/D,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAE7D;AAED,wBAAgB,eAAe,IAAI,SAAS,MAAM,EAAE,CAEnD;AAcD;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,WAAW,EACrB,IAAI,EAAE,SAAS,MAAM,EAAE,GACtB,eAAe,GAAG,SAAS,CA8C7B;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;CAChC;AAED,iGAAiG;AACjG,wBAAsB,WAAW,CAC/B,OAAO,GAAE;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAO,GAC3C,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAIrC;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,wCAAwC;IACxC,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,WAAW,EACrB,IAAI,EAAE,SAAS,MAAM,EAAE,GACtB,QAAQ,GAAG,SAAS,CAUtB;AAED,mGAAmG;AACnG,wBAAgB,WAAW,CACzB,QAAQ,EAAE,WAAW,EACrB,IAAI,EAAE,SAAS,MAAM,EAAE,GACtB,MAAM,GAAG,SAAS,CAIpB;AA2BD,iGAAiG;AACjG,wBAAsB,UAAU,CAC9B,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,KAAK,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAkD,GAC1E,OAAO,CAAC,IAAI,CAAC,CAyCf"}