create-quiver 0.15.2 → 0.15.4

package/specs/quiver-v37-cli-i18n-foundation/pr.md

@@ -0,0 +1,97 @@
+## Title
+
+Quiver v37 CLI i18n foundation
+
+## Summary
+
+- Adds the shared foundation for Spanish and English CLI output.
+- Persists the configured language so users do not need flags after setup.
+- Keeps JSON output stable and non-localized.
+- Adds the approved follow-up i18n specs v38-v43 as the program roadmap.
+
+## Scope
+
+- Language resolution and config persistence.
+- Message catalogs and translation helpers.
+- `config language` commands.
+- Localized help/parser/early errors.
+- Docs and validation for the i18n foundation.
+- Roadmap specs for read-only commands, setup/onboarding, spec/slice workflows, AI lifecycle, generated docs, and release readiness.
+
+## Files
+
+- `src/create-quiver/index.js`
+- `src/create-quiver/commands/config.js`
+- `src/create-quiver/lib/i18n/**`
+- `tests/commands/cli-contract.test.js`
+- `tests/commands/config-language.test.js`
+- `tests/lib/i18n-catalog.test.js`
+- `tests/lib/i18n-language.test.js`
+- `docs/CLI_UX_GUIDE.md`
+- `docs/reference/commands.md`
+- `docs/INDEX.md`
+- `specs/quiver-v37-cli-i18n-foundation/**`
+- `specs/quiver-v38-cli-i18n-read-only-commands/**`
+- `specs/quiver-v39-cli-i18n-setup-onboarding/**`
+- `specs/quiver-v40-cli-i18n-spec-slice-workflows/**`
+- `specs/quiver-v41-cli-i18n-ai-lifecycle/**`
+- `specs/quiver-v42-cli-i18n-generated-docs/**`
+- `specs/quiver-v43-cli-i18n-audit-release-readiness/**`
+
+## How to Test (DETAILED - REQUIRED)
+
+### Required Environment
+
+- Node.js and npm available.
+- Repository checked out on macOS, Linux, or Windows-compatible shell.
+
+### Worktree Access
+
+- This PR is based on `main`.
+- No external services are required for local validation.
+
+### Run the Project
+
+```bash
+node bin/create-quiver.js --help
+node bin/create-quiver.js --lang es --help
+node bin/create-quiver.js config language show
+node bin/create-quiver.js config language set es --json
+node bin/create-quiver.js version --json
+```
+
+### Use Cases
+
+1. Run `node bin/create-quiver.js --lang es --help` and verify headings/descriptions are in Spanish while commands and flags remain exact.
+2. Run `QUIVER_LANG=es node bin/create-quiver.js --unknown-flag` and verify the early parser error is localized.
+3. Run `node bin/create-quiver.js version --json --lang es` and verify stdout remains parseable JSON with stable field names.
+4. Run `node bin/create-quiver.js config language set es` in a temp project and verify `.quiver/config.json` stores `language: "es"` without deleting existing keys.
+
+### Technical Verification
+
+```bash
+node --test tests/**/*.test.js
+git diff --check
+node bin/create-quiver.js spec validate specs/quiver-v37-cli-i18n-foundation --strict
+npm run package:quiver
+npm run smoke:create-quiver
+```
+
+## Evidence
+
+- `node --test tests/**/*.test.js` passed with 549 tests.
+- `git diff --check` passed.
+- `node bin/create-quiver.js spec validate specs/quiver-v37-cli-i18n-foundation --strict` passed.
+- `npm run package:quiver` passed.
+- `npm run smoke:create-quiver` passed.
+
+## Rollback
+
+- Revert this PR.
+- Remove `.quiver/config.json` language entries only if a local project used the new `config language set` command during manual testing.
+
+## Risks / Notes
+
+- Parser-level errors can bypass command-local i18n if the foundation is not wired before dispatch.
+- JSON contracts must remain stable across languages.
+- v38-v43 are specs only in this PR; command-specific migrations remain pending by design.

