werkmeister-core 0.91.2 → 0.91.3
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 +6 -0
- package/dist/agent_state.d.ts +16 -1
- package/dist/agent_state.js +16 -1
- package/dist/compose.d.ts +13 -1
- package/dist/daemon_client.d.ts +130 -10
- package/dist/daemon_client.js +105 -8
- package/dist/errors.d.ts +33 -12
- package/dist/errors.js +40 -12
- package/dist/form_schema.d.ts +40 -5
- package/dist/form_schema.js +42 -5
- package/dist/harness/types.d.ts +1 -1
- package/dist/infra.d.ts +27 -6
- package/dist/infra.js +31 -6
- package/dist/issue_tracker.d.ts +23 -1
- package/dist/issue_tracker.js +24 -1
- package/dist/lifecycle.d.ts +16 -1
- package/dist/lifecycle.js +16 -1
- package/dist/pr_lifecycle.d.ts +99 -12
- package/dist/pr_lifecycle.js +98 -11
- package/dist/resources.d.ts +22 -2
- package/dist/resources.js +22 -2
- package/dist/sandbox.d.ts +367 -83
- package/dist/sandbox.js +359 -80
- package/dist/scheduler_client.d.ts +36 -4
- package/dist/scheduler_client.js +36 -4
- package/dist/status.d.ts +28 -1
- package/dist/status.js +28 -1
- package/dist/telepresence.d.ts +55 -14
- package/dist/telepresence.js +62 -14
- package/package.json +2 -1
package/dist/form_schema.js
CHANGED
|
@@ -181,10 +181,29 @@ export function repoSelectionError(formData) {
|
|
|
181
181
|
return "Select at least one service (or add a repo below) — a workspace needs at least one repo.";
|
|
182
182
|
}
|
|
183
183
|
const blank = (v) => v == null || v === "" || (Array.isArray(v) && v.length === 0);
|
|
184
|
+
// For renderers without a JSON Schema validator (the /workspaces pane); the
|
|
185
|
+
// browser form's AJV covers the schema part and calls `repoSelectionError` itself.
|
|
184
186
|
/**
|
|
185
|
-
*
|
|
186
|
-
*
|
|
187
|
-
*
|
|
187
|
+
* Checks new-workspace form data against the form's schema, without a JSON
|
|
188
|
+
* Schema validator. It checks required fields, allowed choices and patterns,
|
|
189
|
+
* and that at least one service or repo is picked. Runs in-process.
|
|
190
|
+
*
|
|
191
|
+
* @param bundle - The form schema; only `schema.properties` and
|
|
192
|
+
* `schema.required` are read.
|
|
193
|
+
* @param formData - The field values to check.
|
|
194
|
+
* @returns Field key → why that field can't be submitted (the repo check is
|
|
195
|
+
* reported under `services`). Empty when the data can be submitted.
|
|
196
|
+
*
|
|
197
|
+
* @example
|
|
198
|
+
* ```ts
|
|
199
|
+
* import { validateFormData } from "werkmeister-core/sdk";
|
|
200
|
+
*
|
|
201
|
+
* const errors = validateFormData(
|
|
202
|
+
* { schema: { properties: { feature: { type: "string", pattern: "^[a-z-]+$" } }, required: ["feature"] } },
|
|
203
|
+
* { feature: "Login Page", services: ["api"] },
|
|
204
|
+
* );
|
|
205
|
+
* console.log(errors); // { feature: '"Login Page" doesn\'t match the expected format' }
|
|
206
|
+
* ```
|
|
188
207
|
*/
|
|
189
208
|
export function validateFormData(bundle, formData) {
|
|
190
209
|
const errors = {};
|
|
@@ -210,8 +229,26 @@ export function validateFormData(bundle, formData) {
|
|
|
210
229
|
return errors;
|
|
211
230
|
}
|
|
212
231
|
/**
|
|
213
|
-
*
|
|
214
|
-
*
|
|
232
|
+
* Merges fields fetched from an issue into new-workspace form data, filling only
|
|
233
|
+
* empty fields, so a field the person already filled is never overwritten and
|
|
234
|
+
* fetching again is safe. `issue_id` is the exception: the fetched one always
|
|
235
|
+
* wins, because the lookup returns the canonical ref (`api#7` becomes
|
|
236
|
+
* `acme/api#7`). Runs in-process and returns a new object.
|
|
237
|
+
*
|
|
238
|
+
* @param current - The form data as it is now.
|
|
239
|
+
* @param incoming - The fields fetched from the issue.
|
|
240
|
+
* @returns A copy of `current` with the empty fields filled from `incoming`.
|
|
241
|
+
*
|
|
242
|
+
* @example
|
|
243
|
+
* ```ts
|
|
244
|
+
* import { mergeFormData } from "werkmeister-core/sdk";
|
|
245
|
+
*
|
|
246
|
+
* const merged = mergeFormData(
|
|
247
|
+
* { feature: "login", description: "" },
|
|
248
|
+
* { feature: "sign-in", description: "Add SSO", issue_id: "PROJ-42" },
|
|
249
|
+
* );
|
|
250
|
+
* console.log(merged); // { feature: "login", description: "Add SSO", issue_id: "PROJ-42" }
|
|
251
|
+
* ```
|
|
215
252
|
*/
|
|
216
253
|
export function mergeFormData(current, incoming) {
|
|
217
254
|
const out = { ...current };
|
package/dist/harness/types.d.ts
CHANGED
|
@@ -24,7 +24,7 @@ export type HooksSupport = {
|
|
|
24
24
|
/** The werkmeister hooks this harness cannot run, for the printed line and the `hooks` tool. */
|
|
25
25
|
missing: string;
|
|
26
26
|
};
|
|
27
|
-
/** Where one harness reads werkmeister's context layer
|
|
27
|
+
/** Where one harness reads werkmeister's context layer: its instructions file and skills folder, and whether it takes hooks and subagents. */
|
|
28
28
|
export interface HarnessLayout {
|
|
29
29
|
/** The harness this layout belongs to. */
|
|
30
30
|
readonly id: HarnessId;
|
package/dist/infra.d.ts
CHANGED
|
@@ -25,13 +25,34 @@
|
|
|
25
25
|
*/
|
|
26
26
|
export declare function startSharedInfra(signal?: AbortSignal): Promise<boolean>;
|
|
27
27
|
/**
|
|
28
|
-
*
|
|
29
|
-
*
|
|
28
|
+
* Brings up werkmeister's shared infrastructure stack (the proxy, generated
|
|
29
|
+
* config, the corporate CA and the host web servers). It is the machine-wide
|
|
30
|
+
* stack every workspace routes through, not a workspace: to start a workspace's
|
|
31
|
+
* containers, use `runWorkspaceAction` with `"up"`.
|
|
30
32
|
*
|
|
31
|
-
*
|
|
32
|
-
* the
|
|
33
|
-
*
|
|
34
|
-
*
|
|
33
|
+
* Runs in-process. It writes the proxy files under `~/.werkmeister`, extracts
|
|
34
|
+
* the corporate CA, runs `docker compose up -d --build` for the shared stack
|
|
35
|
+
* (the Caddy proxy and the k8s port-forwards, plus any baseline services), then
|
|
36
|
+
* builds and starts the host web servers (the workspaces dashboard and the MCP
|
|
37
|
+
* server). Safe to re-run: the web servers restart only when they rebuilt.
|
|
38
|
+
*
|
|
39
|
+
* @param signal - Cancels the compose step. Already aborted: nothing is touched
|
|
40
|
+
* and it returns false. Aborted during `docker compose up`: compose stops and it
|
|
41
|
+
* returns false, but the host web servers are still built and started.
|
|
42
|
+
* @returns True when the compose stack started; false when it was cancelled,
|
|
43
|
+
* the shared compose file is missing, docker is missing or `docker compose`
|
|
44
|
+
* failed. It does not wait for the services to become healthy.
|
|
45
|
+
* @throws Error when the compose process fails to spawn for any other reason.
|
|
46
|
+
*
|
|
47
|
+
* @example
|
|
48
|
+
* ```ts
|
|
49
|
+
* import { infraUp } from "werkmeister-core/sdk";
|
|
50
|
+
*
|
|
51
|
+
* const started = await infraUp({ signal: AbortSignal.timeout(300_000) });
|
|
52
|
+
* if (!started) {
|
|
53
|
+
* console.error("Shared infrastructure did not start: check docker.");
|
|
54
|
+
* }
|
|
55
|
+
* ```
|
|
35
56
|
*/
|
|
36
57
|
export declare function up({ signal }?: {
|
|
37
58
|
signal?: AbortSignal;
|
package/dist/infra.js
CHANGED
|
@@ -222,14 +222,39 @@ async function checkInfraHealth() {
|
|
|
222
222
|
}
|
|
223
223
|
return services;
|
|
224
224
|
}
|
|
225
|
+
// Health is deliberately a second call (`infraHealth`), because the CLI prints
|
|
226
|
+
// its section header between the two and a library that owned both would have
|
|
227
|
+
// to print that header itself. The CLI turns a false return into the "check
|
|
228
|
+
// docker and your kubeconfig" hint.
|
|
225
229
|
/**
|
|
226
|
-
*
|
|
227
|
-
*
|
|
230
|
+
* Brings up werkmeister's shared infrastructure stack (the proxy, generated
|
|
231
|
+
* config, the corporate CA and the host web servers). It is the machine-wide
|
|
232
|
+
* stack every workspace routes through, not a workspace: to start a workspace's
|
|
233
|
+
* containers, use `runWorkspaceAction` with `"up"`.
|
|
228
234
|
*
|
|
229
|
-
*
|
|
230
|
-
* the
|
|
231
|
-
*
|
|
232
|
-
*
|
|
235
|
+
* Runs in-process. It writes the proxy files under `~/.werkmeister`, extracts
|
|
236
|
+
* the corporate CA, runs `docker compose up -d --build` for the shared stack
|
|
237
|
+
* (the Caddy proxy and the k8s port-forwards, plus any baseline services), then
|
|
238
|
+
* builds and starts the host web servers (the workspaces dashboard and the MCP
|
|
239
|
+
* server). Safe to re-run: the web servers restart only when they rebuilt.
|
|
240
|
+
*
|
|
241
|
+
* @param signal - Cancels the compose step. Already aborted: nothing is touched
|
|
242
|
+
* and it returns false. Aborted during `docker compose up`: compose stops and it
|
|
243
|
+
* returns false, but the host web servers are still built and started.
|
|
244
|
+
* @returns True when the compose stack started; false when it was cancelled,
|
|
245
|
+
* the shared compose file is missing, docker is missing or `docker compose`
|
|
246
|
+
* failed. It does not wait for the services to become healthy.
|
|
247
|
+
* @throws Error when the compose process fails to spawn for any other reason.
|
|
248
|
+
*
|
|
249
|
+
* @example
|
|
250
|
+
* ```ts
|
|
251
|
+
* import { infraUp } from "werkmeister-core/sdk";
|
|
252
|
+
*
|
|
253
|
+
* const started = await infraUp({ signal: AbortSignal.timeout(300_000) });
|
|
254
|
+
* if (!started) {
|
|
255
|
+
* console.error("Shared infrastructure did not start: check docker.");
|
|
256
|
+
* }
|
|
257
|
+
* ```
|
|
233
258
|
*/
|
|
234
259
|
export async function up({ signal } = {}) {
|
|
235
260
|
// Ahead of everything, not just of the compose spawn: the setup below writes
|
package/dist/issue_tracker.d.ts
CHANGED
|
@@ -47,7 +47,29 @@ export interface TrackerAt {
|
|
|
47
47
|
export declare function projectFor(at?: TrackerAt): Project | null;
|
|
48
48
|
/** The one project marked `default: true`; null when none, or more than one. */
|
|
49
49
|
export declare function defaultProject(): Project | null;
|
|
50
|
-
/**
|
|
50
|
+
/**
|
|
51
|
+
* Returns the issue tracker (Jira, GitHub, ...) for a lookup. It picks the
|
|
52
|
+
* project named by `at.project`, else the first configured project whose tracker
|
|
53
|
+
* finds an issue ref in `at.text` that its scope holds; with neither, it falls
|
|
54
|
+
* back to the machine's tracker (`overrides.issue_tracker` in the config).
|
|
55
|
+
* Runs in-process and only reads the config; the tracker's own methods make the
|
|
56
|
+
* network calls.
|
|
57
|
+
*
|
|
58
|
+
* @param at - Where the lookup happens. `project` is a project name from the
|
|
59
|
+
* config's `projects:`; `text` is any text holding an issue ref (a key, a URL,
|
|
60
|
+
* a branch name). Omit it for the machine's tracker.
|
|
61
|
+
* @returns The tracker: parse refs with `parseRef`, build links with `url`,
|
|
62
|
+
* read issues with `fetchIssue`.
|
|
63
|
+
*
|
|
64
|
+
* @example
|
|
65
|
+
* ```ts
|
|
66
|
+
* import { issueTracker } from "werkmeister-core/sdk";
|
|
67
|
+
*
|
|
68
|
+
* const tracker = issueTracker({ text: "feature/PROJ-42-login" });
|
|
69
|
+
* const ref = tracker.parseRef("feature/PROJ-42-login");
|
|
70
|
+
* if (ref) console.log(tracker.url(ref));
|
|
71
|
+
* ```
|
|
72
|
+
*/
|
|
51
73
|
export declare function issueTracker(at?: TrackerAt): IssueTrackerStrategy;
|
|
52
74
|
/**
|
|
53
75
|
* A new workspace's project (SW-104): `named`, else the one whose scope holds
|
package/dist/issue_tracker.js
CHANGED
|
@@ -81,7 +81,30 @@ export function defaultProject() {
|
|
|
81
81
|
const marked = loadProjects().filter((p) => p.default);
|
|
82
82
|
return marked.length === 1 ? marked[0] : null;
|
|
83
83
|
}
|
|
84
|
-
|
|
84
|
+
// Project resolution is `projectFor`.
|
|
85
|
+
/**
|
|
86
|
+
* Returns the issue tracker (Jira, GitHub, ...) for a lookup. It picks the
|
|
87
|
+
* project named by `at.project`, else the first configured project whose tracker
|
|
88
|
+
* finds an issue ref in `at.text` that its scope holds; with neither, it falls
|
|
89
|
+
* back to the machine's tracker (`overrides.issue_tracker` in the config).
|
|
90
|
+
* Runs in-process and only reads the config; the tracker's own methods make the
|
|
91
|
+
* network calls.
|
|
92
|
+
*
|
|
93
|
+
* @param at - Where the lookup happens. `project` is a project name from the
|
|
94
|
+
* config's `projects:`; `text` is any text holding an issue ref (a key, a URL,
|
|
95
|
+
* a branch name). Omit it for the machine's tracker.
|
|
96
|
+
* @returns The tracker: parse refs with `parseRef`, build links with `url`,
|
|
97
|
+
* read issues with `fetchIssue`.
|
|
98
|
+
*
|
|
99
|
+
* @example
|
|
100
|
+
* ```ts
|
|
101
|
+
* import { issueTracker } from "werkmeister-core/sdk";
|
|
102
|
+
*
|
|
103
|
+
* const tracker = issueTracker({ text: "feature/PROJ-42-login" });
|
|
104
|
+
* const ref = tracker.parseRef("feature/PROJ-42-login");
|
|
105
|
+
* if (ref) console.log(tracker.url(ref));
|
|
106
|
+
* ```
|
|
107
|
+
*/
|
|
85
108
|
export function issueTracker(at) {
|
|
86
109
|
const project = at ? projectFor(at) : null;
|
|
87
110
|
return project ? projectTracker(project) : REGISTRY[loadIssueTracker()];
|
package/dist/lifecycle.d.ts
CHANGED
|
@@ -128,7 +128,22 @@ export declare function describeLease(l: Lease): string;
|
|
|
128
128
|
* queued `up` and a timed-out service start (SW-675). *stays*: still queued, so the grant starts it.
|
|
129
129
|
*/
|
|
130
130
|
export declare function capacityWait(feature: string, position: number, stays: boolean): string;
|
|
131
|
-
/**
|
|
131
|
+
/**
|
|
132
|
+
* Reads the services a workspace runs: the `SERVICES` list in its `.env`, which
|
|
133
|
+
* `werkmeister workspace init` writes. Runs in-process and only reads that file.
|
|
134
|
+
*
|
|
135
|
+
* @param workspace - Absolute path of the workspace folder.
|
|
136
|
+
* @returns The service names, in file order. Empty when the `.env` or its
|
|
137
|
+
* `SERVICES` line is missing.
|
|
138
|
+
*
|
|
139
|
+
* @example
|
|
140
|
+
* ```ts
|
|
141
|
+
* import { readServicesFromWorkspace, resolveWorkspaceDir } from "werkmeister-core/sdk";
|
|
142
|
+
*
|
|
143
|
+
* const dir = await resolveWorkspaceDir("my-workspace");
|
|
144
|
+
* console.log(readServicesFromWorkspace(dir)); // e.g. ["api", "web"]
|
|
145
|
+
* ```
|
|
146
|
+
*/
|
|
132
147
|
export declare function readServicesFromWorkspace(workspace: string): string[];
|
|
133
148
|
/**
|
|
134
149
|
* True when this process runs inside *feature*'s own container: every
|
package/dist/lifecycle.js
CHANGED
|
@@ -447,7 +447,22 @@ function readSlotFromWorkspace(workspace) {
|
|
|
447
447
|
}
|
|
448
448
|
return null;
|
|
449
449
|
}
|
|
450
|
-
/**
|
|
450
|
+
/**
|
|
451
|
+
* Reads the services a workspace runs: the `SERVICES` list in its `.env`, which
|
|
452
|
+
* `werkmeister workspace init` writes. Runs in-process and only reads that file.
|
|
453
|
+
*
|
|
454
|
+
* @param workspace - Absolute path of the workspace folder.
|
|
455
|
+
* @returns The service names, in file order. Empty when the `.env` or its
|
|
456
|
+
* `SERVICES` line is missing.
|
|
457
|
+
*
|
|
458
|
+
* @example
|
|
459
|
+
* ```ts
|
|
460
|
+
* import { readServicesFromWorkspace, resolveWorkspaceDir } from "werkmeister-core/sdk";
|
|
461
|
+
*
|
|
462
|
+
* const dir = await resolveWorkspaceDir("my-workspace");
|
|
463
|
+
* console.log(readServicesFromWorkspace(dir)); // e.g. ["api", "web"]
|
|
464
|
+
* ```
|
|
465
|
+
*/
|
|
451
466
|
export function readServicesFromWorkspace(workspace) {
|
|
452
467
|
const envFile = path.join(workspace, ".env");
|
|
453
468
|
if (!fs.existsSync(envFile) || !fs.statSync(envFile).isFile()) {
|
package/dist/pr_lifecycle.d.ts
CHANGED
|
@@ -214,8 +214,28 @@ export declare function openPrs(ws: string, only?: string, deps?: Deps): Promise
|
|
|
214
214
|
retry?: true;
|
|
215
215
|
}>;
|
|
216
216
|
/**
|
|
217
|
-
*
|
|
218
|
-
*
|
|
217
|
+
* Checks each pull request a workspace has opened and records what changed: the
|
|
218
|
+
* same pass `werkmeister pr status` makes. Runs in-process and calls `gh` for
|
|
219
|
+
* each open PR, and `git` to find the release tag of a merged one. It has side
|
|
220
|
+
* effects: it rewrites the workspace's PR files (merged, shipped, closed, changes
|
|
221
|
+
* requested), moves the issue in its tracker, stops the workspace's containers
|
|
222
|
+
* once a PR has merged, and commits and pushes the record when anything changed.
|
|
223
|
+
*
|
|
224
|
+
* @param ws - The workspace folder's absolute path, e.g. from {@link resolveWorkspaceDir}.
|
|
225
|
+
* @param deps - The services it uses; leave it at its default.
|
|
226
|
+
* @param opts - `gh: false` skips the `gh` lookups and only re-checks merged PRs for a release.
|
|
227
|
+
* @returns `lines`, one status line per PR then any issue move or commit;
|
|
228
|
+
* `changed`, true when a PR file was rewritten; and `views`, the `gh pr view`
|
|
229
|
+
* data of each PR still open, keyed by PR file path.
|
|
230
|
+
*
|
|
231
|
+
* @example
|
|
232
|
+
* ```ts
|
|
233
|
+
* import { refreshPrStatus, resolveWorkspaceDir } from "werkmeister-core/sdk";
|
|
234
|
+
*
|
|
235
|
+
* const ws = await resolveWorkspaceDir("my-workspace");
|
|
236
|
+
* const { lines, changed } = await refreshPrStatus(ws);
|
|
237
|
+
* console.log(lines.join("\n"), changed ? "(recorded)" : "");
|
|
238
|
+
* ```
|
|
219
239
|
*/
|
|
220
240
|
export declare function refreshPrStatus(ws: string, deps?: Deps, opts?: {
|
|
221
241
|
gh?: boolean;
|
|
@@ -365,10 +385,30 @@ export declare function shipMerged(workspaces: string[], deps?: Deps, lockFile?:
|
|
|
365
385
|
*/
|
|
366
386
|
export declare function deliverHeadless(cb: PrCallback): Promise<string[]>;
|
|
367
387
|
/**
|
|
368
|
-
*
|
|
369
|
-
*
|
|
370
|
-
*
|
|
371
|
-
*
|
|
388
|
+
* Makes one pass over every workspace's open pull requests, the same pass
|
|
389
|
+
* `werkmeister pr watch` makes, and wakes the Claude sessions that opened them
|
|
390
|
+
* when a PR needs work (a failing check, a conflict, a review). Runs in-process
|
|
391
|
+
* and calls `gh`. It has side effects: it resumes those sessions headless with a
|
|
392
|
+
* message, and, unless `repo` is given, stops the containers of workspaces that
|
|
393
|
+
* have sat idle. It never merges a PR and never closes out a workspace.
|
|
394
|
+
*
|
|
395
|
+
* @param opts - `desktop: true` returns the messages meant for sessions open in
|
|
396
|
+
* the Claude desktop app instead of leaving them; `repo` (`owner/name`) limits
|
|
397
|
+
* the pass to workspaces with a PR in that repo.
|
|
398
|
+
* @param deps - The services it uses; leave it at its default.
|
|
399
|
+
* @param send - How a message reaches a session; leave it at its default.
|
|
400
|
+
* @param idleLock - The lock file that keeps two idle-stop passes apart; leave it at its default.
|
|
401
|
+
* @returns `ok` (always true), `lines` (what the pass did, one line per event),
|
|
402
|
+
* and `desktop` (with `desktop: true`, each message to send: its `ws`, `session`, `url` and `message`).
|
|
403
|
+
* @throws Error when `repo` is given and another pass is already running.
|
|
404
|
+
*
|
|
405
|
+
* @example
|
|
406
|
+
* ```ts
|
|
407
|
+
* import { watchPrs } from "werkmeister-core/sdk";
|
|
408
|
+
*
|
|
409
|
+
* const { lines } = await watchPrs({ desktop: false });
|
|
410
|
+
* for (const line of lines) console.log(line);
|
|
411
|
+
* ```
|
|
372
412
|
*/
|
|
373
413
|
export declare function watchPrs(opts: {
|
|
374
414
|
desktop: boolean;
|
|
@@ -407,7 +447,25 @@ export declare function newPr(ws: string, worktree: string, slug: string, deps?:
|
|
|
407
447
|
/** The report to print. */
|
|
408
448
|
lines: string[];
|
|
409
449
|
}>;
|
|
410
|
-
/**
|
|
450
|
+
/**
|
|
451
|
+
* Tells where a workspace is in its life, from its PR files and `closeout.md`
|
|
452
|
+
* alone. Runs in-process and synchronously; it reads only local files (no `gh`,
|
|
453
|
+
* no network), so it is cheap to call often. Run {@link refreshPrStatus} first
|
|
454
|
+
* for the latest state from GitHub.
|
|
455
|
+
*
|
|
456
|
+
* @param ws - The workspace folder's absolute path, e.g. from {@link resolveWorkspaceDir}.
|
|
457
|
+
* @returns `state`: `working`, `ready` (every PR approved), `pr-open`, `merged`,
|
|
458
|
+
* `shipped`, `closed-out` or `abandoned`; and `prs`, one entry per PR file.
|
|
459
|
+
* A workspace with no PR files, or a malformed one, reads as `working`.
|
|
460
|
+
*
|
|
461
|
+
* @example
|
|
462
|
+
* ```ts
|
|
463
|
+
* import { lifecycleOf, resolveWorkspaceDir } from "werkmeister-core/sdk";
|
|
464
|
+
*
|
|
465
|
+
* const { state, prs } = lifecycleOf(await resolveWorkspaceDir("my-workspace"));
|
|
466
|
+
* console.log(state, prs.map((p) => `${p.stem}: ${p.status}`).join(", "));
|
|
467
|
+
* ```
|
|
468
|
+
*/
|
|
411
469
|
export declare function lifecycleOf(ws: string): {
|
|
412
470
|
/** Where the workspace is, from its PR files and `closeout.md`. */
|
|
413
471
|
state: Lifecycle;
|
|
@@ -425,7 +483,7 @@ export declare function lifecycleOf(ws: string): {
|
|
|
425
483
|
release: string | null;
|
|
426
484
|
/** True when the PR file opts out of waiting for a release. */
|
|
427
485
|
skip_release: boolean;
|
|
428
|
-
/** The merged PR changed its registry fragment and the
|
|
486
|
+
/** The merged PR changed its service registry fragment and the machine registry hasn't been synced yet. */
|
|
429
487
|
registry_sync: boolean;
|
|
430
488
|
/** Absolute path of the PR file. */
|
|
431
489
|
path: string;
|
|
@@ -455,10 +513,39 @@ export declare function releaseVscodeSessions(ws: string, dir?: string): void;
|
|
|
455
513
|
*/
|
|
456
514
|
export declare function openTerminalSessions(ws: string, run?: Run, ownedDir?: string): Promise<string[]>;
|
|
457
515
|
/**
|
|
458
|
-
*
|
|
459
|
-
*
|
|
460
|
-
*
|
|
461
|
-
*
|
|
516
|
+
* Closes out a finished workspace and removes it. This is destructive: for a
|
|
517
|
+
* shipped workspace it moves the issue to done, writes `closeout.md`, removes
|
|
518
|
+
* the workspace (its containers, worktrees and folder) and deletes the merged
|
|
519
|
+
* branches, locally and on `origin`. Runs in-process and calls `git` and the
|
|
520
|
+
* issue tracker. Running it again after a removal that failed finishes the job.
|
|
521
|
+
*
|
|
522
|
+
* @param name - The workspace's folder name.
|
|
523
|
+
* @param opts - `abandon`: give up on unshipped work with this reason; the issue
|
|
524
|
+
* gets the reason as a comment, every branch is pushed and kept.
|
|
525
|
+
* `noPr`: the work changed no repo, so close it as done with this reason instead of a PR.
|
|
526
|
+
* `skipPostmortem`: close without a `postmortem.md`, with this reason.
|
|
527
|
+
* Each needs a non-empty reason; `noPr` can't be combined with the other two.
|
|
528
|
+
* @param deps - The services it uses; leave it at its default.
|
|
529
|
+
* @returns `command`, the matching CLI command; `output`, what it did, one step per line;
|
|
530
|
+
* `path`, the workspace folder (now removed); and `terminals`, `claude` sessions
|
|
531
|
+
* still running in that folder, for a person to exit.
|
|
532
|
+
* @throws `WorkspaceError` when `name` is not a workspace, a reason is
|
|
533
|
+
* empty, the options conflict, another close-out of it is running, the
|
|
534
|
+
* workspace has no `postmortem.md` (without `skipPostmortem`), or a PR is not
|
|
535
|
+
* yet shipped, closed or abandoned (without `abandon` or `noPr`).
|
|
536
|
+
*
|
|
537
|
+
* @example
|
|
538
|
+
* ```ts
|
|
539
|
+
* import { closeOut, WorkspaceError } from "werkmeister-core/sdk";
|
|
540
|
+
*
|
|
541
|
+
* try {
|
|
542
|
+
* const { output, terminals } = await closeOut("my-workspace");
|
|
543
|
+
* console.log(output, ...terminals);
|
|
544
|
+
* } catch (e) {
|
|
545
|
+
* if (e instanceof WorkspaceError) console.error(e.message);
|
|
546
|
+
* else throw e;
|
|
547
|
+
* }
|
|
548
|
+
* ```
|
|
462
549
|
*/
|
|
463
550
|
export declare function closeOut(name: string, opts?: {
|
|
464
551
|
abandon?: string;
|
package/dist/pr_lifecycle.js
CHANGED
|
@@ -1423,8 +1423,28 @@ export async function openPrs(ws, only, deps = defaultDeps()) {
|
|
|
1423
1423
|
return { ok, lines, ...(!ok && retryOnly && { retry: true }) };
|
|
1424
1424
|
}
|
|
1425
1425
|
/**
|
|
1426
|
-
*
|
|
1427
|
-
*
|
|
1426
|
+
* Checks each pull request a workspace has opened and records what changed: the
|
|
1427
|
+
* same pass `werkmeister pr status` makes. Runs in-process and calls `gh` for
|
|
1428
|
+
* each open PR, and `git` to find the release tag of a merged one. It has side
|
|
1429
|
+
* effects: it rewrites the workspace's PR files (merged, shipped, closed, changes
|
|
1430
|
+
* requested), moves the issue in its tracker, stops the workspace's containers
|
|
1431
|
+
* once a PR has merged, and commits and pushes the record when anything changed.
|
|
1432
|
+
*
|
|
1433
|
+
* @param ws - The workspace folder's absolute path, e.g. from {@link resolveWorkspaceDir}.
|
|
1434
|
+
* @param deps - The services it uses; leave it at its default.
|
|
1435
|
+
* @param opts - `gh: false` skips the `gh` lookups and only re-checks merged PRs for a release.
|
|
1436
|
+
* @returns `lines`, one status line per PR then any issue move or commit;
|
|
1437
|
+
* `changed`, true when a PR file was rewritten; and `views`, the `gh pr view`
|
|
1438
|
+
* data of each PR still open, keyed by PR file path.
|
|
1439
|
+
*
|
|
1440
|
+
* @example
|
|
1441
|
+
* ```ts
|
|
1442
|
+
* import { refreshPrStatus, resolveWorkspaceDir } from "werkmeister-core/sdk";
|
|
1443
|
+
*
|
|
1444
|
+
* const ws = await resolveWorkspaceDir("my-workspace");
|
|
1445
|
+
* const { lines, changed } = await refreshPrStatus(ws);
|
|
1446
|
+
* console.log(lines.join("\n"), changed ? "(recorded)" : "");
|
|
1447
|
+
* ```
|
|
1428
1448
|
*/
|
|
1429
1449
|
export async function refreshPrStatus(ws, deps = defaultDeps(),
|
|
1430
1450
|
// `gh: false` is check-in's sweep (SW-65): open → merged stays with `gh` in `pr status`.
|
|
@@ -2071,10 +2091,30 @@ async function fixLeftBehind(dir, deps) {
|
|
|
2071
2091
|
return (status.code !== 0 || !!status.stdout.trim() || unpushed.code !== 0 || !!unpushed.stdout.trim());
|
|
2072
2092
|
}
|
|
2073
2093
|
/**
|
|
2074
|
-
*
|
|
2075
|
-
*
|
|
2076
|
-
*
|
|
2077
|
-
*
|
|
2094
|
+
* Makes one pass over every workspace's open pull requests, the same pass
|
|
2095
|
+
* `werkmeister pr watch` makes, and wakes the Claude sessions that opened them
|
|
2096
|
+
* when a PR needs work (a failing check, a conflict, a review). Runs in-process
|
|
2097
|
+
* and calls `gh`. It has side effects: it resumes those sessions headless with a
|
|
2098
|
+
* message, and, unless `repo` is given, stops the containers of workspaces that
|
|
2099
|
+
* have sat idle. It never merges a PR and never closes out a workspace.
|
|
2100
|
+
*
|
|
2101
|
+
* @param opts - `desktop: true` returns the messages meant for sessions open in
|
|
2102
|
+
* the Claude desktop app instead of leaving them; `repo` (`owner/name`) limits
|
|
2103
|
+
* the pass to workspaces with a PR in that repo.
|
|
2104
|
+
* @param deps - The services it uses; leave it at its default.
|
|
2105
|
+
* @param send - How a message reaches a session; leave it at its default.
|
|
2106
|
+
* @param idleLock - The lock file that keeps two idle-stop passes apart; leave it at its default.
|
|
2107
|
+
* @returns `ok` (always true), `lines` (what the pass did, one line per event),
|
|
2108
|
+
* and `desktop` (with `desktop: true`, each message to send: its `ws`, `session`, `url` and `message`).
|
|
2109
|
+
* @throws Error when `repo` is given and another pass is already running.
|
|
2110
|
+
*
|
|
2111
|
+
* @example
|
|
2112
|
+
* ```ts
|
|
2113
|
+
* import { watchPrs } from "werkmeister-core/sdk";
|
|
2114
|
+
*
|
|
2115
|
+
* const { lines } = await watchPrs({ desktop: false });
|
|
2116
|
+
* for (const line of lines) console.log(line);
|
|
2117
|
+
* ```
|
|
2078
2118
|
*/
|
|
2079
2119
|
export async function watchPrs(opts, deps = defaultDeps(), send = deliverHeadless, idleLock = path.join(sandboxHome(), "idle-stop.lock")) {
|
|
2080
2120
|
const { workspaces } = await listWorkspaces();
|
|
@@ -2272,7 +2312,25 @@ export async function newPr(ws, worktree, slug, deps = defaultDeps()) {
|
|
|
2272
2312
|
],
|
|
2273
2313
|
};
|
|
2274
2314
|
}
|
|
2275
|
-
/**
|
|
2315
|
+
/**
|
|
2316
|
+
* Tells where a workspace is in its life, from its PR files and `closeout.md`
|
|
2317
|
+
* alone. Runs in-process and synchronously; it reads only local files (no `gh`,
|
|
2318
|
+
* no network), so it is cheap to call often. Run {@link refreshPrStatus} first
|
|
2319
|
+
* for the latest state from GitHub.
|
|
2320
|
+
*
|
|
2321
|
+
* @param ws - The workspace folder's absolute path, e.g. from {@link resolveWorkspaceDir}.
|
|
2322
|
+
* @returns `state`: `working`, `ready` (every PR approved), `pr-open`, `merged`,
|
|
2323
|
+
* `shipped`, `closed-out` or `abandoned`; and `prs`, one entry per PR file.
|
|
2324
|
+
* A workspace with no PR files, or a malformed one, reads as `working`.
|
|
2325
|
+
*
|
|
2326
|
+
* @example
|
|
2327
|
+
* ```ts
|
|
2328
|
+
* import { lifecycleOf, resolveWorkspaceDir } from "werkmeister-core/sdk";
|
|
2329
|
+
*
|
|
2330
|
+
* const { state, prs } = lifecycleOf(await resolveWorkspaceDir("my-workspace"));
|
|
2331
|
+
* console.log(state, prs.map((p) => `${p.stem}: ${p.status}`).join(", "));
|
|
2332
|
+
* ```
|
|
2333
|
+
*/
|
|
2276
2334
|
export function lifecycleOf(ws) {
|
|
2277
2335
|
let files = [];
|
|
2278
2336
|
try {
|
|
@@ -2457,10 +2515,39 @@ export async function openTerminalSessions(ws, run = execRun, ownedDir = vscodeT
|
|
|
2457
2515
|
return out;
|
|
2458
2516
|
}
|
|
2459
2517
|
/**
|
|
2460
|
-
*
|
|
2461
|
-
*
|
|
2462
|
-
*
|
|
2463
|
-
*
|
|
2518
|
+
* Closes out a finished workspace and removes it. This is destructive: for a
|
|
2519
|
+
* shipped workspace it moves the issue to done, writes `closeout.md`, removes
|
|
2520
|
+
* the workspace (its containers, worktrees and folder) and deletes the merged
|
|
2521
|
+
* branches, locally and on `origin`. Runs in-process and calls `git` and the
|
|
2522
|
+
* issue tracker. Running it again after a removal that failed finishes the job.
|
|
2523
|
+
*
|
|
2524
|
+
* @param name - The workspace's folder name.
|
|
2525
|
+
* @param opts - `abandon`: give up on unshipped work with this reason; the issue
|
|
2526
|
+
* gets the reason as a comment, every branch is pushed and kept.
|
|
2527
|
+
* `noPr`: the work changed no repo, so close it as done with this reason instead of a PR.
|
|
2528
|
+
* `skipPostmortem`: close without a `postmortem.md`, with this reason.
|
|
2529
|
+
* Each needs a non-empty reason; `noPr` can't be combined with the other two.
|
|
2530
|
+
* @param deps - The services it uses; leave it at its default.
|
|
2531
|
+
* @returns `command`, the matching CLI command; `output`, what it did, one step per line;
|
|
2532
|
+
* `path`, the workspace folder (now removed); and `terminals`, `claude` sessions
|
|
2533
|
+
* still running in that folder, for a person to exit.
|
|
2534
|
+
* @throws `WorkspaceError` when `name` is not a workspace, a reason is
|
|
2535
|
+
* empty, the options conflict, another close-out of it is running, the
|
|
2536
|
+
* workspace has no `postmortem.md` (without `skipPostmortem`), or a PR is not
|
|
2537
|
+
* yet shipped, closed or abandoned (without `abandon` or `noPr`).
|
|
2538
|
+
*
|
|
2539
|
+
* @example
|
|
2540
|
+
* ```ts
|
|
2541
|
+
* import { closeOut, WorkspaceError } from "werkmeister-core/sdk";
|
|
2542
|
+
*
|
|
2543
|
+
* try {
|
|
2544
|
+
* const { output, terminals } = await closeOut("my-workspace");
|
|
2545
|
+
* console.log(output, ...terminals);
|
|
2546
|
+
* } catch (e) {
|
|
2547
|
+
* if (e instanceof WorkspaceError) console.error(e.message);
|
|
2548
|
+
* else throw e;
|
|
2549
|
+
* }
|
|
2550
|
+
* ```
|
|
2464
2551
|
*/
|
|
2465
2552
|
export async function closeOut(name, opts = {}, deps = defaultDeps()) {
|
|
2466
2553
|
const why = opts.abandon?.trim();
|
package/dist/resources.d.ts
CHANGED
|
@@ -78,7 +78,27 @@ export declare function hostSummary(stats: ContainerStat[], load?: number[], cor
|
|
|
78
78
|
/** One line for a failure, so a timeout under load reads as load (SW-209). */
|
|
79
79
|
export declare function loadNote(load: number[], cores: number): string;
|
|
80
80
|
/**
|
|
81
|
-
*
|
|
82
|
-
*
|
|
81
|
+
* Measures CPU and memory for every workspace at once, from one
|
|
82
|
+
* `docker stats --no-stream` sweep, plus the host's load. Runs in-process; it
|
|
83
|
+
* shells out to docker.
|
|
84
|
+
*
|
|
85
|
+
* @param timeoutMs - Cuts the sweep off after this many milliseconds (default
|
|
86
|
+
* 20 000). A wedged docker gives partial numbers, never a hang.
|
|
87
|
+
* @returns `projects`: usage keyed by compose project, each with `cpuPercent`
|
|
88
|
+
* (percent of one core, summed over its containers) and `memMib`. `host`:
|
|
89
|
+
* `load` (1, 5 and 15 minute load averages), `cores`, and
|
|
90
|
+
* `featureCpuPercent` (every workspace container's CPU summed, shared
|
|
91
|
+
* infrastructure left out).
|
|
92
|
+
*
|
|
93
|
+
* @example
|
|
94
|
+
* ```ts
|
|
95
|
+
* import { getWorkspaceResources } from "werkmeister-core/sdk";
|
|
96
|
+
*
|
|
97
|
+
* const { projects, host } = await getWorkspaceResources(10_000);
|
|
98
|
+
* for (const [project, use] of Object.entries(projects)) {
|
|
99
|
+
* console.log(`${project}: ${use.cpuPercent}% CPU, ${use.memMib} MiB`);
|
|
100
|
+
* }
|
|
101
|
+
* console.log(`load ${host.load[0]} on ${host.cores} cores`);
|
|
102
|
+
* ```
|
|
83
103
|
*/
|
|
84
104
|
export declare function getWorkspaceResources(timeoutMs?: number): Promise<WorkspaceResources>;
|
package/dist/resources.js
CHANGED
|
@@ -170,8 +170,28 @@ export function loadNote(load, cores) {
|
|
|
170
170
|
return `host load ${one} / ${five} / ${fifteen} (1, 5, 15 min) on ${cores} cores`;
|
|
171
171
|
}
|
|
172
172
|
/**
|
|
173
|
-
*
|
|
174
|
-
*
|
|
173
|
+
* Measures CPU and memory for every workspace at once, from one
|
|
174
|
+
* `docker stats --no-stream` sweep, plus the host's load. Runs in-process; it
|
|
175
|
+
* shells out to docker.
|
|
176
|
+
*
|
|
177
|
+
* @param timeoutMs - Cuts the sweep off after this many milliseconds (default
|
|
178
|
+
* 20 000). A wedged docker gives partial numbers, never a hang.
|
|
179
|
+
* @returns `projects`: usage keyed by compose project, each with `cpuPercent`
|
|
180
|
+
* (percent of one core, summed over its containers) and `memMib`. `host`:
|
|
181
|
+
* `load` (1, 5 and 15 minute load averages), `cores`, and
|
|
182
|
+
* `featureCpuPercent` (every workspace container's CPU summed, shared
|
|
183
|
+
* infrastructure left out).
|
|
184
|
+
*
|
|
185
|
+
* @example
|
|
186
|
+
* ```ts
|
|
187
|
+
* import { getWorkspaceResources } from "werkmeister-core/sdk";
|
|
188
|
+
*
|
|
189
|
+
* const { projects, host } = await getWorkspaceResources(10_000);
|
|
190
|
+
* for (const [project, use] of Object.entries(projects)) {
|
|
191
|
+
* console.log(`${project}: ${use.cpuPercent}% CPU, ${use.memMib} MiB`);
|
|
192
|
+
* }
|
|
193
|
+
* console.log(`load ${host.load[0]} on ${host.cores} cores`);
|
|
194
|
+
* ```
|
|
175
195
|
*/
|
|
176
196
|
export async function getWorkspaceResources(timeoutMs = 20_000) {
|
|
177
197
|
const stats = await containerStats(AbortSignal.timeout(timeoutMs));
|