@boyingliu01/xp-gate 0.5.3 → 0.6.1

package/lib/__tests__/ui-review.test.ts

@@ -0,0 +1,119 @@
+/**
+ * @test ui-review
+ * @intent Verify UI review file generation helpers
+ * @covers UI-REVIEW-001
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { execSync } from 'child_process';
+import { existsSync, mkdirSync, readFileSync, rmSync } from 'fs';
+import { join } from 'path';
+
+vi.mock('child_process', () => ({
+  execSync: vi.fn(),
+}));
+
+const mockExecSync = vi.mocked(execSync);
+const TEST_DIR = join(process.cwd(), '.ui-review-test');
+
+describe('ui-review', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    if (existsSync(TEST_DIR)) {
+      rmSync(TEST_DIR, { recursive: true, force: true });
+    }
+    mkdirSync(TEST_DIR, { recursive: true });
+  });
+
+  afterEach(() => {
+    if (existsSync(TEST_DIR)) {
+      rmSync(TEST_DIR, { recursive: true, force: true });
+    }
+  });
+
+  it('should parse file list and renamed paths', async () => {
+    const { parseFileList } = await import('../ui-review');
+    expect(parseFileList('views/a.html → views/b.html\n\nsrc/auth.ts\n')).toEqual([
+      'views/b.html',
+      'src/auth.ts',
+    ]);
+  });
+
+  it('should return changed files from staged and modified diff', async () => {
+    mockExecSync.mockReturnValue('src/components/Button.tsx\nviews/index.html\n');
+    const { getChangedFilesForReview } = await import('../ui-review');
+    expect(getChangedFilesForReview()).toEqual(['src/components/Button.tsx', 'views/index.html']);
+  });
+
+  it('should fall back to tracked files when no changes are present', async () => {
+    mockExecSync
+      .mockReturnValueOnce('')
+      .mockReturnValueOnce('src/components/Fallback.tsx\n');
+    const { getChangedFilesForReview } = await import('../ui-review');
+    expect(getChangedFilesForReview()).toEqual(['src/components/Fallback.tsx']);
+  });
+
+  it('should fall back to find command when git ls-files fails', async () => {
+    mockExecSync
+      .mockReturnValueOnce('')
+      .mockImplementationOnce(() => { throw new Error('not git'); })
+      .mockReturnValueOnce('views/index.html\n');
+    const { getChangedFilesForReview } = await import('../ui-review');
+    expect(getChangedFilesForReview()).toEqual(['views/index.html']);
+  });
+
+  it('should build an approved review result with 24h expiry', async () => {
+    mockExecSync.mockReturnValue('abc123\n');
+    const { buildUiReviewResult } = await import('../ui-review');
+    const now = new Date('2026-06-02T00:00:00.000Z');
+    const result = buildUiReviewResult(['views/index.html'], now);
+    expect(result).toMatchObject({
+      commit: 'abc123',
+      verdict: 'APPROVED',
+      design_review: 'APPROVED',
+      browser_qa: 'APPROVED',
+      ui_changes_detected: ['views/index.html'],
+    });
+    expect(result.expires).toBe('2026-06-03T00:00:00.000Z');
+  });
+
+  it('should run main and exit 0 when no UI changes are detected', async () => {
+    mockExecSync.mockReturnValue('src/auth.ts\n');
+    const exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => undefined) as never);
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => undefined);
+    const { main } = await import('../ui-review');
+    main();
+    expect(exitSpy).toHaveBeenCalledWith(0);
+    expect(logSpy).toHaveBeenCalledWith('ℹ️ No UI changes detected in staged/modified files.');
+    exitSpy.mockRestore();
+    logSpy.mockRestore();
+  });
+
+  it('should run main and write result when UI changes are detected', async () => {
+    const cwdSpy = vi.spyOn(process, 'cwd').mockReturnValue(TEST_DIR);
+    mockExecSync
+      .mockReturnValueOnce('views/index.html\n')
+      .mockReturnValueOnce('abc123\n');
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => undefined);
+    const { main } = await import('../ui-review');
+    main();
+    expect(existsSync(join(TEST_DIR, '.ui-gate-result.json'))).toBe(true);
+    expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('Generated .ui-gate-result.json'));
+    cwdSpy.mockRestore();
+    logSpy.mockRestore();
+  });
+
+  it('should write .ui-gate-result.json', async () => {
+    const { writeUiReviewResult } = await import('../ui-review');
+    const result = {
+      commit: 'abc123',
+      verdict: 'APPROVED',
+      expires: '2026-06-03T00:00:00.000Z',
+      design_review: 'APPROVED',
+      browser_qa: 'APPROVED',
+      ui_changes_detected: ['views/index.html'],
+    };
+    writeUiReviewResult(result, TEST_DIR);
+    const parsed = JSON.parse(readFileSync(join(TEST_DIR, '.ui-gate-result.json'), 'utf8'));
+    expect(parsed.ui_changes_detected).toEqual(['views/index.html']);
+  });
+});

package/lib/gate-audit.ts

@@ -0,0 +1,263 @@
+/**
+ * Gate Audit Logger — structured JSONL audit for quality gate executions.
+ *
+ * Log file: .xp-gate/audit.jsonl
+ * Rotation: max 10 MB, rename to .1, keep up to 3 archives.
+ * Fail-safe: write errors never block the caller.
+ */
+import {
+  existsSync,
+  mkdirSync,
+  appendFileSync,
+  writeFileSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  chmodSync,
+} from 'fs';
+import { join } from 'path';
+
+// ── Constants ────────────────────────────────────────────────────────────────
+
+const AUDIT_DIR = '.xp-gate';
+const AUDIT_FILE = 'audit.jsonl';
+const MAX_FILE_BYTES = 10 * 1024 * 1024; // 10 MB
+const MAX_ARCHIVES = 3;
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+export interface GateAuditEntry {
+  timestamp: string;
+  gate_id: string;
+  gate_name: string;
+  passed: boolean;
+  issues_found: number;
+  duration_ms: number;
+  trigger: 'commit' | 'push' | 'manual';
+  repo_path: string;
+  commit_hash: string;
+}
+
+// ── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Append one audit entry to .xp-gate/audit.jsonl.
+ * Creates the directory lazily on first write.
+ * NEVER throws — errors are logged to stderr only.
+ */
+export function appendAuditEntry(
+  entry: GateAuditEntry,
+  repoRoot: string = process.cwd(),
+): void {
+  try {
+    const logPath = join(repoRoot, AUDIT_DIR, AUDIT_FILE);
+
+    // Lazy-create directory
+    const dirPath = join(repoRoot, AUDIT_DIR);
+    if (!existsSync(dirPath)) {
+      mkdirSync(dirPath, { recursive: true });
+    }
+
+    // Rotate before write if file is too large
+    rotateIfNeeded(logPath);
+
+    const line = JSON.stringify(entry) + '\n';
+
+    // POSIX append with atomic semantics
+    try {
+      appendFileSync(logPath, line, 'utf8');
+      // Set restrictive permissions on first write (idempotent)
+      try {
+        chmodSync(logPath, 0o600);
+      } catch {
+        // chmod may fail on some filesystems — non-fatal
+      }
+    } catch {
+      // Windows fallback: open with 'a' flag
+      writeFileSync(logPath, line, { flag: 'a', encoding: 'utf8' });
+    }
+  } catch (err) {
+    // Fail-safe: never propagate errors to caller
+    console.error('[xp-gate audit] Failed to append entry:', (err as Error).message);
+  }
+}
+
+/**
+ * Read the last N entries from the audit log.
+ */
+export function readTailEntries(
+  count: number = 20,
+  repoRoot: string = process.cwd(),
+): GateAuditEntry[] {
+  const logPath = join(repoRoot, AUDIT_DIR, AUDIT_FILE);
+  if (!existsSync(logPath)) {
+    return [];
+  }
+
+  const content = readFileSync(logPath, 'utf8').trim();
+  if (!content) {
+    return [];
+  }
+
+  const allLines = content.split('\n');
+  const tailLines = allLines.slice(-count);
+  const entries: GateAuditEntry[] = [];
+
+  for (const line of tailLines) {
+    if (line.trim()) {
+      try {
+        entries.push(JSON.parse(line) as GateAuditEntry);
+      } catch {
+        // Skip malformed lines
+      }
+    }
+  }
+
+  return entries;
+}
+
+/**
+ * Compute per-gate aggregate statistics.
+ */
+export function computeStats(
+  repoRoot: string = process.cwd(),
+): { gate_id: string; pass_pct: string; avg_ms: number; avg_issues: number }[] {
+  const logPath = join(repoRoot, AUDIT_DIR, AUDIT_FILE);
+  if (!existsSync(logPath)) {
+    return [];
+  }
+
+  const content = readFileSync(logPath, 'utf8').trim();
+  if (!content) {
+    return [];
+  }
+
+  // Parse all valid entries
+  const entries: GateAuditEntry[] = [];
+  for (const line of content.split('\n')) {
+    if (line.trim()) {
+      try {
+        entries.push(JSON.parse(line) as GateAuditEntry);
+      } catch {
+        // Skip malformed
+      }
+    }
+  }
+
+  // Aggregate by gate_id
+  const buckets = new Map<string, { total: number; passed: number; ms: number; issues: number }>();
+
+  for (const e of entries) {
+    const b = buckets.get(e.gate_id) ?? { total: 0, passed: 0, ms: 0, issues: 0 };
+    b.total += 1;
+    if (e.passed) b.passed += 1;
+    b.ms += e.duration_ms;
+    b.issues += e.issues_found;
+    buckets.set(e.gate_id, b);
+  }
+
+  const results: { gate_id: string; pass_pct: string; avg_ms: number; avg_issues: number }[] = [];
+
+  for (const [gate_id, b] of Array.from(buckets.entries())) {
+    results.push({
+      gate_id,
+      pass_pct: (b.total > 0 ? ((b.passed / b.total) * 100).toFixed(1) + '%' : 'N/A'),
+      avg_ms: b.total > 0 ? Math.round(b.ms / b.total) : 0,
+      avg_issues: b.total > 0 ? parseFloat((b.issues / b.total).toFixed(2)) : 0,
+    });
+  }
+
+  // Sort by gate_id for stable output
+  results.sort((a, b) => a.gate_id.localeCompare(b.gate_id));
+  return results;
+}
+
+/**
+ * Rotate the audit log if it exceeds MAX_FILE_BYTES.
+ * Renames current file to .1, shifts existing archives.
+ * Keeps at most MAX_ARCHIVES archived files.
+ */
+function shouldRotate(logPath: string): boolean {
+  if (!existsSync(logPath)) return false;
+  try {
+    return statSync(logPath).size >= MAX_FILE_BYTES;
+  } catch {
+    return false;
+  }
+}
+
+function shiftOldArchives(logPath: string): void {
+  for (let i = MAX_ARCHIVES; i >= 2; i--) {
+    const from = `${logPath}.${i - 1}`;
+    const to = `${logPath}.${i}`;
+    if (existsSync(from)) {
+      try { renameSync(from, to); } catch { /* skip */ }
+    }
+  }
+}
+
+function archiveCurrent(logPath: string): void {
+  const first = `${logPath}.1`;
+  if (existsSync(first)) {
+    try { renameSync(first, `${logPath}.2`); } catch { /* skip */ }
+  }
+  try {
+    renameSync(logPath, first);
+  } catch {
+    try { writeFileSync(logPath, '', 'utf8'); } catch { /* skip */ }
+  }
+}
+
+export function rotateIfNeeded(logPath: string): void {
+  if (!shouldRotate(logPath)) return;
+  shiftOldArchives(logPath);
+  archiveCurrent(logPath);
+}
+
+function runCli(): void {
+  const args = process.argv.slice(2);
+  const command = args[0];
+
+  if (command === 'record') {
+    const opts = parseCliOptions(args.slice(1));
+    const entry: GateAuditEntry = {
+      timestamp: new Date().toISOString(),
+      gate_id: opts['gate-id'] || 'unknown',
+      gate_name: opts['gate-name'] || 'unknown',
+      passed: opts['passed'] === 'true',
+      issues_found: parseInt(opts['issues-found'] || '0', 10),
+      duration_ms: parseInt(opts['duration-ms'] || '0', 10),
+      trigger: (opts['trigger'] as 'commit' | 'push' | 'manual') || 'manual',
+      repo_path: process.cwd(),
+      commit_hash: getCommitHash(),
+    };
+    appendAuditEntry(entry);
+  } else {
+    console.error(`Unknown audit command: ${command}`);
+    process.exit(1);
+  }
+}
+
+if (require.main === module) {
+  runCli();
+}
+
+export function parseCliOptions(args: string[]): Record<string, string> {
+  const opts: Record<string, string> = {};
+  for (let i = 0; i < args.length; i++) {
+    if (args[i].startsWith('--') && i + 1 < args.length) {
+      opts[args[i].slice(2)] = args[i + 1];
+      i++;
+    }
+  }
+  return opts;
+}
+
+export function getCommitHash(): string {
+  try {
+    const { execSync } = require('child_process');
+    return execSync('git rev-parse HEAD', { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+  } catch {
+    return 'unknown';
+  }
+}

package/lib/install-skill.js

@@ -144,21 +144,7 @@ async function downloadFile(url, dest, verbose) {
   });
 }
 
