trackerctl 0.1.0 → 0.2.0

package/README.md

@@ -86,6 +86,8 @@ Read commands serve from a local sqlite cache that auto-syncs when older than
 | `tracker release <id>` | Clear assignee + label, tombstone claim tokens |
 | `tracker close <id> [--reason <text>]` | Close (clears assignee + in-progress label) |
 | `tracker comment <id> <text>` | Post a comment on an item |
+| `tracker spend <id> <duration>` | Add time spent (`1h30m`, `2d`; `-30m` subtracts) |
+| `tracker estimate <id> <duration>` | Set the time estimate (`0` clears it) |
 | `tracker dep <id> --blocked-by <o> \| --blocks <o>` | Add a dependency edge |
 | `tracker parent <child> <parent>` | Re-parent an item |
 | `tracker remember <key> <text>` | Store a project memory |
@@ -101,6 +103,8 @@ tracker search --state closed                 # state alone is a valid filter
 tracker search "payment timeout" --label backend --state open
 tracker comment 42 "blocked on design review"
 tracker comments 42 --json
+tracker spend 42 1h30m                        # durations: w/d/h/m/s, 1d=8h, 1w=5d
+tracker estimate 42 2d
 tracker search checkout --remote --json       # fresher, server-side
 tracker create -t "Ship login" -d "OAuth" --parent 12 --blocked-by 7,9 -l auth,backend
 tracker claim 42 && do-the-work || echo "someone else got it"
@@ -144,6 +148,8 @@ domain refusal (e.g. lost a claim race) — pick different work, don't retry.
 - Inspect:          `tracker show <id> --json`, `tracker children <id> --json`,
                     `tracker epic-status <id> --json`, `tracker comments <id> --json`
 - Discuss:          `tracker comment <id> "<note for humans or other agents>"`
+- Track time:       `tracker spend <id> 1h30m` after finishing work (estimate vs spent
+                    feeds later evaluations; durations use 1d=8h, -30m subtracts)
 - Project memory:   `tracker remember <key> "<fact>"`, `tracker memories --json`,
                     `tracker forget <key>`
 
@@ -168,7 +174,9 @@ Never edit the `📌 Project Memory` issue or `🔒/🔓` notes by hand.
   "blockedBy": ["7", "9"],     // ids of open OR closed blockers; `ready` checks openness
   "url": "https://gitlab…/issues/42",
   "description": "…",
