pan-wizard 3.7.10 → 3.10.0

package/pan-wizard-core/bin/pan-tools.cjs

@@ -214,6 +214,7 @@ const runner = require('./lib/runner.cjs');
 const docLint = require('./lib/doc-lint.cjs');
 const learnLint = require('./lib/learn-lint.cjs');
 const learnIndex = require('./lib/learn-index.cjs');
+const links = require('./lib/links.cjs');
 
 /**
  * Get the value following a flag in the args array.
@@ -663,7 +664,8 @@ async function main() {
         const standardsFlag = args.includes('--standards');
         const fullFlag = args.includes('--full');
         const driftFlag = args.includes('--drift');
-        verify.cmdValidateHealth(cwd, { repair: repairFlag, standards: standardsFlag, full: fullFlag, drift: driftFlag }, raw);
+        const linksFlag = args.includes('--links');
+        verify.cmdValidateHealth(cwd, { repair: repairFlag, standards: standardsFlag, full: fullFlag, drift: driftFlag, links: linksFlag }, raw);
       } else if (subcommand === 'deployment') {
         verify.cmdValidateDeployment(cwd, raw);
       } else {
@@ -1037,6 +1039,16 @@ async function main() {
       break;
     }
 
+    case 'models': {
+      const subcommand = args[1];
+      if (subcommand === 'check' || !subcommand) {
+        cost.cmdModelsCheck(raw);
+      } else {
+        error('Unknown models subcommand. Available: check');
+      }
+      break;
+    }
+
     case 'bus': {
       const subcommand = args[1];
       if (subcommand === 'publish') {
@@ -1307,6 +1319,28 @@ async function main() {
       break;
     }
 
+    case 'links': {
+      const subcommand = args[1];
+      if (subcommand === 'validate' || !subcommand) {
+        const collectMulti = (flag) => {
+          const vals = [];
+          for (let i = 0; i < args.length; i++) {
+            if (args[i] === flag && i + 1 < args.length) vals.push(args[i + 1]);
+          }
+          return vals.length ? vals : null;
+        };
+        const opts = {
+          docRoots: collectMulti('--doc-root'),
+          sourceRoots: collectMulti('--source-root'),
+          strict: args.includes('--strict'),
+          raw,
+        };
+        links.cmdLinksValidate(cwd, opts);
+        break;
+      }
+      error(`Unknown links subcommand: ${subcommand}. Available: validate`);
+    }
+
     default:
       error(`Unknown command: ${command}. Run pan-tools without arguments to see available commands.`);
   }

package/pan-wizard-core/workflows/plan-phase.md

@@ -511,6 +511,17 @@ Offer: 1) Force proceed, 2) Provide guidance and retry, 3) Abandon
 
 ## 13. Present Final Status
 
+**Sync state.md first** — without this, state.md says "Ready to plan" until the
+first plan's summary lands, and `/pan:progress`/`preflight` read a stale picture:
+
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs state update "Status" "Ready to execute"
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs state update "Current Plan" "1"
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs state update "Total Plans in Phase" "${PLAN_COUNT}"
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs state update "Last Activity" "$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs current-timestamp date --raw)"
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs state update "Last Activity Description" "Phase ${PHASE_NUMBER} planned — ${PLAN_COUNT} plans created"
+```
+
 Route to `<offer_next>` OR `auto_advance` depending on flags/config.
 
 **Circular optimization — log plan creation:**

package/scripts/build-plugin.js

@@ -0,0 +1,105 @@
+/**
+ * Build the PAN Wizard Claude Code plugin (ecosystem review item: plugin
+ * distribution, first slice). Emits a self-contained plugin directory at
+ * dist/pan-wizard-plugin/ following the verified plugin layout:
+ *
+ *   .claude-plugin/plugin.json    manifest (metadata; components auto-discover)
+ *   commands/pan/*.md             command markdown (Claude flavor)
+ *   agents/pan-*.md               agent definitions
+ *   hooks/hooks.json              PAN hooks with ${CLAUDE_PLUGIN_ROOT} paths
+ *   hooks/pan-*.js                hook scripts
+ *   pan-wizard-core/              dispatcher + modules + workflows + templates
+ *
+ * Distribution status: built ALONGSIDE the loose-file installer. Marketplace
+ * publishing is gated on one live verification — whether ${CLAUDE_PLUGIN_ROOT}
+ * expands inside command markdown content (documented for hook/MCP configs
+ * only). Until then, content references core paths relative to the plugin
+ * root, which matches the documented plugin working layout.
+ *
+ * Usage: node scripts/build-plugin.js  (or npm run build:plugin)
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.join(__dirname, '..');
+const OUT = path.join(ROOT, 'dist', 'pan-wizard-plugin');
+const pkg = require(path.join(ROOT, 'package.json'));
+const lib = require(path.join(ROOT, 'bin', 'install-lib.cjs'));
+
+// Plugin-relative prefix used inside markdown content. Hook/MCP configs get
+// the documented ${CLAUDE_PLUGIN_ROOT} form via buildPluginHooksConfig().
+const CONTENT_PREFIX = '${CLAUDE_PLUGIN_ROOT}/';
+
+function rewriteContent(content) {
+  return content
+    .replace(/~\/\.claude\/pan-wizard-core\//g, `${CONTENT_PREFIX}pan-wizard-core/`)
+    .replace(/\.\/\.claude\/pan-wizard-core\//g, `${CONTENT_PREFIX}pan-wizard-core/`)
+    .replace(/~\/\.claude\/agents\//g, `${CONTENT_PREFIX}agents/`)
+    .replace(/\.\/\.claude\/agents\//g, `${CONTENT_PREFIX}agents/`)
+    .replace(/~\/\.claude\//g, CONTENT_PREFIX)
+    .replace(/\.\/\.claude\//g, CONTENT_PREFIX);
+}
+
+function copyTree(srcDir, destDir, transformMd) {
+  fs.mkdirSync(destDir, { recursive: true });
+  for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
+    const srcPath = path.join(srcDir, entry.name);
+    const destPath = path.join(destDir, entry.name);
+    if (entry.isDirectory()) {
+      copyTree(srcPath, destPath, transformMd);
+    } else if (transformMd && entry.name.endsWith('.md')) {
+      fs.writeFileSync(destPath, transformMd(fs.readFileSync(srcPath, 'utf8')));
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+function main() {
+  // Clean output
+  fs.rmSync(OUT, { recursive: true, force: true });
+  fs.mkdirSync(path.join(OUT, '.claude-plugin'), { recursive: true });
+
+  // 1. Manifest
+  fs.writeFileSync(
+    path.join(OUT, '.claude-plugin', 'plugin.json'),
+    JSON.stringify(lib.buildPluginManifest(pkg), null, 2) + '\n'
+  );
+
+  // 2. Commands (Claude flavor, plugin-root-relative paths)
+  copyTree(path.join(ROOT, 'commands', 'pan'), path.join(OUT, 'commands', 'pan'), rewriteContent);
+
+  // 3. Agents
+  copyTree(path.join(ROOT, 'agents'), path.join(OUT, 'agents'), rewriteContent);
+
+  // 4. Hooks: config + scripts
+  fs.mkdirSync(path.join(OUT, 'hooks'), { recursive: true });
+  fs.writeFileSync(
+    path.join(OUT, 'hooks', 'hooks.json'),
+    JSON.stringify(lib.buildPluginHooksConfig(), null, 2) + '\n'
+  );
+  const hooksDist = path.join(ROOT, 'hooks', 'dist');
+  if (fs.existsSync(hooksDist)) {
+    for (const f of fs.readdirSync(hooksDist).filter(n => n.endsWith('.js'))) {
+      fs.copyFileSync(path.join(hooksDist, f), path.join(OUT, 'hooks', f));
+    }
+  }
+
+  // 5. Core (strip source-only internal learnings, same policy as the installer)
+  copyTree(path.join(ROOT, 'pan-wizard-core'), path.join(OUT, 'pan-wizard-core'), rewriteContent);
+  fs.rmSync(path.join(OUT, 'pan-wizard-core', 'learnings', 'internal'), { recursive: true, force: true });
+  fs.writeFileSync(path.join(OUT, 'pan-wizard-core', 'VERSION'), pkg.version);
+
+  // Sanity report
+  const count = (p) => { try { return fs.readdirSync(p).length; } catch { return 0; } };
+  console.log('PAN plugin built at', path.relative(ROOT, OUT));
+  console.log('  commands/pan:', count(path.join(OUT, 'commands', 'pan')));
+  console.log('  agents:', count(path.join(OUT, 'agents')));
+  console.log('  hooks:', count(path.join(OUT, 'hooks')));
+  console.log('  version:', pkg.version);
+}
+
+main();

package/scripts/git-hooks/pre-commit

@@ -0,0 +1,40 @@
+#!/bin/sh
+# PAN Wizard pre-commit hook.
+#
+# Runs `gitleaks protect` against staged changes. Blocks the commit if a
+# secret is detected. The PAN allowlists in .gitleaks.toml are honoured.
+#
+# Install once per clone:
+#   cp scripts/git-hooks/pre-commit .git/hooks/pre-commit
+#   chmod +x .git/hooks/pre-commit
+# Or with a symlink (Unix / Git Bash):
+#   ln -sf ../../scripts/git-hooks/pre-commit .git/hooks/pre-commit
+#
+# Bypass for an emergency (creates a paper trail in the commit log):
+#   SKIP_GITLEAKS=1 git commit -m "..."
+#
+# Exit codes:
+#   0  ok — no secrets detected (or gitleaks not installed; we don't block).
+#   1  gitleaks found something — fix the staged change before committing.
+
+set -e
+
+if [ "${SKIP_GITLEAKS:-}" = "1" ]; then
+  echo "[pre-commit] SKIP_GITLEAKS=1 — gitleaks bypassed."
+  exit 0
+fi
+
+if ! command -v gitleaks >/dev/null 2>&1; then
+  echo "[pre-commit] gitleaks not installed — skipping secret scan." >&2
+  echo "[pre-commit] Install with: winget install gitleaks.gitleaks" >&2
+  exit 0
+fi
+
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+CONFIG="$REPO_ROOT/.gitleaks.toml"
+
+if [ -f "$CONFIG" ]; then
+  exec gitleaks protect --staged --no-banner --redact --config "$CONFIG"
+else
+  exec gitleaks protect --staged --no-banner --redact
+fi

package/scripts/install-git-hooks.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+/**
+ * install-git-hooks.js
+ *
+ * Points this repo's git at `scripts/git-hooks/` instead of the per-clone
+ * `.git/hooks/` directory. Run automatically by the `prepare` npm script,
+ * which fires on `npm install` inside the source repo.
+ *
+ * Why this exists:
+ *   `.git/hooks/` is per-clone (never committed). Without this, every fresh
+ *   clone of PAN Wizard would have to manually `cp scripts/git-hooks/pre-commit
+ *   .git/hooks/` to get the gitleaks pre-commit scan. With `core.hooksPath`
+ *   set to the tracked `scripts/git-hooks/` directory, the hook is active
+ *   the moment you finish `npm install`.
+ *
+ * No-op when not in a git working tree (e.g., the package is being installed
+ * as a dependency in someone else's `node_modules/`, where there's no `.git`).
+ *
+ * Safe to re-run.
+ */
+
+'use strict';
+
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const REPO_ROOT = path.resolve(__dirname, '..');
+const HOOKS_DIR = 'scripts/git-hooks';
+
+// 1. Are we in a git working tree? If not, this is a downstream install —
+//    do nothing.
+const gitDir = path.join(REPO_ROOT, '.git');
+if (!fs.existsSync(gitDir)) {
+  // Silent no-op for downstream consumers. Their `node_modules/pan-wizard/`
+  // doesn't have its own .git directory.
+  process.exit(0);
+}
+
+// 2. Set core.hooksPath. Idempotent — overwrites any previous value.
+try {
+  execFileSync('git', ['config', '--local', 'core.hooksPath', HOOKS_DIR], {
+    cwd: REPO_ROOT,
+    stdio: 'inherit',
+  });
+} catch (err) {
+  // If `git` isn't on PATH or the config write fails, warn but don't fail
+  // the install. The user can run this manually later.
+  console.warn(`[install-git-hooks] could not set core.hooksPath: ${err.message}`);
+  process.exit(0);
+}
+
+// 3. Confirm the hook file is executable on Unix. On Windows the bit doesn't
+//    matter — Git Bash treats `.sh` and shebanged scripts as executable.
+const hookFile = path.join(REPO_ROOT, HOOKS_DIR, 'pre-commit');
+if (process.platform !== 'win32') {
+  try {
+    fs.chmodSync(hookFile, 0o755);
+  } catch {
+    // Best effort.
+  }
+}
+
+console.error(`[install-git-hooks] core.hooksPath → ${HOOKS_DIR} (gitleaks pre-commit active)`);

