@danypops/tickets 0.1.0

package/src/daemon/ledger.ts

@@ -0,0 +1,124 @@
+/**
+ * Ledger — the daemon's local, independent pool of every issue it has seen.
+ * Mirrors emcee's SQLite Ledger concept: a passively-populated local index
+ * that keeps working (search, stats, last-known state) even when a backend
+ * is slow, rate-limited, or unreachable. Populated by poller.ts on its own
+ * schedule; queried directly by ledger.search / ledger.stats ops, independent
+ * of any live upstream call.
+ */
+import type { Database } from "bun:sqlite";
+import type { Migration } from "@danypops/daemon-kit/storage";
+import type { Issue } from "../domain/issue.js";
+
+export const LEDGER_MIGRATIONS: Migration[] = [
+  {
+    version: 1,
+    up: (db) => {
+      db.exec(`
+        CREATE TABLE issues (
+          ref TEXT PRIMARY KEY,
+          backend TEXT NOT NULL,
+          key TEXT NOT NULL,
+          title TEXT NOT NULL,
+          status TEXT NOT NULL,
+          priority TEXT NOT NULL,
+          url TEXT,
+          updated_at TEXT,
+          synced_at TEXT NOT NULL,
+          raw_json TEXT NOT NULL
+        );
+        CREATE INDEX idx_issues_backend ON issues (backend);
+        CREATE INDEX idx_issues_title ON issues (title);
+      `);
+    },
+  },
+];
+
+interface IssueRow {
+  ref: string;
+  backend: string;
+  key: string;
+  title: string;
+  status: string;
+  priority: string;
+  url: string | null;
+  updated_at: string | null;
+  synced_at: string;
+  raw_json: string;
+}
+
+function rowToIssue(row: IssueRow): Issue {
+  return JSON.parse(row.raw_json) as Issue;
+}
+
+const DEFAULT_SEARCH_LIMIT = 50;
+const MAX_SEARCH_LIMIT = 200;
+
+export class Ledger {
+  constructor(private readonly db: Database) {}
+
+  upsert(backend: string, issue: Issue): void {
+    this.db
+      .query(
+        `INSERT INTO issues (ref, backend, key, title, status, priority, url, updated_at, synced_at, raw_json)
+         VALUES ($ref, $backend, $key, $title, $status, $priority, $url, $updatedAt, $syncedAt, $rawJson)
+         ON CONFLICT(ref) DO UPDATE SET
+           title = excluded.title,
+           status = excluded.status,
+           priority = excluded.priority,
+           url = excluded.url,
+           updated_at = excluded.updated_at,
+           synced_at = excluded.synced_at,
+           raw_json = excluded.raw_json`,
+      )
+      .run({
+        $ref: issue.ref,
+        $backend: backend,
+        $key: issue.key,
+        $title: issue.title,
+        $status: issue.status,
+        $priority: issue.priority,
+        $url: issue.url ?? null,
+        $updatedAt: issue.updatedAt ?? null,
+        $syncedAt: new Date().toISOString(),
+        $rawJson: JSON.stringify(issue),
+      });
+  }
+
+  upsertMany(backend: string, issues: Issue[]): number {
+    const tx = this.db.transaction((rows: Issue[]) => {
+      for (const issue of rows) this.upsert(backend, issue);
+    });
+    tx(issues);
+    return issues.length;
+  }
+
+  get(ref: string): Issue | undefined {
+    const row = this.db.query("SELECT * FROM issues WHERE ref = ?").get(ref) as IssueRow | null;
+    return row ? rowToIssue(row) : undefined;
+  }
+
+  /** Bounded LIKE search over title, newest-synced first. Explicit limit, capped hard. */
+  search(query: string, limit = DEFAULT_SEARCH_LIMIT): Issue[] {
+    const bounded = Math.min(Math.max(limit, 1), MAX_SEARCH_LIMIT);
+    const rows = this.db
+      .query("SELECT * FROM issues WHERE title LIKE ? ORDER BY synced_at DESC LIMIT ?")
+      .all(`%${query}%`, bounded) as IssueRow[];
+    return rows.map(rowToIssue);
+  }
+
+  listByBackend(backend: string, limit = DEFAULT_SEARCH_LIMIT): Issue[] {
+    const bounded = Math.min(Math.max(limit, 1), MAX_SEARCH_LIMIT);
+    const rows = this.db
+      .query("SELECT * FROM issues WHERE backend = ? ORDER BY synced_at DESC LIMIT ?")
+      .all(backend, bounded) as IssueRow[];
+    return rows.map(rowToIssue);
+  }
+
+  stats(): { backend: string; count: number }[] {
+    const rows = this.db
+      .query("SELECT backend, COUNT(*) as count FROM issues GROUP BY backend ORDER BY backend")
+      .all() as { backend: string; count: number }[];
+    return rows;
+  }
+}

