@wirecat/cli-base 0.0.0-stage → 0.22.0

package/LICENSE

@@ -0,0 +1,204 @@
+Copyright (c) 2026 Viacheslav Ptsarev
+
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,391 @@
-# Temporary Holding Version
+<img src="https://raw.githubusercontent.com/WireCatLabs/cli-base/main/docs/images/social-preview.png" alt="The foundation for agent-ready CLIs: output for people and machines, stable exit codes, keyring, testable clocks" width="100%">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @wirecat/cli-base
+
+The parts every command line tool needs and nobody enjoys writing twice: the two output streams,
+a renderer for people and for machines, a closed error model with stable exit codes, the OS
+keyring behind a testable seam, and injectable clocks.
+
+Extracted from [`brazecli`](https://github.com/leemour/brazecli), where each piece earned its
+shape, and shared with [`max-cli`](https://github.com/WireCatLabs/max-cli).
+
+Published on npm and used by `max-cli`, `cli-messaging`, `tg-cli` and `brazecli`. What changed in
+each version is in [`CHANGELOG.md`](CHANGELOG.md); how the package is put together and released is in
+[`docs/dev/`](docs/dev/ARCHITECTURE.md).
+
+## The rule this package exists to keep
+
+**In a machine mode, stdout carries data and nothing else.** No spinner, no `✓`, no warning, no
+ANSI. Diagnostics go to stderr, in every mode including the pretty one. That is the contract a
+script or an agent depends on, and `captureStreams` exists so a test can prove nothing leaked
+across.
+
+```ts
+import { captureStreams, createRenderer } from "@wirecat/cli-base"
+
+const streams = captureStreams()
+createRenderer({ format: "json", color: false, streams }).result({ chats: 2 })
+
+streams.stdout // ['{"chats":2}']
+streams.stderr // []
+```
+
+## What is in it
+
+| | |
+|---|---|
+| `streams` | the stdout/stderr split, and the capture used to test it |
+| `renderer` · `pretty` | `pretty` / `json` / `jsonl`; tables for lists, labelled lines for objects; `quiet` keeps only failures on stderr |
+| `errors` · `exit-codes` | 14 closed error codes, one exit number each, so a script can branch on `$?` |
+| `keyring` | `KeyringStore` with the system, memory and deliberately-broken implementations |
+| `fieldsOf` · `projectFields` | validated field selection preserving list metadata and operation identifiers |
+| `createOutputBuffer` | bounded UTF-8 output held until successful completion and resource cleanup |
+| `createDeadline` | cooperative command cancellation with injected sleep and a parent abort signal |
+| `time` | monotonic and wall clocks, and the one sleep that both timeouts and backoff use |
+| `logger` | the four-method interface a host adapts Pino to — this package logs nothing itself |
+| `paths` | config, state and cache in the XDG layout on Linux and macOS (`~/.config`, `~/.local/share`, `~/.cache`) and the `AppData` one on Windows, each overridable by environment variable; `migrateLegacyMacPaths` moves an older release's `~/Library` folders once |
+| `config` | JSON config loading that names the bad field, and an atomic write that locks the directory down |
+| `credentials` | environment → keyring → file, warning once and falling through when the keyring refuses |
+| `logging` | a Pino adapter writing JSON lines with secrets redacted by field name; a file that cannot be written is reported to `onError`, never thrown |
+| `retry` | full-jitter backoff, and the distinction between "no answer came" and "safe to repeat" |
+| `/testing` | `captureStreams`, `memoryKeyring`, `brokenKeyring`, `fakeClock` |
+| `/commands` | the command registry: `describeProgram`, `annotate`, `flatten`, `refuseJoinedPath`, and `commandsDocument` — the one `commands --json` shape, with its schema — see below |
+| `/completion` | shell completion over the registry: `suggest`, `formatSuggestions` — see below |
+| `/update` | keeping an install current: `installerOf`, `updateCommand`, `latestVersion`, `mayNotify`, `updateNotice`, `runUpdate` — see below |
+| `/codegen` | build time: an official API description → types, Valibot schemas, an operation manifest and a coverage page — see below |
+| `/release` | release time: `releaseCheck` and the checks it runs — changelog shape, links, package contents, version in step — see below |
+| `/skill` | the CLI's SKILL.md for coding agents: `skillCommand` (`show`, `install`), `skillHint`, `skillResource` — see below |
+| `/mcp` | local stdio MCP setup for Codex and Claude Code, plus a read-only handshake and tool-list probe |
+| `/standards` | the registries the standard is made of — vocabulary, output envelope, error object and reasons, next steps, log record, lint rules — as Valibot schemas that also emit JSON Schema 2020-12 |
+
+**Nothing in the root export is HTTP.** Status classification, `Retry-After` parsing and the fetch
+seam live in `@wirecat/cli-base/http`, so a CLI that speaks a socket never depends on a stack it
+does not call:
+
+```ts
+import { providerWaitMs, statusToCode } from "@wirecat/cli-base/http"
+```
+
+**Portable command control stays independent of provider and store lifetimes.**
+`fieldsOf("id,speaker.id")` parses up to 128 field paths; `projectFields(value, paths)` selects data
+from objects or list items while preserving the list envelope and `operationId` / `sendId`.
+`items.id` also works for bare objects and JSONL items. Unknown fields are omitted; parent selections
+win over their children. Unsafe prototype paths are refused, including when paths are passed directly.
+
+`createOutputBuffer({ maxOutputBytes })` retains raw output chunks until `flush(write)` or `discard()`.
+Its default limit is 4 MiB; zero disables the limit. It counts actual UTF-8 bytes, including delimiters
+the caller passes, and adds no newlines. Use a new buffer for each command and flush only after resource
+cleanup succeeds; discard on failure. A flush consumes the buffer even when its writer throws.
+The `bytes` property reports the cumulative accepted byte count. A writer failure can leave partial
+output; buffering only guarantees no output before flushing.
+
+Optional `{ fields, format: "json" | "jsonl" }` projects before counting bytes. With projection,
+each `data(text)` must contain a complete JSON value or complete JSONL lines; fragments fail before
+buffering. Without projection, arbitrary text chunks work. Hosts can instead project values before
+rendering and buffer the renderer's raw text. For core renderers, pass the line delimiter explicitly
+when adapting `Streams.data`: `data: (text) => buffer.data(text + "\n")`.
+
+`createDeadline({ timeoutMs, signal, sleep })` supplies a command signal and `race(body)`. An omitted
+timeout creates no timer; zero aborts synchronously without calling sleep, and the maximum is 2147483647 milliseconds.
+Pass its signal to every cancellable operation and check it before writes. On timeout or parent
+cancellation, `race` waits for the body to settle before rejecting, so a caller can safely close
+resources afterwards. An operation ignoring its signal can delay completion; this helper never
+abandons it in the background. A body's more precise `outcome_unknown` error survives interruption.
+Call `dispose()` in `finally` to remove the timer and parent listener. There are no process signal
+handlers, retries, automatic resource cleanup or HTTP behavior in these helpers.
+
+**The command registry is `@wirecat/cli-base/commands`** — the whole command tree as data, like
+`rails routes`, for an agent to read instead of `--help` and for generated documentation. It walks
+the live [Commander](https://github.com/tj/commander.js) tree, so a command built in a loop from a
+catalog appears exactly like a handwritten one; `annotate` adds what the tree cannot say. Commander
+is a type here, not a runtime dependency — an optional peer, 15 or newer.
+
+```ts
+import { annotate, describeProgram } from "@wirecat/cli-base/commands"
+
+annotate(program.command("send"), { mutates: true, examples: ["max messages send 42 hi"] })
+annotate(generated, { origin: "generated", operationId: "campaigns.list" })
+
+describeProgram(program) // [{ path: ["send"], usage, origin, mutates, options: [...], commands: [...] }]
+```
+
+Each option says whether it `takesValue` and, separately, whether it is `mandatory` — not
+Commander's `required`, which means "takes a value when given" — plus its choices, default,
+environment variable, the options it `conflicts` with and the values it `implies`.
+
+`refuseJoinedPath(program, args)` throws a `validation_error` when a command path arrived as one
+argument (`"projects add" --help`, what a zsh loop over `$c` passes), naming the words to type.
+Commander would print the root help instead; call it on the words before `parseAsync`, after a
+leading profile word if the CLI takes one.
+
+**Shell completion is `@wirecat/cli-base/completion`**, built on the registry. `suggest` takes the
+words typed so far and answers what may come next: a command, an action, an option, one of its
+values, or an argument's values from a source the CLI hands in — a local cache, never the network,
+because a shell calls it on every Tab. `formatSuggestions` writes the answer in the protocol of the
+shell scripts [`@bomb.sh/tab`](https://github.com/bombshell-dev/tab) generates, so the CLI prints
+those scripts with tab and answers `<cli> complete -- <words>` with this; cli-base itself does not
+depend on tab.
+
+```ts
+import { formatSuggestions, suggest } from "@wirecat/cli-base/completion"
+
+const words = argv.slice(argv.indexOf("--") + 1)
+streams.data(formatSuggestions(suggest({ commands, globalOptions, words, sources: { arguments: { chat: chatNames } } })))
+```
+
+**Two traps worth knowing before you use the credential store.** The OS keyring is global: an entry
+is addressed by service and account and knows nothing about which config directory asked for it, so
+a throwaway config directory silently overwrites the real secret unless you pass `isolated: true`.
+And a secret should never be handed to a logger in the first place — redaction by field name is the
+second line of defence, not the first.
+
+**Everything the environment knows can be passed in**: the clock, the sleep, the keyring, `env`,
+`fetch` and the streams. The real ones are only defaults — `Credentials` without a `keyring` uses the
+system keychain, `resolvePaths` without `env` reads `process.env`. Passing them is what makes a
+timeout test finish instantly and a keyring test incapable of reaching a real keychain.
+
+**Generating an API catalog is `@wirecat/cli-base/codegen`**, a build-time tool. It reads a
+format-neutral `ApiModel` — operations with a transport binding (`http` method and path, or `rpc`
+name), an `effect` (`read`, `write`, `destructive`) and how far the source can be trusted
+(`contract`, `example`, `inferred`, `override`) — and writes committed files. It parses no file
+format: the adapter from OpenAPI, Postman or anything else lives in the CLI that has that source,
+so this adds no dependency. Generation stops, naming the problem, when two operations collide, an
+operation is not classified as a read or a write, an override matches nothing, a reference points
+nowhere or a construct cannot be expressed; it never drops an operation or falls back to `any`.
+
+```ts
+import { generate, manifestGenerator, typesGenerator, valibotGenerator, writeArtifacts } from "@wirecat/cli-base/codegen"
+
+const artifacts = generate(model, [typesGenerator({ path }), valibotGenerator({ path, typesImport }), manifestGenerator({ path })], {
+  overrides: { answerOnCallback: { effect: "write", reason: "a POST that edits a message" } },
+  banner: ["Source: spec/bot/schema.yaml", "Run: pnpm bot:generate"],
+})
+const stale = writeArtifacts(artifacts, { root, check: process.argv.includes("--check") })
+```
+
+The generated schemas import `@wirecat/cli-base/codegen/runtime` at run time — a few number
+helpers, not the generator. Numbers are expected from a lossless JSON parser (`lossless-json`): a
+64-bit integer comes out as its exact decimal string, and any other integer that does not fit a JS
+number fails instead of rounding. Objects are loose, so a field the API added later passes through.
+Unions retain every alternative, including recursive references and Boolean literals.
+`definitionsGenerator` emits the same schema nodes for runtime input traversal; RPC parameters can be in the JSON body.
+Enums and discriminated unions are **strict**: a value or subtype the snapshot does not know fails,
+so decode a live stream (updates, webhooks) only where that is what you want.
+
+**The schemas decode; they do not encode.** Their output carries an `int64` as a string, so sending
+it back would put a string where the API expects a number. Validate a request with the schema, then
+send the original lossless value.
+
+**Keeping an install current is `@wirecat/cli-base/update`.** `installerOf(realpath(script))` says
+which package manager put the CLI there — pnpm, npm or bun, measured on real installs — and
+`updateCommand` gives the argv that updates it; a checkout or `npx` gets none. `latestVersion` asks
+npm with a timeout and answers `undefined` on any failure. `mayNotify` says whether a person is at a
+terminal to be told: never in JSON, a pipe, `--quiet`, `CI` or with `NO_UPDATE_NOTIFIER`.
+`updateNotice` is the whole daily line: it stays silent when `update` or `complete` is anywhere on
+the command line, asks npm at most once a day through a state file the CLI names, and returns the
+sentence or `undefined` — it never throws. `runUpdate` starts the package manager with its output on
+stderr (`spawnPlan` is the Windows `.cmd` rule). Nothing here updates or prints by itself — a CLI
+holding somebody's credentials must not change itself unasked.
+
+**A CLI's guide for coding agents is `@wirecat/cli-base/skill`.** `skillCommand(app, skillUrl,
+environment)` is `<cli> skill show` — SKILL.md on stdout, even into a pipe, or `{ name, content }`
+with `--json` — and `<cli> skill install [--for claude|agents|all]`, which writes it to
+`~/.claude/skills/<appName>/` and `~/.agents/skills/<appName>/` with the CLI's version as
+`metadata.version` in the frontmatter, refusing a file whose `name` is not `<appName>`. `environment` is the host's own renderer, streams and `env` for that invocation.
+`skillHint` is one line, or `undefined`, for an agent (`AI_AGENT` or `CLAUDECODE` set) with no copy
+installed or an older one, at most once a day, through the same state file as `updateNotice`; the
+host prints it on stderr. `skillResource` is what an MCP server registers to serve the file as
+`<command>://skill`, plus a line for its `instructions` — the SDK stays the host's.
+
+**The release checks are `@wirecat/cli-base/release`** — everything about a release that a program
+can decide. A check is `{ name, run }`, and `run` returns the problems it found, one line each; an
+empty list is a pass. `releaseCheck(checks, { version, log })` runs them all, even after a failure,
+prints `ok` or `FAIL` per check and returns how many failed — the caller exits. The checks every CLI
+shares: `command(root, "pnpm", "lint")` for anything that passes by exiting 0, `notOnNpm`,
+`packContents` against a list of what may ship, `changelogProblems` for the fixed headings and the
+dated top section, `docsProblems` for dead links and anchors and the rules of the pages a user reads,
+and `versionScript` — the whole of a `version:check` / `version:sync` script. Each CLI passes its
+own headings, id prefixes and pages; the checks that belong to one messenger stay in that CLI.
+
+```ts
+import { command, notOnNpm, packageVersion, releaseCheck } from "@wirecat/cli-base/release"
+
+const version = packageVersion(root)
+const failed = releaseCheck(
+  [
+    { name: "version not on npm", run: notOnNpm(root, "@wirecat/tg-cli", version) },
+    { name: "lint", run: command(root, "pnpm", "lint") },
+  ],
+  { version, log: console.log },
+)
+process.exit(failed === 0 ? 0 : 1)
+```
+
+## Where secrets actually go, per platform
+
+The keyring is real on every desktop and absent on most servers, so the fallback is not an edge
+case — it is the normal path in CI and containers. Checked against `@napi-rs/keyring` 2.1.0 on
+2026-09-19.
+
+| Platform | Backing store | Needs installing |
+|---|---|---|
+| macOS | Keychain, via the Security framework | nothing — part of the OS |
+| Windows | Credential Manager | nothing — part of the OS |
+| Linux desktop (GNOME, KDE) | Secret Service over D-Bus — `gnome-keyring`, `kwallet` | nothing on a normal desktop; the keyring must be **unlocked** |
+| Linux headless, container, WSL, CI | usually **nothing** — no session bus, no secrets daemon | falls back to a `0600` file, with one warning on stderr |
+| FreeBSD | Secret Service, same as Linux | same |
+
+**No compiler is involved.** The package ships prebuilt binaries for twelve platform triples —
+macOS arm64/x64, Windows x64/ia32/arm64, Linux x64 and arm64 in both glibc and musl, armv7,
+riscv64, FreeBSD x64 — so there is no Rust toolchain and no node-gyp on any mainstream target.
+The Linux binary links only against libc: it speaks D-Bus itself rather than through libsecret,
+so *libsecret is not a requirement* — a running Secret Service provider is.
+
+Two consequences worth designing for rather than discovering:
+
+- **`auto` is the right default and `file` must stay available.** `credentialStorage: "file"` skips
+  the keyring entirely, which is what a container wants and what a locked keyring makes necessary.
+- **A locked Linux keyring can block on a prompt** rather than failing. That is the one case the
+  fallback does not rescue, and a CLI that hangs looks broken rather than locked.
+
+## Both runtimes
+
+Node 22+ and Bun, and the Bun half is executed rather than assumed:
+
+```sh
+pnpm test        # vitest, Node
+pnpm smoke:bun   # the same exports, actually run under Bun
+pnpm lint
+pnpm typecheck
+pnpm build
+```
+
+The rest of the checks, and what each is for, are in [`docs/dev/TESTING.md`](docs/dev/TESTING.md).
+
+## Shared tooling
+
+The configuration, development scripts and CI that every CLI on cli-base used to copy. A repository
+takes each piece on its own.
+
+**TypeScript.** Compiler options only; paths and file lists stay in the repository, because `tsc`
+resolves them against the file that declares them.
+
+```jsonc
+// tsconfig.json
+{
+  "extends": "@wirecat/cli-base/tsconfig.base.json",
+  "compilerOptions": { "rootDir": "src", "outDir": "dist" },
+  "include": ["src/**/*.ts"],
+  "exclude": ["src/**/*.test.ts"]
+}
+// tsconfig.test.json — checks every file under src/, tests included, without emitting
+{ "extends": ["./tsconfig.json", "@wirecat/cli-base/tsconfig.test.json"] }
+// tsconfig.scripts.json — checks scripts/
+{ "extends": ["./tsconfig.json", "@wirecat/cli-base/tsconfig.scripts.json"] }
+```
+
+**Biome.** Formatter, linter and the rule that lets `scripts/` print. Your `files.includes` and
+your own `overrides` (import boundaries) stay in your file; Biome adds them to the shared ones.
+Write the specifier without `.json`: Biome reads anything ending in `.json` as a relative path.
+
+```json
+{ "extends": ["@wirecat/cli-base/biome"], "files": { "includes": ["**", "!**/dist", "!**/node_modules", "!pnpm-lock.yaml"] } }
+```
+
+**lefthook.** Biome and gitleaks on staged files before a commit, `pnpm typecheck` before a push.
+An extended file **overrides** your `lefthook.yml`; to change a shared hook, use `lefthook-local.yml`.
+
+```yaml
+extends:
+  - node_modules/@wirecat/cli-base/config/lefthook.yml
+```
+
+**`cli-dev`.** Installed with the package; `pnpm exec cli-dev help` lists the commands.
+
+| Instead of | Run |
+|---|---|
+| `scripts/slow-tests.ts` | `cli-dev slow-tests [report] [count]` |
+| `scripts/next-version.mjs` | `cli-dev next-version <wanted> <latest> <versions-json>` |
+| `scripts/version.ts` | `cli-dev version [--sync] [--file src/version.ts]` |
+| `scripts/docs-check.ts` | `cli-dev docs-check --rules scripts/release/checks.ts`, or `--ids CLI,MAX` with the English defaults |
+| `scripts/test-matrix.ts` | `cli-dev test-matrix --program dist/program.js --untested scripts/test-matrix-untested.ts --name max [--check]` |
+
+| — | `cli-dev lint --cli dist/bin.js` (or `--commands <file>`): the command tree against the standard |
+
+`cli-dev lint` reads `<cli> commands --json`, refuses a document not in `commandsDocument`'s shape, and
+judges it by `LINT_RULES` and `VOCABULARY` from `/standards`. Known violations live in
+`lint/baseline/<rule-id>.json`, one file per rule, and may only shrink: an entry with no violation left
+fails the run. `--write-baseline` rewrites those files to today's violations. Permanent exceptions go in
+`lint/overrides.json` — `[{ "rule", "target", "reason" }]` — and more than `--budget` (10) of them fails.
+
+`--rules` names a module exporting `CHANGELOG` and `docsRules(root)`; `--program` one exporting
+`createProgram`; `--untested` one exporting `UNTESTED`. A TypeScript module loads on Node 24 as it is.
+
+**Docs.** Spelling, Markdown form and prose rules for the pages a user reads. The tools are your
+own dev dependencies (`cspell`, `@cspell/dict-ru_ru`, `@cspell/dict-en-gb`, `rumdl`); the settings
+and the shared word list are here. Code blocks and inline code are not spell-checked: commands and
+options are checked against the program by the parity check.
+
+```jsonc
+// cspell.json — the dictionaries resolve from your node_modules, so you import them yourself
+{
+  "version": "0.2",
+  "import": ["@wirecat/cli-base/cspell", "@cspell/dict-en-gb/cspell-ext.json", "@cspell/dict-ru_ru/cspell-ext.json"],
+  "ignorePaths": ["docs/commands.md", "docs/dev/**", "CHANGELOG.md"],
+  "words": []
+}
+```
+
+```sh
+cspell --no-progress README.md "docs/*.md"
+rumdl check --config node_modules/@wirecat/cli-base/config/rumdl.toml README.md docs/*.md
+vale README.md docs/*.md   # .vale.ini: StylesPath = node_modules/@wirecat/cli-base/config/vale
+```
+
+`cli-dev docs-check --pages` adds the structure check: `docs/` against `docs/meta.json`, the
+sidebar of [the docs portal](https://github.com/WireCatLabs/cli-docs/blob/main/docs/STRUCTURE.md).
+Vale's styles are `CliDocs` (filler words, long sentences) and `Tg` (tg's tone: a Telegram client,
+never "unofficial"); its rules warn rather than fail until they are tuned.
+
+**CI.** Install, lint, typecheck, test with coverage, build, your extra checks, Bun, and a gitleaks
+scan of the whole history. Jobs only your repository needs stay beside it in your `ci.yml`.
+
+```yaml
+jobs:
+  ci:
+    uses: WireCatLabs/cli-base/.github/workflows/node-ci.yml@v<version>
+    with:
+      checks: |
+        pnpm docs:check
+      bun-run: pnpm build && pnpm smoke:bun   # the default is pnpm smoke:bun
+```
+
+Inputs: `node-version` (`"24"`), `checks` (shell lines run after the build), `bun` (`true`),
+`bun-run`. The workflow is in the repository, not the package: pin a tag or a commit, not `main`.
+
+## Releasing
+
+Raise `version` in `package.json` and date the `## Unreleased` section of
+[`CHANGELOG.md`](CHANGELOG.md) as that version, through a pull request; merge it, then on `main`:
+
+```sh
+bin/release
+```
+
+It refuses a dirty tree, a branch other than `main` and a `main` that is not pushed. When npm already
+has the version, or a higher one, it commits the next free version to `main` — the next minor for
+`x.y.0`, the next patch otherwise — renames the changelog heading to match, and publishes that. Then it starts
+[`release.yml`](.github/workflows/release.yml) and follows it. The workflow runs every check,
+publishes through npm's [trusted publishing](https://docs.npmjs.com/trusted-publishers/) — no npm
+token in GitHub, and npm attaches provenance — and tags `v<version>` only once npm shows the new version.
+
+npm trusts the workflow **by file name**: the package's Trusted Publisher settings on npmjs.com name
+`WireCatLabs` / `cli-base` / `release.yml`. Rename the file and publishing stops until they are updated.
+
+`bin/release --local` is the fallback: it runs the same checks here and publishes with the npm token
+from the keyring (`secret-tool`, service `npm`, account `leemour`) without printing it. The token
+must be allowed to write `@wirecat/cli-base`, not only `@wirecat/max-cli`.
+
+## Licence
+
+[Apache License 2.0](LICENSE).

package/config/biome.base.json

@@ -0,0 +1,56 @@
+{
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 120
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "double",
+      "semicolons": "asNeeded",
+      "trailingCommas": "all",
+      "arrowParentheses": "always"
+    }
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "preset": "recommended",
+      "style": {
+        "useConst": "error",
+        "noNonNullAssertion": "error"
+      },
+      "correctness": {
+        "noUnusedImports": "error",
+        "noUnusedVariables": "error"
+      },
+      "suspicious": {
+        "noExplicitAny": "error",
+        "noConsole": {
+          "level": "error",
+          "options": {
+            "allow": ["error"]
+          }
+        }
+      }
+    }
+  },
+  "overrides": [
+    {
+      "includes": ["scripts/**"],
+      "linter": {
+        "rules": {
+          "suspicious": {
+            "noConsole": "off"
+          }
+        }
+      }
+    }
+  ]
+}