@autoview/cli 0.1.0

package/src/orchestrate/utils/auditFrontendRuntime.ts

@@ -0,0 +1,454 @@
+import { type ChildProcess, spawn } from "child_process";
+import { createHash } from "crypto";
+import fs from "fs/promises";
+import { createServer } from "net";
+import os from "os";
+import path from "path";
+
+import {
+  ensureCachedNodeModules,
+  tryLinkNodeModules,
+} from "./cacheNodeModules";
+
+const PLAYWRIGHT_DEP = "playwright@^1.50.0";
+
+/**
+ * Per-page runtime defect captured by the Playwright audit. `console` covers
+ * `console.error` calls the page made during boot; `pageerror` covers uncaught
+ * exceptions; `navigation` covers Playwright's own `page.goto` failure
+ * (timeout, net::ERR, etc.) so the orchestrator sees the page as broken even
+ * when the runtime did not get a chance to fire a console message.
+ */
+export interface IRuntimeAuditDiagnostic {
+  /** Screen path the agent emitted (e.g. `/cart`, `/sales/[id]`). */
+  pagePath: string;
+  /** Category of failure. */
+  type: "console" | "pageerror" | "navigation";
+  /** Human-readable message — kept short so the retry prompt stays focused. */
+  message: string;
+}
+
+export interface IAuditFrontendRuntimeResult {
+  /** Flat list of every diagnostic captured across all visited pages. */
+  diagnostics: IRuntimeAuditDiagnostic[];
+  /**
+   * Convenience map keyed by screen path → diagnostics on that page. Pages that
+   * booted without any console / pageerror / navigation issue are absent from
+   * the map (use {@link visited} for the full visit list).
+   */
+  byPage: Map<string, IRuntimeAuditDiagnostic[]>;
+  /**
+   * Screen paths that the audit attempted (`length === pages.length` on
+   * success).
+   */
+  visited: string[];
+  /** Markdown body for `wiki/runtime-audit.md`. */
+  markdown: string;
+  /** Wall-clock duration of the whole audit (install + boot + visits + cleanup). */
+  elapsedMs: number;
+}
+
+const NEXT_DEV_BOOT_TIMEOUT_MS = 90_000;
+const PAGE_VISIT_TIMEOUT_MS = 20_000;
+const PAGE_SETTLE_MS = 2_500;
+
+/**
+ * Boot the assembled frontend under `next dev`, launch a headless Chromium via
+ * Playwright, visit every screen the product plan declared, and return the
+ * per-page console / pageerror / navigation diagnostics. Used by the
+ * orchestrator as Phase 6 (runtime audit) — the layer above `tsc --noEmit` that
+ * catches errors typecheck cannot see (`obj?.array.method(...)`
+ * undefined-access patterns, missing client-only guards, react render
+ * crashes).
+ *
+ * Operates in `NEXT_PUBLIC_API_SIMULATE=true` so the audit does not require a
+ * live backend — the SDK serves typia-random fixture data and pages exercise
+ * their real render paths. Live-backend variants can be added later by
+ * threading the host through.
+ *
+ * Throws on infrastructure failure (`npm install` crashed, port allocation
+ * failed, Chromium download blocked). Runtime errors on the pages themselves
+ * are returned as data; the whole point of this gate is to surface them.
+ */
+export async function auditFrontendRuntime(
+  files: Record<string, string>,
+  pages: string[],
+): Promise<IAuditFrontendRuntimeResult> {
+  const startedAt = Date.now();
+  const tempDir = await fs.mkdtemp(
+    path.join(os.tmpdir(), "autoview-runtime-audit-"),
+  );
+  let nextDev: ChildProcess | null = null;
+  try {
+    await writeFiles(tempDir, files);
+    const packageJson = files["package.json"];
+    const hash =
+      packageJson !== undefined
+        ? createHash("sha256").update(packageJson).digest("hex").slice(0, 16)
+        : "no-package-json";
+    const cachedNodeModules =
+      packageJson !== undefined
+        ? await ensureCachedNodeModules({
+            cacheNamespace: "runtime-audit",
+            hash,
+            packageJson,
+            extraDeps: [PLAYWRIGHT_DEP],
+          })
+        : null;
+    if (cachedNodeModules !== null) {
+      const linked = await tryLinkNodeModules(tempDir, cachedNodeModules);
+      if (!linked) {
+        await installDependencies(tempDir);
+        await installPlaywright(tempDir);
+      }
+    } else {
+      await installDependencies(tempDir);
+      await installPlaywright(tempDir);
+    }
+    await installChromium(tempDir);
+
+    const port = await getFreePort();
+    nextDev = await startNextDev(tempDir, port);
+    const baseUrl = `http://127.0.0.1:${port}`;
+
+    await writeFile(tempDir, "scripts/.audit-runner.cjs", buildRunnerScript());
+    const stdout = await spawnCommand(
+      "node",
+      [
+        path.join(tempDir, "scripts", ".audit-runner.cjs"),
+        JSON.stringify(pages),
+        baseUrl,
+        String(PAGE_VISIT_TIMEOUT_MS),
+        String(PAGE_SETTLE_MS),
+      ],
+      { cwd: tempDir },
+    );
+
+    const diagnostics = parseRunnerOutput(stdout);
+    const byPage = groupByPage(diagnostics);
+    return {
+      diagnostics,
+      byPage,
+      visited: [...pages],
+      markdown: renderMarkdownReport(diagnostics, byPage, pages),
+      elapsedMs: Date.now() - startedAt,
+    };
+  } finally {
+    if (nextDev !== null) await killNextDev(nextDev);
+    await fs.rm(tempDir, { recursive: true, force: true }).catch(() => {});
+  }
+}
+
+/* -------------------------------------------------------------------------- */
+/* fs                                                                          */
+/* -------------------------------------------------------------------------- */
+
+async function writeFiles(
+  root: string,
+  files: Record<string, string>,
+): Promise<void> {
+  for (const [relative, content] of Object.entries(files)) {
+    await writeFile(root, relative, content);
+  }
+}
+
+async function writeFile(
+  root: string,
+  relative: string,
+  content: string,
+): Promise<void> {
+  const full = path.join(root, relative);
+  await fs.mkdir(path.dirname(full), { recursive: true });
+  await fs.writeFile(full, content, "utf-8");
+}
+
+/* -------------------------------------------------------------------------- */
+/* install                                                                     */
+/* -------------------------------------------------------------------------- */
+
+async function installDependencies(root: string): Promise<void> {
+  await spawnCommand(
+    "npm",
+    ["install", "--silent", "--no-audit", "--no-fund"],
+    { cwd: root },
+  );
+}
+
+async function installPlaywright(root: string): Promise<void> {
+  await spawnCommand(
+    "npm",
+    [
+      "install",
+      "--silent",
+      "--no-audit",
+      "--no-fund",
+      "--no-save",
+      "playwright@^1.50.0",
+    ],
+    { cwd: root },
+  );
+}
+
+async function installChromium(root: string): Promise<void> {
+  await spawnCommand(
+    path.join(root, "node_modules", ".bin", "playwright"),
+    ["install", "chromium"],
+    { cwd: root },
+  );
+}
+
+/* -------------------------------------------------------------------------- */
+/* next dev                                                                    */
+/* -------------------------------------------------------------------------- */
+
+function getFreePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const server = createServer();
+    server.listen(0, "127.0.0.1", () => {
+      const addr = server.address();
+      if (addr === null || typeof addr === "string") {
+        server.close();
+        reject(new Error("Failed to allocate a free port"));
+        return;
+      }
+      const port = addr.port;
+      server.close(() => resolve(port));
+    });
+    server.on("error", reject);
+  });
+}
+
+function startNextDev(root: string, port: number): Promise<ChildProcess> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(
+      "node",
+      [path.join(root, "node_modules", "next", "dist", "bin", "next"), "dev"],
+      {
+        cwd: root,
+        env: {
+          ...process.env,
+          PORT: String(port),
+          NEXT_PUBLIC_API_SIMULATE: "true",
+          // Force literal Authorization header so the SDK does not crash
+          // when bootstrapAuth is a no-op in simulator mode.
+          NEXT_PUBLIC_API_TOKEN: "Bearer preview",
+        },
+        stdio: ["ignore", "pipe", "pipe"],
+      },
+    );
+
+    let buffer = "";
+    let settled = false;
+    const onData = (chunk: Buffer): void => {
+      buffer += chunk.toString("utf-8");
+      if (!settled && buffer.includes("Ready in")) {
+        settled = true;
+        child.stdout?.off("data", onData);
+        child.stderr?.off("data", onData);
+        resolve(child);
+      }
+    };
+    child.stdout?.on("data", onData);
+    child.stderr?.on("data", onData);
+
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      child.kill("SIGTERM");
+      reject(
+        new Error(
+          `next dev did not become ready within ${NEXT_DEV_BOOT_TIMEOUT_MS}ms:\n${buffer.slice(-1000)}`,
+        ),
+      );
+    }, NEXT_DEV_BOOT_TIMEOUT_MS);
+
+    child.on("exit", (code) => {
+      clearTimeout(timer);
+      if (settled) return;
+      settled = true;
+      reject(
+        new Error(
+          `next dev exited with code ${code} before becoming ready:\n${buffer.slice(-1000)}`,
+        ),
+      );
+    });
+  });
+}
+
+async function killNextDev(child: ChildProcess): Promise<void> {
+  if (child.exitCode !== null) return;
+  child.kill("SIGTERM");
+  await new Promise((r) => setTimeout(r, 1500));
+  if (child.exitCode === null) child.kill("SIGKILL");
+}
+
+/* -------------------------------------------------------------------------- */
+/* runner script (executed inside the temp dir, requires installed playwright) */
+/* -------------------------------------------------------------------------- */
+
+function buildRunnerScript(): string {
+  // CommonJS so the temp dir does not need to be ESM-aware. Reads pages +
+  // baseUrl + timeouts from argv, emits a JSON array of `{ pagePath, type,
+  // message }` to stdout. Failures during navigation become `navigation`
+  // diagnostics so the caller never silently misses a broken page.
+  return `"use strict";
+const { chromium } = require("playwright");
+
+(async () => {
+  const pages = JSON.parse(process.argv[2]);
+  const baseUrl = process.argv[3];
+  const visitTimeout = parseInt(process.argv[4], 10);
+  const settleMs = parseInt(process.argv[5], 10);
+  const browser = await chromium.launch();
+  const context = await browser.newContext({
+    viewport: { width: 1280, height: 800 },
+  });
+  const diagnostics = [];
+  for (const pagePath of pages) {
+    const resolved = pagePath.replace(/\\[[^\\]]+\\]/g, "demo");
+    const url = baseUrl + (resolved.startsWith("/") ? resolved : "/" + resolved);
+    const page = await context.newPage();
+    const pageErrors = [];
+    page.on("console", (msg) => {
+      if (msg.type() === "error") {
+        pageErrors.push({ pagePath, type: "console", message: msg.text() });
+      }
+    });
+    page.on("pageerror", (err) => {
+      pageErrors.push({ pagePath, type: "pageerror", message: err.message });
+    });
+    try {
+      // \`domcontentloaded\` instead of \`networkidle\` because typia random
+      // simulator data keeps the SDK firing background requests indefinitely
+      // on data-heavy pages — \`networkidle\` then times out at 20s on a
+      // page that already rendered cleanly. DOMContentLoaded plus the
+      // explicit settle window catches the same render errors without
+      // mistaking simulator chatter for a broken page.
+      await page.goto(url, {
+        waitUntil: "domcontentloaded",
+        timeout: visitTimeout,
+      });
+      await page.waitForTimeout(settleMs);
+    } catch (err) {
+      const message = err && err.message ? err.message : String(err);
+      pageErrors.push({ pagePath, type: "navigation", message });
+    }
+    for (const d of pageErrors) diagnostics.push(d);
+    await page.close().catch(() => {});
+  }
+  await browser.close().catch(() => {});
+  process.stdout.write(JSON.stringify(diagnostics));
+})().catch((err) => {
+  process.stderr.write(err && err.stack ? err.stack : String(err));
+  process.exit(1);
+});
+`;
+}
+
+function parseRunnerOutput(stdout: string): IRuntimeAuditDiagnostic[] {
+  const trimmed = stdout.trim();
+  if (trimmed.length === 0) return [];
+  try {
+    const parsed: unknown = JSON.parse(trimmed);
+    if (!Array.isArray(parsed)) return [];
+    return parsed.filter(
+      (entry): entry is IRuntimeAuditDiagnostic =>
+        entry !== null &&
+        typeof entry === "object" &&
+        typeof (entry as IRuntimeAuditDiagnostic).pagePath === "string" &&
+        typeof (entry as IRuntimeAuditDiagnostic).message === "string" &&
+        (entry as IRuntimeAuditDiagnostic).type !== undefined,
+    );
+  } catch {
+    return [];
+  }
+}
+
+function groupByPage(
+  diagnostics: IRuntimeAuditDiagnostic[],
+): Map<string, IRuntimeAuditDiagnostic[]> {
+  const map = new Map<string, IRuntimeAuditDiagnostic[]>();
+  for (const d of diagnostics) {
+    const bucket = map.get(d.pagePath);
+    if (bucket === undefined) map.set(d.pagePath, [d]);
+    else bucket.push(d);
+  }
+  return map;
+}
+
+function renderMarkdownReport(
+  diagnostics: IRuntimeAuditDiagnostic[],
+  byPage: Map<string, IRuntimeAuditDiagnostic[]>,
+  pages: string[],
+): string {
+  if (diagnostics.length === 0) {
+    return [
+      "# Runtime audit",
+      "",
+      `Visited **${pages.length}** page(s) under \`next dev\` (simulator mode).`,
+      "No console errors, page errors, or navigation failures detected.",
+      "",
+    ].join("\n");
+  }
+  const head = [
+    "# Runtime audit",
+    "",
+    `Visited **${pages.length}** page(s) under \`next dev\` (simulator mode).`,
+    `Detected **${diagnostics.length}** diagnostic(s) across **${byPage.size}** page(s).`,
+    "",
+  ];
+  const sections = [...byPage.entries()]
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([pagePath, items]) => {
+      const lines = items.map((d) => `- \`${d.type}\` — ${escape(d.message)}`);
+      return [`## \`${pagePath}\` (${items.length})`, "", ...lines, ""].join(
+        "\n",
+      );
+    });
+  return [...head, ...sections].join("\n");
+}
+
+function escape(message: string): string {
+  return message.replace(/`/g, "\\`").replace(/\n+/g, " ").slice(0, 500);
+}
+
+/* -------------------------------------------------------------------------- */
+/* spawn                                                                       */
+/* -------------------------------------------------------------------------- */
+
+function spawnCommand(
+  cmd: string,
+  args: string[],
+  options: { cwd: string },
+): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, { cwd: options.cwd, stdio: "pipe" });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk.toString("utf-8");
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk.toString("utf-8");
+    });
+    child.on("error", (err) => {
+      reject(
+        new Error(
+          `Failed to spawn \`${cmd} ${args.join(" ")}\`: ${err.message}`,
+        ),
+      );
+    });
+    child.on("close", (code) => {
+      if (code === 0) {
+        resolve(stdout);
+      } else {
+        reject(
+          new Error(
+            `\`${cmd} ${args.slice(0, 3).join(" ")}...\` exited with code ${code}` +
+              (stderr.length > 0 ? `:\n${stderr.slice(-1500)}` : ""),
+          ),
+        );
+      }
+    });
+  });
+}

