@antasphere/chassis-cli 0.0.0-stage → 1.0.0

package/dist/safe-write.d.ts

@@ -0,0 +1,46 @@
+import type { Readable } from 'node:stream';
+/**
+ * Writing SERVER-CHOSEN paths to a developer's disk, safely.
+ *
+ * The tool's `pull` and the generic `files download` both materialize names the
+ * instance picked (a manifest path, a stored filename). That makes the local
+ * filesystem the last line of defence, and a lexical `resolve()` +
+ * `startsWith()` is not one: it says nothing about symlinks. Three rules,
+ * enforced here so both call sites get the same ones:
+ *
+ *  1. the path must be relative and stay inside the destination LEXICALLY;
+ *  2. the parent directory, after `realpath()`, must still be inside the
+ *     destination (a symlinked sub-directory is a way out);
+ *  3. the final component is opened `O_NOFOLLOW`, so an existing symlink is
+ *     refused rather than written through, and the file's mode is forced to
+ *     0644 — `O_TRUNC` on an existing file PRESERVES its mode, which is how
+ *     an already-executable path stays executable after a hostile pull.
+ */
+/** Thrown when a write target fails containment; the CLI turns it into exit 1. */
+export declare class UnsafeWriteError extends Error {
+    constructor(message: string);
+}
+/** Lexical containment: `relPath` must resolve to something under `root`. */
+export declare function resolveInside(root: string, relPath: string): string;
+/**
+ * Write `bytes` at `root`/`relPath` under all three rules above. Returns the
+ * absolute path written.
+ */
+export declare function writeContained(root: string, relPath: string, bytes: Uint8Array): Promise<string>;
+/**
+ * Write `bytes` to an exact path, refusing to follow a symlink there and
+ * forcing mode 0644 (never inherit an existing file's executable bit).
+ */
+export declare function writeNoFollow(target: string, bytes: Uint8Array): Promise<void>;
+/**
+ * Stream `source` to `root`/`relPath` under the same three rules as
+ * `writeContained`, for a body too large to buffer (a zip of respondent
+ * uploads). Returns the absolute path and the byte count. A failed stream
+ * removes the partial file — a truncated archive must not look like a
+ * finished one.
+ */
+export declare function streamContained(root: string, relPath: string, source: Readable): Promise<{
+    path: string;
+    sizeBytes: number;
+}>;
+//# sourceMappingURL=safe-write.d.ts.map

package/dist/safe-write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-write.d.ts","sourceRoot":"","sources":["../src/safe-write.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAG5C;;;;;;;;;;;;;;;;GAgBG;AAEH,kFAAkF;AAClF,qBAAa,gBAAiB,SAAQ,KAAK;gBAC7B,OAAO,EAAE,MAAM;CAI5B;AAED,6EAA6E;AAC7E,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAUnE;AAqBD;;;GAGG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAKtG;AAED;;;GAGG;AACH,wBAAsB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAoBpF;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,QAAQ,GACf,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CAuB9C"}

package/dist/safe-write.js

