@clue-ai/cli 0.0.9 → 0.0.11

package/README.md

@@ -6,52 +6,63 @@ The Clue product repository keeps SDKs, shared schemas, and API contracts. Tool
 
 ## Commands
 
+The public npm package is `@clue-ai/cli`. The binary exposed by that package is
+`clue-ai`, but first-run setup should not assume a global `clue-ai` install.
+Use `npx -y @clue-ai/cli <command>` unless `.clue/setup-manifest.json`
+explicitly provides a different invocation.
+
 ```bash
 /clue-init
-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-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 . --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-gen --request clue-semantic-request.json --repo .
+npx -y @clue-ai/cli setup --clue-api-key <key> --clue-api-base-url <url> --project-key <key> --environment dev
+npx -y @clue-ai/cli setup-detect --repo .
+npx -y @clue-ai/cli semantic-inventory --framework fastapi --backend-root-path backend --repo .
+npx -y @clue-ai/cli semantic-workflow --framework fastapi --backend-root-path backend --repo .
+npx -y @clue-ai/cli lifecycle-apply --plan clue-lifecycle-plan.json --repo .
+npx -y @clue-ai/cli setup-check --framework fastapi --backend-root-path backend --repo . --target codex --require-sdk-lifecycle
+npx -y @clue-ai/cli 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>
+npx -y @clue-ai/cli init --request clue-init-request.json --repo .
+npx -y @clue-ai/cli semantic-gen --request clue-semantic-request.json --repo .
 ```
 
 `/clue-init` is the standard user-facing command for Codex and Claude Code
 wrappers. The command collects structured setup inputs and invokes the same
 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-gen`. Do not commit runtime semantic request files to client
-repositories.
+`npx -y @clue-ai/cli semantic-workflow` mechanically writes the GitHub Actions workflow that
+passes the semantic generation request through `CLUE_SEMANTIC_REQUEST_JSON` at
+CI runtime and then runs `npx -y @clue-ai/cli 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
+`npx -y @clue-ai/cli setup` installs the target AI-tool skills and, when backend routes are
 detectable, also runs the machine-owned setup preparation:
 
 - detects the FastAPI backend root
-- writes `.clue/semantic-routes.json`
 - writes `.github/workflows/clue-semantic-snapshot.yml`
 - writes `.clue/setup-manifest.json`
+- writes `.env.clue` when environment guidance is ready, after protecting it in `.gitignore`
 
-The AI prompt should use those generated artifacts as inputs and should not
-hand-edit route inventory or semantic CI workflow files.
+Route inventory is computed mechanically on demand and returned in stdout; it is
+not written to `.clue/semantic-routes.json`. The AI prompt should use generated
+manifest/workflow artifacts as inputs and should not hand-edit route inventory
+or semantic CI workflow files.
 
-`clue-ai setup-detect` mechanically detects FastAPI route candidates and returns
+`npx -y @clue-ai/cli setup-detect` mechanically detects FastAPI route candidates and returns
 the framework, backend root path, service key candidate, route files, and route
 count before any AI interpretation.
 
-`clue-ai lifecycle-apply` mechanically applies an AI-produced exact replacement
-plan after validating edit paths, lifecycle API names, no broad tracking, and no
-DOM clue tags.
+`npx -y @clue-ai/cli lifecycle-apply` mechanically applies an AI-produced exact replacement
+plan after validating edit paths, lifecycle API names, blocked-plan status,
+canonical SDK usage, no broad tracking, no DOM clue tags, and claimed lifecycle
+insertion evidence.
 
-`clue-ai setup-check` mechanically verifies installed setup skills, route
+`npx -y @clue-ai/cli setup-check` mechanically verifies installed setup skills, route
 inventory, semantic workflow shape, runtime request absence, obvious secret
-leaks, and SDK lifecycle presence when requested.
+leaks, and SDK lifecycle presence when requested. With
+`--require-sdk-lifecycle`, a passing result is still static only; dependency
+installation, SDK imports in the target environments, app startup, and event
+delivery remain required before setup can be called complete.
 
-`clue-ai setup-watch` polls the Clue API setup-check endpoint while you operate
+`npx -y @clue-ai/cli setup-watch` polls the Clue API setup-check endpoint while you operate
 the local service. `--clue-api-base-url` is the Clue API URL, not the customer
 frontend URL. Use `--watch-targets` to list every local frontend/backend app by
 service key and the lifecycle checks expected for that service, for example
@@ -59,7 +70,7 @@ service key and the lifecycle checks expected for that service, for example
 Do not assume localhost ports; use the actual URLs printed by the repository's
 dev scripts or configured in its local env.
 
