runlist 0.0.0 → 0.94.2

package/src/modules.mjs

@@ -0,0 +1,355 @@
+// Modules dashboard (F16). Two view-only commands:
+//   `runlist modules`         — one row per discovered module, dynamic status columns
+//   `runlist module <name>`   — plans for one module, grouped by status, stale flagged inline
+//
+// Aggregation lives in `aggregateModules` (pure data). Both renderers consume
+// the same shape, so JSON output and the table share one source of truth.
+//
+// Constraint cheatsheet (see docs/archived/modules-dashboard.md):
+//   M1 dynamic columns      — discover statuses from rendered rows, drop empty cols
+//   M2 overflow fallback    — drop-empty first, then stacked render if still too wide
+//   M3 double-counting      — `modules: [a, b]` increments both rows (intended)
+//   M4 (none) bucket        — surface when ≥1 plan has empty modules
+//   M6 archived/skipStale   — terminal statuses excluded; skipStale don't contribute to `stale`
+import { toSlug, truncate, die, suggestCandidates } from './util.mjs';
+import { bold, dim, yellow, red, green, blue, magenta, cyan, brightYellow } from './color.mjs';
+
+const STATUS_COLORS = {
+  'in-session': (s) => bold(red(s)),
+  'active': green,
+  'planned': blue,
+  'blocked': yellow,
+  'partial': (s) => dim(green(s)),
+  'paused': magenta,
+  'awaiting': brightYellow,
+  'queued-after': (s) => dim(cyan(s)),
+  'archived': dim,
+  'pending': bold,
+  'claimed': dim,
+};
+
+function colorStatus(status, text) {
+  const fn = STATUS_COLORS[status] ?? ((s) => s);
+  return fn(text);
+}
+
+// Single pass over docs → Map<moduleName, aggregate>. Terminal-status docs are
+// excluded entirely (M6) — they pollute the active-work picture. skipStale
+// statuses are counted toward totals but never contribute to `stale` so they
+// don't lie about staleness when a custom config (e.g. `backlog`) opts out.
+export function aggregateModules(docs, config) {
+  const terminal = config.lifecycle.terminalStatuses;
+  const skipStale = config.lifecycle.skipStaleFor;
+  const liveDocs = docs.filter(d => !terminal.has(d.status));
+  const uniqueTotal = liveDocs.length;
+
+  const modules = new Map();
+  function bucket(name) {
+    if (!modules.has(name)) {
+      modules.set(name, {
+        name,
+        plans: [],
+        byStatus: {},
+        stale: 0,
+        ageSum: 0,
+        ageCount: 0,
+        oldest: null,
+        nextStepCount: 0,
+      });
+    }
+    return modules.get(name);
+  }
+
+  for (const doc of liveDocs) {
+    const names = doc.modules?.length ? doc.modules : ['(none)'];
+    for (const name of names) {
+      const m = bucket(name);
+      m.plans.push(doc);
+      m.byStatus[doc.status] = (m.byStatus[doc.status] ?? 0) + 1;
+      if (doc.isStale && !skipStale.has(doc.status)) m.stale += 1;
+      if (typeof doc.daysSinceUpdate === 'number') {
+        m.ageSum += doc.daysSinceUpdate;
+        m.ageCount += 1;
+        if (!m.oldest || doc.daysSinceUpdate > m.oldest.ageDays) {
+          m.oldest = { slug: toSlug(doc), ageDays: doc.daysSinceUpdate };
+        }
+      }
+      if (doc.hasNextStep) m.nextStepCount += 1;
+    }
+  }
+
+  const rows = [...modules.values()].map(m => ({
+    name: m.name,
+    total: m.plans.length,
+    byStatus: m.byStatus,
+    stale: m.stale,
+    avgAgeDays: m.ageCount > 0 ? m.ageSum / m.ageCount : 0,
+    oldest: m.oldest,
+    nextStepPct: m.plans.length > 0 ? m.nextStepCount / m.plans.length : 0,
+    _plans: m.plans,
+  }));
+
+  return { rows, totalUnique: uniqueTotal };
+}
+
+// Cleanup-rank formula (R3): high stale share + high average age + lower total
+// floats modules that have rotted; low total in the denominator keeps a single
+// ancient plan from outweighing a 30-plan module with two stale ones. Document
+// in `--help`; iterate after running on real corpora.
+function cleanupScore(row) {
+  return (row.stale * row.avgAgeDays) / Math.max(row.total, 1);
+}
+
+function buildSorter(sort) {
+  if (sort === 'stale') return (a, b) => b.stale - a.stale || b.total - a.total;
+  if (sort === 'age') return (a, b) => b.avgAgeDays - a.avgAgeDays || b.total - a.total;
+  if (sort === 'nextstep') return (a, b) => b.nextStepPct - a.nextStepPct || b.total - a.total;
+  if (sort === 'cleanup') return (a, b) => cleanupScore(b) - cleanupScore(a) || b.stale - a.stale;
+  return (a, b) => b.total - a.total || a.name.localeCompare(b.name);
+}
+
+function parseFlags(argv) {
+  const flags = { sort: 'total', json: false, limit: 20, all: false };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--sort' && argv[i + 1]) { flags.sort = argv[++i]; continue; }
+    if (arg === '--json') { flags.json = true; continue; }
+    if (arg === '--limit' && argv[i + 1]) { flags.limit = parseInt(argv[++i], 10); continue; }
+    if (arg === '--all') { flags.all = true; continue; }
+  }
+  const validSorts = new Set(['total', 'stale', 'age', 'nextstep', 'cleanup']);
+  if (!validSorts.has(flags.sort)) {
+    die(`Invalid --sort value: ${flags.sort}. Valid: ${[...validSorts].join(', ')}.`);
+  }
+  return flags;
+}
+
+// Discover which status columns to render. Only statuses with ≥1 non-zero cell
+// across the rendered rows make the cut (M1). Ordered by config.statusOrder
+// first, then alphabetically for any custom statuses the index encountered
+// that aren't in statusOrder (so a custom `research` column appears).
+function discoverStatusColumns(rows, config) {
+  const seen = new Set();
+  for (const row of rows) {
+    for (const [status, count] of Object.entries(row.byStatus)) {
+      if (count > 0) seen.add(status);
+    }
+  }
+  const ordered = config.statusOrder.filter(s => seen.has(s));
+  const extras = [...seen].filter(s => !config.statusOrder.includes(s)).sort();
+  return [...ordered, ...extras];
+}
+
+function fmtAge(days) {
+  if (!Number.isFinite(days)) return '-';
+  if (days < 1) return '<1d';
+  if (days < 10) return `${days.toFixed(1)}d`;
+  return `${Math.round(days)}d`;
+}
+
+function fmtPct(frac) {
+  if (!Number.isFinite(frac)) return '-';
+  return `${Math.round(frac * 100)}%`;
+}
+
+function fmtOldest(oldest) {
+  if (!oldest) return '-';
+  const slug = truncate(oldest.slug, 14);
+  return `${slug} (${fmtAge(oldest.ageDays)})`;
+}
+
+// Heuristic column-width budget. Returns true if the dynamic-columns table
+// will fit within the terminal; caller switches to the stacked render if not.
+function tableFits(rows, statuses, termWidth) {
+  const nameCol = Math.max(8, ...rows.map(r => r.name.length));
+  const statusCols = statuses.length * 7; // each status header padded
+  const tailCols = 6 /*stale*/ + 8 /*age*/ + 22 /*oldest*/ + 6 /*next%*/ + 8 /*gutters*/;
+  return nameCol + statusCols + tailCols <= termWidth;
+}
+
+function pad(s, width) {
+  if (s.length >= width) return s;
+  return s + ' '.repeat(width - s.length);
+}
+
+function padLeft(s, width) {
+  if (s.length >= width) return s;
+  return ' '.repeat(width - s.length) + s;
+}
+
+function renderTable(rows, statuses, config) {
+  const nameCol = Math.max(8, ...rows.map(r => r.name.length));
+  const lines = [];
+  const headerCells = [
+    pad('module', nameCol),
+    ...statuses.map(s => padLeft(s.slice(0, 5), 5)),
+    padLeft('stale', 5),
+    padLeft('avgAge', 7),
+    pad('oldest', 22),
+    padLeft('next%', 5),
+  ];
+  lines.push(dim(headerCells.join('  ')));
+  for (const row of rows) {
+    const cells = [
+      pad(row.name, nameCol),
+      ...statuses.map(s => {
+        const n = row.byStatus[s] ?? 0;
+        const text = padLeft(String(n), 5);
+        return n > 0 ? colorStatus(s, text) : dim(text);
+      }),
+      padLeft(String(row.stale), 5),
+      padLeft(fmtAge(row.avgAgeDays), 7),
+      pad(fmtOldest(row.oldest), 22),
+      padLeft(fmtPct(row.nextStepPct), 5),
+    ];
+    lines.push(cells.join('  '));
+  }
+  return lines.join('\n') + '\n';
+}
+
+// Stacked fallback (M2 step 2): one block per module, status counts indented.
+// Preserves every value — never collapses to "Other".
+function renderStacked(rows, statuses) {
+  const lines = [];
+  for (const row of rows) {
+    lines.push(bold(row.name) + dim(`  · ${row.total} total · ${row.stale} stale · avg ${fmtAge(row.avgAgeDays)} · next-step ${fmtPct(row.nextStepPct)}`));
+    const cells = statuses
+      .filter(s => (row.byStatus[s] ?? 0) > 0)
+      .map(s => `${colorStatus(s, s)}: ${row.byStatus[s]}`);
+    if (cells.length) lines.push('  ' + cells.join('  '));
+    if (row.oldest) lines.push(dim(`  oldest: ${row.oldest.slug} (${fmtAge(row.oldest.ageDays)})`));
+    lines.push('');
+  }
+  return lines.join('\n');
+}
+
+export function runModulesDashboard(index, argv, config) {
+  const flags = parseFlags(argv);
+  const { rows, totalUnique } = aggregateModules(index.docs, config);
+  rows.sort(buildSorter(flags.sort));
+  const totalModules = rows.length;
+  const displayRows = flags.all ? rows : rows.slice(0, flags.limit);
+
+  if (flags.json) {
+    const out = {
+      type: 'plan',
+      sort: flags.sort,
+      _totalUnique: totalUnique,
+      modules: displayRows.map(r => ({
+        name: r.name,
+        total: r.total,
+        byStatus: r.byStatus,
+        stale: r.stale,
+        avgAgeDays: Math.round(r.avgAgeDays * 10) / 10,
+        oldest: r.oldest,
+        nextStepPct: Math.round(r.nextStepPct * 100) / 100,
+      })),
+    };
+    process.stdout.write(JSON.stringify(out, null, 2) + '\n');
+    return;
+  }
+
+  if (rows.length === 0) {
+    process.stdout.write('No modules found.\n');
+    return;
+  }
+
+  const statuses = discoverStatusColumns(displayRows, config);
+  const termWidth = process.stdout.columns || 120;
+
+  const header = `${totalModules} modules · ${totalUnique} plans · sort: ${flags.sort}`;
+  process.stdout.write(dim(header) + '\n\n');
+
+  if (tableFits(displayRows, statuses, termWidth)) {
+    process.stdout.write(renderTable(displayRows, statuses, config));
+  } else {
+    process.stdout.write(renderStacked(displayRows, statuses));
+  }
+
+  if (!flags.all && rows.length > flags.limit) {
+    const hidden = rows.length - flags.limit;
+    process.stdout.write('\n' + dim(`  ${hidden} more module${hidden === 1 ? '' : 's'}  ·  runlist modules --all\n`));
+  }
+}
+
+export function runModuleDetail(index, argv, config) {
+  const flags = { sort: 'status', json: false };
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--sort' && argv[i + 1]) { flags.sort = argv[++i]; continue; }
+    if (arg === '--json') { flags.json = true; continue; }
+    if (arg.startsWith('-')) continue;
+    positional.push(arg);
+  }
+  const name = positional[0];
+  if (!name) die('Usage: runlist module <name>');
+
+  const { rows } = aggregateModules(index.docs, config);
+  const row = rows.find(r => r.name === name);
+  if (!row) {
+    const candidates = rows.map(r => r.name);
+    const suggestions = suggestCandidates(name, candidates);
+    const hint = suggestions.length
+      ? `Did you mean: ${suggestions.join(', ')}?`
+      : `Available: ${candidates.slice(0, 5).join(', ')}${candidates.length > 5 ? ', …' : ''} (run \`runlist modules\` for the full list).`;
+    die(`Module '${name}' not found. ${hint}`);
+  }
+
+  const plans = row._plans.slice();
+  if (flags.sort === 'updated' || flags.sort === 'age') {
+    plans.sort((a, b) => (b.daysSinceUpdate ?? 0) - (a.daysSinceUpdate ?? 0));
+  } else {
+    plans.sort((a, b) => {
+      const ai = config.statusOrder.indexOf(a.status);
+      const bi = config.statusOrder.indexOf(b.status);
+      const aIdx = ai === -1 ? Number.MAX_SAFE_INTEGER : ai;
+      const bIdx = bi === -1 ? Number.MAX_SAFE_INTEGER : bi;
+      if (aIdx !== bIdx) return aIdx - bIdx;
+      return (b.daysSinceUpdate ?? 0) - (a.daysSinceUpdate ?? 0);
+    });
+  }
+
+  if (flags.json) {
+    const out = {
+      name: row.name,
+      total: row.total,
+      plans: plans.map(p => ({
+        path: p.path,
+        slug: toSlug(p),
+        status: p.status,
+        daysSinceUpdate: p.daysSinceUpdate,
+        isStale: p.isStale,
+        hasNextStep: p.hasNextStep,
+        summary: p.summary,
+      })),
+    };
+    process.stdout.write(JSON.stringify(out, null, 2) + '\n');
+    return;
+  }
+
+  process.stdout.write(dim(`${row.total} plans · ${row.stale} stale · module: ${row.name}`) + '\n');
+
+  const skipStale = config.lifecycle.skipStaleFor;
+  const groups = new Map();
+  for (const p of plans) {
+    if (!groups.has(p.status)) groups.set(p.status, []);
+    groups.get(p.status).push(p);
+  }
+  const orderedStatuses = [
+    ...config.statusOrder.filter(s => groups.has(s)),
+    ...[...groups.keys()].filter(s => !config.statusOrder.includes(s)),
+  ];
+  for (const status of orderedStatuses) {
+    const group = groups.get(status);
+    process.stdout.write(`\n${bold(colorStatus(status, status))} (${group.length})\n`);
+    for (const p of group) {
+      const slug = toSlug(p);
+      const age = fmtAge(p.daysSinceUpdate);
+      const staleTag = p.isStale && !skipStale.has(p.status) ? dim(' [stale]') : '';
+      const next = p.nextStep ? ` — ${truncate(p.nextStep, 60)}` : '';
+      process.stdout.write(`  ${slug}  ${dim(age)}${staleTag}${next}\n`);
+    }
+  }
+  process.stdout.write('\n');
+}

