@solidactions/cli 3.18.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.
@@ -4,7 +4,12 @@
4
4
  *
5
5
  * Fetches a skill from the crews library and reconstructs a local skill folder
6
6
  * (the inverse of `skill push`): writes <dest>/SKILL.md + any bundled reference
7
- * files under <dest>/. Default dest = ./<name>/.
7
+ * files under <dest>/. Default dest = ./<name>/. Shared-library skills by
8
+ * default; --role [--in-crew] pulls a role-scoped skill.
9
+ *
10
+ * The destination is replaced as a unit (writeDirAtomic): after a pull it holds
11
+ * exactly the fetched files — old complete copy or new complete copy, never a
12
+ * mix, and no stale files.
8
13
  *
9
14
  * --json mode: prints the raw read result from the server and exits WITHOUT
10
15
  * writing any files. This is useful for scripting/inspection. The default
@@ -14,99 +19,172 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
14
19
  return (mod && mod.__esModule) ? mod : { "default": mod };
15
20
  };
16
21
  Object.defineProperty(exports, "__esModule", { value: true });
17
- exports.SKILL_SIDECAR = void 0;
22
+ exports.ROLE_SIDECAR = exports.SKILL_SIDECAR = void 0;
23
+ exports.fetchSkillFiles = fetchSkillFiles;
24
+ exports.pullSkillWithConfig = pullSkillWithConfig;
18
25
  exports.skillPullWithConfig = skillPullWithConfig;
19
26
  exports.skillPull = skillPull;
20
- const fs_1 = __importDefault(require("fs"));
21
27
  const path_1 = __importDefault(require("path"));
22
28
  const chalk_1 = __importDefault(require("chalk"));
23
29
  const api_1 = require("../utils/api");
24
30
  const mcp_1 = require("../utils/mcp");
25
31
  const skill_bundle_1 = require("../utils/skill-bundle");
32
+ const atomic_dir_1 = require("../utils/atomic-dir");
26
33
  /** Filename of the provenance sidecar written alongside a pulled skill. */
27
34
  exports.SKILL_SIDECAR = '.solidactions-skill.json';
