@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
@@ -45,7 +45,7 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?`
45
45
  marking an optional member and `plus` introducing its call-signature members,
46
46
  and a type alias's own type literal with a union's arms escaped as `\|`.
47
47
 
48
- | Type | Kind | Shape | Summary |
48
+ | Name | Kind | Signature | Summary |
49
49
  | ----------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
50
50
  | `Row` | type | `Record<string, unknown>` | Represents a CSV row — a plain record of column values keyed by column name. |
51
51
  | `CSVTable` | interface | `{ columns, rows }` | Represents a parsed CSV table — the typed rows plus the column order they were parsed (or declared) in. |
@@ -70,7 +70,7 @@ and a type alias's own type literal with a union's arms escaped as `\|`.
70
70
  | `ExportOptions` | interface | `{ key?, columns? }` | Represents the options for `CSVInterface.export`. |
71
71
  | `TableExport` | interface | `{ key, columns, schema }` | Represents a CSV's portable definition, produced by `CSVInterface.export` — the unit of schema exchange across environments. |
72
72
  | `CSVErrorCode` | type | `'UNTERMINATED_QUOTE' \| 'BAD_QUOTE' \| 'RAGGED_ROW' \| 'DUPLICATE_HEADER' \| 'EMPTY_HEADER' \| 'LIMIT_EXCEEDED' \| 'INVALID_OPTION'` | Names a machine-readable `CSVError` code. |
73
- | `CSVInterface` | interface | `{ table, rows, errors } plus find, filter, map, reduce, stream, toJSON, export` | Represents a parsed, queryable CSV document — the typed `CSVTable` plus the query, rewrite, and export operations over it. |
73
+ | `CSVInterface` | interface | `{ table, rows, errors, find(), filter(), map(), reduce(), stream(), toJSON(), export() }` | Represents a parsed, queryable CSV document — the typed `CSVTable` plus the query, rewrite, and export operations over it. |
74
74
 
75
75
  ### Errors
76
76
 
@@ -78,10 +78,10 @@ From [`errors.ts`](../src/core/errors.ts). An invalid option or programmer
78
78
  error always throws a `CSVError`; a parse-time malformation is collected
79
79
  into a result's `errors` unless `strict` is set.
80
80
 
81
- | Error | Kind | Signature | Summary |
82
- | ------------ | -------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
83
- | `CSVError` | class | `extends Error` | Represents an error surfaced by the CSV layer — either thrown for a programmer error / `strict`-mode parse failure, or collected into a result's `errors` list. |
84
- | `isCSVError` | function | `(value: unknown) => value is CSVError` | Narrows an unknown caught value to a `CSVError`. |
81
+ | Name | Kind | Signature | Summary |
82
+ | ------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
83
+ | `CSVError` | class | `new (code: CSVErrorCode, message: string, location?: Readonly<{ readonly line?: number; readonly column?: number; readonly offset?: number; }>, context?: Readonly<Record<string, unknown>>) => CSVError` | Represents an error surfaced by the CSV layer — either thrown for a programmer error / `strict`-mode parse failure, or collected into a result's `errors` list. |
84
+ | `isCSVError` | function | `(value: unknown) => value is CSVError` | Narrows an unknown caught value to a `CSVError`. |
85
85
 
86
86
  ### Constants
87
87
 
@@ -90,21 +90,21 @@ canonical patterns from, from [`constants.ts`](../src/core/constants.ts).
90
90
 
91
91
  A `Shape` cell holds the constant's declared type.
92
92
 
93
- | Constant | Kind | Shape | Summary |
93
+ | Name | Kind | Signature | Summary |
94
94
  | -------------------------- | ----- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
95
- | `BOM` | const | `string` | Names the UTF-8 byte-order-mark character, `'\uFEFF'`, prepended when `RenderOptions.bom` is `true`. |
95
+ | `BOM` | const | `"\uFEFF"` | Names the UTF-8 byte-order-mark character, `'\uFEFF'`, prepended when `RenderOptions.bom` is `true`. |
96
96
  | `DEFAULT_PARSE_OPTIONS` | const | `Required<Omit<ParseOptions, 'comment'>>` | Holds the resolved default `ParseOptions` (everything but `comment`, which has no default) — what `parseCSV` uses for any option left unspecified: `{ delimiter: ',', quote: '"', escape: 'double', header: true, blanks: true, trim: false, ragged: 'collect', infer: false, limit: 0, strict: false }`. |
97
97
  | `DEFAULT_RENDER_OPTIONS` | const | `Required<Omit<RenderOptions, 'columns'>>` | Holds the resolved default `RenderOptions` (everything but `columns`, which has no default) — what `renderCSV` uses for any option left unspecified: `{ delimiter: ',', quote: '"', escape: 'double', newline: '\r\n', header: true, quotes: 'minimal', blank: '', sanitize: true, bom: false }`. |
98
98
  | `SANITIZE_PREFIXES` | const | `ReadonlySet<string>` | Lists the leading characters the OWASP CSV-injection guard treats as formula-triggering — a field starting with any of these is prefixed with a protective `'` when `RenderOptions.sanitize` is `true`. |
