@wirecat/cli-base 0.63.0 → 0.64.0

package/CHANGELOG.md

@@ -8,6 +8,119 @@ Versions before 0.8.0 are in the [git tags](https://github.com/WireCatLabs/cli-b
 Every entry says what changed as a caller sees it, why, and what to watch for — the rules are
 [`docs/dev/CONVENTIONS.md`](docs/dev/CONVENTIONS.md#the-changelog).
 
+## 0.64.0 — 27.10.2026
+
+### Added
+
+- **`cli-dev bundle --bin dist/bin/<cli>.js` builds the published bin as an esbuild bundle, the way tg-cli 0.100.0
+  ships.** It moves tg's `scripts/bundle.ts` into cli-base so every CLI builds the same way: code splitting that keeps
+  each lazy `import()` lazy; `import.meta.url` and run-time package lookups that stay at the original module's place
+  in the CLI, cli-core and cli-base; CommonJS named exports for a dynamic `import("yaml")`; kept names; native and
+  by-name packages left outside. The bin becomes a loader that answers `--version`, turns the compile cache on and,
+  under `serve`, `watch` and `mcp`, preloads every chunk so a running server survives an in-place upgrade. The build
+  fails when a bundled module would look in the wrong place. Add `esbuild` (an optional peer, `^0.28.0`) as a
+  devDependency and name the CLI's own outside packages with `--external`. The rule is
+  [WC-LAY-10](docs/standards/layout.md#wc-lay-10--ship-the-bin-as-a-bundle-that-cli-dev-bundle-builds).
+- **WC-PERM-22 on the [Permissions](docs/standards/permissions.md) page: a CLI that is not a messenger declares its
+  own permission keys and defaults with cli-core's `commandPermissions`** (cli-core 0.450.0). It says how such a CLI
+  keys its commands, picks built-in defaults for what its writes do, and runs writes through the read-only lock and the
+  write guard. The example is a calendar: event writes ask, deleting a whole series and mailing attendees are denied
+  until the owner allows them. The page covered messenger CLIs only, and WC-PERM-6's "ask only before what cannot be
+  undone" read as if it applied to a calendar too; it now says it is the messengers' list. drive, zoom and memo do
+  not declare `commandPermissions` yet; the rule names them as known gaps.
+- **`cli-dev audit` compares gcal (`@wirecat/gcal-cli`, the Google Calendar CLI) in the `all` parity group**, next to
+  tg, max, memo, drive, zm and wa, so its shared root commands are held to the same options and summaries. A run
+  without gcal's command tree skips it, as before; the weekly audit adds it once gcal is published on npm.
+- **The command vocabulary has the words a calendar CLI needs.** Verbs `unsync` (stop syncing a thing; what is
+  stored stays), `review` (list what waits for the owner's decision) and `resolve` (settle one such thing with the
+  owner's choice); collections `calendars`, `events` and `people`. `events` was only a view word, so a command group
+  named `events` was reported by `unknown-resource`.
+- **The vocabulary has the flags and the verb of calendar writes** (cli-core's `events create | update | delete |
+  respond`). Flags `--end-time`, `--start-date`, `--end-date`, `--location`, `--attendee` (repeat it for more),
+  `--id` (the id a create is made with) as `value`; `--calendar` and `--series` as `target`; `--no-notify` as `mode`.
+  `--notify` now means telling the people a change concerns — a chat's members or an event's attendees. Verb
+  `respond` (answer an invitation). Without them `option-role` and `unknown-verb` reported every calendar CLI's
+  write commands.
+- **The vocabulary has the words of free/busy and repeating events** (cli-core's `calendars busy` and
+  `events create | update --repeat`). View `busy` (when calendars or people are taken, without what takes them);
+  flags `--repeat <rule>` (an RFC 5545 rule) as `value` and `--hours <from-to>` (the working hours to look in) as
+  `target`. gcal-cli overrides the four lint reports they cause until it takes this release.
+
+- **`requestSchema(operation, definitions)` in `@wirecat/cli-base/codegen` builds the JSON Schema of a generated
+  operation's request body**, every referenced definition under `$defs`, or returns `null` when the operation takes
+  no body. drive-cli and gcal-cli each kept an identical copy for `api show`. Pass a manifest operation and the
+  `definitions` that `definitionsGenerator` wrote.
+
+### Changed — may break callers
+
+- **A lint baseline entry or override for a word that is now in the vocabulary goes stale, and `cli-dev lint` fails
+  on it.** This release adds `unsync`, `review`, `resolve`, `calendars`, `events` and `people`. zoom-cli lists
+  `events` in `lint/baseline/unknown-resource.json`; gcal-cli lists `calendars`, `events`, `people`,
+  `calendars unsync`, `links review` and `links resolve` in its baseline; drive-cli overrides `unknown-verb` for
+  `comments resolve`, and cli-memo for `search people`, in `lint/overrides.json`. Remove those entries in the same
+  change that takes this version.
+- **The calendar write words make gcal-cli's write baseline stale too.** Its `lint/baseline/option-role.json` (20
+  entries under `events create | update | delete | respond`) and `events respond` in `unknown-verb.json` go stale
+  with this release; remove them when gcal takes it. No other CLI's baseline or overrides on `main` name these words.
+- **The free/busy and repeat words make four of gcal-cli's overrides stale.** `lint/overrides.json` names
+  `calendars busy` (`unknown-verb`), `calendars busy --hours` and `events create | update --repeat` (`option-role`);
+  remove them when gcal takes this release.
+
+- **`describeAlone` is no longer exported from `@wirecat/cli-base/commands`.** It was made public by accident in
+  0.62.0; it is a helper of the shared-command check and only works with a map kept for one check. No known caller
+  imports it. Describe a whole tree with `describeProgram` instead.
+
+### Fixed
+
+- **Handbook corrections from gcal-cli's first-release audit.**
+  - The Toolchain, CI, Security, Testing and Store pages listed "the ten repositories" and "the six CLIs" without
+    gcal. They now say "the WireCat repositories": every WireCat CLI, a new one from its first commit, and the shared
+    repositories. `gcal-cli` is a known repository name for "Enforced by".
+  - WC-SECR-4 said the keyring service is the command's name. It is the CLI's app name (`max-cli`, `gcal-cli`,
+    `cli-memo`), as cli-core passes it.
+  - WC-REL-16 says what a CLI's package `files` holds: `dist`, `skills`, `README.md`, `LICENSE` and what the CLI
+    reads or runs after install (`scenarios`, `install`, notices); `CHANGELOG.md` may ship. Never `src/`, tests,
+    scripts, workflows, `bin/release`, `config/`, `lint/`, `contracts/` or `template.json`.
+  - WC-REL-11 names its one exception: a package's first version, published by the owner with `bin/release --local`,
+    since npm sets a trusted publisher only for a package that exists. Step 2 of
+    [New CLI](docs/standards/new-cli.md) says the same.
+  - [New CLI](docs/standards/new-cli.md) says which copied files a CLI rewrites (seeds) and which it leaves to
+    cli-template (template-owned), and that a template-owned page wrong for the CLI is fixed in cli-template.
+  - "Done when" told authors to add a new CLI's shared audit findings to `audit/baseline`, which has not accepted
+    them since cli-base 0.51.0. It now says to fix each one, or declare an exact difference in the parity group.
+  - WC-CI-8 says the fresh-agent audit is given the pinned cli-base workflows.
+  - WC-TEST-12 has one exception: commands generated from an API description share one reason that names an
+    options-against-the-snapshot test and a test that drives a generated command through `run()`.
+
+- **`syncDiscovery` writes the same snapshot for the same revision of a Google API.** Google serves one revision with
+  its object keys in a different order on each download, so two syncs gave different files, hashes and generated
+  code. The snapshot is now the parsed document with its keys sorted and 2-space indentation; values and array order
+  are unchanged. `sha256` is stable; `sourceSha256` is still the hash of the bytes Google served, so it can change
+  between syncs. The first sync after upgrading rewrites each snapshot once, and `pnpm generate` then reorders the
+  generated types, schemas and manifest once.
+- **`skill show` now names every agent `skill install` serves: Claude Code, Codex, Gemini CLI, OpenClaw, and Hermes
+  on request.** Its help named only the first three, so OpenClaw and Hermes users could not tell the skill was meant
+  for them.
+- **The [CI](docs/standards/ci.md) page lists the monthly cron minutes WireCat repositories already use**, under
+  WC-CI-9, and [New CLI](docs/standards/new-cli.md) step 3 points to it. Finding a free minute meant reading
+  `monthly.yml` in every repository. A new CLI adds its minute to the list in the same pull request that joins the
+  parity groups.
+- **The [Kit surface](docs/standards/kit-surface.md) page lists every cli-core and cli-base export cli-template
+  0.7.0 imports**, among them the ones for MCP over HTTP: `mcpServerCommand`, `serveOverHttp`, `httpLockFile` and
+  the rest. The page left them out, so a change to them would not have been seen as one that reaches every new CLI.
+- **[New CLI](docs/standards/new-cli.md) lets the fresh audit agent read the cli-base workflow files a CLI's
+  workflows pin.** WC-CI-8 tells an audit to read them, but the audit was limited to the handbook and the
+  repository. A release audit prompt kept in a CLI repository needs the same change.
+- **WC-TEST-5 on the [Testing](docs/standards/testing.md) page says that a test may wait for a local process or
+  server it started**, polling with a timeout shorter than the test's own; a fixed sleep is still not allowed. It
+  was unclear whether such a wait counts as waiting for real time.
+- **WC-CMD-6 on the [Commands](docs/standards/commands.md) page names `mcp --revoke` as an exception.** The rule says
+  an option never turns a command into a different action, and `--revoke` does: it forgets every browser login
+  instead of starting a server. The owner kept it an option on `mcp` because it belongs with the HTTP server's login
+  state. No other option gets this exception.
+- **The handbook's examples start `gcal-cli` with the command `gcal`, not `cal`**, the system calendar program on macOS
+  and many Linux systems. A CLI named after it would shadow it.
+
 ## 0.63.0 — 27.10.2026
 
 ### Added

package/dist/codegen/discovery.d.ts

@@ -33,7 +33,7 @@ export interface DiscoveryProvenance {
     version: string;
     /** Of the committed file; `readDiscovery` refuses a snapshot that no longer matches it. */
     sha256: string;
-    /** Of the bytes Google served. Equal to `sha256` unless the file was normalized after download. */
+    /** Of the bytes Google served. Google varies its key order, so this one can change while `sha256` does not. */
     sourceSha256: string;
     normalization: string;
 }
@@ -43,8 +43,8 @@ export interface SyncDiscoveryOptions {
     fetch?: typeof globalThis.fetch;
 }
 /**
- * Downloads each Discovery document byte for byte and records where it came from. Run by hand, then review
- * the diff: the build never fetches. `provenance.json` keeps the order of `sources`, and that order is
+ * Downloads each Discovery document, sorts its object keys so the same revision always gives the same file, and
+ * records where it came from. Run by hand, then review the diff: the build never fetches. `provenance.json` keeps the order of `sources`, and that order is
  * the order of the generated schemas.
  */
 export declare const syncDiscovery: (sources: Readonly<Record<string, string>>, options: SyncDiscoveryOptions) => Promise<Record<string, DiscoveryProvenance>>;

package/dist/codegen/discovery.js

@@ -240,9 +240,18 @@ export const adaptDiscovery = (documents, options = {}) => {
     };
 };
 const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
+/** Google serves the same revision with its keys in a different order each time; arrays keep theirs. */
+const sortKeys = (value) => Array.isArray(value)
+    ? value.map(sortKeys)
+    : object(value)
+        ? Object.fromEntries(Object.keys(value)
+            .sort()
+            .map((key) => [key, sortKeys(value[key])]))
+        : value;
+const NORMALIZATION = "object keys sorted, 2-space JSON; values and array order unchanged";
 /**
- * Downloads each Discovery document byte for byte and records where it came from. Run by hand, then review
- * the diff: the build never fetches. `provenance.json` keeps the order of `sources`, and that order is
+ * Downloads each Discovery document, sorts its object keys so the same revision always gives the same file, and
+ * records where it came from. Run by hand, then review the diff: the build never fetches. `provenance.json` keeps the order of `sources`, and that order is
  * the order of the generated schemas.
  */
 export const syncDiscovery = async (sources, options) => {
@@ -257,20 +266,20 @@ export const syncDiscovery = async (sources, options) => {
         const document = JSON.parse(raw);
         if (!object(document) || document.name !== service)
             throw new Error(`${source} is not the Discovery document of ${service}`);
-        const hash = sha256(raw);
-        downloaded[service] = raw;
+        const written = `${JSON.stringify(sortKeys(document), null, 2)}\n`;
+        downloaded[service] = written;
         provenance[service] = {
             source,
             revision: String(document.revision),
             version: String(document.version),
-            sha256: hash,
-            sourceSha256: hash,
-            normalization: "none",
+            sha256: sha256(written),
+            sourceSha256: sha256(raw),
+            normalization: NORMALIZATION,
         };
     }
     mkdirSync(options.dir, { recursive: true });
-    for (const [service, raw] of Object.entries(downloaded))
-        writeFileSync(join(options.dir, `${service}.json`), raw);
+    for (const [service, text] of Object.entries(downloaded))
+        writeFileSync(join(options.dir, `${service}.json`), text);
     writeFileSync(join(options.dir, "provenance.json"), `${JSON.stringify(provenance, null, 2)}\n`);
     return provenance;
 };

package/dist/codegen/index.d.ts

@@ -1,10 +1,12 @@
 /**
  * Turns an official API description into committed code: types, Valibot schemas, an operation
- * manifest and a coverage page. Build-time only, and format-neutral: it parses no file format and
+ * manifest and a coverage page. Build-time, apart from the small helpers a CLI reads the generated
+ * files with (`identifier`, `requestSchema`), and format-neutral: it parses no file format and
  * adds no dependency. `adaptOpenApi` reads an OpenAPI document and `adaptDiscovery` Google Discovery
  * documents the consumer has parsed; an adapter from Postman or anything else lives in the consumer.
  */
 export { adaptDiscovery, type DiscoveryMetadata, type DiscoveryOptions, type DiscoveryProvenance, type DiscoveryResult, type DiscoveryService, readDiscovery, type SyncDiscoveryOptions, syncDiscovery, } from "./discovery.js";
+export { requestSchema } from "./json-schema.js";
 export { type CoverageOptions, coverageGenerator, definitionsGenerator, type ManifestOperation, manifestGenerator, } from "./manifest.js";
 export type { ApiBody, ApiModel, ApiOperation, ApiParameter, ApiSchema, Binding, CodeGenerator, Confidence, Discriminator, Effect, GeneratedArtifact, HttpBinding, HttpMethod, Override, RpcBinding, SchemaNode, SourceInfo, SourceReference, } from "./model.js";
 export { identifier, kebab } from "./names.js";

package/dist/codegen/index.js

@@ -1,10 +1,12 @@
 /**
  * Turns an official API description into committed code: types, Valibot schemas, an operation
- * manifest and a coverage page. Build-time only, and format-neutral: it parses no file format and
+ * manifest and a coverage page. Build-time, apart from the small helpers a CLI reads the generated
+ * files with (`identifier`, `requestSchema`), and format-neutral: it parses no file format and
  * adds no dependency. `adaptOpenApi` reads an OpenAPI document and `adaptDiscovery` Google Discovery
  * documents the consumer has parsed; an adapter from Postman or anything else lives in the consumer.
  */
 export { adaptDiscovery, readDiscovery, syncDiscovery, } from "./discovery.js";
+export { requestSchema } from "./json-schema.js";
 export { coverageGenerator, definitionsGenerator, manifestGenerator, } from "./manifest.js";
 export { identifier, kebab } from "./names.js";
 export { adaptOpenApi, OpenApiError } from "./openapi.js";

package/dist/codegen/json-schema.d.ts

@@ -0,0 +1,8 @@
+import type { ManifestOperation } from "./manifest.js";
+import type { SchemaNode } from "./model.js";
+/**
+ * The JSON Schema (draft 2020-12) of an operation's request body, built from the `definitions` that
+ * `definitionsGenerator` wrote, with every referenced definition under `$defs`; `null` when the operation takes no
+ * body. For a CLI's `api show`, so an agent sees what to send before it calls.
+ */
+export declare const requestSchema: (operation: Pick<ManifestOperation, "request">, definitions: Readonly<Record<string, SchemaNode>>) => Record<string, unknown> | null;

package/dist/codegen/json-schema.js

@@ -0,0 +1,78 @@
+import { identifier } from "./names.js";
+/**
+ * The JSON Schema (draft 2020-12) of an operation's request body, built from the `definitions` that
+ * `definitionsGenerator` wrote, with every referenced definition under `$defs`; `null` when the operation takes no
+ * body. For a CLI's `api show`, so an agent sees what to send before it calls.
+ */
+export const requestSchema = (operation, definitions) => {
+    if (!operation.request?.schema)
+        return null;
+    const defs = {};
+    const visiting = new Set();
+    const node = (value) => {
+        const common = { ...(value.description ? { description: value.description } : {}) };
+        switch (value.type) {
+            case "ref": {
+                const name = identifier(value.ref);
+                add(name);
+                return { ...common, $ref: `#/$defs/${name}` };
+            }
+            case "unknown":
+                return common;
+            case "union":
+                return { ...common, anyOf: value.of.map(node) };
+            case "allOf":
+                return { ...common, allOf: value.of.map(node) };
+            case "object":
+                return {
+                    ...common,
+                    type: "object",
+                    properties: Object.fromEntries(Object.entries(value.properties).map(([key, item]) => [key, node(item)])),
+                    required: value.required,
+                    additionalProperties: value.additionalProperties ? node(value.additionalProperties) : true,
+                };
+            case "array":
+                return {
+                    ...common,
+                    type: "array",
+                    items: node(value.items),
+                    ...(value.minItems === undefined ? {} : { minItems: value.minItems }),
+                    ...(value.maxItems === undefined ? {} : { maxItems: value.maxItems }),
+                };
+            case "string":
+                return {
+                    ...common,
+                    type: "string",
+                    ...(value.enum ? { enum: value.enum } : {}),
+                    ...(value.pattern ? { pattern: value.pattern } : {}),
+                    ...(value.minLength === undefined ? {} : { minLength: value.minLength }),
+                    ...(value.maxLength === undefined ? {} : { maxLength: value.maxLength }),
+                };
+            case "boolean":
+                return { ...common, type: "boolean" };
+            case "integer":
+            case "number":
+                return {
+                    ...common,
+                    type: value.type,
+                    ...(value.minimum === undefined ? {} : { minimum: value.minimum }),
+                    ...(value.maximum === undefined ? {} : { maximum: value.maximum }),
+                };
+        }
+    };
+    const add = (name) => {
+        if (visiting.has(name))
+            return;
+        visiting.add(name);
+        const value = definitions[name];
+        if (!value)
+            throw new Error(`generated schema reference is missing: ${name}`);
+        defs[name] = node(value);
+    };
+    add(operation.request.schema);
+    return {
+        $schema: "https://json-schema.org/draft/2020-12/schema",
+        $ref: `#/$defs/${operation.request.schema}`,
+        $defs: defs,
+    };
+};

package/dist/commands/index.d.ts

@@ -12,7 +12,7 @@
 import type { Command } from "commander";
 export { type CommandsDocument, type CommandsDocumentAbout, commandsDocument, commandsDocumentJsonSchema, commandsDocumentSchema, parseCommandsDocument, } from "./document.js";
 export { COMMANDS_PAGE_LABELS, type CommandsPage, type CommandsPageLabels, type CommandsPageText, commandsPage, } from "./page.js";
-export * from "./registry.js";
+export { type ArgumentInfo, annotate, annotateOption, type CommandInfo, type CommandLifetime, type CommandMeta, type CommandOutput, type CommandReach, type CommandState, describeOptions, describeProgram, flatten, metaOf, type OptionInfo, type OptionMeta, type Origin, optionMetaOf, stepTargets, } from "./registry.js";
 /**
  * Refuses a command path that arrived as one argument — `"projects add" --help`, what a zsh loop over
  * `$c` passes. Commander settles `--help` for an unknown word before any hook runs and prints the root

package/dist/commands/index.js

@@ -1,7 +1,7 @@
 import { CliError } from "../errors.js";
 export { commandsDocument, commandsDocumentJsonSchema, commandsDocumentSchema, parseCommandsDocument, } from "./document.js";
 export { COMMANDS_PAGE_LABELS, commandsPage, } from "./page.js";
-export * from "./registry.js";
+export { annotate, annotateOption, describeOptions, describeProgram, flatten, metaOf, optionMetaOf, stepTargets, } from "./registry.js";
 /**
  * Refuses a command path that arrived as one argument — `"projects add" --help`, what a zsh loop over
  * `$c` passes. Commander settles `--help` for an unknown word before any hook runs and prints the root

package/dist/credentials.d.ts

@@ -9,7 +9,7 @@ export interface StoredCredential {
 export interface CredentialsOptions {
     /** Where the fallback file lives when the keyring cannot be used. */
     configDir: string;
-    /** The keyring service name — the command's name, e.g. `max-cli`. */
+    /** The keyring service name — the CLI's app name, e.g. `max-cli`, not its command word. */
     service: string;
     /**
      * **True when the config directory came from the environment rather than the OS convention.**

package/dist/dev/bundle.d.ts

@@ -0,0 +1,25 @@
+export interface BundleOptions {
+    /** The CLI's root: `dist/` and `package.json` are under it. */
+    root: string;
+    /** The compiled bin, relative to `root`, e.g. `dist/bin/tg.js`. It becomes the loader. */
+    bin: string;
+    /** Packages that stay outside the bundle, besides `DEFAULT_EXTERNAL`. `*` matches anything. */
+    external?: readonly string[];
+    /** Packages whose modules keep their installed place, besides `DEFAULT_ANCHORED`. */
+    anchored?: readonly string[];
+    /** Third-party files read and found harmless, besides `DEFAULT_HARMLESS` (a path suffix each). */
+    harmless?: readonly string[];
+}
+export interface BundleResult {
+    problems: string[];
+    /** The chunks a server preloads, as the loader names them. */
+    chunks: string[];
+}
+/** Native modules, Bun's SQLite, and what cli-core loads only by name or starts as a worker from its own file. */
+export declare const DEFAULT_EXTERNAL: string[];
+export declare const DEFAULT_ANCHORED: string[];
+export declare const DEFAULT_HARMLESS: string[];
+export declare const LOADER_MARK = "// cli-dev bundle loader\n";
+/** The bin that replaces the compiled one: `name` is the bundle's entry, `chunks` what a server preloads. */
+export declare const loaderSource: (name: string, version: string, chunks: readonly string[]) => string;
+export declare const bundle: (options: BundleOptions) => Promise<BundleResult>;

