@solidactions/cli 1.28.0 → 1.30.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.
@@ -30,6 +30,7 @@ const js_yaml_1 = __importDefault(require("js-yaml"));
30
30
  const api_1 = require("../utils/api");
31
31
  const mcp_1 = require("../utils/mcp");
32
32
  const skill_snapshot_1 = require("../utils/skill-snapshot");
33
+ const skill_pull_1 = require("./skill-pull");
33
34
  /**
34
35
  * Protocol param names reserved by the skills/roles MCP tool actions. Frontmatter
35
36
  * keys that collide with these would silently corrupt the request once spread
@@ -99,6 +100,11 @@ function parseSkillFile(content) {
99
100
  * keep a bare-filename key (e.g. "helper.py"), and files in subfolders keep
100
101
  * their relative path (e.g. "references/member-roles.md") — matching how
101
102
  * SKILL.md cites them, so bundled reference docs land complete (#247).
103
+ *
104
+ * Also excludes `skill pull`'s provenance sidecar (SKILL_SIDECAR) and
105
+ * `skill run`'s local runtime-state dir (.sa-state/) — neither is skill
106
+ * content, and uploading them would leak local revision bookkeeping / state
107
+ * into the remote library and agent sandboxes.
102
108
  */
103
109
  function readReferences(dir) {
104
110
  const references = {};
@@ -106,6 +112,8 @@ function readReferences(dir) {
106
112
  for (const entry of fs_1.default.readdirSync(current, { withFileTypes: true })) {
107
113
  const abs = path_1.default.join(current, entry.name);
108
114
  if (entry.isDirectory()) {
115
+ if (entry.name === '.sa-state')
116
+ continue; // skill run's local runtime-state dir
109
117
  walk(abs);
110
118
  continue;
111
119
  }
@@ -115,6 +123,8 @@ function readReferences(dir) {
115
123
  const key = path_1.default.relative(dir, abs).split(path_1.default.sep).join('/');
116
124
  if (key === 'SKILL.md')
117
125
  continue; // exclude only the top-level skill file
126
+ if (key === skill_pull_1.SKILL_SIDECAR)
127
+ continue; // exclude the skill pull provenance sidecar
118
128
  references[key] = fs_1.default.readFileSync(abs, 'utf8');
119
129
  }
120
130
  };
@@ -194,8 +204,15 @@ function parseCommandFile(filename, content) {
194
204
  * When options.dryRun is true, performs only a skills.read pre-flight and
195
205
  * returns {status:'would-create'} or {status:'would-update'} without any
196
206
  * create or edit call.
207
+ *
208
+ * sidecarRevision (edit path only): the pulled skill's last-known head_revision_id
209
+ * (from the local .solidactions-skill.json sidecar), sent as base_version_id so the
210
+ * server can detect drift. undefined = no sidecar (nothing to guard); null = sidecar
211
+ * present but never published. Ignored when options.force is set. On a concurrent_edit
212
+ * response, throws a message naming the remote's current_revision_id, the local base,
213
+ * and --force as the override.
197
214
  */
198
- async function pushParsedSkill(payload, options, config) {
215
+ async function pushParsedSkill(payload, options, config, sidecarRevision) {
199
216
  const { name, description, properties, body, references } = payload;
200
217
  assertNoReservedFrontmatterKeys(properties);
201
218
  const isRole = !!options.role;
@@ -241,9 +258,10 @@ async function pushParsedSkill(payload, options, config) {
241
258
  }
242
259
  // On name collision, switch to the edit path.
243
260
  if (!result.ok && result.data?.code === 'name_collision') {
261
+ const guardBaseVersion = sidecarRevision != null && !options.force;
244
262
  const editArgs = isRole
245
- ? { ...properties, action: 'edit_skill', role: options.role, name, description, body, references }
246
- : { ...properties, action: 'edit', identifier: name, description, body, references };
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 } : {}) };
247
265
  try {
248
266
  result = await (0, mcp_1.callCrewsTool)(config, tool, editArgs);
249
267
  }
@@ -253,6 +271,10 @@ async function pushParsedSkill(payload, options, config) {
253
271
  if (!result.ok) {
254
272
  const errData = result.data;
255
273
  const errCode = errData?.code ?? 'unknown_error';
274
+ if (errCode === 'concurrent_edit') {
275
+ const currentRevisionId = errData?.current_revision_id;
276
+ 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
+ }
256
278
  const errMsg = errData?.message ?? 'MCP returned an error with no message';
257
279
  throw new Error(`${errCode}: ${errMsg}`);
258
280
  }
@@ -325,6 +347,63 @@ function stagedPushWarning(result, isRole) {
325
347
  : `⚠ Not yet published. Agents read the unversioned draft until you publish to pin a version.\n`;
326
348
  return headline + publishLine;
327
349
  }
350
+ /**
351
+ * Read the local provenance sidecar (written by `skill pull`), if present.
352
+ * Returns null when absent, or unreadable/malformed — nothing to guard against on push.
353
+ */
354
+ function readSidecar(dir) {
355
+ const sidecarPath = path_1.default.join(dir, skill_pull_1.SKILL_SIDECAR);
356
+ if (!fs_1.default.existsSync(sidecarPath)) {
357
+ return null;
358
+ }
359
+ try {
360
+ return JSON.parse(fs_1.default.readFileSync(sidecarPath, 'utf8'));
361
+ }
362
+ catch {
363
+ return null;
364
+ }
365
+ }
366
+ /**
367
+ * After a successful guarded edit or a create, refresh the local sidecar's
368
+ * head_revision_id so the *next* push's drift check is against the version we
369
+ * just wrote, not a stale one from the original pull. Prefers the revision id
370
+ * carried on the response; falls back to one skills.read (or roles.read_skill
371
+ * for --role) when the response doesn't carry one.
372
+ *
373
+ * On 'created' specifically, a lookup miss clears head_revision_id to null
374
+ * rather than leaving the sidecar's old value in place: 'created' means the
375
+ * name didn't collide, so this is either a brand-new skill or a remote
376
+ * delete+recreate — either way the old revision id belongs to a different
377
+ * (possibly now-deleted) document, and sending it as base_version_id on a
378
+ * future edit would false-positive the concurrent_edit drift guard.
379
+ *
380
+ * Best-effort otherwise: a failed lookup on the 'updated' path just leaves
381
+ * the sidecar as-is rather than failing the push (which already succeeded).
382
+ */
383
+ async function refreshSidecarRevision(dir, sidecar, pushResult, options, config) {
384
+ const fromResponse = pushResult.data.head_revision_id ?? pushResult.data.version_id;
385
+ let headRevisionId = typeof fromResponse === 'number' ? fromResponse : null;
386
+ if (headRevisionId === null) {
387
+ const isRole = !!options.role;
388
+ const readArgs = isRole
389
+ ? { action: 'read_skill', role: options.role, name: pushResult.name }
390
+ : { action: 'read', identifier: pushResult.name };
391
+ try {
392
+ const readResult = await (0, mcp_1.callCrewsTool)(config, isRole ? 'roles' : 'skills', readArgs);
393
+ if (readResult.ok && typeof readResult.data?.head_revision_id === 'number') {
394
+ headRevisionId = readResult.data.head_revision_id;
395
+ }
396
+ }
397
+ catch {
398
+ // Best-effort refresh — leave the sidecar stale rather than failing the push.
399
+ }
400
+ }
401
+ if (headRevisionId === null && pushResult.status !== 'created') {
402
+ return;
403
+ }
404
+ const updated = { ...sidecar, head_revision_id: headRevisionId };
405
+ fs_1.default.writeFileSync(path_1.default.join(dir, skill_pull_1.SKILL_SIDECAR), JSON.stringify(updated, null, 2) + '\n', 'utf8');
406
+ }
328
407
  /**
329
408
  * Core implementation — accepts an injected config so tests can point at a
330
409
  * stub server without touching the filesystem config.
@@ -355,14 +434,19 @@ async function skillPushWithConfig(dir, options, config) {
355
434
  process.stderr.write(chalk_1.default.red(`error: ${e.message}\n`));
356
435
  process.exit(1);
357
436
  }
437
+ const sidecar = readSidecar(absDir);
438
+ const sidecarRevision = sidecar ? (sidecar.head_revision_id ?? null) : undefined;
358
439
  let pushResult;
359
440
  try {
360
- pushResult = await pushParsedSkill(payload, options, config);
441
+ pushResult = await pushParsedSkill(payload, options, config, sidecarRevision);
361
442
  }
362
443
  catch (e) {
363
444
  process.stderr.write(chalk_1.default.red(`error: ${e.message}\n`));
364
445
  process.exit(1);
365
446
  }
447
+ if (sidecar && (pushResult.status === 'updated' || pushResult.status === 'created')) {
448
+ await refreshSidecarRevision(absDir, sidecar, pushResult, options, config);
449
+ }
366
450
  // Optionally publish (snapshot) the just-pushed revision (single-skill mode).
367
451
  let publishOutcome = null;
368
452
  if (options.publish && !options.dryRun) {
@@ -0,0 +1,164 @@
1
+ "use strict";
2
+ var __importDefault = (this && this.__importDefault) || function (mod) {
3
+ return (mod && mod.__esModule) ? mod : { "default": mod };
4
+ };
5
+ Object.defineProperty(exports, "__esModule", { value: true });
6
+ exports.shellQuoteArg = shellQuoteArg;
7
+ exports.parseEnvFile = parseEnvFile;
8
+ exports.assembleEnv = assembleEnv;
9
+ exports.skillRunWithConfig = skillRunWithConfig;
10
+ exports.skillRun = skillRun;
11
+ /**
12
+ * solidactions skill run <dir> [--crew <c>] [--environment <env>] [--env-file <f>] -- <command...>
13
+ *
14
+ * Local analogue of the crews MCP exec_skill: runs <command> with cwd=<dir>
15
+ * (matching the sandbox's cwd=/work/skills/<slug>), with crew variables
16
+ * fetched at runtime from /api/v1/crews/{id}/variables/resolve. Secrets are
17
+ * included only when the API key holds env:reveal; skipped names are printed.
18
+ * DELIBERATE DIVERGENCE from remote exec_skill: default environment is `dev`
19
+ * (this is a dev tool); remote defaults to production. Always prints the env.
20
+ */
21
+ const fs_1 = __importDefault(require("fs"));
22
+ const os_1 = __importDefault(require("os"));
23
+ const path_1 = __importDefault(require("path"));
24
+ const child_process_1 = require("child_process");
25
+ const axios_1 = __importDefault(require("axios"));
26
+ const chalk_1 = __importDefault(require("chalk"));
27
+ const js_yaml_1 = __importDefault(require("js-yaml"));
28
+ const api_1 = require("../utils/api");
29
+ const crew_1 = require("../utils/crew");
30
+ const RESERVED_KEYS = ['WORKFLOW_INPUT', 'WORKFLOW_INPUT_URL', 'STEPS_TRIGGER_ID', 'TENANT_ID', 'SA_PROXY_URL', 'SA_PROXY_TOKEN', 'WORKFLOW_SLUG', 'PATH', 'HOME'];
31
+ const RESERVED_PREFIXES = ['SOLIDACTIONS_'];
32
+ function isReservedEnvName(name) {
33
+ return RESERVED_KEYS.includes(name) || RESERVED_PREFIXES.some((p) => name.toUpperCase().startsWith(p));
34
+ }
35
+ /**
36
+ * Single-quote a commander-parsed argument for re-injection into a shell
37
+ * command line. commander's `<command...>` variadic already split the
38
+ * user's invocation into discrete argv words (the outer shell did any
39
+ * quote-stripping); joining those words back together with bare spaces and
40
+ * handing them to `sh -c` would let the inner shell reinterpret any
41
+ * metacharacters they contain (spaces, quotes, parens, `&&`, ...). Quoting
42
+ * each word individually keeps it intact as a single shell token, while
43
+ * still letting `shell: true` run multi-word commands.
44
+ */
45
+ function shellQuoteArg(arg) {
46
+ return `'${arg.replace(/'/g, `'\\''`)}'`;
47
+ }
48
+ function parseEnvFile(content) {
49
+ const out = {};
50
+ for (const raw of content.split('\n')) {
51
+ const line = raw.trim();
52
+ if (!line || line.startsWith('#'))
53
+ continue;
54
+ const eq = line.indexOf('=');
55
+ if (eq <= 0)
56
+ continue;
57
+ const key = line.slice(0, eq).trim();
58
+ let value = line.slice(eq + 1).trim();
59
+ if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
60
+ value = value.slice(1, -1);
61
+ }
62
+ out[key] = value;
63
+ }
64
+ return out;
65
+ }
66
+ function assembleEnv(opts) {
67
+ const warnings = [];
68
+ const env = {};
69
+ for (const [key, value] of Object.entries(opts.resolved)) {
70
+ if (isReservedEnvName(key)) {
71
+ warnings.push(`crew variable '${key}' is reserved (set by the platform at runtime) — ignored`);
72
+ continue;
73
+ }
74
+ env[key] = value;
75
+ }
76
+ for (const [key, value] of Object.entries(opts.fileVars)) {
77
+ if (isReservedEnvName(key)) {
78
+ warnings.push(`env-file key '${key}' is reserved (set by the platform at runtime) — ignored`);
79
+ continue;
80
+ }
81
+ if (key in env) {
82
+ warnings.push(`env-file override shadows crew variable: ${key}`);
83
+ }
84
+ env[key] = value;
85
+ }
86
+ if (opts.storageScope === 'crew') {
87
+ env.SOLIDACTIONS_STATE_DIR = path_1.default.join(opts.dir, '.sa-state');
88
+ }
89
+ else if (opts.storageScope === 'workspace') {
90
+ env.SOLIDACTIONS_SHARED_DIR = path_1.default.join(os_1.default.homedir(), '.solidactions', 'shared', opts.config.workspaceId ?? 'default');
91
+ }
92
+ env.SOLIDACTIONS_API_URL = `${opts.config.host}/api/v1`;
93
+ env.SOLIDACTIONS_API_TOKEN = opts.config.apiKey;
94
+ env.SOLIDACTIONS_WORKSPACE_ID = opts.config.workspaceId ?? '';
95
+ return { env, warnings };
96
+ }
97
+ function readStorageScope(dir) {
98
+ const skillMd = path_1.default.join(dir, 'SKILL.md');
99
+ if (!fs_1.default.existsSync(skillMd))
100
+ return null;
101
+ const content = fs_1.default.readFileSync(skillMd, 'utf8');
102
+ const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
103
+ if (!match)
104
+ return null;
105
+ const fm = js_yaml_1.default.load(match[1]);
106
+ const scope = fm?.storage?.scope ?? fm?.['storage.scope'] ?? null;
107
+ return scope === 'crew' || scope === 'workspace' ? scope : null;
108
+ }
109
+ async function skillRunWithConfig(dir, commandParts, options, config) {
110
+ const absDir = path_1.default.resolve(dir);
111
+ if (!fs_1.default.existsSync(path_1.default.join(absDir, 'SKILL.md'))) {
112
+ process.stderr.write(chalk_1.default.red(`error: ${dir} does not contain a SKILL.md\n`));
113
+ process.exit(1);
114
+ }
115
+ if (commandParts.length === 0) {
116
+ process.stderr.write(chalk_1.default.red('error: no command given — usage: skill run <dir> -- <command...>\n'));
117
+ process.exit(1);
118
+ }
119
+ const environment = options.environment ?? 'dev';
120
+ // Crew vars: --crew wins; else no crew vars (shared-skill parity).
121
+ let resolved = {};
122
+ let skippedSecrets = [];
123
+ if (options.crew) {
124
+ const crew = await (0, crew_1.resolveCrewId)(config, options.crew);
125
+ try {
126
+ const response = await axios_1.default.get(`${config.host}/api/v1/crews/${crew.id}/variables/resolve?environment=${encodeURIComponent(environment)}`, { headers: (0, api_1.getApiHeaders)(config) });
127
+ resolved = response.data?.variables ?? {};
128
+ skippedSecrets = response.data?.skipped_secrets ?? [];
129
+ }
130
+ catch (e) {
131
+ process.stderr.write(chalk_1.default.red(`error: failed to resolve crew variables: ${e?.response?.data?.message ?? e.message}\n`));
132
+ process.exit(1);
133
+ }
134
+ }
135
+ else {
136
+ process.stderr.write(chalk_1.default.gray('no --crew given — running without crew variables (shared-skill parity)\n'));
137
+ }
138
+ const fileVars = options.envFile ? parseEnvFile(fs_1.default.readFileSync(path_1.default.resolve(options.envFile), 'utf8')) : {};
139
+ const storageScope = readStorageScope(absDir);
140
+ const { env, warnings } = assembleEnv({ resolved, fileVars, storageScope, dir: absDir, config });
141
+ for (const w of warnings)
142
+ process.stderr.write(chalk_1.default.yellow(`warn: ${w}\n`));
143
+ if (env.SOLIDACTIONS_STATE_DIR)
144
+ fs_1.default.mkdirSync(env.SOLIDACTIONS_STATE_DIR, { recursive: true });
145
+ if (env.SOLIDACTIONS_SHARED_DIR)
146
+ fs_1.default.mkdirSync(env.SOLIDACTIONS_SHARED_DIR, { recursive: true });
147
+ const plainCount = Object.keys(resolved).length;
148
+ process.stderr.write(chalk_1.default.blue(`running locally in ${dir} — env '${environment}', ${plainCount} crew vars loaded\n`));
149
+ if (skippedSecrets.length > 0) {
150
+ process.stderr.write(chalk_1.default.yellow(`${skippedSecrets.length} secret ${skippedSecrets.length === 1 ? 'var' : 'vars'} unavailable (${skippedSecrets.join(', ')}): ` +
151
+ `your API key lacks the 'env:reveal' ability. Mint a key with env:reveal, set a dev value with \`solidactions crew env set\`, or use --env-file.\n`));
152
+ }
153
+ const result = (0, child_process_1.spawnSync)(commandParts.map(shellQuoteArg).join(' '), {
154
+ shell: true,
155
+ cwd: absDir,
156
+ stdio: 'inherit',
157
+ env: { ...process.env, ...env },
158
+ });
159
+ process.exit(result.status ?? 1);
160
+ }
161
+ async function skillRun(dir, commandParts, options) {
162
+ const config = await (0, api_1.requireConfigWithWorkspace)();
163
+ await skillRunWithConfig(dir, commandParts, options, config);
164
+ }
package/dist/index.js CHANGED
@@ -41,8 +41,16 @@ const skill_pull_1 = require("./commands/skill-pull");
41
41
  const skill_list_1 = require("./commands/skill-list");
42
42
  const skill_view_1 = require("./commands/skill-view");
43
43
  const skill_delete_1 = require("./commands/skill-delete");
44
+ const skill_run_1 = require("./commands/skill-run");
45
+ const skill_exec_1 = require("./commands/skill-exec");
44
46
  const role_push_1 = require("./commands/role-push");
45
47
  const docs_push_1 = require("./commands/docs-push");
48
+ const docs_pull_1 = require("./commands/docs-pull");
49
+ const docs_upload_1 = require("./commands/docs-upload");
50
+ const crew_env_set_1 = require("./commands/crew-env-set");
51
+ const crew_env_list_1 = require("./commands/crew-env-list");
52
+ const crew_env_delete_1 = require("./commands/crew-env-delete");
53
+ const crew_env_push_1 = require("./commands/crew-env-push");
46
54
  const config_1 = require("./utils/config");
47
55
  // eslint-disable-next-line @typescript-eslint/no-var-requires
48
56
  const pkg = require('../package.json');
@@ -320,6 +328,50 @@ env
320
328
  (0, env_push_1.envPush)(projectName, path, options);
321
329
  });
