@clue-ai/cli 0.0.3 → 0.0.4

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.4",
   "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/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/semantic-ci.mjs

@@ -209,6 +209,64 @@ const callAiProvider = async ({ request, apiKey, routes }) => {
   );
 };
 
+const semanticGenerationFailureReason = (error) => {
+  if (!(error instanceof Error)) {
+    return "AI semantic generation failed for this route.";
+  }
+  const providerStatusMatch = /AI provider failed: (?<status>\d+)/.exec(
+    error.message,
+  );
+  if (providerStatusMatch?.groups?.status) {
+    return `AI semantic generation failed for this route: provider_${providerStatusMatch.groups.status}.`;
+  }
+  if (/empty semantic generation content/.test(error.message)) {
+    return "AI semantic generation returned empty content for this route.";
+  }
+  if (error instanceof SyntaxError) {
+    return "AI semantic generation returned malformed JSON for this route.";
+  }
+  return "AI semantic generation failed for this route.";
+};
+
+const unavailableAiRoute = (operationSourceKey, confidenceReason) => ({
+  operation_source_key: operationSourceKey,
+  confidence_reason: confidenceReason,
+});
+
+const generateAiRoutesPerRoute = async ({ request, apiKey, routes }) => {
+  const aiRoutes = new Map();
+  for (const route of routes) {
+    try {
+      const routeAiRoutes = await callAiProvider({
+        request,
+        apiKey,
+        routes: [route],
+      });
+      const aiRoute = routeAiRoutes.get(route.operation_source_key);
+      if (aiRoute?.semantics) {
+        aiRoutes.set(route.operation_source_key, aiRoute);
+      } else {
+        aiRoutes.set(
+          route.operation_source_key,
+          unavailableAiRoute(
+            route.operation_source_key,
+            "AI semantic generation omitted this route.",
+          ),
+        );
+      }
+    } catch (error) {
+      aiRoutes.set(
+        route.operation_source_key,
+        unavailableAiRoute(
+          route.operation_source_key,
+          semanticGenerationFailureReason(error),
+        ),
+      );
+    }
+  }
+  return aiRoutes;
+};
+
 const buildAiSelectionPrompt = (selectionCandidates) =>
   JSON.stringify({
     task: "Choose adopted semantic values from deterministic and AI candidates. Return JSON only.",
@@ -1420,7 +1478,8 @@ const buildSnapshot = ({ request, routes, aiRoutes, aiSelectionDecisions }) => {
     const baseRoute = !aiRoute?.semantics
       ? fallbackSemantics(
           routeWithVersion,
-          "AI semantics were unavailable for this route.",
+          aiRoute?.confidence_reason ??
+            "AI semantics were unavailable for this route.",
           hashScope,
         )
       : {
@@ -1799,7 +1858,7 @@ export const runSemanticCi = async ({ repoRoot, request: rawRequest, env }) => {
     ),
   }));
   const aiProviderApiKey = requireAiProviderApiKey(env);
-  const aiRoutes = await callAiProvider({
+  const aiRoutes = await generateAiRoutesPerRoute({
     request,
     apiKey: aiProviderApiKey,
     routes: promptRoutes,

package/src/setup-tool.mjs

@@ -3,6 +3,7 @@ import { join, resolve } from "node:path";
 import readline from "node:readline/promises";
 
 const SKILL_NAMES = [
+  "clue-setup-orchestrator",
   "clue-route-semantic-snapshot",
   "clue-semantic-ci",
   "clue-sdk-instrumentation",
@@ -21,13 +22,15 @@ const TARGET_SKILL_ROOTS = {
 const normalizeTarget = (target) => {
   const normalized = String(target ?? "").trim().toLowerCase().replace(/[\s-]+/g, "_");
   if (!TARGETS.has(normalized)) {
-    throw new Error("target must be codex or claude_code");
+    throw new Error("AIツールは codex または claude_code を指定してください");
   }
   return normalized;
 };
 
 const skillBody = (name) => {
   const descriptions = {
+    "clue-setup-orchestrator":
+      "Use first when running the full Clue setup so one execution agent per implementation workstream and multiple monitoring agents coordinate separate setup phases.",
     "clue-route-semantic-snapshot":
       "Use when analyzing backend routes, handlers, controllers, or endpoints to create privacy-safe Clue semantic snapshots.",
     "clue-semantic-ci":
@@ -43,19 +46,48 @@ const skillBody = (name) => {
   };
 
   const steps = {
+    "clue-setup-orchestrator": [
+      "Use one execution agent per implementation workstream.",
+      "Each execution agent owns exactly one workstream and its tests.",
+      "Required execution agents: SDK Lifecycle Execution Agent, Semantic Snapshot Execution Agent, and Semantic Snapshot CI Execution Agent.",
+      "Run execution agents in parallel only when file ownership does not conflict; otherwise run them sequentially with monitor gates between workstreams.",
+      "Use multiple monitoring agents for read-only checks, or named review passes if subagents are unavailable.",
+      "Run setup phases separately in this order: repository discovery, semantic snapshot, semantic snapshot CI, SDK lifecycle implementation, verification, final report.",
+      "Treat only semantic snapshot, semantic snapshot CI, and SDK lifecycle implementation as implementation workstreams with execution agents.",
+      "Before each workstream, read and apply the matching Clue setup skill.",
+      "After each implementation workstream, run a monitoring check with `clue-setup-audit` before continuing.",
+      "For final local verification, read and apply `clue-local-verification`.",
+      "For the final report, read and apply `clue-setup-report`.",
+      "Do not continue past P0/P1 monitoring findings until fixed or reported as blocked.",
+    ],
     "clue-route-semantic-snapshot": [
+      "Use this skill as the source of truth for semantic snapshot content and structure.",
+      "Keep semantic snapshot authoring separate from CI workflow creation and SDK lifecycle implementation.",
+      "Do not create CI workflow files or SDK lifecycle calls from this skill.",
       "Inspect only allowed source paths.",
       "Identify route, handler, controller, and endpoint behavior from privacy-safe evidence.",
+      "Create route entries with operation_source_key, method/path_template when available, route_summary, route_confidence, confidence_reason, and source_evidence_refs.",
+      "Create layer_evidence for data effects, side effects, validation, permissions, failures, and component fingerprints when available.",
+      "Create operation_effects only when target object evidence and domain behavior evidence are sufficient.",
+      "Create target_object_profiles, target_object_catalog, and target_object_mappings for accepted operation effects.",
+      "Preserve unresolved_operation_effects with missing_context instead of fabricating unknown operation effects.",
+      "Include source_evidence_refs and ai_inference_evidence without raw source, secrets, prompts, or completions.",
       "Create semantic snapshot inputs without raw source, secrets, prompts, or completions.",
       "Report unresolved routes as blockers instead of guessing.",
     ],
     "clue-semantic-ci": [
+      "Use this skill as the source of truth for semantic snapshot CI workflow format.",
+      "Keep CI workflow creation separate from semantic snapshot content authoring and SDK lifecycle implementation.",
+      "Do not author semantic snapshot content or SDK lifecycle calls from this skill.",
       "Create or update `.github/workflows/clue-semantic-snapshot.yml`.",
       "Use `npx @clue-ai/cli semantic-ci --request .clue/semantic-request.runtime.json --repo .`.",
       "Reference GitHub Secrets and Variables by name only.",
       "Do not print or commit secret values.",
     ],
     "clue-sdk-instrumentation": [
+      "Use this skill as the source of truth for Clue SDK lifecycle implementation.",
+      "Keep SDK lifecycle implementation separate from semantic snapshot and CI workflow work.",
+      "Do not create semantic snapshot content or semantic snapshot CI workflow files from this skill.",
       "Find the app/bootstrap entrypoint and add ClueInit only when the location is clear.",
       "Find login success handling and add ClueIdentify only when the user identity is available.",
       "Find account, workspace, organization, or tenant resolution and add ClueSetAccount only when the subject is available.",
@@ -63,22 +95,31 @@ const skillBody = (name) => {
       "Skip unclear lifecycle points and report blockers.",
     ],
     "clue-setup-audit": [
+      "Act as a read-only monitoring agent, not the execution agent.",
+      "Check one completed workstream at a time and report P0/P1 issues before more implementation continues.",
       "Review changed files line by line.",
+      "Verify semantic snapshot, semantic CI, and SDK lifecycle responsibilities did not bleed into each other.",
       "Reject broad ClueTrack instrumentation and DOM clue tags.",
       "Confirm no project key, API key, secret, or env value appears in diff or report.",
       "Confirm lifecycle insertions are minimal and reviewable.",
     ],
     "clue-local-verification": [
+      "Act as a read-only monitoring agent for local verification evidence.",
+      "Verify each workstream independently before the final setup report.",
       "Confirm generated skill files exist.",
       "Confirm workflow files and SDK lifecycle imports/calls exist when those phases have run.",
       "Confirm only env names are reported.",
       "Leave event delivery verification to the Clue setup screen.",
     ],
     "clue-setup-report": [
+      "Use this skill only after execution and monitoring passes are finished.",
       "Summarize changed files.",
       "List completed setup phases.",
+      "List skills used for each workstream.",
+      "List execution agent and monitoring agents, or named review passes if subagents were unavailable.",
       "List blockers with exact file or environment names when available.",
       "List required env names without values.",
+      "List P0/P1 monitoring findings and fixes.",
       "State that commit and push were not performed.",
     ],
   };
@@ -91,10 +132,19 @@ const skillBody = (name) => {
     "",
     "# Rules",
     "",
+    "- For full Clue setup, use one execution agent per implementation workstream and multiple monitoring agents for read-only checks.",
+    "- The full setup must start with `clue-setup-orchestrator`.",
+    "- Each execution agent owns exactly one workstream; monitoring agents review one workstream at a time and report P0/P1 issues.",
+    "- Do not continue past a P0/P1 monitoring finding until it is fixed or explicitly reported as blocked.",
+    "- If subagents are unavailable, run the same structure as separate named review passes and say so in the final report.",
     "- Do not expose project keys, API keys, secrets, tokens, or environment variable values.",
+    "- Do not ask the user to paste secret values.",
+    "- Do not read `.env`, `.env.*`, secret files, logs, dumps, build output, coverage output, `node_modules`, vendor directories, dependency directories, or dependency output.",
+    "- Report only environment variable names, never values.",
     "- Do not commit or push changes.",
     "- Prefer existing repository patterns and minimal diffs.",
     "- If evidence is unclear, report a blocker instead of guessing.",
+    "- Do not merge semantic snapshot, semantic CI, SDK lifecycle, audit, verification, and report responsibilities into one undifferentiated task.",
     "",
     "# Workflow",
     "",
@@ -106,7 +156,9 @@ const skillBody = (name) => {
 const askTarget = async ({ input = process.stdin, output = process.stdout } = {}) => {
   const rl = readline.createInterface({ input, output });
   try {
-    const answer = await rl.question("Use Clue setup skills for which AI tool? [codex/claude_code] ");
+    const answer = await rl.question(
+      "ClueのセットアップSkillsをどのAIツールに追加しますか？ [codex/claude_code] ",
+    );
     return normalizeTarget(answer);
   } finally {
     rl.close();