@limina-labs/momentum 0.30.2

package/core/lanes/lib/state.js

@@ -0,0 +1,325 @@
+'use strict';
+
+/**
+ * Lane state layer (Phase 21b, FEAT-026 — see ADR-0002).
+ *
+ * State lives ONCE per repo inside the shared git directory:
+ *
+ *   <git-common-dir>/momentum/lanes/
+ *   ├── registry.json          { stateVersion, lanes: [<id>...] }
+ *   └── <id>/
+ *       ├── manifest.json      lane manifest (shape below)
+ *       └── inbox/             signals (Phase 21b G4); processed/ after ack
+ *
+ * Anchoring at `git rev-parse --git-common-dir` makes the state
+ * untracked by construction, shared across every linked worktree, and
+ * gone with the repo. The format is INTERNAL (stateVersion 1) — the
+ * publish-as-contract decision is deferred to the 21c close per the
+ * platform direction's one-way-door rule.
+ *
+ * Concurrency: all writes go through a single mkdir-lock chokepoint
+ * (the pattern proven in core/swarm/lib/manifest.js); reads are
+ * lock-free. Manifest writes are tmp-file + rename for atomicity.
+ *
+ * Zero dependencies — node builtins only.
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const STATE_VERSION = 1;
+const LANES_SUBDIR = path.join('momentum', 'lanes');
+const REGISTRY = 'registry.json';
+const MANIFEST = 'manifest.json';
+const LOCK_DIR = '.lock';
+const LOCK_RETRIES = 50;
+const LOCK_RETRY_MS = 100;
+
+const STATUSES = Object.freeze(['open', 'done', 'landed', 'closed']);
+const GRADES = Object.freeze(['phase', 'quick-task', 'spike']);
+const ADHOC_BRANCH = /^(fix|chore|feat|refactor|infra)\//;
+
+// ─── git helpers ─────────────────────────────────────────────────────────
+
+function git(cwd, ...args) {
+  const res = spawnSync('git', args, { cwd, encoding: 'utf8' });
+  if (res.status !== 0) return null;
+  return res.stdout.trim();
+}
+
+/** Absolute path of the shared git dir, from any worktree. Null outside a repo. */
+function gitCommonDir(cwd) {
+  const out = git(cwd, 'rev-parse', '--git-common-dir');
+  if (!out) return null;
+  return path.resolve(cwd, out);
+}
+
+/** Root of the current worktree. Null outside a repo. */
+function worktreeRoot(cwd) {
+  return git(cwd, 'rev-parse', '--show-toplevel');
+}
+
+/** Anchor dir for lane state (<common>/momentum/lanes). Null outside a repo. */
+function resolveAnchor(cwd) {
+  const common = gitCommonDir(cwd || process.cwd());
+  if (!common) return null;
+  return path.join(common, LANES_SUBDIR);
+}
+
+// ─── ids / inference ─────────────────────────────────────────────────────
+
+function laneId(branch) {
+  return String(branch).replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '');
+}
+
+/**
+ * Infer the plan node a branch binds to (the Rule 15 convention as data).
+ * `repoRoot` (a worktree root) is used to check for the phase directory.
+ */
+function inferPlanNode(branch, repoRoot) {
+  if (/^phase-/.test(branch)) {
+    const dir = repoRoot && fs.existsSync(path.join(repoRoot, 'specs', 'phases', branch));
+    return { type: 'phase', ref: branch, dirExists: Boolean(dir) };
+  }
+  if (ADHOC_BRANCH.test(branch)) {
+    return { type: 'adhoc', ref: laneId(branch) };
+  }
+  return { type: 'unbound', ref: null };
+}
+
+function defaultGrade(planNode) {
+  if (planNode.type === 'phase') return 'phase';
+  return 'quick-task'; // spikes are always declared explicitly
+}
+
+// ─── locking ─────────────────────────────────────────────────────────────
+
+function sleepMs(ms) {
+  // Synchronous sleep without deps: Atomics.wait on a throwaway buffer.
+  const sab = new Int32Array(new SharedArrayBuffer(4));
+  Atomics.wait(sab, 0, 0, ms);
+}
+
+/** Run fn holding the anchor-wide mkdir lock. Throws ELOCK on timeout. */
+function withLock(anchor, fn) {
+  fs.mkdirSync(anchor, { recursive: true });
+  const lock = path.join(anchor, LOCK_DIR);
+  let held = false;
+  for (let i = 0; i < LOCK_RETRIES; i++) {
+    try {
+      fs.mkdirSync(lock);
+      held = true;
+      break;
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err;
+      sleepMs(LOCK_RETRY_MS);
+    }
+  }
+  if (!held) {
+    const e = new Error(`lane state lock busy: ${lock}`);
+    e.code = 'ELOCK';
+    throw e;
+  }
+  try {
+    return fn();
+  } finally {
+    try { fs.rmdirSync(lock); } catch { /* already gone */ }
+  }
+}
+
+// ─── reads (lock-free) ───────────────────────────────────────────────────
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function readRegistry(anchor) {
+  return readJson(path.join(anchor, REGISTRY)) || { stateVersion: STATE_VERSION, lanes: [] };
+}
+
+function laneDir(anchor, id) {
+  return path.join(anchor, id);
+}
+
+function readManifest(anchor, id) {
+  return readJson(path.join(laneDir(anchor, id), MANIFEST));
+}
+
+/** All manifests listed in the registry (missing ones skipped). */
+function listLanes(anchor) {
+  const reg = readRegistry(anchor);
+  return reg.lanes.map((id) => readManifest(anchor, id)).filter(Boolean);
+}
+
+// ─── writes (locked) ─────────────────────────────────────────────────────
+
+function writeJsonAtomic(file, obj) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = path.join(
+    path.dirname(file),
+    `.${path.basename(file)}.${process.pid}.${Math.random().toString(36).slice(2, 8)}.tmp`
+  );
+  fs.writeFileSync(tmp, JSON.stringify(obj, null, 2) + os.EOL);
+  fs.renameSync(tmp, file);
+}
+
+/**
+ * Create + register a lane. Throws EEXIST if the id is already registered
+ * with a non-closed manifest.
+ */
+function createLane(anchor, manifest) {
+  const full = {
+    stateVersion: STATE_VERSION,
+    id: manifest.id,
+    branch: manifest.branch,
+    planNode: manifest.planNode,
+    worktree: manifest.worktree || null,
+    grade: manifest.grade,
+    touches: manifest.touches || [],
+    status: 'open',
+    opened: manifest.opened || new Date().toISOString(),
+    doneAt: null,
+    landedAt: null,
+    note: manifest.note || null,
+  };
+  if (!GRADES.includes(full.grade)) {
+    throw new Error(`invalid grade '${full.grade}' (expected ${GRADES.join('|')})`);
+  }
+  return withLock(anchor, () => {
+    const existing = readManifest(anchor, full.id);
+    if (existing && existing.status !== 'closed') {
+      const e = new Error(`lane '${full.id}' already open (status: ${existing.status})`);
+      e.code = 'EEXIST';
+      throw e;
+    }
+    const reg = readRegistry(anchor);
+    if (!reg.lanes.includes(full.id)) reg.lanes.push(full.id);
+    writeJsonAtomic(path.join(laneDir(anchor, full.id), MANIFEST), full);
+    writeJsonAtomic(path.join(anchor, REGISTRY), reg);
+    return full;
+  });
+}
+
+/** Patch a lane manifest. Throws ENOLANE when it doesn't exist. */
+function updateLane(anchor, id, patch) {
+  return withLock(anchor, () => {
+    const current = readManifest(anchor, id);
+    if (!current) {
+      const e = new Error(`no such lane: '${id}'`);
+      e.code = 'ENOLANE';
+      throw e;
+    }
+    if (patch.status && !STATUSES.includes(patch.status)) {
+      throw new Error(`invalid status '${patch.status}' (expected ${STATUSES.join('|')})`);
+    }
+    const next = { ...current, ...patch };
+    writeJsonAtomic(path.join(laneDir(anchor, id), MANIFEST), next);
+    return next;
+  });
+}
+
+// ─── inbox reads (writes live in signals.js — G4) ────────────────────────
+
+const INBOX = 'inbox';
+const PROCESSED = 'processed';
+const SIGNAL_TYPES = Object.freeze(['pause', 'resume', 'redirect', 'kill', 'message']);
+
+function inboxDir(anchor, id) {
+  return path.join(laneDir(anchor, id), INBOX);
+}
+
+function processedDir(anchor, id) {
+  return path.join(inboxDir(anchor, id), PROCESSED);
+}
+
+/** Unread signal files for a lane, oldest first. [{file, seq, type, ...body}] */
+function unreadSignals(anchor, id) {
+  const dir = inboxDir(anchor, id);
+  let names;
+  try {
+    names = fs.readdirSync(dir);
+  } catch {
+    return [];
+  }
+  return names
+    .filter((n) => n.endsWith('.json'))
+    .sort()
+    .map((n) => {
+      const body = readJson(path.join(dir, n)) || {};
+      return { file: n, ...body };
+    });
+}
+
+function unreadCount(anchor, id) {
+  return unreadSignals(anchor, id).length;
+}
+
+// ─── touch-path overlap (ENH-047, advisory) ─────────────────────────────
+
+/** Normalize a touch glob to a comparable path prefix. */
+function touchPrefix(glob) {
+  return String(glob)
+    .replace(/\*+.*$/, '') // drop from the first wildcard
+    .replace(/\/+$/, '');
+}
+
+/** True when two touch declarations plausibly overlap (prefix containment). */
+function touchesOverlap(a, b) {
+  const pa = touchPrefix(a);
+  const pb = touchPrefix(b);
+  if (pa === '' || pb === '') return true; // bare '**' overlaps everything
+  return pa === pb || pa.startsWith(pb + '/') || pb.startsWith(pa + '/');
+}
+
+/**
+ * Overlap report between one lane's touches and every other active lane.
+ * Returns [{ laneId, mine, theirs }].
+ */
+function overlapWarnings(anchor, id, touches) {
+  const warnings = [];
+  if (!touches || touches.length === 0) return warnings;
+  for (const other of listLanes(anchor)) {
+    if (other.id === id) continue;
+    if (other.status === 'closed' || other.status === 'landed') continue;
+    for (const mine of touches) {
+      for (const theirs of other.touches || []) {
+        if (touchesOverlap(mine, theirs)) {
+          warnings.push({ laneId: other.id, mine, theirs });
+        }
+      }
+    }
+  }
+  return warnings;
+}
+
+module.exports = {
+  STATE_VERSION,
+  STATUSES,
+  GRADES,
+  resolveAnchor,
+  gitCommonDir,
+  worktreeRoot,
+  laneId,
+  inferPlanNode,
+  defaultGrade,
+  withLock,
+  readRegistry,
+  readManifest,
+  listLanes,
+  createLane,
+  updateLane,
+  laneDir,
+  touchesOverlap,
+  overlapWarnings,
+  SIGNAL_TYPES,
+  inboxDir,
+  processedDir,
+  unreadSignals,
+  unreadCount,
+};

