trackerctl 0.3.0 → 0.4.1

package/README.md

@@ -89,6 +89,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 attach <id> <file...> [-m <msg>]` | Upload files, reference them from one comment; prints markdown |
+| `tracker label <id> [--add a,b] [--remove c,d]` | Add/remove labels without clobbering the rest |
 | `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 |
@@ -96,6 +98,16 @@ Read commands serve from a local sqlite cache that auto-syncs when older than
 | `tracker remember <key> <text>` | Store a project memory |
 | `tracker forget <key>` | Hide a memory key |
 | `tracker memories [filter]` | List memories (latest per key wins) |
+| `tracker pr create -t <title> --target <b> …` | Open a PR/MR (`mr` is an alias); `-i 42,43` records Closes trailers |
+| `tracker pr status <id>` | State + provider-neutral CI signal (`none\|pending\|green\|red`) |
+| `tracker pr merge <id> [--close-issues]` | Merge; `--close-issues` closes trailer-referenced issues explicitly |
+| `tracker pr comment/comments/close/reopen` | Discuss, reject (`close -m <reason>`), reopen |
+
+Issues and PRs are **separate capability ports**: `provider` selects where issues live,
+`merge_provider` (defaults to `provider`) selects where PRs live — so a Jira + GitHub
+mix needs no core changes, only adapters. Issue closing on merge is always explicit via
+the issues port: GitLab's `Closes #N` magic only fires on default-branch targets, and a
+GitHub PR can never auto-close a Jira issue, so tracker never relies on provider magic.
 
 Examples:
 
@@ -106,6 +118,7 @@ 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 attach 42 before.png after.png -m "reference screenshots"
 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
@@ -113,6 +126,9 @@ tracker create -t "Ship login" -d "OAuth" --parent 12 --blocked-by 7,9 -l auth,b
 tracker claim 42 && do-the-work || echo "someone else got it"
 tracker close 42 --reason "fixed in MR !17"
 tracker remember deploy-cmd "bun run deploy:prod"
