@sansavision/aurora 0.1.0-alpha.20260212.4

package/test/create-route.test.ts

@@ -0,0 +1,117 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { describe, expect, it } from "bun:test";
+
+import { runAuroraCli } from "../src";
+
+let tempCounter = 1;
+
+function uniqueTempPath(suffix: string): string {
+  tempCounter += 1;
+  return `/tmp/aurora-cli-create-route-${suffix}-${Date.now()}-${tempCounter}`;
+}
+
+describe("aurora create-route", () => {
+  it("scaffolds a default form route with novice-safe boilerplate", () => {
+    const cwd = uniqueTempPath("default");
+    mkdirSync(cwd, { recursive: true });
+
+    const result = runAuroraCli(["create-route", "guestbook"], { cwd });
+    const routeRoot = join(cwd, "src/routes/guestbook");
+
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("aurora create-route bootstrap");
+    expect(result.stdout).toContain("route_slug: guestbook");
+    expect(result.stdout).toContain("route_kind: form");
+    expect(result.stdout).toContain("auth: public");
+
+    expect(existsSync(join(routeRoot, "page.tsx"))).toBe(true);
+    expect(existsSync(join(routeRoot, "guestbook.client.tsx"))).toBe(true);
+    expect(existsSync(join(routeRoot, "guestbook.server.ts"))).toBe(true);
+
+    const serverSource = readFileSync(join(routeRoot, "guestbook.server.ts"), "utf8");
+    expect(serverSource).toContain('export const runtime = "node";');
+    expect(serverSource).toContain('export const auth = "public";');
+    expect(serverSource).toContain("export async function listGuestbook");
+    expect(serverSource).toContain("export async function submitGuestbook");
+  });
+
+  it("supports kind/data/auth/realtime options", () => {
+    const cwd = uniqueTempPath("custom");
+    mkdirSync(cwd, { recursive: true });
+
+    const result = runAuroraCli(
+      [
+        "create-route",
+        "alerts",
+        "--kind",
+        "dashboard",
+        "--data",
+        "api",
+        "--auth",
+        "user",
+        "--realtime",
+      ],
+      { cwd },
+    );
+
+    const routeRoot = join(cwd, "src/routes/alerts");
+    const serverSource = readFileSync(join(routeRoot, "alerts.server.ts"), "utf8");
+
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("route_kind: dashboard");
+    expect(result.stdout).toContain("data_source: api");
+    expect(result.stdout).toContain("auth: user");
+    expect(result.stdout).toContain("realtime: enabled");
+
+    expect(serverSource).toContain('export const auth = "user";');
+    expect(serverSource).toContain('export const dataSource = "api";');
+    expect(serverSource).toContain("loadAlertsMetrics");
+    expect(serverSource).toContain("AlertsRealtimeChannel");
+  });
+
+  it("returns a parse error when route name is missing", () => {
+    const cwd = uniqueTempPath("missing");
+    mkdirSync(cwd, { recursive: true });
+
+    const result = runAuroraCli(["create-route"], { cwd });
+
+    expect(result.exitCode).toBe(2);
+    expect(result.stderr).toContain("aurora create-route: route name is required");
+  });
+
+  it("rejects invalid kind/data/auth values and unknown options", () => {
+    const cwd = uniqueTempPath("invalid");
+    mkdirSync(cwd, { recursive: true });
+
+    const invalidKind = runAuroraCli(["create-route", "x", "--kind", "wizard"], { cwd });
+    const invalidData = runAuroraCli(["create-route", "x", "--data", "cache"], { cwd });
+    const invalidAuth = runAuroraCli(["create-route", "x", "--auth", "guest"], { cwd });
+    const unknown = runAuroraCli(["create-route", "x", "--dry-run"], { cwd });
+
+    expect(invalidKind.exitCode).toBe(2);
+    expect(invalidKind.stderr).toContain("--kind requires one of crud|read-only|form|dashboard|empty");
+
+    expect(invalidData.exitCode).toBe(2);
+    expect(invalidData.stderr).toContain("--data requires one of database|api|none");
+
+    expect(invalidAuth.exitCode).toBe(2);
+    expect(invalidAuth.stderr).toContain("--auth requires 'public', 'user', 'admin', or 'permission:<name>'");
+
+    expect(unknown.exitCode).toBe(2);
+    expect(unknown.stderr).toContain("unknown option '--dry-run'");
+  });
+
+  it("returns an error when route directory already exists and is not empty", () => {
+    const cwd = uniqueTempPath("exists");
+    const routeRoot = join(cwd, "src/routes/reports");
+    mkdirSync(routeRoot, { recursive: true });
+    writeFileSync(join(routeRoot, "seed.txt"), "seed\n", "utf8");
+
+    const result = runAuroraCli(["create-route", "reports"], { cwd });
+
+    expect(result.exitCode).toBe(2);
+    expect(result.stderr).toContain("target directory already exists and is not empty");
+  });
+});

