feat(integration): add status reporting by PascalThuet · Pull Request #2674 · github/spec-kit

PascalThuet · 2026-05-22T07:20:17Z

Summary

add specify integration status for read-only integration status reporting
report default/installed integrations, multi-install safety, manifest health, and missing/modified managed files
document the command and cover healthy/unhealthy status cases

Closes #2671

Maintainer feedback

Renamed the originally proposed integration doctor command to integration status after maintainer feedback in [Feature]: Add specify integration status reporting command #2671.

Review feedback

Removed the private manifest hash helper import by hashing locally in the status module.
Reused a single integration.json read for raw and normalized state.
Avoided repeated project-root resolution during manifest file checks.
Added JSON coverage for warning/error status branches.
Documented exit-code semantics for CI/agent consumers.
Rejected unsafe integration keys before constructing manifest paths.
Escaped project-controlled values before rendering Rich status output.
Rejected filename-invalid and Windows-reserved manifest keys.
Kept reported installed integrations aligned with the raw state used for manifest checks.
Replaced managed-file exists() prechecks with explicit lstat/stat handling.
Avoided impossible integration upgrade <unknown> suggestions for stale unknown integrations.
Clarified raw recorded vs effective installed integrations in JSON status output.
Kept manifest checks on the effective default when the raw installed list is empty.
Documented the raw integration-state reader contract.
Reused initialized status-test project templates to avoid rerunning full init for each status case.
Reported multi-install safety as unknown when integration state is missing, unreadable, or records no installed integrations.
Ignored non-list raw installed_integrations values when deriving raw status checks.
Reported actual manifest load/check attempts, including shared speckit, in JSON status output.
Included integration-state read error details in status findings.
Tightened JSON contract invariants for raw recorded integrations and unknown multi-install safety.
Hardened status checks around symlink loops, symlink targets outside the project, and stale unknown integration suggestions.
Clarified project-root resolution fallback, tracked symlink classification, and multi-install remediation messaging.
Added regression coverage that manifest loads do not depend on Path.exists() and tracked symlinks are not followed with Path.stat().

Testing

uv run --extra test pytest tests/integrations/test_integration_subcommand.py::TestIntegrationStatus -q - 36 passed
uv run --extra test pytest tests/integrations/test_integration_subcommand.py tests/integrations/test_manifest.py -q - 124 passed
uvx ruff check src/specify_cli/integration_state.py src/specify_cli/integration_status.py src/specify_cli/__init__.py tests/integrations/test_integration_subcommand.py
git diff --check

AI Disclosure

I did not use AI assistance
I did use AI assistance

Used OpenAI Codex to inspect the integration state/manifest helpers, implement the status reporting command, add tests/docs, address maintainer and review feedback, run validation, and draft this PR.

Copilot

Pull request overview

Note

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

Adds a new specify integration doctor subcommand to provide read-only diagnostics of a project’s integration state, with both human-readable and JSON outputs.

Changes:

Introduces integration_doctor.py to compute a structured health report (findings, manifest checks, multi-install safety).
Adds CLI wiring + formatted console/JSON output for specify integration doctor.
Adds integration tests and reference docs for the new command.

Reviewed changes

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

File	Description
tests/integrations/test_integration_subcommand.py	Adds integration tests covering `integration doctor` success and failure modes.
src/specify_cli/integration_doctor.py	Implements the diagnostic report generation and manifest/state validation logic.
src/specify_cli/init.py	Adds the `integration doctor` Typer command and report printing/JSON emission.
docs/reference/integrations.md	Documents usage and expected outputs for `integration doctor`.

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

Copilot

Pull request overview

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

Copilot

Pull request overview

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

Copilot

Copilot's findings

Files reviewed: 5/5 changed files
Comments generated: 2

mnriem

Please address Copilot feedback. If not applicable, please explain why

Copilot

Copilot's findings

Files reviewed: 5/5 changed files
Comments generated: 2

mnriem · 2026-05-27T16:19:16Z

Please address Copilot feedback

Copilot

Pull request overview

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

Copilot

Copilot's findings

Files reviewed: 5/5 changed files
Comments generated: 2

mnriem · 2026-05-28T13:59:35Z

Please address Copilot feedback

Copilot

Pull request overview

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

