@autoview/cli 0.1.0

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

@@ -0,0 +1,86 @@
+import { describe, expect, it } from "vitest";
+
+import { describeEndpointPropsShape } from "./describeEndpointPropsShape";
+
+const stub = (
+  overrides: Partial<IAutoViewEndpoint>,
+): IAutoViewEndpoint => ({
+  method: "patch",
+  path: "/things",
+  specification: "",
+  description: "",
+  authorizationType: null,
+  parameters: [],
+  requestBody: null,
+  responseBody: null,
+  authorizationActor: null,
+  name: "index",
+  prerequisites: [],
+  accessor: ["things", "index"],
+  ...overrides,
+});
+
+describe("describeEndpointPropsShape", () => {
+  it("returns `{}` when there are no path params and no body", () => {
+    expect(describeEndpointPropsShape(stub({}))).toBe("{}");
+  });
+
+  it("emits a single path parameter", () => {
+    expect(
+      describeEndpointPropsShape(
+        stub({
+          method: "get",
+          name: "at",
+          parameters: [
+            { name: "id", description: "", schema: { type: "string" } },
+          ],
+        }),
+      ),
+    ).toBe("{ id: string }");
+  });
+
+  it("wraps the body type under `body` when no path params exist", () => {
+    expect(
+      describeEndpointPropsShape(
+        stub({
+          requestBody: { description: "", typeName: "IShoppingSale.IRequest" },
+        }),
+      ),
+    ).toBe("{ body: IShoppingSale.IRequest }");
+  });
+
+  it("combines multiple path params with the body wrapper", () => {
+    expect(
+      describeEndpointPropsShape(
+        stub({
+          method: "post",
+          name: "create",
+          parameters: [
+            { name: "saleId", description: "", schema: { type: "string" } },
+            { name: "reviewId", description: "", schema: { type: "string" } },
+          ],
+          requestBody: {
+            description: "",
+            typeName: "IShoppingSaleReviewComment.ICreate",
+          },
+        }),
+      ),
+    ).toBe(
+      "{ saleId: string; reviewId: string; body: IShoppingSaleReviewComment.ICreate }",
+    );
+  });
+
+  it("maps integer/number param schemas to `number`", () => {
+    expect(
+      describeEndpointPropsShape(
+        stub({
+          method: "get",
+          name: "at",
+          parameters: [
+            { name: "index", description: "", schema: { type: "integer" } },
+          ],
+        }),
+      ),
+    ).toBe("{ index: number }");
+  });
+});

package/src/orchestrate/utils/describeEndpointPropsShape.ts

