@autoview/cli 0.1.0

package/src/verify/runWorkflows.ts

@@ -0,0 +1,403 @@
+import { type ChildProcess, spawn } from "child_process";
+import { createHash } from "crypto";
+import fs from "fs/promises";
+import { createServer } from "net";
+import os from "os";
+import path from "path";
+
+import {
+  ensureCachedNodeModules,
+  tryLinkNodeModules,
+} from "../orchestrate/utils/cacheNodeModules";
+import { IWorkflow } from "./workflows";
+
+/**
+ * Verification execution layer — drive the derived user workflows in a real
+ * headless browser and report, per step, whether the expected outcome actually
+ * happened (data rendered, navigation moved), not merely that nothing errored.
+ *
+ * Boots the assembled frontend under `next dev` in simulator mode (no live
+ * backend needed — the SDK serves typia-random data so every render path runs),
+ * launches Chromium via Playwright, and walks each workflow's steps with
+ * positive DOM assertions. Returns a structured report the operator (or a fix
+ * loop) reads to know exactly which journey/step failed and why.
+ */
+const PLAYWRIGHT_DEP = "playwright@^1.50.0";
+const NEXT_DEV_BOOT_TIMEOUT_MS = 120_000;
+
+export interface IWorkflowStepResult {
+  label: string;
+  expect: string;
+  ok: boolean;
+  /** What was found — evidence for the report (row count, error text, …). */
+  detail: string;
+}
+
+export interface IWorkflowResult {
+  id: string;
+  title: string;
+  resource: string;
+  ok: boolean;
+  steps: IWorkflowStepResult[];
+}
+
+export interface IRunWorkflowsResult {
+  workflows: IWorkflowResult[];
+  /** workflows that passed every step. */
+  passed: number;
+  /** workflows with at least one failing step. */
+  failed: number;
+  markdown: string;
+  elapsedMs: number;
+}
+
+export async function runWorkflows(
+  files: Record<string, string>,
+  workflows: IWorkflow[],
+): Promise<IRunWorkflowsResult> {
+  const startedAt = Date.now();
+  const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "autoview-verify-"));
+  let nextDev: ChildProcess | null = null;
+  try {
+    await writeFiles(tempDir, files);
+    await installEverything(tempDir, files["package.json"]);
+
+    const port = await getFreePort();
+    nextDev = await startNextDev(tempDir, port);
+    const baseUrl = `http://127.0.0.1:${port}`;
+
+    await writeFile(tempDir, "scripts/.verify-runner.cjs", buildRunnerScript());
+    const stdout = await spawnCommand(
+      "node",
+      [
+        path.join(tempDir, "scripts", ".verify-runner.cjs"),
+        JSON.stringify(workflows),
+        baseUrl,
+      ],
+      { cwd: tempDir },
+    );
+
+    const results = parseResults(stdout, workflows);
+    const passed = results.filter((w) => w.ok).length;
+    return {
+      workflows: results,
+      passed,
+      failed: results.length - passed,
+      markdown: renderMarkdown(results),
+      elapsedMs: Date.now() - startedAt,
+    };
+  } finally {
+    if (nextDev !== null) await killNextDev(nextDev);
+    await fs.rm(tempDir, { recursive: true, force: true }).catch(() => {});
+  }
+}
+
+/* -------------------------------------------------------------------------- */
+/* runner script (runs inside the temp dir against the installed playwright)  */
+/* -------------------------------------------------------------------------- */
+
+function buildRunnerScript(): string {
+  // CJS, executed in the temp dir. For each workflow step it performs the
+  // action, lets the client fetch settle, then asserts the POSITIVE outcome for
+  // the expected page kind. A `console.error` / uncaught exception during a
+  // step fails it too. Emits a JSON array of workflow results to stdout.
+  return String.raw`"use strict";
+const { chromium } = require("playwright");
+
+const SETTLE_MS = 4500;
+const VISIT_TIMEOUT = 120000;
+
+async function assertExpect(page, expect) {
+  // returns { ok, detail }
+  const errorCard = await page.locator('text=/Couldn.t load/i').count();
+  if (expect === "landing") {
+    const links = await page.locator('main a[href]').count();
+    return { ok: links > 0, detail: links + " links" };
+  }
+  if (expect === "table") {
+    const rows = await page.locator('table tbody tr').count();
+    const empty = await page.locator('text=/came back empty|no .* yet|nested collection/i').count();
+    if (errorCard > 0) return { ok: false, detail: "error card shown" };
+    if (rows > 0) return { ok: true, detail: rows + " rows" };
+    if (empty > 0) return { ok: true, detail: "empty state" };
+    return { ok: false, detail: "no rows, no empty state, no error (stuck?)" };
+  }
+  if (expect === "detail") {
+    const fields = await page.locator('dt').count();
+    if (errorCard > 0) return { ok: false, detail: "error card shown" };
+    if (fields > 0) return { ok: true, detail: fields + " fields" };
+    return { ok: false, detail: "no fields rendered" };
+  }
+  if (expect === "form") {
+    const inputs = await page.locator('input, select, textarea, button[type=submit]').count();
+    return { ok: inputs > 0, detail: inputs + " inputs" };
+  }
+  return { ok: false, detail: "unknown expect" };
+}
+
+(async () => {
+  const workflows = JSON.parse(process.argv[2]);
+  const baseUrl = process.argv[3];
+  const browser = await chromium.launch();
+  const ctx = await browser.newContext({ viewport: { width: 1280, height: 900 } });
+
+  // Pre-warm: the first SDK-backed page triggers a one-time on-demand compile of
+  // the generated SDK module graph, which on a large API can exceed a normal
+  // navigation timeout (~100s+). That is a dev-server cost, not an app defect —
+  // warm it once up front (generous budget) so per-workflow navigations are
+  // fast and never false-fail on a cold compile.
+  let warmPath = null;
+  for (const wf of workflows) {
+    for (const s of wf.steps) {
+      if (s.action.type === "visit" && s.action.path !== "/") { warmPath = s.action.path; break; }
+    }
+    if (warmPath) break;
+  }
+  if (warmPath) {
+    const wp = await ctx.newPage();
+    try { await wp.goto(baseUrl + warmPath, { waitUntil: "domcontentloaded", timeout: 300000 }); } catch (e) {}
+    await wp.waitForTimeout(2000).catch(() => {});
+    await wp.close().catch(() => {});
+  }
+
+  const out = [];
+  for (const wf of workflows) {
+    const page = await ctx.newPage();
+    let pageError = null;
+    page.on("pageerror", (e) => { pageError = e.message; });
+    page.on("console", (m) => { if (m.type() === "error" && !pageError) pageError = "console: " + m.text(); });
+    const steps = [];
+    let wfOk = true;
+    for (const step of wf.steps) {
+      let res = { ok: false, detail: "" };
+      try {
+        const a = step.action;
+        if (a.type === "visit") {
+          await page.goto(baseUrl + a.path, { waitUntil: "domcontentloaded", timeout: VISIT_TIMEOUT });
+        } else if (a.type === "clickFirstRow") {
+          const view = page.locator('table tbody tr a:has-text("View")').first();
+          if (await view.count() === 0) {
+            // No row to open. An empty list is the app behaving correctly (the
+            // simulator simply returned zero rows), not a failure — skip the
+            // detail step. A real failure (error card / stuck page) is caught by
+            // the preceding list step.
+            const empty = await page.locator('text=/came back empty|no .* yet|nested collection/i').count();
+            const detail = empty > 0 ? "skipped — list is empty" : "no row to open (list did not render)";
+            steps.push({ label: step.label, expect: step.expect, ok: empty > 0, detail });
+            if (empty === 0) wfOk = false;
+            pageError = null;
+            continue;
+          }
+          await view.click();
+        } else if (a.type === "clickLink") {
+          await page.locator('a:has-text("' + a.text + '")').first().click();
+        }
+        await page.waitForTimeout(SETTLE_MS);
+        res = await assertExpect(page, step.expect);
+        if (pageError) { res = { ok: false, detail: "runtime error: " + String(pageError).slice(0, 120) }; }
+      } catch (e) {
+        res = { ok: false, detail: "step threw: " + String(e && e.message ? e.message : e).slice(0, 120) };
+      }
+      steps.push({ label: step.label, expect: step.expect, ok: res.ok, detail: res.detail });
+      if (!res.ok) wfOk = false;
+      pageError = null;
+    }
+    out.push({ id: wf.id, title: wf.title, resource: wf.resource, ok: wfOk, steps });
+    await page.close().catch(() => {});
+  }
+  await browser.close().catch(() => {});
+  process.stdout.write(JSON.stringify(out));
+})().catch((err) => {
+  process.stderr.write(err && err.stack ? err.stack : String(err));
+  process.exit(1);
+});
+`;
+}
+
+function parseResults(
+  stdout: string,
+  workflows: IWorkflow[],
+): IWorkflowResult[] {
+  const trimmed = stdout.trim();
+  if (trimmed.length === 0) {
+    return workflows.map((w) => ({
+      id: w.id,
+      title: w.title,
+      resource: w.resource,
+      ok: false,
+      steps: w.steps.map((s) => ({
+        label: s.label,
+        expect: s.expect,
+        ok: false,
+        detail: "no runner output",
+      })),
+    }));
+  }
+  try {
+    const parsed: unknown = JSON.parse(trimmed);
+    if (!Array.isArray(parsed)) throw new Error("not an array");
+    return parsed as IWorkflowResult[];
+  } catch {
+    return workflows.map((w) => ({
+      id: w.id,
+      title: w.title,
+      resource: w.resource,
+      ok: false,
+      steps: [{ label: "runner", expect: "-", ok: false, detail: "unparseable runner output" }],
+    }));
+  }
+}
+
+function renderMarkdown(results: IWorkflowResult[]): string {
+  const passed = results.filter((w) => w.ok).length;
+  const lines: string[] = [
+    "# Workflow verification",
+    "",
+    `Ran **${results.length}** user workflow(s) in a real headless browser (simulator mode).`,
+    `**${passed} passed**, **${results.length - passed} failed**.`,
+    "",
+  ];
+  for (const wf of results) {
+    lines.push(`## ${wf.ok ? "✅" : "❌"} ${wf.title}`, "");
+    for (const step of wf.steps) {
+      lines.push(`- ${step.ok ? "✓" : "✗"} ${step.label} → expect \`${step.expect}\` — ${step.detail}`);
+    }
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+
+/* -------------------------------------------------------------------------- */
+/* dev-server lifecycle (mirrors auditFrontendRuntime's proven boot)          */
+/* -------------------------------------------------------------------------- */
+
+async function installEverything(
+  root: string,
+  packageJson: string | undefined,
+): Promise<void> {
+  const hash =
+    packageJson !== undefined
+      ? createHash("sha256").update(packageJson).digest("hex").slice(0, 16)
+      : "no-package-json";
+  const cached =
+    packageJson !== undefined
+      ? await ensureCachedNodeModules({
+          cacheNamespace: "runtime-audit",
+          hash,
+          packageJson,
+          extraDeps: [PLAYWRIGHT_DEP],
+        })
+      : null;
+  if (cached !== null && (await tryLinkNodeModules(root, cached))) {
+    await installChromium(root);
+    return;
+  }
+  await spawnCommand("npm", ["install", "--silent", "--no-audit", "--no-fund"], { cwd: root });
+  await spawnCommand(
+    "npm",
+    ["install", "--silent", "--no-audit", "--no-fund", "--no-save", PLAYWRIGHT_DEP],
+    { cwd: root },
+  );
+  await installChromium(root);
+}
+
+async function installChromium(root: string): Promise<void> {
+  await spawnCommand(path.join(root, "node_modules", ".bin", "playwright"), ["install", "chromium"], {
+    cwd: root,
+  });
+}
+
+async function writeFiles(root: string, files: Record<string, string>): Promise<void> {
+  for (const [relative, content] of Object.entries(files)) {
+    await writeFile(root, relative, content);
+  }
+}
+
+async function writeFile(root: string, relative: string, content: string): Promise<void> {
+  const full = path.join(root, relative);
+  await fs.mkdir(path.dirname(full), { recursive: true });
+  await fs.writeFile(full, content, "utf-8");
+}
+
+function getFreePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const server = createServer();
+    server.listen(0, "127.0.0.1", () => {
+      const addr = server.address();
+      if (addr === null || typeof addr === "string") {
+        server.close();
+        reject(new Error("Failed to allocate a free port"));
+        return;
+      }
+      const port = addr.port;
+      server.close(() => resolve(port));
+    });
+    server.on("error", reject);
+  });
+}
+
+function startNextDev(root: string, port: number): Promise<ChildProcess> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(
+      "node",
+      [path.join(root, "node_modules", "next", "dist", "bin", "next"), "dev"],
+      {
+        cwd: root,
+        env: {
+          ...process.env,
+          PORT: String(port),
+          NEXT_PUBLIC_API_SIMULATE: "true",
+          NEXT_PUBLIC_API_TOKEN: "Bearer preview",
+        },
+        stdio: ["ignore", "pipe", "pipe"],
+      },
+    );
+    let buffer = "";
+    let settled = false;
+    const onData = (chunk: Buffer): void => {
+      buffer += chunk.toString("utf-8");
+      if (!settled && buffer.includes("Ready in")) {
+        settled = true;
+        child.stdout?.off("data", onData);
+        child.stderr?.off("data", onData);
+        resolve(child);
+      }
+    };
+    child.stdout?.on("data", onData);
+    child.stderr?.on("data", onData);
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      child.kill("SIGTERM");
+      reject(new Error(`next dev did not become ready within ${NEXT_DEV_BOOT_TIMEOUT_MS}ms:\n${buffer.slice(-800)}`));
+    }, NEXT_DEV_BOOT_TIMEOUT_MS);
+    child.on("exit", (code) => {
+      clearTimeout(timer);
+      if (settled) return;
+      settled = true;
+      reject(new Error(`next dev exited with code ${code} before ready:\n${buffer.slice(-800)}`));
+    });
+  });
+}
+
+async function killNextDev(child: ChildProcess): Promise<void> {
+  if (child.exitCode !== null) return;
+  child.kill("SIGTERM");
+  await new Promise((r) => setTimeout(r, 1500));
+  if (child.exitCode === null) child.kill("SIGKILL");
+}
+
+function spawnCommand(cmd: string, args: string[], options: { cwd: string }): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, { cwd: options.cwd, stdio: "pipe" });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (c) => (stdout += c.toString("utf-8")));
+    child.stderr.on("data", (c) => (stderr += c.toString("utf-8")));
+    child.on("error", (err) => reject(new Error(`Failed to spawn \`${cmd}\`: ${err.message}`)));
+    child.on("close", (code) => {
+      if (code === 0) resolve(stdout);
+      else reject(new Error(`\`${cmd} ${args.slice(0, 2).join(" ")}…\` exited ${code}${stderr ? `:\n${stderr.slice(-1200)}` : ""}`));
+    });
+  });
+}