Copilot

Copilot's findings

Files reviewed: 5/5 changed files
Comments generated: 2

Copilot

Copilot's findings

Files reviewed: 6/6 changed files
Comments generated: 1

mnriem · 2026-06-03T21:37:25Z

Please address Copilot feedback

Copilot

Copilot's findings

Files reviewed: 6/6 changed files
Comments generated: 0 new

Copilot

Copilot's findings

Files reviewed: 6/6 changed files
Comments generated: 0 new

mnriem

Please test & lint errors

Copilot

Copilot's findings

Files reviewed: 6/6 changed files
Comments generated: 1

…ainment On Windows, os.readlink() (and sometimes Path.resolve()) return paths with the \\?\ extended-length prefix. Comparing such a target against a plain project root via Path.relative_to() spuriously fails, so an in-project dangling symlink was classified as `invalid` instead of `missing` — failing test_status_treats_dangling_symlink_as_missing and the windows-style variant on the Windows CI runners. Centralize the containment check in _is_within_project() and strip the \\?\ / \\?\UNC\ prefix from both sides before relative_to(). Add portable regression tests for the prefix-stripping helper and the containment contract. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

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

A three-way merge / rebase onto main silently dropped the module-level `import pytest` from test_integration_subcommand.py: main reorganized the import block without it (using only a local `import pytest as _pytest`), while this branch added top-level fixtures and `pytest.skip`/`pytest.raises` usage. The overlapping import-hunk edits resolved by dropping the import, breaking collection with `NameError: name 'pytest' is not defined` on every runner. Re-add the import in the third-party group. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

`test_strip_extended_length_prefix_normalizes_windows_paths` compared the str() form of the helper's output against a hand-built string. On Windows, pathlib renders a UNC root with a trailing separator (`\\server\share\`), so the exact string match failed there (`\\server\share\` != `\\server\share`) even though `_strip_extended_length_prefix` behaves correctly — the trailing separator is irrelevant to the `relative_to` containment check it feeds. Compare Path objects (semantic equality) instead of exact strings so the assertion holds on both POSIX and Windows. No production code change needed. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

The fallback `_manifest_suggestion` for the shared `speckit` manifest (used when no usable default integration is recorded) suggested `specify init --here --force`, which can trigger interactive integration selection. For CI/agent consumers of `integration status`, surface an explicit `--integration <key>` placeholder, matching the file's existing `<key>` suggestion style. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Copilot

Copilot's findings

Files reviewed: 6/6 changed files
Comments generated: 0 new

mnriem · 2026-06-09T12:20:57Z

Thank you!

Copilot AI review requested due to automatic review settings May 22, 2026 07:20

Copilot AI reviewed May 22, 2026

View reviewed changes

PascalThuet marked this pull request as ready for review May 22, 2026 08:14

PascalThuet requested a review from mnriem as a code owner May 22, 2026 08:14

Copilot AI review requested due to automatic review settings May 22, 2026 08:14

Copilot AI reviewed May 22, 2026

View reviewed changes

Comment thread src/specify_cli/integration_status.py

Comment thread src/specify_cli/integration_status.py Outdated

Comment thread src/specify_cli/integration_doctor.py Outdated

Copilot AI review requested due to automatic review settings May 26, 2026 15:47

PascalThuet changed the title ~~feat(integration): add doctor diagnostics~~ feat(integration): add status reporting May 26, 2026

Copilot AI reviewed May 26, 2026

View reviewed changes

Comment thread src/specify_cli/integration_status.py Outdated

Comment thread src/specify_cli/integration_status.py Outdated

Comment thread src/specify_cli/integration_status.py Outdated

Comment thread src/specify_cli/integration_status.py Outdated

Comment thread docs/reference/integrations.md

Copilot AI review requested due to automatic review settings May 26, 2026 16:12

Copilot AI reviewed May 26, 2026

View reviewed changes

Comment thread src/specify_cli/__init__.py Outdated

Comment thread src/specify_cli/__init__.py Outdated

Comment thread src/specify_cli/integration_status.py

mnriem requested a review from Copilot May 27, 2026 12:23

Copilot started reviewing on behalf of mnriem May 27, 2026 12:23 View session

Copilot AI reviewed May 27, 2026

View reviewed changes