@@ -0,0 +1,127 @@
+import { constants as FS } from 'node:fs';
+import { mkdir, open, realpath, unlink } from 'node:fs/promises';
+import { dirname, isAbsolute, relative, resolve } from 'node:path';
+import { pipeline } from 'node:stream/promises';
+/**
+ * Writing SERVER-CHOSEN paths to a developer's disk, safely.
+ *
+ * The tool's `pull` and the generic `files download` both materialize names the
+ * instance picked (a manifest path, a stored filename). That makes the local
+ * filesystem the last line of defence, and a lexical `resolve()` +
+ * `startsWith()` is not one: it says nothing about symlinks. Three rules,
+ * enforced here so both call sites get the same ones:
+ *
+ *  1. the path must be relative and stay inside the destination LEXICALLY;
+ *  2. the parent directory, after `realpath()`, must still be inside the
+ *     destination (a symlinked sub-directory is a way out);
+ *  3. the final component is opened `O_NOFOLLOW`, so an existing symlink is
+ *     refused rather than written through, and the file's mode is forced to
+ *     0644 — `O_TRUNC` on an existing file PRESERVES its mode, which is how
+ *     an already-executable path stays executable after a hostile pull.
+ */
+/** Thrown when a write target fails containment; the CLI turns it into exit 1. */
+export class UnsafeWriteError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'UnsafeWriteError';
+    }
+}
+/** Lexical containment: `relPath` must resolve to something under `root`. */
+export function resolveInside(root, relPath) {
+    if (isAbsolute(relPath)) {
+        throw new UnsafeWriteError(`Refusing to write an absolute path: ${relPath}`);
+    }
+    const target = resolve(root, relPath);
+    const rel = relative(root, target);
+    if (rel === '' || rel.startsWith('..') || isAbsolute(rel)) {
+        throw new UnsafeWriteError(`Refusing to write outside ${root}: ${relPath}`);
+    }
+    return target;
+}
+/**
+ * Create (recursively) the parent of `target` and prove that the REAL
+ * directory it lands in is still inside `root`. `mkdir -p` happily walks
+ * through an existing symlinked directory, so this must run after it.
+ */
+async function prepareParent(root, target) {
+    const parent = dirname(target);
+    await mkdir(parent, { recursive: true });
+    const realRoot = await realpath(root);
+    const realParent = await realpath(parent);
+    const rel = relative(realRoot, realParent);
+    if (rel !== '' && (rel.startsWith('..') || isAbsolute(rel))) {
+        throw new UnsafeWriteError(`Refusing to write through a symlinked directory: ${parent} resolves to ${realParent}, ` +
+            `outside ${realRoot}`);
+    }
+}
+/**
+ * Write `bytes` at `root`/`relPath` under all three rules above. Returns the
+ * absolute path written.
+ */
+export async function writeContained(root, relPath, bytes) {
+    const target = resolveInside(root, relPath);
+    await prepareParent(root, target);
+    await writeNoFollow(target, bytes);
+    return target;
+}
+/**
+ * Write `bytes` to an exact path, refusing to follow a symlink there and
+ * forcing mode 0644 (never inherit an existing file's executable bit).
+ */
+export async function writeNoFollow(target, bytes) {
+    let handle;
+    try {
+        handle = await open(target, FS.O_WRONLY | FS.O_CREAT | FS.O_TRUNC | FS.O_NOFOLLOW, 0o644);
+    }
+    catch (e) {
+        const code = e.code;
+        // ELOOP (POSIX) / EMLINK (some BSDs) — the target exists and is a symlink.
+        if (code === 'ELOOP' || code === 'EMLINK') {
+            throw new UnsafeWriteError(`Refusing to write through the symlink at ${target}`);
+        }
+        throw e;
+    }
+    try {
+        await handle.writeFile(bytes);
+        // O_TRUNC keeps the existing mode; re-assert it so a pull can never
+        // leave a file executable (or group/world-writable) behind.
+        await handle.chmod(0o644).catch(() => undefined);
+    }
+    finally {
+        await handle.close();
+    }
+}
+/**
+ * Stream `source` to `root`/`relPath` under the same three rules as
+ * `writeContained`, for a body too large to buffer (a zip of respondent
+ * uploads). Returns the absolute path and the byte count. A failed stream
+ * removes the partial file — a truncated archive must not look like a
+ * finished one.
+ */
+export async function streamContained(root, relPath, source) {
+    const target = resolveInside(root, relPath);
+    await prepareParent(root, target);
+    let handle;
+    try {
+        handle = await open(target, FS.O_WRONLY | FS.O_CREAT | FS.O_TRUNC | FS.O_NOFOLLOW, 0o644);
+    }
+    catch (e) {
+        const code = e.code;
+        if (code === 'ELOOP' || code === 'EMLINK') {
+            throw new UnsafeWriteError(`Refusing to write through the symlink at ${target}`);
+        }
+        throw e;
+    }
+    try {
+        await handle.chmod(0o644).catch(() => undefined);
+        const sink = handle.createWriteStream();
+        await pipeline(source, sink);
+        return { path: target, sizeBytes: sink.bytesWritten };
+    }
+    catch (e) {
+        await handle.close().catch(() => undefined);
+        await unlink(target).catch(() => undefined);
+        throw e;
+    }
+}
+//# sourceMappingURL=safe-write.js.map

package/dist/safe-write.js.map

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

package/dist/stdin.d.ts

@@ -0,0 +1,4 @@
+import { type CliIo } from './context.js';
+/** First line of stdin, claimed for exactly one purpose per invocation. */
+export declare function readSecretFromStdin(io: CliIo, claimant: string): Promise<string>;
+//# sourceMappingURL=stdin.d.ts.map

