feat(extensions): Quality of life improvements for RFC-aligned catalog integration

[mbachorik]

Quality of life comprehensive improvements for RFC-aligned catalog integration with version comparison and enhanced verbose output.

Changes

Original Features

• Extension commands accept both ID and display name
• List: --available, --all, --verbose flags with rich metadata
• Info: version comparison installed vs catalog
• Documentation updates

Bugfixes (follow-up commits)

• Automatic extension updates: Implement download → remove → install flow with confirmation
• Atomic backup/restore: Full rollback on failed updates (extension dir, command files, hooks, registry)
• Config preservation: User config files preserved during updates
• Registry restoration: Preserve installed_at timestamp on rollback and enable/disable
• Always backup registry: Backup registry metadata even when extension directory is missing
• Extension ID verification: Verify downloaded ZIP contains expected extension ID (security)
• Better error handling: Catch ExtensionError explicitly, let KeyboardInterrupt propagate
• Graceful failure handling: Per-extension update loop catches all exceptions
• Catalog warnings: Show warning in verbose mode when catalog is unavailable
• Catalog cache invalidation: Invalidate cache when SPECKIT_CATALOG_URL changes
• Consistent UX: Use resolved display names in enable/disable/update output
• UX messages: Distinguish "catalog unavailable" from "not in catalog"
• Dead code removal: Remove unreachable conditional in error path

All Reviewer Feedback Addressed ✅

• Catalog error fallback for installed extensions
• UX message clarity (catalog unavailable vs not found)
• Dead code removed
• Exception handling narrowed (ExtensionError, KeyboardInterrupt)
• enable/disable preserves installed_at
• Registry rollback preserves installed_at
• Rollback completeness (command files, hooks, extensions.yml)
• Cache invalidation on URL change
• Non-ExtensionError handling in update loop
• Always backup registry (even without directory)
• Extension ID mismatch detection (security)

Test Coverage

• 68 tests pass (23 new tests added)
• Covers: updates, backup/restore, config preservation, error handling, cache invalidation

---

Authored with GitHub Copilot and Claude

[Copilot]

Pull request overview

This PR enhances the Spec Kit extension CLI UX around RFC-aligned catalog integration by improving extension identification (ID vs display name), adding richer listing/info output, and documenting the new flags/behaviors.

Changes:

• Added --verbose support to specify extension list (IDs + extra metadata, plus update-available hints).
• Enhanced specify extension info with version comparison (installed vs catalog) and a new --verbose mode.
• Updated extension docs to describe verbose output and “ID or name” arguments across commands.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 6 comments.

File	Description
src/specify_cli/__init__.py	Adds verbose flags, richer extension list/info output, and resolves extensions by ID or display name in multiple commands.
extensions/EXTENSION-USER-GUIDE.md	Documents verbose list/info usage and removing by display name.
extensions/EXTENSION-API-REFERENCE.md	Updates CLI reference for --verbose and “ID or name” arguments.

Comments suppressed due to low confidence (1)

src/specify_cli/init.py:2342

• extension_info() now returns/raises in all branches above, but a large block of the previous implementation remains after the final raise typer.Exit(1). This code is unreachable and duplicates output logic, which makes future edits error-prone; it should be deleted to avoid confusion and accidental drift.

        # Case 3: Extension not found anywhere
        console.print(f"[red]Error:[/red] Extension '{extension}' not found in catalog or installed locally")
        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()

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 6 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

src/specify_cli/init.py:2612

• extension_enable resolves extension_id but some user-facing messages still interpolate the original extension argument (which may be a display name). This can produce confusing output (e.g., reporting "already enabled" / "enabled" for a string that isn't the canonical ID). Prefer printing the resolved ID and/or the extension's display name from the manifest for consistency with the actual target being modified.

    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_id, 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_id:
                    hook["enabled"] = True
        hook_executor.save_project_config(config)

    console.print(f"[green]✓[/green] Extension '{extension}' enabled")

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 4 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 5 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

[Copilot]

catalog.download_extension() can raise after partially creating/writing the ZIP (e.g., IOError while saving). In that case zip_path is never returned here, so this command can’t clean up the partial file and may leave corrupt ZIPs in the downloads/cache dir. Consider making download_extension() responsible for deleting any partially-written file on exceptions, or downloading into a temp file/dir that is always cleaned up.

[Copilot]

install_from_directory() preserves existing *-config.yml files by reading/writing their contents. That rewrites the files and can lose permissions/ownership/mtime (e.g., turning a 0600 secrets file into default permissions) and can also fail on non-UTF8 content. Prefer preserving configs by copying the files themselves (e.g., shutil.copy2 to a temp dir and back, or capturing/restoring stat/mode) instead of read_text()/write_text().

Suggested change

	config_files = list(dest_dir.glob("*-config.yml")) + list(
	dest_dir.glob("*-config.local.yml")
	)
	for config_file in config_files:
	preserved_configs[config_file.name] = config_file.read_text()
	shutil.rmtree(dest_dir)
	shutil.copytree(source_dir, dest_dir)
	# Restore preserved config files (overwrite new defaults with user's config)
	for config_name, config_content in preserved_configs.items():
	config_path = dest_dir / config_name
	config_path.write_text(config_content)
	with tempfile.TemporaryDirectory() as tmpdir:
	tmpdir_path = Path(tmpdir)
	config_files = list(dest_dir.glob("*-config.yml")) + list(
	dest_dir.glob("*-config.local.yml")
	)
	for config_file in config_files:
	backup_path = tmpdir_path / config_file.name
	shutil.copy2(config_file, backup_path)
	preserved_configs[config_file.name] = backup_path
	shutil.rmtree(dest_dir)
	shutil.copytree(source_dir, dest_dir)
	# Restore preserved config files (overwrite new defaults with user's config)
	for config_name, backup_path in preserved_configs.items():
	config_path = dest_dir / config_name
	shutil.copy2(backup_path, config_path)
	else:
	shutil.copytree(source_dir, dest_dir)

[mnriem]

@mbachorik I have #1707 in flight and once that lands can you see if anything needs to change for this?

[mbachorik]

@mnriem definitely. i'll keep an eye on #1707