@michaelxwb/code-flow 0.8.1 → 1.0.0

package/lib/config.js

@@ -0,0 +1,85 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const f = require('./fs');
+const glob = require('./glob');
+
+function defaults() {
+  return { version: 1, workflow: 'hook', always: [], paths: {},
+    budget: { maxTokens: 2500, maxBytes: 16384 },
+    tests: { timeoutSeconds: 120, jobs: 2, regression: null },
+    capture: { enabled: false, path: '.code-flow/process' } };
+}
+function reference(value) {
+  f.string(value, 'Spec reference');
+  const parts = value.split('#');
+  f.demand(parts.length <= 2 && /^[a-z0-9][a-z0-9/_-]*$/.test(parts[0]) &&
+    parts[0].split('/').every(Boolean) && (!parts[1] || /^RULE-[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*$/.test(parts[1])) &&
+    (parts.length === 1 || Boolean(parts[1])), 'invalid_reference', 'Invalid Spec reference: ' + value);
+  return { id: parts[0], rule: parts[1] || null };
+}
+function validate(raw) {
+  f.object(raw, 'config');
+  f.demand(raw.version === 1, 'invalid_config', 'config.version must be 1');
+  const base = defaults();
+  const result = { ...raw, workflow: raw.workflow ?? base.workflow,
+    always: raw.always ?? [], paths: raw.paths ?? {},
+    budget: { ...base.budget, ...f.object(raw.budget ?? {}, 'budget') },
+    tests: { ...base.tests, ...f.object(raw.tests ?? {}, 'tests') },
+    capture: { ...base.capture, ...f.object(raw.capture ?? {}, 'capture') } };
+  f.demand(['hook', 'full'].includes(result.workflow), 'invalid_config',
+    'workflow must be hook or full');
+  f.demand(typeof result.capture.enabled === 'boolean', 'invalid_config',
+    'capture.enabled must be boolean');
+  f.string(result.capture.path, 'capture.path');
+  f.demand(/^\.code-flow\/[A-Za-z0-9._/-]+$/.test(result.capture.path) &&
+    !result.capture.path.split('/').includes('..') && !result.capture.path.endsWith('/'),
+    'invalid_config', 'capture.path must be a relative path under .code-flow');
+  f.strings(result.always, 'always').forEach(reference);
+  f.object(result.paths, 'paths');
+  for (const [pattern, refs] of Object.entries(result.paths)) {
+    glob.compile(pattern); f.strings(refs, 'paths references').forEach(reference);
+  }
+  f.positive(result.budget.maxTokens, 'maxTokens', true);
+  f.positive(result.budget.maxBytes, 'maxBytes', true);
+  f.positive(result.tests.timeoutSeconds, 'timeoutSeconds');
+  f.positive(result.tests.jobs, 'jobs', true);
+  if (result.tests.regression !== null) result.tests.regression = regression(result.tests.regression);
+  return result;
+}
+
+function regression(value) {
+  f.object(value, 'tests.regression');
+  f.demand((value.argv !== undefined) !== (value.run !== undefined), 'invalid_config',
+    'tests.regression requires exactly one of argv or run');
+  if (value.argv !== undefined) f.strings(value.argv, 'tests.regression argv');
+  else f.string(value.run, 'tests.regression run');
+  if (value.cwd !== undefined) f.string(value.cwd, 'tests.regression cwd');
+  if (value.timeout !== undefined) f.positive(value.timeout, 'tests.regression timeout');
+  if (value.parallel !== undefined) f.demand(typeof value.parallel === 'boolean',
+    'invalid_config', 'tests.regression parallel must be boolean');
+  if (value.group !== undefined) f.string(value.group, 'tests.regression group');
+  if (value.env !== undefined) f.object(value.env, 'tests.regression env');
+  return { ...value, id: 'regression' };
+}
+function findRoot(cwd, required = true) {
+  let current = f.realpath(cwd);
+  while (true) {
+    if (fs.existsSync(path.join(current, '.code-flow/config.json'))) return current;
+    const parent = path.dirname(current);
+    if (parent === current || fs.existsSync(path.join(current, '.git'))) break;
+    current = parent;
+  }
+  f.demand(!required, 'project_missing', 'Run inside a project with .code-flow/config.json');
+  return null;
+}
+function load(root) {
+  const raw = f.readText(f.inside(root, '.code-flow/config.json'), 65536);
+  f.demand(raw !== null, 'config_missing', 'Missing config.json');
+  let data;
+  try { data = JSON.parse(raw); } catch (error) {
+    throw new f.FlowError('config_invalid', 'Invalid config JSON: ' + error.message);
+  }
+  return validate(data);
+}
+module.exports = { defaults, reference, validate, findRoot, load };

package/lib/doctor.js

@@ -0,0 +1,283 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const f = require('./fs');
+const config = require('./config');
+const spec = require('./spec');
+const task = require('./task');
+const taskdoc = require('./taskdoc');
+const init = require('./init');
+const runs = require('./runs');
+const toml = require('./toml');
+
+const TEMPLATES = init.WORKFLOW_TEMPLATES;
+const LAUNCHER = init.LAUNCHER_TEMPLATES;
+
+function check(code, severity, status, message, target = null, nextAction = '') {
+  return { code, severity, status, path: target, message, next_action: nextAction };
+}
+
+function pass(code, message, target = null) {
+  return check(code, 'info', 'pass', message, target, '');
+}
+
+function gitRead(root, args) {
+  const result = spawnSync('git', args, { cwd: root, encoding: 'utf8',
+    env: { ...process.env, GIT_OPTIONAL_LOCKS: '0' } });
+  return result.status === 0 ? result.stdout.trim() : null;
+}
+
+function configChecks(root) {
+  try { return [{ value: config.load(root), checks: [pass('CONFIG_OK', 'config 可读取。', '.code-flow/config.json')] }]; }
+  catch (error) {
+    return [{ value: null, checks: [check('CONFIG_INVALID', 'error', 'fail', error.message,
+      '.code-flow/config.json', '修复 config.json 后重试')] }];
+  }
+}
+
+function templateChecks(root) {
+  const directory = path.join(root, '.code-flow/templates');
+  const checks = [];
+  for (const name of TEMPLATES) {
+    if (!fs.existsSync(path.join(directory, name))) {
+      checks.push(check('TEMPLATE_MISSING', 'error', 'fail', '缺少工作流模板: ' + name,
+        '.code-flow/templates/' + name, '运行 code-flow init'));
+    }
+  }
+  const taskTemplate = f.readText(path.join(directory, 'task.md'));
+  if (taskTemplate !== null && !/^## TASK-\d+:/m.test(taskTemplate)) {
+    checks.push(check('TEMPLATE_INSTRUCTION_INVALID', 'error', 'fail',
+      '任务模板缺少多 TASK 段格式。', '.code-flow/templates/task.md', '运行 code-flow init'));
+  }
+  return checks.length ? checks : [pass('TEMPLATE_OK', '工作流模板完整。', '.code-flow/templates')];
+}
+
+function fallbackFindings(root) {
+  const text = f.readText(path.join(root, '.code-flow/launcher/hook.sh'));
+  if (text === null) return [];
+  const node = /--node '([^']+)'/.exec(text)?.[1];
+  const entry = /--entry '([^']+)'/.exec(text)?.[1];
+  if (!node || !entry || (fs.existsSync(node) && fs.existsSync(entry))) return [];
+  return [check('HOOK_ENTRY_FALLBACK', 'warning', 'fail',
+    '固定回退 Node/JS 入口不存在；PATH 全局包仍可能可用。', '.code-flow/launcher/hook.sh',
+    '重新 code-flow init 或修复全局安装')];
+}
+
+function launcherChecks(root) {
+  const checks = [];
+  for (const name of LAUNCHER) {
+    if (!fs.existsSync(path.join(root, '.code-flow/launcher', name))) {
+      checks.push(check('HOOK_ENTRY_MISSING', 'error', 'fail', '项目启动器缺失: ' + name,
+        '.code-flow/launcher/' + name, '运行 code-flow init'));
+    }
+  }
+  checks.push(...fallbackFindings(root));
+  let platforms = [];
+  try { platforms = init.installed(root); } catch (error) {
+    checks.push(check('HOOK_CONFIG_INVALID', 'error', 'fail', error.message,
+      'platform configuration', '修复平台 Hook 配置'));
+  }
+  if (!platforms.length && !checks.some(item => item.code === 'HOOK_CONFIG_INVALID')) {
+    checks.push(check('HOOK_CONFIG_INVALID', 'warning', 'fail', '未发现 v1 平台 Hook。',
+      '.claude/.codex/.costrict/.opencode', '运行 code-flow init --platform=all'));
+  }
+  if (platforms.length) {
+    const target = require('./adapters').PLATFORMS[platforms[0]].hooks;
+    checks.push(check('HOST_TRUST_UNKNOWN', 'warning', 'unknown',
+      '无法从文件确定宿主是否已加载并信任此 Hook。', target,
+      '在宿主审阅 Hook，并提交一次 prompt 检查注入。'));
+  }
+  const errors = checks.filter(item => item.severity === 'error');
+  const unhealthy = checks.some(item => item.code === 'HOOK_ENTRY_MISSING' ||
+    item.code === 'HOOK_ENTRY_FALLBACK');
+  if (!errors.length && !unhealthy) {
+    checks.push(pass('HOOK_ENTRY_OK', '项目启动器与平台入口可静态读取。', '.code-flow/launcher'));
+  }
+  return checks;
+}
+
+function codexChecks(root) {
+  const relative = '.codex/config.toml';
+  const text = f.readText(path.join(root, relative));
+  if (text === null) return [];
+  const found = toml.featuresHooks(text);
+  if (found.unsupported) return [check('CODEX_CONFIG_FORM', 'error', 'fail',
+    'Codex config.toml 使用不支持的 features.hooks 形式: ' + found.unsupported,
+    relative, '改成规范 [features] 表 + hooks = true，或根级单行 features.hooks = true')];
+  if (found.header < 0 && found.key < 0) return [];
+  if (found.value !== 'true') return [check('CODEX_HOOKS_DISABLED', 'warning', 'fail',
+    'Codex config.toml 未启用 features.hooks。', relative,
+    '在 [features] 表中加入 hooks = true，或运行 code-flow init')];
+  return [pass('CODEX_CONFIG_OK', 'Codex config.toml 的 features.hooks 已启用。', relative)];
+}
+
+function specChecks(root, settings) {
+  let listing;
+  try { listing = spec.list(root); } catch (error) {
+    return { ids: new Set(), checks: [check('SPEC_INVALID', 'error', 'fail', error.message,
+      '.code-flow/specs', '修复 Spec 树')] };
+  }
+  const checks = listing.diagnostics.map(item => check('SPEC_INVALID', 'error', 'fail',
+    item.message, item.source ? '.code-flow/specs/' + item.source + '.md' : '.code-flow/specs',
+    '修复 Spec 文件'));
+  const ids = new Set(listing.items.map(item => item.id));
+  const refs = [];
+  if (settings) {
+    for (const value of settings.always) refs.push(config.reference(value));
+    for (const values of Object.values(settings.paths)) {
+      for (const value of values) refs.push(config.reference(value));
+    }
+  }
+  for (const ref of refs) {
+    if (!ids.has(ref.id)) checks.push(check('SPEC_REF_MISSING', 'error', 'fail',
+      'config 引用了不存在的 Spec: ' + ref.id, '.code-flow/config.json', '修复引用或补充 Spec'));
+  }
+  if (!checks.length) checks.push(pass('SPEC_OK', 'Spec 格式与 config 引用有效。', '.code-flow/specs'));
+  return { ids, checks };
+}
+
+function taskChecks(root, specIds) {
+  let listing;
+  try { listing = task.list(root); } catch (error) {
+    return [check('TASK_INVALID', 'error', 'fail', error.message,
+      '.code-flow/tasks', '修复任务文档')];
+  }
+  const checks = listing.diagnostics.map(item => check(
+    item.code && item.code.startsWith('task_depends') ? 'TASK_DEPENDENCY_INVALID' : 'TASK_INVALID',
+    'error', 'fail', item.message, item.source || '.code-flow/tasks', '修复任务文档'));
+  for (const item of listing.items) {
+    for (const ref of item.spec_refs) {
+      if (!specIds.has(ref.split('#')[0])) checks.push(check('SPEC_REF_MISSING', 'error', 'fail',
+        item.task + ' 引用了不存在的 Spec: ' + ref, item.task_file, '修复 Spec-Refs'));
+    }
+  }
+  const files = [...new Set(listing.items.map(item => item.task_file))];
+  for (const file of files) {
+    try { taskdoc.batches(task.loadDocument(root, file).tasks); } catch (error) {
+      checks.push(check('TASK_DEPENDENCY_INVALID', 'error', 'fail', error.message,
+        file, '修复 Depends 或任务状态'));
+    }
+  }
+  if (!checks.length) checks.push(pass('TASK_OK', '任务文档与依赖有效。', '.code-flow/tasks'));
+  return checks;
+}
+
+function worktreeList(root) {
+  const raw = gitRead(root, ['worktree', 'list', '--porcelain']);
+  if (raw === null) return null;
+  const entries = [];
+  let current = null;
+  for (const line of raw.split('\n')) {
+    if (line.startsWith('worktree ')) { current = { path: line.slice(9), branch: null, head: null }; entries.push(current); }
+    else if (current && line.startsWith('HEAD ')) current.head = line.slice(5);
+    else if (current && line.startsWith('branch ')) current.branch = line.slice(7);
+  }
+  return entries;
+}
+
+function registeredWorker(registered, absolute) {
+  return registered.find(item => {
+    try { return f.realpath(item.path) === f.realpath(absolute); } catch (_) { return false; }
+  });
+}
+
+function workerFindings(root, ledger, registered, record) {
+  const checks = [];
+  for (const worker of ledger.worktrees) {
+    if (worker.status === 'removed') continue;
+    const absolute = path.join(root, worker.path);
+    if (!fs.existsSync(absolute) || !registeredWorker(registered, absolute)) {
+      checks.push(check('WORKTREE_RECOVERY_REQUIRED', 'warning', 'fail',
+        '缺少注册的 worker worktree: ' + worker.task, worker.path || record.file,
+        '按 ledger 重建或显式放弃该 run'));
+    } else if (worker.status === 'merged' && worker.collected_head &&
+        gitRead(root, ['merge-base', '--is-ancestor', worker.collected_head, 'HEAD']) === null) {
+      checks.push(check('WORKTREE_RECOVERY_REQUIRED', 'warning', 'fail',
+        '已合并 worker 的提交不在协调历史中: ' + worker.task, worker.path,
+        '检查分支重写并显式恢复 ledger'));
+    }
+  }
+  return checks;
+}
+
+function runFindings(root, ledger, registered, record) {
+  const checks = [];
+  let rootMatches = false;
+  try { rootMatches = f.realpath(ledger.coordinator.root) === f.realpath(root); } catch (_) { rootMatches = false; }
+  if (!rootMatches) {
+    checks.push(check('WORKTREE_IDENTITY_MISMATCH', 'error', 'fail',
+      'ledger 协调工作区与当前项目不一致: ' + record.run_id, record.file,
+      '在记录中的协调工作区运行 doctor'));
+    return checks;
+  }
+  if (ledger.status !== 'done' && ledger.status !== 'aborted') {
+    checks.push(check('WORKTREE_RECOVERY_REQUIRED', 'warning', 'fail',
+      'worktree run 尚未完成: ' + record.status, record.file,
+      '执行 code-flow task parallel status 后继续 merge/cleanup'));
+  }
+  if (!registered) return checks.concat(check('WORKTREE_RECOVERY_REQUIRED', 'warning', 'fail',
+    'Git worktree 注册信息不可读取: ' + record.run_id, record.file, '检查 Git worktree 注册'));
+  if (ledger.coordinator.branch && gitRead(root, ['symbolic-ref', '-q', 'HEAD']) !== ledger.coordinator.branch) {
+    checks.push(check('WORKTREE_IDENTITY_MISMATCH', 'error', 'fail',
+      '协调分支已切换: ' + record.run_id, record.file, '切回原分支或显式放弃 run'));
+  }
+  return checks.concat(workerFindings(root, ledger, registered, record));
+}
+
+function worktreeChecks(root) {
+  let records;
+  try { records = runs.list(root); } catch (error) {
+    return [check('WORKTREE_LEDGER_INVALID', 'error', 'fail', error.message,
+      '.code-flow/worktrees', '检查 worktree run 目录')];
+  }
+  if (!records.length) return [pass('WORKTREE_OK', '没有未完成的 worktree run。', '.code-flow/worktrees')];
+  const checks = [], registered = worktreeList(root);
+  for (const record of records) {
+    if (record.status === 'invalid') {
+      checks.push(check('WORKTREE_LEDGER_INVALID', 'error', 'fail',
+        record.error || 'ledger 无效', record.file, '修复或显式放弃该 run'));
+      continue;
+    }
+    checks.push(...runFindings(root, record.ledger, registered, record));
+  }
+  return checks.length ? checks : [pass('WORKTREE_OK', 'worktree run 状态可读取。', '.code-flow/worktrees')];
+}
+
+function summary(checks) {
+  const result = { pass: 0, warning: 0, error: 0, unknown: 0 };
+  for (const item of checks) {
+    if (item.status === 'pass') result.pass++;
+    else if (item.status === 'unknown') result.unknown++;
+    if (item.severity === 'warning' && item.status !== 'pass') result.warning++;
+    if (item.severity === 'error' && item.status !== 'pass') result.error++;
+  }
+  return result;
+}
+
+function text(checks, totals) {
+  return checks.map(item => '[' + item.status.toUpperCase() + '] ' + item.code + ' ' +
+    item.message + (item.path ? ' (' + item.path + ')' : '')).join('\n') + '\n' +
+    'pass=' + totals.pass + ' warning=' + totals.warning +
+    ' error=' + totals.error + ' unknown=' + totals.unknown + '\n';
+}
+
+function run(root) {
+  const real = f.realpath(root);
+  const configured = configChecks(real), settings = configured[0].value;
+  const specs = specChecks(real, settings);
+  const checks = [
+    ...configured[0].checks,
+    ...templateChecks(real),
+    ...launcherChecks(real),
+    ...codexChecks(real),
+    ...specs.checks,
+    ...taskChecks(real, specs.ids),
+    ...worktreeChecks(real)
+  ];
+  const totals = summary(checks);
+  return { schema_version: 1, root: real, ok: totals.error === 0, summary: totals,
+    checks, text: text(checks, totals) };
+}
+
+module.exports = { run, TEMPLATES, LAUNCHER };

