@autoview/cli 0.1.0

package/src/agent/verifyAgentTasks.ts

@@ -0,0 +1,171 @@
+import { OpenApi } from "@typia/interface";
+
+import { buildToolSurface, IAgentTool } from "./toolSurface";
+
+/**
+ * Behavioral verification of an agent tool surface — the trust layer.
+ *
+ * The consumability report proves the surface is *structurally* navigable
+ * (every id has a producer). This proves it *behaviorally*: a real agent, given
+ * the tools, completes named tasks end-to-end against the live backend. It is
+ * how "the API works for an agent" is demonstrated rather than asserted — the
+ * agent analogue of the frontend's workflow verifier.
+ *
+ * The deterministic parts (tool conversion + HTTP execution) are pure and
+ * unit-tested; the agent loop is driven by a configurable model (the operator's
+ * choice via env / opts), since which model an API's agents will use is the
+ * operator's call, not ours.
+ */
+
+/** OpenAI / OpenRouter function-calling tool shape. */
+export interface IFunctionTool {
+  type: "function";
+  function: { name: string; description: string; parameters: object };
+}
+
+/** OpenAI function names allow only `[a-zA-Z0-9_-]` — the dotted accessor (fine
+ * for MCP) is not valid, so sanitize for the function-calling path. */
+export const functionName = (toolName: string): string =>
+  toolName.replace(/[^A-Za-z0-9_-]/g, "_");
+
+/** Convert the agent tool surface to OpenAI function-calling tools. */
+export function toFunctionTools(tools: IAgentTool[]): IFunctionTool[] {
+  return tools.map((t) => ({
+    type: "function",
+    function: {
+      name: functionName(t.name),
+      description: t.description,
+      parameters: t.inputSchema,
+    },
+  }));
+}
+
+/**
+ * Execute one tool call against a live backend: substitute path params, attach
+ * query / body, issue the HTTP request, return the response text. Pure aside
+ * from the network call — deterministic in how it maps a call to a request.
+ */
+export async function executeToolCall(
+  tools: IAgentTool[],
+  name: string,
+  args: Record<string, unknown>,
+  opts: { baseUrl: string; auth?: string },
+): Promise<{ ok: boolean; text: string }> {
+  const tool = tools.find((t) => t.name === name);
+  if (tool === undefined) return { ok: false, text: `unknown tool: ${name}` };
+  let path = tool.operation.path;
+  for (const p of tool.operation.pathParams) {
+    path = path.replace(`{${p}}`, encodeURIComponent(String(args[p] ?? "")));
+  }
+  const url = new URL(opts.baseUrl.replace(/\/$/, "") + path);
+  if (tool.operation.hasQuery && args.query && typeof args.query === "object") {
+    for (const [k, v] of Object.entries(args.query as Record<string, unknown>)) {
+      if (v !== undefined && v !== null) url.searchParams.set(k, String(v));
+    }
+  }
+  const method = tool.operation.method;
+  try {
+    const res = await fetch(url, {
+      method,
+      headers: { "content-type": "application/json", ...(opts.auth ? { authorization: opts.auth } : {}) },
+      body: ["GET", "HEAD", "DELETE"].includes(method) ? undefined : JSON.stringify(args.body ?? {}),
+    });
+    const text = await res.text();
+    return { ok: res.ok, text };
+  } catch (err) {
+    return { ok: false, text: `request failed: ${err instanceof Error ? err.message : String(err)}` };
+  }
+}
+
+export interface IAgentTask {
+  id: string;
+  prompt: string;
+  /** Optional success predicate over the agent's final answer (e.g. contains a known value). */
+  expect?: (answer: string) => boolean;
+}
+
+export interface IAgentTaskResult {
+  id: string;
+  answer: string;
+  toolCalls: string[];
+  passed: boolean | null;
+}
+
+/** Minimal OpenAI-compatible client surface this verifier needs (so the SDK is injected, not imported). */
+export interface IChatClient {
+  chat: {
+    completions: {
+      create(req: unknown): Promise<{
+        choices: Array<{
+          message: {
+            content: string | null;
+            tool_calls?: Array<{ id: string; function: { name: string; arguments: string } }>;
+          };
+        }>;
+      }>;
+    };
+  };
+}
+
+/**
+ * Run the agent through each task against the tool surface + backend. The chat
+ * client and model are injected by the caller (configurable, e.g. from `.env`).
+ */
+export async function verifyAgentTasks(
+  document: OpenApi.IDocument,
+  opts: {
+    client: IChatClient;
+    model: string;
+    baseUrl: string;
+    auth?: string;
+    tasks: IAgentTask[];
+    maxTurns?: number;
+  },
+): Promise<IAgentTaskResult[]> {
+  const tools = buildToolSurface(document);
+  const fnTools = toFunctionTools(tools);
+  // function-calling sanitizes dotted names → map the sanitized name the model
+  // calls back to the real tool for execution.
+  const byFnName = new Map(tools.map((t) => [functionName(t.name), t.name]));
+  const maxTurns = opts.maxTurns ?? 10;
+  const results: IAgentTaskResult[] = [];
+
+  for (const task of opts.tasks) {
+    const messages: Array<Record<string, unknown>> = [
+      { role: "system", content: "You are an API agent. Use the provided tools to complete the task, then reply in plain text with the answer. Never ask the user questions." },
+      { role: "user", content: task.prompt },
+    ];
+    const toolCalls: string[] = [];
+    let answer = "(no answer)";
+    for (let turn = 0; turn < maxTurns; turn++) {
+      const resp = await opts.client.chat.completions.create({
+        model: opts.model,
+        messages,
+        tools: fnTools,
+        tool_choice: "auto",
+        temperature: 0,
+      });
+      const msg = resp.choices[0]!.message;
+      messages.push(msg as Record<string, unknown>);
+      if (msg.tool_calls === undefined || msg.tool_calls.length === 0) {
+        answer = msg.content ?? "";
+        break;
+      }
+      for (const tc of msg.tool_calls) {
+        let args: Record<string, unknown> = {};
+        try { args = JSON.parse(tc.function.arguments || "{}"); } catch { /* keep {} */ }
+        const realName = byFnName.get(tc.function.name) ?? tc.function.name;
+        const result = await executeToolCall(tools, realName, args, { baseUrl: opts.baseUrl, auth: opts.auth });
+        toolCalls.push(realName);
+        messages.push({ role: "tool", tool_call_id: tc.id, content: result.text.slice(0, 2500) });
+      }
+    }
+    results.push({
+      id: task.id,
+      answer,
+      toolCalls,
+      passed: task.expect ? task.expect(answer) : null,
+    });
+  }
+  return results;
+}

