@xxkeefer/mrkl 0.3.0 → 0.3.1

package/README.md

@@ -1,6 +1,8 @@
 <p align="center">
   <h1 align="center">mrkl</h1>
   <p align="center">
+    📝 <i>mrkl, rhymes with sparkle</i> ✨
+    <br />
     Lightweight CLI for structured markdown task tracking.
     <br />
     Track work in your repo, not in a separate app.
@@ -15,17 +17,17 @@
 
 ---
 
-## Why mrkl?
+## Why mrkl? 🤔
 
 Most task trackers live outside your codebase. mrkl keeps tasks as markdown files right alongside your code — version-controlled, greppable, and readable by both humans and AI agents.
 
-- **No external service** — tasks live in `.tasks/` as structured markdown
-- **Git-native** — commit, branch, and diff your tasks like any other file
-- **AI-agent friendly** — consistent YAML frontmatter makes tasks easy to parse programmatically
-- **Conventional commits vocabulary** — task types mirror what you already use (`feat`, `fix`, `chore`, etc.)
-- **Zero config** — one command to set up, sensible defaults for everything
+- 🗂️ **No external service** — tasks live in `.tasks/` as structured markdown
+- 🌿 **Git-native** — commit, branch, and diff your tasks like any other file
+- 🤖 **AI-agent friendly** — consistent YAML frontmatter makes tasks easy to parse programmatically
+- 📏 **Conventional commits vocabulary** — task types mirror what you already use (`feat`, `fix`, `chore`, etc.)
+- ⚡ **Zero config** — one command to set up, sensible defaults for everything
 
-## Install
+## Install 📦
 
 ```sh
 pnpm add -g @xxkeefer/mrkl
@@ -37,7 +39,7 @@ Or use without installing:
 npx @xxkeefer/mrkl init MY_PROJECT
 ```
 
-## Quick Start
+## Quick Start 🚀
 
 ```sh
 # Initialize in your project root
@@ -60,9 +62,25 @@ mrkl list --status todo
 
 # Archive a completed task
 mrkl done PROJ-001
+
+# All commands have short aliases
+mrkl c feat "dark mode"   # create
+mrkl ls --type fix         # list
+mrkl d PROJ-001            # done
+mrkl x PROJ-002            # close
 ```
 
-## Commands
+## Commands 🛠️
+
+| Command | Alias | Description |
+|---------|-------|-------------|
+| `init` | `i` | Initialize mrkl in the current project |
+| `create` | `c` | Create a new task |
+| `list` | `ls` | List active tasks |
+| `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 |
+| `install-skills` | — | Install bundled Claude Code skills |
 
 ### `mrkl init <prefix>`
 
@@ -89,10 +107,10 @@ Creates a new task file.
 | `type` | Task type (see [Task Types](#task-types)) |
 | `title` | Short description of the task |
 
-| Option | Description |
-|--------|-------------|
-| `--desc <text>` | Detailed description |
-| `--ac <text>` | Acceptance criterion (repeatable) |
+| Option | Alias | Description |
+|--------|-------|-------------|
+| `--desc <text>` | `-d` | Detailed description |
+| `--ac <text>` | `-a` | Acceptance criterion (repeatable) |
 
 ```sh
 mrkl create feat "search functionality" \
@@ -102,14 +120,16 @@ mrkl create feat "search functionality" \
   --ac "highlights matching terms"
 ```
 
+Running `mrkl create` with no arguments enters **interactive mode**, prompting for type, title, description, and acceptance criteria.
+
 ### `mrkl list [options]`
 
 Lists all active tasks.
 
-| Option | Description |
-|--------|-------------|
-| `--type <type>` | Filter by task type |
-| `--status <status>` | Filter by status (`todo`, `in-progress`, `done`) |
+| Option | Alias | Description |
+|--------|-------|-------------|
+| `--type <type>` | `-t` | Filter by task type |
+| `--status <status>` | `-s` | Filter by status (`todo`, `in-progress`, `done`) |
 
 Non-conforming markdown files in the tasks directory are silently skipped.
 
@@ -123,6 +143,38 @@ Archives a completed task.
 
 Moves the task file to `.tasks/.archive/` and sets its status to `done`.
 
+### `mrkl close <id>`
+
+Closes a task that won't be done — duplicates, out-of-scope work, etc.
+
+| Argument | Description |
+|----------|-------------|
+| `id` | Task ID to close (e.g., `PROJ-002`) |
+
+Sets the task status to `closed` and moves it to `.tasks/.archive/`.
+
+### `mrkl prune <date> [options]`
+
+Permanently deletes archived tasks created on or before a cutoff date.
+
+| Argument | Description |
+|----------|-------------|
+| `date` | Cutoff date (`YYYY-MM-DD` or `YYYYMMDD`) |
+
+| Option | Alias | Description |
+|--------|-------|-------------|
+| `--force` | `-f` | Skip confirmation prompt |
+
+Shows a confirmation prompt listing tasks to be deleted unless `--force` is used.
+
+```sh
+# Delete archived tasks from January or earlier
+mrkl prune 2026-01-31
+
+# Skip confirmation
+mrkl prune 2026-01-31 --force
+```
+
 ### `mrkl install-skills`
 
 Installs bundled Claude Code skills into the current project.
@@ -131,7 +183,7 @@ Copies skill directories from the mrkl package into `.claude/skills/` so they ar
 
 ```sh
 mrkl install-skills
