@clue-ai/cli 0.0.16 → 0.0.18

package/src/setup-ai-contract.mjs

@@ -0,0 +1,114 @@
+export const AI_SETUP_CONTRACT_VERSION =
+  "2026-05-10.frontend-adapter-contract.v8";
+
+export const SETUP_DOCTRINE = {
+  purpose:
+    "Clue setup installs an external SDK integration so observed product facts can reach Clue's Customer Value Understanding Engine. It is not an opportunity to improve, refactor, redesign, or reinterpret the host application.",
+  minimal_diff_reason:
+    "The customer must be able to review and merge the setup diff with confidence. Extra formatting, refactors, auth rewrites, UI changes, or unrelated cleanup make the integration harder to trust.",
+  ai_decision_boundary:
+    "The AI should use repository understanding only to choose existing lifecycle boundaries for ClueInit, ClueIdentify, ClueSetAccount, and ClueLogout.",
+  deterministic_control_boundary:
+    "Everything that can be controlled mechanically should be controlled by the CLI, generated skills, documentation contract, lifecycle plan schema, and setup-check static guards.",
+  documentation_reason:
+    "SDK signatures, environment variable names, browser token behavior, and verification ownership are contracts. The AI must read the setup documents instead of relying on memory.",
+  failure_posture:
+    "When a lifecycle point, SDK package, signature, env name, or verification step is unclear, the correct output is a blocker or user_verification_pending, not a guessed implementation or a completion claim.",
+};
+
+export const DETERMINISTIC_CONTROL_MODEL = {
+  ai_should_decide: [
+    "which existing bootstrap point owns ClueInit",
+    "which existing login/session success point owns ClueIdentify",
+    "which existing account/workspace/organization resolution point owns ClueSetAccount",
+    "which existing logout/session reset point owns ClueLogout",
+    "whether a lifecycle point is unclear and should be reported as blocked",
+  ],
+  cli_should_control: [
+    "official SDK package names",
+    "official public SDK function names and supported lifecycle API set",
+    "environment variable names produced by setup and consumed by setup code",
+    "machine-owned semantic workflow generation and verification",
+    "setup-watch ownership as user-operated verification",
+    "static rejection of known unsafe wiring such as leaked secrets, wrong SDKs, blocking lifecycle calls, broad ClueTrack setup, and unsafe browser token proxy patterns",
+    "local API connectivity preflight for the four required setup hops before user-operated setup-watch",
+    "canonical frontend SDK adapter env names, token proxy path, and initialization safety checks",
+  ],
+};
+
+export const API_CONNECTIVITY_CONTRACT = {
+  purpose:
+    "Clue setup has four distinct HTTP hops. The AI must not collapse customer-owned proxy routes and Clue-owned ingest routes into one vague browser-token endpoint.",
+  hops: {
+    client_backend_browser_token_proxy: {
+      owner: "customer_backend",
+      method: "POST",
+      path: "/api/v1/clue/browser-tokens",
+      caller: "customer_frontend_browserTokenProvider",
+      purpose:
+        "Issue a short-lived browser token without exposing CLUE_API_KEY to browser code.",
+    },
+    clue_backend_browser_token_issue: {
+      owner: "clue_backend",
+      method: "POST",
+      path: "/api/v1/ingest/browser-tokens",
+      caller: "customer_backend_browser_token_proxy",
+      purpose:
+        "Clue backend validates CLUE_API_KEY, project, environment, service key, and origin, then returns a browser token.",
+    },
+    browser_ingest: {
+      owner: "clue_backend",
+      method: "POST",
+      path: "/api/v1/ingest/browser",
+      caller: "customer_frontend_browser_sdk",
+      env_name: "NEXT_PUBLIC_CLUE_INGEST_ENDPOINT for Next.js browser code",
+      purpose:
+        "Browser SDK sends observation source events with x-clue-browser-token.",
+    },
+    backend_ingest: {
+      owner: "clue_backend",
+      method: "POST",
+      path: "/api/v1/ingest/backend",
+      caller: "customer_backend_sdk",
+      env_name: "CLUE_INGEST_ENDPOINT",
+      purpose:
+        "Backend SDK sends observation source events with server-side CLUE_API_KEY.",
+    },
+  },
+  preflight_command: "setup-doctor --local",
+  setup_watch_boundary:
+    "setup-doctor checks local API connectivity before user flows. setup-watch remains user-operated lifecycle and event-delivery verification.",
+};
+
+export const FRONTEND_ADAPTER_CONTRACT = {
+  purpose:
+    "Frontend SDK adapter code is part of the Clue setup contract. The AI may choose where the adapter is imported, but must not invent new token URL, env, or initialization semantics.",
+  nextjs_public_env: [
+    "NEXT_PUBLIC_CLUE_PROJECT_KEY",
+    "NEXT_PUBLIC_CLUE_ENVIRONMENT",
+    "NEXT_PUBLIC_CLUE_SERVICE_KEY",
+    "NEXT_PUBLIC_CLUE_INGEST_ENDPOINT",
+    "NEXT_PUBLIC_CLUE_BROWSER_TOKEN_ENDPOINT",
+  ],
+  browser_token_proxy_path: "/api/v1/clue/browser-tokens",
+  rules: [
+    "Do not derive the Clue browser-token proxy from generic app API env names such as NEXT_PUBLIC_API_URL.",
+    "Do not mix stale browser token paths with the canonical /api/v1/clue/browser-tokens path in the same adapter.",
+    "Next.js browserTokenProvider must call NEXT_PUBLIC_CLUE_BROWSER_TOKEN_ENDPOINT, whose value is the customer backend browser-token proxy URL.",
+    "Do not call ClueInit with empty-string fallbacks for required NEXT_PUBLIC_CLUE_* values.",
+    "If a singleton guard is used, do not mark initialized=true before ClueInit has been called with required config present.",
+    "The browser token provider must send the same frontend serviceKey used by ClueInit.",
+  ],
+};
+
+export const setupDoctrineSkillLines = () => [
+  `- Purpose: ${SETUP_DOCTRINE.purpose}`,
+  `- Minimal diff reason: ${SETUP_DOCTRINE.minimal_diff_reason}`,
+  `- AI decision boundary: ${SETUP_DOCTRINE.ai_decision_boundary}`,
+  `- Static control boundary: ${SETUP_DOCTRINE.deterministic_control_boundary}`,
+  `- Documentation reason: ${SETUP_DOCTRINE.documentation_reason}`,
+  `- Failure posture: ${SETUP_DOCTRINE.failure_posture}`,
+  `- API connectivity: ${API_CONNECTIVITY_CONTRACT.purpose}`,
+  `- Frontend adapter: ${FRONTEND_ADAPTER_CONTRACT.purpose}`,
+  `- API preflight: run ${API_CONNECTIVITY_CONTRACT.preflight_command} when local services and required env are available; do not substitute it for user-operated setup-watch.`,
+];

