@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.
- package/CHANGELOG.md +56 -0
- package/README.md +45 -0
- package/commands.js +575 -0
- package/completions.js +4 -4
- package/man/roark-calendar-connection-check.1 +93 -0
- package/man/roark-calendar-connection-create.1 +102 -0
- package/man/roark-calendar-connection-delete.1 +93 -0
- package/man/roark-calendar-connection-get.1 +93 -0
- package/man/roark-calendar-connection-list.1 +93 -0
- package/man/roark-calendar-connection-target-get.1 +96 -0
- package/man/roark-calendar-connection-target-list.1 +93 -0
- package/man/roark-calendar-connection-update.1 +103 -0
- package/man/roark-metric-definition-update.1 +3 -0
- package/man/roark-metric-variant-update.1 +3 -0
- package/man/roark-tool-create.1 +123 -0
- package/man/roark-tool-delete.1 +93 -0
- package/man/roark-tool-get.1 +93 -0
- package/man/roark-tool-list.1 +96 -0
- package/man/roark-tool-update.1 +127 -0
- package/man/roark.1 +39 -0
- package/npm-shrinkwrap.json +6 -6
- package/package.json +15 -2
- package/runtime/commands/config-as-code.js +5 -23
- package/runtime/commands/get-started.d.ts +34 -0
- package/runtime/commands/get-started.js +350 -0
- package/runtime/config-bundle.d.ts +10 -0
- package/runtime/config-bundle.js +14 -3
- package/runtime/config-changes.d.ts +15 -0
- package/runtime/config-changes.js +32 -0
- package/runtime/get-started/account.d.ts +18 -0
- package/runtime/get-started/account.js +35 -0
- package/runtime/get-started/agent.d.ts +17 -0
- package/runtime/get-started/agent.js +116 -0
- package/runtime/get-started/answers.d.ts +15 -0
- package/runtime/get-started/answers.js +42 -0
- package/runtime/get-started/apply.d.ts +35 -0
- package/runtime/get-started/apply.js +54 -0
- package/runtime/get-started/existing.d.ts +15 -0
- package/runtime/get-started/existing.js +47 -0
- package/runtime/get-started/ladder.d.ts +37 -0
- package/runtime/get-started/ladder.js +69 -0
- package/runtime/get-started/module.d.ts +20 -0
- package/runtime/get-started/module.js +159 -0
- package/runtime/get-started/placeholder.d.ts +9 -0
- package/runtime/get-started/placeholder.js +36 -0
- package/runtime/get-started/prompt.d.ts +32 -0
- package/runtime/get-started/prompt.js +132 -0
- package/runtime/get-started/resources.d.ts +106 -0
- package/runtime/get-started/resources.js +184 -0
- package/runtime/get-started/run.d.ts +42 -0
- package/runtime/get-started/run.js +101 -0
- package/runtime/get-started/scaffold-only.d.ts +19 -0
- package/runtime/get-started/scaffold-only.js +43 -0
- package/runtime/get-started/scaffold.d.ts +15 -0
- package/runtime/get-started/scaffold.js +35 -0
- package/runtime/get-started/starter-metrics.d.ts +33 -0
- package/runtime/get-started/starter-metrics.js +104 -0
- package/runtime/get-started/steps.d.ts +33 -0
- package/runtime/get-started/steps.js +112 -0
- package/runtime/get-started/target.d.ts +47 -0
- package/runtime/get-started/target.js +81 -0
- package/runtime/get-started/types.d.ts +18 -0
- package/runtime/get-started/types.js +8 -0
- package/runtime/get-started/watch.d.ts +57 -0
- package/runtime/get-started/watch.js +103 -0
- package/runtime/program.js +5 -0
- package/version.d.ts +1 -1
- package/version.js +1 -1
|
@@ -0,0 +1,159 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
/**
|
|
3
|
+
* The TypeScript form of the config `get-started` writes.
|
|
4
|
+
*
|
|
5
|
+
* Same resources as the YAML, serialized differently: `roark.config.ts` exporting
|
|
6
|
+
* `defineConfig({ resources })`, with one `define*` helper per kind. The DSL is a mirror of the
|
|
7
|
+
* YAML one (cross-references are names, not object references), so this takes the resource
|
|
8
|
+
* objects the YAML path already builds and only changes how they reach the page.
|
|
9
|
+
*
|
|
10
|
+
* Worth the second emitter because the two are not interchangeable in practice: YAML needs
|
|
11
|
+
* nothing installed and works for anyone who reached the CLI through a global install, while the
|
|
12
|
+
* TypeScript form gives types, editor completion and real code around the values - but only in a
|
|
13
|
+
* project that has `@roarkanalytics/sdk` to import from.
|
|
14
|
+
*/
|
|
15
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
16
|
+
exports.setupModule = exports.CONFIG_MODULE_IMPORT = exports.CONFIG_MODULE_FILE = void 0;
|
|
17
|
+
const resources_1 = require("./resources");
|
|
18
|
+
/** The file `config apply` auto-detects when it is given no path, which is why this name. */
|
|
19
|
+
exports.CONFIG_MODULE_FILE = 'roark.config.ts';
|
|
20
|
+
/** The package the helpers come from. Absent from the project, the config cannot be loaded. */
|
|
21
|
+
exports.CONFIG_MODULE_IMPORT = '@roarkanalytics/sdk/lib/config';
|
|
22
|
+
const HELPERS = {
|
|
23
|
+
metric: 'defineMetric',
|
|
24
|
+
persona: 'definePersona',
|
|
25
|
+
agent: 'defineAgent',
|
|
26
|
+
flow: 'defineImprovFlow',
|
|
27
|
+
simulationPlan: 'defineSimulationPlan',
|
|
28
|
+
};
|
|
29
|
+
const omit = (value, key) => Object.fromEntries(Object.entries(value).filter(([name]) => name !== key));
|
|
30
|
+
/** `my-agent` -> `myAgent`, for the const each resource is bound to. */
|
|
31
|
+
const camelize = (name) => {
|
|
32
|
+
const camel = name
|
|
33
|
+
.split(/[-_.]+/)
|
|
34
|
+
.filter((part) => part.length > 0)
|
|
35
|
+
.map((part, index) => (index === 0 ? part : `${part.charAt(0).toUpperCase()}${part.slice(1)}`))
|
|
36
|
+
.join('');
|
|
37
|
+
// A config name may start with a digit, which an identifier may not.
|
|
38
|
+
return /^[0-9]/.test(camel) ? `_${camel}` : camel;
|
|
39
|
+
};
|
|
40
|
+
/**
|
|
41
|
+
* A single-quoted TypeScript string.
|
|
42
|
+
*
|
|
43
|
+
* Newlines are escaped, not just quotes and backslashes. Nothing the prompts can produce today
|
|
44
|
+
* holds one - readline hands back a line at a time - but a value that gained one from anywhere
|
|
45
|
+
* else would emit a literal broken across two lines, which is not valid TypeScript, and the
|
|
46
|
+
* failure would land on the user as a syntax error in a file they did not write.
|
|
47
|
+
*/
|
|
48
|
+
const quote = (value) => `'${value
|
|
49
|
+
.replace(/\\/g, '\\\\')
|
|
50
|
+
.replace(/'/g, "\\'")
|
|
51
|
+
.replace(/\n/g, '\\n')
|
|
52
|
+
.replace(/\r/g, '\\r')
|
|
53
|
+
.replace(/\t/g, '\\t')}'`;
|
|
54
|
+
/**
|
|
55
|
+
* How wide a line may get before the literal breaks across several.
|
|
56
|
+
*
|
|
57
|
+
* Roughly what a formatter would do, so running prettier over the generated file is close to a
|
|
58
|
+
* no-op rather than a rewrite of every line someone would then see in a diff.
|
|
59
|
+
*/
|
|
60
|
+
const WIDTH = 88;
|
|
61
|
+
const key = (name) => (/^[a-zA-Z_$][\w$]*$/.test(name) ? name : quote(name));
|
|
62
|
+
const entriesOf = (value) => Object.entries(value).filter(([, entry]) => entry !== undefined);
|
|
63
|
+
/** The whole value on one line. Used when it fits; the multi-line form is the fallback. */
|
|
64
|
+
const compact = (value) => {
|
|
65
|
+
if (typeof value === 'string')
|
|
66
|
+
return quote(value);
|
|
67
|
+
if (typeof value === 'number' || typeof value === 'boolean')
|
|
68
|
+
return String(value);
|
|
69
|
+
if (value === null)
|
|
70
|
+
return 'null';
|
|
71
|
+
if (Array.isArray(value))
|
|
72
|
+
return `[${value.map(compact).join(', ')}]`;
|
|
73
|
+
if (typeof value === 'object') {
|
|
74
|
+
const entries = entriesOf(value);
|
|
75
|
+
if (entries.length === 0)
|
|
76
|
+
return '{}';
|
|
77
|
+
return `{ ${entries.map(([name, entry]) => `${key(name)}: ${compact(entry)}`).join(', ')} }`;
|
|
78
|
+
}
|
|
79
|
+
return 'undefined';
|
|
80
|
+
};
|
|
81
|
+
/**
|
|
82
|
+
* A TypeScript object literal.
|
|
83
|
+
*
|
|
84
|
+
* Hand-rolled rather than `JSON.stringify`: the output is code someone will read and edit, so it
|
|
85
|
+
* wants single quotes, unquoted keys, trailing commas and short values kept on one line, none of
|
|
86
|
+
* which JSON can produce.
|
|
87
|
+
*/
|
|
88
|
+
const literal = (value, indent, used = 0) => {
|
|
89
|
+
const inline = compact(value);
|
|
90
|
+
// `used` is what the line already spent before this value: `const x = defineAgent(` and the
|
|
91
|
+
// closing `);`. Without it a one-line literal that fits on its own overflows once its
|
|
92
|
+
// declaration is in front of it.
|
|
93
|
+
if (indent.length + used + inline.length <= WIDTH)
|
|
94
|
+
return inline;
|
|
95
|
+
if (Array.isArray(value)) {
|
|
96
|
+
const inner = `${indent} `;
|
|
97
|
+
const entries = value.map((entry) => `${inner}${literal(entry, inner)},`).join('\n');
|
|
98
|
+
return `[\n${entries}\n${indent}]`;
|
|
99
|
+
}
|
|
100
|
+
if (value !== null && typeof value === 'object') {
|
|
101
|
+
const inner = `${indent} `;
|
|
102
|
+
const lines = entriesOf(value)
|
|
103
|
+
.map(([name, entry]) => `${inner}${key(name)}: ${literal(entry, inner)},`)
|
|
104
|
+
.join('\n');
|
|
105
|
+
return `{\n${lines}\n${indent}}`;
|
|
106
|
+
}
|
|
107
|
+
return inline;
|
|
108
|
+
};
|
|
109
|
+
/** The resources, as `const <name> = define<Kind>({ ... })` blocks, in apply order. */
|
|
110
|
+
const declarations = (setup) => {
|
|
111
|
+
const used = new Set();
|
|
112
|
+
const helpers = [];
|
|
113
|
+
const bindings = [];
|
|
114
|
+
const blocks = [];
|
|
115
|
+
for (const { kind, resource, notes } of (0, resources_1.resourcesFor)(setup, 'ts')) {
|
|
116
|
+
const helper = HELPERS[kind];
|
|
117
|
+
if (helper === undefined)
|
|
118
|
+
continue;
|
|
119
|
+
if (!helpers.includes(helper))
|
|
120
|
+
helpers.push(helper);
|
|
121
|
+
// `kind` is the helper's job. `type` is too, but ONLY for a flow, where the helper is chosen
|
|
122
|
+
// per type (`defineImprovFlow`): a metric's `type` is a required field of its own, and
|
|
123
|
+
// stripping that one produces a config that does not compile.
|
|
124
|
+
const { kind: _kind, name, ...fields } = resource;
|
|
125
|
+
const rest = kind === 'flow' ? omit(fields, 'type') : fields;
|
|
126
|
+
let binding = camelize(String(name));
|
|
127
|
+
// Two kinds may legitimately share a name, and two consts may not.
|
|
128
|
+
if (used.has(binding))
|
|
129
|
+
binding = `${binding}${kind.charAt(0).toUpperCase()}${kind.slice(1)}`;
|
|
130
|
+
used.add(binding);
|
|
131
|
+
bindings.push(binding);
|
|
132
|
+
const opening = `const ${binding} = ${helper}(`;
|
|
133
|
+
const body = literal({ name, ...rest }, '', opening.length + ');'.length);
|
|
134
|
+
blocks.push([...notes.map((note) => `// ${note}`), `${opening}${body});`].join('\n'));
|
|
135
|
+
}
|
|
136
|
+
return { source: blocks.join('\n\n'), helpers, bindings };
|
|
137
|
+
};
|
|
138
|
+
/** The whole `roark.config.ts`, or undefined when the setup has nothing to write. */
|
|
139
|
+
const setupModule = (setup) => {
|
|
140
|
+
const { source, helpers, bindings } = declarations(setup);
|
|
141
|
+
const imported = [...helpers, 'defineConfig'].sort();
|
|
142
|
+
return {
|
|
143
|
+
path: exports.CONFIG_MODULE_FILE,
|
|
144
|
+
contents: [
|
|
145
|
+
'// Roark config as code. Everything this project declares in Roark lives here.',
|
|
146
|
+
'//',
|
|
147
|
+
`// \`roark config apply\` finds this file by name, so it needs no argument. The YAML form is`,
|
|
148
|
+
'// equivalent: see https://roark.ai/documentation/config-as-code/overview',
|
|
149
|
+
'',
|
|
150
|
+
`import {\n${imported.map((helper) => ` ${helper},`).join('\n')}\n} from '${exports.CONFIG_MODULE_IMPORT}';`,
|
|
151
|
+
'',
|
|
152
|
+
source,
|
|
153
|
+
'',
|
|
154
|
+
`export default defineConfig({\n resources: [${bindings.join(', ')}],\n});`,
|
|
155
|
+
'',
|
|
156
|
+
].join('\n'),
|
|
157
|
+
};
|
|
158
|
+
};
|
|
159
|
+
exports.setupModule = setupModule;
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What `--scaffold-only` writes: a complete, valid config with nothing invented about you.
|
|
3
|
+
*
|
|
4
|
+
* Every value here is a placeholder someone is expected to replace, which is why the command
|
|
5
|
+
* prints a TODO per file rather than pretending the result is ready to apply.
|
|
6
|
+
*/
|
|
7
|
+
import { type ConfigFormat, type Setup } from './resources';
|
|
8
|
+
export declare const placeholderSetup: () => Setup;
|
|
9
|
+
export declare const placeholderTodos: (format: ConfigFormat) => string[];
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
/**
|
|
3
|
+
* What `--scaffold-only` writes: a complete, valid config with nothing invented about you.
|
|
4
|
+
*
|
|
5
|
+
* Every value here is a placeholder someone is expected to replace, which is why the command
|
|
6
|
+
* prints a TODO per file rather than pretending the result is ready to apply.
|
|
7
|
+
*/
|
|
8
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
9
|
+
exports.placeholderTodos = exports.placeholderSetup = void 0;
|
|
10
|
+
const module_1 = require("./module");
|
|
11
|
+
const resources_1 = require("./resources");
|
|
12
|
+
const placeholderSetup = () => ({
|
|
13
|
+
agent: {
|
|
14
|
+
name: 'my-agent',
|
|
15
|
+
endpoints: [{ value: '+15551234567', direction: 'INCOMING' }],
|
|
16
|
+
dial: { value: '+15551234567', direction: 'INCOMING' },
|
|
17
|
+
},
|
|
18
|
+
persona: { name: 'curious-caller', language: 'EN', accent: 'US', gender: 'FEMALE' },
|
|
19
|
+
flow: {
|
|
20
|
+
name: 'first-scenario',
|
|
21
|
+
goal: 'You call to ask a question you need answered before you can book.',
|
|
22
|
+
expectation: 'The agent answers the question and offers to help further',
|
|
23
|
+
},
|
|
24
|
+
metrics: ['agent_responsive', 'call_ended_cleanly', 'scenario_adherence'],
|
|
25
|
+
plan: { name: 'first-run', maxDurationSeconds: resources_1.DEFAULT_MAX_DURATION_SECONDS },
|
|
26
|
+
});
|
|
27
|
+
exports.placeholderSetup = placeholderSetup;
|
|
28
|
+
const placeholderTodos = (format) => {
|
|
29
|
+
const agent = format === 'ts' ? module_1.CONFIG_MODULE_FILE : 'agents/my-agent.yaml';
|
|
30
|
+
const flow = format === 'ts' ? module_1.CONFIG_MODULE_FILE : 'flows/first-scenario.yaml';
|
|
31
|
+
return [
|
|
32
|
+
`Replace the endpoint value in ${agent} with the number Roark should call.`,
|
|
33
|
+
`Rewrite the scenario prompt in ${flow} so it describes a real call.`,
|
|
34
|
+
];
|
|
35
|
+
};
|
|
36
|
+
exports.placeholderTodos = placeholderTodos;
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The questions `get-started` asks.
|
|
3
|
+
*
|
|
4
|
+
* `confirm.ts` covers the only question the rest of the CLI needs ("are you sure?"). A guided
|
|
5
|
+
* setup needs three more shapes - a value, one choice, a set of choices - so they live here
|
|
6
|
+
* instead of growing that file. Same rules as everywhere else: the conversation is written to
|
|
7
|
+
* stderr so stdout stays reserved for the ids a script captures, and it is all line-oriented
|
|
8
|
+
* (no cursor control), so it behaves the same over ssh, in tmux, and in a dumb terminal.
|
|
9
|
+
*
|
|
10
|
+
* `Prompter` is an interface because scripted answers are the only practical way to test a
|
|
11
|
+
* wizard: a real readline needs a TTY, which CI does not have.
|
|
12
|
+
*/
|
|
13
|
+
export interface Choice<T extends string> {
|
|
14
|
+
value: T;
|
|
15
|
+
label: string;
|
|
16
|
+
/** A few words on what picking this means; dimmed after the label. */
|
|
17
|
+
hint?: string;
|
|
18
|
+
}
|
|
19
|
+
export interface AskOptions {
|
|
20
|
+
default?: string;
|
|
21
|
+
/** Returns a message when the answer is unusable, so the same question can be asked again. */
|
|
22
|
+
validate?: (answer: string) => string | undefined;
|
|
23
|
+
}
|
|
24
|
+
export interface Prompter {
|
|
25
|
+
ask: (question: string, options?: AskOptions) => Promise<string>;
|
|
26
|
+
select: <T extends string>(question: string, choices: readonly Choice<T>[], fallback: T) => Promise<T>;
|
|
27
|
+
/** Returns the chosen values; an empty array is a legitimate answer ("none"). */
|
|
28
|
+
multiSelect: <T extends string>(question: string, choices: readonly Choice<T>[], fallback: readonly T[]) => Promise<T[]>;
|
|
29
|
+
confirm: (question: string, fallback: boolean) => Promise<boolean>;
|
|
30
|
+
close: () => void;
|
|
31
|
+
}
|
|
32
|
+
export declare const createPrompter: () => Prompter;
|
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
/**
|
|
3
|
+
* The questions `get-started` asks.
|
|
4
|
+
*
|
|
5
|
+
* `confirm.ts` covers the only question the rest of the CLI needs ("are you sure?"). A guided
|
|
6
|
+
* setup needs three more shapes - a value, one choice, a set of choices - so they live here
|
|
7
|
+
* instead of growing that file. Same rules as everywhere else: the conversation is written to
|
|
8
|
+
* stderr so stdout stays reserved for the ids a script captures, and it is all line-oriented
|
|
9
|
+
* (no cursor control), so it behaves the same over ssh, in tmux, and in a dumb terminal.
|
|
10
|
+
*
|
|
11
|
+
* `Prompter` is an interface because scripted answers are the only practical way to test a
|
|
12
|
+
* wizard: a real readline needs a TTY, which CI does not have.
|
|
13
|
+
*/
|
|
14
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
15
|
+
exports.createPrompter = void 0;
|
|
16
|
+
const node_readline_1 = require("node:readline");
|
|
17
|
+
const errors_1 = require("../errors");
|
|
18
|
+
const output_1 = require("../output");
|
|
19
|
+
/**
|
|
20
|
+
* How many times one question is re-asked before giving up. Looping forever on a pipe that will
|
|
21
|
+
* never answer is how a wizard hangs a CI job; three tries is enough for a typo and no more.
|
|
22
|
+
*/
|
|
23
|
+
const ATTEMPTS = 3;
|
|
24
|
+
const exhausted = () => {
|
|
25
|
+
throw new errors_1.UsageError('No usable answer after three attempts, so nothing was changed.');
|
|
26
|
+
};
|
|
27
|
+
const createPrompter = () => {
|
|
28
|
+
const out = process.stderr;
|
|
29
|
+
const color = (0, output_1.supportsColor)(out);
|
|
30
|
+
const rl = (0, node_readline_1.createInterface)({ input: process.stdin, output: out });
|
|
31
|
+
const line = (text) => (0, output_1.write)(text, out);
|
|
32
|
+
const question = (text) => new Promise((resolve) => rl.question(text, resolve));
|
|
33
|
+
const problem = (text) => line((0, output_1.paint)(` ${text}`, 'yellow', color));
|
|
34
|
+
const asked = (text) => `${(0, output_1.paint)('?', 'cyan', color)} ${text}`;
|
|
35
|
+
const listChoices = (choices, marked) => {
|
|
36
|
+
choices.forEach((choice, index) => {
|
|
37
|
+
const mark = marked.includes(choice.value) ? (0, output_1.paint)('>', 'green', color) : ' ';
|
|
38
|
+
const hint = choice.hint === undefined ? '' : (0, output_1.paint)(` ${choice.hint}`, 'dim', color);
|
|
39
|
+
line(` ${mark} ${index + 1}) ${choice.label}${hint}`);
|
|
40
|
+
});
|
|
41
|
+
};
|
|
42
|
+
const ask = async (text, options = {}) => {
|
|
43
|
+
const fallback = options.default;
|
|
44
|
+
const suffix = fallback === undefined ? '' : ` ${(0, output_1.paint)(`[${fallback}]`, 'dim', color)}`;
|
|
45
|
+
for (let attempt = 0; attempt < ATTEMPTS; attempt += 1) {
|
|
46
|
+
const raw = (await question(`${asked(text)}${suffix} `)).trim();
|
|
47
|
+
const answer = raw.length > 0 ? raw : fallback ?? '';
|
|
48
|
+
if (answer.length === 0) {
|
|
49
|
+
problem('A value is needed here.');
|
|
50
|
+
continue;
|
|
51
|
+
}
|
|
52
|
+
const invalid = options.validate?.(answer);
|
|
53
|
+
if (invalid !== undefined) {
|
|
54
|
+
problem(invalid);
|
|
55
|
+
continue;
|
|
56
|
+
}
|
|
57
|
+
return answer;
|
|
58
|
+
}
|
|
59
|
+
return exhausted();
|
|
60
|
+
};
|
|
61
|
+
const select = async (text, choices, fallback) => {
|
|
62
|
+
if (choices.length === 0)
|
|
63
|
+
throw new errors_1.UsageError(`nothing to choose from for: ${text}`);
|
|
64
|
+
const fallbackIndex = choices.findIndex((choice) => choice.value === fallback);
|
|
65
|
+
for (let attempt = 0; attempt < ATTEMPTS; attempt += 1) {
|
|
66
|
+
line(asked(text));
|
|
67
|
+
listChoices(choices, [fallback]);
|
|
68
|
+
const hint = fallbackIndex < 0 ? '' : (0, output_1.paint)(`[${fallbackIndex + 1}]`, 'dim', color);
|
|
69
|
+
const raw = (await question(` ${hint} `)).trim();
|
|
70
|
+
if (raw.length === 0 && fallbackIndex >= 0)
|
|
71
|
+
return fallback;
|
|
72
|
+
const index = Number(raw);
|
|
73
|
+
if (Number.isInteger(index) && index >= 1 && index <= choices.length)
|
|
74
|
+
return choices[index - 1].value;
|
|
75
|
+
// Typing the answer out is what someone who has run this before will do. Either side counts:
|
|
76
|
+
// the value is what a second run remembers, the label is what is on screen.
|
|
77
|
+
const typed = raw.toLowerCase();
|
|
78
|
+
const named = choices.find((choice) => choice.value.toLowerCase() === typed || choice.label.toLowerCase() === typed);
|
|
79
|
+
if (named)
|
|
80
|
+
return named.value;
|
|
81
|
+
problem(`Pick a number from 1 to ${choices.length}.`);
|
|
82
|
+
}
|
|
83
|
+
return exhausted();
|
|
84
|
+
};
|
|
85
|
+
const multiSelect = async (text, choices, fallback) => {
|
|
86
|
+
if (choices.length === 0)
|
|
87
|
+
return [];
|
|
88
|
+
for (let attempt = 0; attempt < ATTEMPTS; attempt += 1) {
|
|
89
|
+
line(asked(text));
|
|
90
|
+
listChoices(choices, fallback);
|
|
91
|
+
line((0, output_1.paint)(' Numbers, comma separated. Enter keeps the marked ones; "none" picks nothing.', 'dim', color));
|
|
92
|
+
const raw = (await question(' ').then((answer) => answer.trim())).toLowerCase();
|
|
93
|
+
if (raw.length === 0)
|
|
94
|
+
return [...fallback];
|
|
95
|
+
if (raw === 'none')
|
|
96
|
+
return [];
|
|
97
|
+
const parts = raw.split(/[\s,]+/).filter((part) => part.length > 0);
|
|
98
|
+
const picked = [];
|
|
99
|
+
let bad;
|
|
100
|
+
for (const part of parts) {
|
|
101
|
+
const index = Number(part);
|
|
102
|
+
if (!Number.isInteger(index) || index < 1 || index > choices.length) {
|
|
103
|
+
bad = part;
|
|
104
|
+
break;
|
|
105
|
+
}
|
|
106
|
+
const value = choices[index - 1].value;
|
|
107
|
+
if (!picked.includes(value))
|
|
108
|
+
picked.push(value);
|
|
109
|
+
}
|
|
110
|
+
if (bad === undefined)
|
|
111
|
+
return picked;
|
|
112
|
+
problem(`"${bad}" is not one of 1 to ${choices.length}.`);
|
|
113
|
+
}
|
|
114
|
+
return exhausted();
|
|
115
|
+
};
|
|
116
|
+
const confirmPrompt = async (text, fallback) => {
|
|
117
|
+
const hint = (0, output_1.paint)(fallback ? '[Y/n]' : '[y/N]', 'dim', color);
|
|
118
|
+
for (let attempt = 0; attempt < ATTEMPTS; attempt += 1) {
|
|
119
|
+
const raw = (await question(`${asked(text)} ${hint} `)).trim();
|
|
120
|
+
if (raw.length === 0)
|
|
121
|
+
return fallback;
|
|
122
|
+
if (/^y(es)?$/i.test(raw))
|
|
123
|
+
return true;
|
|
124
|
+
if (/^no?$/i.test(raw))
|
|
125
|
+
return false;
|
|
126
|
+
problem('Answer y or n.');
|
|
127
|
+
}
|
|
128
|
+
return exhausted();
|
|
129
|
+
};
|
|
130
|
+
return { ask, select, multiSelect, confirm: confirmPrompt, close: () => rl.close() };
|
|
131
|
+
};
|
|
132
|
+
exports.createPrompter = createPrompter;
|
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The config-as-code files `get-started` writes.
|
|
3
|
+
*
|
|
4
|
+
* The wizard's output is a config directory, not a sequence of create calls. That is deliberate:
|
|
5
|
+
* the YAML is the thing we want someone to own and commit, `config apply` is idempotent so a
|
|
6
|
+
* second run is safe, and the whole flow then rides on one endpoint pair instead of six resource
|
|
7
|
+
* APIs. The wizard is disposable; the files are not.
|
|
8
|
+
*
|
|
9
|
+
* Everything here is pure - answers in, file contents out - so the shape of what we write is
|
|
10
|
+
* tested without a terminal or a network.
|
|
11
|
+
*/
|
|
12
|
+
/** Editor autocomplete and validation for anyone who opens these files afterwards. */
|
|
13
|
+
export declare const SCHEMA_HEADER = "# yaml-language-server: $schema=https://roark.ai/roark-config.schema.json";
|
|
14
|
+
/**
|
|
15
|
+
* A Roark-managed environment that exists in every project, so a first run needs no environment
|
|
16
|
+
* of its own. Flows reference an environment by its display name.
|
|
17
|
+
*/
|
|
18
|
+
export declare const DEFAULT_ENVIRONMENT = "Quiet line";
|
|
19
|
+
/** How long a simulated call may run before Roark ends it. */
|
|
20
|
+
export declare const DEFAULT_MAX_DURATION_SECONDS = 300;
|
|
21
|
+
/** The config DSL's local key: lowercase, and the same regex the server validates. */
|
|
22
|
+
export declare const NAME_PATTERN: RegExp;
|
|
23
|
+
/** E.164, which is what a PHONE endpoint's value has to be. */
|
|
24
|
+
export declare const PHONE_PATTERN: RegExp;
|
|
25
|
+
export type EndpointDirection = 'INCOMING' | 'OUTGOING' | 'INCOMING_AND_OUTGOING';
|
|
26
|
+
export interface EndpointSetup {
|
|
27
|
+
value: string;
|
|
28
|
+
direction: EndpointDirection;
|
|
29
|
+
}
|
|
30
|
+
export interface AgentSetup {
|
|
31
|
+
name: string;
|
|
32
|
+
/** The agent's name in Roark when it is not slug-shaped. Set when adopting an existing agent. */
|
|
33
|
+
displayName?: string;
|
|
34
|
+
/**
|
|
35
|
+
* Endpoints to declare. Left out when adopting an agent whose endpoints Roark already holds:
|
|
36
|
+
* an absent `endpoints` key leaves them untouched, where an empty list would detach every one.
|
|
37
|
+
*/
|
|
38
|
+
endpoints?: readonly EndpointSetup[];
|
|
39
|
+
/** The line the run dials. Absent when the agent has nothing reachable yet. */
|
|
40
|
+
dial?: EndpointSetup | {
|
|
41
|
+
direction: EndpointDirection;
|
|
42
|
+
};
|
|
43
|
+
}
|
|
44
|
+
export interface PersonaSetup {
|
|
45
|
+
name: string;
|
|
46
|
+
language: string;
|
|
47
|
+
accent: string;
|
|
48
|
+
gender: string;
|
|
49
|
+
}
|
|
50
|
+
export interface FlowSetup {
|
|
51
|
+
name: string;
|
|
52
|
+
/** What the caller is calling about, in their own terms. */
|
|
53
|
+
goal: string;
|
|
54
|
+
/** One thing the agent has to do for the call to count as a pass. */
|
|
55
|
+
expectation?: string;
|
|
56
|
+
}
|
|
57
|
+
export interface CustomMetricSetup {
|
|
58
|
+
name: string;
|
|
59
|
+
/** A yes/no question about the call, which becomes the grading prompt. */
|
|
60
|
+
question: string;
|
|
61
|
+
}
|
|
62
|
+
export interface PlanSetup {
|
|
63
|
+
name: string;
|
|
64
|
+
maxDurationSeconds: number;
|
|
65
|
+
}
|
|
66
|
+
export interface Setup {
|
|
67
|
+
agent: AgentSetup;
|
|
68
|
+
persona: PersonaSetup;
|
|
69
|
+
flow: FlowSetup;
|
|
70
|
+
/** Metric slugs the run is graded by: Roark's own, plus the custom one when there is one. */
|
|
71
|
+
metrics: readonly string[];
|
|
72
|
+
customMetric?: CustomMetricSetup;
|
|
73
|
+
/** Absent when there is no endpoint to dial, so there is nothing a plan could run against. */
|
|
74
|
+
plan?: PlanSetup;
|
|
75
|
+
}
|
|
76
|
+
export interface ScaffoldFile {
|
|
77
|
+
/** Relative to the config directory, always posix-style. */
|
|
78
|
+
path: string;
|
|
79
|
+
contents: string;
|
|
80
|
+
}
|
|
81
|
+
/** Best-effort config name from free text, so a name can be suggested rather than demanded. */
|
|
82
|
+
export declare const slugify: (text: string) => string;
|
|
83
|
+
/** `refund_policy_accuracy` -> `Refund Policy Accuracy`, for a readable display name. */
|
|
84
|
+
export declare const titleize: (name: string) => string;
|
|
85
|
+
/** A run is outbound only when the line it dials is outgoing-only; everything else is inbound. */
|
|
86
|
+
export declare const directionFor: (endpointDirection: EndpointDirection | undefined) => "INBOUND" | "OUTBOUND";
|
|
87
|
+
/** Which serialization the config is written in. The resources are the same either way. */
|
|
88
|
+
export type ConfigFormat = 'yaml' | 'ts';
|
|
89
|
+
export interface ResourceEntry {
|
|
90
|
+
/** The config `kind`, which the TypeScript helpers supply themselves. */
|
|
91
|
+
kind: string;
|
|
92
|
+
/** Where the YAML form puts it, relative to the config directory. */
|
|
93
|
+
path: string;
|
|
94
|
+
resource: Record<string, unknown>;
|
|
95
|
+
/** Comments to write above it. A few differ by format, because the escape hatches do. */
|
|
96
|
+
notes: string[];
|
|
97
|
+
}
|
|
98
|
+
/**
|
|
99
|
+
* Every resource this setup implies, in apply order (which is also a sensible reading order).
|
|
100
|
+
*
|
|
101
|
+
* Shared by both serializations, so the YAML and the TypeScript forms cannot describe different
|
|
102
|
+
* projects: they are the same objects, written two ways.
|
|
103
|
+
*/
|
|
104
|
+
export declare const resourcesFor: (setup: Setup, format?: ConfigFormat) => ResourceEntry[];
|
|
105
|
+
/** The YAML form: one file per resource, under the config directory. */
|
|
106
|
+
export declare const setupFiles: (setup: Setup) => ScaffoldFile[];
|
|
@@ -0,0 +1,184 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
/**
|
|
3
|
+
* The config-as-code files `get-started` writes.
|
|
4
|
+
*
|
|
5
|
+
* The wizard's output is a config directory, not a sequence of create calls. That is deliberate:
|
|
6
|
+
* the YAML is the thing we want someone to own and commit, `config apply` is idempotent so a
|
|
7
|
+
* second run is safe, and the whole flow then rides on one endpoint pair instead of six resource
|
|
8
|
+
* APIs. The wizard is disposable; the files are not.
|
|
9
|
+
*
|
|
10
|
+
* Everything here is pure - answers in, file contents out - so the shape of what we write is
|
|
11
|
+
* tested without a terminal or a network.
|
|
12
|
+
*/
|
|
13
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
14
|
+
exports.setupFiles = exports.resourcesFor = exports.directionFor = exports.titleize = exports.slugify = exports.PHONE_PATTERN = exports.NAME_PATTERN = exports.DEFAULT_MAX_DURATION_SECONDS = exports.DEFAULT_ENVIRONMENT = exports.SCHEMA_HEADER = void 0;
|
|
15
|
+
const yaml_1 = require("yaml");
|
|
16
|
+
/** Editor autocomplete and validation for anyone who opens these files afterwards. */
|
|
17
|
+
exports.SCHEMA_HEADER = '# yaml-language-server: $schema=https://roark.ai/roark-config.schema.json';
|
|
18
|
+
/**
|
|
19
|
+
* A Roark-managed environment that exists in every project, so a first run needs no environment
|
|
20
|
+
* of its own. Flows reference an environment by its display name.
|
|
21
|
+
*/
|
|
22
|
+
exports.DEFAULT_ENVIRONMENT = 'Quiet line';
|
|
23
|
+
/** How long a simulated call may run before Roark ends it. */
|
|
24
|
+
exports.DEFAULT_MAX_DURATION_SECONDS = 300;
|
|
25
|
+
/** The config DSL's local key: lowercase, and the same regex the server validates. */
|
|
26
|
+
exports.NAME_PATTERN = /^[a-z0-9][a-z0-9-_.]*$/;
|
|
27
|
+
/** E.164, which is what a PHONE endpoint's value has to be. */
|
|
28
|
+
exports.PHONE_PATTERN = /^\+[1-9]\d{6,14}$/;
|
|
29
|
+
/** Best-effort config name from free text, so a name can be suggested rather than demanded. */
|
|
30
|
+
const slugify = (text) => text
|
|
31
|
+
.toLowerCase()
|
|
32
|
+
.replace(/[^a-z0-9]+/g, '-')
|
|
33
|
+
.replace(/^-+|-+$/g, '')
|
|
34
|
+
.slice(0, 60);
|
|
35
|
+
exports.slugify = slugify;
|
|
36
|
+
/** `refund_policy_accuracy` -> `Refund Policy Accuracy`, for a readable display name. */
|
|
37
|
+
const titleize = (name) => name
|
|
38
|
+
.split(/[-_.]+/)
|
|
39
|
+
.filter((word) => word.length > 0)
|
|
40
|
+
.map((word) => `${word.charAt(0).toUpperCase()}${word.slice(1)}`)
|
|
41
|
+
.join(' ');
|
|
42
|
+
exports.titleize = titleize;
|
|
43
|
+
/** A run is outbound only when the line it dials is outgoing-only; everything else is inbound. */
|
|
44
|
+
const directionFor = (endpointDirection) => endpointDirection === 'OUTGOING' ? 'OUTBOUND' : 'INBOUND';
|
|
45
|
+
exports.directionFor = directionFor;
|
|
46
|
+
const document = (notes, resource) => [
|
|
47
|
+
exports.SCHEMA_HEADER,
|
|
48
|
+
...notes.map((note) => `# ${note}`),
|
|
49
|
+
'',
|
|
50
|
+
// No line wrapping: a folded prompt is valid YAML but miserable to edit.
|
|
51
|
+
(0, yaml_1.stringify)(resource, { lineWidth: 0 }),
|
|
52
|
+
].join('\n');
|
|
53
|
+
const agentEntry = (agent, format) => ({
|
|
54
|
+
kind: 'agent',
|
|
55
|
+
path: `agents/${agent.name}.yaml`,
|
|
56
|
+
notes: [
|
|
57
|
+
'The agent under test. Roark does not run it; this is how Roark reaches it.',
|
|
58
|
+
...(agent.endpoints === undefined ?
|
|
59
|
+
['Its endpoints live in Roark already, so they are not declared here.']
|
|
60
|
+
: format === 'ts' ?
|
|
61
|
+
["Add `prompt: readFileSync('./prompts/<name>.md', 'utf8')` to keep its system prompt here too."]
|
|
62
|
+
: ['Add `prompt: file://prompts/<name>.md` to keep its system prompt in git too.']),
|
|
63
|
+
],
|
|
64
|
+
resource: {
|
|
65
|
+
kind: 'agent',
|
|
66
|
+
name: agent.name,
|
|
67
|
+
...(agent.displayName === undefined ? {} : { displayName: agent.displayName }),
|
|
68
|
+
...(agent.endpoints === undefined ?
|
|
69
|
+
{}
|
|
70
|
+
: {
|
|
71
|
+
endpoints: agent.endpoints.map((endpoint) => ({
|
|
72
|
+
value: endpoint.value,
|
|
73
|
+
direction: endpoint.direction,
|
|
74
|
+
})),
|
|
75
|
+
}),
|
|
76
|
+
},
|
|
77
|
+
});
|
|
78
|
+
const personaEntry = (persona) => ({
|
|
79
|
+
kind: 'persona',
|
|
80
|
+
path: `personas/${persona.name}.yaml`,
|
|
81
|
+
notes: [
|
|
82
|
+
'The simulated caller. Everything else about them has a sensible default:',
|
|
83
|
+
'baseEmotion, speechPace, backgroundNoise, interruption and more.',
|
|
84
|
+
],
|
|
85
|
+
resource: {
|
|
86
|
+
kind: 'persona',
|
|
87
|
+
name: persona.name,
|
|
88
|
+
language: persona.language,
|
|
89
|
+
accent: persona.accent,
|
|
90
|
+
gender: persona.gender,
|
|
91
|
+
},
|
|
92
|
+
});
|
|
93
|
+
const flowEntry = (flow, agentName, personaName) => ({
|
|
94
|
+
kind: 'flow',
|
|
95
|
+
path: `flows/${flow.name}.yaml`,
|
|
96
|
+
notes: [
|
|
97
|
+
'What the call is about. `improv` means the caller is given a goal and talks freely;',
|
|
98
|
+
'a scripted flow is the other kind, for an exact turn-by-turn script.',
|
|
99
|
+
'Add `edgeCases` to test the same call going wrong in a specific way.',
|
|
100
|
+
],
|
|
101
|
+
resource: {
|
|
102
|
+
kind: 'flow',
|
|
103
|
+
type: 'improv',
|
|
104
|
+
name: flow.name,
|
|
105
|
+
agents: [agentName],
|
|
106
|
+
happyPath: {
|
|
107
|
+
persona: personaName,
|
|
108
|
+
environment: exports.DEFAULT_ENVIRONMENT,
|
|
109
|
+
prompt: flow.goal,
|
|
110
|
+
},
|
|
111
|
+
...(flow.expectation === undefined ? {} : { expectations: [flow.expectation] }),
|
|
112
|
+
},
|
|
113
|
+
});
|
|
114
|
+
const metricEntry = (metric) => ({
|
|
115
|
+
kind: 'metric',
|
|
116
|
+
path: `metrics/${metric.name}.yaml`,
|
|
117
|
+
notes: [
|
|
118
|
+
'A custom metric, graded by an LLM against the transcript.',
|
|
119
|
+
'`name` is the slug a plan references. `type` and `name` are fixed once created.',
|
|
120
|
+
],
|
|
121
|
+
resource: {
|
|
122
|
+
kind: 'metric',
|
|
123
|
+
name: metric.name,
|
|
124
|
+
displayName: (0, exports.titleize)(metric.name).slice(0, 100),
|
|
125
|
+
type: 'BOOLEAN',
|
|
126
|
+
// The grading prompt has to reference a transcript source and the world context, so the
|
|
127
|
+
// question is wrapped rather than used raw: a prompt that names neither is rejected.
|
|
128
|
+
prompt: `Using {{transcript}} and {{world_context}}, ${metric.question}`,
|
|
129
|
+
trueLabel: 'Yes',
|
|
130
|
+
falseLabel: 'No',
|
|
131
|
+
},
|
|
132
|
+
});
|
|
133
|
+
const planEntry = (setup, plan) => {
|
|
134
|
+
const dial = setup.agent.dial;
|
|
135
|
+
// The line is named only when it could be ambiguous. An agent whose config declares exactly one
|
|
136
|
+
// endpoint has nothing to disambiguate, and naming it there would mean the same number lived in
|
|
137
|
+
// two places that could drift apart. An adopted agent is the other case: Roark may hold several
|
|
138
|
+
// endpoints for it, and apply refuses to guess rather than dial the wrong one.
|
|
139
|
+
const declaresOneEndpoint = setup.agent.endpoints?.length === 1;
|
|
140
|
+
const value = !declaresOneEndpoint && dial !== undefined && 'value' in dial ? dial.value : undefined;
|
|
141
|
+
return {
|
|
142
|
+
kind: 'simulationPlan',
|
|
143
|
+
path: `simulation-plans/${plan.name}.yaml`,
|
|
144
|
+
notes: [
|
|
145
|
+
'The saved run: which line to call, which flows to run, and what grades them.',
|
|
146
|
+
'Applying this declares the plan. Starting a run is a separate, deliberate step.',
|
|
147
|
+
'Add `schedule` to run it on a cadence, or `iterations` to run each case more than once.',
|
|
148
|
+
],
|
|
149
|
+
resource: {
|
|
150
|
+
kind: 'simulationPlan',
|
|
151
|
+
name: plan.name,
|
|
152
|
+
direction: (0, exports.directionFor)(dial?.direction),
|
|
153
|
+
agentEndpoints: [
|
|
154
|
+
{
|
|
155
|
+
agent: setup.agent.name,
|
|
156
|
+
...(value === undefined ? {} : { value, direction: dial?.direction }),
|
|
157
|
+
},
|
|
158
|
+
],
|
|
159
|
+
metrics: [...setup.metrics],
|
|
160
|
+
flows: [{ flow: setup.flow.name }],
|
|
161
|
+
maxDurationSeconds: plan.maxDurationSeconds,
|
|
162
|
+
},
|
|
163
|
+
};
|
|
164
|
+
};
|
|
165
|
+
/**
|
|
166
|
+
* Every resource this setup implies, in apply order (which is also a sensible reading order).
|
|
167
|
+
*
|
|
168
|
+
* Shared by both serializations, so the YAML and the TypeScript forms cannot describe different
|
|
169
|
+
* projects: they are the same objects, written two ways.
|
|
170
|
+
*/
|
|
171
|
+
const resourcesFor = (setup, format = 'yaml') => [
|
|
172
|
+
...(setup.customMetric === undefined ? [] : [metricEntry(setup.customMetric)]),
|
|
173
|
+
personaEntry(setup.persona),
|
|
174
|
+
agentEntry(setup.agent, format),
|
|
175
|
+
flowEntry(setup.flow, setup.agent.name, setup.persona.name),
|
|
176
|
+
...(setup.plan === undefined ? [] : [planEntry(setup, setup.plan)]),
|
|
177
|
+
];
|
|
178
|
+
exports.resourcesFor = resourcesFor;
|
|
179
|
+
/** The YAML form: one file per resource, under the config directory. */
|
|
180
|
+
const setupFiles = (setup) => (0, exports.resourcesFor)(setup, 'yaml').map((entry) => ({
|
|
181
|
+
path: entry.path,
|
|
182
|
+
contents: document(entry.notes, entry.resource),
|
|
183
|
+
}));
|
|
184
|
+
exports.setupFiles = setupFiles;
|