@principal-ai/principal-studio-cli 0.35.3

package/dist/commands/init.js

@@ -0,0 +1,220 @@
+/**
+ * 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_CANVAS = {
+    nodes: [],
+    edges: [],
+};
+const HUSKY_PRE_COMMIT = `# Run principal view linting on staged .principal-views files
+npx @principal-ai/principal-studio-cli lint --quiet
+`;
+/**
+ * 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')
+        .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');
+            // 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 = `# Principal View Component Library
+version: "1.0.0"
+name: "Component Library"
+description: "Component library for Principal View visualizations"
+
+# Service resource registry
+# Define all services in this repository with their OTEL resource attributes
+# Each service configures its own resources at runtime, but declaring them here provides:
+# - Service documentation/registry
+# - Expected resource schema for validation
+# - Dev workspace trace routing
+#
+# Example:
+# resources:
+#   my-service:
+#     service.name: "my-service"
+#     service.version: "1.0.0"
+#     deployment.environment: "development"
+#
+resources: {}
+
+nodeComponents: {}
+
+edgeComponents: {}
+`;
+                writeFileSync(libraryFile, libraryYaml);
+                console.log(chalk.green(`Created library file: .principal-views/library.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('principal-view-cli lint')) {
+                                    console.log(chalk.yellow(`Husky pre-commit hook already includes principal view linting`));
+                                }
+                                else {
+                                    // Append our lint command to existing pre-commit
+                                    const updatedContent = existingContent.trimEnd() +
+                                        '\n\n# Run principal view linting\nnpx @principal-ai/principal-studio-cli lint --quiet\n';
+                                    writeFileSync(preCommitFile, updatedContent);
+                                    console.log(chalk.green(`Updated Husky pre-commit hook with principal view linting`));
+                                    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 (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('npx @principal-ai/principal-studio-cli 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('npx @principal-ai/principal-studio-cli lint')} - Lint configuration files`);
+            console.log(`  • ${chalk.cyan('npx @principal-ai/principal-studio-cli lint --json')} - Output lint results as JSON`);
+            console.log(`  • ${chalk.cyan('npx @principal-ai/principal-studio-cli validate')} - Validate canvas files`);
+            console.log(`  • ${chalk.cyan('npx @principal-ai/principal-studio-cli 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,11 @@
+/**
+ * Lint command - DEPRECATED
+ *
+ * This command has been deprecated and now calls the `validate` command internally.
+ * Please use `validate` directly for all validation needs.
+ *
+ * @deprecated Use `validate` command instead
+ */
+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;;;;;;;GAOG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,wBAAgB,iBAAiB,IAAI,OAAO,CAsE3C"}

package/dist/commands/lint.js

@@ -0,0 +1,71 @@
+/**
+ * Lint command - DEPRECATED
+ *
+ * This command has been deprecated and now calls the `validate` command internally.
+ * Please use `validate` directly for all validation needs.
+ *
+ * @deprecated Use `validate` command instead
+ */
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { spawn } from 'node:child_process';
+export function createLintCommand() {
+    const command = new Command('lint');
+    command
+        .description('DEPRECATED: Use `validate` instead. Validates Principal View files.')
+        .argument('[files...]', 'Files or glob patterns to validate (defaults to .principal-views/**/*)')
+        .option('--library <path>', 'DEPRECATED: Path to component library file (ignored)')
+        .option('-q, --quiet', 'Only output errors')
+        .option('--json', 'Output results as JSON')
+        .option('--rule <rules...>', 'DEPRECATED: Only run specific rules (ignored)')
+        .option('--ignore-rule <rules...>', 'DEPRECATED: Skip specific rules (ignored)')
+        .action(async (files, options) => {
+        // Show deprecation warning (unless JSON output or quiet mode)
+        if (!options.json && !options.quiet) {
+            console.log(chalk.yellow('⚠️  The `lint` command is deprecated and will be removed in a future version.'));
+            console.log(chalk.yellow('   Please use `validate` instead.\n'));
+        }
+        // Warn about ignored options
+        if (!options.json && !options.quiet) {
+            const ignoredOptions = [];
+            if (options.library)
+                ignoredOptions.push('--library');
+            if (options.rule)
+                ignoredOptions.push('--rule');
+            if (options.ignoreRule)
+                ignoredOptions.push('--ignore-rule');
+            if (ignoredOptions.length > 0) {
+                console.log(chalk.dim(`   Note: ${ignoredOptions.join(', ')} option(s) are no longer supported and will be ignored.\n`));
+            }
+        }
+        // Build validate command arguments
+        const validateArgs = ['validate'];
+        if (files.length > 0) {
+            validateArgs.push(...files);
+        }
+        if (options.quiet) {
+            validateArgs.push('--quiet');
+        }
+        if (options.json) {
+            validateArgs.push('--json');
+        }
+        // Spawn the validate command using the same CLI
+        const child = spawn(process.execPath, [process.argv[1], ...validateArgs], {
+            stdio: 'inherit',
+            cwd: process.cwd(),
+        });
+        child.on('close', (code) => {
+            process.exit(code ?? 0);
+        });
+        child.on('error', (error) => {
+            if (!options.json) {
+                console.error(chalk.red('Error:'), error.message);
+            }
+            else {
+                console.log(JSON.stringify({ error: error.message }));
+            }
+            process.exit(1);
+        });
+    });
+    return command;
+}

