@genn-inc/cluebase-cli 0.0.1

package/README.md

@@ -0,0 +1,101 @@
+# Cluebase CLI
+
+This package owns the Cluebase setup CLI.
+
+The Cluebase product repository keeps SDKs, shared schemas, and API contracts. Tool implementation lives here so client repositories do not receive tool source code.
+
+## Commands
+
+The public npm package is `@genn-inc/cluebase-cli`. The binary exposed by that package is
+`cluebase-ai`, but first-run setup should not assume a global `cluebase-ai` install.
+Use `npx -y @genn-inc/cluebase-cli <command>` unless `.cluebase/setup-manifest.json`
+explicitly provides a different invocation.
+
+```bash
+npx -y @genn-inc/cluebase-cli setup --cluebase-api-key <ak_dev_or_prod_key> --cluebase-api-base-url <cluebase-api-base-url> --project-key <pk_dev_or_prod_key>
+npx -y @genn-inc/cluebase-cli setup-discover-check --manifest .cluebase/setup-manifest.json --discoveries .cluebase/discoveries.json
+npx -y @genn-inc/cluebase-cli setup-check --framework fastapi --backend-root-path backend --repo . --require-sdk-lifecycle
+npx -y @genn-inc/cluebase-cli setup-doctor --local
+```
+
+`npx -y @genn-inc/cluebase-cli setup` installs the target AI-tool skills and, when any
+frontend or backend service is detectable, also runs the machine-owned setup
+preparation:
+
+- detects frontend services (React/Vite, Next.js, Vue, Angular, SvelteKit, Nuxt)
+  and backend services (Python: FastAPI/Django/Flask and other WSGI/ASGI apps;
+  Node: Express/NestJS/Fastify/Koa) from dependency manifests and framework
+  import signals — language, framework, and service root only
+- writes `.cluebase/setup-manifest.json`
+- defers service-specific runtime env guidance to the Cluebase setup screen Step 2;
+  the CLI does not write `.env.cluebase`
+
+A frontend-only project (single-page app plus serverless/static hosting, with no
+detectable backend) is a supported setup path and continues as a frontend SDK
+integration rather than being blocked. Setup is blocked only when no frontend or
+backend service is detected at all.
+
+Route and lifecycle-boundary inventory is not enumerated by a per-framework
+parser. It is discovered semantically by the AI setup STEP commands
+(`cluebase-discover` and its review/context passes) reading the customer codebase,
+so unsupported frameworks and unknown routes degrade gracefully instead of
+blocking setup.
+
+## Universal HTTP ingest contract
+
+The Cluebase SDKs are a convenience over three stable HTTP endpoints. Any stack that
+has no matching Cluebase SDK can integrate by calling these endpoints directly, which
+is the universal fallback setup path:
+
+- `POST /api/v1/ingest/browser-tokens` — the browser obtains a short-lived token
+  from the Cluebase backend directly, authenticated by the public project key and the
+  request `Origin`. No customer-backend proxy route.
+- `POST /api/v1/ingest/browser` — the browser sends canonical observation source
+  event batches with the short-lived token in `x-cluebase-browser-token`.
+- `POST /api/v1/ingest/backend` — the customer backend sends server-side batches
+  with `CLUEBASE_API_KEY` in `x-cluebase-api-key`.
+
+The Cluebase environment (dev/prod) is derived from the project key prefix
+(`pk_dev_` vs `pk_prod_`); no environment variable is passed. Use this contract
+directly for any language or framework without a Cluebase SDK; do not add Cluebase proxy
+routes under the customer backend.
+
+`npx -y @genn-inc/cluebase-cli setup-check` mechanically verifies installed setup skills,
+obvious secret leaks, and SDK lifecycle presence when requested. With
+`--require-sdk-lifecycle`, a passing result is still static only; dependency
+installation, SDK imports in the target environments, app startup, and event
+delivery remain required before setup can be called complete.
+
+`npx -y @genn-inc/cluebase-cli setup-doctor --local` checks API connectivity before
+user-operated lifecycle verification. It verifies three setup hops:
+
+1. frontend SDK to Cluebase `/api/v1/ingest/browser-tokens` (short-lived token
+   issuance — the frontend SDK calls the Cluebase backend directly using the
+   public project key and request Origin, no customer-backend proxy in between).
+2. customer frontend to Cluebase canonical browser observation batch ingest with
+   the short-lived token.
+3. customer backend to Cluebase `/api/v1/ingest/backend` (server-side ingest
+   with `CLUEBASE_API_KEY`).
+
+It also scans the customer backend for `/api/v1/cluebase/*` proxy routes and
+emits a blocking error requiring removal (`customer_backend_cluebase_route_forbidden`).
+Setup-doctor does not replace real login, organization, or logout flows; confirm
+those flows from the Cluebase setup screen or published batch evidence after operating the
+local customer frontend/backend.
+
+`npx -y @genn-inc/cluebase-cli setup` reads the Cluebase API base URL, project key, and API
+key from setup screen flags, detects local services, writes
+`.cluebase/setup-manifest.json`, and points runtime env setup to the Cluebase setup
+screen Step 2.
+
+## Required Environment
+
+- `CLUEBASE_API_KEY`: Cluebase setup screen issues this value.
+- `CLUEBASE_PROJECT_KEY`: Cluebase setup screen issues this value.
+- `CLUEBASE_API_BASE_URL`: Cluebase API base URL shown by the setup screen.
+
+## Boundaries
+
+- The tool may read allowed source paths in the client repository.
+- The tool must not read `.env`, secrets, logs, dumps, build output, or vendor directories.
+- Raw source code, raw SQL, bind values, function names, class names, file paths, and import graphs must not be sent to Cluebase.