99
- | `POSITIONAL_COLUMN_PREFIX` | const | `string` | Names the prefix used for positional columns (`column1`, `column2`, …) when `ParseOptions.header` is `false`, or a header field is empty — 1-based, `'column'`. |
100
- | `SANITIZE_ESCAPE` | const | `string` | Names the protective prefix `sanitizeField` prepends to a field starting with a formula-triggering character (the OWASP CSV-injection guidance), `"'"`. |
101
- | `SUFFIX_SEPARATOR` | const | `string` | Names the separator between a disambiguated column name and its collision counter (`name` → `name_2`, `name_3`, …) — see `uniqueName`, `'_'`. |
99
+ | `POSITIONAL_COLUMN_PREFIX` | const | `"column"` | Names the prefix used for positional columns (`column1`, `column2`, …) when `ParseOptions.header` is `false`, or a header field is empty — 1-based, `'column'`. |
100
+ | `SANITIZE_ESCAPE` | const | `"'"` | Names the protective prefix `sanitizeField` prepends to a field starting with a formula-triggering character (the OWASP CSV-injection guidance), `"'"`. |
101
+ | `SUFFIX_SEPARATOR` | const | `"_"` | Names the separator between a disambiguated column name and its collision counter (`name` → `name_2`, `name_3`, …) — see `uniqueName`, `'_'`. |
102
102
  | `INTEGER_PATTERN` | const | `RegExp` | Matches a canonical integer only — an optional leading `-`, no leading zeros (except the bare digit `0`), digits only. No `+` sign, no whitespace. |
103
103
  | `REAL_PATTERN` | const | `RegExp` | Matches a canonical decimal only — an optional leading `-`, an integer part with no leading zeros (except the bare digit `0`), an optional `.` followed by at least one digit. No scientific notation, no `NaN` / `Infinity`, no decimal comma, no trailing dot. |
104
104
  | `NUMERIC_PATTERN` | const | `RegExp` | Matches what the renderer treats as a plain number for the `'nonnumeric'` `QuoteStyle` and the sanitize `+` / `-` exemption — like `REAL_PATTERN` but also allowing a leading `+`. |
105
- | `BOOLEAN_TRUE` | const | `string` | Names the canonical serialized form of the boolean `true` — the string `'true'`. |
106
- | `BOOLEAN_FALSE` | const | `string` | Names the canonical serialized form of the boolean `false` — the string `'false'`. |
107
- | `MAX_ERRORS` | const | `number` | Sets the maximum number of `CSVError`s collected into a parse result, `100` — once reached, error collection stops (earlier records already parsed are kept, later malformations are silently no longer recorded). |
105
+ | `BOOLEAN_TRUE` | const | `"true"` | Names the canonical serialized form of the boolean `true` — the string `'true'`. |
106
+ | `BOOLEAN_FALSE` | const | `"false"` | Names the canonical serialized form of the boolean `false` — the string `'false'`. |
107
+ | `MAX_ERRORS` | const | `100` | Sets the maximum number of `CSVError`s collected into a parse result, `100` — once reached, error collection stops (earlier records already parsed are kept, later malformations are silently no longer recorded). |
108
108
 
