werkmeister-core 0.90.5 → 0.91.0

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 (51) hide show
  1. package/CHANGELOG.md +14 -0
  2. package/dist/build_caches.d.ts +14 -1
  3. package/dist/docker.d.ts +8 -1
  4. package/dist/docker.js +2 -2
  5. package/dist/dockerode_load.d.ts +2 -0
  6. package/dist/dockerode_load.js +11 -0
  7. package/dist/form_schema.d.ts +9 -1
  8. package/dist/fragment_detect/assist.d.ts +20 -0
  9. package/dist/fragment_detect/assist.js +2 -0
  10. package/dist/fragment_detect/plan.d.ts +46 -0
  11. package/dist/fragment_detect/plan.js +46 -4
  12. package/dist/fragment_detect/render.d.ts +5 -0
  13. package/dist/fragment_detect/render.js +1 -0
  14. package/dist/fragment_detect/types.d.ts +7 -0
  15. package/dist/fragment_detect/validate.d.ts +5 -0
  16. package/dist/fragment_detect/validate.js +5 -0
  17. package/dist/graduate.d.ts +5 -0
  18. package/dist/harness/claude/session.d.ts +1 -1
  19. package/dist/harness/claude/session.js +1 -1
  20. package/dist/harness/types.d.ts +22 -3
  21. package/dist/issue_tracker.d.ts +2 -0
  22. package/dist/issue_trackers/types.d.ts +15 -1
  23. package/dist/launcher.d.ts +1 -1
  24. package/dist/launcher.js +1 -1
  25. package/dist/lifecycle.d.ts +36 -15
  26. package/dist/lifecycle.js +14 -0
  27. package/dist/machine_setup.d.ts +4 -0
  28. package/dist/migrate.d.ts +5 -0
  29. package/dist/migrate.js +4 -0
  30. package/dist/notes.d.ts +7 -0
  31. package/dist/pr_lifecycle.d.ts +76 -3
  32. package/dist/pr_lifecycle.js +9 -1
  33. package/dist/proc.js +8 -2
  34. package/dist/registry_sync.d.ts +3 -2
  35. package/dist/resources.d.ts +2 -0
  36. package/dist/run_start.d.ts +4 -0
  37. package/dist/sandbox.d.ts +73 -12
  38. package/dist/sandbox.js +6 -6
  39. package/dist/sdk.d.ts +35 -6
  40. package/dist/sdk.js +25 -5
  41. package/dist/slots.d.ts +4 -0
  42. package/dist/standards.d.ts +1 -1
  43. package/dist/stats.d.ts +9 -0
  44. package/dist/status.d.ts +20 -4
  45. package/dist/strategies/types.d.ts +3 -0
  46. package/dist/telepresence.d.ts +15 -0
  47. package/dist/test_run.d.ts +8 -0
  48. package/dist/workspace_init.d.ts +2 -1
  49. package/dist/workspace_token.d.ts +3 -2
  50. package/dist/workspace_token.js +3 -2
  51. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,19 @@
1
1
  # sandbox-core
2
2
 
3
+ ## 0.91.0
4
+
5
+ ### Minor Changes
6
+
7
+ - daa9bd0: **Breaking (SDK):** `up` on `werkmeister-core/sdk` is now `infraUp`. It always started the shared infrastructure, not a workspace. Replace `up()` with `infraUp()`. A workspace's own stack is `runWorkspaceAction(name, "up")`. The Workspaces pane's Connect button works with either core version once the plugin is updated; an older plugin on this CLI fails Connect with `core.up is not a function` until it updates.
8
+
9
+ The SDK now covers everything the MCP server and CLI offer (SW-748): `infraDown`, `infraStop`, `infraRestart`, `infraHealth` and `connectK8s`; `WorkspaceAction` and `WORKSPACE_ACTIONS`; and the functions behind every MCP tool and CLI command, with their argument and result types. `docs/sdk-parity.md` maps each one. The SDK reference adds a Lifecycle section and every `callTool` tool name with its arguments.
10
+
11
+ ## 0.90.6
12
+
13
+ ### Patch Changes
14
+
15
+ - fa318f9: Faster starts and prompt exits. `dockerode` (about 300 modules, ~0.2 s of CPU) loads on the first Docker call instead of at start, so a command that never reaches the Engine no longer pays for it. A command that is not installed (a missing `gh`, say) no longer holds the process open for its whole timeout after failing. The MCP proxy exits when its client closes stdin, instead of waiting two seconds to be signalled.
16
+
3
17
  ## 0.90.5
