@cnrai/pave 0.3.35 → 0.3.51

package/MARKETPLACE.md

@@ -1,406 +0,0 @@
-# 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