@clue-ai/cli 0.0.22 → 0.0.23

package/package.json

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

package/src/lifecycle-init.mjs

@@ -1,4 +1,4 @@
-import { readFile, writeFile } from "node:fs/promises";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import {
   callJsonAiProvider,
@@ -15,6 +15,7 @@ import { listAllowedSourceFiles } from "./path-policy.mjs";
 import {
   API_CONNECTIVITY_CONTRACT,
   DETERMINISTIC_CONTROL_MODEL,
+  OFFICIAL_SDK_CONTRACT,
   SETUP_DOCTRINE,
 } from "./setup-ai-contract.mjs";
 
@@ -57,6 +58,18 @@ const LIFECYCLE_PLAN_TOOL_SCHEMA = {
         additionalProperties: false,
       },
     },
+    file_creations: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          file_path: { type: "string" },
+          content: { type: "string" },
+        },
+        required: ["file_path", "content"],
+        additionalProperties: false,
+      },
+    },
     lifecycle_insertions: {
       type: "array",
       items: {
@@ -99,6 +112,7 @@ const LIFECYCLE_PLAN_TOOL_SCHEMA = {
   required: [
     "status",
     "edits",
+    "file_creations",
     "lifecycle_insertions",
     "blockers",
     "warnings",
@@ -197,6 +211,16 @@ const assertClueSetupOnlyEdit = (edit) => {
   }
 };
 
+const assertClueSetupOnlyFileCreation = (fileCreation) => {
+  if (!CLUE_SETUP_ADDITION_PATTERN.test(fileCreation.content)) {
+    throw new Error(
+      `Clue lifecycle file creations must contain only Clue setup related code in ${fileCreation.file_path}`,
+    );
+  }
+  assertNoForbiddenInstrumentation(fileCreation.content);
+  assertLifecycleCallsAreNonBlocking(fileCreation.content);
+};
+
 const normalizeLifecycleInsertion = (input) => ({
   api_name: assertApiName(nonEmpty(input.api_name, "api_name")),
   file_path: nonEmpty(input.file_path, "file_path"),
@@ -240,6 +264,12 @@ const normalizePlan = (input) => {
     find: nonEmpty(edit.find, "edit.find"),
     replace: nonEmpty(edit.replace, "edit.replace"),
   }));
+  const fileCreations = Array.isArray(input.file_creations)
+    ? input.file_creations.map((fileCreation) => ({
+        file_path: nonEmpty(fileCreation.file_path, "file_creation.file_path"),
+        content: nonEmpty(fileCreation.content, "file_creation.content"),
+      }))
+    : [];
   const lifecycleInsertions = Array.isArray(input.lifecycle_insertions)
     ? input.lifecycle_insertions.map(normalizeLifecycleInsertion)
     : [];
@@ -247,7 +277,11 @@ const normalizePlan = (input) => {
     ? input.blockers.map(normalizeBlocker)
     : [];
   if (status === "blocked") {
-    if (edits.length > 0 || lifecycleInsertions.length > 0) {
+    if (
+      edits.length > 0 ||
+      fileCreations.length > 0 ||
+      lifecycleInsertions.length > 0
+    ) {
       throw new Error("blocked lifecycle plan must not include edits");
     }
     if (blockers.length === 0) {
@@ -260,6 +294,7 @@ const normalizePlan = (input) => {
   return {
     status,
     edits,
+    fileCreations,
     lifecycleInsertions,
     blockers,
     warnings: Array.isArray(input.warnings)
@@ -532,10 +567,11 @@ const buildLifecycleEvidenceSourceMap = async ({
   sourceByPath = new Map(),
 }) => {
   for (const filePath of [
-    ...new Set([
-      ...plan.edits.map((edit) => edit.file_path),
-      ...plan.lifecycleInsertions.map((insertion) => insertion.file_path),
-    ]),
+      ...new Set([
+        ...plan.edits.map((edit) => edit.file_path),
+        ...plan.fileCreations.map((fileCreation) => fileCreation.file_path),
+        ...plan.lifecycleInsertions.map((insertion) => insertion.file_path),
+      ]),
   ]) {
     await loadSourceIntoMap({ repoRoot, sourceByPath, filePath });
   }
@@ -580,6 +616,28 @@ export const applyLifecyclePlan = async ({
   }
   const sourceByPath = new Map();
   const pendingWrites = new Map();
+  for (const fileCreation of plan.fileCreations) {
+    const { absolutePath, relativePath } = safeRelativePath(
+      repoRoot,
+      fileCreation.file_path,
+    );
+    assertAllowedWritePath({ allowedWritePaths, filePath: relativePath });
+    assertClueSetupOnlyFileCreation(fileCreation);
+    try {
+      await readFile(absolutePath, "utf8");
+      throw new Error(`file_creation target already exists: ${relativePath}`);
+    } catch (error) {
+      if (error?.code !== "ENOENT") throw error;
+    }
+    sourceByPath.set(relativePath, {
+      file_path: relativePath,
+      text: fileCreation.content,
+    });
+    pendingWrites.set(relativePath, {
+      absolutePath,
+      text: fileCreation.content,
+    });
+  }
   for (const edit of plan.edits) {
     const { absolutePath, relativePath } = safeRelativePath(
       repoRoot,
@@ -624,9 +682,13 @@ export const applyLifecyclePlan = async ({
     });
   }
   for (const write of pendingWrites.values()) {
+    await mkdir(dirname(write.absolutePath), { recursive: true });
     await writeFile(write.absolutePath, write.text, "utf8");
   }
   return {
+    fileCreations: plan.fileCreations.map((fileCreation) => ({
+      file_path: fileCreation.file_path,
+    })),
     lifecycleInsertions: plan.lifecycleInsertions,
     warnings: plan.warnings,
   };
@@ -719,13 +781,17 @@ const buildLifecyclePrompt = ({ request, files }) =>
     task: "Add Clue SDK lifecycle API calls to this repository using exact text replacements.",
     setup_doctrine: SETUP_DOCTRINE,
     deterministic_control_model: DETERMINISTIC_CONTROL_MODEL,
+    official_sdk_contract: OFFICIAL_SDK_CONTRACT,
     api_connectivity_contract: API_CONNECTIVITY_CONTRACT,
     rules: [
       "Return JSON only.",
       "Understand the setup doctrine before choosing edits. This is an external Clue integration, not a host app refactor or redesign task.",
       "Use AI judgment only for lifecycle boundary placement. Let the CLI, generated skills, documentation contract, lifecycle plan schema, and setup-check static guards control deterministic mechanics.",
-      "If SDK signatures, environment names, browser token behavior, package installability, or verification ownership are unclear, return status blocked instead of guessing.",
+      "Treat official_sdk_contract as verified Clue setup input from the CLI. Do not block merely because the customer repo does not already contain Clue SDK imports, dependencies, browserTokenProvider wiring, or a Clue adapter.",
+      "If SDK signatures, environment names, browser token behavior, package installability, or verification ownership remain unclear after applying official_sdk_contract, return status blocked instead of guessing.",
       "Use only exact replacements. Each find string must be copied exactly from source.",
+      "Use file_creations only for minimal Clue-owned setup wiring files when no existing Clue adapter or browser-token proxy module exists.",
+      "Do not use file_creations for host application refactors, business logic, unrelated helpers, formatting, or non-Clue abstractions.",
       "Add ClueInit, ClueIdentify, ClueSetAccount, and ClueLogout where repository code has clear lifecycle points.",
       "Official Clue SDK public lifecycle APIs are no-throw and own SDK failure isolation.",
       "Do not add per-call try/catch, try/except, .catch, or custom safe wrappers solely around official Clue SDK public lifecycle calls.",
@@ -752,6 +818,7 @@ const buildLifecyclePrompt = ({ request, files }) =>
       "For Next.js browser/client code, read NEXT_PUBLIC_CLUE_PROJECT_KEY, NEXT_PUBLIC_CLUE_ENVIRONMENT, NEXT_PUBLIC_CLUE_SERVICE_KEY, NEXT_PUBLIC_CLUE_INGEST_ENDPOINT, and NEXT_PUBLIC_CLUE_BROWSER_TOKEN_ENDPOINT from the frontend .env.local block.",
       "Do not read process.env.CLUE_PROJECT_KEY, process.env.CLUE_ENVIRONMENT, process.env.CLUE_SERVICE_KEY, or process.env.CLUE_INGEST_ENDPOINT in Next.js browser/client code, and do not add non-public CLUE_* fallbacks there.",
       "Frontend SDK adapter code is contract-owned Clue setup wiring. The AI may choose the existing import/mount point, but must not invent token URL, env, or initialization semantics.",
+      "If no safe frontend/browser SDK adapter boundary exists, create a minimal Clue-owned adapter file under the existing frontend source root and add the smallest exact replacement needed to import or mount it from an existing stable bootstrap point.",
       "For Next.js frontend adapters, read the full customer-backend browser-token proxy URL from NEXT_PUBLIC_CLUE_BROWSER_TOKEN_ENDPOINT. Do not derive it from NEXT_PUBLIC_API_URL, generic app API env names, detected backend ports, or relative frontend-origin paths.",
       "Do not mix stale browser-token paths such as /api/clue/browser-token, /clue/browser-tokens, or /browser-tokens with the canonical /api/v1/clue/browser-tokens path.",
       "Do not call ClueInit with empty-string fallbacks for required NEXT_PUBLIC_CLUE_* values. If required Clue env is absent, skip initialization and report the missing env names.",
@@ -759,6 +826,7 @@ const buildLifecyclePrompt = ({ request, files }) =>
       "For non-Next.js browser code, use the exact frontend env names written in .env.clue for that service instead of inventing a framework-specific prefix.",
       "Never place CLUE_API_KEY in frontend code, frontend env files, browser bundles, or client-readable config.",
       "When browser SDK ingest is configured, implement a backend-owned browser token endpoint that reads server-side CLUE_API_KEY and requests POST /api/v1/ingest/browser-tokens from Clue.",
+      "If no backend-owned browser token proxy module exists, create a minimal Clue-owned route/module under the existing backend source root and add the smallest exact replacement needed to register it in the existing backend router.",
       "Configure frontend ClueInit with browserTokenProvider that calls the local backend token endpoint and returns the token string.",
       "Keep the four setup API hops distinct: customer frontend -> customer backend /api/v1/clue/browser-tokens, customer backend -> Clue /api/v1/ingest/browser-tokens, customer frontend -> Clue /api/v1/ingest/browser, and customer backend -> Clue /api/v1/ingest/backend.",
       "The local backend token endpoint is part of the customer app, not the Clue API. Place it under a Clue-reserved local route such as /api/v1/clue/browser-tokens; do not use a generic path such as /browser-tokens that could be confused with product behavior. It must call Clue server-side at /api/v1/ingest/browser-tokens.",
@@ -797,6 +865,12 @@ const buildLifecyclePrompt = ({ request, files }) =>
     output_shape: {
       status: "ready",
       blockers: [],
+      file_creations: [
+        {
+          file_path: "app/clue_adapter.py",
+          content: "new Clue-only setup file content",
+        },
+      ],
       edits: [
         {
           file_path: "app/main.py",

package/src/setup-agent.mjs

@@ -456,6 +456,7 @@ export const runSetupAgent = async ({
       lastSetupCheck = setupCheck;
       attempts.push({
         attempt,
+        file_creations: lifecycleResult.fileCreations ?? [],
         lifecycle_insertions: lifecycleResult.lifecycleInsertions,
         warnings: lifecycleResult.warnings,
         setup_check_passed: setupCheck.passed,

package/src/setup-ai-contract.mjs

@@ -1,5 +1,5 @@
 export const AI_SETUP_CONTRACT_VERSION =
-  "2026-05-10.latest-sdk-contract.v9";
+  "2026-05-10.latest-sdk-contract.v10";
 
 export const SETUP_DOCTRINE = {
   purpose:
@@ -102,6 +102,52 @@ export const FRONTEND_ADAPTER_CONTRACT = {
   ],
 };
 
+export const OFFICIAL_SDK_CONTRACT = {
+  purpose:
+    "This bundled contract is the authoritative Clue SDK contract for setup-agent. A customer repository is expected to start without Clue SDK imports or dependencies; absence of existing Clue code is not a blocker.",
+  frontend_browser_sdk: {
+    package_name: "@clue-ai/browser-sdk",
+    dependency_specifier: "@clue-ai/browser-sdk@latest",
+    import_path: "@clue-ai/browser-sdk",
+    public_lifecycle_apis: {
+      ClueInit:
+        "ClueInit(options: { endpoint: string; projectKey: string; environment: string; serviceKey?: string; producerId?: string; browserTokenProvider?: () => string | Promise<string>; ... }): void",
+      ClueIdentify:
+        "ClueIdentify(userId: string, traits?: Record<string, string | number | boolean | null>): void",
+      ClueSetAccount:
+        "ClueSetAccount(accountId: string, traits?: Record<string, string | number | boolean | null>): void",
+      ClueLogout: "ClueLogout(): void",
+    },
+    safety_contract:
+      "Public lifecycle APIs are no-throw wrappers. Do not add custom per-call try/catch or await them.",
+  },
+  backend_fastapi_sdk: {
+    package_name: "clue-fastapi-sdk",
+    dependency_specifier: "clue-fastapi-sdk",
+    python_import:
+      "from clue_fastapi_sdk import clue_init_fastapi, ClueIdentify, ClueSetAccount, ClueLogout",
+    public_lifecycle_apis: {
+      clue_init_fastapi:
+        "clue_init_fastapi(app, *, project_key: str, environment: str, api_key: str | None = None, service_name: str = 'python-service', producer_id: str | None = None, service_key: str | None = None, ... ) -> bool",
+      ClueIdentify:
+        "ClueIdentify(user_id: str, traits: Mapping[str, object] | None = None) -> bool",
+      ClueSetAccount:
+        "ClueSetAccount(account_id: str, traits: Mapping[str, object] | None = None) -> bool",
+      ClueLogout: "ClueLogout(reason: str | None = None) -> bool",
+    },
+    safety_contract:
+      "Public lifecycle APIs catch SDK errors internally and return bool where applicable. Do not wrap each call solely for Clue failure isolation.",
+  },
+  minimal_file_creation_contract: {
+    allowed_when:
+      "No existing Clue adapter, browser-token proxy module, or client bootstrap wrapper exists in the customer repo.",
+    allowed_files:
+      "Only Clue-owned minimal SDK wiring files under existing frontend/backend source roots, plus exact replacements in existing files to import/register those files.",
+    rule:
+      "Creating a minimal Clue adapter or browser-token proxy is allowed setup wiring, not a host application refactor.",
+  },
+};
+
 export const setupDoctrineSkillLines = () => [
   `- Purpose: ${SETUP_DOCTRINE.purpose}`,
   `- Minimal diff reason: ${SETUP_DOCTRINE.minimal_diff_reason}`,
@@ -109,6 +155,7 @@ export const setupDoctrineSkillLines = () => [
   `- Static control boundary: ${SETUP_DOCTRINE.deterministic_control_boundary}`,
   `- Documentation reason: ${SETUP_DOCTRINE.documentation_reason}`,
   `- Failure posture: ${SETUP_DOCTRINE.failure_posture}`,
+  `- Official SDK contract: ${OFFICIAL_SDK_CONTRACT.purpose}`,
   `- API connectivity: ${API_CONNECTIVITY_CONTRACT.purpose}`,
   `- Frontend adapter: ${FRONTEND_ADAPTER_CONTRACT.purpose}`,
   `- API preflight: run ${API_CONNECTIVITY_CONTRACT.preflight_command} when local services and required env are available; do not substitute it for user-operated setup-watch.`,

package/src/setup-documents.mjs

@@ -8,6 +8,7 @@ export const CORE_SETUP_DOCUMENT_IDS = [
   "clue-boundary",
   "environment-and-secrets",
   "find-integration-points",
+  "official-sdk-contract",
   "browser-token-endpoint",
   "clue-init",
   "clue-identify",
@@ -96,4 +97,3 @@ export const buildSetupDocumentationContract = ({
       "Read the relevant Clue setup documents before editing and list consulted_document_ids in the final report.",
   };
 };
-

package/src/setup-tool.mjs

@@ -260,7 +260,7 @@ const skillBody = (name, { documentsUrl } = {}) => {
       "Open the docs page when the AI tool has browser or HTTP access. If it cannot be opened, continue only from the generated skill text and manifest doc ids, then report `documentation_access_blocked`.",
       "Read all ids in `documentation.required_doc_ids` that apply to the detected repository.",
       "For framework-specific implementation, select ids from `documentation.selected_framework_doc_ids` first. If empty, use `documentation.framework_doc_ids_by_framework` for the detected framework.",
-      "Minimum lifecycle docs before implementation: ai-setup-order, environment-and-secrets, browser-token-endpoint, clue-init, clue-identify, clue-set-account, clue-logout, setup-verification, forbidden-patterns.",
+      "Minimum lifecycle docs before implementation: ai-setup-order, environment-and-secrets, official-sdk-contract, browser-token-endpoint, clue-init, clue-identify, clue-set-account, clue-logout, setup-verification, forbidden-patterns.",
       "For Next.js, read framework-nextjs. For React, Vite, Vue, or Angular browser apps, read framework-react-spa. For FastAPI, read framework-fastapi. For Django, read framework-django.",
       "Return `consulted_document_ids` to the orchestrator and final report.",
       "If a document contradicts `.clue/setup-manifest.json` or generated skills, stop and report a blocker instead of choosing behavior silently.",
@@ -316,6 +316,8 @@ const skillBody = (name, { documentsUrl } = {}) => {
       "Do not add per-call try/catch, try/except, `.catch`, or custom safe wrappers solely around official Clue SDK public lifecycle calls.",
       "Never await a Clue lifecycle call in a way that can block login, logout, account selection, request handling, page rendering, or API responses.",
       "Add or report the required SDK dependency instead of fabricating lifecycle APIs.",
+      "A clean customer repository is expected to have no existing Clue SDK imports, dependencies, browserTokenProvider wiring, or Clue adapter. Do not treat that absence as a blocker; add the minimal official Clue setup wiring.",
+      "When no existing Clue adapter or browser-token proxy module exists, creating a minimal Clue-owned setup file under the existing source root is allowed. Do not use new files for unrelated host app abstractions.",
       "For frontend code, add the real `@clue-ai/browser-sdk` dependency when missing. Use the latest channel (`@clue-ai/browser-sdk@latest`) so setup receives current SDK fixes. Do not invent `clue-js-sdk`, `@clue/browser-sdk`, local placeholder modules, or dynamic imports that hide a missing SDK.",
       `When lifecycle edits are clear, write an exact replacement plan to a temporary local JSON file and apply it with \`${clueCliCommand("lifecycle-apply --plan <plan-file> --repo .")}\`.`,
       "If npm/npx cannot fetch the Clue CLI package, report a blocker with the exact command and error instead of manually applying replacement plans.",