@poietic-tech/cli 0.0.0-stage → 0.1.0

package/dist/errors.js

@@ -0,0 +1,139 @@
+import { sanitize } from "./text.js";
+import { PoieticAuthError } from "@poietic-tech/auth";
+import { CredentialFileError, LoginDenied, LoginExpired, UnsupportedPlatform, UntrustedServer, } from "@poietic-tech/auth/node";
+/** The exit-code table, verbatim. */
+export const EXIT_ROWS = [
+    { exit: 0, meaning: "success", codes: [] },
+    { exit: 1, meaning: "unexpected failure", codes: ["internal", "module_failed"] },
+    { exit: 2, meaning: "usage error", codes: ["bad_usage", "bad_request"] },
+    { exit: 3, meaning: "not logged in, or the login was refused", codes: ["not_logged_in"] },
+    { exit: 4, meaning: "not found", codes: ["no_such_agent", "not_found"] },
+    {
+        exit: 5,
+        meaning: "not allowed",
+        codes: ["agent_not_allowed", "not_allowed", "not_a_builder", "cannot_delegate", "quota_exceeded", "too_many_tokens"],
+    },
+    { exit: 6, meaning: "a step-up is needed and `--no-wait` was given", codes: ["reauth_required"] },
+    { exit: 7, meaning: "the login or step-up was denied or expired", codes: ["login_denied", "login_expired"] },
+    {
+        exit: 8,
+        meaning: "network, server or local environment failure",
+        codes: ["network", "server_error", "untrusted_server", "credential_file", "unsupported_platform"],
+    },
+    { exit: 130, meaning: "interrupted by Ctrl-C", codes: ["interrupted"] },
+];
+export const EXIT = Object.assign(Object.create(null), Object.fromEntries(EXIT_ROWS.flatMap((r) => r.codes.map((c) => [c, r.exit]))));
+/** Exit code for a code the table does not name: by HTTP status. */
+function exitByStatus(status) {
+    if (status === undefined)
+        return 1;
+    if (status === 400 || status === 409 || status === 422)
+        return 2;
+    if (status === 401)
+        return 3;
+    if (status === 403)
+        return 5;
+    if (status === 404)
+        return 4;
+    if (status === 0 || status === 429 || status >= 500)
+        return 8;
+    return 1;
+}
+export function exitCodeOf(code, status) {
+    return Object.hasOwn(EXIT, code) ? EXIT[code] : exitByStatus(status);
+}
+export class CliError extends Error {
+    code;
+    exitCode;
+    status;
+    constructor(code, message, opts = {}) {
+        super(message);
+        this.name = "CliError";
+        this.code = code;
+        this.exitCode = exitCodeOf(code, opts.status);
+        if (opts.status !== undefined)
+            this.status = opts.status;
+    }
+}
+const NETWORK_CODES = /^(ECONNREFUSED|ENOTFOUND|ECONNRESET|ETIMEDOUT)$/;
+/** The code a status stands for when the server named none. */
+export function codeByStatus(status) {
+    if (status === 401)
+        return "not_logged_in";
+    if (status === 403)
+        return "not_allowed";
+    if (status === 404)
+        return "not_found";
+    if (status === 400 || status === 409 || status === 422)
+        return "bad_request";
+    if (status === 0 || status === 429 || status >= 500)
+        return "server_error";
+    return "internal";
+}
+export function toCliError(error, signal) {
+    if (error instanceof CliError)
+        return error;
+    if (signal.aborted)
+        return new CliError("interrupted", "Interrupted.");
+    if (error instanceof LoginDenied)
+        return new CliError("login_denied", error.message, { status: error.status });
+    if (error instanceof LoginExpired)
+        return new CliError("login_expired", error.message, { status: error.status });
+    if (error instanceof UntrustedServer)
+        return new CliError("untrusted_server", error.message);
+    if (error instanceof CredentialFileError)
+        return new CliError("credential_file", error.message);
+    if (error instanceof UnsupportedPlatform)
+        return new CliError("unsupported_platform", error.message);
+    if (error instanceof PoieticAuthError) {
+        return new CliError(error.code ?? codeByStatus(error.status), error.message, { status: error.status });
+    }
+    if (error instanceof TypeError) {
+        const cause = error.cause;
+        if (/fetch failed/.test(error.message) || (typeof cause?.code === "string" && NETWORK_CODES.test(cause.code))) {
+            return new CliError("network", "Cannot reach the auth server.");
+        }
+    }
+    return new CliError("internal", error instanceof Error ? error.message : "Unexpected failure.");
+}
+/**
+ * A login credential, an agent token or a JWT, starting where a word starts: "compat_bot" is a
+ * name, not a token. "_" may precede one, so "ci_pat_…" is still caught, and so may a percent or
+ * backslash escape, so "code%3Dpcl_…" and a literal "\npat_…" are too.
+ */
+const SECRET = /(?:(?<![A-Za-z0-9])|(?<=%[0-9A-Fa-f]{2})|(?<=\\[nrt])|(?<=\\u[0-9A-Fa-f]{4}))(?:pcl_[A-Za-z0-9_-]+|pat_[A-Za-z0-9_-]+|eyJ[\w-]*\.[\w-]+\.[\w-]*)/g;
+export function redact(text) {
+    return text.replace(SECRET, "[redacted]");
+}
+export function renderError(e, machine, color) {
+    const message = redact(e.message);
+    if (machine) {
+        return JSON.stringify({ error: redact(e.code), message, ...(e.status !== undefined ? { status: e.status } : {}) }) + "\n";
+    }
+    return `${color ? "\x1b[31merror:\x1b[0m" : "error:"} ${sanitize(message)}\n`;
+}
+const API_CODE = /^[a-z][a-z0-9_]{0,63}$/;
+const API_MESSAGES = Object.assign(Object.create(null), {
+    name_taken: "An agent with that name already exists.",
+    quota_exceeded: "You have reached your agent quota.",
+    too_many_tokens: "This agent already has the most live tokens it may have.",
+    not_allowed: "Your account may not manage agents.",
+    not_a_builder: "The agent you act as is not a builder.",
+});
+/** The error for a failed auth-server answer. The body is read for its code only, never quoted. */
+export async function apiError(res, what) {
+    let code;
+    try {
+        const body = await res.json();
+        const c = body !== null && typeof body === "object" ? body.error : undefined;
+        // A secret-shaped "code" is no code: it would be printed as the error's name.
+        if (typeof c === "string" && API_CODE.test(c) && redact(c) === c)
+            code = c;
+    }
+    catch {
+        // not JSON: the status decides
+    }
+    const named = code ?? codeByStatus(res.status);
+    const message = API_MESSAGES[named] ?? `${what} failed: ${res.status} (${named})`;
+    return new CliError(named, message, { status: res.status });
+}

