Repository navigation
Expand file tree
/
Copy pathprogram.ts
More file actions
217 lines (199 loc) · 8.57 KB
/
Copy pathprogram.ts
File metadata and controls
217 lines (199 loc) · 8.57 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
import { Command, Option } from 'commander'
import { updateCommand } from '#sim-cli/commands/update'
import { loginCommand, logoutCommand, profilesCommand, whoamiCommand } from './commands/auth'
import { configureCommand } from './commands/configure'
import { attachCredentialCommands } from './commands/credentials'
import { attachProtocolCommands } from './commands/protocol/index'
import { cliCommand } from './commands/search'
import { attachSecretCommands } from './commands/secrets'
import { telemetryCommand } from './commands/telemetry'
import { OUTPUT_FORMATS } from './config/index'
import {
assertNoReservedProgramFlags,
buildGeneratedCommands,
refuseHelpAfterUnknownCommand,
} from './runtime/build'
import { detectCodingAgent } from './telemetry/coding-agent'
import { announceUpdateIfAvailable } from './update/check'
import { cliVersion } from './version'
/** Root program description, shared by `--help` and the generated docs. */
export const PROGRAM_DESCRIPTION = 'Talk to the Sim API from your terminal'
export const HELP_EPILOGUE = `
Profiles work like the AWS CLI: settings live in ~/.sim/config, keys in
~/.sim/credentials (0600), or under SIM_CONFIG_DIR when it is set. Select one
with -P, --profile, or SIM_PROFILE.
Workflow, knowledge-base and workspace IDs are bare UUIDs. Table IDs carry a
tbl_ prefix and file IDs a wf_ one, so wf_ never names a workflow. An audit-log
or custom-tool ID can open with a dash, which reads as a flag; put -- in front
of it, as in sim audit-logs get -- -HlDcD1z76nK6R4crsUp0.
Examples:
$ sim cli search "cancel a workflow run" Find the command for a task
$ sim login Authorize the default profile
$ sim login --profile dev --endpoint http://localhost:3000
$ sim profile add acme --workspace 7e2d9c14-6b83-4a55-8f01-c4d3e9a76b28
$ sim workflows list
$ sim logs list --level error --limit 20
$ sim configure --set-output table Prefer tables over the JSON default
$ sim --output table tables get tbl_9f3c1a05d4b7426e8c2f0917ab35de64
$ sim knowledge search --query "refund policy" --kb 4c1b7f60-2d55-4a3e-9c18-70b6ea2f9d31
$ sim workflows export 3a9e21d8-5f47-4c0b-b2ea-91d7c6034ef8 > wf.json
$ sim workflows import --workflow @wf.json
$ sim knowledge export 4c1b7f60-2d55-4a3e-9c18-70b6ea2f9d31 -o ./kb.simkb.zip
$ sim knowledge import ./kb.simkb.zip --name "Docs (copy)"
$ sim whoami --profile dev
`
/**
* Printed above group-level help when a coding agent runs the CLI.
*
* Agents otherwise map the surface by walking `--help` down every group, which
* costs a call and a screenful of context per level. Leaf help is left alone:
* an agent reading it has already found its command.
*/
export const AGENT_DISCOVERY_NOTE = `=== AGENT COMMAND DISCOVERY ===
Do not explore commands by chaining nested --help calls. Instead run:
sim cli search "<describe the task you want to accomplish>"
It returns the 5 best-matching commands, each with a one-line summary. Pick the
best match rather than repeating similar searches, then run
\`<command> --help\` for its flags.
=== END AGENT COMMAND DISCOVERY ===
`
/**
* Executable but unpublished until launch, so kept out of `--help` and `sim cli` search. The
* Mothership command inventory still lists them, marked `unpublished`, because the worker routes
* to them only when Sim enables the feature for a turn.
*/
export const UNPUBLISHED_GROUPS: ReadonlySet<string> = new Set(['projects'])
/** The root's own value-taking options, which consume the token after them. */
const ROOT_VALUE_FLAGS: ReadonlySet<string> = new Set([
'-P',
'--profile',
'--endpoint',
'-w',
'--workspace',
'--output',
])
/**
* Whether a subcommand was named before the version flag was typed.
*
* A bare `--version` carries no value to refuse, so `sim workflows rollback
* wf_1 --version` still printed the CLI version and exited `0`. What separates
* it from `sim --version` is not the flag but its position: the first bare word
* in argv is the command the caller meant to run, and a command that reached
* this listener does not declare `--version` itself.
*/
function namesASubcommandFirst(rawArgs: readonly string[]): boolean {
const tokens = rawArgs.slice(2)
for (let index = 0; index < tokens.length; index += 1) {
const token = tokens[index]
if (token === '--version' || token === '-V') return false
if (ROOT_VALUE_FLAGS.has(token)) {
index += 1
continue
}
if (token.startsWith('-')) continue
return true
}
return false
}
/**
* The root version flag, declared to accept the value it must refuse.
*
* Commander matches the root's own options anywhere in argv, so a plain
* `-V, --version` was matched inside `sim workflows rollback wf_1 --version 1`
* before the leaf ever ran: the version printed, the process exited `0`, and no
* request was made — a rollback that silently did nothing. Taking an optional
* value here is what makes that case distinguishable, and the listener runs
* before the one `version()` installs, so a supplied value fails loudly instead
* of printing a version nobody asked for. The bare form after a subcommand is
* refused on position for the same reason. `sim --version` on its own is
* unchanged.
*
* The placeholder is `[none]` rather than a value name: the option declares an
* optional argument only so that a supplied one is visible here, and `--help`
* has to say that no value is accepted rather than name one.
*/
function addVersionOption(program: Command): void {
program.on('option:version', (value?: string | null) => {
if (value === null || value === undefined) {
// `rawArgs` is commander's own record of the argv it was handed; it is
// populated before any listener fires but is absent from the typings.
const { rawArgs } = program as Command & { rawArgs?: string[] }
if (!namesASubcommandFirst(rawArgs ?? [])) return
program.error(
'error: --version reports the Sim CLI version and is not a command flag. A command that acts on a deployment version reads it from --to-version.'
)
}
program.error(
'error: --version reports the Sim CLI version and takes no value. A command that acts on a deployment version reads it from --to-version.'
)
})
program.version(
cliVersion(),
'-V, --version [none]',
'output the version number (takes no value)'
)
}
/**
* Assemble the complete command tree.
*
* Kept separate from the entrypoint so the documentation generator can walk the
* same tree the terminal parses. A generator that rebuilt the surface from the
* contract instead would be a second implementation of `buildGeneratedCommands`,
* free to drift from the one users actually run.
*
* `version` is optional because the generator reads the package metadata itself
* and the emitted pages must not carry a version that goes stale on every
* release.
*/
export function buildProgram(
options: {
version?: boolean
helpText?: string
program?: Command
env?: NodeJS.ProcessEnv
hostCommands?: boolean
} = {}
): Command {
const env = options.env ?? process.env
const program = options.program ?? new Command()
program.name('sim').description(PROGRAM_DESCRIPTION)
if (options.version !== false) addVersionOption(program)
program
.option('-P, --profile <name>', 'Profile to use (env: SIM_PROFILE)')
.option('--endpoint <url>', 'Sim deployment to talk to (env: SIM_ENDPOINT)')
.option('-w, --workspace <id>', 'Workspace to target (env: SIM_WORKSPACE)')
.addOption(
new Option('--output <format>', 'Output format for this command').choices([...OUTPUT_FORMATS])
)
if (options.hostCommands !== false) {
for (const command of [
loginCommand,
logoutCommand,
whoamiCommand,
profilesCommand,
configureCommand,
])
program.addCommand(command())
const update = updateCommand()
program.addCommand(update)
program.addCommand(telemetryCommand())
program.hook('preAction', async (_program, command) => {
if (command === update) return
await announceUpdateIfAvailable()
})
}
program.addCommand(cliCommand())
for (const command of buildGeneratedCommands()) {
program.addCommand(command, { hidden: UNPUBLISHED_GROUPS.has(command.name()) })
}
attachCredentialCommands(program)
attachProtocolCommands(program)
attachSecretCommands(program)
program.addHelpText('after', options.helpText ?? HELP_EPILOGUE)
program.addHelpText('beforeAll', ({ command }) =>
detectCodingAgent(env) !== undefined && command.commands.length > 0 ? AGENT_DISCOVERY_NOTE : ''
)
refuseHelpAfterUnknownCommand(program)
assertNoReservedProgramFlags(program)
return program
}