@vatio-ai/cli 0.98.0 → 0.99.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/bin/vatio.mjs CHANGED
@@ -8,6 +8,8 @@ import { Config, ConfigError } from "../lib/config.mjs";
8
8
  import { CliOutdatedError, HttpError, UnauthorizedError, ForbiddenError, NotFoundError } from "../lib/http.mjs";
9
9
  import { UserError, fail } from "../lib/support.mjs";
10
10
  import { helpText } from "../lib/help.mjs";
11
+ import { unknownCommandMessage } from "../lib/suggest.mjs";
12
+ import { changelog } from "../lib/release-notes.mjs";
11
13
  import { login, logout } from "../lib/commands/auth.mjs";
12
14
  import { configCommand, doctor, init, version, whoami } from "../lib/commands/misc.mjs";
13
15
  import { diff, publish, pull, push, rollback, status } from "../lib/commands/deploy.mjs";
@@ -36,8 +38,9 @@ const RETIRED = {
36
38
  widget: "was removed: `vatio env` prints the snippet and its token, and the look is edited in\n" +
37
39
  "the inbox, under Channels → Widget.",
38
40
  mcp: "was removed. Point your coding agent at `vatio docs --save` and let it run the CLI.",
39
- update: "is npm's job now: `npx @vatio-ai/cli@latest` always runs the current release, and\n" +
40
- "`npm install -g @vatio-ai/cli@latest` updates a global install.",
41
+ update: "is npm's job: `npx @vatio-ai/cli@latest` always runs the current release, and\n" +
42
+ "`npm install -g @vatio-ai/cli@latest` updates a global install.\n" +
43
+ "`vatio changelog` says which release is current and what it changed.",
41
44
  propose: "was removed in 0.71.0. Test with `vatio test` and publish with `vatio publish`."
42
45
  };
43
46
 
@@ -128,6 +131,8 @@ async function run(command, args) {
128
131
  return await evalCommand(config, args);
129
132
  case "tools":
130
133
  return await tools(config, args);
134
+ case "changelog":
135
+ return await changelog(config, args);
131
136
  case "docs":
132
137
  return await docs(config, args);
133
138
  case "feedback":
@@ -141,7 +146,7 @@ async function run(command, args) {
141
146
  return console.log(helpText());
142
147
  default:
143
148
  if (RETIRED[command]) fail(`\`vatio ${command}\` ${RETIRED[command]}`);
144
- fail(`Unknown command: ${command}\n\n${helpText()}`);
149
+ fail(unknownCommandMessage(command, args));
145
150
  }
146
151
  }
147
152
 
