@principal-ai/principal-view-cli 0.1.13

package/dist/commands/hooks.js

@@ -0,0 +1,295 @@
+/**
+ * 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';
+import { existsSync, readFileSync, writeFileSync, unlinkSync, chmodSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import chalk from 'chalk';
+import { execSync } from 'node:child_process';
+const HUSKY_DIR = '.husky';
+const PRE_COMMIT_HOOK = 'pre-commit';
+const VV_HOOK_MARKER = '# Principal View checks';
+/**
+ * Get the Principal View pre-commit hook content
+ */
+function getVVHookContent() {
+    return `${VV_HOOK_MARKER}
+echo "Running Principal View doctor check..."
+npx privu doctor --errors-only || {
+  echo "❌ Principal View doctor check failed (errors found)"
+  echo "   Run 'privu doctor' to see details"
+  exit 1
+}
+
+echo "Running Principal View canvas validation..."
+npx privu validate --quiet 2>/dev/null || {
+  if [ $? -ne 0 ]; then
+    echo "❌ Canvas validation failed"
+    echo "   Run 'privu validate' to see details"
+    exit 1
+  fi
+}
+`;
+}
+/**
+ * Find the repository root by looking for .git directory
+ */
+function findRepoRoot(startPath) {
+    let current = resolve(startPath);
+    const root = resolve('/');
+    while (current !== root) {
+        if (existsSync(join(current, '.git'))) {
+            return current;
+        }
+        current = resolve(current, '..');
+    }
+    throw new Error('Not a git repository (or any parent up to mount point)');
+}
+/**
+ * Check if husky is installed
+ */
+function isHuskyInstalled(repoPath) {
+    const huskyPath = join(repoPath, HUSKY_DIR);
+    return existsSync(huskyPath);
+}
+/**
+ * Initialize husky if not already installed
+ */
+function initializeHusky(repoPath) {
+    if (!isHuskyInstalled(repoPath)) {
+        console.log('📦 Installing husky...');
+        try {
+            // Check if package.json exists
+            const packageJsonPath = join(repoPath, 'package.json');
+            if (!existsSync(packageJsonPath)) {
+                throw new Error('No package.json found. Please run npm init first.');
+            }
+            // Install husky
+            execSync('npm install --save-dev husky', {
+                cwd: repoPath,
+                stdio: 'inherit',
+            });
+            // Initialize husky
+            execSync('npx husky init', {
+                cwd: repoPath,
+                stdio: 'inherit',
+            });
+            // Remove the default placeholder if it exists
+            const hookPath = join(repoPath, HUSKY_DIR, PRE_COMMIT_HOOK);
+            if (existsSync(hookPath)) {
+                const content = readFileSync(hookPath, 'utf8').trim();
+                if (content === 'npm test') {
+                    // Remove the placeholder file - we'll create our own when --add is used
+                    unlinkSync(hookPath);
+                    console.log('ℹ️  Removed default husky placeholder hook');
+                }
+            }
+            console.log('✅ Husky installed and initialized');
+        }
+        catch (error) {
+            throw new Error(`Failed to initialize husky: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+}
+/**
+ * Check if pre-commit hook has PV validation
+ */
+function hasVVHook(repoPath) {
+    const hookPath = join(repoPath, HUSKY_DIR, PRE_COMMIT_HOOK);
+    if (!existsSync(hookPath)) {
+        return false;
+    }
+    const content = readFileSync(hookPath, 'utf8');
+    return content.includes(VV_HOOK_MARKER);
+}
+/**
+ * Add PV validation to pre-commit hook
+ */
+function addVVHook(repoPath) {
+    const hookPath = join(repoPath, HUSKY_DIR, PRE_COMMIT_HOOK);
+    const vvContent = getVVHookContent();
+    if (existsSync(hookPath)) {
+        // Append to existing hook
+        let existingContent = readFileSync(hookPath, 'utf8');
+        // Check if already has PV hook
+        if (existingContent.includes(VV_HOOK_MARKER)) {
+            return;
+        }
+        // Remove default husky placeholder if it's the only content
+        const trimmedContent = existingContent.trim();
+        if (trimmedContent === 'npm test') {
+            // Replace the placeholder entirely
+            writeFileSync(hookPath, vvContent, 'utf8');
+            console.log('ℹ️  Replaced default husky placeholder with Principal View checks');
+        }
+        else {
+            // Add PV hook at the end
+            const updatedContent = existingContent.trimEnd() + '\n\n' + vvContent;
+            writeFileSync(hookPath, updatedContent, 'utf8');
+        }
+    }
+    else {
+        // Create new hook file
+        writeFileSync(hookPath, vvContent, 'utf8');
+        // Make it executable
+        chmodSync(hookPath, 0o755);
+    }
+}
+/**
+ * Remove PV validation from pre-commit hook
+ */
+function removeVVHook(repoPath) {
+    const hookPath = join(repoPath, HUSKY_DIR, PRE_COMMIT_HOOK);
+    if (!existsSync(hookPath)) {
+        return;
+    }
+    const content = readFileSync(hookPath, 'utf8');
+    if (!content.includes(VV_HOOK_MARKER)) {
+        return;
+    }
+    // Split content by lines and find the PV section
+    const lines = content.split('\n');
+    const startIndex = lines.findIndex((line) => line.includes(VV_HOOK_MARKER));
+    if (startIndex === -1) {
+        return;
+    }
+    // Find the end of the PV section
+    let endIndex = lines.length - 1;
+    let inVVBlock = true;
+    let i = startIndex + 1;
+    while (i < lines.length && inVVBlock) {
+        const line = lines[i];
+        // Check if this line is part of the PV block
+        if (line &&
+            (line.includes('privu ') ||
+                line.includes('Principal View') ||
+                line.includes('echo "Running Visual') ||
+                (line.includes('exit 1') && i > startIndex && i < startIndex + 15) ||
+                (line === '}' && i > startIndex && i < startIndex + 15) ||
+                (line.trim() === '' && i === startIndex + 1))) {
+            endIndex = i;
+            i++;
+        }
+        else if (line && line.trim() === '' && i < startIndex + 15) {
+            // Empty line might be part of our block
+            endIndex = i;
+            i++;
+        }
+        else {
+            // We've reached content that's not part of our block
+            inVVBlock = false;
+        }
+    }
+    // Remove the section (inclusive)
+    lines.splice(startIndex, endIndex - startIndex + 1);
+    // Clean up extra blank lines
+    let result = lines.join('\n');
+    result = result.replace(/\n{3,}/g, '\n\n').trim();
+    if (result) {
+        writeFileSync(hookPath, result + '\n', 'utf8');
+    }
+    else {
+        // If hook is now empty, remove it
+        unlinkSync(hookPath);
+    }
+}
+export function createHooksCommand() {
+    const command = new Command('hooks');
+    command
+        .description('Manage husky pre-commit hooks for Principal View')
+        .option('-p, --path <path>', 'Repository path (defaults to current directory)')
+        .option('--add', 'Add Principal View checks to pre-commit hook')
+        .option('--remove', 'Remove Principal View checks from pre-commit hook')
+        .option('--check', 'Check if Principal View checks exist in pre-commit hook')
+        .option('--init', 'Initialize husky if not already installed')
+        .action((options) => {
+        try {
+            const repoPath = findRepoRoot(options.path || process.cwd());
+            // Check if it's a git repository
+            if (!existsSync(join(repoPath, '.git'))) {
+                console.error(chalk.red('❌ Not a git repository'));
+                process.exit(1);
+            }
+            // Handle init option
+            if (options.init) {
+                initializeHusky(repoPath);
+                return;
+            }
+            // Check if husky is installed
+            if (!isHuskyInstalled(repoPath)) {
+                if (options.check) {
+                    console.log(chalk.red('❌ Husky is not installed'));
+                    console.log('   Run "privu hooks --init" to install husky');
+                    process.exit(1);
+                }
+                else if (options.add) {
+                    console.log(chalk.red('❌ Husky is not installed'));
+                    console.log('   Run "privu hooks --init" first to install husky');
+                    process.exit(1);
+                }
+                else if (options.remove) {
+                    console.log('ℹ️  Husky is not installed');
+                    return;
+                }
+                else {
+                    console.log(chalk.red('❌ Husky is not installed in this repository'));
+                    console.log('\nTo install husky and set up Principal View hooks:');
+                    console.log('  privu hooks --init --add');
+                    process.exit(1);
+                }
+            }
+            const hasHook = hasVVHook(repoPath);
+            if (options.check) {
+                if (hasHook) {
+                    console.log(chalk.green('✅ Principal View checks found in pre-commit hook'));
+                }
+                else {
+                    console.log(chalk.red('❌ No Principal View checks in pre-commit hook'));
+                    process.exit(1);
+                }
+            }
+            else if (options.add) {
+                if (hasHook) {
+                    console.log('ℹ️  Principal View checks already exist in pre-commit hook');
+                }
+                else {
+                    addVVHook(repoPath);
+                    console.log(chalk.green('✅ Added Principal View checks to pre-commit hook'));
+                    console.log('\nPre-commit hook will now:');
+                    console.log('  • Run privu doctor to check for stale configurations');
+                    console.log('  • Validate all .canvas files');
+                }
+            }
+            else if (options.remove) {
+                if (!hasHook) {
+                    console.log('ℹ️  No Principal View checks found in pre-commit hook');
+                }
+                else {
+                    removeVVHook(repoPath);
+                    console.log(chalk.green('✅ Removed Principal View checks from pre-commit hook'));
+                }
+            }
+            else {
+                // Default action: show status
+                console.log(chalk.bold('\nPrincipal View Hooks Status\n'));
+                console.log(`Repository: ${repoPath}`);
+                console.log(`Husky: ${chalk.green('installed')}`);
+                console.log(`PV Hooks: ${hasHook ? chalk.green('configured') : chalk.yellow('not configured')}`);
+                if (hasHook) {
+                    console.log('\nUse --remove to remove or --check to verify');
+                }
+                else {
+                    console.log('\nUse --add to add or --check to verify');
+                }
+            }
+        }
+        catch (error) {
+            console.error(chalk.red('Error:'), error instanceof Error ? error.message : String(error));
+            process.exit(1);
+        }
+    });
+    return command;
+}

package/dist/commands/init.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Init command - Initialize a .principal-views folder with template files and linting setup
+ */
+import { Command } from 'commander';
+export declare function createInitCommand(): Command;
+//# sourceMappingURL=init.d.ts.map

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

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

package/dist/commands/init.js

@@ -0,0 +1,290 @@
+/**
+ * Init command - Initialize a .principal-views folder with template files and linting setup
+ */
+import { Command } from 'commander';
+import { existsSync, mkdirSync, writeFileSync, readFileSync, chmodSync } from 'node:fs';
+import { join } from 'node:path';
+import { execSync } from 'node:child_process';
+import chalk from 'chalk';
+const TEMPLATE_LIBRARY = {
+    version: '1.0.0',
+    name: 'Component Library',
+    nodeComponents: {},
+    edgeComponents: {},
+};
+const TEMPLATE_CANVAS = {
+    nodes: [],
+    edges: [],
+};
+const TEMPLATE_PRIVURC = `# Principal View Configuration Lint Rules
+# See: https://github.com/principal-ai/principal-view
+
+# File patterns to include
+include:
+  - ".principal-views/**/*.yaml"
+  - ".principal-views/**/*.yml"
+  - ".principal-views/**/*.json"
+
+# File patterns to exclude
+exclude:
+  - "**/node_modules/**"
+  - ".principal-views/library.yaml"
+
+# Path to component library (optional)
+library: ".principal-views/library.yaml"
+
+# Rule configuration
+# Severity: "off" | "warn" | "error" (or 0 | 1 | 2)
+rules:
+  # Schema rules - validate structure
+  no-unknown-fields: error
+  required-metadata: error
+  valid-node-types: error
+  valid-edge-types: error
+  valid-color-format: error
+
+  # Reference rules - check cross-references
+  connection-type-references: error
+  state-transition-references: error
+
+  # Structure rules - ensure completeness
+  minimum-node-sources:
+    - error
+    - minimum: 1
+      excludeNodeTypes: []
+  orphaned-node-types: error
+  orphaned-edge-types: error
+  unreachable-states: error
+  dead-end-states:
+    - error
+    - allowTerminalStates: true
+
+  # Pattern rules - validate regex patterns
+  valid-action-patterns:
+    - error
+    - strictMode: false
+
+  # Library rules - check against component library
+  library-node-type-match:
+    - error
+    - requireLibraryMatch: false
+`;
+const HUSKY_PRE_COMMIT = `#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+# Run principal view linting on staged .principal-views files
+privu lint --quiet
+`;
+/**
+ * Check if a command exists in PATH
+ */
+function commandExists(cmd) {
+    try {
+        execSync(`which ${cmd}`, { stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check if we're in a git repository
+ */
+function isGitRepo() {
+    try {
+        execSync('git rev-parse --is-inside-work-tree', { stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Get the git root directory
+ */
+function getGitRoot() {
+    try {
+        return execSync('git rev-parse --show-toplevel', { encoding: 'utf8' }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check if husky is already installed
+ */
+function isHuskyInstalled(gitRoot) {
+    return existsSync(join(gitRoot, '.husky'));
+}
+/**
+ * Detect package manager
+ */
+function detectPackageManager() {
+    if (existsSync('bun.lockb'))
+        return 'bun';
+    if (existsSync('pnpm-lock.yaml'))
+        return 'pnpm';
+    if (existsSync('yarn.lock'))
+        return 'yarn';
+    return 'npm';
+}
+export function createInitCommand() {
+    const command = new Command('init');
+    command
+        .description('Initialize a .principal-views folder with template files and linting setup')
+        .option('-f, --force', 'Overwrite existing files')
+        .option('-n, --name <name>', 'Name for the canvas file', 'architecture')
+        .option('--no-husky', 'Skip Husky pre-commit hook setup')
+        .option('--no-lint-config', 'Skip .privurc.yaml creation')
+        .action(async (options) => {
+        try {
+            const cwd = process.cwd();
+            const principalViewsDir = join(cwd, '.principal-views');
+            const canvasFile = join(principalViewsDir, `${options.name}.canvas`);
+            const libraryFile = join(principalViewsDir, 'library.yaml');
+            const privurcFile = join(cwd, '.privurc.yaml');
+            // Check if .principal-views directory exists
+            if (!existsSync(principalViewsDir)) {
+                mkdirSync(principalViewsDir, { recursive: true });
+                console.log(chalk.green(`Created directory: .principal-views/`));
+            }
+            // Create canvas file
+            if (existsSync(canvasFile) && !options.force) {
+                console.log(chalk.yellow(`Canvas file already exists: .principal-views/${options.name}.canvas`));
+            }
+            else {
+                writeFileSync(canvasFile, JSON.stringify(TEMPLATE_CANVAS, null, 2));
+                console.log(chalk.green(`Created canvas file: .principal-views/${options.name}.canvas`));
+            }
+            // Create library file
+            if (existsSync(libraryFile) && !options.force) {
+                console.log(chalk.yellow(`Library file already exists: .principal-views/library.yaml`));
+            }
+            else {
+                const libraryYaml = `version: "1.0.0"
+name: "Component Library"
+
+nodeComponents: {}
+
+edgeComponents: {}
+`;
+                writeFileSync(libraryFile, libraryYaml);
+                console.log(chalk.green(`Created library file: .principal-views/library.yaml`));
+            }
+            // Create .privurc.yaml config file
+            if (options.lintConfig !== false) {
+                if (existsSync(privurcFile) && !options.force) {
+                    console.log(chalk.yellow(`Config file already exists: .privurc.yaml`));
+                }
+                else {
+                    writeFileSync(privurcFile, TEMPLATE_PRIVURC);
+                    console.log(chalk.green(`Created lint config: .privurc.yaml`));
+                }
+            }
+            // Set up Husky pre-commit hook
+            let huskySetup = false;
+            if (options.husky !== false) {
+                if (!isGitRepo()) {
+                    console.log(chalk.yellow(`Skipping Husky setup: not a git repository`));
+                }
+                else {
+                    const gitRoot = getGitRoot();
+                    if (!gitRoot) {
+                        console.log(chalk.yellow(`Skipping Husky setup: could not find git root`));
+                    }
+                    else {
+                        const huskyDir = join(gitRoot, '.husky');
+                        const preCommitFile = join(huskyDir, 'pre-commit');
+                        if (isHuskyInstalled(gitRoot)) {
+                            // Husky is already installed, just add/update pre-commit hook
+                            if (existsSync(preCommitFile)) {
+                                // Check if our hook is already in the file
+                                const existingContent = readFileSync(preCommitFile, 'utf8');
+                                if (existingContent.includes('privu lint')) {
+                                    console.log(chalk.yellow(`Husky pre-commit hook already includes privu lint`));
+                                }
+                                else {
+                                    // Append our lint command to existing pre-commit
+                                    const updatedContent = existingContent.trimEnd() + '\n\n# Run principal view linting\nprivu lint --quiet\n';
+                                    writeFileSync(preCommitFile, updatedContent);
+                                    console.log(chalk.green(`Updated Husky pre-commit hook with privu lint`));
+                                    huskySetup = true;
+                                }
+                            }
+                            else {
+                                // Create new pre-commit hook
+                                writeFileSync(preCommitFile, HUSKY_PRE_COMMIT);
+                                chmodSync(preCommitFile, '755');
+                                console.log(chalk.green(`Created Husky pre-commit hook`));
+                                huskySetup = true;
+                            }
+                        }
+                        else {
+                            // Husky is not installed, try to install it
+                            const pm = detectPackageManager();
+                            const packageJsonPath = join(gitRoot, 'package.json');
+                            if (!existsSync(packageJsonPath)) {
+                                console.log(chalk.yellow(`Skipping Husky setup: no package.json found`));
+                            }
+                            else {
+                                console.log(chalk.dim(`Installing Husky...`));
+                                try {
+                                    // Install husky as dev dependency
+                                    const installCmd = {
+                                        npm: 'npm install --save-dev husky',
+                                        yarn: 'yarn add --dev husky',
+                                        pnpm: 'pnpm add --save-dev husky',
+                                        bun: 'bun add --dev husky',
+                                    }[pm];
+                                    execSync(installCmd, { stdio: 'inherit', cwd: gitRoot });
+                                    // Initialize husky
+                                    execSync('npx husky init', { stdio: 'inherit', cwd: gitRoot });
+                                    // Write our pre-commit hook
+                                    writeFileSync(preCommitFile, HUSKY_PRE_COMMIT);
+                                    chmodSync(preCommitFile, '755');
+                                    console.log(chalk.green(`Installed Husky and created pre-commit hook`));
+                                    huskySetup = true;
+                                }
+                                catch (installError) {
+                                    console.log(chalk.yellow(`Could not install Husky automatically: ${installError.message}`));
+                                    console.log(chalk.dim(`  You can install it manually: ${pm} add --dev husky && npx husky init`));
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+            console.log('');
+            console.log(chalk.bold('Setup complete!'));
+            console.log('');
+            console.log(chalk.bold('Files created:'));
+            console.log(`  • ${chalk.cyan('.principal-views/library.yaml')} - Component library definitions`);
+            console.log(`  • ${chalk.cyan(`.principal-views/${options.name}.canvas`)} - Graph canvas file`);
+            if (options.lintConfig !== false) {
+                console.log(`  • ${chalk.cyan('.privurc.yaml')} - Lint configuration`);
+            }
+            if (huskySetup) {
+                console.log(`  • ${chalk.cyan('.husky/pre-commit')} - Pre-commit hook`);
+            }
+            console.log('');
+            console.log(chalk.bold('Next steps:'));
+            console.log(`  1. Define components in ${chalk.cyan('.principal-views/library.yaml')}`);
+            console.log(`  2. Build your graph in ${chalk.cyan(`.principal-views/${options.name}.canvas`)}`);
+            console.log(`  3. Run ${chalk.cyan('privu lint')} to validate your configuration`);
+            if (huskySetup) {
+                console.log(`  4. Commits will now automatically lint .principal-views files`);
+            }
+            console.log('');
+            console.log(chalk.bold('Commands:'));
+            console.log(`  • ${chalk.cyan('privu lint')} - Lint configuration files`);
+            console.log(`  • ${chalk.cyan('privu lint --json')} - Output lint results as JSON`);
+            console.log(`  • ${chalk.cyan('privu validate')} - Validate canvas files`);
+            console.log(`  • ${chalk.cyan('privu doctor')} - Check project setup`);
+        }
+        catch (error) {
+            console.error(chalk.red('Error:'), error.message);
+            process.exit(1);
+        }
+    });
+    return command;
+}

package/dist/commands/lint.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Lint command - Lint graph configuration files using the rules engine
+ */
+import { Command } from 'commander';
+export declare function createLintCommand(): Command;
+//# sourceMappingURL=lint.d.ts.map

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

@@ -0,0 +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;AAiQpC,wBAAgB,iBAAiB,IAAI,OAAO,CA2K3C"}