package/dist/stdin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdin.d.ts","sourceRoot":"","sources":["../src/stdin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,KAAK,EAAE,MAAM,cAAc,CAAC;AAyBzD,2EAA2E;AAC3E,wBAAsB,mBAAmB,CAAC,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAYtF"}

package/dist/stdin.js

@@ -0,0 +1,36 @@
+import { CliUsageError } from './context.js';
+/**
+ * Secrets that arrive on stdin instead of the command line.
+ *
+ * A value passed as `--api-key <prefix>_…` or `--password hunter2` is visible to
+ * every process on the box (`ps`, `/proc/<pid>/cmdline`) and lands verbatim
+ * in the shell history file. The flags stay — they are what scripts already
+ * use — but each one now has a `-stdin` sibling and, for the share
+ * password, an environment variable, so nothing forces a secret through
+ * argv.
+ *
+ * stdin can only be spent once, so it is claimed: the second claimant in one
+ * invocation gets a usage error instead of silently receiving the first
+ * one's value.
+ */
+const claims = new WeakMap();
+async function readAllStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString('utf8');
+}
+/** First line of stdin, claimed for exactly one purpose per invocation. */
+export async function readSecretFromStdin(io, claimant) {
+    const holder = claims.get(io);
+    if (holder !== undefined) {
+        throw new CliUsageError(`Only one secret can be read from stdin per command — ${holder} already claimed it.`);
+    }
+    claims.set(io, claimant);
+    const raw = await (io.readStdin ?? readAllStdin)();
+    const value = raw.split('\n')[0]?.trim() ?? '';
+    if (!value)
+        throw new CliUsageError(`Nothing on stdin to read the ${claimant} from.`);
+    return value;
+}
+//# sourceMappingURL=stdin.js.map

package/dist/stdin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdin.js","sourceRoot":"","sources":["../src/stdin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAc,MAAM,cAAc,CAAC;AAEzD;;;;;;;;;;;;;GAaG;AAEH,MAAM,MAAM,GAAG,IAAI,OAAO,EAAiB,CAAC;AAE5C,KAAK,UAAU,YAAY;IACzB,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,OAAO,CAAC,KAAK;QAAE,MAAM,CAAC,IAAI,CAAC,KAAe,CAAC,CAAC;IACtE,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AAChD,CAAC;AAED,2EAA2E;AAC3E,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,EAAS,EAAE,QAAgB;IACnE,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC9B,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,MAAM,IAAI,aAAa,CACrB,wDAAwD,MAAM,sBAAsB,CACrF,CAAC;IACJ,CAAC;IACD,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC;IACzB,MAAM,GAAG,GAAG,MAAM,CAAC,EAAE,CAAC,SAAS,IAAI,YAAY,CAAC,EAAE,CAAC;IACnD,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IAC/C,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,aAAa,CAAC,gCAAgC,QAAQ,QAAQ,CAAC,CAAC;IACtF,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/testing/index.d.ts

