@vatio-ai/cli 0.49.0 → 0.51.0

package/bin/vatio.mjs

@@ -24,6 +24,7 @@ import { kb } from "../lib/commands/knowledge.mjs";
 import { instagram, whatsapp } from "../lib/commands/channels.mjs";
 import { docs, issue } from "../lib/commands/support-commands.mjs";
 import { mcp } from "../lib/commands/mcp.mjs";
+import { printUpdateNotice, startUpdateCheck } from "../lib/update-notice.mjs";
 
 // Two commands that existed and are gone, answered by name rather than as
 // unknown: one was removed from the product, the other is what npm does.
@@ -38,6 +39,12 @@ const RETIRED = {
 async function main(argv) {
   const args = argv.slice(2);
   const command = args.shift();
+  const updateCheck = startUpdateCheck(command);
+  await run(command, args);
+  await printUpdateNotice(updateCheck);
+}
+
+async function run(command, args) {
   const config = new Config({ startDir: process.cwd() });
 
   switch (command) {

package/lib/api-client.mjs

@@ -127,6 +127,24 @@ export class ApiClient extends HttpClient {
     return this.post(`/knowledge_bases/${encode(base)}/sites/refresh`, { url });
   }
 
+  // Writes land in the base's draft, which preview answers from; live moves
+  // only on publish or rollback.
+  knowledgeChanges(base) {
+    return this.get(`/knowledge_bases/${encode(base)}/changes`);
+  }
+
+  publishKnowledgeBase({ base, note }) {
+    return this.post(`/knowledge_bases/${encode(base)}/publish`, { note });
+  }
+
+  knowledgeSnapshots(base) {
+    return this.get(`/knowledge_bases/${encode(base)}/snapshots`);
+  }
+
+  rollbackKnowledgeBase({ base, number }) {
+    return this.post(`/knowledge_bases/${encode(base)}/snapshots/${encode(String(number))}/rollback`, {});
+  }
+
   // --- publishable tokens and the widget ------------------------------
 
   listPublishableTokens() {

package/lib/commands/knowledge.mjs

@@ -2,8 +2,12 @@
 //
 // 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.
+// That is why this is a command and not part of the manifest.
+//
+// Every write goes to the base's draft, which preview answers from. Live
+// answers from the last published snapshot and changes only on `publish` --
+// or `rollback`, which points it at an earlier one. So: write, try it on
+// preview, publish.
 //
 // A base holds entries, and an entry is markdown. Either you wrote it, or a
 // site wrote it from a page it read — and a site is one URL or one pattern,
@@ -30,6 +34,10 @@ export async function kb(config, args) {
     case "follow": return await follow(client, workspace, args.shift(), args.shift());
     case "unfollow": return await unfollow(client, workspace, args.shift(), args.shift());
     case "refresh": return await refresh(client, workspace, args.shift(), args.shift());
+    case "status": return await status(client, workspace, args.shift());
+    case "publish": return await publish(client, workspace, args);
+    case "history": return await history(client, workspace, args.shift());
+    case "rollback": return await rollback(client, workspace, args.shift(), args.shift());
     default: fail(`Unknown kb subcommand: ${sub}\n\n${usage()}`);
   }
 }
@@ -45,7 +53,11 @@ function usage() {
   vatio kb rm-entry BASE ENTRY              Delete one entry
   vatio kb follow BASE URL                  Read a site into the base, nightly
   vatio kb unfollow BASE URL                Stop reading it, and drop its entries
-  vatio kb refresh BASE [URL]               Read the sites again now`;
+  vatio kb refresh BASE [URL]               Read the sites again now
+  vatio kb status BASE                      What the draft has that live does not
+  vatio kb publish BASE [-m NOTE]           Take the draft live
+  vatio kb history BASE                     Every publication, newest first
+  vatio kb rollback BASE NUMBER             Point live back at publication NUMBER`;
 }
 
 async function list(client, workspace) {
@@ -80,6 +92,7 @@ async function show(client, workspace, name) {
     `${base.name} on workspace ${workspace}: entries=${base.entries_count} ` +
       `ready=${base.answerable_count}${referenceNote(base)}`
   );
+  console.log(`  ${liveNote(base)}`);
 
   const sites = asArray(base.sites);
   if (sites.length > 0) {
@@ -106,10 +119,20 @@ async function show(client, workspace, name) {
   console.log("\n  entries:");
   for (const entry of entries) {
     const origin = entry.written ? "written here" : entry.url;
-    console.log(`    ${entry.name}  ${entry.state ?? "?"}  ${origin}`);
+    const version = entry.version ? `  v${entry.version}` : "";
+    console.log(`    ${entry.name}${version}  ${entry.state ?? "?"}  ${origin}`);
   }
 }
 
+// Where live stands, and whether the draft has moved past it.
+function liveNote(base) {
+  const live = base.live_snapshot ? `live=publication #${base.live_snapshot}` : "live=never published";
+  const pending = base.pending_changes
+    ? `  ${base.pending_changes} unpublished change${base.pending_changes === 1 ? "" : "s"} — \`vatio kb publish ${base.name}\``
+    : "";
+  return `${live}${pending}`;
+}
+
 // Several names, because the moment this command is most often run is a push
 // that just refused for naming bases that do not exist yet -- and that push
 // names all of them at once. One base per invocation turned a first deploy
@@ -165,7 +188,9 @@ async function write(client, workspace, args) {
   }
 
   const row = await client.writeKnowledgeEntry({ base, name, content });
-  console.log(`Wrote ${row.name} in ${base} on workspace ${workspace}`);
+  const version = row.version ? ` (v${row.version})` : "";
+  console.log(`Wrote ${row.name}${version} to the draft of ${base} on workspace ${workspace}`);
+  console.log(`Preview answers with it now; \`vatio kb publish ${base}\` takes it live.`);
 }
 
 // Prints exactly what the platform holds, so a diff against the file you
@@ -221,6 +246,65 @@ async function refresh(client, workspace, base, url) {
   console.log(`Runs in the background — check progress with \`vatio kb show ${base}\``);
 }
 
+// The draft against live, entry by entry -- what `publish` would do.
+async function status(client, workspace, base) {
+  if (!base) fail("usage: vatio kb status BASE");
+
+  const changes = asArray((await client.knowledgeChanges(base)).data);
+  if (changes.length === 0) {
+    console.log(`${base} on workspace ${workspace}: everything is published`);
+    return;
+  }
+
+  console.log(`${base} on workspace ${workspace}: ${changes.length} unpublished change${changes.length === 1 ? "" : "s"}`);
+  for (const change of changes) {
+    const from = change.live_version ? `v${change.live_version}` : "—";
+    const to = change.draft_version ? `v${change.draft_version}` : "—";
+    console.log(`  ${change.change.padEnd(8)} ${change.name}  ${from} → ${to}`);
+  }
+  console.log(`\nPublish with \`vatio kb publish ${base} -m "what changed"\``);
+}
+
+async function publish(client, workspace, args) {
+  const base = args.shift();
+  if (!base) fail("usage: vatio kb publish BASE [-m NOTE]");
+
+  let note = "";
+  const flag = args.findIndex((arg) => arg === "-m" || arg === "--note");
+  if (flag !== -1) note = args[flag + 1] ?? "";
+
+  const snapshot = await client.publishKnowledgeBase({ base, note });
+  console.log(`Published ${base} on workspace ${workspace} as #${snapshot.number} (${snapshot.entries} entries)`);
+  console.log(`Live answers from it now. Undo with \`vatio kb rollback ${base} NUMBER\` — see \`vatio kb history ${base}\`.`);
+}
+
+async function history(client, workspace, base) {
+  if (!base) fail("usage: vatio kb history BASE");
+
+  const snapshots = asArray((await client.knowledgeSnapshots(base)).data);
+  if (snapshots.length === 0) {
+    console.log(`${base} on workspace ${workspace} was never published — \`vatio kb publish ${base}\``);
+    return;
+  }
+
+  console.log(`Publications of ${base} on workspace ${workspace}:`);
+  for (const snapshot of snapshots) {
+    const live = snapshot.live ? "  ← live" : "";
+    const who = snapshot.author ? `  ${snapshot.author}` : "";
+    const note = snapshot.note ? `  ${snapshot.note}` : "";
+    console.log(`  #${snapshot.number}  ${snapshot.created_at}${who}  entries=${snapshot.entries}${note}${live}`);
+  }
+}
+
+// Only the pointer moves: the draft, and every later publication, stay.
+async function rollback(client, workspace, base, number) {
+  if (!base || !number || !/^\d+$/.test(number)) fail("usage: vatio kb rollback BASE NUMBER");
+
+  await client.rollbackKnowledgeBase({ base, number });
+  console.log(`Live for ${base} on workspace ${workspace} is publication #${number} again`);
+  console.log("The draft is untouched; publish again whenever it is ready.");
+}
+
 // Blocking on purpose: `vatio kb write docs refunds < refunds.md` should behave
 // like every other filter, and a terminal with nobody piping into it returns ""
 // rather than hanging on a read that will never end.

package/lib/commands/mcp.mjs

@@ -94,10 +94,14 @@ const COMMANDS = {
     annotations: { readOnlyHint: false }
   },
   kb: {
-    usage: "[list] | show NAME | create NAME | add-source BASE NAME URL | upload BASE FILE... | reindex BASE",
+    usage:
+      "[list] | show NAME | create NAME | write BASE ENTRY [FILE] | cat BASE ENTRY | rm-entry BASE ENTRY | " +
+      "follow BASE URL | unfollow BASE URL | refresh BASE [URL] | status BASE | publish BASE [-m NOTE] | " +
+      "history BASE | rollback BASE NUMBER",
     summary:
       "Knowledge bases, which belong to the workspace rather than to a deployment: `knowledge:` in " +
-      "vatio.yml is a list of names, and a push neither fills nor empties one.",
+      "vatio.yml is a list of names, and a push neither fills nor empties one. Writes go to a draft that " +
+      "preview answers from; live changes only on publish.",
     annotations: { readOnlyHint: false, openWorldHint: true }
   },
   tokens: {

package/lib/commands/workspace-admin.mjs

@@ -7,7 +7,7 @@
 // vatio.yml and all of them are here.
 
 import { deployClient } from "./deploy.mjs";
-import { fail, takeValue } from "../support.mjs";
+import { askSecret, fail, paint, takeValue } from "../support.mjs";
 
 // live, preview, or a named preview like pr-42. This used to accept only the
 // first two, which meant a workspace could deploy to `pr-42` and then have no
@@ -46,10 +46,13 @@ export async function secrets(config, args) {
   }
   if (sub === "set") {
     const key = args.shift();
-    const value = args.shift();
-    if (!key || value === undefined) fail("Usage: vatio secrets set KEY VALUE");
+    if (!key) fail("Usage: vatio secrets set KEY [VALUE]");
+    // Asked for rather than typed on the command line, where it would stay in
+    // shell history.
+    const value = args.shift() ?? (await askSecret(`${paint("green", "?")} Paste your secret: `));
+    if (value === "") fail(`No value given for ${key}`);
     await client.upsertSecret({ key, value });
-    console.log(`Set ${key} on workspace ${workspace}`);
+    console.log(`${paint("green", "✓")} Set secret ${key} on workspace ${workspace}`);
     return;
   }
   if (sub === "rm" || sub === "remove" || sub === "delete") {
@@ -60,7 +63,7 @@ export async function secrets(config, args) {
     return;
   }
 
-  fail("Usage: vatio secrets list|set KEY VALUE|rm KEY");
+  fail("Usage: vatio secrets list|set KEY [VALUE]|rm KEY");
 }
 
 export async function tokens(config, args) {

package/lib/help.mjs

@@ -49,9 +49,13 @@ flag, the directory decides.
     kb rm-entry BASE ENTRY     Delete one entry
     kb follow BASE URL         Read a site into the base, nightly
     kb unfollow BASE URL | refresh BASE [URL]
+    kb status BASE             What the draft has that live does not
+    kb publish BASE [-m NOTE]  Take the draft live (preview already has it)
+    kb history BASE | rollback BASE NUMBER
 
   Credentials and the widget:
-    secrets list|set KEY VALUE|rm KEY
+    secrets list|set KEY [VALUE]|rm KEY
+                               Without VALUE, set asks for it with the input hidden
     tokens list|create [--env NAME] [--label NAME]|revoke PREFIX
     widget [--env NAME]        What the platform enforces, and the tokens there are
     auth --new-key             Keypair that signs the JWT saying who a visitor is
@@ -69,7 +73,7 @@ flag, the directory decides.
     config show|get KEY|set KEY VALUE|unset KEY
                                Keys: base_url, token
 
-  Environment: VATIO_BASE_URL, VATIO_TOKEN, VATIO_HOME
+  Environment: VATIO_BASE_URL, VATIO_TOKEN, VATIO_HOME, VATIO_NO_UPDATE_NOTIFIER
 
   Docs: https://docs.vatio.ai
 `;

package/lib/support.mjs

@@ -118,3 +118,59 @@ export async function ask(question) {
     rl.close();
   }
 }
+
+const COLORS = { green: 32, yellow: 33, cyan: 36 };
+
+export function paint(color, text) {
+  if (process.env.NO_COLOR || !process.stderr.isTTY) return text;
+  return `\x1b[${COLORS[color]}m${text}\x1b[0m`;
+}
+
+// A value typed or pasted with a star echoed per character, gh-style, so a
+// secret never lands in shell history or terminal scrollback. Off a terminal
+// the value is whatever arrives on stdin: `op read … | vatio secrets set KEY`.
+export async function askSecret(question) {
+  if (!process.stdin.isTTY) return (await readStdin()).replace(/\r?\n$/, "");
+
+  const input = process.stdin;
+  const output = process.stderr;
+  output.write(question);
+  input.setRawMode(true);
+  input.setEncoding("utf8");
+  input.resume();
+
+  return await new Promise((resolve, reject) => {
+    let value = "";
+    const finish = (error) => {
+      input.removeListener("data", onData);
+      input.setRawMode(false);
+      input.pause();
+      output.write("\n");
+      if (error) reject(error);
+      else resolve(value);
+    };
+    const onData = (chunk) => {
+      for (const char of chunk) {
+        if (char === "\r" || char === "\n") return finish();
+        if (char === "\u0003") return finish(new UserError("Cancelled"));
+        if (char === "\u007f" || char === "\b") {
+          if (value.length > 0) {
+            value = [...value].slice(0, -1).join("");
+            output.write("\b \b");
+          }
+          continue;
+        }
+        if (char < " ") continue;
+        value += char;
+        output.write("*");
+      }
+    };
+    input.on("data", onData);
+  });
+}
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8");
+}

package/lib/update-notice.mjs

@@ -0,0 +1,99 @@
+// "A new release of vatio is available", after a command, the way gh does it.
+//
+// The registry is asked at most once a day and the answer is kept in
+// ~/.vatio/update-check.json, so only the run that refreshes it makes a
+// request -- and that request runs alongside the command, not before it.
+// Nothing prints unless stderr is a terminal: a pipe, CI, or `vatio mcp`
+// (whose children write to a pipe) never sees it.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { configHome } from "./config.mjs";
+import { VERSION } from "./version.mjs";
+import { paint } from "./support.mjs";
+
+const PACKAGE = "@vatio-ai/cli";
+const LATEST_URL = `https://registry.npmjs.org/${PACKAGE}/latest`;
+const CHECK_EVERY_MS = 24 * 60 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 1_500;
+const SKIPPED_COMMANDS = ["mcp", "version", "--version", "-v"];
+
+export function startUpdateCheck(command) {
+  if (!shouldCheck(command)) return null;
+
+  const path = join(configHome(), "update-check.json");
+  const cached = readState(path);
+  if (cached && Date.now() - Date.parse(cached.checked_at) < CHECK_EVERY_MS) {
+    return Promise.resolve(cached.latest);
+  }
+  return fetchLatest().then((latest) => {
+    if (latest) writeState(path, { checked_at: new Date().toISOString(), latest });
+    return latest ?? cached?.latest ?? null;
+  });
+}
+
+export async function printUpdateNotice(check) {
+  if (!check) return;
+  const latest = await check.catch(() => null);
+  if (!latest || !isNewer(latest, VERSION)) return;
+
+  // npx sets npm_command=exec; a global install has no npm around it at all.
+  const upgrade = process.env.npm_command === "exec"
+    ? `npx ${PACKAGE}@latest`
+    : `npm install -g ${PACKAGE}@latest`;
+  process.stderr.write(
+    `\n${paint("yellow", `A new release of vatio is available: ${VERSION} → ${latest}`)}\n` +
+    `To upgrade, run: ${upgrade}\n` +
+    `${paint("cyan", "https://docs.vatio.ai/changelog")}\n`
+  );
+}
+
+function shouldCheck(command) {
+  if (SKIPPED_COMMANDS.includes(command)) return false;
+  if (!process.stderr.isTTY) return false;
+  if (process.env.CI || process.env.VATIO_NO_UPDATE_NOTIFIER) return false;
+  return true;
+}
+
+async function fetchLatest() {
+  try {
+    const response = await fetch(LATEST_URL, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+    if (!response.ok) return null;
+    const version = (await response.json())?.version;
+    return typeof version === "string" ? version : null;
+  } catch {
+    return null;
+  }
+}
+
+function readState(path) {
+  if (!existsSync(path)) return null;
+  try {
+    const state = JSON.parse(readFileSync(path, "utf8"));
+    return typeof state?.latest === "string" && typeof state?.checked_at === "string" ? state : null;
+  } catch {
+    return null;
+  }
+}
+
+function writeState(path, state) {
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(state)}\n`);
+  } catch {
+    // A read-only home only means the next run asks the registry again.
+  }
+}
+
+// Plain x.y.z; a prerelease on either side is never announced.
+function isNewer(candidate, current) {
+  const parse = (value) => /^(\d+)\.(\d+)\.(\d+)$/.exec(value)?.slice(1).map(Number);
+  const a = parse(candidate);
+  const b = parse(current);
+  if (!a || !b) return false;
+  for (let i = 0; i < 3; i += 1) {
+    if (a[i] !== b[i]) return a[i] > b[i];
+  }
+  return false;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vatio-ai/cli",
-  "version": "0.49.0",
+  "version": "0.51.0",
   "description": "Vatio CLI — deploy and manage Vatio agent workspaces",
   "keywords": [
     "vatio",