package/dist/dev/bundle.js

@@ -0,0 +1,271 @@
+/**
+ * `cli-dev bundle`: the published bin starts from an esbuild bundle of `dist/`, so a command loads a few dozen files
+ * instead of about a thousand. Moved from tg-cli's `scripts/bundle.ts`, where it was proven first.
+ *
+ * - `dist/bundle/` holds the bundle. Its chunks keep every lazy `import()` lazy.
+ * - The bin becomes a loader: it answers `--version`, turns the compile cache on before any of the bundle compiles,
+ *   and for a server preloads every chunk so an in-place upgrade cannot pull one from under it.
+ * - A module moved into a chunk would look for files and packages from the chunk. In the CLI's own modules and in the
+ *   anchored packages (cli-core, cli-base), `import.meta.url` becomes the module's own place, and a package they load
+ *   at run time is resolved from there too: pnpm installs cli-core's dependencies beside cli-core, not beside the CLI.
+ * - The build fails when a bundled module would still look in the wrong place.
+ */
+import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { isBuiltin } from "node:module";
+import { basename, dirname, join, relative, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+/** Native modules, Bun's SQLite, and what cli-core loads only by name or starts as a worker from its own file. */
+export const DEFAULT_EXTERNAL = [
+    "bun:sqlite",
+    "*.node",
+    "better-sqlite3",
+    "@napi-rs/*",
+    "@resvg/*",
+    "@huggingface/*",
+    "sherpa-onnx*",
+    "onnxruntime-*",
+    "@wirecat/cli-core-onnx",
+    "@wirecat/cli-core-sqlite",
+    "ogg-opus-decoder",
+];
+export const DEFAULT_ANCHORED = ["@wirecat/cli-core", "@wirecat/cli-base"];
+// commander and @colors name these in comments and messages; liquidjs resolves partials with explicit `paths`, so the
+// requiring file does not matter.
+export const DEFAULT_HARMLESS = [
+    "/commander/lib/command.js",
+    "/@colors/colors/lib/colors.js",
+    "/liquidjs/dist/liquid.node.js",
+];
+export const LOADER_MARK = "// cli-dev bundle loader\n";
+const posix = (path) => path.split(sep).join("/");
+const matcher = (patterns) => {
+    const expressions = patterns.map((pattern) => new RegExp(`^${pattern.replaceAll(".", "\\.").replaceAll("*", ".*")}$`));
+    return (specifier) => expressions.some((expression) => expression.test(specifier));
+};
+// Node has no "resolve from this parent" call; a resolve hook for the one call gives Node's own answer. Bun has no
+// hooks but has `Bun.resolveSync(specifier, parent)`; when it finds nothing, the plain lookup keeps Bun's own error.
+const FROM = "cli-dev-bundle:from";
+const FROM_SOURCE = `import * as module from "node:module"
+import { dirname } from "node:path"
+import { fileURLToPath, pathToFileURL } from "node:url"
+export const resolveFrom = (parent, specifier) => {
+  if (globalThis.Bun) {
+    if (specifier.includes(":")) return import.meta.resolve(specifier)
+    try {
+      return pathToFileURL(globalThis.Bun.resolveSync(specifier, dirname(fileURLToPath(parent)))).href
+    } catch {
+      return import.meta.resolve(specifier)
+    }
+  }
+  if (!module.registerHooks) return import.meta.resolve(specifier)
+  const hooks = module.registerHooks({
+    resolve: (asked, context, next) => next(asked, asked === specifier ? { ...context, parentURL: parent } : context),
+  })
+  try {
+    return import.meta.resolve(specifier)
+  } finally {
+    hooks.deregister()
+  }
+}
+export const importFrom = async (parent, specifier) => import(resolveFrom(parent, specifier))
+`;
+const BY_NAME = /(?<![\w$.])import\(\s*(?!["'`.])/g;
+const LITERAL = /(?<![\w$.])import\(\s*(["'])([^"'.][^"']*)\1\s*\)/g;
+const ownPlaces = (dist, out, anchored, harmless, isExternal, problems) => {
+    const placeOf = (file) => {
+        if (file.startsWith(dist + sep))
+            return `new URL(${JSON.stringify(posix(relative(out, file)))}, import.meta.url).href`;
+        for (const name of anchored) {
+            const marker = `${sep}node_modules${sep}${name.replace("/", sep)}${sep}`;
+            const at = file.lastIndexOf(marker);
+            if (at < 0)
+                continue;
+            const packageRoot = file.slice(0, at + marker.length);
+            const manifest = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
+            const entry = manifest.exports?.["."]?.default;
+            if (typeof entry !== "string")
+                throw new Error(`${name}: package.json has no exports["."].default to anchor on`);
+            const path = posix(relative(dirname(join(packageRoot, entry)), file));
+            return `new URL(${JSON.stringify(path)}, import.meta.resolve(${JSON.stringify(name)})).href`;
+        }
+        return undefined;
+    };
+    return {
+        name: "own-places",
+        setup(context) {
+            context.onResolve({ filter: new RegExp(`^${FROM}$`) }, () => ({ path: FROM, namespace: FROM }));
+            context.onLoad({ filter: /.*/, namespace: FROM }, () => ({ contents: FROM_SOURCE, loader: "js" }));
+            context.onLoad({ filter: /\.[cm]?js$/ }, (args) => {
+                const source = readFileSync(args.path, "utf8");
+                const place = placeOf(args.path);
+                if (!place) {
+                    const known = harmless.some((path) => posix(args.path).endsWith(path));
+                    if (!known && /import\.meta|__dirname|__filename|require\.resolve/.test(source))
+                        problems.push(args.path);
+                    return undefined;
+                }
+                const loadsOutside = [...source.matchAll(LITERAL)].some(([, , specifier]) => specifier && isExternal(specifier));
+                if (!source.includes("import.meta") && source.search(BY_NAME) < 0 && !loadsOutside)
+                    return undefined;
+                const other = source.match(/import\.meta\.(?!url\b|resolve\b)\w+/);
+                if (other)
+                    problems.push(`${args.path}: ${other[0]}`);
+                // `place` holds `import.meta.url` or `import.meta.resolve`, so it goes in last.
+                const contents = source
+                    .replaceAll(/import\.meta\.resolve\(/g, "resolveFrom(PLACE, ")
+                    .replaceAll(BY_NAME, "importFrom(PLACE, ")
+                    .replaceAll(LITERAL, (call, quote, specifier) => isExternal(specifier) ? `importFrom(PLACE, ${quote}${specifier}${quote})` : call)
+                    .replaceAll(/import\.meta\.url\b/g, "PLACE")
+                    .replaceAll(/\bPLACE\b/g, place);
+                return { contents: `import { importFrom, resolveFrom } from "${FROM}";\n${contents}`, loader: "js" };
+            });
+        },
+    };
+};
+const isCommonJs = (file) => {
+    if (file.endsWith(".cjs"))
+        return true;
+    if (!file.endsWith(".js"))
+        return false;
+    for (let directory = dirname(file); directory !== dirname(directory); directory = dirname(directory)) {
+        const manifest = join(directory, "package.json");
+        if (existsSync(manifest))
+            return JSON.parse(readFileSync(manifest, "utf8")).type !== "module";
+    }
+    return true;
+};
+/**
+ * `await import("yaml")` gets CommonJS's named exports from Node, but only `default` from a bundled chunk. A dynamic
+ * import of CommonJS goes through a module that exports the names Node itself finds in it.
+ */
+const commonJsNames = {
+    name: "common-js-names",
+    setup(context) {
+        context.onResolve({ filter: /.*/ }, async (args) => {
+            if (args.kind !== "dynamic-import" || args.pluginData === "inner")
+                return undefined;
+            const resolved = await context.resolve(args.path, {
+                kind: "dynamic-import",
+                importer: args.importer,
+                resolveDir: args.resolveDir,
+                pluginData: "inner",
+            });
+            if (resolved.errors.length > 0 || resolved.external || !isCommonJs(resolved.path))
+                return undefined;
+            return { path: resolved.path, namespace: "common-js-names" };
+        });
+        context.onLoad({ filter: /.*/, namespace: "common-js-names" }, async (args) => {
+            const names = Object.keys(await import(pathToFileURL(args.path).href)).filter((name) => name !== "default");
+            const values = names.map((name, index) => `const n${index} = cjs[${JSON.stringify(name)}]`);
+            const exported = names.map((name, index) => `n${index} as ${JSON.stringify(name)}`);
+            return {
+                contents: `const cjs = require(${JSON.stringify(args.path)})\n${values.join("\n")}\nexport default cjs\nexport { ${exported.join(", ")} }\n`,
+                resolveDir: dirname(args.path),
+                loader: "js",
+            };
+        });
+    },
+};
+/** The bin that replaces the compiled one: `name` is the bundle's entry, `chunks` what a server preloads. */
+export const loaderSource = (name, version, chunks) => `#!/usr/bin/env node
+${LOADER_MARK}import * as module from "node:module"
+
+const words = process.argv.slice(2)
+// As the CLI answers it, unless a test records the argv: then the CLI writes the record too.
+if (
+  words.length === 1 &&
+  (words[0] === "--version" || words[0] === "-V") &&
+  !Object.keys(process.env).some((key) => key.endsWith("_TEST_ARGV_LOG"))
+) {
+  process.stdout.write(${JSON.stringify(`${version}\n`)})
+} else {
+  // Before the bundle compiles: the bundle's own call comes after its chunks.
+  module.enableCompileCache()
+  const serves = words
+    .slice(0, 3)
+    .some((word, at) => ["serve", "watch"].includes(word) || (word === "mcp" && !/^[^-]/.test(words[at + 1] ?? "")))
+  if (serves && module.registerHooks) {
+    const bundle = new URL("../bundle/", import.meta.url).href
+    module.registerHooks({
+      resolve: (specifier, context, next) =>
+        specifier.startsWith("./") && context.parentURL?.startsWith(bundle)
+          ? { url: new URL(specifier, context.parentURL).href, format: "module", shortCircuit: true }
+          : next(specifier, context),
+    })
+  }
+  const running = import(${JSON.stringify(`../bundle/${name}.js`)})
+  const chunks = ${JSON.stringify(chunks)}
+  // After the server answers its first request, so it starts no later.
+  if (serves) setTimeout(() => void Promise.allSettled(chunks.map((chunk) => import(chunk))), 2000).unref()
+  await running
+}
+`;
+export const bundle = async (options) => {
+    const { build } = await import("esbuild");
+    const root = options.root;
+    const dist = join(root, "dist");
+    const out = join(dist, "bundle");
+    const bin = join(root, options.bin);
+    const name = basename(bin).replace(/\.[cm]?js$/, "");
+    const external = [...DEFAULT_EXTERNAL, ...(options.external ?? [])];
+    const isExternal = matcher(external);
+    const problems = [];
+    if (!bin.startsWith(dist + sep))
+        return { problems: [`${options.bin} is not under dist/`], chunks: [] };
+    if (readFileSync(bin, "utf8").includes(LOADER_MARK))
+        return { problems: [`${options.bin} is already the loader — compile it again (tsc) first`], chunks: [] };
+    const { version } = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+    rmSync(out, { recursive: true, force: true });
+    const { metafile } = await build({
+        absWorkingDir: root,
+        entryPoints: { [name]: bin },
+        outdir: out,
+        bundle: true,
+        splitting: true,
+        format: "esm",
+        platform: "node",
+        target: "node22",
+        chunkNames: "[name]-[hash]",
+        // Two modules with one name would otherwise become `name2`, and `name` reaches errors and `commands --json`.
+        keepNames: true,
+        external,
+        // Bundled CommonJS calls `require` for Node's own modules.
+        banner: {
+            js: 'import { createRequire as __bundleRequire } from "node:module";\nconst require = __bundleRequire(import.meta.url);',
+        },
+        plugins: [
+            commonJsNames,
+            ownPlaces(dist, out, [...DEFAULT_ANCHORED, ...(options.anchored ?? [])], [...DEFAULT_HARMLESS, ...(options.harmless ?? [])], isExternal, problems),
+        ],
+        metafile: true,
+        logLevel: "silent",
+    });
+    // Only the CLI's own modules may import a package that stays outside: it resolves from the bundle, the CLI's place.
+    const own = `${posix(relative(root, dist))}/`;
+    for (const [input, { imports }] of Object.entries(metafile.inputs)) {
+        if (input.startsWith(own))
+            continue;
+        for (const { path, external: outside } of imports) {
+            if (outside && !isBuiltin(path) && !["bun:sqlite", "<runtime>"].includes(path))
+                problems.push(`${input} imports ${path}, which would resolve from the bundle`);
+        }
+    }
+    if (problems.length > 0)
+        return { problems, chunks: [] };
+    // An upgrade replaces the chunks under a running server, and their names carry a hash: a server that had not yet
+    // loaded one would fail to find it. A server loads them all soon after it starts, and finds a chunk it holds without
+    // looking on disk, where Node's resolver would look again for each new importer.
+    const lazy = new Set();
+    for (const { imports } of Object.values(metafile.outputs)) {
+        for (const { path, kind, external: outside } of imports) {
+            if (kind === "dynamic-import" && !outside)
+                lazy.add(`../bundle/${basename(path)}`);
+        }
+    }
+    const chunks = [...lazy].sort();
+    const missing = chunks.filter((chunk) => !existsSync(join(out, basename(chunk))));
+    if (missing.length > 0)
+        return { problems: missing.map((chunk) => `the loader names ${chunk}, not built`), chunks };
+    writeFileSync(bin, loaderSource(name, version, chunks));
+    return { problems: [], chunks };
+};