package/dist/interrupt.d.ts

@@ -0,0 +1,11 @@
+/** What `onInterrupt` needs of `process`, so a test can stand in for it. */
+export interface SignalSource {
+    on(event: "SIGINT", listener: () => void): unknown;
+}
+/**
+ * Ctrl-C. The first press aborts the run's signal, which every request, wait and sleep the host
+ * makes honours, so the command ends itself with exit 130 (and a login can still revoke the
+ * session it was collecting). A module's own work may not listen, so a second press exits 130 at
+ * once. Listening at all turns off Node's default exit, which is why the second press is needed.
+ */
+export declare function onInterrupt(proc: SignalSource, controller: AbortController, exit: (code: number) => void): void;

package/dist/interrupt.js

@@ -0,0 +1,14 @@
+/**
+ * Ctrl-C. The first press aborts the run's signal, which every request, wait and sleep the host
+ * makes honours, so the command ends itself with exit 130 (and a login can still revoke the
+ * session it was collecting). A module's own work may not listen, so a second press exits 130 at
+ * once. Listening at all turns off Node's default exit, which is why the second press is needed.
+ */
+export function onInterrupt(proc, controller, exit) {
+    proc.on("SIGINT", () => {
+        if (controller.signal.aborted)
+            exit(130);
+        else
+            controller.abort();
+    });
+}

