@cnrai/pave 0.3.32 → 0.3.34

package/MARKETPLACE.md

@@ -0,0 +1,406 @@
+# OpenPave Skill Marketplace
+
+The OpenPave Skill Marketplace is a centralized registry for discovering, installing, and publishing PAVE skills. It uses GitHub Pages for the public-facing website and a simple YAML-based registry for skill metadata.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    GitHub Pages Marketplace                      │
+│               (cnrai.github.io/openpave-marketplace)             │
+├─────────────────────────────────────────────────────────────────┤
+│  registry.yaml        │  Static site (Jekyll/HTML)              │
+│  ┌─────────────────┐  │  ┌─────────────────────────────────────┐│
+│  │ - gmail         │  │  │  Browse skills, search, categories  ││
+│  │ - dropbox       │  │  │  Installation instructions          ││
+│  │ - exa           │  │  │  Auto-generated from registry.yaml  ││
+│  │ - ...           │  │  └─────────────────────────────────────┘│
+│  └─────────────────┘  │                                         │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                         pave CLI                                 │
+├─────────────────────────────────────────────────────────────────┤
+│  pave search <query>    │ Search marketplace registry           │
+│  pave install <name>    │ Lookup in registry → clone from GitHub│
+│  pave publish           │ Validate & add to registry via PR     │
+│  pave update <name>     │ Pull latest version from GitHub       │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Registry Location
+
+- **Repository**: `cnrai/openpave-marketplace`
+- **GitHub Pages URL**: `https://cnrai.github.io/openpave-marketplace`
+- **Raw Registry URL**: `https://raw.githubusercontent.com/cnrai/openpave-marketplace/main/registry.yaml`
+
+## CLI Commands
+
+### `pave search <query>`
+
+Search the marketplace for skills by name, description, or keywords.
+
+```bash
+# Search for email-related skills
+pave search email
+
+# Search for storage skills
+pave search storage
+
+# List all available skills
+pave search --all
+```
+
+### `pave install <source>`
+
+Install a skill from various sources. Priority order:
+
+| Source Type | Example | Description |
+|-------------|---------|-------------|
+| Registry name | `pave install gmail` | Lookup in marketplace → clone from GitHub |
+| GitHub shorthand | `pave install cnrai/openpave-gmail` | Direct clone from GitHub |
+| GitHub URL | `pave install https://github.com/cnrai/openpave-gmail` | Direct clone from URL |
+| Local path | `pave install ./my-skill` | Copy from local directory |
+
+```bash
+# Install from marketplace (recommended)
+pave install gmail
+pave install dropbox
+
+# Install from GitHub directly
+pave install cnrai/openpave-gmail
+
+# Install from local path (for development)
+pave install /path/to/my-skill
+pave install ./my-local-skill
+
+# Force reinstall
+pave install gmail --force
+```
+
+### `pave publish [path]`
+
+Publish a skill to the marketplace. This validates your skill and creates a pull request to add it to the registry.
+
+```bash
+# Publish current directory
+pave publish
+
+# Publish specific path
+pave publish ./my-skill
+
+# Publish with verbose output
+pave publish --verbose
+```
+
+**Requirements for publishing:**
+- Valid `skill.yaml` with required fields
+- Public GitHub repository
+- MIT or compatible license
+- README.md with usage instructions
+
+### `pave update <name>`
+
+Update an installed skill to the latest version from GitHub.
+
+```bash
+# Update a specific skill
+pave update gmail
+
+# Update all skills
+pave update --all
+
+# Check for updates without installing
+pave update --check
+```
+
+### `pave list`
+
+List installed skills.
+
+```bash
+pave list
+pave list --json
+```
+
+### `pave remove <name>`
+
+Remove an installed skill.
+
+```bash
+pave remove gmail
+```
+
+### `pave info <name>`
+
+Show detailed information about a skill.
+
+```bash
+pave info gmail
+pave info ./my-skill
+```
+
+## Registry Format
+
+The marketplace uses a YAML-based registry (`registry.yaml`):
+
+```yaml
+# OpenPave Skill Marketplace Registry
+version: 1
+updated: 2026-02-22T12:00:00Z
+
+skills:
+  gmail:
+    name: gmail
+    version: 1.0.0
+    description: Read and manage Gmail messages securely using OAuth
+    author: cnrai
+    repository: cnrai/openpave-gmail
+    category: communication
+    icon: "📧"
+    keywords:
+      - email
+      - gmail
+      - google
+      - inbox
+      - messages
+    published: 2026-02-21T00:00:00Z
+    
+  dropbox:
+    name: dropbox
+    version: 1.0.0
+    description: Access Dropbox files and Paper documents
+    author: cnrai
+    repository: cnrai/openpave-dropbox
+    category: storage
+    icon: "📦"
+    keywords:
+      - files
+      - cloud
+      - storage
+      - dropbox
+    published: 2026-02-21T00:00:00Z
+```
+
+### Registry Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Unique skill identifier (lowercase, hyphens only) |
+| `version` | Yes | Semver version (e.g., 1.0.0) |
+| `description` | Yes | Short description (max 100 chars) |
+| `author` | Yes | GitHub username or org |
+| `repository` | Yes | GitHub repo in `owner/repo` format |
+| `category` | Yes | One of: communication, storage, search, productivity, development, other |
+| `icon` | No | Emoji icon for display |
+| `keywords` | No | Array of search keywords |
+| `published` | Yes | ISO 8601 timestamp |
+
+## Skill Format (skill.yaml)
+
+Each skill must have a `skill.yaml` in its root directory:
+
+```yaml
+# Required fields
+name: gmail
+version: 1.0.0
+description: Read and manage Gmail messages securely using OAuth
+entrypoint: index.js
+pattern: sandbox
+
+# Author information
+author:
+  name: OpenPave
+  url: https://github.com/cnrai
+
+# License and links
+license: MIT
+homepage: https://github.com/cnrai/openpave-gmail
+repository: cnrai/openpave-gmail
+
+# Available commands
+commands:
+  - name: list
+    description: List recent messages
+    options:
+      - --max <number>
+      - --summary
+      - --json
+
+  - name: read
+    description: Read a specific message
+    args:
+      - <messageId>
+    options:
+      - --summary
+      - --json
+
+# Token configuration for secure API access
+tokens:
+  gmail:
+    type: oauth
+    description: Gmail API OAuth credentials
+    domains:
+      - gmail.googleapis.com
+      - "*.googleapis.com"
+    env:
+      required:
+        - GMAIL_CLIENT_ID
+        - GMAIL_CLIENT_SECRET
+        - GMAIL_REFRESH_TOKEN
+
+# Sandbox permissions
+permissions:
+  fs.read: []
+  fs.write: []
+  network:
+    - gmail.googleapis.com
+    - oauth2.googleapis.com
+  modules:
+    - fs
+    - path
+
+# Metadata
+category: communication
+icon: "📧"
+keywords:
+  - email
+  - gmail
+  - google
+```
+
+## Categories
+
+| Category | Description | Examples |
+|----------|-------------|----------|
+| `communication` | Email, messaging, notifications | gmail, slack, discord |
+| `storage` | File storage, cloud drives | dropbox, gdrive, s3 |
+| `search` | Web search, research tools | exa, google-search |
+| `productivity` | Calendar, tasks, notes | google-calendar, notion |
+| `development` | Code, git, CI/CD tools | github, gitlab |
+| `other` | Everything else | - |
+
+## Marketplace Repository Structure
+
+```
+cnrai/openpave-marketplace/
+├── registry.yaml           # Main skill registry
+├── skills/                  # Individual skill metadata (optional, for caching)
+│   ├── gmail.yaml
+│   ├── dropbox.yaml
+│   └── exa.yaml
+├── index.html              # Static site homepage
+├── _config.yml             # Jekyll config for GitHub Pages
+├── assets/
+│   └── style.css
+└── README.md
+```
+
+## Publishing Workflow
+
+### For Skill Authors
+
+1. **Create your skill repository** on GitHub (e.g., `yourname/openpave-myskill`)
+
+2. **Add required files:**
+   - `skill.yaml` - Skill manifest
+   - `index.js` - Main entrypoint
+   - `README.md` - Documentation
+   - `LICENSE` - MIT recommended
+
+3. **Test locally:**
+   ```bash
+   pave install ./my-skill
+   pave run myskill --help
+   ```
+
+4. **Publish to marketplace:**
+   ```bash
+   cd my-skill
+   pave publish
+   ```
+
+5. **Wait for PR approval** - maintainers will review and merge
+
+### For Maintainers
+
+1. Review incoming PRs to `cnrai/openpave-marketplace`
+2. Verify skill.yaml is valid
+3. Check repository exists and is accessible
+4. Test installation: `pave install owner/repo`
+5. Merge PR to add to registry
+
+## Local Development
+
+### Testing without marketplace
+
+```bash
+# Install from local path
+pave install ./my-skill
+
+# Run commands
+pave run myskill command --args
+
+# Check info
+pave info myskill
+```
+
+### Testing marketplace integration
+
+```bash
+# Set custom registry URL (for testing)
+PAVE_REGISTRY_URL=https://raw.githubusercontent.com/yourname/test-marketplace/main/registry.yaml pave search test
+
+# Or use local file
+PAVE_REGISTRY_FILE=./test-registry.yaml pave search test
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `PAVE_REGISTRY_URL` | Custom registry URL | `https://raw.githubusercontent.com/cnrai/openpave-marketplace/main/registry.yaml` |
+| `PAVE_REGISTRY_FILE` | Local registry file (overrides URL) | - |
+| `PAVE_CACHE_TTL` | Registry cache TTL in seconds | `3600` (1 hour) |
+
+### Cache Location
+
+The registry is cached locally to reduce network requests:
+
+```
+~/.pave/cache/
+├── registry.yaml           # Cached registry
+└── registry.meta.json      # Cache metadata (timestamp, etag)
+```
+
+## Error Handling
+
+### Common Errors
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `Skill not found in registry` | Skill name not in marketplace | Check spelling or install from GitHub URL |
+| `Repository not found` | GitHub repo doesn't exist | Verify repository URL |
+| `Invalid skill.yaml` | Missing required fields | Check skill.yaml format |
+| `Network error` | Can't reach GitHub | Check internet connection |
+
+## Node 16 Compatibility
+
+The marketplace module is designed for Node 16 compatibility:
+
+- Uses `https` module instead of `fetch`
+- Synchronous YAML parsing with `js-yaml`
+- No ES2022+ features
+- Works on iSH iOS
+
+## Future Enhancements
+
+- [ ] Skill ratings and reviews
+- [ ] Download statistics
+- [ ] Verified publisher badges
+- [ ] Automatic version updates
+- [ ] Dependency resolution between skills
+- [ ] Private/enterprise registries

