@orkestrel/scaffold 0.0.123 → 0.0.125

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/dist/agents/skills/orkestrel-publish/scripts/steps.js +523 -0
  2. package/dist/agents/skills/orkestrel-publish/scripts/wave.js +70 -11
  3. package/dist/bin/main.js +18 -18
  4. package/dist/bin/main.js.map +1 -1
  5. package/dist/host/agents/orchestration.md +5 -1
  6. package/dist/host/agents/platforms/windows.md +9 -1
  7. package/dist/host/agents/skills/orkestrel-dispatch/SKILL.md +1 -1
  8. package/dist/host/agents/skills/orkestrel-falsify/references/brief.md +1 -0
  9. package/dist/host/agents/skills/orkestrel-harden/references/methods.md +30 -2
  10. package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +1 -0
  11. package/dist/host/agents/skills/orkestrel-parallel/references/t3.md +5 -1
  12. package/dist/host/agents/skills/orkestrel-publish/SKILL.md +1 -0
  13. package/dist/host/agents/skills/orkestrel-publish/references/release.md +2 -2
  14. package/dist/host/agents/skills/orkestrel-publish/references/wave.md +23 -6
  15. package/dist/host/agents/skills/orkestrel-publish/scripts/steps.ts +654 -0
  16. package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +79 -14
  17. package/dist/host/claude/agents/orkestrel.md +45 -45
  18. package/dist/host/claude/rules/patterns.md +1 -1
  19. package/dist/host/claude/rules/portability.md +2 -0
  20. package/dist/host/claude/rules/quality.md +3 -1
  21. package/dist/host/claude/rules/tests.md +3 -1
  22. package/dist/host/guides/agent.md +349 -244
  23. package/dist/host/guides/brief.md +52 -48
  24. package/dist/host/guides/browser.md +2 -2
  25. package/dist/host/guides/contract.md +226 -104
  26. package/dist/host/guides/database.md +12 -12
  27. package/dist/host/guides/interpret.md +531 -155
  28. package/dist/host/guides/mcp.md +183 -61
  29. package/dist/host/guides/ndjson.md +47 -34
  30. package/dist/host/guides/ollama.md +123 -66
  31. package/dist/host/guides/program.md +117 -39
  32. package/dist/host/guides/qualifier.md +110 -59
  33. package/dist/host/guides/rater.md +85 -32
  34. package/dist/host/guides/reason.md +377 -114
  35. package/dist/host/guides/scaffold.md +20 -12
  36. package/dist/host/guides/study.md +580 -483
  37. package/dist/host/guides/tool.md +163 -58
  38. package/dist/host/guides/toolbox.md +159 -80
  39. package/dist/host/guides/workflow.md +44 -25
  40. package/dist/host/manifest.json +41 -35
  41. package/dist/src/core/index.cjs +17 -17
  42. package/dist/src/core/index.cjs.map +1 -1
  43. package/dist/src/core/index.js +17 -17
  44. package/dist/src/core/index.js.map +1 -1
  45. package/dist/src/server/index.cjs +23 -11
  46. package/dist/src/server/index.cjs.map +1 -1
  47. package/dist/src/server/index.d.cts +10 -6
  48. package/dist/src/server/index.d.ts +10 -6
  49. package/dist/src/server/index.js +23 -11
  50. package/dist/src/server/index.js.map +1 -1
  51. package/package.json +17 -17
@@ -2,24 +2,26 @@
2
2
 
3
3
  > A stateful newline-delimited-JSON (NDJSON) stream parser: a self-contained handle
4
4
  > that turns string chunks into the complete records decoded so far, skips a blank
5
- > line, and skips a malformed or non-record line unless strict mode refuses it.
5
+ > line, and refuses a malformed or non-record line unless `strict: false` skips it.
6
6
 
7
7
  `parse(chunk)` appends `chunk` to an internal buffer and splits it on `\n`: every
8
8
  line before the last is `\n`-terminated, hence complete, and is parsed to a record,
9
9
  while the final segment is held back for the next call, so a line split across chunk
10
10
  boundaries is reassembled the moment its closing `\n` arrives. Each trimmed line is
