werkmeister-core 0.93.3 → 0.93.6

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 +33 -0
  2. package/dist/agent_state.js +3 -2
  3. package/dist/archetypes.js +1 -1
  4. package/dist/build_caches.d.ts +78 -10
  5. package/dist/build_caches.js +24 -4
  6. package/dist/daemon_client.d.ts +7 -5
  7. package/dist/daemon_client.js +5 -4
  8. package/dist/docker.d.ts +35 -7
  9. package/dist/docker.js +21 -6
  10. package/dist/errors.d.ts +4 -2
  11. package/dist/errors.js +4 -2
  12. package/dist/fixture_workspace.d.ts +5 -1
  13. package/dist/fixture_workspace.js +37 -8
  14. package/dist/form_schema.d.ts +25 -7
  15. package/dist/form_schema.js +6 -1
  16. package/dist/fragment_detect/assist.d.ts +126 -10
  17. package/dist/fragment_detect/assist.js +57 -2
  18. package/dist/fragment_detect/plan.d.ts +93 -13
  19. package/dist/fragment_detect/plan.js +46 -3
  20. package/dist/fragment_detect/render.d.ts +42 -2
  21. package/dist/fragment_detect/render.js +24 -1
  22. package/dist/fragment_detect/types.d.ts +51 -4
  23. package/dist/fragment_detect/validate.d.ts +57 -3
  24. package/dist/fragment_detect/validate.js +57 -3
  25. package/dist/graduate.d.ts +50 -9
  26. package/dist/graduate.js +28 -3
  27. package/dist/harness/claude/session.d.ts +17 -3
  28. package/dist/harness/claude/session.js +18 -3
  29. package/dist/harness/layout.d.ts +18 -1
  30. package/dist/harness/layout.js +18 -1
  31. package/dist/harness/types.d.ts +121 -22
  32. package/dist/infra.d.ts +84 -11
  33. package/dist/infra.js +89 -11
  34. package/dist/issue_status.d.ts +42 -2
  35. package/dist/issue_status.js +23 -1
  36. package/dist/issue_tracker.d.ts +17 -3
  37. package/dist/issue_tracker.js +7 -3
  38. package/dist/issue_trackers/types.d.ts +44 -19
  39. package/dist/launcher.d.ts +15 -0
  40. package/dist/lifecycle.d.ts +170 -46
  41. package/dist/lifecycle.js +114 -37
  42. package/dist/machine_setup.d.ts +12 -8
  43. package/dist/migrate.d.ts +39 -7
  44. package/dist/migrate.js +25 -2
  45. package/dist/notes.d.ts +41 -8
  46. package/dist/notes.js +30 -7
  47. package/dist/pr_lifecycle.d.ts +163 -18
  48. package/dist/pr_lifecycle.js +203 -40
  49. package/dist/pr_rules.js +1 -1
  50. package/dist/registry_sync.d.ts +41 -11
  51. package/dist/registry_sync.js +24 -4
  52. package/dist/resources.d.ts +24 -3
  53. package/dist/run_start.d.ts +17 -5
  54. package/dist/sandbox.d.ts +644 -157
  55. package/dist/sandbox.js +444 -85
  56. package/dist/scheduler_client.d.ts +2 -2
  57. package/dist/scheduler_client.js +2 -2
  58. package/dist/slots.d.ts +42 -7
  59. package/dist/slots.js +18 -3
  60. package/dist/standards.d.ts +37 -17
  61. package/dist/standards.js +23 -10
  62. package/dist/stats.d.ts +66 -20
  63. package/dist/stats.js +42 -14
  64. package/dist/status.d.ts +82 -13
  65. package/dist/status.js +23 -1
  66. package/dist/strategies/icm_templates.js +5 -4
  67. package/dist/strategies/index.d.ts +20 -1
  68. package/dist/strategies/index.js +20 -1
  69. package/dist/strategies/types.d.ts +25 -10
  70. package/dist/telepresence.d.ts +74 -15
  71. package/dist/telepresence.js +12 -4
  72. package/dist/test_run.d.ts +61 -14
  73. package/dist/test_run.js +28 -5
  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,38 @@
1
1
  # sandbox-core
2
2
 
