mirror of
https://github.com/github/spec-kit.git
synced 2026-03-17 02:43:08 +00:00
Compare commits
5 Commits
localden/u
...
v0.0.93
| Author | SHA1 | Date | |
|---|---|---|---|
|
f14a47ea7d | ||
|
|
36d97235ad | ||
|
|
4afbd87abb | ||
|
|
b562438df9 | ||
|
|
9111699cd2 |
4
.github/workflows/lint.yml
vendored
4
.github/workflows/lint.yml
vendored
@@ -17,4 +17,6 @@ jobs:
|
||||
- name: Run markdownlint-cli2
|
||||
uses: DavidAnson/markdownlint-cli2-action@v19
|
||||
with:
|
||||
globs: '**/*.md'
|
||||
globs: |
|
||||
'**/*.md'
|
||||
!extensions/**/*.md
|
||||
|
||||
@@ -34,7 +34,8 @@ rewrite_paths() {
|
||||
sed -E \
|
||||
-e 's@(/?)memory/@.specify/memory/@g' \
|
||||
-e 's@(/?)scripts/@.specify/scripts/@g' \
|
||||
-e 's@(/?)templates/@.specify/templates/@g'
|
||||
-e 's@(/?)templates/@.specify/templates/@g' \
|
||||
-e 's@\.specify\.specify/@.specify/@g'
|
||||
}
|
||||
|
||||
generate_commands() {
|
||||
|
||||
7
.gitignore
vendored
7
.gitignore
vendored
@@ -44,3 +44,10 @@ env/
|
||||
.genreleases/
|
||||
*.zip
|
||||
sdd-*/
|
||||
|
||||
docs/dev
|
||||
|
||||
# Extension system
|
||||
.specify/extensions/.cache/
|
||||
.specify/extensions/.backup/
|
||||
.specify/extensions/*/local-config.yml
|
||||
@@ -19,7 +19,9 @@
|
||||
},
|
||||
"MD050": {
|
||||
"style": "asterisk"
|
||||
}
|
||||
},
|
||||
"MD036": false,
|
||||
"MD060": false
|
||||
},
|
||||
"ignores": [
|
||||
".genreleases/"
|
||||
|
||||
114
CHANGELOG.md
114
CHANGELOG.md
@@ -7,6 +7,120 @@ All notable changes to the Specify CLI and templates are documented here.
|
||||
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
||||
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
||||
|
||||
## [0.1.0] - 2026-01-28
|
||||
|
||||
### Added
|
||||
|
||||
- **Extension System**: Introduced modular extension architecture for Spec Kit
|
||||
- Extensions are self-contained packages that add commands and functionality without bloating core
|
||||
- Extension manifest schema (`extension.yml`) with validation
|
||||
- Extension registry (`.specify/extensions/.registry`) for tracking installed extensions
|
||||
- Extension manager module (`src/specify_cli/extensions.py`) for installation/removal
|
||||
- New CLI commands:
|
||||
- `specify extension list` - List installed extensions
|
||||
- `specify extension add` - Install extension from local directory or URL
|
||||
- `specify extension remove` - Uninstall extension
|
||||
- `specify extension search` - Search extension catalog
|
||||
- `specify extension info` - Show detailed extension information
|
||||
- Semantic versioning compatibility checks
|
||||
- Support for extension configuration files
|
||||
- Command registration system for AI agents (Claude support initially)
|
||||
- Added dependencies: `pyyaml>=6.0`, `packaging>=23.0`
|
||||
|
||||
- **Extension Catalog**: Extension discovery and distribution system
|
||||
- Central catalog (`extensions/catalog.json`) for published extensions
|
||||
- Extension catalog manager (`ExtensionCatalog` class) with:
|
||||
- Catalog fetching from GitHub
|
||||
- 1-hour local caching for performance
|
||||
- Search by query, tag, author, or verification status
|
||||
- Extension info retrieval
|
||||
- Catalog cache stored in `.specify/extensions/.cache/`
|
||||
- Search and info commands with rich console output
|
||||
- Added 9 catalog-specific unit tests (100% pass rate)
|
||||
|
||||
- **Jira Extension**: First official extension for Jira integration
|
||||
- Extension ID: `jira`
|
||||
- Version: 1.0.0
|
||||
- Commands:
|
||||
- `/speckit.jira.specstoissues` - Create Jira hierarchy from spec and tasks
|
||||
- `/speckit.jira.discover-fields` - Discover Jira custom fields
|
||||
- `/speckit.jira.sync-status` - Sync task completion status
|
||||
- Comprehensive documentation (README, usage guide, examples)
|
||||
- MIT licensed
|
||||
|
||||
- **Hook System**: Extension lifecycle hooks for automation
|
||||
- `HookExecutor` class for managing extension hooks
|
||||
- Hooks registered in `.specify/extensions.yml`
|
||||
- Hook registration during extension installation
|
||||
- Hook unregistration during extension removal
|
||||
- Support for optional and mandatory hooks
|
||||
- Hook execution messages for AI agent integration
|
||||
- Condition support for conditional hook execution (placeholder)
|
||||
|
||||
- **Extension Management**: Advanced extension management commands
|
||||
- `specify extension update` - Check and update extensions to latest version
|
||||
- `specify extension enable` - Enable a disabled extension
|
||||
- `specify extension disable` - Disable extension without removing it
|
||||
- Version comparison with catalog
|
||||
- Update notifications
|
||||
- Preserve configuration during updates
|
||||
|
||||
- **Multi-Agent Support**: Extensions now work with all supported AI agents (Phase 6)
|
||||
- Automatic detection and registration for all agents in project
|
||||
- Support for 16+ AI agents (Claude, Gemini, Copilot, Cursor, Qwen, and more)
|
||||
- Agent-specific command formats (Markdown and TOML)
|
||||
- Automatic argument placeholder conversion ($ARGUMENTS → {{args}})
|
||||
- Commands registered for all detected agents during installation
|
||||
- Multi-agent command unregistration on extension removal
|
||||
- `CommandRegistrar.register_commands_for_agent()` method
|
||||
- `CommandRegistrar.register_commands_for_all_agents()` method
|
||||
|
||||
- **Configuration Layers**: Full configuration cascade system (Phase 6)
|
||||
- **Layer 1**: Defaults from extension manifest (`extension.yml`)
|
||||
- **Layer 2**: Project config (`.specify/extensions/{ext-id}/{ext-id}-config.yml`)
|
||||
- **Layer 3**: Local config (`.specify/extensions/{ext-id}/local-config.yml`, gitignored)
|
||||
- **Layer 4**: Environment variables (`SPECKIT_{EXT_ID}_{KEY}` pattern)
|
||||
- Recursive config merging with proper precedence
|
||||
- `ConfigManager` class for programmatic config access
|
||||
- `get_config()`, `get_value()`, `has_value()` methods
|
||||
- Support for nested configuration paths with dot-notation
|
||||
|
||||
- **Hook Condition Evaluation**: Smart hook execution based on runtime conditions (Phase 6)
|
||||
- Config conditions: `config.key.path is set`, `config.key == 'value'`, `config.key != 'value'`
|
||||
- Environment conditions: `env.VAR is set`, `env.VAR == 'value'`, `env.VAR != 'value'`
|
||||
- Automatic filtering of hooks based on condition evaluation
|
||||
- Safe fallback behavior on evaluation errors
|
||||
- Case-insensitive pattern matching
|
||||
|
||||
- **Hook Integration**: Agent-level hook checking and execution (Phase 6)
|
||||
- `check_hooks_for_event()` method for AI agents to query hooks after core commands
|
||||
- Condition-aware hook filtering before execution
|
||||
- `enable_hooks()` and `disable_hooks()` methods per extension
|
||||
- Formatted hook messages for agent display
|
||||
- `execute_hook()` method for hook execution information
|
||||
|
||||
- **Documentation Suite**: Comprehensive documentation for users and developers
|
||||
- **EXTENSION-USER-GUIDE.md**: Complete user guide with installation, usage, configuration, and troubleshooting
|
||||
- **EXTENSION-API-REFERENCE.md**: Technical API reference with manifest schema, Python API, and CLI commands
|
||||
- **EXTENSION-PUBLISHING-GUIDE.md**: Publishing guide for extension authors
|
||||
- **RFC-EXTENSION-SYSTEM.md**: Extension architecture design document
|
||||
|
||||
- **Extension Template**: Starter template in `extensions/template/` for creating new extensions
|
||||
- Fully commented `extension.yml` manifest template
|
||||
- Example command file with detailed explanations
|
||||
- Configuration template with all options
|
||||
- Complete project structure (README, LICENSE, CHANGELOG, .gitignore)
|
||||
- EXAMPLE-README.md showing final documentation format
|
||||
|
||||
- **Unit Tests**: Comprehensive test suite with 39 tests covering all extension system components
|
||||
- Test coverage: 83% of extension module code
|
||||
- Test dependencies: `pytest>=7.0`, `pytest-cov>=4.0`
|
||||
- Configured pytest in `pyproject.toml`
|
||||
|
||||
### Changed
|
||||
|
||||
- Version bumped to 0.1.0 (minor release for new feature)
|
||||
|
||||
## [0.0.22] - 2025-11-07
|
||||
|
||||
- Support for VS Code/Copilot agents, and moving away from prompts to proper agents with hand-offs.
|
||||
|
||||
714
extensions/EXTENSION-API-REFERENCE.md
Normal file
714
extensions/EXTENSION-API-REFERENCE.md
Normal file
@@ -0,0 +1,714 @@
|
||||
# Extension API Reference
|
||||
|
||||
Technical reference for Spec Kit extension system APIs and manifest schema.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Extension Manifest](#extension-manifest)
|
||||
2. [Python API](#python-api)
|
||||
3. [Command File Format](#command-file-format)
|
||||
4. [Configuration Schema](#configuration-schema)
|
||||
5. [Hook System](#hook-system)
|
||||
6. [CLI Commands](#cli-commands)
|
||||
|
||||
---
|
||||
|
||||
## Extension Manifest
|
||||
|
||||
### Schema Version 1.0
|
||||
|
||||
File: `extension.yml`
|
||||
|
||||
```yaml
|
||||
schema_version: "1.0" # Required
|
||||
|
||||
extension:
|
||||
id: string # Required, pattern: ^[a-z0-9-]+$
|
||||
name: string # Required, human-readable name
|
||||
version: string # Required, semantic version (X.Y.Z)
|
||||
description: string # Required, brief description (<200 chars)
|
||||
author: string # Required
|
||||
repository: string # Required, valid URL
|
||||
license: string # Required (e.g., "MIT", "Apache-2.0")
|
||||
homepage: string # Optional, valid URL
|
||||
|
||||
requires:
|
||||
speckit_version: string # Required, version specifier (>=X.Y.Z)
|
||||
tools: # Optional, array of tool requirements
|
||||
- name: string # Tool name
|
||||
version: string # Optional, version specifier
|
||||
required: boolean # Optional, default: false
|
||||
|
||||
provides:
|
||||
commands: # Required, at least one command
|
||||
- name: string # Required, pattern: ^speckit\.[a-z0-9-]+\.[a-z0-9-]+$
|
||||
file: string # Required, relative path to command file
|
||||
description: string # Required
|
||||
aliases: [string] # Optional, array of alternate names
|
||||
|
||||
config: # Optional, array of config files
|
||||
- name: string # Config file name
|
||||
template: string # Template file path
|
||||
description: string
|
||||
required: boolean # Default: false
|
||||
|
||||
hooks: # Optional, event hooks
|
||||
event_name: # e.g., "after_tasks", "after_implement"
|
||||
command: string # Command to execute
|
||||
optional: boolean # Default: true
|
||||
prompt: string # Prompt text for optional hooks
|
||||
description: string # Hook description
|
||||
condition: string # Optional, condition expression
|
||||
|
||||
tags: # Optional, array of tags (2-10 recommended)
|
||||
- string
|
||||
|
||||
defaults: # Optional, default configuration values
|
||||
key: value # Any YAML structure
|
||||
```
|
||||
|
||||
### Field Specifications
|
||||
|
||||
#### `extension.id`
|
||||
|
||||
- **Type**: string
|
||||
- **Pattern**: `^[a-z0-9-]+$`
|
||||
- **Description**: Unique extension identifier
|
||||
- **Examples**: `jira`, `linear`, `azure-devops`
|
||||
- **Invalid**: `Jira`, `my_extension`, `extension.id`
|
||||
|
||||
#### `extension.version`
|
||||
|
||||
- **Type**: string
|
||||
- **Format**: Semantic versioning (X.Y.Z)
|
||||
- **Description**: Extension version
|
||||
- **Examples**: `1.0.0`, `0.9.5`, `2.1.3`
|
||||
- **Invalid**: `v1.0`, `1.0`, `1.0.0-beta`
|
||||
|
||||
#### `requires.speckit_version`
|
||||
|
||||
- **Type**: string
|
||||
- **Format**: Version specifier
|
||||
- **Description**: Required spec-kit version range
|
||||
- **Examples**:
|
||||
- `>=0.1.0` - Any version 0.1.0 or higher
|
||||
- `>=0.1.0,<2.0.0` - Version 0.1.x or 1.x
|
||||
- `==0.1.0` - Exactly 0.1.0
|
||||
- **Invalid**: `0.1.0`, `>= 0.1.0` (space), `latest`
|
||||
|
||||
#### `provides.commands[].name`
|
||||
|
||||
- **Type**: string
|
||||
- **Pattern**: `^speckit\.[a-z0-9-]+\.[a-z0-9-]+$`
|
||||
- **Description**: Namespaced command name
|
||||
- **Format**: `speckit.{extension-id}.{command-name}`
|
||||
- **Examples**: `speckit.jira.specstoissues`, `speckit.linear.sync`
|
||||
- **Invalid**: `jira.specstoissues`, `speckit.command`, `speckit.jira.CreateIssues`
|
||||
|
||||
#### `hooks`
|
||||
|
||||
- **Type**: object
|
||||
- **Keys**: Event names (e.g., `after_tasks`, `after_implement`, `before_commit`)
|
||||
- **Description**: Hooks that execute at lifecycle events
|
||||
- **Events**: Defined by core spec-kit commands
|
||||
|
||||
---
|
||||
|
||||
## Python API
|
||||
|
||||
### ExtensionManifest
|
||||
|
||||
**Module**: `specify_cli.extensions`
|
||||
|
||||
```python
|
||||
from specify_cli.extensions import ExtensionManifest
|
||||
|
||||
manifest = ExtensionManifest(Path("extension.yml"))
|
||||
```
|
||||
|
||||
**Properties**:
|
||||
|
||||
```python
|
||||
manifest.id # str: Extension ID
|
||||
manifest.name # str: Extension name
|
||||
manifest.version # str: Version
|
||||
manifest.description # str: Description
|
||||
manifest.requires_speckit_version # str: Required spec-kit version
|
||||
manifest.commands # List[Dict]: Command definitions
|
||||
manifest.hooks # Dict: Hook definitions
|
||||
```
|
||||
|
||||
**Methods**:
|
||||
|
||||
```python
|
||||
manifest.get_hash() # str: SHA256 hash of manifest file
|
||||
```
|
||||
|
||||
**Exceptions**:
|
||||
|
||||
```python
|
||||
ValidationError # Invalid manifest structure
|
||||
CompatibilityError # Incompatible with current spec-kit version
|
||||
```
|
||||
|
||||
### ExtensionRegistry
|
||||
|
||||
**Module**: `specify_cli.extensions`
|
||||
|
||||
```python
|
||||
from specify_cli.extensions import ExtensionRegistry
|
||||
|
||||
registry = ExtensionRegistry(extensions_dir)
|
||||
```
|
||||
|
||||
**Methods**:
|
||||
|
||||
```python
|
||||
# Add extension to registry
|
||||
registry.add(extension_id: str, metadata: dict)
|
||||
|
||||
# Remove extension from registry
|
||||
registry.remove(extension_id: str)
|
||||
|
||||
# Get extension metadata
|
||||
metadata = registry.get(extension_id: str) # Optional[dict]
|
||||
|
||||
# List all extensions
|
||||
extensions = registry.list() # Dict[str, dict]
|
||||
|
||||
# Check if installed
|
||||
is_installed = registry.is_installed(extension_id: str) # bool
|
||||
```
|
||||
|
||||
**Registry Format**:
|
||||
|
||||
```json
|
||||
{
|
||||
"schema_version": "1.0",
|
||||
"extensions": {
|
||||
"jira": {
|
||||
"version": "1.0.0",
|
||||
"source": "catalog",
|
||||
"manifest_hash": "sha256...",
|
||||
"enabled": true,
|
||||
"registered_commands": ["speckit.jira.specstoissues", ...],
|
||||
"installed_at": "2026-01-28T..."
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### ExtensionManager
|
||||
|
||||
**Module**: `specify_cli.extensions`
|
||||
|
||||
```python
|
||||
from specify_cli.extensions import ExtensionManager
|
||||
|
||||
manager = ExtensionManager(project_root)
|
||||
```
|
||||
|
||||
**Methods**:
|
||||
|
||||
```python
|
||||
# Install from directory
|
||||
manifest = manager.install_from_directory(
|
||||
source_dir: Path,
|
||||
speckit_version: str,
|
||||
register_commands: bool = True
|
||||
) # Returns: ExtensionManifest
|
||||
|
||||
# Install from ZIP
|
||||
manifest = manager.install_from_zip(
|
||||
zip_path: Path,
|
||||
speckit_version: str
|
||||
) # Returns: ExtensionManifest
|
||||
|
||||
# Remove extension
|
||||
success = manager.remove(
|
||||
extension_id: str,
|
||||
keep_config: bool = False
|
||||
) # Returns: bool
|
||||
|
||||
# List installed extensions
|
||||
extensions = manager.list_installed() # List[Dict]
|
||||
|
||||
# Get extension manifest
|
||||
manifest = manager.get_extension(extension_id: str) # Optional[ExtensionManifest]
|
||||
|
||||
# Check compatibility
|
||||
manager.check_compatibility(
|
||||
manifest: ExtensionManifest,
|
||||
speckit_version: str
|
||||
) # Raises: CompatibilityError if incompatible
|
||||
```
|
||||
|
||||
### ExtensionCatalog
|
||||
|
||||
**Module**: `specify_cli.extensions`
|
||||
|
||||
```python
|
||||
from specify_cli.extensions import ExtensionCatalog
|
||||
|
||||
catalog = ExtensionCatalog(project_root)
|
||||
```
|
||||
|
||||
**Methods**:
|
||||
|
||||
```python
|
||||
# Fetch catalog
|
||||
catalog_data = catalog.fetch_catalog(force_refresh: bool = False) # Dict
|
||||
|
||||
# Search extensions
|
||||
results = catalog.search(
|
||||
query: Optional[str] = None,
|
||||
tag: Optional[str] = None,
|
||||
author: Optional[str] = None,
|
||||
verified_only: bool = False
|
||||
) # Returns: List[Dict]
|
||||
|
||||
# Get extension info
|
||||
ext_info = catalog.get_extension_info(extension_id: str) # Optional[Dict]
|
||||
|
||||
# Check cache validity
|
||||
is_valid = catalog.is_cache_valid() # bool
|
||||
|
||||
# Clear cache
|
||||
catalog.clear_cache()
|
||||
```
|
||||
|
||||
### HookExecutor
|
||||
|
||||
**Module**: `specify_cli.extensions`
|
||||
|
||||
```python
|
||||
from specify_cli.extensions import HookExecutor
|
||||
|
||||
hook_executor = HookExecutor(project_root)
|
||||
```
|
||||
|
||||
**Methods**:
|
||||
|
||||
```python
|
||||
# Get project config
|
||||
config = hook_executor.get_project_config() # Dict
|
||||
|
||||
# Save project config
|
||||
hook_executor.save_project_config(config: Dict)
|
||||
|
||||
# Register hooks
|
||||
hook_executor.register_hooks(manifest: ExtensionManifest)
|
||||
|
||||
# Unregister hooks
|
||||
hook_executor.unregister_hooks(extension_id: str)
|
||||
|
||||
# Get hooks for event
|
||||
hooks = hook_executor.get_hooks_for_event(event_name: str) # List[Dict]
|
||||
|
||||
# Check if hook should execute
|
||||
should_run = hook_executor.should_execute_hook(hook: Dict) # bool
|
||||
|
||||
# Format hook message
|
||||
message = hook_executor.format_hook_message(
|
||||
event_name: str,
|
||||
hooks: List[Dict]
|
||||
) # str
|
||||
```
|
||||
|
||||
### CommandRegistrar
|
||||
|
||||
**Module**: `specify_cli.extensions`
|
||||
|
||||
```python
|
||||
from specify_cli.extensions import CommandRegistrar
|
||||
|
||||
registrar = CommandRegistrar()
|
||||
```
|
||||
|
||||
**Methods**:
|
||||
|
||||
```python
|
||||
# Register commands for Claude Code
|
||||
registered = registrar.register_commands_for_claude(
|
||||
manifest: ExtensionManifest,
|
||||
extension_dir: Path,
|
||||
project_root: Path
|
||||
) # Returns: List[str] (command names)
|
||||
|
||||
# Parse frontmatter
|
||||
frontmatter, body = registrar.parse_frontmatter(content: str)
|
||||
|
||||
# Render frontmatter
|
||||
yaml_text = registrar.render_frontmatter(frontmatter: Dict) # str
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Command File Format
|
||||
|
||||
### Universal Command Format
|
||||
|
||||
**File**: `commands/{command-name}.md`
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: "Command description"
|
||||
tools:
|
||||
- 'mcp-server/tool_name'
|
||||
- 'other-mcp-server/other_tool'
|
||||
---
|
||||
|
||||
# Command Title
|
||||
|
||||
Command documentation in Markdown.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
1. Requirement 1
|
||||
2. Requirement 2
|
||||
|
||||
## User Input
|
||||
|
||||
$ARGUMENTS
|
||||
|
||||
## Steps
|
||||
|
||||
### Step 1: Description
|
||||
|
||||
Instruction text...
|
||||
|
||||
\`\`\`bash
|
||||
# Shell commands
|
||||
\`\`\`
|
||||
|
||||
### Step 2: Another Step
|
||||
|
||||
More instructions...
|
||||
|
||||
## Configuration Reference
|
||||
|
||||
Information about configuration options.
|
||||
|
||||
## Notes
|
||||
|
||||
Additional notes and tips.
|
||||
```
|
||||
|
||||
### Frontmatter Fields
|
||||
|
||||
```yaml
|
||||
description: string # Required, brief command description
|
||||
tools: [string] # Optional, MCP tools required
|
||||
```
|
||||
|
||||
### Special Variables
|
||||
|
||||
- `$ARGUMENTS` - Placeholder for user-provided arguments
|
||||
- Extension context automatically injected:
|
||||
|
||||
```markdown
|
||||
<!-- Extension: {extension-id} -->
|
||||
<!-- Config: .specify/extensions/{extension-id}/ -->
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Configuration Schema
|
||||
|
||||
### Extension Config File
|
||||
|
||||
**File**: `.specify/extensions/{extension-id}/{extension-id}-config.yml`
|
||||
|
||||
Extensions define their own config schema. Common patterns:
|
||||
|
||||
```yaml
|
||||
# Connection settings
|
||||
connection:
|
||||
url: string
|
||||
api_key: string
|
||||
|
||||
# Project settings
|
||||
project:
|
||||
key: string
|
||||
workspace: string
|
||||
|
||||
# Feature flags
|
||||
features:
|
||||
enabled: boolean
|
||||
auto_sync: boolean
|
||||
|
||||
# Defaults
|
||||
defaults:
|
||||
labels: [string]
|
||||
assignee: string
|
||||
|
||||
# Custom fields
|
||||
field_mappings:
|
||||
internal_name: "external_field_id"
|
||||
```
|
||||
|
||||
### Config Layers
|
||||
|
||||
1. **Extension Defaults** (from `extension.yml` `defaults` section)
|
||||
2. **Project Config** (`{extension-id}-config.yml`)
|
||||
3. **Local Override** (`{extension-id}-config.local.yml`, gitignored)
|
||||
4. **Environment Variables** (`SPECKIT_{EXTENSION}_*`)
|
||||
|
||||
### Environment Variable Pattern
|
||||
|
||||
Format: `SPECKIT_{EXTENSION}_{KEY}`
|
||||
|
||||
Examples:
|
||||
|
||||
- `SPECKIT_JIRA_PROJECT_KEY`
|
||||
- `SPECKIT_LINEAR_API_KEY`
|
||||
- `SPECKIT_GITHUB_TOKEN`
|
||||
|
||||
---
|
||||
|
||||
## Hook System
|
||||
|
||||
### Hook Definition
|
||||
|
||||
**In extension.yml**:
|
||||
|
||||
```yaml
|
||||
hooks:
|
||||
after_tasks:
|
||||
command: "speckit.jira.specstoissues"
|
||||
optional: true
|
||||
prompt: "Create Jira issues from tasks?"
|
||||
description: "Automatically create Jira hierarchy"
|
||||
condition: null
|
||||
```
|
||||
|
||||
### Hook Events
|
||||
|
||||
Standard events (defined by core):
|
||||
|
||||
- `after_tasks` - After task generation
|
||||
- `after_implement` - After implementation
|
||||
- `before_commit` - Before git commit
|
||||
- `after_commit` - After git commit
|
||||
|
||||
### Hook Configuration
|
||||
|
||||
**In `.specify/extensions.yml`**:
|
||||
|
||||
```yaml
|
||||
hooks:
|
||||
after_tasks:
|
||||
- extension: jira
|
||||
command: speckit.jira.specstoissues
|
||||
enabled: true
|
||||
optional: true
|
||||
prompt: "Create Jira issues from tasks?"
|
||||
description: "..."
|
||||
condition: null
|
||||
```
|
||||
|
||||
### Hook Message Format
|
||||
|
||||
```markdown
|
||||
## Extension Hooks
|
||||
|
||||
**Optional Hook**: {extension}
|
||||
Command: `/{command}`
|
||||
Description: {description}
|
||||
|
||||
Prompt: {prompt}
|
||||
To execute: `/{command}`
|
||||
```
|
||||
|
||||
Or for mandatory hooks:
|
||||
|
||||
```markdown
|
||||
**Automatic Hook**: {extension}
|
||||
Executing: `/{command}`
|
||||
EXECUTE_COMMAND: {command}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## CLI Commands
|
||||
|
||||
### extension list
|
||||
|
||||
**Usage**: `specify extension list [OPTIONS]`
|
||||
|
||||
**Options**:
|
||||
|
||||
- `--available` - Show available extensions from catalog
|
||||
- `--all` - Show both installed and available
|
||||
|
||||
**Output**: List of installed extensions with metadata
|
||||
|
||||
### extension add
|
||||
|
||||
**Usage**: `specify extension add EXTENSION [OPTIONS]`
|
||||
|
||||
**Options**:
|
||||
|
||||
- `--from URL` - Install from custom URL
|
||||
- `--dev PATH` - Install from local directory
|
||||
- `--version VERSION` - Install specific version
|
||||
- `--no-register` - Skip command registration
|
||||
|
||||
**Arguments**:
|
||||
|
||||
- `EXTENSION` - Extension name or URL
|
||||
|
||||
### extension remove
|
||||
|
||||
**Usage**: `specify extension remove EXTENSION [OPTIONS]`
|
||||
|
||||
**Options**:
|
||||
|
||||
- `--keep-config` - Preserve config files
|
||||
- `--force` - Skip confirmation
|
||||
|
||||
**Arguments**:
|
||||
|
||||
- `EXTENSION` - Extension ID
|
||||
|
||||
### extension search
|
||||
|
||||
**Usage**: `specify extension search [QUERY] [OPTIONS]`
|
||||
|
||||
**Options**:
|
||||
|
||||
- `--tag TAG` - Filter by tag
|
||||
- `--author AUTHOR` - Filter by author
|
||||
- `--verified` - Show only verified extensions
|
||||
|
||||
**Arguments**:
|
||||
|
||||
- `QUERY` - Optional search query
|
||||
|
||||
### extension info
|
||||
|
||||
**Usage**: `specify extension info EXTENSION`
|
||||
|
||||
**Arguments**:
|
||||
|
||||
- `EXTENSION` - Extension ID
|
||||
|
||||
### extension update
|
||||
|
||||
**Usage**: `specify extension update [EXTENSION]`
|
||||
|
||||
**Arguments**:
|
||||
|
||||
- `EXTENSION` - Optional, extension ID (default: all)
|
||||
|
||||
### extension enable
|
||||
|
||||
**Usage**: `specify extension enable EXTENSION`
|
||||
|
||||
**Arguments**:
|
||||
|
||||
- `EXTENSION` - Extension ID
|
||||
|
||||
### extension disable
|
||||
|
||||
**Usage**: `specify extension disable EXTENSION`
|
||||
|
||||
**Arguments**:
|
||||
|
||||
- `EXTENSION` - Extension ID
|
||||
|
||||
---
|
||||
|
||||
## Exceptions
|
||||
|
||||
### ValidationError
|
||||
|
||||
Raised when extension manifest validation fails.
|
||||
|
||||
```python
|
||||
from specify_cli.extensions import ValidationError
|
||||
|
||||
try:
|
||||
manifest = ExtensionManifest(path)
|
||||
except ValidationError as e:
|
||||
print(f"Invalid manifest: {e}")
|
||||
```
|
||||
|
||||
### CompatibilityError
|
||||
|
||||
Raised when extension is incompatible with current spec-kit version.
|
||||
|
||||
```python
|
||||
from specify_cli.extensions import CompatibilityError
|
||||
|
||||
try:
|
||||
manager.check_compatibility(manifest, "0.1.0")
|
||||
except CompatibilityError as e:
|
||||
print(f"Incompatible: {e}")
|
||||
```
|
||||
|
||||
### ExtensionError
|
||||
|
||||
Base exception for all extension-related errors.
|
||||
|
||||
```python
|
||||
from specify_cli.extensions import ExtensionError
|
||||
|
||||
try:
|
||||
manager.install_from_directory(path, "0.1.0")
|
||||
except ExtensionError as e:
|
||||
print(f"Extension error: {e}")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Version Functions
|
||||
|
||||
### version_satisfies
|
||||
|
||||
Check if a version satisfies a specifier.
|
||||
|
||||
```python
|
||||
from specify_cli.extensions import version_satisfies
|
||||
|
||||
# True if 1.2.3 satisfies >=1.0.0,<2.0.0
|
||||
satisfied = version_satisfies("1.2.3", ">=1.0.0,<2.0.0") # bool
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## File System Layout
|
||||
|
||||
```text
|
||||
.specify/
|
||||
├── extensions/
|
||||
│ ├── .registry # Extension registry (JSON)
|
||||
│ ├── .cache/ # Catalog cache
|
||||
│ │ ├── catalog.json
|
||||
│ │ └── catalog-metadata.json
|
||||
│ ├── .backup/ # Config backups
|
||||
│ │ └── {ext}-{config}.yml
|
||||
│ ├── {extension-id}/ # Extension directory
|
||||
│ │ ├── extension.yml # Manifest
|
||||
│ │ ├── {ext}-config.yml # User config
|
||||
│ │ ├── {ext}-config.local.yml # Local overrides (gitignored)
|
||||
│ │ ├── {ext}-config.template.yml # Template
|
||||
│ │ ├── commands/ # Command files
|
||||
│ │ │ └── *.md
|
||||
│ │ ├── scripts/ # Helper scripts
|
||||
│ │ │ └── *.sh
|
||||
│ │ ├── docs/ # Documentation
|
||||
│ │ └── README.md
|
||||
│ └── extensions.yml # Project extension config
|
||||
└── scripts/ # (existing spec-kit)
|
||||
|
||||
.claude/
|
||||
└── commands/
|
||||
└── speckit.{ext}.{cmd}.md # Registered commands
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
*Last Updated: 2026-01-28*
|
||||
*API Version: 1.0*
|
||||
*Spec Kit Version: 0.1.0*
|
||||
649
extensions/EXTENSION-DEVELOPMENT-GUIDE.md
Normal file
649
extensions/EXTENSION-DEVELOPMENT-GUIDE.md
Normal file
@@ -0,0 +1,649 @@
|
||||
# Extension Development Guide
|
||||
|
||||
A guide for creating Spec Kit extensions.
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Create Extension Directory
|
||||
|
||||
```bash
|
||||
mkdir my-extension
|
||||
cd my-extension
|
||||
```
|
||||
|
||||
### 2. Create `extension.yml` Manifest
|
||||
|
||||
```yaml
|
||||
schema_version: "1.0"
|
||||
|
||||
extension:
|
||||
id: "my-ext" # Lowercase, alphanumeric + hyphens only
|
||||
name: "My Extension"
|
||||
version: "1.0.0" # Semantic versioning
|
||||
description: "My custom extension"
|
||||
author: "Your Name"
|
||||
repository: "https://github.com/you/spec-kit-my-ext"
|
||||
license: "MIT"
|
||||
|
||||
requires:
|
||||
speckit_version: ">=0.1.0" # Minimum spec-kit version
|
||||
tools: # Optional: External tools required
|
||||
- name: "my-tool"
|
||||
required: true
|
||||
version: ">=1.0.0"
|
||||
commands: # Optional: Core commands needed
|
||||
- "speckit.tasks"
|
||||
|
||||
provides:
|
||||
commands:
|
||||
- name: "speckit.my-ext.hello" # Must follow pattern: speckit.{ext-id}.{cmd}
|
||||
file: "commands/hello.md"
|
||||
description: "Say hello"
|
||||
aliases: ["speckit.hello"] # Optional aliases
|
||||
|
||||
config: # Optional: Config files
|
||||
- name: "my-ext-config.yml"
|
||||
template: "my-ext-config.template.yml"
|
||||
description: "Extension configuration"
|
||||
required: false
|
||||
|
||||
hooks: # Optional: Integration hooks
|
||||
after_tasks:
|
||||
command: "speckit.my-ext.hello"
|
||||
optional: true
|
||||
prompt: "Run hello command?"
|
||||
|
||||
tags: # Optional: For catalog search
|
||||
- "example"
|
||||
- "utility"
|
||||
```
|
||||
|
||||
### 3. Create Commands Directory
|
||||
|
||||
```bash
|
||||
mkdir commands
|
||||
```
|
||||
|
||||
### 4. Create Command File
|
||||
|
||||
**File**: `commands/hello.md`
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: "Say hello command"
|
||||
tools: # Optional: AI tools this command uses
|
||||
- 'some-tool/function'
|
||||
scripts: # Optional: Helper scripts
|
||||
sh: ../../scripts/bash/helper.sh
|
||||
ps: ../../scripts/powershell/helper.ps1
|
||||
---
|
||||
|
||||
# Hello Command
|
||||
|
||||
This command says hello!
|
||||
|
||||
## User Input
|
||||
|
||||
$ARGUMENTS
|
||||
|
||||
## Steps
|
||||
|
||||
1. Greet the user
|
||||
2. Show extension is working
|
||||
|
||||
```bash
|
||||
echo "Hello from my extension!"
|
||||
echo "Arguments: $ARGUMENTS"
|
||||
```
|
||||
|
||||
## Extension Configuration
|
||||
|
||||
Load extension config from `.specify/extensions/my-ext/my-ext-config.yml`.
|
||||
|
||||
### 5. Test Locally
|
||||
|
||||
```bash
|
||||
cd /path/to/spec-kit-project
|
||||
specify extension add --dev /path/to/my-extension
|
||||
```
|
||||
|
||||
### 6. Verify Installation
|
||||
|
||||
```bash
|
||||
specify extension list
|
||||
|
||||
# Should show:
|
||||
# ✓ My Extension (v1.0.0)
|
||||
# My custom extension
|
||||
# Commands: 1 | Hooks: 1 | Status: Enabled
|
||||
```
|
||||
|
||||
### 7. Test Command
|
||||
|
||||
If using Claude:
|
||||
|
||||
```bash
|
||||
claude
|
||||
> /speckit.my-ext.hello world
|
||||
```
|
||||
|
||||
The command will be available in `.claude/commands/speckit.my-ext.hello.md`.
|
||||
|
||||
---
|
||||
|
||||
## Manifest Schema Reference
|
||||
|
||||
### Required Fields
|
||||
|
||||
#### `schema_version`
|
||||
|
||||
Extension manifest schema version. Currently: `"1.0"`
|
||||
|
||||
#### `extension`
|
||||
|
||||
Extension metadata block.
|
||||
|
||||
**Required sub-fields**:
|
||||
|
||||
- `id`: Extension identifier (lowercase, alphanumeric, hyphens)
|
||||
- `name`: Human-readable name
|
||||
- `version`: Semantic version (e.g., "1.0.0")
|
||||
- `description`: Short description
|
||||
|
||||
**Optional sub-fields**:
|
||||
|
||||
- `author`: Extension author
|
||||
- `repository`: Source code URL
|
||||
- `license`: SPDX license identifier
|
||||
- `homepage`: Extension homepage URL
|
||||
|
||||
#### `requires`
|
||||
|
||||
Compatibility requirements.
|
||||
|
||||
**Required sub-fields**:
|
||||
|
||||
- `speckit_version`: Semantic version specifier (e.g., ">=0.1.0,<2.0.0")
|
||||
|
||||
**Optional sub-fields**:
|
||||
|
||||
- `tools`: External tools required (array of tool objects)
|
||||
- `commands`: Core spec-kit commands needed (array of command names)
|
||||
- `scripts`: Core scripts required (array of script names)
|
||||
|
||||
#### `provides`
|
||||
|
||||
What the extension provides.
|
||||
|
||||
**Required sub-fields**:
|
||||
|
||||
- `commands`: Array of command objects (must have at least one)
|
||||
|
||||
**Command object**:
|
||||
|
||||
- `name`: Command name (must match `speckit.{ext-id}.{command}`)
|
||||
- `file`: Path to command file (relative to extension root)
|
||||
- `description`: Command description (optional)
|
||||
- `aliases`: Alternative command names (optional, array)
|
||||
|
||||
### Optional Fields
|
||||
|
||||
#### `hooks`
|
||||
|
||||
Integration hooks for automatic execution.
|
||||
|
||||
Available hook points:
|
||||
|
||||
- `after_tasks`: After `/speckit.tasks` completes
|
||||
- `after_implement`: After `/speckit.implement` completes (future)
|
||||
|
||||
Hook object:
|
||||
|
||||
- `command`: Command to execute (must be in `provides.commands`)
|
||||
- `optional`: If true, prompt user before executing
|
||||
- `prompt`: Prompt text for optional hooks
|
||||
- `description`: Hook description
|
||||
- `condition`: Execution condition (future)
|
||||
|
||||
#### `tags`
|
||||
|
||||
Array of tags for catalog discovery.
|
||||
|
||||
#### `defaults`
|
||||
|
||||
Default extension configuration values.
|
||||
|
||||
#### `config_schema`
|
||||
|
||||
JSON Schema for validating extension configuration.
|
||||
|
||||
---
|
||||
|
||||
## Command File Format
|
||||
|
||||
### Frontmatter (YAML)
|
||||
|
||||
```yaml
|
||||
---
|
||||
description: "Command description" # Required
|
||||
tools: # Optional
|
||||
- 'tool-name/function'
|
||||
scripts: # Optional
|
||||
sh: ../../scripts/bash/helper.sh
|
||||
ps: ../../scripts/powershell/helper.ps1
|
||||
---
|
||||
```
|
||||
|
||||
### Body (Markdown)
|
||||
|
||||
Use standard Markdown with special placeholders:
|
||||
|
||||
- `$ARGUMENTS`: User-provided arguments
|
||||
- `{SCRIPT}`: Replaced with script path during registration
|
||||
|
||||
**Example**:
|
||||
|
||||
````markdown
|
||||
## Steps
|
||||
|
||||
1. Parse arguments
|
||||
2. Execute logic
|
||||
|
||||
```bash
|
||||
args="$ARGUMENTS"
|
||||
echo "Running with args: $args"
|
||||
```
|
||||
````
|
||||
|
||||
### Script Path Rewriting
|
||||
|
||||
Extension commands use relative paths that get rewritten during registration:
|
||||
|
||||
**In extension**:
|
||||
|
||||
```yaml
|
||||
scripts:
|
||||
sh: ../../scripts/bash/helper.sh
|
||||
```
|
||||
|
||||
**After registration**:
|
||||
|
||||
```yaml
|
||||
scripts:
|
||||
sh: .specify/scripts/bash/helper.sh
|
||||
```
|
||||
|
||||
This allows scripts to reference core spec-kit scripts.
|
||||
|
||||
---
|
||||
|
||||
## Configuration Files
|
||||
|
||||
### Config Template
|
||||
|
||||
**File**: `my-ext-config.template.yml`
|
||||
|
||||
```yaml
|
||||
# My Extension Configuration
|
||||
# Copy this to my-ext-config.yml and customize
|
||||
|
||||
# Example configuration
|
||||
api:
|
||||
endpoint: "https://api.example.com"
|
||||
timeout: 30
|
||||
|
||||
features:
|
||||
feature_a: true
|
||||
feature_b: false
|
||||
|
||||
credentials:
|
||||
# DO NOT commit credentials!
|
||||
# Use environment variables instead
|
||||
api_key: "${MY_EXT_API_KEY}"
|
||||
```
|
||||
|
||||
### Config Loading
|
||||
|
||||
In your command, load config with layered precedence:
|
||||
|
||||
1. Extension defaults (`extension.yml` → `defaults`)
|
||||
2. Project config (`.specify/extensions/my-ext/my-ext-config.yml`)
|
||||
3. Local overrides (`.specify/extensions/my-ext/my-ext-config.local.yml` - gitignored)
|
||||
4. Environment variables (`SPECKIT_MY_EXT_*`)
|
||||
|
||||
**Example loading script**:
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
EXT_DIR=".specify/extensions/my-ext"
|
||||
|
||||
# Load and merge config
|
||||
config=$(yq eval '.' "$EXT_DIR/my-ext-config.yml" -o=json)
|
||||
|
||||
# Apply env overrides
|
||||
if [ -n "${SPECKIT_MY_EXT_API_KEY:-}" ]; then
|
||||
config=$(echo "$config" | jq ".api.api_key = \"$SPECKIT_MY_EXT_API_KEY\"")
|
||||
fi
|
||||
|
||||
echo "$config"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Validation Rules
|
||||
|
||||
### Extension ID
|
||||
|
||||
- **Pattern**: `^[a-z0-9-]+$`
|
||||
- **Valid**: `my-ext`, `tool-123`, `awesome-plugin`
|
||||
- **Invalid**: `MyExt` (uppercase), `my_ext` (underscore), `my ext` (space)
|
||||
|
||||
### Extension Version
|
||||
|
||||
- **Format**: Semantic versioning (MAJOR.MINOR.PATCH)
|
||||
- **Valid**: `1.0.0`, `0.1.0`, `2.5.3`
|
||||
- **Invalid**: `1.0`, `v1.0.0`, `1.0.0-beta`
|
||||
|
||||
### Command Name
|
||||
|
||||
- **Pattern**: `^speckit\.[a-z0-9-]+\.[a-z0-9-]+$`
|
||||
- **Valid**: `speckit.my-ext.hello`, `speckit.tool.cmd`
|
||||
- **Invalid**: `my-ext.hello` (missing prefix), `speckit.hello` (no extension namespace)
|
||||
|
||||
### Command File Path
|
||||
|
||||
- **Must be** relative to extension root
|
||||
- **Valid**: `commands/hello.md`, `commands/subdir/cmd.md`
|
||||
- **Invalid**: `/absolute/path.md`, `../outside.md`
|
||||
|
||||
---
|
||||
|
||||
## Testing Extensions
|
||||
|
||||
### Manual Testing
|
||||
|
||||
1. **Create test extension**
|
||||
2. **Install locally**:
|
||||
|
||||
```bash
|
||||
specify extension add --dev /path/to/extension
|
||||
```
|
||||
|
||||
3. **Verify installation**:
|
||||
|
||||
```bash
|
||||
specify extension list
|
||||
```
|
||||
|
||||
4. **Test commands** with your AI agent
|
||||
5. **Check command registration**:
|
||||
|
||||
```bash
|
||||
ls .claude/commands/speckit.my-ext.*
|
||||
```
|
||||
|
||||
6. **Remove extension**:
|
||||
|
||||
```bash
|
||||
specify extension remove my-ext
|
||||
```
|
||||
|
||||
### Automated Testing
|
||||
|
||||
Create tests for your extension:
|
||||
|
||||
```python
|
||||
# tests/test_my_extension.py
|
||||
import pytest
|
||||
from pathlib import Path
|
||||
from specify_cli.extensions import ExtensionManifest
|
||||
|
||||
def test_manifest_valid():
|
||||
"""Test extension manifest is valid."""
|
||||
manifest = ExtensionManifest(Path("extension.yml"))
|
||||
assert manifest.id == "my-ext"
|
||||
assert len(manifest.commands) >= 1
|
||||
|
||||
def test_command_files_exist():
|
||||
"""Test all command files exist."""
|
||||
manifest = ExtensionManifest(Path("extension.yml"))
|
||||
for cmd in manifest.commands:
|
||||
cmd_file = Path(cmd["file"])
|
||||
assert cmd_file.exists(), f"Command file not found: {cmd_file}"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Distribution
|
||||
|
||||
### Option 1: GitHub Repository
|
||||
|
||||
1. **Create repository**: `spec-kit-my-ext`
|
||||
2. **Add files**:
|
||||
|
||||
```text
|
||||
spec-kit-my-ext/
|
||||
├── extension.yml
|
||||
├── commands/
|
||||
├── scripts/
|
||||
├── docs/
|
||||
├── README.md
|
||||
├── LICENSE
|
||||
└── CHANGELOG.md
|
||||
```
|
||||
|
||||
3. **Create release**: Tag with version (e.g., `v1.0.0`)
|
||||
4. **Install from repo**:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/you/spec-kit-my-ext
|
||||
specify extension add --dev spec-kit-my-ext/
|
||||
```
|
||||
|
||||
### Option 2: ZIP Archive (Future)
|
||||
|
||||
Create ZIP archive and host on GitHub Releases:
|
||||
|
||||
```bash
|
||||
zip -r spec-kit-my-ext-1.0.0.zip extension.yml commands/ scripts/ docs/
|
||||
```
|
||||
|
||||
Users install with:
|
||||
|
||||
```bash
|
||||
specify extension add --from https://github.com/.../spec-kit-my-ext-1.0.0.zip
|
||||
```
|
||||
|
||||
### Option 3: Extension Catalog (Future)
|
||||
|
||||
Submit to official catalog:
|
||||
|
||||
1. **Fork** spec-kit repository
|
||||
2. **Add entry** to `extensions/catalog.json`
|
||||
3. **Create PR**
|
||||
4. **After merge**, users can install with:
|
||||
|
||||
```bash
|
||||
specify extension add my-ext # No URL needed!
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Naming Conventions
|
||||
|
||||
- **Extension ID**: Use descriptive, hyphenated names (`jira-integration`, not `ji`)
|
||||
- **Commands**: Use verb-noun pattern (`create-issue`, `sync-status`)
|
||||
- **Config files**: Match extension ID (`jira-config.yml`)
|
||||
|
||||
### Documentation
|
||||
|
||||
- **README.md**: Overview, installation, usage
|
||||
- **CHANGELOG.md**: Version history
|
||||
- **docs/**: Detailed guides
|
||||
- **Command descriptions**: Clear, concise
|
||||
|
||||
### Versioning
|
||||
|
||||
- **Follow SemVer**: `MAJOR.MINOR.PATCH`
|
||||
- **MAJOR**: Breaking changes
|
||||
- **MINOR**: New features
|
||||
- **PATCH**: Bug fixes
|
||||
|
||||
### Security
|
||||
|
||||
- **Never commit secrets**: Use environment variables
|
||||
- **Validate input**: Sanitize user arguments
|
||||
- **Document permissions**: What files/APIs are accessed
|
||||
|
||||
### Compatibility
|
||||
|
||||
- **Specify version range**: Don't require exact version
|
||||
- **Test with multiple versions**: Ensure compatibility
|
||||
- **Graceful degradation**: Handle missing features
|
||||
|
||||
---
|
||||
|
||||
## Example Extensions
|
||||
|
||||
### Minimal Extension
|
||||
|
||||
Smallest possible extension:
|
||||
|
||||
```yaml
|
||||
# extension.yml
|
||||
schema_version: "1.0"
|
||||
extension:
|
||||
id: "minimal"
|
||||
name: "Minimal Extension"
|
||||
version: "1.0.0"
|
||||
description: "Minimal example"
|
||||
requires:
|
||||
speckit_version: ">=0.1.0"
|
||||
provides:
|
||||
commands:
|
||||
- name: "speckit.minimal.hello"
|
||||
file: "commands/hello.md"
|
||||
```
|
||||
|
||||
````markdown
|
||||
<!-- commands/hello.md -->
|
||||
---
|
||||
description: "Hello command"
|
||||
---
|
||||
|
||||
# Hello World
|
||||
|
||||
```bash
|
||||
echo "Hello, $ARGUMENTS!"
|
||||
```
|
||||
````
|
||||
|
||||
### Extension with Config
|
||||
|
||||
Extension using configuration:
|
||||
|
||||
```yaml
|
||||
# extension.yml
|
||||
# ... metadata ...
|
||||
provides:
|
||||
config:
|
||||
- name: "tool-config.yml"
|
||||
template: "tool-config.template.yml"
|
||||
required: true
|
||||
```
|
||||
|
||||
```yaml
|
||||
# tool-config.template.yml
|
||||
api_endpoint: "https://api.example.com"
|
||||
timeout: 30
|
||||
```
|
||||
|
||||
````markdown
|
||||
<!-- commands/use-config.md -->
|
||||
# Use Config
|
||||
|
||||
Load config:
|
||||
```bash
|
||||
config_file=".specify/extensions/tool/tool-config.yml"
|
||||
endpoint=$(yq eval '.api_endpoint' "$config_file")
|
||||
echo "Using endpoint: $endpoint"
|
||||
```
|
||||
````
|
||||
|
||||
### Extension with Hooks
|
||||
|
||||
Extension that runs automatically:
|
||||
|
||||
```yaml
|
||||
# extension.yml
|
||||
hooks:
|
||||
after_tasks:
|
||||
command: "speckit.auto.analyze"
|
||||
optional: false # Always run
|
||||
description: "Analyze tasks after generation"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Extension won't install
|
||||
|
||||
**Error**: `Invalid extension ID`
|
||||
|
||||
- **Fix**: Use lowercase, alphanumeric + hyphens only
|
||||
|
||||
**Error**: `Extension requires spec-kit >=0.2.0`
|
||||
|
||||
- **Fix**: Update spec-kit with `uv tool install specify-cli --force`
|
||||
|
||||
**Error**: `Command file not found`
|
||||
|
||||
- **Fix**: Ensure command files exist at paths specified in manifest
|
||||
|
||||
### Commands not registered
|
||||
|
||||
**Symptom**: Commands don't appear in AI agent
|
||||
|
||||
**Check**:
|
||||
|
||||
1. `.claude/commands/` directory exists
|
||||
2. Extension installed successfully
|
||||
3. Commands registered in registry:
|
||||
|
||||
```bash
|
||||
cat .specify/extensions/.registry
|
||||
```
|
||||
|
||||
**Fix**: Reinstall extension to trigger registration
|
||||
|
||||
### Config not loading
|
||||
|
||||
**Check**:
|
||||
|
||||
1. Config file exists: `.specify/extensions/{ext-id}/{ext-id}-config.yml`
|
||||
2. YAML syntax is valid: `yq eval '.' config.yml`
|
||||
3. Environment variables set correctly
|
||||
|
||||
---
|
||||
|
||||
## Getting Help
|
||||
|
||||
- **Issues**: Report bugs at GitHub repository
|
||||
- **Discussions**: Ask questions in GitHub Discussions
|
||||
- **Examples**: See `spec-kit-jira` for full-featured example (Phase B)
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Create your extension** following this guide
|
||||
2. **Test locally** with `--dev` flag
|
||||
3. **Share with community** (GitHub, catalog)
|
||||
4. **Iterate** based on feedback
|
||||
|
||||
Happy extending! 🚀
|
||||
530
extensions/EXTENSION-PUBLISHING-GUIDE.md
Normal file
530
extensions/EXTENSION-PUBLISHING-GUIDE.md
Normal file
@@ -0,0 +1,530 @@
|
||||
# Extension Publishing Guide
|
||||
|
||||
This guide explains how to publish your extension to the Spec Kit extension catalog, making it discoverable by `specify extension search`.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Prerequisites](#prerequisites)
|
||||
2. [Prepare Your Extension](#prepare-your-extension)
|
||||
3. [Submit to Catalog](#submit-to-catalog)
|
||||
4. [Verification Process](#verification-process)
|
||||
5. [Release Workflow](#release-workflow)
|
||||
6. [Best Practices](#best-practices)
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before publishing an extension, ensure you have:
|
||||
|
||||
1. **Valid Extension**: A working extension with a valid `extension.yml` manifest
|
||||
2. **Git Repository**: Extension hosted on GitHub (or other public git hosting)
|
||||
3. **Documentation**: README.md with installation and usage instructions
|
||||
4. **License**: Open source license file (MIT, Apache 2.0, etc.)
|
||||
5. **Versioning**: Semantic versioning (e.g., 1.0.0)
|
||||
6. **Testing**: Extension tested on real projects
|
||||
|
||||
---
|
||||
|
||||
## Prepare Your Extension
|
||||
|
||||
### 1. Extension Structure
|
||||
|
||||
Ensure your extension follows the standard structure:
|
||||
|
||||
```text
|
||||
your-extension/
|
||||
├── extension.yml # Required: Extension manifest
|
||||
├── README.md # Required: Documentation
|
||||
├── LICENSE # Required: License file
|
||||
├── CHANGELOG.md # Recommended: Version history
|
||||
├── .gitignore # Recommended: Git ignore rules
|
||||
│
|
||||
├── commands/ # Extension commands
|
||||
│ ├── command1.md
|
||||
│ └── command2.md
|
||||
│
|
||||
├── config-template.yml # Config template (if needed)
|
||||
│
|
||||
└── docs/ # Additional documentation
|
||||
├── usage.md
|
||||
└── examples/
|
||||
```
|
||||
|
||||
### 2. extension.yml Validation
|
||||
|
||||
Verify your manifest is valid:
|
||||
|
||||
```yaml
|
||||
schema_version: "1.0"
|
||||
|
||||
extension:
|
||||
id: "your-extension" # Unique lowercase-hyphenated ID
|
||||
name: "Your Extension Name" # Human-readable name
|
||||
version: "1.0.0" # Semantic version
|
||||
description: "Brief description (one sentence)"
|
||||
author: "Your Name or Organization"
|
||||
repository: "https://github.com/your-org/spec-kit-your-extension"
|
||||
license: "MIT"
|
||||
homepage: "https://github.com/your-org/spec-kit-your-extension"
|
||||
|
||||
requires:
|
||||
speckit_version: ">=0.1.0" # Required spec-kit version
|
||||
|
||||
provides:
|
||||
commands: # List all commands
|
||||
- name: "speckit.your-extension.command"
|
||||
file: "commands/command.md"
|
||||
description: "Command description"
|
||||
|
||||
tags: # 2-5 relevant tags
|
||||
- "category"
|
||||
- "tool-name"
|
||||
```
|
||||
|
||||
**Validation Checklist**:
|
||||
|
||||
- ✅ `id` is lowercase with hyphens only (no underscores, spaces, or special characters)
|
||||
- ✅ `version` follows semantic versioning (X.Y.Z)
|
||||
- ✅ `description` is concise (under 100 characters)
|
||||
- ✅ `repository` URL is valid and public
|
||||
- ✅ All command files exist in the extension directory
|
||||
- ✅ Tags are lowercase and descriptive
|
||||
|
||||
### 3. Create GitHub Release
|
||||
|
||||
Create a GitHub release for your extension version:
|
||||
|
||||
```bash
|
||||
# Tag the release
|
||||
git tag v1.0.0
|
||||
git push origin v1.0.0
|
||||
|
||||
# Create release on GitHub
|
||||
# Go to: https://github.com/your-org/spec-kit-your-extension/releases/new
|
||||
# - Tag: v1.0.0
|
||||
# - Title: v1.0.0 - Release Name
|
||||
# - Description: Changelog/release notes
|
||||
```
|
||||
|
||||
The release archive URL will be:
|
||||
|
||||
```text
|
||||
https://github.com/your-org/spec-kit-your-extension/archive/refs/tags/v1.0.0.zip
|
||||
```
|
||||
|
||||
### 4. Test Installation
|
||||
|
||||
Test that users can install from your release:
|
||||
|
||||
```bash
|
||||
# Test dev installation
|
||||
specify extension add --dev /path/to/your-extension
|
||||
|
||||
# Test from GitHub archive
|
||||
specify extension add --from https://github.com/your-org/spec-kit-your-extension/archive/refs/tags/v1.0.0.zip
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Submit to Catalog
|
||||
|
||||
### 1. Fork the spec-kit Repository
|
||||
|
||||
```bash
|
||||
# Fork on GitHub
|
||||
# https://github.com/statsperform/spec-kit/fork
|
||||
|
||||
# Clone your fork
|
||||
git clone https://github.com/YOUR-USERNAME/spec-kit.git
|
||||
cd spec-kit
|
||||
```
|
||||
|
||||
### 2. Add Extension to Catalog
|
||||
|
||||
Edit `extensions/catalog.json` and add your extension:
|
||||
|
||||
```json
|
||||
{
|
||||
"schema_version": "1.0",
|
||||
"updated_at": "2026-01-28T15:54:00Z",
|
||||
"catalog_url": "https://raw.githubusercontent.com/statsperform/spec-kit/main/extensions/catalog.json",
|
||||
"extensions": {
|
||||
"your-extension": {
|
||||
"name": "Your Extension Name",
|
||||
"id": "your-extension",
|
||||
"description": "Brief description of your extension",
|
||||
"author": "Your Name",
|
||||
"version": "1.0.0",
|
||||
"download_url": "https://github.com/your-org/spec-kit-your-extension/archive/refs/tags/v1.0.0.zip",
|
||||
"repository": "https://github.com/your-org/spec-kit-your-extension",
|
||||
"homepage": "https://github.com/your-org/spec-kit-your-extension",
|
||||
"documentation": "https://github.com/your-org/spec-kit-your-extension/blob/main/docs/",
|
||||
"changelog": "https://github.com/your-org/spec-kit-your-extension/blob/main/CHANGELOG.md",
|
||||
"license": "MIT",
|
||||
"requires": {
|
||||
"speckit_version": ">=0.1.0",
|
||||
"tools": [
|
||||
{
|
||||
"name": "required-mcp-tool",
|
||||
"version": ">=1.0.0",
|
||||
"required": true
|
||||
}
|
||||
]
|
||||
},
|
||||
"provides": {
|
||||
"commands": 3,
|
||||
"hooks": 1
|
||||
},
|
||||
"tags": [
|
||||
"category",
|
||||
"tool-name",
|
||||
"feature"
|
||||
],
|
||||
"verified": false,
|
||||
"downloads": 0,
|
||||
"stars": 0,
|
||||
"created_at": "2026-01-28T00:00:00Z",
|
||||
"updated_at": "2026-01-28T00:00:00Z"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Important**:
|
||||
|
||||
- Set `verified: false` (maintainers will verify)
|
||||
- Set `downloads: 0` and `stars: 0` (auto-updated later)
|
||||
- Use current timestamp for `created_at` and `updated_at`
|
||||
- Update the top-level `updated_at` to current time
|
||||
|
||||
### 3. Submit Pull Request
|
||||
|
||||
```bash
|
||||
# Create a branch
|
||||
git checkout -b add-your-extension
|
||||
|
||||
# Commit your changes
|
||||
git add extensions/catalog.json
|
||||
git commit -m "Add your-extension to catalog
|
||||
|
||||
- Extension ID: your-extension
|
||||
- Version: 1.0.0
|
||||
- Author: Your Name
|
||||
- Description: Brief description
|
||||
"
|
||||
|
||||
# Push to your fork
|
||||
git push origin add-your-extension
|
||||
|
||||
# Create Pull Request on GitHub
|
||||
# https://github.com/statsperform/spec-kit/compare
|
||||
```
|
||||
|
||||
**Pull Request Template**:
|
||||
|
||||
```markdown
|
||||
## Extension Submission
|
||||
|
||||
**Extension Name**: Your Extension Name
|
||||
**Extension ID**: your-extension
|
||||
**Version**: 1.0.0
|
||||
**Author**: Your Name
|
||||
**Repository**: https://github.com/your-org/spec-kit-your-extension
|
||||
|
||||
### Description
|
||||
Brief description of what your extension does.
|
||||
|
||||
### Checklist
|
||||
- [x] Valid extension.yml manifest
|
||||
- [x] README.md with installation and usage docs
|
||||
- [x] LICENSE file included
|
||||
- [x] GitHub release created (v1.0.0)
|
||||
- [x] Extension tested on real project
|
||||
- [x] All commands working
|
||||
- [x] No security vulnerabilities
|
||||
|
||||
### Testing
|
||||
Tested on:
|
||||
- macOS 13.0+ with spec-kit 0.1.0
|
||||
- Project: [Your test project]
|
||||
|
||||
### Additional Notes
|
||||
Any additional context or notes for reviewers.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Verification Process
|
||||
|
||||
### What Happens After Submission
|
||||
|
||||
1. **Automated Checks** (if available):
|
||||
- Manifest validation
|
||||
- Download URL accessibility
|
||||
- Repository existence
|
||||
- License file presence
|
||||
|
||||
2. **Manual Review**:
|
||||
- Code quality review
|
||||
- Security audit
|
||||
- Functionality testing
|
||||
- Documentation review
|
||||
|
||||
3. **Verification**:
|
||||
- If approved, `verified: true` is set
|
||||
- Extension appears in `specify extension search --verified`
|
||||
|
||||
### Verification Criteria
|
||||
|
||||
To be verified, your extension must:
|
||||
|
||||
✅ **Functionality**:
|
||||
|
||||
- Works as described in documentation
|
||||
- All commands execute without errors
|
||||
- No breaking changes to user workflows
|
||||
|
||||
✅ **Security**:
|
||||
|
||||
- No known vulnerabilities
|
||||
- No malicious code
|
||||
- Safe handling of user data
|
||||
- Proper validation of inputs
|
||||
|
||||
✅ **Code Quality**:
|
||||
|
||||
- Clean, readable code
|
||||
- Follows extension best practices
|
||||
- Proper error handling
|
||||
- Helpful error messages
|
||||
|
||||
✅ **Documentation**:
|
||||
|
||||
- Clear installation instructions
|
||||
- Usage examples
|
||||
- Troubleshooting section
|
||||
- Accurate description
|
||||
|
||||
✅ **Maintenance**:
|
||||
|
||||
- Active repository
|
||||
- Responsive to issues
|
||||
- Regular updates
|
||||
- Semantic versioning followed
|
||||
|
||||
### Typical Review Timeline
|
||||
|
||||
- **Automated checks**: Immediate (if implemented)
|
||||
- **Manual review**: 3-7 business days
|
||||
- **Verification**: After successful review
|
||||
|
||||
---
|
||||
|
||||
## Release Workflow
|
||||
|
||||
### Publishing New Versions
|
||||
|
||||
When releasing a new version:
|
||||
|
||||
1. **Update version** in `extension.yml`:
|
||||
|
||||
```yaml
|
||||
extension:
|
||||
version: "1.1.0" # Updated version
|
||||
```
|
||||
|
||||
2. **Update CHANGELOG.md**:
|
||||
|
||||
```markdown
|
||||
## [1.1.0] - 2026-02-15
|
||||
|
||||
### Added
|
||||
- New feature X
|
||||
|
||||
### Fixed
|
||||
- Bug fix Y
|
||||
```
|
||||
|
||||
3. **Create GitHub release**:
|
||||
|
||||
```bash
|
||||
git tag v1.1.0
|
||||
git push origin v1.1.0
|
||||
# Create release on GitHub
|
||||
```
|
||||
|
||||
4. **Update catalog**:
|
||||
|
||||
```bash
|
||||
# Fork spec-kit repo (or update existing fork)
|
||||
cd spec-kit
|
||||
|
||||
# Update extensions/catalog.json
|
||||
jq '.extensions["your-extension"].version = "1.1.0"' extensions/catalog.json > tmp.json && mv tmp.json extensions/catalog.json
|
||||
jq '.extensions["your-extension"].download_url = "https://github.com/your-org/spec-kit-your-extension/archive/refs/tags/v1.1.0.zip"' extensions/catalog.json > tmp.json && mv tmp.json extensions/catalog.json
|
||||
jq '.extensions["your-extension"].updated_at = "2026-02-15T00:00:00Z"' extensions/catalog.json > tmp.json && mv tmp.json extensions/catalog.json
|
||||
jq '.updated_at = "2026-02-15T00:00:00Z"' extensions/catalog.json > tmp.json && mv tmp.json extensions/catalog.json
|
||||
|
||||
# Submit PR
|
||||
git checkout -b update-your-extension-v1.1.0
|
||||
git add extensions/catalog.json
|
||||
git commit -m "Update your-extension to v1.1.0"
|
||||
git push origin update-your-extension-v1.1.0
|
||||
```
|
||||
|
||||
5. **Submit update PR** with changelog in description
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Extension Design
|
||||
|
||||
1. **Single Responsibility**: Each extension should focus on one tool/integration
|
||||
2. **Clear Naming**: Use descriptive, unambiguous names
|
||||
3. **Minimal Dependencies**: Avoid unnecessary dependencies
|
||||
4. **Backward Compatibility**: Follow semantic versioning strictly
|
||||
|
||||
### Documentation
|
||||
|
||||
1. **README.md Structure**:
|
||||
- Overview and features
|
||||
- Installation instructions
|
||||
- Configuration guide
|
||||
- Usage examples
|
||||
- Troubleshooting
|
||||
- Contributing guidelines
|
||||
|
||||
2. **Command Documentation**:
|
||||
- Clear description
|
||||
- Prerequisites listed
|
||||
- Step-by-step instructions
|
||||
- Error handling guidance
|
||||
- Examples
|
||||
|
||||
3. **Configuration**:
|
||||
- Provide template file
|
||||
- Document all options
|
||||
- Include examples
|
||||
- Explain defaults
|
||||
|
||||
### Security
|
||||
|
||||
1. **Input Validation**: Validate all user inputs
|
||||
2. **No Hardcoded Secrets**: Never include credentials
|
||||
3. **Safe Dependencies**: Only use trusted dependencies
|
||||
4. **Audit Regularly**: Check for vulnerabilities
|
||||
|
||||
### Maintenance
|
||||
|
||||
1. **Respond to Issues**: Address issues within 1-2 weeks
|
||||
2. **Regular Updates**: Keep dependencies updated
|
||||
3. **Changelog**: Maintain detailed changelog
|
||||
4. **Deprecation**: Give advance notice for breaking changes
|
||||
|
||||
### Community
|
||||
|
||||
1. **License**: Use permissive open-source license (MIT, Apache 2.0)
|
||||
2. **Contributing**: Welcome contributions
|
||||
3. **Code of Conduct**: Be respectful and inclusive
|
||||
4. **Support**: Provide ways to get help (issues, discussions, email)
|
||||
|
||||
---
|
||||
|
||||
## FAQ
|
||||
|
||||
### Q: Can I publish private/proprietary extensions?
|
||||
|
||||
A: The main catalog is for public extensions only. For private extensions:
|
||||
|
||||
- Host your own catalog.json file
|
||||
- Users add your catalog: `specify extension add-catalog https://your-domain.com/catalog.json`
|
||||
- Not yet implemented - coming in Phase 4
|
||||
|
||||
### Q: How long does verification take?
|
||||
|
||||
A: Typically 3-7 business days for initial review. Updates to verified extensions are usually faster.
|
||||
|
||||
### Q: What if my extension is rejected?
|
||||
|
||||
A: You'll receive feedback on what needs to be fixed. Make the changes and resubmit.
|
||||
|
||||
### Q: Can I update my extension anytime?
|
||||
|
||||
A: Yes, submit a PR to update the catalog with your new version. Verified status may be re-evaluated for major changes.
|
||||
|
||||
### Q: Do I need to be verified to be in the catalog?
|
||||
|
||||
A: No, unverified extensions are still searchable. Verification just adds trust and visibility.
|
||||
|
||||
### Q: Can extensions have paid features?
|
||||
|
||||
A: Extensions should be free and open-source. Commercial support/services are allowed, but core functionality must be free.
|
||||
|
||||
---
|
||||
|
||||
## Support
|
||||
|
||||
- **Catalog Issues**: <https://github.com/statsperform/spec-kit/issues>
|
||||
- **Extension Template**: <https://github.com/statsperform/spec-kit-extension-template> (coming soon)
|
||||
- **Development Guide**: See EXTENSION-DEVELOPMENT-GUIDE.md
|
||||
- **Community**: Discussions and Q&A
|
||||
|
||||
---
|
||||
|
||||
## Appendix: Catalog Schema
|
||||
|
||||
### Complete Catalog Entry Schema
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "string (required)",
|
||||
"id": "string (required, unique)",
|
||||
"description": "string (required, <200 chars)",
|
||||
"author": "string (required)",
|
||||
"version": "string (required, semver)",
|
||||
"download_url": "string (required, valid URL)",
|
||||
"repository": "string (required, valid URL)",
|
||||
"homepage": "string (optional, valid URL)",
|
||||
"documentation": "string (optional, valid URL)",
|
||||
"changelog": "string (optional, valid URL)",
|
||||
"license": "string (required)",
|
||||
"requires": {
|
||||
"speckit_version": "string (required, version specifier)",
|
||||
"tools": [
|
||||
{
|
||||
"name": "string (required)",
|
||||
"version": "string (optional, version specifier)",
|
||||
"required": "boolean (default: false)"
|
||||
}
|
||||
]
|
||||
},
|
||||
"provides": {
|
||||
"commands": "integer (optional)",
|
||||
"hooks": "integer (optional)"
|
||||
},
|
||||
"tags": ["array of strings (2-10 tags)"],
|
||||
"verified": "boolean (default: false)",
|
||||
"downloads": "integer (auto-updated)",
|
||||
"stars": "integer (auto-updated)",
|
||||
"created_at": "string (ISO 8601 datetime)",
|
||||
"updated_at": "string (ISO 8601 datetime)"
|
||||
}
|
||||
```
|
||||
|
||||
### Valid Tags
|
||||
|
||||
Recommended tag categories:
|
||||
|
||||
- **Integration**: jira, linear, github, gitlab, azure-devops
|
||||
- **Category**: issue-tracking, vcs, ci-cd, documentation, testing
|
||||
- **Platform**: atlassian, microsoft, google
|
||||
- **Feature**: automation, reporting, deployment, monitoring
|
||||
|
||||
Use 2-5 tags that best describe your extension.
|
||||
|
||||
---
|
||||
|
||||
*Last Updated: 2026-01-28*
|
||||
*Catalog Format Version: 1.0*
|
||||
885
extensions/EXTENSION-USER-GUIDE.md
Normal file
885
extensions/EXTENSION-USER-GUIDE.md
Normal file
@@ -0,0 +1,885 @@
|
||||
# Extension User Guide
|
||||
|
||||
Complete guide for using Spec Kit extensions to enhance your workflow.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Introduction](#introduction)
|
||||
2. [Getting Started](#getting-started)
|
||||
3. [Finding Extensions](#finding-extensions)
|
||||
4. [Installing Extensions](#installing-extensions)
|
||||
5. [Using Extensions](#using-extensions)
|
||||
6. [Managing Extensions](#managing-extensions)
|
||||
7. [Configuration](#configuration)
|
||||
8. [Troubleshooting](#troubleshooting)
|
||||
9. [Best Practices](#best-practices)
|
||||
|
||||
---
|
||||
|
||||
## Introduction
|
||||
|
||||
### What are Extensions?
|
||||
|
||||
Extensions are modular packages that add new commands and functionality to Spec Kit without bloating the core framework. They allow you to:
|
||||
|
||||
- **Integrate** with external tools (Jira, Linear, GitHub, etc.)
|
||||
- **Automate** repetitive tasks with hooks
|
||||
- **Customize** workflows for your team
|
||||
- **Share** solutions across projects
|
||||
|
||||
### Why Use Extensions?
|
||||
|
||||
- **Clean Core**: Keeps spec-kit lightweight and focused
|
||||
- **Optional Features**: Only install what you need
|
||||
- **Community Driven**: Anyone can create and share extensions
|
||||
- **Version Controlled**: Extensions are versioned independently
|
||||
|
||||
---
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Spec Kit version 0.1.0 or higher
|
||||
- A spec-kit project (directory with `.specify/` folder)
|
||||
|
||||
### Check Your Version
|
||||
|
||||
```bash
|
||||
specify --version
|
||||
# Should show 0.1.0 or higher
|
||||
```
|
||||
|
||||
### First Extension
|
||||
|
||||
Let's install the Jira extension as an example:
|
||||
|
||||
```bash
|
||||
# 1. Search for the extension
|
||||
specify extension search jira
|
||||
|
||||
# 2. Get detailed information
|
||||
specify extension info jira
|
||||
|
||||
# 3. Install it
|
||||
specify extension add jira
|
||||
|
||||
# 4. Configure it
|
||||
vim .specify/extensions/jira/jira-config.yml
|
||||
|
||||
# 5. Use it
|
||||
# (Commands are now available in Claude Code)
|
||||
/speckit.jira.specstoissues
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Finding Extensions
|
||||
|
||||
### Browse All Extensions
|
||||
|
||||
```bash
|
||||
specify extension search
|
||||
```
|
||||
|
||||
Shows all available extensions in the catalog.
|
||||
|
||||
### Search by Keyword
|
||||
|
||||
```bash
|
||||
# Search for "jira"
|
||||
specify extension search jira
|
||||
|
||||
# Search for "issue tracking"
|
||||
specify extension search issue
|
||||
```
|
||||
|
||||
### Filter by Tag
|
||||
|
||||
```bash
|
||||
# Find all issue-tracking extensions
|
||||
specify extension search --tag issue-tracking
|
||||
|
||||
# Find all Atlassian tools
|
||||
specify extension search --tag atlassian
|
||||
```
|
||||
|
||||
### Filter by Author
|
||||
|
||||
```bash
|
||||
# Extensions by Stats Perform
|
||||
specify extension search --author "Stats Perform"
|
||||
```
|
||||
|
||||
### Show Verified Only
|
||||
|
||||
```bash
|
||||
# Only show verified extensions
|
||||
specify extension search --verified
|
||||
```
|
||||
|
||||
### Get Extension Details
|
||||
|
||||
```bash
|
||||
# Detailed information
|
||||
specify extension info jira
|
||||
```
|
||||
|
||||
Shows:
|
||||
|
||||
- Description
|
||||
- Requirements
|
||||
- Commands provided
|
||||
- Hooks available
|
||||
- Links (documentation, repository, changelog)
|
||||
- Installation status
|
||||
|
||||
---
|
||||
|
||||
## Installing Extensions
|
||||
|
||||
### Install from Catalog
|
||||
|
||||
```bash
|
||||
# By name (from catalog)
|
||||
specify extension add jira
|
||||
```
|
||||
|
||||
This will:
|
||||
|
||||
1. Download the extension from GitHub
|
||||
2. Validate the manifest
|
||||
3. Check compatibility with your spec-kit version
|
||||
4. Install to `.specify/extensions/jira/`
|
||||
5. Register commands with your AI agent
|
||||
6. Create config template
|
||||
|
||||
### Install from URL
|
||||
|
||||
```bash
|
||||
# From GitHub release
|
||||
specify extension add --from https://github.com/org/spec-kit-ext/archive/refs/tags/v1.0.0.zip
|
||||
```
|
||||
|
||||
### Install from Local Directory (Development)
|
||||
|
||||
```bash
|
||||
# For testing or development
|
||||
specify extension add --dev /path/to/extension
|
||||
```
|
||||
|
||||
### Installation Output
|
||||
|
||||
```text
|
||||
✓ Extension installed successfully!
|
||||
|
||||
Jira Integration (v1.0.0)
|
||||
Create Jira Epics, Stories, and Issues from spec-kit artifacts
|
||||
|
||||
Provided commands:
|
||||
• speckit.jira.specstoissues - Create Jira hierarchy from spec and tasks
|
||||
• speckit.jira.discover-fields - Discover Jira custom fields for configuration
|
||||
• speckit.jira.sync-status - Sync task completion status to Jira
|
||||
|
||||
⚠ Configuration may be required
|
||||
Check: .specify/extensions/jira/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Using Extensions
|
||||
|
||||
### Using Extension Commands
|
||||
|
||||
Extensions add commands that appear in your AI agent (Claude Code):
|
||||
|
||||
```text
|
||||
# In Claude Code
|
||||
> /speckit.jira.specstoissues
|
||||
|
||||
# Or use short alias (if provided)
|
||||
> /speckit.specstoissues
|
||||
```
|
||||
|
||||
### Extension Configuration
|
||||
|
||||
Most extensions require configuration:
|
||||
|
||||
```bash
|
||||
# 1. Find the config file
|
||||
ls .specify/extensions/jira/
|
||||
|
||||
# 2. Copy template to config
|
||||
cp .specify/extensions/jira/jira-config.template.yml \
|
||||
.specify/extensions/jira/jira-config.yml
|
||||
|
||||
# 3. Edit configuration
|
||||
vim .specify/extensions/jira/jira-config.yml
|
||||
|
||||
# 4. Use the extension
|
||||
# (Commands will now work with your config)
|
||||
```
|
||||
|
||||
### Extension Hooks
|
||||
|
||||
Some extensions provide hooks that execute after core commands:
|
||||
|
||||
**Example**: Jira extension hooks into `/speckit.tasks`
|
||||
|
||||
```text
|
||||
# Run core command
|
||||
> /speckit.tasks
|
||||
|
||||
# Output includes:
|
||||
## Extension Hooks
|
||||
|
||||
**Optional Hook**: jira
|
||||
Command: `/speckit.jira.specstoissues`
|
||||
Description: Automatically create Jira hierarchy after task generation
|
||||
|
||||
Prompt: Create Jira issues from tasks?
|
||||
To execute: `/speckit.jira.specstoissues`
|
||||
```
|
||||
|
||||
You can then choose to run the hook or skip it.
|
||||
|
||||
---
|
||||
|
||||
## Managing Extensions
|
||||
|
||||
### List Installed Extensions
|
||||
|
||||
```bash
|
||||
specify extension list
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```text
|
||||
Installed Extensions:
|
||||
|
||||
✓ Jira Integration (v1.0.0)
|
||||
Create Jira Epics, Stories, and Issues from spec-kit artifacts
|
||||
Commands: 3 | Hooks: 1 | Status: Enabled
|
||||
```
|
||||
|
||||
### Update Extensions
|
||||
|
||||
```bash
|
||||
# Check for updates (all extensions)
|
||||
specify extension update
|
||||
|
||||
# Update specific extension
|
||||
specify extension update jira
|
||||
```
|
||||
|
||||
Output:
|
||||
|
||||
```text
|
||||
🔄 Checking for updates...
|
||||
|
||||
Updates available:
|
||||
|
||||
• jira: 1.0.0 → 1.1.0
|
||||
|
||||
Update these extensions? [y/N]:
|
||||
```
|
||||
|
||||
### Disable Extension Temporarily
|
||||
|
||||
```bash
|
||||
# Disable without removing
|
||||
specify extension disable jira
|
||||
|
||||
✓ Extension 'jira' disabled
|
||||
|
||||
Commands will no longer be available. Hooks will not execute.
|
||||
To re-enable: specify extension enable jira
|
||||
```
|
||||
|
||||
### Re-enable Extension
|
||||
|
||||
```bash
|
||||
specify extension enable jira
|
||||
|
||||
✓ Extension 'jira' enabled
|
||||
```
|
||||
|
||||
### Remove Extension
|
||||
|
||||
```bash
|
||||
# Remove extension (with confirmation)
|
||||
specify extension remove jira
|
||||
|
||||
# Keep configuration when removing
|
||||
specify extension remove jira --keep-config
|
||||
|
||||
# Force removal (no confirmation)
|
||||
specify extension remove jira --force
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
### Configuration Files
|
||||
|
||||
Extensions can have multiple configuration files:
|
||||
|
||||
```text
|
||||
.specify/extensions/jira/
|
||||
├── jira-config.yml # Main config (version controlled)
|
||||
├── jira-config.local.yml # Local overrides (gitignored)
|
||||
└── jira-config.template.yml # Template (reference)
|
||||
```
|
||||
|
||||
### Configuration Layers
|
||||
|
||||
Configuration is merged in this order (highest priority last):
|
||||
|
||||
1. **Extension defaults** (from `extension.yml`)
|
||||
2. **Project config** (`jira-config.yml`)
|
||||
3. **Local overrides** (`jira-config.local.yml`)
|
||||
4. **Environment variables** (`SPECKIT_JIRA_*`)
|
||||
|
||||
### Example: Jira Configuration
|
||||
|
||||
**Project config** (`.specify/extensions/jira/jira-config.yml`):
|
||||
|
||||
```yaml
|
||||
project:
|
||||
key: "MSATS"
|
||||
|
||||
defaults:
|
||||
epic:
|
||||
labels: ["spec-driven"]
|
||||
```
|
||||
|
||||
**Local override** (`.specify/extensions/jira/jira-config.local.yml`):
|
||||
|
||||
```yaml
|
||||
project:
|
||||
key: "MYTEST" # Override for local development
|
||||
```
|
||||
|
||||
**Environment variable**:
|
||||
|
||||
```bash
|
||||
export SPECKIT_JIRA_PROJECT_KEY="DEVTEST"
|
||||
```
|
||||
|
||||
Final resolved config uses `DEVTEST` from environment variable.
|
||||
|
||||
### Project-Wide Extension Settings
|
||||
|
||||
File: `.specify/extensions.yml`
|
||||
|
||||
```yaml
|
||||
# Extensions installed in this project
|
||||
installed:
|
||||
- jira
|
||||
- linear
|
||||
|
||||
# Global settings
|
||||
settings:
|
||||
auto_execute_hooks: true
|
||||
|
||||
# Hook configuration
|
||||
hooks:
|
||||
after_tasks:
|
||||
- extension: jira
|
||||
command: speckit.jira.specstoissues
|
||||
enabled: true
|
||||
optional: true
|
||||
prompt: "Create Jira issues from tasks?"
|
||||
```
|
||||
|
||||
### Core Environment Variables
|
||||
|
||||
In addition to extension-specific environment variables (`SPECKIT_{EXT_ID}_*`), spec-kit supports core environment variables:
|
||||
|
||||
| Variable | Description | Default |
|
||||
|----------|-------------|---------|
|
||||
| `SPECKIT_CATALOG_URL` | Override the extension catalog URL | GitHub-hosted catalog |
|
||||
| `GH_TOKEN` / `GITHUB_TOKEN` | GitHub API token for downloads | None |
|
||||
|
||||
#### Example: Using a custom catalog for testing
|
||||
|
||||
```bash
|
||||
# Point to a local or alternative catalog
|
||||
export SPECKIT_CATALOG_URL="http://localhost:8000/catalog.json"
|
||||
|
||||
# Or use a staging catalog
|
||||
export SPECKIT_CATALOG_URL="https://example.com/staging/catalog.json"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Organization Catalog Customization
|
||||
|
||||
### Why the Default Catalog is Empty
|
||||
|
||||
The default spec-kit catalog ships empty by design. This allows organizations to:
|
||||
|
||||
- **Control available extensions** - Curate which extensions your team can install
|
||||
- **Host private extensions** - Internal tools that shouldn't be public
|
||||
- **Customize for compliance** - Meet security/audit requirements
|
||||
- **Support air-gapped environments** - Work without internet access
|
||||
|
||||
### Setting Up a Custom Catalog
|
||||
|
||||
#### 1. Create Your Catalog File
|
||||
|
||||
Create a `catalog.json` file with your extensions:
|
||||
|
||||
```json
|
||||
{
|
||||
"schema_version": "1.0",
|
||||
"updated_at": "2026-02-03T00:00:00Z",
|
||||
"catalog_url": "https://your-org.com/spec-kit/catalog.json",
|
||||
"extensions": {
|
||||
"jira": {
|
||||
"name": "Jira Integration",
|
||||
"id": "jira",
|
||||
"description": "Create Jira issues from spec-kit artifacts",
|
||||
"author": "Your Organization",
|
||||
"version": "2.1.0",
|
||||
"download_url": "https://github.com/your-org/spec-kit-jira/archive/refs/tags/v2.1.0.zip",
|
||||
"repository": "https://github.com/your-org/spec-kit-jira",
|
||||
"license": "MIT",
|
||||
"requires": {
|
||||
"speckit_version": ">=0.1.0",
|
||||
"tools": [
|
||||
{"name": "atlassian-mcp-server", "required": true}
|
||||
]
|
||||
},
|
||||
"provides": {
|
||||
"commands": 3,
|
||||
"hooks": 1
|
||||
},
|
||||
"tags": ["jira", "atlassian", "issue-tracking"],
|
||||
"verified": true
|
||||
},
|
||||
"internal-tool": {
|
||||
"name": "Internal Tool Integration",
|
||||
"id": "internal-tool",
|
||||
"description": "Connect to internal company systems",
|
||||
"author": "Your Organization",
|
||||
"version": "1.0.0",
|
||||
"download_url": "https://internal.your-org.com/extensions/internal-tool-1.0.0.zip",
|
||||
"repository": "https://github.internal.your-org.com/spec-kit-internal",
|
||||
"license": "Proprietary",
|
||||
"requires": {
|
||||
"speckit_version": ">=0.1.0"
|
||||
},
|
||||
"provides": {
|
||||
"commands": 2
|
||||
},
|
||||
"tags": ["internal", "proprietary"],
|
||||
"verified": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 2. Host the Catalog
|
||||
|
||||
Options for hosting your catalog:
|
||||
|
||||
| Method | URL Example | Use Case |
|
||||
| ------ | ----------- | -------- |
|
||||
| GitHub Pages | `https://your-org.github.io/spec-kit-catalog/catalog.json` | Public or org-visible |
|
||||
| Internal web server | `https://internal.company.com/spec-kit/catalog.json` | Corporate network |
|
||||
| S3/Cloud storage | `https://s3.amazonaws.com/your-bucket/catalog.json` | Cloud-hosted teams |
|
||||
| Local file server | `http://localhost:8000/catalog.json` | Development/testing |
|
||||
|
||||
**Security requirement**: URLs must use HTTPS (except `localhost` for testing).
|
||||
|
||||
#### 3. Configure Your Environment
|
||||
|
||||
##### Option A: Environment variable (recommended for CI/CD)
|
||||
|
||||
```bash
|
||||
# In ~/.bashrc, ~/.zshrc, or CI pipeline
|
||||
export SPECKIT_CATALOG_URL="https://your-org.com/spec-kit/catalog.json"
|
||||
```
|
||||
|
||||
##### Option B: Per-project configuration
|
||||
|
||||
Create `.env` or set in your shell before running spec-kit commands:
|
||||
|
||||
```bash
|
||||
SPECKIT_CATALOG_URL="https://your-org.com/spec-kit/catalog.json" specify extension search
|
||||
```
|
||||
|
||||
#### 4. Verify Configuration
|
||||
|
||||
```bash
|
||||
# Search should now show your catalog's extensions
|
||||
specify extension search
|
||||
|
||||
# Install from your catalog
|
||||
specify extension add jira
|
||||
```
|
||||
|
||||
### Catalog JSON Schema
|
||||
|
||||
Required fields for each extension entry:
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
| ----- | ---- | -------- | ----------- |
|
||||
| `name` | string | Yes | Human-readable name |
|
||||
| `id` | string | Yes | Unique identifier (lowercase, hyphens) |
|
||||
| `version` | string | Yes | Semantic version (X.Y.Z) |
|
||||
| `download_url` | string | Yes | URL to ZIP archive |
|
||||
| `repository` | string | Yes | Source code URL |
|
||||
| `description` | string | No | Brief description |
|
||||
| `author` | string | No | Author/organization |
|
||||
| `license` | string | No | SPDX license identifier |
|
||||
| `requires.speckit_version` | string | No | Version constraint |
|
||||
| `requires.tools` | array | No | Required external tools |
|
||||
| `provides.commands` | number | No | Number of commands |
|
||||
| `provides.hooks` | number | No | Number of hooks |
|
||||
| `tags` | array | No | Search tags |
|
||||
| `verified` | boolean | No | Verification status |
|
||||
|
||||
### Use Cases
|
||||
|
||||
#### Private/Internal Extensions
|
||||
|
||||
Host proprietary extensions that integrate with internal systems:
|
||||
|
||||
```json
|
||||
{
|
||||
"internal-auth": {
|
||||
"name": "Internal SSO Integration",
|
||||
"download_url": "https://artifactory.company.com/spec-kit/internal-auth-1.0.0.zip",
|
||||
"verified": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Curated Team Catalog
|
||||
|
||||
Limit which extensions your team can install:
|
||||
|
||||
```json
|
||||
{
|
||||
"extensions": {
|
||||
"jira": { "..." },
|
||||
"github": { "..." }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Only `jira` and `github` will appear in `specify extension search`.
|
||||
|
||||
#### Air-Gapped Environments
|
||||
|
||||
For networks without internet access:
|
||||
|
||||
1. Download extension ZIPs to internal file server
|
||||
2. Create catalog pointing to internal URLs
|
||||
3. Host catalog on internal web server
|
||||
|
||||
```json
|
||||
{
|
||||
"jira": {
|
||||
"download_url": "https://files.internal/spec-kit/jira-2.1.0.zip"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Development/Testing
|
||||
|
||||
Test new extensions before publishing:
|
||||
|
||||
```bash
|
||||
# Start local server
|
||||
python -m http.server 8000 --directory ./my-catalog/
|
||||
|
||||
# Point spec-kit to local catalog
|
||||
export SPECKIT_CATALOG_URL="http://localhost:8000/catalog.json"
|
||||
|
||||
# Test installation
|
||||
specify extension add my-new-extension
|
||||
```
|
||||
|
||||
### Combining with Direct Installation
|
||||
|
||||
You can still install extensions not in your catalog using `--from`:
|
||||
|
||||
```bash
|
||||
# From catalog
|
||||
specify extension add jira
|
||||
|
||||
# Direct URL (bypasses catalog)
|
||||
specify extension add --from https://github.com/someone/spec-kit-ext/archive/v1.0.0.zip
|
||||
|
||||
# Local development
|
||||
specify extension add --dev /path/to/extension
|
||||
```
|
||||
|
||||
**Note**: Direct URL installation shows a security warning since the extension isn't from your configured catalog.
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Extension Not Found
|
||||
|
||||
**Error**: `Extension 'jira' not found in catalog
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. Check spelling: `specify extension search jira`
|
||||
2. Refresh catalog: `specify extension search --help`
|
||||
3. Check internet connection
|
||||
4. Extension may not be published yet
|
||||
|
||||
### Configuration Not Found
|
||||
|
||||
**Error**: `Jira configuration not found`
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. Check if extension is installed: `specify extension list`
|
||||
2. Create config from template:
|
||||
|
||||
```bash
|
||||
cp .specify/extensions/jira/jira-config.template.yml \
|
||||
.specify/extensions/jira/jira-config.yml
|
||||
```
|
||||
|
||||
3. Reinstall extension: `specify extension remove jira && specify extension add jira`
|
||||
|
||||
### Command Not Available
|
||||
|
||||
**Issue**: Extension command not appearing in AI agent
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. Check extension is enabled: `specify extension list`
|
||||
2. Restart AI agent (Claude Code)
|
||||
3. Check command file exists:
|
||||
|
||||
```bash
|
||||
ls .claude/commands/speckit.jira.*.md
|
||||
```
|
||||
|
||||
4. Reinstall extension
|
||||
|
||||
### Incompatible Version
|
||||
|
||||
**Error**: `Extension requires spec-kit >=0.2.0, but you have 0.1.0`
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. Upgrade spec-kit:
|
||||
|
||||
```bash
|
||||
uv tool upgrade specify-cli
|
||||
```
|
||||
|
||||
2. Install older version of extension:
|
||||
|
||||
```bash
|
||||
specify extension add --from https://github.com/org/ext/archive/v1.0.0.zip
|
||||
```
|
||||
|
||||
### MCP Tool Not Available
|
||||
|
||||
**Error**: `Tool 'jira-mcp-server/epic_create' not found`
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. Check MCP server is installed
|
||||
2. Check AI agent MCP configuration
|
||||
3. Restart AI agent
|
||||
4. Check extension requirements: `specify extension info jira`
|
||||
|
||||
### Permission Denied
|
||||
|
||||
**Error**: `Permission denied` when accessing Jira
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. Check Jira credentials in MCP server config
|
||||
2. Verify project permissions in Jira
|
||||
3. Test MCP server connection independently
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Version Control
|
||||
|
||||
**Do commit**:
|
||||
|
||||
- `.specify/extensions.yml` (project extension config)
|
||||
- `.specify/extensions/*/jira-config.yml` (project config)
|
||||
|
||||
**Don't commit**:
|
||||
|
||||
- `.specify/extensions/.cache/` (catalog cache)
|
||||
- `.specify/extensions/.backup/` (config backups)
|
||||
- `.specify/extensions/*/*.local.yml` (local overrides)
|
||||
- `.specify/extensions/.registry` (installation state)
|
||||
|
||||
Add to `.gitignore`:
|
||||
|
||||
```gitignore
|
||||
.specify/extensions/.cache/
|
||||
.specify/extensions/.backup/
|
||||
.specify/extensions/*/*.local.yml
|
||||
.specify/extensions/.registry
|
||||
```
|
||||
|
||||
### 2. Team Workflows
|
||||
|
||||
**For teams**:
|
||||
|
||||
1. Agree on which extensions to use
|
||||
2. Commit extension configuration
|
||||
3. Document extension usage in README
|
||||
4. Keep extensions updated together
|
||||
|
||||
**Example README section**:
|
||||
|
||||
```markdown
|
||||
## Extensions
|
||||
|
||||
This project uses:
|
||||
- **jira** (v1.0.0) - Jira integration
|
||||
- Config: `.specify/extensions/jira/jira-config.yml`
|
||||
- Requires: jira-mcp-server
|
||||
|
||||
To install: `specify extension add jira`
|
||||
```
|
||||
|
||||
### 3. Local Development
|
||||
|
||||
Use local config for development:
|
||||
|
||||
```yaml
|
||||
# .specify/extensions/jira/jira-config.local.yml
|
||||
project:
|
||||
key: "DEVTEST" # Your test project
|
||||
|
||||
defaults:
|
||||
task:
|
||||
custom_fields:
|
||||
customfield_10002: 1 # Lower story points for testing
|
||||
```
|
||||
|
||||
### 4. Environment-Specific Config
|
||||
|
||||
Use environment variables for CI/CD:
|
||||
|
||||
```bash
|
||||
# .github/workflows/deploy.yml
|
||||
env:
|
||||
SPECKIT_JIRA_PROJECT_KEY: ${{ secrets.JIRA_PROJECT }}
|
||||
|
||||
- name: Create Jira Issues
|
||||
run: specify extension add jira && ...
|
||||
```
|
||||
|
||||
### 5. Extension Updates
|
||||
|
||||
**Check for updates regularly**:
|
||||
|
||||
```bash
|
||||
# Weekly or before major releases
|
||||
specify extension update
|
||||
```
|
||||
|
||||
**Pin versions for stability**:
|
||||
|
||||
```yaml
|
||||
# .specify/extensions.yml
|
||||
installed:
|
||||
- id: jira
|
||||
version: "1.0.0" # Pin to specific version
|
||||
```
|
||||
|
||||
### 6. Minimal Extensions
|
||||
|
||||
Only install extensions you actively use:
|
||||
|
||||
- Reduces complexity
|
||||
- Faster command loading
|
||||
- Less configuration
|
||||
|
||||
### 7. Documentation
|
||||
|
||||
Document extension usage in your project:
|
||||
|
||||
```markdown
|
||||
# PROJECT.md
|
||||
|
||||
## Working with Jira
|
||||
|
||||
After creating tasks, sync to Jira:
|
||||
1. Run `/speckit.tasks` to generate tasks
|
||||
2. Run `/speckit.jira.specstoissues` to create Jira issues
|
||||
3. Run `/speckit.jira.sync-status` to update status
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## FAQ
|
||||
|
||||
### Q: Can I use multiple extensions at once?
|
||||
|
||||
**A**: Yes! Extensions are designed to work together. Install as many as you need.
|
||||
|
||||
### Q: Do extensions slow down spec-kit?
|
||||
|
||||
**A**: No. Extensions are loaded on-demand and only when their commands are used.
|
||||
|
||||
### Q: Can I create private extensions?
|
||||
|
||||
**A**: Yes. Install with `--dev` or `--from` and keep private. Public catalog submission is optional.
|
||||
|
||||
### Q: How do I know if an extension is safe?
|
||||
|
||||
**A**: Look for the ✓ Verified badge. Verified extensions are reviewed by maintainers. Always review extension code before installing.
|
||||
|
||||
### Q: Can extensions modify spec-kit core?
|
||||
|
||||
**A**: No. Extensions can only add commands and hooks. They cannot modify core functionality.
|
||||
|
||||
### Q: What happens if two extensions have the same command name?
|
||||
|
||||
**A**: Extensions use namespaced commands (`speckit.{extension}.{command}`), so conflicts are very rare. The extension system will warn you if conflicts occur.
|
||||
|
||||
### Q: Can I contribute to existing extensions?
|
||||
|
||||
**A**: Yes! Most extensions are open source. Check the repository link in `specify extension info {extension}`.
|
||||
|
||||
### Q: How do I report extension bugs?
|
||||
|
||||
**A**: Go to the extension's repository (shown in `specify extension info`) and create an issue.
|
||||
|
||||
### Q: Can extensions work offline?
|
||||
|
||||
**A**: Once installed, extensions work offline. However, some extensions may require internet for their functionality (e.g., Jira requires Jira API access).
|
||||
|
||||
### Q: How do I backup my extension configuration?
|
||||
|
||||
**A**: Extension configs are in `.specify/extensions/{extension}/`. Back up this directory or commit configs to git.
|
||||
|
||||
---
|
||||
|
||||
## Support
|
||||
|
||||
- **Extension Issues**: Report to extension repository (see `specify extension info`)
|
||||
- **Spec Kit Issues**: <https://github.com/statsperform/spec-kit/issues>
|
||||
- **Extension Catalog**: <https://github.com/statsperform/spec-kit/tree/main/extensions>
|
||||
- **Documentation**: See EXTENSION-DEVELOPMENT-GUIDE.md and EXTENSION-PUBLISHING-GUIDE.md
|
||||
|
||||
---
|
||||
|
||||
*Last Updated: 2026-01-28*
|
||||
*Spec Kit Version: 0.1.0*
|
||||
1791
extensions/RFC-EXTENSION-SYSTEM.md
Normal file
1791
extensions/RFC-EXTENSION-SYSTEM.md
Normal file
File diff suppressed because it is too large
Load Diff
60
extensions/catalog.example.json
Normal file
60
extensions/catalog.example.json
Normal file
@@ -0,0 +1,60 @@
|
||||
{
|
||||
"schema_version": "1.0",
|
||||
"updated_at": "2026-02-03T00:00:00Z",
|
||||
"catalog_url": "https://your-org.example.com/speckit/catalog.json",
|
||||
"extensions": {
|
||||
"jira": {
|
||||
"name": "Jira Integration",
|
||||
"id": "jira",
|
||||
"description": "Create Jira Epics, Stories, and Issues from spec-kit artifacts",
|
||||
"author": "Your Organization",
|
||||
"version": "2.1.0",
|
||||
"download_url": "https://github.com/your-org/spec-kit-jira/archive/refs/tags/v2.1.0.zip",
|
||||
"repository": "https://github.com/your-org/spec-kit-jira",
|
||||
"homepage": "https://github.com/your-org/spec-kit-jira",
|
||||
"documentation": "https://github.com/your-org/spec-kit-jira/blob/main/README.md",
|
||||
"changelog": "https://github.com/your-org/spec-kit-jira/blob/main/CHANGELOG.md",
|
||||
"license": "MIT",
|
||||
"requires": {
|
||||
"speckit_version": ">=0.1.0",
|
||||
"tools": [
|
||||
{
|
||||
"name": "atlassian",
|
||||
"version": ">=1.0.0",
|
||||
"required": true
|
||||
}
|
||||
]
|
||||
},
|
||||
"provides": {
|
||||
"commands": 3,
|
||||
"hooks": 1
|
||||
},
|
||||
"tags": ["jira", "atlassian", "issue-tracking"],
|
||||
"verified": true,
|
||||
"downloads": 0,
|
||||
"stars": 0,
|
||||
"created_at": "2026-01-28T00:00:00Z",
|
||||
"updated_at": "2026-02-03T00:00:00Z"
|
||||
},
|
||||
"linear": {
|
||||
"name": "Linear Integration",
|
||||
"id": "linear",
|
||||
"description": "Sync specs and tasks with Linear issues",
|
||||
"author": "Your Organization",
|
||||
"version": "1.0.0",
|
||||
"download_url": "https://github.com/your-org/spec-kit-linear/archive/refs/tags/v1.0.0.zip",
|
||||
"repository": "https://github.com/your-org/spec-kit-linear",
|
||||
"license": "MIT",
|
||||
"requires": {
|
||||
"speckit_version": ">=0.1.0"
|
||||
},
|
||||
"provides": {
|
||||
"commands": 2
|
||||
},
|
||||
"tags": ["linear", "issue-tracking"],
|
||||
"verified": false,
|
||||
"created_at": "2026-01-30T00:00:00Z",
|
||||
"updated_at": "2026-01-30T00:00:00Z"
|
||||
}
|
||||
}
|
||||
}
|
||||
6
extensions/catalog.json
Normal file
6
extensions/catalog.json
Normal file
@@ -0,0 +1,6 @@
|
||||
{
|
||||
"schema_version": "1.0",
|
||||
"updated_at": "2026-02-03T00:00:00Z",
|
||||
"catalog_url": "https://raw.githubusercontent.com/github/spec-kit/main/extensions/catalog.json",
|
||||
"extensions": {}
|
||||
}
|
||||
39
extensions/template/.gitignore
vendored
Normal file
39
extensions/template/.gitignore
vendored
Normal file
@@ -0,0 +1,39 @@
|
||||
# Local configuration overrides
|
||||
*-config.local.yml
|
||||
|
||||
# Python
|
||||
__pycache__/
|
||||
*.py[cod]
|
||||
*$py.class
|
||||
*.so
|
||||
.Python
|
||||
env/
|
||||
venv/
|
||||
|
||||
# Testing
|
||||
.pytest_cache/
|
||||
.coverage
|
||||
htmlcov/
|
||||
|
||||
# IDEs
|
||||
.vscode/
|
||||
.idea/
|
||||
*.swp
|
||||
*.swo
|
||||
*~
|
||||
|
||||
# OS
|
||||
.DS_Store
|
||||
Thumbs.db
|
||||
|
||||
# Logs
|
||||
*.log
|
||||
|
||||
# Build artifacts
|
||||
dist/
|
||||
build/
|
||||
*.egg-info/
|
||||
|
||||
# Temporary files
|
||||
*.tmp
|
||||
.cache/
|
||||
39
extensions/template/CHANGELOG.md
Normal file
39
extensions/template/CHANGELOG.md
Normal file
@@ -0,0 +1,39 @@
|
||||
# Changelog
|
||||
|
||||
All notable changes to this extension will be documented in this file.
|
||||
|
||||
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
||||
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
||||
|
||||
## [Unreleased]
|
||||
|
||||
### Planned
|
||||
|
||||
- Feature ideas for future versions
|
||||
- Enhancements
|
||||
- Bug fixes
|
||||
|
||||
## [1.0.0] - YYYY-MM-DD
|
||||
|
||||
### Added
|
||||
|
||||
- Initial release of extension
|
||||
- Command: `/speckit.my-extension.example` - Example command functionality
|
||||
- Configuration system with template
|
||||
- Documentation and examples
|
||||
|
||||
### Features
|
||||
|
||||
- Feature 1 description
|
||||
- Feature 2 description
|
||||
- Feature 3 description
|
||||
|
||||
### Requirements
|
||||
|
||||
- Spec Kit: >=0.1.0
|
||||
- External dependencies (if any)
|
||||
|
||||
---
|
||||
|
||||
[Unreleased]: https://github.com/your-org/spec-kit-my-extension/compare/v1.0.0...HEAD
|
||||
[1.0.0]: https://github.com/your-org/spec-kit-my-extension/releases/tag/v1.0.0
|
||||
158
extensions/template/EXAMPLE-README.md
Normal file
158
extensions/template/EXAMPLE-README.md
Normal file
@@ -0,0 +1,158 @@
|
||||
# EXAMPLE: Extension README
|
||||
|
||||
This is an example of what your extension README should look like after customization.
|
||||
**Delete this file and replace README.md with content similar to this.**
|
||||
|
||||
---
|
||||
|
||||
# My Extension
|
||||
|
||||
<!-- CUSTOMIZE: Replace with your extension description -->
|
||||
|
||||
Brief description of what your extension does and why it's useful.
|
||||
|
||||
## Features
|
||||
|
||||
<!-- CUSTOMIZE: List key features -->
|
||||
|
||||
- Feature 1: Description
|
||||
- Feature 2: Description
|
||||
- Feature 3: Description
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
# Install from catalog
|
||||
specify extension add my-extension
|
||||
|
||||
# Or install from local development directory
|
||||
specify extension add --dev /path/to/my-extension
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
1. Create configuration file:
|
||||
|
||||
```bash
|
||||
cp .specify/extensions/my-extension/config-template.yml \
|
||||
.specify/extensions/my-extension/my-extension-config.yml
|
||||
```
|
||||
|
||||
2. Edit configuration:
|
||||
|
||||
```bash
|
||||
vim .specify/extensions/my-extension/my-extension-config.yml
|
||||
```
|
||||
|
||||
3. Set required values:
|
||||
<!-- CUSTOMIZE: List required configuration -->
|
||||
```yaml
|
||||
connection:
|
||||
url: "https://api.example.com"
|
||||
api_key: "your-api-key"
|
||||
|
||||
project:
|
||||
id: "your-project-id"
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
<!-- CUSTOMIZE: Add usage examples -->
|
||||
|
||||
### Command: example
|
||||
|
||||
Description of what this command does.
|
||||
|
||||
```bash
|
||||
# In Claude Code
|
||||
> /speckit.my-extension.example
|
||||
```
|
||||
|
||||
**Prerequisites**:
|
||||
|
||||
- Prerequisite 1
|
||||
- Prerequisite 2
|
||||
|
||||
**Output**:
|
||||
|
||||
- What this command produces
|
||||
- Where results are saved
|
||||
|
||||
## Configuration Reference
|
||||
|
||||
<!-- CUSTOMIZE: Document all configuration options -->
|
||||
|
||||
### Connection Settings
|
||||
|
||||
| Setting | Type | Required | Description |
|
||||
|---------|------|----------|-------------|
|
||||
| `connection.url` | string | Yes | API endpoint URL |
|
||||
| `connection.api_key` | string | Yes | API authentication key |
|
||||
|
||||
### Project Settings
|
||||
|
||||
| Setting | Type | Required | Description |
|
||||
|---------|------|----------|-------------|
|
||||
| `project.id` | string | Yes | Project identifier |
|
||||
| `project.workspace` | string | No | Workspace or organization |
|
||||
|
||||
## Environment Variables
|
||||
|
||||
Override configuration with environment variables:
|
||||
|
||||
```bash
|
||||
# Override connection settings
|
||||
export SPECKIT_MY_EXTENSION_CONNECTION_URL="https://custom-api.com"
|
||||
export SPECKIT_MY_EXTENSION_CONNECTION_API_KEY="custom-key"
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
<!-- CUSTOMIZE: Add real-world examples -->
|
||||
|
||||
### Example 1: Basic Workflow
|
||||
|
||||
```bash
|
||||
# Step 1: Create specification
|
||||
> /speckit.spec
|
||||
|
||||
# Step 2: Generate tasks
|
||||
> /speckit.tasks
|
||||
|
||||
# Step 3: Use extension
|
||||
> /speckit.my-extension.example
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
<!-- CUSTOMIZE: Add common issues -->
|
||||
|
||||
### Issue: Configuration not found
|
||||
|
||||
**Solution**: Create config from template (see Configuration section)
|
||||
|
||||
### Issue: Command not available
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. Check extension is installed: `specify extension list`
|
||||
2. Restart AI agent
|
||||
3. Reinstall extension
|
||||
|
||||
## License
|
||||
|
||||
MIT License - see LICENSE file
|
||||
|
||||
## Support
|
||||
|
||||
- **Issues**: <https://github.com/your-org/spec-kit-my-extension/issues>
|
||||
- **Spec Kit Docs**: <https://github.com/statsperform/spec-kit>
|
||||
|
||||
## Changelog
|
||||
|
||||
See [CHANGELOG.md](CHANGELOG.md) for version history.
|
||||
|
||||
---
|
||||
|
||||
*Extension Version: 1.0.0*
|
||||
*Spec Kit: >=0.1.0*
|
||||
21
extensions/template/LICENSE
Normal file
21
extensions/template/LICENSE
Normal file
@@ -0,0 +1,21 @@
|
||||
MIT License
|
||||
|
||||
Copyright (c) 2026 [Your Name or Organization]
|
||||
|
||||
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.
|
||||
79
extensions/template/README.md
Normal file
79
extensions/template/README.md
Normal file
@@ -0,0 +1,79 @@
|
||||
# Extension Template
|
||||
|
||||
Starter template for creating a Spec Kit extension.
|
||||
|
||||
## Quick Start
|
||||
|
||||
1. **Copy this template**:
|
||||
|
||||
```bash
|
||||
cp -r extensions/template my-extension
|
||||
cd my-extension
|
||||
```
|
||||
|
||||
2. **Customize `extension.yml`**:
|
||||
- Change extension ID, name, description
|
||||
- Update author and repository
|
||||
- Define your commands
|
||||
|
||||
3. **Create commands**:
|
||||
- Add command files in `commands/` directory
|
||||
- Use Markdown format with YAML frontmatter
|
||||
|
||||
4. **Create config template**:
|
||||
- Define configuration options
|
||||
- Document all settings
|
||||
|
||||
5. **Write documentation**:
|
||||
- Update README.md with usage instructions
|
||||
- Add examples
|
||||
|
||||
6. **Test locally**:
|
||||
|
||||
```bash
|
||||
cd /path/to/spec-kit-project
|
||||
specify extension add --dev /path/to/my-extension
|
||||
```
|
||||
|
||||
7. **Publish** (optional):
|
||||
- Create GitHub repository
|
||||
- Create release
|
||||
- Submit to catalog (see EXTENSION-PUBLISHING-GUIDE.md)
|
||||
|
||||
## Files in This Template
|
||||
|
||||
- `extension.yml` - Extension manifest (CUSTOMIZE THIS)
|
||||
- `config-template.yml` - Configuration template (CUSTOMIZE THIS)
|
||||
- `commands/example.md` - Example command (REPLACE THIS)
|
||||
- `README.md` - Extension documentation (REPLACE THIS)
|
||||
- `LICENSE` - MIT License (REVIEW THIS)
|
||||
- `CHANGELOG.md` - Version history (UPDATE THIS)
|
||||
- `.gitignore` - Git ignore rules
|
||||
|
||||
## Customization Checklist
|
||||
|
||||
- [ ] Update `extension.yml` with your extension details
|
||||
- [ ] Change extension ID to your extension name
|
||||
- [ ] Update author information
|
||||
- [ ] Define your commands
|
||||
- [ ] Create command files in `commands/`
|
||||
- [ ] Update config template
|
||||
- [ ] Write README with usage instructions
|
||||
- [ ] Add examples
|
||||
- [ ] Update LICENSE if needed
|
||||
- [ ] Test extension locally
|
||||
- [ ] Create git repository
|
||||
- [ ] Create first release
|
||||
|
||||
## Need Help?
|
||||
|
||||
- **Development Guide**: See EXTENSION-DEVELOPMENT-GUIDE.md
|
||||
- **API Reference**: See EXTENSION-API-REFERENCE.md
|
||||
- **Publishing Guide**: See EXTENSION-PUBLISHING-GUIDE.md
|
||||
- **User Guide**: See EXTENSION-USER-GUIDE.md
|
||||
|
||||
## Template Version
|
||||
|
||||
- Version: 1.0.0
|
||||
- Last Updated: 2026-01-28
|
||||
- Compatible with Spec Kit: >=0.1.0
|
||||
210
extensions/template/commands/example.md
Normal file
210
extensions/template/commands/example.md
Normal file
@@ -0,0 +1,210 @@
|
||||
---
|
||||
description: "Example command that demonstrates extension functionality"
|
||||
# CUSTOMIZE: List MCP tools this command uses
|
||||
tools:
|
||||
- 'example-mcp-server/example_tool'
|
||||
---
|
||||
|
||||
# Example Command
|
||||
|
||||
<!-- CUSTOMIZE: Replace this entire file with your command documentation -->
|
||||
|
||||
This is an example command that demonstrates how to create commands for Spec Kit extensions.
|
||||
|
||||
## Purpose
|
||||
|
||||
Describe what this command does and when to use it.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
List requirements before using this command:
|
||||
|
||||
1. Prerequisite 1 (e.g., "MCP server configured")
|
||||
2. Prerequisite 2 (e.g., "Configuration file exists")
|
||||
3. Prerequisite 3 (e.g., "Valid API credentials")
|
||||
|
||||
## User Input
|
||||
|
||||
$ARGUMENTS
|
||||
|
||||
## Steps
|
||||
|
||||
### Step 1: Load Configuration
|
||||
|
||||
<!-- CUSTOMIZE: Replace with your actual steps -->
|
||||
|
||||
Load extension configuration from the project:
|
||||
|
||||
``bash
|
||||
config_file=".specify/extensions/my-extension/my-extension-config.yml"
|
||||
|
||||
if [ ! -f "$config_file" ]; then
|
||||
echo "❌ Error: Configuration not found at $config_file"
|
||||
echo "Run 'specify extension add my-extension' to install and configure"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Read configuration values
|
||||
|
||||
setting_value=$(yq eval '.settings.key' "$config_file")
|
||||
|
||||
# Apply environment variable overrides
|
||||
|
||||
setting_value="${SPECKIT_MY_EXTENSION_KEY:-$setting_value}"
|
||||
|
||||
# Validate configuration
|
||||
|
||||
if [ -z "$setting_value" ]; then
|
||||
echo "❌ Error: Configuration value not set"
|
||||
echo "Edit $config_file and set 'settings.key'"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "📋 Configuration loaded: $setting_value"
|
||||
``
|
||||
|
||||
### Step 2: Perform Main Action
|
||||
|
||||
<!-- CUSTOMIZE: Replace with your command logic -->
|
||||
|
||||
Describe what this step does:
|
||||
|
||||
``markdown
|
||||
Use MCP tools to perform the main action:
|
||||
|
||||
- Tool: example-mcp-server example_tool
|
||||
- Parameters: { "key": "$setting_value" }
|
||||
|
||||
This calls the MCP server tool to execute the operation.
|
||||
``
|
||||
|
||||
### Step 3: Process Results
|
||||
|
||||
<!-- CUSTOMIZE: Add more steps as needed -->
|
||||
|
||||
Process the results and provide output:
|
||||
|
||||
`` bash
|
||||
echo ""
|
||||
echo "✅ Command completed successfully!"
|
||||
echo ""
|
||||
echo "Results:"
|
||||
echo " • Item 1: Value"
|
||||
echo " • Item 2: Value"
|
||||
echo ""
|
||||
``
|
||||
|
||||
### Step 4: Save Output (Optional)
|
||||
|
||||
Save results to a file if needed:
|
||||
|
||||
``bash
|
||||
output_file=".specify/my-extension-output.json"
|
||||
|
||||
cat > "$output_file" <<EOF
|
||||
{
|
||||
"timestamp": "$(date -u +"%Y-%m-%dT%H:%M:%SZ")",
|
||||
"setting": "$setting_value",
|
||||
"results": []
|
||||
}
|
||||
EOF
|
||||
|
||||
echo "💾 Output saved to $output_file"
|
||||
``
|
||||
|
||||
## Configuration Reference
|
||||
|
||||
<!-- CUSTOMIZE: Document configuration options -->
|
||||
|
||||
This command uses the following configuration from `my-extension-config.yml`:
|
||||
|
||||
- **settings.key**: Description of what this setting does
|
||||
- Type: string
|
||||
- Required: Yes
|
||||
- Example: `"example-value"`
|
||||
|
||||
- **settings.another_key**: Description of another setting
|
||||
- Type: boolean
|
||||
- Required: No
|
||||
- Default: `false`
|
||||
- Example: `true`
|
||||
|
||||
## Environment Variables
|
||||
|
||||
<!-- CUSTOMIZE: Document environment variable overrides -->
|
||||
|
||||
Configuration can be overridden with environment variables:
|
||||
|
||||
- `SPECKIT_MY_EXTENSION_KEY` - Overrides `settings.key`
|
||||
- `SPECKIT_MY_EXTENSION_ANOTHER_KEY` - Overrides `settings.another_key`
|
||||
|
||||
Example:
|
||||
``bash
|
||||
export SPECKIT_MY_EXTENSION_KEY="override-value"
|
||||
``
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
<!-- CUSTOMIZE: Add common issues and solutions -->
|
||||
|
||||
### "Configuration not found"
|
||||
|
||||
**Solution**: Install the extension and create configuration:
|
||||
``bash
|
||||
specify extension add my-extension
|
||||
cp .specify/extensions/my-extension/config-template.yml \
|
||||
.specify/extensions/my-extension/my-extension-config.yml
|
||||
``
|
||||
|
||||
### "MCP tool not available"
|
||||
|
||||
**Solution**: Ensure MCP server is configured in your AI agent settings.
|
||||
|
||||
### "Permission denied"
|
||||
|
||||
**Solution**: Check credentials and permissions in the external service.
|
||||
|
||||
## Notes
|
||||
|
||||
<!-- CUSTOMIZE: Add helpful notes and tips -->
|
||||
|
||||
- This command requires an active connection to the external service
|
||||
- Results are cached for performance
|
||||
- Re-run the command to refresh data
|
||||
|
||||
## Examples
|
||||
|
||||
<!-- CUSTOMIZE: Add usage examples -->
|
||||
|
||||
### Example 1: Basic Usage
|
||||
|
||||
``bash
|
||||
|
||||
# Run with default configuration
|
||||
>
|
||||
> /speckit.my-extension.example
|
||||
``
|
||||
|
||||
### Example 2: With Environment Override
|
||||
|
||||
``bash
|
||||
|
||||
# Override configuration with environment variable
|
||||
|
||||
export SPECKIT_MY_EXTENSION_KEY="custom-value"
|
||||
> /speckit.my-extension.example
|
||||
``
|
||||
|
||||
### Example 3: After Core Command
|
||||
|
||||
``bash
|
||||
|
||||
# Use as part of a workflow
|
||||
>
|
||||
> /speckit.tasks
|
||||
> /speckit.my-extension.example
|
||||
``
|
||||
|
||||
---
|
||||
|
||||
*For more information, see the extension README or run `specify extension info my-extension`*
|
||||
75
extensions/template/config-template.yml
Normal file
75
extensions/template/config-template.yml
Normal file
@@ -0,0 +1,75 @@
|
||||
# Extension Configuration Template
|
||||
# Copy this to my-extension-config.yml and customize for your project
|
||||
|
||||
# CUSTOMIZE: Add your configuration sections below
|
||||
|
||||
# Example: Connection settings
|
||||
connection:
|
||||
# URL to external service
|
||||
url: "" # REQUIRED: e.g., "https://api.example.com"
|
||||
|
||||
# API key or token
|
||||
api_key: "" # REQUIRED: Your API key
|
||||
|
||||
# Example: Project settings
|
||||
project:
|
||||
# Project identifier
|
||||
id: "" # REQUIRED: e.g., "my-project"
|
||||
|
||||
# Workspace or organization
|
||||
workspace: "" # OPTIONAL: e.g., "my-org"
|
||||
|
||||
# Example: Feature flags
|
||||
features:
|
||||
# Enable/disable main functionality
|
||||
enabled: true
|
||||
|
||||
# Automatic synchronization
|
||||
auto_sync: false
|
||||
|
||||
# Verbose logging
|
||||
verbose: false
|
||||
|
||||
# Example: Default values
|
||||
defaults:
|
||||
# Labels to apply
|
||||
labels: [] # e.g., ["automated", "spec-kit"]
|
||||
|
||||
# Priority level
|
||||
priority: "medium" # Options: "low", "medium", "high"
|
||||
|
||||
# Assignee
|
||||
assignee: "" # OPTIONAL: Default assignee
|
||||
|
||||
# Example: Field mappings
|
||||
# Map internal names to external field IDs
|
||||
field_mappings:
|
||||
# Example mappings
|
||||
# internal_field: "external_field_id"
|
||||
# status: "customfield_10001"
|
||||
|
||||
# Example: Advanced settings
|
||||
advanced:
|
||||
# Timeout in seconds
|
||||
timeout: 30
|
||||
|
||||
# Retry attempts
|
||||
retry_count: 3
|
||||
|
||||
# Cache duration in seconds
|
||||
cache_duration: 3600
|
||||
|
||||
# Environment Variable Overrides:
|
||||
# You can override any setting with environment variables using this pattern:
|
||||
# SPECKIT_MY_EXTENSION_{SECTION}_{KEY}
|
||||
#
|
||||
# Examples:
|
||||
# - SPECKIT_MY_EXTENSION_CONNECTION_API_KEY: Override connection.api_key
|
||||
# - SPECKIT_MY_EXTENSION_PROJECT_ID: Override project.id
|
||||
# - SPECKIT_MY_EXTENSION_FEATURES_ENABLED: Override features.enabled
|
||||
#
|
||||
# Note: Use uppercase and replace dots with underscores
|
||||
|
||||
# Local Overrides:
|
||||
# For local development, create my-extension-config.local.yml (gitignored)
|
||||
# to override settings without affecting the team configuration
|
||||
97
extensions/template/extension.yml
Normal file
97
extensions/template/extension.yml
Normal file
@@ -0,0 +1,97 @@
|
||||
schema_version: "1.0"
|
||||
|
||||
extension:
|
||||
# CUSTOMIZE: Change 'my-extension' to your extension ID (lowercase, hyphen-separated)
|
||||
id: "my-extension"
|
||||
|
||||
# CUSTOMIZE: Human-readable name for your extension
|
||||
name: "My Extension"
|
||||
|
||||
# CUSTOMIZE: Update version when releasing (semantic versioning: X.Y.Z)
|
||||
version: "1.0.0"
|
||||
|
||||
# CUSTOMIZE: Brief description (under 200 characters)
|
||||
description: "Brief description of what your extension does"
|
||||
|
||||
# CUSTOMIZE: Your name or organization name
|
||||
author: "Your Name"
|
||||
|
||||
# CUSTOMIZE: GitHub repository URL (create before publishing)
|
||||
repository: "https://github.com/your-org/spec-kit-my-extension"
|
||||
|
||||
# REVIEW: License (MIT is recommended for open source)
|
||||
license: "MIT"
|
||||
|
||||
# CUSTOMIZE: Extension homepage (can be same as repository)
|
||||
homepage: "https://github.com/your-org/spec-kit-my-extension"
|
||||
|
||||
# Requirements for this extension
|
||||
requires:
|
||||
# CUSTOMIZE: Minimum spec-kit version required
|
||||
# Use >=X.Y.Z for minimum version
|
||||
# Use >=X.Y.Z,<Y.0.0 for version range
|
||||
speckit_version: ">=0.1.0"
|
||||
|
||||
# CUSTOMIZE: Add MCP tools or other dependencies
|
||||
# Remove if no external tools required
|
||||
tools:
|
||||
- name: "example-mcp-server"
|
||||
version: ">=1.0.0"
|
||||
required: true
|
||||
|
||||
# Commands provided by this extension
|
||||
provides:
|
||||
commands:
|
||||
# CUSTOMIZE: Define your commands
|
||||
# Pattern: speckit.{extension-id}.{command-name}
|
||||
- name: "speckit.my-extension.example"
|
||||
file: "commands/example.md"
|
||||
description: "Example command that demonstrates functionality"
|
||||
# Optional: Add aliases for shorter command names
|
||||
aliases: ["speckit.example"]
|
||||
|
||||
# ADD MORE COMMANDS: Copy this block for each command
|
||||
# - name: "speckit.my-extension.another-command"
|
||||
# file: "commands/another-command.md"
|
||||
# description: "Another command"
|
||||
|
||||
# CUSTOMIZE: Define configuration files
|
||||
config:
|
||||
- name: "my-extension-config.yml"
|
||||
template: "config-template.yml"
|
||||
description: "Extension configuration"
|
||||
required: true # Set to false if config is optional
|
||||
|
||||
# CUSTOMIZE: Define hooks (optional)
|
||||
# Remove if no hooks needed
|
||||
hooks:
|
||||
# Hook that runs after /speckit.tasks
|
||||
after_tasks:
|
||||
command: "speckit.my-extension.example"
|
||||
optional: true # User will be prompted
|
||||
prompt: "Run example command?"
|
||||
description: "Demonstrates hook functionality"
|
||||
condition: null # Future: conditional execution
|
||||
|
||||
# ADD MORE HOOKS: Copy this block for other events
|
||||
# after_implement:
|
||||
# command: "speckit.my-extension.another"
|
||||
# optional: false # Auto-execute without prompting
|
||||
# description: "Runs automatically after implementation"
|
||||
|
||||
# CUSTOMIZE: Add relevant tags (2-5 recommended)
|
||||
# Used for discovery in catalog
|
||||
tags:
|
||||
- "example"
|
||||
- "template"
|
||||
# ADD MORE: "category", "tool-name", etc.
|
||||
|
||||
# CUSTOMIZE: Default configuration values (optional)
|
||||
# These are merged with user config
|
||||
defaults:
|
||||
# Example default values
|
||||
feature:
|
||||
enabled: true
|
||||
auto_sync: false
|
||||
|
||||
# ADD MORE: Any default settings for your extension
|
||||
@@ -1,6 +1,6 @@
|
||||
[project]
|
||||
name = "specify-cli"
|
||||
version = "0.0.22"
|
||||
version = "0.1.0"
|
||||
description = "Specify CLI, part of GitHub Spec Kit. A tool to bootstrap your projects for Spec-Driven Development (SDD)."
|
||||
requires-python = ">=3.11"
|
||||
dependencies = [
|
||||
@@ -10,6 +10,8 @@ dependencies = [
|
||||
"platformdirs",
|
||||
"readchar",
|
||||
"truststore>=0.10.4",
|
||||
"pyyaml>=6.0",
|
||||
"packaging>=23.0",
|
||||
]
|
||||
|
||||
[project.scripts]
|
||||
@@ -22,3 +24,30 @@ build-backend = "hatchling.build"
|
||||
[tool.hatch.build.targets.wheel]
|
||||
packages = ["src/specify_cli"]
|
||||
|
||||
[project.optional-dependencies]
|
||||
test = [
|
||||
"pytest>=7.0",
|
||||
"pytest-cov>=4.0",
|
||||
]
|
||||
|
||||
[tool.pytest.ini_options]
|
||||
testpaths = ["tests"]
|
||||
python_files = ["test_*.py"]
|
||||
python_classes = ["Test*"]
|
||||
python_functions = ["test_*"]
|
||||
addopts = [
|
||||
"-v",
|
||||
"--strict-markers",
|
||||
"--tb=short",
|
||||
]
|
||||
|
||||
[tool.coverage.run]
|
||||
source = ["src"]
|
||||
omit = ["*/tests/*", "*/__pycache__/*"]
|
||||
|
||||
[tool.coverage.report]
|
||||
precision = 2
|
||||
show_missing = true
|
||||
skip_covered = false
|
||||
|
||||
|
||||
|
||||
8
spec-kit.code-workspace
Normal file
8
spec-kit.code-workspace
Normal file
@@ -0,0 +1,8 @@
|
||||
{
|
||||
"folders": [
|
||||
{
|
||||
"path": "."
|
||||
}
|
||||
],
|
||||
"settings": {}
|
||||
}
|
||||
@@ -942,6 +942,41 @@ def ensure_executable_scripts(project_path: Path, tracker: StepTracker | None =
|
||||
for f in failures:
|
||||
console.print(f" - {f}")
|
||||
|
||||
def ensure_constitution_from_template(project_path: Path, tracker: StepTracker | None = None) -> None:
|
||||
"""Copy constitution template to memory if it doesn't exist (preserves existing constitution on reinitialization)."""
|
||||
memory_constitution = project_path / ".specify" / "memory" / "constitution.md"
|
||||
template_constitution = project_path / ".specify" / "templates" / "constitution-template.md"
|
||||
|
||||
# If constitution already exists in memory, preserve it
|
||||
if memory_constitution.exists():
|
||||
if tracker:
|
||||
tracker.add("constitution", "Constitution setup")
|
||||
tracker.skip("constitution", "existing file preserved")
|
||||
return
|
||||
|
||||
# If template doesn't exist, something went wrong with extraction
|
||||
if not template_constitution.exists():
|
||||
if tracker:
|
||||
tracker.add("constitution", "Constitution setup")
|
||||
tracker.error("constitution", "template not found")
|
||||
return
|
||||
|
||||
# Copy template to memory directory
|
||||
try:
|
||||
memory_constitution.parent.mkdir(parents=True, exist_ok=True)
|
||||
shutil.copy2(template_constitution, memory_constitution)
|
||||
if tracker:
|
||||
tracker.add("constitution", "Constitution setup")
|
||||
tracker.complete("constitution", "copied from template")
|
||||
else:
|
||||
console.print(f"[cyan]Initialized constitution from template[/cyan]")
|
||||
except Exception as e:
|
||||
if tracker:
|
||||
tracker.add("constitution", "Constitution setup")
|
||||
tracker.error("constitution", str(e))
|
||||
else:
|
||||
console.print(f"[yellow]Warning: Could not initialize constitution: {e}[/yellow]")
|
||||
|
||||
@app.command()
|
||||
def init(
|
||||
project_name: str = typer.Argument(None, help="Name for your new project directory (optional if using --here, or use '.' for current directory)"),
|
||||
@@ -1108,6 +1143,7 @@ def init(
|
||||
("zip-list", "Archive contents"),
|
||||
("extracted-summary", "Extraction summary"),
|
||||
("chmod", "Ensure scripts executable"),
|
||||
("constitution", "Constitution setup"),
|
||||
("cleanup", "Cleanup"),
|
||||
("git", "Initialize git repository"),
|
||||
("final", "Finalize")
|
||||
@@ -1128,6 +1164,8 @@ def init(
|
||||
|
||||
ensure_executable_scripts(project_path, tracker=tracker)
|
||||
|
||||
ensure_constitution_from_template(project_path, tracker=tracker)
|
||||
|
||||
if not no_git:
|
||||
tracker.start("git")
|
||||
if is_git_repo(project_path):
|
||||
@@ -1361,6 +1399,641 @@ def version():
|
||||
console.print(panel)
|
||||
console.print()
|
||||
|
||||
|
||||
# ===== Extension Commands =====
|
||||
|
||||
extension_app = typer.Typer(
|
||||
name="extension",
|
||||
help="Manage spec-kit extensions",
|
||||
add_completion=False,
|
||||
)
|
||||
app.add_typer(extension_app, name="extension")
|
||||
|
||||
|
||||
def get_speckit_version() -> str:
|
||||
"""Get current spec-kit version."""
|
||||
import importlib.metadata
|
||||
try:
|
||||
return importlib.metadata.version("specify-cli")
|
||||
except Exception:
|
||||
# Fallback: try reading from pyproject.toml
|
||||
try:
|
||||
import tomllib
|
||||
pyproject_path = Path(__file__).parent.parent.parent / "pyproject.toml"
|
||||
if pyproject_path.exists():
|
||||
with open(pyproject_path, "rb") as f:
|
||||
data = tomllib.load(f)
|
||||
return data.get("project", {}).get("version", "unknown")
|
||||
except Exception:
|
||||
# Intentionally ignore any errors while reading/parsing pyproject.toml.
|
||||
# If this lookup fails for any reason, we fall back to returning "unknown" below.
|
||||
pass
|
||||
return "unknown"
|
||||
|
||||
|
||||
@extension_app.command("list")
|
||||
def extension_list(
|
||||
available: bool = typer.Option(False, "--available", help="Show available extensions from catalog"),
|
||||
all_extensions: bool = typer.Option(False, "--all", help="Show both installed and available"),
|
||||
):
|
||||
"""List installed extensions."""
|
||||
from .extensions import ExtensionManager
|
||||
|
||||
project_root = Path.cwd()
|
||||
|
||||
# Check if we're in a spec-kit project
|
||||
specify_dir = project_root / ".specify"
|
||||
if not specify_dir.exists():
|
||||
console.print("[red]Error:[/red] Not a spec-kit project (no .specify/ directory)")
|
||||
console.print("Run this command from a spec-kit project root")
|
||||
raise typer.Exit(1)
|
||||
|
||||
manager = ExtensionManager(project_root)
|
||||
installed = manager.list_installed()
|
||||
|
||||
if not installed and not (available or all_extensions):
|
||||
console.print("[yellow]No extensions installed.[/yellow]")
|
||||
console.print("\nInstall an extension with:")
|
||||
console.print(" specify extension add <extension-name>")
|
||||
return
|
||||
|
||||
if installed:
|
||||
console.print("\n[bold cyan]Installed Extensions:[/bold cyan]\n")
|
||||
|
||||
for ext in installed:
|
||||
status_icon = "✓" if ext["enabled"] else "✗"
|
||||
status_color = "green" if ext["enabled"] else "red"
|
||||
|
||||
console.print(f" [{status_color}]{status_icon}[/{status_color}] [bold]{ext['name']}[/bold] (v{ext['version']})")
|
||||
console.print(f" {ext['description']}")
|
||||
console.print(f" Commands: {ext['command_count']} | Hooks: {ext['hook_count']} | Status: {'Enabled' if ext['enabled'] else 'Disabled'}")
|
||||
console.print()
|
||||
|
||||
if available or all_extensions:
|
||||
console.print("\nInstall an extension:")
|
||||
console.print(" [cyan]specify extension add <name>[/cyan]")
|
||||
|
||||
|
||||
@extension_app.command("add")
|
||||
def extension_add(
|
||||
extension: str = typer.Argument(help="Extension name or path"),
|
||||
dev: bool = typer.Option(False, "--dev", help="Install from local directory"),
|
||||
from_url: Optional[str] = typer.Option(None, "--from", help="Install from custom URL"),
|
||||
):
|
||||
"""Install an extension."""
|
||||
from .extensions import ExtensionManager, ExtensionCatalog, ExtensionError, ValidationError, CompatibilityError
|
||||
|
||||
project_root = Path.cwd()
|
||||
|
||||
# Check if we're in a spec-kit project
|
||||
specify_dir = project_root / ".specify"
|
||||
if not specify_dir.exists():
|
||||
console.print("[red]Error:[/red] Not a spec-kit project (no .specify/ directory)")
|
||||
console.print("Run this command from a spec-kit project root")
|
||||
raise typer.Exit(1)
|
||||
|
||||
manager = ExtensionManager(project_root)
|
||||
speckit_version = get_speckit_version()
|
||||
|
||||
try:
|
||||
with console.status(f"[cyan]Installing extension: {extension}[/cyan]"):
|
||||
if dev:
|
||||
# Install from local directory
|
||||
source_path = Path(extension).expanduser().resolve()
|
||||
if not source_path.exists():
|
||||
console.print(f"[red]Error:[/red] Directory not found: {source_path}")
|
||||
raise typer.Exit(1)
|
||||
|
||||
if not (source_path / "extension.yml").exists():
|
||||
console.print(f"[red]Error:[/red] No extension.yml found in {source_path}")
|
||||
raise typer.Exit(1)
|
||||
|
||||
manifest = manager.install_from_directory(source_path, speckit_version)
|
||||
|
||||
elif from_url:
|
||||
# Install from URL (ZIP file)
|
||||
import urllib.request
|
||||
import urllib.error
|
||||
from urllib.parse import urlparse
|
||||
|
||||
# Validate URL
|
||||
parsed = urlparse(from_url)
|
||||
is_localhost = parsed.hostname in ("localhost", "127.0.0.1", "::1")
|
||||
|
||||
if parsed.scheme != "https" and not (parsed.scheme == "http" and is_localhost):
|
||||
console.print("[red]Error:[/red] URL must use HTTPS for security.")
|
||||
console.print("HTTP is only allowed for localhost URLs.")
|
||||
raise typer.Exit(1)
|
||||
|
||||
# Warn about untrusted sources
|
||||
console.print("[yellow]Warning:[/yellow] Installing from external URL.")
|
||||
console.print("Only install extensions from sources you trust.\n")
|
||||
console.print(f"Downloading from {from_url}...")
|
||||
|
||||
# Download ZIP to temp location
|
||||
download_dir = project_root / ".specify" / "extensions" / ".cache" / "downloads"
|
||||
download_dir.mkdir(parents=True, exist_ok=True)
|
||||
zip_path = download_dir / f"{extension}-url-download.zip"
|
||||
|
||||
try:
|
||||
with urllib.request.urlopen(from_url, timeout=60) as response:
|
||||
zip_data = response.read()
|
||||
zip_path.write_bytes(zip_data)
|
||||
|
||||
# Install from downloaded ZIP
|
||||
manifest = manager.install_from_zip(zip_path, speckit_version)
|
||||
except urllib.error.URLError as e:
|
||||
console.print(f"[red]Error:[/red] Failed to download from {from_url}: {e}")
|
||||
raise typer.Exit(1)
|
||||
finally:
|
||||
# Clean up downloaded ZIP
|
||||
if zip_path.exists():
|
||||
zip_path.unlink()
|
||||
|
||||
else:
|
||||
# Install from catalog
|
||||
catalog = ExtensionCatalog(project_root)
|
||||
|
||||
# Check if extension exists in catalog
|
||||
ext_info = catalog.get_extension_info(extension)
|
||||
if not ext_info:
|
||||
console.print(f"[red]Error:[/red] Extension '{extension}' not found in catalog")
|
||||
console.print("\nSearch available extensions:")
|
||||
console.print(" specify extension search")
|
||||
raise typer.Exit(1)
|
||||
|
||||
# Download extension ZIP
|
||||
console.print(f"Downloading {ext_info['name']} v{ext_info.get('version', 'unknown')}...")
|
||||
zip_path = catalog.download_extension(extension)
|
||||
|
||||
try:
|
||||
# Install from downloaded ZIP
|
||||
manifest = manager.install_from_zip(zip_path, speckit_version)
|
||||
finally:
|
||||
# Clean up downloaded ZIP
|
||||
if zip_path.exists():
|
||||
zip_path.unlink()
|
||||
|
||||
console.print(f"\n[green]✓[/green] Extension installed successfully!")
|
||||
console.print(f"\n[bold]{manifest.name}[/bold] (v{manifest.version})")
|
||||
console.print(f" {manifest.description}")
|
||||
console.print(f"\n[bold cyan]Provided commands:[/bold cyan]")
|
||||
for cmd in manifest.commands:
|
||||
console.print(f" • {cmd['name']} - {cmd.get('description', '')}")
|
||||
|
||||
console.print(f"\n[yellow]⚠[/yellow] Configuration may be required")
|
||||
console.print(f" Check: .specify/extensions/{manifest.id}/")
|
||||
|
||||
except ValidationError as e:
|
||||
console.print(f"\n[red]Validation Error:[/red] {e}")
|
||||
raise typer.Exit(1)
|
||||
except CompatibilityError as e:
|
||||
console.print(f"\n[red]Compatibility Error:[/red] {e}")
|
||||
raise typer.Exit(1)
|
||||
except ExtensionError as e:
|
||||
console.print(f"\n[red]Error:[/red] {e}")
|
||||
raise typer.Exit(1)
|
||||
|
||||
|
||||
@extension_app.command("remove")
|
||||
def extension_remove(
|
||||
extension: str = typer.Argument(help="Extension ID to remove"),
|
||||
keep_config: bool = typer.Option(False, "--keep-config", help="Don't remove config files"),
|
||||
force: bool = typer.Option(False, "--force", help="Skip confirmation"),
|
||||
):
|
||||
"""Uninstall an extension."""
|
||||
from .extensions import ExtensionManager
|
||||
|
||||
project_root = Path.cwd()
|
||||
|
||||
# Check if we're in a spec-kit project
|
||||
specify_dir = project_root / ".specify"
|
||||
if not specify_dir.exists():
|
||||
console.print("[red]Error:[/red] Not a spec-kit project (no .specify/ directory)")
|
||||
console.print("Run this command from a spec-kit project root")
|
||||
raise typer.Exit(1)
|
||||
|
||||
manager = ExtensionManager(project_root)
|
||||
|
||||
# Check if extension is installed
|
||||
if not manager.registry.is_installed(extension):
|
||||
console.print(f"[red]Error:[/red] Extension '{extension}' is not installed")
|
||||
raise typer.Exit(1)
|
||||
|
||||
# Get extension info
|
||||
ext_manifest = manager.get_extension(extension)
|
||||
if ext_manifest:
|
||||
ext_name = ext_manifest.name
|
||||
cmd_count = len(ext_manifest.commands)
|
||||
else:
|
||||
ext_name = extension
|
||||
cmd_count = 0
|
||||
|
||||
# Confirm removal
|
||||
if not force:
|
||||
console.print(f"\n[yellow]⚠ This will remove:[/yellow]")
|
||||
console.print(f" • {cmd_count} commands from AI agent")
|
||||
console.print(f" • Extension directory: .specify/extensions/{extension}/")
|
||||
if not keep_config:
|
||||
console.print(f" • Config files (will be backed up)")
|
||||
console.print()
|
||||
|
||||
confirm = typer.confirm("Continue?")
|
||||
if not confirm:
|
||||
console.print("Cancelled")
|
||||
raise typer.Exit(0)
|
||||
|
||||
# Remove extension
|
||||
success = manager.remove(extension, keep_config=keep_config)
|
||||
|
||||
if success:
|
||||
console.print(f"\n[green]✓[/green] Extension '{ext_name}' removed successfully")
|
||||
if keep_config:
|
||||
console.print(f"\nConfig files preserved in .specify/extensions/{extension}/")
|
||||
else:
|
||||
console.print(f"\nConfig files backed up to .specify/extensions/.backup/{extension}/")
|
||||
console.print(f"\nTo reinstall: specify extension add {extension}")
|
||||
else:
|
||||
console.print(f"[red]Error:[/red] Failed to remove extension")
|
||||
raise typer.Exit(1)
|
||||
|
||||
|
||||
@extension_app.command("search")
|
||||
def extension_search(
|
||||
query: str = typer.Argument(None, help="Search query (optional)"),
|
||||
tag: Optional[str] = typer.Option(None, "--tag", help="Filter by tag"),
|
||||
author: Optional[str] = typer.Option(None, "--author", help="Filter by author"),
|
||||
verified: bool = typer.Option(False, "--verified", help="Show only verified extensions"),
|
||||
):
|
||||
"""Search for available extensions in catalog."""
|
||||
from .extensions import ExtensionCatalog, ExtensionError
|
||||
|
||||
project_root = Path.cwd()
|
||||
|
||||
# Check if we're in a spec-kit project
|
||||
specify_dir = project_root / ".specify"
|
||||
if not specify_dir.exists():
|
||||
console.print("[red]Error:[/red] Not a spec-kit project (no .specify/ directory)")
|
||||
console.print("Run this command from a spec-kit project root")
|
||||
raise typer.Exit(1)
|
||||
|
||||
catalog = ExtensionCatalog(project_root)
|
||||
|
||||
try:
|
||||
console.print("🔍 Searching extension catalog...")
|
||||
results = catalog.search(query=query, tag=tag, author=author, verified_only=verified)
|
||||
|
||||
if not results:
|
||||
console.print("\n[yellow]No extensions found matching criteria[/yellow]")
|
||||
if query or tag or author or verified:
|
||||
console.print("\nTry:")
|
||||
console.print(" • Broader search terms")
|
||||
console.print(" • Remove filters")
|
||||
console.print(" • specify extension search (show all)")
|
||||
raise typer.Exit(0)
|
||||
|
||||
console.print(f"\n[green]Found {len(results)} extension(s):[/green]\n")
|
||||
|
||||
for ext in results:
|
||||
# Extension header
|
||||
verified_badge = " [green]✓ Verified[/green]" if ext.get("verified") else ""
|
||||
console.print(f"[bold]{ext['name']}[/bold] (v{ext['version']}){verified_badge}")
|
||||
console.print(f" {ext['description']}")
|
||||
|
||||
# Metadata
|
||||
console.print(f"\n [dim]Author:[/dim] {ext.get('author', 'Unknown')}")
|
||||
if ext.get('tags'):
|
||||
tags_str = ", ".join(ext['tags'])
|
||||
console.print(f" [dim]Tags:[/dim] {tags_str}")
|
||||
|
||||
# Stats
|
||||
stats = []
|
||||
if ext.get('downloads') is not None:
|
||||
stats.append(f"Downloads: {ext['downloads']:,}")
|
||||
if ext.get('stars') is not None:
|
||||
stats.append(f"Stars: {ext['stars']}")
|
||||
if stats:
|
||||
console.print(f" [dim]{' | '.join(stats)}[/dim]")
|
||||
|
||||
# Links
|
||||
if ext.get('repository'):
|
||||
console.print(f" [dim]Repository:[/dim] {ext['repository']}")
|
||||
|
||||
# Install command
|
||||
console.print(f"\n [cyan]Install:[/cyan] specify extension add {ext['id']}")
|
||||
console.print()
|
||||
|
||||
except ExtensionError as e:
|
||||
console.print(f"\n[red]Error:[/red] {e}")
|
||||
console.print("\nTip: The catalog may be temporarily unavailable. Try again later.")
|
||||
raise typer.Exit(1)
|
||||
|
||||
|
||||
@extension_app.command("info")
|
||||
def extension_info(
|
||||
extension: str = typer.Argument(help="Extension ID or name"),
|
||||
):
|
||||
"""Show detailed information about an extension."""
|
||||
from .extensions import ExtensionCatalog, ExtensionManager, ExtensionError
|
||||
|
||||
project_root = Path.cwd()
|
||||
|
||||
# Check if we're in a spec-kit project
|
||||
specify_dir = project_root / ".specify"
|
||||
if not specify_dir.exists():
|
||||
console.print("[red]Error:[/red] Not a spec-kit project (no .specify/ directory)")
|
||||
console.print("Run this command from a spec-kit project root")
|
||||
raise typer.Exit(1)
|
||||
|
||||
catalog = ExtensionCatalog(project_root)
|
||||
manager = ExtensionManager(project_root)
|
||||
|
||||
try:
|
||||
ext_info = catalog.get_extension_info(extension)
|
||||
|
||||
if not ext_info:
|
||||
console.print(f"[red]Error:[/red] Extension '{extension}' not found in catalog")
|
||||
console.print("\nTry: specify extension search")
|
||||
raise typer.Exit(1)
|
||||
|
||||
# Header
|
||||
verified_badge = " [green]✓ Verified[/green]" if ext_info.get("verified") else ""
|
||||
console.print(f"\n[bold]{ext_info['name']}[/bold] (v{ext_info['version']}){verified_badge}")
|
||||
console.print(f"ID: {ext_info['id']}")
|
||||
console.print()
|
||||
|
||||
# Description
|
||||
console.print(f"{ext_info['description']}")
|
||||
console.print()
|
||||
|
||||
# Author and License
|
||||
console.print(f"[dim]Author:[/dim] {ext_info.get('author', 'Unknown')}")
|
||||
console.print(f"[dim]License:[/dim] {ext_info.get('license', 'Unknown')}")
|
||||
console.print()
|
||||
|
||||
# Requirements
|
||||
if ext_info.get('requires'):
|
||||
console.print("[bold]Requirements:[/bold]")
|
||||
reqs = ext_info['requires']
|
||||
if reqs.get('speckit_version'):
|
||||
console.print(f" • Spec Kit: {reqs['speckit_version']}")
|
||||
if reqs.get('tools'):
|
||||
for tool in reqs['tools']:
|
||||
tool_name = tool['name']
|
||||
tool_version = tool.get('version', 'any')
|
||||
required = " (required)" if tool.get('required') else " (optional)"
|
||||
console.print(f" • {tool_name}: {tool_version}{required}")
|
||||
console.print()
|
||||
|
||||
# Provides
|
||||
if ext_info.get('provides'):
|
||||
console.print("[bold]Provides:[/bold]")
|
||||
provides = ext_info['provides']
|
||||
if provides.get('commands'):
|
||||
console.print(f" • Commands: {provides['commands']}")
|
||||
if provides.get('hooks'):
|
||||
console.print(f" • Hooks: {provides['hooks']}")
|
||||
console.print()
|
||||
|
||||
# Tags
|
||||
if ext_info.get('tags'):
|
||||
tags_str = ", ".join(ext_info['tags'])
|
||||
console.print(f"[bold]Tags:[/bold] {tags_str}")
|
||||
console.print()
|
||||
|
||||
# Statistics
|
||||
stats = []
|
||||
if ext_info.get('downloads') is not None:
|
||||
stats.append(f"Downloads: {ext_info['downloads']:,}")
|
||||
if ext_info.get('stars') is not None:
|
||||
stats.append(f"Stars: {ext_info['stars']}")
|
||||
if stats:
|
||||
console.print(f"[bold]Statistics:[/bold] {' | '.join(stats)}")
|
||||
console.print()
|
||||
|
||||
# Links
|
||||
console.print("[bold]Links:[/bold]")
|
||||
if ext_info.get('repository'):
|
||||
console.print(f" • Repository: {ext_info['repository']}")
|
||||
if ext_info.get('homepage'):
|
||||
console.print(f" • Homepage: {ext_info['homepage']}")
|
||||
if ext_info.get('documentation'):
|
||||
console.print(f" • Documentation: {ext_info['documentation']}")
|
||||
if ext_info.get('changelog'):
|
||||
console.print(f" • Changelog: {ext_info['changelog']}")
|
||||
console.print()
|
||||
|
||||
# Installation status and command
|
||||
is_installed = manager.registry.is_installed(ext_info['id'])
|
||||
if is_installed:
|
||||
console.print("[green]✓ Installed[/green]")
|
||||
console.print(f"\nTo remove: specify extension remove {ext_info['id']}")
|
||||
else:
|
||||
console.print("[yellow]Not installed[/yellow]")
|
||||
console.print(f"\n[cyan]Install:[/cyan] specify extension add {ext_info['id']}")
|
||||
|
||||
except ExtensionError as e:
|
||||
console.print(f"\n[red]Error:[/red] {e}")
|
||||
raise typer.Exit(1)
|
||||
|
||||
|
||||
@extension_app.command("update")
|
||||
def extension_update(
|
||||
extension: str = typer.Argument(None, help="Extension ID to update (or all)"),
|
||||
):
|
||||
"""Update extension(s) to latest version."""
|
||||
from .extensions import ExtensionManager, ExtensionCatalog, ExtensionError
|
||||
from packaging import version as pkg_version
|
||||
|
||||
project_root = Path.cwd()
|
||||
|
||||
# Check if we're in a spec-kit project
|
||||
specify_dir = project_root / ".specify"
|
||||
if not specify_dir.exists():
|
||||
console.print("[red]Error:[/red] Not a spec-kit project (no .specify/ directory)")
|
||||
console.print("Run this command from a spec-kit project root")
|
||||
raise typer.Exit(1)
|
||||
|
||||
manager = ExtensionManager(project_root)
|
||||
catalog = ExtensionCatalog(project_root)
|
||||
|
||||
try:
|
||||
# Get list of extensions to update
|
||||
if extension:
|
||||
# Update specific extension
|
||||
if not manager.registry.is_installed(extension):
|
||||
console.print(f"[red]Error:[/red] Extension '{extension}' is not installed")
|
||||
raise typer.Exit(1)
|
||||
extensions_to_update = [extension]
|
||||
else:
|
||||
# Update all extensions
|
||||
installed = manager.list_installed()
|
||||
extensions_to_update = [ext["id"] for ext in installed]
|
||||
|
||||
if not extensions_to_update:
|
||||
console.print("[yellow]No extensions installed[/yellow]")
|
||||
raise typer.Exit(0)
|
||||
|
||||
console.print("🔄 Checking for updates...\n")
|
||||
|
||||
updates_available = []
|
||||
|
||||
for ext_id in extensions_to_update:
|
||||
# Get installed version
|
||||
metadata = manager.registry.get(ext_id)
|
||||
installed_version = pkg_version.Version(metadata["version"])
|
||||
|
||||
# Get catalog info
|
||||
ext_info = catalog.get_extension_info(ext_id)
|
||||
if not ext_info:
|
||||
console.print(f"⚠ {ext_id}: Not found in catalog (skipping)")
|
||||
continue
|
||||
|
||||
catalog_version = pkg_version.Version(ext_info["version"])
|
||||
|
||||
if catalog_version > installed_version:
|
||||
updates_available.append(
|
||||
{
|
||||
"id": ext_id,
|
||||
"installed": str(installed_version),
|
||||
"available": str(catalog_version),
|
||||
"download_url": ext_info.get("download_url"),
|
||||
}
|
||||
)
|
||||
else:
|
||||
console.print(f"✓ {ext_id}: Up to date (v{installed_version})")
|
||||
|
||||
if not updates_available:
|
||||
console.print("\n[green]All extensions are up to date![/green]")
|
||||
raise typer.Exit(0)
|
||||
|
||||
# Show available updates
|
||||
console.print("\n[bold]Updates available:[/bold]\n")
|
||||
for update in updates_available:
|
||||
console.print(
|
||||
f" • {update['id']}: {update['installed']} → {update['available']}"
|
||||
)
|
||||
|
||||
console.print()
|
||||
confirm = typer.confirm("Update these extensions?")
|
||||
if not confirm:
|
||||
console.print("Cancelled")
|
||||
raise typer.Exit(0)
|
||||
|
||||
# Perform updates
|
||||
console.print()
|
||||
for update in updates_available:
|
||||
ext_id = update["id"]
|
||||
console.print(f"📦 Updating {ext_id}...")
|
||||
|
||||
# TODO: Implement download and reinstall from URL
|
||||
# For now, just show message
|
||||
console.print(
|
||||
f"[yellow]Note:[/yellow] Automatic update not yet implemented. "
|
||||
f"Please update manually:"
|
||||
)
|
||||
console.print(f" specify extension remove {ext_id} --keep-config")
|
||||
console.print(f" specify extension add {ext_id}")
|
||||
|
||||
console.print(
|
||||
"\n[cyan]Tip:[/cyan] Automatic updates will be available in a future version"
|
||||
)
|
||||
|
||||
except ExtensionError as e:
|
||||
console.print(f"\n[red]Error:[/red] {e}")
|
||||
raise typer.Exit(1)
|
||||
|
||||
|
||||
@extension_app.command("enable")
|
||||
def extension_enable(
|
||||
extension: str = typer.Argument(help="Extension ID to enable"),
|
||||
):
|
||||
"""Enable a disabled extension."""
|
||||
from .extensions import ExtensionManager, HookExecutor
|
||||
|
||||
project_root = Path.cwd()
|
||||
|
||||
# Check if we're in a spec-kit project
|
||||
specify_dir = project_root / ".specify"
|
||||
if not specify_dir.exists():
|
||||
console.print("[red]Error:[/red] Not a spec-kit project (no .specify/ directory)")
|
||||
console.print("Run this command from a spec-kit project root")
|
||||
raise typer.Exit(1)
|
||||
|
||||
manager = ExtensionManager(project_root)
|
||||
hook_executor = HookExecutor(project_root)
|
||||
|
||||
if not manager.registry.is_installed(extension):
|
||||
console.print(f"[red]Error:[/red] Extension '{extension}' is not installed")
|
||||
raise typer.Exit(1)
|
||||
|
||||
# Update registry
|
||||
metadata = manager.registry.get(extension)
|
||||
if metadata.get("enabled", True):
|
||||
console.print(f"[yellow]Extension '{extension}' is already enabled[/yellow]")
|
||||
raise typer.Exit(0)
|
||||
|
||||
metadata["enabled"] = True
|
||||
manager.registry.add(extension, metadata)
|
||||
|
||||
# Enable hooks in extensions.yml
|
||||
config = hook_executor.get_project_config()
|
||||
if "hooks" in config:
|
||||
for hook_name in config["hooks"]:
|
||||
for hook in config["hooks"][hook_name]:
|
||||
if hook.get("extension") == extension:
|
||||
hook["enabled"] = True
|
||||
hook_executor.save_project_config(config)
|
||||
|
||||
console.print(f"[green]✓[/green] Extension '{extension}' enabled")
|
||||
|
||||
|
||||
@extension_app.command("disable")
|
||||
def extension_disable(
|
||||
extension: str = typer.Argument(help="Extension ID to disable"),
|
||||
):
|
||||
"""Disable an extension without removing it."""
|
||||
from .extensions import ExtensionManager, HookExecutor
|
||||
|
||||
project_root = Path.cwd()
|
||||
|
||||
# Check if we're in a spec-kit project
|
||||
specify_dir = project_root / ".specify"
|
||||
if not specify_dir.exists():
|
||||
console.print("[red]Error:[/red] Not a spec-kit project (no .specify/ directory)")
|
||||
console.print("Run this command from a spec-kit project root")
|
||||
raise typer.Exit(1)
|
||||
|
||||
manager = ExtensionManager(project_root)
|
||||
hook_executor = HookExecutor(project_root)
|
||||
|
||||
if not manager.registry.is_installed(extension):
|
||||
console.print(f"[red]Error:[/red] Extension '{extension}' is not installed")
|
||||
raise typer.Exit(1)
|
||||
|
||||
# Update registry
|
||||
metadata = manager.registry.get(extension)
|
||||
if not metadata.get("enabled", True):
|
||||
console.print(f"[yellow]Extension '{extension}' is already disabled[/yellow]")
|
||||
raise typer.Exit(0)
|
||||
|
||||
metadata["enabled"] = False
|
||||
manager.registry.add(extension, metadata)
|
||||
|
||||
# Disable hooks in extensions.yml
|
||||
config = hook_executor.get_project_config()
|
||||
if "hooks" in config:
|
||||
for hook_name in config["hooks"]:
|
||||
for hook in config["hooks"][hook_name]:
|
||||
if hook.get("extension") == extension:
|
||||
hook["enabled"] = False
|
||||
hook_executor.save_project_config(config)
|
||||
|
||||
console.print(f"[green]✓[/green] Extension '{extension}' disabled")
|
||||
console.print(f"\nCommands will no longer be available. Hooks will not execute.")
|
||||
console.print(f"To re-enable: specify extension enable {extension}")
|
||||
|
||||
|
||||
def main():
|
||||
app()
|
||||
|
||||
|
||||
1785
src/specify_cli/extensions.py
Normal file
1785
src/specify_cli/extensions.py
Normal file
File diff suppressed because it is too large
Load Diff
@@ -16,11 +16,13 @@ You **MUST** consider the user input before proceeding (if not empty).
|
||||
|
||||
## Outline
|
||||
|
||||
You are updating the project constitution at `/memory/constitution.md`. This file is a TEMPLATE containing placeholder tokens in square brackets (e.g. `[PROJECT_NAME]`, `[PRINCIPLE_1_NAME]`). Your job is to (a) collect/derive concrete values, (b) fill the template precisely, and (c) propagate any amendments across dependent artifacts.
|
||||
You are updating the project constitution at `.specify/memory/constitution.md`. This file is a TEMPLATE containing placeholder tokens in square brackets (e.g. `[PROJECT_NAME]`, `[PRINCIPLE_1_NAME]`). Your job is to (a) collect/derive concrete values, (b) fill the template precisely, and (c) propagate any amendments across dependent artifacts.
|
||||
|
||||
**Note**: If `.specify/memory/constitution.md` does not exist yet, it should have been initialized from `.specify/templates/constitution-template.md` during project setup. If it's missing, copy the template first.
|
||||
|
||||
Follow this execution flow:
|
||||
|
||||
1. Load the existing constitution template at `/memory/constitution.md`.
|
||||
1. Load the existing constitution at `.specify/memory/constitution.md`.
|
||||
- Identify every placeholder token of the form `[ALL_CAPS_IDENTIFIER]`.
|
||||
**IMPORTANT**: The user might require less or more principles than the ones used in the template. If a number is specified, respect that - follow the general template. You will update the doc accordingly.
|
||||
|
||||
@@ -41,10 +43,10 @@ Follow this execution flow:
|
||||
- Ensure Governance section lists amendment procedure, versioning policy, and compliance review expectations.
|
||||
|
||||
4. Consistency propagation checklist (convert prior checklist into active validations):
|
||||
- Read `/templates/plan-template.md` and ensure any "Constitution Check" or rules align with updated principles.
|
||||
- Read `/templates/spec-template.md` for scope/requirements alignment—update if constitution adds/removes mandatory sections or constraints.
|
||||
- Read `/templates/tasks-template.md` and ensure task categorization reflects new or removed principle-driven task types (e.g., observability, versioning, testing discipline).
|
||||
- Read each command file in `/templates/commands/*.md` (including this one) to verify no outdated references (agent-specific names like CLAUDE only) remain when generic guidance is required.
|
||||
- Read `.specify/templates/plan-template.md` and ensure any "Constitution Check" or rules align with updated principles.
|
||||
- Read `.specify/templates/spec-template.md` for scope/requirements alignment—update if constitution adds/removes mandatory sections or constraints.
|
||||
- Read `.specify/templates/tasks-template.md` and ensure task categorization reflects new or removed principle-driven task types (e.g., observability, versioning, testing discipline).
|
||||
- Read each command file in `.specify/templates/commands/*.md` (including this one) to verify no outdated references (agent-specific names like CLAUDE only) remain when generic guidance is required.
|
||||
- Read any runtime guidance docs (e.g., `README.md`, `docs/quickstart.md`, or agent-specific guidance files if present). Update references to principles changed.
|
||||
|
||||
5. Produce a Sync Impact Report (prepend as an HTML comment at top of the constitution file after update):
|
||||
@@ -61,7 +63,7 @@ Follow this execution flow:
|
||||
- Dates ISO format YYYY-MM-DD.
|
||||
- Principles are declarative, testable, and free of vague language ("should" → replace with MUST/SHOULD rationale where appropriate).
|
||||
|
||||
7. Write the completed constitution back to `/memory/constitution.md` (overwrite).
|
||||
7. Write the completed constitution back to `.specify/memory/constitution.md` (overwrite).
|
||||
|
||||
8. Output a final summary to the user with:
|
||||
- New version and bump rationale.
|
||||
@@ -79,4 +81,4 @@ If the user supplies partial updates (e.g., only one principle revision), still
|
||||
|
||||
If critical info missing (e.g., ratification date truly unknown), insert `TODO(<FIELD_NAME>): explanation` and include in the Sync Impact Report under deferred items.
|
||||
|
||||
Do not create a new template; always operate on the existing `/memory/constitution.md` file.
|
||||
Do not create a new template; always operate on the existing `.specify/memory/constitution.md` file.
|
||||
|
||||
1
tests/__init__.py
Normal file
1
tests/__init__.py
Normal file
@@ -0,0 +1 @@
|
||||
"""Unit tests for Spec Kit."""
|
||||
989
tests/test_extensions.py
Normal file
989
tests/test_extensions.py
Normal file
@@ -0,0 +1,989 @@
|
||||
"""
|
||||
Unit tests for the extension system.
|
||||
|
||||
Tests cover:
|
||||
- Extension manifest validation
|
||||
- Extension registry operations
|
||||
- Extension manager installation/removal
|
||||
- Command registration
|
||||
"""
|
||||
|
||||
import pytest
|
||||
import json
|
||||
import tempfile
|
||||
import shutil
|
||||
from pathlib import Path
|
||||
from datetime import datetime, timezone
|
||||
|
||||
from specify_cli.extensions import (
|
||||
ExtensionManifest,
|
||||
ExtensionRegistry,
|
||||
ExtensionManager,
|
||||
CommandRegistrar,
|
||||
ExtensionCatalog,
|
||||
ExtensionError,
|
||||
ValidationError,
|
||||
CompatibilityError,
|
||||
version_satisfies,
|
||||
)
|
||||
|
||||
|
||||
# ===== Fixtures =====
|
||||
|
||||
@pytest.fixture
|
||||
def temp_dir():
|
||||
"""Create a temporary directory for tests."""
|
||||
tmpdir = tempfile.mkdtemp()
|
||||
yield Path(tmpdir)
|
||||
shutil.rmtree(tmpdir)
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def valid_manifest_data():
|
||||
"""Valid extension manifest data."""
|
||||
return {
|
||||
"schema_version": "1.0",
|
||||
"extension": {
|
||||
"id": "test-ext",
|
||||
"name": "Test Extension",
|
||||
"version": "1.0.0",
|
||||
"description": "A test extension",
|
||||
"author": "Test Author",
|
||||
"repository": "https://github.com/test/test-ext",
|
||||
"license": "MIT",
|
||||
},
|
||||
"requires": {
|
||||
"speckit_version": ">=0.1.0",
|
||||
"commands": ["speckit.tasks"],
|
||||
},
|
||||
"provides": {
|
||||
"commands": [
|
||||
{
|
||||
"name": "speckit.test.hello",
|
||||
"file": "commands/hello.md",
|
||||
"description": "Test command",
|
||||
}
|
||||
]
|
||||
},
|
||||
"hooks": {
|
||||
"after_tasks": {
|
||||
"command": "speckit.test.hello",
|
||||
"optional": True,
|
||||
"prompt": "Run test?",
|
||||
}
|
||||
},
|
||||
"tags": ["testing", "example"],
|
||||
}
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def extension_dir(temp_dir, valid_manifest_data):
|
||||
"""Create a complete extension directory structure."""
|
||||
ext_dir = temp_dir / "test-ext"
|
||||
ext_dir.mkdir()
|
||||
|
||||
# Write manifest
|
||||
import yaml
|
||||
manifest_path = ext_dir / "extension.yml"
|
||||
with open(manifest_path, 'w') as f:
|
||||
yaml.dump(valid_manifest_data, f)
|
||||
|
||||
# Create commands directory
|
||||
commands_dir = ext_dir / "commands"
|
||||
commands_dir.mkdir()
|
||||
|
||||
# Write command file
|
||||
cmd_file = commands_dir / "hello.md"
|
||||
cmd_file.write_text("""---
|
||||
description: "Test hello command"
|
||||
---
|
||||
|
||||
# Test Hello Command
|
||||
|
||||
$ARGUMENTS
|
||||
""")
|
||||
|
||||
return ext_dir
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def project_dir(temp_dir):
|
||||
"""Create a mock spec-kit project directory."""
|
||||
proj_dir = temp_dir / "project"
|
||||
proj_dir.mkdir()
|
||||
|
||||
# Create .specify directory
|
||||
specify_dir = proj_dir / ".specify"
|
||||
specify_dir.mkdir()
|
||||
|
||||
return proj_dir
|
||||
|
||||
|
||||
# ===== ExtensionManifest Tests =====
|
||||
|
||||
class TestExtensionManifest:
|
||||
"""Test ExtensionManifest validation and parsing."""
|
||||
|
||||
def test_valid_manifest(self, extension_dir):
|
||||
"""Test loading a valid manifest."""
|
||||
manifest_path = extension_dir / "extension.yml"
|
||||
manifest = ExtensionManifest(manifest_path)
|
||||
|
||||
assert manifest.id == "test-ext"
|
||||
assert manifest.name == "Test Extension"
|
||||
assert manifest.version == "1.0.0"
|
||||
assert manifest.description == "A test extension"
|
||||
assert len(manifest.commands) == 1
|
||||
assert manifest.commands[0]["name"] == "speckit.test.hello"
|
||||
|
||||
def test_missing_required_field(self, temp_dir):
|
||||
"""Test manifest missing required field."""
|
||||
import yaml
|
||||
|
||||
manifest_path = temp_dir / "extension.yml"
|
||||
with open(manifest_path, 'w') as f:
|
||||
yaml.dump({"schema_version": "1.0"}, f) # Missing 'extension'
|
||||
|
||||
with pytest.raises(ValidationError, match="Missing required field"):
|
||||
ExtensionManifest(manifest_path)
|
||||
|
||||
def test_invalid_extension_id(self, temp_dir, valid_manifest_data):
|
||||
"""Test manifest with invalid extension ID format."""
|
||||
import yaml
|
||||
|
||||
valid_manifest_data["extension"]["id"] = "Invalid_ID" # Uppercase not allowed
|
||||
|
||||
manifest_path = temp_dir / "extension.yml"
|
||||
with open(manifest_path, 'w') as f:
|
||||
yaml.dump(valid_manifest_data, f)
|
||||
|
||||
with pytest.raises(ValidationError, match="Invalid extension ID"):
|
||||
ExtensionManifest(manifest_path)
|
||||
|
||||
def test_invalid_version(self, temp_dir, valid_manifest_data):
|
||||
"""Test manifest with invalid semantic version."""
|
||||
import yaml
|
||||
|
||||
valid_manifest_data["extension"]["version"] = "invalid"
|
||||
|
||||
manifest_path = temp_dir / "extension.yml"
|
||||
with open(manifest_path, 'w') as f:
|
||||
yaml.dump(valid_manifest_data, f)
|
||||
|
||||
with pytest.raises(ValidationError, match="Invalid version"):
|
||||
ExtensionManifest(manifest_path)
|
||||
|
||||
def test_invalid_command_name(self, temp_dir, valid_manifest_data):
|
||||
"""Test manifest with invalid command name format."""
|
||||
import yaml
|
||||
|
||||
valid_manifest_data["provides"]["commands"][0]["name"] = "invalid-name"
|
||||
|
||||
manifest_path = temp_dir / "extension.yml"
|
||||
with open(manifest_path, 'w') as f:
|
||||
yaml.dump(valid_manifest_data, f)
|
||||
|
||||
with pytest.raises(ValidationError, match="Invalid command name"):
|
||||
ExtensionManifest(manifest_path)
|
||||
|
||||
def test_no_commands(self, temp_dir, valid_manifest_data):
|
||||
"""Test manifest with no commands provided."""
|
||||
import yaml
|
||||
|
||||
valid_manifest_data["provides"]["commands"] = []
|
||||
|
||||
manifest_path = temp_dir / "extension.yml"
|
||||
with open(manifest_path, 'w') as f:
|
||||
yaml.dump(valid_manifest_data, f)
|
||||
|
||||
with pytest.raises(ValidationError, match="must provide at least one command"):
|
||||
ExtensionManifest(manifest_path)
|
||||
|
||||
def test_manifest_hash(self, extension_dir):
|
||||
"""Test manifest hash calculation."""
|
||||
manifest_path = extension_dir / "extension.yml"
|
||||
manifest = ExtensionManifest(manifest_path)
|
||||
|
||||
hash_value = manifest.get_hash()
|
||||
assert hash_value.startswith("sha256:")
|
||||
assert len(hash_value) > 10
|
||||
|
||||
|
||||
# ===== ExtensionRegistry Tests =====
|
||||
|
||||
class TestExtensionRegistry:
|
||||
"""Test ExtensionRegistry operations."""
|
||||
|
||||
def test_empty_registry(self, temp_dir):
|
||||
"""Test creating a new empty registry."""
|
||||
extensions_dir = temp_dir / "extensions"
|
||||
extensions_dir.mkdir()
|
||||
|
||||
registry = ExtensionRegistry(extensions_dir)
|
||||
|
||||
assert registry.data["schema_version"] == "1.0"
|
||||
assert registry.data["extensions"] == {}
|
||||
assert len(registry.list()) == 0
|
||||
|
||||
def test_add_extension(self, temp_dir):
|
||||
"""Test adding an extension to registry."""
|
||||
extensions_dir = temp_dir / "extensions"
|
||||
extensions_dir.mkdir()
|
||||
|
||||
registry = ExtensionRegistry(extensions_dir)
|
||||
|
||||
metadata = {
|
||||
"version": "1.0.0",
|
||||
"source": "local",
|
||||
"enabled": True,
|
||||
}
|
||||
registry.add("test-ext", metadata)
|
||||
|
||||
assert registry.is_installed("test-ext")
|
||||
ext_data = registry.get("test-ext")
|
||||
assert ext_data["version"] == "1.0.0"
|
||||
assert "installed_at" in ext_data
|
||||
|
||||
def test_remove_extension(self, temp_dir):
|
||||
"""Test removing an extension from registry."""
|
||||
extensions_dir = temp_dir / "extensions"
|
||||
extensions_dir.mkdir()
|
||||
|
||||
registry = ExtensionRegistry(extensions_dir)
|
||||
registry.add("test-ext", {"version": "1.0.0"})
|
||||
|
||||
assert registry.is_installed("test-ext")
|
||||
|
||||
registry.remove("test-ext")
|
||||
|
||||
assert not registry.is_installed("test-ext")
|
||||
assert registry.get("test-ext") is None
|
||||
|
||||
def test_registry_persistence(self, temp_dir):
|
||||
"""Test that registry persists to disk."""
|
||||
extensions_dir = temp_dir / "extensions"
|
||||
extensions_dir.mkdir()
|
||||
|
||||
# Create registry and add extension
|
||||
registry1 = ExtensionRegistry(extensions_dir)
|
||||
registry1.add("test-ext", {"version": "1.0.0"})
|
||||
|
||||
# Load new registry instance
|
||||
registry2 = ExtensionRegistry(extensions_dir)
|
||||
|
||||
# Should still have the extension
|
||||
assert registry2.is_installed("test-ext")
|
||||
assert registry2.get("test-ext")["version"] == "1.0.0"
|
||||
|
||||
|
||||
# ===== ExtensionManager Tests =====
|
||||
|
||||
class TestExtensionManager:
|
||||
"""Test ExtensionManager installation and removal."""
|
||||
|
||||
def test_check_compatibility_valid(self, extension_dir, project_dir):
|
||||
"""Test compatibility check with valid version."""
|
||||
manager = ExtensionManager(project_dir)
|
||||
manifest = ExtensionManifest(extension_dir / "extension.yml")
|
||||
|
||||
# Should not raise
|
||||
result = manager.check_compatibility(manifest, "0.1.0")
|
||||
assert result is True
|
||||
|
||||
def test_check_compatibility_invalid(self, extension_dir, project_dir):
|
||||
"""Test compatibility check with invalid version."""
|
||||
manager = ExtensionManager(project_dir)
|
||||
manifest = ExtensionManifest(extension_dir / "extension.yml")
|
||||
|
||||
# Requires >=0.1.0, but we have 0.0.1
|
||||
with pytest.raises(CompatibilityError, match="Extension requires spec-kit"):
|
||||
manager.check_compatibility(manifest, "0.0.1")
|
||||
|
||||
def test_install_from_directory(self, extension_dir, project_dir):
|
||||
"""Test installing extension from directory."""
|
||||
manager = ExtensionManager(project_dir)
|
||||
|
||||
manifest = manager.install_from_directory(
|
||||
extension_dir,
|
||||
"0.1.0",
|
||||
register_commands=False # Skip command registration for now
|
||||
)
|
||||
|
||||
assert manifest.id == "test-ext"
|
||||
assert manager.registry.is_installed("test-ext")
|
||||
|
||||
# Check extension directory was copied
|
||||
ext_dir = project_dir / ".specify" / "extensions" / "test-ext"
|
||||
assert ext_dir.exists()
|
||||
assert (ext_dir / "extension.yml").exists()
|
||||
assert (ext_dir / "commands" / "hello.md").exists()
|
||||
|
||||
def test_install_duplicate(self, extension_dir, project_dir):
|
||||
"""Test installing already installed extension."""
|
||||
manager = ExtensionManager(project_dir)
|
||||
|
||||
# Install once
|
||||
manager.install_from_directory(extension_dir, "0.1.0", register_commands=False)
|
||||
|
||||
# Try to install again
|
||||
with pytest.raises(ExtensionError, match="already installed"):
|
||||
manager.install_from_directory(extension_dir, "0.1.0", register_commands=False)
|
||||
|
||||
def test_remove_extension(self, extension_dir, project_dir):
|
||||
"""Test removing an installed extension."""
|
||||
manager = ExtensionManager(project_dir)
|
||||
|
||||
# Install extension
|
||||
manager.install_from_directory(extension_dir, "0.1.0", register_commands=False)
|
||||
|
||||
ext_dir = project_dir / ".specify" / "extensions" / "test-ext"
|
||||
assert ext_dir.exists()
|
||||
|
||||
# Remove extension
|
||||
result = manager.remove("test-ext", keep_config=False)
|
||||
|
||||
assert result is True
|
||||
assert not manager.registry.is_installed("test-ext")
|
||||
assert not ext_dir.exists()
|
||||
|
||||
def test_remove_nonexistent(self, project_dir):
|
||||
"""Test removing non-existent extension."""
|
||||
manager = ExtensionManager(project_dir)
|
||||
|
||||
result = manager.remove("nonexistent")
|
||||
assert result is False
|
||||
|
||||
def test_list_installed(self, extension_dir, project_dir):
|
||||
"""Test listing installed extensions."""
|
||||
manager = ExtensionManager(project_dir)
|
||||
|
||||
# Initially empty
|
||||
assert len(manager.list_installed()) == 0
|
||||
|
||||
# Install extension
|
||||
manager.install_from_directory(extension_dir, "0.1.0", register_commands=False)
|
||||
|
||||
# Should have one extension
|
||||
installed = manager.list_installed()
|
||||
assert len(installed) == 1
|
||||
assert installed[0]["id"] == "test-ext"
|
||||
assert installed[0]["name"] == "Test Extension"
|
||||
assert installed[0]["version"] == "1.0.0"
|
||||
assert installed[0]["command_count"] == 1
|
||||
assert installed[0]["hook_count"] == 1
|
||||
|
||||
def test_config_backup_on_remove(self, extension_dir, project_dir):
|
||||
"""Test that config files are backed up on removal."""
|
||||
manager = ExtensionManager(project_dir)
|
||||
|
||||
# Install extension
|
||||
manager.install_from_directory(extension_dir, "0.1.0", register_commands=False)
|
||||
|
||||
# Create a config file
|
||||
ext_dir = project_dir / ".specify" / "extensions" / "test-ext"
|
||||
config_file = ext_dir / "test-ext-config.yml"
|
||||
config_file.write_text("test: config")
|
||||
|
||||
# Remove extension (without keep_config)
|
||||
manager.remove("test-ext", keep_config=False)
|
||||
|
||||
# Check backup was created (now in subdirectory per extension)
|
||||
backup_dir = project_dir / ".specify" / "extensions" / ".backup" / "test-ext"
|
||||
backup_file = backup_dir / "test-ext-config.yml"
|
||||
assert backup_file.exists()
|
||||
assert backup_file.read_text() == "test: config"
|
||||
|
||||
|
||||
# ===== CommandRegistrar Tests =====
|
||||
|
||||
class TestCommandRegistrar:
|
||||
"""Test CommandRegistrar command registration."""
|
||||
|
||||
def test_parse_frontmatter_valid(self):
|
||||
"""Test parsing valid YAML frontmatter."""
|
||||
content = """---
|
||||
description: "Test command"
|
||||
tools:
|
||||
- tool1
|
||||
- tool2
|
||||
---
|
||||
|
||||
# Command body
|
||||
$ARGUMENTS
|
||||
"""
|
||||
registrar = CommandRegistrar()
|
||||
frontmatter, body = registrar.parse_frontmatter(content)
|
||||
|
||||
assert frontmatter["description"] == "Test command"
|
||||
assert frontmatter["tools"] == ["tool1", "tool2"]
|
||||
assert "Command body" in body
|
||||
assert "$ARGUMENTS" in body
|
||||
|
||||
def test_parse_frontmatter_no_frontmatter(self):
|
||||
"""Test parsing content without frontmatter."""
|
||||
content = "# Just a command\n$ARGUMENTS"
|
||||
|
||||
registrar = CommandRegistrar()
|
||||
frontmatter, body = registrar.parse_frontmatter(content)
|
||||
|
||||
assert frontmatter == {}
|
||||
assert body == content
|
||||
|
||||
def test_render_frontmatter(self):
|
||||
"""Test rendering frontmatter to YAML."""
|
||||
frontmatter = {
|
||||
"description": "Test command",
|
||||
"tools": ["tool1", "tool2"]
|
||||
}
|
||||
|
||||
registrar = CommandRegistrar()
|
||||
output = registrar.render_frontmatter(frontmatter)
|
||||
|
||||
assert output.startswith("---\n")
|
||||
assert output.endswith("---\n")
|
||||
assert "description: Test command" in output
|
||||
|
||||
def test_register_commands_for_claude(self, extension_dir, project_dir):
|
||||
"""Test registering commands for Claude agent."""
|
||||
# Create .claude directory
|
||||
claude_dir = project_dir / ".claude" / "commands"
|
||||
claude_dir.mkdir(parents=True)
|
||||
|
||||
ExtensionManager(project_dir) # Initialize manager (side effects only)
|
||||
manifest = ExtensionManifest(extension_dir / "extension.yml")
|
||||
|
||||
registrar = CommandRegistrar()
|
||||
registered = registrar.register_commands_for_claude(
|
||||
manifest,
|
||||
extension_dir,
|
||||
project_dir
|
||||
)
|
||||
|
||||
assert len(registered) == 1
|
||||
assert "speckit.test.hello" in registered
|
||||
|
||||
# Check command file was created
|
||||
cmd_file = claude_dir / "speckit.test.hello.md"
|
||||
assert cmd_file.exists()
|
||||
|
||||
content = cmd_file.read_text()
|
||||
assert "description: Test hello command" in content
|
||||
assert "<!-- Extension: test-ext -->" in content
|
||||
assert "<!-- Config: .specify/extensions/test-ext/ -->" in content
|
||||
|
||||
def test_command_with_aliases(self, project_dir, temp_dir):
|
||||
"""Test registering a command with aliases."""
|
||||
import yaml
|
||||
|
||||
# Create extension with command alias
|
||||
ext_dir = temp_dir / "ext-alias"
|
||||
ext_dir.mkdir()
|
||||
|
||||
manifest_data = {
|
||||
"schema_version": "1.0",
|
||||
"extension": {
|
||||
"id": "ext-alias",
|
||||
"name": "Extension with Alias",
|
||||
"version": "1.0.0",
|
||||
"description": "Test",
|
||||
},
|
||||
"requires": {
|
||||
"speckit_version": ">=0.1.0",
|
||||
},
|
||||
"provides": {
|
||||
"commands": [
|
||||
{
|
||||
"name": "speckit.alias.cmd",
|
||||
"file": "commands/cmd.md",
|
||||
"aliases": ["speckit.shortcut"],
|
||||
}
|
||||
]
|
||||
},
|
||||
}
|
||||
|
||||
with open(ext_dir / "extension.yml", 'w') as f:
|
||||
yaml.dump(manifest_data, f)
|
||||
|
||||
(ext_dir / "commands").mkdir()
|
||||
(ext_dir / "commands" / "cmd.md").write_text("---\ndescription: Test\n---\n\nTest")
|
||||
|
||||
claude_dir = project_dir / ".claude" / "commands"
|
||||
claude_dir.mkdir(parents=True)
|
||||
|
||||
manifest = ExtensionManifest(ext_dir / "extension.yml")
|
||||
registrar = CommandRegistrar()
|
||||
registered = registrar.register_commands_for_claude(manifest, ext_dir, project_dir)
|
||||
|
||||
assert len(registered) == 2
|
||||
assert "speckit.alias.cmd" in registered
|
||||
assert "speckit.shortcut" in registered
|
||||
assert (claude_dir / "speckit.alias.cmd.md").exists()
|
||||
assert (claude_dir / "speckit.shortcut.md").exists()
|
||||
|
||||
|
||||
# ===== Utility Function Tests =====
|
||||
|
||||
class TestVersionSatisfies:
|
||||
"""Test version_satisfies utility function."""
|
||||
|
||||
def test_version_satisfies_simple(self):
|
||||
"""Test simple version comparison."""
|
||||
assert version_satisfies("1.0.0", ">=1.0.0")
|
||||
assert version_satisfies("1.0.1", ">=1.0.0")
|
||||
assert not version_satisfies("0.9.9", ">=1.0.0")
|
||||
|
||||
def test_version_satisfies_range(self):
|
||||
"""Test version range."""
|
||||
assert version_satisfies("1.5.0", ">=1.0.0,<2.0.0")
|
||||
assert not version_satisfies("2.0.0", ">=1.0.0,<2.0.0")
|
||||
assert not version_satisfies("0.9.0", ">=1.0.0,<2.0.0")
|
||||
|
||||
def test_version_satisfies_complex(self):
|
||||
"""Test complex version specifier."""
|
||||
assert version_satisfies("1.0.5", ">=1.0.0,!=1.0.3")
|
||||
assert not version_satisfies("1.0.3", ">=1.0.0,!=1.0.3")
|
||||
|
||||
def test_version_satisfies_invalid(self):
|
||||
"""Test invalid version strings."""
|
||||
assert not version_satisfies("invalid", ">=1.0.0")
|
||||
assert not version_satisfies("1.0.0", "invalid specifier")
|
||||
|
||||
|
||||
# ===== Integration Tests =====
|
||||
|
||||
class TestIntegration:
|
||||
"""Integration tests for complete workflows."""
|
||||
|
||||
def test_full_install_and_remove_workflow(self, extension_dir, project_dir):
|
||||
"""Test complete installation and removal workflow."""
|
||||
# Create Claude directory
|
||||
(project_dir / ".claude" / "commands").mkdir(parents=True)
|
||||
|
||||
manager = ExtensionManager(project_dir)
|
||||
|
||||
# Install
|
||||
manager.install_from_directory(
|
||||
extension_dir,
|
||||
"0.1.0",
|
||||
register_commands=True
|
||||
)
|
||||
|
||||
# Verify installation
|
||||
assert manager.registry.is_installed("test-ext")
|
||||
installed = manager.list_installed()
|
||||
assert len(installed) == 1
|
||||
assert installed[0]["id"] == "test-ext"
|
||||
|
||||
# Verify command registered
|
||||
cmd_file = project_dir / ".claude" / "commands" / "speckit.test.hello.md"
|
||||
assert cmd_file.exists()
|
||||
|
||||
# Verify registry has registered commands (now a dict keyed by agent)
|
||||
metadata = manager.registry.get("test-ext")
|
||||
registered_commands = metadata["registered_commands"]
|
||||
# Check that the command is registered for at least one agent
|
||||
assert any(
|
||||
"speckit.test.hello" in cmds
|
||||
for cmds in registered_commands.values()
|
||||
)
|
||||
|
||||
# Remove
|
||||
result = manager.remove("test-ext")
|
||||
assert result is True
|
||||
|
||||
# Verify removal
|
||||
assert not manager.registry.is_installed("test-ext")
|
||||
assert not cmd_file.exists()
|
||||
assert len(manager.list_installed()) == 0
|
||||
|
||||
def test_multiple_extensions(self, temp_dir, project_dir):
|
||||
"""Test installing multiple extensions."""
|
||||
import yaml
|
||||
|
||||
# Create two extensions
|
||||
for i in range(1, 3):
|
||||
ext_dir = temp_dir / f"ext{i}"
|
||||
ext_dir.mkdir()
|
||||
|
||||
manifest_data = {
|
||||
"schema_version": "1.0",
|
||||
"extension": {
|
||||
"id": f"ext{i}",
|
||||
"name": f"Extension {i}",
|
||||
"version": "1.0.0",
|
||||
"description": f"Extension {i}",
|
||||
},
|
||||
"requires": {"speckit_version": ">=0.1.0"},
|
||||
"provides": {
|
||||
"commands": [
|
||||
{
|
||||
"name": f"speckit.ext{i}.cmd",
|
||||
"file": "commands/cmd.md",
|
||||
}
|
||||
]
|
||||
},
|
||||
}
|
||||
|
||||
with open(ext_dir / "extension.yml", 'w') as f:
|
||||
yaml.dump(manifest_data, f)
|
||||
|
||||
(ext_dir / "commands").mkdir()
|
||||
(ext_dir / "commands" / "cmd.md").write_text("---\ndescription: Test\n---\nTest")
|
||||
|
||||
manager = ExtensionManager(project_dir)
|
||||
|
||||
# Install both
|
||||
manager.install_from_directory(temp_dir / "ext1", "0.1.0", register_commands=False)
|
||||
manager.install_from_directory(temp_dir / "ext2", "0.1.0", register_commands=False)
|
||||
|
||||
# Verify both installed
|
||||
installed = manager.list_installed()
|
||||
assert len(installed) == 2
|
||||
assert {ext["id"] for ext in installed} == {"ext1", "ext2"}
|
||||
|
||||
# Remove first
|
||||
manager.remove("ext1")
|
||||
|
||||
# Verify only second remains
|
||||
installed = manager.list_installed()
|
||||
assert len(installed) == 1
|
||||
assert installed[0]["id"] == "ext2"
|
||||
|
||||
|
||||
# ===== Extension Catalog Tests =====
|
||||
|
||||
|
||||
class TestExtensionCatalog:
|
||||
"""Test extension catalog functionality."""
|
||||
|
||||
def test_catalog_initialization(self, temp_dir):
|
||||
"""Test catalog initialization."""
|
||||
project_dir = temp_dir / "project"
|
||||
project_dir.mkdir()
|
||||
(project_dir / ".specify").mkdir()
|
||||
|
||||
catalog = ExtensionCatalog(project_dir)
|
||||
|
||||
assert catalog.project_root == project_dir
|
||||
assert catalog.cache_dir == project_dir / ".specify" / "extensions" / ".cache"
|
||||
|
||||
def test_cache_directory_creation(self, temp_dir):
|
||||
"""Test catalog cache directory is created when fetching."""
|
||||
project_dir = temp_dir / "project"
|
||||
project_dir.mkdir()
|
||||
(project_dir / ".specify").mkdir()
|
||||
|
||||
catalog = ExtensionCatalog(project_dir)
|
||||
|
||||
# Create mock catalog data
|
||||
catalog_data = {
|
||||
"schema_version": "1.0",
|
||||
"extensions": {
|
||||
"test-ext": {
|
||||
"name": "Test Extension",
|
||||
"id": "test-ext",
|
||||
"version": "1.0.0",
|
||||
"description": "Test",
|
||||
}
|
||||
},
|
||||
}
|
||||
|
||||
# Manually save to cache to test cache reading
|
||||
catalog.cache_dir.mkdir(parents=True, exist_ok=True)
|
||||
catalog.cache_file.write_text(json.dumps(catalog_data))
|
||||
catalog.cache_metadata_file.write_text(
|
||||
json.dumps(
|
||||
{
|
||||
"cached_at": datetime.now(timezone.utc).isoformat(),
|
||||
"catalog_url": "http://test.com/catalog.json",
|
||||
}
|
||||
)
|
||||
)
|
||||
|
||||
# Should use cache
|
||||
result = catalog.fetch_catalog()
|
||||
assert result == catalog_data
|
||||
|
||||
def test_cache_expiration(self, temp_dir):
|
||||
"""Test that expired cache is not used."""
|
||||
project_dir = temp_dir / "project"
|
||||
project_dir.mkdir()
|
||||
(project_dir / ".specify").mkdir()
|
||||
|
||||
catalog = ExtensionCatalog(project_dir)
|
||||
|
||||
# Create expired cache
|
||||
catalog.cache_dir.mkdir(parents=True, exist_ok=True)
|
||||
catalog_data = {"schema_version": "1.0", "extensions": {}}
|
||||
catalog.cache_file.write_text(json.dumps(catalog_data))
|
||||
|
||||
# Set cache time to 2 hours ago (expired)
|
||||
expired_time = datetime.now(timezone.utc).timestamp() - 7200
|
||||
expired_datetime = datetime.fromtimestamp(expired_time, tz=timezone.utc)
|
||||
catalog.cache_metadata_file.write_text(
|
||||
json.dumps(
|
||||
{
|
||||
"cached_at": expired_datetime.isoformat(),
|
||||
"catalog_url": "http://test.com/catalog.json",
|
||||
}
|
||||
)
|
||||
)
|
||||
|
||||
# Cache should be invalid
|
||||
assert not catalog.is_cache_valid()
|
||||
|
||||
def test_search_all_extensions(self, temp_dir):
|
||||
"""Test searching all extensions without filters."""
|
||||
project_dir = temp_dir / "project"
|
||||
project_dir.mkdir()
|
||||
(project_dir / ".specify").mkdir()
|
||||
|
||||
catalog = ExtensionCatalog(project_dir)
|
||||
|
||||
# Create mock catalog
|
||||
catalog_data = {
|
||||
"schema_version": "1.0",
|
||||
"extensions": {
|
||||
"jira": {
|
||||
"name": "Jira Integration",
|
||||
"id": "jira",
|
||||
"version": "1.0.0",
|
||||
"description": "Jira integration",
|
||||
"author": "Stats Perform",
|
||||
"tags": ["issue-tracking", "jira"],
|
||||
"verified": True,
|
||||
},
|
||||
"linear": {
|
||||
"name": "Linear Integration",
|
||||
"id": "linear",
|
||||
"version": "0.9.0",
|
||||
"description": "Linear integration",
|
||||
"author": "Community",
|
||||
"tags": ["issue-tracking"],
|
||||
"verified": False,
|
||||
},
|
||||
},
|
||||
}
|
||||
|
||||
# Save to cache
|
||||
catalog.cache_dir.mkdir(parents=True, exist_ok=True)
|
||||
catalog.cache_file.write_text(json.dumps(catalog_data))
|
||||
catalog.cache_metadata_file.write_text(
|
||||
json.dumps(
|
||||
{
|
||||
"cached_at": datetime.now(timezone.utc).isoformat(),
|
||||
"catalog_url": "http://test.com",
|
||||
}
|
||||
)
|
||||
)
|
||||
|
||||
# Search without filters
|
||||
results = catalog.search()
|
||||
assert len(results) == 2
|
||||
|
||||
def test_search_by_query(self, temp_dir):
|
||||
"""Test searching by query text."""
|
||||
project_dir = temp_dir / "project"
|
||||
project_dir.mkdir()
|
||||
(project_dir / ".specify").mkdir()
|
||||
|
||||
catalog = ExtensionCatalog(project_dir)
|
||||
|
||||
# Create mock catalog
|
||||
catalog_data = {
|
||||
"schema_version": "1.0",
|
||||
"extensions": {
|
||||
"jira": {
|
||||
"name": "Jira Integration",
|
||||
"id": "jira",
|
||||
"version": "1.0.0",
|
||||
"description": "Jira issue tracking",
|
||||
"tags": ["jira"],
|
||||
},
|
||||
"linear": {
|
||||
"name": "Linear Integration",
|
||||
"id": "linear",
|
||||
"version": "1.0.0",
|
||||
"description": "Linear project management",
|
||||
"tags": ["linear"],
|
||||
},
|
||||
},
|
||||
}
|
||||
|
||||
catalog.cache_dir.mkdir(parents=True, exist_ok=True)
|
||||
catalog.cache_file.write_text(json.dumps(catalog_data))
|
||||
catalog.cache_metadata_file.write_text(
|
||||
json.dumps(
|
||||
{
|
||||
"cached_at": datetime.now(timezone.utc).isoformat(),
|
||||
"catalog_url": "http://test.com",
|
||||
}
|
||||
)
|
||||
)
|
||||
|
||||
# Search for "jira"
|
||||
results = catalog.search(query="jira")
|
||||
assert len(results) == 1
|
||||
assert results[0]["id"] == "jira"
|
||||
|
||||
def test_search_by_tag(self, temp_dir):
|
||||
"""Test searching by tag."""
|
||||
project_dir = temp_dir / "project"
|
||||
project_dir.mkdir()
|
||||
(project_dir / ".specify").mkdir()
|
||||
|
||||
catalog = ExtensionCatalog(project_dir)
|
||||
|
||||
# Create mock catalog
|
||||
catalog_data = {
|
||||
"schema_version": "1.0",
|
||||
"extensions": {
|
||||
"jira": {
|
||||
"name": "Jira",
|
||||
"id": "jira",
|
||||
"version": "1.0.0",
|
||||
"description": "Jira",
|
||||
"tags": ["issue-tracking", "jira"],
|
||||
},
|
||||
"linear": {
|
||||
"name": "Linear",
|
||||
"id": "linear",
|
||||
"version": "1.0.0",
|
||||
"description": "Linear",
|
||||
"tags": ["issue-tracking", "linear"],
|
||||
},
|
||||
"github": {
|
||||
"name": "GitHub",
|
||||
"id": "github",
|
||||
"version": "1.0.0",
|
||||
"description": "GitHub",
|
||||
"tags": ["vcs", "github"],
|
||||
},
|
||||
},
|
||||
}
|
||||
|
||||
catalog.cache_dir.mkdir(parents=True, exist_ok=True)
|
||||
catalog.cache_file.write_text(json.dumps(catalog_data))
|
||||
catalog.cache_metadata_file.write_text(
|
||||
json.dumps(
|
||||
{
|
||||
"cached_at": datetime.now(timezone.utc).isoformat(),
|
||||
"catalog_url": "http://test.com",
|
||||
}
|
||||
)
|
||||
)
|
||||
|
||||
# Search by tag "issue-tracking"
|
||||
results = catalog.search(tag="issue-tracking")
|
||||
assert len(results) == 2
|
||||
assert {r["id"] for r in results} == {"jira", "linear"}
|
||||
|
||||
def test_search_verified_only(self, temp_dir):
|
||||
"""Test searching verified extensions only."""
|
||||
project_dir = temp_dir / "project"
|
||||
project_dir.mkdir()
|
||||
(project_dir / ".specify").mkdir()
|
||||
|
||||
catalog = ExtensionCatalog(project_dir)
|
||||
|
||||
# Create mock catalog
|
||||
catalog_data = {
|
||||
"schema_version": "1.0",
|
||||
"extensions": {
|
||||
"jira": {
|
||||
"name": "Jira",
|
||||
"id": "jira",
|
||||
"version": "1.0.0",
|
||||
"description": "Jira",
|
||||
"verified": True,
|
||||
},
|
||||
"linear": {
|
||||
"name": "Linear",
|
||||
"id": "linear",
|
||||
"version": "1.0.0",
|
||||
"description": "Linear",
|
||||
"verified": False,
|
||||
},
|
||||
},
|
||||
}
|
||||
|
||||
catalog.cache_dir.mkdir(parents=True, exist_ok=True)
|
||||
catalog.cache_file.write_text(json.dumps(catalog_data))
|
||||
catalog.cache_metadata_file.write_text(
|
||||
json.dumps(
|
||||
{
|
||||
"cached_at": datetime.now(timezone.utc).isoformat(),
|
||||
"catalog_url": "http://test.com",
|
||||
}
|
||||
)
|
||||
)
|
||||
|
||||
# Search verified only
|
||||
results = catalog.search(verified_only=True)
|
||||
assert len(results) == 1
|
||||
assert results[0]["id"] == "jira"
|
||||
|
||||
def test_get_extension_info(self, temp_dir):
|
||||
"""Test getting specific extension info."""
|
||||
project_dir = temp_dir / "project"
|
||||
project_dir.mkdir()
|
||||
(project_dir / ".specify").mkdir()
|
||||
|
||||
catalog = ExtensionCatalog(project_dir)
|
||||
|
||||
# Create mock catalog
|
||||
catalog_data = {
|
||||
"schema_version": "1.0",
|
||||
"extensions": {
|
||||
"jira": {
|
||||
"name": "Jira Integration",
|
||||
"id": "jira",
|
||||
"version": "1.0.0",
|
||||
"description": "Jira integration",
|
||||
"author": "Stats Perform",
|
||||
},
|
||||
},
|
||||
}
|
||||
|
||||
catalog.cache_dir.mkdir(parents=True, exist_ok=True)
|
||||
catalog.cache_file.write_text(json.dumps(catalog_data))
|
||||
catalog.cache_metadata_file.write_text(
|
||||
json.dumps(
|
||||
{
|
||||
"cached_at": datetime.now(timezone.utc).isoformat(),
|
||||
"catalog_url": "http://test.com",
|
||||
}
|
||||
)
|
||||
)
|
||||
|
||||
# Get extension info
|
||||
info = catalog.get_extension_info("jira")
|
||||
assert info is not None
|
||||
assert info["id"] == "jira"
|
||||
assert info["name"] == "Jira Integration"
|
||||
|
||||
# Non-existent extension
|
||||
info = catalog.get_extension_info("nonexistent")
|
||||
assert info is None
|
||||
|
||||
def test_clear_cache(self, temp_dir):
|
||||
"""Test clearing catalog cache."""
|
||||
project_dir = temp_dir / "project"
|
||||
project_dir.mkdir()
|
||||
(project_dir / ".specify").mkdir()
|
||||
|
||||
catalog = ExtensionCatalog(project_dir)
|
||||
|
||||
# Create cache
|
||||
catalog.cache_dir.mkdir(parents=True, exist_ok=True)
|
||||
catalog.cache_file.write_text("{}")
|
||||
catalog.cache_metadata_file.write_text("{}")
|
||||
|
||||
assert catalog.cache_file.exists()
|
||||
assert catalog.cache_metadata_file.exists()
|
||||
|
||||
# Clear cache
|
||||
catalog.clear_cache()
|
||||
|
||||
assert not catalog.cache_file.exists()
|
||||
assert not catalog.cache_metadata_file.exists()
|
||||
Reference in New Issue
Block a user