@danypops/tickets 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Popsuevich
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,196 @@
+# tickets
+
+A unified CLI, daemon, and TypeScript library for issue tracking across
+**GitHub**, **GitLab**, and **Jira** — plus a `pi-tickets` extension so a
+coding agent can query and mutate issues the same way the CLI does.
+
+## Why a daemon
+
+Every backend adapter pools issues into a local SQLite ledger on its own
+schedule, independent of whether anything is currently asking for data —
+`tickets ledger search`/`ledger stats` and the ledger ops still answer from
+the last successful sync even if a backend is slow, rate-limited, or
+temporarily unreachable. The CLI and the pi-tickets extension are both thin,
+interchangeable clients of one authenticated RPC daemon; neither talks to
+GitHub/GitLab/Jira or opens the SQLite ledger directly. See
+[RESEARCH.md](RESEARCH.md) for the sources this was built against.
+
+## Requirements
+
+- **[Bun](https://bun.sh) 1.1+.** The daemon uses `bun:sqlite` and
+  `Bun.serve` (via `@danypops/daemon-kit`); the CLI, library, and pi-tickets
+  extension are plain TypeScript but currently ship as source, run through
+  Bun rather than a compiled Node build.
+- `@danypops/daemon-kit` comes from the public npm registry (`^0.2.1`) —
+  no local checkout or `file:` path needed, `bun install` fetches it directly.
+
+## Install
+
+```bash
+bun install
+```
+
+## Run
+
+```bash
+# Start the daemon (binds 127.0.0.1 on an ephemeral port; writes a handle +
+# auth token under $XDG_RUNTIME_DIR/tickets and $XDG_STATE_HOME/tickets).
+bun run daemon
+
+# Or let the CLI manage it — every issue/ledger command below auto-starts the
+# daemon on first use if it isn't already running.
+bun run src/cli/index.ts daemon status    # never auto-starts; just checks
+bun run src/cli/index.ts daemon start
+bun run src/cli/index.ts daemon stop      # asks it to shut down gracefully
+bun run src/cli/index.ts daemon restart
+
+bun run src/cli/index.ts backends
+bun run src/cli/index.ts list -b github --status todo
+bun run src/cli/index.ts get jira:PROJ-42
+bun run src/cli/index.ts create -b github "Fix the thing" --label bug
+bun run src/cli/index.ts comment add jira:PROJ-42 "Looks good, shipping"
+bun run src/cli/index.ts ledger search "login bug"
+bun run src/cli/index.ts ledger stats
+```
+
+Once installed as a package, the same commands are available as `tickets`
+and `tickets-daemon` (see `bin` in `package.json`).
+
+## Configuration
+
+### Environment variables
+
+```bash
+# GitHub (token optional for public-repo reads)
+export GITHUB_TOKEN=ghp_xxx
+export GITHUB_OWNER=your-org
+export GITHUB_REPO=your-repo
+
+# GitLab (token optional for public-project reads)
+export GITLAB_TOKEN=glpat-xxx
+export GITLAB_PROJECT=namespace/project
+export GITLAB_URL=https://gitlab.example.com   # optional, defaults to gitlab.com
+
+# Jira
+export JIRA_API_TOKEN=xxx
+export JIRA_URL=https://yourcompany.atlassian.net
+export JIRA_EMAIL=you@yourcompany.com
+export JIRA_PROJECT=PROJ
+```
+
+### Config file (multi-instance)
+
+`$XDG_CONFIG_HOME/tickets/config.yaml` (default `~/.config/tickets/config.yaml`):
+
+```yaml
+backends:
+  github:
+    owner: your-org
+    repo: your-repo
+    token_env: GITHUB_TOKEN
+
+  gitlab:
+    project: namespace/project
+    token_env: GITLAB_TOKEN
+
+  jira:
+    url: https://yourcompany.atlassian.net
+    email: you@yourcompany.com
+    token_env: JIRA_API_TOKEN
+    project: PROJ
+
+  jira-staging:            # multi-instance: same type, different name
+    type: jira
+    url: https://staging.atlassian.net
+    email: you@yourcompany.com
+    token_env: JIRA_STAGING_TOKEN
+```
+
+## Delegated OAuth login (instead of a static token)
+
+Each backend supports a different real delegated-auth flow — see
+[RESEARCH.md](RESEARCH.md) for exactly which, and why Jira's is shaped
+differently from GitHub/GitLab's:
+
+```bash
+# GitHub / GitLab: device flow — opens a browser, prints a short code.
+tickets auth login --backend github --client-id <your-github-oauth-app-client-id>
+tickets auth login --backend gitlab --client-id <your-gitlab-application-id>
+
+# Jira: authorization code grant — opens a browser, receives the callback
+# on a local loopback server. Atlassian's 3LO apps are confidential clients
+# (no PKCE, no device flow), so a client secret is required here.
+tickets auth login --backend jira \
+  --client-id <your-atlassian-oauth-client-id> \
+  --client-secret <your-atlassian-oauth-client-secret>
+
+tickets auth status
+tickets auth logout github
+```
+
+A stored, still-fresh delegated token always takes precedence over a static
+config/env token for that backend. Tokens are written to
+`$XDG_STATE_HOME/tickets/oauth/<backend>.json`, mode `0600`, and are never
+printed by any command. **Restart the daemon** after logging in so it picks
+up the new credential — `buildRepositories()` runs once at daemon startup.
+
+## The `pi-tickets` extension
+
+`extensions/pi-tickets/` registers a single `tickets` tool for
+[pi](https://github.com/badlogic/pi) with one action per CLI command (`list`,
+`get`, `create`, `update`, `search`, `children`, `comments`, `comment_add`,
+`backends`, `ledger_search`, `ledger_stats`). It talks to the same daemon
+through the same authenticated RPC client the CLI uses — never a direct
+backend call or a direct SQLite open. OAuth login is deliberately **not** a
+tool action: approving access requires a human in a browser, which belongs
+in a terminal (`tickets auth login`), not an LLM tool call.
+
+To use it:
+
+```bash
+cd extensions/pi-tickets
+bun install
+```
+
+then either symlink (or copy) `extensions/pi-tickets` into
+`~/.pi/agent/extensions/pi-tickets`, or add its path to `settings.json`:
+
+```json
+{ "extensions": ["/path/to/tickets/extensions/pi-tickets"] }
+```
+
+## Development
+
+```bash
+bun install
+bun run typecheck   # tsc --noEmit against src/ and test/
+bun test            # domain, adapters, application service, auth flows, daemon
+cd extensions/pi-tickets && bun install && bun test && bun run typecheck
+```
+
+Tests never hit real GitHub/GitLab/Jira/Atlassian: adapters take an
+injectable `fetchImpl`, and the daemon tests (`test/daemon/`) run the real
+`@danypops/daemon-kit` `startDaemon()`/SQLite/HTTP stack against a scratch
+XDG root with a fake `IssueRepository`.
+
+## Architecture
+
+```
+Driver (inbound)              Application              Driven (outbound)
+┌───────────────┐        ┌─────────────────┐        ┌──────────────────┐
+│ CLI (commander)│──RPC──▶│                 │        │ GitHub adapter   │
+│ pi-tickets     │──RPC──▶│  tickets-daemon │───────▶│ GitLab adapter   │
+│  (Pi tool)     │        │  (TicketService │───────▶│ Jira adapter     │
+└───────────────┘        │   + Ledger      │───────▶│ SQLite (Ledger)  │
+                          │   + Poller)     │        └──────────────────┘
+                          └─────────────────┘
+                          built on @danypops/daemon-kit
+                          (paths, storage, http, logging, daemon, rpc-client)
+```
+
+Hexagonal architecture: `src/domain` has zero I/O, `src/ports` defines the
+outbound contract, `src/adapters` implement it per backend, `src/application`
+orchestrates by parsing `backend:key` refs and routing to the named
+repository, and `src/daemon` is the only place that owns the SQLite ledger,
+wraps it in a Bearer-authenticated HTTP RPC surface, and runs the pooling
+poller as a `daemon-kit` maintenance task.

package/RESEARCH.md

@@ -0,0 +1,109 @@
+# Research notes
+
+This file records the primary sources each adapter and auth flow was built
+against, so the design decisions here are traceable instead of guessed.
+
+## Issue-tracking REST APIs
+
+- **GitHub REST API v3 — Issues**: https://docs.github.com/en/rest/issues/issues
+  Confirmed live. `githubIssue` field shapes (`number`, `state`, `labels`,
+  `pull_request` sentinel for filtering PRs out of the issues endpoint) and
+  auth (`Authorization: token <PAT>`, optional for public-repo reads) match
+  this doc.
+- **GitLab REST API v4 — Issues**: https://docs.gitlab.com/api/issues/
+  Confirmed live. Endpoint shapes (`/api/v4/projects/:id/issues`, `iid` vs
+  `id`, `state`/`state_event`) and auth (`PRIVATE-TOKEN` header for personal
+  access tokens) match this doc.
+- **Jira Cloud/Server REST API v2**: https://developer.atlassian.com/cloud/jira/platform/rest/v2/
+  `/rest/api/2/issue/{key}`, `/rest/api/2/search` (JQL), and the
+  transition-based status model (`/rest/api/2/issue/{key}/transitions`) match
+  this doc. Jira does not support a direct "set status" field PUT — status is
+  workflow-owned, hence `JiraRepository.transitionTo`.
+
+The three adapters were also cross-checked against a real, working Go
+implementation of the same three backends (a separate project, not shipped
+here) before being ported to TypeScript, which is why request/response
+shapes are exact rather than approximate.
+
+## Delegated OAuth (vs. static personal access tokens)
+
+Static PATs are simple but are exactly the kind of long-lived, broad-scope,
+easily-copy-pasted secret that delegated auth exists to avoid. Each backend's
+*actual* supported delegated flow was checked directly against its own docs
+before implementing anything — the three backends turned out to support three
+different flows, not one:
+
+- **GitHub — OAuth 2.0 Device Authorization Grant (RFC 8628)**:
+  https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps#device-flow
+  `POST https://github.com/login/device/code` → user opens
+  `verification_uri`, enters `user_code` → daemon polls
+  `POST https://github.com/login/oauth/access_token` with
+  `grant_type=urn:ietf:params:oauth:grant-type:device_code`. No client secret,
+  no redirect URI, no local callback server — ideal for a headless daemon.
+  Requires the device flow to be enabled on a registered GitHub OAuth App;
+  the client ID is public.
+
+- **GitLab — OAuth 2.0 Device Authorization Grant**:
+  https://docs.gitlab.com/api/oauth2/ ("Device Authorization Grant", GA in
+  GitLab 17.9, also available on GitLab.com). Same RFC 8628 shape as GitHub,
+  different paths: `POST {url}/oauth/authorize_device`,
+  `POST {url}/oauth/token`. Requires a "non-confidential" GitLab OAuth
+  application (no client secret for this flow either).
+
+- **Jira/Atlassian — OAuth 2.0 (3LO), Authorization Code grant, no PKCE**:
+  https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/
+  Atlassian's 3LO apps are confidential clients: the docs page has zero
+  mentions of PKCE, `code_challenge`, or a device flow — confirmed absent,
+  not assumed. Token exchange requires `client_id` **and** `client_secret`.
+  This is also the only one of the three that needs a local redirect: we bind
+  an ephemeral loopback HTTP server (`src/auth/jira-oauth.ts`,
+  `startCallbackServer`), send the user to
+  `https://auth.atlassian.com/authorize`, and receive the code on
+  `http://127.0.0.1:{port}/callback`.
+
+  A second, easy-to-miss detail from the same doc: an OAuth 2.0 (3LO) access
+  token is **not** used against the tenant's own `*.atlassian.net` domain the
+  way a Basic-auth API token is. You first call
+  `GET https://api.atlassian.com/oauth/token/accessible-resources` with the
+  access token to discover the site's `cloudId`, then all further API calls
+  go through `https://api.atlassian.com/ex/jira/{cloudId}/...` with
+  `Authorization: Bearer <token>`. `JiraRepository` models this as a second,
+  separate constructor mode (`JiraOAuthOptions`) alongside the original
+  Basic-auth mode (`JiraBasicAuthOptions`) — same port, two adapters-within-
+  the-adapter, picked by `config.ts`'s auth precedence.
+
+  Refresh tokens require `offline_access` in the requested scope and use the
+  standard `grant_type=refresh_token` shape (`refreshJiraToken`).
+
+### What isn't implemented (honest scope boundary)
+
+- GitHub/GitLab OAuth token refresh: not implemented. GitHub's classic OAuth
+  App device-flow tokens are effectively non-expiring in practice; GitLab's
+  do expire (`expires_in` in the response) and *do* support the standard
+  `grant_type=refresh_token` shape, but a refresh path for it hasn't been
+  wired up yet — re-running `tickets auth login --backend gitlab` is the
+  current workaround. Jira's refresh function (`refreshJiraToken`) exists and
+  is tested, but nothing calls it automatically yet; `config.ts` only checks
+  freshness and falls back to a static token when a stored OAuth token has
+  expired.
+- Multiple Atlassian sites per token: `loginWithJiraAuthorizationCode` picks
+  the first accessible site unless a `chooseSite` callback is given. Fine for
+  the common single-site case; a config option to pick by hostname would be
+  the natural follow-up.
+
+## Architecture inspiration
+
+The domain/ports/adapters/application-service split (and the CLI/MCP-style
+single-tool "one entry point per capability" shape the pi-tickets extension
+follows) is adapted from a separate, existing Go project that implements the
+same idea (issue tracking across Linear/GitHub/GitLab/Jira with a hexagonal
+architecture) — ported here in scope to GitHub/GitLab/Jira and to
+TypeScript/Bun, not a line-for-line translation.
+
+The daemon itself (XDG paths, auth-token bootstrap, SQLite pragmas/migration
+runner, structured logging, Bearer-token HTTP RPC, process lifecycle) is
+built on [`@danypops/daemon-kit`](https://www.npmjs.com/package/@danypops/daemon-kit)
+(published to npm; this project depends on `^0.2.1`), a shared substrate
+used by several other supervised Bun daemons in the same ecosystem.
+See that package's own README for the substrate's design rationale; this
+project only documents how it's *used* here.

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@danypops/tickets",
+  "version": "0.1.0",
+  "description": "Unified CLI, daemon, and TypeScript library for issue tracking across GitHub, GitLab, and Jira.",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "tickets": "./src/cli/index.ts",
+    "tickets-daemon": "./src/daemon/main.ts"
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "RESEARCH.md"
+  ],
+  "scripts": {
+    "daemon": "bun run src/daemon/main.ts",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@danypops/daemon-kit": "^0.2.1",
+    "commander": "^12.1.0",
+    "yaml": "^2.6.0"
+  },
+  "devDependencies": {
+    "bun-types": "^1.3.0",
+    "typescript": "^5.7.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.1.0"
+  },
+  "keywords": [
+    "issue-tracker",
+    "jira",
+    "github",
+    "gitlab",
+    "cli",
+    "daemon"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DanyPops/tickets.git"
+  },
+  "homepage": "https://github.com/DanyPops/tickets#readme",
+  "bugs": {
+    "url": "https://github.com/DanyPops/tickets/issues"
+  }
+}

