@clue-ai/cli 0.0.3 → 0.0.5

package/bin/clue-cli.mjs

@@ -0,0 +1,859 @@
+#!/usr/bin/env node
+import { createServer } from "node:http";
+import { createInterface } from "node:readline/promises";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { commandSpecs } from "../src/command-spec.mjs";
+import {
+	buildSemanticWorkflowRequestFromFlags,
+	runInitTool,
+	writeSemanticWorkflow,
+} from "../src/init-tool.mjs";
+import { applyLifecyclePlan } from "../src/lifecycle-init.mjs";
+import { runSemanticCi, runSemanticInventory } from "../src/semantic-ci.mjs";
+import { runSetupCheck } from "../src/setup-check.mjs";
+import { runSetupDetect } from "../src/setup-detect.mjs";
+import { runSetupPrepare } from "../src/setup-prepare.mjs";
+import { installSetupSkills } from "../src/setup-tool.mjs";
+
+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 writeJsonIfRequested = async ({ repoRoot, outputPath, value }) => {
+	if (typeof outputPath !== "string") return false;
+	const resolvedRepoRoot = resolve(repoRoot);
+	const resolvedOutputPath = resolve(resolvedRepoRoot, outputPath);
+	const relativeOutputPath = relative(resolvedRepoRoot, resolvedOutputPath);
+	if (relativeOutputPath.startsWith("..") || isAbsolute(relativeOutputPath)) {
+		throw new Error(`output path escapes repo root: ${outputPath}`);
+	}
+	await mkdir(dirname(resolvedOutputPath), { recursive: true });
+	await writeFile(
+		resolvedOutputPath,
+		`${JSON.stringify(value, null, 2)}\n`,
+		"utf8",
+	);
+	return true;
+};
+
+const sleep = (ms) =>
+	new Promise((resolveSleep) => setTimeout(resolveSleep, ms));
+
+const splitCsv = (value) =>
+	typeof value === "string"
+		? value
+				.split(",")
+				.map((entry) => entry.trim())
+				.filter(Boolean)
+		: [];
+
+const splitWatchTargetEntries = (value) => {
+	if (typeof value !== "string") return [];
+	const entries = [];
+	let current = "";
+	let bracketDepth = 0;
+	for (const char of value) {
+		if (char === "[") bracketDepth += 1;
+		if (char === "]") bracketDepth = Math.max(0, bracketDepth - 1);
+		if (char === "," && bracketDepth === 0) {
+			if (current.trim()) entries.push(current.trim());
+			current = "";
+			continue;
+		}
+		current += char;
+	}
+	if (current.trim()) entries.push(current.trim());
+	return entries;
+};
+
+const WATCH_LIFECYCLE_ALIASES = new Map([
+	["clue-init", "init"],
+	["init", "init"],
+	["sdk-initialized", "init"],
+	["clue-identify", "identify"],
+	["identify", "identify"],
+	["identified", "identify"],
+	["clue-set-account", "set-account"],
+	["set-account", "set-account"],
+	["account", "set-account"],
+	["clue-logout", "logout"],
+	["logout", "logout"],
+	["event-sent", "event-sent"],
+	["event", "event-sent"],
+	["log", "event-sent"],
+]);
+
+const DEFAULT_WATCH_LIFECYCLE = [
+	"init",
+	"identify",
+	"set-account",
+	"logout",
+	"event-sent",
+];
+const DEFAULT_SETUP_MANIFEST_PATH = ".clue/setup-manifest.json";
+
+const parseExpectedLifecycle = (value) => {
+	if (typeof value !== "string" || !value.trim()) {
+		return DEFAULT_WATCH_LIFECYCLE;
+	}
+	const entries = value
+		.split(/[,+]/)
+		.map((entry) => entry.trim().toLowerCase())
+		.filter(Boolean);
+	const normalized = entries.map((entry) => {
+		const lifecycle = WATCH_LIFECYCLE_ALIASES.get(entry);
+		if (!lifecycle) {
+			throw new Error(
+				`invalid lifecycle check: ${entry}; expected init, identify, set-account, logout, or event-sent`,
+			);
+		}
+		return lifecycle;
+	});
+	return [...new Set(normalized)];
+};
+
+const parseWatchTargets = (value) =>
+	splitWatchTargetEntries(value).map((entry) => {
+		const match =
+			/^(frontend|backend):([^[\]=\s]+)(?:\[([^\]]+)\])?(?:=(\S+))?$/.exec(
+				entry,
+			);
+		if (!match) {
+			throw new Error(
+				`invalid --watch-targets entry: ${entry}; expected frontend:<service-key>[init,identify,set-account,logout,event-sent][=<url>] or backend:<service-key>[...][=<url>]`,
+			);
+		}
+		const serviceKey = match[2];
+		return {
+			kind: match[1],
+			serviceKey,
+			producerId: serviceKey,
+			expectedLifecycle: parseExpectedLifecycle(match[3]),
+			url: match[4] ?? null,
+		};
+	});
+
+const normalizeManifestWatchTarget = (target) => {
+	if (!target || typeof target !== "object") {
+		throw new Error("invalid setup manifest watch target");
+	}
+	const kind = target.kind;
+	const serviceKey = target.service_key ?? target.serviceKey;
+	if (kind !== "frontend" && kind !== "backend") {
+		throw new Error("setup manifest watch target kind must be frontend or backend");
+	}
+	if (typeof serviceKey !== "string" || !serviceKey.trim()) {
+		throw new Error("setup manifest watch target service_key is required");
+	}
+	const localUrlCandidates = Array.isArray(target.local_url_candidates)
+		? target.local_url_candidates
+				.map((entry) => String(entry).trim())
+				.filter(Boolean)
+		: [];
+	const urlEnvName =
+		typeof target.url_env_name === "string" && target.url_env_name.trim()
+			? target.url_env_name.trim()
+			: null;
+	const explicitUrl =
+		typeof target.url === "string" && target.url.trim()
+			? target.url.trim()
+			: null;
+	const expectedLifecycle = Array.isArray(target.expected_lifecycle)
+		? parseExpectedLifecycle(target.expected_lifecycle.join(","))
+		: DEFAULT_WATCH_LIFECYCLE;
+	return {
+		kind,
+		serviceKey: serviceKey.trim(),
+		producerId:
+			typeof target.producer_id === "string" && target.producer_id.trim()
+				? target.producer_id.trim()
+				: serviceKey.trim(),
+		expectedLifecycle,
+		url: explicitUrl,
+		urlEnvName,
+		localUrlCandidates,
+	};
+};
+
+const readSetupManifest = async ({ repoRoot, manifestPath }) => {
+	const resolvedPath = resolve(repoRoot, manifestPath);
+	return readJson(resolvedPath);
+};
+
+const manifestWatchTargets = (manifest) => {
+	const targets = manifest?.lifecycle_verification?.watch_targets;
+	if (!Array.isArray(targets) || targets.length === 0) {
+		return [];
+	}
+	return targets.map(normalizeManifestWatchTarget);
+};
+
+const resolveTargetUrlFromEnv = ({ target, env }) => {
+	if (target.url) return target.url;
+	if (target.urlEnvName && typeof env[target.urlEnvName] === "string") {
+		const value = env[target.urlEnvName].trim();
+		if (value) return value;
+	}
+	return target.localUrlCandidates[0] ?? null;
+};
+
+const shouldAskQuestions = ({ flags }) =>
+	!flags.has("yes") && process.stdin.isTTY && process.stdout.isTTY;
+
+const confirmTargetUrls = async ({ flags, watchTargets, env }) => {
+	const initialTargets = watchTargets.map((target) => ({
+		...target,
+		url: resolveTargetUrlFromEnv({ target, env }),
+	}));
+	if (!shouldAskQuestions({ flags })) {
+		return initialTargets;
+	}
+	const readline = createInterface({
+		input: process.stdin,
+		output: process.stdout,
+	});
+	try {
+		const confirmedTargets = [];
+		for (const target of initialTargets) {
+			const currentUrl = target.url ?? "";
+			const answer = await readline.question(
+				`${target.kind}のローカルURL(${target.serviceKey})はこちらで正しいですか？ ${currentUrl || "(未設定)"}\nEnterで決定、違う場合はURLを入力: `,
+			);
+			confirmedTargets.push({
+				...target,
+				url: answer.trim() || currentUrl || null,
+			});
+		}
+		return confirmedTargets;
+	} finally {
+		readline.close();
+	}
+};
+
+const uniqueCsv = (values) => [...new Set(values.filter(Boolean))].join(",");
+
+const buildWatchProducerIds = ({ explicitProducerIds, watchTargets }) =>
+	uniqueCsv([
+		...splitCsv(explicitProducerIds),
+		...watchTargets.map((target) => target.producerId),
+	]);
+
+const checkTargetUrl = async (url) => {
+	if (!url) return { checked: false, reachable: true, status: null };
+	try {
+		const response = await fetch(url, { method: "GET" });
+		return {
+			checked: true,
+			reachable: response.status < 500,
+			status: response.status,
+		};
+	} catch {
+		return { checked: true, reachable: false, status: null };
+	}
+};
+
+const evaluateWatchTargets = async ({ latest, watchTargets }) => {
+	const producers = Array.isArray(latest?.producers) ? latest.producers : [];
+	return Promise.all(
+		watchTargets.map(async (target) => {
+			const producer = producers.find(
+				(entry) => entry.id === target.producerId,
+			);
+			const urlHealth = await checkTargetUrl(target.url);
+			const lifecycleStatus = {
+				init: Boolean(producer?.clueInit ?? producer?.sdkInitialized),
+				identify: Boolean(producer?.clueIdentify),
+				"set-account": Boolean(producer?.clueSetAccount),
+				logout: Boolean(producer?.clueLogout),
+				"event-sent": Boolean(producer?.logStored),
+			};
+			const expectedLifecycle = target.expectedLifecycle;
+			const unexpectedLifecycle = Object.entries(lifecycleStatus)
+				.filter(
+					([name, passed]) =>
+						passed &&
+						name !== "event-sent" &&
+						name !== "init" &&
+						!expectedLifecycle.includes(name),
+				)
+				.map(([name]) => name);
+			const producerPassed =
+				expectedLifecycle.every((name) => lifecycleStatus[name]) &&
+				unexpectedLifecycle.length === 0;
+			return {
+				...target,
+				expectedLifecycle,
+				eventCount: producer?.eventCount ?? 0,
+				latestOccurredAt: producer?.latestOccurredAt ?? null,
+				logStored: Boolean(producer?.logStored),
+				requestStored: Boolean(producer?.requestStored),
+				sdkInitialized: Boolean(producer?.sdkInitialized),
+				lifecycleStatus,
+				unexpectedLifecycle,
+				urlChecked: urlHealth.checked,
+				urlReachable: urlHealth.reachable,
+				urlStatus: urlHealth.status,
+				passed: producerPassed && urlHealth.reachable,
+			};
+		}),
+	);
+};
+
+const lifecycleStatusFromEvents = (events) => {
+	const customEventNames = new Set(
+		events
+			.map((event) => event.custom_event_name ?? event.customEventName)
+			.filter((value) => typeof value === "string"),
+	);
+	return {
+		init: customEventNames.has("sdk_initialized"),
+		identify: customEventNames.has("identity_identified"),
+		"set-account": customEventNames.has("account_associated"),
+		logout: customEventNames.has("identity_logged_out"),
+		"event-sent": events.length > 0,
+	};
+};
+
+const localSetupCheckSnapshot = ({ receivedBatches }) => {
+	const producerEvents = new Map();
+	for (const batch of receivedBatches) {
+		const producerId =
+			batch.producerId ||
+			batch.payload?.producer_metadata?.producer_id ||
+			batch.payload?.producer_id;
+		if (typeof producerId !== "string" || !producerId.trim()) continue;
+		const events = Array.isArray(batch.payload?.events)
+			? batch.payload.events
+			: [];
+		const existing = producerEvents.get(producerId) ?? [];
+		producerEvents.set(producerId, [...existing, ...events]);
+	}
+	const producers = [...producerEvents.entries()].map(([id, events]) => {
+		const lifecycleStatus = lifecycleStatusFromEvents(events);
+		return {
+			id,
+			eventCount: events.length,
+			clueInit: lifecycleStatus.init,
+			clueIdentify: lifecycleStatus.identify,
+			clueSetAccount: lifecycleStatus["set-account"],
+			clueLogout: lifecycleStatus.logout,
+			sdkInitialized: lifecycleStatus.init,
+			logStored: lifecycleStatus["event-sent"],
+			requestStored: events.some((event) => event.event_category === "request"),
+			internalFlowStored: events.some(
+				(event) => event.event_category === "internal_flow",
+			),
+			latestOccurredAt:
+				events
+					.map((event) => event.occurred_at)
+					.filter((value) => typeof value === "string")
+					.sort()
+					.at(-1) ?? null,
+		};
+	});
+	const lifecycleChecks = producers.flatMap((producer) => [
+		["frontend_sdk_initialized", producer.sdkInitialized],
+		["backend_sdk_initialized", producer.sdkInitialized],
+		["frontend_log_sent", producer.logStored],
+		["backend_log_sent", producer.logStored],
+		["identified_event", producer.clueIdentify],
+		["account_event", producer.clueSetAccount],
+		["logout_reset", producer.clueLogout],
+	]);
+	const checks = Object.fromEntries(
+		lifecycleChecks.map(([name, passed]) => [
+			name,
+			passed ? "passed" : "waiting",
+		]),
+	);
+	return { checks, producers };
+};
+
+const readRequestJson = async (request) => {
+	const chunks = [];
+	for await (const chunk of request) {
+		chunks.push(chunk);
+	}
+	const body = Buffer.concat(chunks).toString("utf8");
+	if (!body.trim()) return {};
+	return JSON.parse(body);
+};
+
+const startLocalSetupReceiver = async ({ host, port }) => {
+	const receivedBatches = [];
+	const server = createServer(async (request, response) => {
+		response.setHeader("access-control-allow-origin", "*");
+		response.setHeader("access-control-allow-methods", "POST, OPTIONS");
+		response.setHeader("access-control-allow-headers", "*");
+		if (request.method === "OPTIONS") {
+			response.writeHead(204);
+			response.end();
+			return;
+		}
+		if (request.method !== "POST") {
+			response.writeHead(404, { "content-type": "application/json" });
+			response.end(JSON.stringify({ accepted: false }));
+			return;
+		}
+		try {
+			const payload = await readRequestJson(request);
+			receivedBatches.push({
+				payload,
+				producerId:
+					payload?.producer_metadata?.producer_id ?? payload?.producer_id ?? null,
+				path: request.url,
+			});
+			response.writeHead(202, { "content-type": "application/json" });
+			response.end(
+				JSON.stringify({
+					accepted: true,
+					status: "accepted",
+					duplicate: false,
+					eventCount: Array.isArray(payload?.events) ? payload.events.length : 0,
+				}),
+			);
+		} catch (error) {
+			response.writeHead(400, { "content-type": "application/json" });
+			response.end(
+				JSON.stringify({
+					accepted: false,
+					reason: error instanceof Error ? error.message : String(error),
+				}),
+			);
+		}
+	});
+	await new Promise((resolveListen, rejectListen) => {
+		server.once("error", rejectListen);
+		server.listen(port, host, () => {
+			server.off("error", rejectListen);
+			resolveListen();
+		});
+	});
+	const address = server.address();
+	if (!address || typeof address === "string") {
+		throw new Error("local setup receiver failed to bind");
+	}
+	const baseUrl = `http://${host}:${address.port}`;
+	return {
+		baseUrl,
+		receivedBatches,
+		close: () =>
+			new Promise((resolveClose) => {
+				server.close(() => resolveClose());
+			}),
+	};
+};
+
+const renderWatchTargets = (targetChecks) =>
+	targetChecks
+		.map((target) => {
+			const urlStatus = target.urlChecked
+				? ` url:${target.urlReachable ? target.urlStatus : "unreachable"}`
+				: "";
+			const lifecycle = target.expectedLifecycle
+				.map(
+					(name) =>
+						`${name}:${target.lifecycleStatus[name] ? "ok" : "waiting"}`,
+				)
+				.join(" ");
+			const unexpected = target.unexpectedLifecycle.length
+				? ` unexpected:${target.unexpectedLifecycle.join(",")}`
+				: "";
+			return `${target.passed ? "[x]" : "[ ]"} ${target.kind}:${target.serviceKey} ${lifecycle} events:${target.eventCount}${urlStatus}${unexpected}`;
+		})
+		.join("\n");
+
+const setupCheckUrl = ({
+	clueApiBaseUrl,
+	environment,
+	limit,
+	producerIds,
+	projectId,
+	projectKey,
+	startedAt,
+}) => {
+	const normalizedBaseUrl = String(clueApiBaseUrl).replace(/\/+$/, "");
+	const url = new URL(`${normalizedBaseUrl}/api/v1/events/setup-check`);
+	url.searchParams.set("projectKey", projectKey);
+	url.searchParams.set("environment", environment);
+	url.searchParams.set("startedAt", startedAt);
+	url.searchParams.set("limit", String(limit));
+	if (typeof projectId === "string" && projectId.trim()) {
+		url.searchParams.set("project_id", projectId.trim());
+	}
+	if (typeof producerIds === "string" && producerIds.trim()) {
+		url.searchParams.set("producerIds", producerIds.trim());
+	}
+	return url;
+};
+
+const runSetupWatch = async ({ flags, repoRoot = ".", env = process.env }) => {
+	const localMode = flags.has("local");
+	const manifestPath = String(
+		flags.get("manifest") || DEFAULT_SETUP_MANIFEST_PATH,
+	);
+	const manifest = localMode
+		? await readSetupManifest({ repoRoot, manifestPath })
+		: null;
+	if (localMode && manifest?.status !== "ready_for_ai") {
+		throw new Error(
+			`setup-watch --local requires a ready setup manifest at ${manifestPath}`,
+		);
+	}
+	const projectKey = String(
+		flags.get("project-key") ||
+			env.CLUE_PROJECT_KEY ||
+			manifest?.project_key ||
+			"",
+	).trim();
+	if (!projectKey && !localMode) {
+		throw new Error("--project-key or CLUE_PROJECT_KEY is required");
+	}
+	const environment = String(
+		flags.get("environment") ||
+			env.CLUE_ENVIRONMENT ||
+			manifest?.environment ||
+			"dev",
+	).trim();
+	const clueApiBaseUrl = String(
+		flags.get("clue-api-base-url") || env.CLUE_API_BASE_URL || "",
+	).trim();
+	if (!clueApiBaseUrl && !localMode) {
+		throw new Error("--clue-api-base-url or CLUE_API_BASE_URL is required");
+	}
+	const startedAt = String(
+		flags.get("started-at") || new Date().toISOString(),
+	).trim();
+	const timeoutMs = Number(flags.get("timeout-ms") || 120_000);
+	const pollIntervalMs = Number(flags.get("poll-interval-ms") || 3000);
+	const limit = Number(flags.get("limit") || 200);
+	const projectId = flags.get("project-id");
+	const explicitWatchTargets = parseWatchTargets(flags.get("watch-targets"));
+	const watchTargets = await confirmTargetUrls({
+		flags,
+		watchTargets:
+			explicitWatchTargets.length > 0
+				? explicitWatchTargets
+				: manifestWatchTargets(manifest),
+		env,
+	});
+	const producerIds = buildWatchProducerIds({
+		explicitProducerIds: flags.get("producer-ids"),
+		watchTargets,
+	});
+	const started = Date.now();
+	let latest = null;
+
+	if (localMode) {
+		const receiver = await startLocalSetupReceiver({
+			host: String(flags.get("host") || "127.0.0.1"),
+			port: Number(flags.get("port") || 0),
+		});
+		try {
+			process.stdout.write(
+				`Local Clue setup receiver: ${receiver.baseUrl}\n`,
+			);
+			process.stdout.write(
+				`Frontend endpoint: ${receiver.baseUrl}/api/v1/ingest/browser\n`,
+			);
+			process.stdout.write(
+				`Backend endpoint: ${receiver.baseUrl}/api/v1/ingest/backend\n`,
+			);
+			if (watchTargets.length > 0) {
+				process.stdout.write(
+					`Watching targets: ${watchTargets.map((target) => `${target.kind}:${target.serviceKey}`).join(", ")}\n`,
+				);
+			}
+			while (Date.now() - started <= timeoutMs) {
+				latest = localSetupCheckSnapshot({
+					receivedBatches: receiver.receivedBatches,
+				});
+				const targetChecks = await evaluateWatchTargets({
+					latest,
+					watchTargets,
+				});
+				const targetChecksPassed =
+					targetChecks.length > 0 &&
+					targetChecks.every((target) => target.passed);
+				const renderedTargets = renderWatchTargets(targetChecks);
+				process.stdout.write(`${renderedTargets}\n\n`);
+				if (targetChecksPassed) {
+					process.stdout.write("Clue local setup checks passed.\n");
+					return { ...latest, local: true, watchTargets: targetChecks };
+				}
+				await sleep(pollIntervalMs);
+			}
+			process.stdout.write(`${JSON.stringify(latest, null, 2)}\n`);
+			throw new Error(
+				"setup-watch --local timed out before all Clue setup checks passed",
+			);
+		} finally {
+			await receiver.close();
+		}
+	}
+
+	process.stdout.write(
+		`Waiting for Clue setup checks since ${startedAt} (${environment})...\n`,
+	);
+	if (watchTargets.length > 0) {
+		process.stdout.write(
+			`Watching targets: ${watchTargets.map((target) => `${target.kind}:${target.serviceKey}`).join(", ")}\n`,
+		);
+	}
+
+	while (Date.now() - started <= timeoutMs) {
+		const response = await fetch(
+			setupCheckUrl({
+				clueApiBaseUrl,
+				environment,
+				limit,
+				producerIds,
+				projectId,
+				projectKey,
+				startedAt,
+			}),
+		);
+		if (!response.ok) {
+			throw new Error(`setup-check request failed: ${response.status}`);
+		}
+		latest = await response.json();
+		const checks = latest?.checks ?? {};
+		const entries = Object.entries(checks);
+		const setupChecksPassed =
+			entries.length > 0 && entries.every(([, status]) => status === "passed");
+		const targetChecks = await evaluateWatchTargets({ latest, watchTargets });
+		const targetChecksPassed = targetChecks.every((target) => target.passed);
+		const passed = setupChecksPassed && targetChecksPassed;
+		const rendered = entries
+			.map(([id, status]) => `${status === "passed" ? "[x]" : "[ ]"} ${id}`)
+			.join("\n");
+		const renderedTargets = renderWatchTargets(targetChecks);
+		process.stdout.write(
+			`${rendered}${renderedTargets ? `\n${renderedTargets}` : ""}\n\n`,
+		);
+		if (passed) {
+			process.stdout.write("Clue setup checks passed.\n");
+			return { ...latest, watchTargets: targetChecks };
+		}
+		await sleep(pollIntervalMs);
+	}
+
+	process.stdout.write(`${JSON.stringify(latest, null, 2)}\n`);
+	throw new Error("setup-watch timed out before all Clue setup checks passed");
+};
+
+const usage = () =>
+	[
+		"Usage:",
+		"  /clue-init",
+		"  clue-ai setup",
+		"  clue-ai setup-detect --repo .",
+		"  clue-ai semantic-inventory --framework fastapi --backend-root-path backend --repo . --output .clue/semantic-routes.json",
+		"  clue-ai semantic-workflow --framework fastapi --backend-root-path backend --repo .",
+		"  clue-ai lifecycle-apply --plan clue-lifecycle-plan.json --repo .",
+		"  clue-ai setup-check --framework fastapi --backend-root-path backend --repo .",
+		"  clue-ai setup-watch --local",
+		"  clue-ai setup-watch --project-key <key> --environment dev --clue-api-base-url <clue-api-base-url> --watch-targets frontend:web[init,identify,set-account,logout,event-sent]=<frontend-url>,backend:api[init,identify,set-account,logout,event-sent]=<backend-url>",
+		"  clue-ai init --request clue-init-request.json --repo .",
+		"  clue-ai semantic-ci --request clue-semantic-request.json --repo . [--previous-snapshot-file previous.json]",
+		"  clue-ai semantic-ci --request-env CLUE_SEMANTIC_REQUEST_JSON --repo .",
+	].join("\n");
+
+const main = async () => {
+	const { command, flags } = parseArgs(process.argv.slice(2));
+	if (command === "help" || flags.has("help")) {
+		process.stdout.write(`${usage()}\n`);
+		return;
+	}
+
+	if (command === "commands") {
+		process.stdout.write(
+			`${JSON.stringify({ commands: commandSpecs }, null, 2)}\n`,
+		);
+		return;
+	}
+
+	const requestPath = flags.get("request");
+	const repoRoot = resolve(String(flags.get("repo") || "."));
+
+	if (command === "setup-watch") {
+		const report = await runSetupWatch({ flags, repoRoot });
+		process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+		return;
+	}
+
+	if (command === "setup") {
+		const report = await installSetupSkills({
+			repoRoot,
+			target:
+				typeof flags.get("target") === "string"
+					? flags.get("target")
+					: undefined,
+		});
+		const preparation = flags.has("skills-only")
+			? {
+					status: "skipped",
+					reason: "skills-only flag was provided",
+				}
+			: await runSetupPrepare({
+					repoRoot,
+					target: report.target,
+					skillRoot: report.skill_root,
+				});
+		process.stdout.write(
+			`${JSON.stringify({ ...report, preparation }, null, 2)}\n`,
+		);
+		return;
+	}
+
+	if (command === "setup-detect") {
+		const report = await runSetupDetect({
+			repoRoot,
+			excludedSourcePaths:
+				typeof flags.get("excluded-source-paths") === "string"
+					? flags
+							.get("excluded-source-paths")
+							.split(",")
+							.map((entry) => entry.trim())
+							.filter(Boolean)
+					: [],
+		});
+		process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+		if (!report.detected) {
+			process.exitCode = 1;
+		}
+		return;
+	}
+
+	if (command === "semantic-workflow") {
+		const request = buildSemanticWorkflowRequestFromFlags({
+			framework: flags.get("framework"),
+			backendRootPath: flags.get("backend-root-path"),
+			allowedSourcePaths: flags.get("allowed-source-paths"),
+			excludedSourcePaths: flags.get("excluded-source-paths"),
+			serviceKey: flags.get("service-key"),
+			workflowPath: flags.get("workflow-path"),
+		});
+		const report = await writeSemanticWorkflow({ repoRoot, request });
+		process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+		return;
+	}
+
+	if (command === "semantic-inventory") {
+		const request = buildSemanticWorkflowRequestFromFlags({
+			framework: flags.get("framework"),
+			backendRootPath: flags.get("backend-root-path"),
+			allowedSourcePaths: flags.get("allowed-source-paths"),
+			excludedSourcePaths: flags.get("excluded-source-paths"),
+			serviceKey: flags.get("service-key"),
+			workflowPath: flags.get("workflow-path"),
+		});
+		const report = await runSemanticInventory({ repoRoot, request });
+		await writeJsonIfRequested({
+			repoRoot,
+			outputPath: flags.get("output"),
+			value: report,
+		});
+		process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+		return;
+	}
+
+	if (command === "lifecycle-apply") {
+		const planPath = flags.get("plan");
+		if (typeof planPath !== "string") {
+			throw new Error("--plan is required");
+		}
+		const plan = await readJson(resolve(planPath));
+		const report = await applyLifecyclePlan({ repoRoot, plan });
+		process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+		return;
+	}
+
+	if (command === "setup-check") {
+		const hasInventoryFlags =
+			typeof flags.get("framework") === "string" &&
+			typeof flags.get("backend-root-path") === "string";
+		const request = hasInventoryFlags
+			? buildSemanticWorkflowRequestFromFlags({
+					framework: flags.get("framework"),
+					backendRootPath: flags.get("backend-root-path"),
+					allowedSourcePaths: flags.get("allowed-source-paths"),
+					excludedSourcePaths: flags.get("excluded-source-paths"),
+					serviceKey: flags.get("service-key"),
+					workflowPath: flags.get("workflow-path"),
+				})
+			: undefined;
+		const report = await runSetupCheck({
+			repoRoot,
+			request,
+			target:
+				typeof flags.get("target") === "string"
+					? flags.get("target")
+					: undefined,
+			requireSdkLifecycle: flags.has("require-sdk-lifecycle"),
+		});
+		process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+		if (!report.passed) {
+			process.exitCode = 1;
+		}
+		return;
+	}
+
+	const requestEnvName = flags.get("request-env");
+	if (typeof requestPath !== "string" && typeof requestEnvName !== "string") {
+		throw new Error("--request is required");
+	}
+	const request =
+		typeof requestEnvName === "string"
+			? JSON.parse(process.env[requestEnvName] ?? "")
+			: await readJson(resolve(requestPath));
+
+	if (command === "init") {
+		const report = await runInitTool({ repoRoot, request });
+		process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+		return;
+	}
+
+	if (command === "semantic-ci") {
+		const previousSnapshotPath =
+			flags.get("previous-snapshot") ?? flags.get("previous-snapshot-file");
+		const previousSnapshot =
+			typeof previousSnapshotPath === "string"
+				? await readJson(resolve(previousSnapshotPath))
+				: undefined;
+		const result = await runSemanticCi({
+			repoRoot,
+			request,
+			env: process.env,
+			previousSnapshot,
+		});
+		process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+		return;
+	}
+
+	throw new Error(`Unknown command: ${command}\n${usage()}`);
+};
+
+main().catch((error) => {
+	process.stderr.write(
+		`${error instanceof Error ? error.message : String(error)}\n`,
+	);
+	process.exitCode = 1;
+});