@genn-inc/cluebase-cli 0.0.1

package/src/setup-doctor-deadline.mjs

@@ -0,0 +1,221 @@
+import {
+  clearTimeout as clearDeadlineTimeout,
+  setTimeout as setDeadlineTimeout,
+} from "node:timers";
+
+export const DEFAULT_SETUP_DOCTOR_DEADLINE_MS = 180_000;
+export const MAX_SETUP_DOCTOR_DEADLINE_MS = 2_147_483_647;
+export const SETUP_DOCTOR_DEADLINE_ENV = "CLUEBASE_SETUP_DOCTOR_DEADLINE_MS";
+export const SETUP_DOCTOR_DEADLINE_ERROR_CODE =
+  "SETUP_DOCTOR_DEADLINE_EXCEEDED";
+
+export const readSetupDoctorDeadlineConfig = () => {
+  const raw = process.env[SETUP_DOCTOR_DEADLINE_ENV];
+  if (!raw) {
+    return { deadlineMs: DEFAULT_SETUP_DOCTOR_DEADLINE_MS, error: null };
+  }
+  const parsed = Number(raw);
+  if (
+    !Number.isSafeInteger(parsed) ||
+    parsed <= 0 ||
+    parsed > MAX_SETUP_DOCTOR_DEADLINE_MS
+  ) {
+    return {
+      deadlineMs: DEFAULT_SETUP_DOCTOR_DEADLINE_MS,
+      error: `${SETUP_DOCTOR_DEADLINE_ENV} must be a positive safe integer no greater than ${MAX_SETUP_DOCTOR_DEADLINE_MS}.`,
+    };
+  }
+  return { deadlineMs: parsed, error: null };
+};
+
+export const setupDoctorDeadlineCheck = (config) =>
+  config.error
+    ? {
+        id: "setup_deadline_config",
+        name: "setup-doctor overall deadline configuration",
+        severity: "error",
+        passed: false,
+        error: config.error,
+        env_var: SETUP_DOCTOR_DEADLINE_ENV,
+        deadline_ms: config.deadlineMs,
+      }
+    : null;
+
+export const setupDoctorDeadlineError = () => {
+  const error = new Error("setup-doctor deadline exceeded");
+  error.code = SETUP_DOCTOR_DEADLINE_ERROR_CODE;
+  return error;
+};
+
+export const isSetupDoctorDeadlineError = (error) =>
+  error?.code === SETUP_DOCTOR_DEADLINE_ERROR_CODE;
+
+export const throwIfSetupDoctorDeadlineExceeded = (signal, error = null) => {
+  if (
+    signal?.aborted ||
+    (signal && (error?.name === "AbortError" || error?.code === "ABORT_ERR"))
+  ) {
+    throw setupDoctorDeadlineError();
+  }
+};
+
+export const runSetupDoctorStage = async (stage, signal) => {
+  throwIfSetupDoctorDeadlineExceeded(signal);
+  const result = await stage();
+  throwIfSetupDoctorDeadlineExceeded(signal);
+  return result;
+};
+
+export const setupDoctorDeadlineFailureReport = ({ deadlineMs, contract }) => ({
+  status: "failed",
+  passed: false,
+  contract,
+  checks: [
+    {
+      id: "setup_deadline",
+      name: "setup-doctor overall deadline",
+      severity: "error",
+      passed: false,
+      error: "setup-doctor overall deadline exceeded.",
+      deadline_ms: deadlineMs,
+    },
+  ],
+  qualityChecks: [],
+  qualityCheckSummary: null,
+  summary: {
+    apiConnectivity: { total: 1, failed: 1, passed: false },
+    doctrineWarnings: { total: 0, failed: 0 },
+    dataQuality: null,
+  },
+  inputs: {
+    manifest_loaded: false,
+    client_frontend_url_configured: false,
+    origin_configured: false,
+    cluebase_api_base_url_configured: false,
+    project_key_configured: false,
+    frontend_project_key_configured: false,
+    backend_project_key_configured: false,
+    frontend_cluebase_api_base_url_configured: false,
+    backend_ingest_url_configured: false,
+    environment_configured: false,
+    backend_service_key_configured: false,
+    cluebase_api_key_configured: false,
+    env_files_loaded: [],
+    frontend_env_files_loaded: [],
+    backend_env_files_loaded: [],
+  },
+});
+
+export const requestWithSetupDoctorDeadline = ({
+  fetchImpl,
+  options,
+  signal,
+  url,
+}) => {
+  if (!signal) return fetchImpl(url, options);
+  if (signal.aborted) return Promise.reject(setupDoctorDeadlineError());
+
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    let onAbort;
+    const cleanup = () => signal.removeEventListener("abort", onAbort);
+    const finish = (handler, value) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      handler(value);
+    };
+    onAbort = () => finish(reject, setupDoctorDeadlineError());
+
+    signal.addEventListener("abort", onAbort, { once: true });
+    Promise.resolve()
+      .then(() => fetchImpl(url, { ...options, signal }))
+      .then(
+        (response) => finish(resolve, response),
+        (error) => finish(reject, error),
+      );
+  });
+};
+
+export const waitForSetupDoctorPollInterval = (intervalMs, signal) => {
+  if (!signal) {
+    return new Promise((resolve) => setTimeout(() => resolve(true), intervalMs));
+  }
+  if (signal.aborted) return Promise.resolve(false);
+
+  return new Promise((resolve) => {
+    let settled = false;
+    let timer = null;
+    let onAbort;
+    const cleanup = () => signal.removeEventListener("abort", onAbort);
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      cleanup();
+      resolve(value);
+    };
+    onAbort = () => finish(false);
+    signal.addEventListener("abort", onAbort, { once: true });
+    timer = setTimeout(() => finish(true), intervalMs);
+  });
+};
+
+export const createSetupDoctorDeadlineFetch = ({
+  deadlineCheck,
+  fetchImpl,
+  signal,
+}) => {
+  const deadlineFetch = (url, options) =>
+    requestWithSetupDoctorDeadline({
+      fetchImpl,
+      options,
+      signal,
+      url,
+    });
+  return Object.assign(deadlineFetch, {
+    deadlineCheck,
+    runStage: (stage) => runSetupDoctorStage(stage, signal),
+    signal,
+    waitForPollInterval: (intervalMs) =>
+      waitForSetupDoctorPollInterval(intervalMs, signal),
+  });
+};
+
+export const withSetupDoctorDeadline = (run, contract = null) => async (args) => {
+  const setupDeadlineConfig = readSetupDoctorDeadlineConfig();
+  const controller = new AbortController();
+  const deadlineCheck = setupDoctorDeadlineCheck(setupDeadlineConfig);
+  const runPromise = Promise.resolve().then(() =>
+    run({
+      ...args,
+      signal: controller.signal,
+      fetchImpl: createSetupDoctorDeadlineFetch({
+        deadlineCheck,
+        fetchImpl: args.fetchImpl ?? fetch,
+        signal: controller.signal,
+      }),
+    }),
+  );
+  let deadlineTimer;
+  const deadlinePromise = new Promise((_, reject) => {
+    deadlineTimer = setDeadlineTimeout(() => {
+      controller.abort();
+      reject(setupDoctorDeadlineError());
+    }, setupDeadlineConfig.deadlineMs);
+  });
+
+  try {
+    return await Promise.race([runPromise, deadlinePromise]);
+  } catch (error) {
+    if (!isSetupDoctorDeadlineError(error) || !controller.signal.aborted) throw error;
+    return setupDoctorDeadlineFailureReport({
+      contract,
+      deadlineMs: setupDeadlineConfig.deadlineMs,
+    });
+  } finally {
+    clearDeadlineTimeout(deadlineTimer);
+    controller.abort();
+    void runPromise.catch(() => {});
+  }
+};