28
- /**
29
- * Core implementation — accepts an injected config so tests can point at a
30
- * stub server without touching the filesystem config.
31
- *
32
- * Steps:
33
- * 1. Call skills.read to fetch the skill from the library.
34
- * 2. If --json: print the raw result, exit 0 (no file writes).
35
- * 3. Otherwise: reconstruct SKILL.md from the returned `properties` (which
36
- * contains name, description, and any extra props), OMITTING `type` (the
37
- * server sets it; stripping mirrors what parseSkillFile does on push so a
38
- * push→pull→push round-trip is idempotent). Write <dest>/SKILL.md, then
39
- * write each reference file under <dest>/ with a path-traversal guard.
40
- */
41
- async function skillPullWithConfig(name, dest, options, config) {
42
- // Call the crews MCP server for a skills.read
35
+ /** Filename of the provenance sidecar written into a pulled role folder (and the replace marker). Lives here so skill push can recognise a pulled role folder without importing role-pull (which imports skill-push). */
36
+ exports.ROLE_SIDECAR = '.solidactions-role.json';
37
+ /** A user-facing pull failure (message is printed as-is after `error: `). */
38
+ class SkillPullError extends Error {
39
+ }
40
+ function isPlainObject(v) {
41
+ return typeof v === 'object' && v !== null && !Array.isArray(v);
42
+ }
43
+ /** Same rule as writeDirAtomic, so unsafe reference keys can be skipped with a warning instead of aborting the pull. */
44
+ function isUnsafeKey(key) {
45
+ return path_1.default.isAbsolute(key) || key.split(/[\\/]/).includes('..');
46
+ }
47
+ /** Call skills.read (shared) or roles.read_skill (--role) and return the raw payload. */
48
+ async function readSkillData(config, name, opts) {
49
+ const isRole = Boolean(opts.role);
43
50
  let result;
44
51
  try {
45
- result = await (0, mcp_1.callCrewsTool)(config, 'skills', { action: 'read', identifier: name });
52
+ result = isRole
53
+ ? await (0, mcp_1.callCrewsTool)(config, 'roles', {
54
+ action: 'read_skill',
55
+ role: opts.role,
56
+ name,
57
+ in_crew: opts.inCrew,
58
+ })
59
+ : await (0, mcp_1.callCrewsTool)(config, 'skills', { action: 'read', identifier: name });
46
60
  }
47
61
  catch (e) {
48
- process.stderr.write(chalk_1.default.red(`error: ${e.message}\n`));
49
- process.exit(1);
62
+ throw new SkillPullError(e.message);
50
63
  }
51
64
  if (!result.ok) {
52
65
  const code = result.data?.code ?? 'unknown_error';
53
66
  const message = result.data?.message ?? 'MCP returned an error with no message';
54
- process.stderr.write(chalk_1.default.red(`error: ${code}: ${message}\n`));
55
- process.exit(1);
67
+ if (!isRole && code === 'skill_not_found') {
68
+ throw new SkillPullError(`${code}: ${message}\n` +
69
+ `'${name}' is not in the shared library; if it belongs to a role, pass --role ROLE [--in-crew CREW]`);
70
+ }
71
+ throw new SkillPullError(`${code}: ${message}`);
56
72
  }
57
- const data = result.data;
58
- // --json mode: print raw result and exit WITHOUT writing files.
59
- // This is intentionally non-destructive: inspect the raw server payload
60
- // without side-effects. File reconstruction is the default (no --json) mode.
61
- if (options.json) {
62
- console.log(JSON.stringify(data));
63
- process.exit(0);
73
+ return result.data;
74
+ }
75
+ /**
76
+ * Read, validate and return the full file map for a skill (SKILL.md, references,
77
+ * provenance sidecar) WITHOUT writing anything. Keys are relative paths.
78
+ * Throws SkillPullError-style Errors on server errors or a malformed response.
79
+ */
80
+ async function fetchSkillFiles(config, name, opts = {}) {
81
+ const data = await readSkillData(config, name, opts);
82
+ return buildSkillFiles(config, name, opts, data);
83
+ }
84
+ async function buildSkillFiles(config, name, opts, data) {
85
+ // Shape guard — before anything is written or fetched further.
86
+ if (!isPlainObject(data) || typeof data.body !== 'string' || !isPlainObject(data.properties)) {
87
+ const keys = isPlainObject(data) ? Object.keys(data) : [];
88
+ throw new SkillPullError(`unexpected response shape from server (keys received: ${keys.length ? keys.join(', ') : '(none)'})`);
64
89
  }
65
- // Resolve the output directory (default: ./<name>/)
66
- const out = dest ?? './' + name;
67
- const absOut = path_1.default.resolve(out);
68
- // Build the frontmatter object from `properties`, OMITTING `type`.
69
- // The server stores a `type` field but it is stripped on push (parseSkillFile
70
- // does `const { type: _type, ...properties } = rest`). We mirror that here
71
- // so that pull → push is idempotent.
72
- const skillMdContent = (0, skill_bundle_1.reconstructSkillMd)(data.properties, data.body);
73
- // Create the output directory (and parents) if needed
74
- fs_1.default.mkdirSync(absOut, { recursive: true });
75
- // Write SKILL.md
76
- fs_1.default.writeFileSync(path_1.default.join(absOut, 'SKILL.md'), skillMdContent, 'utf8');
77
- // Write reference files, guarding against path traversal
78
- const reference = data.reference ?? {};
79
- const absOutNorm = path_1.default.resolve(absOut) + path_1.default.sep;
80
- let writtenCount = 0;
81
- let skippedCount = 0;
82
- for (const [key, content] of Object.entries(reference)) {
83
- // Guard 1: reject absolute paths
84
- if (path_1.default.isAbsolute(key)) {
85
- process.stderr.write(chalk_1.default.yellow(`warn: skipping unsafe reference key (absolute path): ${key}\n`));
86
- skippedCount++;
90
+ if (data.reference !== undefined && data.reference !== null && !isPlainObject(data.reference)) {
91
+ throw new SkillPullError(`unexpected response shape from server: 'reference' is not an object (keys received: ${Object.keys(data).join(', ')})`);
92
+ }
93
+ const isRole = Boolean(opts.role);
94
+ const group = isRole ? 'roles' : 'skills';
95
+ const locator = isRole
96
+ ? { role: opts.role, name, in_crew: opts.inCrew }
97
+ : { identifier: name };
98
+ const files = {};
99
+ for (const [key, value] of Object.entries((data.reference ?? {}))) {
100
+ if (isUnsafeKey(key)) {
101
+ process.stderr.write(chalk_1.default.yellow(`warn: skipping unsafe reference key: ${key}\n`));
87
102
  continue;
88
103
  }
89
- // Guard 2: reject path traversal (any key that resolves outside absOut)
90
- const target = path_1.default.resolve(absOut, key);
91
- if (!target.startsWith(absOutNorm)) {
92
- process.stderr.write(chalk_1.default.yellow(`warn: skipping unsafe reference key (traversal): ${key}\n`));
93
- skippedCount++;
94
- continue;
104
+ if (typeof value === 'string') {
105
+ files[key] = value;
106
+ }
107
+ else if (isPlainObject(value) && value.binary === true) {
108
+ files[key] = await (0, skill_bundle_1.fetchBinaryReference)(config, group, locator, key, {
109
+ size: value.size,
110
+ blobSha: value.blob_sha,
111
+ });
112
+ }
113
+ else {
114
+ throw new SkillPullError(`unexpected response shape from server: reference '${key}' is neither text nor a binary descriptor`);
95
115
  }
96
- // Safe: create parent dirs and write the file
97
- fs_1.default.mkdirSync(path_1.default.dirname(target), { recursive: true });
98
- fs_1.default.writeFileSync(target, content, 'utf8');
99
- writtenCount++;
100
116
  }
101
- // Write the provenance sidecar so downstream commands (e.g. `skill push`)
102
- // can detect drift against the revision this pull was taken from.
117
+ // Build the frontmatter from `properties`, OMITTING `type` (the server sets it;
118
+ // stripping mirrors parseSkillFile on push so push -> pull -> push is idempotent).
119
+ files['SKILL.md'] = (0, skill_bundle_1.reconstructSkillMd)(data.properties, data.body);
120
+ // Provenance sidecar so downstream commands (e.g. `skill push`) can detect drift.
103
121
  const sidecar = {
104
122
  identifier: data.identifier,
105
123
  doc_id: typeof data.doc_id === 'string' ? parseInt(data.doc_id, 10) : data.doc_id,
106
124
  head_revision_id: typeof data.head_revision_id === 'string' ? parseInt(data.head_revision_id, 10) : (data.head_revision_id ?? null),
107
- role: null,
125
+ role: opts.role ?? null,
108
126
  };
109
- fs_1.default.writeFileSync(path_1.default.join(absOut, exports.SKILL_SIDECAR), JSON.stringify(sidecar, null, 2) + '\n', 'utf8');
127
+ if (isRole)
128
+ sidecar.in_crew = opts.inCrew ?? null;
129
+ files[exports.SKILL_SIDECAR] = JSON.stringify(sidecar, null, 2) + '\n';
130
+ return files;
131
+ }
132
+ /** Fetch a skill and replace `dest` with it as a unit. Throws on failure; nothing is written on error. */
133
+ async function pullSkillWithConfig(name, dest, config, opts = {}) {
134
+ (0, atomic_dir_1.assertReplaceableDir)(dest, exports.SKILL_SIDECAR);
135
+ (0, atomic_dir_1.writeDirAtomic)(path_1.default.resolve(dest), await fetchSkillFiles(config, name, opts));
136
+ }
137
+ function fail(message) {
138
+ process.stderr.write(chalk_1.default.red(`error: ${message}\n`));
139
+ process.exit(1);
140
+ }
141
+ /**
142
+ * Core CLI implementation — accepts an injected config so tests can point at a
143
+ * stub server without touching the filesystem config.
144
+ */
145
+ async function skillPullWithConfig(name, dest, options, config) {
146
+ if (options.inCrew && !options.role)
147
+ fail('--in-crew requires --role.');
148
+ if (dest === undefined && (name === '.' || name === '..' || name.includes('/') || name.includes('\\'))) {
149
+ fail(`'${name}' cannot be used as a default destination folder; pass an explicit [dest] directory`);
150
+ }
151
+ const readOpts = { role: options.role, inCrew: options.inCrew };
152
+ const out = dest ?? './' + name;
153
+ // Replacing a folder is destructive: refuse before any network call or write.
154
+ if (!options.json) {
155
+ try {
156
+ (0, atomic_dir_1.assertReplaceableDir)(out, exports.SKILL_SIDECAR);
157
+ }
158
+ catch (e) {
159
+ fail(e.message);
160
+ }
161
+ }
162
+ let data;
163
+ try {
164
+ data = await readSkillData(config, name, readOpts);
165
+ }
166
+ catch (e) {
167
+ fail(e.message);
168
+ }
169
+ // --json mode: print raw result and exit WITHOUT writing files.
170
+ if (options.json) {
171
+ console.log(JSON.stringify(data));
172
+ process.exit(0);
173
+ }
174
+ let files;
175
+ try {
176
+ files = await buildSkillFiles(config, name, readOpts, data);
177
+ }
178
+ catch (e) {
179
+ fail(e.message);
180
+ }
181
+ try {
182
+ (0, atomic_dir_1.writeDirAtomic)(path_1.default.resolve(out), files);
183
+ }
184
+ catch (e) {
185
+ fail(`failed to write ${out}: ${e.message}`);
186
+ }
187
+ const writtenCount = Object.keys(files).filter((k) => k !== 'SKILL.md' && k !== exports.SKILL_SIDECAR).length;
110
188
  const refSummary = writtenCount === 1 ? '1 reference' : `${writtenCount} references`;
111
189
  console.log(chalk_1.default.green(`pulled skill '${name}' → ${out} (${refSummary})`));
112
190
  process.exit(0);
@@ -13,7 +13,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
13
13
  return (mod && mod.__esModule) ? mod : { "default": mod };
14
14
  };
15
15
  Object.defineProperty(exports, "__esModule", { value: true });
16
- exports.RESERVED_PARAM_KEYS = void 0;
16
+ exports.ROLE_FRONTMATTER_PARAMS = exports.RESERVED_PARAM_KEYS = void 0;
17
+ exports.foldedFrontmatterKeys = foldedFrontmatterKeys;
18
+ exports.noteFoldedFrontmatterKeys = noteFoldedFrontmatterKeys;
19
+ exports.shapeFrontmatterParams = shapeFrontmatterParams;
17
20
  exports.assertNoReservedFrontmatterKeys = assertNoReservedFrontmatterKeys;
18
21
  exports.parseSkillFile = parseSkillFile;
19
22
  exports.readReferences = readReferences;
@@ -31,12 +34,62 @@ const api_1 = require("../utils/api");
31
34
  const mcp_1 = require("../utils/mcp");
32
35
  const skill_snapshot_1 = require("../utils/skill-snapshot");
33
36
  const skill_pull_1 = require("./skill-pull");
37
+ const crew_1 = require("../utils/crew");
34
38
  /**
35
39
  * Protocol param names reserved by the skills/roles MCP tool actions. Frontmatter
36
40
  * keys that collide with these would silently corrupt the request once spread
37
41
  * top-level into the call arguments.
38
42
  */
39
- exports.RESERVED_PARAM_KEYS = ['action', 'identifier', 'role', 'name', 'description', 'body', 'references', 'base_version_id'];
43
+ exports.RESERVED_PARAM_KEYS = ['action', 'identifier', 'role', 'name', 'description', 'body', 'references', 'base_version_id', 'in_crew', 'workspace', 'version_id'];
44
+ /**
45
+ * Frontmatter keys the current MCP catalog accepts as top-level create/edit params
46
+ * (crews_skills_manage / crews_roles_manage). The server rejects any other param
47
+ * with `unknown_params`, so everything else is folded into `metadata`.
48
+ */
49
+ const SKILL_FRONTMATTER_PARAMS = ['catalog_advertised', 'metadata', 'license', 'compatibility', 'allowed-tools', 'storage', 'version_mode'];
50
+ exports.ROLE_FRONTMATTER_PARAMS = [
51
+ 'inherits_from', 'always_load_docs', 'always_load_memory', 'always_load_skills', 'available_skills',
52
+ 'catalog_advertised', 'metadata', 'version_mode',
53
+ ];
54
+ /**
55
+ * Keys `shapeFrontmatterParams` will fold into `metadata` (not in the schema, value defined).
56
+ */
57
+ function foldedFrontmatterKeys(properties, allowed) {
58
+ return Object.entries(properties)
59
+ .filter(([key, value]) => !allowed.includes(key) && value !== undefined)
60
+ .map(([key]) => key);
61
+ }
62
+ /**
63
+ * Write the one-line stderr note about folded frontmatter keys (nothing when none were folded).
64
+ * Stderr keeps --json stdout clean.
65
+ */
66
+ function noteFoldedFrontmatterKeys(properties, allowed) {
67
+ const folded = foldedFrontmatterKeys(properties, allowed);
68
+ if (folded.length > 0) {
69
+ process.stderr.write(`note: frontmatter keys not in the schema were stored under metadata: ${folded.join(', ')}\n`);
70
+ }
71
+ }
72
+ /**
73
+ * Split frontmatter-derived properties into schema params (sent top-level) and the
74
+ * rest, which is merged under `metadata` (inert client key/value strings).
75
+ */
76
+ function shapeFrontmatterParams(properties, allowed) {
77
+ const out = {};
78
+ const extra = {};
79
+ for (const [key, value] of Object.entries(properties)) {
80
+ if (allowed.includes(key)) {
81
+ out[key] = value;
82
+ }
83
+ else if (value !== undefined) {
84
+ extra[key] = typeof value === 'string' ? value : JSON.stringify(value);
85
+ }
86
+ }
87
+ if (Object.keys(extra).length > 0) {
88
+ const existing = out.metadata && typeof out.metadata === 'object' ? out.metadata : {};
89
+ out.metadata = { ...extra, ...existing };
90
+ }
91
+ return out;
92
+ }
40
93
  /**
41
94
  * Throws if any frontmatter-derived property key collides with a reserved
42
95
  * protocol param name.
@@ -101,7 +154,8 @@ function parseSkillFile(content) {
101
154
  * their relative path (e.g. "references/member-roles.md") — matching how
102
155
  * SKILL.md cites them, so bundled reference docs land complete (#247).
103
156
  *
104
- * Also excludes `skill pull`'s provenance sidecar (SKILL_SIDECAR) and
157
+ * Also excludes `skill pull`'s provenance sidecar (SKILL_SIDECAR), `role pull`'s
158
+ * (ROLE_SIDECAR) and
105
159
  * `skill dev`'s local runtime-state dir (.sa-state/) — neither is skill
106
160
  * content, and uploading them would leak local revision bookkeeping / state
107
161
  * into the remote library and agent sandboxes.
@@ -125,6 +179,8 @@ function readReferences(dir) {
125
179
  continue; // exclude only the top-level skill file
126
180
  if (key === skill_pull_1.SKILL_SIDECAR)
127
181
  continue; // exclude the skill pull provenance sidecar
182
+ if (key === skill_pull_1.ROLE_SIDECAR)
183
+ continue; // exclude the role pull provenance sidecar
128
184
  references[key] = fs_1.default.readFileSync(abs, 'utf8');
129
185
  }
130
186
  };
@@ -217,6 +273,16 @@ async function pushParsedSkill(payload, options, config, sidecarRevision) {
217
273
  assertNoReservedFrontmatterKeys(properties);
218
274
  const isRole = !!options.role;
219
275
  const tool = isRole ? 'roles' : 'skills';
276
+ const frontmatterParams = shapeFrontmatterParams(properties, SKILL_FRONTMATTER_PARAMS);
277
+ noteFoldedFrontmatterKeys(properties, SKILL_FRONTMATTER_PARAMS);
278
+ // in_crew comes only from --in-crew (never frontmatter); sent only with --role and only when given.
279
+ const crewArgs = isRole && options.inCrew ? { in_crew: options.inCrew } : {};
280
+ // Tool error -> Error, with crew-scoping codes (ambiguous_role) mapped to an actionable --in-crew hint.
281
+ const toolError = (data) => {
282
+ const code = data?.code ?? 'unknown_error';
283
+ const hint = isRole ? (0, crew_1.crewErrorHint)(code, options.role, data?.message) : null;
284
+ return new Error(hint ?? `${code}: ${data?.message ?? 'MCP returned an error with no message'}`);
285
+ };
220
286
  // --dry-run: pre-flight a read to detect existence; make NO create/edit calls.
221
287
  if (options.dryRun) {
222
288
  // Role-scoped skills are read via the roles tool's read_skill {role, name};
@@ -224,7 +290,7 @@ async function pushParsedSkill(payload, options, config, sidecarRevision) {
224
290
  // `skill_not_found` when absent. (read does NOT accept `identifier` on the
225
291
  // roles tool, so the action/args must branch on isRole.)
226
292
  const readArgs = isRole
227
- ? { action: 'read_skill', role: options.role, name }
293
+ ? { action: 'read_skill', role: options.role, name, ...crewArgs }
228
294
  : { action: 'read', identifier: name };
229
295
  let readResult;
230
296
  try {
@@ -239,16 +305,15 @@ async function pushParsedSkill(payload, options, config, sidecarRevision) {
239
305
  return { status: 'would-create', name, data: {} };
240
306
  }
241
307
  // Any other error is unexpected — surface it
242
- const errMsg = readResult.data?.message ?? 'MCP returned an error with no message';
243
- throw new Error(`${code ?? 'unknown_error'}: ${errMsg}`);
308
+ throw toolError(readResult.data);
244
309
  }
245
310
  // Read succeeded → skill exists → would update
246
311
  return { status: 'would-update', name, data: {} };
247
312
  }
248
313
  // Spread frontmatter extras FIRST so the fixed protocol keys always win.
249
314
  const createArgs = isRole
250
- ? { ...properties, action: 'create_skill', role: options.role, name, description, body, references }
251
- : { ...properties, action: 'create', name, description, body, references };
315
+ ? { ...frontmatterParams, action: 'create_skill', role: options.role, ...crewArgs, name, description, body, references }
316
+ : { ...frontmatterParams, action: 'create', name, description, body, references };
252
317
  let result;
253
318
  try {
254
319
  result = await (0, mcp_1.callCrewsTool)(config, tool, createArgs);
@@ -260,8 +325,8 @@ async function pushParsedSkill(payload, options, config, sidecarRevision) {
260
325
  if (!result.ok && result.data?.code === 'name_collision') {
261
326
  const guardBaseVersion = sidecarRevision != null && !options.force;
262
327
  const editArgs = isRole
263
- ? { ...properties, action: 'edit_skill', role: options.role, name, description, body, references, ...(guardBaseVersion ? { base_version_id: sidecarRevision } : {}) }
264
- : { ...properties, action: 'edit', identifier: name, description, body, references, ...(guardBaseVersion ? { base_version_id: sidecarRevision } : {}) };
328
+ ? { ...frontmatterParams, action: 'edit_skill', role: options.role, ...crewArgs, name, description, body, references, ...(guardBaseVersion ? { base_version_id: sidecarRevision } : {}) }
329
+ : { ...frontmatterParams, action: 'edit', identifier: name, description, body, references, ...(guardBaseVersion ? { base_version_id: sidecarRevision } : {}) };
265
330
  try {
266
331
  result = await (0, mcp_1.callCrewsTool)(config, tool, editArgs);
267
332
  }
@@ -275,16 +340,12 @@ async function pushParsedSkill(payload, options, config, sidecarRevision) {
275
340
  const currentRevisionId = errData?.current_revision_id;
276
341
  throw new Error(`remote skill changed since your pull (their revision ${currentRevisionId}, your base ${sidecarRevision}) — re-pull to merge, or pass --force to overwrite`);
277
342
  }
278
- const errMsg = errData?.message ?? 'MCP returned an error with no message';
279
- throw new Error(`${errCode}: ${errMsg}`);
343
+ throw toolError(errData);
280
344
  }
281
345
  return { status: 'updated', name, data: result.data ?? {} };
282
346
  }
283
347
  if (!result.ok) {
284
- const errData = result.data;
285
- const errCode = errData?.code ?? 'unknown_error';
286
- const errMsg = errData?.message ?? 'MCP returned an error with no message';
287
- throw new Error(`${errCode}: ${errMsg}`);
348
+ throw toolError(result.data);
288
349
  }
289
350
  return { status: 'created', name, data: result.data ?? {} };
290
351
  }
@@ -324,7 +385,7 @@ function printPushResult(result, options) {
324
385
  * truthy snapshot_hint (null when the skill is version_mode=live).
325
386
  * Dry-run statuses never warn.
326
387
  */
327
- function stagedPushWarning(result, isRole) {
388
+ function stagedPushWarning(result, isRole, role, inCrew) {
328
389
  const { status, name, data } = result;
329
390
  if (status === 'created') {
330
391
  if (!data.snapshot_hint) {
@@ -340,7 +401,7 @@ function stagedPushWarning(result, isRole) {
340
401
  return null;
341
402
  }
342
403
  const publishLine = isRole
343
- ? ` Publish this role-scoped skill via the MCP crews_versions take_snapshot tool.\n`
404
+ ? ` Run: solidactions skill publish ${name} --role ${role ?? '<role>'}${inCrew ? ` --in-crew ${inCrew}` : ''}\n`
344
405
  : ` Run: solidactions skill publish ${name}\n`;
345
406
  const headline = status === 'updated'
346
407
  ? `⚠ Staged, not published. This revision won't run for agents until you publish it.\n`
@@ -386,7 +447,7 @@ async function refreshSidecarRevision(dir, sidecar, pushResult, options, config)
386
447
  if (headRevisionId === null) {
387
448
  const isRole = !!options.role;
388
449
  const readArgs = isRole
389
- ? { action: 'read_skill', role: options.role, name: pushResult.name }
450
+ ? { action: 'read_skill', role: options.role, name: pushResult.name, ...(options.inCrew ? { in_crew: options.inCrew } : {}) }
390
451
  : { action: 'read', identifier: pushResult.name };
391
452
  try {
392
453
  const readResult = await (0, mcp_1.callCrewsTool)(config, isRole ? 'roles' : 'skills', readArgs);
@@ -412,13 +473,17 @@ async function refreshSidecarRevision(dir, sidecar, pushResult, options, config)
412
473
  * (skills/ + commands/ subdirectories) based on directory structure.
413
474
  */
414
475
  async function skillPushWithConfig(dir, options, config) {
476
+ if (options.inCrew && !options.role) {
477
+ process.stderr.write(chalk_1.default.red('error: --in-crew requires --role.\n'));
478
+ process.exit(1);
479
+ }
415
480
  const absDir = path_1.default.resolve(dir);
416
481
  if (!fs_1.default.existsSync(absDir) || !fs_1.default.statSync(absDir).isDirectory()) {
417
482
  process.stderr.write(chalk_1.default.red(`error: "${dir}" is not a directory.\n`));
418
483
  process.exit(1);
419
484
  }
420
- if (options.publish && options.role) {
421
- process.stderr.write(chalk_1.default.red('error: --publish is not supported with --role yet; publish the role-scoped skill via the MCP take_snapshot tool.\n'));
485
+ if (fs_1.default.existsSync(path_1.default.join(absDir, skill_pull_1.ROLE_SIDECAR))) {
486
+ process.stderr.write(chalk_1.default.red(`error: ${dir} is a pulled role folder; use \`solidactions role push\`\n`));
422
487
  process.exit(1);
423
488
  }
424
489
  const topLevelSkillMd = path_1.default.join(absDir, 'SKILL.md');
@@ -461,7 +526,7 @@ async function skillPushWithConfig(dir, options, config) {
461
526
  }
462
527
  }
463
528
  else {
464
- publishOutcome = await (0, skill_snapshot_1.publishSkillByName)(config, pushResult.name);
529
+ publishOutcome = await (0, skill_snapshot_1.publishSkillByName)(config, pushResult.name, { role: options.role, inCrew: options.inCrew });
465
530
  }
466
531
  }
467
532
  if (options.json) {
@@ -471,9 +536,9 @@ async function skillPushWithConfig(dir, options, config) {
471
536
  }
472
537
  printPushResult(pushResult, options);
473
538
  if (publishOutcome) {
474
- (0, skill_snapshot_1.emitPublishOutcome)(pushResult.name, publishOutcome, { pushed: true });
539
+ (0, skill_snapshot_1.emitPublishOutcome)(pushResult.name, publishOutcome, { pushed: true, role: options.role, inCrew: options.inCrew });
475
540
  }
476
- const warning = stagedPushWarning(pushResult, !!options.role);
541
+ const warning = stagedPushWarning(pushResult, !!options.role, options.role, options.inCrew);
477
542
  if (warning) {
478
543
  process.stderr.write(chalk_1.default.yellow(warning));
479
544
  }
package/dist/index.js CHANGED
@@ -82,6 +82,7 @@ const skill_delete_1 = require("./commands/skill-delete");
82
82
  const skill_dev_1 = require("./commands/skill-dev");
83
83
  const skill_exec_1 = require("./commands/skill-exec");
84
84
  const role_push_1 = require("./commands/role-push");
85
+ const role_pull_1 = require("./commands/role-pull");
85
86
  const doc_push_1 = require("./commands/doc-push");
86
87
  const doc_pull_1 = require("./commands/doc-pull");
87
88
  const doc_upload_1 = require("./commands/doc-upload");
@@ -94,6 +95,7 @@ const state_1 = require("./commands/state");
94
95
  const workflow_view_1 = require("./commands/workflow-view");
95
96
  const database_1 = require("./commands/database");
96
97
  const database_push_1 = require("./commands/database-push");
98
+ const database_export_1 = require("./commands/database-export");
97
99
  const config_1 = require("./utils/config");
98
100
  const mutating_commands_1 = require("./utils/mutating-commands");
99
101
  const agent_freshness_1 = require("./utils/agent-freshness");
@@ -379,6 +381,23 @@ database
379
381
  .action(async (name, file, options) => {
380
382
  await (0, database_1.databaseIngest)(name, file, { table: options.table, mode: options.mode, batchId: options.batchId, json: options.json });
381
383
  });
384
+ database
385
+ .command('export')
386
+ .description('Export an analytical database snapshot as Parquet files and a manifest')
387
+ .argument('<name>', 'Database name')
388
+ .option('--table <table>', 'Export one table (repeatable)', (value, previous = []) => [...previous, value], [])
389
+ .option('--output <directory>', 'Destination directory')
390
+ .option('--no-wait', 'Print the accepted export id without waiting or downloading')
391
+ .option('--resume <export-id>', 'Resume an existing authorized export')
392
+ .option('--replace', 'Replace a non-reusable ready export without prompting')
393
+ .option('--json', 'Output as JSON')
394
+ .addHelpText('after', `
395
+ Exports contain Parquet files and manifest.json only. New exports require an absent or empty destination; downloads never overwrite files.
396
+ Downloads verify the manifest against the authenticated API manifest digest, then verify each file byte length and SHA-256. Signed links are refreshed once on expiry.
397
+ Resume an interrupted download with --resume <export-id>. JSON output never includes signed URLs.`)
398
+ .action(async (name, options) => {
399
+ await (0, database_export_1.databaseExport)(name, options);
400
+ });
382
401
  database
383
402
  .command('drop-table')
384
403
  .description('Delete one table from an analytical database and free its space')
@@ -904,6 +923,7 @@ skill
904
923
  .description('Push a local skill folder into the library (create, or update if it already exists)')
905
924
  .argument('<dir>', 'Path to the skill directory (must contain SKILL.md)')
906
925
  .option('--role <name>', 'Scope the skill to a role instead of the shared library')
926
+ .option('--in-crew <crew>', 'Crew containing the role (with --role; disambiguates roles in multiple crews)')
907
927
  .option('--json', 'Output result as JSON')
908
928
  .option('--dry-run', 'Preview create vs update without writing')
909
929
  .option('--publish', 'Publish (snapshot) the skill after pushing, making it live for agents')
@@ -915,6 +935,8 @@ skill
915
935
  .command('publish')
916
936
  .description('Publish (snapshot) a skill so its latest pushed revision goes live for agents')
917
937
  .argument('<name>', 'Skill name/identifier (e.g. "my-skill" or "shared/my-skill")')
938
+ .option('--role <name>', 'Publish a role-scoped skill of this role instead of a shared-library skill')
939
+ .option('--in-crew <crew>', 'Crew containing the role (with --role; disambiguates roles in multiple crews)')
918
940
  .option('--json', 'Output result as JSON')
919
941
  .action(async (name, options) => {
920
942
  await (0, skill_publish_1.skillPublish)(name, options);
@@ -924,6 +946,8 @@ skill
924
946
  .description('Fetch a skill from the library to a local folder for editing (inverse of push)')
925
947
  .argument('<name>', 'Skill name or identifier')
926
948
  .argument('[dest]', 'Destination directory (defaults to ./<name>/)')
949
+ .option('--role <role>', 'Pull a role-scoped skill of this role instead of a shared-library skill')
950
+ .option('--in-crew <crew>', 'Crew containing the role (with --role; disambiguates roles in multiple crews)')
927
951
  .option('--json', 'Output raw read result as JSON (no file writes)')
928
952
  .action(async (name, dest, options) => {
929
953
  await (0, skill_pull_1.skillPull)(name, dest, options);
@@ -994,11 +1018,27 @@ const role = exports.program.command('role').description('Manage roles (crews SO
994
1018
  role
995
1019
  .command('push <dir>')
996
1020
  .description('Push a role definition (create or update)')
1021
+ .option('--in-crew <crew>', 'Crew that contains the role (required to create a role; disambiguates when the name exists in several crews)')
1022
+ .option('--replace-links', 'Replace always_load_skills / available_skills even when they differ from what role pull recorded (the server may hold links you cannot see)')
997
1023
  .option('--dry-run', 'Preview create vs update without writing')
998
1024
  .option('--json', 'Output result as JSON')
999
1025
  .action(async (dir, options) => {
1000
1026
  await (0, role_push_1.rolePush)(dir, options);
1001
1027
  });
1028
+ role
1029
+ .command('pull')
1030
+ .description('Fetch a role and its role-scoped skills to a local folder (inverse of push)\n\n' +
1031
+ 'Pulls the role\'s PUBLISHED version: a versioned role must have a snapshot (or use version_mode: live).\n' +
1032
+ 'Inherited properties are merged by the server (RoleActivator) and are pulled as the effective value.\n' +
1033
+ 'For a role with inherits_from, pushing the pulled folder back would store the inherited values on the child (a warning is printed).\n' +
1034
+ 'Writes SKILL.md, .solidactions-role.json and skills/<skill>/ in one atomic replace of the folder.')
1035
+ .argument('<name>', 'Role name')
1036
+ .argument('[dir]', 'Destination directory (defaults to ./<name>/)')
1037
+ .option('--in-crew <crew>', 'Crew that contains the role (disambiguates when the name exists in several crews)')
1038
+ .option('--no-skills', 'Pull the role only, without its role-scoped skills')
1039
+ .action(async (name, dir, options) => {
1040
+ await (0, role_pull_1.rolePull)(name, dir, options);
1041
+ });
1002
1042
  // =============================================================================
1003
1043
  // doc <subcommand> (SA-Docs surface)
1004
1044
  // =============================================================================