@antasphere/chassis-cli 0.0.0-stage → 1.0.0

package/dist/identity.d.ts

@@ -0,0 +1,36 @@
+import type { ToolIdentity } from '@antasphere/chassis-contract';
+/**
+ * What a tool is called, in every place the generic CLI spells it. ONE object,
+ * passed by the tool to `defineCli` (index.ts): the chassis holds no product
+ * literal of its own, so each field below is read where the literal used to
+ * sit and the bytes a person or a script sees are the tool's own.
+ */
+export interface CliIdentity {
+    /** The binary's name: `program.name()`, and every `\`<bin> …\`` hint. */
+    bin: string;
+    /** The tool's namespace in the shared config home, and its cli-core connect name. */
+    tool: string;
+    /** The pre-cli-core config directory (`$XDG_CONFIG_HOME/<dir>/config.json`), imported once. */
+    legacyConfigDir: string;
+    /** The product's name in a sentence. */
+    displayName: string;
+    /** The environment variables' prefix: `<PREFIX>_URL`, `<PREFIX>_API_KEY`, `<PREFIX>_WORKSPACE`. */
+    envPrefix: string;
+    /** The API key prefix, without the underscore: `<prefix>_…`. */
+    keyPrefix: string;
+    /** The scope a key needs for the full-workspace export, as `export --help` names it. */
+    exportScope: string;
+    /**
+     * The tool's cloud home (`identity.cloud.url`): the last step of the URL
+     * resolution and the instance of the implicit `cloud` profile, so a clean
+     * machine with an `antasphere login` needs no flag (PRDCT-2947).
+     */
+    cloudUrl: string;
+}
+/**
+ * The CLI's identity, BUILT from the tool's one definition (`ToolIdentity`,
+ * written in the tool's contract package): a tool passes
+ * `cliIdentity(IDENTITY)` to `defineCli` and spells nothing a second time.
+ */
+export declare function cliIdentity(identity: ToolIdentity): CliIdentity;
+//# sourceMappingURL=identity.d.ts.map

package/dist/identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAEjE;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,yEAAyE;IACzE,GAAG,EAAE,MAAM,CAAC;IACZ,qFAAqF;IACrF,IAAI,EAAE,MAAM,CAAC;IACb,+FAA+F;IAC/F,eAAe,EAAE,MAAM,CAAC;IACxB,wCAAwC;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,mGAAmG;IACnG,SAAS,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAC;IAClB,wFAAwF;IACxF,WAAW,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,YAAY,GAAG,WAAW,CAW/D"}

package/dist/identity.js

@@ -0,0 +1,18 @@
+/**
+ * The CLI's identity, BUILT from the tool's one definition (`ToolIdentity`,
+ * written in the tool's contract package): a tool passes
+ * `cliIdentity(IDENTITY)` to `defineCli` and spells nothing a second time.
+ */
+export function cliIdentity(identity) {
+    return {
+        bin: identity.cli.bin,
+        tool: identity.slug,
+        legacyConfigDir: identity.cli.legacyConfigDir,
+        displayName: identity.displayName,
+        envPrefix: identity.cli.envPrefix,
+        keyPrefix: identity.apiKeyPrefix,
+        exportScope: identity.scopes.dataExport,
+        cloudUrl: identity.cloud.url
+    };
+}
+//# sourceMappingURL=identity.js.map