package/src/cli/main.ts

@@ -0,0 +1,363 @@
+#!/usr/bin/env node
+import { IAgenticaVendor } from "@agentica/core";
+import fs from "fs/promises";
+import OpenAI from "openai";
+import path from "path";
+
+import { AutoViewAgent } from "../AutoViewAgent";
+import { generateDeterministic } from "../generateDeterministic";
+import { emitMcpServer } from "../agent/emitMcpServer";
+import { emitConsumabilityReport } from "../agent/emitReport";
+import { extractBackendFromSwaggerFile, fromSwaggerFile } from "../fromSwagger";
+import { renderPreviewHtml } from "../preview/renderPreview";
+
+interface ICliOptions {
+  swaggerPath: string;
+  outDir: string;
+  model: string;
+  apiKey: string;
+  baseURL?: string;
+  designTheme?: string;
+  semaphore?: number;
+  /**
+   * Explicit `--backend <url>` flag value. `undefined` when not given so the
+   * CLI can fall back to the swagger's `servers[0].url` and then to simulator
+   * mode. Empty string means the user passed `--backend ""` which counts as
+   * "force simulator mode".
+   */
+  backendOverride: string | undefined;
+  /** Opt into the Phase 6 Playwright runtime audit. Defaults to false. */
+  runtimeAudit: boolean;
+  /** Opt into workflow verification (`--verify`). Defaults to false. */
+  verify: boolean;
+  /**
+   * `--preview`: LLM-free READ-layer explorer. Skips the whole generation
+   * pipeline (and the --model / --api-key requirement), parses the swagger, and
+   * writes a single self-contained `preview.html` so the operator can inspect
+   * how AutoView read their swagger before paying for a full run.
+   */
+  preview: boolean;
+  /**
+   * `--emit mcp`: deterministic, LLM-free. Instead of the frontend, generate a
+   * runnable MCP server (agent tool surface) from the swagger and stop.
+   */
+  emit?: string;
+  /**
+   * `--no-llm`: generate the frontend deterministically, with NO model/key. The
+   * render is already deterministic; this skips the optional LLM typecheck-
+   * recovery / runtime-audit / review passes the full agent would run.
+   */
+  noLlm: boolean;
+  /** Path globs to KEEP (comma-separated `--include`). Slices a large swagger. */
+  include?: string[];
+  /** Path globs to DROP (comma-separated `--exclude`). */
+  exclude?: string[];
+}
+
+/**
+ * Tiny argv parser — supports `--key value` and `--key=value`. Avoids pulling a
+ * CLI parsing library so the package install stays lean.
+ */
+function parseArgs(argv: string[]): ICliOptions {
+  const positional: string[] = [];
+  const flags = new Map<string, string>();
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]!;
+    if (arg.startsWith("--")) {
+      const eq = arg.indexOf("=");
+      if (eq !== -1) {
+        flags.set(arg.slice(2, eq), arg.slice(eq + 1));
+      } else {
+        const key = arg.slice(2);
+        const next = argv[i + 1];
+        if (next !== undefined && !next.startsWith("--")) {
+          flags.set(key, next);
+          i++;
+        } else {
+          flags.set(key, "true");
+        }
+      }
+    } else {
+      positional.push(arg);
+    }
+  }
+  const swaggerPath = positional[0];
+  const outDir = flags.get("out") ?? "./frontend";
+  const model = flags.get("model") ?? process.env.AUTOVIEW_MODEL ?? "";
+  const apiKey =
+    flags.get("api-key") ??
+    process.env.AUTOVIEW_API_KEY ??
+    process.env.OPENAI_API_KEY ??
+    "";
+  const baseURL = flags.get("base-url") ?? process.env.AUTOVIEW_BASE_URL;
+  const emit = flags.get("emit");
+  const designTheme = flags.get("design-theme");
+  const semaphoreRaw = flags.get("semaphore");
+  const semaphore =
+    semaphoreRaw !== undefined ? parseInt(semaphoreRaw, 10) : undefined;
+  const backendOverride = flags.get("backend") ?? process.env.AUTOVIEW_BACKEND;
+  const preview = flags.get("preview") === "true";
+  const noLlm = flags.get("no-llm") === "true";
+  const splitGlobs = (raw: string | undefined): string[] | undefined => {
+    if (raw === undefined) return undefined;
+    const parts = raw
+      .split(",")
+      .map((s) => s.trim())
+      .filter((s) => s.length > 0);
+    return parts.length > 0 ? parts : undefined;
+  };
+  const include = splitGlobs(flags.get("include"));
+  const exclude = splitGlobs(flags.get("exclude"));
+  if (swaggerPath === undefined) {
+    throw new Error(usage("Missing positional argument: <swagger.json>"));
+  }
+  // --preview, --emit, and --no-llm are LLM-free, so model / api-key are optional.
+  const llmFree = preview || emit !== undefined || noLlm;
+  if (!llmFree && model === "") {
+    throw new Error(
+      usage(
+        "Missing --model (or AUTOVIEW_MODEL env). Example: --model openai/gpt-5.4",
+      ),
+    );
+  }
+  if (!llmFree && apiKey === "") {
+    throw new Error(
+      usage("Missing --api-key (or AUTOVIEW_API_KEY / OPENAI_API_KEY env)."),
+    );
+  }
+  const runtimeAuditRaw =
+    flags.get("runtime-audit") ?? process.env.AUTOVIEW_RUNTIME_AUDIT ?? "";
+  const runtimeAudit =
+    runtimeAuditRaw === "true" ||
+    runtimeAuditRaw === "1" ||
+    runtimeAuditRaw === "yes";
+  const verify = flags.get("verify") === "true";
+  return {
+    swaggerPath,
+    outDir,
+    model,
+    apiKey,
+    baseURL,
+    designTheme,
+    semaphore: Number.isFinite(semaphore) ? semaphore : undefined,
+    backendOverride,
+    runtimeAudit,
+    verify,
+    preview,
+    emit,
+    noLlm,
+    include,
+    exclude,
+  };
+}
+
+function usage(extra?: string): string {
+  const head = extra !== undefined ? `${extra}\n\n` : "";
+  return (
+    head +
+    [
+      "Usage: autoview <swagger.json> --model <name> --api-key <key> [options]",
+      "",
+      "Options:",
+      "  --out <dir>           Output directory (default: ./frontend)",
+      "  --model <name>        LLM model identifier, e.g. openai/gpt-5.4",
+      "  --api-key <key>       Vendor API key (or AUTOVIEW_API_KEY / OPENAI_API_KEY env)",
+      "  --base-url <url>      OpenAI-compatible endpoint (default: OpenAI)",
+      "  --design-theme <txt>  Optional design direction",
+      "  --semaphore <n>       Render concurrency cap (default: 8)",
+      "  --backend <url>       Live backend host for connection.ts (simulate:false).",
+      "                        Auto-extracted from swagger servers[] when omitted.",
+      '                        Pass --backend="" to force simulator mode.',
+      "  --runtime-audit       Opt into Phase 6 Playwright runtime audit (adds",
+      "                        ~10-20min; installs Playwright + Chromium).",
+      "  --verify              Verify the generated app in a real headless browser:",
+      "                        walk the user workflows (list → detail, forms) and",
+      "                        write wiki/verification.md. Installs Chromium.",
+      "  --no-llm              Generate the frontend deterministically — NO model",
+      "                        / api-key. The render is deterministic; this skips",
+      "                        the optional LLM typecheck-recovery / audit / review.",
+      "  --preview             LLM-free: parse the swagger and write preview.html",
+      "                        (endpoint tree + schemas + READ report). No --model",
+      "                        / --api-key needed. Inspect before a full run.",
+      "  --emit mcp            LLM-free: generate a runnable MCP server (agent tool",
+      "                        surface — read/write annotated, producer hints) instead",
+      "                        of the frontend. Set API_HOST to run it.",
+      "  --emit report         LLM-free: write consumability-report.md — can this API",
+      "                        be driven as a product? (navigable graph + orphan ids).",
+      "  --include <globs>     Comma-separated path globs to KEEP — slice a large",
+      '                        swagger, e.g. --include "shoppings/customers/**".',
+      "  --exclude <globs>     Comma-separated path globs to DROP after include,",
+      '                        e.g. --exclude "**/monitors/**".',
+      "",
+      "Environment fallbacks:",
+      "  AUTOVIEW_MODEL, AUTOVIEW_API_KEY (or OPENAI_API_KEY),",
+      "  AUTOVIEW_BASE_URL, AUTOVIEW_BACKEND, AUTOVIEW_RUNTIME_AUDIT",
+    ].join("\n")
+  );
+}
+
+async function writeAll(
+  outDir: string,
+  files: Record<string, string>,
+): Promise<void> {
+  await fs.mkdir(outDir, { recursive: true });
+  for (const [relative, content] of Object.entries(files)) {
+    const full = path.join(outDir, relative);
+    await fs.mkdir(path.dirname(full), { recursive: true });
+    await fs.writeFile(full, content, "utf-8");
+  }
+}
+
+async function main(): Promise<void> {
+  const options = parseArgs(process.argv.slice(2));
+  const document = await fromSwaggerFile(options.swaggerPath);
+
+  // --preview: LLM-free READ-layer explorer. Parse, render a self-contained
+  // HTML, and stop — no model call, no generation.
+  if (options.preview) {
+    const serverUrl =
+      (await extractBackendFromSwaggerFile(options.swaggerPath))?.host ?? null;
+    const html = renderPreviewHtml(
+      document,
+      {
+        title: document.info?.title ?? "API",
+        version: document.info?.version ?? "—",
+        serverUrl,
+      },
+      { include: options.include, exclude: options.exclude },
+    );
+    await fs.mkdir(options.outDir, { recursive: true });
+    const out = path.join(options.outDir, "preview.html");
+    await fs.writeFile(out, html, "utf-8");
+    // eslint-disable-next-line no-console
+    console.log(
+      `[autoview] preview written to ${out} (LLM-free). Open it in a browser.`,
+    );
+    return;
+  }
+
+  // --emit mcp: LLM-free. Generate a runnable MCP server (agent tool surface)
+  // from the swagger and stop. No frontend, no model call.
+  if (options.emit === "mcp") {
+    const host =
+      options.backendOverride ??
+      (await extractBackendFromSwaggerFile(options.swaggerPath))?.host ??
+      null;
+    const files = emitMcpServer(document, {
+      backend: host,
+      title: document.info?.title,
+    });
+    await writeAll(options.outDir, files);
+    // eslint-disable-next-line no-console
+    console.log(
+      `[autoview] MCP server written to ${options.outDir} (LLM-free). cd in, npm install, set API_HOST, npm start.`,
+    );
+    return;
+  }
+  // --emit report: LLM-free. Write a consumability report (can this API be
+  // driven as a product? navigable graph + orphan inputs) and stop.
+  if (options.emit === "report") {
+    const md = emitConsumabilityReport(document);
+    await fs.mkdir(options.outDir, { recursive: true });
+    const out = path.join(options.outDir, "consumability-report.md");
+    await fs.writeFile(out, md, "utf-8");
+    // eslint-disable-next-line no-console
+    console.log(`[autoview] consumability report written to ${out} (LLM-free).`);
+    return;
+  }
+  if (options.emit !== undefined) {
+    throw new Error(usage(`Unknown --emit target "${options.emit}". Supported: mcp, report.`));
+  }
+
+  // Resolve backend host: explicit --backend flag wins; otherwise read the
+  // swagger's `servers[0].url` so the generated frontend defaults to
+  // `simulate:false` against the real backend. `--backend=""` is treated as
+  // "force simulator mode" — the operator can opt out without editing files.
+  const backend: { host: string } | null = await (async () => {
+    if (options.backendOverride !== undefined) {
+      return options.backendOverride.length > 0
+        ? { host: options.backendOverride }
+        : null;
+    }
+    return extractBackendFromSwaggerFile(options.swaggerPath);
+  })();
+  // eslint-disable-next-line no-console
+  console.log(
+    backend === null
+      ? `[autoview] backend: (none) — frontend will boot in simulator mode (typia-random data)`
+      : `[autoview] backend: ${backend.host} — frontend will boot in live mode (simulate:false)`,
+  );
+
+  // --no-llm: deterministic frontend, no model/key. Skips the agent's optional
+  // LLM polish (typecheck-recovery / runtime-audit / review).
+  if (options.noLlm) {
+    const files = await generateDeterministic(document, {
+      backend: backend ?? { host: null },
+      filter: { include: options.include, exclude: options.exclude },
+      semaphore: options.semaphore,
+    });
+    await writeAll(options.outDir, files);
+    // eslint-disable-next-line no-console
+    console.log(
+      `[autoview] wrote ${Object.keys(files).length} files to ${options.outDir} (deterministic, LLM-free).`,
+    );
+    return;
+  }
+
+  const openai = new OpenAI({
+    apiKey: options.apiKey,
+    baseURL: options.baseURL,
+  });
+  const vendor: IAgenticaVendor = {
+    model: options.model,
+    api: openai,
+  };
+
+  const agent = new AutoViewAgent({
+    document,
+    vendor,
+    designTheme: options.designTheme,
+    semaphore: options.semaphore,
+    backend,
+    runtimeAudit: options.runtimeAudit,
+    verify: options.verify,
+    include: options.include,
+    exclude: options.exclude,
+    onEvent: (event) => {
+      const summary = (() => {
+        switch (event.type) {
+          case "autoViewStart":
+            return `start (source=${event.source})`;
+          case "autoViewSdkStudy":
+            return `sdk-study (${event.resources} resources, ${event.actors} actors)`;
+          case "autoViewProductPlan":
+            return `product-plan (${event.pages} pages)`;
+          case "autoViewScaffold":
+            return `scaffold (${event.files} files)`;
+          case "autoViewRenderPage":
+            return `render ${event.completed}/${event.total} → ${event.pagePath} (${event.ok ? "ok" : "failed"})`;
+          case "autoViewReview":
+            return `review (${event.broken} broken, ${event.recovered} recovered)`;
+          case "autoViewComplete":
+            return `complete (${event.pages} pages, ${Object.keys(event.files).length} files, ${(event.elapsed / 1000).toFixed(1)}s)`;
+        }
+      })();
+      // eslint-disable-next-line no-console
+      console.log(`[autoview] ${summary}`);
+    },
+  });
+
+  const { files } = await agent.run();
+  await writeAll(options.outDir, files);
+  // eslint-disable-next-line no-console
+  console.log(
+    `[autoview] wrote ${Object.keys(files).length} files to ${options.outDir}`,
+  );
+}
+
+main().catch((err: unknown) => {
+  const message = err instanceof Error ? err.message : String(err);
+  // eslint-disable-next-line no-console
+  console.error(`\n[autoview] ${message}`);
+  process.exit(1);
+});