4
18
 
5
19
  ### Patch Changes
@@ -42,23 +42,36 @@ 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
  export interface PruneResult {
46
- name: string;
47
+ /** 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. */
47
49
  action: "max_age" | "prune" | "reset" | "skipped";
50
+ /** What happened or would happen, the command's output, or why it was skipped or failed. */
48
51
  detail: string;
52
+ /** False when the prune failed or could not be attempted; a deliberate skip is still ok. */
49
53
  ok: boolean;
50
54
  }
55
+ /** Which caches `pruneCaches` touches, and how. */
51
56
  export interface PruneOptions {
57
+ /** One registry cache; absent for every cache. */
52
58
  name?: string;
59
+ /** Empty the cache entirely instead of applying its prune rule. */
53
60
  reset?: boolean;
61
+ /** Prune even while a running container mounts the cache. */
54
62
  force?: boolean;
63
+ /** Report what would be removed without removing it. */
55
64
  dryRun?: boolean;
56
65
  }
57
66
  /** Docker reads `pruneCaches` needs; tests swap these for fakes. */
58
67
  export interface PruneDeps {
68
+ /** The registry's caches, keyed by name. */
59
69
  caches: CacheRegistry;
70
+ /** One row per cache, as `cacheSnapshots` reads it. */
60
71
  snapshots: (caches: CacheRegistry) => Promise<CacheSnapshot[]>;
72
+ /** Names of the running containers mounting *source*; null when Docker is unreachable. */
61
73
  busy: (source: string) => Promise<string[] | null>;
74
+ /** Runs one command synchronously, capturing its output. */
62
75
  run: (argv: string[]) => RunResult;
63
76
  }
64
77
  /**
package/dist/docker.d.ts CHANGED
@@ -10,7 +10,8 @@
10
10
  * `depends_on: service_healthy`, profiles, BuildKit, `.env` interpolation — is a
11
11
  * project to reimplement, not a refactor.
12
12
  */
13
- import Dockerode, { type DockerOptions } from "dockerode";
13
+ import type Dockerode from "dockerode";
14
+ import type { DockerOptions } from "dockerode";
14
15
  /**
15
16
  * Where the daemon is.
16
17
  *
@@ -62,11 +63,17 @@ export declare function containerRecord(c: Dockerode.ContainerInfo): ProjectCont
62
63
  export declare function displayPorts(ports: Dockerode.Port[]): string;
63
64
  /** True when a container of this exact name exists and is running. */
64
65
  export declare function containerRunning(name: string): Promise<boolean>;
66
+ /** One stats sample of a running container, as `docker stats --no-stream` reports it. */
65
67
  export interface ContainerStat {
68
+ /** Container name, without Docker's leading `/`; the short ID when it has none. */
66
69
  name: string;
70
+ /** CPU share over the sample window; 100 is one full core. */
67
71
  cpuPercent: number;
72
+ /** Resident memory in MiB, page cache excluded. */
68
73
  memMib: number;
74
+ /** The memory limit in MiB; Docker reports the host's memory when none is set. */
69
75
  memLimitMib: number;
76
+ /** The container's Docker labels. */
70
77
  labels: Record<string, string>;
71
78
  }
72
79
  /**
package/dist/docker.js CHANGED
@@ -16,9 +16,9 @@ import * as os from "node:os";
16
16
  import * as path from "node:path";
17
17
  import { PassThrough, Readable } from "node:stream";
18
18
  import { StringDecoder } from "node:string_decoder";
19
- import Dockerode from "dockerode";
20
19
  import * as tar from "tar-fs";
21
20
  import { BLUE, CYAN, GREEN, MAGENTA, RESET, YELLOW } from "./colors.js";
21
+ import { loadDockerode } from "./dockerode_load.js";
22
22
  import { ProcError, run } from "./proc.js";
23
23
  /**
24
24
  * Where the daemon is.
@@ -125,7 +125,7 @@ export function endpointOptions(host) {
125
125
  let client = null;
126
126
  /** The shared client. The endpoint is resolved once, on first use. */
127
127
  export function docker() {
128
- return (client ??= new Dockerode(resolveEndpoint()));
128
+ return (client ??= new (loadDockerode())(resolveEndpoint()));
129
129
  }
