dotmd-cli 0.54.0 → 0.56.0

package/bin/dotmd.mjs

@@ -37,6 +37,7 @@ const FLAG_SPECS = {
   hud: { flags: new Set(['--json', '--subagent']), values: new Set() },
   guard: { flags: new Set(), values: new Set() },
   misuse: { flags: new Set(['--json', '--tail', '--by-rule', '--repo']), values: new Set(['--tail', '--repo']) },
+  update: { flags: new Set(['--check', '--cli-only', '--plugin-only']), values: new Set() },
   check: { flags: new Set(['--fix', '--errors-only', '--no-collapse', '--json', '--verbose']), values: new Set() },
   doctor: { flags: new Set(['--apply', '--yes', '--dry-run', '-n', '--statuses', '--migrate-template', '--migrate-prompts', '--frontmatter-fix', '--project', '--json', '--include-archived']), values: new Set() },
   runlist: { flags: new Set(['--json', '--full', '--no-index', '--show-files']), values: new Set(), subcommands: new Set(['next']) },
@@ -157,6 +158,18 @@ Rules:
 Every catch is appended to the cross-repo misuse log. Disable with DOTMD_GUARD=0.
 Read the log with \`dotmd misuse\`.`,
 
+  update: `dotmd update — update the dotmd CLI and the Claude Code plugin together
+
+  dotmd update                 npm i -g dotmd-cli  +  claude plugin update dotmd@dotmd
+  dotmd update --check         report CLI vs plugin versions, do nothing (network-free)
+  dotmd update --cli-only      only the npm CLI
+  dotmd update --plugin-only   only the plugin
+
+The plugin and CLI ship in lockstep; a release bumps both. Updating the plugin
+requires a session restart (or /reload-plugins) to apply. The plugin step needs
+the \`claude\` CLI on PATH — otherwise it prints the \`/plugin update\` command to
+run from a session instead.`,
+
   misuse: `dotmd misuse — read the cross-repo guard log (~/.claude/logs/dotmd-misuse.log)
 
   dotmd misuse                last 20 intercepted wrong-moves
@@ -1220,7 +1233,12 @@ async function main() {
     restArgs.push(args[i]);
   }
 
-  if (!config.configFound && command !== 'init') {
+  // Hook commands (`hud`, `guard`) fire in EVERY repo via the globally-enabled
+  // plugin — `guard` runs on every Bash/Read/Edit. They must stay silent where
+  // dotmd isn't used, so don't nag them about a missing config (they no-op
+  // cleanly on their own). The warning is still useful for interactive commands.
+  const HOOK_COMMANDS = new Set(['hud', 'guard']);
+  if (!config.configFound && command !== 'init' && !HOOK_COMMANDS.has(command)) {
     warn('No dotmd config found — using defaults. Run `dotmd init` to create one.');
   }
 
@@ -1305,6 +1323,7 @@ async function main() {
   // Lifecycle commands
   if (command === 'hud') { const { runHud } = await import('../src/hud.mjs'); runHud(restArgs, config); return; }
   if (command === 'guard') { const { runGuard } = await import('../src/guard.mjs'); await runGuard(restArgs, config); return; }
+  if (command === 'update') { const { runUpdate } = await import('../src/update.mjs'); runUpdate(restArgs, config); return; }
   if (command === 'misuse') { const { runMisuse } = await import('../src/misuse-read.mjs'); runMisuse(restArgs, config); return; }
   if (command === 'journal') { const { runJournal } = await import('../src/journal-read.mjs'); runJournal(restArgs, config); return; }
   if (command === 'pickup' || command === 'unpickup' || command === 'release' || command === 'finish') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.54.0",
+  "version": "0.56.0",
   "description": "CLI for managing markdown documents with YAML frontmatter — index, query, validate, graph, export, Notion sync, AI summaries.",
   "type": "module",
   "license": "MIT",
@@ -13,6 +13,7 @@
   "files": [
     "bin/",
     "src/",
+    "scripts/postinstall.mjs",
     "dotmd.config.example.mjs"
   ],
   "keywords": [
@@ -39,6 +40,7 @@
   "homepage": "https://github.com/reowens/dotmd#readme",
   "scripts": {
     "test": "node --test test/*.test.mjs",
+    "postinstall": "node scripts/postinstall.mjs",
     "preversion": "npm test",
     "version": "node bin/dotmd.mjs hud >/dev/null 2>&1; node scripts/sync-plugin-version.mjs; git add .claude/commands docs/docs.md plugins/dotmd/.claude-plugin/plugin.json .claude-plugin/marketplace.json 2>/dev/null; true",
     "postversion": "bash scripts/postversion.sh"

package/scripts/postinstall.mjs

@@ -0,0 +1,36 @@
+// Runs after `npm install dotmd-cli`. Because the dotmd Claude Code plugin is a
+// separate artifact from this CLI, upgrading the CLI alone leaves the plugin
+// (hooks/skill/commands) on its old version. This script bridges that — but
+// conservatively:
+//
+//   - Only on GLOBAL installs (`npm i -g`). A project devDep / CI / Docker
+//     install must never touch a user's Claude Code state.
+//   - Default: just print a one-line nudge. A CLI install silently mutating the
+//     agent's plugin cache is surprising; opt in with DOTMD_AUTO_PLUGIN_UPDATE=1
+//     to actually run the refresh.
+//   - NEVER fail the install: everything is swallowed and we always exit 0. A
+//     nonzero postinstall would break `npm i -g dotmd-cli`.
+//   - Skipped entirely under `npm install --ignore-scripts`.
+import { spawnSync } from 'node:child_process';
+
+try {
+  // Lifecycle env: npm sets this to "true" for global installs.
+  if (process.env.npm_config_global !== 'true') process.exit(0);
+
+  const hasClaude = (() => {
+    try {
+      const cmd = process.platform === 'win32' ? 'where' : 'which';
+      return spawnSync(cmd, ['claude'], { encoding: 'utf8' }).status === 0;
+    } catch { return false; }
+  })();
+
+  if (process.env.DOTMD_AUTO_PLUGIN_UPDATE === '1' && hasClaude) {
+    spawnSync('claude', ['plugin', 'update', 'dotmd@dotmd'], { stdio: 'ignore', timeout: 60000 });
+    process.stdout.write('dotmd: refreshed the Claude Code plugin — restart your session (or /reload-plugins) to apply.\n');
+  } else {
+    process.stdout.write('dotmd CLI installed. Using the Claude Code plugin? Run `dotmd update` to refresh it too, then restart.\n');
+  }
+} catch {
+  // Best effort only — never break the install.
+}
+process.exit(0);

package/src/commands.mjs

@@ -8,6 +8,6 @@ export const KNOWN_COMMANDS = [
   'unblocks', 'health', 'glossary', 'modules', 'module',
   'fix-refs', 'lint', 'rename', 'migrate', 'notion', 'export', 'summary',
   'watch', 'diff', 'new', 'init', 'completions', 'statuses', 'journal',
-  'guard', 'misuse',
+  'guard', 'misuse', 'update',
   'ship', 'self-check',
 ];

package/src/hud.mjs

@@ -1,11 +1,42 @@
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
 import { asString, toRepoPath, currentSessionId } from './util.mjs';
-import { dim } from './color.mjs';
+import { dim, yellow } from './color.mjs';
 import { buildIndex } from './index.mjs';
 import { refreshStaleSlashCommands } from './claude-commands.mjs';
 import { readJournalEntries, journalFilePath } from './journal.mjs';
+import { compareVersions } from './update.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
+
+// Detect when the running plugin's bundled version disagrees with this CLI's
+// version. Since every release bumps both in lockstep, a mismatch means exactly
+// one channel is behind. Network-free: the plugin's hook sets CLAUDE_PLUGIN_ROOT
+// to the plugin dir, whose plugin.json carries its version. Gated to the
+// version-keyed *cache* install — a directory-source plugin tracks content live
+// and its version label lags benignly, so we don't nag local dev. Returns a
+// one-line notice or null (silent when in sync). Surfaces to the agent because
+// hud output is injected as SessionStart/SubagentStart context.
+export function detectVersionDrift(env = process.env) {
+  try {
+    const root = env.CLAUDE_PLUGIN_ROOT;
+    if (!root) return null;
+    const cacheSeg = `${path.sep}plugins${path.sep}cache${path.sep}`;
+    if (!root.includes(cacheSeg)) return null;
+    const pj = path.join(root, '.claude-plugin', 'plugin.json');
+    if (!existsSync(pj)) return null;
+    const pluginVersion = JSON.parse(readFileSync(pj, 'utf8')).version;
+    const cmp = compareVersions(pluginVersion, pkg.version);
+    if (cmp === null || cmp === 0) return null;
+    if (cmp < 0) return `dotmd plugin ${pluginVersion} is behind the CLI ${pkg.version} — run \`dotmd update\` then restart.`;
+    return `dotmd CLI ${pkg.version} is behind the plugin ${pluginVersion} — run \`dotmd update\` (or npm i -g dotmd-cli).`;
+  } catch {
+    return null;
+  }
+}
 
 // Statuses that count as "actionable" for a prompt are derived from config:
 // types.prompt.context.expanded (the statuses the user wants prominently shown).
