@clue-ai/cli 0.0.3 → 0.0.5

package/commands/claude-code/clue-init.md

@@ -4,8 +4,7 @@ Run the Clue SDK initialization tool with structured inputs.
 
 Required fields:
 
-- `project_key`
-- `service_key`
+- `project_key` as an environment variable reference or placeholder, not a pasted secret value
 - `framework`
 - `backend_root_path`
 - `environment`
@@ -19,9 +18,12 @@ Required secrets:
 
 Behavior:
 
-1. Collect the required fields as structured input.
-2. Build the canonical init request.
-3. Run `clue-ai init --request <generated-request.json> --repo .`.
-4. Show the generated report and low-confidence review points.
+1. Follow the installed `clue-setup-orchestrator` skill and its monitoring gates.
+2. Collect the required fields as structured input without asking for secret values.
+3. Derive `service_key` from `backend_root_path` and repository structure; do not ask the user to type it.
+4. Build the canonical init request.
+5. Run `clue-ai init --request <generated-request.json> --repo .`.
+6. Show the generated report and low-confidence review points.
 
 Do not ask the user to write a free-form setup prompt.
+Do not ask the user to paste project key, API key, service key, token, or environment values.

package/commands/codex/clue-init.md

@@ -4,8 +4,7 @@ Run the Clue SDK initialization tool with structured inputs.
 
 Required fields:
 
-- `project_key`
-- `service_key`
+- `project_key` as an environment variable reference or placeholder, not a pasted secret value
 - `framework`
 - `backend_root_path`
 - `environment`
@@ -19,9 +18,12 @@ Required secrets:
 
 Behavior:
 
-1. Collect the required fields as structured input.
-2. Build the canonical init request.
-3. Run `clue-ai init --request <generated-request.json> --repo .`.
-4. Show the generated report and low-confidence review points.
+1. Follow the installed `clue-setup-orchestrator` skill and its monitoring gates.
+2. Collect the required fields as structured input without asking for secret values.
+3. Derive `service_key` from `backend_root_path` and repository structure; do not ask the user to type it.
+4. Build the canonical init request.
+5. Run `clue-ai init --request <generated-request.json> --repo .`.
+6. Show the generated report and low-confidence review points.
 
 Do not ask the user to write a free-form setup prompt.
