@poietic-tech/cli 0.0.0-stage → 0.1.0

package/dist/modules/agents.js

@@ -0,0 +1,238 @@
+import { Argument, Option } from "commander";
+import { apiError, CliError } from "../errors.js";
+import { defineModule } from "../module.js";
+/** The server's AGENT_PATH segment. */
+export const ID = /^[0-9a-f-]{36}$/;
+const malformed = () => new CliError("server_error", "The auth server sent an answer this command cannot read.");
+/**
+ * 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 async function agentsCall(ctx, method, path, body, signal) {
+    const caller = await ctx.caller();
+    const send = () => caller.authFetch(path, {
+        method,
+        headers: { "content-type": "application/json" },
+        ...(method === "GET" || body === undefined ? {} : { body: JSON.stringify(body) }),
+        ...(signal ? { signal } : {}),
+    });
+    let res = await send();
+    if (res.status === 403) {
+        const err = await apiError(res, `${method} ${path}`);
+        if (err.code !== "reauth_required")
+            throw err;
+        await ctx.stepUp();
+        if (signal?.aborted)
+            throw new CliError("interrupted", "Interrupted.");
+        res = await send();
+    }
+    if (!res.ok)
+        throw await apiError(res, `${method} ${path}`);
+    try {
+        return await res.json();
+    }
+    catch {
+        throw malformed();
+    }
+}
+/** Only the person may change an agent: the builder view has no PATCH. Fails before any request. */
+export async function personOnly(ctx, what) {
+    if ((await ctx.caller()).actingAs !== "login") {
+        ctx.fail("not_allowed", `Only you can ${what}: unset POIETIC_IDENTITY and POIETIC_AGENT_TOKEN.`);
+    }
+}
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const agentOf = (res) => {
+    const a = res?.agent;
+    if (!isObject(a) || typeof a.id !== "string" || !ID.test(a.id) || typeof a.name !== "string")
+        throw malformed();
+    return a;
+};
+const asciiFold = (s) => s.replace(/[A-Z]/g, (c) => c.toLowerCase());
+/**
+ * A mirror of cleanName in packages/identity/text.ts, in the same order (collapse whitespace,
+ * strip controls and deceptive characters, collapse, trim). It is a copy, not an import, because
+ * the published CLI cannot depend on that package, so it can drift; keep the two in step.
+ */
+const CONTROL_CHARS = /[\u0000-\u001F\u007F]/g;
+const DECEPTIVE_CHARS = /[\u202A-\u202E\u2066-\u2069\u200B-\u200D\u2060\uFEFF]/g;
+const normalizeName = (s) => s.normalize("NFC").replace(/\s+/g, " ").replace(CONTROL_CHARS, "").replace(DECEPTIVE_CHARS, "").replace(/\s+/g, " ").trim();
+const fold = (s) => asciiFold(normalizeName(s));
+export async function listAgents(ctx, signal) {
+    const body = await agentsCall(ctx, "GET", "/agents", undefined, signal);
+    const agents = body?.agents;
+    if (!Array.isArray(agents) || agents.some((a) => a === null || typeof a !== "object" || typeof a.id !== "string" || !ID.test(a.id) || typeof a.name !== "string")) {
+        throw malformed();
+    }
+    return agents;
+}
+/** `ref` is a name (as the server resolves POIETIC_IDENTITY) or `id:<uuid>`. */
+export async function resolveAgent(ctx, ref, opts = {}) {
+    if (ref.startsWith("id:")) {
+        const id = ref.slice(3);
+        if (!ID.test(id))
+            throw new CliError("bad_usage", `"${ref}" is not an agent id.`);
+        if (!opts.list)
+            return { id };
+        const agent = (await listAgents(ctx, opts.signal)).find((a) => a.id === id);
+        if (!agent)
+            throw new CliError("no_such_agent", `No agent you can see has the id ${id}; see \`poietic-tech agents list\`.`);
+        return { id, agent };
+    }
+    const want = fold(ref);
+    const agent = (await listAgents(ctx, opts.signal)).find((a) => a.created_by === null && fold(a.name) === want);
+    if (!agent) {
+        throw new CliError("no_such_agent", `No agent of yours is named "${ref}". Agents a builder made are addressed as id:<uuid>; see \`poietic-tech agents list\`.`);
+    }
+    return { id: agent.id, agent };
+}
+export function levelOf(a) {
+    return a.delegator ? "delegator" : a.builder ? "builder" : "none";
+}
+const day = (t) => (typeof t === "number" ? new Date(t * 1000).toISOString().slice(0, 10) : "-");
+export function agentColumns(all) {
+    return [
+        ["NAME", (a) => a.name],
+        ["LEVEL", levelOf],
+        ["ACT-AS", (a) => (a.act_as_allowed === undefined ? "-" : a.act_as_allowed ? "on" : "off")],
+        ["CREATED BY", (a) => (a.created_by === null ? "-" : (all.find((x) => x.id === a.created_by)?.name ?? a.created_by))],
+        ["LIVE TOKENS", (a) => a.live_tokens ?? "-"],
+        ["CREATED", (a) => day(a.created_at)],
+    ];
+}
+export const TOKEN_COLUMNS = [
+    ["ID", (t) => t.id],
+    ["LABEL", (t) => t.label],
+    ["ORIGIN", (t) => (t.created_via ? `${t.created_via}${t.created_via_label ? ` (${t.created_via_label})` : ""}` : "-")],
+    ["EXPIRES", (t) => (t.expires_at === null || t.expires_at === undefined ? "never" : day(t.expires_at))],
+    ["LAST USED", (t) => (t.last_used_at === null || t.last_used_at === undefined ? "never" : day(t.last_used_at))],
+    ["STATE", (t) => t.state],
+];
+async function tokensOf(ctx, id, signal) {
+    const tokens = (await agentsCall(ctx, "GET", `/agents/${id}/tokens`, undefined, signal))?.tokens;
+    if (!Array.isArray(tokens))
+        throw malformed();
+    return tokens;
+}
+function agentsModule(host) {
+    return defineModule((ctx) => {
+        const format = () => host.globals?.format;
+        const { signal } = host.io;
+        const resolve = (ref, list = false) => resolveAgent(ctx, ref, { list, signal });
+        ctx.program
+            .command("list")
+            .description("List your agents")
+            .action(async () => {
+            const all = await listAgents(ctx, signal);
+            ctx.output.list(all, { columns: agentColumns(all), id: (a) => a.name });
+        });
+        ctx.program
+            .command("show")
+            .description("Show an agent and its tokens")
+            .argument("<agent>", "agent name or id:<uuid>")
+            .action(async (ref) => {
+            const { id, agent } = await resolve(ref, true);
+            const tokens = await tokensOf(ctx, id, signal);
+            const row = agent;
+            if (format() === "table") {
+                ctx.output.item(row);
+                host.output().text("");
+                ctx.output.list(tokens, { columns: TOKEN_COLUMNS });
+            }
+            else if (format() === "ids")
+                ctx.output.item(row);
+            else
+                ctx.output.item({ agent: row, tokens });
+        });
+        const tokens = ctx.program.command("tokens").description("Manage an agent's tokens");
+        tokens
+            .command("list")
+            .description("List an agent's tokens")
+            .argument("<agent>", "agent name or id:<uuid>")
+            .action(async (ref) => {
+            const { id } = await resolve(ref);
+            ctx.output.list(await tokensOf(ctx, id, signal), { columns: TOKEN_COLUMNS });
+        });
+        const call = (method, path, body) => agentsCall(ctx, method, path, body, signal);
+        const printAgent = (res) => {
+            const a = agentOf(res);
+            ctx.output.item(a, agentColumns([a]));
+        };
+        const patch = async (ref, what, body) => {
+            await personOnly(ctx, what);
+            const { id } = await resolve(ref);
+            printAgent(await call("PATCH", `/agents/${id}`, body));
+        };
+        ctx.program
+            .command("create")
+            .description("Create an agent")
+            .argument("<name>", "the new agent's name")
+            .action(async (name) => printAgent(await call("POST", "/agents", { name })));
+        ctx.program
+            .command("rename")
+            .description("Rename an agent")
+            .argument("<agent>", "agent name or id:<uuid>")
+            .argument("<new>", "the new name")
+            .action((ref, name) => patch(ref, "rename an agent", { name }));
+        ctx.program
+            .command("set")
+            .description("Set an agent's level")
+            .argument("<agent>", "agent name or id:<uuid>")
+            .addOption(new Option("--level <level>", "what the agent may do").choices(["none", "builder", "delegator"]).makeOptionMandatory())
+            .action((ref, opts) => patch(ref, "change an agent's level", { permissions: opts.level }));
+        ctx.program
+            .command("act-as")
+            .description("Allow or stop acting as an agent")
+            .argument("<agent>", "agent name or id:<uuid>")
+            .addArgument(new Argument("<state>", "on or off").choices(["on", "off"]))
+            .action((ref, state) => patch(ref, "change whether an agent can be acted as", { act_as_allowed: state === "on" }));
+        tokens
+            .command("create")
+            .description("Create a token for an agent; prints the secret once")
+            .argument("<agent>", "agent name or id:<uuid>")
+            .option("--label <label>", "a label for the token")
+            .addOption(new Option("--expires <when>", "when the token expires").choices(["never", "90d"]).default("never"))
+            .action(async (ref, opts) => {
+            const person = (await ctx.caller()).actingAs === "login";
+            const { id } = await resolve(ref);
+            const ninety = opts.expires === "90d";
+            const body = {
+                ...(opts.label !== undefined ? { label: opts.label } : {}),
+                ...(ninety ? (person ? { expires: "90d" } : { expires_in: 7_776_000 }) : {}),
+            };
+            const token = (await call("POST", `/agents/${id}/tokens`, body))?.token;
+            if (!isObject(token) || typeof token.secret !== "string" || typeof token.id !== "string")
+                throw malformed();
+            ctx.output.secret(token.secret, "Copy this token now. It won't be shown again.", { id: token.id });
+        });
+        tokens
+            .command("revoke")
+            .description("Revoke one of an agent's tokens")
+            .argument("<agent>", "agent name or id:<uuid>")
+            .argument("<token-id>", "the token's id, from `agents tokens list`")
+            .action(async (ref, tid) => {
+            if (!ID.test(tid))
+                ctx.fail("bad_usage", `"${tid}" is not a token id.`);
+            const { id } = await resolve(ref);
+            await call("DELETE", `/agents/${id}/tokens/${tid}`);
+            ctx.output.item({ revoked: true });
+        });
+        ctx.program
+            .command("delete")
+            .description("Delete an agent")
+            .argument("<agent>", "agent name or id:<uuid>")
+            .requiredOption("--confirm <name>", "the agent's current name, exactly")
+            .action(async (ref, opts) => {
+            const { id, agent } = await resolve(ref, true);
+            if (opts.confirm !== agent.name)
+                ctx.fail("bad_usage", `--confirm must be the agent's current name, "${agent.name}".`);
+            const res = await call("DELETE", `/agents/${id}`, { confirm: opts.confirm });
+            if (typeof res?.deleted !== "number")
+                throw malformed();
+            ctx.output.item({ deleted: res.deleted });
+        });
+    });
+}
+export const agentsBuiltin = ["agents", "Manage your agents", agentsModule];