package/dist/io.d.ts

@@ -0,0 +1,18 @@
+/** Everything the command touches outside its own process, injected so tests can fake it. */
+export interface CliIO {
+    stdout(t: string): void;
+    stderr(t: string): void;
+    env: Readonly<Record<string, string | undefined>>;
+    cwd: string;
+    stdoutIsTTY: boolean;
+    stderrIsTTY: boolean;
+    now(): number;
+    sleep(ms: number, signal?: AbortSignal): Promise<void>;
+    openBrowser(url: string): void;
+    signal: AbortSignal;
+    hostname: string;
+    platform: string;
+    hostDir: string;
+    execPath: string;
+}
+export declare function processIO(signal: AbortSignal): CliIO;

package/dist/io.js

@@ -0,0 +1,48 @@
+/// <reference types="node" />
+import { spawn } from "node:child_process";
+import { hostname } from "node:os";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+export function processIO(signal) {
+    return {
+        stdout: (t) => void process.stdout.write(t),
+        stderr: (t) => void process.stderr.write(t),
+        env: process.env,
+        cwd: process.cwd(),
+        stdoutIsTTY: process.stdout.isTTY === true,
+        stderrIsTTY: process.stderr.isTTY === true,
+        now: () => Date.now() / 1000,
+        sleep: (ms, s) => new Promise((resolve, reject) => {
+            if (s?.aborted)
+                return reject(s.reason);
+            const onAbort = () => {
+                clearTimeout(timer);
+                reject(s.reason);
+            };
+            const timer = setTimeout(() => {
+                s?.removeEventListener("abort", onAbort);
+                resolve();
+            }, ms);
+            s?.addEventListener("abort", onAbort, { once: true });
+        }),
+        openBrowser: (url) => {
+            try {
+                const child = spawn(process.platform === "darwin" ? "open" : "xdg-open", [url], {
+                    detached: true,
+                    stdio: "ignore",
+                });
+                child.on("error", () => { });
+                child.unref();
+            }
+            catch {
+                // No browser to open: the link is printed anyway.
+            }
+        },
+        signal,
+        hostname: hostname(),
+        platform: process.platform,
+        // src/io.ts and dist/io.js both sit one level below the package directory.
+        hostDir: dirname(dirname(fileURLToPath(import.meta.url))),
+        execPath: process.execPath,
+    };
+}

package/dist/main.d.ts

@@ -0,0 +1,10 @@
+import { Command } from "commander";
+import { VERSION, type Builtin, type Host } from "./context.js";
+import type { CliIO } from "./io.js";
+import type { PoieticTechModule } from "./module.js";
+export { VERSION };
+/** Attach a module as `name`, with the shared output configuration, and run its setup. */
+export declare function registerModule(host: Host, program: Command, name: string, mod: PoieticTechModule, summary: string): Promise<Command>;
+/** The command the arguments name, without parsing them: `x` for `help <x>`. */
+export declare function firstOperand(argv: string[]): string | undefined;
+export declare function run(argv: string[], io: CliIO, builtins?: Builtin[]): Promise<number>;

package/dist/main.js