package/specs/quiver-v37-cli-i18n-foundation/slices/slice-00-foundation-and-program-roadmap/CLOSURE_BRIEF.md

@@ -0,0 +1,10 @@
+# CLOSURE_BRIEF - slice-00 Foundation and program roadmap
+
+## Summary
+
+Documentation package created. No runtime implementation was performed.
+
+## Validation
+
+- Pending `npx create-quiver spec validate specs/quiver-v37-cli-i18n-foundation --strict`.
+- Pending `git diff --check`.

package/specs/quiver-v37-cli-i18n-foundation/slices/slice-00-foundation-and-program-roadmap/EXECUTION_BRIEF.md

@@ -0,0 +1,22 @@
+# EXECUTION_BRIEF - slice-00 Foundation and program roadmap
+
+## Context
+
+The user approved a multi-spec roadmap for full Spanish and English CLI support. This slice creates only the documentation package and handoffs.
+
+## Objective
+
+Create the v37 foundation spec, roadmap, and implementation slices without modifying runtime code.
+
+## Acceptance Criteria
+
+- The spec package exists under `specs/quiver-v37-cli-i18n-foundation`.
+- Each slice has `slice.json`, `EXECUTION_BRIEF.md`, and `CLOSURE_BRIEF.md`.
+- The next executable slice is clearly marked as ready.
+- No runtime code is modified by this slice.
+
+## Completion Checklist
+
+- [x] Spec root documents created.
+- [x] Slice handoffs created.
+- [x] Runtime implementation deferred.

package/specs/quiver-v37-cli-i18n-foundation/slices/slice-00-foundation-and-program-roadmap/slice.json

@@ -0,0 +1,54 @@
+{
+  "slice_id": "slice-00-foundation-and-program-roadmap",
+  "ticket": "QUIVER-37-00",
+  "type": "documentation",
+  "title": "Foundation and program roadmap",
+  "objective": "Create the approved v37 i18n foundation spec package and handoffs without runtime implementation.",
+  "description": "Documents the shared foundation required before migrating commands to Spanish and English output.",
+  "git": {
+    "branch_type": "docs",
+    "base_branch": "main",
+    "branch_slug": "v37-i18n-foundation-roadmap",
+    "branch_name": "docs/QUIVER-37-00-v37-i18n-foundation-roadmap"
+  },
+  "files": [
+    "specs/quiver-v37-cli-i18n-foundation/**"
+  ],
+  "expected_read_paths": [
+    "docs/INDEX.md",
+    "docs/CLI_UX_GUIDE.md",
+    "docs/reference/commands.md"
+  ],
+  "allowed_write_paths": [
+    "specs/quiver-v37-cli-i18n-foundation/**"
+  ],
+  "depends_on": [],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "This creates the contract for all later v37 slices.",
+  "must": [
+    "Create the spec package and slice handoffs.",
+    "Document the language precedence and JSON stability guardrails.",
+    "Mark slice-01 as ready."
+  ],
+  "not_included": [
+    "Runtime implementation.",
+    "Catalog migration for existing commands."
+  ],
+  "acceptance": [
+    "Spec root documents exist.",
+    "Each slice has execution and closure briefs.",
+    "slice.json files are valid JSON.",
+    "Runtime code is untouched."
+  ],
+  "tests": [
+    "npx create-quiver spec validate specs/quiver-v37-cli-i18n-foundation --strict",
+    "git diff --check"
+  ],
+  "validation_hints": [
+    "Strict validation requires completed slices to be referenced in EVIDENCE_REPORT.md."
+  ],
+  "estimated_hours": 1,
+  "status": "completed",
+  "completed_at": "2026-05-28T00:00:00.000Z",
+  "blocked_reason": null
+}

package/specs/quiver-v37-cli-i18n-foundation/slices/slice-01-language-resolution-contract/CLOSURE_BRIEF.md

