@wirecat/cli-base 0.65.4 → 0.66.0

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 };
+});

package/dist/wcat/start.d.ts

@@ -0,0 +1,38 @@
+import { type WcatTool } from "./describe.js";
+import { type LauncherState } from "./launcher.js";
+export interface WcatStartIo {
+    /** `process.argv`: the runtime, the script, then the words. */
+    argv: readonly string[];
+    env: NodeJS.ProcessEnv;
+    platform: NodeJS.Platform;
+    stdout: {
+        write: (text: string) => unknown;
+        isTTY?: boolean;
+    };
+    stderr: {
+        write: (text: string) => unknown;
+        isTTY?: boolean;
+    };
+    /** A file of the installed package, links resolved; cli-base's own file, which sits in the same install. */
+    script: string;
+}
+export interface WcatStart {
+    /** The exit code when `wcat` handled this start (`--wcat-describe`, or dispatch mode); `undefined` otherwise. */
+    code?: number;
+    /** What happened to the `wcat` launcher on a normal start; `undefined` when the tool is not a global install. */
+    launcher?: LauncherState;
+}
+/**
+ * The first call in a CLI's bin, before its program loads:
+ *
+ * ```ts
+ * const { code } = await wcatStart({ command: "tg", version, description })
+ * if (code !== undefined) process.exitCode = code
+ * else await startCli(…)
+ * ```
+ *
+ * - `wcat-tg --wcat-describe` prints the tool's description as JSON for `wcat --help`.
+ * - `wcat-tg --wcat-dispatch …`, which only the launcher passes, runs `wcat …`.
+ * - Any other start makes sure the `wcat` launcher in the tool's bin folder works: a few `stat` calls when it does.
+ */
+export declare const wcatStart: (tool: WcatTool, io?: Partial<WcatStartIo>) => Promise<WcatStart>;

package/dist/wcat/start.js

@@ -0,0 +1,45 @@
+/**
+ * The part of `wcat` a CLI loads on every start, kept to Node built-ins: answering `--wcat-describe`, handing over to
+ * the dispatcher when the launcher asks, and otherwise checking the `wcat` launcher with a few `stat` calls.
+ */
+import { fileURLToPath } from "node:url";
+import { describeAnswer } from "./describe.js";
+import { binFolder, ensureLauncher } from "./launcher.js";
+import { DESCRIBE_FLAG, DISPATCH_FLAG } from "./names.js";
+/**
+ * The first call in a CLI's bin, before its program loads:
+ *
+ * ```ts
+ * const { code } = await wcatStart({ command: "tg", version, description })
+ * if (code !== undefined) process.exitCode = code
+ * else await startCli(…)
+ * ```
+ *
+ * - `wcat-tg --wcat-describe` prints the tool's description as JSON for `wcat --help`.
+ * - `wcat-tg --wcat-dispatch …`, which only the launcher passes, runs `wcat …`.
+ * - Any other start makes sure the `wcat` launcher in the tool's bin folder works: a few `stat` calls when it does.
+ */
+export const wcatStart = async (tool, io = {}) => {
+    const argv = io.argv ?? process.argv;
+    const env = io.env ?? process.env;
+    const platform = io.platform ?? process.platform;
+    const stdout = io.stdout ?? process.stdout;
+    const [first, ...rest] = argv.slice(2);
+    if (first === DESCRIBE_FLAG) {
+        stdout.write(`${JSON.stringify(describeAnswer(tool))}\n`);
+        return { code: 0 };
+    }
+    if (first === DISPATCH_FLAG) {
+        const { runWcat } = await import("./dispatch.js");
+        const code = await runWcat(rest, { env, platform, stdout, stderr: io.stderr ?? process.stderr, self: tool });
+        return { code };
+    }
+    const folder = binFolder({
+        name: tool.command,
+        argv1: argv[1],
+        script: io.script ?? fileURLToPath(import.meta.url),
+        env,
+        platform,
+    });
+    return folder ? { launcher: ensureLauncher({ ...folder, platform }) } : {};
+};

package/docs/standards/README.md