package/lib/frontmatter.js

@@ -0,0 +1,42 @@
+'use strict';
+const fs = require('node:fs');
+const { object, demand, FlowError } = require('./fs');
+
+function parse(raw) {
+  const bom = raw.startsWith('\ufeff') ? '\ufeff' : '';
+  const text = raw.slice(bom.length);
+  const match = text.match(/^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/);
+  demand(match, 'frontmatter_missing', 'Expected JSON frontmatter');
+  let meta;
+  try { meta = JSON.parse(match[1]); } catch (error) {
+    throw new FlowError('frontmatter_invalid', 'Invalid JSON frontmatter: ' + error.message);
+  }
+  object(meta, 'frontmatter');
+  return { meta, body: text.slice(match[0].length), header: match[0], bom,
+    eol: match[0].includes('\r\n') ? '\r\n' : '\n', raw };
+}
+function stringify(document, meta = document.meta, body = document.body) {
+  const eol = document.eol || '\n';
+  const header = document.header && JSON.stringify(meta) === JSON.stringify(document.meta)
+    ? document.header : '---' + eol + JSON.stringify(meta, null, 2).replace(/\n/g, eol) + eol + '---' + eol;
+  return (document.bom || '') + header + body;
+}
+function create(meta, body = '') {
+  return stringify({ meta: {}, body, eol: '\n', bom: '' }, meta, body);
+}
+function readHeader(file) {
+  const fd = fs.openSync(file, 'r');
+  const chunks = [];
+  try {
+    for (let total = 0; total < 65536; total += 1024) {
+      const buffer = Buffer.alloc(1024);
+      const size = fs.readSync(fd, buffer, 0, buffer.length, null);
+      if (!size) break;
+      chunks.push(buffer.subarray(0, size));
+      const text = Buffer.concat(chunks).toString('utf8');
+      if (/^\ufeff?---[ \t]*\r?\n[\s\S]*?\r?\n---[ \t]*(?:\r?\n|$)/.test(text)) return parse(text).meta;
+    }
+    throw new FlowError('frontmatter_missing', 'Missing or oversized JSON frontmatter: ' + file);
+  } finally { fs.closeSync(fd); }
+}
+module.exports = { parse, stringify, create, readHeader };

