mergie-cli 0.1.0

package/src/daemon/reviewService.ts

@@ -0,0 +1,243 @@
+import { isLockfile } from "@/domain/lockfiles.ts";
+import { commentAnchorHash, type DiffSide } from "@/domain/hash.ts";
+import { parseUnifiedDiff, type DiffLine, type FileStatus } from "@/domain/diff.ts";
+import { parseWordDiff, withWordChanges, type FileWordChanges } from "@/domain/wordDiff.ts";
+import type { CommentKind, CommentRow } from "@/db/repositories/comments.ts";
+import type { GithubThread } from "./githubThreads.ts";
+
+/** A comment resolved to a position within a hunk for rendering. */
+export interface AnchoredComment {
+  /** Comment id. */
+  id: number;
+  /** Markdown body. */
+  body: string;
+  /** Which side the comment is on. */
+  side: DiffSide;
+  /** Whether it targets a line range or the whole hunk. */
+  kind: CommentKind;
+  /** Index into `hunk.lines` the comment sits under; -1 for a whole-hunk comment. */
+  lineIndex: number;
+  /** Creation timestamp (ms). */
+  createdAt: number;
+  /** Last-updated timestamp (ms). */
+  updatedAt: number;
+  /** GitHub URL if this comment was posted; null otherwise. */
+  githubUrl: string | null;
+}
+
+/** A GitHub thread resolved to a position within a hunk for rendering. */
+export interface AnchoredGithubThread extends GithubThread {
+  /** Index into `hunk.lines` the thread sits under. */
+  lineIndex: number;
+}
+
+/** A hunk as presented to the UI for a range. */
+export interface HunkView {
+  /** Content hash identifying the hunk. */
+  hash: string;
+  /** Raw hunk header. */
+  header: string;
+  /** Base-side start line. */
+  oldStart: number;
+  /** Base-side line count. */
+  oldLines: number;
+  /** Head-side start line. */
+  newStart: number;
+  /** Head-side line count. */
+  newLines: number;
+  /** The hunk's lines. */
+  lines: DiffLine[];
+  /** Whether this hunk is marked viewed. */
+  viewed: boolean;
+  /** Comments anchored within this hunk. */
+  comments: AnchoredComment[];
+  /** Synced GitHub inline threads anchored within this hunk. */
+  githubThreads: AnchoredGithubThread[];
+}
+
+/** A file as presented to the UI for a range. */
+export interface FileView {
+  /** Base-side path. */
+  oldPath: string;
+  /** Head-side path. */
+  newPath: string;
+  /** How the file changed. */
+  status: FileStatus;
+  /** True for binary files (no textual hunks). */
+  isBinary: boolean;
+  /** True if the file matches a lock/generated-file pattern. */
+  isLockfile: boolean;
+  /** True when the file has hunks and all are viewed. */
+  viewed: boolean;
+  /** The file's hunks. */
+  hunks: HunkView[];
+}
+
+/** Collaborators needed to assemble a range view. */
+export interface BuildRangeDeps {
+  /** Produce the raw unified diff between two commits. */
+  rawDiff: (startSha: string, endSha: string) => Promise<string>;
+  /**
+   * Produce the porcelain word-diff between two commits, for intra-line change
+   * highlighting. Optional — when absent, lines carry no word-level ranges.
+   */
+  wordDiff?: (startSha: string, endSha: string) => Promise<string>;
+  /** Whether a hunk hash is marked viewed. */
+  isViewed: (hunkHash: string) => boolean;
+  /** Lock/generated-file glob patterns. */
+  lockfilePatterns: readonly string[];
+  /** All stored comments (attached to matching hunks/lines). */
+  comments?: readonly CommentRow[];
+  /** Synced GitHub threads (attached to matching hunks/lines). */
+  githubThreads?: readonly GithubThread[];
+}
+
+/** Look up a file's word-diff changes by either its base or head path. */
+class WordChangeIndex {
+  private readonly byPath = new Map<string, FileWordChanges>();
+
+  constructor(files: FileWordChanges[]) {
+    for (const f of files) {
+      this.byPath.set(f.newPath, f);
+      this.byPath.set(f.oldPath, f);
+    }
+  }
+
+  /** The changes for a file, matched on head path first then base path. */
+  forFile(oldPath: string, newPath: string): FileWordChanges | undefined {
+    return this.byPath.get(newPath) ?? this.byPath.get(oldPath);
+  }
+}
+
+/**
+ * Assemble the per-file, per-hunk view for a commit range: parse the diff,
+ * annotate each hunk with viewed state + anchored comments, and each file with
+ * its lock-file flag and auto-viewed status.
+ */
+export async function buildRangeView(
+  deps: BuildRangeDeps,
+  startSha: string,
+  endSha: string,
+): Promise<FileView[]> {
+  const [raw, wordRaw] = await Promise.all([
+    deps.rawDiff(startSha, endSha),
+    deps.wordDiff ? deps.wordDiff(startSha, endSha) : Promise.resolve(""),
+  ]);
+  const wordChanges = new WordChangeIndex(parseWordDiff(wordRaw));
+  const threads: readonly GithubThread[] = deps.githubThreads ?? [];
+  // Drop local comments already represented by a synced thread (posted from mergie).
+  const syncedRootIds = new Set<string>(threads.map((t) => t.root.githubId));
+  const comments: readonly CommentRow[] = (deps.comments ?? []).filter(
+    (c) => c.githubId === null || !syncedRootIds.has(c.githubId),
+  );
+  return parseUnifiedDiff(raw).map((file) => {
+    const fc = wordChanges.forFile(file.oldPath, file.newPath);
+    const hunks: HunkView[] = file.hunks.map((h) => ({
+      hash: h.hash,
+      header: h.header,
+      oldStart: h.oldStart,
+      oldLines: h.oldLines,
+      newStart: h.newStart,
+      newLines: h.newLines,
+      lines: withWordChanges(h.lines, fc),
+      viewed: deps.isViewed(h.hash),
+      comments: anchorComments(file.newPath, h.hash, h.lines, comments),
+      githubThreads: anchorGithubThreads(file.newPath, h.lines, threads),
+    }));
+    return {
+      oldPath: file.oldPath,
+      newPath: file.newPath,
+      status: file.status,
+      isBinary: file.isBinary,
+      isLockfile: isLockfile(file.newPath, deps.lockfilePatterns),
+      viewed: hunks.length > 0 && hunks.every((h) => h.viewed),
+      hunks,
+    };
+  });
+}
+
+/** Map a stored comment to its anchored view form. */
+function toAnchored(c: CommentRow, lineIndex: number): AnchoredComment {
+  return {
+    id: c.id, body: c.body, side: c.side, kind: c.kind, lineIndex,
+    createdAt: c.createdAt, updatedAt: c.updatedAt, githubUrl: c.githubUrl,
+  };
+}
+
+/**
+ * Find the comments that anchor to a hunk: whole-hunk comments whose anchor is
+ * the hunk hash, and line comments (single or multi-line) whose anchored text
+ * matches a contiguous block of same-side lines.
+ */
+function anchorComments(
+  path: string,
+  hunkHash: string,
+  lines: DiffLine[],
+  comments: readonly CommentRow[],
+): AnchoredComment[] {
+  const out: AnchoredComment[] = [];
+  for (const c of comments) {
+    if (c.path !== path) continue;
+    if (c.kind === "hunk") {
+      if (c.anchorHash === hunkHash) out.push(toAnchored(c, -1));
+      continue;
+    }
+    const span: number = c.startLine !== null && c.endLine !== null ? c.endLine - c.startLine + 1 : 1;
+    const idx = findAnchorWindow(path, lines, c.side, span, c.anchorHash);
+    if (idx !== null) out.push(toAnchored(c, idx));
+  }
+  return out;
+}
+
+/**
+ * Attach GitHub threads to a hunk: a thread anchors where the hunk has a line,
+ * on the thread's side, whose side-relative number equals the thread's line.
+ * Threads without a matching line in this range are dropped (not shown).
+ */
+function anchorGithubThreads(
+  path: string,
+  lines: DiffLine[],
+  threads: readonly GithubThread[],
+): AnchoredGithubThread[] {
+  const out: AnchoredGithubThread[] = [];
+  for (const t of threads) {
+    if (t.path !== path || t.line === null) continue;
+    const lineIndex: number = lines.findIndex((l) => {
+      const onSide = t.side === "RIGHT" ? l.kind !== "del" : l.kind !== "add";
+      const no = t.side === "RIGHT" ? l.newNo : l.oldNo;
+      return onSide && no === t.line;
+    });
+    if (lineIndex !== -1) out.push({ ...t, lineIndex });
+  }
+  return out;
+}
+
+/** Indices of lines that participate on a given diff side, in reading order. */
+function sideLineIndices(lines: DiffLine[], side: DiffSide): number[] {
+  const out: number[] = [];
+  lines.forEach((line, i) => {
+    const onSide = side === "RIGHT" ? line.kind === "add" || line.kind === "ctx" : line.kind === "del" || line.kind === "ctx";
+    if (onSide) out.push(i);
+  });
+  return out;
+}
+
+/**
+ * Locate a contiguous window of `span` same-side lines whose joined text hashes
+ * to `anchorHash`. Returns the window's first `lines` index, or null.
+ */
+function findAnchorWindow(
+  path: string,
+  lines: DiffLine[],
+  side: DiffSide,
+  span: number,
+  anchorHash: string,
+): number | null {
+  const sideIdx: number[] = sideLineIndices(lines, side);
+  for (let s = 0; s + span <= sideIdx.length; s++) {
+    const window: number[] = sideIdx.slice(s, s + span);
+    const text: string = window.map((i) => lines[i]?.text ?? "").join("\n");
+    if (commentAnchorHash(path, side, text) === anchorHash) return window[0] ?? null;
+  }
+  return null;
+}

