@orkestrel/scaffold 0.0.115 → 0.0.116

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 (70) hide show
  1. package/dist/bin/main.js +137 -15
  2. package/dist/bin/main.js.map +1 -1
  3. package/dist/host/agents/skills/orkestrel-publish/references/wave.md +1 -1
  4. package/dist/host/claude/agents/orkestrel.md +1 -1
  5. package/dist/host/claude/rules/names.md +3 -1
  6. package/dist/host/guides/abort.md +17 -17
  7. package/dist/host/guides/agent.md +445 -445
  8. package/dist/host/guides/brief.md +143 -143
  9. package/dist/host/guides/browser.md +731 -731
  10. package/dist/host/guides/budget.md +39 -39
  11. package/dist/host/guides/capture.md +298 -298
  12. package/dist/host/guides/console.md +109 -109
  13. package/dist/host/guides/contract.md +335 -335
  14. package/dist/host/guides/csv.md +30 -30
  15. package/dist/host/guides/database.md +163 -163
  16. package/dist/host/guides/emitter.md +17 -17
  17. package/dist/host/guides/form.md +99 -99
  18. package/dist/host/guides/guide.md +361 -183
  19. package/dist/host/guides/html.md +49 -49
  20. package/dist/host/guides/indexeddb.md +40 -40
  21. package/dist/host/guides/interpret.md +139 -139
  22. package/dist/host/guides/lsp.md +114 -114
  23. package/dist/host/guides/markdown.md +68 -68
  24. package/dist/host/guides/mcp.md +3745 -3745
  25. package/dist/host/guides/middleware.md +170 -170
  26. package/dist/host/guides/msg.md +95 -95
  27. package/dist/host/guides/ndjson.md +8 -8
  28. package/dist/host/guides/ollama.md +56 -56
  29. package/dist/host/guides/pool.md +21 -21
  30. package/dist/host/guides/probe.md +82 -82
  31. package/dist/host/guides/process.md +99 -99
  32. package/dist/host/guides/program.md +98 -96
  33. package/dist/host/guides/qualifier.md +70 -70
  34. package/dist/host/guides/queue.md +37 -37
  35. package/dist/host/guides/rater.md +38 -38
  36. package/dist/host/guides/reason.md +308 -308
  37. package/dist/host/guides/relation.md +50 -50
  38. package/dist/host/guides/router.md +58 -58
  39. package/dist/host/guides/scaffold.md +554 -419
  40. package/dist/host/guides/sea.md +128 -128
  41. package/dist/host/guides/server.md +100 -100
  42. package/dist/host/guides/sqlite.md +28 -28
  43. package/dist/host/guides/sse.md +20 -20
  44. package/dist/host/guides/study.md +444 -444
  45. package/dist/host/guides/table.md +82 -82
  46. package/dist/host/guides/template.md +41 -41
  47. package/dist/host/guides/terminal.md +121 -121
  48. package/dist/host/guides/test.md +273 -273
  49. package/dist/host/guides/timeout.md +18 -18
  50. package/dist/host/guides/tool.md +27 -27
  51. package/dist/host/guides/toolbox.md +166 -166
  52. package/dist/host/guides/websocket.md +54 -54
  53. package/dist/host/guides/worker.md +24 -24
  54. package/dist/host/guides/workflow.md +187 -187
  55. package/dist/host/guides/workspace.md +55 -55
  56. package/dist/host/manifest.json +55 -55
  57. package/dist/host/tests/setupPolicy.ts +5 -3
  58. package/dist/src/core/index.cjs +89 -3
  59. package/dist/src/core/index.cjs.map +1 -1
  60. package/dist/src/core/index.d.cts +229 -144
  61. package/dist/src/core/index.d.ts +229 -144
  62. package/dist/src/core/index.js +87 -4
  63. package/dist/src/core/index.js.map +1 -1
  64. package/dist/src/server/index.cjs +292 -66
  65. package/dist/src/server/index.cjs.map +1 -1
  66. package/dist/src/server/index.d.cts +188 -6
  67. package/dist/src/server/index.d.ts +188 -6
  68. package/dist/src/server/index.js +287 -69
  69. package/dist/src/server/index.js.map +1 -1
  70. package/package.json +4 -3
@@ -53,21 +53,21 @@ await child.destroy()
53
53
 
