@voltade/volty 0.1.23 → 0.1.25

package/README.md

@@ -48,6 +48,16 @@ Open Claude Code anywhere and ask in plain language. The skill you installed in
 
 Claude knows the safety rules: tests run on your workspace's Sandbox from a synthetic contact, whose replies are recorded in the thread but never sent, so nothing can reach a real contact. Claude cleans up after itself when it's done, and anything left over is removed after 24 hours.
 
+## Working on a workspace's code in a folder
+
+To edit a workspace's automations, pages, quick paths and inbox settings as files, start a folder with:
+
+```sh
+volty init my-workspace
+```
+
+It pulls the workspace into the new folder and adds a `package.json`, a `.gitignore`, and a `tsconfig.json` that references `tsconfig.code.json` and `tsconfig.entry.json`, so your editor and Claude can check the code the way a push does with `npx tsc -b`, as the `@voltade/sdk` README explains. Run `npm install` in the folder, then open it in your editor. A file the folder already has is kept. `volty pull` brings in later changes from the workspace and `volty push` sends yours back.
+
 ## Upgrading
 
 When a newer version exists, the tool prints a notice — Claude will see it and upgrade for you. To do it yourself:

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 existsSync6, mkdirSync as mkdirSync5, readFileSync as readFileSync7, writeFileSync as writeFileSync7 } from "node:fs";
 import { homedir as homedir3 } from "node:os";
-import { join as join5 } from "node:path";
+import { join as join7 } from "node:path";
 
 // src/api.ts
 import { createHash } from "node:crypto";
@@ -572,6 +572,202 @@ function renderResult(body, json) {
   return text || "(no output)";
 }
 