@@ -0,0 +1,202 @@
+import { OpenApi } from "@typia/interface";
+import { IAutoViewEndpoint } from "../../utils";
+
+/**
+ * Derive the Nestia `(connection, props)` call shape for a single AutoBE
+ * operation as a one-line TypeScript signature string. Used by the Render phase
+ * to spoon-feed the LLM the exact `props` object shape it has to pass —
+ * otherwise the model routinely flattens body fields into the top level of
+ * `props`, which makes the simulator return a masked 400 and the page renders
+ * the empty state.
+ *
+ * Examples (matching the live shopping SDK):
+ *
+ * - `at` on `/sales/:id` → `{ id: string }`
+ * - `index` on `/sales` (PATCH) → `{ body: IShoppingSale.IRequest }`
+ * - `create` on `/sales/:saleId/reviews` → `{ saleId: string; body:
+ *   IShoppingSaleReview.ICreate }`
+ *
+ * Pure. Does not mutate the operation.
+ */
+export function describeEndpointPropsShape(
+  op: IAutoViewEndpoint,
+): string {
+  const fields: string[] = [];
+  for (const param of op.parameters) {
+    fields.push(`${param.name}: ${renderParamType(param.schema)}`);
+  }
+  // Query endpoints carry their query object under `props.query`. Omitting it
+  // here is exactly why the Render LLM passed `undefined` as props for
+  // findByStatus / login and broke typecheck — the props shape never told it a
+  // query existed.
+  if (op.query != null) {
+    fields.push(`query: ${renderQueryShape(op.query)}`);
+  }
+  if (op.requestBody !== null) {
+    fields.push(`body: ${op.requestBody.typeName}`);
+  }
+  if (fields.length === 0) return "{}";
+  return `{ ${fields.join("; ")} }`;
+}
+
+/** Render a query schema: a named component (nestia emits `*.GetQuery`) or an
+ *  inline object. The Render phase imports the named SDK type either way. */
+function renderQueryShape(query: OpenApi.IJsonSchema): string {
+  if ("$ref" in query && typeof query.$ref === "string") {
+    return query.$ref.split("/").pop()!;
+  }
+  if ("properties" in query && query.properties) {
+    const required = new Set(query.required ?? []);
+    const fields = Object.entries(query.properties).map(([name, prop]) => {
+      const optional = required.has(name) ? "" : "?";
+      const type = "type" in prop ? String(prop.type) : "unknown";
+      return `${name}${optional}: ${type}`;
+    });
+    return fields.length > 0 ? `{ ${fields.join("; ")} }` : "{}";
+  }
+  return "Record<string, unknown>";
+}
+
+/**
+ * Inspect the document's component schemas and return a brief, machine-friendly
+ * line describing the operation's request body — what type it is, which fields
+ * are required, and a sample literal the LLM can copy verbatim into the page
+ * when no domain-specific filter applies.
+ *
+ * Returns an empty string when the operation has no request body, or when the
+ * referenced schema cannot be resolved (the prompt is then unchanged for that
+ * endpoint, no harm done).
+ *
+ * Format:
+ *
+ *     body: IShoppingSale.IRequest — required: [page, limit]; example: { "page": 1, "limit": 24 }
+ *
+ * Pure. Does not mutate the document.
+ */
+export function describeRequestBodyHint(
+  op: IAutoViewEndpoint,
+  doc: OpenApi.IDocument,
+): string {
+  if (op.requestBody === null) return "";
+  const schema = (doc.components?.schemas ?? {})[op.requestBody.typeName];
+  if (schema === undefined) return `body: ${op.requestBody.typeName}`;
+  const required = collectRequired(schema, doc);
+  const example = sampleLiteral(schema, doc, required);
+  const requiredPart =
+    required.length > 0
+      ? ` — required: [${required.join(", ")}]`
+      : " — (no required fields)";
+  const examplePart = example !== null ? `; example: ${example}` : "";
+  return `body: ${op.requestBody.typeName}${requiredPart}${examplePart}`;
+}
+
+function renderParamType(schema: OpenApi.IJsonSchema): string {
+  if (!("type" in schema)) return "string";
+  switch (schema.type) {
+    case "integer":
+    case "number":
+      return "number";
+    case "boolean":
+      return "boolean";
+    default:
+      return "string";
+  }
+}
+
+/**
+ * Pull the `required[]` list out of an object schema, resolving a single level
+ * of `$ref` indirection when the type name points at a nested component.
+ * Returns an empty array for non-object schemas so callers can uniformly print
+ * "(no required fields)".
+ */
+function collectRequired(
+  schema: OpenApi.IJsonSchema,
+  doc: OpenApi.IDocument,
+): string[] {
+  const resolved = resolveSchema(schema, doc);
+  if (resolved === null) return [];
+  if (!("type" in resolved) || resolved.type !== "object") return [];
+  return resolved.required ?? [];
+}
+
+/**
+ * Best-effort literal that satisfies the schema's required fields. Used to give
+ * the LLM a concrete `{ "body": ... }` starting point instead of a bare type
+ * name. We do not try to be exhaustive — just enough to clear the typia
+ * validation gate (page/limit numbers, empty arrays for collections, null for
+ * nullable refs, etc.).
+ */
+function sampleLiteral(
+  schema: OpenApi.IJsonSchema,
+  doc: OpenApi.IDocument,
+  required: string[],
+): string | null {
+  const resolved = resolveSchema(schema, doc);
+  if (resolved === null) return null;
+  if (!("type" in resolved) || resolved.type !== "object") return null;
+  const obj = resolved as OpenApi.IJsonSchema.IObject;
+  const entries: string[] = [];
+  for (const field of required) {
+    const childSchema = (obj.properties ?? {})[field];
+    if (childSchema === undefined) continue;
+    entries.push(
+      `${JSON.stringify(field)}: ${sampleValue(childSchema, doc, field)}`,
+    );
+  }
+  return `{ ${entries.join(", ")} }`;
+}
+
+function sampleValue(
+  schema: OpenApi.IJsonSchema,
+  doc: OpenApi.IDocument,
+  fieldHint: string,
+): string {
+  const resolved = resolveSchema(schema, doc) ?? schema;
+  if ("const" in resolved) {
+    return JSON.stringify(
+      (resolved as OpenApi.IJsonSchema.IConstant).const,
+    );
+  }
+  if ("oneOf" in resolved) {
+    const branches = resolved.oneOf;
+    if (branches.length > 0) return sampleValue(branches[0]!, doc, fieldHint);
+    return "null";
+  }
+  if (!("type" in resolved)) return "null";
+  switch (resolved.type) {
+    case "boolean":
+      return "false";
+    case "integer":
+    case "number":
+      if (fieldHint === "page" || fieldHint === "current") return "1";
+      if (fieldHint === "limit") return "24";
+      return "0";
+    case "string":
+      return '""';
+    case "array":
+      return "[]";
+    case "object":
+      return "{}";
+    case "null":
+      return "null";
+  }
+  return "null";
+}
+
+/**
+ * Follow a single layer of `$ref` indirection so callers can ask for an object
+ * schema by type name (the request-body `typeName`) and receive the resolved
+ * component back. Returns `null` when the ref does not point at a known
+ * component.
+ */
+function resolveSchema(
+  schema: OpenApi.IJsonSchema,
+  doc: OpenApi.IDocument,
+): OpenApi.IJsonSchema | null {
+  if ("$ref" in schema && typeof schema.$ref === "string") {
+    const name = schema.$ref.replace(/^#\/components\/schemas\//, "");
+    const target = (doc.components?.schemas ?? {})[name];
+    return (target ?? null) as OpenApi.IJsonSchema | null;
+  }
+  return schema;
+}

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

@@ -0,0 +1,87 @@
+import { OpenApi } from "@typia/interface";
+import { describe, expect, it } from "vitest";
+
+import { describeEndpointRequestBodyShape } from "./describeEndpointRequestBodyShape";
+
+const op = (
+  overrides: Partial<IAutoViewEndpoint>,
+): IAutoViewEndpoint => ({
+  method: "patch",
+  path: "/things",
+  specification: "",
+  description: "",
+  authorizationType: null,
+  parameters: [],
+  requestBody: null,
+  responseBody: null,
+  authorizationActor: null,
+  name: "index",
+  prerequisites: [],
+  accessor: ["things", "index"],
+  ...overrides,
+});
+
+const doc = (
+  schemas: Record<string, OpenApi.IJsonSchema>,
+): OpenApi.IDocument =>
+  ({
+    operations: [],
+    components: {
+      schemas,
+      securitySchemes: {},
+    },
+  }) as unknown as OpenApi.IDocument;
+
+describe("describeEndpointRequestBodyShape", () => {
+  it("returns null when the operation has no request body", () => {
+    expect(describeEndpointRequestBodyShape(op({}), doc({}))).toBeNull();
+  });
+
+  it("falls back to the bare type name when the schema is missing", () => {
+    expect(
+      describeEndpointRequestBodyShape(
+        op({
+          requestBody: { description: "", typeName: "IMissing" },
+        }),
+        doc({}),
+      ),
+    ).toBe("IMissing");
+  });
+
+  it("expands sort grammars as arrays of literal-string unions", () => {
+    expect(
+      describeEndpointRequestBodyShape(
+        op({
+          requestBody: { description: "", typeName: "ITrashRequest" },
+        }),
+        doc({
+          ITrashRequest: {
+            type: "object",
+            description: "",
+            properties: {
+              page: { type: "integer", description: "" },
+              sort: {
+                type: "array",
+                description: "",
+                items: {
+                  oneOf: [
+                    { const: "created_at.asc", description: "" },
+                    { const: "created_at.desc", description: "" },
+                  ],
+                },
+              },
+            },
+            required: ["page"],
+          },
+        }),
+      ),
+    ).toBe(
+      [
+        "{",
+        "  page: number;",
+        '  sort?: Array<"created_at.asc" | "created_at.desc">;',
+        "}",
+      ].join("\n"),
+    );
+  });
+});

package/src/orchestrate/utils/describeEndpointRequestBodyShape.ts

@@ -0,0 +1,31 @@
+import { OpenApi } from "@typia/interface";
+import { IAutoViewEndpoint } from "../../utils";
+
+import { renderNamedSchema } from "./renderJsonSchema";
+
+/**
+ * Render the request body type of a single AutoBE operation as a readable,
+ * multi-line TypeScript-shaped string — mirror of
+ * {@link describeEndpointResponseShape} for the input side.
+ *
+ * The existing one-line {@link describeRequestBodyHint} surfaces the typeName,
+ * required keys, and a sample literal, but stops short of expanding nested
+ * arrays-of-union-literals (sort grammars) or other deeply-typed request DTOs —
+ * which is enough for the LLM to fall back on its priors and emit `sort: {
+ * field: ..., direction: ... }[]` against an `ITrashRequest.sort` whose real
+ * shape is `("created_at.asc" | "created_at.desc" | ...)[]`. Pre-rendering the
+ * full shape on the way in kills that whole class of defect at zero LLM cost,
+ * just like the response path does.
+ *
+ * Returns `null` when the operation has no request body so callers can skip the
+ * line entirely rather than emitting `body: void`.
+ *
+ * Pure. Does not mutate the document.
+ */
+export function describeEndpointRequestBodyShape(
+  op: IAutoViewEndpoint,
+  doc: OpenApi.IDocument,
+): string | null {
+  if (op.requestBody === null) return null;
+  return renderNamedSchema(op.requestBody.typeName, doc);
+}

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

@@ -0,0 +1,70 @@
+import { OpenApi } from "@typia/interface";
+import { describe, expect, it } from "vitest";
+
+import { describeEndpointResponseShape } from "./describeEndpointResponseShape";
+
+const op = (
+  overrides: Partial<IAutoViewEndpoint>,
+): IAutoViewEndpoint => ({
+  method: "get",
+  path: "/things",
+  specification: "",
+  description: "",
+  authorizationType: null,
+  parameters: [],
+  requestBody: null,
+  responseBody: null,
+  authorizationActor: null,
+  name: "at",
+  prerequisites: [],
+  accessor: ["things", "at"],
+  ...overrides,
+});
+
+const doc = (
+  schemas: Record<string, OpenApi.IJsonSchema>,
+): OpenApi.IDocument =>
+  ({
+    operations: [],
+    components: {
+      schemas,
+      securitySchemes: {},
+    },
+  }) as unknown as OpenApi.IDocument;
+
+describe("describeEndpointResponseShape", () => {
+  it("returns `void` when the operation has no response body", () => {
+    expect(describeEndpointResponseShape(op({}), doc({}))).toBe("void");
+  });
+
+  it("falls back to the bare type name when the schema is missing", () => {
+    expect(
+      describeEndpointResponseShape(
+        op({
+          responseBody: { description: "", typeName: "IMissing" },
+        }),
+        doc({}),
+      ),
+    ).toBe("IMissing");
+  });
+
+  it("delegates resolved schemas to the shared renderer", () => {
+    expect(
+      describeEndpointResponseShape(
+        op({
+          responseBody: { description: "", typeName: "IFlag" },
+        }),
+        doc({
+          IFlag: {
+            type: "object",
+            description: "",
+            properties: {
+              value: { type: "boolean", description: "" },
+            },
+            required: ["value"],
+          },
+        }),
+      ),
+    ).toBe(["{", "  value: boolean;", "}"].join("\n"));
+  });
+});

package/src/orchestrate/utils/describeEndpointResponseShape.ts

@@ -0,0 +1,32 @@
+import { OpenApi } from "@typia/interface";
+import { IAutoViewEndpoint } from "../../utils";
+
+import { renderNamedSchema } from "./renderJsonSchema";
+
+/**
+ * Render the response body type of a single AutoBE operation as a readable,
+ * multi-line TypeScript-shaped string. Used by the Render phase to spoon-feed
+ * the LLM the exact field names + nesting of every endpoint's return value —
+ * otherwise the model invents plausible-sounding properties (e.g. `auth.member`
+ * on `IAuthorized` when the real shape is `{ id, created_at, token }`), which
+ * then fails TypeScript when the user runs `npm run typecheck` against the
+ * generated frontend.
+ *
+ * Returns `void` when the operation has no response body, so callers can
+ * pass-through to `Promise<void>` in the rendered signature. Delegates the
+ * actual schema walk to {@link renderJsonSchema} so request and response
+ * descriptions stay shape-compatible.
+ *
+ * Pure. Does not mutate the document.
+ */
+export function describeEndpointResponseShape(
+  op: IAutoViewEndpoint,
+  doc: OpenApi.IDocument,
+): string {
+  if (op.responseBody === null) return "void";
+  const shape = renderNamedSchema(op.responseBody.typeName, doc);
+  // A list endpoint responds with an array of the element type. Make the
+  // array explicit so the Render phase builds a table/list off the element
+  // fields, not a single-record view.
+  return op.responseBody.isArray ? `${shape}[]` : shape;
+}

package/src/orchestrate/utils/executeCachedBatch.ts

@@ -0,0 +1,59 @@
+import { Pair } from "tstl";
+import { v7 } from "uuid";
+
+/**
+ * Executes a task list with semaphore-controlled parallelization.
+ *
+ * All tasks are dispatched immediately into a worker pool, with concurrency
+ * limited by `semaphore` to prevent overwhelming LLM APIs. Results are returned
+ * in original order. On the first task failure the remaining queue is aborted
+ * and the original error is rethrown.
+ *
+ * Standalone copy of `@autobe/agent`'s `executeCachedBatch` that takes the
+ * concurrency cap directly as a number — the autoview package does not need the
+ * full `AutoBeContext` shape just to read `ctx.vendor.semaphore`.
+ *
+ * @param semaphore Concurrency cap (1–N parallel tasks at any one time).
+ * @param taskList List of async tasks to execute, each receiving the cache key
+ *   as its argument.
+ * @param promptCacheKey Optional cache key (generates a UUID if omitted) — used
+ *   as the user-message body so the LLM provider can reuse a cached system
+ *   prompt across calls.
+ */
+export const executeCachedBatch = async <T>(
+  semaphore: number,
+  taskList: Task<T>[],
+  promptCacheKey?: string,
+): Promise<T[]> => {
+  if (taskList.length === 0) return [];
+
+  promptCacheKey ??= v7();
+
+  const queue: Array<Pair<Task<T>, number>> = taskList.map(
+    (task, index) => new Pair(task, index),
+  );
+  const results: Pair<T, number>[] = [];
+  let aborted: boolean = false;
+  let firstError: unknown = null;
+  await Promise.allSettled(
+    new Array(Math.min(semaphore, queue.length)).fill(0).map(async () => {
+      while (queue.length !== 0 && !aborted) {
+        const item: Pair<Task<T>, number> = queue.splice(0, 1)[0]!;
+        try {
+          const result: T = await item.first(promptCacheKey!);
+          if (!aborted) results.push(new Pair(result, item.second));
+        } catch (error) {
+          if (!aborted) {
+            aborted = true;
+            queue.length = 0;
+            firstError = error;
+          }
+        }
+      }
+    }),
+  );
+  if (firstError !== null) throw firstError;
+  return results.sort((x, y) => x.second - y.second).map((p) => p.first);
+};
+
+type Task<T> = (user: string) => Promise<T>;

package/src/orchestrate/utils/loadShoppingFixture.ts

@@ -0,0 +1,52 @@
+import { OpenApi } from "@typia/interface";
+import { OpenApiConverter } from "@typia/utils";
+
+/**
+ * Lazy-load `@samchon/shopping-api/swagger.json` and convert it to an
+ * {@link OpenApi.IDocument} so AutoView can run against a stable reference
+ * SDK without depending on the live `interface` phase.
+ *
+ * Also surfaces the swagger's first declared server URL — the bundled
+ * `@samchon/shopping-api` swagger lists `https://shopping-be.wrtn.ai` so the
+ * generated frontend can hit a real backend (and render real product names like
+ * "Apple Watch") instead of typia-random mock gibberish. The Scaffold phase
+ * uses this URL to seed the default `IConnection.host`.
+ *
+ * The swagger payload is ~700 KB, so the result is memoized on the first call.
+ * The conversion reuses the same `invertOpenApiDocument` helper the live
+ * interface compiler relies on, which means the rest of the AutoView pipeline
+ * cannot tell the document came from a fixture instead of a freshly generated
+ * session.
+ *
+ * The shopping-api package ships an OpenAPI 3.x document — its shape is
+ * structurally identical to typia's `OpenApi.IDocument`, so we cast through
+ * `unknown` rather than dragging in another normalization library. The
+ * downstream invert helper validates the relevant fields itself; an
+ * incompatible document would surface there.
+ */
+export interface IShoppingFixture {
+  document: OpenApi.IDocument;
+  /**
+   * First entry from `swagger.servers[]`. `null` when the swagger omits
+   * `servers` (the SDK would then have to rely on simulate-only mocks).
+   */
+  serverUrl: string | null;
+}
+
+let cached: IShoppingFixture | null = null;
+
+export function loadShoppingFixture(): IShoppingFixture {
+  if (cached !== null) return cached;
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const swagger = require("@samchon/shopping-api/swagger.json") as {
+    servers?: ReadonlyArray<{ url?: string | null } | null> | null;
+  };
+  const document = OpenApiConverter.upgradeDocument(
+    swagger as unknown as Parameters<typeof OpenApiConverter.upgradeDocument>[0],
+  );
+  const serverUrl =
+    swagger.servers?.find((s) => typeof s?.url === "string" && s.url.length > 0)
+      ?.url ?? null;
+  cached = { document, serverUrl: serverUrl ?? null };
+  return cached;
+}