@xxkeefer/mrkl 0.1.0 → 0.2.6

package/README.md

@@ -0,0 +1,250 @@
+<p align="center">
+  <h1 align="center">mrkl</h1>
+  <p align="center">
+    Lightweight CLI for structured markdown task tracking.
+    <br />
+    Track work in your repo, not in a separate app.
+  </p>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@xxkeefer/mrkl"><img src="https://img.shields.io/npm/v/@xxkeefer/mrkl" alt="npm version" /></a>
+  <a href="https://github.com/xxKeefer/mrkl/blob/main/LICENSE"><img src="https://img.shields.io/github/license/xxKeefer/mrkl" alt="license" /></a>
+  <a href="https://github.com/xxKeefer/mrkl"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs welcome" /></a>
+</p>
+
+---
+
+## 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
+
+## Install
+
+```sh
+pnpm add -g @xxkeefer/mrkl
+```
+
+Or use without installing:
+
+```sh
+npx @xxkeefer/mrkl init MY_PROJECT
+```
+
+## Quick Start
+
+```sh
+# Initialize in your project root
+mrkl init PROJ
+
+# Create tasks
+mrkl create feat "user authentication"
+mrkl create fix "login redirect loop" --desc "Users get stuck after OAuth callback"
+mrkl create feat "dark mode" --ac "toggle in settings" --ac "persists across sessions"
+
+# View active tasks
+mrkl list
+# PROJ-001  feat  todo  user authentication
+# PROJ-002  fix   todo  login redirect loop
+# PROJ-003  feat  todo  dark mode
+
+# Filter by type or status
+mrkl list --type fix
+mrkl list --status todo
+
+# Archive a completed task
+mrkl done PROJ-001
+```
+
+## Commands
+
+### `mrkl init <prefix>`
+
+Initializes mrkl in the current directory.
+
+| Argument | Description |
+|----------|-------------|
+| `prefix` | Project prefix for task IDs (e.g., `PROJ`, `API`, `WEB`) |
+
+Creates:
+- `.config/mrkl/mrkl.toml` — project configuration
+- `.config/mrkl/mrkl_counter` — auto-incrementing ID tracker
+- `.tasks/` — active task directory
+- `.tasks/.archive/` — completed task storage
+
+Safe to run multiple times — existing config and counter are preserved.
+
+### `mrkl create <type> <title> [options]`
+
+Creates a new task file.
+
+| Argument | Description |
+|----------|-------------|
+| `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) |
+
+```sh
+mrkl create feat "search functionality" \
+  --desc "Full-text search across all documents" \
+  --ac "search bar in header" \
+  --ac "results update as you type" \
+  --ac "highlights matching terms"
+```
+
+### `mrkl list [options]`
+
+Lists all active tasks.
+
+| Option | Description |
+|--------|-------------|
+| `--type <type>` | Filter by task type |
+| `--status <status>` | Filter by status (`todo`, `in-progress`, `done`) |
+
+Non-conforming markdown files in the tasks directory are silently skipped.
+
+### `mrkl done <id>`
+
+Archives a completed task.
+
+| Argument | Description |
+|----------|-------------|
+| `id` | Task ID to archive (e.g., `PROJ-001`) |
+
+Moves the task file to `.tasks/.archive/` and sets its status to `done`.
+
+## Task Types
+
+mrkl uses [conventional commit](https://www.conventionalcommits.org/) types:
+
+| Type | Purpose |
+|------|---------|
+| `feat` | New feature |
+| `fix` | Bug fix |
+| `chore` | Maintenance |
+| `docs` | Documentation |
+| `perf` | Performance improvement |
+| `refactor` | Code restructuring |
+| `test` | Testing |
+| `ci` | CI/CD changes |
+| `build` | Build system changes |
+| `style` | Code style/formatting |
+
+## Task File Format
+
+Each task is a markdown file with YAML frontmatter:
+
+```
+.tasks/PROJ-001 feat - user authentication.md
+```
+
+```markdown
+---
+id: PROJ-001
+type: feat
+status: todo
+created: '2026-03-01'
+---
+## Description
+
+Implement user authentication with OAuth2.
+
+## Acceptance Criteria
+
+- [ ] login page renders
+- [ ] OAuth flow completes
+- [ ] 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.
+
+## Project Structure
+
+After initialization, mrkl adds the following to your project:
+
+```
+your-project/
+  .config/mrkl/
+    mrkl.toml           # project configuration
+    mrkl_counter        # current task number
+  .tasks/
+    PROJ-001 feat - first task.md
+    PROJ-002 fix - second task.md
+    .archive/
+      PROJ-000 chore - archived task.md
+```
+
+Commit `.config/mrkl/` and `.tasks/` to version control. They're designed to be tracked alongside your code.
+
+## 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.**
+
+1. **Plan** — Create tasks on a `planning/` branch, merge to main via PR
+2. **Execute** — Branch feature work from main (which has all tasks)
+3. **Ad-hoc** — Mid-sprint tasks follow the same pattern at smaller scale
+
+```sh
+# Sprint planning
+git checkout -b planning/sprint-3 main
+mrkl create feat "user authentication"
+mrkl create fix "login redirect loop"
+# commit, PR, merge to main
+
+# Feature work (branch from main after planning merges)
+git checkout -b feature/MRKL-019_user-auth main
+# ... do the work ...
+mrkl done MRKL-019
+# commit, PR, merge to main
+```
+
+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 lives in `.config/mrkl/mrkl.toml` (or `mrkl.toml` at the project root):
+
+```toml
+prefix = "PROJ"
+tasks_dir = ".tasks"
+```
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `prefix` | *(required)* | Project prefix for task IDs |
+| `tasks_dir` | `".tasks"` | Directory for task files |
+
+## Development
+
+```sh
+git clone https://github.com/xxKeefer/mrkl.git
+cd mrkl
+pnpm install
+
+# Run tests
+pnpm test
+
+# Run CLI in development
+pnpm tsx src/cli.ts list
+
+# Build
+pnpm build
+```
+
+## Contributing
+
+Contributions are welcome! See **[CONTRIBUTING.md](CONTRIBUTING.md)** for branch protection rules, merge strategy, and development setup.
+
+## License
+
+[MIT](LICENSE)