package/dist/modules/auth.d.ts

@@ -0,0 +1,4 @@
+import type { Builtin } from "../context.js";
+/** Only a link the person could safely click is handed to the browser opener. */
+export declare function safeToOpen(link: string): boolean;
+export declare const authBuiltins: Builtin[];

package/dist/modules/auth.js

@@ -0,0 +1,129 @@
+import { deviceLogin, logout, readLogin, serverOrigin } from "@poietic-tech/auth/node";
+import { inline } from "../text.js";
+import { defineModule } from "../module.js";
+/** Only a link the person could safely click is handed to the browser opener. */
+export function safeToOpen(link) {
+    let url;
+    try {
+        url = new URL(link);
+    }
+    catch {
+        return false;
+    }
+    if (url.protocol === "https:")
+        return true;
+    return url.protocol === "http:" && (url.hostname === "localhost" || url.hostname === "127.0.0.1");
+}
+const signedIn = (user, server) => `Signed in as ${inline(user.name)}${user.email ? ` (${inline(user.email)})` : ""} at ${server}`;
+function isTable(host) {
+    return host.globals?.format === "table";
+}
+/** Results for the table format go out as the text given; every other format gets the object. */
+function result(host, ctx, text, obj, id) {
+    if (isTable(host))
+        host.output().text(text);
+    else if (host.globals?.format === "ids") {
+        if (id !== undefined)
+            host.io.stdout(`${inline(id)}\n`);
+    }
+    else
+        ctx.output.item(obj);
+}
+function login(host) {
+    return defineModule((ctx) => {
+        const { io } = host;
+        ctx.program
+            .option("--label <text>", "name this terminal's login", io.hostname)
+            .option("--no-browser", "do not open the browser")
+            .action(async (opts) => {
+            const server = serverOrigin({ server: host.globals?.server, env: io.env });
+            const { user } = await deviceLogin({
+                server,
+                env: io.env,
+                now: io.now,
+                sleep: io.sleep,
+                signal: io.signal,
+                label: opts.label,
+                onNotice: (m) => ctx.output.message(m),
+                onCode: (p) => {
+                    ctx.output.message(`Open ${p.verificationUri} and enter ${p.userCode}`);
+                    if (io.stderrIsTTY && opts.browser && safeToOpen(p.verificationUri))
+                        io.openBrowser(p.verificationUri);
+                },
+            });
+            const line = signedIn(user, server);
+            // Whatever the format, the person is told which account the code approved.
+            ctx.output.message(line);
+            result(host, ctx, line, { user, server }, user.id);
+        });
+    });
+}
+function logoutModule(host) {
+    return defineModule((ctx) => {
+        const { io } = host;
+        ctx.program.action(async () => {
+            const opts = { server: host.globals?.server, env: io.env };
+            const origin = serverOrigin(opts);
+            if ((await readLogin(opts)) === null) {
+                ctx.output.message("Not signed in.");
+                if (!isTable(host))
+                    result(host, ctx, "", { revokedOnServer: false });
+                return;
+            }
+            const { revokedOnServer } = await logout({
+                ...opts,
+                now: io.now,
+                sleep: io.sleep,
+                onNotice: (m) => ctx.output.message(m),
+            });
+            if (revokedOnServer) {
+                result(host, ctx, "Signed out.", { revokedOnServer });
+            }
+            else {
+                ctx.output.message(`Signed out here, but the server could not be reached, so the session is still live. Revoke it at ${origin}/account.`);
+                if (!isTable(host))
+                    result(host, ctx, "", { revokedOnServer });
+            }
+        });
+    });
+}
+function whoami(host) {
+    return defineModule((ctx) => {
+        const { io } = host;
+        ctx.program.option("--offline", "read the saved login only; make no request").action(async (opts) => {
+            const base = { server: host.globals?.server, env: io.env };
+            if (opts.offline) {
+                const login = await readLogin(base);
+                if (login === null)
+                    return ctx.fail("not_logged_in", "Not signed in. Run `poietic-tech login`.");
+                const text = signedIn(login.user, login.server) + (login.label !== null ? `\nTerminal: ${inline(login.label)}` : "");
+                result(host, ctx, text, { offline: true, user: login.user, server: login.server, label: login.label }, login.user.id);
+                return;
+            }
+            const caller = await ctx.caller();
+            const identity = await caller.identity();
+            const label = caller.actingAs === "agent-token" ? null : ((await readLogin(base))?.label ?? null);
+            const server = ctx.server;
+            const obj = {
+                identity: { kind: identity.kind, id: identity.id, name: identity.name, owner: identity.owner },
+                actingAs: caller.actingAs,
+                server,
+                label,
+                warnings: [...caller.warnings],
+            };
+            const who = inline(`${identity.kind}, ${identity.id}${identity.owner ? `, owned by ${identity.owner}` : ""}`);
+            const lines = [
+                ["Acting as", `${inline(identity.name)} (${who})`],
+                ["Via", caller.actingAs],
+                ["Server", server],
+                ...(label !== null ? [["Terminal", inline(label)]] : []),
+            ];
+            result(host, ctx, lines.map(([k, v]) => `${k}: ${v}`).join("\n"), obj, identity.id);
+        });
+    });
+}
+export const authBuiltins = [
+    ["login", "Sign this terminal in", login],
+    ["logout", "Sign this terminal out", logoutModule],
+    ["whoami", "Show who commands act as", whoami],
+];

