@wirecat/cli-base 0.65.5 → 0.66.1

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;

package/dist/wcat/shim.js

@@ -0,0 +1,104 @@
+import { lstatSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { DISPATCH_FLAG } from "./names.js";
+/**
+ * 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 const SHIM_FORMAT = 1;
+const MARK = /^(?:#|REM) wirecat-shim (\d+) (launcher|shortcut) (\S+)\r?$/m;
+const NOTE = {
+    launcher: "Written by @wirecat/cli-base. Any WireCat tool rewrites it when it breaks; it is safe to delete.",
+    shortcut: "Made by `wcat shortcuts add`; `wcat shortcuts remove` takes it out.",
+};
+const shellQuote = (text) => `'${text.replaceAll("'", `'\\''`)}'`;
+/**
+ * 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 const shimFiles = (kind, { dir, name, target, platform }) => {
+    const mark = `wirecat-shim ${SHIM_FORMAT} ${kind} ${target}`;
+    const extra = kind === "launcher" ? ` ${DISPATCH_FLAG}` : "";
+    if (platform !== "win32")
+        return [
+            {
+                path: join(dir, name),
+                text: `#!/bin/sh\n# ${mark}\n# ${NOTE[kind]}\nexec ${shellQuote(join(dir, target))}${extra} "$@"\n`,
+            },
+        ];
+    return [
+        {
+            path: join(dir, `${name}.cmd`),
+            text: ["@ECHO off", `REM ${mark}`, `REM ${NOTE[kind]}`, `"%~dp0${target}"${extra} %*`, ""].join("\r\n"),
+        },
+        {
+            path: join(dir, `${name}.ps1`),
+            text: [
+                `# ${mark}`,
+                `# ${NOTE[kind]}`,
+                // PowerShell hands a .cmd its arguments unquoted, so `a&b` would run `b`; npm and pnpm write a .ps1 beside
+                // their .cmd, and it is started instead whenever it is there.
+                `$stem = Join-Path $PSScriptRoot "${target.replace(/\.(cmd|exe|bat)$/i, "")}"`,
+                `$target = if (Test-Path -LiteralPath "$stem.ps1") { "$stem.ps1" } else { Join-Path $PSScriptRoot "${target}" }`,
+                "if ($MyInvocation.ExpectingInput) {",
+                `  $input | & $target${extra} @args`,
+                "} else {",
+                `  & $target${extra} @args`,
+                "}",
+                "exit $LASTEXITCODE",
+                "",
+            ].join("\r\n"),
+        },
+    ];
+};
+export const parseShim = (text) => {
+    const found = MARK.exec(text.split("\n", 3).join("\n"));
+    if (!found)
+        return undefined;
+    return { format: Number(found[1]), kind: found[2], target: found[3] };
+};
+/** A shim file is a few hundred bytes; anything larger is not one of ours and is not read. */
+const MAX_SHIM_BYTES = 4096;
+/** What sits at `path`: nothing, one of our shims, or a file or link that belongs to someone else. */
+export const fileState = (path) => {
+    let stat;
+    try {
+        stat = lstatSync(path);
+    }
+    catch (error) {
+        return error.code === "ENOENT" ? { state: "missing" } : { state: "foreign" };
+    }
+    if (!stat.isFile() || stat.size > MAX_SHIM_BYTES)
+        return { state: "foreign" };
+    try {
+        const text = readFileSync(path, "utf8");
+        const mark = parseShim(text);
+        return mark ? { state: "ours", mark, text } : { state: "foreign" };
+    }
+    catch {
+        return { state: "foreign" };
+    }
+};
+export const exists = (path) => {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+};
+/** Written beside the target and renamed over it, so two tools starting at once never leave half a file. */
+export const writeShim = ({ path, text }) => {
+    const temporary = `${path}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+    try {
+        writeFileSync(temporary, text, { mode: 0o755 });
+        renameSync(temporary, path);
+    }
+    finally {
+        rmSync(temporary, { force: true });
+    }
+};

package/dist/wcat/shortcuts.d.ts

@@ -0,0 +1,31 @@
+import { type SearchEnv } from "./path.js";
+/**
+ * - `made`: the short name is a shortcut cli-base made, and `remove` may take it out.
+ * - `free`: no program on PATH has the name, so `add` may make it.
+ * - `package`: the tool's package installs the short name itself; the package manager owns it.
+ * - `taken`: another program has the name; it is never touched.
+ */
+export type ShortcutStatus = "made" | "free" | "package" | "taken";
+export interface Shortcut {
+    /** The short name, which is also the tool's name: `tg`. */
+    name: string;
+    status: ShortcutStatus;
+    /** The file that has the name, for every status but `free`. */
+    path?: string;
+    /** The `wcat-<name>` program the shortcut starts. */
+    program: string;
+}
+export interface ShortcutChange extends Shortcut {
+    changed: boolean;
+}
+/** Every installed `wcat-<name>` program by name, the first on PATH for each, built-in names left out. */
+export declare const installedPrograms: (search: SearchEnv) => Map<string, string[]>;
+/** The short name of each installed tool, or of the tools named: made, free, installed by the package or taken. */
+export declare const listShortcuts: (search: SearchEnv, names?: readonly string[]) => Shortcut[];
+/**
+ * Makes a shortcut for each free name, in the folder of the program it starts. Only a name no program on PATH has is
+ * made, so a shortcut never hides another program and never sits in front of one.
+ */
+export declare const addShortcuts: (search: SearchEnv, names?: readonly string[]) => ShortcutChange[];
+/** Removes the shortcuts cli-base made; a file it did not make stays, whatever its name. */
+export declare const removeShortcuts: (search: SearchEnv, names?: readonly string[]) => ShortcutChange[];

package/dist/wcat/shortcuts.js

@@ -0,0 +1,105 @@
+import { closeSync, openSync, readSync, realpathSync, rmSync } from "node:fs";
+import { basename, dirname } from "node:path";
+import { CliError } from "../errors.js";
+import { findOnPath, findTools, isBuiltIn } from "./path.js";
+import { fileState, shimFiles, writeShim } from "./shim.js";
+const WIRECAT_PACKAGE = /node_modules[\\/]+@wirecat[\\/]/;
+/** A link into an `@wirecat/*` package, or a package manager's wrapper that starts one (npm on Windows, pnpm). */
+const isWirecatPackage = (path) => {
+    try {
+        if (WIRECAT_PACKAGE.test(realpathSync(path)))
+            return true;
+        const buffer = Buffer.alloc(16 * 1024);
+        const fd = openSync(path, "r");
+        try {
+            const read = readSync(fd, buffer, 0, buffer.length, 0);
+            return WIRECAT_PACKAGE.test(buffer.subarray(0, read).toString("latin1"));
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    catch {
+        return false;
+    }
+};
+const ourShortcut = (path) => {
+    const state = fileState(path);
+    return state.state === "ours" && state.mark.kind === "shortcut";
+};
+const statusOf = (name, program, search) => {
+    const files = shimFiles("shortcut", {
+        dir: dirname(program),
+        name,
+        target: basename(program),
+        platform: search.platform,
+    });
+    const named = findOnPath(name, search);
+    const made = [...files.map((file) => file.path), ...named].find(ourShortcut);
+    if (made)
+        return { name, status: "made", path: made, program };
+    const first = named[0];
+    if (first === undefined)
+        return { name, status: "free", program };
+    return { name, status: isWirecatPackage(first) ? "package" : "taken", path: first, program };
+};
+/** A bin folder only an administrator may change is the usual cause, and the person can act on it. */
+const changeFile = (path, change) => {
+    try {
+        change();
+    }
+    catch (error) {
+        throw new CliError("permission_error", `could not change ${path}: ${error.code ?? error}`, {
+            reason: "access.denied",
+        });
+    }
+};
+/** Every installed `wcat-<name>` program by name, the first on PATH for each, built-in names left out. */
+export const installedPrograms = (search) => new Map([...findTools(search)].filter(([name]) => !isBuiltIn(name)));
+const chosen = (names, search) => {
+    const installed = installedPrograms(search);
+    if (names === undefined || names.length === 0)
+        return [...installed].map(([name, paths]) => [name, paths[0]]);
+    const missing = names.filter((name) => !installed.has(name));
+    if (missing.length > 0)
+        throw new CliError("not_found", `not installed: ${missing.map((name) => `wcat-${name}`).join(", ")}`, {
+            reason: "tool.not-installed",
+            tool: missing[0],
+            installed: [...installed.keys()],
+        });
+    return [...new Set(names)].map((name) => [name, installed.get(name)[0]]);
+};
+/** The short name of each installed tool, or of the tools named: made, free, installed by the package or taken. */
+export const listShortcuts = (search, names) => chosen(names, search).map(([name, program]) => statusOf(name, program, search));
+/**
+ * Makes a shortcut for each free name, in the folder of the program it starts. Only a name no program on PATH has is
+ * made, so a shortcut never hides another program and never sits in front of one.
+ */
+export const addShortcuts = (search, names) => listShortcuts(search, names).map((shortcut) => {
+    if (shortcut.status !== "free")
+        return { ...shortcut, changed: false };
+    const files = shimFiles("shortcut", {
+        dir: dirname(shortcut.program),
+        name: shortcut.name,
+        target: basename(shortcut.program),
+        platform: search.platform,
+    });
+    for (const file of files)
+        changeFile(file.path, () => writeShim(file));
+    return { ...shortcut, status: "made", path: files[0]?.path, changed: true };
+});
+/** Removes the shortcuts cli-base made; a file it did not make stays, whatever its name. */
+export const removeShortcuts = (search, names) => listShortcuts(search, names).map((shortcut) => {
+    if (shortcut.status !== "made")
+        return { ...shortcut, changed: false };
+    const files = shimFiles("shortcut", {
+        dir: dirname(shortcut.path),
+        name: shortcut.name,
+        target: basename(shortcut.program),
+        platform: search.platform,
+    });
+    for (const file of files)
+        if (ourShortcut(file.path))
+            changeFile(file.path, () => rmSync(file.path, { force: true }));
+    return { ...statusOf(shortcut.name, shortcut.program, search), changed: true };
+});