@autoview/cli 0.1.0

package/src/orchestrate/orchestrateAutoViewRenderDeterministic.ts

@@ -0,0 +1,101 @@
+import { OpenApi } from "@typia/interface";
+import { v7 } from "uuid";
+
+import { AutoBeAutoViewRenderPageEvent } from "../typings";
+import { IAutoViewAgentContext } from "../context/IAutoViewAgentContext";
+import { toEndpoints } from "../utils/toEndpoints";
+import { IAutoViewProductPlan } from "./structures/IAutoViewProductPlan";
+import { IAutoViewRenderOutput, screenPathToFile } from "./orchestrateAutoViewRender";
+import { renderResourcePage } from "./utils/renderResourcePage";
+
+/**
+ * Phase 4 — deterministic Render.
+ *
+ * Replaces the LLM-driven `orchestrateAutoViewRender`. For each screen it emits
+ * a thin `page.tsx` that wires the typed SDK call to a universal `Resource*`
+ * component, with the column / field metadata baked from the swagger schema (see
+ * {@link renderResourcePage}). No LLM call, no parser-retry loop, no per-page
+ * latency — the whole phase is a synchronous map. The result keeps the
+ * {@link IAutoViewRenderOutput} shape so the typecheck / review phases downstream
+ * are unchanged.
+ *
+ * "모든 엔드포인트 빡빡 + 테이블 모든 필드 빡빡 + 누락 0" is now a structural
+ * guarantee: every screen the deterministic plan produced gets a page, and every
+ * property of its row / response / request type becomes a column / row / input.
+ */
+export async function orchestrateAutoViewRenderDeterministic(
+  ctx: IAutoViewAgentContext,
+  props: {
+    document: OpenApi.IDocument;
+    productPlan: IAutoViewProductPlan;
+    step: number;
+  },
+): Promise<IAutoViewRenderOutput> {
+  const endpoints = toEndpoints(props.document);
+  const total = props.productPlan.screens.length;
+  const files: Record<string, string> = {};
+  const screens: IAutoViewRenderOutput.IScreenReport[] = [];
+
+  let completed = 0;
+  for (const screen of props.productPlan.screens) {
+    const tsx = renderResourcePage(
+      screen,
+      endpoints,
+      props.document,
+      props.productPlan.screens,
+    );
+    const filePath = screenPathToFile(screen.path);
+    files[filePath] = tsx;
+    completed++;
+
+    screens.push({
+      pagePath: screen.path,
+      uiPattern: screen.uiPattern as string,
+      actor: screen.actor,
+      rationale: "deterministic",
+      attempts: 1,
+      ok: true,
+      diagnostic: "",
+    });
+
+    ctx.dispatch({
+      type: "autoViewRenderPage",
+      id: v7(),
+      created_at: new Date().toISOString(),
+      step: props.step,
+      total,
+      completed,
+      pagePath: screen.path,
+      uiPattern: screen.uiPattern as string,
+      attempts: 1,
+      ok: true,
+      tokenUsage: zeroTokenUsage(),
+      metric: zeroMetric(),
+    } satisfies AutoBeAutoViewRenderPageEvent);
+  }
+
+  return { files, screens };
+}
+
+function zeroTokenUsage(): AutoBeAutoViewRenderPageEvent["tokenUsage"] {
+  return {
+    total: 0,
+    input: { total: 0, cached: 0 },
+    output: {
+      total: 0,
+      reasoning: 0,
+      accepted_prediction: 0,
+      rejected_prediction: 0,
+    },
+  };
+}
+
+function zeroMetric(): AutoBeAutoViewRenderPageEvent["metric"] {
+  return {
+    attempt: 0,
+    success: 0,
+    invalidJson: 0,
+    validationFailure: 0,
+    consent: 0,
+  };
+}

package/src/orchestrate/orchestrateAutoViewReview.ts

