@clue-ai/cli 0.0.16 → 0.0.18

package/src/setup-doctor.mjs

@@ -0,0 +1,442 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { API_CONNECTIVITY_CONTRACT } from "./setup-ai-contract.mjs";
+
+const DEFAULT_SETUP_MANIFEST_PATH = ".clue/setup-manifest.json";
+const BROWSER_TOKEN_PROXY_PATH =
+  API_CONNECTIVITY_CONTRACT.hops.client_backend_browser_token_proxy.path;
+const CLUE_BROWSER_TOKEN_PATH =
+  API_CONNECTIVITY_CONTRACT.hops.clue_backend_browser_token_issue.path;
+const BROWSER_INGEST_PATH = API_CONNECTIVITY_CONTRACT.hops.browser_ingest.path;
+const BACKEND_INGEST_PATH = API_CONNECTIVITY_CONTRACT.hops.backend_ingest.path;
+
+const optionalString = (value) =>
+  typeof value === "string" && value.trim() ? value.trim() : null;
+
+const trimTrailingSlash = (value) => String(value).replace(/\/+$/, "");
+
+const joinUrl = (baseUrl, path) => `${trimTrailingSlash(baseUrl)}${path}`;
+
+const readJsonIfPresent = async (path) => {
+  try {
+    return JSON.parse(await readFile(path, "utf8"));
+  } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw error;
+  }
+};
+
+const manifestWatchTargets = (manifest, kind) => {
+  const targets = manifest?.lifecycle_verification?.watch_targets;
+  if (!Array.isArray(targets)) return [];
+  return targets.filter((target) => target?.kind === kind);
+};
+
+const firstTargetUrl = ({ env, manifest, kind }) => {
+  for (const target of manifestWatchTargets(manifest, kind)) {
+    const explicitUrl = optionalString(target.url);
+    if (explicitUrl) return explicitUrl;
+    const envName = optionalString(target.url_env_name);
+    if (envName && optionalString(env[envName])) return optionalString(env[envName]);
+    const candidates = Array.isArray(target.local_url_candidates)
+      ? target.local_url_candidates
+      : [];
+    for (const candidate of candidates) {
+      const value = optionalString(candidate);
+      if (value) return value;
+    }
+  }
+  return null;
+};
+
+const firstTargetServiceKey = (manifest, kind) => {
+  for (const target of manifestWatchTargets(manifest, kind)) {
+    const serviceKey = optionalString(target.service_key ?? target.serviceKey);
+    if (serviceKey) return serviceKey;
+  }
+  return null;
+};
+
+const readTextResponse = async (response) => {
+  try {
+    return await response.text();
+  } catch {
+    return "";
+  }
+};
+
+const parseJsonText = (text) => {
+  try {
+    return text.trim() ? JSON.parse(text) : null;
+  } catch {
+    return null;
+  }
+};
+
+const postJson = async ({ body, fetchImpl, headers = {}, url }) => {
+  try {
+    const response = await fetchImpl(url, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        ...headers,
+      },
+      body: JSON.stringify(body),
+    });
+    const text = await readTextResponse(response);
+    return {
+      transportOk: true,
+      response,
+      text,
+      json: parseJsonText(text),
+    };
+  } catch (error) {
+    return {
+      transportOk: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+};
+
+const compactFailure = (result) => {
+  if (!result.transportOk) return result.error ?? "request failed";
+  const jsonMessage =
+    typeof result.json?.message === "string"
+      ? result.json.message
+      : typeof result.json?.error === "string"
+        ? result.json.error
+        : null;
+  return jsonMessage ?? result.text?.slice(0, 240) ?? "request failed";
+};
+
+const tokenFromResult = (result) =>
+  result.transportOk &&
+  result.response.ok &&
+  typeof result.json?.token === "string" &&
+  result.json.token.trim()
+    ? result.json.token.trim()
+    : null;
+
+const buildCheck = ({
+  error = null,
+  id,
+  method = "POST",
+  passed,
+  result = null,
+  url,
+}) => ({
+  id,
+  method,
+  url,
+  passed: Boolean(passed),
+  status: result?.transportOk ? result.response.status : null,
+  error: passed ? null : (error ?? compactFailure(result)),
+});
+
+const buildBrowserEventPayload = ({ environment, projectKey, serviceKey }) => {
+  const timestamp = new Date().toISOString();
+  const id = `setup_doctor_${Date.now()}`;
+  return {
+    batch_id: `batch_${id}`,
+    idempotency_key: `idem_${id}`,
+    sent_at: timestamp,
+    source_type: "browser_sdk",
+    source_schema_version: "1",
+    producer_metadata: {
+      producer_id: serviceKey,
+      sdk_type: "browser",
+      sdk_version: "setup-doctor",
+    },
+    events: [
+      {
+        event_id: `event_${id}`,
+        event_category: "custom",
+        event_name: "setup_doctor_browser_connectivity",
+        occurred_at: timestamp,
+        source_event_id: `event_${id}`,
+        source_schema_version: "1",
+        source_event_type: "setup_doctor_browser_connectivity",
+        source_event_kind: "custom",
+        producer_id: serviceKey,
+        project_key: projectKey,
+        environment,
+        properties: {},
+        metrics: { count: 1 },
+      },
+    ],
+  };
+};
+
+const buildBackendEventPayload = ({
+  apiKey,
+  backendServiceKey,
+  environment,
+  projectKey,
+}) => {
+  const timestamp = new Date().toISOString();
+  return {
+    projectKey,
+    apiKey,
+    environment,
+    sdkType: "backend",
+    sdkVersion: "setup-doctor",
+    schemaVersion: 1,
+    events: [
+      {
+        event_name: "setup_doctor_backend_connectivity",
+        occurred_at: timestamp,
+        service_key: backendServiceKey,
+        properties: {},
+        metrics: { count: 1 },
+      },
+    ],
+  };
+};
+
+const requiredInputCheck = ({ id, missing, url = null }) => ({
+  id,
+  method: "POST",
+  url,
+  passed: false,
+  status: null,
+  error: `missing required input: ${missing.join(", ")}`,
+});
+
+export const runSetupDoctor = async ({
+  env = process.env,
+  fetchImpl = fetch,
+  flags,
+  repoRoot = ".",
+}) => {
+  const manifestPath = String(
+    flags.get("manifest") || DEFAULT_SETUP_MANIFEST_PATH,
+  );
+  const manifest = await readJsonIfPresent(resolve(repoRoot, manifestPath));
+  const clueApiBaseUrl =
+    optionalString(flags.get("clue-api-base-url")) ??
+    optionalString(env.CLUE_API_BASE_URL) ??
+    optionalString(manifest?.clue_context?.clue_api_base_url);
+  const projectKey =
+    optionalString(flags.get("project-key")) ??
+    optionalString(env.CLUE_PROJECT_KEY) ??
+    optionalString(manifest?.clue_context?.project_key);
+  const environment =
+    optionalString(flags.get("environment")) ??
+    optionalString(env.CLUE_ENVIRONMENT) ??
+    optionalString(manifest?.clue_context?.environment) ??
+    "dev";
+  const apiKey =
+    optionalString(flags.get("clue-api-key")) ??
+    optionalString(env.CLUE_API_KEY);
+  const serviceKey =
+    optionalString(flags.get("service-key")) ??
+    optionalString(env.NEXT_PUBLIC_CLUE_SERVICE_KEY) ??
+    firstTargetServiceKey(manifest, "frontend");
+  const backendServiceKey =
+    optionalString(flags.get("backend-service-key")) ??
+    optionalString(env.CLUE_SERVICE_KEY) ??
+    firstTargetServiceKey(manifest, "backend") ??
+    serviceKey;
+  const clientBackendUrl =
+    optionalString(flags.get("client-backend-url")) ??
+    firstTargetUrl({ env, manifest, kind: "backend" });
+  const clientFrontendUrl =
+    optionalString(flags.get("client-frontend-url")) ??
+    firstTargetUrl({ env, manifest, kind: "frontend" });
+  const origin =
+    optionalString(flags.get("origin")) ??
+    clientFrontendUrl ??
+    "http://localhost";
+  const browserTokenProxyUrl =
+    optionalString(flags.get("browser-token-proxy-url")) ??
+    optionalString(env.NEXT_PUBLIC_CLUE_BROWSER_TOKEN_ENDPOINT) ??
+    optionalString(env.CLUE_BROWSER_TOKEN_ENDPOINT) ??
+    (clientBackendUrl ? joinUrl(clientBackendUrl, BROWSER_TOKEN_PROXY_PATH) : null);
+  const clueBrowserTokenUrl = clueApiBaseUrl
+    ? joinUrl(clueApiBaseUrl, CLUE_BROWSER_TOKEN_PATH)
+    : null;
+  const browserIngestUrl =
+    optionalString(flags.get("browser-ingest-url")) ??
+    optionalString(env.NEXT_PUBLIC_CLUE_INGEST_ENDPOINT) ??
+    optionalString(manifest?.clue_context?.ingest_endpoints?.browser) ??
+    (clueApiBaseUrl ? joinUrl(clueApiBaseUrl, BROWSER_INGEST_PATH) : null);
+  const backendIngestUrl =
+    optionalString(flags.get("backend-ingest-url")) ??
+    optionalString(env.CLUE_INGEST_ENDPOINT) ??
+    optionalString(manifest?.clue_context?.ingest_endpoints?.backend) ??
+    (clueApiBaseUrl ? joinUrl(clueApiBaseUrl, BACKEND_INGEST_PATH) : null);
+
+  const checks = [];
+
+  let proxyToken = null;
+  if (!browserTokenProxyUrl || !serviceKey) {
+    checks.push(
+      requiredInputCheck({
+        id: "client_backend_browser_token_proxy",
+        missing: [
+          ...(!browserTokenProxyUrl
+            ? [
+                "NEXT_PUBLIC_CLUE_BROWSER_TOKEN_ENDPOINT or CLUE_BROWSER_TOKEN_ENDPOINT or client-backend-url",
+              ]
+            : []),
+          ...(!serviceKey ? ["service-key"] : []),
+        ],
+        url: browserTokenProxyUrl,
+      }),
+    );
+  } else {
+    const result = await postJson({
+      fetchImpl,
+      url: browserTokenProxyUrl,
+      headers: { origin },
+      body: { serviceKey },
+    });
+    proxyToken = tokenFromResult(result);
+    checks.push(
+      buildCheck({
+        id: "client_backend_browser_token_proxy",
+        passed: Boolean(proxyToken),
+        result,
+        url: browserTokenProxyUrl,
+      }),
+    );
+  }
+
+  let directToken = null;
+  if (!clueBrowserTokenUrl || !apiKey || !projectKey || !environment || !serviceKey) {
+    checks.push(
+      requiredInputCheck({
+        id: "clue_backend_browser_token_issue",
+        missing: [
+          ...(!clueBrowserTokenUrl ? ["clue-api-base-url"] : []),
+          ...(!apiKey ? ["CLUE_API_KEY"] : []),
+          ...(!projectKey ? ["CLUE_PROJECT_KEY"] : []),
+          ...(!environment ? ["CLUE_ENVIRONMENT"] : []),
+          ...(!serviceKey ? ["service-key"] : []),
+        ],
+        url: clueBrowserTokenUrl,
+      }),
+    );
+  } else {
+    const result = await postJson({
+      fetchImpl,
+      url: clueBrowserTokenUrl,
+      headers: { "x-clue-api-key": apiKey },
+      body: {
+        projectKey,
+        environment,
+        serviceKey,
+        origin,
+      },
+    });
+    directToken = tokenFromResult(result);
+    checks.push(
+      buildCheck({
+        id: "clue_backend_browser_token_issue",
+        passed: Boolean(directToken),
+        result,
+        url: clueBrowserTokenUrl,
+      }),
+    );
+  }
+
+  const browserToken = proxyToken ?? directToken;
+  if (!browserIngestUrl || !projectKey || !environment || !serviceKey || !browserToken) {
+    checks.push(
+      requiredInputCheck({
+        id: "browser_ingest",
+        missing: [
+          ...(!browserIngestUrl ? ["browser-ingest-url"] : []),
+          ...(!projectKey ? ["CLUE_PROJECT_KEY"] : []),
+          ...(!environment ? ["CLUE_ENVIRONMENT"] : []),
+          ...(!serviceKey ? ["service-key"] : []),
+          ...(!browserToken ? ["browser token"] : []),
+        ],
+        url: browserIngestUrl,
+      }),
+    );
+  } else {
+    const result = await postJson({
+      fetchImpl,
+      url: browserIngestUrl,
+      headers: {
+        origin,
+        "x-clue-project-key": projectKey,
+        "x-clue-service-key": serviceKey,
+        "x-clue-browser-token": browserToken,
+        "x-clue-sdk-request": "browser",
+        "x-clue-environment": environment,
+        "x-clue-sdk-version": "setup-doctor",
+        "x-clue-source-schema-version": "1",
+      },
+      body: buildBrowserEventPayload({ environment, projectKey, serviceKey }),
+    });
+    checks.push(
+      buildCheck({
+        id: "browser_ingest",
+        passed: Boolean(result.transportOk && result.response.ok),
+        result,
+        url: browserIngestUrl,
+      }),
+    );
+  }
+
+  if (!backendIngestUrl || !apiKey || !projectKey || !environment || !backendServiceKey) {
+    checks.push(
+      requiredInputCheck({
+        id: "backend_ingest",
+        missing: [
+          ...(!backendIngestUrl ? ["backend-ingest-url"] : []),
+          ...(!apiKey ? ["CLUE_API_KEY"] : []),
+          ...(!projectKey ? ["CLUE_PROJECT_KEY"] : []),
+          ...(!environment ? ["CLUE_ENVIRONMENT"] : []),
+          ...(!backendServiceKey ? ["backend-service-key"] : []),
+        ],
+        url: backendIngestUrl,
+      }),
+    );
+  } else {
+    const result = await postJson({
+      fetchImpl,
+      url: backendIngestUrl,
+      headers: {
+        "x-clue-project-key": projectKey,
+        "x-clue-api-key": apiKey,
+      },
+      body: buildBackendEventPayload({
+        apiKey,
+        backendServiceKey,
+        environment,
+        projectKey,
+      }),
+    });
+    checks.push(
+      buildCheck({
+        id: "backend_ingest",
+        passed: Boolean(result.transportOk && result.response.ok),
+        result,
+        url: backendIngestUrl,
+      }),
+    );
+  }
+
+  const passed = checks.every((check) => check.passed);
+  return {
+    status: passed ? "passed" : "failed",
+    passed,
+    contract: API_CONNECTIVITY_CONTRACT,
+    checks,
+    inputs: {
+      manifest_loaded: Boolean(manifest),
+      client_backend_url_configured: Boolean(clientBackendUrl),
+      client_frontend_url_configured: Boolean(clientFrontendUrl),
+      browser_token_proxy_url_configured: Boolean(browserTokenProxyUrl),
+      clue_api_base_url_configured: Boolean(clueApiBaseUrl),
+      project_key_configured: Boolean(projectKey),
+      environment_configured: Boolean(environment),
+      service_key_configured: Boolean(serviceKey),
+      backend_service_key_configured: Boolean(backendServiceKey),
+      clue_api_key_configured: Boolean(apiKey),
+    },
+  };
+};

package/src/setup-help.mjs

@@ -2,9 +2,16 @@ import {
   CLUE_CLI_INVOCATION_CONTRACT,
   clueCliCommand,
 } from "./cli-invocation.mjs";
+import {
+  AI_SETUP_CONTRACT_VERSION,
+  API_CONNECTIVITY_CONTRACT,
+  DETERMINISTIC_CONTROL_MODEL,
+  FRONTEND_ADAPTER_CONTRACT,
+  SETUP_DOCTRINE,
+} from "./setup-ai-contract.mjs";
 import { buildSetupDocumentationContract } from "./setup-documents.mjs";
 
-export const AI_SETUP_HELP_VERSION = "2026-05-10.lifecycle-placement-only.v4";
+export const AI_SETUP_HELP_VERSION = AI_SETUP_CONTRACT_VERSION;
 
 export const buildAiSetupHelp = () => ({
   name: "@clue-ai/cli AI setup help",
@@ -13,6 +20,10 @@ export const buildAiSetupHelp = () => ({
     "Machine-readable Clue setup contract for AI coding agents. Use this before editing a customer repository for Clue setup.",
   cli_invocation: CLUE_CLI_INVOCATION_CONTRACT,
   setup_execution_contract: {
+    setup_doctrine: SETUP_DOCTRINE,
+    deterministic_control_model: DETERMINISTIC_CONTROL_MODEL,
+    api_connectivity_contract: API_CONNECTIVITY_CONTRACT,
+    frontend_adapter_contract: FRONTEND_ADAPTER_CONTRACT,
     agent_primary_task:
       "Decide where to place ClueInit, ClueIdentify, ClueSetAccount, and ClueLogout in existing repository lifecycle boundaries, then apply only those minimal Clue SDK wiring changes.",
     implementation_workstreams: ["sdk_lifecycle_placement"],
@@ -51,12 +62,15 @@ export const buildAiSetupHelp = () => ({
           "NEXT_PUBLIC_CLUE_ENVIRONMENT",
           "NEXT_PUBLIC_CLUE_SERVICE_KEY",
           "NEXT_PUBLIC_CLUE_INGEST_ENDPOINT",
+          "NEXT_PUBLIC_CLUE_BROWSER_TOKEN_ENDPOINT",
         ],
-        rule: "When the frontend framework is Next.js, browser/client code must read only these NEXT_PUBLIC_* Clue variables. Do not add process.env.CLUE_* fallbacks in client-bundled code.",
+        rule: "When the frontend framework is Next.js, browser/client code must read only these NEXT_PUBLIC_* Clue variables. Do not add process.env.CLUE_* fallbacks in client-bundled code. browserTokenProvider must call NEXT_PUBLIC_CLUE_BROWSER_TOKEN_ENDPOINT, not a relative frontend-origin path or generic NEXT_PUBLIC_API_URL.",
       },
       backend_browser_token_proxy_env: {
         variables: ["CLUE_API_KEY", "CLUE_API_BASE_URL"],
         rule: "CLUE_API_KEY stays server-side. CLUE_API_BASE_URL is used only by backend-owned browser token proxy code and is not part of backend SDK initialization. The proxy endpoint belongs to the customer backend, but it calls the Clue API server-side at /api/v1/ingest/browser-tokens. The frontend browserTokenProvider must send the frontend ClueInit serviceKey to that customer backend proxy, and the proxy must issue browser tokens for that frontend serviceKey, not the backend service key.",
+        origin_rule:
+          "The backend proxy must derive request origin from trusted request headers or server request metadata. Project key and environment must come from server configuration or be validated against it. Do not forward origin, projectKey, or environment from JSON/body payload fields under server CLUE_API_KEY.",
       },
     },
     documentation_contract: buildSetupDocumentationContract(),
@@ -68,6 +82,13 @@ export const buildAiSetupHelp = () => ({
       ai_agent_responsibility:
         "Report the command and required user verification as pending when it was not run by the user.",
     },
+    setup_doctor: {
+      owner: "ai_or_user",
+      ai_agent_may_run: true,
+      command: clueCliCommand("setup-doctor --local"),
+      rule: "Run setup-doctor after local frontend/backend services and required env are available. It checks API connectivity only and does not replace user-operated setup-watch.",
+      checked_hops: Object.keys(API_CONNECTIVITY_CONTRACT.hops),
+    },
     completion_boundary: {
       ai_may_claim: [
         "Clue setup code changes were applied",

package/src/setup-prepare.mjs

@@ -8,6 +8,7 @@ import {
   CLUE_CLI_INVOCATION_CONTRACT,
   clueCliCommand,
 } from "./cli-invocation.mjs";
+import { API_CONNECTIVITY_CONTRACT } from "./setup-ai-contract.mjs";
 import { buildSetupDocumentationContract } from "./setup-documents.mjs";
 import { runSetupDetect } from "./setup-detect.mjs";
 
@@ -15,11 +16,14 @@ const DEFAULT_SETUP_MANIFEST_PATH = ".clue/setup-manifest.json";
 const DEFAULT_ENV_GUIDE_PATH = ".env.clue";
 const BROWSER_INGEST_PATH = "/api/v1/ingest/browser";
 const BACKEND_INGEST_PATH = "/api/v1/ingest/backend";
+const BROWSER_TOKEN_PROXY_PATH =
+  API_CONNECTIVITY_CONTRACT.hops.client_backend_browser_token_proxy.path;
 const FRONTEND_PUBLIC_ENV_NAMES = [
   "CLUE_INGEST_ENDPOINT",
   "CLUE_PROJECT_KEY",
   "CLUE_ENVIRONMENT",
   "CLUE_SERVICE_KEY",
+  "CLUE_BROWSER_TOKEN_ENDPOINT",
 ];
 const BACKEND_RUNTIME_ENV_NAMES = [
   "CLUE_SERVICE_KEY",
@@ -186,6 +190,7 @@ const frontendEnvName = ({ target, name }) =>
     : name;
 
 const buildServiceEnvBlock = ({
+  browserTokenEndpoint,
   target,
   setupContext,
   includeBrowserTokenProxyConfig = false,
@@ -210,6 +215,12 @@ const buildServiceEnvBlock = ({
       value: target.service_key,
     },
   ];
+  if (target.kind === "frontend") {
+    variables.push({
+      name: frontendEnvName({ target, name: "CLUE_BROWSER_TOKEN_ENDPOINT" }),
+      value: browserTokenEndpoint,
+    });
+  }
   if (target.kind === "backend") {
     variables.push({ name: "CLUE_API_KEY", value: setupContext.clue_api_key });
     if (includeBrowserTokenProxyConfig) {
@@ -265,6 +276,14 @@ const buildEnvironmentInstructions = ({ manifest, setupContext }) => {
   const includeBrowserTokenProxyConfig = watchTargets.some(
     (target) => target.kind === "frontend",
   );
+  const backendTarget = watchTargets.find((target) => target.kind === "backend");
+  const backendUrlCandidate =
+    optionalString(backendTarget?.local_url_candidates?.[0]) ??
+    "http://<client-backend-url>";
+  const browserTokenEndpoint = buildEndpoint(
+    backendUrlCandidate,
+    BROWSER_TOKEN_PROXY_PATH,
+  );
   return {
     status: "ready",
     env_file_path: DEFAULT_ENV_GUIDE_PATH,
@@ -276,6 +295,7 @@ const buildEnvironmentInstructions = ({ manifest, setupContext }) => {
       service_key: target.service_key,
       env_file_candidates: envFileCandidates(target),
       env_block: buildServiceEnvBlock({
+        browserTokenEndpoint,
         target,
         setupContext,
         includeBrowserTokenProxyConfig,
@@ -488,6 +508,7 @@ export const runSetupPrepare = async ({
       project_key: setupContext.project_key,
       environment: setupContext.environment,
       clue_api_base_url: setupContext.clue_api_base_url,
+      api_connectivity_contract: API_CONNECTIVITY_CONTRACT,
       ingest_endpoints: setupContext.clue_api_base_url
         ? {
             browser: buildEndpoint(
@@ -557,6 +578,12 @@ export const runSetupPrepare = async ({
         completion_meaning:
           "required before setup-watch local completion can be trusted",
       },
+      {
+        id: "local_api_connectivity_preflight",
+        command: clueCliCommand("setup-doctor --local"),
+        completion_meaning:
+          "required before user setup-watch; verifies customer proxy, Clue browser-token issuance, browser ingest, and backend ingest connectivity when local services and required env are available",
+      },
       {
         id: "local_event_delivery",
         command: `user runs ${clueCliCommand("setup-watch --local")}`,