@uic-coe-connect/cli 0.1.0

package/dist/commands/env.js

@@ -0,0 +1,122 @@
+import { readFileSync } from "node:fs";
+import { CliError } from "../client.js";
+import { emit, info, table } from "../output.js";
+import { register } from "../registry.js";
+import { resolveApp } from "./apps.js";
+/**
+ * Env values are secrets. They're masked by default and only printed in full
+ * behind an explicit `--show`, so an agent transcript or a shoulder-surfed
+ * terminal doesn't leak a database password from a routine `env list`.
+ */
+function mask(value) {
+    if (value.length <= 4)
+        return "••••";
+    return `${value.slice(0, 2)}${"•".repeat(Math.min(value.length - 4, 20))}${value.slice(-2)}`;
+}
+/** Parses KEY=VALUE lines (a .env file), ignoring blanks and # comments. */
+function parseDotenv(text) {
+    const out = {};
+    for (const raw of text.split("\n")) {
+        const line = raw.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        const eq = line.indexOf("=");
+        if (eq <= 0)
+            continue;
+        const key = line.slice(0, eq).trim();
+        let value = line.slice(eq + 1).trim();
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        out[key] = value;
+    }
+    return out;
+}
+export function registerEnvCommands() {
+    register({
+        name: "env list",
+        summary: "List an app's environment variables (values masked)",
+        usage: "env list <app> [--show]",
+        async run({ args, client }) {
+            const c = client();
+            const app = await resolveApp(c, args.arg(0, "app"));
+            const { env } = await c.request("GET", `/registered-apps/${app.id}/env`);
+            const show = args.bool("show");
+            emit({ appId: app.id, env: show ? env : Object.fromEntries(Object.entries(env).map(([k, v]) => [k, mask(v)])) }, () => {
+                table(Object.entries(env).map(([key, value]) => ({ key, value: show ? value : mask(value) })), ["key", "value"]);
+                if (!show && Object.keys(env).length > 0)
+                    info("\n(values masked — pass --show to reveal)");
+            });
+        },
+    }, {
+        name: "env get",
+        summary: "Print one variable's value",
+        usage: "env get <app> <KEY>",
+        async run({ args, client }) {
+            const c = client();
+            const app = await resolveApp(c, args.arg(0, "app"));
+            const key = args.arg(1, "KEY");
+            const { env } = await c.request("GET", `/registered-apps/${app.id}/env`);
+            if (!(key in env)) {
+                throw new CliError(`${app.id} has no variable "${key}".`, 4, `Set: ${Object.keys(env).join(", ") || "(none)"}`);
+            }
+            emit({ appId: app.id, key, value: env[key] }, () => process.stdout.write(`${env[key]}\n`));
+        },
+    }, {
+        name: "env set",
+        summary: "Set one or more variables",
+        usage: "env set <app> KEY=VALUE [KEY=VALUE...] | --from-file <.env>",
+        async run({ args, client }) {
+            const c = client();
+            const app = await resolveApp(c, args.arg(0, "app"));
+            const { env } = await c.request("GET", `/registered-apps/${app.id}/env`);
+            const updates = {};
+            const file = args.flag("from-file");
+            if (file) {
+                try {
+                    Object.assign(updates, parseDotenv(readFileSync(file, "utf8")));
+                }
+                catch (error) {
+                    throw new CliError(`Could not read ${file}: ${error instanceof Error ? error.message : String(error)}`, 6);
+                }
+            }
+            for (const pair of args.positional.slice(1)) {
+                const eq = pair.indexOf("=");
+                if (eq <= 0) {
+                    throw new CliError(`"${pair}" is not KEY=VALUE.`, 6, "Example: coe env set myapp PORT=4000");
+                }
+                updates[pair.slice(0, eq).trim()] = pair.slice(eq + 1);
+            }
+            if (Object.keys(updates).length === 0) {
+                throw new CliError("Nothing to set.", 6, "Pass KEY=VALUE pairs or --from-file <.env>");
+            }
+            // Read-modify-write against the granular env route, so this never
+            // clobbers the app's name/url/icon the way a full record PUT would.
+            const next = { ...env, ...updates };
+            await c.request("PUT", `/registered-apps/${app.id}/env`, { env: next });
+            emit({ appId: app.id, set: Object.keys(updates), count: Object.keys(next).length }, () => info(`✓ Set ${Object.keys(updates).join(", ")} on ${app.id}`));
+        },
+    }, {
+        name: "env unset",
+        summary: "Remove one or more variables",
+        usage: "env unset <app> <KEY> [KEY...]",
+        async run({ args, client }) {
+            const c = client();
+            const app = await resolveApp(c, args.arg(0, "app"));
+            const keys = args.positional.slice(1);
+            if (keys.length === 0)
+                throw new CliError("Name at least one KEY to remove.", 6);
+            const { env } = await c.request("GET", `/registered-apps/${app.id}/env`);
+            const missing = keys.filter((k) => !(k in env));
+            if (missing.length > 0) {
+                throw new CliError(`${app.id} has no variable ${missing.map((m) => `"${m}"`).join(", ")}.`, 4);
+            }
+            const next = { ...env };
+            for (const key of keys)
+                delete next[key];
+            await c.request("PUT", `/registered-apps/${app.id}/env`, { env: next });
+            emit({ appId: app.id, removed: keys, count: Object.keys(next).length }, () => info(`✓ Removed ${keys.join(", ")} from ${app.id}`));
+        },
+    });
+}