@@ -0,0 +1,30 @@
+# CLOSURE_BRIEF - slice-01 Language resolution contract
+
+## Summary
+
+Implemented the language resolution foundation for `en` and `es`.
+
+Added:
+
+- `src/create-quiver/lib/i18n/language.js`
+- global `--lang` extraction before command dispatch
+- project/global config helpers for `.quiver/config.json` and `~/.quiver/config.json`
+- locale normalization for supported `en` and `es` variants
+- warnings for unsupported explicit language sources
+- focused unit and CLI contract tests
+
+## Validation
+
+- [x] `node --test tests/lib/i18n-language.test.js`
+- [x] `node --test tests/commands/cli-contract.test.js`
+- [x] `node --test tests/**/*.test.js`
+- [x] `node bin/create-quiver.js spec validate specs/quiver-v37-cli-i18n-foundation --strict`
+- [x] `git diff --check`
+
+## Pending
+
+- Package and smoke validation are deferred to `slice-05-foundation-docs-tests-package-readiness`.
+
+## Remaining Risks
+
+- Command output is not translated yet; slice-02 through slice-05 own catalog, command wiring, and docs/package readiness.

package/specs/quiver-v37-cli-i18n-foundation/slices/slice-01-language-resolution-contract/EXECUTION_BRIEF.md

@@ -0,0 +1,27 @@
+# EXECUTION_BRIEF - slice-01 Language resolution contract
+
+## Context
+
+Users should configure language once and then receive CLI responses in that language without repeating flags.
+
+## Objective
+
+Implement the language resolution contract and config read/write primitives for `en` and `es`.
+
+## Acceptance Criteria
+
+- Resolution order is `--lang`, `QUIVER_LANG`, project config, global config, locale, `en`.
+- `--lang` works before and after the command name.
+- Project config is `.quiver/config.json`.
+- Global config is `~/.quiver/config.json` resolved with `os.homedir()`.
+- Locale detection reads `LC_ALL`, `LC_MESSAGES`, `LANG`, `LANGUAGE`, and `Intl.DateTimeFormat().resolvedOptions().locale`.
+- `es_AR`, `es-AR`, `en_US`, and `en-US` normalize correctly.
+- Unsupported values fall back to `en` with human-mode guidance.
+- `--json` remains stable and does not include localized prose unless an existing schema explicitly allows it.
+
+## Completion Checklist
+
+- [x] Resolver helper implemented.
+- [x] Config read/write helper implemented.
+- [x] Global flag parser supports before/after command.
+- [x] Unit tests cover precedence and locale normalization.

package/specs/quiver-v37-cli-i18n-foundation/slices/slice-01-language-resolution-contract/slice.json

@@ -0,0 +1,66 @@
+{
+  "slice_id": "slice-01-language-resolution-contract",
+  "ticket": "QUIVER-37-01",
+  "type": "feature",
+  "title": "Language resolution contract",
+  "objective": "Implement the ordered language resolution and config persistence foundation for Spanish and English CLI output.",
+  "description": "Adds the reusable resolver that all localized command output will consume.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v37-language-resolution-contract",
+    "branch_name": "feature/QUIVER-37-01-v37-language-resolution-contract"
+  },
+  "files": [
+    "src/create-quiver/lib/i18n/language.js",
+    "tests/lib/i18n-language.test.js"
+  ],
+  "expected_read_paths": [
+    "src/create-quiver/index.js",
+    "src/create-quiver/lib/paths.js",
+    "docs/CLI_UX_GUIDE.md",
+    "specs/quiver-v37-cli-i18n-foundation/SPEC.md"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/lib/i18n/language.js",
+    "src/create-quiver/index.js",
+    "tests/lib/i18n-language.test.js",
+    "tests/commands/cli-contract.test.js",
+    "specs/quiver-v37-cli-i18n-foundation/**"
+  ],
+  "depends_on": [
+    "slice-00-foundation-and-program-roadmap"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "All later i18n work depends on the exact precedence and parser contract.",
+  "must": [
+    "Support only en and es.",
+    "Apply the approved precedence order.",
+    "Resolve global config through os.homedir().",
+    "Normalize common locale variants.",
+    "Keep JSON output stable."
+  ],
+  "not_included": [
+    "Message catalog implementation.",
+    "Command-by-command migration."
+  ],
+  "acceptance": [
+    "Tests prove each language source wins in the approved order.",
+    "Tests prove --lang works before and after commands.",
+    "Unsupported language values fall back to en with human guidance.",
+    "No JSON schema keys are localized."
+  ],
+  "tests": [
+    "node --test tests/lib/i18n-language.test.js",
+    "node --test tests/commands/cli-contract.test.js",
+    "git diff --check"
+  ],
+  "validation_hints": [
+    "Use environment isolation in tests.",
+    "Include Windows-style home path coverage where practical."
+  ],
+  "estimated_hours": 5,
+  "status": "completed",
+  "completed_at": "2026-05-29T00:00:00.000Z",
+  "blocked_reason": null
+}