package/lib/fs.js

@@ -0,0 +1,141 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const crypto = require('node:crypto');
+
+class FlowError extends Error {
+  constructor(code, message, exitCode = 2) {
+    super(message); this.name = 'FlowError'; this.code = code; this.exitCode = exitCode;
+  }
+}
+function demand(condition, code, message, exitCode = 2) {
+  if (!condition) throw new FlowError(code, message, exitCode);
+}
+function object(value, label) {
+  demand(value !== null && typeof value === 'object' && !Array.isArray(value),
+    'invalid_data', label + ' must be an object');
+  return value;
+}
+function string(value, label) {
+  demand(typeof value === 'string' && value.trim().length > 0 && !value.includes('\0'),
+    'invalid_data', label + ' must be a nonempty string');
+  return value;
+}
+function strings(value, label) {
+  demand(Array.isArray(value), 'invalid_data', label + ' must be an array');
+  return value.map(item => string(item, label));
+}
+function positive(value, label, integer = false) {
+  demand(typeof value === 'number' && Number.isFinite(value) && value > 0 &&
+    (!integer || Number.isSafeInteger(value)), 'invalid_data', label + ' must be positive' + (integer ? ' integer' : ''));
+  return value;
+}
+function hash(value) { return crypto.createHash('sha256').update(value).digest('hex'); }
+function readText(file, maximum = 4 * 1024 * 1024) {
+  try {
+    demand(fs.statSync(file).size <= maximum, 'file_too_large', 'File too large: ' + file);
+    return fs.readFileSync(file, 'utf8');
+  } catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+}
+function realpath(value) {
+  return fs.realpathSync.native(value);
+}
+function within(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return relative === '' || (!relative.startsWith('..' + path.sep) && relative !== '..' && !path.isAbsolute(relative));
+}
+function inside(root, relative) {
+  string(relative, 'path');
+  const clean = relative.replace(/\\/g, '/');
+  demand(!path.posix.isAbsolute(clean) && !path.win32.isAbsolute(relative) &&
+    !clean.split('/').includes('..') && !/[\r\n]/.test(clean), 'invalid_path', 'Invalid path: ' + relative);
+  const base = realpath(root);
+  let current = base;
+  for (const part of clean.split('/').filter(p => p && p !== '.')) {
+    const next = path.join(current, part);
+    if (!fs.existsSync(next) && fs.existsSync(current) && fs.statSync(current).isDirectory()) {
+      const entries = fs.readdirSync(current);
+      demand(!entries.some(name => name !== part && name.toLowerCase() === part.toLowerCase()) ||
+        entries.includes(part), 'invalid_path', 'Path case mismatch: ' + relative);
+    }
+    current = next;
+    if (fs.existsSync(current)) {
+      const real = realpath(current);
+      demand(real === current || real.toLowerCase() !== current.toLowerCase(),
+        'invalid_path', 'Path case mismatch: ' + relative);
+      demand(within(base, real), 'invalid_path', 'Path escapes workspace: ' + relative);
+    }
+  }
+  demand(within(base, current), 'invalid_path', 'Path escapes workspace: ' + relative);
+  return current;
+}
+function removeIfPresent(file) {
+  try { fs.unlinkSync(file); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+}
+function atomicWrite(file, text, before = undefined) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temporary = path.join(path.dirname(file), '.' + path.basename(file) + '.' + crypto.randomUUID() + '.tmp');
+  let fd;
+  try {
+    fd = fs.openSync(temporary, 'wx', 0o600);
+    fs.writeFileSync(fd, text, 'utf8'); fs.fsyncSync(fd); fs.closeSync(fd); fd = undefined;
+    demand(before === undefined || readText(file) === before, 'concurrent_change', 'Concurrent edit: ' + file, 1);
+    fs.renameSync(temporary, file);
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+    removeIfPresent(temporary);
+  }
+}
+function transientRoot(root) {
+  return path.join(os.tmpdir(), 'code-flow', hash(realpath(root)));
+}
+function lockDirectory(root) {
+  return path.join(transientRoot(root), 'locks');
+}
+function acquireIn(directory, key) {
+  fs.mkdirSync(directory, { recursive: true });
+  const file = path.join(directory, hash(key) + '.lock');
+  const owner = crypto.randomUUID();
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      const fd = fs.openSync(file, 'wx', 0o600);
+      try { fs.writeFileSync(fd, JSON.stringify({ pid: process.pid, owner })); } finally { fs.closeSync(fd); }
+      return { file, owner, key };
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      const raw = readText(file);
+      if (raw === null) continue;
+      let record;
+      try { record = JSON.parse(raw); } catch (failure) {
+        throw new FlowError('lock_invalid', 'Invalid lock JSON: ' + failure.message, 1);
+      }
+      demand(Number.isInteger(record.pid) && record.pid > 0, 'lock_invalid', 'Invalid lock owner: ' + file, 1);
+      try { process.kill(record.pid, 0); } catch (failure) {
+        if (failure.code === 'ESRCH' && readText(file) === raw) { removeIfPresent(file); continue; }
+        if (failure.code !== 'EPERM') throw failure;
+      }
+      throw new FlowError('locked', 'Resource lock is held: ' + key, 1);
+    }
+  }
+  throw new FlowError('locked', 'Cannot acquire lock: ' + key, 1);
+}
+function acquire(root, key) {
+  return acquireIn(lockDirectory(root), key);
+}
+function releaseLock(lock) {
+  const raw = readText(lock.file);
+  if (raw === null) return;
+  demand(JSON.parse(raw).owner === lock.owner, 'lock_changed', 'Lock ownership changed', 1);
+  removeIfPresent(lock.file);
+}
+async function withLockIn(directory, key, operation) {
+  const lock = acquireIn(directory, key);
+  try { return await operation(); } finally { releaseLock(lock); }
+}
+async function withLock(root, key, operation) {
+  return withLockIn(lockDirectory(root), key, operation);
+}
+module.exports = { FlowError, demand, object, string, strings, positive, hash,
+  readText, realpath, within, inside, removeIfPresent, atomicWrite, transientRoot,
+  acquireIn, releaseLock, withLockIn, withLock };