package/src/verify/workflows.test.ts

@@ -0,0 +1,117 @@
+import { OpenApiConverter } from "@typia/utils";
+import { describe, expect, it } from "vitest";
+
+import { buildDeterministicPlan } from "../orchestrate/utils/buildDeterministicPlan";
+import { deriveWorkflows } from "./workflows";
+
+function doc(paths: Record<string, unknown>, schemas: Record<string, unknown> = {}) {
+  return OpenApiConverter.upgradeDocument({
+    openapi: "3.0.0",
+    info: { title: "t", version: "1.0.0" },
+    paths,
+    components: { schemas },
+  } as never);
+}
+
+const ok = { 200: { description: "ok" } };
+const fixture = doc(
+  {
+    "/pets": {
+      get: {
+        operationId: "index",
+        responses: {
+          200: {
+            description: "ok",
+            content: {
+              "application/json": {
+                schema: { type: "array", items: { $ref: "#/components/schemas/Pet" } },
+              },
+            },
+          },
+        },
+      },
+    },
+    "/pets/{petId}": {
+      get: {
+        operationId: "at",
+        parameters: [{ name: "petId", in: "path", required: true, schema: { type: "string" } }],
+        responses: {
+          200: { description: "ok", content: { "application/json": { schema: { $ref: "#/components/schemas/Pet" } } } },
+        },
+      },
+    },
+  },
+  { Pet: { type: "object", properties: { id: { type: "string" }, name: { type: "string" } } } },
+);
+
+describe("deriveWorkflows", () => {
+  it("derives a home workflow plus a browse-and-open journey per resource", () => {
+    const plan = buildDeterministicPlan(fixture, "user");
+    const flows = deriveWorkflows(plan);
+
+    const home = flows.find((f) => f.id === "home")!;
+    expect(home.steps).toHaveLength(1);
+    expect(home.steps[0]!.expect).toBe("landing");
+
+    const pets = flows.find((f) => f.title === "Browse Pets")!;
+    expect(pets).toBeDefined();
+    // list step then open-a-record step (a detail screen exists)
+    expect(pets.steps.map((s) => s.expect)).toEqual(["table", "detail"]);
+    expect(pets.steps[0]!.action).toEqual({ type: "visit", path: "/pets" });
+    expect(pets.steps[1]!.action).toEqual({ type: "clickFirstRow" });
+  });
+
+  it("a list with no detail screen yields a single list step (no row click)", () => {
+    const readonly = doc({
+      "/inventory": {
+        get: {
+          operationId: "index",
+          responses: {
+            200: {
+              description: "ok",
+              content: {
+                "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/I" } } },
+              },
+            },
+          },
+        },
+      },
+    }, { I: { type: "object", properties: { count: { type: "integer" } } } });
+    const flows = deriveWorkflows(buildDeterministicPlan(readonly, "user"));
+    const inv = flows.find((f) => f.title === "Browse Inventory")!;
+    expect(inv.steps.map((s) => s.expect)).toEqual(["table"]);
+  });
+
+  it("derives a form workflow for a top-level create endpoint", () => {
+    const creatable = doc(
+      {
+        "/pets": {
+          get: {
+            operationId: "index",
+            responses: {
+              200: { description: "ok", content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/Pet" } } } } },
+            },
+          },
+          post: {
+            operationId: "create",
+            requestBody: { content: { "application/json": { schema: { $ref: "#/components/schemas/Pet" } } } },
+            responses: ok,
+          },
+        },
+      },
+      { Pet: { type: "object", properties: { name: { type: "string" } }, required: ["name"] } },
+    );
+    const flows = deriveWorkflows(buildDeterministicPlan(creatable, "user"));
+    const form = flows.find((f) => f.title.includes("form"))!;
+    expect(form).toBeDefined();
+    expect(form.steps).toHaveLength(1);
+    expect(form.steps[0]!.expect).toBe("form");
+    expect(form.steps[0]!.action).toEqual({ type: "visit", path: "/pets/new" });
+  });
+
+  it("is deterministic", () => {
+    const a = deriveWorkflows(buildDeterministicPlan(fixture, "user"));
+    const b = deriveWorkflows(buildDeterministicPlan(fixture, "user"));
+    expect(a).toEqual(b);
+  });
+});

