cc-devflow 4.1.5 → 4.2.0

package/lib/harness/operations/verify.js

@@ -0,0 +1,163 @@
+/**
+ * [INPUT]: 依赖 manifest 与 package scripts，依赖 shell gates（lint/typecheck/test/audit/review）。
+ * [OUTPUT]: 生成 report-card.json，给出 quick/strict/review 门禁结论。
+ * [POS]: harness 质量门禁入口，被 CLI `harness:verify` 调用。
+ * [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+ */
+
+const {
+  nowIso,
+  getPackageScripts,
+  readJson,
+  writeJson,
+  runCommand,
+  getTaskManifestPath,
+  getReportCardPath
+} = require('../store');
+const { parseManifest, parseReportCard } = require('../schemas');
+
+async function runGate(command, cwd, timeoutMs = 20 * 60 * 1000) {
+  const result = await runCommand(command, { cwd, timeoutMs });
+  return {
+    status: result.code === 0 ? 'pass' : 'fail',
+    durationMs: result.durationMs,
+    details: result.code === 0
+      ? 'ok'
+      : (result.stderr || result.stdout || 'command failed').trim().slice(0, 400)
+  };
+}
+
+async function runNpmScriptGate(scripts, scriptName, repoRoot) {
+  if (!scripts[scriptName]) {
+    return {
+      name: scriptName,
+      command: `npm run ${scriptName}`,
+      status: 'skipped',
+      durationMs: 0,
+      details: `Script ${scriptName} is not defined`
+    };
+  }
+
+  const result = await runGate(`npm run ${scriptName}`, repoRoot);
+  return {
+    name: scriptName,
+    command: `npm run ${scriptName}`,
+    ...result
+  };
+}
+
+async function runReviewGate({ repoRoot, strict, skipReview }) {
+  if (!strict) {
+    return {
+      status: 'skipped',
+      details: 'Strict mode disabled'
+    };
+  }
+
+  if (skipReview) {
+    return {
+      status: 'skipped',
+      details: 'Skipped by --skip-review'
+    };
+  }
+
+  const hasCodex = await runCommand('command -v codex', { cwd: repoRoot });
+  if (hasCodex.code !== 0) {
+    return {
+      status: 'fail',
+      details: 'codex binary not found; rerun with --skip-review if intentional'
+    };
+  }
+
+  const review = await runCommand('codex review --base main', {
+    cwd: repoRoot,
+    timeoutMs: 30 * 60 * 1000
+  });
+
+  if (review.code !== 0) {
+    return {
+      status: 'fail',
+      details: (review.stderr || review.stdout || 'codex review failed').trim().slice(0, 400)
+    };
+  }
+
+  return {
+    status: 'pass',
+    details: 'codex review passed'
+  };
+}
+
+function collectBlockingFindings(manifest, quickGates, strictGates, reviewGate) {
+  const findings = [];
+
+  for (const task of manifest.tasks) {
+    if (task.status === 'failed') {
+      findings.push(`${task.id}: ${task.lastError || 'task failed'}`);
+    }
+  }
+
+  for (const gate of [...quickGates, ...strictGates]) {
+    if (gate.status === 'fail') {
+      findings.push(`${gate.name}: ${gate.details}`);
+    }
+  }
+
+  if (reviewGate.status === 'fail') {
+    findings.push(`review: ${reviewGate.details}`);
+  }
+
+  return findings;
+}
+
+async function runVerify({ repoRoot, changeId, strict = false, skipReview = false }) {
+  const manifestPath = getTaskManifestPath(repoRoot, changeId);
+  const manifest = parseManifest(await readJson(manifestPath));
+  const scripts = await getPackageScripts(repoRoot);
+
+  const quickGateNames = ['lint', 'typecheck', 'test'];
+  const quickGates = [];
+
+  for (const name of quickGateNames) {
+    quickGates.push(await runNpmScriptGate(scripts, name, repoRoot));
+  }
+
+  const strictGates = [];
+  if (strict) {
+    strictGates.push(await runNpmScriptGate(scripts, 'test:integration', repoRoot));
+
+    const audit = await runGate('npm audit --audit-level=high', repoRoot, 20 * 60 * 1000);
+    strictGates.push({
+      name: 'audit',
+      command: 'npm audit --audit-level=high',
+      ...audit
+    });
+  }
+
+  const review = await runReviewGate({ repoRoot, strict, skipReview });
+  const blockingFindings = collectBlockingFindings(manifest, quickGates, strictGates, review);
+  const hasFailures = blockingFindings.length > 0;
+
+  const report = parseReportCard({
+    changeId,
+    overall: hasFailures ? 'fail' : 'pass',
+    quickGates,
+    strictGates,
+    review,
+    blockingFindings,
+    timestamp: nowIso()
+  });
+
+  const outputPath = getReportCardPath(repoRoot, changeId);
+  await writeJson(outputPath, report);
+
+  return {
+    changeId,
+    outputPath,
+    overall: report.overall,
+    blockingFindings: report.blockingFindings
+  };
+}
+
+module.exports = {
+  runVerify
+};