package/specs/quiver-v37-cli-i18n-foundation/slices/slice-02-message-catalog-interpolation/CLOSURE_BRIEF.md

@@ -0,0 +1,27 @@
+# CLOSURE_BRIEF - slice-02 Message catalog and interpolation
+
+## Summary
+
+Implemented the shared message catalog foundation.
+
+Added:
+
+- versioned `en` and `es` catalogs
+- translation helper
+- safe interpolation with predictable missing params
+- one/other plural support
+- explicit fallback to English
+- catalog completeness validation
+
+## Validation
+
+- [x] `node --test tests/lib/i18n-catalog.test.js`
+- [ ] `git diff --check`
+
+## Pending
+
+- Run `git diff --check` after final docs updates.
+
+## Remaining Risks
+
+- Commands do not consume catalog keys yet; slice-03 through slice-05 own command wiring, parser/help migration, and docs/package readiness.

package/specs/quiver-v37-cli-i18n-foundation/slices/slice-02-message-catalog-interpolation/EXECUTION_BRIEF.md

@@ -0,0 +1,26 @@
+# EXECUTION_BRIEF - slice-02 Message catalog and interpolation
+
+## Context
+
+Localized output must be maintainable and testable. Hardcoded Spanish or English strings in command bodies would make coverage incomplete.
+
+## Objective
+
+Add the catalog and translation helper used by the CLI for human output.
+
+## Acceptance Criteria
+
+- Catalogs exist for `en` and `es`.
+- Catalog metadata includes a version.
+- Interpolation escapes missing or unsafe values predictably.
+- Plural forms support at least `one` and `other`.
+- Missing keys fail tests.
+- Fallback to `en` is explicit and tested.
+- Suggested commands and flags remain exact literals.
+
+## Completion Checklist
+
+- [x] Catalog files added.
+- [x] Translation helper added.
+- [x] Missing-key and fallback tests added.
+- [x] Pluralization tests added.

package/specs/quiver-v37-cli-i18n-foundation/slices/slice-02-message-catalog-interpolation/slice.json