package/dist/cli.mjs

@@ -1,9 +1,45 @@
 #!/usr/bin/env node
 import { defineCommand, runMain } from 'citty';
 import consola from 'consola';
+import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { stringify, parse as parse$1 } from 'smol-toml';
+import matter from 'gray-matter';
 
-function initConfig(_dir, _opts) {
-  throw new Error("not implemented");
+const CONFIG_PATHS = [
+  join(".config", "mrkl", "mrkl.toml"),
+  "mrkl.toml"
+];
+function loadConfig(dir) {
+  const configPath = CONFIG_PATHS.map((p) => join(dir, p)).find((p) => existsSync(p));
+  if (!configPath) {
+    throw new Error(`mrkl.toml not found in ${dir}`);
+  }
+  const raw = readFileSync(configPath, "utf-8");
+  const parsed = parse$1(raw);
+  return {
+    prefix: parsed.prefix,
+    tasks_dir: parsed.tasks_dir ?? ".tasks"
+  };
+}
+function initConfig(dir, opts) {
+  const configDir = join(dir, ".config", "mrkl");
+  const configPath = join(configDir, "mrkl.toml");
+  if (!existsSync(configPath)) {
+    const config2 = {
+      prefix: opts?.prefix ?? "TASK",
+      tasks_dir: opts?.tasks_dir ?? ".tasks"
+    };
+    mkdirSync(configDir, { recursive: true });
+    writeFileSync(configPath, stringify(config2));
+  }
+  const config = loadConfig(dir);
+  const tasksDir = join(dir, config.tasks_dir);
+  mkdirSync(join(tasksDir, ".archive"), { recursive: true });
+  const counterPath = join(dir, ".config", "mrkl", "mrkl_counter");
+  if (!existsSync(counterPath)) {
+    writeFileSync(counterPath, "0");
+  }
 }
 
 const initCommand = defineCommand({
@@ -19,21 +55,143 @@ const initCommand = defineCommand({
   },
   run({ args }) {
     const dir = process.cwd();
-    initConfig(dir, { prefix: args.prefix });
-    consola.success("mrkl initialized");
+    try {
+      initConfig(dir, { prefix: args.prefix });
+      consola.success("mrkl initialized");
+    } catch (err) {
+      consola.error(String(err.message));
+      process.exit(1);
+    }
   }
 });
 
-function createTask(_opts) {
-  throw new Error("not implemented");
+const COUNTER_FILE = join(".config", "mrkl", "mrkl_counter");
+function nextId(dir) {
+  const filePath = join(dir, COUNTER_FILE);
+  const current = existsSync(filePath) ? parseInt(readFileSync(filePath, "utf-8").trim(), 10) : 0;
+  const next = current + 1;
+  writeFileSync(filePath, String(next));
+  return next;
 }
-function listTasks(_filter) {
-  throw new Error("not implemented");
+
+function render(task) {
+  const frontmatter = {
+    id: task.id,
+    type: task.type,
+    status: task.status,
+    created: task.created
+  };
+  const sections = [];
+  sections.push("## Description");
+  sections.push("");
+  sections.push(task.description || "");
+  sections.push("");
+  sections.push("## Acceptance Criteria");
+  sections.push("");
+  for (const item of task.acceptance_criteria) {
+    sections.push(`- [ ] ${item}`);
+  }
+  const body = sections.join("\n") + "\n";
+  return matter.stringify(body, frontmatter);
 }
-function archiveTask(_dir, _id) {
-  throw new Error("not implemented");
+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 acRegex = /^- \[[ x]\] (.+)$/gm;
+  const acceptance_criteria = [];
+  let match;
+  while ((match = acRegex.exec(body)) !== null) {
+    acceptance_criteria.push(match[1]);
+  }
+  const descMatch = body.match(/## Description\n\n([\s\S]*?)(?:\n\n## Acceptance Criteria|$)/);
+  const description = descMatch ? descMatch[1].trim() : "";
+  return {
+    id: data.id,
+    type: data.type,
+    status: data.status,
+    created: data.created,
+    title,
+    description,
+    acceptance_criteria
+  };
 }
 
+function normalizeTitle(raw) {
+  const result = raw.trim().toLowerCase().replace(/[/\\]/g, "-").replace(/[<>:"|?*\x00-\x1f]/g, "").replace(/-{2,}/g, "-").replace(/ {2,}/g, " ").replace(/^-+|-+$/g, "");
+  if (!result) throw new Error("Title is empty after normalisation");
+  return result;
+}
+function createTask(opts) {
+  const config = loadConfig(opts.dir);
+  const num = nextId(opts.dir);
+  const id = `${config.prefix}-${String(num).padStart(3, "0")}`;
+  const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+  const task = {
+    id,
+    type: opts.type,
+    status: "todo",
+    created: today,
+    title: normalizeTitle(opts.title),
+    description: opts.description ?? "",
+    acceptance_criteria: opts.acceptance_criteria ?? []
+  };
+  const filename = `${id} ${task.type} - ${task.title}.md`;
+  const tasksDir = join(opts.dir, config.tasks_dir);
+  writeFileSync(join(tasksDir, filename), render(task));
+  return task;
+}
+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(".")
+  );
+  let tasks = files.flatMap((f) => {
+    try {
+      const content = readFileSync(join(tasksDir, f), "utf-8");
+      const task = parse(content, f);
+      if (!task.id || !task.type || !task.status) return [];
+      return [task];
+    } catch {
+      return [];
+    }
+  });
+  if (filter.type) tasks = tasks.filter((t) => t.type === filter.type);
+  if (filter.status) tasks = tasks.filter((t) => t.status === filter.status);
+  return tasks;
+}
+function archiveTask(dir, id) {
+  const config = loadConfig(dir);
+  const tasksDir = join(dir, config.tasks_dir);
+  const file = readdirSync(tasksDir).find(
+    (f) => f.endsWith(".md") && f.startsWith(id)
+  );
+  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 = "done";
+  const archivePath = join(tasksDir, ".archive", file);
+  writeFileSync(archivePath, render(task));
+  unlinkSync(filePath);
+}
+
+const TASK_TYPES = [
+  "feat",
+  "fix",
+  "chore",
+  "docs",
+  "perf",
+  "refactor",
+  "test",
+  "ci",
+  "build",
+  "style"
+];
+
 const createCommand = defineCommand({
   meta: {
     name: "create",
@@ -60,14 +218,24 @@ const createCommand = defineCommand({
     }
   },
   run({ args }) {
-    process.cwd();
-    const task = createTask({
-      type: args.type,
-      title: args.title,
-      description: args.desc,
-      acceptance_criteria: args.ac ? [args.ac] : void 0
-    });
-    consola.success(`Created ${task.id}: ${task.title}`);
+    if (!TASK_TYPES.includes(args.type)) {
+      consola.error(`Invalid type "${args.type}". Must be one of: ${TASK_TYPES.join(", ")}`);
+      process.exit(1);
+    }
+    const dir = process.cwd();
+    try {
+      const task = createTask({
+        dir,
+        type: args.type,
+        title: args.title,
+        description: args.desc,
+        acceptance_criteria: args.ac ? Array.isArray(args.ac) ? args.ac : [args.ac] : void 0
+      });
+      consola.success(`Created ${task.id}: ${task.title}`);
+    } catch (err) {
+      consola.error(String(err.message));
+      process.exit(1);
+    }
   }
 });
 
@@ -87,17 +255,23 @@ const listCommand = defineCommand({
     }
   },
   run({ args }) {
-    process.cwd();
-    const tasks = listTasks({
-      type: args.type,
-      status: args.status
-    });
-    if (tasks.length === 0) {
-      consola.info("No tasks found");
-      return;
-    }
-    for (const task of tasks) {
-      consola.log(`${task.id}  ${task.type.padEnd(10)} ${task.status.padEnd(12)} ${task.title}`);
+    const dir = process.cwd();
+    try {
+      const tasks = listTasks({
+        dir,
+        type: args.type,
+        status: args.status
+      });
+      if (tasks.length === 0) {
+        consola.info("No tasks found");
+        return;
+      }
+      for (const task of tasks) {
+        consola.log(`${task.id}  ${task.type.padEnd(10)} ${task.status.padEnd(12)} ${task.title}`);
+      }
+    } catch (err) {
+      consola.error(String(err.message));
+      process.exit(1);
     }
   }
 });
@@ -116,8 +290,13 @@ const doneCommand = defineCommand({
   },
   run({ args }) {
     const dir = process.cwd();
-    archiveTask(dir, args.id);
-    consola.success(`Archived ${args.id}`);
+    try {
+      archiveTask(dir, args.id);
+      consola.success(`Archived ${args.id}`);
+    } catch (err) {
+      consola.error(String(err.message));
+      process.exit(1);
+    }
   }
 });
 
@@ -130,8 +309,11 @@ const main = defineCommand({
   subCommands: {
     init: initCommand,
     create: createCommand,
+    c: createCommand,
     list: listCommand,
     done: doneCommand
   }
 });
 runMain(main);
+
+export { main };

package/package.json

@@ -1,16 +1,11 @@
 {
   "name": "@xxkeefer/mrkl",
-  "version": "0.1.0",
+  "version": "0.2.6",
   "type": "module",
   "description": "Lightweight CLI tool for structured markdown task tracking",
   "bin": {
     "mrkl": "./dist/cli.mjs"
   },
-  "scripts": {
-    "build": "unbuild",
-    "dev": "node --import tsx src/cli.ts",
-    "test": "vitest run"
-  },
   "keywords": [
     "cli",
     "task",
@@ -18,7 +13,9 @@
     "markdown"
   ],
   "license": "MIT",
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/xxKeefer/mrkl.git"
@@ -35,8 +32,17 @@
   },
   "devDependencies": {
     "@types/node": "^25.3.3",
+    "changelogen": "^0.6.2",
     "typescript": "^5.7.0",
     "unbuild": "^3.3.1",
     "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "build": "unbuild",
+    "dev": "node --import tsx src/cli.ts",
+    "test": "vitest run",
+    "release": "./scripts/release.sh",
+    "changelog": "changelogen",
+    "changelog:preview": "changelogen --no-output"
   }
-}
+}