@clue-ai/cli 0.0.6 → 0.0.8

package/README.md

@@ -16,7 +16,7 @@ clue-ai lifecycle-apply --plan clue-lifecycle-plan.json --repo .
 clue-ai setup-check --framework fastapi --backend-root-path backend --repo . --target codex --require-sdk-lifecycle
 clue-ai setup-watch --project-key <key> --environment dev --clue-api-base-url <clue-api-base-url> --watch-targets frontend:web[init,identify,set-account,event-sent]=<frontend-url>,backend:api[init,identify,set-account,logout,event-sent]=<backend-url>
 clue-ai init --request clue-init-request.json --repo .
-clue-ai semantic-ci --request clue-semantic-request.json --repo .
+clue-ai semantic-gen --request clue-semantic-request.json --repo .
 ```
 
 `/clue-init` is the standard user-facing command for Codex and Claude Code
@@ -25,7 +25,7 @@ tool request/report contract as `clue-ai init`.
 
 `clue-ai semantic-workflow` mechanically writes the GitHub Actions workflow that
 generates `.clue/semantic-request.runtime.json` only inside CI and then runs
-`clue-ai semantic-ci`. Do not commit runtime semantic request files to client
+`clue-ai semantic-gen`. Do not commit runtime semantic request files to client
 repositories.
 
 `clue-ai setup` installs the target AI-tool skills and, when backend routes are
@@ -66,22 +66,19 @@ detected service.
 
 ## Required Environment
 
-- `CLUE_API_KEY`
-- `CLUE_AI_PROVIDER`
-- `CLUE_AI_PROVIDER_API_KEY`
-- `CLUE_AI_MODEL`
+- `CLUE_API_KEY`: Clue setup screen issues this value.
+- `CLUE_AI_PROVIDER_API_KEY`: the customer's AI provider key, not a Clue key. For Codex/OpenAI, create it at `https://platform.openai.com/api-keys`. For Claude Code/Anthropic, create it at `https://console.anthropic.com/settings/keys`.
+- `CLUE_AI_PROVIDER`: generated from setup target when possible: `codex -> openai`, `claude_code -> anthropic`.
+- `CLUE_AI_MODEL`: generated with a concrete default. OpenAI examples: `gpt-5.4-mini`, `gpt-5.5`, `gpt-5.4-nano`. Anthropic examples: `claude-sonnet-4-6`, `claude-opus-4-7`, `claude-haiku-4-5-20251001`.
 
-`CLUE_AI_PROVIDER` selects the AI provider used by semantic snapshot generation and
-lifecycle implementation planning. Use `openai` for OpenAI-compatible Chat
-Completions providers and `anthropic` for Claude Messages API. `CLUE_AI_PROVIDER_API_KEY`
-must match the selected provider. `CLUE_AI_MODEL` is the selected provider's model
-name. Keep it in environment configuration so provider/model upgrades do not
-require CLI code changes.
+`clue-ai semantic-gen` runs semantic AI inside the customer repository CI with
+the customer-configured AI provider key. Clue receives only the final
+privacy-safe semantic snapshot.
 
 ## Boundaries
 
 - The tool may read allowed source paths in the client repository.
 - The tool must not read `.env`, secrets, logs, dumps, build output, or vendor directories.
-- Raw source code is sent only from the client CI runner to the configured AI provider.
-- Raw source code, raw SQL, bind values, function names, class names, file paths, and import graphs are not sent to Clue by default.
+- Semantic generation calls the configured AI provider from customer CI.
+- Raw source code, raw SQL, bind values, function names, class names, file paths, and import graphs are not sent to Clue.
 - `clue-layer.yaml` and `clue-semantic.yaml` are not committed to client repositories.

package/bin/clue-cli.mjs

@@ -15,6 +15,10 @@ import { runSetupCheck } from "../src/setup-check.mjs";
 import { runSetupDetect } from "../src/setup-detect.mjs";
 import { runSetupPrepare } from "../src/setup-prepare.mjs";
 import { installSetupSkills } from "../src/setup-tool.mjs";
