@cnrai/pave 0.3.32 → 0.3.34

package/lib/args-parser.js

@@ -0,0 +1,837 @@
+#!/usr/bin/env node
+/**
+ * PAVE CLI Argument Parser
+ * Node 16 compatible - no external dependencies
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/* global PAVE_VERSION */
+
+// Shared flag definitions used by multiple command branches (hoisted to avoid duplication)
+const FLAGS_WITH_VALUES = new Set([
+  '--config', '--category', '-c', '--model', '-m', '--session', '-s',
+  '--port', '-p', '--host', '--max-memory', '--memory-limit', '--memory-warning',
+  '--memory-critical', '--memory-startup', '--opencode-dir',
+  '--bind', '-b', '--shell', '--last', '--export',
+  '--name', '-n', '--sleep', '--soul', '--reinject-interval',
+  '--query', '-q', '--skill', '--path', '--output', '-o',
+  '--lines', '--agent',
+]);
+const BOOLEAN_FLAGS = new Set([
+  '--json', '--no-stream', '--color', '--verbose', '--no-tools', '--debug',
+  '--force', '-f', '--all', '-a', '--help', '-h', '--version', '-v',
+  '--list', '--full', '--quiet', '--silent',
+  '--daemon', '--follow',
+  '--urgent',
+]);
+// Flags that optionally take a value (on/off/true/false/0/1)
+const OPTIONAL_VALUE_FLAGS = new Set(['--memory-monitor', '--ish-mode']);
+// Include common case variants so --ish-mode TRUE / --memory-monitor ON work
+const OPTIONAL_VALUES = new Set([
+  'on', 'off', 'true', 'false', '0', '1',
+  'ON', 'OFF', 'TRUE', 'FALSE',
+]);
+
+function parseArgs(argv = process.argv.slice(2)) {
+  const args = {
+    // Subcommand (install, list, remove, etc.) - null means run TUI
+    command: null,
+    commandArgs: [], // Arguments for the subcommand
+
+    // Memory configuration
+    ishMode: null, // Force ISH mode: true/false/null (auto-detect)
+    memoryLimit: null, // Heap limit in MB
+    memoryWarning: null, // Warning threshold in MB
+    memoryCritical: null, // Critical threshold in MB
+    memoryStartup: null, // Startup limit in MB
+    memoryMonitor: null, // Enable memory monitoring: true/false/null (auto)
+
+    // Server configuration
+    port: null, // Server port
+    host: null, // Server hostname
+    opencodedir: null, // Working directory
+
+    // General options
+    help: false,
+    version: false,
+    debug: false,
+    verbose: false,
+    force: false, // Force overwrite for install
+    json: false, // JSON output for list
+
+    // Marketplace options
+    all: false, // Show all skills (for search)
+    category: null, // Filter by category (for search)
+    check: false, // Check only, don't install (for update)
+    createPr: false, // Create PR for publish
+    upgrade: false, // Upgrade existing skill in marketplace
+
+    // Chat options
+    session: null, // Session ID or 'new' for new session
+    noStream: false, // Disable streaming output
+    color: false, // Enable colored output (implies --no-stream)
+    model: null, // Model to use (e.g., 'github-copilot/claude-sonnet-4')
+    showTools: true, // Tool output shown by default; use --no-tools to hide
+    agent: null, // Target agent name for inbox message (pave chat -a <agent>)
+    urgent: false, // Send as urgent interrupt (pave chat -a <agent> --urgent "msg")
+
+    // Agent options
+    name: null, // Agent name (e.g., 'OpenPAVE software engineer')
+    sleep: null, // Sleep duration between iterations (e.g., '30m', '1h', '5s')
+    soul: null, // Path to SOUL.md file for agent instructions
+    reinjectInterval: null, // Re-send SOUL every N iterations to prevent drift; null uses agent default (10)
+    agentSubcommand: null, // Agent subcommand: 'init', 'stop', 'logs' for pave agent <sub>
+    daemon: false, // Start agent in background (--daemon)
+    follow: false, // Follow log output in real-time (--follow)
+    lines: null, // Number of log lines to show (--lines <n>)
+
+    // History options
+    last: null, // Show last N messages
+    export: null, // Export to file path
+    listSessions: false, // List all sessions
+
+    // Shell-init options
+    bind: null, // Key binding (e.g., 'ctrl+g', 'ctrl+p')
+    shell: null, // Shell type: zsh, bash, fish (auto-detected)
+    installShell: false, // Auto-install to shell config file
+
+    // Config path
+    config: null, // Custom .pave config directory path
+  };
+
+  // Check for subcommands first (must be first non-flag argument)
+  const subcommands = ['install', 'list', 'remove', 'uninstall', 'info', 'run', 'search', 'publish', 'update', 'chat', 'history', 'shell-init', 'agent', 'agents'];
+  if (argv.length > 0 && subcommands.includes(argv[0])) {
+    args.command = argv[0];
+
+    // For 'run' command, pass ALL remaining arguments (including flags) to the skill
+    // For 'chat' command, collect the message (may be multiple words)
+    // For other commands, only collect non-flag arguments
+    if (args.command === 'run') {
+      // Pass everything after 'run' to the skill (it handles its own flags)
+      args.commandArgs = argv.slice(1);
+      // Return early - don't parse any flags for 'run' command
+      // They all belong to the skill
+      return args;
+    } if (args.command === 'chat') {
+      // Collect message parts (everything that's not a flag we handle)
+      for (let i = 1; i < argv.length; i++) {
+        const a = argv[i];
+        // Skip our flags and their values
+        if (a === '--session' || a === '-s' || a === '--model' || a === '-m') {
+          i++; // Skip the value too
+        } else if (a === '--agent' || a === '-a') {
+          // Agent target for inbox message (#231: validate value is not a flag)
+          if (i + 1 < argv.length && !argv[i + 1].startsWith('-')) {
+            args.agent = argv[i + 1];
+            i++; // Skip the value
+          } else {
+            console.error('Error: --agent requires an agent name');
+            process.exit(1);
+          }
+        } else if (a === '--json' || a === '--no-stream' || a === '--color' || a === '--verbose' || a === '--no-tools' || a === '--debug') {
+          // Skip boolean flags
+        } else if (!a.startsWith('-')) {
+          args.commandArgs.push(a);
+        }
+      }
+    } else if (args.command === 'agent') {
+      // For agent command, extract positional args (SOUL path) while skipping flags and their values.
+      // Also detect 'init' subcommand: the first non-flag positional token that is 'init'
+      // sets agentSubcommand and is excluded from commandArgs.
+      // Key insight: the agent command should have exactly one positional arg (the SOUL path).
+      // All unknown --flags are assumed to take a value (consumed as next token).
+
+      for (let i = 1; i < argv.length; i++) {
+        const a = argv[i];
+        const next = argv[i + 1];
+
+        // Skip known flags that take values (and their values)
+        if (FLAGS_WITH_VALUES.has(a)) {
+          i++; // Skip the value too
+        } else if (BOOLEAN_FLAGS.has(a)) {
+          // Skip boolean flags
+        } else if (OPTIONAL_VALUE_FLAGS.has(a)) {
+          // Skip optional value flags - check if next arg is an optional value
+          if (next && OPTIONAL_VALUES.has(next.toLowerCase())) {
+            i++; // Skip the optional value
+          }
+        } else if (a.startsWith('--') && a.includes('=')) {
+          // Handle --flag=value style (skip entirely)
+          continue;
+        } else if (a.startsWith('-') && !a.startsWith('--') && a.length === 2 && next && !next.startsWith('-')) {
+          // Handle unknown short flags like -x value (assume they take a value if next doesn't start with -)
+          i++; // Skip the presumed value
+        } else if (a.startsWith('--') && next && !next.startsWith('-')) {
+          // Handle unknown long flags: assume they take a value whenever next arg exists
+          // and doesn't start with '-'. This prevents URIs like discord://123 from being
+          // misclassified as positional args.
+          i++; // Skip the presumed value
+        } else if (!a.startsWith('-')) {
+          // Positional argument: either a subcommand keyword (init/stop/start/restart/
+          // logs/update/rm/ps) as the first positional, or a SOUL path / agent name after that.
+          // Detect agent subcommands if it's the first positional token
+          if ((a === 'init' || a === 'stop' || a === 'logs' || a === 'restart' || a === 'start' || a === 'update' || a === 'rm') && args.agentSubcommand === null && args.commandArgs.length === 0) {
+            args.agentSubcommand = a;
+          } else if (a === 'ps' && args.command === 'agent' && args.agentSubcommand === null && args.commandArgs.length === 0) {
+            // Map 'pave agent ps' to 'pave agents' to avoid .pave directory creation side effect
+            args.command = 'agents';
+            // Skip adding 'ps' to commandArgs; extra args are collected below and validated
+          } else if (args.command === 'agents') {
+            // Already mapped to agents; collect any remaining args (should be empty)
+            args.commandArgs.push(a);
+          } else {
+            args.commandArgs.push(a);
+          }
+        }
+        // Skip any other flags we don't recognize (flags with no value after them)
+      }
+
+      // Validate positional args for agent commands.
+      // For subcommands (stop/start/restart/logs/update/rm), enforce at most one agent name.
+      // For bare "pave agent" with multiple positional args, heuristically pick the
+      // SOUL file (prefer .md files, fall back to last arg) and warn.
+      // 'pave agent ps' maps to 'pave agents' - reject any extra args
+      if (args.command === 'agents' && args.commandArgs.length > 0) {
+        console.error('Error: "pave agent ps" accepts no arguments, got: ' + args.commandArgs.join(', '));
+        console.error('Usage: pave agent ps');
+        process.exit(1);
+      } else if (args.agentSubcommand === 'stop' || args.agentSubcommand === 'logs' || args.agentSubcommand === 'restart' || args.agentSubcommand === 'start' || args.agentSubcommand === 'update' || args.agentSubcommand === 'rm') {
+        // stop/start/restart/logs/update/rm accept at most one agent name
+        if (args.commandArgs.length > 1) {
+          console.error('Error: "pave agent ' + args.agentSubcommand + '" accepts at most one agent name, got: ' + args.commandArgs.join(', '));
+          console.error('Usage: pave agent ' + args.agentSubcommand + ' [name]');
+          process.exit(1);
+        }
+      } else if (!args.agentSubcommand && args.commandArgs.length > 1) {
+        const mdFiles = args.commandArgs.filter((a) => a.endsWith('.md'));
+        if (mdFiles.length === 1) {
+          // Use the .md file as SOUL path, discard others
+          args.commandArgs = mdFiles;
+        } else if (mdFiles.length > 1) {
+          // Multiple .md files - use --soul to disambiguate
+          console.error(`Warning: Multiple potential SOUL files found: ${args.commandArgs.join(', ')}`);
+          console.error(`         Use --soul <path> to specify the SOUL file explicitly.`);
+          // Keep the last one as the presumed SOUL path
+          args.commandArgs = [args.commandArgs[args.commandArgs.length - 1]];
+        } else {
+          // No .md files, use the last positional arg
+          console.error(`Warning: Multiple positional args found: ${args.commandArgs.join(', ')}`);
+          console.error(`         Using the last one as SOUL path. Use --soul to be explicit.`);
+          args.commandArgs = [args.commandArgs[args.commandArgs.length - 1]];
+        }
+      }
+    } else {
+      // Collect remaining non-flag arguments as command args.
+      // Skip values that follow flags expecting arguments (e.g., --config ./.pave)
+      // Uses shared FLAGS_WITH_VALUES, BOOLEAN_FLAGS, OPTIONAL_VALUE_FLAGS from module scope.
+      for (let i = 1; i < argv.length; i++) {
+        const a = argv[i];
+        const next = argv[i + 1];
+        if (FLAGS_WITH_VALUES.has(a)) {
+          i++; // skip the flag's value
+        } else if (OPTIONAL_VALUE_FLAGS.has(a)) {
+          // Skip optional value flags - consume next token only when it matches an allowed value
+          if (next && OPTIONAL_VALUES.has(next.toLowerCase())) {
+            i++; // Skip the optional value
+          }
+        } else if (!a.startsWith('-')) {
+          args.commandArgs.push(a);
+        }
+      }
+    }
+  }
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    const next = argv[i + 1];
+
+    // Context-sensitive short flags for 'agent logs' subcommand.
+    // -f means --follow and -n means --lines when inside 'agent logs',
+    // overriding their normal meanings (--force, --name).
+    if (args.agentSubcommand === 'logs') {
+      if (arg === '-f') {
+        args.follow = true;
+        continue;
+      }
+      if (arg === '-n') {
+        const linesValue = argv[i + 1];
+        if (!linesValue || linesValue.startsWith('-')) {
+          console.error('Error: -n/--lines requires a positive integer value');
+          process.exit(1);
+        }
+        if (!/^\d+$/.test(linesValue)) {
+          console.error('Error: -n/--lines requires a positive integer, got "' + linesValue + '"');
+          process.exit(1);
+        }
+        const parsedLines = parseInt(linesValue, 10);
+        if (parsedLines <= 0) {
+          console.error('Error: -n/--lines requires a positive integer, got "' + linesValue + '"');
+          process.exit(1);
+        }
+        args.lines = parsedLines;
+        i++;
+        continue;
+      }
+    }
+
+    // Boolean flags
+    if (arg === '--help' || arg === '-h') {
+      args.help = true;
+    } else if (arg === '--version' || arg === '-v') {
+      args.version = true;
+    } else if (arg === '--debug') {
+      args.debug = true;
+    } else if (arg === '--verbose') {
+      args.verbose = true;
+    } else if (arg === '--force' || arg === '-f') {
+      args.force = true;
+    } else if (arg === '--json') {
+      args.json = true;
+    } else if (arg === '--all' || (arg === '-a' && args.command !== 'chat' && args.command !== null)) {
+      args.all = true;
+    } else if (arg === '--check') {
+      args.check = true;
+    } else if (arg === '--create-pr') {
+      args.createPr = true;
+    } else if (arg === '--upgrade' || arg === '-u') {
+      args.upgrade = true;
+    } else if ((arg === '--category' || arg === '-c') && next) {
+      args.category = next;
+      i++;
+    }
+
+    // Chat options
+    else if ((arg === '--session' || arg === '-s') && next) {
+      args.session = next;
+      i++;
+    } else if (arg === '--no-stream') {
+      args.noStream = true;
+    } else if (arg === '--color') {
+      args.color = true;
+      args.noStream = true; // Color output requires waiting for full response
+    } else if ((arg === '--model' || arg === '-m') && next) {
+      args.model = next;
+      i++;
+    } else if (arg === '--no-tools') {
+      args.showTools = false;
+    } else if ((arg === '--agent' || arg === '-a') && next && !next.startsWith('-')) {
+      args.agent = next;
+      i++;
+    } else if (arg === '--urgent') {
+      args.urgent = true;
+    }
+
+    // Agent options
+    else if (arg === '--name' || arg === '-n') {
+      const nameValue = argv[i + 1];
+      if (!nameValue || nameValue.startsWith('-')) {
+        console.error('Error: --name requires a value');
+        process.exit(1);
+      }
+      args.name = nameValue;
+      i++;
+    } else if ((arg === '--sleep')) {
+      const sleepValue = argv[i + 1];
+      if (!sleepValue || sleepValue.startsWith('-')) {
+        console.error('Error: --sleep requires a value');
+        process.exit(1);
+      }
+      args.sleep = sleepValue;
+      i++;
+    } else if (arg === '--soul') {
+      const soulValue = argv[i + 1];
+      if (!soulValue || soulValue.startsWith('-')) {
+        console.error('Error: --soul requires a value');
+        process.exit(1);
+      }
+      args.soul = soulValue;
+      i++;
+    } else if (arg === '--reinject-interval') {
+      const riValue = argv[i + 1];
+      if (!riValue || riValue.startsWith('-')) {
+        console.error('Error: --reinject-interval requires a positive integer value');
+        process.exit(1);
+      }
+      if (!/^\d+$/.test(riValue)) {
+        console.error(`Error: --reinject-interval requires a positive integer, got "${riValue}"`);
+        process.exit(1);
+      }
+      const parsed = parseInt(riValue, 10);
+      if (parsed <= 0) {
+        console.error(`Error: --reinject-interval requires a positive integer, got "${riValue}"`);
+        process.exit(1);
+      }
+      args.reinjectInterval = parsed;
+      i++;
+    } else if (arg === '--daemon') {
+      args.daemon = true;
+    } else if (arg === '--follow') {
+      args.follow = true;
+    } else if (arg === '--lines') {
+      const linesValue = argv[i + 1];
+      if (!linesValue || linesValue.startsWith('-')) {
+        console.error('Error: --lines requires a positive integer value');
+        process.exit(1);
+      }
+      if (!/^\d+$/.test(linesValue)) {
+        console.error('Error: --lines requires a positive integer, got "' + linesValue + '"');
+        process.exit(1);
+      }
+      const parsedLines = parseInt(linesValue, 10);
+      if (parsedLines <= 0) {
+        console.error('Error: --lines requires a positive integer, got "' + linesValue + '"');
+        process.exit(1);
+      }
+      args.lines = parsedLines;
+      i++;
+    }
+
+    // History options
+    else if (arg === '--list') {
+      args.listSessions = true;
+    } else if (arg === '--last' && next) {
+      const lastValue = parseInt(next, 10);
+      if (!Number.isInteger(lastValue) || lastValue <= 0) {
+        console.error(`Error: --last requires a positive integer, got "${next}"`);
+        process.exit(1);
+      }
+      args.last = lastValue;
+      i++;
+    } else if (arg === '--export' && next) {
+      args.export = next;
+      i++;
+    }
+
+    // Shell-init options
+    else if ((arg === '--bind' || arg === '-b') && next) {
+      // Validate keybinding: only allow ctrl+<letter>, ^<letter>, or ctrl+/ patterns
+      // These are the only formats parseKeyBinding() can reliably convert to shell codes
+      const validBindPattern = /^(ctrl[+\-_][a-zA-Z\/\\]|\^[a-zA-Z])$/i;
+      if (!validBindPattern.test(next)) {
+        console.error(`Error: --bind must be in format: ctrl+<letter> or ^<letter> (e.g., ctrl+p, ^G)`);
+        process.exit(1);
+      }
+      args.bind = next;
+      i++;
+    } else if (arg === '--shell' && next) {
+      // Validate shell type
+      const validShells = ['zsh', 'bash', 'fish'];
+      if (!validShells.includes(next.toLowerCase())) {
+        console.error(`Error: --shell must be one of: ${validShells.join(', ')}`);
+        process.exit(1);
+      }
+      args.shell = next.toLowerCase();
+      i++;
+    } else if (arg === '--install' || arg === '-i') {
+      args.installShell = true;
+    }
+
+    // ISH Memory Configuration
+    else if (arg === '--ish-mode') {
+      if (next === 'true' || next === 'on' || next === '1') {
+        args.ishMode = true;
+      } else if (next === 'false' || next === 'off' || next === '0') {
+        args.ishMode = false;
+      } else {
+        args.ishMode = true; // Default to true if no value
+      }
+      if (next && (next === 'true' || next === 'false' || next === 'on' || next === 'off' || next === '1' || next === '0')) {
+        i++; // Skip next arg if it was consumed
+      }
+    }
+
+    else if (arg === '--memory-limit' && next) {
+      const mb = parseInt(next, 10);
+      if (!isNaN(mb) && mb > 0) {
+        args.memoryLimit = mb;
+        i++;
+      }
+    }
+
+    else if (arg === '--memory-warning' && next) {
+      const mb = parseInt(next, 10);
+      if (!isNaN(mb) && mb > 0) {
+        args.memoryWarning = mb;
+        i++;
+      }
+    }
+
+    else if (arg === '--memory-critical' && next) {
+      const mb = parseInt(next, 10);
+      if (!isNaN(mb) && mb > 0) {
+        args.memoryCritical = mb;
+        i++;
+      }
+    }
+
+    else if (arg === '--memory-startup' && next) {
+      const mb = parseInt(next, 10);
+      if (!isNaN(mb) && mb > 0) {
+        args.memoryStartup = mb;
+        i++;
+      }
+    }
+
+    else if (arg === '--memory-monitor') {
+      if (next === 'true' || next === 'on' || next === '1') {
+        args.memoryMonitor = true;
+      } else if (next === 'false' || next === 'off' || next === '0') {
+        args.memoryMonitor = false;
+      } else {
+        args.memoryMonitor = true; // Default to true if no value
+      }
+      if (next && (next === 'true' || next === 'false' || next === 'on' || next === 'off' || next === '1' || next === '0')) {
+        i++;
+      }
+    }
+
+    // Server Configuration
+    else if (arg === '--port' && next) {
+      const port = parseInt(next, 10);
+      if (!isNaN(port) && port > 0 && port < 65536) {
+        args.port = port;
+        i++;
+      }
+    }
+
+    else if (arg === '--host' && next) {
+      args.host = next;
+      i++;
+    }
+
+    else if (arg === '--opencode-dir' && next) {
+      args.opencodedir = next;
+      i++;
+    }
+
+    // Config path - ensure next is a value, not another flag
+    else if (arg === '--config') {
+      if (next && !next.startsWith('-')) {
+        args.config = next;
+        i++;
+      } else {
+        console.error('Error: --config requires a path argument');
+        process.exit(1);
+      }
+    }
+
+    // Handle combined short flags
+    else if (arg.startsWith('-') && !arg.startsWith('--') && arg.length > 2) {
+      for (let j = 1; j < arg.length; j++) {
+        const flag = arg[j];
+        if (flag === 'h') args.help = true;
+        else if (flag === 'v') args.version = true;
+        else if (flag === 'd') args.debug = true;
+      }
+    }
+  }
+
+  // Apply defaults for agent command for any omitted options
+  // Each option is defaulted independently if not explicitly provided
+  // Skip defaults when --help or --version is requested to avoid side effects (e.g., directory creation)
+  if (args.command === 'agent' && !args.help && !args.version) {
+    // Default config: ./.pave (relative to current working directory)
+    if (!args.config) {
+      args.config = './.pave';
+    }
+
+    // For 'agent init/stop/logs', only config default is needed (no sleep/SOUL defaults)
+    if (!args.agentSubcommand) {
+      // Default sleep: 1m (1 minute)
+      if (!args.sleep) {
+        args.sleep = '1m';
+      }
+
+      // Default SOUL file: AGENTS.md (if no soul flag and no command args)
+      if (!args.soul && args.commandArgs.length === 0) {
+        args.commandArgs = ['AGENTS.md'];
+      }
+    }
+  }
+
+  return args;
+}
+
+function showHelp() {
+  console.log(`
+PAVE - Personal AI Virtual Environment
+
+USAGE:
+  pave [options]                     Start the PAVE TUI + server
+  pave chat <message>                Send a message (non-interactive)
+  pave agent [options] [SOUL.md]        Run as continuous autonomous agent (default: AGENTS.md)
+  pave agent --daemon                    Start agent in background (daemon mode)
+  pave agent init                       Initialize agent environment (.pave + permissions.yaml)
+  pave agent stop [name]                Stop a running agent (SIGTERM, SIGKILL after 5s)
+  pave agent start [name]               Start a stopped agent using saved config from status.json
+  pave agent restart [name]             Restart a running agent (preserves session)
+  pave agent update [name] [--sleep <dur>] [--reinject-interval <n>] [--soul <path>]
+                                        Update agent config (sleep, reinject interval, soul)
+  pave agent logs [name] [-f|--follow] [-n|--lines <n>]  View agent log output
+  pave agent ps                        List all registered agent instances (alias: pave agents)
+  pave agents                           List all registered agent instances (alias: pave agent ps)
+  pave history [options]             Show session conversation history
+  pave shell-init [options]          Output shell integration code
+  pave run <skill> <command> [args]  Run a skill command
+  pave install <name|path|url>       Install a skill
+  pave search <query>                Search the skill marketplace
+  pave publish [path]                Publish a skill to marketplace
+  pave update <name>                 Update an installed skill
+  pave list [options]                List installed skills
+  pave remove <name>                 Remove an installed skill
+  pave info <name>                   Show info about a skill
+
+SHELL INTEGRATION:
+  shell-init                Output shell integration code
+  
+  --bind, -b <key>          Key binding (default: ctrl+p)
+  --shell <shell>           Shell type: zsh, bash, fish (auto-detected)
+  --install, -i             Auto-install to shell config (~/.zshrc, etc.)
+  
+  Setup:
+    # Auto-install (recommended)
+    pave shell-init --install
+    
+    # Or manually add to your shell config:
+    # Zsh (~/.zshrc)
+    eval "$(pave shell-init)"
+    
+    # Bash (~/.bashrc)
+    eval "$(pave shell-init --shell bash)"
+    
+    # Fish (~/.config/fish/config.fish)
+    pave shell-init --shell fish | source
+  
+  Then press Ctrl+P to start chatting inline!
+
+CHAT (Non-Interactive):
+  chat <message>            Send a message and get response
+  chat "multi word msg"     Use quotes for multi-word messages
+  echo "msg" | pave chat    Pipe input as message
+  
+  --session, -s <id>        Use specific session ID
+  --session new             Force new session (ignore .pave-session.json)
+  --model, -m <model>       Model to use (e.g., github-copilot/claude-sonnet-4)
+  --agent, -a <name>        Send message to a running agent's inbox
+  --urgent                  Send as urgent interrupt (aborts current work)
+  --no-tools                Hide tool execution progress/results (shown by default)
+  --no-stream               Wait for complete response (no streaming)
+  --color                     Colored markdown output (implies --no-stream)
+  --json                    Output response as JSON
+
+AGENT MODE (Continuous Autonomous Agent):
+  agent [SOUL.md]           Run agent following instructions (default: AGENTS.md)
+  agent init                Initialize agent environment (create .pave + default permissions.yaml)
+  agent init --config <dir> Initialize at a custom config directory
+  agent --soul <path>       Alternative way to specify SOUL file
+  
+  --name, -n <name>         Agent name (e.g., 'OpenPAVE software engineer')
+  --sleep <duration>        Sleep between iterations (e.g., '30m', '1h', '5s')
+                            Default: 1m (1 minute)
+  --reinject-interval <n>   Re-send SOUL every N iterations to prevent drift
+                            Default: 10
+  --config <path>           Config directory (default: ./.pave)
+  --session, -s <id>        Use existing session (resumes conversation)
+  --session new             Force new session (re-sends SOUL instructions)
+  --model, -m <model>       Model to use
+  
+  Defaults: SOUL=AGENTS.md, sleep=1m, reinject-interval=10, config=./.pave
+  
+  The agent runs in a continuous loop:
+    1. On startup, reads SOUL.md for instructions (personality, goals, channels)
+    2. If starting a NEW session: sends SOUL.md content as first message
+       If RESUMING a session: skips initial SOUL send, starts with "keep going"
+    3. SOUL is re-injected automatically when:
+       - The SOUL file is edited (hot-reload via content hash detection)
+       - After auto-compaction (to restore full instructions in new session)
+       - Every N iterations (periodic, controlled by --reinject-interval)
+    4. Between SOUL re-injections, sends "keep going" to continue
+    5. Sleeps for the specified duration between iterations
+    6. Repeats until stopped (Ctrl+C)
+  
+  Session Persistence:
+    - Agent sessions are stored in ~/.pave/state/agent-session-<hash>.json
+    - Restarting the agent will resume the previous session automatically
+    - Use --session new to force a fresh session (re-sends SOUL instructions)
+  
+  Example SOUL.md:
+    You are an AI software engineer for the OpenPAVE project.
+    
+    Your goals:
+    1. Check GitHub issues: gh issue list --repo cnrai/openpave
+    2. Check open PRs: gh pr list --repo cnrai/openpave
+    3. If there are issues assigned to you or unassigned, work on them
+    4. Create PRs for fixes, monitor Copilot reviews
+
+HISTORY:
+  history                   Show conversation history for current session
+  history --session <id>    Show history for specific session
+  history --list            List all available sessions
+  history --last <n>        Show only last N messages (default: all)
+  history --export <file>   Export history to file (markdown format)
+  history --json            Output as JSON
+
+SKILL EXECUTION:
+  run <skill> <command> [args...]    Run a skill command in the sandbox
+                                     Example: pave run gmail list --max 5
+
+MARKETPLACE:
+  search <query>          Search marketplace by name/keywords
+  search --all            List all available skills
+  search -c <category>    Filter by category
+  install <name>          Install from marketplace (e.g., pave install gmail)
+  install <owner/repo>    Install from GitHub (e.g., pave install cnrai/openpave-gmail)
+  install <path>          Install from local directory
+  publish [path]          Validate and publish skill to marketplace
+  publish --create-pr     Auto-create PR to marketplace (requires gh CLI)
+  publish --upgrade       Upgrade existing skill in marketplace
+  update <name>           Update skill to latest version
+  update --all            Update all installed skills
+  update --check          Check for updates without installing
+
+SKILL MANAGEMENT:
+  list                  List all installed skills
+  remove <name>         Remove/uninstall a skill
+  info <name>           Show detailed skill information
+
+SKILL OPTIONS:
+  --force, -f           Force overwrite existing skill
+  --json                Output in JSON format
+  --verbose             Show detailed execution info
+  --all, -a             Show all (for search/update)
+  --category, -c <cat>  Filter by category
+  --check               Check only, don't install
+  --create-pr           Create PR for publishing
+  --upgrade, -u         Upgrade existing skill in marketplace
+
+MEMORY CONFIGURATION (ISH/Resource-Constrained Environments):
+  --ish-mode [on|off]           Force ISH mode (auto-detected by default)
+  --memory-limit <MB>           Heap memory limit in MB (default: 8MB for ISH, 100MB standard)
+  --memory-warning <MB>         Warning threshold in MB (default: 80% of limit)
+  --memory-critical <MB>        Critical threshold in MB (default: same as limit)
+  --memory-startup <MB>         Startup limit in MB (default: higher to allow init)
+  --memory-monitor [on|off]     Enable memory monitoring (auto-enabled for ISH)
+
+SERVER CONFIGURATION:
+  --port <port>                 Server port (default: 4096)
+  --host <hostname>             Server hostname (default: 127.0.0.1)
+  --opencode-dir <path>         Working directory (default: current)
+
+GENERAL OPTIONS:
+  --config <path>               Custom .pave config directory
+                                Default: ~/.pave (global)
+                                For 'agent' command: ./.pave (project-local, allows per-project config)
+  --debug                       Enable debug logging
+  --verbose                     Verbose output
+  --help, -h                    Show this help
+  --version, -v                 Show version
+
+EXAMPLES:
+  # Start PAVE TUI
+  pave
+
+  # Non-interactive chat
+  pave chat "What is 2+2?"
+  pave chat "Explain this error" --session new
+  pave chat "Hello" --model github-copilot/claude-sonnet-4
+  echo "Summarize this" | pave chat
+  cat file.txt | pave chat "Review this code"
+
+  # Send message to a running agent
+  pave chat -a github-watcher "check the error logs"
+  pave chat --agent gw "check logs"        # prefix matching
+  pave chat -a gw --urgent "stop, check production errors"
+
+  # Search marketplace
+  pave search email
+  pave search --all
+  pave search -c communication
+
+  # Install from marketplace
+  pave install gmail
+  pave install dropbox
+
+  # Install from GitHub
+  pave install cnrai/openpave-gmail
+
+  # Run a skill command
+  pave run gmail list --max 5
+  pave run gmail unread
+  pave run gmail read <messageId>
+
+  # Publish a skill
+  pave publish ./my-skill
+  pave publish --create-pr
+  pave publish --create-pr --upgrade   # Upgrade existing skill
+
+  # Update skills
+  pave update gmail
+  pave update --all
+
+  # List installed skills
+  pave list
+  pave list --json
+
+  # Remove a skill
+  pave remove gmail
+
+  # Use custom config directory (for agent command)
+  # Note: The agent command supports --config as an option
+  pave agent --config /tmp/.pave SOUL.md
+  pave agent --config "$HOME/work/.pave" --sleep 30m
+
+  # View conversation history
+  pave history                         # Current session history
+  pave history --list                  # List all sessions
+  pave history --session <id>          # Specific session
+  pave history --last 10               # Last 10 messages
+  pave history --export chat.md        # Export to markdown file
+  pave history --json                  # Output as JSON
+
+  # Run as autonomous agent
+  pave agent                            # Run with defaults (AGENTS.md, 1m sleep, ./.pave)
+  pave agent init                       # Initialize .pave directory with default permissions
+  pave agent init --config ./my-config  # Initialize at custom config path
+  pave agent SOUL.md --sleep 30m        # Check every 30 minutes
+  pave agent SOUL.md --name "OpenPAVE software engineer"
+  pave agent --soul ./agents/github-watcher.md --sleep 1h
+
+SKILL LOCATIONS:
+  Skills installed to:          ~/.pave/skills/<name>/
+  Lock file:                    ~/.pave/skills.lock.json
+  Registry cache:               ~/.pave/cache/registry.yaml
+  (Use --config to override ~/.pave)
+`);
+}
+
+function showVersion() {
+  // PAVE_VERSION is injected at build time by esbuild define
+  // It gets replaced with the actual version string
+  let version = '0.0.0'; // fallback
+
+  // Check if PAVE_VERSION was injected (it becomes a string literal)
+  if (typeof PAVE_VERSION === 'string') {
+    version = PAVE_VERSION;
+  } else {
+    // Fallback: try to read package.json (for development)
+    try {
+      const pkgPath = path.join(__dirname, '..', 'package.json');
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+      version = pkg.version || '0.0.0';
+    } catch (e) {
+      // Use fallback
+    }
+  }
+
+  console.log(`PAVE version ${version}`);
+  process.exit(0);
+}
+
+module.exports = {
+  parseArgs,
+  showHelp,
+  showVersion,
+};