package/test/create.test.ts

@@ -0,0 +1,222 @@
+import { describe, expect, it } from "bun:test";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { runAuroraCli } from "../src";
+
+let tempCounter = 1;
+
+function uniqueTempPath(suffix: string): string {
+  tempCounter += 1;
+  return `/tmp/aurora-cli-create-${suffix}-${Date.now()}-${tempCounter}`;
+}
+
+describe("aurora create", () => {
+  it("creates a project scaffold with default basic template", () => {
+    const cwd = uniqueTempPath("cwd-basic");
+    mkdirSync(cwd, { recursive: true });
+
+    const result = runAuroraCli(["create", "my-app"], { cwd });
+    const projectRoot = join(cwd, "my-app");
+
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("aurora create bootstrap");
+    expect(result.stdout).toContain("template: basic");
+    expect(result.stdout).toContain(`project_root: ${projectRoot}`);
+
+    expect(existsSync(join(projectRoot, "package.json"))).toBe(true);
+    expect(existsSync(join(projectRoot, "src/routes/index.tsx"))).toBe(true);
+    expect(existsSync(join(projectRoot, "src/actions/createMessage.action.server.ts"))).toBe(true);
+    expect(existsSync(join(projectRoot, "src/queries/listMessages.server.ts"))).toBe(true);
+    expect(existsSync(join(projectRoot, "src/lib/auth.server.ts"))).toBe(true);
+    expect(existsSync(join(projectRoot, "aurora.template.json"))).toBe(true);
+
+    const templateMeta = readFileSync(join(projectRoot, "aurora.template.json"), "utf8");
+    expect(templateMeta).toContain("\"template\": \"basic\"");
+    const readme = readFileSync(join(projectRoot, "README.md"), "utf8");
+    expect(readme).toContain("Aurora basic starter template.");
+  });
+
+  it("supports template selection and --git scaffold option", () => {
+    const cwd = uniqueTempPath("cwd-dashboard");
+    mkdirSync(cwd, { recursive: true });
+
+    const result = runAuroraCli(["create", "dash-app", "--template", "dashboard", "--git"], {
+      cwd,
+    });
+    const projectRoot = join(cwd, "dash-app");
+
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("template: dashboard");
+    expect(result.stdout).toContain("git: enabled");
+
+    expect(existsSync(join(projectRoot, ".gitignore"))).toBe(true);
+    const readme = readFileSync(join(projectRoot, "README.md"), "utf8");
+    expect(readme).toContain("Template: dashboard");
+  });
+
+  it("scaffolds dashboard template with chart/grid/realtime seams", () => {
+    const cwd = uniqueTempPath("cwd-dashboard-assets");
+    mkdirSync(cwd, { recursive: true });
+
+    const result = runAuroraCli(["create", "dashboard-app", "--template", "dashboard"], {
+      cwd,
+    });
+    const projectRoot = join(cwd, "dashboard-app");
+
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("template: dashboard");
+    expect(existsSync(join(projectRoot, "src/widgets/MetricChart.client.ts"))).toBe(true);
+    expect(existsSync(join(projectRoot, "src/widgets/DataGrid.client.ts"))).toBe(true);
+    expect(existsSync(join(projectRoot, "src/realtime/useDashboardRealtime.client.ts"))).toBe(
+      true,
+    );
+    expect(existsSync(join(projectRoot, "src/queries/getDashboardMetrics.server.ts"))).toBe(true);
+  });
+
+  it("scaffolds the saas template with auth/billing/realtime/email seams", () => {
+    const cwd = uniqueTempPath("cwd-saas");
+    mkdirSync(cwd, { recursive: true });
+
+    const result = runAuroraCli(["create", "saas-app", "--template", "saas"], {
+      cwd,
+    });
+    const projectRoot = join(cwd, "saas-app");
+
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("template: saas");
+    expect(existsSync(join(projectRoot, "src/auth/session.server.ts"))).toBe(true);
+    expect(existsSync(join(projectRoot, "src/billing/checkout.server.ts"))).toBe(true);
+    expect(existsSync(join(projectRoot, "src/realtime/notifications.server.ts"))).toBe(true);
+    expect(existsSync(join(projectRoot, "src/email/sendWelcome.server.ts"))).toBe(true);
+  });
+
+  it("scaffolds the blog template with markdown, seo, and static assets", () => {
+    const cwd = uniqueTempPath("cwd-blog");
+    mkdirSync(cwd, { recursive: true });
+
+    const result = runAuroraCli(["create", "blog-app", "--template", "blog"], {
+      cwd,
+    });
+    const projectRoot = join(cwd, "blog-app");
+
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("template: blog");
+    expect(existsSync(join(projectRoot, "src/content/posts/hello-world.md"))).toBe(true);
+    expect(existsSync(join(projectRoot, "src/content/posts/release-notes.md"))).toBe(true);
+    expect(existsSync(join(projectRoot, "src/seo/meta.ts"))).toBe(true);
+    expect(existsSync(join(projectRoot, "src/routes/posts/[slug].tsx"))).toBe(true);
+    expect(existsSync(join(projectRoot, "public/assets/og-default.svg"))).toBe(true);
+
+    const readme = readFileSync(join(projectRoot, "README.md"), "utf8");
+    expect(readme).toContain("Aurora blog starter template.");
+  });
+
+  it("scaffolds the desktop template with tauri and secure-storage seams", () => {
+    const cwd = uniqueTempPath("cwd-desktop");
+    mkdirSync(cwd, { recursive: true });
+
+    const result = runAuroraCli(["create", "desktop-app", "--template", "desktop"], {
+      cwd,
+    });
+    const projectRoot = join(cwd, "desktop-app");
+
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("template: desktop");
+    expect(existsSync(join(projectRoot, "src/desktop/tauriBridge.client.ts"))).toBe(true);
+    expect(existsSync(join(projectRoot, "src/desktop/secureStorage.client.ts"))).toBe(true);
+    expect(existsSync(join(projectRoot, "src/sync/offlineSyncBoundary.server.ts"))).toBe(true);
+    expect(existsSync(join(projectRoot, "src/queries/getDesktopSyncStatus.server.ts"))).toBe(
+      true,
+    );
+    expect(
+      existsSync(join(projectRoot, "src/actions/saveDesktopPreference.action.server.ts")),
+    ).toBe(true);
+
+    const readme = readFileSync(join(projectRoot, "README.md"), "utf8");
+    expect(readme).toContain("Aurora desktop starter template.");
+  });
+
+  it("scaffolds the mobile template with typed SDK and retry transport seams", () => {
+    const cwd = uniqueTempPath("cwd-mobile");
+    mkdirSync(cwd, { recursive: true });
+
+    const result = runAuroraCli(["create", "mobile-app", "--template", "mobile"], {
+      cwd,
+    });
+    const projectRoot = join(cwd, "mobile-app");
+
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("template: mobile");
+    expect(existsSync(join(projectRoot, "src/mobile/generated/mobile-api-sdk.ts"))).toBe(true);
+    expect(
+      existsSync(join(projectRoot, "src/mobile/auth/session-handoff.client.ts")),
+    ).toBe(true);
+    expect(
+      existsSync(join(projectRoot, "src/mobile/transport/mobile-api-transport.client.ts")),
+    ).toBe(true);
+    expect(existsSync(join(projectRoot, "src/routes/index.tsx"))).toBe(true);
+
+    const readme = readFileSync(join(projectRoot, "README.md"), "utf8");
+    expect(readme).toContain("Aurora mobile companion starter template.");
+  });
+
+  it("supports monorepo template layout", () => {
+    const cwd = uniqueTempPath("cwd-monorepo");
+    mkdirSync(cwd, { recursive: true });
+
+    const result = runAuroraCli(["create", "mono-app", "--template", "monorepo"], { cwd });
+    const projectRoot = join(cwd, "mono-app");
+
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("template: monorepo");
+    expect(existsSync(join(projectRoot, "apps/web/src/routes/index.tsx"))).toBe(true);
+    expect(existsSync(join(projectRoot, "packages/ui/README.md"))).toBe(true);
+    expect(existsSync(join(projectRoot, "packages/shared/README.md"))).toBe(true);
+
+    const rootReadme = readFileSync(join(projectRoot, "README.md"), "utf8");
+    expect(rootReadme).toContain("Template: monorepo");
+  });
+
+  it("returns an error when project name is missing", () => {
+    const cwd = uniqueTempPath("cwd-missing-name");
+    mkdirSync(cwd, { recursive: true });
+
+    const result = runAuroraCli(["create"], { cwd });
+
+    expect(result.exitCode).toBe(2);
+    expect(result.stderr).toContain("aurora create: project name is required");
+  });
+
+  it("returns an error for invalid template values", () => {
+    const cwd = uniqueTempPath("cwd-invalid-template");
+    mkdirSync(cwd, { recursive: true });
+
+    const result = runAuroraCli(["create", "my-app", "--template", "unknown"], { cwd });
+
+    expect(result.exitCode).toBe(2);
+    expect(result.stderr).toContain("aurora create: invalid template 'unknown'");
+  });
+
+  it("returns an error when target directory already exists and is not empty", () => {
+    const cwd = uniqueTempPath("cwd-existing");
+    const projectRoot = join(cwd, "existing-app");
+    mkdirSync(projectRoot, { recursive: true });
+    writeFileSync(join(projectRoot, "seed.txt"), "seed\n", "utf8");
+
+    const result = runAuroraCli(["create", "existing-app"], { cwd });
+
+    expect(result.exitCode).toBe(2);
+    expect(result.stderr).toContain("target directory already exists and is not empty");
+  });
+
+  it("returns an error for unknown create options", () => {
+    const cwd = uniqueTempPath("cwd-unknown-option");
+    mkdirSync(cwd, { recursive: true });
+
+    const result = runAuroraCli(["create", "my-app", "--open"], { cwd });
+
+    expect(result.exitCode).toBe(2);
+    expect(result.stderr).toContain("aurora create: unknown option '--open'");
+  });
+});

