@danypops/tickets 0.1.0 → 0.2.1

package/src/cli/index.ts

@@ -14,6 +14,7 @@ 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";
+import { installTicketsService, systemctlTickets, systemdUnitPath } from "./systemd-service.js";
 
 function printJson(value: unknown): void {
   process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
@@ -31,7 +32,7 @@ async function withClient<T>(fn: (client: TicketsRpcClient) => Promise<T>): Prom
 }
 
 const program = new Command();
-program.name("tickets").description("Unified issue tracking CLI (GitHub, GitLab, Jira)").version("0.1.0");
+program.name("tickets").description("Unified issue tracking CLI (GitHub, GitLab, Jira)").version("0.2.0");
 
 program
   .command("list")
@@ -156,6 +157,43 @@ program
     await withClient((client) => client.call("backends.list", {}));
   });
 
+const focus = program.command("focus").description("track the single ticket you're currently working on, with its full URL");
+
+focus
+  .command("set <ref>")
+  .description('focus a ticket, e.g. "jira:PROJ-42" or "github:#7" (resolves and stores its real web URL)')
+  .action(async (ref: string) => {
+    await withClient((client) => client.call("focus.set", { ref }));
+  });
+
+focus
+  .command("get")
+  .description("show the currently focused ticket, if any")
+  .action(async () => {
+    await withClient((client) => client.call("focus.get", {}));
+  });
+
+focus
+  .command("pause [reason]")
+  .description("pause the current focus without losing it (e.g. stepping away to do something else)")
+  .action(async (reason: string | undefined) => {
+    await withClient((client) => client.call("focus.pause", { reason }));
+  });
+
+focus
+  .command("unpause")
+  .description("resume a paused focus")
+  .action(async () => {
+    await withClient((client) => client.call("focus.unpause", {}));
+  });
+
+focus
+  .command("clear")
+  .description("clear the current focus")
+  .action(async () => {
+    await withClient((client) => client.call("focus.clear", {}));
+  });
+
 const daemon = program.command("daemon").description("manage the tickets daemon process");
 
 daemon
@@ -218,6 +256,44 @@ daemon
     }
   });
 
+const service = program
+  .command("service")
+  .description("deploy the tickets daemon as a persistent systemd --user service (Linux; survives logout/reboot, unlike `daemon start`'s on-demand spawn)");
+
+service
+  .command("install")
+  .description("write, enable, and (re)start a tickets-daemon.service systemd --user unit pointed at this install")
+  .action(() => {
+    try {
+      const { unitPath } = installTicketsService();
+      printJson({ status: "installed", unitPath });
+    } catch (err) {
+      process.stderr.write(`error: ${err instanceof Error ? err.message : String(err)}\n`);
+      process.exitCode = 1;
+    }
+  });
+
+for (const action of ["start", "stop", "restart", "status"] as const) {
+  service
+    .command(action)
+    .description(`systemctl --user ${action} tickets-daemon.service`)
+    .action(() => {
+      try {
+        systemctlTickets(action);
+      } catch (err) {
+        process.stderr.write(`error: ${err instanceof Error ? err.message : String(err)}\n`);
+        process.exitCode = 1;
+      }
+    });
+}
+
+service
+  .command("path")
+  .description("print where the systemd unit file would be written")
+  .action(() => {
+    printJson({ unitPath: systemdUnitPath() });
+  });
+
 const auth = program.command("auth").description("delegated OAuth login (device flow for GitHub/GitLab, authorization code for Jira)");
 
 auth

package/src/cli/systemd-service.ts