-# ✔ Installed plan-from-task
+# 🧩 Installed plan-from-task
 ```
 
 Currently ships with:
@@ -140,7 +192,7 @@ Currently ships with:
 |-------|-------------|
 | `plan-from-task` | Generate and execute implementation plans from mrkl task files |
 
-## Task Types
+## Task Types 🏷️
 
 mrkl uses [conventional commit](https://www.conventionalcommits.org/) types:
 
@@ -157,7 +209,7 @@ mrkl uses [conventional commit](https://www.conventionalcommits.org/) types:
 | `build` | Build system changes |
 | `style` | Code style/formatting |
 
-## Task File Format
+## Task File Format 📄
 
 Each task is a markdown file with YAML frontmatter:
 
@@ -185,7 +237,7 @@ Implement user authentication with OAuth2.
 
 The format is intentionally simple — edit task files directly when you need to update descriptions, change status, or check off criteria.
 
-## Project Structure
+## Project Structure 🗂️
 
 After initialization, mrkl adds the following to your project:
 
@@ -203,7 +255,7 @@ your-project/
 
 Commit `.config/mrkl/` and `.tasks/` to version control. They're designed to be tracked alongside your code.
 
-## Team Workflow
+## Team Workflow 👥
 
 When using mrkl with **git worktrees** or **protected branches**, task IDs can conflict if multiple branches create tasks concurrently. The fix is a simple convention: **separate planning from execution.**
 
@@ -227,7 +279,7 @@ mrkl done MRKL-019
 
 The counter only increments on planning branches — one at a time — so IDs never conflict. See **[docs/workflow.md](docs/workflow.md)** for the full guide with examples and edge cases.
 
-## Configuration
+## Configuration ⚙️
 
 Configuration lives in `.config/mrkl/mrkl.toml` (or `mrkl.toml` at the project root):
 
@@ -241,7 +293,7 @@ tasks_dir = ".tasks"
 | `prefix` | *(required)* | Project prefix for task IDs |
 | `tasks_dir` | `".tasks"` | Directory for task files |
 
-## Development
+## Development 🧑‍💻
 
 ```sh
 git clone https://github.com/xxKeefer/mrkl.git