package/README.md

@@ -1,40 +1,237 @@
-# @cnrai/pave
+# PAVE - Personal AI Virtual Environment
 
-PAVE - Personal AI Virtual Environment. AI agent framework for the terminal.
+PAVE combines an OpenCode-Lite server with a terminal UI client in a single process, specifically optimized for resource-constrained environments like iSH on iOS.
 
-## Installation
+## Features
 
+- **Resource-Efficient**: Runs smoothly on iSH iOS with Node 16
+- **Configurable Memory Management**: CLI arguments for fine-tuning memory limits
+- **Auto-Detection**: Automatically detects iSH environment and applies appropriate settings
+- **Terminal UI**: Real-time chat interface with markdown rendering
+- **Embedded Server**: No separate server process required
+
+## Quick Start
+
+### Standard Usage
+```bash
+node index.js
+```
+
+### ISH/iOS Usage
 ```bash
-npm install -g @cnrai/pave
+# Using startup script (recommended)
+./start-pave.sh
+
+# Or manually with garbage collection
+node --expose-gc index.js
 ```
 
-## Usage
+## CLI Options
+
+### Memory Configuration
+Perfect for ISH and other resource-constrained environments:
 
 ```bash
-pave                    # Launch TUI
-pave --help             # Show help
-pave --version          # Show version
-pave chat "question"    # Quick chat
+# Force ISH mode with custom memory limits
+node index.js --ish-mode --memory-limit 16 --memory-warning 12
+
+# Disable memory monitoring
+node index.js --memory-monitor off
+
+# Custom startup memory allowance (for large JS bundles)
+node index.js --memory-startup 64 --memory-limit 12
 ```
 