package/core/lib/frontmatter.js

@@ -0,0 +1,163 @@
+'use strict';
+
+/**
+ * Zero-dependency YAML-frontmatter subset parser/serializer (OKF v0.1).
+ *
+ * Momentum only ever EMITS this subset, so it only PARSES this subset:
+ *   - string scalars:        key: value | key: "value" | key: 'value'
+ *   - inline string lists:   key: [a, b, "c d"]
+ *   - block string lists:    key:\n  - a\n  - b
+ *   - empty scalars:         key:
+ *
+ * Reads are tolerant per the OKF conformance rules: anything outside the
+ * subset (nested maps, multi-line scalars, tabs) makes parse() return
+ * `data: null` — callers treat the file as opaque and leave it alone.
+ * parse() never throws. Round-trips preserve unknown keys and key order.
+ */
+
+const OPEN = /^---\r?\n/;
+
+/** True when content begins with a `---` frontmatter fence. */
+function hasBlock(content) {
+  return typeof content === 'string' && OPEN.test(content);
+}
+
+function unquote(value) {
+  if (value.length >= 2) {
+    const first = value[0];
+    const last = value[value.length - 1];
+    if (first === last && (first === '"' || first === "'")) {
+      const inner = value.slice(1, -1);
+      return first === '"' ? inner.replace(/\\(["\\])/g, '$1') : inner;
+    }
+  }
+  return value;
+}
+
+function parseInlineList(value) {
+  const inner = value.slice(1, -1).trim();
+  if (inner === '') return [];
+  const items = [];
+  let current = '';
+  let quote = null;
+  for (let i = 0; i < inner.length; i += 1) {
+    const ch = inner[i];
+    if (quote) {
+      current += ch;
+      if (ch === quote && inner[i - 1] !== '\\') quote = null;
+    } else if (ch === '"' || ch === "'") {
+      current += ch;
+      quote = ch;
+    } else if (ch === ',') {
+      items.push(unquote(current.trim()));
+      current = '';
+    } else {
+      current += ch;
+    }
+  }
+  if (quote) return null; // unterminated quote — outside the subset
+  items.push(unquote(current.trim()));
+  return items;
+}
+
+/**
+ * Parse frontmatter. Returns { data, body, raw }:
+ *   data — object (string | string[] values), or null when there is no
+ *          fence or the block falls outside the supported subset;
+ *   body — content after the closing fence (original content when no
+ *          fence / unparseable block);
+ *   raw  — the exact frontmatter text between the fences (null when no
+ *          fence), preserved so callers can do textual edits instead of
+ *          reserializing.
+ */
+function parse(content) {
+  if (!hasBlock(content)) return { data: null, body: content, raw: null };
+
+  const fenceEnd = content.match(/\r?\n---[ \t]*(\r?\n|$)/);
+  if (!fenceEnd) return { data: null, body: content, raw: null };
+
+  const open = content.match(OPEN)[0].length;
+  const rawBlock = content.slice(open, fenceEnd.index);
+  const body = content.slice(fenceEnd.index + fenceEnd[0].length);
+
+  const data = {};
+  const lines = rawBlock.split(/\r?\n/);
+  let pendingKey = null;
+  const emptyKeys = new Set();
+
+  for (const line of lines) {
+    if (line.trim() === '' || line.trim().startsWith('#')) continue;
+    const listItem = line.match(/^\s+-\s?(.*)$/);
+    if (listItem) {
+      if (pendingKey === null) return { data: null, body: content, raw: rawBlock };
+      data[pendingKey].push(unquote(listItem[1].trim()));
+      emptyKeys.delete(pendingKey);
+      continue;
+    }
+    if (/^\s/.test(line)) return { data: null, body: content, raw: rawBlock }; // nested structure
+    const kv = line.match(/^([A-Za-z0-9_-]+):(.*)$/);
+    if (!kv) return { data: null, body: content, raw: rawBlock };
+    const key = kv[1];
+    const value = kv[2].trim();
+    if (value === '') {
+      data[key] = [];
+      pendingKey = key; // block list opener — or an empty scalar (normalized below)
+      emptyKeys.add(key);
+      continue;
+    }
+    pendingKey = null;
+    if (value.startsWith('[') && value.endsWith(']')) {
+      const list = parseInlineList(value);
+      if (list === null) return { data: null, body: content, raw: rawBlock };
+      data[key] = list;
+    } else {
+      data[key] = unquote(value);
+    }
+  }
+
+  // `key:` that never received list items is an empty string scalar.
+  for (const key of emptyKeys) data[key] = '';
+
+  return { data, body, raw: rawBlock };
+}
+
+const NEEDS_QUOTES = /[:#\[\]{}&*!|>'"%@`,]|^[\s-]|\s$|^$|^(true|false|null|~|yes|no|on|off)$|^[\d.+-]/i;
+
+function quoteScalar(value) {
+  const str = String(value);
+  if (!NEEDS_QUOTES.test(str)) return str;
+  return `"${str.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+
+/** Serialize a data object to frontmatter YAML lines (no fences). */
+function stringifyData(data) {
+  const lines = [];
+  for (const [key, value] of Object.entries(data)) {
+    if (Array.isArray(value)) {
+      lines.push(`${key}: [${value.map(quoteScalar).join(', ')}]`);
+    } else {
+      lines.push(`${key}: ${quoteScalar(value)}`);
+    }
+  }
+  return lines.join('\n');
+}
+
+/** Compose a full document: fenced frontmatter + body. */
+function compose(data, body) {
+  const yaml = stringifyData(data);
+  const sep = body && !body.startsWith('\n') ? '\n' : '';
+  return `---\n${yaml}\n---\n${sep}${body || ''}`;
+}
+
+/**
+ * Insert `type: <value>` as the first line of an EXISTING frontmatter
+ * block, textually — everything else in the file is preserved
+ * byte-for-byte. Returns null when the file has no block.
+ */
+function insertTypeLine(content, type) {
+  if (!hasBlock(content)) return null;
+  const open = content.match(OPEN)[0];
+  return `${open}type: ${quoteScalar(type)}\n${content.slice(open.length)}`;
+}
+
+module.exports = { hasBlock, parse, stringifyData, compose, insertTypeLine, quoteScalar };