@wirecat/cli-base 0.65.5 → 0.66.0

package/CHANGELOG.md

@@ -8,6 +8,32 @@ 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

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/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/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 {};

package/dist/wcat/dispatch.js

@@ -0,0 +1,184 @@
+import { randomUUID } from "node:crypto";
+import { constants } from "node:os";
+import crossSpawn from "cross-spawn";
+import { CliError } from "../errors.js";
+import { BUILT_IN_COMMANDS, FIRST_PARTY_TOOLS, PROGRAM_PREFIX, TOOL_NAME } from "./names.js";
+import { findOnPath } from "./path.js";
+import { baseVersion, probeDescribe } from "./probe.js";
+import { addShortcuts, installedPrograms, listShortcuts, removeShortcuts } from "./shortcuts.js";
+const DEFAULT_DESCRIBE_TIMEOUT_MS = 2000;
+/** Every `wcat-<name>` on PATH with what it says about itself, then WireCat's own tools that are not installed. */
+export const listTools = async (context) => {
+    const installed = installedPrograms(context);
+    const timeoutMs = context.describeTimeoutMs ?? DEFAULT_DESCRIBE_TIMEOUT_MS;
+    const found = await Promise.all([...installed].map(async ([name, paths]) => {
+        const [path, ...shadowed] = paths;
+        const own = context.self?.command === name ? context.self : undefined;
+        const described = own ?? (await probeDescribe(path, { env: context.env, timeoutMs }));
+        return {
+            name,
+            installed: true,
+            path,
+            ...(described?.version ? { version: described.version } : {}),
+            ...(described?.description ? { description: described.description } : {}),
+            ...(described?.docs ? { docs_url: described.docs } : {}),
+            ...(shadowed.length > 0 ? { shadowed } : {}),
+        };
+    }));
+    const missing = FIRST_PARTY_TOOLS.filter((tool) => tool.package && !installed.has(tool.name)).map((tool) => ({
+        name: tool.name,
+        installed: false,
+        package: tool.package,
+        install: `npm install -g ${tool.package}`,
+    }));
+    return [...found, ...missing];
+};
+const envelope = (items, started) => ({
+    items,
+    page: { mode: "page", limit: Math.max(items.length, 1), has_more: false },
+    meta: { run_id: randomUUID(), duration_ms: Math.max(0, Math.round(performance.now() - started)), complete: true },
+});
+const column = (rows) => {
+    const widths = rows[0]?.map((_, at) => rows.reduce((wide, row) => Math.max(wide, (row[at] ?? "").length), 0)) ?? [];
+    return rows.map((row) => `  ${row.map((cell, at) => cell.padEnd(widths[at] ?? 0)).join("  ")}`.trimEnd());
+};
+const USAGE = [
+    "wcat <tool> [arguments]                 run a tool: wcat tg --help",
+    "wcat shortcuts [add|remove] [tool...]   short names, such as tg, for installed tools",
+    "wcat --json                             the list below as JSON",
+];
+const listText = (tools) => {
+    const installed = tools.filter((tool) => tool.installed);
+    const missing = tools.filter((tool) => !tool.installed);
+    return [
+        "wcat runs WireCat tools, and any other wcat-<name> program on PATH.",
+        "",
+        ...USAGE,
+        "",
+        installed.length > 0 ? "Installed:" : "Installed: none",
+        ...column(installed.map((tool) => [tool.name, tool.version ?? "", tool.description ?? "(no description)"])),
+        ...(missing.length > 0
+            ? ["", "Not installed:", ...column(missing.map((tool) => [tool.name, tool.install ?? ""]))]
+            : []),
+        "",
+    ].join("\n");
+};
+const shadowWarnings = (tools) => tools
+    .filter((tool) => tool.shadowed)
+    .map((tool) => `wcat: ${(tool.shadowed?.length ?? 0) + 1} programs are named ${PROGRAM_PREFIX}${tool.name}; wcat runs the first:\n${[tool.path, ...(tool.shadowed ?? [])].map((path) => `  ${path}`).join("\n")}\n`)
+    .join("");
+const shortcutText = (shortcuts) => {
+    if (shortcuts.length === 0)
+        return "No wcat-<name> programs are installed.\n";
+    const said = (shortcut) => {
+        switch (shortcut.status) {
+            case "made":
+                return `made: ${shortcut.path}`;
+            case "free":
+                return shortcut.changed ? "removed" : "free: wcat shortcuts add makes it";
+            case "package":
+                return `installed by the package: ${shortcut.path}`;
+            case "taken":
+                return `taken by ${shortcut.path}`;
+        }
+    };
+    return `${column(shortcuts.map((shortcut) => [shortcut.name, said(shortcut)])).join("\n")}\n`;
+};
+const signalNumber = (signal) => constants.signals[signal] ?? 1;
+/**
+ * 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 const runTool = (path, args, context) => new Promise((resolve, reject) => {
+    const signals = context.signals ?? process;
+    const child = crossSpawn(path, [...args], { stdio: "inherit", env: context.env });
+    const pass = (signal) => () => child.kill(signal);
+    const term = pass("SIGTERM");
+    const hup = pass("SIGHUP");
+    const ignore = () => { };
+    signals.on("SIGTERM", term).on("SIGHUP", hup).on("SIGINT", ignore);
+    const done = () => signals.off("SIGTERM", term).off("SIGHUP", hup).off("SIGINT", ignore);
+    child.once("error", (error) => {
+        done();
+        reject(new CliError("configuration_error", `could not start ${path}: ${error.message}`));
+    });
+    child.once("exit", (code, signal) => {
+        done();
+        resolve(code ?? (signal ? 128 + signalNumber(signal) : 1));
+    });
+});
+const fail = async (error, json, context) => {
+    const { errorObjectOf, exitCodeOfError, renderError } = await import("../failure.js");
+    const object = errorObjectOf(error);
+    context.stderr.write(`${renderError(object, { cli: "wcat", interactive: !json })}\n`);
+    return exitCodeOfError(object);
+};
+const shortcuts = async (args, json, context) => {
+    const [action, ...names] = args;
+    const started = performance.now();
+    const result = action === "add"
+        ? addShortcuts(context, names)
+        : action === "remove"
+            ? removeShortcuts(context, names)
+            : action === undefined || action === "list"
+                ? listShortcuts(context, names)
+                : undefined;
+    if (result === undefined)
+        throw new CliError("validation_error", `wcat shortcuts takes list, add or remove, not "${action}"`, {
+            reason: "input.invalid",
+        });
+    context.stdout.write(json ? `${JSON.stringify(envelope(result, started))}\n` : shortcutText(result));
+    return 0;
+};
+/**
+ * `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 const runWcat = async (args, context) => {
+    const [first, ...rest] = args;
+    // A tool's own --json is the tool's; wcat reads it only for its own answers and for a tool it cannot find.
+    const json = args.includes("--json");
+    const words = args.filter((word) => word !== "--json");
+    const started = performance.now();
+    try {
+        if (first === "--version" || first === "-V" || first === "version") {
+            const tools = await listTools(context);
+            const by = context.self ? `, run by ${PROGRAM_PREFIX}${context.self.command} ${context.self.version}` : "";
+            context.stdout.write(`wcat ${baseVersion()} (@wirecat/cli-base${by})\n\n${listText(tools)}`);
+            return 0;
+        }
+        if (words.length === 0 || first === "--help" || first === "-h" || first === "help") {
+            const tools = await listTools(context);
+            if (json)
+                context.stdout.write(`${JSON.stringify(envelope(tools, started))}\n`);
+            else {
+                context.stderr.write(shadowWarnings(tools));
+                context.stdout.write(listText(tools));
+            }
+            return 0;
+        }
+        if (first === "shortcuts")
+            return await shortcuts(words.slice(1), json, context);
+        if (BUILT_IN_COMMANDS.includes(first))
+            throw new CliError("validation_error", `wcat ${first} is reserved for a later version of wcat`, {
+                reason: "input.invalid",
+            });
+        if (first?.startsWith("-"))
+            throw new CliError("validation_error", `wcat does not take ${first} before a tool's name`, {
+                reason: "input.invalid",
+            });
+        const name = first;
+        const [path, ...shadowed] = TOOL_NAME.test(name) ? findOnPath(`${PROGRAM_PREFIX}${name}`, context) : [];
+        if (path === undefined) {
+            const installed = [...installedPrograms(context).keys()];
+            throw new CliError("not_found", `no ${PROGRAM_PREFIX}${name} on PATH; installed: ${installed.length > 0 ? installed.join(", ") : "none"}`, { reason: "tool.not-installed", tool: name, installed });
+        }
+        if (shadowed.length > 0 && context.stderr.isTTY)
+            context.stderr.write(shadowWarnings([{ name, installed: true, path, shadowed }]));
+        return await runTool(path, rest, context);
+    }
+    catch (error) {
+        return fail(error, json, context);
+    }
+};

package/dist/wcat/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `wcat`, the umbrella command: `wcat tg …` runs `wcat-tg …`, as `git foo` runs `git-foo`. Its code is here, so every
+ * CLI on cli-base carries a copy; the `wcat` file on PATH is a small launcher that starts an installed tool in
+ * dispatch mode, and each tool repairs it on start.
+ *
+ * A CLI's bin imports `wcatStart` from `@wirecat/cli-base/wcat/start`, which loads only Node built-ins; this entry
+ * point is the whole library, for WireCat Desktop and for tests.
+ */
+export { type DescribeAnswer, describeAnswer, parseDescribe, type WcatTool } from "./describe.js";
+export { type ListedTool, listTools, runWcat, type WcatContext } from "./dispatch.js";
+export { type BinFolder, binFolder, ensureLauncher, type LauncherState } from "./launcher.js";
+export { BUILT_IN_COMMANDS, DESCRIBE_FLAG, DISPATCH_FLAG, FIRST_PARTY_TOOLS, PROGRAM_PREFIX, RESERVED_NAMES, TOOL_NAME, } from "./names.js";
+export { findOnPath, findTools, type SearchEnv } from "./path.js";
+export { parseShim, SHIM_FORMAT, type ShimKind, shimFiles } from "./shim.js";
+export { addShortcuts, installedPrograms, listShortcuts, removeShortcuts, type Shortcut, type ShortcutChange, type ShortcutStatus, } from "./shortcuts.js";
+export { type WcatStart, type WcatStartIo, wcatStart } from "./start.js";

