@commentary-dev/cli 0.1.0

package/dist/index.js

@@ -0,0 +1,1660 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { Command, Option } from "commander";
+
+// src/commands.ts
+import fs4 from "fs/promises";
+import path5 from "path";
+import chokidar from "chokidar";
+import open from "open";
+
+// src/errors.ts
+var CliError = class extends Error {
+  exitCode;
+  constructor(message, exitCode2 = 1) {
+    super(message);
+    this.name = "CliError";
+    this.exitCode = exitCode2;
+  }
+};
+var ExitCode = {
+  Ok: 0,
+  General: 1,
+  Usage: 2,
+  Auth: 3,
+  Network: 4,
+  Api: 5,
+  Safety: 6,
+  Timeout: 124
+};
+function toErrorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+// src/sse.ts
+var SseParser = class {
+  buffer = "";
+  id;
+  event;
+  dataLines = [];
+  retry;
+  feed(chunk) {
+    this.buffer += chunk;
+    const messages = [];
+    while (true) {
+      const boundary = this.findBoundary();
+      if (!boundary) {
+        break;
+      }
+      const raw = this.buffer.slice(0, boundary.index);
+      this.buffer = this.buffer.slice(boundary.index + boundary.length);
+      const message = this.consumeBlock(raw);
+      if (message) {
+        messages.push(message);
+      }
+    }
+    return messages;
+  }
+  flush() {
+    if (!this.buffer.trim()) {
+      this.buffer = "";
+      return [];
+    }
+    const message = this.consumeBlock(this.buffer);
+    this.buffer = "";
+    return message ? [message] : [];
+  }
+  findBoundary() {
+    const candidates = [
+      { index: this.buffer.indexOf("\r\n\r\n"), length: 4 },
+      { index: this.buffer.indexOf("\n\n"), length: 2 },
+      { index: this.buffer.indexOf("\r\r"), length: 2 }
+    ].filter((candidate) => candidate.index >= 0);
+    return candidates.sort((a, b) => a.index - b.index)[0] ?? null;
+  }
+  consumeBlock(raw) {
+    for (const line of raw.split(/\r\n|\r|\n/)) {
+      this.consumeLine(line);
+    }
+    if (this.dataLines.length === 0) {
+      this.event = void 0;
+      this.dataLines = [];
+      this.retry = void 0;
+      return null;
+    }
+    const message = {
+      id: this.id,
+      event: this.event,
+      data: this.dataLines.join("\n"),
+      retry: this.retry
+    };
+    this.event = void 0;
+    this.dataLines = [];
+    this.retry = void 0;
+    return message;
+  }
+  consumeLine(line) {
+    if (!line || line.startsWith(":")) {
+      return;
+    }
+    const separator = line.indexOf(":");
+    const field = separator >= 0 ? line.slice(0, separator) : line;
+    const value = separator >= 0 ? line.slice(separator + 1).replace(/^ /, "") : "";
+    if (field === "id") {
+      this.id = value;
+    } else if (field === "event") {
+      this.event = value;
+    } else if (field === "data") {
+      this.dataLines.push(value);
+    } else if (field === "retry") {
+      const retry = Number(value);
+      if (Number.isInteger(retry) && retry >= 0) {
+        this.retry = retry;
+      }
+    }
+  }
+};
+
+// src/api-client.ts
+var CommentaryApiClient = class {
+  baseUrl;
+  token;
+  fetchImpl;
+  constructor(options) {
+    this.baseUrl = options.baseUrl.replace(/\/$/, "");
+    this.token = options.token ?? null;
+    this.fetchImpl = options.fetchImpl ?? fetch;
+  }
+  async getOAuthMetadata() {
+    return this.rawJson("/.well-known/oauth-authorization-server", { auth: false });
+  }
+  async requestDeviceCode(input) {
+    const metadata = await this.getOAuthMetadata();
+    return this.rawJson(metadata.device_authorization_endpoint, {
+      auth: false,
+      method: "POST",
+      body: {
+        client_id: input.clientId,
+        client_name: input.clientName,
+        scope: input.scope,
+        resource: input.resource
+      }
+    });
+  }
+  async exchangeDeviceCode(input) {
+    const metadata = await this.getOAuthMetadata();
+    return this.rawJson(metadata.token_endpoint, {
+      auth: false,
+      method: "POST",
+      body: {
+        grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+        device_code: input.deviceCode,
+        resource: input.resource
+      }
+    });
+  }
+  async listDraftReviews() {
+    return this.request("/api/v1/draft-reviews");
+  }
+  async createDraftReview(input) {
+    return this.request("/api/v1/draft-reviews", {
+      method: "POST",
+      body: {
+        title: input.title,
+        description: input.description,
+        sourceType: "cli",
+        files: input.files.map((file) => ({
+          path: file.path,
+          content: file.content,
+          contentType: file.contentType
+        }))
+      }
+    });
+  }
+  async getDraftReview(sessionId) {
+    return this.request(
+      `/api/v1/draft-reviews/${encodeURIComponent(sessionId)}`
+    );
+  }
+  async createRevision(input) {
+    return this.request(
+      `/api/v1/draft-reviews/${encodeURIComponent(input.sessionId)}/revisions`,
+      {
+        method: "POST",
+        body: {
+          summary: input.summary,
+          files: input.files.map((file) => ({
+            fileId: file.fileId,
+            path: file.path,
+            content: file.content,
+            contentType: file.contentType
+          }))
+        }
+      }
+    );
+  }
+  async listRevisions(sessionId) {
+    return this.request(
+      `/api/v1/draft-reviews/${encodeURIComponent(sessionId)}/revisions`
+    );
+  }
+  async listComments(input) {
+    const params = new URLSearchParams();
+    if (input.status) {
+      params.set("status", input.status);
+    }
+    if (input.filePath) {
+      params.set("filePath", input.filePath);
+    }
+    if (input.fileId) {
+      params.set("fileId", input.fileId);
+    }
+    const suffix = params.size ? `?${params}` : "";
+    return this.request(
+      `/api/v1/draft-reviews/${encodeURIComponent(input.sessionId)}/comments${suffix}`
+    );
+  }
+  async replyToComment(input) {
+    return this.request(
+      `/api/v1/draft-reviews/${encodeURIComponent(input.sessionId)}/comments/${encodeURIComponent(input.threadId)}/replies`,
+      {
+        method: "POST",
+        body: { bodyMarkdown: input.bodyMarkdown }
+      }
+    );
+  }
+  async updateCommentStatus(input) {
+    return this.request(
+      `/api/v1/draft-reviews/${encodeURIComponent(input.sessionId)}/comments/${encodeURIComponent(input.threadId)}/status`,
+      {
+        method: "POST",
+        body: { status: input.status }
+      }
+    );
+  }
+  async getFileContent(input) {
+    return this.rawText(
+      `/api/v1/draft-reviews/${encodeURIComponent(input.sessionId)}/files/${encodeURIComponent(input.fileId)}/content`,
+      { auth: true }
+    );
+  }
+  async *streamDraftReviewEvents(input) {
+    const params = new URLSearchParams();
+    if (input.cursor) {
+      params.set("cursor", input.cursor);
+    }
+    if (input.once) {
+      params.set("once", "1");
+    }
+    const suffix = params.size ? `?${params}` : "";
+    const response = await this.doFetch(
+      `/api/v1/draft-reviews/${encodeURIComponent(input.sessionId)}/events${suffix}`,
+      { auth: true, accept: "text/event-stream", signal: input.signal }
+    );
+    if (!response.ok) {
+      await this.throwApiError(response);
+    }
+    if (!response.body) {
+      throw new CliError("Commentary event stream did not include a response body.", ExitCode.Api);
+    }
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    const parser = new SseParser();
+    let completed = false;
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        completed = done;
+        const messages = done ? parser.flush() : parser.feed(decoder.decode(value, { stream: true }));
+        for (const message of messages) {
+          if (message.event && message.event !== "draft-review") {
+            continue;
+          }
+          if (!message.data) {
+            continue;
+          }
+          yield JSON.parse(message.data);
+        }
+        if (done) {
+          break;
+        }
+      }
+    } catch (error) {
+      if (input.signal?.aborted) {
+        return;
+      }
+      throw new CliError(
+        error instanceof Error ? error.message : "Commentary event stream failed.",
+        ExitCode.Network
+      );
+    } finally {
+      if (!completed) {
+        await reader.cancel().catch(() => void 0);
+      }
+      reader.releaseLock();
+    }
+  }
+  async request(pathOrUrl, init) {
+    return this.rawJson(pathOrUrl, { ...init, auth: true });
+  }
+  async rawText(pathOrUrl, init) {
+    const response = await this.doFetch(pathOrUrl, init);
+    if (!response.ok) {
+      await this.throwApiError(response);
+    }
+    return response.text();
+  }
+  async rawJson(pathOrUrl, init) {
+    const response = await this.doFetch(pathOrUrl, init);
+    const contentType = response.headers.get("content-type") ?? "";
+    const payload = contentType.includes("application/json") ? await response.json() : null;
+    if (!response.ok) {
+      this.throwPayloadError(response.status, payload);
+    }
+    return payload;
+  }
+  async doFetch(pathOrUrl, init) {
+    const url = pathOrUrl.startsWith("http://") || pathOrUrl.startsWith("https://") ? pathOrUrl : `${this.baseUrl}${pathOrUrl}`;
+    const headers = {
+      accept: init.accept ?? "application/json"
+    };
+    let body;
+    if (init.body !== void 0) {
+      headers["content-type"] = "application/json";
+      body = JSON.stringify(init.body);
+    }
+    if (init.auth) {
+      if (!this.token) {
+        throw new CliError(
+          "Authentication is required. Run commentary login or set COMMENTARY_TOKEN.",
+          ExitCode.Auth
+        );
+      }
+      headers.authorization = `Bearer ${this.token}`;
+    }
+    try {
+      const requestInit = {
+        method: init.method ?? "GET",
+        headers
+      };
+      if (init.signal) {
+        requestInit.signal = init.signal;
+      }
+      if (body !== void 0) {
+        requestInit.body = body;
+      }
+      return await this.fetchImpl(url, requestInit);
+    } catch (error) {
+      throw new CliError(
+        error instanceof Error ? error.message : "Network request failed.",
+        ExitCode.Network
+      );
+    }
+  }
+  async throwApiError(response) {
+    const contentType = response.headers.get("content-type") ?? "";
+    if (contentType.includes("application/json")) {
+      this.throwPayloadError(response.status, await response.json());
+    }
+    throw new CliError(
+      `Commentary API returned ${response.status}.`,
+      response.status === 401 ? ExitCode.Auth : ExitCode.Api
+    );
+  }
+  throwPayloadError(status, payload) {
+    const body = payload && typeof payload === "object" ? payload : {};
+    const message = typeof body.error === "string" ? body.error : typeof body.error_description === "string" ? body.error_description : `Commentary API returned ${status}.`;
+    throw new CliError(message, status === 401 || status === 403 ? ExitCode.Auth : ExitCode.Api);
+  }
+};
+
+// src/constants.ts
+var DEFAULT_BASE_URL = "https://commentary.dev";
+var SESSION_FILE = ".commentary/session.json";
+var PACKAGE_NAME = "@commentary-dev/cli";
+var CLIENT_ID = "commentary-cli";
+var CLIENT_NAME = "Commentary CLI";
+var REQUIRED_SCOPES = [
+  "commentary.review.read",
+  "commentary.comments.read",
+  "commentary.comments.write",
+  "commentary.comments.status"
+];
+var SUPPORTED_EXTENSIONS = [".md", ".markdown", ".mdx", ".html", ".htm", ".txt"];
+var DEFAULT_IGNORES = [
+  "**/.git/**",
+  "**/node_modules/**",
+  "**/dist/**",
+  "**/build/**",
+  "**/.next/**",
+  "**/.nuxt/**",
+  "**/coverage/**",
+  "**/.commentary/**",
+  "**/.DS_Store"
+];
+var DRAFT_REVIEW_MAX_FILES = 20;
+var DRAFT_REVIEW_MAX_FILE_BYTES = 512 * 1024;
+var DRAFT_REVIEW_MAX_TOTAL_BYTES = 2 * 1024 * 1024;
+
+// src/config.ts
+import fs from "fs/promises";
+import os from "os";
+import path from "path";
+function configDir() {
+  if (process.env.COMMENTARY_CONFIG_DIR) {
+    return process.env.COMMENTARY_CONFIG_DIR;
+  }
+  if (process.platform === "win32" && process.env.APPDATA) {
+    return path.join(process.env.APPDATA, "commentary");
+  }
+  if (process.env.XDG_CONFIG_HOME) {
+    return path.join(process.env.XDG_CONFIG_HOME, "commentary");
+  }
+  return path.join(os.homedir(), ".config", "commentary");
+}
+function configPath() {
+  return path.join(configDir(), "config.json");
+}
+async function readConfig() {
+  try {
+    return JSON.parse(await fs.readFile(configPath(), "utf8"));
+  } catch {
+    return {};
+  }
+}
+async function writeConfig(config) {
+  await fs.mkdir(configDir(), { recursive: true, mode: 448 });
+  await fs.writeFile(configPath(), `${JSON.stringify(config, null, 2)}
+`, {
+    encoding: "utf8",
+    mode: 384
+  });
+}
+function normalizeBaseUrl(baseUrl) {
+  const value = baseUrl?.trim() || process.env.COMMENTARY_BASE_URL || DEFAULT_BASE_URL;
+  const url = new URL(value);
+  url.hash = "";
+  url.search = "";
+  return url.toString().replace(/\/$/, "");
+}
+async function getStoredToken(baseUrl) {
+  const config = await readConfig();
+  return config.tokens?.[normalizeBaseUrl(baseUrl)] ?? null;
+}
+async function setStoredToken(baseUrl, token) {
+  const config = await readConfig();
+  config.tokens ??= {};
+  config.tokens[normalizeBaseUrl(baseUrl)] = token;
+  await writeConfig(config);
+}
+async function removeStoredToken(baseUrl) {
+  const config = await readConfig();
+  if (config.tokens) {
+    delete config.tokens[normalizeBaseUrl(baseUrl)];
+  }
+  await writeConfig(config);
+}
+async function resolveToken(input) {
+  if (input.token?.trim()) {
+    return input.token.trim();
+  }
+  if (process.env.COMMENTARY_TOKEN?.trim()) {
+    return process.env.COMMENTARY_TOKEN.trim();
+  }
+  const stored = await getStoredToken(input.baseUrl);
+  return stored?.accessToken ?? null;
+}
+
+// src/content.ts
+import path2 from "path";
+var MARKDOWN_EXTENSIONS = /* @__PURE__ */ new Set([".md", ".markdown", ".mdx"]);
+var HTML_EXTENSIONS = /* @__PURE__ */ new Set([".html", ".htm"]);
+var PLAIN_EXTENSIONS = /* @__PURE__ */ new Set([".txt"]);
+var SUPPORTED_EXTENSIONS2 = /* @__PURE__ */ new Set([
+  ...MARKDOWN_EXTENSIONS,
+  ...HTML_EXTENSIONS,
+  ...PLAIN_EXTENSIONS
+]);
+function normalizeSlashes(value) {
+  return value.replaceAll("\\", "/");
+}
+function normalizeReviewPath(filePath) {
+  const normalized = normalizeSlashes(filePath).trim().replace(/^\/+/, "");
+  if (!normalized) {
+    throw new CliError("Draft review file path is required.", ExitCode.Usage);
+  }
+  if (/^[a-z]:\//iu.test(normalized) || filePath.trim().startsWith("/") || filePath.trim().startsWith("\\")) {
+    throw new CliError("Draft review file paths must be relative.", ExitCode.Usage);
+  }
+  if (normalized.split("/").some((segment) => !segment || segment === "." || segment === "..")) {
+    throw new CliError(
+      "Draft review file paths must not contain empty, current, or parent directory segments.",
+      ExitCode.Usage
+    );
+  }
+  return normalized;
+}
+function getPathExtension(filePath) {
+  return path2.posix.extname(normalizeSlashes(filePath)).toLowerCase();
+}
+function isSupportedPath(filePath) {
+  return SUPPORTED_EXTENSIONS2.has(getPathExtension(filePath));
+}
+function isLikelyHtml(content) {
+  const trimmed = content.trimStart().toLowerCase();
+  return trimmed.startsWith("<!doctype html") || trimmed.startsWith("<html") || /<(head|body|main|article|section|div|p|h[1-6]|table|ul|ol)\b[^>]*>[\s\S]*<\/\1>/iu.test(
+    content
+  );
+}
+function contentTypeFromPath(filePath) {
+  const extension = getPathExtension(filePath);
+  if (MARKDOWN_EXTENSIONS.has(extension)) {
+    return "markdown";
+  }
+  if (HTML_EXTENSIONS.has(extension)) {
+    return "html";
+  }
+  if (PLAIN_EXTENSIONS.has(extension)) {
+    return "plain_text";
+  }
+  return null;
+}
+function detectContentType(input) {
+  const requested = input.requested ?? "auto";
+  if (requested !== "auto") {
+    if (!["markdown", "html", "plain_text"].includes(requested)) {
+      throw new CliError("Choose a supported draft content type.", ExitCode.Usage);
+    }
+    return requested;
+  }
+  const fromPath = contentTypeFromPath(input.filePath);
+  if (fromPath) {
+    return fromPath;
+  }
+  return isLikelyHtml(input.content) ? "html" : "markdown";
+}
+
+// src/files.ts
+import fs2 from "fs/promises";
+import path3 from "path";
+import fg from "fast-glob";
+
+// src/hash.ts
+import { createHash } from "crypto";
+function contentHash(content) {
+  return createHash("sha256").update(content).digest("hex");
+}
+
+// src/files.ts
+function toPosixRelative(root, absolutePath) {
+  const relative = path3.relative(root, absolutePath);
+  if (!relative || relative.startsWith("..") || path3.isAbsolute(relative)) {
+    throw new CliError(`Path is outside the review root: ${absolutePath}`, ExitCode.Usage);
+  }
+  return normalizeReviewPath(relative);
+}
+async function readUtf8File(absolutePath) {
+  const bytes = await fs2.readFile(absolutePath);
+  const content = bytes.toString("utf8");
+  if (content.includes("\0")) {
+    throw new CliError(
+      `File must be UTF-8 text, not binary content: ${absolutePath}`,
+      ExitCode.Usage
+    );
+  }
+  return content;
+}
+async function collectPathEntries(inputPaths, options) {
+  const root = path3.resolve(options.root);
+  const entries = /* @__PURE__ */ new Set();
+  const includeExtensions = SUPPORTED_EXTENSIONS.map((extension) => extension.replace(".", ""));
+  for (const inputPath of inputPaths) {
+    const absolute = path3.resolve(root, inputPath);
+    let stat;
+    try {
+      stat = await fs2.stat(absolute);
+    } catch {
+      throw new CliError(`Path does not exist: ${inputPath}`, ExitCode.Usage);
+    }
+    if (stat.isDirectory()) {
+      const relativeDir = normalizeSlashes(path3.relative(root, absolute)) || ".";
+      const patterns = options.include?.length ? options.include.map((pattern) => normalizeSlashes(path3.posix.join(relativeDir, pattern))) : [`${relativeDir === "." ? "" : `${relativeDir}/`}**/*.{${includeExtensions.join(",")}}`];
+      const matches = await fg(patterns, {
+        cwd: root,
+        onlyFiles: true,
+        dot: false,
+        ignore: [...DEFAULT_IGNORES, ...options.exclude ?? []]
+      });
+      matches.forEach((match) => entries.add(path3.resolve(root, match)));
+      continue;
+    }
+    if (stat.isFile()) {
+      if (!isSupportedPath(absolute)) {
+        throw new CliError(`Unsupported file type: ${inputPath}`, ExitCode.Usage);
+      }
+      entries.add(absolute);
+    }
+  }
+  return [...entries].sort((left, right) => left.localeCompare(right));
+}
+async function collectFiles(inputPaths, options) {
+  if (inputPaths.length === 0) {
+    throw new CliError("At least one path is required.", ExitCode.Usage);
+  }
+  const root = path3.resolve(options.root);
+  const absolutePaths = await collectPathEntries(inputPaths, options);
+  if (absolutePaths.length === 0) {
+    throw new CliError("No supported files were found.", ExitCode.Usage);
+  }
+  if (absolutePaths.length > DRAFT_REVIEW_MAX_FILES) {
+    throw new CliError(
+      `Draft reviews support up to ${DRAFT_REVIEW_MAX_FILES} files per revision.`,
+      ExitCode.Usage
+    );
+  }
+  let totalBytes = 0;
+  const collected = [];
+  for (const absolutePath of absolutePaths) {
+    const content = await readUtf8File(absolutePath);
+    const sizeBytes = Buffer.byteLength(content);
+    if (sizeBytes > DRAFT_REVIEW_MAX_FILE_BYTES) {
+      throw new CliError(
+        `Draft review file exceeds ${DRAFT_REVIEW_MAX_FILE_BYTES} bytes: ${absolutePath}`,
+        ExitCode.Usage
+      );
+    }
+    totalBytes += sizeBytes;
+    if (totalBytes > DRAFT_REVIEW_MAX_TOTAL_BYTES) {
+      throw new CliError(
+        `Draft review revisions support up to ${DRAFT_REVIEW_MAX_TOTAL_BYTES} total bytes.`,
+        ExitCode.Usage
+      );
+    }
+    const reviewPath = toPosixRelative(root, absolutePath);
+    const contentType = detectContentType({
+      filePath: reviewPath,
+      content,
+      requested: options.requestedContentType
+    });
+    collected.push({
+      absolutePath,
+      path: reviewPath,
+      content,
+      contentType,
+      contentHash: contentHash(content),
+      sizeBytes
+    });
+  }
+  return collected;
+}
+async function readTrackedFiles(root, trackedFiles) {
+  const collected = [];
+  for (const tracked of trackedFiles) {
+    const absolutePath = path3.resolve(root, tracked.path);
+    const content = await readUtf8File(absolutePath);
+    const sizeBytes = Buffer.byteLength(content);
+    collected.push({
+      absolutePath,
+      path: tracked.path,
+      fileId: tracked.fileId,
+      content,
+      contentType: tracked.contentType,
+      contentHash: contentHash(content),
+      sizeBytes
+    });
+  }
+  return collected;
+}
+function toTrackedFiles(files, apiFiles) {
+  const apiByPath = new Map(apiFiles?.map((file) => [file.path, file]) ?? []);
+  return files.map((file) => {
+    const apiFile = apiByPath.get(file.path);
+    return {
+      path: file.path,
+      fileId: apiFile?.fileId ?? file.fileId,
+      contentType: file.contentType,
+      contentHash: apiFile?.contentHash ?? file.contentHash,
+      sizeBytes: apiFile?.sizeBytes ?? file.sizeBytes
+    };
+  });
+}
+
+// src/output.ts
+function writeJson(stdout, value) {
+  stdout.write(`${JSON.stringify(value, null, 2)}
+`);
+}
+function writeText(stdout, value) {
+  stdout.write(`${value.trimEnd()}
+`);
+}
+function formatReviewCreated(input) {
+  return [
+    "Created Commentary review",
+    "",
+    `Title: ${input.draftReview.title}`,
+    `Files: ${input.fileCount}`,
+    `Session: ${input.draftReview.id}`,
+    `URL: ${input.draftReview.reviewUrl}`,
+    "",
+    `Saved local session metadata to ${input.sessionFilePath}`
+  ].join("\n");
+}
+function formatRevision(input) {
+  return [
+    input.noOp ? "No changes to sync" : "Synced Commentary review",
+    "",
+    `Session: ${input.metadata.reviewSessionId}`,
+    `Revision: ${input.revision.revisionNumber}`,
+    `Files uploaded: ${input.uploaded}`,
+    `URL: ${input.metadata.reviewUrl}`
+  ].join("\n");
+}
+function commentBody(thread) {
+  const first = thread.comments[0];
+  return first?.bodyMarkdown ?? first?.body ?? "";
+}
+function commentAuthor(thread) {
+  const first = thread.comments[0];
+  return first?.authorLogin ?? first?.author ?? "Unknown";
+}
+function formatCommentsText(threads) {
+  if (threads.length === 0) {
+    return "No comments found.";
+  }
+  return threads.map(
+    (thread) => [
+      `[${thread.id}] ${thread.filePath}`,
+      `Status: ${thread.status}`,
+      thread.selectedText ? `Anchor: "${thread.selectedText}"` : null,
+      `${commentAuthor(thread)}: ${commentBody(thread)}`
+    ].filter(Boolean).join("\n")
+  ).join("\n\n");
+}
+function formatCommentsMarkdown(input) {
+  const lines = [
+    "# Commentary Review Comments",
+    "",
+    `Session: ${input.session.reviewSessionId}`,
+    `URL: ${input.session.reviewUrl}`,
+    ""
+  ];
+  if (input.threads.length === 0) {
+    lines.push("No comments found.");
+    return lines.join("\n");
+  }
+  for (const thread of input.threads) {
+    lines.push(`## Comment ${thread.id}`, "");
+    lines.push(`File: ${thread.filePath}`);
+    lines.push(`Status: ${thread.status}`);
+    if (thread.selectedText) {
+      lines.push(`Anchor: "${thread.selectedText}"`);
+    }
+    if (thread.sourceLineStart) {
+      lines.push(
+        `Lines: ${thread.sourceLineStart}${thread.sourceLineEnd && thread.sourceLineEnd !== thread.sourceLineStart ? `-${thread.sourceLineEnd}` : ""}`
+      );
+    }
+    lines.push("", "User comment:", `> ${commentBody(thread).replace(/\n/g, "\n> ")}`, "");
+    const replies = thread.comments.slice(1);
+    if (replies.length > 0) {
+      lines.push("Replies:");
+      replies.forEach((reply) => {
+        lines.push(
+          `- ${reply.authorLogin ?? reply.author ?? "Unknown"}: ${reply.bodyMarkdown ?? reply.body ?? ""}`
+        );
+      });
+      lines.push("");
+    }
+  }
+  return lines.join("\n").trimEnd();
+}
+function formatWaitCommentText(event) {
+  if (!event.thread) {
+    return `Received ${event.type} (${event.id}).`;
+  }
+  const thread = event.thread;
+  const body = commentBody(thread);
+  return [
+    `[${thread.id}] ${thread.filePath}`,
+    `Event: ${event.type}`,
+    `Status: ${thread.status}`,
+    thread.selectedText ? `Anchor: "${thread.selectedText}"` : null,
+    `${commentAuthor(thread)}: ${body}`
+  ].filter(Boolean).join("\n");
+}
+function formatWaitCommentMarkdown(input) {
+  const lines = [
+    "# Commentary Comment",
+    "",
+    `Session: ${input.session.reviewSessionId}`,
+    `URL: ${input.session.reviewUrl}`,
+    `Event: ${input.event.type}`,
+    `Cursor: ${input.event.id}`,
+    ""
+  ];
+  if (!input.event.thread) {
+    lines.push("No thread payload was available for this event.");
+    return lines.join("\n");
+  }
+  lines.push(formatCommentsMarkdown({ session: input.session, threads: [input.event.thread] }));
+  return lines.join("\n").trimEnd();
+}
+function publicSessionJson(metadata) {
+  return {
+    reviewSessionId: metadata.reviewSessionId,
+    reviewUrl: metadata.reviewUrl,
+    baseUrl: metadata.baseUrl,
+    rootPath: metadata.rootPath,
+    trackedFiles: metadata.trackedFiles,
+    createdAt: metadata.createdAt,
+    lastSyncedAt: metadata.lastSyncedAt,
+    lastKnownRevision: metadata.lastKnownRevision
+  };
+}
+
+// src/session.ts
+import fs3 from "fs/promises";
+import path4 from "path";
+async function pathExists(filePath) {
+  try {
+    await fs3.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function findSessionFile(startDir, explicitPath) {
+  if (explicitPath) {
+    return path4.resolve(startDir, explicitPath);
+  }
+  let current = path4.resolve(startDir);
+  while (true) {
+    const candidate = path4.join(current, SESSION_FILE);
+    if (await pathExists(candidate)) {
+      return candidate;
+    }
+    const parent = path4.dirname(current);
+    if (parent === current) {
+      return path4.resolve(startDir, SESSION_FILE);
+    }
+    current = parent;
+  }
+}
+async function loadSessionMetadata(startDir, explicitPath) {
+  const filePath = await findSessionFile(startDir, explicitPath);
+  let raw;
+  try {
+    raw = await fs3.readFile(filePath, "utf8");
+  } catch {
+    throw new CliError(
+      `No Commentary session metadata found at ${filePath}. Run commentary review first.`,
+      ExitCode.Usage
+    );
+  }
+  const metadata = JSON.parse(raw);
+  return {
+    filePath,
+    metadata
+  };
+}
+async function saveSessionMetadata(filePath, metadata) {
+  await fs3.mkdir(path4.dirname(filePath), { recursive: true });
+  await fs3.writeFile(filePath, `${JSON.stringify(metadata, null, 2)}
+`, {
+    encoding: "utf8",
+    mode: 420
+  });
+}
+function sessionRoot(sessionFilePath, metadata) {
+  return path4.resolve(path4.dirname(sessionFilePath), metadata.rootPath);
+}
+
+// src/commands.ts
+function nowIso() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+async function makeClient(runtime, options) {
+  const baseUrl = normalizeBaseUrl(options.baseUrl);
+  const token = await resolveToken({ baseUrl, token: options.token });
+  return new CommentaryApiClient({ baseUrl, token, fetchImpl: runtime.fetchImpl });
+}
+function apiFilesFromRevision(revision) {
+  return revision?.files.map((file) => ({
+    fileId: file.fileId,
+    path: file.path,
+    contentHash: file.contentHash,
+    sizeBytes: file.sizeBytes,
+    contentType: file.contentType
+  }));
+}
+function changedFiles(current, tracked) {
+  const trackedByPath = new Map(tracked.map((file) => [file.path, file]));
+  return current.filter((file) => {
+    const previous = trackedByPath.get(file.path);
+    return !previous || previous.contentHash !== file.contentHash || previous.contentType !== file.contentType;
+  });
+}
+async function loadSession(runtime, options) {
+  return loadSessionMetadata(runtime.cwd, options.sessionFile);
+}
+function shouldOpen(runtime, noOpen) {
+  return !noOpen && runtime.isTty !== false && !process.env.CI;
+}
+function placeholderSessionMetadata(input) {
+  return {
+    version: 1,
+    reviewSessionId: input.sessionId,
+    reviewUrl: `${input.baseUrl}/review/draft/${encodeURIComponent(input.sessionId)}`,
+    baseUrl: input.baseUrl,
+    rootPath: ".",
+    trackedFiles: [],
+    source: [],
+    createdAt: "",
+    lastSyncedAt: "",
+    lastKnownRevision: null
+  };
+}
+async function openOrPrint(runtime, url, noOpen) {
+  if (!shouldOpen(runtime, noOpen)) {
+    writeText(runtime.stdout, url);
+    return;
+  }
+  try {
+    await open(url);
+  } catch {
+    writeText(runtime.stdout, url);
+  }
+}
+function parseDurationMs(value, defaultMs) {
+  const raw = value?.trim();
+  if (!raw) {
+    return defaultMs;
+  }
+  if (raw === "0") {
+    return 0;
+  }
+  const match = raw.match(/^(\d+)(ms|s|m|h)?$/i);
+  if (!match) {
+    throw new CliError(
+      "Duration must be a number with optional ms, s, m, or h suffix.",
+      ExitCode.Usage
+    );
+  }
+  const amount = Number(match[1]);
+  const unit = match[2]?.toLowerCase() ?? "ms";
+  const multiplier = unit === "h" ? 36e5 : unit === "m" ? 6e4 : unit === "s" ? 1e3 : 1;
+  return amount * multiplier;
+}
+function delay(ms, signal) {
+  return new Promise((resolve) => {
+    if (signal.aborted) {
+      resolve();
+      return;
+    }
+    const timeout = setTimeout(resolve, ms);
+    signal.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(timeout);
+        resolve();
+      },
+      { once: true }
+    );
+  });
+}
+function payloadString(event, key) {
+  const value = event.payload[key];
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+function isWaitCommentMatch(input) {
+  const allowed = input.event.type === "comment.created" || input.includeReplies === true && input.event.type === "reply.created";
+  if (!allowed) {
+    return false;
+  }
+  if (!input.filePath) {
+    return true;
+  }
+  return (input.event.thread?.filePath ?? payloadString(input.event, "filePath")) === input.filePath;
+}
+async function loginCommand(runtime, options) {
+  const baseUrl = normalizeBaseUrl(options.baseUrl);
+  if (options.token?.trim()) {
+    await setStoredToken(baseUrl, { accessToken: options.token.trim() });
+    if (options.json) {
+      writeJson(runtime.stdout, { ok: true, baseUrl });
+    } else {
+      writeText(runtime.stdout, `Stored Commentary token for ${baseUrl}.`);
+    }
+    return;
+  }
+  const client = new CommentaryApiClient({ baseUrl, fetchImpl: runtime.fetchImpl });
+  const resource = `${baseUrl}/api`;
+  const device = await client.requestDeviceCode({
+    clientId: CLIENT_ID,
+    clientName: CLIENT_NAME,
+    scope: REQUIRED_SCOPES.join(" "),
+    resource
+  });
+  if (options.json) {
+    writeJson(runtime.stdout, {
+      verificationUri: device.verification_uri,
+      verificationUriComplete: device.verification_uri_complete,
+      userCode: device.user_code,
+      expiresIn: device.expires_in
+    });
+  } else {
+    writeText(
+      runtime.stdout,
+      [
+        "Connect Commentary",
+        "",
+        `Open: ${device.verification_uri_complete}`,
+        `Code: ${device.user_code}`,
+        "",
+        "Waiting for approval..."
+      ].join("\n")
+    );
+  }
+  if (shouldOpen(runtime, options.noOpen)) {
+    await open(device.verification_uri_complete).catch(() => void 0);
+  }
+  const startedAt = Date.now();
+  const intervalMs = Math.max(1, device.interval) * 1e3;
+  while (Date.now() - startedAt < device.expires_in * 1e3) {
+    await new Promise((resolve) => setTimeout(resolve, intervalMs));
+    try {
+      const token = await client.exchangeDeviceCode({ deviceCode: device.device_code, resource });
+      await setStoredToken(baseUrl, {
+        accessToken: token.access_token,
+        refreshToken: token.refresh_token,
+        expiresAt: new Date(Date.now() + token.expires_in * 1e3).toISOString()
+      });
+      if (!options.json) {
+        writeText(runtime.stdout, `Logged in to ${baseUrl}.`);
+      }
+      return;
+    } catch (error) {
+      if (error instanceof CliError && error.message === "authorization_pending") {
+        continue;
+      }
+      throw error;
+    }
+  }
+  throw new CliError("Device authorization expired.", ExitCode.Auth);
+}
+async function logoutCommand(runtime, options) {
+  const baseUrl = normalizeBaseUrl(options.baseUrl);
+  await removeStoredToken(baseUrl);
+  if (options.json) {
+    writeJson(runtime.stdout, { ok: true, baseUrl });
+  } else {
+    writeText(runtime.stdout, `Removed Commentary token for ${baseUrl}.`);
+  }
+}
+async function whoamiCommand(runtime, options) {
+  const client = await makeClient(runtime, options);
+  const result = await client.listDraftReviews();
+  const payload = {
+    ok: true,
+    baseUrl: client.baseUrl,
+    token: "valid",
+    accessibleDraftReviews: result.draftReviews.length
+  };
+  if (options.json) {
+    writeJson(runtime.stdout, payload);
+  } else {
+    writeText(
+      runtime.stdout,
+      `Authenticated for ${client.baseUrl}. Accessible draft reviews: ${result.draftReviews.length}`
+    );
+  }
+}
+async function reviewCommand(runtime, paths, options) {
+  const root = path5.resolve(runtime.cwd, options.root ?? ".");
+  const files = await collectFiles(paths, {
+    root,
+    include: options.include,
+    exclude: options.exclude,
+    requestedContentType: options.contentType ?? "auto"
+  });
+  const title = options.title?.trim() || (files.length === 1 ? path5.basename(files[0].path, path5.extname(files[0].path)) : path5.basename(root)) || "Commentary review";
+  const client = await makeClient(runtime, options);
+  const result = await client.createDraftReview({
+    title,
+    description: options.description ?? null,
+    files
+  });
+  const sessionFilePath = await findSessionFile(root, options.sessionFile ?? SESSION_FILE);
+  const now = nowIso();
+  const metadata = {
+    version: 1,
+    reviewSessionId: result.sessionId,
+    reviewUrl: result.reviewUrl,
+    baseUrl: client.baseUrl,
+    rootPath: path5.relative(path5.dirname(sessionFilePath), root) || ".",
+    trackedFiles: toTrackedFiles(files, apiFilesFromRevision(result.draftReview.latestRevision)),
+    source: ["review", ...paths],
+    createdAt: now,
+    lastSyncedAt: now,
+    lastKnownRevision: result.draftReview.latestRevision?.revisionNumber ?? null
+  };
+  await saveSessionMetadata(sessionFilePath, metadata);
+  if (options.json) {
+    writeJson(runtime.stdout, {
+      ok: true,
+      draftReview: result.draftReview,
+      sessionFilePath,
+      session: publicSessionJson(metadata)
+    });
+  } else {
+    writeText(
+      runtime.stdout,
+      formatReviewCreated({
+        draftReview: result.draftReview,
+        sessionFilePath,
+        fileCount: files.length
+      })
+    );
+  }
+  if (!options.noOpen) {
+    await openOrPrint(runtime, result.reviewUrl, options.noOpen);
+  }
+  if (options.watch) {
+    await watchCommand(runtime, { ...options, sessionFile: sessionFilePath });
+  }
+}
+async function syncCommand(runtime, options) {
+  const loaded = await loadSession(runtime, options);
+  const root = sessionRoot(loaded.filePath, loaded.metadata);
+  const current = await readTrackedFiles(root, loaded.metadata.trackedFiles);
+  const changed = changedFiles(current, loaded.metadata.trackedFiles);
+  if (options.dryRun) {
+    const payload = {
+      ok: true,
+      changedFiles: changed.map((file) => file.path),
+      fileCount: current.length
+    };
+    if (options.json) {
+      writeJson(runtime.stdout, payload);
+    } else {
+      writeText(
+        runtime.stdout,
+        payload.changedFiles.length ? payload.changedFiles.join("\n") : "No local changes."
+      );
+    }
+    return;
+  }
+  if (!options.all && changed.length === 0) {
+    const revision = {
+      id: "",
+      revisionNumber: loaded.metadata.lastKnownRevision ?? 0,
+      files: []
+    };
+    if (options.json) {
+      writeJson(runtime.stdout, {
+        ok: true,
+        noOp: true,
+        session: publicSessionJson(loaded.metadata)
+      });
+    } else {
+      writeText(
+        runtime.stdout,
+        formatRevision({ metadata: loaded.metadata, revision, uploaded: 0, noOp: true })
+      );
+    }
+    return;
+  }
+  const client = await makeClient(runtime, { ...options, baseUrl: loaded.metadata.baseUrl });
+  const result = await client.createRevision({
+    sessionId: loaded.metadata.reviewSessionId,
+    summary: options.message ?? null,
+    files: current
+  });
+  const nextMetadata = {
+    ...loaded.metadata,
+    trackedFiles: toTrackedFiles(current, apiFilesFromRevision(result.revision)),
+    lastSyncedAt: nowIso(),
+    lastKnownRevision: result.revision.revisionNumber
+  };
+  await saveSessionMetadata(loaded.filePath, nextMetadata);
+  if (options.json) {
+    writeJson(runtime.stdout, {
+      ok: true,
+      revision: result.revision,
+      noOp: Boolean(result.noOp),
+      session: publicSessionJson(nextMetadata)
+    });
+  } else {
+    writeText(
+      runtime.stdout,
+      formatRevision({
+        metadata: nextMetadata,
+        revision: result.revision,
+        uploaded: current.length,
+        noOp: result.noOp
+      })
+    );
+  }
+}
+async function watchCommand(runtime, options) {
+  const loaded = await loadSession(runtime, options);
+  const root = sessionRoot(loaded.filePath, loaded.metadata);
+  const debounceMs = Number(options.debounce ?? 1500);
+  let timer = null;
+  let syncing = false;
+  const watcher = chokidar.watch(
+    loaded.metadata.trackedFiles.map((file) => path5.resolve(root, file.path)),
+    {
+      ignoreInitial: true,
+      ignored: /(^|[/\\])(\.git|node_modules|dist|build|\.next|\.commentary)([/\\]|$)|(~$|\.tmp$|\.swp$)/
+    }
+  );
+  const runSync = () => {
+    if (timer) {
+      clearTimeout(timer);
+    }
+    timer = setTimeout(() => {
+      if (syncing) {
+        return;
+      }
+      syncing = true;
+      syncCommand(runtime, { ...options, message: options.message ?? "Watch sync" }).catch(
+        (error) => runtime.stderr.write(`${error instanceof Error ? error.message : String(error)}
+`)
+      ).finally(() => {
+        syncing = false;
+      });
+    }, debounceMs);
+  };
+  watcher.on("add", runSync).on("change", runSync).on("unlink", runSync);
+  writeText(
+    runtime.stdout,
+    `Watching ${loaded.metadata.trackedFiles.length} file(s). Press Ctrl+C to stop.`
+  );
+  await new Promise((resolve) => {
+    const close = () => {
+      void watcher.close().finally(resolve);
+    };
+    process.once("SIGINT", close);
+    process.once("SIGTERM", close);
+  });
+}
+async function commentsCommand(runtime, options) {
+  const loaded = options.session ? null : await loadSession(runtime, options);
+  const metadata = loaded?.metadata;
+  const sessionId = options.session ?? metadata?.reviewSessionId;
+  if (!sessionId) {
+    throw new CliError("A session id is required.", ExitCode.Usage);
+  }
+  const baseUrl = metadata?.baseUrl ?? normalizeBaseUrl(options.baseUrl);
+  const client = await makeClient(runtime, { ...options, baseUrl });
+  const status = options.all ? void 0 : options.resolved ? "resolved" : "open";
+  const result = await client.listComments({
+    sessionId,
+    status,
+    filePath: options.file ? normalizeReviewPath(options.file) : void 0
+  });
+  const format = options.json ? "json" : options.format ?? "text";
+  if (format === "json") {
+    writeJson(runtime.stdout, { ok: true, threads: result.threads });
+  } else if (format === "markdown") {
+    writeText(
+      runtime.stdout,
+      formatCommentsMarkdown({
+        session: metadata ?? {
+          version: 1,
+          reviewSessionId: sessionId,
+          reviewUrl: `${baseUrl}/review/draft/${encodeURIComponent(sessionId)}`,
+          baseUrl,
+          rootPath: ".",
+          trackedFiles: [],
+          source: [],
+          createdAt: "",
+          lastSyncedAt: "",
+          lastKnownRevision: null
+        },
+        threads: result.threads
+      })
+    );
+  } else {
+    writeText(runtime.stdout, formatCommentsText(result.threads));
+  }
+}
+async function waitCommentCommand(runtime, options) {
+  const loaded = options.session ? null : await loadSession(runtime, options);
+  const sessionId = options.session ?? loaded?.metadata.reviewSessionId;
+  if (!sessionId) {
+    throw new CliError("A session id is required.", ExitCode.Usage);
+  }
+  const baseUrl = loaded?.metadata.baseUrl ?? normalizeBaseUrl(options.baseUrl);
+  const session = loaded?.metadata ?? placeholderSessionMetadata({ sessionId, baseUrl });
+  const client = await makeClient(runtime, { ...options, baseUrl });
+  const filePath = options.file ? normalizeReviewPath(options.file) : void 0;
+  const timeoutMs = parseDurationMs(options.timeout, 30 * 60 * 1e3);
+  const abortController = new AbortController();
+  let timedOut = false;
+  let cursor = options.cursor ?? (options.from === "beginning" ? void 0 : "latest");
+  let reconnectDelayMs = 1e3;
+  const timeout = timeoutMs > 0 ? setTimeout(() => {
+    timedOut = true;
+    abortController.abort();
+  }, timeoutMs) : null;
+  try {
+    while (!abortController.signal.aborted) {
+      try {
+        for await (const event of client.streamDraftReviewEvents({
+          sessionId,
+          cursor,
+          signal: abortController.signal
+        })) {
+          cursor = event.id;
+          reconnectDelayMs = 1e3;
+          if (event.type === "draft.deleted") {
+            throw new CliError("Draft review was deleted before a comment arrived.", ExitCode.Api);
+          }
+          if (!isWaitCommentMatch({ event, includeReplies: options.includeReplies, filePath })) {
+            continue;
+          }
+          const format = options.json ? "json" : options.format ?? "markdown";
+          if (format === "json") {
+            writeJson(runtime.stdout, { ok: true, event });
+          } else if (format === "text") {
+            writeText(runtime.stdout, formatWaitCommentText(event));
+          } else {
+            writeText(runtime.stdout, formatWaitCommentMarkdown({ session, event }));
+          }
+          abortController.abort();
+          return;
+        }
+      } catch (error) {
+        if (abortController.signal.aborted) {
+          break;
+        }
+        if (error instanceof CliError && error.exitCode !== ExitCode.Network) {
+          throw error;
+        }
+        if (options.verbose) {
+          runtime.stderr.write(
+            `Event stream disconnected; reconnecting in ${reconnectDelayMs}ms.
+`
+          );
+        }
+      }
+      await delay(reconnectDelayMs, abortController.signal);
+      reconnectDelayMs = Math.min(reconnectDelayMs * 2, 1e4);
+    }
+  } finally {
+    if (timeout) {
+      clearTimeout(timeout);
+    }
+  }
+  throw new CliError(
+    timedOut ? "Timed out waiting for a draft review comment." : "Stopped waiting for a draft review comment.",
+    timedOut ? ExitCode.Timeout : ExitCode.General
+  );
+}
+async function replyCommand(runtime, threadId, message, options) {
+  const loaded = options.session ? null : await loadSession(runtime, options);
+  const sessionId = options.session ?? loaded?.metadata.reviewSessionId;
+  if (!sessionId) {
+    throw new CliError("A session id is required.", ExitCode.Usage);
+  }
+  const client = await makeClient(runtime, {
+    ...options,
+    baseUrl: loaded?.metadata.baseUrl ?? options.baseUrl
+  });
+  const result = await client.replyToComment({ sessionId, threadId, bodyMarkdown: message });
+  if (options.json) {
+    writeJson(runtime.stdout, { ok: true, thread: result.thread });
+  } else {
+    writeText(runtime.stdout, `Replied to ${threadId}.`);
+  }
+}
+async function resolveCommand(runtime, threadId, options) {
+  const loaded = options.session ? null : await loadSession(runtime, options);
+  const sessionId = options.session ?? loaded?.metadata.reviewSessionId;
+  if (!sessionId) {
+    throw new CliError("A session id is required.", ExitCode.Usage);
+  }
+  const client = await makeClient(runtime, {
+    ...options,
+    baseUrl: loaded?.metadata.baseUrl ?? options.baseUrl
+  });
+  if (options.message?.trim()) {
+    await client.replyToComment({ sessionId, threadId, bodyMarkdown: options.message.trim() });
+  }
+  const result = await client.updateCommentStatus({ sessionId, threadId, status: "resolved" });
+  if (options.json) {
+    writeJson(runtime.stdout, { ok: true, thread: result.thread });
+  } else {
+    writeText(runtime.stdout, `Resolved ${threadId}.`);
+  }
+}
+async function pullCommand(runtime, options) {
+  const loaded = await loadSession(runtime, options);
+  const root = sessionRoot(loaded.filePath, loaded.metadata);
+  const client = await makeClient(runtime, { ...options, baseUrl: loaded.metadata.baseUrl });
+  const session = await client.getDraftReview(loaded.metadata.reviewSessionId);
+  const writes = [];
+  for (const file of session.draftReview.files) {
+    const content = await client.getFileContent({
+      sessionId: loaded.metadata.reviewSessionId,
+      fileId: file.id
+    });
+    const targetRoot = options.output ? path5.resolve(runtime.cwd, options.output) : root;
+    const target = path5.resolve(targetRoot, file.path);
+    let current = null;
+    try {
+      current = await fs4.readFile(target, "utf8");
+    } catch {
+      current = null;
+    }
+    writes.push({ path: file.path, target, content, changed: current !== content });
+  }
+  if (options.dryRun) {
+    const changed = writes.filter((write) => write.changed).map((write) => write.path);
+    if (options.json) {
+      writeJson(runtime.stdout, { ok: true, changedFiles: changed });
+    } else {
+      writeText(runtime.stdout, changed.length ? changed.join("\n") : "No remote changes.");
+    }
+    return;
+  }
+  const changedWrites = writes.filter((write) => write.changed);
+  if (changedWrites.length > 0 && !options.yes && !options.output) {
+    throw new CliError(
+      "Pull would overwrite local files. Rerun with --yes, --backup, or --output <dir>.",
+      ExitCode.Safety
+    );
+  }
+  for (const write of writes) {
+    if (!write.changed) {
+      continue;
+    }
+    await fs4.mkdir(path5.dirname(write.target), { recursive: true });
+    if (options.backup) {
+      try {
+        await fs4.copyFile(write.target, `${write.target}.bak`);
+      } catch {
+      }
+    }
+    await fs4.writeFile(write.target, write.content, "utf8");
+  }
+  const nextTracked = loaded.metadata.trackedFiles.map((tracked) => {
+    const write = writes.find((candidate) => candidate.path === tracked.path);
+    return write ? {
+      ...tracked,
+      contentHash: contentHash(write.content),
+      sizeBytes: Buffer.byteLength(write.content)
+    } : tracked;
+  });
+  await saveSessionMetadata(loaded.filePath, { ...loaded.metadata, trackedFiles: nextTracked });
+  if (options.json) {
+    writeJson(runtime.stdout, { ok: true, filesWritten: changedWrites.length });
+  } else {
+    writeText(runtime.stdout, `Pulled ${changedWrites.length} file(s).`);
+  }
+}
+async function openCommand(runtime, options) {
+  if (options.session) {
+    const baseUrl = normalizeBaseUrl(options.baseUrl);
+    await openOrPrint(runtime, `${baseUrl}/review/draft/${encodeURIComponent(options.session)}`);
+    return;
+  }
+  const loaded = await loadSession(runtime, options);
+  await openOrPrint(runtime, loaded.metadata.reviewUrl);
+}
+async function statusCommand(runtime, options) {
+  const loaded = await loadSession(runtime, options);
+  const root = sessionRoot(loaded.filePath, loaded.metadata);
+  const current = await readTrackedFiles(root, loaded.metadata.trackedFiles);
+  const changed = changedFiles(current, loaded.metadata.trackedFiles).map((file) => file.path);
+  let openComments = null;
+  try {
+    const client = await makeClient(runtime, { ...options, baseUrl: loaded.metadata.baseUrl });
+    openComments = (await client.listComments({ sessionId: loaded.metadata.reviewSessionId, status: "open" })).threads.length;
+  } catch {
+    openComments = null;
+  }
+  const payload = { ...publicSessionJson(loaded.metadata), changedFiles: changed, openComments };
+  if (options.json) {
+    writeJson(runtime.stdout, payload);
+  } else {
+    writeText(
+      runtime.stdout,
+      [
+        `Session: ${loaded.metadata.reviewSessionId}`,
+        `URL: ${loaded.metadata.reviewUrl}`,
+        `Base URL: ${loaded.metadata.baseUrl}`,
+        `Tracked files: ${loaded.metadata.trackedFiles.length}`,
+        `Last revision: ${loaded.metadata.lastKnownRevision ?? "unknown"}`,
+        `Changed files: ${changed.length ? changed.join(", ") : "none"}`,
+        `Open comments: ${openComments ?? "unknown"}`
+      ].join("\n")
+    );
+  }
+}
+async function sessionsCommand(runtime, options) {
+  const client = await makeClient(runtime, options);
+  const result = await client.listDraftReviews();
+  if (options.json) {
+    writeJson(runtime.stdout, result);
+  } else {
+    writeText(
+      runtime.stdout,
+      result.draftReviews.map((draft) => `${draft.id}	${draft.title}	${draft.reviewUrl}`).join("\n") || "No draft reviews found."
+    );
+  }
+}
+async function revisionsCommand(runtime, options) {
+  const loaded = options.session ? null : await loadSession(runtime, options);
+  const sessionId = options.session ?? loaded?.metadata.reviewSessionId;
+  if (!sessionId) {
+    throw new CliError("A session id is required.", ExitCode.Usage);
+  }
+  const client = await makeClient(runtime, {
+    ...options,
+    baseUrl: loaded?.metadata.baseUrl ?? options.baseUrl
+  });
+  const result = await client.listRevisions(sessionId);
+  if (options.json) {
+    writeJson(runtime.stdout, result);
+  } else {
+    writeText(
+      runtime.stdout,
+      result.revisions.map(
+        (revision) => `#${revision.revisionNumber}	${revision.summary ?? ""}	${revision.createdAt ?? ""}`
+      ).join("\n") || "No revisions found."
+    );
+  }
+}
+
+// src/cli.ts
+function collectOption(value, previous = []) {
+  previous.push(value);
+  return previous;
+}
+function runtimeFromOptions(options) {
+  return {
+    cwd: options?.cwd ?? process.cwd(),
+    stdout: options?.stdout ?? process.stdout,
+    stderr: options?.stderr ?? process.stderr,
+    fetchImpl: options?.fetchImpl,
+    isTty: options?.isTty ?? process.stdout.isTTY
+  };
+}
+function globalOptions(command) {
+  return command.optsWithGlobals();
+}
+function wrap(runtime, action) {
+  return async function wrapped() {
+    await action(globalOptions(this));
+  };
+}
+function commandOptionsWithNoOpen(command) {
+  const options = command.opts();
+  return {
+    ...globalOptions(command),
+    ...options,
+    noOpen: options.open === false
+  };
+}
+function buildProgram(runtime) {
+  const program = new Command();
+  program.name("commentary").description("Create and manage Commentary draft review sessions from local files.").version("0.1.0").showHelpAfterError().exitOverride();
+  program.option("--base-url <url>", "Commentary base URL").option("--token <token>", "Commentary API token").option("--json", "Print JSON output").option("--verbose", "Print verbose diagnostics").option("--quiet", "Suppress non-essential output").option("--no-color", "Disable color output").option("--session-file <path>", "Path to project session metadata");
+  program.command("login").description("Authenticate with Commentary.").option("--token <token>", "Store an existing API token").option("--no-open", "Do not open the browser during device login").action(async function() {
+    await loginCommand(runtime, commandOptionsWithNoOpen(this));
+  });
+  program.command("logout").description("Remove the stored Commentary token for the selected base URL.").action(wrap(runtime, (options) => logoutCommand(runtime, options)));
+  program.command("whoami").description("Validate the configured Commentary token.").action(wrap(runtime, (options) => whoamiCommand(runtime, options)));
+  program.command("review").description("Create a draft review from files or folders.").argument("<paths...>").option("--title <title>", "Review title").option("--description <description>", "Review description").addOption(
+    new Option("--content-type <type>", "Content type").choices(["auto", "markdown", "html", "plain_text"]).default("auto")
+  ).option("--watch", "Watch files and sync after creating the review").option("--no-open", "Do not open the browser").option("--root <path>", "Root for relative review paths").option("--include <glob>", "Include glob for directory review", collectOption).option("--exclude <glob>", "Exclude glob for directory review", collectOption).action(async function(paths) {
+    await reviewCommand(runtime, paths, commandOptionsWithNoOpen(this));
+  });
+  const sync = program.command("sync").description("Upload current tracked files as a new revision.").option("--message <summary>", "Revision summary").option("--all", "Upload even when hashes have not changed").option("--dry-run", "Print pending changes without uploading").action(async function() {
+    await syncCommand(runtime, { ...globalOptions(this), ...this.opts() });
+  });
+  program.command("revision").description("Alias for sync.").option("--message <summary>", "Revision summary").option("--all", "Upload even when hashes have not changed").option("--dry-run", "Print pending changes without uploading").action(async function() {
+    await syncCommand(runtime, { ...globalOptions(this), ...this.opts() });
+  });
+  program.command("watch").description("Watch tracked files and sync revisions.").option("--debounce <ms>", "Debounce in milliseconds", "1500").option("--message <summary>", "Revision summary").action(async function() {
+    await watchCommand(runtime, { ...globalOptions(this), ...this.opts() });
+  });
+  program.command("comments").description("List draft review comments.").addOption(
+    new Option("--format <format>", "Output format").choices(["text", "markdown", "json"]).default("text")
+  ).option("--open", "Show open comments").option("--resolved", "Show resolved comments").option("--all", "Show all comments").option("--file <path>", "Filter by file path").option("--session <id>", "Explicit session id").action(async function() {
+    await commentsCommand(runtime, { ...globalOptions(this), ...this.opts() });
+  });
+  program.command("wait-comment").description("Wait for the next draft review comment event.").option("--session <id>", "Explicit session id").option("--file <path>", "Filter by file path").option("--include-replies", "Also return reply.created events").option("--cursor <id>", "Resume after a specific live event cursor").addOption(
+    new Option("--from <position>", "Where to start when no cursor is provided").choices(["beginning", "latest"]).default("latest")
+  ).option("--timeout <duration>", "Maximum wait time, e.g. 30m, 10s, or 0", "30m").addOption(
+    new Option("--format <format>", "Output format").choices(["text", "markdown", "json"]).default("markdown")
+  ).action(async function() {
+    await waitCommentCommand(runtime, { ...globalOptions(this), ...this.opts() });
+  });
+  program.command("reply").description("Reply to a comment thread.").argument("<comment-id>").argument("<message>").option("--session <id>", "Explicit session id").action(async function(threadId, message) {
+    await replyCommand(runtime, threadId, message, { ...globalOptions(this), ...this.opts() });
+  });
+  program.command("resolve").description("Resolve a comment thread.").argument("<comment-id>").option("--session <id>", "Explicit session id").option("--message <message>", "Reply before resolving").action(async function(threadId) {
+    await resolveCommand(runtime, threadId, { ...globalOptions(this), ...this.opts() });
+  });
+  program.command("pull").description("Download latest reviewed files safely.").option("--dry-run", "Show what would change").option("--yes", "Overwrite changed files").option("--backup", "Create .bak files before overwrite").option("--output <dir>", "Write files to a separate directory").action(async function() {
+    await pullCommand(runtime, { ...globalOptions(this), ...this.opts() });
+  });
+  program.command("open").description("Open the linked review in a browser, or print the URL in headless output.").option("--session <id>", "Explicit session id").action(async function() {
+    await openCommand(runtime, { ...globalOptions(this), ...this.opts() });
+  });
+  program.command("status").description("Show current linked review status.").action(wrap(runtime, (options) => statusCommand(runtime, options)));
+  program.command("sessions").description("List draft review sessions for the authenticated account.").action(wrap(runtime, (options) => sessionsCommand(runtime, options)));
+  program.command("revisions").description("List revisions for the linked or specified draft review.").option("--session <id>", "Explicit session id").action(async function() {
+    await revisionsCommand(runtime, { ...globalOptions(this), ...this.opts() });
+  });
+  sync.alias("upload");
+  program.addHelpText(
+    "after",
+    `
+Examples:
+  npx ${PACKAGE_NAME} review ./docs/spec.md
+  commentary comments --format markdown --open
+  commentary wait-comment --json
+`
+  );
+  return program;
+}
+async function runCli(argv = process.argv.slice(2), options) {
+  const runtime = runtimeFromOptions(options);
+  const program = buildProgram(runtime);
+  try {
+    await program.parseAsync(argv, { from: "user" });
+    return ExitCode.Ok;
+  } catch (error) {
+    const commanderError = error;
+    if (commanderError.code === "commander.helpDisplayed" || commanderError.code === "commander.version") {
+      return ExitCode.Ok;
+    }
+    if (commanderError.code?.startsWith("commander.")) {
+      runtime.stderr.write(`${commanderError.message ?? "Invalid command."}
+`);
+      return commanderError.exitCode ?? ExitCode.Usage;
+    }
+    if (error instanceof CliError) {
+      runtime.stderr.write(`${error.message}
+`);
+      return error.exitCode;
+    }
+    runtime.stderr.write(`${toErrorMessage(error)}
+`);
+    return ExitCode.General;
+  }
+}
+
+// src/index.ts
+var exitCode = await runCli();
+if (exitCode !== 0) {
+  process.exitCode = exitCode;
+}
+//# sourceMappingURL=index.js.map