@boyingliu01/xp-gate 0.14.8 → 0.14.10

package/lib/check.js

@@ -2,49 +2,144 @@
 
 const { principles } = require('./principles.js');
 const { arch } = require('./arch.js');
+const { getGateInfo, runGate } = require('./gate-runner.js');
+
+function parseCheckArgs(args) {
+  const flags = { all: false, list: false, gateIds: null };
+  const posArgs = [];
+  let i = 0;
+  while (i < args.length) {
+    const arg = args[i];
+    if (arg === '--all') { flags.all = true; i++; }
+    else if (arg === '--list') { flags.list = true; i++; }
+    else if (arg === '--gates' && i + 1 < args.length) {
+      flags.gateIds = args[i + 1].split(',').map(s => s.trim()).filter(Boolean);
+      i += 2;
+    }
+    else if (arg.startsWith('--gates=')) {
+      flags.gateIds = arg.split('=')[1].split(',').map(s => s.trim()).filter(Boolean);
+      i++;
+    }
+    else { posArgs.push(arg); i++; }
+  }
+  const rawTarget = posArgs[0] || null;
+  const isGateNumber = rawTarget && /^\d+$/.test(rawTarget);
+  return {
+    ...flags,
+    positionals: posArgs,
+    pathArg: isGateNumber ? posArgs[1] || null : rawTarget,
+    gateNumber: isGateNumber ? rawTarget : null,
+  };
+}
 
