@danypops/tickets 0.11.0 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/tickets",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Unified CLI, daemon, and TypeScript library for issue tracking across GitHub, GitLab, and Jira.",
   "type": "module",
   "license": "MIT",

package/src/agent-tools/tickets-vehicle.ts

@@ -34,6 +34,7 @@ const LIMITS = { defaultTimeoutMs: 10_000, maxTimeoutMs: 30_000, maxRequestBytes
 
 const stringProp: LooseObjectProperty = { type: "string" };
 const numberProp: LooseObjectProperty = { type: "number" };
+const booleanProp: LooseObjectProperty = { type: "boolean" };
 
 interface OperationSpec {
   readonly action: TicketOperation;
@@ -71,7 +72,8 @@ const OPERATIONS: readonly OperationSpec[] = [
   },
   {
     action: "issue.list",
-    description: "Lists issues from one backend, optionally filtered.",
+    description:
+      "Lists issues from one backend, optionally filtered. reportedByMe/assignedToMe/reviewRequestedOfMe/qaContactIsMe filter to the caller's own tickets using each backend's own identity (no username needed); set more than one to OR them together. reviewRequestedOfMe is GitHub/GitLab-only (PR/MR reviewer requests); qaContactIsMe is Jira-only (its discovered 'QA Contact' field) -- an unsupported flag on a given backend throws rather than being silently ignored.",
     effect: "read",
     properties: {
       backend: stringProp,
@@ -80,11 +82,25 @@ const OPERATIONS: readonly OperationSpec[] = [
       assignee: stringProp,
       labels: stringArrayProp,
       limit: numberProp,
+      reportedByMe: booleanProp,
+      assignedToMe: booleanProp,
+      reviewRequestedOfMe: booleanProp,
+      qaContactIsMe: booleanProp,
     },
     required: ["backend"],
-    mapInput: ({ backend, project, status, assignee, labels, limit }) => ({
+    mapInput: ({ backend, project, status, assignee, labels, limit, reportedByMe, assignedToMe, reviewRequestedOfMe, qaContactIsMe }) => ({
       backend,
-      filter: definedEntriesOnly({ project, status, assignee, labels, limit }),
+      filter: definedEntriesOnly({
+        project,
+        status,
+        assignee,
+        labels,
+        limit,
+        reportedByMe,
+        assignedToMe,
+        reviewRequestedOfMe,
+        qaContactIsMe,
+      }),
     }),
   },
   {

package/src/cli/index.ts

@@ -47,6 +47,10 @@ program
   .option("--assignee <user>", "filter by assignee")
   .option("--label <label...>", "filter by label(s)")
   .option("--limit <n>", "max results", (v) => Number.parseInt(v, 10))
+  .option("--reported-by-me", "only issues reported/authored by you (Jira reporter / GitHub PR author / GitLab issue author)")
+  .option("--assigned-to-me", "only issues assigned to you")
+  .option("--review-requested-of-me", "only PRs/MRs where you're requested as a reviewer (GitHub/GitLab only)")
+  .option("--qa-contact-is-me", "only issues where you're the QA Contact (Jira only)")
   .action(async (opts) => {
     const filter: ListFilter = {
       project: opts.project,
@@ -54,6 +58,10 @@ program
       assignee: opts.assignee,
       labels: opts.label,
       limit: opts.limit,
+      reportedByMe: opts.reportedByMe,
+      assignedToMe: opts.assignedToMe,
+      reviewRequestedOfMe: opts.reviewRequestedOfMe,
+      qaContactIsMe: opts.qaContactIsMe,
     };
     await withClient((client) => client.call("issue.list", { backend: opts.backend, filter }));
   });

package/src/github/github.ts

@@ -165,19 +165,34 @@ export class GitHubRepository {
   }
 
   async list(filter: ListFilter): Promise<Issue[]> {
+    if (filter.qaContactIsMe) throw new Error('github: "qaContactIsMe" is a Jira-only concept, not supported on the github backend');
     const limit = filter.limit && filter.limit > 0 ? filter.limit : 50;
-    const raw = await this.call((signal) =>
-      this.client.rest.issues.listForRepo({
-        owner: this.owner,
-        repo: this.repoName(),
-        per_page: limit,
-        state: filter.status ? mapStatusToGitHub(filter.status) : "all",
-        assignee: filter.assignee,
-        labels: filter.labels?.length ? filter.labels.join(",") : undefined,
-        request: { signal },
-      }),
-    );
-    return (raw as GhIssue[]).map((i) => toDomain(i));
+    const meQualifiers = buildMeQualifiers(filter);
+    if (meQualifiers.length === 0) {
+      const raw = await this.call((signal) =>
+        this.client.rest.issues.listForRepo({
+          owner: this.owner,
+          repo: this.repoName(),
+          per_page: limit,
+          state: filter.status ? mapStatusToGitHub(filter.status) : "all",
+          assignee: filter.assignee,
+          labels: filter.labels?.length ? filter.labels.join(",") : undefined,
+          request: { signal },
+        }),
+      );
+      return (raw as GhIssue[]).map((i) => toDomain(i));
+    }
+    // Any "me" flag routes through the Search API instead of listForRepo: it's the only GitHub
+    // surface with a review-requested filter at all (confirmed against GitHub's own REST docs --
+    // listForRepo has no such parameter), and it happens to support author/assignee "me" qualifiers
+    // too, so one call covers every combination of the three flags. Response items are Issue-shaped
+    // (same pull_request: {merged_at} stub as listForRepo's own entries -- confirmed against
+    // @octokit/openapi-types' issue-search-result-item schema), so toDomain() applies unchanged.
+    const q = buildMeSearchQuery(this.owner, this.repoName(), filter, meQualifiers);
+    const result = (await this.call((signal) =>
+      this.client.rest.search.issuesAndPullRequests({ q, per_page: limit, request: { signal } }),
+    )) as { items: GhIssue[] };
+    return result.items.map((i) => toDomain(i));
   }
 
   async get(key: string): Promise<Issue> {
@@ -362,6 +377,24 @@ function mapStatusToGitHub(status: Status): "open" | "closed" {
   return status === "done" || status === "canceled" ? "closed" : "open";
 }
 
+/** ListFilter.{reportedByMe,assignedToMe,reviewRequestedOfMe} -> GitHub Search API qualifiers -- see ListFilter's own doc comment. */
+function buildMeQualifiers(filter: ListFilter): string[] {
+  const qualifiers: string[] = [];
+  if (filter.reportedByMe) qualifiers.push("author:@me");
+  if (filter.assignedToMe) qualifiers.push("assignee:@me");
+  if (filter.reviewRequestedOfMe) qualifiers.push("user-review-requested:@me");
+  return qualifiers;
+}
+
+/** Composes a full Search API `q` string: repo scope + status/labels (AND, matching list()'s own semantics) + the "me" qualifiers (OR'd together). */
+function buildMeSearchQuery(owner: string, repo: string, filter: ListFilter, meQualifiers: readonly string[]): string {
+  const parts = [`repo:${owner}/${repo}`];
+  if (filter.status) parts.push(`is:${mapStatusToGitHub(filter.status)}`);
+  for (const label of filter.labels ?? []) parts.push(`label:"${label.replace(/"/g, '\\"')}"`);
+  parts.push(meQualifiers.length === 1 ? meQualifiers[0]! : `(${meQualifiers.join(" OR ")})`);
+  return parts.join(" ");
+}
+
 function mapStatusFromGitHub(state: string): Status {
   return state.toLowerCase() === "closed" ? "done" : "todo";
 }

package/src/gitlab/gitlab.ts

@@ -166,17 +166,54 @@ export class GitLabRepository {
   }
 
   async list(filter: ListFilter): Promise<Issue[]> {
+    if (filter.qaContactIsMe) throw new Error('gitlab: "qaContactIsMe" is a Jira-only concept, not supported on the gitlab backend');
+    if (filter.reviewRequestedOfMe) {
+      throw new Error(
+        'gitlab: "reviewRequestedOfMe" is a merge-request-only concept (scope=reviews_for_me) that list()\'s Issues-only scope can\'t express -- see get()\'s "!<iid>" convention for merge requests',
+      );
+    }
     const limit = filter.limit && filter.limit > 0 ? filter.limit : 50;
-    const raw = await this.call<GlIssue[]>(() =>
-      this.client.Issues.all({
-        projectId: this.projectId,
-        perPage: limit,
-        state: filter.status ? mapStatusToGitLab(filter.status) : undefined,
-        assigneeUsername: filter.assignee ? [filter.assignee] : undefined,
-        labels: filter.labels?.length ? filter.labels.join(",") : undefined,
-      }),
+    const scopes = meScopes(filter);
+    if (scopes.length <= 1) {
+      const raw = await this.call<GlIssue[]>(() =>
+        this.client.Issues.all({
+          projectId: this.projectId,
+          perPage: limit,
+          state: filter.status ? mapStatusToGitLab(filter.status) : undefined,
+          assigneeUsername: filter.assignee ? [filter.assignee] : undefined,
+          labels: filter.labels?.length ? filter.labels.join(",") : undefined,
+          ...(scopes[0] ? { scope: scopes[0] } : {}),
+        }),
+      );
+      return raw.map(toDomain);
+    }
+    // Both reportedByMe and assignedToMe: GitLab's own `scope` param takes exactly one value per
+    // call (no server-side OR across scopes), so the OR-of-roles group ListFilter's own doc comment
+    // describes is executed here as two calls, deduped client-side by ref -- the one place in this
+    // adapter an OR of "me" flags genuinely costs more than one request (Jira/GitHub both express
+    // it in a single native query).
+    const results = await Promise.all(
+      scopes.map((scope) =>
+        this.call<GlIssue[]>(() =>
+          this.client.Issues.all({
+            projectId: this.projectId,
+            perPage: limit,
+            state: filter.status ? mapStatusToGitLab(filter.status) : undefined,
+            labels: filter.labels?.length ? filter.labels.join(",") : undefined,
+            scope,
+          }),
+        ),
+      ),
     );
-    return raw.map(toDomain);
+    const seen = new Set<string>();
+    const merged: Issue[] = [];
+    for (const raw of results.flat()) {
+      const issue = toDomain(raw);
+      if (seen.has(issue.ref)) continue;
+      seen.add(issue.ref);
+      merged.push(issue);
+    }
+    return merged.slice(0, limit);
   }
 
   async get(key: string): Promise<Issue> {
@@ -372,6 +409,14 @@ function mapStatusToGitLab(status: Status): "opened" | "closed" {
   return status === "done" || status === "canceled" ? "closed" : "opened";
 }
 
+/** ListFilter.{reportedByMe,assignedToMe} -> GitLab Issues API `scope` values -- see ListFilter's own doc comment. */
+function meScopes(filter: ListFilter): ("created_by_me" | "assigned_to_me")[] {
+  const scopes: ("created_by_me" | "assigned_to_me")[] = [];
+  if (filter.reportedByMe) scopes.push("created_by_me");
+  if (filter.assignedToMe) scopes.push("assigned_to_me");
+  return scopes;
+}
+
 function mapStatusEventToGitLab(status: Status): "close" | "reopen" {
   return status === "done" || status === "canceled" ? "close" : "reopen";
 }

package/src/issue/issue.ts

@@ -178,6 +178,30 @@ export interface ListFilter {
   assignee?: string;
   query?: string;
   limit?: number;
+  /**
+   * "Mine" filtering -- deliberately a small set of named, orthogonal boolean flags rather than
+   * either a hardcoded single `mine` concept or a generic cross-backend query language (see the
+   * research Doc "Tickets 'mine' filtering: grounded API research" for why both alternatives were
+   * rejected). Every backend maps each flag to its own native "current user" mechanism (Jira's JQL
+   * currentUser(), GitHub's Search API @me qualifiers, GitLab's scope=*_me) -- never a resolved
+   * literal username. Setting more than one of these ORs them together ("assignee OR reporter"),
+   * AND'd with every other ListFilter field exactly like today's plain fields. A backend that has
+   * no native equivalent for a given flag throws rather than silently ignoring it (e.g.
+   * reviewRequestedOfMe on Jira, qaContactIsMe on GitHub/GitLab) -- a silently-dropped role would
+   * make an incomplete result look complete.
+   */
+  /** Jira: `reporter = currentUser()`. GitHub: `author:@me` (Search API). GitLab: `scope=created_by_me` (Issues API). */
+  reportedByMe?: boolean;
+  /** Jira: `assignee = currentUser()`. GitHub: `assignee:@me` (Search API). GitLab: `scope=assigned_to_me` (Issues API). */
+  assignedToMe?: boolean;
+  /**
+   * GitHub: `user-review-requested:@me` (Search API, PRs only). GitLab: `scope=reviews_for_me` --
+   * a merge-request-only concept list()'s Issues-only scope can't express, so GitLab throws. Jira
+   * has no reviewer concept on plain issues, so Jira throws too.
+   */
+  reviewRequestedOfMe?: boolean;
+  /** Jira only, via the discovered "QA Contact" custom field (auto-discovers if never run). GitHub/GitLab throw -- no equivalent concept. */
+  qaContactIsMe?: boolean;
 }
 
 /** "backend:key" ref parsing, split on the first colon only (keys may contain colons). */

package/src/jira/jira.ts

@@ -204,6 +204,11 @@ export class JiraRepository {
    * the background), not just the single legacy `project` config field.
    */
   async list(filter: ListFilter): Promise<Issue[]> {
+    if (filter.reviewRequestedOfMe) {
+      throw new Error(
+        'jira: "reviewRequestedOfMe" has no meaning on Jira issues (no reviewer concept) -- omit this filter for the jira backend',
+      );
+    }
     const projects = filter.project ? [filter.project] : this.defaultProjects();
     const clauses: string[] = [];
     const scope = projectClause(projects);
@@ -211,9 +216,30 @@ export class JiraRepository {
     if (filter.status) clauses.push(`status = ${jqlQuote(mapStatusToJira(filter.status))}`);
     if (filter.assignee) clauses.push(`assignee = ${jqlQuote(filter.assignee)}`);
     for (const label of filter.labels ?? []) clauses.push(`labels = ${jqlQuote(label)}`);
+    const meClauses = await this.buildMeClauses(filter);
+    if (meClauses.length > 0) clauses.push(meClauses.length === 1 ? meClauses[0]! : `(${meClauses.join(" OR ")})`);
     return this.searchJql(buildJql(clauses, "AND"), filter.limit ?? 50);
   }
 
+  /**
+   * Builds the OR'd group of "me" role clauses for list()'s ListFilter.{reportedByMe,assignedToMe,
+   * qaContactIsMe} flags -- see ListFilter's own doc comment for why this is a small set of named
+   * flags rather than a hardcoded single "mine" concept or a generic query language. "QA Contact"
+   * resolves through the same discoverFields()-backed manifest applyCustomFields() already uses
+   * (auto-discovering on first use), so an instance without that field throws a clear "unknown
+   * custom field" error rather than silently omitting the clause.
+   */
+  private async buildMeClauses(filter: ListFilter): Promise<string[]> {
+    const clauses: string[] = [];
+    if (filter.assignedToMe) clauses.push("assignee = currentUser()");
+    if (filter.reportedByMe) clauses.push("reporter = currentUser()");
+    if (filter.qaContactIsMe) {
+      await this.resolveCustomField("QA Contact");
+      clauses.push('"QA Contact" = currentUser()');
+    }
+    return clauses;
+  }
+
   async get(key: string): Promise<Issue> {
     const [raw, remoteLinks] = await Promise.all([
       this.call<JiraIssue>(() => this.client.issues.getIssue({ issueIdOrKey: key }), key),