@@ -141,8 +141,19 @@ export async function push(config, args) {
141
141
  // What the files match now, so the next push is built on it.
142
142
  config.rememberBaseDeployment({ baseUrl, workspace, deploymentId: payload.deployment_id });
143
143
 
144
- const landedOn = payload.environment ?? "preview";
145
- console.log(`Pushed deployment #${payload.deployment_id} to ${landedOn} (git_sha=${JSON.stringify(payload.git_sha ?? null)})`);
144
+ // The environment is named only when it is the answer to something: a push
145
+ // that is waiting for a publish sits in preview, and that is worth saying.
146
+ // One that visitors already have does not, and "to preview" there is the
147
+ // line that has to be explained by hand afterwards.
148
+ const outcome = payload.outcome;
149
+ const landedOn = outcome && typeof outcome === "object" ? (outcome.reaches_visitors ? null : outcome.environment) : (payload.environment ?? "preview");
150
+ const where = landedOn ? ` to ${landedOn}` : "";
151
+ console.log(`Pushed deployment #${payload.deployment_id}${where} (git_sha=${JSON.stringify(payload.git_sha ?? null)})`);
152
+ // What it means for the people talking to the agent. The environment name
153
+ // answers a question nobody asked: for a draft it said "to preview" while
154
+ // live was following every push, which is the single thing new developers
155
+ // have to be told by hand.
156
+ for (const line of consequenceLines(payload)) console.log(line);
146
157
  // Where to try it: the inbox's Test page for that environment.
147
158
  if (payload.share_url) console.log(`Try it: ${payload.share_url}`);
148
159
  for (const warning of asArray(payload.warnings)) console.log(` warning: ${warning}`);
@@ -157,11 +168,53 @@ export async function push(config, args) {
157
168
  printNotices(payload);
158
169
  }
159
170
 
171
+ // The two or three lines that say who sees this push, read off the platform's
172
+ // `outcome` rather than guessed from the environment name.
173
+ //
174
+ // A draft is the whole point: live follows preview on every push
175
+ // (Vatio::Deploy::FollowPreview), so the agent is answering with this now,
176
+ // and saying "pushed to preview" and nothing else is how a developer comes
177
+ // to believe their work is not live when it is.
178
+ function consequenceLines(payload) {
179
+ const outcome = payload.outcome;
180
+ // A platform older than this CLI sends no outcome; its prose notices still
181
+ // arrive and printNotices shows them.
182
+ if (!outcome || typeof outcome !== "object") return [];
183
+
184
+ if (outcome.reaches_visitors) {
185
+ const lines = ["→ Your agent is answering with this now."];
186
+ if (outcome.draft) {
187
+ lines.push(
188
+ " Every push reaches your app, WhatsApp and Instagram at once, until someone",
189
+ " outside your team talks to it. From their first conversation on, a push waits",
190
+ " for `vatio publish`."
191
+ );
192
+ }
193
+ return lines;
194
+ }
195
+
196
+ const live = outcome.live_deployment_id ? `deployment #${outcome.live_deployment_id}` : "the published version";
197
+ const lines = [];
198
+ if (outcome.left_draft_at) {
199
+ lines.push("→ People have started talking to your agent, so a push no longer reaches them.");
200
+ lines.push(` Visitors still get ${live}.`);
201
+ } else {
202
+ lines.push(`→ Visitors still get ${live}. This push is waiting.`);
203
+ }
204
+ lines.push(outcome.has_tests ? " Next: `vatio test --wait`, then `vatio publish`." : " Next: `vatio publish`.");
205
+ return lines;
206
+ }
207
+
160
208
  // Something the platform wants the developer to know about the command they
161
209
  // just ran -- a deprecation, usually. On stderr so scripts reading stdout keep
162
210
  // working.
211
+ //
212
+ // `outcome.supersedes` lists the ones consequenceLines already said in fewer
213
+ // words; printing both would say it twice.
163
214
  function printNotices(payload) {
215
+ const superseded = new Set(asArray(payload.outcome?.supersedes));
164
216
  for (const notice of asArray(payload.notices)) {
217
+ if (superseded.has(notice)) continue;
165
218
  process.stderr.write(`\n${paint("yellow", `Notice: ${notice}`)}\n`);
166
219
  }
167
220
  }
@@ -18,6 +18,9 @@ import { printSkillsHint } from "../skills-hint.mjs";
18
18
 
19
19
  const POLL_MS = 3_000;
20
20
  const DEFAULT_TIMEOUT_S = 900;
21
+ // A test run's report renders every case's turn, so it is the slowest read in
22
+ // the CLI; a flags document is the same shape.
23
+ const MARKDOWN_TIMEOUT_MS = 60_000;
21
24
 
22
25
  function workspaceBase(config) {
23
26
  const base = config.resolveBaseUrl();
@@ -28,17 +31,35 @@ function workspaceBase(config) {
28
31
 
29
32
  async function fetchMarkdown(config, path, what) {
30
33
  const { url, token } = workspaceBase(config);
31
- const response = await fetch(`${url}${path}`, {
32
- headers: { ...clientHeaders(), Accept: "text/markdown, text/plain", Authorization: `Bearer ${token}` },
33
- signal: AbortSignal.timeout(30_000)
34
- });
34
+ let response;
35
+ try {
36
+ response = await fetch(`${url}${path}`, {
37
+ headers: { ...clientHeaders(), Accept: "text/markdown, text/plain", Authorization: `Bearer ${token}` },
38
+ signal: AbortSignal.timeout(MARKDOWN_TIMEOUT_MS)
39
+ });
40
+ } catch (error) {
41
+ // AbortSignal.timeout rejects with a bare DOMException, which reached the
42
+ // top as `DOMException: TimeoutError: The operation was aborted due to
43
+ // timeout` and a stack trace: the two sessions it happened to both ended
44
+ // there. A long report is the usual reason, and it is still on Vatio's
45
+ // servers, so say what to run to read it.
46
+ const reason = error?.name === "TimeoutError" ? `took longer than ${MARKDOWN_TIMEOUT_MS / 1000}s to render` : "could not be read";
47
+ fail(`${what} ${reason}. Nothing was lost — it is on Vatio's servers. Try the same command again.`);
48
+ }
35
49
  await throwIfOutdated(response);
36
50
  if (!response.ok) {
37
51
  const body = await response.json().catch(() => null);
38
52
  const reason = body?.error?.message ?? `HTTP ${response.status}`;
39
53
  fail(`Could not read ${what} (${reason})`);
40
54
  }
41
- return await response.text();
55
+ try {
56
+ // The signal covers the body too, so a render that streams slowly aborts
57
+ // here rather than at the call above.
58
+ return await response.text();
59
+ } catch (error) {
60
+ const reason = error?.name === "TimeoutError" ? `stopped arriving after ${MARKDOWN_TIMEOUT_MS / 1000}s` : "could not be read";
61
+ fail(`${what} ${reason}. Nothing was lost — it is on Vatio's servers. Try the same command again.`);
62
+ }
42
63
  }
43
64
 
44
65
  // The open flags as one document: each flagged reply with the conversation
@@ -271,9 +292,33 @@ async function runTests(config, args, { name, waitByDefault }) {
271
292
  }
272
293
  const runs = started.runs ?? [];
273
294
  if (runs.length === 0) {
295
+ // "No tests" and "every test was skipped" are different answers, and the
296
+ // second one is the agent filter or an agent that is not on this
297
+ // environment (reported above) rather than an empty suite.
298
+ if (agent || (started.missing_agents ?? []).length > 0) {
299
+ console.log(
300
+ `No tests ran on ${environment}${agent ? ` for agent \`${agent}\`` : ""}. ` +
301
+ "`vatio test list` shows the suite and which agent each case belongs to."
302
+ );
303
+ return;
304
+ }
305
+ // What this said until now was "report a reply in the inbox", which is
306
+ // the door for a reply that went *wrong*. On a workspace where nothing
307
+ // has gone wrong yet there is nothing to report, so the answer read as
308
+ // "there is nothing to do here" and the suite never got started: of the
309
+ // twelve workspaces, six have never run a case, including the three
310
+ // newest. A suite is built out of replies that are already right, and
311
+ // `vatio test add` is how one is kept.
274
312
  console.log(
275
- "No reports to test yet. Report a reply in the inbox, or after a `vatio chat` with\n" +
276
- '`vatio flags add "what it should have done"`.'
313
+ "No tests yet, so there is nothing to replay.\n" +
314
+ "\n" +
315
+ "A test is a reply you have seen be right, kept so later versions keep it right:\n" +
316
+ ' vatio chat --new "what a visitor would ask"\n' +
317
+ ' vatio test add "what the answer has to say"\n' +
318
+ "\n" +
319
+ "Then `vatio test` replays them all on every version, and `vatio publish` refuses\n" +
320
+ "one that breaks them. A reply that was wrong is a report instead:\n" +
321
+ '`vatio flags add "what it should have done"`, or Reportar in the inbox.'
277
322
  );
278
323
  return;
279
324
  }
@@ -307,10 +352,20 @@ async function runTests(config, args, { name, waitByDefault }) {
307
352
  finished.push(row);
308
353
  }
309
354
 
355
+ // The verdict first, so it is what this command exits with. A report that
356
+ // will not render is a reading problem, and it used to decide the exit code:
357
+ // `fetchMarkdown` failing made a run that passed exit 1, and skipped the
358
+ // reports of every run after it.
359
+ if (finished.some((run) => run.failed > 0)) process.exitCode = 1;
360
+
310
361
  for (const run of finished) {
311
- process.stdout.write(await fetchMarkdown(config, `/evals/runs/${run.id}.md`, `test run ${run.id}`));
362
+ try {
363
+ process.stdout.write(await fetchMarkdown(config, `/evals/runs/${run.id}.md`, `test run ${run.id}`));
364
+ } catch (error) {
365
+ console.error(`vatio: ${error.message}`);
366
+ console.error(`vatio: run ${run.id} finished ${run.failed > 0 ? `with ${run.failed} failing` : "with every case passing"}.`);
367
+ }
312
368
  }
313
- if (finished.some((run) => run.failed > 0)) process.exitCode = 1;
314
369
  }
315
370
 
316
371
  async function testShow(config, id) {
@@ -3,6 +3,9 @@
3
3
  // publishable token (with the origins it accepts) and a server key; none of
4
4
  // them is in vatio.yml.
5
5
 
6
+ import { existsSync, readFileSync, realpathSync } from "node:fs";
7
+ import { join } from "node:path";
8
+
6
9
  import { deployClient } from "./deploy.mjs";
7
10
  import { askSecret, fail, paint, takeFlag, takeValue } from "../support.mjs";
8
11
 
@@ -39,6 +42,10 @@ export async function secrets(config, args) {
39
42
  const workspace = config.resolveWorkspaceRequired();
40
43
  const client = deployClient(config, workspace);
41
44
  const tests = takeFlag(args, "--tests");
45
+ // `--from-env` takes a name or nothing, so it cannot go through takeValue:
46
+ // that one fails when the flag is last (`set KEY --from-env`, the documented
47
+ // form) and swallows the next flag when there is one (`--from-env --tests`).
48
+ const fromEnv = takeOptionalValue(args, "--from-env");
42
49
  const given = givenEnvironment(args);
43
50
  if (tests && given) fail("--tests is the value for every environment but live; drop --env");
44
51
  const sub = args.shift() ?? "list";
@@ -50,10 +57,12 @@ export async function secrets(config, args) {
50
57
 
51
58
  if (sub === "set") {
52
59
  const key = args.shift();
53
- if (!key) fail("Usage: vatio secrets set KEY [VALUE] [--env NAME | --tests]");
54
- // Asked for rather than typed on the command line, where it would stay in
55
- // shell history.
56
- const value = args.shift() ?? (await askSecret(`${paint("green", "?")} Paste your secret: `));
60
+ if (!key) fail("Usage: vatio secrets set KEY [VALUE] [--from-env [NAME]] [--env NAME | --tests]");
61
+ const value = fromEnv === null
62
+ // Asked for rather than typed on the command line, where it would stay in
63
+ // shell history.
64
+ ? args.shift() ?? (await askSecret(`${paint("green", "?")} Paste your secret: `))
65
+ : readLocalEnv(config, fromEnv === "" ? key : fromEnv);
57
66
  if (value === "") fail(`No value given for ${key}`);
58
67
  await client.upsertSecret({ key, value, environment, tests });
59
68
  console.log(`${paint("green", "✓")} Set secret ${key} on workspace ${workspace} (${scope})`);
@@ -67,7 +76,7 @@ export async function secrets(config, args) {
67
76
  return;
68
77
  }
69
78
 
70
- fail("Usage: vatio secrets list|set KEY [VALUE]|rm KEY [--env NAME | --tests]");
79
+ fail("Usage: vatio secrets list|set KEY [VALUE] [--from-env [NAME]]|rm KEY [--env NAME | --tests]");
71
80
  }
72
81
 
73
82
  async function listSecrets(client, workspace, environment) {
@@ -228,6 +237,127 @@ export async function keys(config, args) {
228
237
  fail("Usage: vatio keys list|create [--env live|preview] [--label NAME]|revoke PREFIX");
229
238
  }
230
239
 
240
+ // A flag whose value is optional: `--flag`, `--flag VALUE` or `--flag=VALUE`.
241
+ // Returns null when it is absent and "" when it is there with no value, so
242
+ // the caller can tell those two apart. A following token that starts with `-`
243
+ // is the next flag, not this one's value.
244
+ function takeOptionalValue(args, name) {
245
+ const prefix = `${name}=`;
246
+ for (let i = 0; i < args.length; i += 1) {
247
+ if (args[i] === name) {
248
+ const next = args[i + 1];
249
+ if (next === undefined || next.startsWith("-")) {
250
+ args.splice(i, 1);
251
+ return "";
252
+ }
253
+ args.splice(i, 2);
254
+ return next;
255
+ }
256
+ if (args[i].startsWith(prefix)) {
257
+ const value = args[i].slice(prefix.length);
258
+ args.splice(i, 1);
259
+ return value;
260
+ }
261
+ }
262
+ return null;
263
+ }
264
+
265
+ // One named value, out of the process environment or the `.env` beside the
266
+ // workspace, so a coding agent can set a secret it is not allowed to see.
267
+ //
268
+ // Why it exists: the skills tell an agent to hand `vatio secrets` to the
269
+ // developer, because the value is theirs and not the agent's to read. That is
270
+ // right, and it also means somebody has to be at the keyboard -- in Grupo
271
+ // Proser's onboarding six of the eight `secrets set` calls were run by the
272
+ // human, each one a stop in the middle of the agent's work. Naming the key
273
+ // instead of the value keeps the secret out of the agent's context and out of
274
+ // shell history, and lets it finish on its own.
275
+ //
276
+ // Only the key asked for is read. There is no bulk upload on purpose: a
277
+ // `.env` holds more than this workspace needs, and none of the rest is
278
+ // Vatio's business.
279
+ function readLocalEnv(config, name) {
280
+ if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) fail(`\`${name}\` is not an environment variable name`);
281
+
282
+ const exported = process.env[name];
283
+ if (exported !== undefined && exported !== "") return exported;
284
+
285
+ const roots = [];
286
+ try {
287
+ roots.push(config.workspaceRootRequired());
288
+ } catch {
289
+ // No workspace yet: the cwd is still worth reading.
290
+ }
291
+ roots.push(process.cwd());
292
+
293
+ const seen = [];
294
+ for (const root of roots) {
295
+ // Resolved, so the workspace root and the cwd are not reported as two
296
+ // files when they are one (/tmp and /private/tmp on macOS).
297
+ let path = join(root, ".env");
298
+ try {
299
+ path = realpathSync(path);
300
+ } catch {
301
+ // Not there, or not readable: the existsSync below says so.
302
+ }
303
+ if (seen.includes(path)) continue;
304
+ seen.push(path);
305
+ if (!existsSync(path)) continue;
306
+
307
+ const found = valueIn(readFileSync(path, "utf8"), name);
308
+ if (found === null) continue;
309
+ if (found === UNTERMINATED) {
310
+ fail(
311
+ `\`${name}\` in ${path} opens a quote it does not close on the same line.\n` +
312
+ "A multi-line value is not read from a .env — pipe it instead: " +
313
+ `cat key.pem | vatio secrets set ${name}`
314
+ );
315
+ }
316
+ if (found === "") fail(`\`${name}\` is in ${path} but has no value.`);
317
+ return found;
318
+ }
319
+
320
+ fail(
321
+ `\`${name}\` is not in the environment${seen.length > 0 ? ` or in ${seen.join(" or ")}` : ""}.\n` +
322
+ `Export it, put it in a .env, or pass the value: vatio secrets set ${name} VALUE`
323
+ );
324
+ }
325
+
326
+ // A minimal .env read: `KEY=value`, with or without `export`, with or without
327
+ // quotes, with or without a trailing comment. No interpolation.
328
+ //
329
+ // Returns the value, null when the key is not in the file, or UNTERMINATED
330
+ // for a quote the line never closes -- a multi-line value, a PEM key usually,
331
+ // whose first line is not the secret. readLocalEnv refuses that rather than
332
+ // sending it.
333
+ //
334
+ // The last assignment wins, the way dotenv and `set -a; . ./.env` both read a
335
+ // file that sets one key twice.
336
+ function valueIn(text, name) {
337
+ let found = null;
338
+
339
+ for (const line of text.split(/\r?\n/)) {
340
+ const match = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(line);
341
+ if (!match || match[1] !== name) continue;
342
+
343
+ const rest = match[2].trim();
344
+ const quote = rest[0] === '"' || rest[0] === "'" ? rest[0] : null;
345
+ if (quote === null) {
346
+ // Bare: whitespace then `#` starts a comment.
347
+ found = rest.replace(/\s+#.*$/, "").trim();
348
+ continue;
349
+ }
350
+ // Quoted: up to the closing quote, so a `#` inside stays in the value and
351
+ // anything after the quote is a comment.
352
+ const closed = new RegExp(`^${quote}((?:[^${quote}\\\\]|\\\\.)*)${quote}`).exec(rest);
353
+ found = closed === null ? UNTERMINATED : closed[1].replace(/\\(.)/g, "$1");
354
+ }
355
+
356
+ return found;
357
+ }
358
+
359
+ const UNTERMINATED = Symbol("unterminated");
360
+
231
361
  // An empty list is not "anywhere": only Vatio's own pages can use the token.
232
362
  function originsLine(origins) {
233
363
  const list = asArray(origins);
package/lib/help.mjs CHANGED
@@ -4,7 +4,7 @@ export function helpText() {
4
4
  return `Vatio CLI ${VERSION}
5
5
 
6
6
  npx @vatio-ai/cli init my-agent Start a workspace here
7
- npx @vatio-ai/cli push Deploy it to preview
7
+ npx @vatio-ai/cli push Deploy it
8
8
 
9
9
  (installed globally with \`npm i -g @vatio-ai/cli\`, the command is just \`vatio\`)
10
10
 
@@ -12,9 +12,11 @@ A workspace is any directory with a vatio.yml. Every command except init reads
12
12
  \`workspace:\` from the vatio.yml at or above the cwd — there is no --workspace
13
13
  flag, the directory decides.
14
14
 
15
- --env NAME targets an environment, and there are two: preview (the next
16
- version, what \`vatio push\` updates) and live (what visitors talk to).
17
- Commands default as listed.
15
+ Until someone outside your team talks to your agent, \`push\` is the deploy:
16
+ live follows every one of them. From their first conversation on, a push waits
17
+ for \`publish\`, and that is what --env NAME is about: preview is the version
18
+ you are working on, live is what visitors talk to. Every push says which of
19
+ the two you are in. Commands default as listed.
18
20
 
19
21
  Getting started:
20
22
  init [SLUG] [--name NAME] Create vatio.yml here, and the remote to match
@@ -25,6 +27,10 @@ Commands default as listed.
25
27
  the workspaces it reaches
26
28
  doctor Node, config, workspace, token and account status
27
29
  version What this CLI is
30
+ changelog [--full] Which release is current, what it changed since the
31
+ version you have, and how to get it (npm does the
32
+ updating; this only tells you). --full prints each
33
+ entry whole instead of its headlines
28
34
  docs [--save [PATH]] The whole developer contract, live from Vatio
29
35
  feedback "TEXT" Tell the Vatio team what got in the way
30
36
  share-session ["FEEDBACK"] Send this Claude Code or Codex session to the
@@ -36,11 +42,14 @@ Commands default as listed.
36
42
  share-session --never Stop coding agents from offering
37
43
 
38
44
  Deploy:
39
- push [--force] Validate the workspace, then update preview; runs
40
- no tests (the first push signs in like \`login\`).
41
- Refused over edits made outside your files (pull
42
- them first) and over an unpublished push from
43
- another git branch; --force replaces either
45
+ push [--force] Validate the workspace, then deploy it; runs no
46
+ tests (the first push signs in like \`login\`).
47
+ Reaches your agent directly while the workspace
48
+ is a draft, and waits in preview once people
49
+ talk to it. Refused over edits made outside your
50
+ files (pull them first) and over an unpublished
51
+ push from another git branch; --force replaces
52
+ either
44
53
  pull [--env NAME] [--force]
45
54
  Write the deployed agent into vatio.yml's agent:
46
55
  block and tools/, edits from the Vatio MCP
@@ -137,8 +146,11 @@ Commands default as listed.
137
146
  quiet-hours off Answer around the clock
138
147
 
139
148
  Credentials:
140
- secrets list|set KEY [VALUE]|rm KEY [--env NAME | --tests]
149
+ secrets list|set KEY [VALUE] [--from-env [NAME]]|rm KEY [--env NAME | --tests]
141
150
  Without VALUE, set asks for it with the input hidden.
151
+ --from-env takes the value from your shell or the
152
+ .env beside the workspace, so a coding agent can set
153
+ a secret without being shown it (NAME defaults to KEY).
142
154
  With --env, the value only that environment uses;
143
155
  otherwise the value everywhere. With --tests, the
144
156
  value preview and every test run use, like a staging URL
@@ -0,0 +1,160 @@
1
+ // What changed between the installed CLI and the current release, read off
2
+ // the changelog Vatio publishes.
3
+ //
4
+ // `vatio update` was removed when npm became the thing that updates the CLI,
5
+ // and what was left was a one-line refusal. That answers how to upgrade and
6
+ // not what upgrading would bring, and the second half had no answer anywhere
7
+ // a coding agent could reach: the update notice exists
8
+ // (lib/update-notice.mjs) but prints only when stderr is a terminal, which an
9
+ // agent never has.
10
+ //
11
+ // So `vatio changelog` answers it, and `vatio update` keeps being the refusal
12
+ // -- pointed here now. This updates nothing either: it says what npm would
13
+ // bring, and what to run.
14
+
15
+ import { VERSION } from "./version.mjs";
16
+ import { clientHeaders } from "./telemetry.mjs";
17
+
18
+ export const PACKAGE = "@vatio-ai/cli";
19
+ export const CHANGELOG_URL = "https://vatio.ai/docs/changelog";
20
+ const CHANGELOG_MARKDOWN = "/docs/changelog.md";
21
+ const FETCH_TIMEOUT_MS = 10_000;
22
+ const LATEST_URL = `https://registry.npmjs.org/${PACKAGE}/latest`;
23
+
24
+ // `## 0.98.0 — 2026-10-22` opens an entry; the next one of these ends it.
25
+ const ENTRY = /^## +(\d+\.\d+\.\d+)\b.*$/gm;
26
+ // Each change in an entry opens with its own sentence in bold.
27
+ const HEADLINE = /^\*\*(.+?)\*\*/gms;
28
+
29
+ export function compareVersions(a, b) {
30
+ const parse = (value) => /^(\d+)\.(\d+)\.(\d+)$/.exec(String(value))?.slice(1).map(Number);
31
+ const left = parse(a);
32
+ const right = parse(b);
33
+ if (!left || !right) return null;
34
+ for (let i = 0; i < 3; i += 1) {
35
+ if (left[i] !== right[i]) return left[i] > right[i] ? 1 : -1;
36
+ }
37
+ return 0;
38
+ }
39
+
40
+ // The entries of the changelog, newest first: { version, body }.
41
+ export function entriesIn(markdown) {
42
+ const text = String(markdown);
43
+ const starts = [...text.matchAll(ENTRY)];
44
+
45
+ return starts.map((match, index) => ({
46
+ version: match[1],
47
+ body: text.slice(match.index + match[0].length, starts[index + 1]?.index ?? text.length).trim()
48
+ }));
49
+ }
50
+
51
+ // The headline of each change in one entry: the bold sentence it opens with,
52
+ // without its trailing period, and the whole first line when an entry has no
53
+ // bold lead at all.
54
+ export function headlinesIn(body) {
55
+ const found = [...String(body).matchAll(HEADLINE)]
56
+ .map((match) => match[1].replace(/\s+/g, " ").trim().replace(/\.$/, ""))
57
+ .filter((line) => line !== "");
58
+ if (found.length > 0) return found;
59
+
60
+ const first = String(body).split("\n").find((line) => line.trim() !== "");
61
+ return first ? [first.replace(/\s+/g, " ").trim().replace(/\.$/, "")] : [];
62
+ }
63
+
64
+ // Entries newer than `current` and no newer than `latest`, newest first. An
65
+ // unparseable version on either side means "say nothing" rather than "say
66
+ // everything": a wrong list is worse than a link.
67
+ export function changesBetween(markdown, { current, latest }) {
68
+ return entriesIn(markdown).filter(({ version }) => {
69
+ const aboveCurrent = compareVersions(version, current);
70
+ if (aboveCurrent === null || aboveCurrent <= 0) return false;
71
+ if (!latest) return true;
72
+
73
+ const withinLatest = compareVersions(version, latest);
74
+ return withinLatest !== null && withinLatest <= 0;
75
+ });
76
+ }
77
+
78
+ async function fetchText(url, accept) {
79
+ try {
80
+ const response = await fetch(url, {
81
+ headers: { ...clientHeaders(), Accept: accept },
82
+ signal: AbortSignal.timeout(FETCH_TIMEOUT_MS)
83
+ });
84
+ if (!response.ok) return null;
85
+ return await response.text();
86
+ } catch {
87
+ // No network, a slow render, an offline developer: the command still says
88
+ // which version is installed and what to run.
89
+ return null;
90
+ }
91
+ }
92
+
93
+ async function latestRelease() {
94
+ const body = await fetchText(LATEST_URL, "application/json");
95
+ if (body === null) return null;
96
+ try {
97
+ const version = JSON.parse(body)?.version;
98
+ return typeof version === "string" && compareVersions(version, "0.0.0") !== null ? version : null;
99
+ } catch {
100
+ return null;
101
+ }
102
+ }
103
+
104
+ // How to get the current release, in the form that fits how this one is being
105
+ // run: npx sets npm_command=exec, a global install has no npm around it.
106
+ export function upgradeCommand() {
107
+ return process.env.npm_command === "exec" ? `npx ${PACKAGE}@latest` : `npm install -g ${PACKAGE}@latest`;
108
+ }
109
+
110
+ // `vatio changelog`. Updates nothing, and says so first: npm owns that, and a
111
+ // command that printed "updated" without having updated would be worse than
112
+ // the refusal this replaces.
113
+ export async function changelog(config, args = []) {
114
+ const full = args.includes("--full");
115
+ const lines = [];
116
+
117
+ const [latest, markdown] = await Promise.all([
118
+ latestRelease(),
119
+ fetchText(`${config.resolveBaseUrl()}${CHANGELOG_MARKDOWN}`, "text/markdown, text/plain")
120
+ ]);
121
+
122
+ const behind = latest !== null && compareVersions(latest, VERSION) === 1;
123
+ if (latest === null) {
124
+ lines.push(`vatio ${VERSION} is installed. The registry could not be reached, so whether it is current is unknown.`);
125
+ } else if (behind) {
126
+ lines.push(`vatio ${VERSION} is installed; ${latest} is the current release.`);
127
+ } else {
128
+ lines.push(`vatio ${VERSION} is installed, and it is the current release.`);
129
+ }
130
+
131
+ lines.push("");
132
+ if (behind || latest === null) {
133
+ lines.push("Nothing was updated here — npm does that:");
134
+ lines.push(` ${upgradeCommand()}`);
135
+ lines.push("");
136
+ }
137
+
138
+ const changes = markdown === null ? [] : changesBetween(markdown, { current: VERSION, latest });
139
+ if (changes.length > 0) {
140
+ lines.push(`What ${changes.length === 1 ? "the release" : "those releases"} changed:`);
141
+ lines.push("");
142
+ for (const entry of changes) {
143
+ lines.push(` ${entry.version}`);
144
+ if (full) {
145
+ for (const line of entry.body.split("\n")) lines.push(line === "" ? "" : ` ${line}`);
146
+ lines.push("");
147
+ } else {
148
+ for (const headline of headlinesIn(entry.body)) lines.push(` ${headline}`);
149
+ }
150
+ }
151
+ lines.push("");
152
+ lines.push(full ? `In a browser: ${CHANGELOG_URL}` : `Each one in full: \`vatio changelog --full\`, or ${CHANGELOG_URL}`);
153
+ } else if (markdown === null) {
154
+ lines.push(`What changed is in the changelog: ${CHANGELOG_URL}`);
155
+ } else if (!behind) {
156
+ lines.push(`Earlier releases are in the changelog: ${CHANGELOG_URL}`);
157
+ }
158
+
159
+ console.log(lines.join("\n"));
160
+ }
@@ -14,6 +14,7 @@ import { spawnSync } from "node:child_process";
14
14
 
15
15
  import { consumedStdin } from "./support.mjs";
16
16
  import { VERSION } from "./version.mjs";
17
+ import { CHANGELOG_URL } from "./release-notes.mjs";
17
18
 
18
19
  const RAN_LATEST = "VATIO_CLI_RAN_LATEST";
19
20
 
@@ -25,6 +26,11 @@ export function runLatest(error, argv) {
25
26
  `vatio: ${VERSION} is not the current release, so this runs ${latest} through npx. ` +
26
27
  "`npm install -g @vatio-ai/cli@latest` installs it."
27
28
  );
29
+ // The one place a coding agent crosses a version boundary: the update
30
+ // notice prints only to a terminal, and an agent has none, so this was the
31
+ // whole of what it ever learned about a new release. What changed is a
32
+ // command away now.
33
+ console.error(`vatio: what changed between them: \`vatio changelog\` (or ${CHANGELOG_URL}).`);
28
34
  const input = consumedStdin();
29
35
  const child = spawnSync("npx", ["--yes", `@vatio-ai/cli@${latest}`, ...argv.slice(2)], {
30
36
  stdio: input === null ? "inherit" : ["pipe", "inherit", "inherit"],
@@ -0,0 +1,256 @@
1
+ // What the CLI says when the first argument is not a command.
2
+ //
3
+ // It used to print `Unknown command: X` and the whole help, and the telemetry
4
+ // says that ended the session: of 31 sessions that hit
5
+ // `Unknown command: @vatio-ai/cli`, none ran another command afterwards. A
6
+ // coding agent reading a wall of help text does not find its mistake in it;
7
+ // it needs the one line that says what to run instead.
8
+ //
9
+ // Three kinds of mistake get named rather than guessed at:
10
+ //
11
+ // - The way the CLI is started used as a command: `@vatio-ai/cli`, `npx`,
12
+ // `vatio`. `npx @vatio-ai/cli @vatio-ai/cli push` is the shape the
13
+ // telemetry shows, and the package name is the most abandoned error in
14
+ // the whole dataset.
15
+ // - A subcommand without its command: `show` is `vatio chat show` or
16
+ // `vatio kb show`, and on its own it is neither.
17
+ // - A message without `chat`: `vatio "do you deliver?"` is a sentence
18
+ // somebody meant to say to their agent.
19
+ //
20
+ // Anything left is matched by edit distance, which catches the ordinary typo
21
+ // (`puhs`, `publsh`) and declines to guess when nothing is close.
22
+
23
+ // Every command the dispatch in bin/vatio.mjs answers. Kept here rather than
24
+ // read out of that switch so the suggestion works without parsing source at
25
+ // runtime; scripts/check-docs.mjs fails the build when the two drift apart,
26
+ // which is what keeps this honest.
27
+ export const COMMANDS = [
28
+ "auth",
29
+ "business",
30
+ "changelog",
31
+ "chat",
32
+ "config",
33
+ "diff",
34
+ "docs",
35
+ "doctor",
36
+ "env",
37
+ "eval",
38
+ "feedback",
39
+ "flags",
40
+ "init",
41
+ "instagram",
42
+ "kb",
43
+ "keys",
44
+ "login",
45
+ "logout",
46
+ "messages",
47
+ "publish",
48
+ "pull",
49
+ "push",
50
+ "quiet-hours",
51
+ "rollback",
52
+ "routines",
53
+ "secrets",
54
+ "share-session",
55
+ "status",
56
+ "templates",
57
+ "test",
58
+ "tokens",
59
+ "tools",
60
+ "version",
61
+ "webhooks",
62
+ "whatsapp",
63
+ "whoami"
64
+ ];
65
+
66
+ // Words that only mean something after a command. A token that is one of
67
+ // these is a dropped command, not a typo, so it is answered with the commands
68
+ // it belongs to instead of by edit distance.
69
+ //
70
+ // Only subcommands that are not also commands in their own right: `test`,
71
+ // `publish`, `status` and `rollback` are dispatched before this is reached, so
72
+ // listing them here would be dead. scripts/check-docs.mjs checks the command
73
+ // names on the right against the dispatch.
74
+ const SUBCOMMAND_OF = {
75
+ add: ["flags", "test"],
76
+ cat: ["kb"],
77
+ create: ["kb", "tokens", "keys", "templates", "webhooks", "routines"],
78
+ deliveries: ["webhooks"],
79
+ enable: ["webhooks", "routines"],
80
+ export: ["chat"],
81
+ failed: ["messages"],
82
+ follow: ["kb"],
83
+ get: ["config"],
84
+ history: ["kb"],
85
+ list: ["env", "kb", "secrets", "tokens", "keys", "templates", "webhooks", "routines", "test"],
86
+ off: ["quiet-hours"],
87
+ origins: ["tokens"],
88
+ refresh: ["kb"],
89
+ remove: ["secrets", "webhooks", "routines", "flags", "test"],
90
+ revoke: ["tokens", "keys"],
91
+ rm: ["env", "kb", "secrets", "webhooks", "routines", "flags", "test"],
92
+ "rm-entry": ["kb"],
93
+ runs: ["routines"],
94
+ set: ["business", "quiet-hours", "secrets", "config"],
95
+ show: ["chat", "kb", "business", "quiet-hours", "config"],
96
+ unfollow: ["kb"],
97
+ unset: ["config"],
98
+ update: ["routines"],
99
+ write: ["kb"]
100
+ };
101
+
102
+ // Exported so scripts/check-docs.mjs can check every command named above is
103
+ // one the CLI actually dispatches.
104
+ export const SUBCOMMAND_OWNERS = [...new Set(Object.values(SUBCOMMAND_OF).flat())];
105
+
106
+ // How the CLI is started. None of them is a command, and all of them turn up
107
+ // as one when a wrapper is pasted twice.
108
+ const STARTERS = new Set(["npx", "npm", "node", "vatio", "@vatio-ai/cli", "cli", "--yes", "-y", "exec"]);
109
+
110
+ const PACKAGE_NAME = /^@vatio-ai\/cli(@[\w.^~-]+)?$/;
111
+
112
+ // A first argument that is a sentence rather than a word: what somebody meant
113
+ // to say to their agent, with `chat` left out.
114
+ function looksLikeMessage(token) {
115
+ return /\s/.test(token) || /[?¿!¡]$/.test(token) || token.split(/\s+/).length > 1;
116
+ }
117
+
118
+ // Optimal string alignment: a substitution, an insertion, a deletion or a
119
+ // swap of two adjacent characters each cost one. The swap matters -- `puhs`
120
+ // for `push` is the commonest typo there is, and plain Levenshtein scores it
121
+ // as two mistakes and then declines to guess.
122
+ function editDistance(a, b) {
123
+ if (a === b) return 0;
124
+
125
+ const rows = a.length + 1;
126
+ const cols = b.length + 1;
127
+ const grid = Array.from({ length: rows }, () => new Array(cols).fill(0));
128
+
129
+ for (let row = 0; row < rows; row += 1) grid[row][0] = row;
130
+ for (let col = 0; col < cols; col += 1) grid[0][col] = col;
131
+
132
+ for (let row = 1; row < rows; row += 1) {
133
+ for (let col = 1; col < cols; col += 1) {
134
+ const cost = a[row - 1] === b[col - 1] ? 0 : 1;
135
+ grid[row][col] = Math.min(
136
+ grid[row - 1][col] + 1,
137
+ grid[row][col - 1] + 1,
138
+ grid[row - 1][col - 1] + cost
139
+ );
140
+ if (row > 1 && col > 1 && a[row - 1] === b[col - 2] && a[row - 2] === b[col - 1]) {
141
+ grid[row][col] = Math.min(grid[row][col], grid[row - 2][col - 2] + 1);
142
+ }
143
+ }
144
+ }
145
+ return grid[a.length][b.length];
146
+ }
147
+
148
+ // How far off a token may be and still be called a typo: a third of its
149
+ // length, so short names are not matched to each other (`env` to `eval`) and
150
+ // long ones tolerate the two-character slip (`quiet-hour`, `share-sesion`).
151
+ function tolerance(token) {
152
+ return token.length <= 4 ? 1 : Math.max(1, Math.floor(token.length / 3));
153
+ }
154
+
155
+ // The commands a token could be, nearest first. Exported for the help text
156
+ // and for anything else that wants to be forgiving about a name.
157
+ export function nearestCommands(token, { limit = 3 } = {}) {
158
+ const needle = String(token).toLowerCase();
159
+ if (needle === "") return [];
160
+
161
+ const scored = COMMANDS.map((command) => {
162
+ if (command.startsWith(needle) || needle.startsWith(command)) return { command, score: 0 };
163
+ if (command.includes(needle) && needle.length >= 3) return { command, score: 1 };
164
+ return { command, score: editDistance(needle, command) + 1 };
165
+ })
166
+ .filter(({ score }) => score <= tolerance(needle) + 1)
167
+ .sort((a, b) => a.score - b.score || a.command.localeCompare(b.command));
168
+
169
+ if (scored.length === 0) return [];
170
+
171
+ // Only the closest, and the others only when they are exactly as close.
172
+ // `publsh` is one edit from `publish` and two from `push`, so offering both
173
+ // would make the reader choose between a match and a near miss.
174
+ const best = scored[0].score;
175
+ return scored.filter(({ score }) => score === best).slice(0, limit).map(({ command }) => command);
176
+ }
177
+
178
+ // The whole message for a first argument that is not a command: what went
179
+ // wrong, the one thing to run instead when that can be known, and where the
180
+ // rest of the surface is. Never the full help -- the reader already could not
181
+ // find the command in it.
182
+ export function unknownCommandMessage(command, args = []) {
183
+ const token = String(command);
184
+ const rest = args.filter((arg) => !STARTERS.has(arg) && !PACKAGE_NAME.test(arg));
185
+ const trailing = rest.length > 0 ? ` ${rest.join(" ")}` : "";
186
+
187
+ // The starter can arrive as the whole invocation in one argument, when a
188
+ // generated command line was quoted: `vatio "@vatio-ai/cli push"`. Read the
189
+ // first word, and carry the remaining words over as the command.
190
+ const words = token.split(/\s+/).filter(Boolean);
191
+ const head = words[0] ?? "";
192
+ if (PACKAGE_NAME.test(head) || STARTERS.has(head)) {
193
+ const carried = words.slice(1).filter((word) => !STARTERS.has(word) && !PACKAGE_NAME.test(word));
194
+ const after = [...carried, ...rest].join(" ");
195
+ return [
196
+ `\`${head}\` is how the CLI is started, not a command it takes.`,
197
+ "",
198
+ `Run: vatio${after === "" ? " push" : ` ${after}`}`,
199
+ "",
200
+ "Installed globally the command is `vatio`; through npx the whole invocation is",
201
+ "`npx @vatio-ai/cli ARGS` and the package name is not repeated.",
202
+ "",
203
+ "`vatio help` lists every command."
204
+ ].join("\n");
205
+ }
206
+
207
+ if (looksLikeMessage(token)) {
208
+ return [
209
+ `\`${token}\` is not a command. To say it to your agent, \`chat\` takes the message:`,
210
+ "",
211
+ `Run: vatio chat ${JSON.stringify(token)}`,
212
+ "",
213
+ "`vatio help` lists every command."
214
+ ].join("\n");
215
+ }
216
+
217
+ const belongsTo = SUBCOMMAND_OF[token.toLowerCase()];
218
+ if (belongsTo) {
219
+ const options = belongsTo.map((owner) => `vatio ${owner} ${token}${trailing}`);
220
+ return [
221
+ `\`${token}\` is a subcommand, so it needs the command it belongs to:`,
222
+ "",
223
+ ...options.map((option) => ` ${option}`),
224
+ "",
225
+ "`vatio help` lists every command."
226
+ ].join("\n");
227
+ }
228
+
229
+ const near = nearestCommands(token);
230
+ if (near.length === 1) {
231
+ return [
232
+ `Unknown command: ${token}. The closest is \`${near[0]}\`.`,
233
+ "",
234
+ `Run: vatio ${near[0]}${trailing}`,
235
+ "",
236
+ "`vatio help` lists every command."
237
+ ].join("\n");
238
+ }
239
+ if (near.length > 1) {
240
+ return [
241
+ `Unknown command: ${token}. Did you mean one of these?`,
242
+ "",
243
+ ...near.map((option) => ` vatio ${option}${trailing}`),
244
+ "",
245
+ "`vatio help` lists every command."
246
+ ].join("\n");
247
+ }
248
+
249
+ return [
250
+ `Unknown command: ${token}.`,
251
+ "",
252
+ `Commands: ${COMMANDS.join(", ")}`,
253
+ "",
254
+ "`vatio help` explains each one, and `vatio docs` prints the whole contract."
255
+ ].join("\n");
256
+ }
@@ -44,6 +44,7 @@ export async function printUpdateNotice(check) {
44
44
  process.stderr.write(
45
45
  `\n${paint("yellow", `A new release of vatio is available: ${VERSION} → ${latest}`)}\n` +
46
46
  `To upgrade, run: ${upgrade}\n` +
47
+ `What it changed: vatio changelog\n` +
47
48
  `${paint("cyan", "https://vatio.ai/docs/changelog")}\n`
48
49
  );
49
50
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vatio-ai/cli",
3
- "version": "0.98.0",
3
+ "version": "0.99.0",
4
4
  "description": "Vatio CLI — deploy and manage Vatio agent workspaces",
5
5
  "keywords": [
6
6
  "vatio",