package/dist/identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.js","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"AA+BA;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,QAAsB;IAChD,OAAO;QACL,GAAG,EAAE,QAAQ,CAAC,GAAG,CAAC,GAAG;QACrB,IAAI,EAAE,QAAQ,CAAC,IAAI;QACnB,eAAe,EAAE,QAAQ,CAAC,GAAG,CAAC,eAAe;QAC7C,WAAW,EAAE,QAAQ,CAAC,WAAW;QACjC,SAAS,EAAE,QAAQ,CAAC,GAAG,CAAC,SAAS;QACjC,SAAS,EAAE,QAAQ,CAAC,YAAY;QAChC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,UAAU;QACvC,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAC,GAAG;KAC7B,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+import type { ChassisClient } from '@antasphere/chassis-sdk';
+import type { Cli, CliDefinition } from './kit.js';
+/**
+ * `@antasphere/chassis-cli`: the generic half of a tool's command line. The
+ * profiles and the config file, the context (instance, key, workspace), the
+ * workspace selection, secrets on stdin, the contained writes, the browser
+ * opener, the generic command groups, the program and the runner. A tool
+ * instantiates it ONCE (`defineCli`) with its identity and its client, and
+ * its command modules read the kit that comes back.
+ */
+export { cliIdentity, type CliIdentity } from './identity.js';
+export { redactKey, type CliConfigStore } from './config.js';
+export type { CliConfig, CliConnectKey, CliEnv, CliProfile } from './config.js';
+export { CliUsageError, fmtBytes, printJson, sanitizeForTty, setStdinApiKey, stdinApiKey, table, ttySafeIo, type CliContext, type CliContextKit, type CliIo, type CredentialSource } from './context.js';
+export { findWorkspace, isWorkspaceId, matchWorkspace, workspaceLines, type CliWorkspace, type MeResponse, type MeWorkspace, type SelectionKind, type WorkspaceSelection, type WorkspaceSource } from './workspace.js';
+export { readSecretFromStdin } from './stdin.js';
+export { resolveInside, streamContained, UnsafeWriteError, writeContained, writeNoFollow } from './safe-write.js';
+export { isInteractive, openInBrowser, platformOpener } from './open.js';
+export { safeDownloadName } from './commands/files.js';
+export { explainProjectRefusal, roleNamedBy, memberRef, type ProjectLookup } from './commands/projects.js';
+export { CliApiRefusal, drainPages } from './context.js';
+export type { Cli, CliDefinition, CliKit, RegisterTool } from './kit.js';
+export declare function defineCli<TClient extends ChassisClient<string>>(definition: CliDefinition<TClient>): Cli<TClient>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAG7D,OAAO,KAAK,EAAE,GAAG,EAAE,aAAa,EAAU,MAAM,UAAU,CAAC;AAI3D;;;;;;;GAOG;AAEH,OAAO,EAAE,WAAW,EAAE,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AAC9D,OAAO,EAAE,SAAS,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7D,YAAY,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAChF,OAAO,EACL,aAAa,EACb,QAAQ,EACR,SAAS,EACT,cAAc,EACd,cAAc,EACd,WAAW,EACX,KAAK,EACL,SAAS,EACT,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,KAAK,EACV,KAAK,gBAAgB,EACtB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,aAAa,EACb,aAAa,EACb,cAAc,EACd,cAAc,EACd,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACrB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EACL,aAAa,EACb,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,aAAa,EACd,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAE,qBAAqB,EAAE,WAAW,EAAE,SAAS,EAAE,KAAK,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAC3G,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AACzD,YAAY,EAAE,GAAG,EAAE,aAAa,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAEzE,wBAAgB,SAAS,CAAC,OAAO,SAAS,aAAa,CAAC,MAAM,CAAC,EAC7D,UAAU,EAAE,aAAa,CAAC,OAAO,CAAC,GACjC,GAAG,CAAC,OAAO,CAAC,CAOd"}

package/dist/index.js

