webhand 0.0.0-stage → 0.2.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/LICENSE +21 -0
- package/README.md +252 -2
- package/THIRD_PARTY_LICENSE_jev-ultrafast.txt +21 -0
- package/assets/recorder.js +113 -0
- package/assets/snapshot.js +556 -0
- package/dist/agent.js +183 -0
- package/dist/bin.js +22 -0
- package/dist/browser.js +236 -0
- package/dist/cli.js +1144 -0
- package/dist/learn.js +79 -0
- package/dist/metrics.js +64 -0
- package/dist/policies/base.js +178 -0
- package/dist/policies/jev.js +198 -0
- package/dist/policies/scripted.js +48 -0
- package/dist/py.js +141 -0
- package/dist/run.js +80 -0
- package/dist/runbook.js +286 -0
- package/dist/session.js +331 -0
- package/dist/tasks.js +37 -0
- package/dist/types.js +34 -0
- package/dist/workspace.js +78 -0
- package/package.json +57 -4
package/dist/py.js
ADDED
|
@@ -0,0 +1,141 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Python-compatible formatting. What the CLI prints is measured (handoff chars) and read by Claude,
|
|
3
|
+
* so it stays exactly as the Python implementation printed it.
|
|
4
|
+
*/
|
|
5
|
+
// Python's str.isprintable() is false for these: other (Cc, Cf, Cs, Co, Cn) and separators except the space.
|
|
6
|
+
const NOT_PRINTABLE = /[\p{C}\p{Z}]/u;
|
|
7
|
+
function escapeChar(char, quote) {
|
|
8
|
+
if (char === "\\")
|
|
9
|
+
return "\\\\";
|
|
10
|
+
if (char === quote)
|
|
11
|
+
return `\\${quote}`;
|
|
12
|
+
if (char === "\n")
|
|
13
|
+
return "\\n";
|
|
14
|
+
if (char === "\r")
|
|
15
|
+
return "\\r";
|
|
16
|
+
if (char === "\t")
|
|
17
|
+
return "\\t";
|
|
18
|
+
if (char !== " " && NOT_PRINTABLE.test(char)) {
|
|
19
|
+
const code = char.codePointAt(0) ?? 0;
|
|
20
|
+
if (code < 0x100)
|
|
21
|
+
return `\\x${code.toString(16).padStart(2, "0")}`;
|
|
22
|
+
if (code < 0x10000)
|
|
23
|
+
return `\\u${code.toString(16).padStart(4, "0")}`;
|
|
24
|
+
return `\\U${code.toString(16).padStart(8, "0")}`;
|
|
25
|
+
}
|
|
26
|
+
return char;
|
|
27
|
+
}
|
|
28
|
+
function reprString(text) {
|
|
29
|
+
const quote = text.includes("'") && !text.includes('"') ? '"' : "'";
|
|
30
|
+
let body = "";
|
|
31
|
+
for (const char of text)
|
|
32
|
+
body += escapeChar(char, quote);
|
|
33
|
+
return quote + body + quote;
|
|
34
|
+
}
|
|
35
|
+
function reprNumber(value) {
|
|
36
|
+
if (Number.isNaN(value))
|
|
37
|
+
return "nan";
|
|
38
|
+
if (!Number.isFinite(value))
|
|
39
|
+
return value > 0 ? "inf" : "-inf";
|
|
40
|
+
return String(value);
|
|
41
|
+
}
|
|
42
|
+
/** repr() of a JSON-like value. */
|
|
43
|
+
export function pyRepr(value) {
|
|
44
|
+
if (value === null || value === undefined)
|
|
45
|
+
return "None";
|
|
46
|
+
if (value === true)
|
|
47
|
+
return "True";
|
|
48
|
+
if (value === false)
|
|
49
|
+
return "False";
|
|
50
|
+
if (typeof value === "string")
|
|
51
|
+
return reprString(value);
|
|
52
|
+
if (typeof value === "number")
|
|
53
|
+
return reprNumber(value);
|
|
54
|
+
if (Array.isArray(value))
|
|
55
|
+
return `[${value.map(pyRepr).join(", ")}]`;
|
|
56
|
+
if (value instanceof Map) {
|
|
57
|
+
return `{${[...value].map(([k, v]) => `${pyRepr(k)}: ${pyRepr(v)}`).join(", ")}}`;
|
|
58
|
+
}
|
|
59
|
+
if (typeof value === "object") {
|
|
60
|
+
return `{${Object.entries(value)
|
|
61
|
+
.map(([k, v]) => `${pyRepr(k)}: ${pyRepr(v)}`)
|
|
62
|
+
.join(", ")}}`;
|
|
63
|
+
}
|
|
64
|
+
return String(value);
|
|
65
|
+
}
|
|
66
|
+
/** str() of a JSON-like value, as an f-string prints it. */
|
|
67
|
+
export function pyStr(value) {
|
|
68
|
+
if (typeof value === "string")
|
|
69
|
+
return value;
|
|
70
|
+
return pyRepr(value);
|
|
71
|
+
}
|
|
72
|
+
/**
|
|
73
|
+
* json.dumps(value, ensure_ascii=False). Maps keep their order, which a plain object would not keep
|
|
74
|
+
* for keys like "2" and "1". compact gives the separators httpx uses for a request body.
|
|
75
|
+
*/
|
|
76
|
+
export function pyJson(value, compact = false) {
|
|
77
|
+
const comma = compact ? "," : ", ";
|
|
78
|
+
const colon = compact ? ":" : ": ";
|
|
79
|
+
const encode = (item) => {
|
|
80
|
+
if (item === null || item === undefined)
|
|
81
|
+
return "null";
|
|
82
|
+
if (typeof item === "number")
|
|
83
|
+
return Number.isFinite(item) ? JSON.stringify(item) : "null";
|
|
84
|
+
if (typeof item === "string" || typeof item === "boolean")
|
|
85
|
+
return JSON.stringify(item);
|
|
86
|
+
if (Array.isArray(item))
|
|
87
|
+
return `[${item.map(encode).join(comma)}]`;
|
|
88
|
+
const entries = item instanceof Map ? [...item] : Object.entries(item);
|
|
89
|
+
return `{${entries
|
|
90
|
+
.filter(([, v]) => v !== undefined)
|
|
91
|
+
.map(([k, v]) => `${JSON.stringify(String(k))}${colon}${encode(v)}`)
|
|
92
|
+
.join(comma)}}`;
|
|
93
|
+
};
|
|
94
|
+
return encode(value);
|
|
95
|
+
}
|
|
96
|
+
/** round() to an int: halves go to the even neighbour. */
|
|
97
|
+
export function pyRound(value) {
|
|
98
|
+
const floor = Math.floor(value);
|
|
99
|
+
const diff = value - floor;
|
|
100
|
+
if (diff > 0.5)
|
|
101
|
+
return floor + 1;
|
|
102
|
+
if (diff < 0.5)
|
|
103
|
+
return floor;
|
|
104
|
+
return floor % 2 === 0 ? floor : floor + 1;
|
|
105
|
+
}
|
|
106
|
+
/** Python truthiness: None, False, 0, "", [] and {} are false. */
|
|
107
|
+
export function pyTruthy(value) {
|
|
108
|
+
if (value === null || value === undefined || value === false || value === 0 || value === "")
|
|
109
|
+
return false;
|
|
110
|
+
if (Array.isArray(value))
|
|
111
|
+
return value.length > 0;
|
|
112
|
+
if (value instanceof Map)
|
|
113
|
+
return value.size > 0;
|
|
114
|
+
if (typeof value === "object")
|
|
115
|
+
return Object.keys(value).length > 0;
|
|
116
|
+
return true;
|
|
117
|
+
}
|
|
118
|
+
/** time.strftime("%Y%m%dT%H%M%S") in local time. */
|
|
119
|
+
export function stamp(date = new Date()) {
|
|
120
|
+
const pad = (n) => String(n).padStart(2, "0");
|
|
121
|
+
return (`${date.getFullYear()}${pad(date.getMonth() + 1)}${pad(date.getDate())}` +
|
|
122
|
+
`T${pad(date.getHours())}${pad(date.getMinutes())}${pad(date.getSeconds())}`);
|
|
123
|
+
}
|
|
124
|
+
/** datetime.now(timezone.utc).isoformat(). */
|
|
125
|
+
export function utcIso(date = new Date()) {
|
|
126
|
+
return `${date.toISOString().slice(0, 23)}000+00:00`;
|
|
127
|
+
}
|
|
128
|
+
/** The length Python reports for a str: code points, not UTF-16 units. */
|
|
129
|
+
export function pyLen(text) {
|
|
130
|
+
let count = 0;
|
|
131
|
+
for (const _ of text)
|
|
132
|
+
count++;
|
|
133
|
+
return count;
|
|
134
|
+
}
|
|
135
|
+
/** type(error).__name__: error, as Python formats an exception for a log. */
|
|
136
|
+
export function describeError(error) {
|
|
137
|
+
if (error instanceof Error)
|
|
138
|
+
return `${error.name}: ${error.message}`;
|
|
139
|
+
return `Error: ${String(error)}`;
|
|
140
|
+
}
|
|
141
|
+
export const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
|
package/dist/run.js
ADDED
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
/** Harness smoke test: the fixed script, no model. Agent runs go through the webhand CLI. */
|
|
2
|
+
import { join } from "node:path";
|
|
3
|
+
import { parseArgs } from "node:util";
|
|
4
|
+
import { Budget, GOAL_REPORTED, runAgent } from "./agent.js";
|
|
5
|
+
import { Browser } from "./browser.js";
|
|
6
|
+
import { gitState, Recorder, summarize } from "./metrics.js";
|
|
7
|
+
import { ScriptedPolicy } from "./policies/scripted.js";
|
|
8
|
+
import { describeError, pyStr, stamp, utcIso } from "./py.js";
|
|
9
|
+
import { loadTask } from "./tasks.js";
|
|
10
|
+
const ROOT = process.cwd();
|
|
11
|
+
async function runOnce(taskName, task, repeat, folder, options) {
|
|
12
|
+
const recorder = new Recorder(join(folder, `${taskName}-scripted-${repeat}.jsonl`));
|
|
13
|
+
let browser = null;
|
|
14
|
+
let result = { status: "error", reason: null };
|
|
15
|
+
let verdict = { success: false, evidence: null };
|
|
16
|
+
try {
|
|
17
|
+
const policy = new ScriptedPolicy(task.SCRIPT);
|
|
18
|
+
browser = await Browser.open(task.startUrl(ROOT), { headless: !options.headed });
|
|
19
|
+
recorder.event("run_start", {
|
|
20
|
+
task: taskName,
|
|
21
|
+
goal: task.GOAL,
|
|
22
|
+
policy: "scripted",
|
|
23
|
+
repeat,
|
|
24
|
+
config: policy.config(),
|
|
25
|
+
chrome: browser.version,
|
|
26
|
+
git: gitState(),
|
|
27
|
+
started_at: utcIso(),
|
|
28
|
+
});
|
|
29
|
+
const plan = { goal: task.GOAL, steps: [], values: [] };
|
|
30
|
+
const { page: _page, ...outcome } = await runAgent(browser, policy, plan, recorder, new Budget(options.maxActions, options.maxDecisions));
|
|
31
|
+
result = { ...outcome, status: outcome.outcome === GOAL_REPORTED ? "done" : "blocked" };
|
|
32
|
+
verdict = await task.verify(browser);
|
|
33
|
+
}
|
|
34
|
+
catch (error) {
|
|
35
|
+
// A failed run is data: keep it and move to the next one.
|
|
36
|
+
result = { ...result, reason: describeError(error) };
|
|
37
|
+
}
|
|
38
|
+
finally {
|
|
39
|
+
await browser?.close();
|
|
40
|
+
}
|
|
41
|
+
const summary = summarize(recorder.calls);
|
|
42
|
+
recorder.event("run_end", { ...result, verified: verdict.success, evidence: verdict.evidence, ...summary });
|
|
43
|
+
recorder.close();
|
|
44
|
+
const reason = result.reason || result.detail || null;
|
|
45
|
+
console.log(`${taskName}#${repeat}: ${result.status} verified=${pyStr(verdict.success)} reason=${pyStr(reason)}`);
|
|
46
|
+
return verdict.success === true;
|
|
47
|
+
}
|
|
48
|
+
export async function main(argv = process.argv.slice(2)) {
|
|
49
|
+
const { values } = parseArgs({
|
|
50
|
+
args: argv,
|
|
51
|
+
options: {
|
|
52
|
+
task: { type: "string" },
|
|
53
|
+
repeat: { type: "string", default: "1" },
|
|
54
|
+
headed: { type: "boolean", default: false },
|
|
55
|
+
"max-actions": { type: "string", default: String(Budget.MAX_ACTIONS) },
|
|
56
|
+
"max-decisions": { type: "string", default: String(Budget.MAX_DECISIONS) },
|
|
57
|
+
},
|
|
58
|
+
});
|
|
59
|
+
if (!values.task)
|
|
60
|
+
throw new Error("--task is required");
|
|
61
|
+
const task = await loadTask(values.task);
|
|
62
|
+
const folder = join(ROOT, "runs", stamp());
|
|
63
|
+
const options = {
|
|
64
|
+
headed: values.headed ?? false,
|
|
65
|
+
maxActions: Number(values["max-actions"]),
|
|
66
|
+
maxDecisions: Number(values["max-decisions"]),
|
|
67
|
+
};
|
|
68
|
+
const passed = [];
|
|
69
|
+
for (let repeat = 1; repeat <= Number(values.repeat); repeat++) {
|
|
70
|
+
passed.push(await runOnce(values.task, task, repeat, folder, options));
|
|
71
|
+
}
|
|
72
|
+
console.log(`${passed.filter(Boolean).length}/${passed.length} verified. Logs: ${folder}`);
|
|
73
|
+
return passed.every(Boolean) ? 0 : 1;
|
|
74
|
+
}
|
|
75
|
+
if (import.meta.url === `file://${process.argv[1]}`) {
|
|
76
|
+
main().then((code) => process.exit(code), (error) => {
|
|
77
|
+
console.error(error instanceof Error ? error.message : error);
|
|
78
|
+
process.exit(1);
|
|
79
|
+
});
|
|
80
|
+
}
|
package/dist/runbook.js
ADDED
|
@@ -0,0 +1,286 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What webhand has learned: service information and reviewed procedures (runbooks).
|
|
3
|
+
*
|
|
4
|
+
* Both guide Claude's plan and Jev's choices. Procedures are never replayed. They live in the project's
|
|
5
|
+
* .webhand/runbooks and the user's ~/.webhand/runbooks; a project file wins over a user file of the same name.
|
|
6
|
+
*/
|
|
7
|
+
import { createHash } from "node:crypto";
|
|
8
|
+
import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
|
|
9
|
+
import { dirname, join, resolve } from "node:path";
|
|
10
|
+
import { pathToFileURL } from "node:url";
|
|
11
|
+
import { parse } from "smol-toml";
|
|
12
|
+
import { pyRepr, pyStr, pyTruthy } from "./py.js";
|
|
13
|
+
import { roots, scopeRoot } from "./workspace.js";
|
|
14
|
+
const WORD = "[\\p{L}\\p{N}_-]+";
|
|
15
|
+
const NAME = new RegExp(`^${WORD}(/${WORD})?$`, "u");
|
|
16
|
+
const SERVICE_NAME = new RegExp(`^${WORD}$`, "u");
|
|
17
|
+
const PARAM = /\{([A-Za-z_][\p{L}\p{N}_]*)\}/gu;
|
|
18
|
+
const ACTORS = new Set(["jev", "human"]);
|
|
19
|
+
const STATUSES = new Set(["draft", "approved"]);
|
|
20
|
+
const DEFAULTS = new Set(["focus", "skip"]); // A region's default in service.toml. Without one, it is observed as usual.
|
|
21
|
+
const SERVICE_FILE = "service"; // runbooks/<service>/service.toml holds the service information.
|
|
22
|
+
/** The runbook folder of a scope, whether or not it exists. */
|
|
23
|
+
export function root(scope = "project") {
|
|
24
|
+
return join(scopeRoot(scope), "runbooks");
|
|
25
|
+
}
|
|
26
|
+
/** Runbook folders that exist or may exist, project first. */
|
|
27
|
+
function folders() {
|
|
28
|
+
return roots().map(({ scope, dir }) => ({ scope, dir: join(dir, "runbooks") }));
|
|
29
|
+
}
|
|
30
|
+
/** The runbook cannot be used as written. */
|
|
31
|
+
export class RunbookError extends Error {
|
|
32
|
+
name = "RunbookError";
|
|
33
|
+
}
|
|
34
|
+
/** Checks a runbook name such as hotel/filter. */
|
|
35
|
+
function checkName(name) {
|
|
36
|
+
if (!NAME.test(name) || name.split("/").at(-1) === SERVICE_FILE) {
|
|
37
|
+
throw new RunbookError(`Invalid runbook name: ${pyRepr(name)}`);
|
|
38
|
+
}
|
|
39
|
+
return name;
|
|
40
|
+
}
|
|
41
|
+
function checkService(service) {
|
|
42
|
+
if (!SERVICE_NAME.test(service))
|
|
43
|
+
throw new RunbookError(`Invalid service name: ${pyRepr(service)}`);
|
|
44
|
+
return service;
|
|
45
|
+
}
|
|
46
|
+
/** Where a runbook of a scope is written. */
|
|
47
|
+
export function path(name, scope = "project") {
|
|
48
|
+
return join(root(scope), `${checkName(name)}.toml`);
|
|
49
|
+
}
|
|
50
|
+
/** Where a service's information of a scope is written. */
|
|
51
|
+
export function servicePath(service, scope = "project") {
|
|
52
|
+
return join(root(scope), checkService(service), `${SERVICE_FILE}.toml`);
|
|
53
|
+
}
|
|
54
|
+
function isFile(file) {
|
|
55
|
+
try {
|
|
56
|
+
return statSync(file).isFile();
|
|
57
|
+
}
|
|
58
|
+
catch {
|
|
59
|
+
return false;
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
/** The file that is read for a relative name: the project's if it has one, else the user's. */
|
|
63
|
+
function find(relative) {
|
|
64
|
+
for (const { scope, dir } of folders()) {
|
|
65
|
+
const file = join(dir, relative);
|
|
66
|
+
if (isFile(file))
|
|
67
|
+
return { file, scope, base: dirname(dirname(dir)) };
|
|
68
|
+
}
|
|
69
|
+
return null;
|
|
70
|
+
}
|
|
71
|
+
function findRunbook(name) {
|
|
72
|
+
return find(`${checkName(name)}.toml`);
|
|
73
|
+
}
|
|
74
|
+
function findService(service) {
|
|
75
|
+
return find(join(checkService(service), `${SERVICE_FILE}.toml`));
|
|
76
|
+
}
|
|
77
|
+
function readToml(file) {
|
|
78
|
+
const raw = readFileSync(file);
|
|
79
|
+
try {
|
|
80
|
+
return { raw, data: parse(new TextDecoder("utf-8", { fatal: true }).decode(raw)) };
|
|
81
|
+
}
|
|
82
|
+
catch (error) {
|
|
83
|
+
throw new RunbookError(`${file}: ${error instanceof Error ? error.message : String(error)}`);
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
const get = (doc, key, fallback = undefined) => (key in doc ? doc[key] : fallback);
|
|
87
|
+
/** Region patterns, such as "main/form:宿泊予約" or "footer". Anything else is an error. */
|
|
88
|
+
function patterns(file, where, value) {
|
|
89
|
+
if (value === null || value === undefined)
|
|
90
|
+
return [];
|
|
91
|
+
if (!Array.isArray(value) || !value.every((item) => typeof item === "string" && item.trim())) {
|
|
92
|
+
throw new RunbookError(`${file}: ${where} must be a list of region keys`);
|
|
93
|
+
}
|
|
94
|
+
return value.map((item) => item.trim());
|
|
95
|
+
}
|
|
96
|
+
function regions(file, page) {
|
|
97
|
+
const found = [];
|
|
98
|
+
for (const region of get(page, "regions", [])) {
|
|
99
|
+
const raw = get(region, "key");
|
|
100
|
+
const key = patterns(file, "pages.regions.key", raw !== undefined && raw !== null ? [raw] : null);
|
|
101
|
+
if (!key.length)
|
|
102
|
+
throw new RunbookError(`${file}: a region on ${get(page, "url", "?")} has no key`);
|
|
103
|
+
const fallback = get(region, "default", null);
|
|
104
|
+
if (fallback !== null && !DEFAULTS.has(fallback)) {
|
|
105
|
+
throw new RunbookError(`${file}: region ${pyRepr(key[0])} has unknown default ${pyRepr(fallback)}`);
|
|
106
|
+
}
|
|
107
|
+
found.push({ key: key[0], purpose: get(region, "purpose", ""), default: fallback });
|
|
108
|
+
}
|
|
109
|
+
return found;
|
|
110
|
+
}
|
|
111
|
+
/**
|
|
112
|
+
* Combines region choices. A later layer wins: learned defaults, then the runbook, then Claude.
|
|
113
|
+
* Focus patterns keep the later layer's order first, since the first focus is shown first.
|
|
114
|
+
*/
|
|
115
|
+
export function view(...layers) {
|
|
116
|
+
let focus = [];
|
|
117
|
+
let skip = [];
|
|
118
|
+
for (const layer of layers) {
|
|
119
|
+
if (!pyTruthy(layer))
|
|
120
|
+
continue;
|
|
121
|
+
const newFocus = [...(layer?.focus ?? [])];
|
|
122
|
+
const newSkip = [...(layer?.skip ?? [])];
|
|
123
|
+
const kept = (p) => !newFocus.includes(p) && !newSkip.includes(p);
|
|
124
|
+
focus = [...newFocus, ...focus.filter(kept)];
|
|
125
|
+
skip = [...skip.filter(kept), ...newSkip];
|
|
126
|
+
}
|
|
127
|
+
return { focus, skip };
|
|
128
|
+
}
|
|
129
|
+
/** What the service information says to focus on or skip on every page. */
|
|
130
|
+
export function serviceView(info) {
|
|
131
|
+
const keys = (info?.pages ?? []).flatMap((page) => page.regions);
|
|
132
|
+
return {
|
|
133
|
+
focus: keys.filter((r) => r.default === "focus").map((r) => r.key),
|
|
134
|
+
skip: keys.filter((r) => r.default === "skip").map((r) => r.key),
|
|
135
|
+
};
|
|
136
|
+
}
|
|
137
|
+
/** Service information for Claude's plan and Jev's state. null when nothing was learned. */
|
|
138
|
+
export function loadService(service) {
|
|
139
|
+
const found = findService(service);
|
|
140
|
+
if (!found)
|
|
141
|
+
return null;
|
|
142
|
+
const { file, scope } = found;
|
|
143
|
+
const { data } = readToml(file);
|
|
144
|
+
const missing = ["service", "description", "base_url", "sources"].filter((key) => !pyTruthy(data[key]));
|
|
145
|
+
if (missing.length)
|
|
146
|
+
throw new RunbookError(`${file}: missing ${missing.join(", ")}`);
|
|
147
|
+
const login = get(data, "login", {});
|
|
148
|
+
return {
|
|
149
|
+
service: data.service,
|
|
150
|
+
description: String(data.description).trim(),
|
|
151
|
+
base_url: data.base_url,
|
|
152
|
+
login: { required: pyTruthy(get(login, "required")), url: get(login, "url", null) },
|
|
153
|
+
pages: get(data, "pages", []).map((p) => ({
|
|
154
|
+
url: get(p, "url", ""),
|
|
155
|
+
purpose: get(p, "purpose", ""),
|
|
156
|
+
regions: regions(file, p),
|
|
157
|
+
})),
|
|
158
|
+
facts: get(data, "facts", []).map(pyStr),
|
|
159
|
+
scope,
|
|
160
|
+
};
|
|
161
|
+
}
|
|
162
|
+
function subfolders(dir) {
|
|
163
|
+
if (!existsSync(dir))
|
|
164
|
+
return [];
|
|
165
|
+
return readdirSync(dir, { withFileTypes: true })
|
|
166
|
+
.filter((entry) => entry.isDirectory())
|
|
167
|
+
.map((entry) => entry.name);
|
|
168
|
+
}
|
|
169
|
+
/** Everything learned in both scopes, without filling parameters. Claude reads this to plan. */
|
|
170
|
+
export function catalog() {
|
|
171
|
+
const services = [...new Set(folders().flatMap(({ dir }) => subfolders(dir)))].sort();
|
|
172
|
+
return services.map((service) => {
|
|
173
|
+
const info = loadService(service);
|
|
174
|
+
const names = new Set();
|
|
175
|
+
for (const { dir } of folders()) {
|
|
176
|
+
const folder = join(dir, service);
|
|
177
|
+
if (!existsSync(folder))
|
|
178
|
+
continue;
|
|
179
|
+
for (const file of readdirSync(folder)) {
|
|
180
|
+
if (file.endsWith(".toml") && file !== `${SERVICE_FILE}.toml` && isFile(join(folder, file))) {
|
|
181
|
+
names.add(file.slice(0, -".toml".length));
|
|
182
|
+
}
|
|
183
|
+
}
|
|
184
|
+
}
|
|
185
|
+
const procedures = [...names].sort().map((stem) => {
|
|
186
|
+
const found = find(join(service, `${stem}.toml`));
|
|
187
|
+
if (!found)
|
|
188
|
+
throw new RunbookError(`${service}/${stem} disappeared while reading`);
|
|
189
|
+
const { data } = readToml(found.file);
|
|
190
|
+
return {
|
|
191
|
+
name: `${service}/${stem}`,
|
|
192
|
+
scope: found.scope,
|
|
193
|
+
status: get(data, "status", null),
|
|
194
|
+
goal: get(data, "goal", null),
|
|
195
|
+
start_url: get(data, "start_url", null),
|
|
196
|
+
params: Object.fromEntries(Object.entries(get(data, "params", {})).map(([k, v]) => [k, get(v, "description", "")])),
|
|
197
|
+
human_steps: get(data, "steps", []).filter((s) => get(s, "actor") === "human").length,
|
|
198
|
+
focus: get(data, "focus", []),
|
|
199
|
+
skip: get(data, "skip", []),
|
|
200
|
+
};
|
|
201
|
+
});
|
|
202
|
+
return { service, info, procedures };
|
|
203
|
+
});
|
|
204
|
+
}
|
|
205
|
+
export function parseValues(pairs) {
|
|
206
|
+
const values = {};
|
|
207
|
+
for (const pair of pairs) {
|
|
208
|
+
const at = pair.indexOf("=");
|
|
209
|
+
if (at <= 0)
|
|
210
|
+
throw new RunbookError(`Expected KEY=VALUE, got ${pyRepr(pair)}`);
|
|
211
|
+
values[pair.slice(0, at)] = pair.slice(at + 1);
|
|
212
|
+
}
|
|
213
|
+
return values;
|
|
214
|
+
}
|
|
215
|
+
/** A URL without a scheme is a local file, relative to base (the folder that holds the scope's .webhand). */
|
|
216
|
+
export function resolveUrl(url, base = process.cwd()) {
|
|
217
|
+
if (/^[A-Za-z][A-Za-z0-9+.-]*:/.test(url))
|
|
218
|
+
return url;
|
|
219
|
+
const hash = url.indexOf("#");
|
|
220
|
+
const withoutFragment = hash >= 0 ? url.slice(0, hash) : url;
|
|
221
|
+
const at = withoutFragment.indexOf("?");
|
|
222
|
+
const local = at >= 0 ? withoutFragment.slice(0, at) : withoutFragment;
|
|
223
|
+
const query = at >= 0 ? withoutFragment.slice(at + 1) : "";
|
|
224
|
+
const file = resolve(base, local);
|
|
225
|
+
if (!isFile(file))
|
|
226
|
+
throw new RunbookError(`start_url file not found: ${local}`);
|
|
227
|
+
return pathToFileURL(file).href + (query ? `?${query}` : "");
|
|
228
|
+
}
|
|
229
|
+
/** Validates a runbook and fills in its parameters. Every problem is an error, not a guess. */
|
|
230
|
+
export function load(name, values = {}) {
|
|
231
|
+
const found = findRunbook(name);
|
|
232
|
+
if (!found)
|
|
233
|
+
throw new RunbookError(`Unknown runbook: ${name}`);
|
|
234
|
+
return loadFile(found.file, name, found.scope, values, found.base);
|
|
235
|
+
}
|
|
236
|
+
export function loadFile(file, name, scope, values = {}, base = process.cwd()) {
|
|
237
|
+
const { raw, data } = readToml(file);
|
|
238
|
+
const required = ["service", "name", "goal", "start_url", "status", "sources", "steps"];
|
|
239
|
+
const missing = required.filter((key) => !pyTruthy(data[key]));
|
|
240
|
+
if (missing.length)
|
|
241
|
+
throw new RunbookError(`${file}: missing ${missing.join(", ")}`);
|
|
242
|
+
if (!STATUSES.has(data.status))
|
|
243
|
+
throw new RunbookError(`${file}: unknown status ${pyRepr(data.status)}`);
|
|
244
|
+
const declared = get(data, "params", {});
|
|
245
|
+
const unknown = Object.keys(values)
|
|
246
|
+
.filter((key) => !(key in declared))
|
|
247
|
+
.sort();
|
|
248
|
+
if (unknown.length)
|
|
249
|
+
throw new RunbookError(`${file}: unknown parameters ${pyRepr(unknown)}`);
|
|
250
|
+
const filled = {};
|
|
251
|
+
for (const [key, spec] of Object.entries(declared))
|
|
252
|
+
filled[key] = key in values ? values[key] : get(spec, "default");
|
|
253
|
+
const fill = (text) => String(text).replace(PARAM, (_match, param) => {
|
|
254
|
+
const value = filled[param];
|
|
255
|
+
if (value === null || value === undefined) {
|
|
256
|
+
throw new RunbookError(`${file}: parameter ${pyRepr(param)} has no value. Pass --param ${param}=VALUE`);
|
|
257
|
+
}
|
|
258
|
+
return pyStr(value);
|
|
259
|
+
});
|
|
260
|
+
const steps = data.steps.map((step, i) => {
|
|
261
|
+
const number = i + 1;
|
|
262
|
+
const actor = get(step, "actor", "jev");
|
|
263
|
+
if (!ACTORS.has(actor))
|
|
264
|
+
throw new RunbookError(`${file}: step ${number} has unknown actor ${pyRepr(actor)}`);
|
|
265
|
+
if (!pyTruthy(step.instruction))
|
|
266
|
+
throw new RunbookError(`${file}: step ${number} has no instruction`);
|
|
267
|
+
return {
|
|
268
|
+
actor,
|
|
269
|
+
instruction: fill(step.instruction),
|
|
270
|
+
hints: get(step, "hints", []).map(fill),
|
|
271
|
+
done_when: pyTruthy(step.done_when) ? fill(step.done_when) : null,
|
|
272
|
+
};
|
|
273
|
+
});
|
|
274
|
+
return {
|
|
275
|
+
name,
|
|
276
|
+
scope,
|
|
277
|
+
service: data.service,
|
|
278
|
+
status: data.status,
|
|
279
|
+
digest: createHash("sha256").update(raw).digest("hex").slice(0, 16),
|
|
280
|
+
goal: fill(data.goal),
|
|
281
|
+
start_url: resolveUrl(fill(data.start_url), base),
|
|
282
|
+
steps,
|
|
283
|
+
focus: patterns(file, "focus", get(data, "focus")),
|
|
284
|
+
skip: patterns(file, "skip", get(data, "skip")),
|
|
285
|
+
};
|
|
286
|
+
}
|