@clue-ai/cli 0.0.4 → 0.0.6

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

@@ -11,10 +11,16 @@ Required fields:
 - `allowed_source_paths`
 - `excluded_source_paths`
 
-Required secrets:
+Required environment:
 
 - `CLUE_API_KEY`
+- `AI_PROVIDER`
 - `AI_PROVIDER_API_KEY`
+- `CLUE_AI_MODEL`
+
+`AI_PROVIDER` must be `openai` or `anthropic`. `AI_PROVIDER_API_KEY` must be the
+API key for the selected provider. `CLUE_AI_MODEL` must be the model name for the
+selected provider.
 
 Behavior:
 

package/commands/codex/clue-init.md

@@ -11,10 +11,16 @@ Required fields:
 - `allowed_source_paths`
 - `excluded_source_paths`
 
-Required secrets:
+Required environment:
 
 - `CLUE_API_KEY`
+- `AI_PROVIDER`
 - `AI_PROVIDER_API_KEY`
+- `CLUE_AI_MODEL`
+
+`AI_PROVIDER` must be `openai` or `anthropic`. `AI_PROVIDER_API_KEY` must be the
+API key for the selected provider. `CLUE_AI_MODEL` must be the model name for the
+selected provider.
 
 Behavior:
 

package/package.json

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

package/src/ai-provider.mjs

@@ -0,0 +1,146 @@
+const SUPPORTED_AI_PROVIDERS = new Set(["openai", "anthropic"]);
+
+const normalizeProvider = (value) => {
+  const provider = String(value || "openai")
+    .trim()
+    .toLowerCase();
+  if (!SUPPORTED_AI_PROVIDERS.has(provider)) {
+    throw new Error(
+      `CLUE_AI_PROVIDER must be one of: ${Array.from(SUPPORTED_AI_PROVIDERS).join(", ")}`,
+    );
+  }
+  return provider;
+};
+
+const trimTrailingSlash = (value) => String(value).replace(/\/+$/, "");
+
+const providerBaseUrl = ({ provider, env = {}, request = {} }) => {
+  const explicit =
+    request.ai_provider_base_url || env.CLUE_AI_PROVIDER_BASE_URL || null;
+  if (explicit) {
+    return trimTrailingSlash(explicit);
+  }
+  return provider === "anthropic"
+    ? "https://api.anthropic.com/v1"
+    : "https://api.openai.com/v1";
+};
+
+const providerModel = ({ env = {}, request = {} }) => {
+  const configuredModel =
+    env.CLUE_INIT_AI_MODEL || env.CLUE_AI_MODEL || request.ai_model;
+  const model = String(configuredModel || "").trim();
+  if (!model) {
+    throw new Error("CLUE_AI_MODEL is required");
+  }
+  return model;
+};
+
+export const resolveAiProviderConfig = ({ env = {}, request = {}, apiKey }) => {
+  const provider = normalizeProvider(
+    request.ai_provider || env.CLUE_AI_PROVIDER,
+  );
+  const resolvedApiKey = apiKey || env.CLUE_AI_PROVIDER_API_KEY;
+  if (!resolvedApiKey) {
+    throw new Error("CLUE_AI_PROVIDER_API_KEY is required");
+  }
+  return {
+    provider,
+    apiKey: resolvedApiKey,
+    baseUrl: providerBaseUrl({ provider, env, request }),
+    model: providerModel({ env, request }),
+  };
+};
+
+const parseOpenAiJson = async ({ response, emptyMessage }) => {
+  const body = await response.json();
+  const content = body?.choices?.[0]?.message?.content;
+  if (typeof content !== "string" || content.trim() === "") {
+    throw new Error(emptyMessage);
+  }
+  return JSON.parse(content);
+};
+
+const parseAnthropicJson = async ({ response, toolName, emptyMessage }) => {
+  const body = await response.json();
+  const toolUse = Array.isArray(body?.content)
+    ? body.content.find(
+        (entry) => entry?.type === "tool_use" && entry.name === toolName,
+      )
+    : null;
+  if (toolUse?.input && typeof toolUse.input === "object") {
+    return toolUse.input;
+  }
+  const text = Array.isArray(body?.content)
+    ? body.content
+        .filter(
+          (entry) => entry?.type === "text" && typeof entry.text === "string",
+        )
+        .map((entry) => entry.text)
+        .join("")
+        .trim()
+    : "";
+  if (!text) {
+    throw new Error(emptyMessage);
+  }
+  return JSON.parse(text);
+};
+
+export const callJsonAiProvider = async ({
+  config,
+  system,
+  user,
+  toolName = "return_json",
+  toolDescription = "Return schema-valid JSON for this Clue task.",
+  failureMessage = "AI provider failed",
+  emptyMessage = "AI provider returned empty content",
+}) => {
+  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,
+            system,
+            messages: [{ role: "user", content: user }],
+            tools: [
+              {
+                name: toolName,
+                description: toolDescription,
+                input_schema: {
+                  type: "object",
+                  additionalProperties: true,
+                },
+              },
+            ],
+            tool_choice: { type: "tool", name: toolName },
+          }),
+        })
+      : await fetch(`${config.baseUrl}/chat/completions`, {
+          method: "POST",
+          headers: {
+            "content-type": "application/json",
+            authorization: `Bearer ${config.apiKey}`,
+          },
+          body: JSON.stringify({
+            model: config.model,
+            messages: [
+              { role: "system", content: system },
+              { role: "user", content: user },
+            ],
+            response_format: { type: "json_object" },
+          }),
+        });
+
+  if (!response.ok) {
+    throw new Error(`${failureMessage}: ${response.status}`);
+  }
+  return config.provider === "anthropic"
+    ? parseAnthropicJson({ response, toolName, emptyMessage })
+    : parseOpenAiJson({ response, emptyMessage });
+};