322
330
  // =============================================================================
331
+ // crew env <subcommand>
332
+ // =============================================================================
333
+ const crew = program.command('crew').description('Manage crews');
334
+ const crewEnv = crew.command('env').description('Manage crew variables');
335
+ crewEnv
336
+ .command('set')
337
+ .description('Set a crew variable (create or update)')
338
+ .argument('<crew>', 'Crew name or id')
339
+ .argument('<key>', 'Variable key')
340
+ .argument('<value>', 'Variable value')
341
+ .option('-e, --env <environment>', 'Target environment (production/staging/dev/all)', 'all')
342
+ .option('--no-secret', 'Do not mark as secret — crew variables are secret by default (unlike `env set`)')
343
+ .action((crewArg, key, value, options) => {
344
+ (0, crew_env_set_1.crewEnvSet)(crewArg, key, value, options);
345
+ });
346
+ crewEnv
347
+ .command('list')
348
+ .description('List crew variables')
349
+ .argument('<crew>', 'Crew name or id')
350
+ .option('--json', 'Output as JSON')
351
+ .action((crewArg, options) => {
352
+ (0, crew_env_list_1.crewEnvList)(crewArg, options);
353
+ });
354
+ crewEnv
355
+ .command('delete')
356
+ .description('Delete a crew variable')
357
+ .argument('<crew>', 'Crew name or id')
358
+ .argument('<key>', 'Variable key')
359
+ .option('-y, --yes', 'Skip confirmation prompt')
360
+ .action((crewArg, key, options) => {
361
+ (0, crew_env_delete_1.crewEnvDelete)(crewArg, key, options);
362
+ });
363
+ crewEnv
364
+ .command('push')
365
+ .description('Push variables from a .env file to a crew')
366
+ .argument('<crew>', 'Crew name or id')
367
+ .argument('[file]', 'Source .env file', '.env')
368
+ .option('-e, --env <environment>', 'Target environment (production/staging/dev/all)', 'all')
369
+ .option('--no-secret', 'Do not mark pushed variables as secret — secret by default (unlike `env push`)')
370
+ .option('-y, --yes', 'Skip confirmation prompt')
371
+ .action((crewArg, file, options) => {
372
+ (0, crew_env_push_1.crewEnvPush)(crewArg, file, options);
373
+ });
374
+ // =============================================================================
323
375
  // schedule <subcommand>
