werkmeister-core 0.93.2 → 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.
Files changed (78) hide show
  1. package/CHANGELOG.md +26 -0
  2. package/dist/build_caches.d.ts +78 -10
  3. package/dist/build_caches.js +24 -4
  4. package/dist/daemon_client.d.ts +7 -5
  5. package/dist/daemon_client.js +5 -4
  6. package/dist/docker.d.ts +35 -7
  7. package/dist/docker.js +21 -6
  8. package/dist/errors.d.ts +4 -2
  9. package/dist/errors.js +4 -2
  10. package/dist/form_schema.d.ts +25 -7
  11. package/dist/form_schema.js +6 -1
  12. package/dist/fragment_detect/assist.d.ts +126 -10
  13. package/dist/fragment_detect/assist.js +57 -2
  14. package/dist/fragment_detect/plan.d.ts +93 -13
  15. package/dist/fragment_detect/plan.js +46 -3
  16. package/dist/fragment_detect/render.d.ts +42 -2
  17. package/dist/fragment_detect/render.js +24 -1
  18. package/dist/fragment_detect/types.d.ts +51 -4
  19. package/dist/fragment_detect/validate.d.ts +57 -3
  20. package/dist/fragment_detect/validate.js +57 -3
  21. package/dist/graduate.d.ts +50 -9
  22. package/dist/graduate.js +28 -3
  23. package/dist/harness/claude/session.d.ts +17 -3
  24. package/dist/harness/claude/session.js +18 -3
  25. package/dist/harness/claude/usage.js +21 -4
  26. package/dist/harness/layout.d.ts +18 -1
  27. package/dist/harness/layout.js +18 -1
  28. package/dist/harness/types.d.ts +121 -22
  29. package/dist/infra.d.ts +84 -11
  30. package/dist/infra.js +89 -11
  31. package/dist/issue_status.d.ts +42 -2
  32. package/dist/issue_status.js +23 -1
  33. package/dist/issue_tracker.d.ts +15 -3
  34. package/dist/issue_trackers/types.d.ts +44 -19
  35. package/dist/launcher.d.ts +15 -0
  36. package/dist/lifecycle.d.ts +170 -46
  37. package/dist/lifecycle.js +93 -31
  38. package/dist/machine_setup.d.ts +12 -8
  39. package/dist/migrate.d.ts +39 -7
  40. package/dist/migrate.js +25 -2
  41. package/dist/notes.d.ts +41 -8
  42. package/dist/notes.js +30 -7
  43. package/dist/pr_lifecycle.d.ts +159 -17
  44. package/dist/pr_lifecycle.js +154 -36
  45. package/dist/pr_rules.js +1 -1
  46. package/dist/registry_sync.d.ts +41 -11
  47. package/dist/registry_sync.js +24 -4
  48. package/dist/resources.d.ts +24 -3
  49. package/dist/run_start.d.ts +17 -5
  50. package/dist/sandbox.d.ts +636 -156
  51. package/dist/sandbox.js +434 -83
  52. package/dist/scaffold.d.ts +1 -1
  53. package/dist/scaffold.js +11 -6
  54. package/dist/scheduler_client.d.ts +2 -2
  55. package/dist/scheduler_client.js +2 -2
  56. package/dist/slots.d.ts +42 -7
  57. package/dist/slots.js +18 -3
  58. package/dist/standards.d.ts +37 -17
  59. package/dist/standards.js +23 -10
  60. package/dist/stats.d.ts +66 -20
  61. package/dist/stats.js +42 -14
  62. package/dist/status.d.ts +82 -13
  63. package/dist/status.js +23 -1
  64. package/dist/strategies/icm_templates.js +3 -3
  65. package/dist/strategies/index.d.ts +20 -1
  66. package/dist/strategies/index.js +20 -1
  67. package/dist/strategies/types.d.ts +25 -10
  68. package/dist/telepresence.d.ts +74 -15
  69. package/dist/telepresence.js +12 -4
  70. package/dist/test_run.d.ts +61 -14
  71. package/dist/test_run.js +28 -5
  72. package/dist/usage_snapshot.d.ts +5 -1
  73. package/dist/usage_snapshot.js +22 -10
  74. package/dist/workspace_init.d.ts +67 -18
  75. package/dist/workspace_init.js +45 -9
  76. package/dist/workspace_token.d.ts +39 -5
  77. package/dist/workspace_token.js +41 -5
  78. package/package.json +2 -2
