@wirecat/cli-core 0.0.0 → 0.18.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Viacheslav Ptsarev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,344 @@
+# @wirecat/cli-core
+
+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-core"
+
+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 |
+| `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` | `env-paths` for config, state and cache, each overridable by environment variable |
+| `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` — 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 |
+
+**Nothing in the root export is HTTP.** Status classification, `Retry-After` parsing and the fetch
+seam live in `@wirecat/cli-core/http`, so a CLI that speaks a socket never depends on a stack it
+does not call:
+
+```ts
+import { providerWaitMs, statusToCode } from "@wirecat/cli-core/http"
+```
+
+**The command registry is `@wirecat/cli-core/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-core/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`.
+
+**Shell completion is `@wirecat/cli-core/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-core itself does not
+depend on tab.
+
+```ts
+import { formatSuggestions, suggest } from "@wirecat/cli-core/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-core/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-core/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-core/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-core/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-core/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-core/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-core/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-core 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-core/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-core/tsconfig.test.json"] }
+// tsconfig.scripts.json — checks scripts/
+{ "extends": ["./tsconfig.json", "@wirecat/cli-core/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-core/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-core/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]` |
+
+`--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-core/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-core/config/rumdl.toml README.md docs/*.md
+vale README.md docs/*.md   # .vale.ini: StylesPath = node_modules/@wirecat/cli-core/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-core/.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-core` / `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-core`, not only `@wirecat/max-cli`.
+
+## Licence
+
+MIT.

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"
+          }
+        }
+      }
+    }
+  ]
+}

package/config/cspell.json

@@ -0,0 +1,57 @@
+{
+  "version": "0.2",
+  "language": "en,en-GB,ru",
+  "ignoreRegExpList": [
+    "/^\\s*(```|~~~)[\\s\\S]*?^\\s*\\1/gm",
+    "/`[^`\\n]*`/g",
+    "/<!--[\\s\\S]*?-->/g",
+    "/\\]\\([^)]*\\)/g"
+  ],
+  "words": [
+    "armv",
+    "brazecli",
+    "bunx",
+    "claude",
+    "codegen",
+    "frontmatter",
+    "gitleaks",
+    "kwallet",
+    "leemour",
+    "libc",
+    "libsecret",
+    "LUKS",
+    "mtcute",
+    "npmjs",
+    "pioh",
+    "riscv",
+    "tailnet",
+    "tailscale",
+    "tgcli",
+    "unpushed",
+    "volta",
+    "wirecat",
+    "автодополнение",
+    "бана",
+    "вебхук",
+    "вебхуки",
+    "капчу",
+    "контрибьюторы",
+    "листателя",
+    "Минцифры",
+    "опкод",
+    "отсканируете",
+    "переголосовать",
+    "пулл",
+    "реквесты",
+    "рендерер",
+    "спиннера",
+    "схлопнет",
+    "схлопывает",
+    "токенам",
+    "токене",
+    "токеном",
+    "токену",
+    "хэша",
+    "хэшем"
+  ]
+}

package/config/lefthook.yml

@@ -0,0 +1,34 @@
+# Git hooks. Installed by the `prepare` npm script, which pnpm runs on every install — necessary
+# because pnpm blocks dependencies' build scripts by default, so lefthook's own postinstall never
+# fires and the hooks would otherwise silently never land.
+#
+# Install by hand:      pnpm exec lefthook install
+# Skip for one commit:  LEFTHOOK=0 git commit …
+
+pre-commit:
+  parallel: true
+  commands:
+    biome:
+      glob: "*.{ts,tsx,js,mjs,cjs,json,jsonc}"
+      # Staged files only. The whole-repo run is the CI gate; running it per-commit is how people
+      # end up reaching for --no-verify, which is worse than no hook.
+      run: pnpm exec biome check --no-errors-on-unmatched --files-ignore-unknown=true {staged_files}
+
+    gitleaks:
+      # Staged content only, and it warns rather than blocks when gitleaks is not installed: a
+      # fresh clone must still be able to commit. CI is the gate that cannot be skipped.
+      run: |
+        if command -v gitleaks >/dev/null 2>&1; then
+          gitleaks git --staged --no-banner --redact .
+        else
+          echo "gitleaks is not installed — staged changes were NOT scanned for secrets."
+          echo "  install: https://github.com/gitleaks/gitleaks#installing  (CI scans regardless)"
+        fi
+
+pre-push:
+  parallel: true
+  commands:
+    typecheck:
+      # A messaging CLI's parity check builds into the same dist/ as typecheck, so it runs here, after
+      # it, rather than as a command of its own beside it. A project without the script skips it.
+      run: pnpm typecheck && pnpm -s run --if-present parity:check

package/config/rumdl.toml

