@arrhq/crate-cli 0.1.0

package/src/cli.mjs

@@ -0,0 +1,1473 @@
+#!/usr/bin/env node
+
+import { execFile } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { promisify } from "node:util";
+
+const DEFAULT_TIMEOUT_MS = 20_000;
+const DEFAULT_MAX_WAIT_SECONDS = 180;
+const DEFAULT_POLL_INTERVAL_SECONDS = 3;
+
+const UUID_PATTERN =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const SESSION_ID_PATTERN = /^[A-Za-z0-9._:@/-]{1,128}$/;
+const CONTEXT_LABEL_PATTERN = /^(?:checkpoint:)?[a-z0-9][a-z0-9._/:-]{1,95}$/;
+const CORRELATION_ID_PATTERN = /^[A-Za-z0-9._:@/-]{1,128}$/;
+const GITHUB_REPO_PATTERN = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+const CHECKPOINT_PENDING_PATTERN =
+  /task close failed: checkpoint_status (?:must be persisted before close|wait timed out before persisted) \(status=([^,\s)]+), decision=([^\s)]+)\)\./i;
+
+const execFileAsync = promisify(execFile);
+
+const HELP_TEXT = `Usage:
+  crate <command> [options]
+
+Commands:
+  tool list
+  tool call
+  tasks list
+  tasks create
+  tasks update
+  tasks close
+  checkpoint status
+
+Examples:
+  crate tool list
+  crate tool call --name list_project_tasks --args-json '{"status":"open","limit":20}'
+  crate tasks list --status in_progress --limit 50
+  crate tasks create --title "設計task" --description "詳細設計"
+  crate tasks update --task-id <task_uuid> --status in_progress
+  crate tasks close --task-id <task_uuid> --client-event-id <checkpoint_uuid>
+  crate checkpoint status --client-event-id <checkpoint_uuid>
+
+Global options:
+  --mcp-url <url>              MCP endpoint URL
+  --mcp-ingest-token <token>   MCP token (x-crate-ingest-token)
+  --server-name <name>         mcp server key in ~/.codex/config.toml
+  --timeout-ms <ms>            RPC timeout (default: 20000)
+  --json                       JSON output
+  --help                       Show help`;
+
+const COMMAND_HELP = {
+  "tool list": `Usage: crate tool list [options]
+Options:
+  --mcp-url <url>
+  --mcp-ingest-token <token>
+  --server-name <name>
+  --timeout-ms <ms>
+  --json`,
+  "tool call": `Usage: crate tool call --name <tool> [options]
+Options:
+  --name <tool_name>           MCP tool name (required)
+  --args-json <json>           Tool arguments as JSON object (default: {})
+  --args-file <path>           Path to JSON file for tool arguments
+  --mcp-url <url>
+  --mcp-ingest-token <token>
+  --server-name <name>
+  --timeout-ms <ms>
+  --json`,
+  "tasks list": `Usage: crate tasks list [options]
+Options:
+  --project-id <uuid>
+  --status <open|in_progress|close|canceled>
+  --limit <n>
+  --mcp-url <url>
+  --mcp-ingest-token <token>
+  --server-name <name>
+  --timeout-ms <ms>
+  --json`,
+  "tasks create": `Usage: crate tasks create --title <text> [options]
+Options:
+  --title <text>               Task title (required)
+  --description <text>
+  --project-id <uuid>
+  --github-repo-full-name <owner/repo>
+  --session-id <id>            default: CODEX_THREAD_ID
+  --occurred-at <iso8601>      default: now
+  --client-event-id <uuid>     default: generated
+  --correlation-id <id>        default: task/create/<epoch_ms>
+  --context-label <label>
+  --actor-context <text>
+  --source-context <text>
+  --mcp-url <url>
+  --mcp-ingest-token <token>
+  --server-name <name>
+  --timeout-ms <ms>
+  --json`,
+  "tasks update": `Usage: crate tasks update --task-id <uuid> [options]
+Options:
+  --task-id <uuid>             Target task id (required)
+  --title <text>
+  --description <text>
+  --status <open|in_progress|close|canceled>
+  --project-id <uuid>
+  --github-repo-full-name <owner/repo>
+  --session-id <id>            default: CODEX_THREAD_ID
+  --occurred-at <iso8601>      default: now
+  --client-event-id <uuid>     default: generated (except status=close with --context-label)
+  --correlation-id <id>        default: task/update/<task-id>/<epoch_ms>
+  --context-label <label>      required fallback when status=close and client_event_id omitted
+  --actor-context <text>
+  --source-context <text>
+  --mcp-url <url>
+  --mcp-ingest-token <token>
+  --server-name <name>
+  --timeout-ms <ms>
+  --json`,
+  "tasks close": `Usage: crate tasks close --task-id <uuid> [options]
+Options:
+  --task-id <uuid>             Task ID to close (required)
+  --session-id <id>            default: CODEX_THREAD_ID
+  --occurred-at <iso8601>      default: now
+  --correlation-id <id>        default: task/close/<task-id>/<epoch_ms>
+  --client-event-id <uuid>     Checkpoint event ID (preferred)
+  --context-label <label>      Fallback checkpoint label (checkpoint:<note>:<work_slug>)
+  --project-id <uuid>
+  --github-repo-full-name <owner/repo>
+  --max-wait-seconds <n>       default: 180
+  --poll-interval-seconds <n>  default: 3
+  --mcp-url <url>
+  --mcp-ingest-token <token>
+  --server-name <name>
+  --timeout-ms <ms>
+  --json`,
+  "checkpoint status": `Usage: crate checkpoint status [options]
+Options:
+  --client-event-id <uuid>     Preferred lookup key
+  --session-id <id>            Required when client_event_id omitted
+  --context-label <label>      Required when client_event_id omitted
+  --project-id <uuid>
+  --mcp-url <url>
+  --mcp-ingest-token <token>
+  --server-name <name>
+  --timeout-ms <ms>
+  --json`,
+};
+
+const parseArgValue = (arg, prefix) => {
+  if (arg === prefix) return null;
+  if (arg.startsWith(`${prefix}=`)) return arg.slice(prefix.length + 1);
+  return undefined;
+};
+
+const decodeTomlString = (value) =>
+  value
+    .replace(/\\n/g, "\n")
+    .replace(/\\r/g, "\r")
+    .replace(/\\t/g, "\t")
+    .replace(/\\"/g, '"')
+    .replace(/\\\\/g, "\\");
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+const toTrimmed = (value) => (typeof value === "string" ? value.trim() : "");
+
+const normalizeSessionId = (value) => {
+  const trimmed = toTrimmed(value);
+  if (!trimmed) return "";
+  return SESSION_ID_PATTERN.test(trimmed) ? trimmed : "";
+};
+
+const normalizeClientEventId = (value) => {
+  const trimmed = toTrimmed(value).toLowerCase();
+  if (!trimmed) return "";
+  return UUID_PATTERN.test(trimmed) ? trimmed : "";
+};
+
+const normalizeContextLabel = (value) => {
+  const trimmed = toTrimmed(value).toLowerCase();
+  if (!trimmed) return "";
+  if (!CONTEXT_LABEL_PATTERN.test(trimmed)) return "";
+  return trimmed.startsWith("checkpoint:") ? trimmed : `checkpoint:${trimmed}`;
+};
+
+const normalizeCorrelationId = (value) => {
+  const trimmed = toTrimmed(value);
+  if (!trimmed) return "";
+  return CORRELATION_ID_PATTERN.test(trimmed) ? trimmed : "";
+};
+
+const normalizeOccurredAt = (value) => {
+  const trimmed = toTrimmed(value);
+  if (!trimmed) return "";
+  const parsed = Date.parse(trimmed);
+  if (Number.isNaN(parsed)) return "";
+  return new Date(parsed).toISOString();
+};
+
+const normalizeGithubRepoFullName = (value) => {
+  const raw = toTrimmed(value);
+  if (!raw) return "";
+
+  const asDirect = raw.replace(/\.git$/i, "").replace(/^\/+|\/+$/g, "");
+  if (GITHUB_REPO_PATTERN.test(asDirect)) return asDirect;
+
+  const sshMatch = raw.match(/^git@[^:]+:([^/]+\/[^/]+?)(?:\.git)?$/i);
+  if (sshMatch?.[1]) {
+    const candidate = sshMatch[1].replace(/\.git$/i, "");
+    return GITHUB_REPO_PATTERN.test(candidate) ? candidate : "";
+  }
+
+  try {
+    const parsed = new URL(raw);
+    const segments = parsed.pathname
+      .split("/")
+      .map((segment) => segment.trim())
+      .filter(Boolean);
+    if (segments.length !== 2) return "";
+    const candidate = `${segments[0]}/${segments[1]}`.replace(/\.git$/i, "");
+    return GITHUB_REPO_PATTERN.test(candidate) ? candidate : "";
+  } catch {
+    return "";
+  }
+};
+
+const parsePositiveInteger = (value, flagName) => {
+  const parsed = Number.parseInt(String(value), 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw new Error(`${flagName} must be a positive integer.`);
+  }
+  return parsed;
+};
+
+const parseBooleanInline = (value, flagName) => {
+  const normalized = toTrimmed(value).toLowerCase();
+  if (normalized === "" || normalized === "1" || normalized === "true") return true;
+  if (normalized === "0" || normalized === "false") return false;
+  throw new Error(`${flagName} only accepts true/false.`);
+};
+
+const parseFlags = (argv, schema, defaults = {}) => {
+  const options = { ...defaults };
+  const seenFlags = new Set();
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--") continue;
+    if (!arg.startsWith("--")) {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+
+    const eqIndex = arg.indexOf("=");
+    const flag = eqIndex === -1 ? arg : arg.slice(0, eqIndex);
+    const inlineValue = eqIndex === -1 ? undefined : arg.slice(eqIndex + 1);
+    const rule = schema[flag];
+    if (!rule) {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+
+    seenFlags.add(flag);
+
+    if (rule.type === "boolean") {
+      options[rule.key] =
+        inlineValue === undefined ? true : parseBooleanInline(inlineValue, flag);
+      continue;
+    }
+
+    let rawValue = inlineValue;
+    if (rawValue === undefined) {
+      const next = argv[index + 1];
+      if (!next || next.startsWith("--")) {
+        throw new Error(`${flag} requires a value.`);
+      }
+      rawValue = next;
+      index += 1;
+    }
+
+    if (rule.type === "integer") {
+      options[rule.key] = parsePositiveInteger(rawValue, flag);
+      continue;
+    }
+
+    options[rule.key] = rawValue;
+  }
+
+  return { options, seenFlags };
+};
+
+const getCommonDefaults = () => ({
+  mcpUrl: process.env.CRATE_MCP_URL?.trim() ?? "",
+  mcpIngestToken: process.env.CRATE_MCP_INGEST_TOKEN?.trim() ?? "",
+  serverName: process.env.CRATE_MCP_SERVER_NAME?.trim() ?? "",
+  timeoutMs: DEFAULT_TIMEOUT_MS,
+  outputJson: false,
+  help: false,
+});
+
+const getWriteDefaults = () => ({
+  sessionId: process.env.CODEX_THREAD_ID?.trim() ?? "",
+  occurredAt: process.env.CRATE_EVENT_OCCURRED_AT?.trim() ?? "",
+  correlationId: process.env.CRATE_EVENT_CORRELATION_ID?.trim() ?? "",
+  clientEventId: process.env.CRATE_EVENT_CLIENT_EVENT_ID?.trim() ?? "",
+  contextLabel: process.env.CRATE_EVENT_CONTEXT_LABEL?.trim() ?? "",
+});
+
+const COMMON_SCHEMA = {
+  "--mcp-url": { key: "mcpUrl", type: "string" },
+  "--mcp-ingest-token": { key: "mcpIngestToken", type: "string" },
+  "--server-name": { key: "serverName", type: "string" },
+  "--timeout-ms": { key: "timeoutMs", type: "integer" },
+  "--json": { key: "outputJson", type: "boolean" },
+  "--help": { key: "help", type: "boolean" },
+};
+
+const WRITE_SCHEMA = {
+  "--session-id": { key: "sessionId", type: "string" },
+  "--occurred-at": { key: "occurredAt", type: "string" },
+  "--correlation-id": { key: "correlationId", type: "string" },
+  "--client-event-id": { key: "clientEventId", type: "string" },
+  "--context-label": { key: "contextLabel", type: "string" },
+  "--actor-context": { key: "actorContext", type: "string" },
+  "--source-context": { key: "sourceContext", type: "string" },
+  "--project-id": { key: "projectId", type: "string" },
+  "--github-repo-full-name": { key: "githubRepoFullName", type: "string" },
+};
+
+const normalizeCommonOptions = (options) => {
+  options.mcpUrl = toTrimmed(options.mcpUrl);
+  options.mcpIngestToken = toTrimmed(options.mcpIngestToken);
+  options.serverName = toTrimmed(options.serverName);
+  options.timeoutMs = parsePositiveInteger(options.timeoutMs, "--timeout-ms");
+  return options;
+};
+
+const normalizeWriteEventOptions = ({
+  options,
+  seenFlags,
+  defaultCorrelationId,
+  requireClientEventId,
+}) => {
+  options.sessionId = normalizeSessionId(options.sessionId);
+  if (seenFlags.has("--session-id") && !options.sessionId) {
+    throw new Error("--session-id must match [A-Za-z0-9._:@/-]{1,128}.");
+  }
+  if (!options.sessionId) {
+    throw new Error("--session-id is required (or set CODEX_THREAD_ID).");
+  }
+
+  const normalizedOccurredAt = normalizeOccurredAt(options.occurredAt);
+  if (seenFlags.has("--occurred-at") && !normalizedOccurredAt) {
+    throw new Error("--occurred-at must be a valid timestamp.");
+  }
+  options.occurredAt = normalizedOccurredAt || new Date().toISOString();
+
+  options.correlationId = normalizeCorrelationId(options.correlationId);
+  if (seenFlags.has("--correlation-id") && !options.correlationId) {
+    throw new Error("--correlation-id must match [A-Za-z0-9._:@/-]{1,128}.");
+  }
+  if (!options.correlationId) {
+    options.correlationId = defaultCorrelationId;
+  }
+
+  options.clientEventId = normalizeClientEventId(options.clientEventId);
+  if (seenFlags.has("--client-event-id") && !options.clientEventId) {
+    throw new Error("--client-event-id must be UUID.");
+  }
+
+  options.contextLabel = normalizeContextLabel(options.contextLabel);
+  if (seenFlags.has("--context-label") && !options.contextLabel) {
+    throw new Error(
+      "--context-label must be checkpoint:<note>:<work_slug> or <note>:<work_slug>.",
+    );
+  }
+
+  if (requireClientEventId) {
+    options.clientEventId = options.clientEventId || randomUUID();
+  }
+
+  options.projectId = toTrimmed(options.projectId);
+  options.githubRepoFullName = normalizeGithubRepoFullName(options.githubRepoFullName);
+  if (seenFlags.has("--github-repo-full-name") && !options.githubRepoFullName) {
+    throw new Error("--github-repo-full-name must be owner/repo.");
+  }
+
+  options.actorContext = toTrimmed(options.actorContext);
+  options.sourceContext = toTrimmed(options.sourceContext);
+
+  return options;
+};
+
+const readCodexServerConfigs = async () => {
+  const configPath = join(homedir(), ".codex", "config.toml");
+  let raw = "";
+  try {
+    raw = await readFile(configPath, "utf8");
+  } catch {
+    return [];
+  }
+
+  const servers = new Map();
+  let currentSection = "";
+
+  const ensureServer = (name) => {
+    if (!servers.has(name)) {
+      servers.set(name, {
+        name,
+        url: "",
+        token: "",
+        enabled: true,
+      });
+    }
+    return servers.get(name);
+  };
+
+  for (const sourceLine of raw.split(/\r?\n/)) {
+    const line = sourceLine.trim();
+    if (!line || line.startsWith("#")) continue;
+
+    const sectionMatch = line.match(/^\[([^\]]+)\]$/);
+    if (sectionMatch) {
+      currentSection = sectionMatch[1];
+      continue;
+    }
+
+    if (!currentSection.startsWith("mcp_servers.")) continue;
+
+    const relativeSection = currentSection.slice("mcp_servers.".length);
+    const isHeaderSection = relativeSection.endsWith(".http_headers");
+    const serverName = isHeaderSection
+      ? relativeSection.slice(0, -".http_headers".length)
+      : relativeSection;
+    if (!serverName) continue;
+
+    const server = ensureServer(serverName);
+
+    const boolMatch = sourceLine.match(/^[\s]*([A-Za-z0-9._-]+)[\s]*=[\s]*(true|false)[\s]*$/i);
+    if (boolMatch && !isHeaderSection) {
+      if (boolMatch[1] === "enabled") {
+        server.enabled = boolMatch[2].toLowerCase() === "true";
+      }
+      continue;
+    }
+
+    const pairMatch = sourceLine.match(
+      /^[\s]*([A-Za-z0-9._-]+)[\s]*=[\s]*"((?:[^"\\]|\\.)*)"[\s]*$/,
+    );
+    if (!pairMatch) continue;
+
+    const key = pairMatch[1];
+    const value = decodeTomlString(pairMatch[2]);
+
+    if (!isHeaderSection && key === "url") {
+      server.url = value;
+      continue;
+    }
+    if (isHeaderSection && key === "x-crate-ingest-token") {
+      server.token = value;
+    }
+  }
+
+  return [...servers.values()];
+};
+
+const parseGithubRepoFromRemoteUrl = (remoteUrl) => {
+  const raw = toTrimmed(remoteUrl);
+  if (!raw) return "";
+  return normalizeGithubRepoFullName(raw);
+};
+
+const inferGithubRepoFromGitRemote = async () => {
+  try {
+    const { stdout } = await execFileAsync("git", ["remote", "get-url", "origin"], {
+      timeout: 5_000,
+      maxBuffer: 64 * 1024,
+    });
+    return parseGithubRepoFromRemoteUrl(stdout);
+  } catch {
+    return "";
+  }
+};
+
+const resolveMcpConnection = async (options) => {
+  if (options.mcpUrl && options.mcpIngestToken) {
+    return {
+      mcpUrl: options.mcpUrl,
+      mcpIngestToken: options.mcpIngestToken,
+    };
+  }
+
+  if (options.mcpUrl && !options.mcpIngestToken) {
+    throw new Error("MCP token is missing. Provide --mcp-ingest-token.");
+  }
+  if (!options.mcpUrl && options.mcpIngestToken) {
+    throw new Error("MCP URL is missing. Provide --mcp-url.");
+  }
+
+  const servers = await readCodexServerConfigs();
+  const enabledComplete = servers.filter(
+    (server) => server.enabled !== false && server.url && server.token,
+  );
+
+  if (options.serverName) {
+    const matched = enabledComplete.find((server) => server.name === options.serverName);
+    if (!matched) {
+      throw new Error(
+        `MCP server '${options.serverName}' was not found or incomplete in ~/.codex/config.toml.`,
+      );
+    }
+    return {
+      mcpUrl: matched.url,
+      mcpIngestToken: matched.token,
+    };
+  }
+
+  if (enabledComplete.length === 1) {
+    return {
+      mcpUrl: enabledComplete[0].url,
+      mcpIngestToken: enabledComplete[0].token,
+    };
+  }
+
+  throw new Error(
+    "Unable to resolve MCP server automatically. Provide --server-name, or --mcp-url and --mcp-ingest-token.",
+  );
+};
+
+const parseEventStreamBody = (rawText) => {
+  if (typeof rawText !== "string" || rawText.trim() === "") return null;
+
+  const events = rawText.split(/\r?\n\r?\n/);
+  for (let index = events.length - 1; index >= 0; index -= 1) {
+    const chunk = events[index];
+    if (!chunk.includes("data:")) continue;
+    const dataLines = chunk
+      .split(/\r?\n/)
+      .filter((line) => line.startsWith("data:"))
+      .map((line) => line.slice("data:".length).trimStart());
+    if (dataLines.length === 0) continue;
+    const eventData = dataLines.join("\n").trim();
+    if (!eventData || eventData === "[DONE]") continue;
+    try {
+      return JSON.parse(eventData);
+    } catch {
+      // Ignore parse errors.
+    }
+  }
+
+  return null;
+};
+
+const parseRpcResponseBody = async (response) => {
+  const contentType = response.headers.get("content-type")?.toLowerCase() ?? "";
+  if (contentType.includes("application/json")) {
+    return response.json().catch(() => null);
+  }
+
+  const rawText = await response.text().catch(() => "");
+  if (!rawText) return null;
+
+  const fromSse = parseEventStreamBody(rawText);
+  if (fromSse) return fromSse;
+
+  try {
+    return JSON.parse(rawText);
+  } catch {
+    return null;
+  }
+};
+
+const rpcCall = async ({ url, payload, timeoutMs, token, sessionId }) => {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const headers = {
+      "Content-Type": "application/json",
+      Accept: "application/json, text/event-stream",
+      "x-crate-ingest-token": token,
+    };
+    if (sessionId) {
+      headers["mcp-session-id"] = sessionId;
+    }
+
+    const response = await fetch(url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(payload),
+      signal: controller.signal,
+    });
+
+    const body = await parseRpcResponseBody(response);
+    const nextSessionId = response.headers.get("mcp-session-id") ?? sessionId ?? "";
+    return {
+      ok: response.ok,
+      status: response.status,
+      body,
+      sessionId: nextSessionId,
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+};
+
+const extractToolText = (rpcBody) => {
+  const content = rpcBody?.result?.content;
+  if (!Array.isArray(content)) return "";
+  const textItem = content.find((item) => item && item.type === "text");
+  return typeof textItem?.text === "string" ? textItem.text : "";
+};
+
+const assertRpcSuccess = (response, actionName) => {
+  if (!response.body) {
+    throw new Error(`${actionName}: empty response body (status=${response.status}).`);
+  }
+  if (response.body.error) {
+    const message = response.body.error?.message ?? "RPC error";
+    throw new Error(`${actionName}: ${message}`);
+  }
+};
+
+const createMcpClient = ({ url, token, timeoutMs, clientName, clientVersion }) => {
+  let rpcId = 1;
+  let sessionId = "";
+
+  const call = async (method, params) => {
+    const response = await rpcCall({
+      url,
+      payload: {
+        jsonrpc: "2.0",
+        id: rpcId,
+        method,
+        params,
+      },
+      timeoutMs,
+      token,
+      sessionId,
+    });
+    rpcId += 1;
+    if (response.sessionId) {
+      sessionId = response.sessionId;
+    }
+    return response;
+  };
+
+  const initialize = async () => {
+    const response = await call("initialize", {
+      protocolVersion: "2025-06-18",
+      capabilities: {},
+      clientInfo: {
+        name: clientName,
+        version: clientVersion,
+      },
+    });
+    assertRpcSuccess(response, "initialize");
+  };
+
+  const listTools = async () => {
+    const response = await call("tools/list", {});
+    assertRpcSuccess(response, "tools/list");
+    return response.body?.result ?? {};
+  };
+
+  const callTool = async (name, args) => {
+    const response = await call("tools/call", {
+      name,
+      arguments: args,
+    });
+    assertRpcSuccess(response, `tools/call:${name}`);
+
+    const text = extractToolText(response.body) || "";
+    const isError = Boolean(response.body?.result?.isError);
+    return {
+      isError,
+      text,
+      result: response.body?.result ?? null,
+    };
+  };
+
+  return { initialize, listTools, callTool };
+};
+
+const parseJsonText = (text, label) => {
+  try {
+    return JSON.parse(text);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`${label}: failed to parse JSON response (${message}).`);
+  }
+};
+
+const tryParseJsonText = (text) => {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+};
+
+const callToolExpectJson = async (client, toolName, args) => {
+  const result = await client.callTool(toolName, args);
+  if (result.isError) {
+    throw new Error(`${toolName} failed: ${result.text}`);
+  }
+  return {
+    payload: parseJsonText(result.text, toolName),
+    text: result.text,
+    rawResult: result.result,
+  };
+};
+
+const classifyTaskCloseError = (message) => {
+  const normalized = toTrimmed(message);
+  const matched = normalized.match(CHECKPOINT_PENDING_PATTERN);
+  if (!matched) {
+    return {
+      retryable: false,
+      status: null,
+      decision: null,
+    };
+  }
+
+  const status = toTrimmed(matched[1]).toLowerCase();
+  const decision = toTrimmed(matched[2]).toLowerCase();
+  const retryableStatuses = new Set(["queued", "processing", "retrying"]);
+
+  return {
+    retryable: decision === "pending" && retryableStatuses.has(status),
+    status: status || null,
+    decision: decision || null,
+  };
+};
+
+const toCheckpointLookupArgs = (options) => {
+  const args = {};
+  if (options.projectId) args.project_id = options.projectId;
+  if (options.clientEventId) {
+    args.client_event_id = options.clientEventId;
+    return args;
+  }
+  args.session_id = options.sessionId;
+  args.context_label = options.contextLabel;
+  return args;
+};
+
+const toTaskCloseArgs = (options) => {
+  const args = {
+    task_id: options.taskId,
+    status: "close",
+    session_id: options.sessionId,
+    occurred_at: options.occurredAt,
+    correlation_id: options.correlationId,
+  };
+  if (options.projectId) args.project_id = options.projectId;
+  if (options.githubRepoFullName) args.github_repo_full_name = options.githubRepoFullName;
+  if (options.clientEventId) args.client_event_id = options.clientEventId;
+  if (options.contextLabel) args.context_label = options.contextLabel;
+  if (options.actorContext) args.actor_context = options.actorContext;
+  if (options.sourceContext) args.source_context = options.sourceContext;
+  return args;
+};
+
+const tryTaskClose = async (client, options) => {
+  const result = await client.callTool("update_project_task", toTaskCloseArgs(options));
+  if (result.isError) {
+    return {
+      ok: false,
+      error: result.text,
+    };
+  }
+
+  return {
+    ok: true,
+    payload: parseJsonText(result.text, "update_project_task"),
+  };
+};
+
+const waitForCheckpointPersisted = async (client, options) => {
+  const maxWaitMs = options.maxWaitSeconds * 1000;
+  const pollIntervalMs = options.pollIntervalSeconds * 1000;
+  const startedAt = Date.now();
+  const history = [];
+
+  while (Date.now() - startedAt <= maxWaitMs) {
+    const statusResult = await client.callTool(
+      "checkpoint_status",
+      toCheckpointLookupArgs(options),
+    );
+    if (statusResult.isError) {
+      throw new Error(`checkpoint_status failed: ${statusResult.text}`);
+    }
+
+    const payload = parseJsonText(statusResult.text, "checkpoint_status");
+    const record = {
+      checked_at: new Date().toISOString(),
+      status: toTrimmed(payload?.status),
+      decision: toTrimmed(payload?.gate?.decision),
+      passed: Boolean(payload?.gate?.passed),
+      matched_by: toTrimmed(payload?.matched_by) || null,
+      snapshot_id: toTrimmed(payload?.snapshot?.id) || null,
+    };
+    history.push(record);
+
+    if (record.passed || record.status === "persisted") {
+      return {
+        ok: true,
+        history,
+      };
+    }
+
+    if (record.status === "failed" || record.decision === "fail") {
+      return {
+        ok: false,
+        history,
+        reason: "checkpoint_failed",
+      };
+    }
+
+    await sleep(pollIntervalMs);
+  }
+
+  return {
+    ok: false,
+    history,
+    reason: "timeout",
+  };
+};
+
+const parseCommand = (argv) => {
+  const normalizedArgv = [...argv];
+  while (normalizedArgv[0] === "--") {
+    normalizedArgv.shift();
+  }
+
+  if (normalizedArgv.length === 0) {
+    return { key: "help", args: [] };
+  }
+
+  const first = toTrimmed(normalizedArgv[0]).toLowerCase();
+  const second = toTrimmed(normalizedArgv[1]).toLowerCase();
+
+  if (first === "help" || first === "--help" || first === "-h") {
+    return { key: "help", args: normalizedArgv.slice(1) };
+  }
+
+  const compound = `${first} ${second}`;
+  const knownCompound = new Set([
+    "tool list",
+    "tool call",
+    "tasks list",
+    "tasks create",
+    "tasks update",
+    "tasks close",
+    "checkpoint status",
+  ]);
+
+  if (knownCompound.has(compound)) {
+    return {
+      key: compound,
+      args: normalizedArgv.slice(2),
+    };
+  }
+
+  throw new Error(`Unknown command: ${normalizedArgv.slice(0, 2).join(" ")}`);
+};
+
+const createClient = async (options, runtime = {}) => {
+  const connection = await resolveMcpConnection(options);
+  const client = createMcpClient({
+    url: connection.mcpUrl,
+    token: connection.mcpIngestToken,
+    timeoutMs: options.timeoutMs,
+    clientName: runtime.clientName ?? "crate-cli",
+    clientVersion: runtime.clientVersion ?? "0.1.0",
+  });
+  await client.initialize();
+  return client;
+};
+
+const outputMaybeJson = (options, payload, textRenderer) => {
+  if (options.outputJson) {
+    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    return;
+  }
+  process.stdout.write(textRenderer(payload));
+};
+
+const parseToolArgsObject = async (options) => {
+  const hasInline = Boolean(toTrimmed(options.argsJson));
+  const hasFile = Boolean(toTrimmed(options.argsFile));
+  if (hasInline && hasFile) {
+    throw new Error("Specify only one of --args-json or --args-file.");
+  }
+
+  let raw = "";
+  if (hasInline) {
+    raw = options.argsJson;
+  } else if (hasFile) {
+    raw = await readFile(options.argsFile, "utf8");
+  }
+
+  if (!raw.trim()) {
+    return {};
+  }
+
+  const parsed = tryParseJsonText(raw);
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("Tool arguments must be a JSON object.");
+  }
+  return parsed;
+};
+
+const handleToolList = async (argv, runtime) => {
+  const { options } = parseFlags(argv, COMMON_SCHEMA, getCommonDefaults());
+  normalizeCommonOptions(options);
+
+  if (options.help) {
+    process.stdout.write(`${COMMAND_HELP["tool list"]}\n`);
+    return 0;
+  }
+
+  const client = await createClient(options, runtime);
+  const payload = await client.listTools();
+  const tools = Array.isArray(payload?.tools) ? payload.tools : [];
+
+  outputMaybeJson(options, { count: tools.length, tools: payload.tools ?? [] }, (data) => {
+    const lines = [`tools: ${data.count}`];
+    for (const tool of tools) {
+      const name = toTrimmed(tool?.name);
+      if (name) lines.push(`- ${name}`);
+    }
+    return `${lines.join("\n")}\n`;
+  });
+
+  return 0;
+};
+
+const handleToolCall = async (argv, runtime) => {
+  const schema = {
+    ...COMMON_SCHEMA,
+    "--name": { key: "toolName", type: "string" },
+    "--args-json": { key: "argsJson", type: "string" },
+    "--args-file": { key: "argsFile", type: "string" },
+  };
+
+  const { options } = parseFlags(argv, schema, {
+    ...getCommonDefaults(),
+    toolName: "",
+    argsJson: "",
+    argsFile: "",
+  });
+  normalizeCommonOptions(options);
+  options.toolName = toTrimmed(options.toolName);
+
+  if (options.help) {
+    process.stdout.write(`${COMMAND_HELP["tool call"]}\n`);
+    return 0;
+  }
+  if (!options.toolName) {
+    throw new Error("--name is required.");
+  }
+
+  const args = await parseToolArgsObject(options);
+  const client = await createClient(options, runtime);
+  const result = await client.callTool(options.toolName, args);
+
+  if (result.isError) {
+    throw new Error(`${options.toolName} failed: ${result.text}`);
+  }
+
+  const parsed = tryParseJsonText(result.text);
+  outputMaybeJson(
+    options,
+    {
+      tool: options.toolName,
+      args,
+      output: parsed ?? result.text,
+      raw_result: result.result,
+    },
+    (payload) => {
+      const lines = [`tool call succeeded: ${payload.tool}`];
+      if (typeof payload.output === "string") {
+        lines.push(payload.output);
+      } else {
+        lines.push(JSON.stringify(payload.output, null, 2));
+      }
+      return `${lines.join("\n")}\n`;
+    },
+  );
+
+  return 0;
+};
+
+const handleTasksList = async (argv, runtime) => {
+  const schema = {
+    ...COMMON_SCHEMA,
+    "--project-id": { key: "projectId", type: "string" },
+    "--status": { key: "status", type: "string" },
+    "--limit": { key: "limit", type: "integer" },
+  };
+
+  const { options } = parseFlags(argv, schema, {
+    ...getCommonDefaults(),
+    projectId: "",
+    status: "",
+    limit: 50,
+  });
+
+  normalizeCommonOptions(options);
+  options.projectId = toTrimmed(options.projectId);
+  options.status = toTrimmed(options.status);
+
+  if (options.help) {
+    process.stdout.write(`${COMMAND_HELP["tasks list"]}\n`);
+    return 0;
+  }
+
+  const args = {};
+  if (options.projectId) args.project_id = options.projectId;
+  if (options.status) args.status = options.status;
+  if (options.limit) args.limit = options.limit;
+
+  const client = await createClient(options, runtime);
+  const { payload } = await callToolExpectJson(client, "list_project_tasks", args);
+
+  outputMaybeJson(options, payload, (data) => {
+    const tasks = Array.isArray(data?.tasks) ? data.tasks : [];
+    const lines = [`tasks: ${tasks.length}`];
+    for (const task of tasks) {
+      const id = toTrimmed(task?.id);
+      const status = toTrimmed(task?.status) || "unknown";
+      const title = toTrimmed(task?.title) || "(no title)";
+      lines.push(`- [${status}] ${id} ${title}`);
+    }
+    return `${lines.join("\n")}\n`;
+  });
+
+  return 0;
+};
+
+const handleTasksCreate = async (argv, runtime) => {
+  const schema = {
+    ...COMMON_SCHEMA,
+    ...WRITE_SCHEMA,
+    "--title": { key: "title", type: "string" },
+    "--description": { key: "description", type: "string" },
+  };
+
+  const { options, seenFlags } = parseFlags(argv, schema, {
+    ...getCommonDefaults(),
+    ...getWriteDefaults(),
+    title: "",
+    description: "",
+    actorContext: "agent",
+    sourceContext: "crate-cli",
+    projectId: "",
+    githubRepoFullName: process.env.CRATE_GITHUB_REPO_FULL_NAME?.trim() ?? "",
+  });
+
+  normalizeCommonOptions(options);
+  options.title = toTrimmed(options.title);
+  options.description = toTrimmed(options.description);
+
+  if (options.help) {
+    process.stdout.write(`${COMMAND_HELP["tasks create"]}\n`);
+    return 0;
+  }
+  if (!options.title) {
+    throw new Error("--title is required.");
+  }
+
+  normalizeWriteEventOptions({
+    options,
+    seenFlags,
+    defaultCorrelationId: `task/create/${Date.now()}`,
+    requireClientEventId: true,
+  });
+
+  if (!options.githubRepoFullName) {
+    options.githubRepoFullName = await inferGithubRepoFromGitRemote();
+  }
+
+  const args = {
+    title: options.title,
+    session_id: options.sessionId,
+    occurred_at: options.occurredAt,
+    client_event_id: options.clientEventId,
+    correlation_id: options.correlationId,
+  };
+  if (options.description) args.description = options.description;
+  if (options.projectId) args.project_id = options.projectId;
+  if (options.contextLabel) args.context_label = options.contextLabel;
+  if (options.actorContext) args.actor_context = options.actorContext;
+  if (options.sourceContext) args.source_context = options.sourceContext;
+  if (options.githubRepoFullName) args.github_repo_full_name = options.githubRepoFullName;
+
+  const client = await createClient(options, runtime);
+  const { payload } = await callToolExpectJson(client, "create_project_task", args);
+
+  outputMaybeJson(options, payload, (data) => {
+    const task = data?.task ?? {};
+    const lines = ["task created"];
+    if (task.id) lines.push(`- task_id: ${task.id}`);
+    if (task.status) lines.push(`- status: ${task.status}`);
+    if (task.title) lines.push(`- title: ${task.title}`);
+    return `${lines.join("\n")}\n`;
+  });
+
+  return 0;
+};
+
+const handleTasksUpdate = async (argv, runtime) => {
+  const schema = {
+    ...COMMON_SCHEMA,
+    ...WRITE_SCHEMA,
+    "--task-id": { key: "taskId", type: "string" },
+    "--title": { key: "title", type: "string" },
+    "--description": { key: "description", type: "string" },
+    "--status": { key: "status", type: "string" },
+  };
+
+  const { options, seenFlags } = parseFlags(argv, schema, {
+    ...getCommonDefaults(),
+    ...getWriteDefaults(),
+    taskId: "",
+    title: "",
+    description: "",
+    status: "",
+    actorContext: "agent",
+    sourceContext: "crate-cli",
+    projectId: "",
+    githubRepoFullName: process.env.CRATE_GITHUB_REPO_FULL_NAME?.trim() ?? "",
+  });
+
+  normalizeCommonOptions(options);
+  options.taskId = toTrimmed(options.taskId);
+  options.title = toTrimmed(options.title);
+  options.description = toTrimmed(options.description);
+  options.status = toTrimmed(options.status);
+
+  if (options.help) {
+    process.stdout.write(`${COMMAND_HELP["tasks update"]}\n`);
+    return 0;
+  }
+  if (!options.taskId) {
+    throw new Error("--task-id is required.");
+  }
+  if (!options.title && !options.description && !options.status) {
+    throw new Error("Specify at least one of --title, --description, --status.");
+  }
+
+  const isClose = options.status === "close";
+  normalizeWriteEventOptions({
+    options,
+    seenFlags,
+    defaultCorrelationId: `task/update/${options.taskId}/${Date.now()}`,
+    requireClientEventId: !isClose,
+  });
+
+  if (isClose && !options.clientEventId && !options.contextLabel) {
+    throw new Error(
+      "status=close requires checkpoint evidence: --client-event-id (preferred) or --context-label.",
+    );
+  }
+
+  if (!options.githubRepoFullName) {
+    options.githubRepoFullName = await inferGithubRepoFromGitRemote();
+  }
+
+  const args = {
+    task_id: options.taskId,
+    session_id: options.sessionId,
+    occurred_at: options.occurredAt,
+    correlation_id: options.correlationId,
+  };
+  if (options.title) args.title = options.title;
+  if (options.description) args.description = options.description;
+  if (options.status) args.status = options.status;
+  if (options.projectId) args.project_id = options.projectId;
+  if (options.clientEventId) args.client_event_id = options.clientEventId;
+  if (options.contextLabel) args.context_label = options.contextLabel;
+  if (options.actorContext) args.actor_context = options.actorContext;
+  if (options.sourceContext) args.source_context = options.sourceContext;
+  if (options.githubRepoFullName) args.github_repo_full_name = options.githubRepoFullName;
+
+  const client = await createClient(options, runtime);
+  const { payload } = await callToolExpectJson(client, "update_project_task", args);
+
+  outputMaybeJson(options, payload, (data) => {
+    const task = data?.task ?? {};
+    const lines = ["task updated"];
+    if (task.id) lines.push(`- task_id: ${task.id}`);
+    if (task.status) lines.push(`- status: ${task.status}`);
+    if (task.title) lines.push(`- title: ${task.title}`);
+    return `${lines.join("\n")}\n`;
+  });
+
+  return 0;
+};
+
+const handleCheckpointStatus = async (argv, runtime) => {
+  const schema = {
+    ...COMMON_SCHEMA,
+    "--project-id": { key: "projectId", type: "string" },
+    "--client-event-id": { key: "clientEventId", type: "string" },
+    "--session-id": { key: "sessionId", type: "string" },
+    "--context-label": { key: "contextLabel", type: "string" },
+  };
+
+  const { options, seenFlags } = parseFlags(argv, schema, {
+    ...getCommonDefaults(),
+    projectId: "",
+    clientEventId: process.env.CRATE_EVENT_CLIENT_EVENT_ID?.trim() ?? "",
+    sessionId: process.env.CODEX_THREAD_ID?.trim() ?? "",
+    contextLabel: process.env.CRATE_EVENT_CONTEXT_LABEL?.trim() ?? "",
+  });
+
+  normalizeCommonOptions(options);
+  options.projectId = toTrimmed(options.projectId);
+  options.clientEventId = normalizeClientEventId(options.clientEventId);
+  options.sessionId = normalizeSessionId(options.sessionId);
+  options.contextLabel = normalizeContextLabel(options.contextLabel);
+
+  if (options.help) {
+    process.stdout.write(`${COMMAND_HELP["checkpoint status"]}\n`);
+    return 0;
+  }
+
+  if (seenFlags.has("--client-event-id") && !options.clientEventId) {
+    throw new Error("--client-event-id must be UUID.");
+  }
+  if (seenFlags.has("--session-id") && !options.sessionId) {
+    throw new Error("--session-id must match [A-Za-z0-9._:@/-]{1,128}.");
+  }
+  if (seenFlags.has("--context-label") && !options.contextLabel) {
+    throw new Error(
+      "--context-label must be checkpoint:<note>:<work_slug> or <note>:<work_slug>.",
+    );
+  }
+
+  if (!options.clientEventId && (!options.sessionId || !options.contextLabel)) {
+    throw new Error(
+      "checkpoint lookup requires --client-event-id, or both --session-id and --context-label.",
+    );
+  }
+
+  const args = toCheckpointLookupArgs(options);
+  const client = await createClient(options, runtime);
+  const { payload } = await callToolExpectJson(client, "checkpoint_status", args);
+
+  outputMaybeJson(options, payload, (data) => {
+    const lines = ["checkpoint status"];
+    lines.push(`- status: ${toTrimmed(data?.status) || "unknown"}`);
+    lines.push(`- decision: ${toTrimmed(data?.gate?.decision) || "unknown"}`);
+    lines.push(`- passed: ${Boolean(data?.gate?.passed)}`);
+    if (data?.matched_by) lines.push(`- matched_by: ${data.matched_by}`);
+    return `${lines.join("\n")}\n`;
+  });
+
+  return 0;
+};
+
+const parseTasksCloseOptions = (argv) => {
+  const schema = {
+    ...COMMON_SCHEMA,
+    ...WRITE_SCHEMA,
+    "--task-id": { key: "taskId", type: "string" },
+    "--max-wait-seconds": { key: "maxWaitSeconds", type: "integer" },
+    "--poll-interval-seconds": { key: "pollIntervalSeconds", type: "integer" },
+  };
+
+  const { options, seenFlags } = parseFlags(argv, schema, {
+    ...getCommonDefaults(),
+    ...getWriteDefaults(),
+    taskId: "",
+    projectId: process.env.CRATE_PROJECT_ID?.trim() ?? "",
+    githubRepoFullName: process.env.CRATE_GITHUB_REPO_FULL_NAME?.trim() ?? "",
+    maxWaitSeconds: DEFAULT_MAX_WAIT_SECONDS,
+    pollIntervalSeconds: DEFAULT_POLL_INTERVAL_SECONDS,
+    actorContext: "agent",
+    sourceContext: "crate-cli",
+  });
+
+  normalizeCommonOptions(options);
+  if (options.help) {
+    return options;
+  }
+
+  options.taskId = toTrimmed(options.taskId);
+  if (!options.taskId) {
+    throw new Error("--task-id is required.");
+  }
+
+  normalizeWriteEventOptions({
+    options,
+    seenFlags,
+    defaultCorrelationId: `task/close/${options.taskId || "unknown"}/${Date.now()}`,
+    requireClientEventId: false,
+  });
+
+  options.maxWaitSeconds = parsePositiveInteger(options.maxWaitSeconds, "--max-wait-seconds");
+  options.pollIntervalSeconds = parsePositiveInteger(
+    options.pollIntervalSeconds,
+    "--poll-interval-seconds",
+  );
+
+  if (!options.clientEventId && !options.contextLabel) {
+    throw new Error(
+      "checkpoint evidence is required: --client-event-id (preferred) or --context-label.",
+    );
+  }
+
+  return options;
+};
+
+const handleTasksClose = async (argv, runtime) => {
+  const options = parseTasksCloseOptions(argv);
+  if (options.help) {
+    process.stdout.write(`${COMMAND_HELP["tasks close"]}\n`);
+    return 0;
+  }
+
+  if (!options.githubRepoFullName) {
+    options.githubRepoFullName = await inferGithubRepoFromGitRemote();
+  }
+
+  const client = await createClient(options, runtime);
+
+  const closeAttempts = [];
+  let closeResult = await tryTaskClose(client, options);
+  closeAttempts.push({
+    attempted_at: new Date().toISOString(),
+    ok: closeResult.ok,
+    error: closeResult.ok ? null : closeResult.error,
+  });
+
+  let checkpointWait = null;
+
+  if (!closeResult.ok) {
+    const classified = classifyTaskCloseError(closeResult.error);
+    if (!classified.retryable) {
+      throw new Error(closeResult.error || "task close failed.");
+    }
+
+    checkpointWait = await waitForCheckpointPersisted(client, options);
+    if (!checkpointWait.ok) {
+      const tail = checkpointWait.history.at(-1);
+      throw new Error(
+        `task close retry aborted: reason=${checkpointWait.reason}, last_status=${tail?.status ?? "n/a"}, last_decision=${tail?.decision ?? "n/a"}`,
+      );
+    }
+
+    closeResult = await tryTaskClose(client, options);
+    closeAttempts.push({
+      attempted_at: new Date().toISOString(),
+      ok: closeResult.ok,
+      error: closeResult.ok ? null : closeResult.error,
+    });
+
+    if (!closeResult.ok) {
+      throw new Error(closeResult.error || "task close failed after checkpoint persisted.");
+    }
+  }
+
+  const payload = {
+    status: "closed",
+    task_id: options.taskId,
+    session_id: options.sessionId,
+    event_contract: {
+      occurred_at: options.occurredAt,
+      correlation_id: options.correlationId,
+      client_event_id: options.clientEventId || null,
+      context_label: options.contextLabel || null,
+    },
+    checkpoint_key: options.clientEventId
+      ? { client_event_id: options.clientEventId }
+      : { session_id: options.sessionId, context_label: options.contextLabel },
+    attempts: closeAttempts,
+    checkpoint_wait: checkpointWait,
+    result: closeResult.payload,
+  };
+
+  outputMaybeJson(options, payload, (data) => {
+    const lines = ["task close completed with checkpoint-aware retry"];
+    lines.push(`- task_id: ${data.task_id}`);
+    lines.push(`- session_id: ${data.session_id}`);
+    lines.push(`- close_attempts: ${data.attempts.length}`);
+    if (data.checkpoint_wait) {
+      lines.push(`- checkpoint_polls: ${data.checkpoint_wait.history.length}`);
+    }
+    return `${lines.join("\n")}\n`;
+  });
+
+  return 0;
+};
+
+const runWithCommand = async (command, args, runtime) => {
+  switch (command) {
+    case "tool list":
+      return handleToolList(args, runtime);
+    case "tool call":
+      return handleToolCall(args, runtime);
+    case "tasks list":
+      return handleTasksList(args, runtime);
+    case "tasks create":
+      return handleTasksCreate(args, runtime);
+    case "tasks update":
+      return handleTasksUpdate(args, runtime);
+    case "tasks close":
+      return handleTasksClose(args, runtime);
+    case "checkpoint status":
+      return handleCheckpointStatus(args, runtime);
+    case "help":
+      {
+        const normalized = args
+          .map((value) => toTrimmed(value).toLowerCase())
+          .filter((value) => value.length > 0);
+        const compound =
+          normalized.length >= 2 ? `${normalized[0]} ${normalized[1]}` : normalized[0] || "";
+        if (COMMAND_HELP[compound]) {
+          process.stdout.write(`${COMMAND_HELP[compound]}\n`);
+          return 0;
+        }
+      }
+      process.stdout.write(`${HELP_TEXT}\n`);
+      return 0;
+    default:
+      if (COMMAND_HELP[command]) {
+        process.stdout.write(`${COMMAND_HELP[command]}\n`);
+        return 0;
+      }
+      process.stdout.write(`${HELP_TEXT}\n`);
+      return 0;
+  }
+};
+
+export const runCrateCli = async (argv = process.argv.slice(2), runtime = {}) => {
+  const parsed = parseCommand(argv);
+  return runWithCommand(parsed.key, parsed.args, runtime);
+};
+
+export const __testables = {
+  classifyTaskCloseError,
+  normalizeContextLabel,
+  normalizeClientEventId,
+  normalizeSessionId,
+  parseCommand,
+  parseTasksCloseOptions,
+  parseFlags,
+  parseGithubRepoFromRemoteUrl,
+};
+
+const isExecutedAsScript = () => {
+  if (!process.argv[1]) return false;
+  try {
+    return import.meta.url === pathToFileURL(process.argv[1]).href;
+  } catch {
+    return false;
+  }
+};
+
+if (isExecutedAsScript()) {
+  runCrateCli()
+    .then((code) => {
+      process.exitCode = code;
+    })
+    .catch((error) => {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error(`crate-cli failed: ${message}`);
+      process.exitCode = 1;
+    });
+}