@metyatech/task-tracker 0.2.3 → 0.2.5

package/README.md

@@ -30,7 +30,9 @@ npm link
 
 Tasks are stored in `<git-repo-root>/.tasks.jsonl` (JSONL format, one JSON object per line). All commands must be run from within a git repository. The file is created automatically on first `add`.
 
-Each task: `{ id, description, stage, createdAt, updatedAt }`
+Each task: `{ id, description, stage, committedEventId?, createdAt, updatedAt }`
+
+`committedEventId` is a unique ID written when the task transitions to `committed`. It is used to locate the git commit that introduced the event into `.tasks.jsonl`, enabling accurate `pushed` detection even when `update --stage committed` is called before the actual commit.
 
 To sync tasks across PCs, commit `.tasks.jsonl` and push/pull like any other file.
 
@@ -56,9 +58,9 @@ task-tracker list --json
 ### Update a task
 
 ```bash
-task-tracker update <id> --stage implemented
+task-tracker update <id> --stage committed
 task-tracker update <id> --description "Updated description"
-task-tracker update <id> --stage verified --json
+task-tracker update <id> --stage released --json
 ```
 
 ### Mark done
@@ -89,9 +91,17 @@ The `check` command:
 
 ## Lifecycle Stages
 
-`pending` → `in-progress` → `implemented` → `verified` → `committed` → `pushed` → `pr-created` → `merged` → `released` → `published` → `done`
+Persisted stages: `pending` → `in-progress` → `committed` → `released` → `done`
+
+The `pushed` stage is **derived** and cannot be set manually. When a task is in `committed`
+stage, `list` and `check` display its effective stage as `pushed` automatically once the
+`.tasks.jsonl` commit that first introduced the task's `committedEventId` is reachable from
+the remote upstream branch (`git merge-base --is-ancestor`). This means derivation is
+accurate even when `update --stage committed` is called before the actual git commit.
+
+To filter by effective `pushed` stage: `task-tracker list --stage pushed`
 
-Stages can be set in any order.
+Setting `--stage pushed` on `add` or `update` is an error.
 
 ## Dev Commands
 

package/dist/cli.js

@@ -3,15 +3,16 @@
 // src/cli.ts
 import { Command } from "commander";
 import { fileURLToPath as fileURLToPath2 } from "url";
-import { dirname as dirname3, join as join4 } from "path";
+import { dirname as dirname3, join as join5 } from "path";
 import { readFileSync as readFileSync3 } from "fs";
 
 // src/storage.ts
 import { readFileSync, writeFileSync, existsSync, appendFileSync, mkdirSync } from "fs";
-import { dirname, join } from "path";
+import { dirname, join as join2 } from "path";
 
 // src/git.ts
 import { execSync } from "child_process";