+tracker pr create -t "Fix login" --target dev -i 42 --json
+tracker pr status 5 --json                    # poll for ci green/red
+tracker pr merge 5 --close-issues
 ```
 
 Exit codes: **0** success · **2** domain failure (lost claim race, refused claim, not
@@ -151,6 +167,15 @@ 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>"`
+- Attach evidence:  `tracker attach <id> <files...> -m "<context>" --json` — uploads
+                    screenshots/files and references them from a comment; reuse the
+                    returned markdown in descriptions
+- Open a PR/MR:     `tracker pr create -t "<title>" --target <branch> -i <issue-ids> --json`
+                    (source defaults to the current branch)
+- Watch the CI:     `tracker pr status <id> --json` — poll until `.ci` is "green" or "red"
+- Land it:          `tracker pr merge <id> --close-issues` — also closes the `-i` issues
+                    with a comment explaining why; never rely on provider auto-close
+
 - 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`,

package/dist/tracker.js

@@ -2,8 +2,38 @@
 // @bun
 
 // src/cli/index.ts
-import { existsSync as existsSync4 } from "fs";
-import { resolve as resolve4 } from "path";
+import { existsSync as existsSync4, readFileSync as readFileSync4 } from "fs";
+import { basename, resolve as resolve4 } from "path";
+
+// src/core/merge.ts
+function closesTrailers(issues) {
+  return issues.map((id) => `Closes #${id}`).join(`
+`);
+}
+function parseClosesIssues(description) {
+  const ids = [];
+  for (const m of description.matchAll(/^Closes #(\S+)\s*$/gim)) {
+    if (!ids.includes(m[1]))
+      ids.push(m[1]);
+  }
+  return ids;
+}
+function withClosesTrailers(description, issues) {
+  if (issues.length === 0)
+    return description;
+  return [description, closesTrailers(issues)].filter(Boolean).join(`
+
+`);
+}
+async function mergeAndCloseIssues(merge, issues, prId) {
+  const pr = await merge.prGet(prId);
+  await merge.prMerge(prId);
+  for (const id of pr.closesIssues) {
+    await issues.transition(id, "closed");
+    await issues.comment(id, `closed by merged PR: ${pr.url}`);
+  }
+  return { closed: pr.closesIssues };
+}
 
 // src/errors.ts
 class DomainError extends Error {
@@ -52,7 +82,7 @@ class GitLabClient {
         ...init,
         headers: {
           Authorization: `Bearer ${this.token}`,
-          "Content-Type": "application/json",
+          ...init.body instanceof FormData ? {} : { "Content-Type": "application/json" },
           ...init.headers ?? {}
         }
       });
@@ -101,6 +131,11 @@ class GitLabClient {
     }
     return all;
   }
+  async upload(path, form) {
+    const url = `${this.baseUrl}/api/v4/${path.replace(/^\//, "")}`;
+    const res = await this.request(url, { method: "POST", body: form });
+    return await res.json();
+  }
   async graphql(query, variables = {}) {
     const res = await this.request(`${this.baseUrl}/api/graphql`, {
       method: "POST",
@@ -207,10 +242,35 @@ mutation trackerWorkItemSetParent($input: WorkItemUpdateInput!) {
     workItem { id }
   }
 }`;
+function mapCiStatus(status) {
+  if (!status)
+    return "none";
+  if (status === "success")
+    return "green";
+  if (status === "failed" || status === "canceled")
+    return "red";
+  return "pending";
+}
+function mapMr(mr) {
+  return {
+    id: String(mr.iid),
+    title: mr.title,
+    state: mr.state === "merged" ? "merged" : mr.state === "opened" ? "open" : "closed",
+    source: mr.source_branch,
+    target: mr.target_branch,
+    draft: mr.draft ?? /^draft:/i.test(mr.title),
+    ci: mapCiStatus(mr.head_pipeline?.status),
+    closesIssues: parseClosesIssues(mr.description ?? ""),
+    url: mr.web_url,
+    description: mr.description ?? "",
+    updatedAt: mr.updated_at
+  };
+}
 
 class GitLabAdapter {
   provider = "gitlab";
   client;
+  baseUrl;
   projectRef;
   fullPath;
   nativeBlocking;
@@ -222,6 +282,7 @@ class GitLabAdapter {
       token: opts.token,
       fetchImpl: opts.fetchImpl
     });
+    this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
     this.projectRef = encodeURIComponent(opts.project);
     this.fullPath = /^\d+$/.test(opts.project) ? null : opts.project;
     this.nativeBlocking = opts.nativeBlocking;
@@ -477,6 +538,94 @@ class GitLabAdapter {
       createdAt: n.created_at
     }));
   }
+  async prCreate(draft) {
+    const title = draft.draft && !/^draft:/i.test(draft.title) ? `Draft: ${draft.title}` : draft.title;
+    const mr = await this.client.rest(`projects/${this.projectRef}/merge_requests`, {
+      method: "POST",
+      body: {
+        title,
+        source_branch: draft.source,
+        target_branch: draft.target,
+        description: withClosesTrailers(draft.description ?? "", draft.issues ?? [])
+      }
+    });
+    return mapMr(mr);
+  }
+  async prGet(id) {
+    try {
+      const mr = await this.client.rest(`projects/${this.projectRef}/merge_requests/${id}`);
+      return mapMr(mr);
+    } catch (e) {
+      if (e instanceof GitLabHttpError && e.status === 404) {
+        throw new DomainError(`PR !${id} not found`);
+      }
+      throw e;
+    }
+  }
+  async prMerge(id) {
+    try {
+      await this.client.rest(`projects/${this.projectRef}/merge_requests/${id}/merge`, {
+        method: "PUT"
+      });
+    } catch (e) {
+      if (e instanceof GitLabHttpError && [405, 406, 409, 422].includes(e.status)) {
+        throw new DomainError(`GitLab refuses to merge !${id}: ${e.message}`);
+      }
+      throw e;
+    }
+  }
+  async prComment(id, body) {
+    await this.client.rest(`projects/${this.projectRef}/merge_requests/${id}/notes`, {
+      method: "POST",
+      body: { body }
+    });
+  }
+  async prListComments(id) {
+    const notes = await this.client.rest(`projects/${this.projectRef}/merge_requests/${id}/notes`, { query: { sort: "asc", order_by: "created_at" }, paginate: true });
+    return notes.filter((n) => !n.system).map((n) => ({
+      id: String(n.id),
+      body: n.body,
+      author: mapUser(n.author),
+      createdAt: n.created_at
+    }));
+  }
+  async prStateEvent(id, event) {
+    try {
+      await this.client.rest(`projects/${this.projectRef}/merge_requests/${id}`, {
+        method: "PUT",
+        body: { state_event: event }
+      });
+    } catch (e) {
+      if (e instanceof GitLabHttpError && e.status === 422) {
+        throw new DomainError(`cannot ${event} PR !${id}: ${e.message}`);
+      }
+      throw e;
+    }
+  }
+  async prClose(id) {
+    return this.prStateEvent(id, "close");
+  }
+  async prReopen(id) {
+    return this.prStateEvent(id, "reopen");
+  }
+  async attach(id, files, message) {
+    const attachments = [];
+    for (const file of files) {
+      const form = new FormData;
+      form.set("file", new Blob([file.content]), file.filename);
+      const up = await this.client.upload(`projects/${this.projectRef}/uploads`, form);
+      attachments.push({
+        filename: file.filename,
+        url: `${this.baseUrl}${up.full_path ?? up.url}`,
+        markdown: up.markdown
+      });
+    }
+    const body = [message, ...attachments.map((a) => a.markdown)].filter(Boolean).join(`
+
+`);
+    await this.comment(id, body);
+    return attachments;
+  }
   async searchRemote(q) {
     const state = q.state ?? "all";
     const issues = await this.client.rest(`projects/${this.projectRef}/issues`, {
@@ -728,6 +877,9 @@ function parseConfig(json, rootDir) {
   if (raw.provider !== "gitlab") {
     throw new UsageError(`unsupported provider "${raw.provider}" (only "gitlab" for now)`);
   }
+  if ((raw.merge_provider ?? raw.provider) !== "gitlab") {
+    throw new UsageError(`unsupported merge_provider "${raw.merge_provider}" (only "gitlab" for now)`);
+  }
   const g = raw.gitlab ?? {};
   if (!g.base_url)
     throw new UsageError("config: gitlab.base_url is required");
@@ -736,6 +888,7 @@ function parseConfig(json, rootDir) {
   const tokenEnv = g.token_env === undefined ? ["TRACKER_GITLAB_TOKEN"] : Array.isArray(g.token_env) ? g.token_env : [g.token_env];
   return {
     provider: "gitlab",
+    merge_provider: "gitlab",
     gitlab: {
       base_url: g.base_url.replace(/\/+$/, ""),
       project: String(g.project),
@@ -1201,6 +1354,10 @@ write commands:
   release <id>               clear assignee/label, tombstone live claim tokens
   close <id> [--reason <text>]
   comment <id> <text>        post a comment on an item
+  label <id> [--add a,b] [--remove c,d]
+                             add/remove labels without touching the others
+  attach <id> <file...> [-m <message>]
+                             upload files and attach them via a comment
   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>
@@ -1208,6 +1365,15 @@ write commands:
   remember <key> <text>      store a project memory (key has no whitespace)
   forget <key>               hide a memory key
 
+pull/merge requests ("pr" and "mr" are the same command):
+  pr create -t <title> --target <branch> [--source <branch>] [-d <desc>]
+            [-i <issue-ids>] [--draft] [--json]
+  pr status <id> [--json]    state + provider-neutral ci signal (none|pending|green|red)
+  pr merge <id> [--close-issues]
+  pr comment <id> <text>
+  pr comments <id> [--json]
+  pr close <id> [-m <reason>] | pr reopen <id>
+
 search filters:
   --assignee <user> --author <user> --label <l> --state open|closed|all
   --parent <id> --remote     (text query optional when any filter is given)
@@ -1266,6 +1432,50 @@ Posts a comment on the item. Everything after the id is joined into one
 comment body, so quoting multi-word text is optional.
 
 example: tracker comment 42 "blocked on the design review, see thread"`,
+  label: `usage: tracker label <id> [--add <a,b>] [--remove <c,d>]
+
+Adds and/or removes labels (comma-separated) without clobbering the rest.
+At least one of --add/--remove is required.
+
+examples:
+  tracker label 42 --add status::agent-blocked
+  tracker label 42 --remove status::agent-blocked --add meta::human-only`,
+  attach: `usage: tracker attach <id> <file...> [-m <message>] [--json]
+
+Uploads each file to the provider and posts ONE comment on the item containing
+the optional message plus a markdown reference per file, so the attachments are
+discoverable from the item itself. Prints each file's markdown snippet (reusable
+in descriptions); --json emits [{filename, url, markdown}].
+
+examples:
+  tracker attach 42 before.png after.png -m "reference screenshots"
+  tracker attach 42 design.png --json`,
+  pr: `usage: tracker pr <action> \u2026    (alias: tracker mr)
+
+actions:
+  create -t <title> --target <branch> [--source <branch>] [-d <desc>]
+         [-i <id1,id2>] [--draft] [--json]
+                      open a PR/MR; --source defaults to the current git branch.
+                      -i records "Closes #N" trailers so merge --close-issues
+                      can close those issues explicitly (no provider magic).
+  status <id> [--json]
+                      state (open|merged|closed) + ci signal (none|pending|green|red);
+                      poll this to watch a pipeline.
+  merge <id> [--close-issues]
+                      merge; --close-issues then closes every trailer-referenced
+                      issue via the issue tracker and comments why.
+  comment <id> <text> post a comment
+  comments <id> [--json]
+                      list comments oldest-first
+  close <id> [-m <reason>]
+                      close without merging ("reject"); reason posts as a comment
+  reopen <id>
+
+examples:
+  tracker pr create -t "Fix login" --target dev -i 42 --json
+  tracker pr status 5 --json
+  tracker pr merge 5 --close-issues
+  tracker pr close 5 -m "superseded by !6"`,
   comments: `usage: tracker comments <id> [--json]
 
 Lists the item's comments oldest-first (system notes are filtered out). Claim
@@ -1626,6 +1836,147 @@ async function cmdComment(ctx, args) {
   await ctx.adapter.comment(id, body);
   console.log(`commented on #${id}`);
 }
+async function cmdLabel(ctx, args) {
+  const id = normalizeId(args.positionals[0]);
+  const csv = (name) => (str(args, name) ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+  const addLabels = csv("--add");
+  const removeLabels = csv("--remove");
+  if (addLabels.length === 0 && removeLabels.length === 0) {
+    throw new UsageError(commandHelp("label"));
+  }
+  await ctx.adapter.update(id, {
+    ...addLabels.length ? { addLabels } : {},
+    ...removeLabels.length ? { removeLabels } : {}
+  });
+  invalidate(ctx);
+  const parts = [
+    ...addLabels.length ? [`+${addLabels.join(" +")}`] : [],
+    ...removeLabels.length ? [`-${removeLabels.join(" -")}`] : []
+  ];
+  console.log(`#${id} labels: ${parts.join(" ")}`);
+}
+async function cmdAttach(ctx, args) {
+  const [idArg, ...paths] = args.positionals;
+  const id = normalizeId(idArg);
+  if (paths.length === 0)
+    throw new UsageError(commandHelp("attach"));
+  const files = paths.map((p) => {
+    if (!existsSync4(p))
+      throw new UsageError(`${p}: no such file`);
+    return { filename: basename(p), content: new Uint8Array(readFileSync4(p)) };
+  });
+  const attachments = await ctx.adapter.attach(id, files, str(args, "--message"));
+  if (args.flags.get("--json"))
+    return printJson(attachments);
+  for (const a of attachments)
+    console.log(a.markdown);
+  console.error(`attached ${attachments.length} file(s) to #${id}`);
+}
+function normalizePrId(raw) {
+  if (!raw)
+    throw new UsageError("PR id is required");
+  return raw.replace(/^[!#]/, "");
+}
+function currentGitBranch() {
+  const proc = Bun.spawnSync(["git", "rev-parse", "--abbrev-ref", "HEAD"]);
+  const branch = proc.success ? proc.stdout.toString().trim() : "";
+  if (!branch || branch === "HEAD") {
+    throw new UsageError("could not determine the current git branch \u2014 pass --source");
+  }
+  return branch;
+}
+async function cmdPr(ctx, args) {
+  const [action, ...positionals] = args.positionals;
+  const json = args.flags.get("--json");
+  switch (action) {
+    case "create": {
+      const title = str(args, "--title");
+      const target = str(args, "--target");
+      if (!title)
+        throw new UsageError(`--title is required
+
+${commandHelp("pr")}`);
+      if (!target)
+        throw new UsageError(`--target is required
+
+${commandHelp("pr")}`);
+      const pr = await ctx.adapter.prCreate({
+        title,
+        target,
+        source: str(args, "--source") ?? currentGitBranch(),
+        description: str(args, "--description"),
+        draft: args.flags.get("--draft") === true,
+        issues: (str(args, "--issue") ?? "").split(",").filter(Boolean).map((s) => s.replace(/^#/, ""))
+      });
+      if (json)
+        return printJson(pr);
+      console.log(pr.url);
+      console.error(`created PR !${pr.id}: ${pr.source} \u2192 ${pr.target}`);
+      return;
+    }
+    case "status": {
+      const pr = await ctx.adapter.prGet(normalizePrId(positionals[0]));
+      if (json)
+        return printJson(pr);
+      const closes = pr.closesIssues.length ? ` \xB7 closes ${pr.closesIssues.map((i) => `#${i}`).join(",")}` : "";
+      console.log(`!${pr.id} ${pr.state} \xB7 ci ${pr.ci}${pr.draft ? " \xB7 draft" : ""}${closes}`);
+      console.log(pr.url);
+      return;
+    }
+    case "merge": {
+      const id = normalizePrId(positionals[0]);
+      if (args.flags.get("--close-issues")) {
+        const { closed } = await mergeAndCloseIssues(ctx.adapter, ctx.adapter, id);
+        invalidate(ctx);
+        console.log(closed.length ? `merged !${id}, closed ${closed.map((i) => `#${i}`).join(", ")}` : `merged !${id} (no Closes trailers found)`);
+      } else {
+        await ctx.adapter.prMerge(id);
+        console.log(`merged !${id}`);
+      }
+      return;
+    }
+    case "comment": {
+      const id = normalizePrId(positionals[0]);
+      const body = positionals.slice(1).join(" ").trim();
+      if (!body)
+        throw new UsageError(commandHelp("pr"));
+      await ctx.adapter.prComment(id, body);
+      console.log(`commented on !${id}`);
+      return;
+    }
+    case "comments": {
+      const id = normalizePrId(positionals[0]);
+      const comments = await ctx.adapter.prListComments(id);
+      if (json)
+        return printJson(comments);
+      if (comments.length === 0)
+        return console.error(`(no comments on !${id})`);
+      for (const c of comments) {
+        console.log(`@${c.author.username}	${c.createdAt}`);
+        console.log(c.body);
+        console.log("");
+      }
+      return;
+    }
+    case "close": {
+      const id = normalizePrId(positionals[0]);
+      const reason = str(args, "--message");
+      if (reason)
+        await ctx.adapter.prComment(id, reason);
+      await ctx.adapter.prClose(id);
+      console.log(`closed !${id}`);
+      return;
+    }
+    case "reopen": {
+      const id = normalizePrId(positionals[0]);
+      await ctx.adapter.prReopen(id);
+      console.log(`reopened !${id}`);
+      return;
+    }
+    default:
+      throw new UsageError(commandHelp("pr"));
+  }
+}
 async function cmdComments(ctx, args) {
   const id = normalizeId(args.positionals[0]);
   const comments = await ctx.adapter.listComments(id);
@@ -1841,6 +2192,19 @@ var VALUE_FLAGS = {
   memories: { "--json": "bool" },
   comment: {},
   comments: { "--json": "bool" },
+  attach: { "--message": "value", "--json": "bool" },
+  label: { "--add": "value", "--remove": "value" },
+  pr: {
+    "--title": "value",
+    "--description": "value",
+    "--source": "value",
+    "--target": "value",
+    "--issue": "value",
+    "--draft": "bool",
+    "--close-issues": "bool",
+    "--message": "value",
+    "--json": "bool"
+  },
   spend: {},
   estimate: {},
   sync: {},
@@ -1858,10 +2222,13 @@ var ALIASES = {
     "--labels": "--label",
     "-m": "--milestone"
   },
-  close: { "-r": "--reason" }
+  close: { "-r": "--reason" },
+  attach: { "-m": "--message" },
+  pr: { "-t": "--title", "-d": "--description", "-m": "--message", "-i": "--issue" }
 };
 async function run(argv) {
-  const [cmd, ...rest] = argv;
+  const [rawCmd, ...rest] = argv;
+  const cmd = rawCmd === "mr" ? "pr" : rawCmd;
   if (!cmd || cmd === "help" || cmd === "--help" || cmd === "-h") {
     console.log(HELP);
     return cmd ? 0 : 1;
@@ -1902,6 +2269,9 @@ ${HELP}`);
     memories: cmdMemories,
     comment: cmdComment,
     comments: cmdComments,
+    attach: cmdAttach,
+    label: cmdLabel,
+    pr: cmdPr,
     spend: cmdSpend,
     estimate: cmdEstimate,
     search: cmdSearch,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trackerctl",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "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",

package/tracker.config.example.json

@@ -1,5 +1,6 @@
 {
   "provider": "gitlab",
+  "merge_provider": "gitlab",
   "gitlab": {
     "base_url": "https://gitlab.example.com",
     "project": "group/project",