package/src/daemon/main.ts

@@ -0,0 +1,20 @@
+#!/usr/bin/env bun
+/**
+ * The real tickets-daemon binary. Requires Bun (bun:sqlite, Bun.serve via
+ * daemon-kit). Everything else in this package (the library, the CLI, the
+ * pi-tickets extension) is plain Node-compatible TypeScript and talks to
+ * this process only over the loopback HTTP RPC surface — see client.ts.
+ */
+import { runDaemonProcess } from "@danypops/daemon-kit/daemon";
+import { readPackageVersion } from "@danypops/daemon-kit/version";
+import { bootstrap } from "./bootstrap.js";
+
+const version = readPackageVersion(new URL("../../package.json", import.meta.url), "Tickets");
+const { options } = bootstrap({ version });
+
+runDaemonProcess({
+  ...options,
+  onListen: (info) => {
+    options.logger?.info("tickets daemon listening", { host: info.host, port: info.port, version });
+  },
+});

package/src/daemon/ops.ts

@@ -0,0 +1,75 @@
+/**
+ * The RPC protocol shared between the tickets daemon (server.ts, running under
+ * Bun) and every client (cli/index.ts, extensions/pi-tickets, running under
+ * whatever consumes this package). Pure types, zero runtime imports, safe to
+ * import from either side without pulling in bun:sqlite or Bun.serve.
+ */
+import type { Comment, CreateInput, Issue, ListFilter, UpdateInput } from "../domain/issue.js";
+
+export type TicketOperation =
+  | "backends.list"
+  | "issue.list"
+  | "issue.get"
+  | "issue.create"
+  | "issue.update"
+  | "issue.search"
+  | "issue.children"
+  | "issue.comments"
+  | "issue.comment_add"
+  | "ledger.search"
+  | "ledger.stats"
+  | "daemon.shutdown";
+
+export interface TicketOpInputs extends Record<TicketOperation, unknown> {
+  "backends.list": Record<string, never>;
+  "issue.list": { backend: string; filter?: ListFilter };
+  "issue.get": { ref: string };
+  "issue.create": { backend: string; input: CreateInput };
+  "issue.update": { ref: string; input: UpdateInput };
+  "issue.search": { backend: string; query: string; limit?: number };
+  "issue.children": { ref: string };
+  "issue.comments": { ref: string };
+  "issue.comment_add": { ref: string; body: string };
+  "ledger.search": { query: string; limit?: number };
+  "ledger.stats": Record<string, never>;
+  "daemon.shutdown": Record<string, never>;
+}
+
+export interface TicketOpOutputs extends Record<TicketOperation, unknown> {
+  "backends.list": { backends: string[] };
+  "issue.list": { issues: Issue[] };
+  "issue.get": { issue: Issue };
+  "issue.create": { issue: Issue };
+  "issue.update": { issue: Issue };
+  "issue.search": { issues: Issue[] };
+  "issue.children": { issues: Issue[] };
+  "issue.comments": { comments: Comment[] };
+  "issue.comment_add": { comment: Comment };
+  "ledger.search": { issues: Issue[] };
+  "ledger.stats": { backends: { backend: string; count: number }[] };
+  "daemon.shutdown": { stopping: true };
+}
+
+export const TICKET_OPERATIONS: TicketOperation[] = [
+  "backends.list",
+  "issue.list",
+  "issue.get",
+  "issue.create",
+  "issue.update",
+  "issue.search",
+  "issue.children",
+  "issue.comments",
+  "issue.comment_add",
+  "ledger.search",
+  "ledger.stats",
+  "daemon.shutdown",
+];
+
+/** Daemon path/state directory identity — the one place this name is spelled out. */
+export const TICKETS_DAEMON_NAMES = {
+  stateDirectoryName: "tickets",
+  databaseFilename: "tickets.db",
+  tokenFilename: "token",
+  handleFilename: "handle.json",
+  systemdUnitName: "tickets-daemon.service",
+} as const;

package/src/daemon/poller.ts

