@nilsr0711/drydock 0.1.0

package/README.md

@@ -0,0 +1,368 @@
+<div align="center">
+
+# ⚓ Drydock
+
+**Turn GitHub issues into merged pull requests — autonomously, on your own machine.**
+
+Drydock is a local-first orchestrator that picks issues off a queue, drives the
+[`claude`](https://docs.claude.com/en/docs/claude-code) CLI to implement them, babysits
+CI until it's green, auto-merges, and tracks every dollar it spends — all from a single
+dashboard bound to `127.0.0.1`.
+
+[![CI](https://github.com/NilsR0711/drydock/actions/workflows/ci.yml/badge.svg)](https://github.com/NilsR0711/drydock/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/NilsR0711/drydock/actions/workflows/codeql.yml/badge.svg)](https://github.com/NilsR0711/drydock/actions/workflows/codeql.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Next.js 16](https://img.shields.io/badge/Next.js-16-black?logo=next.js)](https://nextjs.org)
+[![React 19](https://img.shields.io/badge/React-19-149eca?logo=react)](https://react.dev)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5-3178c6?logo=typescript&logoColor=white)](https://www.typescriptlang.org)
+[![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](#contributing)
+
+</div>
+
+> [!NOTE]
+> Drydock is a **single-user, local tool**: no auth, no cloud, no multi-tenant. It binds
+> `127.0.0.1` only and stores everything in a local SQLite file. It shells out to the
+> `claude` and `gh` CLIs you already have authenticated.
+
+---
+
+## Table of contents
+
+- [Why Drydock](#why-drydock)
+- [Features](#features)
+- [How it works](#how-it-works)
+- [Job lifecycle](#job-lifecycle)
+- [Quickstart](#quickstart)
+- [Requirements](#requirements)
+- [Configuration](#configuration)
+- [Screens](#screens)
+- [Project layout](#project-layout)
+- [Tech stack](#tech-stack)
+- [Development](#development)
+- [Operations](#operations)
+- [MCP server](#mcp-server)
+- [Roadmap](#roadmap)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
+## Why Drydock
+
+Coding agents are great at small, well-scoped issues — but babysitting them one terminal
+at a time doesn't scale. Drydock turns that loop into a queue:
+
+- **You** triage issues into a queue and set priority.
+- **Drydock** runs them through an agent, opens the PR, watches CI, retries failures, and
+  merges when green.
+- **You** only get pinged when something genuinely needs a human.
+
+It's the difference between *driving* an agent and *operating a dock* of them.
+
+## Features
+
+🗂️ **Backlog & queue board** — drag issues from a synced backlog into a sortable, priority-ordered queue. One issue or many in flight, per repo.
+
+🤖 **Autonomous implementation** — spawns a coding agent (`claude` or the `codex` CLI), streams its work, and opens a pull request.
+
+🔌 **Pluggable agents** — choose `claude` or `codex` per repo (with a global default in settings); a preflight check verifies the selected CLI is installed.
+
+🦊 **GitHub & GitLab** — choose the platform per repo. GitLab (gitlab.com or self-hosted) uses the REST API v4 with a per-repo base URL + access token — no extra CLI to install.
+
+🛂 **Opt-in autonomous triage** — per repo, let Drydock label incoming issues (deterministic keyword classifier, whitelist-only output) and auto-process the ones that are *ready* and not blocked. Off by default; gated by author association for public repos, a per-issue attempt limit, and all the usual cost/concurrency limits. Never auto-merges.
+
+🔧 **CI babysitting & auto-merge** — polls `gh pr checks`, merges on green, and on red resumes the session with a CI-fix prompt (up to **3 retries**), then files a follow-up issue and hands off.
+
+🩹 **Opt-in CI auto-heal** — per repo, turn the failure path into a structured classify → fix → verify loop: failing checks are bucketed (healable / external / flaky / unknown), only healable ones get a targeted fix, and each attempt is verified for a real, improving change. External and AI-review checks are never code-healed. Hard budgets (per-session and per-fingerprint attempts, a cooldown, and a concurrency cap) keep it bounded. Off by default; never auto-merges.
+
+💬 **Opt-in PR review-feedback** — per repo, ingest review threads on a Drydock PR and run the mechanical iteration: only **trusted reviewers** are acted on (bots ignored), each comment walks a lifecycle (`pending → queued → in_progress → resolved`, with `failed` / `rejected` / `flagged` branches), and the agent applies the change on the PR branch, replies, and resolves the thread. Status replies are marker-based and idempotent (updated in place, not duplicated), with bounded per-sweep and per-item budgets. Off by default; never auto-merges. See [ADR 019](docs/adr/019-pr-review-feedback.md).
+
+🧩 **Opt-in issue decomposition** — per repo, split a large issue ("fix these 5 bugs", "implement X with A/B/C") into ordered, tracked subtasks. A deterministic heuristic handles GitHub task lists (`- [ ]`) and "Bug N —" headings for free; prose falls back to a one-shot agent. Decomposition is idempotent (keyed on the issue body hash, redone only when the body changes), subtasks are surfaced in the agent prompt and worked in order, and progress is reflected on the issue and in the UI. Off by default. See [ADR 020](docs/adr/020-issue-decomposition.md).
+
+🚀 **Opt-in post-merge deployment healing** — per repo, watch a merged PR's deployment via pluggable platform adapters (Vercel and Railway today; adding Netlify/Fly/Render is one adapter, no core changes). The platform is auto-detected from repo config or set explicitly. The merged commit's deployment is polled with bounded delay/interval/timeout budgets, and on failure the logs are captured and a follow-up **fix PR** is opened for a human to review. Sessions are surfaced in the repo's Deployments panel. Off by default; never auto-merges. See [ADR 021](docs/adr/021-post-merge-deployment-healing.md).
+
+⚖️ **Rate-limit budgeting** — a priority-aware governor meters every GitHub call: the background sweep runs at *low* priority and yields once the budget drops below a reserve fraction, while interactive actions stay *high*; a hard floor stops anything from draining the budget to zero, a 429 backs off until reset, and unchanged issue lists are fetched with conditional ETag requests so they cost nothing. See [ADR 018](docs/adr/018-rate-limit-governor.md).
+
+📡 **Live logs over SSE** — the agent's NDJSON output is parsed incrementally, persisted, and streamed to the browser in real time.
+
+💸 **Cost tracking** — per-job and aggregate spend from the agent's reported `total_cost_usd` (or estimated from tokens), with a **daily cost limit** that gates the driver loop.
+
+⏯️ **Global pause & per-repo controls** — pause everything from the navbar, pick an agent and model per repo, toggle serial vs. parallel processing, and customize the queue label.
+
+🔔 **External notifications** — get pinged on Telegram, Slack (incoming webhook) and email (SMTP) for the lifecycle events you care about (job needs human, job failed, PR opened, PR merged, daily cost limit reached, automation paused/draining). Each channel is configured independently, every event has a per-event opt-in, and a one-click test button verifies setup. Delivery is best-effort and never blocks the loop; secrets are redacted from logs. See [ADR 024](docs/adr/024-external-notifications.md).
+
+📐 **ADR review queue** — a file watcher surfaces new `docs/adr/*.md` decisions for approve/reject.
+
+🧱 **Crash-safe lease queue** — jobs are claimed from a SQLite-backed queue with a lease token kept alive by heartbeats. A crashed worker's `working` jobs are requeued (with attempt-scaled backoff) on the next startup instead of getting stuck, CI-babysitting states park as `interrupted`, finalizing with a stale lease is rejected, a dedupe key prevents double-enqueuing the same issue, and a PID lockfile stops a second instance racing the queue. Graceful shutdown drains then SIGKILLs after 5s. See [ADR 022](docs/adr/022-lease-based-job-queue.md).
+
+🎨 **Polished UX** — light/dark theme, confirm dialogs on destructive actions, toast feedback, and accessible primitives.
+
+## How it works
+
+```mermaid
+flowchart LR
+    I["GitHub issue"] -->|"sync via gh"| B["Backlog"]
+    B -->|"queue"| Q["Priority queue"]
+    Q --> D["Orchestrator<br/>driver loop"]
+    D -->|"spawn claude"| S["Agent session"]
+    S -->|"opens PR"| CI{"CI checks"}
+    CI -->|"green"| M["Auto-merge ✅"]
+    CI -->|"red"| R["CI babysitter<br/>(resume + fix)"]
+    R -->|"fixed"| CI
+    R -->|"exhausted"| H["needs human<br/>+ follow-up issue"]
+```
+
+A single orchestrator boots with the server process (`src/instrumentation.ts`). On start it
+runs crash recovery (requeue orphaned `working` jobs, park CI-babysitting states as
+`interrupted`) and installs graceful-shutdown handlers. The **driver loop** atomically claims
+the next eligible queued job with a lease (respecting per-repo priority, the daily cost limit,
+the global pause, and serial-vs-parallel settings), heartbeats it while it runs, then releases
+the lease once it settles.
+
+- **Sessions** — the `claude` CLI is spawned as a subprocess; its `stream-json` stdout is
+  parsed line-by-line, written to `job_events`, and pushed to the browser over SSE.
+- **CI babysitter** — polls checks, merges on green, and on failure pulls the failed run log
+  and resumes the session with a fix prompt (Haiku) until it passes or the retry budget runs out.
+- **ADRs** — a [chokidar](https://github.com/paulmillr/chokidar) watcher registers new ADR
+  files for review.
+
+> Every external command (`claude`, `gh`, `git`) goes through an injectable runner, so the
+> entire test suite runs offline with fakes — no network, no real subprocesses ([ADR&nbsp;004](docs/adr/004-injectable-command-runner.md)).
+
+## Job lifecycle
+
+Each job moves through an explicit, validated state machine
+([ADR&nbsp;005](docs/adr/005-job-state-machine.md)):
+
+```mermaid
+stateDiagram-v2
+    [*] --> queued
+    queued --> working
+    working --> ci_running
+    working --> needs_human
+    ci_running --> merged
+    ci_running --> ci_failed
+    ci_failed --> retrying
+    retrying --> ci_running
+    ci_failed --> needs_human
+    retrying --> needs_human
+    needs_human --> queued
+    merged --> [*]
+    aborted --> [*]
+```
+
+`aborted` (manual) and `interrupted` (crash recovery) can be reached from any in-flight state;
+`needs_human` and `interrupted` jobs can be re-queued. Terminal states are `merged` and `aborted`.
+
+## Install
+
+Run the published tool straight from the terminal — no checkout required:
+
+```bash
+npx @nilsr0711/drydock            # boot the server and print the dashboard URL
+npx @nilsr0711/drydock --open     # …and open it in your browser
+```
+
+Or install it globally — the command is `drydock` regardless of the scoped package name:
+
+```bash
+npm i -g @nilsr0711/drydock
+drydock --open
+```
+
+The SQLite database lives in `~/.drydock/` (override with `DRYDOCK_DATA_DIR`) and is created
+and migrated automatically on first start — there are no setup steps. Then open the dashboard,
+add a repository, and start queuing issues.
+
+```bash
+drydock --help         # all flags
+drydock --version      # installed version
+drydock --port 8080 --host 0.0.0.0   # bind elsewhere (defaults: 127.0.0.1:3737)
+drydock update         # update a global install to the latest version
+```
+
+You still need the `claude` and (for GitHub) `gh` CLIs on `PATH` — see [Requirements](#requirements).
+
+## Quickstart
+
+For local development from a checkout:
+
+```bash
+git clone https://github.com/NilsR0711/drydock.git
+cd drydock
+
+pnpm install        # installs deps (builds better-sqlite3)
+pnpm dev            # dev server on http://127.0.0.1:3737
+```
+
+That's it — the SQLite database is created and migrated on first connection. Open the
+dashboard, add a repository, and start queuing issues.
+
+```bash
+pnpm build          # production build
+pnpm start          # serve the production build
+pnpm test           # run the unit suite (167 tests, fully offline)
+```
+
+## Requirements
+
+| Tool | Version | Notes |
+| --- | --- | --- |
+| Node.js | ≥ 20.9 (22 recommended) | matches the CI matrix |
+| npm | ≥ 10 (ships with Node) | to install/run the published tool — `npm i -g @nilsr0711/drydock` or `npx @nilsr0711/drydock` |
+| [`claude`](https://docs.claude.com/en/docs/claude-code) **or** [`codex`](https://github.com/openai/codex) CLI | latest | the coding agent — pick one per repo; on `PATH`, authenticated |
+| [`gh`](https://cli.github.com) CLI | latest | on `PATH`, authenticated — for **GitHub** repos |
+| pnpm | 10.x | **only for local development** from a checkout (`corepack enable`) |
+
+You need at least one agent CLI (`claude` or `codex`); a preflight check verifies the one
+selected for a repo is installed. CLI paths are configurable under **Settings** if they're
+not on `PATH`. **GitLab** repos need no extra CLI — they use the REST API with a per-repo
+base URL + access token instead.
+For self-hosted instances behind a corporate CA or proxy, set `NODE_EXTRA_CA_CERTS` and/or
+`HTTPS_PROXY` in Drydock's environment (see [ADR 015](docs/adr/015-gitlab-forge-support.md)).
+
+## Configuration
+
+Drydock is configured at runtime from the **Settings** page and per-repo controls — no
+`.env` required. The environment variables, all optional:
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `DRYDOCK_DATA_DIR` | `~/.drydock` | Directory for the database and local state (packaged runs) |
+| `DRYDOCK_DB` | `<data dir>/drydock.db`¹ | SQLite file path (use `:memory:` for ephemeral runs); overrides the data dir |
+| `DRYDOCK_MIGRATIONS` | `./drizzle` | Folder of generated SQL migrations (set automatically by the `drydock` launcher) |
+
+¹ A source checkout (`pnpm dev`/`pnpm start`) defaults `DRYDOCK_DB` to `data/drydock.db` in the
+project; the `drydock` launcher defaults it to `~/.drydock/drydock.db`.
+
+**Settings (global):** pause switch · daily cost limit · log retention (days) · `claude`/`gh` CLI paths · notification channels (Telegram / Slack / email) and per-event opt-in.
+**Per repo:** platform (GitHub / GitLab, with base URL + token for GitLab) · default model · serial vs. parallel processing · queue label (default `drydock:queue`).
+
+## Screens
+
+| Route | Screen |
+| --- | --- |
+| `/` | Dashboard — repos, status counts, recent activity |
+| `/repos/[id]` | Repo workspace — backlog/queue board, settings, activity, cost |
+| `/jobs/[id]` | Job detail — live streaming log, cost & tokens |
+| `/prompts` | Versioned prompt editor |
+| `/adrs` | ADR review queue |
+| `/costs` | Cost dashboard — daily, by model, top jobs |
+| `/settings` | Global settings |
+
+## Project layout
+
+```
+src/
+├─ app/                  # Next.js App Router pages + SSE route
+├─ components/           # UI (board, modals, charts, ui/ primitives)
+├─ instrumentation.ts    # boots the single orchestrator per process
+└─ lib/
+   ├─ orchestrator/      # driver loop, state machine, sessions, CI babysitter
+   ├─ issues/            # backlog sync, queue, server actions
+   ├─ forge/             # platform abstraction (github + gitlab) + registry
+   ├─ github/            # gh CLI wrapper (the github forge)
+   ├─ exec/ · stream/    # subprocess runner + stream-json parser
+   ├─ db/                # Drizzle schema, queries, migrations
+   ├─ adr/ · prompts/    # ADR watcher/review, prompt templates
+   ├─ mcp/               # stdio MCP server: tool registry + wiring
+   ├─ cli.ts             # `pnpm mcp` dispatcher (dev MCP entrypoint)
+   └─ repos/ · settings/ # repo & settings services
+bin/drydock.mjs          # published `drydock` launcher (boots the standalone server)
+scripts/drydock.ts       # dev MCP entrypoint (pnpm mcp)
+scripts/package-standalone.mjs  # finishes the standalone bundle for npm
+docs/adr/                # architecture decision records (index: docs/DECISIONS.md)
+tests/                   # Vitest suite — fully offline
+```
+
+## Tech stack
+
+**Next.js 16** (App Router · RSC · Server Actions) · **React 19** · **TypeScript 5** ·
+**SQLite** via `better-sqlite3` + **Drizzle ORM** · **Tailwind CSS v4** · **Zod** ·
+**Server-Sent Events** for live logs · **Vitest** · **Biome** (lint + format).
+
+## Development
+
+```bash
+pnpm lint           # biome ci (lint + format check)
+pnpm format         # biome check --write (auto-fix)
+pnpm typecheck      # tsc --noEmit
+pnpm test           # vitest run
+pnpm db:generate    # regenerate Drizzle migrations after schema changes
+pnpm mcp            # start the local stdio MCP server (see "MCP server")
+```
+
+- **Tests never touch the network** — the `claude`/`gh`/`git` CLIs are injected as fakes.
+- **Architecture decisions** live in [`docs/adr/`](docs/adr) (index:
+  [`docs/DECISIONS.md`](docs/DECISIONS.md)).
+- CI runs lint, typecheck, tests, and build on Node 20 & 22; CodeQL scans the codebase;
+  Dependabot keeps dependencies and actions current.
+
+## Operations
+
+- **Backups** — `pnpm backup` writes a consistent SQLite snapshot into `data/backups/` and
+  prunes anything older than 7 days. Schedule it daily via cron/launchd.
+- **Retention & pruning** — finished jobs' verbose log events are pruned past the
+  **log retention** window (default 30 days; cost summary rows are kept). A daily in-process
+  sweep runs automatically; for a manual run use `pnpm db:prune [--days <n>] [--no-vacuum]`,
+  which deletes expired events and runs `VACUUM` to reclaim disk. See
+  [ADR 023](docs/adr/023-log-retention-and-pruning.md).
+- **Secret redaction** — GitHub/GitLab tokens and `Bearer` values echoed in agent output are
+  scrubbed before any log event is persisted or streamed.
+- **Pause / cost limit** — flip the global pause or hit the daily cost limit and the driver
+  loop stops claiming new work; in-flight jobs finish cleanly.
+
+## MCP server
+
+Drydock can be driven by any [MCP](https://modelcontextprotocol.io) host (Claude Desktop, a
+higher-level agent, …) over a **local stdio** server — no HTTP. stdio is a process-local
+transport, so the server is reachable only by the host that launches it on the same machine.
+
+Start it with `pnpm mcp` (or `drydock mcp` if the package is linked). For an MCP host, point its
+config at the entrypoint, e.g.:
+
+```json
+{
+  "mcpServers": {
+    "drydock": {
+      "command": "npx",
+      "args": ["tsx", "/absolute/path/to/drydock/scripts/drydock.ts", "mcp"]
+    }
+  }
+}
+```
+
+**Tools** (all route through the same service layer as the dashboard):
+
+| Area   | Tools                                                                 |
+| ------ | --------------------------------------------------------------------- |
+| Repos  | `list_repos`, `add_repo`, `sync_repo_issues`                          |
+| Issues | `list_issues`, `add_to_queue`, `remove_from_queue`, `set_issue_labels`|
+| Jobs   | `list_jobs`, `get_job`, `requeue_job`, `abort_job`                    |
+| System | `get_settings`, `update_settings`, `set_drain_mode`, `get_logs`       |
+
+**Safety** — work-initiating tools (`add_to_queue`, `requeue_job`) honor the same gates as the
+UI: they refuse while draining, globally paused, or over the daily/per-repo cost limit.
+`get_settings` redacts credential fields and `update_settings` cannot set them. See
+[ADR 025](docs/adr/025-mcp-server.md).
+
+## Roadmap
+
+- [ ] Parallel multi-repo dashboards at a glance
+- [ ] Webhook-driven issue sync (vs. polling)
+- [ ] Richer CI failure classification & targeted fix prompts
+- [ ] Exportable cost reports
+
+Have an idea? [Open an issue](https://github.com/NilsR0711/drydock/issues).
+
+## Contributing
+
+Contributions are welcome! Please:
+
+1. Open an issue to discuss substantial changes first.
+2. Keep the suite green: `pnpm lint && pnpm typecheck && pnpm test`.
+3. Follow the existing style (Biome-formatted, Conventional Commits) and add tests for new behavior.
+
+## License
+
+Released under the [MIT License](LICENSE) © 2026 NilsR0711.

package/bin/drydock.mjs

@@ -0,0 +1,241 @@
+#!/usr/bin/env node
+
+// Drydock terminal launcher (issue #12). Boots the bundled Next.js standalone
+// server, applying SQLite migrations into a user data directory on first start,
+// and optionally opens the dashboard in the browser. Plain ESM with no build
+// step or TypeScript runtime so it works straight from the published tarball.
+
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const DEFAULT_HOST = "127.0.0.1";
+const DEFAULT_PORT = 3737;
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+/**
+ * Parse the launcher's CLI arguments into a directive. `--help`/`--version`
+ * short-circuit; otherwise the result describes how to serve. Throws an Error
+ * with a human-readable message on invalid input so the caller can print it.
+ */
+export function parseArgs(argv) {
+  for (const arg of argv) {
+    if (arg === "--help" || arg === "-h") return { mode: "help" };
+    if (arg === "--version" || arg === "-v") return { mode: "version" };
+  }
+
+  if (argv[0] === "update") {
+    if (argv.length > 1) throw new Error(`unexpected argument: ${argv[1]}`);
+    return { mode: "update" };
+  }
+
+  let host = DEFAULT_HOST;
+  let port = DEFAULT_PORT;
+  let open = false;
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+
+    if (arg === "--open") {
+      open = true;
+      continue;
+    }
+
+    const value = (flag) => {
+      const eq = `${flag}=`;
+      if (arg.startsWith(eq)) return arg.slice(eq.length);
+      const next = argv[i + 1];
+      if (next === undefined) throw new Error(`missing value for ${flag}`);
+      i++;
+      return next;
+    };
+
+    if (arg === "--port" || arg === "-p" || arg.startsWith("--port=")) {
+      port = parsePort(value("--port"));
+      continue;
+    }
+    if (arg === "--host" || arg === "-H" || arg.startsWith("--host=")) {
+      host = value("--host");
+      continue;
+    }
+
+    if (arg.startsWith("-")) throw new Error(`unknown option: ${arg}`);
+    throw new Error(`unexpected argument: ${arg}`);
+  }
+
+  return { mode: "serve", host, port, open };
+}
+
+function parsePort(raw) {
+  const port = Number(raw);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new Error(`invalid port: "${raw}" (expected an integer between 1 and 65535)`);
+  }
+  return port;
+}
+
+/**
+ * Resolve the directory holding Drydock's database and local state. Defaults to
+ * `~/.drydock` so a packaged install never writes inside its own (potentially
+ * read-only) install location; overridable via DRYDOCK_DATA_DIR.
+ *
+ * @param {{ env?: Record<string, string | undefined>, home?: string }} [opts]
+ */
+export function resolveDataDir({ env = process.env, home = homedir() } = {}) {
+  const override = env.DRYDOCK_DATA_DIR?.trim();
+  return override ? override : join(home, ".drydock");
+}
+
+/**
+ * Resolve the SQLite database path; DRYDOCK_DB overrides the data dir entirely.
+ *
+ * @param {{ env?: Record<string, string | undefined>, home?: string }} [opts]
+ */
+export function resolveDbPath({ env = process.env, home = homedir() } = {}) {
+  const override = env.DRYDOCK_DB?.trim();
+  return override ? override : join(resolveDataDir({ env, home }), "drydock.db");
+}
+
+const HELP = `drydock — autonomously turn GitHub issues into pull requests
+
+Usage:
+  drydock [options]      Start the server and dashboard
+  drydock update         Update to the latest published version
+
+Options:
+  -p, --port <number>   Port to listen on (default: ${DEFAULT_PORT})
+  -H, --host <host>     Host to bind to (default: ${DEFAULT_HOST})
+      --open            Open the dashboard in your browser once it is ready
+  -v, --version         Print the version and exit
+  -h, --help            Show this help and exit
+
+Data is stored in ~/.drydock (override with DRYDOCK_DATA_DIR); the database is
+created and migrated automatically on first start.`;
+
+/** The command that updates a global install to the latest published version. */
+export function updateCommand() {
+  return { command: "npm", args: ["install", "--global", "@nilsr0711/drydock@latest"] };
+}
+
+/** Run the self-update, inheriting stdio so npm's progress is visible. */
+function runUpdate() {
+  const { command, args } = updateCommand();
+  console.error(`Updating drydock: ${command} ${args.join(" ")}`);
+  const child = spawn(command, args, {
+    shell: process.platform === "win32",
+    stdio: "inherit",
+  });
+  child.on("exit", (code) => process.exit(code ?? 0));
+  child.on("error", (err) => {
+    console.error(`Update failed: ${err.message}`);
+    process.exit(1);
+  });
+}
+
+/** Read the package version without an import assertion (keeps ESM warning-free). */
+function readVersion() {
+  return JSON.parse(readFileSync(join(PACKAGE_ROOT, "package.json"), "utf8")).version;
+}
+
+/** Spawn the platform browser-opener for `url`, detached and best-effort. */
+function openBrowser(url) {
+  const command =
+    process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+  const child = spawn(command, [url], {
+    shell: process.platform === "win32",
+    stdio: "ignore",
+    detached: true,
+  });
+  child.on("error", () => {
+    console.error(`Could not open a browser automatically. Visit ${url}`);
+  });
+  child.unref();
+}
+
+/** Poll the server until it accepts connections, then resolve. */
+async function waitForServer(url, { attempts = 100, intervalMs = 100 } = {}) {
+  for (let i = 0; i < attempts; i++) {
+    try {
+      await fetch(url);
+      return true;
+    } catch {
+      await new Promise((r) => setTimeout(r, intervalMs));
+    }
+  }
+  return false;
+}
+
+async function serve({ host, port, open }) {
+  const serverEntry = join(PACKAGE_ROOT, ".next", "standalone", "server.js");
+  if (!existsSync(serverEntry)) {
+    throw new Error(
+      "Standalone server bundle not found. Run `pnpm build` first (the published package ships it prebuilt).",
+    );
+  }
+
+  const dataDir = resolveDataDir();
+  mkdirSync(dataDir, { recursive: true });
+
+  const env = {
+    ...process.env,
+    NODE_ENV: "production",
+    HOSTNAME: host,
+    PORT: String(port),
+    DRYDOCK_DB: resolveDbPath(),
+    DRYDOCK_MIGRATIONS: join(PACKAGE_ROOT, "drizzle"),
+  };
+
+  const url = `http://${host}:${port}`;
+  console.error(`Drydock starting on ${url} (data: ${dataDir})`);
+
+  const server = spawn(process.execPath, [serverEntry], {
+    cwd: dirname(serverEntry),
+    env,
+    stdio: "inherit",
+  });
+
+  server.on("exit", (code) => process.exit(code ?? 0));
+  process.on("SIGINT", () => server.kill("SIGINT"));
+  process.on("SIGTERM", () => server.kill("SIGTERM"));
+
+  if (open) {
+    waitForServer(url).then((ready) => {
+      if (ready) openBrowser(url);
+    });
+  }
+}
+
+async function main(argv) {
+  let directive;
+  try {
+    directive = parseArgs(argv);
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    console.error(`\nRun \`drydock --help\` for usage.`);
+    process.exit(2);
+  }
+
+  switch (directive.mode) {
+    case "help":
+      console.log(HELP);
+      return;
+    case "version":
+      console.log(readVersion());
+      return;
+    case "update":
+      runUpdate();
+      return;
+    default:
+      await serve(directive);
+  }
+}
+
+// Only run when executed directly, not when imported by tests.
+if (process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1])) {
+  main(process.argv.slice(2)).catch((err) => {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  });
+}

package/drizzle/0000_green_northstar.sql

@@ -0,0 +1,78 @@
+CREATE TABLE `adrs` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`job_id` integer,
+	`file_path` text NOT NULL,
+	`title` text NOT NULL,
+	`status` text DEFAULT 'pending_review' NOT NULL,
+	`created_at` integer DEFAULT (unixepoch()) NOT NULL,
+	FOREIGN KEY (`job_id`) REFERENCES `jobs`(`id`) ON UPDATE no action ON DELETE set null
+);
+--> statement-breakpoint
+CREATE TABLE `followup_issues` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`job_id` integer,
+	`gh_issue_number` integer NOT NULL,
+	`title` text NOT NULL,
+	`created_at` integer DEFAULT (unixepoch()) NOT NULL,
+	FOREIGN KEY (`job_id`) REFERENCES `jobs`(`id`) ON UPDATE no action ON DELETE set null
+);
+--> statement-breakpoint
+CREATE TABLE `job_events` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`job_id` integer NOT NULL,
+	`ts` integer DEFAULT (unixepoch()) NOT NULL,
+	`type` text NOT NULL,
+	`payload` text DEFAULT '{}' NOT NULL,
+	FOREIGN KEY (`job_id`) REFERENCES `jobs`(`id`) ON UPDATE no action ON DELETE cascade
+);
+--> statement-breakpoint
+CREATE INDEX `job_events_job_ts_idx` ON `job_events` (`job_id`,`ts`);--> statement-breakpoint
+CREATE TABLE `jobs` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`repo_id` integer NOT NULL,
+	`issue_number` integer NOT NULL,
+	`status` text DEFAULT 'queued' NOT NULL,
+	`branch` text,
+	`pr_number` integer,
+	`session_id` text,
+	`started_at` integer,
+	`finished_at` integer,
+	`model` text,
+	`max_turns` integer DEFAULT 40 NOT NULL,
+	`total_input_tokens` integer DEFAULT 0 NOT NULL,
+	`total_output_tokens` integer DEFAULT 0 NOT NULL,
+	`cost_usd` real DEFAULT 0 NOT NULL,
+	`ci_retry_count` integer DEFAULT 0 NOT NULL,
+	`error_message` text,
+	`created_at` integer DEFAULT (unixepoch()) NOT NULL,
+	FOREIGN KEY (`repo_id`) REFERENCES `repos`(`id`) ON UPDATE no action ON DELETE cascade
+);
+--> statement-breakpoint
+CREATE INDEX `jobs_repo_idx` ON `jobs` (`repo_id`);--> statement-breakpoint
+CREATE INDEX `jobs_status_idx` ON `jobs` (`status`);--> statement-breakpoint
+CREATE TABLE `prompt_templates` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`repo_id` integer,
+	`name` text NOT NULL,
+	`content` text NOT NULL,
+	`version` integer DEFAULT 1 NOT NULL,
+	`updated_at` integer DEFAULT (unixepoch()) NOT NULL,
+	FOREIGN KEY (`repo_id`) REFERENCES `repos`(`id`) ON UPDATE no action ON DELETE cascade
+);
+--> statement-breakpoint
+CREATE TABLE `repos` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`path` text NOT NULL,
+	`name` text NOT NULL,
+	`default_branch` text DEFAULT 'main' NOT NULL,
+	`queue_label` text DEFAULT 'drydock:queue' NOT NULL,
+	`working_label` text DEFAULT 'drydock:working' NOT NULL,
+	`needs_human_label` text DEFAULT 'drydock:needs-human' NOT NULL,
+	`default_model` text DEFAULT 'claude-sonnet-4-5' NOT NULL,
+	`created_at` integer DEFAULT (unixepoch()) NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE `settings` (
+	`key` text PRIMARY KEY NOT NULL,
+	`value` text NOT NULL
+);