@clue-ai/cli 0.0.9 → 0.0.11

package/src/lifecycle-init.mjs

@@ -1,229 +1,635 @@
 import { readFile, writeFile } from "node:fs/promises";
-import { isAbsolute, relative, resolve } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { callJsonAiProvider, resolveAiProviderConfig } from "./ai-provider.mjs";
-import { findLifecycleGuardViolations } from "./lifecycle-guard.mjs";
+import {
+  extractExecutableModuleStatements,
+  findLifecycleCallApiNames,
+  findLifecycleGuardViolations,
+  stripSourceNoise,
+} from "./lifecycle-guard.mjs";
 import { listAllowedSourceFiles } from "./path-policy.mjs";
 
 const API_NAMES = new Set([
-	"ClueInit",
-	"ClueIdentify",
-	"ClueSetAccount",
-	"ClueLogout",
+  "ClueInit",
+  "ClueIdentify",
+  "ClueSetAccount",
+  "ClueLogout",
 ]);
 
 const SOURCE_EXTENSIONS = [".py", ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"];
 const MAX_CONTEXT_FILES = 180;
 const MAX_FILE_CHARS = 12_000;
 const MAX_TOTAL_CHARS = 360_000;
+const FRONTEND_SDK_PACKAGE = "@clue-ai/browser-sdk";
+const WRONG_FRONTEND_SDK_PACKAGES = ["clue-js-sdk", "@clue/browser-sdk"];
+const CLUE_SETUP_ADDITION_PATTERN =
+  /\b(?:ClueInit|ClueIdentify|ClueSetAccount|ClueLogout|clue_init_fastapi|clue_init_django|clue-fastapi-sdk|clue-django-sdk|CLUE_[A-Z0-9_]+|browserTokenProvider|clue[-_])|@clue-ai\/browser-sdk/i;
 
 const nonEmpty = (value, field) => {
-	if (typeof value !== "string" || value.trim() === "") {
-		throw new Error(`${field} is required`);
-	}
-	return value.trim();
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error(`${field} is required`);
+  }
+  return value.trim();
 };
 
 const safeRelativePath = (repoRoot, filePath) => {
-	const root = resolve(repoRoot);
-	const absolutePath = resolve(root, filePath);
-	const relativePath = relative(root, absolutePath);
-	if (relativePath.startsWith("..") || isAbsolute(relativePath)) {
-		throw new Error(`edit path escapes repo root: ${filePath}`);
-	}
-	return { absolutePath, relativePath };
+  const root = resolve(repoRoot);
+  const absolutePath = resolve(root, filePath);
+  const relativePath = relative(root, absolutePath);
+  if (relativePath.startsWith("..") || isAbsolute(relativePath)) {
+    throw new Error(`edit path escapes repo root: ${filePath}`);
+  }
+  return { absolutePath, relativePath };
 };
 
 const assertApiName = (apiName) => {
-	if (!API_NAMES.has(apiName)) {
-		throw new Error(`unsupported lifecycle API: ${apiName}`);
-	}
-	return apiName;
+  if (!API_NAMES.has(apiName)) {
+    throw new Error(`unsupported lifecycle API: ${apiName}`);
+  }
+  return apiName;
 };
 
 const assertNoForbiddenInstrumentation = (replacement) => {
-	if (replacement.includes("ClueTrack")) {
-		throw new Error("init tool must not add broad ClueTrack instrumentation");
-	}
-	if (/data-clue-(id|key)/i.test(replacement)) {
-		throw new Error("init tool must not add data-clue-id or data-clue-key");
-	}
+  if (replacement.includes("ClueTrack")) {
+    throw new Error("init tool must not add broad ClueTrack instrumentation");
+  }
+  if (/data-clue-(id|key)/i.test(replacement)) {
+    throw new Error("init tool must not add data-clue-id or data-clue-key");
+  }
+  const wrongSdkPackage = WRONG_FRONTEND_SDK_PACKAGES.find((packageName) =>
+    replacement.includes(packageName),
+  );
+  if (wrongSdkPackage) {
+    throw new Error(
+      `init tool must not use wrong frontend SDK package: ${wrongSdkPackage}`,
+    );
+  }
 };
 
