@xxkeefer/mrkl 0.3.1 → 0.4.0

package/README.md

@@ -80,6 +80,7 @@ mrkl x PROJ-002            # close
 | `done` | `d` | Mark a task as done and archive it |
 | `close` | `x` | Close a task (won't do, duplicate, etc.) and archive it |
 | `prune` | `p` | Delete archived tasks created on or before a given date |
+| `migrate_prior_verbose` | — | Migrate legacy verbose-filename tasks to frontmatter-based format |
 | `install-skills` | — | Install bundled Claude Code skills |
 
 ### `mrkl init <prefix>`
@@ -175,6 +176,25 @@ mrkl prune 2026-01-31
 mrkl prune 2026-01-31 --force
 ```
 
+### `mrkl migrate_prior_verbose`
+
+Migrates task files from the legacy verbose-filename format to the current format. This is a **one-time migration** for projects that were using mrkl before v0.4.0.
+
+**What it does:**
+
+1. Scans all task files in `.tasks/` and `.tasks/.archive/`
+2. Extracts the title from the verbose filename (e.g., `PROJ-001 feat - user auth.md`)
+3. Writes the title into YAML frontmatter
+4. If `verbose_files = false` (default): renames files to short format (`PROJ-001.md`)
+5. If `verbose_files = true`: keeps verbose filenames as-is
+
+```sh
+mrkl migrate_prior_verbose
+# ✅ Migrated 12 file(s), skipped 3 file(s).
+```
+
+> **Note:** After upgrading to v0.4.0+, existing task files will fail to parse until migrated. Run this command once to fix them.
+
 ### `mrkl install-skills`
 
 Installs bundled Claude Code skills into the current project.
@@ -211,15 +231,16 @@ mrkl uses [conventional commit](https://www.conventionalcommits.org/) types:
 
 ## Task File Format 📄
 
-Each task is a markdown file with YAML frontmatter:
+Each task is a markdown file with YAML frontmatter. By default, filenames use the short format:
 
 ```
-.tasks/PROJ-001 feat - user authentication.md
+.tasks/PROJ-001.md
 ```
 
 ```markdown
 ---
 id: PROJ-001
+title: user authentication
 type: feat
 status: todo
 created: '2026-03-01'
@@ -235,7 +256,13 @@ Implement user authentication with OAuth2.
 - [ ] session persists across refreshes
 ```
 
-The format is intentionally simple — edit task files directly when you need to update descriptions, change status, or check off criteria.
+With `verbose_files = true`, filenames include the type and title:
+
+```
+.tasks/PROJ-001 feat - user authentication.md
+```
+
+The `title` is always stored in frontmatter regardless of filename format. Edit task files directly when you need to update descriptions, change status, or check off criteria.
 
 ## Project Structure 🗂️
 
@@ -247,10 +274,10 @@ your-project/
     mrkl.toml           # project configuration
     mrkl_counter        # current task number
   .tasks/
-    PROJ-001 feat - first task.md
-    PROJ-002 fix - second task.md
+    PROJ-001.md
+    PROJ-002.md
     .archive/
-      PROJ-000 chore - archived task.md
+      PROJ-000.md
 ```
 
 Commit `.config/mrkl/` and `.tasks/` to version control. They're designed to be tracked alongside your code.
@@ -286,12 +313,14 @@ Configuration lives in `.config/mrkl/mrkl.toml` (or `mrkl.toml` at the project r
 ```toml
 prefix = "PROJ"
 tasks_dir = ".tasks"
+verbose_files = false
 ```
 
 | Key | Default | Description |
 |-----|---------|-------------|
 | `prefix` | *(required)* | Project prefix for task IDs |
 | `tasks_dir` | `".tasks"` | Directory for task files |
+| `verbose_files` | `false` | Use verbose filenames (`PROJ-001 feat - title.md` vs `PROJ-001.md`) |
 
 ## Development 🧑‍💻
 

package/dist/cli.mjs

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 import { defineCommand, runMain } from 'citty';
 import consola from 'consola';
-import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync, unlinkSync, statSync } from 'node:fs';
-import { join, dirname } from 'node:path';
+import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync, unlinkSync, renameSync, statSync } from 'node:fs';
+import { join, basename, dirname } from 'node:path';
 import { stringify, parse as parse$1 } from 'smol-toml';
 import matter from 'gray-matter';
 import { fileURLToPath } from 'node:url';
