feat: add catalog discovery CLI commands

[Adr1an04]

This PR Closes #2344.

Summary

This PR adds integration catalog discovery and catalog-source management commands for the Specify CLI.

It introduces:

• specify integration search [query] [--tag T] [--author A]
• specify integration info <id>
• specify integration catalog list
• specify integration catalog add <url> [--name N]
• specify integration catalog remove <index>

The implementation follows the existing workflow catalog CLI shape while keeping integration behavior separate from workflows/extensions/presets. Integrations remain single-active through the existing install, uninstall, switch, and upgrade commands.

What changed

• Added integration catalog search and info commands.
• Added project-level integration catalog source management.
• Added IntegrationCatalog.get_catalog_configs(), add_catalog(), and remove_catalog().
• Added CLI coverage for search, info, catalog list/add/remove, and project guards.
• Added unit coverage for catalog source management.

Final-entry removal behavior

A review pass caught that removing the final project catalog entry could leave this file behind:

catalogs: []

That would cause later integration commands to fail, because _load_catalog_config() rejects an existing config file with no catalog entries.

This PR now handles that case by deleting:

.specify/integration-catalogs.yml

If catalog entries remain after removal, the file is written normally. If no entries remain, the file is removed and the project falls back to the built-in default catalogs.

What did not change

• No specify integration add, remove, enable, disable, or set-priority commands were added.
• Existing specify integration list, install, uninstall, switch, and upgrade behavior was not refactored.
• _load_catalog_config() validation was not relaxed.
• Workflow, extension, and preset catalog behavior was not changed.
• catalog remove <index> remains 0-based, matching the issue request and the existing workflow catalog command shape.
• catalog add writes project-level config only. It does not add user/global catalog management.

Test selection reasoning

Changed file	Affects	Test	Why
src/specify_cli/__init__.py	New integration CLI commands	T1, T2, T4	Registers and handles integration search, info, and catalog list/add/remove
src/specify_cli/integrations/catalog.py	Integration catalog source management	T1, T2, T4	Adds catalog config list/add/remove behavior and final-entry deletion
tests/integrations/test_cli.py	CLI regression coverage	T1, T2, T4	Covers the new Typer commands and project guard behavior
tests/integrations/test_integration_catalog.py	Library regression coverage	T1, T2, T4	Covers catalog source management, validation, and built-in fallback behavior

Required tests

• T1: focused integration catalog library and CLI regression tests
• T2: full integration test suite
• T3: agent config consistency test
• T4: full pytest suite
• T5: whitespace diff check

Testing

I ran the focused catalog/CLI regression tests, the full integration suite, agent config consistency, the full pytest suite, and a whitespace diff check from native PowerShell on Windows.

git branch --show-current
# feat/2344-integration-catalog-cli

git status --short
# no output

git log --oneline -3
# 049ab8e feat: add catalog discovery CLI commands
# aad7b16 Add Spec Orchestrator extension to community catalog (#2350)
# 6cec171 chore: release 0.8.1, begin 0.8.2.dev0 development (#2356)

python -m pytest tests/integrations/test_integration_catalog.py tests/integrations/test_cli.py -v
# 90 passed in 4.61s

python -m pytest tests/integrations -q
# 941 passed in 52.14s

python -m pytest tests/test_agent_config_consistency.py -q
# 24 passed in 0.14s

python -m pytest -q
# 1629 passed, 125 skipped, 18 warnings in 60.71s

git diff --check
# no output

Command-level validation covered by tests

The automated CLI tests cover:

• Running specify integration search in a spec-kit project.
• Filtering search results by --tag.
• Filtering search results by --author.
• Showing a friendly no-results hint.
• Marking discovery-only catalog entries as not directly installable.
• Running specify integration info for catalog entries.
• Falling back to built-in integration info when a built-in integration is not present in the catalog.
• Listing built-in default catalog sources.
• Adding a project-level catalog source.
• Rejecting invalid non-HTTPS catalog URLs.
• Rejecting duplicate catalog URLs.
• Removing a catalog source by 0-based index.
• Rejecting out-of-range catalog indexes.
• Rejecting removal when no project catalog config exists.
• Removing the final catalog entry and restoring built-in defaults.

Final-entry regression validation

The focused tests include both library-level and CLI-level coverage for the final-entry removal bug:

• Unit coverage verifies remove_catalog(0) deletes .specify/integration-catalogs.yml when removing the only catalog entry.
• Unit coverage verifies subsequent get_active_catalogs() returns the built-in default and community catalogs.
• CLI coverage verifies catalog add followed by catalog remove 0 deletes the config file.
• CLI coverage verifies a follow-up integration catalog list succeeds and shows the built-in defaults.

AI disclosure

I used ChatGPT/Cursor as a coding and review assistant while working on this PR. I implemented and reviewed the final changes myself, and used the tools to help investigate the issue, draft parts of the tests, and polish the PR description. I also ran the validation commands and verified the final diff and test results before submitting this PR.

[Copilot]

Pull request overview

Adds first-class integration catalog discovery and project-level catalog source management to the Specify CLI, aligning integrations with the existing catalog UX used by workflows/extensions while keeping integration install/switch behavior unchanged.

Changes:

• Introduces specify integration search and specify integration info for catalog-based discovery.
• Adds specify integration catalog list/add/remove for project-scoped catalog source management.
• Adds integration catalog source management APIs (get_catalog_configs, add_catalog, remove_catalog) with new unit + CLI tests.

Reviewed changes

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

File	Description
src/specify_cli/__init__.py	Registers new integration search/info and integration catalog ... Typer commands and project guard.
src/specify_cli/integrations/catalog.py	Adds catalog source management API and a validation error type; handles deleting config on final-entry removal.
tests/integrations/test_cli.py	Adds end-to-end CLI coverage for search/info/catalog list/add/remove flows and project guard behavior.
tests/integrations/test_integration_catalog.py	Adds unit coverage for catalog source stack, add/remove behavior, and final-entry deletion fallback.

---

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

[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.

[Copilot]

Pull request overview

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

---

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

[Copilot]

Pull request overview

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

---

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

[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.

[Copilot]

Pull request overview

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

---

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

[Copilot]

Pull request overview

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

---

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

[Copilot]

Pull request overview

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

---

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

[Copilot]

Pull request overview

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

---

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

[Copilot]

Pull request overview

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

---

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

[Copilot]

Pull request overview

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

---

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

[Copilot]

Pull request overview

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

---

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

[Adr1an04]

I rebased this branch onto the latest from main to keep it current and easier to review and merge @mnriem. I also fixed the latest Copilot comments that came about catalog source display and fallback names, and the newest.

For validation, I ran the integration catalog tests, CLI tests, focused catalog and CLI combined tests, the full integration suite, tests/test_agent_config_consistency.py -q, and the full pytest suite. I also manually tested and looked for any additional edge cases. Everything passed, let me know if you want me to update anything else.

I'll be on the lookout if copilot makes more comments on your run

[mnriem]

Thank you! So cool :)