package/src/daemon/router.ts

@@ -0,0 +1,287 @@
+import { z } from "zod";
+import { publicProcedure, router } from "./trpc.ts";
+import type { Context } from "./trpc.ts";
+import type { Workspace } from "./registry.ts";
+
+/** Resolve a loaded PR's workspace or throw a NOT_FOUND-style error. */
+function workspaceOrThrow(ctx: Context, id: string): Workspace {
+  const ws = ctx.registry.getWorkspace(id);
+  if (!ws) throw new Error(`PR not loaded: ${id}`);
+  return ws;
+}
+
+/** Input schema carrying a PR id. */
+const prInput = z.object({ id: z.string().min(1) });
+/** Input schema carrying a PR id + a commit range. */
+const rangeInput = z.object({ id: z.string().min(1), start: z.string().min(1), end: z.string().min(1) });
+
+/**
+ * The mergie tRPC router. End-to-end typed; the React UI infers its client
+ * types from `AppRouter`. New feature areas (diff, comments, symbols, ai) are
+ * added here as nested routers.
+ */
+export const appRouter = router({
+  /** Liveness + the set of loaded PRs. */
+  health: publicProcedure.query(({ ctx }) => ({ ok: true, prs: ctx.registry.listPrs() })),
+
+  /** List loaded PRs. */
+  listPrs: publicProcedure.query(({ ctx }) => ctx.registry.listPrs()),
+
+  /** Open PRs authored by / assigned to / review-requested from the viewer. */
+  listMyPrs: publicProcedure.query(({ ctx }) => ctx.search.listMyPrs()),
+
+  /** Load (or attach to) a PR by URL. */
+  loadPr: publicProcedure
+    .input(z.object({ url: z.string().min(1) }))
+    .mutation(({ ctx, input }) => ctx.registry.loadPr(input.url)),
+
+  /** Re-fetch a loaded PR (new commits / head movement) from GitHub. */
+  refreshPr: publicProcedure
+    .input(prInput)
+    .mutation(async ({ ctx, input }) => {
+      await workspaceOrThrow(ctx, input.id).refresh();
+      return { ok: true };
+    }),
+
+  /** Commits of a loaded PR, oldest → newest (no clone required). */
+  prCommits: publicProcedure
+    .input(prInput)
+    .query(({ ctx, input }) => ctx.registry.commits(input.id)),
+
+  /** Commit topology (baseline + commits) for the range selector. */
+  commitsWithBaseline: publicProcedure
+    .input(prInput)
+    .query(({ ctx, input }) => workspaceOrThrow(ctx, input.id).commitsWithBaseline()),
+
+  /** The default range to show on open. */
+  defaultRange: publicProcedure
+    .input(prInput)
+    .query(({ ctx, input }) => workspaceOrThrow(ctx, input.id).defaultRange()),
+
+  /** The file/hunk view for a commit range. */
+  rangeView: publicProcedure
+    .input(rangeInput.extend({ ignoreWhitespace: z.boolean().optional() }))
+    .query(({ ctx, input }) => workspaceOrThrow(ctx, input.id).rangeView(input.start, input.end, input.ignoreWhitespace)),
+
+  /** Set or clear a hunk's viewed state. */
+  setHunkViewed: publicProcedure
+    .input(z.object({ id: z.string().min(1), hunkHash: z.string().min(1), viewed: z.boolean() }))
+    .mutation(({ ctx, input }) => {
+      workspaceOrThrow(ctx, input.id).setHunkViewed(input.hunkHash, input.viewed);
+      return { ok: true };
+    }),
+
+  /** Mark a commit range reviewed. */
+  addReviewedRange: publicProcedure
+    .input(rangeInput)
+    .mutation(({ ctx, input }) => {
+      workspaceOrThrow(ctx, input.id).addReviewedRange(input.start, input.end);
+      return { ok: true };
+    }),
+
+  /** Un-mark a reviewed commit range. */
+  removeReviewedRange: publicProcedure
+    .input(rangeInput)
+    .mutation(({ ctx, input }) => {
+      workspaceOrThrow(ctx, input.id).removeReviewedRange(input.start, input.end);
+      return { ok: true };
+    }),
+
+  /** List reviewed ranges. */
+  listReviewedRanges: publicProcedure
+    .input(prInput)
+    .query(({ ctx, input }) => workspaceOrThrow(ctx, input.id).listReviewedRanges()),
+
+  /** All comments for a PR. */
+  listComments: publicProcedure
+    .input(prInput)
+    .query(({ ctx, input }) => workspaceOrThrow(ctx, input.id).listComments()),
+
+  /** Unified list (local + fetched GitHub, deduped) for the "All comments" view. */
+  listAllComments: publicProcedure
+    .input(prInput)
+    .query(({ ctx, input }) => workspaceOrThrow(ctx, input.id).listAllComments()),
+
+  /** Full-file side-by-side split rows for a path over a range. */
+  fileSplit: publicProcedure
+    .input(z.object({ id: z.string().min(1), path: z.string().min(1), start: z.string().min(1), end: z.string().min(1), ignoreWhitespace: z.boolean().optional() }))
+    .query(({ ctx, input }) => workspaceOrThrow(ctx, input.id).fileSplit(input.path, input.start, input.end, input.ignoreWhitespace)),
+
+  /** Create a comment on a line or a whole hunk. */
+  addComment: publicProcedure
+    .input(z.object({
+      id: z.string().min(1),
+      kind: z.enum(["lines", "hunk"]),
+      side: z.enum(["LEFT", "RIGHT"]),
+      path: z.string().min(1),
+      body: z.string().min(1),
+      madeAtSha: z.string().min(1),
+      lineText: z.string().optional(),
+      lineNo: z.number().optional(),
+      endLineNo: z.number().optional(),
+      hunkHash: z.string().optional(),
+    }))
+    .mutation(({ ctx, input }) => {
+      const { id, ...comment } = input;
+      return { id: workspaceOrThrow(ctx, id).addComment(comment) };
+    }),
+
+  /** Edit a comment's body (propagates to GitHub if posted). */
+  editComment: publicProcedure
+    .input(z.object({ id: z.string().min(1), commentId: z.number(), body: z.string().min(1) }))
+    .mutation(async ({ ctx, input }) => {
+      await workspaceOrThrow(ctx, input.id).editComment(input.commentId, input.body);
+      return { ok: true };
+    }),
+
+  /** Delete a comment (also deletes on GitHub if posted). */
+  deleteComment: publicProcedure
+    .input(z.object({ id: z.string().min(1), commentId: z.number() }))
+    .mutation(async ({ ctx, input }) => {
+      await workspaceOrThrow(ctx, input.id).deleteComment(input.commentId);
+      return { ok: true };
+    }),
+
+  /** Preview where a comment would post to GitHub (line + any warning). */
+  postCommentPreview: publicProcedure
+    .input(z.object({ id: z.string().min(1), commentId: z.number(), target: z.enum(["end", "head"]) }))
+    .query(({ ctx, input }) => workspaceOrThrow(ctx, input.id).postCommentPreview(input.commentId, input.target)),
+
+  /** Post a comment to GitHub as a single inline comment. */
+  postComment: publicProcedure
+    .input(z.object({ id: z.string().min(1), commentId: z.number(), target: z.enum(["end", "head"]) }))
+    .mutation(({ ctx, input }) => workspaceOrThrow(ctx, input.id).postComment(input.commentId, input.target)),
+
+  /** Pull GitHub inline comments into the local cache. */
+  syncGithub: publicProcedure
+    .input(prInput)
+    .mutation(async ({ ctx, input }) => ({ synced: await workspaceOrThrow(ctx, input.id).syncGithub() })),
+
+  /** Reply to a GitHub inline thread by its root comment id. */
+  replyToThread: publicProcedure
+    .input(z.object({ id: z.string().min(1), rootGithubId: z.string().min(1), body: z.string().min(1) }))
+    .mutation(async ({ ctx, input }) => {
+      await workspaceOrThrow(ctx, input.id).replyToThread(input.rootGithubId, input.body);
+      return { ok: true };
+    }),
+
+  /** Edit a GitHub comment (by GitHub id) the viewer authored. */
+  editGithubComment: publicProcedure
+    .input(z.object({ id: z.string().min(1), githubId: z.string().min(1), body: z.string().min(1) }))
+    .mutation(async ({ ctx, input }) => {
+      await workspaceOrThrow(ctx, input.id).editGithubComment(input.githubId, input.body);
+      return { ok: true };
+    }),
+
+  /** Delete a GitHub comment (by GitHub id) the viewer authored. */
+  deleteGithubComment: publicProcedure
+    .input(z.object({ id: z.string().min(1), githubId: z.string().min(1) }))
+    .mutation(async ({ ctx, input }) => {
+      await workspaceOrThrow(ctx, input.id).deleteGithubComment(input.githubId);
+      return { ok: true };
+    }),
+
+  /** Definition of a symbol via `sem`, at a commit's checkout (optional file scope). */
+  symbolDefinition: publicProcedure
+    .input(z.object({ id: z.string().min(1), symbol: z.string().min(1), sha: z.string().min(1), file: z.string().min(1).optional() }))
+    .query(({ ctx, input }) => workspaceOrThrow(ctx, input.id).symbolDefinition(input.symbol, input.sha, input.file)),
+
+  /** Usages of a symbol via `sem`, at a commit's checkout (optional file scope). */
+  symbolUsages: publicProcedure
+    .input(z.object({ id: z.string().min(1), symbol: z.string().min(1), sha: z.string().min(1), file: z.string().min(1).optional() }))
+    .query(({ ctx, input }) => workspaceOrThrow(ctx, input.id).symbolUsages(input.symbol, input.sha, input.file)),
+
+  /** Literal (default) or regex word search via `rg`, at a commit's checkout. */
+  symbolSearch: publicProcedure
+    .input(z.object({
+      id: z.string().min(1), word: z.string().min(1), sha: z.string().min(1),
+      caseSensitive: z.boolean().optional(), regex: z.boolean().optional(),
+    }))
+    .query(({ ctx, input }) => workspaceOrThrow(ctx, input.id).symbolSearch(input.word, input.sha, { caseSensitive: input.caseSensitive, regex: input.regex })),
+
+  /** Full text of a file at a commit (for a symbol result's full-file popup). */
+  fileAt: publicProcedure
+    .input(z.object({ id: z.string().min(1), sha: z.string().min(1), path: z.string().min(1) }))
+    .query(({ ctx, input }) => workspaceOrThrow(ctx, input.id).fileAt(input.sha, input.path)),
+
+  /** The selectable models + review templates from config. */
+  config: publicProcedure
+    .input(prInput)
+    .query(({ ctx, input }) => workspaceOrThrow(ctx, input.id).config()),
+
+  /** Start an AI chat session scoped to a hunk or file. */
+  createChatSession: publicProcedure
+    .input(z.object({
+      id: z.string().min(1),
+      scopeKind: z.enum(["hunk", "file"]),
+      scopeRef: z.string().min(1),
+      model: z.string().min(1),
+      title: z.string().optional(),
+    }))
+    .mutation(({ ctx, input }) => ({
+      sessionId: workspaceOrThrow(ctx, input.id).createChatSession(input.scopeKind, input.scopeRef, input.model, input.title),
+    })),
+
+  /** List chat sessions, optionally scoped to a hunk/file. */
+  listChatSessions: publicProcedure
+    .input(z.object({ id: z.string().min(1), scopeKind: z.enum(["hunk", "file"]).optional(), scopeRef: z.string().optional() }))
+    .query(({ ctx, input }) => workspaceOrThrow(ctx, input.id).listChatSessions(input.scopeKind, input.scopeRef)),
+
+  /** Messages for a chat session. */
+  listChatMessages: publicProcedure
+    .input(z.object({ id: z.string().min(1), sessionId: z.number() }))
+    .query(({ ctx, input }) => workspaceOrThrow(ctx, input.id).listChatMessages(input.sessionId)),
+
+  /** AI-generated artifacts, optionally scoped to a commit range. */
+  listArtifacts: publicProcedure
+    .input(z.object({ id: z.string().min(1), start: z.string().optional(), end: z.string().optional() }))
+    .query(({ ctx, input }) => {
+      const range = input.start && input.end ? { start: input.start, end: input.end } : undefined;
+      return workspaceOrThrow(ctx, input.id).listArtifacts(range);
+    }),
+
+  /** Run an AI review of a commit range (blocks until complete). */
+  runAiReview: publicProcedure
+    .input(z.object({
+      id: z.string().min(1),
+      start: z.string().min(1),
+      end: z.string().min(1),
+      model: z.string().min(1),
+      templateId: z.string().optional(),
+      prompt: z.string().optional(),
+    }))
+    .mutation(({ ctx, input }) => workspaceOrThrow(ctx, input.id).runAiReview(
+      { start: input.start, end: input.end },
+      { model: input.model, templateId: input.templateId, prompt: input.prompt },
+    )),
+
+  /** List AI reviews, optionally scoped to a commit range. */
+  listAiReviews: publicProcedure
+    .input(z.object({ id: z.string().min(1), start: z.string().optional(), end: z.string().optional() }))
+    .query(({ ctx, input }) => {
+      const range = input.start && input.end ? { start: input.start, end: input.end } : undefined;
+      return workspaceOrThrow(ctx, input.id).listAiReviews(range);
+    }),
+
+  /** In-flight / recently-completed AI-review statuses for this PR (for the header indicator). */
+  aiReviewStatuses: publicProcedure
+    .input(z.object({ id: z.string().min(1) }))
+    .query(({ ctx, input }) => workspaceOrThrow(ctx, input.id).aiReviewStatuses()),
+
+  /** Dismiss a completed AI-review status once the user has acted on it. */
+  dismissAiReviewStatus: publicProcedure
+    .input(z.object({ id: z.string().min(1), start: z.string().min(1), end: z.string().min(1) }))
+    .mutation(({ ctx, input }) => {
+      workspaceOrThrow(ctx, input.id).dismissAiReviewStatus({ start: input.start, end: input.end });
+      return { dismissed: true };
+    }),
+
+  /** Stop the daemon. */
+  stop: publicProcedure.mutation(({ ctx }) => {
+    ctx.requestStop();
+    return { stopping: true };
+  }),
+});
+
+/** Type of the mergie router, consumed by the typed client. */
+export type AppRouter = typeof appRouter;