-const assertLifecycleCallsAreGuarded = (replacement) => {
-	const violations = findLifecycleGuardViolations(replacement);
-	if (violations.length > 0) {
-		throw new Error(
-			`Clue lifecycle calls must be failure-isolated with try/catch, try/except, or an explicit safe Clue helper: ${JSON.stringify(violations)}`,
-		);
-	}
+const assertLifecycleCallsAreNonBlocking = (replacement) => {
+  const violations = findLifecycleGuardViolations(replacement);
+  if (violations.length > 0) {
+    throw new Error(
+      `Clue lifecycle calls must not be awaited or block host service behavior: ${JSON.stringify(violations)}`,
+    );
+  }
+};
+
+const assertClueSetupOnlyEdit = (edit) => {
+  if (!edit.replace.includes(edit.find)) {
+    throw new Error(
+      `Clue lifecycle edits must be additive and preserve existing source in ${edit.file_path}`,
+    );
+  }
+  const addedText = edit.replace.split(edit.find).join("");
+  if (!CLUE_SETUP_ADDITION_PATTERN.test(addedText)) {
+    throw new Error(
+      `Clue lifecycle edits must add only Clue setup related code in ${edit.file_path}`,
+    );
+  }
 };
 
 const normalizeLifecycleInsertion = (input) => ({
-	api_name: assertApiName(nonEmpty(input.api_name, "api_name")),
-	file_path: nonEmpty(input.file_path, "file_path"),
-	confidence: Math.max(0, Math.min(1, Number(input.confidence ?? 0))),
-	reason: nonEmpty(input.reason, "reason"),
+  api_name: assertApiName(nonEmpty(input.api_name, "api_name")),
+  file_path: nonEmpty(input.file_path, "file_path"),
+  confidence: Math.max(0, Math.min(1, Number(input.confidence ?? 0))),
+  reason: nonEmpty(input.reason, "reason"),
 });
 
+const normalizeBlocker = (input) => {
+  if (typeof input === "string") {
+    return { reason: nonEmpty(input, "blocker.reason") };
+  }
+  if (!input || typeof input !== "object") {
+    throw new Error("blocker must be a string or object");
+  }
+  const blocker = {
+    reason: nonEmpty(input.reason, "blocker.reason"),
+  };
+  if (typeof input.evidence === "string" && input.evidence.trim()) {
+    blocker.evidence = input.evidence.trim();
+  }
+  return blocker;
+};
+
 const normalizePlan = (input) => {
-	if (!input || typeof input !== "object") {
-		throw new Error("AI lifecycle plan must be an object");
-	}
-	if (!Array.isArray(input.edits)) {
-		throw new Error("AI lifecycle plan must include edits");
-	}
-	const edits = input.edits.map((edit) => ({
-		file_path: nonEmpty(edit.file_path, "edit.file_path"),
-		find: nonEmpty(edit.find, "edit.find"),
-		replace: nonEmpty(edit.replace, "edit.replace"),
-	}));
-	const lifecycleInsertions = Array.isArray(input.lifecycle_insertions)
-		? input.lifecycle_insertions.map(normalizeLifecycleInsertion)
-		: [];
-	return {
-		edits,
-		lifecycleInsertions,
-		warnings: Array.isArray(input.warnings)
-			? input.warnings
-					.filter((warning) => typeof warning === "string" && warning.trim())
-					.map((warning) => warning.trim())
-			: [],
-	};
+  if (!input || typeof input !== "object") {
+    throw new Error("AI lifecycle plan must be an object");
+  }
+  if (
+    input.status !== undefined &&
+    input.status !== "ready" &&
+    input.status !== "blocked"
+  ) {
+    throw new Error("AI lifecycle plan status must be ready or blocked");
+  }
+  const status = input.status === "blocked" ? "blocked" : "ready";
+  if (!Array.isArray(input.edits)) {
+    throw new Error("AI lifecycle plan must include edits");
+  }
+  const edits = input.edits.map((edit) => ({
+    file_path: nonEmpty(edit.file_path, "edit.file_path"),
+    find: nonEmpty(edit.find, "edit.find"),
+    replace: nonEmpty(edit.replace, "edit.replace"),
+  }));
+  const lifecycleInsertions = Array.isArray(input.lifecycle_insertions)
+    ? input.lifecycle_insertions.map(normalizeLifecycleInsertion)
+    : [];
+  const blockers = Array.isArray(input.blockers)
+    ? input.blockers.map(normalizeBlocker)
+    : [];
+  if (status === "blocked") {
+    if (edits.length > 0 || lifecycleInsertions.length > 0) {
+      throw new Error("blocked lifecycle plan must not include edits");
+    }
+    if (blockers.length === 0) {
+      throw new Error("blocked lifecycle plan must include blockers");
+    }
+  }
+  if (status === "ready" && blockers.length > 0) {
+    throw new Error("ready lifecycle plan must not include blockers");
+  }
+  return {
+    status,
+    edits,
+    lifecycleInsertions,
+    blockers,
+    warnings: Array.isArray(input.warnings)
+      ? input.warnings
+          .filter((warning) => typeof warning === "string" && warning.trim())
+          .map((warning) => warning.trim())
+      : [],
+  };
+};
+
+const escapeRegex = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+const sourceImportsFrontendSdk = (text) =>
+  extractExecutableModuleStatements(text).some((statement) =>
+    new RegExp(
+      `(?:from\\s*["']${escapeRegex(FRONTEND_SDK_PACKAGE)}["']|import\\s*["']${escapeRegex(FRONTEND_SDK_PACKAGE)}["'])`,
+    ).test(statement),
+  );
+
+const parseNamedSpecifiers = (specifiers) =>
+  specifiers
+    .split(",")
+    .map((specifier) => specifier.trim())
+    .filter(Boolean)
+    .map((specifier) => {
+      const match = /^([A-Za-z_$][\w$]*)(?:\s+as\s+([A-Za-z_$][\w$]*))?$/.exec(
+        specifier,
+      );
+      if (!match) return null;
+      return {
+        imported: match[1],
+        local: match[2] ?? match[1],
+        exported: match[2] ?? match[1],
+      };
+    })
+    .filter(Boolean);
+
+const sourceDirectlyProvidesApiFromFrontendSdk = (text, apiName) => {
+  const statements = extractExecutableModuleStatements(text).join("\n");
+  for (const match of statements.matchAll(
+    /import\s*{([^}]+)}\s*from\s*["']([^"']+)["']/g,
+  )) {
+    if (match[2] !== FRONTEND_SDK_PACKAGE) continue;
+    if (
+      parseNamedSpecifiers(match[1]).some(
+        (specifier) =>
+          specifier.imported === apiName && specifier.local === apiName,
+      )
+    ) {
+      return true;
+    }
+  }
+  for (const match of statements.matchAll(
+    /export\s*{([^}]+)}\s*from\s*["']([^"']+)["']/g,
+  )) {
+    if (match[2] !== FRONTEND_SDK_PACKAGE) continue;
+    if (
+      parseNamedSpecifiers(match[1]).some(
+        (specifier) =>
+          specifier.imported === apiName && specifier.exported === apiName,
+      )
+    ) {
+      return true;
+    }
+  }
+  return false;
+};
+
+const frontendSdkImportedLocalsForApi = (text, apiName) => {
+  const locals = [];
+  for (const match of extractExecutableModuleStatements(text)
+    .join("\n")
+    .matchAll(/import\s*{([^}]+)}\s*from\s*["']([^"']+)["']/g)) {
+    if (match[2] !== FRONTEND_SDK_PACKAGE) continue;
+    for (const specifier of parseNamedSpecifiers(match[1])) {
+      if (specifier.imported === apiName) {
+        locals.push(specifier.local);
+      }
+    }
+  }
+  return locals;
+};
+
+const frontendSdkNamespaces = (text) =>
+  [
+    ...extractExecutableModuleStatements(text)
+      .join("\n")
+      .matchAll(
+        /import\s*\*\s*as\s*([A-Za-z_$][\w$]*)\s*from\s*["']([^"']+)["']/g,
+      ),
+  ]
+    .filter((match) => match[2] === FRONTEND_SDK_PACKAGE)
+    .map((match) => match[1]);
+
+const sourceExportsLocalAsApi = (text, localName, apiName) => {
+  const statements = extractExecutableModuleStatements(text).join("\n");
+  for (const match of statements.matchAll(
+    /export\s*{([^}]+)}(?:\s*from\s*["'][^"']+["'])?/g,
+  )) {
+    if (match[0].includes(" from ")) continue;
+    if (
+      parseNamedSpecifiers(match[1]).some(
+        (specifier) =>
+          specifier.imported === localName && specifier.exported === apiName,
+      )
+    ) {
+      return true;
+    }
+  }
+  return new RegExp(
+    `export\\s+const\\s+${escapeRegex(apiName)}\\s*=\\s*${escapeRegex(localName)}\\b`,
+  ).test(statements);
+};
+
+const sourceForwardsFrontendSdkApi = (source, apiName) => {
+  const text = source.text;
+  if (sourceDirectlyProvidesApiFromFrontendSdk(text, apiName)) return true;
+  const importedLocals = frontendSdkImportedLocalsForApi(text, apiName);
+  if (
+    importedLocals.some((localName) =>
+      sourceExportsLocalAsApi(text, localName, apiName),
+    )
+  ) {
+    return true;
+  }
+  return frontendSdkNamespaces(text).some((namespaceName) =>
+    new RegExp(
+      `export\\s+const\\s+${escapeRegex(apiName)}\\s*=\\s*${escapeRegex(namespaceName)}\\.${escapeRegex(apiName)}\\b`,
+    ).test(text),
+  );
+};
+
+const localImportSpecifiersForApi = (text, apiName) =>
+  [
+    ...extractExecutableModuleStatements(text)
+      .join("\n")
+      .matchAll(/import\s*{([^}]+)}\s*from\s*["']([^"']+)["']/g),
+  ]
+    .filter((match) => match[2].startsWith(".") || match[2].startsWith("@/"))
+    .flatMap((match) =>
+      parseNamedSpecifiers(match[1])
+        .filter(
+          (specifier) =>
+            specifier.imported === apiName && specifier.local === apiName,
+        )
+        .map(() => match[2]),
+    );
+
+const importSpecifiers = (text) =>
+  [
+    ...extractExecutableModuleStatements(text)
+      .join("\n")
+      .matchAll(/import\s+(?:[\s\S]*?\s+from\s+)?["']([^"']+)["']/g),
+  ]
+    .map((match) => match[1] ?? match[2])
+    .filter(Boolean);
+
+const candidateSourcePaths = (basePath) => [
+  basePath,
+  ...SOURCE_EXTENSIONS.map((extension) => `${basePath}${extension}`),
+  ...SOURCE_EXTENSIONS.map((extension) => join(basePath, `index${extension}`)),
+];
+
+const localImportCandidatePaths = ({ importerPath, specifier }) => {
+  const candidates = [];
+  if (specifier.startsWith(".")) {
+    candidates.push(
+      ...candidateSourcePaths(join(dirname(importerPath), specifier)),
+    );
+  }
+  if (specifier.startsWith("@/")) {
+    const srcIndex = importerPath.lastIndexOf("/src/");
+    if (srcIndex >= 0) {
+      candidates.push(
+        ...candidateSourcePaths(
+          join(
+            importerPath.slice(0, srcIndex + "/src".length),
+            specifier.slice(2),
+          ),
+        ),
+      );
+    }
+    for (const root of [
+      "src",
+      "frontend/src",
+      "apps/web/src",
+      "apps/admin/src",
+      "apps/visitor/src",
+    ]) {
+      candidates.push(...candidateSourcePaths(join(root, specifier.slice(2))));
+    }
+  }
+  return candidates;
+};
+
+const resolveLocalSource = ({ importerPath, sourceByPath, specifier }) => {
+  const candidates = localImportCandidatePaths({ importerPath, specifier });
+  return candidates
+    .map((candidate) => sourceByPath.get(candidate))
+    .find(Boolean);
+};
+
+const fileLooksFrontend = (filePath) =>
+  /\.(?:ts|tsx|js|jsx|mjs|cjs)$/.test(filePath);
+
+const hasVerifiedFrontendSdkAccess = ({ apiName, source, sourceByPath }) => {
+  if (sourceDirectlyProvidesApiFromFrontendSdk(source.text, apiName))
+    return true;
+  return localImportSpecifiersForApi(source.text, apiName).some((specifier) => {
+    const importedSource = resolveLocalSource({
+      importerPath: source.file_path,
+      sourceByPath,
+      specifier,
+    });
+    return importedSource
+      ? sourceForwardsFrontendSdkApi(importedSource, apiName)
+      : false;
+  });
+};
+
+const assertLifecycleInsertionEvidence = async ({
+  insertion,
+  source,
+  sourceByPath,
+}) => {
+  const executableSource = stripSourceNoise(source.text, {
+    stripStrings: true,
+  });
+  if (
+    !findLifecycleCallApiNames(executableSource).includes(insertion.api_name)
+  ) {
+    throw new Error(
+      `lifecycle insertion evidence missing ${insertion.api_name} call in ${insertion.file_path}`,
+    );
+  }
+  const blocking = findLifecycleGuardViolations(executableSource).filter(
+    (violation) => violation.api_name === insertion.api_name,
+  );
+  if (blocking.length > 0) {
+    throw new Error(
+      `lifecycle insertion evidence contains blocking ${insertion.api_name} call in ${insertion.file_path}`,
+    );
+  }
+  if (
+    fileLooksFrontend(insertion.file_path) &&
+    !hasVerifiedFrontendSdkAccess({
+      apiName: insertion.api_name,
+      source,
+      sourceByPath,
+    })
+  ) {
+    throw new Error(
+      `lifecycle insertion evidence for ${insertion.api_name} in ${insertion.file_path} does not resolve to ${FRONTEND_SDK_PACKAGE}`,
+    );
+  }
+};
+
+const loadSourceIntoMap = async ({ repoRoot, sourceByPath, filePath }) => {
+  if (sourceByPath.has(filePath)) return;
+  const { absolutePath, relativePath } = safeRelativePath(repoRoot, filePath);
+  sourceByPath.set(relativePath, {
+    file_path: relativePath,
+    text: await readFile(absolutePath, "utf8"),
+  });
+};
+
+const buildLifecycleEvidenceSourceMap = async ({
+  repoRoot,
+  plan,
+  sourceByPath = new Map(),
+}) => {
+  for (const filePath of [
+    ...new Set([
+      ...plan.edits.map((edit) => edit.file_path),
+      ...plan.lifecycleInsertions.map((insertion) => insertion.file_path),
+    ]),
+  ]) {
+    await loadSourceIntoMap({ repoRoot, sourceByPath, filePath });
+  }
+  for (const source of [...sourceByPath.values()]) {
+    for (const specifier of importSpecifiers(source.text)) {
+      for (const candidate of localImportCandidatePaths({
+        importerPath: source.file_path,
+        specifier,
+      })) {
+        try {
+          await loadSourceIntoMap({
+            repoRoot,
+            sourceByPath,
+            filePath: candidate,
+          });
+          break;
+        } catch (error) {
+          if (error?.code !== "ENOENT") throw error;
+        }
+      }
+    }
+  }
+  return sourceByPath;
 };
 
 export const applyLifecyclePlan = async ({ repoRoot, plan: rawPlan }) => {
-	const plan = normalizePlan(rawPlan);
-	for (const edit of plan.edits) {
-		const { absolutePath } = safeRelativePath(repoRoot, edit.file_path);
-		assertNoForbiddenInstrumentation(edit.replace);
-		const current = await readFile(absolutePath, "utf8");
-		const occurrences = current.split(edit.find).length - 1;
-		if (occurrences !== 1) {
-			throw new Error(
-				`edit.find must match exactly once in ${edit.file_path}; matched ${occurrences}`,
-			);
-		}
-		assertLifecycleCallsAreGuarded(edit.replace);
-		await writeFile(
-			absolutePath,
-			current.replace(edit.find, edit.replace),
-			"utf8",
-		);
-	}
-	return {
-		lifecycleInsertions: plan.lifecycleInsertions,
-		warnings: plan.warnings,
-	};
+  const plan = normalizePlan(rawPlan);
+  if (plan.status === "blocked") {
+    throw new Error(
+      `AI lifecycle plan blocked: ${plan.blockers
+        .map((blocker) =>
+          blocker.evidence
+            ? `${blocker.reason} (${blocker.evidence})`
+            : blocker.reason,
+        )
+        .join("; ")}`,
+    );
+  }
+  const sourceByPath = new Map();
+  const pendingWrites = new Map();
+  for (const edit of plan.edits) {
+    const { absolutePath, relativePath } = safeRelativePath(
+      repoRoot,
+      edit.file_path,
+    );
+    assertNoForbiddenInstrumentation(edit.replace);
+    const current =
+      sourceByPath.get(relativePath)?.text ??
+      (await readFile(absolutePath, "utf8"));
+    const occurrences = current.split(edit.find).length - 1;
+    if (occurrences !== 1) {
+      throw new Error(
+        `edit.find must match exactly once in ${edit.file_path}; matched ${occurrences}`,
+      );
+    }
+    assertClueSetupOnlyEdit(edit);
+    assertLifecycleCallsAreNonBlocking(edit.replace);
+    const next = current.replace(edit.find, edit.replace);
+    sourceByPath.set(relativePath, {
+      file_path: relativePath,
+      text: next,
+    });
+    pendingWrites.set(relativePath, { absolutePath, text: next });
+  }
+  await buildLifecycleEvidenceSourceMap({ repoRoot, plan, sourceByPath });
+  for (const insertion of plan.lifecycleInsertions) {
+    const source = sourceByPath.get(insertion.file_path);
+    if (!source) {
+      throw new Error(
+        `lifecycle insertion evidence file missing: ${insertion.file_path}`,
+      );
+    }
+    await assertLifecycleInsertionEvidence({
+      insertion,
+      source,
+      sourceByPath,
+    });
+  }
+  for (const write of pendingWrites.values()) {
+    await writeFile(write.absolutePath, write.text, "utf8");
+  }
+  return {
+    lifecycleInsertions: plan.lifecycleInsertions,
+    warnings: plan.warnings,
+  };
 };
 
 const readContextFiles = async ({ repoRoot, request }) => {
-	const files = await listAllowedSourceFiles({
-		repoRoot,
-		allowedSourcePaths: request.allowed_source_paths,
-		excludedSourcePaths: request.excluded_source_paths,
-		extensions: SOURCE_EXTENSIONS,
-	});
-	const context = [];
-	let totalChars = 0;
-	for (const absolutePath of files.slice(0, MAX_CONTEXT_FILES)) {
-		const text = await readFile(absolutePath, "utf8");
-		const snippet = text.slice(0, MAX_FILE_CHARS);
-		totalChars += snippet.length;
-		if (totalChars > MAX_TOTAL_CHARS) {
-			break;
-		}
-		context.push({
-			file_path: relative(resolve(repoRoot), absolutePath),
-			source: snippet,
-			truncated: text.length > snippet.length,
-		});
-	}
-	return context;
+  const files = await listAllowedSourceFiles({
+    repoRoot,
+    allowedSourcePaths: request.allowed_source_paths,
+    excludedSourcePaths: request.excluded_source_paths,
+    extensions: SOURCE_EXTENSIONS,
+  });
+  const context = [];
+  let totalChars = 0;
+  for (const absolutePath of files.slice(0, MAX_CONTEXT_FILES)) {
+    const text = await readFile(absolutePath, "utf8");
+    const snippet = text.slice(0, MAX_FILE_CHARS);
+    totalChars += snippet.length;
+    if (totalChars > MAX_TOTAL_CHARS) {
+      break;
+    }
+    context.push({
+      file_path: relative(resolve(repoRoot), absolutePath),
+      source: snippet,
+      truncated: text.length > snippet.length,
+    });
+  }
+  return context;
 };
 
 const buildLifecyclePrompt = ({ request, files }) =>
