@anytio/pspm 0.0.2 → 0.0.4

package/README.md

@@ -0,0 +1,265 @@
+# PSPM - Prompt Skill Package Manager
+
+A CLI for managing prompt skills across AI coding agents.
+
+## What is PSPM?
+
+PSPM (Prompt Skill Package Manager) is a package manager for prompt skills - small, discoverable capabilities packaged as `SKILL.md` files. Think of it as npm for AI agent skills.
+
+Skills are designed to work with any AI coding agent that supports the SKILL.md format, including Claude Code, Cursor, Windsurf, and others.
+
+## Installation
+
+```bash
+npm install -g @anytio/pspm
+```
+
+Or use with npx:
+
+```bash
+npx @anytio/pspm <command>
+```
+
+## Quick Start
+
+```bash
+# Login with your API key
+pspm login --api-key <your-api-key>
+
+# Add a skill to your project
+pspm add @user/username/skill-name
+
+# List installed skills
+pspm list
+
+# Install all skills from lockfile
+pspm install
+```
+
+## Commands
+
+### Authentication
+
+```bash
+pspm login --api-key <key>    # Authenticate with API key
+pspm logout                   # Clear stored credentials
+pspm whoami                   # Show current user info
+```
+
+### Skill Management
+
+```bash
+pspm add <specifier>          # Add and install a skill
+pspm remove <name>            # Remove an installed skill (alias: rm)
+pspm list                     # List installed skills (alias: ls)
+pspm install                  # Install all skills from lockfile (alias: i)
+pspm update                   # Update skills to latest compatible versions
+```
+
+**Specifier formats:**
+- `@user/username/skillname` - Latest version
+- `@user/username/skillname@2.0.0` - Specific version
+- `@user/username/skillname@^2.0.0` - Semver range
+
+### Publishing
+
+```bash
+pspm publish                  # Publish current directory as a skill
+pspm publish --bump patch     # Auto-bump version (major, minor, patch)
+pspm unpublish <spec> --force # Remove a published skill version
+```
+
+**Publish Output:**
+
+When publishing, PSPM displays detailed package information similar to npm:
+
+```
+pspm notice
+pspm notice 📦  my-skill@1.0.0
+pspm notice Tarball Contents
+pspm notice   5.1kB SKILL.md
+pspm notice   1.5kB package.json
+pspm notice Tarball Details
+pspm notice name:          my-skill
+pspm notice version:       1.0.0
+pspm notice filename:      my-skill-1.0.0.tgz
+pspm notice package size:  2.3kB
+pspm notice unpacked size: 6.6kB
+pspm notice shasum:        4bb744fcfa90b8b033feed3deaeeb00f3a4503e5
+pspm notice integrity:     sha512-DqQJaugblfE5A...
+pspm notice total files:   2
+pspm notice
+pspm notice Publishing to https://pspm.dev with tag latest
++ @user/username/my-skill@1.0.0
+Checksum: abc123...
+```
+
+### Configuration
+
+```bash
+pspm config show              # Show resolved configuration
+pspm config init              # Create .pspmrc in current directory
+```
+
+## Configuration
+
+PSPM uses a simple npm-like INI configuration format.
+
+### User Config (`~/.pspmrc`)
+
+```ini
+; PSPM Configuration
+registry = https://pspm.dev
+authToken = sk_...
+username = myuser
+```
+
+### Project Config (`.pspmrc`)
+
+Project-specific configuration (optional):
+
+```ini
+; Project-specific PSPM configuration
+registry = https://custom-registry.example.com
+```
+
+### Lockfile (`skill-lock.json`)
+
+```json
+{
+  "lockfileVersion": 1,
+  "registryUrl": "https://pspm.dev",
+  "skills": {
+    "@user/username/skillname": {
+      "version": "1.0.0",
+      "resolved": "https://pspm.dev/api/skills/@user/username/skillname/1.0.0/download",
+      "integrity": "sha256-..."
+    }
+  }
+}
+```
+
+### Configuration Resolution
+
+Configuration is resolved in priority order:
+
+1. **Environment Variables** (`PSPM_REGISTRY_URL`, `PSPM_API_KEY`) - Highest
+2. **Project Config** (`.pspmrc` in project directory)
+3. **User Config** (`~/.pspmrc`)
+4. **Defaults** - Lowest
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `PSPM_REGISTRY_URL` | Override registry URL |
+| `PSPM_API_KEY` | Override API key |
+| `PSPM_DEBUG` | Enable debug logging |
+
+## Error Handling
+
+PSPM provides clear, actionable error messages:
+
+**Version Conflict:**
+```
+pspm error code E403
+pspm error 403 403 Forbidden - You cannot publish over the previously published versions: 1.0.0.
+Error: [BAD_REQUEST] Version 1.0.0 must be greater than existing version 1.0.0
+```
+
+**Validation Errors:**
+```
+Error: Validation failed:
+  - name: Skill name must start with a letter and contain only lowercase letters, numbers, and hyphens
+  - version: Invalid semver version
+```
+
+**Authentication Errors:**
+```
+Error: Not logged in. Run 'pspm login --api-key <key>' first, or set PSPM_API_KEY env var.
+```
+
+## Directory Structure
+
+```
+project/
+├── .pspmrc              # Project config (optional)
+├── skill-lock.json      # Lockfile
+└── .skills/             # Installed skills
+    └── username/
+        └── skillname/
+            ├── SKILL.md
+            └── ...
+
+~/
+└── .pspmrc              # User config
+```
+
+## Creating a Skill
+
+A skill is a directory containing at minimum a `package.json` and `SKILL.md`:
+
+```
+my-skill/
+├── package.json         # Required: name, version
+├── SKILL.md             # Required: skill instructions
+├── runtime/             # Optional: runtime files
+├── scripts/             # Optional: scripts
+└── data/                # Optional: data files
+```
+
+**package.json:**
+```json
+{
+  "name": "@user/myusername/my-skill",
+  "version": "1.0.0",
+  "description": "A helpful skill for...",
+  "files": ["package.json", "SKILL.md", "runtime", "scripts", "data"]
+}
+```
+
+**SKILL.md:**
+```markdown
+---
+name: my-skill
+description: A helpful skill that does X
+---
+
+# Instructions
+
+When activated, this skill helps you...
+```
+
+## CI/CD Integration
+
+```bash
+# Use environment variables
+export PSPM_API_KEY=sk_ci_key
+export PSPM_REGISTRY_URL=https://registry.example.com/api/skills
+
+# Install with frozen lockfile (fails if lockfile is outdated)
+pspm install --frozen-lockfile
+```
+
+## Using Different Registries
+
+Use environment variables to switch between registries:
+
+```bash
+# Development
+PSPM_REGISTRY_URL=https://staging.example.com pspm add @user/bsheng/skill
+
+# Production
+PSPM_REGISTRY_URL=https://prod.example.com pspm publish
+```
+
+Or set the registry in your project's `.pspmrc`:
+
+```ini
+; .pspmrc
+registry = https://custom-registry.example.com
+```
+
+## License
+
+See LICENSE file.