@genn-inc/cluebase-cli 0.0.1

package/src/setup-doctor-route-scan.mjs

@@ -0,0 +1,160 @@
+// setup-doctor customer-backend Cluebase route scan.
+// Extracted from setup-doctor for file-size limits; content is unchanged.
+
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { isExcludedSourcePath } from "./path-policy.mjs";
+import { throwIfSetupDoctorDeadlineExceeded } from "./setup-doctor-deadline.mjs";
+import {
+  readSetupDoctorFile,
+  validateSetupDoctorDirectory,
+} from "./setup-doctor-file-boundary.mjs";
+import {
+  CLUEBASE_RESERVED_ROUTE_PATTERN,
+  BROWSER_TOKEN_PROXY_HINT_PATTERN,
+  ROUTE_DECLARATION_PATTERN,
+  PROXY_SCAN_FILE_EXTENSIONS,
+  PROXY_SCAN_EXCLUDED_PATHS,
+  PROXY_SCAN_MAX_FILES,
+  optionalString,
+  manifestDetectedServices,
+  relativeInsideRepo,
+} from "./setup-doctor-env.mjs";
+
+export const requiredInputCheck = ({ id, missing, url = null }) => ({
+  id,
+  severity: "error",
+  method: "POST",
+  url,
+  passed: false,
+  status: null,
+  error: `missing required input: ${missing.join(", ")}`,
+});
+
+export const fileExtension = (filePath) => {
+  const dot = filePath.lastIndexOf(".");
+  if (dot < 0) return "";
+  return filePath.slice(dot).toLowerCase();
+};
+
+export const pathLooksLikeCustomerBackendCluebaseRoute = (path) =>
+  path
+    .split(/[\\/]+/)
+    .map((part) => part.toLowerCase())
+    .join("/")
+    .includes("api/v1/cluebase/");
+
+export const containsCustomerBackendCluebaseRoute = (text) =>
+  (ROUTE_DECLARATION_PATTERN.test(text) &&
+    CLUEBASE_RESERVED_ROUTE_PATTERN.test(text)) ||
+  (BROWSER_TOKEN_PROXY_HINT_PATTERN.test(text) &&
+    ROUTE_DECLARATION_PATTERN.test(text));
+
+// Walk customer backend directories and collect files that appear to define a
+// Cluebase-specific route handler. Setup requires direct browser-to-Cluebase token
+// issuance, so customer backends should not own this route surface.
+export const collectCustomerBackendCluebaseRouteFiles = async ({
+  repoRoot = ".",
+  rootAbs,
+  limit = PROXY_SCAN_MAX_FILES,
+  signal,
+}) => {
+  const matched = [];
+  let scanned = 0;
+  let truncated = false;
+  const walk = async (dirAbs, relPath) => {
+    throwIfSetupDoctorDeadlineExceeded(signal);
+    if (scanned >= limit) {
+      truncated = true;
+      return;
+    }
+    let entries;
+    try {
+      const directory = await validateSetupDoctorDirectory({
+        repoRoot,
+        path: dirAbs,
+        signal,
+      });
+      entries = await readdir(directory.absolutePath, { withFileTypes: true });
+    } catch (error) {
+      throwIfSetupDoctorDeadlineExceeded(signal, error);
+      truncated = true;
+      return;
+    }
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+      if (scanned >= limit) {
+        truncated = true;
+        return;
+      }
+      if (entry.name.startsWith(".") && entry.name !== ".env") continue;
+      const childAbs = join(dirAbs, entry.name);
+      const childRel = relPath ? join(relPath, entry.name) : entry.name;
+      if (isExcludedSourcePath(childRel, PROXY_SCAN_EXCLUDED_PATHS)) continue;
+      if (entry.isDirectory()) {
+        await walk(childAbs, childRel);
+        continue;
+      }
+      if (!entry.isFile()) {
+        truncated = true;
+        continue;
+      }
+      const ext = fileExtension(entry.name);
+      if (!PROXY_SCAN_FILE_EXTENSIONS.has(ext)) continue;
+      let text;
+      try {
+        text = await readSetupDoctorFile({
+          repoRoot,
+          path: childAbs,
+          signal,
+        });
+      } catch (error) {
+        throwIfSetupDoctorDeadlineExceeded(signal, error);
+        truncated = true;
+        continue;
+      }
+      if (pathLooksLikeCustomerBackendCluebaseRoute(childRel)) {
+        matched.push(childRel);
+        continue;
+      }
+      scanned += 1;
+      throwIfSetupDoctorDeadlineExceeded(signal);
+      if (containsCustomerBackendCluebaseRoute(text)) {
+        matched.push(childRel);
+      }
+    }
+  };
+  throwIfSetupDoctorDeadlineExceeded(signal);
+  await walk(rootAbs, "");
+  throwIfSetupDoctorDeadlineExceeded(signal);
+  return { files: matched, scanned, truncated };
+};
+
+export const resolveBackendRootCandidates = ({ flags, manifest, repoRoot }) => {
+  const flagRoot = optionalString(flags.get("backend-root-path"));
+  if (flagRoot) {
+    const relativeRoot = relativeInsideRepo({ path: flagRoot, repoRoot });
+    return [relativeRoot]
+      .filter(Boolean)
+      .map((root) => root);
+  }
+  const detectedRoot = optionalString(manifest?.detected?.backend_root_path);
+  if (detectedRoot) {
+    const relativeRoot = relativeInsideRepo({ path: detectedRoot, repoRoot });
+    return [relativeRoot]
+      .filter(Boolean)
+      .map((root) => root);
+  }
+  const backendTargets = manifestDetectedServices(manifest, "backend");
+  const targetRoots = backendTargets
+    .map((target) => optionalString(target.root_path ?? target.path))
+    .filter(Boolean)
+    .flatMap((path) => {
+      const relativeRoot = relativeInsideRepo({ path, repoRoot });
+      return [relativeRoot]
+        .filter(Boolean)
+        .map((root) => root);
+    });
+  if (targetRoots.length > 0) return targetRoots;
+  return [];
+};

