vellum-cli 0.2.0 → 0.3.0

package/dist/index.js

@@ -61,7 +61,7 @@ async function clearToken(baseUrl) {
   return existing;
 }
 
-// src/commands/login.ts
+// src/commands/comments.ts
 import { parseArgs } from "node:util";
 // ../core/src/client.ts
 class VellumApiError extends Error {
@@ -113,6 +113,42 @@ class VellumClient {
       await this.fail(res);
     return await res.json();
   }
+  async getPage(pageId) {
+    const res = await this.fetchImpl(`${this.baseUrl}/v1/pages/${encodeURIComponent(pageId)}`, { headers: this.authHeaders() });
+    if (!res.ok)
+      await this.fail(res);
+    return await res.json();
+  }
+  async createComment(pageId, opts) {
+    const res = await this.fetchImpl(`${this.baseUrl}/v1/pages/${encodeURIComponent(pageId)}/comments`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", ...this.authHeaders() },
+      body: JSON.stringify({
+        version_id: opts.versionId,
+        body: opts.body,
+        anchor: opts.anchor,
+        parent_id: opts.parentId
+      })
+    });
+    if (!res.ok)
+      await this.fail(res);
+    return await res.json();
+  }
+  async listComments(pageId, opts = {}) {
+    const url = new URL(`${this.baseUrl}/v1/pages/${encodeURIComponent(pageId)}/comments`);
+    if (opts.versionId)
+      url.searchParams.set("version_id", opts.versionId);
+    const res = await this.fetchImpl(url, { headers: this.authHeaders() });
+    if (!res.ok)
+      await this.fail(res);
+    return await res.json();
+  }
+  async resolveComment(commentId) {
+    const res = await this.fetchImpl(`${this.baseUrl}/v1/comments/${encodeURIComponent(commentId)}/resolve`, { method: "POST", headers: this.authHeaders() });
+    if (!res.ok)
+      await this.fail(res);
+    return await res.json();
+  }
   async startCliAuth() {
     const res = await this.fetchImpl(`${this.baseUrl}/v1/cli/auth/start`, {
       method: "POST",
@@ -150,6 +186,148 @@ class VellumClient {
       await this.fail(res);
   }
 }
+// src/commands/comments.ts
+var HELP = `vellum comments — list the comments on a document
+
+Usage:
+  vellum comments <page-id> [options]
+
+Reads are public, so no login is required. Comments print as threads; replies
+are indented under their parent.
+
+Options:
+  --open             Show only unresolved threads
+  --version <id>     Only comments anchored to this version id
+  --url <url>        Server base URL          (env: VELLUM_URL)
+  --json             Print the raw JSON response
+  -h, --help         Show this help`;
+var truncate = (s, n) => s.length > n ? `${s.slice(0, n - 1)}…` : s;
+var oneLine = (s) => s.replace(/\s+/g, " ").trim();
+function printComment(c, indent) {
+  const who = c.author_email ?? c.author_name ?? "(unknown)";
+  const state = c.resolved ? "resolved" : "open";
+  console.log(`${indent}${c.id}  [${state}]  ${who}`);
+  if (c.anchor?.exact) {
+    console.log(`${indent}  on “${truncate(oneLine(c.anchor.exact), 70)}”`);
+  }
+  console.log(`${indent}  ${truncate(oneLine(c.body), 100)}`);
+  for (const reply of c.replies ?? []) {
+    printComment(reply, `${indent}    `);
+  }
+}
+async function commentsCommand(argv) {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      open: { type: "boolean", default: false },
+      version: { type: "string" },
+      url: { type: "string" },
+      json: { type: "boolean", default: false },
+      help: { type: "boolean", short: "h", default: false }
+    }
+  });
+  if (values.help) {
+    console.log(HELP);
+    return 0;
+  }
+  const pageId = positionals[0];
+  if (!pageId) {
+    console.error(`Error: missing <page-id>.
+`);
+    console.error(HELP);
+    return 1;
+  }
+  const baseUrl = resolveBaseUrl({ url: values.url });
+  const client2 = new VellumClient({ baseUrl });
+  let comments = await client2.listComments(pageId, {
+    versionId: values.version
+  });
+  if (values.open)
+    comments = comments.filter((c) => !c.resolved);
+  if (values.json) {
+    console.log(JSON.stringify(comments, null, 2));
+    return 0;
+  }
+  if (comments.length === 0) {
+    console.log(values.open ? "No open comments." : "No comments.");
+    return 0;
+  }
+  for (const c of comments)
+    printComment(c, "");
+  return 0;
+}
+
+// src/commands/get.ts
+import { parseArgs as parseArgs2 } from "node:util";
+var HELP2 = `vellum get — print a document's raw HTML
+
+Usage:
+  vellum get <page-id> [options]
+
+Reads are public, so no login is required. Without --version, the page's
+current version is printed.
+
+Options:
+  --version <n>      Print a specific version number (default: current)
+  --url <url>        Server base URL          (env: VELLUM_URL)
+  -h, --help         Show this help`;
+function resolveVersion(page, requested) {
+  if (requested != null) {
+    return page.versions.find((v) => v.version_number === requested) ?? null;
+  }
+  const current = page.current_version_id ? page.versions.find((v) => v.id === page.current_version_id) : undefined;
+  return current ?? page.versions[page.versions.length - 1] ?? null;
+}
+async function getCommand(argv) {
+  const { values, positionals } = parseArgs2({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      version: { type: "string" },
+      url: { type: "string" },
+      help: { type: "boolean", short: "h", default: false }
+    }
+  });
+  if (values.help) {
+    console.log(HELP2);
+    return 0;
+  }
+  const pageId = positionals[0];
+  if (!pageId) {
+    console.error(`Error: missing <page-id>.
+`);
+    console.error(HELP2);
+    return 1;
+  }
+  let version;
+  if (values.version != null) {
+    version = Number.parseInt(values.version, 10);
+    if (!Number.isInteger(version) || version < 1) {
+      console.error("Error: --version must be a positive integer.");
+      return 1;
+    }
+  }
+  const baseUrl = resolveBaseUrl({ url: values.url });
+  const client2 = new VellumClient({ baseUrl });
+  const page = await client2.getPage(pageId);
+  const target = resolveVersion(page, version);
+  if (!target) {
+    console.error(version != null ? `Error: page has no version ${version}.` : "Error: page has no versions.");
+    return 1;
+  }
+  const res = await fetch(target.raw_url);
+  if (!res.ok) {
+    console.error(`Error: could not fetch raw HTML (${res.status}).`);
+    return 1;
+  }
+  process.stdout.write(await res.text());
+  return 0;
+}
+
+// src/commands/login.ts
+import { parseArgs as parseArgs3 } from "node:util";
+
 // src/util/open.ts
 import { spawn } from "node:child_process";
 function openBrowser(url) {
@@ -166,7 +344,7 @@ function openBrowser(url) {
 }
 
 // src/commands/login.ts
-var HELP = `vellum login — authenticate this machine to a Vellum server
+var HELP3 = `vellum login — authenticate this machine to a Vellum server
 
 Opens your browser to approve a CLI login, then stores a token under
 ~/.config/vellum/config.json so future commands authenticate as you.
@@ -180,7 +358,7 @@ Options:
   -h, --help         Show this help`;
 var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 async function loginCommand(argv) {
-  const { values } = parseArgs({
+  const { values } = parseArgs3({
     args: argv,
     options: {
       url: { type: "string" },
@@ -189,7 +367,7 @@ async function loginCommand(argv) {
     }
   });
   if (values.help) {
-    console.log(HELP);
+    console.log(HELP3);
     return 0;
   }
   const baseUrl = resolveBaseUrl({ url: values.url });
@@ -229,8 +407,8 @@ To authorize this CLI, visit:
 }
 
 // src/commands/logout.ts
-import { parseArgs as parseArgs2 } from "node:util";
-var HELP2 = `vellum logout — remove this machine's stored CLI token
+import { parseArgs as parseArgs4 } from "node:util";
+var HELP4 = `vellum logout — remove this machine's stored CLI token
 
 Usage:
   vellum logout [options]
@@ -239,7 +417,7 @@ Options:
   --url <url>        Server base URL          (env: VELLUM_URL)
   -h, --help         Show this help`;
 async function logoutCommand(argv) {
-  const { values } = parseArgs2({
+  const { values } = parseArgs4({
     args: argv,
     options: {
       url: { type: "string" },
@@ -247,7 +425,7 @@ async function logoutCommand(argv) {
     }
   });
   if (values.help) {
-    console.log(HELP2);
+    console.log(HELP4);
     return 0;
   }
   const baseUrl = resolveBaseUrl({ url: values.url });
@@ -263,10 +441,170 @@ async function logoutCommand(argv) {
   return 0;
 }
 
+// src/commands/markup.ts
+import { parseArgs as parseArgs5 } from "node:util";
+var HELP5 = `vellum markup — pin a comment to a passage of a document
+
+Usage:
+  vellum markup <page-id> --quote "<text>" --body "<note>" [options]
+  echo "<note>" | vellum markup <page-id> --quote "<text>"
+
+The --quote text must appear verbatim in the document; the viewer highlights it
+and links the highlight to your note. Without --version, the page's current
+version is used.
+
+Options:
+  --quote <text>     Passage to mark up (must match the document text)
+  --body <note>      Your note (or pipe it via stdin)
+  --version <n>      Pin to a specific version number (default: current)
+  --force            Post even if the quote isn't found in the version
+  --url <url>        Server base URL          (env: VELLUM_URL)
+  --api-key <key>    Shared API key           (env: VELLUM_API_KEY)
+  --json             Print the raw JSON response
+  -h, --help         Show this help`;
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin)
+    chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8");
+}
+function resolveVersion2(page, requested) {
+  if (requested != null) {
+    return page.versions.find((v) => v.version_number === requested) ?? null;
+  }
+  const current = page.current_version_id ? page.versions.find((v) => v.id === page.current_version_id) : undefined;
+  return current ?? page.versions[page.versions.length - 1] ?? null;
+}
+function extractText(html) {
+  return html.replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, "").replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, "").replace(/<[^>]+>/g, "").replace(/&nbsp;/g, " ").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#39;/g, "'");
+}
+var collapse = (s) => s.replace(/\s+/g, " ").trim();
+function quoteIsAnchorable(html, quote) {
+  const text = extractText(html);
+  return text.includes(quote) || collapse(text).includes(collapse(quote));
+}
+async function markupCommand(argv) {
+  const { values, positionals } = parseArgs5({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      quote: { type: "string" },
+      body: { type: "string" },
+      version: { type: "string" },
+      force: { type: "boolean", default: false },
+      url: { type: "string" },
+      "api-key": { type: "string" },
+      json: { type: "boolean", default: false },
+      help: { type: "boolean", short: "h", default: false }
+    }
+  });
+  if (values.help) {
+    console.log(HELP5);
+    return 0;
+  }
+  const pageId = positionals[0];
+  if (!pageId) {
+    console.error(`Error: missing <page-id>.
+`);
+    console.error(HELP5);
+    return 1;
+  }
+  const quote = (values.quote ?? "").trim();
+  if (!quote) {
+    console.error("Error: --quote is required (the passage to mark up).");
+    return 1;
+  }
+  const body = (values.body ?? await readStdin()).trim();
+  if (!body) {
+    console.error("Error: no note provided (pass --body or pipe it via stdin).");
+    return 1;
+  }
+  let version;
+  if (values.version != null) {
+    version = Number.parseInt(values.version, 10);
+    if (!Number.isInteger(version) || version < 1) {
+      console.error("Error: --version must be a positive integer.");
+      return 1;
+    }
+  }
+  const flags = { url: values.url, apiKey: values["api-key"] };
+  const baseUrl = resolveBaseUrl(flags);
+  const credential = await resolveCredential(flags, baseUrl);
+  const client2 = new VellumClient({ baseUrl, ...credential });
+  const page = await client2.getPage(pageId);
+  const target = resolveVersion2(page, version);
+  if (!target) {
+    console.error(version != null ? `Error: page has no version ${version}.` : "Error: page has no versions to mark up.");
+    return 1;
+  }
+  if (!values.force) {
+    const html = await fetch(target.raw_url).then((r) => r.ok ? r.text() : "");
+    if (!quoteIsAnchorable(html, quote)) {
+      console.error(`Error: --quote was not found in v${target.version_number}; the highlight
+` + "       would not appear. Check the wording, or pass --force to post anyway.");
+      return 1;
+    }
+  }
+  const anchor = { type: "text-quote", exact: quote };
+  const comment = await client2.createComment(pageId, {
+    versionId: target.id,
+    body,
+    anchor
+  });
+  if (values.json) {
+    console.log(JSON.stringify(comment, null, 2));
+  } else {
+    console.log("✓ markup added");
+    console.log(`  on:   “${quote.length > 80 ? `${quote.slice(0, 79)}…` : quote}”`);
+    console.log(`  view: ${page.view_url}`);
+  }
+  return 0;
+}
+
+// src/commands/open.ts
+import { parseArgs as parseArgs6 } from "node:util";
+var HELP6 = `vellum open — print (and open) a document's view URL
+
+Usage:
+  vellum open <page-id> [options]
+
+Options:
+  --no-browser       Just print the URL; don't open the browser
+  --url <url>        Server base URL          (env: VELLUM_URL)
+  -h, --help         Show this help`;
+async function openCommand(argv) {
+  const { values, positionals } = parseArgs6({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      "no-browser": { type: "boolean", default: false },
+      url: { type: "string" },
+      help: { type: "boolean", short: "h", default: false }
+    }
+  });
+  if (values.help) {
+    console.log(HELP6);
+    return 0;
+  }
+  const pageId = positionals[0];
+  if (!pageId) {
+    console.error(`Error: missing <page-id>.
+`);
+    console.error(HELP6);
+    return 1;
+  }
+  const baseUrl = resolveBaseUrl({ url: values.url });
+  const page = await new VellumClient({ baseUrl }).getPage(pageId);
+  console.log(page.view_url);
+  if (!values["no-browser"])
+    openBrowser(page.view_url);
+  return 0;
+}
+
 // src/commands/push.ts
 import { readFile as readFile2 } from "node:fs/promises";
