@principal-ai/principal-studio-cli 0.35.3

package/dist/commands/migration.js

@@ -0,0 +1,247 @@
+/**
+ * Migration command - Display the migration guide for moving from legacy flat structure to storyboards
+ */
+import { Command } from 'commander';
+import chalk from 'chalk';
+const MIGRATION_GUIDE = `
+${chalk.bold.cyan('Migration Guide: Legacy Flat Structure → Storyboards')}
+
+${chalk.bold('Overview')}
+
+This guide will help you migrate from the legacy flat structure to the new
+hierarchical storyboard structure for organizing Principal Views.
+
+${chalk.yellow('Status:')} The legacy flat structure is ${chalk.bold('fully deprecated')} as of version 1.0.0
+and will produce validation errors. Both structures are currently supported for
+backward compatibility, but the flat structure is no longer recommended and will
+be removed in v2.0.0.
+
+${chalk.bold('Why Migrate?')}
+
+${chalk.bold('Problems with Legacy Flat Structure:')}
+
+The legacy flat structure stores all files directly in .principal-views/:
+
+  .principal-views/
+    ├── checkout-flow.otel.canvas
+    ├── checkout-flow.workflow.json
+    └── __executions__/
+        ├── success-test.otel.json
+        └── error-test.otel.json
+
+${chalk.yellow('Limitations:')}
+  • Hard to associate multiple workflows with one canvas
+  • Hard to associate executions with specific workflows
+  • No clear relationship between workflow and its test executions
+  • Doesn't scale well with multiple workflows per feature area
+
+${chalk.bold('Benefits of Storyboard Structure:')}
+
+The new storyboard structure provides clear hierarchy:
+
+  .principal-views/
+    └── checkout-flow/                      # Storyboard folder
+        ├── checkout-flow.otel.canvas       # Canvas definition
+        ├── happy-path/                      # Workflow folder
+        │   ├── happy-path.workflow.json    # Workflow definition
+        │   ├── success-1.otel.json         # Execution files
+        │   └── success-2.otel.json
+        └── payment-failures/                # Another workflow
+            ├── payment-failures.workflow.json
+            ├── declined-1.otel.json
+            └── timeout-1.otel.json
+
+${chalk.green('Advantages:')}
+  • ${chalk.bold('Clear Hierarchy:')} Storyboard → Workflows → Executions
+  • ${chalk.bold('Multiple Workflows:')} Easy to have many workflow variations for one canvas
+  • ${chalk.bold('Organized Executions:')} Each workflow has its own execution files
+  • ${chalk.bold('Better Discoverability:')} Related files are co-located
+
+${chalk.bold('Migration Steps')}
+
+${chalk.bold('Step 1: Understand Your Current Structure')}
+
+First, identify what you have in your current .principal-views/ directory:
+
+  ${chalk.dim('$ ls -R .principal-views/')}
+
+Look for:
+  • Canvas files (.canvas or .otel.canvas)
+  • Workflow files (.workflow.json)
+  • Execution files (.otel.json) in __executions__/
+
+${chalk.bold('Step 2: Plan Your Storyboard Organization')}
+
+For each canvas file, decide:
+  1. What is the storyboard name? (Usually the canvas basename)
+  2. What workflows belong to this canvas?
+  3. Which execution files belong to each workflow?
+
+${chalk.bold('Step 3: Create Storyboard Folder Structure')}
+
+For each canvas:
+
+${chalk.bold('3.1. Create Storyboard Directory')}
+
+  ${chalk.dim('# Example: migrating checkout-flow.otel.canvas')}
+  ${chalk.cyan('$ mkdir -p .principal-views/checkout-flow')}
+
+${chalk.bold('3.2. Move Canvas File')}
+
+  ${chalk.cyan('$ mv .principal-views/checkout-flow.otel.canvas \\\\')}
+  ${chalk.cyan('     .principal-views/checkout-flow/checkout-flow.otel.canvas')}
+
+${chalk.bold('3.3. Create Workflow Folders')}
+
+  ${chalk.dim('# Example: creating a happy-path workflow')}
+  ${chalk.cyan('$ mkdir -p .principal-views/checkout-flow/happy-path')}
+
+${chalk.bold('3.4. Create or Move Workflow File')}
+
+If you have an existing workflow file:
+
+  ${chalk.cyan('$ mv .principal-views/checkout-flow.workflow.json \\\\')}
+  ${chalk.cyan('     .principal-views/checkout-flow/happy-path/happy-path.workflow.json')}
+
+If you need to create a new workflow file:
+
+  ${chalk.dim('{')}
+  ${chalk.dim('  "version": "1.0.0",')}
+  ${chalk.dim('  "canvas": "../checkout-flow.otel.canvas",')}
+  ${chalk.dim('  "name": "Happy Path",')}
+  ${chalk.dim('  "description": "Successful checkout flow",')}
+  ${chalk.dim('  "mode": "test",')}
+  ${chalk.dim('  "scenarios": [...]')}
+  ${chalk.dim('}')}
+
+${chalk.yellow('Important:')} The ${chalk.bold('canvas')} field must be a relative path pointing to
+the parent canvas file.
+
+${chalk.bold('3.5. Move Execution Files')}
+
+Move execution files from __executions__/ into the appropriate workflow folder:
+
+  ${chalk.cyan('$ mv .principal-views/__executions__/success-1.otel.json \\\\')}
+  ${chalk.cyan('     .principal-views/checkout-flow/happy-path/success-1.otel.json')}
+
+${chalk.bold('Step 4: Update Canvas References in Workflow Files')}
+
+Ensure all workflow files have the correct relative canvas path:
+
+  ${chalk.dim('{')}
+  ${chalk.dim('  "canvas": "../checkout-flow.otel.canvas"')}
+  ${chalk.dim('}')}
+
+The path should use ${chalk.bold('..')} to reference the parent storyboard canvas.
+
+${chalk.bold('Step 5: Cleanup Legacy Directories')}
+
+Once all files are migrated, remove the old __executions__/ directory if empty:
+
+  ${chalk.cyan('$ rmdir .principal-views/__executions__/')}
+
+${chalk.bold('Step 6: Verify Migration')}
+
+Check your new structure:
+
+  ${chalk.cyan('$ tree .principal-views/')}
+
+${chalk.bold('Complete Migration Example')}
+
+${chalk.bold('Before (Legacy Flat Structure):')}
+
+  .principal-views/
+  ├── checkout.otel.canvas
+  ├── checkout.workflow.json
+  ├── refund.workflow.json
+  └── __executions__/
+      ├── checkout-success.otel.json
+      ├── checkout-declined.otel.json
+      └── refund-full.otel.json
+
+${chalk.bold('After (Storyboard Structure):')}
+
+  .principal-views/
+  └── checkout/
+      ├── checkout.otel.canvas
+      ├── checkout-flow/
+      │   ├── checkout-flow.workflow.json
+      │   ├── checkout-success.otel.json
+      │   └── checkout-declined.otel.json
+      └── refund-flow/
+          ├── refund-flow.workflow.json
+          └── refund-full.otel.json
+
+${chalk.bold('Common Issues and Solutions')}
+
+${chalk.bold('Issue 1: Deprecation Errors')}
+
+${chalk.red('Problem:')} You see errors like:
+  "DEPRECATED: Legacy flat canvas structure is no longer supported"
+
+${chalk.green('Solution:')} Follow this migration guide to move to the storyboard
+structure immediately.
+
+${chalk.bold('Issue 2: Canvas Reference Not Found')}
+
+${chalk.red('Problem:')} Workflow files cannot find the canvas file.
+
+${chalk.green('Solution:')} Update the "canvas" field in workflow.json to use the
+correct relative path:
+  ${chalk.dim('"canvas": "../storyboard-name.otel.canvas"')}
+
+${chalk.bold('Issue 3: Executions Not Associated with Workflow')}
+
+${chalk.red('Problem:')} Execution files in the old __executions__/ directory are
+not linked to workflows.
+
+${chalk.green('Solution:')} Move execution files into the appropriate workflow folder.
+
+${chalk.bold('Best Practices')}
+
+${chalk.bold('Naming Conventions:')}
+
+  ${chalk.green('✓')} Storyboard Names: Use the feature or component name
+     Examples: checkout-flow, user-authentication
+
+  ${chalk.green('✓')} Workflow Names: Describe the scenario or test case
+     Examples: happy-path, payment-failures, edge-cases
+
+  ${chalk.green('✓')} Execution Files: Include scenario prefix or variant number
+     Examples: success-1.otel.json, declined-card-1.otel.json
+
+${chalk.bold('Timeline')}
+
+  • v0.15.0: Legacy structure shows deprecation warnings
+  • v1.0.0 (Current): Legacy structure produces validation errors
+  • v2.0.0 (Future): Legacy structure will be completely removed
+
+${chalk.bold('Getting Help')}
+
+If you encounter issues during migration:
+
+  1. Check this guide for common issues
+  2. Run ${chalk.cyan('principal-ai doctor')} to check for configuration issues
+  3. Run ${chalk.cyan('principal-ai validate')} to verify your structure
+  4. Open an issue in the repository with your current file structure
+
+${chalk.bold('Related Commands')}
+
+  ${chalk.cyan('principal-ai doctor')}     - Check for configuration staleness and issues
+  ${chalk.cyan('principal-ai validate')}   - Validate your Principal View files
+  ${chalk.cyan('principal-ai init')}       - Initialize a new .principal-views directory
+  ${chalk.cyan('principal-ai create')}     - Create new canvas or workflow files
+
+${chalk.dim('For the full detailed guide with more examples, visit:')}
+${chalk.dim('https://github.com/principal-ai/principal-view-core-library/blob/main/docs/MIGRATION_GUIDE.md')}
+`;
+export function createMigrationCommand() {
+    const command = new Command('migration');
+    command
+        .description('Display the migration guide for moving to storyboard structure')
+        .alias('migrate')
+        .action(() => {
+        console.log(MIGRATION_GUIDE);
+    });
+    return command;
+}