package/bin/cluebase-cli.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { runCli } from "../src/cli-command.mjs";
+
+process.stdin.unref?.();
+
+runCli(process.argv.slice(2)).catch((error) => {
+	process.stderr.write(
+		`${error instanceof Error ? error.message : String(error)}\n`,
+	);
+	process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@genn-inc/cluebase-cli",
+  "version": "0.0.1",
+  "type": "module",
+  "bin": {
+    "cluebase-ai": "bin/cluebase-cli.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md"
+  ],
+  "dependencies": {},
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/cli-command.mjs

@@ -0,0 +1,515 @@
+import { execFile } from "node:child_process";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+import {
+	CLUEBASE_CLI_BINARY_NAME,
+	CLUEBASE_CLI_PACKAGE_NAME,
+	CLUEBASE_CLI_RECOMMENDED_PREFIX,
+	cluebaseCliCommand,
+} from "./cli-invocation.mjs";
+import { analyzeCodeEvidenceReport } from "./code-evidence-analyzer.mjs";
+import {
+	deriveEnvironmentFromProjectApiKey,
+	deriveEnvironmentFromProjectKey,
+} from "./contracts.mjs";
+import { runSetupCheck } from "./setup-check.mjs";
+import { runSetupDiscoverCheck } from "./setup-discover-check.mjs";
+import { runSetupDoctor } from "./setup-doctor.mjs";
+import { buildAiSetupHelp } from "./setup-help.mjs";
+import { runSetupPrepare } from "./setup-prepare.mjs";
+import { discoverSetupContract } from "./setup-repository-discovery.mjs";
+import { installSetupSteps } from "./setup-tool.mjs";
+
+export const parseArgs = (argv) => {
+	const [command = "help", ...tokens] = argv;
+	const flags = new Map();
+	for (let index = 0; index < tokens.length; index += 1) {
+		const token = tokens[index];
+		if (!token.startsWith("--")) continue;
+		const key = token.slice(2);
+		const next = tokens[index + 1];
+		if (next && !next.startsWith("--")) {
+			flags.set(key, next);
+			index += 1;
+		} else {
+			flags.set(key, true);
+		}
+	}
+	return { command, flags };
+};
+
+const readJson = async (path) => JSON.parse(await readFile(path, "utf8"));
+
+const readPackageVersion = async () => {
+	const packageJson = JSON.parse(
+		await readFile(new URL("../package.json", import.meta.url), "utf8"),
+	);
+	return String(packageJson.version);
+};
+
+const readTextIfExists = async (path) => {
+	try {
+		return await readFile(path, "utf8");
+	} catch (error) {
+		if (error?.code === "ENOENT") return "";
+		throw error;
+	}
+};
+
+const DEFAULT_SETUP_MANIFEST_PATH = ".cluebase/setup-manifest.json";
+
+const isGitignoreEntryPresent = (content, entry) =>
+	content
+		.split(/\r?\n/)
+		.map((line) => line.trim())
+		.includes(entry);
+
+const appendGitignoreEntry = async ({ repoRoot, entry }) => {
+	const gitignorePath = resolve(repoRoot, ".gitignore");
+	const current = await readTextIfExists(gitignorePath);
+	if (isGitignoreEntryPresent(current, entry)) {
+		return "already_ignored";
+	}
+	const prefix = current.length > 0 && !current.endsWith("\n") ? "\n" : "";
+	await writeFile(gitignorePath, `${current}${prefix}${entry}\n`, "utf8");
+	return "added";
+};
+
+const CLUEBASE_ARTIFACT_GITIGNORE_ENTRIES = [
+	".cluebase/discoveries.json",
+	".cluebase/setup-check.json",
+	".cluebase/setup-diff.patch",
+	".cluebase/setup-review-findings.md",
+	".cluebase/secrets.json",
+];
+
+const protectCluebaseArtifacts = async ({ repoRoot }) => {
+	const gitignorePath = resolve(repoRoot, ".gitignore");
+	const current = await readTextIfExists(gitignorePath);
+	const results = [];
+	for (const entry of CLUEBASE_ARTIFACT_GITIGNORE_ENTRIES) {
+		if (isGitignoreEntryPresent(current, entry)) {
+			results.push({ entry, gitignore_status: "already_ignored" });
+			continue;
+		}
+		const status = await appendGitignoreEntry({ repoRoot, entry });
+		results.push({ entry, gitignore_status: status });
+	}
+	return results;
+};
+
+const SECRETS_FILE_PATH = ".cluebase/secrets.json";
+
+const writeSecretsFile = async ({ repoRoot, apiKey }) => {
+	if (typeof apiKey !== "string" || apiKey.trim().length === 0) {
+		return { status: "skipped", reason: "no_api_key_provided" };
+	}
+	const absolutePath = resolve(repoRoot, SECRETS_FILE_PATH);
+	const body = {
+		cluebase_api_key: apiKey.trim(),
+		_warning:
+			"DO NOT COMMIT. This file contains the Cluebase API key. The Cluebase setup CLI auto-adds `.cluebase/secrets.json` to .gitignore — keep it that way.",
+	};
+	await mkdir(dirname(absolutePath), { recursive: true });
+	await writeFile(absolutePath, `${JSON.stringify(body, null, 2)}\n`, {
+		encoding: "utf8",
+		mode: 0o600,
+	});
+	return { status: "written", path: SECRETS_FILE_PATH };
+};
+
+const usage = () =>
+	[
+		"Cluebase CLI:",
+		`  npm package: ${CLUEBASE_CLI_PACKAGE_NAME}`,
+		`  binary: ${CLUEBASE_CLI_BINARY_NAME}`,
+		`  first-run invocation: ${CLUEBASE_CLI_RECOMMENDED_PREFIX} <command>`,
+		`  global ${CLUEBASE_CLI_BINARY_NAME} installation is not required`,
+		`  AI setup help: ${cluebaseCliCommand("help --json")}`,
+		"",
+		"Usage:",
+		`  ${cluebaseCliCommand("setup --cluebase-api-key <ak_dev_or_prod_key> --cluebase-api-base-url <url> --project-key <pk_dev_or_prod_key> --documents-url <url>")}`,
+		`  ${cluebaseCliCommand("setup-check --framework fastapi --backend-root-path backend --repo .")}`,
+		`  ${cluebaseCliCommand("setup-discover --repo .")}`,
+		`  ${cluebaseCliCommand("setup-discover-check --manifest .cluebase/setup-manifest.json --discoveries .cluebase/discoveries.json")}`,
+		`  ${cluebaseCliCommand("setup-doctor --local")}`,
+		`  ${cluebaseCliCommand("code-evidence --source-revision-sha <40-char-commit-sha> --repo .")}`,
+	].join("\n");
+
+const renderEnvironmentInstructions = (instructions) => {
+	if (!instructions || instructions.status !== "deferred_to_setup_wizard") {
+		return "";
+	}
+	const services = Array.isArray(instructions.detected_services)
+		? instructions.detected_services
+		: [];
+	const serviceLines = services.map((service) => {
+		const kindLabel = service.kind === "frontend" ? "frontend" : "backend";
+		const frameworkLabel = service.framework ?? "unknown";
+		return `  - [${kindLabel}] ${service.root_path} (${frameworkLabel})`;
+	});
+	const lines = [
+		"",
+		"環境変数の設定は setup 画面の Step2 を見て行ってください。",
+		"(CLI 側では .env.cluebase ファイルは生成しません。setup 画面に必要な値が表示されます)",
+		"",
+		"検出したサービス:",
+		...(serviceLines.length > 0 ? serviceLines : ["  (なし)"]),
+		"",
+	];
+	return `${lines.join("\n")}\n`;
+};
+
+const renderSetupResult = ({ preparation }) => {
+	if (preparation?.status === "ready_for_ai") {
+		const manifestPath =
+			preparation.artifacts?.setup_manifest_path ??
+			".cluebase/setup-manifest.json";
+		return [
+			"Cluebase セットアップの準備が完了しました。",
+			"",
+			"作成したファイル:",
+			`- ${manifestPath}`,
+			"",
+			"次にやること:",
+			"1. Claude Code を使う場合: `claude` を起動し、`/cluebase-discover` -> `/cluebase-discover-review` -> `/cluebase-discover-context` -> `/cluebase-discover-check` -> `/cluebase-implement` -> `/cluebase-implement-check` -> `/cluebase-implement-review` -> `/cluebase-doctor` の順に実行してください。",
+			"2. Codex を使う場合: `codex` を起動し、`$cluebase-discover` -> `$cluebase-discover-review` -> `$cluebase-discover-context` -> `$cluebase-discover-check` -> `$cluebase-implement` -> `$cluebase-implement-check` -> `$cluebase-implement-review` -> `$cluebase-doctor` の順に実行してください。",
+			"",
+			"環境変数は Step 2 のコマンド (/cluebase-implement) が env ファイルへ自動で書き込みます。手動設定は通常不要です（自動書込が動かなかった場合のみ、setup 画面の env セクションに表示された値をコピーしてください）。",
+		].join("\n");
+	}
+
+	const blockers = Array.isArray(preparation?.blockers)
+		? preparation.blockers
+				.map((blocker) => blocker.message ?? blocker.reason ?? blocker.code)
+				.filter(Boolean)
+		: [];
+	return [
+		"Cluebase setup に失敗しました。",
+		"",
+		"原因:",
+		...(blockers.length > 0
+			? blockers.map((blocker) => `- ${blocker}`)
+			: ["- setup に必要な情報を検出できませんでした。"]),
+	].join("\n");
+};
+
+const defaultIo = {
+	stdout: process.stdout,
+	stderr: process.stderr,
+	setExitCode: (code) => {
+		process.exitCode = code;
+	},
+};
+
+export const runCli = async (argv, io = defaultIo) => {
+	const { command, flags } = parseArgs(argv);
+	if (
+		command === "version" ||
+		command === "--version" ||
+		flags.has("version")
+	) {
+		io.stdout.write(`${await readPackageVersion()}\n`);
+		return;
+	}
+
+	if (
+		(command === "help" || command === "--help" || flags.has("help")) &&
+		flags.has("json")
+	) {
+		io.stdout.write(`${JSON.stringify(buildAiSetupHelp(), null, 2)}\n`);
+		return;
+	}
+
+	if (command === "help" || command === "--help" || flags.has("help")) {
+		io.stdout.write(`${usage()}\n`);
+		return;
+	}
+
+	const repoRoot = resolve(String(flags.get("repo") || "."));
+
+	if (command === "setup-doctor") {
+		const report = await runSetupDoctor({ flags, repoRoot });
+		io.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+		if (!report.passed) {
+			io.setExitCode(1);
+		}
+		return;
+	}
+
+	if (command === "code-evidence" || command === "analyze-code-evidence") {
+		const sourceRevisionSha = flags.get("source-revision-sha");
+		if (typeof sourceRevisionSha !== "string") {
+			throw new Error("--source-revision-sha is required");
+		}
+		const csvPaths = (value) =>
+			typeof value === "string"
+				? value
+						.split(",")
+						.map((entry) => entry.trim())
+						.filter(Boolean)
+				: undefined;
+		const report = await analyzeCodeEvidenceReport({
+			repoRoot,
+			sourceRevisionSha,
+			allowedSourcePaths: csvPaths(flags.get("allowed-source-paths")),
+			excludedSourcePaths: csvPaths(flags.get("excluded-source-paths")),
+			setupDiscoveryPath:
+				typeof flags.get("setup-discovery") === "string"
+					? String(flags.get("setup-discovery"))
+					: undefined,
+			externalIdentityContextPath:
+				typeof flags.get("external-identity-context") === "string"
+					? String(flags.get("external-identity-context"))
+					: undefined,
+		});
+		io.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+		if (report.setup_plan.status !== "healthy") {
+			io.setExitCode(1);
+		}
+		return;
+	}
+
+	if (command === "setup-discover") {
+		const setupDiscovery = await discoverSetupContract({ repoRoot });
+		io.stdout.write(
+			`${JSON.stringify({ setup_discovery: setupDiscovery }, null, 2)}\n`,
+		);
+		return;
+	}
+
+	if (command === "setup") {
+		const setupProjectKey = flags.get("project-key");
+		const setupCluebaseApiKey = flags.get("cluebase-api-key");
+		if (typeof setupProjectKey === "string" && setupProjectKey.trim()) {
+			const projectKeyEnv = deriveEnvironmentFromProjectKey(setupProjectKey);
+			if (!projectKeyEnv) {
+				throw new Error("--project-key must start with pk_dev_ or pk_prod_");
+			}
+			if (
+				typeof setupCluebaseApiKey === "string" &&
+				setupCluebaseApiKey.trim()
+			) {
+				const apiKeyEnv =
+					deriveEnvironmentFromProjectApiKey(setupCluebaseApiKey);
+				if (!apiKeyEnv) {
+					throw new Error(
+						"--cluebase-api-key must start with ak_dev_ or ak_prod_",
+					);
+				}
+				if (projectKeyEnv !== apiKeyEnv) {
+					throw new Error(
+						`environment mismatch: --project-key prefix indicates ${projectKeyEnv} but --cluebase-api-key prefix indicates ${apiKeyEnv}. Use a key pair from the same environment.`,
+					);
+				}
+			}
+		}
+		const report = await installSetupSteps({
+			repoRoot,
+			documentsUrl: flags.get("documents-url"),
+		});
+		const preparation = flags.has("skills-only")
+			? {
+					status: "skipped",
+					reason: "skills-only flag was provided",
+				}
+			: await runSetupPrepare({
+					repoRoot,
+					setupContext: {
+						cluebaseApiKey: flags.get("cluebase-api-key"),
+						cluebaseApiBaseUrl: flags.get("cluebase-api-base-url"),
+						documentsUrl: flags.get("documents-url"),
+						projectKey: flags.get("project-key"),
+					},
+				});
+		const cluebaseArtifactProtection = await protectCluebaseArtifacts({
+			repoRoot,
+		});
+		preparation.cluebase_artifact_protection = cluebaseArtifactProtection;
+		const secretsProtection = await writeSecretsFile({
+			repoRoot,
+			apiKey: flags.get("cluebase-api-key"),
+		});
+		preparation.secrets_protection = secretsProtection;
+		const environmentInstructions = renderEnvironmentInstructions(
+			preparation.environment_instructions,
+		);
+		if (environmentInstructions && flags.has("json")) {
+			io.stderr.write(environmentInstructions);
+		}
+		if (flags.has("json")) {
+			io.stdout.write(
+				`${JSON.stringify({ ...report, preparation }, null, 2)}\n`,
+			);
+		} else {
+			io.stdout.write(`${renderSetupResult({ preparation })}\n`);
+		}
+		if (!flags.has("json") && preparation.status === "blocked") {
+			io.setExitCode(1);
+		}
+		return;
+	}
+
+	if (command === "setup-discover-check") {
+		const manifestPath = String(
+			flags.get("manifest") || DEFAULT_SETUP_MANIFEST_PATH,
+		);
+		const discoveriesPath = flags.get("discoveries");
+		if (typeof discoveriesPath !== "string") {
+			throw new Error("--discoveries is required");
+		}
+		const report = await runSetupDiscoverCheck({
+			manifestPath,
+			discoveriesPath,
+			repoRoot,
+		});
+		if (report.passed) {
+			io.stderr.write(
+				"OK — 発見結果に問題は見つかりませんでした。次の STEP に進めます。\n",
+			);
+		} else {
+			const issueCount = Array.isArray(report.errors)
+				? report.errors.length
+				: 0;
+			io.stderr.write(
+				`FAIL — ${issueCount} 件の指摘があります。下の JSON 出力の errors の内容を Claude Code に伝えて修正してから、もう一度この STEP を実行してください。\n`,
+			);
+		}
+		io.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+		if (!report.passed) {
+			io.setExitCode(report.exit_code ?? 1);
+		}
+		return;
+	}
+
+	if (command === "setup-check") {
+		const explicitFramework =
+			typeof flags.get("framework") === "string"
+				? flags.get("framework")
+				: null;
+		const explicitBackendRootPath =
+			typeof flags.get("backend-root-path") === "string"
+				? flags.get("backend-root-path")
+				: null;
+		let resolvedFramework = explicitFramework;
+		let resolvedBackendRootPath = explicitBackendRootPath;
+		const autoDetectedFields = [];
+		if (!resolvedFramework) {
+			let discoveries;
+			const sourcePath = ".cluebase/discoveries.json";
+			try {
+				discoveries = await readJson(resolve(repoRoot, sourcePath));
+			} catch {
+				discoveries = null;
+			}
+			const candidate =
+				typeof discoveries?.framework_backend === "string"
+					? discoveries.framework_backend.trim()
+					: "";
+			if (candidate) {
+				resolvedFramework = candidate;
+				autoDetectedFields.push(`--framework ${candidate} (${sourcePath})`);
+			}
+		}
+		if (!resolvedBackendRootPath) {
+			try {
+				const manifest = await readJson(
+					resolve(repoRoot, DEFAULT_SETUP_MANIFEST_PATH),
+				);
+				const candidate =
+					typeof manifest?.detected?.backend_root_path === "string"
+						? manifest.detected.backend_root_path.trim()
+						: "";
+				if (candidate) {
+					resolvedBackendRootPath = candidate;
+					autoDetectedFields.push(
+						`--backend-root-path ${candidate} (${DEFAULT_SETUP_MANIFEST_PATH})`,
+					);
+				}
+			} catch {
+				// A missing manifest leaves the explicit command contract unchanged.
+			}
+		}
+		if (autoDetectedFields.length > 0) {
+			io.stderr.write(
+				`setup-check: auto-detected ${autoDetectedFields.join(" + ")}\n`,
+			);
+		}
+		const hasInventoryFlags =
+			typeof resolvedFramework === "string" &&
+			typeof resolvedBackendRootPath === "string";
+		const request = hasInventoryFlags
+			? {
+					framework: resolvedFramework,
+					backend_root_path: resolvedBackendRootPath,
+					allowed_source_paths:
+						typeof flags.get("allowed-source-paths") === "string"
+							? String(flags.get("allowed-source-paths"))
+									.split(",")
+									.map((entry) => entry.trim())
+									.filter(Boolean)
+							: [resolvedBackendRootPath],
+					excluded_source_paths:
+						typeof flags.get("excluded-source-paths") === "string"
+							? String(flags.get("excluded-source-paths"))
+									.split(",")
+									.map((entry) => entry.trim())
+									.filter(Boolean)
+							: [],
+				}
+			: undefined;
+		const report = await runSetupCheck({
+			repoRoot,
+			request,
+			requireSdkLifecycle: flags.has("require-sdk-lifecycle"),
+		});
+		if (flags.has("write-snapshot")) {
+			const cluebaseDir = resolve(repoRoot, ".cluebase");
+			await mkdir(cluebaseDir, { recursive: true });
+			const reportPath = resolve(cluebaseDir, "setup-check.json");
+			await writeFile(
+				reportPath,
+				`${JSON.stringify(report, null, 2)}\n`,
+				"utf8",
+			);
+			let gitDiffOutput = "";
+			let gitDiffError = null;
+			try {
+				const { stdout } = await execFileAsync("git", ["diff", "HEAD"], {
+					cwd: repoRoot,
+					maxBuffer: 50 * 1024 * 1024,
+				});
+				gitDiffOutput = stdout;
+			} catch (err) {
+				gitDiffError = err instanceof Error ? err.message : String(err);
+			}
+			const diffPath = resolve(repoRoot, ".cluebase/setup-diff.patch");
+			await writeFile(diffPath, gitDiffOutput, "utf8");
+			const reportPassedLabel = report.passed ? "passed" : "FAILED";
+			io.stderr.write(
+				`setup-check: wrote .cluebase/setup-check.json (${reportPassedLabel}) and .cluebase/setup-diff.patch (${gitDiffOutput.length} bytes)\n`,
+			);
+			if (gitDiffError) {
+				io.stderr.write(
+					`setup-check: warning — git diff HEAD failed: ${gitDiffError}\n`,
+				);
+			} else if (gitDiffOutput.trim().length === 0) {
+				io.stderr.write(
+					"setup-check: warning — .cluebase/setup-diff.patch is empty. If implementation changes were already committed, you may need: git diff HEAD~1 > .cluebase/setup-diff.patch\n",
+				);
+			}
+			return;
+		}
+		io.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+		if (!report.passed) {
+			io.setExitCode(1);
+		}
+		return;
+	}
+
+	throw new Error(`Unknown command: ${command}\n${usage()}`);
+};

package/src/cli-invocation.mjs

@@ -0,0 +1,17 @@
+export const CLUEBASE_CLI_PACKAGE_NAME = "@genn-inc/cluebase-cli";
+export const CLUEBASE_CLI_BINARY_NAME = "cluebase-ai";
+export const CLUEBASE_CLI_RECOMMENDED_PREFIX = `npx -y ${CLUEBASE_CLI_PACKAGE_NAME}`;
+
+export const CLUEBASE_CLI_INVOCATION_CONTRACT = {
+  package_name: CLUEBASE_CLI_PACKAGE_NAME,
+  binary_name: CLUEBASE_CLI_BINARY_NAME,
+  recommended_prefix: CLUEBASE_CLI_RECOMMENDED_PREFIX,
+  global_binary_required: false,
+  version_check_command: `${CLUEBASE_CLI_RECOMMENDED_PREFIX} --version`,
+  help_command: `${CLUEBASE_CLI_RECOMMENDED_PREFIX} --help`,
+  ai_help_command: `${CLUEBASE_CLI_RECOMMENDED_PREFIX} help --json`,
+  rule: "Use the recommended_prefix for Cluebase CLI commands. Do not discover or require a global cluebase-ai binary; missing global cluebase-ai is normal. For AI setup scope and responsibility rules, run ai_help_command.",
+};
+
+export const cluebaseCliCommand = (args) =>
+  `${CLUEBASE_CLI_RECOMMENDED_PREFIX} ${args}`;