causly-server 0.0.0-stage → 1.5.0

package/tools/toolsetOps.js

@@ -0,0 +1,123 @@
+// `causly-server toolsets`: choose which packs load at startup in the user's editors.
+// Clients like Claude Desktop do not refresh their tool list mid-chat, so what is
+// switched on here is what the agent can use from the first message.
+import fs from "fs";
+import { PACKS } from "../packs/registry.js";
+import {
+  DEFAULT_TOOLSETS,
+  SERVER_NAME,
+  clientConfigPath,
+  pickClients,
+  readJson,
+  backup,
+} from "./cliOps.js";
+
+const CLIENT_LABEL = { claude: "Claude Desktop", cursor: "Cursor", windsurf: "Windsurf" };
+const ACTIONS = ["list", "add", "remove", "reset"];
+
+const parse = (v) =>
+  String(v || "")
+    .split(",")
+    .map((s) => s.trim().toLowerCase())
+    .filter(Boolean);
+
+const coreNames = () => Object.keys(PACKS).filter((n) => PACKS[n].core);
+const optionalNames = () => Object.keys(PACKS).filter((n) => !PACKS[n].core);
+
+function toolCounts() {
+  try {
+    const m = JSON.parse(fs.readFileSync(new URL("../packs/manifest.json", import.meta.url), "utf8"));
+    return Object.fromEntries(Object.entries(m.packs || {}).map(([n, p]) => [n, p.tools?.length ?? null]));
+  } catch {
+    return {};
+  }
+}
+
+/** "all" is expanded so a single pack can be removed from it. */
+const expand = (list) => (list.includes("all") ? [...new Set([...list.filter((n) => n !== "all"), ...optionalNames()])] : list);
+
+export function toolsetRows(list) {
+  const on = new Set(expand(list));
+  const counts = toolCounts();
+  return Object.entries(PACKS).map(([name, pack]) => ({
+    name,
+    description: pack.description,
+    core: Boolean(pack.core),
+    on: Boolean(pack.core) || on.has(name),
+    tools: counts[name] ?? null,
+  }));
+}
+
+export function formatToolsets(rows) {
+  const width = Math.max(...rows.map((r) => r.name.length));
+  const line = (r) =>
+    `  ${r.on ? "on " : "off"}  ${r.name.padEnd(width)}  ${String(r.tools ?? "?").padStart(2)} tools  ${r.description}`;
+  const on = rows.filter((r) => r.on);
+  const off = rows.filter((r) => !r.on);
+  const out = [`Loaded at startup (${on.length}):`, ...on.map(line)];
+  if (off.length) out.push("", `Not loaded (${off.length}); the agent can still load these in clients that refresh their tool list:`, ...off.map(line));
+  out.push("", "Change with: causly-server toolsets add <name,...> | remove <name,...> | reset");
+  return out;
+}
+
+function writeToolsets(file, list) {
+  const { config } = readJson(file);
+  const entry = config.mcpServers[SERVER_NAME];
+  const env = { ...(entry.env || {}) };
+  if (list.length) env.CAUSLY_TOOLSETS = list.join(",");
+  else delete env.CAUSLY_TOOLSETS;
+  if (Object.keys(env).length) entry.env = env;
+  else delete entry.env;
+  backup(file);
+  fs.writeFileSync(file, `${JSON.stringify(config, null, 2)}\n`);
+}
+
+export function runToolsets({ action = "list", names = [], client, platform, home, env } = {}) {
+  if (!ACTIONS.includes(action)) throw new Error(`Unknown toolsets command "${action}". Use: ${ACTIONS.join(", ")}.`);
+  const where = { platform, home, env };
+  const targets = pickClients(client || "all", where)
+    .map((c) => ({ client: c, file: clientConfigPath(c, where) }))
+    .filter((t) => {
+      const { config } = readJson(t.file);
+      return config.mcpServers && SERVER_NAME in config.mcpServers;
+    });
+  if (!targets.length) throw new Error('causly-server is not set up in any editor yet. Run "causly-server init" first.');
+
+  const requested = [...new Set(names.map((n) => String(n).trim().toLowerCase()).filter(Boolean))];
+  const current = (t) => parse(readJson(t.file).config.mcpServers[SERVER_NAME].env?.CAUSLY_TOOLSETS);
+  const notes = [];
+  let changed = false;
+
+  if (action === "add" || action === "remove") {
+    if (!requested.length) throw new Error(`Name at least one toolset, for example: causly-server toolsets ${action} github`);
+    const unknown = requested.filter((n) => !PACKS[n] && n !== "all");
+    if (unknown.length) throw new Error(`Unknown toolset: ${unknown.join(", ")}. Available: ${optionalNames().join(", ")}.`);
+  }
+
+  for (const t of targets) {
+    const before = current(t);
+    let after = before;
+    if (action === "reset") after = parse(DEFAULT_TOOLSETS);
+    else if (action === "add") after = [...new Set([...expand(before), ...requested.filter((n) => !PACKS[n]?.core)])];
+    else if (action === "remove") after = expand(before).filter((n) => !requested.includes(n));
+    if (action === "add" && requested.includes("all")) after = ["all"];
+    if (action !== "list" && after.join(",") !== before.join(",")) {
+      writeToolsets(t.file, after);
+      changed = true;
+    }
+    t.after = after;
+  }
+  for (const n of requested) if (PACKS[n]?.core) notes.push(`${n} is a core toolset and is always on.`);
+
+  const rows = toolsetRows(targets[0].after ?? current(targets[0]));
+  const lines = formatToolsets(rows);
+  if (action !== "list") {
+    const labels = targets.map((t) => CLIENT_LABEL[t.client]).join(" and ");
+    lines.unshift(
+      changed ? `Saved for ${labels}. These packs are in the tool list from the next restart; until then the agent can already use them through use_tool.` : "Nothing changed.",
+      ...notes,
+      ""
+    );
+  }
+  return { changed, clients: targets.map((t) => t.client), rows, lines };
+}

