@poietic-tech/cli 0.0.1-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Benjamin Small
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,150 @@
+# @poietic-tech/cli
+
+The `poietic-tech` command: sign in to [auth.poietic.tech](https://auth.poietic.tech),
+manage your agents, and run the commands of any installed poietic module. It is built for
+people and for AI agents: tables for people, JSON for machines, stable exit codes, and it
+never prompts or reads stdin.
+
+Node 20 or later, macOS or Linux (it exits 8 on Windows).
+
+```sh
+npm i -g @poietic-tech/cli
+poietic-tech login
+```
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `login [--label <text>] [--no-browser]` | Sign in through the browser. Prints `Open <link> and enter <code>`, then the account it signed in as |
+| `logout` | End this terminal's login |
+| `whoami [--offline]` | Who commands act as and why; `--offline` reads the saved login and makes no request |
+| `agents list` | List your agents |
+| `agents show <agent>` | Show an agent and its tokens |
+| `agents create <name>` | Create an agent |
+| `agents rename <agent> <new>` | Rename an agent |
+| `agents set <agent> --level none\|builder\|delegator` | Set what an agent may do |
+| `agents act-as <agent> on\|off` | Allow or stop acting as an agent |
+| `agents tokens list <agent>` | List an agent's tokens |
+| `agents tokens create <agent> [--label <label>] [--expires never\|90d]` | Create a token; the secret is printed once |
+| `agents tokens revoke <agent> <token-id>` | Revoke a token |
+| `agents delete <agent> --confirm <name>` | Delete an agent; `--confirm` must be its exact current name |
+| `modules list` | Every module found and whether it runs |
+| `modules allow <package>` / `modules disallow <package>` | Allow or stop allowing a package outside `@poietic-tech` |
+| `help [topic]` | Show help; `help exit-codes` prints the exit codes |
+
+An `<agent>` is a name or `id:<uuid>`. A name matches only agents you made yourself;
+address an agent a builder made as `id:<uuid>`. When the server asks for a recent sign-in (for example to raise a level, turn act-as on,
+create a token or delete an agent), the command asks you to confirm in the browser and
+retries once; with `--no-wait` it exits 6 instead.
+
+Global options, on every command:
+
+| Option | Meaning |
+| --- | --- |
+| `--json` | Same as `--format json` |
+| `--format table\|json\|ndjson\|ids` | Output format |
+| `-q`, `--quiet` | Print only what was asked for |
+| `--server <origin>` | The auth server to use. Only `https://auth.poietic.tech` and `http://localhost` or `127.0.0.1` are accepted; any other origin is refused (`untrusted_server`, exit 8) unless `POIETIC_ALLOW_CUSTOM_AUTH=1` |
+| `--no-wait` | Fail with exit 6 instead of waiting for a step-up |
+| `--no-color` | Never colour output |
+| `-V`, `--version` | Print the version |
+| `-h`, `--help` | Show help |
+
+## Output and environment
+
+Results go to stdout; messages, links, warnings and errors go to stderr. The format is
+`table` when stdout is a terminal and `json` otherwise; `--format` or `--json` overrides
+it, and so does `POIETIC_TECH_FORMAT`, with the flag winning over the variable. In a
+machine format an error is one JSON object on stderr:
+`{ "error": "<code>", "message": "…", "status"?: number }`. A command named without a
+subcommand (`poietic-tech`, `poietic-tech agents`) prints its help on stdout and exits 0.
+
+Ctrl-C stops the request or browser wait in progress and exits 130. A module command that
+does not stop on its own exits 130 at a second Ctrl-C.
+
+| Variable | Effect |
+| --- | --- |
+| `POIETIC_TECH_FORMAT` | Default output format (`table`, `json`, `ndjson`, `ids`) |
+| `POIETIC_AUTH_URL` | The auth server, when `--server` is not given; the same origin rule applies |
+| `POIETIC_ALLOW_CUSTOM_AUTH` | Set to `1` to allow an auth origin other than `auth.poietic.tech` or localhost |
+| `POIETIC_IDENTITY` | Act as this agent instead of as yourself. Ignored, with a warning, when `POIETIC_AGENT_TOKEN` is set |
+| `POIETIC_AGENT_TOKEN` | Authenticate as an agent with its `pat_` token instead of a saved login |
+| `NO_COLOR` | Disable colour |
+
+`POIETIC_CREDENTIALS_DIR` and `XDG_CONFIG_HOME` move the folder below.
+
+Exit codes: run `poietic-tech help exit-codes`.
+
+## Files
+
+Everything lives in `~/.config/poietic-tech/` (a folder of mode 0700, files of mode 0600):
+
+- `login.json` and `tokens.json`: the saved login and cached tokens, managed by
+  `@poietic-tech/auth/node`. The command never reads or writes them itself.
+- `modules.json`: the packages outside `@poietic-tech` that you have allowed
+  (`{ "version": 1, "allowed": ["pkg-name", …] }`). It holds no secret, but it decides what
+  code runs with your login, so it is protected the same way.
+
+## Writing a module
+
+A module is an npm package that adds a subcommand. Install it next to the command or
+globally, and `poietic-tech` finds it at startup by reading its `package.json`; nothing is
+imported until its command is used (`poietic-tech --help` lists it from its `summary`).
+
+```json
+{
+  "name": "@poietic-tech/issues",
+  "peerDependencies": { "@poietic-tech/cli": "^0.1.0" },
+  "poietic-tech": { "command": "issues", "entry": "./dist/poietic-tech.js", "api": 1, "summary": "Issue tracker" }
+}
+```
+
+- `command` matches `^[a-z][a-z0-9-]{0,31}$` and must not be a built-in (`login`, `logout`,
+  `whoami`, `agents`, `modules`, `help`, or the help topic `exit-codes`). Two modules claiming
+  one command are both refused.
+- `entry` is a path inside the package; one that escapes it, or that cannot be read, is refused.
+- `api` is the contract version the module was written against. This host supports `1`.
+- `summary` is one line for `--help`.
+- The package's `name` must equal its folder name in `node_modules`.
+
+The entry's default export is the result of `defineModule`, imported from the only part of
+this package a module may rely on, `@poietic-tech/cli/module`:
+
+```ts
+import { defineModule } from "@poietic-tech/cli/module";
+
+export default defineModule((ctx) => {
+  ctx.program.command("list").description("List issues").action(async () => {
+    const caller = await ctx.caller();
+    const res = await caller.fetch("https://issues.poietic.tech/api/issues");
+    const rows = (await res.json()) as { key: string; title: string }[];
+    ctx.output.list(rows, { columns: [["KEY", (r) => r.key], ["TITLE", (r) => r.title]] });
+  });
+});
+```
+
+A module that throws while loading fails only its own command (`module_failed`, exit 1).
+
+`ModuleContext`:
+
+| Member | What it is |
+| --- | --- |
+| `program` | The module's own commander `Command`, already named and attached; add subcommands to it |
+| `caller()` | Lazily resolves the shared `Caller`; cached for the run, so commands that never call it never read the credential file |
+| `output` | `item(obj, columns?)`, `list(rows, { columns, id? })` (`id` gives the value `--format ids` prints per row), `message(text)` (stderr), `warn(text)` (stderr), `secret(value, warning, extra?)` (stdout once, the warning on stderr; `extra` fields join the JSON form), honouring `--json`, `--format` and `-q` |
+| `fail(code, message, opts?)` | Throws a `CliError` the host renders and maps to an exit code. A code in the exit-code table uses its row; an unknown code maps by `opts.status` (400, 409, 422 to 2; 401 to 3; 403 to 5; 404 to 4; 0, 429 and 5xx to 8), else exits 1 |
+| `stepUp()` | Runs the browser confirmation, honouring `--no-wait` |
+| `server` | The normalised auth origin in use |
+| `env` | The environment the host was given (read-only) |
+| `version` | The host's version and supported API versions |
+
+### What may load
+
+Packages in the `@poietic-tech` scope load automatically. Any other package loads only
+after `poietic-tech modules allow <package>`, because a module runs in the same process as
+your login. `modules list` shows each module and why it does or does not run.
+
+## License
+
+MIT

package/dist/allowlist.d.ts

@@ -0,0 +1,13 @@
+type Env = Readonly<Record<string, string | undefined>>;
+/** An npm package name, optionally scoped. It cannot start with "." or name a parent folder. */
+export declare const PACKAGE_NAME: RegExp;
+/** Where the allow file lives: `<credentials folder>/modules.json`. */
+export declare function allowFilePath(env: Env): string;
+/**
+ * The packages outside @poietic-tech whose modules may run. Every entry must be
+ * a package name, since each one becomes a folder path under a root.
+ */
+export declare function readAllowed(env: Env): Promise<string[]>;
+export declare function allow(env: Env, name: string): Promise<"added" | "already" | "scoped">;
+export declare function disallow(env: Env, name: string): Promise<"removed" | "absent">;
+export {};

package/dist/allowlist.js

@@ -0,0 +1,50 @@
+import { join } from "node:path";
+import { CredentialFileError, credentialsDir, readConfigFile, writeConfigFile } from "@poietic-tech/auth/node";
+import { CliError } from "./errors.js";
+/** An npm package name, optionally scoped. It cannot start with "." or name a parent folder. */
+export const PACKAGE_NAME = /^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/;
+const SCOPE = "@poietic-tech/";
+/** Where the allow file lives: `<credentials folder>/modules.json`. */
+export function allowFilePath(env) {
+    return join(credentialsDir(env), "modules.json");
+}
+function checkName(name) {
+    if (typeof name !== "string" || !PACKAGE_NAME.test(name)) {
+        throw new CliError("bad_usage", `${JSON.stringify(name)} is not a package name.`);
+    }
+}
+/**
+ * The packages outside @poietic-tech whose modules may run. Every entry must be
+ * a package name, since each one becomes a folder path under a root.
+ */
+export async function readAllowed(env) {
+    const data = await readConfigFile("modules", { env });
+    if (data === null)
+        return [];
+    const allowed = data.allowed;
+    if (!Array.isArray(allowed) || !allowed.every((n) => typeof n === "string" && PACKAGE_NAME.test(n))) {
+        throw new CredentialFileError(`${allowFilePath(env)} is not a modules file this tool understands. Delete it and allow the modules again.`);
+    }
+    return [...new Set(allowed)].sort();
+}
+async function save(env, allowed) {
+    await writeConfigFile("modules", { allowed: [...new Set(allowed)].sort() }, { env });
+}
+export async function allow(env, name) {
+    checkName(name);
+    if (name.startsWith(SCOPE))
+        return "scoped";
+    const allowed = await readAllowed(env);
+    if (allowed.includes(name))
+        return "already";
+    await save(env, [...allowed, name]);
+    return "added";
+}
+export async function disallow(env, name) {
+    checkName(name);
+    const allowed = await readAllowed(env);
+    if (!allowed.includes(name))
+        return "absent";
+    await save(env, allowed.filter((n) => n !== name));
+    return "removed";
+}

package/dist/bin.d.ts

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

package/dist/bin.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/// <reference types="node" />
+import { onInterrupt } from "./interrupt.js";
+import { processIO } from "./io.js";
+import { run } from "./main.js";
+const controller = new AbortController();
+onInterrupt(process, controller, (code) => process.exit(code));
+process.exitCode = await run(process.argv.slice(2), processIO(controller.signal));

package/dist/context.d.ts

@@ -0,0 +1,20 @@
+import type { Command } from "commander";
+import { type Caller } from "@poietic-tech/auth/node";
+import type { CliIO } from "./io.js";
+import { type ModuleContext, type PoieticTechModule } from "./module.js";
+import { Output, type Globals } from "./output.js";
+export declare const VERSION = "0.1.0";
+/** What the host holds for one run. Built-in modules are factories over it. */
+export interface Host {
+    readonly io: CliIO;
+    /** Set by the preAction hook, after parse. */
+    globals: Globals | null;
+    output(): Output;
+    caller(): Promise<Caller>;
+    /** The built-in command names of this run, set by `run`. */
+    builtins: readonly string[];
+}
+export type Builtin = [name: string, summary: string, make: (host: Host) => PoieticTechModule];
+export declare function createHost(io: CliIO): Host;
+/** The context a module's setup receives. Every member is read at call time: globals exist only after parse. */
+export declare function createContext(host: Host, program: Command): ModuleContext;

package/dist/context.js

@@ -0,0 +1,80 @@
+import { resolveCaller, serverOrigin, stepUp } from "@poietic-tech/auth/node";
+import { CliError } from "./errors.js";
+import { MODULE_API } from "./module.js";
+import { Output } from "./output.js";
+export const VERSION = "0.1.0";
+export function createHost(io) {
+    let output = null;
+    let caller = null;
+    const host = {
+        io,
+        globals: null,
+        builtins: [],
+        output() {
+            if (!host.globals)
+                throw new CliError("internal", "Output was used before the options were read.");
+            return (output ??= new Output(io, host.globals));
+        },
+        /** Resolved once per run; its warnings (POIETIC_IDENTITY ignored, say) are printed then, once, for every command. */
+        caller() {
+            return (caller ??= resolveCaller({
+                server: globals(host).server,
+                env: io.env,
+                now: io.now,
+                sleep: io.sleep,
+                onNotice: (m) => host.output().message(m),
+            }).then((c) => {
+                for (const w of c.warnings)
+                    host.output().warn(w);
+                return c;
+            }));
+        },
+    };
+    return host;
+}
+function globals(host) {
+    if (!host.globals)
+        throw new CliError("internal", "The options were read before parse.");
+    return host.globals;
+}
+/** The context a module's setup receives. Every member is read at call time: globals exist only after parse. */
+export function createContext(host, program) {
+    const { io } = host;
+    const output = Object.freeze({
+        item: (obj, columns) => host.output().item(obj, columns),
+        list: (rows, opts) => host.output().list(rows, opts),
+        message: (text) => host.output().message(text),
+        warn: (text) => host.output().warn(text),
+        secret: (value, warning, extra) => host.output().secret(value, warning, extra),
+    });
+    const env = Object.freeze({ ...io.env });
+    const version = Object.freeze({ host: VERSION, api: Object.freeze([MODULE_API]) });
+    return Object.freeze({
+        program,
+        caller: () => host.caller(),
+        output,
+        fail(code, message, opts) {
+            throw new CliError(code, message, opts);
+        },
+        async stepUp() {
+            const g = globals(host);
+            if (!g.wait) {
+                throw new CliError("reauth_required", "This needs a recent sign-in. Run the same command without --no-wait to confirm in the browser.");
+            }
+            await stepUp({
+                server: g.server,
+                env: io.env,
+                now: io.now,
+                sleep: io.sleep,
+                signal: io.signal,
+                onNotice: (m) => host.output().message(m),
+                onCode: (p) => host.output().message(`Confirm it's you: open ${p.verificationUri} and enter ${p.userCode}`),
+            });
+        },
+        get server() {
+            return serverOrigin({ server: globals(host).server, env: io.env });
+        },
+        env,
+        version,
+    });
+}

package/dist/discovery.d.ts

@@ -0,0 +1,41 @@
+import { clean } from "./text.js";
+import { type PoieticTechModule } from "./module.js";
+/**
+ * Finding modules reads package.json files only; nothing is imported until its
+ * command runs. This decides what code runs in-process with the person's login.
+ */
+export type ModuleState = {
+    kind: "available";
+} | {
+    kind: "refused";
+    reason: string;
+} | {
+    kind: "needs";
+    version: string | null;
+} | {
+    kind: "not-allowed";
+};
+export interface Discovered {
+    name: string;
+    version: string;
+    command: string | null;
+    summary: string;
+    source: "local" | "global";
+    dir: string;
+    entry: string | null;
+    state: ModuleState;
+}
+export interface Roots {
+    local: string | null;
+    global: string;
+}
+/** The node_modules the host was loaded from, and the global one. */
+export declare function discoveryRoots(hostDir: string, execPath: string): Roots;
+export { clean };
+export declare function stateText(s: ModuleState): string;
+export declare function discover(roots: Roots, allowed: readonly string[], opts: {
+    builtins: readonly string[];
+    unscoped?: boolean;
+}): Promise<Discovered[]>;
+/** Import an available module's entry; any failure is module_failed, naming only the package. */
+export declare function importModule(d: Discovered): Promise<PoieticTechModule>;

package/dist/discovery.js

@@ -0,0 +1,239 @@
+import { clean } from "./text.js";
+import { readdir, readFile, realpath } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+import { PACKAGE_NAME } from "./allowlist.js";
+import { CliError } from "./errors.js";
+import { MODULE_API } from "./module.js";
+const SCOPE = "@poietic-tech";
+const HOST = "@poietic-tech/cli";
+const COMMAND = /^[a-z][a-z0-9-]{0,31}$/;
+const SUPPORTED_API = [MODULE_API];
+/** The node_modules the host was loaded from, and the global one. */
+export function discoveryRoots(hostDir, execPath) {
+    const up = resolve(hostDir, "../..");
+    const local = basename(up) === "node_modules" ? up : null;
+    const global = local !== null && basename(dirname(local)) === "lib" ? local : resolve(dirname(execPath), "../lib/node_modules");
+    return { local, global };
+}
+// C0 controls, DEL, C1 controls, zero-width characters, line and paragraph
+// separators, bidi embeddings, overrides and isolates, and the BOM.
+export { clean };
+export function stateText(s) {
+    switch (s.kind) {
+        case "available":
+            return "loaded on demand";
+        case "refused":
+            return `refused: ${s.reason}`;
+        case "needs":
+            return s.version === null ? "needs a newer poietic-tech" : `needs poietic-tech ${s.version} or later`;
+        case "not-allowed":
+            return "not allowed";
+    }
+}
+const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/** `child` is strictly inside `parent` (both absolute, already resolved). */
+function inside(child, parent) {
+    const rel = relative(parent, child);
+    return rel !== "" && !isAbsolute(rel) && rel.split(sep)[0] !== "..";
+}
+async function readJson(file) {
+    try {
+        const parsed = JSON.parse(await readFile(file, "utf8"));
+        return isObject(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function list(dir) {
+    try {
+        return (await readdir(dir)).sort();
+    }
+    catch {
+        return [];
+    }
+}
+async function realOrNull(path) {
+    try {
+        return await realpath(path);
+    }
+    catch {
+        return null;
+    }
+}
+/** The lower bound of the module's `@poietic-tech/cli` peer range, if it reads as a version. */
+function neededVersion(pkg) {
+    const peers = pkg.peerDependencies;
+    if (!isObject(peers) || !Object.hasOwn(peers, HOST) || typeof peers[HOST] !== "string")
+        return null;
+    const m = /^[\^~>=\s]*(\d+(?:\.\d+){0,2})/.exec(peers[HOST]);
+    return m ? m[1] : null;
+}
+async function realRoots(roots) {
+    const out = [];
+    const pairs = [
+        [roots.local !== null && resolve(roots.local) !== resolve(roots.global) ? roots.local : null, "local"],
+        [roots.global, "global"],
+    ];
+    for (const [path, source] of pairs) {
+        if (path === null)
+            continue;
+        const real = await realOrNull(path);
+        if (real !== null)
+            out.push({ path, real, source });
+    }
+    return out;
+}
+/**
+ * Where the entry really is; "outside" when it resolves outside the package or
+ * the package outside every root; null when it cannot be resolved at all.
+ */
+async function checkEntry(dir, entry, roots) {
+    const lexical = resolve(dir, entry);
+    if (!inside(lexical, resolve(dir)))
+        return "outside";
+    const realDir = await realOrNull(dir);
+    if (realDir === null || !roots.some((r) => inside(realDir, r.real)))
+        return "outside";
+    // Missing, a dangling symlink or unreadable: nothing checked, so nothing to import.
+    const realEntry = await realOrNull(lexical);
+    if (realEntry === null)
+        return null;
+    return inside(realEntry, realDir) ? realEntry : "outside";
+}
+function field(pkg) {
+    const f = pkg["poietic-tech"];
+    if (!isObject(f))
+        return null;
+    const { command, entry, api, summary } = f;
+    if (typeof command !== "string" || !COMMAND.test(command))
+        return null;
+    if (typeof entry !== "string" || entry === "")
+        return null;
+    if (typeof api !== "number" || !Number.isInteger(api))
+        return null;
+    if (typeof summary !== "string")
+        return null;
+    return { command, entry, api, summary };
+}
+async function inspect(root, name, allowed, roots, builtins) {
+    const dir = join(root.path, name);
+    const pkg = await readJson(join(dir, "package.json"));
+    if (pkg === null || !Object.hasOwn(pkg, "poietic-tech"))
+        return null;
+    const raw = isObject(pkg["poietic-tech"]) ? pkg["poietic-tech"] : {};
+    const base = {
+        name: clean(name),
+        version: typeof pkg.version === "string" ? clean(pkg.version) : "",
+        command: typeof raw.command === "string" ? clean(raw.command) : null,
+        summary: typeof raw.summary === "string" ? clean(raw.summary) : "",
+        source: root.source,
+        dir,
+    };
+    const refused = (reason) => ({ ...base, entry: null, state: { kind: "refused", reason } });
+    // npm aliases install any package under any folder: the published name proves the scope, not the folder.
+    if (pkg.name !== name)
+        return refused("package name does not match its folder");
+    if (!allowed)
+        return { ...base, entry: null, state: { kind: "not-allowed" } };
+    const f = field(pkg);
+    if (f === null)
+        return { ...refused("invalid poietic-tech field"), command: null };
+    if (!SUPPORTED_API.includes(f.api))
+        return { ...base, entry: null, state: { kind: "needs", version: neededVersion(pkg) } };
+    if (builtins.has(f.command))
+        return refused(`command "${f.command}" is built in`);
+    const entry = await checkEntry(dir, f.entry, roots);
+    if (entry === "outside")
+        return refused("entry is outside the package");
+    // Missing, a dangling symlink or unreadable: refused, so it is never imported.
+    if (entry === null)
+        return refused("entry cannot be read");
+    return { ...base, entry, state: { kind: "available" } };
+}
+/** Package names in a root other than @poietic-tech's: top-level and other scopes. */
+async function otherPackages(root) {
+    const names = [];
+    for (const entry of await list(root)) {
+        if (entry.startsWith("@")) {
+            if (entry === SCOPE)
+                continue;
+            for (const sub of await list(join(root, entry)))
+                names.push(`${entry}/${sub}`);
+        }
+        else {
+            names.push(entry);
+        }
+    }
+    return names.filter((n) => PACKAGE_NAME.test(n));
+}
+export async function discover(roots, allowed, opts) {
+    const real = await realRoots(roots);
+    // `help exit-codes` is a built-in topic, so no module may claim the name either.
+    const builtins = new Set([...opts.builtins, "help", "exit-codes"]);
+    const allowedSet = new Set(allowed.filter((n) => PACKAGE_NAME.test(n)));
+    const found = [];
+    const seen = new Set();
+    const consider = async (root, name, isAllowed) => {
+        if (seen.has(name))
+            return;
+        const d = await inspect(root, name, isAllowed, real, builtins);
+        if (d === null)
+            return;
+        seen.add(name);
+        found.push(d);
+    };
+    for (const root of real) {
+        for (const sub of await list(join(root.path, SCOPE))) {
+            const name = `${SCOPE}/${sub}`;
+            if (name !== HOST && PACKAGE_NAME.test(name))
+                await consider(root, name, true);
+        }
+    }
+    for (const name of [...allowedSet].sort()) {
+        if (name.startsWith(`${SCOPE}/`))
+            continue;
+        for (const root of real)
+            await consider(root, name, true);
+    }
+    if (opts.unscoped) {
+        for (const root of real) {
+            for (const name of await otherPackages(root.path))
+                await consider(root, name, allowedSet.has(name));
+        }
+    }
+    // Two modules claiming one command are both refused.
+    const claims = new Map();
+    for (const d of found) {
+        if (d.state.kind !== "available" || d.command === null)
+            continue;
+        claims.set(d.command, [...(claims.get(d.command) ?? []), d]);
+    }
+    for (const [command, ds] of claims) {
+        if (ds.length < 2)
+            continue;
+        for (const d of ds) {
+            const other = ds.find((o) => o !== d);
+            d.state = { kind: "refused", reason: `command "${command}" is also claimed by ${other.name}` };
+            d.entry = null;
+        }
+    }
+    return found;
+}
+/** Import an available module's entry; any failure is module_failed, naming only the package. */
+export async function importModule(d) {
+    const failed = () => new CliError("module_failed", `The module ${d.name} failed to load.`);
+    if (d.state.kind !== "available" || d.entry === null)
+        throw failed();
+    let mod;
+    try {
+        mod = (await import(pathToFileURL(d.entry).href)).default;
+    }
+    catch {
+        throw failed();
+    }
+    if (!isObject(mod) || mod.api !== MODULE_API || typeof mod.setup !== "function")
+        throw failed();
+    return mod;
+}

package/dist/errors.d.ts

@@ -0,0 +1,23 @@
+/** The exit-code table, verbatim. */
+export declare const EXIT_ROWS: readonly {
+    exit: number;
+    meaning: string;
+    codes: readonly string[];
+}[];
+export declare const EXIT: Readonly<Record<string, number>>;
+export declare function exitCodeOf(code: string, status?: number): number;
+export declare class CliError extends Error {
+    readonly code: string;
+    readonly exitCode: number;
+    readonly status?: number;
+    constructor(code: string, message: string, opts?: {
+        status?: number;
+    });
+}
+/** The code a status stands for when the server named none. */
+export declare function codeByStatus(status: number): string;
+export declare function toCliError(error: unknown, signal: AbortSignal): CliError;
+export declare function redact(text: string): string;
+export declare function renderError(e: CliError, machine: boolean, color: boolean): string;
+/** The error for a failed auth-server answer. The body is read for its code only, never quoted. */
+export declare function apiError(res: Response, what: string): Promise<CliError>;