@@ -0,0 +1,70 @@
+import type { ChassisClient } from '@antasphere/chassis-sdk';
+import type { CliIo } from '../context.js';
+import type { Cli } from '../kit.js';
+/**
+ * The test harness of a CLI built on this package, shared by the chassis suite
+ * and by the tool's own tests. `./testing` is a test-only entry: it is built
+ * (the tool's tests read it from `dist`) and kept out of the packed artefact
+ * (`files` in package.json) and out of the tool's bundle (nothing under a
+ * tool's `src` imports it).
+ *
+ * Router-style fake fetch: handlers matched by method + path regex, so
+ * order-insensitive flows (parallel uploads) stay assertable. Records every
+ * call with its parsed body (JSON / FormData summary).
+ */
+export interface RecordedCall {
+    method: string;
+    path: string;
+    body?: unknown;
+}
+/**
+ * The full wire view of a call — origin + authorization header included.
+ * Kept in a SEPARATE array (`wire`) so the legacy strict `toEqual` asserts
+ * on `calls` keep their exact shape; the connect tests use this to prove
+ * which credential went to which host.
+ */
+export interface WireCall {
+    method: string;
+    origin: string;
+    path: string;
+    auth: string | undefined;
+    /** The `x-workspace-id` header, present only when the request carried one. */
+    workspace?: string;
+    body?: unknown;
+}
+export interface Route {
+    method: string;
+    path: RegExp;
+    reply: (call: {
+        path: string;
+        body?: unknown;
+        form?: FormData;
+        headers: Headers;
+    }) => {
+        status?: number;
+        body?: unknown;
+        raw?: Response;
+    };
+}
+export declare function routedHarness(routes: Route[], env?: Record<string, string | undefined>): {
+    io: CliIo;
+    calls: RecordedCall[];
+    wire: WireCall[];
+    out: () => string;
+    err: () => string;
+};
+/** A temp HOME-like config root, isolated per test. */
+export declare function tempConfigEnv(): Promise<Record<string, string>>;
+/**
+ * What the chassis suite (`test/suite`) reads from `@chassis-cli-test/host`:
+ * one instantiated CLI and its runner, with the tool's groups and version
+ * already bound. The chassis package aliases the specifier to its minimal
+ * `things` tool; a tool's own CLI package aliases it to its real kit, and the
+ * same files run a second time there. Every literal that spells the tool in
+ * the suite is read from `cli.identity`.
+ */
+export interface CliTestHost<TClient extends ChassisClient<string>> {
+    cli: Cli<TClient>;
+    run(argv: string[], io: CliIo): Promise<number>;
+}
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAErC;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,8EAA8E;IAC9E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,KAAK;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,QAAQ,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,KAAK;QACpF,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,IAAI,CAAC,EAAE,OAAO,CAAC;QACf,GAAG,CAAC,EAAE,QAAQ,CAAC;KAChB,CAAC;CACH;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAM;;;;;;EA0D1F;AAED,uDAAuD;AACvD,wBAAsB,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAGrE;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW,CAAC,OAAO,SAAS,aAAa,CAAC,MAAM,CAAC;IAChE,GAAG,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;IAClB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACjD"}

package/dist/testing/index.js

@@ -0,0 +1,67 @@
+import { mkdtemp } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+export function routedHarness(routes, env = {}) {
+    const calls = [];
+    const wire = [];
+    const out = [];
+    const err = [];
+    const fetch = (async (input, init) => {
+        const url = new URL(input.toString());
+        const method = (init?.method ?? 'GET').toUpperCase();
+        const path = url.pathname + url.search;
+        let body;
+        let form;
+        if (typeof init?.body === 'string') {
+            try {
+                body = JSON.parse(init.body);
+            }
+            catch {
+                body = init.body;
+            }
+        }
+        else if (init?.body instanceof FormData) {
+            form = init.body;
+            body = { sha256: form.get('sha256') };
+        }
+        calls.push({ method, path, ...(body !== undefined ? { body } : {}) });
+        const headers = new Headers(init?.headers);
+        const auth = headers.get('authorization') ?? undefined;
+        const workspace = headers.get('x-workspace-id') ?? undefined;
+        wire.push({
+            method,
+            origin: url.origin,
+            path,
+            auth,
+            ...(workspace !== undefined ? { workspace } : {}),
+            ...(body !== undefined ? { body } : {})
+        });
+        const route = routes.find((r) => r.method === method && r.path.test(url.pathname));
+        if (!route) {
+            return new Response(JSON.stringify({ error: { code: 'not_found', message: `no fake route ${method} ${path}` } }), {
+                status: 404,
+                headers: { 'content-type': 'application/json' }
+            });
+        }
+        const result = route.reply({ path, body, headers, ...(form ? { form } : {}) });
+        if (result.raw)
+            return result.raw;
+        return new Response(JSON.stringify(result.body ?? {}), {
+            status: result.status ?? 200,
+            headers: { 'content-type': 'application/json' }
+        });
+    });
+    const io = {
+        env,
+        out: { write: (s) => out.push(s) },
+        err: { write: (s) => err.push(s) },
+        fetch
+    };
+    return { io, calls, wire, out: () => out.join(''), err: () => err.join('') };
+}
+/** A temp HOME-like config root, isolated per test. */
+export async function tempConfigEnv() {
+    const dir = await mkdtemp(join(tmpdir(), 'cli-cfg-'));
+    return { XDG_CONFIG_HOME: dir };
+}
+//# sourceMappingURL=index.js.map

package/dist/testing/index.js.map

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

package/dist/workspace.d.ts

