@clue-ai/cli 0.0.5 → 0.0.7

package/src/lifecycle-init.mjs

@@ -1,13 +1,14 @@
 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([
-	"ClueInit",
-	"ClueIdentify",
-	"ClueSetAccount",
-	"ClueLogout",
+  "ClueInit",
+  "ClueIdentify",
+  "ClueSetAccount",
+  "ClueLogout",
 ]);
 
 const SOURCE_EXTENSIONS = [".py", ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"];
@@ -16,234 +17,208 @@ 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 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}`,
-			);
-		}
-		assertLifecycleCallsAreGuarded(edit.replace);
-		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.",
-			"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,
-	});
+  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.",
+    ],
+    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,
+    },
+    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.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",
+  });
 };

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)
@@ -22,6 +22,29 @@ const clueInitToolRequiredSecretsSchema = zod_1.z
     }
 })
     .transform((value) => Array.from(new Set(value)));
+const clueInitToolRequiredVariableSchema = zod_1.z.enum([
+    "CLUE_AI_PROVIDER",
+    "CLUE_AI_MODEL",
+    "CLUE_PROJECT_KEY",
+    "CLUE_ENVIRONMENT",
+    "CLUE_API_BASE_URL",
+]);
+const clueInitToolRequiredVariablesSchema = zod_1.z
+    .array(clueInitToolRequiredVariableSchema)
+    .superRefine((value, context) => {
+    for (const variable of [
+        "CLUE_AI_PROVIDER",
+        "CLUE_AI_MODEL",
+    ]) {
+        if (!value.includes(variable)) {
+            context.addIssue({
+                code: zod_1.z.ZodIssueCode.custom,
+                message: `${variable} is required`,
+            });
+        }
+    }
+})
+    .transform((value) => Array.from(new Set(value)));
 const clueInitToolRequestSchema = zod_1.z.object({
     target_tool: clueInitToolTargetSchema,
     project_key: nonEmptyStringSchema,
@@ -48,6 +71,7 @@ const clueInitToolReportSchema = zod_1.z.object({
     ci_workflow_path: nonEmptyStringSchema,
     ci_workflow_added: zod_1.z.literal(true),
     required_secrets: clueInitToolRequiredSecretsSchema,
+    required_variables: clueInitToolRequiredVariablesSchema,
     lifecycle_insertions: zod_1.z.array(clueInitToolLifecycleInsertionSchema),
     semantic_generation_timing: zod_1.z.literal("after_merge_ci"),
     semantic_preview_generated: zod_1.z.literal(false),
@@ -211,6 +235,27 @@ const semanticSnapshotAnalysisSummarySchema = zod_1.z
         .default(0),
 })
     .strict();
+const semanticSnapshotGenerationContractSchema = zod_1.z
+    .object({
+    schema_version: zod_1.z.number().int().positive(),
+    analyzer_version: nonEmptyStringSchema,
+    route_prompt_contract_version: nonEmptyStringSchema,
+    reuse_prompt_contract_version: nonEmptyStringSchema,
+    selector_prompt_contract_version: nonEmptyStringSchema,
+    privacy_sanitizer_version: nonEmptyStringSchema,
+})
+    .strict();
+const semanticSnapshotAiRuntimeSchema = zod_1.z
+    .object({
+    mode: zod_1.z.enum(["client_ci"]),
+    provider: nonEmptyStringSchema,
+    model: nonEmptyStringSchema,
+    model_source: zod_1.z.literal("customer_ci_secret"),
+    runner_version: nonEmptyStringSchema,
+    role_ids: zod_1.z.array(nonEmptyStringSchema).min(1),
+    temperature: zod_1.z.literal(0),
+})
+    .strict();
 const semanticCandidateSchema = zod_1.z
     .object({
     label: nonEmptyStringSchema,
@@ -460,6 +505,8 @@ const semanticSnapshotRequestSchema = zod_1.z
     idempotency_key: nonEmptyStringSchema,
     schema_version: zod_1.z.number().int().positive().default(1),
     semantic_snapshot_version: nonEmptyStringSchema.optional(),
+    generation_contract: semanticSnapshotGenerationContractSchema.optional(),
+    ai_runtime: semanticSnapshotAiRuntimeSchema.optional(),
     generated_at: zod_1.z.string().datetime({ offset: true }),
     repository: semanticSnapshotRepositorySchema,
     service: semanticSnapshotServiceSchema,