@roarkanalytics/cli 0.61.1 → 0.68.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (68) hide show
  1. package/CHANGELOG.md +56 -0
  2. package/README.md +45 -0
  3. package/commands.js +575 -0
  4. package/completions.js +4 -4
  5. package/man/roark-calendar-connection-check.1 +93 -0
  6. package/man/roark-calendar-connection-create.1 +102 -0
  7. package/man/roark-calendar-connection-delete.1 +93 -0
  8. package/man/roark-calendar-connection-get.1 +93 -0
  9. package/man/roark-calendar-connection-list.1 +93 -0
  10. package/man/roark-calendar-connection-target-get.1 +96 -0
  11. package/man/roark-calendar-connection-target-list.1 +93 -0
  12. package/man/roark-calendar-connection-update.1 +103 -0
  13. package/man/roark-metric-definition-update.1 +3 -0
  14. package/man/roark-metric-variant-update.1 +3 -0
  15. package/man/roark-tool-create.1 +123 -0
  16. package/man/roark-tool-delete.1 +93 -0
  17. package/man/roark-tool-get.1 +93 -0
  18. package/man/roark-tool-list.1 +96 -0
  19. package/man/roark-tool-update.1 +127 -0
  20. package/man/roark.1 +39 -0
  21. package/npm-shrinkwrap.json +6 -6
  22. package/package.json +15 -2
  23. package/runtime/commands/config-as-code.js +5 -23
  24. package/runtime/commands/get-started.d.ts +34 -0
  25. package/runtime/commands/get-started.js +350 -0
  26. package/runtime/config-bundle.d.ts +10 -0
  27. package/runtime/config-bundle.js +14 -3
  28. package/runtime/config-changes.d.ts +15 -0
  29. package/runtime/config-changes.js +32 -0
  30. package/runtime/get-started/account.d.ts +18 -0
  31. package/runtime/get-started/account.js +35 -0
  32. package/runtime/get-started/agent.d.ts +17 -0
  33. package/runtime/get-started/agent.js +116 -0
  34. package/runtime/get-started/answers.d.ts +15 -0
  35. package/runtime/get-started/answers.js +42 -0
  36. package/runtime/get-started/apply.d.ts +35 -0
  37. package/runtime/get-started/apply.js +54 -0
  38. package/runtime/get-started/existing.d.ts +15 -0
  39. package/runtime/get-started/existing.js +47 -0
  40. package/runtime/get-started/ladder.d.ts +37 -0
  41. package/runtime/get-started/ladder.js +69 -0
  42. package/runtime/get-started/module.d.ts +20 -0
  43. package/runtime/get-started/module.js +159 -0
  44. package/runtime/get-started/placeholder.d.ts +9 -0
  45. package/runtime/get-started/placeholder.js +36 -0
  46. package/runtime/get-started/prompt.d.ts +32 -0
  47. package/runtime/get-started/prompt.js +132 -0
  48. package/runtime/get-started/resources.d.ts +106 -0
  49. package/runtime/get-started/resources.js +184 -0
  50. package/runtime/get-started/run.d.ts +42 -0
  51. package/runtime/get-started/run.js +101 -0
  52. package/runtime/get-started/scaffold-only.d.ts +19 -0
  53. package/runtime/get-started/scaffold-only.js +43 -0
  54. package/runtime/get-started/scaffold.d.ts +15 -0
  55. package/runtime/get-started/scaffold.js +35 -0
  56. package/runtime/get-started/starter-metrics.d.ts +33 -0
  57. package/runtime/get-started/starter-metrics.js +104 -0
  58. package/runtime/get-started/steps.d.ts +33 -0
  59. package/runtime/get-started/steps.js +112 -0
  60. package/runtime/get-started/target.d.ts +47 -0
  61. package/runtime/get-started/target.js +81 -0
  62. package/runtime/get-started/types.d.ts +18 -0
  63. package/runtime/get-started/types.js +8 -0
  64. package/runtime/get-started/watch.d.ts +57 -0
  65. package/runtime/get-started/watch.js +103 -0
  66. package/runtime/program.js +5 -0
  67. package/version.d.ts +1 -1
  68. package/version.js +1 -1