Comment thread src/specify_cli/integration_status.py

Comment thread src/specify_cli/integration_status.py

mnriem requested changes May 27, 2026

View reviewed changes

mnriem requested a review from Copilot May 27, 2026 16:08

Copilot started reviewing on behalf of mnriem May 27, 2026 16:08 View session

Copilot AI reviewed May 27, 2026

View reviewed changes

Comment thread src/specify_cli/integration_status.py Outdated

Comment thread src/specify_cli/integration_status.py

Copilot AI review requested due to automatic review settings May 27, 2026 20:52

Copilot AI reviewed May 27, 2026

View reviewed changes

Comment thread src/specify_cli/integration_status.py Outdated

Comment thread src/specify_cli/integration_state.py

Comment thread tests/integrations/test_integration_subcommand.py Outdated

Comment thread tests/integrations/test_integration_subcommand.py Outdated

mnriem requested a review from Copilot May 28, 2026 12:41

Copilot started reviewing on behalf of mnriem May 28, 2026 12:42 View session

Copilot AI reviewed May 28, 2026

View reviewed changes

Comment thread src/specify_cli/integration_status.py

Comment thread src/specify_cli/integration_status.py

Copilot AI review requested due to automatic review settings May 28, 2026 14:34

Copilot AI reviewed May 28, 2026

View reviewed changes

Comment thread src/specify_cli/integration_status.py Outdated

Comment thread src/specify_cli/integration_state.py Outdated

Comment thread src/specify_cli/integration_status.py Outdated

mnriem requested a review from Copilot May 28, 2026 15:23

Copilot started reviewing on behalf of mnriem May 28, 2026 15:23 View session

Copilot AI reviewed May 28, 2026

View reviewed changes

Comment thread src/specify_cli/integration_status.py Outdated

Comment thread src/specify_cli/integration_status.py Outdated

Copilot started reviewing on behalf of mnriem June 3, 2026 21:08 View session

Copilot AI reviewed Jun 3, 2026

View reviewed changes

Comment thread src/specify_cli/integration_status.py

PascalThuet requested a review from mnriem June 3, 2026 21:46

mnriem requested a review from Copilot June 3, 2026 21:54

Copilot started reviewing on behalf of mnriem June 3, 2026 21:54 View session

Copilot AI reviewed Jun 3, 2026

View reviewed changes

PascalThuet force-pushed the codex/integration-doctor branch from d6d5a72 to de5010c Compare June 3, 2026 22:28

mnriem requested a review from Copilot June 4, 2026 12:15

Copilot started reviewing on behalf of mnriem June 4, 2026 12:15 View session

Copilot AI reviewed Jun 4, 2026

View reviewed changes

mnriem requested changes Jun 4, 2026

View reviewed changes

mnriem requested a review from Copilot June 8, 2026 14:09

Copilot started reviewing on behalf of mnriem June 8, 2026 14:09 View session

Copilot AI reviewed Jun 8, 2026

View reviewed changes

Comment thread src/specify_cli/integration_status.py Outdated

PascalThuet and others added 7 commits June 8, 2026 17:13

feat(integration): add status reporting

d4e3632

docs(integration): include status in query command docstring

0f85960

Potential fix for pull request finding

746d4cc

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

PascalThuet force-pushed the codex/integration-doctor branch from d742358 to 5c6548f Compare June 8, 2026 15:25

mnriem requested a review from Copilot June 8, 2026 20:35

Copilot started reviewing on behalf of mnriem June 8, 2026 20:35 View session

Copilot AI reviewed Jun 8, 2026

View reviewed changes

mnriem self-requested a review June 9, 2026 12:19

mnriem approved these changes Jun 9, 2026

View reviewed changes

mnriem merged commit f65d9f9 into github:main Jun 9, 2026
11 checks passed

Conversation

PascalThuet commented May 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Maintainer feedback

Review feedback

Testing

AI Disclosure

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot's findings

Uh oh!

Uh oh!

Uh oh!

mnriem left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot's findings

Uh oh!

Uh oh!

Uh oh!

mnriem commented May 27, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot's findings

Uh oh!

Uh oh!

Uh oh!

mnriem commented May 28, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

PascalThuet commented May 22, 2026 •

edited

Loading