dotmd-cli 0.1.0

package/src/config.mjs

@@ -0,0 +1,197 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const CONFIG_FILENAMES = ['dotmd.config.mjs', '.dotmd.config.mjs', 'dotmd.config.js'];
+
+const DEFAULTS = {
+  root: '.',
+  archiveDir: 'archived',
+  excludeDirs: [],
+
+  statuses: {
+    order: ['active', 'ready', 'planned', 'research', 'blocked', 'reference', 'archived'],
+    staleDays: {
+      active: 14,
+      ready: 14,
+      planned: 30,
+      blocked: 30,
+      research: 30,
+    },
+  },
+
+  lifecycle: {
+    archiveStatuses: ['archived'],
+    skipStaleFor: ['archived', 'reference'],
+    skipWarningsFor: ['archived'],
+  },
+
+  taxonomy: {
+    surfaces: null,
+    moduleRequiredFor: [],
+  },
+
+  index: null,
+
+  context: {
+    expanded: ['active'],
+    listed: ['ready', 'planned'],
+    counted: ['blocked', 'research', 'reference', 'archived'],
+    recentDays: 3,
+    recentStatuses: ['active', 'ready', 'planned'],
+    recentLimit: 10,
+    truncateNextStep: 80,
+  },
+
+  display: {
+    lineWidth: 0,
+    truncateTitle: 30,
+    truncateNextStep: 80,
+  },
+
+  referenceFields: {
+    bidirectional: [],
+    unidirectional: [],
+  },
+
+  presets: {
+    stale: ['--status', 'active,ready,planned,blocked,research', '--stale', '--sort', 'updated', '--all'],
+    actionable: ['--status', 'active,ready', '--has-next-step', '--sort', 'updated', '--all'],
+  },
+};
+
+function findConfigFile(startDir) {
+  let dir = path.resolve(startDir);
+  const root = path.parse(dir).root;
+
+  while (dir !== root) {
+    for (const filename of CONFIG_FILENAMES) {
+      const candidate = path.join(dir, filename);
+      if (existsSync(candidate)) return candidate;
+    }
+    dir = path.dirname(dir);
+  }
+
+  return null;
+}
+
+function deepMerge(defaults, overrides) {
+  const result = { ...defaults };
+  for (const [key, value] of Object.entries(overrides)) {
+    if (value != null && typeof value === 'object' && !Array.isArray(value) &&
+        result[key] != null && typeof result[key] === 'object' && !Array.isArray(result[key])) {
+      result[key] = deepMerge(result[key], value);
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
+export async function resolveConfig(cwd, explicitConfigPath) {
+  const configPath = explicitConfigPath
+    ? path.resolve(cwd, explicitConfigPath)
+    : findConfigFile(cwd);
+
+  let userConfig = {};
+  let hooks = {};
+  let configDir = cwd;
+
+  if (configPath && existsSync(configPath)) {
+    const configUrl = pathToFileURL(configPath).href;
+    const mod = await import(configUrl);
+
+    configDir = path.dirname(configPath);
+
+    for (const [key, value] of Object.entries(mod)) {
+      if (key === 'default') continue;
+      if (typeof value === 'function') {
+        hooks[key] = value;
+      } else {
+        userConfig[key] = value;
+      }
+    }
+  }
+
+  // Backwards compat: `readme` config key maps to `index`
+  if (userConfig.readme && !userConfig.index) {
+    userConfig.index = userConfig.readme;
+    delete userConfig.readme;
+  }
+
+  const config = deepMerge(DEFAULTS, userConfig);
+
+  const docsRoot = path.resolve(configDir, config.root);
+
+  // Find repo root by walking up looking for .git
+  let repoRoot = configDir;
+  {
+    let dir = configDir;
+    const fsRoot = path.parse(dir).root;
+    while (dir !== fsRoot) {
+      if (existsSync(path.join(dir, '.git'))) {
+        repoRoot = dir;
+        break;
+      }
+      dir = path.dirname(dir);
+    }
+  }
+
+  const statusOrder = config.statuses.order;
+  const validStatuses = new Set(statusOrder);
+  const staleDaysByStatus = {};
+  for (const status of statusOrder) {
+    staleDaysByStatus[status] = config.statuses.staleDays?.[status] ?? null;
+  }
+
+  const validSurfaces = config.taxonomy.surfaces
+    ? new Set(config.taxonomy.surfaces)
+    : null;
+  const moduleRequiredStatuses = new Set(config.taxonomy.moduleRequiredFor);
+
+  const indexPath = config.index?.path
+    ? path.resolve(repoRoot, config.index.path)
+    : null;
+
+  // Compute docs root relative path for index link stripping
+  const docsRootRelative = path.relative(repoRoot, docsRoot).split(path.sep).join('/');
+  const docsRootPrefix = docsRootRelative ? docsRootRelative + '/' : '';
+
+  // Lifecycle config
+  const lifecycle = config.lifecycle;
+  const archiveStatuses = new Set(lifecycle.archiveStatuses);
+  const skipStaleFor = new Set(lifecycle.skipStaleFor);
+  const skipWarningsFor = new Set(lifecycle.skipWarningsFor);
+
+  return {
+    raw: config,
+
+    docsRoot,
+    repoRoot,
+    configDir,
+    configPath: configPath ?? null,
+    archiveDir: config.archiveDir,
+    excludeDirs: new Set(config.excludeDirs),
+    docsRootPrefix,
+
+    statusOrder,
+    validStatuses,
+    staleDaysByStatus,
+
+    lifecycle: { archiveStatuses, skipStaleFor, skipWarningsFor },
+
+    validSurfaces,
+    moduleRequiredStatuses,
+
+    indexPath,
+    indexStartMarker: config.index?.startMarker ?? '<!-- GENERATED:dotmd:start -->',
+    indexEndMarker: config.index?.endMarker ?? '<!-- GENERATED:dotmd:end -->',
+    archivedHighlightLimit: config.index?.archivedLimit ?? 8,
+
+    context: config.context,
+    display: config.display,
+    referenceFields: config.referenceFields,
+    presets: config.presets,
+    hooks,
+  };
+}

package/src/extractors.mjs

@@ -0,0 +1,60 @@
+export function extractFirstHeading(body) {
+  return body.match(/^#\s+(.+)$/m)?.[1]?.trim() ?? null;
+}
+
+export function extractSummary(body) {
+  const blockquoteLines = body
+    .split('\n')
+    .filter(line => line.startsWith('> '))
+    .map(line => line.slice(2).trim())
+    .filter(Boolean);
+
+  const nonStatusLine = blockquoteLines.find(line => !/^Status note\b/i.test(line));
+  return nonStatusLine ?? blockquoteLines[0] ?? null;
+}
+
+export function extractStatusSnapshot(body) {
+  const statusNoteMatch = body.match(/^>\s+Status note(?:\s+\([^)]+\))?:\s*(.+)$/m);
+  if (statusNoteMatch) return statusNoteMatch[1].trim();
+
+  const boldStatusMatch = body.match(/^\*\*Status:\*\*\s*(.+)$/m);
+  if (boldStatusMatch) return boldStatusMatch[1].trim();
+
+  const plainStatusMatch = body.match(/^-\s+Status:\s*(.+)$/m);
+  if (plainStatusMatch) return plainStatusMatch[1].trim();
+
+  return null;
+}
+
+export function extractNextStep(body) {
+  const match = body.match(/^##+\s+(?:Suggested\s+)?Next Step\s*$([\s\S]*?)(?=^##+\s|\Z)/m);
+  if (!match) return null;
+
+  const lines = match[1]
+    .split('\n')
+    .map(line => line.trim())
+    .filter(Boolean)
+    .map(line => line.replace(/^[-*]\s+/, ''));
+
+  return lines[0] ?? null;
+}
+
+export function extractChecklistCounts(body) {
+  const matches = [...body.matchAll(/^\s*[-*]\s+\[([ xX])\]\s+/gm)];
+  let completed = 0;
+  let open = 0;
+
+  for (const match of matches) {
+    if (match[1].toLowerCase() === 'x') {
+      completed += 1;
+    } else {
+      open += 1;
+    }
+  }
+
+  return {
+    completed,
+    open,
+    total: completed + open,
+  };
+}

package/src/frontmatter.mjs

@@ -0,0 +1,55 @@
+export function extractFrontmatter(raw) {
+  if (!raw.startsWith('---\n')) {
+    return { frontmatter: '', body: raw };
+  }
+
+  const endMarker = raw.indexOf('\n---\n', 4);
+  if (endMarker === -1) {
+    return { frontmatter: '', body: raw };
+  }
+
+  return {
+    frontmatter: raw.slice(4, endMarker),
+    body: raw.slice(endMarker + 5),
+  };
+}
+
+export function parseSimpleFrontmatter(text) {
+  const data = {};
+  let currentArrayKey = null;
+
+  for (const rawLine of text.split('\n')) {
+    const line = rawLine.replace(/\r$/, '');
+    if (!line.trim()) continue;
+
+    const keyMatch = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (keyMatch) {
+      const [, key, rawValue] = keyMatch;
+      if (!rawValue.trim()) {
+        data[key] = [];
+        currentArrayKey = key;
+      } else {
+        data[key] = parseScalar(rawValue.trim());
+        currentArrayKey = null;
+      }
+      continue;
+    }
+
+    if (currentArrayKey) {
+      const itemMatch = line.match(/^\s*-\s+(.*)$/);
+      if (itemMatch) {
+        data[currentArrayKey].push(parseScalar(itemMatch[1].trim()));
+        continue;
+      }
+    }
+  }
+
+  return data;
+}
+
+function parseScalar(value) {
+  const unquoted = value.replace(/^['"]|['"]$/g, '');
+  if (unquoted === 'true') return true;
+  if (unquoted === 'false') return false;
+  return unquoted;
+}

package/src/git.mjs

@@ -0,0 +1,18 @@
+import { spawnSync } from 'node:child_process';
+
+export function getGitLastModified(relPath, repoRoot) {
+  const result = spawnSync('git', ['log', '-1', '--format=%aI', '--', relPath], {
+    cwd: repoRoot,
+    encoding: 'utf8',
+  });
+  if (result.status !== 0 || !result.stdout.trim()) return null;
+  return result.stdout.trim();
+}
+
+export function gitMv(source, target, repoRoot) {
+  const result = spawnSync('git', ['mv', source, target], {
+    cwd: repoRoot,
+    encoding: 'utf8',
+  });
+  return { status: result.status, stderr: result.stderr };
+}

package/src/index-file.mjs

@@ -0,0 +1,104 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { capitalize, escapeTable } from './util.mjs';
+import { formatSnapshot } from './render.mjs';
+
+export function renderIndexFile(index, config) {
+  const current = readFileSync(config.indexPath, 'utf8');
+  const start = current.indexOf(config.indexStartMarker);
+  const end = current.indexOf(config.indexEndMarker);
+
+  if (start === -1 || end === -1 || end < start) {
+    throw new Error(`${config.indexPath} is missing generated block markers.`);
+  }
+
+  const before = current.slice(0, start + config.indexStartMarker.length);
+  const after = current.slice(end);
+  const generated = `\n\n${renderGeneratedBlock(index, config)}\n`;
+  return `${before}${generated}${after}`;
+}
+
+function renderGeneratedBlock(index, config) {
+  const lines = [];
+  const prefix = config.docsRootPrefix;
+
+  for (const status of config.statusOrder) {
+    const docs = index.docs.filter(doc => doc.status === status);
+    if (docs.length === 0) continue;
+
+    if (config.lifecycle.archiveStatuses.has(status)) {
+      lines.push(...renderArchivedSection(docs, config, status));
+      lines.push('');
+      continue;
+    }
+
+    lines.push(`## ${capitalize(status)}`);
+    lines.push('');
+    lines.push('| Doc | Status Snapshot |');
+    lines.push('|-----|-----------------|');
+    for (const doc of docs) {
+      const snapshot = formatSnapshot(doc, config);
+      const linkPath = prefix ? doc.path.replace(prefix, '') : doc.path;
+      lines.push(`| [${escapeTable(doc.title)}](${linkPath}) | ${escapeTable(snapshot)} |`);
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n').trimEnd();
+}
+
+function renderArchivedSection(docs, config, status) {
+  const lines = [];
+  const limit = config.archivedHighlightLimit;
+  const prefix = config.docsRootPrefix;
+  const highlights = docs
+    .filter(doc => doc.currentState && doc.currentState !== 'No current_state set')
+    .sort((a, b) => {
+      const aUpdated = a.updated ?? '';
+      const bUpdated = b.updated ?? '';
+      return bUpdated.localeCompare(aUpdated);
+    })
+    .slice(0, limit);
+
+  lines.push(`## ${capitalize(status)}`);
+  lines.push('');
+  lines.push(`${capitalize(status)} docs are indexed by the CLI/JSON output. Showing ${highlights.length} recent or high-signal highlights out of ${docs.length} ${status} docs:`);
+  lines.push('');
+  lines.push('| Doc | Status Snapshot |');
+  lines.push('|-----|-----------------|');
+  for (const doc of highlights) {
+    const linkPath = prefix ? doc.path.replace(prefix, '') : doc.path;
+    lines.push(`| [${escapeTable(doc.title)}](${linkPath}) | ${escapeTable(formatSnapshot(doc, config))} |`);
+  }
+  lines.push('');
+  lines.push('- Use `dotmd list` or `dotmd json` for the full inventory.');
+
+  return lines;
+}
+
+export function writeIndex(content, config) {
+  writeFileSync(config.indexPath, content, 'utf8');
+}
+
+export function checkIndex(docs, config) {
+  const warnings = [];
+  const errors = [];
+
+  if (!config.indexPath) return { warnings, errors };
+
+  const current = readFileSync(config.indexPath, 'utf8');
+  const start = current.indexOf(config.indexStartMarker);
+  const end = current.indexOf(config.indexEndMarker);
+
+  if (start === -1 || end === -1 || end < start) {
+    errors.push({ path: config.indexPath, level: 'error', message: 'Missing generated index block markers.' });
+    return { warnings, errors };
+  }
+
+  const index = { docs };
+  const expected = renderIndexFile(index, config);
+  if (expected !== current) {
+    errors.push({ path: config.indexPath, level: 'error', message: 'Generated index block is stale. Run `dotmd index`.' });
+  }
+
+  return { warnings, errors };
+}

package/src/index.mjs

@@ -0,0 +1,151 @@
+import { readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
+import { extractFirstHeading, extractSummary, extractStatusSnapshot, extractNextStep, extractChecklistCounts } from './extractors.mjs';
+import { asString, normalizeStringList, normalizeBlockers, mergeUniqueStrings, toRepoPath } from './util.mjs';
+import { validateDoc, checkBidirectionalReferences, checkGitStaleness, computeDaysSinceUpdate, computeIsStale, computeChecklistCompletionRate } from './validate.mjs';
+import { checkIndex } from './index-file.mjs';
+
+export function buildIndex(config) {
+  const docs = collectDocFiles(config).map(f => parseDocFile(f, config));
+  const warnings = [];
+  const errors = [];
+
+  for (const doc of docs) {
+    warnings.push(...doc.warnings);
+    errors.push(...doc.errors);
+  }
+
+  if (config.hooks.validate) {
+    const ctx = { config, allDocs: docs, repoRoot: config.repoRoot };
+    for (const doc of docs) {
+      const result = config.hooks.validate(doc, ctx);
+      if (result?.errors) {
+        doc.errors.push(...result.errors);
+        errors.push(...result.errors);
+      }
+      if (result?.warnings) {
+        doc.warnings.push(...result.warnings);
+        warnings.push(...result.warnings);
+      }
+    }
+  }
+
+  const transformedDocs = config.hooks.transformDoc
+    ? docs.map(d => config.hooks.transformDoc(d) ?? d)
+    : docs;
+
+  const countsByStatus = Object.fromEntries(config.statusOrder.map(status => [
+    status,
+    transformedDocs.filter(doc => doc.status === status).length,
+  ]));
+
+  if (config.indexPath) {
+    const indexCheck = checkIndex(transformedDocs, config);
+    warnings.push(...indexCheck.warnings);
+    errors.push(...indexCheck.errors);
+  }
+
+  const refCheck = checkBidirectionalReferences(transformedDocs, config);
+  warnings.push(...refCheck.warnings);
+
+  const gitWarnings = checkGitStaleness(transformedDocs, config);
+  warnings.push(...gitWarnings);
+
+  return {
+    generatedAt: new Date().toISOString(),
+    docs: transformedDocs,
+    countsByStatus,
+    warnings,
+    errors,
+  };
+}
+
+export function collectDocFiles(config) {
+  const files = [];
+  const skipPaths = new Set();
+  if (config.indexPath) skipPaths.add(config.indexPath);
+  walkMarkdownFiles(config.docsRoot, files, config.excludeDirs, skipPaths);
+  return files.sort((a, b) => a.localeCompare(b));
+}
+
+function walkMarkdownFiles(directory, files, excludedDirs, skipPaths) {
+  let entries;
+  try {
+    entries = readdirSync(directory, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      if (excludedDirs && excludedDirs.has(entry.name)) continue;
+      walkMarkdownFiles(path.join(directory, entry.name), files, excludedDirs, skipPaths);
+      continue;
+    }
+    const fullPath = path.join(directory, entry.name);
+    if (!entry.isFile() || !entry.name.endsWith('.md') || skipPaths.has(fullPath)) continue;
+    files.push(fullPath);
+  }
+}
+
+export function parseDocFile(filePath, config) {
+  const relativePath = toRepoPath(filePath, config.repoRoot);
+  const raw = readFileSync(filePath, 'utf8');
+  const { frontmatter, body } = extractFrontmatter(raw);
+  const parsedFrontmatter = parseSimpleFrontmatter(frontmatter);
+  const headingTitle = extractFirstHeading(body);
+  const title = asString(parsedFrontmatter.title) ?? headingTitle ?? path.basename(filePath, '.md');
+  const summary = asString(parsedFrontmatter.summary) ?? extractSummary(body) ?? null;
+  const currentState = asString(parsedFrontmatter.current_state) ?? extractStatusSnapshot(body) ?? 'No current_state set';
+  const nextStep = asString(parsedFrontmatter.next_step) ?? extractNextStep(body) ?? null;
+  const blockers = normalizeBlockers(parsedFrontmatter.blockers);
+  const surface = asString(parsedFrontmatter.surface) ?? null;
+  const surfaces = normalizeStringList(parsedFrontmatter.surfaces);
+  const moduleName = asString(parsedFrontmatter.module) ?? null;
+  const modules = normalizeStringList(parsedFrontmatter.modules);
+  const domain = asString(parsedFrontmatter.domain) ?? null;
+  const audience = asString(parsedFrontmatter.audience) ?? null;
+  const executionMode = asString(parsedFrontmatter.execution_mode) ?? null;
+  const checklist = extractChecklistCounts(body);
+
+  // Dynamic reference field extraction
+  const refFields = {};
+  for (const field of [...(config.referenceFields.bidirectional || []), ...(config.referenceFields.unidirectional || [])]) {
+    refFields[field] = normalizeStringList(parsedFrontmatter[field]);
+  }
+
+  const doc = {
+    path: relativePath,
+    status: asString(parsedFrontmatter.status) ?? null,
+    owner: asString(parsedFrontmatter.owner) ?? null,
+    surface,
+    surfaces: mergeUniqueStrings(surface ? [surface] : [], surfaces),
+    module: moduleName,
+    modules: mergeUniqueStrings(moduleName ? [moduleName] : [], modules),
+    domain,
+    audience,
+    executionMode,
+    title,
+    summary,
+    currentState,
+    nextStep,
+    blockers,
+    updated: asString(parsedFrontmatter.updated) ?? null,
+    created: asString(parsedFrontmatter.created) ?? null,
+    audited: asString(parsedFrontmatter.audited) ?? null,
+    auditLevel: asString(parsedFrontmatter.audit_level) ?? null,
+    sourceOfTruth: asString(parsedFrontmatter.source_of_truth) ?? null,
+    checklist,
+    refFields,
+    checklistCompletionRate: computeChecklistCompletionRate(checklist),
+    hasNextStep: Boolean(nextStep),
+    hasBlockers: blockers.length > 0,
+    daysSinceUpdate: computeDaysSinceUpdate(asString(parsedFrontmatter.updated) ?? null),
+    isStale: computeIsStale(asString(parsedFrontmatter.status), asString(parsedFrontmatter.updated) ?? null, config),
+    warnings: [],
+    errors: [],
+  };
+
+  validateDoc(doc, parsedFrontmatter, headingTitle, config);
+  return doc;
+}

package/src/init.mjs

@@ -0,0 +1,60 @@
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { green, dim } from './color.mjs';
+
+const STARTER_CONFIG = `// dotmd.config.mjs — document management configuration
+// All exports are optional. See dotmd.config.example.mjs for full reference.
+
+export const root = 'docs';
+
+export const index = {
+  path: 'docs/docs.md',
+  startMarker: '<!-- GENERATED:dotmd:start -->',
+  endMarker: '<!-- GENERATED:dotmd:end -->',
+  archivedLimit: 8,
+};
+`;
+
+const STARTER_INDEX = `# Docs
+
+<!-- GENERATED:dotmd:start -->
+
+_No docs yet. Run \`dotmd list\` after creating your first document._
+
+<!-- GENERATED:dotmd:end -->
+`;
+
+export function runInit(cwd) {
+  const configPath = path.join(cwd, 'dotmd.config.mjs');
+  const docsDir = path.join(cwd, 'docs');
+  const indexPath = path.join(docsDir, 'docs.md');
+
+  process.stdout.write('\n');
+
+  if (existsSync(configPath)) {
+    process.stdout.write(`  ${dim('exists')}  dotmd.config.mjs\n`);
+  } else {
+    writeFileSync(configPath, STARTER_CONFIG, 'utf8');
+    process.stdout.write(`  ${green('create')}  dotmd.config.mjs\n`);
+  }
+
+  if (existsSync(docsDir)) {
+    process.stdout.write(`  ${dim('exists')}  docs/\n`);
+  } else {
+    mkdirSync(docsDir, { recursive: true });
+    process.stdout.write(`  ${green('create')}  docs/\n`);
+  }
+
+  if (existsSync(indexPath)) {
+    process.stdout.write(`  ${dim('exists')}  docs/docs.md\n`);
+  } else {
+    writeFileSync(indexPath, STARTER_INDEX, 'utf8');
+    process.stdout.write(`  ${green('create')}  docs/docs.md\n`);
+  }
+
+  const today = new Date().toISOString().slice(0, 10);
+  process.stdout.write(`\nReady. Create your first doc:\n`);
+  process.stdout.write(`  printf '---\\nstatus: active\\nupdated: ${today}\\n---\\n\\n# My Doc\\n' > docs/my-doc.md\n`);
+  process.stdout.write(`  dotmd list\n\n`);
+}
+