-	JSON.stringify({
-		task: "Add Clue SDK lifecycle API calls to this repository using exact text replacements.",
-		rules: [
-			"Return JSON only.",
-			"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.",
-			"Every Clue lifecycle call must be failure-isolated. If Clue fails, the host service must continue without throwing, rejecting, or blocking login/API behavior.",
-			"Use a small safe Clue helper, local try/catch/try/except wrapper, or direct .catch handler around Clue lifecycle calls.",
-			"Never await a Clue lifecycle call in a way that can block login, logout, account selection, request handling, page rendering, or API responses.",
-			"Find all clear login success paths and add ClueIdentify to every one of them. Do not stop after the first login flow.",
-			"Find all clear account, workspace, organization, or tenant resolution paths and add ClueSetAccount to every one of them.",
-			"Find all clear logout or session reset paths and add ClueLogout to every one of them.",
-			"Inspect backend lifecycle points as carefully as frontend lifecycle points. Backend login/session/account code is especially important.",
-			"For FastAPI backends, add the clue-fastapi-sdk dependency when missing, import clue_init_fastapi plus ClueIdentify/ClueSetAccount/ClueLogout where needed, and initialize the SDK at FastAPI app creation.",
-			"For Django backends, add the clue-django-sdk dependency when missing, import the Django SDK lifecycle helpers where needed, and initialize the SDK in the Django integration point.",
-			"For other backend frameworks, use the matching Clue backend SDK if one exists; if no backend SDK exists, report a blocker instead of silently frontend-only setup.",
-			"Do not add broad ClueTrack instrumentation.",
-			"Do not add data-clue-id, data-clue-key, or similar DOM tags.",
-			"Do not create route semantics files or layer files.",
-			"Do not copy project keys, API keys, service secrets, or environment-specific values into code.",
-			"Do not send raw email, raw person names, tokens, workspace names, organization names, or tenant names as lifecycle traits unless the repository already has an explicit Clue privacy policy allowing them.",
-			"Prefer stable ids and non-PII booleans/counts for ClueIdentify and ClueSetAccount traits.",
-			"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 environment variables.",
-			"For browser code, read CLUE_PROJECT_KEY, CLUE_ENVIRONMENT, CLUE_SERVICE_KEY, and CLUE_INGEST_ENDPOINT from environment variables through the target framework's safe client config mechanism. Do not hard-code a Next.js-only 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 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.",
-			"Prefer minimal edits that engineers can review in one PR.",
-			"If a lifecycle point is unclear, skip that edit and include a warning.",
-		],
-		repository_context: {
-			target_tool: request.target_tool,
-			framework: request.framework,
-			project_key_env: "CLUE_PROJECT_KEY",
-			browser_project_key_env: "CLUE_PROJECT_KEY",
-			environment_env: "CLUE_ENVIRONMENT",
-			browser_environment_env: "CLUE_ENVIRONMENT",
-			clue_api_base_url_env: "CLUE_API_BASE_URL",
-			clue_ingest_endpoint_env: "CLUE_INGEST_ENDPOINT",
-			browser_ingest_endpoint_env: "CLUE_INGEST_ENDPOINT",
-			browser_token_endpoint_path: "/api/v1/ingest/browser-tokens",
-			service_key: request.service_key,
-		},
-		output_shape: {
-			edits: [
-				{
-					file_path: "app/main.py",
-					find: "exact original text",
-					replace: "exact replacement text",
-				},
-			],
-			lifecycle_insertions: [
-				{
-					api_name: "ClueInit",
-					file_path: "app/main.py",
-					confidence: 0.8,
-					reason: "SDK initialized where FastAPI app is created.",
-				},
-			],
-			warnings: ["short engineer review note"],
-		},
-		files,
-	});
+  JSON.stringify({
+    task: "Add Clue SDK lifecycle API calls to this repository using exact text replacements.",
+    rules: [
+      "Return JSON only.",
+      "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.",
+      "Do not add per-call try/catch, try/except, .catch, or custom safe wrappers solely around official Clue SDK public lifecycle calls.",
+      "Do not create no-op wrappers, placeholder lifecycle functions, fake SDK modules, window.Clue* shims, or helpers that swallow calls without forwarding them to a real Clue SDK import.",
+      "Custom repository adapters are allowed only when they demonstrably forward to the real Clue SDK.",
+      "Never await a Clue lifecycle call in a way that can block login, logout, account selection, request handling, page rendering, or API responses.",
+      "Find all clear login success paths and add ClueIdentify to every one of them. Do not stop after the first login flow.",
+      "Find all clear account, workspace, organization, or tenant resolution paths and add ClueSetAccount to every one of them.",
+      "Find all clear logout or session reset paths and add ClueLogout to every one of them.",
+      "Inspect backend lifecycle points as carefully as frontend lifecycle points. Backend login/session/account code is especially important.",
+      "For frontend code, add or use the real @clue-ai/browser-sdk dependency. Do not invent clue-js-sdk, @clue/browser-sdk, local SDK modules, global window.Clue APIs, or dynamic imports that hide a missing SDK.",
+      "For FastAPI backends, add the clue-fastapi-sdk dependency when missing, import clue_init_fastapi plus ClueIdentify/ClueSetAccount/ClueLogout where needed, and initialize the SDK at FastAPI app creation.",
+      "For Django backends, use clue-django-sdk only after dependency or registry verification confirms it is installable. If it cannot be verified, report a blocker instead of adding guessed imports or dependencies.",
+      "For other backend frameworks, treat SDK existence as unverified unless present in dependency files or verified through package-manager/official documentation. If no backend SDK exists or verification is impossible, report a blocker instead of silently frontend-only setup.",
+      "Do not add broad ClueTrack instrumentation.",
+      "Do not add data-clue-id, data-clue-key, or similar DOM tags.",
+      "Do not create route semantics files or layer files.",
+      "Do not copy project keys, API keys, service secrets, or environment-specific values into code.",
+      "Do not send raw email, raw person names, tokens, workspace names, organization names, or tenant names as lifecycle traits unless the repository already has an explicit Clue privacy policy allowing them.",
+      "Prefer stable ids and non-PII booleans/counts for ClueIdentify and ClueSetAccount traits.",
+      "Use environment variable names for Clue configuration values.",
+      "For Python/FastAPI code, read CLUE_PROJECT_KEY, CLUE_ENVIRONMENT, CLUE_API_KEY, CLUE_API_BASE_URL, and CLUE_INGEST_ENDPOINT from environment variables.",
+      "For browser code, read CLUE_PROJECT_KEY, CLUE_ENVIRONMENT, CLUE_SERVICE_KEY, and CLUE_INGEST_ENDPOINT from environment variables through the target framework's safe client config mechanism. Do not hard-code a Next.js-only 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 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.",
+      "Prefer minimal edits that engineers can review in one PR.",
+      "If a lifecycle point is unclear, skip that edit and include a warning.",
+      "Return status ready only when edits are safe to apply. Return status blocked when required SDKs or lifecycle points cannot be verified.",
+      "If status is blocked, return no edits and no lifecycle_insertions, and list blockers. Do not encode blockers as warnings.",
+    ],
+    repository_context: {
+      target_tool: request.target_tool,
+      framework: request.framework,
+      project_key_env: "CLUE_PROJECT_KEY",
+      browser_project_key_env: "CLUE_PROJECT_KEY",
+      environment_env: "CLUE_ENVIRONMENT",
+      browser_environment_env: "CLUE_ENVIRONMENT",
+      clue_api_base_url_env: "CLUE_API_BASE_URL",
+      clue_ingest_endpoint_env: "CLUE_INGEST_ENDPOINT",
+      browser_ingest_endpoint_env: "CLUE_INGEST_ENDPOINT",
+      browser_token_endpoint_path: "/api/v1/ingest/browser-tokens",
+      service_key: request.service_key,
+    },
+    output_shape: {
+      status: "ready",
+      blockers: [],
+      edits: [
+        {
+          file_path: "app/main.py",
+          find: "exact original text",
+          replace: "exact replacement text",
+        },
+      ],
+      lifecycle_insertions: [
+        {
+          api_name: "ClueInit",
+          file_path: "app/main.py",
+          confidence: 0.8,
+          reason: "SDK initialized where FastAPI app is created.",
+        },
+      ],
+      warnings: ["short engineer review note"],
+    },
+    files,
+  });
 
 export const planLifecycleInsertions = async ({ repoRoot, request, env }) => {
-	const apiKey = env.CLUE_AI_PROVIDER_API_KEY;
-	if (!apiKey) {
-		throw new Error(
-			"CLUE_AI_PROVIDER_API_KEY is required for lifecycle API insertion",
-		);
-	}
-	const files = await readContextFiles({ repoRoot, request });
-	return callJsonAiProvider({
-		config: resolveAiProviderConfig({ env, apiKey }),
-		system:
-			"You are a safe code-edit planner for Clue SDK initialization. Return schema-valid JSON only.",
-		user: buildLifecyclePrompt({ request, files }),
-		toolName: "return_lifecycle_plan",
-		toolDescription: "Return the Clue SDK lifecycle insertion plan.",
-		failureMessage: "AI provider failed during lifecycle planning",
-		emptyMessage: "AI provider returned empty lifecycle plan",
-	});
+  const apiKey = env.CLUE_AI_PROVIDER_API_KEY;
+  if (!apiKey) {
+    throw new Error(
+      "CLUE_AI_PROVIDER_API_KEY is required for lifecycle API insertion",
+    );
+  }
+  const files = await readContextFiles({ repoRoot, request });
+  return callJsonAiProvider({
+    config: resolveAiProviderConfig({ env, apiKey }),
+    system:
+      "You are a safe code-edit planner for Clue SDK initialization. Return schema-valid JSON only.",
+    user: buildLifecyclePrompt({ request, files }),
+    toolName: "return_lifecycle_plan",
+    toolDescription: "Return the Clue SDK lifecycle insertion plan.",
+    failureMessage: "AI provider failed during lifecycle planning",
+    emptyMessage: "AI provider returned empty lifecycle plan",
+  });
 };