@metyatech/task-tracker 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 metyatech
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,109 @@
+# task-tracker
+
+Persistent task lifecycle tracker for AI agent sessions. Stores tasks in `.tasks.jsonl` at the root of your git repository — making task state version-controllable and syncable across PCs via git.
+
+## Overview
+
+When using AI agents (Claude, Codex, Gemini, Copilot), tasks from conversations get forgotten across sessions. Agents are forcefully terminated and cannot persist state on exit. `task-tracker` lets agents record tasks to disk immediately when they arise, and check for stale work at session start.
+
+Tasks are stored per-repository in `.tasks.jsonl` alongside your code. Commit the file to track task state in version control; add it to `.gitignore` to keep it local.
+
+## Compatibility
+
+- Node.js 18+
+- macOS, Linux, Windows
+- Requires git (tasks are scoped to the current git repository)
+
+## Install
+
+```bash
+npm install -g @metyatech/task-tracker
+```
+
+Or link locally for development:
+
+```bash
+npm link
+```
+
+## Storage
+
+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 }`
+
+To sync tasks across PCs, commit `.tasks.jsonl` and push/pull like any other file.
+
+## Usage
+
+### Add a task
+
+```bash
+task-tracker add "Implement feature X"
+task-tracker add "Deploy to staging" --stage in-progress
+task-tracker add "Review PR #42" --json
+```
+
+### List tasks
+
+```bash
+task-tracker list              # active tasks only
+task-tracker list --all        # include done tasks
+task-tracker list --stage in-progress
+task-tracker list --json
+```
+
+### Update a task
+
+```bash
+task-tracker update <id> --stage implemented
+task-tracker update <id> --description "Updated description"
+task-tracker update <id> --stage verified --json
+```
+
+### Mark done
+
+```bash
+task-tracker done <id>
+```
+
+### Remove a task
+
+```bash
+task-tracker remove <id>
+```
+
+### Check for stale work
+
+```bash
+task-tracker check
+task-tracker check --json
+```
+
+The `check` command:
+
+1. Lists all active (non-done) tasks from this repo's `.tasks.jsonl`
+2. Runs `git status --porcelain` on the repo root
+3. Runs `git log @{u}..HEAD --oneline` to show unpushed commits
+4. Outputs a combined report
+
+## Lifecycle Stages
+
+`pending` → `in-progress` → `implemented` → `verified` → `committed` → `pushed` → `pr-created` → `merged` → `released` → `published` → `done`
+
+Stages can be set in any order.
+
+## Dev Commands
+
+```bash
+npm run build        # Build with tsup
+npm run test         # Run tests with vitest
+npm run lint         # ESLint
+npm run format       # Prettier (write)
+npm run format:check # Prettier (check)
+npm run verify       # format:check + lint + build + test
+```
+
+## License
+
+MIT © metyatech

package/dist/cli.js

@@ -0,0 +1,315 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { Command } from "commander";
+import { fileURLToPath } from "url";
+import { dirname as dirname2, join as join2 } from "path";
+import { readFileSync as readFileSync2 } from "fs";
+
+// src/storage.ts
+import { readFileSync, writeFileSync, existsSync, appendFileSync, mkdirSync } from "fs";
+import { dirname, join } from "path";
+
+// src/git.ts
+import { execSync } from "child_process";
+function tryExec(cmd, cwd) {
+  try {
+    return execSync(cmd, { cwd, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }).trim();
+  } catch {
+    return null;
+  }
+}
+function getRepoRoot() {
+  try {
+    return execSync("git rev-parse --show-toplevel", {
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"]
+    }).trim();
+  } catch {
+    throw new Error("Not in a git repository. task-tracker requires a git repository.");
+  }
+}
+function getRepoStatus(repoPath) {
+  const name = repoPath.split(/[\\/]/).pop() ?? repoPath;
+  const status = {
+    path: repoPath,
+    name,
+    dirty: false,
+    dirtyFiles: [],
+    unpushed: false,
+    unpushedCommits: []
+  };
+  const porcelain = tryExec("git status --porcelain", repoPath);
+  if (porcelain === null) {
+    status.error = "git status failed";
+    return status;
+  }
+  if (porcelain) {
+    status.dirty = true;
+    status.dirtyFiles = porcelain.split("\n").filter(Boolean);
+  }
+  const unpushed = tryExec("git log @{u}..HEAD --oneline", repoPath);
+  if (unpushed !== null && unpushed) {
+    status.unpushed = true;
+    status.unpushedCommits = unpushed.split("\n").filter(Boolean);
+  }
+  return status;
+}
+
+// src/storage.ts
+function getStoragePath() {
+  const root = getRepoRoot();
+  return join(root, ".tasks.jsonl");
+}
+function ensureStorageDir(storagePath) {
+  const dir = dirname(storagePath);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+}
+function readTasks(storagePath) {
+  ensureStorageDir(storagePath);
+  if (!existsSync(storagePath)) {
+    return [];
+  }
+  const content = readFileSync(storagePath, "utf-8").trim();
+  if (!content) return [];
+  return content.split("\n").filter((line) => line.trim()).map((line) => JSON.parse(line));
+}
+function writeTasks(storagePath, tasks) {
+  ensureStorageDir(storagePath);
+  const content = tasks.map((t) => JSON.stringify(t)).join("\n");
+  writeFileSync(storagePath, content ? content + "\n" : "", "utf-8");
+}
+function addTaskToStorage(storagePath, task) {
+  ensureStorageDir(storagePath);
+  appendFileSync(storagePath, JSON.stringify(task) + "\n", "utf-8");
+}
+
+// src/tasks.ts
+import { nanoid } from "nanoid";
+
+// src/types.ts
+var STAGES = [
+  "pending",
+  "in-progress",
+  "implemented",
+  "verified",
+  "committed",
+  "pushed",
+  "pr-created",
+  "merged",
+  "released",
+  "published",
+  "done"
+];
+var DONE_STAGES = ["done"];
+
+// src/tasks.ts
+function createTask(storagePath, description, options = {}) {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const task = {
+    id: nanoid(8),
+    description,
+    stage: options.stage ?? "pending",
+    createdAt: now,
+    updatedAt: now
+  };
+  addTaskToStorage(storagePath, task);
+  return task;
+}
+function listTasks(storagePath, options = {}) {
+  let tasks = readTasks(storagePath);
+  if (!options.all) {
+    tasks = tasks.filter((t) => !DONE_STAGES.includes(t.stage));
+  }
+  if (options.stage) {
+    tasks = tasks.filter((t) => t.stage === options.stage);
+  }
+  return tasks;
+}
+function updateTask(storagePath, id, updates) {
+  const tasks = readTasks(storagePath);
+  const idx = tasks.findIndex((t) => t.id === id);
+  if (idx === -1) return null;
+  const task = tasks[idx];
+  if (updates.stage !== void 0) task.stage = updates.stage;
+  if (updates.description !== void 0) task.description = updates.description;
+  task.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+  writeTasks(storagePath, tasks);
+  return task;
+}
+function removeTask(storagePath, id) {
+  const tasks = readTasks(storagePath);
+  const filtered = tasks.filter((t) => t.id !== id);
+  if (filtered.length === tasks.length) return false;
+  writeTasks(storagePath, filtered);
+  return true;
+}
+
+// src/format.ts
+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);
+  const id = chalk.bold(task.id);
+  return `${id}  ${stage}  ${task.description}`;
+}
+function formatTaskTable(tasks) {
+  if (tasks.length === 0) {
+    return chalk.dim("No tasks found.");
+  }
+  return tasks.map(formatTask).join("\n");
+}
+function formatCheckReport(activeTasks, repoStatus) {
+  const lines = [];
+  lines.push(chalk.bold("=== Task Tracker Check ==="));
+  lines.push("");
+  lines.push(chalk.bold(`Active Tasks (${activeTasks.length}):`));
+  if (activeTasks.length === 0) {
+    lines.push(chalk.dim("  No active tasks."));
+  } else {
+    for (const t of activeTasks) {
+      lines.push("  " + formatTask(t));
+    }
+  }
+  lines.push("");
+  lines.push(chalk.bold(`Git Status (${repoStatus.name}):`));
+  if (repoStatus.error) {
+    lines.push(chalk.red(`  Error: ${repoStatus.error}`));
+  } else if (!repoStatus.dirty && !repoStatus.unpushed) {
+    lines.push(chalk.green("  Clean."));
+  } else {
+    if (repoStatus.dirty) {
+      lines.push(chalk.red(`  Uncommitted changes (${repoStatus.dirtyFiles.length} files):`));
+      for (const f of repoStatus.dirtyFiles.slice(0, 5)) {
+        lines.push(chalk.dim(`    ${f}`));
+      }
+      if (repoStatus.dirtyFiles.length > 5) {
+        lines.push(chalk.dim(`    ... and ${repoStatus.dirtyFiles.length - 5} more`));
+      }
+    }
+    if (repoStatus.unpushed) {
+      lines.push(chalk.blue(`  Unpushed commits (${repoStatus.unpushedCommits.length}):`));
+      for (const c of repoStatus.unpushedCommits.slice(0, 5)) {
+        lines.push(chalk.dim(`    ${c}`));
+      }
+    }
+  }
+  return lines.join("\n");
+}
+
+// src/cli.ts
+import process from "process";
+var __filename = fileURLToPath(import.meta.url);
+var __dirname = dirname2(__filename);
+var version = "0.0.0";
+try {
+  const pkg = JSON.parse(readFileSync2(join2(__dirname, "..", "package.json"), "utf-8"));
+  version = pkg.version;
+} catch {
+}
+function isValidStage(s) {
+  return STAGES.includes(s);
+}
+function getStorage() {
+  try {
+    return getStoragePath();
+  } catch (e) {
+    console.error(e instanceof Error ? e.message : "Not in a git repository");
+    process.exit(1);
+  }
+}
+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) => {
+  if (!isValidStage(opts.stage)) {
+    console.error(`Invalid stage: ${opts.stage}
+Valid stages: ${STAGES.join(", ")}`);
+    process.exit(1);
+  }
+  const task = createTask(getStorage(), description, { stage: opts.stage });
+  if (opts.json) {
+    console.log(JSON.stringify(task, null, 2));
+  } else {
+    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) {
+    console.error(`Invalid stage: ${opts.stage}
+Valid stages: ${STAGES.join(", ")}`);
+    process.exit(1);
+  }
+  const tasks = listTasks(getStorage(), { all: opts.all, stage });
+  if (opts.json) {
+    console.log(JSON.stringify(tasks, null, 2));
+  } else {
+    console.log(formatTaskTable(tasks));
+  }
+});
+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) => {
+  if (opts.stage && !isValidStage(opts.stage)) {
+    console.error(`Invalid stage: ${opts.stage}
+Valid stages: ${STAGES.join(", ")}`);
+    process.exit(1);
+  }
+  const updates = {};
+  if (opts.stage) updates.stage = opts.stage;
+  if (opts.description) updates.description = opts.description;
+  const task = updateTask(getStorage(), id, updates);
+  if (!task) {
+    console.error(`Task not found: ${id}`);
+    process.exit(1);
+  }
+  if (opts.json) {
+    console.log(JSON.stringify(task, null, 2));
+  } else {
+    console.log("Updated: " + formatTask(task));
+  }
+});
+program.command("done <id>").description("Mark task as done").action((id) => {
+  const task = updateTask(getStorage(), id, { stage: "done" });
+  if (!task) {
+    console.error(`Task not found: ${id}`);
+    process.exit(1);
+  }
+  console.log("Done: " + formatTask(task));
+});
+program.command("remove <id>").description("Remove a task permanently").action((id) => {
+  const removed = removeTask(getStorage(), id);
+  if (!removed) {
+    console.error(`Task not found: ${id}`);
+    process.exit(1);
+  }
+  console.log(`Removed task: ${id}`);
+});
+program.command("check").description("Show active tasks and git status for this repo").option("--json", "JSON output").action((opts) => {
+  const storage = getStorage();
+  const repoRoot = dirname2(storage);
+  const activeTasks = listTasks(storage, { all: false });
+  const repoStatus = getRepoStatus(repoRoot);
+  if (opts.json) {
+    console.log(JSON.stringify({ activeTasks, repoStatus }, null, 2));
+  } else {
+    console.log(formatCheckReport(activeTasks, repoStatus));
+  }
+});
+program.parse(process.argv);

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@metyatech/task-tracker",
+  "version": "0.1.0",
+  "description": "Persistent task lifecycle tracker for AI agent sessions",
+  "type": "module",
+  "bin": {
+    "task-tracker": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/metyatech/task-tracker.git"
+  },
+  "bugs": {
+    "url": "https://github.com/metyatech/task-tracker/issues"
+  },
+  "homepage": "https://github.com/metyatech/task-tracker",
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "lint": "eslint src --ext .ts",
+    "format": "prettier --write \"src/**/*.ts\" \"*.json\" \"*.md\"",
+    "format:check": "prettier --check \"src/**/*.ts\" \"*.json\" \"*.md\"",
+    "verify": "npm run format:check && npm run lint && npm run build && npm run test"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "nanoid": "^5.0.7"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@typescript-eslint/eslint-plugin": "^7.0.0",
+    "@typescript-eslint/parser": "^7.0.0",
+    "eslint": "^8.57.0",
+    "prettier": "^3.2.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.4.0"
+  }
+}