+import { join, relative } from "path";
 function tryExec(cmd, cwd) {
   try {
     return execSync(cmd, { cwd, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }).trim();
@@ -55,11 +56,36 @@ function getRepoStatus(repoPath) {
   }
   return status;
 }
+function isCommitReachableFromUpstream(repoPath, commit) {
+  if (!/^[0-9a-f]{4,40}$/i.test(commit)) return false;
+  const result = tryExec(`git merge-base --is-ancestor ${commit} @{u}`, repoPath);
+  return result !== null;
+}
+function findCommitByEventId(repoPath, storageFile, eventId) {
+  if (!/^[A-Za-z0-9_-]{4,64}$/.test(eventId)) return null;
+  const relPath = relative(repoPath, storageFile).replace(/\\/g, "/");
+  const result = tryExec(`git log -S "${eventId}" --format=%H -- "${relPath}"`, repoPath);
+  if (!result) return null;
+  const hash = result.split("\n")[0].trim();
+  return hash || null;
+}
+function deriveEffectiveStage(task, repoPath) {
+  if (task.stage === "committed") {
+    if (task.committedEventId) {
+      const storageFile = join(repoPath, ".tasks.jsonl");
+      const commit = findCommitByEventId(repoPath, storageFile, task.committedEventId);
+      if (commit && isCommitReachableFromUpstream(repoPath, commit)) {
+        return "pushed";
+      }
+    }
+  }
+  return task.stage;
+}
 
 // src/storage.ts
 function getStoragePath() {
   const root = getRepoRoot();
-  return join(root, ".tasks.jsonl");
+  return join2(root, ".tasks.jsonl");
 }
 function ensureStorageDir(storagePath) {
   const dir = dirname(storagePath);
@@ -74,7 +100,15 @@ function readTasks(storagePath) {
   }
   const content = readFileSync(storagePath, "utf-8").trim();
   if (!content) return [];
-  return content.split("\n").filter((line) => line.trim()).map((line) => JSON.parse(line));
+  return content.split("\n").filter((line) => line.trim()).map((line) => {
+    try {
+      return JSON.parse(line);
+    } catch {
+      process.stderr.write(`[task-tracker] Warning: skipping malformed line in tasks file
+`);
+      return null;
+    }
+  }).filter((task) => task !== null);
 }
 function writeTasks(storagePath, tasks) {
   ensureStorageDir(storagePath);
@@ -90,19 +124,7 @@ function addTaskToStorage(storagePath, task) {
 import { nanoid } from "nanoid";
 
 // src/types.ts
-var STAGES = [
-  "pending",
-  "in-progress",
-  "implemented",
-  "verified",
-  "committed",
-  "pushed",
-  "pr-created",
-  "merged",
-  "released",
-  "published",
-  "done"
-];
+var STAGES = ["pending", "in-progress", "committed", "released", "done"];
 var DONE_STAGES = ["done"];
 
 // src/tasks.ts
@@ -135,6 +157,9 @@ function updateTask(storagePath, id, updates) {
   const task = tasks[idx];
   if (updates.stage !== void 0) task.stage = updates.stage;
   if (updates.description !== void 0) task.description = updates.description;
+  if (updates.stage === "committed" && !task.committedEventId) {
+    task.committedEventId = nanoid(16);
+  }
   task.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
   writeTasks(storagePath, tasks);
   return task;
@@ -176,32 +201,28 @@ import chalk from "chalk";
 var STAGE_COLORS = {
   pending: (s) => chalk.gray(s),
   "in-progress": (s) => chalk.blue(s),
-  implemented: (s) => chalk.cyan(s),
-  verified: (s) => chalk.yellow(s),
   committed: (s) => chalk.magenta(s),
   pushed: (s) => chalk.green(s),
-  "pr-created": (s) => chalk.greenBright(s),
-  merged: (s) => chalk.green(s),
   released: (s) => chalk.blueBright(s),
-  published: (s) => chalk.greenBright(s),
   done: (s) => chalk.dim(s)
 };
 function stageColor(stage) {
   const fn = STAGE_COLORS[stage] ?? ((s) => chalk.white(s));
   return fn(stage);
 }
-function formatTask(task) {
-  const stage = stageColor(task.stage);
+function formatTask(task, effectiveStage) {
+  const displayStage = effectiveStage ?? task.stage;
+  const stage = stageColor(displayStage);
   const id = chalk.bold(task.id);
   return `${id}  ${stage}  ${task.description}`;
 }
-function formatTaskTable(tasks) {
+function formatTaskTable(tasks, getEffectiveStage) {
   if (tasks.length === 0) {
     return chalk.dim("No tasks found.");
   }
-  return tasks.map(formatTask).join("\n");
+  return tasks.map((t) => formatTask(t, getEffectiveStage?.(t))).join("\n");
 }
-function formatCheckReport(activeTasks, repoStatus) {
+function formatCheckReport(activeTasks, repoStatus, getEffectiveStage) {
   const lines = [];
   lines.push(chalk.bold("=== Task Tracker Check ==="));
   lines.push("");
@@ -210,7 +231,7 @@ function formatCheckReport(activeTasks, repoStatus) {
     lines.push(chalk.dim("  No active tasks."));
   } else {
     for (const t of activeTasks) {
-      lines.push("  " + formatTask(t));
+      lines.push("  " + formatTask(t, getEffectiveStage?.(t)));
     }
   }
   lines.push("");
@@ -242,25 +263,25 @@ function formatCheckReport(activeTasks, repoStatus) {
 // src/gui.ts
 import { createServer } from "http";
 import { readFileSync as readFileSync2, existsSync as existsSync3 } from "fs";
-import { join as join3, dirname as dirname2, resolve } from "path";
+import { join as join4, dirname as dirname2, resolve } from "path";
 import { fileURLToPath } from "url";
 import { exec } from "child_process";
 
 // src/scanner.ts
 import { existsSync as existsSync2, readdirSync, statSync } from "fs";
-import { join as join2, basename } from "path";
+import { join as join3, basename } from "path";
 function scanTaskFiles(dir) {
-  const rootFile = join2(dir, ".tasks.jsonl");
+  const rootFile = join3(dir, ".tasks.jsonl");
   const root = existsSync2(rootFile) ? { path: rootFile, dir, name: basename(dir) } : null;
   const repos = [];
   try {
     const entries = readdirSync(dir);
     for (const entry of entries) {
       if (entry.startsWith(".")) continue;
-      const subDir = join2(dir, entry);
+      const subDir = join3(dir, entry);
       try {
         if (statSync(subDir).isDirectory()) {
-          const taskFile = join2(subDir, ".tasks.jsonl");
+          const taskFile = join3(subDir, ".tasks.jsonl");
           if (existsSync2(taskFile)) {
             repos.push({ path: taskFile, dir: subDir, name: entry });
           }
@@ -278,8 +299,8 @@ var __filename = fileURLToPath(import.meta.url);
 var __dirname = dirname2(__filename);
 function getHtmlPath() {
   const candidates = [
-    join3(__dirname, "public", "index.html"),
-    join3(__dirname, "..", "public", "index.html")
+    join4(__dirname, "public", "index.html"),
+    join4(__dirname, "..", "public", "index.html")
   ];
   for (const p of candidates) {
     if (existsSync3(p)) return p;
@@ -387,7 +408,7 @@ function startGui(dir, port = 3333) {
         if (pathname === "/api/tasks/purge" && method === "POST") {
           const body = await parseBody(req);
           const targetDir = typeof body.dir === "string" ? body.dir : resolvedDir;
-          const taskFile = join3(targetDir, ".tasks.jsonl");
+          const taskFile = join4(targetDir, ".tasks.jsonl");
           const result = purgeTasks(taskFile);
           sendJson(res, { count: result.count, ids: result.purged.map((t) => t.id) });
           return;
@@ -399,7 +420,7 @@ function startGui(dir, port = 3333) {
             return;
           }
           const targetDir = typeof body.dir === "string" ? body.dir : resolvedDir;
-          const taskFile = join3(targetDir, ".tasks.jsonl");
+          const taskFile = join4(targetDir, ".tasks.jsonl");
           const stage = typeof body.stage === "string" && STAGES.includes(body.stage) ? body.stage : void 0;
           const task = createTask(taskFile, body.description, { stage });
           sendJson(res, task, 201);
@@ -411,7 +432,7 @@ function startGui(dir, port = 3333) {
           if (method === "PUT") {
             const body = await parseBody(req);
             const targetDir = typeof body.dir === "string" ? body.dir : resolvedDir;
-            const taskFile = join3(targetDir, ".tasks.jsonl");
+            const taskFile = join4(targetDir, ".tasks.jsonl");
             const updates = {};
             if (typeof body.stage === "string" && STAGES.includes(body.stage)) {
               updates.stage = body.stage;
@@ -429,7 +450,7 @@ function startGui(dir, port = 3333) {
           }
           if (method === "DELETE") {
             const queryDir = url.searchParams.get("dir") ?? resolvedDir;
-            const taskFile = join3(queryDir, ".tasks.jsonl");
+            const taskFile = join4(queryDir, ".tasks.jsonl");
             const removed = removeTask(taskFile, id);
             if (!removed) {
               sendError(res, "Task not found", 404);
@@ -463,15 +484,34 @@ function startGui(dir, port = 3333) {
 import process2 from "process";
 var __filename2 = fileURLToPath2(import.meta.url);
 var __dirname2 = dirname3(__filename2);
+var HYPHENATED_TASK_ID_PATTERN = /^-[A-Za-z0-9_-]{7}$/;
+var TASK_ID_COMMAND_OPTIONS = {
+  update: {
+    "--stage": true,
+    "--description": true,
+    "--json": false
+  },
+  done: {
+    "--keep": true
+  },
+  remove: {}
+};
 var version = "0.0.0";
 try {
-  const pkg = JSON.parse(readFileSync3(join4(__dirname2, "..", "package.json"), "utf-8"));
+  const pkg = JSON.parse(readFileSync3(join5(__dirname2, "..", "package.json"), "utf-8"));
   version = pkg.version;
 } catch {
 }
 function isValidStage(s) {
   return STAGES.includes(s);
 }
+function isDerivedStage(s) {
+  return s === "pushed";
+}
+function derivedStageError(stage) {
+  return `\`${stage}\` is a derived stage and cannot be set manually.
+Set stage to \`committed\` instead; \`${stage}\` is derived automatically when the commit containing \`committedEventId\` is reachable from the upstream branch.`;
+}
 function getStorage() {
   try {
     return getStoragePath();
@@ -480,9 +520,46 @@ function getStorage() {
     process2.exit(1);
   }
 }
+function normalizeHyphenatedTaskIdArg(argv) {
+  const commandName = argv[2];
+  const optionSpec = TASK_ID_COMMAND_OPTIONS[commandName];
+  if (!optionSpec) {
+    return argv;
+  }
+  const args = argv.slice(3);
+  if (args.includes("--")) {
+    return argv;
+  }
+  for (let i = 0; i < args.length; i += 1) {
+    const token = args[i];
+    const consumesValue = optionSpec[token];
+    if (consumesValue !== void 0) {
+      if (consumesValue) {
+        i += 1;
+      }
+      continue;
+    }
+    if (!token.startsWith("-")) {
+      return argv;
+    }
+    if (!HYPHENATED_TASK_ID_PATTERN.test(token)) {
+      return argv;
+    }
+    return [...argv.slice(0, 3), ...args.slice(0, i), ...args.slice(i + 1), "--", token];
+  }
+  return argv;
+}
 var program = new Command();
 program.name("task-tracker").description("Persistent task lifecycle tracker for AI agent sessions").version(version, "-V, --version");
-program.command("add <description>").description("Add a new task").option("--stage <stage>", "Initial stage", "pending").option("--json", "Output created task as JSON").action((description, opts) => {
+program.command("add <description>").description("Add a new task").option(
+  "--stage <stage>",
+  `Initial stage (valid: ${STAGES.join(", ")}; \`pushed\` is derived, not settable)`,
+  "pending"
+).option("--json", "Output created task as JSON").action((description, opts) => {
+  if (isDerivedStage(opts.stage)) {
+    console.error(derivedStageError(opts.stage));
+    process2.exit(1);
+  }
   if (!isValidStage(opts.stage)) {
     console.error(`Invalid stage: ${opts.stage}
 Valid stages: ${STAGES.join(", ")}`);
@@ -495,30 +572,63 @@ Valid stages: ${STAGES.join(", ")}`);
     console.log("Created: " + formatTask(task));
   }
 });
-program.command("list").description("List tasks").option("--all", "Include completed/done tasks").option("--stage <stage>", "Filter by stage").option("--json", "JSON output").action((opts) => {
-  const stage = opts.stage && isValidStage(opts.stage) ? opts.stage : void 0;
-  if (opts.stage && !stage) {
+program.command("list").description("List tasks").option("--all", "Include completed/done tasks").option("--stage <stage>", `Filter by stage; use \`pushed\` to filter by derived effective stage`).option("--json", "JSON output").action((opts) => {
+  const storage = getStorage();
+  const repoRoot = dirname3(storage);
+  if (opts.stage === "pushed") {
+    const committed = listTasks(storage, { all: opts.all, stage: "committed" });
+    const tasks2 = committed.filter((t) => deriveEffectiveStage(t, repoRoot) === "pushed");
+    if (opts.json) {
+      console.log(
+        JSON.stringify(
+          tasks2.map((t) => ({ ...t, effectiveStage: "pushed" })),
+          null,
+          2
+        )
+      );
+    } else {
+      console.log(formatTaskTable(tasks2, () => "pushed"));
+    }
+    return;
+  }
+  if (opts.stage && !isValidStage(opts.stage)) {
     console.error(`Invalid stage: ${opts.stage}
 Valid stages: ${STAGES.join(", ")}`);
     process2.exit(1);
   }
-  const tasks = listTasks(getStorage(), { all: opts.all, stage });
+  const stage = opts.stage ? opts.stage : void 0;
+  const tasks = listTasks(storage, { all: opts.all, stage });
+  const getEffective = (t) => deriveEffectiveStage(t, repoRoot);
   if (opts.json) {
-    console.log(JSON.stringify(tasks, null, 2));
+    console.log(
+      JSON.stringify(
+        tasks.map((t) => ({ ...t, effectiveStage: getEffective(t) })),
+        null,
+        2
+      )
+    );
   } else {
-    console.log(formatTaskTable(tasks));
+    console.log(formatTaskTable(tasks, getEffective));
   }
 });
-program.command("update <id>").description("Update a task").option("--stage <stage>", "Set lifecycle stage").option("--description <text>", "Update description").option("--json", "JSON output").action((id, opts) => {
+program.command("update <id>").description("Update a task").option(
+  "--stage <stage>",
+  `Set lifecycle stage (valid: ${STAGES.join(", ")}; \`pushed\` is derived, not settable)`
+).option("--description <text>", "Update description").option("--json", "JSON output").action((id, opts) => {
+  if (opts.stage && isDerivedStage(opts.stage)) {
+    console.error(derivedStageError(opts.stage));
+    process2.exit(1);
+  }
   if (opts.stage && !isValidStage(opts.stage)) {
     console.error(`Invalid stage: ${opts.stage}
 Valid stages: ${STAGES.join(", ")}`);
     process2.exit(1);
   }
+  const storage = getStorage();
   const updates = {};
   if (opts.stage) updates.stage = opts.stage;
   if (opts.description) updates.description = opts.description;
-  const task = updateTask(getStorage(), id, updates);
+  const task = updateTask(storage, id, updates);
   if (!task) {
     console.error(`Task not found: ${id}`);
     process2.exit(1);
@@ -555,10 +665,20 @@ program.command("check").description("Show active tasks and git status for this
   const repoRoot = dirname3(storage);
   const activeTasks = listTasks(storage, { all: false });
   const repoStatus = getRepoStatus(repoRoot);
+  const getEffective = (t) => deriveEffectiveStage(t, repoRoot);
   if (opts.json) {
-    console.log(JSON.stringify({ activeTasks, repoStatus }, null, 2));
+    console.log(
+      JSON.stringify(
+        {
+          activeTasks: activeTasks.map((t) => ({ ...t, effectiveStage: getEffective(t) })),
+          repoStatus
+        },
+        null,
+        2
+      )
+    );
   } else {
-    console.log(formatCheckReport(activeTasks, repoStatus));
+    console.log(formatCheckReport(activeTasks, repoStatus, getEffective));
   }
 });
 program.command("purge").description("Remove all done tasks from storage").option("--dry-run", "Show what would be removed without removing").option("--keep <n>", "Keep N most recent done tasks, purge the rest").option("--json", "JSON output").action((opts) => {
@@ -586,4 +706,4 @@ program.command("gui [dir]").description("Start the web GUI (defaults to current
   const port = parseInt(opts.port, 10) || 3333;
   startGui(targetDir, port);
 });
-program.parse(process2.argv);
+program.parse(normalizeHyphenatedTaskIdArg(process2.argv));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metyatech/task-tracker",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Persistent task lifecycle tracker for AI agent sessions",
   "type": "module",
   "bin": {
@@ -53,7 +53,7 @@
     "vitest": "^4.0.0"
   },
   "overrides": {
-    "minimatch": "^10.2.2"
+    "minimatch": "10.2.4"
   },
   "lint-staged": {
     "src/**/*.ts": [