package/dist/wcat/index.js

@@ -0,0 +1,16 @@
+/**
+ * `wcat`, the umbrella command: `wcat tg …` runs `wcat-tg …`, as `git foo` runs `git-foo`. Its code is here, so every
+ * CLI on cli-base carries a copy; the `wcat` file on PATH is a small launcher that starts an installed tool in
+ * dispatch mode, and each tool repairs it on start.
+ *
+ * A CLI's bin imports `wcatStart` from `@wirecat/cli-base/wcat/start`, which loads only Node built-ins; this entry
+ * point is the whole library, for WireCat Desktop and for tests.
+ */
+export { describeAnswer, parseDescribe } from "./describe.js";
+export { listTools, runWcat } from "./dispatch.js";
+export { binFolder, ensureLauncher } from "./launcher.js";
+export { BUILT_IN_COMMANDS, DESCRIBE_FLAG, DISPATCH_FLAG, FIRST_PARTY_TOOLS, PROGRAM_PREFIX, RESERVED_NAMES, TOOL_NAME, } from "./names.js";
+export { findOnPath, findTools } from "./path.js";
+export { parseShim, SHIM_FORMAT, shimFiles } from "./shim.js";
+export { addShortcuts, installedPrograms, listShortcuts, removeShortcuts, } from "./shortcuts.js";
+export { wcatStart } from "./start.js";

