foldrun 14.4.0 → 15.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/bin/foldrun.mjs CHANGED
@@ -374,7 +374,7 @@ Options
374
374
  --tag <t> invoke, flow run: a label on the run — repeatable, sent as tags
375
375
  --inputs <set> invoke, flow run: the task is a saved input set (evals/<flow>-inputs.md, or an eval case for the flow)
376
376
  --preview storage cat: the platform reads the file and prints what is in it
377
- --ttl <days> storage share: how long the link works (default 7); --forever: it never expires
377
+ --ttl <days> storage share: how long the link works (default 7); --forever: it never expires (keys create: the key never expires)
378
378
  --into <folder/> storage put: upload under that folder of storage/
379
379
  --as <path> storage put: the path one uploaded file lands at; agent import: the name the copy gets
380
380
  --csv billing statement: the CSV file instead of the table
@@ -437,7 +437,7 @@ Options
437
437
  --authorize-param name=value connect, secrets clients add: an extra authorize-URL parameter the provider documents (repeatable — e.g. access_type=offline)
438
438
  --role <r> keys create, team invite: viewer, editor (default) or admin
439
439
  --no-send team invite: make the link, mail nothing
440
- --expires <span> keys create: when it stops working — 30d, 90d, 365d or never (default never)
440
+ --expires <span> keys create: when it stops working — 30d, 90d (default, as in the dashboard), 365d or never; --forever is never
441
441
  --grace <span> keys rotate: keep the old key working for 1h or 24h while you swap the new one in (default 0: revoked now)
442
442
  --a2a keys create: an A2A key for an outside agent — with --to <workspace> and --flows a,b; --max-tasks <n> caps its open tasks (1–100, default 10)
443
443
  --key-env <NAME> a2a call, a2a status, a2a cancel, a2a card: the environment variable holding the A2A key (default FOLDRUN_A2A_KEY) — a key is never taken on the command line
package/docs/api.md CHANGED
@@ -92,6 +92,7 @@ api workspaces/$WS/flows/publish/run -X POST # start a flow
92
92
  | | PUT | write (`path`, `content`, optional `message` — recorded on the revision, as `foldrun source put --message` sends it) |
93
93
  | | PATCH | move (`from`, `to`) |
94
94
  | | DELETE | remove (`path`) |
95
+ | `/api/workspaces/<ws>/source/share` | POST | **Move to shared**: a skill, tool, script, knowledge or memory file into the account library and out of the workspace, in one call — `path` (`skills/x/SKILL.md`, `tools/x/tool.md` or the folder moves the whole folder), `overwrite` (replace library files already there; `409` otherwise), `dryRun` (what would move, nothing written). Everything is checked first: a folder holding a file the library cannot hold (an image, a binary), one too large or with broken frontmatter is refused `409` and nothing changes. `{ ok, kind, unit, files: [{ from, to, replaces }], moved }`. Account-wide callers only (`workspace:write`), as for the library itself. Hooks are refused. Idempotent |
95
96
 
96
97
  Editing one file at a time. For a whole tree, deploy. The files this door
97
98
  writes are text: markdown, and a script's or a register's own formats —
package/docs/cli.md CHANGED
@@ -141,7 +141,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
141
141
  | `foldrun invoke <flow>` | start a flow on a running platform — `--watch` follows its trace here; `--test` makes it a [test run](runs#test-runs) `--once <key>` sends the key as the run's idempotency key, so a CI step that retries after a dropped response is answered with the run it already started instead of paying for a second. `--tag <t>`, repeatable, labels the run (the API's `tags`). `--inputs <name>` sends a saved input set as the task — a case of `evals/<flow>-inputs.md` or of an eval that runs the flow, as the platform has it (see [Run with saved inputs](flows#run-with-saved-inputs)). `foldrun flow run <flow>` is the same command |
142
142
  | `foldrun source <verb>` | one workspace file on a platform: `ls [dir]`, `cat <path>`, `put <path>` (from `--file`, else stdin; `--message` goes on the revision), `new <kind> <name>`, `mv <from> <to>`, `rm <path>` — the editor's own door, so every write is a revision. `new` is the dashboard's New button for any document (`POST …/assets { kind, name, agent?, template?, language? }`): `tools`, `knowledge`, `memory`, `skills`, `scripts` (and `agents`, `flows`, `evals`), the template written by the platform; `--agent <name>` puts a knowledge, memory, skill or script document inside that agent. For a whole tree, `deploy` |
143
143
  | `foldrun source put <path> --check` | the dashboard editor's checked save (`PUT …/source { check: true }`): a file a deploy would refuse is refused — HTTP 422, the issues printed with their rule ids, exit 1, nothing written; a save that passes prints its warnings. Without `--check` a save is written as before (the editor's **Save anyway**). `--empty` writes an empty file on purpose, as the file tree's **+ Add file** does; an empty input without it is refused, since that is nearly always a pipe that broke |