@@ -29,7 +29,7 @@ the four steps that need a person. A new CLI is ready for its first release when
 |---|---|---:|---|
 | [Toolchain](toolchain.md) | `TOOL` | 20 | TypeScript, Biome, grit plugins, size caps, import cycles, spelling, Markdown, Go |
 | [Layout](layout.md) | `LAY` | 10 | Repository layout, entry points, exports, file size, one job per file, splitting a unit, the bundled bin |
-| [Commands](commands.md) | `CMD` | 28 | Paths, vocabulary, flags, arguments, effects, lifetime, query, help, external references |
+| [Commands](commands.md) | `CMD` | 29 | Paths, vocabulary, flags, arguments, effects, lifetime, query, help, external references, joining `wcat` |
 | [Output](output.md) | `OUT` | 23 | Data on stdout only, envelopes, errors, exit codes, partial answers, projection |
 | [MCP](mcp.md) | `MCP` | 13 | The MCP tools, how they come from commands, what each permission shows |
 | [Accounts](accounts.md) | `ACCT` | 12 | The explicit profile, reads across accounts, scope flags, linked identities, sign-in commands |

package/docs/standards/commands.md

@@ -7,7 +7,7 @@ lifetime it declares, the entity it prints, the query language for lists, the `m
 
 Rule ids on this page are `WC-CMD-<n>`. How to read a rule, how ids work and which rule wins are in the
 [index](README.md). What a command prints is on the [output](output.md) page. How long it runs and how it ends is on
-the [lifecycle](lifecycle.md) page.
+the [lifecycle](lifecycle.md) page. How a CLI joins the `wcat` command is under "Joining `wcat`" below.
 
 The words themselves are not copied here. They live in the cli-base registries, and `cli-dev lint` reads them from
 there:
@@ -360,6 +360,25 @@ The references, each for its own part:
   requirement.
 - **Applies to:** all CLIs. **Since:** cli-base 0.43.0. **Rulings:** none.
 
+## Joining `wcat`
+
+### WC-CMD-29 · Answer `--wcat-describe`, and take no name WireCat reserves
+
+- **Why:** `wcat <name>` runs any `wcat-<name>` program on PATH, and `wcat --help` lists each one with what it says
+  about itself. A name WireCat reserves would be taken over by WireCat's own tool or by a `wcat` command.
+- **Enforced by:** `src/dev/wcat-lint.ts`.
+- **Example:** the bin's first call is `wcatStart({ command: "gcal", version, description, docs })` from
+  `@wirecat/cli-base/wcat/start`. `wcat-gcal --wcat-describe` then prints
+  `{"wcat_describe":1,"name":"gcal","version":"1.2.0","description":"…","docs_url":"…"}`. `cli-dev lint` warns when a
+  `"bin"` key does not start with `wcat-`, when a package outside `@wirecat/` takes a name from `RESERVED_NAMES` in
+  `@wirecat/cli-base/wcat` (`tg`, `max`, `wa`, `zm`, `drive`, `memo`, `mail`, `email`, `wcat` and the built-in commands
+  `help`, `version`, `shortcuts`, `doctor`, `update`, `upgrade`, `app`), and, with `--cli`, when the built CLI does not
+  answer `--wcat-describe`.
+- **Exceptions:** a CLI keeps its short `"bin"` name beside `wcat-<name>` until callers have moved to the new name; the
+  warning stays until then.
+- **Applies to:** all CLIs, and third-party CLIs that join `wcat`. **Since:** cli-base 0.66.0. **Rulings:** NEED-149,
+  NEED-153, NEED-154.
+
 ## Sources
 
 These documents explain the rules on this page in more detail. Where one of them disagrees with this page, this page

package/docs/standards/new-cli.md

@@ -70,6 +70,32 @@ A template-owned page that is wrong for this CLI is a gap in cli-template, under
 wrong sentence: fix it there, and `upgrade` brings the fix. Change it in the CLI only where the CLI must differ for
 good; `upgrade` then asks before it touches the change.
 
+## Naming the CLI and joining `wcat`
+
+`wcat <name> …` runs a command named `wcat-<name>` from PATH, the way `git foo` runs `git-foo`. Any CLI joins by
+installing that command; nothing else is registered anywhere.
+
+- **The name.** Lower-case letters, digits and `-`, starting with a letter. WireCat reserves its own tools' names and
+  `wcat`'s built-in commands: `RESERVED_NAMES` in `@wirecat/cli-base/wcat` holds the list, and
+  [WC-CMD-29](commands.md#wc-cmd-29--answer---wcat-describe-and-take-no-name-wirecat-reserves) asks a CLI outside
+  WireCat not to take one.
+- **The command.** `"bin": { "wcat-<name>": "dist/bin/<name>.js" }`. `cli-dev lint` warns about a `"bin"` key without
+  the `wcat-` prefix. The template still writes the short name, and moves to `wcat-<name>` in a later release.
+- **The description `wcat --help` shows.** Call `wcatStart` first in the bin, before the program loads:
+
+  ```ts
+  import { wcatStart } from "@wirecat/cli-base/wcat/start"
+
+  const { code } = await wcatStart({ command: "gcal", version, description, docs: "https://example.com/gcal" })
+  if (code !== undefined) process.exitCode = code
+  else await startCli(…)
+  ```
+
+  It answers `--wcat-describe`, runs `wcat` when the `wcat` launcher starts the tool, and on any other start makes sure
+  the `wcat` launcher in the tool's bin folder works. `cli-dev lint --cli` warns when the built CLI does not answer.
+- **The short name.** `wcat shortcuts add <name>` makes `<name>` a shortcut to `wcat-<name>`, only when no program on
+  PATH has that name. A CLI does not install its short name itself.
+
 ## Four steps that need a person
 
 `new` prints these at the end.

package/docs/standards/security.md

@@ -68,7 +68,8 @@ name. Any other top-level key is written as `[not allowed]`. A key that names co
 
 cli-base's `Credentials` reads the environment variable first (for CI), then the OS keyring, then a file with mode
 `0600`. The keyring service is the CLI's app name, `appName` in its identity (`max-cli`, `gcal-cli`, `cli-memo`), not
-the command word people type (`max`, `gcal`). A run with moved folders uses the same entry and never deletes it
+the command word people type (`max`, `gcal`). A run with moved folders reads the same entry, writes a temporary one,
+and never replaces or deletes the owner's
 ([WC-SECR-24](#wc-secr-24--a-run-with-moved-folders-shares-the-owners-keyring-entry-and-never-deletes-it)).
 
 - **Why:** the keyring is the safest store on the computer.
@@ -327,23 +328,36 @@ store and runs no search. A CLI declares its provider and may replace any step.
 
 ### WC-SECR-24 · A run with moved folders shares the owner's keyring entry and never deletes it
 
-- **Why:** a per-folder keyring entry (`<app>:<config folder>`) left one copy of a sign-in for every test run, agent
-  check or worktree, about 1,500 of them in the owner's keyring, and nothing removed them. One entry per computer is
-  enough. But a moved run then reaches the owner's real sign-in: `HOME=/tmp/x gcal personal session end` deleted the
-  owner's Google sign-in, because only `<PREFIX>_*_DIR` counted as moved (a security review, 2026-10-30).
+- **Why:** a per-folder keyring entry (`<app>:<config folder>`) for every run left one copy of a sign-in for every test
+  run, agent check or worktree, about 1,500 of them in the owner's keyring, and nothing removed them. One entry per
+  computer is enough. But a moved run then reaches the owner's real sign-in: `HOME=/tmp/x gcal personal session end`
+  deleted the owner's Google sign-in, because only `<PREFIX>_*_DIR` counted as moved (a security review, 2026-10-30),
+  and `session start` in a worktree replaced it.
 - **Enforced by:** `src/credentials.test.ts` · `src/paths.test.ts`.
 - **Example:** a run is moved when `isMovedRun({ appName, prefix, env })` is true: a `<PREFIX>_CONFIG_DIR`,
   `_STATE_DIR` or `_CACHE_DIR` override, or a `HOME` or XDG folder that puts the default folders anywhere but under
-  the account's own home. A CLI passes that as `isolated`. `Credentials` then reads and writes the app's own entry
-  (`<app>` / `oauth:<provider>:<profile>`), as a run with the default folders does. With the system keyring, its
-  `remove` keeps that entry, warns on stderr and leaves `"keyring"` out of what it returns; a moved `HOME` or XDG
-  folder in its `env` counts even when `isolated` is false. A CLI checks `isMovedRun` before it revokes a sign-in at
-  the provider, and says so when `session end` removed nothing. A test passes `memoryKeyring()`; a run that must not
-  see the keyring at all also runs with `DBUS_SESSION_BUS_ADDRESS` removed, since the keyring is reached over D-Bus.
-- **Exceptions:** a write from a moved run, such as `session start` in a worktree, replaces the owner's entry.
-- **Applies to:** every CLI, its tests and every agent that runs a CLI. **Since:** cli-base 0.65.4.
-  **Rulings:** owner, 2026-10-29 (sign-ins copied per work folder should have reused the existing entry); owner,
-  2026-10-30 (share the keyring entry, do not multiply it).
+  the account's own home. A CLI passes that as `isolated`; a moved `HOME` or XDG folder in `env` counts even when
+  `isolated` is false. With the system keyring, `Credentials` in a moved run:
+  - **writes** only a temporary entry, `movedRunService(app, configDir)` = `<app>:<absolute config folder>`, never the
+    owner's `<app>` entry;
+  - **reads** that temporary entry first and the owner's `<app>` entry when it has none, so a moved run still uses
+    the owner's sign-in;
+  - **removes** only the temporary entry, warns on stderr that the owner's was kept, and returns `"keyring"` only when
+    a temporary entry was there. `session end` in a moved run therefore cleans up after `session start`.
+
+  A CLI never revokes a sign-in at the provider in a moved run, even one read from the temporary entry: a refreshed
+  token is still the owner's grant. A test passes `memoryKeyring()`; a run that must not see the keyring at all also
+  runs with `DBUS_SESSION_BUS_ADDRESS` removed, since the keyring is reached over D-Bus.
+- **Cleanup:** a moved run that never reaches `session end` leaves its temporary entry, and so does one that refreshes
+  a token, since the refreshed token is written there. `bin/keyring-dedupe --delete` in the projects folder removes
+  temporary entries that sit beside the owner's real one; a test or agent can also delete one by name with
+  `movedRunService`. When only `<PREFIX>_STATE_DIR` or `_CACHE_DIR` is moved, the temporary entry is named after the
+  owner's own config folder, which `keyring-dedupe` treats as a real entry: remove it with `session end`.
+- **Exceptions:** none.
+- **Applies to:** every CLI, its tests and every agent that runs a CLI. **Since:** cli-base 0.65.4 (temporary entry:
+  0.65.5). **Rulings:** owner, 2026-10-29 (sign-ins copied per work folder should have reused the existing entry);
+  owner, 2026-10-30 (share the keyring entry, do not multiply it); owner, 2026-10-31 (do not replace it: a test of a
+  new session writes a temporary entry and cleans it up).
 
 ## Sources
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-base",
-  "version": "0.65.4",
+  "version": "0.66.0",
   "description": "The parts every command line tool needs: output modes, terminal rendering, error model, exit codes, credentials, clocks",
   "license": "Apache-2.0",
   "author": "Viacheslav Ptsarev",
@@ -90,6 +90,14 @@
       "types": "./dist/standards/tables.d.ts",
       "default": "./dist/standards/tables.js"
     },
+    "./wcat": {
+      "types": "./dist/wcat/index.d.ts",
+      "default": "./dist/wcat/index.js"
+    },
+    "./wcat/start": {
+      "types": "./dist/wcat/start.d.ts",
+      "default": "./dist/wcat/start.js"
+    },
     "./biome": "./config/biome.base.json",
     "./tsconfig.base.json": "./config/tsconfig.base.json",
     "./tsconfig.test.json": "./config/tsconfig.test.json",