@solidactions/cli 3.1.0 → 3.3.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/dist/index.js CHANGED
@@ -37,6 +37,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
37
37
  return (mod && mod.__esModule) ? mod : { "default": mod };
38
38
  };
39
39
  Object.defineProperty(exports, "__esModule", { value: true });
40
+ exports.program = void 0;
40
41
  const chalk_1 = __importDefault(require("chalk"));
41
42
  const commander_1 = require("commander");
42
43
  const deploy_1 = require("./commands/deploy");
@@ -55,6 +56,7 @@ const env_delete_1 = require("./commands/env-delete");
55
56
  const env_map_1 = require("./commands/env-map");
56
57
  const env_pull_1 = require("./commands/env-pull");
57
58
  const env_push_1 = require("./commands/env-push");
59
+ const env_reset_1 = require("./commands/env-reset");
58
60
  const env_set_1 = require("./commands/env-set");
59
61
  const schedule_set_1 = require("./commands/schedule-set");
60
62
  const schedule_list_1 = require("./commands/schedule-list");
@@ -68,6 +70,7 @@ const oauth_action_search_1 = require("./commands/oauth-action-search");
68
70
  const oauth_action_list_1 = require("./commands/oauth-action-list");
69
71
  const oauth_action_view_1 = require("./commands/oauth-action-view");
70
72
  const oauth_action_platforms_1 = require("./commands/oauth-action-platforms");
73
+ const connection_list_1 = require("./commands/connection-list");
71
74
  const workspaces_1 = require("./commands/workspaces");
72
75
  const skill_push_1 = require("./commands/skill-push");
73
76
  const skill_publish_1 = require("./commands/skill-publish");
@@ -88,7 +91,7 @@ const crew_env_push_1 = require("./commands/crew-env-push");
88
91
  const config_1 = require("./utils/config");
89
92
  // eslint-disable-next-line @typescript-eslint/no-var-requires
90
93
  const pkg = require('../package.json');
91
- const program = new commander_1.Command();
94
+ exports.program = new commander_1.Command();
92
95
  if (process.env.SOLIDACTIONS_DEBUG === '1') {
93
96
  // eslint-disable-next-line @typescript-eslint/no-var-requires
94
97
  const { resolveConfig } = require('./utils/config');
@@ -111,7 +114,7 @@ if (process.env.SOLIDACTIONS_DEBUG === '1') {
111
114
  process.stderr.write('[SOLIDACTIONS_DEBUG] no config resolvable\n');
112
115
  }
113
116
  }
114
- program
117
+ exports.program
115
118
  .name('solidactions')
116
119
  .description('SolidActions CLI - Deploy and manage workflow automation')
117
120
  .version(pkg.version);
@@ -121,8 +124,8 @@ program
121
124
  // a parent option of the same name, so `login --workspace <x>` was being
122
125
  // swallowed by this global flag instead of reaching login()'s own option.
123
126
  // The short form `-w` is unaffected and remains the primary way to use this.
