@voltade/volty 0.1.18 → 0.1.20

package/dist/volty.js

@@ -1,11 +1,12 @@
 #!/usr/bin/env node
 
 // bin/volty.ts
-import { existsSync as existsSync3, mkdirSync as mkdirSync4, readFileSync as readFileSync5, writeFileSync as writeFileSync5 } from "node:fs";
+import { existsSync as existsSync4, mkdirSync as mkdirSync4, readFileSync as readFileSync5, writeFileSync as writeFileSync5 } from "node:fs";
 import { homedir as homedir3 } from "node:os";
 import { join as join4 } from "node:path";
 
 // src/api.ts
+import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -41,51 +42,36 @@ async function apiFetch(ctx, path, init) {
   } catch {}
   return { ok: res.ok, status: res.status, body };
 }
-var cachePath = (env) => join(tmpdir(), `volty-catalog-${env}-${targetOrg ?? "default"}.json`);
-function staleKeyHint(env) {
-  return `: this key is not valid any more, run \`volty auth login --env ${env}\``;
+var keyTag = (ctx) => createHash("sha256").update(ctx.apiKey ?? "").digest("hex").slice(0, 12);
+var cachePath = (env, ctx) => join(tmpdir(), `volty-catalog-${env}-${targetOrg ?? "default"}-${keyTag(ctx)}.json`);
+function refusalSuffix(res, env) {
+  if (res.body.error?.message)
+    return `: ${res.body.error.message}`;
+  return res.status === 401 ? `: this key is not valid any more, run \`volty auth login --env ${env}\`` : "";
 }
 async function fetchCatalog(ctx, env, useCache = true) {
-  const path = cachePath(env);
+  const path = cachePath(env, ctx);
   if (useCache && existsSync(path)) {
     try {
       const cached = JSON.parse(readFileSync(path, "utf8"));
-      if (Date.now() - cached.at < CATALOG_TTL_MS && cached.renamed && cached.inApp)
+      if (Date.now() - cached.at < CATALOG_TTL_MS && cached.renamed && cached.inApp && cached.outOfScope)
         return cached;
     } catch {}
   }
   const res = await apiFetch(ctx, "/api/v/_catalog");
   if (!res.ok || !res.body.catalog) {
-    throw new Error(`could not fetch the operation catalog (HTTP ${res.status})${res.status === 401 ? staleKeyHint(env) : ""}`);
+    throw new Error(`could not fetch the operation catalog (HTTP ${res.status})${refusalSuffix(res, env)}`);
   }
   const ops = res.body.catalog;
   const retired = res.body.retired ?? {};
   const renamed = res.body.renamed ?? {};
   const inApp = res.body.inApp ?? {};
+  const outOfScope = res.body.outOfScope ?? {};
   try {
     mkdirSync(tmpdir(), { recursive: true });
-    writeFileSync(path, JSON.stringify({ at: Date.now(), ops, retired, renamed, inApp }));
+    writeFileSync(path, JSON.stringify({ at: Date.now(), ops, retired, renamed, inApp, outOfScope }));
   } catch {}
-  return { ops, retired, renamed, inApp };
-}
-async function fetchOrgs(ctx, env, useCache = true) {
-  const path = join(tmpdir(), `volty-orgs-${env}.json`);
-  if (useCache && existsSync(path)) {
-    try {
-      const cached = JSON.parse(readFileSync(path, "utf8"));
-      if (Date.now() - cached.at < CATALOG_TTL_MS)
-        return cached.orgs;
-    } catch {}
-  }
-  const res = await apiFetch(ctx, "/api/cli/orgs");
-  if (!res.ok || !res.body.orgs) {
-    throw new Error(`could not fetch your org memberships (HTTP ${res.status})${res.status === 401 ? staleKeyHint(env) : ""}`);
-  }
-  const orgs = res.body.orgs;
-  try {
-    writeFileSync(path, JSON.stringify({ at: Date.now(), orgs }));
-  } catch {}
-  return orgs;
+  return { ops, retired, renamed, inApp, outOfScope };
 }
 function pathForOp(name) {
   return `/api/v/${name.trim().split(/\s+/).join("/")}`;
@@ -166,16 +152,59 @@ function ensureContext(config, env) {
   return ctx;
 }
 
+// src/org-keys.ts
+function storedKeyFor(ctx, org, now = Date.now()) {
+  if (!ctx.apiKey)
+    return null;
+  if (!org || org === ctx.organizationId || org === ctx.organizationSlug) {
+    return { apiKey: ctx.apiKey, organizationId: ctx.organizationId };
+  }
+  for (const [organizationId, k] of Object.entries(ctx.orgKeys ?? {})) {
+    if (organizationId !== org && k.slug !== org)
+      continue;
+    if (k.expiresAt && Date.parse(k.expiresAt) <= now)
+      return null;
+    return { apiKey: k.apiKey, organizationId };
+  }
+  return null;
+}
+async function ensureOrgKey(ctx, org, onMint) {
+  const stored = storedKeyFor(ctx, org);
+  if (stored)
+    return { ...stored, minted: false };
+  setOrgOverride(undefined);
+  const res = await apiFetch(ctx, "/api/cli/keys", { method: "POST", body: { org } });
+  if (!res.ok || !res.body.apiKey || !res.body.organizationId) {
+    throw new Error(res.body.error?.message ?? `could not get a key for '${org}' (HTTP ${res.status})`);
+  }
+  const entry = { apiKey: res.body.apiKey, slug: res.body.slug ?? org, expiresAt: res.body.expiresAt };
+  ctx.orgKeys = { ...ctx.orgKeys, [res.body.organizationId]: entry };
+  onMint(`Minted a key for ${entry.slug} (expires ${entry.expiresAt?.slice(0, 10) ?? "never"})`);
+  return { apiKey: entry.apiKey, organizationId: res.body.organizationId, minted: true };
+}
+async function dropOrgKeys(ctx) {
+  await Promise.all(Object.values(ctx.orgKeys ?? {}).map(async (k) => {
+    const res = await apiFetch({ ...ctx, apiKey: k.apiKey }, "/api/cli/logout", { method: "POST", body: {} }).catch(() => null);
+    if (!res || !res.ok && res.status !== 401) {
+      process.stderr.write(`Could not revoke the key for ${k.slug}; \`volty keys revoke cli --org ${k.slug}\` removes it.
+`);
+    }
+  }));
+  ctx.orgKeys = undefined;
+}
+
 // src/auth.ts
 async function whoami(ctx) {
   if (!ctx.apiKey)
-    return null;
+    return { error: "not logged in" };
   const res = await apiFetch(ctx, "/api/cli/whoami");
-  if (!res.ok || !res.body.organizationId)
-    return null;
+  if (!res.ok || !res.body.organizationId) {
+    return { error: res.body?.error?.message ?? "the stored key did not validate, run `volty auth login --rotate`" };
+  }
   ctx.organizationId = res.body.organizationId;
+  ctx.organizationSlug = res.body.organizationSlug ?? undefined;
   ctx.principal = res.body.email ?? res.body.name ?? res.body.userId;
-  return res.body;
+  return { who: res.body };
 }
 function openBrowser(url) {
   const cmd = process.platform === "darwin" ? ["open", url] : process.platform === "win32" ? ["cmd", "/c", "start", url] : ["xdg-open", url];
@@ -233,13 +262,13 @@ async function login(config, env, opts) {
     ctx.baseUrl = opts.baseUrl;
   if (!ctx.baseUrl)
     throw new Error(`no base URL for '${env}' — pass --base-url <url>`);
-  if (!opts.rotate && await whoami(ctx)) {
+  if (!opts.rotate && "who" in await whoami(ctx)) {
     return `Already authenticated to '${env}' as ${ctx.principal ?? "(unknown)"} — reusing the stored key.`;
   }
+  await dropOrgKeys(ctx);
   if (opts.token) {
     ctx.apiKey = opts.token;
-    const who = await whoami(ctx);
-    if (!who)
+    if ("error" in await whoami(ctx))
       throw new Error("the provided --token did not validate");
     return `Authenticated to '${env}' as ${ctx.principal ?? "(unknown)"} (org ${ctx.organizationId}).`;
   }
@@ -247,28 +276,29 @@ async function login(config, env, opts) {
     const key = await devGrant(ctx, opts.devPersona, opts.org);
     if (key) {
       ctx.apiKey = key;
-      const who = await whoami(ctx);
-      return `Authenticated to '${env}' as ${who?.email ?? ctx.organizationId ?? "(unknown)"} (dev persona ${opts.devPersona}).`;
+      await whoami(ctx);
+      return `Authenticated to '${env}' as ${ctx.principal ?? ctx.organizationId ?? "(unknown)"} (dev persona ${opts.devPersona}).`;
     }
     process.stdout.write(`The '${env}' server is not in development mode, so --as has no dev grant to use. Falling back to the browser grant.
 `);
   }
   ctx.apiKey = await deviceGrant(ctx);
-  const who = await whoami(ctx);
-  return `Authenticated to '${env}' as ${who?.email ?? ctx.organizationId ?? "(unknown)"}.`;
+  await whoami(ctx);
+  return `Authenticated to '${env}' as ${ctx.principal ?? ctx.organizationId ?? "(unknown)"}.`;
 }
 async function logout(config, env) {
   const ctx = config.contexts[env];
   if (!ctx?.apiKey)
     return `No stored key for '${env}'.`;
   await apiFetch(ctx, "/api/cli/logout", { method: "POST", body: {} });
+  await dropOrgKeys(ctx);
   ctx.apiKey = undefined;
   ctx.principal = undefined;
   return `Logged out of '${env}' (key revoked).`;
 }
 
 // src/dispatch.ts
-import { readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "node:fs";
+import { existsSync as existsSync3, readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "node:fs";
 
 // ../shared/ops/flag-parse.ts
 function acceptsNull(prop) {
@@ -386,6 +416,9 @@ function missMessage(catalog, argv) {
   const inApp = retiredPrefix(catalog.inApp, argv);
   if (inApp)
     return `\`${inApp.name}\` is not run from here. ${inApp.replacement}`;
+  const outOfScope = retiredPrefix(catalog.outOfScope, argv);
+  if (outOfScope)
+    return outOfScope.replacement;
   const retired = retiredPrefix(catalog.retired, argv);
   if (retired)
     return `\`${retired.name}\` is retired: ${retired.replacement}`;
@@ -406,12 +439,29 @@ function parseFlags(op, rest) {
   const parsed = parseFlagTokens(props, rest, CliUsageError);
   for (const [key, value] of Object.entries(parsed.input)) {
     const prop = props[key];
-    if (typeof value === "string" && value.startsWith("@") && prop && isBase64(prop)) {
+    if (typeof value !== "string" || !value.startsWith("@") || !prop)
+      continue;
+    if (isBase64(prop))
       parsed.input[key] = readBase64File(key, value.slice(1));
-    }
+    else if (isText(prop))
+      parsed.input[key] = readTextFlag(key, value.slice(1)) ?? value;
   }
   return parsed;
 }
+function isText(prop) {
+  return [prop, ...prop.anyOf ?? []].some((branch) => branch.type === "string" && !branch.enum);
+}
+function readTextFlag(flag, path) {
+  if (path === "-")
+    return readFileSync3(0, "utf8");
+  if (!existsSync3(path))
+    return null;
+  try {
+    return readFileSync3(path, "utf8");
+  } catch (err) {
+    throw new CliUsageError(`--${flag}: cannot read ${path} (${err.code ?? "error"})`);
+  }
+}
 function isBase64(prop) {
   return [prop, ...prop.anyOf ?? []].some((branch) => branch.contentEncoding === "base64");
 }
@@ -478,14 +528,19 @@ function opUsage(op) {
   }
   return parts.join(" ");
 }
-function renderCatalog(catalog) {
-  const lines = catalog.toSorted((a, b) => a.name.localeCompare(b.name)).map((op) => `  ${op.name}  —  ${op.description}`);
+function renderCatalog(catalog, group) {
+  const shown = group ? catalog.filter((op) => op.name === group || op.name.startsWith(`${group} `)) : catalog;
+  if (group && shown.length === 0) {
+    const groups = [...new Set(catalog.map((op) => op.name.split(" ")[0]))].toSorted();
+    return `No operations in '${group}'. Groups: ${groups.join(", ")}`;
+  }
+  const lines = shown.toSorted((a, b) => a.name.localeCompare(b.name)).map((op) => `  ${op.name}  —  ${op.description}`);
   return [
     "Run a Volty platform operation:  volty <operation> [--flags] [--json]",
     "",
     ...lines,
     "",
-    "`volty <operation> --help` shows usage; `--json` returns the machine-readable result."
+    "`volty help <group>` lists one group (`volty help chat-flow`); `volty <operation> --help` shows usage; `--json` returns the machine-readable result. A text flag takes a file as `--source=@flow.ts`, or stdin as `--source=@-`."
   ].join(`
 `);
 }
@@ -517,6 +572,35 @@ 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"]);
+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 === "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) {
@@ -553,12 +637,6 @@ function resolveTargetOrg({ env, baseUrl, override, sticky, command }) {
     return { org: undefined };
   return { refusal: PROD_ORG_REFUSAL };
 }
-function describeOrgTarget(orgs, org, env) {
-  const match = orgs.find((o) => o.organizationId === org);
-  if (!match)
-    return { refusal: `org ${org} is not one of your memberships on ${env}` };
-  return { line: `→ ${env} · ${match.name} (${match.organizationId}) · ${match.role}` };
-}
 
 // src/proposals.ts
 function decideProposal(ctx, proposalId, decision, reason) {
@@ -690,11 +768,11 @@ async function handleAuth(rest, config, env, orgOverride) {
     const ctx = config.contexts[env];
     if (!ctx?.apiKey)
       fail(`not logged in to '${env}' — run \`volty auth login --env ${env}\``);
-    const who = await whoami(ctx);
-    if (!who)
-      fail("the stored key did not validate — run `volty auth login --rotate`");
+    const res = await whoami(ctx);
+    if ("error" in res)
+      fail(res.error);
     saveConfig(config);
-    process.stdout.write(`${who.email ?? who.userId} · org ${who.organizationId} · role ${who.role}
+    process.stdout.write(`${res.who.email ?? res.who.userId} · org ${res.who.organizationId} · role ${res.who.role}
 `);
     return;
   }
@@ -778,23 +856,27 @@ async function handleOrg(rest, config, env, target) {
     const json = takeBool(rest.slice(1), "--json");
     if (!ctx.apiKey)
       fail(`not logged in to '${env}' — run \`volty auth login --env ${env}\``);
-    const res = await apiFetch(ctx, "/api/cli/orgs");
-    if (!res.ok || !res.body.orgs)
-      failResult("org list", res.body, res.status, json.present);
+    const orgs = [
+      { organizationId: ctx.organizationId ?? "", slug: ctx.organizationSlug ?? "", expiresAt: null },
+      ...Object.entries(ctx.orgKeys ?? {}).map(([organizationId, k]) => ({
+        organizationId,
+        slug: k.slug,
+        expiresAt: k.expiresAt ?? null
+      }))
+    ];
     if (json.present) {
-      process.stdout.write(`${JSON.stringify(res.body, null, 2)}
+      process.stdout.write(`${JSON.stringify({ orgs }, null, 2)}
 `);
       return;
     }
-    const active = target.org ?? res.body.current;
-    if (res.body.orgs.length === 0)
-      process.stdout.write(`(no org memberships)
-`);
-    for (const o of res.body.orgs) {
-      const marker = o.organizationId === active ? "*" : " ";
-      process.stdout.write(`${marker} ${o.organizationId}	${o.role}	${o.name}
+    for (const [i, o] of orgs.entries()) {
+      const active = target.org ? target.org === o.organizationId || target.org === o.slug : i === 0;
+      const note = i === 0 ? "signed in" : `expires ${o.expiresAt?.slice(0, 10) ?? "never"}`;
+      process.stdout.write(`${active ? "*" : " "} ${o.organizationId}	${o.slug}	${note}
 `);
     }
+    process.stdout.write(`Another workspace you belong to: pass --org <slug> and the CLI gets a key for it.
+`);
     return;
   }
   fail("usage: volty org <use|current|list>");
@@ -837,7 +919,7 @@ function handleSkill(rest) {
     join4(import.meta.dirname, "..", "skill", "volty-cli-ops", "SKILL.md"),
     join4(import.meta.dirname, "..", "..", ".claude", "skills", "volty-cli-ops", "SKILL.md")
   ];
-  const source = candidates.find((p) => existsSync3(p));
+  const source = candidates.find((p) => existsSync4(p));
   if (!source)
     fail("bundled SKILL.md not found — reinstall the @voltade/volty package");
   const destDir = join4(homedir3(), ".claude", "skills", "volty-cli-ops");
@@ -867,7 +949,6 @@ async function main() {
   });
   if ("refusal" in target)
     fail(target.refusal);
-  setOrgOverride(target.org);
   const [cmd, ...rest] = argv;
   if (cmd === "auth")
     return handleAuth(rest, config, env, orgExtract.value ?? (process.env.VOLTY_ORG || undefined));
@@ -879,21 +960,37 @@ async function main() {
     return handleDocs(config, env);
   if (cmd === "skill")
     return handleSkill(rest);
-  const ctx = config.contexts[env];
-  if (!ctx?.apiKey)
+  const login = config.contexts[env];
+  if (!login?.apiKey)
     fail(`not logged in to '${env}' — run \`volty auth login --env ${env}\``);
+  let ctx = login;
+  if (target.org) {
+    let selected;
+    try {
+      selected = await ensureOrgKey(login, target.org, (line) => process.stderr.write(`${line}
+`));
+    } catch (err) {
+      fail(err instanceof Error ? err.message : String(err));
+    }
+    if (selected.minted)
+      saveConfig(config);
+    ctx = { ...login, apiKey: selected.apiKey, organizationId: selected.organizationId };
+    setOrgOverride(selected.organizationId);
+  }
   if (prod && !isOrgFreeCommand(argv) && target.org) {
-    const described = describeOrgTarget(await fetchOrgs(ctx, env, !cacheFlag.present), target.org, env);
-    if ("refusal" in described)
-      fail(described.refusal);
-    process.stderr.write(`${described.line}
+    const res = await whoami(ctx);
+    if ("error" in res)
+      fail(res.error);
+    process.stderr.write(`→ ${env} · ${res.who.organizationName} (${res.who.organizationId}) · ${res.who.role}
 `);
   }
   if (cmd === "changes" && rest[0] === "decide")
     return handleChanges(rest, ctx);
+  if (cmd === "keys")
+    argv = keysArgv(argv);
   const catalog = await fetchCatalog(ctx, env, !cacheFlag.present);
   if (!cmd || cmd === "help" || cmd === "--help") {
-    process.stdout.write(`${renderCatalog(catalog.ops)}
+    process.stdout.write(`${renderCatalog(catalog.ops, rest.length ? rest.join(" ") : undefined)}
 `);
     return;
   }

package/package.json

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

package/skill/volty-cli-ops/SKILL.md

@@ -25,6 +25,7 @@ Use the lane the behaviour was reported on. On the contact lane Volty declines t
 
 ## On prod
 
+- A key reaches one org and calls operations only; `--org` gets each org you belong to its own key the first time. A call a key cannot make is refused with a sentence naming why; report that sentence instead of working around it. `volty keys create <name>` mints a narrower named key for a script (`volty docs` has the flags).
 - Name the org on every command (`--env prod --org <id>`, or `VOLTY_ENV` and `VOLTY_ORG` in the process), and read the stderr line the CLI prints before each command to check it names the org you meant. Act only in the org the user named.
 - Test through the Sandbox, where a reply to the synthetic contact is recorded as sent and never leaves. A real conversation is never a test target.
 - Run `volty debug sandbox-cleanup --all --env prod --org <id>` when you finish.