runlist 0.0.0 → 0.94.1

package/src/state-migration.mjs

@@ -0,0 +1,123 @@
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  rmSync,
+  rmdirSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import path from 'node:path';
+import { processOwnerLiveness } from './atomic-mutation.mjs';
+import { LEGACY_STATE_DIR, STATE_DIR } from './naming.mjs';
+
+export { stateDir } from './naming.mjs';
+
+const MIGRATION_MARKER = 'migrated-from-dotmd.json';
+const DROP_ENTRIES = new Set(['handoffs']);
+const TERMINAL_TRANSACTION_STATUSES = new Set(['committed', 'rolled-back', 'failed-manual']);
+
+function heldLocks(lockRoot) {
+  if (!existsSync(lockRoot)) return [];
+  let entries;
+  try { entries = readdirSync(lockRoot); }
+  catch { return [{ lock: path.basename(lockRoot), status: 'unreadable-directory' }]; }
+  const held = [];
+  for (const entry of entries) {
+    const ownerPath = path.join(lockRoot, entry, 'owner.json');
+    if (!existsSync(ownerPath)) {
+      held.push({ lock: entry, status: 'owner-missing' });
+      continue;
+    }
+    let owner;
+    try { owner = JSON.parse(readFileSync(ownerPath, 'utf8')); }
+    catch {
+      held.push({ lock: entry, status: 'owner-unreadable' });
+      continue;
+    }
+    if (processOwnerLiveness(owner) !== 'dead') {
+      held.push({ lock: entry, status: 'held-or-unverifiable', pid: owner.pid, hostname: owner.hostname });
+    }
+  }
+  return held;
+}
+
+function unresolvedTransactions(transactionRoot) {
+  if (!existsSync(transactionRoot)) return [];
+  let entries;
+  try { entries = readdirSync(transactionRoot); }
+  catch { return [{ id: path.basename(transactionRoot), status: 'unreadable-directory' }]; }
+  const open = [];
+  for (const entry of entries) {
+    const manifestPath = path.join(transactionRoot, entry, 'manifest.json');
+    if (!existsSync(manifestPath)) {
+      open.push({ id: entry, status: 'manifest-missing' });
+      continue;
+    }
+    let manifest;
+    try { manifest = JSON.parse(readFileSync(manifestPath, 'utf8')); }
+    catch { open.push({ id: entry, status: 'unreadable' }); continue; }
+    if (!TERMINAL_TRANSACTION_STATUSES.has(manifest.status)) {
+      open.push({ id: entry, status: manifest.status ?? 'unknown' });
+    }
+  }
+  return open;
+}
+
+function moveEntry(from, to) {
+  if (existsSync(to)) {
+    if (statSync(to).isDirectory() && statSync(from).isDirectory()) {
+      for (const child of readdirSync(from)) moveEntry(path.join(from, child), path.join(to, child));
+      rmSync(from, { recursive: true, force: true });
+      return;
+    }
+    // Current state wins an exact-name collision. The legacy copy is stale by
+    // definition and retaining both would make the next migration ambiguous.
+    rmSync(from, { recursive: true, force: true });
+    return;
+  }
+  renameSync(from, to);
+}
+
+export function migrateStateDirectory(repoRoot, options = {}) {
+  const root = path.resolve(repoRoot);
+  const from = path.join(root, LEGACY_STATE_DIR);
+  const to = path.join(root, STATE_DIR);
+  if (!existsSync(from)) return { status: 'noop', reason: 'nothing-to-migrate', from, to };
+
+  const held = heldLocks(path.join(from, 'locks'));
+  if (held.length) {
+    return {
+      status: 'refused', reason: 'locks-held', detail: held, from, to,
+      message: `Legacy state has ${held.length} lock${held.length === 1 ? '' : 's'} that ${held.length === 1 ? 'is' : 'are'} not provably abandoned. State migration refused; retry after active work finishes or inspect with \`runlist doctor --transactions\`.`,
+    };
+  }
+
+  const open = unresolvedTransactions(path.join(from, 'transactions'));
+  if (open.length) {
+    return {
+      status: 'refused', reason: 'transactions-unresolved', detail: open, from, to,
+      message: `${open.length} transaction${open.length === 1 ? ' is' : 's are'} not terminal (${open.map(item => `${item.id}: ${item.status}`).join(', ')}). State migration refused. Resolve with \`runlist doctor --transactions --apply\`, then retry.`,
+    };
+  }
+
+  if (options.dryRun) return { status: 'noop', reason: 'dry-run', from, to };
+
+  mkdirSync(to, { recursive: true });
+  for (const entry of readdirSync(from)) {
+    if (DROP_ENTRIES.has(entry)) {
+      rmSync(path.join(from, entry), { recursive: true, force: true });
+      continue;
+    }
+    moveEntry(path.join(from, entry), path.join(to, entry));
+  }
+  try { if (readdirSync(from).length === 0) rmdirSync(from); } catch {}
+
+  writeFileSync(
+    path.join(to, MIGRATION_MARKER),
+    JSON.stringify({ from: LEGACY_STATE_DIR, to: STATE_DIR, migratedAt: new Date().toISOString() }, null, 2) + '\n',
+  );
+  return { status: 'migrated', from, to };
+}

