@paperpod/cli 0.1.0

package/dist/cli.js

@@ -0,0 +1,812 @@
+#!/usr/bin/env node
+/**
+ * PaperPod CLI
+ *
+ * Agent-native sandbox execution from your terminal.
+ *
+ * Usage:
+ *   ppod exec "ls -la"               # Execute a command
+ *   ppod exec "npm test" --timeout 120000
+ *   ppod write /app/script.py ./local.py
+ *   cat file.txt | ppod write /app/file.txt
+ *   ppod read /app/output.txt
+ *   ppod ls /app
+ *   ppod login                        # Save token
+ *   ppod status                       # Check connection
+ *
+ * Environment:
+ *   PAPERPOD_TOKEN      - Authentication token (overrides config file)
+ *   PAPERPOD_API_URL    - API URL (default: wss://paperpod.dev/ws)
+ */
+import { execCommand, writeCommand, readCommand, listCommand, loginCommand, logoutCommand, statusCommand, helpCommand, versionCommand, 
+// Process & Ports
+exposeCommand, processStartCommand, processListCommand, processKillCommand, 
+// Browser
+screenshotCommand, pdfCommand, scrapeCommand, markdownCommand, contentCommand, traceCommand, testCommand, browserSessionsCommand, browserLimitsCommand, 
+// AI
+aiGenerateCommand, aiEmbedCommand, aiImageCommand, aiTranscribeCommand, 
+// Code
+interpretCommand, 
+// Memory
+memoryWriteCommand, memoryReadCommand, memoryListCommand, memoryDeleteCommand, memoryUsageCommand, 
+// Account
+balanceCommand, } from "./commands.js";
+function parseArgs(argv) {
+    const args = argv.slice(2);
+    const command = args[0] || "help";
+    const rest = [];
+    const options = {};
+    let i = 1;
+    while (i < args.length) {
+        const arg = args[i];
+        if (arg === "--timeout" && args[i + 1]) {
+            options.timeout = parseInt(args[i + 1], 10);
+            i += 2;
+        }
+        else if (arg === "--json") {
+            options.json = true;
+            i++;
+        }
+        else if (arg === "--no-stream") {
+            options.stream = false;
+            i++;
+        }
+        else if ((arg === "-o" || arg === "--output") && args[i + 1]) {
+            options.output = args[i + 1];
+            i += 2;
+        }
+        else if (arg === "-h" || arg === "--help") {
+            options.help = true;
+            i++;
+        }
+        else if (arg === "--full-page") {
+            options.fullPage = true;
+            i++;
+        }
+        else if (arg === "--width" && args[i + 1]) {
+            options.width = parseInt(args[i + 1], 10);
+            i += 2;
+        }
+        else if (arg === "--height" && args[i + 1]) {
+            options.height = parseInt(args[i + 1], 10);
+            i += 2;
+        }
+        else if (arg === "--format" && args[i + 1]) {
+            options.format = args[i + 1];
+            i += 2;
+        }
+        else if (arg === "--landscape") {
+            options.landscape = true;
+            i++;
+        }
+        else if (arg === "--limit" && args[i + 1]) {
+            options.limit = parseInt(args[i + 1], 10);
+            i += 2;
+        }
+        else if (arg === "--model" && args[i + 1]) {
+            options.model = args[i + 1];
+            i += 2;
+        }
+        else if (arg === "--system" && args[i + 1]) {
+            options.systemPrompt = args[i + 1];
+            i += 2;
+        }
+        else if (arg === "--max-tokens" && args[i + 1]) {
+            options.maxTokens = parseInt(args[i + 1], 10);
+            i += 2;
+        }
+        else if (arg === "--temperature" && args[i + 1]) {
+            options.temperature = parseFloat(args[i + 1]);
+            i += 2;
+        }
+        else if (arg === "--language" && args[i + 1]) {
+            options.language = args[i + 1];
+            i += 2;
+        }
+        else if (arg === "--id" && args[i + 1]) {
+            options.processId = args[i + 1];
+            i += 2;
+        }
+        else if (arg === "--trace" && args[i + 1]) {
+            options.trace = args[i + 1];
+            i += 2;
+        }
+        else if (arg.startsWith("-")) {
+            // Unknown option, skip
+            i++;
+        }
+        else {
+            rest.push(arg);
+            i++;
+        }
+    }
+    return { command, args: rest, options };
+}
+// ============================================================================
+// Per-Command Help
+// ============================================================================
+const COMMAND_HELP = {
+    exec: `
+ppod exec <command> [options]
+
+Execute a shell command in your sandbox.
+
+OPTIONS:
+  --timeout <ms>    Command timeout (default: 60000)
+  --json            Output as JSON
+  --no-stream       Disable streaming output
+
+EXAMPLES:
+  ppod exec "ls -la"
+  ppod exec "python train.py" --timeout 120000
+  ppod exec "npm test" --json
+`,
+    write: `
+ppod write <remote-path> [local-file]
+
+Write a file to your sandbox. If no local file is specified, reads from stdin.
+
+EXAMPLES:
+  ppod write /app/script.py ./local.py
+  echo "hello" | ppod write /app/hello.txt
+  cat config.json | ppod write /app/config.json
+`,
+    read: `
+ppod read <remote-path> [-o output-file]
+
+Read a file from your sandbox.
+
+OPTIONS:
+  -o, --output <file>   Save to local file instead of stdout
+
+EXAMPLES:
+  ppod read /app/output.txt
+  ppod read /app/data.json -o local.json
+`,
+    ls: `
+ppod ls [path] [options]
+
+List directory contents in your sandbox.
+
+OPTIONS:
+  --json    Output as JSON
+
+EXAMPLES:
+  ppod ls
+  ppod ls /app --json
+`,
+    "browser:screenshot": `
+ppod browser:screenshot <url> [options]
+
+Take a screenshot of a web page.
+
+OPTIONS:
+  -o, --output <file>   Save to file (default: prints base64)
+  --full-page           Capture entire page
+  --width <px>          Viewport width (default: 1280)
+  --height <px>         Viewport height (default: 720)
+  --format <fmt>        png, jpeg, or webp (default: png)
+  --trace <file>        Capture Playwright trace for debugging
+  --json                Output as JSON
+
+EXAMPLES:
+  ppod browser:screenshot https://example.com -o shot.png
+  ppod browser:screenshot https://example.com --full-page
+  ppod browser:screenshot https://example.com --trace debug.zip
+`,
+    "browser:pdf": `
+ppod browser:pdf <url> [options]
+
+Generate a PDF from a web page.
+
+OPTIONS:
+  -o, --output <file>   Save to file (default: prints base64)
+  --landscape           Use landscape orientation
+  --format <size>       a4, letter, legal (default: a4)
+  --json                Output as JSON
+
+EXAMPLES:
+  ppod browser:pdf https://example.com -o doc.pdf
+  ppod browser:pdf https://example.com --landscape
+`,
+    "browser:scrape": `
+ppod browser:scrape <url> [selector] [options]
+
+Scrape elements from a web page.
+
+ARGUMENTS:
+  url         The page URL
+  selector    CSS selector (default: "body")
+
+OPTIONS:
+  --limit <n>   Max elements to return
+  --json        Output as JSON
+
+EXAMPLES:
+  ppod browser:scrape https://example.com
+  ppod browser:scrape https://example.com "h1, h2"
+  ppod browser:scrape https://news.ycombinator.com ".titleline" --limit 10
+`,
+    "browser:markdown": `
+ppod browser:markdown <url> [options]
+
+Extract markdown from a rendered web page.
+
+OPTIONS:
+  -o, --output <file>   Save to file
+  --json                Output as JSON
+
+EXAMPLES:
+  ppod browser:markdown https://example.com
+  ppod browser:markdown https://example.com -o page.md
+`,
+    "browser:content": `
+ppod browser:content <url> [options]
+
+Get the rendered HTML of a web page.
+
+OPTIONS:
+  -o, --output <file>   Save to file
+  --json                Output as JSON
+
+EXAMPLES:
+  ppod browser:content https://example.com
+  ppod browser:content https://example.com -o page.html
+`,
+    "browser:trace": `
+ppod browser:trace start|stop [options]
+
+Start or stop browser tracing for debugging.
+
+NOTE: Tracing captures all browser operations within the same connection.
+      Use with ppod browser:* commands in sequence.
+
+OPTIONS:
+  -o, --output <file>   Save trace to file (for stop)
+  --json                Output as JSON
+
+EXAMPLES:
+  ppod browser:trace start
+  ppod browser:screenshot https://example.com
+  ppod browser:trace stop -o trace.zip
+`,
+    "browser:test": `
+ppod browser:test <url> '<assertions-json>' [options]
+
+Run Playwright-style assertions against a web page.
+
+ASSERTION TYPES:
+  visible     Element is visible:       {"type":"visible","selector":"h1"}
+  hidden      Element is hidden:        {"type":"hidden","selector":".modal"}
+  text        Element has text:         {"type":"text","selector":"h1","expected":"Hello"}
+  count       Element count:            {"type":"count","selector":"li","expected":5}
+  title       Page title contains:      {"type":"title","expected":"Example"}
+  url         URL contains:             {"type":"url","expected":"example.com"}
+
+OPTIONS:
+  --json    Output as JSON
+
+EXAMPLES:
+  ppod browser:test https://example.com '[{"type":"visible","selector":"h1"}]'
+  ppod browser:test https://example.com '[{"type":"text","selector":"h1","expected":"Example Domain"}]'
+`,
+    ai: `
+ppod ai <prompt> [options]
+
+Generate text using a large language model.
+
+OPTIONS:
+  --model <name>        Model to use (default: llama-3.2-1b-instruct)
+  --system <prompt>     System prompt
+  --max-tokens <n>      Max output tokens
+  --temperature <f>     Sampling temperature (0-2)
+  --json                Output as JSON
+
+EXAMPLES:
+  ppod ai "Write a haiku about coding"
+  ppod ai "Explain quantum computing" --model "@cf/meta/llama-3.1-8b-instruct"
+  ppod ai "Summarize this" --json
+`,
+    "ai:image": `
+ppod ai:image <prompt> [options]
+
+Generate an image from a text prompt.
+
+OPTIONS:
+  -o, --output <file>   Save to file (default: prints base64)
+  --width <px>          Image width (default: 1024)
+  --height <px>         Image height (default: 1024)
+  --model <name>        Model to use
+  --json                Output as JSON
+
+EXAMPLES:
+  ppod ai:image "A sunset over mountains" -o sunset.png
+  ppod ai:image "A happy robot" --width 512 --height 512
+`,
+    "ai:embed": `
+ppod ai:embed <text> [options]
+
+Generate embeddings for text.
+
+OPTIONS:
+  --model <name>    Model to use
+  --json            Output as JSON
+
+EXAMPLES:
+  ppod ai:embed "Hello world"
+  ppod ai:embed "Search query" --json
+`,
+    expose: `
+ppod expose <port> [options]
+
+Expose a port from your sandbox and get a public URL.
+
+OPTIONS:
+  --json    Output as JSON
+
+EXAMPLES:
+  ppod start "python -m http.server 8080"
+  ppod expose 8080
+`,
+    start: `
+ppod start <command> [options]
+
+Start a background process in your sandbox.
+
+OPTIONS:
+  --json    Output as JSON
+
+EXAMPLES:
+  ppod start "node server.js"
+  ppod start "python -m http.server 8080"
+  ppod ps              # Check running processes
+  ppod expose 8080     # Expose the port
+`,
+    ps: `
+ppod ps [options]
+
+List running processes in your sandbox.
+
+OPTIONS:
+  --json    Output as JSON
+
+EXAMPLES:
+  ppod ps
+  ppod ps --json
+`,
+    kill: `
+ppod kill <process-id>
+
+Kill a running process.
+
+EXAMPLES:
+  ppod ps              # Get process IDs
+  ppod kill proc-123
+`,
+    "mem:write": `
+ppod mem:write <path> [local-file]
+
+Write to persistent memory (survives sandbox restarts).
+
+EXAMPLES:
+  ppod mem:write state.json ./local.json
+  echo '{"step":1}' | ppod mem:write progress.json
+`,
+    "mem:read": `
+ppod mem:read <path>
+
+Read from persistent memory.
+
+EXAMPLES:
+  ppod mem:read state.json
+  ppod mem:read progress.json --json
+`,
+    "mem:ls": `
+ppod mem:ls [prefix] [options]
+
+List files in persistent memory.
+
+OPTIONS:
+  --json    Output as JSON
+
+EXAMPLES:
+  ppod mem:ls
+  ppod mem:ls research/
+`,
+    "mem:rm": `
+ppod mem:rm <path>
+
+Delete a file from persistent memory.
+
+EXAMPLES:
+  ppod mem:rm old-state.json
+`,
+    interpret: `
+ppod interpret <code> [options]
+
+Execute code with rich output (images, charts, dataframes).
+
+OPTIONS:
+  --language <lang>   python, javascript, r (default: python)
+  --json              Output as JSON
+
+EXAMPLES:
+  ppod interpret "import matplotlib.pyplot as plt; plt.plot([1,2,3]); plt.show()"
+  ppod interpret "console.log('hello')" --language javascript
+`,
+};
+function showCommandHelp(command) {
+    // Normalize command (handle aliases)
+    const normalized = command
+        .replace(/^screenshot$/, "browser:screenshot")
+        .replace(/^pdf$/, "browser:pdf")
+        .replace(/^scrape$/, "browser:scrape")
+        .replace(/^markdown$/, "browser:markdown")
+        .replace(/^content$/, "browser:content")
+        .replace(/^trace$/, "browser:trace")
+        .replace(/^test$/, "browser:test");
+    if (COMMAND_HELP[normalized]) {
+        console.log(COMMAND_HELP[normalized]);
+    }
+    else if (COMMAND_HELP[command]) {
+        console.log(COMMAND_HELP[command]);
+    }
+    else {
+        // Fall back to general help
+        helpCommand();
+    }
+}
+// ============================================================================
+// Main
+// ============================================================================
+async function main() {
+    const { command, args, options } = parseArgs(process.argv);
+    // Handle per-command help
+    if (options.help) {
+        showCommandHelp(command);
+        process.exit(0);
+    }
+    let exitCode = 0;
+    try {
+        switch (command) {
+            case "exec":
+                if (args.length === 0) {
+                    console.error("Usage: ppod exec <command>");
+                    process.exit(1);
+                }
+                exitCode = await execCommand(args.join(" "), {
+                    timeout: options.timeout,
+                    json: options.json,
+                    stream: options.stream,
+                });
+                break;
+            case "write":
+                if (args.length === 0) {
+                    console.error("Usage: ppod write <remote-path> [local-file]");
+                    process.exit(1);
+                }
+                exitCode = await writeCommand(args[0], args[1] || null, {
+                    timeout: options.timeout,
+                });
+                break;
+            case "read":
+                if (args.length === 0) {
+                    console.error("Usage: ppod read <remote-path>");
+                    process.exit(1);
+                }
+                exitCode = await readCommand(args[0], {
+                    timeout: options.timeout,
+                    output: options.output,
+                });
+                break;
+            case "ls":
+            case "list":
+                exitCode = await listCommand(args[0] || ".", {
+                    timeout: options.timeout,
+                    json: options.json,
+                });
+                break;
+            case "login":
+                exitCode = await loginCommand(args[0]);
+                break;
+            case "logout":
+                exitCode = await logoutCommand();
+                break;
+            case "status":
+                exitCode = await statusCommand();
+                break;
+            // ====== Port Exposure ======
+            case "expose":
+                if (args.length === 0) {
+                    console.error("Usage: ppod expose <port>");
+                    process.exit(1);
+                }
+                exitCode = await exposeCommand(parseInt(args[0], 10), {
+                    timeout: options.timeout,
+                    json: options.json,
+                });
+                break;
+            // ====== Browser Commands ======
+            // Support both "screenshot" and "browser:screenshot" for consistency
+            case "screenshot":
+            case "browser:screenshot":
+                if (args.length === 0) {
+                    console.error("Usage: ppod browser:screenshot <url> [-o file.png]");
+                    console.error("       ppod screenshot <url> [-o file.png]");
+                    process.exit(1);
+                }
+                exitCode = await screenshotCommand(args[0], {
+                    timeout: options.timeout,
+                    output: options.output,
+                    fullPage: options.fullPage,
+                    width: options.width,
+                    height: options.height,
+                    format: options.format,
+                    json: options.json,
+                    trace: options.trace,
+                });
+                break;
+            case "pdf":
+            case "browser:pdf":
+                if (args.length === 0) {
+                    console.error("Usage: ppod browser:pdf <url> [-o file.pdf]");
+                    console.error("       ppod pdf <url> [-o file.pdf]");
+                    process.exit(1);
+                }
+                exitCode = await pdfCommand(args[0], {
+                    timeout: options.timeout,
+                    output: options.output,
+                    landscape: options.landscape,
+                    paperFormat: options.format,
+                    json: options.json,
+                    trace: options.trace,
+                });
+                break;
+            case "scrape":
+            case "browser:scrape":
+                if (args.length === 0) {
+                    console.error("Usage: ppod browser:scrape <url> [selector]");
+                    console.error("       ppod scrape <url> [selector]");
+                    console.error("\nSelector defaults to 'body' if not specified.");
+                    process.exit(1);
+                }
+                // Default selector to "body" if not provided
+                exitCode = await scrapeCommand(args[0], args[1] || "body", {
+                    timeout: options.timeout,
+                    limit: options.limit,
+                    json: options.json,
+                    trace: options.trace,
+                });
+                break;
+            case "markdown":
+            case "browser:markdown":
+                if (args.length === 0) {
+                    console.error("Usage: ppod browser:markdown <url> [-o file.md]");
+                    console.error("       ppod markdown <url> [-o file.md]");
+                    process.exit(1);
+                }
+                exitCode = await markdownCommand(args[0], {
+                    timeout: options.timeout,
+                    output: options.output,
+                    json: options.json,
+                    trace: options.trace,
+                });
+                break;
+            case "content":
+            case "browser:content":
+                if (args.length === 0) {
+                    console.error("Usage: ppod browser:content <url> [-o file.html]");
+                    console.error("       ppod content <url> [-o file.html]");
+                    process.exit(1);
+                }
+                exitCode = await contentCommand(args[0], {
+                    timeout: options.timeout,
+                    output: options.output,
+                    json: options.json,
+                    trace: options.trace,
+                });
+                break;
+            case "trace":
+            case "browser:trace":
+                if (args.length === 0 || !["start", "stop"].includes(args[0])) {
+                    console.error("Usage: ppod browser:trace start|stop [-o trace.zip]");
+                    console.error("       ppod trace start|stop [-o trace.zip]");
+                    console.error("\nNote: Tracing captures operations within the same WebSocket connection.");
+                    console.error("      For cross-request tracing, browser operations should share a session.");
+                    process.exit(1);
+                }
+                exitCode = await traceCommand(args[0], {
+                    timeout: options.timeout,
+                    output: options.output,
+                    json: options.json,
+                });
+                break;
+            case "test":
+            case "browser:test":
+                if (args.length < 2) {
+                    console.error("Usage: ppod browser:test <url> '<assertions-json>'");
+                    console.error("       ppod test <url> '<assertions-json>'");
+                    console.error("\nAssertion format: JSON array of assertion objects");
+                    console.error("  Types: visible, hidden, text, count, title, url\n");
+                    console.error("Examples:");
+                    console.error('  ppod browser:test https://example.com \'[{"type":"visible","selector":"h1"}]\'');
+                    console.error('  ppod browser:test https://example.com \'[{"type":"text","selector":"h1","expected":"Hello"}]\'');
+                    console.error('  ppod browser:test https://example.com \'[{"type":"title","expected":"Example"}]\'');
+                    process.exit(1);
+                }
+                exitCode = await testCommand(args[0], args[1], {
+                    timeout: options.timeout,
+                    json: options.json,
+                });
+                break;
+            case "browser:sessions":
+                exitCode = await browserSessionsCommand({
+                    timeout: options.timeout,
+                    json: options.json,
+                });
+                break;
+            case "browser:limits":
+                exitCode = await browserLimitsCommand({
+                    timeout: options.timeout,
+                    json: options.json,
+                });
+                break;
+            // ====== AI Commands ======
+            case "ai":
+                if (args.length === 0) {
+                    console.error("Usage: ppod ai <prompt>");
+                    process.exit(1);
+                }
+                exitCode = await aiGenerateCommand(args.join(" "), {
+                    timeout: options.timeout,
+                    model: options.model,
+                    systemPrompt: options.systemPrompt,
+                    maxTokens: options.maxTokens,
+                    temperature: options.temperature,
+                    json: options.json,
+                });
+                break;
+            case "ai:embed":
+                if (args.length === 0) {
+                    console.error("Usage: ppod ai:embed <text>");
+                    process.exit(1);
+                }
+                exitCode = await aiEmbedCommand(args.join(" "), {
+                    timeout: options.timeout,
+                    model: options.model,
+                    json: options.json,
+                });
+                break;
+            case "ai:image":
+                if (args.length === 0) {
+                    console.error("Usage: ppod ai:image <prompt> [-o file.png]");
+                    process.exit(1);
+                }
+                exitCode = await aiImageCommand(args.join(" "), {
+                    timeout: options.timeout,
+                    model: options.model,
+                    output: options.output,
+                    width: options.width,
+                    height: options.height,
+                    json: options.json,
+                });
+                break;
+            case "ai:transcribe":
+                if (args.length === 0) {
+                    console.error("Usage: ppod ai:transcribe <audio-file>");
+                    process.exit(1);
+                }
+                exitCode = await aiTranscribeCommand(args[0], {
+                    timeout: options.timeout,
+                    model: options.model,
+                    json: options.json,
+                });
+                break;
+            // ====== Code Interpreter ======
+            case "interpret":
+                if (args.length === 0) {
+                    console.error("Usage: ppod interpret '<code>' [--language python|javascript]");
+                    process.exit(1);
+                }
+                exitCode = await interpretCommand(args.join(" "), {
+                    timeout: options.timeout,
+                    language: options.language,
+                    json: options.json,
+                });
+                break;
+            // ====== Memory Commands ======
+            case "mem:write":
+                if (args.length === 0) {
+                    console.error("Usage: ppod mem:write <path> [local-file]");
+                    process.exit(1);
+                }
+                exitCode = await memoryWriteCommand(args[0], args[1] || null, {
+                    timeout: options.timeout,
+                });
+                break;
+            case "mem:read":
+                if (args.length === 0) {
+                    console.error("Usage: ppod mem:read <path>");
+                    process.exit(1);
+                }
+                exitCode = await memoryReadCommand(args[0], {
+                    timeout: options.timeout,
+                    output: options.output,
+                });
+                break;
+            case "mem:ls":
+                exitCode = await memoryListCommand(args[0], {
+                    timeout: options.timeout,
+                    json: options.json,
+                });
+                break;
+            case "mem:rm":
+                if (args.length === 0) {
+                    console.error("Usage: ppod mem:rm <path>");
+                    process.exit(1);
+                }
+                exitCode = await memoryDeleteCommand(args[0], {
+                    timeout: options.timeout,
+                });
+                break;
+            case "mem:usage":
+                exitCode = await memoryUsageCommand({
+                    timeout: options.timeout,
+                    json: options.json,
+                });
+                break;
+            // ====== Process Commands ======
+            case "ps":
+                exitCode = await processListCommand({
+                    timeout: options.timeout,
+                    json: options.json,
+                });
+                break;
+            case "start":
+                if (args.length === 0) {
+                    console.error("Usage: ppod start <command>");
+                    process.exit(1);
+                }
+                exitCode = await processStartCommand(args.join(" "), {
+                    timeout: options.timeout,
+                    processId: options.processId,
+                    json: options.json,
+                });
+                break;
+            case "kill":
+                if (args.length === 0) {
+                    console.error("Usage: ppod kill <process-id>");
+                    process.exit(1);
+                }
+                exitCode = await processKillCommand(args[0], {
+                    timeout: options.timeout,
+                });
+                break;
+            // ====== Account Commands ======
+            case "balance":
+                exitCode = await balanceCommand({
+                    timeout: options.timeout,
+                    json: options.json,
+                });
+                break;
+            case "version":
+            case "-v":
+            case "--version":
+                versionCommand();
+                break;
+            case "help":
+            case "-h":
+            case "--help":
+            default:
+                helpCommand();
+                break;
+        }
+    }
+    catch (err) {
+        console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+        exitCode = 1;
+    }
+    process.exit(exitCode);
+}
+main();
+//# sourceMappingURL=cli.js.map