@genn-inc/cluebase-cli 0.0.1

package/src/setup-doctor.mjs

@@ -0,0 +1,545 @@
+// setup-doctor: local API connectivity + data-quality preflight for Cluebase setup.
+// Env/probe/route-scan helpers live in setup-doctor-env / -probe / -route-scan.
+
+import { resolve } from "node:path";
+import { deriveEnvironmentFromProjectKey } from "./contracts.mjs";
+import { API_CONNECTIVITY_CONTRACT } from "./setup-ai-contract.mjs";
+import { loadQualityInputs, runQualityChecks } from "./setup-doctor-quality.mjs";
+import {
+  throwIfSetupDoctorDeadlineExceeded,
+  withSetupDoctorDeadline,
+} from "./setup-doctor-deadline.mjs";
+import {
+  DEFAULT_SETUP_MANIFEST_PATH,
+  CLUEBASE_BROWSER_TOKEN_PATH,
+  BROWSER_INGEST_PATH,
+  BACKEND_INGEST_PATH,
+  CLUEBASE_TEST_SETUP_SDK_VERSION,
+  optionalString,
+  readBatchVisibilityTimeoutConfig,
+  joinUrl,
+  BATCH_STATUS_PLACEHOLDER_PATH,
+  publicCluebaseApiBaseUrl,
+  publicProjectKeyFromEnv,
+  cluebaseApiBaseUrlFromIngestEndpoint,
+  normalizeBrowserIngestUrl,
+  firstTargetUrl,
+  loadDoctorEnv,
+} from "./setup-doctor-env.mjs";
+import { readSetupDoctorJson } from "./setup-doctor-file-boundary.mjs";
+import {
+  firstTargetBackendTargetId,
+  postJson,
+  tokenFromResult,
+  observationBatchIdFromResult,
+  buildCheck,
+  pollBatchVisibility,
+  buildSetupCorrelation,
+  buildBrowserEventPayload,
+  buildBackendEventPayload,
+} from "./setup-doctor-probe.mjs";
+import {
+  requiredInputCheck,
+  collectCustomerBackendCluebaseRouteFiles,
+  resolveBackendRootCandidates,
+} from "./setup-doctor-route-scan.mjs";
+import {
+  manifestHasBackend,
+  manifestHasNodeBackend,
+  manifestHasPythonBackend,
+  nodeBackendPreloadCheck,
+  probeBackendSdkImport,
+  probeNodeBackendPreload,
+  backendSdkImportCheck,
+} from "./setup-doctor-sdk-probe.mjs";
+
+// A frontend-only setup (SPA + static/serverless hosting, no backend) has no
+// backend ingest hop and no customer backend that could expose a Cluebase proxy
+// route. FIX-116: mark those backend-specific checks as N/A-pass instead of
+// failing them on absent backend inputs, which would otherwise make a valid
+// frontend-only setup impossible to pass.
+const frontendOnlyBackendNaCheck = (id) => ({
+  id,
+  severity: "error",
+  passed: true,
+  not_applicable: true,
+  skipped_reason:
+    "frontend-only setup (no backend detected); this backend check does not apply.",
+});
+
+export const runSetupDoctor = withSetupDoctorDeadline(async ({
+  fetchImpl = fetch,
+  flags,
+  repoRoot = ".",
+  runPython,
+}) => {
+  const manifestPath = String(
+    flags.get("manifest") || DEFAULT_SETUP_MANIFEST_PATH,
+  );
+  const resolvedRepoRoot = resolve(repoRoot);
+  const manifest = await readSetupDoctorJson({
+    repoRoot: resolvedRepoRoot,
+    path: manifestPath,
+    signal: fetchImpl.signal,
+    optional: true,
+  });
+  const doctorEnv = await loadDoctorEnv({
+    manifest,
+    repoRoot: resolvedRepoRoot,
+    signal: fetchImpl.signal,
+  });
+  const frontendEnv = doctorEnv.frontendEnv;
+  const backendEnv = doctorEnv.backendEnv;
+  const flagCluebaseApiBaseUrl = optionalString(flags.get("cluebase-api-base-url"));
+  const frontendCluebaseApiBaseUrl =
+    flagCluebaseApiBaseUrl ?? publicCluebaseApiBaseUrl(frontendEnv);
+  const backendCluebaseApiBaseUrl =
+    flagCluebaseApiBaseUrl ??
+    optionalString(backendEnv.CLUEBASE_API_BASE_URL) ??
+    cluebaseApiBaseUrlFromIngestEndpoint(backendEnv.CLUEBASE_INGEST_ENDPOINT);
+  const cluebaseApiBaseUrl = backendCluebaseApiBaseUrl ?? frontendCluebaseApiBaseUrl;
+  const flagProjectKey = optionalString(flags.get("project-key"));
+  const frontendProjectKey =
+    flagProjectKey ?? publicProjectKeyFromEnv(frontendEnv);
+  const backendProjectKey =
+    flagProjectKey ?? optionalString(backendEnv.CLUEBASE_PROJECT_KEY);
+  const projectKey = frontendProjectKey ?? backendProjectKey;
+  const environment = projectKey
+    ? deriveEnvironmentFromProjectKey(projectKey)
+    : null;
+  const apiKey =
+    optionalString(flags.get("cluebase-api-key")) ??
+    optionalString(backendEnv.CLUEBASE_API_KEY);
+  const backendServiceKey =
+    optionalString(flags.get("backend-service-key")) ??
+    optionalString(manifest?.detected?.service_key) ??
+    firstTargetBackendTargetId(manifest);
+  const clientFrontendUrl =
+    optionalString(flags.get("client-frontend-url")) ??
+    firstTargetUrl({ manifest, kind: "frontend" });
+  const origin = optionalString(flags.get("origin")) ?? clientFrontendUrl;
+  const cluebaseBrowserTokenUrl = frontendCluebaseApiBaseUrl
+    ? joinUrl(frontendCluebaseApiBaseUrl, CLUEBASE_BROWSER_TOKEN_PATH)
+    : null;
+  const browserIngestUrl = normalizeBrowserIngestUrl(
+    optionalString(flags.get("browser-ingest-url")) ??
+      (flagCluebaseApiBaseUrl
+        ? joinUrl(flagCluebaseApiBaseUrl, BROWSER_INGEST_PATH)
+        : null) ??
+      publicCluebaseApiBaseUrl(frontendEnv) ??
+      (frontendCluebaseApiBaseUrl
+        ? joinUrl(frontendCluebaseApiBaseUrl, BROWSER_INGEST_PATH)
+        : null),
+  );
+  const backendIngestUrl =
+    optionalString(flags.get("backend-ingest-url")) ??
+    (flagCluebaseApiBaseUrl
+      ? joinUrl(flagCluebaseApiBaseUrl, BACKEND_INGEST_PATH)
+      : null) ??
+    optionalString(backendEnv.CLUEBASE_INGEST_ENDPOINT) ??
+    (backendCluebaseApiBaseUrl
+      ? joinUrl(backendCluebaseApiBaseUrl, BACKEND_INGEST_PATH)
+      : null);
+
+  const checks = [fetchImpl.deadlineCheck].filter(Boolean);
+  // Real backend SDK import probe: catches published cluebase-backend-sdk versions
+  // that predate the `cluebase` facade (grep-based checks miss this and pass
+  // falsely while the customer backend crashes at import).
+  if (manifestHasPythonBackend(manifest)) {
+    const sdkProbe = await probeBackendSdkImport({
+      repoRoot: resolvedRepoRoot,
+      backendRootPath: optionalString(manifest?.detected?.backend_root_path),
+      ...(runPython ? { runPython } : {}),
+      signal: fetchImpl.signal,
+    });
+    checks.push(backendSdkImportCheck(sdkProbe));
+  }
+  // Node backends must preload the SDK instrumentation entry. Without it the
+  // server starts, reports no error, and records nothing on the backend side —
+  // a failure no source-text check can see.
+  if (manifestHasNodeBackend(manifest)) {
+    const preloadProbe = await probeNodeBackendPreload({
+      repoRoot: resolvedRepoRoot,
+      backendRootPath: optionalString(manifest?.detected?.backend_root_path),
+      nodeOptions: optionalString(backendEnv.NODE_OPTIONS),
+      signal: fetchImpl.signal,
+    });
+    checks.push(nodeBackendPreloadCheck(preloadProbe));
+  }
+  // Backend hops apply when the manifest detected a backend, or the caller
+  // explicitly targets a backend via flags. Otherwise this is a frontend-only
+  // setup and the backend checks are N/A (FIX-116).
+  const explicitBackendTargetFlag =
+    flags.has("backend-ingest-url") ||
+    flags.has("backend-service-key") ||
+    flags.has("backend-root-path");
+  const backendApplicable =
+    manifestHasBackend(manifest) || explicitBackendTargetFlag;
+  const batchVisibilityTimeoutConfig = readBatchVisibilityTimeoutConfig();
+  if (batchVisibilityTimeoutConfig.error) {
+    checks.push({
+      id: "setup_timeout_config",
+      name: "setup-doctor batch visibility timeout configuration",
+      severity: "error",
+      passed: false,
+      error: batchVisibilityTimeoutConfig.error,
+      env_var: "CLUEBASE_SETUP_VERIFICATION_BATCH_TIMEOUT_MS",
+      timeout_ms: batchVisibilityTimeoutConfig.timeoutMs,
+    });
+  }
+  let browserIngestBatchId = null;
+  const setupCorrelation = buildSetupCorrelation();
+
+  // Frontend SDK fetches its token from the Cluebase backend directly.
+  let browserToken = null;
+  if (!cluebaseBrowserTokenUrl || !frontendProjectKey || !origin) {
+    checks.push(
+      requiredInputCheck({
+        id: "cluebase_backend_browser_token_issue",
+        missing: [
+          ...(!cluebaseBrowserTokenUrl ? ["cluebase-api-base-url"] : []),
+          ...(!frontendProjectKey ? ["frontend public project key"] : []),
+          ...(!origin ? ["client-frontend-url or origin"] : []),
+        ],
+        url: cluebaseBrowserTokenUrl,
+      }),
+    );
+  } else {
+    const result = await postJson({
+      fetchImpl,
+      url: cluebaseBrowserTokenUrl,
+      headers: { origin },
+      body: {
+        projectKey: frontendProjectKey,
+      },
+    });
+    browserToken = tokenFromResult(result);
+    checks.push(
+      buildCheck({
+        id: "cluebase_backend_browser_token_issue",
+        passed: Boolean(browserToken),
+        result,
+        url: cluebaseBrowserTokenUrl,
+      }),
+    );
+  }
+
+  // Frontend SDK sends browser events to Cluebase ingest with the token issued above.
+  if (!browserIngestUrl || !frontendProjectKey || !browserToken) {
+    checks.push(
+      requiredInputCheck({
+        id: "browser_ingest",
+        missing: [
+          ...(!browserIngestUrl ? ["browser-ingest-url"] : []),
+          ...(!frontendProjectKey ? ["frontend public project key"] : []),
+          ...(!browserToken ? ["browser token"] : []),
+        ],
+        url: browserIngestUrl,
+      }),
+    );
+  } else {
+    const result = await postJson({
+      fetchImpl,
+      url: browserIngestUrl,
+      headers: {
+        origin,
+        "x-cluebase-project-key": frontendProjectKey,
+        "x-cluebase-browser-token": browserToken,
+        "x-cluebase-sdk-request": "browser",
+        "x-cluebase-sdk-version": CLUEBASE_TEST_SETUP_SDK_VERSION,
+        "x-cluebase-source-schema-version": "1",
+      },
+      body: buildBrowserEventPayload({
+        correlation: setupCorrelation,
+      }),
+    });
+    browserIngestBatchId = observationBatchIdFromResult(result);
+    checks.push(
+      buildCheck({
+        id: "browser_ingest",
+        passed: Boolean(
+          result.transportOk && result.response.ok && browserIngestBatchId,
+        ),
+        error: browserIngestBatchId
+          ? null
+          : "browser ingest response must include observation_ingest_batch_id",
+        result,
+        url: browserIngestUrl,
+      }),
+    );
+  }
+
+  if (
+    !browserIngestBatchId ||
+    !cluebaseApiBaseUrl ||
+    !apiKey ||
+    !backendProjectKey
+  ) {
+    checks.push(
+      requiredInputCheck({
+        id: "browser_ingest_reached_ledger",
+        missing: [
+          ...(!browserIngestBatchId
+            ? ["browser_observation_ingest_batch_id"]
+            : []),
+          ...(!cluebaseApiBaseUrl ? ["api-base-url"] : []),
+          ...(!apiKey ? ["CLUEBASE_API_KEY"] : []),
+          ...(!backendProjectKey ? ["CLUEBASE_PROJECT_KEY"] : []),
+        ],
+        url: cluebaseApiBaseUrl
+          ? joinUrl(cluebaseApiBaseUrl, BATCH_STATUS_PLACEHOLDER_PATH)
+          : null,
+      }),
+    );
+  } else {
+    checks.push(
+      await pollBatchVisibility({
+        apiKey,
+        batchId: browserIngestBatchId,
+        checkId: "browser_ingest_reached_ledger",
+        cluebaseApiBaseUrl,
+        fetchImpl,
+        projectKey: backendProjectKey,
+        timeoutMs: batchVisibilityTimeoutConfig.timeoutMs,
+      }),
+    );
+  }
+  // Backend SDK sends backend events to Cluebase ingest. Frontend-only setups have
+  // no backend, so these hops are N/A (FIX-116).
+  if (!backendApplicable) {
+    checks.push(frontendOnlyBackendNaCheck("backend_ingest"));
+    checks.push(frontendOnlyBackendNaCheck("backend_ingest_reached_ledger"));
+  } else {
+    let backendIngestBatchId = null;
+    if (
+      !backendIngestUrl ||
+      !apiKey ||
+      !backendProjectKey ||
+      !backendServiceKey
+    ) {
+      checks.push(
+        requiredInputCheck({
+          id: "backend_ingest",
+          missing: [
+            ...(!backendIngestUrl ? ["backend-ingest-url"] : []),
+            ...(!apiKey ? ["CLUEBASE_API_KEY"] : []),
+            ...(!backendProjectKey ? ["CLUEBASE_PROJECT_KEY"] : []),
+            ...(!backendServiceKey ? ["backend-service-key"] : []),
+          ],
+          url: backendIngestUrl,
+        }),
+      );
+    } else {
+      const result = await postJson({
+        fetchImpl,
+        url: backendIngestUrl,
+        headers: {
+          "x-cluebase-project-key": backendProjectKey,
+          "x-cluebase-api-key": apiKey,
+        },
+        body: buildBackendEventPayload({
+          backendServiceKey,
+          correlation: setupCorrelation,
+          projectKey: backendProjectKey,
+        }),
+      });
+      checks.push(
+        buildCheck({
+          id: "backend_ingest",
+          passed: Boolean(result.transportOk && result.response.ok),
+          result,
+          url: backendIngestUrl,
+        }),
+      );
+      // Ingest 201 受領だけで「動いている」 と判定すると、raw-ingest→normalize→
+      // publish の下流 hop が壊れた状態を見逃す。ingest response から batch id
+      // を抽出し、backend_ingest_reached_ledger で published まで検証する。
+      if (result.transportOk && result.response.ok) {
+        backendIngestBatchId = observationBatchIdFromResult(result);
+      }
+    }
+
+    // Confirm backend ingest reached published state, not only HTTP 201.
+    if (
+      !backendIngestBatchId ||
+      !cluebaseApiBaseUrl ||
+      !apiKey ||
+      !backendProjectKey
+    ) {
+      checks.push(
+        requiredInputCheck({
+          id: "backend_ingest_reached_ledger",
+          missing: [
+            ...(!backendIngestBatchId ? ["backend_ingest_batch_id"] : []),
+            ...(!cluebaseApiBaseUrl ? ["api-base-url"] : []),
+            ...(!apiKey ? ["CLUEBASE_API_KEY"] : []),
+            ...(!backendProjectKey ? ["CLUEBASE_PROJECT_KEY"] : []),
+          ],
+          url: cluebaseApiBaseUrl
+            ? joinUrl(cluebaseApiBaseUrl, BATCH_STATUS_PLACEHOLDER_PATH)
+            : null,
+        }),
+      );
+    } else {
+      checks.push({
+        ...(await pollBatchVisibility({
+          apiKey,
+          batchId: backendIngestBatchId,
+          checkId: "backend_ingest_reached_ledger",
+          cluebaseApiBaseUrl,
+          fetchImpl,
+          projectKey: backendProjectKey,
+          timeoutMs: batchVisibilityTimeoutConfig.timeoutMs,
+        })),
+        remediation_prompt: null,
+      });
+      throwIfSetupDoctorDeadlineExceeded(fetchImpl.signal);
+    }
+  }
+
+  // Customer backends must not expose Cluebase-specific browser-token routes.
+  const skipCustomerBackendRouteScan = flags.has("skip-cluebase-route-scan");
+  const customerBackendRouteScanRoots = backendApplicable
+    ? resolveBackendRootCandidates({
+        flags,
+        manifest,
+        repoRoot: resolvedRepoRoot,
+      })
+    : [];
+  const customerBackendRouteFiles = [];
+  let customerBackendRouteScanTruncated = false;
+  let customerBackendRouteScannedFiles = 0;
+  let customerBackendRouteScanRan = false;
+  if (
+    !skipCustomerBackendRouteScan &&
+    customerBackendRouteScanRoots.length > 0
+  ) {
+    customerBackendRouteScanRan = true;
+    for (const rootPath of customerBackendRouteScanRoots) {
+      const result = await fetchImpl.runStage(() =>
+        collectCustomerBackendCluebaseRouteFiles({
+          repoRoot: resolvedRepoRoot,
+          rootAbs: resolve(resolvedRepoRoot, rootPath || "."),
+          signal: fetchImpl.signal,
+        }),
+      );
+      customerBackendRouteScannedFiles += result.scanned;
+      if (result.truncated) customerBackendRouteScanTruncated = true;
+      for (const filePath of result.files) {
+        if (!customerBackendRouteFiles.includes(filePath))
+          customerBackendRouteFiles.push(filePath);
+      }
+    }
+  }
+  const customerBackendRouteScanMissing =
+    !skipCustomerBackendRouteScan && customerBackendRouteScanRoots.length === 0;
+  const customerBackendRouteCheck = !backendApplicable
+    ? frontendOnlyBackendNaCheck("customer_backend_cluebase_route_forbidden")
+    : {
+    id: "customer_backend_cluebase_route_forbidden",
+    severity: "error",
+    method: null,
+    url: null,
+    passed:
+      !skipCustomerBackendRouteScan &&
+      !customerBackendRouteScanMissing &&
+      !customerBackendRouteScanTruncated &&
+      customerBackendRouteFiles.length === 0,
+    status:
+      customerBackendRouteScanMissing || skipCustomerBackendRouteScan
+        ? "skipped"
+        : null,
+    error: skipCustomerBackendRouteScan
+      ? "Customer-backend Cluebase route scan was explicitly skipped; setup cannot be marked passed until direct browser-token routing is verified."
+      : customerBackendRouteScanMissing
+        ? "customer backend root was not found; Customer-backend Cluebase route scan did not run. Pass --backend-root-path or provide .cluebase/setup-manifest.json detected.backend_root_path to verify direct browser-token routing."
+        : customerBackendRouteScanTruncated
+          ? "Customer-backend Cluebase route scan was incomplete: it reached its file limit or could not read a configured root/file. Narrow --backend-root-path, remove generated files, or fix the unreadable path so direct browser-token routing can be verified."
+          : customerBackendRouteFiles.length === 0
+            ? null
+            : "Customer-backend Cluebase route detected. The frontend SDK calls the Cluebase backend directly; remove this Cluebase route before setup can pass.",
+    files: customerBackendRouteFiles,
+    scan_ran: customerBackendRouteScanRan,
+    scan_truncated: customerBackendRouteScanTruncated,
+    scanned_files: customerBackendRouteScannedFiles,
+    scan_root_candidates: customerBackendRouteScanRoots.map((root) => root || "."),
+  };
+  checks.push(customerBackendRouteCheck);
+
+  // 顧客 source code / discoveries.json / env file を解析し、 API 疎通だけでは
+  // 検知不能な「動いているのに使えない」 失敗を fail-fast で halt する。
+  //
+  // 起動条件: `.cluebase/discoveries.json` が存在する顧客 repo 文脈でのみ実行。
+  // discoveries.json が無い文脈 (= test 用 tmpdir / CLI 単体起動) では quality
+  // check 自体を skip し、 API 疎通だけ検証する。
+  // `--skip-quality-checks` flag で明示的に stop 可 (= 強制 skip)。
+  // `--force-quality-checks` flag で discoveries.json が無くても実行 (= test 用)。
+  let qualityChecks = [];
+  let qualityCheckSummary = null;
+  const skipQuality = flags.has("skip-quality-checks");
+  const forceQuality = flags.has("force-quality-checks");
+  if (!skipQuality) {
+    const qualityInputs = await fetchImpl.runStage(() =>
+      loadQualityInputs({ repoRoot: resolvedRepoRoot, signal: fetchImpl.signal }),
+    );
+    const hasDiscoveries = qualityInputs.discoveries !== null;
+    if (hasDiscoveries || forceQuality) {
+      const qualityResult = await fetchImpl.runStage(() =>
+        runQualityChecks({
+          ...qualityInputs,
+          repoRoot: resolvedRepoRoot,
+          signal: fetchImpl.signal,
+        }),
+      );
+      qualityChecks = qualityResult.checks;
+      qualityCheckSummary = qualityResult.summary;
+    }
+  }
+  // 集計: API 疎通 + customer route surface check + quality error check 全 pass で setup 成功。
+  // quality warn check は続行可。
+  const errorChecks = checks.filter((check) => check.severity === "error");
+  const warningChecks = checks.filter((check) => check.severity === "warning");
+  const apiConnectivityPassed = errorChecks.every((check) => check.passed);
+  const qualityErrorPassed = qualityCheckSummary
+    ? qualityCheckSummary.errorFailed === 0
+    : true;
+  const passed = apiConnectivityPassed && qualityErrorPassed;
+
+  return {
+    status: passed ? "passed" : "failed",
+    passed,
+    contract: API_CONNECTIVITY_CONTRACT,
+    checks,
+    qualityChecks,
+    qualityCheckSummary,
+    summary: {
+      apiConnectivity: {
+        total: errorChecks.length,
+        failed: errorChecks.filter((c) => !c.passed).length,
+        passed: apiConnectivityPassed,
+      },
+      doctrineWarnings: {
+        total: warningChecks.length,
+        failed: warningChecks.filter((c) => !c.passed).length,
+      },
+      dataQuality: qualityCheckSummary,
+    },
+    inputs: {
+      manifest_loaded: Boolean(manifest),
+      client_frontend_url_configured: Boolean(clientFrontendUrl),
+      origin_configured: Boolean(origin),
+      cluebase_api_base_url_configured: Boolean(cluebaseApiBaseUrl),
+      project_key_configured: Boolean(projectKey),
+      frontend_project_key_configured: Boolean(frontendProjectKey),
+      backend_project_key_configured: Boolean(backendProjectKey),
+      frontend_cluebase_api_base_url_configured: Boolean(frontendCluebaseApiBaseUrl),
+      backend_ingest_url_configured: Boolean(backendIngestUrl),
+      environment_configured: Boolean(environment),
+      backend_service_key_configured: Boolean(backendServiceKey),
+      cluebase_api_key_configured: Boolean(apiKey),
+      env_files_loaded: doctorEnv.loadedFiles,
+      frontend_env_files_loaded: doctorEnv.frontendLoadedFiles,
+      backend_env_files_loaded: doctorEnv.backendLoadedFiles,
+    },
+  };
+}, API_CONNECTIVITY_CONTRACT);

