dotmd-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Beyond
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,187 @@
+# dotmd
+
+Zero-dependency CLI for managing markdown documents with YAML frontmatter.
+
+Index, query, validate, and lifecycle-manage any collection of `.md` files — plans, ADRs, RFCs, design docs, meeting notes. Built for AI-assisted development workflows where structured docs need to stay current.
+
+## Install
+
+```bash
+npm install -g dotmd-cli
+```
+
+## Quick Start
+
+```bash
+dotmd init              # creates dotmd.config.mjs + docs/ + docs/README.md
+dotmd list              # index all docs grouped by status
+dotmd check             # validate frontmatter and references
+dotmd context           # compact briefing (great for LLM context)
+```
+
+## What It Does
+
+dotmd scans a directory of markdown files, parses their YAML frontmatter, and gives you tools to work with them:
+
+- **Index** — group docs by status, show progress bars, next steps
+- **Query** — filter by status, keyword, module, surface, owner, staleness
+- **Validate** — check for missing fields, broken references, stale dates
+- **Lifecycle** — transition statuses, auto-archive with `git mv`, bump dates
+- **README generation** — auto-generate an index block in your README
+- **Context briefing** — compact summary designed for AI/LLM consumption
+
+## Document Format
+
+Any `.md` file with YAML frontmatter:
+
+```markdown
+---
+status: active
+updated: 2026-03-14
+module: auth
+surface: backend
+next_step: implement token refresh
+current_state: initial scaffolding complete
+---
+
+# Auth Token Refresh
+
+Design doc content here...
+
+- [x] Research existing patterns
+- [ ] Implement refresh logic
+- [ ] Add tests
+```
+
+The only required field is `status`. Everything else is optional but unlocks more features (staleness detection, filtering, coverage reports).
+
+## Commands
+
+```
+dotmd list [--verbose]       List docs grouped by status
+dotmd json                   Full index as JSON
+dotmd check                  Validate frontmatter and references
+dotmd coverage [--json]      Metadata coverage report
+dotmd context                Compact briefing (LLM-oriented)
+dotmd focus [status]         Detailed view for one status group
+dotmd query [filters]        Filtered search
+dotmd index [--write]        Generate/update docs.md index block
+dotmd status <file> <status> Transition document status
+dotmd archive <file>         Archive (status + move + index regen)
+dotmd touch <file>           Bump updated date
+dotmd init                   Create starter config + docs directory
+```
+
+### Query Filters
+
+```bash
+dotmd query --status active,ready --module auth
+dotmd query --keyword "token" --has-next-step
+dotmd query --stale --sort updated --all
+dotmd query --surface backend --checklist-open
+```
+
+Flags: `--status`, `--keyword`, `--module`, `--surface`, `--domain`, `--owner`, `--updated-since`, `--stale`, `--has-next-step`, `--has-blockers`, `--checklist-open`, `--sort`, `--limit`, `--all`, `--git`, `--json`.
+
+### Preset Aliases
+
+Define custom query presets in your config:
+
+```js
+export const presets = {
+  stale: ['--status', 'active,ready', '--stale', '--sort', 'updated', '--all'],
+  mine: ['--owner', 'robert', '--status', 'active', '--all'],
+};
+```
+
+Then run `dotmd stale` or `dotmd mine` as shorthand.
+
+## Configuration
+
+Create `dotmd.config.mjs` at your project root (or run `dotmd init`):
+
+```js
+export const root = 'docs/plans';         // where your .md files live
+export const archiveDir = 'archived';     // subdirectory for archived docs
+
+export const statuses = {
+  order: ['draft', 'active', 'approved', 'superseded', 'archived'],
+  staleDays: { draft: 7, active: 14, approved: 30 },
+};
+
+export const lifecycle = {
+  archiveStatuses: ['archived'],          // auto-move to archiveDir
+  skipStaleFor: ['archived'],
+  skipWarningsFor: ['archived'],
+};
+
+export const readme = {
+  path: 'docs/plans/README.md',
+  startMarker: '<!-- GENERATED:dotmd:start -->',
+  endMarker: '<!-- GENERATED:dotmd:end -->',
+};
+```
+
+All exports are optional. 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`.
+
+## Hooks
+
+Hooks are function exports in your config file. They let you extend validation, customize rendering, and react to lifecycle events.
+
+### Custom Validation
+
+```js
+export function validate(doc, ctx) {
+  const warnings = [];
+  if (doc.status === 'active' && !doc.owner) {
+    warnings.push({
+      path: doc.path,
+      level: 'warning',
+      message: 'Active docs should have an owner.',
+    });
+  }
+  return { errors: [], warnings };
+}
+```
+
+### Render Hooks
+
+Override any renderer by exporting a function that receives the default:
+
+```js
+export function renderContext(index, defaultRenderer) {
+  let output = defaultRenderer(index);
+  return `# My Project\n\n${output}`;
+}
+```
+
+Available: `renderContext`, `renderCompactList`, `renderCheck`, `formatSnapshot`.
+
+### Lifecycle Hooks
+
+```js
+export function onArchive(doc, { oldPath, newPath }) {
+  console.log(`Archived: ${oldPath} → ${newPath}`);
+}
+
+export function onStatusChange(doc, { oldStatus, newStatus }) {
+  // notify, log, trigger CI, etc.
+}
+```
+
+Available: `onArchive`, `onStatusChange`, `onTouch`.
+
+## Features
+
+- **Zero dependencies** — pure Node.js builtins (`fs`, `path`, `child_process`)
+- **No build step** — ships as plain ESM, runs directly
+- **Git-aware** — detects frontmatter date drift vs git history, uses `git mv` for archives
+- **Configurable everything** — statuses, taxonomy, lifecycle, validation rules, display
+- **Hook system** — extend with JS functions, no plugin framework to learn
+- **LLM-friendly** — `dotmd context` generates compact briefings for AI assistants
+
+## License
+
+MIT

package/bin/dotmd.mjs

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import { resolveConfig } from '../src/config.mjs';
+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 } from '../src/lifecycle.mjs';
+import { runInit } from '../src/init.mjs';
+import { die } from '../src/util.mjs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const pkg = JSON.parse(readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
+
+const HELP = {
+  _main: `dotmd v${pkg.version} — frontmatter markdown document manager
+
+Commands:
+  list [--verbose]       List docs grouped by status (default)
+  json                   Full index as JSON
+  check                  Validate frontmatter and references
+  coverage [--json]      Metadata coverage report
+  context                Compact briefing (LLM-oriented)
+  focus [status]         Detailed view for one status group
+  query [filters]        Filtered search
+  index [--write]        Generate/update docs.md index block
+  status <file> <status> Transition document status
+  archive <file>         Archive (status + move + index regen)
+  touch <file>           Bump updated date
+  init                   Create starter config + docs directory
+
+Options:
+  --config <path>        Explicit config file path
+  --dry-run, -n          Preview changes without writing anything
+  --help, -h             Show help
+  --version, -v          Show version`,
+
+  query: `dotmd query — filtered document search
+
+Filters:
+  --status <s1,s2>       Filter by status (comma-separated)
+  --keyword <term>       Search title, summary, state, path
+  --module <name>        Filter by module
+  --surface <name>       Filter by surface
+  --domain <name>        Filter by domain
+  --owner <name>         Filter by owner
+  --updated-since <date> Only docs updated after date
+  --stale                Only stale docs
+  --has-next-step        Only docs with a next step
+  --has-blockers         Only docs with blockers
+  --checklist-open       Only docs with open checklist items
+  --sort <field>         Sort by: updated (default), title, status
+  --limit <n>            Max results (default: 20)
+  --all                  Show all results (no limit)
+  --git                  Use git dates instead of frontmatter
+  --json                 Output as JSON`,
+
+  status: `dotmd status <file> <new-status> — transition document status
+
+Moves the document to the new status. If transitioning to an archive
+status, automatically moves the file to the archive directory and
+regenerates the index (if configured).
+
+Use --dry-run (-n) to preview changes without writing anything.`,
+
+  archive: `dotmd archive <file> — archive a document
+
+Sets status to 'archived', moves to the archive directory, regenerates
+the index, and scans for stale references.
+
+Use --dry-run (-n) to preview changes without writing anything.`,
+
+  index: `dotmd index [--write] — generate/update docs.md index
+
+Without --write, prints the generated content to stdout.
+With --write, updates the configured index file in place.
+
+Use --dry-run (-n) with --write to preview without writing.`,
+
+  init: `dotmd init — create starter config and docs directory
+
+Creates dotmd.config.mjs, docs/, and docs/docs.md in the current
+directory. Skips any files that already exist.`,
+};
+
+async function main() {
+  const args = process.argv.slice(2);
+  const command = args[0] ?? 'list';
+
+  // Pre-config flags
+  if (args.includes('--version') || args.includes('-v')) {
+    process.stdout.write(`${pkg.version}\n`);
+    return;
+  }
+
+  if (command === '--help' || command === '-h') {
+    process.stdout.write(`${HELP._main}\n`);
+    return;
+  }
+
+  // Per-command help
+  if (args.includes('--help') || args.includes('-h')) {
+    process.stdout.write(`${HELP[command] ?? HELP._main}\n`);
+    return;
+  }
+
+  // Init doesn't need config
+  if (command === 'init') {
+    runInit(process.cwd());
+    return;
+  }
+
+  // Extract --config flag
+  let explicitConfig = null;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--config' && args[i + 1]) {
+      explicitConfig = args[i + 1];
+      break;
+    }
+  }
+
+  const dryRun = args.includes('--dry-run') || args.includes('-n');
+
+  const config = await resolveConfig(process.cwd(), explicitConfig);
+  const restArgs = args.slice(1);
+
+  // Preset aliases
+  if (config.presets[command]) {
+    const index = buildIndex(config);
+    runQuery(index, [...config.presets[command], ...restArgs], config);
+    return;
+  }
+
+  // Lifecycle commands
+  if (command === 'status') { runStatus(restArgs, config, { dryRun }); return; }
+  if (command === 'archive') { runArchive(restArgs, config, { dryRun }); return; }
+  if (command === 'touch') { runTouch(restArgs, config, { dryRun }); return; }
+
+  const index = buildIndex(config);
+
+  if (command === 'json') {
+    process.stdout.write(`${JSON.stringify(index, null, 2)}\n`);
+    return;
+  }
+
+  if (command === 'list') {
+    if (args.includes('--verbose')) {
+      process.stdout.write(renderVerboseList(index, config));
+    } else {
+      process.stdout.write(renderCompactList(index, config));
+    }
+    return;
+  }
+
+  if (command === 'check') {
+    process.stdout.write(renderCheck(index, config));
+    if (index.errors.length > 0) process.exitCode = 1;
+    return;
+  }
+
+  if (command === 'coverage') {
+    if (args.includes('--json')) {
+      process.stdout.write(`${JSON.stringify(buildCoverage(index, config), null, 2)}\n`);
+    } else {
+      process.stdout.write(renderCoverage(index, config));
+    }
+    return;
+  }
+
+  if (command === 'index') {
+    if (!config.indexPath) {
+      die('Index generation is not configured. Add an `index` section to your dotmd.config.mjs.');
+      return;
+    }
+    const write = args.includes('--write');
+    const rendered = renderIndexFile(index, config);
+    if (write && !dryRun) {
+      writeIndex(rendered, config);
+      process.stdout.write(`Updated ${config.indexPath}\n`);
+    } else if (write && dryRun) {
+      process.stdout.write(`[dry-run] Would update ${config.indexPath}\n`);
+    } else {
+      process.stdout.write(rendered);
+    }
+    return;
+  }
+
+  if (command === 'focus') { runFocus(index, restArgs, config); return; }
+  if (command === 'query') { runQuery(index, restArgs, config); return; }
+  if (command === 'context') { process.stdout.write(renderContext(index, config)); return; }
+
+  // Unknown command — show help
+  die(`Unknown command: ${command}\n\n${HELP._main}`);
+}
+
+main().catch(err => {
+  die(err.message);
+});

package/dotmd.config.example.mjs

@@ -0,0 +1,116 @@
+// dotmd.config.mjs — document management configuration
+// All exports are optional. Omitted values use built-in defaults.
+// Place this file at the root of your project.
+
+// ─── Static Config ───────────────────────────────────────────────────────────
+
+// Directory containing your markdown docs (relative to this config file)
+export const root = 'docs';
+
+// Subdirectory for archived docs (used by `dotmd archive` and `dotmd status`)
+export const archiveDir = 'archived';
+
+// Directories to skip when scanning
+export const excludeDirs = ['evidence'];
+
+// Status workflow — order determines display grouping
+export const statuses = {
+  order: ['active', 'ready', 'planned', 'research', 'blocked', 'reference', 'archived'],
+  // Days after which a doc is considered stale (null = never stale)
+  staleDays: {
+    active: 14,
+    ready: 14,
+    planned: 30,
+    blocked: 30,
+    research: 30,
+  },
+};
+
+// Lifecycle behavior — which statuses trigger special handling
+export const lifecycle = {
+  archiveStatuses: ['archived'],      // auto-move to archiveDir on transition
+  skipStaleFor: ['archived'],         // skip staleness checks
+  skipWarningsFor: ['archived'],      // skip validation warnings (summary, etc.)
+};
+
+// Taxonomy validation — set fields to null to skip validation
+export const taxonomy = {
+  surfaces: ['frontend', 'backend', 'mobile', 'docs', 'ops', 'platform'],
+  moduleRequiredFor: ['active', 'ready', 'planned', 'blocked'],
+};
+
+// Index file generation — remove this section to disable
+export const index = {
+  path: 'docs/docs.md',
+  startMarker: '<!-- GENERATED:dotmd:start -->',
+  endMarker: '<!-- GENERATED:dotmd:end -->',
+  archivedLimit: 8,
+};
+
+// Context briefing layout (`dotmd context`)
+export const context = {
+  expanded: ['active'],
+  listed: ['ready', 'planned'],
+  counted: ['blocked', 'research', 'reference', 'archived'],
+  recentDays: 3,
+  recentStatuses: ['active', 'ready', 'planned'],
+  recentLimit: 10,
+  truncateNextStep: 80,
+};
+
+// Display settings
+export const display = {
+  lineWidth: 0,         // 0 = auto-detect terminal width
+  truncateTitle: 30,
+  truncateNextStep: 80,
+};
+
+// Reference fields for bidirectional link checking
+export const referenceFields = {
+  bidirectional: ['related_docs'],    // warn if A→B but B↛A
+  unidirectional: ['supports'],       // one-way, no symmetry check
+};
+
+// Query presets — expand to filter args when used as commands
+export const presets = {
+  stale: ['--status', 'active,ready,planned,blocked,research', '--stale', '--sort', 'updated', '--all'],
+  actionable: ['--status', 'active,ready', '--has-next-step', '--sort', 'updated', '--all'],
+};
+
+// ─── Function Hooks ──────────────────────────────────────────────────────────
+// Hooks are optional. Each receives a default implementation it can wrap or replace.
+
+// Custom validation — called after built-in validation for each doc.
+// Return { errors: [], warnings: [] } to add issues.
+// export function validate(doc, ctx) {
+//   const warnings = [];
+//   if (doc.status === 'active' && !doc.owner) {
+//     warnings.push({ path: doc.path, level: 'warning', message: 'Active docs should have an owner.' });
+//   }
+//   return { errors: [], warnings };
+// }
+
+// Override the context briefing output.
+// export function renderContext(index, defaultRenderer) {
+//   return defaultRenderer(index);
+// }
+
+// Override the index file rendering.
+// export function renderIndex(index, defaultRenderer) {
+//   return defaultRenderer(index);
+// }
+
+// Override the status snapshot display format.
+// export function formatSnapshot(doc, defaultFormatter) {
+//   return defaultFormatter(doc);
+// }
+
+// Post-parse doc transformation — add computed fields.
+// export function transformDoc(doc) {
+//   return doc;
+// }
+
+// Lifecycle callbacks — fire after the operation completes.
+// export function onArchive(doc, { oldPath, newPath }) {}
+// export function onStatusChange(doc, { oldStatus, newStatus, path }) {}
+// export function onTouch(doc, { path, date }) {}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "dotmd-cli",
+  "version": "0.1.0",
+  "description": "Zero-dependency CLI for managing markdown documents with YAML frontmatter — index, query, validate, lifecycle.",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "dotmd": "bin/dotmd.mjs"
+  },
+  "exports": {
+    ".": "./src/index.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "dotmd.config.example.mjs"
+  ],
+  "keywords": [
+    "markdown",
+    "frontmatter",
+    "cli",
+    "docs",
+    "plans",
+    "adr",
+    "rfc",
+    "document-management",
+    "yaml"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/beyond-dev/platform.git",
+    "directory": "packages/dotmd"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/color.mjs

@@ -0,0 +1,10 @@
+const enabled = (process.env.FORCE_COLOR === '1')
+  || (process.stdout.isTTY && !process.env.NO_COLOR);
+
+const wrap = (code) => enabled ? (s) => `\x1b[${code}m${s}\x1b[0m` : (s) => s;
+
+export const bold = wrap('1');
+export const dim = wrap('2');
+export const red = wrap('31');
+export const yellow = wrap('33');
+export const green = wrap('32');