@clue-ai/cli 0.0.18 → 0.0.20

package/src/semantic-ci.mjs

@@ -644,6 +644,9 @@ const generateAiRoutesPerRoute = async ({
         );
       }
     } catch (error) {
+      if (error instanceof SyntaxError) {
+        throw error;
+      }
       aiRoutes.set(
         route.operation_source_key,
         unavailableAiRoute(
@@ -2066,25 +2069,31 @@ const buildSnapshot = ({
       };
     }
 
+    const effectivePlan =
+      !aiRoute?.semantics && plan.active_semantic_source === "new_confirmed"
+        ? unconfirmedFallbackPlan({ plan, reason: unavailableReason })
+        : plan;
+
     return withStabilityMetadata({
       currentRoute: route,
-      plan,
+      plan: effectivePlan,
       route: {
         ...baseRoute,
         operation_effects: assignmentCollections.operationEffects,
         unresolved_operation_effects:
           assignmentCollections.unresolvedOperationEffects,
         source_evidence_refs: routeEvidenceRefs.map((entry) => entry.id),
-        route_input_hash: plan.route_input_hash,
-        previous_route_input_hash: plan.previous_route_input_hash,
-        previous_route_semantic_hash: plan.previous_route_semantic_hash,
+        route_input_hash: effectivePlan.route_input_hash,
+        previous_route_input_hash: effectivePlan.previous_route_input_hash,
+        previous_route_semantic_hash: effectivePlan.previous_route_semantic_hash,
         semantic_origin:
-          plan.origin === "changed_route_needs_review" && aiRoute?.semantics
+          effectivePlan.origin === "changed_route_needs_review" &&
+          aiRoute?.semantics
             ? "changed_route_needs_review"
-            : plan.origin,
-        semantic_change_reason: plan.semantic_change_reason,
+            : effectivePlan.origin,
+        semantic_change_reason: effectivePlan.semantic_change_reason,
         previous_semantic_snapshot_version:
-          plan.previous_route?.semantic_snapshot_version,
+          effectivePlan.previous_route?.semantic_snapshot_version,
         route_semantic_hash: routeSemanticHash({
           ...baseRoute,
           operation_effects: assignmentCollections.operationEffects,
@@ -2463,8 +2472,16 @@ const routeSourceForPolicy = (route) =>
 const classifyClueInfrastructureRoute = (route) => {
   const source = routeSourceForPolicy(route);
   const reservedPath = isReservedClueBrowserTokenPath(route.path_template);
-  const proxiesToClueBrowserTokenApi =
+  const directlyCallsClueBrowserTokenApi =
     /\/(?:api\/v[0-9]+\/)?ingest\/browser-tokens\b/i.test(source);
+  const usesClueBrowserTokenRequestContract =
+    /\bCLUE_API_BASE_URL\b/.test(source) &&
+    /\bCLUE_PROJECT_KEY\b/.test(source) &&
+    /\bCLUE_ENVIRONMENT\b/.test(source) &&
+    /\bserviceKey\b/.test(source) &&
+    /\b(?:client|httpx)\.post\b/.test(source);
+  const proxiesToClueBrowserTokenApi =
+    directlyCallsClueBrowserTokenApi || usesClueBrowserTokenRequestContract;
   const usesServerSideClueApiKey = /\bCLUE_API_KEY\b|x-clue-api-key/i.test(
     source,
   );
@@ -2481,6 +2498,8 @@ const classifyClueInfrastructureRoute = (route) => {
       evidence: {
         reserved_clue_path: true,
         proxies_to_clue_browser_token_api: true,
+        uses_clue_browser_token_request_contract:
+          usesClueBrowserTokenRequestContract,
         uses_server_side_clue_api_key: true,
       },
     };
@@ -2491,6 +2510,8 @@ const classifyClueInfrastructureRoute = (route) => {
     evidence: {
       reserved_clue_path: reservedPath,
       proxies_to_clue_browser_token_api: proxiesToClueBrowserTokenApi,
+      uses_clue_browser_token_request_contract:
+        usesClueBrowserTokenRequestContract,
       uses_server_side_clue_api_key: usesServerSideClueApiKey,
     },
   };
@@ -2853,6 +2874,19 @@ const withStabilityMetadata = ({ route, currentRoute, plan }) => ({
   evidence_packet_summary: buildEvidencePacketSummary(currentRoute),
 });
 
+const unconfirmedFallbackPlan = ({ plan, reason }) => ({
+  ...plan,
+  origin: "fallback",
+  purpose_change_state: "insufficient_evidence",
+  active_semantic_source: "new_unconfirmed",
+  stability_confidence: 0,
+  stability_missing_context: [
+    ...safeArray(plan.stability_missing_context),
+    "AI route semantic generation did not produce usable active semantics.",
+  ],
+  semantic_change_reason: reason,
+});
+
 const fieldPathMatchesKeys = ({
   fieldPath,
   routeKeys,
@@ -3246,6 +3280,31 @@ const sendSnapshot = async ({ request, env, snapshot }) => {
   }
 };
 
+const routeHasUsableActiveSemantics = (route) =>
+  route.semantics.route_confidence > 0 ||
+  safeArray(route.operation_effects).length > 0 ||
+  ["previous_reused", "previous_kept_pending_review"].includes(
+    route.active_semantic_source,
+  );
+
+const assertSemanticSnapshotUploadable = (snapshot) => {
+  const authFailureRoute = snapshot.routes.find((route) =>
+    /provider_(401|403)\b/.test(route.confidence_reason ?? ""),
+  );
+  if (authFailureRoute) {
+    throw new Error(
+      `semantic snapshot generation failed before upload: AI provider authentication failed for ${authFailureRoute.operation_source_key}`,
+    );
+  }
+  const usableRouteCount = snapshot.routes.filter(routeHasUsableActiveSemantics)
+    .length;
+  if (snapshot.routes.length > 0 && usableRouteCount === 0) {
+    throw new Error(
+      "semantic snapshot generation produced zero usable route semantics; refusing upload",
+    );
+  }
+};
+
 const assertSemanticSnapshotAudit = ({
   routes,
   snapshot,
@@ -3274,6 +3333,7 @@ const assertSemanticSnapshotAudit = ({
     "changed_route_semantic_reused",
     "changed_route_semantic_regenerated",
     "changed_route_needs_review",
+    "fallback",
   ]);
   for (const route of auditedSnapshot.routes) {
     const currentRoute = routeByKey.get(route.operation_source_key);
@@ -3347,6 +3407,25 @@ const assertSemanticSnapshotAudit = ({
           `semantic snapshot audit found missing previous metadata for added purpose: ${route.operation_source_key}`,
         );
       }
+      if (
+        route.active_semantic_source === "new_confirmed" &&
+        route.semantics.route_confidence === 0 &&
+        safeArray(route.operation_effects).length === 0
+      ) {
+        throw new Error(
+          `semantic snapshot audit found confirmed semantics without usable evidence: ${route.operation_source_key}`,
+        );
+      }
+      if (
+        route.active_semantic_source === "new_unconfirmed" &&
+        (route.semantic_origin !== "fallback" ||
+          route.purpose_change_state !== "insufficient_evidence" ||
+          route.semantic_stability.confidence !== 0)
+      ) {
+        throw new Error(
+          `semantic snapshot audit found inconsistent unconfirmed fallback semantics: ${route.operation_source_key}`,
+        );
+      }
     }
     if (
       (route.semantic_origin === "unchanged_route_reused" ||
@@ -3495,6 +3574,7 @@ export const runSemanticCi = async ({
     generationContract,
     aiRuntime,
   });
+  assertSemanticSnapshotUploadable(snapshot);
   const upload = await sendSnapshot({ request, env, snapshot });
   return {
     accepted: upload.accepted === true,

package/src/setup-agent.mjs

@@ -0,0 +1,504 @@
+import { access, readFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import {
+  applyLifecyclePlan,
+  planLifecycleInsertionsStrict,
+} from "./lifecycle-init.mjs";
+import { runSetupCheck } from "./setup-check.mjs";
+import { runSetupDoctor } from "./setup-doctor.mjs";
+
+const DEFAULT_SETUP_MANIFEST_PATH = ".clue/setup-manifest.json";
+const DEFAULT_ENV_GUIDE_PATH = ".env.clue";
+const DEFAULT_MAX_ATTEMPTS = 3;
+const REQUIRED_SETUP_AGENT_AI_ENV_NAMES = [
+  "CLUE_AI_PROVIDER",
+  "CLUE_AI_PROVIDER_API_KEY",
+  "CLUE_AI_MODEL",
+];
+const DEPENDENCY_WRITE_FILE_CANDIDATES = [
+  "package.json",
+  "package-lock.json",
+  "pnpm-lock.yaml",
+  "yarn.lock",
+  "bun.lock",
+  "requirements.txt",
+  "requirements-dev.txt",
+  "pyproject.toml",
+  "Pipfile",
+  "Pipfile.lock",
+  "poetry.lock",
+];
+
+const optionalString = (value) =>
+  typeof value === "string" && value.trim() ? value.trim() : null;
+
+const readJson = async (path) => JSON.parse(await readFile(path, "utf8"));
+
+const parseEnvGuide = (text) => {
+  const values = {};
+  for (const line of text.split(/\r?\n/)) {
+    const match = /^\s*([A-Z][A-Z0-9_]*)=(.*)\s*$/.exec(line);
+    if (!match) continue;
+    const value = match[2].trim().replace(/^(['"])(.*)\1$/, "$2");
+    if (/^<[^>]+>$/.test(value)) continue;
+    values[match[1]] = value;
+  }
+  return values;
+};
+
+const readEnvGuideIfPresent = async ({ repoRoot }) => {
+  try {
+    return parseEnvGuide(
+      await readFile(resolve(repoRoot, DEFAULT_ENV_GUIDE_PATH), "utf8"),
+    );
+  } catch (error) {
+    if (error?.code === "ENOENT") return {};
+    throw error;
+  }
+};
+
+const exists = async (path) => {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+const normalizePositiveInteger = (value, fallback) => {
+  const parsed = Number.parseInt(String(value ?? ""), 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+};
+
+const aiProviderEnvFromFlags = ({ env, flags }) => {
+  const aiProvider = optionalString(flags.get("ai-provider"));
+  const aiProviderApiKey = optionalString(flags.get("ai-provider-api-key"));
+  const aiModel = optionalString(flags.get("ai-model"));
+  return {
+    ...env,
+    ...(aiProvider ? { CLUE_AI_PROVIDER: aiProvider } : {}),
+    ...(aiProviderApiKey
+      ? { CLUE_AI_PROVIDER_API_KEY: aiProviderApiKey }
+      : {}),
+    ...(aiModel ? { CLUE_AI_MODEL: aiModel } : {}),
+  };
+};
+
+const missingSetupAgentAiEnvNames = (env) =>
+  REQUIRED_SETUP_AGENT_AI_ENV_NAMES.filter((name) => !optionalString(env[name]));
+
+const blockedMissingAiProviderConfig = ({ manifestPath, missingInputs }) => ({
+  status: "blocked",
+  code: "CLUE_SETUP_AGENT_AI_CONFIG_MISSING",
+  manifest_path: manifestPath,
+  attempts: [],
+  setup_check: null,
+  setup_doctor: {
+    status: "skipped",
+    reason: "AI provider configuration is missing",
+    missing_inputs: missingInputs,
+    report: null,
+  },
+  blockers: [
+    {
+      reason:
+        "setup-agent requires CLUE_AI_PROVIDER, CLUE_AI_PROVIDER_API_KEY, and CLUE_AI_MODEL before lifecycle planning",
+      evidence: {
+        missing_inputs: missingInputs,
+        env_file_path: DEFAULT_ENV_GUIDE_PATH,
+        supported_providers: ["openai", "anthropic"],
+        cli_flags: [
+          "--ai-provider",
+          "--ai-provider-api-key",
+          "--ai-model",
+        ],
+      },
+    },
+  ],
+  next_steps: [
+    "Open .env.clue and replace CLUE_AI_PROVIDER_API_KEY with an OpenAI API key for codex or an Anthropic API key for claude_code.",
+    "Confirm CLUE_AI_PROVIDER and CLUE_AI_MODEL are set in .env.clue or process env.",
+    "Alternatively run setup-agent with --ai-provider, --ai-provider-api-key, and --ai-model.",
+  ],
+  user_verification: {
+    setup_watch_owner: "user",
+    setup_watch_auto_run: false,
+    status: "not_reached",
+    required_command: "npx -y @clue-ai/cli setup-watch --local",
+  },
+});
+
+const requireManifest = async ({ manifestPath, repoRoot }) => {
+  try {
+    return await readJson(resolve(repoRoot, manifestPath));
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      const blocker = new Error(
+        `setup-agent requires ${manifestPath}; run setup first`,
+      );
+      blocker.code = "CLUE_SETUP_MANIFEST_MISSING";
+      throw blocker;
+    }
+    throw error;
+  }
+};
+
+const sourcePathsFromManifest = (manifest) => {
+  const watchTargets = Array.isArray(
+    manifest.lifecycle_verification?.watch_targets,
+  )
+    ? manifest.lifecycle_verification.watch_targets
+    : [];
+  return [
+    ...new Set(
+      [
+        manifest.detected?.backend_root_path,
+        ...watchTargets.map((target) => target?.root_path),
+      ]
+        .map(optionalString)
+        .filter(Boolean),
+    ),
+  ];
+};
+
+const dependencyCandidateRoots = (sourcePaths) => [
+  ".",
+  ...sourcePaths.flatMap((root) => {
+    const normalized = root.replace(/\/+$/, "");
+    return normalized.endsWith("/src") || normalized.endsWith("/app")
+      ? [normalized, dirname(normalized)]
+      : [normalized];
+  }),
+];
+
+const discoveredDependencyWritePaths = async ({ repoRoot, sourcePaths }) => {
+  const candidates = dependencyCandidateRoots(sourcePaths).flatMap((root) =>
+    DEPENDENCY_WRITE_FILE_CANDIDATES.map((file) =>
+      root === "." ? file : join(root, file),
+    ),
+  );
+  const discovered = [];
+  for (const candidate of [...new Set(candidates)]) {
+    if (await exists(resolve(repoRoot, candidate))) {
+      discovered.push(candidate);
+    }
+  }
+  return discovered;
+};
+
+const allowedWritePathsFromRequest = async ({ repoRoot, request }) => [
+  ...new Set([
+    ...request.allowed_source_paths,
+    ...(await discoveredDependencyWritePaths({
+      repoRoot,
+      sourcePaths: request.allowed_source_paths,
+    })),
+  ]),
+];
+
+const buildLifecycleRequestFromManifest = ({ manifest, target }) => {
+  if (manifest?.status !== "ready_for_ai") {
+    throw new Error("setup-agent requires a ready_for_ai setup manifest");
+  }
+  const framework = optionalString(manifest.detected?.framework);
+  const backendRootPath = optionalString(manifest.detected?.backend_root_path);
+  const serviceKey = optionalString(manifest.detected?.service_key);
+  const sourcePaths = sourcePathsFromManifest(manifest);
+  if (!framework || !backendRootPath || !serviceKey || sourcePaths.length === 0) {
+    throw new Error(
+      "setup-agent manifest is missing framework, backend root, service key, or source paths",
+    );
+  }
+  return {
+    target_tool: optionalString(target) ?? optionalString(manifest.target) ?? "codex",
+    framework,
+    project_key: "CLUE_PROJECT_KEY",
+    environment: "CLUE_ENVIRONMENT",
+    service_key: serviceKey,
+    allowed_source_paths: sourcePaths,
+    excluded_source_paths: [],
+    backend_root_path: backendRootPath,
+  };
+};
+
+const failedChecks = (setupCheck) =>
+  Array.isArray(setupCheck?.checks)
+    ? setupCheck.checks
+        .filter((check) => !check.passed)
+        .map((check) => ({
+          id: check.id,
+          summary: check.summary ?? null,
+          details: {
+            missing_apis: check.missing_apis ?? null,
+            backend_lifecycle: check.backend_lifecycle ?? null,
+            frontend_lifecycle: check.frontend_lifecycle ?? null,
+            findings: check.findings ?? null,
+          },
+        }))
+    : [];
+
+const runStaticSetupCheck = async ({
+  manifest,
+  repoRoot,
+  request,
+  setupChecker,
+  target,
+}) =>
+  setupChecker({
+    repoRoot,
+    request: {
+      framework: request.framework,
+      backend_root_path: request.backend_root_path,
+      allowed_source_paths: request.allowed_source_paths,
+      excluded_source_paths: request.excluded_source_paths,
+      service_key: request.service_key,
+      workflow_path: manifest.artifacts?.ci_workflow_path,
+    },
+    target,
+    requireSdkLifecycle: true,
+  });
+
+const missingInputsFromDoctor = (report) => [
+  ...new Set(
+    (report?.checks ?? [])
+      .flatMap((check) => {
+        const match = /^missing required input: (?<names>.+)$/.exec(
+          check.error ?? "",
+        );
+        return match?.groups?.names
+          ? match.groups.names.split(",").map((entry) => entry.trim())
+          : [];
+      })
+      .filter(Boolean),
+  ),
+];
+
+const runOptionalSetupDoctor = async ({ env, flags, repoRoot, setupDoctor }) => {
+  if (flags.has("skip-setup-doctor")) {
+    return {
+      status: "skipped",
+      reason: "skip-setup-doctor flag was provided",
+      missing_inputs: [],
+      report: null,
+    };
+  }
+  const report = await setupDoctor({ env, flags, repoRoot });
+  const missingInputs = missingInputsFromDoctor(report);
+  if (!report.passed) {
+    const failedChecks = Array.isArray(report?.checks)
+      ? report.checks.filter((check) => !check.passed)
+      : [];
+    const allFailuresAreMissingInputs =
+      failedChecks.length > 0 &&
+      failedChecks.every((check) =>
+        /^missing required input: .+$/.test(check.error ?? ""),
+      );
+    if (allFailuresAreMissingInputs) {
+      return {
+        status: "blocked_missing_inputs",
+        reason: "setup-doctor required inputs are missing",
+        missing_inputs: missingInputs,
+        report,
+      };
+    }
+    return {
+      status: "failed",
+      reason: "setup-doctor connectivity preflight failed",
+      missing_inputs: [],
+      report,
+    };
+  }
+  return {
+    status: "passed",
+    reason: null,
+    missing_inputs: [],
+    report,
+  };
+};
+
+const attemptFailureContext = ({ attempt, error, setupCheck, stage }) => ({
+  attempt,
+  stage,
+  error:
+    error === undefined
+      ? null
+      : error instanceof Error
+        ? error.message
+        : String(error),
+  failed_checks: failedChecks(setupCheck),
+});
+
+export const runSetupAgent = async ({
+  env = process.env,
+  flags = new Map(),
+  lifecycleApplier = applyLifecyclePlan,
+  lifecyclePlanner = planLifecycleInsertionsStrict,
+  repoRoot = ".",
+  setupChecker = runSetupCheck,
+  setupDoctor = runSetupDoctor,
+}) => {
+  const resolvedRepoRoot = resolve(repoRoot ?? ".");
+  const manifestPath = String(
+    flags.get("manifest") || DEFAULT_SETUP_MANIFEST_PATH,
+  );
+  let manifest;
+  try {
+    manifest = await requireManifest({
+      manifestPath,
+      repoRoot: resolvedRepoRoot,
+    });
+  } catch (error) {
+    if (error?.code === "CLUE_SETUP_MANIFEST_MISSING") {
+      return {
+        status: "blocked",
+        code: "CLUE_SETUP_MANIFEST_MISSING",
+        manifest_path: manifestPath,
+        attempts: [],
+        setup_check: null,
+        setup_doctor: {
+          status: "skipped",
+          reason: "setup manifest is missing",
+          missing_inputs: [],
+          report: null,
+        },
+        blockers: [
+          {
+            reason: error.message,
+            evidence: manifestPath,
+          },
+        ],
+        user_verification: {
+          setup_watch_owner: "user",
+          setup_watch_auto_run: false,
+          status: "not_reached",
+          required_command: "npx -y @clue-ai/cli setup-watch --local",
+        },
+      };
+    }
+    throw error;
+  }
+  const target = optionalString(flags.get("target")) ?? manifest.target;
+  const mergedEnv = {
+    ...(await readEnvGuideIfPresent({ repoRoot: resolvedRepoRoot })),
+    ...env,
+  };
+  const request = buildLifecycleRequestFromManifest({ manifest, target });
+  const allowedWritePaths = await allowedWritePathsFromRequest({
+    repoRoot: resolvedRepoRoot,
+    request,
+  });
+  const maxAttempts = normalizePositiveInteger(
+    flags.get("max-attempts"),
+    DEFAULT_MAX_ATTEMPTS,
+  );
+  const aiEnv = aiProviderEnvFromFlags({ env: mergedEnv, flags });
+  const missingAiInputs = missingSetupAgentAiEnvNames(aiEnv);
+  if (missingAiInputs.length > 0) {
+    return blockedMissingAiProviderConfig({
+      manifestPath,
+      missingInputs: missingAiInputs,
+    });
+  }
+  const attempts = [];
+  let failureContext = null;
+  let lastSetupCheck = null;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    try {
+      const plan = await lifecyclePlanner({
+        repoRoot: resolvedRepoRoot,
+        request,
+        env: aiEnv,
+        failureContext,
+      });
+      const lifecycleResult = await lifecycleApplier({
+        repoRoot: resolvedRepoRoot,
+        plan,
+        allowedWritePaths,
+      });
+      const setupCheck = await runStaticSetupCheck({
+        manifest,
+        repoRoot: resolvedRepoRoot,
+        request,
+        setupChecker,
+        target,
+      });
+      lastSetupCheck = setupCheck;
+      attempts.push({
+        attempt,
+        lifecycle_insertions: lifecycleResult.lifecycleInsertions,
+        warnings: lifecycleResult.warnings,
+        setup_check_passed: setupCheck.passed,
+        failed_checks: failedChecks(setupCheck),
+      });
+      if (setupCheck.passed) {
+        const setupDoctorResult = await runOptionalSetupDoctor({
+          env: mergedEnv,
+          flags,
+          repoRoot: resolvedRepoRoot,
+          setupDoctor,
+        });
+        return {
+          status:
+            setupDoctorResult.status === "passed" ||
+            setupDoctorResult.status === "skipped"
+              ? "user_verification_pending"
+              : "blocked",
+          manifest_path: manifestPath,
+          attempts,
+          setup_check: setupCheck,
+          setup_doctor: setupDoctorResult,
+          user_verification: {
+            setup_watch_owner: "user",
+            setup_watch_auto_run: false,
+            status: "user_verification_pending",
+            required_command: "npx -y @clue-ai/cli setup-watch --local",
+          },
+        };
+      }
+      failureContext = attemptFailureContext({
+        attempt,
+        setupCheck,
+        stage: "setup_check",
+      });
+    } catch (error) {
+      failureContext = attemptFailureContext({
+        attempt,
+        error,
+        stage: "lifecycle_apply_or_plan",
+      });
+      attempts.push({
+        attempt,
+        setup_check_passed: false,
+        error: failureContext.error,
+        failed_checks: [],
+      });
+    }
+  }
+
+  return {
+    status: "blocked",
+    manifest_path: manifestPath,
+    attempts,
+    setup_check: lastSetupCheck,
+    setup_doctor: {
+      status: "skipped",
+      reason: "setup-check did not pass",
+      missing_inputs: [],
+      report: null,
+    },
+    blockers: [
+      {
+        reason: "setup-agent retry budget exhausted",
+        evidence: failureContext,
+      },
+    ],
+    user_verification: {
+      setup_watch_owner: "user",
+      setup_watch_auto_run: false,
+      status: "not_reached",
+      required_command: "npx -y @clue-ai/cli setup-watch --local",
+    },
+  };
+};

package/src/setup-ai-contract.mjs

@@ -1,5 +1,5 @@
 export const AI_SETUP_CONTRACT_VERSION =
-  "2026-05-10.frontend-adapter-contract.v8";
+  "2026-05-10.latest-sdk-contract.v9";
 
 export const SETUP_DOCTRINE = {
   purpose:
@@ -26,6 +26,7 @@ export const DETERMINISTIC_CONTROL_MODEL = {
   ],
   cli_should_control: [
     "official SDK package names",
+    "latest-channel Clue SDK dependency declarations so setup agents cannot pin stale SDK versions",
     "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",