-import { parseArgs as parseArgs3 } from "node:util";
-var HELP3 = `vellum push — create a Vellum artifact from HTML
+import { parseArgs as parseArgs7 } from "node:util";
+var HELP7 = `vellum push — create a Vellum artifact from HTML
 
 Usage:
   vellum push <file.html> [options]
@@ -278,14 +616,14 @@ Options:
   --api-key <key>    Shared API key           (env: VELLUM_API_KEY)
   --json             Print the raw JSON response
   -h, --help         Show this help`;
-async function readStdin() {
+async function readStdin2() {
   const chunks = [];
   for await (const chunk of process.stdin)
     chunks.push(chunk);
   return Buffer.concat(chunks).toString("utf8");
 }
 async function pushCommand(argv) {
-  const { values, positionals } = parseArgs3({
+  const { values, positionals } = parseArgs7({
     args: argv,
     allowPositionals: true,
     options: {
@@ -297,11 +635,11 @@ async function pushCommand(argv) {
     }
   });
   if (values.help) {
-    console.log(HELP3);
+    console.log(HELP7);
     return 0;
   }
   const file = positionals[0];
-  const html = file ? await readFile2(file, "utf8") : await readStdin();
+  const html = file ? await readFile2(file, "utf8") : await readStdin2();
   if (!html.trim()) {
     console.error("Error: no HTML provided (empty file or stdin).");
     return 1;
@@ -321,9 +659,143 @@ async function pushCommand(argv) {
   return 0;
 }
 
+// src/commands/reply.ts
+import { parseArgs as parseArgs8 } from "node:util";
+var HELP8 = `vellum reply — reply to a comment thread
+
+Usage:
+  vellum reply <page-id> <comment-id> --body "<note>"
+  echo "<note>" | vellum reply <page-id> <comment-id>
+
+The reply is threaded under <comment-id> and inherits the parent's version.
+Run \`vellum comments <page-id>\` to find the page and comment ids.
+
+Options:
+  --body <note>      Your reply (or pipe it via stdin)
+  --url <url>        Server base URL          (env: VELLUM_URL)
+  --api-key <key>    Shared API key           (env: VELLUM_API_KEY)
+  --json             Print the raw JSON response
+  -h, --help         Show this help`;
+async function readStdin3() {
+  const chunks = [];
+  for await (const chunk of process.stdin)
+    chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8");
+}
+function flatten(comments) {
+  const out = [];
+  const walk = (c) => {
+    out.push(c);
+    for (const reply of c.replies ?? [])
+      walk(reply);
+  };
+  for (const c of comments)
+    walk(c);
+  return out;
+}
+async function replyCommand(argv) {
+  const { values, positionals } = parseArgs8({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      body: { type: "string" },
+      url: { type: "string" },
+      "api-key": { type: "string" },
+      json: { type: "boolean", default: false },
+      help: { type: "boolean", short: "h", default: false }
+    }
+  });
+  if (values.help) {
+    console.log(HELP8);
+    return 0;
+  }
+  const [pageId, commentId] = positionals;
+  if (!pageId || !commentId) {
+    console.error("Error: usage is `vellum reply <page-id> <comment-id>`.\n");
+    console.error(HELP8);
+    return 1;
+  }
+  const body = (values.body ?? await readStdin3()).trim();
+  if (!body) {
+    console.error("Error: no note provided (pass --body or pipe it via stdin).");
+    return 1;
+  }
+  const flags = { url: values.url, apiKey: values["api-key"] };
+  const baseUrl = resolveBaseUrl(flags);
+  const credential = await resolveCredential(flags, baseUrl);
+  const client2 = new VellumClient({ baseUrl, ...credential });
+  const parent = flatten(await client2.listComments(pageId)).find((c) => c.id === commentId);
+  if (!parent) {
+    console.error(`Error: no comment ${commentId} on page ${pageId}.`);
+    return 1;
+  }
+  if (!parent.version_id) {
+    console.error("Error: parent comment has no version to reply on.");
+    return 1;
+  }
+  const reply = await client2.createComment(pageId, {
+    versionId: parent.version_id,
+    body,
+    parentId: commentId
+  });
+  if (values.json) {
+    console.log(JSON.stringify(reply, null, 2));
+  } else {
+    console.log(`✓ replied to ${commentId}`);
+  }
+  return 0;
+}
+
+// src/commands/resolve.ts
+import { parseArgs as parseArgs9 } from "node:util";
+var HELP9 = `vellum resolve — mark a comment as resolved
+
+Usage:
+  vellum resolve <comment-id> [options]
+
+Options:
+  --url <url>        Server base URL          (env: VELLUM_URL)
+  --api-key <key>    Shared API key           (env: VELLUM_API_KEY)
+  --json             Print the raw JSON response
+  -h, --help         Show this help`;
+async function resolveCommand(argv) {
+  const { values, positionals } = parseArgs9({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      url: { type: "string" },
+      "api-key": { type: "string" },
+      json: { type: "boolean", default: false },
+      help: { type: "boolean", short: "h", default: false }
+    }
+  });
+  if (values.help) {
+    console.log(HELP9);
+    return 0;
+  }
+  const commentId = positionals[0];
+  if (!commentId) {
+    console.error(`Error: missing <comment-id>.
+`);
+    console.error(HELP9);
+    return 1;
+  }
+  const flags = { url: values.url, apiKey: values["api-key"] };
+  const baseUrl = resolveBaseUrl(flags);
+  const credential = await resolveCredential(flags, baseUrl);
+  const client2 = new VellumClient({ baseUrl, ...credential });
+  const comment = await client2.resolveComment(commentId);
+  if (values.json) {
+    console.log(JSON.stringify(comment, null, 2));
+  } else {
+    console.log(`✓ resolved ${comment.id}`);
+  }
+  return 0;
+}
+
 // src/commands/whoami.ts