@@ -0,0 +1,52 @@
+/**
+ * Poller — pools issues from every configured backend into the local Ledger
+ * on its own schedule, independent of whether any client (CLI, pi-tickets)
+ * is currently asking for anything. A backend sync failure (rate limit,
+ * network, bad creds) is logged and skipped; it never crashes the daemon
+ * and never blocks other backends' syncs.
+ */
+import type { Logger } from "@danypops/daemon-kit/logging";
+import type { MaintenanceTask } from "@danypops/daemon-kit/daemon";
+import type { TicketService } from "../application/service.js";
+import type { Ledger } from "./ledger.js";
+
+const DEFAULT_SYNC_LIMIT = 50;
+
+/** Runs one sync pass across all given backends. Exported standalone for tests. */
+export async function syncOnce(
+  service: TicketService,
+  ledger: Ledger,
+  backends: string[],
+  logger?: Logger,
+): Promise<{ backend: string; synced: number; error?: string }[]> {
+  const results: { backend: string; synced: number; error?: string }[] = [];
+  for (const backend of backends) {
+    try {
+      const issues = await service.list(backend, { limit: DEFAULT_SYNC_LIMIT });
+      const synced = ledger.upsertMany(backend, issues);
+      results.push({ backend, synced });
+      logger?.debug("ledger sync ok", { backend, synced });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      results.push({ backend, synced: 0, error: message });
+      logger?.warn("ledger sync failed", { backend, error: message });
+    }
+  }
+  return results;
+}
+
+export function createSyncTask(
+  service: TicketService,
+  ledger: Ledger,
+  backends: string[],
+  intervalMs: number,
+  logger?: Logger,
+): MaintenanceTask {
+  return {
+    name: "ledger-sync",
+    intervalMs,
+    run: async () => {
+      await syncOnce(service, ledger, backends, logger);
+    },
+  };
+}

package/src/daemon/server.ts

@@ -0,0 +1,100 @@
+/**
+ * Daemon HTTP surface: Bearer-token auth, /health, /ready, and a single
+ * dispatch endpoint (/api/v1/ops) per daemon-kit's http.ts convention.
+ * Every operation here has a CLI command (cli/index.ts) and a pi-tickets
+ * tool action — no operation exists only for one caller.
+ */
+import { errorResponse, healthResponse, jsonResponse, readyResponse, requireBearerToken } from "@danypops/daemon-kit/http";
+import type { Logger } from "@danypops/daemon-kit/logging";
+import { AuthRequiredError, IssueNotFoundError } from "../adapters/errors.js";
+import { NotSupportedError, type TicketService, UnknownBackendError } from "../application/service.js";
+import type { Ledger } from "./ledger.js";
+import { TICKET_OPERATIONS, type TicketOpInputs, type TicketOperation, type TicketOpOutputs } from "./ops.js";
+
+export interface TicketsAppDeps {
+  service: TicketService;
+  ledger: Ledger;
+  token: string;
+  version: string;
+  logger?: Logger;
+  /**
+   * Invoked by the `daemon.shutdown` op, after the HTTP response is already
+   * queued to flush. Defaults set by bootstrap.ts self-signal the process so
+   * the same tested SIGINT/SIGTERM path (daemon-kit's runDaemonProcess) does
+   * the actual graceful stop — this hook only ever *requests* shutdown, it
+   * never calls process.exit directly.
+   */
+  onShutdownRequested?: () => void;
+}
+
+type Handler<Op extends TicketOperation> = (
+  deps: TicketsAppDeps,
+  input: TicketOpInputs[Op],
+) => Promise<TicketOpOutputs[Op]>;
+
+const handlers: { [Op in TicketOperation]: Handler<Op> } = {
+  "backends.list": async (deps) => ({ backends: deps.service.backends() }),
+  "issue.list": async (deps, input) => ({ issues: await deps.service.list(input.backend, input.filter) }),
+  "issue.get": async (deps, input) => ({ issue: await deps.service.get(input.ref) }),
+  "issue.create": async (deps, input) => ({ issue: await deps.service.create(input.backend, input.input) }),
+  "issue.update": async (deps, input) => ({ issue: await deps.service.update(input.ref, input.input) }),
+  "issue.search": async (deps, input) => ({ issues: await deps.service.search(input.backend, input.query, input.limit) }),
+  "issue.children": async (deps, input) => ({ issues: await deps.service.children(input.ref) }),
+  "issue.comments": async (deps, input) => ({ comments: await deps.service.comments(input.ref) }),
+  "issue.comment_add": async (deps, input) => ({ comment: await deps.service.addComment(input.ref, input.body) }),
+  "ledger.search": async (deps, input) => ({ issues: deps.ledger.search(input.query, input.limit) }),
+  "ledger.stats": async (deps) => ({ backends: deps.ledger.stats() }),
+  "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.
+    setTimeout(() => deps.onShutdownRequested?.(), 50);
+    return { stopping: true };
+  },
+};
+
+function isTicketOperation(value: unknown): value is TicketOperation {
+  return typeof value === "string" && (TICKET_OPERATIONS as string[]).includes(value);
+}
+
+function statusFor(error: unknown): number {
+  if (error instanceof IssueNotFoundError) return 404;
+  if (error instanceof UnknownBackendError || error instanceof NotSupportedError) return 400;
+  if (error instanceof AuthRequiredError) return 422;
+  return 500;
+}
+
+export function buildApp(deps: TicketsAppDeps): { fetch(request: Request): Promise<Response> } {
+  return {
+    async fetch(request: Request): Promise<Response> {
+      const url = new URL(request.url);
+
+      if (!requireBearerToken(request, deps.token)) return errorResponse("unauthorized", 401);
+      if (request.method === "GET" && url.pathname === "/health") return healthResponse(deps.version);
+      if (request.method === "GET" && url.pathname === "/ready") return readyResponse(true);
+
+      if (url.pathname === "/api/v1/ops") {
+        if (request.method === "GET") return jsonResponse({ operations: TICKET_OPERATIONS });
+        if (request.method === "POST") {
+          let body: { op?: unknown; input?: unknown };
+          try {
+            body = (await request.json()) as { op?: unknown; input?: unknown };
+          } catch {
+            return errorResponse("invalid JSON body", 400);
+          }
+          if (!isTicketOperation(body.op)) return errorResponse(`unknown op: ${String(body.op)}`, 400);
+          const handler = handlers[body.op] as Handler<TicketOperation>;
+          try {
+            const result = await handler(deps, (body.input ?? {}) as never);
+            return jsonResponse({ result });
+          } catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            deps.logger?.warn("op failed", { op: body.op, error: message });
+            return errorResponse(message, statusFor(error));
+          }
+        }
+      }
+
+      return errorResponse("not found", 404);
+    },
+  };
+}

