@spectrl/cli 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Pasha Naumov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,443 @@
+# Spectrl
+
+Spectrl is a local-first spec registry that treats structured documents (PRDs, TDDs, ADRs) as versioned, installable packages. Think npm for your documentation.
+
+**Key benefits:**
+
+- **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
+
+## Installation
+
+```bash
+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)
+
+```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`.
+
+### 2. Publish to local registry
+
+```bash
+cd my-feature
+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)
+```
+
+### 4. Install the spec
+
+```bash
+spectrl install my-feature
+# Resolving my-feature... found version 0.1.0
+# Installed my-feature@0.1.0
+# Updated .spectrl/spectrl-index.json
+```
+
+## Core Concepts
+
+Spectrl applies package manager principles to structured documentation:
+
+- **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
+
+**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/`).
+
+## Commands
+
+### `spectrl init`
+
+Initialize a new project index.
+
+```bash
+spectrl init
+```
+
+Creates `.spectrl/spectrl-index.json` in the current directory.
+
+**Options:**
+
+- `--skip-agents` - Skip AGENTS.md creation
+- `--force-agents` - Create/append AGENTS.md without prompting
+
+**Example:**
+
+```bash
+spectrl init
+# Created .spectrl/spectrl-index.json
+# Would you like to create AGENTS.md? (y/n)
+```
+
+### `spectrl new`
+
+Create a new spec with a manifest template.
+
+```bash
+spectrl new <name> [options]
+```
+
+**Arguments:**
+
+- `<name>` - Spec name (lowercase alphanumeric with hyphens)
+
+**Options:**
+
+- `--version <version>` - Initial version (default: `0.1.0`)
+- `--description <desc>` - Spec description
+
+**Example:**
+
+```bash
+spectrl new user-auth --version 1.0.0 --description "User authentication system"
+# Created user-auth/spectrl.json
+```
+
+### `spectrl publish`
+
+Publish the current spec to the local registry.
+
+```bash
+spectrl publish
+```
+
+Run from a directory containing `spectrl.json`. Publishes to `~/.spectrl/registry/{name}/{version}/` with content hash.
+
+**Example:**
+
+```bash
+spectrl publish
+# Published my-feature@1.0.0
+```
+
+### `spectrl install`
+
+Install specs from the local registry.
+
+```bash
+# Restore all specs from project index
+spectrl install
+
+# Install specific spec (latest version)
+spectrl install <name>
+
+# Install specific version
+spectrl install <name>@<version>
+```
+
+**Options:**
+
+- `--registry <path>` - Custom registry path (default: `~/.spectrl/registry`)
+
+**Example:**
+
+```bash
+spectrl install user-auth
+# Resolving user-auth... found version 2.1.0
+# Installed user-auth@2.1.0
+# Updated .spectrl/spectrl-index.json
+```
+
+## Workflows
+
+### Team Collaboration
+
+Share specs across team members using the project index and lock file.
+
+```bash
+# Developer A: Publish and install specs in project
+cd my-feature
+spectrl publish
+
+cd /path/to/project
+spectrl install my-feature@1.0.0
+# Installed my-feature@1.0.0
+# Updated .spectrl/spectrl-index.json
+
+spectrl install base-spec
+# Resolving base-spec... found version 2.0.0
+# Installed base-spec@2.0.0
+
+# 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
+
+# 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
+```
+
+### Multi-File Spec
+
+Bundle related documents together in a single spec.
+
+```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
+```
+
+## File Formats
+
+### Manifest (`spectrl.json`)
+
+Defines a spec. **Required:** `name`, `version`, `files`.
+
+```json
+{
+  "name": "spec-name",
+  "version": "1.0.0",
+  "description": "What this spec contains",
+  "files": ["doc1.md", "doc2.md"],
+  "dependencies": {
+    "other-spec": "1.0.0"
+  }
+}
+```
+
+**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..."
+  }
+}
+```
+
+**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"]
+    }
+  ]
+}
+```
+
+**Fields:**
+
+- `createdAt`: Generation timestamp
+- `entries`: Array of resolved specs
+  - `name`, `version`, `hash`, `source`: Spec metadata
+  - `deps`: Direct dependencies (`name@version` format)
+
+## Troubleshooting
+
+### Registry Errors
+
+```
+Error: Spec my-spec@1.0.0 not found in registry
+```
+
+Publish the spec first:
+
+```bash
+cd path/to/my-spec && spectrl publish
+```
+
+```
+Error: Spec missing-spec not found in registry
+```
+
+The spec doesn't exist in your registry:
+
+```bash
+cd path/to/missing-spec && spectrl publish
+```
+
+### Validation Errors
+
+```
+Error: Invalid spec reference format. Use: name or name@version
+```
+
+Use correct format:
+
+```bash
+spectrl install my-spec
+# or
+spectrl install my-spec@1.0.0
+```
+
+```
+Error: Validation failed: file path contains '..'
+```
+
+Use relative paths only (no parent directory references):
+
+```json
+{
+  "files": ["docs/design/architecture.md"]
+}
+```
+
+```
+Error: Validation failed: files array cannot be empty
+```
+
+Add at least one file in `spectrl.json`:
+
+```json
+{
+  "files": ["README.md"]
+}
+```
+
+```
+Error: File not found: docs/missing.md
+```
+
+Verify the file exists:
+
+```bash
+ls -la docs/missing.md
+```
+
+### Dependency Errors
+
+```
+Error: Missing dependency middleware@0.5.0. Add it to .spectrl/spectrl-index.json
+```
+
+Install the missing dependency:
+
+```bash
+spectrl install middleware@0.5.0
+```
+
+```
+Error: Manifest mismatch for app@1.0.0: found name=app, version=0.9.0
+```
+
+Update the index key or manifest to match. Check `spectrl.json` version field.
+
+```
+Error: Cyclic dependency detected: dep-x@1.0.0 → dep-y@1.0.0 → dep-x@1.0.0
+```
+
+Remove the circular dependency from your spec manifests.
+
+### Integrity Errors
+
+```
+Error: Integrity breach: hash mismatch for app@1.0.0
+```
+
+Spec content changed after publishing. Republish or verify source:
+
+```bash
+cd path/to/app && spectrl publish
+```
+
+```
+Hash changes unexpectedly
+```
+
+Check for file modifications, line endings (LF vs CRLF), or trailing whitespace:
+
+```bash
+diff my-spec/docs/prd.md ~/.spectrl/registry/my-spec/1.0.0/files/docs/prd.md
+```
+
+## License
+
+MIT