3
+ ## 0.93.6
4
+
5
+ ### Patch Changes
6
+
7
+ - 4db8b7b: SW-665: `pr gate` tests every service again when a branch changes an `infrastructure:` or `caches:` entry in the repo's own `.werkmeister/services.yaml` (`every service: … infrastructure: <name>`); since SW-573 such a change touched no service and ran no tests.
8
+ - cccc0ce: SW-721: the container test line in `werkmeister-context.md` and its allow rule escape a `'` in the test or lint command (`'\''`), so both run the registered command instead of a different word split.
9
+ - 44c12ab: SW-809: `with-fixture-workspace --queue <feature>:<waitedMin>[:<service>,...]` (and `withFixtureWorkspace({ queue })`) seeds a waiter's workspace, compose.yml, lease and `waiting.json`, not only its name, so a starved, whole-feature or service queue head runs through the built CLI. `--queue` now repeats; a bare name still seeds only the name.
10
+ - df3c3d0: SW-825: the generated propose-stage contract says to start the release check's container with `werkmeister feature up --service <name>` first, since an earlier `pr gate --tests` stopped the containers it started.
11
+ - 5f85455: SW-829: `pr gate` (and so `pr open`) adds a `group` row to a grouped workspace's gate. It warns about each `group:` member whose key is in no commit subject in `origin/<base>..HEAD`, since that member would ship as Done with the PR, and prints the fix: remove it from `group:` and move it back to To Do with `werkmeister issue update <KEY> --status "To Do" --comment …`.
12
+ - 166fb6d: SW-831: when preemption fails to stop a victim and some of its containers still run, the victim is no longer queued, so its agent's container and test commands are not held over live containers. The start that asked still waits at the head of the queue. A victim with nothing left running is queued to come back, as before.
13
+ - 855cb69: SW-832: while a workspace waits for capacity, the hook now also holds the MCP `test` tool and `workspace-pr` with `gate` or `open`, as it holds their Bash forms. `workspace-pr` `status` still runs.
14
+ - 6ff3082: SW-833: `runWorkspaceAction` takes an optional `{ byPerson }` that says a person, not an agent, asked for an `up`. The workspaces pane's Up passes `byPerson: true`, so a person's Up on a full machine can stop agents' features instead of queueing behind them, in a workspace that is not autonomous. An autonomous workspace's Up still queues as an agent's. Before this, the pane ran inside Claude Code and inherited `CLAUDECODE=1`, so its Up always counted as an agent's start.
15
+ - b6108f6: SW-840: when a workspace is started from the waiting queue and some of its containers are still stopped, the message that resumes its session now names each one and the command that starts it (`werkmeister feature up --service <name>`). Before this, it said the containers were up. Preemption stops on-demand containers too, and the grant's `up` starts only the default set.
16
+
17
+ ## 0.93.5
18
+
19
+ ### Patch Changes
20
+
21
+ - 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.
22
+ - 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.
23
+ - 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.
24
+ - 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.
25
+
26
+ ## 0.93.4
27
+
28
+ ### Patch Changes
29
+
30
+ - 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.
31
+ - 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.
32
+ - 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.
33
+ - 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.
34
+ - 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.
35
+
3
36
  ## 0.93.3
4
37
 
5
38
  ### Patch Changes
