@clue-ai/cli 0.0.16 → 0.0.18

package/README.md

@@ -19,6 +19,7 @@ npx -y @clue-ai/cli semantic-inventory --framework fastapi --backend-root-path b
 npx -y @clue-ai/cli semantic-workflow --framework fastapi --backend-root-path backend --repo .
 npx -y @clue-ai/cli lifecycle-apply --plan clue-lifecycle-plan.json --repo .
 npx -y @clue-ai/cli setup-check --framework fastapi --backend-root-path backend --repo . --target codex --require-sdk-lifecycle
+npx -y @clue-ai/cli setup-doctor --local
 npx -y @clue-ai/cli setup-watch --project-key <key> --environment dev --clue-api-base-url <clue-api-base-url> --watch-targets frontend:web[init,identify,set-account,event-sent]=<frontend-url>,backend:api[init,identify,set-account,logout,event-sent]=<backend-url>
 npx -y @clue-ai/cli init --request clue-init-request.json --repo .
 npx -y @clue-ai/cli semantic-gen --request clue-semantic-request.json --repo .
@@ -62,6 +63,14 @@ leaks, and SDK lifecycle presence when requested. With
 installation, SDK imports in the target environments, app startup, and event
 delivery remain required before setup can be called complete.
 
+`npx -y @clue-ai/cli setup-doctor --local` checks API connectivity before
+user-operated lifecycle verification. It verifies the four setup hops:
+customer frontend to customer backend `/api/v1/clue/browser-tokens`, customer
+backend to Clue `/api/v1/ingest/browser-tokens`, customer frontend to Clue
+`/api/v1/ingest/browser`, and customer backend to Clue
+`/api/v1/ingest/backend`. It does not replace setup-watch because it does not
+exercise real login, account, or logout flows.
+
 `npx -y @clue-ai/cli setup-watch` polls the Clue API setup-check endpoint in
 remote mode while you operate the service. `--clue-api-base-url` is the Clue API
 URL, not the customer frontend URL. Use `--watch-targets` to list every

package/bin/clue-cli.mjs

@@ -19,6 +19,7 @@ import { applyLifecyclePlan } from "../src/lifecycle-init.mjs";
 import { runSemanticCi, runSemanticInventory } from "../src/semantic-ci.mjs";
 import { runSetupCheck } from "../src/setup-check.mjs";
 import { runSetupDetect } from "../src/setup-detect.mjs";
+import { runSetupDoctor } from "../src/setup-doctor.mjs";
 import { buildAiSetupHelp } from "../src/setup-help.mjs";
 import { runSetupPrepare } from "../src/setup-prepare.mjs";
 import { installSetupSkills } from "../src/setup-tool.mjs";
@@ -855,6 +856,7 @@ const usage = () =>
     `  ${clueCliCommand("semantic-workflow --framework fastapi --backend-root-path backend --repo .")}`,
     `  ${clueCliCommand("lifecycle-apply --plan clue-lifecycle-plan.json --repo .")}`,
     `  ${clueCliCommand("setup-check --framework fastapi --backend-root-path backend --repo . --target codex")}`,
+    `  ${clueCliCommand("setup-doctor --local")}`,
     `  ${clueCliCommand("init --request clue-init-request.json --repo .")}`,
     `  ${clueCliCommand("semantic-gen --request clue-semantic-request.json --repo . [--previous-snapshot-file previous.json]")}`,
     `  ${clueCliCommand("semantic-gen --request-env CLUE_SEMANTIC_REQUEST_JSON --repo .")}`,
@@ -919,6 +921,15 @@ const main = async () => {
     return;
   }
 
