dotmd-cli 0.11.1 → 0.12.0

package/README.md

@@ -120,6 +120,8 @@ dotmd plans                  List all plans
 dotmd stale                  List stale docs
 dotmd actionable             List docs with next steps
 dotmd index [--write]        Generate/update docs.md index block
+dotmd pickup <file>          Pick up a plan (in-session + print)
+dotmd finish <file>          Finish a plan (done or active)
 dotmd status <file> <status> Transition document status
 dotmd archive <file>         Archive (status + move + update refs)
 dotmd touch <file>           Bump updated date

package/bin/dotmd.mjs

@@ -8,7 +8,7 @@ import { buildIndex } from '../src/index.mjs';
 import { renderCompactList, renderVerboseList, renderContext, renderCheck, renderCoverage, buildCoverage } from '../src/render.mjs';
 import { renderIndexFile, writeIndex } from '../src/index-file.mjs';
 import { runFocus, runQuery } from '../src/query.mjs';
-import { runStatus, runArchive, runTouch, runBulkArchive } from '../src/lifecycle.mjs';
+import { runStatus, runArchive, runTouch, runBulkArchive, runPickup, runFinish } from '../src/lifecycle.mjs';
 import { runInit } from '../src/init.mjs';
 import { runNew } from '../src/new.mjs';
 import { runCompletions } from '../src/completions.mjs';
@@ -62,6 +62,8 @@ Validate & Fix:
   fix-refs [--dry-run]              Auto-fix broken reference paths + body links
 
 Lifecycle:
+  pickup <file>                     Pick up a plan (set in-session + print)
+  finish <file> [done|active]       Finish a plan (set done or active)
   status <file> <status>            Transition document status
   archive <file>                    Archive (status + move + update refs)
   bulk archive <f1> <f2> ...        Archive multiple files at once
@@ -130,6 +132,28 @@ Filters:
   --summarize-limit <n>  Max docs to summarize (default: 5)
   --model <name>         Model for AI summaries`,
 
+  pickup: `dotmd pickup <file> — pick up a plan and start working
+
+Sets the plan to in-session and prints its content.
+Fails if the plan is already in-session, blocked, done, or archived.
+
+Options:
+  --json                 Output as JSON
+  --dry-run, -n          Preview without writing
+
+If no file is given, prompts with a list of active plans.`,
+
+  finish: `dotmd finish <file> [done|active] — finish working on a plan
+
+Sets the plan status to done (default) or back to active.
+Only works on plans currently in-session.
+
+Options:
+  --json                 Output as JSON
+  --dry-run, -n          Preview without writing
+
+If no file is given, prompts with a list of in-session plans.`,
+
   status: `dotmd status <file> <new-status> — transition document status
 
 Moves the document to the new status. If transitioning to an archive
