@anytio/pspm 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,221 @@
+# Changelog
+
+All notable changes to the PSPM CLI will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-01-23
+
+### Changed
+
+- **License changed to The Artistic License 2.0** - Same license used by npm, providing a balance between open source availability and artistic control
+- **Version reset to 0.2.0** - First public open source release
+
+## [0.1.1] - 2026-01-23
+
+### Added
+
+- **Multiple package support for `add` command**: Install multiple packages in a single command
+  - `pspm add pkg1 pkg2 pkg3` - Add multiple packages at once
+  - Continues with remaining packages if one fails
+  - Shows summary of successes/failures when adding multiple packages
+
+- **Multiple package support for `install` command**: npm-like behavior
+  - `pspm install pkg1 pkg2` - Add and install specific packages (delegates to `add`)
+  - `pspm install` (no args) - Install from lockfile (original behavior)
+  - Mirrors npm's install command behavior
+
+### Changed
+
+- **Validation before agent selection**: Packages are now validated before prompting for agent selection
+  - Resolves and validates all packages first
+  - Only prompts for agents after validation succeeds
+  - Prevents wasted time selecting agents for non-existent packages
+
+- **Default agents changed to all agents**: When using `-y` flag or defaults
+  - Previously defaulted to `claude-code` only
+  - Now defaults to all built-in agents: `claude-code`, `codex`, `cursor`, `gemini`, `kiro`, `opencode`
+  - Use `--agent claude-code` to install for a single agent
+
+## [0.1.0] - 2026-01-23
+
+### Added
+
+- **GitHub dependencies**: Install skills directly from GitHub repositories
+  - `pspm add github:owner/repo` - Install entire repository
+  - `pspm add github:owner/repo/path` - Install specific subdirectory
+  - `pspm add github:owner/repo@ref` - Pin to branch, tag, or commit
+  - GitHub packages stored in `.pspm/skills/_github/{owner}/{repo}/`
+  - `githubDependencies` section in `pspm.json`
+  - `githubPackages` section in lockfile (version 3)
+
+- **Multi-agent symlink support**: Link skills to multiple AI agent configurations
+  - `--agent` flag on `add`, `install`, and `link` commands
+  - Default agents: `claude-code` (`.claude/skills/`), `cursor` (`.cursor/skills/`), `codex` (`.codex/skills/`)
+  - Custom agent configurations in `pspm.json` under `agents` field
+  - Relative symlinks for portability across machines
+  - `--agent none` to skip symlink creation
+
+- **New `link` command**: Recreate agent symlinks without reinstalling
+  - `pspm link` - Recreate symlinks for all installed skills
+  - `pspm link --agent claude-code,cursor` - Link to specific agents
+
+- **Enhanced `list` command**: Shows source type and linked agents
+  - Displays whether skill is from registry or GitHub
+  - Shows which agents have symlinks to each skill
+
+### Changed
+
+- Lockfile version bumped to 3 to support `githubPackages`
+- `install` command now processes both registry and GitHub dependencies
+- `remove` command now cleans up symlinks from all configured agents
+
+## [0.0.7] - 2026-01-23
+
+### Added
+
+- **Public packages support**: Packages can now be made public, allowing anyone to download without authentication
+  - New `pspm access` command to change package visibility
+  - `--access` flag on `pspm publish` to set visibility during publish
+  - Public packages can be installed without authentication
+  - Visibility change is one-way: public packages cannot be made private again (npm-style)
+
+- **Multi-registry authentication**: npm-style configuration for multiple registries
+  - Scope-to-registry mappings: `@myorg:registry = https://corp.pspm.io`
+  - Per-registry auth tokens: `//pspm.dev:authToken = sk_xxx`
+  - Automatic token selection based on registry URL
+
+- **Auth-optional downloads**: `pspm add` and `pspm install` no longer require authentication for public packages
+  - Private packages still require authentication
+  - Clear error messages when authentication is needed
+
+### Changed
+
+- Configuration format extended to support multi-registry authentication
+- SDK `apiKey` is now optional to support public package downloads
+- Directory structure changed: skills now installed to `.pspm/skills/` (previously `.skills/`)
+- Lockfile path changed to `pspm-lock.json` (previously `skill-lock.json`)
+
+## [0.0.6] - 2026-01-22
+
+### Changed
+
+- Fixed presigned R2 download URLs to skip auth headers
+- Use versionInfo.downloadUrl instead of manual URL construction
+
+## [0.0.5] - 2026-01-22
+
+### Changed
+
+- **BREAKING: Simplified configuration to npm-like INI format**
+  - Config file moved from `~/.pspm/config.json` to `~/.pspmrc`
+  - Uses INI format (like `.npmrc`) instead of JSON
+  - Automatic migration from old config on first run
+  - Project config `.pspmrc` now uses INI format
+
+- **BREAKING: Removed profile system**
+  - Removed commands: `config list`, `config add`, `config use`, `config set`, `config delete`
+  - Removed `--profile` global flag
+  - Removed `PSPM_PROFILE` environment variable
+  - Use `PSPM_REGISTRY_URL` and `PSPM_API_KEY` env vars to switch registries
+
+### Simplified Config Format
+
+**Before (v0.0.4):**
+```json
+{
+  "version": 2,
+  "defaultProfile": "default",
+  "profiles": {
+    "default": {
+      "registryUrl": "https://pspm.dev",
+      "apiKey": "sk_...",
+      "username": "myuser"
+    }
+  }
+}
+```
+
+**After (v0.0.5):**
+```ini
+; PSPM Configuration
+registry = https://pspm.dev
+authToken = sk_...
+username = myuser
+```
+
+### Migration
+
+Existing users will have their config automatically migrated on first run. Only the default profile credentials are preserved. If you used multiple profiles, use environment variables instead:
+
+```bash
+# Instead of: pspm add --profile production
+PSPM_REGISTRY_URL=https://prod.example.com pspm add @user/skill
+```
+
+## [0.0.4] - 2026-01-22
+
+### Added
+
+- **npm-style publish output**: Display detailed package information when publishing, including:
+  - Package name and version
+  - Tarball contents with file sizes
+  - Tarball details (filename, package size, unpacked size, shasum, integrity hash, total files)
+  - Publishing destination URL
+- **Improved error messages**: npm-style E403 error codes for version conflicts
+
+### Changed
+
+- Publish output now uses `pspm notice` prefix for consistency with npm
+- Success message format changed to `+ @user/username/skill@version`
+- Default registry URL simplified from `https://pspm.dev/api/skills` to `https://pspm.dev`
+
+## [0.0.3] - 2026-01-21
+
+### Added
+
+- Browser-based OAuth login flow with local callback server
+- Support for CLI token exchange via `/api/api-keys/cli-token-exchange`
+- Structured error handling with `extractApiErrorMessage` helper
+- Debug mode via `PSPM_DEBUG` environment variable
+
+### Fixed
+
+- CLI URL duplication issue when registry URL already contains path
+- Server error handling now uses `app.onError` for reliable error responses
+- API error messages now properly extract and display validation details
+
+### Changed
+
+- Migrated from oRPC client to generated SDK using Orval
+- Improved error message formatting for validation errors
+
+## [0.0.2] - 2026-01-20
+
+### Added
+
+- Multi-profile configuration support
+- Project-level `.pspmrc` configuration file
+- Environment variable overrides (`PSPM_PROFILE`, `PSPM_REGISTRY_URL`, `PSPM_API_KEY`)
+- `config` subcommands: `list`, `show`, `add`, `use`, `set`, `delete`, `init`
+- Lockfile support with `skill-lock.json`
+- `--frozen-lockfile` option for CI/CD environments
+- `update` command for updating skills to latest compatible versions
+- `unpublish` command for removing published skill versions
+
+### Changed
+
+- Configuration format updated to version 2 with profile support
+- Skills now installed to `.skills/{username}/{name}/` directory structure
+
+## [0.0.1] - 2026-01-19
+
+### Added
+
+- Initial release
+- Core commands: `login`, `logout`, `whoami`
+- Skill management: `add`, `remove`, `list`, `install`
+- Publishing: `publish` with `--bump` option
+- Basic configuration with `~/.pspm/config.json`
+- Semver range support for skill specifiers

