@jaimevalasek/aioson 1.7.2 → 1.9.0

package/src/commands/dossier-audit.js

@@ -0,0 +1,222 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+
+const CHAIN_AGENTS = Object.freeze([
+  'product',
+  'sheldon',
+  'analyst',
+  'architect',
+  'ux-ui',
+  'pm',
+  'orchestrator',
+  'dev',
+  'qa'
+]);
+
+const FEATURE_DOSSIER_HEADER = '## Feature dossier';
+
+function resolveProjectRoot(targetDir) {
+  return path.resolve(process.cwd(), targetDir || '.');
+}
+
+async function readFileOrNull(filePath) {
+  try {
+    return await fs.readFile(filePath, 'utf8');
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return null;
+    throw err;
+  }
+}
+
+function extractSection(raw, header) {
+  if (typeof raw !== 'string') return null;
+  const headerRe = new RegExp(`(^|\\n)${header.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\$&')}\\s*\\n`);
+  const match = raw.match(headerRe);
+  if (!match) return null;
+  const startIdx = match.index + (match[1] === '\n' ? 1 : 0);
+  const afterHeader = startIdx + header.length + 1;
+  const remainder = raw.slice(afterHeader);
+  const nextSectionMatch = remainder.match(/\n## /);
+  const endIdx = nextSectionMatch ? afterHeader + nextSectionMatch.index + 1 : raw.length;
+  return raw.slice(startIdx, endIdx);
+}
+
+async function checkTemplateParity({ projectRoot, agents }) {
+  const violations = [];
+  const checked = [];
+
+  for (const agent of agents) {
+    const workspacePath = path.join(projectRoot, '.aioson', 'agents', `${agent}.md`);
+    const templatePath = path.join(projectRoot, 'template', '.aioson', 'agents', `${agent}.md`);
+
+    const workspaceRaw = await readFileOrNull(workspacePath);
+    const templateRaw = await readFileOrNull(templatePath);
+
+    if (workspaceRaw === null && templateRaw === null) continue;
+
+    const workspaceSection = workspaceRaw ? extractSection(workspaceRaw, FEATURE_DOSSIER_HEADER) : null;
+    const templateSection = templateRaw ? extractSection(templateRaw, FEATURE_DOSSIER_HEADER) : null;
+
+    checked.push(agent);
+
+    if (workspaceSection === templateSection) continue;
+
+    const workspaceLen = workspaceSection ? workspaceSection.length : 0;
+    const templateLen = templateSection ? templateSection.length : 0;
+
+    let kind;
+    if (workspaceSection && !templateSection) kind = 'workspace_only';
+    else if (!workspaceSection && templateSection) kind = 'template_only';
+    else if (workspaceLen > templateLen) kind = 'workspace_ahead';
+    else kind = 'template_ahead';
+
+    violations.push({
+      agent,
+      kind,
+      workspace_chars: workspaceLen,
+      template_chars: templateLen
+    });
+  }
+
+  return { checked, violations };
+}
+
+function parseFeaturesTable(raw) {
+  if (typeof raw !== 'string') return [];
+  const out = [];
+  const lines = raw.split('\n');
+  let inTable = false;
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('|')) {
+      inTable = false;
+      continue;
+    }
+    if (/^\|\s*-+\s*\|/.test(trimmed)) {
+      inTable = true;
+      continue;
+    }
+    if (!inTable) continue;
+    const cells = trimmed.split('|').slice(1, -1).map((c) => c.trim());
+    if (cells.length < 2) continue;
+    const [slug, status] = cells;
+    if (!slug || slug.toLowerCase() === 'slug') continue;
+    out.push({ slug, status: (status || '').toLowerCase() });
+  }
+  return out;
+}
+
+function parseFrontmatterField(raw, key) {
+  if (typeof raw !== 'string') return null;
+  const fmMatch = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!fmMatch) return null;
+  const fieldRe = new RegExp(`^${key}:\\s*"?([^"\\n]+)"?\\s*$`, 'm');
+  const match = fmMatch[1].match(fieldRe);
+  return match ? match[1].trim() : null;
+}
+
+async function readClassificationForFeature({ projectRoot, slug }) {
+  const ctxDir = path.join(projectRoot, '.aioson', 'context');
+  const candidates = [
+    path.join(ctxDir, 'features', slug, 'dossier.md'),
+    path.join(ctxDir, `prd-${slug}.md`),
+    path.join(ctxDir, `spec-${slug}.md`)
+  ];
+  for (const candidate of candidates) {
+    const raw = await readFileOrNull(candidate);
+    if (!raw) continue;
+    const cls = parseFrontmatterField(raw, 'classification');
+    if (cls) return cls.toUpperCase();
+  }
+  return null;
+}
+
+async function checkCoverage({ projectRoot }) {
+  const ctxDir = path.join(projectRoot, '.aioson', 'context');
+  const featuresPath = path.join(ctxDir, 'features.md');
+  const featuresRaw = await readFileOrNull(featuresPath);
+  if (featuresRaw === null) {
+    return { features_checked: [], missing_dossier: [], features_md_missing: true };
+  }
+
+  const features = parseFeaturesTable(featuresRaw);
+  const missing = [];
+  const checked = [];
+
+  for (const feature of features) {
+    if (feature.status !== 'in_progress') continue;
+    const classification = await readClassificationForFeature({ projectRoot, slug: feature.slug });
+    checked.push({ slug: feature.slug, status: feature.status, classification });
+    if (classification !== 'SMALL' && classification !== 'MEDIUM') continue;
+    const dossierPath = path.join(ctxDir, 'features', feature.slug, 'dossier.md');
+    const dossierRaw = await readFileOrNull(dossierPath);
+    if (dossierRaw === null) {
+      missing.push({ slug: feature.slug, classification });
+    }
+  }
+
+  return { features_checked: checked, missing_dossier: missing, features_md_missing: false };
+}
+
+async function runDossierAudit({ args = [], options = {}, logger } = {}) {
+  const targetDir = args[0] || '.';
+  const jsonOut = Boolean(options.json);
+  const log = (msg) => { if (logger && !jsonOut) logger.log(msg); };
+  const projectRoot = resolveProjectRoot(targetDir);
+
+  const check = options.check ? String(options.check) : null;
+  if (!check) {
+    if (jsonOut) return { ok: false, reason: 'missing_check' };
+    log('--check=<template-parity|coverage> is required.');
+    return { ok: false };
+  }
+
+  if (check === 'template-parity') {
+    const result = await checkTemplateParity({ projectRoot, agents: CHAIN_AGENTS });
+    const ok = result.violations.length === 0;
+    if (jsonOut) return { ok, check, ...result };
+    if (ok) {
+      log(`template-parity OK — ${result.checked.length} chain agent(s) verified.`);
+    } else {
+      log(`template-parity FAILED — ${result.violations.length} violation(s):`);
+      for (const v of result.violations) {
+        log(`  - @${v.agent}: ${v.kind} (workspace=${v.workspace_chars} chars, template=${v.template_chars} chars)`);
+      }
+    }
+    return { ok, check, ...result };
+  }
+
+  if (check === 'coverage') {
+    const result = await checkCoverage({ projectRoot });
+    const ok = result.missing_dossier.length === 0 && !result.features_md_missing;
+    if (jsonOut) return { ok, check, ...result };
+    if (result.features_md_missing) {
+      log('coverage check skipped — .aioson/context/features.md missing.');
+    } else if (ok) {
+      log(`coverage OK — ${result.features_checked.length} in-progress feature(s) verified; all SMALL/MEDIUM have a dossier.`);
+    } else {
+      log(`coverage FAILED — ${result.missing_dossier.length} feature(s) without dossier:`);
+      for (const m of result.missing_dossier) {
+        log(`  - ${m.slug} (${m.classification})`);
+      }
+    }
+    return { ok, check, ...result };
+  }
+
+  if (jsonOut) return { ok: false, reason: 'unknown_check', check };
+  log(`Unknown --check="${check}" — use template-parity or coverage.`);
+  return { ok: false };
+}
+
+module.exports = {
+  runDossierAudit,
+  CHAIN_AGENTS,
+  FEATURE_DOSSIER_HEADER,
+  extractSection,
+  parseFeaturesTable,
+  parseFrontmatterField,
+  checkTemplateParity,
+  checkCoverage
+};