@@ -198,17 +229,36 @@ const SUBAGENT_PRIMER = [
   'git add/commit a prompt (they are session-local, often gitignored); hand-edit a `status:` field (use `dotmd set`).',
 ].join('\n');
 
+// The plugin's SessionStart/SubagentStart hooks fire in EVERY repo (it's enabled
+// globally), but the primer only helps where dotmd is actually used. Gate on a
+// discovered config: `dotmd init` writes dotmd.config.mjs, so "has a config" is
+// the zero-false-positive signal for "this is a dotmd repo." A bare docs/ dir is
+// deliberately NOT enough — too many repos have one. In a non-dotmd repo the hook
+// then contributes nothing to the session: no primer, no index build, no heal.
+function isDotmdRepo(config) {
+  return Boolean(config?.configFound);
+}
+
 export function runHud(argv, config) {
   const json = argv.includes('--json');
 
+  const drift = detectVersionDrift();
+  const dotmdRepo = isDotmdRepo(config);
+
   // SubagentStart hook entry point — emit the compact primer and return. No
   // index build, no journal read, no slash-command heal: a subagent doesn't
   // need the operator-facing machinery, just the verbs and the guardrails.
   if (argv.includes('--subagent')) {
+    if (!dotmdRepo) return; // silent in repos that don't use dotmd
     process.stdout.write(dim(SUBAGENT_PRIMER) + '\n');
+    if (drift) process.stdout.write(yellow(drift) + '\n');
     return;
   }
 
+  // Non-dotmd repo, and not a programmatic --json caller → contribute nothing to
+  // the session. Skip the index build, slash-heal, primer, and drift line.
+  if (!dotmdRepo && !json) return;
+
   const hud = buildHud(config);
 
   // Self-heal stale slash-command files. Wrapped: a broken scaffolder must
@@ -222,7 +272,7 @@ export function runHud(argv, config) {
   }
 
   if (json) {
-    process.stdout.write(JSON.stringify(hud, null, 2) + '\n');
+    process.stdout.write(JSON.stringify({ ...hud, drift: drift ?? null }, null, 2) + '\n');
     return;
   }
 
@@ -237,4 +287,5 @@ export function runHud(argv, config) {
   // `dotmd hud --json` for programmatic callers. The hook's job is purely to
   // teach the verbs, never to report status.
   process.stdout.write(dim('dotmd: plans|briefing  set <status> [<file>]  new <type> <slug>  use [<file>]  archive <file>  (use [no-arg] → oldest pending prompt)') + '\n');
+  if (drift) process.stdout.write(yellow(drift) + '\n');
 }

package/src/update.mjs

@@ -0,0 +1,116 @@
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { green, dim, yellow } from './color.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
+
+const NPM_PKG = 'dotmd-cli';
+const DEFAULT_PLUGIN_ID = 'dotmd@dotmd';
+
+// Parse an x.y.z prefix; returns [major, minor, patch] or null.
+function parseVer(v) {
+  if (typeof v !== 'string') return null;
+  const m = v.trim().match(/^(\d+)\.(\d+)\.(\d+)/);
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+
+// -1 if a<b, 0 if equal, 1 if a>b, null if either is unparseable.
+export function compareVersions(a, b) {
+  const pa = parseVer(a), pb = parseVer(b);
+  if (!pa || !pb) return null;
+  for (let i = 0; i < 3; i++) if (pa[i] !== pb[i]) return pa[i] < pb[i] ? -1 : 1;
+  return 0;
+}
+
+// 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 = {}) {
+  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));
+    if (!id) return null;
+    const entry = Array.isArray(plugins[id]) ? plugins[id][0] : plugins[id];
+    return { id, version: entry?.version ?? null };
+  } catch {
+    return 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 }.
+export function planUpdate(opts, ctx) {
+  const steps = [];
+  if (!opts.pluginOnly) {
+    steps.push(ctx.hasNpm
+      ? { kind: 'cli', cmd: ['npm', 'i', '-g', `${NPM_PKG}@latest`] }
+      : { kind: 'skip', reason: 'npm not found on PATH — skipping CLI update' });
+  }
+  if (!opts.cliOnly) {
+    if (!ctx.plugin) {
+      steps.push({ kind: 'skip', reason: 'dotmd plugin not installed — skipping plugin update' });
+    } else if (!ctx.hasClaude) {
+      steps.push({ kind: 'skip', reason: `claude CLI not found — run \`/plugin update ${ctx.plugin.id}\` from a session instead` });
+    } else {
+      steps.push({ kind: 'plugin', cmd: ['claude', 'plugin', 'update', ctx.plugin.id] });
+    }
+  }
+  return steps;
+}
+
+function which(bin) {
+  try {
+    const cmd = process.platform === 'win32' ? 'where' : 'which';
+    return spawnSync(cmd, [bin], { encoding: 'utf8' }).status === 0;
+  } catch {
+    return false;
+  }
+}
+
+export function runUpdate(argv, _config) {
+  const check = argv.includes('--check');
+  const cliOnly = argv.includes('--cli-only');
+  const pluginOnly = argv.includes('--plugin-only');
+  const plugin = readInstalledPlugin();
+
+  if (check) {
+    process.stdout.write(`dotmd CLI:    ${pkg.version}\n`);
+    if (plugin) {
+      const cmp = compareVersions(plugin.version, pkg.version);
+      const tag = cmp === 0 ? green('in sync')
+        : cmp === null ? dim('(unknown)')
+        : cmp < 0 ? yellow('behind — run `dotmd update`')
+        : yellow('ahead — CLI is behind');
+      process.stdout.write(`dotmd plugin: ${plugin.version ?? '?'} (${plugin.id}) ${tag}\n`);
+    } else {
+      process.stdout.write(dim('dotmd plugin: not installed\n'));
+    }
+    return;
+  }
+
+  const steps = planUpdate({ cliOnly, pluginOnly }, { plugin, hasClaude: which('claude'), hasNpm: which('npm') });
+  let ran = 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' });
+    ran = true;
+    if (r.status !== 0) process.stdout.write(yellow(`(${s.cmd[0]} exited ${r.status ?? '?'})\n`));
+  }
+  if (ran) {
+    process.stdout.write(green('\n✓ restart your Claude Code session (or /reload-plugins) to apply.\n'));
+  }
+}