package/src/command-spec.mjs

@@ -2,7 +2,7 @@ export const CLUE_INIT_COMMAND_NAME = "/clue-init";
 
 export const REQUIRED_SECRET_NAMES = [
   "CLUE_API_KEY",
-  "AI_PROVIDER_API_KEY",
+  "CLUE_AI_PROVIDER_API_KEY",
 ];
 
 export const CLUE_INIT_COMMAND_FIELDS = [
@@ -55,15 +55,14 @@ const deriveServiceKeyFromBackendRootPath = (backendRootPath) => {
     .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}`);
+    throw new Error(
+      `service_key cannot be derived from backend_root_path for ${CLUE_INIT_COMMAND_NAME}`,
+    );
   }
   return normalized;
 };
 
-export const buildClueInitRequestFromCommandInput = ({
-  targetTool,
-  input,
-}) => {
+export const buildClueInitRequestFromCommandInput = ({ targetTool, input }) => {
   const backendRootPath = requireField(input, "backend_root_path");
   const serviceKey =
     typeof input?.service_key === "string" && input.service_key.trim()
@@ -85,7 +84,8 @@ export const buildClueInitRequestFromCommandInput = ({
       [],
       "excluded_source_paths",
     ),
-    ...(typeof input?.ci_workflow_path === "string" && input.ci_workflow_path.trim()
+    ...(typeof input?.ci_workflow_path === "string" &&
+    input.ci_workflow_path.trim()
       ? { ci_workflow_path: input.ci_workflow_path.trim() }
       : {}),
   };

package/src/contracts.mjs

@@ -7,6 +7,7 @@ const {
   clueInitToolRequestSchema,
   clueInitToolReportSchema,
   semanticSnapshotRequestSchema,
+  semanticSnapshotResponseSchema,
 } = schemaPackage;
 
 const formatSchemaError = (result, field) => {
@@ -47,7 +48,11 @@ const stringArray = (value, field, { min = 0 } = {}) => {
 };
 
 export const validateInitRequest = (input) => {
-  const parsed = parseWithSchema(clueInitToolRequestSchema, input, "init request");
+  const parsed = parseWithSchema(
+    clueInitToolRequestSchema,
+    input,
+    "init request",
+  );
   return {
     ...parsed,
     allowed_source_paths: [...new Set(parsed.allowed_source_paths)],
@@ -55,14 +60,18 @@ export const validateInitRequest = (input) => {
   };
 };
 
-export const buildInitReport = ({ request, lifecycleInsertions, warnings = [] }) =>
+export const buildInitReport = ({
+  request,
+  lifecycleInsertions,
+  warnings = [],
+}) =>
   parseWithSchema(
     clueInitToolReportSchema,
     {
       target_tool: request.target_tool,
       ci_workflow_path: request.ci_workflow_path,
       ci_workflow_added: true,
-      required_secrets: ["CLUE_API_KEY", "AI_PROVIDER_API_KEY"],
+      required_secrets: ["CLUE_API_KEY", "CLUE_AI_PROVIDER_API_KEY"],
       lifecycle_insertions: lifecycleInsertions,
       semantic_generation_timing: "after_merge_ci",
       semantic_preview_generated: false,
@@ -80,9 +89,13 @@ export const validateSemanticCiRequest = (input) => ({
   project_key: nonEmpty(input.project_key, "project_key"),
   environment: nonEmpty(input.environment, "environment"),
   service_key: nonEmpty(input.service_key, "service_key"),
+  ai_provider: optionalNonEmpty(input.ai_provider) ?? "openai",
   repository: {
     provider: nonEmpty(input.repository?.provider, "repository.provider"),
-    repository_id: nonEmpty(input.repository?.repository_id, "repository.repository_id"),
+    repository_id: nonEmpty(
+      input.repository?.repository_id,
+      "repository.repository_id",
+    ),
     ...(optionalNonEmpty(input.repository?.owner)
       ? { owner: optionalNonEmpty(input.repository.owner) }
       : {}),
@@ -92,11 +105,15 @@ export const validateSemanticCiRequest = (input) => ({
     ...(optionalNonEmpty(input.repository?.default_branch)
       ? { default_branch: optionalNonEmpty(input.repository.default_branch) }
       : {}),
-    merge_commit: nonEmpty(input.repository?.merge_commit, "repository.merge_commit"),
+    merge_commit: nonEmpty(
+      input.repository?.merge_commit,
+      "repository.merge_commit",
+    ),
     ...(optionalNonEmpty(input.repository?.merged_at)
       ? { merged_at: optionalNonEmpty(input.repository.merged_at) }
       : {}),
-    ...(input.repository?.pull_request_number === undefined || input.repository?.pull_request_number === null
+    ...(input.repository?.pull_request_number === undefined ||
+    input.repository?.pull_request_number === null
       ? {}
       : { pull_request_number: input.repository.pull_request_number }),
     ...(optionalNonEmpty(input.repository?.workflow_run_id)
@@ -104,21 +121,43 @@ export const validateSemanticCiRequest = (input) => ({
       : {}),
   },
   service: {
-    service_key: nonEmpty(input.service?.service_key ?? input.service_key, "service.service_key"),
+    service_key: nonEmpty(
+      input.service?.service_key ?? input.service_key,
+      "service.service_key",
+    ),
     root_path: input.service?.root_path ?? null,
     framework: input.service?.framework ?? "fastapi",
     language: input.service?.language ?? "python",
   },
-	  allowed_source_paths: stringArray(input.allowed_source_paths, "allowed_source_paths", { min: 1 }),
-	  excluded_source_paths: stringArray(input.excluded_source_paths ?? [], "excluded_source_paths"),
-	  clue_api_base_url: nonEmpty(input.clue_api_base_url, "clue_api_base_url"),
-	  ai_provider_base_url: optionalNonEmpty(input.ai_provider_base_url) ?? "https://api.openai.com/v1",
-	  ai_model: optionalNonEmpty(input.ai_model) ?? "gpt-5.4-mini",
-	});
+  allowed_source_paths: stringArray(
+    input.allowed_source_paths,
+    "allowed_source_paths",
+    { min: 1 },
+  ),
+  excluded_source_paths: stringArray(
+    input.excluded_source_paths ?? [],
+    "excluded_source_paths",
+  ),
+  clue_api_base_url: nonEmpty(input.clue_api_base_url, "clue_api_base_url"),
+  ai_provider_base_url: optionalNonEmpty(input.ai_provider_base_url) ?? null,
+  ai_model: nonEmpty(input.ai_model, "ai_model"),
+});
 
 export const buildOperationSourceKey = (method, pathTemplate) =>
   `route.${method.toUpperCase()}.${pathTemplate}`;
 
 export const validateSemanticSnapshotRequest = (input) => {
-  return parseWithSchema(semanticSnapshotRequestSchema, input, "semantic snapshot");
+  return parseWithSchema(
+    semanticSnapshotRequestSchema,
+    input,
+    "semantic snapshot",
+  );
+};
+
+export const validateSemanticSnapshotResponse = (input) => {
+  return parseWithSchema(
+    semanticSnapshotResponseSchema,
+    input,
+    "semantic snapshot response",
+  );
 };

package/src/init-tool.mjs

@@ -1,20 +1,110 @@
 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);
+  const projectKey =
+    typeof flags.projectKey === "string" && flags.projectKey.trim()
+      ? flags.projectKey.trim()
+      : "${{ vars.CLUE_PROJECT_KEY }}";
+  const environment =
+    typeof flags.environment === "string" && flags.environment.trim()
+      ? flags.environment.trim()
+      : "${{ vars.CLUE_ENVIRONMENT }}";
+  const clueApiBaseUrl =
+    typeof flags.clueApiBaseUrl === "string" && flags.clueApiBaseUrl.trim()
+      ? flags.clueApiBaseUrl.trim()
+      : "${{ vars.CLUE_API_BASE_URL }}";
+  return {
+    project_key: projectKey,
+    environment,
+    clue_api_base_url: clueApiBaseUrl,
+    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 usesGithubVariable = (value) =>
+  typeof value === "string" && value.includes("${{ vars.");
 
 const workflowRequestPayload = (request) =>
   JSON.stringify(
     {
-      project_key: "${{ vars.CLUE_PROJECT_KEY }}",
-      environment: "${{ vars.CLUE_ENVIRONMENT }}",
+      project_key: request.project_key ?? "${{ vars.CLUE_PROJECT_KEY }}",
+      environment: request.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 }}",
       },
@@ -26,40 +116,87 @@ const workflowRequestPayload = (request) =>
       },
       allowed_source_paths: request.allowed_source_paths,
       excluded_source_paths: request.excluded_source_paths,
-      clue_api_base_url: "${{ vars.CLUE_API_BASE_URL }}",
+      clue_api_base_url:
+        request.clue_api_base_url ?? "${{ vars.CLUE_API_BASE_URL }}",
+      ai_provider: "${{ vars.CLUE_AI_PROVIDER }}",
       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_AI_PROVIDER_API_KEY: \${{ secrets.CLUE_AI_PROVIDER_API_KEY }}
+          CLUE_AI_PROVIDER: \${{ vars.CLUE_AI_PROVIDER }}
+          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", "CLUE_AI_PROVIDER_API_KEY"],
+    required_variables: [
+      "CLUE_AI_PROVIDER",
+      ...(usesGithubVariable(
+        request.project_key ?? "${{ vars.CLUE_PROJECT_KEY }}",
+      )
+        ? ["CLUE_PROJECT_KEY"]
+        : []),
+      ...(usesGithubVariable(
+        request.environment ?? "${{ vars.CLUE_ENVIRONMENT }}",
+      )
+        ? ["CLUE_ENVIRONMENT"]
+        : []),
+      ...(usesGithubVariable(
+        request.clue_api_base_url ?? "${{ vars.CLUE_API_BASE_URL }}",
+      )
+        ? ["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,
@@ -67,9 +204,7 @@ export const runInitTool = async ({
   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");
+  await writeSemanticWorkflow({ repoRoot, request });
   const lifecyclePlan = await lifecyclePlanner({ repoRoot, request, env });
   const lifecycleResult = await applyLifecyclePlan({
     repoRoot,
@@ -79,8 +214,6 @@ export const runInitTool = async ({
   return buildInitReport({
     request,
     lifecycleInsertions: lifecycleResult.lifecycleInsertions,
-    warnings: [
-      ...lifecycleResult.warnings,
-    ],
+    warnings: [...lifecycleResult.warnings],
   });
 };