package/dist/modules/modules.d.ts

@@ -0,0 +1,2 @@
+import type { Builtin } from "../context.js";
+export declare const modulesBuiltin: Builtin;

package/dist/modules/modules.js

@@ -0,0 +1,75 @@
+import { allow, disallow, readAllowed } from "../allowlist.js";
+import { clean, discover, discoveryRoots, stateText } from "../discovery.js";
+import { defineModule } from "../module.js";
+import { inline } from "../text.js";
+const row = (d) => ({
+    package: clean(d.name),
+    version: clean(d.version),
+    command: clean(d.command ?? ""),
+    summary: clean(d.summary),
+    source: d.source,
+    state: clean(stateText(d.state)),
+});
+const COLUMNS = [
+    ["PACKAGE", (r) => r.package],
+    ["VERSION", (r) => r.version],
+    ["COMMAND", (r) => r.command],
+    ["SUMMARY", (r) => r.summary],
+    ["SOURCE", (r) => r.source],
+    ["STATE", (r) => r.state],
+];
+function modulesModule(host) {
+    return defineModule((ctx) => {
+        const { io } = host;
+        const format = () => host.globals?.format;
+        /** Table prints the sentence; ids prints the package; json and ndjson print the object. */
+        const report = (text, obj) => {
+            if (format() === "table") {
+                if (text !== "")
+                    host.output().text(text);
+            }
+            else if (format() === "ids")
+                io.stdout(`${inline(obj.package)}\n`);
+            else
+                ctx.output.item(obj);
+        };
+        ctx.program
+            .command("list")
+            .description("List the modules found and whether they run")
+            .action(async () => {
+            const found = await discover(discoveryRoots(io.hostDir, io.execPath), await readAllowed(io.env), {
+                builtins: host.builtins,
+                unscoped: true,
+            });
+            ctx.output.list(found.map(row), { columns: COLUMNS, id: (r) => r.package });
+        });
+        ctx.program
+            .command("allow")
+            .description("Allow a package outside @poietic-tech to run")
+            .argument("<package>", "npm package name")
+            .action(async (name) => {
+            const result = await allow(io.env, name);
+            if (result === "scoped")
+                ctx.output.message("@poietic-tech packages load without being allowed.");
+            const text = result === "added"
+                ? `Allowed ${name}. Its commands now run with your login.`
+                : result === "already"
+                    ? `${name} is already allowed.`
+                    : "";
+            report(text, { package: name, allowed: true, changed: result === "added" });
+        });
+        ctx.program
+            .command("disallow")
+            .description("Stop allowing a package")
+            .argument("<package>", "npm package name")
+            .action(async (name) => {
+            const result = await disallow(io.env, name);
+            report(result === "removed" ? `Removed ${name}.` : `${name} was not allowed.`, {
+                package: name,
+                allowed: false,
+                changed: result === "removed",
+            });
+        });
+    });
+}
+export const modulesBuiltin = ["modules", "List and allow modules", modulesModule];

