@clue-ai/cli 0.0.4 → 0.0.6

package/bin/clue-cli.mjs

@@ -1,9 +1,19 @@
 #!/usr/bin/env node
-import { readFile } from "node:fs/promises";
-import { resolve } from "node:path";
+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 { runInitTool } from "../src/init-tool.mjs";
-import { runSemanticCi } from "../src/semantic-ci.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) => {
@@ -26,13 +36,676 @@ const parseArgs = (argv) => {
 
 const readJson = async (path) => JSON.parse(await readFile(path, "utf8"));
 
-const usage = () => [
-  "Usage:",
-  "  /clue-init",
-  "  clue-ai setup",
-  "  clue-ai init --request clue-init-request.json --repo .",
-  "  clue-ai semantic-ci --request clue-semantic-request.json --repo .",
-].join("\n");
+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-api-key <key> --clue-api-base-url <url> --project-key <key> --environment dev",
+    "  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 renderEnvironmentInstructions = (instructions) => {
+  if (!instructions || instructions.status !== "ready") {
+    return "";
+  }
+  const lines = ["", instructions.message, ""];
+  for (const block of instructions.service_env_blocks) {
+    lines.push(
+      `[${block.kind}] ${block.root_path} (${block.env_file_candidates.join(" or ")})`,
+      block.env_block,
+      "",
+    );
+  }
+  lines.push(
+    "GitHub Secrets",
+    ...instructions.ci_github.secrets.map(
+      (entry) => `${entry.name}=${entry.value}`,
+    ),
+    "",
+    "GitHub Variables",
+    ...instructions.ci_github.variables.map(
+      (entry) => `${entry.name}=${entry.value}`,
+    ),
+    "",
+  );
+  return `${lines.join("\n")}\n`;
+};
 
 const main = async () => {
   const { command, flags } = parseArgs(process.argv.slice(2));
@@ -42,25 +715,158 @@ const main = async () => {
   }
 
   if (command === "commands") {
-    process.stdout.write(`${JSON.stringify({ commands: commandSpecs }, null, 2)}\n`);
+    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,
+      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,
+          setupContext: {
+            clueApiKey: flags.get("clue-api-key"),
+            clueApiBaseUrl: flags.get("clue-api-base-url"),
+            projectKey: flags.get("project-key"),
+            environment: flags.get("environment"),
+          },
+        });
+    const environmentInstructions = renderEnvironmentInstructions(
+      preparation.environment_instructions,
+    );
+    if (environmentInstructions) {
+      process.stderr.write(environmentInstructions);
+    }
+    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 (typeof requestPath !== "string") {
+  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 = await readJson(resolve(requestPath));
+  const request =
+    typeof requestEnvName === "string"
+      ? JSON.parse(process.env[requestEnvName] ?? "")
+      : await readJson(resolve(requestPath));
 
   if (command === "init") {
     const report = await runInitTool({ repoRoot, request });
@@ -69,7 +875,18 @@ const main = async () => {
   }
 
   if (command === "semantic-ci") {
-    const result = await runSemanticCi({ repoRoot, request, env: process.env });
+    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;
   }
@@ -78,6 +895,8 @@ const main = async () => {
 };
 
 main().catch((error) => {
-  process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+  process.stderr.write(
+    `${error instanceof Error ? error.message : String(error)}\n`,
+  );
   process.exitCode = 1;
 });