@danypops/tickets 0.1.0

package/src/cli/index.ts

@@ -0,0 +1,337 @@
+#!/usr/bin/env bun
+/**
+ * The tickets CLI is a thin client of the tickets daemon: every command maps
+ * 1:1 to a daemon RPC op (see daemon/ops.ts and daemon/server.ts), the same
+ * ops the pi-tickets extension calls. Nothing here opens the daemon's SQLite
+ * ledger or a backend adapter directly.
+ */
+import { Command } from "commander";
+import type { CreateInput, ListFilter, Priority, Status, UpdateInput } from "../domain/issue.js";
+import { parseStatus } from "../domain/issue.js";
+import { createTicketsClient, type TicketsRpcClient } from "../client/tickets-client.js";
+import { openUrl } from "../auth/browser.js";
+import { loginWithGitHubDeviceFlow } from "../auth/github-oauth.js";
+import { gitlabDeviceEndpoints, loginWithGitLabDeviceFlow } from "../auth/gitlab-oauth.js";
+import { loginWithJiraAuthorizationCode } from "../auth/jira-oauth.js";
+import { deleteToken, isTokenFresh, listStoredBackends, loadToken, saveToken } from "../auth/token-store.js";
+
+function printJson(value: unknown): void {
+  process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+
+async function withClient<T>(fn: (client: TicketsRpcClient) => Promise<T>): Promise<void> {
+  try {
+    const client = await createTicketsClient();
+    printJson(await fn(client));
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`error: ${message}\n`);
+    process.exitCode = 1;
+  }
+}
+
+const program = new Command();
+program.name("tickets").description("Unified issue tracking CLI (GitHub, GitLab, Jira)").version("0.1.0");
+
+program
+  .command("list")
+  .description("list issues on a backend")
+  .requiredOption("-b, --backend <name>", "backend name")
+  .option("--status <status>", "filter by status")
+  .option("--assignee <user>", "filter by assignee")
+  .option("--label <label...>", "filter by label(s)")
+  .option("--limit <n>", "max results", (v) => Number.parseInt(v, 10))
+  .action(async (opts) => {
+    const filter: ListFilter = {
+      status: opts.status ? parseStatus(opts.status) : undefined,
+      assignee: opts.assignee,
+      labels: opts.label,
+      limit: opts.limit,
+    };
+    await withClient((client) => client.call("issue.list", { backend: opts.backend, filter }));
+  });
+
+program
+  .command("get <ref>")
+  .description('get one issue, e.g. "jira:PROJ-42" or "github:#7"')
+  .action(async (ref: string) => {
+    await withClient((client) => client.call("issue.get", { ref }));
+  });
+
+program
+  .command("create <title>")
+  .description("create an issue")
+  .requiredOption("-b, --backend <name>", "backend name")
+  .option("--description <text>", "issue description")
+  .option("--priority <priority>", "priority: none|urgent|high|medium|low")
+  .option("--label <label...>", "label(s)")
+  .option("--assignee <user>", "assignee")
+  .option("--project <project>", "project key/id override")
+  .action(async (title: string, opts) => {
+    const input: CreateInput = {
+      title,
+      description: opts.description,
+      priority: opts.priority as Priority | undefined,
+      labels: opts.label,
+      assignee: opts.assignee,
+      project: opts.project,
+    };
+    await withClient((client) => client.call("issue.create", { backend: opts.backend, input }));
+  });
+
+program
+  .command("update <ref>")
+  .description("update an issue")
+  .option("--title <text>", "new title")
+  .option("--description <text>", "new description")
+  .option("--status <status>", "new status")
+  .option("--priority <priority>", "new priority")
+  .option("--label <label...>", "replace labels")
+  .option("--assignee <user>", "reassign (empty string to unassign)")
+  .action(async (ref: string, opts) => {
+    const input: UpdateInput = {
+      title: opts.title,
+      description: opts.description,
+      status: opts.status ? parseStatus(opts.status) : (undefined as Status | undefined),
+      priority: opts.priority as Priority | undefined,
+      labels: opts.label,
+      assignee: opts.assignee,
+    };
+    await withClient((client) => client.call("issue.update", { ref, input }));
+  });
+
+program
+  .command("search <query>")
+  .description("search issues on a backend")
+  .requiredOption("-b, --backend <name>", "backend name")
+  .option("--limit <n>", "max results", (v) => Number.parseInt(v, 10))
+  .action(async (query: string, opts) => {
+    await withClient((client) => client.call("issue.search", { backend: opts.backend, query, limit: opts.limit }));
+  });
+
+program
+  .command("children <ref>")
+  .description("list child issues (Jira sub-tasks/epics; empty on backends without native sub-issues)")
+  .action(async (ref: string) => {
+    await withClient((client) => client.call("issue.children", { ref }));
+  });
+
+const comment = program.command("comment").description("comment operations");
+
+comment
+  .command("list <ref>")
+  .description("list comments on an issue")
+  .action(async (ref: string) => {
+    await withClient((client) => client.call("issue.comments", { ref }));
+  });
+
+comment
+  .command("add <ref> <body>")
+  .description("add a comment to an issue")
+  .action(async (ref: string, body: string) => {
+    await withClient((client) => client.call("issue.comment_add", { ref, body }));
+  });
+
+const ledger = program.command("ledger").description("query the daemon's locally pooled issue cache");
+
+ledger
+  .command("search <query>")
+  .description("search the local ledger (works even if the backend is currently unreachable)")
+  .option("--limit <n>", "max results", (v) => Number.parseInt(v, 10))
+  .action(async (query: string, opts) => {
+    await withClient((client) => client.call("ledger.search", { query, limit: opts.limit }));
+  });
+
+ledger
+  .command("stats")
+  .description("issue counts per backend in the local ledger")
+  .action(async () => {
+    await withClient((client) => client.call("ledger.stats", {}));
+  });
+
+program
+  .command("backends")
+  .description("list configured backend names")
+  .action(async () => {
+    await withClient((client) => client.call("backends.list", {}));
+  });
+
+const daemon = program.command("daemon").description("manage the tickets daemon process");
+
+daemon
+  .command("status")
+  .description("check whether the tickets daemon is reachable (never auto-starts it)")
+  .action(async () => {
+    try {
+      const client = await createTicketsClient({ autoStart: false });
+      printJson({ reachable: true, ...(await client.health()) });
+    } catch (err) {
+      printJson({ reachable: false, error: err instanceof Error ? err.message : String(err) });
+    }
+  });
+
+daemon
+  .command("start")
+  .description("start the daemon if it isn't already running")
+  .action(async () => {
+    try {
+      const client = await createTicketsClient({ autoStart: true });
+      printJson({ status: "running", ...(await client.health()) });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      process.stderr.write(`error: ${message}\n`);
+      process.exitCode = 1;
+    }
+  });
+
+daemon
+  .command("stop")
+  .description("ask the running daemon to shut down gracefully")
+  .action(async () => {
+    try {
+      const client = await createTicketsClient({ autoStart: false });
+      await client.call("daemon.shutdown", {});
+      printJson({ status: "stopping" });
+    } catch (err) {
+      printJson({ status: "not_running", detail: err instanceof Error ? err.message : String(err) });
+    }
+  });
+
+daemon
+  .command("restart")
+  .description("stop the daemon (if running) and start a fresh one")
+  .action(async () => {
+    try {
+      const client = await createTicketsClient({ autoStart: false });
+      await client.call("daemon.shutdown", {});
+    } catch {
+      // not running — nothing to stop, proceed straight to starting a fresh one.
+    }
+    await new Promise((resolve) => setTimeout(resolve, 300));
+    try {
+      const client = await createTicketsClient({ autoStart: true });
+      printJson({ status: "restarted", ...(await client.health()) });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      process.stderr.write(`error: ${message}\n`);
+      process.exitCode = 1;
+    }
+  });
+
+const auth = program.command("auth").description("delegated OAuth login (device flow for GitHub/GitLab, authorization code for Jira)");
+
+auth
+  .command("login")
+  .description("authorize tickets against a backend and store the resulting token locally (0600, never printed)")
+  .requiredOption("-b, --backend <name>", "github | gitlab | jira (or a custom multi-instance name, paired with --type)")
+  .option("--type <type>", "adapter type, when --backend is a custom multi-instance name")
+  .option("--client-id <id>", "OAuth client/application ID (falls back to <TYPE>_OAUTH_CLIENT_ID)")
+  .option("--client-secret <secret>", "OAuth client secret (Jira only — GitHub/GitLab device flow needs none)")
+  .option("--url <baseUrl>", "self-managed GitLab URL (defaults to gitlab.com)")
+  .option("--scope <scope>", "space-delimited OAuth scope override")
+  .action(async (opts) => {
+    const type = opts.type ?? opts.backend;
+    try {
+      if (type === "github") {
+        const clientId = opts.clientId ?? process.env.GITHUB_OAUTH_CLIENT_ID;
+        if (!clientId) throw new Error("--client-id or GITHUB_OAUTH_CLIENT_ID is required");
+        const token = await loginWithGitHubDeviceFlow({
+          clientId,
+          scope: opts.scope,
+          onPrompt: async (prompt) => {
+            process.stderr.write(`Open ${prompt.verificationUri} and enter code: ${prompt.userCode}\n`);
+            try {
+              openUrl(prompt.verificationUriComplete ?? prompt.verificationUri);
+            } catch {
+              // headless environment — the printed URL/code above is still enough to proceed manually.
+            }
+          },
+        });
+        saveToken(opts.backend, { accessToken: token.accessToken, refreshToken: token.refreshToken, expiresAt: token.expiresAt, scope: token.scope });
+      } else if (type === "gitlab") {
+        const clientId = opts.clientId ?? process.env.GITLAB_OAUTH_CLIENT_ID;
+        if (!clientId) throw new Error("--client-id or GITLAB_OAUTH_CLIENT_ID is required");
+        const baseUrl = opts.url ?? process.env.GITLAB_URL;
+        const token = await loginWithGitLabDeviceFlow({
+          clientId,
+          baseUrl,
+          scope: opts.scope,
+          onPrompt: async (prompt) => {
+            process.stderr.write(`Open ${prompt.verificationUri} and enter code: ${prompt.userCode}\n`);
+            try {
+              openUrl(prompt.verificationUriComplete ?? prompt.verificationUri);
+            } catch {
+              // headless environment — printed instructions above are enough.
+            }
+          },
+        });
+        saveToken(opts.backend, { accessToken: token.accessToken, refreshToken: token.refreshToken, expiresAt: token.expiresAt, scope: token.scope });
+      } else if (type === "jira") {
+        const clientId = opts.clientId ?? process.env.JIRA_OAUTH_CLIENT_ID;
+        const clientSecret = opts.clientSecret ?? process.env.JIRA_OAUTH_CLIENT_SECRET;
+        if (!clientId || !clientSecret) {
+          throw new Error("--client-id/--client-secret or JIRA_OAUTH_CLIENT_ID/JIRA_OAUTH_CLIENT_SECRET are required (Atlassian 3LO has no public-client flow)");
+        }
+        const token = await loginWithJiraAuthorizationCode({
+          clientId,
+          clientSecret,
+          scope: opts.scope,
+          onPrompt: async (authorizeUrl) => {
+            process.stderr.write(`Open this URL to authorize tickets against your Atlassian site:\n${authorizeUrl}\n`);
+            try {
+              openUrl(authorizeUrl);
+            } catch {
+              // headless environment — the printed URL above is enough to proceed manually.
+            }
+          },
+        });
+        saveToken(opts.backend, {
+          accessToken: token.accessToken,
+          refreshToken: token.refreshToken,
+          expiresAt: token.expiresAt,
+          extra: { cloudId: token.cloudId, siteUrl: token.siteUrl },
+        });
+      } else {
+        throw new Error(`auth login: unsupported type "${type}" (expected github, gitlab, or jira)`);
+      }
+      printJson({
+        backend: opts.backend,
+        status: "authorized",
+        note: "restart the tickets daemon (or run `tickets daemon-status` after a fresh start) to pick up the new token",
+      });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      process.stderr.write(`error: ${message}\n`);
+      process.exitCode = 1;
+    }
+  });
+
+auth
+  .command("status")
+  .description("list backends with a locally stored delegated token")
+  .action(() => {
+    const backends = listStoredBackends();
+    printJson(
+      backends.map((backend) => {
+        const token = loadToken(backend);
+        return {
+          backend,
+          fresh: token ? isTokenFresh(token) : false,
+          expiresAt: token?.expiresAt ?? null,
+          scope: token?.scope ?? null,
+        };
+      }),
+    );
+  });
+
+auth
+  .command("logout <backend>")
+  .description("remove a backend's locally stored delegated token (falls back to config/env PAT)")
+  .action((backend: string) => {
+    deleteToken(backend);
+    printJson({ backend, status: "logged_out" });
+  });
+
+program.parseAsync(process.argv).catch(() => {
+  process.exitCode = 1;
+});