package/src/setup-doctor-sdk-probe.mjs

@@ -0,0 +1,340 @@
+// Backend SDK real-import probe for setup-doctor.
+//
+// The static (grep-based) setup-check only sees the source text; it cannot tell
+// that the customer's INSTALLED `cluebase-backend-sdk` actually provides the
+// `cluebase` facade the STEP 5 code calls. A published version that predates the
+// facade (e.g. 0.1.1) passes the grep check yet crashes the customer backend at
+// import time. This probe runs the real `from cluebase_backend_sdk import cluebase`
+// import in the customer's Python so that drift surfaces as an actionable
+// failure instead of a false OK. It never weakens any other check.
+
+import { execFile } from "node:child_process";
+import { basename, join } from "node:path";
+import { promisify } from "node:util";
+import {
+	setupDoctorDeadlineError,
+	throwIfSetupDoctorDeadlineExceeded,
+} from "./setup-doctor-deadline.mjs";
+import {
+	isSetupDoctorFileBoundaryError,
+	prepareSetupDoctorPythonProbe,
+	readSetupDoctorJson,
+} from "./setup-doctor-file-boundary.mjs";
+
+const execFileAsync = promisify(execFile);
+
+export const MIN_BACKEND_SDK_VERSION = "0.0.1";
+
+// FastAPI / Django / Flask are the Python backends whose STEP 5 wiring imports
+// the `cluebase` facade from `cluebase_backend_sdk`. Node backends use the separate
+// `@genn-inc/cluebase-backend-sdk` package and are out of scope for this Python probe.
+export const PYTHON_BACKEND_FRAMEWORKS = ["fastapi", "django", "flask"];
+
+const BACKEND_SDK_IMPORT_CODE = "from cluebase_backend_sdk import cluebase";
+
+const isUnreadablePythonError = (error) =>
+	error?.code === "EACCES" || error?.code === "EPERM";
+
+export const backendFrameworksFromManifest = (manifest) => {
+	const selected = Array.isArray(manifest?.documentation?.selected_frameworks)
+		? manifest.documentation.selected_frameworks
+		: [];
+	const detected =
+		typeof manifest?.detected?.framework === "string"
+			? [manifest.detected.framework]
+			: [];
+	return [...selected, ...detected].map((value) => String(value).toLowerCase());
+};
+
+export const manifestHasPythonBackend = (manifest) =>
+	backendFrameworksFromManifest(manifest).some((framework) =>
+		PYTHON_BACKEND_FRAMEWORKS.includes(framework),
+	);
+
+// Node backends wire `@genn-inc/cluebase-backend-sdk`, whose instrumentation must be
+// preloaded before the server modules are loaded.
+export const NODE_BACKEND_FRAMEWORKS = [
+	"express",
+	"nestjs",
+	"fastify",
+	"koa",
+	"hono",
+];
+
+// Backend frameworks across languages. Used to decide whether the doctor's
+// backend-specific hops apply at all: a frontend-only setup (SPA + static /
+// serverless hosting, no backend) has no backend ingest and no customer
+// backend that could expose a Cluebase proxy route.
+export const BACKEND_FRAMEWORKS = [
+	...PYTHON_BACKEND_FRAMEWORKS,
+	...NODE_BACKEND_FRAMEWORKS,
+];
+
+export const manifestHasNodeBackend = (manifest) =>
+	backendFrameworksFromManifest(manifest).some((framework) =>
+		NODE_BACKEND_FRAMEWORKS.includes(framework),
+	);
+
+export const manifestHasBackend = (manifest) => {
+	const backendRootPath = manifest?.detected?.backend_root_path;
+	if (typeof backendRootPath === "string" && backendRootPath.trim()) {
+		return true;
+	}
+	return backendFrameworksFromManifest(manifest).some((framework) =>
+		BACKEND_FRAMEWORKS.includes(framework),
+	);
+};
+
+// Candidate Python interpreters, venv first (customer installs into a venv far
+// more often than into system site-packages), then the bare commands.
+export const pythonInterpreterCandidates = ({ repoRoot, backendRootPath }) => {
+	const roots = [];
+	if (typeof backendRootPath === "string" && backendRootPath.trim()) {
+		roots.push(join(repoRoot, backendRootPath));
+	}
+	roots.push(repoRoot);
+	const venvPythons = roots.flatMap((root) => [
+		join(root, ".venv", "bin", "python"),
+		join(root, "venv", "bin", "python"),
+	]);
+	return [...venvPythons, "python3", "python"];
+};
+
+const classifyImportFailure = (stderr) => {
+	const text = String(stderr ?? "");
+	if (/No module named ['"]cluebase_backend_sdk['"]/.test(text)) {
+		return "not_installed";
+	}
+	if (/cannot import name ['"]cluebase['"]/.test(text)) {
+		return "facade_missing";
+	}
+	return "unknown";
+};
+
+// Runs the import in the first interpreter that actually executes. `runPython`
+// is injectable for tests: it resolves to { code, stdout, stderr } and throws
+// (e.g. ENOENT) when the interpreter is not runnable.
+export const probeBackendSdkImport = async ({
+	repoRoot,
+	backendRootPath,
+	signal,
+	runPython = (python, code, options = {}) =>
+		execFileAsync(python, ["-c", code], options)
+			.then(() => ({ code: 0, stdout: "", stderr: "" }))
+			.catch((error) => {
+				if (error?.code === "ENOENT" || isUnreadablePythonError(error)) {
+					throw error;
+				}
+				return {
+					code: typeof error?.code === "number" ? error.code : 1,
+					stdout: String(error?.stdout ?? ""),
+					stderr: String(error?.stderr ?? error?.message ?? ""),
+				};
+			}),
+	candidates,
+} = {}) => {
+	let secured;
+	try {
+		secured = await prepareSetupDoctorPythonProbe({
+			repoRoot,
+			backendRootPath,
+			candidates,
+			createCandidates: pythonInterpreterCandidates,
+			signal,
+		});
+	} catch (error) {
+		throwIfSetupDoctorDeadlineExceeded(signal, error);
+		if (isSetupDoctorFileBoundaryError(error)) {
+			return { status: "invalid_path" };
+		}
+		throw error;
+	}
+
+	for (const { candidate, executable } of secured.candidates) {
+		throwIfSetupDoctorDeadlineExceeded(signal);
+		let result;
+		try {
+			result = await runPython(executable, BACKEND_SDK_IMPORT_CODE, { signal });
+		} catch (error) {
+			if (signal?.aborted) throw setupDoctorDeadlineError();
+			if (error?.code === "ENOENT") continue;
+			if (isUnreadablePythonError(error)) return { status: "invalid_path" };
+			throw error;
+		}
+		throwIfSetupDoctorDeadlineExceeded(signal);
+		if (result.code === 0) {
+			return { status: "ok", python: basename(candidate) };
+		}
+		return {
+			status: classifyImportFailure(result.stderr),
+			python: basename(candidate),
+		};
+	}
+	return { status: "python_unavailable" };
+};
+
+// Node instrumentation patches a module while it is being loaded, so it cannot
+// reach a module that has already been loaded. `cluebase.init(...)` runs in the
+// body of the entry file, after `express` / `pg` are evaluated, so the
+// instrumentation has to be preloaded instead. Nothing in the source text
+// reveals whether that happened — the customer's server starts fine and simply
+// records nothing — which is why this reads the start commands.
+export const CLUEBASE_REGISTER_SPECIFIER = "@genn-inc/cluebase-backend-sdk/register";
+
+const CLUEBASE_PRELOAD_PATTERN =
+	/--(?:import|require)(?:[=\s]+)['"]?@genn-inc\/cluebase-backend-sdk\/register['"]?/;
+
+const isServerStartScriptName = (name) =>
+	name === "dev" || name === "start" || name.startsWith("start:");
+
+export const probeNodeBackendPreload = async ({
+	repoRoot,
+	backendRootPath,
+	nodeOptions,
+	signal,
+	readJson = readSetupDoctorJson,
+} = {}) => {
+	if (typeof nodeOptions === "string" && CLUEBASE_PRELOAD_PATTERN.test(nodeOptions)) {
+		return { status: "ok", source: "node_options" };
+	}
+	const backendRoot =
+		typeof backendRootPath === "string" && backendRootPath.trim()
+			? backendRootPath.trim().replace(/\/+$/, "")
+			: null;
+	const manifestPath = backendRoot
+		? `${backendRoot}/package.json`
+		: "package.json";
+	let packageJson;
+	try {
+		packageJson = await readJson({
+			repoRoot,
+			path: manifestPath,
+			signal,
+			optional: true,
+		});
+	} catch (error) {
+		throwIfSetupDoctorDeadlineExceeded(signal, error);
+		if (isSetupDoctorFileBoundaryError(error)) {
+			return { status: "invalid_path", path: manifestPath };
+		}
+		throw error;
+	}
+	if (packageJson === null) {
+		return { status: "package_json_missing", path: manifestPath };
+	}
+	const scripts =
+		packageJson.scripts && typeof packageJson.scripts === "object"
+			? packageJson.scripts
+			: {};
+	const startScripts = Object.entries(scripts).filter(
+		([name, command]) =>
+			isServerStartScriptName(name) && typeof command === "string",
+	);
+	if (startScripts.length === 0) {
+		return { status: "no_start_script", path: manifestPath };
+	}
+	const missing = startScripts
+		.filter(([, command]) => !CLUEBASE_PRELOAD_PATTERN.test(command))
+		.map(([name]) => name);
+	if (missing.length > 0) {
+		return { status: "missing", path: manifestPath, scripts: missing };
+	}
+	return {
+		status: "ok",
+		source: "scripts",
+		path: manifestPath,
+		scripts: startScripts.map(([name]) => name),
+	};
+};
+
+// What the customer loses is the point of the message: without the preload the
+// server runs and reports no error, and four of the five inputs that build one
+// user action stay empty.
+const PRELOAD_CONSEQUENCE =
+	"この指定が無いと、顧客の backend で「どの処理が動いたか」「どのデータを読み書きしたか」「どの分岐で判断したか」「どの外部サービスを呼んだか」が 1 件も記録されません。server は正常に起動しエラーも出ないため、記録が空であることに誰も気づけません。";
+
+const PRELOAD_REMEDY = `起動コマンドに \`--import ${CLUEBASE_REGISTER_SPECIFIER}\` を追加してください (例: \`node --import ${CLUEBASE_REGISTER_SPECIFIER} dist/main.js\`)。Docker / PM2 など package.json 以外から起動している場合は、そちらの起動コマンドか NODE_OPTIONS に同じ指定を入れてください。`;
+
+export const nodeBackendPreloadCheck = (probe) => {
+	const id = "backend_sdk_instrumentation_preload";
+	if (probe.status === "ok") {
+		return {
+			id,
+			severity: "error",
+			passed: true,
+			source: probe.source,
+			...(probe.scripts ? { scripts: probe.scripts } : {}),
+		};
+	}
+	if (probe.status === "missing") {
+		return {
+			id,
+			severity: "error",
+			passed: false,
+			scripts: probe.scripts,
+			error: `× backend の起動コマンドに Cluebase の計装の先読み込みがありません (${probe.path} の ${probe.scripts.join(" / ")})。${PRELOAD_CONSEQUENCE}${PRELOAD_REMEDY}`,
+		};
+	}
+	if (probe.status === "invalid_path") {
+		return {
+			id,
+			severity: "error",
+			passed: false,
+			error: `× backend の package.json (${probe.path}) が repository boundary を満たさないため、計装の先読み込みを検証できませんでした。`,
+		};
+	}
+	// package.json が見つからない / 起動 script が無い場合、起動方法は Docker CMD や
+	// 外部の supervisor 側にある。誤った赤にも誤った緑にもせず、未検証と伝える。
+	const reason =
+		probe.status === "package_json_missing"
+			? `backend の package.json (${probe.path}) が見つかりません`
+			: `${probe.path} に start / dev script がありません`;
+	return {
+		id,
+		severity: "warning",
+		passed: false,
+		error: `WARN: 計装の先読み込みを検証できませんでした (${reason})。${PRELOAD_CONSEQUENCE}実際の起動コマンドに \`--import ${CLUEBASE_REGISTER_SPECIFIER}\` が入っているか確認してください。`,
+	};
+};
+
+export const backendSdkImportCheck = (probe) => {
+	const id = "backend_sdk_import";
+	if (probe.status === "invalid_path") {
+		return {
+			id,
+			severity: "error",
+			passed: false,
+			error:
+				"× backend SDK import 検証失敗: backend root または Python interpreter path が repository boundary を満たさないか、読み取れません。symlink を使わない環境は `python -m venv --copies .venv` で作成してください。",
+		};
+	}
+	if (probe.status === "ok") {
+		return { id, severity: "error", passed: true, python: probe.python };
+	}
+	if (probe.status === "python_unavailable") {
+		// Cannot run Python here (e.g. no interpreter on PATH). Do not assert a
+		// false pass or a false fail — warn that the real import was not verified.
+		return {
+			id,
+			// doctor aggregates overall pass from severity==="error" checks only, and
+			// counts severity==="warning" in its warning summary. "cannot verify" is
+			// neither a pass nor a hard fail.
+			severity: "warning",
+			passed: false,
+			error:
+				'WARN: backend SDK の実 import を検証できませんでした (Python 実行環境が見つからない)。backend を起動する環境で `python -c "from cluebase_backend_sdk import cluebase"` が通るか確認してください。',
+		};
+	}
+	const remediation =
+		probe.status === "not_installed"
+			? `cluebase-backend-sdk が未インストールです。backend の依存をインストールしてください (例: pip install -r requirements.txt)。`
+			: probe.status === "facade_missing"
+				? `インストール済み cluebase-backend-sdk が古く \`cluebase\` ファサードがありません (要 >= ${MIN_BACKEND_SDK_VERSION})。\`pip install -U cluebase-backend-sdk\` で更新してください。`
+				: `backend SDK の import 検証に失敗しました。backend の Python 環境で \`from cluebase_backend_sdk import cluebase\` が通るか確認してください。`;
+	return {
+		id,
+		severity: "error",
+		passed: false,
+		error: `× backend SDK import 検証失敗: ${remediation}`,
+	};
+};