@@ -0,0 +1,9 @@
+# MD013 (line length): prose is wrapped by hand at 100–120 and tables cannot wrap.
+# MD041 (first line a heading): READMEs open with the logo; docs-check --pages checks the pages.
+# MD057 (relative links): docs-check follows every link and anchor already.
+[global]
+disable = ["MD013", "MD041", "MD057"]
+exclude = ["docs/commands.md", "node_modules", "dist", "docs_ai"]
+
+[MD033]
+allowed-elements = ["p", "img", "a", "br", "details", "summary", "sup", "sub", "kbd"]

package/config/tsconfig.base.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "lib": ["ES2023"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "types": ["node"],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "noFallthroughCasesInSwitch": true,
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "composite": true
+  }
+}

package/config/tsconfig.scripts.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "composite": false,
+    "declaration": false,
+    "declarationMap": false,
+    "emitDeclarationOnly": false,
+    "noEmit": true,
+    "rootDir": "${configDir}",
+    "allowImportingTsExtensions": true
+  },
+  "include": ["${configDir}/scripts/**/*.ts"],
+  "exclude": []
+}

package/config/tsconfig.test.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "composite": false,
+    "declaration": false,
+    "declarationMap": false,
+    "emitDeclarationOnly": false,
+    "noEmit": true
+  },
+  "include": ["${configDir}/src/**/*.ts"],
+  "exclude": []
+}

package/config/vale/CliDocs/Filler.yml

@@ -0,0 +1,9 @@
+extends: existence
+message: "'%s' tells the reader nothing; say what happens instead."
+level: warning
+ignorecase: true
+nonword: true
+# \p{L}, not \w or \b: those match no Cyrillic, and the rule would pass Russian text silently.
+tokens:
+  - '(?<!\p{L})(?:simply|just|easily|obviously|of course|basically|really|very)(?!\p{L})'
+  - '(?<!\p{L})(?:просто|легко|очевидно|конечно|всего лишь|на самом деле|очень)(?!\p{L})'

package/config/vale/CliDocs/SentenceLength.yml

@@ -0,0 +1,6 @@
+extends: occurrence
+message: "A sentence of more than 35 words; split it, one idea per sentence."
+level: suggestion
+scope: sentence
+max: 35
+token: '\p{L}+'

package/config/vale/Tg/Tone.yml

@@ -0,0 +1,7 @@
+extends: existence
+message: "'%s': tg is a Telegram client; state its limits as features, not as a risk."
+level: error
+ignorecase: true
+nonword: true
+tokens:
+  - '(?<!\p{L})(?:unofficial|at your own risk|banned|bans?|get blocked)(?!\p{L})'

package/dist/codegen/index.d.ts

@@ -0,0 +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
+ * adds no dependency. The adapter from OpenAPI, Postman or anything else lives in the consumer.
+ */
+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";
+export { applyOverrides, CodegenError, type GenerateOptions, generate, validateModel, type WriteOptions, writeArtifacts, } from "./pipeline.js";
+export { typesGenerator } from "./typescript.js";
+export { type ValibotOptions, valibotGenerator } from "./valibot.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/codegen/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/codegen/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EACL,KAAK,eAAe,EACpB,iBAAiB,EACjB,oBAAoB,EACpB,KAAK,iBAAiB,EACtB,iBAAiB,GAClB,MAAM,eAAe,CAAA;AACtB,YAAY,EACV,OAAO,EACP,QAAQ,EACR,YAAY,EACZ,YAAY,EACZ,SAAS,EACT,OAAO,EACP,aAAa,EACb,UAAU,EACV,aAAa,EACb,MAAM,EACN,iBAAiB,EACjB,WAAW,EACX,UAAU,EACV,QAAQ,EACR,UAAU,EACV,UAAU,EACV,UAAU,EACV,eAAe,GAChB,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAC9C,OAAO,EACL,cAAc,EACd,YAAY,EACZ,KAAK,eAAe,EACpB,QAAQ,EACR,aAAa,EACb,KAAK,YAAY,EACjB,cAAc,GACf,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAChD,OAAO,EAAE,KAAK,cAAc,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA"}

package/dist/codegen/index.js

@@ -0,0 +1,11 @@
+/**
+ * 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
+ * adds no dependency. The adapter from OpenAPI, Postman or anything else lives in the consumer.
+ */
+export { coverageGenerator, definitionsGenerator, manifestGenerator, } from "./manifest.js";
+export { identifier, kebab } from "./names.js";
+export { applyOverrides, CodegenError, generate, validateModel, writeArtifacts, } from "./pipeline.js";
+export { typesGenerator } from "./typescript.js";
+export { valibotGenerator } from "./valibot.js";
+//# sourceMappingURL=index.js.map

package/dist/codegen/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/codegen/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAEL,iBAAiB,EACjB,oBAAoB,EAEpB,iBAAiB,GAClB,MAAM,eAAe,CAAA;AAqBtB,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAC9C,OAAO,EACL,cAAc,EACd,YAAY,EAEZ,QAAQ,EACR,aAAa,EAEb,cAAc,GACf,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAChD,OAAO,EAAuB,gBAAgB,EAAE,MAAM,cAAc,CAAA"}