package/dist/commands/pipelines.d.ts

@@ -0,0 +1 @@
+export declare function registerPipelineCommands(): void;

package/dist/commands/pipelines.js

@@ -0,0 +1,187 @@
+import { readFileSync } from "node:fs";
+import { CliError } from "../client.js";
+import { emit, info, table } from "../output.js";
+import { register } from "../registry.js";
+import { resolveApp } from "./apps.js";
+/**
+ * Steps are written as a compact `type:arg` list so a pipeline can be created
+ * in one command instead of hand-authoring JSON:
+ *
+ *   pull  scan  npm:ci@backend  npm:build@backend  migrate:backend  chown  pm2:restart@my-api
+ *
+ * `--steps-file` takes the raw JSON array instead, for anything this shorthand
+ * can't express.
+ */
+function parseStep(token) {
+    const [head, subdir] = token.split("@");
+    const [type, arg] = head.split(":");
+    switch (type) {
+        case "pull":
+            return { type: "pull" };
+        case "scan":
+            return { type: "scan" };
+        case "chown":
+            return { type: "chown" };
+        case "npm":
+            if (!arg)
+                throw new CliError(`npm step needs a script: npm:ci or npm:build@subdir`, 6);
+            return { type: "npm", script: arg, subdir: subdir || undefined };
+        case "migrate":
+            return { type: "migrate", subdir: arg || subdir || undefined };
+        case "pm2":
+            if (!arg)
+                throw new CliError(`pm2 step needs an action: pm2:restart@process-name`, 6);
+            return { type: "pm2", action: arg, process: subdir || undefined };
+        default:
+            throw new CliError(`Unknown step "${token}".`, 6, "Valid: pull, scan, chown, npm:<script>[@subdir], migrate[:subdir], pm2:<action>[@process]");
+    }
+}
+function describeStep(step) {
+    switch (step.type) {
+        case "npm":
+            return `npm ${step.script}${step.subdir ? ` (${step.subdir})` : ""}`;
+        case "migrate":
+            return `migrate${step.subdir ? ` (${step.subdir})` : ""}`;
+        case "pm2":
+            return `pm2 ${step.action}${step.process ? ` ${step.process}` : ""}`;
+        default:
+            return step.type;
+    }
+}
+function stepsFrom(args) {
+    const file = args.flag("steps-file");
+    if (file) {
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(file, "utf8"));
+        }
+        catch (error) {
+            throw new CliError(`Could not read steps from ${file}: ${error instanceof Error ? error.message : String(error)}`, 6);
+        }
+        if (!Array.isArray(parsed))
+            throw new CliError(`${file} must contain a JSON array of steps.`, 6);
+        return parsed;
+    }
+    return [];
+}
+/** Saves the whole pipeline set back — the API replaces the array wholesale. */
+async function savePipelines(client, appId, pipelines) {
+    return client.request("PUT", `/registered-apps/${appId}/pipelines`, { pipelines });
+}
+function findPipeline(app, ref) {
+    const pipelines = app.pipelines ?? [];
+    const found = pipelines.find((p) => p.id === ref) ??
+        pipelines.find((p) => p.name.toLowerCase() === ref.toLowerCase());
+    if (!found) {
+        throw new CliError(`No pipeline "${ref}" on ${app.id}.`, 4, pipelines.length > 0
+            ? `Available: ${pipelines.map((p) => p.name).join(", ")}`
+            : "That app has no pipelines yet — create one with: coe pipelines create");
+    }
+    return found;
+}
+export function registerPipelineCommands() {
+    register({
+        name: "pipelines list",
+        summary: "List an app's deploy pipelines",
+        usage: "pipelines list <app>",
+        async run({ args, client }) {
+            const app = await resolveApp(client(), args.arg(0, "app"));
+            const pipelines = app.pipelines ?? [];
+            emit({ appId: app.id, pipelines }, () => {
+                table(pipelines.map((p) => ({
+                    id: p.id,
+                    name: p.name,
+                    steps: p.config.steps.map(describeStep).join(" → "),
+                })), ["id", "name", "steps"]);
+            });
+        },
+    }, {
+        name: "pipelines show",
+        summary: "Show one pipeline's steps as JSON",
+        usage: "pipelines show <app> <pipeline>",
+        async run({ args, client }) {
+            const app = await resolveApp(client(), args.arg(0, "app"));
+            const pipeline = findPipeline(app, args.arg(1, "pipeline"));
+            emit(pipeline, () => {
+                info(`${pipeline.name} (${pipeline.id})`);
+                pipeline.config.steps.forEach((step, i) => {
+                    info(`  ${i + 1}. ${describeStep(step)}`);
+                });
+            });
+        },
+    }, {
+        name: "pipelines create",
+        summary: "Create a pipeline from a step list",
+        usage: 'pipelines create <app> --name "Full deploy" <step>... | --steps-file <f.json>',
+        details: [
+            "Steps: pull, scan, chown, npm:<script>[@subdir], migrate[:subdir], pm2:<action>[@process]",
+            'Example: coe pipelines create myapp --name "Full" pull scan npm:ci@backend pm2:restart@myapp-api',
+        ],
+        async run({ args, client }) {
+            const c = client();
+            const app = await resolveApp(c, args.arg(0, "app"));
+            const name = args.flag("name");
+            if (!name)
+                throw new CliError("--name is required.", 6);
+            const steps = [
+                ...stepsFrom(args),
+                ...args.positional.slice(1).map(parseStep),
+            ];
+            if (steps.length === 0) {
+                throw new CliError("A pipeline needs at least one step.", 6, "Run: coe help");
+            }
+            const pipelines = [...(app.pipelines ?? [])];
+            if (pipelines.some((p) => p.name.toLowerCase() === name.toLowerCase())) {
+                throw new CliError(`${app.id} already has a pipeline named "${name}".`, 6);
+            }
+            // Ids are assigned server-side on save; a placeholder keeps the shape valid.
+            pipelines.push({ id: "", name, config: { steps } });
+            const updated = await savePipelines(c, app.id, pipelines);
+            const created = (updated.pipelines ?? []).find((p) => p.name === name);
+            emit({ appId: app.id, pipeline: created }, () => info(`✓ Created pipeline "${name}" on ${app.id} (${steps.length} steps)`));
+        },
+    }, {
+        name: "pipelines set-steps",
+        summary: "Replace an existing pipeline's steps",
+        usage: "pipelines set-steps <app> <pipeline> <step>... | --steps-file <f.json>",
+        async run({ args, client }) {
+            const c = client();
+            const app = await resolveApp(c, args.arg(0, "app"));
+            const pipeline = findPipeline(app, args.arg(1, "pipeline"));
+            const steps = [...stepsFrom(args), ...args.positional.slice(2).map(parseStep)];
+            if (steps.length === 0)
+                throw new CliError("A pipeline needs at least one step.", 6);
+            const pipelines = (app.pipelines ?? []).map((p) => p.id === pipeline.id ? { ...p, config: { steps } } : p);
+            await savePipelines(c, app.id, pipelines);
+            emit({ appId: app.id, pipelineId: pipeline.id, steps }, () => info(`✓ Updated "${pipeline.name}" on ${app.id} (${steps.length} steps)`));
+        },
+    }, {
+        name: "pipelines rename",
+        summary: "Rename a pipeline",
+        usage: "pipelines rename <app> <pipeline> <new-name>",
+        async run({ args, client }) {
+            const c = client();
+            const app = await resolveApp(c, args.arg(0, "app"));
+            const pipeline = findPipeline(app, args.arg(1, "pipeline"));
+            const newName = args.arg(2, "new-name");
+            const pipelines = (app.pipelines ?? []).map((p) => p.id === pipeline.id ? { ...p, name: newName } : p);
+            await savePipelines(c, app.id, pipelines);
+            emit({ appId: app.id, pipelineId: pipeline.id, name: newName }, () => info(`✓ Renamed "${pipeline.name}" → "${newName}"`));
+        },
+    }, {
+        name: "pipelines delete",
+        summary: "Delete a pipeline",
+        usage: "pipelines delete <app> <pipeline> --yes",
+        async run({ args, client }) {
+            const c = client();
+            const app = await resolveApp(c, args.arg(0, "app"));
+            const pipeline = findPipeline(app, args.arg(1, "pipeline"));
+            if (!args.bool("yes")) {
+                throw new CliError(`This deletes pipeline "${pipeline.name}" from ${app.id}.`, 6, "Re-run with --yes to confirm.");
+            }
+            const pipelines = (app.pipelines ?? []).filter((p) => p.id !== pipeline.id);
+            await savePipelines(c, app.id, pipelines);
+            emit({ appId: app.id, deleted: pipeline.id }, () => info(`✓ Deleted pipeline "${pipeline.name}" from ${app.id}`));
+        },
+    });
+}