+import {
+  semanticAgentSkillBundle,
+  validateSemanticAgentSkillBundle,
+} from "../src/semantic-agent-runner.mjs";
 
 const parseArgs = (argv) => {
   const [command = "help", ...tokens] = argv;
@@ -36,6 +40,15 @@ const parseArgs = (argv) => {
 
 const readJson = async (path) => JSON.parse(await readFile(path, "utf8"));
 
+const readTextIfExists = async (path) => {
+  try {
+    return await readFile(path, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") return "";
+    throw error;
+  }
+};
+
 const writeJsonIfRequested = async ({ repoRoot, outputPath, value }) => {
   if (typeof outputPath !== "string") return false;
   const resolvedRepoRoot = resolve(repoRoot);
@@ -219,6 +232,73 @@ const resolveTargetUrlFromEnv = ({ target, env }) => {
 const shouldAskQuestions = ({ flags }) =>
   !flags.has("yes") && process.stdin.isTTY && process.stdout.isTTY;
 
+const isGitignoreEntryPresent = (content, entry) =>
+  content
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .includes(entry);
+
+const appendGitignoreEntry = async ({ repoRoot, entry }) => {
+  const gitignorePath = resolve(repoRoot, ".gitignore");
+  const current = await readTextIfExists(gitignorePath);
+  if (isGitignoreEntryPresent(current, entry)) {
+    return "already_ignored";
+  }
+  const prefix = current.length > 0 && !current.endsWith("\n") ? "\n" : "";
+  await writeFile(gitignorePath, `${current}${prefix}${entry}\n`, "utf8");
+  return "added";
+};
+
+const maybeProtectEnvironmentGuide = async ({
+  repoRoot,
+  envFilePath,
+  flags,
+}) => {
+  if (typeof envFilePath !== "string" || !envFilePath.trim()) {
+    return null;
+  }
+  const gitignorePath = resolve(repoRoot, ".gitignore");
+  const current = await readTextIfExists(gitignorePath);
+  if (isGitignoreEntryPresent(current, envFilePath)) {
+    return {
+      env_file_path: envFilePath,
+      gitignore_status: "already_ignored",
+    };
+  }
+  if (flags.has("yes")) {
+    await appendGitignoreEntry({ repoRoot, entry: envFilePath });
+    return {
+      env_file_path: envFilePath,
+      gitignore_status: "added",
+    };
+  }
+  if (shouldAskQuestions({ flags })) {
+    const rl = createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+    try {
+      const answer = await rl.question(
+        `${envFilePath} は秘密情報を含みます。.gitignore に追加しますか？ [Y/n] `,
+      );
+      if (!answer.trim() || /^y(es)?$/i.test(answer.trim())) {
+        await appendGitignoreEntry({ repoRoot, entry: envFilePath });
+        return {
+          env_file_path: envFilePath,
+          gitignore_status: "added",
+        };
+      }
+    } finally {
+      rl.close();
+    }
+  }
+  return {
+    env_file_path: envFilePath,
+    gitignore_status: "not_ignored",
+    warning: `${envFilePath} contains secrets. Do not commit it.`,
+  };
+};
+
 const confirmTargetUrls = async ({ flags, watchTargets, env }) => {
   const initialTargets = watchTargets.map((target) => ({
     ...target,
@@ -670,40 +750,28 @@ const usage = () =>
     "  clue-ai setup --clue-api-key <key> --clue-api-base-url <url> --project-key <key> --environment dev",
     "  clue-ai setup-detect --repo .",
     "  clue-ai semantic-inventory --framework fastapi --backend-root-path backend --repo . --output .clue/semantic-routes.json",
+    "  clue-ai semantic-agent-skills --output .clue/semantic-agent-skills.json",
     "  clue-ai semantic-workflow --framework fastapi --backend-root-path backend --repo .",
     "  clue-ai lifecycle-apply --plan clue-lifecycle-plan.json --repo .",
     "  clue-ai setup-check --framework fastapi --backend-root-path backend --repo .",
     "  clue-ai setup-watch --local",
     "  clue-ai setup-watch --project-key <key> --environment dev --clue-api-base-url <clue-api-base-url> --watch-targets frontend:web[init,identify,set-account,logout,event-sent]=<frontend-url>,backend:api[init,identify,set-account,logout,event-sent]=<backend-url>",
     "  clue-ai init --request clue-init-request.json --repo .",
-    "  clue-ai semantic-ci --request clue-semantic-request.json --repo . [--previous-snapshot-file previous.json]",
-    "  clue-ai semantic-ci --request-env CLUE_SEMANTIC_REQUEST_JSON --repo .",
+    "  clue-ai semantic-gen --request clue-semantic-request.json --repo . [--previous-snapshot-file previous.json]",
+    "  clue-ai semantic-gen --request-env CLUE_SEMANTIC_REQUEST_JSON --repo .",
   ].join("\n");
 
 const renderEnvironmentInstructions = (instructions) => {
   if (!instructions || instructions.status !== "ready") {
     return "";
   }
-  const lines = ["", instructions.message, ""];
-  for (const block of instructions.service_env_blocks) {
-    lines.push(
-      `[${block.kind}] ${block.root_path} (${block.env_file_candidates.join(" or ")})`,
-      block.env_block,
-      "",
-    );
-  }
-  lines.push(
-    "GitHub Secrets",
-    ...instructions.ci_github.secrets.map(
-      (entry) => `${entry.name}=${entry.value}`,
-    ),
+  const lines = [
     "",
-    "GitHub Variables",
-    ...instructions.ci_github.variables.map(
-      (entry) => `${entry.name}=${entry.value}`,
-    ),
+    `環境変数の設定内容を ${instructions.env_file_path} に書き出しました。`,
+    `Step2で ${instructions.env_file_path} を開き、各サービスの env と GitHub Secrets/Variables に反映してください。`,
+    `${instructions.env_file_path} は秘密情報を含むため、コミットしないでください。`,
     "",
-  );
+  ];
   return `${lines.join("\n")}\n`;
 };
 
@@ -754,6 +822,14 @@ const main = async () => {
             environment: flags.get("environment"),
           },
         });
+    const environmentFileProtection = await maybeProtectEnvironmentGuide({
+      repoRoot,
+      envFilePath: preparation.environment_instructions?.env_file_path,
+      flags,
+    });
+    if (environmentFileProtection) {
+      preparation.environment_file_protection = environmentFileProtection;
+    }
     const environmentInstructions = renderEnvironmentInstructions(
       preparation.environment_instructions,
     );
@@ -818,6 +894,17 @@ const main = async () => {
     return;
   }
 
+  if (command === "semantic-agent-skills") {
+    const bundle = semanticAgentSkillBundle();
+    await writeJsonIfRequested({
+      repoRoot,
+      outputPath: flags.get("output"),
+      value: bundle,
+    });
+    process.stdout.write(`${JSON.stringify(bundle, null, 2)}\n`);
+    return;
+  }
+
   if (command === "lifecycle-apply") {
     const planPath = flags.get("plan");
     if (typeof planPath !== "string") {
@@ -874,18 +961,24 @@ const main = async () => {
     return;
   }
 
-  if (command === "semantic-ci") {
+  if (command === "semantic-gen") {
     const previousSnapshotPath =
       flags.get("previous-snapshot") ?? flags.get("previous-snapshot-file");
     const previousSnapshot =
       typeof previousSnapshotPath === "string"
         ? await readJson(resolve(previousSnapshotPath))
         : undefined;
+    const agentSkillsPath = flags.get("agent-skills-file");
+    const agentSkills =
+      typeof agentSkillsPath === "string"
+        ? validateSemanticAgentSkillBundle(await readJson(resolve(agentSkillsPath)))
+        : undefined;
     const result = await runSemanticCi({
       repoRoot,
       request,
       env: process.env,
       previousSnapshot,
+      agentSkills,
     });
     process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
     return;

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

@@ -14,13 +14,14 @@ Required fields:
 Required environment:
 
 - `CLUE_API_KEY`
-- `AI_PROVIDER`
-- `AI_PROVIDER_API_KEY`
+- `CLUE_AI_PROVIDER_API_KEY`
+- `CLUE_AI_PROVIDER`
 - `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.
+Semantic snapshot generation runs inside the customer repository CI with the
+customer-configured AI provider key. Clue must receive only the final
+privacy-safe semantic snapshot, not raw source code, prompts, completions, or AI
+provider keys.
 
 Behavior:
 

package/commands/codex/clue-init.md

@@ -14,13 +14,14 @@ Required fields:
 Required environment:
 
 - `CLUE_API_KEY`
-- `AI_PROVIDER`
-- `AI_PROVIDER_API_KEY`
+- `CLUE_AI_PROVIDER_API_KEY`
+- `CLUE_AI_PROVIDER`
 - `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.
+Semantic snapshot generation runs inside the customer repository CI with the
+customer-configured AI provider key. Clue must receive only the final
+privacy-safe semantic snapshot, not raw source code, prompts, completions, or AI
+provider keys.
 
 Behavior:
 

package/package.json

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

package/src/ai-provider.mjs

@@ -15,8 +15,7 @@ const normalizeProvider = (value) => {
 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;
+  const explicit = env.CLUE_AI_PROVIDER_BASE_URL || null;
   if (explicit) {
     return trimTrailingSlash(explicit);
   }
@@ -106,6 +105,7 @@ export const callJsonAiProvider = async ({
           body: JSON.stringify({
             model: config.model,
             max_tokens: 4096,
+            temperature: 0,
             system,
             messages: [{ role: "user", content: user }],
             tools: [
@@ -129,6 +129,7 @@ export const callJsonAiProvider = async ({
           },
           body: JSON.stringify({
             model: config.model,
+            temperature: 0,
             messages: [
               { role: "system", content: system },
               { role: "user", content: user },

package/src/command-spec.mjs

@@ -4,6 +4,7 @@ export const REQUIRED_SECRET_NAMES = [
   "CLUE_API_KEY",
   "CLUE_AI_PROVIDER_API_KEY",
 ];
+export const REQUIRED_VARIABLE_NAMES = ["CLUE_AI_PROVIDER", "CLUE_AI_MODEL"];
 
 export const CLUE_INIT_COMMAND_FIELDS = [
   "project_key",
@@ -22,6 +23,7 @@ export const CLUE_INIT_COMMAND = {
   report_contract: "clueInitToolReportSchema",
   required_fields: CLUE_INIT_COMMAND_FIELDS,
   required_secret_names: REQUIRED_SECRET_NAMES,
+  required_variable_names: REQUIRED_VARIABLE_NAMES,
 };
 
 export const commandSpecs = [CLUE_INIT_COMMAND];

package/src/contracts.mjs

@@ -2,7 +2,6 @@ import { createRequire } from "node:module";
 
 const require = createRequire(import.meta.url);
 const schemaPackage = require("./public-schema.cjs");
-
 const {
   clueInitToolRequestSchema,
   clueInitToolReportSchema,
@@ -63,6 +62,7 @@ export const validateInitRequest = (input) => {
 export const buildInitReport = ({
   request,
   lifecycleInsertions,
+  requiredVariables = [],
   warnings = [],
 }) =>
   parseWithSchema(
@@ -72,6 +72,7 @@ export const buildInitReport = ({
       ci_workflow_path: request.ci_workflow_path,
       ci_workflow_added: true,
       required_secrets: ["CLUE_API_KEY", "CLUE_AI_PROVIDER_API_KEY"],
+      required_variables: requiredVariables,
       lifecycle_insertions: lifecycleInsertions,
       semantic_generation_timing: "after_merge_ci",
       semantic_preview_generated: false,
@@ -89,7 +90,6 @@ 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(
@@ -139,8 +139,9 @@ export const validateSemanticCiRequest = (input) => ({
     "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"),
+  ai_provider_base_url: null,
+  ai_provider: optionalNonEmpty(input.ai_provider),
+  ai_model: optionalNonEmpty(input.ai_model),
 });
 
 export const buildOperationSourceKey = (method, pathTemplate) =>

package/src/init-tool.mjs

@@ -110,7 +110,6 @@ const workflowRequestPayload = (request) =>
       },
       service: {
         service_key: request.service_key,
-        root_path: request.allowed_source_paths[0],
         framework: request.framework,
         language: "python",
       },
@@ -118,8 +117,6 @@ const workflowRequestPayload = (request) =>
       excluded_source_paths: request.excluded_source_paths,
       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,
@@ -157,10 +154,11 @@ jobs:
           CLUE_API_KEY: \${{ secrets.CLUE_API_KEY }}
           CLUE_AI_PROVIDER_API_KEY: \${{ secrets.CLUE_AI_PROVIDER_API_KEY }}
           CLUE_AI_PROVIDER: \${{ vars.CLUE_AI_PROVIDER }}
+          CLUE_AI_MODEL: \${{ vars.CLUE_AI_MODEL }}
           CLUE_SEMANTIC_REQUEST_JSON: |
 ${indentMultiline(workflowRequestPayload(request), 12)}
         run: |
-          npx @clue-ai/cli semantic-ci --request-env CLUE_SEMANTIC_REQUEST_JSON --repo .
+          npx @clue-ai/cli semantic-gen --request-env CLUE_SEMANTIC_REQUEST_JSON --repo .
 `;
 
 export const writeSemanticWorkflow = async ({ repoRoot, request }) => {
@@ -173,6 +171,7 @@ export const writeSemanticWorkflow = async ({ repoRoot, request }) => {
     required_secrets: ["CLUE_API_KEY", "CLUE_AI_PROVIDER_API_KEY"],
     required_variables: [
       "CLUE_AI_PROVIDER",
+      "CLUE_AI_MODEL",
       ...(usesGithubVariable(
         request.project_key ?? "${{ vars.CLUE_PROJECT_KEY }}",
       )
@@ -188,7 +187,6 @@ export const writeSemanticWorkflow = async ({ repoRoot, request }) => {
       )
         ? ["CLUE_API_BASE_URL"]
         : []),
-      "CLUE_AI_MODEL",
     ],
     runtime_request_committed: false,
     semantic_generation_timing: "after_merge_ci",
@@ -204,7 +202,7 @@ export const runInitTool = async ({
   lifecyclePlanner = planLifecycleInsertions,
 }) => {
   const request = validateInitRequest(rawRequest);
-  await writeSemanticWorkflow({ repoRoot, request });
+  const workflowResult = await writeSemanticWorkflow({ repoRoot, request });
   const lifecyclePlan = await lifecyclePlanner({ repoRoot, request, env });
   const lifecycleResult = await applyLifecyclePlan({
     repoRoot,
@@ -214,6 +212,7 @@ export const runInitTool = async ({
   return buildInitReport({
     request,
     lifecycleInsertions: lifecycleResult.lifecycleInsertions,
+    requiredVariables: workflowResult.required_variables,
     warnings: [...lifecycleResult.warnings],
   });
 };

package/src/public-schema.cjs

@@ -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,