package/src/naming.mjs

@@ -0,0 +1,55 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+
+// Canonical product-owned names and the spellings accepted during migration.
+// Writers use the current names. Readers accept both so a new build can safely
+// recover work left by an older build. Migration is intentionally one-way.
+export const PRODUCT_NAME = 'runlist';
+export const LEGACY_PRODUCT_NAME = 'dotmd';
+
+export const STATE_DIR = '.runlist';
+export const LEGACY_STATE_DIR = '.dotmd';
+
+export const ARTIFACT_PREFIX = '.runlist-';
+export const LEGACY_ARTIFACT_PREFIX = '.dotmd-';
+
+export const CONFIG_FILENAMES = [
+  'runlist.config.mjs',
+  '.runlist.config.mjs',
+  'runlist.config.js',
+  'dotmd.config.mjs',
+  '.dotmd.config.mjs',
+  'dotmd.config.js',
+];
+
+export const ENV_PREFIX = 'RUNLIST_';
+export const LEGACY_ENV_PREFIX = 'DOTMD_';
+
+// Prefer current state, but let an explicitly refused migration keep operating
+// against the untouched legacy directory.
+export function stateDir(repoRoot) {
+  const root = path.resolve(repoRoot);
+  const current = path.join(root, STATE_DIR);
+  if (existsSync(current)) return current;
+  const legacy = path.join(root, LEGACY_STATE_DIR);
+  if (existsSync(legacy)) return legacy;
+  return current;
+}
+
+export function isOwnedArtifact(basename, kind = '') {
+  const suffix = kind ? `${kind}-` : '';
+  return basename.startsWith(`${ARTIFACT_PREFIX}${suffix}`)
+    || basename.startsWith(`${LEGACY_ARTIFACT_PREFIX}${suffix}`);
+}
+
+export function isSidecarArtifact(basename, kind = '') {
+  const suffix = kind ? `${kind}-` : '';
+  return basename.includes(`${ARTIFACT_PREFIX}${suffix}`)
+    || basename.includes(`${LEGACY_ARTIFACT_PREFIX}${suffix}`);
+}
+
+export function readEnv(name, env = process.env) {
+  const current = env[`${ENV_PREFIX}${name}`];
+  if (current !== undefined) return current;
+  return env[`${LEGACY_ENV_PREFIX}${name}`];
+}

