@clue-ai/cli 0.0.9 → 0.0.11

package/src/setup-help.mjs

@@ -0,0 +1,69 @@
+import {
+  CLUE_CLI_INVOCATION_CONTRACT,
+  clueCliCommand,
+} from "./cli-invocation.mjs";
+
+export const AI_SETUP_HELP_VERSION = "2026-05-10.lifecycle-placement-only.v1";
+
+export const buildAiSetupHelp = () => ({
+  name: "@clue-ai/cli AI setup help",
+  version: AI_SETUP_HELP_VERSION,
+  purpose:
+    "Machine-readable Clue setup contract for AI coding agents. Use this before editing a customer repository for Clue setup.",
+  cli_invocation: CLUE_CLI_INVOCATION_CONTRACT,
+  setup_execution_contract: {
+    agent_primary_task:
+      "Decide where to place ClueInit, ClueIdentify, ClueSetAccount, and ClueLogout in existing repository lifecycle boundaries, then apply only those minimal Clue SDK wiring changes.",
+    implementation_workstreams: ["sdk_lifecycle_placement"],
+    lifecycle_apis_in_scope: [
+      "ClueInit",
+      "ClueIdentify",
+      "ClueSetAccount",
+      "ClueLogout",
+    ],
+    lifecycle_apis_out_of_scope_by_default: ["ClueTrack"],
+    allowed_change_scope: {
+      rule: "Only changes required to place ClueInit, ClueIdentify, ClueSetAccount, and ClueLogout are allowed.",
+      allowed: [
+        "Clue SDK dependency declarations and lockfile changes needed to install those SDKs",
+        "Clue SDK imports, bootstrap adapters, and single initialization points",
+        "backend-owned browser token endpoints required so frontend SDK code never exposes CLUE_API_KEY",
+        "Clue lifecycle calls at existing clear login, logout, account, workspace, organization, or tenant boundaries",
+        "tests or verification scripts directly proving the four lifecycle API placement decisions",
+      ],
+      forbidden: [
+        "ClueTrack instrumentation unless the user explicitly requested product event tracking",
+        "semantic snapshot implementation or CI workflow edits during lifecycle placement",
+        "unrelated refactors, renames, file moves, formatting churn, or broad cleanup",
+        "business logic changes that are not required for Clue setup",
+        "auth/session flow rewrites beyond the minimal Clue hook insertion point",
+        "UI layout, styling, copy, or navigation changes unrelated to Clue setup",
+        "dependency upgrades unrelated to Clue SDK installability",
+        "hand-authored semantic snapshot artifacts or runtime request files",
+      ],
+    },
+    setup_watch: {
+      owner: "user",
+      ai_agent_must_run: false,
+      command: clueCliCommand("setup-watch --local"),
+      rule: "Do not run setup-watch during implementation. setup-watch and the Clue setup screen require user-operated local services and real login/logout/account flows.",
+      ai_agent_responsibility:
+        "Report the command and required user verification as pending when it was not run by the user.",
+    },
+    completion_boundary: {
+      ai_may_claim: [
+        "Clue setup code changes were applied",
+        "static setup-check passed",
+        "SDK dependency install/import/build/typecheck checks passed when actually run",
+      ],
+      ai_must_not_claim: [
+        "setup completed",
+        "event delivery verified",
+        "setup-watch passed",
+        "Clue setup screen verification passed",
+      ],
+      final_status_when_setup_watch_not_user_verified:
+        "user_verification_pending",
+    },
+  },
+});

package/src/setup-prepare.mjs

@@ -4,6 +4,10 @@ import {
   buildSemanticWorkflowRequestFromFlags,
   writeSemanticWorkflow,
 } from "./init-tool.mjs";
+import {
+  CLUE_CLI_INVOCATION_CONTRACT,
+  clueCliCommand,
+} from "./cli-invocation.mjs";
 import { runSetupDetect } from "./setup-detect.mjs";
 
 const DEFAULT_SETUP_MANIFEST_PATH = ".clue/setup-manifest.json";
@@ -169,6 +173,9 @@ const buildServiceEnvBlock = ({ target, setupContext }) => {
       name: "CLUE_INGEST_ENDPOINT",
       value: buildEndpoint(setupContext.clue_api_base_url, ingestPath),
     },
+    ...(target.kind === "backend"
+      ? [{ name: "CLUE_API_BASE_URL", value: setupContext.clue_api_base_url }]
+      : []),
     { name: "CLUE_PROJECT_KEY", value: setupContext.project_key },
     { name: "CLUE_ENVIRONMENT", value: setupContext.environment },
     { name: "CLUE_SERVICE_KEY", value: target.service_key },