@@ -0,0 +1,177 @@
+import { Command, CommanderError, Option } from "commander";
+import { CliError, EXIT_ROWS, renderError, toCliError } from "./errors.js";
+import { createContext, createHost, VERSION } from "./context.js";
+import { agentsBuiltin } from "./modules/agents.js";
+import { authBuiltins } from "./modules/auth.js";
+import { modulesBuiltin } from "./modules/modules.js";
+import { readAllowed } from "./allowlist.js";
+import { discover, discoveryRoots, importModule, stateText } from "./discovery.js";
+import { sanitize } from "./text.js";
+import { colourOn, prescanFormat, resolveGlobals } from "./output.js";
+export { VERSION };
+/** The built-ins `run` registers when none are passed. */
+const DEFAULT_BUILTINS = [...authBuiltins, agentsBuiltin, modulesBuiltin];
+function configure(cmd, io) {
+    // Errors are rendered by `run` (outputError is silenced), so the only text commander sends to
+    // writeErr is the help it shows for a command named without a subcommand. That help is the
+    // answer, not an error, so it goes to stdout and `run` exits 0.
+    cmd
+        .exitOverride()
+        .configureOutput({ writeOut: (s) => io.stdout(sanitize(s)), writeErr: (s) => io.stdout(sanitize(s)), outputError: () => { } });
+    for (const sub of cmd.commands)
+        configure(sub, io);
+}
+function buildProgram(io, host) {
+    const program = new Command("poietic-tech")
+        .version(VERSION, "-V, --version")
+        .option("--json", "same as --format json")
+        .addOption(new Option("--format <format>", "output format").choices(["table", "json", "ndjson", "ids"]))
+        .option("-q, --quiet", "print only what was asked for")
+        .option("--server <origin>", "the auth server to use")
+        .option("--no-wait", "fail instead of waiting for a step-up")
+        .option("--no-color", "never colour output");
+    program.hook("preAction", (_, action) => {
+        const o = action.optsWithGlobals();
+        host.globals = resolveGlobals({ ...o, color: o.color !== false, wait: o.wait !== false }, io);
+    });
+    configure(program, io);
+    return program;
+}
+/** `help [topic]`: the root help, `exit-codes`, or the help of a registered command. */
+function addHelp(program, io) {
+    program
+        .helpCommand(false)
+        .command("help [topic]")
+        .description("show help, or `help exit-codes` for the exit codes")
+        .action((topic) => {
+        if (topic === undefined)
+            return program.outputHelp();
+        if (topic === "exit-codes") {
+            for (const r of EXIT_ROWS)
+                io.stdout(`${r.exit}  ${r.meaning}${r.codes.length ? `  (${r.codes.join(", ")})` : ""}\n`);
+            return;
+        }
+        const target = program.commands.find((c) => c.name() === topic && c.name() !== "help");
+        if (!target)
+            throw new CliError("bad_usage", `No help topic "${sanitize(topic)}"; try \`poietic-tech --help\`.`);
+        target.outputHelp();
+    });
+    configure(program.commands.at(-1), io);
+}
+/** Attach a module as `name`, with the shared output configuration, and run its setup. */
+export async function registerModule(host, program, name, mod, summary) {
+    const cmd = program.command(name).description(summary);
+    configure(cmd, host.io);
+    await mod.setup(createContext(host, cmd));
+    // Subcommands made with `new Command` and added by the module inherit nothing.
+    configure(cmd, host.io);
+    return cmd;
+}
+/** Global options that take a value, so the value is not mistaken for the command. */
+const VALUED = new Set(["--format", "--server"]);
+/** The command the arguments name, without parsing them: `x` for `help <x>`. */
+export function firstOperand(argv) {
+    const operands = [];
+    for (let i = 0; i < argv.length && operands.length < 2; i++) {
+        const a = argv[i];
+        if (a === "--") {
+            operands.push(...argv.slice(i + 1, i + 3));
+            break;
+        }
+        if (VALUED.has(a))
+            i++;
+        else if (!a.startsWith("-")) {
+            operands.push(a);
+            if (operands[0] !== "help")
+                break;
+        }
+    }
+    return operands[0] === "help" ? (operands[1] ?? "help") : operands[0];
+}
+/**
+ * Find the modules, import and register the one the arguments name, and give
+ * every other available one a placeholder so --help lists it from its summary.
+ */
+async function addModules(host, program, argv, builtinNames) {
+    const { io } = host;
+    const operand = firstOperand(argv);
+    // A built-in, or the built-in help topic `exit-codes`: no module is looked for, let alone imported.
+    if (operand === "exit-codes" || (operand !== undefined && operand !== "help" && builtinNames.includes(operand)))
+        return;
+    let allowed = [];
+    let held = null;
+    try {
+        allowed = await readAllowed(io.env);
+    }
+    catch (error) {
+        held = error;
+    }
+    const roots = discoveryRoots(io.hostDir, io.execPath);
+    const found = await discover(roots, allowed, { builtins: builtinNames });
+    for (const d of found) {
+        if (d.state.kind !== "available" || d.command === null)
+            continue;
+        if (d.command !== operand) {
+            configure(program.command(d.command).description(d.summary), io);
+            continue;
+        }
+        const mod = await importModule(d);
+        try {
+            await registerModule(host, program, d.command, mod, d.summary);
+        }
+        catch {
+            throw new CliError("module_failed", `The module ${d.name} failed to load.`);
+        }
+    }
+    // A broken allow file matters only to a command it could have named.
+    const scoped = found.some((d) => d.command === operand && d.name.startsWith("@poietic-tech/"));
+    if (held !== null && operand !== undefined && operand !== "help" && !scoped)
+        throw held;
+    if (operand === undefined || operand === "help" || found.some((d) => d.command === operand && d.state.kind === "available"))
+        return;
+    // Say why a module's command does not run, rather than "unknown command". Only on this
+    // failing path are other packages' package.json files read, to find a not-allowed one.
+    const blocked = found.find((d) => d.command === operand) ??
+        (held === null
+            ? (await discover(roots, allowed, { builtins: builtinNames, unscoped: true })).find((d) => d.command === operand)
+            : undefined);
+    if (blocked)
+        throw notRunnable(blocked);
+}
+function notRunnable(d) {
+    if (d.state.kind === "not-allowed") {
+        return new CliError("bad_usage", `"${d.command}" comes from ${d.name}, which is not allowed; allow it with \`poietic-tech modules allow ${d.name}\`.`);
+    }
+    return new CliError("bad_usage", `"${d.command}" comes from ${d.name}, which does not run (${stateText(d.state)}); see \`poietic-tech modules list\`.`);
+}
+export async function run(argv, io, builtins = DEFAULT_BUILTINS) {
+    const host = createHost(io);
+    const fail = (e) => {
+        const format = host.globals?.format ?? prescanFormat(argv, io);
+        const noColor = argv.slice(0, argv.indexOf("--") < 0 ? argv.length : argv.indexOf("--")).includes("--no-color");
+        const color = host.globals?.color ?? colourOn(!noColor, format, io);
+        io.stderr(renderError(e, format !== "table", color));
+        return e.exitCode;
+    };
+    if (io.platform === "win32") {
+        return fail(new CliError("unsupported_platform", "poietic-tech does not run on Windows yet."));
+    }
+    host.builtins = builtins.map(([name]) => name);
+    try {
+        const program = buildProgram(io, host);
+        for (const [name, summary, make] of builtins)
+            await registerModule(host, program, name, make(host), summary);
+        addHelp(program, io);
+        await addModules(host, program, argv, builtins.map(([name]) => name));
+        await program.parseAsync(argv, { from: "user" });
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof CommanderError) {
+            if (error.exitCode === 0 || error.code === "commander.help")
+                return 0;
+            return fail(new CliError("bad_usage", error.message.replace(/^error: /, "")));
+        }
+        return fail(toCliError(error, io.signal));
+    }
+}

