@autoview/cli 0.1.0

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

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest";
+
+import { hashFrontendDependencies } from "./validateFrontendTypecheck";
+
+describe("hashFrontendDependencies", () => {
+  it("returns a stable 16-char hex for the same package.json body", () => {
+    const a = hashFrontendDependencies({
+      "package.json": '{"name":"x","dependencies":{"next":"14"}}',
+    });
+    const b = hashFrontendDependencies({
+      "package.json": '{"name":"x","dependencies":{"next":"14"}}',
+    });
+    expect(a).toBe(b);
+    expect(a).toMatch(/^[0-9a-f]{16}$/);
+  });
+
+  it("changes when package.json changes", () => {
+    expect(
+      hashFrontendDependencies({
+        "package.json": '{"name":"x","dependencies":{"next":"14"}}',
+      }),
+    ).not.toBe(
+      hashFrontendDependencies({
+        "package.json": '{"name":"x","dependencies":{"next":"15"}}',
+      }),
+    );
+  });
+
+  it("falls back to a fixed sentinel when package.json is missing", () => {
+    expect(hashFrontendDependencies({})).toBe("no-package-json");
+  });
+});

package/src/orchestrate/utils/validateFrontendTypecheck.ts

@@ -0,0 +1,335 @@
+import { spawn } from "child_process";
+import { createHash } from "crypto";
+import fs from "fs/promises";
+import os from "os";
+import path from "path";
+
+import {
+  ensureCachedNodeModules,
+  tryLinkNodeModules,
+} from "./cacheNodeModules";
+
+/**
+ * Per-file diagnostic emitted by {@link validateFrontendTypecheck}. Mirrors the
+ * one-line shape `tsc --noEmit` prints to stderr (`<file>(<line>,<col>): error
+ * TS<code>: <message>`) so the orchestrator can hand it back to the Render
+ * phase verbatim when scheduling a retry.
+ */
+export interface ITypecheckDiagnostic {
+  /** Path of the broken file, relative to the project root. */
+  file: string;
+  /** 1-indexed line where tsc anchored the error. */
+  line: number;
+  /** 1-indexed column where tsc anchored the error. */
+  column: number;
+  /** TS<n> code (e.g. `TS2339`). */
+  code: string;
+  /** Human-readable diagnostic body, one line. */
+  message: string;
+}
+
+/** Result of running the typecheck against a virtual frontend project. */
+export interface IValidateFrontendTypecheckResult {
+  /** Map of broken file → diagnostics on that file. */
+  diagnostics: Map<string, ITypecheckDiagnostic[]>;
+  /** Total number of diagnostics across all files. */
+  totalErrors: number;
+  /**
+   * Markdown report suitable for dropping into `wiki/typecheck.md`. Always
+   * present even when there are zero errors — the empty body still tells the
+   * operator the gate ran.
+   */
+  markdown: string;
+  /**
+   * Wall-clock duration of the whole check (npm install + tsc + parse) in
+   * milliseconds. Useful for the orchestrator to surface progress info without
+   * timing the call itself.
+   */
+  elapsedMs: number;
+}
+
+/**
+ * Run `npm install` + `tsc --noEmit` against the assembled frontend file map
+ * and return the per-file diagnostics. The whole project is materialized into a
+ * temp directory, dependencies are installed via `npm install --silent`, and
+ * the project's own `tsconfig.json` drives the compile — same code path the
+ * external user gets when they run `npm run typecheck` themselves.
+ *
+ * The temp directory is removed on success. On failure (npm install crash,
+ * spawn ENOENT, etc.) it is left behind so the operator can inspect what the
+ * agent shipped; the path is included in the thrown error message.
+ *
+ * Returns a structured result rather than throwing on typecheck failures — type
+ * errors are the entire point of running this gate. Only infrastructural
+ * problems (npm missing, install failure) throw.
+ */
+export async function validateFrontendTypecheck(
+  files: Record<string, string>,
+): Promise<IValidateFrontendTypecheckResult> {
+  const session = await FrontendTypecheckSession.open(files);
+  try {
+    return await session.typecheck();
+  } finally {
+    await session.dispose();
+  }
+}
+
+/**
+ * Reusable typecheck session. Materializes the project into a temp directory
+ * and installs dependencies once, then lets the caller mutate individual files
+ * and re-run `tsc --noEmit` repeatedly without paying the npm install cost
+ * again. Used by the typecheck-driven render retry loop, where the orchestrator
+ * needs to type-check the project, hand the diagnostics to the LLM, write the
+ * model's corrected TSX back, and type-check again — possibly several times.
+ *
+ * Always call {@link dispose} when finished so the temp directory is cleaned up.
+ * The session is single-use per process; create a new one for a new file map
+ * whose `package.json` differs.
+ */
+export class FrontendTypecheckSession {
+  private constructor(private readonly tempDir: string) {}
+
+  /**
+   * Materialize the file map into a fresh temp directory and run `npm install`
+   * once — except `node_modules` itself is symlinked from a per-package.json
+   * cache directory (`~/.cache/autoview-typecheck/<hash>/node_modules`), so the
+   * install only runs the first time the agent sees a given `package.json`
+   * body. Subsequent opens with the same dependencies finish in milliseconds
+   * instead of the ~30s npm install pays.
+   *
+   * Throws on infra failure (npm missing, install crash) and leaves the temp
+   * dir behind for the operator to inspect. Falls back to a plain in-place
+   * install when the symlink cannot be created (Windows without admin /
+   * filesystem refusing symlinks), so the behavior degrades gracefully.
+   */
+  public static async open(
+    files: Record<string, string>,
+  ): Promise<FrontendTypecheckSession> {
+    const tempDir = await fs.mkdtemp(
+      path.join(os.tmpdir(), "autoview-typecheck-"),
+    );
+    try {
+      await writeFiles(tempDir, files);
+      const hash = hashFrontendDependencies(files);
+      const packageJson = files["package.json"];
+      const cachedNodeModules =
+        packageJson !== undefined
+          ? await ensureCachedNodeModules({
+              cacheNamespace: "typecheck",
+              hash,
+              packageJson,
+            })
+          : null;
+      if (cachedNodeModules !== null) {
+        const linked = await tryLinkNodeModules(tempDir, cachedNodeModules);
+        if (!linked) {
+          await installDependencies(tempDir);
+        }
+      } else {
+        await installDependencies(tempDir);
+      }
+      return new FrontendTypecheckSession(tempDir);
+    } catch (err) {
+      throw enrichError(err, tempDir);
+    }
+  }
+
+  /** Root of the temp dir backing this session. Exposed for diagnostics only. */
+  public get root(): string {
+    return this.tempDir;
+  }
+
+  /**
+   * Overwrite an individual file in the session's working tree. Used by the
+   * retry loop to swap in the LLM's corrected TSX before the next typecheck
+   * run. Creates intermediate directories as needed.
+   */
+  public async writeFile(relative: string, content: string): Promise<void> {
+    const full = path.join(this.tempDir, relative);
+    await fs.mkdir(path.dirname(full), { recursive: true });
+    await fs.writeFile(full, content, "utf-8");
+  }
+
+  /**
+   * Run `tsc --noEmit` against the current state of the working tree and return
+   * the parsed diagnostics + markdown report. Cheap relative to {@link open} (no
+   * npm install) — milliseconds of process spawn plus the actual compile time.
+   */
+  public async typecheck(): Promise<IValidateFrontendTypecheckResult> {
+    const startedAt = Date.now();
+    const stdout = await runTypecheck(this.tempDir);
+    const diagnostics = parseDiagnostics(stdout);
+    const totalErrors = [...diagnostics.values()].reduce(
+      (acc, list) => acc + list.length,
+      0,
+    );
+    return {
+      diagnostics,
+      totalErrors,
+      markdown: renderMarkdownReport(diagnostics, totalErrors),
+      elapsedMs: Date.now() - startedAt,
+    };
+  }
+
+  /**
+   * Remove the temp directory. Safe to call multiple times and never throws —
+   * the caller almost always invokes this from a `finally` block where a
+   * cleanup failure must not mask the original error.
+   */
+  public async dispose(): Promise<void> {
+    await fs.rm(this.tempDir, { recursive: true, force: true }).catch(() => {});
+  }
+}
+
+/**
+ * Stable hash of the project's `package.json` so future cache-aware variants
+ * can key against it. Exposed so callers can decide whether to short-circuit
+ * the check across runs without parsing the file themselves.
+ */
+export function hashFrontendDependencies(
+  files: Record<string, string>,
+): string {
+  const pkgJson = files["package.json"];
+  if (pkgJson === undefined) return "no-package-json";
+  return createHash("sha256").update(pkgJson).digest("hex").slice(0, 16);
+}
+
+async function writeFiles(
+  root: string,
+  files: Record<string, string>,
+): Promise<void> {
+  for (const [relative, content] of Object.entries(files)) {
+    const full = path.join(root, relative);
+    await fs.mkdir(path.dirname(full), { recursive: true });
+    await fs.writeFile(full, content, "utf-8");
+  }
+}
+
+async function installDependencies(root: string): Promise<void> {
+  await spawnCommand(
+    "npm",
+    ["install", "--silent", "--no-audit", "--no-fund"],
+    {
+      cwd: root,
+    },
+  );
+}
+
+async function runTypecheck(root: string): Promise<string> {
+  // Use the locally installed tsc (npm install puts it in
+  // node_modules/.bin) so the version matches the project's typescript
+  // dependency. Capture stdout only — tsc writes diagnostics there
+  // when not in --pretty mode.
+  return spawnCommand(
+    path.join(root, "node_modules", ".bin", "tsc"),
+    ["--noEmit", "--pretty", "false"],
+    { cwd: root, allowNonZeroExit: true },
+  );
+}
+
+interface ISpawnOptions {
+  cwd: string;
+  allowNonZeroExit?: boolean;
+}
+
+function spawnCommand(
+  cmd: string,
+  args: string[],
+  options: ISpawnOptions,
+): 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 || options.allowNonZeroExit === true) {
+        resolve(stdout);
+      } else {
+        reject(
+          new Error(
+            `\`${cmd} ${args.join(" ")}\` exited with code ${code}` +
+              (stderr.length > 0 ? `:\n${stderr}` : ""),
+          ),
+        );
+      }
+    });
+  });
+}
+
+const DIAGNOSTIC_LINE = /^(.+?)\((\d+),(\d+)\): error (TS\d+): (.*)$/;
+
+function parseDiagnostics(stdout: string): Map<string, ITypecheckDiagnostic[]> {
+  const map = new Map<string, ITypecheckDiagnostic[]>();
+  for (const raw of stdout.split(/\r?\n/)) {
+    const match = DIAGNOSTIC_LINE.exec(raw);
+    if (match === null) continue;
+    const [, file, lineRaw, columnRaw, code, message] = match;
+    const diagnostic: ITypecheckDiagnostic = {
+      file: file!,
+      line: parseInt(lineRaw!, 10),
+      column: parseInt(columnRaw!, 10),
+      code: code!,
+      message: message!,
+    };
+    const bucket = map.get(diagnostic.file);
+    if (bucket === undefined) {
+      map.set(diagnostic.file, [diagnostic]);
+    } else {
+      bucket.push(diagnostic);
+    }
+  }
+  return map;
+}
+
+function renderMarkdownReport(
+  diagnostics: Map<string, ITypecheckDiagnostic[]>,
+  totalErrors: number,
+): string {
+  if (totalErrors === 0) {
+    return [
+      "# Typecheck report",
+      "",
+      "`tsc --noEmit` succeeded against the assembled project. No errors.",
+      "",
+    ].join("\n");
+  }
+  const sortedFiles = [...diagnostics.keys()].sort();
+  const sections = sortedFiles.map((file) => {
+    const list = diagnostics.get(file) ?? [];
+    const lines = list.map(
+      (d) =>
+        `- L${d.line}:${d.column} \`${d.code}\` — ${escapeBackticks(d.message)}`,
+    );
+    return [`## \`${file}\` (${list.length})`, "", ...lines, ""].join("\n");
+  });
+  return [
+    "# Typecheck report",
+    "",
+    `\`tsc --noEmit\` reported **${totalErrors}** error(s) across **${diagnostics.size}** file(s).`,
+    "",
+    ...sections,
+  ].join("\n");
+}
+
+function escapeBackticks(input: string): string {
+  return input.replace(/`/g, "\\`");
+}
+
+function enrichError(err: unknown, tempDir: string): Error {
+  const base = err instanceof Error ? err : new Error(String(err));
+  base.message = `${base.message}\n(project preserved at: ${tempDir})`;
+  return base;
+}

package/src/preview/renderPreview.ts

@@ -0,0 +1,273 @@
+import { OpenApi } from "@typia/interface";
+
+import { renderNamedSchema } from "../orchestrate/utils/renderJsonSchema";
+import {
+  classifyEndpoints,
+  filterEndpoints,
+  IAutoViewEndpoint,
+  IClassifiedEndpoint,
+  IEndpointFilter,
+  IResourceGroup,
+  planResource,
+  toEndpoints,
+  unsupportedOperations,
+} from "../utils";
+
+/**
+ * Static `--preview` explorer — the LLM-free READ-layer view.
+ *
+ * Runs only `fromSwagger → toEndpoints` (zero LLM calls) and renders a single
+ * self-contained HTML page so the operator can confirm, in seconds, exactly how
+ * AutoView parsed their swagger: every endpoint grouped by resource, with its
+ * params / query / request / response types expanded. The point is to surface
+ * the READ layer's understanding *before* paying for a full LLM generation run.
+ *
+ * Also emits a READ report: how many endpoints resolved a request / response
+ * body, how many carry query strings, and — critically — how many have a body
+ * the parser could not resolve (non-JSON / multipart), so nothing is dropped
+ * silently.
+ */
+export interface IPreviewMeta {
+  title: string;
+  version: string;
+  serverUrl: string | null;
+}
+
+export function renderPreviewHtml(
+  document: OpenApi.IDocument,
+  meta: IPreviewMeta,
+  filter: IEndpointFilter = {},
+): string {
+  const endpoints = filterEndpoints(toEndpoints(document), filter);
+  const unsupported = unsupportedOperations(document);
+  const groups = classifyEndpoints(endpoints, document);
+  const stats = computeStats(endpoints);
+
+  const sections = groups
+    .map((group) => renderResource(group, document))
+    .join("\n");
+
+  const droppedSection =
+    unsupported.length === 0
+      ? ""
+      : `<section class="resource">
+  <h2 class="warn">dropped <small>${unsupported.length}</small></h2>
+  <p class="note">Operations HttpMigration could not parse (unsupported content type — raw binary upload/download). Listed so they are not lost silently; they need a hand-written page.</p>
+  ${unsupported
+    .map(
+      (u) => `<div class="endpoint"><div class="body" style="padding:.6rem">
+    <span class="method method-${u.method.toLowerCase()}">${esc(u.method)}</span>
+    <code class="path">${esc(u.path)}</code>
+    <span class="badge badge-warn">dropped</span>
+    <div class="detail muted" style="margin-top:.4rem">${esc(u.reason)}</div>
+  </div></div>`,
+    )
+    .join("\n")}
+</section>`;
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>${esc(meta.title)} — AutoView preview</title>
+<style>${STYLE}</style>
+</head>
+<body>
+<header>
+  <h1>${esc(meta.title)} <small>v${esc(meta.version)}</small></h1>
+  <p class="server">${
+    meta.serverUrl
+      ? `backend: <code>${esc(meta.serverUrl)}</code>`
+      : `<span class="warn">no <code>servers[]</code> — frontend would boot in simulator mode</span>`
+  }</p>
+</header>
+<section class="report">
+  <h2>READ report</h2>
+  <div class="cards">
+    <div class="card"><b>${stats.total}</b><span>endpoints</span></div>
+    <div class="card"><b>${groups.length}</b><span>resources</span></div>
+    <div class="card"><b>${stats.withQuery}</b><span>query endpoints</span></div>
+    <div class="card"><b>${stats.reqBody}</b><span>request bodies</span></div>
+    <div class="card"><b>${stats.resBody}</b><span>response bodies</span></div>
+    <div class="card ${stats.unresolvedBody > 0 ? "card-warn" : ""}"><b>${stats.unresolvedBody}</b><span>unresolved body*</span></div>
+    <div class="card ${unsupported.length > 0 ? "card-warn" : ""}"><b>${unsupported.length}</b><span>dropped**</span></div>
+  </div>
+  <p class="note">* write operations whose request body the READ layer could not resolve (typically multipart). Marked <span class="badge badge-warn">no-body</span> below.<br/>** operations HttpMigration could not parse at all (unsupported content type). Listed in the <b>dropped</b> section so nothing is lost silently.</p>
+</section>
+${sections}
+${droppedSection}
+<footer>Generated by AutoView <code>--preview</code> — READ layer only, no LLM. Run the full command (without <code>--preview</code>) to generate the frontend.</footer>
+</body>
+</html>`;
+}
+
+interface IStats {
+  total: number;
+  withQuery: number;
+  reqBody: number;
+  resBody: number;
+  unresolvedBody: number;
+}
+
+function computeStats(endpoints: IAutoViewEndpoint[]): IStats {
+  let withQuery = 0;
+  let reqBody = 0;
+  let resBody = 0;
+  let unresolvedBody = 0;
+  const bodyMethods = new Set(["post", "put", "patch"]);
+  for (const ep of endpoints) {
+    if (ep.query !== null) withQuery++;
+    if (ep.requestBody !== null) reqBody++;
+    if (ep.responseBody !== null) resBody++;
+    // A write operation with no resolvable request body is a candidate for a
+    // silently-dropped non-JSON / multipart payload.
+    if (bodyMethods.has(ep.method.toLowerCase()) && ep.requestBody === null) {
+      unresolvedBody++;
+    }
+  }
+  return { total: endpoints.length, withQuery, reqBody, resBody, unresolvedBody };
+}
+
+function renderResource(
+  group: IResourceGroup,
+  document: OpenApi.IDocument,
+): string {
+  const rows = group.endpoints
+    .map((c) => renderEndpoint(c, document))
+    .join("\n");
+  // Deterministic screen set this resource produces — actual Next.js paths.
+  const screens = planResource(group);
+  const plannedHtml = screens
+    .map(
+      (s) =>
+        `<span class="screen screen-${s.kind}"><code>${esc(s.path)}</code> <i>${s.kind}</i></span>`,
+    )
+    .join("");
+  return `<section class="resource">
+  <h2>${esc(group.resource)} <small>${group.endpoints.length}</small></h2>
+  <div class="planned">screens: ${plannedHtml || "<i class='muted'>none (no list/detail/create/update)</i>"}</div>
+  ${rows}
+</section>`;
+}
+
+function renderEndpoint(
+  classified: IClassifiedEndpoint,
+  document: OpenApi.IDocument,
+): string {
+  const ep = classified.endpoint;
+  const method = ep.method.toLowerCase();
+  const bodyMethods = new Set(["post", "put", "patch"]);
+  const unresolved =
+    bodyMethods.has(method) && ep.requestBody === null
+      ? `<span class="badge badge-warn">no-body</span>`
+      : "";
+  const queryBadge =
+    ep.query !== null ? `<span class="badge badge-q">query</span>` : "";
+
+  const details: string[] = [];
+  if (ep.parameters.length > 0) {
+    details.push(
+      `<div class="detail"><b>path</b> ${ep.parameters
+        .map((p) => `<code>${esc(p.name)}</code>`)
+        .join(" ")}</div>`,
+    );
+  }
+  if (ep.query !== null) {
+    details.push(
+      `<div class="detail"><b>query</b><pre>${esc(renderSchemaInline(ep.query, document))}</pre></div>`,
+    );
+  }
+  if (ep.requestBody !== null) {
+    details.push(
+      `<div class="detail"><b>request</b> <code>${esc(ep.requestBody.typeName)}</code><pre>${esc(renderNamedSchema(ep.requestBody.typeName, document))}</pre></div>`,
+    );
+  }
+  if (ep.responseBody !== null) {
+    details.push(
+      `<div class="detail"><b>response</b> <code>${esc(ep.responseBody.typeName)}</code><pre>${esc(renderNamedSchema(ep.responseBody.typeName, document))}</pre></div>`,
+    );
+  }
+
+  return `<details class="endpoint">
+  <summary>
+    <span class="badge role role-${classified.role}">${classified.role}</span>
+    <span class="method method-${method}">${esc(ep.method.toUpperCase())}</span>
+    <code class="path">${esc(ep.path)}</code>
+    ${queryBadge}${unresolved}
+    <span class="accessor">${esc(ep.accessor.join("."))}</span>
+  </summary>
+  <div class="body">
+    ${ep.description ? `<p class="desc">${esc(ep.description)}</p>` : ""}
+    ${details.join("\n    ") || '<div class="detail muted">no params / body</div>'}
+  </div>
+</details>`;
+}
+
+// The query schema is an inline object (not a $ref), so render it directly via
+// renderNamedSchema's sibling path — but renderNamedSchema only takes a type
+// name. For inline query schemas we stringify the JSON shape compactly.
+function renderSchemaInline(
+  schema: OpenApi.IJsonSchema,
+  _document: OpenApi.IDocument,
+): string {
+  if ("properties" in schema && schema.properties) {
+    const required = new Set(schema.required ?? []);
+    return Object.entries(schema.properties)
+      .map(([name, prop]) => {
+        const opt = required.has(name) ? "" : "?";
+        const t = "type" in prop ? String(prop.type) : "unknown";
+        return `${name}${opt}: ${t}`;
+      })
+      .join("\n");
+  }
+  return "type" in schema ? String(schema.type) : "unknown";
+}
+
+function esc(s: string): string {
+  return s
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+const STYLE = `
+:root { color-scheme: light dark; }
+* { box-sizing: border-box; }
+body { font: 14px/1.5 ui-sans-serif, system-ui, sans-serif; margin: 0; padding: 0 0 4rem; max-width: 900px; margin-inline: auto; }
+header { padding: 2rem 1.5rem 1rem; border-bottom: 1px solid #8883; }
+h1 { margin: 0; font-size: 1.6rem; } h1 small { font-weight: 400; opacity: .55; font-size: .9rem; }
+.server { margin: .4rem 0 0; opacity: .8; } .warn { color: #c80; }
+code { font-family: ui-monospace, monospace; background: #8881; padding: .05em .35em; border-radius: 4px; }
+.report { padding: 1rem 1.5rem; }
+.report h2, .resource h2 { font-size: 1rem; text-transform: uppercase; letter-spacing: .05em; opacity: .6; }
+.cards { display: flex; flex-wrap: wrap; gap: .6rem; }
+.card { background: #8881; border-radius: 8px; padding: .6rem .9rem; min-width: 90px; }
+.card b { display: block; font-size: 1.5rem; } .card span { opacity: .65; font-size: .8rem; }
+.card-warn { background: #c8001a; color: #fff; } .card-warn span { opacity: .85; }
+.note { font-size: .8rem; opacity: .6; }
+.resource { padding: .3rem 1.5rem; }
+.endpoint { border: 1px solid #8883; border-radius: 8px; margin: .35rem 0; padding: .1rem .2rem; }
+.endpoint summary { cursor: pointer; padding: .5rem; display: flex; align-items: center; gap: .5rem; flex-wrap: wrap; }
+.method { font-weight: 700; font-size: .72rem; padding: .15em .5em; border-radius: 4px; color: #fff; }
+.method-get { background: #2563eb; } .method-post { background: #16a34a; }
+.method-put, .method-patch { background: #d97706; } .method-delete { background: #dc2626; }
+.path { font-size: .95rem; } .accessor { margin-left: auto; opacity: .45; font-size: .8rem; font-family: ui-monospace, monospace; }
+.badge { font-size: .68rem; padding: .1em .45em; border-radius: 4px; }
+.badge-q { background: #7c3aed; color: #fff; } .badge-warn { background: #c8001a; color: #fff; }
+.roles, .planned { padding: .1rem 0 .5rem; opacity: .9; font-size: .8rem; }
+.planned .screen { display: inline-block; margin: .15rem .3rem .15rem 0; padding: .1rem .4rem; border-radius: 5px; background: #8881; }
+.planned .screen i { opacity: .55; font-style: normal; font-size: .72rem; text-transform: uppercase; }
+.screen-list { border-left: 3px solid #2563eb; } .screen-detail { border-left: 3px solid #0891b2; }
+.screen-create { border-left: 3px solid #16a34a; } .screen-edit { border-left: 3px solid #d97706; }
+.role { font-weight: 700; text-transform: uppercase; letter-spacing: .03em; }
+.role-list { background: #2563eb; color: #fff; } .role-search { background: #7c3aed; color: #fff; }
+.role-detail { background: #0891b2; color: #fff; } .role-create { background: #16a34a; color: #fff; }
+.role-update { background: #d97706; color: #fff; } .role-delete { background: #dc2626; color: #fff; }
+.role-action { background: #64748b; color: #fff; }
+.body { padding: 0 .6rem .6rem; } .desc { opacity: .75; margin: .2rem 0 .6rem; }
+.detail { margin: .3rem 0; } .detail b { display: inline-block; min-width: 4.5rem; opacity: .55; font-size: .8rem; text-transform: uppercase; }
+.detail pre { margin: .2rem 0 0; background: #8881; padding: .5rem .7rem; border-radius: 6px; overflow-x: auto; font-size: .82rem; }
+.muted { opacity: .5; }
+footer { padding: 2rem 1.5rem; opacity: .5; font-size: .8rem; border-top: 1px solid #8883; margin-top: 1rem; }
+`;

package/src/typings/compiler.ts

@@ -0,0 +1,47 @@
+import { OpenApi } from "@typia/interface";
+
+/**
+ * Narrow self-defined view of the AutoBE compiler. AutoView only calls
+ * `compiler.interface.write(document, exclude)` to materialize the SDK source
+ * it shows the LLM, so only that surface is reproduced here.
+ *
+ * Step 3 of the standalone track replaces the underlying `@autobe/compiler`
+ * runtime with a standard-OpenAPI SDK generator; this interface is the seam
+ * that change happens behind.
+ */
+export interface IAutoBeCompiler {
+  interface: IAutoBeInterfaceCompiler;
+}
+
+export interface IAutoBeInterfaceCompiler {
+  /**
+   * Generate the SDK / NestJS project source for an OpenAPI document.
+   *
+   * @param document AutoBE OpenAPI AST document
+   * @param options Either an exclude list, or a `{ language, exclude }` object
+   * @returns `path → content` map of the generated project
+   */
+  write(
+    document: OpenApi.IDocument,
+    options:
+      | string[]
+      | {
+          language: "typescript" | "java";
+          exclude: string[];
+        },
+  ): Promise<Record<string, string>>;
+}
+
+/**
+ * Compiler event listener. AutoView hands the compiler a no-op sink (no UI to
+ * forward realize-test events to), so only the nested shape the sink fills is
+ * modeled. Loosely typed because the standalone path never reads the args.
+ */
+export interface IAutoBeCompilerListener {
+  realize: {
+    test: {
+      onOperation: (...args: unknown[]) => Promise<void>;
+      onReset: (...args: unknown[]) => Promise<void>;
+    };
+  };
+}