mirror of
https://github.com/simstudioai/sim.git
synced 2026-11-20 12:08:01 +08:00
* feat(api): attribute polled run failures, deployed input schema, paused-run list, and applied run limits
- GET /v2/workflows/{id}/runs/{runId} reads the failing block back from the run's
recorded trace, withheld when the viewer's permission group hides execution data
- GET /v2/workflows/{id} adds inputSchema for the active deployment's API run input
- GET /v2/workflows/runs/paused lists a workspace's runs waiting on human input,
projecting pause points exactly as the run detail does
- Execute responses report executionTimeoutSeconds; GET /v2/billing/status adds plan limits
* fix(api): respect the paused-run page cap in the CLI and keep waiting pause points under the cap
- CLI generator carries a numeric field's contract maximum; the pager never requests
a page above it while still paging to the caller's total --limit
- Pause point cap keeps points not yet resumed before resumed history, so a run that
paused again is never listed without its waiting point (run detail and paused list)
* improvement(api): reuse FailedTraceBlock and sort pause points once when capping
* fix(api): custom-block trace boundary, legacy pause point arrays, and list point selection
- A custom block is an opaque trace boundary for failing-block attribution
- The paused-run list reads object and legacy array pause_points
- The list selects waiting human points before the per-run cap, reads points in
waves that stop once the page budget is spent, and shares one waiting predicate
- Resume response schemas omit executionTimeoutSeconds
- Drop a non-null assertion from the CLI page cap test
* fix(api): attribute concurrent failures to the stored error's block and never fail a workflow read on its deployment
- Failing-block attribution prefers the span the stored error names, else the
failure that ended first, else none; the block error prefix has one owner
- The workflow read degrades inputSchema to null when the deployment cannot be
read or its schema has an unexpected shape
- Integration cases for time-only, archived, and cross-workspace exclusion
* fix(api): consistent trace walk, block-named error attribution, required applied timeout, and ungated input schema
- Failing-block attribution walks spans as hasUnhandledError does, through
successful blocks, with one shared successful-boundary rule
- An error message headed by the failing block's name is attributed to it even
when the name reads as a run-level failure
- executionTimeoutSeconds is required (nullable) on Execute workflow responses
- The workflow read takes inputSchema from the active version row, not isDeployed
- Pause cap wording: unresolved points are kept in preference, listed earliest first
- Regenerate the CLI API the previous contract wording left stale
* fix(api): parse resume responses with the resume schema in e2e scripts and regenerate the CLI API on staging
- Stop-after and pinned-execute e2e scripts parse resume responses with
v2ResumeWorkflowDataSchema, which omits executionTimeoutSeconds
- Regenerate the CLI API against the merged staging contracts
* fix(api): parse the stop-after e2e resume helper's response with the resume schema
1403 lines
51 KiB
TypeScript
1403 lines
51 KiB
TypeScript
#!/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']],
|
||
},
|
||
schedules: {
|
||
description: 'List the schedules deployed workflows run across a workspace.',
|
||
notes: [
|
||
'A schedule’s timing comes from its schedule block. Edit the block with `sim workflows operations apply`, then deploy; pause or resume one with `sim workflows triggers update`.',
|
||
],
|
||
},
|
||
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'],
|
||
['Build and run workflows with the API', '/api-reference/build-and-run-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', prefixes: ['search'] },
|
||
{ title: 'Export and import', prefixes: ['export', 'import', 'imports'] },
|
||
{ 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: 'Search source permissions', prefixes: ['search sources permissions'] },
|
||
{ 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', 'outline', 'operations', 'variables'] },
|
||
{
|
||
title: 'Deployments and versions',
|
||
prefixes: [
|
||
'deploy',
|
||
'deployment',
|
||
'triggers',
|
||
'versions',
|
||
'activate',
|
||
'revert',
|
||
'rollback',
|
||
'undeploy',
|
||
],
|
||
},
|
||
{
|
||
title: 'Run and inspect',
|
||
prefixes: [
|
||
'run',
|
||
'runs list',
|
||
'runs paused',
|
||
'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', 'update', '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',
|
||
}
|
||
|
||
/**
|
||
* Reference-page anchors a renamed command keeps, so links to the spelling it
|
||
* shipped under still land on it. `workspaces members` became a group whose
|
||
* default subcommand is `list`.
|
||
*/
|
||
const LEGACY_REFERENCE_ANCHORS: Record<string, string> = {
|
||
'workspaces members list': 'sim-workspaces-members',
|
||
}
|
||
|
||
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 ? LEGACY_REFERENCE_ANCHORS : 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
|
||
* `cli-reference`, and the page `/cli/reference.mdx` serves as raw Markdown.
|
||
*/
|
||
function renderReferencePage(
|
||
program: Command,
|
||
groups: Command[],
|
||
globals: DocumentedCommand[],
|
||
referenceLinks: ReadonlyMap<string, string>
|
||
): string {
|
||
const lines = [
|
||
...frontmatter('Complete reference', 'Every sim command, argument, and flag on a single page'),
|
||
'Every command on one page, generated from the CLI itself. Start at the',
|
||
'[overview](/cli/commands) to browse; this page is for searching and for tools.',
|
||
'',
|
||
'Append `.mdx` to an authored guide or CLI reference page for its raw Markdown —',
|
||
'[`/cli/reference.mdx`](/cli/reference.mdx) is this page as plain text. The docs',
|
||
'are also published as [`/llms.txt`](/llms.txt) and',
|
||
'[`/llms-full.txt`](/llms-full.txt).',
|
||
'',
|
||
'## Global options',
|
||
'',
|
||
'Place these options before or after the command. Each command uses the settings',
|
||
'relevant to its action. Telemetry commands always print text; workflow export',
|
||
'prints a portable JSON document, or YAML when selected.',
|
||
// Deliberately unwrapped, like the same table on the overview page:
|
||
// `CommandTable` sizes its second column for the `Required` cell of the
|
||
// three-column tables, which on this two-column one would crush the
|
||
// description into 5.5rem.
|
||
'',
|
||
'| Option | Description |',
|
||
'| --- | --- |',
|
||
...documentedOptions(program).map(
|
||
(option) => `| ${code(option.flags)} | ${describeOption(option)} |`
|
||
),
|
||
'',
|
||
]
|
||
|
||
lines.push(
|
||
'Use `--help` to inspect a command. `sim --version` prints the CLI version,',
|
||
'takes no value, and exits without running a command. Deployment-version commands',
|
||
'use their documented arguments or `--to-version`.',
|
||
'',
|
||
'API schema links describe HTTP payloads. See [CLI output formats](/cli/output)',
|
||
'for resource unwrapping, pagination envelopes, and display formats.',
|
||
''
|
||
)
|
||
|
||
for (const leaf of globals)
|
||
lines.push(...renderCommand(leaf, { commandHeadings: true, referenceLinks }))
|
||
|
||
for (const group of groups) {
|
||
lines.push(`## sim ${group.name()}`, '')
|
||
const documentation = GROUP_DOCUMENTATION[group.name()]
|
||
if (documentation) lines.push(escapeProse(documentation.description), '')
|
||
for (const note of documentation?.notes ?? []) lines.push(escapeProse(note), '')
|
||
const aliases = group.aliases()
|
||
if (aliases.length > 0) {
|
||
lines.push(`Also spelled ${aliases.map((alias) => `\`sim ${alias}\``).join(', ')}.`, '')
|
||
}
|
||
for (const leaf of collectLeaves(group, [group.name()])) {
|
||
lines.push(...renderCommand(leaf, { level: 3, commandHeadings: true, referenceLinks }))
|
||
}
|
||
}
|
||
|
||
return `${lines.join('\n').trimEnd()}\n`
|
||
}
|
||
|
||
function renderGroupPage(group: Command, referenceLinks: ReadonlyMap<string, string>): string {
|
||
const name = group.name()
|
||
const leaves = collectLeaves(group, [name])
|
||
const aliases = group.aliases()
|
||
const documentation = GROUP_DOCUMENTATION[name]
|
||
const description = documentation?.description ?? sentenceCase(group.description())
|
||
assertDistinctHeadings(`${name}.mdx`, leaves)
|
||
const hasTables = leaves.some(
|
||
(entry) =>
|
||
entry.command.registeredArguments.length > 0 || documentedOptions(entry.command).length > 0
|
||
)
|
||
const lines = [...frontmatter(titleFor(name), description, hasTables), description, '']
|
||
for (const note of documentation?.notes ?? []) lines.push(escapeProse(note), '')
|
||
if (aliases.length > 0) {
|
||
lines.push(
|
||
`\`sim ${name}\` is also spelled ${aliases.map((alias) => `\`sim ${alias}\``).join(', ')}.`,
|
||
''
|
||
)
|
||
}
|
||
lines.push('These commands accept the [global options](/cli/commands#global-options).', '')
|
||
const sections = GROUP_SECTIONS[name]
|
||
if (sections) {
|
||
const remaining = new Set(leaves)
|
||
for (const section of sections) {
|
||
const entries: DocumentedCommand[] = []
|
||
for (const prefix of section.prefixes) {
|
||
const matches = [...remaining].filter((entry) => {
|
||
const relative = entry.path.slice(1).join(' ')
|
||
return relative === prefix || relative.startsWith(`${prefix} `)
|
||
})
|
||
for (const entry of orderedCommands(matches)) {
|
||
entries.push(entry)
|
||
remaining.delete(entry)
|
||
}
|
||
}
|
||
if (!entries.length) continue
|
||
lines.push(`## ${section.title}`, '')
|
||
for (const entry of entries) lines.push(...renderCommand(entry, { level: 3, referenceLinks }))
|
||
}
|
||
if (remaining.size) {
|
||
lines.push('## Other commands', '')
|
||
for (const entry of orderedCommands([...remaining]))
|
||
lines.push(...renderCommand(entry, { level: 3, referenceLinks }))
|
||
}
|
||
} else {
|
||
for (const entry of orderedCommands(leaves))
|
||
lines.push(...renderCommand(entry, { referenceLinks }))
|
||
}
|
||
lines.push(...relatedDocs(documentation))
|
||
return `${lines.join('\n').trimEnd()}\n`
|
||
}
|
||
|
||
function renderIndexPage(
|
||
program: Command,
|
||
groups: Command[],
|
||
globals: DocumentedCommand[],
|
||
referenceLinks: ReadonlyMap<string, string>
|
||
): string {
|
||
const lines = [
|
||
...frontmatter(
|
||
'CLI commands',
|
||
'Find command groups, global options, and login, configuration, and Chat commands.'
|
||
),
|
||
'Resource commands use this shape:',
|
||
'',
|
||
'```bash',
|
||
'sim <resource> [sub-resource] <verb> [arguments] [options]',
|
||
'```',
|
||
'',
|
||
'Some resource groups also accept a singular alias: `sim workflow get` and',
|
||
'`sim workflows get` are the same command. `knowledge` also answers to `kb`.',
|
||
'Each group’s reference lists its supported aliases. Login, configuration, and',
|
||
'Chat commands appear below. To find a command for a task, use',
|
||
'`sim cli search "describe your task"`.',
|
||
'',
|
||
'## Global options',
|
||
'',
|
||
'Place these options before or after the command. Each command uses the settings',
|
||
'relevant to its action. Telemetry commands always print text; workflow export',
|
||
'prints a portable JSON document, or YAML when selected.',
|
||
'',
|
||
'| Option | Description |',
|
||
'| --- | --- |',
|
||
...documentedOptions(program).map(
|
||
(option) => `| ${code(option.flags)} | ${describeOption(option)} |`
|
||
),
|
||
'',
|
||
'Use `--help` to inspect a command. Run `sim --version` to print the CLI version;',
|
||
'`--version` takes no value and exits without running a command. Deployment-version',
|
||
'commands use their documented arguments or `--to-version` instead.',
|
||
'',
|
||
'See [output formats](/cli/output) for the JSON default and display formats.',
|
||
'',
|
||
'## Command groups',
|
||
'',
|
||
'| Group | Description |',
|
||
'| --- | --- |',
|
||
...groups.map(
|
||
(group) =>
|
||
`| [${code(`sim ${group.name()}`)}](/cli/${group.name()}) | ${escapeCell(GROUP_DOCUMENTATION[group.name()]?.description ?? sentenceCase(group.description())) || '—'} |`
|
||
),
|
||
'',
|
||
]
|
||
|
||
for (const leaf of globals) lines.push(...renderCommand(leaf, { referenceLinks }))
|
||
|
||
lines.push(
|
||
'## Related docs',
|
||
'',
|
||
'- [Complete command reference](/cli/reference)',
|
||
'- [Authentication](/cli/authentication)',
|
||
'- [Scripting](/cli/scripting)',
|
||
''
|
||
)
|
||
return `${lines.join('\n').trimEnd()}\n`
|
||
}
|
||
|
||
/**
|
||
* The section's sidebar.
|
||
*
|
||
* Generated because the command-group entries are, and a hand-maintained copy
|
||
* would drift the moment a group is added. The hand-written guides stay in
|
||
* `GUIDE_PAGES` so adding one is an edit here rather than a change to how the
|
||
* pages are produced.
|
||
*/
|
||
function renderMeta(groups: Command[]): string {
|
||
return `${JSON.stringify(
|
||
{
|
||
title: 'CLI',
|
||
root: true,
|
||
pages: [
|
||
'---Sim CLI---',
|
||
...GUIDE_PAGES,
|
||
'---Commands---',
|
||
OVERVIEW_PAGE,
|
||
...groups.map((group) => group.name()),
|
||
REFERENCE_PAGE,
|
||
],
|
||
},
|
||
null,
|
||
2
|
||
)}\n`
|
||
}
|
||
|
||
/**
|
||
* Fails on two commands sharing one invocation path.
|
||
*
|
||
* Commander resolves a duplicate name to the first registered match, so the
|
||
* loser is unreachable from the terminal while still appearing in `--help` —
|
||
* which is how `knowledge documents update` shadowed the single-document
|
||
* update. Left alone the generator would emit two identical headings and
|
||
* document a command nobody can run, so the collision fails the build here
|
||
* instead: the fix is a `command` entry in the CLI contract.
|
||
*/
|
||
function assertNoDuplicatePaths(leaves: DocumentedCommand[]): void {
|
||
const seen = new Set<string>()
|
||
const duplicates = new Set<string>()
|
||
for (const leaf of leaves) {
|
||
const invocation = leaf.path.join(' ')
|
||
if (seen.has(invocation)) duplicates.add(invocation)
|
||
seen.add(invocation)
|
||
}
|
||
if (duplicates.size === 0) return
|
||
for (const invocation of duplicates) {
|
||
console.error(`duplicate command path: sim ${invocation}`)
|
||
}
|
||
console.error(
|
||
'\nTwo operations derive to the same command, so one is unreachable.\n' +
|
||
'Give one of them a `command` in packages/sim-cli/src/contract/commands.ts.'
|
||
)
|
||
process.exit(1)
|
||
}
|
||
|
||
/**
|
||
* Fails on a request field that documents itself nowhere.
|
||
*
|
||
* Without a `.describe()` on the route contract, the CLI can only fall back to
|
||
* restating the flag name — `--sort-by Set sort by` — and that fallback lands
|
||
* verbatim in `--help` and in these pages. It reads like documentation while
|
||
* telling the reader nothing, which is worse than an obvious hole.
|
||
*
|
||
* The contract is the right place to fix it because the same prose feeds the
|
||
* OpenAPI specs and the API reference, so one `.describe()` documents the
|
||
* field everywhere it appears.
|
||
*
|
||
* `workspaceId` and `cursor` are exempt: neither is ever a flag — the profile
|
||
* supplies one and pagination consumes the other.
|
||
*/
|
||
function assertEveryFieldDocumented(): void {
|
||
const undocumented: string[] = []
|
||
|
||
for (const [operation, spec] of Object.entries(V2_OPERATIONS)) {
|
||
for (const slot of ['query', 'body'] as const) {
|
||
const fields = (spec as Record<string, unknown>)[slot]
|
||
if (!fields || typeof fields !== 'object') continue
|
||
for (const [field, descriptor] of Object.entries(fields)) {
|
||
if (field === 'workspaceId' || field === 'cursor') continue
|
||
const described = (descriptor as { describe?: unknown }).describe
|
||
if (typeof described !== 'string' || !described.trim()) {
|
||
undocumented.push(`${operation}.${slot}.${field}`)
|
||
}
|
||
}
|
||
}
|
||
}
|
||
|
||
if (undocumented.length === 0) return
|
||
for (const field of undocumented) console.error(`undocumented request field: ${field}`)
|
||
console.error(
|
||
`\n${undocumented.length} field(s) would render as "Set <name>" in --help and in the docs.\n` +
|
||
'Add a `.describe()` in apps/sim/lib/api/contracts/v2, then run:\n' +
|
||
' bun run generate:cli-api && bun run generate:cli-docs'
|
||
)
|
||
process.exit(1)
|
||
}
|
||
|
||
/** The sidebar names every guide, so a renamed or deleted one must not fail silently. */
|
||
function assertGuidesExist(): void {
|
||
const missing = GUIDE_PAGES.filter((page) => !fs.existsSync(path.join(OUTPUT_DIR, `${page}.mdx`)))
|
||
if (missing.length === 0) return
|
||
for (const page of missing) console.error(`missing hand-written guide: cli/${page}.mdx`)
|
||
console.error('\nCreate it, or drop it from GUIDE_PAGES in scripts/generate-cli-docs.ts.')
|
||
process.exit(1)
|
||
}
|
||
|
||
function build(): Map<string, string> {
|
||
assertEveryFieldDocumented()
|
||
assertGuidesExist()
|
||
|
||
const program = buildProgram({ version: false })
|
||
const top = subcommands(program)
|
||
const groups = top.filter((command) => subcommands(command).length > 0)
|
||
const globals = top
|
||
.filter((command) => subcommands(command).length === 0)
|
||
.map((command) => ({ path: [command.name()], command }))
|
||
|
||
assertNoDuplicatePaths([
|
||
...groups.flatMap((group) => collectLeaves(group, [group.name()])),
|
||
...globals,
|
||
])
|
||
|
||
const referenceLinks = apiReferenceLinks()
|
||
const files = new Map<string, string>()
|
||
files.set('meta.json', renderMeta(groups))
|
||
files.set(`${OVERVIEW_PAGE}.mdx`, renderIndexPage(program, groups, globals, referenceLinks))
|
||
files.set(`${REFERENCE_PAGE}.mdx`, renderReferencePage(program, groups, globals, referenceLinks))
|
||
for (const group of groups)
|
||
files.set(`${group.name()}.mdx`, renderGroupPage(group, referenceLinks))
|
||
return files
|
||
}
|
||
|
||
/** Generated pages already on disk. Hand-written guides are not the sweep's to remove. */
|
||
function currentFiles(): Map<string, string> {
|
||
if (!fs.existsSync(OUTPUT_DIR)) return new Map()
|
||
const guides = new Set<string>(GUIDE_PAGES.map((page) => `${page}.mdx`))
|
||
return new Map(
|
||
fs
|
||
.readdirSync(OUTPUT_DIR, { withFileTypes: true })
|
||
.filter((entry) => entry.isFile() && !guides.has(entry.name))
|
||
.map(
|
||
(entry) => [entry.name, fs.readFileSync(path.join(OUTPUT_DIR, entry.name), 'utf8')] as const
|
||
)
|
||
)
|
||
}
|
||
|
||
function main(): void {
|
||
const check = process.argv.includes('--check')
|
||
const expected = build()
|
||
const actual = currentFiles()
|
||
|
||
const stale = [...actual.keys()].filter((name) => !expected.has(name))
|
||
const changed = [...expected.entries()].filter(([name, content]) => actual.get(name) !== content)
|
||
|
||
if (check) {
|
||
if (stale.length === 0 && changed.length === 0) {
|
||
console.log(`CLI docs are up to date (${expected.size} files).`)
|
||
return
|
||
}
|
||
for (const name of changed)
|
||
console.error(`stale: ${path.relative(ROOT, path.join(OUTPUT_DIR, name[0]))}`)
|
||
for (const name of stale)
|
||
console.error(`orphaned: ${path.relative(ROOT, path.join(OUTPUT_DIR, name))}`)
|
||
console.error('\nRun `bun run generate:cli-docs` and commit the result.')
|
||
process.exit(1)
|
||
}
|
||
|
||
fs.mkdirSync(OUTPUT_DIR, { recursive: true })
|
||
for (const name of stale) fs.rmSync(path.join(OUTPUT_DIR, name))
|
||
for (const [name, content] of expected) {
|
||
fs.writeFileSync(path.join(OUTPUT_DIR, name), content)
|
||
}
|
||
console.log(
|
||
`Wrote ${expected.size} files to ${path.relative(ROOT, OUTPUT_DIR)}` +
|
||
(stale.length > 0 ? `, removed ${stale.length} orphaned` : '')
|
||
)
|
||
}
|
||
|
||
// Guarded so the pure helpers above can be imported by tests without the
|
||
// generator rewriting the docs as a side effect of the import.
|
||
if (import.meta.main) main()
|