package/dist/wcat/launcher.d.ts

@@ -0,0 +1,40 @@
+export interface BinFolderInput {
+    /** The tool's name in `wcat <name>`: `tg`. */
+    name: string;
+    /** `process.argv[1]`: the command as it was started, which is the bin folder's own link where npm makes one. */
+    argv1?: string;
+    /** A file of the installed package, links resolved: where it lives says which package manager put it there. */
+    script: string;
+    env: NodeJS.ProcessEnv;
+    platform: NodeJS.Platform;
+}
+export interface BinFolder {
+    dir: string;
+    /** The tool's own command in it, `wcat-tg` or `wcat-tg.cmd`. */
+    program: string;
+}
+/**
+ * The global bin folder the running tool was installed into, or `undefined` for npx, a checkout or a project's own
+ * `node_modules/.bin`. At most four `stat` calls, so it can run on every start.
+ */
+export declare const binFolder: ({ name, argv1, script, env, platform }: BinFolderInput) => BinFolder | undefined;
+/**
+ * Whether the program in `dir` still starts something. bun on Windows leaves a tool's `.exe` behind when the tool is
+ * uninstalled; the `.bunx` beside it names the script, as UTF-16 text up to a `"`, and that script is gone.
+ */
+export declare const installed: (dir: string, program: string) => boolean;
+/**
+ * - `kept`: the launcher is there and starts a tool that is installed.
+ * - `written`: it was missing, broken or in an older format, and now starts the running tool.
+ * - `foreign`: a `wcat` that cli-base did not write is there, and stays untouched.
+ * - `newer`: a newer cli-base wrote it; this one leaves it alone.
+ * - `failed`: it could not be written, such as a bin folder only an administrator may change.
+ */
+export type LauncherState = "kept" | "written" | "foreign" | "newer" | "failed";
+/**
+ * Makes sure the `wcat` launcher in `dir` starts an installed tool. It never prints and never throws: a tool calls it
+ * on every start, and a launcher it cannot write must not fail the tool's own command.
+ */
+export declare const ensureLauncher: ({ dir, program, platform, }: BinFolder & {
+    platform: NodeJS.Platform;
+}) => LauncherState;