-  "updatedAt": "2026-06-10T17:21:33.000Z"
+  "updatedAt": "2026-06-10T17:21:33.000Z",
+  "timeSpentSeconds": 3600,        // 0 = none recorded
+  "timeEstimateSeconds": 57600     // 0 = no estimate
 }
 ```
 

package/dist/tracker.js

@@ -156,6 +156,8 @@ function mapIssue(issue, info) {
     url: issue.web_url,
     description,
     updatedAt: issue.updated_at,
+    timeSpentSeconds: issue.time_stats?.total_time_spent ?? 0,
+    timeEstimateSeconds: issue.time_stats?.time_estimate ?? 0,
     raw: issue
   };
 }
@@ -225,7 +227,12 @@ class GitLabAdapter {
     this.nativeBlocking = opts.nativeBlocking;
   }
   capabilities() {
-    return { nativeBlocking: this.nativeBlocking, nativeHierarchy: true, serverSearch: true };
+    return {
+      nativeBlocking: this.nativeBlocking,
+      nativeHierarchy: true,
+      serverSearch: true,
+      timeTracking: true
+    };
   }
   async getFullPath() {
     if (this.fullPath)
@@ -414,6 +421,47 @@ class GitLabAdapter {
       throw new DomainError(`workItemUpdate: ${data.workItemUpdate.errors.join("; ")}`);
     }
   }
+  static glDuration(seconds) {
+    const sign = seconds < 0 ? "-" : "";
+    let rest = Math.abs(seconds);
+    const parts = [];
+    const h = Math.floor(rest / 3600);
+    rest %= 3600;
+    const m = Math.floor(rest / 60);
+    const s = rest % 60;
+    if (h)
+      parts.push(`${h}h`);
+    if (m)
+      parts.push(`${m}m`);
+    if (s)
+      parts.push(`${s}s`);
+    return sign + (parts.join("") || "0m");
+  }
+  async addTimeSpent(id, seconds) {
+    try {
+      await this.client.rest(`projects/${this.projectRef}/issues/${id}/add_spent_time`, {
+        method: "POST",
+        body: { duration: GitLabAdapter.glDuration(seconds) }
+      });
+    } catch (e) {
+      if (e instanceof GitLabHttpError && e.status === 400) {
+        throw new DomainError(`cannot record ${GitLabAdapter.glDuration(seconds)} on #${id}: ${e.message}`);
+      }
+      throw e;
+    }
+  }
+  async setTimeEstimate(id, seconds) {
+    if (seconds === 0) {
+      await this.client.rest(`projects/${this.projectRef}/issues/${id}/reset_time_estimate`, {
+        method: "POST"
+      });
+      return;
+    }
+    await this.client.rest(`projects/${this.projectRef}/issues/${id}/time_estimate`, {
+      method: "POST",
+      body: { duration: GitLabAdapter.glDuration(seconds) }
+    });
+  }
   async comment(id, body) {
     await this.client.rest(`projects/${this.projectRef}/issues/${id}/notes`, {
       method: "POST",
@@ -478,6 +526,8 @@ CREATE TABLE IF NOT EXISTS items (
   url         TEXT NOT NULL,
   description TEXT NOT NULL,
   updated_at  TEXT NOT NULL,
+  time_spent    INTEGER NOT NULL DEFAULT 0,
+  time_estimate INTEGER NOT NULL DEFAULT 0,
   raw         TEXT
 );
 CREATE INDEX IF NOT EXISTS idx_items_parent ON items(parent);
@@ -501,16 +551,24 @@ class Cache {
       mkdirSync(dirname(path), { recursive: true });
     this.db = new Database(path);
     this.db.exec(SCHEMA);
+    for (const col of [
+      "time_spent INTEGER NOT NULL DEFAULT 0",
+      "time_estimate INTEGER NOT NULL DEFAULT 0"
+    ]) {
+      try {
+        this.db.exec(`ALTER TABLE items ADD COLUMN ${col}`);
+      } catch {}
+    }
   }
   replaceAll(items, provider) {
-    const insertItem = this.db.prepare(`INSERT INTO items (id, provider, kind, title, state, labels, assignees, author, parent, url, description, updated_at, raw)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+    const insertItem = this.db.prepare(`INSERT INTO items (id, provider, kind, title, state, labels, assignees, author, parent, url, description, updated_at, time_spent, time_estimate, raw)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
     const insertLink = this.db.prepare("INSERT OR IGNORE INTO links (blocker, blocked) VALUES (?, ?)");
     const insertFts = this.db.prepare("INSERT INTO items_fts (id, title, description) VALUES (?, ?, ?)");
     const tx = this.db.transaction(() => {
       this.db.exec("DELETE FROM items; DELETE FROM links; DELETE FROM items_fts;");
       for (const item of items) {
-        insertItem.run(item.id, provider, item.kind, item.title, item.state, JSON.stringify(item.labels), JSON.stringify(item.assignees), item.author ? JSON.stringify(item.author) : null, item.parent, item.url, item.description, item.updatedAt, item.raw === undefined ? null : JSON.stringify(item.raw));
+        insertItem.run(item.id, provider, item.kind, item.title, item.state, JSON.stringify(item.labels), JSON.stringify(item.assignees), item.author ? JSON.stringify(item.author) : null, item.parent, item.url, item.description, item.updatedAt, item.timeSpentSeconds, item.timeEstimateSeconds, item.raw === undefined ? null : JSON.stringify(item.raw));
         for (const blocker of item.blockedBy)
           insertLink.run(blocker, item.id);
         insertFts.run(item.id, item.title, item.description);
@@ -531,7 +589,9 @@ class Cache {
       blockedBy: this.blockersOf(row.id),
       url: row.url,
       description: row.description,
-      updatedAt: row.updated_at
+      updatedAt: row.updated_at,
+      timeSpentSeconds: row.time_spent,
+      timeEstimateSeconds: row.time_estimate
     };
   }
   blockersOf(id) {
@@ -854,6 +914,47 @@ async function releaseItem(adapter, id, policy) {
   return { id, cleared };
 }
 
+// src/core/duration.ts
+var UNIT_SECONDS = {
+  w: 5 * 8 * 3600,
+  d: 8 * 3600,
+  h: 3600,
+  m: 60,
+  s: 1
+};
+function parseDuration(input) {
+  const trimmed = input.trim();
+  const negative = trimmed.startsWith("-");
+  const body = negative ? trimmed.slice(1) : trimmed;
+  if (body === "0")
+    return 0;
+  const parts = [...body.matchAll(/(\d+)([wdhms])/g)];
+  const matched = parts.map((p) => p[0]).join("");
+  if (parts.length === 0 || matched !== body) {
+    throw new UsageError(`invalid duration "${input}" \u2014 use units w/d/h/m/s, e.g. 1h30m, 45m, 2d (1d=8h, 1w=5d), -30m to subtract`);
+  }
+  const seconds = parts.reduce((sum, p) => sum + Number(p[1]) * UNIT_SECONDS[p[2]], 0);
+  return negative ? -seconds : seconds;
+}
+function formatDuration(totalSeconds) {
+  const sign = totalSeconds < 0 ? "-" : "";
+  let rest = Math.abs(Math.round(totalSeconds));
+  const parts = [];
+  const h = Math.floor(rest / 3600);
+  rest %= 3600;
+  const m = Math.floor(rest / 60);
+  const s = rest % 60;
+  if (h)
+    parts.push(`${h}h`);
+  if (m)
+    parts.push(`${m}m`);
+  if (s)
+    parts.push(`${s}s`);
+  if (parts.length === 0)
+    return "0m";
+  return sign + parts.join(" ");
+}
+
 // src/core/ids.ts
 function normalizeId(input) {
   const id = (input ?? "").trim().replace(/^#/, "");
@@ -1029,6 +1130,8 @@ write commands:
   release <id>               clear assignee/label, tombstone live claim tokens
   close <id> [--reason <text>]
   comment <id> <text>        post a comment on an item
+  spend <id> <duration>      add time spent (1h30m, 45m, 2d; -30m subtracts)
+  estimate <id> <duration>   set the time estimate (0 clears it)
   dep <id> --blocked-by <other> | --blocks <other>
   parent <child-id> <parent-id>
   remember <key> <text>      store a project memory (key has no whitespace)
@@ -1098,6 +1201,21 @@ Lists the item's comments oldest-first (system notes are filtered out). Claim
 notes (\uD83D\uDD12/\uD83D\uDD13) and memory entries (\uD83D\uDCCC) appear here too \u2014 useful for debugging.
 
 example: tracker comments 42 --json`,
+  spend: `usage: tracker spend <id> <duration>
+
+Adds to the item's time spent. Durations use GitLab conventions:
+units w/d/h/m/s with 1d = 8h and 1w = 5d. A leading "-" subtracts.
+
+examples:
+  tracker spend 42 1h30m
+  tracker spend 42 -30m     # logged too much, take 30m back`,
+  estimate: `usage: tracker estimate <id> <duration>
+
+Sets the item's time estimate (same duration format as spend). 0 clears it.
+
+examples:
+  tracker estimate 42 2d
+  tracker estimate 42 0`,
   dep: `usage: tracker dep <id> --blocked-by <other> | --blocks <other>
 
 examples:
@@ -1168,6 +1286,11 @@ function printItemDetail(item, blocks) {
   console.log(`parent:     ${item.parent ? `#${item.parent}` : "-"}`);
   console.log(`blocked by: ${item.blockedBy.map((b) => `#${b}`).join(", ") || "-"}`);
   console.log(`blocks:     ${blocks.map((b) => `#${b}`).join(", ") || "-"}`);
+  if (item.timeSpentSeconds || item.timeEstimateSeconds) {
+    const spent = formatDuration(item.timeSpentSeconds);
+    const estimate = item.timeEstimateSeconds ? ` / estimate ${formatDuration(item.timeEstimateSeconds)}` : "";
+    console.log(`time:       spent ${spent}${estimate}`);
+  }
   console.log(`updated:    ${item.updatedAt}`);
   if (item.description) {
     console.log("---");
@@ -1185,7 +1308,7 @@ function parseArgs(args, spec, aliases = {}) {
   const positionals = [];
   for (let i = 0;i < args.length; i++) {
     const arg = args[i];
-    if (!arg.startsWith("-") || arg === "-") {
+    if (!arg.startsWith("-") || arg === "-" || /^-\d/.test(arg)) {
       positionals.push(arg);
       continue;
     }
@@ -1381,6 +1504,38 @@ async function cmdMemories(ctx, args) {
   for (const m of memories)
     console.log(`${m.key}	${m.ts}	${m.text}`);
 }
+function requireTimeTracking(ctx) {
+  if (!ctx.adapter.capabilities().timeTracking) {
+    throw new UsageError(`the ${ctx.adapter.provider} adapter does not support time tracking`);
+  }
+}
+async function cmdSpend(ctx, args) {
+  requireTimeTracking(ctx);
+  const [idArg, durationArg] = args.positionals;
+  const id = normalizeId(idArg);
+  if (!durationArg)
+    throw new UsageError(commandHelp("spend"));
+  const seconds = parseDuration(durationArg);
+  if (seconds === 0)
+    throw new UsageError("spend needs a non-zero duration (e.g. 1h30m or -30m)");
+  await ctx.adapter.addTimeSpent(id, seconds);
+  invalidate(ctx);
+  const item = await ctx.adapter.get(id);
+  console.log(`#${id} ${seconds > 0 ? "spent" : "subtracted"} ${formatDuration(Math.abs(seconds))} \u2192 total ${formatDuration(item.timeSpentSeconds)}`);
+}
+async function cmdEstimate(ctx, args) {
+  requireTimeTracking(ctx);
+  const [idArg, durationArg] = args.positionals;
+  const id = normalizeId(idArg);
+  if (durationArg === undefined)
+    throw new UsageError(commandHelp("estimate"));
+  const seconds = parseDuration(durationArg);
+  if (seconds < 0)
+    throw new UsageError("an estimate cannot be negative (use 0 to clear it)");
+  await ctx.adapter.setTimeEstimate(id, seconds);
+  invalidate(ctx);
+  console.log(seconds === 0 ? `#${id} estimate cleared` : `#${id} estimate ${formatDuration(seconds)}`);
+}
 async function cmdComment(ctx, args) {
   const [idArg, ...textParts] = args.positionals;
   const id = normalizeId(idArg);
@@ -1589,6 +1744,8 @@ var VALUE_FLAGS = {
   memories: { "--json": "bool" },
   comment: {},
   comments: { "--json": "bool" },
+  spend: {},
+  estimate: {},
   sync: {},
   claim: {},
   release: {},
@@ -1644,6 +1801,8 @@ ${HELP}`);
     memories: cmdMemories,
     comment: cmdComment,
     comments: cmdComments,
+    spend: cmdSpend,
+    estimate: cmdEstimate,
     search: cmdSearch,
     users: cmdUsers,
     whoami: cmdWhoami

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trackerctl",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Multi-backend issue-tracking CLI for humans and AI agents — claim races, dependencies, hierarchy, local FTS search, project memory. GitLab adapter first.",
   "license": "MIT",
   "author": "refo",