package/src/domain/issue.ts

@@ -0,0 +1,114 @@
+/**
+ * Domain package — the canonical, backend-agnostic representation of a work item.
+ * Zero external dependencies, zero I/O. Mirrors the shape independently reachable
+ * from GitHub Issues, GitLab Issues, and Jira issues (see RESEARCH.md for the
+ * source API docs each adapter was built against).
+ */
+
+export const PRIORITIES = ["none", "urgent", "high", "medium", "low"] as const;
+export type Priority = (typeof PRIORITIES)[number];
+
+/** Accepts case-insensitive strings and falls back to "none" for anything unrecognized. */
+export function parsePriority(value: unknown): Priority {
+  if (typeof value !== "string") return "none";
+  const lower = value.toLowerCase().trim();
+  return (PRIORITIES as readonly string[]).includes(lower) ? (lower as Priority) : "none";
+}
+
+export const STATUSES = [
+  "backlog",
+  "todo",
+  "in_progress",
+  "in_review",
+  "done",
+  "canceled",
+] as const;
+export type Status = (typeof STATUSES)[number];
+
+export function parseStatus(value: unknown, fallback: Status = "todo"): Status {
+  if (typeof value !== "string") return fallback;
+  const lower = value.toLowerCase().trim();
+  return (STATUSES as readonly string[]).includes(lower) ? (lower as Status) : fallback;
+}
+
+export interface IssueParent {
+  key: string;
+  title: string;
+  status?: string;
+}
+
+export interface Comment {
+  id: string;
+  body: string;
+  author?: string;
+  createdAt?: string;
+  updatedAt?: string;
+}
+
+/** The unified representation of a work item, regardless of which platform it lives on. */
+export interface Issue {
+  /** "backend:key", e.g. "jira:PROJ-42" or "github:#7". */
+  ref: string;
+  id: string;
+  key: string;
+  title: string;
+  description?: string;
+  status: Status;
+  /** The backend's own status string, preserved for round-tripping/debugging. */
+  rawStatus?: string;
+  priority: Priority;
+  labels?: string[];
+  assignee?: string;
+  reporter?: string;
+  project?: string;
+  issueType?: string;
+  resolution?: string;
+  parent?: IssueParent;
+  createdAt?: string;
+  updatedAt?: string;
+  url?: string;
+}
+
+export interface CreateInput {
+  title: string;
+  description?: string;
+  status?: Status;
+  priority?: Priority;
+  labels?: string[];
+  assignee?: string;
+  project?: string;
+  issueType?: string;
+  parentKey?: string;
+}
+
+export interface UpdateInput {
+  title?: string;
+  description?: string;
+  status?: Status;
+  priority?: Priority;
+  labels?: string[];
+  assignee?: string;
+  resolution?: string;
+}
+
+export interface ListFilter {
+  project?: string;
+  status?: Status;
+  labels?: string[];
+  assignee?: string;
+  query?: string;
+  limit?: number;
+}
+
+/** "backend:key" ref parsing, split on the first colon only (keys may contain colons). */
+export function parseRef(ref: string): { backend: string; key: string } {
+  const idx = ref.indexOf(":");
+  if (idx <= 0 || idx === ref.length - 1) {
+    throw new Error(`invalid ref ${JSON.stringify(ref)}: expected "backend:key"`);
+  }
+  return { backend: ref.slice(0, idx), key: ref.slice(idx + 1) };
+}
+
+export function makeRef(backend: string, key: string): string {
+  return `${backend}:${key}`;
+}