@@ -0,0 +1,97 @@
+/**
+ * Deploys the tickets daemon as a persistent systemd --user service, so it
+ * survives logout/reboot instead of only existing for as long as some CLI
+ * command's on-demand auto-spawn keeps it alive. Mirrors papyrus's own
+ * `papyrus service <install|start|stop|restart|status>` pattern exactly
+ * (see ~/Projects/papyrus/src/cli.ts) -- same shape, same systemctl --user
+ * verbs, same install order (write unit -> daemon-reload -> enable ->
+ * restart). Every side effect (file write, directory creation, systemctl
+ * invocation) is injectable so this is fully testable without touching a
+ * real filesystem or spawning a real systemctl process.
+ */
+import { execFileSync } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { resolveDaemonEntryPath } from "../client/tickets-client.js";
+import { TICKETS_DAEMON_NAMES } from "../daemon/ops.js";
+
+export interface SystemdUnitOptions {
+  bunBin: string;
+  daemonMainPath: string;
+}
+
+export function renderSystemdUnit(options: SystemdUnitOptions): string {
+  return `[Unit]
+Description=Tickets daemon -- unified GitHub/GitLab/Jira issue tracking
+After=default.target
+
+[Service]
+Type=simple
+ExecStart=${options.bunBin} run ${options.daemonMainPath}
+Restart=always
+RestartSec=2
+
+[Install]
+WantedBy=default.target
+`;
+}
+
+/** XDG_CONFIG_HOME/systemd/user/tickets-daemon.service, falling back to ~/.config like systemd itself does. */
+export function systemdUnitPath(env: Record<string, string | undefined> = process.env): string {
+  const configHome = env.XDG_CONFIG_HOME ?? join(env.HOME ?? "", ".config");
+  return join(configHome, "systemd", "user", TICKETS_DAEMON_NAMES.systemdUnitName);
+}
+
+export type CommandRunner = (command: string, args: string[]) => void;
+
+const defaultRunner: CommandRunner = (command, args) => {
+  try {
+    execFileSync(command, args, { stdio: "inherit" });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`${command} ${args.join(" ")} failed (is systemd --user available? this feature is Linux-only): ${message}`);
+  }
+};
+
+export type SystemctlAction = "start" | "stop" | "restart" | "status" | "enable" | "daemon-reload";
+
+/** Always targets the tickets unit name under --user scope; daemon-reload takes no unit argument. */
+export function systemctlTickets(action: SystemctlAction, runner: CommandRunner = defaultRunner): void {
+  const args = action === "daemon-reload" ? ["--user", "daemon-reload"] : ["--user", action, TICKETS_DAEMON_NAMES.systemdUnitName];
+  runner("systemctl", args);
+}
+
+export interface InstallOptions {
+  bunBin?: string;
+  daemonMainPath?: string;
+  env?: Record<string, string | undefined>;
+  runner?: CommandRunner;
+  writeFile?: (path: string, content: string) => void;
+  ensureDir?: (path: string) => void;
+}
+
+/**
+ * Writes the unit file, then daemon-reload -> enable -> restart, in that
+ * order -- systemd must see the file before enable/restart can act on it,
+ * and restart (not start) so re-running install after an upgrade picks up
+ * a changed ExecStart path immediately rather than requiring a manual stop.
+ */
+export function installTicketsService(opts: InstallOptions = {}): { unitPath: string } {
+  const unitPath = systemdUnitPath(opts.env);
+  const ensureDir = opts.ensureDir ?? ((dir: string) => mkdirSync(dir, { recursive: true }));
+  const writeFile = opts.writeFile ?? writeFileSync;
+  const runner = opts.runner ?? defaultRunner;
+
+  ensureDir(dirname(unitPath));
+  writeFile(
+    unitPath,
+    renderSystemdUnit({
+      bunBin: opts.bunBin ?? process.execPath,
+      daemonMainPath: opts.daemonMainPath ?? resolveDaemonEntryPath(),
+    }),
+  );
+  systemctlTickets("daemon-reload", runner);
+  systemctlTickets("enable", runner);
+  systemctlTickets("restart", runner);
+  return { unitPath };
+}

package/src/client/tickets-client.ts

@@ -29,10 +29,14 @@ async function isAlive(handle: DaemonHandle, token: string): Promise<boolean> {
   }
 }
 