package/test/dev.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from "bun:test";
+
+import { runAuroraCli } from "../src";
+
+describe("aurora dev", () => {
+  const cwd = "/tmp/aurora-dev";
+
+  it("prints bootstrap output with default HTTP and HMR bridge settings", () => {
+    const result = runAuroraCli(["dev"], { cwd });
+
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("aurora dev bootstrap");
+    expect(result.stdout).toContain("url: http://localhost:3000");
+    expect(result.stdout).toContain("hmr_bridge: ws://localhost:3000/__aurora_hmr");
+    expect(result.stdout).toContain("open_browser: disabled");
+    expect(result.stdout).toContain("https: disabled");
+  });
+
+  it("supports --port, --open, and --https options", () => {
+    const result = runAuroraCli(["dev", "--port", "4310", "--open", "--https"], { cwd });
+
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("url: https://localhost:4310");
+    expect(result.stdout).toContain("hmr_bridge: wss://localhost:4310/__aurora_hmr");
+    expect(result.stdout).toContain("open_browser: enabled");
+    expect(result.stdout).toContain("https: enabled");
+  });
+
+  it("returns an error when --port is missing a value", () => {
+    const result = runAuroraCli(["dev", "--port"], { cwd });
+
+    expect(result.exitCode).toBe(2);
+    expect(result.stderr).toContain("aurora dev: --port requires a numeric value");
+  });
+
+  it("returns an error for out-of-range or invalid --port values", () => {
+    const nonNumeric = runAuroraCli(["dev", "--port", "abc"], { cwd });
+    const outOfRange = runAuroraCli(["dev", "--port", "70000"], { cwd });
+
+    expect(nonNumeric.exitCode).toBe(2);
+    expect(nonNumeric.stderr).toContain("aurora dev: --port must be an integer between 1 and 65535");
+    expect(outOfRange.exitCode).toBe(2);
+    expect(outOfRange.stderr).toContain("aurora dev: --port must be an integer between 1 and 65535");
+  });
+
+  it("returns an error for unknown options", () => {
+    const result = runAuroraCli(["dev", "--unknown"], { cwd });
+
+    expect(result.exitCode).toBe(2);
+    expect(result.stderr).toContain("aurora dev: unknown option '--unknown'");
+  });
+});

