@solidactions/cli 3.19.0 → 3.20.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/README.md +19 -3
- package/dist/command-manifest.json +148 -1
- package/dist/commands/role-pull.js +215 -0
- package/dist/commands/role-push.js +226 -44
- package/dist/commands/skill-publish.js +12 -4
- package/dist/commands/skill-pull.js +144 -66
- package/dist/commands/skill-push.js +89 -24
- package/dist/index.js +22 -0
- package/dist/utils/atomic-dir.js +111 -0
- package/dist/utils/crew.js +31 -0
- package/dist/utils/mcp.js +129 -19
- package/dist/utils/mutating-commands.js +1 -0
- package/dist/utils/skill-snapshot.js +15 -6
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -450,10 +450,11 @@ Manage agent skills on the crews SOP surface. `push` is an idempotent upsert (cr
|
|
|
450
450
|
|
|
451
451
|
| Command | Key Flags | Description |
|
|
452
452
|
|---------|-----------|-------------|
|
|
453
|
-
| `skill push <dir>` | `--role <name>`, `--dry-run`, `--json`, `--force` | Push a skill folder, or a whole plugin dir — recursive: pushes every `skills/*/SKILL.md`, converts `commands/*.md` → skills, and ingests each skill's `references/`. `--role` scopes to a role instead of the shared library. Drift-guarded against the local `.solidactions-skill.json` sidecar revision; `--force` skips the guard |
|
|
453
|
+
| `skill push <dir>` | `--role <name>`, `--in-crew <crew>`, `--dry-run`, `--publish`, `--json`, `--force` | Push a skill folder, or a whole plugin dir — recursive: pushes every `skills/*/SKILL.md`, converts `commands/*.md` → skills, and ingests each skill's `references/`. `--role` scopes to a role instead of the shared library; `--in-crew` names the crew that holds the role (with `--role`, to disambiguate a role name that exists in several crews). `--publish` snapshots the skill after pushing so it goes live for agents. Drift-guarded against the local `.solidactions-skill.json` sidecar revision; `--force` skips the guard |
|
|
454
|
+
| `skill publish <name>` | `--role <name>`, `--in-crew <crew>`, `--json` | Publish (snapshot) a skill so its latest pushed revision goes live for agents. With `--role`, publishes that role's role-scoped skill instead of a shared-library skill; `--in-crew` disambiguates the role across crews |
|
|
454
455
|
| `skill list` | `--json`, `--limit <n>` | List skills in the library |
|
|
455
456
|
| `skill view <name>` | `--json` | Show one skill |
|
|
456
|
-
| `skill pull <name> [dest]` | `--json` | Fetch a skill to a local folder for editing (inverse of push);
|
|
457
|
+
| `skill pull <name> [dest]` | `--role <role>`, `--in-crew <crew>`, `--json` | Fetch a skill to a local folder for editing (inverse of push); `dest` defaults to `./<name>/`. `--role` pulls a role-scoped skill of that role instead of a shared-library skill; `--in-crew` disambiguates the role across crews. Writes a `.solidactions-skill.json` provenance sidecar used by `push`'s drift guard. `--json` prints the raw read result and writes no files |
|
|
457
458
|
| `skill delete <name>` | `--json` | Delete a skill (Admin only) |
|
|
458
459
|
| `skill exec <name> --target sandbox -- <cmd>` (`--target` required) | `--role <name>`, `--in-crew <crew>`, `--environment <env>` (default `production`) | Execute the server-stored skill in its server sandbox (post-push smoke; default env production) |
|
|
459
460
|
| `skill exec <name> --target host -- <cmd>` (`--target` required) | `--role <name>`, `--in-crew <crew>`, `--crew <nameOrId>`, `--environment <env>` (default `production`), `--env-file <path>` | Execute the server-stored skill on THIS machine via a transparent revision-checked cache — no pull step; crew vars fetched from the platform (default env production; secrets need `env:reveal`) |
|
|
@@ -469,11 +470,26 @@ variables; `dev` defaults to `dev`.
|
|
|
469
470
|
|
|
470
471
|
For `skill dev` / `skill exec`, pass the command as separate words after `--` (e.g. `-- python script.py --flag`); to run a single preformed shell string, wrap it explicitly with `sh -c '...'`.
|
|
471
472
|
|
|
473
|
+
**Frontmatter keys.** Frontmatter keys outside the server schema are stored under `metadata` (values that aren't strings are JSON-encoded), and push prints which keys were folded.
|
|
474
|
+
|
|
472
475
|
### role
|
|
473
476
|
|
|
474
477
|
| Command | Key Flags | Description |
|
|
475
478
|
|---------|-----------|-------------|
|
|
476
|
-
| `role push <dir>` | `--dry-run`, `--json` | Push a role definition (create or update) |
|
|
479
|
+
| `role push <dir>` | `--in-crew <crew>`, `--replace-links`, `--dry-run`, `--json` | Push a role definition (create or update). `--in-crew` names the crew that holds the role; it is **required to create** a role, and disambiguates the name when it exists in several crews. Without it, an existing role that has that name in exactly one crew is updated in place |
|
|
480
|
+
| `role pull <name> [dir]` | `--in-crew <crew>`, `--no-skills` | Fetch a role and its role-scoped skills to a local folder (inverse of push); `dir` defaults to `./<name>/`. Writes `SKILL.md`, a `.solidactions-role.json` provenance sidecar and `skills/<skill>/` for each role-scoped skill. `--no-skills` pulls the role only. `--in-crew` disambiguates a role name that exists in several crews |
|
|
481
|
+
|
|
482
|
+
**`skill pull` and `role pull` replace the destination atomically.** A pull builds the new folder as `<dest>.tmp-*` beside the destination and then swaps it in, so a failed pull leaves the previous copy untouched. If the process is killed mid-swap, `<dest>.old-*` is the previous copy (rename it back to `<dest>`) and `<dest>.tmp-*` can be deleted. A pull refuses to replace an existing non-empty folder unless it carries the marker file from an earlier pull — `.solidactions-skill.json` for `skill pull`, `.solidactions-role.json` for `role pull` — so a directory that is not a pulled skill or role is never overwritten (nor is the current directory or one of its parents, nor a plain file). The check runs before any network call or write; remove the folder or choose another destination to proceed.
|
|
483
|
+
|
|
484
|
+
**`role pull` pulls the role's published version, with effective values.** A versioned role must have a snapshot (or use `version_mode: live`). Properties the role inherits (`inherits_from`) are merged by the server and pulled as the *effective* value; for such a role, pushing the pulled folder back would store the inherited values on the child, so `role pull` prints a warning. The role's skill preload settings are exported too: `always_load_skills` and `available_skills` are written to the `SKILL.md` frontmatter as skill identifiers (for example `shared/triage`), in the server's order, and `role push` sends them back. Skills in the role's own `skills/` folder are found by the server automatically, so they are not listed in `available_skills`; they travel in `skills/`. Like properties, these lists are the effective merged values.
|
|
485
|
+
|
|
486
|
+
**Creating a role requires `--in-crew`; updating one usually does not.** `role push <dir> --in-crew <crew>` creates the role in that crew if it does not exist and updates it if it does; the crew is never read from the folder's frontmatter. Without `--in-crew`, `role push` looks the role up by name first: if exactly one role has that name it is updated (in its own crew), if none does the push stops and asks for `--in-crew` (a create needs a crew), and if several crews have a role with that name it stops and asks you to choose with `--in-crew`. `--dry-run` follows the same lookup and reports the same result (or the same error) as the real push.
|
|
487
|
+
|
|
488
|
+
**Skill links are preserved on push unless you change them.** `role pull` records the `always_load_skills` and `available_skills` it wrote in `.solidactions-role.json`, along with the role's crew (normalised) and doc id. When you push that folder back to the same role, a link list that still equals the recorded one is kept as it is on the server: it is left out of the update, so every link survives, including skills you cannot see. `role push --dry-run` says which lists it keeps. If you edit a list (a reorder counts, and so does a blank `always_load_skills:`), `role push` exits 1 unless you pass `--replace-links`, because replacing the list deletes links you cannot see. With `--replace-links`, a list you removed from the frontmatter (or left blank) is cleared on the server. Creating a role, or pushing a folder with no `.solidactions-role.json`, sends the lists as written. `--dry-run` applies the same check.
|
|
489
|
+
|
|
490
|
+
**Rate limits.** The server throttles the MCP endpoint that `skill` and `role` use to 60 calls per minute per token. On HTTP 429 the CLI waits the `Retry-After` interval (in seconds or an HTTP date, capped at 60s; 5s if the header is missing or invalid), prints `rate limited by server (429); retrying in <N>s` to stderr, and tries up to 3 times in total before failing with `MCP request failed with HTTP 429`.
|
|
491
|
+
|
|
492
|
+
**Frontmatter keys.** Frontmatter keys outside the server schema are stored under `metadata` (values that aren't strings are JSON-encoded), and push prints which keys were folded.
|
|
477
493
|
|
|
478
494
|
### doc
|
|
479
495
|
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"schema_version": 1,
|
|
3
3
|
"cli_name": "solidactions",
|
|
4
|
-
"cli_version": "3.
|
|
4
|
+
"cli_version": "3.20.0",
|
|
5
5
|
"global_options": [
|
|
6
6
|
{
|
|
7
7
|
"flags": "-V, --version",
|
|
@@ -4829,6 +4829,18 @@
|
|
|
4829
4829
|
"negated": false,
|
|
4830
4830
|
"hidden": false
|
|
4831
4831
|
},
|
|
4832
|
+
{
|
|
4833
|
+
"flags": "--in-crew <crew>",
|
|
4834
|
+
"long": "--in-crew",
|
|
4835
|
+
"short": null,
|
|
4836
|
+
"description": "Crew containing the role (with --role; disambiguates roles in multiple crews)",
|
|
4837
|
+
"required": false,
|
|
4838
|
+
"value_required": true,
|
|
4839
|
+
"value_optional": false,
|
|
4840
|
+
"variadic": false,
|
|
4841
|
+
"negated": false,
|
|
4842
|
+
"hidden": false
|
|
4843
|
+
},
|
|
4832
4844
|
{
|
|
4833
4845
|
"flags": "--json",
|
|
4834
4846
|
"long": "--json",
|
|
@@ -4909,6 +4921,30 @@
|
|
|
4909
4921
|
}
|
|
4910
4922
|
],
|
|
4911
4923
|
"options": [
|
|
4924
|
+
{
|
|
4925
|
+
"flags": "--role <name>",
|
|
4926
|
+
"long": "--role",
|
|
4927
|
+
"short": null,
|
|
4928
|
+
"description": "Publish a role-scoped skill of this role instead of a shared-library skill",
|
|
4929
|
+
"required": false,
|
|
4930
|
+
"value_required": true,
|
|
4931
|
+
"value_optional": false,
|
|
4932
|
+
"variadic": false,
|
|
4933
|
+
"negated": false,
|
|
4934
|
+
"hidden": false
|
|
4935
|
+
},
|
|
4936
|
+
{
|
|
4937
|
+
"flags": "--in-crew <crew>",
|
|
4938
|
+
"long": "--in-crew",
|
|
4939
|
+
"short": null,
|
|
4940
|
+
"description": "Crew containing the role (with --role; disambiguates roles in multiple crews)",
|
|
4941
|
+
"required": false,
|
|
4942
|
+
"value_required": true,
|
|
4943
|
+
"value_optional": false,
|
|
4944
|
+
"variadic": false,
|
|
4945
|
+
"negated": false,
|
|
4946
|
+
"hidden": false
|
|
4947
|
+
},
|
|
4912
4948
|
{
|
|
4913
4949
|
"flags": "--json",
|
|
4914
4950
|
"long": "--json",
|
|
@@ -4959,6 +4995,30 @@
|
|
|
4959
4995
|
}
|
|
4960
4996
|
],
|
|
4961
4997
|
"options": [
|
|
4998
|
+
{
|
|
4999
|
+
"flags": "--role <role>",
|
|
5000
|
+
"long": "--role",
|
|
5001
|
+
"short": null,
|
|
5002
|
+
"description": "Pull a role-scoped skill of this role instead of a shared-library skill",
|
|
5003
|
+
"required": false,
|
|
5004
|
+
"value_required": true,
|
|
5005
|
+
"value_optional": false,
|
|
5006
|
+
"variadic": false,
|
|
5007
|
+
"negated": false,
|
|
5008
|
+
"hidden": false
|
|
5009
|
+
},
|
|
5010
|
+
{
|
|
5011
|
+
"flags": "--in-crew <crew>",
|
|
5012
|
+
"long": "--in-crew",
|
|
5013
|
+
"short": null,
|
|
5014
|
+
"description": "Crew containing the role (with --role; disambiguates roles in multiple crews)",
|
|
5015
|
+
"required": false,
|
|
5016
|
+
"value_required": true,
|
|
5017
|
+
"value_optional": false,
|
|
5018
|
+
"variadic": false,
|
|
5019
|
+
"negated": false,
|
|
5020
|
+
"hidden": false
|
|
5021
|
+
},
|
|
4962
5022
|
{
|
|
4963
5023
|
"flags": "--json",
|
|
4964
5024
|
"long": "--json",
|
|
@@ -5443,6 +5503,30 @@
|
|
|
5443
5503
|
}
|
|
5444
5504
|
],
|
|
5445
5505
|
"options": [
|
|
5506
|
+
{
|
|
5507
|
+
"flags": "--in-crew <crew>",
|
|
5508
|
+
"long": "--in-crew",
|
|
5509
|
+
"short": null,
|
|
5510
|
+
"description": "Crew that contains the role (required to create a role; disambiguates when the name exists in several crews)",
|
|
5511
|
+
"required": false,
|
|
5512
|
+
"value_required": true,
|
|
5513
|
+
"value_optional": false,
|
|
5514
|
+
"variadic": false,
|
|
5515
|
+
"negated": false,
|
|
5516
|
+
"hidden": false
|
|
5517
|
+
},
|
|
5518
|
+
{
|
|
5519
|
+
"flags": "--replace-links",
|
|
5520
|
+
"long": "--replace-links",
|
|
5521
|
+
"short": null,
|
|
5522
|
+
"description": "Replace always_load_skills / available_skills even when they differ from what role pull recorded (the server may hold links you cannot see)",
|
|
5523
|
+
"required": false,
|
|
5524
|
+
"value_required": false,
|
|
5525
|
+
"value_optional": false,
|
|
5526
|
+
"variadic": false,
|
|
5527
|
+
"negated": false,
|
|
5528
|
+
"hidden": false
|
|
5529
|
+
},
|
|
5446
5530
|
{
|
|
5447
5531
|
"flags": "--dry-run",
|
|
5448
5532
|
"long": "--dry-run",
|
|
@@ -5481,6 +5565,69 @@
|
|
|
5481
5565
|
}
|
|
5482
5566
|
]
|
|
5483
5567
|
},
|
|
5568
|
+
{
|
|
5569
|
+
"path": [
|
|
5570
|
+
"role",
|
|
5571
|
+
"pull"
|
|
5572
|
+
],
|
|
5573
|
+
"name": "pull",
|
|
5574
|
+
"aliases": [],
|
|
5575
|
+
"description": "Fetch a role and its role-scoped skills to a local folder (inverse of push)\n\nPulls the role's PUBLISHED version: a versioned role must have a snapshot (or use version_mode: live).\nInherited properties are merged by the server (RoleActivator) and are pulled as the effective value.\nFor a role with inherits_from, pushing the pulled folder back would store the inherited values on the child (a warning is printed).\nWrites SKILL.md, .solidactions-role.json and skills/<skill>/ in one atomic replace of the folder.",
|
|
5576
|
+
"hidden": false,
|
|
5577
|
+
"arguments": [
|
|
5578
|
+
{
|
|
5579
|
+
"name": "name",
|
|
5580
|
+
"required": true,
|
|
5581
|
+
"variadic": false,
|
|
5582
|
+
"description": "Role name"
|
|
5583
|
+
},
|
|
5584
|
+
{
|
|
5585
|
+
"name": "dir",
|
|
5586
|
+
"required": false,
|
|
5587
|
+
"variadic": false,
|
|
5588
|
+
"description": "Destination directory (defaults to ./<name>/)"
|
|
5589
|
+
}
|
|
5590
|
+
],
|
|
5591
|
+
"options": [
|
|
5592
|
+
{
|
|
5593
|
+
"flags": "--in-crew <crew>",
|
|
5594
|
+
"long": "--in-crew",
|
|
5595
|
+
"short": null,
|
|
5596
|
+
"description": "Crew that contains the role (disambiguates when the name exists in several crews)",
|
|
5597
|
+
"required": false,
|
|
5598
|
+
"value_required": true,
|
|
5599
|
+
"value_optional": false,
|
|
5600
|
+
"variadic": false,
|
|
5601
|
+
"negated": false,
|
|
5602
|
+
"hidden": false
|
|
5603
|
+
},
|
|
5604
|
+
{
|
|
5605
|
+
"flags": "--no-skills",
|
|
5606
|
+
"long": "--no-skills",
|
|
5607
|
+
"short": null,
|
|
5608
|
+
"description": "Pull the role only, without its role-scoped skills",
|
|
5609
|
+
"required": false,
|
|
5610
|
+
"value_required": false,
|
|
5611
|
+
"value_optional": false,
|
|
5612
|
+
"variadic": false,
|
|
5613
|
+
"negated": true,
|
|
5614
|
+
"hidden": false,
|
|
5615
|
+
"default": true
|
|
5616
|
+
},
|
|
5617
|
+
{
|
|
5618
|
+
"flags": "-h, --help",
|
|
5619
|
+
"long": "--help",
|
|
5620
|
+
"short": "-h",
|
|
5621
|
+
"description": "display help for command",
|
|
5622
|
+
"required": false,
|
|
5623
|
+
"value_required": false,
|
|
5624
|
+
"value_optional": false,
|
|
5625
|
+
"variadic": false,
|
|
5626
|
+
"negated": false,
|
|
5627
|
+
"hidden": false
|
|
5628
|
+
}
|
|
5629
|
+
]
|
|
5630
|
+
},
|
|
5484
5631
|
{
|
|
5485
5632
|
"path": [
|
|
5486
5633
|
"role",
|
|
@@ -0,0 +1,215 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
/**
|
|
3
|
+
* solidactions role pull <name> [dir] [--in-crew <crew>] [--no-skills]
|
|
4
|
+
*
|
|
5
|
+
* Fetches a role's PUBLISHED definition from the crews library and reconstructs a
|
|
6
|
+
* local role folder that `role push` accepts as a no-op:
|
|
7
|
+
*
|
|
8
|
+
* <dir>/SKILL.md role frontmatter + body (the format role push reads)
|
|
9
|
+
* <dir>/.solidactions-role.json provenance sidecar (name, in_crew, ...); also the
|
|
10
|
+
* marker that lets a later pull replace this folder
|
|
11
|
+
* <dir>/skills/<skill>/... each role-scoped skill (unless --no-skills), in the
|
|
12
|
+
* same layout as `skill pull --role`
|
|
13
|
+
*
|
|
14
|
+
* Everything is fetched first and then written with ONE writeDirAtomic, so a failed
|
|
15
|
+
* fetch writes nothing and a successful pull replaces the folder as a unit.
|
|
16
|
+
*
|
|
17
|
+
* The role's skill preload configuration is not a property: the server stores
|
|
18
|
+
* always_load_skills / available_skills as role_skill_links rows and returns them top-level
|
|
19
|
+
* in `read`. They are exported into the always_load_skills / available_skills frontmatter
|
|
20
|
+
* fields (identifiers such as "shared/triage", in the server's order), which role push sends
|
|
21
|
+
* back top-level. Skills that sit in the role's own skills/ folder are auto-discovered by the
|
|
22
|
+
* server and appear in its available_skills index under a bare name; those are not links, so
|
|
23
|
+
* bare names are left out of available_skills (they travel in skills/ instead).
|
|
24
|
+
*
|
|
25
|
+
* Inherited properties and skill links are merged by the server (RoleActivator) and are pulled
|
|
26
|
+
* as the effective value: the folder holds what the role resolves to, not only what it sets
|
|
27
|
+
* itself. A role with inherits_from therefore gets a warning: role push of the folder would
|
|
28
|
+
* store the inherited values on the child.
|
|
29
|
+
*/
|
|
30
|
+
var __importDefault = (this && this.__importDefault) || function (mod) {
|
|
31
|
+
return (mod && mod.__esModule) ? mod : { "default": mod };
|
|
32
|
+
};
|
|
33
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
34
|
+
exports.ROLE_SIDECAR = void 0;
|
|
35
|
+
exports.pullRoleWithConfig = pullRoleWithConfig;
|
|
36
|
+
exports.rolePullWithConfig = rolePullWithConfig;
|
|
37
|
+
exports.rolePull = rolePull;
|
|
38
|
+
const path_1 = __importDefault(require("path"));
|
|
39
|
+
const js_yaml_1 = __importDefault(require("js-yaml"));
|
|
40
|
+
const chalk_1 = __importDefault(require("chalk"));
|
|
41
|
+
const api_1 = require("../utils/api");
|
|
42
|
+
const mcp_1 = require("../utils/mcp");
|
|
43
|
+
const crew_1 = require("../utils/crew");
|
|
44
|
+
const atomic_dir_1 = require("../utils/atomic-dir");
|
|
45
|
+
const skill_push_1 = require("./skill-push");
|
|
46
|
+
const skill_pull_1 = require("./skill-pull");
|
|
47
|
+
Object.defineProperty(exports, "ROLE_SIDECAR", { enumerable: true, get: function () { return skill_pull_1.ROLE_SIDECAR; } });
|
|
48
|
+
/** A user-facing pull failure (message is printed as-is after `error: `). */
|
|
49
|
+
class RolePullError extends Error {
|
|
50
|
+
}
|
|
51
|
+
function isPlainObject(v) {
|
|
52
|
+
return typeof v === 'object' && v !== null && !Array.isArray(v);
|
|
53
|
+
}
|
|
54
|
+
/** A skill name becomes a path segment under skills/, so it must be a single safe segment. */
|
|
55
|
+
function assertSafeSegment(skill) {
|
|
56
|
+
if (typeof skill !== 'string' || skill === '' || skill === '.' || skill === '..' || /[\\/]/.test(skill)) {
|
|
57
|
+
throw new RolePullError(`server returned an unsafe skill name: ${JSON.stringify(skill)}`);
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
/**
|
|
61
|
+
* Pull the skill identifiers out of a `read` payload's always_load_skills (resolved bundles) or
|
|
62
|
+
* available_skills (description entries): both carry the link's `identifier`, in server order.
|
|
63
|
+
* A missing field means none; a malformed one is an error rather than a silent loss.
|
|
64
|
+
*/
|
|
65
|
+
function skillIdentifiers(data, key) {
|
|
66
|
+
const raw = data[key];
|
|
67
|
+
if (raw === undefined || raw === null)
|
|
68
|
+
return [];
|
|
69
|
+
if (!Array.isArray(raw))
|
|
70
|
+
throw new RolePullError(`unexpected response shape from server: ${key} is not a list`);
|
|
71
|
+
const out = [];
|
|
72
|
+
for (const entry of raw) {
|
|
73
|
+
const id = isPlainObject(entry) ? entry.identifier : undefined;
|
|
74
|
+
if (typeof id !== 'string' || id === '') {
|
|
75
|
+
throw new RolePullError(`unexpected response shape from server: a ${key} entry has no identifier`);
|
|
76
|
+
}
|
|
77
|
+
if (!out.includes(id))
|
|
78
|
+
out.push(id);
|
|
79
|
+
}
|
|
80
|
+
return out;
|
|
81
|
+
}
|
|
82
|
+
function mapReadError(code, message, name, inCrew) {
|
|
83
|
+
if (code === 'no_snapshot') {
|
|
84
|
+
return `role ${name} has no published version (no_snapshot); publish it first, or set version_mode: live`;
|
|
85
|
+
}
|
|
86
|
+
if (code === 'role_not_found') {
|
|
87
|
+
return `role '${name}' not found${inCrew ? ` in crew '${inCrew}'` : ''} (role_not_found); check the name, or pass --in-crew CREW to say which crew it lives in`;
|
|
88
|
+
}
|
|
89
|
+
if (code === 'ambiguous_role') {
|
|
90
|
+
return `role '${name}' exists in multiple crews (ambiguous_role); pass --in-crew CREW to choose one`;
|
|
91
|
+
}
|
|
92
|
+
return `${code}: ${message}`;
|
|
93
|
+
}
|
|
94
|
+
/** Render SKILL.md exactly as `role push` parses it back (body follows the closing --- line verbatim). */
|
|
95
|
+
function renderRoleMd(properties, body) {
|
|
96
|
+
const fm = { name: properties.name, description: properties.description };
|
|
97
|
+
for (const key of skill_push_1.ROLE_FRONTMATTER_PARAMS) {
|
|
98
|
+
if (properties[key] !== undefined && properties[key] !== null)
|
|
99
|
+
fm[key] = properties[key];
|
|
100
|
+
}
|
|
101
|
+
return `---\n${js_yaml_1.default.dump(fm, { lineWidth: -1 })}---\n${body}`;
|
|
102
|
+
}
|
|
103
|
+
/**
|
|
104
|
+
* Fetch the role (and, unless withSkills is false, its skills) and replace `dest` with
|
|
105
|
+
* the result as a unit. Throws on any failure, having written nothing.
|
|
106
|
+
*/
|
|
107
|
+
async function pullRoleWithConfig(name, dest, config, opts = {}) {
|
|
108
|
+
const inCrew = opts.inCrew;
|
|
109
|
+
const withSkills = opts.withSkills ?? true;
|
|
110
|
+
// Replacing a folder is destructive: refuse before any network call or write.
|
|
111
|
+
(0, atomic_dir_1.assertReplaceableDir)(dest, skill_pull_1.ROLE_SIDECAR, undefined, 'role');
|
|
112
|
+
const crewArgs = inCrew ? { in_crew: inCrew } : {};
|
|
113
|
+
const read = await (0, mcp_1.callCrewsTool)(config, 'roles', { action: 'read', name, ...crewArgs });
|
|
114
|
+
if (!read.ok) {
|
|
115
|
+
throw new RolePullError(mapReadError(read.data?.code ?? 'unknown_error', read.data?.message ?? 'MCP returned an error with no message', name, inCrew));
|
|
116
|
+
}
|
|
117
|
+
const data = read.data;
|
|
118
|
+
if (!isPlainObject(data) || typeof data.body !== 'string' || !isPlainObject(data.properties)) {
|
|
119
|
+
const keys = isPlainObject(data) ? Object.keys(data) : [];
|
|
120
|
+
throw new RolePullError(`unexpected response shape from server (keys received: ${keys.length ? keys.join(', ') : '(none)'})`);
|
|
121
|
+
}
|
|
122
|
+
const properties = data.properties;
|
|
123
|
+
if (typeof properties.description !== 'string' || properties.description === '') {
|
|
124
|
+
throw new RolePullError(`role '${name}' has no description, so it cannot be written as a pushable SKILL.md`);
|
|
125
|
+
}
|
|
126
|
+
const roleName = typeof properties.name === 'string' && properties.name ? properties.name : name;
|
|
127
|
+
// Values the server redacted are not the real values; pushing them back would corrupt the role.
|
|
128
|
+
const redacted = Array.isArray(data.redacted_keys) ? data.redacted_keys.filter((k) => typeof k === 'string') : [];
|
|
129
|
+
const usable = { ...properties, name: roleName };
|
|
130
|
+
// Skill links are top-level in the payload (not properties). available_skills also lists the
|
|
131
|
+
// role's auto-discovered local skills under bare names, which are not links: keep 'x/y' only.
|
|
132
|
+
const alwaysLoadSkills = skillIdentifiers(data, 'always_load_skills');
|
|
133
|
+
const availableSkills = skillIdentifiers(data, 'available_skills').filter((id) => id.includes('/'));
|
|
134
|
+
if (alwaysLoadSkills.length > 0)
|
|
135
|
+
usable.always_load_skills = alwaysLoadSkills;
|
|
136
|
+
if (availableSkills.length > 0)
|
|
137
|
+
usable.available_skills = availableSkills;
|
|
138
|
+
for (const key of redacted) {
|
|
139
|
+
if (key in usable && key !== 'name' && key !== 'description') {
|
|
140
|
+
delete usable[key];
|
|
141
|
+
process.stderr.write(chalk_1.default.yellow(`warn: property '${key}' is redacted by the server and was not written\n`));
|
|
142
|
+
}
|
|
143
|
+
}
|
|
144
|
+
const files = {};
|
|
145
|
+
files['SKILL.md'] = renderRoleMd(usable, data.body);
|
|
146
|
+
if (withSkills) {
|
|
147
|
+
const list = await (0, mcp_1.callCrewsTool)(config, 'roles', { action: 'list_skills', role: name, ...crewArgs });
|
|
148
|
+
if (!list.ok) {
|
|
149
|
+
throw new RolePullError(mapReadError(list.data?.code ?? 'unknown_error', list.data?.message ?? 'MCP returned an error with no message', name, inCrew));
|
|
150
|
+
}
|
|
151
|
+
const skills = list.data?.skills;
|
|
152
|
+
if (!Array.isArray(skills)) {
|
|
153
|
+
throw new RolePullError(`unexpected response shape from list_skills (keys received: ${isPlainObject(list.data) ? Object.keys(list.data).join(', ') : '(none)'})`);
|
|
154
|
+
}
|
|
155
|
+
for (const entry of skills) {
|
|
156
|
+
const skillName = isPlainObject(entry) ? (entry.name ?? entry.identifier) : entry;
|
|
157
|
+
assertSafeSegment(skillName);
|
|
158
|
+
const skillFiles = await (0, skill_pull_1.fetchSkillFiles)(config, skillName, { role: name, inCrew });
|
|
159
|
+
for (const [rel, content] of Object.entries(skillFiles)) {
|
|
160
|
+
files[`skills/${skillName}/${rel}`] = content;
|
|
161
|
+
}
|
|
162
|
+
}
|
|
163
|
+
}
|
|
164
|
+
// Baseline of the link lists exactly as written to the frontmatter (an absent list is []).
|
|
165
|
+
// role push compares against it, so an unchanged list is left out of the edit and the server
|
|
166
|
+
// keeps every link, including ones this caller could not see.
|
|
167
|
+
const linkBaseline = (key) => Array.isArray(usable[key]) ? usable[key] : [];
|
|
168
|
+
files[skill_pull_1.ROLE_SIDECAR] = JSON.stringify({
|
|
169
|
+
name: roleName,
|
|
170
|
+
in_crew: (0, crew_1.normalizeCrewPath)(inCrew),
|
|
171
|
+
links: {
|
|
172
|
+
always_load_skills: linkBaseline('always_load_skills'),
|
|
173
|
+
available_skills: linkBaseline('available_skills'),
|
|
174
|
+
},
|
|
175
|
+
doc_id: typeof data.doc_id === 'string' ? parseInt(data.doc_id, 10) : (data.doc_id ?? null),
|
|
176
|
+
head_revision_id: typeof data.head_revision_id === 'string' ? parseInt(data.head_revision_id, 10) : (data.head_revision_id ?? null),
|
|
177
|
+
active_snapshot_revision_id: typeof data.active_snapshot_revision_id === 'string'
|
|
178
|
+
? parseInt(data.active_snapshot_revision_id, 10)
|
|
179
|
+
: (data.active_snapshot_revision_id ?? null),
|
|
180
|
+
}, null, 2) + '\n';
|
|
181
|
+
(0, atomic_dir_1.writeDirAtomic)(path_1.default.resolve(dest), files);
|
|
182
|
+
// The server has no unmerged read, so `properties` is the effective (parent-merged) value.
|
|
183
|
+
// Pushing it back would store the parent's entries on this role: make that visible.
|
|
184
|
+
const parent = properties.inherits_from;
|
|
185
|
+
if (typeof parent === 'string' && parent !== '') {
|
|
186
|
+
process.stderr.write(chalk_1.default.yellow(`warn: role ${roleName} inherits from ${parent}; the pulled properties and skill links include inherited values, ` +
|
|
187
|
+
`and pushing this folder back with role push will store them on ${roleName}.\n`));
|
|
188
|
+
}
|
|
189
|
+
}
|
|
190
|
+
function fail(message) {
|
|
191
|
+
process.stderr.write(chalk_1.default.red(`error: ${message}\n`));
|
|
192
|
+
process.exit(1);
|
|
193
|
+
}
|
|
194
|
+
/** CLI wrapper: validates the destination, runs the pull, prints the result and exits. */
|
|
195
|
+
async function rolePullWithConfig(name, dest, options, config) {
|
|
196
|
+
if (dest === undefined && (name === '.' || name === '..' || name.includes('/') || name.includes('\\'))) {
|
|
197
|
+
fail(`'${name}' cannot be used as a default destination folder; pass an explicit [dir] directory`);
|
|
198
|
+
}
|
|
199
|
+
const out = dest ?? './' + name;
|
|
200
|
+
try {
|
|
201
|
+
await pullRoleWithConfig(name, out, config, { inCrew: options.inCrew, withSkills: options.skills !== false });
|
|
202
|
+
}
|
|
203
|
+
catch (e) {
|
|
204
|
+
fail(e.message);
|
|
205
|
+
}
|
|
206
|
+
console.log(chalk_1.default.green(`pulled role '${name}' → ${out}`));
|
|
207
|
+
process.exit(0);
|
|
208
|
+
}
|
|
209
|
+
/**
|
|
210
|
+
* Entry point called from index.ts.
|
|
211
|
+
*/
|
|
212
|
+
async function rolePull(name, dest, options) {
|
|
213
|
+
const config = await (0, api_1.requireConfigWithWorkspace)();
|
|
214
|
+
await rolePullWithConfig(name, dest, options, config);
|
|
215
|
+
}
|