-function spawnDaemon(): void {
+/** Absolute path to the daemon's real entry point, resolved from this package's own root. Used both to spawn it on demand and to point a systemd unit's ExecStart at it (see cli/systemd-service.ts). */
+export function resolveDaemonEntryPath(): string {
   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" });
+  return join(root, "src", "daemon", "main.ts");
+}
+
+function spawnDaemon(): void {
+  const child = spawn("bun", ["run", resolveDaemonEntryPath()], { detached: true, stdio: "ignore" });
   child.unref();
 }
 

package/src/config/config.ts

@@ -12,6 +12,7 @@ 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";
+import { type TryEnigmaCredential, tryEnigmaCredential } from "../auth/enigma-source.js";
 
 export interface BackendConfig {
   /** Adapter type: "github" | "gitlab" | "jira". Falls back to the config key when omitted. */
@@ -55,19 +56,27 @@ function resolveToken(cfg: BackendConfig, env: NodeJS.ProcessEnv, envFallback: s
 }
 
 /**
- * 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).
+ * Resolution order, highest priority first: (1) a running Enigma vault, if
+ * one happens to be configured for this backend — entirely optional, never a
+ * hard dependency, and bounded so Tickets never waits long for it (see
+ * auth/enigma-source.ts); (2) a locally stored, still-fresh delegated OAuth
+ * token (see auth/token-store.ts, populated by `tickets auth login`); (3) a
+ * static config/env PAT. (1) is additive to the pre-Enigma precedence this
+ * project already followed 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(
+export async function preferredAuth(
   name: string,
   cfg: BackendConfig,
   env: NodeJS.ProcessEnv,
   envFallback: string,
-): { token: string | undefined; oauth: boolean; extra?: Record<string, string> } {
+  tryEnigma: TryEnigmaCredential = tryEnigmaCredential,
+): Promise<{ token: string | undefined; oauth: boolean; extra?: Record<string, string> }> {
+  const fromEnigma = await tryEnigma(name, { env });
+  if (fromEnigma) return { token: fromEnigma.accessToken, oauth: true, extra: fromEnigma.extra };
+
   const stored = loadToken(name, { env });
   if (stored && isTokenFresh(stored)) {
     return { token: stored.accessToken, oauth: true, extra: stored.extra };
@@ -80,45 +89,47 @@ function preferredAuth(
  * 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(
+export async function buildRepositories(
   config: Config,
   env: NodeJS.ProcessEnv = process.env,
-): Record<string, IssueRepository> {
+  tryEnigma: TryEnigmaCredential = tryEnigmaCredential,
+): Promise<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);
+    const repo = await createRepository(name, type, cfg, env, tryEnigma);
     if (repo) repos[name] = repo;
   }
 
   if (!repos.github && (env.GITHUB_OWNER || env.GITHUB_TOKEN)) {
-    const repo = createRepository("github", "github", {}, env);
+    const repo = await createRepository("github", "github", {}, env, tryEnigma);
     if (repo) repos.github = repo;
   }
   if (!repos.gitlab && (env.GITLAB_PROJECT || env.GITLAB_TOKEN)) {
-    const repo = createRepository("gitlab", "gitlab", {}, env);
+    const repo = await createRepository("gitlab", "gitlab", {}, env, tryEnigma);
     if (repo) repos.gitlab = repo;
   }
   if (!repos.jira && env.JIRA_URL) {
-    const repo = createRepository("jira", "jira", {}, env);
+    const repo = await createRepository("jira", "jira", {}, env, tryEnigma);
     if (repo) repos.jira = repo;
   }
 
   return repos;
 }
 
-function createRepository(
+async function createRepository(
   name: string,
   type: string,
   cfg: BackendConfig,
   env: NodeJS.ProcessEnv,
-): IssueRepository | undefined {
+  tryEnigma: TryEnigmaCredential,
+): Promise<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");
+      const auth = await preferredAuth(name, cfg, env, "GITHUB_TOKEN", tryEnigma);
       return new GitHubRepository(name, {
         owner,
         repo: cfg.repo ?? env.GITHUB_REPO,
@@ -129,7 +140,7 @@ function createRepository(
     case "gitlab": {
       const project = cfg.project ?? env.GITLAB_PROJECT;
       if (!project) return undefined;
-      const auth = preferredAuth(name, cfg, env, "GITLAB_TOKEN");
+      const auth = await preferredAuth(name, cfg, env, "GITLAB_TOKEN", tryEnigma);
       return new GitLabRepository(name, {
         projectId: project,
         token: auth.token,
@@ -138,7 +149,7 @@ function createRepository(
       });
     }
     case "jira": {
-      const auth = preferredAuth(name, cfg, env, "JIRA_API_TOKEN");
+      const auth = await preferredAuth(name, cfg, env, "JIRA_API_TOKEN", tryEnigma);
       if (auth.oauth && auth.token && auth.extra?.cloudId) {
         return new JiraRepository(name, {
           accessToken: auth.token,

package/src/daemon/bootstrap.ts

@@ -13,6 +13,7 @@ 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 { FOCUS_MIGRATIONS, FocusStore } from "./focus.js";
 import { Ledger, LEDGER_MIGRATIONS } from "./ledger.js";
 import { TICKETS_DAEMON_NAMES } from "./ops.js";
 import { buildApp } from "./server.js";
@@ -39,6 +40,7 @@ export interface BootstrapOptions {
 export interface BootstrappedDaemon {
   db: Database;
   ledger: Ledger;
+  focusStore: FocusStore;
   service: TicketService;
   options: StartDaemonOptions;
 }
@@ -46,13 +48,14 @@ export interface BootstrappedDaemon {
 const DEFAULT_SYNC_INTERVAL_MS = 5 * 60_000;
 const DEFAULT_CHECKPOINT_INTERVAL_MS = 10 * 60_000;
 
-export function bootstrap(opts: BootstrapOptions = {}): BootstrappedDaemon {
+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 });
+  const db = openSqliteWithPragmas(paths.database, { migrations: [...LEDGER_MIGRATIONS, ...FOCUS_MIGRATIONS] });
   const ledger = new Ledger(db);
+  const focusStore = new FocusStore(db);
   const logger = opts.logger ?? createLogger("tickets-daemon", { levelEnvVar: "TICKETS_LOG_LEVEL" });
-  const repos = opts.repos ?? buildRepositories(opts.config ?? loadConfig());
+  const repos = opts.repos ?? (await buildRepositories(opts.config ?? loadConfig()));
   const service = new TicketService(repos);
   const version = opts.version ?? "0.0.0-dev";
 
@@ -72,6 +75,7 @@ export function bootstrap(opts: BootstrapOptions = {}): BootstrappedDaemon {
       buildApp({
         service,
         ledger,
+        focusStore,
         token,
         version,
         logger,
@@ -82,5 +86,5 @@ export function bootstrap(opts: BootstrapOptions = {}): BootstrappedDaemon {
     },
   };
 
-  return { db, ledger, service, options };
+  return { db, ledger, focusStore, service, options };
 }

package/src/daemon/focus.ts

@@ -0,0 +1,126 @@
+/**
+ * Focus — the single ticket currently being worked on, independent of any
+ * one CLI invocation or tool call. Unlike the Ledger (a cache of every issue
+ * the daemon has ever seen), Focus is a pointer: one ref, its resolved title
+ * and full web URL, and whether work on it is active or paused. Persisted
+ * so it survives daemon restarts. A singleton by design — there is never
+ * more than one ticket in focus at a time, so setting focus always replaces
+ * whatever was there, the same way switching your attention to a different
+ * ticket in real life replaces what you were just looking at.
+ */
+import type { Database } from "bun:sqlite";
+import type { Migration } from "@danypops/daemon-kit/storage";
+
+export const FOCUS_MIGRATIONS: Migration[] = [
+  {
+    version: 2,
+    up: (db) => {
+      db.exec(`
+        CREATE TABLE ticket_focus (
+          id INTEGER PRIMARY KEY CHECK (id = 1),
+          ref TEXT NOT NULL,
+          title TEXT NOT NULL,
+          url TEXT NOT NULL,
+          status TEXT NOT NULL,
+          pause_reason TEXT,
+          updated_at TEXT NOT NULL
+        );
+      `);
+    },
+  },
+];
+
+export type FocusStatus = "active" | "paused";
+
+export interface TicketFocusState {
+  ref: string;
+  title: string;
+  url: string;
+  status: FocusStatus;
+  updatedAt: string;
+  pauseReason?: string;
+}
+
+/** Invalid focus state transitions (nothing focused, double-pause, double-unpause) or a resolved issue with no URL to focus on. Maps to HTTP 400, not 500. */
+export class FocusError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "FocusError";
+  }
+}
+
+interface FocusRow {
+  ref: string;
+  title: string;
+  url: string;
+  status: FocusStatus;
+  pause_reason: string | null;
+  updated_at: string;
+}
+
+function rowToState(row: FocusRow): TicketFocusState {
+  return {
+    ref: row.ref,
+    title: row.title,
+    url: row.url,
+    status: row.status,
+    updatedAt: row.updated_at,
+    ...(row.pause_reason ? { pauseReason: row.pause_reason } : {}),
+  };
+}
+
+export class FocusStore {
+  constructor(private readonly db: Database) {}
+
+  get(): TicketFocusState | undefined {
+    const row = this.db
+      .query("SELECT ref, title, url, status, pause_reason, updated_at FROM ticket_focus WHERE id = 1")
+      .get() as FocusRow | null;
+    return row ? rowToState(row) : undefined;
+  }
+
+  /** Always lands "active" and drops any prior pause reason: switching focus onto a different ticket is not the same as resuming a pause on the old one. */
+  set(ref: string, title: string, url: string): TicketFocusState {
+    const updatedAt = new Date().toISOString();
+    this.db
+      .query(
+        `INSERT INTO ticket_focus (id, ref, title, url, status, pause_reason, updated_at)
+         VALUES (1, $ref, $title, $url, 'active', NULL, $updatedAt)
+         ON CONFLICT(id) DO UPDATE SET
+           ref = excluded.ref, title = excluded.title, url = excluded.url,
+           status = 'active', pause_reason = NULL, updated_at = excluded.updated_at`,
+      )
+      .run({ $ref: ref, $title: title, $url: url, $updatedAt: updatedAt });
+    return { ref, title, url, status: "active", updatedAt };
+  }
+
+  pause(reason?: string): TicketFocusState {
+    const current = this.get();
+    if (!current) throw new FocusError("no ticket is currently focused");
+    if (current.status === "paused") throw new FocusError(`focus on "${current.ref}" is already paused`);
+    return this.transition("paused", reason);
+  }
+
+  unpause(): TicketFocusState {
+    const current = this.get();
+    if (!current) throw new FocusError("no ticket is currently focused");
+    if (current.status === "active") throw new FocusError(`focus on "${current.ref}" is already active`);
+    return this.transition("active", undefined);
+  }
+
+  /** Returns whether a focus existed to clear (idempotent either way). */
+  clear(): boolean {
+    const existed = this.get() !== undefined;
+    this.db.exec("DELETE FROM ticket_focus WHERE id = 1");
+    return existed;
+  }
+
+  private transition(status: FocusStatus, reason: string | undefined): TicketFocusState {
+    const updatedAt = new Date().toISOString();
+    this.db
+      .query("UPDATE ticket_focus SET status = $status, pause_reason = $reason, updated_at = $updatedAt WHERE id = 1")
+      .run({ $status: status, $reason: reason ?? null, $updatedAt: updatedAt });
+    // Non-null: transition() is only ever called right after get() confirmed a row exists.
+    return this.get()!;
+  }
+}