@@ -468,6 +492,8 @@ async function main() {
   if (command === 'notion') { await runNotion(restArgs, config, { dryRun }); return; }
 
   // Lifecycle commands
+  if (command === 'pickup') { await runPickup(restArgs, config, { dryRun }); return; }
+  if (command === 'finish') { await runFinish(restArgs, config, { dryRun }); return; }
   if (command === 'status') { await runStatus(restArgs, config, { dryRun }); return; }
   if (command === 'archive') { runArchive(restArgs, config, { dryRun }); return; }
   if (command === 'bulk' && restArgs[0] === 'archive') { runBulkArchive(restArgs.slice(1), config, { dryRun }); return; }
@@ -698,7 +724,7 @@ async function main() {
   // Unknown command — suggest closest match
   const allCommands = [
     'list', 'json', 'check', 'coverage', 'stats', 'graph', 'deps', 'context',
-    'focus', 'query', 'plans', 'stale', 'actionable', 'index', 'status', 'archive', 'touch', 'doctor',
+    'focus', 'query', 'plans', 'stale', 'actionable', 'index', 'pickup', 'finish', 'status', 'archive', 'touch', 'doctor',
     'fix-refs', 'lint', 'rename', 'migrate', 'notion', 'export', 'summary',
     'watch', 'diff', 'new', 'init', 'completions',
   ];

package/dotmd.config.example.mjs

@@ -147,6 +147,8 @@ export const presets = {
 // export function onNew({ path, status, title, template }) {}
 // export function onRename({ oldPath, newPath, referencesUpdated }) {}
 // export function onLint({ path, fixes }) {}
+// export function onPickup({ path, oldStatus, newStatus }) {}
+// export function onFinish({ path, oldStatus, newStatus }) {}
 
 // AI hooks — override summarization (replaces local MLX model).
 // export function summarizeDoc(body, meta) { return 'Custom summary'; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "description": "CLI for managing markdown documents with YAML frontmatter — index, query, validate, graph, export, Notion sync, AI summaries.",
   "type": "module",
   "license": "MIT",

package/src/completions.mjs

@@ -2,7 +2,7 @@ import { die } from './util.mjs';
 
 const COMMANDS = [
   'list', 'json', 'check', 'coverage', 'stats', 'graph', 'deps', 'unblocks', 'health', 'glossary', 'context', 'focus', 'query',
-  'plans', 'stale', 'actionable', 'index', 'status', 'archive', 'bulk', 'touch', 'doctor', 'lint', 'rename', 'migrate',
+  'plans', 'stale', 'actionable', 'index', 'pickup', 'finish', 'status', 'archive', 'bulk', 'touch', 'doctor', 'lint', 'rename', 'migrate',
   'fix-refs', 'notion', 'export', 'summary', 'watch', 'diff', 'init', 'new', 'completions',
 ];
 
@@ -32,6 +32,8 @@ const COMMAND_FLAGS = {
   plans: ['--status', '--json', '--sort', '--limit', '--all', '--stale', '--has-next-step'],
   stale: ['--json', '--sort', '--limit', '--all'],
   actionable: ['--json', '--sort', '--limit', '--all'],
+  pickup: ['--json'],
+  finish: ['--json'],
   status: [],
   archive: [],
   doctor: [],

package/src/lifecycle.mjs

@@ -119,6 +119,118 @@ export async function runStatus(argv, config, opts = {}) {
   }); } catch (err) { warn(`Hook 'onStatusChange' threw: ${err.message}`); }
 }
 
+export async function runPickup(argv, config, opts = {}) {
+  const { dryRun } = opts;
+  const json = argv.includes('--json');
+  let input = argv.find(a => !a.startsWith('-'));
+
+  // Interactive: pick from active plans
+  if (!input) {
+    if (!isInteractive()) die('Usage: dotmd pickup <file>');
+    const index = buildIndex(config);
+    const active = index.docs.filter(d => d.type === 'plan' && (d.status === 'active' || d.status === 'planned'));
+    if (active.length === 0) die('No active or planned plans to pick up.');
+    const choice = await promptChoice('Pick a plan:', active.map(d => `${d.title} (${d.status}) — ${d.path}`));
+    if (!choice) die('No plan selected.');
+    const idx = active.findIndex((_, i) => choice === `${active[i].title} (${active[i].status}) — ${active[i].path}`);
+    if (idx === -1) die('No plan selected.');
+    input = active[idx].path;
+  }
+
+  const filePath = resolveDocPath(input, config);
+  if (!filePath) die(`File not found: ${input}`);
+
+  const raw = readFileSync(filePath, 'utf8');
+  const { frontmatter: fmRaw, body } = extractFrontmatter(raw);
+  const parsedFm = parseSimpleFrontmatter(fmRaw);
+  const docType = asString(parsedFm.type) ?? null;
+  const oldStatus = asString(parsedFm.status);
+  const title = asString(parsedFm.title) ?? path.basename(filePath, '.md');
+  const repoPath = toRepoPath(filePath, config.repoRoot);
+
+  if (docType && docType !== 'plan') warn(`${repoPath} has type '${docType}', not 'plan'.`);
+
+  if (oldStatus === 'in-session') die(`Already in-session — another Claude instance may be working on this.\n  ${repoPath}`);
+  if (oldStatus === 'blocked') {
+    const blockers = parsedFm.blockers ? (Array.isArray(parsedFm.blockers) ? parsedFm.blockers.join(', ') : String(parsedFm.blockers)) : 'unknown';
+    die(`Plan is blocked: ${blockers}\n  ${repoPath}`);
+  }
+  const pickupable = new Set(['active', 'planned']);
+  if (oldStatus && !pickupable.has(oldStatus)) die(`Cannot pick up a plan with status '${oldStatus}'. Must be active or planned.\n  ${repoPath}`);
+
+  const today = new Date().toISOString().slice(0, 10);
+
+  if (dryRun) {
+    process.stderr.write(`${dim('[dry-run]')} Would update: status: ${oldStatus} → in-session, updated: ${today}\n`);
+  } else {
+    updateFrontmatter(filePath, { status: 'in-session', updated: today });
+  }
+
+  if (json) {
+    process.stdout.write(JSON.stringify({ path: repoPath, oldStatus, newStatus: 'in-session', title, body: body?.trim() ?? '' }, null, 2) + '\n');
+  } else {
+    process.stderr.write(`${green('▶ Picked up')}: ${repoPath} (${oldStatus} → in-session)\n\n`);
+    if (body?.trim()) process.stdout.write(body.trim() + '\n');
+  }
+
+  try { config.hooks.onPickup?.({ path: repoPath, oldStatus, newStatus: 'in-session' }); } catch (err) { warn(`Hook 'onPickup' threw: ${err.message}`); }
+}
+
+export async function runFinish(argv, config, opts = {}) {
+  const { dryRun } = opts;
+  const json = argv.includes('--json');
+  const positional = argv.filter(a => !a.startsWith('-'));
+  let input = positional[0];
+  const targetStatus = positional[1] ?? 'done';
+
+  if (!['done', 'active'].includes(targetStatus)) die(`Invalid finish status: ${targetStatus}. Use 'done' or 'active'.`);
+
+  // Interactive: pick from in-session plans
+  if (!input) {
+    if (!isInteractive()) die('Usage: dotmd finish <file> [done|active]');
+    const index = buildIndex(config);
+    const inSession = index.docs.filter(d => d.status === 'in-session');
+    if (inSession.length === 0) die('No plans currently in-session.');
+    if (inSession.length === 1) {
+      input = inSession[0].path;
+      process.stderr.write(`${dim(`Auto-selected: ${input}`)}\n`);
+    } else {
+      const choice = await promptChoice('Finish which plan:', inSession.map(d => `${d.title} — ${d.path}`));
+      if (!choice) die('No plan selected.');
+      const idx = inSession.findIndex((_, i) => choice === `${inSession[i].title} — ${inSession[i].path}`);
+      if (idx === -1) die('No plan selected.');
+      input = inSession[idx].path;
+    }
+  }
+
+  const filePath = resolveDocPath(input, config);
+  if (!filePath) die(`File not found: ${input}`);
+
+  const raw = readFileSync(filePath, 'utf8');
+  const { frontmatter: fmRaw } = extractFrontmatter(raw);
+  const parsedFm = parseSimpleFrontmatter(fmRaw);
+  const oldStatus = asString(parsedFm.status);
+  const repoPath = toRepoPath(filePath, config.repoRoot);
+
+  if (oldStatus !== 'in-session') die(`Plan is not in-session (current: ${oldStatus}).\n  ${repoPath}`);
+
+  const today = new Date().toISOString().slice(0, 10);
+
+  if (dryRun) {
+    process.stderr.write(`${dim('[dry-run]')} Would update: status: in-session → ${targetStatus}, updated: ${today}\n`);
+  } else {
+    updateFrontmatter(filePath, { status: targetStatus, updated: today });
+  }
+
+  if (json) {
+    process.stdout.write(JSON.stringify({ path: repoPath, oldStatus, newStatus: targetStatus }, null, 2) + '\n');
+  } else {
+    process.stdout.write(`${green('✓ Finished')}: ${repoPath} (in-session → ${targetStatus})\n`);
+  }
+
+  try { config.hooks.onFinish?.({ path: repoPath, oldStatus, newStatus: targetStatus }); } catch (err) { warn(`Hook 'onFinish' threw: ${err.message}`); }
+}
+
 export function runArchive(argv, config, opts = {}) {
   const { dryRun } = opts;
   const input = argv[0];