324
376
  // =============================================================================
325
377
  const schedule = program.command('schedule').description('Manage cron schedules');
@@ -461,6 +513,7 @@ skill
461
513
  .option('--json', 'Output result as JSON')
462
514
  .option('--dry-run', 'Preview create vs update without writing')
463
515
  .option('--publish', 'Publish (snapshot) the skill after pushing, making it live for agents')
516
+ .option('--force', 'Skip the drift guard: push without checking the remote against your local sidecar revision')
464
517
  .action(async (dir, options) => {
465
518
  await (0, skill_push_1.skillPush)(dir, options);
466
519
  });
@@ -503,6 +556,28 @@ skill
503
556
  .action(async (name, options) => {
504
557
  await (0, skill_delete_1.skillDelete)(name, options);
505
558
  });
559
+ skill
560
+ .command('run')
561
+ .description('Run a skill script LOCALLY with crew variables fetched from the platform (dev loop; default env dev; secrets need env:reveal; see `skill exec` for the remote/deployed counterpart, default env production)')
562
+ .argument('<dir>', 'Local skill directory (must contain SKILL.md)')
563
+ .argument('<command...>', 'Command to run (after --), e.g. -- node scripts/q.js')
564
+ .option('--crew <nameOrId>', 'Crew whose variables to fetch (omit for shared skills)')
565
+ .option('--environment <env>', 'Variable environment: production|staging|dev', 'dev')
566
+ .option('--env-file <path>', 'Local KEY=VALUE overrides (reserved names ignored)')
567
+ .action(async (dir, commandParts, options) => {
568
+ await (0, skill_run_1.skillRun)(dir, commandParts, options);
569
+ });
570
+ skill
571
+ .command('exec')
572
+ .description('Run a command against the DEPLOYED skill in its real sandbox runtime (post-push smoke; default env production; see `skill run` for the local dev-loop counterpart, default env dev)')
573
+ .argument('<name>', 'Skill name or identifier')
574
+ .argument('<command...>', 'Command to run remotely (after --), e.g. -- node scripts/q.js')
575
+ .option('--role <name>', 'Role-scoped skill (uses roles.exec_skill)')
576
+ .option('--in-crew <crew>', 'Disambiguate when the role name exists in multiple crews')
577
+ .option('--environment <env>', 'Sandbox environment: production|staging|dev (default production)')
578
+ .action(async (name, commandParts, options) => {
579
+ await (0, skill_exec_1.skillExec)(name, commandParts, options);
580
+ });
506
581
  // =============================================================================
