@clue-ai/cli 0.0.18 → 0.0.19

package/src/setup-check.mjs

@@ -39,7 +39,9 @@ const REQUIRED_SETUP_SKILL_PHRASES = {
     "For Next.js browser/client code, use only `NEXT_PUBLIC_CLUE_PROJECT_KEY`",
     "Do not read `process.env.CLUE_PROJECT_KEY`",
     "CLUE_API_BASE_URL` is not part of backend SDK initialization",
-    "Do not add `@clue-ai/browser-sdk` or backend SDK dependencies with `*` or `latest`",
+    "Install Clue SDK dependencies through the latest channel",
+    "`@clue-ai/browser-sdk` must use `latest`",
+    "Python backend SDK dependencies must not be pinned",
     "Whitespace-only changes are allowed only on lines directly changed for Clue SDK wiring",
     "The local backend token endpoint is part of the customer app, not the Clue API",
     "send the same service key used by `ClueInit`",
@@ -60,6 +62,7 @@ const REQUIRED_SETUP_SKILL_PHRASES = {
     "Reject frontend browser token providers that derive the Clue proxy URL from `NEXT_PUBLIC_API_URL`",
     "Reject frontend adapters that mix stale browser-token paths",
     "Reject frontend adapters that set `initialized = true` before calling `ClueInit`",
+    "Reject Clue SDK dependency entries that pin stale fixed versions",
     "Audit the setup diff against the Clue setup contract even when the code was written by another agent",
     "Reject whitespace-only edits, import sorting, formatter churn",
     "Reject unrelated refactors, renames, file moves",
@@ -147,6 +150,12 @@ const DEPENDENCY_FILE_CANDIDATES = [
   "poetry.lock",
   "Pipfile",
 ];
+const PYTHON_BACKEND_DEPENDENCY_DECLARATION_FILES = [
+  "requirements.txt",
+  "requirements-dev.txt",
+  "pyproject.toml",
+  "Pipfile",
+];
 const exists = async (path) => {
   try {
     await access(path);
@@ -394,6 +403,20 @@ const setupSourcePaths = async ({ repoRoot, request, includeFrontend }) => {
   return existing.length ? existing : requested;
 };
 
+const setupBackendRootPaths = (request) => {
+  const configuredRoots = [
+    ...(Array.isArray(request?.backend_root_paths)
+      ? request.backend_root_paths
+      : []),
+    request?.backend_root_path,
+  ]
+    .filter((root) => typeof root === "string" && root.trim())
+    .map((root) => root.trim());
+  return configuredRoots.length
+    ? [...new Set(configuredRoots)]
+    : (request?.allowed_source_paths ?? []);
+};
+
 const secretLeakPatterns = [
   /pk_(live|test)_[A-Za-z0-9_-]+/,
   /sk_(live|test)_[A-Za-z0-9_-]+/,
@@ -776,17 +799,71 @@ const findNextLifecycleNonPublicEnvFiles = ({
     .map((source) => source.file_path);
 };
 
-const findWildcardFrontendSdkDependencyFiles = (dependencySources) =>
+const findNonLatestFrontendSdkDependencyFiles = (dependencySources) =>
   packageJsonSourcesWithDependency(dependencySources, FRONTEND_SDK_PACKAGE)
     .filter((source) => {
       const version = packageJsonDependencyVersion(
         source.text,
         FRONTEND_SDK_PACKAGE,
       );
-      return version === "*" || version === "latest";
+      return version !== "latest";
     })
     .map((source) => source.file_path);
 
+const sourceIsPythonBackendDependencyDeclaration = (source) =>
+  PYTHON_BACKEND_DEPENDENCY_DECLARATION_FILES.some((fileName) =>
+    source.file_path.endsWith(fileName),
+  );
+
+const backendSdkDependencyLineHasPinnedVersion = (line, packageName) => {
+  const stripped = line.trim();
+  if (!stripped || stripped.startsWith("#")) return false;
+  const withoutInlineComment = stripped.replace(/\s+#.*$/, "");
+  const packagePattern = new RegExp(
+    `(^|[\\s"'=,{\\[]+)${escapeRegex(packageName)}($|[\\s"'=<>~!@,;)}\\]]+)`,
+    "i",
+  );
+  if (!packagePattern.test(withoutInlineComment)) return false;
+
+  const requirementPattern = new RegExp(
+    `${escapeRegex(packageName)}(?:\\[[^\\]]+\\])?([^\\s"',;}\\]]*)`,
+    "i",
+  );
+  const requirementMatch = requirementPattern.exec(withoutInlineComment);
+  const suffix = requirementMatch?.[1] ?? "";
+  if (suffix && suffix !== ";") {
+    return true;
+  }
+
+  const keyPattern = new RegExp(
+    `^\\s*["']?${escapeRegex(packageName)}["']?\\s*=\\s*(.+)$`,
+    "i",
+  );
+  const keyMatch = keyPattern.exec(withoutInlineComment);
+  if (!keyMatch) return false;
+  const value = keyMatch[1].trim();
+  if (/^["']\*["']$/.test(value)) return false;
+  if (/version\s*=\s*["']\*["']/.test(value)) return false;
+  return true;
+};
+
+const findPinnedBackendSdkDependencyFiles = (
+  dependencySources,
+  packageNames,
+) =>
+  dependencySources
+    .filter(sourceIsPythonBackendDependencyDeclaration)
+    .filter((source) =>
+      source.text
+        .split(/\r?\n/)
+        .some((line) =>
+          packageNames.some((packageName) =>
+            backendSdkDependencyLineHasPinnedVersion(line, packageName),
+          ),
+        ),
+    )
+    .map((source) => source.file_path);
+
 const sourceLooksLikeBrowserTokenProvider = (source) => {
   const text = stripSourceNoise(source.text);
   return (
@@ -1053,6 +1130,10 @@ const checkSdkLifecycle = ({
   const backendSdkDependencyPresent =
     !backendPresent ||
     dependencyHasAnyPackage(dependencySources, backendSpec.packages);
+  const pinnedBackendSdkDependencyFiles = findPinnedBackendSdkDependencyFiles(
+    dependencySources,
+    backendSpec.packages,
+  );
   const backendSdkImportPresent =
     !backendPresent ||
     sourcesHavePythonImport(backendSources, backendSpec.imports);
@@ -1079,8 +1160,8 @@ const checkSdkLifecycle = ({
     dependencySources,
     frontendSources,
   });
-  const wildcardFrontendSdkDependencyFiles =
-    findWildcardFrontendSdkDependencyFiles(dependencySources);
+  const nonLatestFrontendSdkDependencyFiles =
+    findNonLatestFrontendSdkDependencyFiles(dependencySources);
   const browserTokenProviderMissingServiceKeyFiles =
     findBrowserTokenProviderMissingServiceKeyFiles(frontendSources);
   const browserTokenProviderWrongProxyPathFiles =
@@ -1143,6 +1224,7 @@ const checkSdkLifecycle = ({
         ? null
         : backendSpec.blocker,
       sdk_dependency_present: backendSdkDependencyPresent,
+      pinned_sdk_dependency_files: pinnedBackendSdkDependencyFiles,
       sdk_import_present: backendSdkImportPresent,
       sdk_dependency_or_import_present: backendSdkPresent,
       sdk_init_present: backendInitPresent,
@@ -1164,7 +1246,7 @@ const checkSdkLifecycle = ({
         frontendLifecycleFilesWithoutVerifiedSdk,
       wrong_sdk_packages: wrongFrontendSdkPackages,
       next_lifecycle_non_public_env_files: nextLifecycleNonPublicEnvFiles,
-      wildcard_sdk_dependency_files: wildcardFrontendSdkDependencyFiles,
+      non_latest_sdk_dependency_files: nonLatestFrontendSdkDependencyFiles,
       browser_token_provider_missing_service_key_files:
         browserTokenProviderMissingServiceKeyFiles,
       browser_token_provider_wrong_proxy_path_files:
@@ -1194,13 +1276,14 @@ const checkSdkLifecycle = ({
       missingApis.length === 0 &&
       backendSdkPresent &&
       backendSdkInstallabilityVerified &&
+      pinnedBackendSdkDependencyFiles.length === 0 &&
       backendInitPresent &&
       backendMissingApis.length === 0 &&
       frontendSdkPresent &&
       frontendLifecycleFilesWithoutVerifiedSdk.length === 0 &&
       wrongFrontendSdkPackages.length === 0 &&
       nextLifecycleNonPublicEnvFiles.length === 0 &&
-      wildcardFrontendSdkDependencyFiles.length === 0 &&
+      nonLatestFrontendSdkDependencyFiles.length === 0 &&
       browserTokenProviderMissingServiceKeyFiles.length === 0 &&
       browserTokenProviderWrongProxyPathFiles.length === 0 &&
       browserTokenProviderNonClueEndpointEnvFiles.length === 0 &&
@@ -1414,7 +1497,7 @@ export const runSetupCheck = async ({
 
   if (requireSdkLifecycle) {
     const sdkLifecycle = checkSdkLifecycle({
-      backendRootPaths: request?.allowed_source_paths ?? [],
+      backendRootPaths: setupBackendRootPaths(request),
       dependencySources,
       framework: request?.framework,
       sources,

package/src/setup-help.mjs

@@ -55,6 +55,21 @@ export const buildAiSetupHelp = () => ({
         "whitespace-only edits, import sorting, formatter churn, or comment/style cleanup outside the exact Clue SDK wiring lines",
       ],
     },
+    sdk_dependency_contract: {
+      frontend: {
+        package: "@clue-ai/browser-sdk",
+        install: "package-manager add @clue-ai/browser-sdk@latest",
+        rule:
+          "Frontend package.json must declare @clue-ai/browser-sdk as latest. Fixed versions and * are rejected by setup-check because stale SDKs break setup contracts.",
+      },
+      backend: {
+        fastapi_package: "clue-fastapi-sdk",
+        django_package: "clue-django-sdk",
+        install: "pip install --upgrade <backend-sdk-package>",
+        rule:
+          "Python backend SDK dependency declarations must be unpinned so pip resolves the latest release. Fixed ==, ~=, <=, >=, <, >, local path, and exact-version declarations are rejected by setup-check.",
+      },
+    },
     environment_contract: {
       nextjs_frontend_client_env: {
         variables: [
@@ -86,9 +101,21 @@ export const buildAiSetupHelp = () => ({
       owner: "ai_or_user",
       ai_agent_may_run: true,
       command: clueCliCommand("setup-doctor --local"),
-      rule: "Run setup-doctor after local frontend/backend services and required env are available. It checks API connectivity only and does not replace user-operated setup-watch.",
+      rule: "Run setup-doctor after local frontend/backend services and required env are available. setup-agent blocks when required setup-doctor inputs are missing or connectivity fails, unless setup-doctor is explicitly skipped. It checks API connectivity only and does not replace user-operated setup-watch.",
       checked_hops: Object.keys(API_CONNECTIVITY_CONTRACT.hops),
     },
+    setup_agent: {
+      owner: "clue_cli",
+      command: clueCliCommand("setup-agent --repo ."),
+      providers: ["openai", "anthropic"],
+      env:
+        "Set exactly CLUE_AI_PROVIDER, CLUE_AI_PROVIDER_API_KEY, and CLUE_AI_MODEL. setup-agent uses the same AI provider configuration as the rest of the Clue CLI. Optional CLI overrides are --ai-provider, --ai-provider-api-key, and --ai-model; do not use ambiguous --api_key flags.",
+      model_role:
+        "Return a strict structured lifecycle plan only; the CLI owns scanning, edit application, checks, doctor preflight, retry, and final status.",
+      tool_calling:
+        "OpenAI uses Responses API forced function tools with strict schema and parallel_tool_calls false. Anthropic uses Messages API tool_choice with the same input schema.",
+      setup_watch_auto_run: false,
+    },
     completion_boundary: {
       ai_may_claim: [
         "Clue setup code changes were applied",

package/src/setup-tool.mjs

@@ -316,7 +316,7 @@ 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.",
-      "For frontend code, add the real `@clue-ai/browser-sdk` dependency when missing. Do not invent `clue-js-sdk`, `@clue/browser-sdk`, local placeholder modules, or dynamic imports that hide a missing SDK.",
+      "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.",
       "Delete the temporary lifecycle plan file after applying it unless the user explicitly asks to keep it for review.",
@@ -339,9 +339,11 @@ const skillBody = (name, { documentsUrl } = {}) => {
       "The backend browser token proxy must derive origin from trusted request headers or server request metadata. Do not forward `origin`, `projectKey`, or `environment` from JSON/body payload fields under server `CLUE_API_KEY`.",
       "For browser token proxy code, the service key sent to Clue must be the frontend `ClueInit` serviceKey from the browser request, not the backend service's `CLUE_SERVICE_KEY`.",
       "If a backend-owned browser token endpoint is implemented, read `CLUE_API_BASE_URL` from the backend env block and normalize it so values with or without a trailing `/api/v1` do not produce duplicate paths.",
-      "For FastAPI code, add `clue-fastapi-sdk` to the backend dependency file when missing, import `clue_init_fastapi` plus `ClueIdentify`, `ClueSetAccount`, and `ClueLogout` where needed, and use `CLUE_PROJECT_KEY`, `CLUE_ENVIRONMENT`, `CLUE_API_KEY`, and `CLUE_INGEST_ENDPOINT` from the backend env block.",
+      "For FastAPI code, add unpinned `clue-fastapi-sdk` to the backend dependency file when missing so pip resolves the latest release, import `clue_init_fastapi` plus `ClueIdentify`, `ClueSetAccount`, and `ClueLogout` where needed, and use `CLUE_PROJECT_KEY`, `CLUE_ENVIRONMENT`, `CLUE_API_KEY`, and `CLUE_INGEST_ENDPOINT` from the backend env block.",
       "`CLUE_API_BASE_URL` is not part of backend SDK initialization. Use it only when the application backend owns a browser-token proxy for a frontend service.",
-      "Do not add `@clue-ai/browser-sdk` or backend SDK dependencies with `*` or `latest`; use a concrete published version or package-manager-resolved semver range and update the repository lockfile when one exists.",
+      "Python backend SDK dependencies must not be pinned.",
+      "`@clue-ai/browser-sdk` must use `latest`.",
+      "Install Clue SDK dependencies through the latest channel. Frontend package managers must use `@clue-ai/browser-sdk@latest`; Python backend dependency declarations must not pin `clue-fastapi-sdk` or `clue-django-sdk` to a fixed version.",
       "Use `CLUE_SERVICE_KEY` as the canonical local service identifier. Do not ask the user to manage a separate producer id; SDKs should send producer id as the service key for setup verification compatibility.",
       "For frontend code, pass `serviceKey` from the frontend service env name written by `.env.clue` to `ClueInit`; in Next.js browser/client code that name is `NEXT_PUBLIC_CLUE_SERVICE_KEY`.",
       "For Django code, use `clue-django-sdk` only after package-manager or registry verification confirms it is installable; if it is not published or cannot be verified, report a blocker instead of adding a guessed dependency or import.",
@@ -381,7 +383,7 @@ const skillBody = (name, { documentsUrl } = {}) => {
       "Reject broad ClueTrack instrumentation and DOM clue tags.",
       "Reject ClueTrack instrumentation unless the user explicitly requested product event tracking.",
       "Reject Next.js browser/client code that reads non-public `process.env.CLUE_*` variables.",
-      "Reject Clue SDK dependency entries that use `*` or `latest` instead of a concrete published version or package-manager-resolved semver range.",
+      "Reject Clue SDK dependency entries that pin stale fixed versions. Frontend package.json must use `@clue-ai/browser-sdk: latest`; Python backend SDK dependency declarations must be unpinned or package-manager wildcard-latest.",
       "Reject Next.js browser token providers that do not read `NEXT_PUBLIC_CLUE_BROWSER_TOKEN_ENDPOINT`.",
       "Confirm no project key, API key, secret, or env value appears in diff or report.",
       "Confirm lifecycle insertions are minimal and reviewable.",
@@ -402,7 +404,7 @@ const skillBody = (name, { documentsUrl } = {}) => {
       "Confirm the semantic workflow does not send GitHub actor, triggering_actor, sender, repository owner, repository name, or default branch to Clue.",
       "Confirm `.clue/semantic-request.runtime.json` is not created, committed, or staged.",
       `Run \`${clueCliCommand("setup-check --framework <framework> --backend-root-path <path> --repo . --target <codex|claude_code> --require-sdk-lifecycle")}\` when possible.`,
-      `Run \`${clueCliCommand("setup-doctor --local")}\` when local frontend/backend services are running and required env values are available. Report skipped_setup_doctor with the missing service URL or env name when it cannot run.`,
+      `Run \`${clueCliCommand("setup-doctor --local")}\` when local frontend/backend services are running. Missing setup-doctor inputs or failed API hops are blockers unless the user explicitly skipped setup-doctor.`,
       `Do not run \`${clueCliCommand("setup-watch --local")}\` automatically. setup-watch requires the user to operate real local frontend/backend services and login/logout/account flows.`,
       "If the user has not provided setup-watch or setup-screen evidence, report event delivery verification as `user_verification_pending` and do not state `setup completed`.",
       "Local static verification passed does not mean setup complete unless dependency install, SDK imports, app startup, and user-provided setup-watch or setup-screen event delivery were all verified.",
@@ -475,7 +477,7 @@ const skillBody = (name, { documentsUrl } = {}) => {
     `- Setup API connectivity has four distinct hops: ${Object.entries(API_CONNECTIVITY_CONTRACT.hops)
       .map(([name, hop]) => `${name}=${hop.method} ${hop.path}`)
       .join(", ")}.`,
-    `- Run \`${clueCliCommand("setup-doctor --local")}\` when local services and required env are available. This checks API connectivity only; it does not replace user-operated setup-watch.`,
+    `- Run \`${clueCliCommand("setup-doctor --local")}\` when local services are running. Missing setup-doctor inputs or failed API hops are blockers unless the user explicitly skipped setup-doctor. This checks API connectivity only; it does not replace user-operated setup-watch.`,
     "- Do not implement or refresh semantic snapshot CI during lifecycle placement; report a blocker if generated semantic artifacts are missing or stale.",
     `- Do not run \`${clueCliCommand("setup-watch --local")}\` automatically. setup-watch and the Clue setup screen are user-operated verification steps, not implementation-agent responsibility.`,
     "- The full setup must start with `clue-setup-orchestrator`.",