@@ -1,15 +1,15 @@
1
1
  {
2
2
  "name": "@roarkanalytics/cli",
3
- "version": "0.61.1",
3
+ "version": "0.68.0",
4
4
  "lockfileVersion": 3,
5
5
  "requires": true,
6
6
  "packages": {
7
7
  "": {
8
8
  "name": "@roarkanalytics/cli",
9
- "version": "0.61.1",
9
+ "version": "0.68.0",
10
10
  "license": "Apache-2.0",
11
11
  "dependencies": {
12
- "@roarkanalytics/sdk": "^6.2.0",
12
+ "@roarkanalytics/sdk": "^7.0.0",
13
13
  "commander": "^14.0.3",
14
14
  "jiti": "^2.4.2",
15
15
  "yaml": "^2.9.0"
@@ -22,9 +22,9 @@
22
22
  }
23
23
  },
24
24
  "node_modules/@roarkanalytics/sdk": {
25
- "version": "6.2.0",
26
- "resolved": "https://registry.npmjs.org/@roarkanalytics/sdk/-/sdk-6.2.0.tgz",
27
- "integrity": "sha512-zPoo0o2f4ruygNG940nb8WfI5504ZnN9uHsyZLxNhNtlfXJtAeIbMgDihB2qzdCWeAsZKun6cQyKk9C503H/gw==",
25
+ "version": "7.0.0",
26
+ "resolved": "https://registry.npmjs.org/@roarkanalytics/sdk/-/sdk-7.0.0.tgz",
27
+ "integrity": "sha512-/sTFJcJPj426aSvJZQd5+fk04d4V0ugjOyEVO95PvWaoTrIJffor9Y+yYyNTXlWvogi/iVaXv/w2oDUa4jtVeA==",
28
28
  "license": "Apache-2.0"
29
29
  },
30
30
  "node_modules/commander": {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@roarkanalytics/cli",
3
- "version": "0.61.1",
3
+ "version": "0.68.0",
4
4
  "description": "The official command line interface for the Roark API",
5
5
  "author": "Roark <james@roark.ai>",
6
6
  "type": "commonjs",
@@ -29,7 +29,7 @@
29
29
  "fix": "eslint --fix . && prettier --write ."
30
30
  },
31
31
  "dependencies": {
32
- "@roarkanalytics/sdk": "^6.2.0",
32
+ "@roarkanalytics/sdk": "^7.0.0",
33
33
  "commander": "^14.0.3",
34
34
  "jiti": "^2.4.2",
35
35
  "yaml": "^2.9.0"
@@ -78,6 +78,14 @@
78
78
  "./man/roark-benchmark-target-get.1",
79
79
  "./man/roark-benchmark-target-history-list.1",
80
80
  "./man/roark-benchmark-target-score-sample-list.1",
81
+ "./man/roark-calendar-connection-check.1",
82
+ "./man/roark-calendar-connection-create.1",
83
+ "./man/roark-calendar-connection-delete.1",
84
+ "./man/roark-calendar-connection-get.1",
85
+ "./man/roark-calendar-connection-list.1",
86
+ "./man/roark-calendar-connection-target-get.1",
87
+ "./man/roark-calendar-connection-target-list.1",
88
+ "./man/roark-calendar-connection-update.1",
81
89
  "./man/roark-call-batch-delete.1",
82
90
  "./man/roark-call-cost-get.1",
83
91
  "./man/roark-call-create.1",
@@ -195,6 +203,11 @@
195
203
  "./man/roark-simulation-tool-fixture-delete.1",
196
204
  "./man/roark-simulation-tool-fixture-list.1",
197
205
  "./man/roark-simulation-tool-fixture-update.1",
206
+ "./man/roark-tool-create.1",
207
+ "./man/roark-tool-delete.1",
208
+ "./man/roark-tool-get.1",
209
+ "./man/roark-tool-list.1",
210
+ "./man/roark-tool-update.1",
198
211
  "./man/roark-usage-get.1",
199
212
  "./man/roark-webhook-create.1",
200
213
  "./man/roark-webhook-delete.1",
@@ -23,26 +23,8 @@ const errors_1 = require("../errors");
23
23
  const input_1 = require("../input");
24
24
  const output_1 = require("../output");
25
25
  const config_bundle_1 = require("../config-bundle");
26
+ const config_changes_1 = require("../config-changes");
26
27
  const config_module_1 = require("../config-module");
27
- const OP_MARK = { create: '+', update: '~', delete: '-', noop: ' ' };
28
- /** One-line-per-change summary for a terminal; `apply` results also carry a status. */
29
- const formatChanges = (data) => {
30
- const lines = data.changes.map((change) => {
31
- const mark = OP_MARK[String(change['op'])] ?? '?';
32
- const status = change['status'] ? ` (${String(change['status'])})` : '';
33
- const error = change['error'] ? ` ${String(change['error'])}` : '';
34
- return ` ${mark} ${String(change['configKey'])}${status}${error}`;
35
- });
36
- const s = data.summary;
37
- const tally = [
38
- `${s['create'] ?? 0} to create`,
39
- `${s['update'] ?? 0} to update`,
40
- `${s['delete'] ?? 0} to delete`,
41
- ...(s['failed'] === undefined ? [] : [`${s['failed']} failed`]),
42
- ].join(', ');
43
- return [...lines, '', tally].join('\n');
44
- };
45
- const changeCount = (summary) => (summary['create'] ?? 0) + (summary['update'] ?? 0) + (summary['delete'] ?? 0);
46
28
  /**
47
29
  * Resolve the bundle from a `path`, `--data`/stdin, or an auto-detected config file:
48
30
  * - a directory → build it from YAML
@@ -120,7 +102,7 @@ const registerConfigAsCodeCommands = (root, binaryName, clientFor, resolveOutput
120
102
  const output = resolveOutput(options);
121
103
  (0, output_1.write)(output.format === 'json' || options['json'] === true ?
122
104
  (0, output_1.render)(result.data, output)
123
- : formatChanges(result.data));
105
+ : (0, config_changes_1.formatChanges)(result.data));
124
106
  });
125
107
  withCommonOptions(config.command('apply [path]'))
126
108
  .description('Reconcile the project to a config directory, .ts config file, or bundle. Previews and confirms first.')
@@ -139,13 +121,13 @@ const registerConfigAsCodeCommands = (root, binaryName, clientFor, resolveOutput
139
121
  const json = output.format === 'json' || options['json'] === true;
140
122
  // Preview then confirm, so a prune-driven delete is never a surprise.
141
123
  const preview = (await client.config.diff(bundle));
142
- const pending = changeCount(preview.data.summary);
124
+ const pending = (0, config_changes_1.changeCount)(preview.data.summary);
143
125
  if (pending === 0) {
144
126
  (0, output_1.write)('No changes; project already matches the config.', process.stderr);
145
127
  return;
146
128
  }
147
129
  if (!json)
148
- (0, output_1.write)(formatChanges(preview.data), process.stderr);
130
+ (0, output_1.write)((0, config_changes_1.formatChanges)(preview.data), process.stderr);
149
131
  await (0, confirm_1.confirm)(`Apply ${pending} change(s)?`, {
150
132
  assumeYes: options['yes'] === true,
151
133
  noInput: options['input'] === false,
@@ -153,7 +135,7 @@ const registerConfigAsCodeCommands = (root, binaryName, clientFor, resolveOutput
153
135
  const result = await client.config.apply(bundle);
154
136
  (0, output_1.write)(json ?
155
137
  (0, output_1.render)(result.data, output)
156
- : formatChanges(result.data));
138
+ : (0, config_changes_1.formatChanges)(result.data));
157
139
  });
158
140
  config.addHelpText('after', [
159
141
  '',
@@ -0,0 +1,34 @@
1
+ /**
2
+ * `roark get-started` - the guided first run.
3
+ *
4
+ * Seven steps from an installed CLI to a graded simulation: who you are, the agent, the caller,
5
+ * the scenario, the metrics, the saved plan, the run. Each step asks the fewest questions it can,
6
+ * echoes the command it is shorthand for, and writes a config file.
7
+ *
8
+ * Two decisions shape everything here:
9
+ *
10
+ * - It writes config as code and applies it, rather than making six create calls. The user ends
11
+ * up owning the files, a second run is idempotent, and the whole flow rides on `config diff` /
12
+ * `config apply` plus one run endpoint instead of every resource API.
13
+ * - It never prunes. A quickstart that deleted a config-managed resource someone already had
14
+ * would be unforgivable, and the directory it builds is deliberately a subset of a real one.
15
+ *
16
+ * Not interactive-only by accident: `--scaffold-only` writes the same files with placeholders and
17
+ * makes no network call, which is the path for CI, dotfiles, and anyone who would rather read
18
+ * YAML than answer questions.
19
+ *
20
+ * This file is the orchestrator and nothing else: the flags, the order of the steps, and what
21
+ * each one does with the answer. Every step and phase lives in `../get-started/`, one module
22
+ * apiece, so this reads as the shape of the flow rather than its details.
23
+ */
24
+ import { Command } from 'commander';
25
+ import type { ClientFor, ResolveOutput } from '../get-started/types';
26
+ export declare const registerGetStartedCommand: (root: Command, binaryName: string, clientFor: ClientFor, resolveOutput: ResolveOutput) => void;
27
+ /**
28
+ * What every step needs to ask its questions: somewhere to read from, somewhere to write to, and
29
+ * what is already declared.
30
+ *
31
+ * One object rather than six parameters apiece, and one per step rather than one giant handler:
32
+ * `chooseAgent` was already written this way, so the rest being inline made the file read as two
33
+ * different programs.
34
+ */
@@ -0,0 +1,350 @@
1
+ "use strict";
2
+ /**
3
+ * `roark get-started` - the guided first run.
4
+ *
5
+ * Seven steps from an installed CLI to a graded simulation: who you are, the agent, the caller,
6
+ * the scenario, the metrics, the saved plan, the run. Each step asks the fewest questions it can,
7
+ * echoes the command it is shorthand for, and writes a config file.
8
+ *
9
+ * Two decisions shape everything here:
10
+ *
11
+ * - It writes config as code and applies it, rather than making six create calls. The user ends
12
+ * up owning the files, a second run is idempotent, and the whole flow rides on `config diff` /
13
+ * `config apply` plus one run endpoint instead of every resource API.
14
+ * - It never prunes. A quickstart that deleted a config-managed resource someone already had
15
+ * would be unforgivable, and the directory it builds is deliberately a subset of a real one.
16
+ *
17
+ * Not interactive-only by accident: `--scaffold-only` writes the same files with placeholders and
18
+ * makes no network call, which is the path for CI, dotfiles, and anyone who would rather read
19
+ * YAML than answer questions.
20
+ *
21
+ * This file is the orchestrator and nothing else: the flags, the order of the steps, and what
22
+ * each one does with the answer. Every step and phase lives in `../get-started/`, one module
23
+ * apiece, so this reads as the shape of the flow rather than its details.
24
+ */
25
+ Object.defineProperty(exports, "__esModule", { value: true });
26
+ exports.registerGetStartedCommand = void 0;
27
+ const confirm_1 = require("../confirm");
28
+ const errors_1 = require("../errors");
29
+ const output_1 = require("../output");
30
+ const account_1 = require("../get-started/account");
31
+ const agent_1 = require("../get-started/agent");
32
+ const apply_1 = require("../get-started/apply");
33
+ const existing_1 = require("../get-started/existing");
34
+ const ladder_1 = require("../get-started/ladder");
35
+ const module_1 = require("../get-started/module");
36
+ const prompt_1 = require("../get-started/prompt");
37
+ const resources_1 = require("../get-started/resources");
38
+ const run_1 = require("../get-started/run");
39
+ const scaffold_only_1 = require("../get-started/scaffold-only");
40
+ const scaffold_1 = require("../get-started/scaffold");
41
+ const steps_1 = require("../get-started/steps");
42
+ const target_1 = require("../get-started/target");
43
+ const answers_1 = require("../get-started/answers");
44
+ const withCommonOptions = (command) => command
45
+ .option('--base-url <url>', 'API base URL')
46
+ .option('--project <id>', 'project to act on')
47
+ .option('--token <token>', 'bearer token')
48
+ .option('--timeout <ms>', 'request timeout in milliseconds')
49
+ .option('--max-retries <count>', 'retries for retryable failures')
50
+ .option('--format <format>', 'output format')
51
+ .option('--json', 'shorthand for --format json')
52
+ .option('--no-color', 'disable colour')
53
+ .option('-q, --quiet', 'suppress non-essential output')
54
+ .showHelpAfterError();
55
+ const registerGetStartedCommand = (root, binaryName, clientFor, resolveOutput) => {
56
+ withCommonOptions(root.command('get-started'))
57
+ .alias('init')
58
+ .description('Guided setup: an agent, a caller, a scenario, metrics, and your first graded run')
59
+ // No commander default: the default depends on the format (`./roark` for YAML, the working
60
+ // directory for a config module, where `config apply` finds it by name), and a default here
61
+ // would make "was --dir given?" unanswerable.
62
+ .option('--dir <path>', `where to write the config (default: ${target_1.DEFAULT_DIR}, or . for --ts)`)
63
+ .option('--ts', `write TypeScript (${module_1.CONFIG_MODULE_FILE}) instead of YAML`)
64
+ .option('--yaml', 'write YAML, without asking')
65
+ .option('--scaffold-only', 'write the files with placeholder values and stop: no questions, no API calls')
66
+ .option('--no-run', 'apply the config but do not start a simulation')
67
+ .option('-y, --yes', 'skip both confirmations: the apply, and placing the call')
68
+ .option('--no-input', 'never prompt; fail instead')
69
+ .addHelpText('after', [
70
+ '',
71
+ 'Seven steps: account, agent, caller, scenario, metrics, plan, run. Each one writes a YAML',
72
+ 'file you own, and the whole directory is applied with `config apply`, so re-running is safe',
73
+ 'and nothing is ever pruned.',
74
+ '',
75
+ ` ${binaryName} get-started # answer the questions`,
76
+ ` ${binaryName} get-started --scaffold-only # just write the files`,
77
+ ` ${binaryName} get-started --no-run # set everything up, run it later`,
78
+ ` ${binaryName} get-started --ts # TypeScript config instead of YAML`,
79
+ '',
80
+ 'Two things are confirmed before they happen: the apply, and the run. `--yes` skips both,',
81
+ 'so in a script it will place a real, billed call. Pair it with `--no-run` if that is not',
82
+ 'what you want.',
83
+ ].join('\n'))
84
+ .action(async (options) => {
85
+ const color = (0, output_1.supportsColor)(process.stderr);
86
+ const scaffoldOnly = options['scaffoldOnly'] === true;
87
+ const quiet = options['quiet'] === true;
88
+ const say = (text) => {
89
+ if (!quiet)
90
+ (0, output_1.write)(text, process.stderr);
91
+ };
92
+ const wantsTs = options['ts'] === true;
93
+ const wantsYaml = options['yaml'] === true;
94
+ if (wantsTs && wantsYaml) {
95
+ throw new errors_1.UsageError('--ts and --yaml ask for two different files. Pick one.');
96
+ }
97
+ const chosenDir = typeof options['dir'] === 'string' ? options['dir'] : undefined;
98
+ // Settled up front for the non-interactive paths; the question below can still change it,
99
+ // which is why nothing else keeps its own copy of the directory. It did once, and a
100
+ // TypeScript config chosen at the prompt was written to `./roark` and then loaded from the
101
+ // working directory, because only one of the two had been recomputed.
102
+ //
103
+ // A TypeScript config defaults to the working directory rather than `./roark`, because
104
+ // `config apply` finds `roark.config.ts` there by itself and then needs no argument.
105
+ let target = (0, target_1.targetFor)(wantsTs ? 'ts' : 'yaml', chosenDir ?? (wantsTs ? '.' : target_1.DEFAULT_DIR));
106
+ if (!scaffoldOnly && (options['input'] === false || !(0, confirm_1.isInteractive)())) {
107
+ throw new errors_1.UsageError([
108
+ `${binaryName} get-started asks questions, so it needs a terminal.`,
109
+ '',
110
+ `Run it in one, or use --scaffold-only to write ${target.label} with placeholder values`,
111
+ `and fill them in by hand (then \`${(0, target_1.applyCommand)(binaryName, target)}\`).`,
112
+ ].join('\n'));
113
+ }
114
+ /** Said once the target is settled, because a config module that cannot import is useless. */
115
+ const warnIfUnimportable = () => {
116
+ if (target.format !== 'ts' || (0, target_1.sdkIsInstalled)(target.dir))
117
+ return;
118
+ say((0, ladder_1.note)(`${module_1.CONFIG_MODULE_FILE} imports ${module_1.CONFIG_MODULE_IMPORT}, which this project cannot resolve. Install a recent @roarkanalytics/sdk here, or use --yaml.`, color, 'yellow'));
119
+ };
120
+ if (scaffoldOnly) {
121
+ await (0, scaffold_only_1.scaffoldOnlyRun)({ binaryName, target, color, quiet, say, warnIfUnimportable });
122
+ return;
123
+ }
124
+ const prompter = (0, prompt_1.createPrompter)();
125
+ try {
126
+ // Only where the flags left it open; `chooseFormat` decides whether to ask at all.
127
+ if (!wantsTs && !wantsYaml)
128
+ target = await (0, target_1.chooseFormat)(prompter, chosenDir, target);
129
+ say((0, ladder_1.intro)(binaryName, target.label, target.format, color));
130
+ warnIfUnimportable();
131
+ const existing = await (0, existing_1.readExisting)(target);
132
+ // A config module is one file holding everything, so there is no way to add a resource
133
+ // to one without editing code somebody wrote. The YAML form has no such problem: a
134
+ // missing resource is a missing file, and writing it touches nothing else.
135
+ //
136
+ // So when the module already exists it is taken as final. Complete (it declares a plan)
137
+ // means the useful re-run still works: skip the questions, apply, offer the run. Partial
138
+ // means stopping, rather than asking questions whose answers have nowhere to go.
139
+ if (target.format === 'ts' && existing.length > 0) {
140
+ // Every kind, not just the plan: a module with no persona would still send step 3 to
141
+ // the prompt, and its answer could not be written. Complete means nothing left to ask.
142
+ const missing = [
143
+ ['an agent', 'agent'],
144
+ ['a caller', 'persona'],
145
+ ['a scenario', 'flow'],
146
+ ['a run plan', 'simulationPlan'],
147
+ ].filter(([, kind]) => (0, existing_1.namesOfKind)(existing, kind).length === 0);
148
+ if (missing.length > 0) {
149
+ throw new errors_1.UsageError([
150
+ `${target.label} already exists, and ${binaryName} get-started writes that file whole`,
151
+ 'rather than editing one you wrote.',
152
+ '',
153
+ `Add what it is missing yourself (${missing.map(([label]) => label).join(', ')}), then`,
154
+ `\`${(0, target_1.applyCommand)(binaryName, target)}\`. Or start a YAML config beside it with --yaml.`,
155
+ ].join('\n'));
156
+ }
157
+ say((0, ladder_1.note)(`${target.label} already declares everything, so this only runs it.`, color));
158
+ }
159
+ // ---- 1. Account ------------------------------------------------------------------
160
+ say((0, ladder_1.stepHeader)(0, color));
161
+ let client;
162
+ try {
163
+ client = clientFor(options);
164
+ }
165
+ catch (error) {
166
+ if (error instanceof errors_1.AuthRequiredError) {
167
+ throw new errors_1.AuthRequiredError(`${error.message}\nThen run \`${binaryName} get-started\` again.`);
168
+ }
169
+ throw error;
170
+ }
171
+ const credential = await (0, account_1.describeCredential)(client, binaryName);
172
+ const project = credential.defaultProject;
173
+ say((0, ladder_1.stepDone)(0, [
174
+ credential.email ?? 'credential accepted',
175
+ project === undefined ? undefined : `project ${project}`,
176
+ ]
177
+ .filter((part) => part !== undefined)
178
+ .join(', '), color));
179
+ if (credential.scope === 'USER' && project === undefined) {
180
+ say((0, ladder_1.note)(`No project selected. Run \`${binaryName} config set project <id>\` (\`${binaryName} project list\` shows the ids) if the next step fails.`, color, 'yellow'));
181
+ }
182
+ const steps = { prompter, say, color, binaryName, existing, label: target.label };
183
+ // ---- 2. Agent --------------------------------------------------------------------
184
+ const configuredAgents = (0, existing_1.namesOfKind)(existing, 'agent');
185
+ let agent;
186
+ if (configuredAgents.length > 0) {
187
+ agent = { name: configuredAgents[0] };
188
+ say((0, ladder_1.stepSkipped)(1, `${agent.name}, already declared in ${target.label}`, color));
189
+ // The declared file is the source of truth for its endpoints, and reading them back out
190
+ // of YAML to re-derive a direction would just duplicate what apply already resolves.
191
+ const declared = existing.find((resource) => resource['kind'] === 'agent' && resource['name'] === agent.name);
192
+ const endpoints = (declared?.['endpoints'] ?? [])
193
+ .filter((endpoint) => {
194
+ return typeof endpoint['value'] === 'string';
195
+ })
196
+ .map((endpoint) => ({
197
+ value: endpoint.value,
198
+ // The DSL's own default when the file leaves it out, so this reads the file rather
199
+ // than guessing at it.
200
+ direction: (typeof endpoint.direction === 'string' ?
201
+ endpoint.direction
202
+ : 'INCOMING'),
203
+ }));
204
+ if (endpoints.length === 1) {
205
+ agent = { ...agent, dial: endpoints[0] };
206
+ }
207
+ else if (endpoints.length > 1) {
208
+ // Several declared lines, and they are not interchangeable: one may be the inbound
209
+ // number and another the outbound one, which run opposite tests. Picking the first
210
+ // would quietly call the wrong line.
211
+ // Keyed on value AND direction: one number routinely carries an inbound endpoint and
212
+ // an outbound one, so the number alone does not identify a line.
213
+ const key = (endpoint) => `${endpoint.value}::${endpoint.direction}`;
214
+ const line = await prompter.select(`${agent.name} declares several lines. Which should the run call?`, endpoints.map((endpoint) => ({
215
+ value: key(endpoint),
216
+ label: endpoint.value,
217
+ hint: endpoint.direction.toLowerCase().replace(/_/g, ' '),
218
+ })), key(endpoints[0]));
219
+ agent = { ...agent, dial: endpoints.find((endpoint) => key(endpoint) === line) };
220
+ }
221
+ }
222
+ else {
223
+ say((0, ladder_1.stepHeader)(1, color));
224
+ agent = await (0, agent_1.chooseAgent)(client, prompter, say, binaryName, color);
225
+ say((0, ladder_1.stepDone)(1, agent.dial === undefined ? `${agent.name}, no line to call yet` : agent.name, color));
226
+ }
227
+ // ---- 3. Caller -------------------------------------------------------------------
228
+ const persona = await (0, steps_1.chooseCaller)(steps);
229
+ // ---- 4. Scenario -----------------------------------------------------------------
230
+ const flow = await (0, steps_1.chooseScenario)(steps, agent, configuredAgents.length === 0);
231
+ // ---- 5. Metrics ------------------------------------------------------------------
232
+ const configuredPlans = (0, existing_1.namesOfKind)(existing, 'simulationPlan');
233
+ const graded = await (0, steps_1.chooseMetrics)(steps, client, configuredPlans[0]);
234
+ const metrics = graded.metrics;
235
+ const customMetric = graded.customMetric;
236
+ // ---- 6. Plan ---------------------------------------------------------------------
237
+ let planName;
238
+ if (configuredPlans.length > 0) {
239
+ planName = configuredPlans[0];
240
+ say((0, ladder_1.stepSkipped)(5, `${planName}, already declared in ${target.label}`, color));
241
+ }
242
+ else if (agent.dial === undefined) {
243
+ say((0, ladder_1.stepSkipped)(5, `waiting on a line to call. Add an endpoint to ${agent.name}'s config and run this again`, color));
244
+ }
245
+ else {
246
+ say((0, ladder_1.stepHeader)(5, color));
247
+ planName = await prompter.ask('Name for the saved run?', {
248
+ default: 'first-run',
249
+ validate: (0, answers_1.nameRules)('name'),
250
+ });
251
+ say((0, ladder_1.stepDone)(5, planName, color));
252
+ }
253
+ const setup = {
254
+ agent,
255
+ persona,
256
+ flow,
257
+ metrics,
258
+ ...(customMetric === undefined ? {} : { customMetric }),
259
+ ...(planName === undefined ?
260
+ {}
261
+ : { plan: { name: planName, maxDurationSeconds: resources_1.DEFAULT_MAX_DURATION_SECONDS } }),
262
+ };
263
+ // Only the files for steps that actually ran: a step read back out of the directory is
264
+ // already on disk, and rewriting it is how an edit gets lost.
265
+ const pending = target.format === 'ts' ?
266
+ // One file, written whole or not at all. The guard above means we only reach a write
267
+ // when there was nothing there before.
268
+ existing.length === 0 ?
269
+ [(0, module_1.setupModule)(setup)]
270
+ : []
271
+ : (0, resources_1.setupFiles)(setup).filter((file) => {
272
+ if (file.path.startsWith('agents/'))
273
+ return configuredAgents.length === 0;
274
+ if (file.path.startsWith('personas/'))
275
+ return persona.authored;
276
+ if (file.path.startsWith('flows/'))
277
+ return flow.authored;
278
+ if (file.path.startsWith('simulation-plans/'))
279
+ return configuredPlans.length === 0;
280
+ return true;
281
+ });
282
+ say('');
283
+ const result = await (0, scaffold_1.writeScaffold)(target.dir, pending);
284
+ for (const path of result.written)
285
+ say(`${(0, output_1.paint)('+', 'green', color)} ${path}`);
286
+ for (const path of result.skipped)
287
+ say(`${(0, output_1.paint)('·', 'yellow', color)} ${path} (already there, left alone)`);
288
+ // ---- Apply -----------------------------------------------------------------------
289
+ const outcome = await (0, apply_1.applyConfig)({
290
+ client,
291
+ prompter,
292
+ say,
293
+ binaryName,
294
+ color,
295
+ quiet,
296
+ options,
297
+ target,
298
+ });
299
+ if (outcome.stopped)
300
+ return;
301
+ const applied = outcome.applied;
302
+ // ---- 7. Run ----------------------------------------------------------------------
303
+ if (planName !== undefined && options['run'] !== false) {
304
+ const started = await (0, run_1.startRun)({
305
+ client,
306
+ prompter,
307
+ say,
308
+ binaryName,
309
+ color,
310
+ quiet,
311
+ options,
312
+ planName,
313
+ dir: target.label,
314
+ apply: (0, target_1.applyCommand)(binaryName, target),
315
+ dial: agent.dial,
316
+ applied,
317
+ resolveOutput,
318
+ });
319
+ if (started)
320
+ return;
321
+ }
322
+ // Everything that did not start a run: no plan yet, `--no-run`, or a plan whose id we
323
+ // could not resolve. The directory is still the useful result, so it goes to stdout.
324
+ say((0, ladder_1.nextSteps)({
325
+ binaryName,
326
+ dir: target.label,
327
+ apply: (0, target_1.applyCommand)(binaryName, target),
328
+ lines: planName === undefined ?
329
+ [
330
+ `${(0, output_1.paint)(`${binaryName} get-started`, 'cyan', color)} run this again to finish the plan and the run`,
331
+ ]
332
+ : [`${(0, output_1.paint)(`${binaryName} get-started`, 'cyan', color)} run this again to start the run`],
333
+ }, color));
334
+ if (!quiet)
335
+ (0, output_1.write)(target.label);
336
+ }
337
+ finally {
338
+ prompter.close();
339
+ }
340
+ });
341
+ };
342
+ exports.registerGetStartedCommand = registerGetStartedCommand;
343
+ /**
344
+ * What every step needs to ask its questions: somewhere to read from, somewhere to write to, and
345
+ * what is already declared.
346
+ *
347
+ * One object rather than six parameters apiece, and one per step rather than one giant handler:
348
+ * `chooseAgent` was already written this way, so the rest being inline made the file read as two
349
+ * different programs.
350
+ */
@@ -7,6 +7,16 @@
7
7
  * loader stays deliberately schema-agnostic (no per-kind knowledge), and any drift is caught by
8
8
  * the API, not silently accepted here.
9
9
  */
10
+ import { UsageError } from './errors';
11
+ /**
12
+ * A directory that exists but holds no resources.
13
+ *
14
+ * Its own class so a caller can tell "nothing here yet" from "this config is broken" without
15
+ * matching on the message text, which would break silently the day the wording changes.
16
+ * `get-started` treats it as a fresh start; everyone else still sees a UsageError and exit 2.
17
+ */
18
+ export declare class EmptyConfigDirectoryError extends UsageError {
19
+ }
10
20
  export interface ConfigBundle {
11
21
  resources: Array<Record<string, unknown>>;
12
22
  prune?: boolean;
@@ -9,11 +9,21 @@
9
9
  * the API, not silently accepted here.
10
10
  */
11
11
  Object.defineProperty(exports, "__esModule", { value: true });
12
- exports.buildBundle = void 0;
12
+ exports.buildBundle = exports.EmptyConfigDirectoryError = void 0;
13
13
  const promises_1 = require("node:fs/promises");
14
14
  const node_path_1 = require("node:path");
15
15
  const yaml_1 = require("yaml");
16
16
  const errors_1 = require("./errors");
17
+ /**
18
+ * A directory that exists but holds no resources.
19
+ *
20
+ * Its own class so a caller can tell "nothing here yet" from "this config is broken" without
21
+ * matching on the message text, which would break silently the day the wording changes.
22
+ * `get-started` treats it as a fresh start; everyone else still sees a UsageError and exit 2.
23
+ */
24
+ class EmptyConfigDirectoryError extends errors_1.UsageError {
25
+ }
26
+ exports.EmptyConfigDirectoryError = EmptyConfigDirectoryError;
17
27
  const FILE_PREFIX = 'file://';
18
28
  /**
19
29
  * Resolve a single `file://relative/path` reference against the config root and return the file's
@@ -88,8 +98,9 @@ const buildBundle = async (dir, options = {}) => {
88
98
  seen.set(key, rel);
89
99
  resources.push(resource);
90
100
  }
91
- if (resources.length === 0)
92
- throw new errors_1.UsageError(`no config resources (*.yaml) found under ${dir}`);
101
+ if (resources.length === 0) {
102
+ throw new EmptyConfigDirectoryError(`no config resources (*.yaml) found under ${dir}`);
103
+ }
93
104
  return { resources, ...(options.prune === undefined ? {} : { prune: options.prune }) };
94
105
  };
95
106
  exports.buildBundle = buildBundle;
@@ -0,0 +1,15 @@
1
+ /**
2
+ * Rendering a config `diff` / `apply` result for a terminal.
3
+ *
4
+ * Shared by `config diff` / `config apply` and by `get-started`, which applies the directory it
5
+ * just wrote. One formatter rather than two, so the preview someone sees in the guided flow is
6
+ * byte-for-byte the preview they see once they are running the commands themselves.
7
+ */
8
+ export interface ChangeSet {
9
+ changes: Array<Record<string, unknown>>;
10
+ summary: Record<string, number>;
11
+ }
12
+ /** One line per change, then a tally. `apply` results also carry a per-change status. */
13
+ export declare const formatChanges: (data: ChangeSet) => string;
14
+ /** How many changes an apply would actually make, which is what a confirmation has to quote. */
15
+ export declare const changeCount: (summary: Record<string, number>) => number;
@@ -0,0 +1,32 @@
1
+ "use strict";
2
+ /**
3
+ * Rendering a config `diff` / `apply` result for a terminal.
4
+ *
5
+ * Shared by `config diff` / `config apply` and by `get-started`, which applies the directory it
6
+ * just wrote. One formatter rather than two, so the preview someone sees in the guided flow is
7
+ * byte-for-byte the preview they see once they are running the commands themselves.
8
+ */
9
+ Object.defineProperty(exports, "__esModule", { value: true });
10
+ exports.changeCount = exports.formatChanges = void 0;
11
+ const OP_MARK = { create: '+', update: '~', delete: '-', noop: ' ' };
12
+ /** One line per change, then a tally. `apply` results also carry a per-change status. */
13
+ const formatChanges = (data) => {
14
+ const lines = data.changes.map((change) => {
15
+ const mark = OP_MARK[String(change['op'])] ?? '?';
16
+ const status = change['status'] ? ` (${String(change['status'])})` : '';
17
+ const error = change['error'] ? ` ${String(change['error'])}` : '';
18
+ return ` ${mark} ${String(change['configKey'])}${status}${error}`;
19
+ });
20
+ const s = data.summary;
21
+ const tally = [
22
+ `${s['create'] ?? 0} to create`,
23
+ `${s['update'] ?? 0} to update`,
24
+ `${s['delete'] ?? 0} to delete`,
25
+ ...(s['failed'] === undefined ? [] : [`${s['failed']} failed`]),
26
+ ].join(', ');
27
+ return [...lines, '', tally].join('\n');
28
+ };
29
+ exports.formatChanges = formatChanges;
30
+ /** How many changes an apply would actually make, which is what a confirmation has to quote. */
31
+ const changeCount = (summary) => (summary['create'] ?? 0) + (summary['update'] ?? 0) + (summary['delete'] ?? 0);
32
+ exports.changeCount = changeCount;
@@ -0,0 +1,18 @@
1
+ /**
2
+ * Step 1: what the credential says it is.
3
+ *
4
+ * Named so the flow can open with the account and project it is about to change, rather than
5
+ * announcing that something unspecified worked.
6
+ */
7
+ import type Roark from '@roarkanalytics/sdk';
8
+ export interface Credential {
9
+ email?: string;
10
+ scope?: string;
11
+ defaultProject?: string;
12
+ }
13
+ /**
14
+ * What the credential says it is, so step one can name the account and project rather than
15
+ * announcing that something unspecified worked. Only a 401 stops the flow: anything else (an
16
+ * older API with no `/v1/me`, a key without the permission) is a thin answer, not a broken one.
17
+ */
18
+ export declare const describeCredential: (client: Roark, binaryName: string) => Promise<Credential>;