507
582
  // role <subcommand> (SOP surface — flat peer of skill, per cli#34)
508
583
  // =============================================================================
@@ -527,9 +602,30 @@ docs
527
602
  .option('--type <slug>', 'Doc-type slug to apply to all uploaded docs')
528
603
  .option('--folder <base>', 'Nest the whole upload under this base folder path in SA-Docs')
529
604
  .option('--dry-run', 'Preview what would be created without writing')
605
+ .option('--force', 'Overwrite tracked docs (from a prior docs pull) without a base-revision drift guard')
530
606
  .option('--json', 'Output result as JSON')
531
607
  .action(async (dir, options) => {
532
- await (0, docs_push_1.docsPush)(dir, { onConflict: options.onConflict, type: options.type, folder: options.folder, dryRun: options.dryRun, json: options.json });
608
+ await (0, docs_push_1.docsPush)(dir, { onConflict: options.onConflict, type: options.type, folder: options.folder, dryRun: options.dryRun, force: options.force, json: options.json });
609
+ });
610
+ docs
611
+ .command('pull')
612
+ .description('Download a Docs folder tree to a local directory for editing (inverse of push)')
613
+ .argument('<folder>', 'Docs folder path (or a single doc path)')
614
+ .argument('[dest]', 'Destination directory (defaults to ./<last-segment>/)')
615
+ .option('-y, --yes', 'Overwrite a non-empty destination without confirmation')
616
+ .option('--overwrite', 'DESTRUCTIVE: discard unpushed local changes (tracked files whose content no longer matches the last pull) and overwrite them; implies --yes')
617
+ .option('--json', 'Machine-readable output')
618
+ .action(async (folder, dest, options) => {
619
+ await (0, docs_pull_1.docsPull)(folder, dest, options);
620
+ });
621
+ docs
622
+ .command('upload <files...>')
623
+ .description('Upload one or more media files to SA-Docs (requires a token with the "docs" ability)')
624
+ .option('--folder <path>', 'Folder path to upload into (auto-created if missing)')
625
+ .option('--title <title>', 'Title for the uploaded doc (only valid with a single file)')
626
+ .option('--replace <doc-id-or-path>', 'replace the bytes of an existing media doc (by id, or by docs path)')
627
+ .action(async (files, options) => {
628
+ await (0, docs_upload_1.docsUpload)(files, { folder: options.folder, title: options.title, replace: options.replace });
533
629
  });