package/src/setup-check.mjs

@@ -12,6 +12,7 @@ import {
   stripSourceNoise,
 } from "./lifecycle-guard.mjs";
 import { listAllowedSourceFiles } from "./path-policy.mjs";
+import { AI_SETUP_CONTRACT_VERSION } from "./setup-ai-contract.mjs";
 import { runSemanticInventory } from "./semantic-ci.mjs";
 
 const DEFAULT_WORKFLOW_PATH = ".github/workflows/clue-semantic-snapshot.yml";
@@ -27,7 +28,7 @@ const SETUP_SKILLS = [
   "clue-local-verification",
   "clue-setup-report",
 ];
-const SETUP_SKILL_CONTENT_VERSION = "2026-05-10.lifecycle-placement-only.v4";
+const SETUP_SKILL_CONTENT_VERSION = AI_SETUP_CONTRACT_VERSION;
 const REQUIRED_SETUP_SKILL_PHRASES = {
   "clue-sdk-instrumentation": [
     "Do not create no-op wrappers",
@@ -41,7 +42,13 @@ const REQUIRED_SETUP_SKILL_PHRASES = {
     "Do not add `@clue-ai/browser-sdk` or backend SDK dependencies with `*` or `latest`",
     "Whitespace-only changes are allowed only on lines directly changed for Clue SDK wiring",
     "The local backend token endpoint is part of the customer app, not the Clue API",
-    "The frontend `browserTokenProvider` must send the same service key used by `ClueInit`",
+    "send the same service key used by `ClueInit`",
+    "NEXT_PUBLIC_CLUE_BROWSER_TOKEN_ENDPOINT",
+    "Do not forward `origin`, `projectKey`, or `environment` from JSON/body payload fields under server `CLUE_API_KEY`",
+    "Frontend SDK adapter code is contract-owned Clue setup wiring",
+    "Do not derive it from `NEXT_PUBLIC_API_URL`",
+    "Do not call `ClueInit` with empty-string fallbacks",
+    "do not set `initialized = true` before `ClueInit`",
     "For Django code, use `clue-django-sdk` only after package-manager or registry verification confirms it is installable",
   ],
   "clue-setup-audit": [
@@ -49,12 +56,18 @@ const REQUIRED_SETUP_SKILL_PHRASES = {
     "Reject Django SDK setup when `clue-django-sdk` installability has not been verified",
     "Reject ClueTrack instrumentation unless the user explicitly requested product event tracking",
     "Reject Next.js browser/client code that reads non-public `process.env.CLUE_*` variables",
+    "Reject browser token proxy code that forwards origin, projectKey, or environment from request JSON/body under server `CLUE_API_KEY`",
+    "Reject frontend browser token providers that derive the Clue proxy URL from `NEXT_PUBLIC_API_URL`",
+    "Reject frontend adapters that mix stale browser-token paths",
+    "Reject frontend adapters that set `initialized = true` before calling `ClueInit`",
+    "Audit the setup diff against the Clue setup contract even when the code was written by another agent",
     "Reject whitespace-only edits, import sorting, formatter churn",
     "Reject unrelated refactors, renames, file moves",
     "Execution agents must not approve, certify, or mark their own work complete",
   ],
   "clue-local-verification": [
     "`setup-check --require-sdk-lifecycle` is a static source check only",
+    "`setup-doctor --local` API connectivity preflight",
     "Verify frontend SDK installability/import",
     "Verify backend SDK installability/import",
     "Do not run `npx -y @clue-ai/cli setup-watch --local` automatically",
@@ -732,7 +745,13 @@ const NEXT_PUBLIC_CLUE_NAMES = [
   "CLUE_ENVIRONMENT",
   "CLUE_SERVICE_KEY",
   "CLUE_INGEST_ENDPOINT",
+  "CLUE_BROWSER_TOKEN_ENDPOINT",
 ];
+const CANONICAL_BROWSER_TOKEN_PROXY_PATH = "/api/v1/clue/browser-tokens";
+const BROWSER_TOKEN_PATH_PATTERN =
+  /\/[^"'`\s]*(?:browser[-_]?tokens?|browser[-_]?token)\b/i;
+const GENERIC_PUBLIC_API_ENV_PATTERN =
+  /\bprocess\.env\.(?:(?:NEXT_PUBLIC|VITE|REACT_APP)_(?!CLUE_)[A-Z0-9_]*(?:API|BACKEND|BASE|URL)[A-Z0-9_]*)\b/;
 
 const findNextLifecycleNonPublicEnvFiles = ({
   dependencySources,
@@ -806,6 +825,86 @@ const findNextBrowserTokenProviderMissingPublicServiceKeyFiles = ({
     .map((source) => source.file_path);
 };
 
+const findNextBrowserTokenProviderMissingPublicEndpointFiles = ({
+  dependencySources,
+  frontendSources,
+}) => {
+  const roots = nextPackageRoots(dependencySources);
+  if (roots.length === 0) return [];
+  return frontendSources
+    .filter((source) => sourceIsUnderAnyRoot(source, roots))
+    .filter(sourceLooksLikeBrowserTokenProvider)
+    .filter(
+      (source) =>
+        !/\bprocess\.env\.NEXT_PUBLIC_CLUE_BROWSER_TOKEN_ENDPOINT\b/.test(
+          source.text,
+        ),
+    )
+    .map((source) => source.file_path);
+};
+
+const browserTokenPathLiterals = (text) =>
+  [
+    ...stripSourceNoise(text).matchAll(
+      /(["'`])([^"'`]*(?:browser[-_]?tokens?|browser[-_]?token)[^"'`]*)\1/gi,
+    ),
+  ].map((match) => match[2]);
+
+const findBrowserTokenProviderWrongProxyPathFiles = (frontendSources) =>
+  frontendSources
+    .filter(sourceLooksLikeBrowserTokenProvider)
+    .filter((source) => {
+      const text = stripSourceNoise(source.text);
+      if (!/\bfetch\s*\(/.test(text)) return false;
+      const tokenPathLiterals = browserTokenPathLiterals(text).filter(
+        (literal) => BROWSER_TOKEN_PATH_PATTERN.test(literal),
+      );
+      if (tokenPathLiterals.length === 0) {
+        return false;
+      }
+      return tokenPathLiterals.some(
+        (literal) => !literal.includes(CANONICAL_BROWSER_TOKEN_PROXY_PATH),
+      );
+    })
+    .map((source) => source.file_path);
+
+const findBrowserTokenProviderNonClueEndpointEnvFiles = (frontendSources) =>
+  frontendSources
+    .filter(sourceLooksLikeBrowserTokenProvider)
+    .filter((source) =>
+      GENERIC_PUBLIC_API_ENV_PATTERN.test(stripSourceNoise(source.text)),
+    )
+    .map((source) => source.file_path);
+
+const findClueInitEmptyEnvFallbackFiles = (frontendSources) =>
+  frontendSources
+    .filter(
+      (source) =>
+        sourceImportsFrontendSdk(source) ||
+        sourceLooksLikeBrowserTokenProvider(source),
+    )
+    .filter((source) =>
+      /process\.env\.NEXT_PUBLIC_CLUE_[A-Z0-9_]+\s*(?:\?\?|\|\|)\s*(["'])\1/.test(
+        stripSourceNoise(source.text),
+      ),
+    )
+    .map((source) => source.file_path);
+
+const findFrontendInitBeforeClueInitFiles = (frontendSources) =>
+  frontendSources
+    .filter((source) => sourceImportsFrontendSdk(source))
+    .filter((source) => {
+      const text = stripSourceNoise(source.text, { stripStrings: true });
+      const initializedIndex = text.search(/\binitialized\s*=\s*true\b/);
+      const clueInitIndex = text.search(/\bClueInit\s*\(/);
+      return (
+        initializedIndex >= 0 &&
+        clueInitIndex >= 0 &&
+        initializedIndex < clueInitIndex
+      );
+    })
+    .map((source) => source.file_path);
+
 const sourceLooksLikeBrowserTokenProxy = (source) => {
   const text = stripSourceNoise(source.text);
   return (
@@ -827,6 +926,43 @@ const findBrowserTokenProxyUsingBackendServiceKeyFiles = (backendSources) =>
     })
     .map((source) => source.file_path);
 
+const bodyOriginPatterns = [
+  /\b(?:payload|body|requestBody|request_body|data|input)\.origin\b/i,
+  /\b(?:payload|body|requestBody|request_body|data|input)\s*\[\s*["']origin["']\s*\]/i,
+  /\b(?:payload|body|requestBody|request_body|data|input)\.get\s*\(\s*["']origin["']/i,
+  /["']origin["']\s*:\s*(?:payload|body|requestBody|request_body|data|input)\b/i,
+  /\borigin\s*=\s*(?:payload|body|requestBody|request_body|data|input)\b/i,
+];
+
+const bodyProjectEnvironmentPatterns = [
+  /\b(?:projectKey|project_key)\s*:\s*(?:payload|body|requestBody|request_body|data|input)\b/i,
+  /["'](?:projectKey|project_key)["']\s*:\s*(?:payload|body|requestBody|request_body|data|input)\b/i,
+  /\benvironment\s*:\s*(?:payload|body|requestBody|request_body|data|input)\b/i,
+  /["']environment["']\s*:\s*(?:payload|body|requestBody|request_body|data|input)\b/i,
+];
+
+const findBrowserTokenProxyTrustingBodyOriginFiles = (backendSources) =>
+  backendSources
+    .filter(sourceLooksLikeBrowserTokenProxy)
+    .filter((source) => {
+      const text = stripSourceNoise(source.text);
+      return bodyOriginPatterns.some((pattern) => pattern.test(text));
+    })
+    .map((source) => source.file_path);
+
+const findBrowserTokenProxyTrustingBodyProjectEnvironmentFiles = (
+  backendSources,
+) =>
+  backendSources
+    .filter(sourceLooksLikeBrowserTokenProxy)
+    .filter((source) => {
+      const text = stripSourceNoise(source.text);
+      return bodyProjectEnvironmentPatterns.some((pattern) =>
+        pattern.test(text),
+      );
+    })
+    .map((source) => source.file_path);
+
 const backendSdkSpec = (framework) =>
   BACKEND_SDK_BY_FRAMEWORK[String(framework ?? "").toLowerCase()] ?? {
     packages: Object.values(BACKEND_SDK_BY_FRAMEWORK).flatMap(
@@ -947,13 +1083,30 @@ const checkSdkLifecycle = ({
     findWildcardFrontendSdkDependencyFiles(dependencySources);
   const browserTokenProviderMissingServiceKeyFiles =
     findBrowserTokenProviderMissingServiceKeyFiles(frontendSources);
+  const browserTokenProviderWrongProxyPathFiles =
+    findBrowserTokenProviderWrongProxyPathFiles(frontendSources);
+  const browserTokenProviderNonClueEndpointEnvFiles =
+    findBrowserTokenProviderNonClueEndpointEnvFiles(frontendSources);
+  const clueInitEmptyEnvFallbackFiles =
+    findClueInitEmptyEnvFallbackFiles(frontendSources);
+  const frontendInitBeforeClueInitFiles =
+    findFrontendInitBeforeClueInitFiles(frontendSources);
   const nextBrowserTokenProviderMissingPublicServiceKeyFiles =
     findNextBrowserTokenProviderMissingPublicServiceKeyFiles({
       dependencySources,
       frontendSources,
     });
+  const nextBrowserTokenProviderMissingPublicEndpointFiles =
+    findNextBrowserTokenProviderMissingPublicEndpointFiles({
+      dependencySources,
+      frontendSources,
+    });
   const browserTokenProxyUsingBackendServiceKeyFiles =
     findBrowserTokenProxyUsingBackendServiceKeyFiles(backendSources);
+  const browserTokenProxyTrustingBodyOriginFiles =
+    findBrowserTokenProxyTrustingBodyOriginFiles(backendSources);
+  const browserTokenProxyTrustingBodyProjectEnvironmentFiles =
+    findBrowserTokenProxyTrustingBodyProjectEnvironmentFiles(backendSources);
   const backendIdentityRequired =
     backendPresent &&
     /\b(login|signin|sign_in|auth|token|session)\b/i.test(backendCombined);
@@ -1014,10 +1167,22 @@ const checkSdkLifecycle = ({
       wildcard_sdk_dependency_files: wildcardFrontendSdkDependencyFiles,
       browser_token_provider_missing_service_key_files:
         browserTokenProviderMissingServiceKeyFiles,
+      browser_token_provider_wrong_proxy_path_files:
+        browserTokenProviderWrongProxyPathFiles,
+      browser_token_provider_non_clue_endpoint_env_files:
+        browserTokenProviderNonClueEndpointEnvFiles,
+      clue_init_empty_env_fallback_files: clueInitEmptyEnvFallbackFiles,
+      frontend_init_before_clue_init_files: frontendInitBeforeClueInitFiles,
       next_browser_token_provider_missing_public_service_key_files:
         nextBrowserTokenProviderMissingPublicServiceKeyFiles,
+      next_browser_token_provider_missing_public_endpoint_files:
+        nextBrowserTokenProviderMissingPublicEndpointFiles,
       browser_token_proxy_uses_backend_service_key_files:
         browserTokenProxyUsingBackendServiceKeyFiles,
+      browser_token_proxy_trusts_body_origin_files:
+        browserTokenProxyTrustingBodyOriginFiles,
+      browser_token_proxy_trusts_body_project_environment_files:
+        browserTokenProxyTrustingBodyProjectEnvironmentFiles,
     },
     has_noop_wrapper: noOpPattern.test(combined),
     component_lifecycle_init_files: componentLifecycleInitFiles,
@@ -1037,8 +1202,15 @@ const checkSdkLifecycle = ({
       nextLifecycleNonPublicEnvFiles.length === 0 &&
       wildcardFrontendSdkDependencyFiles.length === 0 &&
       browserTokenProviderMissingServiceKeyFiles.length === 0 &&
+      browserTokenProviderWrongProxyPathFiles.length === 0 &&
+      browserTokenProviderNonClueEndpointEnvFiles.length === 0 &&
+      clueInitEmptyEnvFallbackFiles.length === 0 &&
+      frontendInitBeforeClueInitFiles.length === 0 &&
       nextBrowserTokenProviderMissingPublicServiceKeyFiles.length === 0 &&
+      nextBrowserTokenProviderMissingPublicEndpointFiles.length === 0 &&
       browserTokenProxyUsingBackendServiceKeyFiles.length === 0 &&
+      browserTokenProxyTrustingBodyOriginFiles.length === 0 &&
+      browserTokenProxyTrustingBodyProjectEnvironmentFiles.length === 0 &&
       !noOpPattern.test(combined) &&
       componentLifecycleInitFiles.length === 0 &&
       blockingLifecycleFiles.length === 0,