💫 Toolkit to help you get started with SDD or any other process!
feat(extensions): Quality of life improvements for RFC-aligned catalog integration (#1776)
Michal Bachorik58ce653908a3
diff --git a/extensions/RFC-EXTENSION-SYSTEM.md b/extensions/RFC-EXTENSION-SYSTEM.mdindex c6469c48d..a0f6034e5 100644--- a/extensions/RFC-EXTENSION-SYSTEM.md+++ b/extensions/RFC-EXTENSION-SYSTEM.md@@ -1,9 +1,9 @@# RFC: Spec Kit Extension System-**Status**: Draft+**Status**: Implemented**Author**: Stats Perform Engineering**Created**: 2026-01-28-**Updated**: 2026-01-28+**Updated**: 2026-03-11---@@ -24,8 +24,9 @@13. [Security Considerations](#security-considerations)14. [Migration Strategy](#migration-strategy)15. [Implementation Phases](#implementation-phases)-16. [Open Questions](#open-questions)-17. [Appendices](#appendices)+16. [Resolved Questions](#resolved-questions)+17. [Open Questions (Remaining)](#open-questions-remaining)+18. [Appendices](#appendices)---@@ -1504,203 +1505,225 @@ AI agent registers both names, so old scripts work.## Implementation Phases-### Phase 1: Core Extension System (Week 1-2)+### Phase 1: Core Extension System ✅ COMPLETED**Goal**: Basic extension infrastructure**Deliverables**:-- [ ] Extension manifest schema (`extension.yml`)-- [ ] Extension directory structure-- [ ] CLI commands:- - [ ] `specify extension list`- - [ ] `specify extension add` (from URL)- - [ ] `specify extension remove`-- [ ] Extension registry (`.specify/extensions/.registry`)-- [ ] Command registration (Claude only initially)-- [ ] Basic validation (manifest schema, compatibility)-- [ ] Documentation (extension development guide)+- [x] Extension manifest schema (`extension.yml`)+- [x] Extension directory structure+- [x] CLI commands:+ - [x] `specify extension list`+ - [x] `specify extension add` (from URL and local `--dev`)+ - [x] `specify extension remove`+- [x] Extension registry (`.specify/extensions/.registry`)+- [x] Command registration (Claude and 15+ other agents)+- [x] Basic validation (manifest schema, compatibility)+- [x] Documentation (extension development guide)**Testing**:-- [ ] Unit tests for manifest parsing-- [ ] Integration test: Install dummy extension-- [ ] Integration test: Register commands with Claude+- [x] Unit tests for manifest parsing+- [x] Integration test: Install dummy extension+- [x] Integration test: Register commands with Claude-### Phase 2: Jira Extension (Week 3)+### Phase 2: Jira Extension ✅ COMPLETED**Goal**: First production extension**Deliverables**:-- [ ] Create `spec-kit-jira` repository-- [ ] Port Jira functionality to extension-- [ ] Create `jira-config.yml` template-- [ ] Commands:- - [ ] `specstoissues.md`- - [ ] `discover-fields.md`- - [ ] `sync-status.md`-- [ ] Helper scripts-- [ ] Documentation (README, configuration guide, examples)-- [ ] Release v1.0.0+- [x] Create `spec-kit-jira` repository+- [x] Port Jira functionality to extension+- [x] Create `jira-config.yml` template+- [x] Commands:+ - [x] `specstoissues.md`+ - [x] `discover-fields.md`+ - [x] `sync-status.md`+- [x] Helper scripts+- [x] Documentation (README, configuration guide, examples)+- [x] Release v3.0.0**Testing**:-- [ ] Test on `eng-msa-ts` project-- [ ] Verify spec→Epic, phase→Story, task→Issue mapping-- [ ] Test configuration loading and validation-- [ ] Test custom field application+- [x] Test on `eng-msa-ts` project+- [x] Verify spec→Epic, phase→Story, task→Issue mapping+- [x] Test configuration loading and validation+- [x] Test custom field application-### Phase 3: Extension Catalog (Week 4)+### Phase 3: Extension Catalog ✅ COMPLETED**Goal**: Discovery and distribution**Deliverables**:-- [ ] Central catalog (`extensions/catalog.json` in spec-kit repo)-- [ ] Catalog fetch and parsing-- [ ] CLI commands:- - [ ] `specify extension search`- - [ ] `specify extension info`-- [ ] Catalog publishing process (GitHub Action)-- [ ] Documentation (how to publish extensions)+- [x] Central catalog (`extensions/catalog.json` in spec-kit repo)+- [x] Community catalog (`extensions/catalog.community.json`)+- [x] Catalog fetch and parsing with multi-catalog support+- [x] CLI commands:+ - [x] `specify extension search`+ - [x] `specify extension info`+ - [x] `specify extension catalog list`+ - [x] `specify extension catalog add`+ - [x] `specify extension catalog remove`+- [x] Documentation (how to publish extensions)**Testing**:-- [ ] Test catalog fetch-- [ ] Test extension search/filtering-- [ ] Test catalog caching+- [x] Test catalog fetch+- [x] Test extension search/filtering+- [x] Test catalog caching+- [x] Test multi-catalog merge with priority-### Phase 4: Advanced Features (Week 5-6)+### Phase 4: Advanced Features ✅ COMPLETED**Goal**: Hooks, updates, multi-agent support**Deliverables**:-- [ ] Hook system (`hooks` in extension.yml)-- [ ] Hook registration and execution-- [ ] Project extensions config (`.specify/extensions.yml`)-- [ ] CLI commands:- - [ ] `specify extension update`- - [ ] `specify extension enable/disable`-- [ ] Command registration for multiple agents (Gemini, Copilot)-- [ ] Extension update notifications-- [ ] Configuration layer resolution (project, local, env)+- [x] Hook system (`hooks` in extension.yml)+- [x] Hook registration and execution+- [x] Project extensions config (`.specify/extensions.yml`)+- [x] CLI commands:+ - [x] `specify extension update` (with atomic backup/restore)+ - [x] `specify extension enable/disable`+- [x] Command registration for multiple agents (15+ agents including Claude, Copilot, Gemini, Cursor, etc.)+- [x] Extension update notifications (version comparison)+- [x] Configuration layer resolution (project, local, env)++**Additional features implemented beyond original RFC**:++- [x] **Display name resolution**: All commands accept extension display names in addition to IDs+- [x] **Ambiguous name handling**: User-friendly tables when multiple extensions match a name+- [x] **Atomic update with rollback**: Full backup of extension dir, commands, hooks, and registry with automatic rollback on failure+- [x] **Pre-install ID validation**: Validates extension ID from ZIP before installing (security)+- [x] **Enabled state preservation**: Disabled extensions stay disabled after update+- [x] **Registry update/restore methods**: Clean API for enable/disable and rollback operations+- [x] **Catalog error fallback**: `extension info` falls back to local info when catalog unavailable+- [x] **`_install_allowed` flag**: Discovery-only catalogs can't be used for installation+- [x] **Cache invalidation**: Cache invalidated when `SPECKIT_CATALOG_URL` changes**Testing**:-- [ ] Test hooks in core commands-- [ ] Test extension updates (preserve config)-- [ ] Test multi-agent registration+- [x] Test hooks in core commands+- [x] Test extension updates (preserve config)+- [x] Test multi-agent registration+- [x] Test atomic rollback on update failure+- [x] Test enabled state preservation+- [x] Test display name resolution-### Phase 5: Polish & Documentation (Week 7)+### Phase 5: Polish & Documentation ✅ COMPLETED**Goal**: Production ready**Deliverables**:-- [ ] Comprehensive documentation:- - [ ] User guide (installing/using extensions)- - [ ] Extension development guide- - [ ] Extension API reference- - [ ] Migration guide (core → extension)-- [ ] Error messages and validation improvements-- [ ] CLI help text updates-- [ ] Example extension template (cookiecutter)-- [ ] Blog post / announcement-- [ ] Video tutorial+- [x] Comprehensive documentation:+ - [x] User guide (EXTENSION-USER-GUIDE.md)+ - [x] Extension development guide (EXTENSION-DEV-GUIDE.md)+ - [x] Extension API reference (EXTENSION-API-REFERENCE.md)+- [x] Error messages and validation improvements+- [x] CLI help text updates**Testing**:-- [ ] End-to-end testing on multiple projects-- [ ] Community beta testing-- [ ] Performance testing (large projects)+- [x] End-to-end testing on multiple projects+- [x] 163 unit tests passing----## Open Questions+## Resolved Questions-### 1. Extension Namespace+The following questions from the original RFC have been resolved during implementation:-**Question**: Should extension commands use namespace prefix?+### 1. Extension Namespace ✅ RESOLVED-**Options**:+**Question**: Should extension commands use namespace prefix?-- A) Prefixed: `/speckit.jira.specstoissues` (explicit, avoids conflicts)-- B) Short alias: `/jira.specstoissues` (shorter, less verbose)-- C) Both: Register both names, prefer prefixed in docs+**Decision**: **Option C** - Both prefixed and aliases are supported. Commands use `speckit.{extension}.{command}` as canonical name, with optional aliases defined in manifest.-**Recommendation**: C (both), prefixed is canonical+**Implementation**: The `aliases` field in `extension.yml` allows extensions to register additional command names.----### 2. Config File Location+### 2. Config File Location ✅ RESOLVED**Question**: Where should extension configs live?-**Options**:--- A) Extension directory: `.specify/extensions/jira/jira-config.yml` (encapsulated)-- B) Root level: `.specify/jira-config.yml` (more visible)-- C) Unified: `.specify/extensions.yml` (all extension configs in one file)+**Decision**: **Option A** - Extension directory (`.specify/extensions/{ext-id}/{ext-id}-config.yml`). This keeps extensions self-contained and easier to manage.-**Recommendation**: A (extension directory), cleaner separation+**Implementation**: Each extension has its own config file within its directory, with layered resolution (defaults → project → local → env vars).----### 3. Command File Format+### 3. Command File Format ✅ RESOLVED**Question**: Should extensions use universal format or agent-specific?-**Options**:--- A) Universal Markdown: Extensions write once, CLI converts per-agent-- B) Agent-specific: Extensions provide separate files for each agent-- C) Hybrid: Universal default, agent-specific overrides+**Decision**: **Option A** - Universal Markdown format. Extensions write commands once, CLI converts to agent-specific format during registration.-**Recommendation**: A (universal), reduces duplication+**Implementation**: `CommandRegistrar` class handles conversion to 15+ agent formats (Claude, Copilot, Gemini, Cursor, etc.).----### 4. Hook Execution Model+### 4. Hook Execution Model ✅ RESOLVED**Question**: How should hooks execute?-**Options**:--- A) AI agent interprets: Core commands output `EXECUTE_COMMAND: name`-- B) CLI executes: Core commands call `specify extension hook after_tasks`-- C) Agent built-in: Extension system built into AI agent (Claude SDK)+**Decision**: **Option A** - Hooks are registered in `.specify/extensions.yml` and executed by the AI agent when it sees the hook trigger. Hook state (enabled/disabled) is managed per-extension.-**Recommendation**: A initially (simpler), move to C long-term+**Implementation**: `HookExecutor` class manages hook registration and state in `extensions.yml`.----### 5. Extension Distribution+### 5. Extension Distribution ✅ RESOLVED**Question**: How should extensions be packaged?+**Decision**: **Option A** - ZIP archives downloaded from GitHub releases (via catalog `download_url`). Local development uses `--dev` flag with directory path.++**Implementation**: `ExtensionManager.install_from_zip()` handles ZIP extraction and validation.++---++### 6. Multi-Version Support ✅ RESOLVED++**Question**: Can multiple versions of same extension coexist?++**Decision**: **Option A** - Single version only. Updates replace the existing version with atomic rollback on failure.++**Implementation**: `extension update` performs atomic backup/restore to ensure safe updates.++---++## Open Questions (Remaining)++### 1. Sandboxing / Permissions (Future)++**Question**: Should extensions declare required permissions?+**Options**:-- A) ZIP archives: Downloaded from GitHub releases-- B) Git repos: Cloned directly (`git clone`)-- C) Python packages: Installable via `uv tool install`+- A) No sandboxing (current): Extensions run with same privileges as AI agent+- B) Permission declarations: Extensions declare `filesystem:read`, `network:external`, etc.+- C) Opt-in sandboxing: Organizations can enable permission enforcement-**Recommendation**: A (ZIP), simpler for non-Python extensions in future+**Status**: Deferred to future version. Currently using trust-based model where users trust extension authors.----### 6. Multi-Version Support+### 2. Package Signatures (Future)-**Question**: Can multiple versions of same extension coexist?+**Question**: Should extensions be cryptographically signed?**Options**:-- A) Single version: Only one version installed at a time-- B) Multi-version: Side-by-side versions (`.specify/extensions/[email protected]/`, `.specify/extensions/[email protected]/`)-- C) Per-branch: Different branches use different versions+- A) No signatures (current): Trust based on catalog source+- B) GPG/Sigstore signatures: Verify package integrity+- C) Catalog-level verification: Catalog maintainers verify packages-**Recommendation**: A initially (simpler), consider B in future if needed+**Status**: Deferred to future version. `checksum` field is available in catalog schema but not enforced.---diff --git a/src/specify_cli/__init__.py b/src/specify_cli/__init__.pyindex dac7eaa54..55e97ea9f 100644--- a/src/specify_cli/__init__.py+++ b/src/specify_cli/__init__.py@@ -1813,6 +1813,126 @@ def get_speckit_version() -> str:return "unknown"+def _resolve_installed_extension(+ argument: str,+ installed_extensions: list,+ command_name: str = "command",+ allow_not_found: bool = False,+) -> tuple[Optional[str], Optional[str]]:+ """Resolve an extension argument (ID or display name) to an installed extension.++ Args:+ argument: Extension ID or display name provided by user+ installed_extensions: List of installed extension dicts from manager.list_installed()+ command_name: Name of the command for error messages (e.g., "enable", "disable")+ allow_not_found: If True, return (None, None) when not found instead of raising++ Returns:+ Tuple of (extension_id, display_name), or (None, None) if allow_not_found=True and not found++ Raises:+ typer.Exit: If extension not found (and allow_not_found=False) or name is ambiguous+ """+ from rich.table import Table++ # First, try exact ID match+ for ext in installed_extensions:+ if ext["id"] == argument:+ return (ext["id"], ext["name"])++ # If not found by ID, try display name match+ name_matches = [ext for ext in installed_extensions if ext["name"].lower() == argument.lower()]++ if len(name_matches) == 1:+ # Unique display-name match+ return (name_matches[0]["id"], name_matches[0]["name"])+ elif len(name_matches) > 1:+ # Ambiguous display-name match+ console.print(+ f"[red]Error:[/red] Extension name '{argument}' is ambiguous. "+ "Multiple installed extensions share this name:"+ )+ table = Table(title="Matching extensions")+ table.add_column("ID", style="cyan", no_wrap=True)+ table.add_column("Name", style="white")+ table.add_column("Version", style="green")+ for ext in name_matches:+ table.add_row(ext.get("id", ""), ext.get("name", ""), str(ext.get("version", "")))+ console.print(table)+ console.print("\nPlease rerun using the extension ID:")+ console.print(f" [bold]specify extension {command_name} <extension-id>[/bold]")+ raise typer.Exit(1)+ else:+ # No match by ID or display name+ if allow_not_found:+ return (None, None)+ console.print(f"[red]Error:[/red] Extension '{argument}' is not installed")+ raise typer.Exit(1)+++def _resolve_catalog_extension(+ argument: str,+ catalog,+ command_name: str = "info",+) -> tuple[Optional[dict], Optional[Exception]]:+ """Resolve an extension argument (ID or display name) from the catalog.++ Args:+ argument: Extension ID or display name provided by user+ catalog: ExtensionCatalog instance+ command_name: Name of the command for error messages++ Returns:+ Tuple of (extension_info, catalog_error)+ - If found: (ext_info_dict, None)+ - If catalog error: (None, error)+ - If not found: (None, None)+ """+ from rich.table import Table+ from .extensions import ExtensionError++ try:+ # First try by ID+ ext_info = catalog.get_extension_info(argument)+ if ext_info:+ return (ext_info, None)++ # Try by display name - search using argument as query, then filter for exact match+ search_results = catalog.search(query=argument)+ name_matches = [ext for ext in search_results if ext["name"].lower() == argument.lower()]++ if len(name_matches) == 1:+ return (name_matches[0], None)+ elif len(name_matches) > 1:+ # Ambiguous display-name match in catalog+ console.print(+ f"[red]Error:[/red] Extension name '{argument}' is ambiguous. "+ "Multiple catalog extensions share this name:"+ )+ table = Table(title="Matching extensions")+ table.add_column("ID", style="cyan", no_wrap=True)+ table.add_column("Name", style="white")+ table.add_column("Version", style="green")+ table.add_column("Catalog", style="dim")+ for ext in name_matches:+ table.add_row(+ ext.get("id", ""),+ ext.get("name", ""),+ str(ext.get("version", "")),+ ext.get("_catalog_name", ""),+ )+ console.print(table)+ console.print("\nPlease rerun using the extension ID:")+ console.print(f" [bold]specify extension {command_name} <extension-id>[/bold]")+ raise typer.Exit(1)++ # Not found+ return (None, None)++ except ExtensionError as e:+ return (None, e)++@extension_app.command("list")def extension_list(available: bool = typer.Option(False, "--available", help="Show available extensions from catalog"),@@ -2111,8 +2231,11 @@ def extension_add(# Install from catalogcatalog = ExtensionCatalog(project_root)- # Check if extension exists in catalog- ext_info = catalog.get_extension_info(extension)+ # Check if extension exists in catalog (supports both ID and display name)+ ext_info, catalog_error = _resolve_catalog_extension(extension, catalog, "add")+ if catalog_error:+ console.print(f"[red]Error:[/red] Could not query extension catalog: {catalog_error}")+ raise typer.Exit(1)if not ext_info:console.print(f"[red]Error:[/red] Extension '{extension}' not found in catalog")console.print("\nSearch available extensions:")@@ -2132,9 +2255,10 @@ def extension_add()raise typer.Exit(1)- # Download extension ZIP+ # Download extension ZIP (use resolved ID, not original argument which may be display name)+ extension_id = ext_info['id']console.print(f"Downloading {ext_info['name']} v{ext_info.get('version', 'unknown')}...")- zip_path = catalog.download_extension(extension)+ zip_path = catalog.download_extension(extension_id)try:# Install from downloaded ZIP@@ -2167,7 +2291,7 @@ def extension_add(@extension_app.command("remove")def extension_remove(- extension: str = typer.Argument(help="Extension ID to remove"),+ extension: str = typer.Argument(help="Extension ID or name 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"),):@@ -2185,25 +2309,19 @@ def extension_remove(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)+ # Resolve extension ID from argument (handles ambiguous names)+ installed = manager.list_installed()+ extension_id, display_name = _resolve_installed_extension(extension, installed, "remove")- # 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+ # Get extension info for command count+ ext_manifest = manager.get_extension(extension_id)+ cmd_count = len(ext_manifest.commands) if ext_manifest else 0# Confirm removalif not force:console.print("\n[yellow]⚠This will remove:[/yellow]")console.print(f" • {cmd_count} commands from AI agent")- console.print(f" • Extension directory: .specify/extensions/{extension}/")+ console.print(f" • Extension directory: .specify/extensions/{extension_id}/")if not keep_config:console.print(" • Config files (will be backed up)")console.print()@@ -2214,15 +2332,15 @@ def extension_remove(raise typer.Exit(0)# Remove extension- success = manager.remove(extension, keep_config=keep_config)+ success = manager.remove(extension_id, keep_config=keep_config)if success:- console.print(f"\n[green]✓[/green] Extension '{ext_name}' removed successfully")+ console.print(f"\n[green]✓[/green] Extension '{display_name}' removed successfully")if keep_config:- console.print(f"\nConfig files preserved in .specify/extensions/{extension}/")+ console.print(f"\nConfig files preserved in .specify/extensions/{extension_id}/")else:- console.print(f"\nConfig files backed up to .specify/extensions/.backup/{extension}/")- console.print(f"\nTo reinstall: specify extension add {extension}")+ console.print(f"\nConfig files backed up to .specify/extensions/.backup/{extension_id}/")+ console.print(f"\nTo reinstall: specify extension add {extension_id}")else:console.print("[red]Error:[/red] Failed to remove extension")raise typer.Exit(1)@@ -2320,7 +2438,7 @@ def extension_info(extension: str = typer.Argument(help="Extension ID or name"),):"""Show detailed information about an extension."""- from .extensions import ExtensionCatalog, ExtensionManager, ExtensionError+ from .extensions import ExtensionCatalog, ExtensionManagerproject_root = Path.cwd()@@ -2333,118 +2451,181 @@ def extension_info(catalog = ExtensionCatalog(project_root)manager = ExtensionManager(project_root)+ installed = manager.list_installed()- try:- ext_info = catalog.get_extension_info(extension)+ # Try to resolve from installed extensions first (by ID or name)+ # Use allow_not_found=True since the extension may be catalog-only+ resolved_installed_id, resolved_installed_name = _resolve_installed_extension(+ extension, installed, "info", allow_not_found=True+ )- 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)+ # Try catalog lookup (with error handling)+ # If we resolved an installed extension by display name, use its ID for catalog lookup+ # to ensure we get the correct catalog entry (not a different extension with same name)+ lookup_key = resolved_installed_id if resolved_installed_id else extension+ ext_info, catalog_error = _resolve_catalog_extension(lookup_key, catalog, "info")- # 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()+ # Case 1: Found in catalog - show full catalog info+ if ext_info:+ _print_extension_info(ext_info, manager)+ return- # Description- console.print(f"{ext_info['description']}")+ # Case 2: Installed locally but catalog lookup failed or not in catalog+ if resolved_installed_id:+ # Get local manifest info+ ext_manifest = manager.get_extension(resolved_installed_id)+ metadata = manager.registry.get(resolved_installed_id)++ console.print(f"\n[bold]{resolved_installed_name}[/bold] (v{metadata.get('version', 'unknown')})")+ console.print(f"ID: {resolved_installed_id}")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')}")+ if ext_manifest:+ console.print(f"{ext_manifest.description}")+ console.print()+ # Author is optional in extension.yml, safely retrieve it+ author = ext_manifest.data.get("extension", {}).get("author")+ if author:+ console.print(f"[dim]Author:[/dim] {author}")+ console.print()++ if ext_manifest.commands:+ console.print("[bold]Commands:[/bold]")+ for cmd in ext_manifest.commands:+ console.print(f" • {cmd['name']}: {cmd.get('description', '')}")+ console.print()++ # Show catalog status+ if catalog_error:+ console.print(f"[yellow]Catalog unavailable:[/yellow] {catalog_error}")+ console.print("[dim]Note: Using locally installed extension; catalog info could not be verified.[/dim]")+ else:+ console.print("[yellow]Note:[/yellow] Not found in catalog (custom/local extension)")- # Source catalog- if ext_info.get("_catalog_name"):- install_allowed = ext_info.get("_install_allowed", True)- install_note = "" if install_allowed else " [yellow](discovery only)[/yellow]"- console.print(f"[dim]Source catalog:[/dim] {ext_info['_catalog_name']}{install_note}")console.print()+ console.print("[green]✓ Installed[/green]")+ console.print(f"\nTo remove: specify extension remove {resolved_installed_id}")+ return- # 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()+ # Case 3: Not found anywhere+ if catalog_error:+ console.print(f"[red]Error:[/red] Could not query extension catalog: {catalog_error}")+ console.print("\nTry again when online, or use the extension ID directly.")+ else:+ console.print(f"[red]Error:[/red] Extension '{extension}' not found")+ console.print("\nTry: specify extension search")+ raise typer.Exit(1)- # 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()+def _print_extension_info(ext_info: dict, manager):+ """Print formatted extension info from catalog data."""+ # 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()- # 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()+ # Description+ console.print(f"{ext_info['description']}")+ 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()+ # 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')}")- # Installation status and command- is_installed = manager.registry.is_installed(ext_info['id'])+ # Source catalog+ if ext_info.get("_catalog_name"):install_allowed = ext_info.get("_install_allowed", True)- if is_installed:- console.print("[green]✓ Installed[/green]")- console.print(f"\nTo remove: specify extension remove {ext_info['id']}")- elif install_allowed:- console.print("[yellow]Not installed[/yellow]")- console.print(f"\n[cyan]Install:[/cyan] specify extension add {ext_info['id']}")- else:- catalog_name = ext_info.get("_catalog_name", "community")- console.print("[yellow]Not installed[/yellow]")- console.print(- f"\n[yellow]⚠[/yellow] '{ext_info['id']}' is available in the '{catalog_name}' catalog "- f"but not in your approved catalog. Add it to .specify/extension-catalogs.yml "- f"with install_allowed: true to enable installation."- )+ install_note = "" if install_allowed else " [yellow](discovery only)[/yellow]"+ console.print(f"[dim]Source catalog:[/dim] {ext_info['_catalog_name']}{install_note}")+ console.print()- except ExtensionError as e:- console.print(f"\n[red]Error:[/red] {e}")- raise typer.Exit(1)+ # 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'])+ install_allowed = ext_info.get("_install_allowed", True)+ if is_installed:+ console.print("[green]✓ Installed[/green]")+ console.print(f"\nTo remove: specify extension remove {ext_info['id']}")+ elif install_allowed:+ console.print("[yellow]Not installed[/yellow]")+ console.print(f"\n[cyan]Install:[/cyan] specify extension add {ext_info['id']}")+ else:+ catalog_name = ext_info.get("_catalog_name", "community")+ console.print("[yellow]Not installed[/yellow]")+ console.print(+ f"\n[yellow]⚠[/yellow] '{ext_info['id']}' is available in the '{catalog_name}' catalog "+ f"but not in your approved catalog. Add it to .specify/extension-catalogs.yml "+ f"with install_allowed: true to enable installation."+ )@extension_app.command("update")def extension_update(- extension: str = typer.Argument(None, help="Extension ID to update (or all)"),+ extension: str = typer.Argument(None, help="Extension ID or name to update (or all)"),):"""Update extension(s) to latest version."""- from .extensions import ExtensionManager, ExtensionCatalog, ExtensionError+ from .extensions import (+ ExtensionManager,+ ExtensionCatalog,+ ExtensionError,+ ValidationError,+ CommandRegistrar,+ HookExecutor,+ )from packaging import version as pkg_version+ import shutilproject_root = Path.cwd()@@ -2457,18 +2638,17 @@ def extension_update(manager = ExtensionManager(project_root)catalog = ExtensionCatalog(project_root)+ speckit_version = get_speckit_version()try:# Get list of extensions to update+ installed = manager.list_installed()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]+ # Update specific extension - resolve ID from argument (handles ambiguous names)+ extension_id, _ = _resolve_installed_extension(extension, installed, "update")+ extensions_to_update = [extension_id]else:# Update all extensions- installed = manager.list_installed()extensions_to_update = [ext["id"] for ext in installed]if not extensions_to_update:@@ -2482,7 +2662,16 @@ def extension_update(for ext_id in extensions_to_update:# Get installed versionmetadata = manager.registry.get(ext_id)- installed_version = pkg_version.Version(metadata["version"])+ if metadata is None or "version" not in metadata:+ console.print(f"⚠{ext_id}: Registry entry corrupted or missing (skipping)")+ continue+ try:+ installed_version = pkg_version.Version(metadata["version"])+ except pkg_version.InvalidVersion:+ console.print(+ f"⚠{ext_id}: Invalid installed version '{metadata.get('version')}' in registry (skipping)"+ )+ continue# Get catalog infoext_info = catalog.get_extension_info(ext_id)@@ -2490,12 +2679,24 @@ def extension_update(console.print(f"⚠{ext_id}: Not found in catalog (skipping)")continue- catalog_version = pkg_version.Version(ext_info["version"])+ # Check if installation is allowed from this catalog+ if not ext_info.get("_install_allowed", True):+ console.print(f"⚠{ext_id}: Updates not allowed from '{ext_info.get('_catalog_name', 'catalog')}' (skipping)")+ continue++ try:+ catalog_version = pkg_version.Version(ext_info["version"])+ except pkg_version.InvalidVersion:+ console.print(+ f"⚠{ext_id}: Invalid catalog version '{ext_info.get('version')}' (skipping)"+ )+ continueif catalog_version > installed_version:updates_available.append({"id": ext_id,+ "name": ext_info.get("name", ext_id), # Display name for status messages"installed": str(installed_version),"available": str(catalog_version),"download_url": ext_info.get("download_url"),@@ -2521,25 +2722,288 @@ def extension_update(console.print("Cancelled")raise typer.Exit(0)- # Perform updates+ # Perform updates with atomic backup/restoreconsole.print()+ updated_extensions = []+ failed_updates = []+ registrar = CommandRegistrar()+ hook_executor = HookExecutor(project_root)+for update in updates_available:- ext_id = update["id"]- console.print(f"📦 Updating {ext_id}...")+ extension_id = update["id"]+ ext_name = update["name"] # Use display name for user-facing messages+ console.print(f"📦 Updating {ext_name}...")- # TODO: Implement download and reinstall from URL- # For now, just show message- console.print(- "[yellow]Note:[/yellow] Automatic update not yet implemented. "- "Please update manually:"- )- console.print(f" specify extension remove {ext_id} --keep-config")- console.print(f" specify extension add {ext_id}")+ # Backup paths+ backup_base = manager.extensions_dir / ".backup" / f"{extension_id}-update"+ backup_ext_dir = backup_base / "extension"+ backup_commands_dir = backup_base / "commands"+ backup_config_dir = backup_base / "config"- console.print(- "\n[cyan]Tip:[/cyan] Automatic updates will be available in a future version"- )+ # Store backup state+ backup_registry_entry = None+ backup_hooks = None # None means no hooks key in config; {} means hooks key existed+ backed_up_command_files = {}++ try:+ # 1. Backup registry entry (always, even if extension dir doesn't exist)+ backup_registry_entry = manager.registry.get(extension_id)++ # 2. Backup extension directory+ extension_dir = manager.extensions_dir / extension_id+ if extension_dir.exists():+ backup_base.mkdir(parents=True, exist_ok=True)+ if backup_ext_dir.exists():+ shutil.rmtree(backup_ext_dir)+ shutil.copytree(extension_dir, backup_ext_dir)++ # Backup config files separately so they can be restored+ # after a successful install (install_from_directory clears dest dir).+ config_files = list(extension_dir.glob("*-config.yml")) + list(+ extension_dir.glob("*-config.local.yml")+ )+ for cfg_file in config_files:+ backup_config_dir.mkdir(parents=True, exist_ok=True)+ shutil.copy2(cfg_file, backup_config_dir / cfg_file.name)++ # 3. Backup command files for all agents+ registered_commands = backup_registry_entry.get("registered_commands", {})+ for agent_name, cmd_names in registered_commands.items():+ if agent_name not in registrar.AGENT_CONFIGS:+ continue+ agent_config = registrar.AGENT_CONFIGS[agent_name]+ commands_dir = project_root / agent_config["dir"]++ for cmd_name in cmd_names:+ cmd_file = commands_dir / f"{cmd_name}{agent_config['extension']}"+ if cmd_file.exists():+ backup_cmd_path = backup_commands_dir / agent_name / cmd_file.name+ backup_cmd_path.parent.mkdir(parents=True, exist_ok=True)+ shutil.copy2(cmd_file, backup_cmd_path)+ backed_up_command_files[str(cmd_file)] = str(backup_cmd_path)++ # Also backup copilot prompt files+ if agent_name == "copilot":+ prompt_file = project_root / ".github" / "prompts" / f"{cmd_name}.prompt.md"+ if prompt_file.exists():+ backup_prompt_path = backup_commands_dir / "copilot-prompts" / prompt_file.name+ backup_prompt_path.parent.mkdir(parents=True, exist_ok=True)+ shutil.copy2(prompt_file, backup_prompt_path)+ backed_up_command_files[str(prompt_file)] = str(backup_prompt_path)++ # 4. Backup hooks from extensions.yml+ # Use backup_hooks=None to indicate config had no "hooks" key (don't create on restore)+ # Use backup_hooks={} to indicate config had "hooks" key with no hooks for this extension+ config = hook_executor.get_project_config()+ if "hooks" in config:+ backup_hooks = {} # Config has hooks key - preserve this fact+ for hook_name, hook_list in config["hooks"].items():+ ext_hooks = [h for h in hook_list if h.get("extension") == extension_id]+ if ext_hooks:+ backup_hooks[hook_name] = ext_hooks++ # 5. Download new version+ zip_path = catalog.download_extension(extension_id)+ try:+ # 6. Validate extension ID from ZIP BEFORE modifying installation+ # Handle both root-level and nested extension.yml (GitHub auto-generated ZIPs)+ with zipfile.ZipFile(zip_path, "r") as zf:+ import yaml+ manifest_data = None+ namelist = zf.namelist()++ # First try root-level extension.yml+ if "extension.yml" in namelist:+ with zf.open("extension.yml") as f:+ manifest_data = yaml.safe_load(f) or {}+ else:+ # Look for extension.yml in a single top-level subdirectory+ # (e.g., "repo-name-branch/extension.yml")+ manifest_paths = [n for n in namelist if n.endswith("/extension.yml") and n.count("/") == 1]+ if len(manifest_paths) == 1:+ with zf.open(manifest_paths[0]) as f:+ manifest_data = yaml.safe_load(f) or {}++ if manifest_data is None:+ raise ValueError("Downloaded extension archive is missing 'extension.yml'")++ zip_extension_id = manifest_data.get("extension", {}).get("id")+ if zip_extension_id != extension_id:+ raise ValueError(+ f"Extension ID mismatch: expected '{extension_id}', got '{zip_extension_id}'"+ )++ # 7. Remove old extension (handles command file cleanup and registry removal)+ manager.remove(extension_id, keep_config=True)++ # 8. Install new version+ _ = manager.install_from_zip(zip_path, speckit_version)++ # Restore user config files from backup after successful install.+ new_extension_dir = manager.extensions_dir / extension_id+ if backup_config_dir.exists() and new_extension_dir.exists():+ for cfg_file in backup_config_dir.iterdir():+ if cfg_file.is_file():+ shutil.copy2(cfg_file, new_extension_dir / cfg_file.name)++ # 9. Restore metadata from backup (installed_at, enabled state)+ if backup_registry_entry:+ # Copy current registry entry to avoid mutating internal+ # registry state before explicit restore().+ current_metadata = manager.registry.get(extension_id)+ if current_metadata is None:+ raise RuntimeError(+ f"Registry entry for '{extension_id}' missing after install — update incomplete"+ )+ new_metadata = dict(current_metadata)++ # Preserve the original installation timestamp+ if "installed_at" in backup_registry_entry:+ new_metadata["installed_at"] = backup_registry_entry["installed_at"]++ # If extension was disabled before update, disable it again+ if not backup_registry_entry.get("enabled", True):+ new_metadata["enabled"] = False++ # Use restore() instead of update() because update() always+ # preserves the existing installed_at, ignoring our override+ manager.registry.restore(extension_id, new_metadata)++ # Also disable hooks in extensions.yml if extension was disabled+ if not backup_registry_entry.get("enabled", True):+ 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_id:+ hook["enabled"] = False+ hook_executor.save_project_config(config)+ finally:+ # Clean up downloaded ZIP+ if zip_path.exists():+ zip_path.unlink()++ # 10. Clean up backup on success+ if backup_base.exists():+ shutil.rmtree(backup_base)++ console.print(f" [green]✓[/green] Updated to v{update['available']}")+ updated_extensions.append(ext_name)++ except KeyboardInterrupt:+ raise+ except Exception as e:+ console.print(f" [red]✗[/red] Failed: {e}")+ failed_updates.append((ext_name, str(e)))++ # Rollback on failure+ console.print(f" [yellow]↩[/yellow] Rolling back {ext_name}...")++ try:+ # Restore extension directory+ # Only perform destructive rollback if backup exists (meaning we+ # actually modified the extension). This avoids deleting a valid+ # installation when failure happened before changes were made.+ extension_dir = manager.extensions_dir / extension_id+ if backup_ext_dir.exists():+ if extension_dir.exists():+ shutil.rmtree(extension_dir)+ shutil.copytree(backup_ext_dir, extension_dir)++ # Remove any NEW command files created by failed install+ # (files that weren't in the original backup)+ try:+ new_registry_entry = manager.registry.get(extension_id)+ if new_registry_entry is None:+ new_registered_commands = {}+ else:+ new_registered_commands = new_registry_entry.get("registered_commands", {})+ for agent_name, cmd_names in new_registered_commands.items():+ if agent_name not in registrar.AGENT_CONFIGS:+ continue+ agent_config = registrar.AGENT_CONFIGS[agent_name]+ commands_dir = project_root / agent_config["dir"]++ for cmd_name in cmd_names:+ cmd_file = commands_dir / f"{cmd_name}{agent_config['extension']}"+ # Delete if it exists and wasn't in our backup+ if cmd_file.exists() and str(cmd_file) not in backed_up_command_files:+ cmd_file.unlink()++ # Also handle copilot prompt files+ if agent_name == "copilot":+ prompt_file = project_root / ".github" / "prompts" / f"{cmd_name}.prompt.md"+ if prompt_file.exists() and str(prompt_file) not in backed_up_command_files:+ prompt_file.unlink()+ except KeyError:+ pass # No new registry entry exists, nothing to clean up++ # Restore backed up command files+ for original_path, backup_path in backed_up_command_files.items():+ backup_file = Path(backup_path)+ if backup_file.exists():+ original_file = Path(original_path)+ original_file.parent.mkdir(parents=True, exist_ok=True)+ shutil.copy2(backup_file, original_file)++ # Restore hooks in extensions.yml+ # - backup_hooks=None means original config had no "hooks" key+ # - backup_hooks={} or {...} means config had hooks key+ config = hook_executor.get_project_config()+ if "hooks" in config:+ modified = False++ if backup_hooks is None:+ # Original config had no "hooks" key; remove it entirely+ del config["hooks"]+ modified = True+ else:+ # Remove any hooks for this extension added by failed install+ for hook_name, hooks_list in config["hooks"].items():+ original_len = len(hooks_list)+ config["hooks"][hook_name] = [+ h for h in hooks_list+ if h.get("extension") != extension_id+ ]+ if len(config["hooks"][hook_name]) != original_len:+ modified = True++ # Add back the backed up hooks if any+ if backup_hooks:+ for hook_name, hooks in backup_hooks.items():+ if hook_name not in config["hooks"]:+ config["hooks"][hook_name] = []+ config["hooks"][hook_name].extend(hooks)+ modified = True++ if modified:+ hook_executor.save_project_config(config)++ # Restore registry entry (use restore() since entry was removed)+ if backup_registry_entry:+ manager.registry.restore(extension_id, backup_registry_entry)++ console.print(" [green]✓[/green] Rollback successful")+ # Clean up backup directory only on successful rollback+ if backup_base.exists():+ shutil.rmtree(backup_base)+ except Exception as rollback_error:+ console.print(f" [red]✗[/red] Rollback failed: {rollback_error}")+ console.print(f" [dim]Backup preserved at: {backup_base}[/dim]")++ # Summary+ console.print()+ if updated_extensions:+ console.print(f"[green]✓[/green] Successfully updated {len(updated_extensions)} extension(s)")+ if failed_updates:+ console.print(f"[red]✗[/red] Failed to update {len(failed_updates)} extension(s):")+ for ext_name, error in failed_updates:+ console.print(f" • {ext_name}: {error}")+ raise typer.Exit(1)+ except ValidationError as e:+ console.print(f"\n[red]Validation Error:[/red] {e}")+ raise typer.Exit(1)except ExtensionError as e:console.print(f"\n[red]Error:[/red] {e}")raise typer.Exit(1)@@ -2547,7 +3011,7 @@ def extension_update(@extension_app.command("enable")def extension_enable(- extension: str = typer.Argument(help="Extension ID to enable"),+ extension: str = typer.Argument(help="Extension ID or name to enable"),):"""Enable a disabled extension."""from .extensions import ExtensionManager, HookExecutor@@ -2564,34 +3028,38 @@ def extension_enable(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)+ # Resolve extension ID from argument (handles ambiguous names)+ installed = manager.list_installed()+ extension_id, display_name = _resolve_installed_extension(extension, installed, "enable")# Update registry- metadata = manager.registry.get(extension)+ metadata = manager.registry.get(extension_id)+ if metadata is None:+ console.print(f"[red]Error:[/red] Extension '{extension_id}' not found in registry (corrupted state)")+ raise typer.Exit(1)+if metadata.get("enabled", True):- console.print(f"[yellow]Extension '{extension}' is already enabled[/yellow]")+ console.print(f"[yellow]Extension '{display_name}' is already enabled[/yellow]")raise typer.Exit(0)metadata["enabled"] = True- manager.registry.add(extension, metadata)+ manager.registry.update(extension_id, metadata)# Enable hooks in extensions.ymlconfig = 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:+ if hook.get("extension") == extension_id:hook["enabled"] = Truehook_executor.save_project_config(config)- console.print(f"[green]✓[/green] Extension '{extension}' enabled")+ console.print(f"[green]✓[/green] Extension '{display_name}' enabled")@extension_app.command("disable")def extension_disable(- extension: str = typer.Argument(help="Extension ID to disable"),+ extension: str = typer.Argument(help="Extension ID or name to disable"),):"""Disable an extension without removing it."""from .extensions import ExtensionManager, HookExecutor@@ -2608,31 +3076,35 @@ def extension_disable(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)+ # Resolve extension ID from argument (handles ambiguous names)+ installed = manager.list_installed()+ extension_id, display_name = _resolve_installed_extension(extension, installed, "disable")# Update registry- metadata = manager.registry.get(extension)+ metadata = manager.registry.get(extension_id)+ if metadata is None:+ console.print(f"[red]Error:[/red] Extension '{extension_id}' not found in registry (corrupted state)")+ raise typer.Exit(1)+if not metadata.get("enabled", True):- console.print(f"[yellow]Extension '{extension}' is already disabled[/yellow]")+ console.print(f"[yellow]Extension '{display_name}' is already disabled[/yellow]")raise typer.Exit(0)metadata["enabled"] = False- manager.registry.add(extension, metadata)+ manager.registry.update(extension_id, metadata)# Disable hooks in extensions.ymlconfig = 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:+ if hook.get("extension") == extension_id:hook["enabled"] = Falsehook_executor.save_project_config(config)- console.print(f"[green]✓[/green] Extension '{extension}' disabled")+ console.print(f"[green]✓[/green] Extension '{display_name}' disabled")console.print("\nCommands will no longer be available. Hooks will not execute.")- console.print(f"To re-enable: specify extension enable {extension}")+ console.print(f"To re-enable: specify extension enable {extension_id}")def main():diff --git a/src/specify_cli/extensions.py b/src/specify_cli/extensions.pyindex 383ed2154..fa9766b00 100644--- a/src/specify_cli/extensions.py+++ b/src/specify_cli/extensions.py@@ -12,6 +12,7 @@ import osimport tempfileimport zipfileimport shutil+import copyfrom dataclasses import dataclassfrom pathlib import Pathfrom typing import Optional, Dict, List, Any, Callable, Set@@ -228,6 +229,54 @@ class ExtensionRegistry:}self._save()+ def update(self, extension_id: str, metadata: dict):+ """Update extension metadata in registry, merging with existing entry.++ Merges the provided metadata with the existing entry, preserving any+ fields not specified in the new metadata. The installed_at timestamp+ is always preserved from the original entry.++ Use this method instead of add() when updating existing extension+ metadata (e.g., enabling/disabling) to preserve the original+ installation timestamp and other existing fields.++ Args:+ extension_id: Extension ID+ metadata: Extension metadata fields to update (merged with existing)++ Raises:+ KeyError: If extension is not installed+ """+ if extension_id not in self.data["extensions"]:+ raise KeyError(f"Extension '{extension_id}' is not installed")+ # Merge new metadata with existing, preserving original installed_at+ existing = self.data["extensions"][extension_id]+ # Merge: existing fields preserved, new fields override+ merged = {**existing, **metadata}+ # Always preserve original installed_at based on key existence, not truthiness,+ # to handle cases where the field exists but may be falsy (legacy/corruption)+ if "installed_at" in existing:+ merged["installed_at"] = existing["installed_at"]+ else:+ # If not present in existing, explicitly remove from merged if caller provided it+ merged.pop("installed_at", None)+ self.data["extensions"][extension_id] = merged+ self._save()++ def restore(self, extension_id: str, metadata: dict):+ """Restore extension metadata to registry without modifying timestamps.++ Use this method for rollback scenarios where you have a complete backup+ of the registry entry (including installed_at) and want to restore it+ exactly as it was.++ Args:+ extension_id: Extension ID+ metadata: Complete extension metadata including installed_at+ """+ self.data["extensions"][extension_id] = dict(metadata)+ self._save()+def remove(self, extension_id: str):"""Remove extension from registry.@@ -241,21 +290,28 @@ class ExtensionRegistry:def get(self, extension_id: str) -> Optional[dict]:"""Get extension metadata from registry.+ Returns a deep copy to prevent callers from accidentally mutating+ nested internal registry state without going through the write path.+Args:extension_id: Extension IDReturns:- Extension metadata or None if not found+ Deep copy of extension metadata, or None if not found"""- return self.data["extensions"].get(extension_id)+ entry = self.data["extensions"].get(extension_id)+ return copy.deepcopy(entry) if entry is not None else Nonedef list(self) -> Dict[str, dict]:"""Get all installed extensions.+ Returns a deep copy of the extensions mapping to prevent callers+ from accidentally mutating nested internal registry state.+Returns:- Dictionary of extension_id -> metadata+ Dictionary of extension_id -> metadata (deep copies)"""- return self.data["extensions"]+ return copy.deepcopy(self.data["extensions"])def is_installed(self, extension_id: str) -> bool:"""Check if extension is installed.@@ -600,7 +656,7 @@ class ExtensionManager:result.append({"id": ext_id,"name": manifest.name,- "version": metadata["version"],+ "version": metadata.get("version", "unknown"),"description": manifest.description,"enabled": metadata.get("enabled", True),"installed_at": metadata.get("installed_at"),@@ -1112,12 +1168,13 @@ class ExtensionCatalog:config_path: Path to extension-catalogs.ymlReturns:- Ordered list of CatalogEntry objects, or None if file doesn't exist- or contains no valid catalog entries.+ Ordered list of CatalogEntry objects, or None if file doesn't exist.Raises:ValidationError: If any catalog entry has an invalid URL,- the file cannot be parsed, or a priority value is invalid.+ the file cannot be parsed, a priority value is invalid,+ or the file exists but contains no valid catalog entries+ (fail-closed for security)."""if not config_path.exists():return None@@ -1129,12 +1186,17 @@ class ExtensionCatalog:)catalogs_data = data.get("catalogs", [])if not catalogs_data:- return None+ # File exists but has no catalogs key or empty list - fail closed+ raise ValidationError(+ f"Catalog config {config_path} exists but contains no 'catalogs' entries. "+ f"Remove the file to use built-in defaults, or add valid catalog entries."+ )if not isinstance(catalogs_data, list):raise ValidationError(f"Invalid catalog config: 'catalogs' must be a list, got {type(catalogs_data).__name__}")entries: List[CatalogEntry] = []+ skipped_entries: List[int] = []for idx, item in enumerate(catalogs_data):if not isinstance(item, dict):raise ValidationError(@@ -1142,6 +1204,7 @@ class ExtensionCatalog:)url = str(item.get("url", "")).strip()if not url:+ skipped_entries.append(idx)continueself._validate_catalog_url(url)try:@@ -1164,7 +1227,14 @@ class ExtensionCatalog:description=str(item.get("description", "")),))entries.sort(key=lambda e: e.priority)- return entries if entries else None+ if not entries:+ # All entries were invalid (missing URLs) - fail closed for security+ raise ValidationError(+ f"Catalog config {config_path} contains {len(catalogs_data)} entries but none have valid URLs "+ f"(entries at indices {skipped_entries} were skipped). "+ f"Each catalog entry must have a 'url' field."+ )+ return entriesdef get_active_catalogs(self) -> List[CatalogEntry]:"""Get the ordered list of active catalogs.diff --git a/tests/test_extensions.py b/tests/test_extensions.pyindex ba52d0343..4c098c255 100644--- a/tests/test_extensions.py+++ b/tests/test_extensions.py@@ -277,6 +277,135 @@ class TestExtensionRegistry:assert registry2.is_installed("test-ext")assert registry2.get("test-ext")["version"] == "1.0.0"+ def test_update_preserves_installed_at(self, temp_dir):+ """Test that update() preserves the original installed_at timestamp."""+ extensions_dir = temp_dir / "extensions"+ extensions_dir.mkdir()++ registry = ExtensionRegistry(extensions_dir)+ registry.add("test-ext", {"version": "1.0.0", "enabled": True})++ # Get original installed_at+ original_data = registry.get("test-ext")+ original_installed_at = original_data["installed_at"]++ # Update with new metadata+ registry.update("test-ext", {"version": "2.0.0", "enabled": False})++ # Verify installed_at is preserved+ updated_data = registry.get("test-ext")+ assert updated_data["installed_at"] == original_installed_at+ assert updated_data["version"] == "2.0.0"+ assert updated_data["enabled"] is False++ def test_update_merges_with_existing(self, temp_dir):+ """Test that update() merges new metadata with existing fields."""+ extensions_dir = temp_dir / "extensions"+ extensions_dir.mkdir()++ registry = ExtensionRegistry(extensions_dir)+ registry.add("test-ext", {+ "version": "1.0.0",+ "enabled": True,+ "registered_commands": {"claude": ["cmd1", "cmd2"]},+ })++ # Update with partial metadata (only enabled field)+ registry.update("test-ext", {"enabled": False})++ # Verify existing fields are preserved+ updated_data = registry.get("test-ext")+ assert updated_data["enabled"] is False+ assert updated_data["version"] == "1.0.0" # Preserved+ assert updated_data["registered_commands"] == {"claude": ["cmd1", "cmd2"]} # Preserved++ def test_update_raises_for_missing_extension(self, temp_dir):+ """Test that update() raises KeyError for non-installed extension."""+ extensions_dir = temp_dir / "extensions"+ extensions_dir.mkdir()++ registry = ExtensionRegistry(extensions_dir)++ with pytest.raises(KeyError, match="not installed"):+ registry.update("nonexistent-ext", {"enabled": False})++ def test_restore_overwrites_completely(self, temp_dir):+ """Test that restore() overwrites the registry entry completely."""+ extensions_dir = temp_dir / "extensions"+ extensions_dir.mkdir()++ registry = ExtensionRegistry(extensions_dir)+ registry.add("test-ext", {"version": "2.0.0", "enabled": True})++ # Restore with complete backup data+ backup_data = {+ "version": "1.0.0",+ "enabled": False,+ "installed_at": "2024-01-01T00:00:00+00:00",+ "registered_commands": {"claude": ["old-cmd"]},+ }+ registry.restore("test-ext", backup_data)++ # Verify entry is exactly as restored+ restored_data = registry.get("test-ext")+ assert restored_data == backup_data++ def test_restore_can_recreate_removed_entry(self, temp_dir):+ """Test that restore() can recreate an entry after remove()."""+ extensions_dir = temp_dir / "extensions"+ extensions_dir.mkdir()++ registry = ExtensionRegistry(extensions_dir)+ registry.add("test-ext", {"version": "1.0.0"})++ # Save backup and remove+ backup = registry.get("test-ext").copy()+ registry.remove("test-ext")+ assert not registry.is_installed("test-ext")++ # Restore should recreate the entry+ registry.restore("test-ext", backup)+ assert registry.is_installed("test-ext")+ assert registry.get("test-ext")["version"] == "1.0.0"++ def test_get_returns_deep_copy(self, temp_dir):+ """Test that get() returns deep copies for nested structures."""+ extensions_dir = temp_dir / "extensions"+ extensions_dir.mkdir()++ registry = ExtensionRegistry(extensions_dir)+ metadata = {+ "version": "1.0.0",+ "registered_commands": {"claude": ["cmd1"]},+ }+ registry.add("test-ext", metadata)++ fetched = registry.get("test-ext")+ fetched["registered_commands"]["claude"].append("cmd2")++ # Internal registry must remain unchanged.+ internal = registry.data["extensions"]["test-ext"]+ assert internal["registered_commands"] == {"claude": ["cmd1"]}++ def test_list_returns_deep_copy(self, temp_dir):+ """Test that list() returns deep copies for nested structures."""+ extensions_dir = temp_dir / "extensions"+ extensions_dir.mkdir()++ registry = ExtensionRegistry(extensions_dir)+ metadata = {+ "version": "1.0.0",+ "registered_commands": {"claude": ["cmd1"]},+ }+ registry.add("test-ext", metadata)++ listed = registry.list()+ listed["test-ext"]["registered_commands"]["claude"].append("cmd2")++ # Internal registry must remain unchanged.+ internal = registry.data["extensions"]["test-ext"]+ assert internal["registered_commands"] == {"claude": ["cmd1"]}+# ===== ExtensionManager Tests =====@@ -1402,8 +1531,8 @@ class TestCatalogStack:with pytest.raises(ValidationError, match="HTTPS"):catalog.get_active_catalogs()- def test_empty_project_config_falls_back_to_defaults(self, temp_dir):- """Empty catalogs list in config falls back to default stack."""+ def test_empty_project_config_raises_error(self, temp_dir):+ """Empty catalogs list in config raises ValidationError (fail-closed for security)."""import yaml as yaml_moduleproject_dir = self._make_project(temp_dir)@@ -1412,11 +1541,32 @@ class TestCatalogStack:yaml_module.dump({"catalogs": []}, f)catalog = ExtensionCatalog(project_dir)- entries = catalog.get_active_catalogs()- # Falls back to default stack- assert len(entries) == 2- assert entries[0].url == ExtensionCatalog.DEFAULT_CATALOG_URL+ # Fail-closed: empty config should raise, not fall back to defaults+ with pytest.raises(ValidationError) as exc_info:+ catalog.get_active_catalogs()+ assert "contains no 'catalogs' entries" in str(exc_info.value)++ def test_catalog_entries_without_urls_raises_error(self, temp_dir):+ """Catalog entries without URLs raise ValidationError (fail-closed for security)."""+ import yaml as yaml_module++ project_dir = self._make_project(temp_dir)+ config_path = project_dir / ".specify" / "extension-catalogs.yml"+ with open(config_path, "w") as f:+ yaml_module.dump({+ "catalogs": [+ {"name": "no-url-catalog", "priority": 1},+ {"name": "another-no-url", "description": "Also missing URL"},+ ]+ }, f)++ catalog = ExtensionCatalog(project_dir)++ # Fail-closed: entries without URLs should raise, not fall back to defaults+ with pytest.raises(ValidationError) as exc_info:+ catalog.get_active_catalogs()+ assert "none have valid URLs" in str(exc_info.value)# --- _load_catalog_config ---@@ -1943,3 +2093,238 @@ class TestExtensionIgnore:assert not (dest / "docs" / "guide.md").exists()assert not (dest / "docs" / "internal.md").exists()assert (dest / "docs" / "api.md").exists()+++class TestExtensionAddCLI:+ """CLI integration tests for extension add command."""++ def test_add_by_display_name_uses_resolved_id_for_download(self, tmp_path):+ """extension add by display name should use resolved ID for download_extension()."""+ from typer.testing import CliRunner+ from unittest.mock import patch, MagicMock+ from specify_cli import app++ runner = CliRunner()++ # Create project structure+ project_dir = tmp_path / "test-project"+ project_dir.mkdir()+ (project_dir / ".specify").mkdir()+ (project_dir / ".specify" / "extensions").mkdir(parents=True)++ # Mock catalog that returns extension by display name+ mock_catalog = MagicMock()+ mock_catalog.get_extension_info.return_value = None # ID lookup fails+ mock_catalog.search.return_value = [+ {+ "id": "acme-jira-integration",+ "name": "Jira Integration",+ "version": "1.0.0",+ "description": "Jira integration extension",+ "_install_allowed": True,+ }+ ]++ # Track what ID was passed to download_extension+ download_called_with = []+ def mock_download(extension_id):+ download_called_with.append(extension_id)+ # Return a path that will fail install (we just want to verify the ID)+ raise ExtensionError("Mock download - checking ID was resolved")++ mock_catalog.download_extension.side_effect = mock_download++ with patch("specify_cli.extensions.ExtensionCatalog", return_value=mock_catalog), \+ patch.object(Path, "cwd", return_value=project_dir):+ result = runner.invoke(+ app,+ ["extension", "add", "Jira Integration"],+ catch_exceptions=True,+ )++ assert result.exit_code != 0, (+ f"Expected non-zero exit code since mock download raises, got {result.exit_code}"+ )++ # Verify download_extension was called with the resolved ID, not the display name+ assert len(download_called_with) == 1+ assert download_called_with[0] == "acme-jira-integration", (+ f"Expected download_extension to be called with resolved ID 'acme-jira-integration', "+ f"but was called with '{download_called_with[0]}'"+ )+++class TestExtensionUpdateCLI:+ """CLI integration tests for extension update command."""++ @staticmethod+ def _create_extension_source(base_dir: Path, version: str, include_config: bool = False) -> Path:+ """Create a minimal extension source directory for install tests."""+ import yaml++ ext_dir = base_dir / f"test-ext-{version}"+ ext_dir.mkdir(parents=True, exist_ok=True)++ manifest = {+ "schema_version": "1.0",+ "extension": {+ "id": "test-ext",+ "name": "Test Extension",+ "version": version,+ "description": "A test extension",+ },+ "requires": {"speckit_version": ">=0.1.0"},+ "provides": {+ "commands": [+ {+ "name": "speckit.test.hello",+ "file": "commands/hello.md",+ "description": "Test command",+ }+ ]+ },+ "hooks": {+ "after_tasks": {+ "command": "speckit.test.hello",+ "optional": True,+ }+ },+ }++ (ext_dir / "extension.yml").write_text(yaml.dump(manifest, sort_keys=False))+ commands_dir = ext_dir / "commands"+ commands_dir.mkdir(exist_ok=True)+ (commands_dir / "hello.md").write_text("---\ndescription: Test\n---\n\n$ARGUMENTS\n")+ if include_config:+ (ext_dir / "linear-config.yml").write_text("custom: true\nvalue: original\n")+ return ext_dir++ @staticmethod+ def _create_catalog_zip(zip_path: Path, version: str):+ """Create a minimal ZIP that passes extension_update ID validation."""+ import zipfile+ import yaml++ manifest = {+ "schema_version": "1.0",+ "extension": {+ "id": "test-ext",+ "name": "Test Extension",+ "version": version,+ "description": "A test extension",+ },+ "requires": {"speckit_version": ">=0.1.0"},+ "provides": {"commands": [{"name": "speckit.test.hello", "file": "commands/hello.md"}]},+ }++ with zipfile.ZipFile(zip_path, "w") as zf:+ zf.writestr("extension.yml", yaml.dump(manifest, sort_keys=False))++ def test_update_success_preserves_installed_at(self, tmp_path):+ """Successful update should keep original installed_at and apply new version."""+ from typer.testing import CliRunner+ from unittest.mock import patch+ from specify_cli import app++ runner = CliRunner()+ project_dir = tmp_path / "project"+ project_dir.mkdir()+ (project_dir / ".specify").mkdir()+ (project_dir / ".claude" / "commands").mkdir(parents=True)++ manager = ExtensionManager(project_dir)+ v1_dir = self._create_extension_source(tmp_path, "1.0.0", include_config=True)+ manager.install_from_directory(v1_dir, "0.1.0")+ original_installed_at = manager.registry.get("test-ext")["installed_at"]+ original_config_content = (+ project_dir / ".specify" / "extensions" / "test-ext" / "linear-config.yml"+ ).read_text()++ zip_path = tmp_path / "test-ext-update.zip"+ self._create_catalog_zip(zip_path, "2.0.0")+ v2_dir = self._create_extension_source(tmp_path, "2.0.0")++ def fake_install_from_zip(self_obj, _zip_path, speckit_version):+ return self_obj.install_from_directory(v2_dir, speckit_version)++ with patch.object(Path, "cwd", return_value=project_dir), \+ patch.object(ExtensionCatalog, "get_extension_info", return_value={+ "id": "test-ext",+ "name": "Test Extension",+ "version": "2.0.0",+ "_install_allowed": True,+ }), \+ patch.object(ExtensionCatalog, "download_extension", return_value=zip_path), \+ patch.object(ExtensionManager, "install_from_zip", fake_install_from_zip):+ result = runner.invoke(app, ["extension", "update", "test-ext"], input="y\n", catch_exceptions=True)++ assert result.exit_code == 0, result.output++ updated = ExtensionManager(project_dir).registry.get("test-ext")+ assert updated["version"] == "2.0.0"+ assert updated["installed_at"] == original_installed_at+ restored_config_content = (+ project_dir / ".specify" / "extensions" / "test-ext" / "linear-config.yml"+ ).read_text()+ assert restored_config_content == original_config_content++ def test_update_failure_rolls_back_registry_hooks_and_commands(self, tmp_path):+ """Failed update should restore original registry, hooks, and command files."""+ from typer.testing import CliRunner+ from unittest.mock import patch+ from specify_cli import app+ import yaml++ runner = CliRunner()+ project_dir = tmp_path / "project"+ project_dir.mkdir()+ (project_dir / ".specify").mkdir()+ (project_dir / ".claude" / "commands").mkdir(parents=True)++ manager = ExtensionManager(project_dir)+ v1_dir = self._create_extension_source(tmp_path, "1.0.0")+ manager.install_from_directory(v1_dir, "0.1.0")++ backup_registry_entry = manager.registry.get("test-ext")+ hooks_before = yaml.safe_load((project_dir / ".specify" / "extensions.yml").read_text())++ registered_commands = backup_registry_entry.get("registered_commands", {})+ command_files = []+ registrar = CommandRegistrar()+ for agent_name, cmd_names in registered_commands.items():+ if agent_name not in registrar.AGENT_CONFIGS:+ continue+ agent_cfg = registrar.AGENT_CONFIGS[agent_name]+ commands_dir = project_dir / agent_cfg["dir"]+ for cmd_name in cmd_names:+ cmd_path = commands_dir / f"{cmd_name}{agent_cfg['extension']}"+ command_files.append(cmd_path)++ assert command_files, "Expected at least one registered command file"+ for cmd_file in command_files:+ assert cmd_file.exists(), f"Expected command file to exist before update: {cmd_file}"++ zip_path = tmp_path / "test-ext-update.zip"+ self._create_catalog_zip(zip_path, "2.0.0")++ with patch.object(Path, "cwd", return_value=project_dir), \+ patch.object(ExtensionCatalog, "get_extension_info", return_value={+ "id": "test-ext",+ "name": "Test Extension",+ "version": "2.0.0",+ "_install_allowed": True,+ }), \+ patch.object(ExtensionCatalog, "download_extension", return_value=zip_path), \+ patch.object(ExtensionManager, "install_from_zip", side_effect=RuntimeError("install failed")):+ result = runner.invoke(app, ["extension", "update", "test-ext"], input="y\n", catch_exceptions=True)++ assert result.exit_code == 1, result.output++ restored_entry = ExtensionManager(project_dir).registry.get("test-ext")+ assert restored_entry == backup_registry_entry++ hooks_after = yaml.safe_load((project_dir / ".specify" / "extensions.yml").read_text())+ assert hooks_after == hooks_before++ for cmd_file in command_files:+ assert cmd_file.exists(), f"Expected command file to be restored after rollback: {cmd_file}"