@limina-labs/momentum 0.30.2

package/core/ecosystem/lib/initiative.js

@@ -0,0 +1,258 @@
+'use strict';
+
+/**
+ * Initiative helpers — pure, dependency-free.
+ *
+ * An initiative is one markdown file under
+ * `<ecosystem-root>/initiatives/NNNN-<slug>.md` with a YAML frontmatter
+ * block validated against `../schema/initiative.schema.json`. Body is
+ * free-form markdown using the fixed sections from
+ * `../templates/initiative-template.md`.
+ *
+ * Numbering is monotonically increasing across the ecosystem. The
+ * filename slug is for human readability; the `id` integer is canonical.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const INITIATIVES_DIR = 'initiatives';
+const STATE_DIR = '.state';
+const ACTIVE_FILE = 'active-initiative';
+
+const FRONTMATTER_FENCE = '---';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Frontmatter parse / serialize (single-level YAML only)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Minimal YAML reader: supports scalar key:value lines (string / integer)
+ * and inline arrays like `repos: [a, b, c]`. Quotes optional on scalars.
+ * Anything more complex (nested, multi-line) is not used by initiatives
+ * today — keep this strict and dependency-free.
+ */
+function parseFrontmatter(body) {
+  if (typeof body !== 'string') return { frontmatter: null, content: body };
+  const trimmed = body.replace(/^/, '');
+  if (!trimmed.startsWith(FRONTMATTER_FENCE)) {
+    return { frontmatter: null, content: body };
+  }
+  const lines = trimmed.split('\n');
+  // Find the closing fence after the first.
+  let end = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i].trim() === FRONTMATTER_FENCE) { end = i; break; }
+  }
+  if (end === -1) return { frontmatter: null, content: body };
+  const fmLines = lines.slice(1, end);
+  const fm = {};
+  for (const raw of fmLines) {
+    const line = raw.trim();
+    if (line.length === 0 || line.startsWith('#')) continue;
+    const colon = line.indexOf(':');
+    if (colon === -1) continue;
+    const key = line.slice(0, colon).trim();
+    let value = line.slice(colon + 1).trim();
+    if (value.startsWith('[') && value.endsWith(']')) {
+      // Inline array
+      const inner = value.slice(1, -1).trim();
+      fm[key] = inner.length === 0
+        ? []
+        : inner.split(',').map((s) => stripQuotes(s.trim())).filter(Boolean);
+    } else if (/^-?\d+$/.test(value)) {
+      fm[key] = parseInt(value, 10);
+    } else {
+      fm[key] = stripQuotes(value);
+    }
+  }
+  const content = lines.slice(end + 1).join('\n').replace(/^\n+/, '');
+  return { frontmatter: fm, content };
+}
+
+function stripQuotes(s) {
+  if (s.length >= 2) {
+    const first = s[0];
+    const last = s[s.length - 1];
+    if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+      return s.slice(1, -1);
+    }
+  }
+  return s;
+}
+
+function serializeFrontmatter(fm) {
+  const lines = [FRONTMATTER_FENCE];
+  for (const key of Object.keys(fm)) {
+    const value = fm[key];
+    if (value === undefined || value === null) continue;
+    if (Array.isArray(value)) {
+      lines.push(`${key}: [${value.map((v) => formatScalar(v)).join(', ')}]`);
+    } else {
+      lines.push(`${key}: ${formatScalar(value)}`);
+    }
+  }
+  lines.push(FRONTMATTER_FENCE);
+  return lines.join('\n') + '\n';
+}
+
+function formatScalar(v) {
+  if (typeof v === 'number') return String(v);
+  const s = String(v);
+  // Quote when ambiguous: contains characters that would re-parse oddly.
+  if (s.length === 0) return '""';
+  if (/[#:,\[\]]/.test(s) || /^\s|\s$/.test(s) || /^-?\d+$/.test(s)) {
+    return `"${s.replace(/"/g, '\\"')}"`;
+  }
+  return s;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Validation
+// ─────────────────────────────────────────────────────────────────────────────
+
+const VALID_STATUSES = ['in-progress', 'closed', 'abandoned'];
+
+/**
+ * Validates an initiative frontmatter object against the schema.
+ * Returns { ok: true } or { ok: false, errors: [{ path, message }] }.
+ */
+function validateFrontmatter(fm) {
+  const errors = [];
+  const slug = /^[a-z][a-z0-9-]*$/;
+  const date = /^\d{4}-\d{2}-\d{2}$/;
+
+  if (fm === null || typeof fm !== 'object' || Array.isArray(fm)) {
+    return { ok: false, errors: [{ path: '$', message: 'frontmatter must be an object' }] };
+  }
+  if (!Number.isInteger(fm.id) || fm.id < 1) {
+    errors.push({ path: '$.id', message: 'must be a positive integer' });
+  }
+  if (typeof fm.slug !== 'string' || !slug.test(fm.slug)) {
+    errors.push({ path: '$.slug', message: 'must match /^[a-z][a-z0-9-]*$/' });
+  }
+  if (typeof fm.status !== 'string' || !VALID_STATUSES.includes(fm.status)) {
+    errors.push({ path: '$.status', message: `must be one of: ${VALID_STATUSES.join(', ')}` });
+  }
+  if (typeof fm.started !== 'string' || !date.test(fm.started)) {
+    errors.push({ path: '$.started', message: 'must be ISO-8601 date YYYY-MM-DD' });
+  }
+  if (fm.status === 'closed') {
+    if (typeof fm.closed !== 'string' || !date.test(fm.closed)) {
+      errors.push({ path: '$.closed', message: 'required when status=closed' });
+    }
+  }
+  if (typeof fm.owner !== 'string' || fm.owner.length === 0) {
+    errors.push({ path: '$.owner', message: 'required non-empty string' });
+  }
+  if (!Array.isArray(fm.repos) || fm.repos.length === 0 || !fm.repos.every((s) => typeof s === 'string')) {
+    errors.push({ path: '$.repos', message: 'required non-empty array of strings' });
+  }
+  return errors.length === 0 ? { ok: true } : { ok: false, errors };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// File operations
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Discover the next available initiative id by scanning filenames in
+ * <ecosystem-root>/initiatives/. Pure function over directory contents.
+ */
+function nextInitiativeId(ecosystemRoot) {
+  const dir = path.join(ecosystemRoot, INITIATIVES_DIR);
+  if (!fs.existsSync(dir)) return 1;
+  const entries = fs.readdirSync(dir);
+  let max = 0;
+  for (const name of entries) {
+    const m = name.match(/^(\d{4})-[a-z][a-z0-9-]*\.md$/);
+    if (m) {
+      const n = parseInt(m[1], 10);
+      if (n > max) max = n;
+    }
+  }
+  return max + 1;
+}
+
+function initiativeFilename(id, slug) {
+  const padded = String(id).padStart(4, '0');
+  return `${padded}-${slug}.md`;
+}
+
+function initiativePath(ecosystemRoot, id, slug) {
+  return path.join(ecosystemRoot, INITIATIVES_DIR, initiativeFilename(id, slug));
+}
+
+/**
+ * Read + parse an initiative by slug. Searches by filename suffix.
+ * Returns { frontmatter, content, filePath } or null if not found.
+ */
+function loadInitiative(ecosystemRoot, slug) {
+  const dir = path.join(ecosystemRoot, INITIATIVES_DIR);
+  if (!fs.existsSync(dir)) return null;
+  const entries = fs.readdirSync(dir);
+  const match = entries.find((name) => name.endsWith(`-${slug}.md`));
+  if (!match) return null;
+  const filePath = path.join(dir, match);
+  const raw = fs.readFileSync(filePath, 'utf8');
+  const { frontmatter, content } = parseFrontmatter(raw);
+  return { frontmatter, content, filePath };
+}
+
+/**
+ * Write an initiative file. Caller passes already-validated frontmatter
+ * + content. The fenced YAML block is regenerated; content is preserved
+ * verbatim below the closing fence.
+ */
+function writeInitiative(filePath, frontmatter, content) {
+  const v = validateFrontmatter(frontmatter);
+  if (!v.ok) {
+    throw new Error(
+      `writeInitiative: frontmatter validation failed:\n` +
+      v.errors.map((e) => `  ${e.path}: ${e.message}`).join('\n'),
+    );
+  }
+  const fm = serializeFrontmatter(frontmatter);
+  const body = content == null ? '' : content;
+  fs.writeFileSync(filePath, fm + body, 'utf8');
+}
+
+/**
+ * Set the active initiative for the ecosystem. Empty string clears.
+ */
+function setActive(ecosystemRoot, slug) {
+  fs.mkdirSync(path.join(ecosystemRoot, STATE_DIR), { recursive: true });
+  fs.writeFileSync(
+    path.join(ecosystemRoot, STATE_DIR, ACTIVE_FILE),
+    slug == null ? '' : String(slug),
+    'utf8',
+  );
+}
+
+function getActive(ecosystemRoot) {
+  const file = path.join(ecosystemRoot, STATE_DIR, ACTIVE_FILE);
+  if (!fs.existsSync(file)) return null;
+  const s = fs.readFileSync(file, 'utf8').trim();
+  return s || null;
+}
+
+function clearActive(ecosystemRoot) {
+  setActive(ecosystemRoot, '');
+}
+
+module.exports = {
+  INITIATIVES_DIR,
+  STATE_DIR,
+  ACTIVE_FILE,
+  parseFrontmatter,
+  serializeFrontmatter,
+  validateFrontmatter,
+  nextInitiativeId,
+  initiativeFilename,
+  initiativePath,
+  loadInitiative,
+  writeInitiative,
+  setActive,
+  getActive,
+  clearActive,
+};

package/core/ecosystem/lib/pointer.js

@@ -0,0 +1,198 @@
+'use strict';
+
+/**
+ * Pointer block helpers — extracted from bin/ecosystem.js so that
+ * `momentum join` / `momentum leave` (Phase 10 Group 1) can reuse the
+ * same primitives without duplicating logic.
+ *
+ * A pointer block is a sentinel-fenced markdown stanza injected at the
+ * top of a member repo's primary instruction file (CLAUDE.md / AGENTS.md)
+ * telling agents working *inside* the member that the repo is part of
+ * an ecosystem, what to do for cross-repo work, and which orchestration
+ * primitives are available. It is the only touch the ecosystem layer
+ * makes on a member repo — strictly additive.
+ *
+ * The block is versioned via the BEGIN sentinel:
+ *   `<!-- ecosystem:begin v=2 -->`  ← what we WRITE today
+ *   `<!-- ecosystem:begin -->`      ← legacy (v1) — auto-migrated on next touch
+ *
+ * Phase 15 / ENH-032: bumped to v2. The v1 block was information-only
+ * ("Member of X ecosystem at ../X."). v2 is action-bearing — it lists
+ * the orchestration primitives and the cross-repo routing rule
+ * ("write an initiative; never plan cross-repo features here") so an
+ * agent reading the member's primary instruction immediately knows
+ * how to engage with the ecosystem layer.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const POINTER_VERSION = 2;
+const POINTER_BEGIN = `<!-- ecosystem:begin v=${POINTER_VERSION} -->`;
+const POINTER_END = '<!-- ecosystem:end -->';
+
+// Loose substring used to DETECT any pointer block (any version).
+// The literal v=2 sentinel above is what we WRITE; for detection we
+// match the version-less prefix so we can find + migrate v1 blocks.
+const POINTER_BEGIN_PREFIX = '<!-- ecosystem:begin';
+// Regex covers both `<!-- ecosystem:begin -->` and `<!-- ecosystem:begin v=N -->`.
+const POINTER_BEGIN_RE = /<!-- ecosystem:begin(?:\s+v=(\d+))?\s*-->/;
+// Match a full block (BEGIN…END) regardless of version. Used by strip
+// + replace. The `[\s\S]*?` middle is non-greedy so multiple blocks
+// on the same file don't bleed.
+const POINTER_BLOCK_RE = /<!-- ecosystem:begin(?:\s+v=\d+)?\s*-->[\s\S]*?<!-- ecosystem:end -->/g;
+
+// Order matters: prefer CLAUDE.md over AGENTS.md when both exist.
+// Future adapters can extend this via the adapter contract (Phase 11+).
+const PRIMARY_INSTRUCTION_CANDIDATES = ['CLAUDE.md', 'AGENTS.md'];
+
+/**
+ * Locate the primary instruction file in a member repo by checking
+ * the candidate list in order. Returns the filename (relative) or null.
+ */
+function findPrimaryInstructionFile(repoPath) {
+  for (const name of PRIMARY_INSTRUCTION_CANDIDATES) {
+    if (fs.existsSync(path.join(repoPath, name))) {
+      return name;
+    }
+  }
+  return null;
+}
+
+/**
+ * True iff `repoPath` has a primary instruction file containing a
+ * pointer block (any version). Returns false on missing file,
+ * unreadable file, or absent sentinel.
+ */
+function hasPointerBlock(repoPath) {
+  const primary = findPrimaryInstructionFile(repoPath);
+  if (!primary) return false;
+  try {
+    const content = fs.readFileSync(path.join(repoPath, primary), 'utf8');
+    return content.includes(POINTER_BEGIN_PREFIX);
+  } catch (_err) {
+    return false;
+  }
+}
+
+/**
+ * Render the v2 pointer-block contents (no surrounding sentinels).
+ * Exported for tests; also used internally by ensurePointerInjected.
+ */
+function renderPointerBody(ecosystemName, relFromMember) {
+  return [
+    `> **Member of \`${ecosystemName}\` ecosystem** at \`${relFromMember}\`.`,
+    `>`,
+    `> **Cross-repo work?** Write an initiative — never plan cross-repo features in this repo:`,
+    `> \`${relFromMember}/initiatives/<NNNN-slug>.md\` (or \`/initiative create <slug>\`)`,
+    `>`,
+    `> Orchestration primitives (run from this repo or the ecosystem root):`,
+    `> - \`/scout <repo>\` — read another member's state`,
+    `> - \`/dispatch <r1> <r2> "..."\` — parallel multi-repo investigation (slash command — \`momentum dispatch\` CLI is keyword-only)`,
+    `> - \`/handoff <repo>\` — transfer context to another member`,
+    `> - \`/continue\` — resume from an inbox handoff`,
+    `>`,
+    `> See siblings + live state: \`momentum ecosystem status\``,
+  ].join('\n');
+}
+
+/**
+ * Inject the pointer block immediately after the first H1 in the
+ * primary instruction file, or at the top of file if no H1 exists.
+ *
+ * Behaviour by current state:
+ *   - No pointer block      → insert v=POINTER_VERSION block.
+ *   - Pointer block, version < POINTER_VERSION  → migrate in place
+ *     (replace the entire block contents with the current version).
+ *     This is what closes ENH-032 for already-registered members:
+ *     the next time `momentum ecosystem add` runs against them
+ *     (idempotent re-add, or a fresh add of a different member that
+ *     touches the file), the old info-only block is silently upgraded
+ *     to the action-bearing v2 form.
+ *   - Pointer block, version == POINTER_VERSION → no-op.
+ *
+ * `absRepo` — absolute path to the member repo.
+ * `primaryFile` — filename returned by findPrimaryInstructionFile.
+ * `root` — absolute path to the ecosystem root.
+ * `ecosystemName` — manifest name (used in the human-readable line).
+ */
+function ensurePointerInjected(absRepo, primaryFile, root, ecosystemName) {
+  const filePath = path.join(absRepo, primaryFile);
+  const original = fs.readFileSync(filePath, 'utf8');
+  const relFromMember = path.relative(absRepo, root) || '.';
+  const body = renderPointerBody(ecosystemName, relFromMember);
+  const fullBlock = `${POINTER_BEGIN}\n${body}\n${POINTER_END}`;
+
+  const match = original.match(POINTER_BEGIN_RE);
+  if (match) {
+    // A pointer block exists. Inspect its version.
+    const existingVersion = match[1] ? parseInt(match[1], 10) : 1;
+    if (existingVersion >= POINTER_VERSION) {
+      // Up-to-date — preserve as-is (and respect any user edits inside).
+      return;
+    }
+    // Migrate in place: replace the FIRST block with the new block.
+    let replaced = false;
+    const next = original.replace(POINTER_BLOCK_RE, (m) => {
+      if (replaced) return m;
+      replaced = true;
+      return fullBlock;
+    });
+    fs.writeFileSync(filePath, next, 'utf8');
+    return;
+  }
+
+  // No pointer block — insert after first H1 (or at top).
+  const insertion = `\n${fullBlock}\n`;
+  const lines = original.split('\n');
+  let insertAt = 0;
+  for (let i = 0; i < lines.length; i++) {
+    if (/^#\s+/.test(lines[i])) {
+      insertAt = i + 1;
+      break;
+    }
+  }
+  const next = lines
+    .slice(0, insertAt)
+    .concat(insertion.split('\n').slice(0, -1), lines.slice(insertAt))
+    .join('\n');
+  fs.writeFileSync(filePath, next, 'utf8');
+}
+
+/**
+ * Strip the pointer block (any version) and one surrounding blank
+ * line from the given file. Idempotent: silently no-ops if the file
+ * is missing or no pointer block is present.
+ */
+function stripPointer(filePath) {
+  if (!fs.existsSync(filePath)) return;
+  const original = fs.readFileSync(filePath, 'utf8');
+  if (!original.includes(POINTER_BEGIN_PREFIX)) return;
+  // Match leading newline (if any) + the full block + trailing newline
+  // (if any). The BLOCK_RE alone doesn't grab the wrapping whitespace,
+  // so we wrap it with optional newlines here.
+  const re = new RegExp(
+    `\\n?${POINTER_BLOCK_RE.source}\\n?`,
+    'g',
+  );
+  fs.writeFileSync(filePath, original.replace(re, '\n'), 'utf8');
+}
+
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+module.exports = {
+  POINTER_VERSION,
+  POINTER_BEGIN,
+  POINTER_END,
+  POINTER_BEGIN_PREFIX,
+  POINTER_BEGIN_RE,
+  POINTER_BLOCK_RE,
+  PRIMARY_INSTRUCTION_CANDIDATES,
+  findPrimaryInstructionFile,
+  hasPointerBlock,
+  ensurePointerInjected,
+  stripPointer,
+  renderPointerBody,
+};