package/dist/output.d.ts

@@ -0,0 +1,36 @@
+import type { CliIO } from "./io.js";
+export type Format = "table" | "json" | "ndjson" | "ids";
+export type Column<T> = [header: string, get: (row: T) => unknown];
+export interface Globals {
+    format: Format;
+    color: boolean;
+    wait: boolean;
+    server?: string;
+}
+export declare function resolveGlobals(opts: {
+    json?: boolean;
+    format?: string;
+    quiet?: boolean;
+    color: boolean;
+    wait: boolean;
+    server?: string;
+}, io: CliIO): Globals;
+export declare function colourOn(flag: boolean, format: Format, io: CliIO): boolean;
+/** The format `resolveGlobals` would pick from raw argv; never throws, an invalid value falls through. */
+export declare function prescanFormat(argv: string[], io: CliIO): Format;
+export declare class Output {
+    private readonly io;
+    private readonly g;
+    constructor(io: CliIO, g: Globals);
+    item<T>(obj: T, columns?: Column<T>[]): void;
+    list<T>(rows: T[], opts: {
+        columns: Column<T>[];
+        id?: (row: T) => string;
+    }): void;
+    /** Lines of text for the table format, cleaned like every other terminal text. */
+    text(text: string): void;
+    message(text: string): void;
+    warn(text: string): void;
+    secret(value: string, warning: string, extra?: Record<string, unknown>): void;
+    private err;
+}

