@voltade/volty 0.1.24 → 0.1.26

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 readFileSync7, 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 join6 } from "node:path";
+import { join as join7 } from "node:path";
 
 // src/api.ts
 import { createHash } from "node:crypto";
@@ -572,80 +572,99 @@ function renderResult(body, json) {
   return text || "(no output)";
 }
 
-// src/keys.ts
-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);
-  for (let i = 0;i < rest.length; i++) {
-    const token = rest[i];
-    if (!token.startsWith("--")) {
-      out.push("--name", token);
-      continue;
-    }
-    const eq = token.indexOf("=");
-    const flag = eq > 0 ? token.slice(2, eq) : token.slice(2);
-    const value = eq > 0 ? token.slice(eq + 1) : VALUE_FLAGS.has(flag) ? rest[++i] : undefined;
-    if (value === undefined)
-      out.push(token);
-    else if (flag === "for")
-      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());
-    else
-      out.push(`--${flag}`, value);
+// 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"
   }
-  return out;
-}
+};
 
-// src/org-guard.ts
-var ORG_NATIVE = new Set(["use", "current", "list"]);
-function isOrgFreeCommand(command) {
-  const [cmd, sub] = command;
-  if (!cmd || cmd === "help" || cmd === "--help")
-    return true;
-  if (command.includes("--help"))
-    return true;
-  if (cmd === "auth" || cmd === "env" || cmd === "docs" || cmd === "skill")
-    return true;
-  return cmd === "org" && ORG_NATIVE.has(sub ?? "");
-}
-function isProdShaped(env, baseUrl) {
-  if (env === "prod")
-    return true;
-  if (!baseUrl)
+// ../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;
-  let host;
-  try {
-    host = new URL(baseUrl).hostname;
-  } catch {
-    return false;
-  }
-  return host !== "localhost" && host !== "127.0.0.1" && host !== "::1" && host !== "[::1]";
-}
-var PROD_ORG_REFUSAL = "prod needs an explicit org: pass --org <id> or VOLTY_ORG=<id>; run 'volty org list --env prod' to see your orgs";
-var STICKY_ORG_REFUSAL = "prod does not honour a sticky org: pass --org <id> or VOLTY_ORG=<id> on each command instead; run 'volty org list --env prod' to see your orgs";
-function resolveTargetOrg({ env, baseUrl, override, sticky, command }) {
-  if (!isProdShaped(env, baseUrl))
-    return { org: override ?? sticky };
-  if (override)
-    return { org: override };
-  if (isOrgFreeCommand(command))
-    return { org: undefined };
-  return { refusal: PROD_ORG_REFUSAL };
+  return !PUSH_EXCLUDES.some((pattern) => pattern.endsWith("/") ? isDirectory && name === pattern.slice(0, -1) : pattern.startsWith("*") ? name.endsWith(pattern.slice(1)) : name === pattern);
 }
 
