@michaelxwb/code-flow 0.8.1 → 1.0.0

package/lib/render.js

@@ -0,0 +1,115 @@
+'use strict';
+const path = require('node:path');
+const f = require('./fs');
+const config = require('./config');
+const spec = require('./spec');
+const glob = require('./glob');
+function diagnostic(error, source) {
+  return { code: error.code || 'read_error', source, message: error.message };
+}
+function requests(settings, task, paths) {
+  const result = settings.always.map(ref => ({ ref, priority: 0, source: 'always' }));
+  for (const ref of task?.specRefs ?? []) result.push({ ref, priority: ref.includes('#') ? 1 : 2, source: 'task.spec_refs' });
+  for (const file of paths) {
+    for (const [pattern, refs] of Object.entries(settings.paths)) {
+      if (glob.matches(pattern, file)) {
+        for (const ref of refs) result.push({ ref, priority: 3, source: 'path:' + file });
+      }
+    }
+  }
+  return result.sort((a, b) => a.priority - b.priority);
+}
+function select(root, entries, diagnostics) {
+  const loaded = new Map(), selected = new Map();
+  for (const entry of entries) {
+    try {
+      const ref = config.reference(entry.ref);
+      if (!loaded.has(ref.id)) loaded.set(ref.id, spec.load(root, ref.id));
+      const document = loaded.get(ref.id);
+      const rules = ref.rule ? document.rules.filter(rule => rule.id === ref.rule) : document.rules;
+      f.demand(!ref.rule || rules.length, 'rule_missing', 'Missing Rule: ' + entry.ref);
+      for (const rule of rules) {
+        const key = ref.id + '#' + rule.id;
+        if (!selected.has(key)) selected.set(key, { ref: key, spec: ref.id, rule: rule.id,
+          text: rule.text, source: '.code-flow/specs/' + ref.id + '.md', selectedBy: [] });
+        const item = selected.get(key);
+        if (!item.selectedBy.includes(entry.source)) item.selectedBy.push(entry.source);
+      }
+    } catch (error) { diagnostics.push(diagnostic(error, entry.ref)); }
+  }
+  return [...selected.values()];
+}
+function estimate(text) {
+  const ascii = (text.match(/[\x00-\x7f]/g) || []).length;
+  return Math.ceil(ascii / 4) + [...text].length - ascii;
+}
+function ruleText(rule, previous) {
+  const header = !previous || previous.spec !== rule.spec || previous.source !== rule.source ||
+    previous.selectedBy.join(', ') !== rule.selectedBy.join(', ')
+    ? '### ' + rule.spec + '\nsource: ' + rule.source +
+      '\nselected-by: ' + rule.selectedBy.join(', ') + '\n'
+    : '';
+  return header + '\n- [' + rule.rule + '] ' + rule.text + '\n';
+}
+function fits(text, budget) {
+  return estimate(text) <= budget.maxTokens && Buffer.byteLength(text, 'utf8') <= budget.maxBytes;
+}
+function render(selected, settings, context) {
+  const heading = '## Spec Constraints (latest)\n\n' +
+    (context.session ? 'session: ' + context.session + '\n' : '') +
+    (context.task ? 'task: ' + context.task + '\n' : '') +
+    'workflow: ' + settings.workflow + '\n';
+  const readMore = '\nread-more: code-flow spec inject' +
+    (context.task ? ' --task-file "' + context.taskFile + '" --task ' + context.taskId : '') + ' --full\n';
+  const reserve = '\nomitted: ' + selected.slice(0, 3).map(item => item.ref).join(', ') + readMore;
+  const emitted = [], omitted = [];
+  let text = heading, last = null;
+  for (const item of selected) {
+    const addition = '\n' + ruleText(item, last);
+    if (context.full || fits(text + addition + reserve, settings.budget)) {
+      text += addition; emitted.push(item.ref); last = item;
+    } else omitted.push(item);
+  }
+  if (omitted.length) text += '\nomitted: ' + omitted.slice(0, 3).map(item => item.ref).join(', ') +
+    (omitted.length > 3 ? ' (+' + (omitted.length - 3) + ')' : '') + readMore;
+  if (!context.full && !fits(text, settings.budget)) {
+    text = 'Spec budget too small. Run code-flow spec inject --full.\n';
+  }
+  return { text, emitted, omitted: omitted.map(item => ({ ref: item.ref, source: item.source })) };
+}
+function normalizePaths(root, paths) {
+  return [...new Set(paths.map(file => {
+    const relative = path.isAbsolute(file) ? path.relative(root, file) : file;
+    f.inside(root, relative);
+    return relative.replace(/\\/g, '/').replace(/^\.\//, '');
+  }))];
+}
+function inject(root, options = {}) {
+  const settings = config.load(root), diagnostics = [];
+  let task = null;
+  if (options.taskFile) {
+    try { task = require('./task').loadTask(root, options.taskFile, options.taskId); } catch (error) {
+      if (options.strictTask) throw error;
+      diagnostics.push(diagnostic(error, options.taskFile));
+    }
+  }
+  const paths = [];
+  for (const file of options.paths ?? []) {
+    try { paths.push(...normalizePaths(root, [file])); } catch (error) { diagnostics.push(diagnostic(error, file)); }
+  }
+  const entries = requests(settings, task, paths), selected = select(root, entries, diagnostics);
+  let catalog = [];
+  if (!task && entries.length === settings.always.length) {
+    const listing = spec.list(root, false); catalog = listing.items; diagnostics.push(...listing.diagnostics);
+  }
+  const identity = task ? task.relative + '#' + task.id : null;
+  const result = render(selected, settings, { ...options, task: identity,
+    taskFile: task?.relative, taskId: task?.id });
+  if (catalog.length) {
+    const navigation = '\n## Spec Catalog\n' + catalog.slice(0, 20).map(item => item.id + ': ' + item.description).join('\n') +
+      '\n' + catalog.length + ' Specs; code-flow spec list --json\n';
+    if (options.full || fits(result.text + navigation, settings.budget)) result.text += navigation;
+  }
+  return { ...result, selected, diagnostics, catalog, task: identity, taskFile: task?.relative ?? null, taskId: task?.id ?? null };
+}
+module.exports = { inject, select, requests, render, estimate, normalizePaths };

package/lib/repo.js

@@ -0,0 +1,48 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const f = require('./fs');
+
+function run(root, args) {
+  const result = spawnSync('git', args, { cwd: root, encoding: 'utf8', maxBuffer: 1024 * 1024 });
+  if (result.error) {
+    throw new f.FlowError('git_identity', 'Cannot read Git identity: ' + result.error.message, 2);
+  }
+  f.demand(result.status === 0, 'git_identity',
+    'Cannot read Git identity: ' + (result.stderr || 'git exited ' + result.status).trim(), 2);
+  return result.stdout.trim();
+}
+
+function identity(root) {
+  const real = f.realpath(root);
+  if (!fs.existsSync(path.join(real, '.git'))) return { git: false, root: real, linked: false };
+  const gitDir = path.resolve(real, run(real, ['rev-parse', '--git-dir']));
+  const commonDir = path.resolve(real, run(real, ['rev-parse', '--git-common-dir']));
+  const top = f.realpath(run(real, ['rev-parse', '--show-toplevel']));
+  const linked = f.realpath(gitDir) !== f.realpath(commonDir);
+  const branchResult = spawnSync('git', ['symbolic-ref', '-q', 'HEAD'], { cwd: real, encoding: 'utf8' });
+  return { git: true, root: real, top, git_dir: f.realpath(gitDir),
+    git_common_dir: f.realpath(commonDir), branch: branchResult.status === 0 ? branchResult.stdout.trim() : null,
+    linked };
+}
+
+function state(root) {
+  const real = f.realpath(root);
+  if (!fs.existsSync(path.join(real, '.git'))) return { head: null, dirty: null };
+  const head = spawnSync('git', ['rev-parse', 'HEAD'], { cwd: real, encoding: 'utf8' });
+  const status = spawnSync('git', ['status', '--porcelain', '--untracked-files=all'],
+    { cwd: real, encoding: 'utf8', maxBuffer: 8 * 1024 * 1024 });
+  const dirty = status.status !== 0 ? null : status.stdout.split('\n').filter(Boolean)
+    .some(line => !line.slice(3).trim().replace(/^"|"$/g, '').startsWith('.code-flow/'));
+  return { head: head.status === 0 ? head.stdout.trim() : null, dirty };
+}
+
+function requireCoordinator(root, operation) {
+  const current = identity(root);
+  f.demand(!current.linked, 'coordinator_required',
+    operation + ' must run in the coordinator worktree: ' + current.top, 1);
+  return current;
+}
+
+module.exports = { identity, requireCoordinator, state };

package/lib/runs.js

@@ -0,0 +1,155 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const f = require('./fs');
+const repo = require('./repo');
+
+const UNFINISHED = new Set(['preparing', 'running', 'merging', 'verifying', 'cleaning', 'blocked']);
+const STATUSES = new Set([...UNFINISHED, 'done', 'aborted']);
+const WORKTREES = '.code-flow/worktrees';
+
+function validateLedger(ledger, runId) {
+  const errors = [];
+  if (!ledger || typeof ledger !== 'object' || Array.isArray(ledger)) return ['Run ledger must be an object'];
+  if (typeof ledger.run_id !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(ledger.run_id)) {
+    errors.push('Invalid run identity');
+  } else if (runId !== undefined && ledger.run_id !== runId) {
+    errors.push('Run ledger identity does not match: ' + runId);
+  }
+  if (!STATUSES.has(ledger.status)) errors.push('Invalid run status: ' + String(ledger.status));
+  if (!ledger.coordinator || typeof ledger.coordinator !== 'object' || Array.isArray(ledger.coordinator) ||
+      typeof ledger.coordinator.root !== 'string' || typeof ledger.coordinator.branch !== 'string' ||
+      typeof ledger.coordinator.git_common_dir !== 'string') {
+    errors.push('Run ledger has no coordinator identity');
+  }
+  if (!Array.isArray(ledger.worktrees)) errors.push('Run ledger has no worktree list');
+  if (!ledger.merge || typeof ledger.merge !== 'object' || !Array.isArray(ledger.merge.order)) {
+    errors.push('Run ledger has no merge order');
+  }
+  if (errors.length) return errors;
+  for (const worker of ledger.worktrees) {
+    if (!worker || typeof worker !== 'object' || !/^TASK-\d+$/.test(worker.task) ||
+        worker.path !== WORKTREES + '/' + ledger.run_id + '/' + worker.task ||
+        worker.branch !== 'cf-task/' + ledger.run_id + '/' + worker.task) {
+      errors.push('Run ledger owns an invalid worker resource: ' + String(worker?.task));
+    }
+  }
+  if (errors.length) return errors;
+  const tasks = ledger.worktrees.map(worker => worker.task).sort();
+  if (JSON.stringify(tasks) !== JSON.stringify([...ledger.merge.order].sort())) {
+    errors.push('Run ledger merge order does not match worktrees');
+  }
+  return errors;
+}
+
+function list(root) {
+  const base = path.join(root, WORKTREES);
+  if (!fs.existsSync(base)) return [];
+  const runs = [];
+  for (const entry of fs.readdirSync(base, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const file = path.join(base, entry.name, 'run.json');
+    if (!fs.existsSync(file)) continue;
+    try {
+      const ledger = JSON.parse(fs.readFileSync(file, 'utf8'));
+      const taskFile = typeof ledger?.task_file === 'string'
+        ? ledger.task_file.replace(/\\/g, '/').replace(/^\.\//, '') : null;
+      const errors = validateLedger(ledger, entry.name);
+      runs.push(errors.length
+        ? { run_id: entry.name, status: 'invalid', task_file: null,
+          file: path.join(WORKTREES, entry.name, 'run.json'), error: errors[0] }
+        : { run_id: ledger.run_id, status: ledger.status,
+          task_file: taskFile, file: path.join(WORKTREES, entry.name, 'run.json'), ledger });
+    } catch (error) {
+      runs.push({ run_id: entry.name, status: 'invalid', task_file: null,
+        file: path.join(WORKTREES, entry.name, 'run.json'), error: error.message });
+    }
+  }
+  return runs;
+}
+
+function unfinished(root, filter = () => true) {
+  return list(root).filter(run => (UNFINISHED.has(run.status) || run.status === 'invalid') && filter(run));
+}
+
+function assertArchiveAllowed(root, requirementDir) {
+  const normalized = requirementDir.replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/$/, '');
+  const blocked = unfinished(root, run => !run.task_file ||
+    run.task_file === normalized || run.task_file.startsWith(normalized + '/'));
+  f.demand(!blocked.length, 'run_incomplete',
+    'Unfinished worktree run for requirement: ' + blocked.map(run => run.run_id).join(', '), 1);
+}
+
+function assertLearnAllowed(root) {
+  const blocked = unfinished(root);
+  f.demand(!blocked.length, 'run_incomplete',
+    'Unfinished worktree run before Spec learning: ' + blocked.map(run => run.run_id).join(', '), 1);
+}
+
+function readWorkerLedger(file, name, owned) {
+  if (!fs.existsSync(file)) {
+    if (owned) throw new f.FlowError('run_invalid', 'Missing run ledger: ' + name, 2);
+    return null;
+  }
+  try {
+    const ledger = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (!ledger || !Array.isArray(ledger.worktrees)) throw new Error('missing worktrees');
+    return ledger;
+  } catch (error) {
+    if (owned) throw new f.FlowError('run_invalid', 'Invalid run ledger: ' + error.message, 2);
+    return null;
+  }
+}
+
+function ledgerWorkerEnv(ledger, name, current, coordinator) {
+  for (const worker of ledger.worktrees) {
+    if (!worker.env || typeof worker.path !== 'string') continue;
+    if (worker.path !== WORKTREES + '/' + name + '/' + worker.task) continue;
+    let workerRoot;
+    try { workerRoot = f.realpath(path.join(coordinator, worker.path)); } catch (_) { continue; }
+    if (workerRoot !== current) continue;
+    const env = worker.env;
+    f.demand(env && typeof env.CF_WORKTREE_ID === 'string' &&
+      typeof env.CF_TASK_ID === 'string' && typeof env.CF_RUN_ID === 'string' &&
+      env.CF_WORKTREE_ID === name + '/' + worker.task &&
+      env.CF_TASK_ID === worker.task && env.CF_RUN_ID === name,
+      'run_invalid', 'Invalid worker environment in run ledger', 2);
+    return { ...env };
+  }
+  return null;
+}
+
+function workerEnv(root) {
+  const current = f.realpath(root);
+  const identity = repo.identity(current);
+  if (!identity.git || !identity.linked) return {};
+  const result = spawnSync('git', ['worktree', 'list', '--porcelain'],
+    { cwd: current, encoding: 'utf8', maxBuffer: 1024 * 1024 });
+  f.demand(result.status === 0, 'git_identity',
+    'Cannot read Git worktree registration: ' + (result.stderr || '').trim(), 2);
+  const main = result.stdout.split('\n').find(line => line.startsWith('worktree '));
+  f.demand(main, 'git_identity', 'Cannot locate coordinator worktree', 2);
+  const coordinator = f.realpath(main.slice(9));
+  const base = path.join(coordinator, WORKTREES);
+  if (!fs.existsSync(base)) return {};
+  const relative = path.relative(coordinator, current).split(path.sep).join('/');
+  let found = null;
+  for (const entry of fs.readdirSync(base, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const owned = relative.startsWith(WORKTREES + '/' + entry.name + '/');
+    const ledger = readWorkerLedger(path.join(base, entry.name, 'run.json'), entry.name, owned);
+    if (!ledger) continue;
+    const env = ledgerWorkerEnv(ledger, entry.name, current, coordinator);
+    if (!env) {
+      if (owned) throw new f.FlowError('run_invalid',
+        'Run ledger does not own this worker: ' + entry.name, 2);
+      continue;
+    }
+    f.demand(!found, 'env_conflict', 'Worktree is claimed by multiple run ledgers', 1);
+    found = env;
+  }
+  return found ?? {};
+}
+
+module.exports = { list, unfinished, assertArchiveAllowed, assertLearnAllowed, workerEnv, validateLedger, UNFINISHED };

package/lib/session.js

@@ -0,0 +1,40 @@
+'use strict';
+const path = require('node:path');
+const fs = require('node:fs');
+const f = require('./fs');
+function token(root, platform, sessionId) {
+  f.string(sessionId, 'session ID');
+  return f.hash(JSON.stringify([f.realpath(root), platform, sessionId]));
+}
+function location(root, value) {
+  f.demand(typeof value === 'string' && /^[a-f0-9]{64}$/.test(value),
+    'session_invalid', 'Session token must be 64 lowercase hexadecimal characters');
+  return path.join(f.transientRoot(root), 'sessions', value + '.json');
+}
+function read(root, value) {
+  const raw = f.readText(location(root, value), 65536);
+  if (raw === null) return null;
+  let result;
+  try { result = JSON.parse(raw); } catch (error) {
+    throw new f.FlowError('session_invalid', 'Invalid session binding: ' + error.message);
+  }
+  f.object(result, 'session binding');
+  f.string(result.task_file, 'session task_file');
+  f.string(result.task_id, 'session task_id');
+  return result;
+}
+async function bind(root, value, taskFile, taskId) {
+  const file = location(root, value);
+  f.string(taskFile, 'task file');
+  f.string(taskId, 'task id');
+  await f.withLock(root, 'session:' + value, async () => {
+    f.atomicWrite(file, JSON.stringify({ task_file: taskFile, task_id: taskId,
+      bound_at: new Date().toISOString() }) + '\n', f.readText(file));
+  });
+}
+async function unbind(root, value) {
+  const file = location(root, value);
+  await f.withLock(root, 'session:' + value, async () => f.removeIfPresent(file));
+  return { ok: true, action: 'unbind' };
+}
+module.exports = { token, location, read, bind, unbind };

package/lib/spec.js

@@ -0,0 +1,80 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const f = require('./fs');
+const fm = require('./frontmatter');
+const { reference } = require('./config');
+const markdown = require('./markdown');
+
+function parseRules(body) {
+  const lines = body.replace(/\r\n/g, '\n').split('\n');
+  const rules = [], used = new Set();
+  let section = false, fence = null, current = null;
+  const finish = end => {
+    if (!current) return;
+    current.end = end;
+    current.text = lines.slice(current.start, end).map((line, i) =>
+      i === 0 ? line.replace(/^- \[RULE-[^\]]+\] /, '') : line.replace(/^  /, '')).join('\n').trim();
+    f.demand(!used.has(current.id), 'duplicate_rule', 'Duplicate Rule ID: ' + current.id);
+    used.add(current.id);
+    rules.push(current); current = null;
+  };
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i], marker = markdown.fenceMarker(line, fence);
+    if (marker) {
+      fence = marker.next;
+      continue;
+    }
+    if (fence) continue;
+    if (/^##\s/.test(line)) { finish(i); section = /^## Rules\s*$/.test(line); continue; }
+    if (!section) continue;
+    const match = line.match(/^- \[(RULE-[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*)\] (.+)$/);
+    if (match) { finish(i); current = { id: match[1], start: i }; }
+    else if (/^- /.test(line)) {
+      finish(i);
+      throw new f.FlowError('rule_invalid', 'Rule must have a stable RULE ID: ' + line);
+    }
+  }
+  f.demand(!fence, 'rule_fence', 'Unclosed code fence in Spec');
+  finish(lines.length);
+  return { rules, lines };
+}
+function header(meta) {
+  f.string(meta.description, 'Spec description');
+  f.positive(meta.next_rule, 'Spec next_rule', true);
+  return meta;
+}
+function load(root, id) {
+  f.demand(!id.includes('#'), 'invalid_reference', 'Expected Spec path without Rule suffix');
+  reference(id);
+  const file = f.inside(root, '.code-flow/specs/' + id + '.md');
+  const raw = f.readText(file);
+  f.demand(raw !== null, 'spec_missing', 'Missing Spec: ' + id);
+  const document = fm.parse(raw);
+  header(document.meta);
+  return { ...document, ...parseRules(document.body), id, file };
+}
+function walk(directory, prefix = '') {
+  if (!fs.existsSync(directory)) return [];
+  return fs.readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))
+    .flatMap(entry => {
+      const relative = prefix + entry.name;
+      if (entry.isSymbolicLink()) return [];
+      if (entry.isDirectory()) return walk(path.join(directory, entry.name), relative + '/');
+      return entry.isFile() && entry.name.endsWith('.md') ? [relative] : [];
+    });
+}
+function list(root, full = true) {
+  const items = [], diagnostics = [];
+  for (const relative of walk(f.inside(root, '.code-flow/specs'))) {
+    const id = relative.slice(0, -3);
+    try {
+      reference(id);
+      const info = full ? load(root, id) : { meta: header(fm.readHeader(f.inside(root, '.code-flow/specs/' + relative))) };
+      items.push({ id, path: '.code-flow/specs/' + relative, description: info.meta.description,
+        ...(full ? { rules: info.rules.length } : {}) });
+    } catch (error) { diagnostics.push({ code: error.code || 'spec_error', source: id, message: error.message }); }
+  }
+  return { items, diagnostics };
+}
+module.exports = { load, list, parseRules, walk, header };