dotmd-cli 0.14.3 → 0.14.5

package/README.md

@@ -430,27 +430,78 @@ When `dotmd init` runs in a directory with existing `.md` files, it scans them a
 
 ## Configuration
 
-Create `dotmd.config.mjs` at your project root (or run `dotmd init`):
+Create `dotmd.config.mjs` at your project root (or run `dotmd init`).
+
+### Rich status definitions (recommended)
+
+Define each status as an object that co-locates all behavioral properties. Adding a new status is one line in one place — no need to update separate `lifecycle`, `staleDays`, `context`, or `taxonomy` sections.
+
+```js
+export const root = 'docs/plans';
+export const archiveDir = 'archived';
+
+export const types = {
+  plan: {
+    statuses: {
+      'active':   { context: 'expanded', staleDays: 14, requiresModule: true },
+      'planned':  { context: 'listed', staleDays: 30, requiresModule: true },
+      'blocked':  { context: 'listed', staleDays: 30, skipStale: true },
+      'archived': { context: 'counted', archive: true, terminal: true, skipStale: true, skipWarnings: true },
+    },
+  },
+};
+```
+
+**Status properties:**
+
+| Property | Type | Default | Effect |
+|---|---|---|---|
+| `context` | `'expanded'` \| `'listed'` \| `'counted'` | `'counted'` | Display mode in `dotmd context` |
+| `staleDays` | `number` \| `null` | `null` | Days before doc is stale (`null` = never) |
+| `requiresModule` | `boolean` | `false` | Require `module` in frontmatter |
+| `terminal` | `boolean` | `false` | Skip `current_state`/`next_step` warnings |
+| `archive` | `boolean` | `false` | Auto-move to `archiveDir` on transition |
+| `skipStale` | `boolean` | `false` | Exempt from stale checks |
+| `skipWarnings` | `boolean` | `false` | Exempt from validation warnings |
+
+Object key order determines display order. The config resolver derives `statuses.order`, `lifecycle.*`, `taxonomy.moduleRequiredFor`, and `context.*` from these definitions. Explicit global sections still win when provided.
+
+### Array form (also supported)
+
+The traditional array form remains fully backwards compatible:
 
 ```js
-export const root = 'docs/plans';         // string or array of paths
-export const archiveDir = 'archived';     // subdirectory for archived docs
+export const types = {
+  plan: {
+    statuses: ['active', 'planned', 'blocked', 'archived'],
+    context: { expanded: ['active'], listed: ['planned', 'blocked'], counted: ['archived'] },
+    staleDays: { active: 14, planned: 30, blocked: 30 },
+  },
+};
 
+// When using array form, define behavior in separate sections:
 export const statuses = {
-  order: ['draft', 'active', 'approved', 'superseded', 'archived'],
-  staleDays: { draft: 7, active: 14, approved: 30 },
+  order: ['active', 'planned', 'blocked', 'archived'],
+  staleDays: { active: 14, planned: 30, blocked: 30 },
 };
 
 export const lifecycle = {
-  archiveStatuses: ['archived'],          // auto-move to archiveDir
+  archiveStatuses: ['archived'],
   skipStaleFor: ['archived'],
   skipWarningsFor: ['archived'],
-  terminalStatuses: ['archived', 'deprecated', 'reference', 'done'],
+  terminalStatuses: ['archived'],
+};
+
+export const taxonomy = {
+  moduleRequiredFor: ['active', 'planned', 'blocked'],
 };
+```
 
+### Other config
+
+```js
 export const taxonomy = {
   surfaces: ['web', 'ios', 'backend', 'api', 'platform'],
-  moduleRequiredFor: ['active', 'ready', 'planned', 'blocked'],
 };
 
 export const referenceFields = {
@@ -465,7 +516,7 @@ export const index = {
 };
 ```
 
-All exports are optional. Additional options: `types`, `context`, `display`, `presets`, `templates`, `excludeDirs`, `notion`. See [`dotmd.config.example.mjs`](dotmd.config.example.mjs) for the full reference.
+All exports are optional. Additional options: `context`, `display`, `presets`, `templates`, `excludeDirs`, `notion`. See [`dotmd.config.example.mjs`](dotmd.config.example.mjs) for the full reference.
 
 Config discovery walks up from cwd looking for `dotmd.config.mjs` or `.dotmd.config.mjs`.
 

package/bin/dotmd.mjs

@@ -500,7 +500,7 @@ async function main() {
     const { buildIndex } = await import('../src/index.mjs');
     const { runQuery } = await import('../src/query.mjs');
     const index = buildIndex(config);
-    runQuery(index, [...config.presets[command], ...restArgs], config);
+    runQuery(index, [...config.presets[command], ...restArgs], config, { preset: command });
     return;
   }
 

package/dotmd.config.example.mjs

@@ -13,27 +13,58 @@ export const archiveDir = 'archived';
 // Directories to skip when scanning
 export const excludeDirs = ['evidence'];
 
