@principal-ai/principal-studio-cli 0.35.3

package/dist/commands/hooks.d.ts

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../src/commands/hooks.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA4NpC,wBAAgB,kBAAkB,IAAI,OAAO,CA+F5C"}

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 `npx @principal-ai/principal-studio-cli doctor` and `npx @principal-ai/principal-studio-cli 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 @principal-ai/principal-studio-cli@latest doctor --errors-only || {
+  echo "❌ Principal View doctor check failed (errors found)"
+  echo "   Run 'npx @principal-ai/principal-studio-cli doctor' to see details"
+  exit 1
+}
+
+echo "Running Principal View canvas validation..."
+npx @principal-ai/principal-studio-cli@latest validate --quiet 2>/dev/null || {
+  if [ $? -ne 0 ]; then
+    echo "❌ Canvas validation failed"
+    echo "   Run 'npx @principal-ai/principal-studio-cli 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
+        const 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('@principal-ai/principal-studio-cli ') ||
+                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 "npx @principal-ai/principal-studio-cli hooks --init" to install husky');
+                    process.exit(1);
+                }
+                else if (options.add) {
+                    console.log(chalk.red('❌ Husky is not installed'));
+                    console.log('   Run "npx @principal-ai/principal-studio-cli 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('  npx @principal-ai/principal-studio-cli 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 npx @principal-ai/principal-studio-cli 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/inbox.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Inbox command — fetch your trail inbox state from the Principal ADE backend.
+ *
+ * Resolves a GitHub token locally (gh CLI → git credential helper) and calls
+ * `GET /api/trails/inbox` with `Authorization: Bearer <token>`. The token is
+ * never echoed to argv, env, stdout, or stderr. The response carries a
+ * server-derived `notification` per row ({ dot, unread, noteCount,
+ * newNoteCount }) plus a top-level `unreadCount`, so an agent can see which
+ * shared trails need attention and how many notes are new since last open.
+ */
+import { Command } from 'commander';
+export declare function createInboxCommand(): Command;
+//# sourceMappingURL=inbox.d.ts.map

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

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

package/dist/commands/inbox.js

@@ -0,0 +1,179 @@
+/**
+ * Inbox command — fetch your trail inbox state from the Principal ADE backend.
+ *
+ * Resolves a GitHub token locally (gh CLI → git credential helper) and calls
+ * `GET /api/trails/inbox` with `Authorization: Bearer <token>`. The token is
+ * never echoed to argv, env, stdout, or stderr. The response carries a
+ * server-derived `notification` per row ({ dot, unread, noteCount,
+ * newNoteCount }) plus a top-level `unreadCount`, so an agent can see which
+ * shared trails need attention and how many notes are new since last open.
+ */
+import { Command } from 'commander';
+import { spawnSync } from 'node:child_process';
+import chalk from 'chalk';
+const BASE_URL = 'https://app.principal-ade.com';
+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);
+}
+/** Compact "3d ago" / "5m ago" relative time; falls back to the raw value. */
+function timeAgo(iso) {
+    const then = Date.parse(iso);
+    if (Number.isNaN(then))
+        return iso;
+    const seconds = Math.max(0, Math.round((Date.now() - then) / 1000));
+    const units = [
+        [60, 's'],
+        [60, 'm'],
+        [24, 'h'],
+        [7, 'd'],
+        [4.345, 'w'],
+        [12, 'mo'],
+        [Number.POSITIVE_INFINITY, 'y'],
+    ];
+    let value = seconds;
+    let unit = 's';
+    for (const [size, label] of units) {
+        if (value < size) {
+            unit = label;
+            break;
+        }
+        value = Math.floor(value / size);
+        unit = label;
+    }
+    return `${value}${unit} ago`;
+}
+/** One-line note status, e.g. "2 notes (1 new)" or "no notes". */
+function formatNotes(notif, fallbackCount) {
+    const total = notif?.noteCount ?? fallbackCount;
+    const fresh = notif?.newNoteCount ?? 0;
+    if (total === 0)
+        return chalk.dim('no notes');
+    const base = `${total} ${total === 1 ? 'note' : 'notes'}`;
+    if (fresh > 0)
+        return `${base} ${chalk.cyan(`(${fresh} new)`)}`;
+    return chalk.dim(base);
+}
+function renderHuman(data, unreadOnly) {
+    const { entries, unreadCount } = data;
+    const heading = unreadOnly
+        ? `Inbox — ${entries.length} needing attention`
+        : `Inbox — ${entries.length} ${entries.length === 1 ? 'trail' : 'trails'}, ${unreadCount} unread`;
+    console.log(chalk.bold(`\n${heading}\n`));
+    if (entries.length === 0) {
+        console.log(chalk.dim('  Nothing here.\n'));
+        return;
+    }
+    for (const entry of entries) {
+        const notif = entry.notification;
+        const dot = notif?.dot ?? entry.readAt === null;
+        const title = entry.snapshot?.title || `${entry.owner}/${entry.repo}`;
+        const marker = dot ? chalk.hex('#f59e0b')('●') : chalk.dim('·');
+        const titleText = dot ? chalk.bold(title) : title;
+        console.log(`  ${marker} ${titleText}`);
+        const opened = entry.readAt === null ? chalk.yellow('unopened') : chalk.dim('opened');
+        const meta = [
+            chalk.dim(`trail ${entry.trailId}`),
+            `from @${entry.sender.githubLogin}`,
+            formatNotes(notif, entry.snapshot?.noteCount ?? 0),
+            chalk.dim(`sent ${timeAgo(entry.sentAt)}`),
+            opened,
+        ].join(chalk.dim('  ·  '));
+        console.log(`    ${meta}`);
+        console.log(chalk.dim(`    ${entry.owner}/${entry.repo}`));
+        if (entry.comment)
+            console.log(chalk.dim(`    “${entry.comment}”`));
+        console.log('');
+    }
+}
+async function fetchInbox(options) {
+    const token = resolveToken();
+    if (!token)
+        exitWithTokenError();
+    const params = new URLSearchParams();
+    if (options.unread)
+        params.set('unreadOnly', 'true');
+    if (options.limit)
+        params.set('limit', options.limit);
+    const query = params.toString();
+    const url = `${BASE_URL}/api/trails/inbox${query ? `?${query}` : ''}`;
+    let response;
+    try {
+        response = await fetch(url, {
+            headers: {
+                Authorization: `Bearer ${token}`,
+                Accept: 'application/json',
+            },
+        });
+    }
+    catch (error) {
+        process.stderr.write(`Failed to reach ${BASE_URL}: ${error.message}\n`);
+        process.exit(1);
+    }
+    if (response.status === 401) {
+        process.stderr.write('Unauthorized (401). Your GitHub token may be expired — run `gh auth login` and retry.\n');
+        process.exit(1);
+    }
+    if (!response.ok) {
+        process.stderr.write(`Request failed: HTTP ${response.status} ${response.statusText}\n`);
+        process.exit(1);
+    }
+    const body = await response.text();
+    let data;
+    try {
+        data = JSON.parse(body);
+    }
+    catch {
+        process.stderr.write('Unexpected non-JSON response from the inbox endpoint.\n');
+        process.exit(1);
+    }
+    if (options.json) {
+        console.log(JSON.stringify(data, null, 2));
+        return;
+    }
+    renderHuman(data, Boolean(options.unread));
+}
+export function createInboxCommand() {
+    const command = new Command('inbox');
+    command
+        .description('Show your trail inbox: which shared trails need attention and how many notes are new')
+        .option('--json', 'Output the raw inbox response as JSON (for agents)')
+        .option('--unread', 'Only show rows needing attention (unopened or with new notes)')
+        .option('--limit <n>', 'Maximum number of rows to fetch')
+        .action(async (options) => {
+        await fetchInbox(options);
+    });
+    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;AAwDpC,wBAAgB,iBAAiB,IAAI,OAAO,CA+L3C"}