package/src/orchestrate/utils/buildDeterministicPlan.test.ts

@@ -0,0 +1,170 @@
+import { OpenApiConverter } from "@typia/utils";
+import { describe, expect, it } from "vitest";
+
+import { toEndpoints } from "../../utils/toEndpoints";
+import { buildDeterministicPlan } from "./buildDeterministicPlan";
+
+/** Every operation must be referenced by a screen or appear as an omission. */
+function unaccounted(document: ReturnType<typeof doc>): string[] {
+  const plan = buildDeterministicPlan(document, "user");
+  const referenced = new Set<string>();
+  for (const s of plan.screens) for (const a of s.endpoints) referenced.add(a);
+  const omitted = new Set(plan.intentionalOmissions.map((o) => o.target));
+  return toEndpoints(document)
+    .filter((e) => {
+      const acc = e.accessor.join(".");
+      const target = `${e.method.toUpperCase()} ${e.path}`;
+      return !referenced.has(acc) && !omitted.has(target);
+    })
+    .map((e) => `${e.method.toUpperCase()} ${e.path}`);
+}
+
+function doc(paths: Record<string, unknown>, schemas: Record<string, unknown> = {}) {
+  return OpenApiConverter.upgradeDocument({
+    openapi: "3.0.0",
+    info: { title: "t", version: "1.0.0" },
+    paths,
+    components: { schemas },
+  } as never);
+}
+
+const ok = { 200: { description: "ok" } };
+const fixture = doc(
+  {
+    "/pets": {
+      get: { operationId: "list", responses: { 200: { description: "ok", content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/Pet" } } } } } } },
+      post: { operationId: "create", requestBody: { content: { "application/json": { schema: { $ref: "#/components/schemas/Pet" } } } }, responses: ok },
+    },
+    "/pets/{petId}": {
+      get: { operationId: "get", parameters: [{ name: "petId", in: "path", required: true, schema: { type: "string" } }], responses: { 200: { description: "ok", content: { "application/json": { schema: { $ref: "#/components/schemas/Pet" } } } } } },
+      put: { operationId: "update", parameters: [{ name: "petId", in: "path", required: true, schema: { type: "string" } }], requestBody: { content: { "application/json": { schema: { $ref: "#/components/schemas/Pet" } } } }, responses: ok },
+      delete: { operationId: "erase", parameters: [{ name: "petId", in: "path", required: true, schema: { type: "string" } }], responses: ok },
+    },
+  },
+  { Pet: { type: "object", properties: { id: { type: "string" } }, required: ["id"] } },
+);
+
+describe("buildDeterministicPlan", () => {
+  it("produces a root landing hub + the resource's CRUD screens", () => {
+    const plan = buildDeterministicPlan(fixture, "user");
+    expect(plan.screens[0]).toMatchObject({ path: "/", uiPattern: "landing" });
+    const paths = plan.screens.map((s) => s.path);
+    // resource screens are sorted alphabetically by path (after the home hub)
+    expect(paths).toEqual(["/", "/pets", "/pets/[petsId]", "/pets/[petsId]/edit", "/pets/new"]);
+    expect(plan.navigation[0]!.primary).toContain("/");
+    expect(plan.navigation[0]!.primary).toContain("/pets");
+  });
+
+  it("wires each screen to real accessors and hosts write ops on detail", () => {
+    const plan = buildDeterministicPlan(fixture, "user");
+    const detail = plan.screens.find((s) => s.path === "/pets/[petsId]")!;
+    // detail composes its GET plus the update/delete it surfaces as actions
+    expect(detail.endpoints.length).toBeGreaterThanOrEqual(2);
+    expect(plan.screens.every((s) => s.actor === "user")).toBe(true);
+  });
+
+  it("is reproducible — same swagger yields an identical plan", () => {
+    expect(buildDeterministicPlan(fixture, "user")).toEqual(
+      buildDeterministicPlan(fixture, "user"),
+    );
+  });
+
+  it("accounts for every operation — no silent drops (referenced or omitted)", () => {
+    // a resource with TWO creates + TWO deletes — the kind of duplicate-role
+    // shape that used to drop the extras on the floor.
+    const multi = doc(
+      {
+        "/orders": {
+          post: { operationId: "create", requestBody: { content: { "application/json": { schema: { $ref: "#/components/schemas/O" } } } }, responses: ok },
+          patch: { operationId: "index", responses: { 200: { description: "ok", content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/O" } } } } } } },
+        },
+        "/orders/direct": {
+          post: { operationId: "direct", requestBody: { content: { "application/json": { schema: { $ref: "#/components/schemas/O" } } } }, responses: ok },
+        },
+        "/orders/{id}": {
+          delete: { operationId: "erase", parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }], responses: ok },
+        },
+        "/orders/{id}/cancel": {
+          delete: { operationId: "cancel", parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }], responses: ok },
+        },
+      },
+      { O: { type: "object", properties: { id: { type: "string" } }, required: ["id"] } },
+    );
+    expect(unaccounted(multi)).toEqual([]);
+    expect(unaccounted(fixture)).toEqual([]);
+  });
+
+  it("classifies non-browsable list responses structurally (no domain keywords)", () => {
+    const noisy = doc(
+      {
+        // void GET → omitted
+        "/health": { get: { operationId: "health", responses: ok } },
+        // single-object GET → singleton read → detail (not a fake table)
+        "/system": {
+          get: {
+            operationId: "system",
+            responses: {
+              200: {
+                description: "ok",
+                content: {
+                  "application/json": { schema: { $ref: "#/components/schemas/Sys" } },
+                },
+              },
+            },
+          },
+        },
+        // single-object mutating verb → action → omitted
+        "/refresh": {
+          patch: {
+            operationId: "refresh",
+            requestBody: {
+              content: { "application/json": { schema: { $ref: "#/components/schemas/Sys" } } },
+            },
+            responses: {
+              200: {
+                description: "ok",
+                content: {
+                  "application/json": { schema: { $ref: "#/components/schemas/Sys" } },
+                },
+              },
+            },
+          },
+        },
+      },
+      { Sys: { type: "object", properties: { uptime: { type: "number" } }, required: ["uptime"] } },
+    );
+    const plan = buildDeterministicPlan(noisy, "user");
+    const byPath = Object.fromEntries(plan.screens.map((s) => [s.path, s]));
+    // no fake tables survived
+    expect(plan.screens.some((s) => s.uiPattern === "table")).toBe(false);
+    // singleton read became a top-level detail page, still rendering its data
+    expect(byPath["/system"]?.uiPattern).toBe("detail");
+    expect(plan.navigation[0]!.primary).toContain("/system");
+    // void + action verb were omitted, not turned into screens
+    expect(byPath["/health"]).toBeUndefined();
+    expect(byPath["/refresh"]).toBeUndefined();
+    const omitted = plan.intentionalOmissions.map((o) => o.target);
+    expect(omitted).toContain("GET /health");
+    expect(omitted).toContain("PATCH /refresh");
+  });
+
+  it("omits a write-only resource (no list/detail/search to browse) as nav noise", () => {
+    const wo = doc(
+      {
+        // a real, browsable resource
+        "/users": { get: { operationId: "list", responses: { 200: { description: "ok", content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/U" } } } } } } } },
+        // oauth2 token — POST only, no way to browse it: pure nav noise
+        "/token": { post: { operationId: "token", requestBody: { content: { "application/json": { schema: { $ref: "#/components/schemas/U" } } } }, responses: ok } },
+      },
+      { U: { type: "object", properties: { id: { type: "string" } }, required: ["id"] } },
+    );
+    const plan = buildDeterministicPlan(wo, "user");
+    // the browsable resource stays; the write-only one has no screen
+    expect(plan.navigation[0]!.primary).toContain("/users");
+    expect(plan.screens.some((s) => s.path.includes("token"))).toBe(false);
+    // ...but it is recorded as an omission, not silently dropped
+    expect(plan.intentionalOmissions.some((o) => o.target.includes("/token"))).toBe(true);
+    // and coverage stays total
+    expect(unaccounted(wo)).toEqual([]);
+  });
+});