11
11
  filtered — a blank or whitespace-only line (including one whose only content was a
12
- CRLF's trailing `\r`) is skipped, and by default malformed JSON is skipped silently
13
- and a non-record value (an array, a primitive, `null`) is dropped — so only plain
14
- records come back, and a line the stream never terminates is never emitted even when
15
- the buffered text already happens to be valid JSON. With `strict: true` the parser
16
- refuses such a line instead: `parse` throws an `NDJSONError` with code `'SYNTAX'`
17
- for a complete line that is not valid JSON and `'RECORD'` for a complete line that is
18
- not a plain record. The throwing call returns no record, discards the lines after the
19
- refused line in the same call too, and leaves the parser cleared, as `clear()` leaves
20
- it. Blank lines are skipped, and lines are split and trimmed, the same way in both
21
- modes. An unterminated line throws nothing until a later chunk completes it, so a
22
- caller ends a stream with `parse('\n')`. `clear()` drops the buffered partial
12
+ CRLF's trailing `\r`) is skipped — so only plain records come back, and a line the
13
+ stream never terminates is never emitted even when the buffered text already happens
14
+ to be valid JSON. By default the parser refuses a line it cannot return: `parse`
15
+ throws an `NDJSONError` with code `'SYNTAX'` for a complete line that is not valid
16
+ JSON and `'RECORD'` for a complete line that is not a plain record. The throwing call
17
+ returns no record, discards the lines after the refused line in the same call too, and
18
+ leaves the parser cleared, as `clear()` leaves it. With `strict: false` the parser
19
+ skips such a line instead, for a caller that prefers the records it can read over a
20
+ refusal. Blank lines are skipped, and lines are split and trimmed, the same way in both
21
+ modes. A chunk that is not a string throws `'SYNTAX'` in both modes, because joining it
22
+ to the buffer would corrupt the line it holds. An unterminated line throws nothing until
23
+ a later chunk completes it, so a caller ends a stream with `parse('\n')`, which refuses
24
+ a half record unless the parser is lenient. `clear()` drops the buffered partial
23
25
  line so a handle can be reused for a fresh stream. Nothing else is wired in: no
24
26
  Emitter, no server, HTTP, or agent coupling. Pair it with a streaming `TextDecoder`
25
27
  when reading a byte stream — the decoder handles partial characters, the parser
@@ -47,8 +49,8 @@ parser.clear() // drop any buffered partial - ready for a fresh stream
47
49
  | Name | Kind | Signature | Summary |
48
50
  | ----------------------- | --------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
49
51
  | `NDJSONParserInterface` | interface | `{ parse(), clear() }` | Represents the stateful NDJSON (newline-delimited JSON) stream-parser contract a consumer holds — a `parse` that turns each string chunk into the complete records decoded so far, and a `clear` that drops the buffered partial line. |
50
- | `NDJSONParserOptions` | interface | `{ strict? }` | Configures the parser `createNDJSONParser` builds and the `NDJSONParser` constructor accepts — `strict` decides whether a complete line that is not a JSON object is skipped or refused. |
51
- | `NDJSONErrorCode` | type | `'SYNTAX' \| 'RECORD'` | Names the machine-readable code an `NDJSONError` carries — `'SYNTAX'` for a complete line that is not valid JSON, and `'RECORD'` for a complete line that is valid JSON but not a plain record. |
52
+ | `NDJSONParserOptions` | interface | `{ strict? }` | Configures the parser `createNDJSONParser` builds and the `NDJSONParser` constructor accepts — `strict` decides whether a complete line that is not a JSON object is refused or skipped. |
53
+ | `NDJSONErrorCode` | type | `'SYNTAX' \| 'RECORD'` | Names the machine-readable code an `NDJSONError` carries — `'SYNTAX'` for a chunk that is not a string or a complete line that is not valid JSON, and `'RECORD'` for a complete line that is valid JSON but not a plain record. |
52
54
 
53
55
  Types a helper's parameter as `NDJSONParserInterface` and returns the records
54
56
  its `parse` call completes:
@@ -63,20 +65,20 @@ function feed(parser: NDJSONParserInterface, chunk: string): readonly Record<str
63
65
 
64
66
  ### Errors
65
67
 
66
- A strict parser throws an `NDJSONError`, and `isNDJSONError` narrows a caught value to
67
- one:
68
+ A parser throws an `NDJSONError` unless `strict: false` skips the line, and
69
+ `isNDJSONError` narrows a caught value to one:
68
70
 
69
- | Name | Kind | Signature | Summary |
70
- | --------------- | -------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
71
- | `NDJSONError` | class | `new (code: NDJSONErrorCode, message: string) => NDJSONError` | Represents the refusal of a complete NDJSON line by a strict parser, carrying the machine-readable `NDJSONErrorCode` a `catch` branches on. |
72
- | `isNDJSONError` | function | `(value: unknown) => value is NDJSONError` | Narrows an unknown caught value to an `NDJSONError`. |
71
+ | Name | Kind | Signature | Summary |
72
+ | --------------- | -------- | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
73
+ | `NDJSONError` | class | `new (code: NDJSONErrorCode, message: string) => NDJSONError` | Represents a parser's refusal of a chunk or of a complete NDJSON line, carrying the machine-readable `NDJSONErrorCode` a `catch` branches on. |
74
+ | `isNDJSONError` | function | `(value: unknown) => value is NDJSONError` | Narrows an unknown caught value to an `NDJSONError`. |
73
75
 
74
76
  Catches the refusal of a truncated line and branches on its code:
75
77
 
76
78
  ```ts
77
79
  import { createNDJSONParser, isNDJSONError } from '@orkestrel/ndjson'
78
80
 
79
- const parser = createNDJSONParser({ strict: true })
81
+ const parser = createNDJSONParser()
80
82
  try {
81
83
  parser.parse('{"a":\n')
82
84
  } catch (error) {
@@ -111,16 +113,16 @@ parser.parse('{"c":3}') // [] — buffered until its trailing newline arrives
111
113
  parser.parse('\n') // [{ c: 3 }]
112
114
  ```
113
115
 
114
- #### Create a strict parser
116
+ #### Refuse a line
115
117
 
116
- Creates a parser that refuses a non-record line, then shows that the refusal dropped the
117
- partial line the same call carried:
118
+ Refuses a non-record line by default, then shows that the refusal dropped the partial
119
+ line the same call carried:
118
120
 
119
121
  ```ts
120
122
  import { createNDJSONParser, isNDJSONError } from '@orkestrel/ndjson'
121
123
 
122
- const parser = createNDJSONParser({ strict: true })
123
- parser.parse('{"a":1}\n\n') // [{ a: 1 }] - a blank line is still skipped
124
+ const parser = createNDJSONParser()
125
+ parser.parse('{"a":1}\n\n') // [{ a: 1 }] - a blank line is skipped
124
126
  try {
125
127
  parser.parse('[1,2]\n{"b"')
126
128
  } catch (error) {
@@ -130,6 +132,17 @@ parser.parse('\n') // [] - the refusal dropped the partial line
130
132
  parser.parse('{"b":2}\n') // [{ b: 2 }]
131
133
  ```
132
134
 
135
+ #### Create a lenient parser
136
+
137
+ Creates a parser that skips what the default refuses:
138
+
139
+ ```ts
140
+ import { createNDJSONParser } from '@orkestrel/ndjson'
141
+
142
+ const parser = createNDJSONParser({ strict: false })
143
+ parser.parse('not json\n\n{"a":1}\n[1,2]\n') // [{ a: 1 }] - malformed, blank, and non-record lines skipped
144
+ ```
145
+
133
146
  ### Classes
134
147
 
135
148
  | Name | Kind | Signature | Summary |
@@ -143,13 +156,13 @@ surface.
143
156
 
144
157
  #### `NDJSONParserInterface`
145
158
 
146
- | Method | Returns | Summary |
147
- | ------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
148
- | `parse` | `readonly Record<string, unknown>[]` | Appends `chunk` to the buffer and returns every complete `\n`-terminated line parsed to a record, skipping a malformed or non-record line unless the parser is strict; the trailing partial line is retained for the next call unless a strict refusal in the same call clears the buffer, so a line split across a chunk boundary is reassembled when its closing `\n` arrives. |
149
- | `clear` | `void` | Drops any buffered partial line, leaving the handle ready for a fresh stream. |
159
+ | Method | Returns | Summary |
160
+ | ------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
161
+ | `parse` | `readonly Record<string, unknown>[]` | Appends `chunk` to the buffer and returns every complete `\n`-terminated line parsed to a record, refusing a malformed or non-record line unless the parser is lenient; the trailing partial line is retained for the next call unless a refusal in the same call clears the buffer, so a line split across a chunk boundary is reassembled when its closing `\n` arrives. |
162
+ | `clear` | `void` | Drops any buffered partial line, leaving the handle ready for a fresh stream. |
150
163
 
151
- `parse` holds an unterminated line indefinitely, unless a strict refusal in the
152
- same call clears the buffer, and the buffer has no size limit, so a caller fronting an
164
+ `parse` holds an unterminated line indefinitely, unless a refusal in the same call
165
+ clears the buffer, and the buffer has no size limit, so a caller fronting an
153
166
  untrusted upstream enforces its own byte cap.
154
167
 
155
168
  ```ts
@@ -164,8 +177,8 @@ parser.parse('{"c":3}\n') // [{ c: 3 }]
164
177
 
165
178
  ## Tests
166
179
 
167
- - [`tests/guides.test.ts`](../tests/guides.test.ts) — the `## Surface` ↔ `src/core` bijection (value and type exports), the `NDJSONParserInterface` ↔ `NDJSONParser` method bijection, and the equality gate: every `Summary` cell against its declaration's description paragraph, the titled `Create a parser` and `Create a strict parser` fences against the `@example` blocks of those titles (pinned so the titled pairs cannot be retired silently), and the README pitch against this guide's tagline. It also runs the flagship fences, the strict and Errors fences included, and asserts the values their comments claim.
168
- - [`tests/src/core/NDJSONParser.test.ts`](../tests/src/core/NDJSONParser.test.ts) — that `parse` returns the same records however a stream is cut into chunks, skipping malformed, blank, and non-record lines, withholding a line the stream never terminates, and never throwing on any input by default; and that a strict parser refuses each malformed line as `'SYNTAX'` and each non-record line as `'RECORD'` with a fixed message, returns no record from the refusing call and leaves the parser cleared, keeps its records however a clean stream is cut into chunks, trims every Unicode space `String.prototype.trim` strips, and returns what the default returns when `strict` is `false`.
180
+ - [`tests/guides.test.ts`](../tests/guides.test.ts) — the `## Surface` ↔ `src/core` bijection (value and type exports), the `NDJSONParserInterface` ↔ `NDJSONParser` method bijection, and the equality gate: every `Summary` cell against its declaration's description paragraph, the titled `Create a parser`, `Refuse a line`, and `Create a lenient parser` fences against the `@example` blocks of those titles (pinned so the titled pairs cannot be retired silently), and the README pitch against this guide's tagline. It also runs the flagship fences, the refusal, lenient, and Errors fences included, and asserts the values their comments claim.
181
+ - [`tests/src/core/NDJSONParser.test.ts`](../tests/src/core/NDJSONParser.test.ts) — that `parse` returns the same records however a stream is cut into chunks, skipping blank lines and withholding a line the stream never terminates; that the default parser, and one built with any `strict` value but `false`, refuses each malformed line as `'SYNTAX'` and each non-record line as `'RECORD'` with a fixed message, returns no record from the refusing call and leaves the parser cleared, keeps its records however a clean stream is cut into chunks, and trims every Unicode space `String.prototype.trim` strips; that a chunk that is not a string is refused in both modes; and that a `strict: false` parser skips what the default refuses and never throws on a line.
169
182
  - [`tests/src/core/errors.test.ts`](../tests/src/core/errors.test.ts) — that `isNDJSONError` accepts an `NDJSONError` and a subclass, refuses a look-alike, a transparent proxy, a plain object carrying the brand, and an unknown code, and that the constructor stamps a hidden, fixed brand.
170
183
  - [`tests/policy.test.ts`](../tests/policy.test.ts) — repository coding law: source placement, exports, readonly contracts, syntax, and the prose this guide is written in.
171
184
  - [`tests/config.test.ts`](../tests/config.test.ts) — the root configuration's aliases and projects, the policy Oxlint plugin's rules against its rule tester, and the configuration helpers.