@wirecat/cli-base 0.65.4 → 0.66.0

package/CHANGELOG.md

@@ -8,6 +8,49 @@ Versions before 0.8.0 are in the [git tags](https://github.com/WireCatLabs/cli-b
 Every entry says what changed as a caller sees it, why, and what to watch for — the rules are
 [`docs/dev/CONVENTIONS.md`](docs/dev/CONVENTIONS.md#the-changelog).
 
+## 0.66.0 — 31.10.2026
+
+### Added
+
+- **`wcat`, one command that runs every tool: `wcat tg …` runs `wcat-tg …`** (`@wirecat/cli-base/wcat`). Another
+  program named `tg` or `drive` can sit earlier on PATH, and an agent or a script then runs it without any sign; a
+  `wcat-<name>` name is the tool's alone. Any `wcat-<name>` program on PATH joins, ours or not. `wcat --help` lists
+  what is installed with each tool's description, the WireCat tools that are not, with their install commands, and
+  warns when two programs share a name; `--json` prints the list. Built-in names (`help`, `version`, `shortcuts`,
+  `doctor`, `update`, `upgrade`, `app`) always belong to `wcat`. An unknown tool is `not_found` with the new reason
+  `tool.not-installed`. Nothing changes for a CLI until it calls `wcatStart`.
+- **`wcatStart(tool)` from `@wirecat/cli-base/wcat/start`, the first call in a CLI's bin.** It answers
+  `--wcat-describe` with the tool's name, version, description and docs page, runs `wcat` when the `wcat` launcher
+  starts the tool, and on any other start makes sure the `wcat` launcher in the tool's global bin folder works. The
+  launcher is a small marked script that starts an installed `wcat-<tool>` by name (a `.cmd` and `.ps1` pair on
+  Windows), never a link into a package folder, which pnpm renames on every upgrade. A file named `wcat` that
+  cli-base did not write is never touched. When the launcher works, the check costs a few `stat` calls; it loads
+  only Node built-ins. Call it before `startCli`, and set `process.exitCode` to the `code` it returns.
+- **`wcat shortcuts`, and `listShortcuts`, `addShortcuts` and `removeShortcuts` for a program.** A tool's short name,
+  such as `tg`, is made only when no program on PATH has it, and only shortcuts cli-base made are removed. A short
+  name the tool's package installs itself shows as `package` and is left to the package manager.
+- **`RESERVED_NAMES` and a `cli-dev lint` warning for joining `wcat`** ([WC-CMD-29](docs/standards/commands.md#wc-cmd-29--answer---wcat-describe-and-take-no-name-wirecat-reserves)).
+  The lint warns when a `"bin"` key does not start with `wcat-`, when a package outside `@wirecat/` takes a reserved
+  name, and, with `--cli`, when the built CLI does not answer `--wcat-describe`. The warnings do not fail the run:
+  every CLI still installs its short name today.
+
+## 0.65.5 — 31.10.2026
+
+### Added
+
+- **`movedRunService(app, configDir)` names a moved run's temporary keyring entry**, so a test or an agent can delete
+  it by name.
+
+### Security
+
+- **A moved run no longer replaces the owner's keyring entry.** `session start` in a worktree or with
+  `HOME=/tmp/x` overwrote the owner's real sign-in. With the system keyring, `Credentials` in a moved run (`isolated`,
+  or a moved `HOME` or XDG folder) now writes a temporary entry, `<app>:<absolute config folder>`; reads it first and
+  the owner's `<app>` entry when it has none; and `remove` deletes only the temporary entry, so `session end` cleans up.
+  A token refreshed in a moved run is saved in the temporary entry too, so a run that never ends its session leaves
+  one behind ([WC-SECR-24](docs/standards/security.md#wc-secr-24--a-run-with-moved-folders-shares-the-owners-keyring-entry-and-never-deletes-it)).
+  A run with the default folders, and a test with `memoryKeyring()`, are unchanged.
+
 ## 0.65.4 — 31.10.2026
 
 ### Fixed

package/README.md

@@ -187,6 +187,10 @@ operation and never falls back to `any`. 64-bit integers stay exact.
 - **Update checks that never update unasked.** Which package manager installed the CLI, the command that updates it,
   and a daily notice only when a person is at a terminal. A tool holding someone's credentials does not change itself.
 - **Release checks** every CLI shares: changelog shape, dead links, package contents, versions in step.
+- **`wcat`, one command for every tool.** `wcat tg …` runs `wcat-tg …`, like `git foo` runs `git-foo`, and any
+  `wcat-<name>` program on PATH joins. `wcat --help` lists what is installed with each tool's description;
+  `wcat shortcuts add` gives a tool its short name only where no other program has it. Each tool keeps the `wcat`
+  launcher working on start, at the cost of a few `stat` calls.
 
 ## Engineering
 

package/dist/credentials.d.ts

@@ -14,10 +14,9 @@ export interface CredentialsOptions {
     /**
      * **True when the run's folders are not the owner's own** — pass `isMovedRun(…)`.
      *
-     * The run still uses the owner's keyring entry (`service`, the same account names): one sign-in per computer, not
-     * one per temp folder. With the system keyring, `remove` then keeps that entry instead of deleting it, so a test or
-     * worktree run cannot end the owner's real sign-in (WC-SECR-24). A moved `HOME` or XDG folder in `env` counts as
-     * moved even when this is false.
+     * With the system keyring the run reads the owner's entry (`service`) but never replaces or deletes it: `write`
+     * goes to a temporary entry, `movedRunService(service, configDir)`, which `read` prefers and `remove` deletes
+     * (WC-SECR-24). A moved `HOME` or XDG folder in `env` counts as moved even when this is false.
      */
     isolated?: boolean;
     /** Read before the keyring, for CI. */
@@ -30,10 +29,15 @@ export interface CredentialsOptions {
     warn?: (message: string) => void;
 }
 /**
- * The keyring service a `Credentials` uses: the app's own, for a moved run too. The other two arguments are ignored
- * and stay only so that callers written against 0.65.0 still compile.
+ * The app's shared keyring service, which a moved run reads too. The other two arguments are ignored and stay only so
+ * that callers written against 0.65.0 still compile.
  */
 export declare const keyringService: (service: string, _configDir?: string, _isolated?: boolean) => string;
+/**
+ * The temporary keyring service a moved run writes instead of the owner's entry: `<app>:<absolute config folder>`, the
+ * shape `bin/keyring-dedupe` already finds and removes.
+ */
+export declare const movedRunService: (service: string, configDir: string) => string;
 /**
  * Environment first, then the OS keyring, then a file.
  *

package/dist/credentials.js

@@ -1,15 +1,20 @@
 import { readFileSync } from "node:fs";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 import { writeSecurely } from "./config.js";
 import { CliError } from "./errors.js";
 import { systemKeyring } from "./keyring.js";
 import { homeIsMoved } from "./paths.js";
 export const CREDENTIAL_STORAGE = ["auto", "keyring", "file"];
 /**
- * The keyring service a `Credentials` uses: the app's own, for a moved run too. The other two arguments are ignored
- * and stay only so that callers written against 0.65.0 still compile.
+ * The app's shared keyring service, which a moved run reads too. The other two arguments are ignored and stay only so
+ * that callers written against 0.65.0 still compile.
  */
 export const keyringService = (service, _configDir, _isolated) => service;
+/**
+ * The temporary keyring service a moved run writes instead of the owner's entry: `<app>:<absolute config folder>`, the
+ * shape `bin/keyring-dedupe` already finds and removes.
+ */
+export const movedRunService = (service, configDir) => `${service}:${resolve(configDir)}`;
 /**
  * Environment first, then the OS keyring, then a file.
  *
@@ -26,7 +31,8 @@ export class Credentials {
     #envVar;
     #fileName;
     #warn;
-    #keepsSharedEntry;
+    /** Set only for a moved run with the system keyring. */
+    #temporaryService;
     #warned = false;
     constructor(options) {
         this.#configDir = options.configDir;
@@ -37,15 +43,16 @@ export class Credentials {
         this.#fileName = options.fileName ?? "credentials.json";
         this.#warn = options.warn ?? ((message) => process.stderr.write(`${message}\n`));
         this.#service = options.service;
-        this.#keepsSharedEntry =
-            this.#keyring === systemKeyring && (options.isolated === true || homeIsMoved({ env: this.#env }));
+        const moved = this.#keyring === systemKeyring && (options.isolated === true || homeIsMoved({ env: this.#env }));
+        this.#temporaryService = moved ? movedRunService(options.service, options.configDir) : undefined;
     }
     read(account) {
         const fromEnv = this.#envVar ? this.#env[this.#envVar]?.trim() : undefined;
         if (fromEnv)
             return { secret: fromEnv, source: "environment" };
         if (this.#storage !== "file") {
-            const fromKeyring = this.#tryKeyring(() => this.#keyring.get(this.#service, account));
+            const temporary = this.#temporaryService;
+            const fromKeyring = this.#tryKeyring(() => (temporary && this.#keyring.get(temporary, account)) || this.#keyring.get(this.#service, account));
             if (fromKeyring)
                 return { secret: fromKeyring, source: "keyring" };
         }
@@ -55,7 +62,7 @@ export class Credentials {
     write(account, secret) {
         if (this.#storage !== "file") {
             const stored = this.#tryKeyring(() => {
-                this.#keyring.set(this.#service, account, secret);
+                this.#keyring.set(this.#temporaryService ?? this.#service, account, secret);
                 return true;
             });
             if (stored)
@@ -72,12 +79,14 @@ export class Credentials {
     }
     remove(account) {
         const removed = [];
-        if (this.#storage !== "file" && this.#keepsSharedEntry) {
-            this.#warn(`kept ${account} in the OS keyring: it is the owner's sign-in, shared with every run, and a run with moved ` +
-                "folders never removes it");
-        }
-        else if (this.#storage !== "file" && this.#tryKeyring(() => this.#keyring.delete(this.#service, account))) {
-            removed.push("keyring");
+        if (this.#storage !== "file") {
+            if (this.#tryKeyring(() => this.#keyring.delete(this.#temporaryService ?? this.#service, account))) {
+                removed.push("keyring");
+            }
+            if (this.#temporaryService) {
+                this.#warn(`kept ${account} in the OS keyring: it is the owner's sign-in, shared with every run, and a run with moved ` +
+                    "folders never removes it");
+            }
         }
         const store = this.#readFile();
         if (store?.[account] !== undefined) {

package/dist/dev/main.d.ts

@@ -1,3 +1,4 @@
+import spawn from "cross-spawn";
 import { type RunLogProbe } from "./lint.js";
 export interface DevIo {
     cwd: string;
@@ -12,4 +13,8 @@ export interface DevIo {
  * `XDG_STATE_HOME` would point it at the owner's real runs.
  */
 export declare const probeRunLog: (cwd: string, bin: string, environment?: NodeJS.ProcessEnv) => RunLogProbe;
+type HomeCall = (args: string[]) => ReturnType<typeof spawn.sync>;
+/** Runs the built CLI in a new empty home with only PATH from this environment, and removes the home after. */
+export declare const inEmptyHome: <T>(cwd: string, bin: string, environment: NodeJS.ProcessEnv, body: (call: HomeCall) => T) => T;
 export declare const main: (argv: readonly string[], io: DevIo) => Promise<number>;
+export {};

package/dist/dev/main.js

@@ -25,6 +25,7 @@ import { baselineOf, judge, lintCommands, RUN_LOG_COMMANDS, walk } from "./lint.
 import { nextVersion } from "./next-version.js";
 import { slowTests } from "./slow-tests.js";
 import { matrixPage, matrixRows, parseArgvLog } from "./test-matrix.js";
+import { binNameWarnings, describeWarnings } from "./wcat-lint.js";
 const USAGE = `usage: cli-dev <command> [options]
 
   slow-tests [report] [count]          the slowest tests and files (report: coverage/tests.json, count: 20)
@@ -257,7 +258,25 @@ const PROBE_FLAG = "--cli-dev-run-log-probe";
  * kept. The CLI sees a new empty home and nothing else from this environment: a stray `*_STATE_DIR` or
  * `XDG_STATE_HOME` would point it at the owner's real runs.
  */
-export const probeRunLog = (cwd, bin, environment = process.env) => {
+export const probeRunLog = (cwd, bin, environment = process.env) => inEmptyHome(cwd, bin, environment, (call) => {
+    const failed = call([PROBE_FLAG]);
+    if (failed.status === 0)
+        return { kept: false, detail: `\`${PROBE_FLAG}\` did not fail, so nothing could be kept` };
+    const listed = call(["runs", "list", "--json"]);
+    if (listed.status !== 0)
+        return { kept: false, detail: `\`runs list --json\` exited ${listed.status ?? listed.error?.message}` };
+    let items;
+    try {
+        items = JSON.parse(String(listed.stdout)).items;
+    }
+    catch {
+        return { kept: false, detail: "`runs list --json` did not print JSON" };
+    }
+    const kept = Array.isArray(items) && items.some((item) => item?.status === "failed");
+    return kept ? { kept } : { kept, detail: `\`runs list --json\` shows no failed run after \`${PROBE_FLAG}\`` };
+});
+/** Runs the built CLI in a new empty home with only PATH from this environment, and removes the home after. */
+export const inEmptyHome = (cwd, bin, environment, body) => {
     const home = mkdtempSync(join(tmpdir(), "cli-dev-run-log-"));
     const env = {
         PATH: environment.PATH ?? "",
@@ -277,21 +296,7 @@ export const probeRunLog = (cwd, bin, environment = process.env) => {
         maxBuffer: 16 * 1024 * 1024,
     });
     try {
-        const failed = call([PROBE_FLAG]);
-        if (failed.status === 0)
-            return { kept: false, detail: `\`${PROBE_FLAG}\` did not fail, so nothing could be kept` };
-        const listed = call(["runs", "list", "--json"]);
-        if (listed.status !== 0)
-            return { kept: false, detail: `\`runs list --json\` exited ${listed.status ?? listed.error?.message}` };
-        let items;
-        try {
-            items = JSON.parse(String(listed.stdout)).items;
-        }
-        catch {
-            return { kept: false, detail: "`runs list --json` did not print JSON" };
-        }
-        const kept = Array.isArray(items) && items.some((item) => item?.status === "failed");
-        return kept ? { kept } : { kept, detail: `\`runs list --json\` shows no failed run after \`${PROBE_FLAG}\`` };
+        return body(call);
     }
     finally {
         rmSync(home, { recursive: true, force: true });
@@ -406,8 +411,18 @@ const lintRun = (args, io) => {
     if (verdict.overBudget)
         problems.push(`${overrides.length} overrides; the budget is ${budget}`);
     io.err(`lint: ${violations.length} violations — ${verdict.baselined} in the baseline, ${verdict.overridden} overridden (budget ${budget}), ${verdict.fresh.length} new`);
+    for (const warning of wcatWarnings(io.cwd, values.cli))
+        io.err(`warning  ${warning.rule}  ${warning.target}: ${warning.message}`);
     return report(io, problems, "lint: ok");
 };
+const wcatWarnings = (cwd, cli) => {
+    const pkgPath = join(cwd, "package.json");
+    const pkg = existsSync(pkgPath) ? readJson(pkgPath) : {};
+    return [
+        ...binNameWarnings(pkg),
+        ...(cli ? describeWarnings(inEmptyHome(cwd, cli, process.env, (call) => call(["--wcat-describe"]))) : []),
+    ];
+};
 const byCli = (pairs, flag) => new Map((pairs ?? []).map((pair) => {
     const [cli, path] = pair.split(/=(.*)/s);
     if (!cli || !path)

package/dist/dev/wcat-lint.d.ts

@@ -0,0 +1,15 @@
+export interface WcatWarning {
+    rule: "wcat-bin-name" | "wcat-describe";
+    target: string;
+    message: string;
+}
+/** Each command is `wcat-<name>`, and a package outside `@wirecat/` takes no reserved name. */
+export declare const binNameWarnings: (pkg: {
+    name?: unknown;
+    bin?: unknown;
+}) => WcatWarning[];
+/** The built CLI answers `--wcat-describe` with its JSON description. */
+export declare const describeWarnings: (answer: {
+    status: number | null;
+    stdout: unknown;
+}) => WcatWarning[];

package/dist/dev/wcat-lint.js

@@ -0,0 +1,42 @@
+/**
+ * `cli-dev lint`'s checks for joining `wcat` (WC-CMD-29). They warn and never fail the run: every CLI still installs
+ * its short name until it moves to `wcat-<name>`, and the warning becomes a failure once they have.
+ */
+import { parseDescribe } from "../wcat/describe.js";
+import { DESCRIBE_FLAG, PROGRAM_PREFIX, RESERVED_NAMES, TOOL_NAME } from "../wcat/names.js";
+const WIRECAT_SCOPE = "@wirecat/";
+/** The commands a `package.json` installs: its `"bin"` keys, or the package's own name for a `"bin"` string. */
+const binNames = (pkg) => {
+    if (typeof pkg.bin === "string")
+        return typeof pkg.name === "string" ? [pkg.name.replace(/^@[^/]+\//, "")] : [];
+    return typeof pkg.bin === "object" && pkg.bin !== null ? Object.keys(pkg.bin) : [];
+};
+/** Each command is `wcat-<name>`, and a package outside `@wirecat/` takes no reserved name. */
+export const binNameWarnings = (pkg) => binNames(pkg).flatMap((command) => {
+    const target = `package.json "bin" ${command}`;
+    if (!command.startsWith(PROGRAM_PREFIX))
+        return [
+            {
+                rule: "wcat-bin-name",
+                target,
+                message: `install the command as ${PROGRAM_PREFIX}${command}, so no other program on PATH has its name`,
+            },
+        ];
+    const name = command.slice(PROGRAM_PREFIX.length);
+    if (!TOOL_NAME.test(name))
+        return [{ rule: "wcat-bin-name", target, message: "the name after wcat- is lower-case letters, digits and -" }];
+    const ours = typeof pkg.name === "string" && pkg.name.startsWith(WIRECAT_SCOPE);
+    if (!ours && RESERVED_NAMES.includes(name))
+        return [{ rule: "wcat-bin-name", target, message: `${name} is reserved for WireCat's own tools or wcat itself` }];
+    return [];
+});
+/** The built CLI answers `--wcat-describe` with its JSON description. */
+export const describeWarnings = (answer) => answer.status === 0 && parseDescribe(String(answer.stdout))
+    ? []
+    : [
+        {
+            rule: "wcat-describe",
+            target: DESCRIBE_FLAG,
+            message: `the CLI does not answer ${DESCRIBE_FLAG}: call wcatStart from @wirecat/cli-base/wcat/start first in its bin`,
+        },
+    ];

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { BATCH_LIMITS, type BatchContext, type BatchHandler, type BatchOperation, type BatchReport, type BatchResult, type PreparedBatchRequest, prepareBatch, projectBatchAnswers, readBatchInput, runBatch, } from "./batch.js";
 export { loadConfigFile, saveConfigFile, writeSecurely } from "./config.js";
 export type { CredentialSource, CredentialStorage, CredentialsOptions, StoredCredential } from "./credentials.js";
-export { CREDENTIAL_STORAGE, Credentials, keyringService } from "./credentials.js";
+export { CREDENTIAL_STORAGE, Credentials, keyringService, movedRunService } from "./credentials.js";
 export { createDeadline, type Deadline, type DeadlineOptions } from "./deadline.js";
 export { CliError, type CliErrorDetails, type ErrorCode, errorCodes, isCliError } from "./errors.js";
 export { EXIT_CODES, exitCodeFor, GENERIC_FAILURE } from "./exit-codes.js";

package/dist/index.js

@@ -1,6 +1,6 @@
 export { BATCH_LIMITS, prepareBatch, projectBatchAnswers, readBatchInput, runBatch, } from "./batch.js";
 export { loadConfigFile, saveConfigFile, writeSecurely } from "./config.js";
-export { CREDENTIAL_STORAGE, Credentials, keyringService } from "./credentials.js";
+export { CREDENTIAL_STORAGE, Credentials, keyringService, movedRunService } from "./credentials.js";
 export { createDeadline } from "./deadline.js";
 export { CliError, errorCodes, isCliError } from "./errors.js";
 export { EXIT_CODES, exitCodeFor, GENERIC_FAILURE } from "./exit-codes.js";

package/dist/installer.d.ts

@@ -0,0 +1,7 @@
+export type Installer = "pnpm" | "npm" | "bun" | "npx" | "checkout" | "unknown";
+/**
+ * Read from where the running file really lives — `realpath` of the script, not `which`: the
+ * command on `PATH` is a shim or a link, and only its target says who installed it. Paths measured
+ * on 2026-09-24 by installing into throwaway prefixes.
+ */
+export declare const installerOf: (scriptPath: string) => Installer;

package/dist/installer.js

@@ -0,0 +1,17 @@
+/**
+ * Read from where the running file really lives — `realpath` of the script, not `which`: the
+ * command on `PATH` is a shim or a link, and only its target says who installed it. Paths measured
+ * on 2026-09-24 by installing into throwaway prefixes.
+ */
+export const installerOf = (scriptPath) => {
+    const path = scriptPath.replaceAll("\\", "/");
+    if (path.includes("/_npx/"))
+        return "npx";
+    if (path.includes("/install/global/node_modules/"))
+        return "bun";
+    if (/\/\.?pnpm\//.test(path))
+        return "pnpm";
+    if (path.includes("/node_modules/"))
+        return "npm";
+    return path.includes("/dist/") ? "checkout" : "unknown";
+};

package/dist/standards/errors.js

@@ -61,6 +61,12 @@ export const BASE_REASONS = defineReasons([
     { reason: "auth.failed", code: "authentication_error", message: "the sign-in did not work", details: [] },
     { reason: "access.denied", code: "permission_error", message: "this account may not do that", details: [] },
     { reason: "item.not-found", code: "not_found", message: "nothing found by that name", details: [] },
+    {
+        reason: "tool.not-installed",
+        code: "not_found",
+        message: "no wcat-<name> program by that name is on PATH",
+        details: ["tool", "installed"],
+    },
     {
         reason: "confirmation.required",
         code: "confirmation_required",

package/dist/update/index.d.ts

@@ -1,13 +1,8 @@
 export { executableEnvironment, executableOnPath } from "../executable.js";
 import * as v from "valibot";
 import type { FetchLike } from "../http/index.js";
-export type Installer = "pnpm" | "npm" | "bun" | "npx" | "checkout" | "unknown";
-/**
- * Read from where the running file really lives — `realpath` of the script, not `which`: the
- * command on `PATH` is a shim or a link, and only its target says who installed it. Paths measured
- * on 2026-09-24 by installing into throwaway prefixes.
- */
-export declare const installerOf: (scriptPath: string) => Installer;
+export { type Installer, installerOf } from "../installer.js";
+import type { Installer } from "../installer.js";
 /** The argv that updates a global install, or `undefined` where there is nothing to run. */
 export declare const updateCommand: (installer: Installer, packageName: string) => string[] | undefined;
 /** Plain `x.y.z` only: a pre-release is never offered, so it never counts as newer. */

package/dist/update/index.js

@@ -12,23 +12,7 @@ import { executableEnvironment, executableOnPath } from "../executable.js";
 export { executableEnvironment, executableOnPath } from "../executable.js";
 import * as v from "valibot";
 import { loadConfigFile, saveConfigFile } from "../config.js";
-/**
- * Read from where the running file really lives — `realpath` of the script, not `which`: the
- * command on `PATH` is a shim or a link, and only its target says who installed it. Paths measured
- * on 2026-09-24 by installing into throwaway prefixes.
- */
-export const installerOf = (scriptPath) => {
-    const path = scriptPath.replaceAll("\\", "/");
-    if (path.includes("/_npx/"))
-        return "npx";
-    if (path.includes("/install/global/node_modules/"))
-        return "bun";
-    if (/\/\.?pnpm\//.test(path))
-        return "pnpm";
-    if (path.includes("/node_modules/"))
-        return "npm";
-    return path.includes("/dist/") ? "checkout" : "unknown";
-};
+export { installerOf } from "../installer.js";
 /** The argv that updates a global install, or `undefined` where there is nothing to run. */
 export const updateCommand = (installer, packageName) => {
     const target = `${packageName}@latest`;

package/dist/wcat/describe.d.ts

@@ -0,0 +1,22 @@
+/** What a tool says about itself to `wcat`, from `wcat-<name> --wcat-describe` or the tool's own metadata. */
+export interface WcatTool {
+    /** The name in `wcat <name>`, and the short command: `tg`. */
+    command: string;
+    version: string;
+    /** One line: what the tool reads or does. */
+    description: string;
+    /** The tool's documentation page. */
+    docs?: string;
+}
+/** Format of the `--wcat-describe` answer; a later format adds keys and keeps these. */
+export declare const DESCRIBE_FORMAT = 1;
+export interface DescribeAnswer {
+    wcat_describe: number;
+    name: string;
+    version: string;
+    description: string;
+    docs_url?: string;
+}
+export declare const describeAnswer: (tool: WcatTool) => DescribeAnswer;
+/** A `--wcat-describe` answer, or `undefined` for anything else: the program is listed either way. */
+export declare const parseDescribe: (text: string) => Omit<WcatTool, "command"> | undefined;

package/dist/wcat/describe.js

@@ -0,0 +1,31 @@
+import { singleLine } from "../sanitize.js";
+/** Format of the `--wcat-describe` answer; a later format adds keys and keeps these. */
+export const DESCRIBE_FORMAT = 1;
+export const describeAnswer = (tool) => ({
+    wcat_describe: DESCRIBE_FORMAT,
+    name: tool.command,
+    version: tool.version,
+    description: tool.description,
+    ...(tool.docs ? { docs_url: tool.docs } : {}),
+});
+const MAX_TEXT = 200;
+const clean = (value) => typeof value === "string" && value.trim() !== "" ? singleLine(value.trim()).slice(0, MAX_TEXT) : undefined;
+/** A `--wcat-describe` answer, or `undefined` for anything else: the program is listed either way. */
+export const parseDescribe = (text) => {
+    let answer;
+    try {
+        answer = JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof answer !== "object" || answer === null || !("wcat_describe" in answer))
+        return undefined;
+    const { version, description, docs_url: docs } = answer;
+    const url = clean(docs);
+    return {
+        version: clean(version) ?? "",
+        description: clean(description) ?? "",
+        ...(url && /^https?:\/\//.test(url) ? { docs: url } : {}),
+    };
+};

package/dist/wcat/dispatch.d.ts

@@ -0,0 +1,43 @@
+import type { WcatTool } from "./describe.js";
+import { type SearchEnv } from "./path.js";
+interface Output {
+    write: (text: string) => unknown;
+    isTTY?: boolean;
+}
+export interface WcatContext extends SearchEnv {
+    stdout: Output;
+    stderr: Output;
+    /** The tool running the dispatcher: described from its metadata, without starting it again. */
+    self?: WcatTool;
+    /** How long one `--wcat-describe` may take; 2 s when left out. */
+    describeTimeoutMs?: number;
+    /** Where SIGTERM and SIGHUP arrive, to pass on to the tool; `process` when left out. */
+    signals?: Pick<NodeJS.Process, "on" | "off">;
+}
+export interface ListedTool {
+    name: string;
+    installed: boolean;
+    /** The program `wcat <name>` starts. */
+    path?: string;
+    version?: string;
+    description?: string;
+    docs_url?: string;
+    /** Other programs with the same name, later on PATH: `wcat` never runs them. */
+    shadowed?: string[];
+    package?: string;
+    install?: string;
+}
+/** Every `wcat-<name>` on PATH with what it says about itself, then WireCat's own tools that are not installed. */
+export declare const listTools: (context: WcatContext) => Promise<ListedTool[]>;
+/**
+ * Starts `wcat-<name>` with the rest of the words, the same streams and environment, and answers its exit code.
+ * SIGTERM and SIGHUP are passed on. Ctrl-C reaches the tool from the terminal by itself, so SIGINT is only kept from
+ * ending `wcat` before the tool does.
+ */
+export declare const runTool: (path: string, args: readonly string[], context: WcatContext) => Promise<number>;
+/**
+ * `wcat` itself: the words after `wcat`. Built-in commands come first, so a `wcat-<name>` program can never take
+ * one over; anything else names a tool, and the rest of the line is that tool's.
+ */
+export declare const runWcat: (args: readonly string[], context: WcatContext) => Promise<number>;
+export {};