trackerctl 0.1.0

package/dist/tracker.js

@@ -0,0 +1,1665 @@
+#!/usr/bin/env bun
+// @bun
+
+// src/cli/index.ts
+import { existsSync as existsSync3 } from "fs";
+import { resolve as resolve3 } from "path";
+
+// src/errors.ts
+class DomainError extends Error {
+}
+
+class UsageError extends Error {
+}
+var secrets = [];
+function registerSecret(secret) {
+  if (secret && !secrets.includes(secret))
+    secrets.push(secret);
+}
+function redact(text) {
+  let out = text;
+  for (const s of secrets) {
+    while (out.includes(s))
+      out = out.replace(s, "[REDACTED]");
+  }
+  out = out.replace(/glpat-[\w-]{10,}/g, "[REDACTED]");
+  return out;
+}
+
+// src/adapters/gitlab/client.ts
+class GitLabHttpError extends Error {
+  status;
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+  }
+}
+
+class GitLabClient {
+  baseUrl;
+  token;
+  fetchImpl;
+  constructor(opts) {
+    this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+    this.token = opts.token;
+    this.fetchImpl = opts.fetchImpl ?? ((url, init) => fetch(url, init));
+    registerSecret(this.token);
+  }
+  async request(url, init) {
+    let res;
+    try {
+      res = await this.fetchImpl(url, {
+        ...init,
+        headers: {
+          Authorization: `Bearer ${this.token}`,
+          "Content-Type": "application/json",
+          ...init.headers ?? {}
+        }
+      });
+    } catch (e) {
+      throw new UsageError(redact(`request to ${url} failed: ${e.message}`));
+    }
+    if (!res.ok) {
+      const body = await res.text().catch(() => "");
+      throw new GitLabHttpError(res.status, redact(`GitLab API ${init.method ?? "GET"} ${url} \u2192 ${res.status}: ${body.slice(0, 500)}`));
+    }
+    return res;
+  }
+  async rest(path, opts = {}) {
+    const makeUrl = (page2) => {
+      const url = new URL(`${this.baseUrl}/api/v4/${path.replace(/^\//, "")}`);
+      for (const [k, v] of Object.entries(opts.query ?? {})) {
+        if (v !== undefined)
+          url.searchParams.set(k, v);
+      }
+      if (opts.paginate) {
+        url.searchParams.set("per_page", "100");
+        if (page2)
+          url.searchParams.set("page", String(page2));
+      }
+      return url.toString();
+    };
+    const init = {
+      method: opts.method ?? "GET",
+      body: opts.body === undefined ? undefined : JSON.stringify(opts.body)
+    };
+    if (!opts.paginate) {
+      const res = await this.request(makeUrl(), init);
+      const text = await res.text();
+      return text.trim() ? JSON.parse(text) : null;
+    }
+    const all = [];
+    let page;
+    for (let i = 0;i < 100; i++) {
+      const res = await this.request(makeUrl(page), init);
+      const chunk = await res.json();
+      all.push(...chunk);
+      const next = res.headers.get("x-next-page");
+      if (!next)
+        break;
+      page = Number(next);
+    }
+    return all;
+  }
+  async graphql(query, variables = {}) {
+    const res = await this.request(`${this.baseUrl}/api/graphql`, {
+      method: "POST",
+      body: JSON.stringify({ query, variables })
+    });
+    const json = await res.json();
+    if (json.errors?.length) {
+      throw new UsageError(redact(`GraphQL: ${json.errors.map((e) => e.message).join("; ")}`));
+    }
+    if (json.data === undefined)
+      throw new UsageError("GraphQL: empty response");
+    return json.data;
+  }
+}
+
+// src/adapters/gitlab/map.ts
+var TRAILER_RE = /^Tracker-Blocked-By:\s*(.+)$/im;
+function parseBlockedByTrailer(description) {
+  const match = description?.match(TRAILER_RE);
+  if (!match)
+    return [];
+  return match[1].split(",").map((s) => s.trim().replace(/^#/, "")).filter(Boolean);
+}
+function upsertBlockedByTrailer(description, blockerIds) {
+  const existing = parseBlockedByTrailer(description);
+  const merged = [...new Set([...existing, ...blockerIds])];
+  const line = `Tracker-Blocked-By: ${merged.map((id) => `#${id}`).join(", ")}`;
+  if (TRAILER_RE.test(description))
+    return description.replace(TRAILER_RE, line);
+  return description.trim() ? `${description.trimEnd()}
+
+${line}` : line;
+}
+function mapUser(u) {
+  return { id: String(u.id), username: u.username, ...u.name ? { name: u.name } : {} };
+}
+function mapIssue(issue, info) {
+  const description = issue.description ?? "";
+  const blockedBy = new Set([
+    ...info?.blockedBy ?? [],
+    ...parseBlockedByTrailer(description)
+  ]);
+  return {
+    id: String(issue.iid),
+    kind: info?.typeName === "Epic" ? "epic" : "task",
+    title: issue.title,
+    state: issue.state === "opened" ? "open" : "closed",
+    labels: issue.labels ?? [],
+    assignees: (issue.assignees ?? []).map(mapUser),
+    author: issue.author ? mapUser(issue.author) : null,
+    parent: info?.parent ?? null,
+    blockedBy: [...blockedBy].sort((a, b) => Number(a) - Number(b) || (a < b ? -1 : 1)),
+    url: issue.web_url,
+    description,
+    updatedAt: issue.updated_at,
+    raw: issue
+  };
+}
+
+// src/adapters/gitlab/adapter.ts
+var WORK_ITEMS_QUERY = `
+query trackerWorkItems($fullPath: ID!, $after: String) {
+  project(fullPath: $fullPath) {
+    workItems(first: 100, after: $after) {
+      nodes {
+        iid
+        workItemType { name }
+        widgets {
+          ... on WorkItemWidgetHierarchy { parent { iid } }
+          ... on WorkItemWidgetLinkedItems {
+            linkedItems(first: 100) { nodes { linkType workItem { iid } } }
+          }
+        }
+      }
+      pageInfo { endCursor hasNextPage }
+    }
+  }
+}`;
+var WORK_ITEM_GIDS_QUERY = `
+query trackerWorkItemGids($fullPath: ID!, $iids: [String!]) {
+  project(fullPath: $fullPath) {
+    workItems(iids: $iids) { nodes { id iid } }
+  }
+}`;
+var WORK_ITEM_TYPES_QUERY = `
+query trackerWorkItemTypes($fullPath: ID!) {
+  project(fullPath: $fullPath) {
+    workItemTypes { nodes { id name } }
+  }
+}`;
+var WORK_ITEM_CREATE_MUTATION = `
+mutation trackerWorkItemCreate($input: WorkItemCreateInput!) {
+  workItemCreate(input: $input) {
+    errors
+    workItem { id iid }
+  }
+}`;
+var WORK_ITEM_UPDATE_MUTATION = `
+mutation trackerWorkItemSetParent($input: WorkItemUpdateInput!) {
+  workItemUpdate(input: $input) {
+    errors
+    workItem { id }
+  }
+}`;
+
+class GitLabAdapter {
+  provider = "gitlab";
+  client;
+  projectRef;
+  fullPath;
+  nativeBlocking;
+  me = null;
+  taskTypeGid = null;
+  constructor(opts) {
+    this.client = new GitLabClient({
+      baseUrl: opts.baseUrl,
+      token: opts.token,
+      fetchImpl: opts.fetchImpl
+    });
+    this.projectRef = encodeURIComponent(opts.project);
+    this.fullPath = /^\d+$/.test(opts.project) ? null : opts.project;
+    this.nativeBlocking = opts.nativeBlocking;
+  }
+  capabilities() {
+    return { nativeBlocking: this.nativeBlocking, nativeHierarchy: true, serverSearch: true };
+  }
+  async getFullPath() {
+    if (this.fullPath)
+      return this.fullPath;
+    const project = await this.client.rest(`projects/${this.projectRef}`);
+    this.fullPath = project.path_with_namespace;
+    return this.fullPath;
+  }
+  async whoami() {
+    if (!this.me)
+      this.me = mapUser(await this.client.rest("user"));
+    return this.me;
+  }
+  async fetchHierarchy() {
+    const fullPath = await this.getFullPath();
+    const out = new Map;
+    let after = null;
+    for (let page = 0;page < 100; page++) {
+      const data = await this.client.graphql(WORK_ITEMS_QUERY, {
+        fullPath,
+        after
+      });
+      const conn = data.project?.workItems;
+      if (!conn)
+        break;
+      for (const node of conn.nodes) {
+        const parent = node.widgets.find((w) => w.parent !== undefined)?.parent;
+        const linked = node.widgets.find((w) => w.linkedItems !== undefined)?.linkedItems;
+        const blockedBy = [];
+        for (const link of linked?.nodes ?? []) {
+          const type = link.linkType.toLowerCase();
+          if (type === "is_blocked_by" || type === "blocked_by")
+            blockedBy.push(link.workItem.iid);
+        }
+        out.set(node.iid, {
+          parent: parent ? parent.iid : null,
+          blockedBy,
+          typeName: node.workItemType.name
+        });
+      }
+      if (!conn.pageInfo.hasNextPage)
+        break;
+      after = conn.pageInfo.endCursor;
+    }
+    return out;
+  }
+  async fetchAll() {
+    const [issues, hierarchy] = await Promise.all([
+      this.client.rest(`projects/${this.projectRef}/issues`, {
+        query: { state: "all" },
+        paginate: true
+      }),
+      this.fetchHierarchy()
+    ]);
+    return issues.map((issue) => mapIssue(issue, hierarchy.get(String(issue.iid))));
+  }
+  async get(id) {
+    let issue;
+    try {
+      issue = await this.client.rest(`projects/${this.projectRef}/issues/${id}`);
+    } catch (e) {
+      if (e instanceof GitLabHttpError && e.status === 404) {
+        throw new DomainError(`#${id} not found`);
+      }
+      throw e;
+    }
+    return mapIssue(issue);
+  }
+  async resolveGids(iids) {
+    const fullPath = await this.getFullPath();
+    const data = await this.client.graphql(WORK_ITEM_GIDS_QUERY, { fullPath, iids });
+    const out = new Map;
+    for (const node of data.project?.workItems?.nodes ?? [])
+      out.set(node.iid, node.id);
+    return out;
+  }
+  async getTaskTypeGid() {
+    if (this.taskTypeGid)
+      return this.taskTypeGid;
+    const fullPath = await this.getFullPath();
+    const data = await this.client.graphql(WORK_ITEM_TYPES_QUERY, { fullPath });
+    const task = data.project?.workItemTypes?.nodes.find((t) => t.name === "Task");
+    if (!task)
+      throw new UsageError("project has no Task work-item type");
+    this.taskTypeGid = task.id;
+    return task.id;
+  }
+  async create(draft) {
+    if (draft.parent) {
+      const gids = await this.resolveGids([draft.parent]);
+      const parentGid = gids.get(draft.parent);
+      if (!parentGid)
+        throw new DomainError(`parent #${draft.parent} not found`);
+      const fullPath = await this.getFullPath();
+      const data = await this.client.graphql(WORK_ITEM_CREATE_MUTATION, {
+        input: {
+          namespacePath: fullPath,
+          title: draft.title,
+          description: draft.description ?? "",
+          workItemTypeId: await this.getTaskTypeGid(),
+          hierarchyWidget: { parentId: parentGid }
+        }
+      });
+      if (data.workItemCreate.errors.length || !data.workItemCreate.workItem) {
+        throw new DomainError(`workItemCreate: ${data.workItemCreate.errors.join("; ")}`);
+      }
+      const iid = data.workItemCreate.workItem.iid;
+      if (draft.labels?.length || draft.milestone) {
+        await this.client.rest(`projects/${this.projectRef}/issues/${iid}`, {
+          method: "PUT",
+          body: {
+            ...draft.labels?.length ? { add_labels: draft.labels.join(",") } : {},
+            ...draft.milestone ? { milestone_id: draft.milestone } : {}
+          }
+        });
+      }
+      const created = await this.get(iid);
+      return { ...created, parent: draft.parent };
+    }
+    const issue = await this.client.rest(`projects/${this.projectRef}/issues`, {
+      method: "POST",
+      body: {
+        title: draft.title,
+        description: draft.description ?? "",
+        ...draft.labels?.length ? { labels: draft.labels.join(",") } : {},
+        ...draft.milestone ? { milestone_id: draft.milestone } : {},
+        ...draft.epicId ? { epic_id: Number(draft.epicId) } : {}
+      }
+    });
+    return mapIssue(issue);
+  }
+  async update(id, patch) {
+    const body = {};
+    if (patch.assigneeIds) {
+      body.assignee_ids = patch.assigneeIds.length ? patch.assigneeIds.map(Number) : [0];
+    }
+    if (patch.addLabels?.length)
+      body.add_labels = patch.addLabels.join(",");
+    if (patch.removeLabels?.length)
+      body.remove_labels = patch.removeLabels.join(",");
+    if (patch.title !== undefined)
+      body.title = patch.title;
+    if (patch.description !== undefined)
+      body.description = patch.description;
+    if (Object.keys(body).length === 0)
+      return;
+    await this.client.rest(`projects/${this.projectRef}/issues/${id}`, { method: "PUT", body });
+  }
+  async transition(id, to) {
+    await this.client.rest(`projects/${this.projectRef}/issues/${id}`, {
+      method: "PUT",
+      body: { state_event: to === "closed" ? "close" : "reopen" }
+    });
+  }
+  async link(blocker, blocked) {
+    if (this.nativeBlocking) {
+      await this.client.rest(`projects/${this.projectRef}/issues/${blocker}/links`, {
+        method: "POST",
+        body: {
+          target_project_id: decodeURIComponent(this.projectRef),
+          target_issue_iid: Number(blocked),
+          link_type: "blocks"
+        }
+      });
+      return;
+    }
+    const item = await this.get(blocked);
+    await this.update(blocked, {
+      description: upsertBlockedByTrailer(item.description, [blocker])
+    });
+  }
+  async setParent(child, parent) {
+    const wanted = parent === null ? [child] : [child, parent];
+    const gids = await this.resolveGids(wanted);
+    const childGid = gids.get(child);
+    if (!childGid)
+      throw new DomainError(`#${child} not found`);
+    let parentGid = null;
+    if (parent !== null) {
+      parentGid = gids.get(parent) ?? null;
+      if (!parentGid)
+        throw new DomainError(`parent #${parent} not found`);
+    }
+    const data = await this.client.graphql(WORK_ITEM_UPDATE_MUTATION, { input: { id: childGid, hierarchyWidget: { parentId: parentGid } } });
+    if (data.workItemUpdate.errors.length) {
+      throw new DomainError(`workItemUpdate: ${data.workItemUpdate.errors.join("; ")}`);
+    }
+  }
+  async comment(id, body) {
+    await this.client.rest(`projects/${this.projectRef}/issues/${id}/notes`, {
+      method: "POST",
+      body: { body }
+    });
+  }
+  async listComments(id) {
+    const notes = await this.client.rest(`projects/${this.projectRef}/issues/${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 searchRemote(q) {
+    const state = q.state ?? "all";
+    const issues = await this.client.rest(`projects/${this.projectRef}/issues`, {
+      query: {
+        ...q.text ? { search: q.text, in: "title,description" } : {},
+        ...q.assignee ? { assignee_username: q.assignee.replace(/^@/, "") } : {},
+        ...q.author ? { author_username: q.author.replace(/^@/, "") } : {},
+        ...q.label ? { labels: q.label } : {},
+        ...state !== "all" ? { state: state === "open" ? "opened" : "closed" } : {}
+      },
+      paginate: true
+    });
+    return issues.map((issue) => mapIssue(issue));
+  }
+  async resolveUsers(query) {
+    const users = await this.client.rest(`projects/${this.projectRef}/users`, {
+      query: { search: query },
+      paginate: true
+    });
+    return users.map(mapUser);
+  }
+  async probeProject() {
+    const project = await this.client.rest(`projects/${this.projectRef}`);
+    return { name: project.name_with_namespace, webUrl: project.web_url };
+  }
+  async probeGraphql() {
+    await this.getTaskTypeGid();
+    return true;
+  }
+}
+
+// src/cache/db.ts
+import { Database } from "bun:sqlite";
+import { mkdirSync } from "fs";
+import { dirname } from "path";
+var SCHEMA = `
+CREATE TABLE IF NOT EXISTS items (
+  id          TEXT PRIMARY KEY,
+  provider    TEXT NOT NULL,
+  kind        TEXT NOT NULL,
+  title       TEXT NOT NULL,
+  state       TEXT NOT NULL,
+  labels      TEXT NOT NULL,
+  assignees   TEXT NOT NULL,
+  author      TEXT,
+  parent      TEXT,
+  url         TEXT NOT NULL,
+  description TEXT NOT NULL,
+  updated_at  TEXT NOT NULL,
+  raw         TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_items_parent ON items(parent);
+CREATE TABLE IF NOT EXISTS links (
+  blocker TEXT NOT NULL,
+  blocked TEXT NOT NULL,
+  PRIMARY KEY (blocker, blocked)
+);
+CREATE INDEX IF NOT EXISTS idx_links_blocked ON links(blocked);
+CREATE TABLE IF NOT EXISTS meta (
+  key   TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+CREATE VIRTUAL TABLE IF NOT EXISTS items_fts USING fts5(id UNINDEXED, title, description);
+`;
+
+class Cache {
+  db;
+  constructor(path) {
+    if (path !== ":memory:")
+      mkdirSync(dirname(path), { recursive: true });
+    this.db = new Database(path);
+    this.db.exec(SCHEMA);
+  }
+  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 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));
+        for (const blocker of item.blockedBy)
+          insertLink.run(blocker, item.id);
+        insertFts.run(item.id, item.title, item.description);
+      }
+    });
+    tx();
+  }
+  rowToItem(row) {
+    return {
+      id: row.id,
+      kind: row.kind,
+      title: row.title,
+      state: row.state,
+      labels: JSON.parse(row.labels),
+      assignees: JSON.parse(row.assignees),
+      author: row.author ? JSON.parse(row.author) : null,
+      parent: row.parent,
+      blockedBy: this.blockersOf(row.id),
+      url: row.url,
+      description: row.description,
+      updatedAt: row.updated_at
+    };
+  }
+  blockersOf(id) {
+    return this.db.query("SELECT blocker FROM links WHERE blocked = ? ORDER BY blocker").all(id).map((r) => r.blocker);
+  }
+  getItem(id) {
+    const row = this.db.query("SELECT * FROM items WHERE id = ?").get(id);
+    return row ? this.rowToItem(row) : null;
+  }
+  getRaw(id) {
+    const row = this.db.query("SELECT raw FROM items WHERE id = ?").get(id);
+    return row?.raw ? JSON.parse(row.raw) : null;
+  }
+  allItems() {
+    return this.db.query("SELECT * FROM items ORDER BY CAST(id AS INTEGER), id").all().map((row) => this.rowToItem(row));
+  }
+  childrenOf(parent) {
+    return this.db.query("SELECT * FROM items WHERE parent = ? ORDER BY CAST(id AS INTEGER), id").all(parent).map((row) => this.rowToItem(row));
+  }
+  count() {
+    const row = this.db.query("SELECT COUNT(*) AS n FROM items").get();
+    return row?.n ?? 0;
+  }
+  searchText(text) {
+    const query = text.split(/\s+/).filter(Boolean).map((t) => `"${t.replaceAll('"', '""')}"`).join(" ");
+    if (!query)
+      return new Set;
+    const rows = this.db.query("SELECT id FROM items_fts WHERE items_fts MATCH ?").all(query);
+    return new Set(rows.map((r) => r.id));
+  }
+  metaGet(key) {
+    const row = this.db.query("SELECT value FROM meta WHERE key = ?").get(key);
+    return row?.value ?? null;
+  }
+  metaSet(key, value) {
+    this.db.prepare("INSERT OR REPLACE INTO meta (key, value) VALUES (?, ?)").run(key, value);
+  }
+  markSynced(nowMs) {
+    this.metaSet("last_sync_at", String(nowMs));
+  }
+  lastSyncAt() {
+    const v = this.metaGet("last_sync_at");
+    return v === null ? null : Number(v);
+  }
+  isStale(nowMs, staleMs) {
+    const last = this.lastSyncAt();
+    return last === null || nowMs - last > staleMs;
+  }
+  close() {
+    this.db.close();
+  }
+}
+
+// src/cache/ignore-guard.ts
+import { appendFileSync, existsSync, readFileSync } from "fs";
+import { dirname as dirname2, join, relative, resolve } from "path";
+function findGitRoot(startDir) {
+  let dir = resolve(startDir);
+  for (;; ) {
+    if (existsSync(join(dir, ".git")))
+      return dir;
+    const parent = dirname2(dir);
+    if (parent === dir)
+      return null;
+    dir = parent;
+  }
+}
+function isGitIgnored(gitRoot, path) {
+  try {
+    const proc = Bun.spawnSync(["git", "-C", gitRoot, "check-ignore", "-q", "--", path], {
+      stdout: "ignore",
+      stderr: "ignore"
+    });
+    if (proc.exitCode === 0)
+      return true;
+    if (proc.exitCode === 1)
+      return false;
+    return null;
+  } catch {
+    return null;
+  }
+}
+function guardCacheIgnored(rootDir, absCachePath) {
+  const cacheDir = dirname2(absCachePath);
+  const gitRoot = findGitRoot(rootDir);
+  if (!gitRoot)
+    return { action: "skipped", detail: "not inside a git repository" };
+  const ignored = isGitIgnored(gitRoot, absCachePath);
+  if (ignored === null)
+    return { action: "skipped", detail: "git not available" };
+  if (ignored)
+    return { action: "ok", detail: "cache path is git-ignored" };
+  const rel = relative(rootDir, cacheDir);
+  if (rel.startsWith("..")) {
+    return {
+      action: "warn",
+      detail: `cache dir ${cacheDir} is outside the config root and NOT git-ignored \u2014 add it to a .gitignore manually`
+    };
+  }
+  const pattern = `${rel.replaceAll("\\", "/")}/`;
+  const gitignorePath = join(rootDir, ".gitignore");
+  const existing = existsSync(gitignorePath) ? readFileSync(gitignorePath, "utf8") : "";
+  const prefix = existing && !existing.endsWith(`
+`) ? `
+` : "";
+  appendFileSync(gitignorePath, `${prefix}${pattern}
+`);
+  return { action: "added", detail: `added "${pattern}" to ${gitignorePath}` };
+}
+
+// src/config.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import { dirname as dirname3, join as join2, resolve as resolve2 } from "path";
+var CONFIG_FILENAME = "tracker.config.json";
+function findConfigFile(startDir) {
+  let dir = resolve2(startDir);
+  for (;; ) {
+    const candidate = join2(dir, CONFIG_FILENAME);
+    if (existsSync2(candidate))
+      return candidate;
+    const parent = dirname3(dir);
+    if (parent === dir)
+      return null;
+    dir = parent;
+  }
+}
+function parseConfig(json, rootDir) {
+  let raw;
+  try {
+    raw = JSON.parse(json);
+  } catch (e) {
+    throw new UsageError(`invalid ${CONFIG_FILENAME}: ${e.message}`);
+  }
+  if (raw.provider !== "gitlab") {
+    throw new UsageError(`unsupported provider "${raw.provider}" (only "gitlab" for now)`);
+  }
+  const g = raw.gitlab ?? {};
+  if (!g.base_url)
+    throw new UsageError("config: gitlab.base_url is required");
+  if (!g.project)
+    throw new UsageError("config: gitlab.project is required");
+  const tokenEnv = g.token_env === undefined ? ["TRACKER_GITLAB_TOKEN"] : Array.isArray(g.token_env) ? g.token_env : [g.token_env];
+  return {
+    provider: "gitlab",
+    gitlab: {
+      base_url: g.base_url.replace(/\/+$/, ""),
+      project: String(g.project),
+      token_env: tokenEnv,
+      native_blocking: g.native_blocking ?? true
+    },
+    labels: { in_progress: raw.labels?.in_progress ?? "status::in-progress" },
+    memory: {
+      enabled: raw.memory?.enabled ?? true,
+      title: raw.memory?.title ?? "\uD83D\uDCCC Project Memory",
+      label: raw.memory?.label ?? "meta::memory"
+    },
+    cache: {
+      path: raw.cache?.path ?? ".tracker/cache.sqlite",
+      stale_minutes: raw.cache?.stale_minutes ?? 15
+    },
+    rootDir
+  };
+}
+function loadConfig(startDir = process.cwd()) {
+  const file = findConfigFile(startDir);
+  if (!file) {
+    throw new UsageError(`no ${CONFIG_FILENAME} found in ${startDir} or any parent directory \u2014 create one (see README) or cd into the project.`);
+  }
+  return parseConfig(readFileSync2(file, "utf8"), dirname3(file));
+}
+function parseDotEnv(text) {
+  const out = {};
+  for (const line of text.split(`
+`)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#"))
+      continue;
+    const eq = trimmed.indexOf("=");
+    if (eq <= 0)
+      continue;
+    const key = trimmed.slice(0, eq).trim();
+    let value = trimmed.slice(eq + 1).trim();
+    if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
+      value = value.slice(1, -1);
+    }
+    out[key] = value;
+  }
+  return out;
+}
+function resolveToken(config, env = process.env) {
+  const dotEnvPath = join2(config.rootDir, ".env");
+  const dotEnv = existsSync2(dotEnvPath) ? parseDotEnv(readFileSync2(dotEnvPath, "utf8")) : {};
+  for (const name of config.gitlab.token_env) {
+    const fromEnv = env[name];
+    if (fromEnv) {
+      registerSecret(fromEnv);
+      return { token: fromEnv, source: `${name} (environment)` };
+    }
+    const fromFile = dotEnv[name];
+    if (fromFile) {
+      registerSecret(fromFile);
+      return { token: fromFile, source: `${name} (.env)` };
+    }
+  }
+  throw new UsageError(`no GitLab token found. Set one of [${config.gitlab.token_env.join(", ")}] ` + `in the environment or in ${dotEnvPath} (gitignored).`);
+}
+
+// src/core/claim.ts
+var CLAIM_MARK = "\uD83D\uDD12 tracker-claim";
+var RELEASE_MARK = "\uD83D\uDD13 tracker-release";
+var CLAIM_TTL_MS = 5 * 60000;
+var SETTLE_MS = 2000;
+function parseClaim(body) {
+  if (!body.startsWith(CLAIM_MARK))
+    return null;
+  const token = body.match(/token=(\S+)/)?.[1];
+  const agent = body.match(/agent=(\S+)/)?.[1];
+  const at = body.match(/at=(\S+)/)?.[1];
+  if (!token || !agent || !at)
+    return null;
+  const ts = Date.parse(at);
+  if (Number.isNaN(ts))
+    return null;
+  return { token, agent, ts };
+}
+function parseRelease(body) {
+  if (!body.startsWith(RELEASE_MARK))
+    return null;
+  return body.match(/token=(\S+)/)?.[1] ?? null;
+}
+function compareCommentIds(a, b) {
+  const na = Number(a);
+  const nb = Number(b);
+  if (Number.isFinite(na) && Number.isFinite(nb))
+    return na - nb;
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+function electWinner(comments, nowMs, ttlMs) {
+  const released = new Set;
+  for (const c of comments) {
+    const token = parseRelease(c.body);
+    if (token)
+      released.add(token);
+  }
+  const live = [];
+  for (const c of comments) {
+    const claim = parseClaim(c.body);
+    if (!claim)
+      continue;
+    if (released.has(claim.token))
+      continue;
+    if (nowMs - claim.ts > ttlMs)
+      continue;
+    live.push({ ...claim, commentId: c.id });
+  }
+  live.sort((a, b) => a.ts - b.ts || compareCommentIds(a.commentId, b.commentId));
+  return live[0] ?? null;
+}
+var realClaimDeps = {
+  now: () => Date.now(),
+  sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+  randomSuffix: () => Math.random().toString(36).slice(2, 10)
+};
+async function claimItem(adapter, id, policy, deps = realClaimDeps) {
+  const ttlMs = policy.ttlMs ?? CLAIM_TTL_MS;
+  const settleMs = policy.settleMs ?? SETTLE_MS;
+  const me = await adapter.whoami();
+  const item = await adapter.get(id);
+  if (item.state !== "open")
+    return { ok: false, id, reason: `#${id} is ${item.state}` };
+  if (item.labels.includes(policy.memoryLabel)) {
+    return { ok: false, id, reason: `#${id} is the memory issue and cannot be claimed` };
+  }
+  if (item.labels.includes(policy.inProgressLabel)) {
+    return {
+      ok: false,
+      id,
+      reason: `#${id} already claimed (${policy.inProgressLabel} label set)`
+    };
+  }
+  if (item.assignees.length > 0) {
+    const who = item.assignees.map((a) => `@${a.username}`).join(", ");
+    return { ok: false, id, reason: `#${id} already assigned to ${who}` };
+  }
+  const token = `${deps.now()}-${deps.randomSuffix()}`;
+  const at = new Date(deps.now()).toISOString();
+  await adapter.comment(id, `${CLAIM_MARK} agent=${me.username} token=${token} at=${at}`);
+  await deps.sleep(settleMs);
+  const comments = await adapter.listComments(id);
+  const winner = electWinner(comments, deps.now(), ttlMs);
+  if (!winner || winner.token !== token) {
+    await adapter.comment(id, `${RELEASE_MARK} token=${token} reason=lost-race`);
+    return {
+      ok: false,
+      id,
+      reason: `#${id} lost race to @${winner?.agent ?? "?"} (token=${winner?.token ?? "?"})`
+    };
+  }
+  await adapter.update(id, { assigneeIds: [me.id], addLabels: [policy.inProgressLabel] });
+  return { ok: true, id, agent: me.username, token };
+}
+async function releaseItem(adapter, id, policy) {
+  const me = await adapter.whoami();
+  await adapter.update(id, { assigneeIds: [], removeLabels: [policy.inProgressLabel] });
+  const comments = await adapter.listComments(id);
+  const released = new Set;
+  for (const c of comments) {
+    const token = parseRelease(c.body);
+    if (token)
+      released.add(token);
+  }
+  let cleared = 0;
+  for (const c of comments) {
+    const claim = parseClaim(c.body);
+    if (!claim || released.has(claim.token))
+      continue;
+    await adapter.comment(id, `${RELEASE_MARK} token=${claim.token} agent=${me.username} reason=manual-release`);
+    cleared++;
+  }
+  return { id, cleared };
+}
+
+// src/core/ids.ts
+function normalizeId(input) {
+  const id = (input ?? "").trim().replace(/^#/, "");
+  if (!id)
+    throw new UsageError("an item id is required (e.g. 42 or #42)");
+  return id;
+}
+
+// src/core/memory.ts
+var MEM_MARK = "\uD83D\uDCCC MEMORY";
+var FORGET_MARK = "\uD83D\uDDD1 FORGET";
+function parseMemory(body) {
+  if (!body.startsWith(MEM_MARK))
+    return null;
+  const m = body.match(/^\S+\s+\S+\s+key=(\S+)\s+([\s\S]*)$/);
+  if (!m)
+    return null;
+  return { key: m[1], text: m[2].trim() };
+}
+function parseForget(body) {
+  if (!body.startsWith(FORGET_MARK))
+    return null;
+  return body.match(/key=(\S+)/)?.[1] ?? null;
+}
+function resolveMemories(comments, filter) {
+  const forgotten = new Set;
+  for (const c of comments) {
+    const key = parseForget(c.body);
+    if (key)
+      forgotten.add(key);
+  }
+  const latest = new Map;
+  for (const c of comments) {
+    const m = parseMemory(c.body);
+    if (!m || forgotten.has(m.key))
+      continue;
+    latest.set(m.key, { key: m.key, text: m.text, ts: c.createdAt });
+  }
+  const all = [...latest.values()];
+  if (!filter)
+    return all;
+  const f = filter.toLowerCase();
+  return all.filter((m) => m.key.toLowerCase().includes(f) || m.text.toLowerCase().includes(f));
+}
+async function ensureMemoryItem(adapter, cache, policy) {
+  const cached = cache.metaGet("memory_id");
+  if (cached)
+    return cached;
+  let found = cache.allItems().find((i) => i.title === policy.title && i.state === "open");
+  if (!found && adapter.capabilities().serverSearch) {
+    const hits = await adapter.searchRemote({ text: policy.title, state: "open" });
+    found = hits.find((i) => i.title === policy.title);
+  }
+  const item = found ?? await adapter.create({
+    title: policy.title,
+    description: "Persistent project memories. Each note is a memory keyed by `key=<name>`. Do not close.",
+    labels: [policy.label]
+  });
+  cache.metaSet("memory_id", item.id);
+  return item.id;
+}
+async function remember(adapter, cache, policy, key, text) {
+  if (/\s/.test(key))
+    throw new DomainError("memory key cannot contain whitespace");
+  const id = await ensureMemoryItem(adapter, cache, policy);
+  await adapter.comment(id, `${MEM_MARK} key=${key} ${text}`);
+  return id;
+}
+async function forget(adapter, cache, policy, key) {
+  const id = await ensureMemoryItem(adapter, cache, policy);
+  await adapter.comment(id, `${FORGET_MARK} key=${key}`);
+  return id;
+}
+async function listMemories(adapter, cache, policy, filter) {
+  const id = await ensureMemoryItem(adapter, cache, policy);
+  const comments = await adapter.listComments(id);
+  return resolveMemories(comments, filter);
+}
+
+// src/core/ready.ts
+function computeReady(items, policy) {
+  const stateById = new Map(items.map((i) => [i.id, i.state]));
+  return items.filter((item) => {
+    if (item.state !== "open")
+      return false;
+    if (policy.parent && item.parent !== policy.parent)
+      return false;
+    if (item.assignees.length > 0)
+      return false;
+    if (item.labels.includes(policy.inProgressLabel))
+      return false;
+    if (item.labels.includes(policy.memoryLabel))
+      return false;
+    return item.blockedBy.every((blocker) => stateById.get(blocker) !== "open");
+  });
+}
+function computeEpicStatus(parent, children) {
+  if (children.length === 0)
+    return null;
+  const closed = children.filter((c) => c.state === "closed").length;
+  return {
+    parent,
+    total: children.length,
+    open: children.length - closed,
+    closed,
+    pctClosed: Math.round(closed / children.length * 100)
+  };
+}
+
+// src/core/search.ts
+var normalizeUser = (u) => u.replace(/^@/, "").toLowerCase();
+function searchLocal(cache, q) {
+  let items = cache.allItems();
+  if (q.text?.trim()) {
+    const ids = cache.searchText(q.text);
+    items = items.filter((i) => ids.has(i.id));
+  }
+  const state = q.state ?? "all";
+  if (state !== "all")
+    items = items.filter((i) => i.state === state);
+  if (q.parent)
+    items = items.filter((i) => i.parent === q.parent);
+  if (q.label)
+    items = items.filter((i) => i.labels.includes(q.label));
+  if (q.assignee) {
+    const want = normalizeUser(q.assignee);
+    items = items.filter((i) => i.assignees.some((a) => a.username.toLowerCase() === want));
+  }
+  if (q.author) {
+    const want = normalizeUser(q.author);
+    items = items.filter((i) => i.author !== null && i.author.username.toLowerCase() === want);
+  }
+  return items;
+}
+
+// src/core/sync.ts
+async function syncCache(adapter, cache, nowMs = Date.now()) {
+  const items = await adapter.fetchAll();
+  cache.replaceAll(items, adapter.provider);
+  cache.markSynced(nowMs);
+  return { count: items.length };
+}
+async function ensureFresh(adapter, cache, staleMs, nowMs = Date.now(), onSync) {
+  if (!cache.isStale(nowMs, staleMs))
+    return false;
+  onSync?.();
+  await syncCache(adapter, cache, nowMs);
+  return true;
+}
+
+// src/cli/help.ts
+var HELP = `tracker \u2014 multi-backend issue tracking for humans and AI agents
+
+usage: tracker <command> [args]
+
+read commands (local cache, auto-sync when stale; all accept --json):
+  sync                       refresh the local cache from the provider
+  ready [--parent <id>]      open + unblocked + unassigned + not in-progress
+  show <id>                  full detail for one item
+  children <id>              direct children of an item
+  epic-status <id>           closed/total progress over an item's children
+  search [text] [filters]    full-text + filters; --remote for server-side search
+  comments <id>              list an item's comments (oldest first)
+  users <query>              resolve usernames/names to user ids
+  whoami                     the authenticated user
+  memories [filter]          list project memories
+  doctor                     verify config, token, connectivity, capabilities
+
+write commands:
+  create -t <title> [-d <desc>] [--parent <id>] [--epic <id>] [-l a,b]
+         [--blocked-by 1,2] [-m <milestone>] [--json]
+  claim <id>                 race-safe claim (assigns you + in-progress label)
+  release <id>               clear assignee/label, tombstone live claim tokens
+  close <id> [--reason <text>]
+  comment <id> <text>        post a comment on an item
+  dep <id> --blocked-by <other> | --blocks <other>
+  parent <child-id> <parent-id>
+  remember <key> <text>      store a project memory (key has no whitespace)
+  forget <key>               hide a memory key
+
+search filters:
+  --assignee <user> --author <user> --label <l> --state open|closed|all
+  --parent <id> --remote     (text query optional when any filter is given)
+
+examples:
+  tracker ready --parent 12 --json
+  tracker search --assignee mehmet           # works with no text query
+  tracker search "login bug" --state open
+  tracker create -t "Fix login" --parent 12 --blocked-by 7
+  tracker claim 42 && echo mine || echo taken
+  tracker close 42 --reason "fixed in MR !17"
+
+exit codes: 0 ok \xB7 2 domain failure (lost race, refused claim, not found) \xB7 1 usage/config error`;
+var PER_COMMAND = {
+  sync: `usage: tracker sync
+
+Full refresh of the local cache (issues + hierarchy + dependency links).`,
+  ready: `usage: tracker ready [--parent <id>] [--json]
+
+Items that are open, not blocked by any open item, unassigned, not in-progress,
+and not the memory issue.
+
+examples:
+  tracker ready
+  tracker ready --parent 12 --json`,
+  show: `usage: tracker show <id> [--json]
+
+example: tracker show 42`,
+  children: `usage: tracker children <id> [--json]
+
+example: tracker children 12`,
+  "epic-status": `usage: tracker epic-status <id> [--json]
+
+example: tracker epic-status 12`,
+  claim: `usage: tracker claim <id>
+
+Race-safe claim: posts a claim note, waits a settle window, re-reads all notes,
+oldest live claim wins. Loser exits 2. Winner gets assigned + in-progress label.
+
+example: tracker claim 42 && start-work || pick-another`,
+  release: `usage: tracker release <id>
+
+Clears assignee + in-progress label and tombstones all live claim tokens.`,
+  create: `usage: tracker create -t <title> [-d <desc>] [--parent <id>] [--epic <id>]
+                      [-l label1,label2] [--blocked-by <id1,id2>] [-m <milestone>] [--json]
+
+examples:
+  tracker create -t "Ship login" -d "OAuth via Keycloak" -l backend,auth
+  tracker create -t "Subtask" --parent 12 --blocked-by 7,9`,
+  close: `usage: tracker close <id> [--reason <text>]
+
+example: tracker close 42 --reason "fixed in MR !17"`,
+  comment: `usage: tracker comment <id> <text>
+
+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"`,
+  comments: `usage: tracker comments <id> [--json]
+
+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`,
+  dep: `usage: tracker dep <id> --blocked-by <other> | --blocks <other>
+
+examples:
+  tracker dep 42 --blocked-by 7    # 7 blocks 42
+  tracker dep 42 --blocks 50       # 42 blocks 50`,
+  parent: `usage: tracker parent <child-id> <parent-id>
+
+example: tracker parent 42 12`,
+  remember: `usage: tracker remember <key> <text>
+
+example: tracker remember deploy-cmd "bun run deploy:prod"`,
+  forget: `usage: tracker forget <key>
+
+example: tracker forget deploy-cmd`,
+  memories: `usage: tracker memories [filter] [--json]
+
+example: tracker memories deploy`,
+  search: `usage: tracker search [text] [--assignee <user>] [--author <user>] [--label <l>]
+                      [--state open|closed|all] [--parent <id>] [--remote] [--json]
+
+Local-first: full-text (FTS5) over cached title+description plus structured
+filters. Text is optional when at least one filter is given. --remote runs the
+provider's server-side search instead (fresher, slower, no --parent).
+
+examples:
+  tracker search --assignee mehmet
+  tracker search --state closed                # state alone is a valid filter
+  tracker search "payment timeout" --label backend --state open
+  tracker search checkout --remote --json`,
+  users: `usage: tracker users <query> [--json]
+
+example: tracker users mehmet`,
+  whoami: "usage: tracker whoami [--json]",
+  doctor: `usage: tracker doctor [--json]
+
+Verifies config, token, REST/GraphQL connectivity, capabilities, cache.`
+};
+function commandHelp(cmd) {
+  return PER_COMMAND[cmd] ?? HELP;
+}
+
+// src/cli/output.ts
+function itemToJson(item) {
+  const { raw: _raw, ...publicItem } = item;
+  return publicItem;
+}
+function printJson(value) {
+  console.log(JSON.stringify(value, null, 2));
+}
+var formatUsers = (users) => users.map((u) => `@${u.username}`).join(",");
+function printItemLines(items) {
+  for (const item of items) {
+    const parts = [`#${item.id}`, `[${item.state}]`, item.title];
+    if (item.assignees.length)
+      parts.push(`(${formatUsers(item.assignees)})`);
+    if (item.labels.length)
+      parts.push(`{${item.labels.join(", ")}}`);
+    console.log(parts.join("\t"));
+  }
+}
+function printItemDetail(item, blocks) {
+  console.log(`#${item.id}	${item.title}	[${item.state}]`);
+  console.log(`url:        ${item.url}`);
+  console.log(`kind:       ${item.kind}`);
+  console.log(`labels:     ${item.labels.join(", ") || "-"}`);
+  console.log(`assignees:  ${formatUsers(item.assignees) || "-"}`);
+  console.log(`author:     ${item.author ? `@${item.author.username}` : "-"}`);
+  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(", ") || "-"}`);
+  console.log(`updated:    ${item.updatedAt}`);
+  if (item.description) {
+    console.log("---");
+    console.log(item.description);
+  }
+}
+function printUsers(users) {
+  for (const u of users)
+    console.log(`${u.id}	@${u.username}	${u.name ?? ""}`);
+}
+
+// src/cli/index.ts
+function parseArgs(args, spec, aliases = {}) {
+  const flags = new Map;
+  const positionals = [];
+  for (let i = 0;i < args.length; i++) {
+    const arg = args[i];
+    if (!arg.startsWith("-") || arg === "-") {
+      positionals.push(arg);
+      continue;
+    }
+    const name = aliases[arg] ?? arg;
+    const kind = spec[name];
+    if (!kind)
+      throw new UsageError(`unknown flag ${arg} (see tracker help)`);
+    if (kind === "bool") {
+      flags.set(name, true);
+    } else {
+      const value = args[++i];
+      if (value === undefined)
+        throw new UsageError(`flag ${arg} needs a value`);
+      flags.set(name, value);
+    }
+  }
+  return { flags, positionals };
+}
+var str = (p, name) => {
+  const v = p.flags.get(name);
+  return typeof v === "string" ? v : undefined;
+};
+function buildCtx() {
+  const config = loadConfig();
+  const { token } = resolveToken(config);
+  const adapter = new GitLabAdapter({
+    baseUrl: config.gitlab.base_url,
+    project: config.gitlab.project,
+    token,
+    nativeBlocking: config.gitlab.native_blocking
+  });
+  const cachePath = resolve3(config.rootDir, config.cache.path);
+  if (!existsSync3(cachePath)) {
+    const guard = guardCacheIgnored(config.rootDir, cachePath);
+    if (guard.action === "added" || guard.action === "warn")
+      console.error(`(${guard.detail})`);
+  }
+  const cache = new Cache(cachePath);
+  return { config, cache, adapter };
+}
+var claimPolicy = (config) => ({
+  inProgressLabel: config.labels.in_progress,
+  memoryLabel: config.memory.label
+});
+async function freshen(ctx) {
+  await ensureFresh(ctx.adapter, ctx.cache, ctx.config.cache.stale_minutes * 60000, Date.now(), () => console.error("(cache stale, syncing...)"));
+}
+var invalidate = (ctx) => ctx.cache.metaSet("last_sync_at", "0");
+var memoryPolicy = (ctx) => {
+  if (!ctx.config.memory.enabled) {
+    throw new UsageError("the memory feature is disabled in tracker.config.json");
+  }
+  return { title: ctx.config.memory.title, label: ctx.config.memory.label };
+};
+async function cmdSync(ctx) {
+  const t0 = performance.now();
+  const { count } = await syncCache(ctx.adapter, ctx.cache);
+  const ms = Math.round(performance.now() - t0);
+  console.log(`synced ${count} items in ${ms}ms \u2192 ${resolve3(ctx.config.rootDir, ctx.config.cache.path)}`);
+}
+async function cmdReady(ctx, args) {
+  await freshen(ctx);
+  const items = computeReady(ctx.cache.allItems(), {
+    ...claimPolicy(ctx.config),
+    parent: str(args, "--parent") ? normalizeId(str(args, "--parent")) : null
+  });
+  if (args.flags.get("--json"))
+    return printJson(items.map(itemToJson));
+  if (items.length === 0)
+    return console.error("(no ready items)");
+  printItemLines(items);
+}
+async function cmdShow(ctx, args) {
+  await freshen(ctx);
+  const id = normalizeId(args.positionals[0]);
+  const item = ctx.cache.getItem(id);
+  if (!item)
+    throw new DomainError(`#${id} not found in cache (try: tracker sync)`);
+  const blocks = ctx.cache.allItems().filter((i) => i.blockedBy.includes(id)).map((i) => i.id);
+  if (args.flags.get("--json"))
+    return printJson({ ...itemToJson(item), blocks });
+  printItemDetail(item, blocks);
+}
+async function cmdChildren(ctx, args) {
+  await freshen(ctx);
+  const id = normalizeId(args.positionals[0]);
+  const children = ctx.cache.childrenOf(id);
+  if (args.flags.get("--json"))
+    return printJson(children.map(itemToJson));
+  if (children.length === 0)
+    return console.error(`(no children of #${id})`);
+  printItemLines(children);
+}
+async function cmdEpicStatus(ctx, args) {
+  await freshen(ctx);
+  const id = normalizeId(args.positionals[0]);
+  const status = computeEpicStatus(id, ctx.cache.childrenOf(id));
+  if (args.flags.get("--json")) {
+    return printJson(status ?? { parent: id, total: 0, open: 0, closed: 0, pctClosed: 0 });
+  }
+  if (!status)
+    return console.error(`(no children of #${id})`);
+  console.log(`#${status.parent}	${status.closed}/${status.total} closed (${status.pctClosed}%)	open=${status.open}`);
+}
+async function cmdClaim(ctx, args) {
+  const id = normalizeId(args.positionals[0]);
+  const result = await claimItem(ctx.adapter, id, claimPolicy(ctx.config));
+  invalidate(ctx);
+  if (!result.ok)
+    throw new DomainError(result.reason);
+  console.log(`#${id} claimed by @${result.agent} (token=${result.token})`);
+}
+async function cmdRelease(ctx, args) {
+  const id = normalizeId(args.positionals[0]);
+  const { cleared } = await releaseItem(ctx.adapter, id, claimPolicy(ctx.config));
+  invalidate(ctx);
+  console.log(`#${id} released (${cleared} live claim${cleared === 1 ? "" : "s"} cleared)`);
+}
+async function cmdCreate(ctx, args) {
+  const title = str(args, "--title");
+  if (!title)
+    throw new UsageError(commandHelp("create"));
+  const parent = str(args, "--parent");
+  const item = await ctx.adapter.create({
+    title,
+    description: str(args, "--description") ?? "",
+    parent: parent ? normalizeId(parent) : null,
+    labels: str(args, "--label")?.split(",").map((s) => s.trim()).filter(Boolean),
+    milestone: str(args, "--milestone"),
+    epicId: str(args, "--epic")
+  });
+  const blockers = (str(args, "--blocked-by") ?? "").split(",").map((s) => s.trim()).filter(Boolean).map(normalizeId);
+  for (const blocker of blockers)
+    await ctx.adapter.link(blocker, item.id);
+  invalidate(ctx);
+  const withDeps = { ...item, blockedBy: [...new Set([...item.blockedBy, ...blockers])] };
+  if (args.flags.get("--json"))
+    return printJson(itemToJson(withDeps));
+  console.log(`#${item.id}	${item.title}	${item.url}`);
+}
+async function cmdClose(ctx, args) {
+  const id = normalizeId(args.positionals[0]);
+  const reason = str(args, "--reason");
+  if (reason)
+    await ctx.adapter.comment(id, `closed: ${reason}`);
+  await ctx.adapter.update(id, {
+    assigneeIds: [],
+    removeLabels: [ctx.config.labels.in_progress]
+  });
+  await ctx.adapter.transition(id, "closed");
+  invalidate(ctx);
+  console.log(`#${id} closed`);
+}
+async function cmdDep(ctx, args) {
+  const id = normalizeId(args.positionals[0]);
+  const blockedBy = str(args, "--blocked-by");
+  const blocks = str(args, "--blocks");
+  if (blockedBy === undefined === (blocks === undefined)) {
+    throw new UsageError(commandHelp("dep"));
+  }
+  const [blocker, blocked] = blockedBy ? [normalizeId(blockedBy), id] : [id, normalizeId(blocks)];
+  await ctx.adapter.link(blocker, blocked);
+  invalidate(ctx);
+  console.log(`#${blocker} blocks #${blocked}`);
+}
+async function cmdParent(ctx, args) {
+  const child = normalizeId(args.positionals[0]);
+  const parent = normalizeId(args.positionals[1]);
+  await ctx.adapter.setParent(child, parent);
+  invalidate(ctx);
+  console.log(`#${child} parent=#${parent}`);
+}
+async function cmdRemember(ctx, args) {
+  const [key, ...text] = args.positionals;
+  if (!key || text.length === 0)
+    throw new UsageError(commandHelp("remember"));
+  const id = await remember(ctx.adapter, ctx.cache, memoryPolicy(ctx), key, text.join(" "));
+  console.log(`remembered ${key} on #${id}`);
+}
+async function cmdForget(ctx, args) {
+  const key = args.positionals[0];
+  if (!key)
+    throw new UsageError(commandHelp("forget"));
+  await forget(ctx.adapter, ctx.cache, memoryPolicy(ctx), key);
+  console.log(`forgot ${key}`);
+}
+async function cmdMemories(ctx, args) {
+  const memories = await listMemories(ctx.adapter, ctx.cache, memoryPolicy(ctx), args.positionals[0]);
+  if (args.flags.get("--json"))
+    return printJson(memories);
+  if (memories.length === 0)
+    return console.error("(no memories)");
+  for (const m of memories)
+    console.log(`${m.key}	${m.ts}	${m.text}`);
+}
+async function cmdComment(ctx, args) {
+  const [idArg, ...textParts] = args.positionals;
+  const id = normalizeId(idArg);
+  const body = textParts.join(" ").trim();
+  if (!body)
+    throw new UsageError(commandHelp("comment"));
+  await ctx.adapter.comment(id, body);
+  console.log(`commented on #${id}`);
+}
+async function cmdComments(ctx, args) {
+  const id = normalizeId(args.positionals[0]);
+  const comments = await ctx.adapter.listComments(id);
+  if (args.flags.get("--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("");
+  }
+}
+async function cmdSearch(ctx, args) {
+  const query = {
+    text: args.positionals.join(" ") || undefined,
+    assignee: str(args, "--assignee"),
+    author: str(args, "--author"),
+    label: str(args, "--label"),
+    state: str(args, "--state") ?? "all",
+    parent: str(args, "--parent") ? normalizeId(str(args, "--parent")) : undefined
+  };
+  if (!["open", "closed", "all"].includes(query.state)) {
+    throw new UsageError("--state must be open, closed or all");
+  }
+  const hasFilter = query.assignee || query.author || query.label || query.parent || args.flags.has("--state");
+  if (!query.text && !hasFilter) {
+    throw new UsageError(commandHelp("search"));
+  }
+  let items;
+  if (args.flags.get("--remote")) {
+    if (query.parent)
+      throw new UsageError("--parent is local-only (remote search cannot filter by parent)");
+    items = await ctx.adapter.searchRemote(query);
+  } else {
+    await freshen(ctx);
+    items = searchLocal(ctx.cache, query);
+  }
+  if (args.flags.get("--json"))
+    return printJson(items.map(itemToJson));
+  if (items.length === 0)
+    return console.error("(no matches)");
+  printItemLines(items);
+}
+async function cmdUsers(ctx, args) {
+  const query = args.positionals.join(" ");
+  if (!query)
+    throw new UsageError(commandHelp("users"));
+  const users = await ctx.adapter.resolveUsers(query);
+  if (args.flags.get("--json"))
+    return printJson(users);
+  if (users.length === 0)
+    return console.error("(no users matched)");
+  printUsers(users);
+}
+async function cmdWhoami(ctx, args) {
+  const me = await ctx.adapter.whoami();
+  if (args.flags.get("--json"))
+    return printJson(me);
+  console.log(`@${me.username} (id=${me.id})${me.name ? ` \u2014 ${me.name}` : ""}`);
+}
+async function cmdDoctor(args) {
+  const checks = [];
+  let config = null;
+  try {
+    config = loadConfig();
+    checks.push({ name: "config", status: "ok", detail: `${config.rootDir}/tracker.config.json` });
+  } catch (e) {
+    checks.push({
+      name: "config",
+      status: "fail",
+      detail: e.message,
+      fix: "create tracker.config.json (see README) in the project root"
+    });
+  }
+  let ctx = null;
+  if (config) {
+    try {
+      const { source } = resolveToken(config);
+      checks.push({ name: "token", status: "ok", detail: `found via ${source}` });
+      ctx = buildCtx();
+    } catch (e) {
+      checks.push({
+        name: "token",
+        status: "fail",
+        detail: e.message,
+        fix: `export ${config.gitlab.token_env[0]} or add it to ${config.rootDir}/.env`
+      });
+    }
+  }
+  if (ctx) {
+    try {
+      const me = await ctx.adapter.whoami();
+      checks.push({ name: "auth", status: "ok", detail: `authenticated as @${me.username}` });
+    } catch (e) {
+      checks.push({
+        name: "auth",
+        status: "fail",
+        detail: e.message,
+        fix: "check the token's validity and `api` scope, and the base_url"
+      });
+    }
+    try {
+      const project = await ctx.adapter.probeProject();
+      checks.push({ name: "project", status: "ok", detail: project.name });
+    } catch (e) {
+      checks.push({
+        name: "project",
+        status: "fail",
+        detail: e.message,
+        fix: `check gitlab.project ("${config?.gitlab.project}") and that the token can read it`
+      });
+    }
+    try {
+      await ctx.adapter.probeGraphql();
+      checks.push({
+        name: "graphql",
+        status: "ok",
+        detail: "work-item API reachable (Task type found)"
+      });
+    } catch (e) {
+      checks.push({
+        name: "graphql",
+        status: "fail",
+        detail: e.message,
+        fix: "hierarchy commands (create --parent, parent) need the GraphQL work-item API"
+      });
+    }
+    checks.push({
+      name: "blocking-links",
+      status: "ok",
+      detail: `native_blocking=${config?.gitlab.native_blocking} (configured; tier is not verifiable without mutating). Fallback: Tracker-Blocked-By description trailers.`
+    });
+    const last = ctx.cache.lastSyncAt();
+    checks.push({
+      name: "cache",
+      status: "ok",
+      detail: last ? `${ctx.cache.count()} items, synced ${Math.round((Date.now() - last) / 60000)}m ago` : "empty (run: tracker sync)"
+    });
+    const cachePath = resolve3(config.rootDir, config.cache.path);
+    const gitRoot = findGitRoot(config.rootDir);
+    if (gitRoot) {
+      const ignored = isGitIgnored(gitRoot, cachePath);
+      checks.push({
+        name: "cache-ignored",
+        status: ignored === false ? "warn" : "ok",
+        detail: ignored === null ? "git not available, cannot verify" : ignored ? "cache path is git-ignored" : "cache path is NOT git-ignored",
+        ...ignored === false ? { fix: `add "${config.cache.path.replace(/\/[^/]*$/, "")}/" to ${gitRoot}/.gitignore` } : {}
+      });
+    }
+  }
+  const failed = checks.some((c) => c.status === "fail");
+  if (args.flags.get("--json")) {
+    printJson({ ok: !failed, checks });
+  } else {
+    for (const c of checks) {
+      const icon = c.status === "ok" ? "\u2713" : c.status === "warn" ? "!" : "\u2717";
+      console.log(`${icon} ${c.name.padEnd(15)} ${c.detail}`);
+      if (c.fix && c.status !== "ok")
+        console.log(`  fix: ${c.fix}`);
+    }
+    console.log(failed ? `
+problems found.` : `
+all good.`);
+  }
+  return failed ? 1 : 0;
+}
+var VALUE_FLAGS = {
+  ready: { "--parent": "value", "--json": "bool" },
+  show: { "--json": "bool" },
+  children: { "--json": "bool" },
+  "epic-status": { "--json": "bool" },
+  create: {
+    "--title": "value",
+    "--description": "value",
+    "--parent": "value",
+    "--epic": "value",
+    "--label": "value",
+    "--blocked-by": "value",
+    "--milestone": "value",
+    "--json": "bool"
+  },
+  close: { "--reason": "value" },
+  dep: { "--blocked-by": "value", "--blocks": "value" },
+  search: {
+    "--assignee": "value",
+    "--author": "value",
+    "--label": "value",
+    "--state": "value",
+    "--parent": "value",
+    "--remote": "bool",
+    "--json": "bool"
+  },
+  users: { "--json": "bool" },
+  whoami: { "--json": "bool" },
+  doctor: { "--json": "bool" },
+  memories: { "--json": "bool" },
+  comment: {},
+  comments: { "--json": "bool" },
+  sync: {},
+  claim: {},
+  release: {},
+  parent: {},
+  remember: {},
+  forget: {}
+};
+var ALIASES = {
+  create: {
+    "-t": "--title",
+    "-d": "--description",
+    "-l": "--label",
+    "--labels": "--label",
+    "-m": "--milestone"
+  },
+  close: { "-r": "--reason" }
+};
+async function run(argv) {
+  const [cmd, ...rest] = argv;
+  if (!cmd || cmd === "help" || cmd === "--help" || cmd === "-h") {
+    console.log(HELP);
+    return cmd ? 0 : 1;
+  }
+  const spec = VALUE_FLAGS[cmd];
+  if (!spec) {
+    console.error(`unknown command: ${cmd}
+
+${HELP}`);
+    return 1;
+  }
+  if (rest.includes("--help") || rest.includes("-h")) {
+    console.log(commandHelp(cmd));
+    return 0;
+  }
+  const args = parseArgs(rest, spec, ALIASES[cmd] ?? {});
+  if (cmd === "doctor")
+    return cmdDoctor(args);
+  const ctx = buildCtx();
+  const handlers = {
+    sync: cmdSync,
+    ready: cmdReady,
+    show: cmdShow,
+    children: cmdChildren,
+    "epic-status": cmdEpicStatus,
+    claim: cmdClaim,
+    release: cmdRelease,
+    create: cmdCreate,
+    close: cmdClose,
+    dep: cmdDep,
+    parent: cmdParent,
+    remember: cmdRemember,
+    forget: cmdForget,
+    memories: cmdMemories,
+    comment: cmdComment,
+    comments: cmdComments,
+    search: cmdSearch,
+    users: cmdUsers,
+    whoami: cmdWhoami
+  };
+  await handlers[cmd](ctx, args);
+  return 0;
+}
+if (import.meta.main) {
+  try {
+    process.exit(await run(process.argv.slice(2)));
+  } catch (e) {
+    const message = redact(e instanceof Error ? e.message : String(e));
+    console.error(message);
+    process.exit(e instanceof DomainError ? 2 : 1);
+  }
+}
+export {
+  run
+};