@wirecat/cli-base 0.65.4 → 0.66.0

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;

package/dist/wcat/launcher.js

@@ -0,0 +1,109 @@
+import { readFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { installerOf } from "../installer.js";
+import { PROGRAM_PREFIX } from "./names.js";
+import { exists, fileState, SHIM_FORMAT, shimFiles, writeShim } from "./shim.js";
+const posix = (path) => path.replaceAll("\\", "/");
+/** pnpm's global packages live under PNPM_HOME, whatever the folder is called; a project's own `.pnpm` does not. */
+const pnpmHome = (path, env) => {
+    const home = env.PNPM_HOME;
+    return home && path.startsWith(`${posix(home).replace(/\/+$/, "")}/`) ? home : undefined;
+};
+/** Where each package manager puts the commands of a global install, read from where the package itself lives. */
+const layoutFolders = (script, env) => {
+    const path = posix(script);
+    const home = pnpmHome(path, env);
+    // pnpm 12 puts global commands in $PNPM_HOME/bin, earlier versions in $PNPM_HOME itself.
+    if (home)
+        return [join(home, "bin"), home];
+    switch (installerOf(script)) {
+        case "bun":
+            return [`${path.slice(0, path.indexOf("/install/global/node_modules/"))}/bin`];
+        case "npm": {
+            const root = path.slice(0, path.indexOf("/node_modules/"));
+            // `<prefix>/lib/node_modules` with `<prefix>/bin` on Linux and macOS; `<prefix>/node_modules` beside the
+            // commands on Windows.
+            return [basename(root) === "lib" ? join(dirname(root), "bin") : root];
+        }
+        default:
+            return [];
+    }
+};
+/**
+ * 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 const binFolder = ({ name, argv1, script, env, platform }) => {
+    if (!["npm", "pnpm", "bun"].includes(installerOf(script)) && !pnpmHome(posix(script), env))
+        return undefined;
+    const extensions = platform === "win32" ? [".cmd", ".exe"] : [""];
+    const candidates = [argv1 ? dirname(argv1) : undefined, ...layoutFolders(script, env)];
+    for (const dir of new Set(candidates)) {
+        if (dir === undefined || basename(dir) === ".bin")
+            continue;
+        for (const extension of extensions) {
+            const program = `${PROGRAM_PREFIX}${name}${extension}`;
+            if (exists(join(dir, program)))
+                return { dir, program };
+        }
+    }
+    return 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 const installed = (dir, program) => {
+    if (!exists(join(dir, program)))
+        return false;
+    if (!program.toLowerCase().endsWith(".exe"))
+        return true;
+    let script;
+    try {
+        script =
+            readFileSync(join(dir, `${program.slice(0, -4)}.bunx`))
+                .toString("utf16le")
+                .split('"')[0] ?? "";
+    }
+    catch {
+        return true;
+    }
+    if (script === "" || exists(resolve(dir, script)))
+        return true;
+    // The relative path did not resolve; bun's default layout puts the packages in <BUN_INSTALL>/install/global.
+    const at = posix(script).lastIndexOf("/install/global/node_modules/");
+    return at < 0 || exists(join(dirname(dir), posix(script).slice(at + 1)));
+};
+const NAME = "wcat";
+/**
+ * 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 const ensureLauncher = ({ dir, program, platform, }) => {
+    try {
+        const mine = shimFiles("launcher", { dir, name: NAME, target: program, platform });
+        const states = mine.map((file) => fileState(file.path));
+        if (states.some((one) => one.state === "foreign"))
+            return "foreign";
+        const ours = states.flatMap((one) => (one.state === "ours" ? [one] : []));
+        if (ours.some(({ mark }) => mark.format > SHIM_FORMAT))
+            return "newer";
+        if (ours.some(({ mark }) => mark.kind !== "launcher"))
+            return "foreign";
+        // Keep the tool it starts while that tool is installed, so two tools never take turns rewriting it.
+        const current = ours.find(({ mark }) => installed(dir, mark.target))?.mark.target;
+        const wanted = shimFiles("launcher", { dir, name: NAME, target: current ?? program, platform });
+        const stale = wanted.filter((file, at) => {
+            const state = states[at];
+            return state?.state !== "ours" || state.text !== file.text;
+        });
+        if (stale.length === 0)
+            return "kept";
+        for (const file of stale)
+            writeShim(file);
+        return "written";
+    }
+    catch {
+        return "failed";
+    }
+};

package/dist/wcat/names.d.ts

@@ -0,0 +1,16 @@
+/** WireCat's own tools: `wcat --help` names each one that is missing with the command that installs it. */
+export declare const FIRST_PARTY_TOOLS: readonly {
+    name: string;
+    package?: string;
+}[];
+/** `wcat` answers these itself, so a `wcat-<name>` program can never take one over. */
+export declare const BUILT_IN_COMMANDS: readonly ["help", "version", "shortcuts", "doctor", "update", "upgrade", "app"];
+/** Names a third-party CLI must not take: WireCat's tools, the built-in commands and `wcat` itself. */
+export declare const RESERVED_NAMES: readonly string[];
+/** A tool name `wcat` runs: lower case, as a command word and a file name on every system. */
+export declare const TOOL_NAME: RegExp;
+export declare const PROGRAM_PREFIX = "wcat-";
+/** The first argument `wcat-<name> --wcat-describe` answers with its JSON description. */
+export declare const DESCRIBE_FLAG = "--wcat-describe";
+/** The first argument the `wcat` launcher passes, so the tool runs `wcat` instead of its own program. */
+export declare const DISPATCH_FLAG = "--wcat-dispatch";

package/dist/wcat/names.js

@@ -0,0 +1,27 @@
+/** WireCat's own tools: `wcat --help` names each one that is missing with the command that installs it. */
+export const FIRST_PARTY_TOOLS = [
+    { name: "tg", package: "@wirecat/tg-cli" },
+    { name: "max", package: "@wirecat/max-cli" },
+    { name: "wa", package: "@wirecat/whatsapp-cli" },
+    { name: "zm", package: "@wirecat/zoom-cli" },
+    { name: "drive", package: "@wirecat/drive-cli" },
+    { name: "memo", package: "@wirecat/cli-memo" },
+    { name: "mail", package: "@wirecat/mail-cli" },
+    // memo reads email today; the name is held for a tool of its own.
+    { name: "email" },
+];
+/** `wcat` answers these itself, so a `wcat-<name>` program can never take one over. */
+export const BUILT_IN_COMMANDS = ["help", "version", "shortcuts", "doctor", "update", "upgrade", "app"];
+/** Names a third-party CLI must not take: WireCat's tools, the built-in commands and `wcat` itself. */
+export const RESERVED_NAMES = [
+    ...FIRST_PARTY_TOOLS.map((tool) => tool.name),
+    ...BUILT_IN_COMMANDS,
+    "wcat",
+];
+/** A tool name `wcat` runs: lower case, as a command word and a file name on every system. */
+export const TOOL_NAME = /^[a-z][a-z0-9-]{0,39}$/;
+export const PROGRAM_PREFIX = "wcat-";
+/** The first argument `wcat-<name> --wcat-describe` answers with its JSON description. */
+export const DESCRIBE_FLAG = "--wcat-describe";
+/** The first argument the `wcat` launcher passes, so the tool runs `wcat` instead of its own program. */
+export const DISPATCH_FLAG = "--wcat-dispatch";

package/dist/wcat/path.d.ts

@@ -0,0 +1,15 @@
+/** The system `wcat` runs on and the variables it searches; tests pass another platform's. */
+export interface SearchEnv {
+    env: NodeJS.ProcessEnv;
+    platform: NodeJS.Platform;
+}
+/** Each folder once: a folder listed twice is one program, not two. */
+export declare const pathEntries: ({ env, platform }: SearchEnv) => string[];
+/** The endings Windows runs without being told, `.cmd` before `.ps1` when PATHEXT says so; none elsewhere. */
+export declare const programExtensions: ({ env, platform }: SearchEnv) => string[];
+/** Every `command` on PATH, in PATH order, one file per folder: the first ending Windows would run. */
+export declare const findOnPath: (command: string, search: SearchEnv) => string[];
+/** Every `wcat-<name>` program on PATH by name, each with its files in PATH order. */
+export declare const findTools: (search: SearchEnv) => Map<string, string[]>;
+/** Names `wcat` answers itself; a `wcat-<name>` program with one of them never runs through `wcat`. */
+export declare const isBuiltIn: (name: string) => boolean;

package/dist/wcat/path.js

@@ -0,0 +1,83 @@
+import { readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { BUILT_IN_COMMANDS, PROGRAM_PREFIX, TOOL_NAME } from "./names.js";
+const variable = (env, name, platform) => platform === "win32" ? Object.entries(env).find(([key]) => key.toUpperCase() === name)?.[1] : env[name];
+/** Each folder once: a folder listed twice is one program, not two. */
+export const pathEntries = ({ env, platform }) => {
+    const raw = variable(env, "PATH", platform) ?? "";
+    const entries = raw.split(platform === "win32" ? ";" : ":").map((entry) => entry.replace(/^"(.*)"$/, "$1"));
+    const seen = new Set();
+    return entries.filter((entry) => {
+        const key = platform === "win32" ? entry.toLowerCase().replace(/[\\/]+$/, "") : entry.replace(/\/+$/, "");
+        if (entry === "" || seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+};
+/** The endings Windows runs without being told, `.cmd` before `.ps1` when PATHEXT says so; none elsewhere. */
+export const programExtensions = ({ env, platform }) => platform === "win32"
+    ? (variable(env, "PATHEXT", platform) ?? ".COM;.EXE;.BAT;.CMD")
+        .split(";")
+        .filter((ext) => /^\.[a-z0-9]+$/i.test(ext))
+        .map((ext) => ext.toLowerCase())
+    : [""];
+const isProgram = (path, platform) => {
+    try {
+        const stat = statSync(path);
+        return stat.isFile() && (platform === "win32" || (stat.mode & 0o111) !== 0);
+    }
+    catch {
+        return false;
+    }
+};
+/** Every `command` on PATH, in PATH order, one file per folder: the first ending Windows would run. */
+export const findOnPath = (command, search) => {
+    const extensions = programExtensions(search);
+    return pathEntries(search).flatMap((dir) => {
+        for (const extension of extensions) {
+            const path = join(dir, command + extension);
+            if (isProgram(path, search.platform))
+                return [path];
+        }
+        return [];
+    });
+};
+/** Every `wcat-<name>` program on PATH by name, each with its files in PATH order. */
+export const findTools = (search) => {
+    const extensions = programExtensions(search);
+    const tools = new Map();
+    for (const dir of pathEntries(search)) {
+        let files;
+        try {
+            files = readdirSync(dir);
+        }
+        catch {
+            continue;
+        }
+        const here = new Map();
+        for (const file of files) {
+            if (!(search.platform === "win32" ? file.toLowerCase() : file).startsWith(PROGRAM_PREFIX))
+                continue;
+            const extension = extensions.find((ext) => ext !== "" && file.toLowerCase().endsWith(ext)) ?? "";
+            if (search.platform === "win32" && extension === "")
+                continue;
+            const base = search.platform === "win32" ? file.toLowerCase() : file;
+            const name = base.slice(PROGRAM_PREFIX.length, base.length - extension.length);
+            if (!TOOL_NAME.test(name))
+                continue;
+            const best = here.get(name);
+            const rank = (path) => extensions.findIndex((ext) => path.toLowerCase().endsWith(ext));
+            const path = join(dir, file);
+            if (best !== undefined && rank(best) <= rank(path))
+                continue;
+            if (isProgram(path, search.platform))
+                here.set(name, path);
+        }
+        for (const [name, path] of here)
+            tools.set(name, [...(tools.get(name) ?? []), path]);
+    }
+    return new Map([...tools].sort(([a], [b]) => (a < b ? -1 : 1)));
+};
+/** Names `wcat` answers itself; a `wcat-<name>` program with one of them never runs through `wcat`. */
+export const isBuiltIn = (name) => name === "wcat" || BUILT_IN_COMMANDS.includes(name);

package/dist/wcat/probe.d.ts

@@ -0,0 +1,11 @@
+import { type WcatTool } from "./describe.js";
+/**
+ * Asks one program to describe itself. Any program can sit on PATH under a `wcat-` name, so it gets no input, a time
+ * limit and a cap on what it may print, and its failure only means "no description".
+ */
+export declare const probeDescribe: (path: string, { env, timeoutMs }: {
+    env: NodeJS.ProcessEnv;
+    timeoutMs: number;
+}) => Promise<Omit<WcatTool, "command"> | undefined>;
+/** cli-base's own version, read only when `wcat --version` asks; `unknown` from a bundle that left the file behind. */
+export declare const baseVersion: () => string;

package/dist/wcat/probe.js

@@ -0,0 +1,58 @@
+import { readFileSync } from "node:fs";
+import crossSpawn from "cross-spawn";
+import { parseDescribe } from "./describe.js";
+import { DESCRIBE_FLAG } from "./names.js";
+const MAX_ANSWER_BYTES = 64 * 1024;
+/**
+ * Asks one program to describe itself. Any program can sit on PATH under a `wcat-` name, so it gets no input, a time
+ * limit and a cap on what it may print, and its failure only means "no description".
+ */
+export const probeDescribe = (path, { env, timeoutMs }) => new Promise((resolve) => {
+    let child;
+    try {
+        child = crossSpawn(path, [DESCRIBE_FLAG], { stdio: ["ignore", "pipe", "ignore"], env, windowsHide: true });
+    }
+    catch {
+        resolve(undefined);
+        return;
+    }
+    const chunks = [];
+    let size = 0;
+    let settled = false;
+    // On Windows the child is cmd.exe and node is its child: killing cmd.exe leaves node holding the pipe, so "close"
+    // could wait for it. Giving up never waits for "close".
+    const settle = (answer) => {
+        if (settled)
+            return;
+        settled = true;
+        clearTimeout(timer);
+        resolve(answer);
+    };
+    const giveUp = () => {
+        child.kill();
+        child.stdout?.destroy();
+        child.unref();
+        settle(undefined);
+    };
+    const timer = setTimeout(giveUp, timeoutMs);
+    child.stdout?.on("data", (chunk) => {
+        size += chunk.length;
+        if (size > MAX_ANSWER_BYTES)
+            giveUp();
+        else
+            chunks.push(chunk);
+    });
+    child.once("error", () => settle(undefined));
+    child.once("close", (code) => settle(code === 0 ? parseDescribe(Buffer.concat(chunks).toString("utf8")) : undefined));
+});
+/** cli-base's own version, read only when `wcat --version` asks; `unknown` from a bundle that left the file behind. */
+export const baseVersion = () => {
+    try {
+        const raw = readFileSync(new URL("../../package.json", import.meta.url), "utf8");
+        const { name, version } = JSON.parse(raw);
+        return name === "@wirecat/cli-base" && typeof version === "string" ? version : "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+};

package/dist/wcat/shim.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The small files cli-base writes into a bin folder: the `wcat` launcher and the short-name shortcuts. Each starts a
+ * program in the same folder by its stable name (`wcat-tg`), never a file inside a package: pnpm keeps packages in
+ * folders named after their version, so a link into one breaks on the first upgrade.
+ *
+ * Every file carries a mark line, so cli-base can tell its own files from anyone else's and never touches the rest.
+ */
+export declare const SHIM_FORMAT = 1;
+export type ShimKind = "launcher" | "shortcut";
+export interface ShimMark {
+    format: number;
+    kind: ShimKind;
+    /** The program it starts, a file name in the same folder: `wcat-tg`, `wcat-tg.cmd`. */
+    target: string;
+}
+export interface ShimFile {
+    path: string;
+    text: string;
+}
+/**
+ * The files of one shim: `<name>` on Linux and macOS; `<name>.cmd` and `<name>.ps1` on Windows, the pair npm writes
+ * for its own commands. The POSIX file names the folder in full, so a link to it from elsewhere still works; the
+ * Windows pair finds the folder from where it is, as npm's own wrappers do.
+ */
+export declare const shimFiles: (kind: ShimKind, { dir, name, target, platform }: {
+    dir: string;
+    name: string;
+    target: string;
+    platform: NodeJS.Platform;
+}) => ShimFile[];
+export declare const parseShim: (text: string) => ShimMark | undefined;
+export type FileState = {
+    state: "missing";
+} | {
+    state: "ours";
+    mark: ShimMark;
+    text: string;
+} | {
+    state: "foreign";
+};
+/** What sits at `path`: nothing, one of our shims, or a file or link that belongs to someone else. */
+export declare const fileState: (path: string) => FileState;
+export declare const exists: (path: string) => boolean;
+/** Written beside the target and renamed over it, so two tools starting at once never leave half a file. */
+export declare const writeShim: ({ path, text }: ShimFile) => void;