+  if (command === "setup-doctor") {
+    const report = await runSetupDoctor({ flags, repoRoot });
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    if (!report.passed) {
+      process.exitCode = 1;
+    }
+    return;
+  }
+
   if (command === "setup") {
     const report = await installSetupSkills({
       repoRoot,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clue-ai/cli",
-  "version": "0.0.16",
+  "version": "0.0.18",
   "type": "module",
   "bin": {
     "clue-ai": "bin/clue-cli.mjs"

package/src/contracts.mjs

@@ -81,7 +81,7 @@ export const buildInitReport = ({
 			frontend_api_key_exposed: false,
 			browser_token_endpoint_required: true,
 			browser_token_provider_required: true,
-			browser_token_endpoint_path: "/api/v1/ingest/browser-tokens",
+			browser_token_endpoint_path: "/api/v1/clue/browser-tokens",
 			clue_track_inserted: false,
 			clue_dom_tag_inserted: false,
 			allowed_source_paths: request.allowed_source_paths,

package/src/lifecycle-init.mjs

@@ -8,6 +8,11 @@ import {
   stripSourceNoise,
 } from "./lifecycle-guard.mjs";
 import { listAllowedSourceFiles } from "./path-policy.mjs";
+import {
+  API_CONNECTIVITY_CONTRACT,
+  DETERMINISTIC_CONTROL_MODEL,
+  SETUP_DOCTRINE,
+} from "./setup-ai-contract.mjs";
 
 const API_NAMES = new Set([
   "ClueInit",
@@ -543,8 +548,14 @@ const readContextFiles = async ({ repoRoot, request }) => {
 const buildLifecyclePrompt = ({ request, files }) =>
   JSON.stringify({
     task: "Add Clue SDK lifecycle API calls to this repository using exact text replacements.",
+    setup_doctrine: SETUP_DOCTRINE,
+    deterministic_control_model: DETERMINISTIC_CONTROL_MODEL,
+    api_connectivity_contract: API_CONNECTIVITY_CONTRACT,
     rules: [
       "Return JSON only.",
+      "Understand the setup doctrine before choosing edits. This is an external Clue integration, not a host app refactor or redesign task.",
+      "Use AI judgment only for lifecycle boundary placement. Let the CLI, generated skills, documentation contract, lifecycle plan schema, and setup-check static guards control deterministic mechanics.",
+      "If SDK signatures, environment names, browser token behavior, package installability, or verification ownership are unclear, return status blocked instead of guessing.",
       "Use only exact replacements. Each find string must be copied exactly from source.",
       "Add ClueInit, ClueIdentify, ClueSetAccount, and ClueLogout where repository code has clear lifecycle points.",
       "Official Clue SDK public lifecycle APIs are no-throw and own SDK failure isolation.",
@@ -569,15 +580,22 @@ const buildLifecyclePrompt = ({ request, files }) =>
       "Use environment variable names for Clue configuration values.",
       "For Python/FastAPI code, read CLUE_PROJECT_KEY, CLUE_ENVIRONMENT, CLUE_API_KEY, and CLUE_INGEST_ENDPOINT from the backend env block.",
       "CLUE_API_BASE_URL is not part of backend SDK initialization. Use it only when the application backend owns a browser-token proxy for a frontend service.",
-      "For Next.js browser/client code, read 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, read 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 place 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 use the customer'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.",
+      "Keep the four setup API hops distinct: customer frontend -> customer backend /api/v1/clue/browser-tokens, customer backend -> Clue /api/v1/ingest/browser-tokens, customer frontend -> Clue /api/v1/ingest/browser, and customer backend -> Clue /api/v1/ingest/backend.",
+      "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 request origin from trusted request headers or server request metadata. Do not trust origin, projectKey, or environment from JSON/body payload fields when calling Clue with 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.",
       "Do not add @clue-ai/browser-sdk or backend SDK dependencies with * or latest; use a concrete published version or package-manager-resolved semver range and update the repository lockfile when one exists.",
@@ -600,7 +618,10 @@ const buildLifecyclePrompt = ({ request, files }) =>
       tooling_api_base_url_env: "CLUE_API_BASE_URL",
       browser_ingest_endpoint_env: "framework_specific",
       nextjs_browser_ingest_endpoint_env: "NEXT_PUBLIC_CLUE_INGEST_ENDPOINT",
-      browser_token_endpoint_path: "/api/v1/ingest/browser-tokens",
+      client_backend_browser_token_proxy_path: "/api/v1/clue/browser-tokens",
+      nextjs_browser_token_endpoint_env:
+        "NEXT_PUBLIC_CLUE_BROWSER_TOKEN_ENDPOINT",
+      clue_backend_browser_token_issue_path: "/api/v1/ingest/browser-tokens",
       nextjs_browser_service_key_env: "NEXT_PUBLIC_CLUE_SERVICE_KEY",
       service_key: request.service_key,
     },

package/src/public-schema.cjs

@@ -174,6 +174,19 @@ const semanticSnapshotRouteOriginValues = [
     "changed_route_needs_review",
     "fallback",
 ];
+const semanticSnapshotPurposeChangeStateValues = [
+    "same_purpose",
+    "purpose_added",
+    "purpose_changed",
+    "purpose_removed",
+    "insufficient_evidence",
+    "new_route",
+];
+const semanticSnapshotActiveSemanticSourceValues = [
+    "previous_reused",
+    "new_confirmed",
+    "previous_kept_pending_review",
+];
 const targetObjectKeySchema = nonEmptyStringSchema.regex(snakeSegmentPattern, {
     message: "must be a lowercase snake_case key",
 });
@@ -237,6 +250,12 @@ const semanticSnapshotAnalysisSummarySchema = zod_1.z
         .int()
         .nonnegative()
         .default(0),
+    same_purpose_routes: zod_1.z.number().int().nonnegative().default(0),
+    purpose_added_routes: zod_1.z.number().int().nonnegative().default(0),
+    purpose_changed_routes: zod_1.z.number().int().nonnegative().default(0),
+    purpose_removed_routes: zod_1.z.number().int().nonnegative().default(0),
+    insufficient_evidence_routes: zod_1.z.number().int().nonnegative().default(0),
+    new_route_purpose_routes: zod_1.z.number().int().nonnegative().default(0),
 })
     .strict();
 const semanticSnapshotGenerationContractSchema = zod_1.z
@@ -408,6 +427,28 @@ const semanticSnapshotUnresolvedOperationEffectSchema = zod_1.z
     missing_context: zod_1.z.array(nonEmptyStringSchema).default([]),
 })
     .strict();
+const semanticSnapshotEvidencePacketSummarySchema = zod_1.z
+    .object({
+    contract_summary: nonEmptyStringSchema,
+    behavior_summary: nonEmptyStringSchema,
+    data_effect_hints: zod_1.z.array(nonEmptyStringSchema).default([]),
+    side_effect_hints: zod_1.z.array(nonEmptyStringSchema).default([]),
+    validation_hints: zod_1.z.array(nonEmptyStringSchema).default([]),
+    auth_hints: zod_1.z.array(nonEmptyStringSchema).default([]),
+    missing_context: zod_1.z.array(nonEmptyStringSchema).default([]),
+})
+    .strict();
+const semanticSnapshotSemanticStabilitySchema = zod_1.z
+    .object({
+    purpose_change_state: zod_1.z.enum(semanticSnapshotPurposeChangeStateValues),
+    confidence: confidenceSchema,
+    reason: nonEmptyStringSchema,
+    previous_route_input_hash: semanticSnapshotHashSchema.optional(),
+    previous_route_semantic_hash: semanticSnapshotHashSchema.optional(),
+    previous_semantic_snapshot_version: nonEmptyStringSchema.optional(),
+    missing_context: zod_1.z.array(nonEmptyStringSchema).default([]),
+})
+    .strict();
 const semanticMeaningCandidateValueSchema = zod_1.z.union([
     nonEmptyStringSchema,
     zod_1.z.number(),
@@ -470,6 +511,14 @@ const routeSemanticSnapshotEntrySchema = zod_1.z
         .default([]),
     source_evidence_refs: zod_1.z.array(nonEmptyStringSchema).default([]),
     confidence_reason: nonEmptyStringSchema,
+    purpose_change_state: zod_1.z
+        .enum(semanticSnapshotPurposeChangeStateValues)
+        .optional(),
+    active_semantic_source: zod_1.z
+        .enum(semanticSnapshotActiveSemanticSourceValues)
+        .optional(),
+    semantic_stability: semanticSnapshotSemanticStabilitySchema.optional(),
+    evidence_packet_summary: semanticSnapshotEvidencePacketSummarySchema.optional(),
 })
     .strict();
 const addDuplicateIssues = (ctx, values, path, label) => {
@@ -544,6 +593,38 @@ const semanticSnapshotRequestSchema = zod_1.z
             message: "semantic_snapshot_version is required for schema_version >= 2",
         });
     }
+    if (snapshot.schema_version >= 3) {
+        snapshot.routes.forEach((route, routeIndex) => {
+            if (!route.purpose_change_state) {
+                ctx.addIssue({
+                    code: "custom",
+                    path: ["routes", routeIndex, "purpose_change_state"],
+                    message: "routes[].purpose_change_state is required for schema_version >= 3",
+                });
+            }
+            if (!route.active_semantic_source) {
+                ctx.addIssue({
+                    code: "custom",
+                    path: ["routes", routeIndex, "active_semantic_source"],
+                    message: "routes[].active_semantic_source is required for schema_version >= 3",
+                });
+            }
+            if (!route.semantic_stability) {
+                ctx.addIssue({
+                    code: "custom",
+                    path: ["routes", routeIndex, "semantic_stability"],
+                    message: "routes[].semantic_stability is required for schema_version >= 3",
+                });
+            }
+            if (!route.evidence_packet_summary) {
+                ctx.addIssue({
+                    code: "custom",
+                    path: ["routes", routeIndex, "evidence_packet_summary"],
+                    message: "routes[].evidence_packet_summary is required for schema_version >= 3",
+                });
+            }
+        });
+    }
     addDuplicateIssues(ctx, snapshot.target_object_profiles.map((profile) => profile.id), ["target_object_profiles"], "target_object_profiles[].id");
     addDuplicateIssues(ctx, snapshot.target_object_mappings.map((mapping) => mapping.id), ["target_object_mappings"], "target_object_mappings[].id");
     addDuplicateIssues(ctx, snapshot.target_object_catalog.map((entry) => entry.target_object_key), ["target_object_catalog"], "target_object_catalog[].target_object_key");