+// src/init.ts
+import { existsSync as existsSync5, writeFileSync as writeFileSync5 } from "node:fs";
+import { join as join4 } from "node:path";
+
+// ../shared/projects/checker-options.ts
+var checkerOptions = {
+  code: {
+    target: "ES2022",
+    lib: ["ES2022", "DOM", "DOM.Iterable"],
+    module: "ESNext",
+    moduleResolution: "bundler",
+    strict: true,
+    skipLibCheck: true,
+    esModuleInterop: true,
+    types: []
+  },
+  entry: {
+    strict: false,
+    jsx: "react-jsx"
+  }
+};
+
+// ../shared/projects/paths.ts
+var SEGMENT = "[A-Za-z0-9_][A-Za-z0-9._-]*";
+var PROJECT_SEGMENT = new RegExp(`^${SEGMENT}$`);
+var PROJECT_PATH = new RegExp(`^(?:${SEGMENT}/)*${SEGMENT}$`);
+var PUSH_EXCLUDES = [
+  "node_modules/",
+  "bun.lock",
+  "bun.lockb",
+  "package-lock.json",
+  "yarn.lock",
+  "pnpm-lock.yaml",
+  "*.tsbuildinfo"
+];
+function pushes(name, isDirectory) {
+  if (!PROJECT_SEGMENT.test(name))
+    return false;
+  return !PUSH_EXCLUDES.some((pattern) => pattern.endsWith("/") ? isDirectory && name === pattern.slice(0, -1) : pattern.startsWith("*") ? name.endsWith(pattern.slice(1)) : name === pattern);
+}
+
+// ../shared/projects/scaffold.ts
+var SDK_VERSION_RANGE = "^0.1.0";
+var SCAFFOLD_PATHS = [
+  "package.json",
+  "tsconfig.json",
+  "tsconfig.code.json",
+  "tsconfig.entry.json",
+  ".gitignore"
+];
+var ENTRY_FILES = "pages/**/entry.tsx";
+function options(name) {
+  return {
+    ...checkerOptions.code,
+    composite: true,
+    noEmit: true,
+    tsBuildInfoFile: `./node_modules/.cache/volty/${name}.tsbuildinfo`,
+    jsx: checkerOptions.entry.jsx,
+    paths: { "~/*": ["./node_modules/@voltade/sdk/*"] }
+  };
+}
+var json = (value) => `${JSON.stringify(value, null, 2)}
+`;
+function scaffoldFiles() {
+  return {
+    "package.json": json({
+      name: "volty-project",
+      private: true,
+      type: "module",
+      devDependencies: {
+        "@types/react": "^19.0.0",
+        "@types/react-dom": "^19.0.0",
+        "@voltade/sdk": SDK_VERSION_RANGE,
+        typescript: "^5.9.0 || ^7.0.0"
+      }
+    }),
+    "tsconfig.json": json({
+      files: [],
+      references: [{ path: "./tsconfig.code.json" }, { path: "./tsconfig.entry.json" }]
+    }),
+    "tsconfig.code.json": json({
+      compilerOptions: { ...options("code"), allowUnreachableCode: false },
+      include: ["**/*.ts", "**/*.tsx"],
+      exclude: ["node_modules", ENTRY_FILES]
+    }),
+    "tsconfig.entry.json": json({
+      compilerOptions: { ...options("entry"), ...checkerOptions.entry, types: ["@voltade/sdk/globals"] },
+      include: [ENTRY_FILES]
+    }),
+    ".gitignore": `${PUSH_EXCLUDES.join(`
+`)}
+`
+  };
+}
+
+// src/pull.ts
+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 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}`}`);
+  return res.body.structuredContent;
+}
+var sha256 = (text) => createHash2("sha256").update(text).digest("hex");
+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);
+  if (targets) {
+    const other = Object.entries(targets).find(([, t]) => t.workspace !== workspaceId);
+    if (other) {
+      throw new Error(`${dir} holds the project of workspace ${other[1].workspace}: pull ${workspaceId} into its own folder.`);
+    }
+  } 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 base = targets?.[target]?.version;
+  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 = [];
+  const edited = (rel, local) => base !== undefined && sha256(local) !== baseFiles[rel];
+  for (const [rel, text] of [...files].sort(([a], [b]) => a.localeCompare(b))) {
+    const path = join3(dir, rel);
+    const local = existsSync4(path) ? readFileSync4(path, "utf8") : null;
+    if (local === text)
+      continue;
+    if (local !== null && edited(rel, local)) {
+      kept.push({ path: rel, workspace: sha256(text) === baseFiles[rel] ? "unchanged" : "changed" });
+      continue;
+    }
+    mkdirSync3(dirname2(path), { recursive: true });
+    writeFileSync4(path, text);
+    written.push(rel);
+  }
+  for (const rel of Object.keys(baseFiles).sort()) {
+    const path = join3(dir, rel);
+    if (files.has(rel) || !existsSync4(path))
+      continue;
+    if (edited(rel, readFileSync4(path, "utf8"))) {
+      kept.push({ path: rel, workspace: "removed" });
+    } else {
+      unlinkSync(path);
+      deleted.push(rel);
+    }
+  }
+  mkdirSync3(join3(dir, ".volty"), { recursive: true });
+  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);
+  chmodSync(observedPath, 292);
+  return { ...recorded, written, deleted, kept };
+}
+
+// src/init.ts
+function scaffold(dir) {
+  const texts = scaffoldFiles();
+  return SCAFFOLD_PATHS.map((path) => {
+    const target = join4(dir, path);
+    if (existsSync5(target))
+      return { path, written: false };
+    writeFileSync5(target, texts[path]);
+    return { path, written: true };
+  });
+}
+async function init(ctx, opts) {
+  const pulled = readTargets(opts.dir) ? null : await pull(ctx, opts);
+  return { pulled, files: scaffold(opts.dir) };
+}
+function initLines(dir, files) {
+  return [
+    `${dir} is set up for an editor:`,
+    ...files.map((f) => f.written ? `  wrote ${f.path}` : `  kept ${f.path}, which the folder already has`),
+    dir === "." ? "Next: run npm install, then open this folder in your editor." : `Next: cd ${dir}, run npm install, then open the folder in your editor.`
+  ];
+}
+
 // src/keys.ts
 var VALUE_FLAGS = new Set(["name", "for", "for-user-id", "expires", "expires-in-days", "families", "cap"]);
 function keysArgv(argv) {
@@ -648,422 +844,241 @@ function decideProposal(ctx, proposalId, decision, reason) {
   });
 }
 
-// src/pull.ts
-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 = {}) {
-  const res = await runOp(ctx, { name }, input);
-  if (res.status === 422 && res.body?.error?.code === "refused") {
-    return { refused: res.body.error.message ?? `${name} refused` };
-  }
-  if (!res.ok)
-    throw new Error(`${name}: ${res.body?.error?.message ?? `HTTP ${res.status}`}`);
-  return { value: res.body.structuredContent };
-}
-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)}
-`;
-}
-var sha256 = (text) => createHash2("sha256").update(text).digest("hex");
+// src/push.ts
+import { readdirSync as readdirSync2, readFileSync as readFileSync5 } from "node:fs";
+import { join as join5 } from "node:path";
 
-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(`
+// ../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`;
 }
