@genn-inc/cluebase-cli 0.0.1

package/src/setup-discover-check.mjs

@@ -0,0 +1,755 @@
+// setup-discover-check validates `.cluebase/discoveries.json` against
+// `.cluebase/setup-manifest.json` and the repository.
+
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { isAbsolute, resolve } from "node:path";
+
+export const SETUP_DISCOVER_CHECK_EXIT_CODES = Object.freeze({
+  PASS: 0,
+  GENERIC_ERROR: 1,
+  SCHEMA_VIOLATION: 2,
+  FILE_NOT_FOUND: 3,
+  CARDINALITY_VIOLATION: 4,
+  DUPLICATE_SITE: 5,
+  SECRETS_LEAK: 6,
+  SECRETS_NOT_IGNORED: 7,
+});
+
+const SITE_ARRAY_FIELDS = Object.freeze([
+  "identify_sites",
+  "group_sites",
+  "reset_sites",
+]);
+
+const SINGULAR_INIT_FIELDS = Object.freeze([
+  "cluebase_init_frontend",
+  "cluebase_init_backend",
+]);
+
+const isPlainObject = (value) =>
+  value !== null && typeof value === "object" && !Array.isArray(value);
+
+const isPositiveInt = (value) =>
+  typeof value === "number" && Number.isInteger(value) && value >= 1;
+
+const requireString = (value) => typeof value === "string" && value.length > 0;
+
+const requireNonEmptyString = (value) =>
+  typeof value === "string" && value.trim().length > 0;
+
+const ERROR_CODE_TO_EXIT = Object.freeze({
+  SCHEMA_VIOLATION: SETUP_DISCOVER_CHECK_EXIT_CODES.SCHEMA_VIOLATION,
+  FRAMEWORK_MISMATCH: SETUP_DISCOVER_CHECK_EXIT_CODES.SCHEMA_VIOLATION,
+  SERVICE_KEY_MISMATCH: SETUP_DISCOVER_CHECK_EXIT_CODES.SCHEMA_VIOLATION,
+  CARDINALITY_VIOLATION: SETUP_DISCOVER_CHECK_EXIT_CODES.CARDINALITY_VIOLATION,
+  FILE_NOT_FOUND: SETUP_DISCOVER_CHECK_EXIT_CODES.FILE_NOT_FOUND,
+  LINE_OUT_OF_RANGE: SETUP_DISCOVER_CHECK_EXIT_CODES.FILE_NOT_FOUND,
+  ABSOLUTE_PATH: SETUP_DISCOVER_CHECK_EXIT_CODES.FILE_NOT_FOUND,
+  FILE_READ_ERROR: SETUP_DISCOVER_CHECK_EXIT_CODES.FILE_NOT_FOUND,
+  DUPLICATE_SITE: SETUP_DISCOVER_CHECK_EXIT_CODES.DUPLICATE_SITE,
+  SECRETS_LEAK: SETUP_DISCOVER_CHECK_EXIT_CODES.SECRETS_LEAK,
+  SECRETS_NOT_IGNORED: SETUP_DISCOVER_CHECK_EXIT_CODES.SECRETS_NOT_IGNORED,
+});
+
+const validateSchema = (discoveries) => {
+  const errors = [];
+  if (!isPlainObject(discoveries)) {
+    errors.push({
+      code: "SCHEMA_VIOLATION",
+      message: "discoveries must be a JSON object",
+    });
+    return errors;
+  }
+  if (!requireString(discoveries.framework_frontend)) {
+    errors.push({
+      code: "SCHEMA_VIOLATION",
+      message: "framework_frontend must be a non-empty string",
+    });
+  }
+  if (
+    discoveries.framework_backend !== null &&
+    !requireString(discoveries.framework_backend)
+  ) {
+    errors.push({
+      code: "SCHEMA_VIOLATION",
+      message: "framework_backend must be a non-empty string or null",
+    });
+  }
+  if (!requireString(discoveries.service_key)) {
+    errors.push({
+      code: "SCHEMA_VIOLATION",
+      message: "service_key must be a non-empty string",
+    });
+  }
+  for (const field of SINGULAR_INIT_FIELDS) {
+    if (!(field in discoveries)) {
+      errors.push({
+        code: "SCHEMA_VIOLATION",
+        message: `${field} is required (object or null)`,
+      });
+      continue;
+    }
+    const value = discoveries[field];
+    if (Array.isArray(value)) {
+      errors.push({
+        code: "CARDINALITY_VIOLATION",
+        message: `${field} must be a single object or null, not an array`,
+      });
+      continue;
+    }
+    if (value === null) continue;
+    if (!isPlainObject(value)) {
+      errors.push({
+        code: "SCHEMA_VIOLATION",
+        message: `${field} must be an object or null`,
+      });
+      continue;
+    }
+    if (!requireString(value.file)) {
+      errors.push({
+        code: "SCHEMA_VIOLATION",
+        message: `${field}.file must be a non-empty string`,
+      });
+    }
+    if (!isPositiveInt(value.line)) {
+      errors.push({
+        code: "SCHEMA_VIOLATION",
+        message: `${field}.line must be a positive integer`,
+      });
+    }
+    if (!requireString(value.rationale)) {
+      errors.push({
+        code: "SCHEMA_VIOLATION",
+        message: `${field}.rationale must be a non-empty string`,
+      });
+    }
+  }
+  for (const field of SITE_ARRAY_FIELDS) {
+    if (!(field in discoveries)) {
+      errors.push({
+        code: "SCHEMA_VIOLATION",
+        message: `${field} is required (array)`,
+      });
+      continue;
+    }
+    const arr = discoveries[field];
+    if (!Array.isArray(arr)) {
+      errors.push({
+        code: "CARDINALITY_VIOLATION",
+        message: `${field} must be an array (even when empty)`,
+      });
+      continue;
+    }
+    arr.forEach((site, index) => {
+      if (!isPlainObject(site)) {
+        errors.push({
+          code: "SCHEMA_VIOLATION",
+          message: `${field}[${index}] must be an object`,
+        });
+        return;
+      }
+      if (!requireString(site.file)) {
+        errors.push({
+          code: "SCHEMA_VIOLATION",
+          message: `${field}[${index}].file must be a non-empty string`,
+        });
+      }
+      if (!isPositiveInt(site.line)) {
+        errors.push({
+          code: "SCHEMA_VIOLATION",
+          message: `${field}[${index}].line must be a positive integer`,
+        });
+      }
+      if (!requireString(site.rationale)) {
+        errors.push({
+          code: "SCHEMA_VIOLATION",
+          message: `${field}[${index}].rationale must be a non-empty string`,
+        });
+      }
+      if (!requireNonEmptyString(site.evidence_snippet)) {
+        errors.push({
+          code: "SCHEMA_VIOLATION",
+          message: `${field}[${index}].evidence_snippet must be a non-empty string`,
+        });
+      }
+      // `available_fields` / `field_acquisition_notes` 型 check は site 側で
+      // value が入っているときだけ確認する (= STEP 3 完了の有無は警告レベル
+      // で別途レポート、 ここでは型のみ防御)。 STEP 3 incomplete 自体は
+      // buildWarnings の `STEP_3_INCOMPLETE` で検出 (R4-P1-9)。
+      //
+      // available_fields の形式は STEP 3 prompt の指定通り object (= field name → path expression)。
+      // 例: { "id": "data.user.id", "name": "data.user.user_metadata?.name ?? data.user.email" }
+      // reset_sites は引数なしなので空 object `{}` を許容。
+      if (
+        "available_fields" in site &&
+        site.available_fields !== null &&
+        (typeof site.available_fields !== "object" ||
+          Array.isArray(site.available_fields))
+      ) {
+        errors.push({
+          code: "SCHEMA_VIOLATION",
+          message: `${field}[${index}].available_fields must be a plain object (field name → path string) or null`,
+        });
+      }
+      if (
+        "field_acquisition_notes" in site &&
+        site.field_acquisition_notes !== null &&
+        typeof site.field_acquisition_notes !== "string"
+      ) {
+        errors.push({
+          code: "SCHEMA_VIOLATION",
+          message: `${field}[${index}].field_acquisition_notes must be a string or null`,
+        });
+      }
+    });
+  }
+  if (
+    "organization_context" in discoveries &&
+    discoveries.organization_context !== null &&
+    !isPlainObject(discoveries.organization_context)
+  ) {
+    errors.push({
+      code: "SCHEMA_VIOLATION",
+      message:
+        "organization_context must be a plain object or null when present",
+    });
+  }
+  if (
+    "existing_cluebase_calls" in discoveries &&
+    !Array.isArray(discoveries.existing_cluebase_calls)
+  ) {
+    errors.push({
+      code: "SCHEMA_VIOLATION",
+      message: "existing_cluebase_calls must be an array when present",
+    });
+  }
+  if (
+    "unclear_points" in discoveries &&
+    !Array.isArray(discoveries.unclear_points)
+  ) {
+    errors.push({
+      code: "SCHEMA_VIOLATION",
+      message: "unclear_points must be an array when present",
+    });
+  }
+  return errors;
+};
+
+const validateManifestConsistency = (discoveries, manifest) => {
+  if (!isPlainObject(discoveries) || !isPlainObject(manifest)) return [];
+  const errors = [];
+  const detected = isPlainObject(manifest.detected) ? manifest.detected : null;
+  const detectedFramework = detected?.framework;
+  if (
+    requireString(detectedFramework) &&
+    discoveries.framework_frontend !== detectedFramework &&
+    discoveries.framework_backend !== detectedFramework
+  ) {
+    errors.push({
+      code: "FRAMEWORK_MISMATCH",
+      message: `manifest detected.framework="${detectedFramework}" but discoveries.framework_frontend="${discoveries.framework_frontend}" / framework_backend="${discoveries.framework_backend ?? "null"}"`,
+    });
+  }
+  const manifestServiceKey = detected?.service_key;
+  if (
+    requireString(manifestServiceKey) &&
+    requireString(discoveries.service_key) &&
+    discoveries.service_key !== manifestServiceKey
+  ) {
+    errors.push({
+      code: "SERVICE_KEY_MISMATCH",
+      message: `manifest service_key="${manifestServiceKey}" but discoveries.service_key="${discoveries.service_key}"`,
+    });
+  }
+  return errors;
+};
+
+const collectAllSites = (discoveries) => {
+  if (!isPlainObject(discoveries)) return [];
+  const sites = [];
+  for (const field of SINGULAR_INIT_FIELDS) {
+    const value = discoveries[field];
+    if (
+      isPlainObject(value) &&
+      requireString(value.file) &&
+      isPositiveInt(value.line)
+    ) {
+      sites.push({
+        location: field,
+        file: value.file,
+        line: value.line,
+        // Allow implementation to create new singleton files. When true, file existence
+        // and line-count checks are skipped because the file is planned, not
+        // present in the repo yet.
+        creates_new_file: Boolean(value.creates_new_file),
+      });
+    }
+  }
+  for (const field of SITE_ARRAY_FIELDS) {
+    const arr = discoveries[field];
+    if (!Array.isArray(arr)) continue;
+    arr.forEach((site, index) => {
+      if (
+        isPlainObject(site) &&
+        requireString(site.file) &&
+        isPositiveInt(site.line)
+      ) {
+        sites.push({
+          location: `${field}[${index}]`,
+          file: site.file,
+          line: site.line,
+          creates_new_file: false,
+        });
+      }
+    });
+  }
+  return sites;
+};
+
+const validateFileExistence = async ({ discoveries, repoRoot }) => {
+  const errors = [];
+  const sites = collectAllSites(discoveries);
+  for (const site of sites) {
+    if (isAbsolute(site.file)) {
+      errors.push({
+        code: "ABSOLUTE_PATH",
+        location: site.location,
+        file: site.file,
+        message: `${site.location}.file must be a path relative to the repo root, got absolute path "${site.file}"`,
+      });
+      continue;
+    }
+    const absolute = resolve(repoRoot, site.file);
+    if (!existsSync(absolute)) {
+      if (site.creates_new_file) {
+        // Implementation will create this file. Skip the existence and line-range
+        // checks but still require a sensible non-absolute relative path.
+        continue;
+      }
+      errors.push({
+        code: "FILE_NOT_FOUND",
+        location: site.location,
+        file: site.file,
+        message: `${site.location} references "${site.file}" which does not exist in the repository`,
+      });
+      continue;
+    }
+    if (site.creates_new_file) {
+      // File already exists. The implementation step will edit it instead of creating it.
+      continue;
+    }
+    try {
+      const text = await readFile(absolute, "utf8");
+      const lineCount = text.split(/\r?\n/).length;
+      if (site.line > lineCount) {
+        errors.push({
+          code: "LINE_OUT_OF_RANGE",
+          location: site.location,
+          file: site.file,
+          line: site.line,
+          message: `${site.location}.line=${site.line} exceeds the line count (${lineCount}) of ${site.file}`,
+        });
+      }
+    } catch (error) {
+      errors.push({
+        code: "FILE_READ_ERROR",
+        location: site.location,
+        file: site.file,
+        message: `failed to read ${site.file}: ${error instanceof Error ? error.message : String(error)}`,
+      });
+    }
+  }
+  return errors;
+};
+
+const validateNoDuplicates = (discoveries) => {
+  const errors = [];
+  const seen = new Map();
+  const sitesForDuplicateCheck = [];
+  for (const field of SITE_ARRAY_FIELDS) {
+    const arr = isPlainObject(discoveries) ? discoveries[field] : null;
+    if (!Array.isArray(arr)) continue;
+    arr.forEach((site, index) => {
+      if (
+        isPlainObject(site) &&
+        requireString(site.file) &&
+        isPositiveInt(site.line)
+      ) {
+        sitesForDuplicateCheck.push({
+          location: `${field}[${index}]`,
+          file: site.file,
+          line: site.line,
+        });
+      }
+    });
+  }
+  for (const entry of sitesForDuplicateCheck) {
+    const key = `${entry.file}:${entry.line}`;
+    const previous = seen.get(key);
+    if (previous) {
+      errors.push({
+        code: "DUPLICATE_SITE",
+        sites: [previous, entry],
+        message: `duplicate site (file, line) "${key}" at ${previous.location} and ${entry.location}`,
+      });
+    } else {
+      seen.set(key, entry);
+    }
+  }
+  return errors;
+};
+
+const validateEnvFiles = (discoveries) => {
+  if (!isPlainObject(discoveries)) return [];
+  if (!("env_files" in discoveries)) return [];
+  const errors = [];
+  const envFiles = discoveries.env_files;
+  if (!isPlainObject(envFiles)) {
+    errors.push({
+      code: "SCHEMA_VIOLATION",
+      message: "env_files must be a plain object",
+    });
+    return errors;
+  }
+  for (const kind of ["frontend", "backend"]) {
+    if (!(kind in envFiles)) continue;
+    const entry = envFiles[kind];
+    if (entry === null) continue;
+    if (!isPlainObject(entry)) {
+      errors.push({
+        code: "SCHEMA_VIOLATION",
+        message: `env_files.${kind} must be an object or null`,
+      });
+      continue;
+    }
+    if (!requireString(entry.path)) {
+      errors.push({
+        code: "SCHEMA_VIOLATION",
+        message: `env_files.${kind}.path must be a non-empty string`,
+      });
+    }
+    if (entry.format && entry.format !== "dotenv") {
+      errors.push({
+        code: "SCHEMA_VIOLATION",
+        message: `env_files.${kind}.format must be "dotenv" (got "${entry.format}")`,
+      });
+    }
+  }
+  return errors;
+};
+
+// Lines like "NAME=value" where NAME is uppercase ASCII / digits / underscores.
+// Trailing comments / spaces / quotes inside value are allowed.
+const ENV_LINE_PATTERN = /^[A-Z_][A-Z0-9_]*=/;
+const SECRETS_LEAK_PATTERNS = [
+  /^CLUEBASE_API_KEY\s*=/,
+  /^(?:NEXT_PUBLIC|VITE|PUBLIC|NUXT_PUBLIC|REACT_APP)_CLUEBASE_API_KEY\s*=/,
+];
+
+const validateEnvLines = (discoveries) => {
+  if (!isPlainObject(discoveries)) return [];
+  if (!("env_lines" in discoveries)) return [];
+  const errors = [];
+  const envLines = discoveries.env_lines;
+  if (!isPlainObject(envLines)) {
+    errors.push({
+      code: "SCHEMA_VIOLATION",
+      message: "env_lines must be a plain object",
+    });
+    return errors;
+  }
+  for (const kind of ["frontend", "backend"]) {
+    if (!(kind in envLines)) continue;
+    const arr = envLines[kind];
+    if (!Array.isArray(arr)) {
+      errors.push({
+        code: "SCHEMA_VIOLATION",
+        message: `env_lines.${kind} must be an array`,
+      });
+      continue;
+    }
+    arr.forEach((line, idx) => {
+      if (typeof line !== "string") {
+        errors.push({
+          code: "SCHEMA_VIOLATION",
+          message: `env_lines.${kind}[${idx}] must be a string`,
+        });
+        return;
+      }
+      if (!ENV_LINE_PATTERN.test(line)) {
+        errors.push({
+          code: "SCHEMA_VIOLATION",
+          message: `env_lines.${kind}[${idx}] must be a "NAME=value" pair (got "${line.slice(0, 40)}...")`,
+        });
+      }
+    });
+    // Browser-facing env files must never carry server-only secrets.
+    if (kind === "frontend") {
+      arr.forEach((line, idx) => {
+        if (typeof line !== "string") return;
+        for (const pattern of SECRETS_LEAK_PATTERNS) {
+          if (pattern.test(line)) {
+            errors.push({
+              code: "SECRETS_LEAK",
+              message: `env_lines.frontend[${idx}] contains a server-only secret (matched ${pattern}); never expose it via a browser-public env file`,
+            });
+          }
+        }
+      });
+    }
+  }
+  return errors;
+};
+
+const validateSecretsGitignore = async ({ repoRoot }) => {
+  const errors = [];
+  const secretsPath = resolve(repoRoot, ".cluebase/secrets.json");
+  if (!existsSync(secretsPath)) {
+    // secrets.json absent simply means STEP 5 will not have a CLUEBASE_API_KEY
+    // value to auto-write. We surface this in `buildWarnings`, not here.
+    return errors;
+  }
+  const gitignorePath = resolve(repoRoot, ".gitignore");
+  if (!existsSync(gitignorePath)) {
+    errors.push({
+      code: "SECRETS_NOT_IGNORED",
+      message:
+        ".cluebase/secrets.json exists but the repo has no .gitignore. Add `.cluebase/secrets.json` to .gitignore before committing — otherwise the Cluebase API key will leak to the remote.",
+    });
+    return errors;
+  }
+  let gitignoreContent = "";
+  try {
+    gitignoreContent = await readFile(gitignorePath, "utf8");
+  } catch (error) {
+    errors.push({
+      code: "FILE_READ_ERROR",
+      message: `failed to read .gitignore: ${error instanceof Error ? error.message : String(error)}`,
+    });
+    return errors;
+  }
+  const covers = gitignoreContent
+    .split(/\r?\n/)
+    .map((entry) => entry.trim())
+    .some(
+      (entry) =>
+        entry === ".cluebase/secrets.json" ||
+        entry === "/.cluebase/secrets.json" ||
+        entry === ".cluebase" ||
+        entry === ".cluebase/" ||
+        entry === ".cluebase/*" ||
+        entry === "/.cluebase" ||
+        entry === "/.cluebase/" ||
+        entry === "/.cluebase/*",
+    );
+  if (!covers) {
+    errors.push({
+      code: "SECRETS_NOT_IGNORED",
+      message:
+        ".cluebase/secrets.json exists but is NOT registered in .gitignore. Add `.cluebase/secrets.json` to .gitignore before committing — otherwise the Cluebase API key will leak.",
+    });
+  }
+  return errors;
+};
+
+const buildWarnings = (discoveries, { repoRoot } = {}) => {
+  if (!isPlainObject(discoveries)) return [];
+  const warnings = [];
+  if (
+    Array.isArray(discoveries.unclear_points) &&
+    discoveries.unclear_points.length > 0
+  ) {
+    warnings.push({
+      code: "UNCLEAR_POINTS_REMAINING",
+      count: discoveries.unclear_points.length,
+      message: `Discovery reported ${discoveries.unclear_points.length} unclear point(s). Review and resolve before implementation.`,
+    });
+  }
+  if (
+    Array.isArray(discoveries.existing_cluebase_calls) &&
+    discoveries.existing_cluebase_calls.length > 0
+  ) {
+    warnings.push({
+      code: "EXISTING_CLUEBASE_CALLS",
+      count: discoveries.existing_cluebase_calls.length,
+      message: `${discoveries.existing_cluebase_calls.length} existing Cluebase call(s) detected. Implementation must not duplicate them.`,
+    });
+  }
+  // STEP 3 は各 site に `available_fields` / `field_acquisition_notes` を、
+  // discoveries root に `organization_context` を追記する責務。STEP 5 は
+  // これらに基づいて cluebase.identify / cluebase.group の有効 trait を決める。
+  const allSites = [
+    ...(Array.isArray(discoveries.frontend_sites)
+      ? discoveries.frontend_sites
+      : []),
+    ...(Array.isArray(discoveries.backend_sites)
+      ? discoveries.backend_sites
+      : []),
+  ];
+  const sitesMissingAvailableFields = allSites.filter(
+    (site) => isPlainObject(site) && !("available_fields" in site),
+  );
+  const sitesMissingFieldAcquisitionNotes = allSites.filter(
+    (site) => isPlainObject(site) && !("field_acquisition_notes" in site),
+  );
+  const missingOrganizationContext = !("organization_context" in discoveries);
+  const step3Incomplete =
+    sitesMissingAvailableFields.length > 0 ||
+    sitesMissingFieldAcquisitionNotes.length > 0 ||
+    missingOrganizationContext;
+  if (step3Incomplete) {
+    const missingFields = [];
+    if (sitesMissingAvailableFields.length > 0) {
+      missingFields.push(
+        `available_fields (sites=${sitesMissingAvailableFields.length})`,
+      );
+    }
+    if (sitesMissingFieldAcquisitionNotes.length > 0) {
+      missingFields.push(
+        `field_acquisition_notes (sites=${sitesMissingFieldAcquisitionNotes.length})`,
+      );
+    }
+    if (missingOrganizationContext) {
+      missingFields.push("organization_context");
+    }
+    warnings.push({
+      code: "STEP_3_INCOMPLETE",
+      missing: missingFields,
+      message: `STEP 3 context outputs are missing: ${missingFields.join(", ")}. /cluebase-implement will hard stop without them — re-run /cluebase-discover so it can resume from step3_context.`,
+    });
+  }
+  // SECRETS_FILE_MISSING: STEP 5 が CLUEBASE_API_KEY を env file に auto-write
+  // するための値の source (= `.cluebase/secrets.json`) が無い場合。
+  if (repoRoot) {
+    const secretsPath = resolve(repoRoot, ".cluebase/secrets.json");
+    if (!existsSync(secretsPath)) {
+      warnings.push({
+        code: "SECRETS_FILE_MISSING",
+        message:
+          ".cluebase/secrets.json was not generated. STEP 5 will not auto-write CLUEBASE_API_KEY into the backend env file. Re-run `npx -y @genn-inc/cluebase-cli setup ... --cluebase-api-key <key>` with the value from the setup screen, or set CLUEBASE_API_KEY manually in the backend env file.",
+      });
+    }
+  }
+  return warnings;
+};
+
+const pickExitCode = (errors) => {
+  if (errors.length === 0) return SETUP_DISCOVER_CHECK_EXIT_CODES.PASS;
+  let resolvedExit = SETUP_DISCOVER_CHECK_EXIT_CODES.GENERIC_ERROR;
+  for (const error of errors) {
+    const mapped =
+      ERROR_CODE_TO_EXIT[error.code] ??
+      SETUP_DISCOVER_CHECK_EXIT_CODES.GENERIC_ERROR;
+    if (mapped > resolvedExit) resolvedExit = mapped;
+  }
+  return resolvedExit;
+};
+
+// Exported for tests so the validation logic can be exercised without the
+// CLI's filesystem and process integration.
+export const validateDiscoveries = async ({
+  discoveries,
+  manifest = null,
+  repoRoot,
+}) => {
+  const errors = [];
+  const schemaErrors = validateSchema(discoveries);
+  errors.push(...schemaErrors);
+  // env_files / env_lines は type check のみで、不在は warning レベル
+  // (= buildWarnings) で扱う。
+  // SECRETS_LEAK だけは P0 error (= browser env に CLUEBASE_API_KEY が混入したら setup 不可)。
+  errors.push(...validateEnvFiles(discoveries));
+  errors.push(...validateEnvLines(discoveries));
+  if (schemaErrors.length === 0) {
+    errors.push(...validateManifestConsistency(discoveries, manifest));
+    errors.push(...(await validateFileExistence({ discoveries, repoRoot })));
+    errors.push(...validateNoDuplicates(discoveries));
+    errors.push(...(await validateSecretsGitignore({ repoRoot })));
+  }
+  const warnings = buildWarnings(discoveries, { repoRoot });
+  const passed = errors.length === 0;
+  return {
+    passed,
+    errors,
+    warnings,
+    exit_code: pickExitCode(errors),
+  };
+};
+
+const readJsonFile = async (path) => JSON.parse(await readFile(path, "utf8"));
+
+// Public entrypoint used by bin/cluebase-cli.mjs.
+export const runSetupDiscoverCheck = async ({
+  manifestPath,
+  discoveriesPath,
+  repoRoot,
+}) => {
+  let manifest = null;
+  let manifestReadError = null;
+  if (requireString(manifestPath)) {
+    const resolvedManifestPath = isAbsolute(manifestPath)
+      ? manifestPath
+      : resolve(repoRoot, manifestPath);
+    try {
+      manifest = await readJsonFile(resolvedManifestPath);
+    } catch (error) {
+      manifestReadError = error;
+    }
+  }
+  if (!requireString(discoveriesPath)) {
+    return {
+      passed: false,
+      errors: [
+        {
+          code: "GENERIC_ERROR",
+          message: "--discoveries path is required",
+        },
+      ],
+      warnings: [],
+      exit_code: SETUP_DISCOVER_CHECK_EXIT_CODES.GENERIC_ERROR,
+    };
+  }
+  const resolvedDiscoveriesPath = isAbsolute(discoveriesPath)
+    ? discoveriesPath
+    : resolve(repoRoot, discoveriesPath);
+  let discoveries;
+  try {
+    discoveries = await readJsonFile(resolvedDiscoveriesPath);
+  } catch (error) {
+    return {
+      passed: false,
+      errors: [
+        {
+          code: "GENERIC_ERROR",
+          message: `failed to read discoveries JSON: ${error instanceof Error ? error.message : String(error)}`,
+        },
+      ],
+      warnings: [],
+      exit_code: SETUP_DISCOVER_CHECK_EXIT_CODES.GENERIC_ERROR,
+    };
+  }
+  const result = await validateDiscoveries({
+    discoveries,
+    manifest,
+    repoRoot,
+  });
+  if (manifestReadError) {
+    return {
+      ...result,
+      errors: [
+        {
+          code: "GENERIC_ERROR",
+          message: `failed to read manifest JSON: ${manifestReadError instanceof Error ? manifestReadError.message : String(manifestReadError)}`,
+        },
+        ...result.errors,
+      ],
+      passed: false,
+      exit_code: Math.max(
+        result.exit_code,
+        SETUP_DISCOVER_CHECK_EXIT_CODES.GENERIC_ERROR,
+      ),
+    };
+  }
+  return result;
+};