@@ -20,7 +20,8 @@ function loadConfig(dir) {
   const parsed = parse$1(raw);
   return {
     prefix: parsed.prefix,
-    tasks_dir: parsed.tasks_dir ?? ".tasks"
+    tasks_dir: parsed.tasks_dir ?? ".tasks",
+    verbose_files: parsed.verbose_files ?? false
   };
 }
 function initConfig(dir, opts) {
@@ -29,7 +30,8 @@ function initConfig(dir, opts) {
   if (!existsSync(configPath)) {
     const config2 = {
       prefix: opts?.prefix ?? "TASK",
-      tasks_dir: opts?.tasks_dir ?? ".tasks"
+      tasks_dir: opts?.tasks_dir ?? ".tasks",
+      verbose_files: opts?.verbose_files ?? false
     };
     mkdirSync(configDir, { recursive: true });
     writeFileSync(configPath, stringify(config2));
@@ -78,6 +80,7 @@ function nextId(dir) {
 function render(task) {
   const frontmatter = {
     id: task.id,
+    title: task.title,
     type: task.type,
     status: task.status,
     created: task.created
@@ -97,8 +100,12 @@ function render(task) {
 }
 function parse(content, filename) {
   const { data, content: body } = matter(content);
-  const titleMatch = filename.replace(/\.md$/, "").match(/^\S+\s+\S+\s+-\s+(.+)$/);
-  const title = titleMatch ? titleMatch[1] : "";
+  const title = data.title;
+  if (!title) {
+    throw new Error(
+      "Task file missing title in frontmatter. Run 'mrkl migrate_prior_verbose' to fix."
+    );
+  }
   const acRegex = /^- \[[ x]\] (.+)$/gm;
   const acceptance_criteria = [];
   let match;
@@ -137,7 +144,7 @@ function createTask(opts) {
     description: opts.description ?? "",
     acceptance_criteria: opts.acceptance_criteria ?? []
   };
-  const filename = `${id} ${task.type} - ${task.title}.md`;
+  const filename = config.verbose_files ? `${id} ${task.type} - ${task.title}.md` : `${id}.md`;
   const tasksDir = join(opts.dir, config.tasks_dir);
   writeFileSync(join(tasksDir, filename), render(task));
   return task;
@@ -172,7 +179,7 @@ function archiveTask(dir, id) {
   }
   const filePath = join(tasksDir, file);
   const content = readFileSync(filePath, "utf-8");
-  const task = parse(content, file);
+  const task = parse(content);
   task.status = "done";
   const archivePath = join(tasksDir, ".archive", file);
   writeFileSync(archivePath, render(task));
@@ -236,7 +243,7 @@ function closeTask(dir, id) {
   }
   const filePath = join(tasksDir, file);
   const content = readFileSync(filePath, "utf-8");
-  const task = parse(content, file);
+  const task = parse(content);
   task.status = "closed";
   const archivePath = join(tasksDir, ".archive", file);
   writeFileSync(archivePath, render(task));
@@ -282,7 +289,7 @@ async function promptForTask(dir) {
       criteria.length === 0 ? "Acceptance criterion (Esc to skip)" : `Criterion #${criteria.length + 1} (Esc to finish)`,
       { type: "text" }
     );
-    if (typeof ac === "symbol") break;
+    if (typeof ac !== "string") break;
     if (ac.trim()) criteria.push(ac.trim());
   }
   return {
@@ -487,6 +494,90 @@ const closeCommand = defineCommand({
   }
 });
 
+const VERBOSE_REGEX = /^(\S+)\s+(\S+)\s+-\s+(.+)$/;
+function migrateDir(dirPath, verboseFiles) {
+  let migrated = 0;
+  let skipped = 0;
+  const warnings = [];
+  let files;
+  try {
+    files = readdirSync(dirPath).filter((f) => f.endsWith(".md") && !f.startsWith("."));
+  } catch {
+    return { migrated, skipped, warnings };
+  }
+  for (const file of files) {
+    const filePath = join(dirPath, file);
+    const raw = readFileSync(filePath, "utf-8");
+    const { data, content: body } = matter(raw);
+    if (data.title) {
+      skipped++;
+      continue;
+    }
+    const stem = basename(file, ".md");
+    const match = stem.match(VERBOSE_REGEX);
+    if (!match) {
+      warnings.push(`Could not extract title from filename: ${file}`);
+      skipped++;
+      continue;
+    }
+    const title = match[3];
+    const task = {
+      id: data.id,
+      type: data.type,
+      status: data.status,
+      created: data.created instanceof Date ? data.created.toISOString().slice(0, 10) : String(data.created),
+      title,
+      description: "",
+      acceptance_criteria: []
+    };
+    const descMatch = body.match(/## Description\n\n([\s\S]*?)(?:\n\n## Acceptance Criteria|$)/);
+    task.description = descMatch ? descMatch[1].trim() : "";
+    const acRegex = /^- \[[ x]\] (.+)$/gm;
+    let acMatch;
+    while ((acMatch = acRegex.exec(body)) !== null) {
+      task.acceptance_criteria.push(acMatch[1]);
+    }
+    writeFileSync(filePath, render(task));
+    if (!verboseFiles) {
+      const newName = `${data.id}.md`;
+      if (file !== newName) {
+        renameSync(filePath, join(dirPath, newName));
+      }
+    }
+    migrated++;
+  }
+  return { migrated, skipped, warnings };
+}
+const migrateCommand = defineCommand({
+  meta: {
+    name: "migrate",
+    description: "Migrate task files to include title in frontmatter"
+  },
+  run() {
+    const dir = process.cwd();
+    try {
+      const config = loadConfig(dir);
+      const tasksDir = join(dir, config.tasks_dir);
+      const archiveDir = join(tasksDir, ".archive");
+      const active = migrateDir(tasksDir, config.verbose_files);
+      const archived = migrateDir(archiveDir, config.verbose_files);
+      const totalMigrated = active.migrated + archived.migrated;
+      const totalSkipped = active.skipped + archived.skipped;
+      const allWarnings = [...active.warnings, ...archived.warnings];
+      consola.success(`Migrated ${totalMigrated} file(s), skipped ${totalSkipped} file(s).`);
+      for (const w of allWarnings) {
+        consola.warn(w);
+      }
+      if (totalMigrated > 0) {
+        consola.info("Breaking change: title is now stored in frontmatter. Old parsers may need updating.");
+      }
+    } catch (err) {
+      consola.error(String(err.message));
+      process.exit(1);
+    }
+  }
+});
+
 function findPackageRoot() {
   let dir = dirname(fileURLToPath(import.meta.url));
   while (dir !== dirname(dir)) {
@@ -563,6 +654,7 @@ const main = defineCommand({
     p: pruneCommand,
     close: closeCommand,
     x: closeCommand,
+    migrate_prior_verbose: migrateCommand,
     "install-skills": installSkillsCommand
   }
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xxkeefer/mrkl",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "type": "module",
   "description": "Lightweight CLI tool for structured markdown task tracking",
   "bin": {
@@ -34,13 +34,14 @@
   "devDependencies": {
     "@types/node": "^25.3.3",
     "changelogen": "^0.6.2",
+    "tsx": "^4.21.0",
     "typescript": "^5.7.0",
     "unbuild": "^3.3.1",
     "vitest": "^3.0.0"
   },
   "scripts": {
     "build": "unbuild",
-    "dev": "node --import tsx src/cli.ts",
+    "dev": "tsx src/cli.ts",
     "test": "vitest run",
     "changelog": "changelogen --output",
     "changelog:preview": "changelogen --no-output"