package/src/client/tickets-client.ts

@@ -0,0 +1,89 @@
+/**
+ * Node/Bun-portable client for the tickets daemon. Neither the CLI nor the
+ * pi-tickets extension opens the daemon's SQLite ledger directly or talks to
+ * GitHub/GitLab/Jira itself — both go through this authenticated RPC client,
+ * spawning the (Bun-only) daemon on first use if it isn't already running.
+ */
+import { spawn } from "node:child_process";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { DaemonHandle } from "@danypops/daemon-kit/paths";
+import { ensureAuthToken, readDaemonHandle, resolveDaemonPaths } from "@danypops/daemon-kit/paths";
+import { AuthenticatedRpcClient } from "@danypops/daemon-kit/rpc-client";
+import { packageRoot } from "../util/package-root.js";
+import { TICKETS_DAEMON_NAMES, type TicketOpInputs, type TicketOperation, type TicketOpOutputs } from "../daemon/ops.js";
+
+export function ticketsPaths(env?: Record<string, string | undefined>) {
+  return resolveDaemonPaths(TICKETS_DAEMON_NAMES, env ? { env } : {});
+}
+
+async function isAlive(handle: DaemonHandle, token: string): Promise<boolean> {
+  try {
+    const res = await fetch(`http://${handle.host}:${handle.port}/health`, {
+      headers: { authorization: `Bearer ${token}` },
+      signal: AbortSignal.timeout(500),
+    });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+function spawnDaemon(): void {
+  const root = packageRoot(dirname(fileURLToPath(import.meta.url)));
+  const entry = join(root, "src", "daemon", "main.ts");
+  const child = spawn("bun", ["run", entry], { detached: true, stdio: "ignore" });
+  child.unref();
+}
+
+async function waitForHandle(handlePath: string, timeoutMs: number): Promise<DaemonHandle | null> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const handle = readDaemonHandle(handlePath);
+    if (handle) return handle;
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  return null;
+}
+
+export interface EnsureDaemonOptions {
+  /** false: fail immediately with a clear message instead of spawning the daemon. */
+  autoStart?: boolean;
+  timeoutMs?: number;
+}
+
+const DEFAULT_SPAWN_TIMEOUT_MS = 4_000;
+
+export async function ensureDaemonRunning(
+  opts: EnsureDaemonOptions = {},
+): Promise<{ baseUrl: string; token: string }> {
+  const paths = ticketsPaths();
+  const token = ensureAuthToken(paths.token, "Tickets");
+
+  const existing = readDaemonHandle(paths.handle);
+  if (existing && (await isAlive(existing, token))) {
+    return { baseUrl: `http://${existing.host}:${existing.port}`, token };
+  }
+
+  if (opts.autoStart === false) {
+    throw new Error(
+      "tickets daemon is not running. Start it with `npm run daemon` (or `bun run src/daemon/main.ts`).",
+    );
+  }
+
+  spawnDaemon();
+  const handle = await waitForHandle(paths.handle, opts.timeoutMs ?? DEFAULT_SPAWN_TIMEOUT_MS);
+  if (!handle || !(await isAlive(handle, token))) {
+    throw new Error("tickets daemon did not become ready within the timeout");
+  }
+  return { baseUrl: `http://${handle.host}:${handle.port}`, token };
+}
+
+export type TicketsRpcClient = AuthenticatedRpcClient<TicketOperation, TicketOpInputs, TicketOpOutputs>;
+
+export async function createTicketsClient(opts: EnsureDaemonOptions = {}): Promise<TicketsRpcClient> {
+  const { baseUrl, token } = await ensureDaemonRunning(opts);
+  return new AuthenticatedRpcClient<TicketOperation, TicketOpInputs, TicketOpOutputs>(baseUrl, token, {
+    label: "Tickets",
+  });
+}

package/src/config/config.ts

@@ -0,0 +1,162 @@
+/**
+ * Configuration loading — mirrors the env-var-first, config-file-override pattern:
+ * $XDG_CONFIG_HOME/tickets/config.yaml (default ~/.config/tickets/config.yaml),
+ * falling back to well-known env vars per backend when no config file is present.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { GitHubRepository } from "../adapters/github.js";
+import { GitLabRepository } from "../adapters/gitlab.js";
+import { JiraRepository } from "../adapters/jira.js";
+import type { IssueRepository } from "../ports/repository.js";
+import { isTokenFresh, loadToken } from "../auth/token-store.js";
+
+export interface BackendConfig {
+  /** Adapter type: "github" | "gitlab" | "jira". Falls back to the config key when omitted. */
+  type?: string;
+  token?: string;
+  tokenEnv?: string;
+  url?: string;
+  email?: string;
+  owner?: string;
+  project?: string;
+  repo?: string;
+}
+
+export interface Config {
+  backends: Record<string, BackendConfig>;
+}
+
+const APP_NAME = "tickets";
+
+export function configDir(): string {
+  const base = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+  return join(base, APP_NAME);
+}
+
+export function defaultConfigPath(): string {
+  return join(configDir(), "config.yaml");
+}
+
+export function loadConfig(path?: string): Config {
+  const target = path ?? defaultConfigPath();
+  if (!existsSync(target)) return { backends: {} };
+  const data = readFileSync(target, "utf8");
+  const parsed = parseYaml(data) as Partial<Config> | undefined;
+  return { backends: parsed?.backends ?? {} };
+}
+
+function resolveToken(cfg: BackendConfig, env: NodeJS.ProcessEnv, envFallback: string): string | undefined {
+  if (cfg.token) return cfg.token;
+  if (cfg.tokenEnv) return env[cfg.tokenEnv];
+  return env[envFallback];
+}
+
+/**
+ * Prefers a locally stored, still-fresh delegated OAuth token (see auth/,
+ * populated by `tickets auth login`) over a static config/env PAT, per the
+ * general "delegated auth over static token" precedence this project follows
+ * for GitHub, GitLab, and Jira — see RESEARCH.md for the auth flows each
+ * backend actually supports (device flow for GitHub/GitLab, authorization
+ * code for Jira, which has no device flow or PKCE).
+ */
+function preferredAuth(
+  name: string,
+  cfg: BackendConfig,
+  env: NodeJS.ProcessEnv,
+  envFallback: string,
+): { token: string | undefined; oauth: boolean; extra?: Record<string, string> } {
+  const stored = loadToken(name, { env });
+  if (stored && isTokenFresh(stored)) {
+    return { token: stored.accessToken, oauth: true, extra: stored.extra };
+  }
+  return { token: resolveToken(cfg, env, envFallback), oauth: false };
+}
+
+/**
+ * Builds one repository per configured backend, plus any of github/gitlab/jira
+ * inferrable purely from environment variables when not present in the config file.
+ * Config-file entries take precedence over bare env-var inference for the same name.
+ */
+export function buildRepositories(
+  config: Config,
+  env: NodeJS.ProcessEnv = process.env,
+): Record<string, IssueRepository> {
+  const repos: Record<string, IssueRepository> = {};
+
+  for (const [name, cfg] of Object.entries(config.backends)) {
+    const type = cfg.type ?? name;
+    const repo = createRepository(name, type, cfg, env);
+    if (repo) repos[name] = repo;
+  }
+
+  if (!repos.github && (env.GITHUB_OWNER || env.GITHUB_TOKEN)) {
+    const repo = createRepository("github", "github", {}, env);
+    if (repo) repos.github = repo;
+  }
+  if (!repos.gitlab && (env.GITLAB_PROJECT || env.GITLAB_TOKEN)) {
+    const repo = createRepository("gitlab", "gitlab", {}, env);
+    if (repo) repos.gitlab = repo;
+  }
+  if (!repos.jira && env.JIRA_URL) {
+    const repo = createRepository("jira", "jira", {}, env);
+    if (repo) repos.jira = repo;
+  }
+
+  return repos;
+}
+
+function createRepository(
+  name: string,
+  type: string,
+  cfg: BackendConfig,
+  env: NodeJS.ProcessEnv,
+): IssueRepository | undefined {
+  switch (type) {
+    case "github": {
+      const owner = cfg.owner ?? env.GITHUB_OWNER;
+      if (!owner) return undefined;
+      const auth = preferredAuth(name, cfg, env, "GITHUB_TOKEN");
+      return new GitHubRepository(name, {
+        owner,
+        repo: cfg.repo ?? env.GITHUB_REPO,
+        token: auth.token,
+        baseUrl: cfg.url,
+      });
+    }
+    case "gitlab": {
+      const project = cfg.project ?? env.GITLAB_PROJECT;
+      if (!project) return undefined;
+      const auth = preferredAuth(name, cfg, env, "GITLAB_TOKEN");
+      return new GitLabRepository(name, {
+        projectId: project,
+        token: auth.token,
+        tokenType: auth.oauth ? "oauth" : "private",
+        baseUrl: cfg.url ?? env.GITLAB_URL,
+      });
+    }
+    case "jira": {
+      const auth = preferredAuth(name, cfg, env, "JIRA_API_TOKEN");
+      if (auth.oauth && auth.token && auth.extra?.cloudId) {
+        return new JiraRepository(name, {
+          accessToken: auth.token,
+          cloudId: auth.extra.cloudId,
+          project: cfg.project ?? env.JIRA_PROJECT,
+        });
+      }
+      const baseUrl = cfg.url ?? env.JIRA_URL;
+      const email = cfg.email ?? env.JIRA_EMAIL;
+      if (!baseUrl || !email || !auth.token) return undefined;
+      return new JiraRepository(name, {
+        baseUrl,
+        email,
+        token: auth.token,
+        project: cfg.project ?? env.JIRA_PROJECT,
+      });
+    }
+    default:
+      return undefined;
+  }
+}

