@danypops/tickets 0.4.7 → 0.5.0

package/package.json

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

package/src/adapters/jira.ts

@@ -12,8 +12,8 @@
  * client's `UserDetails.accountId` typing would make the fix straightforward
  * (see RESEARCH.md for the full analysis of the bug this leaves unfixed).
  */
-import { Version2Client } from "jira.js";
-import type { HttpException } from "jira.js";
+import { AgileClient, Version2Client } from "jira.js";
+import type { Config as JiraClientConfig, HttpException } from "jira.js";
 import type { AxiosAdapter } from "axios";
 import type { Comment, CreateInput, Issue, IssueLink, ListFilter, Status, UpdateInput } from "../domain/issue.js";
 import { parsePriority } from "../domain/issue.js";
@@ -119,6 +119,8 @@ interface JiraFieldDetails {
 export class JiraRepository {
   readonly name: string;
   private readonly client: Version2Client;
+  /** Same auth/host config Version2Client was built from -- reused lazily by agileClient() so the Agile API client (board/quickfilter resolution) authenticates identically without duplicating the OAuth-vs-basic branching in the constructor below. */
+  private readonly clientConfig: JiraClientConfig;
   private readonly project?: string;
   private readonly configDir?: string;
   /** display name (lowercased) -> { fieldId, schema type/items }, populated lazily from client.issueFields.getFields(). */
@@ -143,24 +145,26 @@ export class JiraRepository {
 
     if (isOAuthOptions(opts)) {
       if (!opts.accessToken || !opts.cloudId) throw new Error("jira: accessToken and cloudId are required for OAuth mode");
-      this.client = new Version2Client({
+      this.clientConfig = {
         authentication: { oauth2: { accessToken: opts.accessToken, cloudId: opts.cloudId } },
         // axios's own native, tested timeout handling -- a stalled call fails predictably
         // instead of hanging (see RESEARCH.md for the octokit throttling-plugin hang this
         // migration found and fixed; jira.js/axios has no equivalent auto-retry-and-wait
         // behavior by default, but had no explicit timeout either until now).
         baseRequestConfig: { timeout: opts.timeoutMs ?? DEFAULT_TIMEOUT_MS, ...(opts.axiosAdapter ? { adapter: opts.axiosAdapter } : {}) },
-      });
+      };
+      this.client = new Version2Client(this.clientConfig);
       return;
     }
 
     if (!opts.baseUrl) throw new Error("jira: baseUrl is required");
     if (!opts.email || !opts.token) throw new Error("jira: email and token are required");
-    this.client = new Version2Client({
+    this.clientConfig = {
       host: opts.baseUrl,
       authentication: { basic: { email: opts.email, apiToken: opts.token } },
       baseRequestConfig: { timeout: opts.timeoutMs ?? DEFAULT_TIMEOUT_MS, ...(opts.axiosAdapter ? { adapter: opts.axiosAdapter } : {}) },
-    });
+    };
+    this.client = new Version2Client(this.clientConfig);
   }
 
   async list(filter: ListFilter): Promise<Issue[]> {
@@ -264,6 +268,40 @@ export class JiraRepository {
     return commentToDomain(raw);
   }
 
+  /** RawQueryable -- runs a raw JQL string verbatim, for the "Saved query" feature (and anything else that already has real JQL rather than a ListFilter to build one from). */
+  async runQuery(query: string, limit = 50): Promise<Issue[]> {
+    return this.searchJql(query, limit);
+  }
+
+  /**
+   * BoardQuickFilterDiscoverable -- resolves a board's quick filter (the same object
+   * a board view's `quickFilter=` URL param and a backlog view's `customFilter=`
+   * param both reference -- Jira just spells the query param differently per view)
+   * to its real JQL clause, via the durable (non-deprecated)
+   * `GET /rest/agile/1.0/board/{boardId}/quickfilter/{id}` endpoint. This is a
+   * fragment, not a full query -- Jira itself ANDs it with the board's own project
+   * scope and a sprint clause when rendering a live board/backlog view. Combine it
+   * with `project = X AND sprint in openSprints()` (board/active-sprint view) or
+   * `project = X AND (sprint is EMPTY OR sprint in futureSprints())` (backlog view)
+   * to save as a plain runnable JQL string via query.save, same as any other saved
+   * query -- no separate "board view" execution path needed. jira.js's AgileClient
+   * wraps the Agile REST API surface; Version2Client (this.client) only covers the
+   * Platform REST API, hence the separate client here.
+   */
+  async discoverBoardQuickFilterJql(boardId: number, quickFilterId: number): Promise<string> {
+    const agile = this.agileClient();
+    const result = await this.call<{ jql?: string }>(() => agile.board.getQuickFilter({ boardId, quickFilterId }));
+    if (!result?.jql) throw new Error(`jira: quick filter ${quickFilterId} on board ${boardId} has no JQL`);
+    return result.jql;
+  }
+
+  private agileClientInstance?: AgileClient;
+
+  private agileClient(): AgileClient {
+    this.agileClientInstance ??= new AgileClient(this.clientConfig);
+    return this.agileClientInstance;
+  }
+
   private async searchJql(jql: string, limit: number): Promise<Issue[]> {
     // searchForIssuesUsingJqlPost hits the deprecated /rest/api/2/search, which
     // Atlassian has sunset on Jira Cloud (410 Gone). The enhanced variant posts

package/src/application/service.ts

@@ -8,8 +8,10 @@ import type { Comment, CreateInput, Issue, ListFilter, UpdateInput } from "../do
 import { parseRef } from "../domain/issue.js";
 import type { Template } from "../domain/template.js";
 import {
+  hasBoardQuickFilterDiscovery,
   hasComments,
   hasFieldDiscovery,
+  hasRawQuery,
   hasStatusDiscovery,
   hasTemplateDiscovery,
   type IssueRepository,
@@ -117,4 +119,18 @@ export class TicketService {
     if (!hasTemplateDiscovery(repo)) throw new NotSupportedError(backend, "template discovery");
     return repo.discoverTemplate(project, issueType, sampleSize);
   }
+
+  /** Runs a raw query string (Jira JQL) verbatim against one backend -- the execution half of the "saved query" feature. */
+  async runQuery(backend: string, query: string, limit?: number): Promise<Issue[]> {
+    const repo = this.repo(backend);
+    if (!hasRawQuery(repo)) throw new NotSupportedError(backend, "raw queries");
+    return repo.runQuery(query, limit);
+  }
+
+  /** Resolves a Jira board's quick filter id to its JQL fragment -- the one-time step that turns a board/backlog view into a saved query. */
+  async discoverBoardQuickFilterJql(backend: string, boardId: number, quickFilterId: number): Promise<string> {
+    const repo = this.repo(backend);
+    if (!hasBoardQuickFilterDiscovery(repo)) throw new NotSupportedError(backend, "board quick filter discovery");
+    return repo.discoverBoardQuickFilterJql(boardId, quickFilterId);
+  }
 }

package/src/cli/index.ts

@@ -230,6 +230,50 @@ discoverCmd
     );
   });
 
+const queryCmd = program.command("query").description("save and run named raw backend queries (Jira JQL) -- e.g. a board's sprint or backlog view");
+
+queryCmd
+  .command("save <name>")
+  .description("save a raw query under a name; saving under an existing name updates it in place")
+  .requiredOption("-b, --backend <name>", "backend name")
+  .requiredOption("--jql <jql>", "the raw query string (Jira JQL)")
+  .option("--description <text>", "human-readable note about what this query is")
+  .action(async (name: string, opts) => {
+    await withClient((client) => client.call("query.save", { name, backend: opts.backend, query: opts.jql, description: opts.description }));
+  });
+
+queryCmd
+  .command("list")
+  .description("list every saved query")
+  .action(async () => {
+    await withClient((client) => client.call("query.list", {}));
+  });
+
+queryCmd
+  .command("remove <name>")
+  .description("remove a saved query")
+  .action(async (name: string) => {
+    await withClient((client) => client.call("query.remove", { name }));
+  });
+
+queryCmd
+  .command("run <name>")
+  .description("run a saved query by name")
+  .option("--limit <n>", "max results", (v) => Number.parseInt(v, 10))
+  .action(async (name: string, opts) => {
+    await withClient((client) => client.call("query.run", { name, limit: opts.limit }));
+  });
+
+discoverCmd
+  .command("board_quickfilter")
+  .description("resolve a Jira board's quick filter id to its JQL fragment -- board view's quickFilter=, backlog view's customFilter=, are the same id")
+  .requiredOption("-b, --backend <name>", "backend name")
+  .requiredOption("--board <id>", "board id", (v) => Number.parseInt(v, 10))
+  .requiredOption("--quick-filter <id>", "quick filter id", (v) => Number.parseInt(v, 10))
+  .action(async (opts) => {
+    await withClient((client) => client.call("discover.board_quickfilter", { backend: opts.backend, boardId: opts.board, quickFilterId: opts.quickFilter }));
+  });
+
 const daemon = program.command("daemon").description("manage the tickets daemon process");
 
 daemon

package/src/daemon/bootstrap.ts

@@ -15,6 +15,7 @@ import { buildRepositories, type BuildRepositories, type Config, createBackendRe
 import type { IssueRepository } from "../ports/repository.js";
 import { FOCUS_MIGRATIONS, FocusStore } from "./focus.js";
 import { Ledger, LEDGER_MIGRATIONS } from "./ledger.js";
+import { SAVED_QUERY_MIGRATIONS, SavedQueryStore } from "./saved-queries.js";
 import { TICKETS_DAEMON_NAMES } from "./ops.js";
 import { buildApp, type TicketsAppDeps } from "./server.js";
 import { createSyncTask } from "./poller.js";
@@ -50,6 +51,7 @@ export interface BootstrappedDaemon {
   db: Database;
   ledger: Ledger;
   focusStore: FocusStore;
+  queries: SavedQueryStore;
   service: TicketService;
   options: StartDaemonOptions;
 }
@@ -61,9 +63,10 @@ const DEFAULT_BACKEND_REFRESH_INTERVAL_MS = 30_000;
 export async function bootstrap(opts: BootstrapOptions = {}): Promise<BootstrappedDaemon> {
   const paths = resolveDaemonPaths(TICKETS_DAEMON_NAMES, opts.pathEnv);
   const token = ensureAuthToken(paths.token, "Tickets");
-  const db = openSqliteWithPragmas(paths.database, { migrations: [...LEDGER_MIGRATIONS, ...FOCUS_MIGRATIONS] });
+  const db = openSqliteWithPragmas(paths.database, { migrations: [...LEDGER_MIGRATIONS, ...FOCUS_MIGRATIONS, ...SAVED_QUERY_MIGRATIONS] });
   const ledger = new Ledger(db);
   const focusStore = new FocusStore(db);
+  const queries = new SavedQueryStore(db);
   const logger = opts.logger ?? createLogger("tickets-daemon", { levelEnvVar: "TICKETS_LOG_LEVEL" });
   const config = opts.config ?? loadConfig();
   const buildRepos = opts.buildRepositories ?? buildRepositories;
@@ -76,7 +79,7 @@ export async function bootstrap(opts: BootstrapOptions = {}): Promise<Bootstrapp
   // the registry field itself -- createTicketsVehicleRegistry never reads
   // deps.vehicleRegistry, so this ordering is safe (see server.ts's own
   // comment on why the registry is built outside it, not imported into it).
-  const vehicleRegistry = createTicketsVehicleRegistry({ service, ledger, focusStore, token, version, logger, onShutdownRequested } as TicketsAppDeps);
+  const vehicleRegistry = createTicketsVehicleRegistry({ service, ledger, focusStore, queries, token, version, logger, onShutdownRequested } as TicketsAppDeps);
 
   const options: StartDaemonOptions = {
     daemonLabel: "Tickets",
@@ -100,6 +103,7 @@ export async function bootstrap(opts: BootstrapOptions = {}): Promise<Bootstrapp
         service,
         ledger,
         focusStore,
+        queries,
         token,
         version,
         logger,
@@ -111,5 +115,5 @@ export async function bootstrap(opts: BootstrapOptions = {}): Promise<Bootstrapp
     },
   };
 
-  return { db, ledger, focusStore, service, options };
+  return { db, ledger, focusStore, queries, service, options };
 }

package/src/daemon/ops.ts

@@ -7,6 +7,7 @@
 import type { Comment, CreateInput, Issue, ListFilter, UpdateInput } from "../domain/issue.js";
 import type { Template } from "../domain/template.js";
 import type { TicketFocusState } from "./focus.js";
+import type { SavedQuery } from "./saved-queries.js";
 
 export type TicketOperation =
   | "backends.list"
@@ -28,6 +29,11 @@ export type TicketOperation =
   | "discover.fields"
   | "discover.statuses"
   | "discover.template"
+  | "discover.board_quickfilter"
+  | "query.save"
+  | "query.list"
+  | "query.remove"
+  | "query.run"
   | "daemon.shutdown";
 
 export interface TicketOpInputs extends Record<TicketOperation, unknown> {
@@ -50,6 +56,11 @@ export interface TicketOpInputs extends Record<TicketOperation, unknown> {
   "discover.fields": { backend: string };
   "discover.statuses": { backend: string };
   "discover.template": { backend: string; project: string; issueType: string; sampleSize?: number };
+  "discover.board_quickfilter": { backend: string; boardId: number; quickFilterId: number };
+  "query.save": { name: string; backend: string; query: string; description?: string };
+  "query.list": Record<string, never>;
+  "query.remove": { name: string };
+  "query.run": { name: string; limit?: number };
   "daemon.shutdown": Record<string, never>;
 }
 
@@ -73,6 +84,11 @@ export interface TicketOpOutputs extends Record<TicketOperation, unknown> {
   "discover.fields": { mappings: Record<string, string> };
   "discover.statuses": { mappings: Record<string, string> };
   "discover.template": { template: Template | null };
+  "discover.board_quickfilter": { jql: string };
+  "query.save": { query: SavedQuery };
+  "query.list": { queries: SavedQuery[] };
+  "query.remove": { removed: boolean };
+  "query.run": { issues: Issue[] };
   "daemon.shutdown": { stopping: true };
 }
 
@@ -96,6 +112,11 @@ export const TICKET_OPERATIONS: TicketOperation[] = [
   "discover.fields",
   "discover.statuses",
   "discover.template",
+  "discover.board_quickfilter",
+  "query.save",
+  "query.list",
+  "query.remove",
+  "query.run",
   "daemon.shutdown",
 ];
 

package/src/daemon/saved-queries.ts

@@ -0,0 +1,102 @@
+/**
+ * Saved queries — a name plus a raw query string (Jira JQL today; the backend
+ * decides what "raw query" means via ports/repository.ts's RawQueryable) that
+ * can be run again by name instead of re-typing the query every time. This is
+ * how a board/backlog view (e.g. a Jira board's quickFilter, or its backlog's
+ * customFilter) becomes something the CLI/TUI/tool surface can browse
+ * directly: resolve the view's real query once (see JiraRepository's
+ * getBoardQuickFilterJql/getBoardViewIssues), then save the result under a
+ * name once and just run it by name from then on.
+ */
+import type { Database } from "bun:sqlite";
+import type { Migration } from "@danypops/vehicle-server/storage";
+
+export const SAVED_QUERY_MIGRATIONS: Migration[] = [
+  {
+    version: 3,
+    up: (db) => {
+      db.exec(`
+        CREATE TABLE saved_query (
+          name TEXT PRIMARY KEY,
+          backend TEXT NOT NULL,
+          query TEXT NOT NULL,
+          description TEXT,
+          created_at TEXT NOT NULL,
+          updated_at TEXT NOT NULL
+        );
+      `);
+    },
+  },
+];
+
+export class SavedQueryNotFoundError extends Error {
+  constructor(name: string) {
+    super(`no saved query named "${name}"`);
+    this.name = "SavedQueryNotFoundError";
+  }
+}
+
+export interface SavedQuery {
+  name: string;
+  backend: string;
+  query: string;
+  description?: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+interface SavedQueryRow {
+  name: string;
+  backend: string;
+  query: string;
+  description: string | null;
+  created_at: string;
+  updated_at: string;
+}
+
+function rowToSavedQuery(row: SavedQueryRow): SavedQuery {
+  return {
+    name: row.name,
+    backend: row.backend,
+    query: row.query,
+    description: row.description ?? undefined,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  };
+}
+
+export class SavedQueryStore {
+  constructor(private readonly db: Database) {}
+
+  /** Creates or overwrites a saved query by name -- saving under an existing name updates it in place rather than erroring, matching the "save this view under a name" mental model (re-saving after a query changed shouldn't require a delete first). */
+  save(name: string, backend: string, query: string, description?: string): SavedQuery {
+    const now = new Date().toISOString();
+    const existing = this.get(name);
+    const createdAt = existing?.createdAt ?? now;
+    this.db
+      .query(
+        `INSERT INTO saved_query (name, backend, query, description, created_at, updated_at)
+         VALUES ($name, $backend, $query, $description, $createdAt, $updatedAt)
+         ON CONFLICT(name) DO UPDATE SET
+           backend = excluded.backend, query = excluded.query, description = excluded.description, updated_at = excluded.updated_at`,
+      )
+      .run({ $name: name, $backend: backend, $query: query, $description: description ?? null, $createdAt: createdAt, $updatedAt: now });
+    return { name, backend, query, description, createdAt, updatedAt: now };
+  }
+
+  get(name: string): SavedQuery | undefined {
+    const row = this.db.query("SELECT * FROM saved_query WHERE name = $name").get({ $name: name }) as SavedQueryRow | null;
+    return row ? rowToSavedQuery(row) : undefined;
+  }
+
+  list(): SavedQuery[] {
+    const rows = this.db.query("SELECT * FROM saved_query ORDER BY name ASC").all() as SavedQueryRow[];
+    return rows.map(rowToSavedQuery);
+  }
+
+  /** Idempotent -- removing a name that doesn't exist is a no-op, not an error, matching this codebase's own undepend/uncontain convention for "already absent". */
+  remove(name: string): boolean {
+    const result = this.db.query("DELETE FROM saved_query WHERE name = $name").run({ $name: name });
+    return result.changes > 0;
+  }
+}

package/src/daemon/server.ts

@@ -16,11 +16,13 @@ import { parseRef } from "../domain/issue.js";
 import { FocusError, type FocusStore } from "./focus.js";
 import type { Ledger } from "./ledger.js";
 import { TICKET_OPERATIONS, type TicketOpInputs, type TicketOperation, type TicketOpOutputs } from "./ops.js";
+import { SavedQueryNotFoundError, type SavedQueryStore } from "./saved-queries.js";
 
 export interface TicketsAppDeps {
   service: TicketService;
   ledger: Ledger;
   focusStore: FocusStore;
+  queries: SavedQueryStore;
   token: string;
   version: string;
   logger?: Logger;
@@ -89,6 +91,17 @@ export const TICKET_OP_HANDLERS: { [Op in TicketOperation]: Handler<Op> } = {
   "discover.template": async (deps, input) => ({
     template: (await deps.service.discoverTemplate(input.backend, input.project, input.issueType, input.sampleSize)) ?? null,
   }),
+  "discover.board_quickfilter": async (deps, input) => ({
+    jql: await deps.service.discoverBoardQuickFilterJql(input.backend, input.boardId, input.quickFilterId),
+  }),
+  "query.save": async (deps, input) => ({ query: deps.queries.save(input.name, input.backend, input.query, input.description) }),
+  "query.list": async (deps) => ({ queries: deps.queries.list() }),
+  "query.remove": async (deps, input) => ({ removed: deps.queries.remove(input.name) }),
+  "query.run": async (deps, input) => {
+    const saved = deps.queries.get(input.name);
+    if (!saved) throw new SavedQueryNotFoundError(input.name);
+    return { issues: await deps.service.runQuery(saved.backend, saved.query, input.limit) };
+  },
   "daemon.shutdown": async (deps) => {
     // Deferred so this handler's own response has already been handed back
     // to Bun.serve before the process starts tearing down.
@@ -102,7 +115,7 @@ function isTicketOperation(value: unknown): value is TicketOperation {
 }
 
 function statusFor(error: unknown): number {
-  if (error instanceof IssueNotFoundError) return 404;
+  if (error instanceof IssueNotFoundError || error instanceof SavedQueryNotFoundError) return 404;
   if (error instanceof UnknownBackendError || error instanceof NotSupportedError || error instanceof FocusError) return 400;
   if (error instanceof AuthRequiredError) return 422;
   return 500;

package/src/ports/repository.ts

@@ -59,3 +59,32 @@ export interface TemplateDiscoverable {
 export function hasTemplateDiscovery(repo: IssueRepository): repo is IssueRepository & TemplateDiscoverable {
   return typeof (repo as Partial<TemplateDiscoverable>).discoverTemplate === "function";
 }
+
+/**
+ * Optional capability — runs a raw query string in the backend's own query language
+ * (Jira's JQL). Backs the "Saved query" feature: a saved query is just a name plus a
+ * raw string in whatever language the backend understands, executed verbatim. Only
+ * Jira supports this today (GitHub/GitLab have no equivalent single query language
+ * spanning issues, boards, and backlogs the way Jira's JQL does).
+ */
+export interface RawQueryable {
+  runQuery(query: string, limit?: number): Promise<Issue[]>;
+}
+
+export function hasRawQuery(repo: IssueRepository): repo is IssueRepository & RawQueryable {
+  return typeof (repo as Partial<RawQueryable>).runQuery === "function";
+}
+
+/**
+ * Optional capability — resolves a Jira board's quick filter id to its real JQL
+ * fragment, the one-time step that turns a board/backlog view URL into a saved
+ * query (see RawQueryable above). Jira only; boards/quick filters have no GitHub or
+ * GitLab equivalent.
+ */
+export interface BoardQuickFilterDiscoverable {
+  discoverBoardQuickFilterJql(boardId: number, quickFilterId: number): Promise<string>;
+}
+
+export function hasBoardQuickFilterDiscovery(repo: IssueRepository): repo is IssueRepository & BoardQuickFilterDiscoverable {
+  return typeof (repo as Partial<BoardQuickFilterDiscoverable>).discoverBoardQuickFilterJql === "function";
+}

package/src/vehicle/tickets-vehicle.ts

@@ -105,6 +105,29 @@ const OPERATIONS: readonly OperationSpec[] = [
     properties: { backend: stringProp, project: stringProp, issueType: stringProp, sampleSize: numberProp },
     required: ["backend", "project", "issueType"],
   },
+  {
+    action: "discover.board_quickfilter",
+    description: "Resolves a Jira board's quick filter id to its JQL fragment -- the one-time step to turn a board/backlog view into a saved query.",
+    effect: "read",
+    properties: { backend: stringProp, boardId: numberProp, quickFilterId: numberProp },
+    required: ["backend", "boardId", "quickFilterId"],
+  },
+  {
+    action: "query.save",
+    description: "Saves a raw backend query (Jira JQL) under a name, so it can be run again later without retyping it -- e.g. a board's sprint or backlog view.",
+    effect: "local-write",
+    properties: { name: stringProp, backend: stringProp, query: stringProp, description: stringProp },
+    required: ["name", "backend", "query"],
+  },
+  { action: "query.list", description: "Lists every saved query.", effect: "read", properties: {}, required: [] },
+  { action: "query.remove", description: "Removes a saved query by name.", effect: "local-write", properties: { name: stringProp }, required: ["name"] },
+  {
+    action: "query.run",
+    description: "Runs a saved query by name against its backend and returns the matching issues.",
+    effect: "read",
+    properties: { name: stringProp, limit: numberProp },
+    required: ["name"],
+  },
 ];
 
 /**