54
54
  The interface-oriented constructors, from `@orkestrel/process/server`.
55
55
 
56
- | API | Kind | Summary |
57
- | ---------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
58
- | `createProcess` | function | Creates one supervised child process and returns it as a `ProcessInterface`, so a caller holds the published contract rather than the `Process` class. |
59
- | `createSession` | function | Creates one raw byte session over a supervised child process and returns it as a `SessionInterface`, so a caller holds the published contract rather than the `Session` class. |
60
- | `createProcessManager` | function | Creates one empty keyed registry of supervised child processes and returns it as a `ProcessManagerInterface`, so a caller holds the published contract rather than the `ProcessManager` class. |
56
+ | Name | Kind | Signature | Summary |
57
+ | ---------------------- | -------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
58
+ | `createProcess` | function | `(options: ProcessOptions) => ProcessInterface` | Creates one supervised child process and returns it as a `ProcessInterface`, so a caller holds the published contract rather than the `Process` class. |
59
+ | `createSession` | function | `(options: SessionOptions) => SessionInterface` | Creates one raw byte session over a supervised child process and returns it as a `SessionInterface`, so a caller holds the published contract rather than the `Session` class. |
60
+ | `createProcessManager` | function | `(options?: ProcessManagerOptions) => ProcessManagerInterface` | Creates one empty keyed registry of supervised child processes and returns it as a `ProcessManagerInterface`, so a caller holds the published contract rather than the `ProcessManager` class. |
61
61
 
62
62
  ### Spawns
63
63
 
64
64
  The one-shot and fire-and-forget spawns, from `@orkestrel/process/server`.
65
65
 
66
- | API | Kind | Summary |
67
- | ------------- | -------- | -------------------------------------------------------------------------------------------- |
68
- | `execute` | function | Runs one command to completion, buffering its output, and settles with the outcome. |
69
- | `executeSync` | function | Runs one command to completion synchronously, buffering its output, and returns the outcome. |
70
- | `detach` | function | Spawns one command as a detached process and returns without waiting for it. |
66
+ | Name | Kind | Signature | Summary |
67
+ | ------------- | -------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
68
+ | `execute` | function | `(command: ProcessCommand, options?: ExecuteOptions) => Promise<ExecuteResult>` | Runs one command to completion, buffering its output, and settles with the outcome. |
69
+ | `executeSync` | function | `(command: ProcessCommand, options?: ExecuteSyncOptions) => ExecuteResult` | Runs one command to completion synchronously, buffering its output, and returns the outcome. |
70
+ | `detach` | function | `(command: ProcessCommand, options?: DetachOptions) => void` | Spawns one command as a detached process and returns without waiting for it. |
71
71
 
72
72
  ### Classes
73
73
 