package/src/setup-documents.mjs

@@ -0,0 +1,112 @@
+export const SETUP_DOCUMENTATION_CONTRACT_VERSION = "1";
+
+export const DEFAULT_SETUP_DOCUMENTS_URL = "/documents";
+
+// Cluebase web app route + screen heading for the external data source connection
+// screen. Value milestones that live only in an external system the customer app
+// never sees (a billing platform, a CRM, a spreadsheet) cannot be instrumented
+// with cluebase.track; they are ingested by connecting the external system on this
+// screen. Kept next to DEFAULT_SETUP_DOCUMENTS_URL because both are Cluebase web app
+// relative paths the setup flow points the customer to. Grounded in the web
+// routing: sidebar "Settings" → "外部データ" nav item, page heading "外部データ接続".
+export const EXTERNAL_DATA_CONNECTION_PATH = "/settings/external-data";
+export const EXTERNAL_DATA_CONNECTION_SCREEN_NAME = "外部データ接続";
+
+export const CORE_SETUP_DOCUMENT_IDS = [
+	"ai-setup-order",
+	"cluebase-boundary",
+	"environment-and-secrets",
+	"find-integration-points",
+	"official-sdk-contract",
+	"cluebase-init",
+	"cluebase-identify",
+	"cluebase-group-organization",
+	"cluebase-reset",
+	"cluebase-local-verification",
+	"forbidden-patterns",
+];
+
+export const FRAMEWORK_SETUP_DOCUMENT_IDS = {
+	angular: "framework-angular",
+	django: "framework-django",
+	fastapi: "framework-fastapi",
+	nextjs: "framework-nextjs",
+	react: "framework-react-spa",
+	vite: "framework-react-spa",
+	vue: "framework-react-spa",
+};
+
+const optionalString = (value) =>
+	typeof value === "string" && value.trim() ? value.trim() : null;
+
+const normalizeDocumentsUrl = (documentsUrl) =>
+	optionalString(documentsUrl)?.replace(/\/+$/, "") ??
+	DEFAULT_SETUP_DOCUMENTS_URL;
+
+const normalizeFrameworks = (frameworks = []) => [
+	...new Set(
+		frameworks
+			.map((framework) =>
+				typeof framework === "string" && framework.trim()
+					? framework.trim().toLowerCase()
+					: null,
+			)
+			.filter(Boolean),
+	),
+];
+
+const docUrlFor = ({ documentsUrl, docId }) => `${documentsUrl}#${docId}`;
+
+export const frameworkDocIdsFor = (frameworks = []) => [
+	...new Set(
+		normalizeFrameworks(frameworks)
+			.map((framework) => FRAMEWORK_SETUP_DOCUMENT_IDS[framework])
+			.filter(Boolean),
+	),
+];
+
+export const buildSetupDocumentationContract = ({
+	documentsUrl,
+	framework,
+	frameworks = [],
+} = {}) => {
+	const normalizedDocumentsUrl = normalizeDocumentsUrl(documentsUrl);
+	const selectedFrameworks = normalizeFrameworks([
+		...(framework ? [framework] : []),
+		...frameworks,
+	]);
+	const selectedFrameworkDocIds = frameworkDocIdsFor(selectedFrameworks);
+	const requiredDocIds = [
+		...new Set([...CORE_SETUP_DOCUMENT_IDS, ...selectedFrameworkDocIds]),
+	];
+
+	return {
+		version: SETUP_DOCUMENTATION_CONTRACT_VERSION,
+		documents_url: normalizedDocumentsUrl,
+		external_data_source_connection: {
+			screen_name: EXTERNAL_DATA_CONNECTION_SCREEN_NAME,
+			path: EXTERNAL_DATA_CONNECTION_PATH,
+			purpose:
+				"Ingest value data that no SDK call can capture because it lives only in an external system the customer app never sees (a billing platform, a CRM, a spreadsheet). The customer connects the external system on this Cluebase web screen instead of instrumenting cluebase.track.",
+		},
+		required_doc_ids: requiredDocIds,
+		framework_doc_ids_by_framework: FRAMEWORK_SETUP_DOCUMENT_IDS,
+		selected_frameworks: selectedFrameworks,
+		selected_framework_doc_ids: selectedFrameworkDocIds,
+		doc_urls: Object.fromEntries(
+			requiredDocIds.map((docId) => [
+				docId,
+				docUrlFor({ documentsUrl: normalizedDocumentsUrl, docId }),
+			]),
+		),
+		pre_editing_gate: [
+			"Open documents_url before editing when tool access allows it.",
+			"Read every required_doc_ids entry that applies to the detected framework.",
+			"If documents_url cannot be opened, continue only from the generated skills and manifest doc ids, and report documentation_access_blocked.",
+			"Do not implement by prompt memory alone when the manifest contains a documentation contract.",
+		],
+		report_required_fields: ["consulted_document_ids"],
+		agent_rule:
+			"Read the relevant Cluebase setup documents before editing and list consulted_document_ids in the final report.",
+	};
+};