@principal-ai/principal-view-cli 0.1.29 → 0.1.31

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

@@ -1 +1 @@
-{"version":3,"file":"lint.d.ts","sourceRoot":"","sources":["../../src/commands/lint.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA2PpC,wBAAgB,iBAAiB,IAAI,OAAO,CA6L3C"}
+{"version":3,"file":"lint.d.ts","sourceRoot":"","sources":["../../src/commands/lint.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAsUpC,wBAAgB,iBAAiB,IAAI,OAAO,CA+P3C"}

package/dist/commands/lint.js

@@ -7,7 +7,7 @@ import { resolve, relative, dirname, basename } from 'node:path';
 import chalk from 'chalk';
 import { globby } from 'globby';
 import yaml from 'js-yaml';
-import { createDefaultRulesEngine, validatePrivuConfig, mergeConfigs, getDefaultConfig, } from '@principal-ai/principal-view-core';
+import { createDefaultRulesEngine, validatePrivuConfig, mergeConfigs, getDefaultConfig, createNarrativeValidator, } from '@principal-ai/principal-view-core';
 // ============================================================================
 // Config File Loading
 // ============================================================================
@@ -116,6 +116,56 @@ function loadGraphConfig(filePath) {
         return null;
     }
 }
+/**
+ * Load a narrative template file
+ */
+function loadNarrativeTemplate(filePath) {
+    if (!existsSync(filePath)) {
+        return null;
+    }
+    try {
+        const raw = readFileSync(filePath, 'utf8');
+        const narrative = JSON.parse(raw);
+        return { narrative, raw };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Load a canvas file for narrative validation
+ */
+function loadCanvas(filePath) {
+    if (!existsSync(filePath)) {
+        return null;
+    }
+    try {
+        const content = readFileSync(filePath, 'utf8');
+        const ext = filePath.toLowerCase();
+        if (ext.endsWith('.json')) {
+            return JSON.parse(content);
+        }
+        else {
+            return yaml.load(content);
+        }
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Determine file type
+ */
+function getFileType(filePath) {
+    const name = basename(filePath).toLowerCase();
+    if (name.endsWith('.narrative.json')) {
+        return 'narrative';
+    }
+    if (name.endsWith('.canvas') || name.endsWith('.otel.canvas')) {
+        return 'canvas';
+    }
+    return 'config';
+}
 // ============================================================================
 // Output Formatting
 // ============================================================================
@@ -205,6 +255,19 @@ function formatJsonOutput(results) {
     };
 }
 // ============================================================================
+// Helper Functions
+// ============================================================================
+/**
+ * Count violations by rule ID
+ */
+function countByRule(violations) {
+    const counts = {};
+    for (const v of violations) {
+        counts[v.ruleId] = (counts[v.ruleId] || 0) + 1;
+    }
+    return counts;
+}
+// ============================================================================
 // Command Implementation
 // ============================================================================
 export function createLintCommand() {
@@ -282,15 +345,14 @@ export function createLintCommand() {
                 ignore: privuConfig.exclude || ['**/node_modules/**'],
                 expandDirectories: false,
             });
-            // Filter out library files, config files, canvas files, narrative templates, and execution artifacts
+            // Filter out library files, config files, and execution artifacts
+            // INCLUDE both canvas files and narrative templates for linting
             const configFiles = matchedFiles.filter((f) => {
                 const name = basename(f).toLowerCase();
                 const isLibraryFile = name.startsWith('library.');
                 const isConfigFile = name.startsWith('.privurc');
-                const isCanvasFile = f.toLowerCase().endsWith('.canvas');
-                const isNarrativeTemplate = name.endsWith('.narrative.json');
                 const isExecutionArtifact = f.includes('__executions__/');
-                return !isLibraryFile && !isConfigFile && !isCanvasFile && !isNarrativeTemplate && !isExecutionArtifact;
+                return !isLibraryFile && !isConfigFile && !isExecutionArtifact;
             });
             if (configFiles.length === 0) {
                 if (options.json) {
@@ -315,44 +377,108 @@ export function createLintCommand() {
                     console.log(chalk.yellow(`Warning: Could not load library from ${libraryPath}`));
                 }
             }
-            // Create rules engine
+            // Create validators
             const engine = createDefaultRulesEngine();
+            const narrativeValidator = createNarrativeValidator();
             // Lint each file
             const results = new Map();
             for (const filePath of configFiles) {
                 const absolutePath = resolve(cwd, filePath);
                 const relativePath = relative(cwd, absolutePath);
-                const loaded = loadGraphConfig(absolutePath);
-                if (!loaded) {
-                    // File couldn't be loaded - report as error
+                const fileType = getFileType(absolutePath);
+                if (fileType === 'narrative') {
+                    // Validate narrative template
+                    const loaded = loadNarrativeTemplate(absolutePath);
+                    if (!loaded) {
+                        // File couldn't be loaded - report as error
+                        results.set(relativePath, {
+                            violations: [
+                                {
+                                    ruleId: 'parse-error',
+                                    severity: 'error',
+                                    file: relativePath,
+                                    message: `Could not parse narrative file: ${filePath}`,
+                                    impact: 'File cannot be validated',
+                                    fixable: false,
+                                },
+                            ],
+                            errorCount: 1,
+                            warningCount: 0,
+                            fixableCount: 0,
+                            byCategory: { schema: 1, reference: 0, structure: 0, pattern: 0, library: 0 },
+                            byRule: { 'parse-error': 1 },
+                        });
+                        continue;
+                    }
+                    // Load the referenced canvas if it exists
+                    const canvasPath = loaded.narrative.canvas
+                        ? resolve(dirname(absolutePath), loaded.narrative.canvas)
+                        : undefined;
+                    const canvas = canvasPath ? loadCanvas(canvasPath) : undefined;
+                    // Run narrative validation
+                    const narrativeResult = await narrativeValidator.validate({
+                        narrative: loaded.narrative,
+                        narrativePath: relativePath,
+                        canvas: canvas ?? undefined,
+                        canvasPath: canvasPath ? relative(cwd, canvasPath) : undefined,
+                        basePath: dirname(absolutePath),
+                        rawContent: loaded.raw,
+                    });
+                    // Convert narrative violations to graph violations format
+                    const violations = narrativeResult.violations.map((v) => ({
+                        ruleId: v.ruleId,
+                        severity: v.severity,
+                        file: v.file,
+                        line: v.line,
+                        path: v.path,
+                        message: v.message,
+                        impact: v.impact,
+                        suggestion: v.suggestion,
+                        fixable: v.fixable,
+                    }));
                     results.set(relativePath, {
-                        violations: [
-                            {
-                                ruleId: 'parse-error',
-                                severity: 'error',
-                                file: relativePath,
-                                message: `Could not parse file: ${filePath}`,
-                                impact: 'File cannot be validated',
-                                fixable: false,
-                            },
-                        ],
-                        errorCount: 1,
-                        warningCount: 0,
-                        fixableCount: 0,
-                        byCategory: { schema: 1, reference: 0, structure: 0, pattern: 0, library: 0 },
-                        byRule: { 'parse-error': 1 },
+                        violations,
+                        errorCount: narrativeResult.errorCount,
+                        warningCount: narrativeResult.warningCount,
+                        fixableCount: narrativeResult.fixableCount,
+                        byCategory: { schema: 0, reference: 0, structure: 0, pattern: 0, library: 0 }, // Could categorize narrative rules
+                        byRule: countByRule(violations),
+                    });
+                }
+                else {
+                    // Validate canvas/graph configuration
+                    const loaded = loadGraphConfig(absolutePath);
+                    if (!loaded) {
+                        // File couldn't be loaded - report as error
+                        results.set(relativePath, {
+                            violations: [
+                                {
+                                    ruleId: 'parse-error',
+                                    severity: 'error',
+                                    file: relativePath,
+                                    message: `Could not parse file: ${filePath}`,
+                                    impact: 'File cannot be validated',
+                                    fixable: false,
+                                },
+                            ],
+                            errorCount: 1,
+                            warningCount: 0,
+                            fixableCount: 0,
+                            byCategory: { schema: 1, reference: 0, structure: 0, pattern: 0, library: 0 },
+                            byRule: { 'parse-error': 1 },
+                        });
+                        continue;
+                    }
+                    // Run linting
+                    const result = await engine.lintWithConfig(loaded.config, privuConfig, {
+                        library,
+                        configPath: relativePath,
+                        rawContent: loaded.raw,
+                        enabledRules: options.rule,
+                        disabledRules: options.ignoreRule,
                     });
-                    continue;
+                    results.set(relativePath, result);
                 }
-                // Run linting
-                const result = await engine.lintWithConfig(loaded.config, privuConfig, {
-                    library,
-                    configPath: relativePath,
-                    rawContent: loaded.raw,
-                    enabledRules: options.rule,
-                    disabledRules: options.ignoreRule,
-                });
-                results.set(relativePath, result);
             }
             // Output results
             if (options.json) {

package/dist/commands/narrative/eval.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function createEvalCommand(): Command;
+//# sourceMappingURL=eval.d.ts.map

package/dist/commands/narrative/eval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eval.d.ts","sourceRoot":"","sources":["../../../src/commands/narrative/eval.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAWpC,wBAAgB,iBAAiB,IAAI,OAAO,CA2E3C"}

package/dist/commands/narrative/eval.js

@@ -0,0 +1,76 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { readFile } from 'node:fs/promises';
+import { evaluateExpression } from '@principal-ai/principal-view-core';
+import { resolvePath, formatValue } from './utils.js';
+export function createEvalCommand() {
+    const command = new Command('eval');
+    command
+        .description('Evaluate template expression with context')
+        .argument('<expression>', 'Template expression to evaluate (e.g., {count > 5 ? \'many\' : \'few\'})')
+        .argument('[context]', 'Optional path to JSON context file')
+        .option('--context <json>', 'Inline JSON context as string')
+        .option('--json', 'Output result as JSON')
+        .action(async (expression, contextPath, options) => {
+        try {
+            let context = {};
+            // Load context from file or inline option
+            if (contextPath) {
+                const content = await readFile(resolvePath(contextPath), 'utf-8');
+                context = JSON.parse(content);
+            }
+            else if (options.context) {
+                context = JSON.parse(options.context);
+            }
+            // Remove curly braces if user included them
+            let cleanExpression = expression.trim();
+            if (cleanExpression.startsWith('{') && cleanExpression.endsWith('}')) {
+                cleanExpression = cleanExpression.slice(1, -1).trim();
+            }
+            // Evaluate expression
+            const result = evaluateExpression(cleanExpression, context);
+            if (options.json) {
+                const output = {
+                    expression: cleanExpression,
+                    context,
+                    result,
+                    type: typeof result,
+                };
+                console.log(JSON.stringify(output, null, 2));
+            }
+            else {
+                console.log(chalk.bold('\nExpression:'), chalk.cyan(`{${cleanExpression}}`));
+                if (Object.keys(context).length > 0) {
+                    console.log(chalk.bold('\nContext:'));
+                    for (const [key, value] of Object.entries(context)) {
+                        console.log(chalk.gray('  •'), `${key} = ${formatValue(value)}`);
+                    }
+                }
+                else {
+                    console.log(chalk.yellow('\nNo context provided'));
+                }
+                console.log(chalk.bold('\nResult:'), formatValue(result));
+                console.log(chalk.gray('Type:'), typeof result);
+                console.log();
+            }
+        }
+        catch (error) {
+            const errorMessage = error.message;
+            if (options.json) {
+                const output = {
+                    error: true,
+                    message: errorMessage,
+                    expression: expression,
+                };
+                console.log(JSON.stringify(output, null, 2));
+            }
+            else {
+                console.error(chalk.red('\nEvaluation Error:'), errorMessage);
+                console.error(chalk.gray('\nExpression:'), expression);
+                console.log();
+            }
+            process.exit(1);
+        }
+    });
+    return command;
+}

package/dist/commands/narrative/index.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function createNarrativeCommand(): Command;
+//# sourceMappingURL=index.d.ts.map

package/dist/commands/narrative/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/narrative/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQpC,wBAAgB,sBAAsB,IAAI,OAAO,CAahD"}

package/dist/commands/narrative/index.js

@@ -0,0 +1,19 @@
+import { Command } from 'commander';
+import { createValidateCommand } from './validate.js';
+import { createInspectCommand } from './inspect.js';
+import { createRenderCommand } from './render.js';
+import { createTestCommand } from './test.js';
+import { createEvalCommand } from './eval.js';
+import { createListCommand } from './list.js';
+export function createNarrativeCommand() {
+    const command = new Command('narrative');
+    command
+        .description('Validate, test, and debug narrative templates')
+        .addCommand(createValidateCommand())
+        .addCommand(createInspectCommand())
+        .addCommand(createRenderCommand())
+        .addCommand(createTestCommand())
+        .addCommand(createEvalCommand())
+        .addCommand(createListCommand());
+    return command;
+}

package/dist/commands/narrative/inspect.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function createInspectCommand(): Command;
+//# sourceMappingURL=inspect.d.ts.map

package/dist/commands/narrative/inspect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspect.d.ts","sourceRoot":"","sources":["../../../src/commands/narrative/inspect.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAuBpC,wBAAgB,oBAAoB,IAAI,OAAO,CAiI9C"}

package/dist/commands/narrative/inspect.js

@@ -0,0 +1,109 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { computeAggregates } from '@principal-ai/principal-view-core';
+import { loadExecution, executionToEvents, resolvePath, formatTimestamp, formatDuration, groupAttributesByPrefix, filterAttributes, countEventsByType, formatValue, capitalize, } from './utils.js';
+export function createInspectCommand() {
+    const command = new Command('inspect');
+    command
+        .description('Inspect execution file and show available attributes for templates')
+        .argument('<execution>', 'Path to .otel.json execution file')
+        .option('--events', 'Show all events')
+        .option('--aggregates', 'Show computed aggregates (default)', true)
+        .option('--json', 'Output as JSON')
+        .option('--filter <pattern>', 'Filter attributes by pattern (e.g., auth.*)')
+        .action(async (execution, options) => {
+        try {
+            const executionPath = resolvePath(execution);
+            // Load execution
+            const executionData = await loadExecution(executionPath);
+            const events = executionToEvents(executionData);
+            // Compute aggregates
+            const aggregates = computeAggregates(events);
+            // Apply filter if provided
+            const filteredAggregates = options.filter
+                ? filterAttributes(aggregates, options.filter)
+                : aggregates;
+            // Count events by type
+            const eventCounts = countEventsByType(events);
+            // Calculate time range
+            const timestamps = events.map((e) => typeof e.timestamp === 'string' ? parseInt(e.timestamp, 10) : e.timestamp);
+            const minTime = Math.min(...timestamps);
+            const maxTime = Math.max(...timestamps);
+            const duration = maxTime - minTime;
+            if (options.json) {
+                const output = {
+                    file: execution,
+                    summary: {
+                        eventCount: events.length,
+                        spanCount: executionData.spans.length,
+                        timeRange: {
+                            start: minTime,
+                            end: maxTime,
+                            duration: duration,
+                        },
+                        status: executionData.metadata?.status || 'UNKNOWN',
+                    },
+                    eventTypes: Array.from(eventCounts.entries()).map(([name, count]) => ({
+                        name,
+                        count,
+                    })),
+                    attributes: filteredAggregates,
+                };
+                if (options.events) {
+                    output.events = events.map((e) => ({
+                        name: e.name,
+                        timestamp: e.timestamp,
+                        attributes: e.attributes,
+                    }));
+                }
+                console.log(JSON.stringify(output, null, 2));
+            }
+            else {
+                // Text output
+                console.log(chalk.bold(`\nInspecting: ${execution}\n`));
+                // Execution Summary
+                console.log(chalk.bold('Execution Summary:'));
+                console.log('━'.repeat(60));
+                console.log(chalk.gray('  • Total Events:'), events.length);
+                console.log(chalk.gray('  • Total Spans:'), executionData.spans.length);
+                console.log(chalk.gray('  • Time Range:'), `${formatTimestamp(minTime)} → ${formatTimestamp(maxTime)} (${formatDuration(duration)})`);
+                const status = executionData.metadata?.status || 'UNKNOWN';
+                const statusColor = status === 'OK' ? chalk.green : chalk.red;
+                console.log(chalk.gray('  • Status:'), statusColor(status));
+                // Event Types
+                console.log(chalk.bold('\nEvent Types:'));
+                console.log('━'.repeat(60));
+                for (const [name, count] of eventCounts) {
+                    console.log(chalk.gray('  •'), `${name} (${count})`);
+                }
+                // Available Attributes
+                console.log(chalk.bold('\nAvailable Attributes (for templates):'));
+                console.log('━'.repeat(60));
+                const grouped = groupAttributesByPrefix(filteredAggregates);
+                for (const [prefix, attrs] of Object.entries(grouped)) {
+                    console.log(chalk.bold(`\n${capitalize(prefix)}:`));
+                    for (const [key, value] of Object.entries(attrs)) {
+                        console.log(chalk.gray('  •'), `${key}: ${formatValue(value)}`);
+                    }
+                }
+                // Show events if requested
+                if (options.events) {
+                    console.log(chalk.bold('\nEvents:'));
+                    console.log('━'.repeat(60));
+                    for (const event of events) {
+                        console.log(chalk.cyan(`\n[${formatTimestamp(typeof event.timestamp === 'string' ? parseInt(event.timestamp, 10) : event.timestamp)}]`), chalk.bold(event.name));
+                        for (const [key, value] of Object.entries(event.attributes || {})) {
+                            console.log(chalk.gray('  •'), `${key}: ${formatValue(value)}`);
+                        }
+                    }
+                }
+                console.log();
+            }
+        }
+        catch (error) {
+            console.error(chalk.red('Error:'), error.message);
+            process.exit(1);
+        }
+    });
+    return command;
+}

package/dist/commands/narrative/list.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function createListCommand(): Command;
+//# sourceMappingURL=list.d.ts.map

package/dist/commands/narrative/list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../../src/commands/narrative/list.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAYpC,wBAAgB,iBAAiB,IAAI,OAAO,CA6G3C"}

package/dist/commands/narrative/list.js

@@ -0,0 +1,101 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { access } from 'node:fs/promises';
+import { resolve, dirname, join } from 'node:path';
+import { globby } from 'globby';
+import { loadNarrative } from './utils.js';
+export function createListCommand() {
+    const command = new Command('list');
+    command
+        .description('List all narrative files in project')
+        .argument('[dir]', 'Directory to search (default: .principal-views/)')
+        .option('--json', 'Output as JSON')
+        .option('--show-canvas', 'Show linked canvas files')
+        .action(async (dir, options) => {
+        try {
+            const searchDir = dir || '.principal-views';
+            const searchPath = resolve(process.cwd(), searchDir);
+            // Find all .narrative.json files
+            const files = await globby('**/*.narrative.json', {
+                cwd: searchPath,
+                ignore: ['node_modules/**', '.git/**', '__executions__/**'],
+            });
+            // Load each narrative and check canvas existence
+            const narratives = await Promise.all(files.map(async (file) => {
+                const fullPath = join(searchPath, file);
+                const narrative = await loadNarrative(fullPath);
+                let canvasExists;
+                if (options.showCanvas && narrative.canvas) {
+                    const narrativeDir = dirname(fullPath);
+                    const canvasPath = resolve(narrativeDir, narrative.canvas);
+                    try {
+                        await access(canvasPath);
+                        canvasExists = true;
+                    }
+                    catch {
+                        canvasExists = false;
+                    }
+                }
+                const defaultCount = narrative.scenarios.filter((s) => s.condition.default).length;
+                return {
+                    file: join(searchDir, file),
+                    canvas: narrative.canvas,
+                    canvasExists,
+                    scenarioCount: narrative.scenarios.length,
+                    defaultCount,
+                    mode: narrative.mode,
+                    name: narrative.name,
+                };
+            }));
+            if (options.json) {
+                const output = {
+                    searchDir,
+                    count: narratives.length,
+                    narratives: narratives.map((n) => ({
+                        file: n.file,
+                        name: n.name,
+                        canvas: n.canvas,
+                        canvasExists: n.canvasExists,
+                        scenarios: n.scenarioCount,
+                        defaultScenarios: n.defaultCount,
+                        mode: n.mode,
+                    })),
+                };
+                console.log(JSON.stringify(output, null, 2));
+            }
+            else {
+                console.log(chalk.bold('\nNarrative Templates:'));
+                console.log('━'.repeat(60));
+                if (narratives.length === 0) {
+                    console.log(chalk.yellow(`\nNo narrative templates found in ${searchDir}`));
+                    console.log();
+                    return;
+                }
+                for (const narrative of narratives) {
+                    console.log(chalk.bold(`\n${narrative.file}`));
+                    if (narrative.name) {
+                        console.log(chalk.gray(`  Name: ${narrative.name}`));
+                    }
+                    if (options.showCanvas && narrative.canvas) {
+                        const status = narrative.canvasExists
+                            ? chalk.green('✓')
+                            : chalk.red('✗');
+                        console.log(chalk.gray(`  Canvas: ${narrative.canvas} ${status}`));
+                    }
+                    else if (narrative.canvas) {
+                        console.log(chalk.gray(`  Canvas: ${narrative.canvas}`));
+                    }
+                    console.log(chalk.gray(`  Scenarios: ${narrative.scenarioCount} (${narrative.defaultCount} default)`));
+                    console.log(chalk.gray(`  Mode: ${narrative.mode}`));
+                }
+                console.log(chalk.bold(`\nFound ${narratives.length} narrative template(s)`));
+                console.log();
+            }
+        }
+        catch (error) {
+            console.error(chalk.red('Error:'), error.message);
+            process.exit(1);
+        }
+    });
+    return command;
+}

package/dist/commands/narrative/render.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function createRenderCommand(): Command;
+//# sourceMappingURL=render.d.ts.map

package/dist/commands/narrative/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../../src/commands/narrative/render.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAmBpC,wBAAgB,mBAAmB,IAAI,OAAO,CAmH7C"}