144
- | `foldrun source share <path>` | the dashboard's **Move to shared**: a skill, tool, script, knowledge or memory file into the account library (`PUT /api/library/<kind>`), then — only once every copy is written — out of the workspace (`DELETE …/source`). A skill or folder tool (`skills/x/SKILL.md`, `tools/x/tool.md`, or the folder) moves every text file of it (subfolders keep their place), and each is deleted from the workspace one by one, never the folder: anything the source API does not list — an image, a binary — stays in the workspace. A library file of the same path is refused unless `--overwrite`; `--dry-run` lists what would move; asks first (`--yes` with no terminal). A hook is refused — `hook add --library` makes a shared one. `--to <workspace>` |
144
+ | `foldrun source share <path>` | the dashboard's **Move to shared** (`POST /api/workspaces/<ws>/source/share`): a skill, tool, script, knowledge or memory file into the account library and out of the workspace, moved by the platform in one call. A skill or folder tool (`skills/x/SKILL.md`, `tools/x/tool.md`, or the folder) moves whole, subfolders in place. It lists what would move first (the platform's dry run), asks (`--yes` with no terminal), then moves. A folder holding a file the library cannot hold (an image, a binary) is refused and nothing moves; a library file of the same path is refused unless `--overwrite`; `--dry-run` stops after the list; `--json` prints the answer. A hook is refused — `hook add --library` makes a shared one. `--to <workspace>`; the library is every workspace's, so it needs an account-wide sign-in |
145
145
  | `foldrun open [page]` | the dashboard for this workspace, in the browser (`runs`, `agents`, `graph`, `repo`…) |
146
146
  | `foldrun login` | sign this machine in from the browser — no key to copy. Type the code it shows on the page and approve within five minutes |
147
147
  | `foldrun login <site> --url <address>` | a browser window to sign in to a site by hand; the session is stored for an agent |
@@ -250,7 +250,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
250
250
  | `--tag <t>` | `invoke`, `flow run`: a label on the run — repeatable |
251
251
  | `--inputs <name>` | `invoke`, `flow run`: the task is that saved input set; not with `--task` |
252
252
  | `--preview` | `storage cat`: the platform reads the file and prints what is in it |
253
- | `--ttl <days>`, `--forever` | `storage share`: how long the link works (default 7 days), or never expires |
253
+ | `--ttl <days>`, `--forever` | `storage share`: how long the link works (default 7 days), or never expires. `--forever` on `keys create`: the key never expires |
254
254
  | `--into <folder/>` | `storage put`: upload under that folder of `storage/` |
255
255
  | `--all` (storage) | `storage ls`: every workspace's storage; `storage shares`: expired and revoked links too |
256
256
  | `--backup <id>` | `backups request`: the snapshot to restore from, by its id (optional; `--at` names the point either way) |
@@ -302,7 +302,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
302
302
  | `--generate-key` | with `--token-auth jwt`: foldrun makes the key (EC P-256) and prints the public JWK to register with the provider; `connect` waits for Enter before it opens the consent |
303
303
  | `--role <r>` | `keys create`, `team invite`: `viewer`, `editor` (default) or `admin` |
304
304
  | `--no-send` | `team invite`: make the link and mail nothing |
305
- | `--expires <span>` | `keys create`: when it stops working — `30d`, `90d`, `365d` or `never` (default) |
305
+ | `--expires <span>` | `keys create`: when it stops working — `30d`, `90d` (the default, as in the dashboard; before CLI 15.0.0 the default was never), `365d` or `never`; `--forever` is `never` |
306
306
  | `--grace <span>` | `keys rotate`: keep the old key working for `1h` or `24h` (default `0`: revoked now) |
307
307
  | `--a2a` | `keys create`: an A2A key for an outside agent, with `--to <workspace>`, `--flows a,b` and optionally `--max-tasks <n>` |
308
308
  | `--key-env <NAME>` | `a2a call`, `a2a status`, `a2a cancel`, `a2a card`: the environment variable that holds the A2A key (default `FOLDRUN_A2A_KEY`) |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "foldrun",
