@hyphaene/hexa-ts-kit 1.10.0 → 1.12.0

package/README.md

@@ -46,6 +46,15 @@ hexa-ts scaffold nestjs-feature src/domains/orders/create
 
 # Scaffold Playwright tests
 hexa-ts scaffold playwright-feature e2e/checkout
+
+# Setup vault config (interactive wizard)
+hexa-ts vault:init
+
+# Compare vault schemas between refs
+hexa-ts vault:diff --repo <alias> <source-ref> <target-ref>
+
+# Quick diff: current branch vs main
+hexa-ts vault:quick-diff
 ```
 
 ### MCP Server
@@ -174,6 +183,113 @@ match: "*.composable.ts"
 ---
 ```
 
+## Vault Diff
+
+Compare `vault.schema.json` between git refs to detect configuration changes before deployment.
+
+### Modes
+
+**Multi-repo** (from anywhere, using `--repo` flag):
+
+```bash
+hexa-ts vault:diff --repo <alias> <source-ref> <target-ref>
+hexa-ts vault:extract --repo <alias> <ref>
+```
+
+**In-repo** (from inside the git repo):
+
+```bash
+hexa-ts vault:diff <source-ref> <target-ref>
+hexa-ts vault:extract <ref>
+```
+
+### Global Configuration
+
+Create `~/.hexa/vault.yaml` to define repo aliases for multi-repo mode:
+
+```yaml
+repos:
+  <alias>:
+    url: "<git-remote-url>"
+    schemaPath: "<path/to/vault.schema.json>"
+    turbineService: "<service-name>"  # optional
+cacheDir: "~/.hexa/vault/.cache"
+```
+
+Each repo entry requires:
+- `url`: Git remote URL (SSH or HTTPS)
+- `schemaPath`: Path to `vault.schema.json` relative to repo root
+- `turbineService` (optional): Turbine service name for environment resolution
+
+### Cache
+
+Multi-repo mode uses bare git clones cached in `~/.hexa/vault/.cache/`. On each run, the cache is fetched automatically to stay up to date. If a fetch fails, the cache is re-cloned from scratch.
+
+### Commands
+
+```bash
+# Multi-repo: compare two refs
+hexa-ts vault:diff --repo <alias> <source-ref> <target-ref>
+
+# In-repo: compare two refs
+hexa-ts vault:diff <source-ref> <target-ref>
+
+# Quick diff: current branch vs main (in-repo only)
+hexa-ts vault:quick-diff
+
+# Extract schema from a ref
+hexa-ts vault:extract --repo <alias> <ref>
+hexa-ts vault:extract <ref>
+
+# JSON output (for agents)
+hexa-ts vault:diff --repo <alias> <source-ref> <target-ref> --format json
+```
+
+### Output
+
+```
+Vault Schema Diff
+Source: <source-ref>
+Target: <target-ref>
+──────────────────────────────────────────────────
+
++ Added:
+  config.newFeature: { enabled, options }
+  config.workflows: enum(TYPE_A | TYPE_B)[]
+
+- Removed:
+  config.deprecatedFlag: boolean
+
+~ Changed:
+  config.items[]: string → number
+
+──────────────────────────────────────────────────
+Summary: +2 -1 ~1
+
+⚠ Breaking changes detected (removals or type changes)
+```
+
+The command exits with code 1 if breaking changes are detected (removals or type changes).
+
+### Setup: vault:init
+
+Generate `~/.hexa/vault.yaml` automatically by scanning your filesystem for repos with `vault.schema.json`:
+
+```bash
+# Interactive wizard (React Ink)
+hexa-ts vault:init
+
+# Non-interactive (auto-detect and write)
+hexa-ts vault:init --no-interactive --scan <paths>
+```
+
+The wizard:
+1. Asks which directories to scan
+2. Discovers git repos containing `vault.schema.json`
+3. Deduplicates by remote URL (skips worktrees)
+4. Suggests aliases for each repo
+5. Previews and writes `~/.hexa/vault.yaml`
+
 ## Development
 
 ### Playground