534
630
  program.parseAsync().catch((err) => {
535
631
  console.error(chalk_1.default.red(err.message ?? String(err)));
@@ -0,0 +1,72 @@
1
+ "use strict";
2
+ var __importDefault = (this && this.__importDefault) || function (mod) {
3
+ return (mod && mod.__esModule) ? mod : { "default": mod };
4
+ };
5
+ Object.defineProperty(exports, "__esModule", { value: true });
6
+ exports.CREW_ENV_VALUES = void 0;
7
+ exports.isValidCrewEnv = isValidCrewEnv;
8
+ exports.crewEnvError = crewEnvError;
9
+ exports.isNumericCrewArg = isNumericCrewArg;
10
+ exports.matchCrewByName = matchCrewByName;
11
+ exports.fetchCrews = fetchCrews;
12
+ exports.resolveCrewId = resolveCrewId;
13
+ const axios_1 = __importDefault(require("axios"));
14
+ const chalk_1 = __importDefault(require("chalk"));
15
+ const api_1 = require("./api");
16
+ exports.CREW_ENV_VALUES = ['production', 'staging', 'dev', 'all'];
17
+ function isValidCrewEnv(value) {
18
+ return exports.CREW_ENV_VALUES.includes(value);
19
+ }
20
+ function crewEnvError(value) {
21
+ return `Invalid --env "${value}" — must be one of: ${exports.CREW_ENV_VALUES.join(', ')}.`;
22
+ }
23
+ /** True when the crew argument should be used as an id directly, bypassing name lookup. */
24
+ function isNumericCrewArg(input) {
25
+ return /^\d+$/.test(input);
26
+ }
27
+ /** Pure: case-insensitive name match against a fetched crew list. */
28
+ function matchCrewByName(input, crews) {
29
+ const matches = crews.filter((c) => c.name.toLowerCase() === input.toLowerCase());
30
+ if (matches.length === 0)
31
+ return { status: 'not_found' };
32
+ if (matches.length > 1)
33
+ return { status: 'ambiguous', candidates: matches };
34
+ return { status: 'ok', crew: matches[0] };
35
+ }
36
+ async function fetchCrews(config) {
37
+ const response = await axios_1.default.get(`${config.host}/api/v1/crews`, { headers: (0, api_1.getApiHeaders)(config) });
38
+ return response.data?.data ?? [];
39
+ }
40
+ /**
41
+ * Resolve a crew CLI argument to an id. Numeric input is used directly as
42
+ * the id (no network call) — lets scripts skip the name lookup entirely and
43
+ * sidesteps ambiguity. Non-numeric input is matched by case-insensitive name
44
+ * against `GET /api/v1/crews`; ambiguous matches list candidates by id so
45
+ * the caller can retry unambiguously.
46
+ */
47
+ async function resolveCrewId(config, input) {
48
+ if (isNumericCrewArg(input)) {
49
+ return { id: input, name: input };
50
+ }
51
+ let crews;
52
+ try {
53
+ crews = await fetchCrews(config);
54
+ }
55
+ catch (error) {
56
+ console.error(chalk_1.default.red('Failed to list crews:'), error.response?.data?.message || error.message);
57
+ process.exit(1);
58
+ }
59
+ const result = matchCrewByName(input, crews);
60
+ if (result.status === 'not_found') {
61
+ console.error(chalk_1.default.red(`Crew "${input}" not found.`));
62
+ process.exit(1);
63
+ }
64
+ if (result.status === 'ambiguous') {
65
+ console.error(chalk_1.default.red(`Multiple crews named "${input}" found — specify by id instead:`));
66
+ for (const c of result.candidates) {
67
+ console.error(chalk_1.default.gray(` id=${c.id}${c.path ? ` path=${c.path}` : ''}`));
68
+ }
69
+ process.exit(1);
70
+ }
71
+ return result.crew;
72
+ }
@@ -0,0 +1,48 @@
1
+ "use strict";
2
+ /**
3
+ * Sidecar manifest (`.solidactions-docs.json`) shared by `docs pull` and
4
+ * `docs push` to track which local files correspond to which SA-Docs docs,
5
+ * and to detect local/server drift via a body sha256.
6
+ */
7
+ var __importDefault = (this && this.__importDefault) || function (mod) {
8
+ return (mod && mod.__esModule) ? mod : { "default": mod };
9
+ };
10
+ Object.defineProperty(exports, "__esModule", { value: true });
11
+ exports.DOCS_MANIFEST = void 0;
12
+ exports.sha256Hex = sha256Hex;
13
+ exports.readManifest = readManifest;
14
+ exports.writeManifest = writeManifest;
15
+ const fs_1 = __importDefault(require("fs"));
16
+ const path_1 = __importDefault(require("path"));
17
+ const crypto_1 = __importDefault(require("crypto"));
18
+ const chalk_1 = __importDefault(require("chalk"));
19
+ exports.DOCS_MANIFEST = '.solidactions-docs.json';
20
+ /** sha256 hex digest of the given bytes/string, as written to disk. */
21
+ function sha256Hex(data) {
22
+ return crypto_1.default.createHash('sha256').update(data).digest('hex');
23
+ }
24
+ /**
25
+ * Read `<dir>/.solidactions-docs.json`. Absent or unparseable → null,
26
+ * meaning nothing under `dir` is guarded (sidecar convention).
27
+ *
28
+ * `docs push` warns on unparseable JSON (files silently becoming untracked would
29
+ * re-create every doc); `docs pull` stays silent (it is about to rewrite it anyway).
30
+ */
31
+ function readManifest(dir, opts = {}) {
32
+ const manifestPath = path_1.default.join(dir, exports.DOCS_MANIFEST);
33
+ if (!fs_1.default.existsSync(manifestPath)) {
34
+ return null;
35
+ }
36
+ try {
37
+ return JSON.parse(fs_1.default.readFileSync(manifestPath, 'utf8'));
38
+ }
39
+ catch {
40
+ if (opts.warnOnParseError) {
41
+ process.stderr.write(chalk_1.default.yellow(`warn: ${exports.DOCS_MANIFEST} exists but could not be parsed — all files will be treated as untracked\n`));
42
+ }
43
+ return null;
44
+ }
45
+ }
46
+ function writeManifest(dir, manifest) {
47
+ fs_1.default.writeFileSync(path_1.default.join(dir, exports.DOCS_MANIFEST), `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
48
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@solidactions/cli",
3
- "version": "1.28.0",
3
+ "version": "1.30.0",
4
4
  "description": "SolidActions CLI - Deploy and manage workflow automation",
5
5
  "main": "dist/index.js",
6
6
  "bin": {