dotmd-cli 0.69.0 → 0.70.1

package/src/statuses.mjs

@@ -14,6 +14,7 @@ import { collectDocFiles } from './index.mjs';
 import { asString, toRepoPath, die } from './util.mjs';
 import { bold, dim, green, yellow } from './color.mjs';
 import { isInteractive, promptText } from './prompt.mjs';
+import { resolveStatusMetadata } from './status-metadata.mjs';
 import {
   parseStatusesBlock,
   renderEntryLine,
@@ -95,34 +96,18 @@ function runListStatuses(args, config) {
 }
 
 function describeTypeStatuses(typeName, config) {
-  const typeDef = config.raw?.types?.[typeName];
-  if (!typeDef) return {};
   const result = {};
-  // After resolveConfig, rich-form types have been normalized into an array.
-  // Reconstruct each status's effective flags from derived sets.
-  const statusList = Array.isArray(typeDef.statuses) ? typeDef.statuses : Object.keys(typeDef.statuses ?? {});
-  const ctx = typeDef.context ?? {};
-  const ctxByStatus = {};
-  for (const [bucket, names] of Object.entries(ctx)) {
-    for (const n of names) ctxByStatus[n] = bucket;
-  }
-  const stale = typeDef.staleDays ?? {};
-  const lc = config.lifecycle;
-  const moduleReq = config.moduleRequiredStatuses;
-
-  for (const name of statusList) {
-    const skipStale = lc.skipStaleFor.has(name);
-    const skipWarnings = lc.skipWarningsFor.has(name);
-    const quiet = skipStale && skipWarnings;
+  for (const metadata of resolveStatusMetadata(config).byType[typeName] ?? []) {
+    const { name } = metadata;
     result[name] = {
-      context: ctxByStatus[name] ?? null,
-      staleDays: stale[name] ?? null,
-      requiresModule: moduleReq.has(name),
-      terminal: lc.terminalStatuses.has(name),
-      archive: lc.archiveStatuses.has(name),
-      skipStale,
-      skipWarnings,
-      quiet,
+      context: metadata.context,
+      staleDays: metadata.staleDays,
+      requiresModule: metadata.requiresModule,
+      terminal: metadata.terminal,
+      archive: metadata.archive,
+      skipStale: metadata.skipStale,
+      skipWarnings: metadata.skipWarnings,
+      quiet: metadata.quiet,
     };
   }
   return result;

package/src/summary.mjs

@@ -37,10 +37,13 @@ export function runSummary(argv, config) {
   const opts = {};
   if (model) opts.model = model;
   if (maxTokens) opts.maxTokens = maxTokens;
+  const previewSkipped = Boolean(config._execution?.suppressSideEffects);
 
   let summary;
   try {
-    summary = config.hooks.summarizeDoc
+    summary = previewSkipped
+      ? null
+      : config.hooks.summarizeDoc
       ? config.hooks.summarizeDoc(body, meta)
       : summarizeDocBody(body, meta, opts);
   } catch (err) {
@@ -49,13 +52,21 @@ export function runSummary(argv, config) {
   }
 
   if (json) {
-    process.stdout.write(JSON.stringify({ path: repoPath, title, status, summary: summary ?? null }, null, 2) + '\n');
+    process.stdout.write(JSON.stringify({
+      path: repoPath,
+      title,
+      status,
+      summary: summary ?? null,
+      summaryStatus: previewSkipped ? 'skipped-preview' : summary ? 'generated' : 'unavailable',
+    }, null, 2) + '\n');
     return;
   }
 
   process.stdout.write(`${bold(title)} ${dim(`(${status})`)}\n`);
   process.stdout.write(`${dim(repoPath)}\n\n`);
-  if (summary) {
+  if (previewSkipped) {
+    process.stdout.write(dim('[preview] Summary generation skipped; models and custom summarizeDoc hooks are not invoked.') + '\n');
+  } else if (summary) {
     process.stdout.write(`${summary}\n`);
   } else {
     process.stdout.write(dim('Summary unavailable (model call failed or uv not installed).') + '\n');

package/src/update.mjs

@@ -29,23 +29,31 @@ export function compareVersions(a, b) {
 // Read Claude Code's plugin install record to find the installed dotmd plugin's
 // id + version. Network-free. `opts.home` is injectable for tests. Returns
 // { id, version } or null when nothing is installed / the file is absent.
-export function readInstalledPlugin(opts = {}) {
+export function readInstalledPluginRecords(opts = {}) {
   const home = opts.home || os.homedir();
   const file = path.join(home, '.claude', 'plugins', 'installed_plugins.json');
   try {
     const j = JSON.parse(readFileSync(file, 'utf8'));
     const plugins = j.plugins || {};
-    const id = plugins[DEFAULT_PLUGIN_ID]
-      ? DEFAULT_PLUGIN_ID
-      : Object.keys(plugins).find(k => /^dotmd@/.test(k));
+    const id = opts.id
+      ? (plugins[opts.id] ? opts.id : null)
+      : plugins[DEFAULT_PLUGIN_ID]
+        ? DEFAULT_PLUGIN_ID
+        : Object.keys(plugins).find(k => /^dotmd@/.test(k));
     if (!id) return null;
-    const entry = Array.isArray(plugins[id]) ? plugins[id][0] : plugins[id];
-    return { id, version: entry?.version ?? null };
+    const entries = Array.isArray(plugins[id]) ? plugins[id] : [plugins[id]];
+    return { id, entries: entries.filter(Boolean) };
   } catch {
     return null;
   }
 }
 
+export function readInstalledPlugin(opts = {}) {
+  const records = readInstalledPluginRecords(opts);
+  if (!records) return null;
+  return { id: records.id, version: records.entries[0]?.version ?? null };
+}
+
 // Decide which steps `dotmd update` should run. Pure — no side effects — so the
 // orchestration is unit-testable. `opts` = { cliOnly, pluginOnly }; `ctx` =
 // { plugin: {id,version}|null, hasClaude, hasNpm }.
@@ -77,7 +85,11 @@ function which(bin) {
   }
 }
 
-export function runUpdate(argv, _config) {
+function executableName(bin) {
+  return process.platform === 'win32' && !bin.endsWith('.cmd') ? `${bin}.cmd` : bin;
+}
+
+export function runUpdate(argv, _config, opts = {}) {
   const check = argv.includes('--check');
   const cliOnly = argv.includes('--cli-only');
   const pluginOnly = argv.includes('--plugin-only');
@@ -99,18 +111,34 @@ export function runUpdate(argv, _config) {
   }
 
   const steps = planUpdate({ cliOnly, pluginOnly }, { plugin, hasClaude: which('claude'), hasNpm: which('npm') });
+  if (opts.dryRun) {
+    for (const step of steps) {
+      if (step.kind === 'skip') process.stdout.write(dim(`[dry-run] skip: ${step.reason}\n`));
+      else process.stdout.write(dim(`[dry-run] Would run: ${step.cmd.join(' ')}\n`));
+    }
+    return;
+  }
   let ran = false;
+  let failed = false;
   for (const s of steps) {
     if (s.kind === 'skip') {
       process.stdout.write(dim(`skip: ${s.reason}\n`));
       continue;
     }
     process.stdout.write(dim(`$ ${s.cmd.join(' ')}\n`));
-    const r = spawnSync(s.cmd[0], s.cmd.slice(1), { stdio: 'inherit' });
+    const r = spawnSync(executableName(s.cmd[0]), s.cmd.slice(1), {
+      stdio: 'inherit',
+      shell: process.platform === 'win32',
+    });
     ran = true;
-    if (r.status !== 0) process.stdout.write(yellow(`(${s.cmd[0]} exited ${r.status ?? '?'})\n`));
+    if (r.status !== 0) {
+      failed = true;
+      process.stdout.write(yellow(`(${s.cmd[0]} exited ${r.status ?? '?'})\n`));
+      break;
+    }
   }
-  if (ran) {
+  if (ran && !failed) {
     process.stdout.write(green('\n✓ restart your Claude Code session (or /reload-plugins) to apply.\n'));
   }
+  if (failed) process.exitCode = 1;
 }

package/src/use.mjs

@@ -1,4 +1,5 @@
-import { readFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
 import { asString, die, resolveDocPath, toRepoPath } from './util.mjs';
 import { consumePrompt, pendingPromptsOldestFirst, resolvePromptInput } from './prompts.mjs';
@@ -26,7 +27,9 @@ export async function runUse(argv, config, opts = {}) {
   // Exact path first, then prompt slugs (they keep precedence on a slug
   // collision — consuming a prompt is the more common intent), then the
   // shared resolver for plan/doc slugs, which dies with did-you-mean on miss.
+  const cwdPath = path.resolve(process.cwd(), positional);
   const filePath = resolveDocPath(positional, config)
+    ?? (existsSync(cwdPath) ? cwdPath : null)
     ?? resolvePromptInput(positional, config, { dieOnMiss: false })
     ?? resolveDocArg(positional, config);
 

package/src/util.mjs

@@ -6,6 +6,7 @@ import { dim } from './color.mjs';
 // Stable identifier for the current shell/agent session. Used for journal
 // attribution and hint de-duplication — not for any plan locking.
 export function currentSessionId() {
+  if (process.env.DOTMD_SESSION_ID) return process.env.DOTMD_SESSION_ID;
   if (process.env.CLAUDE_CODE_SESSION_ID) return process.env.CLAUDE_CODE_SESSION_ID;
   if (process.env.CLAUDE_SESSION_ID) return process.env.CLAUDE_SESSION_ID;
   if (process.env.TERM_SESSION_ID) return `term:${process.env.TERM_SESSION_ID}`;

package/src/validate.mjs

@@ -1,6 +1,6 @@
 import path from 'node:path';
 import { asString, resolveRefPath, suggestCandidates } from './util.mjs';
-import { getGitLastModified, getGitLastModifiedBatch } from './git.mjs';
+import { getGitLastModified, getGitLastModifiedBatch, getGitLastSubstantiveModifiedBatch } from './git.mjs';
 import { toRepoPath } from './util.mjs';
 
 const NOW = new Date();
@@ -156,17 +156,27 @@ export function validateDoc(doc, frontmatter, headingTitle, config) {
   if (!config.lifecycle.skipWarningsFor.has(doc.status)) {
     for (const { singular, plural } of [{ singular: 'module', plural: 'modules' }, { singular: 'surface', plural: 'surfaces' }]) {
       const singularValue = frontmatter[singular];
-      if (!singularValue) continue;
-      const pluralValue = Array.isArray(frontmatter[plural]) ? frontmatter[plural] : [];
+      if (!Object.prototype.hasOwnProperty.call(frontmatter, singular)) continue;
+      const rawPluralValue = frontmatter[plural];
+      const pluralValue = Array.isArray(rawPluralValue)
+        ? rawPluralValue
+        : rawPluralValue === undefined ? [] : [rawPluralValue];
+      const singularValues = Array.isArray(singularValue) ? singularValue : [singularValue];
       const merged = [];
-      for (const v of [singularValue, ...pluralValue]) {
+      for (const v of [...singularValues, ...pluralValue]) {
         if (typeof v === 'string' && v && !merged.includes(v)) merged.push(v);
       }
-      const target = `${plural}: [${merged.map(v => `"${v}"`).join(', ')}]`;
+      const target = `${plural}: [${merged.map(v => JSON.stringify(v)).join(', ')}]`;
+      const autoFixableString = value => typeof value === 'string' && !/(^|\s)#/.test(value);
+      const autoFixable = singularValues.every(autoFixableString)
+        && pluralValue.every(autoFixableString);
+      const guidance = autoFixable
+        ? `use \`${target}\`. Run \`dotmd lint --fix\` to migrate.`
+        : `use a \`${plural}:\` YAML list. Remove the deprecated \`${singular}:\` block manually and preserve all of its values.`;
       doc.warnings.push({
         path: doc.path,
         level: 'warning',
-        message: `\`${singular}:\` (singular) is deprecated — use \`${target}\`. Run \`dotmd lint --fix\` to migrate.`,
+        message: `\`${singular}:\` (singular) is deprecated — ${guidance}`,
       });
     }
   }
@@ -519,16 +529,35 @@ export function checkRoadmapHubExecutionMode(docs, config) {
   return warnings;
 }
 
-export function checkGitStaleness(docs, config) {
+export function checkGitStaleness(docs, config, options = {}) {
   const warnings = [];
-  const gitDates = getGitLastModifiedBatch(config.repoRoot);
-  for (const doc of docs) {
-    if (config.lifecycle.skipStaleFor.has(doc.status)) continue;
-    if (!doc.updated) continue;
+  const eligibleDocs = docs.filter(doc => !config.lifecycle.skipStaleFor.has(doc.status) && doc.updated);
+  const pathspecs = (config.docsRoots || [config.docsRoot])
+    .map(root => toRepoPath(root, config.repoRoot) || '.');
+  const gitMetadata = getGitLastModifiedBatch(
+    config.repoRoot,
+    eligibleDocs.map(doc => doc.path),
+    { pathspecs, ...options },
+  );
+  const driftCandidates = eligibleDocs.filter(doc => {
+    const gitDate = gitMetadata.dates.get(doc.path) ?? null;
+    return Boolean(gitDate && gitDate.slice(0, 10) > doc.updated.slice(0, 10));
+  });
+  const candidatePaths = driftCandidates.map(doc => doc.path);
+  const candidateMetadata = {
+    dates: new Map(candidatePaths.filter(p => gitMetadata.dates.has(p)).map(p => [p, gitMetadata.dates.get(p)])),
+    commits: new Map(candidatePaths.filter(p => gitMetadata.commits?.has(p)).map(p => [p, gitMetadata.commits.get(p)])),
+    history: new Map(candidatePaths.filter(p => gitMetadata.history?.has(p)).map(p => [p, gitMetadata.history.get(p)])),
+    complete: gitMetadata.complete,
+    reason: gitMetadata.reason,
+  };
+  const substantiveMetadata = candidatePaths.length > 0
+    ? getGitLastSubstantiveModifiedBatch(config.repoRoot, candidatePaths, candidateMetadata, options)
+    : candidateMetadata;
 
-    const gitDate = gitDates.get(doc.path) ?? null;
+  for (const doc of driftCandidates) {
+    const gitDate = substantiveMetadata.dates.get(doc.path) ?? null;
     if (!gitDate) continue;
-
     const gitDay = gitDate.slice(0, 10);
     const fmDay = doc.updated.slice(0, 10);
 
@@ -540,6 +569,13 @@ export function checkGitStaleness(docs, config) {
       });
     }
   }
+  if (!substantiveMetadata.complete) {
+    warnings.push({
+      path: toRepoPath(config.docsRoot, config.repoRoot) || '.',
+      level: 'warning',
+      message: `Git metadata is incomplete (${substantiveMetadata.reason}); staleness checks used known dates only.`,
+    });
+  }
   return warnings;
 }
 
@@ -582,9 +618,7 @@ export function validatePlanShape(doc, body, frontmatter, config) {
 
   // 4. Heading drift: case + name variants
   const headingDrift = [
-    { wrong: /^##\s+Open questions\s*$/m, right: '## Open Questions' },
     { wrong: /^##\s+(Non-goals|Out of scope|Out of Scope|out of scope)\s*$/m, right: '## Non-Goals' },
-    { wrong: /^##\s+open questions\s*$/m, right: '## Open Questions' },
   ];
   for (const { wrong, right } of headingDrift) {
     const m = body.match(wrong);
@@ -654,8 +688,10 @@ export function computeDaysSinceUpdate(updated) {
   return Math.floor(diffMs / (1000 * 60 * 60 * 24));
 }
 
-export function computeIsStale(status, updated, config) {
-  const staleAfterDays = config.staleDaysByStatus[status] ?? null;
+export function computeIsStale(status, updated, config, type = null) {
+  const typeStaleDays = type ? config.raw?.types?.[type]?.staleDays : null;
+  const hasTypeDays = Object.prototype.hasOwnProperty.call(typeStaleDays ?? {}, status);
+  const staleAfterDays = hasTypeDays ? typeStaleDays[status] : (config.staleDaysByStatus[status] ?? null);
   if (staleAfterDays == null) return false;
 
   const daysSinceUpdate = computeDaysSinceUpdate(updated);

package/src/watch.mjs

@@ -1,11 +1,16 @@
 import { watch } from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { dim } from './color.mjs';
 
+export function watchCliPath(moduleUrl = import.meta.url) {
+  return path.resolve(path.dirname(fileURLToPath(moduleUrl)), '..', 'bin', 'dotmd.mjs');
+}
+
 export function runWatch(argv, config) {
   const subCommand = argv.length > 0 ? argv : ['list'];
-  const cliPath = path.join(path.dirname(new URL(import.meta.url).pathname), '..', 'bin', 'dotmd.mjs');
+  const cliPath = watchCliPath();
 
   let lastRun = 0;
   const DEBOUNCE = 300;