@principal-ai/principal-studio-cli 0.35.3

package/dist/commands/coverage.js

@@ -0,0 +1,252 @@
+/**
+ * Coverage command - Measure telemetry coverage for canvas nodes
+ *
+ * This command analyzes .otel.canvas files and checks which implementation files
+ * contain the OpenTelemetry events documented in canvas nodes.
+ */
+import { Command } from 'commander';
+import { resolve } from 'node:path';
+import { readFile } from 'node:fs/promises';
+import chalk from 'chalk';
+import { analyzeCoverage, } from '@principal-ai/subsystems-core/node';
+import { FilesystemService, NodeFileSystemAdapter } from '@principal-ai/codebase-composition/node';
+/**
+ * Print coverage report in human-readable format
+ */
+function printCoverageReport(metrics, rootDir, options) {
+    const { verbose } = options;
+    console.log(chalk.bold('\n' + '─'.repeat(70)));
+    console.log(chalk.bold('📈 TELEMETRY COVERAGE REPORT'));
+    console.log(chalk.bold('─'.repeat(70)));
+    // Canvas files
+    console.log(chalk.bold(`\n📋 Canvas Files Analyzed: ${metrics.canvasFiles.length}`));
+    if (verbose) {
+        metrics.canvasFiles.forEach(f => console.log(chalk.dim(`   - ${f}`)));
+    }
+    // Validation errors (show first)
+    if (metrics.validationErrors && metrics.validationErrors.length > 0) {
+        console.log(chalk.red(`\n⚠️  Validation Errors (${metrics.validationErrors.length}):`));
+        metrics.validationErrors.forEach(err => {
+            console.log(chalk.yellow(`\n   Canvas: ${err.canvasPath}`));
+            console.log(chalk.dim(`   Node ID: ${err.nodeId}`));
+            if (err.status) {
+                console.log(chalk.dim(`   Status: ${err.status}`));
+            }
+            console.log(chalk.red(`   Error: ${err.error}`));
+        });
+    }
+    // Node status breakdown
+    if (metrics.nodeStatus) {
+        const ns = metrics.nodeStatus;
+        console.log(chalk.bold('\n📊 Node Status:'));
+        if (ns.missingStatusCount > 0) {
+            console.log(chalk.red(`   ⚠️  Missing Status: ${ns.missingStatusCount} nodes (must add pv.status field)`));
+        }
+        console.log(chalk.dim(`   Draft: ${ns.draftCount} nodes (design phase)`));
+        console.log(chalk.yellow(`   Approved: ${ns.approvedCount} nodes, ${ns.approvedWithFilesCount} with files specified (awaiting implementation)`));
+        console.log(chalk.green(`   Implemented: ${ns.implementedCount} nodes, ${ns.implementedWithFilesCount} with files specified`));
+    }
+    // File summary
+    console.log(chalk.bold('\n🎯 File Coverage Summary:'));
+    console.log(`   Implementation files checked: ${metrics.totalImplementationFiles}`);
+    console.log(`   Files with instrumentation: ${chalk.green(metrics.filesWithInstrumentation.toString())}`);
+    console.log(`   Files without instrumentation: ${chalk.dim((metrics.totalImplementationFiles - metrics.filesWithInstrumentation).toString())}`);
+    const coverageColor = metrics.coveragePercentage >= 80
+        ? chalk.green
+        : metrics.coveragePercentage >= 50
+            ? chalk.yellow
+            : chalk.red;
+    console.log(`   Coverage: ${coverageColor(metrics.coveragePercentage.toFixed(1) + '%')}`);
+    // Event summary
+    console.log(chalk.bold('\n📊 Event Summary:'));
+    console.log(`   Total expected events: ${metrics.totalExpectedEvents}`);
+    console.log(`   Events found: ${chalk.green(metrics.totalFoundEvents.toString())}`);
+    console.log(`   Events missing: ${chalk.red((metrics.totalExpectedEvents - metrics.totalFoundEvents).toString())}`);
+    // Package breakdown
+    if (metrics.packageCoverage && metrics.packageCoverage.length > 0) {
+        console.log(chalk.bold('\n📦 Package Breakdown:'));
+        metrics.packageCoverage.forEach(pkg => {
+            const pkgColor = pkg.coveragePercentage >= 80
+                ? chalk.green
+                : pkg.coveragePercentage >= 50
+                    ? chalk.yellow
+                    : chalk.red;
+            const extSummary = Object.entries(pkg.filesByExtension)
+                .map(([ext, count]) => `${ext}: ${count}`)
+                .join(', ');
+            console.log(chalk.cyan(`\n   ${pkg.packageName}:`));
+            console.log(chalk.dim(`     Path: ${pkg.packagePath || '(root)'}`));
+            console.log(`     Files: ${pkg.totalFiles}${extSummary ? ` (${extSummary})` : ''}`);
+            console.log(`     Instrumented: ${pkg.filesWithInstrumentation}`);
+            console.log(`     Coverage: ${pkgColor(pkg.coveragePercentage.toFixed(1) + '%')}`);
+        });
+    }
+    // Files WITHOUT instrumentation
+    const uninstrumented = metrics.fileCoverage.filter(f => !f.hasInstrumentation);
+    if (uninstrumented.length > 0) {
+        console.log(chalk.red(`\n❌ Files Missing Instrumentation (${uninstrumented.length}):`));
+        const display = verbose ? uninstrumented : uninstrumented.slice(0, 5);
+        display.forEach(file => {
+            console.log(chalk.yellow(`\n   File: ${file.filePath}`));
+            console.log(chalk.dim(`   Missing events: ${file.missingEvents.join(', ')}`));
+        });
+        if (!verbose && uninstrumented.length > 5) {
+            console.log(chalk.dim(`\n   ... and ${uninstrumented.length - 5} more (use --verbose to see all)`));
+        }
+    }
+    // Files WITH instrumentation
+    const instrumented = metrics.fileCoverage.filter(f => f.hasInstrumentation);
+    if (instrumented.length > 0) {
+        console.log(chalk.green(`\n✅ Files With Instrumentation (${instrumented.length}):`));
+        const display = verbose ? instrumented : instrumented.slice(0, 5);
+        display.forEach(file => {
+            const eventCount = file.instrumentationCount;
+            const totalEvents = file.expectedEvents.length;
+            const percentage = ((eventCount / totalEvents) * 100).toFixed(0);
+            console.log(chalk.dim(`   - ${file.filePath}: ${eventCount}/${totalEvents} events (${percentage}%)`));
+            if (verbose && file.foundEvents.length > 0) {
+                console.log(chalk.dim(`     Found: ${file.foundEvents.join(', ')}`));
+            }
+            if (verbose && file.missingEvents.length > 0) {
+                console.log(chalk.yellow(`     Missing: ${file.missingEvents.join(', ')}`));
+            }
+        });
+        if (!verbose && instrumented.length > 5) {
+            console.log(chalk.dim(`   ... and ${instrumented.length - 5} more (use --verbose to see all)`));
+        }
+    }
+    // Heat map summary (top 5 most instrumented files)
+    if (instrumented.length > 0) {
+        console.log(chalk.bold('\n🔥 Top Instrumented Files (Heat Map):'));
+        const sorted = [...instrumented].sort((a, b) => b.instrumentationCount - a.instrumentationCount);
+        const top5 = sorted.slice(0, 5);
+        top5.forEach((file, idx) => {
+            const bar = '█'.repeat(Math.ceil(file.instrumentationCount / 2));
+            console.log(chalk.cyan(`   ${idx + 1}. ${file.filePath}: ${bar} ${file.instrumentationCount} events`));
+        });
+    }
+    // Recommendations
+    console.log(chalk.bold('\n💡 Recommendations:'));
+    if (metrics.validationErrors && metrics.validationErrors.length > 0) {
+        const missingStatusErrors = metrics.validationErrors.filter(e => !e.status);
+        const otherErrors = metrics.validationErrors.filter(e => e.status);
+        if (missingStatusErrors.length > 0) {
+            console.log(chalk.red(`   🔴 ${missingStatusErrors.length} node(s) missing pv.status field - add status to track implementation lifecycle`));
+            console.log(chalk.dim('\n   📚 About the status field:'));
+            console.log(chalk.dim('      • "draft" - Design/proposal phase, not counted in coverage'));
+            console.log(chalk.dim('      • "approved" - Design finalized, ready to implement (requires pv.otel.files)'));
+            console.log(chalk.dim('      • "implemented" - Code exists with instrumentation (requires pv.otel.files)'));
+        }
+        if (otherErrors.length > 0) {
+            console.log(chalk.red(`   🔴 ${otherErrors.length} approved/implemented node(s) missing pv.otel.files`));
+        }
+    }
+    else if (metrics.totalImplementationFiles === 0) {
+        console.log(chalk.red('   🔴 No implemented nodes with pv.otel.files - mark nodes as status="implemented" and add files'));
+    }
+    else if (metrics.coveragePercentage === 0) {
+        console.log(chalk.red('   🔴 No instrumentation found - add OTEL events to files referenced in canvas'));
+    }
+    else if (metrics.coveragePercentage < 30) {
+        console.log(chalk.red('   🔴 Low coverage - add OTEL instrumentation to missing files'));
+    }
+    else if (metrics.coveragePercentage < 60) {
+        console.log(chalk.yellow('   🟡 Moderate coverage - continue instrumenting remaining files'));
+    }
+    else if (metrics.coveragePercentage < 100) {
+        console.log(chalk.green('   🟢 Good coverage - finish instrumenting remaining files'));
+    }
+    else {
+        console.log(chalk.green('   🟢 Excellent coverage - all files have instrumentation!'));
+    }
+    // Next steps
+    console.log(chalk.bold('\n📝 Next Steps:'));
+    if (metrics.validationErrors && metrics.validationErrors.length > 0) {
+        const missingStatusErrors = metrics.validationErrors.filter(e => !e.status);
+        if (missingStatusErrors.length > 0) {
+            console.log(chalk.dim(`   1. Add pv.status to the ${missingStatusErrors.length} node(s) missing it`));
+            console.log(chalk.dim(`   2. Choose based on implementation state:`));
+            console.log(chalk.dim(`      - "draft" if designing/proposing the event`));
+            console.log(chalk.dim(`      - "approved" if ready to implement`));
+            console.log(chalk.dim(`      - "implemented" if code already exists`));
+            console.log(chalk.dim(`   3. For approved/implemented, add pv.otel.files`));
+            console.log(chalk.dim(`   4. Example: { "pv": { "status": "implemented", "event": {...}, "otel": { "files": ["src/file.ts"] } } }`));
+            console.log(chalk.dim(`   5. Re-run: principal-ai coverage`));
+        }
+        else {
+            console.log(chalk.dim(`   1. Fix the ${metrics.validationErrors.length} validation error(s) above`));
+            console.log(chalk.dim(`   2. Add pv.otel.files to approved/implemented nodes`));
+            console.log(chalk.dim(`   3. Example: { "pv": { "status": "implemented", "otel": { "files": ["src/file.ts"] } } }`));
+            console.log(chalk.dim(`   4. Re-run: principal-ai coverage`));
+        }
+    }
+    else if (metrics.totalImplementationFiles === 0) {
+        console.log(chalk.dim(`   1. Mark canvas nodes with status: "draft", "approved", or "implemented"`));
+        console.log(chalk.dim(`   2. Add pv.otel.files to approved/implemented nodes`));
+        console.log(chalk.dim(`   3. Example: { "pv": { "status": "implemented", "otel": { "files": ["src/app/api/route.ts"] } } }`));
+        console.log(chalk.dim(`   4. Re-run: principal-ai coverage`));
+    }
+    else if (uninstrumented.length > 0) {
+        console.log(chalk.dim(`   1. Review the ${uninstrumented.length} uninstrumented file(s) above`));
+        console.log(chalk.dim(`   2. Add the missing OpenTelemetry events to each file`));
+        console.log(chalk.dim(`   3. Use span.addEvent('event.name', { ... }) to emit events`));
+        console.log(chalk.dim(`   4. Re-run: principal-ai coverage`));
+    }
+    else {
+        console.log(chalk.green(`   ✅ All files have instrumentation!`));
+    }
+    console.log(chalk.bold('\n' + '─'.repeat(70) + '\n'));
+}
+export function createCoverageCommand() {
+    const command = new Command('coverage');
+    command
+        .description('Measure telemetry coverage for implementation files')
+        .option('-d, --dir <path>', 'Project directory (defaults to current directory)')
+        .option('--json', 'Output results as JSON')
+        .option('-t, --threshold <percentage>', 'Minimum coverage percentage (exit with error if below)')
+        .option('-v, --verbose', 'Show all files in output')
+        .action(async (options) => {
+        try {
+            const rootDir = resolve(options.dir || process.cwd());
+            // Build FileTree and create fileReader
+            const service = new FilesystemService(new NodeFileSystemAdapter());
+            const fileTree = await service.buildFileSystemTreeFromPath(rootDir);
+            const fileReader = async (path) => readFile(resolve(rootDir, path), 'utf-8');
+            // Analyze coverage
+            const metrics = await analyzeCoverage(fileTree, fileReader);
+            // Output results
+            if (options.json) {
+                console.log(JSON.stringify(metrics, null, 2));
+            }
+            else {
+                printCoverageReport(metrics, rootDir, options);
+            }
+            // Check for validation errors
+            if (metrics.validationErrors && metrics.validationErrors.length > 0) {
+                if (!options.json) {
+                    console.error(chalk.red(`\n✗ Found ${metrics.validationErrors.length} validation error(s). Fix these before checking coverage.`));
+                }
+                process.exit(1);
+            }
+            // Check threshold
+            if (options.threshold) {
+                const threshold = parseFloat(options.threshold);
+                if (isNaN(threshold) || threshold < 0 || threshold > 100) {
+                    console.error(chalk.red('Error: Threshold must be a number between 0 and 100'));
+                    process.exit(1);
+                }
+                if (metrics.coveragePercentage < threshold) {
+                    if (!options.json) {
+                        console.error(chalk.red(`\n✗ Coverage ${metrics.coveragePercentage.toFixed(1)}% is below threshold ${threshold}%`));
+                    }
+                    process.exit(1);
+                }
+            }
+        }
+        catch (error) {
+            console.error(chalk.red('Error:'), error.message);
+            process.exit(1);
+        }
+    });
+    return command;
+}

