@clue-ai/cli 0.0.4 → 0.0.5

package/src/lifecycle-init.mjs

@@ -1,12 +1,13 @@
 import { readFile, writeFile } from "node:fs/promises";
 import { isAbsolute, relative, resolve } from "node:path";
+import { findLifecycleGuardViolations } 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"];
@@ -15,192 +16,234 @@ const MAX_FILE_CHARS = 12_000;
 const MAX_TOTAL_CHARS = 360_000;
 
 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 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"),
-  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 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 (!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())
+			: [],
+	};
 };
 
 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}`,
-      );
-    }
-    await writeFile(absolutePath, current.replace(edit.find, edit.replace), "utf8");
-  }
-  return {
-    lifecycleInsertions: plan.lifecycleInsertions,
-    warnings: plan.warnings,
-  };
+	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 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.",
-    "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",
-      },
-    ],
-    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,
-});
+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 NEXT_PUBLIC_CLUE_PROJECT_KEY, NEXT_PUBLIC_CLUE_ENVIRONMENT, and NEXT_PUBLIC_CLUE_INGEST_ENDPOINT from environment variables.",
+			"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: "NEXT_PUBLIC_CLUE_PROJECT_KEY",
+			environment_env: "CLUE_ENVIRONMENT",
+			browser_environment_env: "NEXT_PUBLIC_CLUE_ENVIRONMENT",
+			clue_api_base_url_env: "CLUE_API_BASE_URL",
+			clue_ingest_endpoint_env: "CLUE_INGEST_ENDPOINT",
+			browser_ingest_endpoint_env: "NEXT_PUBLIC_CLUE_INGEST_ENDPOINT",
+			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,
+	});
 
 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}`,
-    },
-    body: JSON.stringify({
-      model,
-      messages: [
-        {
-          role: "system",
-          content: "You are a safe code-edit planner for Clue SDK initialization. Return schema-valid JSON only.",
-        },
-        { role: "user", content: buildLifecyclePrompt({ request, files }) },
-      ],
-      response_format: { type: "json_object" },
-    }),
-  });
-  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");
-  }
-  return JSON.parse(content);
+	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}`,
+		},
+		body: JSON.stringify({
+			model,
+			messages: [
+				{
+					role: "system",
+					content:
+						"You are a safe code-edit planner for Clue SDK initialization. Return schema-valid JSON only.",
+				},
+				{ role: "user", content: buildLifecyclePrompt({ request, files }) },
+			],
+			response_format: { type: "json_object" },
+		}),
+	});
+	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");
+	}
+	return JSON.parse(content);
 };

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

@@ -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,