package/src/daemon/server.ts

@@ -0,0 +1,106 @@
+import { join, normalize } from "node:path";
+import { fetchRequestHandler } from "@trpc/server/adapters/fetch";
+import { appRouter } from "./router.ts";
+import { handleChatMessage } from "./chatSocket.ts";
+import type { ServerWebSocket } from "bun";
+import type { Context } from "./trpc.ts";
+import type { PrRegistry } from "./registry.ts";
+import { createGhSearchService, type GhSearchService } from "@/services/ghSearch.ts";
+
+/** A running daemon instance. */
+export interface DaemonHandle {
+  /** The bound port. */
+  port: number;
+  /** Base URL, e.g. `http://localhost:4517`. */
+  url: string;
+  /** Stop the server. */
+  stop: () => void;
+}
+
+/** Options for starting the daemon. */
+export interface StartDaemonOptions {
+  /** Port to bind (0 = random, useful for tests). */
+  port: number;
+  /** The PR registry backing the API. */
+  registry: PrRegistry;
+  /** GitHub PR-search service (defaults to the real `gh`-backed service). */
+  search?: GhSearchService;
+  /** Called when the `stop` procedure runs (defaults to stopping the server). */
+  requestStop?: () => void;
+  /** Directory of built static UI assets to serve (optional). */
+  staticDir?: string;
+}
+
+/** tRPC endpoint prefix. */
+const TRPC_PREFIX = "/trpc";
+
+/** WebSocket path for streaming AI chat. */
+const CHAT_WS_PATH = "/ws/chat";
+
+/**
+ * Start the mergie daemon: serves the tRPC API under `/trpc` and, if
+ * `staticDir` is given, the built React UI for all other routes (SPA
+ * fallback to `index.html`).
+ */
+export async function startDaemon(opts: StartDaemonOptions): Promise<DaemonHandle> {
+  const ctx: Context = {
+    registry: opts.registry,
+    search: opts.search ?? createGhSearchService(),
+    requestStop: () => opts.requestStop?.(),
+  };
+
+  const server = Bun.serve({
+    port: opts.port,
+    async fetch(req: Request, srv): Promise<Response | undefined> {
+      const url = new URL(req.url);
+      if (url.pathname === CHAT_WS_PATH) {
+        return srv.upgrade(req) ? undefined : new Response("Upgrade failed", { status: 400 });
+      }
+      if (url.pathname === "/artifact") {
+        return serveArtifact(url, opts.registry);
+      }
+      if (url.pathname === TRPC_PREFIX || url.pathname.startsWith(`${TRPC_PREFIX}/`)) {
+        return fetchRequestHandler({
+          endpoint: TRPC_PREFIX,
+          req,
+          router: appRouter,
+          createContext: () => Promise.resolve(ctx),
+        });
+      }
+      return serveStatic(url.pathname, opts.staticDir);
+    },
+    websocket: {
+      async message(ws: ServerWebSocket, message: string | Buffer): Promise<void> {
+        await handleChatMessage(opts.registry, String(message), (data) => ws.send(JSON.stringify(data)));
+      },
+    },
+  });
+
+  const boundPort: number = server.port ?? opts.port;
+  return {
+    port: boundPort,
+    url: `http://localhost:${boundPort}`,
+    stop: () => server.stop(true),
+  };
+}
+
+/** Serve an AI-generated artifact file (`/artifact?id=<prId>&path=<relPath>`). */
+async function serveArtifact(url: URL, registry: PrRegistry): Promise<Response> {
+  const id: string | null = url.searchParams.get("id");
+  const relPath: string | null = url.searchParams.get("path");
+  if (!id || !relPath) return new Response("Bad request", { status: 400 });
+  const ws = registry.getWorkspace(id);
+  const abs: string | null = ws ? ws.resolveArtifact(relPath) : null;
+  if (!abs) return new Response("Not found", { status: 404 });
+  const file = Bun.file(abs);
+  return (await file.exists()) ? new Response(file) : new Response("Not found", { status: 404 });
+}
+
+/** Serve a static file from `staticDir`, falling back to `index.html` (SPA). */
+async function serveStatic(pathname: string, staticDir?: string): Promise<Response> {
+  if (!staticDir) return new Response("Not found", { status: 404 });
+  const rel: string = normalize(pathname).replace(/^(\.\.[/\\])+/, "");
+  const candidate = Bun.file(join(staticDir, rel === "/" ? "index.html" : rel));
+  if (await candidate.exists()) return new Response(candidate);
+  return new Response(Bun.file(join(staticDir, "index.html")));
+}