package/dist/commands/create.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Create command - Create a new canvas file in the .principal-views folder
+ */
+import { Command } from 'commander';
+export declare function createCreateCommand(): Command;
+//# sourceMappingURL=create.d.ts.map

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

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

package/dist/commands/create.js

@@ -0,0 +1,50 @@
+/**
+ * Create command - Create a new canvas file in the .principal-views folder
+ */
+import { Command } from 'commander';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import chalk from 'chalk';
+const TEMPLATE_CANVAS = {
+    nodes: [],
+    edges: [],
+};
+export function createCreateCommand() {
+    const command = new Command('create');
+    command
+        .description('Create a new canvas file in the .principal-views folder')
+        .requiredOption('-n, --name <name>', 'Name for the canvas file (e.g., "cache-sync-architecture")')
+        .option('-f, --force', 'Overwrite existing file')
+        .action(async (options) => {
+        try {
+            const vgcDir = join(process.cwd(), '.principal-views');
+            const canvasFile = join(vgcDir, `${options.name}.canvas`);
+            // Check if .principal-views directory exists
+            if (!existsSync(vgcDir)) {
+                mkdirSync(vgcDir, { recursive: true });
+                console.log(chalk.green(`Created directory: .principal-views/`));
+            }
+            // Check if canvas file already exists
+            if (existsSync(canvasFile) && !options.force) {
+                console.error(chalk.red(`Error: Canvas file already exists: .principal-views/${options.name}.canvas`));
+                console.log(chalk.yellow(`Use ${chalk.cyan('--force')} to overwrite`));
+                process.exit(1);
+            }
+            // Create the canvas file
+            writeFileSync(canvasFile, JSON.stringify(TEMPLATE_CANVAS, null, 2));
+            console.log(chalk.green(`✓ Created canvas file: .principal-views/${options.name}.canvas`));
+            // Show next steps
+            console.log('');
+            console.log(chalk.bold('Next steps:'));
+            console.log(`  1. Open ${chalk.cyan(`.principal-views/${options.name}.canvas`)} in your editor`);
+            console.log(`  2. Add nodes and edges to define your architecture`);
+            console.log(`  3. Run ${chalk.cyan('npx @principal-ai/principal-studio-cli validate')} to check your configuration`);
+            console.log(`  4. Run ${chalk.cyan('npx @principal-ai/principal-studio-cli doctor')} to verify source mappings`);
+        }
+        catch (error) {
+            console.error(chalk.red('Error:'), error.message);
+            process.exit(1);
+        }
+    });
+    return command;
+}

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

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

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

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