-// Document types — each type has its own status vocabulary and context layout
+// Document types — each type has its own status vocabulary and context layout.
 // Defaults: plan, doc, research. Override to customize statuses per type.
+//
+// Statuses can be defined as an array (names only) or as an object (rich form).
+// The object form co-locates all behavioral properties with each status,
+// eliminating the need for separate lifecycle, staleDays, context, and taxonomy sections.
+
+// ─── Rich status definitions (recommended) ──────────────────────────────────
+// Each status is an object with optional properties:
+//   context:        'expanded' | 'listed' | 'counted' (default: 'counted')
+//   staleDays:      number | null — stale threshold (default: null = never stale)
+//   requiresModule: boolean — require `module` frontmatter (default: false)
+//   terminal:       boolean — skip current_state/next_step warnings (default: false)
+//   archive:        boolean — auto-move to archiveDir on transition (default: false)
+//   skipStale:      boolean — exempt from stale checks (default: false)
+//   skipWarnings:   boolean — exempt from validation warnings (default: false)
+//
 // export const types = {
 //   plan: {
-//     statuses: ['in-session', 'active', 'planned', 'blocked', 'done', 'archived'],
-//     context: { expanded: ['in-session', 'active'], listed: ['planned', 'blocked'], counted: ['done', 'archived'] },
-//     staleDays: { 'in-session': 1, active: 14, planned: 30, blocked: 30 },
+//     statuses: {
+//       'in-session': { context: 'expanded', staleDays: 1, requiresModule: true },
+//       'active':     { context: 'expanded', staleDays: 14, requiresModule: true },
+//       'planned':    { context: 'listed', staleDays: 30, requiresModule: true },
+//       'blocked':    { context: 'listed', staleDays: 30, requiresModule: true, skipStale: true },
+//       'done':       { context: 'counted', terminal: true, skipStale: true, skipWarnings: true },
+//       'archived':   { context: 'counted', archive: true, terminal: true, skipStale: true, skipWarnings: true },
+//     },
 //   },
 //   doc: {
-//     statuses: ['draft', 'active', 'review', 'reference', 'deprecated', 'archived'],
-//     context: { expanded: ['active'], listed: ['draft', 'review'], counted: ['reference', 'deprecated', 'archived'] },
-//     staleDays: { draft: 30, active: 14, review: 14 },
+//     statuses: {
+//       'draft':      { context: 'listed', staleDays: 30 },
+//       'active':     { context: 'expanded', staleDays: 14 },
+//       'review':     { context: 'listed', staleDays: 14 },
+//       'reference':  { context: 'counted', skipStale: true },
+//       'deprecated': { context: 'counted', terminal: true, skipStale: true },
+//       'archived':   { context: 'counted', archive: true, terminal: true, skipStale: true, skipWarnings: true },
+//     },
 //   },
-//   research: {
-//     statuses: ['active', 'reference', 'archived'],
-//     context: { expanded: ['active'], listed: [], counted: ['reference', 'archived'] },
-//     staleDays: { active: 30 },
+// };
+
+// ─── Array form (also supported) ────────────────────────────────────────────
+// When using array form, define behavior in separate statuses/lifecycle/taxonomy sections.
+// export const types = {
+//   plan: {
+//     statuses: ['in-session', 'active', 'planned', 'blocked', 'done', 'archived'],
+//     context: { expanded: ['in-session', 'active'], listed: ['planned', 'blocked'], counted: ['done', 'archived'] },
+//     staleDays: { 'in-session': 1, active: 14, planned: 30, blocked: 30 },
 //   },
 // };
 
 // Status workflow — fallback for docs without a type field. Order determines display grouping.
+// When using rich status definitions, statuses.order and staleDays are derived automatically.
 export const statuses = {
   order: ['active', 'ready', 'planned', 'research', 'blocked', 'reference', 'archived'],
   // Additional statuses valid only in specific roots (merged with order)
@@ -52,7 +83,8 @@ export const statuses = {
   },
 };
 
