@vatio-ai/cli 0.37.2

package/lib/commands/deploy.mjs

@@ -0,0 +1,237 @@
+// push / publish / rollback / status / diff / tools check.
+//
+// Every one of them is HTTP. The workspace is parsed by the platform
+// (POST /deploy/check), so what is left here is: read the directory, send it,
+// print what came back.
+//
+// `pull` is deliberately not here yet. It is the one command that writes over
+// the developer's own files, and the Ruby version carries real subtlety doing
+// it -- a comment where the logo would go, because a revision keeps the name
+// and digest but never the bytes; `identity.pub` written back out; a specific
+// key order in the file it emits. Porting that from memory is how you ship a
+// command that quietly mangles a workspace, so it comes with a round-trip test
+// (push, pull, diff clean) rather than with this.
+
+import { stringify as stringifyYaml } from "yaml";
+
+import { buildBundle, BundleError } from "../bundle.mjs";
+import { ApiClient, CliClient } from "../api-client.mjs";
+import { NotFoundError } from "../http.mjs";
+import { detectGitSha, fail, takeEnv, takeFlag, takeValue } from "../support.mjs";
+
+export function deployClient(config, workspace) {
+  const base = config.resolveBaseUrl();
+  if (!base) fail("VATIO_BASE_URL is required (env or `vatio config set base_url …`)");
+  const token = config.resolveToken();
+  if (!token) fail("VATIO_TOKEN is required (env or `vatio login`)");
+
+  return new ApiClient({ baseUrl: `${base}/api/v1/${workspace}`, token });
+}
+
+export function workspacesClient(config) {
+  const token = config.resolveToken();
+  if (!token) fail(`Run \`vatio login\` first (no token in ${config.configPath})`);
+  return new CliClient({ baseUrl: config.resolveBaseUrl(), token });
+}
+
+// One call answers every local question about a workspace: whether it loads,
+// what manifest it builds, and what it would change. The parse behind it is the
+// platform's, which is the point -- a CLI that parsed the directory itself
+// could only ever be as current as the release the developer happened to
+// install.
+export async function checkWorkspace(config, workspace, { environment = null } = {}) {
+  const root = config.workspaceRootRequired();
+  let files;
+  try {
+    files = buildBundle(root);
+  } catch (error) {
+    if (error instanceof BundleError) fail(`vatio: ${error.message}`);
+    throw error;
+  }
+  return deployClient(config, workspace).check({ files, environment });
+}
+
+export function printDiagnostics(payload) {
+  for (const row of asArray(payload.errors)) console.error(`error: ${diagnosticLine(row)}`);
+  for (const row of asArray(payload.warnings)) console.error(`warning: ${diagnosticLine(row)}`);
+}
+
+// A diagnostic is { message, path } -- `path` is the file it is about, or null
+// for the workspace as a whole. Most messages already open with their own path,
+// which is where the platform read it from, so only prepend it when it is
+// missing rather than printing `tools/x.js: tools/x.js: …`.
+function diagnosticLine(row) {
+  if (!row || typeof row !== "object") return String(row);
+
+  const message = String(row.message ?? "");
+  const path = String(row.path ?? "");
+  if (path === "" || message.startsWith(`${path}:`)) return message;
+  return `${path}: ${message}`;
+}
+
+export async function toolsCheck(config, args) {
+  if (args[0] === "invoke") {
+    fail("`vatio tools invoke` was removed. Test tools inside `vatio chat` so access/auth run in the agent loop.");
+  }
+  if (args.length > 0 && args[0] !== "check") fail("Usage: vatio tools check");
+
+  const workspace = config.resolveWorkspaceRequired();
+  const payload = await checkWorkspace(config, workspace);
+  printDiagnostics(payload);
+  if (!payload.ok) fail(`tools check failed (${asArray(payload.errors).length} error(s))`);
+
+  const tools = asArray(payload.manifest?.tools);
+  console.log(`tools check ok (${tools.length} tool(s))`);
+}
+
+export async function push(config, args) {
+  // Null, not "preview": the platform owns that default, and sending it
+  // explicitly would make a bare `vatio push` and `vatio push --env preview`
+  // two different requests that only happen to agree today.
+  const environment = takeEnv(args, { fallback: null });
+  const workspace = config.resolveWorkspaceRequired();
+
+  // The remote has to exist before the workspace can be checked: the slug is in
+  // the URL of the call that checks it. It is created unnamed -- the push a few
+  // lines down applies `business.name` from the manifest anyway.
+  const clients = workspacesClient(config);
+  const created = !(await clients.workspaceExists(workspace));
+  if (created) {
+    await clients.createWorkspace({ slug: workspace });
+    console.log(`Created remote workspace ${workspace}`);
+  }
+
+  const check = await checkWorkspace(config, workspace, { environment });
+  printDiagnostics(check);
+  if (!check.ok) fail(`push aborted: check failed (${asArray(check.errors).length} error(s))`);
+
+  const client = deployClient(config, workspace);
+  const payload = await client.pushPreview({
+    manifest: check.manifest,
+    gitSha: detectGitSha(config.workspaceRootRequired()),
+    createdBy: process.env.USER ?? null,
+    environment
+  });
+
+  const landedOn = payload.environment ?? "preview";
+  console.log(`Pushed deployment #${payload.deployment_id} to ${landedOn} (git_sha=${JSON.stringify(payload.git_sha ?? null)})`);
+  // The link that opens without a login -- what makes a preview testable by
+  // someone who is not the developer who pushed it.
+  if (payload.share_url) console.log(`Open it: ${payload.share_url}`);
+  for (const warning of asArray(payload.warnings)) console.log(`  warning: ${warning}`);
+  if (payload.preview_url) console.log(`Preview: ${payload.preview_url}`);
+
+  const hint = payload.whatsapp_preview_hint;
+  if (hint) {
+    console.log("");
+    console.log(hint.message);
+    console.log(`  ${hint.url}`);
+  }
+}
+
+export async function publish(config, args) {
+  // Here `--env` names the preview being promoted, not a destination: the
+  // destination of a publish is always live.
+  const environment = takeEnv(args, { fallback: null });
+  const workspace = config.resolveWorkspaceRequired();
+  const payload = await deployClient(config, workspace).publish({
+    createdBy: process.env.USER ?? null,
+    environment
+  });
+  console.log(`Published live deployment #${payload.deployment_id} (git_sha=${JSON.stringify(payload.git_sha ?? null)})`);
+}
+
+export async function rollback(config) {
+  const workspace = config.resolveWorkspaceRequired();
+  const payload = await deployClient(config, workspace).rollback({ createdBy: process.env.USER ?? null });
+  console.log(`Rolled back to deployment #${payload.deployment_id} (from #${payload.rolled_back_from_id})`);
+}
+
+export async function status(config) {
+  const workspace = config.resolveWorkspaceRequired();
+  const payload = await deployClient(config, workspace).deployStatus();
+  console.log(JSON.stringify(payload, null, 2));
+
+  // A base with content that no deployed agent reads is knowledge the agent
+  // cannot reach, and nothing else says so -- it just answers without it. On
+  // stderr so piping `vatio status` into jq keeps working.
+  for (const base of asArray(payload.unreferenced_knowledge_bases)) {
+    console.error(
+      `Warning: knowledge base "${base.name}" has ${base.entries_count} entries but no deployed agent ` +
+        `reads it — add \`knowledge: [${base.name}]\` to vatio.yml and push.`
+    );
+  }
+}
+
+export async function diff(config, args) {
+  const environment = takeEnv(args, { fallback: "preview" });
+  const full = takeFlag(args, "--full");
+  const stat = takeFlag(args, "--stat");
+  const nameOnly = takeFlag(args, "--name-only");
+  const format = takeValue(args, "--format");
+  if (format && !["text", "json"].includes(format)) fail(`Unknown format ${JSON.stringify(format)} (text|json)`);
+
+  const workspace = config.resolveWorkspaceRequired();
+  // The diff comes back with the check -- one call instead of "parse here,
+  // fetch there, compare with a copy of the platform's rules that may have
+  // drifted". `--env live` is what answers "what would publishing change?"
+  const payload = await checkWorkspace(config, workspace, { environment });
+  printDiagnostics(payload);
+  if (!payload.ok) fail(`diff aborted: the workspace does not load (${asArray(payload.errors).length} error(s))`);
+
+  const local = payload.manifest;
+  const changes = asArray(payload.diff);
+
+  if (changes.length === 0) {
+    console.log(`No diff vs remote ${environment}`);
+    return;
+  }
+  if (full) {
+    console.error("Warning: --full prints complete tool source. Avoid using it in shared CI logs.");
+    let remote = {};
+    try {
+      remote = (await deployClient(config, workspace).deployedManifest({ environment })).manifest ?? {};
+    } catch (error) {
+      if (!(error instanceof NotFoundError)) throw error;
+    }
+    console.log("=== local ===");
+    console.log(stringifyYaml(local));
+    console.log(`=== remote ${environment} ===`);
+    console.log(stringifyYaml(remote));
+    return;
+  }
+  if (format === "json") {
+    console.log(JSON.stringify({ workspace, changes }, null, 2));
+    return;
+  }
+  if (stat) {
+    const counts = new Map();
+    for (const change of changes) counts.set(change.status, (counts.get(change.status) ?? 0) + 1);
+    const summary = [...counts].map(([status, count]) => `${count} ${status}`).join(", ");
+    console.log(`${changes.length} change(s): ${summary}`);
+    return;
+  }
+  if (nameOnly) {
+    for (const change of changes) console.log(diffLabel(change));
+    return;
+  }
+
+  for (const change of changes) {
+    const fields = asArray(change.fields);
+    const suffix = fields.length === 0 ? "" : ` (${fields.join(", ")})`;
+    console.log(`${statusLetter(change.status)} ${diffLabel(change)}${suffix}`);
+  }
+  console.log("Use `vatio diff --full` to print complete tool source.");
+}
+
+function diffLabel(change) {
+  return change.type === change.key ? change.type : `${change.type}/${change.key}`;
+}
+
+function statusLetter(status) {
+  return { added: "A", removed: "D", modified: "M" }[status] ?? "?";
+}
+
+function asArray(value) {
+  return Array.isArray(value) ? value : [];
+}