package/scripts/release-check.js

@@ -100,6 +100,17 @@ process.stderr.write('\n[release-check] Gate 4/6: doc-lint counts docs/\n');
   }
 }
 
+
+// npm runs lifecycle scripts (prepare) before pack; any of their stdout noise
+// lands ahead of the --json payload. npm pretty-prints the JSON array starting
+// on its own line — parse from there.
+function parseNpmJson(stdout) {
+  try { return JSON.parse(stdout); } catch { /* fall through to extraction */ }
+  const m = stdout.search(/^[[{]s*$/m);
+  if (m === -1) throw new Error('no JSON payload found in npm output');
+  return JSON.parse(stdout.slice(m));
+}
+
 // Gate 5: npm pack dry-run
 process.stderr.write('\n[release-check] Gate 5/6: npm pack --dry-run\n');
 {
@@ -111,7 +122,7 @@ process.stderr.write('\n[release-check] Gate 5/6: npm pack --dry-run\n');
   }
   // Parse the JSON output to check size
   try {
-    const parsed = JSON.parse(r.stdout);
+    const parsed = parseNpmJson(r.stdout);
     const entry = Array.isArray(parsed) ? parsed[0] : parsed;
     const size = entry.size || 0;
     const fileCount = entry.files ? entry.files.length : 0;
@@ -139,7 +150,7 @@ if (SKIP_SMOKE) {
       logGate('smoke install (pack)', false, `exit ${pack.status}`);
       process.exit(1);
     }
-    const packJson = JSON.parse(pack.stdout);
+    const packJson = parseNpmJson(pack.stdout);
     const tarball = path.join(tmpDir, packJson[0].filename);
     if (!fs.existsSync(tarball)) {
       logGate('smoke install (pack)', false, `tarball not found at ${tarball}`);