generate integrations reference from catalog by DyanGalih · Pull Request #2563 · github/spec-kit

DyanGalih · 2026-05-14T16:35:31Z

What changed

Added a small generator for the integrations reference table, backed by INTEGRATION_REGISTRY plus per-key URL and notes maps in catalog_docs.py.
Added a community_catalog_docs.py helper module and matching tests for the community extensions reference table so the documentation-generation work covers both built-in integrations and community extensions.
Updated docs/reference/integrations.md so the supported agent table is generated from the integration registry (not hand-maintained).
Added a regression test that compares the normalized rows in docs/reference/integrations.md against render_integrations_table() output so content drift is caught without relying on formatting details.

Why

The integrations reference had been hand-maintained, which made it easy for the docs to drift from the runtime registry. This change makes the doc a checked artifact and reduces maintenance overhead.

User impact

Maintainers can update the integration registry and regenerate the docs with specify integration search --markdown.
The community extensions docs are rendered through the same documentation-generation flow, which keeps the two tables aligned.
Readers get a more reliable integrations reference with less chance of stale entries.

Validation

specify integration search --markdown
pytest tests/test_catalog_docs.py -q
pytest tests/test_community_catalog_docs.py -q

Copilot

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds catalog-backed generation and validation for the integrations reference documentation, along with a CLI script and tests to keep the generated markdown in sync.

Changes:

Introduce specify_cli.catalog_docs helpers to render/update the generated integrations table from integrations/catalog.json.
Add scripts/generate_integrations_reference.py with --check/--write modes for CI and local updates.
Regenerate docs/reference/integrations.md with generated-table markers and add tests to enforce consistency.

Reviewed changes

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

File	Description
tests/test_catalog_docs.py	Adds tests asserting the committed docs match the generator and that registry metadata is reflected.
src/specify_cli/catalog_docs.py	Implements catalog loading, table rendering, and marker-based replacement for the docs page.
scripts/generate_integrations_reference.py	Provides a CLI entrypoint to check or rewrite the generated integrations reference file.
docs/reference/integrations.md	Converts the integrations table into a generated block and updates surrounding instructions.

💡 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 6 comments.

mnriem

Love it, but can we integrate it into specify integration search --markdown? Specifically can we keep it simpler than this and just render out the table. On the project end we will take care of integrating it into the docs. I do not want to burden the CLI with that part of the process

DyanGalih · 2026-05-14T22:10:58Z

Thanks for the direction! I've refactored based on your feedback:

What changed:

Removed scripts/generate_integrations_reference.py (standalone script gone)
Stripped all doc-injection machinery from catalog_docs.py — it now only contains the table-rendering helpers (list_integrations_for_docs, render_integrations_table)
Wired render_integrations_table() into the existing specify integration search --markdown flag — it now outputs the rich Agent/Key/Notes table (with proper column alignment and pipe/CR escaping) instead of the old simple Name/ID/Version/Description/Author table
Removed the HTML marker comments from docs/reference/integrations.md and updated the note to reference specify integration search --markdown
Simplified tests/test_catalog_docs.py to just verify table rendering and registry metadata — no subprocess or doc-path tests

Usage:

specify integration search --markdown

Prints the full integrations reference table to stdout. The docs team can paste it wherever needed.

Copilot

Pull request overview

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

Copilot

Copilot's findings

Files reviewed: 4/4 changed files
Comments generated: 3

mnriem

Please address Copilot feedback. Please revert the change to integrations.md as we will setup a separate GitHub actions job for that. Thanks for the great work

Copilot

Pull request overview

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

DyanGalih · 2026-05-15T14:03:18Z

Done! Both tasks completed:\n\n- Copilot feedback addressed — all review threads from the latest rounds have been fixed and replied to (removed dead INTEGRATIONS_REFERENCE_PATH constant, dropped URL-length padding from table renderer, updated integration_search docstring to reflect dual behavior, removed unreachable FileNotFoundError from the except clause, fixed naming from "catalog-backed" to registry-backed, updated PR description validation steps).\n- docs/reference/integrations.md reverted — restored to the upstream/main state and the in-process sync test was removed from the pytest suite (the GH Actions job will handle that check separately)."