-function copyDirRecursive(src, dest) {
-  fs.mkdirSync(dest, { recursive: true });
-  const entries = fs.readdirSync(src, { withFileTypes: true });
-  
-  for (const entry of entries) {
-    const srcPath = path.join(src, entry.name);
-    const destPath = path.join(dest, entry.name);
-    
-    if (entry.isDirectory()) {
-      copyDirRecursive(srcPath, destPath);
-    } else {
-      fs.copyFileSync(srcPath, destPath);
-    }
-  }
-}
+const { copyDirRecursive } = require('./shared-utils');
 
 function ensureConfigDir() {
   fs.mkdirSync(CONFIG_DIR, { recursive: true });

package/lib/rollback.js

@@ -1,6 +1,7 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
+const { copyDirRecursive } = require('./shared-utils');
 
 // Cross-platform home directory resolution
 const HOME = process.env.HOME || process.env.USERPROFILE || os.homedir();
@@ -51,22 +52,6 @@ async function createBackup(installId, skillName) {
   return backupDir;
 }
 
-function copyDirRecursive(src, dest) {
-  fs.mkdirSync(dest, { recursive: true });
-  const entries = fs.readdirSync(src, { withFileTypes: true });
-  
-  for (const entry of entries) {
-    const srcPath = path.join(src, entry.name);
-    const destPath = path.join(dest, entry.name);
-    
-    if (entry.isDirectory()) {
-      copyDirRecursive(srcPath, destPath);
-    } else {
-      fs.copyFileSync(srcPath, destPath);
-    }
-  }
-}
-
 function cleanupBackup(installId) {
   const backupDir = path.join(BACKUP_DIR, installId);
   

package/lib/shared-utils.js

@@ -0,0 +1,25 @@
+/**
+ * Pure utility functions shared by CLI modules.
+ * No module-level state — safe for tests that mock fs/path/os.
+ */
+const fs = require('fs');
+
+/**
+ * Recursively copy a directory.
+ * Pure function: only uses fs/path params, no global config.
+ */
+function copyDirRecursive(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = require('path').join(src, entry.name);
+    const destPath = require('path').join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDirRecursive(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+module.exports = { copyDirRecursive };

package/lib/ui-detector.ts

@@ -204,21 +204,21 @@ function processOutput(input: string, repoRoot: string): void {
     .map(parseRenamedFile)
     .filter((f) => f.length > 0);
   const result = collectUiMatches(files, repoRoot);
-  // eslint-disable-next-line no-console
+   
   console.log(JSON.stringify(result, null, 2));
   process.exit(result.isUiSprint ? 0 : 1);
 }
 
-function runCheckBranch(repoRoot: string): void {
+function runCheckBranch(_repoRoot: string): void {
   const result = detectUiSprint('HEAD');
-  // eslint-disable-next-line no-console
+   
   console.log(JSON.stringify(result, null, 2));
   process.exit(result.isUiSprint ? 0 : 1);
 }
 
-function runDefault(repoRoot: string): void {
+function runDefault(_repoRoot: string): void {
   const result = detectUiSprint();
-  // eslint-disable-next-line no-console
+   
   console.log(JSON.stringify(result, null, 2));
   process.exit(result.isUiSprint ? 0 : 1);
 }

package/lib/ui-review.ts

@@ -5,7 +5,7 @@ import { collectUiMatches, parseRenamedFile } from './ui-detector';
 
 const RESULT_FILE = '.ui-gate-result.json';
 
-interface UiReviewResult {
+export interface UiReviewResult {
   commit: string;
   verdict: string;
   expires: string;
@@ -14,96 +14,101 @@ interface UiReviewResult {
   ui_changes_detected: string[];
 }
 
-function main(): void {
-  // eslint-disable-next-line no-console
-  console.log('═══ xp-gate ui-review ═══');
-  // eslint-disable-next-line no-console
-  console.log('');
-
-  // Get staged + modified files
+export function getChangedFilesForReview(): string[] {
   let files = '';
   try {
     files = execSync('git diff --cached --name-only && git diff --name-only', { encoding: 'utf8' }).trim();
   } catch {
-    // eslint-disable-next-line no-console
     console.log('⚠️ No git repo or no changes. Running in current directory.');
   }
 
-  const fileList = files
+  const fileList = parseFileList(files);
+  if (fileList.length > 0) {
+    return fileList;
+  }
+
+  console.log('No files staged or modified. Checking all tracked files.');
+  return getFallbackFileList();
+}
+
+export function parseFileList(files: string): string[] {
+  return files
     .split('\n')
     .map(parseRenamedFile)
     .filter(f => f.length > 0);
+}
 
-  if (fileList.length === 0) {
-    // eslint-disable-next-line no-console
-    console.log('No files staged or modified. Checking all tracked files.');
-    try {
-      files = execSync('git ls-files', { encoding: 'utf8' }).trim();
-    } catch {
-      files = execSync('find . -maxdepth 3 -type f -name "*.ts" -o -name "*.html" -o -name "*.css" -o -name "*.scss" -o -name "*.tsx" -o -name "*.vue" -o -name "*.svelte" 2>/dev/null | grep -v node_modules | grep -v .git', { encoding: 'utf8' }).trim();
-    }
-    fileList.push(...files.split('\n').filter(f => f.length > 0));
+export function getFallbackFileList(): string[] {
+  try {
+    return parseFileList(execSync('git ls-files', { encoding: 'utf8' }).trim());
+  } catch {
+    const output = execSync(
+      'find . -maxdepth 3 -type f -name "*.ts" -o -name "*.html" -o -name "*.css" -o -name "*.scss" -o -name "*.tsx" -o -name "*.vue" -o -name "*.svelte" 2>/dev/null | grep -v node_modules | grep -v .git',
+      { encoding: 'utf8' },
+    ).trim();
+    return parseFileList(output);
   }
+}
+
+export function buildUiReviewResult(matchedFiles: string[], now: Date = new Date()): UiReviewResult {
+  const commit = getCurrentCommit();
+  const expires = new Date(now.getTime() + 24 * 60 * 60 * 1000).toISOString();
+
+  return {
+    commit,
+    verdict: 'APPROVED',
+    expires,
+    design_review: 'APPROVED',
+    browser_qa: 'APPROVED',
+    ui_changes_detected: matchedFiles,
+  };
+}
+
+export function writeUiReviewResult(result: UiReviewResult, repoRoot: string = process.cwd()): void {
+  writeFileSync(join(repoRoot, RESULT_FILE), JSON.stringify(result, null, 2) + '\n', 'utf8');
+}
+
+function getCurrentCommit(): string {
+  return execSync('git rev-parse HEAD 2>/dev/null || echo "no-commit"', { encoding: 'utf8' }).trim();
+}
+
+export function main(): void {
+  console.log('═══ xp-gate ui-review ═══');
+  console.log('');
 
+  const fileList = getChangedFilesForReview();
   const result = collectUiMatches(fileList);
 
   if (!result.isUiSprint) {
-    // eslint-disable-next-line no-console
     console.log('ℹ️ No UI changes detected in staged/modified files.');
-    // eslint-disable-next-line no-console
     console.log('  Nothing to review. Exiting.');
     process.exit(0);
   }
 
-  // eslint-disable-next-line no-console
   console.log(`🎨 UI changes detected (${result.matchedFiles.length} files):`);
   result.matchedFiles.forEach(f => console.log(`  - ${f}`));
-  // eslint-disable-next-line no-console
   console.log('');
 
-  // eslint-disable-next-line no-console
   console.log('Next steps required before push:');
-  // eslint-disable-next-line no-console
   console.log('  1. Run /design-review in your AI agent session');
-  // eslint-disable-next-line no-console
   console.log('  2. Run /qa or /qa-only in your AI agent session');
-  // eslint-disable-next-line no-console
   console.log('  3. Ensure you have .delphi-config.json configured for Delphi review');
-  // eslint-disable-next-line no-console
   console.log('');
 
-  const commit = execSync('git rev-parse HEAD 2>/dev/null || echo "no-commit"', { encoding: 'utf8' }).trim();
-  const expires = new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString();
+  const uiResult = buildUiReviewResult(result.matchedFiles);
+  writeUiReviewResult(uiResult);
 
-  const uiResult: UiReviewResult = {
-    commit,
-    verdict: 'APPROVED',
-    expires,
-    design_review: 'APPROVED',
-    browser_qa: 'APPROVED',
-    ui_changes_detected: result.matchedFiles,
-  };
-
-  writeFileSync(join(process.cwd(), RESULT_FILE), JSON.stringify(uiResult, null, 2) + '\n', 'utf8');
-
-  // eslint-disable-next-line no-console
   console.log(`✅ Generated ${RESULT_FILE} with APPROVED verdict (template)`);
-  // eslint-disable-next-line no-console
-  console.log(`   Commit: ${commit}`);
-  // eslint-disable-next-line no-console
-  console.log(`   Expires: ${expires}`);
-  // eslint-disable-next-line no-console
+  console.log(`   Commit: ${uiResult.commit}`);
+  console.log(`   Expires: ${uiResult.expires}`);
   console.log('');
-  // eslint-disable-next-line no-console
   console.log('⚠️  REVIEW THIS FILE before push:');
-  // eslint-disable-next-line no-console
   console.log('   - Ensure design_review and browser_qa are actually APPROVED');
-  // eslint-disable-next-line no-console
   console.log('   - Edit verdict to REJECTED if issues found');
-  // eslint-disable-next-line no-console
   console.log('');
-  // eslint-disable-next-line no-console
   console.log('Then: git push (pre-push will validate this file)');
 }
 
-main();
+if (require.main === module) {
+  main();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boyingliu01/xp-gate",
-  "version": "0.5.3",
+  "version": "0.6.1",
   "description": "AI-driven development workflow: 6 quality gates + Delphi review + Sprint Flow",
   "bin": {
     "xp-gate": "./bin/xp-gate.js"

package/plugins/claude-code/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "xp-gate",
-  "version": "0.5.3",
+  "version": "0.6.1",
   "displayName": "XP-Gate",
   "description": "Extreme Programming quality gates + AI workflow skills for Claude Code. Includes 6 quality gates, Sprint Flow, and Delphi multi-expert review.",
   "author": {