@@ -0,0 +1,272 @@
+import { OpenApi } from "@typia/interface";
+import { toEndpoints } from "../utils";
+import { IAgenticaController } from "@agentica/core";
+import { AutoBeAutoViewReviewEvent } from "../typings";
+import { IPointer } from "tstl";
+import typia, { ILlmApplication } from "typia";
+import { v7 } from "uuid";
+
+import { AutoViewSystemPromptConstant } from "../constants/AutoViewSystemPromptConstant";
+import { IAutoViewAgentContext } from "../context/IAutoViewAgentContext";
+import type { IAutoViewRenderOutput } from "./orchestrateAutoViewRender";
+import { IAutoViewProductPlan } from "./structures/IAutoViewProductPlan";
+import { IAutoViewReviewApplication } from "./structures/IAutoViewReviewApplication";
+import { IAutoViewSdkMap } from "./structures/IAutoViewSdkMap";
+import { HistoryMessage } from "./utils/HistoryMessage";
+import type { IValidateFrontendTypecheckResult } from "./utils/validateFrontendTypecheck";
+
+/**
+ * Phase 5 of the AutoView agent — UI Review.
+ *
+ * Produces the operator-facing `wiki/sdk-feedback.md` document. The review is a
+ * code-and-spec audit, not a visual one: the LLM receives the SDK map, the
+ * product plan, and the per-screen render report (rationale + attempts + ok
+ * flag + parser diagnostic when it failed), and turns that into the markdown
+ * sections defined by the system prompt.
+ *
+ * Visual verification on screenshots happens later, during the Sandbox deploy
+ * step, and feeds back into the agent through manual `wiki/sdk-feedback.md`
+ * edits.
+ *
+ * Counts of broken/recovered pages on the event are derived deterministically
+ * from the Render report — the LLM cannot lie about which screens broke.
+ * `screenshots` stays `0` until a real Playwright loop lands; the field exists
+ * on the event so downstream UIs can surface it once it does.
+ */
+export async function orchestrateAutoViewReview(
+  ctx: IAutoViewAgentContext,
+  props: {
+    document: OpenApi.IDocument;
+    sdkMap: IAutoViewSdkMap;
+    productPlan: IAutoViewProductPlan;
+    render: IAutoViewRenderOutput;
+    /**
+     * Result of running `tsc --noEmit` against the assembled project. The
+     * `broken` count on the Review event reflects "files with at least one
+     * typecheck error" rather than "screens whose parser retry was exhausted" —
+     * typecheck is the more honest signal of "will the external user be able to
+     * `npm run build` what we shipped them".
+     */
+    typecheck: IValidateFrontendTypecheckResult;
+    /**
+     * Number of screens the typecheck-driven retry loop successfully recovered:
+     * pages that failed `tsc --noEmit` in the initial measurement but
+     * typechecked cleanly after at least one re-render fed the diagnostics back
+     * to the model.
+     */
+    recovered: number;
+    step: number;
+  },
+): Promise<{ markdown: string }> {
+  const pointer: IPointer<IAutoViewReviewApplication.IProps | null> = {
+    value: null,
+  };
+
+  const renderSummary = props.render.screens.map((s) => ({
+    pagePath: s.pagePath,
+    uiPattern: s.uiPattern,
+    actor: s.actor,
+    rationale: s.rationale,
+    attempts: s.attempts,
+    ok: s.ok,
+    diagnostic: s.diagnostic,
+  }));
+
+  await ctx.conversate({
+    source: "autoViewReview",
+    target: "writeSdkFeedback",
+    controller: createController({
+      build: (next) => {
+        pointer.value = next;
+      },
+    }),
+    enforceFunctionCall: true,
+    histories: [
+      HistoryMessage.system(AutoViewSystemPromptConstant.AUTOVIEW_REVIEW),
+      HistoryMessage.assistant`
+        Here is everything you need to audit the SDK.
+
+        ## SDK map
+
+        \`\`\`json
+        ${JSON.stringify(props.sdkMap, null, 2)}
+        \`\`\`
+
+        ## Product plan
+
+        \`\`\`json
+        ${JSON.stringify(props.productPlan, null, 2)}
+        \`\`\`
+
+        ## Render report (per screen)
+
+        \`\`\`json
+        ${JSON.stringify(renderSummary, null, 2)}
+        \`\`\`
+      `,
+    ],
+    userMessage:
+      "Write `wiki/sdk-feedback.md`. Call `writeSdkFeedback` once with the markdown and a one-sentence summary.",
+  });
+
+  // Count "broken" against the typecheck result: an LLM-rendered page that
+  // passed the per-screen parser retry but still fails `tsc --noEmit` is
+  // still broken from the user's perspective. Parser-only failures are
+  // captured by the placeholder pages the Render phase ships, so they
+  // also fail typecheck and are counted here.
+  const broken = props.typecheck.diagnostics.size;
+  const llmMarkdown =
+    pointer.value === null
+      ? renderFallbackFeedback(props.render.screens)
+      : pointer.value.markdown;
+  // Append a deterministic endpoint-coverage report so the operator
+  // always has an objective view of which accessors landed on a
+  // screen vs. which were left out. The LLM-written markdown can drift,
+  // but the appendix is computed from the same plan and document the
+  // orchestrator already trusts.
+  const coverage = buildEndpointCoverageAppendix(
+    props.document,
+    props.productPlan,
+  );
+  const markdown = `${llmMarkdown.trimEnd()}\n\n${coverage}`;
+
+  ctx.dispatch({
+    type: "autoViewReview",
+    id: v7(),
+    created_at: new Date().toISOString(),
+    step: props.step,
+    screenshots: 0,
+    broken,
+    recovered: props.recovered,
+    sdkFeedback: markdown,
+  } satisfies AutoBeAutoViewReviewEvent);
+
+  return { markdown };
+}
+
+/* -------------------------------------------------------------------------- */
+/* deterministic endpoint-coverage appendix                                   */
+/* -------------------------------------------------------------------------- */
+
+function buildEndpointCoverageAppendix(
+  document: OpenApi.IDocument,
+  plan: IAutoViewProductPlan,
+): string {
+  const allAccessors = new Set<string>();
+  for (const op of toEndpoints(document)) {
+    if (op.accessor && op.accessor.length > 0) {
+      allAccessors.add(op.accessor.join("."));
+    }
+  }
+  const covered = new Set<string>();
+  for (const screen of plan.screens) {
+    for (const accessor of screen.endpoints) {
+      covered.add(accessor);
+    }
+  }
+  // `intentionalOmissions.target` is a free-form label, so we cannot
+  // confidently match it back to an accessor. Surface the operator's
+  // declared list separately so they can audit overlap by eye.
+  const uncovered = [...allAccessors]
+    .filter((a) => !covered.has(a))
+    .sort((a, b) => a.localeCompare(b));
+  const coveredList = [...covered].sort((a, b) => a.localeCompare(b));
+  const lines: string[] = [
+    "## Endpoint coverage (auto-generated)",
+    "",
+    `**Total SDK operations**: ${allAccessors.size} · ` +
+      `**Used by at least one screen**: ${covered.size} · ` +
+      `**Not used by any screen**: ${uncovered.length} · ` +
+      `**Intentional omissions declared**: ${plan.intentionalOmissions.length}`,
+    "",
+    "### Used in screens",
+    "",
+  ];
+  if (coveredList.length === 0) {
+    lines.push("_(none)_");
+  } else {
+    for (const accessor of coveredList) lines.push(`- \`${accessor}\``);
+  }
+  lines.push("", "### Not used by any screen", "");
+  if (uncovered.length === 0) {
+    lines.push("_(none — every SDK accessor lands on at least one screen.)_");
+  } else {
+    for (const accessor of uncovered) lines.push(`- \`${accessor}\``);
+  }
+  lines.push("", "### Intentional omissions declared in the plan", "");
+  if (plan.intentionalOmissions.length === 0) {
+    lines.push("_(none declared)_");
+  } else {
+    for (const omission of plan.intentionalOmissions) {
+      lines.push(`- **${omission.target}** — ${omission.reason}`);
+    }
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+
+/* -------------------------------------------------------------------------- */
+/* fallback when the model fails to call `writeSdkFeedback`                   */
+/* -------------------------------------------------------------------------- */
+
+function renderFallbackFeedback(
+  screens: IAutoViewRenderOutput.IScreenReport[],
+): string {
+  const broken = screens.filter((s) => !s.ok);
+  return [
+    "# SDK Feedback",
+    "",
+    "The Review phase model did not call `writeSdkFeedback`. Falling back",
+    "to a minimal report so the wiki entry still exists.",
+    "",
+    "## Summary",
+    "",
+    "_(LLM omitted summary.)_",
+    "",
+    "## What worked well",
+    "",
+    "None observed.",
+    "",
+    "## What's awkward",
+    "",
+    "None observed.",
+    "",
+    "## What's missing",
+    "",
+    "None observed.",
+    "",
+    "## Pages that broke",
+    "",
+    broken.length === 0
+      ? "None observed."
+      : broken
+          .map(
+            (s) =>
+              `- \`${s.pagePath}\` (${s.uiPattern}) — ${s.attempts} attempts: ${s.diagnostic}`,
+          )
+          .join("\n"),
+    "",
+  ].join("\n");
+}
+
+/* -------------------------------------------------------------------------- */
+/* controller wiring                                                          */
+/* -------------------------------------------------------------------------- */
+
+function createController(props: {
+  build: (next: IAutoViewReviewApplication.IProps) => void;
+}): IAgenticaController.IClass {
+  const application: ILlmApplication =
+    typia.llm.application<IAutoViewReviewApplication>();
+
+  return {
+    protocol: "class",
+    name: "autoViewReview",
+    application,
+    execute: {
+      writeSdkFeedback: (next) => {
+        props.build(next);
+      },
+    } satisfies IAutoViewReviewApplication,
+  };
+}