package/lib/commands/knowledge.mjs

@@ -0,0 +1,256 @@
+// `vatio kb` — knowledge bases.
+//
+// A base belongs to the workspace, not to a deployment: `knowledge:` in
+// vatio.yml is a list of *names*, and a push neither fills nor empties one.
+// That is why this is a command and not part of the manifest, and why live and
+// preview read the same base.
+
+import { basename } from "node:path";
+import { readFileSync, statSync } from "node:fs";
+
+import { deployClient } from "./deploy.mjs";
+import { fail, takeValue } from "../support.mjs";
+
+export async function kb(config, args) {
+  const workspace = config.resolveWorkspaceRequired();
+  const client = deployClient(config, workspace);
+  const sub = args.shift() ?? "list";
+
+  switch (sub) {
+    case "list": return await list(client, workspace);
+    case "show": return await show(client, workspace, args.shift());
+    case "create": return await create(client, workspace, args.shift());
+    case "rm": return await remove(client, workspace, args.shift());
+    case "add-source": return await addSource(client, workspace, args);
+    case "upload": return await upload(client, workspace, args.shift(), args);
+    case "rm-source": return await removeSource(client, workspace, args.shift(), args.shift());
+    case "reindex": return await reindex(client, workspace, args.shift(), args.shift());
+    default: fail(`Unknown kb subcommand: ${sub}\n\n${usage()}`);
+  }
+}
+
+function usage() {
+  return `usage:
+  vatio kb                                  List knowledge bases
+  vatio kb show NAME                        One base and its sources
+  vatio kb create NAME                      Create a base
+  vatio kb rm NAME                          Delete a base (must be unreferenced)
+  vatio kb add-source BASE NAME URL         Add a crawl
+  vatio kb upload BASE FILE...              Upload files into a base
+  vatio kb rm-source BASE NAME              Delete one source
+  vatio kb reindex BASE [NAME]              Re-crawl one source, or every crawl`;
+}
+
+async function list(client, workspace) {
+  const bases = asArray((await client.knowledgeBases()).data);
+  if (bases.length === 0) {
+    console.log(`No knowledge bases on workspace ${workspace}`);
+    console.log("Create one with `vatio kb create docs`, then add `knowledge: [docs]` to vatio.yml");
+    return;
+  }
+
+  console.log(`Knowledge bases on workspace ${workspace} (${bases.length}):`);
+  for (const row of bases) {
+    console.log(`  ${row.name}  sources=${row.sources_count}  entries=${row.entries_count}${referenceNote(row)}`);
+  }
+}
+
+// A base nothing references is indexed knowledge the agent cannot reach: it
+// answers without it and nothing anywhere reports an error. This line is the
+// only place that shows up before a bad conversation does.
+function referenceNote(row) {
+  return row.referenced ? "" : "  (not referenced by any deployed agent)";
+}
+
+async function show(client, workspace, name) {
+  if (!name) fail("usage: vatio kb show NAME");
+
+  const base = await client.knowledgeBase(name);
+  console.log(`${base.name} on workspace ${workspace}: entries=${base.entries_count}${referenceNote(base)}`);
+
+  const sources = asArray(base.sources);
+  if (sources.length === 0) {
+    console.log(
+      `  no sources yet — add one with \`vatio kb add-source ${name} NAME URL\` or \`vatio kb upload ${name} FILE\``
+    );
+    return;
+  }
+
+  for (const row of sources) {
+    const lastCrawled = row.last_crawled_at ?? "never";
+    console.log(
+      `  ${row.name} [${row.kind}]  ${row.status}  pages=${pagesDisplay(row)}  ` +
+        `entries=${row.entries_count}  last_indexed_at=${lastCrawled}`
+    );
+    console.log(row.kind === "upload" ? `    ${row.filename}` : `    ${row.site_url}  ${patternsDisplay(row)}`);
+    if (row.last_error) console.log(`    error: ${row.last_error}`);
+  }
+}
+
+async function create(client, workspace, name) {
+  if (!name) fail("usage: vatio kb create NAME");
+
+  const base = await client.createKnowledgeBase(name);
+  console.log(`Created knowledge base ${base.name} on workspace ${workspace}`);
+  console.log("It is empty and nothing reads it yet. Fill it with `vatio kb add-source` or `vatio kb upload`,");
+  console.log(`then add \`knowledge: [${base.name}]\` to vatio.yml and push.`);
+}
+
+async function remove(client, workspace, name) {
+  if (!name) fail("usage: vatio kb rm NAME");
+
+  await client.deleteKnowledgeBase(name);
+  console.log(`Deleted knowledge base ${name} on workspace ${workspace}`);
+}
+
+async function addSource(client, workspace, args) {
+  const includes = takeAll(args, "--include");
+  const excludes = takeAll(args, "--exclude");
+  const [base, name, siteUrl] = args;
+
+  if (!base || !name || !siteUrl) {
+    fail("usage: vatio kb add-source BASE NAME URL [--include PATH] [--exclude PATH]");
+  }
+
+  const row = await client.addKnowledgeCrawl({ base, name, siteUrl, includes, excludes });
+  console.log(`Added crawl ${row.name} to ${base} on workspace ${workspace} (status=${row.status})`);
+  console.log(`Crawling runs in the background — check progress with \`vatio kb show ${base}\``);
+}
+
+// Every file in one command, because `knowledge/*.md` is how a repo that
+// predates knowledge bases holds its content, and moving it should be one line
+// rather than one line per file.
+async function upload(client, workspace, base, paths) {
+  if (!base || paths.length === 0) fail("usage: vatio kb upload BASE FILE...");
+
+  const missing = paths.filter((path) => !isFile(path));
+  if (missing.length > 0) fail(`No such file: ${missing.join(", ")}`);
+
+  await abortOnCrawlCollisions(client, base, paths);
+
+  for (const path of paths) {
+    const row = await client.uploadKnowledgeDocument({
+      base,
+      filename: basename(path),
+      content: readFileSync(path, "utf8")
+    });
+    console.log(`Uploaded ${basename(path)} to ${base} as ${row.name} (entries=${row.entries_count})`);
+  }
+  console.log(`Indexing runs in the background — check progress with \`vatio kb show ${base}\``);
+}
+
+// Checked for the whole batch before a single file goes up, so an upload of
+// forty files either happens or does not. The platform refuses each collision
+// on its own, but one file at a time means a collision on file twenty lands
+// after nineteen are already in -- half an upload nobody asked for.
+//
+// Advisory, not the guarantee: the platform is what actually refuses. If this
+// check and its naming rule ever drift, the worst case is that this misses a
+// collision and the upload stops there instead, which is where it stopped
+// before.
+async function abortOnCrawlCollisions(client, base, paths) {
+  const sources = asArray((await client.knowledgeBase(base)).sources);
+  const crawls = new Map(sources.filter((row) => row.kind === "crawl").map((row) => [row.name, row]));
+  if (crawls.size === 0) return;
+
+  const collisions = paths
+    .map((path) => [path, crawls.get(sourceNameFor(path))])
+    .filter(([, crawl]) => crawl);
+  if (collisions.length === 0) return;
+
+  const lines = collisions.map(([path, crawl]) => {
+    const declaration = [crawl.site_url, ...asArray(crawl.include).map((p) => `include=${p}`)]
+      .filter(Boolean)
+      .join(" ");
+    return `  ${basename(path)} would land on "${crawl.name}", a crawl of ${declaration}`;
+  });
+
+  fail(
+    `Refusing to upload: ${collisions.length} of ${paths.length} file(s) collide with a crawl in ${base}.\n\n` +
+      `${lines.join("\n")}\n\n` +
+      "An upload cannot take over a crawl — its pages would keep answering lookups\n" +
+      "under a source that no longer says where they came from. Rename the file(s),\n" +
+      `or drop the crawl first with \`vatio kb rm-source ${base} NAME\`.\n\n` +
+      "Nothing was uploaded."
+  );
+}
+
+// Mirrors the platform's own source naming. Kept in step by the platform
+// refusing anyway, not by this being right.
+function sourceNameFor(path) {
+  const stem = basename(String(path)).replace(/\.[^.]*$/, "").toLowerCase();
+  const slug = stem.replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return slug.slice(0, 60).replace(/-+$/, "");
+}
+
+async function removeSource(client, workspace, base, name) {
+  if (!base || !name) fail("usage: vatio kb rm-source BASE NAME");
+
+  await client.deleteKnowledgeSource({ base, name });
+  console.log(`Deleted source ${name} from ${base} on workspace ${workspace}`);
+}
+
+// A bare `vatio kb reindex BASE` re-runs every crawl in the base. Uploads are
+// skipped rather than failing the whole command: there is no upstream to
+// re-read, so "reindex everything" cannot mean them.
+async function reindex(client, workspace, base, name) {
+  if (!base) fail("usage: vatio kb reindex BASE [NAME]");
+
+  let targets;
+  if (name) {
+    targets = [name];
+  } else {
+    const crawls = asArray((await client.knowledgeBase(base)).sources).filter((row) => row.kind === "crawl");
+    if (crawls.length === 0) fail(`No crawls to reindex in ${base} on workspace ${workspace}`);
+    targets = crawls.map((row) => row.name);
+  }
+
+  for (const target of targets) {
+    const row = await client.reindexKnowledgeSource({ base, name: target });
+    console.log(`Reindexing ${row.name} in ${base} on workspace ${workspace} (status=${row.status})`);
+  }
+  console.log(`Crawling runs in the background — check progress with \`vatio kb show ${base}\``);
+}
+
+// pages_discovered_count is newer than pages_indexed_count -- a platform
+// predating it omits the key entirely, so this falls back to the old
+// single-number display rather than printing "pages=3/".
+function pagesDisplay(row) {
+  const discovered = row.pages_discovered_count;
+  const indexed = row.pages_indexed_count;
+  return discovered ? `${indexed}/${discovered}` : String(indexed ?? "");
+}
+
+// No patterns at all means the source covers the whole site, which is the
+// default and needs saying rather than printing blank.
+function patternsDisplay(row) {
+  const includes = asArray(row.include);
+  const excludes = asArray(row.exclude);
+  if (includes.length === 0 && excludes.length === 0) return "whole site";
+
+  const parts = [];
+  if (includes.length > 0) parts.push(`include=${includes.join(",")}`);
+  if (excludes.length > 0) parts.push(`exclude=${excludes.join(",")}`);
+  return parts.join("  ");
+}
+
+function takeAll(args, name) {
+  const values = [];
+  for (;;) {
+    const value = takeValue(args, name);
+    if (value === null) return values;
+    values.push(value);
+  }
+}
+
+function isFile(path) {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function asArray(value) {
+  return Array.isArray(value) ? value : [];
+}