@@ -222,6 +229,9 @@ const buildEnvironmentInstructions = ({ manifest, setupContext }) => {
         },
       ],
       variables: [
+        { name: "CLUE_PROJECT_KEY", value: setupContext.project_key },
+        { name: "CLUE_ENVIRONMENT", value: setupContext.environment },
+        { name: "CLUE_API_BASE_URL", value: setupContext.clue_api_base_url },
         {
           name: "CLUE_AI_PROVIDER",
           value: aiProviderGuide.provider,
@@ -282,8 +292,7 @@ const summarizeEnvironmentInstructions = (instructions) => {
   return {
     status: "ready",
     env_file_path: instructions.env_file_path,
-    message:
-      `${instructions.env_file_path} を開き、各サービスの env と GitHub Secrets に反映してください。`,
+    message: `${instructions.env_file_path} を開き、各サービスの env と GitHub Secrets に反映してください。`,
     service_env_block_count: instructions.service_env_blocks.length,
     github_secret_names: instructions.ci_github.secrets.map(
       (entry) => entry.name,
@@ -326,8 +335,18 @@ export const runSetupPrepare = async ({
       ai_next_scope: "blocked_until_backend_routes_are_detected",
       machine_owned_artifacts: [],
       ai_owned_workstreams: [
-        "sdk_lifecycle_implementation_after_blockers_are_resolved",
+        "sdk_lifecycle_placement_after_blockers_are_resolved",
       ],
+      ai_implementation_scope: {
+        rule: "AI implementation is limited to placing ClueInit, ClueIdentify, ClueSetAccount, and ClueLogout in existing lifecycle boundaries after blockers are resolved.",
+        lifecycle_apis: [
+          "ClueInit",
+          "ClueIdentify",
+          "ClueSetAccount",
+          "ClueLogout",
+        ],
+        out_of_scope_by_default: ["ClueTrack"],
+      },
     };
     await writeJson({
       repoRoot: resolvedRepoRoot,
@@ -340,8 +359,9 @@ export const runSetupPrepare = async ({
     });
     return {
       ...manifest,
-      environment_instructions:
-        summarizeEnvironmentInstructions(environmentInstructions),
+      environment_instructions: summarizeEnvironmentInstructions(
+        environmentInstructions,
+      ),
     };
   }
 
@@ -349,9 +369,6 @@ export const runSetupPrepare = async ({
     framework: candidate.framework,
     backendRootPath: candidate.backend_root_path,
     serviceKey: candidate.service_key,
-    projectKey: setupContext.project_key,
-    environment: setupContext.environment,
-    clueApiBaseUrl: setupContext.clue_api_base_url,
   });
   const workflow = await writeSemanticWorkflow({
     repoRoot: resolvedRepoRoot,
@@ -373,6 +390,7 @@ export const runSetupPrepare = async ({
       frontend_env_name: "CLUE_SERVICE_KEY",
       producer_id_derivation: "producer_id defaults to service_key",
     },
+    cli_invocation: CLUE_CLI_INVOCATION_CONTRACT,
     clue_context: {
       project_key: setupContext.project_key,
       environment: setupContext.environment,
@@ -391,9 +409,11 @@ export const runSetupPrepare = async ({
         : null,
     },
     lifecycle_verification: {
+      owner: "user",
+      ai_agent_must_run_setup_watch: false,
       watch_target_format:
         "frontend:<service-key>[init,identify,set-account,logout,event-sent]=<frontend-url>,backend:<service-key>[init,identify,set-account,logout,event-sent]=<backend-url>",
-      rule: "setup-watch --local uses the structured watch_targets below. Lifecycle checks are fixed for setup verification and are evaluated per service_key.",
+      rule: "setup-watch --local uses the structured watch_targets below, but it is user-operated verification. AI implementation agents must not run setup-watch automatically.",
       watch_targets: buildWatchTargets(detection, candidate),
     },
     artifacts: {
@@ -403,12 +423,54 @@ export const runSetupPrepare = async ({
     },
     machine_owned_artifacts: [workflow.ci_workflow_path, setupManifestPath],
     ai_must_not_edit: [workflow.ci_workflow_path],
-    ai_owned_workstreams: ["sdk_lifecycle_implementation"],
+    ai_owned_workstreams: ["sdk_lifecycle_placement"],
+    ai_implementation_scope: {
+      rule: "AI implementation is limited to placing ClueInit, ClueIdentify, ClueSetAccount, and ClueLogout in existing lifecycle boundaries plus the minimal SDK wiring required for those calls.",
+      lifecycle_apis: [
+        "ClueInit",
+        "ClueIdentify",
+        "ClueSetAccount",
+        "ClueLogout",
+      ],
+      out_of_scope_by_default: ["ClueTrack"],
+    },
     required_final_check: {
-      command:
-        `npx @clue-ai/cli setup-check --framework ${candidate.framework} ` +
-        `--backend-root-path ${candidate.backend_root_path} --repo . --target ${target} --require-sdk-lifecycle`,
+      command: clueCliCommand(
+        `setup-check --framework ${candidate.framework} ` +
+          `--backend-root-path ${candidate.backend_root_path} --repo . --target ${target} --require-sdk-lifecycle`,
+      ),
     },
+    required_final_verification: [
+      {
+        id: "static_setup_check",
+        command: clueCliCommand(
+          `setup-check --framework ${candidate.framework} ` +
+            `--backend-root-path ${candidate.backend_root_path} --repo . --target ${target} --require-sdk-lifecycle`,
+        ),
+        completion_meaning:
+          "static_passed_only_dependency_install_import_app_startup_and_event_delivery_still_required",
+      },
+      {
+        id: "sdk_dependency_install_and_import",
+        command:
+          "run the repository package-manager install plus frontend/backend SDK import checks in the target environments",
+        completion_meaning:
+          "required before claiming SDK lifecycle setup is complete",
+      },
+      {
+        id: "app_startup",
+        command:
+          "start the affected frontend/backend services and verify their configured local URLs respond",
+        completion_meaning:
+          "required before setup-watch local completion can be trusted",
+      },
+      {
+        id: "local_event_delivery",
+        command: `user runs ${clueCliCommand("setup-watch --local")}`,
+        completion_meaning:
+          "requires user-operated local services plus expected lifecycle event delivery; AI agents must report user_verification_pending when user evidence is not provided",
+      },
+    ],
     required_env_names: [
       "CLUE_SERVICE_KEY",
       "CLUE_API_KEY",
@@ -450,7 +512,8 @@ export const runSetupPrepare = async ({
       ...manifestWithEnvironmentArtifact.artifacts,
       environment_file_path: environmentFilePath,
     },
-    environment_instructions:
-      summarizeEnvironmentInstructions(environmentInstructions),
+    environment_instructions: summarizeEnvironmentInstructions(
+      environmentInstructions,
+    ),
   };
 };