@autoview/cli 0.1.0

package/src/orchestrate/utils/buildDeterministicPlan.ts

@@ -0,0 +1,289 @@
+import { OpenApi } from "@typia/interface";
+
+import {
+  filterEndpoints,
+  IAutoViewEndpoint,
+  IEndpointFilter,
+  IPlannedScreen,
+  isCatalogCollection,
+  resourcePlan,
+  ScreenKind,
+  toEndpoints,
+  unsupportedOperations,
+} from "../../utils";
+import { IAutoViewProductPlan } from "../structures/IAutoViewProductPlan";
+import { responseCollection } from "./renderResourcePage";
+
+/**
+ * Deterministic Product Plan — the LLM ProductPlan's replacement.
+ *
+ * The old Phase 2 asked an LLM to invent an information architecture from a
+ * commerce-baked prompt: non-reproducible, domain-locked, no CRUD completeness.
+ * This builds the exact same {@link IAutoViewProductPlan} shape the Scaffold /
+ * Render phases consume, but structurally — from {@link resourcePlan}. Same
+ * swagger always yields the same screens; every resource that exposes a
+ * capability gets its screen; nothing is invented.
+ *
+ * Actors are not modeled yet (the READ layer dropped `authorizationActor` when
+ * it went swagger-native), so every screen is assigned the single `actor`
+ * passed in. Multi-actor navigation is a follow-up that restores per-endpoint
+ * actor tagging.
+ */
+const UI_PATTERN: Record<ScreenKind, IAutoViewProductPlan.UiPattern> = {
+  list: "table",
+  detail: "detail",
+  create: "form",
+  edit: "form",
+};
+
+/**
+ * A "top-level" screen earns a spot in the landing hub + primary nav: a list
+ * table, a catalog, or a singleton read (a bracket-less detail page like
+ * `/system`). Entity-detail / create / edit pages — which carry a `[param]` and
+ * are reached from a list — do not.
+ */
+function isTopLevel(screen: IAutoViewProductPlan.IScreen): boolean {
+  // A landing card is a TOP-LEVEL resource (chain depth 1). Depth ≥ 2 — a nested
+  // resource (`/sales/[saleId]/questions`) OR a param-less sub-view
+  // (`/sales/details`, `/channels/hierarchical`) — is reached from its parent,
+  // never the home hub. Using the structural depth, not a `[` heuristic, keeps
+  // bracket-less nested paths off the hub.
+  if (screen.depth !== undefined && screen.depth !== 1) return false;
+  if (screen.path.includes("[")) return false;
+  return (
+    screen.uiPattern === "table" ||
+    screen.uiPattern === "catalog" ||
+    screen.uiPattern === "detail"
+  );
+}
+
+/** Humanize a snake_case resource name for prose: `file_version_legal_holds`
+ *  → `file version legal holds`. Keeps it lower-case for mid-sentence use. */
+function humanizeResource(resource: string): string {
+  return resource.replace(/_/g, " ").trim();
+}
+
+function purposeOf(screen: IPlannedScreen): string {
+  const name = humanizeResource(screen.resource);
+  switch (screen.kind) {
+    case "list":
+      return `Browse and search ${name}.`;
+    case "detail":
+      return `View one ${name} and act on it.`;
+    case "create":
+      return `Create a new ${name}.`;
+    case "edit":
+      return `Edit an existing ${name}.`;
+  }
+}
+
+function notesOf(screen: IPlannedScreen): string {
+  switch (screen.kind) {
+    case "list":
+      return screen.secondary.some((c) => c.role === "search")
+        ? "Includes search/filter; rows link to the detail screen."
+        : "Rows link to the detail screen.";
+    case "detail":
+      return "Surfaces update / delete / action endpoints as buttons.";
+    case "create":
+      return "Render a form from the request-body schema; submit creates.";
+    case "edit":
+      return "Render a form from the request-body schema, prefilled from detail.";
+  }
+}
+
+function accessorsOf(screen: IPlannedScreen): string[] {
+  return [
+    screen.primary.accessor.join("."),
+    ...screen.secondary.map((c) => c.endpoint.accessor.join(".")),
+  ].filter((a, i, arr) => a.length > 0 && arr.indexOf(a) === i);
+}
+
+/**
+ * How a would-be list screen's primary response reads structurally:
+ *
+ * - `browsable` — an array or a page wrapper (`{ pagination, data: T[] }`). The
+ *   only shape that genuinely belongs in a table.
+ * - `void` — no response body (health checks, fire-and-forget). Nothing to show.
+ * - `singleton-read` — a single object returned by a GET (system status, the
+ *   current actor, a singleton config). Real data, but it is one record, not a
+ *   list — render it as a detail view, not a fake one-row table.
+ * - `action` — a single object returned by a mutating verb (auth login/refresh,
+ *   activate). Not a view at all — omit it.
+ *
+ * Purely structural: response shape + HTTP method, no domain keywords. This is
+ * what turns "every PATCH/GET without an item param becomes a table" (which
+ * dumped auth/monitoring verbs into the nav) into an honest screen set.
+ */
+type ListResponseClass = "browsable" | "void" | "singleton-read" | "action";
+
+function classifyListResponse(
+  op: IAutoViewEndpoint | undefined,
+  document: OpenApi.IDocument,
+): ListResponseClass {
+  if (op === undefined || (op.responseBody === null && op.responseSchema === null))
+    return "void";
+  // Use the SAME collection detection the table renderer uses, so a response is
+  // classed browsable iff a real row collection (incl. resource-named / inline
+  // wrappers, DigitalOcean) can actually be rendered as a table.
+  if (responseCollection(op, document) !== null) return "browsable";
+  return op.method.toLowerCase() === "get" ? "singleton-read" : "action";
+}
+
+export function buildDeterministicPlan(
+  document: OpenApi.IDocument,
+  actor: string,
+  filter: IEndpointFilter = {},
+): IAutoViewProductPlan {
+  const endpoints = filterEndpoints(toEndpoints(document), filter);
+  const planned = resourcePlan(endpoints, document);
+  const byAccessor = new Map(endpoints.map((e) => [e.accessor.join("."), e]));
+
+  const noiseOmissions: IAutoViewProductPlan.IOmission[] = [];
+  const resourceScreens: IAutoViewProductPlan.IScreen[] = [];
+  for (const s of planned) {
+    const screen: IAutoViewProductPlan.IScreen = {
+      path: s.path,
+      title: s.title,
+      purpose: purposeOf(s),
+      actor,
+      endpoints: accessorsOf(s),
+      uiPattern: UI_PATTERN[s.kind],
+      notes: notesOf(s),
+      depth: s.depth,
+    };
+    // A table screen must have a browsable response, or it is noise. Downgrade
+    // singleton reads to detail views; omit voids and action verbs.
+    if (screen.uiPattern === "table") {
+      const op = byAccessor.get(s.primary.accessor.join("."));
+      const cls = classifyListResponse(op, document);
+      if (cls === "void" || cls === "action") {
+        noiseOmissions.push({
+          target: `${op?.method.toUpperCase() ?? "?"} ${op?.path ?? s.path}`,
+          reason:
+            cls === "void"
+              ? "No response body to display."
+              : "Action endpoint (single object from a mutating verb) — not a browsable list.",
+        });
+        continue;
+      }
+      if (cls === "singleton-read") {
+        resourceScreens.push({
+          ...screen,
+          uiPattern: "detail",
+          purpose: `View ${humanizeResource(s.resource)}.`,
+          notes: "Singleton read — one record, not a list.",
+        });
+        continue;
+      }
+      // Browsable: a collection whose rows carry an image + a title reads far
+      // better as a catalog of cards than a dense table. Purely structural —
+      // the element schema decides, no domain keywords.
+      const collection = op ? responseCollection(op, document) : null;
+      if (collection !== null && isCatalogCollection(collection.columns)) {
+        resourceScreens.push({
+          ...screen,
+          uiPattern: "catalog",
+          notes: "Image + title rows — rendered as a card catalog.",
+        });
+        continue;
+      }
+    }
+    resourceScreens.push(screen);
+  }
+
+  // Drop write-only resources. A browse app shows data, so a resource that has
+  // no list / detail / search screen at all — only a create/update form or an
+  // RPC verb (OAuth2 `token`/`revoke`, a `metadata_query/execute_read`) — is
+  // pure nav noise: a lone form seated next to real resources in the primary
+  // nav. Omit it (auditably) so a large swagger's sidebar shows browsable
+  // resources, not every endpoint.
+  const resourceKeyOf = (p: string): string =>
+    p.split("/").filter((s) => s.length > 0 && !s.startsWith("[")).at(0) ?? p;
+  const resourceHasRead = new Map<string, boolean>();
+  for (const s of resourceScreens) {
+    const key = resourceKeyOf(s.path);
+    const isRead = s.uiPattern === "table" || s.uiPattern === "detail";
+    resourceHasRead.set(key, (resourceHasRead.get(key) ?? false) || isRead);
+  }
+  const browsableScreens = resourceScreens
+    .filter((s) => resourceHasRead.get(resourceKeyOf(s.path)) === true)
+    // Alphabetical by path so a large swagger's sidebar is scannable (same
+    // resource's pages stay grouped: /x, /x/[id], /x/[id]/edit, /x/new).
+    .sort((a, b) => a.path.localeCompare(b.path));
+  for (const s of resourceScreens) {
+    if (resourceHasRead.get(resourceKeyOf(s.path)) === true) continue;
+    for (const accessor of s.endpoints) {
+      const op = byAccessor.get(accessor);
+      noiseOmissions.push({
+        target: op ? `${op.method.toUpperCase()} ${op.path}` : s.path,
+        reason:
+          "Write-only resource (no list/detail/search to browse) — omitted from the UI as nav noise.",
+      });
+    }
+  }
+
+  // Root landing hub. Without an explicit `/` screen the dev server shows the
+  // template's "not customized yet" placeholder; this links to each resource's
+  // list and fetches nothing of its own.
+  const home: IAutoViewProductPlan.IScreen = {
+    path: "/",
+    title: "Home",
+    purpose: "Landing hub linking to each resource.",
+    actor,
+    endpoints: [],
+    uiPattern: "landing",
+    notes: "Links to each resource's list screen; no data fetch of its own.",
+  };
+  const screens = [home, ...browsableScreens];
+
+  // Single-actor navigation: home + every top-level screen leads the primary
+  // nav. "Top-level" = a list table or a singleton read (a bracket-less detail
+  // page like `/system`); entity-detail / create / edit pages (which carry a
+  // `[param]` or are reached from a list) go to secondary.
+  const topLevelPaths = browsableScreens
+    .filter((s) => isTopLevel(s))
+    .map((s) => s.path);
+  const secondary = browsableScreens
+    .filter((s) => !isTopLevel(s))
+    .map((s) => s.path);
+  const navigation: IAutoViewProductPlan.INavigation[] = [
+    { actor, primary: ["/", ...topLevelPaths], secondary },
+  ];
+
+  // Operations the READ layer could not turn into a screen — surfaced as
+  // honest omissions instead of vanishing. Noise screens (auth/monitoring verbs)
+  // removed above are reported here too, so "omitted, not broken" stays auditable.
+  const intentionalOmissions: IAutoViewProductPlan.IOmission[] = [
+    ...noiseOmissions,
+    ...unsupportedOperations(document).map((u) => ({
+      target: `${u.method} ${u.path}`,
+      reason: `Unsupported content type — ${u.reason}`,
+    })),
+  ];
+
+  // Integrity backstop — "정확하게 읽는다" rule #1: nothing the READ layer parsed
+  // may silently vanish. Every operation must be referenced by some screen
+  // (primary or secondary) or appear in an omission. Anything left over (a
+  // second create on a resource that already had one, a deeply nested
+  // delete with no detail to host it, an auth verb that did not classify) is
+  // recorded here so coverage is total and auditable rather than lossy.
+  const referenced = new Set<string>();
+  for (const s of browsableScreens) for (const a of s.endpoints) referenced.add(a);
+  const omittedPaths = new Set(
+    intentionalOmissions.map((o) => o.target),
+  );
+  for (const e of endpoints) {
+    const accessor = e.accessor.join(".");
+    if (referenced.has(accessor)) continue;
+    const target = `${e.method.toUpperCase()} ${e.path}`;
+    if (omittedPaths.has(target)) continue;
+    intentionalOmissions.push({
+      target,
+      reason: `Not yet mapped to a screen (accessor ${accessor}) — a duplicate-role or deeply nested endpoint the deterministic plan does not surface yet.`,
+    });
+    omittedPaths.add(target);
+  }
+
+  return { screens, navigation, intentionalOmissions };
+}

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