package/dist/commands/open-studio.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `principal-ai open-studio` — open Principal Studio.
+ *
+ * Launches the standalone principal-studio bundle with its default tabs. If
+ * Studio is already running, focuses its window via the IPC socket instead of
+ * spawning a second instance (and without switching tabs).
+ */
+import { Command } from 'commander';
+export declare function createOpenStudioCommand(): Command;
+//# sourceMappingURL=open-studio.d.ts.map

package/dist/commands/open-studio.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"open-studio.d.ts","sourceRoot":"","sources":["../../src/commands/open-studio.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,wBAAgB,uBAAuB,IAAI,OAAO,CA0BjD"}

package/dist/commands/open-studio.js

@@ -0,0 +1,32 @@
+/**
+ * `principal-ai open-studio` — open Principal Studio.
+ *
+ * Launches the standalone principal-studio bundle with its default tabs. If
+ * Studio is already running, focuses its window via the IPC socket instead of
+ * spawning a second instance (and without switching tabs).
+ */
+import { spawn } from 'node:child_process';
+import { Command } from 'commander';
+import { handoffToRunning } from '../lib/viewer-ipc.js';
+import { resolveViewerLaunch } from './trail.js';
+export function createOpenStudioCommand() {
+    return new Command('open-studio')
+        .description('Open Principal Studio (or focus it if already running)')
+        .option('--viewer-dir <path>', 'Path to the @principal-ai/subsystems-studio package (overrides PRINCIPAL_STUDIO_DIR)')
+        .action(async (options) => {
+        if (await handoffToRunning({ kind: 'FOCUS' })) {
+            process.stderr.write('Principal Studio focused.\n');
+            return;
+        }
+        const launch = resolveViewerLaunch(options.viewerDir);
+        const env = process.env;
+        process.stderr.write('Launching Principal Studio…\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 Principal Studio: ${err.message}\n`);
+            process.exit(1);
+        });
+    });
+}

