dotmd-cli 0.1.0 → 0.2.0

package/bin/dotmd.mjs

@@ -10,7 +10,9 @@ 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';
+import { runNew } from '../src/new.mjs';
+import { runCompletions } from '../src/completions.mjs';
+import { die, warn } from '../src/util.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -31,11 +33,14 @@ Commands:
   status <file> <status> Transition document status
   archive <file>         Archive (status + move + index regen)
   touch <file>           Bump updated date
+  new <name>             Create a new document with frontmatter
   init                   Create starter config + docs directory
+  completions <shell>    Output shell completion script (bash, zsh)
 
 Options:
   --config <path>        Explicit config file path
   --dry-run, -n          Preview changes without writing anything
+  --verbose              Show config details and doc count
   --help, -h             Show help
   --version, -v          Show version`,
 
@@ -81,6 +86,17 @@ With --write, updates the configured index file in place.
 
 Use --dry-run (-n) with --write to preview without writing.`,
 
+  new: `dotmd new <name> — create a new document
+
+Creates a new markdown document with frontmatter in the docs root.
+
+Options:
+  --status <s>         Set initial status (default: active)
+  --title <t>          Override the document title
+
+The filename is derived from <name> by slugifying it.
+Use --dry-run (-n) to preview without creating the file.`,
+
   init: `dotmd init — create starter config and docs directory
 
 Creates dotmd.config.mjs, docs/, and docs/docs.md in the current
@@ -108,12 +124,17 @@ async function main() {
     return;
   }
 
-  // Init doesn't need config
+  // Init and completions don't need config
   if (command === 'init') {
     runInit(process.cwd());
     return;
   }
 
+  if (command === 'completions') {
+    runCompletions(args.slice(1));
+    return;
+  }
+
   // Extract --config flag
   let explicitConfig = null;
   for (let i = 0; i < args.length; i++) {
@@ -124,10 +145,21 @@ async function main() {
   }
 
   const dryRun = args.includes('--dry-run') || args.includes('-n');
+  const verbose = args.includes('--verbose');
 
   const config = await resolveConfig(process.cwd(), explicitConfig);
   const restArgs = args.slice(1);
 
+  if (!config.configFound && command !== 'init') {
+    warn('No dotmd config found — using defaults. Run `dotmd init` to create one.');
+  }
+
+  if (verbose) {
+    process.stderr.write(`Config: ${config.configPath ?? 'none'}\n`);
+    process.stderr.write(`Docs root: ${config.docsRoot}\n`);
+    process.stderr.write(`Repo root: ${config.repoRoot}\n`);
+  }
+
   // Preset aliases
   if (config.presets[command]) {
     const index = buildIndex(config);
@@ -139,9 +171,14 @@ async function main() {
   if (command === 'status') { runStatus(restArgs, config, { dryRun }); return; }
   if (command === 'archive') { runArchive(restArgs, config, { dryRun }); return; }
   if (command === 'touch') { runTouch(restArgs, config, { dryRun }); return; }
+  if (command === 'new') { runNew(restArgs, config, { dryRun }); return; }
 
   const index = buildIndex(config);
 
+  if (verbose) {
+    process.stderr.write(`Docs found: ${index.docs.length}\n`);
+  }
+
   if (command === 'json') {
     process.stdout.write(`${JSON.stringify(index, null, 2)}\n`);
     return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Zero-dependency CLI for managing markdown documents with YAML frontmatter — index, query, validate, lifecycle.",
   "type": "module",
   "license": "MIT",
@@ -31,6 +31,9 @@
     "url": "git+https://github.com/beyond-dev/platform.git",
     "directory": "packages/dotmd"
   },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
   "engines": {
     "node": ">=18"
   }

package/src/completions.mjs

@@ -0,0 +1,97 @@
+import { die } from './util.mjs';
+
+const COMMANDS = [
+  'list', 'json', 'check', 'coverage', 'context', 'focus', 'query',
+  'index', 'status', 'archive', 'touch', 'init', 'new', 'completions',
+];
+
+const GLOBAL_FLAGS = ['--config', '--dry-run', '--verbose', '--help', '--version'];
+
+const COMMAND_FLAGS = {
+  query: ['--status', '--keyword', '--module', '--surface', '--domain', '--owner',
+          '--updated-since', '--stale', '--has-next-step', '--has-blockers',
+          '--checklist-open', '--sort', '--limit', '--all', '--git', '--json'],
+  index: ['--write'],
+  list: ['--verbose'],
+  coverage: ['--json'],
+  new: ['--status', '--title'],
+};
+
+function bashCompletion() {
+  return `# dotmd bash completion
+# Add to ~/.bashrc: eval "$(dotmd completions bash)"
+_dotmd() {
+  local cur prev cmd
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  prev="\${COMP_WORDS[COMP_CWORD-1]}"
+
+  # Find the subcommand
+  cmd=""
+  for ((i=1; i < COMP_CWORD; i++)); do
+    case "\${COMP_WORDS[i]}" in
+      -*) ;;
+      *) cmd="\${COMP_WORDS[i]}"; break ;;
+    esac
+  done
+
+  # Complete commands if no subcommand yet
+  if [[ -z "$cmd" ]]; then
+    COMPREPLY=( $(compgen -W "${COMMANDS.join(' ')} ${GLOBAL_FLAGS.join(' ')}" -- "$cur") )
+    return
+  fi
+
+  # Per-command flag completion
+  case "$cmd" in
+${Object.entries(COMMAND_FLAGS).map(([cmd, flags]) =>
+    `    ${cmd}) COMPREPLY=( $(compgen -W "${flags.join(' ')} ${GLOBAL_FLAGS.join(' ')}" -- "$cur") ) ;;`
+  ).join('\n')}
+    *) COMPREPLY=( $(compgen -W "${GLOBAL_FLAGS.join(' ')}" -- "$cur") ) ;;
+  esac
+}
+complete -F _dotmd dotmd`;
+}
+
+function zshCompletion() {
+  return `# dotmd zsh completion
+# Add to ~/.zshrc: eval "$(dotmd completions zsh)"
+_dotmd() {
+  local -a commands global_flags
+  commands=(
+${COMMANDS.map(c => `    '${c}'`).join('\n')}
+  )
+  global_flags=(
+${GLOBAL_FLAGS.map(f => `    '${f}'`).join('\n')}
+  )
+
+  if (( CURRENT == 2 )); then
+    _describe 'command' commands
+    _describe 'flag' global_flags
+    return
+  fi
+
+  local cmd=\${words[2]}
+  case "$cmd" in
+${Object.entries(COMMAND_FLAGS).map(([cmd, flags]) =>
+    `    ${cmd}) _values 'flags' ${flags.map(f => `'${f}'`).join(' ')} ;;`
+  ).join('\n')}
+  esac
+
+  _describe 'flag' global_flags
+}
+compdef _dotmd dotmd`;
+}
+
+export function runCompletions(argv) {
+  const shell = argv[0];
+  if (!shell) {
+    die('Usage: dotmd completions <bash|zsh>');
+    return;
+  }
+  if (shell === 'bash') {
+    process.stdout.write(bashCompletion() + '\n');
+  } else if (shell === 'zsh') {
+    process.stdout.write(zshCompletion() + '\n');
+  } else {
+    die(`Unsupported shell: ${shell}\nSupported: bash, zsh`);
+  }
+}

package/src/config.mjs

@@ -1,6 +1,7 @@
 import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { die, warn } from './util.mjs';
 
 const CONFIG_FILENAMES = ['dotmd.config.mjs', '.dotmd.config.mjs', 'dotmd.config.js'];
 
@@ -99,7 +100,27 @@ export async function resolveConfig(cwd, explicitConfigPath) {
 
   if (configPath && existsSync(configPath)) {
     const configUrl = pathToFileURL(configPath).href;
-    const mod = await import(configUrl);
+    let mod;
+    try {
+      mod = await import(configUrl);
+    } catch (err) {
+      die('Failed to load config: ' + configPath + '\n' + err.message + '\nRun `dotmd init` to create a starter config.');
+      // Return defaults so caller can still function
+      const defaults = deepMerge(DEFAULTS, {});
+      const defaultStatusOrder = defaults.statuses.order;
+      return {
+        raw: defaults, docsRoot: cwd, repoRoot: cwd, configDir: cwd,
+        configPath: configPath ?? null, configFound: Boolean(configPath),
+        archiveDir: defaults.archiveDir, excludeDirs: new Set(defaults.excludeDirs),
+        docsRootPrefix: '', statusOrder: defaultStatusOrder,
+        validStatuses: new Set(defaultStatusOrder), staleDaysByStatus: {},
+        lifecycle: { archiveStatuses: new Set(defaults.lifecycle.archiveStatuses), skipStaleFor: new Set(defaults.lifecycle.skipStaleFor), skipWarningsFor: new Set(defaults.lifecycle.skipWarningsFor) },
+        validSurfaces: null, moduleRequiredStatuses: new Set(),
+        indexPath: null, indexStartMarker: '<!-- GENERATED:dotmd:start -->', indexEndMarker: '<!-- GENERATED:dotmd:end -->', archivedHighlightLimit: 8,
+        context: defaults.context, display: defaults.display,
+        referenceFields: defaults.referenceFields, presets: defaults.presets, hooks: {},
+      };
+    }
 
     configDir = path.dirname(configPath);
 
@@ -123,6 +144,10 @@ export async function resolveConfig(cwd, explicitConfigPath) {
 
   const docsRoot = path.resolve(configDir, config.root);
 
+  if (!existsSync(docsRoot)) {
+    warn('Docs root does not exist: ' + docsRoot);
+  }
+
   // Find repo root by walking up looking for .git
   let repoRoot = configDir;
   {
@@ -170,6 +195,7 @@ export async function resolveConfig(cwd, explicitConfigPath) {
     repoRoot,
     configDir,
     configPath: configPath ?? null,
+    configFound: Boolean(configPath),
     archiveDir: config.archiveDir,
     excludeDirs: new Set(config.excludeDirs),
     docsRootPrefix,

package/src/lifecycle.mjs

@@ -16,7 +16,7 @@ export function runStatus(argv, config, opts = {}) {
   if (!config.validStatuses.has(newStatus)) { die(`Invalid status: ${newStatus}\nValid: ${[...config.validStatuses].join(', ')}`); return; }
 
   const filePath = resolveDocPath(input, config);
-  if (!filePath) { die(`File not found: ${input}`); return; }
+  if (!filePath) { die(`File not found: ${input}\nSearched: ${toRepoPath(config.repoRoot, config.repoRoot) || '.'}, ${toRepoPath(config.docsRoot, config.repoRoot)}`); return; }
 
   const raw = readFileSync(filePath, 'utf8');
   const { frontmatter } = extractFrontmatter(raw);
@@ -92,7 +92,7 @@ export function runArchive(argv, config, opts = {}) {
   if (!input) { die('Usage: dotmd archive <file>'); return; }
 
   const filePath = resolveDocPath(input, config);
-  if (!filePath) { die(`File not found: ${input}`); return; }
+  if (!filePath) { die(`File not found: ${input}\nSearched: ${toRepoPath(config.repoRoot, config.repoRoot) || '.'}, ${toRepoPath(config.docsRoot, config.repoRoot)}`); return; }
   if (filePath.includes(`/${config.archiveDir}/`)) { die(`Already archived: ${toRepoPath(filePath, config.repoRoot)}`); return; }
 
   const raw = readFileSync(filePath, 'utf8');
@@ -173,7 +173,7 @@ export function runTouch(argv, config, opts = {}) {
   if (!input) { die('Usage: dotmd touch <file>'); return; }
 
   const filePath = resolveDocPath(input, config);
-  if (!filePath) { die(`File not found: ${input}`); return; }
+  if (!filePath) { die(`File not found: ${input}\nSearched: ${toRepoPath(config.repoRoot, config.repoRoot) || '.'}, ${toRepoPath(config.docsRoot, config.repoRoot)}`); return; }
 
   const today = new Date().toISOString().slice(0, 10);
 

package/src/new.mjs

@@ -0,0 +1,54 @@
+import { existsSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { toRepoPath, die } from './util.mjs';
+import { green, dim } from './color.mjs';
+
+export function runNew(argv, config, opts = {}) {
+  const { dryRun } = opts;
+
+  // Parse args
+  const positional = [];
+  let status = 'active';
+  let title = null;
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--status' && argv[i + 1]) { status = argv[++i]; continue; }
+    if (argv[i] === '--title' && argv[i + 1]) { title = argv[++i]; continue; }
+    if (!argv[i].startsWith('-')) positional.push(argv[i]);
+  }
+
+  const name = positional[0];
+  if (!name) { die('Usage: dotmd new <name> [--status <s>] [--title <t>]'); return; }
+
+  // Validate status
+  if (!config.validStatuses.has(status)) {
+    die(`Invalid status: ${status}\nValid: ${[...config.validStatuses].join(', ')}`);
+    return;
+  }
+
+  // Slugify
+  const slug = name.toLowerCase().replace(/[\s_]+/g, '-').replace(/[^a-z0-9-]/g, '').replace(/-+/g, '-').replace(/^-|-$/g, '');
+  if (!slug) { die('Name resolves to empty slug: ' + name); return; }
+
+  // Title
+  const docTitle = title ?? name.replace(/[-_]/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
+
+  // Path
+  const filePath = path.join(config.docsRoot, slug + '.md');
+  const repoPath = toRepoPath(filePath, config.repoRoot);
+
+  if (existsSync(filePath)) {
+    die(`File already exists: ${repoPath}`);
+    return;
+  }
+
+  if (dryRun) {
+    process.stdout.write(`${dim('[dry-run]')} Would create: ${repoPath}\n`);
+    return;
+  }
+
+  const today = new Date().toISOString().slice(0, 10);
+  const content = `---\nstatus: ${status}\nupdated: ${today}\n---\n\n# ${docTitle}\n`;
+
+  writeFileSync(filePath, content, 'utf8');
+  process.stdout.write(`${green('Created')}: ${repoPath}\n`);
+}

package/src/util.mjs

@@ -1,4 +1,5 @@
 import path from 'node:path';
+import { dim } from './color.mjs';
 
 export function escapeTable(value) {
   return String(value).replace(/\|/g, '\\|');
@@ -49,6 +50,10 @@ export function toRepoPath(absolutePath, repoRoot) {
   return path.relative(repoRoot, absolutePath).split(path.sep).join('/');
 }
 
+export function warn(message) {
+  process.stderr.write(`${dim(message)}\n`);
+}
+
 export function die(message) {
   process.stderr.write(`${message}\n`);
   process.exitCode = 1;