@autoview/cli 0.1.0

package/src/orchestrate/orchestrateAutoView.ts

@@ -0,0 +1,590 @@
+import { OpenApi } from "@typia/interface";
+import {
+  AutoBeAutoViewCompleteEvent,
+  AutoBeAutoViewStartEvent,
+  IAutoBeRunAutoViewOptions,
+} from "../typings";
+import { v7 } from "uuid";
+
+import { IAutoViewAgentContext } from "../context/IAutoViewAgentContext";
+import { orchestrateAutoViewProductPlan } from "./orchestrateAutoViewProductPlan";
+import {
+  fileToScreenPath,
+  rerenderScreenForRuntime,
+  rerenderScreenForTypecheck,
+  screenPathToFile,
+} from "./orchestrateAutoViewRender";
+import { orchestrateAutoViewRenderDeterministic } from "./orchestrateAutoViewRenderDeterministic";
+import { orchestrateAutoViewReview } from "./orchestrateAutoViewReview";
+import { orchestrateAutoViewScaffold } from "./orchestrateAutoViewScaffold";
+import { orchestrateAutoViewSdkStudy } from "./orchestrateAutoViewSdkStudy";
+import {
+  type IAuditFrontendRuntimeResult,
+  auditFrontendRuntime,
+} from "./utils/auditFrontendRuntime";
+import { executeCachedBatch } from "./utils/executeCachedBatch";
+import { loadShoppingFixture } from "./utils/loadShoppingFixture";
+import { normalizeProductPlanPaths } from "./utils/normalizeProductPlanPaths";
+import {
+  FrontendTypecheckSession,
+  type IValidateFrontendTypecheckResult,
+} from "./utils/validateFrontendTypecheck";
+import { deriveWorkflows } from "../verify/workflows";
+import { runWorkflows } from "../verify/runWorkflows";
+import { sliceDocument } from "../utils/sliceDocument";
+
+/**
+ * Top-level AutoView orchestrator.
+ *
+ * Walks through the five phases — SDK Study, Product Plan, Scaffold, Render,
+ * Review — emitting one event per phase plus per-page progress during Render.
+ * The final `autoViewComplete` event carries the assembled frontend project as
+ * a flat `path → content` map ready for Sandbox deploy.
+ *
+ * All five phases (SDK Study → Product Plan → Scaffold → Render → UI Review)
+ * are implemented. Visual screenshot capture is intentionally out of scope for
+ * the agent itself — the operator runs Playwright against the Sandbox deploy —
+ * but the Review phase still produces the `wiki/sdk-feedback.md` audit so the
+ * SDK-quality signal lands in the archive.
+ */
+export async function orchestrateAutoView(
+  ctx: IAutoViewAgentContext,
+  options: IAutoBeRunAutoViewOptions = {},
+): Promise<void> {
+  const source = options.source ?? "interface";
+  const designTheme = (options.designTheme ?? "").trim();
+  const {
+    document: fullDocument,
+    step,
+    reason,
+    backend,
+  } = resolveSource(ctx, source, {
+    backend: options.backend ?? null,
+  });
+  // Apply `--include` / `--exclude` at the DOCUMENT level, not just the screen
+  // list: slicing the paths AND pruning component schemas to their transitive
+  // closure is what lets a large swagger (Box, Stripe) actually run — otherwise
+  // SDK Study compiles all ~180 schemas and overflows the model's context.
+  const document = sliceDocument(fullDocument, {
+    include: options.include,
+    exclude: options.exclude,
+  });
+  const startedAt = Date.now();
+
+  ctx.dispatch({
+    type: "autoViewStart",
+    id: v7(),
+    created_at: new Date().toISOString(),
+    source,
+    step,
+    designTheme,
+    reason,
+  } satisfies AutoBeAutoViewStartEvent);
+
+  // Phase 1 — SDK Study.
+  const { map: sdkMap, markdown: sdkMapMarkdown } =
+    await orchestrateAutoViewSdkStudy(ctx, { document, step });
+
+  // Phase 2 — Product Plan.
+  const { plan: rawProductPlan, markdown: productPlanMarkdown } =
+    await orchestrateAutoViewProductPlan(ctx, {
+      document,
+      sdkMap,
+      designTheme,
+      step,
+      filter: { include: options.include, exclude: options.exclude },
+    });
+  // Next.js refuses to start when sibling routes under the same parent
+  // disagree on the dynamic-segment name (e.g. `/sales/[id]` vs.
+  // `/sales/[saleId]`). The planner cannot always avoid that — run the
+  // plan through a deterministic normalizer before the scaffold step
+  // bakes the paths into the file tree.
+  const productPlan = normalizeProductPlanPaths(rawProductPlan);
+
+  // Phase 3 — Scaffold (deterministic).
+  const scaffolded = await orchestrateAutoViewScaffold(ctx, {
+    document,
+    sdkMap,
+    sdkMapMarkdown,
+    productPlan,
+    productPlanMarkdown,
+    step,
+    backend,
+  });
+
+  // Phase 4 — Render (deterministic). Emits one thin `page.tsx` per screen
+  // that wires the typed SDK call to a universal `Resource*` component, with
+  // column / field metadata baked from the swagger schema. No LLM, no
+  // parser-retry roulette: every screen gets a page and every property of its
+  // row / response / request type becomes a column / row / input. The rendered
+  // pages overwrite the scaffold placeholders in place.
+  const render = await orchestrateAutoViewRenderDeterministic(ctx, {
+    document,
+    productPlan,
+    step,
+  });
+  for (const [key, value] of Object.entries(render.files)) {
+    scaffolded[key] = value;
+  }
+
+  // Phase 4.5 — deterministic `tsc --noEmit` against the assembled tree,
+  // plus a typecheck-driven retry pass for screens whose pages failed
+  // the gate. The per-screen parser check inside Render only catches
+  // grammar failures; type errors against the SDK (the model inventing
+  // properties on response types, wrong-casing fields, sending a second
+  // argument to a parameterless endpoint, etc.) escape every render
+  // attempt unless we actually compile the project the way the user
+  // will. Materializing into a temp dir + `npm install` + `tsc` is
+  // expensive (~30s on first run) but the typecheck session reuses the
+  // installed node_modules across retry rounds, so subsequent
+  // typecheck runs cost only the actual compile time.
+  const { typecheck, recovered } = await runTypecheckPhase(ctx, {
+    scaffolded,
+    document,
+    sdkMap,
+    productPlan,
+    designTheme,
+  });
+  scaffolded["wiki/typecheck.md"] = typecheck.markdown;
+
+  // Phase 6 — runtime audit (opt-in). After typecheck closes the static
+  // gate, boot `next dev` against the assembled tree, walk every screen
+  // with a headless Chromium, capture console / pageerror / navigation
+  // diagnostics, and re-render broken pages with the live errors in the
+  // prompt. The retry pass closes the class of bugs `tsc --noEmit`
+  // cannot see — `obj?.array.method(...)` undefined-access patterns,
+  // react render crashes against simulator data, hydration mismatches.
+  // Skipped when `options.runtimeAudit !== true` because the gate
+  // installs Playwright + Chromium (~150MB) and boots `next dev` twice
+  // per run, adding ~10–20 minutes to the agent's wall clock.
+  let runtimeAudit: IAuditFrontendRuntimeResult | null = null;
+  let runtimeRecovered = 0;
+  if (options.runtimeAudit === true) {
+    const result = await runRuntimeAuditPhase(ctx, {
+      scaffolded,
+      document,
+      sdkMap,
+      productPlan,
+      designTheme,
+    });
+    runtimeAudit = result.audit;
+    runtimeRecovered = result.recovered;
+    scaffolded["wiki/runtime-audit.md"] = runtimeAudit.markdown;
+  }
+
+  // Phase 7 — workflow verification (opt-in). Derive the user workflows from
+  // the plan and drive them in a real headless browser, asserting each step's
+  // positive outcome (data rendered, navigation moved). Writes
+  // `wiki/verification.md` — the evidence that the generated app actually works
+  // for a user, not just that it compiles. Skipped unless `options.verify`
+  // because it installs Chromium and boots `next dev`.
+  if (options.verify === true) {
+    try {
+      const workflows = deriveWorkflows(productPlan);
+      const verification = await runWorkflows(scaffolded, workflows);
+      scaffolded["wiki/verification.md"] = verification.markdown;
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      scaffolded["wiki/verification.md"] = [
+        "# Workflow verification",
+        "",
+        "Verification could not run against the assembled project:",
+        "",
+        "```",
+        message,
+        "```",
+      ].join("\n");
+    }
+  }
+
+  // Phase 5 — UI Review. Code-and-spec audit; produces the
+  // operator-facing `wiki/sdk-feedback.md` document. Visual
+  // verification is left to the Sandbox deploy step.
+  const review = await orchestrateAutoViewReview(ctx, {
+    document,
+    sdkMap,
+    productPlan,
+    render,
+    typecheck,
+    recovered: recovered + runtimeRecovered,
+    step,
+  });
+  scaffolded["wiki/sdk-feedback.md"] = review.markdown;
+
+  ctx.dispatch({
+    type: "autoViewComplete",
+    id: v7(),
+    created_at: new Date().toISOString(),
+    step,
+    source,
+    elapsed: Date.now() - startedAt,
+    pages: productPlan.screens.length,
+    files: scaffolded,
+  } satisfies AutoBeAutoViewCompleteEvent);
+}
+
+interface IResolvedSource {
+  document: OpenApi.IDocument;
+  step: number;
+  reason: string;
+  /**
+   * Backend hint surfaced from the source. When the swagger ships a real
+   * `servers[].url`, scaffold the generated frontend with that host + live mode
+   * so the demo renders real product data instead of typia-random gibberish.
+   * When omitted, scaffold falls back to localhost + simulate.
+   */
+  backend: { host: string | null };
+}
+
+function resolveSource(
+  ctx: IAutoViewAgentContext,
+  source: "interface" | "shopping",
+  overrides: { backend: { host: string } | null },
+): IResolvedSource {
+  if (source === "shopping") {
+    // Stable reference SDK derived from `@samchon/shopping-api`. Lets
+    // the AutoView pipeline run end-to-end without waiting for the
+    // live AutoBE interface phase to complete, which is the whole
+    // reason the bundled fixture exists.
+    //
+    // Default the backend at `http://127.0.0.1:37001` instead of the
+    // swagger's `servers[0].url` (the public host is not reachable from
+    // most networks). The frontend pack ships
+    // `scripts/start-shopping-backend.sh`, which clones
+    // `samchon/shopping` and boots its NestJS server on that port — so
+    // the demo runs end-to-end against the real backend with seeded
+    // product data instead of typia-random gibberish.
+    const fixture = loadShoppingFixture();
+    return {
+      document: fixture.document,
+      step: 0,
+      reason:
+        "User triggered AutoView against the bundled @samchon/shopping-api reference.",
+      backend: overrides.backend ?? { host: "http://127.0.0.1:37001" },
+    };
+  }
+  const interfaceHistory = ctx.state().interface;
+  if (interfaceHistory === null) {
+    throw new Error(
+      "AutoView requires the interface phase to be complete first. " +
+        'Run with source: "shopping" to use the bundled reference instead.',
+    );
+  }
+  return {
+    document: interfaceHistory.document,
+    step: interfaceHistory.step,
+    reason: "User triggered AutoView against the AutoBE interface output.",
+    // Honor the caller's backend hint (CLI extracts it from swagger
+    // `servers[]`, or accepts a `--backend <url>` flag). When none was
+    // given the scaffold falls back to simulate-only mode — only useful
+    // for swaggers that genuinely have no backend (AutoBE's interface
+    // phase before the operator wires their own server).
+    backend: overrides.backend ?? { host: null },
+  };
+}
+
+/**
+ * Maximum number of full typecheck+rerender rounds. Initial render counts as
+ * round 0, so this many additional rounds may follow it.
+ */
+const MAX_TYPECHECK_RETRY_ROUNDS = 2;
+
+/**
+ * Phase 4.5 in full: open a typecheck session against the assembled file map,
+ * iterate "typecheck → re-render broken screens → typecheck" up to
+ * {@link MAX_TYPECHECK_RETRY_ROUNDS} rounds, and return the final result. The
+ * scaffolded map is mutated in place — each successful re-render overwrites the
+ * broken file so the assembled output reflects the final state seen by the
+ * typecheck gate.
+ *
+ * Returns the last typecheck result + `recovered` count (screens that the loop
+ * fixed) so the Review event can report both honestly. On infra failure (npm
+ * install crash, etc.) returns a marker typecheck result and a recovered count
+ * of zero — the operator still gets the file map.
+ */
+async function runTypecheckPhase(
+  ctx: IAutoViewAgentContext,
+  args: {
+    scaffolded: Record<string, string>;
+    document: OpenApi.IDocument;
+    sdkMap: ReturnType<typeof loadShoppingFixture> extends { document: infer _ }
+      ? Awaited<ReturnType<typeof orchestrateAutoViewSdkStudy>>["map"]
+      : never;
+    productPlan: Awaited<
+      ReturnType<typeof orchestrateAutoViewProductPlan>
+    >["plan"];
+    designTheme: string;
+  },
+): Promise<{
+  typecheck: IValidateFrontendTypecheckResult;
+  recovered: number;
+}> {
+  let session: FrontendTypecheckSession;
+  try {
+    session = await FrontendTypecheckSession.open(args.scaffolded);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      typecheck: {
+        diagnostics: new Map(),
+        totalErrors: 0,
+        markdown: [
+          "# Typecheck report",
+          "",
+          "`tsc --noEmit` could not be run against the assembled project:",
+          "",
+          "```",
+          message,
+          "```",
+          "",
+          "Re-run the project locally with `npm install && npm run typecheck` to validate.",
+        ].join("\n"),
+        elapsedMs: 0,
+      },
+      recovered: 0,
+    };
+  }
+
+  try {
+    let typecheck = await session.typecheck();
+    let recovered = 0;
+    const allScreenPaths = args.productPlan.screens.map((s) => s.path);
+    const semaphoreCap =
+      typeof ctx.vendor.semaphore === "number"
+        ? ctx.vendor.semaphore
+        : ctx.vendor.semaphore !== undefined
+          ? ctx.vendor.semaphore.max()
+          : 8;
+
+    for (
+      let round = 0;
+      round < MAX_TYPECHECK_RETRY_ROUNDS && typecheck.totalErrors > 0;
+      round++
+    ) {
+      // Build the set of (screen, previousTsx, errors) tuples for every
+      // broken file that maps back to a known screen. Non-screen files
+      // (scaffold components, generated SDK, wiki) are not fixable by
+      // re-rendering a single screen — they are left to fail loudly.
+      const tasks: {
+        screen: (typeof args.productPlan.screens)[number];
+        filePath: string;
+        previousTsx: string;
+        errors: {
+          line: number;
+          column: number;
+          code: string;
+          message: string;
+        }[];
+      }[] = [];
+      for (const [filePath, diagnostics] of typecheck.diagnostics) {
+        const screenPath = fileToScreenPath(filePath);
+        if (screenPath === null) continue;
+        const screen = args.productPlan.screens.find(
+          (s) => s.path === screenPath,
+        );
+        if (screen === undefined) continue;
+        const previousTsx = args.scaffolded[filePath];
+        if (previousTsx === undefined) continue;
+        tasks.push({
+          screen,
+          filePath,
+          previousTsx,
+          errors: diagnostics.map((d) => ({
+            line: d.line,
+            column: d.column,
+            code: d.code,
+            message: d.message,
+          })),
+        });
+      }
+      if (tasks.length === 0) break;
+
+      const fixed = new Set<string>();
+      await executeCachedBatch(
+        semaphoreCap,
+        tasks.map((task) => async (promptCacheKey) => {
+          const result = await rerenderScreenForTypecheck(ctx, {
+            screen: task.screen,
+            document: args.document,
+            sdkMap: args.sdkMap,
+            designTheme: args.designTheme,
+            promptCacheKey,
+            allScreenPaths,
+            previousTsx: task.previousTsx,
+            typecheckErrors: task.errors,
+          });
+          if (result === null || !result.ok) return;
+          args.scaffolded[task.filePath] = result.tsx;
+          await session.writeFile(task.filePath, result.tsx);
+          fixed.add(task.filePath);
+        }),
+      );
+
+      if (fixed.size === 0) break;
+      const next = await session.typecheck();
+      const errorsBefore = new Set(typecheck.diagnostics.keys());
+      const errorsAfter = new Set(next.diagnostics.keys());
+      for (const filePath of fixed) {
+        if (errorsBefore.has(filePath) && !errorsAfter.has(filePath)) {
+          recovered++;
+        }
+      }
+      typecheck = next;
+    }
+
+    return { typecheck, recovered };
+  } finally {
+    await session.dispose();
+  }
+}
+
+/**
+ * Phase 6 in full: open a runtime audit session (npm install + playwright +
+ * chromium + `next dev`), capture per-page console / pageerror / navigation
+ * diagnostics, re-render the broken pages with the diagnostics in the prompt,
+ * and audit one more time. The orchestrator mutates `scaffolded` in place so
+ * the next phase sees the corrected output.
+ *
+ * Returns the final audit + `recovered` count (pages that the loop fixed) so
+ * the Review event can report runtime quality alongside the typecheck quality.
+ * On infra failure (Playwright install crashed, next dev never became ready,
+ * Chromium download blocked) returns a marker audit body and a recovered count
+ * of zero — the operator still gets the file map.
+ */
+async function runRuntimeAuditPhase(
+  ctx: IAutoViewAgentContext,
+  args: {
+    scaffolded: Record<string, string>;
+    document: OpenApi.IDocument;
+    sdkMap: Awaited<ReturnType<typeof orchestrateAutoViewSdkStudy>>["map"];
+    productPlan: Awaited<
+      ReturnType<typeof orchestrateAutoViewProductPlan>
+    >["plan"];
+    designTheme: string;
+  },
+): Promise<{ audit: IAuditFrontendRuntimeResult; recovered: number }> {
+  const pages = args.productPlan.screens.map((s) => s.path);
+  let firstAudit: IAuditFrontendRuntimeResult;
+  try {
+    firstAudit = await auditFrontendRuntime(args.scaffolded, pages);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      audit: {
+        diagnostics: [],
+        byPage: new Map(),
+        visited: pages,
+        markdown: [
+          "# Runtime audit",
+          "",
+          "Playwright runtime audit could not be run against the assembled project:",
+          "",
+          "```",
+          message,
+          "```",
+          "",
+          "Re-run the project locally with `npm install && npm run dev` and visit pages by hand to validate.",
+        ].join("\n"),
+        elapsedMs: 0,
+      },
+      recovered: 0,
+    };
+  }
+  if (firstAudit.byPage.size === 0) {
+    return { audit: firstAudit, recovered: 0 };
+  }
+
+  // Identify broken pages whose screens we own — only `app/.../page.tsx`
+  // files map back to a planned screen; component / wiki / SDK files are
+  // out of this loop's scope.
+  type IRuntimeTask = {
+    screen: (typeof args.productPlan.screens)[number];
+    filePath: string;
+    previousTsx: string;
+    runtimeErrors: {
+      type: "console" | "pageerror" | "navigation";
+      message: string;
+    }[];
+  };
+  const tasks: IRuntimeTask[] = [];
+  for (const [pagePath, diagnostics] of firstAudit.byPage) {
+    const screen = args.productPlan.screens.find((s) => s.path === pagePath);
+    if (screen === undefined) continue;
+    const filePath = screenPathToFile(screen.path);
+    const previousTsx = args.scaffolded[filePath];
+    if (previousTsx === undefined) continue;
+    tasks.push({
+      screen,
+      filePath,
+      previousTsx,
+      runtimeErrors: diagnostics.map((d) => ({
+        type: d.type,
+        message: d.message,
+      })),
+    });
+  }
+  if (tasks.length === 0) return { audit: firstAudit, recovered: 0 };
+
+  const allScreenPaths = args.productPlan.screens.map((s) => s.path);
+  const semaphoreCap =
+    typeof ctx.vendor.semaphore === "number"
+      ? ctx.vendor.semaphore
+      : ctx.vendor.semaphore !== undefined
+        ? ctx.vendor.semaphore.max()
+        : 8;
+
+  const fixed = new Set<string>();
+  await executeCachedBatch(
+    semaphoreCap,
+    tasks.map((task) => async (promptCacheKey) => {
+      const result = await rerenderScreenForRuntime(ctx, {
+        screen: task.screen,
+        document: args.document,
+        sdkMap: args.sdkMap,
+        designTheme: args.designTheme,
+        promptCacheKey,
+        allScreenPaths,
+        previousTsx: task.previousTsx,
+        runtimeErrors: task.runtimeErrors,
+      });
+      if (result === null || !result.ok) return;
+      args.scaffolded[task.filePath] = result.tsx;
+      fixed.add(task.screen.path);
+    }),
+  );
+  if (fixed.size === 0) return { audit: firstAudit, recovered: 0 };
+
+  // Re-audit to measure recovery. Only one retry round to keep the gate
+  // bounded; further rounds rarely help once a page survived the prompt
+  // rewrite with the diagnostics in hand.
+  let secondAudit: IAuditFrontendRuntimeResult;
+  try {
+    secondAudit = await auditFrontendRuntime(args.scaffolded, pages);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    secondAudit = {
+      diagnostics: [],
+      byPage: new Map(),
+      visited: pages,
+      markdown: [
+        "# Runtime audit (post-retry)",
+        "",
+        "Second-round Playwright audit could not be run:",
+        "",
+        "```",
+        message,
+        "```",
+        "",
+        "First-round results above are the last known runtime state.",
+      ].join("\n"),
+      elapsedMs: 0,
+    };
+  }
+  let recovered = 0;
+  for (const pagePath of fixed) {
+    if (firstAudit.byPage.has(pagePath) && !secondAudit.byPage.has(pagePath)) {
+      recovered++;
+    }
+  }
+  return { audit: secondAudit, recovered };
+}