@vatio-ai/cli 0.37.2

package/lib/commands/mcp.mjs

@@ -0,0 +1,307 @@
+// `vatio mcp` — the same CLI, spoken as Model Context Protocol over stdio, so a
+// coding agent drives the commands a developer would instead of writing its own
+// client for the API.
+//
+// It wraps the CLI rather than the API on purpose: what the agent reads is
+// exactly what the developer would have seen, including the advice at the end
+// of a failure. Every command gets a decision recorded in one of two tables --
+// COMMANDS (offered) or WITHHELD (deliberately not) -- and the default for a
+// command nobody thought about is "not offered".
+
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { createInterface } from "node:readline";
+import { dirname, join } from "node:path";
+
+import { VERSION } from "../version.mjs";
+
+const PROTOCOL_VERSIONS = ["2025-06-18", "2025-03-26", "2024-11-05"];
+const MAX_OUTPUT = 20_000;
+const TIMEOUT_MS = 180_000;
+
+const COMMANDS = {
+  docs: {
+    usage: "[--save [PATH]]",
+    summary:
+      "The Vatio developer contract as markdown, live from the platform: vatio.yml, tools, auth, " +
+      "visitor identity, knowledge, channels, the tool result shape, the whole CLI and API. Read " +
+      "this before writing or changing anything in a workspace.",
+    auth: false,
+    annotations: { readOnlyHint: true, openWorldHint: true }
+  },
+  doctor: {
+    usage: "",
+    summary:
+      "Node, config, workspace and token status. Run this when a command fails for a reason that " +
+      "does not look like the workspace itself.",
+    auth: false,
+    annotations: { readOnlyHint: true }
+  },
+  tools: {
+    usage: "check",
+    summary:
+      "`tools check` sends the workspace to Vatio and validates it against the contracts there — " +
+      "manifest shape, tool specs, handler signatures — without deploying anything. The fastest " +
+      "way to find out whether an edit is deployable; push runs the same check anyway.",
+    annotations: { readOnlyHint: true }
+  },
+  status: {
+    usage: "",
+    summary: "Preview and live deployment state for this workspace.",
+    annotations: { readOnlyHint: true }
+  },
+  diff: {
+    usage: "[--env NAME] [--stat|--name-only|--format json|--full]",
+    summary:
+      "What this directory would change against a deployment — preview by default. `--env live` " +
+      "answers \"what would publishing change?\" without publishing.",
+    annotations: { readOnlyHint: true }
+  },
+  push: {
+    usage: "[--env NAME]",
+    summary:
+      "Validate the workspace and update a preview deployment. Never touches live. `--env NAME` " +
+      "lands it on its own named preview (one per pull request) instead of the default one.",
+    annotations: { readOnlyHint: false }
+  },
+  publish: {
+    usage: "[--env NAME]",
+    summary:
+      "Promote a preview to live, which is what customers see. Ask the developer first: this is " +
+      "the one step that changes what real visitors get.",
+    annotations: { readOnlyHint: false, destructiveHint: true }
+  },
+  rollback: {
+    usage: "",
+    summary: "Restore the previous live deployment. Same weight as publish — ask first.",
+    annotations: { readOnlyHint: false, destructiveHint: true }
+  },
+  chat: {
+    usage: '"message" | transcript | debug | reset [--env NAME]',
+    summary:
+      "Talk to the deployed agent as the developer holding the token, and read the transcript. " +
+      "`debug` shows the developer view, including tool calls. `--env live` is a real conversation " +
+      "that appears in the inbox.",
+    annotations: { readOnlyHint: false }
+  },
+  secrets: {
+    usage: "list | set KEY VALUE | rm KEY",
+    summary:
+      "Credentials the workspace's JS tools read as ctx.env. Values are write-only — listing shows " +
+      "keys, never values.",
+    annotations: { readOnlyHint: false }
+  },
+  kb: {
+    usage: "[list] | show NAME | create NAME | add-source BASE NAME URL | upload BASE FILE... | reindex BASE",
+    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.",
+    annotations: { readOnlyHint: false, openWorldHint: true }
+  },
+  tokens: {
+    usage: "list | create [--env NAME] [--label NAME] | revoke PREFIX",
+    summary:
+      "Publishable tokens for the widget and anything built on the SDK. A created token is shown in " +
+      "full exactly once.",
+    annotations: { readOnlyHint: false }
+  },
+  widget: {
+    usage: "[--env NAME]",
+    summary:
+      "What the platform will actually enforce for the widget, the origin allowlist, and the tokens " +
+      "that exist. Read-only: vatio.yml owns every field, so push is what changes it.",
+    annotations: { readOnlyHint: true }
+  },
+  whatsapp: {
+    usage: "[status] | check | activate | deactivate | numbers [list | add PHONE | verify PHONE CODE]",
+    summary:
+      "The workspace's own WhatsApp number, which serves live: whether it is connected, whether Meta " +
+      "delivers to it, and whether it is answering — three things that fail separately. `numbers` is " +
+      "the other thing: the shared WhatsApp preview, test phones that reach preview and need no Meta " +
+      "account. A code goes to the handset, so a human has to read it back to you.",
+    annotations: { readOnlyHint: false, openWorldHint: true }
+  },
+  instagram: {
+    usage: "[status] | check | accounts [list | add @HANDLE | verify CODE]",
+    summary:
+      "The workspace's own Instagram account, which serves live, and the shared Instagram preview " +
+      "under `accounts`. Registering a test account goes handle first, then the developer DMs the " +
+      "preview account from it and Vatio replies with a code. `instagram connect` is not here — it " +
+      "needs Meta's consent screen in a browser.",
+    annotations: { readOnlyHint: false, openWorldHint: true }
+  }
+};
+
+// Named rather than merely absent, so the reason travels with the refusal.
+const WITHHELD = {
+  login: "needs a browser and a person approving a code",
+  logout: "would take the developer's credential away from them",
+  init: "creates a remote workspace; the developer decides that one",
+  issue: "writes to a human's inbox in the developer's name",
+  config: "edits the developer's own credentials file",
+  version: "nothing an agent needs; `doctor` says more",
+  help: "the tool list is this",
+  mcp: "this"
+};
+
+const BLOCKED_SUBCOMMANDS = {
+  chat: { destroy: "destroys a conversation; ask the developer" },
+  kb: { rm: "deletes an indexed base; ask the developer" },
+  whatsapp: { connect: "takes Meta credentials the developer holds", disconnect: "ask the developer" },
+  instagram: { connect: "needs Meta's consent screen in a browser", disconnect: "ask the developer" }
+};
+
+const toolName = (command) => `vatio_${command}`;
+
+export async function mcp(config) {
+  const cliPath = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "bin", "vatio.mjs");
+  const reader = createInterface({ input: process.stdin, crlfDelay: Infinity });
+
+  for await (const line of reader) {
+    if (line.trim() === "") continue;
+
+    let message;
+    try {
+      message = JSON.parse(line);
+    } catch {
+      continue;
+    }
+
+    const response = await handle(message, { config, cliPath });
+    // A notification has no id and gets no reply, which is the whole of the
+    // difference between the two in JSON-RPC.
+    if (response) process.stdout.write(`${JSON.stringify(response)}\n`);
+  }
+}
+
+async function handle(message, context) {
+  const id = message.id;
+  if (id === undefined || id === null) return null;
+
+  const reply = (result) => ({ jsonrpc: "2.0", id, result });
+
+  switch (message.method) {
+    case "initialize":
+      return reply(initializeResult(message.params));
+    case "ping":
+      return reply({});
+    case "tools/list":
+      return reply({ tools: toolDefinitions() });
+    case "tools/call":
+      return reply(await callTool(message.params ?? {}, context));
+    default:
+      return { jsonrpc: "2.0", id, error: { code: -32601, message: `Unknown method: ${message.method}` } };
+  }
+}
+
+function initializeResult(params) {
+  const requested = params?.protocolVersion;
+  const version = PROTOCOL_VERSIONS.includes(requested) ? requested : PROTOCOL_VERSIONS[0];
+
+  return {
+    protocolVersion: version,
+    capabilities: { tools: { listChanged: false } },
+    serverInfo: { name: "vatio", version: VERSION },
+    instructions: [
+      "These tools run the Vatio CLI. A workspace is any directory holding a vatio.yml, and that",
+      "directory decides which remote it deploys to — there is no workspace flag. Pass workspace_dir",
+      "when the workspace is not the directory this server started in.",
+      "",
+      "Start with vatio_docs: it is the contract for vatio.yml, tools, auth, visitor identity and",
+      "knowledge, fetched live from the platform, so it is what the platform actually accepts.",
+      "",
+      "The loop is: edit files, vatio_push (preview only), vatio_chat to read the agent's answer,",
+      "vatio_publish when the developer says so. Nothing a customer sees changes until publish.",
+      "",
+      "Anything that needs a browser or a person — login, issue, instagram connect — is not here;",
+      "ask the developer to run it in their terminal."
+    ].join("\n")
+  };
+}
+
+function toolDefinitions() {
+  return Object.entries(COMMANDS).map(([command, spec]) => ({
+    name: toolName(command),
+    description: `${spec.summary}\n\nUsage: ${usageLine(command, spec)}`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        args: { type: "array", items: { type: "string" }, description: `Arguments after \`vatio ${command}\`` },
+        workspace_dir: { type: "string", description: "Directory holding vatio.yml; defaults to the cwd" }
+      },
+      required: []
+    },
+    annotations: spec.annotations ?? {}
+  }));
+}
+
+function usageLine(command, spec) {
+  return spec.usage ? `vatio ${command} ${spec.usage}` : `vatio ${command}`;
+}
+
+async function callTool(params, { config, cliPath }) {
+  const name = params.name;
+  const command = Object.keys(COMMANDS).find((key) => toolName(key) === name);
+  if (!command) {
+    const withheld = Object.keys(WITHHELD).find((key) => toolName(key) === name);
+    if (withheld) return errorResult(`\`vatio ${withheld}\` is not offered here: ${WITHHELD[withheld]}.`);
+    return errorResult(`Unknown tool ${name}. Offered: ${Object.keys(COMMANDS).map(toolName).join(", ")}`);
+  }
+
+  const args = Array.isArray(params.arguments?.args) ? params.arguments.args.map(String) : [];
+  const blocked = BLOCKED_SUBCOMMANDS[command]?.[args[0]];
+  if (blocked) return errorResult(`\`vatio ${command} ${args[0]}\` is not offered here: ${blocked}.`);
+
+  if (COMMANDS[command].auth !== false && !config.resolveToken()) {
+    return errorResult(
+      "Not logged in: no token in VATIO_TOKEN or ~/.vatio/config.json. Ask the developer to run " +
+        "`vatio login` in their terminal — the device authorization needs a browser — and this " +
+        "server picks the token up from there."
+    );
+  }
+
+  const dir = params.arguments?.workspace_dir ?? process.cwd();
+  const { stdout, stderr, code, timedOut } = await run(cliPath, [command, ...args], dir);
+
+  if (timedOut) return errorResult(`\`vatio ${command}\` did not finish within ${TIMEOUT_MS / 1000}s.`);
+
+  const body = [stdout, stderr].map((part) => part.trim()).filter(Boolean).join("\n");
+  if (code !== 0) return errorResult(`${body}\n\n\`vatio ${command}\` exited ${code}.`.trim());
+  return { content: [{ type: "text", text: truncate(body) }], isError: false };
+}
+
+function run(cliPath, args, cwd) {
+  return new Promise((resolvePromise) => {
+    const child = spawn(process.execPath, [cliPath, ...args], { cwd, stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill("SIGKILL");
+    }, TIMEOUT_MS);
+
+    child.stdout.on("data", (chunk) => { stdout += chunk; });
+    child.stderr.on("data", (chunk) => { stderr += chunk; });
+    child.on("error", (error) => {
+      clearTimeout(timer);
+      resolvePromise({ stdout, stderr: String(error.message), code: 1, timedOut });
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      resolvePromise({ stdout, stderr, code: code ?? 1, timedOut });
+    });
+  });
+}
+
+// A failure is a tool result, not a protocol error: exiting or raising would
+// take the whole session down over one bad push.
+function errorResult(message) {
+  return { content: [{ type: "text", text: truncate(message) }], isError: true };
+}
+
+function truncate(text) {
+  const value = String(text ?? "");
+  return value.length <= MAX_OUTPUT ? value : `${value.slice(0, MAX_OUTPUT - 3)}...`;
+}