124
- program.option('-w, --workspace-override <id-or-slug-or-name>', 'Override active workspace for this command (short form: -w)');
125
- program.hook('preAction', (thisCommand, actionCommand) => {
127
+ exports.program.option('-w, --workspace-override <id-or-slug-or-name>', 'Override active workspace for this command (short form: -w)');
128
+ exports.program.hook('preAction', (thisCommand, actionCommand) => {
126
129
  const opts = thisCommand.opts();
127
130
  const wsOverride = opts.workspaceOverride;
128
131
  if (wsOverride) {
@@ -140,15 +143,15 @@ program.hook('preAction', (thisCommand, actionCommand) => {
140
143
  // =============================================================================
141
144
  // Top-level commands
142
145
  // =============================================================================
143
- program
146
+ exports.program
144
147
  .command('login')
145
148
  .description('Authenticate the CLI (prompts securely for your API key, or via --device for browser-based login)')
146
149
  .argument('[api-key]', 'Legacy positional API key (prefer the masked prompt, --stdin, or --device)')
147
150
  .option('--stdin', 'Read the API key from stdin (for non-interactive automation)')
148
151
  .option('--device', 'Authenticate via browser using OAuth device authorization')
149
- .option('--dev', 'Use local development server (http://localhost:8000)')
150
- .option('--host <url>', 'Custom API host URL')
151
- .option('--workspace <name-or-id>', 'Set workspace by name, slug, or ID (skips interactive prompt). Non-interactive logins without this flag leave the workspace unset.')
152
+ .addOption(new commander_1.Option('--dev', 'Use local development server (http://localhost:8000)').hideHelp())
153
+ .addOption(new commander_1.Option('--host <url>', 'Custom API host URL').hideHelp())
154
+ .option('--workspace <name-or-id>', 'Set workspace by name, slug, or ID. A sole workspace is auto-selected; use --workspace to choose among multiple workspaces.')
152
155
  .option('--local', 'Save config to ./.solidactions/config.json in the current folder')
153
156
  .option('--global', 'Save config to ~/.solidactions/config.json (default if prompted)')
154
157
  .option('--gitignore', 'With --local, add .solidactions/ to .gitignore without prompting')
@@ -166,7 +169,7 @@ Environment:
166
169
  const resolvedApiKey = await (0, login_1.resolveLoginApiKey)(apiKey, { stdin: options.stdin });
167
170
  await (0, login_1.login)(resolvedApiKey, options);
168
171
  });
169
- program
172
+ exports.program
170
173
  .command('init')
171
174
  .description('Scaffold a new SolidActions project (files + AI skills)')
172
175
  .argument('[directory]', 'Directory to create (omit to scaffold in the current empty directory)')
@@ -176,7 +179,7 @@ program
176
179
  .action(async (directory, options) => {
177
180
  await (0, init_1.init)(directory, options);
178
181
  });
179
- program
182
+ exports.program
180
183
  .command('logout')
181
184
  .description('Remove saved credentials')
182
185
  .option('--local', 'Remove only the nearest local ./.solidactions/config.json')
@@ -184,13 +187,13 @@ program
184
187
  .action((options) => {
185
188
  (0, login_1.logout)(options);
186
189
  });
187
- program
190
+ exports.program
188
191
  .command('whoami')
189
192
  .description('Show current configuration')
190
193
  .action(() => {
191
194
  (0, login_1.whoami)();
192
195
  });
193
- program
196
+ exports.program
194
197
  .command('dev')
195
198
  .description('Run a workflow locally using an in-memory mock server (no deploy needed)')
196
199
  .argument('<file>', 'Workflow file to run (e.g., src/simple-steps.ts)')
@@ -205,7 +208,7 @@ program
205
208
  // =============================================================================
206
209
  // project <subcommand>
207
210
  // =============================================================================
208
- const project = program.command('project').description('Manage projects');
211
+ const project = exports.program.command('project').description('Manage projects');
209
212
  project
210
213
  .command('view')
211
214
  .description('View project status and the client-reported deployed revision')
@@ -273,7 +276,7 @@ project
273
276
  // =============================================================================
274
277
  // run <subcommand>
275
278
  // =============================================================================
276
- const runCmd = program.command('run').description('Manage workflow runs');
279
+ const runCmd = exports.program.command('run').description('Manage workflow runs');
277
280
  runCmd
278
281
  .command('start')
279
282
  .description('Trigger a workflow run')
@@ -317,7 +320,7 @@ runCmd
317
320
  // =============================================================================
318
321
  // env <subcommand>
319
322
  // =============================================================================
320
- const env = program.command('env').description('Manage variables');
323
+ const env = exports.program.command('env').description('Manage variables');
321
324
  env
322
325
  .command('set')
323
326
  .description('Set a variable (create or update, global or project)')
@@ -326,6 +329,7 @@ env
326
329
  .argument('[value]', 'Variable value (when first arg is project)')
327
330
  .option('-s, --secret', 'Mark as encrypted secret')
328
331
  .option('-e, --env <environment>', 'Target environment (production/staging/dev)', 'dev')
332
+ .option('--oauth-connection <name>', 'Bind the project key to an OAuth connection')
329
333
  .option('--global', 'Set a global variable (no project) — required for the 2-arg form')
330
334
  .option('--staging-value <value>', 'Staging environment value (global only)')
331
335
  .option('--dev-value <value>', 'Dev environment value (global only)')
@@ -355,6 +359,16 @@ env
355
359
  .action((keyOrProject, key, options) => {
356
360
  (0, env_delete_1.envDelete)(keyOrProject, key, options);
357
361
  });
362
+ env
363
+ .command('reset')
364
+ .description('Reset a project variable mapping to its YAML-declared source')
365
+ .argument('<project>', 'Project name')
366
+ .argument('<KEY>', 'Variable key')
367
+ .allowExcessArguments(false)
368
+ .option('-e, --env <environment>', 'Environment to reset in', 'dev')
369
+ .action(async (projectName, key, options) => {
370
+ await (0, env_reset_1.envReset)(projectName, key, options);
371
+ });
358
372
  env
359
373
  .command('map')
360
374
  .description('Map a global variable to a project-specific key')
@@ -391,7 +405,7 @@ env
391
405
  // =============================================================================
392
406
  // crew env <subcommand>
393
407
  // =============================================================================
394
- const crew = program.command('crew').description('Manage crews');
408
+ const crew = exports.program.command('crew').description('Manage crews');
395
409
  const crewEnv = crew.command('env').description('Manage crew variables');
396
410
  crewEnv
397
411
  .command('set')
@@ -435,7 +449,7 @@ crewEnv
435
449
  // =============================================================================
436
450
  // schedule <subcommand>
437
451
  // =============================================================================
438
- const schedule = program.command('schedule').description('Manage cron schedules');
452
+ const schedule = exports.program.command('schedule').description('Manage cron schedules');
439
453
  schedule
440
454
  .command('set')
441
455
  .description('Set a cron schedule for a workflow')
@@ -467,7 +481,7 @@ schedule
467
481
  // =============================================================================
468
482
  // webhook <subcommand>
469
483
  // =============================================================================
470
- const webhook = program.command('webhook').description('Manage webhooks');
484
+ const webhook = exports.program.command('webhook').description('Manage webhooks');
471
485
  webhook
472
486
  .command('list')
473
487
  .description('List webhook URLs for a project')
@@ -491,7 +505,7 @@ webhook
491
505
  // =============================================================================
492
506
  // workspace <subcommand>
493
507
  // =============================================================================
494
- const workspace = program.command('workspace').description('Manage workspaces');
508
+ const workspace = exports.program.command('workspace').description('Manage workspaces');
495
509
  workspace
496
510
  .command('list')
497
511
  .description('List your workspaces across all organizations')
@@ -516,7 +530,7 @@ Where the pin is saved (--local / --global):
516
530
  // =============================================================================
517
531
  // oauth-action <subcommand>
518
532
  // =============================================================================
519
- const oauthActionCmd = program.command('oauth-action').description('Discover OAuth-backed API operations callable via the SA proxy');
533
+ const oauthActionCmd = exports.program.command('oauth-action').description('Discover OAuth-backed API operations callable via the SA proxy');
520
534
  oauthActionCmd
521
535
  .command('search <platform> [query]')
522
536
  .description('Search available actions for a connected platform')
@@ -551,9 +565,19 @@ oauthActionCmd
551
565
  (0, oauth_action_platforms_1.oauthActionPlatforms)(options);
552
566
  });
553
567
  // =============================================================================
568
+ // connection <subcommand>
569
+ // =============================================================================
570
+ const connection = exports.program.command('connection').description('Manage OAuth connections');
571
+ connection
572
+ .command('list')
573
+ .description('List OAuth connections in the active workspace')
574
+ .action(() => {
575
+ (0, connection_list_1.connectionList)();
576
+ });
577
+ // =============================================================================
554
578
  // ai <subcommand>
555
579
  // =============================================================================
556
- const ai = program.command('ai').description('AI helper tools');
580
+ const ai = exports.program.command('ai').description('AI helper tools');
557
581
  ai
558
582
  .command('init')
559
583
  .description('Install SolidActions AI skills and SDK reference for AI-assisted development')
@@ -570,7 +594,7 @@ ai
570
594
  // =============================================================================
571
595
  // skill <subcommand> (SOP surface — flat top-level noun per cli#34)
572
596
  // =============================================================================
573
- const skill = program.command('skill').description('Manage agent skills (crews SOP surface)');
597
+ const skill = exports.program.command('skill').description('Manage agent skills (crews SOP surface)');
574
598
  skill
575
599
  .command('push')
576
600
  .description('Push a local skill folder into the library (create, or update if it already exists)')
@@ -662,7 +686,7 @@ skill
662
686
  // =============================================================================
663
687
  // role <subcommand> (SOP surface — flat peer of skill, per cli#34)
664
688
  // =============================================================================
665
- const role = program.command('role').description('Manage roles (crews SOP surface)');
689
+ const role = exports.program.command('role').description('Manage roles (crews SOP surface)');
666
690
  role
667
691
  .command('push <dir>')
668
692
  .description('Push a role definition (create or update)')
@@ -674,7 +698,7 @@ role
674
698
  // =============================================================================
675
699
  // doc <subcommand> (SA-Docs surface)
676
700
  // =============================================================================
677
- const doc = program.command('doc').description('Manage docs in SA-Docs');
701
+ const doc = exports.program.command('doc').description('Manage docs in SA-Docs');
678
702
  doc
679
703
  .command('push')
680
704
  .description('Recursively upload a local markdown tree into SA-Docs')
@@ -708,7 +732,12 @@ doc
708
732
  .action(async (files, options) => {
709
733
  await (0, doc_upload_1.docUpload)(files, { folder: options.folder, title: options.title, replace: options.replace });
710
734
  });
711
- program.parseAsync().catch((err) => {
712
- console.error(chalk_1.default.red(err.message ?? String(err)));
713
- process.exit(1);
714
- });
735
+ // Only parse argv when this file IS the process entry point (the `solidactions`
736
+ // bin). The #1004 command-manifest generator requires this module to walk the
737
+ // assembled command tree; that must not consume the caller's argv or exit.
738
+ if (require.main === module) {
739
+ exports.program.parseAsync().catch((err) => {
740
+ console.error(chalk_1.default.red(err.message ?? String(err)));
741
+ process.exit(1);
742
+ });
743
+ }
package/dist/utils/api.js CHANGED
@@ -3,6 +3,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
3
3
  return (mod && mod.__esModule) ? mod : { "default": mod };
4
4
  };
5
5
  Object.defineProperty(exports, "__esModule", { value: true });
6
+ exports.SANDBOX_EGRESS_MESSAGE = void 0;
7
+ exports.augmentSandboxEgressMessage = augmentSandboxEgressMessage;
6
8
  exports.augmentNotFoundMessage = augmentNotFoundMessage;
7
9
  exports.augmentWorkspaceForbiddenMessage = augmentWorkspaceForbiddenMessage;
8
10
  exports.getApiHeaders = getApiHeaders;
@@ -22,6 +24,85 @@ const workspace_lookup_1 = require("./workspace-lookup");
22
24
  // We require the literal single-quotes around the slug so plausible future error messages
23
25
  // like "Project files not found ..." don't false-match.
24
26
  const NOT_FOUND_IN_WORKSPACE = /Project '.+' not found in your active workspace/;
27
+ exports.SANDBOX_EGRESS_MESSAGE = 'Sandbox network egress appears to be blocking app.solidactions.com. '
28
+ + "Allow-list app.solidactions.com in your provider's network settings, "
29
+ + 'start a new agent session if required, then retry. '
30
+ + 'See https://www.solidactions.com/docs/troubleshooting/#sandbox-egress';
31
+ const SANDBOX_EGRESS_PHRASES = [
32
+ /\bhost (?:is )?not permitted\b/i,
33
+ /\bnetwork access denied\b/i,
34
+ /\bnetwork egress\b[\s\S]*?\b(?:blocked|disabled)\b/i,
35
+ /\bdestination\b[\s\S]*?\bnot allowed\b/i,
36
+ ];
37
+ function responseServerHeader(headers) {
38
+ if (!headers) {
39
+ return '';
40
+ }
41
+ if (typeof headers.get === 'function') {
42
+ const value = headers.get('server') ?? headers.get('Server');
43
+ return value == null ? '' : String(value).trim();
44
+ }
45
+ for (const [name, value] of Object.entries(headers)) {
46
+ if (name.toLowerCase() === 'server') {
47
+ return value == null ? '' : String(value).trim();
48
+ }
49
+ }
50
+ return '';
51
+ }
52
+ function flattenProxyResponseText(data) {
53
+ if (typeof data === 'string') {
54
+ return data;
55
+ }
56
+ if (data instanceof Error) {
57
+ return data.message;
58
+ }
59
+ if (!data || typeof data !== 'object' || Array.isArray(data)) {
60
+ return '';
61
+ }
62
+ return ['error', 'message']
63
+ .map((field) => flattenProxyResponseText(data[field]))
64
+ .filter(Boolean)
65
+ .join('\n');
66
+ }
67
+ /**
68
+ * Diagnose a provider proxy's observed Cloud-host 403 without rewriting
69
+ * SolidActions authorization errors or failures against custom hosts.
70
+ */
71
+ function augmentSandboxEgressMessage(error) {
72
+ const response = error?.response;
73
+ if (response?.status !== 403 || responseServerHeader(response.headers)) {
74
+ return error;
75
+ }
76
+ const data = response.data;
77
+ const responseCode = data && typeof data === 'object' && !Array.isArray(data)
78
+ ? data.code
79
+ : null;
80
+ if (responseCode != null && String(responseCode).trim() !== '') {
81
+ return error;
82
+ }
83
+ const requestConfig = error.config ?? response.config;
84
+ let hostname = '';
85
+ try {
86
+ hostname = new URL(requestConfig?.url, requestConfig?.baseURL).hostname;
87
+ }
88
+ catch {
89
+ return error;
90
+ }
91
+ if (hostname !== 'app.solidactions.com') {
92
+ return error;
93
+ }
94
+ const proxyText = flattenProxyResponseText(data).trim();
95
+ if (!proxyText || !SANDBOX_EGRESS_PHRASES.some((phrase) => phrase.test(proxyText))) {
96
+ return error;
97
+ }
98
+ error.message = exports.SANDBOX_EGRESS_MESSAGE;
99
+ response.data = {
100
+ ...(data && typeof data === 'object' && !Array.isArray(data) ? data : {}),
101
+ message: `${exports.SANDBOX_EGRESS_MESSAGE}\n\nProvider response: ${proxyText}`,
102
+ providerResponse: data,
103
+ };
104
+ return error;
105
+ }
25
106
  /**
26
107
  * Inspect an axios error and, if its response message matches the new
27
108
  * workspace-not-found 404 from solidactions-app PR #128, append a
@@ -54,7 +135,7 @@ function augmentWorkspaceForbiddenMessage(error) {
54
135
  }
55
136
  return error;
56
137
  }
57
- axios_1.default.interceptors.response.use((response) => response, (error) => Promise.reject(augmentWorkspaceForbiddenMessage(augmentNotFoundMessage(error))));
138
+ axios_1.default.interceptors.response.use((response) => response, (error) => Promise.reject(augmentWorkspaceForbiddenMessage(augmentNotFoundMessage(augmentSandboxEgressMessage(error)))));
58
139
  function getApiHeaders(config, contentType) {
59
140
  const headers = {
60
141
  'Authorization': `Bearer ${config.apiKey}`,
@@ -165,6 +246,7 @@ async function ensureWorkspaceSelected(config) {
165
246
  workspaces.push({
166
247
  id: ws.id,
167
248
  name: ws.name,
249
+ slug: ws.slug,
168
250
  org_name: ws.tenant_name || orgName,
169
251
  role: ws.role,
170
252
  });
@@ -199,6 +281,11 @@ async function ensureWorkspaceSelected(config) {
199
281
  console.log(chalk_1.default.gray(`Auto-selected workspace: ${selected.name}`));
200
282
  }
201
283
  else {
284
+ if (!process.stdin.isTTY) {
285
+ console.error(chalk_1.default.red('Multiple workspaces are available and no workspace is set for this config. '
286
+ + 'Run `solidactions workspace set <name-or-id> --local` (or --global).'));
287
+ process.exit(1);
288
+ }
202
289
  console.log(chalk_1.default.blue('\nSelect your default workspace (change anytime with `solidactions workspace set`):\n'));
203
290
  workspaces.forEach((ws, i) => {
204
291
  console.log(` ${chalk_1.default.white(`${i + 1}.`)} ${ws.name} ${chalk_1.default.gray(`(${ws.org_name}, ${ws.role})`)}`);
@@ -216,6 +303,7 @@ async function ensureWorkspaceSelected(config) {
216
303
  }
217
304
  selected = workspaces[index];
218
305
  }
306
+ config.workspace = selected.slug ?? selected.name;
219
307
  config.workspaceId = selected.id;
220
308
  if (workspaceSource !== 'env') {
221
309
  const targetPath = resolved?.activePath ?? (0, config_1.getGlobalConfigPath)();
@@ -235,9 +323,5 @@ async function requireConfigWithWorkspace() {
235
323
  config = { ...config, workspace: ws.slug ?? ws.name, workspaceId: ws.id };
236
324
  return config;
237
325
  }
238
- if (!config.workspaceId && !process.stdin.isTTY) {
239
- console.error(chalk_1.default.red('No workspace set for this config. Run `solidactions workspace set <name-or-id> --local` (or --global).'));
240
- process.exit(1);
241
- }
242
326
  return ensureWorkspaceSelected(config);
243
327
  }
@@ -0,0 +1,221 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.COMMAND_MANIFEST_FILE = exports.COMMAND_MANIFEST_SCHEMA_VERSION = void 0;
4
+ exports.buildCommandManifest = buildCommandManifest;
5
+ /**
6
+ * Machine-readable description of the CLI's command surface, generated from the
7
+ * commander definitions at build time (#1004 PR 0). Consumers — chiefly the
8
+ * content repo's prose validator — pin a released manifest and fail CI when
9
+ * documentation names a command or flag that does not exist here.
10
+ *
11
+ * Follows the `schema_version` precedent set by src/utils/skill-cache.ts.
12
+ */
13
+ exports.COMMAND_MANIFEST_SCHEMA_VERSION = 1;
14
+ exports.COMMAND_MANIFEST_FILE = 'command-manifest.json';
15
+ /**
16
+ * True when `value` survives JSON.stringify without becoming undefined —
17
+ * functions, symbols and undefined do not, and must never reach the manifest.
18
+ */
19
+ function isJsonSafe(value) {
20
+ try {
21
+ return JSON.stringify(value) !== undefined;
22
+ }
23
+ catch {
24
+ return false;
25
+ }
26
+ }
27
+ function applyDefault(target, defaultValue, defaultValueDescription) {
28
+ if (defaultValue === undefined) {
29
+ if (defaultValueDescription !== undefined) {
30
+ target.default_description = defaultValueDescription;
31
+ }
32
+ return;
33
+ }
34
+ if (isJsonSafe(defaultValue)) {
35
+ target.default = defaultValue;
36
+ if (defaultValueDescription !== undefined) {
37
+ target.default_description = defaultValueDescription;
38
+ }
39
+ return;
40
+ }
41
+ target.default_description = defaultValueDescription ?? String(defaultValue);
42
+ }
43
+ function describeOption(option) {
44
+ const entry = {
45
+ flags: option.flags,
46
+ long: option.long ?? null,
47
+ short: option.short ?? null,
48
+ description: option.description,
49
+ required: option.mandatory === true,
50
+ value_required: option.required === true,
51
+ value_optional: option.optional === true,
52
+ variadic: option.variadic === true,
53
+ negated: option.negate === true,
54
+ hidden: option.hidden === true,
55
+ };
56
+ // commander's Command.addOption() (lib/command.js ~:548) defaults a negated
57
+ // option's positive attribute to `true` when no explicit defaultValue was
58
+ // given (and no positive counterpart option is registered) — e.g.
59
+ // `--no-cache` implicitly defaults `cache` to `true`. That implicit default
60
+ // lives in the Command's option-processing, not on Option.defaultValue, so
61
+ // it's otherwise invisible here.
62
+ const defaultValue = option.negate === true && option.defaultValue === undefined ? true : option.defaultValue;
63
+ applyDefault(entry, defaultValue, option.defaultValueDescription);
64
+ if (option.argChoices) {
65
+ entry.choices = [...option.argChoices];
66
+ }
67
+ return entry;
68
+ }
69
+ function describeArgument(argument) {
70
+ const entry = {
71
+ name: argument.name(),
72
+ required: argument.required === true,
73
+ variadic: argument.variadic === true,
74
+ description: argument.description,
75
+ };
76
+ applyDefault(entry, argument.defaultValue, argument.defaultValueDescription);
77
+ if (argument.argChoices) {
78
+ entry.choices = [...argument.argChoices];
79
+ }
80
+ return entry;
81
+ }
82
+ /**
83
+ * commander exposes no public getter for a command hidden via
84
+ * `.command(name, { hidden: true })` — the flag lives on the private `_hidden`
85
+ * field, which its own help renderer reads. Read it the same way.
86
+ */
87
+ function isHiddenCommand(command) {
88
+ return command._hidden === true;
89
+ }
90
+ /**
91
+ * commander auto-adds a `-h, --help` option to every command, but it is
92
+ * synthesized at help-render time (see lib/help.js `visibleOptions`) rather
93
+ * than being a real `Option` living in `command.options` — so the plain
94
+ * `command.options.map(describeOption)` walk below silently drops it from
95
+ * the manifest. Downstream doc validators need it (real prose documents
96
+ * `--help`), so read the same private fields commander's own help renderer
97
+ * reads (`_hasHelpOption`, `_helpFlags`, `_helpShortFlag`, `_helpLongFlag`,
98
+ * `_helpDescription` — there is no public getter for any of them) and
99
+ * synthesize an equivalent manifest entry by hand.
100
+ *
101
+ * commander also suppresses a help flag form when a real option on the
102
+ * command already owns that exact flag (`Help.visibleOptions` in
103
+ * lib/help.js, via `Command._findOption`/`Option.is`) — e.g.
104
+ * `.option('-h, --human')` steals `-h` from the synthesized help option, so
105
+ * only `--help` is shown. Mirror that per-form check here.
106
+ */
107
+ function describeHelpOption(command) {
108
+ const cmd = command;
109
+ if (cmd._hasHelpOption !== true) {
110
+ return null;
111
+ }
112
+ const ownsFlag = (flag) => flag !== undefined && command.options.some((option) => option.short === flag || option.long === flag);
113
+ const showShort = cmd._helpShortFlag !== undefined && !ownsFlag(cmd._helpShortFlag);
114
+ const showLong = !ownsFlag(cmd._helpLongFlag);
115
+ if (!showShort && !showLong) {
116
+ return null;
117
+ }
118
+ const short = showShort ? (cmd._helpShortFlag ?? null) : null;
119
+ const long = showLong ? (cmd._helpLongFlag ?? null) : null;
120
+ const flags = showShort && showLong
121
+ ? (cmd._helpFlags ?? [short, long].filter((flag) => flag !== null).join(', '))
122
+ : (long ?? short);
123
+ return {
124
+ flags,
125
+ long,
126
+ short,
127
+ description: cmd._helpDescription ?? '',
128
+ required: false,
129
+ value_required: false,
130
+ value_optional: false,
131
+ variadic: false,
132
+ negated: false,
133
+ hidden: false,
134
+ };
135
+ }
136
+ /**
137
+ * commander adds an implicit `help [command]` (sub)command to any command
138
+ * that has children, no action handler of its own, and no explicit `help`
139
+ * command already registered (`_hasImplicitHelpCommand()` in command.js) —
140
+ * but, like the `-h, --help` option above, it is synthesized at help-render
141
+ * time (see `Help.visibleCommands` in lib/help.js) rather than living in
142
+ * `command.commands`, so the recursive walk in `describeCommand` never sees
143
+ * it. It is real and typable at every level it applies — both
144
+ * `solidactions help project` and `solidactions project help view` work —
145
+ * so downstream doc validators need an entry for it too. Reconstruct it the
146
+ * same way commander's own help renderer does (there is no public API for
147
+ * any of `_hasImplicitHelpCommand`, `_helpCommandnameAndArgs`,
148
+ * `_helpCommandDescription`): build a throwaway `Command` from those private
149
+ * fields, then run it through the normal `describeCommand` walk so its shape
150
+ * (path, aliases, options via `describeHelpOption`, etc.) matches every
151
+ * other command for free.
152
+ */
153
+ function describeImplicitHelpCommand(command, path) {
154
+ const cmd = command;
155
+ if (typeof cmd._hasImplicitHelpCommand !== 'function' || !cmd._hasImplicitHelpCommand()) {
156
+ return [];
157
+ }
158
+ const nameAndArgs = cmd._helpCommandnameAndArgs ?? 'help [command]';
159
+ const match = nameAndArgs.match(/([^ ]+) *(.*)/);
160
+ const helpName = match?.[1] ?? 'help';
161
+ const helpArgs = match?.[2] ?? '';
162
+ // Same construction as commander's Help.visibleCommands: a fresh command
163
+ // with its own help option turned off (commander never lists "-h, --help"
164
+ // twice for the same invocation) and, when the nameAndArgs spec carries
165
+ // one (e.g. "[command]"), the optional target-command argument.
166
+ const helpCommand = command.createCommand(helpName).helpOption(false);
167
+ helpCommand.description(cmd._helpCommandDescription ?? '');
168
+ if (helpArgs) {
169
+ helpCommand.arguments(helpArgs);
170
+ }
171
+ return describeCommand(helpCommand, path);
172
+ }
173
+ function describeCommand(command, parentPath) {
174
+ const path = [...parentPath, command.name()];
175
+ const options = command.options.map(describeOption);
176
+ const helpOption = describeHelpOption(command);
177
+ if (helpOption) {
178
+ options.push(helpOption);
179
+ }
180
+ const entry = {
181
+ path,
182
+ name: command.name(),
183
+ aliases: [...command.aliases()],
184
+ description: command.description(),
185
+ hidden: isHiddenCommand(command),
186
+ arguments: command.registeredArguments.map(describeArgument),
187
+ options,
188
+ };
189
+ return [
190
+ entry,
191
+ ...command.commands.flatMap((child) => describeCommand(child, path)),
192
+ ...describeImplicitHelpCommand(command, path),
193
+ ];
194
+ }
195
+ /**
196
+ * Walk an assembled commander program into its manifest. Declaration order is
197
+ * preserved throughout: it is already deterministic and mirrors help ordering.
198
+ */
199
+ function buildCommandManifest(program, cliVersion) {
200
+ // The root program's `-h, --help` is the same commander-synthesized
201
+ // option as describeHelpOption handles per-command (see that function's
202
+ // comment) — commander keeps it outside `program.options` too, so the
203
+ // plain `program.options.map(describeOption)` walk below would otherwise
204
+ // silently drop it from global_options even though `solidactions --help`
205
+ // works (README.md documents it).
206
+ const globalOptions = program.options.map(describeOption);
207
+ const rootHelpOption = describeHelpOption(program);
208
+ if (rootHelpOption) {
209
+ globalOptions.push(rootHelpOption);
210
+ }
211
+ return {
212
+ schema_version: exports.COMMAND_MANIFEST_SCHEMA_VERSION,
213
+ cli_name: program.name(),
214
+ cli_version: cliVersion,
215
+ global_options: globalOptions,
216
+ commands: [
217
+ ...program.commands.flatMap((command) => describeCommand(command, [])),
218
+ ...describeImplicitHelpCommand(program, []),
219
+ ],
220
+ };
221
+ }