vellum-cli 0.2.0 → 0.3.1

package/README.md

@@ -71,6 +71,31 @@ vellum push artifact.html --page-id pg_123 --json
 On success it prints the new version number, the human view URL, and the raw
 URL. With `--json` it prints the server's `CreateVersionResponse` verbatim.
 
+### `vellum markup <page-id>`
+
+Pin a comment to a passage of a published document. The `--quote` text must
+appear verbatim in the document; the viewer highlights it and links your note to
+the highlight. Without `--version`, the page's current version is used.
+
+```bash
+# anchor a note to a passage
+vellum markup pg_123 --quote "Q3 dashboard" --body "tighten this headline"
+
+# pipe the note in on stdin instead of --body
+echo "tighten this headline" | vellum markup pg_123 --quote "Q3 dashboard"
+```
+
+The CLI checks the quote is anchorable before posting; pass `--force` to post
+anyway, or `--json` for the raw response.
+
+### `vellum whoami`
+
+Show the identity the CLI is authenticated as for a server.
+
+### `vellum logout`
+
+Revoke this machine's stored token server-side and forget it locally.
+
 ## Development
 
 From the repo root, Bun runs the TypeScript source directly (no build):

package/dist/index.js

@@ -61,7 +61,7 @@ async function clearToken(baseUrl) {
   return existing;
 }
 
