@orkestrel/scaffold 0.0.115 → 0.0.117
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/bin/main.js +138 -16
- package/dist/bin/main.js.map +1 -1
- package/dist/host/agents/skills/orkestrel-publish/references/wave.md +1 -1
- package/dist/host/claude/agents/orkestrel.md +2 -2
- package/dist/host/claude/rules/names.md +3 -1
- package/dist/host/guides/abort.md +17 -17
- package/dist/host/guides/agent.md +445 -445
- package/dist/host/guides/brief.md +143 -143
- package/dist/host/guides/browser.md +731 -731
- package/dist/host/guides/budget.md +39 -39
- package/dist/host/guides/capture.md +298 -298
- package/dist/host/guides/console.md +109 -109
- package/dist/host/guides/contract.md +335 -335
- package/dist/host/guides/csv.md +30 -30
- package/dist/host/guides/database.md +163 -163
- package/dist/host/guides/emitter.md +17 -17
- package/dist/host/guides/form.md +99 -99
- package/dist/host/guides/guide.md +368 -183
- package/dist/host/guides/html.md +49 -49
- package/dist/host/guides/indexeddb.md +40 -40
- package/dist/host/guides/interpret.md +139 -139
- package/dist/host/guides/lsp.md +114 -114
- package/dist/host/guides/markdown.md +68 -68
- package/dist/host/guides/mcp.md +3745 -3745
- package/dist/host/guides/middleware.md +170 -170
- package/dist/host/guides/msg.md +95 -95
- package/dist/host/guides/ndjson.md +8 -8
- package/dist/host/guides/ollama.md +56 -56
- package/dist/host/guides/pool.md +21 -21
- package/dist/host/guides/probe.md +82 -82
- package/dist/host/guides/process.md +99 -99
- package/dist/host/guides/program.md +98 -96
- package/dist/host/guides/qualifier.md +70 -70
- package/dist/host/guides/queue.md +37 -37
- package/dist/host/guides/rater.md +38 -38
- package/dist/host/guides/reason.md +308 -308
- package/dist/host/guides/relation.md +50 -50
- package/dist/host/guides/router.md +58 -58
- package/dist/host/guides/scaffold.md +558 -419
- package/dist/host/guides/sea.md +128 -128
- package/dist/host/guides/server.md +100 -100
- package/dist/host/guides/sqlite.md +28 -28
- package/dist/host/guides/sse.md +20 -20
- package/dist/host/guides/study.md +444 -444
- package/dist/host/guides/table.md +82 -82
- package/dist/host/guides/template.md +41 -41
- package/dist/host/guides/terminal.md +121 -121
- package/dist/host/guides/test.md +273 -273
- package/dist/host/guides/timeout.md +18 -18
- package/dist/host/guides/tool.md +27 -27
- package/dist/host/guides/toolbox.md +166 -166
- package/dist/host/guides/websocket.md +54 -54
- package/dist/host/guides/worker.md +24 -24
- package/dist/host/guides/workflow.md +187 -187
- package/dist/host/guides/workspace.md +55 -55
- package/dist/host/manifest.json +55 -55
- package/dist/host/tests/setupPolicy.ts +5 -3
- package/dist/src/core/index.cjs +90 -4
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.d.cts +229 -144
- package/dist/src/core/index.d.ts +229 -144
- package/dist/src/core/index.js +88 -5
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +295 -66
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +193 -6
- package/dist/src/server/index.d.ts +193 -6
- package/dist/src/server/index.js +290 -69
- package/dist/src/server/index.js.map +1 -1
- package/package.json +5 -4
|
@@ -53,21 +53,21 @@ await child.destroy()
|
|
|
53
53
|
|
|
54
54
|
The interface-oriented constructors, from `@orkestrel/process/server`.
|
|
55
55
|
|
|
56
|
-
|
|
|
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
|
-
|
|
|
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
|
-
|
|
|
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
|
-
|
|
|
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
|
-
|
|
|
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
|
-
|
|
|
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
|
-
|
|
|
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
|
-
|
|
|
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
|
-
|
|
|
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
|
-
|
|
|
182
|
-
| ---------------------- | ----- |
|
|
183
|
-
| `PROCESS_GRACE` | const | `
|
|
184
|
-
| `PROCESS_CONFIRMATION` | const | `
|
|
185
|
-
| `PROCESS_DRAIN` | const | `
|
|
186
|
-
| `PROCESS_EVIDENCE` | const | `
|
|
187
|
-
| `PROCESS_BACKLOG` | const | `
|
|
188
|
-
| `PROCESS_OUTPUT` | const | `
|
|
189
|
-
| `PROCESS_TIMER` | const | `
|
|
190
|
-
| `PROCESS_PATHEXT` | const | `
|
|
191
|
-
| `PROCESS_ERROR_CODES` | const | `readonly
|
|
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
|
-
|
|
|
200
|
-
| ------------------------- | --------- |
|
|
201
|
-
| `ProcessCommand` | interface | `{ file, arguments, environment?, input?, isolated? }`
|
|
202
|
-
| `ProcessExit` | interface | `{ code, signal, drained }`
|
|
203
|
-
| `SpawnInput` | interface | `{ file, arguments, verbatim }`
|
|
204
|
-
| `ExecutableOptions` | interface | `{ workspace?, environment? }`
|
|
205
|
-
| `ProcessEventMap` | type | `{ stderr
|
|
206
|
-
| `ProcessOptions` | interface | `{ on?, error?, command, workspace, grace?, drain?, evidence?, backlog?, delivery?, writable?, signal? }`
|
|
207
|
-
| `ProcessInterface` | interface | `{ pid, code, signal, emitter, lines, evidence, truncated, settled, terminated, exit
|
|
208
|
-
| `SessionEventMap` | type | `{ stdout
|
|
209
|
-
| `SessionOptions` | interface | `{ on?, error?, command, workspace, grace?, drain?, evidence?, delivery?, signal? }`
|
|
210
|
-
| `SessionInterface` | interface | `{ pid, code, signal, emitter, evidence, settled, terminated, ended, exit
|
|
211
|
-
| `ExecuteResult` | interface | `{ command, stdout, stderr, code, signal, failed, expired, aborted, truncated }`
|
|
212
|
-
| `ExecuteInput` | interface | `{ command, stdout, stderr, code, signal, expired, aborted, truncated, limit, cause? }`
|
|
213
|
-
| `ExecuteOptions` | interface | `{ workspace?, environment?, input?, timeout?, grace?, signal?, strict?, limit? }`
|
|
214
|
-
| `ExecuteSyncOptions` | interface | `{ workspace?, environment?, input?, timeout?, strict?, limit? }`
|
|
215
|
-
| `DetachOptions` | interface | `{ workspace? }`
|
|
216
|
-
| `ProcessManagerEventMap` | type | `{ launch, exit }`
|
|
217
|
-
| `ProcessManagerOptions` | interface | `{ on?, error? }`
|
|
218
|
-
| `ProcessManagerInterface` | interface | `{ emitter, count
|
|
219
|
-
| `ProcessErrorCode` | type | `(typeof PROCESS_ERROR_CODES)[number]`
|
|
220
|
-
| `ProcessErrorContext` | interface | `{ id?, command?, code?, signal?, value? }`
|
|
221
|
-
| `ProcessErrorOptions` | interface | `{ code, context?, cause?, result? }`
|
|
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
|
-
|
|
|
233
|
+
| Name | Kind | Signature | Summary |
|
|
234
234
|
| ----------------------- | --------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
|
|
235
|
-
| `ProcessChildInterface` | interface | `{ pid?, exitCode, signalCode
|
|
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
|