@orkestrel/scaffold 0.0.114 → 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.
- package/dist/bin/main.js +137 -15
- package/dist/bin/main.js.map +1 -1
- package/dist/host/agents/orchestration.md +5 -3
- package/dist/host/agents/platforms/windows.md +1 -0
- package/dist/host/agents/skills/orkestrel-align/references/integration.md +1 -1
- package/dist/host/agents/skills/orkestrel-debrief/SKILL.md +4 -4
- package/dist/host/agents/skills/orkestrel-dispatch/SKILL.md +4 -1
- package/dist/host/agents/skills/orkestrel-falsify/SKILL.md +8 -2
- package/dist/host/agents/skills/orkestrel-harden/references/equivalence.md +1 -0
- package/dist/host/agents/skills/orkestrel-harden/references/hardening.md +1 -1
- package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +1 -1
- package/dist/host/agents/skills/orkestrel-parallel/references/codex.md +1 -0
- package/dist/host/agents/skills/orkestrel-publish/references/wave.md +9 -3
- package/dist/host/claude/agents/analyst.md +1 -1
- package/dist/host/claude/agents/astra.md +2 -2
- package/dist/host/claude/agents/builder.md +4 -4
- package/dist/host/claude/agents/opus.md +3 -3
- package/dist/host/claude/agents/orkestrel.md +5 -7
- package/dist/host/claude/agents/planner.md +8 -2
- package/dist/host/claude/rules/campaign.md +2 -1
- package/dist/host/claude/rules/documentation.md +1 -0
- package/dist/host/claude/rules/names.md +3 -1
- package/dist/host/claude/rules/tests.md +7 -4
- package/dist/host/claude/rules/writing.md +1 -0
- package/dist/host/claude/skills/enterprise-bootstrap/SKILL.md +1 -2
- package/dist/host/claude/skills/orkestrel-align/SKILL.md +1 -1
- package/dist/host/claude/skills/orkestrel-build/SKILL.md +1 -2
- package/dist/host/claude/skills/orkestrel-debrief/SKILL.md +1 -2
- package/dist/host/claude/skills/orkestrel-dispatch/SKILL.md +1 -1
- package/dist/host/claude/skills/orkestrel-falsify/SKILL.md +1 -1
- package/dist/host/claude/skills/orkestrel-harden/SKILL.md +1 -1
- package/dist/host/claude/skills/orkestrel-journey/SKILL.md +1 -1
- package/dist/host/claude/skills/orkestrel-parallel/SKILL.md +1 -1
- package/dist/host/claude/skills/orkestrel-polish/SKILL.md +1 -2
- package/dist/host/claude/skills/orkestrel-publish/SKILL.md +1 -2
- package/dist/host/claude/skills/orkestrel-scout/SKILL.md +1 -1
- package/dist/host/codex/agents/analyst.toml +8 -5
- package/dist/host/codex/agents/astra.toml +4 -5
- package/dist/host/codex/agents/builder.toml +5 -5
- package/dist/host/codex/agents/opus.toml +3 -4
- package/dist/host/codex/agents/orkestrel.toml +2 -1
- package/dist/host/codex/agents/planner.toml +8 -5
- package/dist/host/codex/agents/reviewer.toml +5 -4
- 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 +361 -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 +554 -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 +93 -93
- package/dist/host/tests/setupPolicy.ts +5 -3
- package/dist/src/core/index.cjs +89 -3
- 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 +87 -4
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +292 -66
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +188 -6
- package/dist/src/server/index.d.ts +188 -6
- package/dist/src/server/index.js +287 -69
- package/dist/src/server/index.js.map +1 -1
- package/package.json +4 -3
|
@@ -50,11 +50,11 @@ Style is **data**: a `Style` is a frozen `{ foreground?, background?, attributes
|
|
|
50
50
|
|
|
51
51
|
The layout and browser scan expose these primitives:
|
|
52
52
|
|
|
53
|
-
|
|
|
54
|
-
| ---------------- | --------- |
|
|
55
|
-
| `renderBoxTop` | function | `(options: BoxOptions, span: number) => string`
|
|
56
|
-
| `LineIterator` | class | `IterableIterator<number>`
|
|
57
|
-
| `ConsoleSegment` | interface | `{ active, cursor, text, style }`
|
|
53
|
+
| Name | Kind | Signature | Summary |
|
|
54
|
+
| ---------------- | --------- | ------------------------------------------------- | -------------------------------------------------------------------------------------- |
|
|
55
|
+
| `renderBoxTop` | function | `(options: BoxOptions, span: number) => string` | Renders a box's top border across the supplied inner span. |
|
|
56
|
+
| `LineIterator` | class | `new (count: number) => IterableIterator<number>` | Yields a position for each requested blank line without allocating the whole sequence. |
|
|
57
|
+
| `ConsoleSegment` | interface | `{ active, cursor, text, style }` | Records the style and visible text at one ANSI scan boundary. |
|
|
58
58
|
|
|
59
59
|
The `isConsoleError` guard recognizes an own identity brand across package copies. It accepts
|
|
60
60
|
subclasses regardless of their `name`, and rejects transparent proxies and unbranded errors.
|
|
@@ -65,24 +65,24 @@ The style engine — text style as data, rendered by a swappable renderer (ANSI
|
|
|
65
65
|
|
|
66
66
|
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 `\|`. A function row's `Shape` cell holds its signature, and a guard row's the type it narrows to. A class row's `Shape` cell holds the interface it implements, or its constructor signature where it implements none.
|
|
67
67
|
|
|
68
|
-
|
|
|
69
|
-
| ------------------- | --------- |
|
|
70
|
-
| `Color` | type | `'black' \| 'red' \| 'green' \| 'yellow' \| 'blue' \| 'magenta' \| 'cyan' \| 'white' \| 'brightBlack' \| 'brightRed' \| 'brightGreen' \| 'brightYellow' \| 'brightBlue' \| 'brightMagenta' \| 'brightCyan' \| 'brightWhite' \| 'default'`
|
|
71
|
-
| `Attribute` | type | `'bold' \| 'dim' \| 'italic' \| 'underline' \| 'inverse' \| 'strikethrough'`
|
|
72
|
-
| `Style` | interface | `{ foreground?, background?, attributes }`
|
|
73
|
-
| `RendererInterface` | interface | `{
|
|
74
|
-
| `StylerOptions` | interface | `{ renderer?, enabled? }`
|
|
75
|
-
| `StylerInterface` | interface | `{ style, enabled, black, red, green, yellow, blue, magenta, cyan, white, brightBlack, brightRed, brightGreen, brightYellow, brightBlue, brightMagenta, brightCyan, brightWhite, bold, dim, italic, underline, inverse, strikethrough }
|
|
76
|
-
| `ThemeStatus` | interface | `{ icon, style }`
|
|
77
|
-
| `Theme` | interface | `{ levels, statuses, accent, chrome }`
|
|
78
|
-
| `ThemeOptions` | interface | `{ levels?, statuses?, accent?, chrome? }`
|
|
79
|
-
| `ANSIRenderer` | class | `RendererInterface`
|
|
80
|
-
| `createStyler` | function | `(options?: StylerOptions) => StylerInterface`
|
|
81
|
-
| `createTheme` | function | `(options?: ThemeOptions) => Theme`
|
|
82
|
-
| `freezeStyle` | function | `(style: Style) => Style`
|
|
83
|
-
| `strip` | function | `(text: string) => string`
|
|
84
|
-
| `stripControls` | function | `(text: string) => string`
|
|
85
|
-
| `width` | function | `(text: string) => number`
|
|
68
|
+
| Name | Kind | Signature | Summary |
|
|
69
|
+
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
70
|
+
| `Color` | type | `'black' \| 'red' \| 'green' \| 'yellow' \| 'blue' \| 'magenta' \| 'cyan' \| 'white' \| 'brightBlack' \| 'brightRed' \| 'brightGreen' \| 'brightYellow' \| 'brightBlue' \| 'brightMagenta' \| 'brightCyan' \| 'brightWhite' \| 'default'` | Names a terminal color — the 8 standard base colors, their 8 bright variants, and `default` (the target's own default ink, emitting no color code). |
|
|
71
|
+
| `Attribute` | type | `'bold' \| 'dim' \| 'italic' \| 'underline' \| 'inverse' \| 'strikethrough'` | Names a text-style attribute — `bold` / `dim` / `italic` / `underline` / `inverse` / `strikethrough`, the standard SGR text effects. |
|
|
72
|
+
| `Style` | interface | `{ foreground?, background?, attributes }` | Represents text style as data — a frozen, readonly record of a foreground color, a background color, and a set of text attributes. The single style value the whole console / terminal system shares; a `RendererInterface` renders it for one target. |
|
|
73
|
+
| `RendererInterface` | interface | `{ render() }` | Declares a swappable style renderer — the seam that turns style data into output for one target. The cross-environment default is the ANSI renderer (SGR escape codes); a browser `%c` / CSS renderer implements the same contract over the same `Style` model, so it drops in without touching the style data (the browser branch). |
|
|
74
|
+
| `StylerOptions` | interface | `{ renderer?, enabled? }` | Configures `createStyler` — `renderer` selects the output target, defaulting to the ANSI renderer, and `enabled` is the no-color switch, defaulting to `true`. |
|
|
75
|
+
| `StylerInterface` | interface | `{ (text: string): string, style, enabled, render(), black, red, green, yellow, blue, magenta, cyan, white, brightBlack, brightRed, brightGreen, brightYellow, brightBlue, brightMagenta, brightCyan, brightWhite, bold, dim, italic, underline, inverse, strikethrough }` | Declares the fluent, composable styling surface — the consumer-facing API. It is both a function (call it with text to render the accumulated style) and a record of chainable accessors: every `Color` and `Attribute` is a getter returning a new styler with that token added, so `styler.red.bold('hi')` and `styler.red(styler.bold('hi'))` both work and nothing is mutated. |
|
|
76
|
+
| `ThemeStatus` | interface | `{ icon, style }` | Represents one narrative outcome's presentation — the icon glyph a `StatusLevel` shows and the `Style` the line renders in. |
|
|
77
|
+
| `Theme` | interface | `{ levels, statuses, accent, chrome }` | Represents the app-wide semantic style vocabulary — each role bound to a `Style` value. Pass one theme to a logger / reporter / spinner / progress and every surface speaks it. |
|
|
78
|
+
| `ThemeOptions` | interface | `{ levels?, statuses?, accent?, chrome? }` | Holds the options for `createTheme` — the roles to override on `DEFAULT_THEME`, a status supplying its whole copied `{ icon, style }` record. |
|
|
79
|
+
| `ANSIRenderer` | class | `new () => RendererInterface` | Implements the cross-environment default `RendererInterface` — renders style data as ANSI SGR escape codes, stateless and event-free. |
|
|
80
|
+
| `createStyler` | function | `(options?: StylerOptions) => StylerInterface` | Creates the fluent, composable `StylerInterface` — ANSI by default, retargeted by a `renderer` and stripped of color by `enabled: false`. |
|
|
81
|
+
| `createTheme` | function | `(options?: ThemeOptions) => Theme` | Creates a `Theme` — the app-wide semantic style vocabulary, merged role by role over `DEFAULT_THEME`. Hand one theme to a logger / reporter / spinner / progress and every surface speaks it; omit `options` for the defaults. |
|
|
82
|
+
| `freezeStyle` | function | `(style: Style) => Style` | Snapshots and deeply freezes one `Style` value, including an independent frozen copy of its `attributes`. |
|
|
83
|
+
| `strip` | function | `(text: string) => string` | Removes every ANSI escape sequence from `text`, returning the plain visible string. |
|
|
84
|
+
| `stripControls` | function | `(text: string) => string` | Removes every non-printing C0 control character from `text` except `\t` / `\n` / `\r` (meaningful whitespace), plus DEL — a separate pass from `strip`, so `width` stays untouched. |
|
|
85
|
+
| `width` | function | `(text: string) => number` | Measures how many visible columns `text` occupies — its length after ANSI escapes are stripped, counted in Unicode code points (so an astral character such as an emoji counts as one, not the two UTF-16 units `String.length` would report). |
|
|
86
86
|
|
|
87
87
|
### Logging
|
|
88
88
|
|
|
@@ -90,22 +90,22 @@ Structured logging — the immutable `LogRecord` + the `entry` event are the tra
|
|
|
90
90
|
|
|
91
91
|
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 `\|`. A function row's `Shape` cell holds its signature, and a guard row's the type it narrows to. A class row's `Shape` cell holds the interface it implements, or its constructor signature where it implements none.
|
|
92
92
|
|
|
93
|
-
|
|
|
94
|
-
| ------------------------ | --------- |
|
|
95
|
-
| `LogLevel` | type | `'debug' \| 'info' \| 'warn' \| 'error'`
|
|
96
|
-
| `LogRecord` | interface | `{ level, message, time, name?, data? }`
|
|
97
|
-
| `SinkInterface` | interface | `{
|
|
98
|
-
| `WriterSet` | interface | `{ log, warn, error }`
|
|
99
|
-
| `selectWriter` | function | `<T>(level: LogLevel \| undefined, writers: WriterSet<T>) => T`
|
|
100
|
-
| `createConsoleSink` | function | `() => SinkInterface`
|
|
101
|
-
| `Logger` | class | `LoggerInterface`
|
|
102
|
-
| `LoggerManager` | class | `LoggerManagerInterface`
|
|
103
|
-
| `LoggerEventMap` | type | `{ entry }`
|
|
104
|
-
| `LogFormatFunction` | type | `(record: LogRecord, styler: StylerInterface, theme: Theme) => string`
|
|
105
|
-
| `LoggerOptions` | interface | `{ on?, error?, level?, name?, sink?, styler?, theme?, format?, limit?, silent? }`
|
|
106
|
-
| `LoggerInterface` | interface | `{ emitter, level, name
|
|
107
|
-
| `LoggerManagerOptions` | interface | `{ level?, sink?, styler?, theme?, format?, limit?, silent? }`
|
|
108
|
-
| `LoggerManagerInterface` | interface | `{ count
|
|
93
|
+
| Name | Kind | Signature | Summary |
|
|
94
|
+
| ------------------------ | --------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
95
|
+
| `LogLevel` | type | `'debug' \| 'info' \| 'warn' \| 'error'` | Names the severity level of a `LogRecord` — one coherent, ascending scale, `debug` < `info` < `warn` < `error`, that a `LoggerInterface` gates by threshold. |
|
|
96
|
+
| `LogRecord` | interface | `{ level, message, time, name?, data? }` | Represents one immutable, serializable log entry. A `LoggerInterface` builds one per call, freezes it, retains a bounded tail of them, and emits it on `entry`; every sink / transport consumes this exact shape. |
|
|
97
|
+
| `SinkInterface` | interface | `{ write() }` | Declares the minimal output primitive — the seam every formatted line is written through. A `Sink` is the one place text leaves the logging system; redirect output (to a file, a buffer, a test recorder, the browser `%c` path, a server TTY) by supplying a different `SinkInterface`, with no change to the logger. |
|
|
98
|
+
| `WriterSet` | interface | `{ log, warn, error }` | Groups the write targets a level-routing sink chooses between — each of the backend's own member type. |
|
|
99
|
+
| `selectWriter` | function | `<T>(level: LogLevel \| undefined, writers: WriterSet<T>) => T` | Selects the member of a `WriterSet` a `LogLevel` routes to — `error` to `error`, `warn` to `warn`, every other level and an omitted level to `log`. |
|
|
100
|
+
| `createConsoleSink` | function | `() => SinkInterface` | Creates the default `SinkInterface` — a console sink that routes by level and writes through the `console` methods snapshotted at creation. The default output target behind the `Logger`. |
|
|
101
|
+
| `Logger` | class | `new (options?: LoggerOptions) => LoggerInterface` | Implements an observable, leveled logger — the entry point into the structured-logging pipeline. Each `debug` / `info` / `warn` / `error` call builds a frozen `LogRecord`, gates it by severity, retains a bounded tail of accepted records, always emits it on `entry` (the transport seam), and — unless `silent` — formats it into a styled line and writes it to its `SinkInterface`. |
|
|
102
|
+
| `LoggerManager` | class | `new (options?: LoggerManagerOptions) => LoggerManagerInterface` | Implements an event-free registry of named `Logger`s plus a convenience fan-out — the manager over the logging layer (a registry, never observable itself; each `Logger` owns its own `emitter`). |
|
|
103
|
+
| `LoggerEventMap` | type | `{ readonly entry: readonly [record: LogRecord]; }` | Declares the observable events a `LoggerInterface` emits — `entry(record)` for every accepted record, the transport seam. |
|
|
104
|
+
| `LogFormatFunction` | type | `(record: LogRecord, styler: StylerInterface, theme: Theme) => string` | Represents the line layout a logger writes — `(record, styler, theme) => string`, one `LogRecord` plus the styling substrate in and one finished line out. `formatRecord` is the default. |
|
|
105
|
+
| `LoggerOptions` | interface | `{ on?, error?, level?, name?, sink?, styler?, theme?, format?, limit?, silent? }` | Configures the `Logger` constructor — the `on` / `error` emitter keys, the `level` threshold, the logger's `name`, the `sink` / `styler` / `theme` / `format` line substrate, the retention `limit`, and the `silent` write switch. |
|
|
106
|
+
| `LoggerInterface` | interface | `{ emitter, level, name?, debug(), info(), warn(), error(), entries(), clear(), destroy() }` | Declares an observable, leveled logger — builds a frozen `LogRecord` per call, gates it by severity, retains a bounded tail, emits it on `entry`, and (unless silent) writes a styled line to its `SinkInterface`. |
|
|
107
|
+
| `LoggerManagerOptions` | interface | `{ level?, sink?, styler?, theme?, format?, limit?, silent? }` | Configures the `LoggerManager` constructor — the `level` / `sink` / `styler` / `theme` / `format` / `limit` / `silent` defaults flowed into every logger it mints. |
|
|
108
|
+
| `LoggerManagerInterface` | interface | `{ count, register(), logger(), loggers(), debug(), info(), warn(), error(), remove() }` | Declares an event-free registry of named `LoggerInterface`s plus a convenience fan-out — the manager over the logging layer. It mints + stores loggers keyed by `name`, looks them up, removes them, and broadcasts a one-off log to every registered logger. |
|
|
109
109
|
|
|
110
110
|
### Reporting
|
|
111
111
|
|
|
@@ -113,7 +113,7 @@ Narrative reporting — pure width-aware layout renderers + a lean `Reporter` fr
|
|
|
113
113
|
|
|
114
114
|
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 `\|`. A function row's `Shape` cell holds its signature, and a guard row's the type it narrows to. A class row's `Shape` cell holds the interface it implements, or its constructor signature where it implements none.
|
|
115
115
|
|
|
116
|
-
|
|
|
116
|
+
| Name | Kind | Signature | Summary |
|
|
117
117
|
| -------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
118
118
|
| `Alignment` | type | `'left' \| 'center' \| 'right'` | Names the horizontal text alignment within a fixed-width cell — `left` / `center` / `right`, the conventional set a `ColumnSpec` (and the box / separator title) aligns by. |
|
|
119
119
|
| `BorderStyle` | type | `'single' \| 'double' \| 'round' \| 'heavy'` | Names a box-drawing border style — `single` / `double` / `round` / `heavy`, the standard Unicode line weights the renderers frame with, each selecting a full junction set in `BORDER_CHARS`. |
|
|
@@ -127,8 +127,8 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?` ma
|
|
|
127
127
|
| `StatusLevel` | type | `'success' \| 'error' \| 'warn' \| 'info'` | Names a narrative outcome level — `success` / `error` / `warn` / `info`, the states `ReporterInterface.status` reports, each with its own icon + color (`STATUS_ICONS` / `STATUS_COLORS`). |
|
|
128
128
|
| `StepPosition` | interface | `{ index, total }` | Represents where one step sits in a sequence — what `ReporterInterface.step` renders as a `[2/5]` prefix. |
|
|
129
129
|
| `ReporterOptions` | interface | `{ sink?, styler?, theme?, width? }` | Configures the `Reporter` constructor — the `sink` every line is written to, the `styler` and `theme` it formats through, and the `width` its layouts measure against. |
|
|
130
|
-
| `ReporterInterface` | interface | `{
|
|
131
|
-
| `Reporter` | class | `ReporterInterface`
|
|
130
|
+
| `ReporterInterface` | interface | `{ section(), step(), timing(), status(), table(), tree(), box(), line(), blank() }` | Declares a lean, event-free narrative reporter — the composable verb set for human / build-run output (sections, steps, timings, outcomes, tables, trees, boxes), formatting through the shared `StylerInterface` + layout renderers and writing to a `SinkInterface`. |
|
|
131
|
+
| `Reporter` | class | `new (options?: ReporterOptions) => ReporterInterface` | Implements a lean, event-free narrative reporter — the composable verb set for human / build-run output. Each verb formats its line through the shared `StylerInterface` and the pure layout renderers (`renderSeparator` / `renderBox` / `renderTable` / `renderTree`) and writes it to a `SinkInterface` — the same styler + sink substrate the logger uses, never a second colorizer. |
|
|
132
132
|
| `renderSeparator` | function | `(options: SeparatorOptions) => string` | Renders a horizontal rule — an optional centered title embedded in a line of fill characters, to a fixed visible width. Pure: same `SeparatorOptions` → same string. |
|
|
133
133
|
| `renderBox` | function | `(options: BoxOptions) => string` | Renders `content` framed in box-drawing characters, optionally captioned, width-aware so styled content stays aligned inside the frame. Pure: same `BoxOptions` → same string. |
|
|
134
134
|
| `renderTable` | function | `(options: TableOptions) => string` | Renders a bordered grid of `columns` + `rows` with per-column alignment and width-aware column sizing. Pure: same `TableOptions` → same string. |
|
|
@@ -152,19 +152,19 @@ Console interception — take control of `console.*` on the read side; a buffere
|
|
|
152
152
|
|
|
153
153
|
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 `\|`. A function row's `Shape` cell holds its signature, and a guard row's the type it narrows to. A class row's `Shape` cell holds the interface it implements, or its constructor signature where it implements none.
|
|
154
154
|
|
|
155
|
-
|
|
|
156
|
-
| --------------------- | --------- |
|
|
157
|
-
| `CaptureLevel` | type | `'log' \| 'info' \| 'warn' \| 'error' \| 'debug'`
|
|
158
|
-
| `ConsoleMethod` | type | `(...args: unknown[]) => void`
|
|
159
|
-
| `CapturedMessage` | interface | `{ level, text, time }`
|
|
160
|
-
| `CaptureEventMap` | type | `{ capture
|
|
161
|
-
| `CaptureOptions` | interface | `{ on?, error?, levels?, mirror?, sink?, limit? }`
|
|
162
|
-
| `CaptureInterface` | interface | `{ emitter, active
|
|
163
|
-
| `CaptureResult` | interface | `{ value, messages }`
|
|
164
|
-
| `RetentionInterface` | interface | `{
|
|
165
|
-
| `Retention` | class | `RetentionInterface
|
|
166
|
-
| `Capture` | class | `CaptureInterface`
|
|
167
|
-
| `createCaptureResult` | function |
|
|
155
|
+
| Name | Kind | Signature | Summary |
|
|
156
|
+
| --------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
157
|
+
| `CaptureLevel` | type | `'log' \| 'info' \| 'warn' \| 'error' \| 'debug'` | Identifies one intercepted `console` method — `log` / `info` / `warn` / `error` / `debug`, the names a `CaptureInterface` patches and reports under. |
|
|
158
|
+
| `ConsoleMethod` | type | `(...args: unknown[]) => void` | Names the console-method shape a `CaptureInterface` snapshots and swaps at the patch boundary — a variadic sink of arbitrary arguments. |
|
|
159
|
+
| `CapturedMessage` | interface | `{ level, text, time }` | Represents one captured console call — an immutable, serializable record of a single intercepted `console.*` invocation. A `CaptureInterface` builds one per call, freezes it, buffers it (total + by level), and emits it on `capture`; every consumer reads this exact shape. |
|
|
160
|
+
| `CaptureEventMap` | type | `{ readonly capture: readonly [message: CapturedMessage]; readonly start: readonly []; readonly stop: readonly []; }` | Declares the observable events a `CaptureInterface` emits — `capture(message)` per intercepted call, plus the `start` and `stop` lifecycle signals. |
|
|
161
|
+
| `CaptureOptions` | interface | `{ on?, error?, levels?, mirror?, sink?, limit? }` | Configures the `Capture` constructor — the `on` / `error` emitter keys, the `levels` intercepted, the `mirror` pass-through, the `sink` forward, and the buffer `limit`. |
|
|
162
|
+
| `CaptureInterface` | interface | `{ emitter, active, start(), stop(), messages(), clear(), destroy() }` | Declares an observable console interceptor — it takes control of the global `console.*` on the read side: while `active`, every configured `console.x` call is captured as a frozen `CapturedMessage`, buffered (total + by level, bounded), emitted on `capture`, and — per options — mirrored to the real console, forwarded to a `SinkInterface`, or both. |
|
|
163
|
+
| `CaptureResult` | interface | `{ value, messages }` | Represents the structured outcome of `createCaptureResult` — the wrapped function's own return `value` plus the `messages` it logged while it ran. |
|
|
164
|
+
| `RetentionInterface` | interface | `{ add(), records(), clear() }` | Declares the bounded, level-keyed retention buffer a capture keeps its records in — one capped total buffer plus one capped bucket per level configured at construction. |
|
|
165
|
+
| `Retention` | class | `new <T extends { readonly level: string; }>(levels: ReadonlyArray<T['level']>, limit: number) => RetentionInterface<T>` | Implements the bounded, level-keyed retention engine the console and process captures buffer through — one capped total buffer plus one capped bucket per level, generic over the record type each capture carries. |
|
|
166
|
+
| `Capture` | class | `new (options?: CaptureOptions) => CaptureInterface` | Implements an observable console interceptor — it takes control of the global `console.*` on the read side. While `active`, every configured `console.x` call is captured as a frozen `CapturedMessage`, buffered (total + by level, bounded), emitted on `capture`, and — per options — mirrored to the real console, forwarded to a `SinkInterface`, or both. |
|
|
167
|
+
| `createCaptureResult` | function | `(<T>(fn: () => Promise<T>, options?: CaptureOptions) => Promise<CaptureResult<T>>) & (<T>(fn: () => T, options?: CaptureOptions) => CaptureResult<T>)` | Runs `fn` with the global `console.*` captured for its duration, returning the function's `value` plus the `CapturedMessage`s it logged — the scoped, self-restoring ergonomic form of the `Capture` class. |
|
|
168
168
|
|
|
169
169
|
### Errors
|
|
170
170
|
|
|
@@ -172,11 +172,11 @@ The one error type the console layer throws — an internal invariant or unreach
|
|
|
172
172
|
|
|
173
173
|
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 `\|`. A function row's `Shape` cell holds its signature, and a guard row's the type it narrows to. A class row's `Shape` cell holds the interface it implements, or its constructor signature where it implements none.
|
|
174
174
|
|
|
175
|
-
|
|
|
175
|
+
| Name | Kind | Signature | Summary |
|
|
176
176
|
| ------------------ | -------- | ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
177
177
|
| `ConsoleErrorCode` | type | `'INVARIANT'` | Names the machine-readable error code a `ConsoleError` carries — `INVARIANT`, the only code the package throws. |
|
|
178
178
|
| `ConsoleError` | class | `new (code: ConsoleErrorCode, message: string, context?: Readonly<Record<string, unknown>>) => ConsoleError` | Carries a `ConsoleErrorCode` and an optional `context` bag — the error the console layer throws for an internal invariant violated at a defensive guard. |
|
|
179
|
-
| `isConsoleError` | function | `ConsoleError`
|
|
179
|
+
| `isConsoleError` | function | `(value: unknown) => value is ConsoleError` | Narrows an unknown caught value to a `ConsoleError` — the guard a `catch` branches on. |
|
|
180
180
|
|
|
181
181
|
### Animations
|
|
182
182
|
|
|
@@ -184,18 +184,18 @@ Live activity animations — pure frame producers over the same styler and sink
|
|
|
184
184
|
|
|
185
185
|
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 `\|`. A class row's `Shape` cell holds the interface it implements, or its constructor signature where it implements none.
|
|
186
186
|
|
|
187
|
-
|
|
|
188
|
-
| ------------------- | --------- |
|
|
189
|
-
| `BarOptions` | interface | `{ current, total, width?, fill?, empty?, styler?, style? }`
|
|
190
|
-
| `SpinnerEventMap` | type | `{ frame
|
|
191
|
-
| `SpinnerOptions` | interface | `{ on?, error?, message?, frames?, interval?, sink?, styler?, theme? }`
|
|
192
|
-
| `SpinnerInterface` | interface | `{ emitter, active, message
|
|
193
|
-
| `Spinner` | class | `SpinnerInterface`
|
|
194
|
-
| `ProgressReport` | interface | `{ current, total }`
|
|
195
|
-
| `ProgressEventMap` | type | `{ update
|
|
196
|
-
| `ProgressOptions` | interface | `{ on?, error?, total, message?, width?, fill?, empty?, sink?, styler?, theme? }`
|
|
197
|
-
| `ProgressInterface` | interface | `{ emitter, active, succeeded, current, total
|
|
198
|
-
| `Progress` | class | `ProgressInterface`
|
|
187
|
+
| Name | Kind | Signature | Summary |
|
|
188
|
+
| ------------------- | --------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
189
|
+
| `BarOptions` | interface | `{ current, total, width?, fill?, empty?, styler?, style? }` | Configures the pure `renderBar` renderer — a determinate progress bar string (`█████░░░░░ 50% (5/10)`), width-aware and styler-optional. |
|
|
190
|
+
| `SpinnerEventMap` | type | `{ readonly frame: readonly [line: string]; readonly start: readonly []; readonly stop: readonly []; }` | Declares the observable events a `SpinnerInterface` emits — `frame(line)` per advance and per outcome, plus the `start` and `stop` timer-lifecycle signals. |
|
|
191
|
+
| `SpinnerOptions` | interface | `{ on?, error?, message?, frames?, interval?, sink?, styler?, theme? }` | Configures the `Spinner` constructor — the `on` / `error` emitter keys, the `message` shown, the glyph `frames` and their `interval`, and the `sink` / `styler` / `theme` line substrate. |
|
|
192
|
+
| `SpinnerInterface` | interface | `{ emitter, active, message, start(), tick(), update(), succeed(), fail(), stop(), destroy() }` | Declares a self-driving, observable activity spinner — a glyph cycle that advances on a periodic timer, writing each `\r` + frame line to its `SinkInterface` and emitting it on `frame`. The line-overwrite is the sink's job (a TTY sink overwrites on the `\r`; a plain sink degrades to a fresh line). |
|
|
193
|
+
| `Spinner` | class | `new (options?: SpinnerOptions) => SpinnerInterface` | Implements a self-driving, observable activity spinner — a glyph cycle that advances on a periodic timer, writing each `\r` + frame line to its `SinkInterface` and emitting it on `frame`. The timer is always cleared on an outcome, so the spinner is leak-free. |
|
|
194
|
+
| `ProgressReport` | interface | `{ current, total }` | Reports one advance of a `ProgressInterface` — the clamped payload carried by the `update` event of `ProgressEventMap`. |
|
|
195
|
+
| `ProgressEventMap` | type | `{ readonly update: readonly [progress: ProgressReport]; readonly succeed: readonly []; }` | Declares the observable events a `ProgressInterface` emits — `update(progress)` per report, plus a `succeed` signal on a successful finish. |
|
|
196
|
+
| `ProgressOptions` | interface | `{ on?, error?, total, message?, width?, fill?, empty?, sink?, styler?, theme? }` | Configures the `Progress` constructor — the `on` / `error` emitter keys, the required `total`, the `message` shown, the bar's `width` / `fill` / `empty` glyphs, and the `sink` / `styler` / `theme` line substrate. |
|
|
197
|
+
| `ProgressInterface` | interface | `{ emitter, active, succeeded, current, total, update(), succeed(), fail(), destroy() }` | Declares an update-driven, observable progress bar — `update(current)` recomputes the bar through `renderBar`, writes `\r` + bar to its `SinkInterface`, and emits the `{ current, total }` on `update`. The line-overwrite is the sink's job (a TTY sink overwrites on the `\r`; a plain sink degrades to a fresh line). No self-timer — the caller drives it. |
|
|
198
|
+
| `Progress` | class | `new (options: ProgressOptions) => ProgressInterface` | Implements an update-driven, observable progress bar — `update` recomputes the bar through `renderBar`, writes `\r` + bar to its `SinkInterface`, and emits the `{ current, total }` on `update`. No self-timer, unlike `Spinner` — the caller drives it. |
|
|
199
199
|
|
|
200
200
|
### Style constants
|
|
201
201
|
|
|
@@ -203,7 +203,7 @@ The SGR code data the ANSI renderer maps through, and the styler's color / attri
|
|
|
203
203
|
|
|
204
204
|
A `Shape` cell holds the constant's declared type.
|
|
205
205
|
|
|
206
|
-
|
|
|
206
|
+
| Name | Kind | Signature | Summary |
|
|
207
207
|
| ------------------ | ----- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
208
208
|
| `FOREGROUND_CODES` | const | `Readonly<Record<Exclude<Color, 'default'>, number>>` | Maps each `Color` to its SGR foreground parameter — the 8 base colors at 30–37 and their bright variants at 90–97. `default` is intentionally absent (it emits no code). |
|
|
209
209
|
| `BACKGROUND_CODES` | const | `Readonly<Record<Exclude<Color, 'default'>, number>>` | Maps each `Color` to its SGR background parameter — the 8 base colors at 40–47 and their bright variants at 100–107. `default` is intentionally absent (it emits no code). |
|
|
@@ -212,7 +212,7 @@ A `Shape` cell holds the constant's declared type.
|
|
|
212
212
|
| `DEFAULT_THEME` | const | `Theme` | Holds the default `Theme` — every role bound to its default `Style`, assembled from `LEVEL_COLORS`, `STATUS_ICONS`, and `STATUS_COLORS` and deeply frozen. |
|
|
213
213
|
| `COLORS` | const | `ReadonlyArray<Exclude<Color, 'default'>>` | Lists every named `Color` except `default`, frozen — the colors the styler exposes as chainable accessors. The source of truth for the color axis; the styler drives its accessors from this array so the literals live in one place. |
|
|
214
214
|
| `ATTRIBUTES` | const | `readonly Attribute[]` | Lists every `Attribute`, frozen — the attributes the styler exposes as chainable accessors. The source of truth for the attribute axis. |
|
|
215
|
-
| `RESET_CODE` | const | `
|
|
215
|
+
| `RESET_CODE` | const | `0` | Holds the SGR RESET parameter (0) — terminates a styled run, clearing all colors and attributes. |
|
|
216
216
|
| `ESC` | const | `string` | Holds the escape control character (`U+001B`) that begins every ANSI escape sequence. Built with `String.fromCharCode` so no raw control character appears in source. |
|
|
217
217
|
| `BEL` | const | `string` | Holds the bell control character (`U+0007`) that can terminate an OSC sequence. |
|
|
218
218
|
| `CSI` | const | `string` | Holds the Control Sequence Introducer (`ESC[`) that opens every SGR sequence. |
|
|
@@ -226,24 +226,24 @@ The level order + label colors, the box-drawing junction sets, status icons / co
|
|
|
226
226
|
|
|
227
227
|
A `Shape` cell holds the constant's declared type.
|
|
228
228
|
|
|
229
|
-
|
|
|
229
|
+
| Name | Kind | Signature | Summary |
|
|
230
230
|
| --------------------- | ----- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
231
231
|
| `LEVEL_SEVERITY` | const | `Readonly<Record<LogLevel, number>>` | Maps each `LogLevel` to its numeric severity — the ascending order the level gate compares through (`debug` 0 < `info` 1 < `warn` 2 < `error` 3). A record is kept when its level's severity is at or above the logger's threshold. The source of truth for level ordering. |
|
|
232
232
|
| `LEVEL_COLORS` | const | `Readonly<Record<LogLevel, Exclude<Color, 'default'>>>` | Maps each `LogLevel` to its default label `Color` — the level's visual treatment, which is a styling choice orthogonal to the level itself (never a separate pseudo-level). The logger colors the level label through its styler with these; swapping a color never changes leveling. `debug` is cyan, `info` blue, `warn` yellow, `error` red. |
|
|
233
|
-
| `DEFAULT_LOG_LIMIT` | const | `
|
|
233
|
+
| `DEFAULT_LOG_LIMIT` | const | `1000` | Sets the default bounded-retention cap for a `LoggerInterface` — `1000`, so at most that many recent records are kept and retention is always bounded. |
|
|
234
234
|
| `DEFAULT_LOG_LEVEL` | const | `LogLevel` | Sets the default `LogLevel` threshold a logger gates at when none is supplied — `info`. |
|
|
235
235
|
| `LOG_LEVELS` | const | `readonly LogLevel[]` | Lists every `LogLevel`, in ascending severity order — the levels a logger exposes as methods and the manager fans out to. The source of truth for the level axis (drives exhaustive tests); aligned with `LEVEL_SEVERITY`. |
|
|
236
236
|
| `BORDER_CHARS` | const | `Readonly<Record<BorderStyle, BorderChars>>` | Holds the complete `BorderChars` junction set for each `BorderStyle` — the standard Unicode box-drawing glyphs at each line weight, deeply frozen. |
|
|
237
237
|
| `STATUS_ICONS` | const | `Readonly<Record<StatusLevel, string>>` | Maps each `StatusLevel` to its icon glyph — the leading mark a `ReporterInterface.status` outcome line shows: `success` ✔, `error` ✖, `warn` ⚠, `info` ℹ. The narrative-outcome counterpart to a log level's label; frozen. |
|
|
238
238
|
| `STATUS_COLORS` | const | `Readonly<Record<StatusLevel, Exclude<Color, 'default'>>>` | Maps each `StatusLevel` to its `Color` — the icon + message color a `status` line renders in (`success` green, `error` red, `warn` yellow, `info` blue). The visual treatment of a narrative outcome, colored through the reporter's styler; orthogonal to leveling, like `LEVEL_COLORS`. Excludes `default` so each value indexes a real styler accessor. |
|
|
239
239
|
| `STATUS_LEVELS` | const | `readonly StatusLevel[]` | Lists every `StatusLevel`, frozen — the outcomes a `status` line supports (drives exhaustive tests). The source of truth for the status axis; aligned with `STATUS_ICONS` / `STATUS_COLORS`. |
|
|
240
|
-
| `DEFAULT_WIDTH` | const | `
|
|
241
|
-
| `DEFAULT_PADDING` | const | `
|
|
240
|
+
| `DEFAULT_WIDTH` | const | `80` | Sets the default visible column width for the width-aware renderers — the separator rule and a `renderBox` with no explicit `width`, and the reporter's `section` rule. A sane terminal default (80 columns); a caller overrides it per-call or through `ReporterOptions.width`. |
|
|
241
|
+
| `DEFAULT_PADDING` | const | `1` | Sets the default horizontal padding inside a box's edges (`renderBox`) — one cell. |
|
|
242
242
|
| `DEFAULT_BORDER` | const | `BorderStyle` | Sets the default `BorderStyle` the box / table renderers frame with when none is given — `single`. |
|
|
243
243
|
| `DEFAULT_ALIGN` | const | `Alignment` | Sets the default cell `Alignment` a `ColumnSpec` uses when none is given — `left`. |
|
|
244
|
-
| `SEPARATOR_FILL` | const | `
|
|
245
|
-
| `SEPARATOR_TITLE_GAP` | const | `
|
|
246
|
-
| `SECOND_MS` | const | `
|
|
244
|
+
| `SEPARATOR_FILL` | const | `"\u2500"` | Holds the default fill character `renderSeparator` draws its rule with — `─`. |
|
|
245
|
+
| `SEPARATOR_TITLE_GAP` | const | `" "` | Holds the single padding cell on each side of a separator's embedded title (`title`) — keeps the title from butting against the rule. One space. |
|
|
246
|
+
| `SECOND_MS` | const | `1000` | Sets the millisecond threshold at or above which `formatDuration` (and so `Reporter.timing`) switches from a `…ms` rendering to a `…s` (seconds, 2 d.p.) rendering — `1000`, exactly one second. |
|
|
247
247
|
|
|
248
248
|
### Capture & animation constants
|
|
249
249
|
|
|
@@ -251,16 +251,16 @@ The intercepted-method set, the bounded-buffer cap, the level projection, and th
|
|
|
251
251
|
|
|
252
252
|
A `Shape` cell holds the constant's declared type.
|
|
253
253
|
|
|
254
|
-
|
|
|
254
|
+
| Name | Kind | Signature | Summary |
|
|
255
255
|
| -------------------------- | ----- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
256
256
|
| `CAPTURE_LEVELS` | const | `readonly CaptureLevel[]` | Lists every `CaptureLevel`, frozen — the `console.*` methods a `CaptureInterface` intercepts by default (and the source of truth for the capture-level axis; drives exhaustive tests). The universal console methods: `log`, `info`, `warn`, `error`, `debug`. |
|
|
257
|
-
| `DEFAULT_CAPTURE_LIMIT` | const | `
|
|
257
|
+
| `DEFAULT_CAPTURE_LIMIT` | const | `1000` | Sets the default bounded-buffer cap for a `CaptureInterface` — `1000`, so at most that many recent `CapturedMessage`s are retained per buffer (the total buffer and each by-level bucket; oldest dropped first) and retention is always bounded. |
|
|
258
258
|
| `CAPTURE_LEVEL_MAP` | const | `Readonly<Record<CaptureLevel, LogLevel>>` | Maps each `CaptureLevel` to its `LogLevel` for the optional sink forward — the projection the Capture routes through when writing an intercepted call to a `SinkInterface`. `sink.write(text, CAPTURE_LEVEL_MAP[level])` is the call this map backs. `warn` / `error` / `debug` / `info` map to their matching `LogLevel`; `log` maps to `info` (a plain console log is informational — the default stream), so a stream-aware sink routes `warn` / `error` captures to the right stream. The source of truth for the capture-to-log projection. |
|
|
259
259
|
| `SPINNER_FRAMES` | const | `readonly string[]` | Holds the default spinner frame cycle a `SpinnerInterface` advances through — the braille-pattern glyphs (`⠋⠙⠹…`, the U+2800 block) that read as a smoothly rotating dot. |
|
|
260
|
-
| `DEFAULT_SPINNER_INTERVAL` | const | `
|
|
261
|
-
| `BAR_FILL` | const | `
|
|
262
|
-
| `BAR_EMPTY` | const | `
|
|
263
|
-
| `DEFAULT_BAR_WIDTH` | const | `
|
|
260
|
+
| `DEFAULT_SPINNER_INTERVAL` | const | `80` | Sets the default timer period between a `SpinnerInterface`'s frames — the `setInterval` interval `start()` arms, `80` ms (≈12.5 frames/second). |
|
|
261
|
+
| `BAR_FILL` | const | `"\u2588"` | Holds the default filled-cell glyph `renderBar` draws the completed run of a progress bar with — the full block `█` (U+2588). A single visible cell; a consumer overrides it through `BarOptions.fill`. |
|
|
262
|
+
| `BAR_EMPTY` | const | `"\u2591"` | Holds the default empty-cell glyph `renderBar` draws the remaining run of a progress bar with — the light-shade block `░` (U+2591). A single visible cell; a consumer overrides it through `BarOptions.empty`. |
|
|
263
|
+
| `DEFAULT_BAR_WIDTH` | const | `30` | Sets the default visible cell count of a progress-bar track — the glyph run `renderBar` fills, and the width a `ProgressInterface` sizes its bar to. `30` cells. |
|
|
264
264
|
|
|
265
265
|
### Browser sink
|
|
266
266
|
|
|
@@ -268,7 +268,7 @@ The browser `%c` console sink — translates the core's ANSI output into a `cons
|
|
|
268
268
|
|
|
269
269
|
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 `\|`. A function row's `Shape` cell holds its signature, and a guard row's the type it narrows to.
|
|
270
270
|
|
|
271
|
-
|
|
|
271
|
+
| Name | Kind | Signature | Summary |
|
|
272
272
|
| -------------------- | --------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
273
273
|
| `BrowserPalette` | interface | `{ color?, attribute? }` | Holds partial browser CSS overrides for the core color and attribute axes — a named `color` or `attribute` entry replaces only that entry, and every omission keeps its default. |
|
|
274
274
|
| `BrowserSinkOptions` | interface | `{ palette? }` | Configures `createBrowserSink` — the optional `palette` partially overriding the browser's named color and attribute CSS mappings. |
|
|
@@ -285,11 +285,11 @@ The SGR → CSS translation data the browser sink maps ANSI runs through (`src/b
|
|
|
285
285
|
|
|
286
286
|
A `Shape` cell holds the constant's declared type.
|
|
287
287
|
|
|
288
|
-
|
|
|
288
|
+
| Name | Kind | Signature | Summary |
|
|
289
289
|
| --------------- | ----- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
290
290
|
| `COLOR_HEX` | const | `Readonly<Record<Exclude<Color, 'default'>, string>>` | Maps each named `Color` to its hex value — the 16 standard terminal colors a browser DevTools console renders the same `Color` names as. The source of truth for the browser color axis: the ANSI renderer maps a `Color` name to an SGR number, and this maps the same name to the CSS color the `%c` sink paints with, so a browser shows the same 16 colors a terminal does. |
|
|
291
291
|
| `ATTRIBUTE_CSS` | const | `Readonly<Record<number, string>>` | Maps each text-`Attribute`'s SGR "on" number to its equivalent CSS declaration — the browser counterpart to the terminal's SGR text effects (`bold` 1 → `font-weight:bold`, `dim` 2 → `opacity:0.6`, `italic` 3 → `font-style:italic`, `underline` 4 → `text-decoration:underline`, `inverse` 7 → best-effort, `strikethrough` 9 → `text-decoration:line-through`). |
|
|
292
|
-
| `DIRECTIVE` | const | `
|
|
292
|
+
| `DIRECTIVE` | const | `"%c"` | Names the browser console directive that switches the active style — one `%c` prefixes every styled run in the `ConsoleOutput` format string, consuming the next entry of the parallel CSS array. The single source of truth for the directive token. |
|
|
293
293
|
| `SGR_PATTERN` | const | `RegExp` | Matches one SGR sequence (`ESC[ <params> m`) and captures its `;`-separated numeric parameters — the subset of ANSI `strip` cares about that carries style (color / attribute / reset), as opposed to cursor / erase / OSC sequences. Global, so the scanner walks every SGR run in a string; built from core's `ESC` so no control-character literal appears in source (the codebase idiom). The capture group is the parameter list (`''` for a bare `ESC[m`, which the spec treats as a reset). |
|
|
294
294
|
|
|
295
295
|
### Server sink + process capture
|
|
@@ -298,25 +298,25 @@ The server output backend — a TTY-aware `Sink` over the real `process` streams
|
|
|
298
298
|
|
|
299
299
|
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 `\|`. An extended interface's name comes before `plus`, with the members it adds after. A function row's `Shape` cell holds its signature, and a guard row's the type it narrows to. A class row's `Shape` cell holds the interface it implements, or its constructor signature where it implements none.
|
|
300
300
|
|
|
301
|
-
|
|
|
302
|
-
| ------------------------- | --------- |
|
|
303
|
-
| `StreamTargetInterface` | interface | `{ isTTY?, columns? }
|
|
304
|
-
| `ServerSinkOptions` | interface | `{ stdout?, stderr?, styled?, environment?, columns? }`
|
|
305
|
-
| `ServerSinkInterface` | interface | `
|
|
306
|
-
| `StreamLevel` | type | `'stdout' \| 'stderr'`
|
|
307
|
-
| `StreamWriteFunction` | type | `NodeJS.WriteStream['write']`
|
|
308
|
-
| `StreamWriteCallback` | type | `(error?: Error \| null) => void`
|
|
309
|
-
| `CapturedChunk` | interface | `{ level, text, time }`
|
|
310
|
-
| `ProcessCaptureEventMap` | type | `{ capture
|
|
311
|
-
| `ProcessCaptureOptions` | interface | `{ on?, error?, levels?, mirror?, sink?, limit? }`
|
|
312
|
-
| `ProcessCaptureInterface` | interface | `{ emitter, active
|
|
313
|
-
| `ProcessCapture` | class | `ProcessCaptureInterface`
|
|
314
|
-
| `createServerSink` | function | `(options?: ServerSinkOptions) => ServerSinkInterface`
|
|
315
|
-
| `isStreamTarget` | function | `StreamTargetInterface`
|
|
316
|
-
| `inferColumns` | function | `(target: StreamTargetInterface) => number`
|
|
317
|
-
| `inferStyled` | function | `(target: StreamTargetInterface, environment: Readonly<Record<string, string \| undefined>>) => boolean`
|
|
318
|
-
| `decodeChunk` | function | `(chunk: unknown, encoding?: unknown) => string`
|
|
319
|
-
| `isBufferEncoding` | function | `BufferEncoding`
|
|
301
|
+
| Name | Kind | Signature | Summary |
|
|
302
|
+
| ------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
303
|
+
| `StreamTargetInterface` | interface | `{ write(), isTTY?, columns? }` | Declares the minimal writable-stream shape the server sink and process capture address — exactly the slice of a Node `tty.WriteStream` / `process.stdout` they touch and no more. |
|
|
304
|
+
| `ServerSinkOptions` | interface | `{ stdout?, stderr?, styled?, environment?, columns? }` | Holds the options for `createServerSink` — the `stdout` and `stderr` targets, the `styled` override, the `environment` inference reads, and an explicit `columns` width. All are optional, so a bare `createServerSink()` writes to the real process streams. |
|
|
305
|
+
| `ServerSinkInterface` | interface | `{ styled, columns }` | Declares a `SinkInterface` that also exposes the `stdout` target's construction-time `styled` fact and the terminal's live or fixed `columns` width — the shape `createServerSink` returns. |
|
|
306
|
+
| `StreamLevel` | type | `'stdout' \| 'stderr'` | Names which process stream a `CapturedChunk` came from — `stdout` or `stderr`, the "level" axis of the process-stream `ProcessCaptureInterface` and the server analogue of the core `Capture`'s `CaptureLevel`. |
|
|
307
|
+
| `StreamWriteFunction` | type | `NodeJS.WriteStream['write']` | Names the process-stream `write` method a `ProcessCaptureInterface` snapshots and swaps at the patch boundary — `NodeJS.WriteStream['write']` verbatim, the write-side analogue of `ConsoleMethod`. |
|
|
308
|
+
| `StreamWriteCallback` | type | `(error?: Error \| null) => void` | Names the completion callback `process.*.write` accepts as its last argument — `(error?) => void`, the Node `write` callback shape and the `StreamWriteFunction` companion. |
|
|
309
|
+
| `CapturedChunk` | interface | `{ level, text, time }` | Represents one intercepted process-stream write — the immutable, serializable record a `ProcessCaptureInterface` buffers and emits, the server analogue of the core `CapturedMessage`. |
|
|
310
|
+
| `ProcessCaptureEventMap` | type | `{ readonly capture: readonly [chunk: CapturedChunk]; readonly start: readonly []; readonly stop: readonly []; }` | Declares the observable events a `ProcessCaptureInterface` emits — `capture(chunk)` per intercepted write, plus the `start` and `stop` signals. |
|
|
311
|
+
| `ProcessCaptureOptions` | interface | `{ on?, error?, levels?, mirror?, sink?, limit? }` | Holds the options for the `ProcessCapture` constructor — the `on` / `error` emitter keys, the `levels` intercepted, the `mirror` pass-through, the `sink` forward, and the buffer `limit`. Every field is optional, so a bare `new ProcessCapture()` buffers both streams without mirroring or forwarding. |
|
|
312
|
+
| `ProcessCaptureInterface` | interface | `{ emitter, active, start(), stop(), messages(), clear(), destroy() }` | Declares an observable interceptor of the raw process output streams — the server's "own all output" capture, patching `process.stdout.write` / `process.stderr.write` on the low-level stream where the core `Capture` patches `console.*`. |
|
|
313
|
+
| `ProcessCapture` | class | `new (options?: ProcessCaptureOptions) => ProcessCaptureInterface` | Implements an observable interceptor of the raw process output streams — it takes control of `process.stdout.write` / `process.stderr.write` on the write side. While `active`, every write to a configured `StreamLevel` is captured as a frozen `CapturedChunk`, buffered (total + per-stream, bounded), emitted on `capture`, and — per options — mirrored to the real stream, forwarded to a `SinkInterface`, or both. |
|
|
314
|
+
| `createServerSink` | function | `(options?: ServerSinkOptions) => ServerSinkInterface` | Creates the server TTY `ServerSinkInterface` — the server output backend, whose `write(text, level?)` routes by level to the process streams and uses construction-time styled facts: it sends ANSI straight to a styled target (with a leading `\r` overwriting a terminal line natively) but `strip`s ANSI to clean text for a plain target. |
|
|
315
|
+
| `isStreamTarget` | function | `(value: unknown) => value is StreamTargetInterface` | Checks whether `value` is a usable `StreamTargetInterface` — a record with a callable `write`. A total type guard: it never throws and returns `false` for anything off-shape, so it narrows the one unavoidable boundary (the real `process.stdout` / `process.stderr`, or a fake stream a test injects) to the exact slice the sink + capture touch — no `as`. |
|
|
316
|
+
| `inferColumns` | function | `(target: StreamTargetInterface) => number` | Infers the width in character cells of a stream target — its live `columns` when it is a TTY, else the non-interactive `DEFAULT_COLUMNS` fallback. The basis a `ServerSinkInterface` reports through `columns` so a `Reporter` / `Progress` can size its layout to the terminal. |
|
|
317
|
+
| `inferStyled` | function | `(target: StreamTargetInterface, environment: Readonly<Record<string, string \| undefined>>) => boolean` | Infers whether one stream target receives styled output — a present `FORCE_COLOR` first, then a non-empty `NO_COLOR`, then `target.isTTY === true`. |
|
|
318
|
+
| `decodeChunk` | function | `(chunk: unknown, encoding?: unknown) => string` | Decodes one `process.stdout.write` / `process.stderr.write` chunk to a string — total, never throws. The process write signature accepts `string \| Uint8Array` plus an optional encoding; the capture wrapper reuses this so intercepting a raw stream write can never crash the host (a throw inside `process.stdout.write` would take the program down). |
|
|
319
|
+
| `isBufferEncoding` | function | `(encoding: unknown) => encoding is BufferEncoding` | Checks whether `encoding` is a `BufferEncoding` accepted by `Buffer.prototype.toString` — a total guard used by `decodeChunk` to honor a process-write `encoding` argument only when it is a real Node encoding (otherwise utf-8 is assumed). |
|
|
320
320
|
|
|
321
321
|
### Server sink constants
|
|
322
322
|
|
|
@@ -324,11 +324,11 @@ The default stream set, buffer cap, no-TTY column fallback, and the stream → l
|
|
|
324
324
|
|
|
325
325
|
A `Shape` cell holds the constant's declared type.
|
|
326
326
|
|
|
327
|
-
|
|
|
327
|
+
| Name | Kind | Signature | Summary |
|
|
328
328
|
| ---------------------- | ----- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
329
329
|
| `STREAM_LEVELS` | const | `readonly StreamLevel[]` | Lists the process streams a `ProcessCaptureInterface` can intercept, in `stdout`-then-`stderr` order — the `StreamLevel` universe and the default configured set. |
|
|
330
|
-
| `DEFAULT_STREAM_LIMIT` | const | `
|
|
331
|
-
| `DEFAULT_COLUMNS` | const | `
|
|
330
|
+
| `DEFAULT_STREAM_LIMIT` | const | `1000` | Sets the default bounded-buffer cap for a `ProcessCaptureInterface` — `1000`, so at most that many recent `CapturedChunk`s are retained per buffer (the total buffer and each per-stream bucket; oldest dropped first) and retention is always bounded. |
|
|
331
|
+
| `DEFAULT_COLUMNS` | const | `80` | Sets the terminal width `createServerSink` reports through `ServerSinkInterface.columns` when the `stdout` stream is not a TTY (so `.columns` is `undefined`) and no explicit `options.columns` was supplied — the conventional 80-column default a non-interactive context (a pipe, a CI log) assumes. |
|
|
332
332
|
| `STREAM_LEVEL_MAP` | const | `Readonly<Record<StreamLevel, LogLevel>>` | Maps each `StreamLevel` to its `LogLevel` for the optional sink forward — the projection a process capture routes through when writing an intercepted chunk to a `SinkInterface`. `sink.write(text, STREAM_LEVEL_MAP[level])` is the call this map backs. `stderr` is conventionally the error/diagnostic stream → `error`; `stdout` is the normal output stream → `info`. The source of truth for the stream-to-log projection (the server analogue of the core `CAPTURE_LEVEL_MAP`). |
|
|
333
333
|
|
|
334
334
|
## Methods
|