package/tools/transcribeOps.js

@@ -0,0 +1,221 @@
+// Speech to text for meeting recordings, plus reading transcript files.
+//
+// Engine: Groq's hosted Whisper (OpenAI-compatible API). The audio file is sent to Groq,
+// so callers must get the user's consent first (meeting_transcribe requires confirm: true).
+// Whisper does not tell speakers apart, so the transcript has timestamps but no names.
+//
+// Credentials: GROQ_API_KEY (free key at console.groq.com/keys).
+// Optional: GROQ_WHISPER_MODEL (default whisper-large-v3-turbo; whisper-large-v3 is a bit
+// more accurate), GROQ_MAX_FILE_MB (25 on the free tier, 100 on the dev tier).
+//
+// Files over the limit, or in a format Groq does not take, are converted with ffmpeg when it
+// is installed (mono 16 kHz Opus at 24 kbps: about 11 MB per hour). Without ffmpeg the error
+// says what to do.
+import fs from "fs";
+import os from "os";
+import path from "path";
+import crypto from "crypto";
+import { execFile } from "child_process";
+
+const GROQ_URL = "https://api.groq.com/openai/v1/audio/transcriptions";
+const DEFAULT_MODEL = "whisper-large-v3-turbo";
+export const AUDIO_EXTS = ["flac", "mp3", "mp4", "mpeg", "mpga", "m4a", "ogg", "wav", "webm"];
+export const TRANSCRIPT_EXTS = [".txt", ".md", ".vtt", ".srt"];
+const MAX_TRANSCRIPT_FILE = 5 * 1024 * 1024;
+
+// ---------------------------------------------------------------- formatting
+
+export function formatClock(seconds) {
+  const s = Math.max(0, Math.floor(Number(seconds) || 0));
+  const h = Math.floor(s / 3600);
+  const m = Math.floor((s % 3600) / 60);
+  const pad = (n) => String(n).padStart(2, "0");
+  return h ? `${h}:${pad(m)}:${pad(s % 60)}` : `${pad(m)}:${pad(s % 60)}`;
+}
+
+/** Whisper segments are sentence-sized; group them into lines of about `block` seconds: "[01:30] text". */
+export function formatSegments(segments, fallbackText = "", block = 30) {
+  if (!Array.isArray(segments) || !segments.length) return String(fallbackText).trim();
+  const lines = [];
+  let start = null;
+  let parts = [];
+  const flush = () => {
+    if (parts.length) lines.push(`[${formatClock(start)}] ${parts.join(" ").replace(/\s+/g, " ").trim()}`);
+    parts = [];
+    start = null;
+  };
+  for (const seg of segments) {
+    const text = String(seg.text ?? "").trim();
+    if (!text) continue;
+    if (start !== null && seg.start - start >= block) flush();
+    if (start === null) start = seg.start ?? 0;
+    parts.push(text);
+  }
+  flush();
+  return lines.join("\n");
+}
+
+const cueTime = (s) => {
+  const m = /(?:(\d+):)?(\d{1,2}):(\d{2})[.,]\d+/.exec(s);
+  return m ? Number(m[1] || 0) * 3600 + Number(m[2]) * 60 + Number(m[3]) : 0;
+};
+
+/** Zoom, Meet, Teams and most tools export .vtt or .srt; turn the cues into "[mm:ss] Speaker: text" lines. */
+export function parseSubtitles(raw) {
+  const blocks = String(raw).replace(/\r/g, "").replace(/^/, "").split(/\n{2,}/);
+  const lines = [];
+  for (const block of blocks) {
+    const rows = block.split("\n").map((r) => r.trim()).filter(Boolean);
+    const at = rows.findIndex((r) => r.includes("-->"));
+    if (at === -1) continue; // WEBVTT header, NOTE blocks, style blocks
+    const text = rows
+      .slice(at + 1)
+      .join(" ")
+      .replace(/<v\s+([^>]+)>/gi, "$1: ")
+      .replace(/<[^>]+>/g, "")
+      .replace(/\s+/g, " ")
+      .trim();
+    if (text) lines.push(`[${formatClock(cueTime(rows[at]))}] ${text}`);
+  }
+  return lines.join("\n");
+}
+
+/** Read a .txt, .md, .vtt or .srt transcript. */
+export function parseTranscriptFile(file) {
+  const ext = path.extname(String(file ?? "")).toLowerCase();
+  if (!TRANSCRIPT_EXTS.includes(ext)) throw new Error(`Transcript files must be ${TRANSCRIPT_EXTS.join(", ")} (got "${ext || "no extension"}"). For audio use meeting_transcribe.`);
+  let stat;
+  try {
+    stat = fs.statSync(file);
+  } catch {
+    throw new Error(`Cannot find the transcript file: ${path.basename(file)}.`);
+  }
+  if (!stat.isFile()) throw new Error("transcript_file must be a file.");
+  if (stat.size > MAX_TRANSCRIPT_FILE) throw new Error("The transcript file is over 5 MB.");
+  const raw = fs.readFileSync(file, "utf8");
+  const text = ext === ".vtt" || ext === ".srt" ? parseSubtitles(raw) : raw.replace(/\r/g, "").trim();
+  if (!text) throw new Error("The transcript file has no text in it.");
+  return text;
+}
+
+// ---------------------------------------------------------------- ffmpeg
+
+function run(exec, cmd, args, timeout) {
+  return new Promise((resolve, reject) => {
+    exec(cmd, args, { timeout, windowsHide: true, maxBuffer: 1024 * 1024 }, (err, stdout, stderr) => {
+      if (err) reject(Object.assign(err, { stderr }));
+      else resolve({ stdout, stderr });
+    });
+  });
+}
+
+async function hasFfmpeg(exec) {
+  try {
+    await run(exec, "ffmpeg", ["-version"], 8000);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function compress(exec, input) {
+  const out = path.join(os.tmpdir(), `causly-${crypto.randomUUID()}.ogg`);
+  try {
+    await run(exec, "ffmpeg", ["-y", "-i", input, "-vn", "-ac", "1", "-ar", "16000", "-c:a", "libopus", "-b:a", "24k", out], 15 * 60_000);
+  } catch (err) {
+    fs.rmSync(out, { force: true });
+    throw new Error(`ffmpeg could not convert this file: ${String(err.stderr || err.message).split("\n").filter(Boolean).slice(-2).join(" ").slice(0, 300)}`);
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------- Groq
+
+function groqKey() {
+  const key = process.env.GROQ_API_KEY;
+  if (!key) throw new Error("Transcription is not set up. Missing: GROQ_API_KEY (free key at https://console.groq.com/keys, add it to .env).");
+  return key;
+}
+
+const mb = (bytes) => Math.round((bytes / 1024 / 1024) * 10) / 10;
+
+/**
+ * Transcribe an audio or video file with Groq Whisper.
+ * Returns { transcript (timestamped lines), text, duration_seconds, language, model, file, recorded_at_ms, converted }.
+ */
+export async function transcribeAudio({ path: file, language, vocabulary } = {}, deps = {}) {
+  const fetchFn = deps.fetch ?? globalThis.fetch;
+  const exec = deps.exec ?? execFile;
+  if (!file || typeof file !== "string") throw new Error("path is required: the recording to transcribe.");
+  if (language !== undefined && !/^[a-z]{2,3}$/i.test(String(language))) throw new Error("language must be a 2-letter code like en or hi (leave it out to detect it).");
+  const key = groqKey();
+
+  let stat;
+  try {
+    stat = fs.statSync(file);
+  } catch {
+    throw new Error(`Cannot find the recording: ${path.basename(file)}.`);
+  }
+  if (!stat.isFile()) throw new Error("path must be a file.");
+  if (!stat.size) throw new Error("The recording is empty.");
+
+  const limit = (Number(process.env.GROQ_MAX_FILE_MB) > 0 ? Number(process.env.GROQ_MAX_FILE_MB) : 25) * 1024 * 1024;
+  const ext = path.extname(file).slice(1).toLowerCase();
+  let upload = file;
+  let converted = false;
+  let temp = null;
+  try {
+    if (!AUDIO_EXTS.includes(ext) || stat.size > limit) {
+      const why = !AUDIO_EXTS.includes(ext) ? `".${ext || "?"}" is not a format Groq accepts (${AUDIO_EXTS.join(", ")})` : `the file is ${mb(stat.size)} MB and the limit is ${mb(limit)} MB`;
+      if (!(await hasFfmpeg(exec))) {
+        throw new Error(`Cannot send this file: ${why}. Install ffmpeg (Windows: winget install ffmpeg) and the server will convert it automatically, or convert it yourself to mp3/m4a under ${mb(limit)} MB.`);
+      }
+      temp = await compress(exec, file);
+      upload = temp;
+      converted = true;
+      const size = fs.statSync(temp).size;
+      if (size > limit) throw new Error(`Even after compressing, the recording is ${mb(size)} MB (limit ${mb(limit)} MB). Split it into shorter parts, or set GROQ_MAX_FILE_MB=100 if your Groq account is on the dev tier.`);
+    }
+
+    const form = new FormData();
+    form.append("file", new Blob([fs.readFileSync(upload)]), path.basename(upload));
+    const model = process.env.GROQ_WHISPER_MODEL || DEFAULT_MODEL;
+    form.append("model", model);
+    form.append("response_format", "verbose_json");
+    form.append("temperature", "0");
+    if (language) form.append("language", String(language).toLowerCase());
+    if (vocabulary && String(vocabulary).trim()) form.append("prompt", String(vocabulary).trim().slice(0, 800));
+
+    let res;
+    try {
+      res = await fetchFn(GROQ_URL, { method: "POST", headers: { authorization: `Bearer ${key}` }, body: form, signal: AbortSignal.timeout(10 * 60_000) });
+    } catch (err) {
+      throw new Error(`Could not reach Groq: ${String(err.message).split(key).join("[REDACTED]")}`);
+    }
+    const data = await res.json().catch(() => ({}));
+    if (!res.ok) {
+      const why = String(data?.error?.message || `HTTP ${res.status}`).split(key).join("[REDACTED]");
+      if (res.status === 401) throw new Error("Groq rejected the API key. Check GROQ_API_KEY.");
+      if (res.status === 413) throw new Error(`Groq says the file is too large (${why}).`);
+      if (res.status === 429) {
+        const wait = res.headers?.get?.("retry-after");
+        throw new Error(`Groq rate limit hit${wait ? `; retry in ${wait}s` : ""}. The free tier limits audio minutes per hour and per day.`);
+      }
+      throw new Error(`Groq error: ${why}`);
+    }
+    const text = String(data.text ?? "").trim();
+    if (!text) throw new Error("No speech was found in the recording.");
+    return {
+      transcript: formatSegments(data.segments, text),
+      text,
+      duration_seconds: Number(data.duration) || stat.size / 16_000,
+      language: data.language ?? null,
+      model,
+      file: path.basename(file),
+      recorded_at_ms: stat.mtimeMs,
+      converted,
+    };
+  } finally {
+    if (temp) fs.rmSync(temp, { force: true });
+  }
+}

package/tools/updateCheck.js

@@ -0,0 +1,58 @@
+// "Is there a newer version?" Asked only by `status` and `doctor`, never while the server runs.
+// One small request to the npm registry, remembered for a day. Turn it off with CAUSLY_UPDATE_CHECK=off.
+import fs from "fs";
+import path from "path";
+import { causlyHome } from "./paths.js";
+
+const num = (v) => String(v).replace(/^v/, "").split("-")[0].split(".").map((n) => Number(n) || 0);
+
+/** > 0 when a is newer than b. */
+export function compareVersions(a, b) {
+  const x = num(a);
+  const y = num(b);
+  for (let i = 0; i < Math.max(x.length, y.length); i++) {
+    const d = (x[i] || 0) - (y[i] || 0);
+    if (d) return d;
+  }
+  return 0;
+}
+
+export async function checkForUpdate({
+  current,
+  name = "causly-server",
+  fetch: fetchFn = globalThis.fetch,
+  env = process.env,
+  cacheFile = path.join(causlyHome(), ".update-check.json"),
+  now = Date.now,
+  maxAgeMs = 24 * 3_600_000,
+} = {}) {
+  if (String(env.CAUSLY_UPDATE_CHECK || "").toLowerCase() === "off") return null;
+
+  try {
+    const cached = JSON.parse(fs.readFileSync(cacheFile, "utf8"));
+    if (cached.latest && now() - cached.checked_at < maxAgeMs) {
+      return { current, latest: cached.latest, newer: compareVersions(cached.latest, current) > 0 };
+    }
+  } catch {
+    // no cache yet
+  }
+
+  try {
+    const res = await fetchFn(`https://registry.npmjs.org/${name}/latest`, { signal: AbortSignal.timeout(3000) });
+    if (!res.ok) return null; // not published yet, or no network
+    const { version } = await res.json();
+    if (!version) return null;
+    try {
+      fs.mkdirSync(path.dirname(cacheFile), { recursive: true });
+      fs.writeFileSync(cacheFile, JSON.stringify({ latest: version, checked_at: now() }));
+    } catch {
+      // the cache is optional
+    }
+    return { current, latest: version, newer: compareVersions(version, current) > 0 };
+  } catch {
+    return null;
+  }
+}
+
+export const updateMessage = (r) =>
+  r?.newer ? `A newer version is available: ${r.current} -> ${r.latest}. Update with: npm install -g causly-server@latest (then restart your editor).` : null;

package/tools/vercelOps.js

@@ -0,0 +1,198 @@
+const VERCEL_API = "https://api.vercel.com";
+
+function getToken() {
+  const token = process.env.VERCEL_TOKEN;
+  if (!token) {
+    throw new Error(
+      "VERCEL_TOKEN not set. Run `npm run setup` to configure it, or add it manually to your .env file: VERCEL_TOKEN=..."
+    );
+  }
+  return token;
+}
+
+async function vercelFetch(path, options = {}) {
+  const token = getToken();
+  const res = await fetch(`${VERCEL_API}${path}`, {
+    ...options,
+    headers: {
+      Authorization: `Bearer ${token}`,
+      ...(options.body ? { "Content-Type": "application/json" } : {}),
+      ...options.headers,
+    },
+  });
+
+  const text = await res.text();
+  let data;
+  try {
+    data = text ? JSON.parse(text) : null;
+  } catch {
+    data = text;
+  }
+
+  if (!res.ok) {
+    const message = data?.error?.message || res.statusText;
+    throw new Error(`Vercel API error (${res.status}): ${message}`);
+  }
+
+  return data;
+}
+
+/** Get the authenticated Vercel user/team — connectivity/auth check. */
+export async function vercelGetAuthenticatedUser() {
+  const data = await vercelFetch("/v2/user");
+  return { id: data.user.id, username: data.user.username, email: data.user.email };
+}
+
+/** List projects for the authenticated user/team. */
+export async function vercelListProjects({ limit = 20 }) {
+  const data = await vercelFetch(`/v9/projects?limit=${limit}`);
+  return {
+    projects: data.projects.map((p) => ({
+      id: p.id,
+      name: p.name,
+      framework: p.framework,
+      latest_url: p.targets?.production?.url || null,
+    })),
+  };
+}
+
+/** Get details of a single project by name or ID. */
+export async function vercelGetProject({ project }) {
+  const data = await vercelFetch(`/v9/projects/${project}`);
+  return {
+    id: data.id,
+    name: data.name,
+    framework: data.framework,
+    link: data.link ? { type: data.link.type, repo: `${data.link.org}/${data.link.repo}` } : null,
+  };
+}
+
+/** List recent deployments, optionally scoped to a project. */
+export async function vercelListDeployments({ project, limit = 10 }) {
+  const query = project ? `?projectId=${project}&limit=${limit}` : `?limit=${limit}`;
+  const data = await vercelFetch(`/v6/deployments${query}`);
+  return {
+    deployments: data.deployments.map((d) => ({
+      uid: d.uid,
+      name: d.name,
+      url: d.url,
+      state: d.state,
+      created: new Date(d.created).toISOString(),
+    })),
+  };
+}
+
+/** Get the status/details of a specific deployment. */
+export async function vercelGetDeployment({ deployment_id }) {
+  const data = await vercelFetch(`/v13/deployments/${deployment_id}`);
+  return {
+    uid: data.id,
+    name: data.name,
+    url: data.url,
+    state: data.readyState,
+    created: new Date(data.createdAt).toISOString(),
+  };
+}
+
+/**
+ * Resolve a GitHub "owner/repo" string to the numeric repo ID Vercel's
+ * gitSource requires. Uses GITHUB_TOKEN if set; falls back to an
+ * unauthenticated call for public repos if it isn't.
+ */
+async function resolveGithubRepoId(ownerSlashRepo) {
+  const headers = { Accept: "application/vnd.github+json", "User-Agent": "causly-server" };
+  if (process.env.GITHUB_TOKEN) headers.Authorization = `Bearer ${process.env.GITHUB_TOKEN}`;
+
+  const res = await fetch(`https://api.github.com/repos/${ownerSlashRepo}`, { headers });
+  if (!res.ok) {
+    throw new Error(
+      `Could not resolve GitHub repo "${ownerSlashRepo}" to an ID (${res.status}). Check the owner/repo is correct and accessible.`
+    );
+  }
+  const data = await res.json();
+  return data.id;
+}
+
+/**
+ * Trigger a new deployment for a git-connected project by redeploying
+ * from a given git ref (branch/commit). Vercel's API needs the numeric
+ * GitHub repo ID (not just "owner/repo"), so this resolves it via the
+ * GitHub API automatically.
+ */
+export async function vercelCreateDeployment({ name, project, git_source_repo, git_source_ref = "main", git_source_type = "github" }) {
+  const repoId = await resolveGithubRepoId(git_source_repo);
+
+  const data = await vercelFetch("/v13/deployments", {
+    method: "POST",
+    body: JSON.stringify({
+      name,
+      project,
+      gitSource: {
+        type: git_source_type,
+        repoId,
+        ref: git_source_ref,
+      },
+    }),
+  });
+  return { uid: data.id, url: data.url, state: data.readyState };
+}
+
+/** Delete a project. */
+export async function vercelDeleteProject({ project }) {
+  await vercelFetch(`/v9/projects/${project}`, { method: "DELETE" });
+  return { project, deleted: true };
+}
+
+/** Get build/runtime logs for a deployment. */
+export async function vercelGetDeploymentLogs({ deployment_id, limit = 200 }) {
+  const data = await vercelFetch(`/v3/deployments/${deployment_id}/events?limit=${limit}`);
+  const events = Array.isArray(data) ? data : data.events || [];
+  return {
+    deployment_id,
+    logs: events.map((e) => ({ type: e.type, text: e.text ?? e.payload?.text, created: e.created })),
+  };
+}
+
+/** Get deployment build/progress events (separate from raw logs — includes build step states). */
+export async function vercelGetDeploymentEvents({ deployment_id }) {
+  const data = await vercelFetch(`/v13/deployments/${deployment_id}`);
+  return {
+    deployment_id,
+    state: data.readyState,
+    ready_substate: data.readySubstate,
+    checks_state: data.checksState,
+    build_errors: data.errorMessage ? { message: data.errorMessage, code: data.errorCode } : null,
+  };
+}
+
+/** Cancel a currently building/queued deployment. */
+export async function vercelCancelDeployment({ deployment_id }) {
+  const data = await vercelFetch(`/v12/deployments/${deployment_id}/cancel`, { method: "PATCH" });
+  return { deployment_id, state: data.readyState };
+}
+
+/** Hit a URL and report status/response time — used to verify a deployment is actually healthy after it goes live. */
+export async function httpCheck({ url, timeout_ms = 10_000 }) {
+  const start = Date.now();
+  try {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeout_ms);
+    const res = await fetch(url, { method: "GET", redirect: "follow", signal: controller.signal });
+    clearTimeout(timer);
+    const response_time_ms = Date.now() - start;
+    return {
+      url,
+      status: res.status,
+      healthy: res.status >= 200 && res.status < 400,
+      response_time_ms,
+    };
+  } catch (err) {
+    return {
+      url,
+      status: null,
+      healthy: false,
+      response_time_ms: Date.now() - start,
+      error: err.name === "AbortError" ? "timeout" : err.message,
+    };
+  }
+}

package/tools/verifyBoundaryAttest.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import fs from "fs";
+import { pathToFileURL } from "url";
+import { verifyBoundaryAttestReceipt } from "./boundaryAttest.js";
+
+export function verifyReceiptFile(receiptPath, expectedPublicKeyPath) {
+  return verifyBoundaryAttestReceipt(fs.readFileSync(receiptPath, "utf8"), fs.readFileSync(expectedPublicKeyPath, "utf8"));
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const [, , receiptPath, expectedPublicKeyPath] = process.argv;
+  if (!receiptPath || !expectedPublicKeyPath) {
+    console.error("Usage: node tools/verifyBoundaryAttest.js <receipt.json> <expected-ed25519-public-key.pem>");
+    process.exitCode = 2;
+  } else {
+    try {
+      const result = verifyReceiptFile(receiptPath, expectedPublicKeyPath);
+      console.log(JSON.stringify(result));
+      if (!result.ok) process.exitCode = 1;
+    } catch (err) {
+      console.log(JSON.stringify({ ok: false, reason: "read_error", detail: err.message }));
+      process.exitCode = 1;
+    }
+  }
+}