@@ -642,7 +642,8 @@ function leftOver(root) {
642
642
  // Starts containers or runs tests. A list of what is held, not of what passes: the ticket names the held
643
643
  // set, and an allowlist would hold `werkmeister feature stop`, the command that frees room (SW-768).
644
644
  const NEEDS_CAPACITY = /(^|[\s;&|(`/'"])(docker|pnpm|npm|npx|node|turbo|vitest|with-temp-home|with-fixture-workspace)(\s|$)|\b(werkmeister|w9r)\s+(feature\s+(up|restart)|pr\s+(gate|open))\b/;
645
- const NEEDS_CAPACITY_TOOL = /^mcp__.*werkmeister.*__(up|restart)$/;
645
+ // The MCP forms of the held commands (SW-832); `workspace-pr` `status` passes like `pr status`.
646
+ const NEEDS_CAPACITY_TOOL = /^mcp__.*werkmeister.*__(up|restart|test|workspace-pr)$/;
646
647
  function needsCapacity(input) {
647
648
  if (input["hook_event_name"] !== "PreToolUse")
648
649
  return false;
@@ -652,7 +653,7 @@ function needsCapacity(input) {
652
653
  const command = String(input["tool_input"]?.["command"] ?? "").replace(/(\s(?:-m|--message)[= ]?\s*)('[^']*'|"[^"]*")/g, "$1''");
653
654
  if (tool === "Bash")
654
655
  return NEEDS_CAPACITY.test(command);
655
- return NEEDS_CAPACITY_TOOL.test(tool);
656
+ return NEEDS_CAPACITY_TOOL.test(tool) && input["tool_input"]?.["action"] !== "status";
656
657
  }
657
658
  /**
658
659
  * The hook's stdout while the workspace is paused or waiting for capacity, or null. `continue: false` ends
@@ -81,7 +81,7 @@ export function serviceNoTests(svcDef) {
81
81
  * `permissions.allow` rule both use it, so the rule matches what the agent runs.
82
82
  */
83
83
  export function containerTestCommand(feature, svc, cmd) {
84
- return `docker exec ${feature}-${svc} sh -c '${cmd}'`;
84
+ return `docker exec ${feature}-${svc} sh -c '${cmd.split("'").join(`'\\''`)}'`;
85
85
  }
86
86
  /** True when *cmd* is simple commands joined only by `&&`: no group, pipe, `||`, `;`, `&`, newline or substitution. */
87
87
  export function isPlainChain(cmd) {
@@ -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
  * ```
@@ -51,7 +51,11 @@ export interface FixtureOptions {
51
51
  config?: Record<string, unknown>;
52
52
  /** Containers the fake docker shows the scheduler as running, so a start can wait for capacity (SW-685). */
53
53
  containers?: FixtureContainer[];
54
- /** Features in the waiting queue, `scheduler/queue.json` (SW-685). */
54
+ /**
55
+ * The waiting queue, `scheduler/queue.json` (SW-685), one `<feature>[:<waitedMin>[:<service>,...]]` each.
56
+ * With a wait, the waiter also gets a workspace with a compose.yml, a lease and a waiting.json whose
57
+ * `since` is that many minutes back (and `services`, a service start), so admission prices and ages it (SW-809).
58
+ */
55
59
  queue?: string[];
56
60
  }
57
61
  /** One running container as `docker inspect` reports it to the scheduler. */
@@ -8,6 +8,8 @@ import { execFileSync } from "node:child_process";
8
8
  import * as fs from "node:fs";
9
9
  import * as path from "node:path";
10
10
  import YAML from "yaml";
11
+ import { waitingPath } from "./agent_state.js";
12
+ import { COMPOSE_FILE } from "./compose_file.js";
11
13
  import { containerOf } from "./config.js";
12
14
  import { dotDir } from "./dot_dir.js";
13
15
  import { writeFakes } from "./fixture_fakes.js";
@@ -15,6 +17,7 @@ import { gitEnv } from "./proc.js";
15
17
  import { prDir, stageDirs, templateFor } from "./strategies/icm_templates.js";
16
18
  // Names become folders under the fixture and lines in the fakes, from a pre-approved wrapper's input.
17
19
  const NAME = /^[a-z0-9][a-z0-9-]*$/;
20
+ const QUEUE_ENTRY = /^([a-z0-9][a-z0-9-]*)(?::(\d+)(?::([a-z0-9][a-z0-9-]*(?:,[a-z0-9][a-z0-9-]*)*))?)?$/;
18
21
  // The only config.yaml keys --config may add: others (jira, github_ingest, paths…) reach real services or repos from a pre-approved run.
19
22
  const CONFIG_KEYS = ["budget"];
20
23
  export const FIXTURE_FEATURE = "demo";
@@ -89,9 +92,9 @@ export function fixturePreset({ gate, bare, change, ...opts }) {
89
92
  if (bad !== undefined)
90
93
  throw new Error(`--running: bad value ${JSON.stringify(bad)}: feature and workspace are lowercase names, startedAt a date, memory and nanoCpus whole numbers`);
91
94
  }
92
- const badName = opts.queue?.find((f) => !NAME.test(f));
93
- if (badName !== undefined)
94
- throw new Error(`--queue: bad feature ${JSON.stringify(badName)}: lowercase names, comma-separated`);
95
+ const badEntry = opts.queue?.find((q) => !QUEUE_ENTRY.test(q));
96
+ if (badEntry !== undefined)
97
+ throw new Error(`--queue: bad entry ${JSON.stringify(badEntry)}: <feature>[:<waitedMin>[:<service>,...]], lowercase names and whole minutes`);
95
98
  const libChange = "packages/lib/index.js";
96
99
  const gateChange = change ?? (opts.fragmentChange === undefined ? libChange : undefined);
97
100
  if (gate && opts.services && gateChange === libChange) {
@@ -213,18 +216,44 @@ ${githubProject(repos.map((r) => r.name))}${opts.config ? YAML.stringify(opts.co
213
216
  git(workspace, "commit", "-q", "-m", "record");
214
217
  git(workspace, "remote", "add", "origin", record);
215
218
  git(workspace, "push", "-q", "-u", "origin", FIXTURE_BRANCH);
219
+ const leases = {};
216
220
  if (opts.slotsFull) {
217
- const leases = {};
218
221
  for (let slot = 1; slot <= YAML.parse(PORTS).feature_slots.count; slot++) {
219
222
  const other = path.join(root, "ws", `other-${slot}`);
220
223
  fs.mkdirSync(other, { recursive: true });
221
224
  leases[`other-${slot}`] = { slot, workspace: other };
222
225
  }
223
- // leasesPath() beside configFile: the env that points it here isn't set yet in this process.
224
- write(path.join(path.dirname(configFile), "scheduler", "leases.json"), JSON.stringify(leases));
225
226
  }
227
+ const now = Date.now();
228
+ const queue = (opts.queue ?? []).map((entry, i) => {
229
+ const [feature = entry, waitedMin, services] = QUEUE_ENTRY.exec(entry)?.slice(1) ?? [];
230
+ if (waitedMin === undefined)
231
+ return feature;
232
+ const ws = path.join(root, "ws", feature);
233
+ const names = services?.split(",");
234
+ // 1 CPU and 1 GiB each, so `budget status` and admission have a cost to show and price.
235
+ const compose = Object.fromEntries((names ?? ["app"]).map((s) => [
236
+ s,
237
+ {
238
+ image: "fixture",
239
+ deploy: { resources: { limits: { cpus: "1" }, reservations: { memory: "1g" } } },
240
+ },
241
+ ]));
242
+ write(path.join(ws, COMPOSE_FILE), YAML.stringify({ services: compose }));
243
+ leases[feature] = { slot: Object.keys(leases).length + 1, workspace: ws };
244
+ write(waitingPath(ws), JSON.stringify({
245
+ position: i + 1,
246
+ reason: "waiting for capacity",
247
+ ...(names && { services: names }),
248
+ since: new Date(now - Number(waitedMin) * 60_000).toISOString(),
249
+ }));
250
+ return feature;
251
+ });
252
+ // leasesPath() beside configFile: the env that points it here isn't set yet in this process.
253
+ if (Object.keys(leases).length)
254
+ write(path.join(path.dirname(configFile), "scheduler", "leases.json"), JSON.stringify(leases));
226
255
  if (opts.queue)
227
- write(path.join(path.dirname(configFile), "scheduler", "queue.json"), JSON.stringify(opts.queue));
256
+ write(path.join(path.dirname(configFile), "scheduler", "queue.json"), JSON.stringify(queue));
228
257
  const containers = (opts.containers ?? []).map((c) => {
229
258
  const ws = path.join(root, "ws", c.workspace);
230
259
  fs.mkdirSync(ws, { recursive: true });
@@ -291,7 +320,7 @@ const SCRIPT = `#!/bin/sh
291
320
  # Generated by \`werkmeister workspace init\` (SW-292); rerun it to regenerate.
292
321
  # Runs this workspace's own built werkmeister CLI against a seeded fixture workspace, removed on exit:
293
322
  # temp HOME and registry, a local bare origin, logging fakes for gh and docker, dead Docker and daemon.
294
- # usage: with-fixture-workspace [--no-wait] [--gate] [--bare] [--daemon] [--exec-runs] [--merged] [--behind] [--slots-full] [--running <file>] [--queue <feature>[,<feature>]...] [--issue <ref>] [--pr-field <key>=<value>]... [--workspace <file>] [--config <file>] [--services <file>] [--fragment <file>] [--change <path>] [--change-base <file>] [--change-branch <file>] [--fragment-change <file>] [--print <file>]... <werkmeister args> [--then <werkmeister args>]...
323
+ # usage: with-fixture-workspace [--no-wait] [--gate] [--bare] [--daemon] [--exec-runs] [--merged] [--behind] [--slots-full] [--running <file>] [--queue <feature>[,<feature>]... | --queue <feature>:<waitedMin>[:<service>,...]]... [--issue <ref>] [--pr-field <key>=<value>]... [--workspace <file>] [--config <file>] [--services <file>] [--fragment <file>] [--change <path>] [--change-base <file>] [--change-branch <file>] [--fragment-change <file>] [--print <file>]... <werkmeister args> [--then <werkmeister args>]...
295
324
  # It only ever runs that CLI, never another command, so one allow rule can cover it (SW-172, SW-231);
296
325
  # --exec-runs, given first, also runs the registry's rows on the host, so the workspace asks before it (SW-473).
297
326
  ws=$(cd "$(dirname "$0")/../.." && pwd -P) || exit 1
@@ -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' }