+Do not ask the user to paste project key, API key, service key, token, or environment values.

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@clue-ai/cli",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "type": "module",
   "bin": {
-    "clue-ai": "bin/clue-tool.mjs"
+    "clue-ai": "bin/clue-cli.mjs"
   },
   "files": [
     "bin/",

package/src/command-spec.mjs

@@ -7,7 +7,6 @@ export const REQUIRED_SECRET_NAMES = [
 
 export const CLUE_INIT_COMMAND_FIELDS = [
   "project_key",
-  "service_key",
   "framework",
   "backend_root_path",
   "environment",
@@ -45,15 +44,35 @@ const normalizeStringArray = (value, fallback, field) => {
     .map((entry) => entry.trim());
 };
 
+const deriveServiceKeyFromBackendRootPath = (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 for ${CLUE_INIT_COMMAND_NAME}`);
+  }
+  return normalized;
+};
+
 export const buildClueInitRequestFromCommandInput = ({
   targetTool,
   input,
 }) => {
   const backendRootPath = requireField(input, "backend_root_path");
+  const serviceKey =
+    typeof input?.service_key === "string" && input.service_key.trim()
+      ? input.service_key.trim()
+      : deriveServiceKeyFromBackendRootPath(backendRootPath);
   return {
     target_tool: targetTool,
     project_key: requireField(input, "project_key"),
-    service_key: requireField(input, "service_key"),
+    service_key: serviceKey,
     framework: requireField(input, "framework"),
     environment: requireField(input, "environment"),
     allowed_source_paths: normalizeStringArray(

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/fastapi-analyzer.mjs

@@ -13,6 +13,7 @@ const FUNCTION_PATTERN = /(?:async\s+def|def)\s+(?<name>[A-Za-z_][A-Za-z0-9_]*)\
 const ROUTER_ASSIGNMENT = /\b(?<name>[A-Za-z_][A-Za-z0-9_]*)\s*=\s*APIRouter\s*\(/g;
 const INCLUDE_ROUTER_CALL = /\b(?<owner>[A-Za-z_][A-Za-z0-9_]*)\.include_router\s*\(/g;
 const FROM_IMPORT = /^\s*from\s+(?<module>[A-Za-z0-9_.]+|\.+[A-Za-z0-9_.]*)\s+import\s+(?<names>[A-Za-z0-9_,\s]+)$/gm;
+const IMPORT_MODULE = /^\s*import\s+(?<modules>[A-Za-z0-9_.,\s]+)$/gm;
 
 const sha256 = (value) => `sha256:${createHash("sha256").update(value).digest("hex")}`;
 
@@ -125,6 +126,41 @@ const resolveImportFile = ({ filesByRelativePath, currentRelativePath, moduleNam
   return null;
 };
 
+const resolveFromImportEntry = ({
+  filesByRelativePath,
+  currentRelativePath,
+  moduleName,
+  importedName,
+}) => {
+  const childModuleName =
+    moduleName.endsWith(".") || moduleName === "."
+      ? `${moduleName}${importedName}`
+      : `${moduleName}.${importedName}`;
+  const childFile = resolveImportFile({
+    filesByRelativePath,
+    currentRelativePath,
+    moduleName: childModuleName,
+  });
+  if (childFile) {
+    return {
+      file: childFile,
+      name: undefined,
+    };
+  }
+  const moduleFile = resolveImportFile({
+    filesByRelativePath,
+    currentRelativePath,
+    moduleName,
+  });
+  if (!moduleFile) {
+    return null;
+  }
+  return {
+    file: moduleFile,
+    name: importedName,
+  };
+};
+
 const parseRouterAssignments = (source, relativePath) => {
   const prefixes = new Map();
   for (const match of source.matchAll(ROUTER_ASSIGNMENT)) {
@@ -141,44 +177,99 @@ const parseRouterAssignments = (source, relativePath) => {
 const parseImports = ({ source, currentRelativePath, filesByRelativePath }) => {
   const imports = new Map();
   for (const match of source.matchAll(FROM_IMPORT)) {
-    const targetFile = resolveImportFile({
-      filesByRelativePath,
-      currentRelativePath,
-      moduleName: match.groups.module,
-    });
-    if (!targetFile) {
-      continue;
-    }
     for (const entry of parseImportNames(match.groups.names)) {
+      const resolved = resolveFromImportEntry({
+        filesByRelativePath,
+        currentRelativePath,
+        moduleName: match.groups.module,
+        importedName: entry.importedName,
+      });
+      if (!resolved) {
+        continue;
+      }
       imports.set(entry.localName, {
+        file: resolved.file,
+        name: resolved.name,
+      });
+    }
+  }
+  for (const match of source.matchAll(IMPORT_MODULE)) {
+    for (const entry of parseImportNames(match.groups.modules)) {
+      const targetFile = resolveImportFile({
+        filesByRelativePath,
+        currentRelativePath,
+        moduleName: entry.importedName,
+      });
+      if (!targetFile) {
+        continue;
+      }
+      imports.set(entry.localName.split(".").at(-1), {
         file: targetFile,
-        name: entry.importedName,
+        name: undefined,
       });
     }
   }
   return imports;
 };
 
+const routerKey = (file, routerName) => `${file}::${routerName}`;
+
+const resolveRouterTarget = ({ target, relativePath, imports }) => {
+  const parts = target.split(".");
+  if (parts.length === 1) {
+    const imported = imports.get(target);
+    return {
+      file: imported?.file ?? relativePath,
+      routerName: imported?.name ?? target,
+    };
+  }
+  const imported = imports.get(parts[0]);
+  if (!imported?.file || imported.name) {
+    throw new Error(`${relativePath}: include_router dotted target cannot be analyzed safely`);
+  }
+  if (parts.length !== 2) {
+    throw new Error(`${relativePath}: include_router dotted target cannot be analyzed safely`);
+  }
+  return {
+    file: imported.file,
+    routerName: parts[1],
+  };
+};
+
 const parseIncludeRouters = ({ source, relativePath, imports }) => {
   const includes = [];
   for (const match of source.matchAll(INCLUDE_ROUTER_CALL)) {
     const openParenIndex = match.index + match[0].length - 1;
     const args = readCallArgs(source, openParenIndex);
-    const routerMatch = /^\s*(?<router>[A-Za-z_][A-Za-z0-9_]*)/.exec(args);
+    const routerMatch = /^\s*(?<router>[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*)/.exec(args);
     if (!routerMatch?.groups?.router) {
       throw new Error(`${relativePath}: include_router target cannot be analyzed safely`);
     }
-    const routerName = routerMatch.groups.router;
-    const imported = imports.get(routerName);
+    const resolved = resolveRouterTarget({
+      target: routerMatch.groups.router,
+      relativePath,
+      imports,
+    });
     includes.push({
-      file: imported?.file ?? relativePath,
-      routerName: imported?.name ?? routerName,
+      ownerName: match.groups.owner,
+      file: resolved.file,
+      routerName: resolved.routerName,
       prefix: extractPrefix({ args, relativePath, callName: "include_router" }),
     });
   }
   return includes;
 };
 
+const addIncludePrefix = (prefixesByRouterKey, key, prefix) => {
+  const current = prefixesByRouterKey.get(key) ?? [];
+  if (!current.includes(prefix)) {
+    current.push(prefix);
+    prefixesByRouterKey.set(key, current);
+    return true;
+  }
+  return false;
+};
+
 const findNextFunction = (source, fromIndex) => {
   FUNCTION_PATTERN.lastIndex = fromIndex;
   const match = FUNCTION_PATTERN.exec(source);
@@ -270,6 +361,14 @@ export const analyzeFastApiRoutes = async ({ repoRoot, files }) => {
     });
   }
 
+  const routerPrefixesByKey = new Map();
+  for (const record of records) {
+    for (const [routerName, prefix] of record.routerPrefixes.entries()) {
+      routerPrefixesByKey.set(routerKey(record.relativePath, routerName), prefix);
+    }
+  }
+
+  const includeEdges = [];
   const includePrefixes = new Map();
   for (const record of records) {
     for (const include of parseIncludeRouters({
@@ -277,10 +376,42 @@ export const analyzeFastApiRoutes = async ({ repoRoot, files }) => {
       relativePath: record.relativePath,
       imports: record.imports,
     })) {
-      const key = `${include.file}::${include.routerName}`;
-      const current = includePrefixes.get(key) ?? [];
-      current.push(include.prefix);
-      includePrefixes.set(key, current);
+      const parentKey = record.routerPrefixes.has(include.ownerName)
+        ? routerKey(record.relativePath, include.ownerName)
+        : null;
+      includeEdges.push({
+        parentKey,
+        targetKey: routerKey(include.file, include.routerName),
+        prefix: include.prefix,
+      });
+      if (!parentKey) {
+        addIncludePrefix(
+          includePrefixes,
+          routerKey(include.file, include.routerName),
+          include.prefix,
+        );
+      }
+    }
+  }
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const edge of includeEdges) {
+      if (!edge.parentKey) {
+        continue;
+      }
+      for (const parentPrefix of includePrefixes.get(edge.parentKey) ?? []) {
+        changed =
+          addIncludePrefix(
+            includePrefixes,
+            edge.targetKey,
+            combinePaths(
+              parentPrefix,
+              routerPrefixesByKey.get(edge.parentKey) ?? "",
+              edge.prefix,
+            ),
+          ) || changed;
+      }
     }
   }
 
@@ -289,7 +420,7 @@ export const analyzeFastApiRoutes = async ({ repoRoot, files }) => {
     const buildForDecorator = ({ match, method, decoratorPath }) => {
       const routerName = match.groups.router;
       const functionInfo = findNextFunction(record.source, match.index + match[0].length);
-      const key = `${record.relativePath}::${routerName}`;
+      const key = routerKey(record.relativePath, routerName);
       const localRouterPrefix = record.routerPrefixes.get(routerName) ?? "";
       const prefixes = includePrefixes.get(key) ?? [""];
       for (const includePrefix of prefixes) {

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