-// src/commands/login.ts
+// src/commands/archive.ts
 import { parseArgs } from "node:util";
 // ../core/src/client.ts
 class VellumApiError extends Error {
@@ -113,6 +113,51 @@ 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 listPages(opts = {}) {
+    const url = new URL(`${this.baseUrl}/v1/pages`);
+    if (opts.archived)
+      url.searchParams.set("status", "archived");
+    else if (opts.all)
+      url.searchParams.set("include", "archived");
+    const res = await this.fetchImpl(url, { headers: this.authHeaders() });
+    if (!res.ok)
+      await this.fail(res);
+    return await res.json();
+  }
+  async archivePage(pageId) {
+    return this.setArchived(pageId, true);
+  }
+  async unarchivePage(pageId) {
+    return this.setArchived(pageId, false);
+  }
+  async setArchived(pageId, archived) {
+    const action = archived ? "archive" : "unarchive";
+    const res = await this.fetchImpl(`${this.baseUrl}/v1/pages/${encodeURIComponent(pageId)}/${action}`, { method: "POST", 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 startCliAuth() {
     const res = await this.fetchImpl(`${this.baseUrl}/v1/cli/auth/start`, {
       method: "POST",
@@ -150,6 +195,164 @@ class VellumClient {
       await this.fail(res);
   }
 }
+// src/commands/archive.ts
+function help(verb) {
+  const what = verb === "archive" ? "hide a page from the gallery and make it read-only" : "restore an archived page to live";
+  return `vellum ${verb} — ${what}
+
+Usage:
+  vellum ${verb} <page-id> [options]
+
+${verb === "archive" ? `Archiving keeps the bytes, versions, comments, and URLs intact — new
+versions and comments are paused until you unarchive. Owner/admin only.` : `Unarchiving restores the page to the gallery and re-opens it for new
+versions and comments. Owner/admin only.`}
+
+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 run(verb, argv) {
+  const { values, positionals } = parseArgs({
+    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(help(verb));
+    return 0;
+  }
+  const pageId = positionals[0];
+  if (!pageId) {
+    console.error(`Error: missing <page-id>.
+`);
+    console.error(help(verb));
+    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 });
+  try {
+    const res = verb === "archive" ? await client2.archivePage(pageId) : await client2.unarchivePage(pageId);
+    if (values.json) {
+      console.log(JSON.stringify(res, null, 2));
+    } else {
+      console.log(`✓ ${verb}d ${res.id}`);
+    }
+    return 0;
+  } catch (err) {
+    if (err instanceof VellumApiError && err.status === 401) {
+      console.error(`Error: ${verb} requires the owner API key. Set VELLUM_API_KEY or pass --api-key.`);
+      return 1;
+    }
+    if (err instanceof VellumApiError && err.status === 404) {
+      console.error(`Error: no page found at ${pageId}.`);
+      return 1;
+    }
+    throw err;
+  }
+}
+function archiveCommand(argv) {
+  return run("archive", argv);
+}
+function unarchiveCommand(argv) {
+  return run("unarchive", argv);
+}
+
+// src/commands/list.ts
+import { parseArgs as parseArgs2 } from "node:util";
+var HELP = `vellum list — list your artifacts (owner/admin only)
+
+Usage:
+  vellum list [options]
+
+By default only live pages are shown. Use --archived for archived-only, or
+--all for both. Listing requires the owner API key (VELLUM_API_KEY / --api-key).
+
+Options:
+  --archived         Show only archived pages
+  --all              Show both live and archived pages
+  --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`;
+function cell(value, width) {
+  if (value.length > width)
+    return `${value.slice(0, width - 1)}…`;
+  return value.padEnd(width);
+}
+function renderTable(pages) {
+  const lines = [
+    `${cell("PAGE", 26)} ${cell("LATEST", 7)} ${cell("VERS", 5)} ${cell("COMM", 5)} TITLE`
+  ];
+  for (const p of pages) {
+    const id = p.archived_at ? `${p.id} *` : p.id;
+    const latest = p.latest_version != null ? `v${p.latest_version}` : "—";
+    lines.push(`${cell(id, 26)} ${cell(latest, 7)} ${cell(String(p.version_count), 5)} ` + `${cell(String(p.comment_count), 5)} ${p.title ?? ""}`.trimEnd());
+  }
+  return lines.join(`
+`);
+}
+async function listCommand(argv) {
+  const { values } = parseArgs2({
+    args: argv,
+    allowPositionals: false,
+    options: {
+      archived: { type: "boolean", default: false },
+      all: { 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(HELP);
+    return 0;
+  }
+  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 });
+  try {
+    const { pages } = await client2.listPages({
+      archived: values.archived,
+      all: values.all
+    });
+    if (values.json) {
+      console.log(JSON.stringify(pages, null, 2));
+      return 0;
+    }
+    if (pages.length === 0) {
+      const scope = values.archived ? "archived " : "";
+      console.log(`No ${scope}pages.`);
+      return 0;
+    }
+    console.log(renderTable(pages));
+    const archivedCount = pages.filter((p) => p.archived_at).length;
+    const suffix = archivedCount ? ` (${archivedCount} archived, marked *)` : "";
+    console.log(`
+${pages.length} page${pages.length === 1 ? "" : "s"}${suffix}`);
+    return 0;
+  } catch (err) {
+    if (err instanceof VellumApiError && err.status === 401) {
+      console.error("Error: list requires the owner API key. Set VELLUM_API_KEY or pass --api-key.");
+      return 1;
+    }
+    throw err;
+  }
+}
+
+// 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 +369,7 @@ function openBrowser(url) {
 }
 
 // src/commands/login.ts
-var HELP = `vellum login — authenticate this machine to a Vellum server
+var HELP2 = `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 +383,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 +392,7 @@ async function loginCommand(argv) {
     }
   });
   if (values.help) {
-    console.log(HELP);
+    console.log(HELP2);
     return 0;
   }
   const baseUrl = resolveBaseUrl({ url: values.url });
@@ -229,8 +432,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 HELP3 = `vellum logout — remove this machine's stored CLI token
 
 Usage:
   vellum logout [options]
@@ -239,7 +442,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 +450,7 @@ async function logoutCommand(argv) {
     }
   });
   if (values.help) {
-    console.log(HELP2);
+    console.log(HELP3);
     return 0;
   }
   const baseUrl = resolveBaseUrl({ url: values.url });
@@ -263,10 +466,130 @@ async function logoutCommand(argv) {
   return 0;
 }
 
+// src/commands/markup.ts
+import { parseArgs as parseArgs5 } from "node:util";
+var HELP4 = `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 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;
+}
+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(HELP4);
+    return 0;
+  }
+  const pageId = positionals[0];
+  if (!pageId) {
+    console.error(`Error: missing <page-id>.
+`);
+    console.error(HELP4);
+    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 = resolveVersion(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/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 parseArgs6 } from "node:util";
+var HELP5 = `vellum push — create a Vellum artifact from HTML
 
 Usage:
   vellum push <file.html> [options]
@@ -278,14 +601,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 } = parseArgs6({
     args: argv,
     allowPositionals: true,
     options: {
@@ -297,11 +620,11 @@ async function pushCommand(argv) {
     }
   });
   if (values.help) {
-    console.log(HELP3);
+    console.log(HELP5);
     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;
@@ -322,8 +645,8 @@ async function pushCommand(argv) {
 }
 
 // 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 parseArgs7 } from "node:util";
+var HELP6 = `vellum whoami — show the identity the CLI is authenticated as
 
 Usage:
   vellum whoami [options]
@@ -333,7 +656,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 } = parseArgs7({
     args: argv,
     options: {
       url: { type: "string" },
@@ -342,7 +665,7 @@ async function whoamiCommand(argv) {
     }
   });
   if (values.help) {
-    console.log(HELP4);
+    console.log(HELP6);
     return 0;
   }
   const baseUrl = resolveBaseUrl({ url: values.url });
@@ -358,7 +681,7 @@ async function whoamiCommand(argv) {
 }
 
 // src/index.ts
-var HELP5 = `vellum — CLI for the Vellum artifact store
+var HELP7 = `vellum — CLI for the Vellum artifact store
 
 Usage:
   vellum <command> [options]
@@ -368,25 +691,33 @@ 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)
+  list      List your artifacts (owner/admin only)
+  markup    Pin a comment to a passage of a document
+  archive   Archive a page (read-only, hidden from the gallery)
+  unarchive Restore an archived page to live
 
 Run 'vellum <command> --help' for command-specific options.`;
 var commands = {
   login: loginCommand,
   logout: logoutCommand,
   whoami: whoamiCommand,
-  push: pushCommand
+  push: pushCommand,
+  list: listCommand,
+  markup: markupCommand,
+  archive: archiveCommand,
+  unarchive: unarchiveCommand
 };
 async function main() {
   const [, , cmd, ...rest] = process.argv;
   if (!cmd || cmd === "-h" || cmd === "--help" || cmd === "help") {
-    console.log(HELP5);
+    console.log(HELP7);
     return cmd ? 0 : 1;
   }
   const handler = commands[cmd];
   if (!handler) {
     console.error(`Unknown command: ${cmd}
 `);
-    console.error(HELP5);
+    console.error(HELP7);
     return 1;
   }
   return handler(rest);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vellum-cli",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "The vellum CLI — publish agent-authored HTML artifacts to a Vellum server.",
   "type": "module",
   "license": "MIT",
@@ -28,9 +28,10 @@
     "start": "bun run src/index.ts",
     "build": "bun build src/index.ts --target=node --format=esm --outfile=dist/index.js",
     "prepack": "bun run build",
+    "release": "bun publish --access public",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "devDependencies": {
-    "@vellum/core": "workspace:*"
+    "@vellum/core": "0.1.0"
   }
 }