mirror of
https://github.com/github/spec-kit.git
synced 2026-03-16 18:33:07 +00:00
Add modular extension system (#1551)
* Add modular extension system for Spec Kit Implement a complete extension system that allows third-party developers to extend Spec Kit functionality through plugins. ## Core Features - Extension discovery and loading from local and global directories - YAML-based extension manifest (extension.yml) with metadata and capabilities - Command extensions: custom slash commands with markdown templates - Hook system: pre/post hooks for generate, task, and sync operations - Extension catalog for discovering and installing community extensions - SPECKIT_CATALOG_URL environment variable for catalog URL override ## Installation Methods - Catalog install: `specify extension add <name>` - URL install: `specify extension add <name> --from <url>` - Dev install: `specify extension add --dev <path>` ## Implementation - ExtensionManager class for lifecycle management (load, enable, disable) - Support for extension dependencies and version constraints - Configuration layering (global → project → extension) - Hook conditions for conditional execution ## Documentation - RFC with design rationale and architecture decisions - API reference for extension developers - Development guide with examples - User guide for installing and managing extensions - Publishing guide for the extension catalog ## Included - Extension template for bootstrapping new extensions - Comprehensive test suite - Example catalog.json structure Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * Update Jira extension to v2.1.0 in catalog Adds 2-level mode support (Epic → Stories only). Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * Address PR review feedback - Fix Zip Slip vulnerability in ZIP extraction with path validation - Fix keep_config option to actually preserve config files on removal - Add URL validation for SPECKIT_CATALOG_URL (HTTPS required, localhost exception) - Add security warning when installing from custom URLs (--from flag) - Empty catalog.json so organizations can ship their own catalogs - Fix markdown linter errors (MD040: add language to code blocks) - Remove redundant import and fix unused variables in tests - Add comment explaining empty except clause for backwards compatibility Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * Add comprehensive organization catalog customization docs - Explain why default catalog is empty (org control) - Document how to create and host custom catalogs - Add catalog JSON schema reference - Include use cases: private extensions, curated catalogs, air-gapped environments - Add examples for combining catalog with direct installation Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * Fix test assertions for extension system data structures - Update test_config_backup_on_remove to use new subdirectory structure (.backup/test-ext/file.yml instead of .backup/test-ext-file.yml) - Update test_full_install_and_remove_workflow to handle registered_commands being a dict keyed by agent name instead of a flat list Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * Address Copilot review feedback - Fix localhost URL check to use parsed.hostname instead of netloc.startswith() This correctly handles URLs with ports like localhost:8080 - Fix YAML indentation error in config-template.yml (line 57) - Fix double space typo in example.md (line 172) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * Add catalog.example.json as reference for organizations The main catalog.json is intentionally empty so organizations can ship their own curated catalogs. This example file shows the expected schema and structure for creating organization-specific catalogs. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * Address remaining Copilot security and logic review feedback - Fix Zip Slip vulnerability by using relative_to() for safe path validation - Add HTTPS validation for extension download URLs - Backup both *-config.yml and *-config.local.yml files on remove - Normalize boolean values to lowercase for hook condition comparisons - Show non-default catalog warning only once per instance Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * Ignoring linter for extensions directory --------- Co-authored-by: iamaeroplane <michal.bachorik@gmail.com> Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com> Co-authored-by: Manfred Riem <manfred.riem@microsoft.com>
This commit is contained in:
Michal Bachorik
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
|
||||
|
||||
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
|
||||
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": {}
|
||||
}
|
||||
@@ -1399,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
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