-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]);
+
+// 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(join5(dir, rel), { withFileTypes: true })) {
+      if (!pushes(entry.name, entry.isDirectory()))
+        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(join5(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;
     }
   };
-  await Promise.all(Array.from({ length: Math.min(size, items.length) }, worker));
+  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 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 } : {}
+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.`);
     }
-  };
-}
-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`);
+    for (const item of plan.items) {
+      for (const f of item.findings)
+        if (f.severity === "error")
+          why.push(`${item.name}: ${f.message}`);
     }
-    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);
+    if (why.length === 0)
+      why.push(plan.summary);
+    return `Nothing was pushed. ${why.join(`
+`)}`;
   }
-  return out;
+  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 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;
+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 };
     }
-    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 (res.status === 202) {
+      const changeId = res.body.structuredContent?.proposalId;
+      return { result: { ...base, result: "held", ...changeId ? { changeId } : {} }, stop: false };
     }
-    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 (res.status === 422) {
+      const detail = res.body?.error?.message ?? `${step.op} refused`;
+      return { result: { ...base, result: "refused", detail }, stop: false };
     }
-    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);
-      }
+    if (res.status !== 200) {
+      const detail = `${step.op}: ${res.body?.error?.message ?? `HTTP ${res.status}`}`;
+      return { result: { ...base, result: "failed", detail }, stop: true };
     }
-    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"));
-}
-async function pull(ctx, opts) {
-  const { dir, workspaceId, target } = opts;
-  const targets = readTargets(dir);
-  if (targets) {
-    const other = Object.entries(targets).find(([, t]) => t.workspace !== workspaceId);
-    if (other) {
-      throw new Error(`${dir} holds the project of workspace ${other[1].workspace}: pull ${workspaceId} into its own folder.`);
+    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 };
     }
-  } 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 written = [];
-  const deleted = [];
-  const kept = [];
-  const edited = (rel, local) => base !== undefined && sha256(local) !== baseFiles[rel];
-  for (const [rel, text] of [...files].sort(([a], [b]) => a.localeCompare(b))) {
-    const path = join3(dir, rel);
-    const local = existsSync4(path) ? readFileSync4(path, "utf8") : null;
-    if (local === text)
+    if (answer?.deployStatus === "pending_approval")
+      pending = true;
+  }
+  return { result: { ...base, result: pending ? "pending" : "applied" }, stop: false };
+}
+var STORED = "stored with the version for the next pull";
+function resultLine(r) {
+  switch (r.result) {
+    case "applied":
+      return r.detail ? `${r.name}: applied, ${r.detail}` : `${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 (local !== null && edited(rel, local)) {
-      kept.push({ path: rel, workspace: sha256(text) === baseFiles[rel] ? "unchanged" : "changed" });
+    if (stopped) {
+      results.push({ path: item.path, name: item.name, lines: item.lines, result: "skipped" });
       continue;
     }
-    mkdirSync3(dirname2(path), { recursive: true });
-    writeFileSync4(path, text);
-    written.push(rel);
-  }
-  for (const rel of Object.keys(baseFiles).sort()) {
-    const path = join3(dir, rel);
-    if (files.has(rel) || !existsSync4(path))
+    if (item.steps.length === 0 && item.stored) {
+      results.push({ path: item.path, name: item.name, lines: item.lines, result: "applied", detail: STORED });
       continue;
-    if (edited(rel, readFileSync4(path, "utf8"))) {
-      kept.push({ path: rel, workspace: "removed" });
-    } else {
-      unlinkSync(path);
-      deleted.push(rel);
     }
+    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.`
+    };
   }
-  mkdirSync3(join3(dir, ".volty"), { recursive: true });
-  const nextTargets = {
-    ...targets,
-    [target]: { workspace: recorded.workspaceId, version: recorded.versionId }
+  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 }
   };
-  writeFileSync4(join3(dir, ".volty", "targets"), `${JSON.stringify(nextTargets, null, 2)}
-`);
-  const observedPath = join3(dir, ".volty", "observed");
-  if (existsSync4(observedPath))
-    chmodSync(observedPath, 420);
-  writeFileSync4(observedPath, observed.render());
-  chmodSync(observedPath, 292);
-  return { ...recorded, written, deleted, kept };
 }
 
 // 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 writeFileSync6 } 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 join6 } from "node:path";
+var CACHE_PATH = join6(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(join6(import.meta.dirname, "..", "package.json"), "utf8"));
     return pkg.version ?? null;
   } catch {
     return null;
@@ -1081,7 +1096,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;
   }
