@clue-ai/cli 0.0.4 → 0.0.6

package/src/setup-check.mjs

@@ -0,0 +1,436 @@
+import { access, readFile } from "node:fs/promises";
+import { join, relative, resolve } from "node:path";
+import {
+  findLifecycleCallApiNames,
+  findLifecycleGuardViolations,
+} from "./lifecycle-guard.mjs";
+import { listAllowedSourceFiles } from "./path-policy.mjs";
+import { runSemanticInventory } from "./semantic-ci.mjs";
+
+const DEFAULT_WORKFLOW_PATH = ".github/workflows/clue-semantic-snapshot.yml";
+
+const disallowedWorkflowMetadataPattern =
+  /github\.(actor|triggering_actor|repository_owner)|github\.event\.sender|github\.event\.repository\.name|"default_branch"\s*:/;
+const SETUP_SKILLS = [
+  "clue-setup-orchestrator",
+  "clue-route-semantic-snapshot",
+  "clue-semantic-ci",
+  "clue-sdk-instrumentation",
+  "clue-setup-audit",
+  "clue-local-verification",
+  "clue-setup-report",
+];
+const TARGET_SKILL_ROOTS = {
+  codex: [".agents", "skills"],
+  claude_code: [".claude", "skills"],
+};
+const SOURCE_EXTENSIONS = [".py", ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"];
+const REQUIRED_LIFECYCLE_APIS = [
+  "ClueInit",
+  "ClueIdentify",
+  "ClueSetAccount",
+  "ClueLogout",
+];
+const BACKEND_SDK_MARKERS = [
+  "clue-fastapi-sdk",
+  "clue-django-sdk",
+  "clue-python-sdk-core",
+  "clue_fastapi_sdk",
+  "clue_django_sdk",
+  "clue_python_sdk_core",
+];
+const DEPENDENCY_FILE_CANDIDATES = [
+  "package.json",
+  "pnpm-lock.yaml",
+  "package-lock.json",
+  "yarn.lock",
+  "requirements.txt",
+  "requirements-dev.txt",
+  "pyproject.toml",
+  "poetry.lock",
+  "Pipfile",
+];
+const exists = async (path) => {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+const normalizeTarget = (target) => {
+  if (typeof target !== "string" || target.trim() === "") return undefined;
+  const normalized = target
+    .trim()
+    .toLowerCase()
+    .replace(/[\s-]+/g, "_");
+  if (!TARGET_SKILL_ROOTS[normalized]) {
+    throw new Error("target must be codex or claude_code");
+  }
+  return normalized;
+};
+
+const addCheck = (checks, id, passed, summary, details = {}) => {
+  checks.push({ id, passed, summary, ...details });
+};
+
+const readAllowedSourceText = async ({
+  repoRoot,
+  allowedSourcePaths,
+  excludedSourcePaths,
+}) => {
+  const files = await listAllowedSourceFiles({
+    repoRoot,
+    allowedSourcePaths,
+    excludedSourcePaths,
+    extensions: SOURCE_EXTENSIONS,
+  });
+  const sources = [];
+  for (const absolutePath of files) {
+    sources.push({
+      file_path: relative(resolve(repoRoot), absolutePath),
+      text: await readFile(absolutePath, "utf8"),
+    });
+  }
+  return sources;
+};
+
+const readDependencyText = async ({ repoRoot, roots }) => {
+  const candidatePaths = [
+    ...DEPENDENCY_FILE_CANDIDATES,
+    ...roots.flatMap((root) =>
+      DEPENDENCY_FILE_CANDIDATES.map((file) => join(root, file)),
+    ),
+  ];
+  const sources = [];
+  for (const path of [...new Set(candidatePaths)]) {
+    const absolutePath = join(repoRoot, path);
+    if (!(await exists(absolutePath))) continue;
+    sources.push({
+      file_path: path,
+      text: await readFile(absolutePath, "utf8"),
+    });
+  }
+  return sources;
+};
+
+const setupSourcePaths = async ({ repoRoot, request, includeFrontend }) => {
+  const requested = request?.allowed_source_paths?.length
+    ? request.allowed_source_paths
+    : ["."];
+  if (!includeFrontend) return requested;
+  const candidates = [
+    ...requested,
+    "frontend/src",
+    "src",
+    "app",
+    "apps/web/src",
+    "packages/frontend",
+  ];
+  const existing = [];
+  for (const candidate of [...new Set(candidates)]) {
+    if (await exists(join(repoRoot, candidate))) {
+      existing.push(candidate);
+    }
+  }
+  return existing.length ? existing : requested;
+};
+
+const secretLeakPatterns = [
+  /pk_(live|test)_[A-Za-z0-9_-]+/,
+  /sk_(live|test)_[A-Za-z0-9_-]+/,
+  /npm_[A-Za-z0-9]{20,}/,
+  /CLUE_API_KEY\s*[:=]\s*["'][^"']+["']/,
+  /CLUE_AI_PROVIDER_API_KEY\s*[:=]\s*["'][^"']+["']/,
+];
+
+const findSecretLeaks = (sources) =>
+  sources.flatMap((source) =>
+    secretLeakPatterns.some((pattern) => pattern.test(source.text))
+      ? [source.file_path]
+      : [],
+  );
+
+const startsWithRoot = (filePath, root) =>
+  filePath === root || filePath.startsWith(`${root.replace(/\/+$/, "")}/`);
+
+const hasAnyMarker = (text, markers) =>
+  markers.some((marker) => text.includes(marker));
+
+const checkSdkLifecycle = ({
+  backendRootPaths = [],
+  dependencySources = [],
+  sources,
+}) => {
+  const combined = sources.map((source) => source.text).join("\n");
+  const backendSources = sources.filter((source) =>
+    backendRootPaths.some((root) => startsWithRoot(source.file_path, root)),
+  );
+  const backendCombined = backendSources
+    .map((source) => source.text)
+    .join("\n");
+  const dependencyCombined = dependencySources
+    .map((source) => source.text)
+    .join("\n");
+  const foundApiNames = findLifecycleCallApiNames(combined);
+  const backendFoundApiNames = findLifecycleCallApiNames(backendCombined);
+  const foundApis = REQUIRED_LIFECYCLE_APIS.filter((api) =>
+    foundApiNames.includes(api),
+  );
+  const missingApis = REQUIRED_LIFECYCLE_APIS.filter(
+    (api) => !foundApis.includes(api),
+  );
+  const noOpPattern =
+    /window\.Clue(?:Init|Identify|SetAccount|Logout)|(?:function|const|let|var)\s+Clue(?:Init|Identify|SetAccount|Logout)\b/;
+  const componentLifecycleInitFiles = sources
+    .filter((source) =>
+      /useEffect\s*\([\s\S]{0,1200}ClueInit/.test(source.text),
+    )
+    .map((source) => source.file_path);
+  const unguardedLifecycleCalls = sources.flatMap((source) =>
+    findLifecycleGuardViolations(source.text).map((violation) => ({
+      file_path: source.file_path,
+      ...violation,
+    })),
+  );
+  const unguardedLifecycleFiles = [
+    ...new Set(unguardedLifecycleCalls.map((violation) => violation.file_path)),
+  ];
+  const backendPresent = backendSources.length > 0;
+  const backendSdkPresent =
+    !backendPresent ||
+    hasAnyMarker(
+      `${backendCombined}\n${dependencyCombined}`,
+      BACKEND_SDK_MARKERS,
+    );
+  const backendInitPresent =
+    !backendPresent ||
+    /clue_init_fastapi|clue_init_django|configure_settings|CluePythonBootstrapConfig/.test(
+      backendCombined,
+    );
+  const backendIdentityRequired =
+    backendPresent &&
+    /\b(login|signin|sign_in|auth|token|session)\b/i.test(backendCombined);
+  const backendLogoutRequired =
+    backendPresent && /\b(logout|signout|sign_out)\b/i.test(backendCombined);
+  const backendAccountRequired =
+    backendPresent &&
+    /\b(account|workspace|organization|tenant)\b/i.test(backendCombined);
+  const backendMissingApis = [
+    ...(backendIdentityRequired &&
+    !backendFoundApiNames.includes("ClueIdentify")
+      ? ["ClueIdentify"]
+      : []),
+    ...(backendLogoutRequired && !backendFoundApiNames.includes("ClueLogout")
+      ? ["ClueLogout"]
+      : []),
+    ...(backendAccountRequired &&
+    !backendFoundApiNames.includes("ClueSetAccount")
+      ? ["ClueSetAccount"]
+      : []),
+  ];
+  return {
+    foundApis,
+    missingApis,
+    backend_lifecycle: {
+      backend_present: backendPresent,
+      backend_root_paths: backendRootPaths,
+      dependency_files: dependencySources.map((source) => source.file_path),
+      sdk_dependency_or_import_present: backendSdkPresent,
+      sdk_init_present: backendInitPresent,
+      required_apis: [
+        ...(backendIdentityRequired ? ["ClueIdentify"] : []),
+        ...(backendAccountRequired ? ["ClueSetAccount"] : []),
+        ...(backendLogoutRequired ? ["ClueLogout"] : []),
+      ],
+      missing_apis: backendMissingApis,
+    },
+    has_noop_wrapper: noOpPattern.test(combined),
+    component_lifecycle_init_files: componentLifecycleInitFiles,
+    unguarded_lifecycle_files: unguardedLifecycleFiles,
+    unguarded_lifecycle_calls: unguardedLifecycleCalls,
+    passed:
+      missingApis.length === 0 &&
+      backendSdkPresent &&
+      backendInitPresent &&
+      backendMissingApis.length === 0 &&
+      !noOpPattern.test(combined) &&
+      componentLifecycleInitFiles.length === 0 &&
+      unguardedLifecycleFiles.length === 0,
+  };
+};
+
+export const runSetupCheck = async ({
+  repoRoot,
+  target,
+  request,
+  requireSdkLifecycle = false,
+}) => {
+  const resolvedRepoRoot = resolve(repoRoot ?? ".");
+  const checks = [];
+  const normalizedTarget = normalizeTarget(target);
+
+  if (normalizedTarget) {
+    const skillRoot = join(
+      resolvedRepoRoot,
+      ...TARGET_SKILL_ROOTS[normalizedTarget],
+    );
+    const missingSkills = [];
+    for (const skillName of SETUP_SKILLS) {
+      const skillPath = join(skillRoot, skillName, "SKILL.md");
+      if (!(await exists(skillPath))) {
+        missingSkills.push(
+          join(...TARGET_SKILL_ROOTS[normalizedTarget], skillName, "SKILL.md"),
+        );
+      }
+    }
+    addCheck(
+      checks,
+      "setup_skills",
+      missingSkills.length === 0,
+      missingSkills.length === 0
+        ? "setup skills are installed"
+        : "setup skills are missing",
+      { missing_files: missingSkills },
+    );
+  }
+
+  const workflowPath = request?.ci_workflow_path ?? DEFAULT_WORKFLOW_PATH;
+  const absoluteWorkflowPath = join(resolvedRepoRoot, workflowPath);
+  if (await exists(absoluteWorkflowPath)) {
+    const workflow = await readFile(absoluteWorkflowPath, "utf8");
+    addCheck(
+      checks,
+      "semantic_workflow",
+      workflow.includes(
+        "npx @clue-ai/cli semantic-ci --request-env CLUE_SEMANTIC_REQUEST_JSON --repo .",
+      ) &&
+        workflow.includes("CLUE_SEMANTIC_REQUEST_JSON: |") &&
+        workflow.includes("CLUE_API_KEY: ${{ secrets.CLUE_API_KEY }}") &&
+        workflow.includes(
+          "CLUE_AI_PROVIDER_API_KEY: ${{ secrets.CLUE_AI_PROVIDER_API_KEY }}",
+        ) &&
+        workflow.includes("CLUE_AI_PROVIDER: ${{ vars.CLUE_AI_PROVIDER }}") &&
+        workflow.includes("permissions:\n  contents: read") &&
+        workflow.includes("persist-credentials: false") &&
+        !disallowedWorkflowMetadataPattern.test(workflow),
+      "semantic workflow uses the canonical env runtime request, least-privilege checkout, and privacy-minimized GitHub metadata",
+      { workflow_path: workflowPath },
+    );
+  } else {
+    addCheck(
+      checks,
+      "semantic_workflow",
+      false,
+      "semantic workflow is missing",
+      {
+        workflow_path: workflowPath,
+      },
+    );
+  }
+
+  addCheck(
+    checks,
+    "runtime_request_not_committed",
+    !(await exists(
+      join(resolvedRepoRoot, ".clue", "semantic-request.runtime.json"),
+    )),
+    ".clue/semantic-request.runtime.json is not present in the repository",
+  );
+
+  if (request) {
+    try {
+      const inventory = await runSemanticInventory({
+        repoRoot: resolvedRepoRoot,
+        request,
+      });
+      addCheck(
+        checks,
+        "semantic_inventory",
+        true,
+        "semantic inventory discovers routes",
+        {
+          route_count: inventory.route_count,
+        },
+      );
+    } catch (error) {
+      addCheck(
+        checks,
+        "semantic_inventory",
+        false,
+        "semantic inventory failed",
+        {
+          error: error instanceof Error ? error.message : String(error),
+        },
+      );
+    }
+  }
+
+  const sourcePaths = await setupSourcePaths({
+    repoRoot: resolvedRepoRoot,
+    request,
+    includeFrontend: requireSdkLifecycle,
+  });
+  const excludedPaths = request?.excluded_source_paths ?? [];
+  const sources = await readAllowedSourceText({
+    repoRoot: resolvedRepoRoot,
+    allowedSourcePaths: sourcePaths,
+    excludedSourcePaths: excludedPaths,
+  });
+  const dependencySources = await readDependencyText({
+    repoRoot: resolvedRepoRoot,
+    roots: request?.allowed_source_paths ?? [],
+  });
+  const secretLeaks = findSecretLeaks([
+    ...sources,
+    ...dependencySources,
+    ...((await exists(absoluteWorkflowPath))
+      ? [
+          {
+            file_path: workflowPath,
+            text: await readFile(absoluteWorkflowPath, "utf8"),
+          },
+        ]
+      : []),
+  ]);
+  addCheck(
+    checks,
+    "no_secret_values",
+    secretLeaks.length === 0,
+    "no obvious secret values found",
+    {
+      files: secretLeaks,
+    },
+  );
+
+  if (requireSdkLifecycle) {
+    const sdkLifecycle = checkSdkLifecycle({
+      backendRootPaths: request?.allowed_source_paths ?? [],
+      dependencySources,
+      sources,
+    });
+    addCheck(
+      checks,
+      "sdk_lifecycle",
+      sdkLifecycle.passed,
+      "SDK lifecycle calls resolve to real source code instead of no-op globals",
+      {
+        found_apis: sdkLifecycle.foundApis,
+        missing_apis: sdkLifecycle.missingApis,
+        backend_lifecycle: sdkLifecycle.backend_lifecycle,
+        has_noop_wrapper: sdkLifecycle.has_noop_wrapper,
+        component_lifecycle_init_files:
+          sdkLifecycle.component_lifecycle_init_files,
+        unguarded_lifecycle_files: sdkLifecycle.unguarded_lifecycle_files,
+        unguarded_lifecycle_calls: sdkLifecycle.unguarded_lifecycle_calls,
+      },
+    );
+  }
+
+  const passed = checks.every((check) => check.passed);
+  return {
+    passed,
+    checks,
+  };
+};

package/src/setup-detect.mjs

@@ -0,0 +1,198 @@
+import { readdir, readFile } from "node:fs/promises";
+import { dirname, join, relative, resolve } from "node:path";
+import { analyzeFastApiRoutes } from "./fastapi-analyzer.mjs";
+import { listAllowedPythonFiles } from "./path-policy.mjs";
+
+const deriveServiceKeyFromPath = (backendRootPath) => {
+  const segment = backendRootPath
+    .split("/")
+    .map((part) => part.trim())
+    .filter(Boolean)
+    .at(-1);
+  const normalized = segment
+    ?.toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  if (!normalized) {
+    throw new Error("service_key cannot be derived from detected backend root");
+  }
+  return normalized;
+};
+
+const commonDirectory = (paths) => {
+  const directories = paths.map((path) => dirname(path).split(/[\\/]+/).filter(Boolean));
+  if (directories.length === 0) return ".";
+  const common = [];
+  for (let index = 0; index < directories[0].length; index += 1) {
+    const part = directories[0][index];
+    if (directories.every((directory) => directory[index] === part)) {
+      common.push(part);
+      continue;
+    }
+    break;
+  }
+  return common.length ? common.join("/") : ".";
+};
+
+const ignoredPackageDirs = new Set([
+  ".git",
+  ".next",
+  ".turbo",
+  "coverage",
+  "dist",
+  "node_modules",
+]);
+
+const listPackageJsonFiles = async ({ repoRoot, currentPath = "." }) => {
+  const absolutePath = join(repoRoot, currentPath);
+  const entries = await readdir(absolutePath, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      if (ignoredPackageDirs.has(entry.name)) continue;
+      files.push(
+        ...(await listPackageJsonFiles({
+          repoRoot,
+          currentPath: join(currentPath, entry.name),
+        })),
+      );
+      continue;
+    }
+    if (entry.isFile() && entry.name === "package.json") {
+      files.push(join(currentPath, entry.name));
+    }
+  }
+  return files;
+};
+
+const readJsonFile = async (path) => JSON.parse(await readFile(path, "utf8"));
+
+const normalizePackageServiceKey = ({ packageJson, packagePath }) => {
+  const packageName =
+    typeof packageJson.name === "string" ? packageJson.name : "";
+  const source = packageName || dirname(packagePath);
+  const segment = source.split("/").at(-1) ?? source;
+  return segment
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+};
+
+const portFromScripts = (scripts) => {
+  const scriptText = Object.values(scripts ?? {})
+    .filter((value) => typeof value === "string")
+    .join("\n");
+  const portFlag = /(?:--port|-p)\s+(\d{2,5})/.exec(scriptText);
+  if (portFlag) return portFlag[1];
+  const envPort = /(?:^|\s)PORT=(\d{2,5})(?:\s|$)/.exec(scriptText);
+  return envPort?.[1] ?? null;
+};
+
+const detectFrontendServices = async ({ repoRoot }) => {
+  const packageJsonFiles = await listPackageJsonFiles({ repoRoot });
+  const services = [];
+  for (const packageJsonFile of packageJsonFiles) {
+    const absolutePath = join(repoRoot, packageJsonFile);
+    const packageJson = await readJsonFile(absolutePath);
+    const dependencies = {
+      ...(packageJson.dependencies ?? {}),
+      ...(packageJson.devDependencies ?? {}),
+    };
+    const framework = dependencies.next
+      ? "nextjs"
+      : dependencies.vite
+        ? "vite"
+        : dependencies["@angular/core"]
+          ? "angular"
+          : dependencies.vue
+            ? "vue"
+            : dependencies.react
+              ? "react"
+              : null;
+    if (!framework) continue;
+    const serviceKey = normalizePackageServiceKey({
+      packageJson,
+      packagePath: packageJsonFile,
+    });
+    if (!serviceKey) continue;
+    const port = portFromScripts(packageJson.scripts);
+    services.push({
+      kind: "frontend",
+      framework,
+      root_path: dirname(packageJsonFile),
+      service_key: serviceKey,
+      local_url_candidates: port ? [`http://localhost:${port}`] : [],
+    });
+  }
+  return services.sort((left, right) =>
+    left.service_key.localeCompare(right.service_key),
+  );
+};
+
+export const runSetupDetect = async ({ repoRoot, excludedSourcePaths = [] }) => {
+  const resolvedRepoRoot = resolve(repoRoot ?? ".");
+  const frontendServices = await detectFrontendServices({
+    repoRoot: resolvedRepoRoot,
+  });
+  const files = await listAllowedPythonFiles({
+    repoRoot: resolvedRepoRoot,
+    allowedSourcePaths: ["."],
+    excludedSourcePaths,
+  });
+  const fastApiRoutes = await analyzeFastApiRoutes({ repoRoot: resolvedRepoRoot, files });
+  if (fastApiRoutes.length === 0) {
+    return {
+      detected: false,
+      blockers: [
+        {
+          code: "NO_FASTAPI_ROUTES",
+          message: "No FastAPI routes were mechanically discovered.",
+        },
+      ],
+      candidates: [],
+      services: {
+        frontend: frontendServices,
+        backend: [],
+      },
+    };
+  }
+
+  const routeFiles = [
+    ...new Set(
+      fastApiRoutes.map((route) => route.ai_context.relative_path).filter(Boolean),
+    ),
+  ].sort();
+  const backendRootPath = commonDirectory(routeFiles);
+  const backendServiceKey = deriveServiceKeyFromPath(backendRootPath);
+  return {
+    detected: true,
+    blockers: [],
+    candidates: [
+      {
+        framework: "fastapi",
+        backend_root_path: backendRootPath,
+        service_key: backendServiceKey,
+        route_count: fastApiRoutes.length,
+        route_files: routeFiles,
+        operation_source_keys: fastApiRoutes
+          .map((route) => route.operation_source_key)
+          .sort(),
+      },
+    ],
+    services: {
+      frontend: frontendServices,
+      backend: [
+        {
+          kind: "backend",
+          framework: "fastapi",
+          root_path: backendRootPath,
+          service_key: backendServiceKey,
+          local_url_candidates: [],
+        },
+      ],
+    },
+    excluded_source_paths: excludedSourcePaths,
+    scanned_python_file_count: files.length,
+    repo_root: relative(process.cwd(), resolvedRepoRoot) || ".",
+  };
+};