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.
@@ -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
- * Field key → why `formData` can't be submitted against a `buildFormSchema` bundle: required, pattern and choices,
186
- * plus `repoSelectionError` (under `services`). Empty when it can. For renderers without a JSON Schema validator
187
- * (the /workspaces pane); the browser form's AJV covers the schema part and calls `repoSelectionError` itself.
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
- * Fill-empty merge of an issue's fields into form data: a field already filled is never clobbered, so re-fetching
214
- * is safe. `issue_id` is the exception — the lookup normalizes it (`api#7` → `acme/api#7`), so the canonical ref wins.
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 };
@@ -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 (proposal § 4.3 projection rows). */
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
- * Bring shared infrastructure up: generated files, the corporate CA, the
29
- * compose stack, and the host web servers.
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
- * Returns whether the compose stack itself started — the caller reports it as
32
- * the "check docker and your kubeconfig" hint. Health is deliberately a second
33
- * call (`infraHealth`), because the CLI prints its section header between the
34
- * two and a library that owned both would have to print that header itself.
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
- * Bring shared infrastructure up: generated files, the corporate CA, the
227
- * compose stack, and the host web servers.
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
- * Returns whether the compose stack itself started — the caller reports it as
230
- * the "check docker and your kubeconfig" hint. Health is deliberately a second
231
- * call (`infraHealth`), because the CLI prints its section header between the
232
- * two and a library that owned both would have to print that header itself.
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
@@ -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
- /** The tracker for `at` (see projectFor), else the machine's (`overrides.issue_tracker`). */
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
@@ -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
- /** The tracker for `at` (see projectFor), else the machine's (`overrides.issue_tracker`). */
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()];
@@ -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
- /** Read the SERVICES list from <workspace>/.env (written by init-workspace). */
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
- /** Read the SERVICES list from <workspace>/.env (written by init-workspace). */
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()) {
@@ -214,8 +214,28 @@ export declare function openPrs(ws: string, only?: string, deps?: Deps): Promise
214
214
  retry?: true;
215
215
  }>;
216
216
  /**
217
- * `werkmeister pr status`: reads each of *ws*'s opened PRs from `gh`, writes merged/shipped/review
218
- * state back to its PR file, moves the issue, and commits the record when anything changed.
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
- * `werkmeister pr watch` (desktop: false) and the werkmeister mod's timer (desktop: true): one
369
- * pass over every workspace. Headless claims are delivered here; desktop claims are returned
370
- * for the mod to send through the app, then one idle-reaper pass. Never merges and
371
- * never closes out.
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
- /** The workspace's place in the lifecycle, from files only — cheap enough for the pane's poll. */
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 sync hasn't run (SW-340). */
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
- * The one end-of-workspace verb (#160). Shipped: close the issue, write closeout.md, remove, delete
459
- * the merged branches. With *abandon*: record the reason, leave the issue, remove (which pushes every
460
- * branch) and keep the branches. With *noPr*: the work changed no repo, so close as done
461
- * with the reason instead of a PR.
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;
@@ -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
- * `werkmeister pr status`: reads each of *ws*'s opened PRs from `gh`, writes merged/shipped/review
1427
- * state back to its PR file, moves the issue, and commits the record when anything changed.
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
- * `werkmeister pr watch` (desktop: false) and the werkmeister mod's timer (desktop: true): one
2075
- * pass over every workspace. Headless claims are delivered here; desktop claims are returned
2076
- * for the mod to send through the app, then one idle-reaper pass. Never merges and
2077
- * never closes out.
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
- /** The workspace's place in the lifecycle, from files only — cheap enough for the pane's poll. */
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
- * The one end-of-workspace verb (#160). Shipped: close the issue, write closeout.md, remove, delete
2461
- * the merged branches. With *abandon*: record the reason, leave the issue, remove (which pushes every
2462
- * branch) and keep the branches. With *noPr*: the work changed no repo, so close as done
2463
- * with the reason instead of a PR.
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();
@@ -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
- * One stats sweep, as `docker stats --no-stream` makes it, for every workspace at
82
- * once. Cut off after *timeoutMs*: a wedged daemon gives partial numbers, never a hang.
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
- * One stats sweep, as `docker stats --no-stream` makes it, for every workspace at
174
- * once. Cut off after *timeoutMs*: a wedged daemon gives partial numbers, never a hang.
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));