Skip to content

πŸ’« Toolkit to help you get started with SDD or any other process!

feat(integration): add status reporting (#2674)

Pascal THUETf65d9f9382ff
diff --git a/docs/reference/integrations.md b/docs/reference/integrations.md
index f2bd36f31..d7480ac29 100644
--- a/docs/reference/integrations.md
+++ b/docs/reference/integrations.md
@@ -126,6 +126,27 @@ specify integration upgrade [<key>]
Reinstalls an installed integration with updated templates and commands (e.g., after upgrading Spec Kit). Defaults to the default integration; if a key is provided, it must be one of the installed integrations. Detects locally modified files and blocks the upgrade unless `--force` is used. Stale files from the previous install that are no longer needed are removed automatically. Shared templates stay aligned with the default integration even when upgrading a non-default integration.
+## Report Integration Status
+
+```bash
+specify integration status
+specify integration status --json
+```
+
+Reports the current project's integration status without changing files. The
+status report includes the default integration, installed integrations,
+multi-install safety, missing managed files, modified managed files, invalid
+manifest paths, shared Spec Kit infrastructure health, unchecked manifests, and
+the target integration for default-sensitive shared templates. The JSON form is
+intended for CI and coding agents that need stable machine-readable status data;
+it also reports the raw recorded integrations and the integration manifests that
+were checked when state repair heuristics differ from the recorded file.
+The command exits 0 when the report status is `ok` or `warning`; it exits 1
+only when the report status is `error`. In JSON output, `multi_install_safe`
+is `null` when no installed integration set can be evaluated, such as when the
+integration state is missing, unreadable, lacks a valid recorded integration
+list, or records no installed integrations.
+
## Integration-Specific Options
Some integrations accept additional options via `--integration-options`:
diff --git a/src/specify_cli/integration_state.py b/src/specify_cli/integration_state.py
index 2b1832435..26e1c24b6 100644
--- a/src/specify_cli/integration_state.py
+++ b/src/specify_cli/integration_state.py
@@ -25,17 +25,14 @@ class IntegrationReadError:
schema: int | None = None
-def try_read_integration_json(
+def _read_integration_json_data(
project_root: Path,
) -> tuple[dict[str, Any] | None, IntegrationReadError | None]:
- """Parse ``.specify/integration.json`` without raising.
+ """Read raw integration state without normalizing or raising.
- Returns ``(normalized_state, None)`` on success, ``(None, None)`` when the
- file does not exist, or ``(None, error)`` for any parse / validation
- failure. This is the single low-level reader; both the CLI's loud
- ``_read_integration_json`` and the workflow engine's silent
- ``_load_project_integration`` consume it so the schema guard and parse
- logic cannot drift between them.
+ Returns ``(data, None)`` when the JSON object is readable and supported,
+ ``(None, None)`` when the file is absent, and ``(None, error)`` for parse,
+ schema, encoding, or filesystem failures.
"""
path = project_root / INTEGRATION_JSON
# Avoid Path.exists() / Path.is_file() as a pre-check: both return False
@@ -70,9 +67,41 @@ def try_read_integration_json(
and schema > INTEGRATION_STATE_SCHEMA
):
return None, IntegrationReadError(kind="schema_too_new", schema=schema)
+ return data, None
+
+
+def try_read_integration_json(
+ project_root: Path,
+) -> tuple[dict[str, Any] | None, IntegrationReadError | None]:
+ """Parse ``.specify/integration.json`` without raising.
+
+ Returns ``(normalized_state, None)`` on success, ``(None, None)`` when the
+ file does not exist, or ``(None, error)`` for any parse / validation
+ failure. This helper delegates file I/O and raw JSON validation to
+ ``_read_integration_json_data`` so callers that need raw state can share
+ the same low-level reader instead of duplicating parse logic.
+ """
+ data, error = _read_integration_json_data(project_root)
+ if data is None:
+ return None, error
return normalize_integration_state(data), None
+def try_read_integration_json_with_raw(
+ project_root: Path,
+) -> tuple[dict[str, Any] | None, dict[str, Any] | None, IntegrationReadError | None]:
+ """Parse ``integration.json`` and return normalized plus raw state.
+
+ Returns ``(normalized_state, raw_state, None)`` when the file is readable,
+ ``(None, None, None)`` when it is absent, and ``(None, None, error)`` for
+ parse, schema, encoding, or filesystem failures.
+ """
+ data, error = _read_integration_json_data(project_root)
+ if data is None:
+ return None, None, error
+ return normalize_integration_state(data), data, None
+
+
def clean_integration_key(key: Any) -> str | None:
"""Return a stripped integration key, or None for empty/non-string values."""
if not isinstance(key, str) or not key.strip():
diff --git a/src/specify_cli/integration_status.py b/src/specify_cli/integration_status.py
new file mode 100644
index 000000000..050f0629d
--- /dev/null
+++ b/src/specify_cli/integration_status.py
@@ -0,0 +1,663 @@
+"""Read-only status reporting for project integration state."""
+
+from __future__ import annotations
+
+import hashlib
+import re
+import stat
+from pathlib import Path
+from typing import Any
+
+from .integration_state import (
+ INTEGRATION_JSON,
+ INTEGRATION_STATE_SCHEMA,
+ IntegrationReadError,
+ default_integration_key,
+ installed_integration_keys,
+ try_read_integration_json_with_raw,
+)
+from .integrations import INTEGRATION_REGISTRY
+from .integrations.manifest import IntegrationManifest
+
+_MANIFEST_READ_ERRORS = (ValueError, OSError)
+_MANIFEST_KEY_RE = re.compile(r"^[A-Za-z0-9._-]+$")
+_WINDOWS_RESERVED_MANIFEST_BASENAMES = {
+ "CON",
+ "PRN",
+ "AUX",
+ "NUL",
+ *(f"COM{i}" for i in range(1, 10)),
+ *(f"LPT{i}" for i in range(1, 10)),
+}
+_SHARED_MANIFEST_KEY = "speckit"
+
+
+def _finding(
+ severity: str,
+ code: str,
+ message: str,
+ *,
+ integration: str | None = None,
+ path: str | None = None,
+ suggestion: str | None = None,
+) -> dict[str, str]:
+ item = {
+ "severity": severity,
+ "code": code,
+ "message": message,
+ }
+ if integration:
+ item["integration"] = integration
+ if path:
+ item["path"] = path
+ if suggestion:
+ item["suggestion"] = suggestion
+ return item
+
+
+def _status(findings: list[dict[str, str]]) -> str:
+ if any(item["severity"] == "error" for item in findings):
+ return "error"
+ if findings:
+ return "warning"
+ return "ok"
+
+
+def _with_error_detail(message: str, error: IntegrationReadError) -> str:
+ if error.detail:
+ return f"{message} Detail: {error.detail}"
+ return message
+
+
+def _integration_state_error_message(error: IntegrationReadError) -> str:
+ if error.kind == "decode":
+ return _with_error_detail(
+ f"{INTEGRATION_JSON} contains invalid JSON or is not valid UTF-8.",
+ error,
+ )
+ if error.kind == "os":
+ return _with_error_detail(f"Could not read {INTEGRATION_JSON}.", error)
+ if error.kind == "not_object":
+ return f"{INTEGRATION_JSON} must contain a JSON object, got {error.detail}."
+ if error.kind == "schema_too_new":
+ return (
+ f"{INTEGRATION_JSON} uses integration state schema {error.schema}, "
+ f"which is newer than this CLI supports; supported schema: {INTEGRATION_STATE_SCHEMA}."
+ )
+ return f"Could not inspect {INTEGRATION_JSON}."
+
+
+def _sha256_file(path: Path) -> str:
+ h = hashlib.sha256()
+ with open(path, "rb") as fh:
+ for chunk in iter(lambda: fh.read(8192), b""):
+ h.update(chunk)
+ return h.hexdigest()
+
+
+def _strip_extended_length_prefix(path: Path) -> Path:
+ """Drop the Windows ``\\\\?\\`` extended-length prefix for path comparison.
+
+ ``os.readlink`` and ``Path.resolve`` can return extended-length paths on
+ Windows (e.g. ``\\\\?\\C:\\proj``). Comparing such a path against a plain
+ ``C:\\proj`` root via :meth:`Path.relative_to` would spuriously fail, so we
+ normalise both sides through this helper before containment checks.
+ """
+ raw = str(path)
+ if raw.startswith("\\\\?\\UNC\\"):
+ return Path("\\\\" + raw[len("\\\\?\\UNC\\"):])
+ if raw.startswith("\\\\?\\"):
+ return Path(raw[len("\\\\?\\"):])
+ return path
+
+
+def _is_within_project(project_root_resolved: Path, candidate: Path) -> bool:
+ """Return ``True`` when *candidate* stays within *project_root_resolved*.
+
+ Both paths are stripped of any Windows extended-length prefix first so that
+ a target produced by ``os.readlink`` (which may be ``\\\\?\\``-prefixed) is
+ still recognised as living inside an unprefixed project root.
+ """
+ try:
+ _strip_extended_length_prefix(candidate).relative_to(
+ _strip_extended_length_prefix(project_root_resolved)
+ )
+ except ValueError:
+ return False
+ return True
+
+
+def _safe_manifest_file(
+ project_root: Path,
+ project_root_resolved: Path,
+ rel: str,
+ *,
+ project_root_is_resolved: bool = True,
+) -> Path | None:
+ rel_path = Path(rel)
+ if rel_path.is_absolute() or ".." in rel_path.parts:
+ return None
+ candidate = project_root / rel_path
+ if not project_root_is_resolved:
+ walk = project_root
+ for part in rel_path.parts[:-1]:
+ walk = walk / part
+ try:
+ if walk.is_symlink():
+ return None
+ except OSError:
+ return None
+ try:
+ candidate_parent = (
+ candidate.parent.resolve(strict=False)
+ if project_root_is_resolved
+ else candidate.parent.absolute()
+ )
+ except (OSError, RuntimeError):
+ return None
+ if not _is_within_project(project_root_resolved, candidate_parent):
+ return None
+ return candidate
+
+
+def _tracked_symlink_manifest_status(
+ path: Path,
+ project_root_resolved: Path,
+ *,
+ project_root_is_resolved: bool = True,
+) -> str:
+ """Classify a tracked symlink without following it outside the project.
+
+ Manifests store content hashes for regular files, so an existing in-project
+ symlink is still reported as modified. Escaping targets are invalid, and
+ dangling in-project targets are missing.
+ """
+ try:
+ target = path.readlink()
+ except OSError:
+ return "modified"
+
+ target_path = target if target.is_absolute() else path.parent / target
+ try:
+ contained_parent = (
+ target_path.parent.resolve(strict=False)
+ if project_root_is_resolved
+ else target_path.parent.absolute()
+ )
+ except (OSError, RuntimeError):
+ return "invalid"
+ if not _is_within_project(project_root_resolved, contained_parent):
+ return "invalid"
+
+ try:
+ target_path.lstat()
+ except FileNotFoundError:
+ return "missing"
+ except OSError:
+ return "modified"
+ return "modified"
+
+
+def _resolve_project_root_for_status(
+ project_root: Path,
+ findings: list[dict[str, str]],
+) -> tuple[Path, bool]:
+ try:
+ return project_root.resolve(), True
+ except (OSError, RuntimeError) as exc:
+ findings.append(
+ _finding(
+ "warning",
+ "project-root-unresolved",
+ f"Could not fully resolve project root: {exc}",
+ suggestion="Check project path permissions and symlinks before relying on manifest path checks.",
+ )
+ )
+ return project_root.absolute(), False
+
+
+def _is_safe_manifest_key(key: str) -> bool:
+ if key in {"", ".", ".."}:
+ return False
+ if key.endswith("."):
+ return False
+ if _MANIFEST_KEY_RE.fullmatch(key) is None:
+ return False
+ if key.split(".", 1)[0].upper() in _WINDOWS_RESERVED_MANIFEST_BASENAMES:
+ return False
+ if "/" in key or "\\" in key:
+ return False
+ key_path = Path(key)
+ return not key_path.is_absolute() and key_path.name == key
+
+
+def _manifest_file_status(
+ manifest: IntegrationManifest,
+ project_root_resolved: Path,
+ *,
+ project_root_is_resolved: bool = True,
+) -> tuple[list[str], list[str], list[str], list[str]]:
+ missing: list[str] = []
+ modified: list[str] = []
+ invalid: list[str] = []
+ valid: list[str] = []
+
+ for rel, expected_hash in manifest.files.items():
+ path = _safe_manifest_file(
+ manifest.project_root,
+ project_root_resolved,
+ rel,
+ project_root_is_resolved=project_root_is_resolved,
+ )
+ if path is None:
+ invalid.append(rel)
+ continue
+ try:
+ path_stat = path.lstat()
+ except FileNotFoundError:
+ valid.append(rel)
+ missing.append(rel)
+ continue
+ except OSError:
+ valid.append(rel)
+ modified.append(rel)
+ continue
+ is_symlink = stat.S_ISLNK(path_stat.st_mode)
+ if not is_symlink:
+ try:
+ is_symlink = path.is_symlink()
+ except OSError:
+ is_symlink = False
+ if is_symlink:
+ symlink_status = _tracked_symlink_manifest_status(
+ path,
+ project_root_resolved,
+ project_root_is_resolved=project_root_is_resolved,
+ )
+ if symlink_status == "invalid":
+ invalid.append(rel)
+ continue
+ valid.append(rel)
+ if symlink_status == "missing":
+ missing.append(rel)
+ continue
+ modified.append(rel)
+ continue
+ valid.append(rel)
+ if not stat.S_ISREG(path_stat.st_mode):
+ modified.append(rel)
+ continue
+ try:
+ if _sha256_file(path) != expected_hash:
+ modified.append(rel)
+ except OSError:
+ modified.append(rel)
+
+ return missing, modified, invalid, valid
+
+
+def _default_not_installed_from_raw_state(raw_state: dict[str, Any]) -> str | None:
+ if not isinstance(raw_state.get("installed_integrations"), list):
+ return None
+
+ raw_default = default_integration_key(raw_state)
+ raw_installed = installed_integration_keys(raw_state)
+ if raw_default and raw_default not in raw_installed:
+ return raw_default
+ return None
+
+
+def _manifest_summary(
+ manifest_path: Path,
+ project_root: Path,
+ *,
+ readable: bool,
+ tracked_files: int = 0,
+ missing_files: list[str] | None = None,
+ modified_files: list[str] | None = None,
+ invalid_files: list[str] | None = None,
+) -> dict[str, Any]:
+ return {
+ "manifest": manifest_path.relative_to(project_root).as_posix(),
+ "readable": readable,
+ "tracked_files": tracked_files,
+ "missing_files": missing_files or [],
+ "modified_files": modified_files or [],
+ "invalid_files": invalid_files or [],
+ }
+
+
+def _manifest_owner(key: str) -> str:
+ if key == _SHARED_MANIFEST_KEY:
+ return "shared Spec Kit infrastructure"
+ return f"integration '{key}'"
+
+
+def _manifest_suggestion(key: str, default_key: str | None) -> str:
+ if key == _SHARED_MANIFEST_KEY:
+ if default_key and default_key in INTEGRATION_REGISTRY:
+ return f"Run `specify integration upgrade {default_key}` to regenerate shared managed files."
+ return (
+ "Run `specify init --here --force --integration <key>` to regenerate "
+ "shared managed files."
+ )
+ if key not in INTEGRATION_REGISTRY:
+ return (
+ "Upgrade Spec Kit, reinstall with a supported CLI version, "
+ f"or remove the stale integration entry from {INTEGRATION_JSON}."
+ )
+ return f"Run `specify integration upgrade {key}` or reinstall the integration."
+
+
+def build_integration_status_report(project_root: Path) -> dict[str, Any]:
+ """Return a machine-readable integration status report for *project_root*."""
+ findings: list[dict[str, str]] = []
+ project_root_resolved, project_root_is_resolved = _resolve_project_root_for_status(
+ project_root,
+ findings,
+ )
+ state, raw_state, error = try_read_integration_json_with_raw(project_root)
+ if error is not None:
+ findings.append(
+ _finding(
+ "error",
+ "integration-state-unreadable",
+ _integration_state_error_message(error),
+ path=INTEGRATION_JSON,
+ suggestion=f"Fix or delete {INTEGRATION_JSON}, then retry.",
+ )
+ )
+ return _build_report(None, [], findings, {}, None)
+
+ if state is None:
+ findings.append(
+ _finding(
+ "error",
+ "integration-state-missing",
+ f"{INTEGRATION_JSON} is missing.",
+ path=INTEGRATION_JSON,
+ suggestion="Run `specify integration install <key>` to install an integration.",
+ )
+ )
+ return _build_report(None, [], findings, {}, None)
+
+ assert raw_state is not None
+ raw_default_key = default_integration_key(raw_state)
+ raw_installed_value = raw_state.get("installed_integrations")
+ raw_installed_is_list = isinstance(raw_installed_value, list)
+ raw_installed_keys = (
+ installed_integration_keys(raw_state)
+ if raw_installed_is_list
+ else []
+ )
+ default_key = raw_default_key or default_integration_key(state)
+ installed_keys = installed_integration_keys(state)
+ raw_default_not_installed = _default_not_installed_from_raw_state(raw_state)
+ if raw_installed_is_list and raw_default_not_installed and raw_installed_keys:
+ check_installed_keys = raw_installed_keys
+ else:
+ check_installed_keys = installed_keys
+ recorded_installed_keys = raw_installed_keys
+ if "installed_integrations" in raw_state and not raw_installed_is_list:
+ findings.append(
+ _finding(
+ "warning",
+ "installed-integrations-invalid",
+ (
+ "installed_integrations must be a list, "
+ f"got {type(raw_installed_value).__name__}."
+ ),
+ path=INTEGRATION_JSON,
+ suggestion=f"Fix {INTEGRATION_JSON}, then retry.",
+ )
+ )
+ if not installed_keys:
+ findings.append(
+ _finding(
+ "warning",
+ "no-installed-integrations",
+ "No installed integrations are recorded.",
+ suggestion="Run `specify integration install <key>` to install one.",
+ )
+ )
+
+ if raw_installed_keys and raw_default_key is None:
+ default_key = None
+ findings.append(
+ _finding(
+ "error",
+ "default-integration-missing",
+ "No default integration is recorded.",
+ suggestion="Run `specify integration use <key>` after choosing an installed integration.",
+ )
+ )
+
+ if raw_default_not_installed:
+ findings.append(
+ _finding(
+ "error",
+ "default-integration-not-installed",
+ (
+ f"Default integration '{raw_default_not_installed}' is not listed "
+ "in installed_integrations."
+ ),
+ integration=raw_default_not_installed,
+ suggestion="Run `specify integration use <key>` for an installed integration, or reinstall the default integration.",
+ )
+ )
+
+ known_installed = [key for key in check_installed_keys if key in INTEGRATION_REGISTRY]
+ unknown_installed: list[str] = []
+ for key in check_installed_keys:
+ if key not in INTEGRATION_REGISTRY:
+ unknown_installed.append(key)
+ findings.append(
+ _finding(
+ "error",
+ "unknown-integration",
+ f"Integration '{key}' is installed but is not known to this CLI.",
+ integration=key,
+ suggestion=(
+ "Upgrade Spec Kit, reinstall with a supported CLI version, "
+ f"or remove the stale integration entry from {INTEGRATION_JSON}."
+ ),
+ )
+ )
+
+ unsafe = [
+ key for key in known_installed
+ if not getattr(INTEGRATION_REGISTRY[key], "multi_install_safe", False)
+ ]
+ if len(check_installed_keys) > 1:
+ unsafe.extend(unknown_installed)
+
+ if len(check_installed_keys) > 1 and unsafe:
+ findings.append(
+ _finding(
+ "error",
+ "unsafe-multi-install",
+ (
+ "Installed integrations are not all declared multi-install safe: "
+ + ", ".join(sorted(unsafe))
+ ),
+ suggestion=(
+ "Use `specify integration use <key>` to change defaults, "
+ "or `specify integration switch <key>` only when replacing integrations."
+ ),
+ )
+ )
+
+ manifest_files_by_path: dict[str, list[str]] = {}
+ manifest_summaries: dict[str, dict[str, Any]] = {}
+ attempted_manifest_keys: list[str] = []
+ manifest_keys = list(check_installed_keys)
+ if _SHARED_MANIFEST_KEY not in manifest_keys:
+ manifest_keys.append(_SHARED_MANIFEST_KEY)
+
+ for key in manifest_keys:
+ owner = _manifest_owner(key)
+ if not _is_safe_manifest_key(key):
+ findings.append(
+ _finding(
+ "error",
+ "integration-key-invalid",
+ f"Integration key {key!r} cannot be used as a manifest filename.",
+ integration=key,
+ path=INTEGRATION_JSON,
+ suggestion=f"Fix {INTEGRATION_JSON}, then reinstall the integration.",
+ )
+ )
+ continue
+
+ attempted_manifest_keys.append(key)
+ manifest_path = project_root / ".specify" / "integrations" / f"{key}.manifest.json"
+ try:
+ manifest = IntegrationManifest.load(
+ key,
+ project_root_resolved,
+ resolve_project_root=False,
+ )
+ except FileNotFoundError:
+ findings.append(
+ _finding(
+ "error",
+ "manifest-missing",
+ f"Manifest for {owner} is missing.",
+ integration=key,
+ path=manifest_path.relative_to(project_root).as_posix(),
+ suggestion=_manifest_suggestion(key, default_key),
+ )
+ )
+ manifest_summaries[key] = _manifest_summary(
+ manifest_path,
+ project_root,
+ readable=False,
+ )
+ continue
+ except _MANIFEST_READ_ERRORS as exc:
+ manifest_summaries[key] = _manifest_summary(
+ manifest_path,
+ project_root,
+ readable=False,
+ )
+ findings.append(
+ _finding(
+ "error",
+ "manifest-unreadable",
+ f"Manifest for {owner} is unreadable: {exc}",
+ integration=key,
+ path=manifest_path.relative_to(project_root).as_posix(),
+ suggestion=_manifest_suggestion(key, default_key),
+ )
+ )
+ continue
+
+ missing, modified, invalid, valid_files = _manifest_file_status(
+ manifest,
+ project_root_resolved,
+ project_root_is_resolved=project_root_is_resolved,
+ )
+ manifest_summaries[key] = _manifest_summary(
+ manifest_path,
+ project_root,
+ readable=True,
+ tracked_files=len(manifest.files),
+ missing_files=missing,
+ modified_files=modified,
+ invalid_files=invalid,
+ )
+
+ for rel in valid_files:
+ manifest_files_by_path.setdefault(rel, []).append(key)
+ if invalid:
+ findings.append(
+ _finding(
+ "error",
+ "manifest-paths-invalid",
+ f"{len(invalid)} unsafe manifest path(s) are recorded for {owner}.",
+ integration=key,
+ path=manifest_path.relative_to(project_root).as_posix(),
+ suggestion=_manifest_suggestion(key, default_key),
+ )
+ )
+ if missing:
+ findings.append(
+ _finding(
+ "error",
+ "managed-files-missing",
+ f"{len(missing)} managed file(s) are missing for {owner}.",
+ integration=key,
+ suggestion=_manifest_suggestion(key, default_key),
+ )
+ )
+ if modified:
+ findings.append(
+ _finding(
+ "warning",
+ "managed-files-modified",
+ f"{len(modified)} managed file(s) were modified for {owner}.",
+ integration=key,
+ suggestion="Review the changes before running `specify integration upgrade --force`.",
+ )
+ )
+
+ for rel, keys in sorted(manifest_files_by_path.items()):
+ if len(keys) > 1:
+ findings.append(
+ _finding(
+ "warning",
+ "managed-file-collision",
+ f"Managed file '{rel}' is tracked by multiple integrations: {', '.join(sorted(keys))}.",
+ path=rel,
+ suggestion="Review the manifests before uninstalling or upgrading these integrations.",
+ )
+ )
+
+ if not raw_installed_is_list or not raw_installed_keys:
+ multi_install_safe = None
+ else:
+ multi_install_safe = not (len(check_installed_keys) > 1 and unsafe)
+ return _build_report(
+ default_key,
+ installed_keys,
+ findings,
+ manifest_summaries,
+ multi_install_safe,
+ manifest_checked_keys=attempted_manifest_keys,
+ recorded_installed_keys=recorded_installed_keys,
+ )
+
+
+def _build_report(
+ default_key: str | None,
+ installed_keys: list[str],
+ findings: list[dict[str, str]],
+ manifests: dict[str, dict[str, Any]],
+ multi_install_safe: bool | None,
+ *,
+ manifest_checked_keys: list[str] | None = None,
+ recorded_installed_keys: list[str] | None = None,
+) -> dict[str, Any]:
+ missing_count = sum(len(item.get("missing_files", [])) for item in manifests.values())
+ modified_count = sum(len(item.get("modified_files", [])) for item in manifests.values())
+ invalid_count = sum(len(item.get("invalid_files", [])) for item in manifests.values())
+ unchecked_count = sum(1 for item in manifests.values() if not item.get("readable", True))
+ return {
+ "status": _status(findings),
+ "default_integration": default_key,
+ "installed_integrations": installed_keys,
+ "recorded_installed_integrations": (
+ installed_keys if recorded_installed_keys is None else recorded_installed_keys
+ ),
+ "manifest_checked_integrations": (
+ installed_keys if manifest_checked_keys is None else manifest_checked_keys
+ ),
+ "multi_install_safe": multi_install_safe,
+ "shared_templates_target_alignment": default_key,
+ "missing_managed_files": missing_count,
+ "modified_managed_files": modified_count,
+ "invalid_manifest_paths": invalid_count,
+ "unchecked_manifests": unchecked_count,
+ "manifests": manifests,
+ "findings": findings,
+ }
diff --git a/src/specify_cli/integrations/_query_commands.py b/src/specify_cli/integrations/_query_commands.py
index b22276547..dda74b061 100644
--- a/src/specify_cli/integrations/_query_commands.py
+++ b/src/specify_cli/integrations/_query_commands.py
@@ -1,10 +1,12 @@
-"""specify integration list/use/search/info + catalog list/add/remove command handlers."""
+"""specify integration list/status/use/search/info + catalog list/add/remove command handlers."""
from __future__ import annotations
+import json
import os
-from typing import Optional
+from typing import Any, Optional
import typer
+from rich.markup import escape as _rich_escape
from rich.table import Table
from .._console import console
@@ -120,6 +122,86 @@ def integration_list(
console.print("Install one with: [cyan]specify integration install <key>[/cyan]")
+def _print_integration_status_report(report: dict[str, Any]) -> None:
+ status = report["status"]
+ status_label = {
+ "ok": "[green]OK[/green]",
+ "warning": "[yellow]WARNING[/yellow]",
+ "error": "[red]ERROR[/red]",
+ }.get(str(status), str(status).upper())
+ installed = report.get("installed_integrations") or []
+ installed_display = ", ".join(_rich_escape(str(item)) for item in installed)
+
+ console.print(f"Integration status: {status_label}")
+ console.print(
+ f"Default integration: {_rich_escape(str(report.get('default_integration') or 'none'))}"
+ )
+ console.print(f"Installed integrations: {installed_display if installed else 'none'}")
+ multi_install_safe = report.get("multi_install_safe")
+ if multi_install_safe is None:
+ multi_install_safe_display = "unknown"
+ else:
+ multi_install_safe_display = "yes" if multi_install_safe else "no"
+ console.print(f"Multi-install safe: {multi_install_safe_display}")
+ console.print(
+ f"Shared templates target alignment: "
+ f"{_rich_escape(str(report.get('shared_templates_target_alignment') or 'none'))}"
+ )
+ console.print(f"Modified managed files: {report.get('modified_managed_files', 0)}")
+ console.print(f"Missing managed files: {report.get('missing_managed_files', 0)}")
+ console.print(f"Invalid manifest paths: {report.get('invalid_manifest_paths', 0)}")
+ console.print(f"Unchecked manifests: {report.get('unchecked_manifests', 0)}")
+
+ findings = report.get("findings") or []
+ if not findings:
+ return
+
+ console.print()
+ console.print("[bold]Findings:[/bold]")
+ for item in findings:
+ severity = item.get("severity", "")
+ severity_label = {
+ "error": "[red]error[/red]",
+ "warning": "[yellow]warning[/yellow]",
+ }.get(severity, severity)
+ prefix = f"- {severity_label} {_rich_escape(str(item.get('code', '')))}"
+ if item.get("integration"):
+ prefix += f" ({_rich_escape(str(item['integration']))})"
+ console.print(
+ f"{prefix}: {_rich_escape(str(item.get('message', '')))}",
+ soft_wrap=True,
+ )
+ if item.get("suggestion"):
+ console.print(
+ f" Suggestion: {_rich_escape(str(item['suggestion']))}",
+ soft_wrap=True,
+ )
+
+
+@integration_app.command("status")
+def integration_status(
+ json_output: bool = typer.Option(
+ False,
+ "--json",
+ help="Emit machine-readable integration status.",
+ ),
+):
+ """Report the current project's integration status without changing files."""
+ from .. import _require_specify_project
+ from ..integration_status import build_integration_status_report
+
+ project_root = _require_specify_project()
+ report = build_integration_status_report(project_root)
+
+ if json_output:
+ typer.echo(json.dumps(report, indent=2))
+ else:
+ _print_integration_status_report(report)
+
+ if report["status"] == "error":
+ raise typer.Exit(1)
+
+
@integration_app.command("use")
def integration_use(
key: str = typer.Argument(help="Installed integration key to make the default"),
diff --git a/src/specify_cli/integrations/manifest.py b/src/specify_cli/integrations/manifest.py
index df0958aa8..23121be01 100644
--- a/src/specify_cli/integrations/manifest.py
+++ b/src/specify_cli/integrations/manifest.py
@@ -108,11 +108,23 @@ class IntegrationManifest:
key: Integration identifier (e.g. ``"copilot"``).
project_root: Absolute path to the project directory.
version: CLI version string recorded in the manifest.
+ resolve_project_root: Resolve ``project_root`` before using it.
"""
- def __init__(self, key: str, project_root: Path, version: str = "") -> None:
+ def __init__(
+ self,
+ key: str,
+ project_root: Path,
+ version: str = "",
+ *,
+ resolve_project_root: bool = True,
+ ) -> None:
self.key = key
- self.project_root = project_root.resolve()
+ self.project_root = (
+ project_root.resolve()
+ if resolve_project_root
+ else project_root.absolute()
+ )
self.version = version
self._files: dict[str, str] = {} # rel_path β†’ sha256 hex
self._recovered_files: set[str] = set()
@@ -387,12 +399,18 @@ class IntegrationManifest:
return path
@classmethod
- def load(cls, key: str, project_root: Path) -> IntegrationManifest:
+ def load(
+ cls,
+ key: str,
+ project_root: Path,
+ *,
+ resolve_project_root: bool = True,
+ ) -> IntegrationManifest:
"""Load an existing manifest from disk.
Raises ``FileNotFoundError`` if the manifest does not exist.
"""
- inst = cls(key, project_root)
+ inst = cls(key, project_root, resolve_project_root=resolve_project_root)
path = inst.manifest_path
try:
data = json.loads(path.read_text(encoding="utf-8"))
diff --git a/tests/integrations/test_integration_subcommand.py b/tests/integrations/test_integration_subcommand.py
index c614d691f..8c486ce2d 100644
--- a/tests/integrations/test_integration_subcommand.py
+++ b/tests/integrations/test_integration_subcommand.py
@@ -2,7 +2,10 @@
import json
import os
+import shutil
+from pathlib import Path
+import pytest
from typer.testing import CliRunner
from specify_cli import app
@@ -47,6 +50,32 @@ def _write_invalid_manifest(project, key):
return manifest
+def _copy_project_template(tmp_path, template):
+ project = tmp_path / "proj"
+ shutil.copytree(template, project)
+ return project
+
+
[email protected](scope="module")
+def status_copilot_template(tmp_path_factory):
+ return _init_project(tmp_path_factory.mktemp("status-copilot"), "copilot")
+
+
[email protected](scope="module")
+def status_claude_template(tmp_path_factory):
+ return _init_project(tmp_path_factory.mktemp("status-claude"), "claude")
+
+
+def copilot_project(tmp_path, status_copilot_template):
+ return _copy_project_template(tmp_path, status_copilot_template)
+
+
+def claude_project(tmp_path, status_claude_template):
+ return _copy_project_template(tmp_path, status_claude_template)
+
+
def _integration_list_row_cells(output: str, key: str) -> list[str]:
plain = strip_ansi(output)
row = next(line for line in plain.splitlines() if line.startswith(f"β”‚ {key}"))
@@ -126,6 +155,823 @@ class TestIntegrationList:
assert "only supports schema 1" in normalized
+# ── status ───────────────────────────────────────────────────────────
+
+
+class TestIntegrationStatus:
+ def test_status_requires_speckit_project(self, tmp_path, monkeypatch):
+ monkeypatch.chdir(tmp_path)
+ result = runner.invoke(app, ["integration", "status"])
+ assert result.exit_code != 0
+ assert "Not a spec-kit project" in result.output
+
+ def test_status_reports_healthy_project(self, copilot_project):
+ result = _run_in_project(copilot_project, ["integration", "status"])
+
+ assert result.exit_code == 0
+ assert "Integration status: OK" in result.output
+ assert "Default integration: copilot" in result.output
+ assert "Installed integrations: copilot" in result.output
+ assert "Shared templates target alignment: copilot" in result.output
+ assert "Modified managed files: 0" in result.output
+ assert "Missing managed files: 0" in result.output
+
+ def test_status_json_reports_healthy_project(self, copilot_project):
+ result = _run_in_project(copilot_project, ["integration", "status", "--json"])
+
+ assert result.exit_code == 0
+ payload = json.loads(result.output)
+ assert payload["status"] == "ok"
+ assert payload["default_integration"] == "copilot"
+ assert payload["installed_integrations"] == ["copilot"]
+ assert payload["recorded_installed_integrations"] == ["copilot"]
+ assert payload["manifest_checked_integrations"] == ["copilot", "speckit"]
+ assert payload["multi_install_safe"] is True
+ assert payload["shared_templates_target_alignment"] == "copilot"
+ assert "shared_templates_aligned_to" not in payload
+ assert payload["findings"] == []
+
+ def test_status_reports_invalid_integration_json(self, copilot_project):
+ (copilot_project / ".specify" / "integration.json").write_text("{", encoding="utf-8")
+
+ result = _run_in_project(copilot_project, ["integration", "status"])
+
+ assert result.exit_code != 0
+ assert "integration-state-unreadable" in result.output
+ assert "invalid JSON" in result.output
+ assert "Detail:" in result.output
+ assert "Multi-install safe: unknown" in result.output
+ assert "Traceback" not in result.output
+
+ def test_status_json_reports_unknown_multi_install_safety_when_state_unreadable(
+ self,
+ copilot_project,
+ ):
+ (copilot_project / ".specify" / "integration.json").write_text("{", encoding="utf-8")
+
+ result = _run_in_project(copilot_project, ["integration", "status", "--json"])
+
+ assert result.exit_code != 0
+ payload = json.loads(result.output)
+ assert payload["status"] == "error"
+ assert payload["multi_install_safe"] is None
+ assert payload["manifest_checked_integrations"] == []
+ assert payload["findings"][0]["code"] == "integration-state-unreadable"
+ assert "Detail:" in payload["findings"][0]["message"]
+
+ def test_status_reports_supported_schema_for_newer_integration_state(self, copilot_project):
+ state_path = copilot_project / ".specify" / "integration.json"
+ state = json.loads(state_path.read_text(encoding="utf-8"))
+ state["integration_state_schema"] = 99
+ state_path.write_text(json.dumps(state), encoding="utf-8")
+
+ result = _run_in_project(copilot_project, ["integration", "status", "--json"])
+
+ assert result.exit_code != 0
+ payload = json.loads(result.output)
+ assert payload["findings"][0]["code"] == "integration-state-unreadable"
+ assert "schema 99" in payload["findings"][0]["message"]
+ assert "supported schema: 1" in payload["findings"][0]["message"]
+
+ def test_status_reports_missing_integration_json(self, copilot_project):
+ (copilot_project / ".specify" / "integration.json").unlink()
+
+ result = _run_in_project(copilot_project, ["integration", "status"])
+
+ assert result.exit_code != 0
+ assert "integration-state-missing" in result.output
+ assert ".specify/integration.json is missing" in result.output
+ assert "Multi-install safe: unknown" in result.output
+
+ def test_status_json_reports_unknown_multi_install_safety_when_state_missing(
+ self,
+ copilot_project,
+ ):
+ (copilot_project / ".specify" / "integration.json").unlink()
+
+ result = _run_in_project(copilot_project, ["integration", "status", "--json"])
+
+ assert result.exit_code != 0
+ payload = json.loads(result.output)
+ assert payload["status"] == "error"
+ assert payload["multi_install_safe"] is None
+ assert payload["manifest_checked_integrations"] == []
+ assert payload["findings"][0]["code"] == "integration-state-missing"
+
+ def test_status_json_reports_no_installed_integrations_as_warning(self, copilot_project):
+ state_path = copilot_project / ".specify" / "integration.json"
+ state_path.write_text(
+ json.dumps({
+ "version": "test",
+ "integration_state_schema": 1,
+ "installed_integrations": [],
+ }),
+ encoding="utf-8",
+ )
+
+ result = _run_in_project(copilot_project, ["integration", "status", "--json"])
+
+ assert result.exit_code == 0
+ payload = json.loads(result.output)
+ assert payload["status"] == "warning"
+ assert payload["installed_integrations"] == []
+ assert payload["multi_install_safe"] is None
+ assert payload["manifest_checked_integrations"] == ["speckit"]
+ assert payload["findings"][0]["code"] == "no-installed-integrations"
+ assert "speckit" in payload["manifests"]
+ assert payload["manifests"]["speckit"]["readable"] is True
+
+ def test_status_checks_shared_manifest_when_no_integrations_installed(self, copilot_project):
+ state_path = copilot_project / ".specify" / "integration.json"
+ state_path.write_text(
+ json.dumps({
+ "version": "test",
+ "integration_state_schema": 1,
+ "installed_integrations": [],
+ }),
+ encoding="utf-8",
+ )
+ (copilot_project / ".specify" / "integrations" / "speckit.manifest.json").unlink()
+
+ result = _run_in_project(copilot_project, ["integration", "status", "--json"])
+
+ assert result.exit_code != 0
+ payload = json.loads(result.output)
+ assert payload["status"] == "error"
+ assert payload["installed_integrations"] == []
+ assert payload["manifest_checked_integrations"] == ["speckit"]
+ assert payload["unchecked_manifests"] == 1
+ assert any(
+ item["code"] == "no-installed-integrations"
+ for item in payload["findings"]
+ )
+ assert any(
+ item["code"] == "manifest-missing"
+ and item["integration"] == "speckit"
+ for item in payload["findings"]
+ )
+
+ def test_status_json_reports_missing_default_integration_as_error(self, claude_project):
+ state_path = claude_project / ".specify" / "integration.json"
+ state = json.loads(state_path.read_text(encoding="utf-8"))
+ state.pop("default_integration", None)
+ state.pop("integration", None)
+ state["installed_integrations"] = ["claude"]
+ state_path.write_text(json.dumps(state), encoding="utf-8")
+
+ result = _run_in_project(claude_project, ["integration", "status", "--json"])
+
+ assert result.exit_code != 0
+ payload = json.loads(result.output)
+ assert payload["status"] == "error"
+ assert payload["default_integration"] is None
+ assert any(
+ item["code"] == "default-integration-missing"
+ for item in payload["findings"]
+ )
+
+ def test_status_ignores_non_list_raw_installed_integrations(self, copilot_project):
+ state_path = copilot_project / ".specify" / "integration.json"
+ state = json.loads(state_path.read_text(encoding="utf-8"))
+ state.pop("default_integration", None)
+ state.pop("integration", None)
+ state["installed_integrations"] = "copilot"
+ state_path.write_text(json.dumps(state), encoding="utf-8")
+
+ result = _run_in_project(copilot_project, ["integration", "status", "--json"])
+
+ assert result.exit_code == 0
+ payload = json.loads(result.output)
+ assert payload["status"] == "warning"
+ assert payload["installed_integrations"] == []
+ assert payload["recorded_installed_integrations"] == []
+ assert payload["manifest_checked_integrations"] == ["speckit"]
+ assert payload["multi_install_safe"] is None
+ assert [item["code"] for item in payload["findings"]] == [
+ "installed-integrations-invalid",
+ "no-installed-integrations",
+ ]
+
+ def test_status_reports_non_list_raw_installed_integrations_with_default(self, copilot_project):
+ state_path = copilot_project / ".specify" / "integration.json"
+ state = json.loads(state_path.read_text(encoding="utf-8"))
+ state["default_integration"] = "copilot"
+ state["integration"] = "copilot"
+ state["installed_integrations"] = "copilot"
+ state_path.write_text(json.dumps(state), encoding="utf-8")
+
+ result = _run_in_project(copilot_project, ["integration", "status", "--json"])
+
+ assert result.exit_code == 0
+ payload = json.loads(result.output)
+ assert payload["status"] == "warning"
+ assert payload["installed_integrations"] == ["copilot"]
+ assert payload["recorded_installed_integrations"] == []
+ assert payload["manifest_checked_integrations"] == ["copilot", "speckit"]
+ assert payload["multi_install_safe"] is None
+ assert [item["code"] for item in payload["findings"]] == [
+ "installed-integrations-invalid",
+ ]
+
+ def test_status_reports_default_integration_not_installed(self, claude_project):
+ state_path = claude_project / ".specify" / "integration.json"
+ state = json.loads(state_path.read_text(encoding="utf-8"))
+ state["default_integration"] = "codex"
+ state["integration"] = "codex"
+ state["installed_integrations"] = ["claude"]
+ state_path.write_text(json.dumps(state), encoding="utf-8")
+
+ result = _run_in_project(claude_project, ["integration", "status", "--json"])
+
+ assert result.exit_code != 0
+ payload = json.loads(result.output)
+ assert payload["default_integration"] == "codex"
+ assert payload["installed_integrations"] == ["codex", "claude"]
+ assert payload["recorded_installed_integrations"] == ["claude"]
+ assert payload["manifest_checked_integrations"] == ["claude", "speckit"]
+ assert any(
+ item["code"] == "default-integration-not-installed"
+ and "Default integration 'codex' is not listed" in item["message"]
+ for item in payload["findings"]
+ )
+ assert "codex" not in payload["manifests"]
+ assert not any(
+ item["code"] == "manifest-missing" and item.get("integration") == "codex"
+ for item in payload["findings"]
+ )
+
+ def test_status_checks_effective_default_manifest_when_raw_installed_is_empty(self, claude_project):
+ state_path = claude_project / ".specify" / "integration.json"
+ state = json.loads(state_path.read_text(encoding="utf-8"))
+ state["installed_integrations"] = []
+ state_path.write_text(json.dumps(state), encoding="utf-8")
+
+ result = _run_in_project(claude_project, ["integration", "status", "--json"])
+
+ assert result.exit_code != 0
+ payload = json.loads(result.output)
+ assert payload["installed_integrations"] == ["claude"]
+ assert payload["recorded_installed_integrations"] == []
+ assert payload["manifest_checked_integrations"] == ["claude", "speckit"]
+ assert payload["multi_install_safe"] is None
+ assert payload["manifests"]["claude"]["readable"] is True
+ assert any(
+ item["code"] == "default-integration-not-installed"
+ for item in payload["findings"]
+ )
+
+ def test_status_reports_missing_manifest(self, copilot_project):
+ (copilot_project / ".specify" / "integrations" / "copilot.manifest.json").unlink()
+
+ result = _run_in_project(copilot_project, ["integration", "status"])
+
+ assert result.exit_code != 0
+ assert "manifest-missing" in result.output
+ assert "Manifest for integration 'copilot' is missing" in result.output
+
+ def test_status_reports_unreadable_manifest_in_json_summary(self, copilot_project):
+ _write_invalid_manifest(copilot_project, "copilot")
+
+ result = _run_in_project(copilot_project, ["integration", "status", "--json"])
+
+ assert result.exit_code != 0
+ payload = json.loads(result.output)
+ assert payload["unchecked_manifests"] == 1
+ assert payload["manifests"]["copilot"]["readable"] is False
+ assert payload["manifests"]["copilot"]["missing_files"] == []
+ assert payload["manifests"]["copilot"]["modified_files"] == []
+
+ def test_status_reports_modified_managed_files_without_failing(self, copilot_project):
+ manifest_path = copilot_project / ".specify" / "integrations" / "copilot.manifest.json"
+ tracked_files = json.loads(manifest_path.read_text(encoding="utf-8"))["files"]
+ first_rel = next(iter(tracked_files))
+ (copilot_project / first_rel).write_text("MODIFIED CONTENT\n", encoding="utf-8")
+
+ result = _run_in_project(copilot_project, ["integration", "status"])
+
+ assert result.exit_code == 0
+ assert "Integration status: WARNING" in result.output
+ assert "managed-files-modified" in result.output
+ assert "Modified managed files: 1" in result.output
+
+ def test_status_reports_missing_managed_files(self, copilot_project):
+ manifest_path = copilot_project / ".specify" / "integrations" / "copilot.manifest.json"
+ tracked_files = json.loads(manifest_path.read_text(encoding="utf-8"))["files"]
+ first_rel = next(iter(tracked_files))
+ (copilot_project / first_rel).unlink()
+
+ result = _run_in_project(copilot_project, ["integration", "status"])
+
+ assert result.exit_code != 0
+ assert "managed-files-missing" in result.output
+ assert "Missing managed files: 1" in result.output
+
+ def test_status_reports_missing_shared_managed_files(self, copilot_project):
+ shared_file = copilot_project / ".specify" / "scripts" / "bash" / "common.sh"
+ assert shared_file.exists()
+ shared_file.unlink()
+
+ result = _run_in_project(copilot_project, ["integration", "status"])
+
+ assert result.exit_code != 0
+ assert "managed-files-missing" in result.output
+ assert "shared Spec Kit infrastructure" in result.output
+ assert "Missing managed files: 1" in result.output
+
+ def test_status_does_not_use_exists_precheck_for_managed_files(self, tmp_path, monkeypatch):
+ from specify_cli.integration_status import _manifest_file_status
+ from specify_cli.integrations.manifest import IntegrationManifest
+
+ project = tmp_path / "proj"
+ project.mkdir()
+ tracked = project / "tracked.md"
+ tracked.write_text("content\n", encoding="utf-8")
+ manifest = IntegrationManifest("test", project, version="test")
+ manifest.record_existing("tracked.md")
+
+ def fail_exists(self):
+ raise AssertionError(f"Path.exists() should not be used for {self}")
+
+ monkeypatch.setattr(Path, "exists", fail_exists)
+
+ missing, modified, invalid, valid = _manifest_file_status(
+ manifest,
+ project.resolve(),
+ )
+
+ assert missing == []
+ assert modified == []
+ assert invalid == []
+ assert valid == ["tracked.md"]
+
+ def test_status_does_not_use_exists_precheck_for_manifest_load(self, copilot_project, monkeypatch):
+ def fail_exists(self):
+ raise AssertionError(f"Path.exists() should not be used for {self}")
+
+ monkeypatch.setattr(Path, "exists", fail_exists)
+
+ result = _run_in_project(copilot_project, ["integration", "status", "--json"])
+
+ assert result.exit_code == 0
+ payload = json.loads(result.output)
+ assert payload["status"] == "ok"
+ assert payload["manifests"]["copilot"]["readable"] is True
+
+ def test_status_reports_unresolved_project_root_without_crashing(self, copilot_project, monkeypatch):
+ original_resolve = Path.resolve
+ failed = {"done": False}
+
+ def fail_first_project_root_resolve(self, *args, **kwargs):
+ if self == copilot_project and not failed["done"]:
+ failed["done"] = True
+ raise RuntimeError("symlink loop")
+ return original_resolve(self, *args, **kwargs)
+
+ monkeypatch.setattr(Path, "resolve", fail_first_project_root_resolve)
+
+ result = _run_in_project(copilot_project, ["integration", "status", "--json"])
+
+ assert result.exit_code == 0
+ payload = json.loads(result.output)
+ assert payload["status"] == "warning"
+ assert any(item["code"] == "project-root-unresolved" for item in payload["findings"])
+
+ def test_status_loads_manifests_when_project_root_resolution_keeps_failing(
+ self,
+ copilot_project,
+ monkeypatch,
+ ):
+ original_resolve = Path.resolve
+
+ def fail_project_root_resolve(self, *args, **kwargs):
+ if self == copilot_project:
+ raise RuntimeError("symlink loop")
+ return original_resolve(self, *args, **kwargs)
+
+ monkeypatch.setattr(Path, "resolve", fail_project_root_resolve)
+
+ result = _run_in_project(copilot_project, ["integration", "status", "--json"])
+
+ assert result.exit_code == 0, result.output
+ payload = json.loads(result.output)
+ assert payload["status"] == "warning"
+ assert payload["manifests"]["copilot"]["readable"] is True
+ assert payload["manifests"]["speckit"]["readable"] is True
+ assert any(item["code"] == "project-root-unresolved" for item in payload["findings"])
+
+ def test_status_uses_lexical_manifest_paths_when_project_root_resolution_falls_back(self, tmp_path):
+ from specify_cli.integration_status import _manifest_file_status
+ from specify_cli.integrations.manifest import IntegrationManifest
+
+ real_project = tmp_path / "real-project"
+ real_project.mkdir()
+ tracked = real_project / "tracked.md"
+ tracked.write_text("content\n", encoding="utf-8")
+ symlinked_project = tmp_path / "symlinked-project"
+ try:
+ symlinked_project.symlink_to(real_project, target_is_directory=True)
+ except OSError as exc:
+ pytest.skip(f"symlinks unavailable: {exc}")
+
+ manifest = IntegrationManifest("test", real_project, version="test")
+ manifest.record_existing("tracked.md")
+ manifest.project_root = symlinked_project.absolute()
+
+ missing, modified, invalid, valid = _manifest_file_status(
+ manifest,
+ symlinked_project.absolute(),
+ project_root_is_resolved=False,
+ )
+
+ assert missing == []
+ assert modified == []
+ assert invalid == []
+ assert valid == ["tracked.md"]
+
+ def test_status_treats_resolve_runtime_error_as_invalid_path(self, tmp_path, monkeypatch):
+ from specify_cli.integration_status import _manifest_file_status
+ from specify_cli.integrations.manifest import IntegrationManifest
+
+ project = tmp_path / "proj"
+ project.mkdir()
+ tracked = project / "tracked.md"
+ tracked.write_text("content\n", encoding="utf-8")
+ manifest = IntegrationManifest("test", project, version="test")
+ manifest.record_existing("tracked.md")
+ project_root_resolved = project.resolve()
+ original_resolve = Path.resolve
+
+ def fail_project_parent_resolve(self, *args, **kwargs):
+ if self == project:
+ raise RuntimeError("symlink loop")
+ return original_resolve(self, *args, **kwargs)
+
+ monkeypatch.setattr(Path, "resolve", fail_project_parent_resolve)
+
+ missing, modified, invalid, valid = _manifest_file_status(
+ manifest,
+ project_root_resolved,
+ )
+
+ assert missing == []
+ assert modified == []
+ assert invalid == ["tracked.md"]
+ assert valid == []
+
+ def test_status_does_not_mask_runtime_errors_from_manifest_load(self, copilot_project, monkeypatch):
+ from specify_cli import integration_status as status_module
+
+ def fail_load(key, project_root, **kwargs):
+ raise RuntimeError(f"unexpected manifest loader bug for {key}")
+
+ monkeypatch.setattr(status_module.IntegrationManifest, "load", fail_load)
+
+ with pytest.raises(RuntimeError, match="unexpected manifest loader bug"):
+ status_module.build_integration_status_report(copilot_project)
+
+ def test_status_treats_dangling_symlink_as_missing(self, copilot_project):
+ manifest_path = copilot_project / ".specify" / "integrations" / "copilot.manifest.json"
+ tracked_files = json.loads(manifest_path.read_text(encoding="utf-8"))["files"]
+ first_rel = next(iter(tracked_files))
+ target = copilot_project / first_rel
+ target.unlink()
+ try:
+ target.symlink_to(copilot_project / "missing-target")
+ except OSError as exc:
+ pytest.skip(f"symlinks unavailable: {exc}")
+
+ result = _run_in_project(copilot_project, ["integration", "status", "--json"])
+
+ assert result.exit_code != 0
+ payload = json.loads(result.output)
+ assert first_rel in payload["manifests"]["copilot"]["missing_files"]
+ assert first_rel not in payload["manifests"]["copilot"]["modified_files"]
+
+ def test_status_treats_windows_style_dangling_symlink_as_missing(self, tmp_path, monkeypatch):
+ from specify_cli.integration_status import _manifest_file_status
+ from specify_cli.integrations.manifest import IntegrationManifest
+
+ project = tmp_path / "proj"
+ project.mkdir()
+ tracked = project / "tracked.md"
+ tracked.write_text("content\n", encoding="utf-8")
+ regular_stat = tracked.lstat()
+
+ manifest = IntegrationManifest("test", project, version="test")
+ manifest.record_existing("tracked.md")
+
+ tracked.unlink()
+ try:
+ tracked.symlink_to(project / "missing-target")
+ except OSError as exc:
+ pytest.skip(f"symlinks unavailable: {exc}")
+
+ original_lstat = Path.lstat
+ original_is_symlink = Path.is_symlink
+
+ def windows_style_lstat(self):
+ if self == tracked:
+ return regular_stat
+ return original_lstat(self)
+
+ def windows_style_is_symlink(self):
+ if self == tracked:
+ return True
+ return original_is_symlink(self)
+
+ monkeypatch.setattr(Path, "lstat", windows_style_lstat)
+ monkeypatch.setattr(Path, "is_symlink", windows_style_is_symlink)
+
+ missing, modified, invalid, valid = _manifest_file_status(
+ manifest,
+ project.resolve(),
+ )
+
+ assert missing == ["tracked.md"]
+ assert modified == []
+ assert invalid == []
+ assert valid == ["tracked.md"]
+
+ def test_strip_extended_length_prefix_normalizes_windows_paths(self):
+ from specify_cli.integration_status import _strip_extended_length_prefix
+
+ # Build the prefixed strings explicitly so the test is meaningful on
+ # every platform (POSIX won't parse backslash separators, but the
+ # helper operates on the string form). Compare Path objects rather than
+ # their str() form: on Windows pathlib renders a UNC root with a
+ # trailing separator (``\\server\share\``), so an exact string match is
+ # brittle, whereas Path equality captures the intended semantics on
+ # both POSIX and Windows.
+ bs = "\\"
+ assert _strip_extended_length_prefix(
+ Path(f"{bs}{bs}?{bs}C:{bs}proj")
+ ) == Path(f"C:{bs}proj")
+ assert _strip_extended_length_prefix(
+ Path(f"{bs}{bs}?{bs}UNC{bs}server{bs}share")
+ ) == Path(f"{bs}{bs}server{bs}share")
+ # Paths without the prefix are returned unchanged.
+ assert _strip_extended_length_prefix(Path("relative/path")) == Path("relative/path")
+
+ def test_is_within_project_tolerates_extended_length_prefix(self):
+ from specify_cli.integration_status import _is_within_project
+
+ # A readlink result on POSIX never carries the prefix, so an in-project
+ # child is contained and an outside path is not. The Windows
+ # prefix-stripping branch is exercised by the dangling-symlink tests on
+ # Windows CI; here we lock in the cross-platform containment contract.
+ root = Path("/tmp/project").resolve()
+ assert _is_within_project(root, root / "child")
+ assert not _is_within_project(root, Path("/tmp/other").resolve())
+
+ def test_status_reports_unsafe_manifest_paths_without_hashing_them(self, tmp_path, copilot_project):
+ outside = tmp_path / "outside"
+ outside.mkdir()
+ (outside / "secret.txt").write_text("outside project\n", encoding="utf-8")
+ link = copilot_project / "outside-link"
+ try:
+ link.symlink_to(outside, target_is_directory=True)
+ except OSError as exc:
+ pytest.skip(f"symlinks unavailable: {exc}")
+
+ manifest_path = copilot_project / ".specify" / "integrations" / "copilot.manifest.json"
+ manifest_data = json.loads(manifest_path.read_text(encoding="utf-8"))
+ manifest_data["files"]["outside-link/secret.txt"] = "wrong"
+ manifest_path.write_text(json.dumps(manifest_data), encoding="utf-8")
+
+ result = _run_in_project(copilot_project, ["integration", "status", "--json"])
+
+ assert result.exit_code != 0
+ payload = json.loads(result.output)
+ assert payload["invalid_manifest_paths"] == 1
+ assert "outside-link/secret.txt" in payload["manifests"]["copilot"]["invalid_files"]
+ assert "outside-link/secret.txt" not in payload["manifests"]["copilot"]["modified_files"]
+
+ def test_status_reports_tracked_symlink_target_escape_as_invalid(self, tmp_path, copilot_project, monkeypatch):
+ outside = tmp_path / "outside"
+ outside.mkdir()
+ outside_file = outside / "secret.txt"
+ outside_file.write_text("outside project\n", encoding="utf-8")
+
+ manifest_path = copilot_project / ".specify" / "integrations" / "copilot.manifest.json"
+ tracked_files = json.loads(manifest_path.read_text(encoding="utf-8"))["files"]
+ first_rel = next(iter(tracked_files))
+ tracked_path = copilot_project / first_rel
+ tracked_path.unlink()
+ try:
+ tracked_path.symlink_to(outside_file)
+ except OSError as exc:
+ pytest.skip(f"symlinks unavailable: {exc}")
+
+ original_stat = Path.stat
+
+ def fail_tracked_symlink_stat(self, *args, **kwargs):
+ follows_symlinks = kwargs.get("follow_symlinks", True)
+ if self == tracked_path and follows_symlinks:
+ raise AssertionError("Path.stat() should not follow tracked symlinks")
+ return original_stat(self, *args, **kwargs)
+
+ monkeypatch.setattr(Path, "stat", fail_tracked_symlink_stat)
+
+ result = _run_in_project(copilot_project, ["integration", "status", "--json"])
+
+ assert result.exit_code != 0
+ payload = json.loads(result.output)
+ assert payload["invalid_manifest_paths"] == 1
+ assert first_rel in payload["manifests"]["copilot"]["invalid_files"]
+ assert first_rel not in payload["manifests"]["copilot"]["modified_files"]
+
+ def test_status_reports_unsafe_multi_install_combination(self, copilot_project):
+ from specify_cli.integrations.manifest import IntegrationManifest
+
+ state_path = copilot_project / ".specify" / "integration.json"
+ state = json.loads(state_path.read_text(encoding="utf-8"))
+ state["installed_integrations"] = ["copilot", "claude"]
+ state["default_integration"] = "copilot"
+ state["integration"] = "copilot"
+ state_path.write_text(json.dumps(state), encoding="utf-8")
+ IntegrationManifest("claude", copilot_project, version="test").save()
+
+ result = _run_in_project(copilot_project, ["integration", "status"])
+
+ assert result.exit_code != 0
+ assert "unsafe-multi-install" in result.output
+ assert "Multi-install safe: no" in result.output
+ assert "specify integration switch <key>" in result.output
+
+ def test_status_treats_unknown_multi_install_as_unsafe(self, claude_project):
+ from specify_cli.integrations.manifest import IntegrationManifest
+
+ state_path = claude_project / ".specify" / "integration.json"
+ state = json.loads(state_path.read_text(encoding="utf-8"))
+ state["installed_integrations"] = ["claude", "mystery"]
+ state["default_integration"] = "claude"
+ state["integration"] = "claude"
+ state_path.write_text(json.dumps(state), encoding="utf-8")
+ IntegrationManifest("mystery", claude_project, version="test").save()
+
+ result = _run_in_project(claude_project, ["integration", "status"])
+
+ assert result.exit_code != 0
+ assert "unknown-integration" in result.output
+ assert "unsafe-multi-install" in result.output
+ assert "remove the stale integration entry" in result.output
+ assert "Multi-install safe: no" in result.output
+
+ def test_status_gives_actionable_suggestion_for_unknown_manifest(self, claude_project):
+ state_path = claude_project / ".specify" / "integration.json"
+ state = json.loads(state_path.read_text(encoding="utf-8"))
+ state["installed_integrations"] = ["mystery"]
+ state["default_integration"] = "mystery"
+ state["integration"] = "mystery"
+ state_path.write_text(json.dumps(state), encoding="utf-8")
+
+ result = _run_in_project(claude_project, ["integration", "status", "--json"])
+
+ assert result.exit_code != 0
+ payload = json.loads(result.output)
+ manifest_finding = next(
+ item for item in payload["findings"]
+ if item["code"] == "manifest-missing" and item["integration"] == "mystery"
+ )
+ assert "remove the stale integration entry" in manifest_finding["suggestion"]
+ assert "integration upgrade mystery" not in manifest_finding["suggestion"]
+
+ def test_status_rejects_unsafe_integration_keys_before_manifest_lookup(self, tmp_path, claude_project):
+ state_path = claude_project / ".specify" / "integration.json"
+ unsafe_key = "../../../escape"
+ state_path.write_text(
+ json.dumps({
+ "integration": unsafe_key,
+ "default_integration": unsafe_key,
+ "installed_integrations": [unsafe_key],
+ }),
+ encoding="utf-8",
+ )
+ outside_manifest = tmp_path / "escape.manifest.json"
+ outside_manifest.write_text(
+ json.dumps({"integration": unsafe_key, "files": {}}),
+ encoding="utf-8",
+ )
+
+ result = _run_in_project(claude_project, ["integration", "status", "--json"])
+
+ assert result.exit_code != 0
+ payload = json.loads(result.output)
+ assert unsafe_key not in payload["manifests"]
+ assert payload["manifest_checked_integrations"] == ["speckit"]
+ assert any(
+ item["code"] == "integration-key-invalid"
+ and item["integration"] == unsafe_key
+ for item in payload["findings"]
+ )
+
+ def test_status_rejects_filename_invalid_integration_keys(self, claude_project):
+ state_path = claude_project / ".specify" / "integration.json"
+ unsafe_key = "bad:key"
+ state_path.write_text(
+ json.dumps({
+ "integration": unsafe_key,
+ "default_integration": unsafe_key,
+ "installed_integrations": [unsafe_key],
+ }),
+ encoding="utf-8",
+ )
+
+ result = _run_in_project(claude_project, ["integration", "status", "--json"])
+
+ assert result.exit_code != 0
+ payload = json.loads(result.output)
+ assert any(
+ item["code"] == "integration-key-invalid"
+ and item["integration"] == unsafe_key
+ for item in payload["findings"]
+ )
+
+ def test_status_rejects_windows_reserved_integration_keys(self, claude_project):
+ state_path = claude_project / ".specify" / "integration.json"
+ unsafe_key = "CON"
+ state_path.write_text(
+ json.dumps({
+ "integration": unsafe_key,
+ "default_integration": unsafe_key,
+ "installed_integrations": [unsafe_key],
+ }),
+ encoding="utf-8",
+ )
+
+ result = _run_in_project(claude_project, ["integration", "status", "--json"])
+
+ assert result.exit_code != 0
+ payload = json.loads(result.output)
+ assert any(
+ item["code"] == "integration-key-invalid"
+ and item["integration"] == unsafe_key
+ for item in payload["findings"]
+ )
+
+ def test_status_reports_managed_file_collisions(self, claude_project):
+ from specify_cli.integrations.manifest import IntegrationManifest
+
+ state_path = claude_project / ".specify" / "integration.json"
+ state = json.loads(state_path.read_text(encoding="utf-8"))
+ state["installed_integrations"] = ["claude", "codex"]
+ state["default_integration"] = "claude"
+ state["integration"] = "claude"
+ state_path.write_text(json.dumps(state), encoding="utf-8")
+
+ claude_manifest = claude_project / ".specify" / "integrations" / "claude.manifest.json"
+ tracked_files = json.loads(claude_manifest.read_text(encoding="utf-8"))["files"]
+ shared_rel = next(iter(tracked_files))
+ codex_manifest = IntegrationManifest("codex", claude_project, version="test")
+ codex_manifest.record_existing(shared_rel)
+ codex_manifest.save()
+
+ result = _run_in_project(claude_project, ["integration", "status"])
+
+ assert result.exit_code == 0
+ assert "managed-file-collision" in result.output
+ assert "Integration status: WARNING" in result.output
+
+ def test_status_json_is_not_rich_rendered(self, tmp_path, monkeypatch):
+ project = tmp_path / "proj"
+ project.mkdir()
+ (project / ".specify").mkdir()
+ (project / ".specify" / "integration.json").write_text(
+ json.dumps({
+ "integration": "[red]x[/red]",
+ "installed_integrations": ["[red]x[/red]"],
+ }),
+ encoding="utf-8",
+ )
+ monkeypatch.chdir(project)
+
+ result = runner.invoke(app, ["integration", "status", "--json"])
+
+ assert result.exit_code != 0
+ payload = json.loads(result.output)
+ assert payload["default_integration"] == "[red]x[/red]"
+ assert payload["installed_integrations"] == ["[red]x[/red]"]
+
+ def test_status_text_escapes_rich_markup_from_project_state(self, tmp_path, monkeypatch):
+ project = tmp_path / "proj"
+ project.mkdir()
+ (project / ".specify").mkdir()
+ (project / ".specify" / "integration.json").write_text(
+ json.dumps({
+ "integration": "[red]x[/red]",
+ "installed_integrations": ["[red]x[/red]"],
+ }),
+ encoding="utf-8",
+ )
+ monkeypatch.chdir(project)
+
+ result = runner.invoke(app, ["integration", "status"])
+
+ assert result.exit_code != 0
+ assert "Default integration: [red]x[/red]" in result.output
+ assert "Installed integrations: [red]x[/red]" in result.output
+
+
# ── install ──────────────────────────────────────────────────────────