@voltade/volty 0.1.22 → 0.1.24

package/dist/volty.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 
 // bin/volty.ts
-import { existsSync as existsSync5, mkdirSync as mkdirSync5, readFileSync as readFileSync6, writeFileSync as writeFileSync6 } from "node:fs";
+import { existsSync as existsSync5, mkdirSync as mkdirSync5, readFileSync as readFileSync7, writeFileSync as writeFileSync6 } from "node:fs";
 import { homedir as homedir3 } from "node:os";
-import { join as join5 } from "node:path";
+import { join as join6 } from "node:path";
 
 // src/api.ts
 import { createHash } from "node:crypto";
@@ -573,7 +573,7 @@ function renderResult(body, json) {
 }
 
 // src/keys.ts
-var VALUE_FLAGS = new Set(["name", "for", "for-user-id", "expires", "expires-in-days", "families"]);
+var VALUE_FLAGS = new Set(["name", "for", "for-user-id", "expires", "expires-in-days", "families", "cap"]);
 function keysArgv(argv) {
   const out = argv.slice(0, 2);
   const rest = argv.slice(2);
@@ -592,6 +592,8 @@ function keysArgv(argv) {
       out.push("--for-user-id", value);
     else if (flag === "expires")
       out.push("--expires-in-days", value.replace(/d$/, ""));
+    else if (flag === "cap")
+      out.push("--daily-cap", value);
     else if (flag === "families")
       for (const f of value.split(","))
         out.push("--families", f.trim());
@@ -650,328 +652,23 @@ function decideProposal(ctx, proposalId, decision, reason) {
 import { createHash as createHash2 } from "node:crypto";
 import { chmodSync, existsSync as existsSync4, mkdirSync as mkdirSync3, readdirSync, readFileSync as readFileSync4, unlinkSync, writeFileSync as writeFileSync4 } from "node:fs";
 import { dirname as dirname2, join as join3 } from "node:path";
-async function call(ctx, name, input = {}) {
+async function read(ctx, name, input = {}) {
   const res = await runOp(ctx, { name }, input);
   if (!res.ok)
     throw new Error(`${name}: ${res.body?.error?.message ?? `HTTP ${res.status}`}`);
-  const structured = res.body.structuredContent;
-  if (structured?.refused)
-    return { refused: res.body.content?.[0]?.text ?? `${name} refused` };
-  return { value: structured };
-}
-async function read(ctx, name, input = {}) {
-  const out = await call(ctx, name, input);
-  if ("refused" in out)
-    throw new Error(`${name}: ${out.refused}`);
-  return out.value;
-}
-function slugBase(name) {
-  const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60).replace(/^-+|-+$/g, "");
-  return slug || "source";
-}
-function tsLiteral(value, indent = "") {
-  if (value === null || typeof value !== "object")
-    return JSON.stringify(value) ?? "undefined";
-  const next = `${indent}  `;
-  if (Array.isArray(value)) {
-    if (value.length === 0)
-      return "[]";
-    return `[
-${value.map((v) => `${next}${tsLiteral(v, next)}`).join(`,
-`)},
-${indent}]`;
-  }
-  const entries = Object.entries(value).filter(([, v]) => v !== undefined);
-  if (entries.length === 0)
-    return "{}";
-  const key = (k) => /^[A-Za-z_$][\w$]*$/.test(k) ? k : JSON.stringify(k);
-  return `{
-${entries.map(([k, v]) => `${next}${key(k)}: ${tsLiteral(v, next)}`).join(`,
-`)},
-${indent}}`;
-}
-function tsFile(header, value) {
-  return `// ${header[0]}
-// ${header[1]}
-export default ${tsLiteral(value)}
-`;
+  return res.body.structuredContent;
 }
 var sha256 = (text) => createHash2("sha256").update(text).digest("hex");
-
-class Observed {
-  sections = new Map;
-  add(heading, line) {
-    let lines = this.sections.get(heading);
-    if (!lines) {
-      lines = [];
-      this.sections.set(heading, lines);
-    }
-    lines.push(line);
-  }
-  render() {
-    const blocks = [...this.sections].map(([heading, lines]) => `${heading}
-${lines.map((l) => `- ${l}`).join(`
-`)}`);
-    return `${[OBSERVED_HEAD, ...blocks].join(`
-
-`)}
-`;
-  }
-}
-var OBSERVED_HEAD = "Read-only. What this workspace holds outside the project as of the last volty pull: data Volty and staff write in the app, and what has no project file yet. Editing this file changes nothing, and volty pull rewrites it.";
-var WAITING_HEADING = "Versions waiting for approval (the files hold the running version)";
-var DRIVE_HEADING = "Drive files (the workspace Drive, which the project does not hold)";
-var part = () => ({ files: new Map, observed: new Observed });
-async function pooled(items, fn, size = 6) {
-  const out = new Array(items.length);
-  let next = 0;
-  const worker = async () => {
-    while (next < items.length) {
-      const i = next++;
-      out[i] = await fn(items[i]);
-    }
-  };
-  await Promise.all(Array.from({ length: Math.min(size, items.length) }, worker));
-  return out;
-}
-function ruleOut(rule) {
-  const { teamId, userId, userIds, ...action } = rule.action;
-  return {
-    enabled: rule.enabled,
-    condition: rule.condition,
-    action: {
-      ...action,
-      ...teamId ? { team: rule.teamSlug } : {},
-      ...userId ? { member: rule.memberEmails[0] ?? null } : {},
-      ...userIds ? { members: rule.memberEmails } : {}
-    }
-  };
-}
-async function pullInboxes(ctx) {
-  const out = { ...part(), slugById: new Map };
-  const { inboxes } = await read(ctx, "inboxes list");
-  const rows = inboxes.filter((i) => i.type === "shared").sort((a, b) => a.id.localeCompare(b.id));
-  const got = await pooled(rows, async (row) => {
-    if (row.role === null)
-      return null;
-    const inbox = await read(ctx, "inboxes get", { inboxId: row.id });
-    const flow = inbox.webChat ? await read(ctx, "chat-flow get", { inboxId: row.id, part: "source" }) : null;
-    return { inbox, flow };
-  });
-  rows.forEach((row, i) => {
-    const one = got[i];
-    if (!one) {
-      out.observed.add("Inboxes not pulled", `${row.name}: you are not on this inbox, so its settings are not readable`);
-      return;
-    }
-    const { inbox, flow } = one;
-    out.slugById.set(row.id, inbox.slug);
-    const dir = `inboxes/${inbox.slug}`;
-    if (flow?.published)
-      out.files.set(`${dir}/quick-paths.ts`, flow.published.source);
-    if (flow && flow.revision > 0 && flow.source !== flow.published?.source) {
-      out.observed.add("Quick paths with unpublished changes (the file holds the published version)", `${dir}/quick-paths.ts: the draft at revision ${flow.revision} is not published`);
-    }
-    const { volty, webChat, routing } = inbox;
-    const { agentId: _agentId, agentName, ...seat } = volty ?? { agentId: "", agentName: "" };
-    const { handoffWhatsappInstanceId: _wa, handoffEmailInstanceId: _email, ...chat } = webChat?.settings ?? {};
-    out.files.set(`${dir}/inbox.ts`, tsFile([
-      `The ${inbox.name} inbox: hours, reply targets, hand-off, priority guide, routing, Volty's reply mode and its web chat.`,
-      "Written by volty pull from the live inbox. Who works the inbox, team members and channels stay in the app."
-    ], {
-      name: inbox.name,
-      icon: inbox.icon,
-      autoEnrollOrgMembers: inbox.autoEnrollOrgMembers,
-      businessHours: inbox.businessHours,
-      idleClose: inbox.idleClose,
-      firstResponseMinutes: inbox.firstResponseMinutes,
-      handoff: inbox.handoff,
-      priority: inbox.priority,
-      routing: { ...routing, rules: routing.rules.map(ruleOut) },
-      volty: volty ? { agent: agentName, ...seat } : null,
-      webChat: webChat ? {
-        ...chat,
-        handoffWhatsappNumber: webChat.handoffAddresses.whatsapp,
-        handoffEmailAddress: webChat.handoffAddresses.email
-      } : null,
-      quickPaths: flow ? { enabled: flow.enabled } : undefined
-    }));
-  });
-  return out;
-}
-async function pullInstructions(ctx, inboxes) {
-  const out = part();
-  const [got, { slugById }] = await Promise.all([read(ctx, "instructions get"), inboxes]);
-  if (got.org.text)
-    out.files.set("instructions/org.md", got.org.text);
-  if (got.team.text)
-    out.files.set("instructions/team.md", got.team.text);
-  for (const row of got.inboxes) {
-    const slug = slugById.get(row.inboxId);
-    if (slug && row.text)
-      out.files.set(`inboxes/${slug}/instructions.md`, row.text);
-  }
-  return out;
-}
-async function pullSources(ctx) {
-  const { sources } = await read(ctx, "sources list");
-  const out = { ...part(), sources };
-  const rows = [...sources].sort((a, b) => a.id.localeCompare(b.id));
-  const got = await pooled(rows, (row) => call(ctx, "sources get", { source: row.id, export: true }));
-  const taken = new Set;
-  rows.forEach((row, i) => {
-    const one = got[i];
-    if (!one || "refused" in one) {
-      out.observed.add("Sources with no file yet (website, API and sync sources)", `${row.name} (${row.kind})`);
-      return;
-    }
-    const base = slugBase(row.name);
-    let slug = base;
-    for (let n = 2;taken.has(slug); n++)
-      slug = `${base}-${n}`;
-    taken.add(slug);
-    const { id: _id, scope, automation, ...rest } = one.value.file;
-    out.files.set(`sources/${slug}.ts`, tsFile([
-      `The ${row.name} source: its settings, the names of its secrets (never a value), lanes, scope and tool modes.`,
-      "Written by volty pull. Secret values, sign-ins and which tools an admin approved stay in the app."
-    ], {
-      ...rest,
-      scope: { mode: scope.mode, inboxes: scope.inboxes.map((i) => i.slug), privateInboxes: scope.privateInboxes },
-      automation: automation?.slug ?? null
-    }));
-  });
-  return out;
-}
-var notDeployed = (row) => `${row.slug}: ${row.pendingApproval ? "its first version waits for approval" : "no version is running"}`;
-async function pullAutomations(ctx) {
-  const out = part();
-  const { automations } = await read(ctx, "automations list");
-  const got = await pooled(automations, async (row) => {
-    if (!row.deployed)
-      return null;
-    const first = await read(ctx, "automations get", { id: row.id });
-    if (first.sourceLabel !== "pending" || !first.active?.version)
-      return { got: first, waiting: false };
-    return {
-      got: await read(ctx, "automations get", { id: row.id, version: first.active.version }),
-      waiting: true
-    };
-  });
-  automations.forEach((row, i) => {
-    const one = got[i];
-    if (!one) {
-      out.observed.add("Automations not deployed", notDeployed(row));
-      return;
-    }
-    if (one.waiting)
-      out.observed.add(WAITING_HEADING, `automations/${row.slug}.ts`);
-    if (one.got.source !== null)
-      out.files.set(`automations/${row.slug}.ts`, one.got.source);
-  });
-  return out;
-}
-async function pullPages(ctx) {
-  const out = part();
-  const { miniApps } = await read(ctx, "mini-apps list");
-  const got = await pooled(miniApps, async (row) => {
-    if (!row.deployed)
-      return null;
-    const first = await read(ctx, "mini-apps get", { id: row.id });
-    if (!first.pending)
-      return { got: first, waiting: false };
-    const active = first.deploys.find((d) => d.status === "active");
-    return {
-      got: active?.version ? await read(ctx, "mini-apps get", { id: row.id, version: active.version }) : first,
-      waiting: true
-    };
-  });
-  miniApps.forEach((row, i) => {
-    const one = got[i];
-    if (!one) {
-      out.observed.add("Pages not deployed", notDeployed(row));
-      return;
-    }
-    if (one.waiting)
-      out.observed.add(WAITING_HEADING, `pages/${row.slug}/`);
-    if (one.got.entrySource !== null)
-      out.files.set(`pages/${row.slug}/entry.tsx`, one.got.entrySource);
-    if (one.got.bffSource !== null)
-      out.files.set(`pages/${row.slug}/bff.ts`, one.got.bffSource);
-  });
-  return out;
-}
-var DRIVE_FOLDER_CAP = 100;
-async function walkDrive(ctx) {
-  const files = [];
-  let queue = ["/"];
-  let walked = 0;
-  while (queue.length > 0 && walked < DRIVE_FOLDER_CAP) {
-    const level = queue.slice(0, DRIVE_FOLDER_CAP - walked);
-    walked += level.length;
-    const listed = await pooled(level, (path) => read(ctx, "drive list-folder", { scope: "organization", path }));
-    const children = [];
-    for (const { entries } of listed) {
-      for (const entry of entries) {
-        if (entry.kind === "folder")
-          children.push(entry.path);
-        else
-          files.push(entry.path);
-      }
-    }
-    queue = [...queue.slice(level.length), ...children];
-  }
-  return { files, unread: queue.length };
-}
-async function observeData(ctx) {
-  const out = part();
-  const [learned, drive, { tables }] = await Promise.all([
-    read(ctx, "learned list"),
-    walkDrive(ctx),
-    read(ctx, "tables list")
-  ]);
-  for (const rule of learned.rules)
-    out.observed.add("Learned rules (Volty writes them; a push never touches them)", rule.text);
-  for (const path of drive.files)
-    out.observed.add(DRIVE_HEADING, path);
-  if (drive.unread > 0)
-    out.observed.add(DRIVE_HEADING, `${drive.unread} more folders not listed`);
-  for (const table of tables)
-    out.observed.add("Tables (their rows stay in the workspace)", table.name);
-  return out;
-}
-function agentsMd(workspaceId, sources) {
-  const systems = [...sources].sort((a, b) => a.name.localeCompare(b.name)).map((s) => `- ${s.name} (${s.kind})`);
-  return `# Volty project
-
-This folder is one Volty workspace's setup as files, written by \`volty pull\` from the live workspace \`${workspaceId}\`.
-
-- \`instructions/org.md\`: the instructions Volty reads everywhere. \`instructions/team.md\`: how Volty works with staff, read only when it talks to staff.
-- \`inboxes/<slug>/inbox.ts\`: one inbox's settings. Beside it, \`instructions.md\` is that inbox's own instructions and \`quick-paths.ts\` its web chat's quick paths.
-- \`sources/<slug>.ts\`: a connected source's settings, the names of its secrets (never a value), lanes and tool modes.
-- \`automations/<slug>.ts\`: an automation's running source.
-- \`pages/<slug>/\`: a page's \`entry.tsx\` and \`bff.ts\`.
-- \`volty.config.ts\`: the workspace this project deploys to.
-- \`.volty/targets\`: the version this folder was pulled from. \`.volty/observed\`: what the workspace holds outside the project (Learned rules, Drive files, tables, sources with no file yet), read-only.
-
-Systems connected to this workspace:
-${systems.length > 0 ? systems.join(`
-`) : "- none"}
-
-Pushing the folder back is not built yet. Run \`volty pull\` again to bring the folder up to date, and \`volty docs\` for every operation.
-`;
-}
-function configFile(target, workspaceId) {
-  return tsFile([
-    "Where this project deploys: each target names one workspace by id.",
-    "Written by volty pull; the version each target was pulled from is in .volty/targets."
-  ], { targets: { [target]: { workspace: workspaceId } } });
-}
 function readTargets(dir) {
   const path = join3(dir, ".volty", "targets");
   if (!existsSync4(path))
     return null;
   return JSON.parse(readFileSync4(path, "utf8"));
 }
+function writeTargets(dir, targets) {
+  writeFileSync4(join3(dir, ".volty", "targets"), `${JSON.stringify(targets, null, 2)}
+`);
+}
 async function pull(ctx, opts) {
   const { dir, workspaceId, target } = opts;
   const targets = readTargets(dir);
@@ -983,32 +680,14 @@ async function pull(ctx, opts) {
   } else if (existsSync4(dir) && readdirSync(dir).some((name) => !name.startsWith("."))) {
     throw new Error(`${dir} is not empty and no volty pull wrote it: pull into an empty folder.`);
   }
-  const inboxes = pullInboxes(ctx);
-  const parts = await Promise.all([
-    inboxes,
-    pullInstructions(ctx, inboxes),
-    pullSources(ctx),
-    pullAutomations(ctx),
-    pullPages(ctx),
-    observeData(ctx)
-  ]);
-  const files = new Map;
-  const observed = new Observed;
-  for (const one of parts) {
-    for (const [rel, text] of one.files)
-      files.set(rel, text);
-    for (const [heading, lines] of one.observed.sections)
-      for (const line of lines)
-        observed.add(heading, line);
-  }
-  files.set("AGENTS.md", agentsMd(workspaceId, parts[2].sources));
-  files.set("volty.config.ts", configFile(target, workspaceId));
   const base = targets?.[target]?.version;
-  const { baseFiles, ...recorded } = await read(ctx, "project record-pull", {
-    workspace: workspaceId,
-    files: Object.fromEntries(files),
-    ...base ? { base } : {}
-  });
+  const {
+    baseFiles,
+    files: tree,
+    observed,
+    ...recorded
+  } = await read(ctx, "project pull", { workspace: workspaceId, ...base ? { base } : {} });
+  const files = new Map(Object.entries(tree));
   const written = [];
   const deleted = [];
   const kept = [];
@@ -1038,30 +717,247 @@ async function pull(ctx, opts) {
     }
   }
   mkdirSync3(join3(dir, ".volty"), { recursive: true });
-  const nextTargets = {
-    ...targets,
-    [target]: { workspace: recorded.workspaceId, version: recorded.versionId }
-  };
-  writeFileSync4(join3(dir, ".volty", "targets"), `${JSON.stringify(nextTargets, null, 2)}
-`);
+  writeTargets(dir, { ...targets, [target]: { workspace: recorded.workspaceId, version: recorded.versionId } });
   const observedPath = join3(dir, ".volty", "observed");
   if (existsSync4(observedPath))
     chmodSync(observedPath, 420);
-  writeFileSync4(observedPath, observed.render());
+  writeFileSync4(observedPath, observed);
   chmodSync(observedPath, 292);
   return { ...recorded, written, deleted, kept };
 }
 
+// src/push.ts
+import { readdirSync as readdirSync2, readFileSync as readFileSync5 } from "node:fs";
+import { join as join4 } from "node:path";
+
+// ../shared/projects/limits.ts
+var PROJECT_FILE_MAX_CHARS = 2000000;
+var PROJECT_FILES_MAX = 2000;
+
+// ../shared/text/plural.ts
+function plural(n, noun) {
+  return n === 1 ? noun : `${noun}s`;
+}
+
+// src/push.ts
+function readProject(dir) {
+  const targets = readTargets(dir);
+  if (!targets) {
+    throw new Error(`${dir} has no .volty/targets, so no volty pull wrote it: pull the workspace into it first.`);
+  }
+  const files = {};
+  let count = 0;
+  const walk = (rel) => {
+    for (const entry of readdirSync2(join4(dir, rel), { withFileTypes: true })) {
+      if (entry.name === "node_modules" || entry.name === ".git")
+        continue;
+      if (rel === "" && entry.name.startsWith("."))
+        continue;
+      const path = rel ? `${rel}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        walk(path);
+        continue;
+      }
+      if (!entry.isFile())
+        continue;
+      if (++count > PROJECT_FILES_MAX) {
+        throw new Error(`${dir} holds more than ${PROJECT_FILES_MAX.toLocaleString("en-US")} files, the most a push takes.`);
+      }
+      const text = readFileSync5(join4(dir, path), "utf8");
+      if (text.length > PROJECT_FILE_MAX_CHARS) {
+        throw new Error(`${path} holds ${text.length.toLocaleString("en-US")} characters, over the ${PROJECT_FILE_MAX_CHARS.toLocaleString("en-US")} a push takes per file.`);
+      }
+      files[path] = text;
+    }
+  };
+  walk("");
+  return { targets, files };
+}
+function pickTargets(targets, env) {
+  const names = Object.keys(targets);
+  if (env === "all")
+    return names;
+  if (env !== undefined) {
+    if (!targets[env])
+      throw new Error(`.volty/targets has no target ${env}: it has ${names.join(", ") || "none"}.`);
+    return [env];
+  }
+  if (names.length === 1)
+    return names;
+  throw new Error(`.volty/targets has ${names.length} targets: name one with --env (${names.join(", ")}) or --env all.`);
+}
+function renderPlan(plan) {
+  const out = [];
+  for (const item of plan.items) {
+    if (item.change === "none" && item.lines.length === 0 && item.findings.length === 0)
+      continue;
+    const [first, ...more] = item.lines;
+    const head = item.change !== "none" ? item.change : first ?? "no change";
+    out.push(`${item.name}: ${head}`);
+    for (const line of item.change !== "none" ? item.lines : more)
+      out.push(`  ${line}`);
+    for (const line of item.liveSince)
+      out.push(`  live since your pull: ${line}`);
+    for (const f of item.findings)
+      out.push(`  ${f.severity}: ${f.message}`);
+  }
+  out.push(plan.summary);
+  return out;
+}
+function refusalOf(plan, confirm) {
+  if (!plan.runnable) {
+    const why = [];
+    if (plan.stale) {
+      const stale = plan.items.filter((i) => i.change !== "none" && i.liveSince.length > 0).map((i) => i.name);
+      why.push(`${stale.length > 0 ? stale.join(", ") : "The workspace"} changed live since your pull: pull again, then push.`);
+    }
+    for (const item of plan.items) {
+      for (const f of item.findings)
+        if (f.severity === "error")
+          why.push(`${item.name}: ${f.message}`);
+    }
+    if (why.length === 0)
+      why.push(plan.summary);
+    return `Nothing was pushed. ${why.join(`
+`)}`;
+  }
+  const destructive = plan.items.filter((i) => i.destructive && i.change !== "none").map((i) => i.name);
+  if (destructive.length > 0 && !confirm) {
+    return `Nothing was pushed: ${destructive.join(", ")} ${destructive.length === 1 ? "is" : "are"} destructive. Read the plan, then push again with --confirm.`;
+  }
+  return null;
+}
+async function applyItem(ctx, item) {
+  const base = { path: item.path, name: item.name, lines: item.lines };
+  let pending = false;
+  for (const step of item.steps) {
+    let res;
+    try {
+      res = await runOp(ctx, { name: step.op }, step.input);
+    } catch (err) {
+      const detail = `${step.op}: ${err instanceof Error ? err.message : String(err)}`;
+      return { result: { ...base, result: "failed", detail }, stop: true };
+    }
+    if (res.status === 202) {
+      const changeId = res.body.structuredContent?.proposalId;
+      return { result: { ...base, result: "held", ...changeId ? { changeId } : {} }, stop: false };
+    }
+    if (res.status === 422) {
+      const detail = res.body?.error?.message ?? `${step.op} refused`;
+      return { result: { ...base, result: "refused", detail }, stop: false };
+    }
+    if (res.status !== 200) {
+      const detail = `${step.op}: ${res.body?.error?.message ?? `HTTP ${res.status}`}`;
+      return { result: { ...base, result: "failed", detail }, stop: true };
+    }
+    const answer = res.body.structuredContent;
+    if (answer?.deployStatus === "changes_requested") {
+      const detail = res.body.content?.map((c) => c.text ?? "").join(`
+`) || `${step.op} was sent back by the reviewer`;
+      return { result: { ...base, result: "refused", detail }, stop: false };
+    }
+    if (answer?.deployStatus === "pending_approval")
+      pending = true;
+  }
+  return { result: { ...base, result: pending ? "pending" : "applied" }, stop: false };
+}
+function resultLine(r) {
+  switch (r.result) {
+    case "applied":
+      return `${r.name}: applied`;
+    case "pending":
+      return `${r.name}: pending approval, the running version stays live until an admin approves`;
+    case "held":
+      return `${r.name}: held as change ${r.changeId ?? "(no id)"} for an admin. The rest of this item did not run and will not run on approval, so push again once it is decided (volty changes lists it)`;
+    case "refused":
+      return `${r.name}: refused: ${r.detail}`;
+    case "failed":
+      return `${r.name}: failed: ${r.detail}`;
+    case "skipped":
+      return r.detail ? `${r.name}: not applied, ${r.detail}` : `${r.name}: skipped, after the failure above`;
+  }
+}
+async function pushTarget(ctx, opts) {
+  const { dir, target, files, targets } = opts;
+  const { workspace, version } = targets[target];
+  const base = version ? { base: version } : {};
+  const plan = await read(ctx, "project push", { workspace, target, files, ...base });
+  const lines = renderPlan(plan);
+  const refusal = refusalOf(plan, opts.confirm || opts.dryRun);
+  if (opts.dryRun)
+    return { exitCode: plan.runnable ? 0 : 1, lines, json: plan, ...refusal ? { error: refusal } : {} };
+  if (refusal)
+    return { exitCode: 1, lines, json: plan, error: refusal };
+  const results = [];
+  let stopped = false;
+  for (const item of plan.items) {
+    if (item.change === "none")
+      continue;
+    if (stopped) {
+      results.push({ path: item.path, name: item.name, lines: item.lines, result: "skipped" });
+      continue;
+    }
+    if (item.steps.length === 0) {
+      const detail = item.findings.find((f) => f.severity === "warn")?.message ?? "nothing to run for this kind yet";
+      results.push({ path: item.path, name: item.name, lines: item.lines, result: "skipped", detail });
+      continue;
+    }
+    const { result, stop } = await applyItem(ctx, item);
+    results.push(result);
+    stopped = stop;
+  }
+  if (results.length === 0)
+    return { exitCode: 0, lines, json: plan };
+  const resultsOut = results.map((r) => resultLine(r));
+  if (results.every((r) => r.result === "skipped")) {
+    const n = results.length;
+    return {
+      exitCode: 1,
+      lines: [...lines, ...resultsOut],
+      json: { items: results },
+      error: `Nothing was pushed: ${n} ${plural(n, "item")} ${n === 1 ? "has" : "have"} nothing to run yet.`
+    };
+  }
+  let record;
+  try {
+    record = await read(ctx, "project record-push", {
+      workspace,
+      target,
+      files,
+      ...base,
+      items: results
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      exitCode: 1,
+      lines: [...lines, ...resultsOut],
+      json: { items: results },
+      error: `The items above ran, but recording the push failed (${message}). .volty/targets keeps the old base: push again.`
+    };
+  }
+  targets[target] = { workspace, version: record.versionId };
+  writeTargets(dir, targets);
+  const count = (o) => results.filter((r) => r.result === o).length;
+  const skipped = count("skipped");
+  const summary = `Pushed ${results.length} ${plural(results.length, "item")} to ${target}: ${count("applied")} applied, ${count("held")} held, ${count("pending")} pending approval, ${count("refused")} refused, ${count("failed")} failed${skipped > 0 ? `, ${skipped} skipped` : ""}.`;
+  return {
+    exitCode: record.status === "partial" ? 1 : 0,
+    lines: [...lines, ...resultsOut, summary],
+    json: { ...record, items: results }
+  };
+}
+
 // src/update.ts
-import { mkdirSync as mkdirSync4, readFileSync as readFileSync5, writeFileSync as writeFileSync5 } from "node:fs";
+import { mkdirSync as mkdirSync4, readFileSync as readFileSync6, writeFileSync as writeFileSync5 } from "node:fs";
 import { homedir as homedir2 } from "node:os";
-import { dirname as dirname3, join as join4 } from "node:path";
-var CACHE_PATH = join4(homedir2(), ".config", "volty", "update-check.json");
+import { dirname as dirname3, join as join5 } from "node:path";
+var CACHE_PATH = join5(homedir2(), ".config", "volty", "update-check.json");
 var CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
 var REGISTRY_LATEST = "https://registry.npmjs.org/@voltade/volty/latest";
 function currentVersion() {
   try {
-    const pkg = JSON.parse(readFileSync5(join4(import.meta.dirname, "..", "package.json"), "utf8"));
+    const pkg = JSON.parse(readFileSync6(join5(import.meta.dirname, "..", "package.json"), "utf8"));
     return pkg.version ?? null;
   } catch {
     return null;
@@ -1079,7 +975,7 @@ function cmpVersion(a, b) {
 }
 function readCache() {
   try {
-    return JSON.parse(readFileSync5(CACHE_PATH, "utf8"));
+    return JSON.parse(readFileSync6(CACHE_PATH, "utf8"));
   } catch {
     return null;
   }
@@ -1344,6 +1240,65 @@ async function handlePull(rest, ctx, env) {
 `)}
 `);
 }
+var PUSH_USAGE = "usage: volty push [dir] [--env <target>|all] [--dry-run] [--confirm] [--json]";
+async function handlePush(argv, config, envFlag) {
+  const dryRun = takeBool(argv, "--dry-run");
+  const confirm = takeBool(dryRun.rest, "--confirm");
+  const json = takeBool(confirm.rest, "--json");
+  const [dir = ".", ...extra] = json.rest;
+  if (extra.length > 0 || dir.startsWith("--"))
+    fail(PUSH_USAGE);
+  const project = readProject(dir);
+  const names = pickTargets(project.targets, envFlag);
+  const answers = {};
+  let exitCode = 0;
+  for (const name of names) {
+    const login = config.contexts[name];
+    if (!login?.apiKey)
+      fail(`not logged in to '${name}', the env target ${name} runs on: run \`volty auth login --env ${name}\``);
+    const { workspace } = project.targets[name];
+    const selected = await ensureOrgKey(login, workspace, (line) => process.stderr.write(`${line}
+`));
+    if (selected.minted)
+      saveConfig(config);
+    const ctx = { ...login, apiKey: selected.apiKey, organizationId: selected.organizationId };
+    setOrgOverride(selected.organizationId);
+    if (isProdShaped(name, login.baseUrl)) {
+      const res = await whoami(ctx);
+      if ("error" in res)
+        fail(res.error);
+      process.stderr.write(`→ ${name} · ${res.who.organizationName} (${res.who.organizationId}) · ${res.who.role}
+`);
+    }
+    if (names.length > 1 && !json.present)
+      process.stdout.write(`Target ${name}, workspace ${workspace}:
+`);
+    const out = await pushTarget(ctx, {
+      dir,
+      target: name,
+      ...project,
+      dryRun: dryRun.present,
+      confirm: confirm.present
+    });
+    answers[name] = out.json;
+    if (!json.present)
+      process.stdout.write(`${out.lines.join(`
+`)}
+`);
+    if (out.error)
+      process.stderr.write(`volty: ${out.error}
+`);
+    exitCode = out.exitCode;
+    if (exitCode !== 0)
+      break;
+  }
+  if (json.present) {
+    const body = names.length === 1 ? answers[names[0]] : answers;
+    process.stdout.write(`${JSON.stringify(body, null, 2)}
+`);
+  }
+  process.exitCode = exitCode;
+}
 async function handleDocs(config, env) {
   const ctx = ensureContext(config, env);
   if (!ctx.baseUrl)
@@ -1357,16 +1312,16 @@ function handleSkill(rest) {
   if (rest[0] !== "install")
     fail("usage: volty skill install");
   const candidates = [
-    join5(import.meta.dirname, "..", "skill", "volty-cli-ops", "SKILL.md"),
-    join5(import.meta.dirname, "..", "..", ".claude", "skills", "volty-cli-ops", "SKILL.md")
+    join6(import.meta.dirname, "..", "skill", "volty-cli-ops", "SKILL.md"),
+    join6(import.meta.dirname, "..", "..", ".claude", "skills", "volty-cli-ops", "SKILL.md")
   ];
   const source = candidates.find((p) => existsSync5(p));
   if (!source)
     fail("bundled SKILL.md not found — reinstall the @voltade/volty package");
-  const destDir = join5(homedir3(), ".claude", "skills", "volty-cli-ops");
+  const destDir = join6(homedir3(), ".claude", "skills", "volty-cli-ops");
   mkdirSync5(destDir, { recursive: true });
-  writeFileSync6(join5(destDir, "SKILL.md"), readFileSync6(source, "utf8"));
-  process.stdout.write(`Installed the volty-cli-ops skill → ${join5(destDir, "SKILL.md")}
+  writeFileSync6(join6(destDir, "SKILL.md"), readFileSync7(source, "utf8"));
+  process.stdout.write(`Installed the volty-cli-ops skill → ${join6(destDir, "SKILL.md")}
 `);
 }
 async function main() {
@@ -1380,6 +1335,11 @@ async function main() {
   const workspaceExtract = argv[0] === "pull" ? takeValue(argv, "--workspace") : { value: undefined, rest: argv };
   argv = workspaceExtract.rest;
   const config = loadConfig();
+  if (argv[0] === "push") {
+    if (orgExtract.value)
+      fail("volty push takes its workspace from .volty/targets: leave out --org");
+    return handlePush(argv.slice(1), config, envExtract.value ?? (process.env.VOLTY_ENV || undefined));
+  }
   const env = activeEnv(config, envExtract.value ?? (process.env.VOLTY_ENV || undefined));
   const peek = config.contexts[env];
   const prod = isProdShaped(env, peek?.baseUrl);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltade/volty",
-  "version": "0.1.22",
+  "version": "0.1.24",
   "description": "Remote CLI for the Volty platform — run operations, trigger real agent wakes, and inspect LLM I/O over an API key.",
   "license": "UNLICENSED",
   "type": "module",