package/src/compiler/AutoViewInterfaceCompiler.ts

@@ -0,0 +1,69 @@
+import { NestiaMigrateApplication } from "@nestia/migrate";
+import { OpenApi } from "@typia/interface";
+
+import { IAutoBeInterfaceCompiler } from "../typings";
+import { ArrayUtil } from "../utils";
+import { normalizeForNestia } from "../utils/normalizeForNestia";
+
+/**
+ * Self-defined interface compiler — Step 3 of the AutoBE-independence track.
+ *
+ * Replaces `@autobe/compiler`'s `AutoBeCompiler`. AutoView only ever calls
+ * `compiler.interface.write(document, exclude)` to materialize the typed SDK it
+ * shows the LLM (SDK Study) and bundles into the scaffold, so only that surface
+ * is reproduced here. TypeScript only — the Java path and the realize/test
+ * listener plumbing AutoBE carries are dropped.
+ *
+ * Under the hood this is the same `@nestia/migrate` call the AutoBE compiler
+ * makes; `@nestia/migrate` is a samchon-ecosystem package, not an AutoBE one,
+ * so depending on it directly keeps the package free of `@autobe/*`. Swapping
+ * NestiaMigrate for a standard-OpenAPI SDK generator (the "Nestia tphase-out"
+ * from the design meeting) is a later iteration that happens behind this seam.
+ *
+ * Prettier beautification (AutoBE's `FilePrinter.beautify`) is intentionally
+ * skipped: it pulled in prettier + sort-imports + jsdoc plugins purely for
+ * cosmetics, and the render phase reads SDK *types*, not formatting.
+ */
+export class AutoViewInterfaceCompiler implements IAutoBeInterfaceCompiler {
+  public async write(
+    document: OpenApi.IDocument,
+    options:
+      | string[]
+      | {
+          language: "typescript" | "java";
+          exclude: string[];
+        },
+  ): Promise<Record<string, string>> {
+    const exclude: string[] = Array.isArray(options)
+      ? options
+      : options.exclude;
+    // swagger 직접 nestia — invert/transform AST 왕복 없음, query 보존.
+    // normalizeForNestia: nestia mis-handles two real-world shapes — a route
+    // whose query has >1 object param (Apideck list endpoints) is dropped, and a
+    // GET/HEAD carrying a requestBody (Notion's comments/users) yields an SDK
+    // function its own fetcher rejects. Normalizing both keeps the SDK in lockstep
+    // with the screen plan, which applies the same pass via toEndpoints.
+    const migrate: NestiaMigrateApplication = new NestiaMigrateApplication(
+      normalizeForNestia(document),
+    );
+    const files: Record<string, string> = migrate.nest({
+      keyword: true,
+      simulate: true,
+      e2e: true,
+      author: {
+        tag: "autoview",
+        value: "Generated by AutoView - https://github.com/wrtnlabs/AutoView-Legacy",
+      },
+    });
+    return Object.fromEntries([
+      ...(await ArrayUtil.asyncMap(
+        Object.entries(files).filter(([key]) => exclude.includes(key) === false),
+        async ([key, value]) => [key, value] as const,
+      )),
+      [
+        "packages/api/swagger.json",
+        JSON.stringify(migrate.getData().document(), null, 2),
+      ],
+    ]);
+  }
+}