package/src/index.ts

@@ -0,0 +1,31 @@
+export * from "./domain/issue.js";
+export * from "./ports/repository.js";
+export * from "./adapters/errors.js";
+export { GitHubRepository, type GitHubOptions } from "./adapters/github.js";
+export { GitLabRepository, type GitLabOptions } from "./adapters/gitlab.js";
+export { JiraRepository, type JiraOptions } from "./adapters/jira.js";
+export { TicketService, UnknownBackendError, NotSupportedError } from "./application/service.js";
+export {
+  type BackendConfig,
+  type Config,
+  loadConfig,
+  buildRepositories,
+  defaultConfigPath,
+  configDir,
+} from "./config/config.js";
+export type { TicketOperation, TicketOpInputs, TicketOpOutputs } from "./daemon/ops.js";
+export {
+  createTicketsClient,
+  ensureDaemonRunning,
+  ticketsPaths,
+  type TicketsRpcClient,
+} from "./client/tickets-client.js";
+
+// Delegated OAuth (device flow for GitHub/GitLab, authorization code for Jira)
+// — see RESEARCH.md for why each backend gets a different flow.
+export * from "./auth/device-flow.js";
+export * from "./auth/token-store.js";
+export { openUrl } from "./auth/browser.js";
+export * from "./auth/github-oauth.js";
+export * from "./auth/gitlab-oauth.js";
+export * from "./auth/jira-oauth.js";

package/src/ports/repository.ts

@@ -0,0 +1,27 @@
+/**
+ * Outbound ports — contracts driven adapters (GitHub, GitLab, Jira, ...) implement.
+ * The application layer depends only on these interfaces, never on a concrete adapter.
+ */
+import type { Comment, CreateInput, Issue, ListFilter, UpdateInput } from "../domain/issue.js";
+
+export interface IssueRepository {
+  /** Backend identifier used in refs, e.g. "github", "gitlab", "jira". */
+  readonly name: string;
+
+  list(filter: ListFilter): Promise<Issue[]>;
+  get(key: string): Promise<Issue>;
+  create(input: CreateInput): Promise<Issue>;
+  update(key: string, input: UpdateInput): Promise<Issue>;
+  search(query: string, limit?: number): Promise<Issue[]>;
+  listChildren(key: string): Promise<Issue[]>;
+}
+
+/** Optional capability — not every backend supports comments the same way (all three here do). */
+export interface CommentCapable {
+  listComments(key: string): Promise<Comment[]>;
+  addComment(key: string, body: string): Promise<Comment>;
+}
+
+export function hasComments(repo: IssueRepository): repo is IssueRepository & CommentCapable {
+  return typeof (repo as Partial<CommentCapable>).listComments === "function";
+}

package/src/util/package-root.ts

@@ -0,0 +1,27 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+/**
+ * Walks upward from `startDir` looking for this package's own package.json
+ * (matched by name, not just presence — a consumer's own package.json could
+ * sit above an installed copy). Bounded to `maxLevels` so a misconfigured
+ * install fails fast instead of walking to filesystem root.
+ */
+export function packageRoot(startDir: string, packageName = "@danypops/tickets", maxLevels = 8): string {
+  let dir = startDir;
+  for (let i = 0; i < maxLevels; i++) {
+    const candidate = join(dir, "package.json");
+    if (existsSync(candidate)) {
+      try {
+        const manifest = JSON.parse(readFileSync(candidate, "utf8")) as { name?: string };
+        if (manifest.name === packageName) return dir;
+      } catch {
+        // fall through and keep walking — an unrelated/unparsable package.json
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  throw new Error(`could not locate package root for "${packageName}" above ${startDir}`);
+}