package/src/verify/workflows.ts

@@ -0,0 +1,154 @@
+import { IAutoViewProductPlan } from "../orchestrate/structures/IAutoViewProductPlan";
+
+/**
+ * The verification layer — "정확하게 검증한다".
+ *
+ * A generated frontend that typechecks is not proven to work: a user has to be
+ * able to open it, see real data, and move through it. This module derives, from
+ * the deterministic product plan, the set of USER WORKFLOWS that a real visitor
+ * would perform — each a short journey with an explicit positive expectation at
+ * every step (the table actually rendered rows or an honest empty state; the
+ * detail actually showed fields; navigation actually moved). The execution layer
+ * ({@link ../verify/runWorkflows}) drives these in a real headless browser and
+ * reports pass/fail per step, so "it works" is demonstrated, not asserted.
+ *
+ * Pure and deterministic: same plan → same workflows, no browser needed. This is
+ * the spec of WHAT gets verified.
+ */
+
+/** What a page must be after a step — drives the runtime DOM assertion. */
+export type WorkflowExpect = "landing" | "table" | "detail" | "form";
+
+/** One user action plus the outcome it must produce. */
+export interface IWorkflowStep {
+  action:
+    | { type: "visit"; path: string }
+    | { type: "clickFirstRow" }
+    | { type: "clickLink"; text: string };
+  expect: WorkflowExpect;
+  /** Human description, shown in the report. */
+  label: string;
+}
+
+/** One end-to-end user journey through a resource. */
+export interface IWorkflow {
+  /** Stable slug (route-derived). */
+  id: string;
+  title: string;
+  /** Resource the journey covers, for grouping the report. */
+  resource: string;
+  steps: IWorkflowStep[];
+}
+
+function slug(path: string): string {
+  const cleaned = path.replace(/[^A-Za-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return cleaned.length > 0 ? cleaned : "home";
+}
+
+/** A top-level resource screen earns its own browse workflow. */
+function isTopLevelTable(screen: IAutoViewProductPlan.IScreen): boolean {
+  if (screen.depth !== undefined && screen.depth !== 1) return false;
+  if (screen.path.includes("[")) return false;
+  return screen.uiPattern === "table" || screen.uiPattern === "catalog";
+}
+
+/**
+ * Derive the user workflows to verify from the product plan.
+ *
+ * - Home: the landing hub must open and present its resource links.
+ * - Per top-level resource: visit the list (it must render a table or an honest
+ *   empty state, not an error), then open the first row's detail (it must render
+ *   the record's fields). This is the core read journey — the one a user does
+ *   first and the one that exercises data fetch + render + navigation together.
+ * - Per top-level singleton read (`/system`): visit it; the detail must render.
+ */
+export function deriveWorkflows(plan: IAutoViewProductPlan): IWorkflow[] {
+  const workflows: IWorkflow[] = [];
+  const screens = plan.screens;
+
+  const landing = screens.find((s) => s.uiPattern === "landing");
+  if (landing !== undefined) {
+    workflows.push({
+      id: "home",
+      title: "Home hub loads and links to resources",
+      resource: "",
+      steps: [
+        { action: { type: "visit", path: "/" }, expect: "landing", label: "Open home" },
+      ],
+    });
+  }
+
+  for (const screen of screens) {
+    if (isTopLevelTable(screen)) {
+      const detail = screens.find(
+        (s) => s.uiPattern === "detail" && s.path.startsWith(`${screen.path}/[`),
+      );
+      const steps: IWorkflowStep[] = [
+        {
+          action: { type: "visit", path: screen.path },
+          expect: "table",
+          label: `Open ${screen.title} list`,
+        },
+      ];
+      if (detail !== undefined) {
+        steps.push({
+          action: { type: "clickFirstRow" },
+          expect: "detail",
+          label: `Open a ${screen.title} record`,
+        });
+      }
+      workflows.push({
+        id: slug(screen.path),
+        title: `Browse ${screen.title}`,
+        resource: screen.title,
+        steps,
+      });
+      continue;
+    }
+    // Top-level create form (`/coupons/new`): verify it opens and renders its
+    // inputs. Forms do not fetch, so this is a fast, reliable structural check
+    // that the request-body schema produced a usable form.
+    if (
+      screen.uiPattern === "form" &&
+      screen.path.endsWith("/new") &&
+      !screen.path.slice(0, -4).includes("[") &&
+      (screen.depth === undefined || screen.depth === 1)
+    ) {
+      workflows.push({
+        id: slug(screen.path),
+        title: `Open the ${screen.title} form`,
+        resource: screen.title,
+        steps: [
+          {
+            action: { type: "visit", path: screen.path },
+            expect: "form",
+            label: `Open ${screen.title}`,
+          },
+        ],
+      });
+      continue;
+    }
+    // Top-level singleton read (`/system`, `/performance`): a bracket-less
+    // detail page. Verify it opens and renders.
+    if (
+      screen.uiPattern === "detail" &&
+      !screen.path.includes("[") &&
+      (screen.depth === undefined || screen.depth === 1)
+    ) {
+      workflows.push({
+        id: slug(screen.path),
+        title: `View ${screen.title}`,
+        resource: screen.title,
+        steps: [
+          {
+            action: { type: "visit", path: screen.path },
+            expect: "detail",
+            label: `Open ${screen.title}`,
+          },
+        ],
+      });
+    }
+  }
+
+  return workflows;
+}