package/lib/harness/planner.js

@@ -0,0 +1,141 @@
+/**
+ * [INPUT]: 依赖 store 读取 TASKS.md 与输出路径，依赖 schemas 校验 manifest。
+ * [OUTPUT]: 对外提供 TASKS.md → task-manifest.json 的解析与生成能力。
+ * [POS]: harness 计划编排层，被 operations/plan 直接调用。
+ * [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+ */
+
+const {
+  nowIso,
+  readText,
+  readJson,
+  writeJson,
+  exists,
+  getTaskManifestPath,
+  getTasksMarkdownPath
+} = require('./store');
+const { parseManifest } = require('./schemas');
+
+const TASK_LINE = /^- \[( |x|X)\]\s+(T\d{3})\s*(.*)$/;
+const TRAILING_PATHS = /\(([^)]+)\)\s*$/;
+const DEPENDS_TAG = /dependsOn:([A-Za-z0-9_,-]+)/i;
+
+function normalizeTitle(rawTitle) {
+  return rawTitle
+    .replace(/\[P\]/g, '')
+    .replace(DEPENDS_TAG, '')
+    .trim();
+}
+
+function parseTouches(rawTail) {
+  const match = rawTail.match(TRAILING_PATHS);
+  if (!match) {
+    return [];
+  }
+
+  return match[1]
+    .split(',')
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+function parseDependsOn(rawTail, fallbackDependsOn, isParallel) {
+  const explicit = rawTail.match(DEPENDS_TAG);
+  if (explicit) {
+    return explicit[1]
+      .split(',')
+      .map((item) => item.trim())
+      .filter(Boolean);
+  }
+
+  if (isParallel || !fallbackDependsOn) {
+    return [];
+  }
+
+  return [fallbackDependsOn];
+}
+
+function parseTasksMarkdown(content) {
+  const lines = content.split(/\r?\n/);
+  const tasks = [];
+  let previousTaskId = null;
+
+  for (const line of lines) {
+    const match = line.match(TASK_LINE);
+    if (!match) {
+      continue;
+    }
+
+    const [, doneMark, taskId, tail] = match;
+    const isParallel = /\[P\]/.test(tail);
+    const touches = parseTouches(tail);
+    const dependsOn = parseDependsOn(tail, previousTaskId, isParallel);
+    const title = normalizeTitle(tail).replace(TRAILING_PATHS, '').trim() || `Task ${taskId}`;
+
+    tasks.push({
+      id: taskId,
+      title,
+      dependsOn,
+      touches,
+      run: [`echo "[TASK ${taskId}] ${title}"`],
+      checks: [],
+      status: doneMark.toLowerCase() === 'x' ? 'passed' : 'pending',
+      attempts: 0,
+      maxRetries: 1
+    });
+
+    previousTaskId = taskId;
+  }
+
+  return tasks;
+}
+
+function buildDefaultTasks(changeId) {
+  return [
+    {
+      id: 'T001',
+      title: `Bootstrap ${changeId}`,
+      dependsOn: [],
+      touches: [],
+      run: [`echo "[TASK T001] Bootstrap ${changeId}"`],
+      checks: [],
+      status: 'pending',
+      attempts: 0,
+      maxRetries: 1
+    }
+  ];
+}
+
+async function createTaskManifest({ repoRoot, changeId, goal, overwrite = false }) {
+  const manifestPath = getTaskManifestPath(repoRoot, changeId);
+
+  if (!overwrite && (await exists(manifestPath))) {
+    const existing = await readJson(manifestPath);
+    return parseManifest(existing);
+  }
+
+  const tasksPath = getTasksMarkdownPath(repoRoot, changeId);
+  const hasTasksFile = await exists(tasksPath);
+  const rawTasks = hasTasksFile ? parseTasksMarkdown(await readText(tasksPath)) : [];
+  const tasks = rawTasks.length > 0 ? rawTasks : buildDefaultTasks(changeId);
+
+  const manifest = parseManifest({
+    changeId,
+    goal: goal || `Deliver ${changeId} safely with auditable checkpoints.`,
+    createdAt: nowIso(),
+    updatedAt: nowIso(),
+    tasks,
+    metadata: {
+      source: hasTasksFile ? 'TASKS.md' : 'default',
+      generatedBy: 'harness:plan'
+    }
+  });
+
+  await writeJson(manifestPath, manifest);
+  return manifest;
+}
+
+module.exports = {
+  parseTasksMarkdown,
+  createTaskManifest
+};

package/lib/harness/schemas.js

@@ -0,0 +1,108 @@
+/**
+ * [INPUT]: 依赖 zod 进行运行时 schema 校验，依赖调用方提供 manifest/report/checkpoint 原始对象。
+ * [OUTPUT]: 对外提供 Manifest/Task/ReportCard/Checkpoint schema 与 parse 校验函数。
+ * [POS]: harness 内核的类型边界层，被 planner/dispatcher/verifier/release 复用。
+ * [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+ */
+
+const { z } = require('zod');
+
+const CHANGE_ID_PATTERN = /^(REQ|BUG)-\d+$/;
+const TASK_ID_PATTERN = /^[A-Z][A-Z0-9_-]{1,31}$/;
+
+const ChangeIdSchema = z.string().regex(CHANGE_ID_PATTERN, 'Invalid changeId format');
+
+const TaskStatusSchema = z.enum(['pending', 'running', 'passed', 'failed', 'skipped']);
+
+const TaskSchema = z.object({
+  id: z.string().regex(TASK_ID_PATTERN, 'Invalid task id'),
+  title: z.string().min(1, 'Task title is required'),
+  dependsOn: z.array(z.string().regex(TASK_ID_PATTERN)).default([]),
+  touches: z.array(z.string().min(1)).default([]),
+  run: z.array(z.string().min(1)).min(1, 'At least one run command is required'),
+  checks: z.array(z.string().min(1)).default([]),
+  status: TaskStatusSchema.default('pending'),
+  attempts: z.number().int().min(0).default(0),
+  maxRetries: z.number().int().min(0).default(1),
+  lastError: z.string().optional()
+});
+
+const ManifestSchema = z.object({
+  changeId: ChangeIdSchema,
+  goal: z.string().min(1).default('Deliver planned requirement changes safely.'),
+  createdAt: z.string().datetime(),
+  updatedAt: z.string().datetime(),
+  tasks: z.array(TaskSchema),
+  metadata: z.object({
+    source: z.enum(['TASKS.md', 'default']).default('default'),
+    generatedBy: z.string().min(1).default('harness:plan')
+  }).default({ source: 'default', generatedBy: 'harness:plan' })
+});
+
+const CheckpointSchema = z.object({
+  changeId: ChangeIdSchema,
+  taskId: z.string().regex(TASK_ID_PATTERN),
+  sessionId: z.string().min(1),
+  status: TaskStatusSchema,
+  summary: z.string().min(1),
+  timestamp: z.string().datetime(),
+  attempt: z.number().int().min(0).default(0)
+});
+
+const GateResultSchema = z.object({
+  name: z.string().min(1),
+  status: z.enum(['pass', 'fail', 'skipped']),
+  command: z.string().min(1),
+  durationMs: z.number().int().min(0),
+  details: z.string().default('')
+});
+
+const ReportCardSchema = z.object({
+  changeId: ChangeIdSchema,
+  overall: z.enum(['pass', 'fail']),
+  quickGates: z.array(GateResultSchema),
+  strictGates: z.array(GateResultSchema),
+  review: z.object({
+    status: z.enum(['pass', 'fail', 'skipped']),
+    details: z.string().default('')
+  }),
+  blockingFindings: z.array(z.string()),
+  timestamp: z.string().datetime()
+});
+
+function parseWithSchema(schema, input, label) {
+  const parsed = schema.safeParse(input);
+  if (parsed.success) {
+    return parsed.data;
+  }
+
+  const issues = parsed.error.issues
+    .map((issue) => `${issue.path.join('.') || '<root>'}: ${issue.message}`)
+    .join('; ');
+  throw new Error(`${label} validation failed: ${issues}`);
+}
+
+function parseManifest(input) {
+  return parseWithSchema(ManifestSchema, input, 'Manifest');
+}
+
+function parseCheckpoint(input) {
+  return parseWithSchema(CheckpointSchema, input, 'Checkpoint');
+}
+
+function parseReportCard(input) {
+  return parseWithSchema(ReportCardSchema, input, 'ReportCard');
+}
+
+module.exports = {
+  ChangeIdSchema,
+  TaskSchema,
+  TaskStatusSchema,
+  ManifestSchema,
+  CheckpointSchema,
+  GateResultSchema,
+  ReportCardSchema,
+  parseManifest,
+  parseCheckpoint,
+  parseReportCard
+};

package/lib/harness/store.js

@@ -0,0 +1,240 @@
+/**
+ * [INPUT]: 依赖 fs/path/child_process，依赖调用方提供 changeId 与命令参数。
+ * [OUTPUT]: 对外提供 harness 路径约定、JSON/文本读写、JSONL 追加、命令执行工具。
+ * [POS]: harness 内核的数据与 IO 基础设施层，被全部 operations 复用。
+ * [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+ */
+
+const fs = require('fs');
+const fsp = fs.promises;
+const path = require('path');
+const { spawn } = require('child_process');
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function resolveRepoRoot(startDir = process.cwd()) {
+  let current = path.resolve(startDir);
+
+  while (true) {
+    const hasPackage = fs.existsSync(path.join(current, 'package.json'));
+    const hasGit = fs.existsSync(path.join(current, '.git'));
+    const hasDevflow = fs.existsSync(path.join(current, 'devflow'));
+
+    if (hasPackage && (hasGit || hasDevflow)) {
+      return current;
+    }
+
+    const parent = path.dirname(current);
+    if (parent === current) {
+      return path.resolve(startDir);
+    }
+    current = parent;
+  }
+}
+
+function getRequirementDir(repoRoot, changeId) {
+  return path.join(repoRoot, 'devflow', 'requirements', changeId);
+}
+
+function getContextPackagePath(repoRoot, changeId) {
+  return path.join(getRequirementDir(repoRoot, changeId), 'context-package.md');
+}
+
+function getTaskManifestPath(repoRoot, changeId) {
+  return path.join(getRequirementDir(repoRoot, changeId), 'task-manifest.json');
+}
+
+function getReportCardPath(repoRoot, changeId) {
+  return path.join(getRequirementDir(repoRoot, changeId), 'report-card.json');
+}
+
+function getReleaseNotePath(repoRoot, changeId) {
+  return path.join(getRequirementDir(repoRoot, changeId), 'RELEASE_NOTE.md');
+}
+
+function getHarnessStatePath(repoRoot, changeId) {
+  return path.join(getRequirementDir(repoRoot, changeId), 'harness-state.json');
+}
+
+function getTasksMarkdownPath(repoRoot, changeId) {
+  return path.join(getRequirementDir(repoRoot, changeId), 'TASKS.md');
+}
+
+function getRuntimeRoot(repoRoot) {
+  return path.join(repoRoot, '.harness', 'runtime');
+}
+
+function getRuntimeChangeDir(repoRoot, changeId) {
+  return path.join(getRuntimeRoot(repoRoot), changeId);
+}
+
+function getRuntimeTaskDir(repoRoot, changeId, taskId) {
+  return path.join(getRuntimeChangeDir(repoRoot, changeId), taskId);
+}
+
+function getEventsPath(repoRoot, changeId, taskId) {
+  return path.join(getRuntimeTaskDir(repoRoot, changeId, taskId), 'events.jsonl');
+}
+
+function getCheckpointPath(repoRoot, changeId, taskId) {
+  return path.join(getRuntimeTaskDir(repoRoot, changeId, taskId), 'checkpoint.json');
+}
+
+async function exists(filePath) {
+  try {
+    await fsp.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function ensureDir(dirPath) {
+  await fsp.mkdir(dirPath, { recursive: true });
+}
+
+async function readText(filePath, fallback = '') {
+  if (!(await exists(filePath))) {
+    return fallback;
+  }
+  return fsp.readFile(filePath, 'utf8');
+}
+
+async function writeText(filePath, content) {
+  await ensureDir(path.dirname(filePath));
+  await fsp.writeFile(filePath, content, 'utf8');
+}
+
+async function readJson(filePath, fallback = null) {
+  if (!(await exists(filePath))) {
+    return fallback;
+  }
+  const content = await readText(filePath);
+  return JSON.parse(content);
+}
+
+async function writeJson(filePath, value) {
+  await ensureDir(path.dirname(filePath));
+  await fsp.writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+
+async function appendJsonl(filePath, value) {
+  await ensureDir(path.dirname(filePath));
+  await fsp.appendFile(filePath, `${JSON.stringify(value)}\n`, 'utf8');
+}
+
+async function listDirectories(dirPath) {
+  if (!(await exists(dirPath))) {
+    return [];
+  }
+
+  const entries = await fsp.readdir(dirPath, { withFileTypes: true });
+  return entries
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => path.join(dirPath, entry.name));
+}
+
+async function runCommand(command, options = {}) {
+  const {
+    cwd = process.cwd(),
+    env = {},
+    timeoutMs = 0,
+    stream = false
+  } = options;
+
+  const startedAt = Date.now();
+
+  return new Promise((resolve) => {
+    const child = spawn(command, {
+      cwd,
+      env: { ...process.env, ...env },
+      shell: true,
+      stdio: stream ? 'inherit' : 'pipe'
+    });
+
+    let stdout = '';
+    let stderr = '';
+    let killedByTimeout = false;
+    let timeoutId = null;
+
+    if (!stream) {
+      child.stdout.on('data', (chunk) => {
+        stdout += String(chunk);
+      });
+
+      child.stderr.on('data', (chunk) => {
+        stderr += String(chunk);
+      });
+    }
+
+    if (timeoutMs > 0) {
+      timeoutId = setTimeout(() => {
+        killedByTimeout = true;
+        child.kill('SIGTERM');
+      }, timeoutMs);
+    }
+
+    child.on('close', (code) => {
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+      }
+
+      resolve({
+        code: typeof code === 'number' ? code : 1,
+        stdout,
+        stderr,
+        durationMs: Date.now() - startedAt,
+        killedByTimeout
+      });
+    });
+
+    child.on('error', (error) => {
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+      }
+
+      resolve({
+        code: 1,
+        stdout,
+        stderr: `${stderr}\n${error.message}`.trim(),
+        durationMs: Date.now() - startedAt,
+        killedByTimeout
+      });
+    });
+  });
+}
+
+async function getPackageScripts(repoRoot) {
+  const pkgPath = path.join(repoRoot, 'package.json');
+  const pkg = await readJson(pkgPath, {});
+  return pkg && pkg.scripts ? pkg.scripts : {};
+}
+
+module.exports = {
+  nowIso,
+  resolveRepoRoot,
+  getRequirementDir,
+  getContextPackagePath,
+  getTaskManifestPath,
+  getReportCardPath,
+  getReleaseNotePath,
+  getHarnessStatePath,
+  getTasksMarkdownPath,
+  getRuntimeRoot,
+  getRuntimeChangeDir,
+  getRuntimeTaskDir,
+  getEventsPath,
+  getCheckpointPath,
+  exists,
+  ensureDir,
+  readText,
+  writeText,
+  readJson,
+  writeJson,
+  appendJsonl,
+  listDirectories,
+  runCommand,
+  getPackageScripts
+};

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "cc-devflow",
-    "version": "4.1.5",
+    "version": "4.2.0",
     "description": "DevFlow CLI tool",
     "main": "bin/cc-devflow.js",
     "bin": {
@@ -26,6 +26,14 @@
         "prepublishOnly": "node scripts/validate-publish.js",
         "test": "jest",
         "start": "node bin/cc-devflow.js",
+        "harness:init": "node bin/harness.js init",
+        "harness:pack": "node bin/harness.js pack",
+        "harness:plan": "node bin/harness.js plan",
+        "harness:dispatch": "node bin/harness.js dispatch",
+        "harness:verify": "node bin/harness.js verify",
+        "harness:release": "node bin/harness.js release",
+        "harness:resume": "node bin/harness.js resume",
+        "harness:janitor": "node bin/harness.js janitor",
         "adapt": "node bin/adapt.js",
         "adapt:check": "node bin/adapt.js --check",
         "adapt:skills": "node bin/adapt.js --skills",