@clue-ai/cli 0.0.4 → 0.0.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clue-ai/cli",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "type": "module",
   "bin": {
     "clue-ai": "bin/clue-cli.mjs"

package/src/contracts.mjs

@@ -7,6 +7,7 @@ const {
   clueInitToolRequestSchema,
   clueInitToolReportSchema,
   semanticSnapshotRequestSchema,
+  semanticSnapshotResponseSchema,
 } = schemaPackage;
 
 const formatSchemaError = (result, field) => {
@@ -122,3 +123,7 @@ export const buildOperationSourceKey = (method, pathTemplate) =>
 export const validateSemanticSnapshotRequest = (input) => {
   return parseWithSchema(semanticSnapshotRequestSchema, input, "semantic snapshot");
 };
+
+export const validateSemanticSnapshotResponse = (input) => {
+  return parseWithSchema(semanticSnapshotResponseSchema, input, "semantic snapshot response");
+};

package/src/init-tool.mjs

@@ -1,86 +1,185 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { buildInitReport, validateInitRequest } from "./contracts.mjs";
-import { applyLifecyclePlan, planLifecycleInsertions } from "./lifecycle-init.mjs";
+import {
+	applyLifecyclePlan,
+	planLifecycleInsertions,
+} from "./lifecycle-init.mjs";
+
+const DEFAULT_SEMANTIC_WORKFLOW_PATH =
+	".github/workflows/clue-semantic-snapshot.yml";
+
+const nonEmpty = (value, field) => {
+	if (typeof value !== "string" || value.trim() === "") {
+		throw new Error(`${field} is required`);
+	}
+	return value.trim();
+};
+
+const normalizeStringArray = (value, field, { min = 0 } = {}) => {
+	if (!Array.isArray(value)) {
+		throw new Error(`${field} must be an array`);
+	}
+	const result = value
+		.filter((entry) => typeof entry === "string" && entry.trim())
+		.map((entry) => entry.trim());
+	if (result.length < min) {
+		throw new Error(`${field} must include at least ${min} item(s)`);
+	}
+	return [...new Set(result)];
+};
+
+const splitCsv = (value) =>
+	typeof value === "string"
+		? value
+				.split(",")
+				.map((entry) => entry.trim())
+				.filter(Boolean)
+		: [];
+
+const deriveServiceKeyFromPath = (backendRootPath) => {
+	const segment = backendRootPath
+		.split("/")
+		.map((part) => part.trim())
+		.filter(Boolean)
+		.at(-1);
+	const normalized = segment
+		?.toLowerCase()
+		.replace(/[^a-z0-9_-]+/g, "-")
+		.replace(/^-+|-+$/g, "");
+	if (!normalized) {
+		throw new Error("service-key cannot be derived from backend-root-path");
+	}
+	return normalized;
+};
+
+export const buildSemanticWorkflowRequestFromFlags = (flags) => {
+	const backendRootPath = nonEmpty(flags.backendRootPath, "backend-root-path");
+	const allowedSourcePaths = splitCsv(flags.allowedSourcePaths);
+	return {
+		ci_workflow_path:
+			typeof flags.workflowPath === "string" && flags.workflowPath.trim()
+				? flags.workflowPath.trim()
+				: DEFAULT_SEMANTIC_WORKFLOW_PATH,
+		service_key:
+			typeof flags.serviceKey === "string" && flags.serviceKey.trim()
+				? flags.serviceKey.trim()
+				: deriveServiceKeyFromPath(backendRootPath),
+		framework: nonEmpty(flags.framework, "framework"),
+		allowed_source_paths: normalizeStringArray(
+			allowedSourcePaths.length ? allowedSourcePaths : [backendRootPath],
+			"allowed-source-paths",
+			{ min: 1 },
+		),
+		excluded_source_paths: normalizeStringArray(
+			splitCsv(flags.excludedSourcePaths),
+			"excluded-source-paths",
+		),
+	};
+};
 
 const workflowRequestPayload = (request) =>
-  JSON.stringify(
-    {
-      project_key: "${{ vars.CLUE_PROJECT_KEY }}",
-      environment: "${{ vars.CLUE_ENVIRONMENT }}",
-      service_key: request.service_key,
-      repository: {
-        provider: "github",
-        repository_id: "${{ github.repository_id }}",
-        owner: "${{ github.repository_owner }}",
-        name: "${{ github.event.repository.name }}",
-        default_branch: "${{ github.event.repository.default_branch }}",
-        merge_commit: "${{ github.sha }}",
-        workflow_run_id: "${{ github.run_id }}",
-      },
-      service: {
-        service_key: request.service_key,
-        root_path: request.allowed_source_paths[0],
-        framework: request.framework,
-        language: "python",
-      },
-      allowed_source_paths: request.allowed_source_paths,
-      excluded_source_paths: request.excluded_source_paths,
-      clue_api_base_url: "${{ vars.CLUE_API_BASE_URL }}",
-      ai_model: "${{ vars.CLUE_AI_MODEL }}",
-    },
-    null,
-    10,
-  ).trim();
+	JSON.stringify(
+		{
+			project_key: "${{ vars.CLUE_PROJECT_KEY }}",
+			environment: "${{ vars.CLUE_ENVIRONMENT }}",
+			service_key: request.service_key,
+			repository: {
+				provider: "github",
+				repository_id: "${{ github.repository_id }}",
+				merge_commit: "${{ github.sha }}",
+				workflow_run_id: "${{ github.run_id }}",
+			},
+			service: {
+				service_key: request.service_key,
+				root_path: request.allowed_source_paths[0],
+				framework: request.framework,
+				language: "python",
+			},
+			allowed_source_paths: request.allowed_source_paths,
+			excluded_source_paths: request.excluded_source_paths,
+			clue_api_base_url: "${{ vars.CLUE_API_BASE_URL }}",
+			ai_model: "${{ vars.CLUE_AI_MODEL }}",
+		},
+		null,
+		10,
+	).trim();
+
+const indentMultiline = (value, spaces) => {
+	const prefix = " ".repeat(spaces);
+	return value
+		.split("\n")
+		.map((line) => `${prefix}${line}`)
+		.join("\n");
+};
 
 const workflowTemplate = (request) => `name: Clue Semantic Snapshot
 
 on:
   push:
 
+permissions:
+  contents: read
+
 jobs:
   semantic-snapshot:
     if: github.ref_name == github.event.repository.default_branch
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
       - uses: actions/setup-node@v4
         with:
           node-version: "20"
       - name: Run Clue semantic generation
-        continue-on-error: true
         env:
           CLUE_API_KEY: \${{ secrets.CLUE_API_KEY }}
           AI_PROVIDER_API_KEY: \${{ secrets.AI_PROVIDER_API_KEY }}
+          CLUE_SEMANTIC_REQUEST_JSON: |
+${indentMultiline(workflowRequestPayload(request), 12)}
         run: |
-          mkdir -p .clue
-          cat > .clue/semantic-request.runtime.json <<'JSON'
-          ${workflowRequestPayload(request)}
-          JSON
-          npx @clue-ai/cli semantic-ci --request .clue/semantic-request.runtime.json --repo .
+          npx @clue-ai/cli semantic-ci --request-env CLUE_SEMANTIC_REQUEST_JSON --repo .
 `;
 
+export const writeSemanticWorkflow = async ({ repoRoot, request }) => {
+	const workflowPath = join(repoRoot, request.ci_workflow_path);
+	await mkdir(dirname(workflowPath), { recursive: true });
+	await writeFile(workflowPath, workflowTemplate(request), "utf8");
+	return {
+		ci_workflow_path: request.ci_workflow_path,
+		ci_workflow_added: true,
+		required_secrets: ["CLUE_API_KEY", "AI_PROVIDER_API_KEY"],
+		required_variables: [
+			"CLUE_PROJECT_KEY",
+			"CLUE_ENVIRONMENT",
+			"CLUE_API_BASE_URL",
+			"CLUE_AI_MODEL",
+		],
+		runtime_request_committed: false,
+		semantic_generation_timing: "after_merge_ci",
+		allowed_source_paths: request.allowed_source_paths,
+		excluded_source_paths: request.excluded_source_paths,
+	};
+};
+
 export const runInitTool = async ({
-  repoRoot,
-  request: rawRequest,
-  env = process.env,
-  lifecyclePlanner = planLifecycleInsertions,
+	repoRoot,
+	request: rawRequest,
+	env = process.env,
+	lifecyclePlanner = planLifecycleInsertions,
 }) => {
-  const request = validateInitRequest(rawRequest);
-  const workflowPath = join(repoRoot, request.ci_workflow_path);
-  await mkdir(dirname(workflowPath), { recursive: true });
-  await writeFile(workflowPath, workflowTemplate(request), "utf8");
-  const lifecyclePlan = await lifecyclePlanner({ repoRoot, request, env });
-  const lifecycleResult = await applyLifecyclePlan({
-    repoRoot,
-    plan: lifecyclePlan,
-  });
+	const request = validateInitRequest(rawRequest);
+	await writeSemanticWorkflow({ repoRoot, request });
+	const lifecyclePlan = await lifecyclePlanner({ repoRoot, request, env });
+	const lifecycleResult = await applyLifecyclePlan({
+		repoRoot,
+		plan: lifecyclePlan,
+	});
 
-  return buildInitReport({
-    request,
-    lifecycleInsertions: lifecycleResult.lifecycleInsertions,
-    warnings: [
-      ...lifecycleResult.warnings,
-    ],
-  });
+	return buildInitReport({
+		request,
+		lifecycleInsertions: lifecycleResult.lifecycleInsertions,
+		warnings: [...lifecycleResult.warnings],
+	});
 };

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]),
+	),
+];