@papercraneai/cli 1.5.6 → 1.6.0-beta.1

package/bin/papercrane.js

@@ -4,12 +4,81 @@ import { Command } from 'commander';
 import chalk from 'chalk';
 import readline from 'readline';
 import fs from 'fs/promises';
+import path from 'path';
+import os from 'os';
 import http from 'http';
 import { http as httpClient } from '../lib/axios-client.js';
 import { setApiKey, clearConfig, isLoggedIn, setDefaultWorkspace, getDefaultWorkspace, setOrgId, getOrgId } from '../lib/config.js';
 import { validateApiKey } from '../lib/cloud-client.js';
 import { listFunctions, getFunction, runFunction, formatDescribe, formatDescribeRoot, formatFlat, formatResult, formatUnconnected } from '../lib/function-client.js';
-import { listWorkspaces, resolveWorkspaceId, getFileTree, readFile, writeFile, editFile, deleteFile, getLocalWorkspacePath, pullWorkspace, pushWorkspace } from '../lib/environment-client.js';
+import { listWorkspaces, resolveWorkspaceId, getLocalWorkspacePath, pullWorkspace, pushWorkspace } from '../lib/environment-client.js';
+
+/**
+ * Check login and workspace setup. Exits with helpful message if not ready.
+ */
+async function requireWorkspace() {
+  const loggedIn = await isLoggedIn();
+  if (!loggedIn) {
+    console.error(chalk.red('Not logged in. Run: papercrane login'));
+    process.exit(1);
+  }
+  const defaultWs = await getDefaultWorkspace();
+  if (!defaultWs) {
+    console.error(chalk.red('No workspace selected.'));
+    console.error(chalk.dim('\nRun these commands first:'));
+    console.error(chalk.dim('  papercrane workspaces list'));
+    console.error(chalk.dim('  papercrane workspaces use <id>'));
+    process.exit(1);
+  }
+  return defaultWs;
+}
+
+/**
+ * After login, list workspaces and prompt user to select one.
+ */
+async function showPostLoginHelp() {
+  try {
+    const workspaces = await listWorkspaces();
+    if (!workspaces || workspaces.length === 0) {
+      console.log(chalk.dim('No workspaces found. Create one at https://papercrane.ai\n'));
+      return;
+    }
+
+    if (workspaces.length === 1) {
+      // Auto-select the only workspace
+      const ws = workspaces[0];
+      await setDefaultWorkspace(ws.id);
+
+      const workspaceDir = getLocalWorkspacePath(ws.id);
+      const { generateScaffolding } = await import('../lib/dev-server.js');
+      await generateScaffolding(workspaceDir);
+
+      const currentLink = path.join(os.homedir(), '.papercrane', 'current');
+      try {
+        const existing = await fs.readlink(currentLink);
+        if (existing !== workspaceDir) {
+          await fs.unlink(currentLink);
+          await fs.symlink(workspaceDir, currentLink);
+        }
+      } catch {
+        try { await fs.unlink(currentLink); } catch {}
+        await fs.symlink(workspaceDir, currentLink);
+      }
+
+      console.log(chalk.green(`\n✓ Workspace set to ${ws.id}${ws.name ? ` (${ws.name})` : ''}`));
+      console.log(chalk.dim(`  Dashboards: ${workspaceDir}/app/\n`));
+      return;
+    }
+
+    console.log(chalk.bold('\nAvailable workspaces:\n'));
+    for (const ws of workspaces) {
+      console.log(`  ${chalk.bold(ws.id)}  ${ws.name || '(unnamed)'}`);
+    }
+    console.log(chalk.dim('\nNext step: papercrane workspaces use <id>\n'));
+  } catch {
+    // Non-fatal — workspace listing might fail
+  }
+}
 
 /**
  * Test if browser can actually open URLs by starting a local server and
@@ -239,7 +308,8 @@ program
           } catch {
             // Non-fatal — org ID is a convenience, not required
           }
-          console.log(chalk.green('✓ Successfully logged in\n'));
+          console.log(chalk.green('✓ Successfully logged in'));
+          await showPostLoginHelp();
         } else {
           console.log(chalk.yellow('⚠️  API key saved, but validation failed.'));
           console.log(chalk.yellow('   The key may be invalid or the service may be unavailable.\n'));
@@ -267,7 +337,8 @@ program
             if (data.orgId) await setOrgId(data.orgId);
             await clearPendingSession();
             console.log(chalk.green(`✓ Logged in as ${data.email}`));
-            console.log(chalk.dim(`  API key saved to ~/.papercrane/config.json\n`));
+            console.log(chalk.dim(`  API key saved to ~/.papercrane/config.json`));
+            await showPostLoginHelp();
             return;
           }
         }
@@ -284,7 +355,8 @@ program
       if (result.orgId) await setOrgId(result.orgId);
 
       console.log(chalk.green(`✓ Logged in as ${result.email}`));
-      console.log(chalk.dim(`  API key saved to ~/.papercrane/config.json\n`));
+      console.log(chalk.dim(`  API key saved to ~/.papercrane/config.json`));
+      await showPostLoginHelp();
     } catch (error) {
       if (error.message.includes('timed out')) {
         console.error(chalk.red('\nAuthentication timed out. Please try again.'));
@@ -386,7 +458,7 @@ program
 
 program
   .command('add [integration]')
-  .description('Add a new integration via OAuth')
+  .description('Connect a new integration')
   .action(async (integration) => {
     try {
       if (integration) {
@@ -458,19 +530,22 @@ program
 
 program
   .command('dashboard-guide')
-  .description('Show how to build dashboards in cloud workspaces')
+  .description('Show how to build dashboards')
   .action(async () => {
-    console.log(chalk.bold('\n📊 Building Dashboards in Papercrane Workspaces\n'));
-    console.log(chalk.dim('Workspaces are Next.js environments. Files you write become live routes.\n'));
+    console.log(chalk.bold('\n📊 Building Dashboards with Papercrane\n'));
+    console.log(chalk.dim('Each dashboard is a folder with two files: page.tsx (UI) and action.ts (data).\n'));
 
     console.log(chalk.bold('FILE STRUCTURE'));
     console.log(chalk.dim('─'.repeat(60)));
     console.log(`
-Create two files for each dashboard page:
-
-  app/(dashboard)/my-dashboard/
-  ├── action.ts    # Server-side data fetching
-  └── page.tsx     # Client component with charts
+  ~/.papercrane/current/app/
+  ├── layout.tsx               # Auto-generated by CLI
+  ├── globals.css              # Auto-generated by CLI
+  └── my-dashboard/            # Your dashboard
+      ├── action.ts            # Server-side data fetching
+      └── page.tsx             # Client component with charts
+
+  Set active workspace: papercrane workspaces use <id>
 `);
 
     console.log(chalk.bold('1. action.ts - Server Action Pattern'));
@@ -577,15 +652,18 @@ Use these Tailwind classes for theme-aware colors:
     console.log(chalk.bold('QUICK START'));
     console.log(chalk.dim('─'.repeat(60)));
     console.log(`
-  1. ${chalk.cyan('papercrane')}                    # List available integrations
-  2. ${chalk.cyan('papercrane describe <path>')}    # Explore endpoints
-  3. ${chalk.cyan('papercrane call <path> \'{}\'')}  # Test data fetching
+  1. ${chalk.cyan('papercrane login')}              # Authenticate with Papercrane
+  2. ${chalk.cyan('papercrane workspaces list')}    # See available workspaces
+  3. ${chalk.cyan('papercrane workspaces use <id>')} # Set active workspace
   4. ${chalk.cyan('papercrane pull')}               # Pull workspace files locally
-  5. Edit files in ${chalk.cyan('~/.papercrane/workspaces/<id>/')}
-  6. ${chalk.cyan('papercrane push')}               # Push changes back
-
-  ${chalk.dim('The pull/push workflow is recommended - edit files locally, then sync.')}
-  ${chalk.dim('For single files, you can also use: papercrane files write <path> --json "..."')}
+  5. ${chalk.cyan('papercrane dev')}                # Start local dev server with HMR
+  6. Create dashboards in ${chalk.cyan('~/.papercrane/current/app/')}
+  7. ${chalk.cyan('papercrane push')}               # Push to cloud, get shareable URLs
+
+  ${chalk.dim('Explore APIs:')}
+  ${chalk.cyan('papercrane')}                       # List connected integrations
+  ${chalk.cyan('papercrane describe <path>')}       # Explore endpoints
+  ${chalk.cyan('papercrane call <path> \'{}\'')}     # Test data fetching
 `);
     console.log();
   });
@@ -634,7 +712,8 @@ workspacesCmd
 workspacesCmd
   .command('use <id>')
   .description('Set the default workspace')
-  .action(async (id) => {
+  .option('--reset-scaffolding', 'Regenerate scaffolding files (layout.tsx, globals.css, configs)')
+  .action(async (id, options) => {
     try {
       const loggedIn = await isLoggedIn();
       if (!loggedIn) {
@@ -649,206 +728,78 @@ workspacesCmd
       }
 
       await setDefaultWorkspace(wsId);
-      console.log(chalk.green(`✓ Default workspace set to ${wsId}\n`));
-    } catch (error) {
-      console.error(chalk.red('Error:'), error.message);
-      process.exit(1);
-    }
-  });
-
-// ============================================================================
-// FILE COMMANDS
-// ============================================================================
 
-const filesCmd = program.command('files').description('Build dashboards by reading/writing files in cloud workspaces.\n\nWorkspaces are Next.js environments - files you write become live routes.\nRun "papercrane dashboard-guide" for the recommended dashboard pattern.');
+      // Scaffold the workspace and create ~/.papercrane/current symlink
+      const { generateScaffolding, resetScaffolding } = await import('../lib/dev-server.js');
+      const workspaceDir = getLocalWorkspacePath(wsId);
 
-filesCmd
-  .command('list [path]')
-  .description('List files in a workspace')
-  .option('-w, --workspace <id>', 'Workspace ID (uses default if not specified)')
-  .action(async (path, options) => {
-    try {
-      const loggedIn = await isLoggedIn();
-      if (!loggedIn) {
-        console.error(chalk.red('Error: Not logged in. Run: papercrane login'));
-        process.exit(1);
+      if (options.resetScaffolding) {
+        await resetScaffolding(workspaceDir);
+        await fs.rm(path.join(workspaceDir, '.next'), { recursive: true, force: true });
+        console.log(chalk.dim('Scaffolding regenerated.'));
       }
+      await generateScaffolding(workspaceDir);
 
-      const wsId = await resolveWorkspaceId(options.workspace);
-      const result = await getFileTree(wsId, path || '');
-
-      console.log(chalk.bold(`\nFiles in workspace ${wsId}${path ? ` (${path})` : ''}:\n`));
-      printFileTree(result.tree, '  ');
-      console.log();
-    } catch (error) {
-      console.error(chalk.red('Error:'), error.message);
-      process.exit(1);
-    }
-  });
-
-filesCmd
-  .command('read <path>')
-  .description('Read file contents')
-  .option('-w, --workspace <id>', 'Workspace ID (uses default if not specified)')
-  .option('--raw', 'Output raw content without formatting')
-  .action(async (path, options) => {
-    try {
-      const loggedIn = await isLoggedIn();
-      if (!loggedIn) {
-        console.error(chalk.red('Error: Not logged in. Run: papercrane login'));
-        process.exit(1);
+      const currentLink = path.join(os.homedir(), '.papercrane', 'current');
+      try {
+        const existing = await fs.readlink(currentLink);
+        if (existing !== workspaceDir) {
+          await fs.unlink(currentLink);
+          await fs.symlink(workspaceDir, currentLink);
+        }
+      } catch {
+        try { await fs.unlink(currentLink); } catch {}
+        await fs.symlink(workspaceDir, currentLink);
       }
 
-      const wsId = await resolveWorkspaceId(options.workspace);
-      const result = await readFile(wsId, path);
-
-      if (options.raw) {
-        process.stdout.write(result.content);
-      } else {
-        console.log(chalk.dim(`# ${result.path} (${result.size} bytes) — use this path for write/edit/delete\n`));
-        console.log(result.content);
-      }
+      console.log(chalk.green(`✓ Default workspace set to ${wsId}`));
+      console.log(chalk.dim(`  ${currentLink} → ${workspaceDir}`));
+      console.log(chalk.dim(`  Dashboards: ${workspaceDir}/app/\n`));
     } catch (error) {
       console.error(chalk.red('Error:'), error.message);
       process.exit(1);
     }
   });
 
-filesCmd
-  .command('write <path> [content]')
-  .description('Write content to a file. Path is relative to workspace root (same paths as files list/read).\n\nExamples:\n  papercrane files write app/page.tsx --json \'"use client";\\nexport default function() {}"\'\n  papercrane files write app/action.ts -f ./local-file.ts')
-  .option('-w, --workspace <id>', 'Workspace ID (uses default if not specified)')
-  .option('-f, --file <localPath>', 'Read content from a local file')
-  .option('--json <string>', 'Content as a JSON-encoded string (recommended for code)')
-  .option('--stdin', 'Read content from stdin')
-  .action(async (path, contentArg, options) => {
-    try {
-      const loggedIn = await isLoggedIn();
-      if (!loggedIn) {
-        console.error(chalk.red('Error: Not logged in. Run: papercrane login'));
-        process.exit(1);
-      }
-
-      let content;
-
-      if (options.json) {
-        // Parse JSON-encoded string
-        try {
-          content = JSON.parse(options.json);
-          if (typeof content !== 'string') {
-            console.error(chalk.red('Error: --json must be a JSON string, e.g., \'"hello\\nworld"\''));
-            process.exit(1);
-          }
-        } catch (e) {
-          console.error(chalk.red('Error: Invalid JSON string'));
-          console.error(chalk.dim('  Expected format: \'"line1\\nline2"\''));
-          process.exit(1);
-        }
-      } else if (options.file) {
-        // Read from local file
-        content = await fs.readFile(options.file, 'utf-8');
-      } else if (options.stdin) {
-        // Read from stdin
-        content = await readStdin();
-      } else if (contentArg) {
-        // Use positional argument
-        content = contentArg;
-      } else {
-        console.error(chalk.red('Error: Content required. Provide --json, --file, --stdin, or as argument'));
-        process.exit(1);
-      }
-
-      const wsId = await resolveWorkspaceId(options.workspace);
-      const result = await writeFile(wsId, path, content);
 
-      console.log(chalk.green(`✓ Written ${result.size} bytes to ${result.path}\n`));
-    } catch (error) {
-      if (error.response?.status === 404) {
-        console.error(chalk.red('Error: 404 — workspace sandbox may be stopped or unreachable'));
-        console.error(chalk.dim(`  Path: ${path}`));
-        console.error(chalk.dim('  Check workspace status: papercrane workspaces list'));
-      } else {
-        console.error(chalk.red('Error:'), error.response?.data?.error || error.message);
-      }
-      process.exit(1);
-    }
-  });
+// ============================================================================
+// DEV COMMAND
+// ============================================================================
 
-filesCmd
-  .command('edit <path>')
-  .description('Edit a file with find/replace')
-  .option('-w, --workspace <id>', 'Workspace ID (uses default if not specified)')
-  .option('--old <string>', 'Text to find')
-  .option('--new <string>', 'Text to replace with')
-  .option('--replace-all', 'Replace all occurrences')
-  .option('-p, --params <json>', 'Parameters as JSON: {"old_string": "...", "new_string": "...", "replace_all": false}')
-  .option('--stdin', 'Read parameters as JSON from stdin')
-  .action(async (path, options) => {
+program
+  .command('dev')
+  .description('Start local dev server for dashboard development with HMR')
+  .option('-w, --workspace <id>', 'Workspace ID')
+  .option('-p, --port <port>', 'Port (default: 3100)', '3100')
+  .option('--clear-cache', 'Clear build cache before starting (use after structural changes like editing globals.css or adding dependencies)')
+  .option('--reset-scaffolding', 'Regenerate scaffolding files (layout.tsx, globals.css, configs) and clear build cache')
+  .action(async (options) => {
     try {
-      const loggedIn = await isLoggedIn();
-      if (!loggedIn) {
-        console.error(chalk.red('Error: Not logged in. Run: papercrane login'));
-        process.exit(1);
-      }
-
-      let oldString, newString, replaceAll = false;
-
-      if (options.stdin) {
-        // Read JSON from stdin
-        const input = await readStdin();
-        const params = JSON.parse(input);
-        oldString = params.old_string;
-        newString = params.new_string;
-        replaceAll = params.replace_all || false;
-      } else if (options.params) {
-        // Parse JSON params
-        const params = JSON.parse(options.params);
-        oldString = params.old_string;
-        newString = params.new_string;
-        replaceAll = params.replace_all || false;
-      } else if (options.old !== undefined && options.new !== undefined) {
-        // Use --old and --new flags
-        oldString = options.old;
-        newString = options.new;
-        replaceAll = options.replaceAll || false;
-      } else {
-        console.error(chalk.red('Error: Must provide --old and --new, or --params, or --stdin'));
-        process.exit(1);
-      }
+      const { generateScaffolding, resetScaffolding, startDevServer } = await import('../lib/dev-server.js');
 
-      const wsId = await resolveWorkspaceId(options.workspace);
-      const result = await editFile(wsId, path, oldString, newString, replaceAll);
+      const wsId = options.workspace ? parseInt(options.workspace, 10) : await requireWorkspace();
+      const workspaceDir = getLocalWorkspacePath(wsId);
 
-      console.log(chalk.green(`✓ Made ${result.replacements} replacement(s) in ${result.path}\n`));
-    } catch (error) {
-      if (error.response?.data?.error) {
-        console.error(chalk.red('Error:'), error.response.data.error);
-        if (error.response.data.occurrences) {
-          console.error(chalk.dim(`  Found ${error.response.data.occurrences} occurrences. Use --replace-all to replace all.`));
-        }
-      } else {
-        console.error(chalk.red('Error:'), error.message);
+      if (options.resetScaffolding) {
+        await resetScaffolding(workspaceDir);
+        console.log(chalk.dim('Scaffolding regenerated.'));
       }
-      process.exit(1);
-    }
-  });
 
-filesCmd
-  .command('delete <path>')
-  .description('Delete a file')
-  .option('-w, --workspace <id>', 'Workspace ID (uses default if not specified)')
-  .action(async (path, options) => {
-    try {
-      const loggedIn = await isLoggedIn();
-      if (!loggedIn) {
-        console.error(chalk.red('Error: Not logged in. Run: papercrane login'));
-        process.exit(1);
+      if (options.clearCache || options.resetScaffolding) {
+        const nextDir = path.join(workspaceDir, '.next');
+        await fs.rm(nextDir, { recursive: true, force: true });
+        console.log(chalk.dim('Build cache cleared.'));
       }
 
-      const wsId = await resolveWorkspaceId(options.workspace);
-      const result = await deleteFile(wsId, path);
+      await generateScaffolding(workspaceDir);
+
+      const port = parseInt(options.port, 10);
+      const dashboardDir = workspaceDir + '/app';
+      console.log(chalk.green(`\nDev server starting on http://localhost:${port}`));
+      console.log(chalk.dim(`Dashboard dir: ${dashboardDir}`));
+      console.log(chalk.dim('Create dashboard folders with page.tsx + action.ts\n'));
 
-      console.log(chalk.green(`✓ Deleted ${result.path}\n`));
+      await startDevServer(workspaceDir, port);
     } catch (error) {
       console.error(chalk.red('Error:'), error.message);
       process.exit(1);
@@ -865,13 +816,7 @@ program
   .option('-w, --workspace <id>', 'Workspace ID (uses default if not specified)')
   .action(async (options) => {
     try {
-      const loggedIn = await isLoggedIn();
-      if (!loggedIn) {
-        console.error(chalk.red('Error: Not logged in. Run: papercrane login'));
-        process.exit(1);
-      }
-
-      const wsId = await resolveWorkspaceId(options.workspace);
+      const wsId = options.workspace ? parseInt(options.workspace, 10) : await requireWorkspace();
 
       console.log(chalk.cyan(`Pulling workspace ${wsId}...`));
 
@@ -879,9 +824,15 @@ program
         process.stdout.write(`\r  ${chalk.dim(`[${current}/${total}]`)} ${file}`);
       });
 
+      // Set up dev server infrastructure after pull
+      const { generateScaffolding } = await import('../lib/dev-server.js');
+      await generateScaffolding(localPath);
+
       console.log('\n');
       console.log(chalk.green(`✓ Pulled ${files.length} files to ${localPath}\n`));
-      console.log(chalk.dim('Edit files locally, then run: papercrane push'));
+      console.log(chalk.dim('Dashboards are in: ' + localPath + '/app/'));
+      console.log(chalk.dim('Start local dev server: papercrane dev'));
+      console.log(chalk.dim('Push changes back:      papercrane push'));
     } catch (error) {
       console.error(chalk.red('Error:'), error.message);
       process.exit(1);
@@ -890,18 +841,12 @@ program
 
 program
   .command('push')
-  .description('Push local files back to workspace')
+  .description('Push dashboards and resources to cloud for sharing')
   .option('-w, --workspace <id>', 'Workspace ID (uses default if not specified)')
-  .option('-p, --path <path>', 'Only push files under this path (e.g., "verdata-vrisk")')
+  .option('-p, --path <path>', 'Only push files under this path (e.g., "ga4-dashboard")')
   .action(async (options) => {
     try {
-      const loggedIn = await isLoggedIn();
-      if (!loggedIn) {
-        console.error(chalk.red('Error: Not logged in. Run: papercrane login'));
-        process.exit(1);
-      }
-
-      const wsId = await resolveWorkspaceId(options.workspace);
+      const wsId = options.workspace ? parseInt(options.workspace, 10) : await requireWorkspace();
       const localPath = getLocalWorkspacePath(wsId);
       const pathFilter = options.path;
 
@@ -912,19 +857,20 @@ program
       }, pathFilter);
 
       console.log('\n');
-      console.log(chalk.green(`✓ Pushed ${files.length} files from ${localPath}`));
+      console.log(chalk.green(`✓ Pushed ${files.length} files to cloud`));
 
-      // Print preview URL(s)
+      // Print shareable URLs
       const { getApiBaseUrl, getOrgId: getStoredOrgId } = await import('../lib/config.js');
       const baseUrl = await getApiBaseUrl();
       const orgId = await getStoredOrgId();
 
-      // Find unique dashboard directories that were pushed
-      const dashboards = [...new Set(files.map(f => f.split('/')[0]).filter(d => d && !d.includes('.')))];
+      const dashboards = [...new Set(files
+        .filter(f => f.startsWith('app/'))
+        .map(f => f.split('/')[1])
+        .filter(d => d && !d.includes('.')))];
 
       if (dashboards.length > 0) {
         console.log('');
-        console.log(chalk.dim('Preview:'));
         const pathPrefix = orgId ? `/org/${orgId}` : '';
         for (const dashboard of dashboards) {
           console.log(chalk.cyan(`  ${baseUrl}${pathPrefix}/environments/${wsId}/${dashboard}`));
@@ -948,29 +894,6 @@ function readStdin() {
   });
 }
 
-// Helper to print file tree recursively
-function printFileTree(tree, indent = '') {
-  if (!tree || !Array.isArray(tree)) return;
-
-  // Sort: folders first, then files
-  const sorted = [...tree].sort((a, b) => {
-    if (a.type === 'folder' && b.type !== 'folder') return -1;
-    if (a.type !== 'folder' && b.type === 'folder') return 1;
-    return a.name.localeCompare(b.name);
-  });
-
-  for (const item of sorted) {
-    if (item.type === 'folder') {
-      console.log(`${indent}${chalk.blue(item.name + '/')}`);
-      if (item.children) {
-        printFileTree(item.children, indent + '  ');
-      }
-    } else {
-      console.log(`${indent}${item.name}`);
-    }
-  }
-}
-
 // Default action: show connected modules when no command is given
 program.action(async (_, cmd) => {
   // Reject unknown commands instead of silently falling through
@@ -986,13 +909,9 @@ program.action(async (_, cmd) => {
     console.error('  papercrane dashboard-guide      Show how to build dashboards');
     console.error('  papercrane workspaces list      List workspaces');
     console.error('  papercrane workspaces use <id>  Set default workspace');
-    console.error('  papercrane files list [path]    List files in workspace');
-    console.error('  papercrane files read <path>    Read file contents');
-    console.error('  papercrane files write <path>   Write file contents');
-    console.error('  papercrane files edit <path>    Edit file with find/replace');
-    console.error('  papercrane files delete <path>  Delete a file');
+    console.error('  papercrane dev                  Start local dev server with HMR');
     console.error('  papercrane pull                 Pull workspace files locally for editing');
-    console.error('  papercrane push                 Push local changes back to workspace');
+    console.error('  papercrane push                 Push to cloud, get shareable URLs');
     console.error('  papercrane login                Log in with API key');
     console.error('  papercrane logout               Log out');
     process.exit(1);

package/components/command-listener.tsx

@@ -0,0 +1,52 @@
+"use client"
+
+import { useEffect, useRef } from "react"
+
+interface CommandHandler {
+  handleCommand: (command: { action: string; value?: string }) => void
+}
+
+export function CommandListener() {
+  const handlerRef = useRef<CommandHandler | null>(null)
+
+  // Try to load the plugin and set up the command handler
+  useEffect(() => {
+    let cancelled = false
+
+    async function init() {
+      try {
+        const pkg = "@papercrane/" + "dashboard-grid/plugin"
+        const mod = await import(/* turbopackIgnore: true */ pkg)
+        if (!cancelled && mod.createCommandHandler) {
+          handlerRef.current = mod.createCommandHandler()
+        }
+      } catch {
+        // Plugin not installed — commands are silently ignored
+      }
+    }
+
+    init()
+    return () => { cancelled = true }
+  }, [])
+
+  useEffect(() => {
+    // Only listen when embedded in an iframe
+    if (typeof window === "undefined" || window === window.parent) {
+      return
+    }
+
+    const handleMessage = (event: MessageEvent) => {
+      const data = event.data
+      if (!data || typeof data !== "object" || data.type !== "papercrane-command") {
+        return
+      }
+
+      handlerRef.current?.handleCommand(data.command)
+    }
+
+    window.addEventListener("message", handleMessage)
+    return () => window.removeEventListener("message", handleMessage)
+  }, [])
+
+  return null
+}