@clue-ai/cli 0.0.18 → 0.0.19

package/bin/clue-cli.mjs

@@ -20,6 +20,7 @@ import { runSemanticCi, runSemanticInventory } from "../src/semantic-ci.mjs";
 import { runSetupCheck } from "../src/setup-check.mjs";
 import { runSetupDetect } from "../src/setup-detect.mjs";
 import { runSetupDoctor } from "../src/setup-doctor.mjs";
+import { runSetupAgent } from "../src/setup-agent.mjs";
 import { buildAiSetupHelp } from "../src/setup-help.mjs";
 import { runSetupPrepare } from "../src/setup-prepare.mjs";
 import { installSetupSkills } from "../src/setup-tool.mjs";
@@ -850,6 +851,7 @@ const usage = () =>
     "Usage:",
     "  /clue-init",
     `  ${clueCliCommand("setup --clue-api-key <key> --clue-api-base-url <url> --project-key <key> --environment dev --documents-url <url>")}`,
+    `  ${clueCliCommand("setup-agent --repo . [--ai-provider openai|anthropic --ai-provider-api-key <key> --ai-model <model>]")}`,
     `  ${clueCliCommand("setup-detect --repo .")}`,
     `  ${clueCliCommand("semantic-inventory --framework fastapi --backend-root-path backend --repo .")}`,
     `  ${clueCliCommand("semantic-agent-skills --output .clue/semantic-agent-skills.json")}`,
@@ -930,6 +932,19 @@ const main = async () => {
     return;
   }
 