package/src/adapters/errors.ts

@@ -0,0 +1,33 @@
+export class IssueNotFoundError extends Error {
+  constructor(backend: string, key: string) {
+    super(`${backend}: issue not found: ${key}`);
+    this.name = "IssueNotFoundError";
+  }
+}
+
+export class AuthRequiredError extends Error {
+  constructor(backend: string, tokenEnv: string) {
+    super(`${backend}: write operation requires ${tokenEnv} to be set`);
+    this.name = "AuthRequiredError";
+  }
+}
+
+export class ApiError extends Error {
+  constructor(
+    public readonly backend: string,
+    public readonly method: string,
+    public readonly path: string,
+    public readonly status: number,
+    public readonly body: string,
+  ) {
+    super(`${backend} API error: ${method} ${path}: ${status}: ${body}`);
+    this.name = "ApiError";
+  }
+}
+
+export class InvalidUrlError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "InvalidUrlError";
+  }
+}

package/src/adapters/github.ts

@@ -0,0 +1,201 @@
+/**
+ * GitHub adapter — driven implementation of IssueRepository/CommentCapable against
+ * the GitHub REST API v3 (docs: https://docs.github.com/en/rest/issues/issues).
+ * Token is optional: public repos allow unauthenticated reads at a lower rate limit.
+ */
+import type { Comment, CreateInput, Issue, ListFilter, Status, UpdateInput } from "../domain/issue.js";
+import { parsePriority } from "../domain/issue.js";
+import { AuthRequiredError } from "./errors.js";
+import { type FetchLike, HttpClient } from "./http.js";
+
+export interface GitHubOptions {
+  owner: string;
+  repo?: string;
+  token?: string;
+  baseUrl?: string;
+  fetchImpl?: FetchLike;
+}
+
+interface GhUser {
+  login: string;
+}
+interface GhLabel {
+  id: number;
+  name: string;
+}
+interface GhIssue {
+  number: number;
+  title: string;
+  body: string | null;
+  state: string;
+  html_url: string;
+  user: GhUser | null;
+  assignee: GhUser | null;
+  labels: GhLabel[];
+  created_at: string;
+  updated_at: string;
+  pull_request?: unknown;
+}
+interface GhComment {
+  id: number;
+  body: string;
+  created_at: string;
+  updated_at: string;
+  user: GhUser | null;
+}
+
+export class GitHubRepository {
+  readonly name: string;
+  private readonly http: HttpClient;
+  private readonly owner: string;
+  private repo?: string;
+  private readonly readOnly: boolean;
+
+  constructor(name: string, opts: GitHubOptions) {
+    if (!opts.owner) throw new Error("github: owner is required");
+    this.name = name;
+    this.owner = opts.owner;
+    this.repo = opts.repo;
+    this.readOnly = !opts.token;
+    this.http = new HttpClient({
+      baseUrl: opts.baseUrl ?? "https://api.github.com",
+      backend: "github",
+      fetchImpl: opts.fetchImpl,
+      headers: {
+        Accept: "application/vnd.github.v3+json",
+        ...(opts.token ? { Authorization: `token ${opts.token}` } : {}),
+      },
+    });
+  }
+
+  private repoPath(): string {
+    if (!this.repo) throw new Error("github: repo not set — pass repo, or scope via config");
+    return `/repos/${this.owner}/${this.repo}`;
+  }
+
+  private requireAuth(): void {
+    if (this.readOnly) throw new AuthRequiredError("github", "GITHUB_TOKEN");
+  }
+
+  async list(filter: ListFilter): Promise<Issue[]> {
+    const limit = filter.limit && filter.limit > 0 ? filter.limit : 50;
+    const params = new URLSearchParams({ per_page: String(limit), state: "all" });
+    if (filter.status) params.set("state", mapStatusToGitHub(filter.status));
+    if (filter.assignee) params.set("assignee", filter.assignee);
+    if (filter.labels?.length) params.set("labels", filter.labels.join(","));
+
+    const raw = (await this.http.get<GhIssue[]>(`${this.repoPath()}/issues?${params}`)) ?? [];
+    return raw.filter((i) => !i.pull_request).map(toDomain);
+  }
+
+  async get(key: string): Promise<Issue> {
+    const number = parseIssueNumber(key);
+    const raw = await this.http.get<GhIssue>(`${this.repoPath()}/issues/${number}`);
+    if (!raw) throw new Error(`github: empty response for #${number}`);
+    if (raw.pull_request) throw new Error(`github: #${number} is a pull request, not an issue`);
+    return toDomain(raw);
+  }
+
+  async create(input: CreateInput): Promise<Issue> {
+    this.requireAuth();
+    const body: Record<string, unknown> = { title: input.title, body: input.description ?? "" };
+    if (input.labels?.length) body.labels = input.labels;
+    if (input.assignee) body.assignees = [input.assignee];
+    const raw = await this.http.post<GhIssue>(`${this.repoPath()}/issues`, body);
+    if (!raw) throw new Error("github: create returned no body");
+    return toDomain(raw);
+  }
+
+  async update(key: string, input: UpdateInput): Promise<Issue> {
+    this.requireAuth();
+    const number = parseIssueNumber(key);
+    const body: Record<string, unknown> = {};
+    if (input.title !== undefined) body.title = input.title;
+    if (input.description !== undefined) body.body = input.description;
+    if (input.status !== undefined) body.state = mapStatusToGitHub(input.status);
+    if (input.labels !== undefined) body.labels = input.labels;
+    if (input.assignee !== undefined) body.assignees = input.assignee ? [input.assignee] : [];
+    const raw = await this.http.patch<GhIssue>(`${this.repoPath()}/issues/${number}`, body);
+    if (!raw) throw new Error("github: update returned no body");
+    return toDomain(raw);
+  }
+
+  async search(query: string, limit = 50): Promise<Issue[]> {
+    const scope = this.repo ? `repo:${this.owner}/${this.repo}` : `org:${this.owner}`;
+    const q = encodeURIComponent(`${scope} ${query}`);
+    const result = await this.http.get<{ items: GhIssue[] }>(`/search/issues?q=${q}&per_page=${limit}`);
+    return (result?.items ?? []).filter((i) => !i.pull_request).map(toDomain);
+  }
+
+  // GitHub has no native sub-issue relationship exposed via REST v3.
+  async listChildren(_key: string): Promise<Issue[]> {
+    return [];
+  }
+
+  async listComments(key: string): Promise<Comment[]> {
+    const number = parseIssueNumber(key);
+    const raw = (await this.http.get<GhComment[]>(`${this.repoPath()}/issues/${number}/comments`)) ?? [];
+    return raw.map(commentToDomain);
+  }
+
+  async addComment(key: string, body: string): Promise<Comment> {
+    this.requireAuth();
+    const number = parseIssueNumber(key);
+    const raw = await this.http.post<GhComment>(`${this.repoPath()}/issues/${number}/comments`, { body });
+    if (!raw) throw new Error("github: add comment returned no body");
+    return commentToDomain(raw);
+  }
+}
+
+function parseIssueNumber(key: string): string {
+  const stripped = key.replace(/^#/, "");
+  const idx = stripped.lastIndexOf("#");
+  return idx >= 0 ? stripped.slice(idx + 1) : stripped;
+}
+
+function mapStatusToGitHub(status: Status): "open" | "closed" {
+  return status === "done" || status === "canceled" ? "closed" : "open";
+}
+
+function mapStatusFromGitHub(state: string): Status {
+  return state.toLowerCase() === "closed" ? "done" : "todo";
+}
+
+function priorityFromLabels(labels: GhLabel[]): ReturnType<typeof parsePriority> {
+  for (const l of labels) {
+    const lower = l.name.toLowerCase();
+    if (lower.includes("urgent") || lower.includes("critical")) return "urgent";
+    if (lower.includes("high")) return "high";
+    if (lower.includes("medium")) return "medium";
+    if (lower.includes("low")) return "low";
+  }
+  return "none";
+}
+
+function toDomain(gh: GhIssue): Issue {
+  return {
+    ref: `github:#${gh.number}`,
+    id: String(gh.number),
+    key: `#${gh.number}`,
+    title: gh.title,
+    description: gh.body ?? undefined,
+    status: mapStatusFromGitHub(gh.state),
+    rawStatus: gh.state,
+    priority: priorityFromLabels(gh.labels ?? []),
+    labels: gh.labels?.length ? gh.labels.map((l) => l.name) : undefined,
+    assignee: gh.assignee?.login,
+    url: gh.html_url,
+    createdAt: gh.created_at,
+    updatedAt: gh.updated_at,
+  };
+}
+
+function commentToDomain(c: GhComment): Comment {
+  return {
+    id: String(c.id),
+    body: c.body,
+    author: c.user?.login,
+    createdAt: c.created_at,
+    updatedAt: c.updated_at,
+  };
+}