-### iSH (iOS)
+### Server Configuration
+```bash
+# Custom port and host
+node index.js --port 8080 --host 0.0.0.0
 
+# Custom working directory
+node index.js --opencode-dir /path/to/workspace
+```
+
+### Debug Options
 ```bash
-npm install -g @cnrai/pave
-node --expose-gc --jitless $(which pave)
+# Debug mode with verbose logging
+node index.js --debug --verbose
+
+# Help and version
+node index.js --help
+node index.js --version
 ```
 
-## Requirements
+## Memory Management Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--ish-mode [on\|off]` | Force ISH mode detection | Auto-detected |
+| `--memory-limit <MB>` | Heap memory limit | 8MB (ISH), 100MB (standard) |
+| `--memory-warning <MB>` | Warning threshold | 80% of limit |
+| `--memory-critical <MB>` | Critical threshold | Same as limit |
+| `--memory-startup <MB>` | Startup limit | Higher to allow init |
+| `--memory-monitor [on\|off]` | Enable monitoring | Auto (ISH=on) |
+
+## Environment Variables
+
+CLI arguments override environment variables:
+
+| Variable | CLI Override | Description |
+|----------|--------------|-------------|
+| `PORT` | `--port` | Server port (default: 4096) |
+| `HOST` | `--host` | Server hostname (default: 127.0.0.1) |
+| `OPENCODE_DIR` | `--opencode-dir` | Working directory |
+| `FORCE_ISH_MODE` | `--ish-mode` | Force ISH mode |
+| `DEBUG` | `--debug` | Enable debug logging |
+
+## ISH/iOS Optimization
+
+PAVE is specifically designed to run efficiently on iSH:
+
+### Automatic Detection
+```bash
+# These indicators trigger ISH mode:
+# - platform === 'linux'
+# - TERM_PROGRAM === 'iSH' 
+# - /etc/alpine-release exists
+# - Node version contains 'alpine'
+```
+
+### Memory Protection
+```bash
+# ISH mode automatically enables:
+# - 8MB heap limit (vs 100MB standard)
+# - Memory monitoring every 5 seconds
+# - Aggressive garbage collection
+# - Emergency cleanup on memory pressure
+# - Process termination before system crash
+```
+
+### Recommended ISH Setup
+```bash
+# Install with garbage collection support
+node --expose-gc index.js
+
+# Or use the startup script
+./start-pave.sh
+
+# For persistent use, create an alias
+echo 'alias pave="cd /path/to/pave && ./start-pave.sh"' >> ~/.profile
+```
+
+## Examples
+
+### Basic Usage
+```bash
+# Auto-detected environment
+node index.js
+
+# With debug logging
+node index.js --debug
+```
+
+### ISH Customization
+```bash
+# Conservative memory settings
+node index.js --memory-limit 6 --memory-warning 4
+
+# Higher startup allowance for large projects
+node index.js --memory-startup 32 --memory-limit 8
+
+# Force ISH mode for testing
+node index.js --ish-mode --debug
+```
+
+### Development Setup
+```bash
+# Custom server for development
+node index.js --port 3000 --host 0.0.0.0 --debug --verbose
+
+# Disable memory monitoring for debugging
+node index.js --memory-monitor off --debug
+```
 