package/dist/module.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @poietic-tech/cli/module: the module contract, API version 1. The only part
+ * of @poietic-tech/cli a module may rely on; everything else is private.
+ */
+import type { Command } from "commander";
+import type { Caller } from "@poietic-tech/auth/node";
+import type { Column } from "./output.js";
+export type { Caller } from "@poietic-tech/auth/node";
+export type { Column } from "./output.js";
+export declare const MODULE_API = 1;
+/** The "poietic-tech" key of a module's package.json. */
+export interface ModuleManifest {
+    command: string;
+    entry: string;
+    api: number;
+    summary: string;
+}
+/** Results to stdout and messages to stderr, honouring --json, --format and -q. */
+export interface ModuleOutput {
+    item<T>(obj: T, columns?: Column<T>[]): void;
+    list<T>(rows: T[], opts: {
+        columns: Column<T>[];
+        id?: (row: T) => string;
+    }): void;
+    message(text: string): void;
+    warn(text: string): void;
+    secret(value: string, warning: string, extra?: Record<string, unknown>): void;
+}
+export interface ModuleContext {
+    readonly program: Command;
+    caller(): Promise<Caller>;
+    readonly output: ModuleOutput;
+    fail(code: string, message: string, opts?: {
+        status?: number;
+    }): never;
+    stepUp(): Promise<void>;
+    readonly server: string;
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly version: {
+        readonly host: string;
+        readonly api: readonly number[];
+    };
+}
+export interface PoieticTechModule {
+    readonly api: 1;
+    readonly setup: (ctx: ModuleContext) => void | Promise<void>;
+}
+export declare function defineModule(setup: PoieticTechModule["setup"]): PoieticTechModule;