-`clue-ai setup` reads Clue values from the setup screen flags, detects local
+`npx -y @clue-ai/cli setup` reads Clue values from the setup screen flags, detects local
 services, writes `.clue/setup-manifest.json`, and prints service-specific env
 blocks. Do not hand-write `CLUE_SERVICE_KEY`; use the value printed for each
 detected service.
@@ -71,7 +82,7 @@ detected service.
 - `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 semantic-gen` runs semantic AI inside the customer repository CI with
+`npx -y @clue-ai/cli 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.
 

package/bin/clue-cli.mjs

@@ -4,6 +4,12 @@ import { createInterface } from "node:readline/promises";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, relative, resolve } from "node:path";
 import { commandSpecs } from "../src/command-spec.mjs";
+import {
+  CLUE_CLI_BINARY_NAME,
+  CLUE_CLI_PACKAGE_NAME,
+  CLUE_CLI_RECOMMENDED_PREFIX,
+  clueCliCommand,
+} from "../src/cli-invocation.mjs";
 import {
   buildSemanticWorkflowRequestFromFlags,
   runInitTool,
@@ -13,6 +19,7 @@ import { applyLifecyclePlan } from "../src/lifecycle-init.mjs";
 import { runSemanticCi, runSemanticInventory } from "../src/semantic-ci.mjs";
 import { runSetupCheck } from "../src/setup-check.mjs";
 import { runSetupDetect } from "../src/setup-detect.mjs";
+import { buildAiSetupHelp } from "../src/setup-help.mjs";
 import { runSetupPrepare } from "../src/setup-prepare.mjs";
 import { installSetupSkills } from "../src/setup-tool.mjs";
 import {
@@ -40,6 +47,13 @@ const parseArgs = (argv) => {
 
 const readJson = async (path) => JSON.parse(await readFile(path, "utf8"));
 
+const readPackageVersion = async () => {
+  const packageJson = JSON.parse(
+    await readFile(new URL("../package.json", import.meta.url), "utf8"),
+  );
+  return String(packageJson.version);
+};
+
 const readTextIfExists = async (path) => {
   try {
     return await readFile(path, "utf8");
@@ -212,6 +226,15 @@ const readSetupManifest = async ({ repoRoot, manifestPath }) => {
   return readJson(resolvedPath);
 };
 
+const readSetupManifestIfPresent = async ({ repoRoot, manifestPath }) => {
+  try {
+    return await readSetupManifest({ repoRoot, manifestPath });
+  } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw error;
+  }
+};
+
 const manifestWatchTargets = (manifest) => {
   const targets = manifest?.lifecycle_verification?.watch_targets;
   if (!Array.isArray(targets) || targets.length === 0) {
@@ -265,37 +288,10 @@ const maybeProtectEnvironmentGuide = async ({
       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();
-    }
-  }
+  await appendGitignoreEntry({ repoRoot, entry: envFilePath });
   return {
     env_file_path: envFilePath,
-    gitignore_status: "not_ignored",
-    warning: `${envFilePath} contains secrets. Do not commit it.`,
+    gitignore_status: "added",
   };
 };
 
@@ -338,12 +334,12 @@ const buildWatchProducerIds = ({ explicitProducerIds, watchTargets }) =>
   ]);
 
 const checkTargetUrl = async (url) => {
-  if (!url) return { checked: false, reachable: true, status: null };
+  if (!url) return { checked: true, reachable: false, status: null };
   try {
     const response = await fetch(url, { method: "GET" });
     return {
       checked: true,
-      reachable: response.status < 500,
+      reachable: response.status >= 200 && response.status < 400,
       status: response.status,
     };
   } catch {
@@ -551,7 +547,7 @@ const renderWatchTargets = (targetChecks) =>
   targetChecks
     .map((target) => {
       const urlStatus = target.urlChecked
-        ? ` url:${target.urlReachable ? target.urlStatus : "unreachable"}`
+        ? ` url:${target.urlReachable ? target.urlStatus : (target.urlStatus ?? "unreachable")}`
         : "";
       const lifecycle = target.expectedLifecycle
         .map(
@@ -595,9 +591,7 @@ const runSetupWatch = async ({ flags, repoRoot = ".", env = process.env }) => {
   const manifestPath = String(
     flags.get("manifest") || DEFAULT_SETUP_MANIFEST_PATH,
   );
-  const manifest = localMode
-    ? await readSetupManifest({ repoRoot, manifestPath })
-    : null;
+  const manifest = await readSetupManifestIfPresent({ repoRoot, manifestPath });
   if (localMode && manifest?.status !== "ready_for_ai") {
     throw new Error(
       `setup-watch --local requires a ready setup manifest at ${manifestPath}`,
@@ -640,6 +634,11 @@ const runSetupWatch = async ({ flags, repoRoot = ".", env = process.env }) => {
         : manifestWatchTargets(manifest),
     env,
   });
+  if (!localMode && watchTargets.length === 0) {
+    throw new Error(
+      "setup-watch requires --watch-targets or .clue/setup-manifest.json lifecycle_verification.watch_targets before setup can be treated as verified",
+    );
+  }
   const producerIds = buildWatchProducerIds({
     explicitProducerIds: flags.get("producer-ids"),
     watchTargets,
@@ -745,20 +744,30 @@ const runSetupWatch = async ({ flags, repoRoot = ".", env = process.env }) => {
 
 const usage = () =>
   [
+    "Clue CLI:",
+    `  npm package: ${CLUE_CLI_PACKAGE_NAME}`,
+    `  binary: ${CLUE_CLI_BINARY_NAME}`,
+    `  first-run invocation: ${CLUE_CLI_RECOMMENDED_PREFIX} <command>`,
+    `  global ${CLUE_CLI_BINARY_NAME} installation is not required`,
+    `  AI setup help: ${clueCliCommand("help --json")}`,
+    "",
     "Usage:",
     "  /clue-init",
-    "  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-gen --request clue-semantic-request.json --repo . [--previous-snapshot-file previous.json]",
-    "  clue-ai semantic-gen --request-env CLUE_SEMANTIC_REQUEST_JSON --repo .",
+    `  ${clueCliCommand("setup --clue-api-key <key> --clue-api-base-url <url> --project-key <key> --environment dev")}`,
+    `  ${clueCliCommand("setup-detect --repo .")}`,
+    `  ${clueCliCommand("semantic-inventory --framework fastapi --backend-root-path backend --repo .")}`,
+    `  ${clueCliCommand("semantic-agent-skills --output .clue/semantic-agent-skills.json")}`,
+    `  ${clueCliCommand("semantic-workflow --framework fastapi --backend-root-path backend --repo .")}`,
+    `  ${clueCliCommand("lifecycle-apply --plan clue-lifecycle-plan.json --repo .")}`,
+    `  ${clueCliCommand("setup-check --framework fastapi --backend-root-path backend --repo . --target codex")}`,
+    `  ${clueCliCommand("init --request clue-init-request.json --repo .")}`,
+    `  ${clueCliCommand("semantic-gen --request clue-semantic-request.json --repo . [--previous-snapshot-file previous.json]")}`,
+    `  ${clueCliCommand("semantic-gen --request-env CLUE_SEMANTIC_REQUEST_JSON --repo .")}`,
+    "",
+    "User-operated verification:",
+    `  ${clueCliCommand("setup-watch --local")}`,
+    `  ${clueCliCommand("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>")}`,
+    "  setup-watch is for the user running real local services; AI implementation agents must not run it automatically.",
   ].join("\n");
 
 const renderEnvironmentInstructions = (instructions) => {
@@ -777,7 +786,24 @@ const renderEnvironmentInstructions = (instructions) => {
 
 const main = async () => {
   const { command, flags } = parseArgs(process.argv.slice(2));
-  if (command === "help" || flags.has("help")) {
+  if (
+    command === "version" ||
+    command === "--version" ||
+    flags.has("version")
+  ) {
+    process.stdout.write(`${await readPackageVersion()}\n`);
+    return;
+  }
+
+  if (
+    (command === "help" || command === "--help" || flags.has("help")) &&
+    flags.has("json")
+  ) {
+    process.stdout.write(`${JSON.stringify(buildAiSetupHelp(), null, 2)}\n`);
+    return;
+  }
+
+  if (command === "help" || command === "--help" || flags.has("help")) {
     process.stdout.write(`${usage()}\n`);
     return;
   }
@@ -806,6 +832,13 @@ const main = async () => {
           ? flags.get("target")
           : undefined,
     });
+    const preEnvironmentFileProtection = flags.has("skills-only")
+      ? null
+      : await maybeProtectEnvironmentGuide({
+          repoRoot,
+          envFilePath: ".env.clue",
+          flags,
+        });
     const preparation = flags.has("skills-only")
       ? {
           status: "skipped",
@@ -822,11 +855,15 @@ const main = async () => {
             environment: flags.get("environment"),
           },
         });
-    const environmentFileProtection = await maybeProtectEnvironmentGuide({
-      repoRoot,
-      envFilePath: preparation.environment_instructions?.env_file_path,
-      flags,
-    });
+    const environmentFileProtection =
+      preEnvironmentFileProtection?.env_file_path ===
+      preparation.environment_instructions?.env_file_path
+        ? preEnvironmentFileProtection
+        : await maybeProtectEnvironmentGuide({
+            repoRoot,
+            envFilePath: preparation.environment_instructions?.env_file_path,
+            flags,
+          });
     if (environmentFileProtection) {
       preparation.environment_file_protection = environmentFileProtection;
     }
@@ -971,7 +1008,9 @@ const main = async () => {
     const agentSkillsPath = flags.get("agent-skills-file");
     const agentSkills =
       typeof agentSkillsPath === "string"
-        ? validateSemanticAgentSkillBundle(await readJson(resolve(agentSkillsPath)))
+        ? validateSemanticAgentSkillBundle(
+            await readJson(resolve(agentSkillsPath)),
+          )
         : undefined;
     const result = await runSemanticCi({
       repoRoot,

package/package.json

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

package/src/cli-invocation.mjs

@@ -0,0 +1,34 @@
+export const CLUE_CLI_PACKAGE_NAME = "@clue-ai/cli";
+export const CLUE_CLI_BINARY_NAME = "clue-ai";
+export const CLUE_CLI_RECOMMENDED_PREFIX = `npx -y ${CLUE_CLI_PACKAGE_NAME}`;
+export const CLUE_CLI_LEGACY_NPX_PREFIX = `npx ${CLUE_CLI_PACKAGE_NAME}`;
+
+export const CLUE_CLI_INVOCATION_CONTRACT = {
+  package_name: CLUE_CLI_PACKAGE_NAME,
+  binary_name: CLUE_CLI_BINARY_NAME,
+  recommended_prefix: CLUE_CLI_RECOMMENDED_PREFIX,
+  global_binary_required: false,
+  version_check_command: `${CLUE_CLI_RECOMMENDED_PREFIX} --version`,
+  help_command: `${CLUE_CLI_RECOMMENDED_PREFIX} --help`,
+  ai_help_command: `${CLUE_CLI_RECOMMENDED_PREFIX} help --json`,
+  rule: "Use the recommended_prefix for Clue CLI commands. Do not discover or require a global clue-ai binary; missing global clue-ai is normal. For AI setup scope and responsibility rules, run ai_help_command.",
+};
+
+export const clueCliCommand = (args) =>
+  `${CLUE_CLI_RECOMMENDED_PREFIX} ${args}`;
+
+export const SEMANTIC_GEN_WORKFLOW_COMMAND = clueCliCommand(
+  "semantic-gen --request-env CLUE_SEMANTIC_REQUEST_JSON --repo .",
+);
+
+export const LEGACY_SEMANTIC_GEN_WORKFLOW_COMMAND = `${CLUE_CLI_LEGACY_NPX_PREFIX} semantic-gen --request-env CLUE_SEMANTIC_REQUEST_JSON --repo .`;
+
+export const SEMANTIC_GEN_WORKFLOW_COMPATIBLE_COMMANDS = [
+  SEMANTIC_GEN_WORKFLOW_COMMAND,
+  LEGACY_SEMANTIC_GEN_WORKFLOW_COMMAND,
+];
+
+export const workflowHasCompatibleSemanticGenCommand = (workflow) =>
+  SEMANTIC_GEN_WORKFLOW_COMPATIBLE_COMMANDS.some((command) =>
+    workflow.includes(command),
+  );

package/src/command-spec.mjs

@@ -1,3 +1,5 @@
+import { CLUE_CLI_INVOCATION_CONTRACT } from "./cli-invocation.mjs";
+
 export const CLUE_INIT_COMMAND_NAME = "/clue-init";
 
 export const REQUIRED_SECRET_NAMES = [
@@ -24,6 +26,7 @@ export const CLUE_INIT_COMMAND = {
   required_fields: CLUE_INIT_COMMAND_FIELDS,
   required_secret_names: REQUIRED_SECRET_NAMES,
   required_variable_names: REQUIRED_VARIABLE_NAMES,
+  cli_invocation: CLUE_CLI_INVOCATION_CONTRACT,
 };
 
 export const commandSpecs = [CLUE_INIT_COMMAND];

package/src/init-tool.mjs

@@ -1,6 +1,7 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { buildInitReport, validateInitRequest } from "./contracts.mjs";
+import { SEMANTIC_GEN_WORKFLOW_COMMAND } from "./cli-invocation.mjs";
 import {
   applyLifecyclePlan,
   planLifecycleInsertions,
@@ -158,7 +159,7 @@ jobs:
           CLUE_SEMANTIC_REQUEST_JSON: |
 ${indentMultiline(workflowRequestPayload(request), 12)}
         run: |
-          npx @clue-ai/cli semantic-gen --request-env CLUE_SEMANTIC_REQUEST_JSON --repo .
+          ${SEMANTIC_GEN_WORKFLOW_COMMAND}
 `;
 
 export const writeSemanticWorkflow = async ({ repoRoot, request }) => {