@clue-ai/cli 0.0.16 → 0.0.18

package/src/setup-tool.mjs

@@ -7,6 +7,11 @@ import {
   CLUE_CLI_RECOMMENDED_PREFIX,
   clueCliCommand,
 } from "./cli-invocation.mjs";
+import {
+  AI_SETUP_CONTRACT_VERSION,
+  API_CONNECTIVITY_CONTRACT,
+  setupDoctrineSkillLines,
+} from "./setup-ai-contract.mjs";
 import { buildSetupDocumentationContract } from "./setup-documents.mjs";
 
 const SKILL_NAMES = [
@@ -19,7 +24,7 @@ const SKILL_NAMES = [
   "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 TARGETS = new Set(["codex", "claude_code"]);
 
@@ -82,7 +87,7 @@ const skillBody = (name, { documentsUrl } = {}) => {
     "clue-setup-audit":
       "Read-only monitoring agent. Owns P0/P1 review for one completed workstream at a time. It must not edit files.",
     "clue-local-verification":
-      "Read-only verification agent. Owns static setup checks, dependency/import/startup evidence, and user verification handoff. It must not edit files or run setup-watch automatically.",
+      "Read-only verification agent. Owns static setup checks, setup-doctor API connectivity preflight, dependency/import/startup evidence, and user verification handoff. It must not edit files or run setup-watch automatically.",
     "clue-setup-report":
       "Final reporting agent. Owns concise completion evidence only after execution and monitoring gates pass.",
   };
@@ -128,6 +133,7 @@ const skillBody = (name, { documentsUrl } = {}) => {
     ],
     "clue-local-verification": [
       "`setup-check` evidence",
+      "`setup-doctor --local` API connectivity preflight when local services and required env are available",
       "user-operated `setup-watch --local` handoff readiness",
       "local URL confirmation without assuming ports",
     ],
@@ -316,15 +322,21 @@ const skillBody = (name, { documentsUrl } = {}) => {
       "Delete the temporary lifecycle plan file after applying it unless the user explicitly asks to keep it for review.",
       "Use environment variable names for Clue configuration values; do not paste project keys or API keys into code.",
       `For local env files, use the service-specific env blocks written to \`.env.clue\` by \`${clueCliCommand("setup")}\`; do not ask the user to guess \`CLUE_SERVICE_KEY\`.`,
-      "For Next.js browser/client code, use only `NEXT_PUBLIC_CLUE_PROJECT_KEY`, `NEXT_PUBLIC_CLUE_ENVIRONMENT`, `NEXT_PUBLIC_CLUE_SERVICE_KEY`, and `NEXT_PUBLIC_CLUE_INGEST_ENDPOINT` from the frontend `.env.local` block.",
+      "For Next.js browser/client code, use only `NEXT_PUBLIC_CLUE_PROJECT_KEY`, `NEXT_PUBLIC_CLUE_ENVIRONMENT`, `NEXT_PUBLIC_CLUE_SERVICE_KEY`, `NEXT_PUBLIC_CLUE_INGEST_ENDPOINT`, and `NEXT_PUBLIC_CLUE_BROWSER_TOKEN_ENDPOINT` from the frontend `.env.local` block.",
       "Do not read `process.env.CLUE_PROJECT_KEY`, `process.env.CLUE_ENVIRONMENT`, `process.env.CLUE_SERVICE_KEY`, or `process.env.CLUE_INGEST_ENDPOINT` in Next.js browser/client code, and do not add non-public `CLUE_*` fallbacks there.",
+      "Frontend SDK adapter code is contract-owned Clue setup wiring. The AI may choose the existing import/mount point, but must not invent token URL, env, or initialization semantics.",
+      "For Next.js frontend adapters, read the full customer-backend browser-token proxy URL from `NEXT_PUBLIC_CLUE_BROWSER_TOKEN_ENDPOINT`. Do not derive it from `NEXT_PUBLIC_API_URL`, generic app API env names, detected backend ports, or relative frontend-origin paths.",
+      "Do not mix stale browser-token paths such as `/api/clue/browser-token`, `/clue/browser-tokens`, or `/browser-tokens` with the canonical `/api/v1/clue/browser-tokens` path.",
+      "Do not call `ClueInit` with empty-string fallbacks for required `NEXT_PUBLIC_CLUE_*` values. If required Clue env is absent, skip initialization and report the missing env names.",
+      "If a singleton guard is used, do not set `initialized = true` before `ClueInit` has actually been called with required config present.",
       "For non-Next.js browser code, use the exact frontend env names written in `.env.clue` for that service instead of inventing a framework-specific prefix.",
       "Never put `CLUE_API_KEY` in frontend code, frontend env files, browser bundles, or client-readable config.",
       "When browser SDK ingest is configured, implement a backend-owned browser token endpoint that reads server-side `CLUE_API_KEY` and requests `POST /api/v1/ingest/browser-tokens` from Clue.",
       "Configure frontend `ClueInit` with `browserTokenProvider` that calls the local backend token endpoint and returns the token string.",
-      "The local backend token endpoint is part of the customer app, not the Clue API. It may be named with the customer app's route convention, but it must call Clue server-side at `/api/v1/ingest/browser-tokens`.",
-      "The frontend `browserTokenProvider` must send the same service key used by `ClueInit` to the customer backend token endpoint. For Next.js this value comes from `NEXT_PUBLIC_CLUE_SERVICE_KEY`.",
-      "The browser token request must include project key, environment, service key, and the current browser origin; the backend must attach `x-clue-api-key` server-side when calling Clue.",
+      "The local backend token endpoint is part of the customer app, not the Clue API. Place it under a Clue-reserved local route such as `/api/v1/clue/browser-tokens`; do not use a generic path such as `/browser-tokens` that could be confused with product behavior. It must call Clue server-side at `/api/v1/ingest/browser-tokens`.",
+      "The frontend `browserTokenProvider` must call `NEXT_PUBLIC_CLUE_BROWSER_TOKEN_ENDPOINT` and send the same service key used by `ClueInit` to the customer backend token endpoint. For Next.js this value comes from `NEXT_PUBLIC_CLUE_SERVICE_KEY`.",
+      "The browser token request must include the frontend service key used by `ClueInit`. Project key and environment may be included only as public consistency hints; the backend must use server configuration or validate them against server configuration before calling Clue.",
+      "The backend browser token proxy must derive origin from trusted request headers or server request metadata. Do not forward `origin`, `projectKey`, or `environment` from JSON/body payload fields under server `CLUE_API_KEY`.",
       "For browser token proxy code, the service key sent to Clue must be the frontend `ClueInit` serviceKey from the browser request, not the backend service's `CLUE_SERVICE_KEY`.",
       "If a backend-owned browser token endpoint is implemented, read `CLUE_API_BASE_URL` from the backend env block and normalize it so values with or without a trailing `/api/v1` do not produce duplicate paths.",
       "For FastAPI code, add `clue-fastapi-sdk` to the backend dependency file when missing, import `clue_init_fastapi` plus `ClueIdentify`, `ClueSetAccount`, and `ClueLogout` where needed, and use `CLUE_PROJECT_KEY`, `CLUE_ENVIRONMENT`, `CLUE_API_KEY`, and `CLUE_INGEST_ENDPOINT` from the backend env block.",
@@ -359,12 +371,18 @@ const skillBody = (name, { documentsUrl } = {}) => {
       "Reject Django SDK setup when `clue-django-sdk` installability has not been verified.",
       "Reject backend setup when backend routes exist but no backend Clue SDK dependency/import/init was added.",
       "Reject awaited lifecycle calls that can block host service behavior.",
+      "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`, generic app API env names, detected backend ports, or non-Clue routing assumptions.",
+      "Reject frontend adapters that mix stale browser-token paths such as `/api/clue/browser-token`, `/clue/browser-tokens`, or `/browser-tokens` with the canonical `/api/v1/clue/browser-tokens` path.",
+      "Reject frontend adapters that set `initialized = true` before calling `ClueInit`, or pass empty-string fallbacks for required `NEXT_PUBLIC_CLUE_*` values into `ClueInit`.",
+      "Audit the setup diff against the Clue setup contract even when the code was written by another agent or an earlier pass. Ownership of authorship is irrelevant to approval.",
       "Reject setup that covers only one login path when multiple login success paths are clearly present.",
       "Reject ClueInit inside React component lifecycle hooks, page components, sidebars, login/register success callbacks, or any repeated user interaction path.",
       "Reject broad ClueTrack instrumentation and DOM clue tags.",
       "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 Clue SDK dependency entries that use `*` or `latest` instead of a concrete published version or package-manager-resolved semver range.",
+      "Reject Next.js browser token providers that do not read `NEXT_PUBLIC_CLUE_BROWSER_TOKEN_ENDPOINT`.",
       "Confirm no project key, API key, secret, or env value appears in diff or report.",
       "Confirm lifecycle insertions are minimal and reviewable.",
       "Reject whitespace-only edits, import sorting, formatter churn, or comment/style cleanup outside the exact Clue SDK wiring lines.",
@@ -384,6 +402,7 @@ const skillBody = (name, { documentsUrl } = {}) => {
       "Confirm the semantic workflow does not send GitHub actor, triggering_actor, sender, repository owner, repository name, or default branch to Clue.",
       "Confirm `.clue/semantic-request.runtime.json` is not created, committed, or staged.",
       `Run \`${clueCliCommand("setup-check --framework <framework> --backend-root-path <path> --repo . --target <codex|claude_code> --require-sdk-lifecycle")}\` when possible.`,
+      `Run \`${clueCliCommand("setup-doctor --local")}\` when local frontend/backend services are running and required env values are available. Report skipped_setup_doctor with the missing service URL or env name when it cannot run.`,
       `Do not run \`${clueCliCommand("setup-watch --local")}\` automatically. setup-watch requires the user to operate real local frontend/backend services and login/logout/account flows.`,
       "If the user has not provided setup-watch or setup-screen evidence, report event delivery verification as `user_verification_pending` and do not state `setup completed`.",
       "Local static verification passed does not mean setup complete unless dependency install, SDK imports, app startup, and user-provided setup-watch or setup-screen event delivery were all verified.",
@@ -436,6 +455,7 @@ const skillBody = (name, { documentsUrl } = {}) => {
     "",
     "# Shared Rules",
     "",
+    ...setupDoctrineSkillLines(),
     "- For full Clue setup, use one SDK lifecycle placement implementation agent and multiple monitoring agents for read-only checks.",
     `- Clue CLI public npm package: \`${CLUE_CLI_PACKAGE_NAME}\`.`,
     `- Clue CLI binary name exposed by that package: \`${CLUE_CLI_BINARY_NAME}\`; a global \`${CLUE_CLI_BINARY_NAME}\` install is not required.`,
@@ -451,7 +471,11 @@ const skillBody = (name, { documentsUrl } = {}) => {
     "- Only exact changes required to place ClueInit, ClueIdentify, ClueSetAccount, and ClueLogout are allowed. Do not perform ClueTrack instrumentation unless the user explicitly requested product event tracking.",
     "- Do not perform unrelated refactors, renames, file moves, formatting churn, broad cleanup, business logic rewrites, auth/session rewrites beyond minimal Clue hook insertion, UI changes unrelated to Clue setup, or unrelated dependency upgrades.",
     "- Do not run broad formatters or make whitespace-only cleanup. Keep formatting changes limited to lines directly touched for Clue SDK wiring.",
-    "- A customer backend browser-token endpoint is only a proxy for browser SDK token issuance. It is not the Clue API itself; the backend must call Clue server-side at `/api/v1/ingest/browser-tokens` with the frontend `ClueInit` service key supplied by the browser token provider.",
+    "- A customer backend browser-token endpoint is only a proxy for browser SDK token issuance. It must live under a Clue-reserved local route such as `/api/v1/clue/browser-tokens`, not a generic product-looking path such as `/browser-tokens`. It is not the Clue API itself; the backend must call Clue server-side at `/api/v1/ingest/browser-tokens` with the frontend `ClueInit` service key supplied by the browser token provider and server-owned project/environment values.",
+    `- Setup API connectivity has four distinct hops: ${Object.entries(API_CONNECTIVITY_CONTRACT.hops)
+      .map(([name, hop]) => `${name}=${hop.method} ${hop.path}`)
+      .join(", ")}.`,
+    `- Run \`${clueCliCommand("setup-doctor --local")}\` when local services and required env are available. This checks API connectivity only; it does not replace user-operated setup-watch.`,
     "- Do not implement or refresh semantic snapshot CI during lifecycle placement; report a blocker if generated semantic artifacts are missing or stale.",
     `- Do not run \`${clueCliCommand("setup-watch --local")}\` automatically. setup-watch and the Clue setup screen are user-operated verification steps, not implementation-agent responsibility.`,
     "- The full setup must start with `clue-setup-orchestrator`.",