package/lib/commands/misc.mjs

@@ -0,0 +1,148 @@
+// version / doctor / config / init.
+
+import { existsSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { stringify as stringifyYaml } from "yaml";
+
+import { KEYS, SLUG_FORMAT } from "../config.mjs";
+import { MANIFEST_FILE, manifestPath } from "../workspace.mjs";
+import { VERSION } from "../version.mjs";
+import { fail, takeValue } from "../support.mjs";
+import { deviceLogin } from "./auth.mjs";
+import { workspacesClient } from "./deploy.mjs";
+
+export const DOCS_URL = "https://vatio.ai/docs";
+
+export function version() {
+  console.log(`Vatio CLI ${VERSION} (node)`);
+  console.log(`Node ${process.version} (${process.platform}-${process.arch})`);
+}
+
+// What to read when a command fails for a reason that does not look like the
+// workspace itself.
+export function doctor(config) {
+  version();
+  console.log(`CLI executable: ${process.argv[1]}`);
+  console.log(`Node executable: ${process.execPath}`);
+  console.log(`Base URL: ${config.resolveBaseUrl()}`);
+  console.log(
+    `Config: ${config.configPath}${existsSync(config.configPath) ? "" : " (missing — run `vatio login`)"}`
+  );
+  console.log(`Workspace root: ${config.workspaceRoot ?? "(none — no vatio.yml at or above the cwd)"}`);
+  const manifest = config.manifestPath();
+  if (manifest) console.log(`Manifest: ${manifest}`);
+  let slug = null;
+  try {
+    slug = config.resolveWorkspace();
+  } catch (error) {
+    console.log(`Workspace: unreadable — ${error.message}`);
+  }
+  if (slug) console.log(`Workspace: ${slug}`);
+  console.log(`Token: ${config.resolveToken() ? "configured" : "missing — run `vatio login`"}`);
+  console.log(`Docs: ${DOCS_URL}`);
+}
+
+export function configCommand(config, args) {
+  const sub = args.shift();
+
+  if (sub === "show" || sub === undefined) {
+    const shown = config.displayHash();
+    if (Object.keys(shown).length === 0) {
+      console.log(`No config in ${config.configPath}`);
+      return;
+    }
+    for (const [key, value] of Object.entries(shown)) console.log(`${key}=${value}`);
+    return;
+  }
+  if (sub === "get") {
+    const value = config.get(requireArg(args, "config get KEY"));
+    if (value) console.log(value);
+    return;
+  }
+  if (sub === "set") {
+    const key = requireArg(args, "config set KEY VALUE");
+    const value = requireArg(args, "config set KEY VALUE");
+    config.set(key, value);
+    console.log(`Set ${key}`);
+    return;
+  }
+  if (sub === "unset") {
+    const key = requireArg(args, "config unset KEY");
+    config.unset(key);
+    console.log(`Unset ${key}`);
+    return;
+  }
+
+  fail(`Unknown config command: ${sub}\n\nKeys: ${KEYS.join(", ")}`);
+}
+
+// `vatio init` writes the one file that makes a directory a workspace, and
+// names the remote it deploys to. Nothing constrains where that directory is --
+// the point of the file is that an agent can live inside the repository of the
+// backend it calls, not in a separate folder of agents.
+export async function init(config, args) {
+  const baseUrl = takeValue(args, "--base-url");
+  const name = takeValue(args, "--name");
+
+  const target = process.cwd();
+  const existing = manifestPath(target);
+  if (existing) fail(`Already a workspace: ${existing}`);
+
+  // A workspace inside a workspace would shadow the outer one for every command
+  // run below it, and no deploy would ever include it.
+  if (config.workspaceRoot) {
+    fail(`${target} is already inside the workspace at ${config.workspaceRoot}.\nRun \`vatio init\` somewhere outside it.`);
+  }
+
+  let slug = String(args.shift() ?? "").trim().toLowerCase();
+  if (slug === "") slug = config.suggestedSlug();
+  if (!SLUG_FORMAT.test(slug)) {
+    fail(`Invalid slug "${slug}" (use lowercase letters, numbers, hyphens)`);
+  }
+
+  // Logging in first means the remote is created against a base_url the
+  // developer has actually authorized, and a fresh machine gets through
+  // `vatio init` in one command instead of two.
+  if (!config.resolveToken()) {
+    const auth = await deviceLogin({ baseUrl, message: "Starting device authorization for Vatio CLI…" });
+    config.writeAuth({ baseUrl: auth.baseUrl, token: auth.token });
+    console.log(`Token saved to ${config.configPath}`);
+    console.log("");
+  }
+
+  const clients = workspacesClient(config);
+  const created = !(await clients.workspaceExists(slug));
+  if (created) await clients.createWorkspace({ slug, name });
+
+  const manifest = join(target, MANIFEST_FILE);
+  writeFileSync(manifest, starterManifest(slug, name));
+
+  console.log(`${created ? "Created" : "Linked"} remote workspace ${slug}`);
+  console.log(`Wrote ${manifest}`);
+  console.log("");
+  console.log("Next:");
+  console.log(`  edit ${MANIFEST_FILE}, then \`vatio push\` and \`vatio publish\``);
+  console.log(`  docs: ${DOCS_URL}`);
+}
+
+// The smallest file that deploys: which workspace, and what the agent does.
+// The slug is already validated as a slug, so it needs no quoting; a display
+// name is whatever the developer typed, so it goes through the YAML emitter.
+function starterManifest(slug, name) {
+  const lines = ["# Which Vatio workspace this directory deploys to.", `workspace: ${slug}`, ""];
+  if (String(name ?? "").trim() !== "") {
+    lines.push(stringifyYaml({ business: { name: String(name).trim() } }).trimEnd());
+    lines.push("");
+  }
+  lines.push("agent:");
+  lines.push("  instructions: |");
+  lines.push("    Describe what this agent does and how it should answer.");
+  lines.push("");
+  return lines.join("\n");
+}
+
+function requireArg(args, usage) {
+  const value = args.shift();
+  if (value === undefined) fail(`Usage: vatio ${usage}`);
+  return value;
+}

package/lib/commands/support-commands.mjs

@@ -0,0 +1,147 @@
+// docs / issue — the two commands that are about Vatio rather than about a
+// deployment.
+
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+
+import { HttpClient } from "../http.mjs";
+import { VERSION } from "../version.mjs";
+import { fail, takeFlag, takeValue } from "../support.mjs";
+import { DOCS_URL } from "./misc.mjs";
+
+// The whole developer contract as markdown, live from the platform. Fetched
+// rather than bundled: the docs describe the deploy you are talking to, and a
+// copy shipped inside this package would start lying the day either moves.
+export async function docs(config, args) {
+  const save = takeFlag(args, "--save");
+  const savePath = takeValue(args, "--save-to") ?? (save ? args.shift() ?? null : null);
+
+  const baseUrl = config.resolveBaseUrl();
+  let markdown;
+  try {
+    const response = await fetch(`${baseUrl}/docs.md`, {
+      headers: { Accept: "text/markdown, text/plain" },
+      signal: AbortSignal.timeout(30_000)
+    });
+    if (!response.ok) throw new Error(`HTTP ${response.status}`);
+    markdown = await response.text();
+  } catch (error) {
+    fail(`Could not fetch the docs: ${error.message}\nRead them at ${DOCS_URL} instead.`);
+  }
+
+  if (!save) {
+    process.stdout.write(markdown);
+    return;
+  }
+
+  const target = resolve(savePath ?? "vatio-docs.md");
+  mkdirSync(dirname(target), { recursive: true });
+  writeFileSync(target, markdown);
+  console.log(`Wrote ${target} (${markdown.split("\n").length} lines, from ${baseUrl})`);
+  console.log("Point your coding agent at it, and re-run `vatio docs --save` to refresh.");
+}
+
+function issuesClient(config) {
+  const token = config.resolveToken();
+  if (!token) fail(`Run \`vatio login\` first (no token in ${config.configPath})`);
+  return new HttpClient({ baseUrl: config.resolveBaseUrl(), token });
+}
+
+// `vatio issue` is a change worth making, written against a template the
+// platform also validates against. It is not an issue tracker: there are no
+// states, labels, assignees or backlog, and that is on purpose.
+export async function issue(config, args) {
+  const sub = args[0];
+  if (sub === "list") return await issueList(config);
+  if (sub === "show") return await issueShow(config, args[1]);
+  if (sub === "comment") return await issueComment(config, args[1], args.slice(2));
+
+  if (takeFlag(args, "--template")) return await issueTemplate(config);
+
+  const file = takeValue(args, "--file");
+  const workspace = takeValue(args, "--workspace") ?? safeWorkspace(config);
+
+  // Before anything is composed: nothing is more annoying than writing one of
+  // these and only then being told to log in.
+  const client = issuesClient(config);
+
+  const body = { cli_version: VERSION };
+  if (workspace) body.workspace = workspace;
+  if (file) {
+    body.markdown = readFileSync(file, "utf8");
+  } else {
+    const message = args.join(" ").trim();
+    if (message === "") {
+      fail(
+        "Usage: vatio issue \"what should change\"\n" +
+          "       vatio issue --file ISSUE.md\n" +
+          "       vatio issue --template   # the shape it is read against"
+      );
+    }
+    body.message = message;
+  }
+
+  const payload = await client.post("/cli/issues", body);
+  console.log(`Sent issue ${payload.id}.`);
+  if (payload.url) console.log(`  ${payload.url}`);
+  console.log("A person reads it and answers by email; `vatio issue list` shows the thread.");
+}
+
+async function issueTemplate(config) {
+  const response = await fetch(`${config.resolveBaseUrl()}/cli/issue_template`, {
+    headers: { Accept: "text/markdown, text/plain" },
+    signal: AbortSignal.timeout(30_000)
+  });
+  if (!response.ok) fail(`Could not fetch the template (HTTP ${response.status})`);
+  process.stdout.write(await response.text());
+}
+
+async function issueList(config) {
+  const payload = await issuesClient(config).get("/cli/issues");
+  const issues = Array.isArray(payload.issues) ? payload.issues : [];
+  if (issues.length === 0) {
+    console.log("You have not sent any issues yet.");
+    console.log('  Send one: vatio issue "what should change"');
+    return;
+  }
+  console.log(`Your issues (${issues.length}):`);
+  for (const row of issues) {
+    console.log(`  [${row.id}] ${row.status ?? ""}  ${row.title ?? row.summary ?? ""}`.trimEnd());
+  }
+}
+
+// The markdown view, which is the same document Vatio's own triage agent
+// reads -- the whole conversation included, so a coding agent can pick the
+// thread up where a person left it.
+async function issueShow(config, id) {
+  if (!id) fail("Usage: vatio issue show ID");
+
+  const response = await fetch(`${config.resolveBaseUrl()}/cli/issues/${encodeURIComponent(id)}.md`, {
+    headers: {
+      Accept: "text/markdown, text/plain",
+      Authorization: `Bearer ${config.resolveToken() ?? ""}`
+    },
+    signal: AbortSignal.timeout(30_000)
+  });
+  if (!response.ok) fail(`Could not read issue ${id} (HTTP ${response.status})`);
+  process.stdout.write(await response.text());
+}
+
+async function issueComment(config, id, rest) {
+  if (!id) fail("Usage: vatio issue comment ID \"your reply\"");
+  const body = rest.join(" ").trim();
+  if (body === "") fail("Usage: vatio issue comment ID \"your reply\"");
+
+  await issuesClient(config).post(`/cli/issues/${encodeURIComponent(id)}/comments`, { body });
+  console.log(`Replied on issue ${id}.`);
+}
+
+// A workspace is useful context on an issue but never required: `vatio issue`
+// has to work from anywhere, including a directory that is not a workspace.
+function safeWorkspace(config) {
+  try {
+    return config.resolveWorkspace();
+  } catch {
+    return null;
+  }
+}