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 +2 -2
- package/docs/api.md +1 -0
- package/docs/cli.md +3 -3
- package/package.json +2 -2
- package/src/commands.mjs +48 -89
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
|
|
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
|
|
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
|
|
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": "
|
|
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.
|
|
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,
|
|
4734
|
-
|
|
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
|
-
*
|
|
4993
|
-
*
|
|
4994
|
-
*
|
|
4995
|
-
*
|
|
4996
|
-
*
|
|
4997
|
-
*
|
|
4998
|
-
*
|
|
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
|
|
5003
|
-
const
|
|
5004
|
-
|
|
5005
|
-
|
|
5006
|
-
|
|
5007
|
-
|
|
5008
|
-
|
|
5009
|
-
|
|
5010
|
-
|
|
5011
|
-
|
|
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
|
-
|
|
5025
|
-
}
|
|
5026
|
-
const
|
|
5027
|
-
|
|
5028
|
-
|
|
5029
|
-
|
|
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}/${
|
|
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
|
-
//
|
|
5043
|
-
//
|
|
5044
|
-
|
|
5045
|
-
if (flags.
|
|
5046
|
-
|
|
5047
|
-
|
|
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
|
|