@@ -0,0 +1,90 @@
+import { OpenApiConverter } from "@typia/utils";
+import { describe, expect, it } from "vitest";
+
+import { buildDeterministicSdkMap } from "./buildDeterministicSdkMap";
+
+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 },
+    // biome-ignore lint: test fixture
+  } as never);
+}
+
+const listResp = (item: string) => ({
+  200: { description: "ok", content: { "application/json": { schema: { type: "array", items: { $ref: `#/components/schemas/${item}` } } } } },
+});
+const objResp = (name: string) => ({
+  200: { description: "ok", content: { "application/json": { schema: { $ref: `#/components/schemas/${name}` } } } },
+});
+const param = (n: string) => ({ name: n, in: "path", required: true, schema: { type: "string" } });
+
+describe("buildDeterministicSdkMap", () => {
+  it("derives resources from the swagger's CRUD shape (no LLM)", () => {
+    const d = doc(
+      {
+        "/sales": { get: { operationId: "index", responses: listResp("Sale") } },
+        "/sales/{saleId}": { get: { operationId: "at", parameters: [param("saleId")], responses: objResp("Sale") } },
+        "/orders": { get: { operationId: "index", responses: listResp("Order") } },
+      },
+      {
+        Sale: { type: "object", properties: { id: { type: "string" } }, required: ["id"] },
+        Order: { type: "object", properties: { id: { type: "string" } }, required: ["id"] },
+      },
+    );
+    const map = buildDeterministicSdkMap(d);
+    expect(map.resources.map((r) => r.name).sort()).toEqual(["orders", "sales"]);
+    // every resource carries a non-empty namespace + purpose
+    for (const r of map.resources) {
+      expect(r.namespace.length).toBeGreaterThan(0);
+      expect(r.purpose.length).toBeGreaterThan(0);
+    }
+  });
+
+  it("falls back to a single `user` actor when no role segment is present", () => {
+    const d = doc(
+      { "/pet": { get: { operationId: "index", responses: listResp("Pet") } } },
+      { Pet: { type: "object", properties: { id: { type: "string" } } } },
+    );
+    const map = buildDeterministicSdkMap(d);
+    expect(map.actors.map((a) => a.name)).toEqual(["user"]);
+    expect(map.actors[0]!.journeys.length).toBeGreaterThanOrEqual(1);
+  });
+
+  it("derives multiple actors from role segments in the accessor", () => {
+    const d = doc(
+      {
+        "/shoppings/customers/sales": { get: { operationId: "index", responses: listResp("Sale") } },
+        "/shoppings/sellers/sales": { post: { operationId: "create", requestBody: { content: { "application/json": { schema: { $ref: "#/components/schemas/Sale" } } } }, responses: objResp("Sale") } },
+      },
+      { Sale: { type: "object", properties: { id: { type: "string" } }, required: ["id"] } },
+    );
+    const map = buildDeterministicSdkMap(d);
+    expect(map.actors.map((a) => a.name)).toContain("customer");
+    expect(map.actors.map((a) => a.name)).toContain("seller");
+    // every actor has at least one journey (the SDK-map invariant)
+    for (const a of map.actors) expect(a.journeys.length).toBeGreaterThanOrEqual(1);
+  });
+
+  it("satisfies the downstream SDK-map invariants (≥1 resource, ≥1 actor, namespaces match accessors)", () => {
+    const d = doc(
+      {
+        "/sales/{saleId}": { get: { operationId: "at", parameters: [param("saleId")], responses: objResp("Sale") } },
+      },
+      { Sale: { type: "object", properties: { id: { type: "string" } }, required: ["id"] } },
+    );
+    const map = buildDeterministicSdkMap(d);
+    expect(map.resources.length).toBeGreaterThanOrEqual(1);
+    expect(map.actors.length).toBeGreaterThanOrEqual(1);
+  });
+
+  it("is deterministic — same document, same map", () => {
+    const d = doc(
+      { "/sales": { get: { operationId: "index", responses: listResp("Sale") } } },
+      { Sale: { type: "object", properties: { id: { type: "string" } } } },
+    );
+    expect(buildDeterministicSdkMap(d)).toEqual(buildDeterministicSdkMap(d));
+  });
+});