package/dist/commands/opencode/fetch.d.ts

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

package/dist/commands/opencode/fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.d.ts","sourceRoot":"","sources":["../../../src/commands/opencode/fetch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAGnC,wBAAgB,kBAAkB,IAAI,OAAO,CAuB5C"}

package/dist/commands/opencode/fetch.js

@@ -0,0 +1,25 @@
+import { Command } from "commander";
+import { OpenCodeEventStore } from "@principal-ai/subsystems-core/node";
+export function createFetchCommand() {
+    const command = new Command("fetch");
+    command
+        .description("Fetch events for an opencode session and print as JSON")
+        .argument("<session-id>", "The session ID (aggregate_id) to fetch events for")
+        .option("-l, --limit <number>", "Maximum events to fetch", "10000")
+        .option("-a, --after <number>", "Sequence number to start after", "-1")
+        .option("--db-path <path>", "Path to opencode.db (defaults to XDG data dir)")
+        .action((sessionId, options) => {
+        const store = new OpenCodeEventStore({ dbPath: options.dbPath });
+        try {
+            const result = store.readAggregate(sessionId, {
+                after: options.after ? Number(options.after) : -1,
+                limit: options.limit ? Number(options.limit) : 10000,
+            });
+            process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+        }
+        finally {
+            store.close();
+        }
+    });
+    return command;
+}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/opencode/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAInC,wBAAgB,qBAAqB,IAAI,OAAO,CAS/C"}