package/test/devtools.test.ts

@@ -0,0 +1,130 @@
+import { join } from "node:path";
+
+import { describe, expect, it } from "bun:test";
+
+import { runAuroraCli } from "../src";
+
+const projectRoot = join(import.meta.dir, "..");
+
+function fixturePath(name: string): string {
+  return join("test/fixtures/devtools", name);
+}
+
+describe("aurora devtools", () => {
+  it("renders all v2 panels in text output for healthy input", () => {
+    const result = runAuroraCli(
+      ["devtools", "--input", fixturePath("healthy.v1.json")],
+      { cwd: projectRoot },
+    );
+
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("aurora devtools report");
+    expect(result.stdout).toContain("status: ok");
+    expect(result.stdout).toContain("[explain]");
+    expect(result.stdout).toContain("[waterfall]");
+    expect(result.stdout).toContain("[performance]");
+    expect(result.stdout).toContain("[realtime]");
+    expect(result.stdout).toContain("[auth]");
+    expect(result.stdout).toContain("query_auth: admin,user");
+    expect(result.stdout).toContain("auth_scoped_subscriptions: admin:1,user:1");
+  });
+
+  it("returns warn status and non-zero exit when panel issues are present", () => {
+    const result = runAuroraCli(
+      ["devtools", "--input", fixturePath("warn.v1.json")],
+      { cwd: projectRoot },
+    );
+
+    expect(result.exitCode).toBe(1);
+    expect(result.stdout).toContain("status: warn");
+    expect(result.stdout).toContain("[EXPLAIN_WARNINGS_PRESENT]");
+    expect(result.stdout).toContain("[BLOCKING_OPERATION_SLOW]");
+    expect(result.stdout).toContain("[ROUTE_SCORE_BELOW_MIN]");
+    expect(result.stdout).toContain("[CONNECTION_UNSTABLE]");
+    expect(result.stdout).toContain("[ROUTE_AUTH_SESSION_MISMATCH]");
+  });
+
+  it("supports json output, panel filtering, and custom thresholds", () => {
+    const result = runAuroraCli(
+      [
+        "devtools",
+        "--input",
+        fixturePath("healthy.v1.json"),
+        "--format",
+        "json",
+        "--panel",
+        "performance,realtime",
+        "--panel",
+        "auth",
+        "--min-route-score",
+        "95",
+        "--max-lag-p95-ms",
+        "100",
+      ],
+      { cwd: projectRoot },
+    );
+
+    expect(result.exitCode).toBe(1);
+    const parsed = JSON.parse(result.stdout ?? "{}") as {
+      mode?: string;
+      status?: string;
+      selectedPanels?: string[];
+      panels?: Array<{ name?: string; status?: string }>;
+    };
+
+    expect(parsed.mode).toBe("devtools");
+    expect(parsed.status).toBe("warn");
+    expect(parsed.selectedPanels).toEqual(["performance", "realtime", "auth"]);
+    expect(parsed.panels?.length).toBe(3);
+    expect(parsed.panels?.some((panel) => panel.name === "performance")).toBe(true);
+    expect(parsed.panels?.some((panel) => panel.name === "realtime" && panel.status === "warn")).toBe(
+      true,
+    );
+    expect(parsed.panels?.some((panel) => panel.name === "auth")).toBe(true);
+    expect(parsed.panels?.some((panel) => panel.name === "explain")).toBe(false);
+  });
+
+  it("rejects missing required options and unknown flags", () => {
+    const missingInput = runAuroraCli(["devtools"], { cwd: projectRoot });
+    const unknown = runAuroraCli(
+      ["devtools", "--input", fixturePath("healthy.v1.json"), "--unknown"],
+      { cwd: projectRoot },
+    );
+    const badPanel = runAuroraCli(
+      ["devtools", "--input", fixturePath("healthy.v1.json"), "--panel", "cache"],
+      { cwd: projectRoot },
+    );
+
+    expect(missingInput.exitCode).toBe(2);
+    expect(missingInput.stderr).toContain("aurora devtools: --input is required");
+    expect(unknown.exitCode).toBe(2);
+    expect(unknown.stderr).toContain("aurora devtools: unknown option '--unknown'");
+    expect(badPanel.exitCode).toBe(2);
+    expect(badPanel.stderr).toContain(
+      "aurora devtools: invalid panel 'cache'. Expected one of explain, waterfall, performance, realtime, auth",
+    );
+  });
+
+  it("fails for invalid json and unsupported schema versions", () => {
+    const invalidJsonPath = fixturePath("invalid.json");
+    const unsupportedVersionPath = fixturePath("unsupported-version.v2.json");
+
+    const invalidJson = runAuroraCli(
+      ["devtools", "--input", invalidJsonPath],
+      { cwd: projectRoot },
+    );
+    const unsupportedVersion = runAuroraCli(
+      ["devtools", "--input", unsupportedVersionPath],
+      { cwd: projectRoot },
+    );
+
+    expect(invalidJson.exitCode).toBe(1);
+    expect(invalidJson.stderr).toContain(
+      `aurora devtools: invalid json input at ${invalidJsonPath}`,
+    );
+    expect(unsupportedVersion.exitCode).toBe(1);
+    expect(unsupportedVersion.stderr).toContain(
+      "aurora devtools: unsupported schemaVersion 2; expected 1",
+    );
+  });
+});