package/src/native-action.mjs

@@ -0,0 +1,59 @@
+import {parseNativeRecord} from './native-record.mjs';
+import {SourceEditError} from './source-editor.mjs';
+
+const fail=(code,message)=>{throw new SourceEditError(code,message);};
+export function prepareNativeAction(source,request,actor) {
+  const parsed=parseNativeRecord(source);
+  if(!parsed.ok||!['flag','decision'].includes(parsed.record?.type))fail('invalid-record','A valid native flag or decision is required. Repair its source before recording an action.');
+  if(!actor?.id||!['human','agent'].includes(actor.kind))fail('unauthenticated','An authenticated human or agent is required.');
+  const {action,note,operationId,at,optionId}=request;
+  if(!/^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/.test(operationId??''))fail('invalid-id','A UUID v4 operation is required.');
+  if(typeof note!=='string'||!note.trim()||note.length>4000)fail('native-invalid-action','Give a reason, up to 4,000 characters.');
+  if(typeof at!=='string'||!/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d{1,3})?Z$/.test(at)||!Number.isFinite(Date.parse(at)))fail('native-invalid-action','A valid recording timestamp is required.');
+  const record=structuredClone(parsed.record),data=record.record_data,by=structuredClone(actor),reason=note.trim(),oldStatus=record.status;
+  if(data.history.some(e=>e.id===`event:${operationId}`))fail('operation-reused','This operation is already in the record. Retry its retained request.');
+  const event={id:`event:${operationId}`,kind:action,by,at,reason,from:oldStatus};
+  if(record.type==='flag') {
+    if(!['accept','reject','resolve','reopen'].includes(action))fail('native-invalid-action','Choose accept, reject, resolve or reopen.');
+    if(action==='reopen' ? oldStatus==='open' : oldStatus!=='open')fail('native-state-conflict','The flag changed state. Reload it before reviewing an action.');
+    if(action==='accept'||action==='reject'){
+      event.previous_triage=structuredClone(data.triage);
+      data.triage={...data.triage,disposition:action==='accept'?'accepted':'rejected',by,at,reason};record.status=action==='reject'?'rejected':'open';
+    }else if(action==='resolve'){
+      const resolution={id:`resolution:${operationId}`,by,at,method:'manual',reason,evidence_ids:[]};
+      data.resolutions.push(resolution);data.active_resolution_id=resolution.id;record.status='resolved';event.resolution_id=resolution.id;
+    }else{
+      event.previous_triage=structuredClone(data.triage);event.previous_resolution_id=data.active_resolution_id??null;
+      const {by:priorBy,at:priorAt,reason:priorReason,...extensions}=data.triage;
+      data.triage={...extensions,disposition:'unreviewed'};delete data.active_resolution_id;record.status='open';
+    }
+  }else{
+    if(!['held','ruled','closed','open'].includes(action))fail('native-invalid-action','Choose open, held, ruled or closed.');
+    const superseded=new Set(data.rulings.map(r=>r.supersedes_ruling_id).filter(Boolean)),heads=data.rulings.filter(r=>!superseded.has(r.id));
+    if(heads.length>1)fail('native-ruling-conflict','Competing rulings need an explicit reconciliation in the source.');
+    const previous=heads[0];
+    if(action==='ruled'||action==='closed'||previous?.kind==='select'){
+      if(actor.kind!=='human')fail('native-authority-required','A human must record or withdraw a ruling. Agents can recommend an option separately.');
+      if(action==='ruled'&&!data.options.some(o=>o.id===optionId))fail('native-invalid-option','Select an existing option.');
+      const ruling={id:`ruling:${operationId}`,kind:action==='ruled'?'select':'withdraw',by,at,reason,authority:{basis:'human'},evidence_ids:[],...(action==='ruled'?{option_id:optionId}:{}),...(previous?{supersedes_ruling_id:previous.id}:{})};
+      data.rulings.push(ruling);event.ruling_id=ruling.id;
+      if(['ruled','closed'].includes(action))data.active_ruling_id=ruling.id;
+    }
+    if(!['ruled','closed'].includes(action))delete data.active_ruling_id;
+    if(action==='held')data.hold={...data.hold,by,at,reason};else delete data.hold;
+    record.status=action;
+  }
+  event.to=record.status;data.history.push(event);record.updated=at;
+  // Replace only managed top-level lines and the literal JSON payload. Preserve
+  // every other metadata byte, the body and its original line endings.
+  const lines=source.match(/[^\r\n]*(?:\r\n|\n|\r|$)/g).filter(Boolean),end=lines.findIndex((l,i)=>i>0&&/^---\s*$/.test(l.trim())),start=lines.findIndex((l,i)=>i>0&&i<end&&/^record_data: [|]/.test(l));
+  if(start<0||end<0)fail('invalid-record','The record_data literal block is required.');
+  let finish=start+1;while(finish<end&&(/^[ \t]/.test(lines[finish])||!lines[finish].trim()))finish++;
+  const eol=lines[start].match(/\r\n|\n|\r$/)?.[0]??'\n';
+  const payload=JSON.stringify(data,null,2).split('\n').map(line=>`  ${line}${eol}`);
+  lines.splice(start+1,finish-start-1,...payload);
+  for(const [field,value] of [['status',record.status],['updated',at]]){const i=lines.findIndex(l=>l.startsWith(`${field}:`));if(i<1)fail('invalid-record',`Missing ${field}.`);const ending=lines[i].match(/\r\n|\n|\r$/)?.[0]??'';lines[i]=`${field}: ${value}${ending}`;}
+  const next=lines.join(''),after=parseNativeRecord(next);
+  if(!after.ok)throw new SourceEditError('invalid-record','The action would violate the native record contract.',{diagnostics:after.diagnostics});
+  return next;
+}