-// Runs the user-invokable subset of quality gates on a path. Mirrors what the
-// pre-commit hook does, but as a standalone CLI surface. Intentionally narrower
-// than the full pre-commit run (no git staging context, no Boy Scout baseline).
-// Currently delegates to: Gate 4 (Principles) + Gate 6 (Architecture).
 async function check(args) {
-  const target = args[0];
-  if (!target) {
-    console.error('Usage: xp-gate check <file_or_directory> [--gates principles,arch]');
+  const opts = parseCheckArgs(args);
+
+  if (opts.list) return listGates();
+  if (opts.gateNumber && !opts.all && !opts.gateIds) return runGate(opts.gateNumber, opts.pathArg);
+  if (opts.all) return checkAllGates(opts.pathArg);
+  if (opts.gateIds && opts.gateIds.length > 0) return runGatesByIds(opts.gateIds, opts.pathArg);
+
+  if (!opts.pathArg) {
+    console.error('Usage: xp-gate check <file_or_directory|gate_number> [options]');
+    console.error('');
+    console.error('Options:');
+    console.error('  --gates <ids>    Run specific gates (comma-separated, e.g. "3,4,6")');
+    console.error('  --all             Run all invokable gates');
+    console.error('  --list            List all available gates');
+    console.error('');
+    console.error('Examples:');
+    console.error('  xp-gate check src/                   # Run principles + architecture check');
+    console.error('  xp-gate check 3                      # Run Gate 3 (Complexity)');
+    console.error('  xp-gate check --gates 3,4,6          # Run gates 3, 4, and 6');
+    console.error('  xp-gate check --all                  # Run all invokable gates');
+    console.error('  xp-gate check --list                 # List available gates');
     return 1;
   }
 
-  const gatesIdx = args.indexOf('--gates');
-  const gateList = gatesIdx >= 0
-    ? args[gatesIdx + 1].split(',').map(s => s.trim()).filter(Boolean)
-    : ['principles', 'arch'];
+  return runDefaultChecks(opts.pathArg);
+}
+
+async function runDefaultChecks(target) {
+  let failures = 0;
+  let ran = 0;
+
+  console.log('━━━ Gate 4: Principles ━━━');
+  const principlesCode = await principles([target]);
+  if (principlesCode !== 0) failures += 1;
+  ran += 1;
+
+  console.log('━━━ Gate 6: Architecture ━━━');
+  const archCode = await arch([]);
+  if (archCode !== 0) failures += 1;
+  ran += 1;
+
+  console.log('');
+  console.log(`[xp-gate check] ${ran - failures}/${ran} gate(s) passed`);
+  return failures === 0 ? 0 : 1;
+}
 
+async function checkAllGates(target) {
+  const { getAllGates } = require('./gate-runner.js');
+  const invokableGates = getAllGates().filter(g => !g.preCommitOnly);
   let failures = 0;
   let ran = 0;
 
-  if (gateList.includes('principles')) {
-    console.log('━━━ Gate 4: Principles ━━━');
-    const code = await principles([target]);
+  for (const gate of invokableGates) {
+    const code = await runGate(gate.id, target);
     if (code !== 0) failures += 1;
     ran += 1;
+    console.log('');
   }
 
-  if (gateList.includes('arch')) {
-    console.log('━━━ Gate 6: Architecture ━━━');
-    const code = await arch([]);
+  console.log(`[xp-gate check --all] ${ran - failures}/${ran} gate(s) passed`);
+  return failures === 0 ? 0 : 1;
+}
+
+async function runGatesByIds(gateIds, target) {
+  let failures = 0;
+  let ran = 0;
+
+  for (const gateId of gateIds) {
+    const code = await runGate(gateId, target);
     if (code !== 0) failures += 1;
     ran += 1;
+    console.log('');
   }
 
   if (ran === 0) {
-    console.error(`[xp-gate check] No valid gates in --gates list: ${gateList.join(',')}`);
-    console.error('  Available gates: principles, arch');
+    console.error(`[xp-gate check] No valid gates in --gates list: ${gateIds.join(',')}`);
+    console.error('  Run: xp-gate check --list  to see available gates');
     return 1;
   }
 
-  console.log('');
   console.log(`[xp-gate check] ${ran - failures}/${ran} gate(s) passed`);
   return failures === 0 ? 0 : 1;
 }
 
+function listGates() {
+  const { getAllGates } = require('./gate-runner.js');
+  const allGates = getAllGates();
+
+  console.log('');
+  console.log('XP-Gate Quality Gates:');
+  console.log('┌──────┬──────────────────────────────┬──────────┬──────────────────────────────────────────┐');
+  console.log('│ Gate │ Name                         │ CLI      │ Description                              │');
+  console.log('├──────┼──────────────────────────────┼──────────┼──────────────────────────────────────────┤');
+  for (const gate of allGates) {
+    const id = gate.id.padEnd(4);
+    const name = gate.name.slice(0, 28).padEnd(28);
+    const cli = gate.preCommitOnly ? 'commit' : 'check';
+    const desc = gate.description.slice(0, 40).padEnd(40);
+    console.log(`│ ${id} │ ${name} │ ${cli.padEnd(8)} │ ${desc} │`);
+  }
+  console.log('└──────┴──────────────────────────────┴──────────┴──────────────────────────────────────────┘');
+  console.log('');
+  console.log('Legend:');
+  console.log('  check   — invokable via xp-gate check <gate-id>');
+  console.log('  commit  — only runs during git commit (pre-commit hook)');
+  console.log('');
+  return 0;
+}
+
 module.exports = { check };

package/lib/doctor.js

@@ -263,6 +263,9 @@ function diagnose() {
   // --- Check 8: TUI auto-registration ---
   issues += diagnoseTuiRegistration(checks);
 
+  // --- Check 9: Installed skills version consistency (#332) ---
+  issues += diagnoseInstalledSkills(config, checks);
+
   return { checks, issues };
 }
 
@@ -689,6 +692,66 @@ function diagnoseTuiRegistration(checks) {
   return 1;
 }
 
+/**
+ * Check 9: Installed skills vs package-bundled skills (#332).
+ * Reports WARN for each installed skill whose SKILL.md differs from the bundled version.
+ * @param {object} config
+ * @param {Array} checks
+ * @returns {number} issue count
+ */
+function diagnoseInstalledSkills(config, checks) {
+  const installedSkills = config.installedSkills || {};
+  const skillNames = Object.keys(installedSkills);
+  if (skillNames.length === 0) {
+    checks.push({ name: 'Installed skills', status: 'SKIP', detail: 'No skills installed' });
+    return 0;
+  }
+
+  const bundledSkillsDir = path.join(PKG_DIR, 'skills');
+  if (!fs.existsSync(bundledSkillsDir)) {
+    checks.push({ name: 'Installed skills', status: 'SKIP', detail: 'Package skills dir not found' });
+    return 0;
+  }
+
+  const platform = detectPlatform();
+  let userSkillsDir;
+  if (platform === 'qoder') {
+    userSkillsDir = path.join(HOME_DIR, '.qoder', 'skills');
+  } else if (platform === 'claude-code') {
+    userSkillsDir = path.join(HOME_DIR, '.claude', 'skills');
+  } else {
+    userSkillsDir = path.join(HOME_DIR, '.config', 'opencode', 'skills');
+  }
+
+  let issues = 0;
+  for (const name of skillNames) {
+    const bundledSkillMd = path.join(bundledSkillsDir, name, 'SKILL.md');
+    const userSkillMd = path.join(userSkillsDir, name, 'SKILL.md');
+
+    if (!fs.existsSync(bundledSkillMd)) continue;
+    if (!fs.existsSync(userSkillMd)) {
+      checks.push({ name: `Skill: ${name}`, status: 'FAIL', detail: 'Installed SKILL.md missing' });
+      issues++;
+      continue;
+    }
+
+    const bundledContent = fs.readFileSync(bundledSkillMd, 'utf8');
+    const userContent = fs.readFileSync(userSkillMd, 'utf8');
+    if (bundledContent !== userContent) {
+      checks.push({
+        name: `Skill: ${name}`,
+        status: 'WARN',
+        detail: 'Outdated — run xp-gate update-skill --all',
+      });
+      issues++;
+    } else {
+      checks.push({ name: `Skill: ${name}`, status: 'PASS', detail: 'Up to date' });
+    }
+  }
+
+  return issues;
+}
+
 /**
  * Fix TUI registration: ensure @boyingliu01/opencode-plugin/tui is in tui.json.
  * Uses atomic write (tmp + renameSync) for JSON safety.

package/lib/gate-runner.js

@@ -0,0 +1,209 @@
+'use strict';
+
+const { execSync, execFileSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+// Gate metadata registry — maps gate IDs to names, descriptions, and how to run them.
+// Standalone gates (<gate-id>: { run }) are invokable via xp-gate gate-<id>.
+// Pre-commit-only gates (<gate-id>: { preCommitOnly: true }) run only in git commit context.
+const GATE_REGISTRY = {
+  '0': {
+    name: 'Version Consistency',
+    description: 'Check VERSION file matches all package.json versions',
+    preCommitOnly: true,
+    reason: 'Requires git-staged context to compare VERSION with package.json files',
+  },
+  '1': {
+    name: 'Code Quality',
+    description: 'Language-specific static analysis and linting (ESLint, Ruff, govet, etc.)',
+    preCommitOnly: true,
+    reason: 'Requires language detection from changed files and adapter routing',
+  },
+  '2': {
+    name: 'Duplicate Code',
+    description: 'jscpd duplicate code detection',
+    run: (targetPath) => {
+      const jscpdConfig = findConfig(targetPath, 'jscpd.conf.json');
+      const args = [targetPath || '.'];
+      if (jscpdConfig) args.push('--config', jscpdConfig);
+      execFileSync('npx', ['-y', 'jscpd', ...args], { stdio: 'inherit' });
+    },
+  },
+  '3': {
+    name: 'Cyclomatic Complexity',
+    description: 'lizard cyclomatic complexity analysis',
+    run: (targetPath) => {
+      const script = resolveGateScript('3');
+      if (script) {
+        execSync(`bash "${script}"`, { stdio: 'inherit' });
+      } else {
+        const target = targetPath || '.';
+        console.log(`Running lizard on ${target}...`);
+        execFileSync('lizard', [target, '--CCN', '10', '--length', '50', '--arguments', '5', '--warnings_only'], { stdio: 'inherit' });
+      }
+    },
+  },
+  '4': {
+    name: 'Clean Code + SOLID Principles',
+    description: '14 Clean Code/SOLID rules across 9 languages',
+    run: (targetPath) => {
+      const { principles } = require('./principles.js');
+      return principles([targetPath || '.']);
+    },
+  },
+  '5': {
+    name: 'Tests + Coverage',
+    description: 'Unit test execution and code coverage enforcement (≥80%)',
+    preCommitOnly: true,
+    reason: 'Requires language detection and adapter-sourced test execution with coverage reports',
+  },
+  '6': {
+    name: 'Architecture + Boy Scout Rule',
+    description: 'Architecture layer boundary validation and warning baseline enforcement',
+    run: (targetPath) => {
+      const { arch } = require('./arch.js');
+      return arch([]);
+    },
+  },
+  '7': {
+    name: 'IaC Security',
+    description: 'Infrastructure-as-Code security scanning (checkov, hadolint, kube-score, tflint)',
+    run: (targetPath) => {
+      const script = resolveGateScript('7');
+      if (script) {
+        execSync(`bash "${script}"`, { stdio: 'inherit' });
+      } else {
+        console.log('IaC security scan requires git-staged context for changed files detection.');
+        console.log('Run: git commit to trigger Gate 7 automatically.');
+      }
+    },
+  },
+  '8': {
+    name: 'Secret Scanning',
+    description: 'gitleaks secret and credential detection',
+    run: (targetPath) => {
+      const script = resolveGateScript('8');
+      if (script) {
+        execSync(`bash "${script}"`, { stdio: 'inherit' });
+      } else {
+        console.log('Secret scanning requires git-staged context for changed files detection.');
+        console.log('Run: git commit to trigger Gate 8 automatically.');
+      }
+    },
+  },
+  '9': {
+    name: 'SAST Security',
+    description: 'semgrep static application security testing',
+    run: (targetPath) => {
+      const script = resolveGateScript('9');
+      if (script) {
+        execSync(`bash "${script}"`, { stdio: 'inherit' });
+      } else {
+        console.log('SAST scanning requires git-staged context for changed files detection.');
+        console.log('Run: git commit to trigger Gate 9 automatically.');
+      }
+    },
+  },
+  '10': {
+    name: 'Build Integrity',
+    description: 'TypeScript compilation, npm pack, and import validation',
+    preCommitOnly: true,
+    reason: 'Build integrity checks require language detection and build tool context',
+  },
+  '11': {
+    name: 'Sprint Flow Enforcement',
+    description: 'Sprint state and delphi-review validation',
+    preCommitOnly: true,
+    reason: 'Requires sprint state (.sprint-state/) and git branch context',
+  },
+};
+
+function findConfig(basePath, fileName) {
+  const candidates = [
+    path.join(basePath || '.', fileName),
+    path.join(process.cwd(), fileName),
+  ];
+  for (const c of candidates) {
+    if (fs.existsSync(c)) return c;
+  }
+  return null;
+}
+
+function resolveGateScript(gateNum) {
+  const candidates = [
+    path.join(process.cwd(), 'githooks', 'gates', `gate-${gateNum}-*.sh`),
+    path.join(process.cwd(), 'githooks', `gate-${gateNum}.sh`),
+  ];
+
+  // Try glob patterns
+  for (const pattern of candidates) {
+    if (pattern.includes('*')) {
+      const dir = path.dirname(pattern);
+      const prefix = path.basename(pattern).replace('*', '');
+      if (fs.existsSync(dir)) {
+        const match = fs.readdirSync(dir).find(f => f.startsWith(`gate-${gateNum}-`) && f.endsWith('.sh'));
+        if (match) return path.join(dir, match);
+      }
+    } else if (fs.existsSync(pattern)) {
+      return pattern;
+    }
+  }
+
+  // Check global install
+  const globalDir = path.join(require('os').homedir(), '.config', 'xp-gate', 'adapters');
+  const globalScript = path.join(globalDir, `gate-${gateNum}.sh`);
+  if (fs.existsSync(globalScript)) return globalScript;
+
+  return null;
+}
+
+function getGateInfo(gateId) {
+  return GATE_REGISTRY[String(gateId)] || null;
+}
+
+function getAllGates() {
+  return Object.entries(GATE_REGISTRY).map(([id, info]) => ({
+    id,
+    name: info.name,
+    description: info.description,
+    preCommitOnly: info.preCommitOnly || false,
+    reason: info.reason || null,
+  }));
+}
+
+async function runGate(gateId, targetPath) {
+  const gate = GATE_REGISTRY[String(gateId)];
+  if (!gate) {
+    console.error(`Unknown gate: ${gateId}`);
+    console.error('Available gates: ' + Object.keys(GATE_REGISTRY).join(', '));
+    return 1;
+  }
+
+  if (gate.preCommitOnly) {
+    console.log(`━━━ Gate ${gateId}: ${gate.name} ━━━`);
+    console.log(`⏭️  SKIPPED - ${gate.reason}`);
+    console.log('   This gate runs automatically during git commit.');
+    console.log('   Run: git commit to trigger all gates.');
+    return 0;
+  }
+
+  if (gate.run) {
+    console.log(`━━━ Gate ${gateId}: ${gate.name} ━━━`);
+    try {
+      const result = gate.run(targetPath);
+      if (result && typeof result.then === 'function') {
+        return await result;
+      }
+      return 0;
+    } catch (err) {
+      console.error(` Gate ${gateId} FAILED: ${err.message}`);
+      return 1;
+    }
+  }
+
+  console.error(`Gate ${gateId}: ${gate.name} — no execution handler available`);
+  return 1;
+}
+
+module.exports = { GATE_REGISTRY, getGateInfo, getAllGates, runGate };

package/lib/install-skill.js

@@ -20,6 +20,15 @@ function getSkillsDir() {
   return path.join(HOME_DIR, '.config', 'opencode', 'skills');
 }
 
+function getCliVersion() {
+  try {
+    const versionFile = path.join(__dirname, '..', '..', '..', 'VERSION');
+    return fs.readFileSync(versionFile, 'utf8').trim();
+  } catch {
+    return '0.0.0';
+  }
+}
+
 const SKILLS_REGISTRY = {
   'sprint-flow': { repo: 'boyingliu01/xp-gate', path: 'skills/sprint-flow' },
   'delphi-review': { repo: 'boyingliu01/xp-gate', path: 'skills/delphi-review' },
@@ -123,10 +132,14 @@ async function performInstall(skillInfo, name, targetDir, offline, verbose) {
   }
 
   ensureConfigDir();
+  
+  // Read actual CLI version from VERSION file
+  const version = getCliVersion();
+  
   updateConfig({
     installedSkills: {
       ...(getConfig().installedSkills || {}),
-      [name]: { version: '1.0.0', installedAt: new Date().toISOString() }
+      [name]: { version, installedAt: new Date().toISOString() }
     }
   });
 

package/lib/next-sprint.js

@@ -1,12 +1,11 @@
 const childProcess = require('child_process');
-const fs = require('fs');
 const path = require('path');
+const { SprintStateManager } = require('./sprint-state-manager');
 
 function readSprintState(dir) {
   try {
-    const stateFile = path.join(dir, '.sprint-state', 'sprint-state.json');
-    if (!fs.existsSync(stateFile)) return null;
-    return JSON.parse(fs.readFileSync(stateFile, 'utf8'));
+    const manager = new SprintStateManager(dir);
+    return manager.read();
   } catch {
     return null;
   }

package/lib/shared-utils.js

@@ -60,7 +60,7 @@ function copyAdapters(srcDir, destDir) {
   const githooksDir = path.resolve(srcDir, '..', '..', '..', 'githooks');
   if (fs.existsSync(githooksDir)) {
     fs.readdirSync(githooksDir).forEach(f => {
-      if (f.startsWith('gate-') && f.endsWith('.sh')) {
+      if ((f.startsWith('gate-') || f === 'sprint-gate.sh') && f.endsWith('.sh')) {
         fs.copyFileSync(path.join(githooksDir, f), path.join(destDir, f));
       }
     });

package/lib/sprint-discovery.js

@@ -13,6 +13,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const { SprintStateManager } = require('./sprint-state-manager');
 
 /**
  * Maximum number of active sprints to return.
@@ -62,16 +63,15 @@ function findGitRoot(startDir) {
 
 /**
  * Read and parse a sprint-state.json from a given project directory.
+ * Uses SprintStateManager for schema validation + auto-migration.
  *
  * @param {string} dir - Directory containing .sprint-state/
  * @returns {object|null} Parsed sprint state, or null if not found or malformed
  */
 function readSprintState(dir) {
   try {
-    const stateFile = path.join(dir, '.sprint-state', 'sprint-state.json');
-    if (!fs.existsSync(stateFile)) return null;
-    const raw = fs.readFileSync(stateFile, 'utf8');
-    return JSON.parse(raw);
+    const manager = new SprintStateManager(dir);
+    return manager.read();
   } catch {
     return null;
   }

package/lib/sprint-state-manager.js

@@ -0,0 +1,122 @@
+/**
+ * Sprint State Manager — centralized read/write/transition for sprint state.
+ *
+ * Resolves #343 (schema drift) and #338 (auto-render enforcement).
+ *
+ * @module sprint-state-manager
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { migrateState, createInitialState, rollbackState, LEGACY_PHASE_MAP } = require('./sprint-state-migrator');
+
+class SprintStateManager {
+  constructor(projectRoot) {
+    this.projectRoot = projectRoot;
+    this.stateDir = path.join(projectRoot, '.sprint-state');
+    this.stateFile = path.join(this.stateDir, 'sprint-state.json');
+    this.backupFile = path.join(this.stateDir, 'sprint-state.json.backup');
+  }
+
+  read() {
+    if (!fs.existsSync(this.stateFile)) {
+      return null;
+    }
+
+    const raw = fs.readFileSync(this.stateFile, 'utf8');
+    let state;
+    try {
+      state = JSON.parse(raw);
+    } catch (err) {
+      throw new Error(`Failed to parse sprint-state.json: ${err.message}`);
+    }
+
+    // Check if migration needed
+    if (!state._schema_version) {
+      // Create backup before first migration
+      if (!fs.existsSync(this.backupFile)) {
+        fs.copyFileSync(this.stateFile, this.backupFile);
+      }
+      state = migrateState(state, this.stateDir);
+      // Write migrated state atomically
+      this.write(state);
+    }
+
+    return state;
+  }
+
+  write(state) {
+    // Ensure state directory exists
+    if (!fs.existsSync(this.stateDir)) {
+      fs.mkdirSync(this.stateDir, { recursive: true });
+    }
+
+    // Atomic write: write to tmp, then rename
+    const tmpFile = this.stateFile + '.tmp';
+    fs.writeFileSync(tmpFile, JSON.stringify(state, null, 2), 'utf8');
+    fs.renameSync(tmpFile, this.stateFile);
+  }
+
+  transitionPhase(phase, status, options = {}) {
+    const state = this.read() || createInitialState(this.projectRoot);
+
+    // Update current phase
+    state.phase = phase;
+
+    // Find or create phase_history entry
+    const phaseNames = ['PREP', 'DESIGN', 'BUILD', 'VERIFY', 'SHIP', 'CLOSE'];
+    const phaseName = phaseNames[phase - 1];
+
+    let entry = state.phase_history.find(e => e.phase === phase);
+    if (!entry) {
+      entry = {
+        phase,
+        phase_name: phaseName,
+        status,
+      };
+      state.phase_history.push(entry);
+    }
+
+    // Update entry
+    entry.status = status;
+    if (status === 'in_progress' && !entry.started_at) {
+      entry.started_at = new Date().toISOString();
+    }
+    if (status === 'completed' || status === 'skipped') {
+      entry.completed_at = new Date().toISOString();
+      if (entry.started_at) {
+        const startMs = new Date(entry.started_at).getTime();
+        const endMs = new Date(entry.completed_at).getTime();
+        entry.duration_seconds = Math.round((endMs - startMs) / 1000);
+      }
+    }
+
+    // Update outputs if provided
+    if (options.outputs) {
+      state.outputs = { ...state.outputs, ...options.outputs };
+    }
+
+    // Write state atomically
+    this.write(state);
+
+    // Trigger onTransition callback (for auto-render)
+    if (typeof options.onTransition === 'function') {
+      try {
+        options.onTransition(state);
+      } catch (err) {
+        // Render failure is WARNING, not BLOCK
+        console.warn(`[WARN] onTransition callback failed: ${err.message}`);
+      }
+    }
+
+    return state;
+  }
+
+  rollback() {
+    return rollbackState(this.stateFile, this.backupFile);
+  }
+}
+
+module.exports = { SprintStateManager, LEGACY_PHASE_MAP };