@pleri/olam-cli 0.1.7

package/host-cp/src/plan-progress.mjs

@@ -0,0 +1,282 @@
+/**
+ * Plan progress parser — reads phase-*-tasks.md trackers to derive
+ * phase/task state for the inbox progress bar.
+ *
+ * @module plan-progress
+ */
+
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+
+const WORKING_THRESHOLD_MS = 10 * 60 * 1000; // 10 minutes
+
+/**
+ * Parse simple key:value pairs from a YAML frontmatter block (---…---).
+ * Handles single-line scalar values only — enough for feature/phase keys.
+ *
+ * @param {string} content
+ * @returns {Record<string, string>}
+ */
+function parseFrontmatter(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return {};
+  const result = {};
+  for (const line of match[1].split('\n')) {
+    const m = line.match(/^([\w-]+):\s*(.+)$/);
+    if (m) result[m[1]] = m[2].trim();
+  }
+  return result;
+}
+
+/**
+ * Extract task definitions from "## Task list" section.
+ * Matches headings like:
+ *   ### A0 — name
+ *   ### B1 step 5 — multi-part name
+ *
+ * @param {string} content
+ * @returns {Array<{id: string, name: string}>}
+ */
+function extractTaskDefs(content) {
+  const sectionMatch = content.match(/^## Task list\s*\n([\s\S]*)/m);
+  if (!sectionMatch) return [];
+
+  const taskSection = sectionMatch[1];
+  const tasks = [];
+  const re = /^###\s+([A-Z]\d+)\b([^\n]*)/gm;
+  let m;
+  while ((m = re.exec(taskSection)) !== null) {
+    const id = m[1];
+    const rest = m[2].trim();
+    // Strip leading em-dash, double-hyphen, or plain hyphen separator
+    const name = rest.replace(/^\s*[—\-]{1,2}\s*/, '').trim() || id;
+    tasks.push({ id, name });
+  }
+  return tasks;
+}
+
+/**
+ * Extract completed task IDs from the CP0 log comment block.
+ * Matches lines like: A0 (2026-05-05): ...
+ *                      A2 (2026-05-05, rebase): ...
+ *
+ * @param {string} content
+ * @returns {Set<string>}
+ */
+function extractCp0Completed(content) {
+  const completed = new Set();
+  const logMatch = content.match(/<!--\s*CP0 log[\s\S]*?-->/);
+  if (!logMatch) return completed;
+
+  const re = /^([A-Z]\d+)\s*\(/gm;
+  let m;
+  while ((m = re.exec(logMatch[0])) !== null) {
+    completed.add(m[1]);
+  }
+  return completed;
+}
+
+/**
+ * Extract completed task IDs from an item-format Status table.
+ * Matches rows like: | A1 | Tool loader index | done |
+ *
+ * @param {string} content
+ * @returns {Set<string>}
+ */
+function extractItemTableCompleted(content) {
+  const completed = new Set();
+  // No `m` flag — `$` must mean end-of-string so the lazy quantifier captures
+  // the whole table, not just the first line.
+  const statusMatch = content.match(/## Status\s*\n([\s\S]*?)(?=\n##\s|$)/);
+  if (!statusMatch) return completed;
+
+  const re = /^\|\s*([A-Z]\d+)\s*\|[^|]+\|\s*done\s*\|/gim;
+  let m;
+  while ((m = re.exec(statusMatch[1])) !== null) {
+    completed.add(m[1]);
+  }
+  return completed;
+}
+
+/**
+ * Extract the authoritative done count from a count-format Status table.
+ * Matches rows like: | done | 3 |
+ *
+ * @param {string} content
+ * @returns {number|null}
+ */
+function extractDoneCount(content) {
+  const m = content.match(/\|\s*done\s*\|\s*(\d+)\s*\|/i);
+  return m ? parseInt(m[1], 10) : null;
+}
+
+/**
+ * Resolve the feature slug from a branch name or by scanning docs/plans/.
+ *
+ * Strategy:
+ *   1. Strip "feat/" prefix + optional "-phase-X" suffix from branch.
+ *   2. Exact match against plans subdirectory names.
+ *   3. Prefix match (branch slug starts with a plan dir name).
+ *   4. Fallback: most-recently-modified plans dir that has phase trackers.
+ *
+ * @param {string} repoPath - path to the git checkout
+ * @param {string|null} branch
+ * @returns {string|null}
+ */
+function resolveFeatureSlug(repoPath, branch) {
+  const plansDir = path.join(repoPath, 'docs', 'plans');
+  let entries;
+  try {
+    entries = readdirSync(plansDir, { withFileTypes: true })
+      .filter((d) => d.isDirectory())
+      .map((d) => d.name);
+  } catch {
+    return null;
+  }
+
+  if (branch) {
+    // Strip feat/ prefix, any nested path, and trailing -phase-X suffix
+    const slug = branch
+      .replace(/^feat\//, '')
+      .replace(/\/.*$/, '')
+      .replace(/-phase-[a-z]$/, '');
+
+    // Exact match
+    if (entries.includes(slug)) return slug;
+
+    // Prefix match (slug starts with a plan dir name)
+    const prefixMatch = entries.find((d) => slug.startsWith(d));
+    if (prefixMatch) return prefixMatch;
+
+    // Branch provided but no name match — don't guess
+    return null;
+  }
+
+  // No branch: fallback to most-recently-modified dir with phase tracker files
+  let newest = null;
+  let newestMtime = 0;
+  for (const dir of entries) {
+    const dirPath = path.join(plansDir, dir);
+    try {
+      const files = readdirSync(dirPath);
+      if (!files.some((f) => /^phase-[a-z]-tasks\.md$/.test(f))) continue;
+      const mtime = statSync(dirPath).mtimeMs;
+      if (mtime > newestMtime) {
+        newestMtime = mtime;
+        newest = dir;
+      }
+    } catch {
+      // skip unreadable entries
+    }
+  }
+
+  return newest;
+}
+
+/**
+ * Parse a single phase tracker file into phase/task state.
+ *
+ * @param {string} filePath
+ * @param {boolean} isRecentlyActive - whether the world had recent activity
+ * @param {{ workingMarked: boolean }} state - mutable flag shared across phases
+ * @returns {{ id: string, name: string, status: string, tasks: Array }|null}
+ */
+function parseTrackerFile(filePath, isRecentlyActive, state) {
+  let content;
+  try {
+    content = readFileSync(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+
+  const fm = parseFrontmatter(content);
+
+  // Phase ID: frontmatter "phase" field or filename "phase-X-tasks.md"
+  const phaseId =
+    fm.phase ||
+    path.basename(filePath).match(/^phase-([a-z])-tasks\.md$/)?.[1] ||
+    '?';
+
+  const phaseName = `Phase ${phaseId.toUpperCase()}`;
+
+  const taskDefs = extractTaskDefs(content);
+  if (taskDefs.length === 0) return null;
+
+  // Collect completions from all sources
+  const cp0Completed = extractCp0Completed(content);
+  const itemTableCompleted = extractItemTableCompleted(content);
+  const doneCount = extractDoneCount(content);
+
+  // Merge CP0 log + item-table; count-format overrides if present
+  const mergedCompleted = new Set([...cp0Completed, ...itemTableCompleted]);
+
+  const tasks = taskDefs.map((t, i) => {
+    const isComplete =
+      doneCount !== null
+        ? i < doneCount          // count format is authoritative
+        : mergedCompleted.has(t.id);
+
+    if (isComplete) return { id: t.id, name: t.name, status: 'complete' };
+
+    // First pending task across all phases = candidate for "working"
+    if (!state.workingMarked) {
+      state.workingMarked = true;
+      return {
+        id: t.id,
+        name: t.name,
+        status: isRecentlyActive ? 'working' : 'pending',
+      };
+    }
+
+    return { id: t.id, name: t.name, status: 'pending' };
+  });
+
+  const allComplete = tasks.every((t) => t.status === 'complete');
+  const anyWorking = tasks.some((t) => t.status === 'working');
+  const phaseStatus = allComplete ? 'complete' : anyWorking ? 'working' : 'pending';
+
+  return { id: phaseId, name: phaseName, status: phaseStatus, tasks };
+}
+
+/**
+ * Read plan progress from a world's git checkout.
+ *
+ * @param {string} repoPath - absolute path to the git checkout
+ * @param {string|null} branch - current branch name (e.g. "feat/foo-phase-a")
+ * @param {{ lastActivityAtMs?: number|null }} [opts]
+ * @returns {{ feature: string, phases: Array }|null}
+ *   null when no plan tracker is found (caller falls back to legacy bar)
+ */
+export function readPlanProgress(repoPath, branch, { lastActivityAtMs = null } = {}) {
+  const feature = resolveFeatureSlug(repoPath, branch);
+  if (!feature) return null;
+
+  const plansDir = path.join(repoPath, 'docs', 'plans', feature);
+  let phaseFiles;
+  try {
+    phaseFiles = readdirSync(plansDir)
+      .filter((f) => /^phase-[a-z]-tasks\.md$/.test(f))
+      .sort();
+  } catch {
+    return null;
+  }
+
+  if (phaseFiles.length === 0) return null;
+
+  const isRecentlyActive =
+    lastActivityAtMs != null
+      ? Date.now() - lastActivityAtMs <= WORKING_THRESHOLD_MS
+      : false;
+
+  const state = { workingMarked: false };
+
+  const phases = phaseFiles
+    .map((file) =>
+      parseTrackerFile(path.join(plansDir, file), isRecentlyActive, state),
+    )
+    .filter(Boolean);
+
+  if (phases.length === 0) return null;
+
+  return { feature, phases };
+}

package/host-cp/src/pr-cache.mjs

@@ -0,0 +1,201 @@
+/**
+ * In-memory cache for GitHub PR data with TTL and concurrent-fetch coalescing.
+ *
+ * @module pr-cache
+ */
+
+const GH_API_BASE = 'https://api.github.com';
+const TTL_MS = 30_000;
+
+/**
+ * Parse owner, repo, and PR number from a GitHub PR URL.
+ *
+ * @param {string} prUrl e.g. https://github.com/owner/repo/pull/123
+ * @returns {{ owner: string, repo: string, number: number } | null}
+ */
+function parsePrUrl(prUrl) {
+  const m = /github\.com\/([^/]+)\/([^/]+)\/pull\/(\d+)/.exec(prUrl);
+  if (!m) return null;
+  return { owner: m[1], repo: m[2], number: parseInt(m[3], 10) };
+}
+
+/**
+ * Reduce an array of check runs into a single status string.
+ *
+ * @param {Array<{conclusion: string|null, status: string}>} checkRuns
+ * @returns {'pending'|'passing'|'failing'|null}
+ */
+function reduceCheckRuns(checkRuns) {
+  if (!checkRuns || checkRuns.length === 0) return null;
+
+  let hasFailure = false;
+  let hasPending = false;
+
+  for (const run of checkRuns) {
+    const conclusion = run.conclusion;
+    const status = run.status;
+
+    if (
+      conclusion === 'failure' ||
+      conclusion === 'timed_out' ||
+      conclusion === 'action_required'
+    ) {
+      hasFailure = true;
+    } else if (
+      status === 'queued' ||
+      status === 'in_progress' ||
+      conclusion === null
+    ) {
+      hasPending = true;
+    }
+  }
+
+  if (hasFailure) return 'failing';
+  if (hasPending) return 'pending';
+  return 'passing';
+}
+
+/**
+ * @typedef {object} PrCacheEntry
+ * @property {number} fetchedAt
+ * @property {'open'|'merged'|'closed'|null} prState
+ * @property {number|null} prNumber
+ * @property {'pending'|'passing'|'failing'|null} prChecks
+ * @property {Promise<PrData>|null} promise
+ */
+
+/**
+ * @typedef {object} PrData
+ * @property {'open'|'merged'|'closed'|null} state
+ * @property {number|null} number
+ * @property {'pending'|'passing'|'failing'|null} checks
+ */
+
+/**
+ * Fetch PR data from GitHub API.
+ *
+ * @param {string} prUrl
+ * @param {() => Promise<string|null>} getToken
+ * @returns {Promise<PrData>}
+ */
+async function fetchPrData(prUrl, getToken) {
+  const parsed = parsePrUrl(prUrl);
+  if (!parsed) return { state: null, number: null, checks: null };
+
+  const token = await getToken();
+  /** @type {HeadersInit} */
+  const headers = { Accept: 'application/vnd.github+json' };
+  if (token) headers['Authorization'] = `token ${token}`;
+
+  // Fetch PR metadata
+  const prResp = await fetch(
+    `${GH_API_BASE}/repos/${parsed.owner}/${parsed.repo}/pulls/${parsed.number}`,
+    { headers, signal: AbortSignal.timeout(10_000) },
+  );
+  if (!prResp.ok) {
+    return { state: null, number: parsed.number, checks: null };
+  }
+  const prData = await prResp.json();
+
+  let state = prData.state ?? null;
+  if (state === 'closed' && prData.merged_at) state = 'merged';
+
+  const sha = prData.head?.sha ?? null;
+  if (!sha) {
+    return { state, number: parsed.number, checks: null };
+  }
+
+  // Fetch check runs for the head SHA
+  let checks = null;
+  try {
+    const checksResp = await fetch(
+      `${GH_API_BASE}/repos/${parsed.owner}/${parsed.repo}/commits/${sha}/check-runs`,
+      { headers, signal: AbortSignal.timeout(10_000) },
+    );
+    if (checksResp.ok) {
+      const checksData = await checksResp.json();
+      const runs = Array.isArray(checksData.check_runs) ? checksData.check_runs : [];
+      checks = reduceCheckRuns(runs);
+    }
+  } catch {
+    // Non-fatal — return null checks
+  }
+
+  return { state, number: parsed.number, checks };
+}
+
+/**
+ * Create a PR data cache with TTL and concurrent-fetch coalescing.
+ *
+ * @returns {{ getPr: (prUrl: string, getToken: () => Promise<string|null>) => Promise<PrData|null> }}
+ */
+export function createPrCache() {
+  /** @type {Map<string, PrCacheEntry>} */
+  const cache = new Map();
+
+  /**
+   * Get PR data for a URL, using cache if fresh or coalescing concurrent fetches.
+   *
+   * @param {string} prUrl
+   * @param {() => Promise<string|null>} getToken
+   * @returns {Promise<PrData|null>}
+   */
+  async function getPr(prUrl, getToken) {
+    if (!prUrl) return null;
+
+    const now = Date.now();
+    const entry = cache.get(prUrl);
+
+    // Fresh cache hit
+    if (entry && !entry.promise && now - entry.fetchedAt < TTL_MS) {
+      return { state: entry.prState, number: entry.prNumber, checks: entry.prChecks };
+    }
+
+    // In-flight fetch — coalesce
+    if (entry && entry.promise) {
+      try {
+        return await entry.promise;
+      } catch {
+        return null;
+      }
+    }
+
+    // Stale or missing — start new fetch
+    const promise = fetchPrData(prUrl, getToken).then(
+      (data) => {
+        cache.set(prUrl, {
+          fetchedAt: Date.now(),
+          prState: data.state,
+          prNumber: data.number,
+          prChecks: data.checks,
+          promise: null,
+        });
+        return data;
+      },
+      (err) => {
+        // Clear promise on error so next call retries
+        const current = cache.get(prUrl);
+        if (current && current.promise) {
+          cache.set(prUrl, { ...current, promise: null });
+        }
+        throw err;
+      },
+    );
+
+    cache.set(prUrl, {
+      fetchedAt: entry ? entry.fetchedAt : 0,
+      prState: entry ? entry.prState : null,
+      prNumber: entry ? entry.prNumber : null,
+      prChecks: entry ? entry.prChecks : null,
+      promise,
+    });
+
+    try {
+      return await promise;
+    } catch {
+      return null;
+    }
+  }
+
+  return { getPr };
+}

package/host-cp/src/pr-merge-poller.mjs

@@ -0,0 +1,154 @@
+/**
+ * PR merge poller for auto-destroying worlds whose PR has merged.
+ *
+ * State machine per world:
+ *   open -> merged (on GitHub reports merged)
+ *   merged -> merged_destroyed (after grace period, if auto_destroy_on_merge)
+ */
+
+const GH_API_BASE = 'https://api.github.com';
+
+/**
+ * Parse owner, repo, and PR number from a GitHub PR URL.
+ * @param {string} prUrl e.g. https://github.com/org/repo/pull/123
+ * @returns {{ owner: string, repo: string, number: number } | null}
+ */
+function parsePrUrl(prUrl) {
+  const m = /github\.com\/([^/]+)\/([^/]+)\/pull\/(\d+)/.exec(prUrl);
+  if (!m) return null;
+  return { owner: m[1], repo: m[2], number: parseInt(m[3], 10) };
+}
+
+/**
+ * @param {{
+ *   prStateStore: import('./world-pr-state.mjs').ReturnType<typeof createWorldPrStateStore>,
+ *   getGhToken: () => Promise<string|null>,
+ *   destroyWorld: (worldId: string) => Promise<void>,
+ *   pollIntervalMs?: number,
+ *   gracePeriodMs?: number,
+ * }} opts
+ */
+export function createPrMergePoller({
+  prStateStore,
+  getGhToken,
+  destroyWorld,
+  pollIntervalMs = 300_000,
+  gracePeriodMs = 600_000,
+}) {
+  let intervalId = null;
+  let disabled = false;
+  let warnedOnce = false;
+  // Track in-flight grace timers so stop() can clear them
+  const graceTimers = new Map();
+
+  async function destroyAndMark(worldId) {
+    const entry = prStateStore.get(worldId);
+    const prUrl = entry?.pr_url ?? '(unknown)';
+    const mergedAt = entry?.pr_merged_at ?? '(unknown)';
+    console.log(
+      `[pr-merge-poller] auto-destroyed world ${worldId}: PR ${prUrl} merged at ${mergedAt}, destroyed at ${new Date().toISOString()}`,
+    );
+    try {
+      await destroyWorld(worldId);
+    } catch (err) {
+      console.error(`[pr-merge-poller] destroyWorld failed for ${worldId}:`, err.message);
+    }
+    prStateStore.set(worldId, { pr_state: 'merged_destroyed' });
+    graceTimers.delete(worldId);
+  }
+
+  function scheduleGrace(worldId, entry) {
+    if (graceTimers.has(worldId)) return; // already scheduled
+    const id = setTimeout(() => {
+      destroyAndMark(worldId).catch((err) => {
+        console.error(`[pr-merge-poller] destroyAndMark error for ${worldId}:`, err.message);
+      });
+    }, gracePeriodMs);
+    graceTimers.set(worldId, id);
+  }
+
+  async function checkPr(worldId, entry, ghToken) {
+    const parsed = parsePrUrl(entry.pr_url);
+    if (!parsed) {
+      console.warn(`[pr-merge-poller] cannot parse PR URL for ${worldId}: ${entry.pr_url}`);
+      return;
+    }
+    const apiUrl = `${GH_API_BASE}/repos/${parsed.owner}/${parsed.repo}/pulls/${parsed.number}`;
+    let data;
+    try {
+      const resp = await fetch(apiUrl, {
+        headers: { Authorization: `token ${ghToken}`, Accept: 'application/vnd.github+json' },
+      });
+      if (!resp.ok) {
+        console.warn(`[pr-merge-poller] GH API ${resp.status} for ${worldId}`);
+        return;
+      }
+      data = await resp.json();
+    } catch (err) {
+      console.warn(`[pr-merge-poller] fetch failed for ${worldId}:`, err.message);
+      return;
+    }
+
+    const isMerged = data.state === 'closed' && data.merged_at != null;
+    if (!isMerged) return;
+
+    prStateStore.set(worldId, {
+      pr_state: 'merged',
+      pr_merged_at: data.merged_at,
+    });
+
+    if (entry.auto_destroy_on_merge === false) return;
+
+    scheduleGrace(worldId, prStateStore.get(worldId));
+  }
+
+  async function pollOnce() {
+    const ghToken = await getGhToken();
+    if (!ghToken) {
+      if (!warnedOnce) {
+        console.warn(
+          'pr-merge-poller: no GH token found (GH_TOKEN/GITHUB_TOKEN env or /gh-config/hosts.yml); PR polling disabled',
+        );
+        warnedOnce = true;
+      }
+      disabled = true;
+      stop();
+      return;
+    }
+
+    const worlds = prStateStore.getWorldsToWatch();
+    for (const entry of worlds) {
+      const { worldId, ...rest } = entry;
+      if (rest.pr_state === 'open') {
+        await checkPr(worldId, rest, ghToken);
+      } else if (rest.pr_state === 'merged') {
+        // Resume grace timer for merged entries that survived a restart
+        if (rest.auto_destroy_on_merge !== false) {
+          scheduleGrace(worldId, rest);
+        }
+      }
+    }
+  }
+
+  function start() {
+    if (intervalId !== null || disabled) return;
+    intervalId = setInterval(() => {
+      pollOnce().catch((err) => {
+        console.error('[pr-merge-poller] pollOnce error:', err.message);
+      });
+    }, pollIntervalMs);
+  }
+
+  function stop() {
+    if (intervalId !== null) {
+      clearInterval(intervalId);
+      intervalId = null;
+    }
+    for (const id of graceTimers.values()) {
+      clearTimeout(id);
+    }
+    graceTimers.clear();
+  }
+
+  return { start, stop };
+}