package/src/stats.mjs

@@ -0,0 +1,200 @@
+import { capitalize, toSlug, warn } from './util.mjs';
+import { bold, dim } from './color.mjs';
+
+function pct(n, total) {
+  if (!total) return 0;
+  return Math.round((n / total) * 100);
+}
+
+export function buildStats(index, config) {
+  const docs = index.docs;
+  const scope = config.statusOrder.filter(s => !config.lifecycle.terminalStatuses.has(s));
+  for (const typeSet of (config.typeStatuses?.values() ?? [])) {
+    for (const s of typeSet) {
+      if (!config.lifecycle.terminalStatuses.has(s) && !scope.includes(s)) scope.push(s);
+    }
+  }
+  const scoped = docs.filter(d => scope.includes(d.status));
+  const nonArchived = docs.filter(d => !config.lifecycle.skipsWarnings(d.status, d.type));
+
+  // Health
+  const staleCount = nonArchived.filter(d => d.isStale).length;
+  const brokenRefCount = index.errors.filter(e => e.message.includes('does not resolve to an existing file')).length;
+  const brokenLinkCount = index.warnings.filter(w => w.message.startsWith('body link')).length;
+
+  // Freshness
+  const withDays = nonArchived.filter(d => d.daysSinceUpdate != null);
+  const sorted = [...withDays].sort((a, b) => (b.daysSinceUpdate ?? 0) - (a.daysSinceUpdate ?? 0));
+  const oldest = sorted[0] ?? null;
+
+  // Checklists
+  const withChecklists = docs.filter(d => d.checklist?.total > 0);
+  const avgCompletion = withChecklists.length > 0
+    ? Math.round(withChecklists.reduce((sum, d) => sum + (d.checklistCompletionRate ?? 0), 0) / withChecklists.length * 100)
+    : 0;
+  const fullyComplete = withChecklists.filter(d => d.checklistCompletionRate === 1).length;
+  const withOpenItems = withChecklists.filter(d => d.checklist.open > 0).length;
+
+  // Audit
+  const auditCounts = { pass1: 0, pass2: 0, deep: 0 };
+  for (const d of scoped) {
+    if (auditCounts[d.auditLevel] !== undefined) auditCounts[d.auditLevel]++;
+  }
+  const auditedCount = auditCounts.pass1 + auditCounts.pass2 + auditCounts.deep;
+
+  return {
+    generatedAt: new Date().toISOString(),
+    totalDocs: docs.length,
+    countsByStatus: index.countsByStatus,
+    countsByType: index.countsByType ?? {},
+    health: {
+      staleCount,
+      stalePct: pct(staleCount, nonArchived.length),
+      nonArchivedCount: nonArchived.length,
+      errorCount: index.errors.length,
+      warningCount: index.warnings.length,
+      brokenRefCount,
+      brokenLinkCount,
+    },
+    freshness: {
+      today: docs.filter(d => d.daysSinceUpdate === 0).length,
+      thisWeek: docs.filter(d => d.daysSinceUpdate != null && d.daysSinceUpdate <= 7).length,
+      thisMonth: docs.filter(d => d.daysSinceUpdate != null && d.daysSinceUpdate <= 30).length,
+      oldest: oldest ? { path: oldest.path, slug: toSlug(oldest), daysSinceUpdate: oldest.daysSinceUpdate } : null,
+    },
+    completeness: {
+      scoped: scoped.length,
+      hasOwner: scoped.filter(d => d.owner).length,
+      hasSurface: scoped.filter(d => d.surfaces?.length).length,
+      hasModule: scoped.filter(d => d.modules?.length).length,
+      hasNextStep: scoped.filter(d => d.hasNextStep).length,
+    },
+    checklists: {
+      docsWithChecklists: withChecklists.length,
+      avgCompletion,
+      fullyComplete,
+      withOpenItems,
+    },
+    audit: {
+      audited: auditedCount,
+      ...auditCounts,
+    },
+  };
+}
+
+// ── Text renderer ──────────────────────────────────────────────────────
+
+export function renderStats(stats, config) {
+  const defaultRenderer = (s) => _renderStats(s, config);
+  if (!config._execution?.suppressSideEffects && config.hooks.renderStats) {
+    try { return config.hooks.renderStats(stats, defaultRenderer); }
+    catch (err) { warn(`Hook 'renderStats' threw: ${err.message}`); }
+  }
+  return defaultRenderer(stats);
+}
+
+function _renderStats(stats, config) {
+  const lines = [];
+  lines.push(bold(`Stats`) + dim(` — ${stats.totalDocs} docs`));
+  lines.push('');
+
+  // Status. With F6, render one line per type when 2+ types have docs so
+  // `plan/partial` and `doc/partial` (semantically distinct under per-type
+  // taxonomies) don't collapse into one number. Single-type corpora keep the
+  // existing flat line — no needless `Plans:` header on a plans-only repo.
+  lines.push(bold('Status'));
+  const typesWithDocs = Object.entries(stats.countsByType ?? {})
+    .filter(([, statusMap]) => Object.values(statusMap).some(n => n > 0));
+  if (typesWithDocs.length > 1) {
+    // Type order: respect config.validTypes declaration order; unknown last.
+    const typeOrder = [...(config.validTypes ?? [])];
+    const sortedTypes = typesWithDocs.sort(([a], [b]) => {
+      const ai = typeOrder.indexOf(a);
+      const bi = typeOrder.indexOf(b);
+      if (ai === -1 && bi === -1) return a.localeCompare(b);
+      if (ai === -1) return 1;
+      if (bi === -1) return -1;
+      return ai - bi;
+    });
+    const labelFor = (t) => t === 'unknown' ? 'Untyped' : (t.charAt(0).toUpperCase() + t.slice(1) + 's');
+    for (const [type, statusMap] of sortedTypes) {
+      const statusesForType = [
+        ...config.statusOrder.filter(s => statusMap[s]),
+        ...Object.keys(statusMap).filter(s => !config.statusOrder.includes(s)).sort(),
+      ];
+      const parts = statusesForType
+        .filter(s => statusMap[s])
+        .map(s => `${s}: ${statusMap[s]}`);
+      lines.push(`  ${dim(labelFor(type) + ':')} ${parts.join('  ')}`);
+    }
+  } else {
+    const allStatuses = [
+      ...config.statusOrder.filter(s => stats.countsByStatus[s]),
+      ...Object.keys(stats.countsByStatus).filter(s => !config.statusOrder.includes(s)).sort(),
+    ];
+    const statusParts = allStatuses
+      .filter(s => stats.countsByStatus[s])
+      .map(s => `${s}: ${stats.countsByStatus[s]}`);
+    lines.push('  ' + statusParts.join('  '));
+  }
+  lines.push('');
+
+  // Health
+  const h = stats.health;
+  lines.push(bold('Health'));
+  lines.push(`  stale: ${h.staleCount}/${h.nonArchivedCount} (${h.stalePct}%)`);
+  lines.push(`  errors: ${h.errorCount}`);
+  lines.push(`  warnings: ${h.warningCount}`);
+  if (h.brokenRefCount) lines.push(`  broken refs: ${h.brokenRefCount}`);
+  if (h.brokenLinkCount) lines.push(`  broken links: ${h.brokenLinkCount}`);
+  lines.push('');
+
+  // Freshness
+  const f = stats.freshness;
+  lines.push(bold('Freshness'));
+  lines.push(`  updated today: ${f.today}    this week: ${f.thisWeek}    this month: ${f.thisMonth}`);
+  if (f.oldest) {
+    lines.push(`  oldest: ${f.oldest.slug} (${f.oldest.daysSinceUpdate}d)`);
+  }
+  lines.push('');
+
+  // Completeness
+  const c = stats.completeness;
+  if (c.scoped > 0) {
+    lines.push(bold('Completeness') + dim(' (active/ready/planned/blocked)'));
+    lines.push(`  has owner: ${c.hasOwner}/${c.scoped} (${pct(c.hasOwner, c.scoped)}%)`);
+    lines.push(`  has surface: ${c.hasSurface}/${c.scoped} (${pct(c.hasSurface, c.scoped)}%)`);
+    lines.push(`  has module: ${c.hasModule}/${c.scoped} (${pct(c.hasModule, c.scoped)}%)`);
+    lines.push(`  has next_step: ${c.hasNextStep}/${c.scoped} (${pct(c.hasNextStep, c.scoped)}%)`);
+    lines.push('');
+  }
+
+  // Checklists
+  const cl = stats.checklists;
+  if (cl.docsWithChecklists > 0) {
+    lines.push(bold('Checklists'));
+    lines.push(`  docs with checklists: ${cl.docsWithChecklists}`);
+    lines.push(`  avg completion: ${cl.avgCompletion}%`);
+    lines.push(`  fully complete: ${cl.fullyComplete}    open items: ${cl.withOpenItems}`);
+    lines.push('');
+  }
+
+  // Audit
+  const a = stats.audit;
+  if (c.scoped > 0) {
+    lines.push(bold('Audit'));
+    lines.push(`  audited: ${a.audited}/${c.scoped} (${pct(a.audited, c.scoped)}%)`);
+    if (a.audited > 0) {
+      lines.push(`  pass1: ${a.pass1}  pass2: ${a.pass2}  deep: ${a.deep}`);
+    }
+    lines.push('');
+  }
+
+  return `${lines.join('\n').trimEnd()}\n`;
+}
+
+// ── JSON renderer ──────────────────────────────────────────────────────
+
+export function renderStatsJson(stats) {
+  return JSON.stringify(stats, null, 2) + '\n';
+}

