π« 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.mdindex 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 OptionsSome integrations accept additional options via `--integration-options`:diff --git a/src/specify_cli/integration_state.py b/src/specify_cli/integration_state.pyindex 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, errorreturn 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.pynew file mode 100644index 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.pyindex 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 jsonimport os-from typing import Optional+from typing import Any, Optionalimport typer+from rich.markup import escape as _rich_escapefrom rich.table import Tablefrom .._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.pyindex 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 = versionself._files: dict[str, str] = {} # rel_path β sha256 hexself._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_pathtry:data = json.loads(path.read_text(encoding="utf-8"))diff --git a/tests/integrations/test_integration_subcommand.py b/tests/integrations/test_integration_subcommand.pyindex c614d691f..8c486ce2d 100644--- a/tests/integrations/test_integration_subcommand.py+++ b/tests/integrations/test_integration_subcommand.py@@ -2,7 +2,10 @@import jsonimport os+import shutil+from pathlib import Path+import pytestfrom typer.testing import CliRunnerfrom 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 ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