@@ -258,10 +310,10 @@ pnpm tsx src/cli.ts list
 pnpm build
 ```
 
-## Contributing
+## Contributing 🤝
 
 Contributions are welcome! See **[CONTRIBUTING.md](CONTRIBUTING.md)** for branch protection rules, merge strategy, and development setup.
 
-## License
+## License 📜
 
 [MIT](LICENSE)

package/dist/cli.mjs

@@ -58,7 +58,7 @@ const initCommand = defineCommand({
     const dir = process.cwd();
     try {
       initConfig(dir, { prefix: args.prefix });
-      consola.success("mrkl initialized");
+      consola.success("\u{1F389} mrkl initialized");
     } catch (err) {
       consola.error(String(err.message));
       process.exit(1);
@@ -145,9 +145,7 @@ function createTask(opts) {
 function listTasks(filter) {
   const config = loadConfig(filter.dir);
   const tasksDir = join(filter.dir, config.tasks_dir);
-  const files = readdirSync(tasksDir).filter(
-    (f) => f.endsWith(".md") && !f.startsWith(".")
-  );
+  const files = readdirSync(tasksDir).filter((f) => f.endsWith(".md") && !f.startsWith("."));
   let tasks = files.flatMap((f) => {
     try {
       const content = readFileSync(join(tasksDir, f), "utf-8");
@@ -180,6 +178,70 @@ function archiveTask(dir, id) {
   writeFileSync(archivePath, render(task));
   unlinkSync(filePath);
 }
+function parseCutoffDate(input) {
+  const normalized = input.replace(/^(\d{4})(\d{2})(\d{2})$/, "$1-$2-$3");
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(normalized)) {
+    throw new Error(`Invalid date format: "${input}". Expected YYYY-MM-DD or YYYYMMDD.`);
+  }
+  const [y, m, d] = normalized.split("-").map(Number);
+  const date = new Date(y, m - 1, d);
+  if (date.getFullYear() !== y || date.getMonth() !== m - 1 || date.getDate() !== d) {
+    throw new Error(`Invalid date: "${input}" is not a real calendar date.`);
+  }
+  return normalized;
+}
+function normalizeCreatedDate(created) {
+  if (created instanceof Date) {
+    return created.toISOString().slice(0, 10);
+  }
+  return String(created);
+}
+function pruneTasks(dir, cutoff) {
+  const config = loadConfig(dir);
+  const archiveDir = join(dir, config.tasks_dir, ".archive");
+  if (!existsSync(archiveDir)) {
+    return { deleted: [], total: 0 };
+  }
+  const files = readdirSync(archiveDir).filter((f) => f.endsWith(".md") && !f.startsWith("."));
+  const deleted = [];
+  for (const f of files) {
+    try {
+      const content = readFileSync(join(archiveDir, f), "utf-8");
+      const task = parse(content, f);
+      const created = normalizeCreatedDate(task.created);
+      if (created <= cutoff) {
+        deleted.push({ id: task.id, title: task.title, created, filename: f });
+      }
+    } catch {
+    }
+  }
+  return { deleted, total: files.length };
+}
+function executePrune(dir, filenames) {
+  const config = loadConfig(dir);
+  const archiveDir = join(dir, config.tasks_dir, ".archive");
+  for (const f of filenames) {
+    unlinkSync(join(archiveDir, f));
+  }
+}
+function closeTask(dir, id) {
+  const config = loadConfig(dir);
+  const tasksDir = join(dir, config.tasks_dir);
+  const idUpper = id.toUpperCase();
+  const file = readdirSync(tasksDir).find(
+    (f) => f.endsWith(".md") && f.toUpperCase().startsWith(idUpper)
+  );
+  if (!file) {
+    throw new Error(`Task ${id} not found`);
+  }
+  const filePath = join(tasksDir, file);
+  const content = readFileSync(filePath, "utf-8");
+  const task = parse(content, file);
+  task.status = "closed";
+  const archivePath = join(tasksDir, ".archive", file);
+  writeFileSync(archivePath, render(task));
+  unlinkSync(filePath);
+}
 
 const TASK_TYPES = [
   "feat",
@@ -206,7 +268,7 @@ async function promptForTask(dir) {
   });
   if (typeof title === "symbol") process.exit(0);
   if (!title.trim()) {
-    consola.error("Title cannot be empty");
+    consola.error("\u274C Title cannot be empty");
     process.exit(1);
   }
   const desc = await consola.prompt("Description (optional, enter to skip)", {
@@ -262,7 +324,7 @@ const createCommand = defineCommand({
     const dir = process.cwd();
     const interactive = !args.type && !args.title;
     if (!interactive && (!args.type || !args.title)) {
-      consola.error("Both type and title are required, or omit both for interactive mode");
+      consola.error("\u274C Both type and title are required, or omit both for interactive mode");
       process.exit(1);
     }
     try {
@@ -270,7 +332,7 @@ const createCommand = defineCommand({
         dir,
         type: (() => {
           if (!TASK_TYPES.includes(args.type)) {
-            consola.error(`Invalid type "${args.type}". Must be one of: ${TASK_TYPES.join(", ")}`);
+            consola.error(`\u274C Invalid type "${args.type}". Must be one of: ${TASK_TYPES.join(", ")}`);
             process.exit(1);
           }
           return args.type;
@@ -280,7 +342,7 @@ const createCommand = defineCommand({
         acceptance_criteria: args.ac ? Array.isArray(args.ac) ? args.ac : [args.ac] : void 0
       };
       const task = createTask(opts);
-      consola.success(`Created ${task.id}: ${task.title}`);
+      consola.success(`\u{1F4DD} Created ${task.id}: ${task.title}`);
     } catch (err) {
       consola.error(String(err.message));
       process.exit(1);
@@ -314,7 +376,7 @@ const listCommand = defineCommand({
         status: args.status
       });
       if (tasks.length === 0) {
-        consola.info("No tasks found");
+        consola.info("\u{1F4ED} No tasks found");
         return;
       }
       for (const task of tasks) {
@@ -343,7 +405,81 @@ const doneCommand = defineCommand({
     const dir = process.cwd();
     try {
       archiveTask(dir, args.id);
-      consola.success(`Archived ${args.id}`);
+      consola.success(`\u2705 Archived ${args.id}`);
+    } catch (err) {
+      consola.error(String(err.message));
+      process.exit(1);
+    }
+  }
+});
+
+const pruneCommand = defineCommand({
+  meta: {
+    name: "prune",
+    description: "Delete archived tasks created on or before a given date"
+  },
+  args: {
+    date: {
+      type: "positional",
+      description: "Cutoff date (YYYY-MM-DD or YYYYMMDD)",
+      required: true
+    },
+    force: {
+      type: "boolean",
+      alias: "f",
+      description: "Skip confirmation prompt",
+      default: false
+    }
+  },
+  async run({ args }) {
+    const dir = process.cwd();
+    let cutoff;
+    try {
+      cutoff = parseCutoffDate(args.date);
+    } catch (err) {
+      consola.error(String(err.message));
+      process.exit(1);
+    }
+    const result = pruneTasks(dir, cutoff);
+    if (result.deleted.length === 0) {
+      consola.info(`\u{1F4ED} No archived tasks found on or before ${cutoff}`);
+      return;
+    }
+    consola.info(`\u{1F50D} Found ${result.deleted.length} task(s) to prune:`);
+    for (const task of result.deleted) {
+      consola.log(`  ${task.id} \u2014 ${task.title} (${task.created})`);
+    }
+    if (!args.force) {
+      const confirm = await consola.prompt("Delete these tasks?", {
+        type: "confirm"
+      });
+      if (typeof confirm === "symbol" || !confirm) {
+        consola.info("\u{1F44B} Aborted");
+        return;
+      }
+    }
+    executePrune(dir, result.deleted.map((t) => t.filename));
+    consola.success(`\u{1F9F9} Pruned ${result.deleted.length} archived task(s)`);
+  }
+});
+
+const closeCommand = defineCommand({
+  meta: {
+    name: "close",
+    description: "Close a task (won't do, duplicate, etc.) and archive it"
+  },
+  args: {
+    id: {
+      type: "positional",
+      description: "Task ID to close (e.g., VON-001)",
+      required: true
+    }
+  },
+  run({ args }) {
+    const dir = process.cwd();
+    try {
+      closeTask(dir, args.id);
+      consola.success(`\u{1F6AB} Closed ${args.id}`);
     } catch (err) {
       consola.error(String(err.message));
       process.exit(1);
@@ -385,21 +521,21 @@ const installSkillsCommand = defineCommand({
       const packageRoot = findPackageRoot();
       const skillsDir = join(packageRoot, "skills");
       if (!existsSync(skillsDir)) {
-        consola.error("No skills directory found in mrkl package");
+        consola.error("\u274C No skills directory found in mrkl package");
         process.exit(1);
       }
       const skills = readdirSync(skillsDir).filter(
         (f) => statSync(join(skillsDir, f)).isDirectory()
       );
       if (skills.length === 0) {
-        consola.info("No skills to install");
+        consola.info("\u{1F4ED} No skills to install");
         return;
       }
       for (const skill of skills) {
         const src = join(skillsDir, skill);
         const target = join(dest, skill);
         copyDirSync(src, target);
-        consola.success(`Installed ${skill}`);
+        consola.success(`\u{1F9E9} Installed ${skill}`);
       }
     } catch (err) {
       consola.error(String(err.message));
@@ -423,6 +559,10 @@ const main = defineCommand({
     ls: listCommand,
     done: doneCommand,
     d: doneCommand,
+    prune: pruneCommand,
+    p: pruneCommand,
+    close: closeCommand,
+    x: closeCommand,
     "install-skills": installSkillsCommand
   }
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xxkeefer/mrkl",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "type": "module",
   "description": "Lightweight CLI tool for structured markdown task tracking",
   "bin": {