@@ -1089,7 +1104,7 @@ function readCache() {
 function writeCache(cache) {
   try {
     mkdirSync4(dirname3(CACHE_PATH), { recursive: true });
-    writeFileSync5(CACHE_PATH, `${JSON.stringify(cache)}
+    writeFileSync6(CACHE_PATH, `${JSON.stringify(cache)}
 `);
   } catch {}
 }
@@ -1316,10 +1331,13 @@ var KEPT_NOTE = {
   changed: ", and the workspace changed it too: delete it and pull again for the workspace copy",
   removed: ", and the workspace no longer has it"
 };
-async function handlePull(rest, ctx, env) {
+function folderArg(rest, command) {
   const [dir = ".", ...extra] = rest;
   if (extra.length > 0 || dir.startsWith("--"))
-    fail("usage: volty pull [dir] [--workspace <id>]");
+    fail(`usage: volty ${command} [dir] [--workspace <id>]`);
+  return dir;
+}
+async function workspaceOf(ctx) {
   let workspaceId = ctx.organizationId;
   if (!workspaceId) {
     const res = await whoami(ctx);
@@ -1329,23 +1347,94 @@ async function handlePull(rest, ctx, env) {
   }
   if (!workspaceId)
     fail("this key names no workspace: run `volty auth login`");
-  const out = await pull(ctx, { dir, workspaceId, target: env });
+  return workspaceId;
+}
+function pullLines(dir, out) {
   if (out.unchanged && out.written.length + out.deleted.length + out.kept.length === 0) {
-    process.stdout.write(`${dir} is up to date with version ${out.versionId} of workspace ${out.workspaceId}.
-`);
-    return;
+    return [`${dir} is up to date with version ${out.versionId} of workspace ${out.workspaceId}.`];
   }
-  const lines = [
+  return [
     `Pulled workspace ${out.workspaceId} into ${dir}: version ${out.versionId}${out.unchanged ? " (unchanged)" : ""}.`,
     ...out.written.map((f) => `  wrote ${f}`),
     ...out.deleted.map((f) => `  deleted ${f}, which the workspace no longer has`),
     ...out.kept.map((f) => `  kept ${f.path}: edited here${KEPT_NOTE[f.workspace]}`),
     "What the project does not hold is listed in .volty/observed."
   ];
+}
+async function handlePull(rest, ctx, env) {
+  const dir = folderArg(rest, "pull");
+  const out = await pull(ctx, { dir, workspaceId: await workspaceOf(ctx), target: env });
+  process.stdout.write(`${pullLines(dir, out).join(`
+`)}
+`);
+}
+async function handleInit(rest, ctx, env) {
+  const dir = folderArg(rest, "init");
+  const out = await init(ctx, { dir, workspaceId: await workspaceOf(ctx), target: env });
+  const lines = [...out.pulled ? pullLines(dir, out.pulled) : [], ...initLines(dir, out.files)];
   process.stdout.write(`${lines.join(`
 `)}
 `);
 }
+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)
@@ -1359,16 +1448,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")
+    join7(import.meta.dirname, "..", "skill", "volty-cli-ops", "SKILL.md"),
+    join7(import.meta.dirname, "..", "..", ".claude", "skills", "volty-cli-ops", "SKILL.md")
   ];
-  const source = candidates.find((p) => existsSync5(p));
+  const source = candidates.find((p) => existsSync6(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 = join7(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")}
+  writeFileSync7(join7(destDir, "SKILL.md"), readFileSync7(source, "utf8"));
+  process.stdout.write(`Installed the volty-cli-ops skill → ${join7(destDir, "SKILL.md")}
 `);
 }
 async function main() {
@@ -1379,9 +1468,14 @@ async function main() {
   argv = orgExtract.rest;
   const cacheFlag = takeBool(argv, "--no-cache");
   argv = cacheFlag.rest;
-  const workspaceExtract = argv[0] === "pull" ? takeValue(argv, "--workspace") : { value: undefined, rest: argv };
+  const workspaceExtract = argv[0] === "pull" || argv[0] === "init" ? 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);
@@ -1431,6 +1525,8 @@ async function main() {
   }
   if (cmd === "pull")
     return handlePull(rest, ctx, env);
+  if (cmd === "init")
+    return handleInit(rest, ctx, env);
   if (cmd === "changes" && rest[0] === "decide")
     return handleChanges(rest, ctx);
   if (cmd === "keys")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltade/volty",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "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",