package/dist/commands/list.d.ts

@@ -0,0 +1,6 @@
+/**
+ * List command - List all .canvas files in a project
+ */
+import { Command } from 'commander';
+export declare function createListCommand(): Command;
+//# sourceMappingURL=list.d.ts.map

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

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

package/dist/commands/list.js

@@ -0,0 +1,78 @@
+/**
+ * List command - List all .canvas files in a project
+ */
+import { Command } from 'commander';
+import { readFileSync, statSync } from 'node:fs';
+import { resolve, relative } from 'node:path';
+import chalk from 'chalk';
+import { globby } from 'globby';
+function getCanvasInfo(filePath) {
+    try {
+        const absolutePath = resolve(filePath);
+        const content = readFileSync(absolutePath, 'utf8');
+        const canvas = JSON.parse(content);
+        const stats = statSync(absolutePath);
+        return {
+            file: relative(process.cwd(), absolutePath),
+            name: canvas.name || canvas.pv?.name || 'Untitled',
+            nodeCount: Array.isArray(canvas.nodes) ? canvas.nodes.length : 0,
+            edgeCount: Array.isArray(canvas.edges) ? canvas.edges.length : 0,
+            modified: stats.mtime,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export function createListCommand() {
+    const command = new Command('list');
+    command
+        .alias('ls')
+        .description('List all .canvas files in the project')
+        .option('-a, --all', 'Search all directories (not just .principal-views)')
+        .option('--json', 'Output as JSON')
+        .action(async (options) => {
+        try {
+            const patterns = options.all
+                ? ['**/*.canvas', '!node_modules/**']
+                : ['.principal-views/*.canvas'];
+            const files = await globby(patterns, {
+                expandDirectories: false,
+            });
+            if (files.length === 0) {
+                if (options.json) {
+                    console.log(JSON.stringify({ files: [] }));
+                }
+                else {
+                    console.log(chalk.yellow('No .canvas files found.'));
+                    if (!options.all) {
+                        console.log(chalk.dim('Run with --all to search all directories'));
+                    }
+                    console.log(chalk.dim('\nTo create a new canvas, run: npx @principal-ai/principal-studio-cli init'));
+                }
+                return;
+            }
+            const canvasInfos = files
+                .map(getCanvasInfo)
+                .filter((info) => info !== null)
+                .sort((a, b) => b.modified.getTime() - a.modified.getTime());
+            if (options.json) {
+                console.log(JSON.stringify({ files: canvasInfos }, null, 2));
+            }
+            else {
+                console.log(chalk.bold(`\nFound ${canvasInfos.length} canvas file(s):\n`));
+                for (const info of canvasInfos) {
+                    console.log(`  ${chalk.cyan(info.file)}`);
+                    console.log(`    ${chalk.bold(info.name)}`);
+                    console.log(chalk.dim(`    ${info.nodeCount} nodes, ${info.edgeCount} edges`));
+                    console.log('');
+                }
+            }
+        }
+        catch (error) {
+            console.error(chalk.red('Error:'), error.message);
+            process.exit(1);
+        }
+    });
+    return command;
+}

package/dist/commands/migrate-nodes.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Migrate Canvas Node Types
+ *
+ * Transforms canvas files from the legacy format (type: "text" + pv.nodeType)
+ * to the new semantic format (type: "otel-event", "otel-scope", etc.)
+ */
+import { Command } from 'commander';
+export declare function createMigrateNodesCommand(): Command;
+//# sourceMappingURL=migrate-nodes.d.ts.map

package/dist/commands/migrate-nodes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate-nodes.d.ts","sourceRoot":"","sources":["../../src/commands/migrate-nodes.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAwSpC,wBAAgB,yBAAyB,IAAI,OAAO,CA4FnD"}