package/src/status-metadata.mjs

@@ -0,0 +1,87 @@
+// Ordered, type-aware view of the effective status configuration. Config loading
+// still resolves compatibility overrides; consumers use this module instead of
+// reconstructing behavior from several global/type-specific fields.
+const CACHE = new WeakMap();
+
+export function resolveStatusMetadata(config) {
+  const cached = CACHE.get(config);
+  if (cached) return cached;
+  const byType = {};
+  const typeOrder = [...(config.validTypes ?? [])];
+
+  for (const type of typeOrder) {
+    const statuses = [...(config.typeStatuses?.get(type) ?? [])];
+    const typeDef = config.raw?.types?.[type] ?? {};
+    const context = config.typeContextConfig?.get(type) ?? typeDef.context ?? {};
+    const contextByStatus = new Map();
+    for (const bucket of ['expanded', 'listed', 'counted']) {
+      for (const status of context[bucket] ?? []) {
+        if (!contextByStatus.has(status)) contextByStatus.set(status, bucket);
+      }
+    }
+
+    byType[type] = statuses.map((name, rank) => {
+      const skipStale = config.lifecycle.skipStaleFor.has(name);
+      const skipWarnings = config.lifecycle.skipsWarnings(name, type);
+      const hasTypeStaleDays = Object.prototype.hasOwnProperty.call(typeDef.staleDays ?? {}, name);
+      return {
+        name,
+        rank,
+        context: contextByStatus.get(name) ?? 'counted',
+        staleDays: hasTypeStaleDays ? typeDef.staleDays[name] : (config.staleDaysByStatus?.[name] ?? null),
+        startable: config.lifecycle.startableStatuses.has(name),
+        terminal: config.lifecycle.isTerminal?.(name, type) ?? config.lifecycle.terminalStatuses.has(name),
+        archive: config.lifecycle.archiveStatuses.has(name),
+        filed: config.lifecycle.filedStatuses.get(name) ?? null,
+        skipStale,
+        skipWarnings,
+        quiet: skipStale && skipWarnings,
+        requiresModule: config.moduleRequiredStatuses.has(name),
+      };
+    });
+  }
+
+  const resolved = { typeOrder, byType };
+  CACHE.set(config, resolved);
+  return resolved;
+}
+
+export function statusMetadataFor(config, type, status) {
+  if (!type || !status) return null;
+  return resolveStatusMetadata(config).byType[type]?.find(item => item.name === status) ?? null;
+}
+
+export function statusesForContext(config, type, bucket) {
+  return (resolveStatusMetadata(config).byType[type] ?? [])
+    .filter(item => item.context === bucket)
+    .map(item => item.name);
+}
+
+export function statusHasContext(config, type, status, bucket) {
+  return statusMetadataFor(config, type, status)?.context === bucket;
+}
+
+export function actionablePromptStatuses(config) {
+  const expanded = statusesForContext(config, 'prompt', 'expanded');
+  return new Set(expanded.length > 0 ? expanded : ['pending']);
+}
+
+export function compareStrings(a, b) {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+// Oldest actionable prompt first. Missing dates sort last; path is the stable
+// final tie-breaker shared by HUD, agent-context, and no-arg `runlist use`.
+export function comparePromptDocs(a, b) {
+  const aCreated = a.created ?? '';
+  const bCreated = b.created ?? '';
+  if (aCreated && bCreated && aCreated !== bCreated) return compareStrings(aCreated, bCreated);
+  if (aCreated && !bCreated) return -1;
+  if (!aCreated && bCreated) return 1;
+  const aUpdated = a.updated ?? '';
+  const bUpdated = b.updated ?? '';
+  if (aUpdated && bUpdated && aUpdated !== bUpdated) return compareStrings(aUpdated, bUpdated);
+  if (aUpdated && !bUpdated) return -1;
+  if (!aUpdated && bUpdated) return 1;
+  return compareStrings(a.path ?? '', b.path ?? '');
+}