dotmd-cli 0.68.0 → 0.69.0

package/bin/dotmd.mjs

@@ -1078,9 +1078,10 @@ Examples:
 The "save a resume prompt" verb. Works mid-anything:
 
 Plan mode (a plan is in-session, or you pass one):
-  1. Saves a resume prompt named resume-<plan-slug> (collision-safe: -2, -3, …).
-     The prompt is session-local — the next session's hud surfaces it; never
-     paste resume text into chat.
+  1. Saves a resume prompt named resume-<plan-slug> (collision-safe: -2, -3, …),
+     stamped with a plan: link so consuming it re-claims the plan (see \`dotmd
+     use\`). The prompt is session-local — the next session's hud surfaces it;
+     never paste resume text into chat.
   2. Releases the plan: one status flip, in-session → active by default
      (--status to override, --note to record why in ## Version History).
   3. Prints the exact \`git commit\` for the plan's frontmatter change — the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.68.0",
+  "version": "0.69.0",
   "description": "CLI for managing markdown documents with YAML frontmatter — index, query, validate, graph, export, Notion sync, AI summaries.",
   "type": "module",
   "license": "MIT",
@@ -48,7 +48,7 @@
   "engines": {
     "node": ">=20"
   },
-  "dependencies": {
+  "optionalDependencies": {
     "@notionhq/client": "^5.13.0",
     "notion-to-md": "^3.1.9"
   }

package/src/baton.mjs

@@ -5,7 +5,8 @@ import { asString, toRepoPath, die, warn, currentSessionId } from './util.mjs';
 import { buildIndex, resolveDocArg } from './index.mjs';
 import { readJournalEntries } from './journal.mjs';
 import { runNew, readBodyInput } from './new.mjs';
-import { runSet } from './lifecycle.mjs';
+import { runSet, updateFrontmatter } from './lifecycle.mjs';
+import { resolvePromptInput } from './prompts.mjs';
 import { green, dim } from './color.mjs';
 
 // `dotmd baton` is the one-command handoff: save the resume prompt AND release
@@ -31,9 +32,9 @@ function matchesDocRef(doc, ref) {
 // or lock — in-session is just frontmatter — so ownership is reconstructed
 // from the per-repo journal: the last `use <plan>` / `set in-session <plan>`
 // this sid ran whose target is still in-session. Falls back to "the only
-// in-session plan" when the journal can't answer (disabled, or another tool
-// flipped the status). Returns { plan, via, inSession }; plan is null when
-// there's no defensible answer (caller decides how to ask).
+// in-session plan" when the journal is *silent* for this session (disabled, or
+// another tool flipped the status). Returns { plan, via, inSession }; plan is
+// null when there's no defensible answer (caller decides how to ask).
 export function findOwnedPlan(config, index = null) {
   const idx = index ?? buildIndex(config);
   const inSession = idx.docs.filter(d => d.type === 'plan' && d.status === 'in-session');
@@ -42,6 +43,13 @@ export function findOwnedPlan(config, index = null) {
   const sid = currentSessionId();
   let entries = [];
   try { entries = readJournalEntries(config); } catch { entries = []; }
+  // Did THIS session issue any ownership command at all (`use` / `set in-session`
+  // / `status … in-session`)? If it did but none matched an in-session plan, this
+  // session's work lives elsewhere (e.g. it consumed a `use <prompt>`, or worked
+  // a plan that's since been released) — so the lone in-session plan is
+  // presumptively *another* session's, and auto-selecting it would flip a
+  // stranger's status. Track that to gate the single-in-session fast path below.
+  let sawOwnershipRef = false;
   for (let i = entries.length - 1; i >= 0; i--) {
     const e = entries[i];
     if (e?.sid !== sid || !Array.isArray(e.argv) || (e.exit ?? 0) !== 0) continue;
@@ -51,11 +59,19 @@ export function findOwnedPlan(config, index = null) {
     else if (a[0] === 'set' && a[1] === 'in-session') ref = a.slice(2).find(x => typeof x === 'string' && !x.startsWith('-'));
     else if (a[0] === 'status' && a.includes('in-session')) ref = a.slice(1).find(x => typeof x === 'string' && !x.startsWith('-') && x !== 'in-session');
     if (!ref) continue;
+    sawOwnershipRef = true;
     const doc = inSession.find(d => matchesDocRef(d, ref));
     if (doc) return { plan: doc, via: 'journal', inSession };
   }
 
-  if (inSession.length === 1) return { plan: inSession[0], via: 'single-in-session', inSession };
+  // Single-in-session fast path — ONLY when the journal is silent about this
+  // session's ownership intent. If this sid *did* run an ownership command that
+  // pointed somewhere other than the lone in-session plan, refuse and let the
+  // caller demand an explicit slug/plan rather than hand off a plan this session
+  // never touched (the cross-session baton misfire).
+  if (inSession.length === 1 && !sawOwnershipRef) {
+    return { plan: inSession[0], via: 'single-in-session', inSession };
+  }
   return { plan: null, via: null, inSession };
 }
 
@@ -193,6 +209,17 @@ export async function runBaton(argv, config, opts = {}) {
   }
   if (!createdSlug) die(`Could not find a free prompt slug for ${slugBase} (tried ${slugBase}-2 … ${slugBase}-9).`);
 
+  // Link the prompt back to its plan so the next session's `dotmd use` re-claims
+  // it (consume = claim). The resume-<slug> filename is a lossy link under -N
+  // suffixing / plan renames; the explicit `plan:` field is the durable one.
+  // Best-effort: a resolve/write hiccup must never fail an otherwise-good handoff.
+  if (planPath && !dryRun) {
+    try {
+      const promptPath = resolvePromptInput(createdSlug, config, { dieOnMiss: false });
+      if (promptPath) updateFrontmatter(promptPath, { plan: repoPath });
+    } catch { /* stamping is best-effort */ }
+  }
+
   // 2. Release the plan — exactly one status flip. Skipped entirely in slug
   // mode: with no plan involved there is nothing to release.
   let archiveResult = null;

package/src/lint.mjs

@@ -73,12 +73,26 @@ export function runLint(argv, config, opts = {}) {
     // existing plural array happens at apply-time so the message reflects
     // just what's being introduced from the singular form.
     for (const { singular, plural } of [{ singular: 'module', plural: 'modules' }, { singular: 'surface', plural: 'surfaces' }]) {
-      const val = asString(parsed[singular]);
-      if (!val) continue;
-      const values = val.includes(',')
-        ? val.split(',').map(s => s.trim()).filter(Boolean)
-        : [val];
-      fixes.push({ field: singular, oldValue: val, newValue: values, pluralKey: plural, type: 'singular-to-plural' });
+      const rawVal = parsed[singular];
+      const val = asString(rawVal);
+      if (val) {
+        // Inline value (`surface: foo`) → migrate into the plural array.
+        const values = val.includes(',')
+          ? val.split(',').map(s => s.trim()).filter(Boolean)
+          : [val];
+        fixes.push({ field: singular, oldValue: val, newValue: values, pluralKey: plural, type: 'singular-to-plural' });
+      } else if (singular in parsed && (!Array.isArray(rawVal) || rawVal.length === 0)) {
+        // Empty deprecated key (`surface:` with nothing after it, which the
+        // parser yields as `[]`) — usually sitting right above a populated
+        // `surfaces:`. There's no value to migrate; the deprecation warning
+        // just wants the dead line gone. `validate` treats the empty `[]` as
+        // present (so it warns), while the old `asString` gate here saw it as
+        // absent and skipped — the exact no-op reported in issue #17. Emit a
+        // drop fix so `lint --fix` does what the warning advertises. A
+        // populated block-form singular (rawVal.length > 0) is left untouched:
+        // too rare to risk mis-editing.
+        fixes.push({ field: singular, pluralKey: plural, type: 'drop-singular' });
+      }
     }
 
     // Trailing whitespace in values
@@ -102,8 +116,22 @@ export function runLint(argv, config, opts = {}) {
   // Also get non-fixable issues from index, excluding issues we can already fix
   const index = buildIndex(config);
   const fixablePaths = new Set(fixable.map(f => f.repoPath));
+  // Singular-key deprecation warnings whose fix `lint --fix` will actually make.
+  // Without this, those warnings landed in BOTH the "fixable" preview and the
+  // "non-fixable" list, so the header claimed "N non-fixable" while every line
+  // told you to run `lint --fix` (issue #17, item 8).
+  const fixableSingularKeys = new Set();
+  for (const { repoPath, fixes } of fixable) {
+    for (const f of fixes) {
+      if (f.type === 'singular-to-plural' || f.type === 'drop-singular') {
+        fixableSingularKeys.add(`${repoPath}::${f.field}`);
+      }
+    }
+  }
   const nonFixable = [...index.errors, ...index.warnings].filter(issue => {
     if (issue.message.includes('Missing frontmatter `status`') && fixablePaths.has(issue.path)) return false;
+    const dep = issue.message.match(/^`(module|surface):` \(singular\) is deprecated/);
+    if (dep && fixableSingularKeys.has(`${issue.path}::${dep[1]}`)) return false;
     return true;
   });
 
@@ -120,6 +148,8 @@ export function runLint(argv, config, opts = {}) {
             process.stdout.write(dim(`    missing status (fixable via AI)\n`));
           } else if (f.type === 'singular-to-plural') {
             process.stdout.write(dim(`    ${f.field}: "${f.oldValue}" → ${f.pluralKey}: [${f.newValue.join(', ')}]\n`));
+          } else if (f.type === 'drop-singular') {
+            process.stdout.write(dim(`    remove deprecated \`${f.field}:\` (empty; \`${f.pluralKey}:\` is the live key)\n`));
           } else if (f.type === 'eof') {
             process.stdout.write(dim(`    missing newline at end of file\n`));
           } else if (f.type === 'add') {
@@ -155,6 +185,7 @@ export function runLint(argv, config, opts = {}) {
     let needsEofFix = false;
     const trimFixes = [];
     const singularToPlural = [];
+    const dropSingular = [];
 
     for (const f of fixes) {
       if (f.type === 'rename-key') {
@@ -165,6 +196,8 @@ export function runLint(argv, config, opts = {}) {
         trimFixes.push(f);
       } else if (f.type === 'singular-to-plural') {
         singularToPlural.push(f);
+      } else if (f.type === 'drop-singular') {
+        dropSingular.push(f);
       } else {
         updates[f.field] = f.newValue;
       }
@@ -212,6 +245,19 @@ export function runLint(argv, config, opts = {}) {
         writeFileSync(filePath, raw, 'utf8');
       }
 
+      // Drop empty deprecated singular keys. The value is known-empty (the fix
+      // is only emitted for `[]`/`''`), so this matches the bare `key:` line
+      // exactly — never a line carrying content — and removes it.
+      for (const ds of dropSingular) {
+        let raw = readFileSync(filePath, 'utf8');
+        const { frontmatter: fm } = extractFrontmatter(raw);
+        const newFm = fm
+          .replace(new RegExp(`^${escapeRegex(ds.field)}:[ \\t]*$`, 'm'), '')
+          .replace(/\n{2,}/g, '\n');
+        raw = replaceFrontmatter(raw, newFm.trim());
+        writeFileSync(filePath, raw, 'utf8');
+      }
+
       // Apply key renames and trim fixes via raw string manipulation
       if (keyRenames.length > 0 || trimFixes.length > 0) {
         let raw = readFileSync(filePath, 'utf8');
@@ -259,6 +305,8 @@ export function runLint(argv, config, opts = {}) {
         }
       } else if (f.type === 'singular-to-plural') {
         process.stdout.write(`${prefix}  ${dim(`${f.field}: "${f.oldValue}" → ${f.pluralKey}: [${f.newValue.join(', ')}]`)}\n`);
+      } else if (f.type === 'drop-singular') {
+        process.stdout.write(`${prefix}  ${dim(`removed deprecated \`${f.field}:\` (empty)`)}\n`);
       } else if (f.type === 'add') {
         process.stdout.write(`${prefix}  ${dim(`add ${f.field}: ${f.newValue}`)}\n`);
       } else {

package/src/notion.mjs

@@ -16,7 +16,7 @@ async function loadDeps() {
     notionClient = Client;
     notionToMd = NotionToMarkdown;
   } catch {
-    die('Notion dependencies not installed. Run: npm install @notionhq/client notion-to-md');
+    die('Notion integration needs its optional dependencies. Run: npm install @notionhq/client notion-to-md\n(These ship as optionalDependencies — a plain `npm i -g dotmd-cli` installs them unless you passed `--omit=optional`.)');
   }
 }
 

package/src/prompts.mjs

@@ -1,13 +1,18 @@
-import { readFileSync, statSync } from 'node:fs';
+import { readFileSync, statSync, existsSync } from 'node:fs';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
-import { asString, toRepoPath, die, resolveDocPath, isArchivedPath } from './util.mjs';
-import { buildIndex } from './index.mjs';
+import { asString, toRepoPath, die, resolveDocPath, isArchivedPath, currentSessionId } from './util.mjs';
+import { buildIndex, resolveDocArg } from './index.mjs';
 import { runQuery } from './query.mjs';
-import { runArchive, runStatus } from './lifecycle.mjs';
+import { runArchive, runStatus, updateFrontmatter } from './lifecycle.mjs';
+import { appendJournalEntry } from './journal.mjs';
 import { runNew } from './new.mjs';
 import { green, dim } from './color.mjs';
 
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
+
 // `resume` is an alias for `use` — agents reach for "resume" when continuing a
 // session; `use` reads as internal mechanics. Both names stay valid; the
 // canonical output ("Consumed: …") is unchanged.
@@ -283,6 +288,48 @@ export function consumePrompt(filePath, config, opts) {
 
   const consumedPath = archiveResult?.newRepoPath ?? repoPath;
   process.stderr.write(`${green('✓ Consumed')}: ${consumedPath}\n`);
+
+  // Consume = claim: a baton-created resume prompt carries `plan: <path>`.
+  // Adopt that plan for THIS session so the next `dotmd baton` (with no arg)
+  // hands it off — closing the cross-session ownership loop that otherwise dies
+  // at the prompt boundary.
+  claimPromptPlan(asString(parsed.plan), config);
+}
+
+// Flip the resume prompt's linked plan to in-session for this session and
+// record the ownership in the journal. The journal entry matters: baton's
+// `findOwnedPlan` reconstructs ownership from journaled `set in-session <plan>`
+// commands, and the outer `use <prompt>` argv can't tie a prompt ref to a plan
+// — so without this synthetic entry the claim would be invisible to baton (and,
+// with the misfire gate, would even make the next baton refuse).
+function claimPromptPlan(planRef, config) {
+  if (!planRef) return;
+  let planPath = null;
+  try { planPath = resolveDocPath(planRef, config) ?? resolveDocArg(planRef, config, { dieOnMiss: false }); }
+  catch { planPath = null; }
+  if (!planPath || !existsSync(planPath)) return; // link went stale (plan renamed/removed) — the resume body already printed, so stay quiet
+
+  let planFm;
+  try { planFm = parseSimpleFrontmatter(extractFrontmatter(readFileSync(planPath, 'utf8')).frontmatter); }
+  catch { return; }
+  const cur = asString(planFm.status);
+  // Only claim a startable plan. Already in-session → someone's on it (don't
+  // steal); archived/terminal → the link is stale. Either way, leave it be.
+  if (!cur || cur === 'in-session' || cur === 'archived') return;
+
+  const repoPath = toRepoPath(planPath, config.repoRoot);
+  try { updateFrontmatter(planPath, { status: 'in-session' }); }
+  catch { return; }
+  try {
+    // `v` MUST be the real CLI version: the journal rotates when a new entry's
+    // version differs from the file's first entry, so a sentinel here would shove
+    // our just-written claim into the backup file where findOwnedPlan can't see it.
+    appendJournalEntry(config, {
+      ts: new Date().toISOString(), sid: currentSessionId(), pid: process.pid,
+      argv: ['set', 'in-session', repoPath], exit: 0, ms: 0, v: pkg.version,
+    });
+  } catch { /* journal is best-effort — the status flip already landed */ }
+  process.stderr.write(`${green('→ Claimed')}: ${repoPath} (in-session)\n`);
 }
 
 // Read-only peek: print the body WITHOUT consuming. The sanctioned triage path