@the-i18n-kit/cli 4.9.0 → 5.0.0

package/README.md

@@ -1,224 +1,55 @@
-# the-i18n-cli
+# @the-i18n-kit/cli
 
-[![npm version](https://img.shields.io/npm/v/the-i18n-cli?style=flat&colorA=18181b&colorB=4fc08d)](https://npmjs.com/package/the-i18n-cli)
+[![npm version](https://img.shields.io/npm/v/@the-i18n-kit/cli?style=flat&colorA=18181b&colorB=4fc08d)](https://npmjs.com/package/@the-i18n-kit/cli)
 [![License](https://img.shields.io/npm/l/the-i18n-cli?style=flat&colorA=18181b&colorB=4fc08d)](https://github.com/fabkho/the-i18n-kit/blob/main/LICENSE)
 
-CLI and core library for managing i18n translation files — supports Nuxt, Laravel, Vue, React/Next.js, and any project with JSON or PHP locale files.
+Find missing translation keys, remove dead ones, and rename across every locale
+and layer at once. Supports Nuxt, Laravel, Vue, React/Next.js, and any project
+with JSON or PHP locale files.
 
-Read, write, search, rename, and remove translation keys across all locales and layers from your terminal. Auto-detects your framework, discovers monorepo structures, and handles the file I/O.
+Part of [the-i18n-kit](https://github.com/fabkho/the-i18n-kit).
 
-Part of [the-i18n-kit](https://github.com/fabkho/the-i18n-kit) monorepo. For MCP server usage, see [the-i18n-mcp](https://www.npmjs.com/package/the-i18n-mcp).
+### 📖 [Documentation](https://fabkho.github.io/the-i18n-kit/)
 
 ## Install
 
 ```bash
-# Global install
-npm install -g the-i18n-cli
-
-# Or use directly with npx
-npx the-i18n-cli --help
-```
-
-## Quick Start
-
-```bash
-the-i18n-cli init                            # Create .i18n-mcp.json from framework detection
-the-i18n-cli missing                         # Find missing translations
-the-i18n-cli search --query "save"           # Search keys and values
-the-i18n-cli write --layer root --translations '{"common.btn.ok": {"en": "OK", "de": "OK"}}'
-the-i18n-cli translate-key --layer root --key common.btn.save --sourceLocale en-US --sourceValue "Save"
-the-i18n-cli translate --layer root --provider openai --model gpt-4o-mini   # Auto-translate missing keys
-the-i18n-cli remove-orphans                  # Find orphan keys (dry-run by default)
-the-i18n-cli check                           # Find used-but-undefined keys (non-zero exit — CI gate)
-```
-
-## Commands
-
-| Command | Description |
-|---------|-------------|
-| `init` | Create a schema-valid `.i18n-mcp.json` from framework detection. Non-interactive; refuses to overwrite without `--force` |
-| `get` | Read translation values for specific keys |
-| `write` | Write translation keys (`add` / `update` / `upsert` mode, default: `upsert`) |
-| `add` | Add new translation keys (skips keys that already exist) |
-| `update` | Update existing keys (skips keys that do not exist) |
-| `missing` | Find keys missing in target locales |
-| `status` | Translation coverage per locale and per layer, with one overall percentage |
-| `search` | Search keys and values |
-| `remove` | Remove keys from all locale files in a layer |
-| `rename` | Rename/move a key across all locale files |
-| `translate` | Find missing translations and translate them via LLM (see Translation Modes). Also available as `translate-missing`, matching the MCP tool name |
-| `translate-key` | Translate one source key into target locales; can overwrite stale values |
-| `remove-orphans` | Find and remove keys not referenced in source code (dry-run by default) |
-| `check` | Find keys referenced in code but defined in no consumed locale layer — the inverse of `remove-orphans`. Exits non-zero when any are found, so it can gate CI. Dynamically built keys are reported as uncertain, never as hard findings |
-| `find-duplicates` | Find keys defined in both a shared layer and a consuming child layer (with divergence detection) |
-| `scan` | Find where translation keys are referenced in source, with file and line — use before renaming or removing a key |
-| `scaffold` | Create empty locale files for new languages |
-
-Run `the-i18n-cli <command> --help` for per-command options.
-
-### Common Flags
-
-| Flag | Description |
-|------|-------------|
-| `-d, --projectDir <dir>` | Project directory (default: cwd) |
-| `--json` | Output as JSON (default when piped) |
-| `--dryRun` | Preview changes without writing |
-| `--output-file <path>` | `missing` / `remove-orphans` / `check`: write the full report to a file, return only a summary |
-
-### Exit Codes and CI Gates
-
-| Code | Meaning |
-|------|---------|
-| `0` | The run succeeded and no gate tripped |
-| `1` | The run itself failed — bad API key, unreadable project, a translate run that translated nothing |
-| `2` | The run succeeded but a gate tripped: findings exist and the tool worked |
-
-Separating `1` from `2` lets a pipeline tell a broken setup apart from a project that simply has untranslated keys.
-
-Gates are opt-in flags, so every invocation without one keeps the exit code it has today:
-
-| Flag | Command | Trips when |
-|------|---------|-----------|
-| `--fail-on-missing` | `missing` | Any key is missing in a target locale |
-| `--fail-on-orphans` | `remove-orphans` | Any orphan key is found (dry-run still applies) |
-| `--fail-on-failed` | `translate` | Any key failed to translate |
-| `--fail-under <n>` | `status` | Overall completion is below `n` percent |
-
-```bash
-the-i18n-cli missing --fail-on-missing          # exit 2 blocks the merge
-the-i18n-cli remove-orphans --fail-on-orphans   # dry-run, but non-zero on findings
-the-i18n-cli translate --fail-on-failed         # exit 2 when the run lost keys
-the-i18n-cli status --fail-under 90             # ratchet coverage like test coverage
-```
-
-`translate` needs its own gate because exit `1` is reserved for a run that
-translated *nothing*. A run that writes 795 keys and loses 141 is a success by
-that measure: it exits `0`, and the partial result is committed like any other.
-The failed keys are still missing, so re-running retries them — the gate is for
-noticing that you need to.
-
-Gates compose on one invocation, and a failed run outranks a tripped gate — exit `1` wins over exit `2`. When a gate trips, the JSON result gains a `gatesTripped` array naming it and reporting the observed value against the threshold; nothing else in the result changes, so existing consumers keep working:
-
-```json
-{
-  "summary": { "totalMissingKeys": 12 },
-  "gatesTripped": [
-    { "name": "fail-on-missing", "counter": "totalMissingKeys", "direction": "above", "threshold": 0, "observed": 12 }
-  ]
-}
+npm install -g @the-i18n-kit/cli
 ```
 
-`check` is the exception: it gates unconditionally with exit `1`, because a key that renders raw in production is a defect rather than a threshold.
-
-## Getting Started on a New Project
-
-```bash
-the-i18n-cli init            # writes .i18n-mcp.json
-the-i18n-cli init --dry-run  # report what it would write, touch nothing
-the-i18n-cli init --force    # overwrite an existing config
-```
-
-`init` detects the framework and writes **only what that framework cannot tell the tool itself**. On a Nuxt, Laravel, Vue or React project the locales, layers and default locale are resolved from the framework config on every run, so `init` deliberately does not copy them into `.i18n-mcp.json` — a generated copy is a second source of truth that drifts silently the day the framework config changes. What you get is the authoring context no adapter can derive:
-
-```json
-{
-  "$schema": "https://raw.githubusercontent.com/fabkho/the-i18n-kit/main/packages/mcp/schema.json",
-  "context": "",
-  "glossary": {},
-  "translationPrompt": "",
-  "localeNotes": {}
-}
-```
-
-A project with no recognised framework is the exception: the generic adapter cannot resolve anything without `localeDirs` and `defaultLocale`, so `init` probes the common locale directory layouts and writes what it finds. The reference locale is guessed as the **fullest** locale file rather than the alphabetically first, since a source locale is the one everything else is translated from.
-
-The result reports which adapter matched and with what confidence, so you can tell why Nuxt was chosen over generic. `init` is non-interactive, so it runs unattended in a devcontainer or CI bootstrap, and it refuses to overwrite an existing config unless you pass `--force`. Even then it preserves any `localeDirs`, `defaultLocale` and `locales` already in the file — `--force` refreshes the scaffolding, it does not discard your locale wiring.
-
-## Coverage
-
-```bash
-the-i18n-cli status                  # per locale and per layer, plus one overall number
-the-i18n-cli status --layer root     # one layer
-the-i18n-cli status --fail-under 90  # CI gate: exit 2 below the threshold
-```
-
-One call replaces calling `missing` per layer and counting keys yourself:
-
-```json
-{
-  "summary": {
-    "totalKeys": 8, "translatedKeys": 3, "missingKeys": 4, "emptyKeys": 1,
-    "completionPercent": 37.5,
-    "protectedLocales": ["de-formal"], "localesChecked": 2
-  }
-}
-```
-
-**Empty strings count as untranslated.** A scaffolded key nobody filled renders as a blank, so counting it as complete would let a locale read as done while showing gaps in the UI — consistent with how `missing` already treats them. They are reported separately from `missing` so you can tell a scaffold-and-forget locale from an untouched one.
-
-**Protected locales are reported but excluded from the overall figure**, in both the project and per-layer numbers. They are maintained by hand, so counting their gaps as project debt makes a healthy project read as failing and moves a number nobody can act on.
-
-The full per-locale and per-layer arrays grow with the project, so pass `--output-file` to write them to disk and get back only the summary.
-
-## Referring to Locales
-
-Anywhere a locale is named — `--ref`, `--targets`, `protectedLocales`, the keys of a `write_translations` payload — you may use the locale's **code**, its **language tag**, or its **file name** (extension included). Resolution takes them in that order.
-
-**Prefer the code.** Codes are unique by construction; language tags are not. A project can declare an informal and a formal German that both carry `language: "de-DE"`, in which case `de-DE` is ambiguous — it resolves to the first match, and that depends on the order of your framework's locale array. The precedence rule guarantees only that a locale's own code is never shadowed by a *different* locale's language tag.
-
-A ref that matches nothing is reported rather than silently dropped:
+The binary is `the-i18n-cli`, whatever the package is called.
 
-```json
-{
-  "written": ["common.save"],
-  "filesWritten": 2,
-  "unresolvedLocales": [
-    { "ref": "de-DE-formal", "keys": ["common.save"], "suggestion": "Did you mean \"de-formal\" or \"de-DE\" or \"de-DE-formal.json\"?" }
-  ]
-}
-```
-
-`unresolvedLocales` is the only reliable signal that a write did less than you asked: the key still appears in `written` because the other locales succeeded, and `filesWritten` is short by one. A ref matching several locales is reported the same way under `ambiguousLocales`, naming every candidate and the one that was used. Both fields are absent when every ref resolves uniquely, so a clean write is byte-for-byte what it always was.
-
-Note that a locale's `file` must be given with its extension (`de-DE-formal.json`); the bare stem is not a valid ref.
-
-## Translation Modes
-
-`translate` and `translate-key` run in one of two modes — every result reports which one ran (`mode: "provider" | "agent" | "dry-run"`).
-
-**Provider mode** — pass `--provider` (`openai`, `anthropic`, or `google`) and `--model`; the API key comes from `--apiKey` or the provider's env var (`OPENAI_API_KEY` / `ANTHROPIC_API_KEY` / `GEMINI_API_KEY`). The CLI calls the LLM directly and writes validated results:
-
-```bash
-the-i18n-cli translate --layer root --provider google --model gemini-2.5-flash
-the-i18n-cli translate --layer root --targets de-DE,fr-FR --batchSize 25 --provider openai --model gpt-4o-mini
-```
-
-To reach an endpoint that speaks the same protocol — a gateway, a self-hosted model server, a proxy — add `--baseUrl`, or set `I18N_BASE_URL`, or `providerBaseUrl` in `.i18n-mcp.json`, in that order of precedence:
+## Quick Start
 
 ```bash
-the-i18n-cli translate --layer root --provider openai --model llama3 \
-  --baseUrl http://localhost:11434/v1 --apiKey unused
+the-i18n-cli init                    # write a config from what it detects
+the-i18n-cli status                  # coverage per locale and per layer
+the-i18n-cli missing                 # what is not translated yet
+the-i18n-cli check                   # keys used in code but defined nowhere
+the-i18n-cli remove-orphans          # keys defined but unused (previews by default)
 ```
 
-An API key is still required even when the endpoint ignores it — pass any placeholder for a local server. This overrides the endpoint only, so providers that also change the request shape or auth header (Azure OpenAI among them) are not reachable this way.
-
-`google` has no endpoint override, so a base URL with it is rejected as a configuration error rather than silently ignored.
+→ [Cold start guide](https://fabkho.github.io/the-i18n-kit/getting-started/cold-start) ·
+[every command and flag](https://fabkho.github.io/the-i18n-kit/reference/cli) ·
+[the library API](https://fabkho.github.io/the-i18n-kit/reference/programmatic-api)
 
-**Agent mode** — no `--provider` given. Nothing is translated: keys are reported as `skipped` with reason `no-provider`, and the result explains how to enable provider mode. (In the MCP server, agent mode instead returns fallback contexts for the host agent — see [the-i18n-mcp](https://www.npmjs.com/package/the-i18n-mcp).)
+## Documentation
 
-### Result contract
+| | |
+|---|---|
+| [Commands](https://fabkho.github.io/the-i18n-kit/reference/cli) | Generated from the command definitions |
+| [Configuration](https://fabkho.github.io/the-i18n-kit/configuration/where-config-lives) | Where it lives, precedence, [every field](https://fabkho.github.io/the-i18n-kit/configuration/reference) |
+| [Frameworks](https://fabkho.github.io/the-i18n-kit/frameworks/detection) | How detection works, and what each adapter reads |
+| [Monorepos and layers](https://fabkho.github.io/the-i18n-kit/monorepos/layers) | Why usage in one app does not protect a key in another |
+| [Referring to locales](https://fabkho.github.io/the-i18n-kit/configuration/locale-refs) | Codes, language tags, and why the code is the one to use |
+| [CI/CD](https://fabkho.github.io/the-i18n-kit/ci-cd/github-actions) | The Action and the GitLab template |
 
-Translate results account for every key:
+| [Translation modes](https://fabkho.github.io/the-i18n-kit/concepts/translation-modes) | Provider and agent mode, the result contract, what is validated before writing |
 
-- `translated` — keys written
-- `wouldTranslate` — `--dryRun` only: keys that would be translated
-- `failed` — with a reason: `provider-error`, `omitted-by-model`, `truncated`, `placeholder-mismatch`, `plural-mismatch`, `write-error`
-- `skipped` — with a reason: `no-provider`, `already-translated`, `protected-locale`
-- Invariant: `missing = translated + wouldTranslate + failed + skipped`
+The section below has not moved to the site yet. It is the deepest material
+here, and it is being rewritten against the new extraction architecture — see
+[#358](https://github.com/fabkho/the-i18n-kit/issues/358).
 
-Translations are validated before writing: placeholder parity per vue-i18n plural variant (`{placeholders}`, `@:linked.refs`; `:params` for PHP) and plural variant-count parity with the source. Failing values are rejected into `failed` instead of written.
-
-Locales listed in `protectedLocales` (see Project Config) are excluded from default translate targets and reported as `skipped` with reason `protected-locale`; naming one explicitly in `--targets` overrides the protection with a warning.
 
 ## How Orphan Detection Works
 
@@ -265,104 +96,6 @@ Prefixes assembled in another scope defeat this even when they are literal — a
 
 `remove-orphans` is dry-run by default; run removals as a reviewed MR and treat the report's `uncertainKeys`/`dynamicKeys` sections as the audit trail.
 
-## Supported Frameworks
-
-| Framework | Locale Format | Auto-Detection | Locale Directories Probed |
-|-----------|--------------|----------------|---------------------------|
-| **Nuxt** (v3+) | JSON | `nuxt.config.ts` with `@nuxtjs/i18n` | `i18n/locales/` per app and per layer; honours each layer's `langDir` (default `locales`) |
-| **Laravel** (9+) | PHP arrays or JSON | `artisan`, `composer.json`, `lang/` | `lang/` or `resources/lang/` — PHP subdirectories (`lang/en/*.php`) or flat JSON (`lang/en.json`) |
-| **Vue** (SPA, v3) | JSON | `vue` in dependencies without Nuxt; `vue-i18n` raises confidence | `src/locales`, `locales`, `src/i18n/locales`, `i18n/locales`, `src/plugins/i18n/locales`, `src/i18n` — or a `localeDir`/`messages` path read out of `src/i18n/index.{ts,js}`, `src/plugins/i18n.{ts,js}`, `src/i18n.{ts,js}`, `i18n.{ts,js}` |
-| **React / Next.js** | JSON | `next`, or `react` + `react-dom`, without Vue/Nuxt; `next-intl`, `next-translate`, `next-i18next`, `react-i18next` or `react-intl` raises confidence | `messages`, `public/locales`, `locales`, `src/i18n`, `src/locales`, `i18n` — namespaced (`messages/en/common.json`) or flat (`locales/en.json`). A `next.config.{ts,js,mjs}` using `createNextIntlPlugin` or `next-translate` pins the directory directly |
-| **Generic** | JSON or PHP | `localeDirs` + `defaultLocale` in `.i18n-mcp.json` | Exactly the paths listed in `localeDirs` |
-
-Detection is confidence-scored: the highest-scoring adapter wins, and a `.i18n-mcp.json` carrying both `localeDirs` and `defaultLocale` outscores framework inference. Set `"framework": "vue"` (or any adapter name) to force one adapter.
-
-### Read, not guessed
-
-Where a project already declares its locales, the adapter reads that file rather than inferring from directory order:
-
-| Setup | Read from | Gives |
-|---|---|---|
-| next-intl | `src/i18n/routing.ts` — `defineRouting({ ... })` | `locales`, `defaultLocale` |
-| next-translate | `i18n.js` | `locales`, `defaultLocale` |
-| Next.js Pages Router | `next.config.{ts,js,mjs}` — `i18n: { ... }` | `locales`, `defaultLocale` |
-| Vue + `@intlify/unplugin-vue-i18n` | `vite.config.{ts,js}` — the plugin's `include` | locale directories |
-
-These files are executed, so a `next.config.js` wrapped in `withNextIntl(...)` or `withSentryConfig(...)` may fail without the right environment. That is never fatal: the CLI warns and falls back to the directory probing above, exactly as it behaved before it could read them.
-
-A value you declare yourself always wins over both. To pin the reference locale regardless of what any framework config says:
-
-```ts
-import { defineI18nKitConfig } from 'the-i18n-cli/config'
-
-export default defineI18nKitConfig({
-  defaultLocale: 'en',
-  localeDirs: ['src/locales'],
-})
-```
-
-## Programmatic API
-
-The CLI also exports all operations as a library for use in other tools:
-
-```ts
-import { detectConfig, getMissingTranslations, addTranslations, translateKey } from 'the-i18n-cli'
-
-const config = await detectConfig('/path/to/project')
-const missing = await getMissingTranslations({ projectDir: '/path/to/project' })
-
-await translateKey({
-  projectDir: '/path/to/project',
-  layer: 'root',
-  key: 'common.actions.save',
-  sourceLocale: 'en-US',
-  sourceValue: 'Save',
-  targetLocales: 'all',
-  overwrite: true,
-})
-```
-
-## Project Config
-
-Project-specific context goes in `i18n-kit.config.ts` at your project root, where the editor checks it:
-
-```ts
-import { defineI18nKitConfig } from 'the-i18n-cli/config'
-
-export default defineI18nKitConfig({
-  context: 'B2B SaaS booking platform',
-  glossary: {
-    Booking: "Core concept. Dutch: 'Boeking'.",
-  },
-  protectedLocales: ['en-us', 'de-formal'],
-})
-```
-
-Read directly, with no build step — a `protectedLocales` entry that only takes effect once something has been built is a locale that quietly goes unprotected in a fresh checkout. `.ts`, `.mts`, `.js`, `.mjs` and `.cjs` all work, and the file is looked up from the working directory upwards, the way `eslint` and `tsconfig` resolve theirs.
-
-`.i18n-mcp.json` accepts the same keys and remains supported:
-
-```json
-{
-  "$schema": "node_modules/the-i18n-mcp/schema.json",
-  "context": "B2B SaaS booking platform",
-  "glossary": {
-    "Booking": "Core concept. Dutch: 'Boeking'.",
-    "Resource": "A bookable entity (room, desk, person)"
-  },
-  "translationPrompt": "Professional but approachable tone. Keep translations concise.",
-  "localeNotes": {
-    "de": "Informal German (du)",
-    "de-formal": "Formal German (Sie)"
-  },
-  "protectedLocales": ["en-us", "de-formal"]
-}
-```
-
-Use one or the other. Both may be present, but declaring the same key in both is an error naming both files rather than a silent precedence rule.
-
-See the [full config reference](https://github.com/fabkho/the-i18n-kit#project-config) for all options. `samplingPreferences` is deprecated and ignored (accepted for backward compatibility) — configure a provider instead.
-
 ## License
 
 [MIT](https://github.com/fabkho/the-i18n-kit/blob/main/LICENSE)

package/dist/{_shared-Dv1EW2gy.js → _shared-DFyy3sh8.js}

@@ -1,11 +1,11 @@
 import { n as writeResult } from "./stdout-guard-sJHFWVem.js";
 import { i as toErrorMessage } from "./errors-coI1dhw1.js";
-import { a as resolveProviderBaseUrl, i as createTranslateFn, l as log, s as loadProjectConfig, t as BASE_URL_ENV } from "./providers-BAwPjeCy.js";
+import { a as resolveProviderBaseUrl, i as createTranslateFn, l as log, s as loadProjectConfig, t as BASE_URL_ENV } from "./providers-CHE2ffi6.js";
 import { defineCommand } from "citty";
 //#region src/commands/_shared.ts
 /** Factory for commands that call an operation and output its result. */
 function createCommand(opts) {
-	return defineCommand({
+	return withGates(defineCommand({
 		meta: {
 			name: opts.name,
 			description: opts.description
@@ -17,8 +17,7 @@ function createCommand(opts) {
 		async run({ args }) {
 			try {
 				const result = await opts.run(args);
-				const runFailed = isTotalFailure(result) || (opts.failWhen?.(result) ?? false);
-				const decision = resolveExitCode(result, requestedGates(opts.gates ?? [], args), runFailed);
+				const decision = resolveExitCode(result, requestedGates(opts.gates ?? [], args), isTotalFailure(result));
 				outputResult(withGateReport(result, decision.tripped), args);
 				if (decision.code !== 0) process.exitCode = decision.code;
 			} catch (error) {
@@ -26,7 +25,10 @@ function createCommand(opts) {
 				process.exitCode = 1;
 			}
 		}
-	});
+	}), opts.gates ?? []);
+}
+function withGates(def, gates) {
+	return Object.assign(def, { gates });
 }
 /**
 * Pure decision from an operation result plus the gates the caller requested
@@ -72,19 +74,29 @@ function trips(gate, observed) {
 function requestedGates(specs, args) {
 	const requested = [];
 	for (const spec of specs) {
-		const raw = args[spec.flag];
-		if (raw === void 0 || raw === null || raw === false || raw === "") continue;
-		const threshold = spec.threshold ?? Number(raw);
-		if (!Number.isFinite(threshold)) continue;
-		requested.push({
+		const resolved = spec.flag === void 0 ? {
+			name: spec.name,
+			threshold: spec.threshold
+		} : {
 			name: kebabCase(spec.flag),
+			threshold: thresholdFromFlag(spec, args)
+		};
+		if (resolved.threshold === void 0 || !Number.isFinite(resolved.threshold)) continue;
+		requested.push({
+			name: resolved.name,
 			counter: spec.counter,
 			direction: spec.direction ?? "above",
-			threshold
+			threshold: resolved.threshold
 		});
 	}
 	return requested;
 }
+/** The gate's threshold, or undefined when this invocation did not ask for it. */
+function thresholdFromFlag(spec, args) {
+	const raw = args[spec.flag];
+	if (raw === void 0 || raw === null || raw === false || raw === "") return void 0;
+	return spec.threshold ?? Number(raw);
+}
 /**
 * Name a tripped gate by the flag that requested it, so the JSON says
 * "fail-on-missing" — what the user typed — rather than "failOnMissing".
@@ -245,4 +257,4 @@ function parseJsonArg(value, argName) {
 //#endregion
 export { resolveProviderTranslateFn as a, providerArgs as i, emitErrorResult as n, splitList as o, parseJsonArg as r, createCommand as t };
 
-//# sourceMappingURL=_shared-Dv1EW2gy.js.map
+//# sourceMappingURL=_shared-DFyy3sh8.js.map

package/dist/_shared-DFyy3sh8.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_shared-DFyy3sh8.js","names":[],"sources":["../src/commands/_shared.ts"],"sourcesContent":["import { defineCommand } from 'citty'\nimport type { CommandDef } from 'citty'\nimport { log } from '../utils/logger.js'\nimport { toErrorMessage } from '../utils/errors.js'\nimport { writeResult } from '../utils/stdout-guard.js'\nimport { createTranslateFn, resolveProviderBaseUrl, BASE_URL_ENV } from '../llm/providers.js'\nimport type { LlmProvider } from '../llm/providers.js'\nimport type { TranslateFn } from '../core/types.js'\nimport { loadProjectConfig } from '../config/project-config.js'\n\n/** Factory for commands that call an operation and output its result. */\nexport function createCommand(opts: {\n  name: string\n  description: string\n  args?: Record<string, unknown>\n  /**\n   * CI gates this command evaluates. The factory reads the requesting flag off\n   * args and evaluates every gate uniformly, so no command grows bespoke exit\n   * logic. Declaring a flagged gate does not add its flag — pair each spec\n   * with an entry in `args`. A spec without a flag is always evaluated.\n   */\n  gates?: GateSpec[]\n  /**\n   * Receives citty's parsed args. `any` is deliberate: each command declares\n   * its own `args` shape and citty does not thread that type through to the\n   * handler, so narrowing here only moves the cast into all nineteen command\n   * modules. The shape is validated by citty against the `args` above.\n   */\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- see above\n  run: (args: any) => Promise<unknown>\n}): CommandDef {\n  // Retained on the definition, not only consumed here: the generated CLI\n  // reference has to state which commands fail a build on findings, and a gate\n  // with no flag leaves no trace in the arg descriptions to infer it from.\n  return withGates(defineCommand({\n    meta: { name: opts.name, description: opts.description },\n    args: { ...sharedArgs, ...(opts.args ?? {}) },\n    async run({ args }) {\n      try {\n        const result = await opts.run(args)\n        const decision = resolveExitCode(result, requestedGates(opts.gates ?? [], args), isTotalFailure(result))\n        outputResult(withGateReport(result, decision.tripped), args)\n        // Assign only on a non-zero decision: a clean run must leave the exit\n        // code exactly as it found it, as it did before gates existed.\n        if (decision.code !== EXIT_SUCCESS) process.exitCode = decision.code\n      } catch (error) {\n        emitErrorResult(error, args)\n        process.exitCode = EXIT_RUN_FAILED\n      }\n    },\n  }) as CommandDef, opts.gates ?? [])\n}\n\n/**\n * A command definition carrying the gates its factory evaluates. Read\n * structurally by the reference generator rather than by importing this type,\n * which would make the docs build depend on the CLI's internals.\n */\ninterface GatedCommandDef extends CommandDef {\n  gates: GateSpec[]\n}\n\nfunction withGates(def: CommandDef, gates: GateSpec[]): GatedCommandDef {\n  return Object.assign(def, { gates })\n}\n\n/** The run succeeded and no gate tripped. */\nexport const EXIT_SUCCESS = 0\n/** The run itself failed — a bad API key, an unreadable project, a total translate failure. */\nexport const EXIT_RUN_FAILED = 1\n/** The run succeeded but a requested gate tripped — findings exist, the tool worked. */\nexport const EXIT_GATE_TRIPPED = 2\n\n/**\n * A CI gate a command evaluates. `counter` is the field of `result.summary`\n * carrying the observed value.\n *\n * The two shapes are a union rather than one type with optional halves so the\n * invariants hold at compile time: a flagged gate always has a flag to read\n * its name and threshold from, and a flagless one always carries both itself.\n * Stated as options, `{ counter, threshold }` type-checks and then has no name\n * to report the gate under.\n */\nexport type GateSpec = FlaggedGateSpec | AlwaysOnGateSpec\n\ninterface GateSpecBase {\n  counter: string\n  /** 'above' trips when observed > threshold (default); 'below' when observed < threshold. */\n  direction?: 'above' | 'below'\n}\n\n/**\n * Requested by a flag, and evaluated only when that flag is passed. Omitting\n * `threshold` takes it from the flag's own value, so a boolean flag pairs with\n * `threshold: 0` and a numeric one (`--fail-under 90`) omits it.\n */\nexport interface FlaggedGateSpec extends GateSpecBase {\n  flag: string\n  name?: never\n  threshold?: number\n}\n\n/**\n * Always evaluated, for findings that are a defect rather than a threshold — a\n * key that renders raw in production is not something you opt into caring\n * about. It still reports as a gate: the run succeeded, and what it found is\n * what you are being told about.\n */\nexport interface AlwaysOnGateSpec extends GateSpecBase {\n  flag?: never\n  name: string\n  threshold: number\n}\n\n/** A gate the caller asked for, with its threshold already resolved. */\nexport interface RequestedGate {\n  name: string\n  counter: string\n  direction: 'above' | 'below'\n  threshold: number\n}\n\n/** A gate that tripped, as reported in the result. */\nexport interface TrippedGate extends RequestedGate {\n  observed: number\n}\n\nexport interface ExitDecision {\n  code: typeof EXIT_SUCCESS | typeof EXIT_RUN_FAILED | typeof EXIT_GATE_TRIPPED\n  tripped: TrippedGate[]\n}\n\n/**\n * Pure decision from an operation result plus the gates the caller requested\n * to an exit code. A failed run outranks a tripped gate — exit 1 wins over\n * exit 2 — and gates are not even consulted in that case, because counters\n * from a run that fell over say nothing about the project.\n */\nexport function resolveExitCode(\n  result: unknown,\n  gates: RequestedGate[],\n  runFailed = false,\n): ExitDecision {\n  if (runFailed) return { code: EXIT_RUN_FAILED, tripped: [] }\n\n  const tripped: TrippedGate[] = []\n  for (const gate of gates) {\n    const observed = observedValue(result, gate.counter)\n    if (observed === undefined || !trips(gate, observed)) continue\n    tripped.push({ ...gate, observed })\n  }\n\n  return {\n    code: tripped.length > 0 ? EXIT_GATE_TRIPPED : EXIT_SUCCESS,\n    tripped,\n  }\n}\n\n/**\n * Read a gate's counter off result.summary. Works on inline results and on\n * the { reportFile, summary } shape alike, since both carry the summary.\n * A missing or non-numeric counter yields undefined and never trips a gate.\n */\nfunction observedValue(result: unknown, counter: string): number | undefined {\n  if (result === null || typeof result !== 'object') return undefined\n  const summary = (result as Record<string, unknown>).summary\n  if (summary === null || typeof summary !== 'object') return undefined\n  const value = (summary as Record<string, unknown>)[counter]\n  return typeof value === 'number' && Number.isFinite(value) ? value : undefined\n}\n\nfunction trips(gate: RequestedGate, observed: number): boolean {\n  return gate.direction === 'below' ? observed < gate.threshold : observed > gate.threshold\n}\n\n/** Filter the declared gates down to the ones this invocation asked for. */\nfunction requestedGates(specs: GateSpec[], args: Record<string, unknown>): RequestedGate[] {\n  const requested: RequestedGate[] = []\n  for (const spec of specs) {\n    const resolved = spec.flag === undefined\n      ? { name: spec.name, threshold: spec.threshold }\n      : { name: kebabCase(spec.flag), threshold: thresholdFromFlag(spec, args) }\n    if (resolved.threshold === undefined || !Number.isFinite(resolved.threshold)) continue\n    requested.push({\n      name: resolved.name,\n      counter: spec.counter,\n      direction: spec.direction ?? 'above',\n      threshold: resolved.threshold,\n    })\n  }\n  return requested\n}\n\n/** The gate's threshold, or undefined when this invocation did not ask for it. */\nfunction thresholdFromFlag(spec: FlaggedGateSpec, args: Record<string, unknown>): number | undefined {\n  const raw = args[spec.flag]\n  if (raw === undefined || raw === null || raw === false || raw === '') return undefined\n  return spec.threshold ?? Number(raw)\n}\n\n/**\n * Name a tripped gate by the flag that requested it, so the JSON says\n * \"fail-on-missing\" — what the user typed — rather than \"failOnMissing\".\n */\nfunction kebabCase(flag: string): string {\n  return flag.replace(/[A-Z]/g, c => `-${c.toLowerCase()}`)\n}\n\n/**\n * Attach the gate report without disturbing the rest of the result: consumers\n * parsing today's shape keep working, and a run where nothing tripped is\n * byte-for-byte what it was before gates existed.\n */\nfunction withGateReport(result: unknown, tripped: TrippedGate[]): unknown {\n  if (tripped.length === 0) return result\n  if (result === null || typeof result !== 'object' || Array.isArray(result)) return result\n  return { ...(result as Record<string, unknown>), gatesTripped: tripped }\n}\n\n/**\n * True when a run completed but achieved nothing: failures present and zero\n * successes. Covers translate-missing-style results (summary.totalFailed /\n * summary.totalTranslated) and translate-key-style results (top-level\n * failed[] / translated[]). Results without those fields are never a\n * total failure, so unrelated commands are unaffected.\n */\nexport function isTotalFailure(result: unknown): boolean {\n  if (result === null || typeof result !== 'object') return false\n  const r = result as Record<string, unknown>\n\n  const summary = r.summary\n  if (summary !== null && typeof summary === 'object') {\n    const s = summary as Record<string, unknown>\n    if (typeof s.totalFailed === 'number' && typeof s.totalTranslated === 'number') {\n      return s.totalFailed > 0 && s.totalTranslated === 0\n    }\n  }\n\n  if (Array.isArray(r.failed) && Array.isArray(r.translated)) {\n    return r.failed.length > 0 && r.translated.length === 0\n  }\n\n  return false\n}\n\nconst sharedArgs = {\n  projectDir: {\n    type: 'string' as const,\n    alias: 'd',\n    description: 'Project directory (default: cwd)',\n  },\n  json: {\n    type: 'boolean' as const,\n    description: 'Output as JSON (default for non-TTY)',\n    default: false,\n  },\n}\n\n/** Output result — stdout always carries the result, machine-parseable when piped/--json */\nfunction outputResult(data: unknown, args: { json?: boolean }): void {\n  const jsonMode = args.json || !process.stdout.isTTY\n  if (\n    !jsonMode &&\n    data !== null &&\n    typeof data === 'object' &&\n    'reportFile' in (data as Record<string, unknown>)\n  ) {\n    const { reportFile, ...rest } = data as Record<string, unknown>\n    log.info(`Wrote report to: ${reportFile}`)\n    writeResult(JSON.stringify(rest, null, 2) + '\\n')\n    return\n  }\n  // JSON mode emits the full result (including reportFile when present) as pure JSON\n  writeResult(JSON.stringify(data, null, 2) + '\\n')\n}\n\n/**\n * Failure output. In JSON mode stdout must still carry parseable JSON —\n * consumers pipe it into jq, and zero bytes is a parse error — so the\n * structured error object IS the result on stdout; the human-readable\n * message goes to stderr in every mode. Exit code stays non-zero (callers\n * set it).\n */\nexport function emitErrorResult(error: unknown, args: { json?: boolean }): void {\n  log.error(toErrorMessage(error))\n  const jsonMode = args.json || !process.stdout.isTTY\n  if (!jsonMode) return\n  const payload = { error: { code: errorCode(error), message: toErrorMessage(error) } }\n  writeResult(JSON.stringify(payload, null, 2) + '\\n')\n}\n\n/** ToolError/FileIOError carry codes; Node errors expose e.g. ENOENT. */\nfunction errorCode(error: unknown): string {\n  if (error instanceof Error) {\n    const code = (error as { code?: unknown }).code\n    if (typeof code === 'string') return code\n    if (error.name === 'ConfigError') return 'CONFIG_ERROR'\n  }\n  return 'UNKNOWN_ERROR'\n}\n\n/** Provider selection flags shared by the translate commands. */\nexport const providerArgs = {\n  provider: { type: 'string' as const, description: 'LLM provider: \"openai\", \"anthropic\", or \"google\". Required for automatic translation.', valueHint: 'openai|anthropic|google' },\n  model: { type: 'string' as const, description: 'Model name (required when --provider is set)' },\n  apiKey: { type: 'string' as const, description: 'API key (falls back to OPENAI_API_KEY / ANTHROPIC_API_KEY / GEMINI_API_KEY env).' },\n  baseUrl: { type: 'string' as const, description: `Provider base URL for gateways, self-hosted models and proxies speaking the provider's protocol. Falls back to ${BASE_URL_ENV}, then providerBaseUrl in .i18n-mcp.json. Not supported by \"google\".` },\n}\n\n/**\n * Build a TranslateFn from the provider flags, or undefined when no provider\n * was given (agent mode). The base URL resolves flag > env > project config;\n * the config file is only read when neither of the first two is set, so a\n * fully-flagged invocation never depends on config discovery.\n */\nexport async function resolveProviderTranslateFn(args: {\n  provider?: string\n  model?: string\n  apiKey?: string\n  baseUrl?: string\n  projectDir?: string\n}): Promise<TranslateFn | undefined> {\n  if (!args.provider) return undefined\n  if (!args.model) {\n    throw new Error('--model is required when --provider is set')\n  }\n\n  let baseUrl = resolveProviderBaseUrl({ flag: args.baseUrl, env: process.env[BASE_URL_ENV] })\n  if (!baseUrl) {\n    const projectConfig = await loadProjectConfig(args.projectDir ?? process.cwd())\n    baseUrl = resolveProviderBaseUrl({ config: projectConfig?.providerBaseUrl })\n  }\n  if (baseUrl) log.debug(`Provider base URL: ${redactBaseUrl(baseUrl)}`)\n\n  return createTranslateFn({\n    provider: args.provider as LlmProvider,\n    model: args.model,\n    apiKey: args.apiKey,\n    baseUrl,\n  })\n}\n\n/**\n * Strip anything secret-shaped from a base URL before it reaches a log.\n * Gateways are routinely addressed as https://user:pass@host or with the key\n * in a query parameter, so keep only origin and path.\n */\nexport function redactBaseUrl(raw: string): string {\n  let url: URL\n  try {\n    url = new URL(raw)\n  } catch {\n    return '<unparseable base URL>'\n  }\n  const credentials = url.username || url.password ? '<redacted>@' : ''\n  const query = url.search || url.hash ? ' (query redacted)' : ''\n  return `${url.protocol}//${credentials}${url.host}${url.pathname}${query}`\n}\n\n/** Split a comma-separated string into a trimmed array, or return undefined */\nexport function splitList(val: string | undefined): string[] | undefined {\n  if (!val) return undefined\n  return val.split(',').map(s => s.trim()).filter(Boolean)\n}\n\n/** Parse a JSON string with a user-friendly error */\nexport function parseJsonArg<T = Record<string, Record<string, string>>>(\n  value: string,\n  argName: string,\n): T {\n  try {\n    return JSON.parse(value) as T\n  } catch (err) {\n    const detail = err instanceof SyntaxError ? err.message : String(err)\n    throw new Error(`Invalid JSON in --${argName}: ${detail}`)\n  }\n}\n"],"mappings":";;;;;;AAWA,SAAgB,cAAc,MAmBf;AAIb,QAAO,UAAU,cAAc;EAC7B,MAAM;GAAE,MAAM,KAAK;GAAM,aAAa,KAAK;GAAa;EACxD,MAAM;GAAE,GAAG;GAAY,GAAI,KAAK,QAAQ,EAAE;GAAG;EAC7C,MAAM,IAAI,EAAE,QAAQ;AAClB,OAAI;IACF,MAAM,SAAS,MAAM,KAAK,IAAI,KAAK;IACnC,MAAM,WAAW,gBAAgB,QAAQ,eAAe,KAAK,SAAS,EAAE,EAAE,KAAK,EAAE,eAAe,OAAO,CAAC;AACxG,iBAAa,eAAe,QAAQ,SAAS,QAAQ,EAAE,KAAK;AAG5D,QAAI,SAAS,SAAA,EAAuB,SAAQ,WAAW,SAAS;YACzD,OAAO;AACd,oBAAgB,OAAO,KAAK;AAC5B,YAAQ,WAAA;;;EAGb,CAAC,EAAgB,KAAK,SAAS,EAAE,CAAC;;AAYrC,SAAS,UAAU,KAAiB,OAAoC;AACtE,QAAO,OAAO,OAAO,KAAK,EAAE,OAAO,CAAC;;;;;;;;AA2EtC,SAAgB,gBACd,QACA,OACA,YAAY,OACE;AACd,KAAI,UAAW,QAAO;EAAE,MAAA;EAAuB,SAAS,EAAE;EAAE;CAE5D,MAAM,UAAyB,EAAE;AACjC,MAAK,MAAM,QAAQ,OAAO;EACxB,MAAM,WAAW,cAAc,QAAQ,KAAK,QAAQ;AACpD,MAAI,aAAa,KAAA,KAAa,CAAC,MAAM,MAAM,SAAS,CAAE;AACtD,UAAQ,KAAK;GAAE,GAAG;GAAM;GAAU,CAAC;;AAGrC,QAAO;EACL,MAAM,QAAQ,SAAS,IAAA,IAAA;EACvB;EACD;;;;;;;AAQH,SAAS,cAAc,QAAiB,SAAqC;AAC3E,KAAI,WAAW,QAAQ,OAAO,WAAW,SAAU,QAAO,KAAA;CAC1D,MAAM,UAAW,OAAmC;AACpD,KAAI,YAAY,QAAQ,OAAO,YAAY,SAAU,QAAO,KAAA;CAC5D,MAAM,QAAS,QAAoC;AACnD,QAAO,OAAO,UAAU,YAAY,OAAO,SAAS,MAAM,GAAG,QAAQ,KAAA;;AAGvE,SAAS,MAAM,MAAqB,UAA2B;AAC7D,QAAO,KAAK,cAAc,UAAU,WAAW,KAAK,YAAY,WAAW,KAAK;;;AAIlF,SAAS,eAAe,OAAmB,MAAgD;CACzF,MAAM,YAA6B,EAAE;AACrC,MAAK,MAAM,QAAQ,OAAO;EACxB,MAAM,WAAW,KAAK,SAAS,KAAA,IAC3B;GAAE,MAAM,KAAK;GAAM,WAAW,KAAK;GAAW,GAC9C;GAAE,MAAM,UAAU,KAAK,KAAK;GAAE,WAAW,kBAAkB,MAAM,KAAK;GAAE;AAC5E,MAAI,SAAS,cAAc,KAAA,KAAa,CAAC,OAAO,SAAS,SAAS,UAAU,CAAE;AAC9E,YAAU,KAAK;GACb,MAAM,SAAS;GACf,SAAS,KAAK;GACd,WAAW,KAAK,aAAa;GAC7B,WAAW,SAAS;GACrB,CAAC;;AAEJ,QAAO;;;AAIT,SAAS,kBAAkB,MAAuB,MAAmD;CACnG,MAAM,MAAM,KAAK,KAAK;AACtB,KAAI,QAAQ,KAAA,KAAa,QAAQ,QAAQ,QAAQ,SAAS,QAAQ,GAAI,QAAO,KAAA;AAC7E,QAAO,KAAK,aAAa,OAAO,IAAI;;;;;;AAOtC,SAAS,UAAU,MAAsB;AACvC,QAAO,KAAK,QAAQ,WAAU,MAAK,IAAI,EAAE,aAAa,GAAG;;;;;;;AAQ3D,SAAS,eAAe,QAAiB,SAAiC;AACxE,KAAI,QAAQ,WAAW,EAAG,QAAO;AACjC,KAAI,WAAW,QAAQ,OAAO,WAAW,YAAY,MAAM,QAAQ,OAAO,CAAE,QAAO;AACnF,QAAO;EAAE,GAAI;EAAoC,cAAc;EAAS;;;;;;;;;AAU1E,SAAgB,eAAe,QAA0B;AACvD,KAAI,WAAW,QAAQ,OAAO,WAAW,SAAU,QAAO;CAC1D,MAAM,IAAI;CAEV,MAAM,UAAU,EAAE;AAClB,KAAI,YAAY,QAAQ,OAAO,YAAY,UAAU;EACnD,MAAM,IAAI;AACV,MAAI,OAAO,EAAE,gBAAgB,YAAY,OAAO,EAAE,oBAAoB,SACpE,QAAO,EAAE,cAAc,KAAK,EAAE,oBAAoB;;AAItD,KAAI,MAAM,QAAQ,EAAE,OAAO,IAAI,MAAM,QAAQ,EAAE,WAAW,CACxD,QAAO,EAAE,OAAO,SAAS,KAAK,EAAE,WAAW,WAAW;AAGxD,QAAO;;AAGT,MAAM,aAAa;CACjB,YAAY;EACV,MAAM;EACN,OAAO;EACP,aAAa;EACd;CACD,MAAM;EACJ,MAAM;EACN,aAAa;EACb,SAAS;EACV;CACF;;AAGD,SAAS,aAAa,MAAe,MAAgC;AAEnE,KACE,EAFe,KAAK,QAAQ,CAAC,QAAQ,OAAO,UAG5C,SAAS,QACT,OAAO,SAAS,YAChB,gBAAiB,MACjB;EACA,MAAM,EAAE,YAAY,GAAG,SAAS;AAChC,MAAI,KAAK,oBAAoB,aAAa;AAC1C,cAAY,KAAK,UAAU,MAAM,MAAM,EAAE,GAAG,KAAK;AACjD;;AAGF,aAAY,KAAK,UAAU,MAAM,MAAM,EAAE,GAAG,KAAK;;;;;;;;;AAUnD,SAAgB,gBAAgB,OAAgB,MAAgC;AAC9E,KAAI,MAAM,eAAe,MAAM,CAAC;AAEhC,KAAI,EADa,KAAK,QAAQ,CAAC,QAAQ,OAAO,OAC/B;CACf,MAAM,UAAU,EAAE,OAAO;EAAE,MAAM,UAAU,MAAM;EAAE,SAAS,eAAe,MAAM;EAAE,EAAE;AACrF,aAAY,KAAK,UAAU,SAAS,MAAM,EAAE,GAAG,KAAK;;;AAItD,SAAS,UAAU,OAAwB;AACzC,KAAI,iBAAiB,OAAO;EAC1B,MAAM,OAAQ,MAA6B;AAC3C,MAAI,OAAO,SAAS,SAAU,QAAO;AACrC,MAAI,MAAM,SAAS,cAAe,QAAO;;AAE3C,QAAO;;;AAIT,MAAa,eAAe;CAC1B,UAAU;EAAE,MAAM;EAAmB,aAAa;EAAyF,WAAW;EAA2B;CACjL,OAAO;EAAE,MAAM;EAAmB,aAAa;EAAgD;CAC/F,QAAQ;EAAE,MAAM;EAAmB,aAAa;EAAoF;CACpI,SAAS;EAAE,MAAM;EAAmB,aAAa,kHAAkH,aAAa;EAAuE;CACxP;;;;;;;AAQD,eAAsB,2BAA2B,MAMZ;AACnC,KAAI,CAAC,KAAK,SAAU,QAAO,KAAA;AAC3B,KAAI,CAAC,KAAK,MACR,OAAM,IAAI,MAAM,6CAA6C;CAG/D,IAAI,UAAU,uBAAuB;EAAE,MAAM,KAAK;EAAS,KAAK,QAAQ,IAAI;EAAe,CAAC;AAC5F,KAAI,CAAC,QAEH,WAAU,uBAAuB,EAAE,SADb,MAAM,kBAAkB,KAAK,cAAc,QAAQ,KAAK,CAAC,GACrB,iBAAiB,CAAC;AAE9E,KAAI,QAAS,KAAI,MAAM,sBAAsB,cAAc,QAAQ,GAAG;AAEtE,QAAO,kBAAkB;EACvB,UAAU,KAAK;EACf,OAAO,KAAK;EACZ,QAAQ,KAAK;EACb;EACD,CAAC;;;;;;;AAQJ,SAAgB,cAAc,KAAqB;CACjD,IAAI;AACJ,KAAI;AACF,QAAM,IAAI,IAAI,IAAI;SACZ;AACN,SAAO;;CAET,MAAM,cAAc,IAAI,YAAY,IAAI,WAAW,gBAAgB;CACnE,MAAM,QAAQ,IAAI,UAAU,IAAI,OAAO,sBAAsB;AAC7D,QAAO,GAAG,IAAI,SAAS,IAAI,cAAc,IAAI,OAAO,IAAI,WAAW;;;AAIrE,SAAgB,UAAU,KAA+C;AACvE,KAAI,CAAC,IAAK,QAAO,KAAA;AACjB,QAAO,IAAI,MAAM,IAAI,CAAC,KAAI,MAAK,EAAE,MAAM,CAAC,CAAC,OAAO,QAAQ;;;AAI1D,SAAgB,aACd,OACA,SACG;AACH,KAAI;AACF,SAAO,KAAK,MAAM,MAAM;UACjB,KAAK;EACZ,MAAM,SAAS,eAAe,cAAc,IAAI,UAAU,OAAO,IAAI;AACrE,QAAM,IAAI,MAAM,qBAAqB,QAAQ,IAAI,SAAS"}

package/dist/{add-BvXrJkqZ.js → add-C-qs8iBa.js}

@@ -1,8 +1,8 @@
 import "./stdout-guard-sJHFWVem.js";
-import { c as addTranslations } from "./operations-BCJd7in3.js";
-import "./providers-BAwPjeCy.js";
-import "./php-reader-DuZ0Hyl_.js";
-import { r as parseJsonArg, t as createCommand } from "./_shared-Dv1EW2gy.js";
+import { c as addTranslations } from "./operations-CTo44gPu.js";
+import "./providers-CHE2ffi6.js";
+import "./php-reader-3Fgw80zK.js";
+import { r as parseJsonArg, t as createCommand } from "./_shared-DFyy3sh8.js";
 //#region src/commands/add.ts
 var add_default = createCommand({
 	name: "add",
@@ -37,4 +37,4 @@ var add_default = createCommand({
 //#endregion
 export { add_default as default };
 
-//# sourceMappingURL=add-BvXrJkqZ.js.map
+//# sourceMappingURL=add-C-qs8iBa.js.map

package/dist/{add-BvXrJkqZ.js.map → add-C-qs8iBa.js.map}

@@ -1 +1 @@
-{"version":3,"file":"add-BvXrJkqZ.js","names":[],"sources":["../src/commands/add.ts"],"sourcesContent":["import { createCommand, parseJsonArg } from './_shared.js'\nimport { addTranslations } from '../core/operations.js'\n\nexport default createCommand({\n  name: 'add',\n  description: 'Add new translation keys (skips keys that already exist)',\n  args: {\n    layer: { type: 'string', description: 'Layer name', required: true },\n    translations: { type: 'string', description: 'JSON: { \"key\": { \"en\": \"val\", \"de\": \"val\" } }', required: true },\n    dryRun: { type: 'boolean', description: 'Preview changes without writing', default: false },\n  },\n  async run(args) {\n    const translations = parseJsonArg<Record<string, Record<string, string>>>(args.translations, 'translations')\n    return addTranslations({ layer: args.layer, translations, dryRun: args.dryRun, projectDir: args.projectDir })\n  },\n})\n"],"mappings":";;;;;;AAGA,IAAA,cAAe,cAAc;CAC3B,MAAM;CACN,aAAa;CACb,MAAM;EACJ,OAAO;GAAE,MAAM;GAAU,aAAa;GAAc,UAAU;GAAM;EACpE,cAAc;GAAE,MAAM;GAAU,aAAa;GAAiD,UAAU;GAAM;EAC9G,QAAQ;GAAE,MAAM;GAAW,aAAa;GAAmC,SAAS;GAAO;EAC5F;CACD,MAAM,IAAI,MAAM;EACd,MAAM,eAAe,aAAqD,KAAK,cAAc,eAAe;AAC5G,SAAO,gBAAgB;GAAE,OAAO,KAAK;GAAO;GAAc,QAAQ,KAAK;GAAQ,YAAY,KAAK;GAAY,CAAC;;CAEhH,CAAC"}
+{"version":3,"file":"add-C-qs8iBa.js","names":[],"sources":["../src/commands/add.ts"],"sourcesContent":["import { createCommand, parseJsonArg } from './_shared.js'\nimport { addTranslations } from '../core/operations.js'\n\nexport default createCommand({\n  name: 'add',\n  description: 'Add new translation keys (skips keys that already exist)',\n  args: {\n    layer: { type: 'string', description: 'Layer name', required: true },\n    translations: { type: 'string', description: 'JSON: { \"key\": { \"en\": \"val\", \"de\": \"val\" } }', required: true },\n    dryRun: { type: 'boolean', description: 'Preview changes without writing', default: false },\n  },\n  async run(args) {\n    const translations = parseJsonArg<Record<string, Record<string, string>>>(args.translations, 'translations')\n    return addTranslations({ layer: args.layer, translations, dryRun: args.dryRun, projectDir: args.projectDir })\n  },\n})\n"],"mappings":";;;;;;AAGA,IAAA,cAAe,cAAc;CAC3B,MAAM;CACN,aAAa;CACb,MAAM;EACJ,OAAO;GAAE,MAAM;GAAU,aAAa;GAAc,UAAU;GAAM;EACpE,cAAc;GAAE,MAAM;GAAU,aAAa;GAAiD,UAAU;GAAM;EAC9G,QAAQ;GAAE,MAAM;GAAW,aAAa;GAAmC,SAAS;GAAO;EAC5F;CACD,MAAM,IAAI,MAAM;EACd,MAAM,eAAe,aAAqD,KAAK,cAAc,eAAe;AAC5G,SAAO,gBAAgB;GAAE,OAAO,KAAK;GAAO;GAAc,QAAQ,KAAK;GAAQ,YAAY,KAAK;GAAY,CAAC;;CAEhH,CAAC"}

package/dist/bin.js

@@ -3,7 +3,12 @@ import { t as guardStdout } from "./stdout-guard-sJHFWVem.js";
 //#region src/bin.ts
 const args = process.argv.slice(2);
 if (!(args.includes("--help") || args.includes("-h") || args.includes("--version") || args.includes("-v"))) guardStdout();
-const { runCli } = await import("./cli-CiX4llY1.js");
+const { renameNotice } = await import("./rename-notice-Cx1vuTRz.js");
+const { createRequire } = await import("node:module");
+const { name } = createRequire(import.meta.url)("../package.json");
+const notice = renameNotice(name);
+if (notice) process.stderr.write(`[the-i18n-cli] ${notice}\n`);
+const { runCli } = await import("./cli-DsFuVJNP.js");
 await runCli();
 //#endregion
 export {};

package/dist/bin.js.map

@@ -1 +1 @@
-{"version":3,"file":"bin.js","names":[],"sources":["../src/bin.ts"],"sourcesContent":["#!/usr/bin/env node\n// Install the stdout guard before anything else loads, so third-party logs\n// (e.g. Nuxt modules during config detection) can never pollute the\n// machine-readable output on stdout. Help/version invocations skip the guard:\n// they never load third-party code and their output belongs on stdout\n// (mirrors the flag check in cli.ts, which cannot be imported before the\n// guard decision).\nimport { guardStdout } from './utils/stdout-guard.js'\n\nconst args = process.argv.slice(2)\nconst isHelpOrVersion = args.includes('--help') || args.includes('-h')\n  || args.includes('--version') || args.includes('-v')\nif (!isHelpOrVersion) {\n  guardStdout()\n}\nconst { runCli } = await import('./cli.js')\nawait runCli()\n"],"mappings":";;;AASA,MAAM,OAAO,QAAQ,KAAK,MAAM,EAAE;AAGlC,IAAI,EAFoB,KAAK,SAAS,SAAS,IAAI,KAAK,SAAS,KAAK,IACjE,KAAK,SAAS,YAAY,IAAI,KAAK,SAAS,KAAK,EAEpD,cAAa;AAEf,MAAM,EAAE,WAAW,MAAM,OAAO;AAChC,MAAM,QAAQ"}
+{"version":3,"file":"bin.js","names":[],"sources":["../src/bin.ts"],"sourcesContent":["#!/usr/bin/env node\n// Install the stdout guard before anything else loads, so third-party logs\n// (e.g. Nuxt modules during config detection) can never pollute the\n// machine-readable output on stdout. Help/version invocations skip the guard:\n// they never load third-party code and their output belongs on stdout\n// (mirrors the flag check in cli.ts, which cannot be imported before the\n// guard decision).\nimport { guardStdout } from './utils/stdout-guard.js'\n\nconst args = process.argv.slice(2)\nconst isHelpOrVersion = args.includes('--help') || args.includes('-h')\n  || args.includes('--version') || args.includes('-v')\nif (!isHelpOrVersion) {\n  guardStdout()\n}\n// Renamed packages announce themselves once per invocation, on stderr so the\n// JSON on stdout is untouched. The package reads its own name, so this is\n// silent when running as @the-i18n-kit/cli (#315).\nconst { renameNotice } = await import('./utils/rename-notice.js')\nconst { createRequire } = await import('node:module')\nconst { name } = createRequire(import.meta.url)('../package.json') as { name: string }\nconst notice = renameNotice(name)\nif (notice) process.stderr.write(`[the-i18n-cli] ${notice}\\n`)\n\nconst { runCli } = await import('./cli.js')\nawait runCli()\n"],"mappings":";;;AASA,MAAM,OAAO,QAAQ,KAAK,MAAM,EAAE;AAGlC,IAAI,EAFoB,KAAK,SAAS,SAAS,IAAI,KAAK,SAAS,KAAK,IACjE,KAAK,SAAS,YAAY,IAAI,KAAK,SAAS,KAAK,EAEpD,cAAa;AAKf,MAAM,EAAE,iBAAiB,MAAM,OAAO;AACtC,MAAM,EAAE,kBAAkB,MAAM,OAAO;AACvC,MAAM,EAAE,SAAS,cAAc,OAAO,KAAK,IAAI,CAAC,kBAAkB;AAClE,MAAM,SAAS,aAAa,KAAK;AACjC,IAAI,OAAQ,SAAQ,OAAO,MAAM,kBAAkB,OAAO,IAAI;AAE9D,MAAM,EAAE,WAAW,MAAM,OAAO;AAChC,MAAM,QAAQ"}

package/dist/{check-9dcNfHtC.js → check-BI1orjXb.js}

@@ -1,24 +1,12 @@
 import "./stdout-guard-sJHFWVem.js";
-import { t as checkUndefinedKeys } from "./operations-BCJd7in3.js";
-import "./providers-BAwPjeCy.js";
-import "./php-reader-DuZ0Hyl_.js";
-import { t as createCommand } from "./_shared-Dv1EW2gy.js";
+import { t as checkUndefinedKeys } from "./operations-CTo44gPu.js";
+import "./providers-CHE2ffi6.js";
+import "./php-reader-3Fgw80zK.js";
+import { t as createCommand } from "./_shared-DFyy3sh8.js";
 //#region src/commands/check.ts
-/**
-* CI gate for `check`: any undefined-key finding fails the build.
-* Reads summary.undefinedCount, so it works for inline results and for
-* the { reportFile, summary } shape alike. Uncertain findings never fail.
-*/
-function hasUndefinedKeys(result) {
-	if (result === null || typeof result !== "object") return false;
-	const summary = result.summary;
-	if (summary === null || typeof summary !== "object") return false;
-	const count = summary.undefinedCount;
-	return typeof count === "number" && count > 0;
-}
 var check_default = createCommand({
 	name: "check",
-	description: "Find keys referenced in code but defined in no consumed locale layer (they render as raw keys); exits non-zero when any are found",
+	description: "Find keys referenced in code but defined in no consumed locale layer (they render as raw keys); findings trip an always-on gate and exit 2, distinct from exit 1 for a run that failed",
 	args: {
 		locale: {
 			type: "string",
@@ -33,7 +21,11 @@ var check_default = createCommand({
 			description: "Also write the findings as a GitLab Code Quality (CodeClimate) JSON report to this file path"
 		}
 	},
-	failWhen: hasUndefinedKeys,
+	gates: [{
+		name: "undefined-keys",
+		counter: "undefinedCount",
+		threshold: 0
+	}],
 	async run(args) {
 		return checkUndefinedKeys({
 			locale: args.locale,
@@ -46,4 +38,4 @@ var check_default = createCommand({
 //#endregion
 export { check_default as default };
 
-//# sourceMappingURL=check-9dcNfHtC.js.map
+//# sourceMappingURL=check-BI1orjXb.js.map

package/dist/check-BI1orjXb.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-BI1orjXb.js","names":[],"sources":["../src/commands/check.ts"],"sourcesContent":["import { createCommand } from './_shared.js'\nimport { checkUndefinedKeys } from '../core/operations.js'\n\nexport default createCommand({\n  name: 'check',\n  description: 'Find keys referenced in code but defined in no consumed locale layer (they render as raw keys); findings trip an always-on gate and exit 2, distinct from exit 1 for a run that failed',\n  args: {\n    locale: { type: 'string', description: 'Reference locale to resolve definitions in (default: project default)' },\n    outputFile: { type: 'string', description: 'Write full output to this file path and return only a summary (useful for large outputs)' },\n    codequalityOutput: { type: 'string', description: 'Also write the findings as a GitLab Code Quality (CodeClimate) JSON report to this file path' },\n  },\n  /**\n   * Always on, and a gate rather than a run failure. A key that renders raw in\n   * production is a defect, so there is no flag to opt into caring about it —\n   * but it is still a finding, and reporting it as exit 1 left the caller\n   * unable to tell an undefined key from a scan that fell over (#369).\n   *\n   * Reads summary.undefinedCount, so it trips on inline results and on the\n   * { reportFile, summary } shape alike. Uncertain findings never trip it.\n   */\n  gates: [{ name: 'undefined-keys', counter: 'undefinedCount', threshold: 0 }],\n  async run(args) {\n    return checkUndefinedKeys({\n      locale: args.locale,\n      projectDir: args.projectDir,\n      outputFile: args.outputFile,\n      codequalityOutput: args.codequalityOutput,\n    })\n  },\n})\n"],"mappings":";;;;;;AAGA,IAAA,gBAAe,cAAc;CAC3B,MAAM;CACN,aAAa;CACb,MAAM;EACJ,QAAQ;GAAE,MAAM;GAAU,aAAa;GAAyE;EAChH,YAAY;GAAE,MAAM;GAAU,aAAa;GAA4F;EACvI,mBAAmB;GAAE,MAAM;GAAU,aAAa;GAAgG;EACnJ;CAUD,OAAO,CAAC;EAAE,MAAM;EAAkB,SAAS;EAAkB,WAAW;EAAG,CAAC;CAC5E,MAAM,IAAI,MAAM;AACd,SAAO,mBAAmB;GACxB,QAAQ,KAAK;GACb,YAAY,KAAK;GACjB,YAAY,KAAK;GACjB,mBAAmB,KAAK;GACzB,CAAC;;CAEL,CAAC"}