package/src/orchestrate/utils/buildDeterministicSdkMap.ts

@@ -0,0 +1,169 @@
+import { OpenApi } from "@typia/interface";
+
+import { EndpointRole, classifyEndpoints } from "../../utils/classifyEndpoints";
+import { toEndpoints } from "../../utils/toEndpoints";
+import { IAutoViewSdkMap } from "../structures/IAutoViewSdkMap";
+
+/**
+ * Deterministic SDK domain map — the LLM-free replacement for the Phase-1 SDK
+ * Study, and the fix for "a large swagger overflows the model's context".
+ *
+ * The original SDK Study compiled the WHOLE SDK source and asked the model to
+ * infer resources / actors / journeys. On a 200-type swagger that prompt is
+ * 300k+ tokens — a hard context overflow. But the downstream phases barely use
+ * the map's prose: the Product Plan is already deterministic and reads only
+ * `actors[0].name`; Scaffold/Review embed the map as a wiki document; Render
+ * reads an actor's journeys only on the LLM rerender fallback. So the map can be
+ * derived structurally — same swagger, same map, zero tokens — without changing
+ * what reaches the user.
+ *
+ * - resources: the top-level CRUD groups from {@link classifyEndpoints}.
+ * - actors:    role segments found in the accessors (`customers`, `sellers`,
+ *   `admins`), normalized; falls back to a single `user`.
+ * - journeys:  a short structural summary per actor (never empty — the SDK-map
+ *   invariant requires ≥1 per actor).
+ */
+export function buildDeterministicSdkMap(
+  document: OpenApi.IDocument,
+): IAutoViewSdkMap {
+  const endpoints = toEndpoints(document);
+  const groups = classifyEndpoints(endpoints, document);
+
+  const actors = deriveActors(endpoints);
+  const actorNames = actors.map((a) => a.name);
+
+  // Top-level resources only (depth 1). Nested groups (`sales/questions`) fold
+  // into their parent for the domain map; the Product Plan still renders their
+  // screens from the full classification.
+  const resources: IAutoViewSdkMap.IResource[] = groups
+    .filter((g) => g.depth === 1 && g.resource !== "root")
+    .map((g) => {
+      const sample = g.endpoints[0]?.endpoint;
+      const namespace =
+        sample !== undefined && sample.accessor.length > 1
+          ? sample.accessor.slice(0, -1).join(".")
+          : g.resource;
+      return {
+        name: g.resource,
+        namespace,
+        purpose: purposeOf(g.resource, g.roles),
+        actorsInvolved: actorNames,
+        notes: notesOf(g.roles),
+      };
+    });
+
+  return {
+    resources,
+    actors,
+    notableConstraints: deriveConstraints(endpoints),
+  };
+}
+
+/* -------------------------------------------------------------------------- */
+/* actors                                                                     */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Accessor segments that name an actor role, mapped to their canonical
+ * singular display name. Real swaggers expose an actor as a namespace segment
+ * (`shoppings.customers.sales`, `shoppings.sellers.sales`); we read the role
+ * straight off the accessor instead of guessing from the domain.
+ */
+const ROLE_SEGMENTS: Record<string, string> = {
+  customer: "customer",
+  customers: "customer",
+  seller: "seller",
+  sellers: "seller",
+  admin: "administrator",
+  admins: "administrator",
+  administrator: "administrator",
+  administrators: "administrator",
+  member: "member",
+  members: "member",
+  buyer: "buyer",
+  buyers: "buyer",
+  manager: "manager",
+  managers: "manager",
+  guest: "guest",
+  guests: "guest",
+};
+
+function deriveActors(
+  endpoints: ReturnType<typeof toEndpoints>,
+): IAutoViewSdkMap.IActor[] {
+  const names: string[] = [];
+  const seen = new Set<string>();
+  for (const e of endpoints) {
+    for (const seg of e.accessor) {
+      const canon = ROLE_SEGMENTS[seg.toLowerCase()];
+      if (canon !== undefined && !seen.has(canon)) {
+        seen.add(canon);
+        names.push(canon);
+      }
+    }
+  }
+  const finalNames = names.length > 0 ? names : ["user"];
+  // Lead with the end-user actor: the Product Plan assigns every screen to
+  // `actors[0]`, so a customer-facing label reads more naturally on the nav than
+  // an admin one. Purely cosmetic — the screen set is identical either way.
+  const ordered = [...finalNames].sort(
+    (a, b) => actorRank(a) - actorRank(b),
+  );
+  return ordered.map((name) => ({
+    name,
+    journeys: [`Sign in as ${name} → navigate the resources they can access.`],
+  }));
+}
+
+/** End-users first, privileged roles last; unknowns keep their found order. */
+const ACTOR_PRIORITY = [
+  "customer",
+  "buyer",
+  "member",
+  "user",
+  "guest",
+  "seller",
+  "manager",
+  "administrator",
+];
+function actorRank(name: string): number {
+  const i = ACTOR_PRIORITY.indexOf(name);
+  return i === -1 ? ACTOR_PRIORITY.length : i;
+}
+
+/* -------------------------------------------------------------------------- */
+/* resource prose (deterministic)                                             */
+/* -------------------------------------------------------------------------- */
+
+function purposeOf(resource: string, roles: Set<EndpointRole>): string {
+  const verbs: string[] = [];
+  if (roles.has("list") || roles.has("search")) verbs.push("browse");
+  if (roles.has("detail")) verbs.push("view");
+  if (roles.has("create")) verbs.push("create");
+  if (roles.has("update")) verbs.push("update");
+  if (roles.has("delete")) verbs.push("remove");
+  if (roles.has("action")) verbs.push("act on");
+  const verb = verbs.length > 0 ? verbs.join(", ") : "work with";
+  return `Lets a user ${verb} ${resource}.`;
+}
+
+function notesOf(roles: Set<EndpointRole>): string {
+  return roles.has("search")
+    ? "Supports search/filter/pagination via query parameters."
+    : "";
+}
+
+function deriveConstraints(
+  endpoints: ReturnType<typeof toEndpoints>,
+): string[] {
+  const constraints: string[] = [];
+  if (endpoints.some((e) => e.query !== null)) {
+    constraints.push(
+      "Some list endpoints accept query parameters for search/filter/pagination.",
+    );
+  }
+  if (endpoints.some((e) => e.method.toLowerCase() === "delete")) {
+    constraints.push("Delete endpoints are present — confirm before destructive actions.");
+  }
+  return constraints;
+}

