@spectrl/cli 0.6.1 → 0.6.3

package/README.md

@@ -1,14 +1,17 @@
-# Spectrl
+# Spectrl CLI
 
-Spectrl is a local-first spec registry that treats structured documents (PRDs, TDDs, ADRs) as versioned, installable packages. Think npm for your documentation.
+> Local-first spec registry with public registry support
 
-**Key benefits:**
+Spectrl is a command-line tool for managing structured documents (PRDs, TDDs, ADRs, etc.) as versioned, installable specs. It supports both local-first development and public registry sharing.
 
-- **Local-first**: Works offline, all data in your repo
-- **Reproducible**: Content hashing ensures deterministic state
-- **Composable**: Specs can depend on other specs
-- **Agent-readable**: Schema-defined for LLM workflows
-- **Backend-optional**: No server required
+## Features
+
+- 📦 **Local-first**: All data lives in your repo, works offline
+- 🔄 **Reproducible**: Deterministic registry state
+- 🧩 **Composable**: Specs can depend on other specs
+- 🤖 **Agent-readable**: Schema-defined structure for LLMs
+- 🌐 **Public registry**: Share and discover specs globally
+- 🔐 **Secure authentication**: GitHub OAuth with device flow
 
 ## Installation
 
@@ -16,428 +19,590 @@ Spectrl is a local-first spec registry that treats structured documents (PRDs, T
 npm install -g @spectrl/cli
 ```
 
-Or use directly with npx (no installation required):
-
-```bash
-npx @spectrl/cli init
-```
-
-**Requirements:**
-
-- Node.js 20+ or Bun
-
 ## Quick Start
 
-### 1. Create a spec (in a separate location)
+### Local Development
 
 ```bash
-cd ~/specs  # Or any location outside your project
-spectrl new my-feature
-# Created my-feature/spectrl.json
-```
-
-Add your documentation files and update the `files` array in `spectrl.json`.
+# Initialize a new project
+spectrl init
 
-### 2. Publish to local registry
+# Create a new spec
+spectrl new my-api-spec --description "REST API specification"
 
-```bash
-cd my-feature
+# Publish to local registry
 spectrl publish
-# Published my-feature@0.1.0
-```
 
-### 3. Initialize your project
-
-```bash
-cd /path/to/your/project
-spectrl init
-# Created .spectrl/spectrl-index.json
-# Would you like to create AGENTS.md? (y/n)
+# Install from local registry
+spectrl install my-api-spec
 ```
 
-### 4. Install the spec
+### Public Registry
 
 ```bash
-spectrl install my-feature
-# Resolving my-feature... found version 0.1.0
-# Installed my-feature@0.1.0
-# Updated .spectrl/spectrl-index.json
-```
+# Authenticate with GitHub
+spectrl login
 
-## Core Concepts
+# Publish to public registry
+spectrl publish
+# Choose "Public registry" when prompted
 
-Spectrl applies package manager principles to structured documentation:
+# Search for specs
+spectrl search api
 
-- **Manifest** (`spectrl.json`): Defines a spec with name, version, files, and dependencies
-- **Registry** (`~/.spectrl/registry/`): Local storage for published specs with content hashing
-- **Project Index** (`.spectrl/spectrl-index.json`): Lists installed specs with sources and hashes
-- **Lock File** (`.spectrl/lock.json`): Captures resolved dependency tree
+# Get spec information
+spectrl info alice/api-spec
 
-**Version Control:** Commit `.spectrl/spectrl-index.json` and `.spectrl/lock.json` (like `package.json` and `package-lock.json`). Add `.spectrl/specs/` to `.gitignore` (like `node_modules/`).
+# Install from public registry
+spectrl install alice/api-spec
 
-## Commands
+# List all installed specs
+spectrl list
+```
 
-### `spectrl init`
+## Commands
 
-Initialize a new project index.
+### Project Management
 
-```bash
-spectrl init
-```
+#### `spectrl init`
 
-Creates `.spectrl/spectrl-index.json` in the current directory.
+Initialize a new project with a local spec index.
 
-**Options:**
+```bash
+spectrl init [options]
 
-- `--skip-agents` - Skip AGENTS.md creation
-- `--force-agents` - Create/append AGENTS.md without prompting
+Options:
+  --skip-agents    Skip AGENTS.md creation/update entirely
+  --force-agents   Force overwrite AGENTS.md with fresh template
+```
 
 **Example:**
 
 ```bash
 spectrl init
-# Created .spectrl/spectrl-index.json
-# Would you like to create AGENTS.md? (y/n)
+# Creates .spectrl/index.json and AGENTS.md
 ```
 
-### `spectrl new`
+#### `spectrl new <name>`
 
 Create a new spec with a manifest template.
 
 ```bash
 spectrl new <name> [options]
-```
 
-**Arguments:**
+Arguments:
+  name             Name of the spec (lowercase alphanumeric with hyphens)
 
-- `<name>` - Spec name (lowercase alphanumeric with hyphens)
-
-**Options:**
-
-- `--version <version>` - Initial version (default: `0.1.0`)
-- `--description <desc>` - Spec description
+Options:
+  --version        Initial version (default: 0.1.0)
+  --description    Description of the spec
+```
 
 **Example:**
 
 ```bash
-spectrl new user-auth --version 1.0.0 --description "User authentication system"
-# Created user-auth/spectrl.json
+spectrl new api-spec --version 1.0.0 --description "REST API specification"
+# Creates spectrl.json and basic file structure
 ```
 
-### `spectrl publish`
+### Local Registry
 
-Publish the current spec to the local registry.
+#### `spectrl publish`
+
+Publish a spec to local or public registry.
 
 ```bash
 spectrl publish
 ```
 
-Run from a directory containing `spectrl.json`. Publishes to `~/.spectrl/registry/{name}/{version}/` with content hash.
+**Interactive prompts:**
+
+- Choose destination: Local registry or Public registry
+- For public: Requires authentication (`spectrl login`)
 
 **Example:**
 
 ```bash
 spectrl publish
-# Published my-feature@1.0.0
+? Where do you want to publish?
+❯ Local registry (~/.spectrl/registry/)
+  Public registry (registry.spectrl.dev)
 ```
 
-### `spectrl install`
+#### `spectrl install [spec]`
 
-Install specs from the local registry.
+Install specs from local or public registry.
 
 ```bash
-# Restore all specs from project index
+spectrl install [spec]
+
+Arguments:
+  spec    Optional spec reference to install
+          - Local: my-spec or my-spec@1.0.0
+          - Public: username/spec or username/spec@1.0.0
+```
+
+**Examples:**
+
+```bash
+# Install all specs from project index
 spectrl install
 
-# Install specific spec (latest version)
-spectrl install <name>
+# Install from local registry
+spectrl install my-spec@1.0.0
 
-# Install specific version
-spectrl install <name>@<version>
+# Install from public registry
+spectrl install alice/api-spec
+spectrl install alice/api-spec@2.1.0
 ```
 
-**Options:**
+### Authentication
 
-- `--registry <path>` - Custom registry path (default: `~/.spectrl/registry`)
+#### `spectrl login`
 
-**Example:**
+Authenticate with GitHub to access the public registry.
 
 ```bash
-spectrl install user-auth
-# Resolving user-auth... found version 2.1.0
-# Installed user-auth@2.1.0
-# Updated .spectrl/spectrl-index.json
+spectrl login
 ```
 
-## Workflows
+**Flow:**
 
-### Team Collaboration
+1. Opens browser to GitHub device authorization
+2. Enter the displayed code
+3. Authorize Spectrl application
+4. Token stored securely in OS keychain
 
-Share specs across team members using the project index and lock file.
+**Example:**
 
 ```bash
-# Developer A: Publish and install specs in project
-cd my-feature
-spectrl publish
+spectrl login
+Initiating GitHub authentication...
 
-cd /path/to/project
-spectrl install my-feature@1.0.0
-# Installed my-feature@1.0.0
-# Updated .spectrl/spectrl-index.json
+Please visit: https://github.com/login/device
+Enter code: ABCD-1234
 
-spectrl install base-spec
-# Resolving base-spec... found version 2.0.0
-# Installed base-spec@2.0.0
+Opening browser...
+Waiting for authorization...
+✓ Logged in as alice
+```
 
-# Commit index and lock file (like package.json and package-lock.json)
-git add .spectrl/spectrl-index.json .spectrl/lock.json
-git commit -m "Add specs"
-git push
+#### `spectrl logout`
 
-# Developer B: Clone and restore all specs from index
-git clone <repo>
-cd <repo>
-spectrl install
-# Installed my-feature@1.0.0
-# Installed base-spec@2.0.0
+Remove stored GitHub authentication token.
+
+```bash
+spectrl logout
 ```
 
-### Multi-File Spec
+#### `spectrl whoami`
 
-Bundle related documents together in a single spec.
+Show current authenticated GitHub user.
 
 ```bash
-# Create spec directory structure
-mkdir -p my-feature/docs
-
-# Add documentation files
-cat > my-feature/docs/prd.md << 'EOF'
-# Product Requirements
-...
-EOF
-
-cat > my-feature/docs/tdd.md << 'EOF'
-# Technical Design
-...
-EOF
-
-# Create manifest with multiple files and dependencies
-cat > my-feature/spectrl.json << 'EOF'
-{
-  "name": "user-auth",
-  "version": "1.0.0",
-  "description": "User authentication feature spec",
-  "files": ["docs/prd.md", "docs/tdd.md"],
-  "dependencies": {"security-standards": "2.0.0"}
-}
-EOF
-
-# Publish to registry
-cd my-feature
-spectrl publish
-# Published user-auth@1.0.0
+spectrl whoami
 ```
 
-## File Formats
+**Examples:**
 
-### Manifest (`spectrl.json`)
-
-Defines a spec. **Required:** `name`, `version`, `files`.
+```bash
+spectrl whoami
+Logged in as alice
 
-```json
-{
-  "name": "spec-name",
-  "version": "1.0.0",
-  "description": "What this spec contains",
-  "files": ["doc1.md", "doc2.md"],
-  "dependencies": {
-    "other-spec": "1.0.0"
-  }
-}
+# When not logged in
+spectrl whoami
+Not logged in
+Run: spectrl login
 ```
 
-**Fields:**
-
-- `name` (required): Lowercase alphanumeric with hyphens
-- `version` (required): Semantic version (e.g., `1.0.0`)
-- `files` (required): Array of relative file paths (no `..`)
-- `description` (optional): Human-readable description
-- `dependencies` (optional): Spec name to version map
-
-### Project Index (`.spectrl/spectrl-index.json`)
-
-Lists installed specs with registry locations and hashes. All transitive dependencies must be listed.
-
-```json
-{
-  "spec-name@1.0.0": {
-    "source": "~/.spectrl/registry/spec-name/1.0.0",
-    "hash": "sha256:abc123..."
-  },
-  "other-spec@1.0.0": {
-    "source": "~/.spectrl/registry/other-spec/1.0.0",
-    "hash": "sha256:def456..."
-  }
-}
-```
+### Discovery
+
+#### `spectrl search <query>`
+
+Search for specs in the public registry.
+
+```bash
+spectrl search <query>
 
-**Fields:**
-
-- Key: `name@version` format
-- `source`: Registry path
-- `hash`: SHA-256 content hash
-
-### Lock File (`.spectrl/lock.json`)
-
-Auto-generated by `spectrl install`. Captures resolved dependency tree. **Do not edit manually.**
-
-```json
-{
-  "createdAt": "2025-11-10T13:40:00Z",
-  "entries": [
-    {
-      "name": "other-spec",
-      "version": "1.0.0",
-      "hash": "sha256:def456...",
-      "source": "~/.spectrl/registry/other-spec/1.0.0",
-      "deps": []
-    },
-    {
-      "name": "spec-name",
-      "version": "1.0.0",
-      "hash": "sha256:abc123...",
-      "source": "~/.spectrl/registry/spec-name/1.0.0",
-      "deps": ["other-spec@1.0.0"]
-    }
-  ]
-}
+Arguments:
+  query    Search query (keywords, tags, or spec names)
 ```
 
-**Fields:**
+**Example:**
 
-- `createdAt`: Generation timestamp
-- `entries`: Array of resolved specs
-  - `name`, `version`, `hash`, `source`: Spec metadata
-  - `deps`: Direct dependencies (`name@version` format)
+```bash
+spectrl search api
 
-## Troubleshooting
+Found 3 specs matching "api":
 
-### Registry Errors
+┌─────────────────────────┬─────────────────────────────────────┬──────────────────┬─────────┐
+│ Spec                    │ Description                         │ Tags             │ Version │
+├─────────────────────────┼─────────────────────────────────────┼──────────────────┼─────────┤
+│ alice/api-spec          │ REST API specification template     │ api, rest        │ 2.1.0   │
+│ bob/graphql-api         │ GraphQL API design patterns         │ api, graphql     │ 1.5.2   │
+│ charlie/openapi-starter │ OpenAPI 3.0 starter template        │ api, openapi     │ 1.0.0   │
+└─────────────────────────┴─────────────────────────────────────┴──────────────────┴─────────┘
 
+Install with: spectrl install <spec>
 ```
-Error: Spec my-spec@1.0.0 not found in registry
-```
 
-Publish the spec first:
+#### `spectrl info <spec>`
+
+Show detailed information about a spec from the public registry.
 
 ```bash
-cd path/to/my-spec && spectrl publish
-```
+spectrl info <spec>
 
-```
-Error: Spec missing-spec not found in registry
+Arguments:
+  spec    Spec reference in format username/spec
 ```
 
-The spec doesn't exist in your registry:
+**Example:**
 
 ```bash
-cd path/to/missing-spec && spectrl publish
-```
+spectrl info alice/api-spec
 
-### Validation Errors
+alice/api-spec
+REST API specification template
 
+Tags: api, rest, openapi
+
+Versions:
+┌─────────┬──────────────────────┬─────────────┐
+│ Version │ Published            │ Downloads   │
+├─────────┼──────────────────────┼─────────────┤
+│ 2.1.0   │ 2024-12-08 (2d ago)  │ 145         │
+│ 2.0.0   │ 2024-11-15 (23d ago) │ 89          │
+│ 1.5.0   │ 2024-10-01 (68d ago) │ 234         │
+└─────────┴──────────────────────┴─────────────┘
+
+Install latest: spectrl install alice/api-spec
+Install specific: spectrl install alice/api-spec@2.1.0
 ```
-Error: Invalid spec reference format. Use: name or name@version
-```
 
-Use correct format:
+#### `spectrl list`
+
+Show all installed specs (local and public).
 
 ```bash
-spectrl install my-spec
-# or
-spectrl install my-spec@1.0.0
+spectrl list
 ```
 
-```
-Error: Validation failed: file path contains '..'
-```
+**Example:**
 
-Use relative paths only (no parent directory references):
+```bash
+spectrl list
 
-```json
-{
-  "files": ["docs/design/architecture.md"]
-}
-```
+Installed specs:
 
-```
-Error: Validation failed: files array cannot be empty
+┌──────────────────────────┬─────────┬──────────┐
+│ Spec                     │ Version │ Source   │
+├──────────────────────────┼─────────┼──────────┤
+│ alice/api-spec           │ 2.1.0   │ public   │
+│ bob/graphql-api          │ 1.5.2   │ public   │
+│ my-local-spec            │ 1.0.0   │ local    │
+└──────────────────────────┴─────────┴──────────┘
+
+3 specs installed
 ```
 
-Add at least one file in `spectrl.json`:
+### Management
 
-```json
-{
-  "files": ["README.md"]
-}
-```
+#### `spectrl update [spec]`
 
-```
-Error: File not found: docs/missing.md
+Check for and install updates for public specs.
+
+```bash
+spectrl update [spec] [options]
+
+Arguments:
+  spec    Optional spec reference to update
+
+Options:
+  --all   Update all specs with available updates
 ```
 
-Verify the file exists:
+**Examples:**
 
 ```bash
-ls -la docs/missing.md
-```
+# Check for updates
+spectrl update
 
-### Dependency Errors
+Updates available:
 
+┌──────────────────────────┬─────────────┬────────────┐
+│ Spec                     │ Installed   │ Latest     │
+├──────────────────────────┼─────────────┼────────────┤
+│ alice/api-spec           │ 2.0.0       │ 2.1.0      │
+│ bob/graphql-api          │ 1.5.0       │ 1.5.2      │
+└──────────────────────────┴─────────────┴────────────┘
+
+Run 'spectrl update <spec>' to update a specific spec
+Run 'spectrl update --all' to update all specs
+
+# Update specific spec
+spectrl update alice/api-spec
+
+# Update all specs
+spectrl update --all
 ```
-Error: Missing dependency middleware@0.5.0. Add it to .spectrl/spectrl-index.json
-```
 
-Install the missing dependency:
+#### `spectrl unpublish <spec>`
+
+Remove a spec version from the public registry (requires authentication).
 
 ```bash
-spectrl install middleware@0.5.0
-```
+spectrl unpublish <spec>
 
-```
-Error: Manifest mismatch for app@1.0.0: found name=app, version=0.9.0
+Arguments:
+  spec    Spec reference in format username/spec@version
 ```
 
-Update the index key or manifest to match. Check `spectrl.json` version field.
+**Example:**
 
-```
-Error: Cyclic dependency detected: dep-x@1.0.0 → dep-y@1.0.0 → dep-x@1.0.0
-```
+```bash
+spectrl unpublish alice/api-spec@1.0.0
 
-Remove the circular dependency from your spec manifests.
+⚠️  This will permanently delete alice/api-spec@1.0.0 from the public registry.
 
-### Integrity Errors
+? Are you sure you want to continue?
+❯ No, cancel
+  Yes, delete alice/api-spec@1.0.0
 
+Unpublishing alice/api-spec@1.0.0...
+✓ Successfully unpublished alice/api-spec@1.0.0
 ```
-Error: Integrity breach: hash mismatch for app@1.0.0
-```
 
-Spec content changed after publishing. Republish or verify source:
+## Configuration
+
+### Environment Variables
 
 ```bash
-cd path/to/app && spectrl publish
+# API endpoint (optional, defaults to production)
+export API_URL="https://api.spectrl.dev"
+
+# Registry URL for downloading specs (optional)
+export REGISTRY_URL="https://registry.spectrl.dev"
 ```
 
+### Token Storage
+
+Spectrl securely stores GitHub tokens using:
+
+- **macOS**: Keychain Access
+- **Windows**: Credential Manager
+- **Linux**: Secret Service (libsecret)
+- **Fallback**: Encrypted file (`~/.spectrl/.auth`)
+
+## Spec Reference Formats
+
+Spectrl supports different spec reference formats:
+
+| Format                  | Description                   | Example                |
+| ----------------------- | ----------------------------- | ---------------------- |
+| `name`                  | Local spec, latest version    | `my-spec`              |
+| `name@version`          | Local spec, specific version  | `my-spec@1.0.0`        |
+| `username/name`         | Public spec, latest version   | `alice/api-spec`       |
+| `username/name@version` | Public spec, specific version | `alice/api-spec@2.1.0` |
+
+## Troubleshooting
+
+### Authentication Issues
+
+**Problem**: `spectrl login` fails with "bad_verification_code"
+
+**Solution**:
+
+1. Ensure Device Flow is enabled on the GitHub OAuth App
+2. Check that you're entering the code correctly
+3. Try the login process again
+
+**Problem**: "Invalid client_id" error during login
+
+**Solution**:
+
+1. Verify the GitHub OAuth App configuration
+2. Contact support if the issue persists
+
+### Token Issues
+
+**Problem**: Commands fail with authentication errors after successful login
+
+**Solution**:
+
+1. Check token validity: `spectrl whoami`
+2. Re-authenticate: `spectrl logout && spectrl login`
+3. Verify keychain permissions on macOS
+
+### Network Issues
+
+**Problem**: Commands timeout or fail with network errors
+
+**Solution**:
+
+1. Check internet connection
+2. Verify API_URL environment variable
+3. Try again later (temporary service issues)
+
+### Installation Issues
+
+**Problem**: "Spec not found" when installing public specs
+
+**Solution**:
+
+1. Verify spec name and username: `spectrl search <query>`
+2. Check spec exists: `spectrl info username/spec`
+3. Ensure you're using the correct format: `username/spec`
+
+**Problem**: Symlink creation fails on Windows
+
+**Solution**:
+
+- Spectrl automatically falls back to copying files
+- No action needed, this is expected behavior
+
+### Publishing Issues
+
+**Problem**: Publish fails with "agent field missing"
+
+**Solution**:
+
+- Spectrl auto-populates the agent field
+- Ensure your `spectrl.json` is valid
+- Check file permissions
+
+## FAQ
+
+### General
+
+**Q: What's the difference between local and public registry?**
+
+A:
+
+- **Local registry**: Specs stored in `~/.spectrl/registry/`, private to your machine
+- **Public registry**: Specs shared globally, discoverable by others, requires authentication
+
+**Q: Can I use both local and public specs in the same project?**
+
+A: Yes! You can install specs from both sources. Use `spectrl list` to see the source of each spec.
+
+**Q: How do I know if a spec is from local or public registry?**
+
+A: Public specs have a username prefix (e.g., `alice/api-spec`), local specs don't (e.g., `my-spec`).
+
+### Authentication
+
+**Q: Do I need to authenticate for local registry operations?**
+
+A: No, authentication is only required for public registry operations (publish, unpublish).
+
+**Q: How long do tokens last?**
+
+A: GitHub tokens don't expire automatically, but you can revoke them anytime in GitHub settings.
+
+**Q: Can I use Spectrl in CI/CD?**
+
+A: Yes, but you'll need to handle authentication differently. Consider using GitHub Actions with GITHUB_TOKEN.
+
+### Specs and Versioning
+
+**Q: What happens when I install a spec that already exists?**
+
+A: Spectrl detects collisions and prompts you to choose: keep existing, replace, or cancel.
+
+**Q: How do I update a published spec?**
+
+A: Increment the version in `spectrl.json` and run `spectrl publish` again.
+
+**Q: Can I unpublish a spec?**
+
+A: Yes, but only specific versions: `spectrl unpublish username/spec@version`. This is permanent.
+
+### File Management
+
+**Q: Where are specs stored locally?**
+
+A:
+
+- **Registry**: `~/.spectrl/registry/`
+- **Project specs**: `.spectrl/specs/`
+- **Project index**: `.spectrl/index.json`
+
+**Q: What happens to files when I install a spec?**
+
+A: Spectrl creates symlinks (or copies on Windows) from `.spectrl/specs/` to the registry.
+
+**Q: Can I modify installed specs?**
+
+A: You can view files, but modifications won't persist. Create your own spec instead.
+
+## Examples
+
+### Publishing Your First Spec
+
+```bash
+# 1. Create a new spec
+mkdir my-api-spec
+cd my-api-spec
+spectrl new api-spec --description "My REST API specification"
+
+# 2. Add your content
+echo "# API Specification" > README.md
+echo "## Endpoints" >> README.md
+
+# 3. Update spectrl.json to include README.md
+# Edit spectrl.json: add "README.md" to files array
+
+# 4. Login to Spectrl
+spectrl login
+
+# 5. Publish to public registry
+spectrl publish
+# Choose "Public registry"
+
+# 6. Verify publication
+spectrl search api-spec
+spectrl info yourusername/api-spec
 ```
-Hash changes unexpectedly
+
+### Finding and Installing Specs
+
+```bash
+# Search for API-related specs
+spectrl search api
+
+# Get detailed information
+spectrl info alice/rest-api-template
+
+# Install latest version
+spectrl install alice/rest-api-template
+
+# Install specific version
+spectrl install alice/rest-api-template@1.2.0
+
+# List all installed specs
+spectrl list
 ```
 
-Check for file modifications, line endings (LF vs CRLF), or trailing whitespace:
+### Keeping Specs Updated
 
 ```bash
-diff my-spec/docs/prd.md ~/.spectrl/registry/my-spec/1.0.0/files/docs/prd.md
+# Check for updates
+spectrl update
+
+# Update specific spec
+spectrl update alice/rest-api-template
+
+# Update all specs at once
+spectrl update --all
 ```
 
+## Support
+
+- **Documentation**: [docs.spectrl.dev](https://docs.spectrl.dev)
+- **Issues**: [GitHub Issues](https://github.com/spectrl/spectrl/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/spectrl/spectrl/discussions)
+
 ## License
 
-MIT
+MIT © [Spectrl](https://spectrl.dev)