package/dist/commands/opencode/index.js

@@ -0,0 +1,11 @@
+import { Command } from "commander";
+import { createFetchCommand } from "./fetch.js";
+import { createListSessionsCommand } from "./list-sessions.js";
+export function createOpencodeCommand() {
+    const command = new Command("opencode");
+    command
+        .description("Read events from opencode's local SQLite database")
+        .addCommand(createListSessionsCommand())
+        .addCommand(createFetchCommand());
+    return command;
+}

package/dist/commands/opencode/list-sessions.d.ts

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

package/dist/commands/opencode/list-sessions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-sessions.d.ts","sourceRoot":"","sources":["../../../src/commands/opencode/list-sessions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAGnC,wBAAgB,yBAAyB,IAAI,OAAO,CAkBnD"}

package/dist/commands/opencode/list-sessions.js

@@ -0,0 +1,20 @@
+import { Command } from "commander";
+import { OpenCodeEventStore } from "@principal-ai/subsystems-core/node";
+export function createListSessionsCommand() {
+    const command = new Command("list-sessions");
+    command
+        .description("List session IDs in the opencode database")
+        .option("--db-path <path>", "Path to opencode.db (defaults to XDG data dir)")
+        .option("--limit <number>", "Maximum sessions to list", "50")
+        .action((options) => {
+        const store = new OpenCodeEventStore({ dbPath: options.dbPath });
+        try {
+            const ids = store.listSessionIds(options.limit ? Number(options.limit) : 50);
+            process.stdout.write(JSON.stringify(ids, null, 2) + "\n");
+        }
+        finally {
+            store.close();
+        }
+    });
+    return command;
+}

package/dist/commands/repo.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Repo command — fetch package information for a GitHub repo from web-ade.
+ *
+ * Hits `GET /api/github/repo/{owner}/{name}/packages` which mirrors the live
+ * package discovery the in-app repo explorer uses (`PackageLayerModule`).
+ * The response is `{ packages: PackageLayer[], summary, treeSha }` where
+ * `summary` carries the monorepo flag, root package name, workspace list,
+ * and aggregated dependency / script counts.
+ *
+ * Resolves a GitHub token locally (gh CLI → git credential helper) and calls
+ * the web-ade API with `Authorization: Bearer <token>`. The token is never
+ * echoed to argv, env, stdout, or stderr.
+ *
+ * Set `PRINCIPAL_ADE_BASE_URL` to point at a non-prod deployment.
+ */
+import { Command } from 'commander';
+export declare function createRepoCommand(): Command;
+//# sourceMappingURL=repo.d.ts.map

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

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

package/dist/commands/repo.js

