runlist 0.0.0 → 0.94.1

package/src/migrate-prompts.mjs

@@ -0,0 +1,171 @@
+import { readFileSync, writeFileSync, readdirSync, statSync, existsSync } from 'node:fs';
+import path from 'node:path';
+import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
+import { toRepoPath, nowIso } from './util.mjs';
+import { getGitFirstAdded } from './git.mjs';
+import { bold, green, dim } from './color.mjs';
+import { readFileSync as rfs } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { authorizeManagedSweep } from './managed-path.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(rfs(path.join(__dirname, '..', 'package.json'), 'utf8'));
+
+function findPromptCandidates(config) {
+  const roots = config.docsRoots || [config.docsRoot];
+  // Build the set of directories to search: each root, plus each root's parent
+  // (catches `docs/prompts/` when roots are like `docs/plans/`, `docs/modules/`),
+  // plus the repo root itself.
+  const candidates = new Set();
+  for (const root of roots) {
+    candidates.add(path.join(root, 'prompts'));
+    candidates.add(path.join(path.dirname(root), 'prompts'));
+  }
+  candidates.add(path.join(config.repoRoot, 'prompts'));
+
+  const out = [];
+  const seen = new Set();
+  for (const dir of candidates) {
+    if (!existsSync(dir) || seen.has(dir)) continue;
+    seen.add(dir);
+    walkDir(dir, out);
+  }
+  return out;
+}
+
+function walkDir(dir, out) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name.startsWith('.')) continue;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) { walkDir(full, out); continue; }
+    if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
+    out.push(full);
+  }
+}
+
+function deriveContext(body, filePath) {
+  // Use first heading or filename as the context label.
+  const firstH1 = body.match(/^#\s+(.+?)\s*$/m);
+  if (firstH1) return firstH1[1].slice(0, 100);
+  // Fall back to slug, title-cased.
+  const slug = path.basename(filePath, '.md');
+  return slug.replace(/[-_]/g, ' ').replace(/\b\w/g, c => c.toUpperCase()).slice(0, 100);
+}
+
+export function migrateOnePrompt(raw, opts = {}) {
+  const { frontmatter, body: rawBody } = extractFrontmatter(raw);
+  const created = opts.created || nowIso();
+
+  // Case 1: no frontmatter at all → wrap with full fresh frontmatter.
+  if (!frontmatter || frontmatter.length === 0) {
+    const body = raw.trimStart();
+    const context = deriveContext(body, opts.filePath || 'unknown');
+    const fm = [
+      'type: prompt',
+      'status: pending',
+      `created: ${created}`,
+      `runlist_version: ${pkg.version}`,
+      `context: "${context.replace(/"/g, '\\"')}"`,
+      'related_plans: []',
+    ].join('\n');
+    return {
+      changes: [{ kind: 'add-frontmatter', detail: `type=prompt, created=${created}, context="${context}"` }],
+      newRaw: `---\n${fm}\n---\n\n${body.trim()}\n`,
+    };
+  }
+
+  // Case 2: frontmatter exists. If it already has `type: prompt`, leave alone.
+  const parsed = parseSimpleFrontmatter(frontmatter);
+  if (parsed.type === 'prompt') {
+    return { changes: [], newRaw: raw, skipped: 'already-prompt' };
+  }
+
+  // Case 3: partial/ad-hoc frontmatter (e.g., `title:` + `purpose:` only).
+  // Add missing required fields while preserving existing keys.
+  const needed = [];
+  if (!parsed.type) needed.push(['type', 'prompt']);
+  if (!parsed.status) needed.push(['status', 'pending']);
+  if (!parsed.created) needed.push(['created', created]);
+  if (!parsed.runlist_version && !parsed.dotmd_version) needed.push(['runlist_version', pkg.version]);
+  if (!parsed.context) {
+    // Prefer existing `title:` if present, else derive from body/filename.
+    const ctx = typeof parsed.title === 'string' ? parsed.title : deriveContext(rawBody || raw, opts.filePath || 'unknown');
+    needed.push(['context', `"${ctx.replace(/"/g, '\\"')}"`]);
+  }
+  if (!parsed.related_plans) needed.push(['related_plans', '[]']);
+
+  if (needed.length === 0) {
+    return { changes: [], newRaw: raw, skipped: 'frontmatter-complete' };
+  }
+
+  // Prepend the missing fields (so `type` ends up at the top for grep-friendliness).
+  const addedLines = needed.map(([k, v]) => `${k}: ${v}`).join('\n');
+  const newFrontmatter = `${addedLines}\n${frontmatter}`;
+  const newRaw = `---\n${newFrontmatter}\n---\n${rawBody}`;
+  return {
+    changes: [{ kind: 'merge-frontmatter', detail: `added: ${needed.map(([k]) => k).join(', ')}` }],
+    newRaw,
+  };
+}
+
+export function runMigratePrompts(argv, config, opts = {}) {
+  const { dryRun } = opts;
+  const json = argv.includes('--json');
+  const fileArg = argv.find(a => !a.startsWith('-') && a !== 'doctor');
+
+  let files;
+  if (fileArg) {
+    const target = fileArg.endsWith('.md') ? fileArg : `${fileArg}.md`;
+    files = findPromptCandidates(config).filter(f => f.endsWith(target) || f === target);
+    if (files.length === 0) {
+      process.stderr.write(`File not found in any prompts/ subdir: ${fileArg}\n`);
+      process.exitCode = 1;
+      return;
+    }
+  } else {
+    files = findPromptCandidates(config);
+  }
+  authorizeManagedSweep(files, config, { kind: 'Prompt migration source' });
+
+  const results = [];
+  let touched = 0;
+
+  for (const filePath of files) {
+    const raw = readFileSync(filePath, 'utf8');
+    const created = getGitFirstAdded(toRepoPath(filePath, config.repoRoot), config.repoRoot)
+      || new Date(statSync(filePath).birthtimeMs).toISOString().replace(/\.\d{3}Z$/, 'Z');
+    const result = migrateOnePrompt(raw, { created, filePath });
+    if (result.changes.length === 0) continue;
+
+    const repoPath = toRepoPath(filePath, config.repoRoot);
+    results.push({ path: repoPath, changes: result.changes });
+    touched++;
+
+    if (!dryRun) writeFileSync(filePath, result.newRaw, 'utf8');
+  }
+
+  if (json) {
+    process.stdout.write(JSON.stringify({
+      dryRun: Boolean(dryRun),
+      filesScanned: files.length,
+      filesTouched: touched,
+      results,
+    }, null, 2) + '\n');
+    return;
+  }
+
+  if (results.length === 0) {
+    process.stdout.write(green('No prompts need migration.') + dim(` (${files.length} scanned)`) + '\n');
+    return;
+  }
+
+  const prefix = dryRun ? dim('[dry-run] ') : '';
+  process.stdout.write(bold(`${prefix}${touched} prompt${touched === 1 ? '' : 's'} ${dryRun ? 'would be' : 'were'} migrated:\n\n`));
+  for (const r of results) {
+    process.stdout.write(`  ${r.path}\n`);
+    for (const c of r.changes) {
+      process.stdout.write(dim(`    [${c.kind}] ${c.detail}\n`));
+    }
+  }
+  if (dryRun) process.stdout.write(`\nRun ${bold('runlist doctor --migrate-prompts')} without --dry-run to apply.\n`);
+}

package/src/migrate-template.mjs

@@ -0,0 +1,170 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
+import { asString, toRepoPath, nowIso } from './util.mjs';
+import { collectDocFiles } from './index.mjs';
+import { bold, green, yellow, dim } from './color.mjs';
+import { authorizeManagedSweep } from './managed-path.mjs';
+
+const HEADING_RENAMES = [
+  { from: /^##\s+Open questions\s*$/gm, to: '## Open Questions' },
+  { from: /^##\s+open questions\s*$/gm, to: '## Open Questions' },
+  { from: /^##\s+Out of [Ss]cope\s*$/gm, to: '## Non-Goals' },
+  { from: /^##\s+out of scope\s*$/gm, to: '## Non-Goals' },
+  { from: /^##\s+Non-goals\s*$/gm, to: '## Non-Goals' },
+];
+
+// Detect "both surface and surfaces are populated" — applies same logic to module/modules.
+// Returns the singular-line text to delete, or null if no fix needed.
+function findRedundantSingular(rawFrontmatter, singularKey, pluralKey, parsed) {
+  const singularVal = asString(parsed[singularKey]);
+  const pluralVal = parsed[pluralKey];
+  const pluralHasValues = Array.isArray(pluralVal) && pluralVal.length > 0;
+  if (!singularVal || !pluralHasValues) return null;
+  // Find the exact line: `<singularKey>: <value>` (single inline, not a block start)
+  const lineRe = new RegExp(`^${singularKey}:\\s*[^\\n]+$`, 'm');
+  const match = rawFrontmatter.match(lineRe);
+  return match ? match[0] : null;
+}
+
+function ensureVersionHistory(body, timestamp) {
+  if (/^##\s+Version History\s*$/m.test(body)) return null;
+  const newSection = `## Version History\n\n- **${timestamp}** Migrated to v0.21 template.\n`;
+  // Insert before ## Closeout if it exists; else append at end.
+  const closeoutMatch = body.match(/^##\s+Closeout\s*$/m);
+  if (closeoutMatch) {
+    const idx = body.indexOf(closeoutMatch[0]);
+    return body.slice(0, idx) + newSection + '\n' + body.slice(idx);
+  }
+  return body.trimEnd() + '\n\n' + newSection;
+}
+
+// Run plan-shape migrations on one file. Pure-ish: returns { changes, newRaw }
+// without writing. Caller handles IO.
+export function migrateOne(raw) {
+  const { frontmatter, body } = extractFrontmatter(raw);
+  if (!frontmatter || !body) return { changes: [], newRaw: raw };
+  const parsed = parseSimpleFrontmatter(frontmatter);
+  if (asString(parsed.type) !== 'plan') return { changes: [], newRaw: raw, skipped: 'not-plan' };
+
+  let newFrontmatter = frontmatter;
+  let newBody = body;
+  const changes = [];
+
+  // 1. Drop redundant singular surface/module when array form is populated.
+  const dropSurface = findRedundantSingular(newFrontmatter, 'surface', 'surfaces', parsed);
+  if (dropSurface) {
+    newFrontmatter = newFrontmatter.replace(new RegExp(`\\n?${dropSurface.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&')}\\n?`), '\n').replace(/\n+/g, '\n');
+    changes.push({ kind: 'drop-singular', detail: dropSurface });
+  }
+  const dropModule = findRedundantSingular(newFrontmatter, 'module', 'modules', parsed);
+  if (dropModule) {
+    newFrontmatter = newFrontmatter.replace(new RegExp(`\\n?${dropModule.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&')}\\n?`), '\n').replace(/\n+/g, '\n');
+    changes.push({ kind: 'drop-singular', detail: dropModule });
+  }
+
+  // 2. Heading renames in body
+  for (const { from, to } of HEADING_RENAMES) {
+    const matches = [...newBody.matchAll(from)];
+    if (matches.length > 0) {
+      newBody = newBody.replace(from, to);
+      for (const m of matches) {
+        changes.push({ kind: 'rename-heading', detail: `\`${m[0].trim()}\` → \`${to}\`` });
+      }
+    }
+  }
+
+  // 3. Add ## Version History section if missing.
+  // Use the file's `updated` timestamp if present, else nowIso(), so the
+  // seed entry reads truthfully ("when this plan was last touched") rather
+  // than dating itself to the migration moment.
+  const seedTs = asString(parsed.updated) || nowIso();
+  const withVh = ensureVersionHistory(newBody, seedTs);
+  if (withVh !== null) {
+    newBody = withVh;
+    changes.push({ kind: 'add-version-history', detail: `seeded with ${seedTs}` });
+  }
+
+  if (changes.length === 0) return { changes: [], newRaw: raw };
+
+  const newRaw = `---\n${newFrontmatter.trim()}\n---\n${newBody}`;
+  return { changes, newRaw };
+}
+
+function isInArchive(filePath, config) {
+  const archiveDir = config.archiveDir || 'archived';
+  const sep = path.sep;
+  return filePath.includes(`${sep}${archiveDir}${sep}`) || filePath.endsWith(`${sep}${archiveDir}`);
+}
+
+export function runMigrateTemplate(argv, config, opts = {}) {
+  const { dryRun } = opts;
+  const json = argv.includes('--json');
+  const includeArchived = argv.includes('--include-archived');
+  // First positional anywhere in argv (skip 'doctor' subcommand if present at idx 0).
+  const fileArg = argv.find(a => !a.startsWith('-') && a !== 'doctor');
+
+  // Allow targeting one file, else sweep all plans (excluding archived by default).
+  let files;
+  if (fileArg) {
+    const target = fileArg.endsWith('.md') ? fileArg : `${fileArg}.md`;
+    files = collectDocFiles(config).filter(f => f.endsWith(target) || f === target);
+    if (files.length === 0) {
+      process.stderr.write(`File not found: ${fileArg}\n`);
+      process.exitCode = 1;
+      return;
+    }
+  } else {
+    files = collectDocFiles(config);
+    if (!includeArchived) files = files.filter(f => !isInArchive(f, config));
+  }
+  authorizeManagedSweep(files, config, { kind: 'Template migration source' });
+
+  const results = [];
+  let totalChanges = 0;
+  let touched = 0;
+
+  for (const filePath of files) {
+    const raw = readFileSync(filePath, 'utf8');
+    const result = migrateOne(raw);
+    if (result.changes.length === 0) continue;
+
+    const repoPath = toRepoPath(filePath, config.repoRoot);
+    results.push({ path: repoPath, changes: result.changes });
+    totalChanges += result.changes.length;
+    touched++;
+
+    if (!dryRun) writeFileSync(filePath, result.newRaw, 'utf8');
+  }
+
+  if (json) {
+    process.stdout.write(JSON.stringify({
+      dryRun: Boolean(dryRun),
+      filesTouched: touched,
+      totalChanges,
+      results,
+    }, null, 2) + '\n');
+    return;
+  }
+
+  if (results.length === 0) {
+    process.stdout.write(green('No template migrations needed.') + '\n');
+    return;
+  }
+
+  const prefix = dryRun ? dim('[dry-run] ') : '';
+  process.stdout.write(bold(`${prefix}${touched} plan${touched === 1 ? '' : 's'} ${dryRun ? 'would be' : 'were'} migrated (${totalChanges} change${totalChanges === 1 ? '' : 's'}):\n\n`));
+
+  for (const r of results) {
+    process.stdout.write(`  ${r.path}\n`);
+    for (const c of r.changes) {
+      process.stdout.write(dim(`    [${c.kind}] ${c.detail}\n`));
+    }
+  }
+
+  if (dryRun) {
+    process.stdout.write(`\nRun ${bold('runlist doctor --migrate-template')} without --dry-run to apply.\n`);
+  } else {
+    process.stdout.write(`\n${green('Done.')} Re-run ${bold('runlist check')} to see remaining issues.\n`);
+  }
+}

package/src/migrate.mjs

@@ -0,0 +1,90 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
+import { asString, toRepoPath, resolveDocPath, die } from './util.mjs';
+import { collectDocFiles } from './index.mjs';
+import { updateFrontmatter } from './lifecycle.mjs';
+import { bold, green, dim } from './color.mjs';
+import { authorizeManagedSweep } from './managed-path.mjs';
+
+export function runMigrate(argv, config, opts = {}) {
+  const { dryRun } = opts;
+
+  // Parse positional args (skip flags)
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i].startsWith('-')) continue;
+    positional.push(argv[i]);
+  }
+
+  const field = positional[0];
+  const oldValue = positional[1];
+  const newValue = positional[2];
+  const fileArgs = positional.slice(3);
+
+  if (!field || !oldValue || !newValue) {
+    die('Usage: runlist migrate <field> <old-value> <new-value> [files...]');
+  }
+
+  const allFiles = collectDocFiles(config);
+
+  // When file args are passed, resolve them to a filter set (mirrors runBulkArchive).
+  let fileFilter = null;
+  if (fileArgs.length > 0) {
+    const matched = [];
+    const unresolved = [];
+    for (const input of fileArgs) {
+      const filePath = resolveDocPath(input, config);
+      if (filePath) {
+        matched.push(filePath);
+        continue;
+      }
+      const normalizedInput = input.replaceAll('\\', '/');
+      const hits = allFiles.filter(f => {
+        const repoPath = toRepoPath(f, config.repoRoot);
+        return repoPath.includes(normalizedInput) || path.basename(f).includes(input);
+      });
+      if (hits.length === 0) {
+        unresolved.push(input);
+      } else {
+        matched.push(...hits);
+      }
+    }
+    if (unresolved.length > 0) {
+      die(`No matching file(s) for: ${unresolved.join(', ')}`);
+    }
+    fileFilter = new Set(matched);
+  }
+
+  const matches = [];
+  authorizeManagedSweep(fileFilter ? [...fileFilter] : allFiles, config, { kind: 'Migration source' });
+
+  for (const filePath of allFiles) {
+    if (fileFilter && !fileFilter.has(filePath)) continue;
+    const raw = readFileSync(filePath, 'utf8');
+    const { frontmatter } = extractFrontmatter(raw);
+    if (!frontmatter) continue;
+    const parsed = parseSimpleFrontmatter(frontmatter);
+    const current = asString(parsed[field]);
+    if (current === oldValue) {
+      matches.push({ filePath, repoPath: toRepoPath(filePath, config.repoRoot) });
+    }
+  }
+
+  if (matches.length === 0) {
+    const scope = fileFilter ? ` in the specified file(s)` : '';
+    process.stdout.write(`No docs found with ${bold(field)}: ${oldValue}${scope}\n`);
+    return;
+  }
+
+  const prefix = dryRun ? dim('[dry-run] ') : '';
+
+  for (const { filePath, repoPath } of matches) {
+    if (!dryRun) {
+      updateFrontmatter(filePath, { [field]: newValue });
+    }
+    process.stdout.write(`${prefix}${green('Updated')}: ${repoPath} (${field}: ${oldValue} → ${newValue})\n`);
+  }
+
+  process.stdout.write(`\n${prefix}${matches.length} file(s) ${dryRun ? 'would be ' : ''}updated.\n`);
+}

package/src/misuse-read.mjs

@@ -0,0 +1,61 @@
+import { existsSync } from 'node:fs';
+import { readMisuseEntries, globalMisuseLogPaths } from './journal.mjs';
+import { dim, red, yellow } from './color.mjs';
+
+// `runlist misuse` — read the cross-repo guard log. Every wrong-move the
+// PreToolUse guard intercepts lands here; this is the operator's window into
+// "what are sessions getting wrong, and how often."
+function parseArgs(argv) {
+  const opts = { tail: null, byRule: false, asJson: false, repo: null };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--tail') { const n = parseInt(argv[++i], 10); opts.tail = Number.isFinite(n) && n > 0 ? n : 20; }
+    else if (a === '--by-rule') opts.byRule = true;
+    else if (a === '--json') opts.asJson = true;
+    else if (a === '--repo' && argv[i + 1]) opts.repo = argv[++i];
+  }
+  if (opts.tail === null && !opts.byRule) opts.tail = 20;
+  return opts;
+}
+
+export function runMisuse(argv, _config) {
+  if (!globalMisuseLogPaths().some(file => existsSync(file))) {
+    process.stderr.write(
+      'No misuse log yet. The PreToolUse guard (`runlist guard`) writes here when it intercepts a wrong move.\n' +
+      'Wire it up: add a PreToolUse hook that runs `runlist guard` (see `runlist help guard`).\n',
+    );
+    return;
+  }
+
+  const opts = parseArgs(argv);
+  let entries = readMisuseEntries();
+  if (opts.repo) entries = entries.filter(e => (e.repo || '').includes(opts.repo));
+
+  if (opts.byRule) {
+    const groups = new Map();
+    for (const e of entries) {
+      const key = e.rule || '(unknown)';
+      if (!groups.has(key)) groups.set(key, { rule: key, count: 0, deny: 0, warn: 0 });
+      const g = groups.get(key);
+      g.count++;
+      if (e.decision === 'deny') g.deny++; else if (e.decision === 'warn') g.warn++;
+    }
+    const rows = [...groups.values()].sort((a, b) => b.count - a.count);
+    if (opts.asJson) { process.stdout.write(JSON.stringify(rows, null, 2) + '\n'); return; }
+    if (!rows.length) { process.stdout.write('No misuse events recorded.\n'); return; }
+    for (const r of rows) {
+      process.stdout.write(`${r.rule.padEnd(16)} ${String(r.count).padStart(4)}×  ${red(`${r.deny} deny`)} / ${yellow(`${r.warn} warn`)}\n`);
+    }
+    return;
+  }
+
+  if (opts.tail) entries = entries.slice(-opts.tail);
+  if (opts.asJson) { process.stdout.write(JSON.stringify(entries, null, 2) + '\n'); return; }
+  if (!entries.length) { process.stdout.write('No misuse events recorded.\n'); return; }
+
+  for (const e of entries) {
+    const tag = e.decision === 'deny' ? red('DENY') : yellow('warn');
+    const repo = e.repo ? dim(` ${e.repo.split('/').pop()}`) : '';
+    process.stdout.write(`[${e.ts}] ${tag} ${e.rule || '?'}${repo} ${dim(e.detail || '')}\n`);
+  }
+}

package/src/model-request.mjs

@@ -0,0 +1,33 @@
+// HTTP requests to the local model server, run as a child process so the
+// synchronous callers (summaries, lint's status inference) can wait on them
+// without every render path turning async. Reads a list of
+// {url, method, body, timeoutMs} as JSON on stdin, sends them in order, and
+// writes the list of {ok, status, json, error} as JSON on stdout.
+
+const input = JSON.parse(await new Promise(resolve => {
+  let data = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', chunk => { data += chunk; });
+  process.stdin.on('end', () => resolve(data));
+}));
+
+async function send(input) {
+  try {
+    const res = await fetch(input.url, {
+      method: input.method ?? 'GET',
+      headers: input.body ? { 'content-type': 'application/json' } : undefined,
+      body: input.body ? JSON.stringify(input.body) : undefined,
+      signal: AbortSignal.timeout(input.timeoutMs ?? 10000),
+    });
+    const text = await res.text();
+    let json = null;
+    try { json = JSON.parse(text); } catch { /* non-JSON body; status says enough */ }
+  return { ok: res.ok, status: res.status, json, error: res.ok ? null : (json?.error ?? text.slice(0, 200)) };
+  } catch (err) {
+    return { ok: false, status: 0, json: null, error: err.name === 'TimeoutError' ? 'timed out' : (err.cause?.code ?? err.message) };
+  }
+}
+
+const out = [];
+for (const req of [input].flat()) out.push(await send(req));
+process.stdout.write(JSON.stringify(Array.isArray(input) ? out : out[0]));