{{ message }}
Repository navigation
Expand file tree
/
Copy pathgenerate-cli-docs.ts
More file actions
1365 lines (1284 loc) · 49.6 KB
/
Copy pathgenerate-cli-docs.ts
File metadata and controls
1365 lines (1284 loc) · 49.6 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
#!/usr/bin/env bun
/**
* Generates the CLI command reference into `apps/docs/content/docs/cli`,
* alongside that section's hand-written guides, and owns the section's
* `meta.json` because the sidebar lists one entry per command group.
*
* The source of truth is the command tree the terminal itself parses —
* `buildProgram()` from `packages/sim-cli` — not the CLI contract and not the
* generated operation table. Both of those are upstream of the tree, so reading
* them instead would mean reimplementing `buildGeneratedCommands`, and the docs
* would be free to describe a surface no user can invoke.
*
* Run `bun run generate:cli-docs` after changing a command; `bun run
* check:cli-docs` fails when the checked-in pages are stale, which is how CI
* keeps them honest.
*/
import type { EventEmitter } from 'node:events'
import fs from 'node:fs'
import path from 'node:path'
import { fileURLToPath } from 'node:url'
import { compareStrings } from '@sim/utils/string'
import type { Command } from 'commander'
import { CLI_CONTRACT } from '../packages/sim-cli/src/contract/commands'
import { V2_OPERATIONS } from '../packages/sim-cli/src/generated/v2-api'
import { buildProgram } from '../packages/sim-cli/src/program'
import { calledOperations, operationOf } from '../packages/sim-cli/src/runtime/called-operations'
const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
export const OUTPUT_DIR = path.join(ROOT, 'apps/docs/content/docs/cli')
/** Commander's synthetic help command is not part of the documented surface. */
const HELP_COMMAND = 'help'
/**
* Hand-written pages in `OUTPUT_DIR`, in sidebar order.
*
* Generated pages sit beside them rather than in a subfolder so each command
* group is a root-level entry under the Commands heading instead of a nested
* folder the reader has to open. That means the stale-file sweep would delete
* these, so they are listed — the same guard `scripts/generate-docs.ts` uses for
* its hand-authored integration pages.
*/
export const GUIDE_PAGES = [
'index',
'authentication',
'configuration',
'output',
'scripting',
'workflow-sync',
'troubleshooting',
'usage-data',
] as const
/** Generated page holding the global options and the commands that take no resource. */
const OVERVIEW_PAGE = 'commands'
/** Generated page carrying every command at once, for search and for agents. */
const REFERENCE_PAGE = 'reference'
interface GroupDocumentation {
title?: string
description: string
notes?: readonly string[]
related?: readonly [string, string][]
}
const GROUP_DOCUMENTATION: Record<string, GroupDocumentation> = {
'audit-logs': {
description:
'Read organization audit actions and filter by actor, resource, workspace, or time.',
notes: [
'Requires an organization Admin or owner, an OAuth login or personal API key, and enabled enterprise audit access for the deployment.',
],
related: [
['Organization permissions', '/platform/permissions'],
['Authentication', '/cli/authentication'],
],
},
billing: {
description: 'Read billing status, credit usage, and storage usage.',
related: [
['Costs', '/platform/costs'],
['Authentication', '/cli/authentication'],
],
},
blocks: {
description:
'Inspect workflow blocks, integration blocks, and triggers available to the workspace.',
notes: [
'The catalog reflects the workspace’s allowed integrations, revealed preview blocks, and deployed custom blocks.',
],
},
'chat-deployments': {
description: 'List workflow chat deployments in the workspace.',
related: [['Deploy or update a workflow chat', '/cli/workflows#chat-deployments']],
},
cli: {
title: 'Command search',
description: 'Find a command by describing the task you want to perform.',
},
'connector-types': {
description:
'Discover knowledge connectors and their authentication and source-configuration schemas.',
notes: ['Use `--detail full` to inspect a connector’s configuration before creating it.'],
related: [['Create and sync knowledge connectors', '/cli/knowledge#connectors']],
},
credentials: {
description: 'Discover providers, connect accounts, and manage credential access.',
notes: [
'Run `sim --output json credentials providers list` to inspect the provider’s fields and authentication requirements before creating a service-account credential. OAuth connection commands return a link that a person must open to authorize the connection.',
],
related: [['Credentials', '/platform/credentials']],
},
'custom-tools': {
description: 'Create and manage code-backed tools that agents can call.',
related: [['Custom tools', '/agents/custom-tools']],
},
files: {
description:
'Browse workspace files, read or write content, manage versions, and configure sharing.',
related: [
['Files', '/files'],
['Output formats', '/cli/output'],
],
},
knowledge: {
description: 'Manage knowledge bases, indexed documents, search, tags, and connector syncs.',
related: [
['Knowledge Base', '/knowledgebase'],
['Tags and filters', '/knowledgebase/tags'],
['Export and import', '/knowledgebase/export-import'],
],
},
logs: {
description: 'Read run diagnostics, follow new runs, and summarize failures and latency.',
related: [
['Logs and debugging', '/logs-debugging'],
['Output formats', '/cli/output'],
],
},
'mcp-servers': {
title: 'MCP servers',
description:
'Connect external Model Context Protocol (MCP) servers so workflows can use their tools.',
notes: [
'To serve Sim workflows to MCP clients instead, use [workflow MCP servers](/cli/workflow-mcp-servers).',
],
related: [['MCP connections', '/agents/mcp']],
},
meta: {
title: 'API status',
description: 'Inspect API availability and the calling credential’s type and expiry.',
related: [['Authentication', '/cli/authentication']],
},
organizations: {
description: 'Manage organization membership, invitations, usage, access requests, and SSO.',
related: [
['Organizations', '/platform/organization'],
['Permissions', '/platform/permissions'],
],
},
'permission-groups': {
description:
'Manage organization permission groups, their configuration, and member assignments.',
notes: [
'Use the linked API request schema for the supported `--config` keys. Supplied arrays replace their entire lists; omitted settings remain unchanged on update.',
],
related: [['Permission groups', '/platform/permissions']],
},
profiles: {
description: 'List profiles and add a workspace profile that shares a stored login.',
notes: [
'Adding a profile reuses the active stored login and selects a default workspace. Supply `--workspace` when running without an interactive terminal.',
],
related: [
['Configuration', '/cli/configuration'],
['Authentication', '/cli/authentication'],
],
},
sandboxes: {
description: 'Manage reusable dependency sets for Function blocks.',
related: [['Function sandboxes', '/workflows/blocks/function#sandboxes']],
},
secrets: {
description: 'Set and manage workspace or personal secrets.',
notes: [
'Personal secrets belong to the caller across workspaces. Workspace secrets are shared resources. Listings include stored values only for workspace secrets marked visible (unredacted); all other entries contain metadata.',
],
related: [['Credentials and secrets', '/platform/credentials']],
},
selectors: {
description:
'Discover destination options for registered fields, such as calendars, channels, and tables.',
notes: [
'A selector key identifies the field’s option source. Its context accepts only declared dependencies; missing OAuth access requires a person to authorize the connection.',
],
},
skills: {
description: 'Create reusable agent instructions and manage their editors.',
related: [['Skills', '/agents/skills']],
},
tables: {
description: 'Manage tables, rows, schemas, views, enrichment runs, imports, and exports.',
related: [
['Tables', '/tables'],
['Workflow columns', '/tables/workflow-columns'],
],
},
telemetry: {
description: 'Inspect and change this machine’s anonymous usage-reporting preference.',
related: [['Usage data', '/cli/usage-data']],
},
tools: {
description: 'Find built-in tools, inspect their parameters, and run them.',
notes: [
'Inspect a tool with `sim tools get <toolId>` before passing its parameters to `sim tools execute`.',
],
},
'workflow-mcp-servers': {
title: 'Workflow MCP servers',
description: 'Serve deployed workflows as tools for Model Context Protocol (MCP) clients.',
notes: [
'These servers expose Sim workflows. To connect a server that provides external tools, use [MCP servers](/cli/mcp-servers).',
],
related: [['MCP connections', '/agents/mcp']],
},
workflows: {
description: 'Build, deploy, run, and inspect workflows from the terminal.',
related: [
['Workflow builder', '/workflows'],
['Import and workspace sync', '/cli/workflow-sync'],
['Scripting and exit codes', '/cli/scripting#exit-codes'],
],
},
workspaces: {
description: 'Read workspace access and manage reviewed fork, push, and pull operations.',
related: [
['Workspace sync', '/cli/workflow-sync'],
['Workspaces', '/platform/workspaces'],
],
},
}
interface CommandSection {
title: string
prefixes: readonly string[]
}
const GROUP_SECTIONS: Record<string, readonly CommandSection[]> = {
credentials: [
{
title: 'Provider discovery and connections',
prefixes: ['providers', 'list', 'create', 'connect', 'reconnect', 'update'],
},
{ title: 'Credential members', prefixes: ['members'] },
{ title: 'Disconnect credentials', prefixes: ['delete'] },
],
files: [
{ title: 'Browse and inspect', prefixes: ['ls', 'list', 'search', 'describe'] },
{ title: 'Upload, create, and read', prefixes: ['upload', 'create', 'get', 'read'] },
{ title: 'Edit and organize', prefixes: ['edit', 'set-content', 'rename', 'move', 'unzip'] },
{ title: 'Sharing', prefixes: ['share'] },
{
title: 'Versions',
prefixes: [
'versions list',
'versions describe',
'versions read',
'versions download',
'versions revert',
'versions delete',
],
},
{ title: 'Archive and restore', prefixes: ['delete', 'batch-delete', 'restore'] },
{ title: 'Folders', prefixes: ['folders', 'mkdir'] },
],
knowledge: [
{
title: 'Knowledge bases',
prefixes: ['list', 'get', 'create', 'update', 'mv', 'delete', 'restore'],
},
{ title: 'Search and export', prefixes: ['search', 'export'] },
{ title: 'Documents', prefixes: ['documents', 'from-workspace-files'] },
{ title: 'Chunks', prefixes: ['chunks'] },
{ title: 'Tags', prefixes: ['tags'] },
{
title: 'Connectors',
prefixes: [
'connectors list',
'connectors get',
'connectors create',
'connectors update',
'connectors sync',
'connectors documents',
'connectors delete',
],
},
{ title: 'Folders', prefixes: ['ls', 'folders', 'mkdir'] },
],
'mcp-servers': [
{ title: 'Server connections', prefixes: ['list', 'get', 'create', 'update'] },
{ title: 'Tool discovery', prefixes: ['tools'] },
{ title: 'Remove servers', prefixes: ['delete'] },
],
organizations: [
{ title: 'Organizations and workspaces', prefixes: ['list', 'get', 'workspaces'] },
{ title: 'Members and credit limits', prefixes: ['members'] },
{ title: 'Invitations', prefixes: ['invitations'] },
{ title: 'Usage', prefixes: ['usage summary', 'usage breakdown', 'usage events'] },
{
title: 'Access requests',
prefixes: [
'access-requests discover',
'access-requests create',
'access-requests mine',
'access-requests cancel',
'access-requests list',
'access-requests preview',
'access-requests resolve',
'access-requests settings',
],
},
{
title: 'Verified domains',
prefixes: ['domains list', 'domains add', 'domains verify', 'domains remove'],
},
{
title: 'SSO providers and policy',
prefixes: [
'sso providers list',
'sso providers get',
'sso providers save',
'sso providers primary',
'sso providers delete',
'sso policy',
],
},
],
'permission-groups': [
{ title: 'Group configuration', prefixes: ['list', 'get', 'create', 'update'] },
{ title: 'Member assignments', prefixes: ['members'] },
{ title: 'Delete groups', prefixes: ['delete'] },
],
skills: [
{ title: 'Skill instructions', prefixes: ['list', 'get', 'create', 'update'] },
{ title: 'Editors', prefixes: ['editors'] },
{ title: 'Delete skills', prefixes: ['delete'] },
],
tables: [
{
title: 'Tables',
prefixes: [
'list',
'get',
'create',
'update',
'move',
'mv',
'delete',
'batch-delete',
'restore',
],
},
{ title: 'Rows and queries', prefixes: ['rows', 'upsert'] },
{ title: 'Columns', prefixes: ['columns'] },
{ title: 'Saved views', prefixes: ['views'] },
{
title: 'Producer groups and runs',
prefixes: ['groups', 'enrichment', 'dispatches', 'cancel-runs'],
},
{ title: 'Imports', prefixes: ['import', 'imports'] },
{
title: 'Exports',
prefixes: ['exports create', 'exports get', 'exports download', 'exports cancel'],
},
{ title: 'Folders', prefixes: ['ls', 'folders', 'mkdir'] },
],
'workflow-mcp-servers': [
{ title: 'Servers', prefixes: ['list', 'get', 'create', 'update'] },
{ title: 'Workflow tools', prefixes: ['tools'] },
{ title: 'Delete servers', prefixes: ['delete'] },
],
workflows: [
{
title: 'Workflows',
prefixes: ['list', 'get', 'create', 'update', 'duplicate', 'move', 'mv', 'delete', 'restore'],
},
{ title: 'Draft state and edits', prefixes: ['state', 'operations', 'variables'] },
{
title: 'Deployments and versions',
prefixes: ['deploy', 'deployment', 'versions', 'activate', 'revert', 'rollback', 'undeploy'],
},
{
title: 'Run and inspect',
prefixes: ['run', 'runs list', 'runs get', 'runs wait', 'runs resume', 'runs cancel'],
},
{ title: 'Chat deployments', prefixes: ['chat status', 'chat publish', 'chat unpublish'] },
{ title: 'Export and import', prefixes: ['export', 'import-preview', 'import'] },
{ title: 'Folders', prefixes: ['ls', 'folders', 'mkdir'] },
],
workspaces: [
{
title: 'Workspace access',
prefixes: ['list', 'get', 'members', 'invitations', 'permission-config'],
},
{
title: 'Access requests',
prefixes: [
'access-requests discover',
'access-requests create',
'access-requests mine',
'access-requests cancel',
],
},
{
title: 'Forks and lineage',
prefixes: [
'fork-availability',
'fork-resources',
'fork-preview',
'fork',
'lineage',
'children',
],
},
{ title: 'Mappings', prefixes: ['mappings'] },
{ title: 'Push and pull', prefixes: ['push-preview', 'push', 'pull-preview', 'pull'] },
{ title: 'Operation status', prefixes: ['operations'] },
{ title: 'Exclusions and recovery', prefixes: ['sync-exclusions', 'fork-rollback', 'unlink'] },
],
}
const COMMAND_NOTES: Record<string, readonly string[]> = {
'tables import': [
'Choose exactly one source: a local CSV path or `--file-id`. For a new table imported with `--file-id`, supply `--name`. With `--table-id`, omit the new-table `--name` and `--folder` flags; `--mode`, `--mapping`, and `--create-columns` apply only to an existing table.',
'**Replace mode deletes all existing rows before loading the CSV and cannot be undone.** It requires `--yes`; cancellation leaves only the rows already imported.',
'The command watches the import by default. `--no-wait` returns a queued receipt. A completed import can still report `rowsRejected`, `cellsRejected`, and `rejectedSamples`; inspect them before accepting the result.',
],
'workflows chat publish': [
'Omitting `--auth-type` selects public access: anyone holding the URL can chat. Supply the complete password or allow-list settings again when replacing a restricted deployment.',
],
'workflows runs cancel': [
'Canceling a paused run prevents resuming that run. Starting a new run can repeat side effects already performed.',
],
'workflows export': [
'The export clears credentials, passwords, and table sub-block values, but it is not a general secret scanner. Inspect literal variables and inline configuration before sharing the document.',
],
'organizations sso providers save': [
'Choose `--provider-type oidc` or `saml`. OIDC requires `--client-id` and `--client-secret`; SAML requires `--entry-point` and `--cert`. Both require an organization-verified domain. The option descriptions state which omitted fields are preserved or cleared.',
],
}
const LEGACY_COMMAND_ANCHORS: Record<string, string> = {
'workflow-mcp-servers tools create': 'publish-workflow-as-mcp-tool',
'workflow-mcp-servers tools delete': 'unpublish-workflow-mcp-tool',
'cli search': 'find-the-command-for-a-task-described-in-plain-words',
'telemetry status': 'show-whether-usage-reporting-is-on-and-why-not-if-it-is-off',
'telemetry enable': 'turn-usage-reporting-on-for-this-machine',
'workflows runs wait': 'wait-for-a-run-to-reach-a-terminal-state-then-show-it',
'workflows chat publish': 'publish-or-replace-a-workflows-chat-deployment',
'workspaces operations wait':
'wait-for-copy-and-deployment-readiness-exit-3-for-configuration-1-for-failure-or-4-for-timeout',
}
const VERB_ORDER = [
'list',
'ls',
'get',
'status',
'describe',
'query',
'count',
'search',
'stats',
'preview',
'discover',
'create',
'add',
'upload',
'save',
'set',
'upsert',
'update',
'edit',
'apply',
'update-each',
'batch-update',
'usage',
'next-slot',
'sync',
'primary',
'enrich',
'read',
'download',
'compare',
'revert',
'wait',
'resume',
'resend',
'cancel',
'delete',
'batch-delete',
'cleanup',
'remove',
'revoke',
'restore',
] as const
interface ApiReferenceOperation {
operationId?: string
tags?: string[]
}
function apiReferenceLinks(): Map<string, string> {
const links = new Map<string, string>()
for (const name of fs.readdirSync(path.join(ROOT, 'apps/docs'))) {
if (!/^openapi-v2-.*\.json$/.test(name)) continue
const document = JSON.parse(fs.readFileSync(path.join(ROOT, 'apps/docs', name), 'utf8')) as {
paths: Record<string, Record<string, ApiReferenceOperation>>
}
for (const [route, operations] of Object.entries(document.paths)) {
for (const [method, operation] of Object.entries(operations)) {
const tag = operation.tags?.[0]
if (!operation.operationId || !tag) continue
const url = `/api-reference/${tag.toLowerCase().replaceAll(' ', '-')}/${operation.operationId}`
links.set(operation.operationId, url)
links.set(`${method.toUpperCase()} ${route}`, url)
}
}
}
return links
}
interface DocumentedCommand {
/** Full invocation path, e.g. `workflows runs get`. */
path: string[]
command: Command
}
function titleFor(name: string): string {
return GROUP_DOCUMENTATION[name]?.title ?? sentenceCase(name.replaceAll('-', ' '))
}
/**
* Commander records a hidden command on a private field and offers no getter,
* so this narrows structurally rather than widening the command to `any`.
*/
function isHiddenCommand(command: Command): boolean {
return (command as Command & { _hidden?: boolean })._hidden === true
}
/** Every option a reader should be taught, in declaration order. */
function documentedOptions(command: Command): Command['options'] {
return command.options.filter((option) => !option.hidden)
}
/**
* Hidden entries are excluded for the same reason `--help` omits them: they are
* spellings the CLI has retired and keeps working only so an existing script
* does not break. Documenting one would teach the name being retired.
*/
function subcommands(command: Command): Command[] {
return command.commands.filter(
(child) => child.name() !== HELP_COMMAND && !isHiddenCommand(child)
)
}
/** Depth-first walk yielding every leaf command, in the order commander lists them. */
function collectLeaves(command: Command, prefix: string[]): DocumentedCommand[] {
const children = subcommands(command)
if (children.length === 0) return [{ path: prefix, command }]
return children.flatMap((child) => collectLeaves(child, [...prefix, child.name()]))
}
/**
* Wraps a value in a code span for a Markdown table cell.
*
* A code span already shields `<` and `{` from MDX, and character references
* are NOT decoded inside one — escaping `<` to `<` here would render the
* entity itself, so `|` is the only character that still has to be escaped. It
* has to be: a literal pipe ends the cell, and flags like `--mode <a|b>` and
* the row filter help both contain one.
*/
function code(value: string): string {
return value.includes('\\') ? literalCode(value) : `\`${value.replace(/\|/g, '\\|')}\``
}
/** A JSX string keeps code containing backslashes and pipes lossless through GFM tables. */
function literalCode(value: string): string {
return `<code>{${JSON.stringify(value).replaceAll('|', '\\u007c')}}</code>`
}
/** Escapes backslashes and pipes in Markdown table prose. */
function escapeTablePipes(value: string): string {
return value.replace(/\\/g, '\\\\').replace(/\|/g, '\\|')
}
function escapeCell(value: string): string {
return mapCodeSpans(
value,
(text) => escapeTablePipes(escapeText(text)),
(span, content) => (content.includes('\\') ? literalCode(content) : span.replace(/\|/g, '\\|'))
)
}
function escapeText(value: string): string {
return value
.replace(/</g, '<')
.replace(/>/g, '>')
.replace(/\{/g, '{')
.replace(/\}/g, '}')
}
/** Escapes MDX-significant prose while retaining inline-code contents. */
function escapeProse(value: string): string {
return mapCodeSpans(value, escapeText, (span) => span)
}
function mapCodeSpans(
value: string,
prose: (text: string) => string,
inlineCode: (span: string, content: string) => string
): string {
const delimiters = [...value.matchAll(/`+/g)]
let result = ''
let offset = 0
for (let index = 0; index < delimiters.length; index += 1) {
const opening = delimiters[index]
if (!opening) continue
let precedingBackslashes = 0
for (
let position = opening.index - 1;
position >= 0 && value[position] === '\\';
position -= 1
) {
precedingBackslashes += 1
}
if (precedingBackslashes % 2 !== 0) continue
const closingIndex = delimiters.findIndex(
(delimiter, candidate) => candidate > index && delimiter[0].length === opening[0].length
)
const closing = delimiters[closingIndex]
if (!closing) continue
const end = closing.index + closing[0].length
result +=
prose(value.slice(offset, opening.index)) +
inlineCode(
value.slice(opening.index, end),
value.slice(opening.index + opening[0].length, closing.index)
)
offset = end
index = closingIndex
}
return result + prose(value.slice(offset))
}
function usageLine(entry: DocumentedCommand): string {
const parts = ['sim', ...entry.path]
for (const argument of entry.command.registeredArguments) {
const name = argument.variadic ? `${argument.name()}...` : argument.name()
parts.push(argument.required ? `<${name}>` : `[${name}]`)
}
if (documentedOptions(entry.command).length > 0) parts.push('[options]')
return parts.join(' ')
}
const REQUIRED_SUFFIX = /\s*\(required\)\s*$/i
/**
* Commander help already spells required-ness inside the description of a
* derived flag. The table states it in its own column, so the trailing marker
* would read as "Yes | Workflow ID (required)".
*/
function stripRequiredSuffix(description: string): string {
return description.replace(REQUIRED_SUFFIX, '')
}
/**
* Whether the flag must be supplied for the command to run.
*
* `option.mandatory` alone under-reports it. A destructive command's `--yes` is
* enforced by the runtime rather than by Commander, deliberately: making it
* mandatory would replace the refusal that names the consequence ("This deletes
* the knowledge base and every document in it. Re-run with --yes to confirm.")
* with Commander's bare "required option '--yes' not specified". The flag is
* still required, and the description says so — which is the same marker
* {@link stripRequiredSuffix} removes, so reading it here keeps the column and
* the prose from contradicting each other.
*/
function isRequiredOption(option: Command['options'][number]): boolean {
return option.mandatory || REQUIRED_SUFFIX.test(option.description || '')
}
/** Help text is written without terminal punctuation; appended clauses need it. */
function asSentence(value: string): string {
if (!value) return ''
return /[.!?]$/.test(value) ? value : `${value}.`
}
/**
* Renders a default value for prose, or `''` when there is nothing to state.
*
* A repeatable flag's Commander default is `[]` — the empty accumulator its
* collector appends to, not a value anyone would type — and `String([])` is the
* empty string, which rendered as a dangling "Defaults to ``." The check is on
* emptiness rather than falsiness: `false` and `0` are real defaults a caller
* needs stated, and a `!value` guard would silently drop both.
*/
export function formatDefault(value: unknown): string {
if (Array.isArray(value)) {
return value.length > 0 ? value.map(String).join(', ') : ''
}
const text = String(value)
return text.trim() ? text : ''
}
/** Returns a table-ready cell: escaped prose, with code spans left intact. */
export function describeOption(option: Command['options'][number]): string {
const parts = [asSentence(escapeCell(stripRequiredSuffix(option.description || '')))]
if (option.argChoices && option.argChoices.length > 0) {
parts.push(`Accepted values: ${option.argChoices.map(code).join(', ')}.`)
}
const defaultValue = option.defaultValue ?? option.defaultValueDescription
if (defaultValue !== undefined && !/\bdefault(?:s|ing)?\b/i.test(option.description)) {
const fallback = formatDefault(defaultValue)
if (fallback) parts.push(`Defaults to ${code(fallback)}.`)
}
const description = parts.filter(Boolean).join(' ')
return description || '—'
}
/**
* Wraps a Markdown table so `CommandTable` can size its columns.
*
* The blank lines are load-bearing: without them MDX treats the table as raw
* JSX children and stops parsing it as Markdown.
*/
function sizedTable(rows: string[]): string[] {
return ['', '<CommandTable>', '', ...rows, '', '</CommandTable>']
}
function renderArguments(entry: DocumentedCommand): string[] {
const args = entry.command.registeredArguments
if (args.length === 0) return []
// Positional descriptions come from the route contract and are usually absent;
// a column of em-dashes is worse than no column.
const described = args.some((argument) => Boolean(argument.description))
const rows = args.map((argument) => {
const name = argument.variadic ? `${argument.name()}...` : argument.name()
const required = argument.required ? 'Yes' : 'No'
const cells = [code(name), required]
if (described) cells.push(escapeCell(argument.description) || '—')
return `| ${cells.join(' | ')} |`
})
const header = described ? '| Argument | Required | Description |' : '| Argument | Required |'
const divider = described ? '| --- | --- | --- |' : '| --- | --- |'
return ['', '**Arguments**', ...sizedTable([header, divider, ...rows])]
}
function renderOptions(entry: DocumentedCommand): string[] {
const options = documentedOptions(entry.command)
if (options.length === 0) return []
const rows = options.map(
(option) =>
`| ${code(option.flags)} | ${isRequiredOption(option) ? 'Yes' : /\brequired (?:when|with|unless|only)/i.test(option.description) ? 'Conditional' : 'No'} | ${describeOption(option)} |`
)
return [
'',
'**Options**',
...sizedTable(['| Option | Required | Description |', '| --- | --- | --- |', ...rows]),
]
}
/**
* Words that must keep their casing when a heading is sentence-cased.
*
* The test for "this word was capitalized only because the summary is Title
* Case" cannot tell `Documents` from `JSON`, and lowercasing the latter is the
* more visible mistake.
*/
const ACRONYMS = new Set([
'API',
'APIs',
'CSV',
'ID',
'IDs',
'JSON',
'MCP',
'OAuth',
'Sim',
'SSE',
'SSO',
'URL',
'YAML',
'OIDC',
'SAML',
'PKCE',
'DNS',
'UTC',
])
/**
* The command's one-line description, as a heading.
*
* The command itself is the obvious heading and is the wrong one: every entry
* on a page shares the same `sim <group>` prefix, so the table of contents
* became a column of "sim knowledge documents …" that has to be read to the
* last word to tell two entries apart. The description distinguishes them at
* the first word instead, and the exact invocation is still directly below in
* the code block.
*
* A trailing parenthetical is dropped — those qualify behavior ("(requested
* outputs are included in JSON or YAML output)") and belong in the body, not in
* a sidebar entry.
*/
function sentenceCase(value: string): string {
return value
.trim()
.split(' ')
.map((word, index) => {
if (ACRONYMS.has(word)) return word
if (index === 0) return word.charAt(0).toUpperCase() + word.slice(1)
return /^[A-Z][a-z]+$/.test(word) ? word.toLowerCase() : word
})
.join(' ')
}
function headingFor(entry: DocumentedCommand): string {
const description = entry.command.description()
return description
? sentenceCase(description.replace(/\s*\([^)]*\)\s*$/, ''))
: `sim ${entry.path.join(' ')}`
}
function orderedCommands(entries: DocumentedCommand[]): DocumentedCommand[] {
const rank = (entry: DocumentedCommand): number => {
const verb = entry.path.at(-1)
const index = VERB_ORDER.findIndex((candidate) => candidate === verb)
return index < 0 ? VERB_ORDER.length : index
}
return [...entries].sort(
(left, right) =>
rank(left) - rank(right) || compareStrings(left.path.join(' '), right.path.join(' '))
)
}
/** Reads command-specific help additions without emitting the root’s help epilogue. */
function additionalHelp(command: Command): string[] {
const chunks: string[] = []
const context = { error: false, command, write: (value: string) => chunks.push(value) }
const helpEvents = command as Command & EventEmitter
helpEvents.emit('afterHelp', context)
const text = chunks.join('').trim()
if (!text) return []
const [prose = '', examples] = text.split(/\nExamples:\s*\n/, 2)
const lines = prose
.split(/\n\s*\n/)
.flatMap((paragraph) => [escapeProse(paragraph.replace(/\s*\n\s*/g, ' ').trim()), ''])
if (examples) {
lines.push(
'**Examples**',
'',
'```bash',
...examples
.trim()
.split('\n')
.map((line) => line.trim().replace(/^\$ /, '')),
'```',
''
)
}
return lines
}
function relatedDocs(documentation: GroupDocumentation | undefined): string[] {
if (!documentation?.related?.length) return []
return [
'## Related docs',
'',
...documentation.related.map(([label, url]) => `- [${label}](${url})`),
'',
]
}
interface RenderOptions {
/** Markdown heading depth, so the master page can nest commands under groups. */
level?: number
/**
* Use the invocation as the heading instead of the description.
*
* Correct on the master page for two reasons: descriptions are only unique
* within a group, so "Delete folder" would collide four ways across one page;
* and a reader — human or agent — arriving at a page of every command is
* looking one up by name, not browsing by task.
*/
commandHeadings?: boolean
referenceLinks?: ReadonlyMap<string, string>
}
function renderCommand(entry: DocumentedCommand, options: RenderOptions = {}): string[] {
const { level = 2, commandHeadings = false, referenceLinks } = options
const aliases = entry.command.aliases()
const heading = commandHeadings ? `sim ${entry.path.join(' ')}` : headingFor(entry)
const description = entry.command.description()
const operation = operationOf(entry.command)
const spec = operation ? CLI_CONTRACT[operation] : undefined
const anchor = commandHeadings ? undefined : LEGACY_COMMAND_ANCHORS[entry.path.join(' ')]
const lines = [`${'#'.repeat(level)} ${escapeProse(heading)}${anchor ? ` [#${anchor}]` : ''}`, '']
if (commandHeadings && description) lines.push(escapeProse(sentenceCase(description)), '')
if (!commandHeadings) {
const qualifier = /\s*\(([^)]*)\)\s*$/.exec(description)?.[1]
if (qualifier)
lines.push(
escapeProse(asSentence(qualifier.charAt(0).toUpperCase() + qualifier.slice(1))),
''
)
}
if (spec?.confirm) lines.push(escapeProse(spec.confirm), '')
for (const note of COMMAND_NOTES[entry.path.join(' ')] ?? []) lines.push(escapeProse(note), '')
lines.push('```bash', usageLine(entry), '```')
if (aliases.length > 0) {
const spelled = aliases.map((alias) =>
code(`sim ${[...entry.path.slice(0, -1), alias].join(' ')}`)
)
lines.push('', `Also available as ${spelled.join(', ')}.`)
}
lines.push(
...renderArguments(entry),
...renderOptions(entry),
'',
...additionalHelp(entry.command)
)
const references = operation ? [operation] : (calledOperations(entry.command) ?? [])
const links = references.flatMap((name) => {
const apiOperation = V2_OPERATIONS[name]
const url =
referenceLinks?.get(name) ??
referenceLinks?.get(
`${apiOperation.method} ${apiOperation.path.replace(/\[([^\]]+)\]/g, '{$1}')}`
)
return url ? [`[${name}](${url})`] : []
})
if (links.length) lines.push(`API request and response schemas: ${links.join(', ')}.`, '')
return lines
}
function frontmatter(title: string, description: string, hasTables = true): string[] {
return [
'---',
`title: ${title}`,
`description: ${description}`,
'---',
'',
...(hasTables ? ["import { CommandTable } from '@/components/ui/command-table'"] : []),
'',
]
}
/**
* Fails when two commands on one page reduce to the same heading.
*
* Headings are descriptions now, and descriptions are not guaranteed unique the
* way command paths are. Two identical `## ` headings would collide on the same
* anchor, so one table-of-contents entry would scroll to the other command. The
* fix is a distinguishing `describe` in the CLI contract.
*/
function assertDistinctHeadings(page: string, entries: DocumentedCommand[]): void {
const byHeading = new Map<string, string[]>()
for (const entry of entries) {
const heading = headingFor(entry)
byHeading.set(heading, [...(byHeading.get(heading) ?? []), `sim ${entry.path.join(' ')}`])
}
const collisions = [...byHeading].filter(([, commands]) => commands.length > 1)
if (collisions.length === 0) return
for (const [heading, commands] of collisions) {
console.error(`${page}: "${heading}" is the heading for ${commands.join(' and ')}`)
}
console.error(
'\nTwo commands on a page share a heading, so they share an anchor.\n' +
'Give one a distinct `describe` in packages/sim-cli/src/contract/commands.ts.'
)
process.exit(1)
}
/**
* Every command on one page.
*
* A reference split across fourteen pages is fine to browse and bad to consult:
* an agent, or anyone using in-page search, has to guess which page holds a
* command before it can read it. This is the single fetch that answers any
* question about the surface — the same shape as Claude Code's own
You can’t perform that action at this time.