package/CHANGELOG.md CHANGED
@@ -1,5 +1,31 @@
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
+
22
+ ## 0.93.3
23
+
24
+ ### Patch Changes
25
+
26
+ - c9fb647: SW-773: usage costs price the current models (Claude Opus 5.5, Sonnet 5.5, Haiku 5.5, Fable 5.2), so `usage.json` and the `workspace-usage` tool no longer show a null cost for every run. `~/.werkmeister/model-pricing.yaml` now overrides the built-in rates instead of replacing them, so a file seeded before a model shipped still prices it with no edit. A model with no rate is reported once instead of silently. The built-in and newly seeded rates for Claude Opus 4.8 and Sonnet 5 move to their published prices ($5/$25 and $2/$10). An existing `model-pricing.yaml` keeps its own older rows for those two models (15/75 and 3/15), and those still win. Delete those rows, or the whole file, to use the new rates.
27
+ - 058117c: SW-774: close-out's `usage.json` and `usage.md` no longer show negative stage minutes. A stage now ends at the earlier of the record-branch commit that first added a file to its `output/` (`.gitkeep` excluded) and its oldest output file, so stages committed together keep their own times. Before, it ended at its newest output file, so a later edit to an earlier stage made the next stage's duration negative.
28
+
3
29
  ## 0.93.2
4
30
 
5
31
  ### Patch Changes
@@ -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
- /** What `pruneCaches` did, or would do, to one cache. */
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` and `prune` from the registry, `reset` when asked to empty it. */
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
- /** Which caches `pruneCaches` touches, and how. */
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
- /** Docker reads `pruneCaches` needs; tests swap these for fakes. */
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, as `cacheSnapshots` reads it. */
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
- * Apply each cache's prune rule (`max_age`, else `prune`), or empty it with
79
- * *reset*. Everything runs in a throwaway container with the cache mounted, so
80
- * a host dir and a volume prune the same way. Never removes a volume: Docker
81
- * refuses while any stopped workspace container still references it.
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[]>;
@@ -159,10 +159,30 @@ const defaultDeps = () => ({
159
159
  run: (argv) => run(argv, { capture: true }),
160
160
  });
161
161
  /**
162
- * Apply each cache's prune rule (`max_age`, else `prune`), or empty it with
163
- * *reset*. Everything runs in a throwaway container with the cache mounted, so
164
- * a host dir and a volume prune the same way. Never removes a volume: Docker
165
- * refuses while any stopped workspace container still references it.
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;
@@ -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 `SandboxError`.
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) console.log(e.code, e.message); // "DAEMON_DOWN"
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) console.log(`daemon ${status.pid} runs ${status.loaded}, disk has ${status.onDisk}`);
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 `SandboxError` when the daemon took the call but did not answer in time
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 `SandboxError`
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
@@ -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 `SandboxError`.
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) console.log(e.code, e.message); // "DAEMON_DOWN"
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 `SandboxError` when the daemon took the call but did not answer in time
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 `SandboxError`
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
- /** One stats sample of a running container, as `docker stats --no-stream` reports it. */
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
- * One stats sample for every running container.
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
- * Each call costs about a second: the daemon samples twice to produce the CPU
94
- * delta, exactly as `docker stats --no-stream` does. They run concurrently, so
95
- * the wall clock is one sample, not one per container.
119
+ * @example
120
+ * ```ts
121
+ * import { containerStats } from "werkmeister-core/sdk";
96
122
  *
97
- * *signal* cancels the requests in flight: on a loaded daemon one snapshot runs
98
- * for tens of seconds. An aborted snapshot comes back partial or empty.
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
- * One stats sample for every running container.
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
- * Each call costs about a second: the daemon samples twice to produce the CPU
262
- * delta, exactly as `docker stats --no-stream` does. They run concurrently, so
263
- * the wall clock is one sample, not one per container.
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
- * *signal* cancels the requests in flight: on a loaded daemon one snapshot runs
266
- * for tens of seconds. An aborted snapshot comes back partial or empty.
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") console.log("still running: don't retry");
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) console.log(e.code, e.message); // "WORKSPACE"
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") console.log("still running: don't retry");
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) console.log(e.code, e.message); // "WORKSPACE"
59
+ * if (e instanceof WorkspaceError)
60
+ * console.log(e.code, e.message); // "WORKSPACE"
59
61
  * else throw e;
60
62
  * }
61
63
  * ```
@@ -75,24 +75,37 @@ export interface SchemaProp {
75
75
  pattern?: string;
76
76
  minLength?: number;
77
77
  }
78
- /** The RJSF bundle `buildFormSchema` returns. */
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 unresolved prompt. */
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 unresolved prompt, keyed by the prompt's key. */
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` for the prompts' 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: the resolved value, else the prompt's default. */
106
+ /** Each field's starting value: what is already known, else the field's default. */
94
107
  formData: Record<string, unknown>;
95
- /** The given title, else `Initialize <name>`. */
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
- * { schema: { properties: { feature: { type: "string", pattern: "^[a-z-]+$" } }, required: ["feature"] } },
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' }
@@ -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
- * { schema: { properties: { feature: { type: "string", pattern: "^[a-z-]+$" } }, required: ["feature"] } },
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' }