@clue-ai/cli 0.0.4 → 0.0.6

package/src/lifecycle-guard.mjs

@@ -0,0 +1,141 @@
+const LIFECYCLE_CALL_PATTERN =
+	/\b(ClueInit|ClueIdentify|ClueSetAccount|ClueLogout)\s*\(/g;
+const SAFE_HELPER_PATTERN =
+	/\b(?:safeClue|safe_clue|safe_clue_call|safeClueCall|withClueGuard|with_clue_guard)\s*\(/g;
+
+const findMatchingDelimiter = (text, openIndex, open, close) => {
+	let depth = 0;
+	for (let index = openIndex; index < text.length; index += 1) {
+		const character = text[index];
+		if (character === open) depth += 1;
+		if (character === close) {
+			depth -= 1;
+			if (depth === 0) return index;
+		}
+	}
+	return -1;
+};
+
+const lineNumberForIndex = (text, index) =>
+	text.slice(0, index).split("\n").length;
+
+const isAwaitedOnCallLine = (text, callIndex) => {
+	const lineStart = text.lastIndexOf("\n", callIndex - 1) + 1;
+	return /\bawait\b/.test(text.slice(lineStart, callIndex));
+};
+
+const isInsideSafeHelperCall = (text, callIndex) => {
+	for (const match of text.matchAll(SAFE_HELPER_PATTERN)) {
+		const helperIndex = match.index ?? 0;
+		if (helperIndex > callIndex) return false;
+		const openParenIndex = text.indexOf("(", helperIndex);
+		const closeParenIndex = findMatchingDelimiter(
+			text,
+			openParenIndex,
+			"(",
+			")",
+		);
+		if (openParenIndex < callIndex && callIndex < closeParenIndex) return true;
+	}
+	return false;
+};
+
+const isInsideJsTryBlock = (text, callIndex) => {
+	for (const match of text.matchAll(/\btry\s*{/g)) {
+		const tryIndex = match.index ?? 0;
+		if (tryIndex > callIndex) return false;
+		const openBraceIndex = text.indexOf("{", tryIndex);
+		const closeBraceIndex = findMatchingDelimiter(
+			text,
+			openBraceIndex,
+			"{",
+			"}",
+		);
+		if (openBraceIndex < callIndex && callIndex < closeBraceIndex) return true;
+	}
+	return false;
+};
+
+const buildLines = (text) => {
+	const lines = [];
+	let start = 0;
+	for (const line of text.split("\n")) {
+		const indent = line.match(/^\s*/)?.[0].length ?? 0;
+		lines.push({
+			start,
+			end: start + line.length,
+			indent,
+			text: line,
+		});
+		start += line.length + 1;
+	}
+	return lines;
+};
+
+const isInsidePythonTryBlock = (text, callIndex) => {
+	const lines = buildLines(text);
+	const callLineIndex = lines.findIndex(
+		(line) => line.start <= callIndex && callIndex <= line.end,
+	);
+	if (callLineIndex < 0) return false;
+	const callLine = lines[callLineIndex];
+	for (let index = callLineIndex - 1; index >= 0; index -= 1) {
+		const candidate = lines[index];
+		if (!candidate.text.trim()) continue;
+		if (!/^\s*try\s*:\s*(?:#.*)?$/.test(candidate.text)) continue;
+		if (candidate.indent >= callLine.indent) continue;
+		const escaped = lines
+			.slice(index + 1, callLineIndex)
+			.some(
+				(line) =>
+					line.text.trim() &&
+					line.indent <= candidate.indent &&
+					!/^\s*(?:except|finally|else)\b/.test(line.text),
+			);
+		if (!escaped) return true;
+	}
+	return false;
+};
+
+const hasCatchHandlerOnCall = (text, callIndex) => {
+	const openParenIndex = text.indexOf("(", callIndex);
+	const closeParenIndex = findMatchingDelimiter(text, openParenIndex, "(", ")");
+	if (closeParenIndex < 0) return false;
+	return /^\s*\.catch\s*\(/.test(text.slice(closeParenIndex + 1));
+};
+
+const isGuardedLifecycleCall = (text, callIndex) =>
+	hasCatchHandlerOnCall(text, callIndex) ||
+	isInsideSafeHelperCall(text, callIndex) ||
+	isInsideJsTryBlock(text, callIndex) ||
+	isInsidePythonTryBlock(text, callIndex);
+
+export const findLifecycleGuardViolations = (text) => {
+	const violations = [];
+	for (const match of text.matchAll(LIFECYCLE_CALL_PATTERN)) {
+		const callIndex = match.index ?? 0;
+		const apiName = match[1];
+		if (isAwaitedOnCallLine(text, callIndex)) {
+			violations.push({
+				api_name: apiName,
+				line: lineNumberForIndex(text, callIndex),
+				reason: "awaited_lifecycle_call",
+			});
+			continue;
+		}
+		if (!isGuardedLifecycleCall(text, callIndex)) {
+			violations.push({
+				api_name: apiName,
+				line: lineNumberForIndex(text, callIndex),
+				reason: "unguarded_lifecycle_call",
+			});
+		}
+	}
+	return violations;
+};
+
+export const findLifecycleCallApiNames = (text) => [
+	...new Set(
+		[...text.matchAll(LIFECYCLE_CALL_PATTERN)].map((match) => match[1]),
+	),
+];

package/src/lifecycle-init.mjs

@@ -1,5 +1,7 @@
 import { readFile, writeFile } from "node:fs/promises";
 import { isAbsolute, relative, resolve } from "node:path";
+import { callJsonAiProvider, resolveAiProviderConfig } from "./ai-provider.mjs";
+import { findLifecycleGuardViolations } from "./lifecycle-guard.mjs";
 import { listAllowedSourceFiles } from "./path-policy.mjs";
 
 const API_NAMES = new Set([
@@ -25,10 +27,7 @@ const safeRelativePath = (repoRoot, filePath) => {
   const root = resolve(repoRoot);
   const absolutePath = resolve(root, filePath);
   const relativePath = relative(root, absolutePath);
-  if (
-    relativePath.startsWith("..") ||
-    isAbsolute(relativePath)
-  ) {
+  if (relativePath.startsWith("..") || isAbsolute(relativePath)) {
     throw new Error(`edit path escapes repo root: ${filePath}`);
   }
   return { absolutePath, relativePath };
@@ -50,6 +49,15 @@ const assertNoForbiddenInstrumentation = (replacement) => {
   }
 };
 
+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 normalizeLifecycleInsertion = (input) => ({
   api_name: assertApiName(nonEmpty(input.api_name, "api_name")),
   file_path: nonEmpty(input.file_path, "file_path"),
@@ -95,7 +103,12 @@ export const applyLifecyclePlan = async ({ repoRoot, plan: rawPlan }) => {
         `edit.find must match exactly once in ${edit.file_path}; matched ${occurrences}`,
       );
     }
-    await writeFile(absolutePath, current.replace(edit.find, edit.replace), "utf8");
+    assertLifecycleCallsAreGuarded(edit.replace);
+    await writeFile(
+      absolutePath,
+      current.replace(edit.find, edit.replace),
+      "utf8",
+    );
   }
   return {
     lifecycleInsertions: plan.lifecycleInsertions,
@@ -128,79 +141,84 @@ const readContextFiles = async ({ repoRoot, request }) => {
   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.",
-    "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.",
-    "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: request.project_key,
-    environment: request.environment,
-    service_key: request.service_key,
-  },
-  output_shape: {
-    edits: [
-      {
-        file_path: "app/main.py",
-        find: "exact original text",
-        replace: "exact replacement text",
-      },
+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, 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.",
+      "Prefer minimal edits that engineers can review in one PR.",
+      "If a lifecycle point is unclear, skip that edit and include a warning.",
     ],
-    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.AI_PROVIDER_API_KEY;
-  if (!apiKey) {
-    throw new Error("AI_PROVIDER_API_KEY is required for lifecycle API insertion");
-  }
-  const files = await readContextFiles({ repoRoot, request });
-  const baseUrl = String(env.AI_PROVIDER_BASE_URL || "https://api.openai.com/v1").replace(/\/+$/, "");
-  const model = String(env.CLUE_INIT_AI_MODEL || env.CLUE_AI_MODEL || "gpt-5.4-mini");
-  const response = await fetch(`${baseUrl}/chat/completions`, {
-    method: "POST",
-    headers: {
-      "content-type": "application/json",
-      authorization: `Bearer ${apiKey}`,
+    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",
+      service_key: request.service_key,
     },
-    body: JSON.stringify({
-      model,
-      messages: [
+    output_shape: {
+      edits: [
         {
-          role: "system",
-          content: "You are a safe code-edit planner for Clue SDK initialization. Return schema-valid JSON only.",
+          file_path: "app/main.py",
+          find: "exact original text",
+          replace: "exact replacement text",
         },
-        { role: "user", content: buildLifecyclePrompt({ request, files }) },
       ],
-      response_format: { type: "json_object" },
-    }),
+      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,
   });
-  if (!response.ok) {
-    throw new Error(`AI provider failed during lifecycle planning: ${response.status}`);
-  }
-  const body = await response.json();
-  const content = body?.choices?.[0]?.message?.content;
-  if (typeof content !== "string" || content.trim() === "") {
-    throw new Error("AI provider returned empty lifecycle plan");
+
+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",
+    );
   }
-  return JSON.parse(content);
+  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",
+  });
 };

package/src/path-policy.mjs

@@ -4,7 +4,9 @@ import { isAbsolute, join, relative, resolve } from "node:path";
 const DEFAULT_EXCLUDES = [
   ".git",
   ".env",
+  ".venv",
   ".next",
+  "venv",
   "node_modules",
   "dist",
   "build",

package/src/public-schema.cjs

@@ -7,7 +7,7 @@ const clueInitToolTargetSchema = zod_1.z.enum(["codex", "claude_code"]);
 const clueInitToolFrameworkSchema = nonEmptyStringSchema;
 const clueInitToolRequiredSecretSchema = zod_1.z.enum([
     "CLUE_API_KEY",
-    "AI_PROVIDER_API_KEY",
+    "CLUE_AI_PROVIDER_API_KEY",
 ]);
 const clueInitToolRequiredSecretsSchema = zod_1.z
     .array(clueInitToolRequiredSecretSchema)
@@ -137,6 +137,15 @@ const semanticSnapshotSelectedSourceValues = [
     "deterministic",
     "ai",
 ];
+const semanticSnapshotRouteOriginValues = [
+    "unchanged_route_reused",
+    "changed_route_semantic_reused",
+    "changed_route_semantic_regenerated",
+    "new_route_ai_generated",
+    "deleted_route_removed",
+    "changed_route_needs_review",
+    "fallback",
+];
 const targetObjectKeySchema = nonEmptyStringSchema.regex(snakeSegmentPattern, {
     message: "must be a lowercase snake_case key",
 });
@@ -190,6 +199,16 @@ const semanticSnapshotAnalysisSummarySchema = zod_1.z
     routes_generated: zod_1.z.number().int().nonnegative(),
     uncertain_routes: zod_1.z.number().int().nonnegative(),
     failed_routes: zod_1.z.number().int().nonnegative(),
+    routes_reused: zod_1.z.number().int().nonnegative().default(0),
+    routes_ai_generated: zod_1.z.number().int().nonnegative().default(0),
+    routes_deleted: zod_1.z.number().int().nonnegative().default(0),
+    routes_needs_review: zod_1.z.number().int().nonnegative().default(0),
+    changed_routes_semantic_reused: zod_1.z.number().int().nonnegative().default(0),
+    changed_routes_semantic_regenerated: zod_1.z
+        .number()
+        .int()
+        .nonnegative()
+        .default(0),
 })
     .strict();
 const semanticCandidateSchema = zod_1.z
@@ -375,8 +394,15 @@ const routeSemanticSnapshotEntrySchema = zod_1.z
     .object({
     operation_source_key: nonEmptyStringSchema,
     semantic_snapshot_version: nonEmptyStringSchema.optional(),
+    previous_semantic_snapshot_version: nonEmptyStringSchema.optional(),
     method: nonEmptyStringSchema.optional(),
     path_template: nonEmptyStringSchema.optional(),
+    route_input_hash: semanticSnapshotHashSchema.optional(),
+    previous_route_input_hash: semanticSnapshotHashSchema.optional(),
+    route_semantic_hash: semanticSnapshotHashSchema.optional(),
+    previous_route_semantic_hash: semanticSnapshotHashSchema.optional(),
+    semantic_origin: zod_1.z.enum(semanticSnapshotRouteOriginValues).optional(),
+    semantic_change_reason: nonEmptyStringSchema.optional(),
     semantics: zod_1.z
         .object({
         route_summary: nonEmptyStringSchema,