@@ -0,0 +1,62 @@
+{
+  "slice_id": "slice-02-message-catalog-interpolation",
+  "ticket": "QUIVER-37-02",
+  "type": "feature",
+  "title": "Message catalog and interpolation",
+  "objective": "Create versioned English and Spanish catalogs with safe interpolation, pluralization, fallback, and missing-key coverage.",
+  "description": "Provides the string infrastructure needed before migrating command output.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v37-message-catalog-interpolation",
+    "branch_name": "feature/QUIVER-37-02-v37-message-catalog-interpolation"
+  },
+  "files": [
+    "src/create-quiver/lib/i18n/catalog.js",
+    "src/create-quiver/lib/i18n/messages/en.js",
+    "src/create-quiver/lib/i18n/messages/es.js",
+    "tests/lib/i18n-catalog.test.js"
+  ],
+  "expected_read_paths": [
+    "src/create-quiver/lib/i18n/language.js",
+    "specs/quiver-v37-cli-i18n-foundation/SPEC.md"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/lib/i18n/**",
+    "tests/lib/i18n-catalog.test.js",
+    "specs/quiver-v37-cli-i18n-foundation/**"
+  ],
+  "depends_on": [
+    "slice-01-language-resolution-contract"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "Later command migrations must share the same catalog API.",
+  "must": [
+    "Implement en and es catalogs.",
+    "Support interpolation and one/other plural forms.",
+    "Fail tests on missing keys.",
+    "Keep command snippets untranslated."
+  ],
+  "not_included": [
+    "Migrating all command output.",
+    "Generated docs localization."
+  ],
+  "acceptance": [
+    "All keys present in en exist in es and vice versa.",
+    "Missing key behavior is deterministic.",
+    "Fallback behavior is tested.",
+    "Pluralization covers one and other."
+  ],
+  "tests": [
+    "node --test tests/lib/i18n-catalog.test.js",
+    "git diff --check"
+  ],
+  "validation_hints": [
+    "Use stable key names grouped by command or domain.",
+    "Avoid embedding ANSI codes in catalog strings."
+  ],
+  "estimated_hours": 5,
+  "status": "completed",
+  "completed_at": "2026-05-29T00:00:00.000Z",
+  "blocked_reason": null
+}

package/specs/quiver-v37-cli-i18n-foundation/slices/slice-03-config-language-command/CLOSURE_BRIEF.md

@@ -0,0 +1,32 @@
+# CLOSURE_BRIEF - slice-03 Config language command
+
+## Summary
+
+Implemented `config language` commands.
+
+Added:
+
+- `config language show`
+- `config language show --json`
+- `config language set <en|es>`
+- `config language set <en|es> --global`
+- project config writes to `.quiver/config.json`
+- global config writes to `~/.quiver/config.json`
+- stable JSON output for show/set
+- command reference documentation
+
+## Validation
+
+- [x] `node --test tests/commands/config-language.test.js`
+- [x] `node --test tests/lib/i18n-catalog.test.js tests/lib/i18n-language.test.js tests/commands/cli-contract.test.js`
+- [x] `node --test tests/**/*.test.js`
+- [x] `node bin/create-quiver.js spec validate specs/quiver-v37-cli-i18n-foundation --strict`
+- [x] `git diff --check`
+
+## Pending
+
+- No pending work for this slice.
+
+## Remaining Risks
+
+- Parser/help localization is still pending in `slice-04-parser-help-error-foundation`.

package/specs/quiver-v37-cli-i18n-foundation/slices/slice-03-config-language-command/EXECUTION_BRIEF.md

@@ -0,0 +1,25 @@
+# EXECUTION_BRIEF - slice-03 Config language command
+
+## Context
+
+Language changes should be discoverable after init and usable in scripts.
+
+## Objective
+
+Add `config language show` and `config language set <en|es>` with project and global persistence.
+
+## Acceptance Criteria
+
+- `config language show` reports effective language and source.
+- `config language set es` and `config language set en` update project config by default.
+- A global option writes to `~/.quiver/config.json` without requiring a project.
+- Invalid languages fail with actionable guidance.
+- `--json` returns stable keys and codes.
+- Existing config keys are preserved.
+
+## Completion Checklist
+
+- [x] Command parser route added.
+- [x] Project/global write paths tested.
+- [x] JSON and human modes covered.
+- [x] Docs updated.

package/specs/quiver-v37-cli-i18n-foundation/slices/slice-03-config-language-command/slice.json

@@ -0,0 +1,66 @@
+{
+  "slice_id": "slice-03-config-language-command",
+  "ticket": "QUIVER-37-03",
+  "type": "feature",
+  "title": "Config language command",
+  "objective": "Add user-facing commands to inspect and update Quiver language configuration.",
+  "description": "Lets users change language without editing JSON by hand.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v37-config-language-command",
+    "branch_name": "feature/QUIVER-37-03-v37-config-language-command"
+  },
+  "files": [
+    "src/create-quiver/commands/config.js",
+    "tests/commands/config-language.test.js",
+    "docs/reference/commands.md"
+  ],
+  "expected_read_paths": [
+    "src/create-quiver/index.js",
+    "src/create-quiver/lib/i18n/language.js",
+    "src/create-quiver/lib/i18n/catalog.js",
+    "docs/reference/commands.md"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/commands/config.js",
+    "src/create-quiver/index.js",
+    "src/create-quiver/lib/i18n/**",
+    "tests/commands/config-language.test.js",
+    "docs/reference/commands.md",
+    "specs/quiver-v37-cli-i18n-foundation/**"
+  ],
+  "depends_on": [
+    "slice-01-language-resolution-contract",
+    "slice-02-message-catalog-interpolation"
+  ],
+  "parallel_safe": "conditional",
+  "parallel_safe_reason": "Can run alongside parser work after catalog ownership is settled.",
+  "must": [
+    "Implement show and set subcommands.",
+    "Preserve existing config keys.",
+    "Support project and global config scopes.",
+    "Keep JSON contracts stable."
+  ],
+  "not_included": [
+    "Migrating unrelated command output."
+  ],
+  "acceptance": [
+    "Users can set es or en for the project.",
+    "Users can set es or en globally.",
+    "show identifies effective language and source.",
+    "Invalid language values fail clearly."
+  ],
+  "tests": [
+    "node --test tests/commands/config-language.test.js",
+    "git diff --check"
+  ],
+  "validation_hints": [
+    "Use temp HOME in tests for global config.",
+    "Assert existing .quiver/config.json content is preserved."
+  ],
+  "estimated_hours": 5,
+  "status": "completed",
+  "completed_at": "2026-05-29T00:00:00.000Z",
+  "blocked_reason": null
+}

package/specs/quiver-v37-cli-i18n-foundation/slices/slice-04-parser-help-error-foundation/CLOSURE_BRIEF.md

@@ -0,0 +1,30 @@
+# CLOSURE_BRIEF - slice-04 Parser, help, and early error foundation
+
+## Summary
+
+Implemented parser/help/error i18n foundation.
+
+Added:
+
+- language-aware top-level help rendering
+- cataloged help headings and command descriptions
+- localized unsupported command errors
+- localized unsupported flag errors
+- localized missing flag value errors, including missing `--lang`
+- localized unsupported-language warnings in CLI entrypoint
+- tests for explicit `--lang`, project-configured language, JSON stdout cleanliness, no-color help, and literal command preservation
+
+## Validation
+
+- [x] `node --test tests/commands/cli-contract.test.js`
+- [x] `node --test tests/lib/i18n-catalog.test.js tests/lib/i18n-language.test.js`
+- [x] `node --test tests/commands/config-language.test.js`
+- [ ] `git diff --check`
+
+## Pending
+
+- Run `git diff --check` after final docs updates.
+
+## Remaining Risks
+
+- Command-specific business output is intentionally not migrated in this slice; it is covered by later i18n specs.

package/specs/quiver-v37-cli-i18n-foundation/slices/slice-04-parser-help-error-foundation/EXECUTION_BRIEF.md

@@ -0,0 +1,24 @@
+# EXECUTION_BRIEF - slice-04 Parser, help, and early error foundation
+
+## Context
+
+Some messages are emitted before command handlers run. They must still respect the selected language.
+
+## Objective
+
+Route help text, parser errors, unsupported command errors, and global option errors through the i18n foundation.
+
+## Acceptance Criteria
+
+- `--help` uses the resolved language.
+- Unknown command and unsupported flag errors use the resolved language.
+- `--lang` errors work even when `--lang` appears before the command.
+- `--json` errors keep stable machine fields.
+- `--no-color`, CI, and no-TTY modes remain clean.
+
+## Completion Checklist
+
+- [ ] Parser-level i18n wiring added.
+- [ ] Help output cataloged.
+- [ ] Early error tests added for `en` and `es`.
+- [ ] JSON/no-TTY tests updated.