package/test/doctor.test.ts

@@ -0,0 +1,129 @@
+import { join } from "node:path";
+
+import { describe, expect, it } from "bun:test";
+
+import { runAuroraCli } from "../src";
+
+describe("aurora doctor", () => {
+  const fixturesRoot = join(import.meta.dir, "fixtures/doctor");
+
+  it("returns a clean report when no issues are found", () => {
+    const result = runAuroraCli(["doctor", "--format", "json"], {
+      cwd: join(fixturesRoot, "clean"),
+    });
+
+    expect(result.exitCode).toBe(0);
+    const parsed = JSON.parse(result.stdout ?? "{}") as {
+      issues?: unknown[];
+      errors?: number;
+      warnings?: number;
+      byCategory?: Record<string, number>;
+    };
+
+    expect(parsed.errors).toBe(0);
+    expect(parsed.warnings).toBe(0);
+    expect(Array.isArray(parsed.issues)).toBe(true);
+    expect(parsed.issues?.length).toBe(0);
+    expect(parsed.byCategory?.boundary).toBe(0);
+    expect(parsed.byCategory?.security).toBe(0);
+    expect(parsed.byCategory?.performance).toBe(0);
+    expect(parsed.byCategory?.a11y).toBe(0);
+    expect(parsed.byCategory?.migration).toBe(0);
+    expect(parsed.byCategory?.governance).toBe(0);
+  });
+
+  it("reports boundary/security/perf/a11y/migration findings with actionable remediation", () => {
+    const result = runAuroraCli(["doctor", "--format", "json"], {
+      cwd: join(fixturesRoot, "findings"),
+    });
+
+    expect(result.exitCode).toBe(1);
+    const parsed = JSON.parse(result.stdout ?? "{}") as {
+      errors?: number;
+      warnings?: number;
+      byCategory?: Record<string, number>;
+      issues?: Array<{
+        code?: string;
+        remediation?: string;
+        ai?: { why?: string; howToFix?: string; docs?: string };
+      }>;
+    };
+
+    expect(parsed.errors).toBe(2);
+    expect(parsed.warnings).toBe(7);
+    expect(parsed.byCategory?.boundary).toBe(1);
+    expect(parsed.byCategory?.migration).toBe(2);
+    expect(parsed.byCategory?.security).toBe(2);
+    expect(parsed.byCategory?.performance).toBe(2);
+    expect(parsed.byCategory?.a11y).toBe(2);
+    expect(parsed.byCategory?.governance).toBe(0);
+
+    expect(parsed.issues?.some((issue) => issue.code === "BOUNDARY_CLIENT_IMPORTS_SERVER")).toBe(
+      true,
+    );
+    expect(parsed.issues?.some((issue) => issue.code === "DEPRECATED_ROUTE_API")).toBe(true);
+    expect(parsed.issues?.some((issue) => issue.code === "MIGRATION_MANUAL_ROUTES_ARRAY")).toBe(
+      true,
+    );
+    expect(parsed.issues?.some((issue) => issue.code === "SECURITY_DYNAMIC_CODE_EXECUTION")).toBe(
+      true,
+    );
+    expect(parsed.issues?.some((issue) => issue.code === "SECURITY_RAW_SQL_STRING")).toBe(true);
+    expect(parsed.issues?.some((issue) => issue.code === "PERF_UNBOUNDED_QUERY")).toBe(true);
+    expect(parsed.issues?.some((issue) => issue.code === "PERF_N_PLUS_ONE_LOOP_AWAIT")).toBe(
+      true,
+    );
+    expect(parsed.issues?.some((issue) => issue.code === "A11Y_IMAGE_MISSING_ALT")).toBe(true);
+    expect(parsed.issues?.some((issue) => issue.code === "A11Y_CLICKABLE_NON_INTERACTIVE")).toBe(
+      true,
+    );
+    expect(parsed.issues?.every((issue) => Boolean(issue.remediation))).toBe(true);
+    expect(parsed.issues?.every((issue) => Boolean(issue.ai?.why))).toBe(true);
+    expect(parsed.issues?.every((issue) => Boolean(issue.ai?.howToFix))).toBe(true);
+    expect(parsed.issues?.every((issue) => Boolean(issue.ai?.docs))).toBe(true);
+  });
+
+  it("renders text output and rejects unknown options", () => {
+    const textResult = runAuroraCli(["doctor"], {
+      cwd: join(fixturesRoot, "findings"),
+    });
+    const invalidOptionResult = runAuroraCli(["doctor", "--unknown"], {
+      cwd: join(fixturesRoot, "clean"),
+    });
+
+    expect(textResult.exitCode).toBe(1);
+    expect(textResult.stdout).toContain("aurora doctor report");
+    expect(textResult.stdout).toContain("categories:");
+    expect(textResult.stdout).toContain("BOUNDARY_CLIENT_IMPORTS_SERVER");
+    expect(textResult.stdout).toContain("DEPRECATED_ROUTE_API");
+    expect(textResult.stdout).toContain("SECURITY_DYNAMIC_CODE_EXECUTION");
+    expect(textResult.stdout).toContain("PERF_UNBOUNDED_QUERY");
+    expect(textResult.stdout).toContain("A11Y_IMAGE_MISSING_ALT");
+    expect(textResult.stdout).toContain("fix:");
+
+    expect(invalidOptionResult.exitCode).toBe(2);
+    expect(invalidOptionResult.stderr).toContain("aurora doctor: unknown option '--unknown'");
+  });
+
+  it("reports governance findings for missing/invalid OWNERS metadata", () => {
+    const result = runAuroraCli(["doctor", "--format", "json"], {
+      cwd: join(fixturesRoot, "governance"),
+    });
+
+    expect(result.exitCode).toBe(0);
+    const parsed = JSON.parse(result.stdout ?? "{}") as {
+      warnings?: number;
+      byCategory?: Record<string, number>;
+      issues?: Array<{ code?: string; file?: string }>;
+    };
+
+    expect(parsed.warnings).toBe(2);
+    expect(parsed.byCategory?.governance).toBe(2);
+    expect(parsed.issues?.some((issue) => issue.code === "GOVERNANCE_MISSING_MODULE_OWNER")).toBe(
+      true,
+    );
+    expect(parsed.issues?.some((issue) => issue.code === "GOVERNANCE_INVALID_OWNERS_EXPORT")).toBe(
+      true,
+    );
+  });
+});