package/dist/module.js

@@ -0,0 +1,4 @@
+export const MODULE_API = 1;
+export function defineModule(setup) {
+    return Object.freeze({ api: 1, setup });
+}

package/dist/modules/agents.d.ts

@@ -0,0 +1,48 @@
+import type { Builtin } from "../context.js";
+import { type Column, type ModuleContext } from "../module.js";
+/** The server's AGENT_PATH segment. */
+export declare const ID: RegExp;
+export interface AgentRow {
+    id: string;
+    name: string;
+    owner: string;
+    created_by: string | null;
+    builder: boolean;
+    delegator: boolean;
+    created_at: number;
+    level?: string;
+    act_as_allowed?: boolean;
+    live_tokens?: number;
+}
+export interface TokenRow {
+    id: string;
+    label: string | null;
+    created_at: number;
+    expires_at: number | null;
+    last_used_at: number | null;
+    state: string;
+    created_via?: string | null;
+    created_via_label?: string | null;
+}
+/**
+ * Calls the /agents API as the person (or the builder named by POIETIC_IDENTITY). Returns the JSON of a 2xx.
+ * `signal` (the run's Ctrl-C) aborts the request in flight.
+ * On `403 reauth_required` it steps up (`ctx.stepUp()`, which fails at once under --no-wait) and
+ * sends once more; a second `reauth_required` is the error. An aborted `signal` never resends.
+ */
+export declare function agentsCall(ctx: ModuleContext, method: string, path: string, body?: unknown, signal?: AbortSignal): Promise<any>;
+/** Only the person may change an agent: the builder view has no PATCH. Fails before any request. */
+export declare function personOnly(ctx: ModuleContext, what: string): Promise<void>;
+export declare function listAgents(ctx: ModuleContext, signal?: AbortSignal): Promise<AgentRow[]>;
+/** `ref` is a name (as the server resolves POIETIC_IDENTITY) or `id:<uuid>`. */
+export declare function resolveAgent(ctx: ModuleContext, ref: string, opts?: {
+    list?: boolean;
+    signal?: AbortSignal;
+}): Promise<{
+    id: string;
+    agent?: AgentRow;
+}>;
+export declare function levelOf(a: AgentRow): "none" | "builder" | "delegator";
+export declare function agentColumns(all: readonly AgentRow[]): Column<AgentRow>[];
+export declare const TOKEN_COLUMNS: Column<TokenRow>[];
+export declare const agentsBuiltin: Builtin;