@wirecat/cli-base 0.65.5 → 0.66.0

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-base",
-  "version": "0.65.5",
+  "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",