@principal-ai/principal-view-cli 0.2.1 → 0.2.3

package/dist/commands/formats.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Formats command - Display documentation about file formats
+ */
+import { Command } from 'commander';
+export declare function createFormatsCommand(): Command;
+//# sourceMappingURL=formats.d.ts.map

package/dist/commands/formats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formats.d.ts","sourceRoot":"","sources":["../../src/commands/formats.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAycpC,wBAAgB,oBAAoB,IAAI,OAAO,CA6B9C"}

package/dist/commands/formats.js

@@ -0,0 +1,475 @@
+/**
+ * Formats command - Display documentation about file formats
+ */
+import { Command } from 'commander';
+import chalk from 'chalk';
+const FORMAT_SECTIONS = {
+    overview: `
+${chalk.bold.cyan('Principal View OTEL File Formats')}
+${chalk.dim('═'.repeat(70))}
+
+The Principal View OTEL workflow uses three main file types:
+
+${chalk.bold('1. Canvas Files')} ${chalk.yellow('.otel.canvas')}
+   Define OTEL event schemas and telemetry structure for a feature.
+   These are the single source of truth for what events should be emitted.
+
+${chalk.bold('2. Narrative Files')} ${chalk.yellow('.narrative.json')}
+   Define scenarios and templates for rendering executions as human-readable
+   narratives based on the emitted events.
+
+${chalk.bold('3. Execution Files')} ${chalk.yellow('.otel.json')}
+   Captured OTEL spans from test runs or production code, exported for
+   visualization and validation against canvas schemas.
+
+Run ${chalk.cyan('npx @principal-ai/principal-view-cli formats <section>')} for details on:
+  ${chalk.yellow('canvas')}       .otel.canvas format and event schemas
+  ${chalk.yellow('narrative')}    .narrative.json format and scenario structure
+  ${chalk.yellow('execution')}    .otel.json format for captured spans
+  ${chalk.yellow('examples')}     Complete example files
+`,
+    canvas: `
+${chalk.bold.cyan('Canvas Format (.otel.canvas)')}
+${chalk.dim('═'.repeat(70))}
+
+Canvas files define the OTEL event schemas for a feature. They document what
+events should be emitted and what attributes each event must/may contain.
+
+${chalk.bold('File Location:')}
+  ${chalk.dim('.principal-views/')}${chalk.yellow('<feature-name>.otel.canvas')}
+
+${chalk.bold('Required Structure:')}
+${chalk.dim('┌────────────────────────────────────────────────────────────────────┐')}
+${chalk.dim('│')} {                                                                  ${chalk.dim('│')}
+${chalk.dim('│')}   ${chalk.green('"nodes"')}: [                  ${chalk.dim('// Array of event schemas')}      ${chalk.dim('│')}
+${chalk.dim('│')}     {                                                              ${chalk.dim('│')}
+${chalk.dim('│')}       ${chalk.yellow('"id"')}: "event-id",      ${chalk.dim('// Unique identifier')}         ${chalk.dim('│')}
+${chalk.dim('│')}       ${chalk.yellow('"type"')}: "text",                                              ${chalk.dim('│')}
+${chalk.dim('│')}       ${chalk.yellow('"text"')}: "# Event Name", ${chalk.dim('// Markdown description')}     ${chalk.dim('│')}
+${chalk.dim('│')}       ${chalk.yellow('"x"')}: 0, ${chalk.yellow('"y"')}: 0, ${chalk.yellow('"width"')}: 200, ${chalk.yellow('"height"')}: 100,                   ${chalk.dim('│')}
+${chalk.dim('│')}       ${chalk.green('"pv"')}: {                                                        ${chalk.dim('│')}
+${chalk.dim('│')}         ${chalk.cyan('"otelEvent"')}: {          ${chalk.dim('// OTEL event definition')}    ${chalk.dim('│')}
+${chalk.dim('│')}           ${chalk.yellow('"name"')}: "feature.event.name",                          ${chalk.dim('│')}
+${chalk.dim('│')}           ${chalk.cyan('"attributes"')}: {       ${chalk.dim('// Required & optional attrs')} ${chalk.dim('│')}
+${chalk.dim('│')}             ${chalk.green('"required"')}: ["attr.name", ...],                     ${chalk.dim('│')}
+${chalk.dim('│')}             ${chalk.green('"optional"')}: ["attr.name", ...]                      ${chalk.dim('│')}
+${chalk.dim('│')}           }                                                            ${chalk.dim('│')}
+${chalk.dim('│')}         }                                                              ${chalk.dim('│')}
+${chalk.dim('│')}       }                                                                ${chalk.dim('│')}
+${chalk.dim('│')}     }                                                                  ${chalk.dim('│')}
+${chalk.dim('│')}   ],                                                                   ${chalk.dim('│')}
+${chalk.dim('│')}   ${chalk.green('"edges"')}: [],                ${chalk.dim('// Optional: event relationships')} ${chalk.dim('│')}
+${chalk.dim('│')}   ${chalk.green('"pv"')}: {                                                          ${chalk.dim('│')}
+${chalk.dim('│')}     ${chalk.yellow('"name"')}: "Feature Name",  ${chalk.dim('// Feature name (NOT "...Canvas")')} ${chalk.dim('│')}
+${chalk.dim('│')}     ${chalk.yellow('"version"')}: "1.0.0"                                            ${chalk.dim('│')}
+${chalk.dim('│')}   }                                                                    ${chalk.dim('│')}
+${chalk.dim('│')} }                                                                      ${chalk.dim('│')}
+${chalk.dim('└────────────────────────────────────────────────────────────────────┘')}
+
+${chalk.bold('Event Schema Best Practices:')}
+
+${chalk.cyan('1. Canvas represents complete, encompassing functionality:')}
+   ✅ API route - Full request/response cycle
+   ✅ CLI command - Complete tool execution
+   ✅ Business operation - End-to-end workflow
+   ❌ Individual helper functions (too granular)
+
+${chalk.cyan('2. Event naming convention:')}
+   ${chalk.yellow('<feature>.<operation>.<state>')}
+   Examples:
+   - validation.started
+   - validation.complete
+   - validation.error
+   - import.parsing.complete
+
+${chalk.cyan('3. Start simple (2-4 events):')}
+   - ${chalk.green('started')}  - When feature begins
+   - ${chalk.green('complete')} - When feature succeeds
+   - ${chalk.green('error')}    - When feature fails
+   - (optional) progress events for clear intermediate steps
+
+${chalk.cyan('4. Attribute naming conventions:')}
+   ${chalk.yellow('<category>.<name>')}
+   - input.*     (input.size, input.recordCount)
+   - output.*    (output.count, output.success)
+   - result.*    (result.validCount, result.invalidCount)
+   - error.*     (error.type, error.message, error.stage)
+   - duration.*  (duration.ms)
+
+${chalk.cyan('5. Required vs Optional attributes:')}
+   - ${chalk.green('required')}: Essential data needed for validation
+   - ${chalk.yellow('optional')}: Nice-to-have context, won't fail validation if missing
+
+${chalk.bold('Validation:')}
+  ${chalk.cyan('npx @principal-ai/principal-view-cli validate')}
+`,
+    narrative: `
+${chalk.bold.cyan('Narrative Format (.narrative.json)')}
+${chalk.dim('═'.repeat(70))}
+
+Narrative files define scenarios for rendering execution data as human-readable
+stories. They evaluate conditions against captured events to select the best
+matching narrative template.
+
+${chalk.bold('File Location:')}
+  ${chalk.dim('.principal-views/')}${chalk.yellow('<feature-name>.narrative.json')}
+  ${chalk.dim('(co-located with corresponding .otel.canvas file)')}
+
+${chalk.bold('Required Structure:')}
+${chalk.dim('┌────────────────────────────────────────────────────────────────────┐')}
+${chalk.dim('│')} {                                                                  ${chalk.dim('│')}
+${chalk.dim('│')}   ${chalk.green('"name"')}: "Feature Name",      ${chalk.dim('// NOT "Feature Name Narratives"')} ${chalk.dim('│')}
+${chalk.dim('│')}   ${chalk.green('"description"')}: "What the feature does",  ${chalk.dim('// Purpose, not "Narratives for..."')} ${chalk.dim('│')}
+${chalk.dim('│')}   ${chalk.green('"scenarios"')}: [                                                 ${chalk.dim('│')}
+${chalk.dim('│')}     {                                                              ${chalk.dim('│')}
+${chalk.dim('│')}       ${chalk.yellow('"priority"')}: 1,           ${chalk.dim('// Lower = higher priority')}   ${chalk.dim('│')}
+${chalk.dim('│')}       ${chalk.yellow('"condition"')}: "...",      ${chalk.dim('// JSONPath/logic expression')} ${chalk.dim('│')}
+${chalk.dim('│')}       ${chalk.yellow('"template"')}: {            ${chalk.dim('// Narrative template')}        ${chalk.dim('│')}
+${chalk.dim('│')}         ${chalk.cyan('"summary"')}: "...",    ${chalk.dim('// One-line summary')}          ${chalk.dim('│')}
+${chalk.dim('│')}         ${chalk.cyan('"details"')}: [        ${chalk.dim('// Step-by-step details')}      ${chalk.dim('│')}
+${chalk.dim('│')}           "Step 1: ...",                                          ${chalk.dim('│')}
+${chalk.dim('│')}           "Step 2: ...",                                          ${chalk.dim('│')}
+${chalk.dim('│')}         ]                                                          ${chalk.dim('│')}
+${chalk.dim('│')}       }                                                            ${chalk.dim('│')}
+${chalk.dim('│')}     }                                                              ${chalk.dim('│')}
+${chalk.dim('│')}   ]                                                                ${chalk.dim('│')}
+${chalk.dim('│')} }                                                                  ${chalk.dim('│')}
+${chalk.dim('└────────────────────────────────────────────────────────────────────┘')}
+
+${chalk.bold('Naming Guidelines:')}
+
+  ❌ DON'T append "Narratives" to the name:
+     "name": "Package Processor Narratives"
+
+  ✅ DO use the feature name directly:
+     "name": "Package Processor"
+
+  ❌ DON'T prefix description with boilerplate:
+     "description": "Human-readable narratives for package extraction..."
+
+  ✅ DO describe the feature's purpose:
+     "description": "Package extraction and analysis from repository file trees"
+
+${chalk.bold('Scenario Best Practices:')}
+
+${chalk.cyan('1. Priority ordering (scenarios evaluated in order):')}
+   - ${chalk.green('1-10')}    Specific scenarios (success/failure cases)
+   - ${chalk.yellow('999')}     Fallback scenario (catches anything)
+
+${chalk.cyan('2. Standard scenario set:')}
+   - ${chalk.green('Success')} (priority 1): Feature completed successfully
+   - ${chalk.yellow('Failure')} (priority 2): Feature encountered error
+   - ${chalk.dim('Fallback')} (priority 999): Generic execution captured
+
+${chalk.cyan('3. Template interpolation:')}
+   Use {{path.to.value}} to reference event attributes
+   Examples:
+   - {{record.count}}
+   - {{error.message}}
+   - {{result.invalidCount}}
+
+${chalk.cyan('4. Template style:')}
+   - Clear, concise summary line
+   - 3-5 detail steps showing workflow
+   - Use emojis for visual scanning (✅ ❌ 📋)
+   - Include key metrics and IDs
+
+${chalk.bold('Validation:')}
+  ${chalk.cyan('npx @principal-ai/principal-view-cli narrative validate')}
+`,
+    execution: `
+${chalk.bold.cyan('Execution Format (.otel.json)')}
+${chalk.dim('═'.repeat(70))}
+
+Execution files contain captured OTEL spans from test runs or production code.
+These files are exported by your test infrastructure and used for visualization
+and validation against canvas schemas.
+
+${chalk.bold('File Location:')}
+  ${chalk.yellow('__executions__/')}${chalk.dim('<feature-name>.otel.json')}
+  ${chalk.dim('(auto-generated by test infrastructure)')}
+
+${chalk.bold('IMPORTANT:')} __executions__/ directory must be committed to git!
+
+${chalk.bold('File Structure:')}
+${chalk.dim('┌────────────────────────────────────────────────────────────────────┐')}
+${chalk.dim('│')} {                                                                  ${chalk.dim('│')}
+${chalk.dim('│')}   ${chalk.green('"exportedAt"')}: "2025-01-21T10:30:00.000Z",  ${chalk.dim('// ISO timestamp')} ${chalk.dim('│')}
+${chalk.dim('│')}   ${chalk.green('"serviceName"')}: "my-service",               ${chalk.dim('// Service name')}  ${chalk.dim('│')}
+${chalk.dim('│')}   ${chalk.green('"spanCount"')}: 5,                            ${chalk.dim('// Total spans')}   ${chalk.dim('│')}
+${chalk.dim('│')}   ${chalk.green('"spans"')}: [                                                     ${chalk.dim('│')}
+${chalk.dim('│')}     {                                                              ${chalk.dim('│')}
+${chalk.dim('│')}       ${chalk.yellow('"traceId"')}: "4bf92f3577b34da6...",  ${chalk.dim('// 32 hex chars')}     ${chalk.dim('│')}
+${chalk.dim('│')}       ${chalk.yellow('"spanId"')}: "00f067aa0ba902b7",     ${chalk.dim('// 16 hex chars')}     ${chalk.dim('│')}
+${chalk.dim('│')}       ${chalk.yellow('"parentSpanId"')}: "abc123...",      ${chalk.dim('// Parent span (null for root)')} ${chalk.dim('│')}
+${chalk.dim('│')}       ${chalk.yellow('"name"')}: "test:feature-name",     ${chalk.dim('// Span name')}         ${chalk.dim('│')}
+${chalk.dim('│')}       ${chalk.yellow('"kind"')}: "INTERNAL",              ${chalk.dim('// Span kind')}         ${chalk.dim('│')}
+${chalk.dim('│')}       ${chalk.yellow('"startTime"')}: 1703548800000,      ${chalk.dim('// Unix ms')}           ${chalk.dim('│')}
+${chalk.dim('│')}       ${chalk.yellow('"endTime"')}: 1703548800050,        ${chalk.dim('// Unix ms')}           ${chalk.dim('│')}
+${chalk.dim('│')}       ${chalk.yellow('"duration"')}: 50,                  ${chalk.dim('// Duration in ms')}    ${chalk.dim('│')}
+${chalk.dim('│')}       ${chalk.yellow('"attributes"')}: {                  ${chalk.dim('// Event attributes')}  ${chalk.dim('│')}
+${chalk.dim('│')}         "input.size": 42,                                        ${chalk.dim('│')}
+${chalk.dim('│')}         "output.success": true                                   ${chalk.dim('│')}
+${chalk.dim('│')}       },                                                          ${chalk.dim('│')}
+${chalk.dim('│')}       ${chalk.yellow('"status"')}: {                                                 ${chalk.dim('│')}
+${chalk.dim('│')}         "code": "OK"                    ${chalk.dim('// OK, ERROR, UNSET')}    ${chalk.dim('│')}
+${chalk.dim('│')}       },                                                          ${chalk.dim('│')}
+${chalk.dim('│')}       ${chalk.yellow('"events"')}: []                      ${chalk.dim('// Optional span events')}  ${chalk.dim('│')}
+${chalk.dim('│')}     }                                                              ${chalk.dim('│')}
+${chalk.dim('│')}   ]                                                                ${chalk.dim('│')}
+${chalk.dim('│')} }                                                                  ${chalk.dim('│')}
+${chalk.dim('└────────────────────────────────────────────────────────────────────┘')}
+
+${chalk.bold('Field Descriptions:')}
+
+${chalk.cyan('exportedAt')} ${chalk.dim('(string, required)')}
+  ISO 8601 timestamp when the file was exported
+
+${chalk.cyan('serviceName')} ${chalk.dim('(string, required)')}
+  Name of the service/test suite that generated these spans
+
+${chalk.cyan('spanCount')} ${chalk.dim('(number, required)')}
+  Total number of spans in this execution
+
+${chalk.cyan('spans')} ${chalk.dim('(array, required)')}
+  Array of span objects containing OTEL trace data
+
+${chalk.bold('Span Object Fields:')}
+
+${chalk.cyan('traceId')} ${chalk.dim('(string, 32 hex chars)')}
+  Unique identifier for the entire trace
+
+${chalk.cyan('spanId')} ${chalk.dim('(string, 16 hex chars)')}
+  Unique identifier for this specific span
+
+${chalk.cyan('parentSpanId')} ${chalk.dim('(string | null)')}
+  Parent span ID, or null for root span
+
+${chalk.cyan('name')} ${chalk.dim('(string)')}
+  Descriptive name for the operation
+
+${chalk.cyan('kind')} ${chalk.dim('(string)')}
+  Span kind: INTERNAL, CLIENT, SERVER, PRODUCER, CONSUMER
+
+${chalk.cyan('startTime')} ${chalk.dim('(number)')}
+  Unix timestamp in milliseconds when span started
+
+${chalk.cyan('endTime')} ${chalk.dim('(number)')}
+  Unix timestamp in milliseconds when span ended
+
+${chalk.cyan('duration')} ${chalk.dim('(number)')}
+  Duration in milliseconds (endTime - startTime)
+
+${chalk.cyan('attributes')} ${chalk.dim('(object)')}
+  Key-value pairs of event attributes (validated against canvas schema)
+
+${chalk.cyan('status')} ${chalk.dim('(object)')}
+  Status code (OK, ERROR, UNSET) and optional message
+
+${chalk.cyan('events')} ${chalk.dim('(array)')}
+  Optional array of timestamped events within the span
+
+${chalk.bold('Generation:')}
+  Set up test infrastructure with OTEL exporters that write to __executions__/
+  See: docs/guides/adding-opentelemetry-to-tests.md
+
+${chalk.bold('Validation:')}
+  ${chalk.cyan('npx @principal-ai/principal-view-cli validate-execution <file>')}
+`,
+    examples: `
+${chalk.bold.cyan('Complete File Examples')}
+${chalk.dim('═'.repeat(70))}
+
+${chalk.bold('Example 1: Data Validator Canvas')}
+${chalk.dim('─'.repeat(70))}
+${chalk.yellow('.principal-views/data-validator.otel.canvas')}
+
+{
+  "nodes": [
+    {
+      "id": "validation-started",
+      "type": "text",
+      "text": "# validation.started\\n\\nEmitted when validation begins",
+      "x": 0, "y": 0, "width": 200, "height": 100,
+      "pv": {
+        "otelEvent": {
+          "name": "validation.started",
+          "attributes": {
+            "required": ["input.recordCount"],
+            "optional": ["input.source"]
+          }
+        }
+      }
+    },
+    {
+      "id": "validation-complete",
+      "type": "text",
+      "text": "# validation.complete\\n\\nEmitted when validation succeeds",
+      "x": 250, "y": 0, "width": 200, "height": 100,
+      "pv": {
+        "otelEvent": {
+          "name": "validation.complete",
+          "attributes": {
+            "required": ["result.validCount", "result.invalidCount"],
+            "optional": ["duration.ms"]
+          }
+        }
+      }
+    },
+    {
+      "id": "validation-error",
+      "type": "text",
+      "text": "# validation.error\\n\\nEmitted when validation fails",
+      "x": 500, "y": 0, "width": 200, "height": 100,
+      "pv": {
+        "otelEvent": {
+          "name": "validation.error",
+          "attributes": {
+            "required": ["error.type", "error.message"],
+            "optional": ["error.stage"]
+          }
+        }
+      }
+    }
+  ],
+  "edges": [],
+  "pv": {
+    "name": "Data Validator",
+    "version": "1.0.0"
+  }
+}
+
+${chalk.bold('Example 2: Narrative Scenarios')}
+${chalk.dim('─'.repeat(70))}
+${chalk.yellow('.principal-views/data-validator.narrative.json')}
+
+{
+  "name": "Data Validator",
+  "description": "Validates data records against defined schemas",
+  "scenarios": [
+    {
+      "priority": 1,
+      "condition": "events[?name=='validation.complete']",
+      "template": {
+        "summary": "✅ Validated {{result.validCount}} records successfully",
+        "details": [
+          "🔍 Started validation",
+          "📊 Processed {{input.recordCount}} records",
+          "✅ {{result.validCount}} valid",
+          "❌ {{result.invalidCount}} invalid"
+        ]
+      }
+    },
+    {
+      "priority": 2,
+      "condition": "events[?name=='validation.error']",
+      "template": {
+        "summary": "❌ Validation failed: {{error.message}}",
+        "details": [
+          "🔍 Started validation",
+          "💥 Error occurred: {{error.message}}",
+          "🏷️  Error type: {{error.type}}"
+        ]
+      }
+    },
+    {
+      "priority": 999,
+      "condition": "true",
+      "template": {
+        "summary": "📋 Validation execution captured",
+        "details": [
+          "📦 Captured {{spans.length}} events",
+          "⏱️  Duration: {{duration.ms}}ms"
+        ]
+      }
+    }
+  ]
+}
+
+${chalk.bold('Example 3: Execution File')}
+${chalk.dim('─'.repeat(70))}
+${chalk.yellow('__executions__/data-validator.otel.json')}
+
+{
+  "exportedAt": "2025-01-21T10:30:45.123Z",
+  "serviceName": "my-app-tests",
+  "spanCount": 3,
+  "spans": [
+    {
+      "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
+      "spanId": "00f067aa0ba902b7",
+      "parentSpanId": null,
+      "name": "test:data-validator",
+      "kind": "INTERNAL",
+      "startTime": 1703548800000,
+      "endTime": 1703548800150,
+      "duration": 150,
+      "attributes": {
+        "test.name": "data validator success case"
+      },
+      "status": { "code": "OK" },
+      "events": []
+    },
+    {
+      "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
+      "spanId": "abc123def4567890",
+      "parentSpanId": "00f067aa0ba902b7",
+      "name": "validation.started",
+      "kind": "INTERNAL",
+      "startTime": 1703548800010,
+      "endTime": 1703548800015,
+      "duration": 5,
+      "attributes": {
+        "input.recordCount": 100,
+        "input.source": "test-data.csv"
+      },
+      "status": { "code": "OK" },
+      "events": []
+    },
+    {
+      "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
+      "spanId": "def789abc1234567",
+      "parentSpanId": "00f067aa0ba902b7",
+      "name": "validation.complete",
+      "kind": "INTERNAL",
+      "startTime": 1703548800140,
+      "endTime": 1703548800145,
+      "duration": 5,
+      "attributes": {
+        "result.validCount": 95,
+        "result.invalidCount": 5,
+        "duration.ms": 130
+      },
+      "status": { "code": "OK" },
+      "events": []
+    }
+  ]
+}
+
+${chalk.bold('Next Steps:')}
+  ${chalk.cyan('npx @principal-ai/principal-view-cli validate')}          Validate canvas
+  ${chalk.cyan('npx @principal-ai/principal-view-cli narrative validate')} Validate narratives
+  ${chalk.cyan('npx @principal-ai/principal-view-cli validate-execution')}  Validate execution
+`,
+};
+export function createFormatsCommand() {
+    const command = new Command('formats');
+    command
+        .description('Display documentation about file formats')
+        .argument('[section]', 'Section to display: overview, canvas, narrative, execution, examples')
+        .action((section) => {
+        const validSections = Object.keys(FORMAT_SECTIONS);
+        if (!section) {
+            console.log(FORMAT_SECTIONS.overview);
+            return;
+        }
+        const normalizedSection = section.toLowerCase();
+        if (!validSections.includes(normalizedSection)) {
+            console.log(chalk.red(`Unknown section: ${section}`));
+            console.log(`Valid sections: ${validSections.join(', ')}`);
+            process.exit(1);
+        }
+        console.log(FORMAT_SECTIONS[normalizedSection]);
+    });
+    return command;
+}

