ccgx-workflow 2.4.1 → 2.5.0

package/templates/scripts/ccg-state-lock.cjs

@@ -0,0 +1,510 @@
+#!/usr/bin/env node
+// CCG State Lock CLI — P1-6 (O_EXCL 文件锁 + SUMMARY 合并 + 通用锁定写).
+//
+// Standalone Node CJS reimplementation of src/utils/state-lock.ts +
+// phase-context.ts mergeSummary. The TS versions ship in ccgx-workflow's
+// dist for package consumers; but /ccg:team-exec Builders run in the USER's
+// project, which has no ccgx-workflow npm dependency.
+//
+// installer.ts copies this file to ~/.claude/.ccg/scripts/ccg-state-lock.cjs.
+// Command templates call:
+//
+//   node ~/.claude/.ccg/scripts/ccg-state-lock.cjs merge-summary \
+//     --workdir <wd> --phase <p> --patch-file <json> [--max-wait-ms N]
+//   node ~/.claude/.ccg/scripts/ccg-state-lock.cjs locked-write \
+//     --target <path> --content-file <file> [--max-wait-ms N]
+//
+// merge-summary: patch JSON = {taskId, plan, provides, affects, keyFiles,
+// tests, completed, notes} (camelCase; --patch-file rather than inline args
+// avoids Windows shell quoting issues). The whole lock→read→merge→atomic
+// write→release cycle happens INSIDE this single short-lived process — that
+// millisecond-scale hold time is the precondition for the 10s lock staleness
+// threshold. NEVER split acquire/release across separate CLI invocations.
+// stdout: merged summary as JSON. Exit 0 = success; 1 = bad args / IO /
+// lock timeout.
+//
+// locked-write: generic lock + tmp+rename atomic write for single-writer
+// files the Lead rewrites each wave (e.g. <WORKDIR>/.ccg/state.md).
+// stdout: {"ok":true,"target":...}. Same exit-code contract.
+//
+// Logic must stay in lockstep with src/utils/state-lock.ts and
+// src/utils/phase-context.ts (mergeSummaryFields / budget truncation).
+// __tests__/stateLockCjs.test.ts pins both against shared fixtures.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+// ─────────────────────────────────────────────────────────────────
+// Lock constants (must mirror state-lock.ts)
+// ─────────────────────────────────────────────────────────────────
+
+const RETRY_DELAY_MS = 200;
+const STALE_THRESHOLD_MS = 10000;
+const MAX_WAIT_MS = 30000;
+const SUMMARY_TOKEN_BUDGET = 200;
+
+const LOCK_RETRY_ERRNOS = new Set([
+  'EPERM', 'EBUSY', 'EAGAIN', 'EINTR', 'EINVAL', 'EIO', 'ENOENT', 'ESTALE',
+]);
+
+// ─────────────────────────────────────────────────────────────────
+// O_EXCL lock (mirrors state-lock.ts acquireLock / releaseLock / withLock)
+// ─────────────────────────────────────────────────────────────────
+
+const heldLocks = new Set();
+let exitHookInstalled = false;
+
+function installExitHook() {
+  if (exitHookInstalled) return;
+  exitHookInstalled = true;
+  process.on('exit', () => {
+    for (const lockPath of heldLocks) {
+      try { fs.unlinkSync(lockPath); } catch { /* already gone */ }
+    }
+    heldLocks.clear();
+  });
+}
+
+function lockPathFor(target) {
+  return `${target}.lock`;
+}
+
+function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+function acquireLock(target, opts) {
+  const options = opts || {};
+  const retryDelayMs = options.retryDelayMs != null ? options.retryDelayMs : RETRY_DELAY_MS;
+  const staleThresholdMs = options.staleThresholdMs != null ? options.staleThresholdMs : STALE_THRESHOLD_MS;
+  const maxWaitMs = options.maxWaitMs != null ? options.maxWaitMs : MAX_WAIT_MS;
+  const lockPath = lockPathFor(target);
+  const startedAt = Date.now();
+
+  while (true) {
+    try {
+      const fd = fs.openSync(lockPath, fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY);
+      fs.writeSync(fd, String(process.pid));
+      fs.closeSync(fd);
+      heldLocks.add(lockPath);
+      installExitHook();
+      return lockPath;
+    } catch (err) {
+      const code = err.code || '';
+      if (code === 'EEXIST') {
+        // Steal only a stale lock (crashed holder); a fresh lock is live.
+        // TOCTOU-safe steal: two waiters can both pass the staleness check,
+        // so the loser must never unlink (it would nuke the winner's fresh
+        // lock). renameSync is atomic — exactly one waiter wins the steal.
+        let stale = false;
+        try {
+          const stat = fs.statSync(lockPath);
+          stale = Date.now() - stat.mtimeMs > staleThresholdMs;
+        } catch {
+          continue; // released between EEXIST and stat
+        }
+        if (stale) {
+          const tombstone = `${lockPath}.steal-${process.pid}-${Date.now()}`;
+          try {
+            fs.renameSync(lockPath, tombstone);
+            // Steal won — clean the tombstone (best effort) and race for
+            // the lock via the normal O_EXCL create.
+            try { fs.unlinkSync(tombstone); } catch { /* tombstone cleanup is best-effort */ }
+            continue;
+          } catch {
+            // Another waiter renamed first (ENOENT et al.) — fall through
+            // to the wait loop and contend for the new lock normally.
+          }
+        }
+      } else if (!LOCK_RETRY_ERRNOS.has(code)) {
+        throw err; // fatal errno — silent bypass causes lost updates
+      }
+      const waited = Date.now() - startedAt;
+      if (waited >= maxWaitMs) {
+        throw new Error(
+          `state-lock: ${lockPath} not acquired after waiting ${waited}ms ` +
+          `(budget ${maxWaitMs}ms, last errno ${code || 'EEXIST'})`
+        );
+      }
+      sleepSync(retryDelayMs + Math.floor(Math.random() * 50));
+    }
+  }
+}
+
+function releaseLock(lockPath) {
+  heldLocks.delete(lockPath);
+  try { fs.unlinkSync(lockPath); } catch { /* lock already gone */ }
+}
+
+function withLock(target, fn, opts) {
+  const lockPath = acquireLock(target, opts);
+  try {
+    return fn();
+  } finally {
+    releaseLock(lockPath);
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────
+// Atomic write (mirrors jobs.ts atomicWriteFileSync)
+// ─────────────────────────────────────────────────────────────────
+
+function atomicWriteFileSync(target, content) {
+  const rand = crypto.randomBytes(6).toString('hex');
+  const tmp = `${target}.tmp.${rand}`;
+  try {
+    fs.writeFileSync(tmp, content, 'utf-8');
+    fs.renameSync(tmp, target);
+  } catch (err) {
+    try { fs.unlinkSync(tmp); } catch { /* nothing to clean up */ }
+    throw err;
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────
+// SUMMARY.md frontmatter helpers (mirror phase-context.ts)
+// ─────────────────────────────────────────────────────────────────
+
+function sanitizePhase(phase) {
+  return String(phase).trim().replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '');
+}
+
+function summaryFilePath(workdir, phase) {
+  return path.join(workdir, '.context', sanitizePhase(phase), 'SUMMARY.md');
+}
+
+function extractFrontmatter(content) {
+  const m = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  return m ? m[1] : null;
+}
+
+function unquote(s) {
+  if ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'"))) {
+    return s.slice(1, -1);
+  }
+  return s;
+}
+
+function parseFrontmatterFields(yaml) {
+  const out = {};
+  const lines = yaml.split(/\r?\n/);
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    if (!line.trim() || line.trim().startsWith('#')) { i += 1; continue; }
+    const match = line.match(/^([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*(.*)$/);
+    if (!match) throw new Error(`phase-context: malformed frontmatter line: ${line}`);
+    const key = match[1];
+    const rest = match[2].trim();
+    if (rest === '') {
+      const items = [];
+      i += 1;
+      while (i < lines.length && /^\s+-\s+/.test(lines[i])) {
+        items.push(unquote(lines[i].replace(/^\s+-\s+/, '').trim()));
+        i += 1;
+      }
+      out[key] = items;
+      continue;
+    }
+    if (rest.startsWith('[') && rest.endsWith(']')) {
+      const inner = rest.slice(1, -1).trim();
+      out[key] = inner ? inner.split(',').map((s) => unquote(s.trim())) : [];
+    } else if (rest === 'true' || rest === 'false') {
+      out[key] = rest === 'true';
+    } else {
+      out[key] = unquote(rest);
+    }
+    i += 1;
+  }
+  return out;
+}
+
+function serializeScalar(value) {
+  if (/[:#\[\],&*!|>'"%@`]/.test(value) || value === '' || /^\s|\s$/.test(value)) {
+    return `"${value.replace(/"/g, '\\"')}"`;
+  }
+  return value;
+}
+
+function serializeList(values) {
+  if (values.length === 0) return '[]';
+  return `[${values.map(serializeScalar).join(', ')}]`;
+}
+
+function toList(value) {
+  if (Array.isArray(value)) return value.map(String);
+  if (typeof value === 'string' && value) return [value];
+  return [];
+}
+
+function readSummaryFile(workdir, phase) {
+  const target = summaryFilePath(workdir, phase);
+  if (!fs.existsSync(target)) return null;
+  const fm = extractFrontmatter(fs.readFileSync(target, 'utf-8'));
+  if (!fm) return null;
+  const fields = parseFrontmatterFields(fm);
+  return {
+    phase: String(fields.phase != null ? fields.phase : phase),
+    plan: String(fields.plan != null ? fields.plan : ''),
+    provides: toList(fields.provides),
+    affects: toList(fields.affects),
+    keyFiles: toList(fields.key_files),
+    tests: toList(fields.tests),
+    completed: fields.completed === true,
+    completedAt: fields.completed_at ? String(fields.completed_at) : undefined,
+    notes: fields.notes ? String(fields.notes) : undefined,
+  };
+}
+
+function summaryFrontmatterText(summary) {
+  const lines = [
+    `phase: ${serializeScalar(summary.phase)}`,
+    `plan: ${serializeScalar(summary.plan)}`,
+    `provides: ${serializeList(summary.provides)}`,
+    `affects: ${serializeList(summary.affects)}`,
+    `key_files: ${serializeList(summary.keyFiles)}`,
+  ];
+  if (summary.tests && summary.tests.length) lines.push(`tests: ${serializeList(summary.tests)}`);
+  lines.push(`completed: ${summary.completed ? 'true' : 'false'}`);
+  if (summary.completedAt) lines.push(`completed_at: ${serializeScalar(summary.completedAt)}`);
+  if (summary.notes) lines.push(`notes: ${serializeScalar(summary.notes)}`);
+  return lines.join('\n');
+}
+
+function renderSummaryDocument(summary) {
+  const frontmatter = ['---', summaryFrontmatterText(summary), '---', ''].join('\n');
+  const body = [
+    `# Phase Summary: ${summary.phase}`,
+    '',
+    `**Plan**: ${summary.plan}  `,
+    `**Status**: ${summary.completed ? 'completed' : 'in-progress'}`,
+    summary.completedAt ? `**Completed**: ${summary.completedAt}` : '',
+    '',
+    '## Provides',
+    ...(summary.provides.length ? summary.provides.map((p) => `- ${p}`) : ['_(none)_']),
+    '',
+    '## Affects',
+    ...(summary.affects.length ? summary.affects.map((a) => `- ${a}`) : ['_(none)_']),
+    '',
+    '## Key files',
+    ...(summary.keyFiles.length ? summary.keyFiles.map((f) => `- \`${f}\``) : ['_(none)_']),
+    '',
+    summary.notes ? `## Notes\n\n${summary.notes}\n` : '',
+  ].filter(Boolean).join('\n');
+  return frontmatter + body;
+}
+
+function summaryTokenEstimate(frontmatter) {
+  return Math.ceil(frontmatter.length / 3.5);
+}
+
+// ─────────────────────────────────────────────────────────────────
+// Merge core (mirrors phase-context.ts mergeSummaryFields + budget)
+// ─────────────────────────────────────────────────────────────────
+
+function unionPreserveOrder(a, b) {
+  return [...new Set([...a, ...b])];
+}
+
+function mergeSummaryContent(existing, phase, plan, patch, nowIso) {
+  const base = existing || {
+    phase,
+    plan,
+    provides: [],
+    affects: [],
+    keyFiles: [],
+    tests: [],
+    completed: false,
+  };
+  const noteSegment = patch.notes
+    ? `[${patch.taskId}] ${String(patch.notes).replace(/\r?\n+/g, ' ').trim()}`
+    : undefined;
+  const mergedNotes = [base.notes, noteSegment].filter(Boolean).join(' | ') || undefined;
+  const completed = patch.completed != null ? patch.completed : base.completed;
+  return {
+    phase: base.phase || phase,
+    plan: base.plan || plan,
+    provides: unionPreserveOrder(base.provides, patch.provides || []),
+    affects: unionPreserveOrder(base.affects, patch.affects || []),
+    keyFiles: unionPreserveOrder(base.keyFiles, patch.keyFiles || []),
+    tests: unionPreserveOrder(base.tests || [], patch.tests || []),
+    completed,
+    completedAt: completed ? (nowIso || new Date().toISOString()) : base.completedAt,
+    notes: mergedNotes,
+  };
+}
+
+function enforceSummaryBudget(summary, budget) {
+  const cap = budget != null ? budget : SUMMARY_TOKEN_BUDGET;
+  let current = summary;
+  let guard = 0;
+  while (
+    current.notes &&
+    summaryTokenEstimate(summaryFrontmatterText(current)) > cap &&
+    guard < 50
+  ) {
+    const excess = summaryTokenEstimate(summaryFrontmatterText(current)) - cap;
+    const cutChars = Math.ceil(excess * 3.5) + 1;
+    const trimmed = current.notes.slice(0, Math.max(0, current.notes.length - cutChars));
+    current = { ...current, notes: trimmed ? `${trimmed}…` : undefined };
+    guard += 1;
+  }
+  return current;
+}
+
+// ─────────────────────────────────────────────────────────────────
+// CLI
+// ─────────────────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const out = { command: null, flags: {}, help: false, bad: false };
+  const args = argv.slice(2);
+  if (args[0] && !args[0].startsWith('-')) {
+    out.command = args.shift();
+  }
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--help' || arg === '-h') {
+      out.help = true;
+    } else if (arg === '--workdir' || arg === '--phase' || arg === '--patch-file'
+      || arg === '--target' || arg === '--content-file' || arg === '--max-wait-ms') {
+      out.flags[arg.slice(2)] = args[++i];
+    } else {
+      process.stderr.write(`ccg-state-lock: unknown flag ${arg}\n`);
+      out.bad = true;
+    }
+  }
+  return out;
+}
+
+function usage() {
+  return [
+    'Usage:',
+    '  node ccg-state-lock.cjs merge-summary --workdir <wd> --phase <p> --patch-file <json> [--max-wait-ms N]',
+    '  node ccg-state-lock.cjs locked-write  --target <path> --content-file <file> [--max-wait-ms N]',
+    '',
+    'merge-summary patch JSON: {taskId, plan, provides, affects, keyFiles, tests, completed, notes}',
+    'Exit 0 = success; 1 = bad args / IO error / lock timeout.',
+  ].join('\n');
+}
+
+function lockOptsFromFlags(flags) {
+  const opts = {};
+  if (flags['max-wait-ms'] != null) {
+    const n = Number(flags['max-wait-ms']);
+    if (!Number.isFinite(n) || n < 0) throw new Error(`invalid --max-wait-ms: ${flags['max-wait-ms']}`);
+    opts.maxWaitMs = n;
+    // Keep retries responsive when the caller shrinks the budget (tests).
+    opts.retryDelayMs = Math.min(RETRY_DELAY_MS, Math.max(10, Math.floor(n / 4)));
+  }
+  return opts;
+}
+
+function cmdMergeSummary(flags) {
+  const workdir = flags.workdir;
+  const phase = flags.phase;
+  const patchFile = flags['patch-file'];
+  if (!workdir || !phase || !patchFile) {
+    process.stderr.write('ccg-state-lock: merge-summary requires --workdir, --phase, --patch-file\n');
+    return 1;
+  }
+  let patch;
+  try {
+    patch = JSON.parse(fs.readFileSync(patchFile, 'utf-8'));
+  } catch (err) {
+    process.stderr.write(`ccg-state-lock: cannot read patch file: ${err.message}\n`);
+    return 1;
+  }
+  if (!patch || typeof patch !== 'object' || typeof patch.taskId !== 'string' || !patch.taskId.trim()) {
+    process.stderr.write('ccg-state-lock: patch JSON must be an object with a non-empty "taskId"\n');
+    return 1;
+  }
+  try {
+    const opts = lockOptsFromFlags(flags);
+    const target = summaryFilePath(workdir, phase);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    const merged = withLock(target, () => {
+      const existing = readSummaryFile(workdir, phase);
+      // Frontmatter keeps the RAW phase (TS mergeSummary parity); sanitize is
+      // path-only (summaryFilePath above).
+      const result = enforceSummaryBudget(
+        mergeSummaryContent(existing, phase, String(patch.plan || ''), patch)
+      );
+      atomicWriteFileSync(target, renderSummaryDocument(result));
+      return result;
+    }, opts);
+    process.stdout.write(JSON.stringify(merged) + '\n');
+    return 0;
+  } catch (err) {
+    process.stderr.write(`ccg-state-lock: ${err.message}\n`);
+    return 1;
+  }
+}
+
+function cmdLockedWrite(flags) {
+  const target = flags.target;
+  const contentFile = flags['content-file'];
+  if (!target || !contentFile) {
+    process.stderr.write('ccg-state-lock: locked-write requires --target, --content-file\n');
+    return 1;
+  }
+  let content;
+  try {
+    content = fs.readFileSync(contentFile, 'utf-8');
+  } catch (err) {
+    process.stderr.write(`ccg-state-lock: cannot read content file: ${err.message}\n`);
+    return 1;
+  }
+  try {
+    const opts = lockOptsFromFlags(flags);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    withLock(target, () => {
+      atomicWriteFileSync(target, content);
+    }, opts);
+    process.stdout.write(JSON.stringify({ ok: true, target }) + '\n');
+    return 0;
+  } catch (err) {
+    process.stderr.write(`ccg-state-lock: ${err.message}\n`);
+    return 1;
+  }
+}
+
+function main(argv) {
+  const args = parseArgs(argv);
+  if (args.help) {
+    process.stderr.write(usage() + '\n');
+    return 0;
+  }
+  if (args.bad) {
+    process.stderr.write(usage() + '\n');
+    return 1;
+  }
+  if (args.command === 'merge-summary') return cmdMergeSummary(args.flags);
+  if (args.command === 'locked-write') return cmdLockedWrite(args.flags);
+  process.stderr.write(usage() + '\n');
+  return 1;
+}
+
+module.exports = {
+  acquireLock,
+  releaseLock,
+  withLock,
+  lockPathFor,
+  mergeSummaryContent,
+  enforceSummaryBudget,
+  summaryTokenEstimate,
+  parseArgs,
+  main,
+  RETRY_DELAY_MS,
+  STALE_THRESHOLD_MS,
+  MAX_WAIT_MS,
+  SUMMARY_TOKEN_BUDGET,
+  LOCK_RETRY_ERRNOS,
+};
+
+if (require.main === module) {
+  process.exit(main(process.argv));
+}