@principal-ai/principal-studio-cli 0.35.3

package/README.md

@@ -0,0 +1,172 @@
+# Principal View CLI
+
+A command-line tool for validating and managing `.canvas` configuration files for the Principal View Framework.
+
+## Installation
+
+```bash
+npm install -g @principal-ai/principal-studio-cli
+```
+
+## Usage
+
+After installation, use the `principal-ai` command:
+
+```bash
+principal-ai --help
+```
+
+Or run without installing via npx:
+
+```bash
+npx @principal-ai/principal-studio-cli --help
+```
+
+### Commands
+
+#### `init` - Initialize Project Structure
+
+Set up a new `.principal-views` folder with template files:
+
+```bash
+principal-ai init
+principal-ai init --name my-architecture
+principal-ai init --force  # Overwrite existing files
+```
+
+#### `validate` - Validate Canvas Files
+
+Strict validation of `.canvas` configuration files:
+
+```bash
+principal-ai validate                    # Validates all .principal-views/*.canvas files
+principal-ai validate path/to/file.canvas
+principal-ai validate "**/*.canvas"      # Glob pattern
+principal-ai validate --quiet            # Only output errors
+principal-ai validate --json             # Output as JSON
+```
+
+**Validation checks:**
+
+- Required `pv` extension with name and version
+- All nodes have required fields (id, type, x, y, width, height)
+- Custom node types must have `pv.nodeType` and valid `pv.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
+principal-ai list
+principal-ai ls --all     # Search all directories
+principal-ai ls --json    # Output as JSON
+```
+
+#### `schema` - Display Format Documentation
+
+Show detailed documentation about the canvas format:
+
+```bash
+principal-ai schema              # Overview
+principal-ai schema nodes        # Node types, shapes, colors
+principal-ai schema edges        # Edge properties and styles
+principal-ai schema pv           # Principal View extension fields
+principal-ai schema examples     # Complete examples
+```
+
+#### `doctor` - Configuration Health Check
+
+Check configuration staleness and validate source patterns:
+
+```bash
+principal-ai doctor
+principal-ai doctor --quiet        # Only show errors and warnings
+principal-ai doctor --errors-only  # For pre-commit hooks
+principal-ai doctor --json         # Output as JSON
+```
+
+## Canvas Format
+
+Canvas files follow the [JSON Canvas](https://jsoncanvas.org/) specification with Principal View extensions that maintain compatibility with standard tools like Obsidian.
+
+### Required Structure
+
+```json
+{
+  "nodes": [...],
+  "edges": [...],
+  "pv": {
+    "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 `pv` extension:
+
+```json
+{
+  "id": "node-1",
+  "type": "custom",
+  "x": 0,
+  "y": 0,
+  "width": 200,
+  "height": 100,
+  "pv": {
+    "nodeType": "service",
+    "shape": "rectangle"
+  }
+}
+```
+
+**Available shapes:** `circle`, `rectangle`, `hexagon`, `diamond`, `custom`
+
+### Edge Types
+
+Define reusable edge styles at the canvas level:
+
+```json
+{
+  "pv": {
+    "edgeTypes": {
+      "data-flow": {
+        "style": "dashed",
+        "color": "#3498db",
+        "width": 2
+      }
+    }
+  }
+}
+```
+
+Use in edges:
+
+```json
+{
+  "id": "edge-1",
+  "fromNode": "node-1",
+  "toNode": "node-2",
+  "pv": {
+    "edgeType": "data-flow"
+  }
+}
+```
+
+## Requirements
+
+- Node.js >= 18
+
+## License
+
+Apache-2.0

package/dist/commands/agent-session.d.ts

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

package/dist/commands/agent-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-session.d.ts","sourceRoot":"","sources":["../../src/commands/agent-session.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAWpC,wBAAgB,yBAAyB,IAAI,OAAO,CAuGnD"}

package/dist/commands/agent-session.js

@@ -0,0 +1,67 @@
+import { writeFile } from 'node:fs/promises';
+import { Command } from 'commander';
+import { accumulateEvents, buildAgentSessionFixture, collectRepositories, fetchRawEvents, listAgentSessions, normalizeEvents, normalizeEventsWithAdapter, } from '@principal-ai/subsystems-core/node';
+export function createAgentSessionCommand() {
+    const command = new Command('agent-session')
+        .description('Read agent sessions and normalize them into universal events (Cline + Codex + opencode + pi + grok)');
+    command
+        .command('list')
+        .description('List top-level sessions from all supported agents (Cline + Codex + opencode + pi + grok)')
+        .option('--db-path <path>', 'Path to opencode.db (defaults to XDG data dir)')
+        .action((options) => {
+        const sessions = listAgentSessions({ dbPath: options.dbPath });
+        process.stdout.write(JSON.stringify(sessions, null, 2) + '\n');
+    });
+    command
+        .command('fetch <session-id>')
+        .description('Fetch a session and print its normalized universal events as JSON')
+        .option('--agent <cline|codex|opencode|pi|grok>', 'Force agent detection (defaults to auto-detect)')
+        .option('--db-path <path>', 'Path to opencode.db (defaults to XDG data dir)')
+        .option('--raw', 'Output raw universal events before repo normalization')
+        .option('--view <normalized|accumulated|both>', 'Which pipeline stage to return (defaults to both)', 'both')
+        .action(async (sessionId, options) => {
+        const { agent, events } = fetchRawEvents(sessionId, {
+            agent: options.agent,
+            dbPath: options.dbPath,
+        });
+        if (options.raw) {
+            process.stdout.write(JSON.stringify({ agent, events }, null, 2) + '\n');
+            return;
+        }
+        const view = options.view ?? 'both';
+        const normalized = await normalizeEvents(events);
+        const accumulated = accumulateEvents(normalized);
+        const repos = collectRepositories(normalized);
+        const payload = { agent, sessionId, repos };
+        if (view === 'normalized' || view === 'both')
+            payload.normalized = normalized;
+        if (view === 'accumulated' || view === 'both')
+            payload.accumulated = accumulated;
+        process.stdout.write(JSON.stringify(payload, null, 2) + '\n');
+    });
+    command
+        .command('fixture <session-id>')
+        .description('Generate a frozen File City agent-session fixture JSON (Cline + Codex + opencode + pi + grok)')
+        .option('--agent <cline|codex|opencode|pi|grok>', 'Force agent detection (defaults to auto-detect)')
+        .option('--db-path <path>', 'Path to opencode.db (defaults to XDG data dir)')
+        .option('-o, --out <path>', 'Output file path (defaults to <session-id>.fixture.json)')
+        .action(async (sessionId, options) => {
+        const { agent, events, sessionMeta } = fetchRawEvents(sessionId, {
+            agent: options.agent,
+            dbPath: options.dbPath,
+        });
+        const { normalized } = await normalizeEventsWithAdapter(events, sessionMeta.workingDirectory);
+        const fixture = buildAgentSessionFixture({
+            agent,
+            sessionId,
+            sessionMeta,
+            normalizedEvents: normalized,
+            rawEventCount: events.length,
+        });
+        const outPath = options.out ?? `${sessionId}.fixture.json`;
+        await writeFile(outPath, JSON.stringify(fixture, null, 2));
+        process.stderr.write(`Wrote ${agent} fixture to ${outPath}\n`);
+        process.stdout.write(JSON.stringify(fixture.session, null, 2) + '\n');
+    });
+    return command;
+}

package/dist/commands/agent-sessions.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `principal-ai agent-sessions` — open the Agent Sessions viewer.
+ *
+ * Launches the standalone principal-studio bundle pointed straight at the Agent
+ * Sessions tab (recent opencode sessions rendered as File City). If a viewer
+ * is already running, hands the tab switch off to it via the IPC socket
+ * instead of spawning a second instance.
+ */
+import { Command } from 'commander';
+export declare function createAgentSessionsCommand(): Command;
+//# sourceMappingURL=agent-sessions.d.ts.map

package/dist/commands/agent-sessions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-sessions.d.ts","sourceRoot":"","sources":["../../src/commands/agent-sessions.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAMpC,wBAAgB,0BAA0B,IAAI,OAAO,CAiCpD"}

package/dist/commands/agent-sessions.js

@@ -0,0 +1,39 @@
+/**
+ * `principal-ai agent-sessions` — open the Agent Sessions viewer.
+ *
+ * Launches the standalone principal-studio bundle pointed straight at the Agent
+ * Sessions tab (recent opencode sessions rendered as File City). If a viewer
+ * is already running, hands the tab switch off to it via the IPC socket
+ * instead of spawning a second instance.
+ */
+import { spawn } from 'node:child_process';
+import { Command } from 'commander';
+import { handoffToRunning } from '../lib/viewer-ipc.js';
+import { resolveViewerLaunch } from './trail.js';
+const AGENT_SESSIONS_TAB_ID = 'agent-sessions';
+export function createAgentSessionsCommand() {
+    return new Command('agent-sessions')
+        .description('Open the Agent Sessions viewer — recent opencode sessions rendered as File City')
+        .option('--viewer-dir <path>', 'Path to the @principal-ai/subsystems-studio package (overrides PRINCIPAL_STUDIO_DIR)')
+        .action(async (options) => {
+        // Prefer a running viewer: switch it to the Agent Sessions tab and exit
+        // without spawning — a second instance couldn't bind the IPC socket.
+        if (await handoffToRunning({ kind: 'ACTIVATE_TAB', tabId: AGENT_SESSIONS_TAB_ID })) {
+            process.stderr.write('Agent Sessions opened in the running viewer.\n');
+            return;
+        }
+        const launch = resolveViewerLaunch(options.viewerDir);
+        const env = {
+            ...process.env,
+            PRINCIPAL_STUDIO_START_TAB: AGENT_SESSIONS_TAB_ID,
+        };
+        process.stderr.write('Launching Agent Sessions viewer…\n');
+        const child = launch.kind === 'installed'
+            ? spawn(launch.bin, [], { env, stdio: 'inherit' })
+            : spawn('bun', ['start'], { cwd: launch.dir, env, stdio: 'inherit' });
+        child.on('error', (err) => {
+            process.stderr.write(`Failed to launch viewer: ${err.message}\n`);
+            process.exit(1);
+        });
+    });
+}

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

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

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

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

package/dist/commands/auxiliary/index.js

@@ -0,0 +1,9 @@
+import { Command } from 'commander';
+import { createValidateCommand } from './validate.js';
+export function createAuxiliaryCommand() {
+    const command = new Command('auxiliary');
+    command
+        .description('Manage and validate the auxiliary manifest (project regions outside the OTEL surface)')
+        .addCommand(createValidateCommand());
+    return command;
+}

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

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

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

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

package/dist/commands/auxiliary/validate.js

@@ -0,0 +1,123 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { resolve } from 'node:path';
+import { readFileSync, existsSync } from 'node:fs';
+import { AuxiliaryManifestValidator, validateAreaScopeDisjoint, 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';
+const MANIFEST_RELATIVE_PATH = '.principal-views/auxiliary.manifest.json';
+export function createValidateCommand() {
+    const command = new Command('validate');
+    command
+        .description('Validate auxiliary.manifest.json against the filesystem and scope paths')
+        .option('--json', 'Output as JSON')
+        .option('-d, --dir <path>', 'Project directory (default: cwd)')
+        .action(async (options) => {
+        try {
+            const baseDir = options.dir || process.cwd();
+            const manifestPath = MANIFEST_RELATIVE_PATH;
+            const manifestFullPath = resolve(baseDir, manifestPath);
+            if (!existsSync(manifestFullPath)) {
+                if (options.json) {
+                    console.log(JSON.stringify({ valid: true, manifestPresent: false, violations: [] }, null, 2));
+                }
+                else {
+                    console.log(chalk.gray(`No ${manifestPath} found — auxiliary manifest is optional, nothing to validate.`));
+                }
+                return;
+            }
+            let manifest;
+            try {
+                manifest = JSON.parse(readFileSync(manifestFullPath, 'utf-8'));
+            }
+            catch (err) {
+                console.error(chalk.red('Error:'), `Failed to parse ${manifestPath}: ${err.message}`);
+                process.exit(1);
+            }
+            const ownFileResult = await new AuxiliaryManifestValidator(new RepoNodeFileSystemAdapter()).validate({
+                manifest,
+                manifestPath,
+                basePath: baseDir,
+            });
+            // Cross-check: areas must not overlap any scope path. Discover the
+            // scopes canvas the same way `pv scopes validate` does.
+            const service = new FilesystemService(new NodeFileSystemAdapter());
+            const fileTree = await service.buildFileSystemTreeFromPath(baseDir);
+            const discovery = new CanvasDiscovery();
+            const discoveryResult = await discovery.discover(fileTree, {
+                fileReader: async (p) => readFileSync(resolve(baseDir, p), 'utf-8'),
+                includeContent: true,
+            });
+            const scopesDiscovered = discoveryResult.canvases.find((c) => c.type === 'scopes');
+            let scopesCanvas;
+            let scopesCanvasPath;
+            if (scopesDiscovered) {
+                scopesCanvasPath = scopesDiscovered.path;
+                const withContent = scopesDiscovered;
+                scopesCanvas = withContent.content;
+                if (!scopesCanvas) {
+                    try {
+                        scopesCanvas = JSON.parse(readFileSync(resolve(baseDir, scopesDiscovered.path), 'utf-8'));
+                    }
+                    catch {
+                        // leave undefined; cross-check will be skipped
+                    }
+                }
+            }
+            const crossViolations = scopesCanvas
+                ? validateAreaScopeDisjoint({ manifest, manifestPath, scopesCanvas, scopesCanvasPath })
+                : [];
+            const violations = [...ownFileResult.violations, ...crossViolations];
+            const errors = violations.filter((v) => v.severity === 'error');
+            const warnings = violations.filter((v) => v.severity === 'warn');
+            const valid = errors.length === 0;
+            if (options.json) {
+                console.log(JSON.stringify({
+                    valid,
+                    manifestPresent: true,
+                    areaCount: (manifest.areas || []).length,
+                    violations,
+                }, null, 2));
+            }
+            else {
+                console.log(chalk.bold('\nAuxiliary Manifest Validation\n'));
+                console.log('━'.repeat(60));
+                console.log(chalk.bold('\nManifest:'));
+                console.log(chalk.gray('  • File:'), manifestPath);
+                console.log(chalk.gray('  • Areas:'), (manifest.areas || []).length);
+                if (violations.length > 0) {
+                    console.log(chalk.bold('\nIssues:'));
+                    console.log('━'.repeat(60));
+                    for (const v of violations) {
+                        const label = v.severity === 'error' ? chalk.red('error') : chalk.yellow('warning');
+                        console.log(`\n${label}: ${v.message}`);
+                        if (v.path)
+                            console.log(chalk.gray(`  Location: ${v.path}`));
+                        if (v.impact)
+                            console.log(chalk.gray(`  Impact: ${v.impact}`));
+                        if (v.suggestion)
+                            console.log(chalk.cyan(`  Suggestion: ${v.suggestion}`));
+                    }
+                }
+                console.log(chalk.bold('\nSummary:'));
+                if (valid) {
+                    console.log(chalk.green('  ✓ Auxiliary manifest 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();
+            }
+            if (!valid)
+                process.exit(1);
+        }
+        catch (error) {
+            console.error(chalk.red('Error:'), error.message);
+            process.exit(1);
+        }
+    });
+    return command;
+}

package/dist/commands/collector/check.d.ts

@@ -0,0 +1,6 @@
+/**
+ * collector check - Send a test trace to verify end-to-end connectivity
+ */
+import { Command } from 'commander';
+export declare function createCheckCommand(): Command;
+//# sourceMappingURL=check.d.ts.map

package/dist/commands/collector/check.d.ts.map

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

package/dist/commands/collector/check.js

@@ -0,0 +1,153 @@
+/**
+ * collector check - Send a test trace to verify end-to-end connectivity
+ */
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { DEFAULT_COLLECTOR_PORT, checkHealth, getServiceStats, createTestTrace, sendTestTrace, } from './utils.js';
+const DEFAULT_TEST_SERVICE = 'principal-cli-test';
+export function createCheckCommand() {
+    const command = new Command('check');
+    command
+        .description('Send a test trace to verify collector connectivity')
+        .option('-p, --port <port>', `Collector port (default: ${DEFAULT_COLLECTOR_PORT})`)
+        .option('-s, --service <name>', `Service name for test trace (default: ${DEFAULT_TEST_SERVICE})`)
+        .option('--auth-token <token>', 'Bearer token if auth is required')
+        .option('--json', 'Output as JSON')
+        .action(async (options) => {
+        try {
+            const port = options.port ? parseInt(options.port, 10) : DEFAULT_COLLECTOR_PORT;
+            const serviceName = options.service || DEFAULT_TEST_SERVICE;
+            const endpoint = `http://localhost:${port}`;
+            const checks = {
+                health: { passed: false, latencyMs: 0, error: undefined },
+                sendTrace: {
+                    passed: false,
+                    traceId: undefined,
+                    latencyMs: 0,
+                    error: undefined,
+                },
+                verifyReceipt: {
+                    passed: false,
+                    foundInStats: false,
+                    error: undefined,
+                },
+            };
+            const suggestions = [];
+            // Step 1: Health check
+            const healthStart = Date.now();
+            const health = await checkHealth(port);
+            checks.health.latencyMs = Date.now() - healthStart;
+            checks.health.passed = health !== null;
+            if (!checks.health.passed) {
+                checks.health.error = 'Collector not reachable';
+                suggestions.push(`Verify the collector is running on port ${port}`);
+                suggestions.push(`Try: curl ${endpoint}/health`);
+            }
+            // Step 2: Send test trace
+            if (checks.health.passed) {
+                const trace = createTestTrace(serviceName);
+                const traceId = trace.resourceSpans[0].scopeSpans[0].spans[0].traceId;
+                const result = await sendTestTrace(port, trace, options.authToken);
+                checks.sendTrace.passed = result.success;
+                checks.sendTrace.latencyMs = result.latencyMs;
+                checks.sendTrace.traceId = traceId;
+                if (!result.success) {
+                    checks.sendTrace.error = result.error;
+                    if (result.statusCode === 401) {
+                        suggestions.push('The collector requires authentication.');
+                        suggestions.push('Use --auth-token <token> to provide a Bearer token.');
+                    }
+                    else if (result.statusCode === 403) {
+                        suggestions.push('Access forbidden. Check collector auth configuration.');
+                    }
+                    else {
+                        suggestions.push(`Failed to send trace: ${result.error}`);
+                    }
+                }
+            }
+            // Step 3: Verify trace was received
+            if (checks.sendTrace.passed) {
+                // Wait a moment for the trace to be processed
+                await new Promise((resolve) => setTimeout(resolve, 100));
+                const stats = await getServiceStats(port);
+                if (stats && stats.services[serviceName]) {
+                    checks.verifyReceipt.passed = true;
+                    checks.verifyReceipt.foundInStats = true;
+                }
+                else {
+                    checks.verifyReceipt.passed = false;
+                    checks.verifyReceipt.error = 'Trace not found in service stats';
+                    suggestions.push('The trace was accepted but not stored.');
+                    suggestions.push(`Service "${serviceName}" may not be in the allowlist.`);
+                    suggestions.push('Check collector configuration for allowedServices setting.');
+                }
+            }
+            const overallPassed = checks.health.passed && checks.sendTrace.passed && checks.verifyReceipt.passed;
+            if (options.json) {
+                console.log(JSON.stringify({
+                    checks,
+                    endpoint: `${endpoint}/v1/traces`,
+                    overallPassed,
+                    suggestions,
+                }, null, 2));
+            }
+            else {
+                console.log(chalk.bold('\nCollector Connectivity Check'));
+                console.log('━'.repeat(60));
+                // Health check
+                const healthStatus = checks.health.passed
+                    ? chalk.green('✓ healthy')
+                    : chalk.red('✗ unreachable');
+                console.log(`\n  1. Health check.............. ${healthStatus}`);
+                // Send trace
+                if (checks.health.passed) {
+                    const sendStatus = checks.sendTrace.passed
+                        ? chalk.green(`✓ accepted`) +
+                            chalk.gray(` (trace: ${checks.sendTrace.traceId?.slice(0, 8)}...)`)
+                        : chalk.red(`✗ ${checks.sendTrace.error}`);
+                    console.log(`  2. Sending test trace........ ${sendStatus}`);
+                }
+                else {
+                    console.log(`  2. Sending test trace........ ${chalk.gray('─ skipped')}`);
+                }
+                // Verify receipt
+                if (checks.sendTrace.passed) {
+                    const verifyStatus = checks.verifyReceipt.passed
+                        ? chalk.green('✓ trace found in /services/stats')
+                        : chalk.red('✗ trace not found');
+                    console.log(`  3. Verifying receipt......... ${verifyStatus}`);
+                }
+                else {
+                    console.log(`  3. Verifying receipt......... ${chalk.gray('─ skipped')}`);
+                }
+                // Latency
+                if (checks.sendTrace.passed) {
+                    console.log(`  4. Roundtrip latency......... ${checks.sendTrace.latencyMs}ms`);
+                }
+                console.log('\n' + '━'.repeat(60));
+                if (overallPassed) {
+                    console.log(chalk.green('✓ Collector is correctly configured and receiving traces.'));
+                    console.log(chalk.gray(`\nYour client should send traces to:`));
+                    console.log(`  ${endpoint}/v1/traces`);
+                }
+                else {
+                    if (suggestions.length > 0) {
+                        console.log();
+                        for (const suggestion of suggestions) {
+                            console.log(chalk.yellow(`  ${suggestion}`));
+                        }
+                    }
+                }
+                console.log();
+            }
+            if (!overallPassed) {
+                process.exit(1);
+            }
+        }
+        catch (error) {
+            console.error(chalk.red('Error:'), error.message);
+            process.exit(1);
+        }
+    });
+    return command;
+}

package/dist/commands/collector/diagnose.d.ts

@@ -0,0 +1,6 @@
+/**
+ * collector diagnose - Comprehensive diagnostic for troubleshooting collector issues
+ */
+import { Command } from 'commander';
+export declare function createDiagnoseCommand(): Command;
+//# sourceMappingURL=diagnose.d.ts.map

package/dist/commands/collector/diagnose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnose.d.ts","sourceRoot":"","sources":["../../../src/commands/collector/diagnose.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAgCpC,wBAAgB,qBAAqB,IAAI,OAAO,CAgQ/C"}