3
- "version": "14.4.0",
3
+ "version": "15.0.0",
4
4
  "description": "Agents are just folders. Write them, check them, run them — on your machine.",
5
5
  "license": "FSL-1.1-ALv2",
6
6
  "type": "module",
@@ -11,7 +11,7 @@
11
11
  "node": ">=22"
12
12
  },
13
13
  "dependencies": {
14
- "@foldrun/core": "^14.3.4"
14
+ "@foldrun/core": "^14.3.5"
15
15
  },
16
16
  "files": [
17
17
  "bin",
package/src/commands.mjs CHANGED
@@ -4730,8 +4730,12 @@ async function keysCmd(positional, flags) {
4730
4730
  if (flags.a2a === true) return keysCreateA2a(url, arg, flags);
4731
4731
  const body = { label: arg };
4732
4732
  if (typeof flags.role === "string") body.role = flags.role;
4733
- // --expires 30d|90d|365d|never; unsaid, the key never expires.
4734
- if (typeof flags.expires === "string") body.expires = flags.expires;
4733
+ // --expires 30d|90d|365d|never (--forever is never); unsaid, 90 days —
4734
+ // the dashboard's default since it was built, and the CLI's since
4735
+ // 5 Nov 2026: a key that ends is a key that cannot leak forever.
4736
+ if (flags.forever === true && flags.expires !== undefined) throw new Error("--forever or --expires <span>, not both");
4737
+ if (flags.expires !== undefined && typeof flags.expires !== "string") throw new Error("--expires needs a span: 30d, 90d, 365d or never");
4738
+ body.expires = flags.forever === true ? "never" : typeof flags.expires === "string" ? flags.expires : "90d";
4735
4739
  // --workspaces a,b narrows the key to those; --workspaces all opens
4736
4740
  // every one you can. Unsaid, the key inherits your own scope.
4737
4741
  if (typeof flags.workspaces === "string") body.workspaces = flags.workspaces === "all" ? null : flags.workspaces.split(",").map((w) => w.trim()).filter(Boolean);
@@ -4983,110 +4987,65 @@ async function sourceCmd(positional, flags) {
4983
4987
  throw new Error(`source: unknown verb "${verb}" — ls, cat, put, new, mv, rm, share`);
4984
4988
  }
4985
4989
 
4986
- /** The workspace folders "Move to shared" applies to — the library kinds
4987
- * but hooks (`foldrun hook add --library` makes a shared one). */
4988
- const SHAREABLE_KINDS = ["skills", "tools", "scripts", "knowledge", "memory"];
4989
-
4990
4990
  /**
4991
4991
  * `foldrun source share <path> --to <ws>` — the dashboard's "Move to shared":
4992
- * the file goes into the account library (PUT /api/library/<kind>) and,
4993
- * once it is safely there, out of the workspace (DELETE …/source). A skill
4994
- * or folder tool moves whole — every file of its folder, where the
4995
- * dashboard copies the one file it shows — and subfolders keep their
4996
- * place. A library file of the same path is refused unless --overwrite;
4997
- * --dry-run lists what would move. Asks first (--yes with no terminal):
4998
- * it leaves this workspace and every workspace in the account can use it.
4992
+ * POST /api/workspaces/<ws>/source/share, which moves it on the server in one
4993
+ * call. A skill or folder tool (skills/x/SKILL.md, tools/x/tool.md, or the
4994
+ * folder) moves whole; a folder holding a file the library cannot hold (an
4995
+ * image, a binary) is refused and nothing moves. It asks the platform what
4996
+ * would move first (dryRun), lists it, asks (--yes with no terminal), then
4997
+ * moves. A library file of the same path is refused unless --overwrite;
4998
+ * --dry-run stops after the list. Done here file by file (4 Nov) it could
4999
+ * not delete a skill's SKILL.md alone, nor reach its other files safely.
4999
5000
  */
5000
5001
  async function sourceShare(url, flags, ws, base, spec) {
5001
5002
  if (!spec) throw new Error("which file? `foldrun source share skills/house-style --to <workspace>` — a skill, tool, script, knowledge or memory file");
5002
- const clean = spec.replace(/^(\.\/)+/, "").replace(/\/+$/, "");
5003
- const [kind, ...rest] = clean.split("/");
5004
- if (kind === "hooks") throw new Error("a hook is a folder whose run.mjs goes with it — `foldrun hook add <name> --library` makes a shared one");
5005
- if (!SHAREABLE_KINDS.includes(kind) || !rest.length) throw new Error(`"${spec}" is not under ${SHAREABLE_KINDS.join("/, ")}/ — only those move to the shared library`);
5006
- // skills/x/SKILL.md or tools/x/tool.md names its folder: the folder is the thing.
5007
- const unit = (kind === "skills" || kind === "tools") && rest.length >= 2 ? `${kind}/${rest[0]}` : clean;
5008
- const { files = [] } = await remoteCall(url, flags, base);
5009
- const members = files.filter((f) => f === unit || f.startsWith(`${unit}/`));
5010
- if (!members.length) throw new Error(`no ${unit} in ${ws} — \`foldrun source ls ${kind} --to ${ws}\` lists what is there`);
5011
- const relOf = (f) => f.slice(kind.length + 1);
5012
-
5013
- /** Which of these the library already has. */
5014
- const inLibrary = async (list) => {
5015
- const hits = [];
5016
- for (const f of list) {
5017
- try {
5018
- await remoteCall(url, flags, `/api/library/${kind}?path=${enc(relOf(f))}`);
5019
- hits.push(f);
5020
- } catch (err) {
5021
- if (!(err instanceof HttpError) || !(err.status === 404 || /not found/i.test(err.message))) throw err;
5022
- }
5003
+ const route = `/api/workspaces/${enc(ws)}/source/share`;
5004
+ const ask = (extra) => remoteCall(url, flags, route, { method: "POST", body: JSON.stringify({ path: spec, ...(flags.overwrite === true ? { overwrite: true } : {}), ...extra }) });
5005
+ let plan;
5006
+ try {
5007
+ plan = await ask({ dryRun: true });
5008
+ } catch (err) {
5009
+ // The route's own 404 says "no <path> in <ws>"; any other 404 is a
5010
+ // platform from before the route.
5011
+ if (err instanceof HttpError && err.status === 404 && !/^no /.test(err.message)) {
5012
+ throw new Error(`${url} has no "Move to shared" route yet — it is newer than this platform; move it in Settings → the workspace's assets, or update the platform`);
5023
5013
  }
5024
- return hits;
5025
- };
5026
- const taken = await inLibrary(members);
5027
- console.log(`\n ${c.bold(unit)} ${c.dim(`· ${ws} → the shared library`)}\n`);
5028
- for (const f of members) console.log(` ${c.dim("·")} ${f} → library/${kind}/${relOf(f)}${taken.includes(f) ? c.amber(" (the library has one — replaced)") : ""}`);
5029
- console.log();
5014
+ throw err;
5015
+ }
5016
+ const json = flags.json === true;
5017
+ const taken = plan.files.filter((f) => f.replaces);
5018
+ // --json: the platform's answer and nothing else — the plan on a dry run
5019
+ // or a refusal, the move's answer once moved.
5020
+ if (json && (flags["dry-run"] === true || (taken.length && flags.overwrite !== true))) {
5021
+ console.log(JSON.stringify(plan, null, 2));
5022
+ return taken.length && flags.overwrite !== true ? 1 : 0;
5023
+ }
5024
+ if (!json) {
5025
+ console.log(`\n ${c.bold(plan.unit)} ${c.dim(`· ${ws} → the shared library`)}\n`);
5026
+ for (const f of plan.files) console.log(` ${c.dim("·")} ${f.from} → library/${plan.kind}/${f.to}${f.replaces ? c.amber(" (the library has one — replaced)") : ""}`);
5027
+ console.log();
5028
+ }
5030
5029
  if (taken.length && flags.overwrite !== true) {
5031
- console.log(` ${c.red("✗")} the library already has ${taken.map((f) => `${kind}/${relOf(f)}`).join(", ")} — nothing was moved; --overwrite replaces ${taken.length === 1 ? "it" : "them"}\n`);
5030
+ console.log(` ${c.red("✗")} the library already has ${taken.map((f) => `${plan.kind}/${f.to}`).join(", ")} — nothing was moved; --overwrite replaces ${taken.length === 1 ? "it" : "them"}\n`);
5032
5031
  return 1;
5033
5032
  }
5034
5033
  if (flags["dry-run"] === true) {
5035
5034
  console.log(` ${c.dim("--dry-run: nothing moved")}\n`);
5036
5035
  return 0;
5037
5036
  }
5038
- if (!(await confirmed(flags, "source share", `Move ${unit} to shared? Every workspace in the account will be able to use it, and it leaves ${ws}. [y/N] `))) {
5037
+ if (!(await confirmed(flags, "source share", `Move ${plan.unit} to shared? Every workspace in the account will be able to use it, and it leaves ${ws}. [y/N] `))) {
5039
5038
  console.log(`\n ${c.dim("nothing moved")}\n`);
5040
5039
  return 0;
5041
5040
  }
5042
- // Asked again after the question, which may have waited a long time: a
5043
- // library file made meanwhile is not replaced without --overwrite. (The
5044
- // library PUT takes no ifMatch, so this narrows the window, no more.)
5045
- if (flags.overwrite !== true) {
5046
- const since = await inLibrary(members);
5047
- if (since.length) throw new Error(`the library now has ${since.map((f) => `${kind}/${relOf(f)}`).join(", ")} — made while this waited; nothing was moved (--overwrite replaces it)`);
5048
- }
5049
- const copied = new Map();
5050
- for (const f of members) {
5051
- const { content } = await remoteCall(url, flags, `${base}?path=${enc(f)}`);
5052
- copied.set(f, content ?? "");
5053
- try {
5054
- await remoteCall(url, flags, `/api/library/${kind}`, { method: "PUT", body: JSON.stringify({ path: relOf(f), content: content ?? "" }) });
5055
- } catch (err) {
5056
- throw new Error(`could not copy ${f} to the library — ${explain(err)}. ${unit} is still in ${ws}${f === members[0] ? "" : "; what was copied before it is in the library too"}`);
5057
- }
5058
- }
5059
- // The DELETE takes no ifMatch, so read it all again first: a file edited
5060
- // or added while this copied would be deleted without ever reaching the
5061
- // library. Changed, it stays in both places and nothing is deleted.
5062
- const { files: now = [] } = await remoteCall(url, flags, base);
5063
- const nowMembers = now.filter((f) => f === unit || f.startsWith(`${unit}/`));
5064
- const moved = [];
5065
- for (const f of nowMembers) {
5066
- if (!copied.has(f)) moved.push(f);
5067
- else if ((await remoteCall(url, flags, `${base}?path=${enc(f)}`)).content !== copied.get(f)) moved.push(f);
5068
- }
5069
- if (moved.length) {
5070
- throw new Error(`copied to shared, but ${moved.join(", ")} changed in ${ws} while it was copied — nothing was deleted, so it is in both places; run it again with --overwrite to copy the new text`);
5071
- }
5072
- // Only once every file is in the library, and only the files that were
5073
- // copied, one by one — never the folder: the source API lists text files
5074
- // alone, so deleting a skill's folder would take an image or other asset
5075
- // in it that never reached the library. A failure leaves the rest in both
5076
- // places, never in neither, and says so.
5077
- for (const [i, f] of members.entries()) {
5078
- try {
5079
- await remoteCall(url, flags, base, { method: "DELETE", body: JSON.stringify({ path: f }) });
5080
- } catch (err) {
5081
- const left = members.slice(i);
5082
- throw new Error(`copied to shared, but ${f} could not be removed from ${ws} — ${explain(err)}. ${left.length === 1 ? "It is" : `These ${left.length} are`} in both now; ${left.map((x) => `\`foldrun source rm ${x} --to ${ws}\``).join(", ")} finish${left.length === 1 ? "es" : ""} the move`);
5083
- }
5084
- }
5085
- console.log(` ${c.green("✓")} ${unit} ${c.dim(`moved to library/${kind}/${relOf(unit)} — every workspace in the account can use it`)}`);
5086
- if (unit !== clean || members.length > 1 || members[0] !== unit) {
5087
- console.log(` ${c.dim(`only its text files move: anything else in ${unit}/ (an image, a binary) stays in ${ws}`)}`);
5041
+ // The platform checks it all again: a library file made while this asked
5042
+ // is refused (409) without --overwrite, and nothing moves.
5043
+ const done = await ask({});
5044
+ if (flags.json === true) {
5045
+ console.log(JSON.stringify(done, null, 2));
5046
+ return 0;
5088
5047
  }
5089
- console.log();
5048
+ console.log(` ${c.green("✓")} ${done.unit} ${c.dim(`moved to library/${done.kind}/${done.unit.slice(done.kind.length + 1)} — every workspace in the account can use it`)}\n`);
5090
5049
  return 0;
5091
5050
  }
5092
5051