@topogram/cli 0.3.64 → 0.3.65

package/src/workflows/import-app/api.js

@@ -1,799 +1,4 @@
 // @ts-check
-import fs from "node:fs";
-import path from "node:path";
 
-import { relativeTo } from "../../path-helpers.js";
-import { canonicalCandidateTerm, idHintify, slugify, titleCase } from "../../text-helpers.js";
-import { listFilesRecursive, readTextIfExists } from "../shared.js";
-import { inferReactRoutes, inferSvelteRoutes, routeSegments } from "./ui.js";
-import { dedupeCandidateRecords, findImportFiles, inferCapabilityEntityId, makeCandidateRecord, normalizeOpenApiPath, selectPreferredImportFiles } from "./shared.js";
-
-/** @param {WorkspacePaths} paths @returns {any} */
-export function discoverApiSources(paths) {
-  const allOpenApiFiles = findImportFiles(
-    paths,
-    (/** @type {any} */ filePath) =>
-      /(openapi|swagger)\.(json|ya?ml)$/i.test(path.basename(filePath))
-  );
-  const openApiFiles = selectPreferredImportFiles(paths, allOpenApiFiles, "openapi");
-  const routeFiles = findImportFiles(
-    paths,
-    (/** @type {any} */ filePath) =>
-      /\.(ts|tsx|js|jsx|mjs|cjs)$/.test(filePath) &&
-      /(server|api|routes|src)/i.test(filePath)
-  );
-  return { openApiFiles, routeFiles };
-}
-
-/** @param {WorkflowRecord} document @param {any} provenance @param {string} sourceKind @returns {any} */
-function parseOpenApiDocument(document, provenance, sourceKind = "openapi") {
-  /** @type {any[]} */
-  const capabilities = [];
-  /** @type {any[]} */
-  const routes = [];
-  const pathsObject = document.paths || {};
-  for (const [endpointPath, operations] of Object.entries(pathsObject)) {
-    for (const [method, operation] of Object.entries(operations || {})) {
-      const normalizedMethod = method.toUpperCase();
-      const operationId = operation.operationId || `candidate_${normalizedMethod.toLowerCase()}_${slugify(endpointPath)}`;
-      const requestSchema =
-        operation.requestBody?.content?.["application/json"]?.schema?.$ref ||
-        operation.requestBody?.content?.["application/json"]?.schema?.type ||
-        null;
-      const successResponse = Object.entries(operation.responses || {}).find((/** @type {any} */ [status]) => /^2/.test(status));
-      const responseSchema =
-        successResponse?.[1]?.content?.["application/json"]?.schema?.$ref ||
-        successResponse?.[1]?.content?.["application/json"]?.schema?.type ||
-        null;
-      const parameterHints = extractOpenApiParameterHints(document, endpointPath, operation);
-      const requestFieldHints = extractOpenApiSchemaFieldHints(document, operation.requestBody?.content?.["application/json"]?.schema);
-      const responseFieldHints = extractOpenApiSchemaFieldHints(document, successResponse?.[1]?.content?.["application/json"]?.schema);
-      const securitySchemes = extractOpenApiSecuritySchemes(document, operation);
-      capabilities.push(
-        makeCandidateRecord({
-          kind: "capability",
-          idHint: operationId,
-          label: operation.summary || titleCase(operationId.replace(/^cap_/, "")),
-          confidence: "high",
-          sourceKind,
-          provenance: `${provenance}#${normalizedMethod} ${endpointPath}`,
-          endpoint: {
-            method: normalizedMethod,
-            path: endpointPath
-          },
-          input_hint: requestSchema,
-          output_hint: responseSchema,
-          input_fields: requestFieldHints.body_fields,
-          output_fields: responseFieldHints.body_fields,
-          path_params: parameterHints.path,
-          query_params: parameterHints.query,
-          header_params: parameterHints.header,
-          security_schemes: securitySchemes,
-          auth_hint: securitySchemes.length > 0 ? "secured" : "unknown"
-        })
-      );
-      routes.push({
-        path: endpointPath,
-        method: normalizedMethod,
-        source_kind: sourceKind,
-        provenance: `${provenance}#${normalizedMethod} ${endpointPath}`
-      });
-    }
-  }
-  return { capabilities, routes };
-}
-
-/** @param {string} ref @returns {any} */
-function openApiRefName(ref) {
-  if (!ref || typeof ref !== "string") {
-    return null;
-  }
-  return ref.split("/").pop() || null;
-}
-
-/** @param {WorkflowRecord} document @param {WorkflowRecord} schema @param {Set<any>} seen @returns {any} */
-function resolveOpenApiSchema(document, schema, seen = new Set()) {
-  if (!schema || typeof schema !== "object") {
-    return null;
-  }
-  if (schema.$ref) {
-    if (seen.has(schema.$ref)) {
-      return null;
-    }
-    seen.add(schema.$ref);
-    if (!schema.$ref.startsWith("#/")) {
-      return null;
-    }
-    const segments = schema.$ref.slice(2).split("/");
-    let current = document;
-    for (const segment of segments) {
-      current = current?.[segment];
-      if (current == null) {
-        return null;
-      }
-    }
-    return resolveOpenApiSchema(document, current, seen) || current;
-  }
-  return schema;
-}
-
-/** @param {WorkflowRecord} document @param {WorkflowRecord} schema @param {Set<any>} fields @param {Set<any>} seen @returns {any} */
-function collectOpenApiObjectFields(document, schema, fields = new Set(), seen = new Set()) {
-  const resolved = resolveOpenApiSchema(document, schema, seen);
-  if (!resolved || typeof resolved !== "object") {
-    return fields;
-  }
-  if (resolved.type === "array" && resolved.items) {
-    collectOpenApiObjectFields(document, resolved.items, fields, seen);
-    return fields;
-  }
-  for (const propertyName of Object.keys(resolved.properties || {})) {
-    fields.add(propertyName);
-  }
-  for (const entry of resolved.allOf || []) {
-    collectOpenApiObjectFields(document, entry, fields, seen);
-  }
-  for (const entry of resolved.oneOf || []) {
-    collectOpenApiObjectFields(document, entry, fields, seen);
-  }
-  for (const entry of resolved.anyOf || []) {
-    collectOpenApiObjectFields(document, entry, fields, seen);
-  }
-  return fields;
-}
-
-/** @param {WorkflowRecord} document @param {WorkflowRecord} schema @returns {any} */
-function extractOpenApiSchemaFieldHints(document, schema) {
-  const fieldNames = [...collectOpenApiObjectFields(document, schema)].sort();
-  return {
-    schema_ref: openApiRefName(schema?.$ref || null),
-    body_fields: fieldNames
-  };
-}
-
-/** @param {string} endpointPath @param {WorkflowRecord} operation @returns {any} */
-function collectOpenApiParameters(endpointPath, operation) {
-  const pathParams = [...String(endpointPath || "").matchAll(/\{([^}]+)\}/g)].map((/** @type {any} */ match) => ({
-    name: match[1],
-    in: "path",
-    required: true
-  }));
-  return [...pathParams, ...((operation.parameters || []).filter(Boolean))];
-}
-
-/** @param {WorkflowRecord} document @param {string} endpointPath @param {WorkflowRecord} operation @returns {any} */
-function extractOpenApiParameterHints(document, endpointPath, operation) {
-  /** @type {WorkflowRecord} */
-  const grouped = {
-    path: [],
-    query: [],
-    header: []
-  };
-  for (const parameter of collectOpenApiParameters(endpointPath, operation)) {
-    const schema = resolveOpenApiSchema(document, parameter.schema || null);
-    const target = parameter.in === "query" ? "query" : parameter.in === "header" ? "header" : "path";
-    grouped[target].push({
-      name: parameter.name,
-      required: Boolean(parameter.required),
-      type: schema?.type || null
-    });
-  }
-  for (const key of Object.keys(grouped)) {
-    grouped[key] = grouped[key].sort((/** @type {any} */ a, /** @type {any} */ b) => a.name.localeCompare(b.name));
-  }
-  return grouped;
-}
-
-/** @param {WorkflowRecord} document @param {WorkflowRecord} operation @returns {any} */
-function extractOpenApiSecuritySchemes(document, operation) {
-  const securityEntries = [...(operation.security || []), ...(document.security || [])];
-  const schemes = new Set();
-  for (const entry of securityEntries) {
-    for (const key of Object.keys(entry || {})) {
-      schemes.add(key);
-    }
-  }
-  return [...schemes].sort();
-}
-
-/** @param {string} text @returns {any} */
-function parseOpenApiYaml(text) {
-  /** @type {WorkflowRecord} */
-  const doc = { paths: {} };
-  let currentPath = null;
-  let currentMethod = null;
-  let inRequestBody = false;
-  let inResponses = false;
-  let currentResponseStatus = null;
-
-  for (const rawLine of text.split(/\r?\n/)) {
-    const line = rawLine.replace(/#.*$/, "");
-    if (!line.trim()) {
-      continue;
-    }
-    const pathMatch = line.match(/^\s{2}(\/[^:]+):\s*$/);
-    if (pathMatch) {
-      currentPath = pathMatch[1];
-      currentMethod = null;
-      doc.paths[currentPath] = doc.paths[currentPath] || {};
-      inRequestBody = false;
-      inResponses = false;
-      currentResponseStatus = null;
-      continue;
-    }
-    const methodMatch = line.match(/^\s{4}(get|post|put|patch|delete):\s*$/i);
-    if (methodMatch && currentPath) {
-      currentMethod = methodMatch[1].toLowerCase();
-      doc.paths[currentPath][currentMethod] = { responses: {} };
-      inRequestBody = false;
-      inResponses = false;
-      currentResponseStatus = null;
-      continue;
-    }
-    if (!currentPath || !currentMethod) {
-      continue;
-    }
-    const operation = doc.paths[currentPath][currentMethod];
-    const operationIdMatch = line.match(/^\s{6}operationId:\s*(.+)$/);
-    if (operationIdMatch) {
-      operation.operationId = operationIdMatch[1].trim().replace(/^["']|["']$/g, "");
-      continue;
-    }
-    const summaryMatch = line.match(/^\s{6}summary:\s*(.+)$/);
-    if (summaryMatch) {
-      operation.summary = summaryMatch[1].trim().replace(/^["']|["']$/g, "");
-      continue;
-    }
-    if (/^\s{6}requestBody:\s*$/.test(line)) {
-      inRequestBody = true;
-      inResponses = false;
-      currentResponseStatus = null;
-      continue;
-    }
-    if (/^\s{6}responses:\s*$/.test(line)) {
-      inResponses = true;
-      inRequestBody = false;
-      currentResponseStatus = null;
-      continue;
-    }
-    const responseStatusMatch = line.match(/^\s{8}['"]?([0-9Xx]{3})['"]?:\s*$/);
-    if (inResponses && responseStatusMatch) {
-      currentResponseStatus = responseStatusMatch[1];
-      operation.responses[currentResponseStatus] = operation.responses[currentResponseStatus] || {};
-      continue;
-    }
-    const refMatch = line.match(/^\s+\$ref:\s*(.+)$/);
-    if (refMatch) {
-      const ref = refMatch[1].trim().replace(/^["']|["']$/g, "");
-      if (inRequestBody) {
-        operation.requestBody = operation.requestBody || { content: { "application/json": { schema: {} } } };
-        operation.requestBody.content["application/json"].schema.$ref = ref;
-      } else if (inResponses && currentResponseStatus) {
-        operation.responses[currentResponseStatus].content = operation.responses[currentResponseStatus].content || { "application/json": { schema: {} } };
-        operation.responses[currentResponseStatus].content["application/json"].schema.$ref = ref;
-      }
-    }
-  }
-
-  return doc;
-}
-
-/** @param {WorkspacePaths} paths @returns {any} */
-function inferServerRoutes(paths) {
-  /** @type {any[]} */
-  const routes = [];
-  const routeFiles = findImportFiles(
-    paths,
-    (/** @type {any} */ filePath) =>
-      /\.(ts|tsx|js|jsx|mjs|cjs)$/.test(filePath) &&
-      /(server|api|routes|src)/i.test(filePath)
-  );
-  for (const filePath of routeFiles) {
-    const text = readTextIfExists(filePath) || "";
-    for (const match of text.matchAll(/\.(get|post|put|patch|delete)\(\s*["'`]([^"'`]+)["'`]\s*,([\s\S]*?)\)\s*;?/gi)) {
-      const handlerTokens = [...match[3].matchAll(/\b([A-Za-z_][A-Za-z0-9_]*)\b/g)].map((/** @type {any} */ entry) => entry[1]);
-      const handlerHint = handlerTokens.length > 0 ? handlerTokens[handlerTokens.length - 1] : null;
-      const pathParams = [...normalizeOpenApiPath(match[2]).matchAll(/\{([^}]+)\}/g)].map((/** @type {any} */ entry) => entry[1]);
-      const handlerContext = handlerHint ? extractHandlerContext(text, handlerHint) : "";
-      const queryParams = inferRouteQueryParams(handlerContext);
-      const authHint = inferRouteAuthHint(match[3], handlerContext);
-      routes.push({
-        file: filePath,
-        method: match[1].toUpperCase(),
-        path: match[2],
-        handler_hint: handlerHint,
-        path_params: pathParams,
-        query_params: queryParams,
-        auth_hint: authHint
-      });
-    }
-  }
-  return routes;
-}
-
-/** @param {WorkspacePaths} paths @returns {any} */
-function inferNextApiRoutes(paths) {
-  const apiRoot = path.join(paths.workspaceRoot, "app", "api");
-  if (!fs.existsSync(apiRoot)) {
-    return [];
-  }
-  const routeFiles = listFilesRecursive(
-    apiRoot,
-    (/** @type {any} */ child) => /\/route\.(tsx|ts|jsx|js)$/.test(child) || /^route\.(tsx|ts|jsx|js)$/.test(path.basename(child))
-  );
-  /** @type {any[]} */
-  const routes = [];
-  for (const filePath of routeFiles) {
-    const text = readTextIfExists(filePath) || "";
-    const relative = relativeTo(apiRoot, filePath);
-    const routePath = `/${relative}`
-      .replace(/\/route\.(tsx|ts|jsx|js)$/, "")
-      .replace(/\[(\.\.\.)?([^\]]+)\]/g, (/** @type {any} */ _match, /** @type {any} */ catchAll, /** @type {any} */ name) => catchAll ? `:${name}*` : `:${name}`);
-    for (const match of text.matchAll(/export\s+async\s+function\s+(GET|POST|PUT|PATCH|DELETE)\s*\(([^)]*)\)/g)) {
-      const method = match[1].toUpperCase();
-      const handlerContext = extractNamedExportBlock(text, match[1]) || "";
-      const queryParams = inferNextRequestSearchParams(handlerContext);
-      const outputFields = inferNextJsonFields(handlerContext);
-      const authHint = inferRouteAuthHint(match[0], handlerContext);
-      routes.push({
-        file: filePath,
-        method,
-        path: routePath === "" ? "/" : routePath,
-        handler_hint: match[1].toLowerCase(),
-        path_params: [...normalizeOpenApiPath(routePath).matchAll(/\{([^}]+)\}/g)].map((/** @type {any} */ entry) => entry[1]),
-        query_params: queryParams,
-        output_fields: outputFields,
-        auth_hint: authHint,
-        source_kind: "route_code"
-      });
-    }
-  }
-  return routes;
-}
-
-/** @param {any} appRoot @param {string} filePath @returns {any} */
-function nextAppRoutePathFromFile(appRoot, filePath) {
-  const relative = relativeTo(appRoot, filePath);
-  return `/${relative}`
-    .replace(/\/actions\.(tsx|ts|jsx|js)$/, "")
-    .replace(/\/page\.(tsx|ts|jsx|js|mdx)$/, "")
-    .replace(/\[(\.\.\.)?([^\]]+)\]/g, (/** @type {any} */ _match, /** @type {any} */ catchAll, /** @type {any} */ name) => catchAll ? `:${name}*` : `:${name}`)
-    .replace(/\/index$/, "")
-    .replace(/^\/$/, "/") || "/";
-}
-
-/** @param {string} text @returns {any} */
-function inferFormDataFields(text) {
-  const fields = new Set();
-  for (const match of String(text || "").matchAll(/formData\.get\(\s*["'`]([^"'`]+)["'`]\s*\)/g)) {
-    fields.add(match[1]);
-  }
-  return [...fields].sort();
-}
-
-/** @param {string} text @returns {any} */
-function inferInputNames(text) {
-  const fields = new Set();
-  for (const match of String(text || "").matchAll(/\bname=["'`]([^"'`]+)["'`]/g)) {
-    fields.add(match[1]);
-  }
-  return [...fields].sort();
-}
-
-/** @param {WorkspacePaths} paths @returns {any} */
-function inferNextAuthCapabilities(paths) {
-  const authConfigPath = path.join(paths.workspaceRoot, "auth.ts");
-  const authConfigText = readTextIfExists(authConfigPath) || "";
-  const hasCredentialsProvider = /CredentialsProvider\s*\(/.test(authConfigText);
-  const createsUserOnAuthorize = /prisma\.user\.create\s*\(/.test(authConfigText);
-  const loginPagePath = path.join(paths.workspaceRoot, "app", "login", "page.tsx");
-  const registerPagePath = path.join(paths.workspaceRoot, "app", "register", "page.tsx");
-  const pages = [
-    {
-      file: loginPagePath,
-      path: "/login",
-      id_hint: "cap_sign_in_user",
-      label: "Sign In User",
-      target_state: "authenticated"
-    },
-    {
-      file: registerPagePath,
-      path: "/register",
-      id_hint: "cap_register_user",
-      label: "Register User",
-      target_state: createsUserOnAuthorize ? "registered" : "created"
-    }
-  ];
-  /** @type {any[]} */
-  const capabilities = [];
-  for (const page of pages) {
-    const text = readTextIfExists(page.file) || "";
-    if (!text || !/signIn\(\s*["'`]credentials["'`]/.test(text)) {
-      continue;
-    }
-    const inputFields = inferInputNames(text);
-    capabilities.push({
-      file: page.file,
-      function_name: page.id_hint.replace(/^cap_/, ""),
-      method: "POST",
-      path: page.path,
-      id_hint: page.id_hint,
-      label: page.label,
-      input_fields: inputFields,
-      output_fields: [],
-      path_params: [],
-      auth_hint: "public",
-      entity_id: "entity_user",
-      target_state: page.target_state,
-      provenance: [
-        relativeTo(paths.repoRoot, page.file),
-        ...(hasCredentialsProvider ? [relativeTo(paths.repoRoot, authConfigPath)] : [])
-      ],
-      source_kind: "route_code"
-    });
-  }
-  return capabilities.sort((/** @type {any} */ a, /** @type {any} */ b) => a.id_hint.localeCompare(b.id_hint));
-}
-
-/** @param {WorkspacePaths} paths @returns {any} */
-function inferNextServerActionCapabilities(paths) {
-  const appRoot = path.join(paths.workspaceRoot, "app");
-  if (!fs.existsSync(appRoot)) {
-    return [];
-  }
-  const actionFiles = listFilesRecursive(
-    appRoot,
-    (/** @type {any} */ child) =>
-      /\/actions\.(tsx|ts|jsx|js)$/.test(child) ||
-      /\/page\.(tsx|ts|jsx|js|mdx)$/.test(child) ||
-      /^page\.(tsx|ts|jsx|js|mdx)$/.test(path.basename(child))
-  );
-  /** @type {any[]} */
-  const capabilities = [];
-  for (const filePath of actionFiles) {
-    const text = readTextIfExists(filePath) || "";
-    const routePath = nextAppRoutePathFromFile(appRoot, filePath);
-    for (const match of text.matchAll(/(?:export\s+)?async\s+function\s+([A-Za-z_][A-Za-z0-9_]*)\s*\(([^)]*)\)\s*\{([\s\S]{0,2400}?)\n\}/g)) {
-      const functionName = match[1];
-      const body = match[3] || "";
-      const trimmedBody = body.trimStart();
-      const isServerAction =
-        /\/actions\.(tsx|ts|jsx|js)$/.test(filePath) ||
-        trimmedBody.startsWith('"use server"') ||
-        trimmedBody.startsWith("'use server'");
-      if (!isServerAction) {
-        continue;
-      }
-      /** @type {WorkflowRecord} */
-      const routeLike = {
-        file: filePath,
-        method: "POST",
-        path: routePath,
-        handler_hint: functionName,
-        auth_hint: inferRouteAuthHint(functionName, body)
-      };
-      capabilities.push({
-        file: filePath,
-        function_name: functionName,
-        method: "POST",
-        path: routePath,
-        id_hint: inferRouteCapabilityId(routeLike),
-        input_fields: inferFormDataFields(body),
-        output_fields: [],
-        path_params: [...normalizeOpenApiPath(routePath).matchAll(/\{([^}]+)\}/g)].map((/** @type {any} */ entry) => entry[1]),
-        auth_hint: routeLike.auth_hint,
-        entity_id: inferCapabilityEntityId({ endpoint: { path: routePath }, id_hint: inferRouteCapabilityId(routeLike) }),
-        source_kind: "route_code"
-      });
-    }
-  }
-  return capabilities.sort((/** @type {any} */ a, /** @type {any} */ b) => a.id_hint.localeCompare(b.id_hint) || a.path.localeCompare(b.path));
-}
-
-/** @param {string} text @param {string} exportName @returns {any} */
-function extractNamedExportBlock(text, exportName) {
-  const escapedName = exportName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-  const match = text.match(new RegExp(`export\\s+async\\s+function\\s+${escapedName}\\s*\\([^)]*\\)\\s*\\{([\\s\\S]{0,2000}?)\\n\\}`, "m"));
-  return match ? match[1] : "";
-}
-
-/** @param {string} text @returns {any} */
-function inferNextRequestSearchParams(text) {
-  const params = new Set();
-  for (const match of String(text || "").matchAll(/searchParams\.get\(\s*["'`]([^"'`]+)["'`]\s*\)/g)) {
-    params.add(match[1]);
-  }
-  return [...params].sort();
-}
-
-/** @param {string} text @returns {any} */
-function inferNextJsonFields(text) {
-  const fields = new Set();
-  for (const match of String(text || "").matchAll(/NextResponse\.json\(\s*\{([\s\S]{0,400}?)\}\s*\)/g)) {
-    for (const fieldMatch of match[1].matchAll(/\b([A-Za-z_][A-Za-z0-9_]*)\b\s*[:,]/g)) {
-      fields.add(fieldMatch[1]);
-    }
-  }
-  return [...fields].sort();
-}
-
-/** @param {string} text @param {any} handlerName @returns {any} */
-function extractHandlerContext(text, handlerName) {
-  if (!handlerName) {
-    return "";
-  }
-  const escapedName = handlerName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-  const patterns = [
-    new RegExp(`function\\s+${escapedName}\\s*\\([^)]*\\)\\s*\\{([\\s\\S]{0,1200}?)\\n\\}`, "m"),
-    new RegExp(`const\\s+${escapedName}\\s*=\\s*(?:async\\s*)?\\([^)]*\\)\\s*=>\\s*\\{([\\s\\S]{0,1200}?)\\n\\}`, "m")
-  ];
-  for (const pattern of patterns) {
-    const match = text.match(pattern);
-    if (match) {
-      return match[1];
-    }
-  }
-  return "";
-}
-
-/** @param {string} text @returns {any} */
-function inferRouteQueryParams(text) {
-  const params = new Set();
-  for (const match of String(text || "").matchAll(/\bquery\s*\(\s*["'`]([^"'`]+)["'`]\s*\)/g)) {
-    params.add(match[1]);
-  }
-  for (const match of String(text || "").matchAll(/\bquery\.([A-Za-z_][A-Za-z0-9_]*)\b/g)) {
-    params.add(match[1]);
-  }
-  return [...params].sort();
-}
-
-/** @param {any[]} routeArguments @param {any} handlerContext @returns {any} */
-function inferRouteAuthHint(routeArguments, handlerContext) {
-  const combined = `${routeArguments || ""}\n${handlerContext || ""}`.toLowerCase();
-  return /\b(auth|session|permission|guard|protected|require_auth|requireauth|ensureauth)\b/.test(combined)
-    ? "secured"
-    : "unknown";
-}
-
-/** @param {WorkflowRecord} route @returns {any} */
-function inferRouteCapabilityId(route) {
-  if (route.handler_hint) {
-    const genericHttpHandler = /^(get|post|put|patch|delete)$/i.test(route.handler_hint);
-    if (!genericHttpHandler) {
-      const normalizedHandler = route.handler_hint
-        .replace(/^(handle|on)/i, "")
-        .replace(/(handler|route|controller|action)$/i, "");
-      const handlerTokens = normalizedHandler
-        .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
-        .split(/[^A-Za-z0-9]+/)
-        .filter(Boolean)
-        .map((/** @type {any} */ token) => token.toLowerCase());
-      if (handlerTokens.length > 0) {
-        return `cap_${handlerTokens.join("_")}`;
-      }
-    }
-  }
-  const method = String(route.method || "").toUpperCase();
-  const segments = routeSegments(normalizeOpenApiPath(route.path));
-  const resource = canonicalCandidateTerm(segments[0] || "item");
-  if (method === "GET" && segments.length <= 1) {
-    return `cap_list_${resource}s`;
-  }
-  if (method === "GET" && segments.length > 1) {
-    return `cap_get_${resource}`;
-  }
-  if (method === "POST") {
-    return `cap_create_${resource}`;
-  }
-  if (method === "PATCH" || method === "PUT") {
-    return `cap_update_${resource}`;
-  }
-  if (method === "DELETE") {
-    return `cap_delete_${resource}`;
-  }
-  return `candidate_${route.method.toLowerCase()}_${slugify(route.path)}`;
-}
-
-/** @param {WorkspacePaths} paths @returns {any} */
-export function collectApiImport(paths) {
-  /** @type {any[]} */
-  const findings = [];
-  /** @type {WorkflowRecord} */
-  const candidates = {
-    capabilities: [],
-    routes: [],
-    stacks: []
-  };
-  const { openApiFiles } = discoverApiSources(paths);
-  let usedOpenApi = false;
-  for (const filePath of openApiFiles) {
-    const provenance = relativeTo(paths.repoRoot, filePath);
-    const text = readTextIfExists(filePath) || "";
-    const document = filePath.endsWith(".json") ? JSON.parse(text) : parseOpenApiYaml(text);
-    const parsed = parseOpenApiDocument(document, provenance, "openapi");
-    usedOpenApi = true;
-    findings.push({
-      kind: "openapi",
-      file: provenance,
-      capability_count: parsed.capabilities.length
-    });
-    candidates.capabilities.push(...parsed.capabilities);
-    candidates.routes.push(...parsed.routes.map((/** @type {any} */ route) => ({
-      path: route.path,
-      method: route.method,
-      confidence: "high",
-      source_kind: route.source_kind,
-      provenance: route.provenance
-    })));
-  }
-  if (!usedOpenApi) {
-    const inferredRoutes = [
-      ...inferNextApiRoutes(paths),
-      ...inferServerRoutes(paths)
-    ];
-    const inferredServerActions = inferNextServerActionCapabilities(paths);
-    const inferredAuthCapabilities = inferNextAuthCapabilities(paths);
-    if (inferredRoutes.length > 0) {
-      findings.push({
-        kind: "route_inventory",
-        files: [...new Set(inferredRoutes.map((/** @type {any} */ route) => relativeTo(paths.repoRoot, route.file)))],
-        route_count: inferredRoutes.length
-      });
-      candidates.capabilities.push(
-        ...inferredRoutes.map((/** @type {any} */ route) =>
-          makeCandidateRecord({
-            kind: "capability",
-            idHint: inferRouteCapabilityId(route),
-            label: `${route.method} ${route.path}`,
-            confidence: "medium",
-            sourceKind: "route_code",
-            provenance: `${relativeTo(paths.repoRoot, route.file)}#${route.method} ${route.path}`,
-            endpoint: {
-              method: route.method,
-              path: normalizeOpenApiPath(route.path)
-            },
-            path_params: (route.path_params || []).map((/** @type {any} */ name) => ({ name, required: true, type: null })),
-            query_params: (route.query_params || []).map((/** @type {any} */ name) => ({ name, required: false, type: null })),
-            header_params: [],
-            input_fields: [],
-            output_fields: route.output_fields || [],
-            auth_hint: route.auth_hint || "unknown"
-          })
-        )
-      );
-      candidates.routes.push(
-        ...inferredRoutes.map((/** @type {any} */ route) => ({
-          path: normalizeOpenApiPath(route.path),
-          method: route.method,
-          confidence: "medium",
-          source_kind: "route_code",
-          provenance: `${relativeTo(paths.repoRoot, route.file)}#${route.method} ${route.path}`
-        }))
-      );
-    }
-    if (inferredServerActions.length > 0) {
-      findings.push({
-        kind: "next_server_actions",
-        files: [...new Set(inferredServerActions.map((/** @type {any} */ action) => relativeTo(paths.repoRoot, action.file)))],
-        action_count: inferredServerActions.length
-      });
-      candidates.capabilities.push(
-        ...inferredServerActions.map((/** @type {any} */ action) =>
-          makeCandidateRecord({
-            kind: "capability",
-            idHint: action.id_hint,
-            label: titleCase(action.id_hint.replace(/^cap_/, "")),
-            confidence: "medium",
-            sourceKind: action.source_kind,
-            provenance: `${relativeTo(paths.repoRoot, action.file)}#${action.function_name}`,
-            endpoint: {
-              method: action.method,
-              path: normalizeOpenApiPath(action.path)
-            },
-            path_params: (action.path_params || []).map((/** @type {any} */ name) => ({ name, required: true, type: null })),
-            query_params: [],
-            header_params: [],
-            input_fields: action.input_fields || [],
-            output_fields: action.output_fields || [],
-            auth_hint: action.auth_hint || "unknown"
-          })
-        )
-      );
-      candidates.routes.push(
-        ...inferredServerActions.map((/** @type {any} */ action) => ({
-          path: normalizeOpenApiPath(action.path),
-          method: action.method,
-          confidence: "medium",
-          source_kind: action.source_kind,
-          provenance: `${relativeTo(paths.repoRoot, action.file)}#${action.function_name}`
-        }))
-      );
-    }
-    if (inferredAuthCapabilities.length > 0) {
-      findings.push({
-        kind: "next_auth_flows",
-        files: [...new Set(inferredAuthCapabilities.flatMap((/** @type {any} */ capability) => capability.provenance || []))],
-        capability_count: inferredAuthCapabilities.length
-      });
-      candidates.capabilities.push(
-        ...inferredAuthCapabilities.map((/** @type {any} */ capability) =>
-          makeCandidateRecord({
-            kind: "capability",
-            idHint: capability.id_hint,
-            label: capability.label,
-            confidence: "medium",
-            sourceKind: capability.source_kind,
-            provenance: capability.provenance,
-            endpoint: {
-              method: capability.method,
-              path: normalizeOpenApiPath(capability.path)
-            },
-            path_params: [],
-            query_params: [],
-            header_params: [],
-            input_fields: capability.input_fields || [],
-            output_fields: capability.output_fields || [],
-            auth_hint: capability.auth_hint || "unknown",
-            entity_id: capability.entity_id,
-            target_state: capability.target_state || null
-          })
-        )
-      );
-      candidates.routes.push(
-        ...inferredAuthCapabilities.map((/** @type {any} */ capability) => ({
-          path: normalizeOpenApiPath(capability.path),
-          method: capability.method,
-          confidence: "medium",
-          source_kind: capability.source_kind,
-          provenance: capability.provenance
-        }))
-      );
-    }
-  }
-  const reactRoutes = inferReactRoutes(path.join(paths.workspaceRoot, "apps", "web"));
-  if (reactRoutes.length > 0) {
-    findings.push({
-      kind: "react_routes",
-      file: relativeTo(paths.repoRoot, path.join(paths.workspaceRoot, "apps", "web", "src", "App.tsx")),
-      routes: reactRoutes
-    });
-    candidates.routes.push(...reactRoutes.map((/** @type {any} */ route) => ({
-      path: route,
-      method: "GET",
-      confidence: "medium",
-      source_kind: "generated_artifact",
-      provenance: relativeTo(paths.repoRoot, path.join(paths.workspaceRoot, "apps", "web", "src", "App.tsx"))
-    })));
-    candidates.stacks.push("react_web");
-  }
-  const svelteRoutes = inferSvelteRoutes(path.join(paths.workspaceRoot, "apps", "web-sveltekit"));
-  if (svelteRoutes.length > 0) {
-    findings.push({
-      kind: "sveltekit_routes",
-      file: relativeTo(paths.repoRoot, path.join(paths.workspaceRoot, "apps", "web-sveltekit", "src", "routes")),
-      routes: svelteRoutes
-    });
-    candidates.routes.push(...svelteRoutes.map((/** @type {any} */ route) => ({
-      path: route,
-      method: "GET",
-      confidence: "medium",
-      source_kind: "generated_artifact",
-      provenance: relativeTo(paths.repoRoot, path.join(paths.workspaceRoot, "apps", "web-sveltekit", "src", "routes"))
-    })));
-    candidates.stacks.push("sveltekit_web");
-  }
-  candidates.capabilities = dedupeCandidateRecords(candidates.capabilities, (/** @type {any} */ record) => record.id_hint);
-  candidates.routes = dedupeCandidateRecords(
-    candidates.routes.map((/** @type {any} */ route) => ({
-      ...route,
-      id_hint: route.id_hint || `${route.method}_${route.path}`
-    })),
-    (/** @type {any} */ record) => `${record.method}:${record.path}:${record.source_kind}`
-  ).map((/** @type {any} */ record) => {
-    const { id_hint, ...route } = record;
-    return route;
-  });
-
-  return { findings, candidates };
-}
+export { collectApiImport } from "./api/collect.js";
+export { discoverApiSources } from "./api/sources.js";