package/dist/commands/validate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/commands/validate.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAunCpC,wBAAgB,qBAAqB,IAAI,OAAO,CAsH/C"}
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/commands/validate.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA+pCpC,wBAAgB,qBAAqB,IAAI,OAAO,CAiI/C"}

package/dist/commands/validate.js

@@ -396,8 +396,9 @@ function hasOtelFeatures(canvas) {
  * - Edge types reference defined types in pv.edgeTypes or library.edgeComponents
  * - Node types reference defined types in pv.nodeTypes or library.nodeComponents
  * - Canvas has pv extension with name and version
+ * - OTEL nodes have source file references and the files exist
  */
-function validateCanvas(canvas, filePath, library) {
+function validateCanvas(canvas, filePath, library, repositoryPath) {
     const issues = [];
     if (!canvas || typeof canvas !== 'object') {
         issues.push({ type: 'error', message: 'Canvas must be an object' });
@@ -633,6 +634,37 @@ function validateCanvas(canvas, filePath, library) {
                 if (nodePv.otel && typeof nodePv.otel === 'object') {
                     checkUnknownFields(nodePv.otel, ALLOWED_CANVAS_FIELDS.nodePvOtel, `${nodePath}.pv.otel`, issues);
                 }
+                // Validate source file references for OTEL event nodes
+                const hasOtelFeatures = nodePv.otel !== undefined || nodePv.events !== undefined;
+                if (hasOtelFeatures) {
+                    // OTEL nodes must have at least one source file reference
+                    if (!Array.isArray(nodePv.sources) || nodePv.sources.length === 0) {
+                        issues.push({
+                            type: 'error',
+                            message: `Node "${nodeLabel}" has OTEL features but is missing required "pv.sources" field`,
+                            path: `${nodePath}.pv.sources`,
+                            suggestion: 'Add at least one source file reference, e.g.: "sources": ["src/services/MyService.ts"]',
+                        });
+                    }
+                }
+                // Validate that all source files exist (if repository path is provided)
+                if (Array.isArray(nodePv.sources) && repositoryPath) {
+                    nodePv.sources.forEach((source, sourceIndex) => {
+                        if (typeof source === 'string') {
+                            // Remove glob patterns (* characters) to get the base path
+                            const cleanPath = source.replace(/\*/g, '');
+                            const fullPath = resolve(repositoryPath, cleanPath);
+                            if (!existsSync(fullPath)) {
+                                issues.push({
+                                    type: 'error',
+                                    message: `Node "${nodeLabel}" references non-existent source file: ${source}`,
+                                    path: `${nodePath}.pv.sources[${sourceIndex}]`,
+                                    suggestion: `Verify the file path is correct relative to repository root: ${repositoryPath}`,
+                                });
+                            }
+                        }
+                    });
+                }
                 if (Array.isArray(nodePv.actions)) {
                     nodePv.actions.forEach((action, actionIndex) => {
                         if (action && typeof action === 'object') {
@@ -855,7 +887,7 @@ function validateCanvas(canvas, filePath, library) {
 /**
  * Validate a single .canvas file
  */
-function validateFile(filePath, library) {
+function validateFile(filePath, library, repositoryPath) {
     const absolutePath = resolve(filePath);
     const relativePath = relative(process.cwd(), absolutePath);
     if (!existsSync(absolutePath)) {
@@ -868,7 +900,7 @@ function validateFile(filePath, library) {
     try {
         const content = readFileSync(absolutePath, 'utf8');
         const canvas = JSON.parse(content);
-        const issues = validateCanvas(canvas, relativePath, library);
+        const issues = validateCanvas(canvas, relativePath, library, repositoryPath);
         const hasErrors = issues.some((i) => i.type === 'error');
         return {
             file: relativePath,
@@ -892,6 +924,7 @@ export function createValidateCommand() {
         .argument('[files...]', 'Files or glob patterns to validate (defaults to .principal-views/*.canvas)')
         .option('-q, --quiet', 'Only output errors')
         .option('--json', 'Output results as JSON')
+        .option('-r, --repository <path>', 'Repository root path for validating source file references (defaults to current directory)')
         .action(async (files, options) => {
         try {
             // Default to .principal-views/*.canvas if no files specified
@@ -914,6 +947,10 @@ export function createValidateCommand() {
             // Load library from .principal-views directory (used for type validation)
             const principalViewsDir = resolve(process.cwd(), '.principal-views');
             const library = loadLibrary(principalViewsDir);
+            // Determine repository path for source file validation
+            const repositoryPath = options.repository
+                ? resolve(options.repository)
+                : process.cwd();
             // Validate library if present
             let libraryResult = null;
             if (library && Object.keys(library.raw).length > 0) {
@@ -926,7 +963,7 @@ export function createValidateCommand() {
                 };
             }
             // Validate all canvas files
-            const results = matchedFiles.map((f) => validateFile(f, library));
+            const results = matchedFiles.map((f) => validateFile(f, library, repositoryPath));
             // Combine results
             const allResults = libraryResult ? [libraryResult, ...results] : results;
             const validCount = allResults.filter((r) => r.isValid).length;