@fnndsc/cumin 3.4.0 → 3.5.0
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/error/errorStack.d.ts +48 -0
- package/dist/error/errorStack.js +71 -10
- package/dist/error/errorStack.js.map +1 -1
- package/dist/index.d.ts +1 -0
- package/dist/index.js +1 -0
- package/dist/index.js.map +1 -1
- package/dist/utils/envelope.d.ts +115 -0
- package/dist/utils/envelope.js +70 -0
- package/dist/utils/envelope.js.map +1 -0
- package/package.json +1 -1
|
@@ -1,6 +1,15 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* @file Process-wide error/message stack for deferred, structured reporting.
|
|
3
3
|
*
|
|
4
|
+
* The stack is a process singleton, but it is *async-context aware*: work run
|
|
5
|
+
* inside {@link ErrorStack.scope_run} pushes to and pops from its own isolated
|
|
6
|
+
* stack rather than the shared one. This lets fire-and-forget background work
|
|
7
|
+
* (cache warming, background refreshes) keep its error traffic off the shared
|
|
8
|
+
* stack, so a foreground command that checkpoints the stack and drains it
|
|
9
|
+
* afterward (see {@link ErrorStack.checkpoint_mark} /
|
|
10
|
+
* {@link ErrorStack.checkpoint_drain}) captures only its own messages and is
|
|
11
|
+
* never corrupted by a background push landing in its drain window.
|
|
12
|
+
*
|
|
4
13
|
* @module
|
|
5
14
|
*/
|
|
6
15
|
type MessageType = "error" | "warning";
|
|
@@ -25,7 +34,46 @@ declare class ErrorStack {
|
|
|
25
34
|
private static instance;
|
|
26
35
|
private stack;
|
|
27
36
|
private functionNamePadWidth;
|
|
37
|
+
/**
|
|
38
|
+
* Holds the isolated stack for work running inside {@link scope_run}. When
|
|
39
|
+
* a store is present, all operations target it instead of the shared stack.
|
|
40
|
+
*/
|
|
41
|
+
private scopeStorage;
|
|
28
42
|
private constructor();
|
|
43
|
+
/**
|
|
44
|
+
* Returns the stack the current async context should operate on: the
|
|
45
|
+
* isolated stack when inside a {@link scope_run}, otherwise the shared one.
|
|
46
|
+
*
|
|
47
|
+
* @returns The active stack array.
|
|
48
|
+
*/
|
|
49
|
+
private stack_active;
|
|
50
|
+
/**
|
|
51
|
+
* Runs a function with an isolated error stack that the shared stack — and
|
|
52
|
+
* any foreground command draining it — never sees. Fire-and-forget
|
|
53
|
+
* background work wraps its body in this so its error traffic cannot land
|
|
54
|
+
* in a concurrent foreground command's drain window. The isolation follows
|
|
55
|
+
* the whole async causal chain started inside `fn`.
|
|
56
|
+
*
|
|
57
|
+
* @param fn - The work to run against a fresh, isolated stack.
|
|
58
|
+
* @returns Whatever `fn` returns.
|
|
59
|
+
*/
|
|
60
|
+
scope_run<T>(fn: () => T): T;
|
|
61
|
+
/**
|
|
62
|
+
* Marks the current depth of the active stack, for a later
|
|
63
|
+
* {@link checkpoint_drain}.
|
|
64
|
+
*
|
|
65
|
+
* @returns An opaque checkpoint (the current stack depth).
|
|
66
|
+
*/
|
|
67
|
+
checkpoint_mark(): number;
|
|
68
|
+
/**
|
|
69
|
+
* Removes and returns every message pushed above a checkpoint, so a command
|
|
70
|
+
* boundary can drain exactly the messages produced since it marked the
|
|
71
|
+
* stack. Messages the command's own code already popped are simply absent.
|
|
72
|
+
*
|
|
73
|
+
* @param checkpoint - A checkpoint from {@link checkpoint_mark}.
|
|
74
|
+
* @returns The drained messages, oldest first.
|
|
75
|
+
*/
|
|
76
|
+
checkpoint_drain(checkpoint: number): StackMessage[];
|
|
29
77
|
/**
|
|
30
78
|
* Get the singleton instance of the ErrorStack.
|
|
31
79
|
*
|
package/dist/error/errorStack.js
CHANGED
|
@@ -2,12 +2,22 @@
|
|
|
2
2
|
/**
|
|
3
3
|
* @file Process-wide error/message stack for deferred, structured reporting.
|
|
4
4
|
*
|
|
5
|
+
* The stack is a process singleton, but it is *async-context aware*: work run
|
|
6
|
+
* inside {@link ErrorStack.scope_run} pushes to and pops from its own isolated
|
|
7
|
+
* stack rather than the shared one. This lets fire-and-forget background work
|
|
8
|
+
* (cache warming, background refreshes) keep its error traffic off the shared
|
|
9
|
+
* stack, so a foreground command that checkpoints the stack and drains it
|
|
10
|
+
* afterward (see {@link ErrorStack.checkpoint_mark} /
|
|
11
|
+
* {@link ErrorStack.checkpoint_drain}) captures only its own messages and is
|
|
12
|
+
* never corrupted by a background push landing in its drain window.
|
|
13
|
+
*
|
|
5
14
|
* @module
|
|
6
15
|
*/
|
|
7
16
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
8
17
|
exports.errorStack = void 0;
|
|
9
18
|
exports.errorStack_configure = errorStack_configure;
|
|
10
19
|
exports.errorStack_getAllOfType = errorStack_getAllOfType;
|
|
20
|
+
const node_async_hooks_1 = require("node:async_hooks");
|
|
11
21
|
/**
|
|
12
22
|
* Pads a string to the right with spaces to a specified length.
|
|
13
23
|
* If the string is longer than the length, it is truncated with ellipses.
|
|
@@ -45,8 +55,55 @@ function functionName_getCurrent() {
|
|
|
45
55
|
class ErrorStack {
|
|
46
56
|
constructor(options = {}) {
|
|
47
57
|
this.stack = [];
|
|
58
|
+
/**
|
|
59
|
+
* Holds the isolated stack for work running inside {@link scope_run}. When
|
|
60
|
+
* a store is present, all operations target it instead of the shared stack.
|
|
61
|
+
*/
|
|
62
|
+
this.scopeStorage = new node_async_hooks_1.AsyncLocalStorage();
|
|
48
63
|
this.functionNamePadWidth = options.functionNamePadWidth || 45; // Default to 45 if not specified
|
|
49
64
|
}
|
|
65
|
+
/**
|
|
66
|
+
* Returns the stack the current async context should operate on: the
|
|
67
|
+
* isolated stack when inside a {@link scope_run}, otherwise the shared one.
|
|
68
|
+
*
|
|
69
|
+
* @returns The active stack array.
|
|
70
|
+
*/
|
|
71
|
+
stack_active() {
|
|
72
|
+
return this.scopeStorage.getStore() ?? this.stack;
|
|
73
|
+
}
|
|
74
|
+
/**
|
|
75
|
+
* Runs a function with an isolated error stack that the shared stack — and
|
|
76
|
+
* any foreground command draining it — never sees. Fire-and-forget
|
|
77
|
+
* background work wraps its body in this so its error traffic cannot land
|
|
78
|
+
* in a concurrent foreground command's drain window. The isolation follows
|
|
79
|
+
* the whole async causal chain started inside `fn`.
|
|
80
|
+
*
|
|
81
|
+
* @param fn - The work to run against a fresh, isolated stack.
|
|
82
|
+
* @returns Whatever `fn` returns.
|
|
83
|
+
*/
|
|
84
|
+
scope_run(fn) {
|
|
85
|
+
return this.scopeStorage.run([], fn);
|
|
86
|
+
}
|
|
87
|
+
/**
|
|
88
|
+
* Marks the current depth of the active stack, for a later
|
|
89
|
+
* {@link checkpoint_drain}.
|
|
90
|
+
*
|
|
91
|
+
* @returns An opaque checkpoint (the current stack depth).
|
|
92
|
+
*/
|
|
93
|
+
checkpoint_mark() {
|
|
94
|
+
return this.stack_active().length;
|
|
95
|
+
}
|
|
96
|
+
/**
|
|
97
|
+
* Removes and returns every message pushed above a checkpoint, so a command
|
|
98
|
+
* boundary can drain exactly the messages produced since it marked the
|
|
99
|
+
* stack. Messages the command's own code already popped are simply absent.
|
|
100
|
+
*
|
|
101
|
+
* @param checkpoint - A checkpoint from {@link checkpoint_mark}.
|
|
102
|
+
* @returns The drained messages, oldest first.
|
|
103
|
+
*/
|
|
104
|
+
checkpoint_drain(checkpoint) {
|
|
105
|
+
return this.stack_active().splice(checkpoint);
|
|
106
|
+
}
|
|
50
107
|
/**
|
|
51
108
|
* Get the singleton instance of the ErrorStack.
|
|
52
109
|
*
|
|
@@ -71,7 +128,7 @@ class ErrorStack {
|
|
|
71
128
|
const functionName = functionName_getCurrent();
|
|
72
129
|
const paddedFunctionName = str_padRight(functionName, this.functionNamePadWidth);
|
|
73
130
|
const enhancedMessage = `[${paddedFunctionName}] | ${message}`;
|
|
74
|
-
this.
|
|
131
|
+
this.stack_active().push({ type, message: enhancedMessage });
|
|
75
132
|
}
|
|
76
133
|
/**
|
|
77
134
|
* Pop the last message from the stack.
|
|
@@ -79,7 +136,7 @@ class ErrorStack {
|
|
|
79
136
|
* @returns The last message object or undefined if the stack is empty.
|
|
80
137
|
*/
|
|
81
138
|
stack_pop() {
|
|
82
|
-
return this.
|
|
139
|
+
return this.stack_active().pop();
|
|
83
140
|
}
|
|
84
141
|
/**
|
|
85
142
|
* Search the stack for messages containing a substring.
|
|
@@ -88,10 +145,10 @@ class ErrorStack {
|
|
|
88
145
|
* @returns An array of formatted strings matching the search.
|
|
89
146
|
*/
|
|
90
147
|
stack_getAll() {
|
|
91
|
-
return [...this.
|
|
148
|
+
return [...this.stack_active()];
|
|
92
149
|
}
|
|
93
150
|
stack_search(substring) {
|
|
94
|
-
return this.
|
|
151
|
+
return this.stack_active()
|
|
95
152
|
.filter((item) => item.message.toLowerCase().includes(substring.toLowerCase()))
|
|
96
153
|
.map((item) => `${item.type}: ${item.message}`);
|
|
97
154
|
}
|
|
@@ -102,7 +159,7 @@ class ErrorStack {
|
|
|
102
159
|
* @returns An array of message strings.
|
|
103
160
|
*/
|
|
104
161
|
allOfType_get(type) {
|
|
105
|
-
return this.
|
|
162
|
+
return this.stack_active()
|
|
106
163
|
.filter((item) => item.type === type)
|
|
107
164
|
.map((item) => item.message);
|
|
108
165
|
}
|
|
@@ -114,7 +171,7 @@ class ErrorStack {
|
|
|
114
171
|
* @returns An array of matching message strings.
|
|
115
172
|
*/
|
|
116
173
|
messagesOfType_search(type, substring) {
|
|
117
|
-
return this.
|
|
174
|
+
return this.stack_active()
|
|
118
175
|
.filter((item) => item.type === type &&
|
|
119
176
|
item.message.toLowerCase().includes(substring.toLowerCase()))
|
|
120
177
|
.map((item) => item.message);
|
|
@@ -123,7 +180,8 @@ class ErrorStack {
|
|
|
123
180
|
* Clear all messages from the stack.
|
|
124
181
|
*/
|
|
125
182
|
stack_clear() {
|
|
126
|
-
|
|
183
|
+
const active = this.stack_active();
|
|
184
|
+
active.length = 0;
|
|
127
185
|
}
|
|
128
186
|
/**
|
|
129
187
|
* Clear all messages of a specific type from the stack.
|
|
@@ -131,7 +189,10 @@ class ErrorStack {
|
|
|
131
189
|
* @param type - The message type to clear.
|
|
132
190
|
*/
|
|
133
191
|
type_clear(type) {
|
|
134
|
-
|
|
192
|
+
const active = this.stack_active();
|
|
193
|
+
const kept = active.filter((item) => item.type !== type);
|
|
194
|
+
active.length = 0;
|
|
195
|
+
active.push(...kept);
|
|
135
196
|
}
|
|
136
197
|
/**
|
|
137
198
|
* Check if the stack contains any messages.
|
|
@@ -139,7 +200,7 @@ class ErrorStack {
|
|
|
139
200
|
* @returns True if the stack is not empty, false otherwise.
|
|
140
201
|
*/
|
|
141
202
|
messages_has() {
|
|
142
|
-
return this.
|
|
203
|
+
return this.stack_active().length > 0;
|
|
143
204
|
}
|
|
144
205
|
/**
|
|
145
206
|
* Check if the stack contains any messages of a specific type.
|
|
@@ -148,7 +209,7 @@ class ErrorStack {
|
|
|
148
209
|
* @returns True if messages of the given type exist, false otherwise.
|
|
149
210
|
*/
|
|
150
211
|
messagesOfType_has(type) {
|
|
151
|
-
return this.
|
|
212
|
+
return this.stack_active().some((item) => item.type === type);
|
|
152
213
|
}
|
|
153
214
|
}
|
|
154
215
|
/**
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"errorStack.js","sourceRoot":"","sources":["../../src/error/errorStack.ts"],"names":[],"mappings":";AAAA
|
|
1
|
+
{"version":3,"file":"errorStack.js","sourceRoot":"","sources":["../../src/error/errorStack.ts"],"names":[],"mappings":"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"}
|
package/dist/index.d.ts
CHANGED
|
@@ -32,6 +32,7 @@ export * from "./io/node_io";
|
|
|
32
32
|
export * from "./utils/keypair";
|
|
33
33
|
export * from "./utils/searchable";
|
|
34
34
|
export * from "./utils/result";
|
|
35
|
+
export * from "./utils/envelope";
|
|
35
36
|
export * from "./cache";
|
|
36
37
|
export * from "./path/chrisPath";
|
|
37
38
|
export * from "./pipelines/chrisPipeline";
|
package/dist/index.js
CHANGED
|
@@ -50,6 +50,7 @@ __exportStar(require("./io/node_io"), exports);
|
|
|
50
50
|
__exportStar(require("./utils/keypair"), exports);
|
|
51
51
|
__exportStar(require("./utils/searchable"), exports);
|
|
52
52
|
__exportStar(require("./utils/result"), exports);
|
|
53
|
+
__exportStar(require("./utils/envelope"), exports);
|
|
53
54
|
__exportStar(require("./cache"), exports);
|
|
54
55
|
__exportStar(require("./path/chrisPath"), exports);
|
|
55
56
|
__exportStar(require("./pipelines/chrisPipeline"), exports);
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;AAEA;;;;;;;;GAQG;;;;;;;;;;;;;;;;;
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;AAEA;;;;;;;;GAQG;;;;;;;;;;;;;;;;;AA4EH,4CAKC;AA/ED,qCAAmB;AACnB,qDAAmC;AACnC,kDAAgC;AAChC,oDAAkC;AAClC,4DAA0C;AAC1C,yDAAuC;AACvC,yDAAuC;AACvC,mEAAiD;AACjD,6DAA2C;AAC3C,mDAAiC;AACjC,6DAA2C;AAC3C,iEAA+C;AAC/C,8DAA4C;AAC5C,yEAAuD;AACvD,iEAA+C;AAC/C,2DAAyC;AACzC,0DAAwC;AACxC,8DAA4C;AAC5C,+CAA6B;AAC7B,0CAAwB;AACxB,+CAA6B;AAC7B,kDAAgC;AAChC,qDAAmC;AACnC,iDAA+B;AAC/B,mDAAiC;AACjC,0CAAwB;AACxB,mDAAiC;AACjC,4DAA0C;AAC1C,qDAAmC;AACnC,mDAAiC;AACjC,uDAAqC;AACrC,iEAA+C;AAC/C,6DAA2C;AAE3C,iFAAiF;AACjF,8CAA2E;AAAlE,uGAAA,YAAY,OAAA;AAAE,uGAAA,YAAY,OAAA;AAAE,oGAAA,SAAS,OAAA;AAiC9C;;;;;GAKG;AACI,KAAK,UAAU,gBAAgB,CAAC,GAAW;IAChD,MAAM,OAAO,GAAW,OAAO,CAAC;IAChC,wCAAwC;IACxC,6CAA6C;IAC7C,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;GAEG;AACH,KAAK,UAAU,IAAI;IACjB,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;AAC5B,CAAC;AAED,gEAAgE;AAChE,qCAAqC;AACrC,IAAI,OAAO,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;IAC5B,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;QACrB,OAAO,CAAC,KAAK,CAAC,oBAAoB,EAAE,KAAK,CAAC,CAAC;QAC3C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC"}
|
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @file Command result envelope.
|
|
3
|
+
*
|
|
4
|
+
* Defines the envelope in which a command's outcome travels from execution
|
|
5
|
+
* to whatever hosts it: a REPL printing to a terminal, a daemon serving
|
|
6
|
+
* remote surfaces, or a pipeline consuming the output of a prior command.
|
|
7
|
+
* The envelope carries both renderings of a result: the text a terminal
|
|
8
|
+
* prints (ANSI permitted) and an optional typed model from which a
|
|
9
|
+
* graphical panel can render the same result structurally.
|
|
10
|
+
*
|
|
11
|
+
* The model slot is discriminated but deliberately untyped here: cumin
|
|
12
|
+
* knows the shape of the slot, never the payloads. Layers that own domain
|
|
13
|
+
* models (chili) export the kind-to-type mapping; layers that publish a
|
|
14
|
+
* wire contract (calypso) validate the slot at their boundary.
|
|
15
|
+
*
|
|
16
|
+
* Error detail is carried in the envelope rather than left implicit in the
|
|
17
|
+
* process-wide errorStack: the dispatch boundary checkpoints the stack
|
|
18
|
+
* before a command runs and drains anything pushed above the checkpoint
|
|
19
|
+
* into the envelope afterward.
|
|
20
|
+
*
|
|
21
|
+
* @see docs/calypso.adoc for the governing design.
|
|
22
|
+
* @module
|
|
23
|
+
*/
|
|
24
|
+
import { StackMessage } from "../error/errorStack";
|
|
25
|
+
/**
|
|
26
|
+
* Terminal status of a completed command.
|
|
27
|
+
*
|
|
28
|
+
* Additional statuses may be added over time; consumers must treat the
|
|
29
|
+
* union as open and handle unknown values conservatively.
|
|
30
|
+
*/
|
|
31
|
+
export type EnvelopeStatus = "ok" | "error";
|
|
32
|
+
/**
|
|
33
|
+
* Discriminated slot for a command's typed result.
|
|
34
|
+
*
|
|
35
|
+
* @property kind - Namespaced model identifier (e.g. `fs.listing`,
|
|
36
|
+
* `feed.detail`). The set of kinds is owned by the layer that produces
|
|
37
|
+
* the models, not by cumin.
|
|
38
|
+
* @property data - The typed payload. Opaque at this altitude; consumers
|
|
39
|
+
* narrow it via the kind map exported by the producing layer.
|
|
40
|
+
*/
|
|
41
|
+
export interface EnvelopeModel {
|
|
42
|
+
kind: string;
|
|
43
|
+
data: unknown;
|
|
44
|
+
}
|
|
45
|
+
/**
|
|
46
|
+
* Record of how a natural-language input was resolved into a command.
|
|
47
|
+
*
|
|
48
|
+
* Present only on envelopes produced through intent resolution, so that
|
|
49
|
+
* surfaces can show what was proposed and what actually ran rather than
|
|
50
|
+
* hiding the mediation.
|
|
51
|
+
*
|
|
52
|
+
* @property input - The user's original input, verbatim.
|
|
53
|
+
* @property proposed - The command line proposed by the resolver.
|
|
54
|
+
* @property validated - Whether the proposal passed validation against the
|
|
55
|
+
* live command vocabulary.
|
|
56
|
+
* @property executed - The command line that actually ran, when execution
|
|
57
|
+
* proceeded. Absent when validation failed or confirmation was declined.
|
|
58
|
+
*/
|
|
59
|
+
export interface ResolutionTrace {
|
|
60
|
+
input: string;
|
|
61
|
+
proposed: string;
|
|
62
|
+
validated: boolean;
|
|
63
|
+
executed?: string;
|
|
64
|
+
}
|
|
65
|
+
/**
|
|
66
|
+
* The envelope in which one command's complete outcome travels.
|
|
67
|
+
*
|
|
68
|
+
* Exactly one envelope concludes each executed command. Streaming output
|
|
69
|
+
* that preceded completion is a transport concern; the envelope's rendered
|
|
70
|
+
* field holds the accumulated data-channel text, so capture, piping, and
|
|
71
|
+
* redirection consume the envelope alone.
|
|
72
|
+
*
|
|
73
|
+
* @property status - Terminal status of the command.
|
|
74
|
+
* @property rendered - Accumulated printable output (ANSI permitted).
|
|
75
|
+
* @property renderedErr - Printable error-stream output (ANSI permitted),
|
|
76
|
+
* exactly what a terminal host writes to stderr. Kept separate from
|
|
77
|
+
* `rendered` so pipes and capture consume only the data stream.
|
|
78
|
+
* @property model - Optional typed result for structural consumers.
|
|
79
|
+
* @property errors - Structured error detail drained from the errorStack at
|
|
80
|
+
* the dispatch boundary, for machine consumers; presentation of errors on
|
|
81
|
+
* a terminal travels in `renderedErr`.
|
|
82
|
+
* @property trace - Resolution record for intent-derived commands.
|
|
83
|
+
*/
|
|
84
|
+
export interface CommandEnvelope {
|
|
85
|
+
status: EnvelopeStatus;
|
|
86
|
+
rendered: string;
|
|
87
|
+
renderedErr?: string;
|
|
88
|
+
model?: EnvelopeModel;
|
|
89
|
+
errors?: StackMessage[];
|
|
90
|
+
trace?: ResolutionTrace;
|
|
91
|
+
}
|
|
92
|
+
/**
|
|
93
|
+
* Creates a successful envelope.
|
|
94
|
+
*
|
|
95
|
+
* @param rendered - Accumulated printable output of the command.
|
|
96
|
+
* @param model - Optional typed result.
|
|
97
|
+
* @returns An envelope with `ok` status.
|
|
98
|
+
*/
|
|
99
|
+
export declare function envelope_ok(rendered: string, model?: EnvelopeModel): CommandEnvelope;
|
|
100
|
+
/**
|
|
101
|
+
* Creates a failed envelope.
|
|
102
|
+
*
|
|
103
|
+
* @param rendered - Any printable output produced before failure.
|
|
104
|
+
* @param errors - Structured error detail drained from the errorStack.
|
|
105
|
+
* @param renderedErr - Printable error-stream output (ANSI permitted).
|
|
106
|
+
* @returns An envelope with `error` status.
|
|
107
|
+
*/
|
|
108
|
+
export declare function envelope_error(rendered: string, errors?: StackMessage[], renderedErr?: string): CommandEnvelope;
|
|
109
|
+
/**
|
|
110
|
+
* Type guard for successful envelopes.
|
|
111
|
+
*
|
|
112
|
+
* @param envelope - The envelope to check.
|
|
113
|
+
* @returns True when the envelope's status is `ok`.
|
|
114
|
+
*/
|
|
115
|
+
export declare function envelope_isOk(envelope: CommandEnvelope): boolean;
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
/**
|
|
3
|
+
* @file Command result envelope.
|
|
4
|
+
*
|
|
5
|
+
* Defines the envelope in which a command's outcome travels from execution
|
|
6
|
+
* to whatever hosts it: a REPL printing to a terminal, a daemon serving
|
|
7
|
+
* remote surfaces, or a pipeline consuming the output of a prior command.
|
|
8
|
+
* The envelope carries both renderings of a result: the text a terminal
|
|
9
|
+
* prints (ANSI permitted) and an optional typed model from which a
|
|
10
|
+
* graphical panel can render the same result structurally.
|
|
11
|
+
*
|
|
12
|
+
* The model slot is discriminated but deliberately untyped here: cumin
|
|
13
|
+
* knows the shape of the slot, never the payloads. Layers that own domain
|
|
14
|
+
* models (chili) export the kind-to-type mapping; layers that publish a
|
|
15
|
+
* wire contract (calypso) validate the slot at their boundary.
|
|
16
|
+
*
|
|
17
|
+
* Error detail is carried in the envelope rather than left implicit in the
|
|
18
|
+
* process-wide errorStack: the dispatch boundary checkpoints the stack
|
|
19
|
+
* before a command runs and drains anything pushed above the checkpoint
|
|
20
|
+
* into the envelope afterward.
|
|
21
|
+
*
|
|
22
|
+
* @see docs/calypso.adoc for the governing design.
|
|
23
|
+
* @module
|
|
24
|
+
*/
|
|
25
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
26
|
+
exports.envelope_ok = envelope_ok;
|
|
27
|
+
exports.envelope_error = envelope_error;
|
|
28
|
+
exports.envelope_isOk = envelope_isOk;
|
|
29
|
+
/**
|
|
30
|
+
* Creates a successful envelope.
|
|
31
|
+
*
|
|
32
|
+
* @param rendered - Accumulated printable output of the command.
|
|
33
|
+
* @param model - Optional typed result.
|
|
34
|
+
* @returns An envelope with `ok` status.
|
|
35
|
+
*/
|
|
36
|
+
function envelope_ok(rendered, model) {
|
|
37
|
+
const envelope = { status: "ok", rendered };
|
|
38
|
+
if (model !== undefined) {
|
|
39
|
+
envelope.model = model;
|
|
40
|
+
}
|
|
41
|
+
return envelope;
|
|
42
|
+
}
|
|
43
|
+
/**
|
|
44
|
+
* Creates a failed envelope.
|
|
45
|
+
*
|
|
46
|
+
* @param rendered - Any printable output produced before failure.
|
|
47
|
+
* @param errors - Structured error detail drained from the errorStack.
|
|
48
|
+
* @param renderedErr - Printable error-stream output (ANSI permitted).
|
|
49
|
+
* @returns An envelope with `error` status.
|
|
50
|
+
*/
|
|
51
|
+
function envelope_error(rendered, errors, renderedErr) {
|
|
52
|
+
const envelope = { status: "error", rendered };
|
|
53
|
+
if (errors !== undefined) {
|
|
54
|
+
envelope.errors = errors;
|
|
55
|
+
}
|
|
56
|
+
if (renderedErr !== undefined) {
|
|
57
|
+
envelope.renderedErr = renderedErr;
|
|
58
|
+
}
|
|
59
|
+
return envelope;
|
|
60
|
+
}
|
|
61
|
+
/**
|
|
62
|
+
* Type guard for successful envelopes.
|
|
63
|
+
*
|
|
64
|
+
* @param envelope - The envelope to check.
|
|
65
|
+
* @returns True when the envelope's status is `ok`.
|
|
66
|
+
*/
|
|
67
|
+
function envelope_isOk(envelope) {
|
|
68
|
+
return envelope.status === "ok";
|
|
69
|
+
}
|
|
70
|
+
//# sourceMappingURL=envelope.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"envelope.js","sourceRoot":"","sources":["../../src/utils/envelope.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;;AAkFH,kCAMC;AAUD,wCAaC;AAQD,sCAEC;AA9CD;;;;;;GAMG;AACH,SAAgB,WAAW,CAAC,QAAgB,EAAE,KAAqB;IACjE,MAAM,QAAQ,GAAoB,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;IAC7D,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,QAAQ,CAAC,KAAK,GAAG,KAAK,CAAC;IACzB,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,cAAc,CAC5B,QAAgB,EAChB,MAAuB,EACvB,WAAoB;IAEpB,MAAM,QAAQ,GAAoB,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;IAChE,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,QAAQ,CAAC,MAAM,GAAG,MAAM,CAAC;IAC3B,CAAC;IACD,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;QAC9B,QAAQ,CAAC,WAAW,GAAG,WAAW,CAAC;IACrC,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;GAKG;AACH,SAAgB,aAAa,CAAC,QAAyB;IACrD,OAAO,QAAQ,CAAC,MAAM,KAAK,IAAI,CAAC;AAClC,CAAC"}
|