@@ -0,0 +1,79 @@
+import type { ChassisClient } from '@antasphere/chassis-sdk';
+import type { CliEnv } from './config.js';
+import type { CliIdentity } from './identity.js';
+/**
+ * Which workspace a command runs in (PRDCT-2419, PRDCT-2947).
+ *
+ * A credential identifies a USER (ADR 014, ADR 019): the workspace is a
+ * per-request `X-Workspace-Id`, and the SDK sends it once told which. There
+ * is ONE organization notion in the tool family: the server's default
+ * organization applies when a command names none, and a command may name
+ * one of two ways:
+ *
+ *   --org <hub organization id or name>   or <PREFIX>_ORG
+ *   --workspace <workspace id or name>    or <PREFIX>_WORKSPACE
+ *
+ * `--org` names the organization the Antasphere way (the id the account
+ * site shows, or its name); the instance maps a hub organization id to its
+ * own workspace through `central_account_id`. `--workspace` names a
+ * workspace of this instance (a self-hosted instance has no hub ids). Both
+ * at once is a usage error; a flag wins over its variable. Nothing is saved
+ * on this machine: the default is the server's (`workspace default` on a
+ * self-hosted instance, the Antasphere account on the cloud).
+ *
+ * A value that is a uuid is sent as it is (the server accepts a local id or a
+ * hub organization id, and fails closed on one that is not the person's); a
+ * name is looked up in `/me`'s `workspaces[]` first, by id, by hub
+ * organization id, then by name. Pure functions only: the wiring (the client,
+ * the header) lives in context.ts.
+ */
+/** `/me`'s answer, read off the client (the SDK does not export the type by name). */
+export type MeResponse = Awaited<ReturnType<ChassisClient<string>['me']>>;
+export type MeWorkspace = MeResponse['workspaces'][number];
+/** Which flag or variable named the selection. */
+export type SelectionKind = 'org' | 'workspace';
+/** Where the workspace of this invocation came from; `default` = nothing selected. */
+export type WorkspaceSource = 'flag' | 'env' | 'default';
+export interface WorkspaceSelection {
+    /** What the person wrote: an id or a name, trimmed. */
+    value: string;
+    source: Exclude<WorkspaceSource, 'default'>;
+    /** `--org` / `<PREFIX>_ORG`, or `--workspace` / `<PREFIX>_WORKSPACE`. */
+    kind: SelectionKind;
+}
+export declare function isWorkspaceId(value: string): boolean;
+/** One line per workspace, for the error messages that list the candidates. */
+export declare function workspaceLines(workspaces: readonly MeWorkspace[]): string;
+/**
+ * The membership a value names, or null: the exact workspace id first, then
+ * the exact hub organization id, else the ONE workspace whose name matches
+ * without regard to case. `ambiguous` carries the several a name matched.
+ */
+export declare function findWorkspace(workspaces: readonly MeWorkspace[], value: string): {
+    match: MeWorkspace | null;
+    ambiguous: MeWorkspace[];
+};
+/** `findWorkspace`, erroring with the candidates on an unknown or ambiguous value. */
+export declare function matchWorkspace(workspaces: readonly MeWorkspace[], value: string): MeWorkspace;
+/** The workspace functions that spell the tool: its environment variables, its binary. */
+export interface CliWorkspace {
+    WORKSPACE_ENV: string;
+    ORG_ENV: string;
+    pickWorkspaceSelection(input: {
+        workspaceFlag: string | undefined;
+        orgFlag: string | undefined;
+        env: CliEnv;
+    }): WorkspaceSelection | undefined;
+    describeSelection(selection: Pick<WorkspaceSelection, 'source' | 'kind'>): string;
+    describeSource(source: WorkspaceSource, kind: SelectionKind | undefined): string;
+    explainRefusal(input: {
+        code: string;
+        status: number;
+        selection: WorkspaceSelection;
+        workspaceId: string;
+        me: MeResponse;
+        baseUrl: string;
+    }): string | null;
+}
+export declare function createWorkspace(identity: CliIdentity): CliWorkspace;
+//# sourceMappingURL=workspace.d.ts.map

