feat(embedded): add host API for mounting Hunk

Author: khoaHyh

package.json

@@ -39,6 +39,10 @@
       "types": "./dist/npm/opentui/index.d.ts",
       "import": "./dist/npm/opentui/index.js"
     },
+    "./embedded": {
+      "types": "./dist/npm/embedded/index.d.ts",
+      "import": "./dist/npm/embedded/index.js"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {

scripts/build-npm.ts

@@ -8,6 +8,7 @@ const outdir = path.join(repoRoot, "dist", "npm");
 const typesOutdir = path.join(repoRoot, "dist", "npm-types");
 const opentuiOutdir = path.join(outdir, "opentui");
 const opentuiTypesDir = path.join(typesOutdir, "opentui");
+const embeddedOutdir = path.join(outdir, "embedded");
 
 const bunEnv = {
   ...process.env,
@@ -32,6 +33,7 @@ function runBun(args: string[]) {
 rmSync(outdir, { recursive: true, force: true });
 rmSync(typesOutdir, { recursive: true, force: true });
 mkdirSync(opentuiOutdir, { recursive: true });
+mkdirSync(embeddedOutdir, { recursive: true });
 
 runBun([
   "build",
@@ -81,6 +83,22 @@ runBun([
   "index.js",
 ]);
 
+const embeddedBuild = await Bun.build({
+  entrypoints: [path.join(repoRoot, "src", "embedded", "index.tsx")],
+  target: "node",
+  format: "esm",
+  outdir: embeddedOutdir,
+  naming: { entry: "index.js" },
+  external: ["@opentui/core", "@opentui/react", "@pierre/diffs", "react", "react/jsx-runtime"],
+});
+
+if (!embeddedBuild.success) {
+  for (const log of embeddedBuild.logs) {
+    console.error(log.message);
+  }
+  throw new Error("Failed to build embedded Hunk export.");
+}
+
 runBun(["x", "tsc", "-p", path.join(repoRoot, "tsconfig.opentui.json")]);
 
 for (const entry of readdirSync(opentuiTypesDir)) {
@@ -89,7 +107,13 @@ for (const entry of readdirSync(opentuiTypesDir)) {
   }
 }
 
+copyFileSync(
+  path.join(repoRoot, "src", "embedded", "index.d.ts"),
+  path.join(embeddedOutdir, "index.d.ts"),
+);
+
 rmSync(typesOutdir, { recursive: true, force: true });
 
 console.log(`Built ${mainJs}`);
 console.log(`Built ${path.join(opentuiOutdir, "index.js")}`);
+console.log(`Built ${path.join(embeddedOutdir, "index.js")}`);

src/embedded/embedded.test.ts

@@ -0,0 +1,141 @@
+import { describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createEmbeddedHunkSession, embeddedSourceToCliInput } from "./index";
+
+const patchText = [
+  "diff --git a/example.ts b/example.ts",
+  "--- a/example.ts",
+  "+++ b/example.ts",
+  "@@ -1 +1 @@",
+  "-const value = 1;",
+  "+const value = 2;",
+  "",
+].join("\n");
+
+describe("embeddedSourceToCliInput", () => {
+  test("maps embedded review sources to Hunk CLI inputs", () => {
+    expect(embeddedSourceToCliInput({ kind: "worktree", options: { theme: "midnight" } })).toEqual({
+      kind: "vcs",
+      staged: false,
+      options: { theme: "midnight" },
+    });
+    expect(embeddedSourceToCliInput({ kind: "staged" })).toEqual({
+      kind: "vcs",
+      staged: true,
+      options: {},
+    });
+    expect(embeddedSourceToCliInput({ kind: "show", ref: "HEAD~1" })).toEqual({
+      kind: "show",
+      ref: "HEAD~1",
+      options: {},
+    });
+    expect(
+      embeddedSourceToCliInput({
+        kind: "vcs",
+        range: "main",
+        staged: false,
+        pathspecs: ["src/app.ts"],
+        options: { vcs: "jj" },
+      }),
+    ).toEqual({
+      kind: "vcs",
+      range: "main",
+      staged: false,
+      pathspecs: ["src/app.ts"],
+      options: { vcs: "jj" },
+    });
+    expect(
+      embeddedSourceToCliInput({ kind: "diff", left: "before.ts", right: "after.ts" }),
+    ).toEqual({
+      kind: "diff",
+      left: "before.ts",
+      right: "after.ts",
+      options: {},
+    });
+    expect(embeddedSourceToCliInput({ kind: "stash-show", ref: "stash@{1}" })).toEqual({
+      kind: "stash-show",
+      ref: "stash@{1}",
+      options: {},
+    });
+    expect(embeddedSourceToCliInput({ kind: "patch", file: "changes.patch" })).toEqual({
+      kind: "patch",
+      file: "changes.patch",
+      options: {},
+    });
+    expect(
+      embeddedSourceToCliInput({
+        kind: "difftool",
+        left: "left.ts",
+        right: "right.ts",
+        path: "src/app.ts",
+      }),
+    ).toEqual({
+      kind: "difftool",
+      left: "left.ts",
+      right: "right.ts",
+      path: "src/app.ts",
+      options: {},
+    });
+  });
+
+  test("loads embedded sessions through Hunk config resolution", async () => {
+    const root = mkdtempSync(join(tmpdir(), "hunk-embedded-config-"));
+    const previousXdgConfigHome = process.env.XDG_CONFIG_HOME;
+
+    try {
+      const configHome = join(root, "config");
+      mkdirSync(join(configHome, "hunk"), { recursive: true });
+      writeFileSync(
+        join(configHome, "hunk", "config.toml"),
+        ['theme = "midnight"', 'mode = "stack"', "line_numbers = false"].join("\n"),
+      );
+      process.env.XDG_CONFIG_HOME = configHome;
+
+      const session = await createEmbeddedHunkSession({
+        cwd: root,
+        source: { kind: "patch", text: patchText, options: { theme: "paper" } },
+      });
+      const snapshot = session.getSnapshot();
+
+      expect(snapshot.status).toBe("ready");
+      if (snapshot.status !== "ready") throw new Error("Expected embedded session to load.");
+      expect(snapshot.bootstrap.initialMode).toBe("stack");
+      expect(snapshot.bootstrap.initialShowLineNumbers).toBe(false);
+      expect(snapshot.bootstrap.initialTheme).toBe("paper");
+
+      session.dispose();
+    } finally {
+      if (previousXdgConfigHome === undefined) {
+        delete process.env.XDG_CONFIG_HOME;
+      } else {
+        process.env.XDG_CONFIG_HOME = previousXdgConfigHome;
+      }
+      rmSync(root, { force: true, recursive: true });
+    }
+  });
+
+  test("keeps the previous source and reports errors when reload fails", async () => {
+    const root = mkdtempSync(join(tmpdir(), "hunk-embedded-reload-error-"));
+
+    try {
+      const initialSource = { kind: "patch", text: patchText, label: "initial patch" } as const;
+      const session = await createEmbeddedHunkSession({
+        cwd: root,
+        source: initialSource,
+      });
+
+      await expect(session.load({ kind: "patch", file: "missing.patch" })).rejects.toThrow();
+
+      expect(session.source).toEqual(initialSource);
+      const snapshot = session.getSnapshot();
+      expect(snapshot.status).toBe("error");
+      expect(snapshot.bootstrap).toBeDefined();
+
+      session.dispose();
+    } finally {
+      rmSync(root, { force: true, recursive: true });
+    }
+  });
+});

src/embedded/index.d.ts

@@ -0,0 +1,73 @@
+import type { CliRenderer, Renderable } from "@opentui/core";
+
+export interface EmbeddedHunkOptions {
+  mode?: "auto" | "split" | "stack";
+  vcs?: "git" | "jj";
+  theme?: string;
+  watch?: boolean;
+  excludeUntracked?: boolean;
+  lineNumbers?: boolean;
+  wrapLines?: boolean;
+  hunkHeaders?: boolean;
+  agentNotes?: boolean;
+}
+
+export type EmbeddedHunkSource =
+  | { kind: "worktree"; pathspecs?: string[]; options?: EmbeddedHunkOptions }
+  | { kind: "staged"; pathspecs?: string[]; options?: EmbeddedHunkOptions }
+  | {
+      kind: "vcs";
+      range?: string;
+      staged: boolean;
+      pathspecs?: string[];
+      options?: EmbeddedHunkOptions;
+    }
+  | { kind: "show"; ref?: string; pathspecs?: string[]; options?: EmbeddedHunkOptions }
+  | { kind: "stash-show"; ref?: string; options?: EmbeddedHunkOptions }
+  | { kind: "diff"; left: string; right: string; options?: EmbeddedHunkOptions }
+  | {
+      kind: "patch";
+      file?: string;
+      text?: string;
+      label?: string;
+      options?: EmbeddedHunkOptions;
+    }
+  | {
+      kind: "difftool";
+      left: string;
+      right: string;
+      path?: string;
+      options?: EmbeddedHunkOptions;
+    };
+
+export type EmbeddedHunkSnapshot =
+  | { status: "loading"; bootstrap?: unknown; error?: undefined }
+  | { status: "ready"; bootstrap: unknown; error?: undefined }
+  | { status: "error"; bootstrap?: unknown; error: string };
+
+export interface EmbeddedHunkSession {
+  readonly cwd: string;
+  readonly source: EmbeddedHunkSource;
+  getSnapshot(): EmbeddedHunkSnapshot;
+  load(source: EmbeddedHunkSource): Promise<void>;
+  subscribe(listener: () => void): () => void;
+  dispose(): void;
+}
+
+export interface EmbeddedHunkMount {
+  update(options: { active: boolean; onQuit: () => void }): void;
+  unmount(): void;
+}
+
+export declare function embeddedSourceToCliInput(source: EmbeddedHunkSource): unknown;
+export declare function createEmbeddedHunkSession(input: {
+  cwd?: string;
+  source: EmbeddedHunkSource;
+}): Promise<EmbeddedHunkSession>;
+export declare function mountEmbeddedHunkApp(input: {
+  active: boolean;
+  container: Renderable;
+  onQuit: () => void;
+  renderer: CliRenderer;
+  session: EmbeddedHunkSession;
+}): EmbeddedHunkMount;