@clue-ai/cli 0.0.22 → 0.0.24

package/src/setup-agent.mjs

@@ -1,4 +1,4 @@
-import { access, readFile } from "node:fs/promises";
+import { access, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import {
   applyLifecyclePlan,
@@ -28,6 +28,8 @@ const DEPENDENCY_WRITE_FILE_CANDIDATES = [
   "Pipfile.lock",
   "poetry.lock",
 ];
+const FRONTEND_SDK_PACKAGE = "@clue-ai/browser-sdk";
+const BACKEND_FASTAPI_SDK_PACKAGE = "clue-fastapi-sdk";
 
 const optionalString = (value) =>
   typeof value === "string" && value.trim() ? value.trim() : null;
@@ -100,6 +102,13 @@ const blockedMissingAiProviderConfig = ({ manifestPath, missingInputs }) => ({
     missing_inputs: missingInputs,
     report: null,
   },
+  quality_gates: buildQualityGates({
+    aiConfigPresent: false,
+    setupDoctorResult: {
+      status: "skipped",
+      reason: "AI provider configuration is missing",
+    },
+  }),
   blockers: [
     {
       reason:
@@ -187,6 +196,143 @@ const discoveredDependencyWritePaths = async ({ repoRoot, sourcePaths }) => {
   return discovered;
 };
 
+const writeJson = async ({ path, value }) => {
+  await writeFile(path, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+};
+
+const ensureFrontendSdkDependency = async ({ repoRoot, rootPath }) => {
+  const packageJsonPath = resolve(repoRoot, rootPath, "package.json");
+  if (!(await exists(packageJsonPath))) return null;
+  const packageJson = await readJson(packageJsonPath);
+  const dependencies =
+    packageJson.dependencies && typeof packageJson.dependencies === "object"
+      ? packageJson.dependencies
+      : {};
+  if (dependencies[FRONTEND_SDK_PACKAGE] === "latest") return null;
+  packageJson.dependencies = {
+    ...dependencies,
+    [FRONTEND_SDK_PACKAGE]: "latest",
+  };
+  await writeJson({ path: packageJsonPath, value: packageJson });
+  return {
+    file_path: join(rootPath, "package.json"),
+    dependency: FRONTEND_SDK_PACKAGE,
+    version: "latest",
+  };
+};
+
+const ensureRequirementsDependency = async ({ repoRoot, path }) => {
+  const absolutePath = resolve(repoRoot, path);
+  if (!(await exists(absolutePath))) return null;
+  const text = await readFile(absolutePath, "utf8");
+  const rawLines = text.split(/\r?\n/);
+  while (rawLines.at(-1) === "") rawLines.pop();
+  const lines = rawLines.filter(
+    (line) => !new RegExp(`^\\s*${BACKEND_FASTAPI_SDK_PACKAGE}\\b`).test(line),
+  );
+  if (!lines.some((line) => line.trim() === BACKEND_FASTAPI_SDK_PACKAGE)) {
+    lines.push(BACKEND_FASTAPI_SDK_PACKAGE);
+  }
+  const next = `${lines.join("\n")}\n`;
+  if (next === text) return null;
+  await writeFile(absolutePath, next, "utf8");
+  return {
+    file_path: path,
+    dependency: BACKEND_FASTAPI_SDK_PACKAGE,
+    version: "latest",
+  };
+};
+
+const ensureSdkDependencies = async ({ repoRoot, manifest, request }) => {
+  const writes = [];
+  const watchTargets = Array.isArray(
+    manifest.lifecycle_verification?.watch_targets,
+  )
+    ? manifest.lifecycle_verification.watch_targets
+    : [];
+  for (const target of watchTargets) {
+    if (target?.kind !== "frontend" || !optionalString(target.root_path)) {
+      continue;
+    }
+    const write = await ensureFrontendSdkDependency({
+      repoRoot,
+      rootPath: target.root_path,
+    });
+    if (write) writes.push(write);
+  }
+  if (request.framework === "fastapi") {
+    const dependencyPaths = await discoveredDependencyWritePaths({
+      repoRoot,
+      sourcePaths: [request.backend_root_path],
+    });
+    const requirementsPath = dependencyPaths.find((path) =>
+      path.endsWith("requirements.txt"),
+    );
+    if (requirementsPath) {
+      const write = await ensureRequirementsDependency({
+        repoRoot,
+        path: requirementsPath,
+      });
+      if (write) writes.push(write);
+    }
+  }
+  return writes;
+};
+
+const planTouchedPaths = (plan) => [
+  ...new Set(
+    [
+      ...(Array.isArray(plan?.edits)
+        ? plan.edits.map((edit) => edit?.file_path)
+        : []),
+      ...(Array.isArray(plan?.file_creations)
+        ? plan.file_creations.map((fileCreation) => fileCreation?.file_path)
+        : []),
+      ...(Array.isArray(plan?.insertions)
+        ? plan.insertions.map((insertion) => insertion?.file_path)
+        : []),
+      ...(Array.isArray(plan?.lifecycle_insertions)
+        ? plan.lifecycle_insertions.map((insertion) => insertion?.file_path)
+        : []),
+    ]
+      .map(optionalString)
+      .filter(Boolean),
+  ),
+];
+
+const snapshotPlanTouchedFiles = async ({ repoRoot, plan }) => {
+  const snapshot = new Map();
+  for (const filePath of planTouchedPaths(plan)) {
+    const absolutePath = resolve(repoRoot, filePath);
+    try {
+      snapshot.set(filePath, {
+        absolutePath,
+        existed: true,
+        text: await readFile(absolutePath, "utf8"),
+      });
+    } catch (error) {
+      if (error?.code !== "ENOENT") throw error;
+      snapshot.set(filePath, {
+        absolutePath,
+        existed: false,
+        text: null,
+      });
+    }
+  }
+  return snapshot;
+};
+
+const restorePlanTouchedFiles = async (snapshot) => {
+  for (const entry of snapshot.values()) {
+    if (entry.existed) {
+      await mkdir(dirname(entry.absolutePath), { recursive: true });
+      await writeFile(entry.absolutePath, entry.text, "utf8");
+    } else {
+      await rm(entry.absolutePath, { force: true });
+    }
+  }
+};
+
 const allowedWritePathsFromRequest = async ({ repoRoot, request }) => [
   ...new Set([
     ...request.allowed_source_paths,
@@ -274,6 +420,55 @@ const missingInputsFromDoctor = (report) => [
   ),
 ];
 
+const buildQualityGates = ({
+  aiConfigPresent,
+  dependencyWrites = [],
+  lifecyclePlanApplied = false,
+  setupCheck = null,
+  setupDoctorResult = null,
+}) => [
+  {
+    id: "ai_provider_config_present",
+    passed: Boolean(aiConfigPresent),
+    evidence: REQUIRED_SETUP_AGENT_AI_ENV_NAMES,
+  },
+  {
+    id: "sdk_dependencies_cli_owned",
+    passed: true,
+    evidence: {
+      dependency_writes: dependencyWrites,
+      note:
+        "setup-agent owns Clue SDK dependency declarations before AI planning",
+    },
+  },
+  {
+    id: "lifecycle_plan_cli_applied",
+    passed: Boolean(lifecyclePlanApplied),
+    evidence:
+      "AI returns a structured plan only; setup-agent validates and applies edits",
+  },
+  {
+    id: "static_setup_check_passed",
+    passed: Boolean(setupCheck?.passed),
+    evidence: "setup-check --require-sdk-lifecycle",
+  },
+  {
+    id: "setup_doctor_preflight",
+    passed: setupDoctorResult?.status === "passed",
+    skipped: setupDoctorResult?.status === "skipped",
+    evidence:
+      setupDoctorResult?.status === "passed"
+        ? "setup-doctor --local passed"
+        : setupDoctorResult?.reason ?? "setup-doctor --local did not pass",
+  },
+  {
+    id: "setup_watch_user_owned",
+    passed: true,
+    evidence:
+      "setup-watch remains user-operated lifecycle and event-delivery verification",
+  },
+];
+
 const runOptionalSetupDoctor = async ({ env, flags, repoRoot, setupDoctor }) => {
   if (flags.has("skip-setup-doctor")) {
     return {
@@ -296,7 +491,7 @@ const runOptionalSetupDoctor = async ({ env, flags, repoRoot, setupDoctor }) =>
       );
     if (allFailuresAreMissingInputs) {
       return {
-        status: "blocked_missing_inputs",
+        status: "skipped",
         reason: "setup-doctor required inputs are missing",
         missing_inputs: missingInputs,
         report,
@@ -430,10 +625,16 @@ export const runSetupAgent = async ({
     });
   }
   const attempts = [];
+  const dependencyWrites = await ensureSdkDependencies({
+    repoRoot: resolvedRepoRoot,
+    manifest,
+    request,
+  });
   let failureContext = null;
   let lastSetupCheck = null;
 
   for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    let planSnapshot = null;
     try {
       const plan = await lifecyclePlanner({
         repoRoot: resolvedRepoRoot,
@@ -441,6 +642,10 @@ export const runSetupAgent = async ({
         env: aiEnv,
         failureContext,
       });
+      planSnapshot = await snapshotPlanTouchedFiles({
+        repoRoot: resolvedRepoRoot,
+        plan,
+      });
       const lifecycleResult = await lifecycleApplier({
         repoRoot: resolvedRepoRoot,
         plan,
@@ -456,6 +661,9 @@ export const runSetupAgent = async ({
       lastSetupCheck = setupCheck;
       attempts.push({
         attempt,
+        dependency_writes: dependencyWrites,
+        file_creations: lifecycleResult.fileCreations ?? [],
+        insertions: lifecycleResult.insertions ?? [],
         lifecycle_insertions: lifecycleResult.lifecycleInsertions,
         warnings: lifecycleResult.warnings,
         setup_check_passed: setupCheck.passed,
@@ -470,14 +678,20 @@ export const runSetupAgent = async ({
         });
         return {
           status:
-            setupDoctorResult.status === "passed" ||
-            setupDoctorResult.status === "skipped"
+            setupDoctorResult.status !== "failed"
               ? "user_verification_pending"
               : "blocked",
           manifest_path: manifestPath,
           attempts,
           setup_check: setupCheck,
           setup_doctor: setupDoctorResult,
+          quality_gates: buildQualityGates({
+            aiConfigPresent: true,
+            dependencyWrites,
+            lifecyclePlanApplied: true,
+            setupCheck,
+            setupDoctorResult,
+          }),
           user_verification: {
             setup_watch_owner: "user",
             setup_watch_auto_run: false,
@@ -486,12 +700,16 @@ export const runSetupAgent = async ({
           },
         };
       }
+      await restorePlanTouchedFiles(planSnapshot);
       failureContext = attemptFailureContext({
         attempt,
         setupCheck,
         stage: "setup_check",
       });
     } catch (error) {
+      if (planSnapshot) {
+        await restorePlanTouchedFiles(planSnapshot);
+      }
       failureContext = attemptFailureContext({
         attempt,
         error,
@@ -499,6 +717,7 @@ export const runSetupAgent = async ({
       });
       attempts.push({
         attempt,
+        dependency_writes: dependencyWrites,
         setup_check_passed: false,
         error: failureContext.error,
         failed_checks: [],
@@ -517,6 +736,18 @@ export const runSetupAgent = async ({
       missing_inputs: [],
       report: null,
     },
+    quality_gates: buildQualityGates({
+      aiConfigPresent: true,
+      dependencyWrites,
+      lifecyclePlanApplied: attempts.some(
+        (attempt) => Array.isArray(attempt.lifecycle_insertions),
+      ),
+      setupCheck: lastSetupCheck,
+      setupDoctorResult: {
+        status: "skipped",
+        reason: "setup-check did not pass",
+      },
+    }),
     blockers: [
       {
         reason: summarizeAttemptFailure(failureContext),

package/src/setup-ai-contract.mjs

@@ -1,5 +1,5 @@
 export const AI_SETUP_CONTRACT_VERSION =
-  "2026-05-10.latest-sdk-contract.v9";
+  "2026-05-10.latest-sdk-contract.v17";
 
 export const SETUP_DOCTRINE = {
   purpose:
@@ -13,7 +13,7 @@ export const SETUP_DOCTRINE = {
   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.",
+    "For supported setup paths, prefer completing safe minimal Clue wiring and reporting unclear lifecycle points as warnings. Reserve blockers for truly unsupported frameworks, unavailable SDK contracts, missing AI configuration, or edits that cannot be applied without guessing outside Clue setup scope.",
 };
 
 export const DETERMINISTIC_CONTROL_MODEL = {
@@ -22,7 +22,7 @@ export const DETERMINISTIC_CONTROL_MODEL = {
     "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",
+    "whether a lifecycle point is unclear and should be skipped with a warning instead of guessed",
   ],
   cli_should_control: [
     "official SDK package names",
@@ -37,6 +37,39 @@ export const DETERMINISTIC_CONTROL_MODEL = {
   ],
 };
 
+export const SETUP_AGENT_QUALITY_GATES = [
+  {
+    id: "ai_provider_config_present",
+    purpose:
+      "Prevent silent setup-agent startup failure when AI provider env is missing.",
+  },
+  {
+    id: "sdk_dependencies_cli_owned",
+    purpose:
+      "Ensure official SDK package names and latest-channel declarations are controlled by CLI logic, not model guesses.",
+  },
+  {
+    id: "lifecycle_plan_cli_applied",
+    purpose:
+      "Ensure the AI only returns a structured plan and cannot directly write files or run shell commands.",
+  },
+  {
+    id: "static_setup_check_passed",
+    purpose:
+      "Reject known bad local-prompt failure modes such as wrong SDKs, stale env names, unsafe browser token wiring, awaited lifecycle calls, and partial lifecycle setup.",
+  },
+  {
+    id: "setup_doctor_preflight",
+    purpose:
+      "Separate API connectivity verification from static source verification and make skipped preflight visible.",
+  },
+  {
+    id: "setup_watch_user_owned",
+    purpose:
+      "Keep real login/logout/account event delivery verification under the user's control.",
+  },
+];
+
 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.",
@@ -55,7 +88,7 @@ export const API_CONNECTIVITY_CONTRACT = {
       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.",
+        "Clue backend validates x-clue-api-key, project, environment, service key, and origin, then returns a browser token.",
     },
     browser_ingest: {
       owner: "clue_backend",
@@ -93,15 +126,66 @@ export const FRONTEND_ADAPTER_CONTRACT = {
   ],
   browser_token_proxy_path: "/api/v1/clue/browser-tokens",
   rules: [
+    "For Next.js, prefer a module-level client singleton such as src/lib/clue.ts that calls ClueInit once after required NEXT_PUBLIC_CLUE_* values are present, then import that module from app/layout.tsx or the existing app bootstrap.",
+    "Next.js browser SDK adapter files must start with \"use client\".",
+    "Do not create a React component whose useEffect calls ClueInit. Component lifecycle hooks, page components, sidebars, login/register success callbacks, and other repeated UI paths are rejected setup locations.",
     "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.",
+    "Backend browser-token proxy calls to Clue must send CLUE_API_KEY as the x-clue-api-key header, never as Authorization bearer, query, or JSON body.",
+    "Do not introduce non-Clue HTTP client dependencies for browser-token proxy code unless they already exist in dependency files.",
   ],
 };
 
+export const OFFICIAL_SDK_CONTRACT = {
+  purpose:
+    "This bundled contract is the authoritative Clue SDK contract for setup-agent. A customer repository is expected to start without Clue SDK imports or dependencies; absence of existing Clue code is not a blocker.",
+  frontend_browser_sdk: {
+    package_name: "@clue-ai/browser-sdk",
+    dependency_specifier: "@clue-ai/browser-sdk@latest",
+    import_path: "@clue-ai/browser-sdk",
+    public_lifecycle_apis: {
+      ClueInit:
+        "ClueInit(options: { endpoint: string; projectKey: string; environment: string; serviceKey?: string; producerId?: string; browserTokenProvider?: () => string | Promise<string>; ... }): void",
+      ClueIdentify:
+        "ClueIdentify(userId: string, traits?: Record<string, string | number | boolean | null>): void",
+      ClueSetAccount:
+        "ClueSetAccount(accountId: string, traits?: Record<string, string | number | boolean | null>): void",
+      ClueLogout: "ClueLogout(): void",
+    },
+    safety_contract:
+      "Public lifecycle APIs are no-throw wrappers. Do not add custom per-call try/catch or await them.",
+  },
+  backend_fastapi_sdk: {
+    package_name: "clue-fastapi-sdk",
+    dependency_specifier: "clue-fastapi-sdk",
+    python_import:
+      "from clue_fastapi_sdk import clue_init_fastapi, ClueIdentify, ClueSetAccount, ClueLogout",
+    public_lifecycle_apis: {
+      clue_init_fastapi:
+        "clue_init_fastapi(app, *, project_key: str, environment: str, api_key: str | None = None, service_name: str = 'python-service', producer_id: str | None = None, service_key: str | None = None, ... ) -> bool",
+      ClueIdentify:
+        "ClueIdentify(user_id: str, traits: Mapping[str, object] | None = None) -> bool",
+      ClueSetAccount:
+        "ClueSetAccount(account_id: str, traits: Mapping[str, object] | None = None) -> bool",
+      ClueLogout: "ClueLogout(reason: str | None = None) -> bool",
+    },
+    safety_contract:
+      "Public lifecycle APIs catch SDK errors internally and return bool where applicable. Do not wrap each call solely for Clue failure isolation. FastAPI initialization must pass service_key so event attribution matches setup-watch service targets. Clue env reads must be non-crashing; do not use os.environ[\"CLUE_*\"] required indexing.",
+  },
+  minimal_file_creation_contract: {
+    allowed_when:
+      "No existing Clue adapter, browser-token proxy module, or client bootstrap wrapper exists in the customer repo.",
+    allowed_files:
+      "Only Clue-owned minimal SDK wiring files under existing frontend/backend source roots, plus exact replacements in existing files to import/register those files.",
+    rule:
+      "Creating a minimal Clue adapter or browser-token proxy is allowed setup wiring, not a host application refactor.",
+  },
+};
+
 export const setupDoctrineSkillLines = () => [
   `- Purpose: ${SETUP_DOCTRINE.purpose}`,
   `- Minimal diff reason: ${SETUP_DOCTRINE.minimal_diff_reason}`,
@@ -109,6 +193,7 @@ export const setupDoctrineSkillLines = () => [
   `- Static control boundary: ${SETUP_DOCTRINE.deterministic_control_boundary}`,
   `- Documentation reason: ${SETUP_DOCTRINE.documentation_reason}`,
   `- Failure posture: ${SETUP_DOCTRINE.failure_posture}`,
+  `- Official SDK contract: ${OFFICIAL_SDK_CONTRACT.purpose}`,
   `- 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.`,