@genn-inc/cluebase-cli 0.0.1

package/src/setup-repository-discovery.mjs

@@ -0,0 +1,764 @@
+import { readdir, readFile } from "node:fs/promises";
+import { dirname, join, relative, resolve } from "node:path";
+import {
+  listAllowedPythonFiles,
+  listAllowedSourceFiles,
+} from "./path-policy.mjs";
+import {
+  BACKEND_SDK_BY_FRAMEWORK,
+  SOURCE_EXTENSIONS,
+} from "./setup-check-constants.mjs";
+import { CODE_EVIDENCE_ROUTE_METHODS } from "./generated-code-evidence-contract.mjs";
+import { stripSourceNoise } from "./lifecycle-guard.mjs";
+
+// Cluebase setup discovery detects instrumentable services mechanically.
+//
+// Deterministic scope (CLI-owned): language + framework + service root, decided
+// from dependency manifests and framework import signals. The normalized setup
+// contract below additionally identifies a unique bootstrap and lifecycle
+// boundary when source evidence makes that safe; ambiguous boundaries remain
+// unresolved for the setup caller.
+
+const deriveServiceKeyFromPath = (rootPath) => {
+  const segment = rootPath
+    .split("/")
+    .map((part) => part.trim())
+    .filter(Boolean)
+    .at(-1);
+  const normalized = segment
+    ?.toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return normalized || "backend";
+};
+
+const commonDirectory = (paths) => {
+  const directories = paths.map((path) =>
+    dirname(path)
+      .split(/[\\/]+/)
+      .filter(Boolean),
+  );
+  if (directories.length === 0) return ".";
+  const common = [];
+  for (let index = 0; index < directories[0].length; index += 1) {
+    const part = directories[0][index];
+    if (directories.every((directory) => directory[index] === part)) {
+      common.push(part);
+      continue;
+    }
+    break;
+  }
+  return common.length ? common.join("/") : ".";
+};
+
+const isPathInsideOrEqual = (childPath, parentPath) =>
+  childPath === parentPath ||
+  parentPath === "." ||
+  childPath.startsWith(`${parentPath}/`);
+
+const ignoredScanDirs = new Set([
+  ".git",
+  ".next",
+  ".turbo",
+  ".venv",
+  "coverage",
+  "dist",
+  "build",
+  "node_modules",
+  "__pycache__",
+  "vendor",
+]);
+
+const PYTHON_MANIFEST_FILES = new Set([
+  "requirements.txt",
+  "requirements-dev.txt",
+  "pyproject.toml",
+  "Pipfile",
+  "setup.py",
+  "setup.cfg",
+]);
+
+const isTestSourcePath = (file) => {
+  const parts = file.split("/").filter(Boolean);
+  return (
+    parts.some((part) => /^(?:test|tests|__tests__|spec)$/i.test(part)) ||
+    /(?:^|\/)(?:test_[^/]+|[^/]+_test\.[^/]+)$/i.test(file)
+  );
+};
+
+const AUTH_BOUNDARY_FILE_PATTERN =
+  /(?:^|\/)(?:auth|authentication|login|signin|sign-in)(?:[._-]|\/|$)/i;
+const AUTH_BOUNDARY_SOURCE_PATTERN =
+  /\b(?:OAuth2(?:Password)?(?:Bearer|RequestForm)?|HTTPBearer|create_access_token|authenticate|sign[_-]?in|login[A-Za-z_$]*)\b/;
+const AUTH_BOUNDARY_ROUTE_PATTERN =
+  /\.\s*(?:get|post|put|patch|api_route)\s*\(\s*["'`][^"'`]*(?:auth|login|sign[-_ ]?in)[^"'`]*["'`]/i;
+
+// Backend framework signals are language/framework labels for documentation
+// selection, matched against declared dependency names or import statements.
+// They are not route parsers. First match wins.
+const PYTHON_FRAMEWORKS = [
+  "fastapi",
+  "django",
+  "flask",
+  "starlette",
+  "sanic",
+  "aiohttp",
+  "tornado",
+  "quart",
+  "falcon",
+];
+// Framework-agnostic Python server runtimes: presence in a manifest proves a
+// runnable backend even when the web framework is unrecognized.
+const PYTHON_SERVER_RUNTIMES = ["uvicorn", "gunicorn", "hypercorn", "daphne"];
+
+const NODE_BACKEND_FRAMEWORK_SIGNALS = [
+  ["@nestjs/core", "nestjs"],
+  ["express", "express"],
+  ["fastify", "fastify"],
+  ["koa", "koa"],
+  ["@hapi/hapi", "hapi"],
+  ["hapi", "hapi"],
+  ["restify", "restify"],
+  ["@adonisjs/core", "adonisjs"],
+];
+
+const FRONTEND_FRAMEWORK_SIGNALS = [
+  ["next", "nextjs"],
+  ["@sveltejs/kit", "sveltekit"],
+  ["nuxt", "nuxt"],
+  ["@angular/core", "angular"],
+  ["vite", "vite"],
+  ["vue", "vue"],
+  ["react", "react"],
+];
+
+const listFilesByName = async ({ repoRoot, names, currentPath = "." }) => {
+  const absolutePath = join(repoRoot, currentPath);
+  const entries = await readdir(absolutePath, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      if (ignoredScanDirs.has(entry.name)) continue;
+      files.push(
+        ...(await listFilesByName({
+          repoRoot,
+          names,
+          currentPath: join(currentPath, entry.name),
+        })),
+      );
+      continue;
+    }
+    if (entry.isFile() && names.has(entry.name)) {
+      files.push(join(currentPath, entry.name));
+    }
+  }
+  return files;
+};
+
+const readJsonFile = async (path) => JSON.parse(await readFile(path, "utf8"));
+
+const packageDependencyNames = (packageJson) =>
+  new Set([
+    ...Object.keys(packageJson.dependencies ?? {}),
+    ...Object.keys(packageJson.devDependencies ?? {}),
+  ]);
+
+const detectFramework = (signals, dependencyNames) => {
+  for (const [dependency, framework] of signals) {
+    if (dependencyNames.has(dependency)) return framework;
+  }
+  return null;
+};
+
+// Declared package names from a Python dependency manifest. Matches
+// requirements-style pins, Pipfile / pyproject tables, and PEP 621 arrays
+// closely enough to recognize known framework and runtime names.
+const pythonDeclaredPackages = (manifestText) => {
+  const names = new Set();
+  for (const rawLine of manifestText.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+    const match = line.match(/["']?([A-Za-z0-9_.-]+)/);
+    if (match) names.add(match[1].toLowerCase());
+  }
+  return names;
+};
+
+const pythonFrameworkFromImports = (source) => {
+  for (const framework of PYTHON_FRAMEWORKS) {
+    const importPattern = new RegExp(
+      String.raw`(^|\n)\s*(from\s+${framework}\b|import\s+${framework}\b)`,
+    );
+    if (importPattern.test(source)) return framework;
+  }
+  return null;
+};
+
+const normalizeTargetId = ({ name, fallbackPath }) => {
+  const source = typeof name === "string" && name ? name : fallbackPath;
+  const segment = source.split("/").at(-1) ?? source;
+  return segment
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+};
+
+const portFromScripts = (scripts) => {
+  const scriptText = Object.values(scripts ?? {})
+    .filter((value) => typeof value === "string")
+    .join("\n");
+  const portFlag = scriptText.match(/(?:--port|-p)\s+(\d{2,5})/);
+  if (portFlag) return portFlag[1];
+  const envPort = scriptText.match(/(?:^|\s)PORT=(\d{2,5})(?:\s|$)/);
+  return envPort?.[1] ?? null;
+};
+
+const backendService = ({ language, framework, rootPath }) => ({
+  kind: "backend",
+  language,
+  framework,
+  root_path: rootPath,
+  service_key: deriveServiceKeyFromPath(rootPath),
+  local_url_candidates: [],
+});
+
+const detectServicesFromPackageJson = async ({ repoRoot }) => {
+  const packageJsonFiles = await listFilesByName({
+    repoRoot,
+    names: new Set(["package.json"]),
+  });
+  const frontend = [];
+  const backend = [];
+  for (const packageJsonFile of packageJsonFiles) {
+    const packageJson = await readJsonFile(join(repoRoot, packageJsonFile));
+    const dependencyNames = packageDependencyNames(packageJson);
+    const rootPath = dirname(packageJsonFile);
+    const frontendFramework = detectFramework(
+      FRONTEND_FRAMEWORK_SIGNALS,
+      dependencyNames,
+    );
+    if (frontendFramework) {
+      const targetId = normalizeTargetId({
+        name: packageJson.name,
+        fallbackPath: packageJsonFile,
+      });
+      if (targetId) {
+        const port = portFromScripts(packageJson.scripts);
+        frontend.push({
+          kind: "frontend",
+          language: "node",
+          framework: frontendFramework,
+          root_path: rootPath,
+          target_id: targetId,
+          local_url_candidates: port ? [`http://localhost:${port}`] : [],
+        });
+      }
+    }
+    const backendFramework = detectFramework(
+      NODE_BACKEND_FRAMEWORK_SIGNALS,
+      dependencyNames,
+    );
+    if (backendFramework) {
+      backend.push(
+        backendService({
+          language: "node",
+          framework: backendFramework,
+          rootPath,
+        }),
+      );
+    }
+  }
+  return { frontend, backend };
+};
+
+// Python backends from framework import signals in source. Root is the common
+// directory of the files importing a given framework, so a nested app package
+// resolves to its own root rather than the repository root.
+const detectPythonBackendsFromSource = async ({ repoRoot }) => {
+  const files = await listAllowedPythonFiles({
+    repoRoot,
+    allowedSourcePaths: ["."],
+    excludedSourcePaths: [],
+  });
+  const relativeFilesByFramework = new Map();
+  for (const absolutePath of files) {
+    const relativePath = relative(repoRoot, absolutePath).replaceAll("\\", "/");
+    if (isTestSourcePath(relativePath)) continue;
+    const framework = pythonFrameworkFromImports(
+      await readFile(absolutePath, "utf8"),
+    );
+    if (!framework) continue;
+    const collected = relativeFilesByFramework.get(framework) ?? [];
+    collected.push(relativePath);
+    relativeFilesByFramework.set(framework, collected);
+  }
+  return [...relativeFilesByFramework.entries()].map(([framework, files]) =>
+    backendService({
+      language: "python",
+      framework,
+      rootPath: commonDirectory(files),
+    }),
+  );
+};
+
+// Python backends declared in dependency manifests, used to catch backends
+// whose framework import was not directly visible in scanned source.
+const detectPythonBackendsFromManifests = async ({ repoRoot }) => {
+  const manifestFiles = await listFilesByName({
+    repoRoot,
+    names: PYTHON_MANIFEST_FILES,
+  });
+  const backendsByRoot = new Map();
+  for (const manifestFile of manifestFiles) {
+    const declaredPackages = pythonDeclaredPackages(
+      await readFile(join(repoRoot, manifestFile), "utf8"),
+    );
+    const framework = PYTHON_FRAMEWORKS.find((name) =>
+      declaredPackages.has(name),
+    );
+    const hasServerRuntime = PYTHON_SERVER_RUNTIMES.some((runtime) =>
+      declaredPackages.has(runtime),
+    );
+    if (!framework && !hasServerRuntime) continue;
+    const rootPath = dirname(manifestFile);
+    const existing = backendsByRoot.get(rootPath);
+    if (existing && (existing.framework !== "python" || !framework)) continue;
+    backendsByRoot.set(
+      rootPath,
+      backendService({
+        language: "python",
+        framework: framework ?? "python",
+        rootPath,
+      }),
+    );
+  }
+  return [...backendsByRoot.values()];
+};
+
+// Merge source-derived and manifest-derived Python backends. Source roots are
+// more precise, so a manifest backend is added only when it does not overlap a
+// source-detected root.
+const mergePythonBackends = (sourceBackends, manifestBackends) => {
+  const merged = [...sourceBackends];
+  for (const manifestBackend of manifestBackends) {
+    const overlaps = merged.some(
+      (existing) =>
+        isPathInsideOrEqual(existing.root_path, manifestBackend.root_path) ||
+        isPathInsideOrEqual(manifestBackend.root_path, existing.root_path),
+    );
+    if (!overlaps) merged.push(manifestBackend);
+  }
+  return merged;
+};
+
+export const discoverSetupRepository = async ({ repoRoot }) => {
+  const resolvedRepoRoot = resolve(repoRoot ?? ".");
+  const packageServices = await detectServicesFromPackageJson({
+    repoRoot: resolvedRepoRoot,
+  });
+  const pythonBackends = mergePythonBackends(
+    await detectPythonBackendsFromSource({ repoRoot: resolvedRepoRoot }),
+    await detectPythonBackendsFromManifests({ repoRoot: resolvedRepoRoot }),
+  );
+
+  const frontend = packageServices.frontend.sort((left, right) =>
+    left.target_id.localeCompare(right.target_id),
+  );
+  const backend = [...pythonBackends, ...packageServices.backend].sort(
+    (left, right) => left.service_key.localeCompare(right.service_key),
+  );
+
+  const detected = frontend.length > 0 || backend.length > 0;
+  const candidates = backend.map((service) => ({
+    framework: service.framework,
+    language: service.language,
+    backend_root_path: service.root_path,
+    service_key: service.service_key,
+  }));
+
+  return {
+    detected,
+    blockers: detected
+      ? []
+      : [
+          {
+            code: "NO_INSTRUMENTABLE_SERVICE",
+            message:
+              "No frontend or backend service was detected. Add a supported frontend or backend service, or use the universal HTTP ingest contract directly.",
+          },
+        ],
+    candidates,
+    services: {
+      frontend,
+      backend,
+    },
+    repo_root: relative(process.cwd(), resolvedRepoRoot) || ".",
+  };
+};
+
+const sourceLineFor = (source, index) =>
+  source.slice(0, index).split("\n").length;
+
+const JS_FUNCTION_BOUNDARY_PATTERN =
+  /(?:^|\n)\s*(?:(?:export\s+)?(?:default\s+)?(?:async\s+)?function\s+([A-Za-z_$][\w$]*)|(?:export\s+)?(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s*)?(?:\([^\n)]*\)|[A-Za-z_$][\w$]*)\s*=>)/gm;
+const PYTHON_FUNCTION_BOUNDARY_PATTERN =
+  /(?:^|\n)\s*(?:async\s+)?def\s+([A-Za-z_][\w]*)\s*\(/gm;
+const ROUTE_BOUNDARY_PATTERN =
+  /(?:^|\n)\s*([A-Za-z_$][\w$]*)\.(get|post|put|patch|delete|options|head|trace|api_route)\s*\(\s*(["'`])([^"'`]+)\3/gim;
+const JS_CLASS_BOUNDARY_PATTERN =
+  /(?:^|\n)\s*(?:(?:export\s+)?(?:default\s+)?class)\s+([A-Za-z_$][\w$]*)\b/gm;
+const NEST_ROUTE_METHOD_NAMES = CODE_EVIDENCE_ROUTE_METHODS.map(
+  (method) => `${method[0]}${method.slice(1).toLowerCase()}`,
+).join("|");
+const NEST_METHOD_BOUNDARY_PATTERN = new RegExp(
+  String.raw`(?:^|\n)\s*@(${NEST_ROUTE_METHOD_NAMES})\s*(?:\(\s*(?:(['"\`])([^'"\`]*?)\2)?\s*\))?\s*(?:(?:public|private|protected|static|readonly)\s+)*(?:async\s+)?([A-Za-z_$][\w$]*)\s*\(`,
+  "gm",
+);
+
+const boundaryCandidatesFor = (source) => {
+  const candidates = [];
+  const classes = [];
+  JS_CLASS_BOUNDARY_PATTERN.lastIndex = 0;
+  for (const match of source.matchAll(JS_CLASS_BOUNDARY_PATTERN)) {
+    classes.push({ index: match.index ?? 0, name: match[1] });
+  }
+  for (const pattern of [
+    JS_FUNCTION_BOUNDARY_PATTERN,
+    PYTHON_FUNCTION_BOUNDARY_PATTERN,
+  ]) {
+    pattern.lastIndex = 0;
+    for (const match of source.matchAll(pattern)) {
+      candidates.push({
+        index: match.index ?? 0,
+        name: match[1] ?? match[2],
+        key: `function:${match[1] ?? match[2]}`,
+      });
+    }
+  }
+  ROUTE_BOUNDARY_PATTERN.lastIndex = 0;
+  for (const match of source.matchAll(ROUTE_BOUNDARY_PATTERN)) {
+    candidates.push({
+      index: match.index ?? 0,
+      name: `${match[2].toUpperCase()} ${match[4]}`,
+      key: `route:${match[2].toUpperCase()}:${match[4]}`,
+    });
+  }
+  NEST_METHOD_BOUNDARY_PATTERN.lastIndex = 0;
+  for (const match of source.matchAll(NEST_METHOD_BOUNDARY_PATTERN)) {
+    const classBoundary = classes
+      .filter((candidate) => candidate.index <= (match.index ?? 0))
+      .at(-1);
+    if (!classBoundary) continue;
+    candidates.push({
+      index: match.index ?? 0,
+      name: `${match[1].toUpperCase()} ${match[3] || "<controller-root>"} :: ${match[4]}`,
+      key: `nest:${classBoundary.name}:${match[4]}`,
+    });
+  }
+  return candidates.sort((left, right) => left.index - right.index);
+};
+
+const boundaryAt = (source, index) => {
+  const candidates = boundaryCandidatesFor(source).filter(
+    (candidate) => candidate.index <= index,
+  );
+  const candidate = candidates.at(-1);
+  return candidate ?? { index: 0, name: null, key: "file" };
+};
+
+const sourceFilesForSetupDiscovery = async (repoRoot) => {
+  const files = await listAllowedSourceFiles({
+    repoRoot,
+    allowedSourcePaths: ["."],
+    excludedSourcePaths: [],
+    extensions: SOURCE_EXTENSIONS,
+  });
+  return Promise.all(
+    files.map(async (absolutePath) => ({
+      file: relative(resolve(repoRoot), absolutePath).replaceAll("\\", "/"),
+      source: await readFile(absolutePath, "utf8"),
+    })),
+  );
+};
+
+const firstIndex = (source, patterns) => {
+  const matches = patterns
+    .map((pattern) => {
+      const index = source.search(pattern);
+      return index < 0 ? null : index;
+    })
+    .filter((index) => index !== null);
+  return matches.length === 0 ? -1 : Math.min(...matches);
+};
+
+const siteAt = ({
+  file,
+  source,
+  index,
+  availableFields,
+  groupOwnerKind,
+  boundary,
+}) => ({
+  file,
+  line: sourceLineFor(source, index),
+  rationale:
+    "Existing application lifecycle boundary identified by setup discovery.",
+  evidenceSnippet: source
+    .slice(Math.max(0, index - 80), Math.min(source.length, index + 180))
+    .trim(),
+  ...(availableFields ? { availableFields } : {}),
+  ...(groupOwnerKind ? { groupOwnerKind } : {}),
+  ...(boundary?.name ? { symbol: boundary.name } : {}),
+});
+
+const uniqueSite = (sites) => (sites.length === 1 ? sites[0] : null);
+
+const setupSourceCandidates = (files, detection) => {
+  const backendRoots = (detection.services?.backend ?? []).map(
+    (service) => service.root_path,
+  );
+  return files.filter(({ file }) =>
+    !isTestSourcePath(file) &&
+    backendRoots.some(
+      (rootPath) =>
+        rootPath === "." ||
+        file === rootPath ||
+        file.startsWith(`${rootPath}/`),
+    ),
+  );
+};
+
+const lifecycleSitesFor = (files) => {
+  const identifyCandidates = [];
+  const groupCandidates = [];
+  const resetCandidates = [];
+  for (const { file, source } of files) {
+    const boundaries = boundaryCandidatesFor(source);
+    const lifecycleCandidates = (pattern) => {
+      pattern.lastIndex = 0;
+      const seen = new Set();
+      return [...source.matchAll(pattern)].flatMap((match) => {
+        const index = match.index ?? 0;
+        const boundary = boundaryAt(source, index);
+        if (seen.has(boundary.key)) return [];
+        seen.add(boundary.key);
+        return [{ index, boundary }];
+      });
+    };
+    const executableSource = stripSourceNoise(source, { stripStrings: true });
+    const isAuthBoundary =
+      AUTH_BOUNDARY_FILE_PATTERN.test(file) ||
+      AUTH_BOUNDARY_SOURCE_PATTERN.test(executableSource) ||
+      AUTH_BOUNDARY_ROUTE_PATTERN.test(source);
+    const userReferencePattern =
+      /\b(?:user|account|currentUser|session\??\.user)\s*(?:\.\s*id|\[\s*["']id["']\s*\])/gi;
+    const userCandidates = lifecycleCandidates(userReferencePattern);
+    if (isAuthBoundary && userCandidates.length > 0) {
+      for (const { index: userIndex, boundary } of userCandidates) {
+        const boundaryEnd = boundaries.find(
+          (candidate) => candidate.index > boundary.index,
+        )?.index ?? source.length;
+        const idMatch = source
+          .slice(userIndex, boundaryEnd)
+          .match(userReferencePattern);
+        const nameMatch = source
+          .slice(userIndex, boundaryEnd)
+          .match(
+            /\b(?:user|account|currentUser|session\??\.user)\s*(?:\.\s*(?:name|displayName)|\[\s*["'](?:name|displayName)["']\s*\])/i,
+          );
+        if (idMatch) {
+          identifyCandidates.push(
+            siteAt({
+              file,
+              source,
+              index: userIndex,
+              boundary,
+              availableFields: {
+                id: idMatch[0],
+                ...(nameMatch ? { name: nameMatch[0] } : {}),
+              },
+            }),
+          );
+        }
+      }
+    }
+
+    const organizationReferencePattern =
+      /\b(?:organization|org)\s*(?:\.\s*id|\[\s*["']id["']\s*\])|\b(?:organizationId|organization_id|orgId|org_id)\b/gi;
+    const organizationCandidates = lifecycleCandidates(
+      organizationReferencePattern,
+    );
+    if (
+      organizationCandidates.length > 0 &&
+      (isAuthBoundary || /group|organization|workspace|tenant/i.test(source))
+    ) {
+      for (const { index: organizationIndex, boundary } of organizationCandidates) {
+        const boundaryEnd = boundaries.find(
+          (candidate) => candidate.index > boundary.index,
+        )?.index ?? source.length;
+        const idMatch = source
+          .slice(organizationIndex, boundaryEnd)
+          .match(organizationReferencePattern);
+        const nameMatch = source
+          .slice(organizationIndex, boundaryEnd)
+          .match(
+            /\b(?:organization|org)\s*(?:\.\s*(?:name|displayName)|\[\s*["'](?:name|displayName)["']\s*\])|\b(?:organizationName|organization_name|orgName|org_name)\b/i,
+          );
+        if (idMatch) {
+          groupCandidates.push(
+            siteAt({
+              file,
+              source,
+              index: organizationIndex,
+              boundary,
+              availableFields: {
+                groupKey: idMatch[0],
+                ...(nameMatch ? { name: nameMatch[0] } : {}),
+              },
+              groupOwnerKind: "organization",
+            }),
+          );
+        }
+      }
+    }
+
+    const resetReferencePattern =
+      /\b(?:logout|logOut|signOut|sign[-_ ]?out|endSession)\s*(?=\()/gi;
+    for (const { index: resetIndex, boundary } of lifecycleCandidates(
+      resetReferencePattern,
+    )) {
+      const returnIndex = source.indexOf("return", resetIndex);
+      const returnLineStart =
+        returnIndex > resetIndex
+          ? source.lastIndexOf("\n", returnIndex - 1) + 1
+          : -1;
+      const previousLineStart =
+        returnLineStart > 0
+          ? source.lastIndexOf("\n", returnLineStart - 2) + 1
+          : resetIndex;
+      resetCandidates.push(
+        siteAt({
+          file,
+          source,
+          index: previousLineStart,
+          boundary,
+        }),
+      );
+    }
+  }
+  return {
+    identifySites: identifyCandidates,
+    groupSites: groupCandidates,
+    resetSites: resetCandidates,
+    identifyCandidateCount: identifyCandidates.length,
+    groupCandidateCount: groupCandidates.length,
+    resetCandidateCount: resetCandidates.length,
+  };
+};
+
+const bootstrapSitesFor = (files, detection) => {
+  const candidates = files.filter(({ source }) =>
+    /\b(?:express\s*\(|NestFactory\.create\s*\(|app\.listen\s*\(|FastAPI\s*\()/.test(
+      source,
+    ),
+  );
+  const backend = detection.services?.backend ?? [];
+  const backendService = backend.length === 1 ? backend[0] : null;
+  const candidate = uniqueSite(
+    candidates.map(({ file, source }) => {
+      const constructionIndex = firstIndex(source, [
+        /\b(?:express\s*\(|NestFactory\.create\s*\(|app\.listen\s*\(|FastAPI\s*\()/,
+      ]);
+      const index =
+        constructionIndex < 0
+          ? 0
+          : source.lastIndexOf("\n", constructionIndex) + 1;
+      return siteAt({ file, source, index });
+    }),
+  );
+  return {
+    site: candidate
+      ? {
+          ...candidate,
+          ...(backendService?.service_key
+            ? { serviceKey: backendService.service_key }
+            : {}),
+          ...(backendService?.framework
+            ? { framework: backendService.framework }
+            : {}),
+        }
+      : null,
+    ambiguous: candidates.length > 1,
+  };
+};
+
+export const discoverSetupContract = async ({ repoRoot, detection }) => {
+  const resolvedRepoRoot = resolve(repoRoot ?? ".");
+  const repositoryDetection =
+    detection ??
+    (await discoverSetupRepository({ repoRoot: resolvedRepoRoot }));
+  const files = await sourceFilesForSetupDiscovery(resolvedRepoRoot);
+  const backendFiles = setupSourceCandidates(files, repositoryDetection);
+  const lifecycle = lifecycleSitesFor(backendFiles);
+  const bootstrap = bootstrapSitesFor(backendFiles, repositoryDetection);
+  const sdkContract =
+    repositoryDetection.services?.backend?.length === 1
+      ? BACKEND_SDK_BY_FRAMEWORK[
+          repositoryDetection.services.backend[0].framework
+        ]
+      : null;
+  const ambiguous =
+    bootstrap.ambiguous ||
+    lifecycle.identifyCandidateCount > 1 ||
+    lifecycle.groupCandidateCount > 1 ||
+    lifecycle.resetCandidateCount > 1;
+  const applicableLifecycleApis = [
+    ...(bootstrap.site ? ["cluebase.init"] : []),
+    ...(lifecycle.identifyCandidateCount > 0 ? ["cluebase.identify"] : []),
+    ...(lifecycle.groupCandidateCount > 0 ? ["cluebase.group"] : []),
+    ...(lifecycle.resetCandidateCount > 0 ? ["cluebase.reset"] : []),
+  ];
+  const ambiguousLifecycleApis = [
+    ...(bootstrap.ambiguous ? ["cluebase.init"] : []),
+    ...(lifecycle.identifyCandidateCount > 1 ? ["cluebase.identify"] : []),
+    ...(lifecycle.groupCandidateCount > 1 ? ["cluebase.group"] : []),
+    ...(lifecycle.resetCandidateCount > 1 ? ["cluebase.reset"] : []),
+  ];
+  const backendService = repositoryDetection.services?.backend;
+  const frontendServices = repositoryDetection.services?.frontend ?? [];
+  const primaryService =
+    backendService?.length === 1
+      ? backendService[0]
+      : frontendServices.length === 1
+        ? frontendServices[0]
+        : null;
+  return {
+    cluebaseInitBackend: bootstrap.site,
+    cluebaseInitFrontend: null,
+    identifySites:
+      lifecycle.identifySites.length === 1 ? lifecycle.identifySites : [],
+    groupSites: lifecycle.groupSites.length === 1 ? lifecycle.groupSites : [],
+    resetSites: lifecycle.resetSites.length === 1 ? lifecycle.resetSites : [],
+    applicableLifecycleApis,
+    ambiguousLifecycleApis,
+    hasUnclearPoints:
+      ambiguous ||
+      !repositoryDetection.detected ||
+      Boolean(sdkContract?.blocker),
+    ...(sdkContract?.packages?.[0]
+      ? { sdkPackageName: sdkContract.packages[0] }
+      : {}),
+    ...(repositoryDetection.services?.backend?.length === 1
+      ? { serviceKey: repositoryDetection.services.backend[0].service_key }
+      : {}),
+    ...(backendService?.length === 1
+      ? { backendRootPath: backendService[0].root_path }
+      : {}),
+    ...(primaryService
+      ? {
+          language: primaryService.language,
+          framework: primaryService.framework,
+        }
+      : {}),
+  };
+};