package/src/setup-doctor-env.mjs

@@ -0,0 +1,331 @@
+// setup-doctor env / URL / dotenv helpers.
+// Extracted from setup-doctor for file-size limits; content is unchanged.
+
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { API_CONNECTIVITY_CONTRACT } from "./setup-ai-contract.mjs";
+import {
+  readSetupDoctorFile,
+  readSetupDoctorJson,
+} from "./setup-doctor-file-boundary.mjs";
+
+export const DEFAULT_SETUP_MANIFEST_PATH = ".cluebase/setup-manifest.json";
+export const CLUEBASE_BROWSER_TOKEN_PATH =
+  API_CONNECTIVITY_CONTRACT.hops.cluebase_backend_browser_token_issue.path;
+export const BROWSER_INGEST_PATH = API_CONNECTIVITY_CONTRACT.hops.browser_ingest.path;
+export const BACKEND_INGEST_PATH = API_CONNECTIVITY_CONTRACT.hops.backend_ingest.path;
+export const BATCH_STATUS_PATH = API_CONNECTIVITY_CONTRACT.hops.batch_status.path;
+export const CLUEBASE_TEST_SETUP_SDK_VERSION = "cluebase_test_setup";
+export const FRONTEND_SOURCE_IDENTIFIER = "frontend";
+export const DEFAULT_BATCH_VISIBILITY_TIMEOUT_MS = 60_000;
+export const BATCH_VISIBILITY_POLL_INTERVAL_MS = 500;
+export const DOCTOR_ENV_FILE_NAMES = [
+  ".env",
+  ".env.development",
+  ".env.local",
+  ".env.development.local",
+];
+
+// Frontend SDK calls Cluebase backend directly. Customer backends must not expose
+// Cluebase-specific route handlers.
+export const CLUEBASE_RESERVED_ROUTE_PATTERN =
+  /(?:["'`])(?:\/api\/v1)?\/cluebase(?:\/|["'`)]|$)|\/api\/v1\/cluebase(?:\/|$)/i;
+export const BROWSER_TOKEN_PROXY_HINT_PATTERN =
+  /browser[-_]?tokens?|\/api\/v1\/ingest\/browser-tokens/i;
+export const ROUTE_DECLARATION_PATTERN =
+  /(?:@(?:router|app)\.(?:get|post|put|patch|delete)|\b(?:router|app)\.(?:get|post|put|patch|delete)\s*\(|@Controller\s*\(|path\s*\(|Route::(?:get|post|put|patch|delete)\s*\(|http\.HandleFunc\s*\()/i;
+export const PROXY_SCAN_FILE_EXTENSIONS = new Set([
+  ".py",
+  ".ts",
+  ".tsx",
+  ".js",
+  ".jsx",
+  ".mjs",
+  ".cjs",
+  ".go",
+  ".rb",
+  ".java",
+  ".kt",
+  ".cs",
+  ".php",
+  ".rs",
+  ".ex",
+  ".exs",
+]);
+export const PROXY_SCAN_EXCLUDED_PATHS = [".cluebase", "out", "target", ".turbo"];
+export const PROXY_SCAN_MAX_FILES = 2000;
+
+export const optionalString = (value) =>
+  typeof value === "string" && value.trim() ? value.trim() : null;
+
+export const trimTrailingSlash = (value) => String(value).replace(/\/+$/, "");
+
+export const isPlainObject = (value) =>
+  value !== null && typeof value === "object" && !Array.isArray(value);
+
+export const normalizeCluebaseApiBaseUrl = (baseUrl) =>
+  trimTrailingSlash(baseUrl).replace(/\/api\/v1$/i, "");
+
+export const readBatchVisibilityTimeoutConfig = () => {
+  const raw = process.env.CLUEBASE_SETUP_VERIFICATION_BATCH_TIMEOUT_MS;
+  if (!raw) {
+    return { timeoutMs: DEFAULT_BATCH_VISIBILITY_TIMEOUT_MS, error: null };
+  }
+  const parsed = Number(raw);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    return {
+      timeoutMs: DEFAULT_BATCH_VISIBILITY_TIMEOUT_MS,
+      error:
+        "CLUEBASE_SETUP_VERIFICATION_BATCH_TIMEOUT_MS must be a positive integer.",
+    };
+  }
+  return { timeoutMs: Math.max(1_000, parsed), error: null };
+};
+
+export const joinUrl = (baseUrl, path) => `${normalizeCluebaseApiBaseUrl(baseUrl)}${path}`;
+
+export const batchStatusPathFor = (batchId) =>
+  BATCH_STATUS_PATH.replace(":batchId", encodeURIComponent(batchId));
+
+export const BATCH_STATUS_PLACEHOLDER_PATH = BATCH_STATUS_PATH.replace(
+  ":batchId",
+  "<batchId>",
+);
+
+export const publicCluebaseApiBaseUrl = (env) =>
+  optionalString(env.NEXT_PUBLIC_CLUEBASE_API_BASE_URL) ??
+  optionalString(env.VITE_CLUEBASE_API_BASE_URL) ??
+  optionalString(env.REACT_APP_CLUEBASE_API_BASE_URL) ??
+  optionalString(env.PUBLIC_CLUEBASE_API_BASE_URL) ??
+  optionalString(env.NUXT_PUBLIC_CLUEBASE_API_BASE_URL);
+
+export const publicProjectKeyFromEnv = (env) =>
+  optionalString(env.NEXT_PUBLIC_CLUEBASE_PROJECT_KEY) ??
+  optionalString(env.VITE_CLUEBASE_PROJECT_KEY) ??
+  optionalString(env.REACT_APP_CLUEBASE_PROJECT_KEY) ??
+  optionalString(env.PUBLIC_CLUEBASE_PROJECT_KEY) ??
+  optionalString(env.NUXT_PUBLIC_CLUEBASE_PROJECT_KEY);
+
+export const cluebaseApiBaseUrlFromIngestEndpoint = (endpoint) => {
+  const raw = optionalString(endpoint);
+  if (!raw) return null;
+  const trimmed = trimTrailingSlash(raw);
+  const base = trimmed.replace(/\/api\/v1\/ingest\/(?:backend|browser)$/i, "");
+  return base === trimmed ? null : base;
+};
+
+export const normalizeBrowserIngestUrl = (url) => {
+  const raw = optionalString(url);
+  if (!raw) return null;
+
+  try {
+    const parsed = new URL(raw);
+    if (
+      parsed.pathname === "" ||
+      parsed.pathname === "/" ||
+      parsed.pathname.replace(/\/+$/, "") === "/api/v1"
+    ) {
+      parsed.pathname = BROWSER_INGEST_PATH;
+      parsed.search = "";
+      parsed.hash = "";
+      return parsed.toString();
+    }
+    return parsed.toString();
+  } catch {
+    const trimmed = trimTrailingSlash(raw);
+    if (trimmed.endsWith("/api/v1")) {
+      return `${trimmed.slice(0, -"/api/v1".length)}${BROWSER_INGEST_PATH}`;
+    }
+    return raw;
+  }
+};
+
+export const manifestDetectedServices = (manifest, kind) => {
+  const targets = manifest?.detected_services;
+  if (!Array.isArray(targets)) return [];
+  return kind
+    ? targets.filter((target) => target?.kind === kind)
+    : targets.filter(isPlainObject);
+};
+
+export const firstTargetUrl = ({ manifest, kind }) => {
+  for (const target of manifestDetectedServices(manifest, kind)) {
+    const explicitUrl = optionalString(target.url);
+    if (explicitUrl) return explicitUrl;
+    const localUrl = Array.isArray(target.local_url_candidates)
+      ? target.local_url_candidates.map(optionalString).find(Boolean)
+      : null;
+    if (localUrl) return localUrl;
+  }
+  return null;
+};
+
+export const stripDotenvInlineComment = (value) => {
+  let quote = null;
+  for (let index = 0; index < value.length; index += 1) {
+    const char = value[index];
+    if ((char === "'" || char === '"') && value[index - 1] !== "\\") {
+      quote = quote === char ? null : (quote ?? char);
+    }
+    if (char === "#" && quote === null && /\s/.test(value[index - 1] ?? "")) {
+      return value.slice(0, index).trimEnd();
+    }
+  }
+  return value;
+};
+
+export const unquoteDotenvValue = (value) => {
+  const trimmed = stripDotenvInlineComment(value.trim());
+  if (trimmed.length < 2) return trimmed;
+  const quote = trimmed[0];
+  if (
+    (quote !== "'" && quote !== '"') ||
+    trimmed[trimmed.length - 1] !== quote
+  ) {
+    return trimmed;
+  }
+  const inner = trimmed.slice(1, -1);
+  if (quote === "'") return inner;
+  return inner
+    .replace(/\\n/g, "\n")
+    .replace(/\\r/g, "\r")
+    .replace(/\\t/g, "\t")
+    .replace(/\\"/g, '"')
+    .replace(/\\\\/g, "\\");
+};
+
+export const parseDotenv = (content) => {
+  const result = {};
+  for (const rawLine of String(content).split(/\r?\n/)) {
+    let line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+    if (line.startsWith("export "))
+      line = line.slice("export ".length).trimStart();
+    const match = /^([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(line);
+    if (!match) continue;
+    result[match[1]] = unquoteDotenvValue(match[2]);
+  }
+  return result;
+};
+
+export const relativeInsideRepo = ({ path, repoRoot }) => {
+  const rawPath = String(path ?? "");
+  if (rawPath.split(/[\\/]+/).filter(Boolean).includes("..")) return null;
+  const absolutePath = isAbsolute(path)
+    ? resolve(path)
+    : resolve(repoRoot, path);
+  const relativePath = relative(repoRoot, absolutePath);
+  if (
+    relativePath.startsWith("..") ||
+    isAbsolute(relativePath)
+  ) {
+    return null;
+  }
+  return relativePath || ".";
+};
+
+export const addEnvCandidate = ({ candidates, path, repoRoot }) => {
+  const relPath = optionalString(path);
+  if (!relPath) return;
+  const insidePath = relativeInsideRepo({ repoRoot, path: relPath });
+  if (insidePath) candidates.add(insidePath);
+};
+
+export const envRootsFromManifest = (manifest, kind) => {
+  const roots = [];
+  if (kind === "backend") {
+    const detectedBackendRoot = optionalString(
+      manifest?.detected?.backend_root_path,
+    );
+    if (detectedBackendRoot) roots.push(detectedBackendRoot);
+  }
+  for (const target of manifestDetectedServices(manifest, kind)) {
+    const root = optionalString(target.root_path ?? target.path);
+    if (root) roots.push(root);
+  }
+  return [...new Set(roots)].flatMap((root) => {
+    const expanded = [root];
+    if (root.endsWith("/src") || root.endsWith("/app")) {
+      expanded.push(dirname(root));
+    }
+    return expanded;
+  });
+};
+
+export const envFileCandidates = ({ discoveries, kind, manifest, repoRoot }) => {
+  const candidates = new Set();
+  if (isPlainObject(discoveries?.env_files)) {
+    const entry = discoveries.env_files[kind];
+    if (isPlainObject(entry)) {
+      addEnvCandidate({ candidates, path: entry.path, repoRoot });
+    }
+  }
+  for (const name of DOCTOR_ENV_FILE_NAMES) {
+    addEnvCandidate({ candidates, path: name, repoRoot });
+  }
+  for (const root of envRootsFromManifest(manifest, kind)) {
+    for (const name of DOCTOR_ENV_FILE_NAMES) {
+      addEnvCandidate({ candidates, path: join(root, name), repoRoot });
+    }
+  }
+  return [...candidates];
+};
+
+export const loadDoctorEnvFiles = async ({
+  discoveries,
+  kind,
+  manifest,
+  repoRoot,
+  signal,
+}) => {
+  const fileEnv = {};
+  const loadedFiles = [];
+  for (const relPath of envFileCandidates({
+    discoveries,
+    kind,
+    manifest,
+    repoRoot,
+  })) {
+    const content = await readSetupDoctorFile({
+      repoRoot,
+      path: relPath,
+      signal,
+      optional: true,
+    });
+    if (content === null) continue;
+    Object.assign(fileEnv, parseDotenv(content));
+    loadedFiles.push(relPath);
+  }
+  return { env: fileEnv, loadedFiles };
+};
+
+export const loadDoctorEnv = async ({ manifest, repoRoot, signal }) => {
+  const discoveries = await readSetupDoctorJson({
+    repoRoot,
+    path: ".cluebase/discoveries.json",
+    signal,
+    optional: true,
+  });
+  const frontend = await loadDoctorEnvFiles({
+    discoveries,
+    kind: "frontend",
+    manifest,
+    repoRoot,
+    signal,
+  });
+  const backend = await loadDoctorEnvFiles({
+    discoveries,
+    kind: "backend",
+    manifest,
+    repoRoot,
+    signal,
+  });
+  return {
+    frontendEnv: frontend.env,
+    backendEnv: backend.env,
+    frontendLoadedFiles: frontend.loadedFiles,
+    backendLoadedFiles: backend.loadedFiles,
+    loadedFiles: [
+      ...new Set([...frontend.loadedFiles, ...backend.loadedFiles]),
+    ],
+  };
+};