@@ -0,0 +1,31 @@
+import { createConfig } from './config.js';
+import { createContext } from './context.js';
+import { createProgram } from './program.js';
+import { createWorkspace } from './workspace.js';
+/**
+ * `@antasphere/chassis-cli`: the generic half of a tool's command line. The
+ * profiles and the config file, the context (instance, key, workspace), the
+ * workspace selection, secrets on stdin, the contained writes, the browser
+ * opener, the generic command groups, the program and the runner. A tool
+ * instantiates it ONCE (`defineCli`) with its identity and its client, and
+ * its command modules read the kit that comes back.
+ */
+export { cliIdentity } from './identity.js';
+export { redactKey } from './config.js';
+export { CliUsageError, fmtBytes, printJson, sanitizeForTty, setStdinApiKey, stdinApiKey, table, ttySafeIo } from './context.js';
+export { findWorkspace, isWorkspaceId, matchWorkspace, workspaceLines } from './workspace.js';
+export { readSecretFromStdin } from './stdin.js';
+export { resolveInside, streamContained, UnsafeWriteError, writeContained, writeNoFollow } from './safe-write.js';
+export { isInteractive, openInBrowser, platformOpener } from './open.js';
+export { safeDownloadName } from './commands/files.js';
+export { explainProjectRefusal, roleNamedBy, memberRef } from './commands/projects.js';
+export { CliApiRefusal, drainPages } from './context.js';
+export function defineCli(definition) {
+    const { identity, createClient } = definition;
+    const config = createConfig(identity);
+    const workspace = createWorkspace(identity);
+    const context = createContext({ identity, createClient, config, workspace });
+    const kit = { identity, createClient, ...config, workspace, ...context };
+    return { ...kit, ...createProgram(kit, definition) };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEjD;;;;;;;GAOG;AAEH,OAAO,EAAE,WAAW,EAAoB,MAAM,eAAe,CAAC;AAC9D,OAAO,EAAE,SAAS,EAAuB,MAAM,aAAa,CAAC;AAE7D,OAAO,EACL,aAAa,EACb,QAAQ,EACR,SAAS,EACT,cAAc,EACd,cAAc,EACd,WAAW,EACX,KAAK,EACL,SAAS,EAKV,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,aAAa,EACb,aAAa,EACb,cAAc,EACd,cAAc,EAOf,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EACL,aAAa,EACb,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,aAAa,EACd,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAE,qBAAqB,EAAE,WAAW,EAAE,SAAS,EAAsB,MAAM,wBAAwB,CAAC;AAC3G,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAGzD,MAAM,UAAU,SAAS,CACvB,UAAkC;IAElC,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,GAAG,UAAU,CAAC;IAC9C,MAAM,MAAM,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;IACtC,MAAM,SAAS,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAC;IAC5C,MAAM,OAAO,GAAG,aAAa,CAAC,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;IAC7E,MAAM,GAAG,GAAoB,EAAE,QAAQ,EAAE,YAAY,EAAE,GAAG,MAAM,EAAE,SAAS,EAAE,GAAG,OAAO,EAAE,CAAC;IAC1F,OAAO,EAAE,GAAG,GAAG,EAAE,GAAG,aAAa,CAAC,GAAG,EAAE,UAAU,CAAC,EAAE,CAAC;AACvD,CAAC"}

package/dist/kit.d.ts

@@ -0,0 +1,46 @@
+import type { CliAuthError } from '@antasphere/cli-core';
+import type { ChassisClient, ClientOptions, PlatformApiError } from '@antasphere/chassis-sdk';
+import type { Command } from 'commander';
+import type { CliConfigStore } from './config.js';
+import type { CliContextKit, CliIo } from './context.js';
+import type { CliIdentity } from './identity.js';
+import type { CliWorkspace } from './workspace.js';
+/** The tool's hook in the command tree: it registers its own groups on the program. */
+export type RegisterTool = (program: Command, io: CliIo) => void;
+export interface CliDefinition<TClient extends ChassisClient<string>> {
+    /** What the tool is called, everywhere the generic CLI spells it (identity.ts). */
+    identity: CliIdentity;
+    /** The program's one-line description (`--help`'s first line after the usage). */
+    description: string;
+    /** The tool's client: every place the generic CLI builds one goes through this. */
+    createClient: (options: ClientOptions) => TClient;
+    /**
+     * The tool's own hint for a refused request, as it is appended to the error
+     * line (leading space and parentheses included), or undefined for none. The
+     * runner asks after the 403 hint and before the 401 one.
+     */
+    errorHint?: (e: PlatformApiError | CliAuthError) => string | undefined;
+}
+/** The generic functions bound to one tool, as the command modules read them. */
+export interface CliKit<TClient extends ChassisClient<string>> extends CliConfigStore, CliContextKit<TClient> {
+    identity: CliIdentity;
+    createClient: (options: ClientOptions) => TClient;
+    /** The workspace functions that spell the tool (workspace.ts). */
+    workspace: CliWorkspace;
+}
+/** What `defineCli` hands back: the kit, plus the program and the runner. */
+export interface Cli<TClient extends ChassisClient<string>> extends CliKit<TClient> {
+    /**
+     * The command tree, built once per run: the global options, the auth,
+     * workspace, project and demo groups, THE TOOL'S GROUPS, then
+     * instance/export/files, and the completion command last (it prints the
+     * tree, so it must see all of it).
+     */
+    buildProgram(io: CliIo, registerTool: RegisterTool, version: string): Command;
+    /**
+     * Run the CLI with injected I/O and return a process exit code. The bin calls
+     * this with real process streams; tests call it in-process.
+     */
+    run(argv: string[], rawIo: CliIo, registerTool: RegisterTool, version: string): Promise<number>;
+}
+//# sourceMappingURL=kit.d.ts.map

package/dist/kit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kit.d.ts","sourceRoot":"","sources":["../src/kit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC9F,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AACzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD,uFAAuF;AACvF,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,KAAK,KAAK,IAAI,CAAC;AAEjE,MAAM,WAAW,aAAa,CAAC,OAAO,SAAS,aAAa,CAAC,MAAM,CAAC;IAClE,mFAAmF;IACnF,QAAQ,EAAE,WAAW,CAAC;IACtB,kFAAkF;IAClF,WAAW,EAAE,MAAM,CAAC;IACpB,mFAAmF;IACnF,YAAY,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,OAAO,CAAC;IAClD;;;;OAIG;IACH,SAAS,CAAC,EAAE,CAAC,CAAC,EAAE,gBAAgB,GAAG,YAAY,KAAK,MAAM,GAAG,SAAS,CAAC;CACxE;AAED,iFAAiF;AACjF,MAAM,WAAW,MAAM,CAAC,OAAO,SAAS,aAAa,CAAC,MAAM,CAAC,CAC3D,SAAQ,cAAc,EAAE,aAAa,CAAC,OAAO,CAAC;IAC9C,QAAQ,EAAE,WAAW,CAAC;IACtB,YAAY,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,OAAO,CAAC;IAClD,kEAAkE;IAClE,SAAS,EAAE,YAAY,CAAC;CACzB;AAED,6EAA6E;AAC7E,MAAM,WAAW,GAAG,CAAC,OAAO,SAAS,aAAa,CAAC,MAAM,CAAC,CAAE,SAAQ,MAAM,CAAC,OAAO,CAAC;IACjF;;;;;OAKG;IACH,YAAY,CAAC,EAAE,EAAE,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;IAC9E;;;OAGG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACjG"}

package/dist/kit.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=kit.js.map

package/dist/kit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kit.js","sourceRoot":"","sources":["../src/kit.ts"],"names":[],"mappings":""}

package/dist/open.d.ts

@@ -0,0 +1,27 @@
+import { spawn } from 'node:child_process';
+import type { CliIo } from './context.js';
+/**
+ * Opening a URL in the person's default browser (PRDCT-2280): the first push
+ * of a folder opens the pushed resource's page, the tool's `open` command opens
+ * it on demand, its `dev` command opens the local preview.
+ *
+ * The URL is always ONE argv item handed to the platform's opener binary,
+ * never a string a shell interprets: a resource title or an instance URL is
+ * somebody else's text, and `sh -c "open $url"` would run whatever it
+ * carries. On Windows `start` is a cmd.exe builtin that `spawn` cannot run
+ * without a shell, so the URL handler is invoked through `rundll32`
+ * instead, which is a real executable taking the URL as an argument.
+ */
+export declare function platformOpener(platform?: NodeJS.Platform): {
+    command: string;
+    args: string[];
+};
+/**
+ * Best effort: a missing opener (a headless box) must never fail the
+ * command that already did its real work. The runner can inject `io.openUrl`
+ * (tests record the call; nothing is spawned).
+ */
+export declare function openInBrowser(io: CliIo, url: string, spawnImpl?: typeof spawn): void;
+/** A stdout that is a terminal: the only place a browser may pop up unasked. */
+export declare function isInteractive(io: CliIo): boolean;
+//# sourceMappingURL=open.d.ts.map

package/dist/open.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"open.d.ts","sourceRoot":"","sources":["../src/open.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAE1C;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAAG;IAC5E,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB,CAIA;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,GAAE,OAAO,KAAa,GAAG,IAAI,CAa3F;AAED,gFAAgF;AAChF,wBAAgB,aAAa,CAAC,EAAE,EAAE,KAAK,GAAG,OAAO,CAEhD"}

package/dist/open.js

@@ -0,0 +1,45 @@
+import { spawn } from 'node:child_process';
+/**
+ * Opening a URL in the person's default browser (PRDCT-2280): the first push
+ * of a folder opens the pushed resource's page, the tool's `open` command opens
+ * it on demand, its `dev` command opens the local preview.
+ *
+ * The URL is always ONE argv item handed to the platform's opener binary,
+ * never a string a shell interprets: a resource title or an instance URL is
+ * somebody else's text, and `sh -c "open $url"` would run whatever it
+ * carries. On Windows `start` is a cmd.exe builtin that `spawn` cannot run
+ * without a shell, so the URL handler is invoked through `rundll32`
+ * instead, which is a real executable taking the URL as an argument.
+ */
+export function platformOpener(platform = process.platform) {
+    if (platform === 'darwin')
+        return { command: 'open', args: [] };
+    if (platform === 'win32')
+        return { command: 'rundll32', args: ['url.dll,FileProtocolHandler'] };
+    return { command: 'xdg-open', args: [] };
+}
+/**
+ * Best effort: a missing opener (a headless box) must never fail the
+ * command that already did its real work. The runner can inject `io.openUrl`
+ * (tests record the call; nothing is spawned).
+ */
+export function openInBrowser(io, url, spawnImpl = spawn) {
+    if (io.openUrl) {
+        io.openUrl(url);
+        return;
+    }
+    const { command, args } = platformOpener();
+    try {
+        const child = spawnImpl(command, [...args, url], { stdio: 'ignore', detached: true });
+        child.on('error', () => undefined);
+        child.unref();
+    }
+    catch {
+        // best-effort
+    }
+}
+/** A stdout that is a terminal: the only place a browser may pop up unasked. */
+export function isInteractive(io) {
+    return io.out.isTTY === true;
+}
+//# sourceMappingURL=open.js.map

package/dist/open.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"open.js","sourceRoot":"","sources":["../src/open.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAG3C;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,cAAc,CAAC,WAA4B,OAAO,CAAC,QAAQ;IAIzE,IAAI,QAAQ,KAAK,QAAQ;QAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;IAChE,IAAI,QAAQ,KAAK,OAAO;QAAE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,6BAA6B,CAAC,EAAE,CAAC;IAChG,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;AAC3C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,EAAS,EAAE,GAAW,EAAE,YAA0B,KAAK;IACnF,IAAI,EAAE,CAAC,OAAO,EAAE,CAAC;QACf,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAChB,OAAO;IACT,CAAC;IACD,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,cAAc,EAAE,CAAC;IAC3C,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,SAAS,CAAC,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,CAAC,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;QACtF,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QACnC,KAAK,CAAC,KAAK,EAAE,CAAC;IAChB,CAAC;IAAC,MAAM,CAAC;QACP,cAAc;IAChB,CAAC;AACH,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,aAAa,CAAC,EAAS;IACrC,OAAO,EAAE,CAAC,GAAG,CAAC,KAAK,KAAK,IAAI,CAAC;AAC/B,CAAC"}

package/dist/owner-session.d.ts

@@ -0,0 +1,34 @@
+import { ChassisClient } from '@antasphere/chassis-sdk';
+import { type CliContext } from './context.js';
+import type { CliIdentity } from './identity.js';
+/**
+ * A command that acts as a SIGNED-IN OWNER, never with an API key.
+ *
+ * Some owner acts are refused to every machine credential by design (the
+ * demo pass routes: nothing in the scope allowlist opens them, and the
+ * handler checks `via === 'session'` again). The CLI reaches them the way a
+ * browser does: one password sign-in, the session cookie held in memory for
+ * the length of the command, a sign-out when it ends, success or failure.
+ *
+ * The address comes from `--owner-email` or `<PREFIX>_OWNER_EMAIL`, the
+ * password from `<PREFIX>_OWNER_PASSWORD` or, with `--owner-password-stdin`,
+ * the first line of stdin. There is no password flag: a value on the command
+ * line is visible in `ps` and lands in the shell history. None of the three
+ * (address, password, cookie) is ever written to the profile, a file, a log
+ * or the terminal: they live in this function's locals and in the one
+ * client's header map, and die with the command.
+ */
+export interface OwnerSessionOptions {
+    /** The tool's identity: `<PREFIX>_OWNER_EMAIL` / `<PREFIX>_OWNER_PASSWORD` are built from it. */
+    identity: Pick<CliIdentity, 'envPrefix'>;
+    /** `--owner-email`. */
+    ownerEmail?: string;
+    /** `--owner-password-stdin`. */
+    ownerPasswordStdin?: boolean;
+}
+/**
+ * Sign in as the owner, run `run` with a client that carries the session
+ * cookie and the origin (and no authorization header), then sign out.
+ */
+export declare function withOwnerSession<T>(ctx: CliContext, options: OwnerSessionOptions, run: (client: ChassisClient<string>) => Promise<T>): Promise<T>;
+//# sourceMappingURL=owner-session.d.ts.map

package/dist/owner-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"owner-session.d.ts","sourceRoot":"","sources":["../src/owner-session.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAsB,MAAM,yBAAyB,CAAC;AAC5E,OAAO,EAAgC,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAC7E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAIjD;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,WAAW,mBAAmB;IAClC,iGAAiG;IACjG,QAAQ,EAAE,IAAI,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;IACzC,uBAAuB;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gCAAgC;IAChC,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAqDD;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EACtC,GAAG,EAAE,UAAU,EACf,OAAO,EAAE,mBAAmB,EAC5B,GAAG,EAAE,CAAC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,GACjD,OAAO,CAAC,CAAC,CAAC,CA2DZ"}

package/dist/owner-session.js

@@ -0,0 +1,106 @@
+import { ChassisClient, DEFAULT_TIMEOUT_MS } from '@antasphere/chassis-sdk';
+import { CliApiRefusal, CliUsageError } from './context.js';
+import { readSecretFromStdin } from './stdin.js';
+import { isWorkspaceId, matchWorkspace } from './workspace.js';
+/**
+ * The sign-in library allows three sign-ins per ten seconds per address, and
+ * a script that makes links for several people signs in once per command:
+ * the fourth command in a row meets the wall. It is a wall of seconds, so the
+ * command waits it out, three times at most, and says so on stderr.
+ */
+const SIGN_IN_WAITS_MS = [4_000, 8_000, 12_000];
+/** The session cookie the sign-in library sets, whatever prefix the instance gives it. */
+const SESSION_COOKIE = /session_token$/;
+/** `name=value` of the session cookie among the answer's `set-cookie` lines, or null. */
+function sessionCookie(res) {
+    for (const line of res.headers.getSetCookie()) {
+        const pair = line.split(';', 1)[0].trim();
+        const eq = pair.indexOf('=');
+        if (eq > 0 && SESSION_COOKIE.test(pair.slice(0, eq)))
+            return pair;
+    }
+    return null;
+}
+/** The sign-in library's own refusals are `{ code, message }`; the API's are `{ error: {…} }`. */
+async function refusalMessage(res) {
+    const body = (await res.json().catch(() => null));
+    const message = body?.error?.message ?? body?.message;
+    return typeof message === 'string' && message ? message : null;
+}
+async function ownerCredentials(ctx, options) {
+    const { envPrefix } = options.identity;
+    const emailVar = `${envPrefix}_OWNER_EMAIL`;
+    const passwordVar = `${envPrefix}_OWNER_PASSWORD`;
+    const email = (options.ownerEmail ?? ctx.io.env[emailVar] ?? '').trim();
+    const password = options.ownerPasswordStdin
+        ? await readSecretFromStdin(ctx.io, 'owner password')
+        : (ctx.io.env[passwordVar] ?? '');
+    if (!email || !password) {
+        throw new CliUsageError(`This command signs in as an owner of the workspace, never with an API key. Set ${emailVar} ` +
+            `(or pass --owner-email) and ${passwordVar} (or pipe it with --owner-password-stdin).`);
+    }
+    return { email, password };
+}
+/**
+ * Sign in as the owner, run `run` with a client that carries the session
+ * cookie and the origin (and no authorization header), then sign out.
+ */
+export async function withOwnerSession(ctx, options, run) {
+    const base = ctx.baseUrl.replace(/\/+$/, '');
+    const origin = new URL(base).origin;
+    const fetchImpl = ctx.io.fetch ?? globalThis.fetch.bind(globalThis);
+    const { email, password } = await ownerCredentials(ctx, options);
+    // The server refuses a sign-in that carries no Origin (the cross-site guard).
+    const signIn = () => fetchImpl(`${base}/api/v1/auth/sign-in/email`, {
+        method: 'POST',
+        headers: { origin, 'content-type': 'application/json' },
+        body: JSON.stringify({ email, password }),
+        signal: AbortSignal.timeout(DEFAULT_TIMEOUT_MS)
+    });
+    const sleep = ctx.io.sleep ?? ((ms) => new Promise((done) => setTimeout(done, ms)));
+    let res = await signIn();
+    for (const wait of SIGN_IN_WAITS_MS) {
+        if (res.status !== 429)
+            break;
+        ctx.io.err.write(`The instance limits sign-ins: waiting ${wait / 1000} seconds.\n`);
+        await sleep(wait);
+        res = await signIn();
+    }
+    if (res.status === 429) {
+        throw new CliApiRefusal('Too many sign-in attempts for now: wait a few minutes, then try again.', 429);
+    }
+    if (!res.ok) {
+        const message = (await refusalMessage(res)) ?? `The sign-in failed (HTTP ${res.status}).`;
+        throw new CliApiRefusal(message, res.status);
+    }
+    const answer = (await res.json().catch(() => null));
+    if (answer?.twoFactorRedirect === true) {
+        throw new CliUsageError('This owner has a second factor: mint demo links from the dashboard.');
+    }
+    const cookie = sessionCookie(res);
+    if (!cookie)
+        throw new CliUsageError('The instance answered the sign-in without a session.');
+    const headers = { cookie, origin };
+    const client = new ChassisClient({ baseUrl: base, fetch: fetchImpl, headers });
+    try {
+        // The workspace selection applies here as it does to every command
+        // (context.ts `applyWorkspace`): an id as it is, a name through `/me`.
+        const selection = ctx.workspaceSelection;
+        if (selection) {
+            client.setWorkspace(isWorkspaceId(selection.value)
+                ? selection.value
+                : matchWorkspace((await client.me()).workspaces, selection.value).id);
+        }
+        return await run(client);
+    }
+    finally {
+        // The session ends with the command; its outcome changes nothing.
+        await fetchImpl(`${base}/api/v1/auth/sign-out`, {
+            method: 'POST',
+            headers: { ...headers, 'content-type': 'application/json' },
+            body: '{}',
+            signal: AbortSignal.timeout(DEFAULT_TIMEOUT_MS)
+        }).catch(() => undefined);
+    }
+}
+//# sourceMappingURL=owner-session.js.map

package/dist/owner-session.js.map

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

package/dist/program.d.ts

@@ -0,0 +1,5 @@
+import { type ChassisClient } from '@antasphere/chassis-sdk';
+import type { Cli, CliDefinition, CliKit } from './kit.js';
+/** The program and the runner of one tool, over its kit (kit.ts). */
+export declare function createProgram<TClient extends ChassisClient<string>>(kit: CliKit<TClient>, definition: Pick<CliDefinition<TClient>, 'description' | 'errorHint'>): Pick<Cli<TClient>, 'buildProgram' | 'run'>;
+//# sourceMappingURL=program.d.ts.map

package/dist/program.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"program.d.ts","sourceRoot":"","sources":["../src/program.ts"],"names":[],"mappings":"AAEA,OAAO,EAAoB,KAAK,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAE/E,OAAO,KAAK,EAAE,GAAG,EAAE,aAAa,EAAE,MAAM,EAAgB,MAAM,UAAU,CAAC;AAmBzE,qEAAqE;AACrE,wBAAgB,aAAa,CAAC,OAAO,SAAS,aAAa,CAAC,MAAM,CAAC,EACjE,GAAG,EAAE,MAAM,CAAC,OAAO,CAAC,EACpB,UAAU,EAAE,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,WAAW,CAAC,GACpE,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,KAAK,CAAC,CA2J5C"}