package/src/orchestrate/utils/cacheNodeModules.ts

@@ -0,0 +1,136 @@
+import { spawn } from "child_process";
+import fs from "fs/promises";
+import os from "os";
+import path from "path";
+
+/**
+ * Per-package.json cache directory holding an installed `node_modules`. Sits
+ * under `$XDG_CACHE_HOME` when set, else `~/.cache`, partitioned by
+ * `(cacheNamespace, hash)` so callers with different dependency sets — and
+ * different downstream consumers (typecheck vs runtime audit) — never collide
+ * on the same cache key.
+ *
+ * Returns the absolute path to the populated `node_modules` directory on
+ * success, or `null` when the cache could not be set up (no writable cache
+ * root, the install crashed, etc.). Callers fall back to a plain in-place
+ * install in that case so the behavior degrades gracefully.
+ *
+ * `extraDeps` lets a caller add packages on top of the bare frontend dependency
+ * set without renaming the cache namespace: the runtime-audit cache uses
+ * `["playwright@^1.50.0"]` so the cached `node_modules` already contains
+ * Playwright the next time the agent runs an audit, on top of the same
+ * React/Next/shadcn tree as the typecheck cache.
+ */
+export async function ensureCachedNodeModules(args: {
+  cacheNamespace: string;
+  hash: string;
+  packageJson: string;
+  extraDeps?: readonly string[];
+}): Promise<string | null> {
+  if (args.hash === "no-package-json") return null;
+  const cacheRoot = path.join(
+    process.env.XDG_CACHE_HOME ?? path.join(os.homedir(), ".cache"),
+    `autoview-${args.cacheNamespace}`,
+    args.hash,
+  );
+  const nodeModules = path.join(cacheRoot, "node_modules");
+  try {
+    // `node_modules/.package-lock.json` is the canonical "install completed"
+    // sentinel npm writes at the end of `npm install`. Its presence means
+    // the previous run finished cleanly and the cache is reusable.
+    await fs.access(path.join(nodeModules, ".package-lock.json"));
+    return nodeModules;
+  } catch {
+    // Cache miss: populate it. Use a sibling temp dir + rename so a
+    // concurrent agent run cannot observe a half-written node_modules.
+    const installer = await fs.mkdtemp(
+      path.join(
+        os.tmpdir(),
+        `autoview-${args.cacheNamespace}-cache-${args.hash}-`,
+      ),
+    );
+    try {
+      await fs.writeFile(
+        path.join(installer, "package.json"),
+        args.packageJson,
+        "utf-8",
+      );
+      await runNpm(installer, [
+        "install",
+        "--silent",
+        "--no-audit",
+        "--no-fund",
+      ]);
+      if (args.extraDeps !== undefined && args.extraDeps.length > 0) {
+        await runNpm(installer, [
+          "install",
+          "--silent",
+          "--no-audit",
+          "--no-fund",
+          "--no-save",
+          ...args.extraDeps,
+        ]);
+      }
+      await fs.mkdir(cacheRoot, { recursive: true });
+      // Atomically move node_modules into place. If something is already
+      // there (concurrent run won the race), rm-then-rename overwrites it
+      // — both are valid installs of the same package.json.
+      await fs.rm(nodeModules, { recursive: true, force: true });
+      await fs.rename(path.join(installer, "node_modules"), nodeModules);
+    } catch {
+      await fs.rm(installer, { recursive: true, force: true }).catch(() => {});
+      return null;
+    }
+    await fs.rm(installer, { recursive: true, force: true }).catch(() => {});
+    try {
+      await fs.access(path.join(nodeModules, ".package-lock.json"));
+      return nodeModules;
+    } catch {
+      return null;
+    }
+  }
+}
+
+/**
+ * Create a symlink from `<workingDir>/node_modules` → `<cachedNodeModules>`.
+ * Returns `false` when the symlink could not be created (Windows without admin,
+ * filesystem refuses links, etc.) so the caller falls back to a plain in-place
+ * install.
+ */
+export async function tryLinkNodeModules(
+  workingDir: string,
+  cachedNodeModules: string,
+): Promise<boolean> {
+  const target = path.join(workingDir, "node_modules");
+  try {
+    await fs.symlink(cachedNodeModules, target, "dir");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function runNpm(cwd: string, args: string[]): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const child = spawn("npm", args, { cwd, stdio: "pipe" });
+    let stderr = "";
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk.toString("utf-8");
+    });
+    child.on("error", (err) => {
+      reject(
+        new Error(`Failed to spawn \`npm ${args.join(" ")}\`: ${err.message}`),
+      );
+    });
+    child.on("close", (code) => {
+      if (code === 0) resolve();
+      else
+        reject(
+          new Error(
+            `\`npm ${args.slice(0, 3).join(" ")}...\` exited with code ${code}` +
+              (stderr.length > 0 ? `:\n${stderr.slice(-1500)}` : ""),
+          ),
+        );
+    });
+  });
+}