package/src/daemon/bootstrap.ts

@@ -0,0 +1,86 @@
+/**
+ * Composition root for the tickets daemon: wires paths, auth token, ledger
+ * storage, real backend repositories, and the sync poller into the options
+ * daemon-kit's startDaemon()/runDaemonProcess() expect. Everything here is
+ * injectable so tests can substitute fake repositories and a scratch XDG
+ * root instead of hitting real GitHub/GitLab/Jira or the real home directory.
+ */
+import type { Database } from "bun:sqlite";
+import { createLogger, type Logger } from "@danypops/daemon-kit/logging";
+import { ensureAuthToken, type PathEnvironment, resolveDaemonPaths } from "@danypops/daemon-kit/paths";
+import { checkpoint, openSqliteWithPragmas } from "@danypops/daemon-kit/storage";
+import type { StartDaemonOptions } from "@danypops/daemon-kit/daemon";
+import { TicketService } from "../application/service.js";
+import { buildRepositories, type Config, loadConfig } from "../config/config.js";
+import type { IssueRepository } from "../ports/repository.js";
+import { Ledger, LEDGER_MIGRATIONS } from "./ledger.js";
+import { TICKETS_DAEMON_NAMES } from "./ops.js";
+import { buildApp } from "./server.js";
+import { createSyncTask } from "./poller.js";
+
+export interface BootstrapOptions {
+  pathEnv?: PathEnvironment;
+  config?: Config;
+  /** Injected directly in tests instead of building from config/env. */
+  repos?: Record<string, IssueRepository>;
+  version?: string;
+  logger?: Logger;
+  syncIntervalMs?: number;
+  checkpointIntervalMs?: number;
+  /**
+   * Overrides the daemon.shutdown op's effect. Defaults to sending this
+   * process SIGTERM, which daemon-kit's runDaemonProcess already handles
+   * with a tested graceful stop (see main.ts). Tests override this instead
+   * of self-signaling the test runner's own process.
+   */
+  onShutdownRequested?: () => void;
+}
+
+export interface BootstrappedDaemon {
+  db: Database;
+  ledger: Ledger;
+  service: TicketService;
+  options: StartDaemonOptions;
+}
+
+const DEFAULT_SYNC_INTERVAL_MS = 5 * 60_000;
+const DEFAULT_CHECKPOINT_INTERVAL_MS = 10 * 60_000;
+
+export function bootstrap(opts: BootstrapOptions = {}): BootstrappedDaemon {
+  const paths = resolveDaemonPaths(TICKETS_DAEMON_NAMES, opts.pathEnv);
+  const token = ensureAuthToken(paths.token, "Tickets");
+  const db = openSqliteWithPragmas(paths.database, { migrations: LEDGER_MIGRATIONS });
+  const ledger = new Ledger(db);
+  const logger = opts.logger ?? createLogger("tickets-daemon", { levelEnvVar: "TICKETS_LOG_LEVEL" });
+  const repos = opts.repos ?? buildRepositories(opts.config ?? loadConfig());
+  const service = new TicketService(repos);
+  const version = opts.version ?? "0.0.0-dev";
+
+  const options: StartDaemonOptions = {
+    daemonLabel: "Tickets",
+    handlePath: paths.handle,
+    logger,
+    maintenanceTasks: [
+      createSyncTask(service, ledger, Object.keys(repos), opts.syncIntervalMs ?? DEFAULT_SYNC_INTERVAL_MS, logger),
+      {
+        name: "checkpoint",
+        intervalMs: opts.checkpointIntervalMs ?? DEFAULT_CHECKPOINT_INTERVAL_MS,
+        run: () => checkpoint(db),
+      },
+    ],
+    buildApp: () =>
+      buildApp({
+        service,
+        ledger,
+        token,
+        version,
+        logger,
+        onShutdownRequested: opts.onShutdownRequested ?? (() => process.kill(process.pid, "SIGTERM")),
+      }),
+    onShutdown: () => {
+      db.close();
+    },
+  };
+
+  return { db, ledger, service, options };
+}