-// src/proposals.ts
-function decideProposal(ctx, proposalId, decision, reason) {
-  return apiFetch(ctx, `/api/changes/proposals/${encodeURIComponent(proposalId)}/decide`, {
-    method: "POST",
-    body: { decision, ...reason ? { reason } : {} }
-  });
+// ../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
@@ -726,9 +745,108 @@ async function pull(ctx, opts) {
   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) {
+  const out = argv.slice(0, 2);
+  const rest = argv.slice(2);
+  for (let i = 0;i < rest.length; i++) {
+    const token = rest[i];
+    if (!token.startsWith("--")) {
+      out.push("--name", token);
+      continue;
+    }
+    const eq = token.indexOf("=");
+    const flag = eq > 0 ? token.slice(2, eq) : token.slice(2);
+    const value = eq > 0 ? token.slice(eq + 1) : VALUE_FLAGS.has(flag) ? rest[++i] : undefined;
+    if (value === undefined)
+      out.push(token);
+    else if (flag === "for")
+      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());
+    else
+      out.push(`--${flag}`, value);
+  }
+  return out;
+}
+
+// src/org-guard.ts
+var ORG_NATIVE = new Set(["use", "current", "list"]);
+function isOrgFreeCommand(command) {
+  const [cmd, sub] = command;
+  if (!cmd || cmd === "help" || cmd === "--help")
+    return true;
+  if (command.includes("--help"))
+    return true;
+  if (cmd === "auth" || cmd === "env" || cmd === "docs" || cmd === "skill")
+    return true;
+  return cmd === "org" && ORG_NATIVE.has(sub ?? "");
+}
+function isProdShaped(env, baseUrl) {
+  if (env === "prod")
+    return true;
+  if (!baseUrl)
+    return false;
+  let host;
+  try {
+    host = new URL(baseUrl).hostname;
+  } catch {
+    return false;
+  }
+  return host !== "localhost" && host !== "127.0.0.1" && host !== "::1" && host !== "[::1]";
+}
+var PROD_ORG_REFUSAL = "prod needs an explicit org: pass --org <id> or VOLTY_ORG=<id>; run 'volty org list --env prod' to see your orgs";
+var STICKY_ORG_REFUSAL = "prod does not honour a sticky org: pass --org <id> or VOLTY_ORG=<id> on each command instead; run 'volty org list --env prod' to see your orgs";
+function resolveTargetOrg({ env, baseUrl, override, sticky, command }) {
+  if (!isProdShaped(env, baseUrl))
+    return { org: override ?? sticky };
+  if (override)
+    return { org: override };
+  if (isOrgFreeCommand(command))
+    return { org: undefined };
+  return { refusal: PROD_ORG_REFUSAL };
+}
+
+// src/proposals.ts
+function decideProposal(ctx, proposalId, decision, reason) {
+  return apiFetch(ctx, `/api/changes/proposals/${encodeURIComponent(proposalId)}/decide`, {
+    method: "POST",
+    body: { decision, ...reason ? { reason } : {} }
+  });
+}
+
 // src/push.ts
 import { readdirSync as readdirSync2, readFileSync as readFileSync5 } from "node:fs";
-import { join as join4 } from "node:path";
+import { join as join5 } from "node:path";
 
 // ../shared/projects/limits.ts
 var PROJECT_FILE_MAX_CHARS = 2000000;
@@ -748,10 +866,8 @@ function readProject(dir) {
   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("."))
+    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()) {
@@ -763,7 +879,7 @@ function readProject(dir) {
       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");
+      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.`);
       }
@@ -861,10 +977,11 @@ async function applyItem(ctx, item) {
   }
   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.name}: 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":
@@ -897,6 +1014,10 @@ async function pushTarget(ctx, opts) {
       results.push({ path: item.path, name: item.name, lines: item.lines, result: "skipped" });
       continue;
     }
+    if (item.steps.length === 0 && item.stored) {
+      results.push({ path: item.path, name: item.name, lines: item.lines, result: "applied", detail: STORED });
+      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 });
@@ -949,15 +1070,15 @@ async function pushTarget(ctx, opts) {
 }
 
 // src/update.ts
-import { mkdirSync as mkdirSync4, readFileSync as readFileSync6, 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 join5 } from "node:path";
-var CACHE_PATH = join5(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(readFileSync6(join5(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;
@@ -983,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 {}
 }
@@ -1210,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);
@@ -1223,19 +1347,31 @@ 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(`
 `)}
 `);
@@ -1312,16 +1448,16 @@ function handleSkill(rest) {
   if (rest[0] !== "install")
     fail("usage: volty skill install");
   const candidates = [
-    join6(import.meta.dirname, "..", "skill", "volty-cli-ops", "SKILL.md"),
-    join6(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 = join6(homedir3(), ".claude", "skills", "volty-cli-ops");
+  const destDir = join7(homedir3(), ".claude", "skills", "volty-cli-ops");
   mkdirSync5(destDir, { recursive: true });
-  writeFileSync6(join6(destDir, "SKILL.md"), readFileSync7(source, "utf8"));
-  process.stdout.write(`Installed the volty-cli-ops skill → ${join6(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() {
@@ -1332,7 +1468,7 @@ 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") {
@@ -1389,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.24",
+  "version": "0.1.26",
   "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",