package/dist/output.js

@@ -0,0 +1,152 @@
+import { CliError, redact } from "./errors.js";
+import { inline, sanitize } from "./text.js";
+const FORMATS = ["table", "json", "ndjson", "ids"];
+const isFormat = (v) => typeof v === "string" && FORMATS.includes(v);
+function fallbackFormat(io, strict) {
+    const env = io.env.POIETIC_TECH_FORMAT;
+    if (env !== undefined && env !== "") {
+        if (isFormat(env))
+            return env;
+        if (strict)
+            throw new CliError("bad_usage", `POIETIC_TECH_FORMAT must be one of ${FORMATS.join(", ")}.`);
+    }
+    return io.stdoutIsTTY ? "table" : "json";
+}
+export function resolveGlobals(opts, io) {
+    const named = [];
+    if (opts.json)
+        named.push("json");
+    if (opts.format !== undefined) {
+        if (!isFormat(opts.format))
+            throw new CliError("bad_usage", `--format must be one of ${FORMATS.join(", ")}.`);
+        named.push(opts.format);
+    }
+    if (opts.quiet)
+        named.push("ids");
+    if (new Set(named).size > 1) {
+        throw new CliError("bad_usage", "--json, --format and -q name different output formats; use only one.");
+    }
+    const format = named[0] ?? fallbackFormat(io, true);
+    return {
+        format,
+        color: colourOn(opts.color, format, io),
+        wait: opts.wait,
+        ...(opts.server !== undefined ? { server: opts.server } : {}),
+    };
+}
+export function colourOn(flag, format, io) {
+    return flag && io.stderrIsTTY && !io.env.NO_COLOR && format === "table";
+}
+/** The format `resolveGlobals` would pick from raw argv; never throws, an invalid value falls through. */
+export function prescanFormat(argv, io) {
+    const named = new Set();
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--")
+            break;
+        if (a === "--json")
+            named.add("json");
+        else if (a === "-q" || a === "--quiet")
+            named.add("ids");
+        else if (a === "--format") {
+            const v = argv[i + 1];
+            if (isFormat(v))
+                named.add(v);
+            i++;
+        }
+        else if (a.startsWith("--format=")) {
+            const v = a.slice("--format=".length);
+            if (isFormat(v))
+                named.add(v);
+        }
+    }
+    if (named.size === 1)
+        return [...named][0];
+    return fallbackFormat(io, false);
+}
+function cell(v) {
+    if (v === null || v === undefined || v === "")
+        return "-";
+    return inline(typeof v === "object" ? JSON.stringify(v) : String(v));
+}
+const isScalar = (v) => v === null || (typeof v !== "object" && typeof v !== "function" && v !== undefined);
+/** The id a row stands for in the ids format: its id, else its name, else nothing. */
+function idOf(r) {
+    const o = r;
+    const v = o.id ?? o.name;
+    return v === undefined || v === null ? null : String(v);
+}
+/** One ids line: cleaned like every terminal value, so a newline in an id cannot make two. */
+const idLine = (v) => `${inline(String(v))}\n`;
+export class Output {
+    io;
+    g;
+    constructor(io, g) {
+        this.io = io;
+        this.g = g;
+    }
+    item(obj, columns) {
+        switch (this.g.format) {
+            case "json":
+                return this.io.stdout(`${JSON.stringify(obj, null, 2)}\n`);
+            case "ndjson":
+                return this.io.stdout(`${JSON.stringify(obj)}\n`);
+            case "ids": {
+                const id = idOf(obj);
+                return id === null ? undefined : this.io.stdout(idLine(id));
+            }
+            case "table": {
+                const pairs = columns
+                    ? columns.map(([h, get]) => [h, cell(get(obj))])
+                    : Object.entries(obj)
+                        .filter(([, v]) => isScalar(v))
+                        .map(([k, v]) => [inline(k), cell(v)]);
+                this.io.stdout(pairs.map(([k, v]) => `${k}: ${v}\n`).join(""));
+            }
+        }
+    }
+    list(rows, opts) {
+        switch (this.g.format) {
+            case "json":
+                return this.io.stdout(`${JSON.stringify({ data: rows }, null, 2)}\n`);
+            case "ndjson":
+                return this.io.stdout(rows.map((r) => `${JSON.stringify(r)}\n`).join(""));
+            case "ids":
+                return this.io.stdout(rows.map((r) => idLine((opts.id ? opts.id(r) : idOf(r)) ?? "")).join(""));
+            case "table": {
+                if (rows.length === 0)
+                    return this.err("No results.\n");
+                const grid = [opts.columns.map(([h]) => h), ...rows.map((r) => opts.columns.map(([, get]) => cell(get(r))))];
+                const widths = opts.columns.map((_, c) => Math.max(...grid.map((line) => line[c].length)));
+                this.io.stdout(grid
+                    .map((line) => line.map((v, c) => (c === line.length - 1 ? v : v.padEnd(widths[c]))).join("  ") + "\n")
+                    .join(""));
+            }
+        }
+    }
+    /** Lines of text for the table format, cleaned like every other terminal text. */
+    text(text) {
+        this.io.stdout(`${sanitize(text)}\n`);
+    }
+    message(text) {
+        this.err(`${sanitize(text)}\n`);
+    }
+    warn(text) {
+        const line = `warning: ${sanitize(text)}`;
+        this.err(`${this.g.color ? `\x1b[33m${line}\x1b[0m` : line}\n`);
+    }
+    secret(value, warning, extra = {}) {
+        const { format } = this.g;
+        // The secret is spread last, so `extra` can never replace it.
+        if (format === "json")
+            this.io.stdout(`${JSON.stringify({ ...extra, secret: value }, null, 2)}\n`);
+        else if (format === "ndjson")
+            this.io.stdout(`${JSON.stringify({ ...extra, secret: value })}\n`);
+        else
+            this.io.stdout(idLine(value));
+        this.message(warning);
+    }
+    err(text) {
+        this.io.stderr(redact(text));
+    }
+}

package/dist/text.d.ts

@@ -0,0 +1,6 @@
+/** One line of text safe to print: cut at the first newline, controls and hidden characters removed. */
+export declare function clean(text: string): string;
+/** A value for one line: newlines become spaces, then controls are removed. */
+export declare function inline(text: string): string;
+/** Text of several lines: newlines stay, every other control and hidden character goes. */
+export declare function sanitize(text: string): string;

package/dist/text.js

@@ -0,0 +1,15 @@
+/** The one place that decides what may reach a terminal: controls, bidi and zero-width characters never do. */
+const CONTROL = /[\u0000-\u001f\u007f-\u009f\u200b-\u200d\u2028\u2029\u202a-\u202e\u2066-\u2069\ufeff]/g;
+const CONTROL_KEEP_NEWLINE = /[\u0000-\u0009\u000b-\u001f\u007f-\u009f\u200b-\u200d\u2028\u2029\u202a-\u202e\u2066-\u2069\ufeff]/g;
+/** One line of text safe to print: cut at the first newline, controls and hidden characters removed. */
+export function clean(text) {
+    return text.split("\n", 1)[0].replace(CONTROL, "");
+}
+/** A value for one line: newlines become spaces, then controls are removed. */
+export function inline(text) {
+    return text.replace(/\r?\n/g, " ").replace(CONTROL, "");
+}
+/** Text of several lines: newlines stay, every other control and hidden character goes. */
+export function sanitize(text) {
+    return text.replace(CONTROL_KEEP_NEWLINE, "");
+}