Copilot

Pull request overview

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

Copilot

Pull request overview

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

Copilot

Pull request overview

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

Copilot

Pull request overview

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

Copilot

Pull request overview

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

…cell rendering, fix table parser for escaped pipes

…t_markdown_table for escaped pipes, guard community tests with skip

… escape integration URLs

…tions in list

…to prevent double-escaping

… ExitStack, update warning message

…r message, validate test rows, prevent double newline

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Tighten the integrations docs rendering helpers and tests to cover the remaining Copilot feedback from PR github#2563: shared repo-root lookup, safer markdown link text, whitespace repository handling, narrower error handling, and missing-file/test parsing guards. Tests: pytest tests/test_catalog_docs.py tests/test_community_catalog_docs.py -q; python3 -m compileall -q src/specify_cli/__init__.py src/specify_cli/catalog_docs.py src/specify_cli/community_catalog_docs.py tests/test_catalog_docs.py tests/test_community_catalog_docs.py Reference: PR github#2563; reply comment github#2563 (comment)

Normalize community tag rendering for multiline values and simplify the docs warnings import. Tests: pytest tests/test_catalog_docs.py tests/test_community_catalog_docs.py -q Reference: PR 2563 feedback

Assisted-by: GitHub Copilot (model: GPT-5, autonomous)

DyanGalih · 2026-07-07T22:17:16Z

Posted on behalf of the branch author by OpenAI Codex (GPT-5).

I addressed the remaining catalog_docs.py review nudge in commit 224f865 by adding trailing commas to both warnings.warn(...) calls. The branch is pushed and ready for review.

I did not resolve review threads from the CLI. If any conversation still appears open in GitHub after you verify the diff, it should now be safe to resolve manually.

Copilot

Pull request overview

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

+@integration_app.command("list")
+def integration_list(
+    catalog: bool = typer.Option(False, "--catalog", help="Browse full catalog (built-in + community)"),
+):
+    """List available integrations and installed status."""
+    from .integrations import INTEGRATION_REGISTRY


+def _update_init_options_for_integration(
+    project_root: Path,
+    integration: Any,
+    script_type: str | None = None,
+) -> None:
+    """Update ``init-options.json`` to reflect *integration* as the active one."""
+    from .integrations.base import SkillsIntegration
+    opts = load_init_options(project_root)
+    opts["integration"] = integration.key
+    opts["ai"] = integration.key
+    opts["context_file"] = integration.context_file
+    if script_type:
+        opts["script"] = script_type
+    if isinstance(integration, SkillsIntegration) or getattr(integration, "_skills_mode", False):
+        opts["ai_skills"] = True
+    else:
+        opts.pop("ai_skills", None)
+    save_init_options(project_root, opts)


+    # Remove managed context section from the agent context file
+    if integration:
+        integration.remove_context_section(project_root)
+


+            removed, skipped = old_manifest.uninstall(project_root, force=force)
+            current_integration.remove_context_section(project_root)
+            if removed:


+| [Goose](https://block.github.io/goose/)                                              | `goose`          | Uses YAML recipe format in `.goose/recipes/`                                                                                              |
 | [IBM Bob](https://www.ibm.com/products/bob)                                          | `bob`            | IDE-based agent                                                                                                                           |
+| [iFlow CLI](https://docs.iflow.cn/en/cli/quickstart)                                 | `iflow`          |                                                                                                                                           |
 | [Junie](https://junie.jetbrains.com/)                                                | `junie`          |                                                                                                                                           |
 | [Kilo Code](https://github.com/Kilo-Org/kilocode)                                    | `kilocode`       |                                                                                                                                           |


Assisted-by: GitHub Copilot (model: GPT-5, autonomous)

Copilot

Pull request overview

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

+    for key, integration in registry.items():
+        config = getattr(integration, "config", {})
+        if not isinstance(config, dict):
+            config = {}
+        label = INTEGRATION_LABEL_OVERRIDES.get(key, str(config.get("name") or key))
+        url = INTEGRATION_DOC_URLS.get(key)  # None if not in map
+        notes = INTEGRATION_NOTES.get(key, "")


+
+    Escapes `)` and `|` which can terminate or corrupt the link destination.
+    """
+    return url.replace(")", "\\)").replace("|", "\\|")


 # ===== Integration Commands =====

 # Moved to integrations/_commands.py — registered here to preserve CLI surface.
 from .integrations._commands import register as _register_integration_cmds  # noqa: E402
 _register_integration_cmds(app)

 # Re-export selected helpers to preserve the public import surface.
 from .integrations._helpers import (  # noqa: E402
    _clear_init_options_for_integration as _clear_init_options_for_integration,
+    _cli_error_detail as _cli_error_detail,
+    _cli_phase_label as _cli_phase_label,
+    _get_speckit_version as _get_speckit_version,
+    _MANIFEST_READ_ERRORS as _MANIFEST_READ_ERRORS,
+    _parse_integration_options as _parse_integration_options,
+    _read_integration_json as _read_integration_json,
+    _refresh_init_options_speckit_version as _refresh_init_options_speckit_version,
+    _register_extensions_for_agent as _register_extensions_for_agent,
+    _remove_integration_json as _remove_integration_json,
+    _resolve_integration_options as _resolve_integration_options,
+    _resolve_integration_script_type as _resolve_integration_script_type,
+    _resolve_script_type as _resolve_script_type,
+    _set_default_integration as _set_default_integration,
+    _set_default_integration_or_exit as _set_default_integration_or_exit,
+    _SharedTemplateRefreshError as _SharedTemplateRefreshError,
+    _unregister_extensions_for_agent as _unregister_extensions_for_agent,
    _update_init_options_for_integration as _update_init_options_for_integration,
+    _write_integration_json as _write_integration_json,
 )
 from ._project import _resolve_init_dir_override as _resolve_init_dir_override  # noqa: E402
+from .integration_runtime import (  # noqa: E402
+    invoke_separator_for_integration as _invoke_separator_for_integration,
+    with_integration_setting as _with_integration_setting,
+)
+from .integration_state import (  # noqa: E402
+    dedupe_integration_keys as _dedupe_integration_keys,
+    default_integration_key as _default_integration_key,
+    installed_integration_keys as _installed_integration_keys,
+    integration_settings as _integration_settings,
+)
+
+
+integration_app = typer.Typer(
+    name="integration",
+    help="Manage coding agent integrations",
+    add_completion=False,
+)
+integration_catalog_app = typer.Typer(
+    name="catalog",
+    help="Manage integration catalog sources",
+    add_completion=False,
+)


mnriem · 2026-07-08T11:32:06Z

Please address Copilot feedback

Copilot AI review requested due to automatic review settings May 14, 2026 16:35

DyanGalih marked this pull request as ready for review May 14, 2026 16:36

DyanGalih requested a review from mnriem as a code owner May 14, 2026 16:36

Copilot AI reviewed May 14, 2026

View reviewed changes

Comment thread src/specify_cli/catalog_docs.py Outdated

Comment thread src/specify_cli/catalog_docs.py Outdated

Comment thread src/specify_cli/catalog_docs.py Outdated

Comment thread scripts/generate_integrations_reference.py Outdated

Comment thread tests/test_catalog_docs.py Outdated

DyanGalih changed the title ~~[codex] generate integrations reference from catalog~~ generate integrations reference from catalog May 14, 2026

DyanGalih requested a review from Copilot May 14, 2026 16:53

Copilot AI reviewed May 14, 2026

View reviewed changes

mnriem requested changes May 14, 2026

View reviewed changes

DyanGalih requested review from Copilot and mnriem May 14, 2026 22:49

DyanGalih force-pushed the 002-generate-integrations-docs branch from 1bdc359 to 59c134c Compare May 14, 2026 23:07

Copilot AI reviewed May 14, 2026

View reviewed changes

Comment thread src/specify_cli/__init__.py Outdated

Comment thread docs/reference/integrations.md Outdated

Comment thread src/specify_cli/catalog_docs.py Outdated

Comment thread tests/test_catalog_docs.py Outdated

Comment thread tests/test_catalog_docs.py Outdated

mnriem requested a review from Copilot May 15, 2026 12:50

Copilot started reviewing on behalf of mnriem May 15, 2026 12:51 View session