109
109
  ### Helpers
110
110
 
@@ -114,7 +114,7 @@ hand-written tokenizer and table builders `parsers.ts` composes, and the
114
114
  rendering projections callers reach for directly. Every function is
115
115
  unit-testable in isolation.
116
116
 
117
- | Helper | Kind | Signature | Summary |
117
+ | Name | Kind | Signature | Summary |
118
118
  | ----------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
119
119
  | `assertValidSeparators` | function | `(delimiter: string, quote: string) => void` | Validates a delimiter / quote pair shared by both `resolveParseOptions` and `resolveRenderOptions` — each must be exactly one character, they must differ, and neither may be CR, LF, or the BOM character. |
120
120
  | `resolveParseOptions` | function | `(options?: ParseOptions) => ResolvedParseOptions` | Merges `options` over `DEFAULT_PARSE_OPTIONS` into a fully-resolved parse configuration. |
@@ -151,7 +151,7 @@ Whole-column type inference from
151
151
  holds, rules which `ColumnType` it carries, and applies that ruling cell by
152
152
  cell.
153
153
 
154
- | Inferer | Kind | Signature | Summary |
154
+ | Name | Kind | Signature | Summary |
155
155
  | ----------------- | -------- | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
156
156
  | `inferColumnType` | function | `(values: readonly string[]) => ColumnType` | Infers a whole column's `ColumnType` conservatively from its raw string values — never `'json'` or `'blob'` (those require an explicit `Columns` declaration). Empty-string cells are ignored entirely (they neither confirm nor demote a type); a column with no non-empty cells is `'text'`. |
157
157
  | `coerceInferred` | function | `(value: string, type: ColumnType) => unknown` | Coerces one string cell to `type`'s typed representation — the exhaustive per-cell dispatch `inferRows` applies once a column's type is known. |
@@ -164,7 +164,7 @@ entry point, which composes the `helpers.ts` tokenizer, the `helpers.ts` table
164
164
  builders, and the `inferers.ts` column inference into a `CSVParseResult`, plus
165
165
  the flat cell coercers that inference dispatches to.
166
166
 
167
- | Parser | Kind | Signature | Summary |
167
+ | Name | Kind | Signature | Summary |
168
168
  | -------------- | -------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
169
169
  | `parseCSV` | function | `(input: string, options?: ParseOptions) => CSVParseResult` | Parses `input` into a typed `CSVParseResult` — header mapping, ragged-row handling, and optional type inference on top of `readRecords`, `deriveHeader`, `buildRow`, and `inferRows`. |
170
170
  | `parseInteger` | function | `(value: string) => number \| undefined` | Parses a raw cell string into a canonical integer — `undefined` for anything else (leading zeros, decimals, out-of-safe-range magnitude, non-numeric text). |
@@ -178,11 +178,11 @@ Declarative `ContractShape` values (from `@orkestrel/contract`), from
178
178
  coercing parser, JSON Schema, and seeded generator. `deriveShapes` builds a
179
179
  whole `Columns` map of them from a table's own cell values.
180
180
 