@@ -76,13 +76,13 @@ The classes a factory constructs and the `Supervisor` engine a consumer construc
76
76
  interface, so its readonly data members are named under [Surface notes](#surface-notes) rather than
77
77
  in a Surface row.
78
78
 
79
- | API | Kind | Summary |
80
- | ---------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
81
- | `Process` | class | Supervises one child, frames its standard output into lines under a bounded backlog, and keeps every observation channel aligned at termination. |
82
- | `Session` | class | Supervises one child and publishes its standard output as raw bytes. |
83
- | `Supervisor` | class | Supervises one child process and reports each lifecycle moment to the face composing it. |
84
- | `ProcessManager` | class | Launches supervised children under caller-chosen ids, evicts each one as it settles, and destroys every live child on teardown. |
85
- | `ProcessError` | class | Represents a child-process failure with a stable machine-readable category. |
79
+ | Name | Kind | Signature | Summary |
80
+ | ---------------- | ----- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
81
+ | `Process` | class | `new (options: ProcessOptions) => ProcessInterface` | Supervises one child, frames its standard output into lines under a bounded backlog, and keeps every observation channel aligned at termination. |
82
+ | `Session` | class | `new (options: SessionOptions) => SessionInterface` | Supervises one child and publishes its standard output as raw bytes. |
83
+ | `Supervisor` | class | `new (options: ProcessOptions, face: SupervisorFace) => Supervisor` | Supervises one child process and reports each lifecycle moment to the face composing it. |
84
+ | `ProcessManager` | class | `new (options?: ProcessManagerOptions) => ProcessManagerInterface` | Launches supervised children under caller-chosen ids, evicts each one as it settles, and destroys every live child on teardown. |
85
+ | `ProcessError` | class | `new (message: string, options: ProcessErrorOptions) => ProcessError` | Represents a child-process failure with a stable machine-readable category. |
86
86
 
87
87
  ### Guards
88
88
 
@@ -90,66 +90,66 @@ The total guard, from `@orkestrel/process`.
90
90
 
91
91
  In a guard table a `Shape` cell holds the type the guard narrows to.
92
92
 
93
- | API | Kind | Shape | Summary |
94
- | ---------------- | -------- | -------------- | ---------------------------------------------------- |
95
- | `isProcessError` | function | `ProcessError` | Checks whether an unknown value is a `ProcessError`. |
93
+ | Name | Kind | Signature | Summary |
94
+ | ---------------- | -------- | ------------------------------------------- | ---------------------------------------------------- |
95
+ | `isProcessError` | function | `(value: unknown) => value is ProcessError` | Checks whether an unknown value is a `ProcessError`. |
96
96
 
97
97
  ### Error factories
98
98
 
99
99
  The constructors for each failure category, from `@orkestrel/process`.
100
100
 
101
- | API | Kind | Summary |
102
- | ---------------------- | -------- | ------------------------------------------------------------------------------------------------------------- |
103
- | `createDuplicateError` | function | Creates the `duplicate`-coded failure raised when a manager launch reuses a live id. |
104
- | `createProtocolError` | function | Creates the `protocol`-coded failure raised when a launch is attempted on a registry that is being destroyed. |
105
- | `createInvalidError` | function | Creates the `invalid`-coded failure raised when a public input is refused before anything is spawned. |
106
- | `createExecuteError` | function | Creates the failure raised when a run does not complete successfully and rejection is requested. |
101
+ | Name | Kind | Signature | Summary |
102
+ | ---------------------- | -------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
103
+ | `createDuplicateError` | function | `(id: string) => ProcessError` | Creates the `duplicate`-coded failure raised when a manager launch reuses a live id. |
104
+ | `createProtocolError` | function | `(id: string) => ProcessError` | Creates the `protocol`-coded failure raised when a launch is attempted on a registry that is being destroyed. |
105
+ | `createInvalidError` | function | `(subject: string, value: unknown) => ProcessError` | Creates the `invalid`-coded failure raised when a public input is refused before anything is spawned. |
106
+ | `createExecuteError` | function | `(result: ExecuteResult, cause?: unknown) => ProcessError` | Creates the failure raised when a run does not complete successfully and rejection is requested. |
107
107
 
108
108
  ### Command helpers
109
109
 
110
110
  The resolution and environment building blocks every spawn composes, from
111
111
  `@orkestrel/process/server`.
112
112
 
113
- | API | Kind | Summary |
114
- | --------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- |
115
- | `snapshotCommand` | function | Takes one owned frozen snapshot of a caller's command. |
116
- | `formatCommand` | function | Renders one command into its diagnostic command line. |
117
- | `quoteArgument` | function | Quotes one command-line token for a `cmd.exe` command line. |
118
- | `buildSpawn` | function | Builds the resolved spawn form of one command for the current host. |
119
- | `buildPlatformSpawn` | function | Builds a spawn form from a resolved file and an explicit platform. |
120
- | `buildExecutableCandidates` | function | Builds the executable candidates an explicit platform would search. |
121
- | `resolveExecutable` | function | Resolves a command file to the executable path the host would launch, or to `undefined` on a POSIX host, which performs its own lookup. |
122
- | `isFile` | function | Checks whether a path names a regular file. |
123
- | `readVariable` | function | Reads one environment variable the way the current host resolves it. |
124
- | `readPlatformVariable` | function | Reads one environment variable under an explicit platform's key rules. |
125
- | `mergeEnvironment` | function | Merges environment overrides into the environment one child receives on the current host. |
126
- | `mergePlatformEnvironment` | function | Merges environment layers under an explicit platform's key rules. |
113
+ | Name | Kind | Signature | Summary |
114
+ | --------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
115
+ | `snapshotCommand` | function | `(command: ProcessCommand) => ProcessCommand` | Takes one owned frozen snapshot of a caller's command. |
116
+ | `formatCommand` | function | `(command: ProcessCommand) => string` | Renders one command into its diagnostic command line. |
117
+ | `quoteArgument` | function | `(value: string) => string` | Quotes one command-line token for a `cmd.exe` command line. |
118
+ | `buildSpawn` | function | `(command: ProcessCommand, options?: ExecutableOptions) => SpawnInput` | Builds the resolved spawn form of one command for the current host. |
119
+ | `buildPlatformSpawn` | function | `(command: ProcessCommand, file: string, environment: Readonly<Record<string, string \| undefined>>, platform: NodeJS.Platform) => SpawnInput` | Builds a spawn form from a resolved file and an explicit platform. |
120
+ | `buildExecutableCandidates` | function | `(file: string, workspace: string, environment: Readonly<Record<string, string \| undefined>>, platform: NodeJS.Platform) => readonly string[]` | Builds the executable candidates an explicit platform would search. |
121
+ | `resolveExecutable` | function | `(file: string, options?: ExecutableOptions) => string \| undefined` | Resolves a command file to the executable path the host would launch, or to `undefined` on a POSIX host, which performs its own lookup. |
122
+ | `isFile` | function | `(target: string) => boolean` | Checks whether a path names a regular file. |
123
+ | `readVariable` | function | `(environment: Readonly<Record<string, string \| undefined>>, name: string) => string \| undefined` | Reads one environment variable the way the current host resolves it. |
124
+ | `readPlatformVariable` | function | `(environment: Readonly<Record<string, string \| undefined>>, name: string, platform: NodeJS.Platform) => string \| undefined` | Reads one environment variable under an explicit platform's key rules. |
125
+ | `mergeEnvironment` | function | `(isolated: boolean, base?: Readonly<Record<string, string \| undefined>>, override?: Readonly<Record<string, string \| undefined>>) => NodeJS.ProcessEnv` | Merges environment overrides into the environment one child receives on the current host. |
126
+ | `mergePlatformEnvironment` | function | `(platform: NodeJS.Platform, parent: Readonly<Record<string, string \| undefined>>, isolated: boolean, base?: Readonly<Record<string, string \| undefined>>, override?: Readonly<Record<string, string \| undefined>>) => NodeJS.ProcessEnv` | Merges environment layers under an explicit platform's key rules. |
127
127
 
128
128
  ### Capture helpers
129
129
 
130
130
  The byte-bounding and result-assembly building blocks, from `@orkestrel/process/server`.
131
131
 
132
- | API | Kind | Summary |
133
- | -------------------- | -------- | -------------------------------------------------------------------------------------------- |
134
- | `trimHead` | function | Trims a buffer to at most `limit` leading bytes without splitting a UTF-8 sequence. |
135
- | `trimTail` | function | Trims a buffer to at most `limit` trailing bytes without splitting a UTF-8 sequence. |
136
- | `captureChunk` | function | Bounds one delivered stream chunk to the bytes a capture still has room for. |
137
- | `buildExecuteResult` | function | Builds one settled `ExecuteResult` from a completed run's captured bytes and terminal facts. |
132
+ | Name | Kind | Signature | Summary |
133
+ | -------------------- | -------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
134
+ | `trimHead` | function | `(bytes: Uint8Array, limit: number) => Buffer` | Trims a buffer to at most `limit` leading bytes without splitting a UTF-8 sequence. |
135
+ | `trimTail` | function | `(bytes: Uint8Array, limit: number) => Buffer` | Trims a buffer to at most `limit` trailing bytes without splitting a UTF-8 sequence. |
136
+ | `captureChunk` | function | `(chunk: unknown, room: number) => Buffer \| undefined` | Bounds one delivered stream chunk to the bytes a capture still has room for. |
137
+ | `buildExecuteResult` | function | `(input: ExecuteInput) => ExecuteResult` | Builds one settled `ExecuteResult` from a completed run's captured bytes and terminal facts. |
138
138
 
139
139
  ### Termination helpers
140
140
 
141
141
  The signalling and confirmation building blocks a bounded stop composes, from
142
142
  `@orkestrel/process/server`.
143
143
 
144
- | API | Kind | Summary |
145
- | ---------------- | -------- | ----------------------------------------------------------------------------------- |
146
- | `inspectProcess` | function | Reports whether a process or POSIX process group still exists. |
147
- | `isExited` | function | Checks whether a child process has reached its native exit. |
148
- | `killProcess` | function | Signals one owned child process, or its detached process group on a POSIX host. |
149
- | `killTree` | function | Kills one Windows process tree through `taskkill`. |
150
- | `waitForExit` | function | Waits for one child process's native exit, bounded by a deadline. |
151
- | `waitForClose` | function | Waits for one child process's streams to close, bounded by a deadline. |
152
- | `stopChild` | function | Terminates one child process tree and reports whether its native exit was observed. |
144
+ | Name | Kind | Signature | Summary |
145
+ | ---------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
146
+ | `inspectProcess` | function | `(pid: number) => boolean \| undefined` | Reports whether a process or POSIX process group still exists. |
147
+ | `isExited` | function | `(child: Pick<ProcessChildInterface, 'exitCode' \| 'signalCode'>) => boolean` | Checks whether a child process has reached its native exit. |
148
+ | `killProcess` | function | `(child: Pick<ProcessChildInterface, 'pid' \| 'kill'>, signal: NodeJS.Signals) => void` | Signals one owned child process, or its detached process group on a POSIX host. |
149
+ | `killTree` | function | `(pid: number, timeout: number) => Promise<boolean>` | Kills one Windows process tree through `taskkill`. |
150
+ | `waitForExit` | function | `(child: Pick<ProcessChildInterface, 'exitCode' \| 'signalCode' \| 'once' \| 'off'>, timeout: number) => Promise<void>` | Waits for one child process's native exit, bounded by a deadline. |
151
+ | `waitForClose` | function | `(child: Pick<ProcessChildInterface, 'once' \| 'off'>, timeout: number) => Promise<boolean>` | Waits for one child process's streams to close, bounded by a deadline. |
152
+ | `stopChild` | function | `(child: ProcessChildInterface, grace: number, confirm: number) => Promise<boolean>` | Terminates one child process tree and reports whether its native exit was observed. |
153
153
 
154
154
  `inspectProcess` returns `true` while the process or POSIX process group exists, including
155
155
  when the host refuses the probe with `EPERM`. It returns `false` after the target is gone
@@ -163,14 +163,14 @@ id other than minus one probes the process group identified by its magnitude.
163
163
  The input refusals every public entry point runs before it spawns anything, from
164
164
  `@orkestrel/process/server`.
165
165
 
166
- | API | Kind | Summary |
167
- | --------------------- | -------- | ------------------------------------------------------------------- |
168
- | `validateText` | function | Validates one spawn-bound string. |
169
- | `validateTimer` | function | Validates one timer-valued option in milliseconds. |
170
- | `validateBytes` | function | Validates one byte-valued option. |
171
- | `validateEnvironment` | function | Validates every spawn-bound string of one environment override map. |
172
- | `validateCommand` | function | Validates every spawn-bound string of one command. |
173
- | `validateWorkspace` | function | Validates the working directory one child starts in. |
166
+ | Name | Kind | Signature | Summary |
167
+ | --------------------- | -------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
168
+ | `validateText` | function | `(value: unknown, subject: string, required: boolean) => void` | Validates one spawn-bound string. |
169
+ | `validateTimer` | function | `(value: number \| undefined, subject: string) => void` | Validates one timer-valued option in milliseconds. |
170
+ | `validateBytes` | function | `(value: number \| undefined, subject: string, minimum: number) => void` | Validates one byte-valued option. |
171
+ | `validateEnvironment` | function | `(environment: Readonly<Record<string, string \| undefined>> \| undefined) => void` | Validates every spawn-bound string of one environment override map. |
172
+ | `validateCommand` | function | `(command: ProcessCommand) => void` | Validates every spawn-bound string of one command. |
173
+ | `validateWorkspace` | function | `(workspace: string \| undefined) => void` | Validates the working directory one child starts in. |
174
174
 
175
175
  ### Constants
176
176
 
@@ -178,17 +178,17 @@ The defaults and host bounds, from `@orkestrel/process`.
178
178
 
179
179
  A `Shape` cell holds the constant's declared type.
180
180
 
181
- | API | Kind | Shape | Summary |
182
- | ---------------------- | ----- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
183
- | `PROCESS_GRACE` | const | `number` | Names the default cooperative POSIX window, 5000 ms, between `SIGTERM` and `SIGKILL` during termination. |
184
- | `PROCESS_CONFIRMATION` | const | `number` | Names the window, 5000 ms, a termination waits for the child's native exit after the final kill. |
185
- | `PROCESS_DRAIN` | const | `number` | Names the default window, 1000 ms, the package waits for the child's read ends to close after the child's native exit or after a termination this package initiated, before cutting them off. |
186
- | `PROCESS_EVIDENCE` | const | `number` | Names the default maximum retained stderr tail, 2048 bytes, for a supervised `ProcessInterface`. |
187
- | `PROCESS_BACKLOG` | const | `number` | Names the default soft high-water mark, 10485760 bytes, for a supervised `ProcessInterface` line backlog. |
188
- | `PROCESS_OUTPUT` | const | `number` | Names the default maximum captured bytes, 10485760 each, for a one-shot run's stdout and stderr. |
189
- | `PROCESS_TIMER` | const | `number` | Names the largest timer delay, 2147483647 ms, the host schedules without truncating it to one. |
190
- | `PROCESS_PATHEXT` | const | `string` | Lists the executable extensions a Windows lookup applies when the environment declares no `PATHEXT`, `.COM;.EXE;.BAT;.CMD`. |
191
- | `PROCESS_ERROR_CODES` | const | `readonly ProcessErrorCode[]` | Lists the machine-readable failure categories a `ProcessError` carries, in declaration order: `spawn`, `timeout`, `input`, `duplicate`, `protocol`, and `invalid`. |
181
+ | Name | Kind | Signature | Summary |
182
+ | ---------------------- | ----- | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
183
+ | `PROCESS_GRACE` | const | `5000` | Names the default cooperative POSIX window, 5000 ms, between `SIGTERM` and `SIGKILL` during termination. |
184
+ | `PROCESS_CONFIRMATION` | const | `5000` | Names the window, 5000 ms, a termination waits for the child's native exit after the final kill. |
185
+ | `PROCESS_DRAIN` | const | `1000` | Names the default window, 1000 ms, the package waits for the child's read ends to close after the child's native exit or after a termination this package initiated, before cutting them off. |
186
+ | `PROCESS_EVIDENCE` | const | `2048` | Names the default maximum retained stderr tail, 2048 bytes, for a supervised `ProcessInterface`. |
187
+ | `PROCESS_BACKLOG` | const | `10485760` | Names the default soft high-water mark, 10485760 bytes, for a supervised `ProcessInterface` line backlog. |
188
+ | `PROCESS_OUTPUT` | const | `10485760` | Names the default maximum captured bytes, 10485760 each, for a one-shot run's stdout and stderr. |
189
+ | `PROCESS_TIMER` | const | `2147483647` | Names the largest timer delay, 2147483647 ms, the host schedules without truncating it to one. |
190
+ | `PROCESS_PATHEXT` | const | `".COM;.EXE;.BAT;.CMD"` | Lists the executable extensions a Windows lookup applies when the environment declares no `PATHEXT`, `.COM;.EXE;.BAT;.CMD`. |
191
+ | `PROCESS_ERROR_CODES` | const | `readonly ["spawn", "timeout", "input", "duplicate", "protocol", "invalid"]` | Lists the machine-readable failure categories a `ProcessError` carries, in declaration order: `spawn`, `timeout`, `input`, `duplicate`, `protocol`, and `invalid`. |
192
192
 
193
193
  ### Types
194
194
 
@@ -196,29 +196,29 @@ The contracts and options, all from `@orkestrel/process`.
196
196
 
197
197
  A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`.
198
198
 
199
- | API | Kind | Shape | Summary |
200
- | ------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
201
- | `ProcessCommand` | interface | `{ file, arguments, environment?, input?, isolated? }` | Represents one spawnable command: the executable, its argument vector, and optional environment overrides and initial standard input. |
202
- | `ProcessExit` | interface | `{ code, signal, drained }` | Represents the observed terminal state of a child process: its exit code or the signal that ended it, and how its observation ended. |
203
- | `SpawnInput` | interface | `{ file, arguments, verbatim }` | Represents the resolved spawn form of one command: the executable to launch, the argument vector to pass, and whether the host receives that vector verbatim. |
204
- | `ExecutableOptions` | interface | `{ workspace?, environment? }` | Supplies the lookup inputs for resolving a command file to an executable path. |
205
- | `ProcessEventMap` | type | `{ stderr, error, exit }` | Represents the push observation surface of a `ProcessInterface` — the moments a fire-and-forget observer subscribes to, alongside the `lines` stream and the `exit` promise. |
206
- | `ProcessOptions` | interface | `{ on?, error?, command, workspace, grace?, drain?, evidence?, backlog?, delivery?, writable?, signal? }` | Configures one supervised child process. |
207
- | `ProcessInterface` | interface | `{ pid, code, signal, emitter, lines, evidence, truncated, settled, terminated, exit } plus send, stop, destroy` | Represents one supervised child process with framed output, a bounded backlog, and bounded termination. |
208
- | `SessionEventMap` | type | `{ stdout, stderr, error, exit }` | Represents the push observation surface of a `SessionInterface` — the moments a byte-oriented observer subscribes to, alongside the `ended` and `exit` promises. |
209
- | `SessionOptions` | interface | `{ on?, error?, command, workspace, grace?, drain?, evidence?, delivery?, signal? }` | Configures one raw byte session over a supervised child. |
210
- | `SessionInterface` | interface | `{ pid, code, signal, emitter, evidence, settled, terminated, ended, exit } plus write, end, stop, destroy` | Represents one supervised child process read as raw bytes, with an open standard-input channel and bounded termination. |
211
- | `ExecuteResult` | interface | `{ command, stdout, stderr, code, signal, failed, expired, aborted, truncated }` | Represents the settled outcome of a one-shot run: the buffered output and the terminal state. |
212
- | `ExecuteInput` | interface | `{ command, stdout, stderr, code, signal, expired, aborted, truncated, limit, cause? }` | Represents the captured bytes and terminal facts one settled `ExecuteResult` is built from. |
213
- | `ExecuteOptions` | interface | `{ workspace?, environment?, input?, timeout?, grace?, signal?, strict?, limit? }` | Configures a one-shot run. |
214
- | `ExecuteSyncOptions` | interface | `{ workspace?, environment?, input?, timeout?, strict?, limit? }` | Configures a synchronous one-shot run. |
215
- | `DetachOptions` | interface | `{ workspace? }` | Configures a detached fire-and-forget spawn. |
216
- | `ProcessManagerEventMap` | type | `{ launch, exit }` | Represents the push observation surface of a `ProcessManagerInterface` — the fleet-level moments a fire-and-forget observer subscribes to. |
217
- | `ProcessManagerOptions` | interface | `{ on?, error? }` | Configures a `ProcessManagerInterface`. |
218
- | `ProcessManagerInterface` | interface | `{ emitter, count } plus process, processes, launch, stop, destroy` | Represents a keyed registry of live supervised child processes. |
219
- | `ProcessErrorCode` | type | `(typeof PROCESS_ERROR_CODES)[number]` | Names the machine-readable `ProcessError` categories, derived from `PROCESS_ERROR_CODES`: `spawn`, `timeout`, `input`, `duplicate`, `protocol`, and `invalid`. |
220
- | `ProcessErrorContext` | interface | `{ id?, command?, code?, signal?, value? }` | Represents structured context carried by a `ProcessError`. |
221
- | `ProcessErrorOptions` | interface | `{ code, context?, cause?, result? }` | Configures a `ProcessError`. |
199
+ | Name | Kind | Signature | Summary |
200
+ | ------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
201
+ | `ProcessCommand` | interface | `{ file, arguments, environment?, input?, isolated? }` | Represents one spawnable command: the executable, its argument vector, and optional environment overrides and initial standard input. |
202
+ | `ProcessExit` | interface | `{ code, signal, drained }` | Represents the observed terminal state of a child process: its exit code or the signal that ended it, and how its observation ended. |
203
+ | `SpawnInput` | interface | `{ file, arguments, verbatim }` | Represents the resolved spawn form of one command: the executable to launch, the argument vector to pass, and whether the host receives that vector verbatim. |
204
+ | `ExecutableOptions` | interface | `{ workspace?, environment? }` | Supplies the lookup inputs for resolving a command file to an executable path. |
205
+ | `ProcessEventMap` | type | `{ readonly stderr: readonly [chunk: string]; readonly error: readonly [error: unknown]; readonly exit: readonly [exit: ProcessExit]; }` | Represents the push observation surface of a `ProcessInterface` — the moments a fire-and-forget observer subscribes to, alongside the `lines` stream and the `exit` promise. |
206
+ | `ProcessOptions` | interface | `{ on?, error?, command, workspace, grace?, drain?, evidence?, backlog?, delivery?, writable?, signal? }` | Configures one supervised child process. |
207
+ | `ProcessInterface` | interface | `{ pid, code, signal, emitter, lines, evidence, truncated, settled, terminated, exit, send(), stop(), destroy() }` | Represents one supervised child process with framed output, a bounded backlog, and bounded termination. |
208
+ | `SessionEventMap` | type | `{ readonly stdout: readonly [chunk: Uint8Array]; readonly stderr: readonly [chunk: string]; readonly error: readonly [error: unknown]; readonly exit: readonly [exit: ProcessExit]; }` | Represents the push observation surface of a `SessionInterface` — the moments a byte-oriented observer subscribes to, alongside the `ended` and `exit` promises. |
209
+ | `SessionOptions` | interface | `{ on?, error?, command, workspace, grace?, drain?, evidence?, delivery?, signal? }` | Configures one raw byte session over a supervised child. |
210
+ | `SessionInterface` | interface | `{ pid, code, signal, emitter, evidence, settled, terminated, ended, exit, write(), end(), stop(), destroy() }` | Represents one supervised child process read as raw bytes, with an open standard-input channel and bounded termination. |
211
+ | `ExecuteResult` | interface | `{ command, stdout, stderr, code, signal, failed, expired, aborted, truncated }` | Represents the settled outcome of a one-shot run: the buffered output and the terminal state. |
212
+ | `ExecuteInput` | interface | `{ command, stdout, stderr, code, signal, expired, aborted, truncated, limit, cause? }` | Represents the captured bytes and terminal facts one settled `ExecuteResult` is built from. |
213
+ | `ExecuteOptions` | interface | `{ workspace?, environment?, input?, timeout?, grace?, signal?, strict?, limit? }` | Configures a one-shot run. |
214
+ | `ExecuteSyncOptions` | interface | `{ workspace?, environment?, input?, timeout?, strict?, limit? }` | Configures a synchronous one-shot run. |
215
+ | `DetachOptions` | interface | `{ workspace? }` | Configures a detached fire-and-forget spawn. |
216
+ | `ProcessManagerEventMap` | type | `{ readonly launch: readonly [id: string]; readonly exit: readonly [id: string, exit: ProcessExit]; }` | Represents the push observation surface of a `ProcessManagerInterface` — the fleet-level moments a fire-and-forget observer subscribes to. |
217
+ | `ProcessManagerOptions` | interface | `{ on?, error? }` | Configures a `ProcessManagerInterface`. |
218
+ | `ProcessManagerInterface` | interface | `{ emitter, count, process(), processes(), launch(), stop(), destroy() }` | Represents a keyed registry of live supervised child processes. |
219
+ | `ProcessErrorCode` | type | `(typeof PROCESS_ERROR_CODES)[number]` | Names the machine-readable `ProcessError` categories, derived from `PROCESS_ERROR_CODES`: `spawn`, `timeout`, `input`, `duplicate`, `protocol`, and `invalid`. |
220
+ | `ProcessErrorContext` | interface | `{ id?, command?, code?, signal?, value? }` | Represents structured context carried by a `ProcessError`. |
221
+ | `ProcessErrorOptions` | interface | `{ code, context?, cause?, result? }` | Configures a `ProcessError`. |
222
222
 
223
223
  ### Server contracts
224
224
 
@@ -230,9 +230,9 @@ Node-only `Supervisor` engine, so the contract sits with the face that construct
230
230
 
231
231
  A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`.
232
232
 
233
- | API | Kind | Shape | Summary |
233
+ | Name | Kind | Signature | Summary |
234
234
  | ----------------------- | --------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
235
- | `ProcessChildInterface` | interface | `{ pid?, exitCode, signalCode } plus kill, once, off` | Represents the child boundary the termination helpers drive. |
235
+ | `ProcessChildInterface` | interface | `{ pid?, exitCode, signalCode, kill(), once(), off() }` | Represents the child boundary the termination helpers drive. |
236
236
  | `SupervisorFace` | interface | `{ chunk, fault, relieve?, close, terminal, teardown }` | Represents the composing face's callbacks for each lifecycle moment of one supervised child. |
237
237
 
238
238
  ### Surface notes