@principal-ai/principal-view-cli 0.1.13

package/README.md

@@ -0,0 +1,157 @@
+# Visual Validation CLI
+
+A command-line tool for validating and managing `.canvas` configuration files for the Visual Validation Framework.
+
+## Installation
+
+```bash
+npm install -g @principal-ai/visual-validation-cli
+```
+
+## Usage
+
+The CLI provides two command aliases: `vv` (primary) and `visual-validation`.
+
+### Commands
+
+#### `init` - Initialize Project Structure
+
+Set up a new `.vgc` folder with template files:
+
+```bash
+vv init
+vv init --name my-architecture
+vv init --force  # Overwrite existing files
+```
+
+#### `validate` - Validate Canvas Files
+
+Strict validation of `.canvas` configuration files:
+
+```bash
+vv validate                    # Validates all .vgc/*.canvas files
+vv validate path/to/file.canvas
+vv validate "**/*.canvas"      # Glob pattern
+vv validate --quiet            # Only output errors
+vv validate --json             # Output as JSON
+```
+
+**Validation checks:**
+- Required `vv` extension with name and version
+- All nodes have required fields (id, type, x, y, width, height)
+- Custom node types must have `vv.nodeType` and valid `vv.shape`
+- Edge references point to existing nodes
+- Edge types reference defined edge type definitions
+
+#### `list` (alias: `ls`) - List Canvas Files
+
+Display all canvas files in the project with metadata:
+
+```bash
+vv list
+vv ls --all     # Search all directories
+vv ls --json    # Output as JSON
+```
+
+#### `schema` - Display Format Documentation
+
+Show detailed documentation about the canvas format:
+
+```bash
+vv schema              # Overview
+vv schema nodes        # Node types, shapes, colors
+vv schema edges        # Edge properties and styles
+vv schema vv           # Visual Validation extension fields
+vv schema examples     # Complete examples
+```
+
+#### `doctor` - Configuration Health Check
+
+Check configuration staleness and validate source patterns:
+
+```bash
+vv doctor
+vv doctor --quiet        # Only show errors and warnings
+vv doctor --errors-only  # For pre-commit hooks
+vv doctor --json         # Output as JSON
+```
+
+## Canvas Format
+
+Canvas files follow the [JSON Canvas](https://jsoncanvas.org/) specification with Visual Validation extensions that maintain compatibility with standard tools like Obsidian.
+
+### Required Structure
+
+```json
+{
+  "nodes": [...],
+  "edges": [...],
+  "vv": {
+    "name": "my-architecture",
+    "version": "1.0.0"
+  }
+}
+```
+
+### Node Types
+
+**Standard types** (no additional metadata required):
+- `text` - Text content
+- `group` - Container for other nodes
+- `file` - File reference
+- `link` - URL link
+
+**Custom types** require `vv` extension:
+```json
+{
+  "id": "node-1",
+  "type": "custom",
+  "x": 0, "y": 0,
+  "width": 200, "height": 100,
+  "vv": {
+    "nodeType": "service",
+    "shape": "rectangle"
+  }
+}
+```
+
+**Available shapes:** `circle`, `rectangle`, `hexagon`, `diamond`, `custom`
+
+### Edge Types
+
+Define reusable edge styles at the canvas level:
+
+```json
+{
+  "vv": {
+    "edgeTypes": {
+      "data-flow": {
+        "style": "dashed",
+        "color": "#3498db",
+        "width": 2
+      }
+    }
+  }
+}
+```
+
+Use in edges:
+
+```json
+{
+  "id": "edge-1",
+  "fromNode": "node-1",
+  "toNode": "node-2",
+  "vv": {
+    "edgeType": "data-flow"
+  }
+}
+```
+
+## Requirements
+
+- Node.js >= 18
+
+## License
+
+MIT

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,CA2C7C"}

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('privu validate')} to check your configuration`);
+            console.log(`  4. Run ${chalk.cyan('privu doctor')} to verify source mappings`);
+        }
+        catch (error) {
+            console.error(chalk.red('Error:'), error.message);
+            process.exit(1);
+        }
+    });
+    return command;
+}

package/dist/commands/doctor.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Doctor command - Check configuration staleness and source pattern validity
+ *
+ * This command performs two types of checks:
+ * 1. Pattern validation: Ensures source patterns in .principal-views/*.yaml configs match actual files
+ * 2. Freshness check: Compares config modification times vs source file changes
+ */
+import { Command } from 'commander';
+export declare function createDoctorCommand(): Command;
+//# sourceMappingURL=doctor.d.ts.map

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

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

package/dist/commands/doctor.js

@@ -0,0 +1,274 @@
+/**
+ * Doctor command - Check configuration staleness and source pattern validity
+ *
+ * This command performs two types of checks:
+ * 1. Pattern validation: Ensures source patterns in .principal-views/*.yaml configs match actual files
+ * 2. Freshness check: Compares config modification times vs source file changes
+ */
+import { Command } from 'commander';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { resolve, relative } from 'node:path';
+import chalk from 'chalk';
+import { globby } from 'globby';
+import yaml from 'js-yaml';
+/**
+ * Format a time difference in human-readable form
+ */
+function formatTimeDiff(ms) {
+    const seconds = Math.floor(ms / 1000);
+    const minutes = Math.floor(seconds / 60);
+    const hours = Math.floor(minutes / 60);
+    const days = Math.floor(hours / 24);
+    if (days > 0)
+        return `${days} day${days > 1 ? 's' : ''}`;
+    if (hours > 0)
+        return `${hours} hour${hours > 1 ? 's' : ''}`;
+    if (minutes > 0)
+        return `${minutes} minute${minutes > 1 ? 's' : ''}`;
+    return `${seconds} second${seconds !== 1 ? 's' : ''}`;
+}
+/**
+ * Check a single .principal-views config file for staleness issues
+ */
+async function checkConfig(configPath, projectRoot) {
+    const absolutePath = resolve(configPath);
+    const relativePath = relative(projectRoot, absolutePath);
+    const issues = [];
+    const stats = {
+        nodeTypesChecked: 0,
+        patternsChecked: 0,
+        filesMatched: 0,
+        staleConfigs: 0,
+    };
+    let configName = 'Unknown';
+    try {
+        const content = readFileSync(absolutePath, 'utf8');
+        const config = yaml.load(content);
+        const configStats = statSync(absolutePath);
+        const configMtime = configStats.mtime.getTime();
+        configName = config.metadata?.name || relativePath;
+        // Check if config has nodeTypes with sources
+        if (!config.nodeTypes || Object.keys(config.nodeTypes).length === 0) {
+            issues.push({
+                type: 'info',
+                configFile: relativePath,
+                message: 'No node types defined in configuration',
+            });
+            return { configFile: relativePath, configName, issues, stats };
+        }
+        // Check each node type's source patterns
+        for (const [nodeTypeName, nodeType] of Object.entries(config.nodeTypes)) {
+            stats.nodeTypesChecked++;
+            if (!nodeType.sources || nodeType.sources.length === 0) {
+                issues.push({
+                    type: 'info',
+                    configFile: relativePath,
+                    nodeType: nodeTypeName,
+                    message: `Node type "${nodeTypeName}" has no source patterns defined`,
+                });
+                continue;
+            }
+            for (const pattern of nodeType.sources) {
+                stats.patternsChecked++;
+                // Find files matching this pattern
+                const matchedFiles = await globby(pattern, {
+                    cwd: projectRoot,
+                    gitignore: true,
+                    ignore: ['node_modules/**', 'dist/**', '.git/**'],
+                });
+                if (matchedFiles.length === 0) {
+                    // Pattern doesn't match any files - this is a warning
+                    issues.push({
+                        type: 'warning',
+                        configFile: relativePath,
+                        nodeType: nodeTypeName,
+                        message: `Source pattern "${pattern}" doesn't match any files`,
+                        details: 'This pattern may be outdated or the files may have been moved/deleted',
+                    });
+                }
+                else {
+                    stats.filesMatched += matchedFiles.length;
+                    // Check if any matched files are newer than the config
+                    let newestFile = null;
+                    let newestMtime = 0;
+                    for (const file of matchedFiles) {
+                        const filePath = resolve(projectRoot, file);
+                        try {
+                            const fileStats = statSync(filePath);
+                            const fileMtime = fileStats.mtime.getTime();
+                            if (fileMtime > newestMtime) {
+                                newestMtime = fileMtime;
+                                newestFile = file;
+                            }
+                        }
+                        catch {
+                            // File may have been deleted between glob and stat
+                        }
+                    }
+                    // Check staleness (with 5-second buffer for build tools)
+                    const STALE_THRESHOLD_MS = 5000;
+                    if (newestFile && newestMtime > configMtime + STALE_THRESHOLD_MS) {
+                        const timeDiff = newestMtime - configMtime;
+                        stats.staleConfigs++;
+                        issues.push({
+                            type: 'warning',
+                            configFile: relativePath,
+                            nodeType: nodeTypeName,
+                            message: `Config may be stale: "${newestFile}" was modified ${formatTimeDiff(timeDiff)} after the config`,
+                            details: `Pattern: ${pattern} (matched ${matchedFiles.length} file${matchedFiles.length > 1 ? 's' : ''})`,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    catch (error) {
+        issues.push({
+            type: 'error',
+            configFile: relativePath,
+            message: `Failed to parse config: ${error.message}`,
+        });
+    }
+    return { configFile: relativePath, configName, issues, stats };
+}
+export function createDoctorCommand() {
+    const command = new Command('doctor');
+    command
+        .description('Check configuration staleness and source pattern validity')
+        .option('-q, --quiet', 'Only show errors and warnings')
+        .option('--errors-only', 'Only show errors (for pre-commit hooks)')
+        .option('--json', 'Output results as JSON')
+        .option('-d, --dir <path>', 'Project directory (defaults to current directory)')
+        .action(async (options) => {
+        try {
+            const projectRoot = resolve(options.dir || process.cwd());
+            const vgcDir = resolve(projectRoot, '.principal-views');
+            if (!existsSync(vgcDir)) {
+                if (options.json) {
+                    console.log(JSON.stringify({ error: 'No .principal-views directory found', results: [] }));
+                }
+                else {
+                    console.log(chalk.yellow('No .principal-views directory found.'));
+                    console.log(chalk.dim('Run "privu init" to create a configuration.'));
+                }
+                return;
+            }
+            // Find all .yaml config files
+            const configFiles = await globby(['*.yaml', '*.yml'], {
+                cwd: vgcDir,
+                absolute: true,
+                ignore: ['README.md'],
+            });
+            if (configFiles.length === 0) {
+                if (options.json) {
+                    console.log(JSON.stringify({ error: 'No config files found in .principal-views', results: [] }));
+                }
+                else {
+                    console.log(chalk.yellow('No configuration files found in .principal-views/'));
+                }
+                return;
+            }
+            // Check each config
+            const results = [];
+            for (const configFile of configFiles) {
+                const result = await checkConfig(configFile, projectRoot);
+                results.push(result);
+            }
+            // Aggregate stats
+            const totalStats = results.reduce((acc, r) => ({
+                nodeTypesChecked: acc.nodeTypesChecked + r.stats.nodeTypesChecked,
+                patternsChecked: acc.patternsChecked + r.stats.patternsChecked,
+                filesMatched: acc.filesMatched + r.stats.filesMatched,
+                staleConfigs: acc.staleConfigs + r.stats.staleConfigs,
+            }), { nodeTypesChecked: 0, patternsChecked: 0, filesMatched: 0, staleConfigs: 0 });
+            // Filter issues based on options
+            const filterIssues = (issues) => {
+                if (options.errorsOnly) {
+                    return issues.filter(i => i.type === 'error');
+                }
+                if (options.quiet) {
+                    return issues.filter(i => i.type === 'error' || i.type === 'warning');
+                }
+                return issues;
+            };
+            // Count issues
+            const allIssues = results.flatMap(r => filterIssues(r.issues));
+            const errorCount = allIssues.filter(i => i.type === 'error').length;
+            const warningCount = allIssues.filter(i => i.type === 'warning').length;
+            // Output results
+            if (options.json) {
+                console.log(JSON.stringify({
+                    results: results.map(r => ({
+                        ...r,
+                        issues: filterIssues(r.issues),
+                    })),
+                    summary: {
+                        configs: results.length,
+                        errors: errorCount,
+                        warnings: warningCount,
+                        ...totalStats,
+                    },
+                }, null, 2));
+            }
+            else {
+                if (!options.quiet && !options.errorsOnly) {
+                    console.log(chalk.bold(`\nChecking ${results.length} configuration file(s)...\n`));
+                }
+                for (const result of results) {
+                    const issues = filterIssues(result.issues);
+                    if (issues.length === 0 && !options.quiet && !options.errorsOnly) {
+                        console.log(chalk.green(`✓ ${result.configFile}`) + chalk.dim(` (${result.configName})`));
+                        continue;
+                    }
+                    if (issues.length > 0) {
+                        const hasErrors = issues.some(i => i.type === 'error');
+                        const icon = hasErrors ? chalk.red('✗') : chalk.yellow('⚠');
+                        console.log(`${icon} ${result.configFile}` + chalk.dim(` (${result.configName})`));
+                        for (const issue of issues) {
+                            const prefix = issue.nodeType ? `[${issue.nodeType}] ` : '';
+                            if (issue.type === 'error') {
+                                console.log(chalk.red(`  ✗ ${prefix}${issue.message}`));
+                            }
+                            else if (issue.type === 'warning') {
+                                console.log(chalk.yellow(`  ⚠ ${prefix}${issue.message}`));
+                            }
+                            else {
+                                console.log(chalk.dim(`  ℹ ${prefix}${issue.message}`));
+                            }
+                            if (issue.details) {
+                                console.log(chalk.dim(`    → ${issue.details}`));
+                            }
+                        }
+                        console.log('');
+                    }
+                }
+                // Summary
+                if (!options.errorsOnly) {
+                    console.log(chalk.dim('─'.repeat(50)));
+                    console.log(chalk.dim(`Checked ${totalStats.nodeTypesChecked} node types, ` +
+                        `${totalStats.patternsChecked} patterns, ` +
+                        `matched ${totalStats.filesMatched} files`));
+                }
+                if (errorCount > 0) {
+                    console.log(chalk.red(`\n✗ ${errorCount} error(s) found`));
+                    process.exit(1);
+                }
+                else if (warningCount > 0 && options.errorsOnly) {
+                    // In errors-only mode, don't fail on warnings
+                    process.exit(0);
+                }
+                else if (warningCount > 0) {
+                    console.log(chalk.yellow(`\n⚠ ${warningCount} warning(s) found`));
+                }
+                else if (!options.quiet && !options.errorsOnly) {
+                    console.log(chalk.green(`\n✓ All configurations are up to date`));
+                }
+            }
+        }
+        catch (error) {
+            console.error(chalk.red('Error:'), error.message);
+            process.exit(1);
+        }
+    });
+    return command;
+}

package/dist/commands/hooks.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Hooks command - Manage husky pre-commit hooks for Principal View
+ *
+ * This command installs/removes pre-commit hooks into a target project
+ * that will run `privu doctor` and `privu validate` before each commit.
+ */
+import { Command } from 'commander';
+export declare function createHooksCommand(): Command;
+//# sourceMappingURL=hooks.d.ts.map

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

@@ -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;AA0NpC,wBAAgB,kBAAkB,IAAI,OAAO,CA6F5C"}