wicked-vault 0.2.0 → 0.3.0

package/README.md

@@ -51,14 +51,20 @@ config root (Claude Code, Gemini, Copilot, Codex, Cursor, Kiro, Antigravity):
 npx wicked-vault-install               # detect and install everywhere
 npx wicked-vault-install --cli=claude  # one CLI only (comma-separated for several)
 npx wicked-vault-install --path ~/.claude   # a specific config root
+npx wicked-vault-install --help        # options
 ```
 
 This mirrors the shared wicked-bus / wicked-brain installer: `$CLAUDE_CONFIG_DIR`
 is honored, alt-config layouts are probed, and skills land as
-`wicked-vault-{init,record-evidence,verify-evidence,analyze-evidence,cross-check-evidence}/`
+`wicked-vault-{init,record-evidence,verify-evidence,analyze-evidence,cross-check-evidence,update}/`
 under each CLI's `skills/`. If wicked-bus is installed, the installer also
 registers the vault as a bus provider (see below).
 
+**Updating:** say `wicked-vault:update` to your agent, or run
+`npm install -g wicked-vault@latest && npx wicked-vault-install` — it compares
+your version against npm and refreshes the skills across every CLI. Both
+binaries support `--help`.
+
 ## CLI
 
 ```bash
@@ -121,6 +127,10 @@ isn't — or when `WICKED_VAULT_NO_BUS=1` is set — emission is a silent no-op
 the CLI behaves identically. A bus error never changes a verdict, the JSON on
 stdout, or an exit code.
 
+Proven end-to-end: `test/bus-integration.sh` drives the vault into a **real**
+wicked-bus (db isolated to a temp dir) and reads every event back off the bus —
+and runs in CI on every push.
+
 | Command | event_type | subdomain | key payload |
 |---|---|---|---|
 | `record` | `wicked.evidence.recorded` | `vault.record` | scope, phase, claim_id, kind, id, envelope_hash |
@@ -167,10 +177,15 @@ evaluator may cite — not the whole story. Nondeterministic observation verifie
 npm run prove                 # record -> tamper -> verify-rejects on a real repo
 bash test/verifiers.sh        # the 5 verifiers, pass + fail cases
 bash test/attestation.sh      # criteria-binding, attest fail-closed/independence, require_attestation