package/src/commands/dossier.js

@@ -0,0 +1,423 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const readline = require('node:readline');
+
+const store = require('../dossier/store');
+const codemapStore = require('../dossier/codemap-store');
+const { compact, shouldCompact } = require('../dossier/dossier-compact');
+const { initFromExisting } = require('../dossier/dossier-bootstrap');
+const { ALLOWED_CLASSIFICATIONS, isValidSlug, isCanonicalAgent } = require('../dossier/schema');
+
+function resolveContextDir(targetDir) {
+  return path.join(path.resolve(process.cwd(), targetDir || '.'), '.aioson', 'context');
+}
+
+function pickSlug(options) {
+  const raw = options.slug || options.feature;
+  return raw ? String(raw) : null;
+}
+
+async function readProjectClassification(ctxDir) {
+  const ctxPath = path.join(ctxDir, 'project.context.md');
+  try {
+    const raw = await fs.readFile(ctxPath, 'utf8');
+    const match = raw.match(/^classification:\s*"?([A-Z]+)"?\s*$/m);
+    if (match && ALLOWED_CLASSIFICATIONS.has(match[1])) {
+      return match[1];
+    }
+  } catch {
+    // ignored — caller falls back
+  }
+  return null;
+}
+
+async function runDossierInit({ args = [], options = {}, logger } = {}) {
+  const targetDir = args[0] || '.';
+  const slug = pickSlug(options);
+  const jsonOut = Boolean(options.json);
+  const log = (msg) => { if (logger && !jsonOut) logger.log(msg); };
+
+  if (!slug) {
+    if (jsonOut) return { ok: false, reason: 'missing_slug' };
+    log('--slug=<feature-slug> is required.');
+    return { ok: false };
+  }
+  if (!isValidSlug(slug)) {
+    if (jsonOut) return { ok: false, reason: 'invalid_slug', slug };
+    log(`Invalid slug "${slug}" — must be kebab-case (lowercase, digits and hyphens).`);
+    return { ok: false };
+  }
+
+  const ctxDir = resolveContextDir(targetDir);
+  let classification = options.classification ? String(options.classification).toUpperCase() : null;
+  if (classification && !ALLOWED_CLASSIFICATIONS.has(classification)) {
+    if (jsonOut) return { ok: false, reason: 'invalid_classification', classification };
+    log(`Invalid classification "${classification}" — use MICRO | SMALL | MEDIUM.`);
+    return { ok: false };
+  }
+  if (!classification) {
+    classification = (await readProjectClassification(ctxDir)) || 'MEDIUM';
+  }
+
+  // --from-existing: synthesize from existing artifacts
+  if (options['from-existing'] || options.fromExisting) {
+    try {
+      const result = await initFromExisting({
+        slug,
+        contextDir: ctxDir,
+        classification,
+        targetDir: path.resolve(process.cwd(), targetDir || '.')
+      });
+      if (result.created === false) {
+        if (jsonOut) return { ok: true, slug, reason: 'unchanged', path: result.path };
+        log(`Dossier unchanged (artifacts not modified since last bootstrap).`);
+        return { ok: true };
+      }
+      if (jsonOut) return { ok: true, slug, path: result.path, classification: result.classification, artifactsFound: result.artifactsFound };
+      log(`Dossier bootstrapped: ${result.path}`);
+      log(`  classification: ${result.classification}`);
+      log(`  artifacts found: ${result.artifactsFound.join(', ')}`);
+      return { ok: true, path: result.path };
+    } catch (err) {
+      if (err && err.code === 'EBOOTSTRAPEMPTY') {
+        if (jsonOut) return { ok: false, reason: 'no_artifacts', slug };
+        log(`No artifacts found for slug "${slug}" — use dossier:init without --from-existing.`);
+        return { ok: false };
+      }
+      if (err && err.code === 'EDOSSIEREXISTS') {
+        if (jsonOut) return { ok: false, reason: 'already_exists', slug, path: err.path };
+        log(`Dossier already exists at ${err.path}.`);
+        return { ok: false };
+      }
+      if (err && err.code === 'EDOSSIERSCHEMA') {
+        if (jsonOut) return { ok: false, reason: 'schema_violation', errors: err.errors };
+        log(`Schema error: ${err.message}`);
+        return { ok: false };
+      }
+      throw err;
+    }
+  }
+
+  const prdFile = path.join(ctxDir, `prd-${slug}.md`);
+  let hasPrd = false;
+  try { await fs.access(prdFile); hasPrd = true; } catch { /* absent */ }
+
+  let initOpts = { slug, contextDir: ctxDir, classification };
+
+  if (!hasPrd) {
+    let whyText = '';
+    let whatText = '';
+    if (!jsonOut && process.stdin.isTTY) {
+      const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+      whyText = await new Promise(resolve => rl.question('Why? ', resolve));
+      whatText = await new Promise(resolve => { rl.question('What? ', ans => { rl.close(); resolve(ans); }); });
+    }
+    initOpts.author = 'dossier-init-prompt';
+    initOpts.whyText = whyText;
+    initOpts.whatText = whatText;
+  }
+
+  try {
+    const result = await store.init(initOpts);
+    if (jsonOut) {
+      return { ok: true, slug, path: result.path, dir: result.dir, classification };
+    }
+    log(`Dossier created: ${result.path}`);
+    log(`  classification: ${classification}`);
+    log(`  status: active   schema: 1.0`);
+    return { ok: true, path: result.path };
+  } catch (err) {
+    if (err && err.code === 'EDOSSIEREXISTS') {
+      if (jsonOut) return { ok: false, reason: 'already_exists', slug, path: err.path };
+      log(`Dossier already exists at ${err.path}. Aborting (atomic init, no --force).`);
+      return { ok: false };
+    }
+    if (err && err.code === 'EDOSSIERSCHEMA') {
+      if (jsonOut) return { ok: false, reason: 'schema_violation', errors: err.errors };
+      log(`Dossier schema violation: ${err.errors.join('; ')}`);
+      return { ok: false };
+    }
+    if (err && err.code === 'EDOSSIERSLUG') {
+      if (jsonOut) return { ok: false, reason: 'invalid_slug', slug };
+      log(err.message);
+      return { ok: false };
+    }
+    throw err;
+  }
+}
+
+async function runDossierShow({ args = [], options = {}, logger } = {}) {
+  const targetDir = args[0] || '.';
+  const slug = pickSlug(options);
+  const jsonOut = Boolean(options.json);
+  const log = (msg) => { if (logger && !jsonOut) logger.log(msg); };
+
+  if (!slug) {
+    if (jsonOut) return { ok: false, reason: 'missing_slug' };
+    log('--slug=<feature-slug> is required.');
+    return { ok: false };
+  }
+  if (!isValidSlug(slug)) {
+    if (jsonOut) return { ok: false, reason: 'invalid_slug', slug };
+    log(`Invalid slug "${slug}" — must be kebab-case.`);
+    return { ok: false };
+  }
+
+  const ctxDir = resolveContextDir(targetDir);
+  try {
+    const result = await store.show({ slug, contextDir: ctxDir });
+    if (jsonOut) {
+      return {
+        ok: true,
+        slug,
+        path: result.path,
+        frontmatter: result.frontmatter,
+        sections: Object.keys(result.sections),
+        warn: result.warn || null
+      };
+    }
+    log(result.header);
+    log(result.raw);
+    if (result.warn === 'history_corrupted') {
+      log(`Warning: dossier-history.md is corrupted or unreadable — history content may be lost.`);
+    }
+    return { ok: true, path: result.path, warn: result.warn || null };
+  } catch (err) {
+    if (err && err.code === 'EDOSSIERMISSING') {
+      if (jsonOut) return { ok: false, reason: 'not_found', slug, path: err.path };
+      log(`Dossier not found for slug "${slug}" (expected at ${err.path}).`);
+      return { ok: false };
+    }
+    if (err && (err.code === 'EDOSSIERPARSE' || err.code === 'EDOSSIERSCHEMA')) {
+      if (jsonOut) return { ok: false, reason: err.code, errors: err.errors, message: err.message };
+      log(`Cannot read dossier: ${err.message}`);
+      return { ok: false };
+    }
+    throw err;
+  }
+}
+
+async function runDossierAddFinding({ args = [], options = {}, logger } = {}) {
+  const targetDir = args[0] || '.';
+  const slug = pickSlug(options);
+  const jsonOut = Boolean(options.json);
+  const log = (msg) => { if (logger && !jsonOut) logger.log(msg); };
+
+  if (!slug) {
+    if (jsonOut) return { ok: false, reason: 'missing_slug' };
+    log('--slug=<feature-slug> is required.');
+    return { ok: false };
+  }
+  if (!isValidSlug(slug)) {
+    if (jsonOut) return { ok: false, reason: 'invalid_slug', slug };
+    log(`Invalid slug "${slug}".`);
+    return { ok: false };
+  }
+
+  const agent = options.agent ? String(options.agent) : null;
+  const section = options.section ? String(options.section) : null;
+  const content = options.content ? String(options.content) : null;
+
+  if (!agent || !isCanonicalAgent(agent)) {
+    if (jsonOut) return { ok: false, reason: 'invalid_agent', agent };
+    log(`--agent=<canonical-agent-id> is required (got: ${JSON.stringify(agent)}).`);
+    return { ok: false };
+  }
+  if (!section || !section.trim()) {
+    if (jsonOut) return { ok: false, reason: 'missing_section' };
+    log('--section=<section-name> is required.');
+    return { ok: false };
+  }
+  if (!content || !content.trim()) {
+    if (jsonOut) return { ok: false, reason: 'missing_content' };
+    log('--content="..." is required.');
+    return { ok: false };
+  }
+
+  const ctxDir = resolveContextDir(targetDir);
+
+  try {
+    const result = await store.addFinding({ slug, contextDir: ctxDir, agent, section, content });
+    if (jsonOut) return { ok: true, slug, added: result.added, hash: result.hash };
+    if (result.added) {
+      log(`Finding added to dossier "${slug}" (section: ${section}, agent: ${agent}).`);
+    } else {
+      log(`Finding already recorded (idempotent — no-op).`);
+    }
+    return { ok: true, slug, added: result.added, hash: result.hash };
+  } catch (err) {
+    if (err && err.code === 'EDOSSIERMISSING') {
+      if (jsonOut) return { ok: false, reason: 'not_found', slug };
+      log(`Dossier not found for slug "${slug}". Run dossier:init first.`);
+      return { ok: false };
+    }
+    throw err;
+  }
+}
+
+async function runDossierAddCodemap({ args = [], options = {}, logger } = {}) {
+  const targetDir = args[0] || '.';
+  const slug = pickSlug(options);
+  const jsonOut = Boolean(options.json);
+  const log = (msg) => { if (logger && !jsonOut) logger.log(msg); };
+
+  if (!slug) {
+    if (jsonOut) return { ok: false, reason: 'missing_slug' };
+    log('--slug=<feature-slug> is required.');
+    return { ok: false };
+  }
+  if (!isValidSlug(slug)) {
+    if (jsonOut) return { ok: false, reason: 'invalid_slug', slug };
+    log(`Invalid slug "${slug}".`);
+    return { ok: false };
+  }
+
+  const filePath = options.file ? String(options.file) : null;
+  if (!filePath) {
+    if (jsonOut) return { ok: false, reason: 'missing_file' };
+    log('--file=<path> is required.');
+    return { ok: false };
+  }
+
+  const lines = options.lines ? String(options.lines) : undefined;
+  const role = options.role ? String(options.role) : undefined;
+  const coupling = options.coupling ? String(options.coupling) : undefined;
+  const addedBy = options['added-by'] ? String(options['added-by']) : undefined;
+
+  const ctxDir = resolveContextDir(targetDir);
+
+  try {
+    const result = await codemapStore.addCodemap({ slug, contextDir: ctxDir, filePath, lines, role, coupling, addedBy });
+    if (jsonOut) return { ok: true, slug, added: result.added, path: result.path, warn: result.warn || null };
+    if (result.added) {
+      log(`Code map entry added to dossier "${slug}": ${filePath}`);
+    } else {
+      log(`Entry already recorded (idempotent — no-op).`);
+    }
+    if (result.warn === 'file_not_found') {
+      log(`Warning: file not found on disk — "${filePath}" registered as planned file.`);
+    }
+    return { ok: true, slug, added: result.added, warn: result.warn || null };
+  } catch (err) {
+    if (err && err.code === 'EDOSSIERMISSING') {
+      if (jsonOut) return { ok: false, reason: 'not_found', slug };
+      log(`Dossier not found for slug "${slug}". Run dossier:init first.`);
+      return { ok: false };
+    }
+    if (err && err.code === 'ECODEMAPVALIDATION') {
+      if (jsonOut) return { ok: false, reason: 'validation_error', errors: err.errors };
+      log(`Validation error: ${err.errors.join('; ')}`);
+      return { ok: false };
+    }
+    throw err;
+  }
+}
+
+async function runDossierLinkRule({ args = [], options = {}, logger } = {}) {
+  const targetDir = args[0] || '.';
+  const slug = pickSlug(options);
+  const jsonOut = Boolean(options.json);
+  const log = (msg) => { if (logger && !jsonOut) logger.log(msg); };
+
+  if (!slug) {
+    if (jsonOut) return { ok: false, reason: 'missing_slug' };
+    log('--slug=<feature-slug> is required.');
+    return { ok: false };
+  }
+  if (!isValidSlug(slug)) {
+    if (jsonOut) return { ok: false, reason: 'invalid_slug', slug };
+    log(`Invalid slug "${slug}".`);
+    return { ok: false };
+  }
+
+  const rulePath = options.rule ? String(options.rule) : null;
+  if (!rulePath) {
+    if (jsonOut) return { ok: false, reason: 'missing_rule' };
+    log('--rule=<path> is required.');
+    return { ok: false };
+  }
+
+  const reason = options.reason ? String(options.reason) : undefined;
+  const ctxDir = resolveContextDir(targetDir);
+  const base = path.resolve(process.cwd(), targetDir || '.');
+
+  try {
+    const result = await codemapStore.linkRule({ slug, contextDir: ctxDir, rulePath, reason, targetDir: base });
+    if (jsonOut) return { ok: true, slug, added: result.added, path: result.path };
+    if (result.added) {
+      log(`Rule linked in dossier "${slug}": ${rulePath}`);
+    } else {
+      log(`Rule already linked (idempotent — no-op).`);
+    }
+    return { ok: true, slug, added: result.added };
+  } catch (err) {
+    if (err && err.code === 'EDOSSIERMISSING') {
+      if (jsonOut) return { ok: false, reason: 'not_found', slug };
+      log(`Dossier not found for slug "${slug}". Run dossier:init first.`);
+      return { ok: false };
+    }
+    if (err && err.code === 'ELINKREULEPATH') {
+      if (jsonOut) return { ok: false, reason: 'invalid_rule_path', message: err.message };
+      log(`Invalid rule path: ${err.message}`);
+      return { ok: false };
+    }
+    if (err && err.code === 'ELINKREULENOTFOUND') {
+      if (jsonOut) return { ok: false, reason: 'rule_not_found', path: err.path };
+      log(`Rule file not found: ${err.path}`);
+      return { ok: false };
+    }
+    throw err;
+  }
+}
+
+async function runDossierCompact({ args = [], options = {}, logger } = {}) {
+  const targetDir = args[0] || '.';
+  const slug = pickSlug(options);
+  const jsonOut = Boolean(options.json);
+  const log = (msg) => { if (logger && !jsonOut) logger.log(msg); };
+
+  if (!slug) {
+    if (jsonOut) return { ok: false, reason: 'missing_slug' };
+    log('--slug=<feature-slug> is required.');
+    return { ok: false };
+  }
+  if (!isValidSlug(slug)) {
+    if (jsonOut) return { ok: false, reason: 'invalid_slug', slug };
+    log(`Invalid slug "${slug}".`);
+    return { ok: false };
+  }
+
+  const force = Boolean(options.force);
+  const ctxDir = resolveContextDir(targetDir);
+
+  try {
+    const result = await compact({ slug, contextDir: ctxDir, force });
+    if (jsonOut) return { ok: true, slug, ...result };
+    if (!result.compacted) {
+      log(`Compaction skipped: ${result.reason} (${result.sizeBytes} bytes).`);
+    } else {
+      log(`Dossier compacted: ${result.migratedSections.length} section(s) migrated to history.`);
+      log(`  Active size: ${result.activeSizeBytes} bytes`);
+      log(`  History: ${result.historyPath}`);
+    }
+    return { ok: true, slug, ...result };
+  } catch (err) {
+    if (err && err.code === 'EDOSSIERMISSING') {
+      if (jsonOut) return { ok: false, reason: 'not_found', slug };
+      log(`Dossier not found for slug "${slug}". Run dossier:init first.`);
+      return { ok: false };
+    }
+    throw err;
+  }
+}
+
+module.exports = {
+  runDossierInit,
+  runDossierShow,
+  runDossierAddFinding,
+  runDossierAddCodemap,
+  runDossierLinkRule,
+  runDossierCompact
+};