-- Node.js >= 16.0.0
-- A GitHub Copilot subscription (for the AI backend)
+### Production ISH Setup
+```bash
+# Optimized for production use in iSH
+./start-pave.sh --memory-limit 12 --memory-warning 8
+```
 
-## Links
+## Startup Script
 
-- Source: https://github.com/cnrai/openpave
-- Issues: https://github.com/cnrai/openpave/issues
-- Homebrew (native binary): `brew tap cnrai/tap && brew install pave`
+The `start-pave.sh` script provides additional convenience:
 
-## License
+```bash
+# Standard startup with auto-detection
+./start-pave.sh
+
+# Force ISH mode
+./start-pave.sh --ish-mode
+
+# Custom memory limit
+./start-pave.sh --memory-limit 32
+
+# Debug mode
+./start-pave.sh --debug --verbose
+
+# Disable garbage collection
+./start-pave.sh --no-gc
+```
+
+## Troubleshooting
+
+### Memory Issues
+```bash
+# Check current memory usage
+node index.js --debug --verbose
+
+# Lower memory limits
+node index.js --memory-limit 6 --memory-warning 4
+
+# Disable monitoring temporarily
+node index.js --memory-monitor off
+```
+
+### ISH Detection Issues
+```bash
+# Force ISH mode
+node index.js --ish-mode
+
+# Check detection
+FORCE_ISH_MODE=true node index.js --debug
+```
+
+### Performance Issues
+```bash
+# Enable garbage collection
+node --expose-gc index.js
+
+# Use startup script
+./start-pave.sh
+
+# Check memory configuration
+node index.js --debug | grep -i memory
+```
+
+## Architecture
+
+PAVE runs OpenCode-Lite and the TUI client in the same Node.js process:
+
+1. **Server starts** with configurable memory limits
+2. **Console redirected** to log file to avoid TUI corruption  
+3. **TUI launches** and connects to embedded server
+4. **Memory monitoring** starts when first session is activated
+5. **Automatic cleanup** prevents memory exhaustion crashes
+
+This architecture is specifically designed for environments where:
+- Memory is extremely limited (8MB heap in iSH)
+- Process spawning is expensive
+- Terminal UI corruption must be avoided
+- Reliability is critical (no crashes in mobile environment)
+
+## Requirements
 
-MIT - Copyright (c) 2025 CNRAI
+- Node.js 16+ (tested extensively on iSH iOS)
+- 12MB+ available memory (8MB for heap + overhead)
+- Terminal with basic ANSI support
+- Optional: `--expose-gc` for optimal memory management