package/dist/program.js

@@ -0,0 +1,150 @@
+import { Command, CommanderError } from 'commander';
+import { CliAuthError, CliConnectError } from '@antasphere/cli-core';
+import { PlatformApiError } from '@antasphere/chassis-sdk';
+import { CliApiRefusal, CliUsageError, setStdinApiKey, ttySafeIo } from './context.js';
+import { readSecretFromStdin } from './stdin.js';
+import { registerAuthCommands } from './commands/auth.js';
+import { registerWorkspaceCommands } from './commands/workspaces.js';
+import { registerProjectCommands } from './commands/projects.js';
+import { registerTeamCommands } from './commands/teams.js';
+import { registerDemoCommands } from './commands/demo.js';
+import { registerFileCommands } from './commands/files.js';
+import { registerCompletionCommand } from './commands/completion.js';
+/** The price and the balance of a credit refusal, each only when it is a number (the code review). */
+function creditFigures(credit) {
+    const parts = [
+        typeof credit?.credits === 'number' ? `this needs ${credit.credits} credits` : null,
+        typeof credit?.balance === 'number' ? `the organization holds ${credit.balance}` : null
+    ].filter((x) => x !== null);
+    return parts.length > 0 ? `${parts.join(' and ')}; ` : '';
+}
+/** The program and the runner of one tool, over its kit (kit.ts). */
+export function createProgram(kit, definition) {
+    const { identity, explainWorkspaceRefusal, workspaceNotFoundHint } = kit;
+    const { description, errorHint } = definition;
+    function buildProgram(io, registerTool, version) {
+        const program = new Command();
+        program
+            .name(identity.bin)
+            .description(description)
+            .version(version)
+            .option('--api-url <url>', `instance base URL (or ${identity.envPrefix}_URL / the profile's; default: the cloud, ${identity.cloudUrl})`)
+            .option('--url <url>', 'alias of --api-url')
+            .option('--api-key <key>', `API key (or ${identity.envPrefix}_API_KEY / profile apiKey)`)
+            .option('--api-key-stdin', 'read the API key from the first line of stdin (keeps it out of argv)', false)
+            .option('--profile <name>', 'use this saved profile (an instance) instead of the active one')
+            .option('--org <id-or-name>', `run in this Antasphere organization, by its id or name (or ${identity.envPrefix}_ORG; default: your default organization)`)
+            .option('--workspace <id-or-name>', `run in this workspace of the instance, by its id or name (or ${identity.envPrefix}_WORKSPACE; default: the server's)`)
+            .option('--json', 'machine-readable JSON output', false);
+        // Identity + profiles: login, logout, whoami, verify, use, profiles,
+        // config show/clear.
+        registerAuthCommands(kit, program, io);
+        // Which workspace the commands run in: workspaces, workspace default.
+        registerWorkspaceCommands(kit, program, io);
+        // The subgroups of the workspace: projects *, projects members *.
+        registerProjectCommands(kit, program, io);
+        // The named groups of the workspace's people: teams *.
+        registerTeamCommands(kit, program, io);
+        // Demo links, as a signed-in owner (never a key): demo link, list, revoke.
+        registerDemoCommands(kit, program, io);
+        // The tool's own groups, where they have always sat in `--help`.
+        registerTool(program, io);
+        // Platform substrate (template heritage): instance, export, files *.
+        registerFileCommands(kit, program, io);
+        // Shell completion — registered LAST so the tree it prints is complete.
+        registerCompletionCommand(identity, program, io);
+        return program;
+    }
+    async function run(argv, rawIo, registerTool, version) {
+        // Every human sink is wrapped ONCE, here: resource titles, annotation bodies,
+        // stored filenames and server error messages are all somebody else's text
+        // heading for a terminal (context.ts `sanitizeForTty`). `--json` keeps the
+        // raw sink through `printJson`.
+        const io = ttySafeIo(rawIo);
+        // `--api-key-stdin` is resolved BEFORE commander parses: `resolveContext`
+        // is synchronous, so the key must already be parked against this io by
+        // the time a command asks for it. Reading stdin is the whole point — an
+        // argv-borne secret is visible in `ps` and lands in the shell history.
+        if (argv.includes('--api-key-stdin')) {
+            try {
+                setStdinApiKey(io, await readSecretFromStdin(io, 'API key'));
+            }
+            catch (e) {
+                io.err.write(`Error: ${e instanceof Error ? e.message : String(e)}\n`);
+                return 1;
+            }
+        }
+        const program = buildProgram(io, registerTool, version);
+        program.exitOverride();
+        program.configureOutput({
+            writeOut: (s) => io.out.write(s),
+            writeErr: (s) => io.err.write(s)
+        });
+        try {
+            await program.parseAsync(argv, { from: 'user' });
+            return 0;
+        }
+        catch (e) {
+            if (e instanceof CommanderError) {
+                // --help / --version and usage errors already wrote their output.
+                return e.exitCode;
+            }
+            if (e instanceof CliConnectError && e.refusal) {
+                // The hub (or the instance's connect door) refused the PERSON, not
+                // the credential: the server's own sentence, as it is, and exit 3,
+                // the code the docs promise for a refusal. No hint: no key fixes it.
+                io.err.write(`Error: ${e.message}\n`);
+                return e.exitCode;
+            }
+            if (e instanceof PlatformApiError || e instanceof CliAuthError) {
+                // A refusal the workspace SELECTION caused reads as a bad key (401) or
+                // a forbidden one (403) on the wire; say what it really was.
+                const explained = await explainWorkspaceRefusal(io, e);
+                if (explained) {
+                    io.err.write(`Error: ${explained}\n`);
+                    return 1;
+                }
+                // A plan refusal (the billing rail, 403 `plan_required`) is not a
+                // key's fault: the sentence carries the upgrade link, the hub's
+                // organization page, where a human raises the plan.
+                const upgradeUrl = (e instanceof PlatformApiError && e.code === 'plan_required'
+                    ? e.details?.upgradeUrl
+                    : undefined);
+                // A credit refusal (402 `entitlement_denied`, PRDCT-2664) carries the
+                // price, the balance and the top-up link, the hub's billing page. The
+                // self-hosted cap's 413 has no details and keeps its message alone.
+                const credit = (e instanceof PlatformApiError && e.code === 'entitlement_denied' ? e.details : undefined);
+                const topUpUrl = typeof credit?.topUpUrl === 'string' && credit.topUpUrl ? credit.topUpUrl : null;
+                // The gate's own message already spells the price, the balance and
+                // the link; the hint repeats them only for a message that does not
+                // (verifier round 1: the URL was printed twice).
+                const hint = typeof upgradeUrl === 'string' && upgradeUrl
+                    ? ` — upgrade the plan at ${upgradeUrl}`
+                    : topUpUrl && !e.message.includes(topUpUrl)
+                        ? ` — ${creditFigures(credit)}top up at ${topUpUrl}`
+                        : e.status === 403
+                            ? ' (this API key is not allowed to do that)'
+                            : (errorHint?.(e) ??
+                                (e.status === 401
+                                    ? ` (check the key: \`${identity.bin} verify\`)`
+                                    : e.status === 404
+                                        ? workspaceNotFoundHint(io)
+                                        : ''));
+                io.err.write(`Error: ${e.message}${hint}\n`);
+                return 1;
+            }
+            if (e instanceof CliUsageError) {
+                // A refusal a command already worded keeps the one thing the command
+                // cannot know: the workspace a 404 was asked of. The thrower says the
+                // exit code (cli-core: 1 a usage or wire error, 3 a refusal).
+                const hint = e instanceof CliApiRefusal && e.status === 404 ? workspaceNotFoundHint(io) : '';
+                io.err.write(`Error: ${e.message}${hint}\n`);
+                return e.exitCode;
+            }
+            io.err.write(`Error: ${e instanceof Error ? e.message : String(e)}\n`);
+            return 1;
+        }
+    }
+    return { buildProgram, run };
+}
+//# sourceMappingURL=program.js.map

package/dist/program.js.map

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