package/lib/glob.js

@@ -0,0 +1,23 @@
+'use strict';
+const { demand, string } = require('./fs');
+
+function compile(pattern) {
+  string(pattern, 'glob');
+  demand(!/[\\{}[\]()!]/.test(pattern) && !pattern.startsWith('/') &&
+    !pattern.split('/').includes('..'), 'invalid_glob', 'Unsupported glob: ' + pattern);
+  let result = '^';
+  for (let i = 0; i < pattern.length; i++) {
+    const char = pattern[i];
+    if (char === '*' && pattern[i + 1] === '*') {
+      demand((i === 0 || pattern[i - 1] === '/') &&
+        (i + 2 === pattern.length || pattern[i + 2] === '/'), 'invalid_glob', 'Invalid ** glob: ' + pattern);
+      if (pattern[i + 2] === '/') { result += '(?:[^/]+/)*'; i += 2; }
+      else { result += '.*'; i++; }
+    } else if (char === '*') result += '[^/]*';
+    else if (char === '?') result += '[^/]';
+    else result += char.replace(/[.+^$|]/g, '\\$&');
+  }
+  return new RegExp(result + '$');
+}
+function matches(pattern, file) { return compile(pattern).test(file.replace(/\\/g, '/')); }
+module.exports = { compile, matches };