+  if (command === "setup-agent") {
+    const report = await runSetupAgent({
+      env: process.env,
+      flags,
+      repoRoot,
+    });
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    if (report.status === "blocked") {
+      process.exitCode = 1;
+    }
+    return;
+  }
+
   if (command === "setup") {
     const report = await installSetupSkills({
       repoRoot,

package/package.json

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

package/src/ai-provider.mjs

@@ -25,8 +25,7 @@ const providerBaseUrl = ({ provider, env = {}, request = {} }) => {
 };
 
 const providerModel = ({ env = {}, request = {} }) => {
-  const configuredModel =
-    env.CLUE_INIT_AI_MODEL || env.CLUE_AI_MODEL || request.ai_model;
+  const configuredModel = env.CLUE_AI_MODEL || request.ai_model;
   const model = String(configuredModel || "").trim();
   if (!model) {
     throw new Error("CLUE_AI_MODEL is required");
@@ -59,6 +58,27 @@ const parseOpenAiJson = async ({ response, emptyMessage }) => {
   return JSON.parse(content);
 };
 
+const parseOpenAiStrictToolJson = async ({ response, toolName, emptyMessage }) => {
+  const body = await response.json();
+  const output = Array.isArray(body?.output) ? body.output : [];
+  const functionCalls = output.flatMap((entry) => {
+    if (entry?.type === "function_call") return [entry];
+    if (Array.isArray(entry?.content)) {
+      return entry.content.filter((item) => item?.type === "function_call");
+    }
+    return [];
+  });
+  const toolCall = functionCalls.find((entry) => entry?.name === toolName);
+  const rawArguments = toolCall?.arguments ?? toolCall?.input;
+  if (typeof rawArguments === "string" && rawArguments.trim()) {
+    return JSON.parse(rawArguments);
+  }
+  if (rawArguments && typeof rawArguments === "object") {
+    return rawArguments;
+  }
+  throw new Error(emptyMessage);
+};
+
 const parseAnthropicJson = async ({ response, toolName, emptyMessage }) => {
   const body = await response.json();
   const toolUse = Array.isArray(body?.content)
@@ -84,6 +104,76 @@ const parseAnthropicJson = async ({ response, toolName, emptyMessage }) => {
   return JSON.parse(text);
 };
 
+export const callStrictToolAiProvider = async ({
+  config,
+  system,
+  user,
+  toolName,
+  toolDescription,
+  parameters,
+  failureMessage = "AI provider failed",
+  emptyMessage = "AI provider returned empty tool call",
+}) => {
+  const response =
+    config.provider === "anthropic"
+      ? await fetch(`${config.baseUrl}/messages`, {
+          method: "POST",
+          headers: {
+            "content-type": "application/json",
+            "x-api-key": config.apiKey,
+            "anthropic-version": "2023-06-01",
+          },
+          body: JSON.stringify({
+            model: config.model,
+            max_tokens: 4096,
+            temperature: 0,
+            system,
+            messages: [{ role: "user", content: user }],
+            tools: [
+              {
+                name: toolName,
+                description: toolDescription,
+                input_schema: parameters,
+              },
+            ],
+            tool_choice: { type: "tool", name: toolName },
+          }),
+        })
+      : await fetch(`${config.baseUrl}/responses`, {
+          method: "POST",
+          headers: {
+            "content-type": "application/json",
+            authorization: `Bearer ${config.apiKey}`,
+          },
+          body: JSON.stringify({
+            model: config.model,
+            input: [
+              { role: "system", content: system },
+              { role: "user", content: user },
+            ],
+            tools: [
+              {
+                type: "function",
+                name: toolName,
+                description: toolDescription,
+                strict: true,
+                parameters,
+              },
+            ],
+            tool_choice: { type: "function", name: toolName },
+            parallel_tool_calls: false,
+            temperature: 0,
+          }),
+        });
+
+  if (!response.ok) {
+    throw new Error(`${failureMessage}: ${response.status}`);
+  }
+  return config.provider === "anthropic"
+    ? parseAnthropicJson({ response, toolName, emptyMessage })
+    : parseOpenAiStrictToolJson({ response, toolName, emptyMessage });
+};
+
 export const callJsonAiProvider = async ({
   config,
   system,

package/src/fastapi-analyzer.mjs

@@ -11,6 +11,7 @@ const ROUTE_DECORATOR = new RegExp(
 const API_ROUTE_DECORATOR = /@(?<router>[A-Za-z_][A-Za-z0-9_]*)\.api_route\(\s*["'](?<path>[^"']+)["'][\s\S]*?methods\s*=\s*\[(?<methods>[^\]]+)\]/gi;
 const FUNCTION_PATTERN = /(?:async\s+def|def)\s+(?<name>[A-Za-z_][A-Za-z0-9_]*)\s*\(/g;
 const ROUTER_ASSIGNMENT = /\b(?<name>[A-Za-z_][A-Za-z0-9_]*)\s*=\s*APIRouter\s*\(/g;
+const ROUTER_ALIAS_ASSIGNMENT = /^\s*(?<alias>[A-Za-z_][A-Za-z0-9_]*)\s*=\s*(?<owner>[A-Za-z_][A-Za-z0-9_]*)\.(?<routerName>[A-Za-z_][A-Za-z0-9_]*)\s*$/gm;
 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;
@@ -214,9 +215,35 @@ const parseImports = ({ source, currentRelativePath, filesByRelativePath }) => {
 
 const routerKey = (file, routerName) => `${file}::${routerName}`;
 
-const resolveRouterTarget = ({ target, relativePath, imports }) => {
+const parseRouterAliases = ({ source, relativePath, imports }) => {
+  const aliases = new Map();
+  for (const match of source.matchAll(ROUTER_ALIAS_ASSIGNMENT)) {
+    const importedOwner = imports.get(match.groups.owner);
+    if (importedOwner?.file && !importedOwner.name) {
+      aliases.set(match.groups.alias, {
+        file: importedOwner.file,
+        name: match.groups.routerName,
+      });
+      continue;
+    }
+    aliases.set(match.groups.alias, {
+      file: relativePath,
+      name: match.groups.routerName,
+    });
+  }
+  return aliases;
+};
+
+const resolveRouterTarget = ({ target, relativePath, imports, routerAliases }) => {
   const parts = target.split(".");
   if (parts.length === 1) {
+    const aliased = routerAliases.get(target);
+    if (aliased) {
+      return {
+        file: aliased.file,
+        routerName: aliased.name,
+      };
+    }
     const imported = imports.get(target);
     return {
       file: imported?.file ?? relativePath,
@@ -236,7 +263,7 @@ const resolveRouterTarget = ({ target, relativePath, imports }) => {
   };
 };
 
-const parseIncludeRouters = ({ source, relativePath, imports }) => {
+const parseIncludeRouters = ({ source, relativePath, imports, routerAliases }) => {
   const includes = [];
   for (const match of source.matchAll(INCLUDE_ROUTER_CALL)) {
     const openParenIndex = match.index + match[0].length - 1;
@@ -249,6 +276,7 @@ const parseIncludeRouters = ({ source, relativePath, imports }) => {
       target: routerMatch.groups.router,
       relativePath,
       imports,
+      routerAliases,
     });
     includes.push({
       ownerName: match.groups.owner,
@@ -359,6 +387,11 @@ export const analyzeFastApiRoutes = async ({ repoRoot, files }) => {
       currentRelativePath: record.relativePath,
       filesByRelativePath,
     });
+    record.routerAliases = parseRouterAliases({
+      source: record.source,
+      relativePath: record.relativePath,
+      imports: record.imports,
+    });
   }
 
   const routerPrefixesByKey = new Map();
@@ -375,6 +408,7 @@ export const analyzeFastApiRoutes = async ({ repoRoot, files }) => {
       source: record.source,
       relativePath: record.relativePath,
       imports: record.imports,
+      routerAliases: record.routerAliases,
     })) {
       const parentKey = record.routerPrefixes.has(include.ownerName)
         ? routerKey(record.relativePath, include.ownerName)

package/src/lifecycle-init.mjs

@@ -1,6 +1,10 @@
 import { readFile, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
-import { callJsonAiProvider, resolveAiProviderConfig } from "./ai-provider.mjs";
+import {
+  callJsonAiProvider,
+  callStrictToolAiProvider,
+  resolveAiProviderConfig,
+} from "./ai-provider.mjs";
 import {
   extractExecutableModuleStatements,
   findLifecycleCallApiNames,
@@ -22,6 +26,13 @@ const API_NAMES = new Set([
 ]);
 
 const SOURCE_EXTENSIONS = [".py", ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"];
+const DEPENDENCY_CONTEXT_FILE_CANDIDATES = [
+  "package.json",
+  "requirements.txt",
+  "requirements-dev.txt",
+  "pyproject.toml",
+  "Pipfile",
+];
 const MAX_CONTEXT_FILES = 180;
 const MAX_FILE_CHARS = 12_000;
 const MAX_TOTAL_CHARS = 360_000;
@@ -29,6 +40,71 @@ const FRONTEND_SDK_PACKAGE = "@clue-ai/browser-sdk";
 const WRONG_FRONTEND_SDK_PACKAGES = ["clue-js-sdk", "@clue/browser-sdk"];
 const CLUE_SETUP_ADDITION_PATTERN =
   /\b(?:ClueInit|ClueIdentify|ClueSetAccount|ClueLogout|clue_init_fastapi|clue_init_django|clue-fastapi-sdk|clue-django-sdk|CLUE_[A-Z0-9_]+|browserTokenProvider|clue[-_])|@clue-ai\/browser-sdk/i;
+const LIFECYCLE_PLAN_TOOL_SCHEMA = {
+  type: "object",
+  properties: {
+    status: { type: "string", enum: ["ready", "blocked"] },
+    edits: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          file_path: { type: "string" },
+          find: { type: "string" },
+          replace: { type: "string" },
+        },
+        required: ["file_path", "find", "replace"],
+        additionalProperties: false,
+      },
+    },
+    lifecycle_insertions: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          api_name: {
+            type: "string",
+            enum: [
+              "ClueInit",
+              "ClueIdentify",
+              "ClueSetAccount",
+              "ClueLogout",
+            ],
+          },
+          file_path: { type: "string" },
+          confidence: { type: "number" },
+          reason: { type: "string" },
+        },
+        required: ["api_name", "file_path", "confidence", "reason"],
+        additionalProperties: false,
+      },
+    },
+    blockers: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          reason: { type: "string" },
+          evidence: { type: ["string", "null"] },
+        },
+        required: ["reason", "evidence"],
+        additionalProperties: false,
+      },
+    },
+    warnings: {
+      type: "array",
+      items: { type: "string" },
+    },
+  },
+  required: [
+    "status",
+    "edits",
+    "lifecycle_insertions",
+    "blockers",
+    "warnings",
+  ],
+  additionalProperties: false,
+};
 
 const nonEmpty = (value, field) => {
   if (typeof value !== "string" || value.trim() === "") {
@@ -47,6 +123,33 @@ const safeRelativePath = (repoRoot, filePath) => {
   return { absolutePath, relativePath };
 };
 
+const startsWithAllowedPath = (filePath, allowedPath) => {
+  const normalizedFilePath = filePath.replace(/\\/g, "/").replace(/^\/+/, "");
+  const normalizedAllowedPath = String(allowedPath ?? "")
+    .replace(/\\/g, "/")
+    .replace(/^\/+/, "")
+    .replace(/\/+$/, "");
+  return (
+    normalizedAllowedPath !== "" &&
+    (normalizedFilePath === normalizedAllowedPath ||
+      normalizedFilePath.startsWith(`${normalizedAllowedPath}/`))
+  );
+};
+
+const assertAllowedWritePath = ({ allowedWritePaths, filePath }) => {
+  if (!Array.isArray(allowedWritePaths) || allowedWritePaths.length === 0) {
+    return;
+  }
+  if (
+    allowedWritePaths.some((allowedPath) =>
+      startsWithAllowedPath(filePath, allowedPath),
+    )
+  ) {
+    return;
+  }
+  throw new Error(`setup-agent cannot edit outside allowed setup paths: ${filePath}`);
+};
+
 const assertApiName = (apiName) => {
   if (!API_NAMES.has(apiName)) {
     throw new Error(`unsupported lifecycle API: ${apiName}`);
@@ -458,7 +561,11 @@ const buildLifecycleEvidenceSourceMap = async ({
   return sourceByPath;
 };
 
-export const applyLifecyclePlan = async ({ repoRoot, plan: rawPlan }) => {
+export const applyLifecyclePlan = async ({
+  repoRoot,
+  plan: rawPlan,
+  allowedWritePaths,
+}) => {
   const plan = normalizePlan(rawPlan);
   if (plan.status === "blocked") {
     throw new Error(
@@ -478,6 +585,7 @@ export const applyLifecyclePlan = async ({ repoRoot, plan: rawPlan }) => {
       repoRoot,
       edit.file_path,
     );
+    assertAllowedWritePath({ allowedWritePaths, filePath: relativePath });
     assertNoForbiddenInstrumentation(edit.replace);
     const current =
       sourceByPath.get(relativePath)?.text ??
@@ -499,6 +607,10 @@ export const applyLifecyclePlan = async ({ repoRoot, plan: rawPlan }) => {
   }
   await buildLifecycleEvidenceSourceMap({ repoRoot, plan, sourceByPath });
   for (const insertion of plan.lifecycleInsertions) {
+    assertAllowedWritePath({
+      allowedWritePaths,
+      filePath: insertion.file_path,
+    });
     const source = sourceByPath.get(insertion.file_path);
     if (!source) {
       throw new Error(
@@ -520,6 +632,42 @@ export const applyLifecyclePlan = async ({ repoRoot, plan: rawPlan }) => {
   };
 };
 
+const dependencyContextCandidatePaths = (allowedSourcePaths) => [
+  ...DEPENDENCY_CONTEXT_FILE_CANDIDATES,
+  ...allowedSourcePaths.flatMap((root) => {
+    const normalized = root.replace(/\/+$/, "");
+    const roots =
+      normalized.endsWith("/src") || normalized.endsWith("/app")
+        ? [normalized, dirname(normalized)]
+        : [normalized];
+    return roots.flatMap((candidateRoot) =>
+      DEPENDENCY_CONTEXT_FILE_CANDIDATES.map((file) =>
+        join(candidateRoot, file),
+      ),
+    );
+  }),
+];
+
+const addContextFile = async ({
+  absolutePath,
+  context,
+  repoRoot,
+  totalChars,
+}) => {
+  const text = await readFile(absolutePath, "utf8");
+  const snippet = text.slice(0, MAX_FILE_CHARS);
+  const nextTotalChars = totalChars + snippet.length;
+  if (nextTotalChars > MAX_TOTAL_CHARS) {
+    return { totalChars, added: false };
+  }
+  context.push({
+    file_path: relative(resolve(repoRoot), absolutePath),
+    source: snippet,
+    truncated: text.length > snippet.length,
+  });
+  return { totalChars: nextTotalChars, added: true };
+};
+
 const readContextFiles = async ({ repoRoot, request }) => {
   const files = await listAllowedSourceFiles({
     repoRoot,
@@ -530,17 +678,38 @@ const readContextFiles = async ({ repoRoot, request }) => {
   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) {
+    const result = await addContextFile({
+      absolutePath,
+      context,
+      repoRoot,
+      totalChars,
+    });
+    totalChars = result.totalChars;
+    if (!result.added) {
       break;
     }
-    context.push({
-      file_path: relative(resolve(repoRoot), absolutePath),
-      source: snippet,
-      truncated: text.length > snippet.length,
-    });
+  }
+  const seen = new Set(context.map((entry) => entry.file_path));
+  for (const candidatePath of dependencyContextCandidatePaths(
+    request.allowed_source_paths,
+  )) {
+    const { absolutePath, relativePath } = safeRelativePath(
+      repoRoot,
+      candidatePath,
+    );
+    if (seen.has(relativePath)) continue;
+    try {
+      const result = await addContextFile({
+        absolutePath,
+        context,
+        repoRoot,
+        totalChars,
+      });
+      totalChars = result.totalChars;
+      if (result.added) seen.add(relativePath);
+    } catch (error) {
+      if (error?.code !== "ENOENT") throw error;
+    }
   }
   return context;
 };
@@ -567,8 +736,8 @@ const buildLifecyclePrompt = ({ request, files }) =>
       "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 frontend code, add or use the real @clue-ai/browser-sdk dependency. Do not invent clue-js-sdk, @clue/browser-sdk, local SDK modules, global window.Clue APIs, or dynamic imports that hide a missing SDK.",
-      "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 frontend code, add or use the real @clue-ai/browser-sdk dependency through the latest channel (@clue-ai/browser-sdk@latest). Do not invent clue-js-sdk, @clue/browser-sdk, local SDK modules, global window.Clue APIs, or dynamic imports that hide a missing SDK.",
+      "For FastAPI backends, add the unpinned clue-fastapi-sdk dependency when missing so pip resolves the latest release, import clue_init_fastapi plus ClueIdentify/ClueSetAccount/ClueLogout where needed, and initialize the SDK at FastAPI app creation.",
       "For Django backends, use clue-django-sdk only after dependency or registry verification confirms it is installable. If it cannot be verified, report a blocker instead of adding guessed imports or dependencies.",
       "For other backend frameworks, treat SDK existence as unverified unless present in dependency files or verified through package-manager/official documentation. If no backend SDK exists or verification is impossible, report a blocker instead of silently frontend-only setup.",
       "Do not add broad ClueTrack instrumentation.",
@@ -598,7 +767,7 @@ const buildLifecyclePrompt = ({ request, files }) =>
       "The backend browser token proxy must derive request origin from trusted request headers or server request metadata. Do not trust origin, projectKey, or environment from JSON/body payload fields when calling Clue with server CLUE_API_KEY.",
       "For browser token proxy code, the service key sent to Clue must be the frontend ClueInit serviceKey from the browser request, not the backend service's CLUE_SERVICE_KEY.",
       "If a backend-owned browser token endpoint is implemented, read CLUE_API_BASE_URL from the backend env block and normalize it so values with or without a trailing /api/v1 do not produce duplicate paths.",
-      "Do not add @clue-ai/browser-sdk or backend SDK dependencies with * or latest; use a concrete published version or package-manager-resolved semver range and update the repository lockfile when one exists.",
+      "Install Clue SDK dependencies through the latest channel. Frontend package managers must use @clue-ai/browser-sdk@latest; Python backend dependency declarations must not pin clue-fastapi-sdk or clue-django-sdk to a fixed version.",
       "Prefer minimal edits that engineers can review in one PR.",
       "Do not run broad formatters, import sorters, cleanup tools, or style-only edits. Whitespace-only changes are allowed only on lines directly changed for Clue SDK wiring.",
       "If a lifecycle point is unclear, skip that edit and include a warning.",
@@ -667,3 +836,45 @@ export const planLifecycleInsertions = async ({ repoRoot, request, env }) => {
     emptyMessage: "AI provider returned empty lifecycle plan",
   });
 };
+
+export const planLifecycleInsertionsStrict = async ({
+  repoRoot,
+  request,
+  env,
+  failureContext = null,
+}) => {
+  const apiKey = env.CLUE_AI_PROVIDER_API_KEY;
+  if (!apiKey) {
+    throw new Error(
+      "CLUE_AI_PROVIDER_API_KEY is required for setup-agent lifecycle planning",
+    );
+  }
+  const setupAgentEnv = {
+    ...env,
+    CLUE_AI_PROVIDER_BASE_URL: undefined,
+  };
+  const files = await readContextFiles({ repoRoot, request });
+  const prompt = JSON.parse(buildLifecyclePrompt({ request, files }));
+  const user = JSON.stringify({
+    ...prompt,
+    setup_agent_mode: {
+      execution_owner: "clue_cli",
+      model_role: "lifecycle_plan_only",
+      direct_file_writes_allowed: false,
+      setup_watch_allowed: false,
+      retry_failure_context: failureContext,
+    },
+  });
+  return callStrictToolAiProvider({
+    config: resolveAiProviderConfig({ env: setupAgentEnv, apiKey }),
+    system:
+      "You are a safe code-edit planner for Clue SDK setup. Call the provided function with a schema-valid lifecycle plan only.",
+    user,
+    toolName: "propose_clue_lifecycle_plan",
+    toolDescription:
+      "Return the exact Clue SDK lifecycle insertion plan for the local CLI to validate and apply.",
+    parameters: LIFECYCLE_PLAN_TOOL_SCHEMA,
+    failureMessage: "AI provider failed during setup-agent lifecycle planning",
+    emptyMessage: "AI provider returned empty setup-agent lifecycle plan",
+  });
+};

package/src/public-schema.cjs

@@ -185,6 +185,7 @@ const semanticSnapshotPurposeChangeStateValues = [
 const semanticSnapshotActiveSemanticSourceValues = [
     "previous_reused",
     "new_confirmed",
+    "new_unconfirmed",
     "previous_kept_pending_review",
 ];
 const targetObjectKeySchema = nonEmptyStringSchema.regex(snakeSegmentPattern, {