package/dist/commands/events/index.js

@@ -0,0 +1,9 @@
+import { Command } from 'commander';
+import { createValidateCommand } from './validate.js';
+export function createEventsCommand() {
+    const command = new Command('events');
+    command
+        .description('Manage and validate event namespace canvases')
+        .addCommand(createValidateCommand());
+    return command;
+}

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

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

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

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

package/dist/commands/events/validate.js

@@ -0,0 +1,124 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { resolve } from 'node:path';
+import { readFileSync } from 'node:fs';
+import { EventsCanvasValidator, CanvasDiscovery, } from '@principal-ai/subsystems-core/node';
+import { FilesystemService, NodeFileSystemAdapter } from '@principal-ai/codebase-composition/node';
+import { NodeFileSystemAdapter as RepoNodeFileSystemAdapter } from '@principal-ai/repository-abstraction/node';
+export function createValidateCommand() {
+    const command = new Command('validate');
+    command
+        .description('Validate events.canvas namespace structure and event organization')
+        .option('--json', 'Output as JSON')
+        .option('-d, --dir <path>', 'Project directory (default: cwd)')
+        .action(async (options) => {
+        try {
+            const baseDir = options.dir || process.cwd();
+            // Discover events canvas
+            const service = new FilesystemService(new NodeFileSystemAdapter());
+            const fileTree = await service.buildFileSystemTreeFromPath(baseDir);
+            const discovery = new CanvasDiscovery();
+            const discoveryResult = await discovery.discover(fileTree, {
+                fileReader: async (path) => readFileSync(resolve(baseDir, path), 'utf-8'),
+                includeContent: true,
+            });
+            // Find events canvas
+            const eventsCanvas = discoveryResult.canvases.find(c => c.type === 'events');
+            let eventsCanvasContent;
+            let eventsCanvasPath;
+            if (eventsCanvas) {
+                eventsCanvasPath = eventsCanvas.path;
+                // Check if content is already loaded
+                const canvasWithContent = eventsCanvas;
+                if (canvasWithContent.content) {
+                    eventsCanvasContent = canvasWithContent.content;
+                }
+                else {
+                    // Load content if not already loaded
+                    try {
+                        const fullPath = resolve(baseDir, eventsCanvas.path);
+                        const content = readFileSync(fullPath, 'utf-8');
+                        eventsCanvasContent = JSON.parse(content);
+                    }
+                    catch {
+                        // Will be handled by validator
+                    }
+                }
+            }
+            // Validate
+            const validator = new EventsCanvasValidator(new RepoNodeFileSystemAdapter());
+            const result = await validator.validate({
+                eventsCanvas: eventsCanvasContent,
+                eventsCanvasPath,
+                basePath: baseDir,
+            });
+            // Output results
+            if (options.json) {
+                console.log(JSON.stringify({
+                    valid: result.valid,
+                    violations: result.violations,
+                    metrics: result.metrics,
+                }, null, 2));
+            }
+            else {
+                console.log(chalk.bold('\nEvents Canvas Validation\n'));
+                console.log('━'.repeat(60));
+                // Metrics summary
+                console.log(chalk.bold('\nMetrics:'));
+                console.log(chalk.gray('  • Total namespaces:'), result.metrics.totalNamespaces);
+                console.log(chalk.gray('  • Documented:'), result.metrics.documentedNamespaces.length);
+                console.log(chalk.gray('  • Total events:'), result.metrics.totalEvents);
+                console.log(chalk.gray('  • Registered:'), result.metrics.registeredEvents.length);
+                if (result.metrics.missingNamespaces.length > 0) {
+                    console.log(chalk.red('  • Missing namespaces:'), result.metrics.missingNamespaces.join(', '));
+                }
+                if (result.metrics.unregisteredEvents.length > 0) {
+                    console.log(chalk.red('  • Unregistered events:'), result.metrics.unregisteredEvents.length);
+                }
+                // Violations
+                if (result.violations.length > 0) {
+                    console.log(chalk.bold('\nIssues:'));
+                    console.log('━'.repeat(60));
+                    for (const violation of result.violations) {
+                        const label = violation.severity === 'error'
+                            ? chalk.red('error')
+                            : chalk.yellow('warning');
+                        console.log(`\n${label}: ${violation.message}`);
+                        if (violation.path) {
+                            console.log(chalk.gray(`  Location: ${violation.path}`));
+                        }
+                        if (violation.impact) {
+                            console.log(chalk.gray(`  Impact: ${violation.impact}`));
+                        }
+                        if (violation.suggestion) {
+                            console.log(chalk.cyan(`  Suggestion: ${violation.suggestion}`));
+                        }
+                    }
+                }
+                // Summary
+                const errors = result.violations.filter((v) => v.severity === 'error');
+                const warnings = result.violations.filter((v) => v.severity === 'warn');
+                console.log(chalk.bold('\nSummary:'));
+                if (result.valid) {
+                    console.log(chalk.green('  ✓ Events canvas is valid'));
+                }
+                else {
+                    console.log(chalk.red(`  ✗ ${errors.length} error(s)`));
+                }
+                if (warnings.length > 0) {
+                    console.log(chalk.yellow(`  ⚠ ${warnings.length} warning(s)`));
+                }
+                console.log();
+            }
+            // Exit with error code if validation failed
+            if (!result.valid) {
+                process.exit(1);
+            }
+        }
+        catch (error) {
+            console.error(chalk.red('Error:'), error.message);
+            process.exit(1);
+        }
+    });
+    return command;
+}

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;AAglCpC,wBAAgB,oBAAoB,IAAI,OAAO,CA6B9C"}