package/dist/workspace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../src/workspace.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,sFAAsF;AACtF,MAAM,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAC1E,MAAM,MAAM,WAAW,GAAG,UAAU,CAAC,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAE3D,kDAAkD;AAClD,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,WAAW,CAAC;AAEhD,sFAAsF;AACtF,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,KAAK,GAAG,SAAS,CAAC;AAEzD,MAAM,WAAW,kBAAkB;IACjC,uDAAuD;IACvD,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,OAAO,CAAC,eAAe,EAAE,SAAS,CAAC,CAAC;IAC5C,yEAAyE;IACzE,IAAI,EAAE,aAAa,CAAC;CACrB;AAKD,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEpD;AAQD,+EAA+E;AAC/E,wBAAgB,cAAc,CAAC,UAAU,EAAE,SAAS,WAAW,EAAE,GAAG,MAAM,CAQzE;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,SAAS,WAAW,EAAE,EAClC,KAAK,EAAE,MAAM,GACZ;IAAE,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;IAAC,SAAS,EAAE,WAAW,EAAE,CAAA;CAAE,CASzD;AAED,sFAAsF;AACtF,wBAAgB,cAAc,CAAC,UAAU,EAAE,SAAS,WAAW,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,WAAW,CAS7F;AAED,0FAA0F;AAC1F,MAAM,WAAW,YAAY;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,sBAAsB,CAAC,KAAK,EAAE;QAC5B,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;QAClC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;QAC5B,GAAG,EAAE,MAAM,CAAC;KACb,GAAG,kBAAkB,GAAG,SAAS,CAAC;IACnC,iBAAiB,CAAC,SAAS,EAAE,IAAI,CAAC,kBAAkB,EAAE,QAAQ,GAAG,MAAM,CAAC,GAAG,MAAM,CAAC;IAClF,cAAc,CAAC,MAAM,EAAE,eAAe,EAAE,IAAI,EAAE,aAAa,GAAG,SAAS,GAAG,MAAM,CAAC;IACjF,cAAc,CAAC,KAAK,EAAE;QACpB,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,kBAAkB,CAAC;QAC9B,WAAW,EAAE,MAAM,CAAC;QACpB,EAAE,EAAE,UAAU,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;KACjB,GAAG,MAAM,GAAG,IAAI,CAAC;CACnB;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,WAAW,GAAG,YAAY,CAsGnE"}

package/dist/workspace.js

