werkmeister-core 0.93.3 → 0.93.5
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 +19 -0
- package/dist/build_caches.d.ts +78 -10
- package/dist/build_caches.js +24 -4
- package/dist/daemon_client.d.ts +7 -5
- package/dist/daemon_client.js +5 -4
- package/dist/docker.d.ts +35 -7
- package/dist/docker.js +21 -6
- package/dist/errors.d.ts +4 -2
- package/dist/errors.js +4 -2
- package/dist/form_schema.d.ts +25 -7
- package/dist/form_schema.js +6 -1
- package/dist/fragment_detect/assist.d.ts +126 -10
- package/dist/fragment_detect/assist.js +57 -2
- package/dist/fragment_detect/plan.d.ts +93 -13
- package/dist/fragment_detect/plan.js +46 -3
- package/dist/fragment_detect/render.d.ts +42 -2
- package/dist/fragment_detect/render.js +24 -1
- package/dist/fragment_detect/types.d.ts +51 -4
- package/dist/fragment_detect/validate.d.ts +57 -3
- package/dist/fragment_detect/validate.js +57 -3
- package/dist/graduate.d.ts +50 -9
- package/dist/graduate.js +28 -3
- package/dist/harness/claude/session.d.ts +17 -3
- package/dist/harness/claude/session.js +18 -3
- package/dist/harness/layout.d.ts +18 -1
- package/dist/harness/layout.js +18 -1
- package/dist/harness/types.d.ts +121 -22
- package/dist/infra.d.ts +84 -11
- package/dist/infra.js +89 -11
- package/dist/issue_status.d.ts +42 -2
- package/dist/issue_status.js +23 -1
- package/dist/issue_tracker.d.ts +15 -3
- package/dist/issue_trackers/types.d.ts +44 -19
- package/dist/launcher.d.ts +15 -0
- package/dist/lifecycle.d.ts +170 -46
- package/dist/lifecycle.js +93 -31
- package/dist/machine_setup.d.ts +12 -8
- package/dist/migrate.d.ts +39 -7
- package/dist/migrate.js +25 -2
- package/dist/notes.d.ts +41 -8
- package/dist/notes.js +30 -7
- package/dist/pr_lifecycle.d.ts +159 -17
- package/dist/pr_lifecycle.js +154 -36
- package/dist/pr_rules.js +1 -1
- package/dist/registry_sync.d.ts +41 -11
- package/dist/registry_sync.js +24 -4
- package/dist/resources.d.ts +24 -3
- package/dist/run_start.d.ts +17 -5
- package/dist/sandbox.d.ts +636 -156
- package/dist/sandbox.js +434 -83
- package/dist/scheduler_client.d.ts +2 -2
- package/dist/scheduler_client.js +2 -2
- package/dist/slots.d.ts +42 -7
- package/dist/slots.js +18 -3
- package/dist/standards.d.ts +37 -17
- package/dist/standards.js +23 -10
- package/dist/stats.d.ts +66 -20
- package/dist/stats.js +42 -14
- package/dist/status.d.ts +82 -13
- package/dist/status.js +23 -1
- package/dist/strategies/icm_templates.js +3 -3
- package/dist/strategies/index.d.ts +20 -1
- package/dist/strategies/index.js +20 -1
- package/dist/strategies/types.d.ts +25 -10
- package/dist/telepresence.d.ts +74 -15
- package/dist/telepresence.js +12 -4
- package/dist/test_run.d.ts +61 -14
- package/dist/test_run.js +28 -5
- package/dist/workspace_init.d.ts +67 -18
- package/dist/workspace_init.js +45 -9
- package/dist/workspace_token.d.ts +39 -5
- package/dist/workspace_token.js +41 -5
- package/package.json +2 -2
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,24 @@
|
|
|
1
1
|
# sandbox-core
|
|
2
2
|
|
|
3
|
+
## 0.93.5
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- 38cc8e9: SW-761: two SDK contract fixes. `getFormSchema()`'s `schema` is now typed as the form's JSON Schema (`properties`, `required`), so `validateFormData(await getFormSchema(), data)` type-checks without a cast; every old read still compiles. A provisioning failure from `createWorkspace({ live: true })` is now a `WorkspaceError` (its class stays `WorkspaceInitError`, its `code` becomes `WORKSPACE`), so catching `WorkspaceError` catches it.
|
|
8
|
+
- bae9fc9: SW-762: every page of the SDK reference now has SDK-user docs and a type-checked example: the 127 exports SDK parity added (functions, interfaces, type aliases and `WORKSPACE_ACTIONS`) are rewritten for SDK users (what each does, returns and throws, in-process or daemon) with a `werkmeister-core/sdk` example. Several docs now match their code where they did not: `parseNote` returns the note with empty frontmatter on a bad header, `fetchIssueCard` returns `{ ref, url }` on a failed fetch, `infraDown`/`infraStop`/`infraRestart` log a failure instead of throwing, and `InfraStatus` reports unhealthy services separately.
|
|
9
|
+
- aa8f406: SW-770: SDK docs link `SandboxError` and `WorkspaceError` in `@throws` again instead of showing them as plain code. `docs:links` now resolves a `{@link Name}` the SDK exports, so `@throws {@link SandboxError}` passes both `docs:links` and `docs:sdk` in any source file.
|
|
10
|
+
- 454dbe9: SW-794: the SDK docs' `@example` code is formatted like the rest of the repo (biome: 2 spaces, 100 columns). `pnpm run format:examples` formats every `@example` block in werkmeister-core's sources, and `docs:sdk` fails on one it would change; a block biome cannot parse is left as written.
|
|
11
|
+
|
|
12
|
+
## 0.93.4
|
|
13
|
+
|
|
14
|
+
### Patch Changes
|
|
15
|
+
|
|
16
|
+
- bf11837: PR rules (SW-661): rule 3's background-job recipe now covers `pr gate` and `pr gate --tests` too (`werkmeister pr gate --tests > <workspace>/.werkmeister/gate-run.log 2>&1`, kept on the record branch with the other `gate-*.log`), and the ICM stage contracts and `pr` help point to it instead of saying "detached", so a full gate no longer gets cut off by a 10-minute foreground tool call.
|
|
17
|
+
- c3f8ad3: `pr gate` (SW-724): the fragment and lockfile base lookups, and `--tests`' diff, share one `git merge-base` per gate run instead of running it once each.
|
|
18
|
+
- 8c6679c: `pr gate` / `pr open` (SW-734): a service the PR file's `skip_tests` names is no longer started, from `compose.gate.yml` or as the lint/release container, so the gate no longer waits for capacity for it or its install. The lint/release container is another repo service when one exists. The capacity-wait line now says that stopping the command ends the wait, and that the gate starts no `skip_tests` service.
|
|
19
|
+
- acd29ef: `pr gate` / `pr open` (SW-739): a test row killed with exit 137 under host load is run once more, after the host-load wait `with-temp-home` uses, and its row says it was retried. It fails only if the retry fails too.
|
|
20
|
+
- c0adef6: `pr gate` / `pr open` (SW-744): a test row whose only error is vitest's worker RPC timeout (`Timeout calling "onTaskUpdate"`, a worker blocked past vitest's fixed 60 s under host load) is run once more after the host-load wait, like an exit 137, and its row says it was retried. A real failure beside it (a failed test, a type error) still fails with no retry. The CLI's own tests start the bundled CLI and scripts asynchronously, so they no longer block a worker that long.
|
|
21
|
+
|
|
3
22
|
## 0.93.3
|
|
4
23
|
|
|
5
24
|
### Patch Changes
|
package/dist/build_caches.d.ts
CHANGED
|
@@ -42,17 +42,39 @@ export interface CacheSnapshot {
|
|
|
42
42
|
* `status` shows it and `cache prune` reaches it.
|
|
43
43
|
*/
|
|
44
44
|
export declare function cacheSnapshots(caches?: CacheRegistry, usage?: Map<string, VolumeUsage> | null | undefined): Promise<CacheSnapshot[]>;
|
|
45
|
-
/**
|
|
45
|
+
/**
|
|
46
|
+
* What {@link pruneCaches} did, or would do, to one cache. It returns one per
|
|
47
|
+
* cache it looked at.
|
|
48
|
+
*
|
|
49
|
+
* @example
|
|
50
|
+
* ```ts
|
|
51
|
+
* import { pruneCaches, type PruneResult } from "werkmeister-core/sdk";
|
|
52
|
+
*
|
|
53
|
+
* const results: PruneResult[] = await pruneCaches();
|
|
54
|
+
* for (const r of results.filter((r) => !r.ok)) console.error(`${r.name}: ${r.detail}`);
|
|
55
|
+
* ```
|
|
56
|
+
*/
|
|
46
57
|
export interface PruneResult {
|
|
47
58
|
/** The cache name; a leftover volume under the old `sandbox-<key>` name reads `<name> (<volume>)`. */ name: string;
|
|
48
|
-
/** The rule applied: `max_age`
|
|
59
|
+
/** The rule applied: `max_age` (delete files older than the cache's age limit), `prune` (run the cache's own prune command), `reset` (empty it), or `skipped`. */
|
|
49
60
|
action: "max_age" | "prune" | "reset" | "skipped";
|
|
50
61
|
/** What happened or would happen, the command's output, or why it was skipped or failed. */
|
|
51
62
|
detail: string;
|
|
52
63
|
/** False when the prune failed or could not be attempted; a deliberate skip is still ok. */
|
|
53
64
|
ok: boolean;
|
|
54
65
|
}
|
|
55
|
-
/**
|
|
66
|
+
/**
|
|
67
|
+
* Which caches {@link pruneCaches} touches, and how. Every field is optional;
|
|
68
|
+
* an empty object prunes every cache by its own rule.
|
|
69
|
+
*
|
|
70
|
+
* @example
|
|
71
|
+
* ```ts
|
|
72
|
+
* import { pruneCaches, type PruneOptions } from "werkmeister-core/sdk";
|
|
73
|
+
*
|
|
74
|
+
* const opts: PruneOptions = { name: "pnpm", reset: true, dryRun: true };
|
|
75
|
+
* console.log(await pruneCaches(opts));
|
|
76
|
+
* ```
|
|
77
|
+
*/
|
|
56
78
|
export interface PruneOptions {
|
|
57
79
|
/** One registry cache; absent for every cache. */
|
|
58
80
|
name?: string;
|
|
@@ -63,11 +85,37 @@ export interface PruneOptions {
|
|
|
63
85
|
/** Report what would be removed without removing it. */
|
|
64
86
|
dryRun?: boolean;
|
|
65
87
|
}
|
|
66
|
-
/**
|
|
88
|
+
/**
|
|
89
|
+
* What {@link pruneCaches} reads and runs: the cache list, Docker's view of
|
|
90
|
+
* each cache, and the command runner. Leave it out to use the real ones;
|
|
91
|
+
* pass your own to run `pruneCaches` against fakes, for example in a test.
|
|
92
|
+
*
|
|
93
|
+
* @example
|
|
94
|
+
* ```ts
|
|
95
|
+
* import { pruneCaches, type PruneDeps } from "werkmeister-core/sdk";
|
|
96
|
+
*
|
|
97
|
+
* const deps: PruneDeps = {
|
|
98
|
+
* caches: { pnpm: { path: "/pnpm-store", prune: "pnpm store prune" } },
|
|
99
|
+
* snapshots: async () => [
|
|
100
|
+
* {
|
|
101
|
+
* name: "pnpm",
|
|
102
|
+
* kind: "volume",
|
|
103
|
+
* source: "werkmeister-pnpm",
|
|
104
|
+
* exists: true,
|
|
105
|
+
* size_bytes: 0,
|
|
106
|
+
* created_at: null,
|
|
107
|
+
* },
|
|
108
|
+
* ],
|
|
109
|
+
* busy: async () => [],
|
|
110
|
+
* run: (argv) => ({ status: 0, stdout: argv.join(" "), stderr: "" }),
|
|
111
|
+
* };
|
|
112
|
+
* console.log(await pruneCaches({}, deps));
|
|
113
|
+
* ```
|
|
114
|
+
*/
|
|
67
115
|
export interface PruneDeps {
|
|
68
|
-
/** The registry's caches, keyed by name. */
|
|
116
|
+
/** The registry's caches (the `caches:` section of `services.yaml`), keyed by name. */
|
|
69
117
|
caches: CacheRegistry;
|
|
70
|
-
/** One row per cache,
|
|
118
|
+
/** One row per cache: where it lives, whether it exists, its size and creation time. */
|
|
71
119
|
snapshots: (caches: CacheRegistry) => Promise<CacheSnapshot[]>;
|
|
72
120
|
/** Names of the running containers mounting *source*; null when Docker is unreachable. */
|
|
73
121
|
busy: (source: string) => Promise<string[] | null>;
|
|
@@ -75,9 +123,29 @@ export interface PruneDeps {
|
|
|
75
123
|
run: (argv: string[]) => RunResult;
|
|
76
124
|
}
|
|
77
125
|
/**
|
|
78
|
-
*
|
|
79
|
-
*
|
|
80
|
-
*
|
|
81
|
-
*
|
|
126
|
+
* Frees disk in the shared build and package caches (the `caches:` section of
|
|
127
|
+
* `services.yaml`). Each cache gets its own rule: `max_age` deletes files older
|
|
128
|
+
* than its age limit, else `prune` runs its prune command; `reset` empties it
|
|
129
|
+
* instead. Runs in-process: each prune is a throwaway `docker run` with the
|
|
130
|
+
* cache mounted, so a host folder and a Docker volume prune the same way. It
|
|
131
|
+
* never removes a volume. A cache a running container mounts is skipped
|
|
132
|
+
* unless `force` is set.
|
|
133
|
+
*
|
|
134
|
+
* @param opts - Which cache (default: all), and whether to reset, force or
|
|
135
|
+
* only report (`dryRun`).
|
|
136
|
+
* @param deps - Where the caches, their state and the command runner come
|
|
137
|
+
* from. Leave it out to use `services.yaml` and Docker.
|
|
138
|
+
* @returns One {@link PruneResult} per cache looked at. An unknown `name`
|
|
139
|
+
* returns a single `skipped` row with `ok: false` rather than throwing, as
|
|
140
|
+
* does a cache whose state Docker can't report.
|
|
141
|
+
*
|
|
142
|
+
* @example
|
|
143
|
+
* ```ts
|
|
144
|
+
* import { pruneCaches } from "werkmeister-core/sdk";
|
|
145
|
+
*
|
|
146
|
+
* for (const r of await pruneCaches({ dryRun: true })) {
|
|
147
|
+
* console.log(`${r.name} [${r.action}] ${r.detail}`);
|
|
148
|
+
* }
|
|
149
|
+
* ```
|
|
82
150
|
*/
|
|
83
151
|
export declare function pruneCaches(opts?: PruneOptions, deps?: PruneDeps): Promise<PruneResult[]>;
|
package/dist/build_caches.js
CHANGED
|
@@ -159,10 +159,30 @@ const defaultDeps = () => ({
|
|
|
159
159
|
run: (argv) => run(argv, { capture: true }),
|
|
160
160
|
});
|
|
161
161
|
/**
|
|
162
|
-
*
|
|
163
|
-
*
|
|
164
|
-
*
|
|
165
|
-
*
|
|
162
|
+
* Frees disk in the shared build and package caches (the `caches:` section of
|
|
163
|
+
* `services.yaml`). Each cache gets its own rule: `max_age` deletes files older
|
|
164
|
+
* than its age limit, else `prune` runs its prune command; `reset` empties it
|
|
165
|
+
* instead. Runs in-process: each prune is a throwaway `docker run` with the
|
|
166
|
+
* cache mounted, so a host folder and a Docker volume prune the same way. It
|
|
167
|
+
* never removes a volume. A cache a running container mounts is skipped
|
|
168
|
+
* unless `force` is set.
|
|
169
|
+
*
|
|
170
|
+
* @param opts - Which cache (default: all), and whether to reset, force or
|
|
171
|
+
* only report (`dryRun`).
|
|
172
|
+
* @param deps - Where the caches, their state and the command runner come
|
|
173
|
+
* from. Leave it out to use `services.yaml` and Docker.
|
|
174
|
+
* @returns One {@link PruneResult} per cache looked at. An unknown `name`
|
|
175
|
+
* returns a single `skipped` row with `ok: false` rather than throwing, as
|
|
176
|
+
* does a cache whose state Docker can't report.
|
|
177
|
+
*
|
|
178
|
+
* @example
|
|
179
|
+
* ```ts
|
|
180
|
+
* import { pruneCaches } from "werkmeister-core/sdk";
|
|
181
|
+
*
|
|
182
|
+
* for (const r of await pruneCaches({ dryRun: true })) {
|
|
183
|
+
* console.log(`${r.name} [${r.action}] ${r.detail}`);
|
|
184
|
+
* }
|
|
185
|
+
* ```
|
|
166
186
|
*/
|
|
167
187
|
export async function pruneCaches(opts = {}, deps = defaultDeps()) {
|
|
168
188
|
const { caches } = deps;
|
package/dist/daemon_client.d.ts
CHANGED
|
@@ -30,7 +30,7 @@ export declare function daemonToken(workspaceRoot?: string): string | null;
|
|
|
30
30
|
/**
|
|
31
31
|
* Thrown when the werkmeister daemon is not reachable: nothing is listening at {@link daemonUrl},
|
|
32
32
|
* or something other than the daemon holds its port. The daemon never saw the call, so it is safe
|
|
33
|
-
* to run the work another way. Its `code` is `DAEMON_DOWN`, and it extends
|
|
33
|
+
* to run the work another way. Its `code` is `DAEMON_DOWN`, and it extends {@link SandboxError}.
|
|
34
34
|
*
|
|
35
35
|
* @example
|
|
36
36
|
* ```ts
|
|
@@ -39,7 +39,8 @@ export declare function daemonToken(workspaceRoot?: string): string | null;
|
|
|
39
39
|
* try {
|
|
40
40
|
* await callTool("status");
|
|
41
41
|
* } catch (e) {
|
|
42
|
-
* if (e instanceof DaemonUnavailable)
|
|
42
|
+
* if (e instanceof DaemonUnavailable)
|
|
43
|
+
* console.log(e.code, e.message); // "DAEMON_DOWN"
|
|
43
44
|
* else throw e;
|
|
44
45
|
* }
|
|
45
46
|
* ```
|
|
@@ -82,7 +83,8 @@ export declare function expectDaemonBuild(get: () => string | null): void;
|
|
|
82
83
|
* import { daemonStatus, type DaemonStatus } from "werkmeister-core/sdk";
|
|
83
84
|
*
|
|
84
85
|
* const status: DaemonStatus | null = await daemonStatus();
|
|
85
|
-
* if (status?.stale)
|
|
86
|
+
* if (status?.stale)
|
|
87
|
+
* console.log(`daemon ${status.pid} runs ${status.loaded}, disk has ${status.onDisk}`);
|
|
86
88
|
* ```
|
|
87
89
|
*/
|
|
88
90
|
export interface DaemonStatus {
|
|
@@ -152,7 +154,7 @@ export interface ToolResult<T> {
|
|
|
152
154
|
* @throws {@link DaemonUnavailable} when the daemon is not running or something else holds its
|
|
153
155
|
* port: the daemon never ran the tool, so you may run the work another way. Also when *signal*
|
|
154
156
|
* aborts the call before any answer came back; the daemon may already be running the tool then.
|
|
155
|
-
* @throws
|
|
157
|
+
* @throws {@link SandboxError} when the daemon took the call but did not answer in time
|
|
156
158
|
* (`code` `DAEMON_TIMEOUT`): it may still be running the tool, so do not run it again. Also when
|
|
157
159
|
* the tool fails (the tool's own `code`, or `HTTP_<status>`), and when the daemon runs older code
|
|
158
160
|
* that has no such tool (`DAEMON_STALE`).
|
|
@@ -186,7 +188,7 @@ export declare function callTool<T = unknown>(name: string, args?: Record<string
|
|
|
186
188
|
* @param opts - `token`: the bearer token to send; by default `WERKMEISTER_MCP_TOKEN`, else the
|
|
187
189
|
* machine token; `null` sends none.
|
|
188
190
|
* @returns A {@link LogTail}. `done` resolves when the stream ends or you call `stop()`. It
|
|
189
|
-
* rejects with {@link DaemonUnavailable} when the daemon is down, and with
|
|
191
|
+
* rejects with {@link DaemonUnavailable} when the daemon is down, and with {@link SandboxError}
|
|
190
192
|
* when the daemon refuses the stream or the logs fail.
|
|
191
193
|
*
|
|
192
194
|
* @example
|
package/dist/daemon_client.js
CHANGED
|
@@ -55,7 +55,7 @@ export function daemonToken(workspaceRoot) {
|
|
|
55
55
|
/**
|
|
56
56
|
* Thrown when the werkmeister daemon is not reachable: nothing is listening at {@link daemonUrl},
|
|
57
57
|
* or something other than the daemon holds its port. The daemon never saw the call, so it is safe
|
|
58
|
-
* to run the work another way. Its `code` is `DAEMON_DOWN`, and it extends
|
|
58
|
+
* to run the work another way. Its `code` is `DAEMON_DOWN`, and it extends {@link SandboxError}.
|
|
59
59
|
*
|
|
60
60
|
* @example
|
|
61
61
|
* ```ts
|
|
@@ -64,7 +64,8 @@ export function daemonToken(workspaceRoot) {
|
|
|
64
64
|
* try {
|
|
65
65
|
* await callTool("status");
|
|
66
66
|
* } catch (e) {
|
|
67
|
-
* if (e instanceof DaemonUnavailable)
|
|
67
|
+
* if (e instanceof DaemonUnavailable)
|
|
68
|
+
* console.log(e.code, e.message); // "DAEMON_DOWN"
|
|
68
69
|
* else throw e;
|
|
69
70
|
* }
|
|
70
71
|
* ```
|
|
@@ -222,7 +223,7 @@ export async function daemonStatus() {
|
|
|
222
223
|
* @throws {@link DaemonUnavailable} when the daemon is not running or something else holds its
|
|
223
224
|
* port: the daemon never ran the tool, so you may run the work another way. Also when *signal*
|
|
224
225
|
* aborts the call before any answer came back; the daemon may already be running the tool then.
|
|
225
|
-
* @throws
|
|
226
|
+
* @throws {@link SandboxError} when the daemon took the call but did not answer in time
|
|
226
227
|
* (`code` `DAEMON_TIMEOUT`): it may still be running the tool, so do not run it again. Also when
|
|
227
228
|
* the tool fails (the tool's own `code`, or `HTTP_<status>`), and when the daemon runs older code
|
|
228
229
|
* that has no such tool (`DAEMON_STALE`).
|
|
@@ -290,7 +291,7 @@ export async function callTool(name, args = {}, opts = {}) {
|
|
|
290
291
|
* @param opts - `token`: the bearer token to send; by default `WERKMEISTER_MCP_TOKEN`, else the
|
|
291
292
|
* machine token; `null` sends none.
|
|
292
293
|
* @returns A {@link LogTail}. `done` resolves when the stream ends or you call `stop()`. It
|
|
293
|
-
* rejects with {@link DaemonUnavailable} when the daemon is down, and with
|
|
294
|
+
* rejects with {@link DaemonUnavailable} when the daemon is down, and with {@link SandboxError}
|
|
294
295
|
* when the daemon refuses the stream or the logs fail.
|
|
295
296
|
*
|
|
296
297
|
* @example
|
package/dist/docker.d.ts
CHANGED
|
@@ -63,7 +63,20 @@ export declare function containerRecord(c: Dockerode.ContainerInfo): ProjectCont
|
|
|
63
63
|
export declare function displayPorts(ports: Dockerode.Port[]): string;
|
|
64
64
|
/** True when a container of this exact name exists and is running. */
|
|
65
65
|
export declare function containerRunning(name: string): Promise<boolean>;
|
|
66
|
-
/**
|
|
66
|
+
/**
|
|
67
|
+
* One CPU and memory sample of a running container, with the same numbers
|
|
68
|
+
* `docker stats --no-stream` shows. {@link containerStats} returns one per
|
|
69
|
+
* running container.
|
|
70
|
+
*
|
|
71
|
+
* @example
|
|
72
|
+
* ```ts
|
|
73
|
+
* import { containerStats, type ContainerStat } from "werkmeister-core/sdk";
|
|
74
|
+
*
|
|
75
|
+
* const stats: ContainerStat[] = await containerStats();
|
|
76
|
+
* const heavy = stats.filter((s) => s.memMib > 0.8 * s.memLimitMib);
|
|
77
|
+
* for (const s of heavy) console.log(s.name, s.memMib.toFixed(0), "MiB");
|
|
78
|
+
* ```
|
|
79
|
+
*/
|
|
67
80
|
export interface ContainerStat {
|
|
68
81
|
/** Container name, without Docker's leading `/`; the short ID when it has none. */
|
|
69
82
|
name: string;
|
|
@@ -88,14 +101,29 @@ export declare function cpuPercent(s: Dockerode.ContainerStats): number;
|
|
|
88
101
|
*/
|
|
89
102
|
export declare function memMib(s: Dockerode.ContainerStats): number;
|
|
90
103
|
/**
|
|
91
|
-
*
|
|
104
|
+
* Takes one CPU and memory sample of every running Docker container on this
|
|
105
|
+
* machine, not only werkmeister's. Runs in-process and talks to the Docker
|
|
106
|
+
* engine directly, not to the werkmeister daemon.
|
|
107
|
+
*
|
|
108
|
+
* A call takes about a second, because Docker samples twice to work out CPU
|
|
109
|
+
* use. All containers are sampled at once, so the time does not grow with
|
|
110
|
+
* their number. On a busy machine it can take much longer; pass `signal` to
|
|
111
|
+
* cap it.
|
|
112
|
+
*
|
|
113
|
+
* @param signal - Cancels the samples still in flight. An aborted call resolves
|
|
114
|
+
* with the samples that finished, possibly none.
|
|
115
|
+
* @returns One {@link ContainerStat} per running container. Empty when Docker
|
|
116
|
+
* is not reachable; a container that stops mid-sample is left out. It does
|
|
117
|
+
* not throw.
|
|
92
118
|
*
|
|
93
|
-
*
|
|
94
|
-
*
|
|
95
|
-
*
|
|
119
|
+
* @example
|
|
120
|
+
* ```ts
|
|
121
|
+
* import { containerStats } from "werkmeister-core/sdk";
|
|
96
122
|
*
|
|
97
|
-
*
|
|
98
|
-
*
|
|
123
|
+
* const stats = await containerStats(AbortSignal.timeout(10_000));
|
|
124
|
+
* stats.sort((a, b) => b.cpuPercent - a.cpuPercent);
|
|
125
|
+
* for (const s of stats.slice(0, 5)) console.log(s.name, `${s.cpuPercent.toFixed(1)}%`);
|
|
126
|
+
* ```
|
|
99
127
|
*/
|
|
100
128
|
export declare function containerStats(signal?: AbortSignal): Promise<ContainerStat[]>;
|
|
101
129
|
/** What only `inspect` knows about a container: the listing carries none of it. */
|
package/dist/docker.js
CHANGED
|
@@ -256,14 +256,29 @@ export function memMib(s) {
|
|
|
256
256
|
return ((s.memory_stats.usage ?? 0) - cache) / MIB;
|
|
257
257
|
}
|
|
258
258
|
/**
|
|
259
|
-
*
|
|
259
|
+
* Takes one CPU and memory sample of every running Docker container on this
|
|
260
|
+
* machine, not only werkmeister's. Runs in-process and talks to the Docker
|
|
261
|
+
* engine directly, not to the werkmeister daemon.
|
|
260
262
|
*
|
|
261
|
-
*
|
|
262
|
-
*
|
|
263
|
-
*
|
|
263
|
+
* A call takes about a second, because Docker samples twice to work out CPU
|
|
264
|
+
* use. All containers are sampled at once, so the time does not grow with
|
|
265
|
+
* their number. On a busy machine it can take much longer; pass `signal` to
|
|
266
|
+
* cap it.
|
|
264
267
|
*
|
|
265
|
-
*
|
|
266
|
-
*
|
|
268
|
+
* @param signal - Cancels the samples still in flight. An aborted call resolves
|
|
269
|
+
* with the samples that finished, possibly none.
|
|
270
|
+
* @returns One {@link ContainerStat} per running container. Empty when Docker
|
|
271
|
+
* is not reachable; a container that stops mid-sample is left out. It does
|
|
272
|
+
* not throw.
|
|
273
|
+
*
|
|
274
|
+
* @example
|
|
275
|
+
* ```ts
|
|
276
|
+
* import { containerStats } from "werkmeister-core/sdk";
|
|
277
|
+
*
|
|
278
|
+
* const stats = await containerStats(AbortSignal.timeout(10_000));
|
|
279
|
+
* stats.sort((a, b) => b.cpuPercent - a.cpuPercent);
|
|
280
|
+
* for (const s of stats.slice(0, 5)) console.log(s.name, `${s.cpuPercent.toFixed(1)}%`);
|
|
281
|
+
* ```
|
|
267
282
|
*/
|
|
268
283
|
export async function containerStats(signal) {
|
|
269
284
|
let running;
|
package/dist/errors.d.ts
CHANGED
|
@@ -16,7 +16,8 @@ export declare const WORKSPACE_ERROR_CODE = "WORKSPACE";
|
|
|
16
16
|
* try {
|
|
17
17
|
* await callTool("status");
|
|
18
18
|
* } catch (e) {
|
|
19
|
-
* if (e instanceof SandboxError && e.code === "DAEMON_TIMEOUT")
|
|
19
|
+
* if (e instanceof SandboxError && e.code === "DAEMON_TIMEOUT")
|
|
20
|
+
* console.log("still running: don't retry");
|
|
20
21
|
* else throw e;
|
|
21
22
|
* }
|
|
22
23
|
* ```
|
|
@@ -45,7 +46,8 @@ export declare class SandboxError extends Error {
|
|
|
45
46
|
* try {
|
|
46
47
|
* console.log(await resolveWorkspaceDir("no-such-workspace"));
|
|
47
48
|
* } catch (e) {
|
|
48
|
-
* if (e instanceof WorkspaceError)
|
|
49
|
+
* if (e instanceof WorkspaceError)
|
|
50
|
+
* console.log(e.code, e.message); // "WORKSPACE"
|
|
49
51
|
* else throw e;
|
|
50
52
|
* }
|
|
51
53
|
* ```
|
package/dist/errors.js
CHANGED
|
@@ -20,7 +20,8 @@ export const WORKSPACE_ERROR_CODE = "WORKSPACE";
|
|
|
20
20
|
* try {
|
|
21
21
|
* await callTool("status");
|
|
22
22
|
* } catch (e) {
|
|
23
|
-
* if (e instanceof SandboxError && e.code === "DAEMON_TIMEOUT")
|
|
23
|
+
* if (e instanceof SandboxError && e.code === "DAEMON_TIMEOUT")
|
|
24
|
+
* console.log("still running: don't retry");
|
|
24
25
|
* else throw e;
|
|
25
26
|
* }
|
|
26
27
|
* ```
|
|
@@ -55,7 +56,8 @@ export class SandboxError extends Error {
|
|
|
55
56
|
* try {
|
|
56
57
|
* console.log(await resolveWorkspaceDir("no-such-workspace"));
|
|
57
58
|
* } catch (e) {
|
|
58
|
-
* if (e instanceof WorkspaceError)
|
|
59
|
+
* if (e instanceof WorkspaceError)
|
|
60
|
+
* console.log(e.code, e.message); // "WORKSPACE"
|
|
59
61
|
* else throw e;
|
|
60
62
|
* }
|
|
61
63
|
* ```
|
package/dist/form_schema.d.ts
CHANGED
|
@@ -75,24 +75,37 @@ export interface SchemaProp {
|
|
|
75
75
|
pattern?: string;
|
|
76
76
|
minLength?: number;
|
|
77
77
|
}
|
|
78
|
-
/**
|
|
78
|
+
/**
|
|
79
|
+
* A form described as JSON Schema, ready for a form library such as
|
|
80
|
+
* react-jsonschema-form (RJSF). {@link getFormSchema} returns one for the
|
|
81
|
+
* create-workspace form.
|
|
82
|
+
*
|
|
83
|
+
* @example
|
|
84
|
+
* ```ts
|
|
85
|
+
* import { type FormBundle, getFormSchema } from "werkmeister-core/sdk";
|
|
86
|
+
*
|
|
87
|
+
* const form: FormBundle = await getFormSchema();
|
|
88
|
+
* for (const key of form.schema.required ?? [])
|
|
89
|
+
* console.log(`${form.schema.properties[key]?.title ?? key} is required`);
|
|
90
|
+
* ```
|
|
91
|
+
*/
|
|
79
92
|
export type FormBundle = {
|
|
80
|
-
/** The JSON Schema: one property per
|
|
93
|
+
/** The JSON Schema: one property per field the person still has to fill in. */
|
|
81
94
|
schema: {
|
|
82
95
|
/** Always `object`: the form is one object of fields. */
|
|
83
96
|
type: "object";
|
|
84
97
|
/** The form heading, the same as the bundle's `title`. */
|
|
85
98
|
title: string;
|
|
86
|
-
/** One field per
|
|
99
|
+
/** One field per question, keyed by the field's key. Each has a `title`, a `type` and, for a choice, an `enum`. */
|
|
87
100
|
properties: Record<string, SchemaProp>;
|
|
88
101
|
/** Keys of the fields that may not be left empty; absent when none. */
|
|
89
102
|
required?: string[];
|
|
90
103
|
};
|
|
91
|
-
/** RJSF widget hints per field key, plus `ui:order
|
|
104
|
+
/** RJSF widget hints per field key, plus `ui:order`, the order to show the fields in. */
|
|
92
105
|
uiSchema: Record<string, unknown>;
|
|
93
|
-
/** Each field's starting value:
|
|
106
|
+
/** Each field's starting value: what is already known, else the field's default. */
|
|
94
107
|
formData: Record<string, unknown>;
|
|
95
|
-
/** The
|
|
108
|
+
/** The form heading, e.g. `Initialize my-workspace`. */
|
|
96
109
|
title: string;
|
|
97
110
|
};
|
|
98
111
|
/**
|
|
@@ -121,7 +134,12 @@ export declare function repoSelectionError(formData: Record<string, unknown>): s
|
|
|
121
134
|
* import { validateFormData } from "werkmeister-core/sdk";
|
|
122
135
|
*
|
|
123
136
|
* const errors = validateFormData(
|
|
124
|
-
* {
|
|
137
|
+
* {
|
|
138
|
+
* schema: {
|
|
139
|
+
* properties: { feature: { type: "string", pattern: "^[a-z-]+$" } },
|
|
140
|
+
* required: ["feature"],
|
|
141
|
+
* },
|
|
142
|
+
* },
|
|
125
143
|
* { feature: "Login Page", services: ["api"] },
|
|
126
144
|
* );
|
|
127
145
|
* console.log(errors); // { feature: '"Login Page" doesn\'t match the expected format' }
|
package/dist/form_schema.js
CHANGED
|
@@ -199,7 +199,12 @@ const blank = (v) => v == null || v === "" || (Array.isArray(v) && v.length ===
|
|
|
199
199
|
* import { validateFormData } from "werkmeister-core/sdk";
|
|
200
200
|
*
|
|
201
201
|
* const errors = validateFormData(
|
|
202
|
-
* {
|
|
202
|
+
* {
|
|
203
|
+
* schema: {
|
|
204
|
+
* properties: { feature: { type: "string", pattern: "^[a-z-]+$" } },
|
|
205
|
+
* required: ["feature"],
|
|
206
|
+
* },
|
|
207
|
+
* },
|
|
203
208
|
* { feature: "Login Page", services: ["api"] },
|
|
204
209
|
* );
|
|
205
210
|
* console.log(errors); // { feature: '"Login Page" doesn\'t match the expected format' }
|
|
@@ -1,25 +1,61 @@
|
|
|
1
1
|
import type { Plan } from "./plan.js";
|
|
2
2
|
export type QuestionKind = "command" | "health_endpoint" | "environment" | "secrets" | "depends_on" | "conflict" | "unmatched";
|
|
3
|
-
/**
|
|
3
|
+
/**
|
|
4
|
+
* One thing the scan could not settle, put as a question to whoever reads the repo
|
|
5
|
+
* (usually Claude). {@link collectQuestions} lists them; send back an {@link Answer} per
|
|
6
|
+
* question you can answer.
|
|
7
|
+
*
|
|
8
|
+
* @example
|
|
9
|
+
* ```ts
|
|
10
|
+
* import { collectQuestions, planFragment, type Question } from "werkmeister-core/sdk";
|
|
11
|
+
*
|
|
12
|
+
* const plan = planFragment("/home/me/repos/my-app", {
|
|
13
|
+
* reposRoot: "/home/me/repos",
|
|
14
|
+
* runner: () => [1, ""],
|
|
15
|
+
* localPath: "/home/me/.werkmeister/services.local.yaml",
|
|
16
|
+
* portsPerSlot: 20,
|
|
17
|
+
* });
|
|
18
|
+
* const questions: Question[] = collectQuestions(plan);
|
|
19
|
+
* for (const q of questions) console.log(`${q.id} (${q.kind}): ${q.prompt}`, q.choices ?? "");
|
|
20
|
+
* ```
|
|
21
|
+
*/
|
|
4
22
|
export interface Question {
|
|
5
|
-
/** `<service>.<key>`, or `unmatched.<name
|
|
23
|
+
/** `<service>.<key>`, or `unmatched.<name>`. An answer names it as its `item`. */
|
|
6
24
|
id: string;
|
|
7
|
-
/**
|
|
25
|
+
/**
|
|
26
|
+
* What is asked, which sets the rule {@link applyAnswers} checks the answer against:
|
|
27
|
+
* `command`, `health_endpoint`, `environment`, `secrets`, `depends_on`, `conflict` or `unmatched`.
|
|
28
|
+
*/
|
|
8
29
|
kind: QuestionKind;
|
|
9
30
|
/** The service asked about, or null for an unmatched finding. */
|
|
10
31
|
service: string | null;
|
|
11
32
|
/** The question in plain English. */
|
|
12
33
|
prompt: string;
|
|
13
|
-
/** What the scan already knows (dir, current guess, files),
|
|
34
|
+
/** What the scan already knows (dir, current guess, files), as a starting point for the answer. */
|
|
14
35
|
facts: Record<string, unknown>;
|
|
15
36
|
/** When set, the answer must be one of these (a subset, for list questions). */
|
|
16
37
|
choices?: unknown[];
|
|
17
38
|
}
|
|
18
|
-
/**
|
|
39
|
+
/**
|
|
40
|
+
* An answer to one {@link Question}, usually from Claude reading the repo. Pass a list
|
|
41
|
+
* of them to {@link applyAnswers}.
|
|
42
|
+
*
|
|
43
|
+
* @example
|
|
44
|
+
* ```ts
|
|
45
|
+
* import type { Answer } from "werkmeister-core/sdk";
|
|
46
|
+
*
|
|
47
|
+
* const answer: Answer = {
|
|
48
|
+
* item: "api.health_endpoint",
|
|
49
|
+
* value: "/healthz",
|
|
50
|
+
* reason: "src/server.ts registers GET /healthz",
|
|
51
|
+
* files_read: ["src/server.ts"],
|
|
52
|
+
* };
|
|
53
|
+
* ```
|
|
54
|
+
*/
|
|
19
55
|
export interface Answer {
|
|
20
56
|
/** The `id` of the question answered. */
|
|
21
57
|
item: string;
|
|
22
|
-
/** The proposed value
|
|
58
|
+
/** The proposed value. Checked against the question's kind and choices before use. */
|
|
23
59
|
value: unknown;
|
|
24
60
|
/** One sentence naming the evidence; written into the fragment as a comment. */
|
|
25
61
|
reason: string;
|
|
@@ -27,7 +63,32 @@ export interface Answer {
|
|
|
27
63
|
files_read: string[];
|
|
28
64
|
}
|
|
29
65
|
export type Resolver = (repoRoot: string, questions: Question[]) => Promise<Answer[]>;
|
|
30
|
-
/**
|
|
66
|
+
/**
|
|
67
|
+
* What {@link applyAnswers} made of a list of answers: the updated plan, and which
|
|
68
|
+
* answers it took or refused.
|
|
69
|
+
*
|
|
70
|
+
* @example
|
|
71
|
+
* ```ts
|
|
72
|
+
* import { type Answer, type ApplyResult, applyAnswers, planFragment } from "werkmeister-core/sdk";
|
|
73
|
+
*
|
|
74
|
+
* const plan = planFragment("/home/me/repos/my-app", {
|
|
75
|
+
* reposRoot: "/home/me/repos",
|
|
76
|
+
* runner: () => [1, ""],
|
|
77
|
+
* localPath: "/home/me/.werkmeister/services.local.yaml",
|
|
78
|
+
* portsPerSlot: 20,
|
|
79
|
+
* });
|
|
80
|
+
* const answers: Answer[] = [
|
|
81
|
+
* {
|
|
82
|
+
* item: "api.command",
|
|
83
|
+
* value: "npm run dev",
|
|
84
|
+
* reason: "package.json dev script",
|
|
85
|
+
* files_read: ["package.json"],
|
|
86
|
+
* },
|
|
87
|
+
* ];
|
|
88
|
+
* const result: ApplyResult = applyAnswers(plan, answers);
|
|
89
|
+
* for (const r of result.rejected) console.warn(`${r.item}: ${r.reason}`);
|
|
90
|
+
* ```
|
|
91
|
+
*/
|
|
31
92
|
export interface ApplyResult {
|
|
32
93
|
/** A copy of the plan with the accepted answers applied; the input plan is unchanged. */
|
|
33
94
|
plan: Plan;
|
|
@@ -35,7 +96,7 @@ export interface ApplyResult {
|
|
|
35
96
|
accepted: string[];
|
|
36
97
|
/** Answers left out, each with the rule they broke. */
|
|
37
98
|
rejected: {
|
|
38
|
-
/** The answer's `item`, as
|
|
99
|
+
/** The answer's `item`, as sent. */
|
|
39
100
|
item: string;
|
|
40
101
|
/** Why it was refused. */
|
|
41
102
|
reason: string;
|
|
@@ -71,8 +132,63 @@ export declare const ANSWER_SCHEMA: {
|
|
|
71
132
|
};
|
|
72
133
|
};
|
|
73
134
|
};
|
|
74
|
-
/**
|
|
135
|
+
/**
|
|
136
|
+
* Lists what is worth asking about a plan: guessed commands and health endpoints,
|
|
137
|
+
* `.env.example` keys, `depends_on`, values two files disagree on, and findings that
|
|
138
|
+
* matched no service. Keys the existing fragment already sets are not asked. Runs
|
|
139
|
+
* in-process; it only builds the questions, and getting them answered (for example by
|
|
140
|
+
* Claude) is up to you.
|
|
141
|
+
*
|
|
142
|
+
* @param plan - A plan from {@link planFragment}.
|
|
143
|
+
* @returns One {@link Question} per open item, possibly none.
|
|
144
|
+
* @throws `Error` from the YAML parser when `plan.existing` doesn't parse.
|
|
145
|
+
*
|
|
146
|
+
* @example
|
|
147
|
+
* ```ts
|
|
148
|
+
* import { collectQuestions, planFragment } from "werkmeister-core/sdk";
|
|
149
|
+
*
|
|
150
|
+
* const plan = planFragment("/home/me/repos/my-app", {
|
|
151
|
+
* reposRoot: "/home/me/repos",
|
|
152
|
+
* runner: () => [1, ""],
|
|
153
|
+
* localPath: "/home/me/.werkmeister/services.local.yaml",
|
|
154
|
+
* portsPerSlot: 20,
|
|
155
|
+
* });
|
|
156
|
+
* const questions = collectQuestions(plan);
|
|
157
|
+
* console.log(JSON.stringify(questions, null, 2));
|
|
158
|
+
* ```
|
|
159
|
+
*/
|
|
75
160
|
export declare function collectQuestions(plan: Plan): Question[];
|
|
76
|
-
/**
|
|
161
|
+
/**
|
|
162
|
+
* Checks each answer against the question it names and applies the ones that pass, as
|
|
163
|
+
* `inferred` fields. An answer to an unknown question, a second answer to the same
|
|
164
|
+
* question, or a value that breaks the question's rule is rejected with the reason.
|
|
165
|
+
* Runs in-process; the input plan is not changed.
|
|
166
|
+
*
|
|
167
|
+
* @param plan - The plan the questions came from (see {@link collectQuestions}).
|
|
168
|
+
* @param answers - The answers, each naming its question's `id` as `item`.
|
|
169
|
+
* @returns An {@link ApplyResult}: the updated copy of the plan, and the accepted and rejected items.
|
|
170
|
+
* @throws `Error` from the YAML parser when `plan.existing` doesn't parse.
|
|
171
|
+
*
|
|
172
|
+
* @example
|
|
173
|
+
* ```ts
|
|
174
|
+
* import { applyAnswers, planFragment, renderFragment } from "werkmeister-core/sdk";
|
|
175
|
+
*
|
|
176
|
+
* const plan = planFragment("/home/me/repos/my-app", {
|
|
177
|
+
* reposRoot: "/home/me/repos",
|
|
178
|
+
* runner: () => [1, ""],
|
|
179
|
+
* localPath: "/home/me/.werkmeister/services.local.yaml",
|
|
180
|
+
* portsPerSlot: 20,
|
|
181
|
+
* });
|
|
182
|
+
* const { plan: next, accepted } = applyAnswers(plan, [
|
|
183
|
+
* {
|
|
184
|
+
* item: "api.health_endpoint",
|
|
185
|
+
* value: "/healthz",
|
|
186
|
+
* reason: "src/server.ts registers GET /healthz",
|
|
187
|
+
* files_read: ["src/server.ts"],
|
|
188
|
+
* },
|
|
189
|
+
* ]);
|
|
190
|
+
* console.log(accepted, renderFragment(next).yaml);
|
|
191
|
+
* ```
|
|
192
|
+
*/
|
|
77
193
|
export declare function applyAnswers(plan: Plan, answers: Answer[]): ApplyResult;
|
|
78
194
|
export declare function assistPrompt(questions: Question[]): string;
|