package/src/daemon/main.ts

@@ -10,7 +10,7 @@ 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 });
+const { options } = await bootstrap({ version });
 
 runDaemonProcess({
   ...options,

package/src/daemon/ops.ts

@@ -5,6 +5,7 @@
  * import from either side without pulling in bun:sqlite or Bun.serve.
  */
 import type { Comment, CreateInput, Issue, ListFilter, UpdateInput } from "../domain/issue.js";
+import type { TicketFocusState } from "./focus.js";
 
 export type TicketOperation =
   | "backends.list"
@@ -18,6 +19,11 @@ export type TicketOperation =
   | "issue.comment_add"
   | "ledger.search"
   | "ledger.stats"
+  | "focus.set"
+  | "focus.get"
+  | "focus.pause"
+  | "focus.unpause"
+  | "focus.clear"
   | "daemon.shutdown";
 
 export interface TicketOpInputs extends Record<TicketOperation, unknown> {
@@ -32,6 +38,11 @@ export interface TicketOpInputs extends Record<TicketOperation, unknown> {
   "issue.comment_add": { ref: string; body: string };
   "ledger.search": { query: string; limit?: number };
   "ledger.stats": Record<string, never>;
+  "focus.set": { ref: string };
+  "focus.get": Record<string, never>;
+  "focus.pause": { reason?: string };
+  "focus.unpause": Record<string, never>;
+  "focus.clear": Record<string, never>;
   "daemon.shutdown": Record<string, never>;
 }
 
@@ -47,6 +58,11 @@ export interface TicketOpOutputs extends Record<TicketOperation, unknown> {
   "issue.comment_add": { comment: Comment };
   "ledger.search": { issues: Issue[] };
   "ledger.stats": { backends: { backend: string; count: number }[] };
+  "focus.set": { focus: TicketFocusState };
+  "focus.get": { focus: TicketFocusState | null };
+  "focus.pause": { focus: TicketFocusState };
+  "focus.unpause": { focus: TicketFocusState };
+  "focus.clear": { cleared: boolean };
   "daemon.shutdown": { stopping: true };
 }
 
@@ -62,6 +78,11 @@ export const TICKET_OPERATIONS: TicketOperation[] = [
   "issue.comment_add",
   "ledger.search",
   "ledger.stats",
+  "focus.set",
+  "focus.get",
+  "focus.pause",
+  "focus.unpause",
+  "focus.clear",
   "daemon.shutdown",
 ];
 

package/src/daemon/server.ts

@@ -8,12 +8,15 @@ import { errorResponse, healthResponse, jsonResponse, readyResponse, requireBear
 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 { 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";
 
 export interface TicketsAppDeps {
   service: TicketService;
   ledger: Ledger;
+  focusStore: FocusStore;
   token: string;
   version: string;
   logger?: Logger;
@@ -44,6 +47,22 @@ const handlers: { [Op in TicketOperation]: Handler<Op> } = {
   "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() }),
+  "focus.set": async (deps, input) => {
+    // Ledger-first: focusing a ticket already pooled locally needs no live
+    // backend call. Otherwise fall back to a live get (also validates the
+    // ref actually exists) and opportunistically warm the ledger with it,
+    // since a ticket you're about to focus on is exactly the kind of issue
+    // worth having cached locally.
+    const cached = deps.ledger.get(input.ref);
+    const issue = cached ?? (await deps.service.get(input.ref));
+    if (!cached) deps.ledger.upsert(parseRef(input.ref).backend, issue);
+    if (!issue.url) throw new FocusError(`issue "${input.ref}" has no URL from its backend; cannot focus without a full link`);
+    return { focus: deps.focusStore.set(input.ref, issue.title, issue.url) };
+  },
+  "focus.get": async (deps) => ({ focus: deps.focusStore.get() ?? null }),
+  "focus.pause": async (deps, input) => ({ focus: deps.focusStore.pause(input.reason) }),
+  "focus.unpause": async (deps) => ({ focus: deps.focusStore.unpause() }),
+  "focus.clear": async (deps) => ({ cleared: deps.focusStore.clear() }),
   "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.
@@ -58,7 +77,7 @@ function isTicketOperation(value: unknown): value is TicketOperation {
 
 function statusFor(error: unknown): number {
   if (error instanceof IssueNotFoundError) return 404;
-  if (error instanceof UnknownBackendError || error instanceof NotSupportedError) return 400;
+  if (error instanceof UnknownBackendError || error instanceof NotSupportedError || error instanceof FocusError) return 400;
   if (error instanceof AuthRequiredError) return 422;
   return 500;
 }

package/src/domain/issue.ts

@@ -79,6 +79,8 @@ export interface CreateInput {
   project?: string;
   issueType?: string;
   parentKey?: string;
+  /** Backend-specific custom fields keyed by display name (e.g. Jira's "QE Priority"), resolved to the backend's own field ID by the adapter. Not every backend supports this (only Jira does today). */
+  customFields?: Record<string, string>;
 }
 
 export interface UpdateInput {
@@ -89,6 +91,8 @@ export interface UpdateInput {
   labels?: string[];
   assignee?: string;
   resolution?: string;
+  /** Backend-specific custom fields keyed by display name (e.g. Jira's "QE Priority"), resolved to the backend's own field ID by the adapter. Not every backend supports this (only Jira does today). */
+  customFields?: Record<string, string>;
 }
 
 export interface ListFilter {

package/src/index.ts

@@ -14,10 +14,12 @@ export {
   configDir,
 } from "./config/config.js";
 export type { TicketOperation, TicketOpInputs, TicketOpOutputs } from "./daemon/ops.js";
+export type { FocusStatus, TicketFocusState } from "./daemon/focus.js";
 export {
   createTicketsClient,
   ensureDaemonRunning,
   ticketsPaths,
+  type EnsureDaemonOptions,
   type TicketsRpcClient,
 } from "./client/tickets-client.js";