@@ -0,0 +1,233 @@
+/**
+ * Repo command — fetch package information for a GitHub repo from web-ade.
+ *
+ * Hits `GET /api/github/repo/{owner}/{name}/packages` which mirrors the live
+ * package discovery the in-app repo explorer uses (`PackageLayerModule`).
+ * The response is `{ packages: PackageLayer[], summary, treeSha }` where
+ * `summary` carries the monorepo flag, root package name, workspace list,
+ * and aggregated dependency / script counts.
+ *
+ * Resolves a GitHub token locally (gh CLI → git credential helper) and calls
+ * the web-ade API with `Authorization: Bearer <token>`. The token is never
+ * echoed to argv, env, stdout, or stderr.
+ *
+ * Set `PRINCIPAL_ADE_BASE_URL` to point at a non-prod deployment.
+ */
+import { Command } from 'commander';
+import { spawnSync } from 'node:child_process';
+const BASE_URL = process.env.PRINCIPAL_ADE_BASE_URL?.replace(/\/+$/, '') ||
+    'https://app.principal-ade.com';
+// ============================================================================
+// Auth
+// ============================================================================
+function resolveTokenViaGh() {
+    const result = spawnSync('gh', ['auth', 'token'], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    if (result.status === 0 && result.stdout) {
+        const token = result.stdout.trim();
+        if (token)
+            return token;
+    }
+    return null;
+}
+function resolveTokenViaGitCredential() {
+    const result = spawnSync('git', ['credential', 'fill'], {
+        encoding: 'utf8',
+        input: 'protocol=https\nhost=github.com\n\n',
+        stdio: ['pipe', 'pipe', 'ignore'],
+    });
+    if (result.status !== 0 || !result.stdout)
+        return null;
+    for (const line of result.stdout.split('\n')) {
+        if (line.startsWith('password=')) {
+            const token = line.slice('password='.length).trim();
+            if (token)
+                return token;
+        }
+    }
+    return null;
+}
+function resolveToken() {
+    return resolveTokenViaGh() ?? resolveTokenViaGitCredential();
+}
+function exitWithTokenError() {
+    process.stderr.write('Could not resolve a GitHub token. Run `gh auth login`, or configure a git credential helper for github.com.\n');
+    process.exit(2);
+}
+// ============================================================================
+// HTTP helpers
+// ============================================================================
+async function describeHttpError(response) {
+    let serverMessage = '';
+    let code = '';
+    try {
+        const body = (await response.clone().json());
+        serverMessage = body.error ?? '';
+        code = body.code ?? '';
+    }
+    catch {
+        // body wasn't JSON — fall through to status-only message
+    }
+    const fallback = response.status === 404
+        ? 'Repository not found (or token lacks read access)'
+        : response.status === 403
+            ? 'Not authorized (token may lack repo scope)'
+            : response.status === 401
+                ? 'GitHub token rejected'
+                : `HTTP ${response.status}`;
+    const human = serverMessage || fallback;
+    return `${human}${code ? ` [${code}]` : ''}`;
+}
+// ============================================================================
+// repo parsing
+// ============================================================================
+function parseOwnerRepo(ownerRepo) {
+    const slashIndex = ownerRepo.indexOf('/');
+    if (slashIndex === -1 || slashIndex === 0 || slashIndex === ownerRepo.length - 1) {
+        process.stderr.write(`Invalid repo format: "${ownerRepo}". Use <owner>/<repo> (e.g. "principal-ai/web-ade").\n`);
+        process.exit(2);
+    }
+    return {
+        owner: ownerRepo.slice(0, slashIndex),
+        repo: ownerRepo.slice(slashIndex + 1),
+    };
+}
+async function fetchPackages(ownerRepo, options) {
+    const { owner, repo } = parseOwnerRepo(ownerRepo);
+    const token = resolveToken();
+    if (!token)
+        exitWithTokenError();
+    const url = `${BASE_URL}/api/github/repo/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/packages`;
+    let response;
+    try {
+        response = await fetch(url, {
+            headers: {
+                Authorization: `Bearer ${token}`,
+                Accept: 'application/json',
+            },
+        });
+    }
+    catch (err) {
+        process.stderr.write(`Network error fetching packages: ${err.message}\n`);
+        process.exit(1);
+    }
+    if (!response.ok) {
+        process.stderr.write(`${await describeHttpError(response)}\n`);
+        process.exit(1);
+    }
+    let body;
+    try {
+        body = (await response.json());
+    }
+    catch {
+        process.stderr.write('Unexpected non-JSON response from the packages endpoint.\n');
+        process.exit(1);
+    }
+    // A 200 may still carry a server-side error message (degraded fallback).
+    if (body.error) {
+        process.stderr.write(`Server reported an error: ${body.error}\n`);
+        process.exit(1);
+    }
+    if (options.json) {
+        const out = options.summaryOnly ? { summary: body.summary, treeSha: body.treeSha } : body;
+        process.stdout.write(JSON.stringify(out, null, 2));
+        process.stdout.write('\n');
+        return;
+    }
+    renderPackagesHuman(body, options.summaryOnly === true);
+}
+// ============================================================================
+// Human rendering
+// ============================================================================
+function renderPackagesHuman(body, summaryOnly) {
+    const { summary = {}, packages, treeSha } = body;
+    const pkgCount = summary.totalPackages ?? packages.length;
+    const heading = summary.isMonorepo
+        ? `Monorepo — ${pkgCount} package${pkgCount === 1 ? '' : 's'}`
+        : `${pkgCount} package${pkgCount === 1 ? '' : 's'}`;
+    console.log(`\n${heading}`);
+    if (summary.rootPackageName) {
+        console.log(`  root: ${summary.rootPackageName}`);
+    }
+    if (treeSha)
+        console.log(`  tree: ${treeSha}`);
+    console.log('');
+    const deps = summary.totalDependencies ?? 0;
+    const devDeps = summary.totalDevDependencies ?? 0;
+    console.log(`  dependencies:        ${deps}   dev: ${devDeps}`);
+    const scripts = summary.availableScripts ?? [];
+    if (scripts.length > 0) {
+        console.log(`  available scripts:  ${scripts.length}`);
+        const preview = scripts.slice(0, 10).join(', ');
+        const more = scripts.length > 10 ? ` (+${scripts.length - 10} more)` : '';
+        console.log(`    ${preview}${more}`);
+    }
+    console.log('');
+    if (summaryOnly)
+        return;
+    const workspacePackages = summary.workspacePackages ?? [];
+    if (workspacePackages.length > 0) {
+        console.log('  workspaces:');
+        for (const ws of workspacePackages) {
+            const name = ws.name || '(unnamed)';
+            const path = ws.path || '';
+            console.log(`    ${name}${path ? `  ${path}` : ''}`);
+        }
+        console.log('');
+    }
+    if (packages.length === 0) {
+        console.log('  (no package manifests detected)');
+        return;
+    }
+    console.log('  packages:');
+    for (const p of packages) {
+        const data = p.packageData;
+        if (!data) {
+            console.log('    (entry without packageData)');
+            continue;
+        }
+        const name = data.name || '(unnamed)';
+        const path = data.path || '';
+        const flags = [];
+        if (data.isMonorepoRoot)
+            flags.push('monorepo-root');
+        if (data.isWorkspace)
+            flags.push('workspace');
+        const flagText = flags.length > 0 ? `  [${flags.join(', ')}]` : '';
+        console.log(`    ${name}${path ? `  ${path}` : ''}${flagText}`);
+        const depCount = Object.keys(data.dependencies || {}).length;
+        const devDepCount = Object.keys(data.devDependencies || {}).length;
+        if (depCount || devDepCount) {
+            console.log(`      deps: ${depCount}, devDeps: ${devDepCount}`);
+        }
+        const commands = data.availableCommands ?? [];
+        if (commands.length > 0) {
+            const names = commands.map((c) => c.name).filter(Boolean);
+            if (names.length > 0) {
+                const preview = names.slice(0, 8).join(', ');
+                const more = names.length > 8 ? ` (+${names.length - 8} more)` : '';
+                console.log(`      scripts: ${preview}${more}`);
+            }
+        }
+    }
+    console.log('');
+}
+// ============================================================================
+// Command wiring
+// ============================================================================
+export function createRepoCommand() {
+    const command = new Command('repo');
+    command.description('Fetch repository data from web-ade');
+    command
+        .command('packages')
+        .description('Detect and return package information for a GitHub repository (live discovery via web-ade).')
+        .argument('<owner/repo>', 'Repo in owner/repo format (e.g. principal-ai/web-ade)')
+        .option('--summary-only', 'Print only the aggregate summary (no per-package list)')
+        .option('--json', 'Output the raw response as JSON (for agents / storing in a story)')
+        .action(async (ownerRepo, options) => {
+        await fetchPackages(ownerRepo, options);
+    });
+    return command;
+}

package/dist/commands/schema.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Schema command - Display documentation about the canvas format
+ */
+import { Command } from 'commander';
+export declare function createSchemaCommand(): Command;
+//# sourceMappingURL=schema.d.ts.map

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

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