-import { parseArgs as parseArgs4 } from "node:util";
-var HELP4 = `vellum whoami — show the identity the CLI is authenticated as
+import { parseArgs as parseArgs10 } from "node:util";
+var HELP10 = `vellum whoami — show the identity the CLI is authenticated as
 
 Usage:
   vellum whoami [options]
@@ -333,7 +805,7 @@ Options:
   --api-key <key>    Shared API key           (env: VELLUM_API_KEY)
   -h, --help         Show this help`;
 async function whoamiCommand(argv) {
-  const { values } = parseArgs4({
+  const { values } = parseArgs10({
     args: argv,
     options: {
       url: { type: "string" },
@@ -342,7 +814,7 @@ async function whoamiCommand(argv) {
     }
   });
   if (values.help) {
-    console.log(HELP4);
+    console.log(HELP10);
     return 0;
   }
   const baseUrl = resolveBaseUrl({ url: values.url });
@@ -358,7 +830,7 @@ async function whoamiCommand(argv) {
 }
 
 // src/index.ts
-var HELP5 = `vellum — CLI for the Vellum artifact store
+var HELP11 = `vellum — CLI for the Vellum artifact store
 
 Usage:
   vellum <command> [options]
@@ -368,25 +840,37 @@ Commands:
   logout    Remove this machine's stored CLI token
   whoami    Show the identity the CLI is authenticated as
   push      Create an artifact (page) from HTML (file or stdin)
+  get       Print a document's raw HTML
+  open      Print (and open) a document's view URL
+  markup    Pin a comment to a passage of a document
+  comments  List the comments on a document
+  reply     Reply to a comment thread
+  resolve   Mark a comment as resolved
 
 Run 'vellum <command> --help' for command-specific options.`;
 var commands = {
   login: loginCommand,
   logout: logoutCommand,
   whoami: whoamiCommand,
-  push: pushCommand
+  push: pushCommand,
+  get: getCommand,
+  open: openCommand,
+  markup: markupCommand,
+  comments: commentsCommand,
+  reply: replyCommand,
+  resolve: resolveCommand
 };
 async function main() {
   const [, , cmd, ...rest] = process.argv;
   if (!cmd || cmd === "-h" || cmd === "--help" || cmd === "help") {
-    console.log(HELP5);
+    console.log(HELP11);
     return cmd ? 0 : 1;
   }
   const handler = commands[cmd];
   if (!handler) {
     console.error(`Unknown command: ${cmd}
 `);
-    console.error(HELP5);
+    console.error(HELP11);
     return 1;
   }
   return handler(rest);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vellum-cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "The vellum CLI — publish agent-authored HTML artifacts to a Vellum server.",
   "type": "module",
   "license": "MIT",