130
130
  /**
131
131
  * A compose project's containers, found by the labels compose stamps on them.
@@ -0,0 +1,2 @@
1
+ import type Dockerode from "dockerode";
2
+ export declare function loadDockerode(): typeof Dockerode;
@@ -0,0 +1,11 @@
1
+ /**
2
+ * dockerode, loaded on first use. Its graph is about 300 CommonJS modules (~0.2 s of CPU at
3
+ * start), and most processes that import docker.ts never reach the Engine.
4
+ *
5
+ * A bundler cannot follow this require: the CLI leaves dockerode external, so it resolves at
6
+ * run time, and the VS Code extension's esbuild.mjs swaps this module for a static import.
7
+ */
8
+ import { createRequire } from "node:module";
9
+ export function loadDockerode() {
10
+ return createRequire(import.meta.url)("dockerode");
11
+ }
@@ -75,16 +75,24 @@ export interface SchemaProp {
75
75
  pattern?: string;
76
76
  minLength?: number;
77
77
  }
78
- /** The RJSF bundle {@link buildFormSchema} returns. */
78
+ /** The RJSF bundle `buildFormSchema` returns. */
79
79
  export type FormBundle = {
80
+ /** The JSON Schema: one property per unresolved prompt. */
80
81
  schema: {
82
+ /** Always `object`: the form is one object of fields. */
81
83
  type: "object";
84
+ /** The form heading, the same as the bundle's `title`. */
82
85
  title: string;
86
+ /** One field per unresolved prompt, keyed by the prompt's key. */
83
87
  properties: Record<string, SchemaProp>;
88
+ /** Keys of the fields that may not be left empty; absent when none. */
84
89
  required?: string[];
85
90
  };
91
+ /** RJSF widget hints per field key, plus `ui:order` for the prompts' order. */
86
92
  uiSchema: Record<string, unknown>;
93
+ /** Each field's starting value: the resolved value, else the prompt's default. */
87
94
  formData: Record<string, unknown>;
95
+ /** The given title, else `Initialize <name>`. */
88
96
  title: string;
89
97
  };
90
98
  /**
@@ -1,25 +1,43 @@
1
1
  import type { Plan } from "./plan.js";
2
2
  export type QuestionKind = "command" | "health_endpoint" | "environment" | "secrets" | "depends_on" | "conflict" | "unmatched";
3
+ /** One field the scan had to guess, put to Claude. */
3
4
  export interface Question {
5
+ /** `<service>.<key>`, or `unmatched.<name>`; an answer names it as `item`. */
4
6
  id: string;
7
+ /** Which rule {@link applyAnswers} checks the answer against. */
5
8
  kind: QuestionKind;
9
+ /** The service asked about, or null for an unmatched finding. */
6
10
  service: string | null;
11
+ /** The question in plain English. */
7
12
  prompt: string;
13
+ /** What the scan already knows (dir, current guess, files), for Claude to start from. */
8
14
  facts: Record<string, unknown>;
15
+ /** When set, the answer must be one of these (a subset, for list questions). */
9
16
  choices?: unknown[];
10
17
  }
18
+ /** Claude's answer to one {@link Question}, in the shape of `ANSWER_SCHEMA`. */
11
19
  export interface Answer {
20
+ /** The `id` of the question answered. */
12
21
  item: string;
22
+ /** The proposed value; checked against the question's kind and choices before use. */
13
23
  value: unknown;
24
+ /** One sentence naming the evidence; written into the fragment as a comment. */
14
25
  reason: string;
26
+ /** Repo files that support the answer. */
15
27
  files_read: string[];
16
28
  }
17
29
  export type Resolver = (repoRoot: string, questions: Question[]) => Promise<Answer[]>;
30
+ /** What {@link applyAnswers} made of Claude's answers. */
18
31
  export interface ApplyResult {
32
+ /** A copy of the plan with the accepted answers applied; the input plan is unchanged. */
19
33
  plan: Plan;
34
+ /** Question ids whose answers landed in the plan. */
20
35
  accepted: string[];
36
+ /** Answers left out, each with the rule they broke. */
21
37
  rejected: {
38
+ /** The answer's `item`, as Claude sent it. */
22
39
  item: string;
40
+ /** Why it was refused. */
23
41
  reason: string;
24
42
  }[];
25
43
  }
@@ -53,6 +71,8 @@ export declare const ANSWER_SCHEMA: {
53
71
  };
54
72
  };
55
73
  };
