@vatio-ai/cli 0.50.0 → 0.52.0

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/deploy.mjs

@@ -18,7 +18,7 @@ import { buildBundle, BundleError } from "../bundle.mjs";
 import { ApiClient, CliClient } from "../api-client.mjs";
 import { NotFoundError } from "../http.mjs";
 import { deviceLogin } from "./auth.mjs";
-import { detectGitSha, fail, takeEnv, takeFlag, takeValue } from "../support.mjs";
+import { detectGitSha, fail, paint, takeEnv, takeFlag, takeValue } from "../support.mjs";
 
 // The first command that makes something exist on a server, so the first one
 // that needs to know whose it is.
@@ -141,6 +141,16 @@ export async function push(config, args) {
     console.log(hint.message);
     console.log(`  ${hint.url}`);
   }
+  printNotices(payload);
+}
+
+// Something the platform wants the developer to know about the command they
+// just ran -- a deprecation, usually. On stderr so scripts reading stdout keep
+// working.
+function printNotices(payload) {
+  for (const notice of asArray(payload.notices)) {
+    process.stderr.write(`\n${paint("yellow", `Notice: ${notice}`)}\n`);
+  }
 }
 
 export async function publish(config, args) {
@@ -156,12 +166,14 @@ export async function publish(config, args) {
   const from = asArray(payload.published_from);
   const source = from.length > 0 ? ` from ${from.join(", ")}` : "";
   console.log(`Published live deployment #${payload.deployment_id}${source} (git_sha=${JSON.stringify(payload.git_sha ?? null)})`);
+  printNotices(payload);
 }
 
 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})`);
+  printNotices(payload);
 }
 
 export async function status(config) {

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

@@ -69,7 +69,8 @@ const COMMANDS = {
     summary:
       "Promote the latest push to live (or the preview `--env` names), which is what customers " +
       "see. Ask the developer first: this is " +
-      "the one step that changes what real visitors get.",
+      "the one step that changes what real visitors get. Refused when the workspace is connected " +
+      "to GitHub: there, live changes only by merging to the default branch.",
     annotations: { readOnlyHint: false, destructiveHint: true }
   },
   rollback: {
@@ -94,10 +95,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/help.mjs

@@ -25,7 +25,8 @@ flag, the directory decides.
   Deploy:
     push [--env NAME]          Validate the workspace, then update a preview
     publish [--env NAME]       Promote the latest push to live. --env promotes
-                               a specific preview instead
+                               a specific preview instead. Refused when GitHub
+                               is connected: merge to the default branch
     rollback                   Restore the previous live deployment
     status                     Preview and live deployment state
     diff [--env NAME]          What this directory would change (default: preview)
@@ -49,6 +50,9 @@ 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

package/package.json

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