package/CLI_GUIDE.md

@@ -0,0 +1,465 @@
+# PSPM CLI Guide
+
+PSPM (Prompt Skill Package Manager) is a CLI tool for managing prompt skills across AI coding agents. It provides commands for authentication, configuration, skill management, and publishing.
+
+## Installation
+
+```bash
+# Install globally
+npm install -g @anytio/pspm
+
+# Or use with npx
+npx @anytio/pspm <command>
+```
+
+## Command Reference
+
+```
+Usage: pspm [options] [command]
+
+Prompt Skill Package Manager for AI coding agents
+
+Options:
+  -V, --version                              output the version number
+  -h, --help                                 display help for command
+
+Commands:
+  config                                     Manage PSPM configuration
+  login [options]                            Log in via browser or with an API key
+  logout                                     Log out and clear stored credentials
+  whoami                                     Show current user information
+  init [options]                             Create a new pspm.json manifest in the current directory
+  migrate [options]                          Migrate from old directory structure (.skills/, skill-lock.json)
+  add [options] <specifiers...>              Add one or more skills
+  remove|rm <name>                           Remove an installed skill
+  list|ls [options]                          List installed skills
+  install|i [options] [specifiers...]        Install skills from lockfile, or add and install specific packages
+  link [options]                             Recreate agent symlinks without reinstalling
+  update [options]                           Update all skills to latest compatible versions
+  publish [options]                          Publish current directory as a skill
+  unpublish [options] <specifier>            Remove a published skill version (only within 72 hours of publishing)
+  access [options] [specifier]               Change package visibility (public/private)
+  deprecate [options] <specifier> [message]  Mark a skill version as deprecated (alternative to unpublish after 72 hours)
+  help [command]                             display help for command
+```
+
+## Authentication
+
+### Login
+
+Authenticate with an API key:
+
+```bash
+pspm login --api-key <key>
+```
+
+Or use browser-based OAuth:
+
+```bash
+pspm login
+```
+
+### Logout
+
+Remove stored credentials:
+
+```bash
+pspm logout
+```
+
+### Who Am I
+
+Display current user information:
+
+```bash
+pspm whoami
+
+# Output:
+#   Username: myuser
+#   User ID: user_123
+#   Registry: https://pspm.dev
+```
+
+## Configuration
+
+### Show Configuration
+
+Display resolved configuration and config file locations:
+
+```bash
+pspm config show
+
+# Output:
+#   Resolved Configuration:
+#
+#     Registry URL:   https://pspm.dev
+#     API Key:        ***
+#     Username:       myuser
+#
+#   Config Locations:
+#     User config:    /Users/you/.pspmrc
+#     Project config: (none)
+#
+#   Environment Variables:
+#     PSPM_REGISTRY_URL: (not set)
+#     PSPM_API_KEY:      (not set)
+```
+
+### Initialize Project Config
+
+Create a `.pspmrc` file in the current directory:
+
+```bash
+pspm config init
+pspm config init --registry https://custom.example.com
+```
+
+## Project Initialization
+
+### Initialize Manifest
+
+Create a new `pspm.json` manifest file in the current directory:
+
+```bash
+pspm init                          # Interactive prompts
+pspm init -y                       # Use defaults, skip prompts
+pspm init -n my-skill              # Specify name
+pspm init -d "My skill"            # Specify description
+pspm init -a "Your Name"           # Specify author
+pspm init -f                       # Overwrite existing pspm.json
+```
+
+### Migrate from Old Structure
+
+Migrate from old directory structure (`.skills/`, `skill-lock.json`):
+
+```bash
+pspm migrate                       # Perform migration
+pspm migrate --dry-run             # Preview changes without applying
+```
+
+## Skill Management
+
+### Add Skill
+
+Add a skill to the project and install it:
+
+```bash
+pspm add <specifier> [--agent <agents>]
+
+# Registry specifier formats:
+pspm add @user/bsheng/vite_slides           # Latest version
+pspm add @user/bsheng/vite_slides@2.0.0     # Specific version
+pspm add @user/bsheng/vite_slides@^2.0.0    # Semver range
+
+# GitHub specifier formats:
+pspm add github:owner/repo                  # Entire repo, default branch
+pspm add github:owner/repo@main             # Entire repo, specific branch
+pspm add github:owner/repo/path/to/skill    # Subdirectory, default branch
+pspm add github:owner/repo/path@v1.0.0      # Subdirectory with tag/ref
+
+# Add multiple skills at once:
+pspm add @user/alice/skill1 @user/bob/skill2
+
+# Agent options:
+pspm add @user/skill --agent claude-code,cursor  # Link to multiple agents
+pspm add github:owner/repo --agent none          # Skip symlink creation
+pspm add @user/skill -y                          # Skip agent selection prompt
+```
+
+### Remove Skill
+
+```bash
+pspm remove <name>
+pspm rm <name>
+
+# Examples:
+pspm remove vite_slides
+pspm rm @user/bsheng/vite_slides
+```
+
+### List Skills
+
+```bash
+pspm list
+pspm ls
+
+# JSON output for scripting
+pspm list --json
+
+# Example output:
+# Installed skills:
+#
+#   @user/alice/code-review@1.2.0 (registry)
+#     -> .claude/skills/code-review
+#
+#   github:owner/repo/skills/react-tips (main@abc1234)
+#     -> .claude/skills/react-tips, .cursor/skills/react-tips
+#
+# Total: 2 skill(s) (1 registry, 1 github)
+```
+
+### Install Skills
+
+Install all skills from the lockfile:
+
+```bash
+pspm install
+pspm i
+
+# With options:
+pspm install --frozen-lockfile           # CI/CD mode - fail if lockfile missing
+pspm install --dir ./vendor/skills       # Install to specific directory
+pspm install --agent claude-code,cursor  # Link to multiple agents
+pspm install --agent none                # Skip symlink creation
+pspm install -y                          # Skip agent selection prompt
+
+# Install specific packages (like npm):
+pspm install @user/alice/skill1 github:org/repo
+```
+
+### Link Skills
+
+Recreate agent symlinks without reinstalling (useful after adding agents):
+
+```bash
+pspm link
+pspm link --agent claude-code,cursor  # Link to specific agents
+pspm link -y                          # Skip agent selection prompt
+```
+
+### Update Skills
+
+```bash
+pspm update
+pspm update --dry-run    # Preview updates without applying
+```
+
+## Publishing
+
+### Publish Skill
+
+Publish the current directory as a skill:
+
+```bash
+pspm publish
+pspm publish --bump patch    # Auto-bump version (major, minor, patch)
+pspm publish --bump minor --tag beta
+pspm publish --access public # Publish and make public in one step
+```
+
+**Required `pspm.json` fields:**
+- `name` - Skill name (e.g., `@user/username/skillname`)
+- `version` - Semver version
+
+**Optional `pspm.json` fields:**
+- `description` - Skill description
+- `author` - Author name
+- `files` - Files to include (default: `["pspm.json", "SKILL.md", "runtime", "scripts", "data"]`)
+
+### Unpublish Skill
+
+Remove a published skill version (only within 72 hours of publishing):
+
+```bash
+pspm unpublish <specifier> --force
+
+# Delete specific version
+pspm unpublish @user/bsheng/vite_slides@2.0.0 --force
+
+# Delete all versions
+pspm unpublish @user/bsheng/vite_slides --force
+```
+
+### Deprecate Skill
+
+Mark a skill version as deprecated (alternative to unpublish after 72 hours):
+
+```bash
+pspm deprecate <specifier> [message]
+
+# Deprecate with message
+pspm deprecate @user/bsheng/old-skill@1.0.0 "Use @user/bsheng/new-skill instead"
+
+# Remove deprecation
+pspm deprecate @user/bsheng/old-skill@1.0.0 --undo
+```
+
+## Visibility
+
+### Change Package Visibility
+
+Change a package's visibility between public and private:
+
+```bash
+# Make current package public
+pspm access --public
+
+# Make specific package public
+pspm access @user/bsheng/vite_slides --public
+```
+
+**Important:** Making a package public is irreversible (following npm conventions). Public packages cannot be made private again.
+
+- **Private packages** (default): Require authentication to download
+- **Public packages**: Anyone can download without authentication
+
+## Configuration Files
+
+### User Config: `~/.pspmrc`
+
+INI format configuration file:
+
+```ini
+; PSPM Configuration
+
+registry = https://pspm.dev
+authToken = sk_...
+username = myuser
+
+; Multi-registry: Scope mappings (optional)
+@myorg:registry = https://corp.pspm.io
+
+; Multi-registry: Per-registry tokens (optional)
+//pspm.dev:authToken = sk_public_token
+//corp.pspm.io:authToken = sk_corp_token
+```
+
+### Project Config: `.pspmrc`
+
+Project-specific configuration (optional):
+
+```ini
+; Project-specific PSPM configuration
+
+registry = https://custom.example.com
+```
+
+### Manifest: `pspm.json`
+
+Package manifest file (created with `pspm init`):
+
+```json
+{
+  "name": "@user/username/my-skill",
+  "version": "1.0.0",
+  "description": "A helpful skill for...",
+  "author": "Your Name",
+  "files": ["pspm.json", "SKILL.md", "runtime", "scripts", "data"]
+}
+```
+
+### Lockfile: `pspm-lock.json`
+
+```json
+{
+  "lockfileVersion": 3,
+  "registryUrl": "https://pspm.dev",
+  "packages": {
+    "@user/bsheng/vite_slides": {
+      "version": "2.0.0",
+      "resolved": "https://pspm.dev/...",
+      "integrity": "sha256-abc123..."
+    }
+  },
+  "githubPackages": {
+    "github:owner/repo/path": {
+      "version": "abc1234",
+      "resolved": "https://github.com/owner/repo",
+      "integrity": "sha256-...",
+      "gitCommit": "abc1234567890...",
+      "gitRef": "main"
+    }
+  }
+}
+```
+
+## 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 | Purpose |
+|----------|---------|
+| `PSPM_API_KEY` | Override API key |
+| `PSPM_DEBUG` | Enable debug logging |
+| `GITHUB_TOKEN` | GitHub token for private repos and higher rate limits |
+
+## Directory Structure
+
+```
+project/
+├── .pspmrc              # Project config (optional)
+├── pspm.json            # Manifest with dependencies
+├── pspm-lock.json       # Lockfile
+├── .pspm/
+│   ├── skills/          # Installed skills
+│   │   ├── {username}/  # Registry skills
+│   │   │   └── {skillname}/
+│   │   └── _github/     # GitHub skills
+│   │       └── {owner}/
+│   │           └── {repo}/
+│   │               └── {path}/
+│   └── cache/           # Tarball cache
+├── .claude/
+│   └── skills/          # Symlinks for claude-code agent
+└── .cursor/
+    └── skills/          # Symlinks for cursor agent (if configured)
+
+~/
+└── .pspmrc              # User config
+```
+
+## Common Workflows
+
+### CI/CD Integration
+
+```bash
+# Use environment variable for authentication
+export PSPM_API_KEY=sk_ci_key
+
+# Install with frozen lockfile (fails if lockfile missing or outdated)
+pspm install --frozen-lockfile
+```
+
+### Publishing Workflow
+
+```bash
+# Initialize a new skill
+pspm init
+
+# Edit pspm.json and create SKILL.md
+# Then publish with auto-bump
+pspm publish --bump patch
+```
+
+## Troubleshooting
+
+| Error | Solution |
+|-------|----------|
+| "Not logged in" | Run `pspm login --api-key <key>` |
+| "Invalid skill specifier" | Use format: `@user/{username}/{name}[@version]` |
+| "No lockfile found" | Run `pspm add <specifier>` first |
+
+Enable debug mode for detailed output:
+
+```bash
+PSPM_DEBUG=1 pspm <command>
+```
+
+## Migration from v0.0.3
+
+If you have an existing `~/.pspm/config.json` from v0.0.3 or earlier, PSPM will automatically migrate your configuration to the new `~/.pspmrc` INI format on first run.
+
+The migration will:
+1. Extract credentials from your default profile
+2. Create a new `~/.pspmrc` file
+3. Remove the old `~/.pspm/config.json`
+
+Use `pspm migrate` to migrate project-level files from old directory structure (`.skills/`, `skill-lock.json`).