-// Lifecycle behavior — which statuses trigger special handling
+// Lifecycle behavior — which statuses trigger special handling.
+// When using rich status definitions, these are derived from per-status flags.
 export const lifecycle = {
   archiveStatuses: ['archived'],      // auto-move to archiveDir on transition
   skipStaleFor: ['archived'],         // skip staleness checks
@@ -60,7 +92,8 @@ export const lifecycle = {
   terminalStatuses: ['archived', 'deprecated', 'reference', 'done'],  // skip current_state/next_step warnings, exclude from stats scope
 };
 
-// Taxonomy validation — set fields to null to skip validation
+// Taxonomy validation — set fields to null to skip validation.
+// moduleRequiredFor is derived from requiresModule when using rich status definitions.
 export const taxonomy = {
   surfaces: ['web', 'ios', 'android', 'mobile', 'full-stack', 'frontend', 'backend', 'api', 'docs', 'ops', 'platform', 'infra', 'design'],
   moduleRequiredFor: ['active', 'ready', 'planned', 'blocked'],

package/package.json

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

package/src/query.mjs

@@ -1,12 +1,12 @@
 import { readFileSync } from 'node:fs';
 import path from 'node:path';
-import { capitalize, toSlug, warn } from './util.mjs';
+import { capitalize, toSlug, truncate, warn } from './util.mjs';
 import { renderProgressBar } from './render.mjs';
 import { computeDaysSinceUpdate, computeIsStale } from './validate.mjs';
 import { getGitLastModifiedBatch } from './git.mjs';
 import { extractFrontmatter } from './frontmatter.mjs';
 import { summarizeDocBody } from './ai.mjs';
-import { dim } from './color.mjs';
+import { bold, dim, yellow, red } from './color.mjs';
 
 export function runFocus(index, argv, config) {
   // Find first positional arg, skipping flag-value pairs like --root <name>
@@ -50,7 +50,7 @@ export function runFocus(index, argv, config) {
   }
 }
 
-export function runQuery(index, argv, config) {
+export function runQuery(index, argv, config, opts = {}) {
   const filters = parseQueryArgs(argv);
   const docs = filterDocs(index.docs, filters, config);
 
@@ -64,6 +64,11 @@ export function runQuery(index, argv, config) {
     return;
   }
 
+  if (opts.preset === 'plans') {
+    renderPlansOutput(docs, filters, config);
+    return;
+  }
+
   renderQueryResults(docs, filters, config);
 }
 
@@ -227,3 +232,66 @@ function compareUpdatedDesc(a, b) {
   const au = a.updated ?? ''; const bu = b.updated ?? '';
   return au !== bu ? bu.localeCompare(au) : 0;
 }
+
+function renderPlansOutput(docs, filters, config) {
+  if (docs.length === 0) {
+    process.stdout.write('No plans found.\n');
+    return;
+  }
+
+  // Summary line
+  const bySt = {};
+  for (const d of docs) { bySt[d.status] = (bySt[d.status] ?? 0) + 1; }
+  const counts = Object.entries(bySt).map(([s, n]) => `${n} ${s}`).join(', ');
+  process.stdout.write(`${bold('Plans')} ${dim(`(${docs.length})`)}  ${counts}\n`);
+
+  // Active filter note (only if user applied extra filters beyond the preset defaults)
+  const activeFilters = [];
+  if (filters.statuses?.length) activeFilters.push(`status: ${filters.statuses.join(', ')}`);
+  if (filters.keyword) activeFilters.push(`keyword: ${filters.keyword}`);
+  if (filters.stale) activeFilters.push('stale only');
+  if (filters.hasNextStep) activeFilters.push('has next step');
+  if (filters.hasBlockers) activeFilters.push('has blockers');
+  if (activeFilters.length) process.stdout.write(dim(`  filtered: ${activeFilters.join(' | ')}`) + '\n');
+
+  // Group by status, ordered by config.statusOrder
+  const statusGroups = new Map();
+  for (const d of docs) {
+    const s = d.status ?? 'unknown';
+    if (!statusGroups.has(s)) statusGroups.set(s, []);
+    statusGroups.get(s).push(d);
+  }
+
+  const orderedStatuses = [...config.statusOrder.filter(s => statusGroups.has(s)), ...([...statusGroups.keys()].filter(s => !config.statusOrder.includes(s)))];
+  const maxWidth = process.stdout.columns || 100;
+
+  for (const status of orderedStatuses) {
+    const group = statusGroups.get(status);
+    process.stdout.write(`\n${bold(`${capitalize(status)} (${group.length})`)}\n`);
+
+    const maxSlug = Math.min(30, Math.max(...group.map(d => toSlug(d).length)));
+
+    for (const doc of group) {
+      const slug = toSlug(doc).padEnd(maxSlug);
+      const age = doc.daysSinceUpdate != null ? `${doc.daysSinceUpdate}d` : ' —';
+      const ageStr = doc.daysSinceUpdate != null && doc.isStale ? red(age.padStart(4)) : dim(age.padStart(4));
+      const progress = renderProgressBar(doc.checklist);
+
+      const parts = [`  ${slug}  ${ageStr}`];
+      if (progress) parts.push(progress);
+
+      if (doc.blockers?.length && (status === 'blocked')) {
+        parts.push(yellow(`blockers: ${doc.blockers.join('; ')}`));
+      } else if (doc.nextStep) {
+        parts.push(`next: ${doc.nextStep}`);
+      } else {
+        parts.push(dim('(no next step)'));
+      }
+
+      const line = parts.join('  ');
+      process.stdout.write((line.length > maxWidth ? line.slice(0, maxWidth - 3) + '...' : line) + '\n');
+    }
+  }
+
+  process.stdout.write('\n');
+}