@clue-ai/cli 0.0.17 → 0.0.19

package/src/setup-agent.mjs

@@ -0,0 +1,448 @@
+import { access, readFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import {
+  applyLifecyclePlan,
+  planLifecycleInsertionsStrict,
+} from "./lifecycle-init.mjs";
+import { runSetupCheck } from "./setup-check.mjs";
+import { runSetupDoctor } from "./setup-doctor.mjs";
+
+const DEFAULT_SETUP_MANIFEST_PATH = ".clue/setup-manifest.json";
+const DEFAULT_ENV_GUIDE_PATH = ".env.clue";
+const DEFAULT_MAX_ATTEMPTS = 3;
+const DEPENDENCY_WRITE_FILE_CANDIDATES = [
+  "package.json",
+  "package-lock.json",
+  "pnpm-lock.yaml",
+  "yarn.lock",
+  "bun.lock",
+  "requirements.txt",
+  "requirements-dev.txt",
+  "pyproject.toml",
+  "Pipfile",
+  "Pipfile.lock",
+  "poetry.lock",
+];
+
+const optionalString = (value) =>
+  typeof value === "string" && value.trim() ? value.trim() : null;
+
+const readJson = async (path) => JSON.parse(await readFile(path, "utf8"));
+
+const parseEnvGuide = (text) => {
+  const values = {};
+  for (const line of text.split(/\r?\n/)) {
+    const match = /^\s*([A-Z][A-Z0-9_]*)=(.*)\s*$/.exec(line);
+    if (!match) continue;
+    const value = match[2].trim().replace(/^(['"])(.*)\1$/, "$2");
+    if (/^<[^>]+>$/.test(value)) continue;
+    values[match[1]] = value;
+  }
+  return values;
+};
+
+const readEnvGuideIfPresent = async ({ repoRoot }) => {
+  try {
+    return parseEnvGuide(
+      await readFile(resolve(repoRoot, DEFAULT_ENV_GUIDE_PATH), "utf8"),
+    );
+  } catch (error) {
+    if (error?.code === "ENOENT") return {};
+    throw error;
+  }
+};
+
+const exists = async (path) => {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+const normalizePositiveInteger = (value, fallback) => {
+  const parsed = Number.parseInt(String(value ?? ""), 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+};
+
+const aiProviderEnvFromFlags = ({ env, flags }) => {
+  const aiProvider = optionalString(flags.get("ai-provider"));
+  const aiProviderApiKey = optionalString(flags.get("ai-provider-api-key"));
+  const aiModel = optionalString(flags.get("ai-model"));
+  return {
+    ...env,
+    ...(aiProvider ? { CLUE_AI_PROVIDER: aiProvider } : {}),
+    ...(aiProviderApiKey
+      ? { CLUE_AI_PROVIDER_API_KEY: aiProviderApiKey }
+      : {}),
+    ...(aiModel ? { CLUE_AI_MODEL: aiModel } : {}),
+  };
+};
+
+const requireManifest = async ({ manifestPath, repoRoot }) => {
+  try {
+    return await readJson(resolve(repoRoot, manifestPath));
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      const blocker = new Error(
+        `setup-agent requires ${manifestPath}; run setup first`,
+      );
+      blocker.code = "CLUE_SETUP_MANIFEST_MISSING";
+      throw blocker;
+    }
+    throw error;
+  }
+};
+
+const sourcePathsFromManifest = (manifest) => {
+  const watchTargets = Array.isArray(
+    manifest.lifecycle_verification?.watch_targets,
+  )
+    ? manifest.lifecycle_verification.watch_targets
+    : [];
+  return [
+    ...new Set(
+      [
+        manifest.detected?.backend_root_path,
+        ...watchTargets.map((target) => target?.root_path),
+      ]
+        .map(optionalString)
+        .filter(Boolean),
+    ),
+  ];
+};
+
+const dependencyCandidateRoots = (sourcePaths) => [
+  ".",
+  ...sourcePaths.flatMap((root) => {
+    const normalized = root.replace(/\/+$/, "");
+    return normalized.endsWith("/src") || normalized.endsWith("/app")
+      ? [normalized, dirname(normalized)]
+      : [normalized];
+  }),
+];
+
+const discoveredDependencyWritePaths = async ({ repoRoot, sourcePaths }) => {
+  const candidates = dependencyCandidateRoots(sourcePaths).flatMap((root) =>
+    DEPENDENCY_WRITE_FILE_CANDIDATES.map((file) =>
+      root === "." ? file : join(root, file),
+    ),
+  );
+  const discovered = [];
+  for (const candidate of [...new Set(candidates)]) {
+    if (await exists(resolve(repoRoot, candidate))) {
+      discovered.push(candidate);
+    }
+  }
+  return discovered;
+};
+
+const allowedWritePathsFromRequest = async ({ repoRoot, request }) => [
+  ...new Set([
+    ...request.allowed_source_paths,
+    ...(await discoveredDependencyWritePaths({
+      repoRoot,
+      sourcePaths: request.allowed_source_paths,
+    })),
+  ]),
+];
+
+const buildLifecycleRequestFromManifest = ({ manifest, target }) => {
+  if (manifest?.status !== "ready_for_ai") {
+    throw new Error("setup-agent requires a ready_for_ai setup manifest");
+  }
+  const framework = optionalString(manifest.detected?.framework);
+  const backendRootPath = optionalString(manifest.detected?.backend_root_path);
+  const serviceKey = optionalString(manifest.detected?.service_key);
+  const sourcePaths = sourcePathsFromManifest(manifest);
+  if (!framework || !backendRootPath || !serviceKey || sourcePaths.length === 0) {
+    throw new Error(
+      "setup-agent manifest is missing framework, backend root, service key, or source paths",
+    );
+  }
+  return {
+    target_tool: optionalString(target) ?? optionalString(manifest.target) ?? "codex",
+    framework,
+    project_key: "CLUE_PROJECT_KEY",
+    environment: "CLUE_ENVIRONMENT",
+    service_key: serviceKey,
+    allowed_source_paths: sourcePaths,
+    excluded_source_paths: [],
+    backend_root_path: backendRootPath,
+  };
+};
+
+const failedChecks = (setupCheck) =>
+  Array.isArray(setupCheck?.checks)
+    ? setupCheck.checks
+        .filter((check) => !check.passed)
+        .map((check) => ({
+          id: check.id,
+          summary: check.summary ?? null,
+          details: {
+            missing_apis: check.missing_apis ?? null,
+            backend_lifecycle: check.backend_lifecycle ?? null,
+            frontend_lifecycle: check.frontend_lifecycle ?? null,
+            findings: check.findings ?? null,
+          },
+        }))
+    : [];
+
+const runStaticSetupCheck = async ({
+  manifest,
+  repoRoot,
+  request,
+  setupChecker,
+  target,
+}) =>
+  setupChecker({
+    repoRoot,
+    request: {
+      framework: request.framework,
+      backend_root_path: request.backend_root_path,
+      allowed_source_paths: request.allowed_source_paths,
+      excluded_source_paths: request.excluded_source_paths,
+      service_key: request.service_key,
+      workflow_path: manifest.artifacts?.ci_workflow_path,
+    },
+    target,
+    requireSdkLifecycle: true,
+  });
+
+const missingInputsFromDoctor = (report) => [
+  ...new Set(
+    (report?.checks ?? [])
+      .flatMap((check) => {
+        const match = /^missing required input: (?<names>.+)$/.exec(
+          check.error ?? "",
+        );
+        return match?.groups?.names
+          ? match.groups.names.split(",").map((entry) => entry.trim())
+          : [];
+      })
+      .filter(Boolean),
+  ),
+];
+
+const runOptionalSetupDoctor = async ({ env, flags, repoRoot, setupDoctor }) => {
+  if (flags.has("skip-setup-doctor")) {
+    return {
+      status: "skipped",
+      reason: "skip-setup-doctor flag was provided",
+      missing_inputs: [],
+      report: null,
+    };
+  }
+  const report = await setupDoctor({ env, flags, repoRoot });
+  const missingInputs = missingInputsFromDoctor(report);
+  if (!report.passed) {
+    const failedChecks = Array.isArray(report?.checks)
+      ? report.checks.filter((check) => !check.passed)
+      : [];
+    const allFailuresAreMissingInputs =
+      failedChecks.length > 0 &&
+      failedChecks.every((check) =>
+        /^missing required input: .+$/.test(check.error ?? ""),
+      );
+    if (allFailuresAreMissingInputs) {
+      return {
+        status: "blocked_missing_inputs",
+        reason: "setup-doctor required inputs are missing",
+        missing_inputs: missingInputs,
+        report,
+      };
+    }
+    return {
+      status: "failed",
+      reason: "setup-doctor connectivity preflight failed",
+      missing_inputs: [],
+      report,
+    };
+  }
+  return {
+    status: "passed",
+    reason: null,
+    missing_inputs: [],
+    report,
+  };
+};
+
+const attemptFailureContext = ({ attempt, error, setupCheck, stage }) => ({
+  attempt,
+  stage,
+  error:
+    error === undefined
+      ? null
+      : error instanceof Error
+        ? error.message
+        : String(error),
+  failed_checks: failedChecks(setupCheck),
+});
+
+export const runSetupAgent = async ({
+  env = process.env,
+  flags = new Map(),
+  lifecycleApplier = applyLifecyclePlan,
+  lifecyclePlanner = planLifecycleInsertionsStrict,
+  repoRoot = ".",
+  setupChecker = runSetupCheck,
+  setupDoctor = runSetupDoctor,
+}) => {
+  const resolvedRepoRoot = resolve(repoRoot ?? ".");
+  const manifestPath = String(
+    flags.get("manifest") || DEFAULT_SETUP_MANIFEST_PATH,
+  );
+  let manifest;
+  try {
+    manifest = await requireManifest({
+      manifestPath,
+      repoRoot: resolvedRepoRoot,
+    });
+  } catch (error) {
+    if (error?.code === "CLUE_SETUP_MANIFEST_MISSING") {
+      return {
+        status: "blocked",
+        code: "CLUE_SETUP_MANIFEST_MISSING",
+        manifest_path: manifestPath,
+        attempts: [],
+        setup_check: null,
+        setup_doctor: {
+          status: "skipped",
+          reason: "setup manifest is missing",
+          missing_inputs: [],
+          report: null,
+        },
+        blockers: [
+          {
+            reason: error.message,
+            evidence: manifestPath,
+          },
+        ],
+        user_verification: {
+          setup_watch_owner: "user",
+          setup_watch_auto_run: false,
+          status: "not_reached",
+          required_command: "npx -y @clue-ai/cli setup-watch --local",
+        },
+      };
+    }
+    throw error;
+  }
+  const target = optionalString(flags.get("target")) ?? manifest.target;
+  const mergedEnv = {
+    ...(await readEnvGuideIfPresent({ repoRoot: resolvedRepoRoot })),
+    ...env,
+  };
+  const request = buildLifecycleRequestFromManifest({ manifest, target });
+  const allowedWritePaths = await allowedWritePathsFromRequest({
+    repoRoot: resolvedRepoRoot,
+    request,
+  });
+  const maxAttempts = normalizePositiveInteger(
+    flags.get("max-attempts"),
+    DEFAULT_MAX_ATTEMPTS,
+  );
+  const aiEnv = aiProviderEnvFromFlags({ env: mergedEnv, flags });
+  const attempts = [];
+  let failureContext = null;
+  let lastSetupCheck = null;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    try {
+      const plan = await lifecyclePlanner({
+        repoRoot: resolvedRepoRoot,
+        request,
+        env: aiEnv,
+        failureContext,
+      });
+      const lifecycleResult = await lifecycleApplier({
+        repoRoot: resolvedRepoRoot,
+        plan,
+        allowedWritePaths,
+      });
+      const setupCheck = await runStaticSetupCheck({
+        manifest,
+        repoRoot: resolvedRepoRoot,
+        request,
+        setupChecker,
+        target,
+      });
+      lastSetupCheck = setupCheck;
+      attempts.push({
+        attempt,
+        lifecycle_insertions: lifecycleResult.lifecycleInsertions,
+        warnings: lifecycleResult.warnings,
+        setup_check_passed: setupCheck.passed,
+        failed_checks: failedChecks(setupCheck),
+      });
+      if (setupCheck.passed) {
+        const setupDoctorResult = await runOptionalSetupDoctor({
+          env: mergedEnv,
+          flags,
+          repoRoot: resolvedRepoRoot,
+          setupDoctor,
+        });
+        return {
+          status:
+            setupDoctorResult.status === "passed" ||
+            setupDoctorResult.status === "skipped"
+              ? "user_verification_pending"
+              : "blocked",
+          manifest_path: manifestPath,
+          attempts,
+          setup_check: setupCheck,
+          setup_doctor: setupDoctorResult,
+          user_verification: {
+            setup_watch_owner: "user",
+            setup_watch_auto_run: false,
+            status: "user_verification_pending",
+            required_command: "npx -y @clue-ai/cli setup-watch --local",
+          },
+        };
+      }
+      failureContext = attemptFailureContext({
+        attempt,
+        setupCheck,
+        stage: "setup_check",
+      });
+    } catch (error) {
+      failureContext = attemptFailureContext({
+        attempt,
+        error,
+        stage: "lifecycle_apply_or_plan",
+      });
+      attempts.push({
+        attempt,
+        setup_check_passed: false,
+        error: failureContext.error,
+        failed_checks: [],
+      });
+    }
+  }
+
+  return {
+    status: "blocked",
+    manifest_path: manifestPath,
+    attempts,
+    setup_check: lastSetupCheck,
+    setup_doctor: {
+      status: "skipped",
+      reason: "setup-check did not pass",
+      missing_inputs: [],
+      report: null,
+    },
+    blockers: [
+      {
+        reason: "setup-agent retry budget exhausted",
+        evidence: failureContext,
+      },
+    ],
+    user_verification: {
+      setup_watch_owner: "user",
+      setup_watch_auto_run: false,
+      status: "not_reached",
+      required_command: "npx -y @clue-ai/cli setup-watch --local",
+    },
+  };
+};

package/src/setup-ai-contract.mjs

@@ -1,5 +1,5 @@
 export const AI_SETUP_CONTRACT_VERSION =
-  "2026-05-10.api-connectivity-contract.v6";
+  "2026-05-10.latest-sdk-contract.v9";
 
 export const SETUP_DOCTRINE = {
   purpose:
@@ -26,12 +26,14 @@ export const DETERMINISTIC_CONTROL_MODEL = {
   ],
   cli_should_control: [
     "official SDK package names",
+    "latest-channel Clue SDK dependency declarations so setup agents cannot pin stale SDK versions",
     "official public SDK function names and supported lifecycle API set",
     "environment variable names produced by setup and consumed by setup code",
     "machine-owned semantic workflow generation and verification",
     "setup-watch ownership as user-operated verification",
     "static rejection of known unsafe wiring such as leaked secrets, wrong SDKs, blocking lifecycle calls, broad ClueTrack setup, and unsafe browser token proxy patterns",
     "local API connectivity preflight for the four required setup hops before user-operated setup-watch",
+    "canonical frontend SDK adapter env names, token proxy path, and initialization safety checks",
   ],
 };
 
@@ -79,6 +81,27 @@ export const API_CONNECTIVITY_CONTRACT = {
     "setup-doctor checks local API connectivity before user flows. setup-watch remains user-operated lifecycle and event-delivery verification.",
 };
 
+export const FRONTEND_ADAPTER_CONTRACT = {
+  purpose:
+    "Frontend SDK adapter code is part of the Clue setup contract. The AI may choose where the adapter is imported, but must not invent new token URL, env, or initialization semantics.",
+  nextjs_public_env: [
+    "NEXT_PUBLIC_CLUE_PROJECT_KEY",
+    "NEXT_PUBLIC_CLUE_ENVIRONMENT",
+    "NEXT_PUBLIC_CLUE_SERVICE_KEY",
+    "NEXT_PUBLIC_CLUE_INGEST_ENDPOINT",
+    "NEXT_PUBLIC_CLUE_BROWSER_TOKEN_ENDPOINT",
+  ],
+  browser_token_proxy_path: "/api/v1/clue/browser-tokens",
+  rules: [
+    "Do not derive the Clue browser-token proxy from generic app API env names such as NEXT_PUBLIC_API_URL.",
+    "Do not mix stale browser token paths with the canonical /api/v1/clue/browser-tokens path in the same adapter.",
+    "Next.js browserTokenProvider must call NEXT_PUBLIC_CLUE_BROWSER_TOKEN_ENDPOINT, whose value is the customer backend browser-token proxy URL.",
+    "Do not call ClueInit with empty-string fallbacks for required NEXT_PUBLIC_CLUE_* values.",
+    "If a singleton guard is used, do not mark initialized=true before ClueInit has been called with required config present.",
+    "The browser token provider must send the same frontend serviceKey used by ClueInit.",
+  ],
+};
+
 export const setupDoctrineSkillLines = () => [
   `- Purpose: ${SETUP_DOCTRINE.purpose}`,
   `- Minimal diff reason: ${SETUP_DOCTRINE.minimal_diff_reason}`,
@@ -87,5 +110,6 @@ export const setupDoctrineSkillLines = () => [
   `- Documentation reason: ${SETUP_DOCTRINE.documentation_reason}`,
   `- Failure posture: ${SETUP_DOCTRINE.failure_posture}`,
   `- 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.`,
 ];