74
+ /** The questions worth asking Claude about *plan*: guessed fields, `.env.example` keys, conflicts and unmatched findings, skipping keys the existing fragment already sets. */
56
75
  export declare function collectQuestions(plan: Plan): Question[];
76
+ /** Check each answer against its question and apply the ones that pass, as `inferred` fields. Unknown or repeated items are rejected. */
57
77
  export declare function applyAnswers(plan: Plan, answers: Answer[]): ApplyResult;
58
78
  export declare function assistPrompt(questions: Question[]): string;
@@ -26,6 +26,7 @@ export const ANSWER_SCHEMA = {
26
26
  },
27
27
  },
28
28
  };
29
+ /** The questions worth asking Claude about *plan*: guessed fields, `.env.example` keys, conflicts and unmatched findings, skipping keys the existing fragment already sets. */
29
30
  export function collectQuestions(plan) {
30
31
  const existing = plan.existing ? (parseYaml(plan.existing) ?? {}) : {};
31
32
  const inFile = (svc, key) => existing?.services?.[svc]?.[key] !== undefined;
@@ -132,6 +133,7 @@ function applyUnmatched(next, id, value, reason) {
132
133
  next.skipped = next.skipped.filter((s) => !found.some((f) => s.item === f.file && s.reason.includes(` ${f.name} — `)));
133
134
  return null;
134
135
  }
136
+ /** Check each answer against its question and apply the ones that pass, as `inferred` fields. Unknown or repeated items are rejected. */
135
137
  export function applyAnswers(plan, answers) {
136
138
  const next = structuredClone(plan);
137
139
  const questions = new Map(collectQuestions(plan).map((q) => [q.id, q]));
@@ -5,68 +5,114 @@ export interface SetupPlan {
5
5
  name: string;
6
6
  fields: Record<string, FieldValue>;
7
7
  }
8
+ /** Everything `werkmeister machine detect` would write for one repo, before rendering. */
8
9
  export interface Plan {
10
+ /** The repo's directory name, as the registry keys it. */
9
11
  repo: string;
12
+ /** Absolute repo root. */
10
13
  root: string;
14
+ /** Absolute path of the repo's `.werkmeister/services.yaml` fragment, whether or not it exists. */
11
15
  fragmentPath: string;
12
16
  /** The existing fragment's text, or null when the repo has none. */
13
17
  existing: string | null;
18
+ /** Detected services, sorted by name; a service already in the fragment keeps its name there. */
14
19
  services: ResolvedService[];
20
+ /** Detected datastores and other in-cluster dependencies, sorted by name. */
15
21
  infrastructure: ResolvedInfra[];
22
+ /** The shared install service, or null when the repo has no root package.json or no Node service. */
16
23
  setup: SetupPlan | null;
17
24
  /** Keys listed in .env.example-style files, per service name. */
18
25
  envExample: Record<string, string[]>;
26
+ /** Findings (k8s, compose, Helm) that no source directory matched; the Claude pass can assign them. */
19
27
  unmatched: Finding[];
28
+ /** Files and detectors left out, each with why. */
20
29
  skipped: Skipped[];
21
30
  }
31
+ /** Inputs to {@link planFragment} beyond the repo itself. */
22
32
  export interface PlanOptions {
33
+ /** Directory holding every registered repo; their fragments' ports count as taken. */
23
34
  reposRoot: string;
35
+ /** Runs `git` to list the repo's files. */
24
36
  runner: Runner;
37
+ /** Path of `services.local.yaml`; its ports count as taken. Need not exist. */
25
38
  localPath: string;
39
+ /** Port offsets available in one feature slot, the ceiling for a new `port_offset`. */
26
40
  portsPerSlot: number;
27
41
  }
42
+ /**
43
+ * Scan *root* and work out its fragment: detected services and infrastructure, with free ports
44
+ * allocated for any entry the existing fragment doesn't already set. Throws if that fragment doesn't parse.
45
+ */
28
46
  export declare function planFragment(root: string, opts: PlanOptions): Plan;
29
47
  /** The plan as plain JSON for reports (no raw findings). */
30
48
  export declare function planSummary(plan: Plan): {
49
+ /** The repo's directory name. */
31
50
  repo: string;
51
+ /** Absolute path of the fragment file. */
32
52
  fragment: string;
53
+ /** True when the repo already had a fragment, so only missing keys would be added. */
33
54
  existed: boolean;
55
+ /** Detected services, sorted by name. */
34
56
  services: {
57
+ /** Service name as the fragment keys it. */
35
58
  name: string;
59
+ /** Repo-relative source directory ("." is the repo root). */
36
60
  dir: string;
61
+ /** Planned fields by key. */
37
62
  fields: {
38
63
  [k: string]: {
64
+ /** The field's value as it would be written to the fragment. */
39
65
  value: unknown;
66
+ /** Where the value came from; for a guess, the reason written as the YAML comment. */
40
67
  source: string;
68
+ /** Whether a file stated it, the scan guessed it, or Claude inferred it. */
41
69
  confidence: import("./types.js").Confidence;
42
70
  };
43
71
  };
72
+ /** Keys where two files stated different values. */
44
73
  conflicts: {
74
+ /** The field the sources disagree on. */
45
75
  key: string;
76
+ /** The value the plan uses. */
46
77
  chosen: FieldValue;
78
+ /** The other stated values, not used. */
47
79
  also: FieldValue[];
48
80
  }[];
49
81
  }[];
82
+ /** Detected infrastructure entries, sorted by name. */
50
83
  infrastructure: {
84
+ /** Infrastructure name as the fragment keys it. */
51
85
  name: string;
86
+ /** Planned fields by key. */
52
87
  fields: {
53
88
  [k: string]: {
89
+ /** The field's value as it would be written to the fragment. */
54
90
  value: unknown;
91
+ /** Where the value came from; for a guess, the reason written as the YAML comment. */
55
92
  source: string;
93
+ /** Whether a file stated it, the scan guessed it, or Claude inferred it. */
56
94
  confidence: import("./types.js").Confidence;
57
95
  };
58
96
  };
59
97
  }[];
98
+ /** The shared install service, or null when there is none. */
60
99
  setup: {
100
+ /** The name the Node services' `setup_service` points at. */
61
101
  name: string;
102
+ /** Planned fields by key. */
62
103
  fields: {
63
104
  [k: string]: {
105
+ /** The field's value as it would be written to the fragment. */
64
106
  value: unknown;
107
+ /** Where the value came from; for a guess, the reason written as the YAML comment. */
65
108
  source: string;
109
+ /** Whether a file stated it, the scan guessed it, or Claude inferred it. */
66
110
  confidence: import("./types.js").Confidence;
67
111
  };
68
112
  };
69
113
  } | null;
114
+ /** `.env.example` keys no service declares yet, per service name. */
70
115
  envExample: Record<string, string[]>;
116
+ /** Files and detectors left out, each with why. */
71
117
  skipped: Skipped[];
72
118
  };
@@ -42,6 +42,10 @@ function envExampleKeys(ctx, dir) {
42
42
  }
43
43
  return [...keys].sort();
44
44
  }
45
+ /**
46
+ * Scan *root* and work out its fragment: detected services and infrastructure, with free ports
47
+ * allocated for any entry the existing fragment doesn't already set. Throws if that fragment doesn't parse.
48
+ */
45
49
  export function planFragment(root, opts) {
46
50
  const abs = path.resolve(root);
47
51
  const repo = path.basename(abs);
@@ -186,21 +190,59 @@ export function planFragment(root, opts) {
186
190
  export function planSummary(plan) {
187
191
  const fields = (f) => Object.fromEntries(Object.entries(f).map(([k, v]) => [
188
192
  k,
189
- { value: v.value, source: v.source, confidence: v.confidence },
193
+ {
194
+ /** The field's value as it would be written to the fragment. */
195
+ value: v.value,
196
+ /** Where the value came from; for a guess, the reason written as the YAML comment. */
197
+ source: v.source,
198
+ /** Whether a file stated it, the scan guessed it, or Claude inferred it. */
199
+ confidence: v.confidence,
200
+ },
190
201
  ]));
191
202
  return {
203
+ /** The repo's directory name. */
192
204
  repo: plan.repo,
205
+ /** Absolute path of the fragment file. */
193
206
  fragment: plan.fragmentPath,
207
+ /** True when the repo already had a fragment, so only missing keys would be added. */
194
208
  existed: plan.existing !== null,
209
+ /** Detected services, sorted by name. */
195
210
  services: plan.services.map((s) => ({
211
+ /** Service name as the fragment keys it. */
196
212
  name: s.name,
213
+ /** Repo-relative source directory ("." is the repo root). */
197
214
  dir: s.dir,
215
+ /** Planned fields by key. */
198
216
  fields: fields(s.fields),
199
- conflicts: s.conflicts.map((c) => ({ key: c.key, chosen: c.chosen, also: c.also })),
217
+ /** Keys where two files stated different values. */
218
+ conflicts: s.conflicts.map((c) => ({
219
+ /** The field the sources disagree on. */
220
+ key: c.key,
221
+ /** The value the plan uses. */
222
+ chosen: c.chosen,
223
+ /** The other stated values, not used. */
224
+ also: c.also,
225
+ })),
200
226
  })),
201
- infrastructure: plan.infrastructure.map((i) => ({ name: i.name, fields: fields(i.fields) })),
202
- setup: plan.setup ? { name: plan.setup.name, fields: fields(plan.setup.fields) } : null,
227
+ /** Detected infrastructure entries, sorted by name. */
228
+ infrastructure: plan.infrastructure.map((i) => ({
229
+ /** Infrastructure name as the fragment keys it. */
230
+ name: i.name,
231
+ /** Planned fields by key. */
232
+ fields: fields(i.fields),
233
+ })),
234
+ /** The shared install service, or null when there is none. */
235
+ setup: plan.setup
236
+ ? {
237
+ /** The name the Node services' `setup_service` points at. */
238
+ name: plan.setup.name,
239
+ /** Planned fields by key. */
240
+ fields: fields(plan.setup.fields),
241
+ }
242
+ : null,
243
+ /** `.env.example` keys no service declares yet, per service name. */
203
244
  envExample: plan.envExample,
245
+ /** Files and detectors left out, each with why. */
204
246
  skipped: plan.skipped,
205
247
  };
206
248
  }
@@ -1,12 +1,17 @@
1
1
  import type { Plan } from "./plan.js";
2
2
  export declare const FRAGMENT_HEADER: string;
3
+ /** The fragment text {@link renderFragment} produced, and what changed. */
3
4
  export interface Rendered {
5
+ /** Absolute path the fragment is written to. */
4
6
  path: string;
7
+ /** The full file text: the existing bytes with new keys spliced in, or a new file with the header. */
5
8
  yaml: string;
6
9
  /** Dotted paths of every key added, e.g. `services.api.internal_port`. */
7
10
  added: string[];
11
+ /** False when the existing file already had everything, so there is nothing to write. */
8
12
  changed: boolean;
9
13
  /** Sections the existing file shapes in a way that can't be extended, with what was left out. */
10
14
  skipped: string[];
11
15
  }
16
+ /** Render *plan* as fragment text. An existing file only gains missing keys and entries; its own text is kept byte for byte. */
12
17
  export declare function renderFragment(plan: Plan): Rendered;
@@ -107,6 +107,7 @@ function sections(plan) {
107
107
  ["setup_services", setup],
108
108
  ];
109
109
  }
110
+ /** Render *plan* as fragment text. An existing file only gains missing keys and entries; its own text is kept byte for byte. */
110
111
  export function renderFragment(plan) {
111
112
  const original = plan.existing ?? "";
112
113
  const doc = parseDocument(original);
@@ -4,11 +4,15 @@
4
4
  * See docs/superpowers/specs/2026-10-02-sandbox-detect-fragment-design.md at 66703fc. // name-check: ignore
5
5
  */
6
6
  import type { Runner } from "../machine_setup.js";
7
+ /** `stated`: a file says so; `guessed`: a heuristic, worth a review; `inferred`: Claude answered from the repo. */
7
8
  export type Confidence = "stated" | "guessed" | "inferred";
8
9
  /** One field value and where it came from. For a guess, `source` is the reason written as the YAML comment. */
9
10
  export interface FieldValue {
11
+ /** The value as it would be written to the fragment. */
10
12
  value: unknown;
13
+ /** The file or rule it came from; for a guess, the reason. */
11
14
  source: string;
15
+ /** How far the value can be trusted. */
12
16
  confidence: Confidence;
13
17
  }
14
18
  export type FindingKind = "package" | "dockerfile" | "k8s" | "compose";
@@ -27,8 +31,11 @@ export interface Finding {
27
31
  runnable?: boolean;
28
32
  fields: Record<string, FieldValue>;
29
33
  }
34
+ /** Something detection left out instead of failing on. */
30
35
  export interface Skipped {
36
+ /** The file or detector left out. */
31
37
  item: string;
38
+ /** Why, as shown to the person. */
32
39
  reason: string;
33
40
  }
34
41
  export interface DetectContext {
@@ -1,5 +1,10 @@
1
1
  import type { Plan } from "./plan.js";
2
2
  import type { Rendered } from "./render.js";
3
3
  export declare function defaultSchemaPath(): string;
4
+ /**
5
+ * Check *rendered* against the fragment JSON Schema, then trial-merge it with every other repo's
6
+ * fragment under *reposRoot*. Returns the problems found; empty means safe to write.
7
+ */
4
8
  export declare function validateFragment(rendered: Rendered, plan: Plan, reposRoot: string, schemaPath?: string): string[];
9
+ /** Write the fragment to its path, creating `.werkmeister/` if needed. */
5
10
  export declare function writeFragment(rendered: Rendered): void;
@@ -13,6 +13,10 @@ const Ajv = (AjvModule.default ??
13
13
  export function defaultSchemaPath() {
14
14
  return path.join(sandboxRoot(), "infra", "schemas", "services-fragment.schema.json");
15
15
  }
16
+ /**
17
+ * Check *rendered* against the fragment JSON Schema, then trial-merge it with every other repo's
18
+ * fragment under *reposRoot*. Returns the problems found; empty means safe to write.
19
+ */
16
20
  export function validateFragment(rendered, plan, reposRoot, schemaPath = defaultSchemaPath()) {
17
21
  let doc;
18
22
  try {
@@ -46,6 +50,7 @@ export function validateFragment(rendered, plan, reposRoot, schemaPath = default
46
50
  }
47
51
  return errors;
48
52
  }
53
+ /** Write the fragment to its path, creating `.werkmeister/` if needed. */
49
54
  export function writeFragment(rendered) {
50
55
  fs.mkdirSync(path.dirname(rendered.path), { recursive: true });
51
56
  fs.writeFileSync(rendered.path, rendered.yaml);
@@ -54,10 +54,15 @@ export declare const noteDecisions: DecisionSource;
54
54
  * — nothing can confirm the rule landed, so nothing claims it did.
55
55
  */
56
56
  export declare function reconcileGraduating(workspaceRoot: string, standardsDir?: string | null, decisions?: DecisionSource): Note[];
57
+ /** Where `graduateNote` scaffolds a decision, and as what. */
57
58
  export interface GraduateNoteOptions {
59
+ /** The standards module to write into; it must exist and use the Rules/Don't/Going-deeper shape. */
58
60
  domain: string;
61
+ /** `rule` adds a bullet to the module's Rules; `example` or `anti-pattern` writes a references file. */
59
62
  kind: string;
63
+ /** The references file's name; the note's slug when null. */
60
64
  slug?: string | null;
65
+ /** The standards tree to write into; the configured one when null. */
61
66
  standardsDir?: string | null;
62
67
  /** The workspace strategy's `decisions`; jit's notes when omitted. */
63
68
  decisions?: DecisionSource;
@@ -40,7 +40,7 @@ export declare function deniedIn(stdout: string): string[];
40
40
  /**
41
41
  * Whether a message relayed at `sentAt` ran in the target session: a user turn
42
42
  * after the send that holds its text. SendMessage succeeding and an idle notice
43
- * arriving prove nothing: a UserPromptSubmit hook can drop the prompt (SW-348).
43
+ * arriving prove nothing: a UserPromptSubmit hook can drop the prompt.
44
44
  */
45
45
  export declare function relayPickedUp(messages: ClaudeMessage[], relay: {
46
46
  sentAt: string;
@@ -85,7 +85,7 @@ export function deniedIn(stdout) {
85
85
  /**
86
86
  * Whether a message relayed at `sentAt` ran in the target session: a user turn
87
87
  * after the send that holds its text. SendMessage succeeding and an idle notice
88
- * arriving prove nothing: a UserPromptSubmit hook can drop the prompt (SW-348).
88
+ * arriving prove nothing: a UserPromptSubmit hook can drop the prompt.
89
89
  */
90
90
  export function relayPickedUp(messages, relay) {
91
91
  const sentAt = Date.parse(relay.sentAt);
@@ -26,25 +26,29 @@ export type HooksSupport = {
26
26
  };
27
27
  /** Where one harness reads werkmeister's context layer (proposal § 4.3 projection rows). */
28
28
  export interface HarnessLayout {
29
+ /** The harness this layout belongs to. */
29
30
  readonly id: HarnessId;
30
31
  /** The file the harness reads first. */
31
32
  readonly instructionsFile: string;
32
33
  /** Workspace-relative dir the harness loads project skills from. */
33
34
  readonly skillsDir: string;
35
+ /** Whether werkmeister's hooks can be written for this harness, and how. */
34
36
  readonly hooks: HooksSupport;
35
37
  /** Whether `.claude/agents`-style subagent definitions are projected. */
36
38
  readonly agents: boolean;
37
- /** The tool a human check asks its questions with (SW-517); absent → a plain-text block. */
39
+ /** The tool a human check asks its questions with; absent → a plain-text block. */
38
40
  readonly questionTool?: string;
39
41
  /** Appended to the instructions file; "" when the harness needs no note. */
40
42
  notice(): string;
41
43
  }
44
+ /** How `sendTurn` runs one turn. */
42
45
  export interface TurnOptions {
43
- /** Workspace root whose autonomous rules the turn gets, `autonomous` or not: nobody is there to approve (SW-313). */
46
+ /** Workspace root whose autonomous rules the turn gets, `autonomous` or not: nobody is there to approve. */
44
47
  unattended?: string;
45
48
  /** Wait for the turn to end and return a {@link TurnResult}. */
46
49
  wait?: boolean;
47
50
  }
51
+ /** What a waited-for turn reports once it ends. */
48
52
  export interface TurnResult {
49
53
  /** The calls refused for lack of approval, as `tool: command`. */
50
54
  denied: string[];
@@ -57,22 +61,31 @@ export interface TurnState {
57
61
  exitCode: number | null;
58
62
  error: string | null;
59
63
  }
60
- /** {@link TurnState} for callers; `idle` means this process started no turn (also after a restart). */
64
+ /** `TurnState` for callers; `idle` means this process started no turn (also after a restart). */
61
65
  export interface TurnStatus {
66
+ /** `failed` covers a non-zero exit and a harness binary that would not spawn. */
62
67
  state: "idle" | "running" | "done" | "failed";
68
+ /** When the turn was started (ISO); null when `idle`. */
63
69
  startedAt: string | null;
70
+ /** The harness process's exit code; null while running, when idle, or when it never spawned. */
64
71
  exitCode: number | null;
72
+ /** Why the turn failed, with the tail of its stderr; null unless `failed`. */
65
73
  error: string | null;
66
74
  }
75
+ /** One entry of a session transcript. */
67
76
  export interface SessionMessage {
68
77
  /** "tool" entries are compact activity rows ("Bash: npm test") from tool_use blocks. */
69
78
  role: "user" | "assistant" | "tool";
79
+ /** The message text, or the activity row for a tool entry. */
70
80
  text: string;
81
+ /** When the harness logged the entry (ISO); null when the line carried none. */
71
82
  timestamp: string | null;
72
83
  }
84
+ /** The recent messages of a folder's newest session. */
73
85
  export interface SessionTranscript {
74
86
  /** Session ID of the newest session, or null if none. */
75
87
  sessionId: string | null;
88
+ /** The folder whose sessions were read. */
76
89
  workspacePath: string;
77
90
  /** Last N user/assistant text messages, oldest first. */
78
91
  messages: SessionMessage[];
@@ -124,11 +137,17 @@ export interface SessionUsage {
124
137
  totals: UsageTotals;
125
138
  estUsd: number | null;
126
139
  }
140
+ /** A workspace's token usage and estimated cost, summed across its sessions. */
127
141
  export interface WorkspaceUsage {
142
+ /** The workspace name the caller asked about. */
128
143
  name: string;
144
+ /** Token counts summed over every session and model. */
129
145
  totals: UsageTotals;
146
+ /** Estimated cost in USD over the models with a known price; null when none has one. */
130
147
  estUsd: number | null;
148
+ /** Per-model totals, costliest first. */
131
149
  byModel: ModelUsage[];
150
+ /** Per-session totals. */
132
151
  sessions: SessionUsage[];
133
152
  }
134
153
  export interface HarnessAdapter {
@@ -35,7 +35,9 @@ export declare function loadIssueTracker(cfg?: Record<string, any>): TrackerId;
35
35
  export declare function projectTracker(project: Project): IssueTrackerStrategy;
36
36
  /** Where a lookup happens: a workspace's `project:` and/or text holding an issue ref. */
37
37
  export interface TrackerAt {
38
+ /** A project name from the machine's projects; one not found is warned about once and ignored. */
38
39
  project?: string;
40
+ /** Any text with an issue ref in it (an issue id, branch name, URL); used when `project` is absent or unknown. */
39
41
  text?: string;
40
42
  }
41
43
  /**