package/dist/config.d.ts

@@ -0,0 +1,19 @@
+export interface Credentials {
+    server: string;
+    netid: string;
+    token: string;
+    expiresAt: string;
+}
+/**
+ * Which server to talk to, most specific wins: --server flag, then COE_SERVER,
+ * then a saved config, then the dev deployment.
+ */
+export declare function resolveServer(flag?: string): string;
+export declare function saveServer(server: string): void;
+export declare function readCredentials(): Credentials | null;
+export declare function saveCredentials(creds: Credentials): void;
+export declare function clearCredentials(): void;
+export declare function credentialsPath(): string;
+export declare function hasCredentialsFile(): boolean;
+/** A human-recognizable name for this session, shown on the approval page. */
+export declare function sessionLabel(): string;

package/dist/config.js

@@ -0,0 +1,67 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir, hostname } from "node:os";
+import path from "node:path";
+/**
+ * Config and credentials live under ~/.coeconnect. Credentials are a separate
+ * file from config so the token can be 0600 and deleted on logout without
+ * disturbing the (non-secret) server URL.
+ */
+const DIR = process.env.COE_CONFIG_DIR ?? path.join(homedir(), ".coeconnect");
+const CONFIG_FILE = path.join(DIR, "config.json");
+const CREDENTIALS_FILE = path.join(DIR, "credentials.json");
+const DEFAULT_SERVER = "https://devcoeconnect.engineering.uic.edu";
+function readJson(file) {
+    try {
+        return JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function writeJson(file, value, mode) {
+    mkdirSync(DIR, { recursive: true, mode: 0o700 });
+    writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`, { mode });
+    chmodSync(file, mode); // enforce even if the file pre-existed with looser bits
+}
+/**
+ * Which server to talk to, most specific wins: --server flag, then COE_SERVER,
+ * then a saved config, then the dev deployment.
+ */
+export function resolveServer(flag) {
+    const chosen = flag ?? process.env.COE_SERVER ?? readJson(CONFIG_FILE)?.server ?? DEFAULT_SERVER;
+    return chosen.replace(/\/+$/, "");
+}
+export function saveServer(server) {
+    writeJson(CONFIG_FILE, { ...readJson(CONFIG_FILE), server }, 0o600);
+}
+export function readCredentials() {
+    const creds = readJson(CREDENTIALS_FILE);
+    if (!creds?.token)
+        return null;
+    // An expired token is the same as none — surface "run coe login" rather than
+    // letting the server return a confusing 401 on the real command.
+    if (Date.parse(creds.expiresAt) <= Date.now())
+        return null;
+    return creds;
+}
+export function saveCredentials(creds) {
+    writeJson(CREDENTIALS_FILE, creds, 0o600);
+}
+export function clearCredentials() {
+    try {
+        rmSync(CREDENTIALS_FILE);
+    }
+    catch {
+        /* already gone */
+    }
+}
+export function credentialsPath() {
+    return CREDENTIALS_FILE;
+}
+export function hasCredentialsFile() {
+    return existsSync(CREDENTIALS_FILE);
+}
+/** A human-recognizable name for this session, shown on the approval page. */
+export function sessionLabel() {
+    return `${process.env.USER ?? "user"}@${hostname()}`;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+import { CliError, createClient } from "./client.js";
+import { registerAccessCommands } from "./commands/access.js";
+import { registerAppCommands } from "./commands/apps.js";
+import { registerAuthCommands } from "./commands/auth.js";
+import { registerDeployCommands } from "./commands/deploy.js";
+import { registerEnvCommands } from "./commands/env.js";
+import { registerPipelineCommands } from "./commands/pipelines.js";
+import { info, setJsonMode } from "./output.js";
+import { allCommands, findCommand, register } from "./registry.js";
+registerAuthCommands();
+registerAppCommands();
+registerPipelineCommands();
+registerDeployCommands();
+registerAccessCommands();
+registerEnvCommands();
+function parseArgs(argv) {
+    const positional = [];
+    const flags = {};
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (!token.startsWith("--")) {
+            positional.push(token);
+            continue;
+        }
+        const body = token.slice(2);
+        const eq = body.indexOf("=");
+        if (eq >= 0) {
+            flags[body.slice(0, eq)] = body.slice(eq + 1);
+            continue;
+        }
+        // `--flag value` unless the next token is itself a flag (then it's boolean).
+        const next = argv[i + 1];
+        if (next !== undefined && !next.startsWith("--")) {
+            flags[body] = next;
+            i++;
+        }
+        else {
+            flags[body] = true;
+        }
+    }
+    return {
+        positional,
+        flags,
+        arg(index, name) {
+            const value = positional[index];
+            if (!value)
+                throw new CliError(`Missing <${name}>.`, 6, "Run: coe help");
+            return value;
+        },
+        flag(name) {
+            const value = flags[name];
+            return typeof value === "string" ? value : undefined;
+        },
+        bool(name) {
+            return flags[name] !== undefined;
+        },
+    };
+}
+function printHelp() {
+    const lines = [
+        "coe — manage COEConnect apps from a terminal",
+        "",
+        "USAGE",
+        "  coe <command> [args] [--flags]",
+        "",
+        "COMMANDS",
+    ];
+    const width = Math.max(...allCommands().map((c) => c.usage.length));
+    for (const command of allCommands()) {
+        lines.push(`  ${command.usage.padEnd(width)}  ${command.summary}`);
+    }
+    lines.push("", "GLOBAL FLAGS", "  --json           Machine-readable output on stdout (for scripts and AI agents)", "  --server <url>   Target a different COEConnect server", "  --help           Show this help", "", "AUTH", "  Run `coe login` and approve the code in your browser. The session lasts 12", "  hours and can only do what you can do in the web UI — you must be on an", "  app's dev team (or a webadmin) to manage it.");
+    process.stdout.write(`${lines.join("\n")}\n`);
+}
+register({
+    name: "help",
+    summary: "Show this help",
+    usage: "help",
+    anonymous: true,
+    async run() {
+        printHelp();
+    },
+});
+async function main() {
+    const argv = process.argv.slice(2);
+    const args = parseArgs(argv);
+    setJsonMode(args.bool("json"));
+    if (argv.length === 0 || args.bool("help")) {
+        printHelp();
+        return;
+    }
+    const found = findCommand(args.positional);
+    if (!found) {
+        throw new CliError(`Unknown command: ${args.positional.join(" ")}`, 6, "Run: coe help");
+    }
+    // Positionals are re-based so a command sees only its own arguments.
+    const scoped = { ...args, positional: found.rest, arg: args.arg, flag: args.flag, bool: args.bool };
+    scoped.arg = (index, name) => {
+        const value = found.rest[index];
+        if (!value)
+            throw new CliError(`Missing <${name}>.`, 6, `Usage: coe ${found.command.usage}`);
+        return value;
+    };
+    await found.command.run({
+        args: scoped,
+        client: () => createClient({ server: args.flag("server"), anonymous: found.command.anonymous }),
+    });
+}
+main().catch((error) => {
+    if (error instanceof CliError) {
+        info(`error: ${error.message}`);
+        if (error.hint)
+            info(`  ${error.hint}`);
+        process.exit(error.exitCode);
+    }
+    info(`error: ${error instanceof Error ? error.message : String(error)}`);
+    process.exit(1);
+});

package/dist/output.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Output helpers.
+ *
+ * Every command supports `--json`, and that isn't a nicety: an AI driving this
+ * CLI should parse a documented shape instead of scraping aligned columns. In
+ * JSON mode nothing but the payload may touch stdout — progress and warnings
+ * go to stderr — so the whole of stdout is always valid JSON.
+ */
+export declare function setJsonMode(on: boolean): void;
+export declare function isJsonMode(): boolean;
+/** The command's result. In JSON mode this is the only thing on stdout. */
+export declare function emit(data: unknown, human: () => void): void;
+/** Progress/status chatter. Always stderr, so it never pollutes piped JSON. */
+export declare function info(message: string): void;
+export declare function warn(message: string): void;
+/** Minimal column alignment — no dependency, and stable enough to eyeball. */
+export declare function table(rows: Array<Record<string, string>>, columns: string[]): void;
+/** Key/value block for `show`-style commands. */
+export declare function details(pairs: Array<[string, string]>): void;

package/dist/output.js

@@ -0,0 +1,51 @@
+/**
+ * Output helpers.
+ *
+ * Every command supports `--json`, and that isn't a nicety: an AI driving this
+ * CLI should parse a documented shape instead of scraping aligned columns. In
+ * JSON mode nothing but the payload may touch stdout — progress and warnings
+ * go to stderr — so the whole of stdout is always valid JSON.
+ */
+let jsonMode = false;
+export function setJsonMode(on) {
+    jsonMode = on;
+}
+export function isJsonMode() {
+    return jsonMode;
+}
+/** The command's result. In JSON mode this is the only thing on stdout. */
+export function emit(data, human) {
+    if (jsonMode) {
+        process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+        return;
+    }
+    human();
+}
+/** Progress/status chatter. Always stderr, so it never pollutes piped JSON. */
+export function info(message) {
+    process.stderr.write(`${message}\n`);
+}
+export function warn(message) {
+    process.stderr.write(`warning: ${message}\n`);
+}
+/** Minimal column alignment — no dependency, and stable enough to eyeball. */
+export function table(rows, columns) {
+    if (rows.length === 0) {
+        info("(none)");
+        return;
+    }
+    const width = (col) => Math.max(col.length, ...rows.map((r) => (r[col] ?? "").length));
+    const widths = columns.map(width);
+    const line = (cells) => cells.map((c, i) => c.padEnd(i === cells.length - 1 ? 0 : widths[i])).join("  ").trimEnd();
+    process.stdout.write(`${line(columns.map((c) => c.toUpperCase()))}\n`);
+    for (const row of rows) {
+        process.stdout.write(`${line(columns.map((c) => row[c] ?? ""))}\n`);
+    }
+}
+/** Key/value block for `show`-style commands. */
+export function details(pairs) {
+    const width = Math.max(...pairs.map(([k]) => k.length));
+    for (const [k, v] of pairs) {
+        process.stdout.write(`${k.padEnd(width)}  ${v}\n`);
+    }
+}

package/dist/registry.d.ts

@@ -0,0 +1,43 @@
+import type { Client } from "./client.js";
+/**
+ * Parsed argv: positional words plus `--flag` / `--flag=value` options.
+ * Deliberately tiny — the alternative is a dependency, and the surface here is
+ * a fixed set of long flags with no clustering or coercion to get wrong.
+ */
+export interface Args {
+    positional: string[];
+    flags: Record<string, string | true>;
+    /** A required positional, by index, with a message naming what's missing. */
+    arg(index: number, name: string): string;
+    /** A flag's value, or undefined. `--flag` with no value reads as true. */
+    flag(name: string): string | undefined;
+    bool(name: string): boolean;
+}
+export interface CommandContext {
+    args: Args;
+    /** Built lazily so `login` and `help` can run without credentials. */
+    client: () => Client;
+}
+export interface Command {
+    /** Invocation name, e.g. "apps list" — may be multi-word. */
+    name: string;
+    summary: string;
+    /** Usage line shown in help, minus the leading `coe`. */
+    usage: string;
+    /** Longer help, one line per entry. */
+    details?: string[];
+    /** True for commands runnable without a session (login, help, version). */
+    anonymous?: boolean;
+    run(ctx: CommandContext): Promise<void>;
+}
+export declare function register(...toAdd: Command[]): void;
+export declare function allCommands(): readonly Command[];
+/**
+ * Resolve argv against the registry, longest name first so "apps list" wins
+ * over a hypothetical "apps". Returns the command and the positionals left
+ * after its name is consumed.
+ */
+export declare function findCommand(words: string[]): {
+    command: Command;
+    rest: string[];
+} | null;

package/dist/registry.js

@@ -0,0 +1,27 @@
+/**
+ * The registry is the extension point: adding a capability means appending a
+ * Command here, and it automatically gains help text, --json, arg parsing, auth
+ * and error handling. Nothing else in the CLI needs to change.
+ */
+const commands = [];
+export function register(...toAdd) {
+    commands.push(...toAdd);
+}
+export function allCommands() {
+    return commands;
+}
+/**
+ * Resolve argv against the registry, longest name first so "apps list" wins
+ * over a hypothetical "apps". Returns the command and the positionals left
+ * after its name is consumed.
+ */
+export function findCommand(words) {
+    const byLength = [...commands].sort((a, b) => b.name.split(" ").length - a.name.split(" ").length);
+    for (const command of byLength) {
+        const parts = command.name.split(" ");
+        if (parts.every((part, i) => words[i] === part)) {
+            return { command, rest: words.slice(parts.length) };
+        }
+    }
+    return null;
+}