@@ -0,0 +1,139 @@
+import { CliUsageError } from '@antasphere/cli-core';
+/** The server's own selector shape (resolve-membership.ts): anything else is a name. */
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export function isWorkspaceId(value) {
+    return UUID_RE.test(value);
+}
+/** The hub organization id of a listed workspace, when it projects one (an older server sends none). */
+function orgIdOf(w) {
+    const id = w.centralAccountId;
+    return typeof id === 'string' && id ? id : null;
+}
+/** One line per workspace, for the error messages that list the candidates. */
+export function workspaceLines(workspaces) {
+    if (workspaces.length === 0)
+        return '  (none)';
+    return workspaces
+        .map((w) => {
+        const org = orgIdOf(w);
+        return `  ${w.id}  ${w.role.padEnd(6)}  ${w.name}${org ? `  (organization ${org})` : ''}`;
+    })
+        .join('\n');
+}
+/**
+ * The membership a value names, or null: the exact workspace id first, then
+ * the exact hub organization id, else the ONE workspace whose name matches
+ * without regard to case. `ambiguous` carries the several a name matched.
+ */
+export function findWorkspace(workspaces, value) {
+    const wanted = value.trim().toLowerCase();
+    const byId = workspaces.find((w) => w.id.toLowerCase() === wanted);
+    if (byId)
+        return { match: byId, ambiguous: [] };
+    const byOrg = workspaces.find((w) => orgIdOf(w)?.toLowerCase() === wanted);
+    if (byOrg)
+        return { match: byOrg, ambiguous: [] };
+    const byName = workspaces.filter((w) => w.name.trim().toLowerCase() === wanted);
+    if (byName.length === 1)
+        return { match: byName[0], ambiguous: [] };
+    return { match: null, ambiguous: byName };
+}
+/** `findWorkspace`, erroring with the candidates on an unknown or ambiguous value. */
+export function matchWorkspace(workspaces, value) {
+    const { match, ambiguous } = findWorkspace(workspaces, value);
+    if (match)
+        return match;
+    if (ambiguous.length > 1) {
+        throw new CliUsageError(`Several of your workspaces are named "${value}". Name one by its id:\n${workspaceLines(ambiguous)}`);
+    }
+    throw new CliUsageError(`"${value}" is not one of your workspaces. Yours:\n${workspaceLines(workspaces)}`);
+}
+export function createWorkspace(identity) {
+    const WORKSPACE_ENV = `${identity.envPrefix}_WORKSPACE`;
+    const ORG_ENV = `${identity.envPrefix}_ORG`;
+    /**
+     * The selection of this invocation, or undefined when nothing selects one.
+     *
+     * An empty `--org` or `--workspace` is a usage error (somebody meant to
+     * name one); an empty variable is an unset one (a CI variable that
+     * expanded to nothing) and falls through. Two flags, or two variables, at
+     * once is a usage error: one command runs in one place.
+     */
+    function pickWorkspaceSelection(input) {
+        if (input.orgFlag !== undefined && input.workspaceFlag !== undefined) {
+            throw new CliUsageError('Pass --org or --workspace, not both.');
+        }
+        if (input.orgFlag !== undefined) {
+            const value = input.orgFlag.trim();
+            if (!value)
+                throw new CliUsageError('--org needs an organization id or name.');
+            return { value, source: 'flag', kind: 'org' };
+        }
+        if (input.workspaceFlag !== undefined) {
+            const value = input.workspaceFlag.trim();
+            if (!value)
+                throw new CliUsageError('--workspace needs a workspace id or name.');
+            return { value, source: 'flag', kind: 'workspace' };
+        }
+        const org = input.env[ORG_ENV]?.trim();
+        const workspace = input.env[WORKSPACE_ENV]?.trim();
+        if (org && workspace) {
+            throw new CliUsageError(`Set ${ORG_ENV} or ${WORKSPACE_ENV}, not both.`);
+        }
+        if (org)
+            return { value: org, source: 'env', kind: 'org' };
+        if (workspace)
+            return { value: workspace, source: 'env', kind: 'workspace' };
+        return undefined;
+    }
+    /** How a selection reads in a sentence: `the --org flag`, `<PREFIX>_WORKSPACE`. */
+    function describeSelection(selection) {
+        if (selection.source === 'flag')
+            return selection.kind === 'org' ? 'the --org flag' : 'the --workspace flag';
+        return selection.kind === 'org' ? ORG_ENV : WORKSPACE_ENV;
+    }
+    /** The same, for `whoami`'s `chosen by` line. */
+    function describeSource(source, kind) {
+        if (source === 'default' || kind === undefined)
+            return "the server's default (nothing selected)";
+        return describeSelection({ source, kind });
+    }
+    /**
+     * What a refused request really meant, once `/me` answered WITHOUT the
+     * selection (so the key itself is good). Two refusals are the selection's:
+     *
+     *  - 403 `workspace_mismatch`: the key is pinned, and a selector-less `/me`
+     *    always resolves a pinned key to its pin — so `me.workspace` IS the pin.
+     *  - 401 `invalid_api_key`: the server answers a workspace the person does
+     *    not belong to exactly like an unknown key (no oracle, resolve-
+     *    membership.ts), which alone would send the person to check a good key.
+     *
+     * null = the selection does not explain it; the caller prints the plain error.
+     */
+    function explainRefusal(input) {
+        const { selection, me } = input;
+        const by = describeSelection(selection);
+        const noun = selection.kind === 'org' ? 'organization' : 'workspace';
+        const selected = findWorkspace(me.workspaces, input.workspaceId).match;
+        if (input.code === 'workspace_mismatch' && input.status === 403) {
+            const pin = me.workspace ? `"${me.workspace.name}" (${me.workspace.id})` : 'another workspace';
+            const asked = selected ? `"${selected.name}" (${selected.id})` : `"${selection.value}"`;
+            return (`This API key is pinned to the workspace ${pin}, and ${by} selects ${asked}. ` +
+                'A pinned key only ever acts in its own workspace: drop the selection, or use a key that is not pinned.');
+        }
+        if (input.code === 'invalid_api_key' && input.status === 401 && !selected) {
+            return (`The ${noun} "${selection.value}" (selected by ${by}) is not one of yours on ${input.baseUrl}; ` +
+                `the API key itself works. Yours:\n${workspaceLines(me.workspaces)}`);
+        }
+        return null;
+    }
+    return {
+        WORKSPACE_ENV,
+        ORG_ENV,
+        pickWorkspaceSelection,
+        describeSelection,
+        describeSource,
+        explainRefusal
+    };
+}
+//# sourceMappingURL=workspace.js.map

package/dist/workspace.js.map

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