-bash test/bus-integration.sh  # graceful no-op + event validity + emission (incl. attested)
+bash test/bus-integration.sh  # graceful no-op + schema validity + real-bus emission (init/record/attest/cross-check)
 ```
 
-Status: v0.2.0 — deterministic core proven on real repos; criteria-binding +
+`attestation.sh` and `bus-integration.sh` are the gating proofs and run in CI
+(`.github/workflows/ci.yml`) on ubuntu + macos, with a Windows CLI smoke.
+
+Status: v0.3.0 — deterministic core proven on real repos; criteria-binding +
 independent judgment tier (ADR-0002, council 5–0) implemented and proven;
-wicked-bus emission + provider registration (optional, fire-and-forget). Not yet
-implemented: `pr_check_status`/`http_status_eq` and the sqlite query cache.
+wicked-bus integration **proven end-to-end against a real bus** (emit → store →
+poll), optional and fire-and-forget; `--help` on both binaries + a
+`wicked-vault:update` skill. Not yet implemented:
+`pr_check_status`/`http_status_eq` and the sqlite query cache.

package/bin/wicked-vault.mjs

@@ -33,7 +33,53 @@ function emit(obj, ok) {
   process.exit(ok ? 0 : 1);
 }
 
+const HELP = `wicked-vault — local-first evidence primitive
+Record evidence with the acceptance criteria it must clear, re-derive integrity
+deterministically, and record independent third-party judgments. Never trusts a
+stored verdict; never lets work self-grade its own "done".
+
+USAGE
+  wicked-vault <command> [options]
+
+COMMANDS
+  init                         Create .wicked-vault/ in the current repo
+  record                       Capture evidence + the criteria it must clear
+                               --scope S --phase P --claim C --kind K --source "<cmd|file>"
+                               --criteria "<text|@file>" (--run | --artifact <file>) [--verifier "kind:arg"]
+  verify   <artifact-id>       Integrity tier: re-derive hashes + verifier (deterministic,
+                               model-free). Exit 0 iff intact AND pass. Surfaces latest opinion.
+  inspect  <artifact-id>       Frozen criteria + evidence + integrity (what a judge evaluates)
+  attest   <artifact-id>       Record an INDEPENDENT judgment (fail-closed; evaluator != creator)
+                               --opinion <pass|reject|unclear> --rationale "..." --evaluator ID
+                               [--model prov/ver] [--prompt-hash H] [--sampling '<json>']
+  attestations <artifact-id>   Show the append-only opinion log
+  cross-check                  Mechanical contract verdict; exit 0 iff PASS
+                               --scope S --phase P [--integrity-only (default) | --with-attestations]
+  declare-contract             Pin a contract  --scope S --phase P --spec <file>
+  supersede <old-id>           Append-only replacement (same flags as record)
+  list                         --scope S [--phase P]
+
+GLOBAL
+  --cwd <dir>     Operate on a vault rooted at <dir> (default: walk up from cwd)
+  --help, -h      Show this help
+
+OUTPUT   JSON on stdout; exit code is the gate signal (0 = PASS / success).
+ENV      WICKED_VAULT_NO_BUS=1   Disable optional wicked-bus event emission
+
+Skills (AI CLIs):  wicked-vault:{init,record-evidence,verify-evidence,analyze-evidence,cross-check-evidence,update}
+Install skills:    npx wicked-vault-install        (run with --help for options)
+Docs:              https://github.com/mikeparcewski/wicked-vault
+`;
+
 const [cmd, ...rest] = process.argv.slice(2);
+
+// Help / no-command: print usage to stdout and exit 0 — before any vault or bus
+// work, so `--help` works outside a repo and never errors.
+if (cmd === undefined || cmd === '--help' || cmd === '-h' || cmd === 'help') {
+  process.stdout.write(HELP);
+  process.exit(0);
+}
+
 const args = parseArgs(rest);
 const cwd = (typeof args.cwd === 'string' && args.cwd) || process.cwd();
 

package/install.mjs

@@ -64,10 +64,41 @@ const CLI_TARGETS = [
   { name: "antigravity", dir: join(home, ".antigravity", "skills"), platform: "antigravity" },
 ];
 
-console.log("wicked-vault installer\n");
-
 const args = argv.slice(2);
 
+// Help: print usage and exit 0 before doing any detection or filesystem work.
+if (args.includes("--help") || args.includes("-h")) {
+  process.stdout.write(`wicked-vault-install — install wicked-vault skills into your AI CLIs/IDEs
+
+Copies the wicked-vault skills into every detected CLI config root so your
+agent knows how to use the vault. Also registers wicked-vault as a wicked-bus
+provider when the bus is available.
+
+USAGE
+  npx wicked-vault-install [options]
+
+OPTIONS
+  (no options)        Detect and install into every supported CLI found
+  --cli=<name>        Install into one CLI only (comma-separated for several),
+                      e.g. --cli=claude  or  --cli=claude,cursor
+  --path=<dir>        Install into a specific config root, e.g. --path=~/.claude
+  --help, -h          Show this help
+
+SUPPORTED CLIs       claude, gemini, copilot, codex, cursor, kiro, antigravity
+                     (\$CLAUDE_CONFIG_DIR is honored; alt-config layouts are probed)
+
+INSTALLS (per CLI, under skills/)
+  wicked-vault-init · -record-evidence · -verify-evidence · -analyze-evidence
+  · -cross-check-evidence · -update
+
+To update later:  npm install -g wicked-vault@latest && npx wicked-vault-install
+                  (or just say "wicked-vault:update" to your agent)
+`);
+  process.exit(0);
+}
+
+console.log("wicked-vault installer\n");
+
 // Flag parser supporting both --flag=value and --flag value forms, plus
 // narrow string-boolean coercion ("true" / "false" → booleans). The ad-hoc
 // parser this replaces silently dropped space-separated values — same bug

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-vault",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Local-first evidence primitive — record evidence with its acceptance criteria, re-derive integrity deterministically, and record independent third-party judgments. Never trusts a stored verdict, never lets work self-grade its own \"done\".",
   "type": "module",
   "bin": {

package/skills/wicked-vault/update/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: wicked-vault:update
+description: |
+  Check for and install wicked-vault updates. Compares the installed version
+  against the npm registry, updates the published CLI, and refreshes the skills
+  across all detected AI CLIs (Claude Code, Gemini, Copilot, Codex, Cursor,
+  Kiro, Antigravity).
+
+  Use when: "update wicked-vault", "check for vault updates", "wicked-vault update",
+  or periodically to stay current.
+---
+
+# wicked-vault:update
+
+Check for and install updates to wicked-vault and its skills.
+
+## Cross-Platform Notes
+
+Commands work on macOS, Linux, and Windows. Prefer agent-native tools
+(Read, Write, Grep, Glob) over shell where possible. JSON parsing uses
+`python3 … || python …` so it runs on macOS, Linux, WSL, and Git Bash.
+
+## When to use
+
+- User asks to update or check for updates.
+- After unexpected behavior that might be fixed in a newer version.
+- Periodically (suggest checking monthly).
+
+## Process
+
+### Step 1 — Check the installed version
+
+Global install:
+
+```bash
+npm list -g wicked-vault --json 2>/dev/null | python3 -c "
+import json, sys
+try:
+    d = json.load(sys.stdin)
+    print(d.get('dependencies', {}).get('wicked-vault', {}).get('version', 'not installed'))
+except Exception:
+    print('not installed')
+" 2>/dev/null || npm list -g wicked-vault --json 2>/dev/null | python -c "
+import json, sys
+try:
+    d = json.load(sys.stdin)
+    print(d.get('dependencies', {}).get('wicked-vault', {}).get('version', 'not installed'))
+except Exception:
+    print('not installed')
+"
+```
+
+Also check a local (project-level) install:
+
+```bash
+npm list wicked-vault --json 2>/dev/null
+```
+
+If neither is installed, the user may be running via `npx wicked-vault@latest`
+(always current) — note that and skip to Step 5 to (re)install skills.
+
+### Step 2 — Check the latest version on npm
+
+```bash
+npm view wicked-vault version 2>/dev/null
+```
+
+### Step 3 — Compare
+
+- Up to date: "wicked-vault is up to date (v{version})."
+- Update available: "wicked-vault v{new} is available (you have v{current}). Update now?"
+
+If the user only wanted to check, stop here and report current vs. available.
+
+### Step 4 — Update the package (if approved)
+
+Global:
+
+```bash
+npm install -g wicked-vault@latest 2>&1
+```
+
+Local (project):
+
+```bash
+npm install wicked-vault@latest 2>&1
+```
+
+If `EACCES` / permission denied:
+- macOS/Linux: `sudo npm install -g wicked-vault@latest`
+- Windows: re-run the shell as Administrator
+- Report the failure — do NOT silently skip.
+
+### Step 5 — Refresh the skills in all CLIs
+
+After updating the package, re-run the installer to copy the updated skills
+into every detected CLI:
+
+```bash
+npx wicked-vault-install
+```
+
+Or target one CLI:
+
+```bash
+npx wicked-vault-install --cli=claude
+```
+
+(The installer is idempotent — re-running overwrites the installed skills with
+the current version and re-registers the wicked-bus provider if the bus is
+present.)
+
+### Step 6 — Verify
+
+Re-run the Step 1 version check and confirm it matches latest. Also confirm the
+CLI runs:
+
+```bash
+npx wicked-vault --help | head -1
+```
+
+If it still shows the old version:
+1. `which wicked-vault` (macOS/Linux) or `where wicked-vault` (Windows).
+2. `npm cache clean --force`.
+3. Check whether nvm / fnm / volta is pinning a stale copy.
+
+### Step 7 — Report
+
+```
+wicked-vault updated: v{old} → v{new}
+Skills refreshed in {N} CLIs: {list}
+```
+
+## Notes
+
+- wicked-vault has **no background server** to update (unlike wicked-brain) —
+  updating is just the package + the skills.
+- The published package is provenance-signed; `npm view wicked-vault --json`
+  shows the attestation under `dist.attestations` if you want to confirm
+  supply-chain integrity after updating.

package/src/bus.mjs

@@ -9,18 +9,49 @@
 //
 // Opt out entirely with WICKED_VAULT_NO_BUS=1.
 
+import { existsSync, readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { pathToFileURL } from 'node:url';
-import { join } from 'node:path';
+import { join, dirname } from 'node:path';
 
 const DOMAIN = 'wicked-vault';
 
+// Given a resolved file inside a package, return its ESM ("import") entry.
+// `require.resolve()` applies the "require" condition, so for a dual-published
+// package it returns the CJS entry — and wicked-bus ships a CJS *shim* with no
+// real exports (importing it yields `emit: undefined`). We must read the
+// package.json and import the ESM entry instead. (`require.resolve` can't fetch
+// package.json directly when "exports" doesn't expose it, so walk up to the
+// package root and read it from disk.)
+function esmEntryForPackage(resolvedFile) {
+  let dir = dirname(resolvedFile);
+  for (let i = 0; i < 10; i++) {
+    const pj = join(dir, 'package.json');
+    if (existsSync(pj)) {
+      let pkg;
+      try { pkg = JSON.parse(readFileSync(pj, 'utf8')); } catch { return null; }
+      const dot = pkg.exports && pkg.exports['.'] !== undefined ? pkg.exports['.'] : pkg.exports;
+      const rel =
+        (dot && typeof dot === 'object' && (dot.import || dot.default)) ||
+        (typeof dot === 'string' ? dot : null) ||
+        pkg.module || pkg.main || 'index.js';
+      return join(dir, rel);
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
 // Resolve the wicked-bus module namespace, or null. Two layers, in order:
 //   1. bare specifier — works when wicked-bus is installed globally or hoisted
-//      alongside the vault.
+//      alongside the vault. import() uses the ESM condition, so it returns the
+//      real module.
 //   2. the consumer project's node_modules (anchored at cwd) — the common case,
 //      since sibling tools live in the same repo the vault is invoked from, and
-//      the vault itself ships no node_modules.
+//      the vault itself ships no node_modules. require.resolve locates the
+//      package; we import its ESM entry so we get real exports, not a CJS shim.
 async function resolveBus(cwd) {
   try {
     return await import('wicked-bus');
@@ -29,8 +60,9 @@ async function resolveBus(cwd) {
   }
   try {
     const require = createRequire(join(cwd, '__vault_bus_anchor__.js'));
-    const entry = require.resolve('wicked-bus');
-    return await import(pathToFileURL(entry).href);
+    const located = require.resolve('wicked-bus');
+    const esm = esmEntryForPackage(located) || located;
+    return await import(pathToFileURL(esm).href);
   } catch {
     return null;
   }
@@ -49,9 +81,15 @@ export async function initBus(cwd = process.cwd()) {
   if (process.env.WICKED_VAULT_NO_BUS === '1') return NOOP;
 
   const bus = await resolveBus(cwd);
-  if (!bus || typeof bus.emit !== 'function' || typeof bus.openDb !== 'function') {
-    return NOOP;
+  // Defensive capability check — a pathological module (e.g. a CJS shim whose
+  // property access throws) must degrade to a no-op, never crash the vault.
+  let usable = false;
+  try {
+    usable = !!bus && typeof bus.emit === 'function' && typeof bus.openDb === 'function';
+  } catch {
+    usable = false;
   }
+  if (!usable) return NOOP;
 
   let db;
   let config;