@principal-ai/principal-view-cli 0.3.1 → 0.3.2
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/package.json +2 -2
- package/dist/commands/coverage.d.ts +0 -9
- package/dist/commands/coverage.d.ts.map +0 -1
- package/dist/commands/coverage.js +0 -158
- package/dist/commands/create.d.ts +0 -6
- package/dist/commands/create.d.ts.map +0 -1
- package/dist/commands/create.js +0 -50
- package/dist/commands/doctor.d.ts +0 -10
- package/dist/commands/doctor.d.ts.map +0 -1
- package/dist/commands/doctor.js +0 -274
- package/dist/commands/formats.d.ts +0 -6
- package/dist/commands/formats.d.ts.map +0 -1
- package/dist/commands/formats.js +0 -475
- package/dist/commands/hooks.d.ts +0 -9
- package/dist/commands/hooks.d.ts.map +0 -1
- package/dist/commands/hooks.js +0 -295
- package/dist/commands/init.d.ts +0 -6
- package/dist/commands/init.d.ts.map +0 -1
- package/dist/commands/init.js +0 -271
- package/dist/commands/lint.d.ts +0 -6
- package/dist/commands/lint.d.ts.map +0 -1
- package/dist/commands/lint.js +0 -506
- package/dist/commands/list.d.ts +0 -6
- package/dist/commands/list.d.ts.map +0 -1
- package/dist/commands/list.js +0 -80
- package/dist/commands/narrative/eval.d.ts +0 -3
- package/dist/commands/narrative/eval.d.ts.map +0 -1
- package/dist/commands/narrative/eval.js +0 -76
- package/dist/commands/narrative/index.d.ts +0 -3
- package/dist/commands/narrative/index.d.ts.map +0 -1
- package/dist/commands/narrative/index.js +0 -19
- package/dist/commands/narrative/inspect.d.ts +0 -3
- package/dist/commands/narrative/inspect.d.ts.map +0 -1
- package/dist/commands/narrative/inspect.js +0 -109
- package/dist/commands/narrative/list.d.ts +0 -3
- package/dist/commands/narrative/list.d.ts.map +0 -1
- package/dist/commands/narrative/list.js +0 -101
- package/dist/commands/narrative/render.d.ts +0 -3
- package/dist/commands/narrative/render.d.ts.map +0 -1
- package/dist/commands/narrative/render.js +0 -99
- package/dist/commands/narrative/test.d.ts +0 -3
- package/dist/commands/narrative/test.d.ts.map +0 -1
- package/dist/commands/narrative/test.js +0 -150
- package/dist/commands/narrative/utils.d.ts +0 -69
- package/dist/commands/narrative/utils.d.ts.map +0 -1
- package/dist/commands/narrative/utils.js +0 -158
- package/dist/commands/narrative/validate.d.ts +0 -3
- package/dist/commands/narrative/validate.d.ts.map +0 -1
- package/dist/commands/narrative/validate.js +0 -149
- package/dist/commands/schema.d.ts +0 -6
- package/dist/commands/schema.d.ts.map +0 -1
- package/dist/commands/schema.js +0 -336
- package/dist/commands/validate-execution.d.ts +0 -11
- package/dist/commands/validate-execution.d.ts.map +0 -1
- package/dist/commands/validate-execution.js +0 -223
- package/dist/commands/validate.d.ts +0 -6
- package/dist/commands/validate.d.ts.map +0 -1
- package/dist/commands/validate.js +0 -1065
- package/dist/index.cjs +0 -243779
- package/dist/index.cjs.map +0 -7
- package/dist/index.d.ts +0 -8
- package/dist/index.d.ts.map +0 -1
- package/dist/index.js +0 -45
package/dist/commands/formats.js
DELETED
|
@@ -1,475 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Formats command - Display documentation about file formats
|
|
3
|
-
*/
|
|
4
|
-
import { Command } from 'commander';
|
|
5
|
-
import chalk from 'chalk';
|
|
6
|
-
const FORMAT_SECTIONS = {
|
|
7
|
-
overview: `
|
|
8
|
-
${chalk.bold.cyan('Principal View OTEL File Formats')}
|
|
9
|
-
${chalk.dim('═'.repeat(70))}
|
|
10
|
-
|
|
11
|
-
The Principal View OTEL workflow uses three main file types:
|
|
12
|
-
|
|
13
|
-
${chalk.bold('1. Canvas Files')} ${chalk.yellow('.otel.canvas')}
|
|
14
|
-
Define OTEL event schemas and telemetry structure for a feature.
|
|
15
|
-
These are the single source of truth for what events should be emitted.
|
|
16
|
-
|
|
17
|
-
${chalk.bold('2. Narrative Files')} ${chalk.yellow('.narrative.json')}
|
|
18
|
-
Define scenarios and templates for rendering executions as human-readable
|
|
19
|
-
narratives based on the emitted events.
|
|
20
|
-
|
|
21
|
-
${chalk.bold('3. Execution Files')} ${chalk.yellow('.otel.json')}
|
|
22
|
-
Captured OTEL spans from test runs or production code, exported for
|
|
23
|
-
visualization and validation against canvas schemas.
|
|
24
|
-
|
|
25
|
-
Run ${chalk.cyan('npx @principal-ai/principal-view-cli formats <section>')} for details on:
|
|
26
|
-
${chalk.yellow('canvas')} .otel.canvas format and event schemas
|
|
27
|
-
${chalk.yellow('narrative')} .narrative.json format and scenario structure
|
|
28
|
-
${chalk.yellow('execution')} .otel.json format for captured spans
|
|
29
|
-
${chalk.yellow('examples')} Complete example files
|
|
30
|
-
`,
|
|
31
|
-
canvas: `
|
|
32
|
-
${chalk.bold.cyan('Canvas Format (.otel.canvas)')}
|
|
33
|
-
${chalk.dim('═'.repeat(70))}
|
|
34
|
-
|
|
35
|
-
Canvas files define the OTEL event schemas for a feature. They document what
|
|
36
|
-
events should be emitted and what attributes each event must/may contain.
|
|
37
|
-
|
|
38
|
-
${chalk.bold('File Location:')}
|
|
39
|
-
${chalk.dim('.principal-views/')}${chalk.yellow('<feature-name>.otel.canvas')}
|
|
40
|
-
|
|
41
|
-
${chalk.bold('Required Structure:')}
|
|
42
|
-
${chalk.dim('┌────────────────────────────────────────────────────────────────────┐')}
|
|
43
|
-
${chalk.dim('│')} { ${chalk.dim('│')}
|
|
44
|
-
${chalk.dim('│')} ${chalk.green('"nodes"')}: [ ${chalk.dim('// Array of event schemas')} ${chalk.dim('│')}
|
|
45
|
-
${chalk.dim('│')} { ${chalk.dim('│')}
|
|
46
|
-
${chalk.dim('│')} ${chalk.yellow('"id"')}: "event-id", ${chalk.dim('// Unique identifier')} ${chalk.dim('│')}
|
|
47
|
-
${chalk.dim('│')} ${chalk.yellow('"type"')}: "text", ${chalk.dim('│')}
|
|
48
|
-
${chalk.dim('│')} ${chalk.yellow('"text"')}: "# Event Name", ${chalk.dim('// Markdown description')} ${chalk.dim('│')}
|
|
49
|
-
${chalk.dim('│')} ${chalk.yellow('"x"')}: 0, ${chalk.yellow('"y"')}: 0, ${chalk.yellow('"width"')}: 200, ${chalk.yellow('"height"')}: 100, ${chalk.dim('│')}
|
|
50
|
-
${chalk.dim('│')} ${chalk.green('"pv"')}: { ${chalk.dim('│')}
|
|
51
|
-
${chalk.dim('│')} ${chalk.cyan('"otelEvent"')}: { ${chalk.dim('// OTEL event definition')} ${chalk.dim('│')}
|
|
52
|
-
${chalk.dim('│')} ${chalk.yellow('"name"')}: "feature.event.name", ${chalk.dim('│')}
|
|
53
|
-
${chalk.dim('│')} ${chalk.cyan('"attributes"')}: { ${chalk.dim('// Required & optional attrs')} ${chalk.dim('│')}
|
|
54
|
-
${chalk.dim('│')} ${chalk.green('"required"')}: ["attr.name", ...], ${chalk.dim('│')}
|
|
55
|
-
${chalk.dim('│')} ${chalk.green('"optional"')}: ["attr.name", ...] ${chalk.dim('│')}
|
|
56
|
-
${chalk.dim('│')} } ${chalk.dim('│')}
|
|
57
|
-
${chalk.dim('│')} } ${chalk.dim('│')}
|
|
58
|
-
${chalk.dim('│')} } ${chalk.dim('│')}
|
|
59
|
-
${chalk.dim('│')} } ${chalk.dim('│')}
|
|
60
|
-
${chalk.dim('│')} ], ${chalk.dim('│')}
|
|
61
|
-
${chalk.dim('│')} ${chalk.green('"edges"')}: [], ${chalk.dim('// Optional: event relationships')} ${chalk.dim('│')}
|
|
62
|
-
${chalk.dim('│')} ${chalk.green('"pv"')}: { ${chalk.dim('│')}
|
|
63
|
-
${chalk.dim('│')} ${chalk.yellow('"name"')}: "Feature Name", ${chalk.dim('// Feature name (NOT "...Canvas")')} ${chalk.dim('│')}
|
|
64
|
-
${chalk.dim('│')} ${chalk.yellow('"version"')}: "1.0.0" ${chalk.dim('│')}
|
|
65
|
-
${chalk.dim('│')} } ${chalk.dim('│')}
|
|
66
|
-
${chalk.dim('│')} } ${chalk.dim('│')}
|
|
67
|
-
${chalk.dim('└────────────────────────────────────────────────────────────────────┘')}
|
|
68
|
-
|
|
69
|
-
${chalk.bold('Event Schema Best Practices:')}
|
|
70
|
-
|
|
71
|
-
${chalk.cyan('1. Canvas represents complete, encompassing functionality:')}
|
|
72
|
-
✅ API route - Full request/response cycle
|
|
73
|
-
✅ CLI command - Complete tool execution
|
|
74
|
-
✅ Business operation - End-to-end workflow
|
|
75
|
-
❌ Individual helper functions (too granular)
|
|
76
|
-
|
|
77
|
-
${chalk.cyan('2. Event naming convention:')}
|
|
78
|
-
${chalk.yellow('<feature>.<operation>.<state>')}
|
|
79
|
-
Examples:
|
|
80
|
-
- validation.started
|
|
81
|
-
- validation.complete
|
|
82
|
-
- validation.error
|
|
83
|
-
- import.parsing.complete
|
|
84
|
-
|
|
85
|
-
${chalk.cyan('3. Start simple (2-4 events):')}
|
|
86
|
-
- ${chalk.green('started')} - When feature begins
|
|
87
|
-
- ${chalk.green('complete')} - When feature succeeds
|
|
88
|
-
- ${chalk.green('error')} - When feature fails
|
|
89
|
-
- (optional) progress events for clear intermediate steps
|
|
90
|
-
|
|
91
|
-
${chalk.cyan('4. Attribute naming conventions:')}
|
|
92
|
-
${chalk.yellow('<category>.<name>')}
|
|
93
|
-
- input.* (input.size, input.recordCount)
|
|
94
|
-
- output.* (output.count, output.success)
|
|
95
|
-
- result.* (result.validCount, result.invalidCount)
|
|
96
|
-
- error.* (error.type, error.message, error.stage)
|
|
97
|
-
- duration.* (duration.ms)
|
|
98
|
-
|
|
99
|
-
${chalk.cyan('5. Required vs Optional attributes:')}
|
|
100
|
-
- ${chalk.green('required')}: Essential data needed for validation
|
|
101
|
-
- ${chalk.yellow('optional')}: Nice-to-have context, won't fail validation if missing
|
|
102
|
-
|
|
103
|
-
${chalk.bold('Validation:')}
|
|
104
|
-
${chalk.cyan('npx @principal-ai/principal-view-cli validate')}
|
|
105
|
-
`,
|
|
106
|
-
narrative: `
|
|
107
|
-
${chalk.bold.cyan('Narrative Format (.narrative.json)')}
|
|
108
|
-
${chalk.dim('═'.repeat(70))}
|
|
109
|
-
|
|
110
|
-
Narrative files define scenarios for rendering execution data as human-readable
|
|
111
|
-
stories. They evaluate conditions against captured events to select the best
|
|
112
|
-
matching narrative template.
|
|
113
|
-
|
|
114
|
-
${chalk.bold('File Location:')}
|
|
115
|
-
${chalk.dim('.principal-views/')}${chalk.yellow('<feature-name>.narrative.json')}
|
|
116
|
-
${chalk.dim('(co-located with corresponding .otel.canvas file)')}
|
|
117
|
-
|
|
118
|
-
${chalk.bold('Required Structure:')}
|
|
119
|
-
${chalk.dim('┌────────────────────────────────────────────────────────────────────┐')}
|
|
120
|
-
${chalk.dim('│')} { ${chalk.dim('│')}
|
|
121
|
-
${chalk.dim('│')} ${chalk.green('"name"')}: "Feature Name", ${chalk.dim('// NOT "Feature Name Narratives"')} ${chalk.dim('│')}
|
|
122
|
-
${chalk.dim('│')} ${chalk.green('"description"')}: "What the feature does", ${chalk.dim('// Purpose, not "Narratives for..."')} ${chalk.dim('│')}
|
|
123
|
-
${chalk.dim('│')} ${chalk.green('"scenarios"')}: [ ${chalk.dim('│')}
|
|
124
|
-
${chalk.dim('│')} { ${chalk.dim('│')}
|
|
125
|
-
${chalk.dim('│')} ${chalk.yellow('"priority"')}: 1, ${chalk.dim('// Lower = higher priority')} ${chalk.dim('│')}
|
|
126
|
-
${chalk.dim('│')} ${chalk.yellow('"condition"')}: "...", ${chalk.dim('// JSONPath/logic expression')} ${chalk.dim('│')}
|
|
127
|
-
${chalk.dim('│')} ${chalk.yellow('"template"')}: { ${chalk.dim('// Narrative template')} ${chalk.dim('│')}
|
|
128
|
-
${chalk.dim('│')} ${chalk.cyan('"summary"')}: "...", ${chalk.dim('// One-line summary')} ${chalk.dim('│')}
|
|
129
|
-
${chalk.dim('│')} ${chalk.cyan('"details"')}: [ ${chalk.dim('// Step-by-step details')} ${chalk.dim('│')}
|
|
130
|
-
${chalk.dim('│')} "Step 1: ...", ${chalk.dim('│')}
|
|
131
|
-
${chalk.dim('│')} "Step 2: ...", ${chalk.dim('│')}
|
|
132
|
-
${chalk.dim('│')} ] ${chalk.dim('│')}
|
|
133
|
-
${chalk.dim('│')} } ${chalk.dim('│')}
|
|
134
|
-
${chalk.dim('│')} } ${chalk.dim('│')}
|
|
135
|
-
${chalk.dim('│')} ] ${chalk.dim('│')}
|
|
136
|
-
${chalk.dim('│')} } ${chalk.dim('│')}
|
|
137
|
-
${chalk.dim('└────────────────────────────────────────────────────────────────────┘')}
|
|
138
|
-
|
|
139
|
-
${chalk.bold('Naming Guidelines:')}
|
|
140
|
-
|
|
141
|
-
❌ DON'T append "Narratives" to the name:
|
|
142
|
-
"name": "Package Processor Narratives"
|
|
143
|
-
|
|
144
|
-
✅ DO use the feature name directly:
|
|
145
|
-
"name": "Package Processor"
|
|
146
|
-
|
|
147
|
-
❌ DON'T prefix description with boilerplate:
|
|
148
|
-
"description": "Human-readable narratives for package extraction..."
|
|
149
|
-
|
|
150
|
-
✅ DO describe the feature's purpose:
|
|
151
|
-
"description": "Package extraction and analysis from repository file trees"
|
|
152
|
-
|
|
153
|
-
${chalk.bold('Scenario Best Practices:')}
|
|
154
|
-
|
|
155
|
-
${chalk.cyan('1. Priority ordering (scenarios evaluated in order):')}
|
|
156
|
-
- ${chalk.green('1-10')} Specific scenarios (success/failure cases)
|
|
157
|
-
- ${chalk.yellow('999')} Fallback scenario (catches anything)
|
|
158
|
-
|
|
159
|
-
${chalk.cyan('2. Standard scenario set:')}
|
|
160
|
-
- ${chalk.green('Success')} (priority 1): Feature completed successfully
|
|
161
|
-
- ${chalk.yellow('Failure')} (priority 2): Feature encountered error
|
|
162
|
-
- ${chalk.dim('Fallback')} (priority 999): Generic execution captured
|
|
163
|
-
|
|
164
|
-
${chalk.cyan('3. Template interpolation:')}
|
|
165
|
-
Use {{path.to.value}} to reference event attributes
|
|
166
|
-
Examples:
|
|
167
|
-
- {{record.count}}
|
|
168
|
-
- {{error.message}}
|
|
169
|
-
- {{result.invalidCount}}
|
|
170
|
-
|
|
171
|
-
${chalk.cyan('4. Template style:')}
|
|
172
|
-
- Clear, concise summary line
|
|
173
|
-
- 3-5 detail steps showing workflow
|
|
174
|
-
- Use emojis for visual scanning (✅ ❌ 📋)
|
|
175
|
-
- Include key metrics and IDs
|
|
176
|
-
|
|
177
|
-
${chalk.bold('Validation:')}
|
|
178
|
-
${chalk.cyan('npx @principal-ai/principal-view-cli narrative validate')}
|
|
179
|
-
`,
|
|
180
|
-
execution: `
|
|
181
|
-
${chalk.bold.cyan('Execution Format (.otel.json)')}
|
|
182
|
-
${chalk.dim('═'.repeat(70))}
|
|
183
|
-
|
|
184
|
-
Execution files use the ${chalk.bold('standard OTLP (OpenTelemetry Protocol) JSON format')}.
|
|
185
|
-
These files are exported by OpenTelemetry SDK and used for visualization
|
|
186
|
-
and validation against canvas schemas.
|
|
187
|
-
|
|
188
|
-
${chalk.bold('File Location:')}
|
|
189
|
-
${chalk.yellow('__executions__/')}${chalk.dim('<feature-name>.otel.json')}
|
|
190
|
-
${chalk.dim('(auto-generated by test infrastructure with OpenTelemetry SDK)')}
|
|
191
|
-
|
|
192
|
-
${chalk.bold('IMPORTANT:')} __executions__/ directory must be committed to git!
|
|
193
|
-
|
|
194
|
-
${chalk.bold('File Structure (OTLP JSON Format):')}
|
|
195
|
-
${chalk.dim('┌────────────────────────────────────────────────────────────────────┐')}
|
|
196
|
-
${chalk.dim('│')} { ${chalk.dim('│')}
|
|
197
|
-
${chalk.dim('│')} ${chalk.green('"resourceSpans"')}: [ ${chalk.dim('// OTLP root structure')} ${chalk.dim('│')}
|
|
198
|
-
${chalk.dim('│')} { ${chalk.dim('│')}
|
|
199
|
-
${chalk.dim('│')} ${chalk.yellow('"resource"')}: { ${chalk.dim('│')}
|
|
200
|
-
${chalk.dim('│')} ${chalk.cyan('"attributes"')}: [ ${chalk.dim('│')}
|
|
201
|
-
${chalk.dim('│')} { "key": "service.name", "value": { "stringValue": "..." }} ${chalk.dim('│')}
|
|
202
|
-
${chalk.dim('│')} ] ${chalk.dim('│')}
|
|
203
|
-
${chalk.dim('│')} }, ${chalk.dim('│')}
|
|
204
|
-
${chalk.dim('│')} ${chalk.yellow('"scopeSpans"')}: [ ${chalk.dim('│')}
|
|
205
|
-
${chalk.dim('│')} { ${chalk.dim('│')}
|
|
206
|
-
${chalk.dim('│')} ${chalk.cyan('"scope"')}: { "name": "...", "version": "..." }, ${chalk.dim('│')}
|
|
207
|
-
${chalk.dim('│')} ${chalk.cyan('"spans"')}: [ ${chalk.dim('│')}
|
|
208
|
-
${chalk.dim('│')} { ${chalk.dim('│')}
|
|
209
|
-
${chalk.dim('│')} "traceId": "4bf92f3577b34da6...", ${chalk.dim('// 32 hex chars')} ${chalk.dim('│')}
|
|
210
|
-
${chalk.dim('│')} "spanId": "00f067aa0ba902b7", ${chalk.dim('// 16 hex chars')} ${chalk.dim('│')}
|
|
211
|
-
${chalk.dim('│')} "name": "test:feature-name", ${chalk.dim('// Span name')} ${chalk.dim('│')}
|
|
212
|
-
${chalk.dim('│')} "kind": 0, ${chalk.dim('// 0=INTERNAL')} ${chalk.dim('│')}
|
|
213
|
-
${chalk.dim('│')} "startTimeUnixNano": "1703...", ${chalk.dim('// Unix nanoseconds')} ${chalk.dim('│')}
|
|
214
|
-
${chalk.dim('│')} "endTimeUnixNano": "1703...", ${chalk.dim('// Unix nanoseconds')} ${chalk.dim('│')}
|
|
215
|
-
${chalk.dim('│')} "attributes": [ ${chalk.dim('// Key-value pairs')} ${chalk.dim('│')}
|
|
216
|
-
${chalk.dim('│')} { "key": "input.size", "value": { "intValue": 42 } } ${chalk.dim('│')}
|
|
217
|
-
${chalk.dim('│')} ], ${chalk.dim('│')}
|
|
218
|
-
${chalk.dim('│')} "events": [ ${chalk.dim('// Span events')} ${chalk.dim('│')}
|
|
219
|
-
${chalk.dim('│')} { ${chalk.dim('│')}
|
|
220
|
-
${chalk.dim('│')} "timeUnixNano": "1703...", ${chalk.dim('│')}
|
|
221
|
-
${chalk.dim('│')} "name": "validation.started", ${chalk.dim('│')}
|
|
222
|
-
${chalk.dim('│')} "attributes": [...] ${chalk.dim('│')}
|
|
223
|
-
${chalk.dim('│')} } ${chalk.dim('│')}
|
|
224
|
-
${chalk.dim('│')} ] ${chalk.dim('│')}
|
|
225
|
-
${chalk.dim('│')} } ${chalk.dim('│')}
|
|
226
|
-
${chalk.dim('│')} ] ${chalk.dim('│')}
|
|
227
|
-
${chalk.dim('│')} } ${chalk.dim('│')}
|
|
228
|
-
${chalk.dim('│')} ] ${chalk.dim('│')}
|
|
229
|
-
${chalk.dim('│')} } ${chalk.dim('│')}
|
|
230
|
-
${chalk.dim('│')} ] ${chalk.dim('│')}
|
|
231
|
-
${chalk.dim('│')} } ${chalk.dim('│')}
|
|
232
|
-
${chalk.dim('└────────────────────────────────────────────────────────────────────┘')}
|
|
233
|
-
|
|
234
|
-
${chalk.bold('OTLP Format Details:')}
|
|
235
|
-
|
|
236
|
-
${chalk.cyan('resourceSpans')} ${chalk.dim('(array, required)')}
|
|
237
|
-
Root array containing resource-grouped spans
|
|
238
|
-
|
|
239
|
-
${chalk.cyan('resource.attributes')} ${chalk.dim('(array)')}
|
|
240
|
-
Metadata about the service (e.g., service.name)
|
|
241
|
-
|
|
242
|
-
${chalk.cyan('scopeSpans')} ${chalk.dim('(array, required)')}
|
|
243
|
-
Instrumentation scope-grouped spans
|
|
244
|
-
|
|
245
|
-
${chalk.cyan('spans')} ${chalk.dim('(array, required)')}
|
|
246
|
-
Array of span objects with OTLP structure
|
|
247
|
-
|
|
248
|
-
${chalk.bold('Span Fields (OTLP Standard):')}
|
|
249
|
-
|
|
250
|
-
${chalk.cyan('traceId')} ${chalk.dim('(string)')} - Unique trace identifier (32 hex chars)
|
|
251
|
-
${chalk.cyan('spanId')} ${chalk.dim('(string)')} - Unique span identifier (16 hex chars)
|
|
252
|
-
${chalk.cyan('parentSpanId')} ${chalk.dim('(string, optional)')} - Parent span ID
|
|
253
|
-
${chalk.cyan('name')} ${chalk.dim('(string)')} - Operation name
|
|
254
|
-
${chalk.cyan('kind')} ${chalk.dim('(number)')} - 0=UNSPECIFIED, 1=INTERNAL, 2=SERVER, 3=CLIENT, 4=PRODUCER, 5=CONSUMER
|
|
255
|
-
${chalk.cyan('startTimeUnixNano')} ${chalk.dim('(string)')} - Start time in Unix nanoseconds
|
|
256
|
-
${chalk.cyan('endTimeUnixNano')} ${chalk.dim('(string)')} - End time in Unix nanoseconds
|
|
257
|
-
${chalk.cyan('attributes')} ${chalk.dim('(array)')} - Key-value pairs: [{ key, value: { stringValue|intValue|... } }]
|
|
258
|
-
${chalk.cyan('events')} ${chalk.dim('(array)')} - Span events with timestamps and attributes
|
|
259
|
-
${chalk.cyan('status')} ${chalk.dim('(object)')} - Status: { code: 1=OK, 2=ERROR }
|
|
260
|
-
|
|
261
|
-
${chalk.bold('Attribute Value Format:')}
|
|
262
|
-
{ "stringValue": "..." } ${chalk.dim('// For strings')}
|
|
263
|
-
{ "intValue": 42 } ${chalk.dim('// For integers')}
|
|
264
|
-
{ "doubleValue": 3.14 } ${chalk.dim('// For floats')}
|
|
265
|
-
{ "boolValue": true } ${chalk.dim('// For booleans')}
|
|
266
|
-
|
|
267
|
-
${chalk.bold('Generation:')}
|
|
268
|
-
Use OpenTelemetry SDK with OTLP JSON exporter
|
|
269
|
-
Example: @opentelemetry/sdk-trace-node + InMemorySpanExporter
|
|
270
|
-
See: tests/otel-setup.ts in the add-skill repository
|
|
271
|
-
|
|
272
|
-
${chalk.bold('Validation:')}
|
|
273
|
-
${chalk.cyan('npx @principal-ai/principal-view-cli validate-execution <file>')}
|
|
274
|
-
|
|
275
|
-
${chalk.bold('Resources:')}
|
|
276
|
-
OTLP Spec: https://opentelemetry.io/docs/specs/otlp/
|
|
277
|
-
OpenTelemetry JS: https://github.com/open-telemetry/opentelemetry-js
|
|
278
|
-
`,
|
|
279
|
-
examples: `
|
|
280
|
-
${chalk.bold.cyan('Complete File Examples')}
|
|
281
|
-
${chalk.dim('═'.repeat(70))}
|
|
282
|
-
|
|
283
|
-
${chalk.bold('Example 1: Data Validator Canvas')}
|
|
284
|
-
${chalk.dim('─'.repeat(70))}
|
|
285
|
-
${chalk.yellow('.principal-views/data-validator.otel.canvas')}
|
|
286
|
-
|
|
287
|
-
{
|
|
288
|
-
"nodes": [
|
|
289
|
-
{
|
|
290
|
-
"id": "validation-started",
|
|
291
|
-
"type": "text",
|
|
292
|
-
"text": "# validation.started\\n\\nEmitted when validation begins",
|
|
293
|
-
"x": 0, "y": 0, "width": 200, "height": 100,
|
|
294
|
-
"pv": {
|
|
295
|
-
"otelEvent": {
|
|
296
|
-
"name": "validation.started",
|
|
297
|
-
"attributes": {
|
|
298
|
-
"required": ["input.recordCount"],
|
|
299
|
-
"optional": ["input.source"]
|
|
300
|
-
}
|
|
301
|
-
}
|
|
302
|
-
}
|
|
303
|
-
},
|
|
304
|
-
{
|
|
305
|
-
"id": "validation-complete",
|
|
306
|
-
"type": "text",
|
|
307
|
-
"text": "# validation.complete\\n\\nEmitted when validation succeeds",
|
|
308
|
-
"x": 250, "y": 0, "width": 200, "height": 100,
|
|
309
|
-
"pv": {
|
|
310
|
-
"otelEvent": {
|
|
311
|
-
"name": "validation.complete",
|
|
312
|
-
"attributes": {
|
|
313
|
-
"required": ["result.validCount", "result.invalidCount"],
|
|
314
|
-
"optional": ["duration.ms"]
|
|
315
|
-
}
|
|
316
|
-
}
|
|
317
|
-
}
|
|
318
|
-
},
|
|
319
|
-
{
|
|
320
|
-
"id": "validation-error",
|
|
321
|
-
"type": "text",
|
|
322
|
-
"text": "# validation.error\\n\\nEmitted when validation fails",
|
|
323
|
-
"x": 500, "y": 0, "width": 200, "height": 100,
|
|
324
|
-
"pv": {
|
|
325
|
-
"otelEvent": {
|
|
326
|
-
"name": "validation.error",
|
|
327
|
-
"attributes": {
|
|
328
|
-
"required": ["error.type", "error.message"],
|
|
329
|
-
"optional": ["error.stage"]
|
|
330
|
-
}
|
|
331
|
-
}
|
|
332
|
-
}
|
|
333
|
-
}
|
|
334
|
-
],
|
|
335
|
-
"edges": [],
|
|
336
|
-
"pv": {
|
|
337
|
-
"name": "Data Validator",
|
|
338
|
-
"version": "1.0.0"
|
|
339
|
-
}
|
|
340
|
-
}
|
|
341
|
-
|
|
342
|
-
${chalk.bold('Example 2: Narrative Scenarios')}
|
|
343
|
-
${chalk.dim('─'.repeat(70))}
|
|
344
|
-
${chalk.yellow('.principal-views/data-validator.narrative.json')}
|
|
345
|
-
|
|
346
|
-
{
|
|
347
|
-
"name": "Data Validator",
|
|
348
|
-
"description": "Validates data records against defined schemas",
|
|
349
|
-
"scenarios": [
|
|
350
|
-
{
|
|
351
|
-
"priority": 1,
|
|
352
|
-
"condition": "events[?name=='validation.complete']",
|
|
353
|
-
"template": {
|
|
354
|
-
"summary": "✅ Validated {{result.validCount}} records successfully",
|
|
355
|
-
"details": [
|
|
356
|
-
"🔍 Started validation",
|
|
357
|
-
"📊 Processed {{input.recordCount}} records",
|
|
358
|
-
"✅ {{result.validCount}} valid",
|
|
359
|
-
"❌ {{result.invalidCount}} invalid"
|
|
360
|
-
]
|
|
361
|
-
}
|
|
362
|
-
},
|
|
363
|
-
{
|
|
364
|
-
"priority": 2,
|
|
365
|
-
"condition": "events[?name=='validation.error']",
|
|
366
|
-
"template": {
|
|
367
|
-
"summary": "❌ Validation failed: {{error.message}}",
|
|
368
|
-
"details": [
|
|
369
|
-
"🔍 Started validation",
|
|
370
|
-
"💥 Error occurred: {{error.message}}",
|
|
371
|
-
"🏷️ Error type: {{error.type}}"
|
|
372
|
-
]
|
|
373
|
-
}
|
|
374
|
-
},
|
|
375
|
-
{
|
|
376
|
-
"priority": 999,
|
|
377
|
-
"condition": "true",
|
|
378
|
-
"template": {
|
|
379
|
-
"summary": "📋 Validation execution captured",
|
|
380
|
-
"details": [
|
|
381
|
-
"📦 Captured {{spans.length}} events",
|
|
382
|
-
"⏱️ Duration: {{duration.ms}}ms"
|
|
383
|
-
]
|
|
384
|
-
}
|
|
385
|
-
}
|
|
386
|
-
]
|
|
387
|
-
}
|
|
388
|
-
|
|
389
|
-
${chalk.bold('Example 3: Execution File')}
|
|
390
|
-
${chalk.dim('─'.repeat(70))}
|
|
391
|
-
${chalk.yellow('__executions__/data-validator.otel.json')}
|
|
392
|
-
|
|
393
|
-
{
|
|
394
|
-
"exportedAt": "2025-01-21T10:30:45.123Z",
|
|
395
|
-
"serviceName": "my-app-tests",
|
|
396
|
-
"spanCount": 3,
|
|
397
|
-
"spans": [
|
|
398
|
-
{
|
|
399
|
-
"traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
|
|
400
|
-
"spanId": "00f067aa0ba902b7",
|
|
401
|
-
"parentSpanId": null,
|
|
402
|
-
"name": "test:data-validator",
|
|
403
|
-
"kind": "INTERNAL",
|
|
404
|
-
"startTime": 1703548800000,
|
|
405
|
-
"endTime": 1703548800150,
|
|
406
|
-
"duration": 150,
|
|
407
|
-
"attributes": {
|
|
408
|
-
"test.name": "data validator success case"
|
|
409
|
-
},
|
|
410
|
-
"status": { "code": "OK" },
|
|
411
|
-
"events": []
|
|
412
|
-
},
|
|
413
|
-
{
|
|
414
|
-
"traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
|
|
415
|
-
"spanId": "abc123def4567890",
|
|
416
|
-
"parentSpanId": "00f067aa0ba902b7",
|
|
417
|
-
"name": "validation.started",
|
|
418
|
-
"kind": "INTERNAL",
|
|
419
|
-
"startTime": 1703548800010,
|
|
420
|
-
"endTime": 1703548800015,
|
|
421
|
-
"duration": 5,
|
|
422
|
-
"attributes": {
|
|
423
|
-
"input.recordCount": 100,
|
|
424
|
-
"input.source": "test-data.csv"
|
|
425
|
-
},
|
|
426
|
-
"status": { "code": "OK" },
|
|
427
|
-
"events": []
|
|
428
|
-
},
|
|
429
|
-
{
|
|
430
|
-
"traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
|
|
431
|
-
"spanId": "def789abc1234567",
|
|
432
|
-
"parentSpanId": "00f067aa0ba902b7",
|
|
433
|
-
"name": "validation.complete",
|
|
434
|
-
"kind": "INTERNAL",
|
|
435
|
-
"startTime": 1703548800140,
|
|
436
|
-
"endTime": 1703548800145,
|
|
437
|
-
"duration": 5,
|
|
438
|
-
"attributes": {
|
|
439
|
-
"result.validCount": 95,
|
|
440
|
-
"result.invalidCount": 5,
|
|
441
|
-
"duration.ms": 130
|
|
442
|
-
},
|
|
443
|
-
"status": { "code": "OK" },
|
|
444
|
-
"events": []
|
|
445
|
-
}
|
|
446
|
-
]
|
|
447
|
-
}
|
|
448
|
-
|
|
449
|
-
${chalk.bold('Next Steps:')}
|
|
450
|
-
${chalk.cyan('npx @principal-ai/principal-view-cli validate')} Validate canvas
|
|
451
|
-
${chalk.cyan('npx @principal-ai/principal-view-cli narrative validate')} Validate narratives
|
|
452
|
-
${chalk.cyan('npx @principal-ai/principal-view-cli validate-execution')} Validate execution
|
|
453
|
-
`,
|
|
454
|
-
};
|
|
455
|
-
export function createFormatsCommand() {
|
|
456
|
-
const command = new Command('formats');
|
|
457
|
-
command
|
|
458
|
-
.description('Display documentation about file formats')
|
|
459
|
-
.argument('[section]', 'Section to display: overview, canvas, narrative, execution, examples')
|
|
460
|
-
.action((section) => {
|
|
461
|
-
const validSections = Object.keys(FORMAT_SECTIONS);
|
|
462
|
-
if (!section) {
|
|
463
|
-
console.log(FORMAT_SECTIONS.overview);
|
|
464
|
-
return;
|
|
465
|
-
}
|
|
466
|
-
const normalizedSection = section.toLowerCase();
|
|
467
|
-
if (!validSections.includes(normalizedSection)) {
|
|
468
|
-
console.log(chalk.red(`Unknown section: ${section}`));
|
|
469
|
-
console.log(`Valid sections: ${validSections.join(', ')}`);
|
|
470
|
-
process.exit(1);
|
|
471
|
-
}
|
|
472
|
-
console.log(FORMAT_SECTIONS[normalizedSection]);
|
|
473
|
-
});
|
|
474
|
-
return command;
|
|
475
|
-
}
|
package/dist/commands/hooks.d.ts
DELETED
|
@@ -1,9 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Hooks command - Manage husky pre-commit hooks for Principal View
|
|
3
|
-
*
|
|
4
|
-
* This command installs/removes pre-commit hooks into a target project
|
|
5
|
-
* that will run `npx @principal-ai/principal-view-cli doctor` and `npx @principal-ai/principal-view-cli validate` before each commit.
|
|
6
|
-
*/
|
|
7
|
-
import { Command } from 'commander';
|
|
8
|
-
export declare function createHooksCommand(): Command;
|
|
9
|
-
//# sourceMappingURL=hooks.d.ts.map
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../src/commands/hooks.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA4NpC,wBAAgB,kBAAkB,IAAI,OAAO,CA+F5C"}
|