@autoview/cli 0.1.0

package/src/fromSwagger.ts

@@ -0,0 +1,500 @@
+import { OpenApi } from "@typia/interface";
+import { OpenApiConverter } from "@typia/utils";
+import fs from "fs/promises";
+
+/**
+ * Normalize a raw OpenAPI / Swagger payload into a standard
+ * {@link OpenApi.IDocument} — the swagger-native shape the AutoView
+ * orchestrators now consume directly (via {@link toEndpoints}).
+ *
+ * Accepts both an in-memory JSON object and a file path; the latter is
+ * convenient for the CLI binary. `OpenApiConverter.upgradeDocument` upgrades
+ * Swagger 2.0 / OpenAPI 3.0 / 3.1 to a single normalized 3.1 document, so
+ * every endpoint — query-string endpoints included — is preserved. (The old
+ * `invertOpenApiDocument` route through the AutoBE AST silently dropped
+ * query-string endpoints.)
+ */
+export function fromSwagger(
+  swagger: Parameters<typeof OpenApiConverter.upgradeDocument>[0],
+): OpenApi.IDocument {
+  resolveParameterRefs(swagger);
+  resolvePathRefs(swagger);
+  stripPathRefAllOf(swagger, 0);
+  flattenAllOf(swagger);
+  promoteInlineBodies(swagger);
+  dropUnroutablePaths(swagger);
+  return OpenApiConverter.upgradeDocument(swagger);
+}
+
+/**
+ * Resolve `$ref`s that are a JSON Pointer INTO another operation's inline
+ * schema (`#/paths/~1v2~1bandwidth/get/responses/...`) by replacing the `$ref`
+ * node with a deep clone of the pointer's target. DigitalOcean DRYs whole
+ * response schemas this way — at the schema root (`/v2/monitoring/metrics/*`
+ * all alias one bandwidth schema) and inside properties
+ * (`POST /v2/apps` → `{ app: $ref → GET /v2/apps …items }`). Standard tooling
+ * only chases `#/components/...` refs; nestia emits `Response = any` for these,
+ * which turns every simulate-mode screen of the resource into a silent empty
+ * state.
+ *
+ * Cycle-safe: a pointer actively being expanded is left verbatim (the later
+ * allOf-stripping pass treats the leftover as noise). Depth-guarded against
+ * pathological nesting. Mutates `raw` in place.
+ */
+function resolvePathRefs(raw: unknown): void {
+  /**
+   * Follow an escaped JSON Pointer from the root. Being a URI fragment, parts
+   * are percent-decoded first (`%7B` → `{` — DO encodes `{app_id}` segments),
+   * then pointer-unescaped (`~1` → `/`, `~0` → `~`), per RFC 6901.
+   */
+  const lookup = (pointer: string): unknown => {
+    let node: unknown = raw;
+    for (const part of pointer.slice(2).split("/")) {
+      let key = part;
+      try {
+        key = decodeURIComponent(key);
+      } catch {
+        // not percent-encoded — use the raw part
+      }
+      key = key.replace(/~1/g, "/").replace(/~0/g, "~");
+      if (typeof node !== "object" || node === null) return undefined;
+      node = (node as Record<string, unknown>)[key];
+    }
+    return node;
+  };
+
+  const active = new Set<string>();
+  const walk = (node: unknown, depth: number): void => {
+    if (depth > 64 || typeof node !== "object" || node === null) return;
+    if (Array.isArray(node)) {
+      for (const v of node) walk(v, depth + 1);
+      return;
+    }
+    const obj = node as Record<string, unknown>;
+    const ref = obj.$ref;
+    if (typeof ref === "string" && ref.startsWith("#/paths/")) {
+      if (!active.has(ref)) {
+        const target = lookup(ref);
+        if (typeof target === "object" && target !== null) {
+          active.add(ref);
+          // The target may itself hold path-pointers — resolve before cloning.
+          walk(target, depth + 1);
+          active.delete(ref);
+          delete obj.$ref;
+          Object.assign(obj, structuredClone(target));
+        }
+      }
+      return; // a (possibly unresolved) ref node has nothing else to walk
+    }
+    for (const v of Object.values(obj)) walk(v, depth + 1);
+  };
+  walk(raw, 0);
+}
+
+/**
+ * Promote every INLINE OBJECT request/response body into a uniquely named
+ * component schema (replacing it with a `$ref`) BEFORE nestia sees the document.
+ *
+ * nestia promotes inline bodies itself, but derives the component name from the
+ * path with `{param}` segments DROPPED — so a parent list and its child detail
+ * (`/v2/droplets` vs `/v2/droplets/{droplet_id}`) both claim
+ * `IApiV2Droplets.GetResponse`. The loser's SDK function is emitted as
+ * `Response = any`; `typia.random<any>()` then yields nothing, and the
+ * simulate-mode screen for that resource renders empty forever — silently. On
+ * DigitalOcean (every body inline) this gutted 38 of 148 SDK files.
+ *
+ * Naming here keeps the param segments (`ApiV2DropletsDropletIdGetResponse`), so
+ * names cannot collide across sibling paths; an unexpected clash falls back to a
+ * numeric suffix. Only plain OBJECT schemas are hoisted: an inline ARRAY must
+ * stay inline so the READ layer still sees `Array<$ref>` and derives the list's
+ * element columns ({@link toEndpoints}'s `resolveBody`), and primitives gain
+ * nothing. Swagger 2.0 inputs are skipped — they have no `components` section
+ * for the refs to land in (the upgrade builds it later). Mutates `raw` in place.
+ */
+function promoteInlineBodies(raw: unknown): void {
+  if (typeof raw !== "object" || raw === null) return;
+  const doc = raw as {
+    openapi?: unknown;
+    paths?: Record<string, Record<string, unknown>>;
+    components?: { schemas?: Record<string, unknown> };
+  };
+  if (typeof doc.openapi !== "string" || doc.paths === undefined) return;
+  doc.components ??= {};
+  doc.components.schemas ??= {};
+  const table = doc.components.schemas;
+
+  const pascal = (s: string): string =>
+    s
+      .replace(/[{}]/g, "")
+      .split(/[^A-Za-z0-9]+/)
+      .filter(Boolean)
+      .map((w) => w[0]!.toUpperCase() + w.slice(1))
+      .join("");
+  const claim = (base: string): string => {
+    let name = base;
+    for (let i = 2; table[name] !== undefined; i++) name = `${base}${i}`;
+    return name;
+  };
+  const isInlineObject = (schema: unknown): schema is Record<string, unknown> =>
+    typeof schema === "object" &&
+    schema !== null &&
+    (schema as { $ref?: unknown }).$ref === undefined &&
+    ((schema as { type?: unknown }).type === "object" ||
+      typeof (schema as { properties?: unknown }).properties === "object") &&
+    Object.keys(
+      ((schema as { properties?: unknown }).properties ?? {}) as object,
+    ).length > 0;
+  const hoist = (holder: unknown, baseName: string): void => {
+    const h = holder as { schema?: unknown } | undefined;
+    if (h === undefined || !isInlineObject(h.schema)) return;
+    const name = claim(baseName);
+    table[name] = h.schema;
+    h.schema = { $ref: `#/components/schemas/${name}` };
+  };
+
+  for (const [path, item] of Object.entries(doc.paths)) {
+    if (typeof item !== "object" || item === null) continue;
+    const pathName = path.split("/").filter(Boolean).map(pascal).join("");
+    for (const method of ["get", "post", "put", "patch", "delete", "head"]) {
+      const op = item[method] as
+        | {
+            requestBody?: { content?: Record<string, unknown> };
+            responses?: Record<string, { content?: Record<string, unknown> }>;
+          }
+        | undefined;
+      if (op === undefined || typeof op !== "object") continue;
+      const opName = `Api${pathName}${pascal(method)}`;
+      hoist(op.requestBody?.content?.["application/json"], `${opName}Body`);
+      for (const [status, response] of Object.entries(op.responses ?? {})) {
+        if (typeof response !== "object" || response === null) continue;
+        hoist(
+          response.content?.["application/json"],
+          `${opName}${pascal(status)}Response`,
+        );
+      }
+    }
+  }
+}
+
+/**
+ * Strip `allOf` members that are an unresolvable JSON-Pointer `$ref` INTO another
+ * operation's inline schema (`#/paths/~1v2~1account~1keys/.../allOf/1`) — the way
+ * DigitalOcean DRYs up shared pagination/meta wrappers. `upgradeDocument` cannot
+ * chase a `#/paths/...` pointer, and when one sits alongside the real data member
+ * (`allOf: [{ properties: { droplets } }, <links-ref>, <meta-ref>]`) it discards
+ * the WHOLE `allOf` — so the list response comes out an empty schema, its table
+ * renders no columns, and its id producer is lost. Drop only the path-pointer
+ * members (pagination noise, not domain data); when a single data member with
+ * `properties` remains, hoist it to a plain object so the upgrade keeps it.
+ * Document-wide, depth-guarded, mutates in place.
+ */
+function stripPathRefAllOf(node: unknown, depth: number): void {
+  if (node === null || typeof node !== "object" || depth > 64) return;
+  if (Array.isArray(node)) {
+    for (const v of node) stripPathRefAllOf(v, depth + 1);
+    return;
+  }
+  const obj = node as Record<string, unknown>;
+  if (Array.isArray(obj.allOf)) {
+    const kept = obj.allOf.filter(
+      (m) =>
+        !(
+          m !== null &&
+          typeof m === "object" &&
+          typeof (m as { $ref?: unknown }).$ref === "string" &&
+          ((m as { $ref: string }).$ref).startsWith("#/paths/")
+        ),
+    );
+    if (kept.length !== obj.allOf.length) {
+      const only = kept[0] as Record<string, unknown> | undefined;
+      if (kept.length === 1 && only?.properties !== undefined && only.$ref === undefined) {
+        obj.type = "object";
+        obj.properties = { ...(obj.properties as object), ...(only.properties as object) };
+        if (only.required !== undefined) obj.required = only.required;
+        delete obj.allOf;
+      } else if (kept.length === 0) {
+        delete obj.allOf;
+      } else {
+        obj.allOf = kept;
+      }
+    }
+  }
+  for (const v of Object.values(obj)) stripPathRefAllOf(v, depth + 1);
+}
+
+/**
+ * Flatten `allOf` composition into plain `properties` BEFORE upgrading —
+ * document-wide, not just component schemas. Two real-world failure shapes:
+ *
+ * - `OpenApiConverter.upgradeDocument` drops `allOf` for some component shapes
+ *   (Box's `CollaborationAllowlistEntries = allOf[Pagination, { entries }]`
+ *   comes out an empty object), so the type would render zero fields.
+ * - An `allOf` INLINE in an operation response (DigitalOcean's
+ *   `GET /v2/droplets` → `allOf:[{properties:{droplets}}, {$ref:Pagination}]`)
+ *   defeats nestia's type emitter: the route's SDK function comes out
+ *   `Response = any`, `typia.random<any>()` yields nothing, and every
+ *   simulate-mode screen for that resource renders empty forever — silently
+ *   (38 of DigitalOcean's 148 SDK files before this pass).
+ *
+ * Merge each member's properties (resolving `$ref` members recursively,
+ * depth-guarded) into the schema's own `properties` and remove the `allOf`, so
+ * the composed fields survive both the upgrade and SDK generation. Component
+ * schemas are flattened first (so `$ref` members resolve to already-flat
+ * shapes), then every remaining `allOf` anywhere in the document. Mutates `raw`
+ * in place.
+ */
+function flattenAllOf(raw: unknown): void {
+  if (typeof raw !== "object" || raw === null) return;
+  const schemas = (raw as { components?: { schemas?: unknown } }).components
+    ?.schemas;
+  const table = (typeof schemas === "object" && schemas !== null
+    ? schemas
+    : {}) as Record<string, Record<string, unknown>>;
+
+  const merge = (
+    schema: unknown,
+    depth: number,
+    seen: ReadonlySet<string>,
+  ): { properties: Record<string, unknown>; required: string[] } => {
+    if (depth > 8 || typeof schema !== "object" || schema === null) {
+      return { properties: {}, required: [] };
+    }
+    const node = schema as Record<string, unknown>;
+    if (typeof node.$ref === "string") {
+      const name = node.$ref.split("/").pop()!;
+      if (seen.has(name) || table[name] === undefined) {
+        return { properties: {}, required: [] };
+      }
+      return merge(table[name], depth + 1, new Set([...seen, name]));
+    }
+    let properties: Record<string, unknown> = {};
+    let required: string[] = [];
+    if (Array.isArray(node.allOf)) {
+      for (const member of node.allOf) {
+        const sub = merge(member, depth + 1, seen);
+        properties = { ...properties, ...sub.properties };
+        required = [...required, ...sub.required];
+      }
+    }
+    if (typeof node.properties === "object" && node.properties !== null) {
+      properties = { ...properties, ...(node.properties as object) };
+    }
+    if (Array.isArray(node.required)) required = [...required, ...node.required];
+    return { properties, required: [...new Set(required)] };
+  };
+
+  const flattenInPlace = (
+    schema: Record<string, unknown>,
+    seen: ReadonlySet<string>,
+  ): void => {
+    const merged = merge(schema, 0, seen);
+    if (Object.keys(merged.properties).length > 0) {
+      schema.properties = merged.properties;
+      schema.required = merged.required;
+      schema.type = "object";
+      delete schema.allOf;
+    }
+  };
+
+  // Pass 1 — component schemas, so a `$ref` member met later resolves flat.
+  for (const name of Object.keys(table)) {
+    const schema = table[name];
+    if (schema === undefined || !Array.isArray(schema.allOf)) continue;
+    flattenInPlace(schema, new Set([name]));
+  }
+
+  // Pass 2 — every remaining `allOf` anywhere in the document (inline response
+  // and request schemas, nested properties, array items …).
+  const walk = (node: unknown, depth: number): void => {
+    if (depth > 64 || typeof node !== "object" || node === null) return;
+    if (Array.isArray(node)) {
+      for (const v of node) walk(v, depth + 1);
+      return;
+    }
+    const obj = node as Record<string, unknown>;
+    // Children first, so a nested allOf is flat before its parent merges it.
+    for (const v of Object.values(obj)) walk(v, depth + 1);
+    if (Array.isArray(obj.allOf)) flattenInPlace(obj, new Set());
+  };
+  walk(raw, 0);
+}
+
+/**
+ * Remove path keys a typed SDK cannot be generated from:
+ *
+ * 1. `#` fragments some swaggers (Box) use to disambiguate overloaded paths
+ *    (`/shared_items#folders`) — nestia turns the `#` into an illegal JS
+ *    accessor segment, and the generated SDK file fails to parse.
+ * 2. A path-template parameter whose NAME is not a valid identifier
+ *    (`/teams/{enterprise-team}/...`, GitHub). nestia derives the SDK accessor
+ *    from the param name and crashes (`Cannot read properties of undefined`)
+ *    when the hyphenated name does not round-trip — taking the WHOLE generation
+ *    down, not just that route.
+ *
+ * Dropping the handful of offending paths up front lets the rest of a large real
+ * swagger (GitHub's 1190 operations) generate. Mutates `raw` in place.
+ */
+function dropUnroutablePaths(raw: unknown): void {
+  if (typeof raw !== "object" || raw === null) return;
+  const paths = (raw as Record<string, unknown>).paths;
+  if (typeof paths !== "object" || paths === null) return;
+  // Standard URL path characters only — letters, digits, `_-./`, and `{param}`.
+  const SAFE = /^[A-Za-z0-9_\-./{}]+$/;
+  // A `{param}` template name must be a valid JS identifier (no hyphens).
+  const IDENT_PARAM = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+  for (const key of Object.keys(paths as object)) {
+    const paramNames = [...key.matchAll(/\{([^}]+)\}/g)].map((m) => m[1]!);
+    if (!SAFE.test(key) || paramNames.some((p) => !IDENT_PARAM.test(p))) {
+      delete (paths as Record<string, unknown>)[key];
+    }
+  }
+}
+
+/**
+ * Resolve `$ref` parameters before upgrading. Real-world swaggers (DigitalOcean,
+ * Box, …) DRY up shared query/path parameters with a `$ref` — sometimes a
+ * standard `#/components/parameters/X`, sometimes a raw JSON Pointer into another
+ * operation (`#/paths/~1v2~1account~1keys/get/parameters/0`). `upgradeDocument`
+ * does not chase those pointers; it leaves the slot `null`, which then crashes
+ * `HttpMigration` with "Cannot read properties of undefined (reading 'in')".
+ *
+ * Walk every operation's (and path item's) `parameters`, dereference each `$ref`
+ * by generic JSON Pointer against the raw document — transitively, with a depth
+ * guard — and drop anything that does not resolve to a real `{ in, name }`
+ * parameter. Mutates the freshly-parsed payload in place (we own it; cloning a
+ * multi-MB document would be wasteful).
+ */
+function resolveParameterRefs(raw: unknown): unknown {
+  if (typeof raw !== "object" || raw === null) return raw;
+  const doc = raw as Record<string, unknown>;
+  const paths = doc.paths;
+  if (typeof paths !== "object" || paths === null) return raw;
+
+  const resolve = (node: unknown, depth: number): unknown => {
+    if (depth > 16 || node === null || typeof node !== "object") return undefined;
+    const ref = (node as { $ref?: unknown }).$ref;
+    if (typeof ref === "string") return resolve(jsonPointer(doc, ref), depth + 1);
+    return "in" in (node as object) ? node : undefined;
+  };
+  const clean = (list: unknown): unknown[] | undefined => {
+    if (!Array.isArray(list)) return undefined;
+    return list.map((p) => resolve(p, 0)).filter((p) => p !== undefined);
+  };
+
+  const METHODS = ["get", "post", "put", "patch", "delete", "options", "head"];
+  for (const key of Object.keys(paths as object)) {
+    const item = (paths as Record<string, unknown>)[key];
+    if (typeof item !== "object" || item === null) continue;
+    const pathItem = item as Record<string, unknown>;
+    const shared = clean(pathItem.parameters);
+    if (shared !== undefined) pathItem.parameters = shared;
+    for (const method of METHODS) {
+      const op = pathItem[method];
+      if (typeof op !== "object" || op === null) continue;
+      const params = clean((op as Record<string, unknown>).parameters);
+      if (params !== undefined) {
+        (op as Record<string, unknown>).parameters = params;
+      }
+    }
+  }
+  return raw;
+}
+
+/** Resolve a `#/...` JSON Pointer against a document. Returns `undefined` on miss. */
+function jsonPointer(doc: unknown, pointer: string): unknown {
+  if (!pointer.startsWith("#/")) return undefined;
+  let current: unknown = doc;
+  for (const rawPart of pointer.slice(2).split("/")) {
+    const part = rawPart.replace(/~1/g, "/").replace(/~0/g, "~");
+    if (current === null || typeof current !== "object") return undefined;
+    current = (current as Record<string, unknown>)[part];
+  }
+  return current;
+}
+
+/**
+ * File-path convenience: read `path` as UTF-8 JSON, parse, and run it through
+ * {@link fromSwagger}. Rejects with a helpful error message when the file is
+ * missing or not valid JSON.
+ */
+export async function fromSwaggerFile(
+  path: string,
+): Promise<OpenApi.IDocument> {
+  let raw: string;
+  try {
+    raw = await fs.readFile(path, "utf-8");
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`Failed to read swagger file at "${path}": ${message}`);
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`Swagger file at "${path}" is not valid JSON: ${message}`);
+  }
+  return fromSwagger(
+    parsed as Parameters<typeof OpenApiConverter.upgradeDocument>[0],
+  );
+}
+
+/**
+ * Pull the first non-empty `servers[].url` out of a raw OpenAPI payload, or
+ * `null` when none is present.
+ *
+ * `OpenApi.IDocument` (the shape AutoView's orchestrators consume) does
+ * not carry the OpenAPI `servers[]` field — it is dropped by
+ * `invertOpenApiDocument` because the AutoBE backend phases do not need it. The
+ * standalone CLI does need it, though: it is the difference between the
+ * generated frontend booting with `simulate: false` against the user's real
+ * backend (real data on first open) and the simulator default (typia-random
+ * gibberish). Read it directly off the raw swagger here so the CLI can pass the
+ * host into {@link AutoViewAgent} without parsing the swagger twice.
+ *
+ * Returns `null` when:
+ *
+ * - The payload is not an object, or
+ * - `servers` is missing / empty / not an array, or
+ * - No `servers[i].url` is a non-empty string.
+ */
+export function extractBackendFromSwagger(payload: unknown): {
+  host: string;
+} | null {
+  if (typeof payload !== "object" || payload === null) return null;
+  const servers = (payload as { servers?: unknown }).servers;
+  if (!Array.isArray(servers)) return null;
+  for (const server of servers) {
+    if (typeof server !== "object" || server === null) continue;
+    const url = (server as { url?: unknown }).url;
+    if (typeof url === "string" && url.length > 0) {
+      return { host: url };
+    }
+  }
+  return null;
+}
+
+/**
+ * File-path convenience for {@link extractBackendFromSwagger}: read `path` as
+ * UTF-8 JSON, parse, and run it through the extractor. Returns `null` on read
+ * or parse failure rather than throwing — the caller usually has a `--backend
+ * <url>` flag and a simulator fallback to lean on, and a missing file would
+ * already have failed louder via {@link fromSwaggerFile}.
+ */
+export async function extractBackendFromSwaggerFile(
+  path: string,
+): Promise<{ host: string } | null> {
+  let raw: string;
+  try {
+    raw = await fs.readFile(path, "utf-8");
+  } catch {
+    return null;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  return extractBackendFromSwagger(parsed);
+}

package/src/generateDeterministic.test.ts

@@ -0,0 +1,39 @@
+import { OpenApiConverter } from "@typia/utils";
+import { describe, expect, it } from "vitest";
+
+import { generateDeterministic } from "./generateDeterministic";
+
+function doc(paths: Record<string, unknown>, schemas: Record<string, unknown> = {}) {
+  return OpenApiConverter.upgradeDocument({
+    openapi: "3.0.0", info: { title: "Shop", version: "1.0.0" }, paths, components: { schemas },
+  } as never);
+}
+
+const fixture = doc(
+  {
+    "/sales": { get: { operationId: "index", responses: { 200: { description: "ok", content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/Sale" } } } } } } } },
+    "/sales/{saleId}": { get: { operationId: "at", parameters: [{ name: "saleId", in: "path", required: true, schema: { type: "string" } }], responses: { 200: { description: "ok", content: { "application/json": { schema: { $ref: "#/components/schemas/Sale" } } } } } } },
+  },
+  { Sale: { type: "object", properties: { id: { type: "string" }, title: { type: "string" } }, required: ["id"] } },
+);
+
+describe("generateDeterministic", () => {
+  it("produces a runnable project with NO LLM (scaffold + pages + connection)", async () => {
+    const files = await generateDeterministic(fixture, { backend: { host: null } });
+    // the project shell, the connection module, and at least the list page exist
+    expect(files["app/page.tsx"]).toBeDefined();
+    expect(files["src/lib/connection.ts"]).toBeDefined();
+    expect(files["app/sales/page.tsx"]).toBeDefined();
+    // the list page wires the typed SDK call — proof the deterministic render ran
+    expect(files["app/sales/page.tsx"]).toContain("api.functional.sales");
+    // no LLM path was taken (it would have thrown); reaching here proves it
+    expect(Object.keys(files).length).toBeGreaterThan(20);
+  }, 30000);
+
+  it("is deterministic — same document, same files", async () => {
+    const a = await generateDeterministic(fixture, { backend: { host: null } });
+    const b = await generateDeterministic(fixture, { backend: { host: null } });
+    expect(Object.keys(a).sort()).toEqual(Object.keys(b).sort());
+    expect(a["app/sales/page.tsx"]).toBe(b["app/sales/page.tsx"]);
+  }, 30000);
+});

package/src/generateDeterministic.ts

@@ -0,0 +1,77 @@
+import { OpenApi } from "@typia/interface";
+
+import { AutoViewInterfaceCompiler } from "./compiler/AutoViewInterfaceCompiler";
+import { orchestrateAutoViewRenderDeterministic } from "./orchestrate/orchestrateAutoViewRenderDeterministic";
+import { orchestrateAutoViewScaffold } from "./orchestrate/orchestrateAutoViewScaffold";
+import { buildDeterministicPlan } from "./orchestrate/utils/buildDeterministicPlan";
+import { buildDeterministicSdkMap } from "./orchestrate/utils/buildDeterministicSdkMap";
+import { normalizeProductPlanPaths } from "./orchestrate/utils/normalizeProductPlanPaths";
+import { IEndpointFilter } from "./utils/endpointFilter";
+import { sliceDocument } from "./utils/sliceDocument";
+
+/**
+ * Generate the frontend with NO LLM and NO API key — the whole READ → MAP →
+ * RENDER pipeline is deterministic, so for the common case (a clean swagger that
+ * compiles) you do not need a model at all. This is the path the `--no-llm` CLI
+ * flag and any programmatic caller take.
+ *
+ * It runs exactly the deterministic phases of {@link orchestrateAutoView}:
+ *
+ * 1. slice the document to `include`/`exclude` (so a large ERP spec still fits),
+ * 2. derive the SDK map + product plan structurally,
+ * 3. scaffold the project + render every page deterministically.
+ *
+ * It deliberately skips the LLM phases the full agent runs — the typecheck-
+ * recovery rerender, the runtime audit, the UI review. The render is already
+ * typecheck-clean on real swaggers; without a key those polish passes simply do
+ * not run. Returns the flat `path → content` project map.
+ */
+export async function generateDeterministic(
+  rawDocument: OpenApi.IDocument,
+  options: {
+    backend: { host: string | null };
+    filter?: IEndpointFilter;
+    semaphore?: number;
+  },
+): Promise<Record<string, string>> {
+  const document = sliceDocument(rawDocument, options.filter ?? {});
+  const sdkMap = buildDeterministicSdkMap(document);
+  const actor = sdkMap.actors[0]?.name ?? "user";
+  const productPlan = normalizeProductPlanPaths(
+    buildDeterministicPlan(document, actor, options.filter ?? {}),
+  );
+
+  // A minimal context: the deterministic phases need only the interface compiler
+  // and a semaphore. `conversate` must never be reached on this path — if it is,
+  // that is a bug (an LLM call leaked into the deterministic pipeline).
+  const compiler = { interface: new AutoViewInterfaceCompiler() };
+  const ctx = {
+    state: () => ({ interface: { document, step: 0 } }),
+    compiler: async () => compiler,
+    vendor: { semaphore: options.semaphore ?? 8 },
+    dispatch: () => undefined,
+    conversate: async () => {
+      throw new Error(
+        "generateDeterministic reached an LLM call — the deterministic path must not.",
+      );
+    },
+    // biome-ignore lint: a structural stub of IAutoViewAgentContext's deterministic surface
+  } as never;
+
+  const scaffolded = await orchestrateAutoViewScaffold(ctx, {
+    document,
+    sdkMap,
+    sdkMapMarkdown: "# SDK Map\n\n_(deterministic)_\n",
+    productPlan,
+    productPlanMarkdown: "# Product Plan\n\n_(deterministic)_\n",
+    step: 0,
+    backend: options.backend,
+  });
+  const render = await orchestrateAutoViewRenderDeterministic(ctx, {
+    document,
+    productPlan,
+    step: 0,
+  });
+
+  return { ...scaffolded, ...render.files };
+}

package/src/index.ts

@@ -0,0 +1,30 @@
+export * from "./AutoViewAgent";
+export * from "./context/IAutoViewAgentContext";
+export * from "./fromSwagger";
+export * from "./orchestrate/orchestrateAutoView";
+export { AutoViewFrontendTemplate } from "./constants/AutoViewFrontendTemplate";
+export {
+  describeEndpointPropsShape,
+  describeRequestBodyHint,
+} from "./orchestrate/utils/describeEndpointPropsShape";
+export { describeEndpointRequestBodyShape } from "./orchestrate/utils/describeEndpointRequestBodyShape";
+export { describeEndpointResponseShape } from "./orchestrate/utils/describeEndpointResponseShape";
+export {
+  renderJsonSchema,
+  renderNamedSchema,
+} from "./orchestrate/utils/renderJsonSchema";
+export {
+  hashFrontendDependencies,
+  validateFrontendTypecheck,
+} from "./orchestrate/utils/validateFrontendTypecheck";
+export type {
+  ITypecheckDiagnostic,
+  IValidateFrontendTypecheckResult,
+} from "./orchestrate/utils/validateFrontendTypecheck";
+export { auditFrontendRuntime } from "./orchestrate/utils/auditFrontendRuntime";
+export type {
+  IAuditFrontendRuntimeResult,
+  IRuntimeAuditDiagnostic,
+} from "./orchestrate/utils/auditFrontendRuntime";
+export { loadShoppingFixture } from "./orchestrate/utils/loadShoppingFixture";
+export type { IShoppingFixture } from "./orchestrate/utils/loadShoppingFixture";