181
- | Shaper | Kind | Signature | Summary |
182
- | ----------------- | -------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
183
- | `columnTypeShape` | function | `(type: ColumnType) => ContractShape` | Returns the `ContractShape` a `ColumnType`'s values must satisfy. |
184
- | `csvTableShape` | const | `ContractShape` | Represents the `ContractShape` of a `CSVTable`'s JSON-serializable projection — an ordered `columns` list of strings plus `rows`, each an open record of JSON values. |
185
- | `deriveShapes` | function | `(table: CSVTable) => Columns` | Derives one `ContractShape` per table column from that column's cell values across all rows (excluding `undefined`/empty-string cells) — the schema-inference leaf behind `CSVInterface.export` when no explicit `Columns` is given. |
181
+ | Name | Kind | Signature | Summary |
182
+ | ----------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
183
+ | `columnTypeShape` | function | `(type: ColumnType) => ContractShape` | Returns the `ContractShape` a `ColumnType`'s values must satisfy. |
184
+ | `csvTableShape` | const | `import("@orkestrel/contract").ObjectShape<{ columns: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").StringShape>; rows: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<Record<never, never>, import("@orkestrel/contract").JSONShape>>; }, false>` | Represents the `ContractShape` of a `CSVTable`'s JSON-serializable projection — an ordered `columns` list of strings plus `rows`, each an open record of JSON values. |
185
+ | `deriveShapes` | function | `(table: CSVTable) => Columns` | Derives one `ContractShape` per table column from that column's cell values across all rows (excluding `undefined`/empty-string cells) — the schema-inference leaf behind `CSVInterface.export` when no explicit `Columns` is given. |
186
186
 
187
187
  ### Validators
188
188
 
@@ -191,19 +191,19 @@ throw, return `false` for any off-shape input.
191
191
 
192
192
  In a guard table a `Shape` cell holds the type the guard narrows to.
193
193
 
194
- | Guard | Kind | Shape | Summary |
195
- | -------------- | ----- | ------------ | --------------------------------------------------------------------------------------------------------------- |
196
- | `isCSVTable` | const | `CSVTable` | Determines whether an arbitrary value is a valid `CSVTable` — an array of column names plus an array of `Row`s. |
197
- | `isColumnType` | const | `ColumnType` | Determines whether a value is a valid `ColumnType` literal. |
194
+ | Name | Kind | Signature | Summary |
195
+ | -------------- | ----- | ------------------- | --------------------------------------------------------------------------------------------------------------- |
196
+ | `isCSVTable` | const | `Guard<CSVTable>` | Determines whether an arbitrary value is a valid `CSVTable` — an array of column names plus an array of `Row`s. |
197
+ | `isColumnType` | const | `Guard<ColumnType>` | Determines whether a value is a valid `ColumnType` literal. |
198
198
 
199
199
  ### Classes
200
200
 
201
201
  The implementing class of `CSVInterface`, from [`CSV.ts`](../src/core/CSV.ts) —
202
202
  documented in full under its own heading following this table.
203
203
 
204
- | Name | Kind | Summary |
205
- | ----- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
206
- | `CSV` | class | Wraps a typed `CSVTable` with the query (`find` / `filter` / `reduce`), rewrite (`map`), streaming, and export operations `CSVInterface` declares. |
204
+ | Name | Kind | Signature | Summary |
205
+ | ----- | ----- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
206
+ | `CSV` | class | `new (input: string \| CSVTable, options?: ParseOptions) => CSVInterface` | Wraps a typed `CSVTable` with the query (`find` / `filter` / `reduce`), rewrite (`map`), streaming, and export operations `CSVInterface` declares. |
207
207
 
208
208
  ### `CSV`
209
209
 
@@ -218,7 +218,7 @@ never mutates the stored table, it returns a new `CSV`. See
218
218
 
219
219
  From [`factories.ts`](../src/core/factories.ts).
220
220
 
221
- | Factory | Kind | Signature | Summary |
221
+ | Name | Kind | Signature | Summary |
222
222
  | --------------------- | -------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
223
223
  | `createCSV` | function | `(input: string \| CSVTable, options?: ParseOptions) => CSVInterface` | Creates a working `CSVInterface` from a CSV string or an already-parsed `CSVTable`. |
224
224
  | `createTableContract` | function | `(columns: Columns) => ContractInterface<Row>` | Compiles a `Columns` map into a `ContractInterface` for a `Row` — a guard, coercing parser, JSON Schema, and seeded generator from one shape declaration. |