π« Toolkit to help you get started with SDD or any other process!
"""specify integration helpers β internal utilities shared across command modules."""
from __future__ import annotations
import os
from pathlib import Path
from typing import Any, Callable
import typer
from rich.markup import escape
from .._agent_config import SCRIPT_TYPE_CHOICES
from .._console import console
from ..integration_runtime import (
invoke_prefix_for_integration as _invoke_prefix_for_integration,
invoke_separator_for_integration as _invoke_separator_for_integration,
resolve_integration_options as _resolve_integration_options_impl,
with_integration_setting as _with_integration_setting,
)
from ..integration_state import (
INTEGRATION_JSON,
INTEGRATION_STATE_SCHEMA,
integration_setting as _integration_setting,
try_read_integration_json as _try_read_integration_json,
write_integration_json as _write_integration_json_file,
)
def _get_speckit_version() -> str:
"""Return the current Spec Kit version.
Resolved lazily through ``_commands.get_speckit_version`` so that tests
that monkeypatch ``specify_cli.integrations._commands.get_speckit_version``
still affect helpers called from the command handlers.
"""
from . import _commands # noqa: PLC0415 β intentional late import to avoid circular + enable patching
return _commands.get_speckit_version()
# ---------------------------------------------------------------------------
# JSON read / write helpers
# ---------------------------------------------------------------------------
def _read_integration_json(project_root: Path) -> dict[str, Any]:
"""Load ``.specify/integration.json``. Returns normalized state when present.
Delegates the parse / schema-guard logic to the shared
:func:`_try_read_integration_json` helper so the CLI and workflow engine
cannot drift on validation rules. Each error variant is translated into
the existing loud-fail UX (console message + ``typer.Exit(1)``).
"""
path = project_root / INTEGRATION_JSON
state, error = _try_read_integration_json(project_root)
if error is None:
return state or {}
if error.kind == "decode":
console.print(f"[red]Error:[/red] {path} contains invalid JSON or is not valid UTF-8.")
console.print(f"Please fix or delete {INTEGRATION_JSON} and retry.")
console.print(f"[dim]Details:[/dim] {error.detail}")
elif error.kind == "os":
console.print(f"[red]Error:[/red] Could not read {path}.")
console.print(f"Please fix file permissions or delete {INTEGRATION_JSON} and retry.")
console.print(f"[dim]Details:[/dim] {error.detail}")
elif error.kind == "not_object":
console.print(
f"[red]Error:[/red] {path} must contain a JSON object, got {error.detail}."
)
console.print(f"Please fix or delete {INTEGRATION_JSON} and retry.")
elif error.kind == "schema_too_new":
console.print(
f"[red]Error:[/red] {path} uses integration state schema {error.schema}, "
f"but this CLI only supports schema {INTEGRATION_STATE_SCHEMA}."
)
console.print("Please upgrade Spec Kit before modifying integrations.")
raise typer.Exit(1)
def _write_integration_json(
project_root: Path,
integration_key: str | None,
installed_integrations: list[str] | None = None,
integration_settings: dict[str, dict[str, Any]] | None = None,
) -> None:
"""Write ``.specify/integration.json`` with legacy-compatible state."""
_write_integration_json_file(
project_root,
version=_get_speckit_version(),
integration_key=integration_key,
installed_integrations=installed_integrations,
settings=integration_settings,
)
# ---------------------------------------------------------------------------
# init-options.json helpers
# ---------------------------------------------------------------------------
def _refresh_init_options_speckit_version(project_root: Path) -> None:
"""Refresh only the Spec Kit version recorded in init-options.json."""
from .. import save_init_options
from .._file_policy import read_project_options
opts = read_project_options(project_root)
if not isinstance(opts, dict) or not opts:
return
opts["speckit_version"] = _get_speckit_version()
save_init_options(project_root, opts)
def _clear_init_options_for_integration(project_root: Path, integration_key: str) -> None:
"""Clear active integration keys from init-options.json when they match."""
from .. import save_init_options
from .._file_policy import read_project_options
opts = read_project_options(project_root)
if opts.get("integration") == integration_key or opts.get("ai") == integration_key:
opts.pop("integration", None)
opts.pop("ai", None)
opts.pop("ai_skills", None)
save_init_options(project_root, opts)
def _remove_integration_json(project_root: Path) -> None:
"""Remove ``.specify/integration.json`` if it exists."""
path = project_root / INTEGRATION_JSON
from ._file_changes import after_file_change, before_file_change
before_file_change(path, removal=True)
path.unlink(missing_ok=True)
after_file_change(path)
# ---------------------------------------------------------------------------
# Error sentinels
# ---------------------------------------------------------------------------
_MANIFEST_READ_ERRORS = (ValueError, FileNotFoundError, OSError, UnicodeDecodeError)
class _SharedTemplateRefreshError(RuntimeError):
"""Raised when default integration metadata should not be persisted."""
# ---------------------------------------------------------------------------
# Script type resolution
# ---------------------------------------------------------------------------
def _normalize_script_type(script_type: str, source: str) -> str:
"""Normalize and validate a script type from CLI/config sources."""
normalized = script_type.strip().lower()
if normalized in SCRIPT_TYPE_CHOICES:
return normalized
console.print(
f"[red]Error:[/red] Invalid script type {script_type!r} from {source}. "
f"Expected one of: {', '.join(sorted(SCRIPT_TYPE_CHOICES.keys()))}."
)
raise typer.Exit(1)
def _resolve_script_type(project_root: Path, script_type: str | None) -> str:
"""Resolve the script type from the CLI flag or init-options.json."""
from .. import load_init_options
if script_type:
return _normalize_script_type(script_type, "--script")
opts = load_init_options(project_root)
saved = opts.get("script")
if isinstance(saved, str) and saved.strip():
return _normalize_script_type(saved, ".specify/init-options.json")
return "ps" if os.name == "nt" else "sh"
def _resolve_integration_script_type(
project_root: Path,
state: dict[str, Any],
key: str,
script_type: str | None = None,
) -> str:
"""Resolve script type for an integration, preferring stored settings."""
if script_type:
return _normalize_script_type(script_type, "--script")
stored = _integration_setting(state, key).get("script")
if isinstance(stored, str) and stored.strip():
return _normalize_script_type(stored, f"{INTEGRATION_JSON} integration_settings.{key}.script")
return _resolve_script_type(project_root, None)
# ---------------------------------------------------------------------------
# Integration options
# ---------------------------------------------------------------------------
def _parse_integration_options(integration: Any, raw_options: str) -> dict[str, Any] | None:
"""Parse --integration-options string into a dict matching the integration's declared options.
Returns ``None`` when no options are provided.
"""
import shlex
parsed: dict[str, Any] = {}
try:
tokens = shlex.split(raw_options)
except ValueError as exc:
# An unbalanced quote (e.g. --integration-options='--commands-dir "foo')
# makes shlex raise "No closing quotation". Translate it into the same
# clean exit-1 UX as every other bad-input path below rather than
# letting a raw traceback escape.
console.print(f"[red]Error:[/red] Could not parse integration options: {exc}.")
raise typer.Exit(1)
declared_options = list(integration.options())
declared = {opt.name.lstrip("-"): opt for opt in declared_options}
allowed = ", ".join(sorted(opt.name for opt in declared_options))
i = 0
while i < len(tokens):
token = tokens[i]
if not token.startswith("-"):
console.print(f"[red]Error:[/red] Unexpected integration option value '{escape(token)}'.")
if allowed:
console.print(f"Allowed options: {allowed}")
raise typer.Exit(1)
name = token.lstrip("-")
value: str | None = None
# Handle --name=value syntax
if "=" in name:
name, value = name.split("=", 1)
opt = declared.get(name)
if not opt:
console.print(f"[red]Error:[/red] Unknown integration option '{escape(token)}'.")
if allowed:
console.print(f"Allowed options: {allowed}")
raise typer.Exit(1)
key = name.replace("-", "_")
if opt.is_flag:
if value is not None:
console.print(f"[red]Error:[/red] Option '{opt.name}' is a flag and does not accept a value.")
raise typer.Exit(1)
parsed[key] = True
i += 1
elif value is not None:
parsed[key] = value
i += 1
elif i + 1 < len(tokens) and not tokens[i + 1].startswith("-"):
parsed[key] = tokens[i + 1]
i += 2
else:
console.print(f"[red]Error:[/red] Option '{opt.name}' requires a value.")
raise typer.Exit(1)
return parsed or None
def _resolve_integration_options(
integration: Any,
state: dict[str, Any],
key: str,
raw_options: str | None,
) -> tuple[str | None, dict[str, Any] | None]:
"""Resolve raw and parsed options for an integration operation."""
return _resolve_integration_options_impl(
integration,
state,
key,
raw_options,
parse_options=_parse_integration_options,
)
def _update_init_options_for_integration(
project_root: Path,
integration: Any,
script_type: str | None = None,
parsed_options: dict[str, Any] | None = None,
) -> None:
"""Update init-options.json to reflect *integration* as the active one.
Agent context/instruction files are owned entirely by the opt-in
agent-context extension, so this function never touches the extension
or its config.
"""
from .. import save_init_options
from .._file_policy import read_project_options
opts = read_project_options(project_root)
opts["integration"] = integration.key
opts["ai"] = integration.key
opts["speckit_version"] = _get_speckit_version()
if script_type:
opts["script"] = script_type
# Whether skills mode is active is owned by each integration via the
# ``is_skills_mode`` hook (base default honors ``--skills``;
# SkillsIntegration returns True; skills-first integrations with a legacy
# opt-out such as Bob override it). This keeps shared code free of
# ``isinstance`` / ``_skills_mode`` probing. Passing parsed_options lets it
# work on the ``use``/``install`` path where no setup() runs (issue #3550).
if integration.is_skills_mode(parsed_options, project_root=project_root):
opts["ai_skills"] = True
else:
opts.pop("ai_skills", None)
save_init_options(project_root, opts)
# ---------------------------------------------------------------------------
# Default integration persistence
# ---------------------------------------------------------------------------
def _set_default_integration(
project_root: Path,
state: dict[str, Any],
key: str,
integration: Any,
installed_keys: list[str],
*,
script_type: str | None = None,
raw_options: str | None = None,
parsed_options: dict[str, Any] | None = None,
refresh_templates: bool = True,
refresh_templates_force: bool = False,
refresh_hint: str | None = None,
) -> None:
"""Persist *key* as default and align active runtime metadata."""
from .. import _install_shared_infra
resolved_script = _resolve_integration_script_type(project_root, state, key, script_type)
settings = _with_integration_setting(
state,
key,
integration,
script_type=resolved_script,
raw_options=raw_options,
parsed_options=parsed_options,
project_root=project_root,
)
if refresh_templates:
try:
_install_shared_infra(
project_root,
resolved_script,
invoke_separator=_invoke_separator_for_integration(
integration, {"integration_settings": settings}, key, parsed_options,
project_root=project_root,
),
invoke_prefix=_invoke_prefix_for_integration(
integration, key, parsed_options, project_root
),
force=refresh_templates_force,
refresh_managed=True,
refresh_hint=refresh_hint,
)
except (ValueError, OSError) as exc:
raise _SharedTemplateRefreshError(
f"Failed to refresh shared infrastructure for '{key}': {exc}"
) from exc
_write_integration_json(project_root, key, installed_keys, settings)
_update_init_options_for_integration(
project_root, integration, script_type=resolved_script, parsed_options=parsed_options
)
def _set_default_integration_or_exit(*args: Any, **kwargs: Any) -> None:
try:
_set_default_integration(*args, **kwargs)
except _SharedTemplateRefreshError as exc:
console.print(f"[red]Error:[/red] {exc}")
raise typer.Exit(1)
# ---------------------------------------------------------------------------
# Extension (un)registration helpers (shared by use / switch / upgrade)
# ---------------------------------------------------------------------------
def _best_effort_extension_op(
project_root: Path,
agent_key: str,
op: Callable[[Any, str], None],
*,
phase: str,
continuing: str,
) -> None:
"""Run a best-effort ``ExtensionManager`` operation for ``agent_key``.
``op`` receives the ``ExtensionManager`` and ``agent_key``. Any failure is
surfaced as a warning via ``_print_cli_warning`` and never aborts the
surrounding integration operation. ``continuing`` describes what already
succeeded so the warning makes the partial outcome clear.
"""
try:
from ..extensions import ExtensionManager
ext_mgr = ExtensionManager(project_root)
op(ext_mgr, agent_key)
except Exception as ext_err:
from .. import _print_cli_warning
_print_cli_warning(phase, "integration", agent_key, ext_err, continuing=continuing)
def _register_extensions_for_agent(
project_root: Path,
agent_key: str,
*,
continuing: str,
force: bool = False,
) -> None:
"""Register all enabled extensions' commands/skills for ``agent_key``.
``use`` / ``switch`` re-register enabled extensions for the agent they
activate (rescaffold); ``upgrade`` does so only for the *active*
integration. Plain ``install`` and upgrade of a non-active integration
deliberately skip this helper so a secondary integration has no extension
side effects until it is selected. See issues #2886 and #2948.
Callers always pass the active agent (use/switch activate the target
before registering), so extension *skill* rendering β which is scoped to
the active ``ai`` / ``ai_skills`` init-options β matches ``agent_key``.
When ``force=True``, existing skill files are overwritten even when they
are not dev-mode symlinks. Pass ``force=True`` in the upgrade path so that
extension content is layered on top of the core-template files that
``setup()`` just regenerated (fixes the skip-guard bug for skills mode).
Best-effort: never aborts the surrounding integration operation. Callers
invoke it *after* the use/upgrade/switch transaction has committed so a
failure here cannot trigger a rollback.
"""
_best_effort_extension_op(
project_root,
agent_key,
lambda mgr, key: mgr.register_enabled_extensions_for_agent(key, force=force),
phase="register extension artifacts for",
continuing=continuing,
)
def _unregister_extensions_for_agent(
project_root: Path,
agent_key: str,
*,
continuing: str,
) -> None:
"""Best-effort removal of ``agent_key``'s extension artifacts.
Used by ``switch`` when uninstalling the previous integration so its
extension command/skill files don't linger as orphans in the old agent's
directory.
"""
_best_effort_extension_op(
project_root,
agent_key,
lambda mgr, key: mgr.unregister_agent_artifacts(key),
phase="clean up extension artifacts for",
continuing=continuing,
)
def _register_presets_for_agent(
project_root: Path,
agent_key: str,
*,
continuing: str,
) -> None:
"""Register all enabled presets' command overrides/skills for ``agent_key``.
Presets follow the same single-active rule as extensions (#2948):
``use`` / ``switch`` re-register enabled presets for the agent they
activate (rescaffold), so a preset installed while a different
integration was active is not left targeting that inactive integration.
Best-effort: never aborts the surrounding integration operation.
"""
try:
from ..presets import PresetManager
preset_mgr = PresetManager(project_root)
preset_mgr.register_enabled_presets_for_agent(agent_key)
except Exception as preset_err:
from .. import _print_cli_warning
_print_cli_warning(
"register preset artifacts for",
"integration",
agent_key,
preset_err,
continuing=continuing,
)
def _snapshot_manifest_before_registration(
project_root: Path, agent_key: str,
) -> tuple[Any, set[str]]:
"""Snapshot an installed manifest's unmodified files before rescaffolding (#5078).
Same rules as ``check_modified()``, applied one file at a time after
``record_existing()``'s path check, so no file outside the project is
read. A path that fails the check or can't be read counts as modified,
with a warning: its hash isn't refreshed after registration.
"""
try:
from .manifest import IntegrationManifest, _sha256, _validate_record_path
manifest = IntegrationManifest.load(agent_key, project_root)
unmodified: set[str] = set()
for rel, expected_hash in manifest.files.items():
# RuntimeError is a symlink loop in Path.resolve() before 3.13.
try:
abs_path = _validate_record_path(Path(rel), manifest.project_root)
if not abs_path.exists() or (
abs_path.is_file() and _sha256(abs_path) == expected_hash
):
unmodified.add(rel)
except (OSError, RuntimeError, ValueError) as file_err:
from .. import _print_cli_warning
_print_cli_warning(
"snapshot manifest hash for",
"file",
rel,
file_err,
continuing="Its hash won't be refreshed after registration.",
)
return manifest, unmodified
except FileNotFoundError:
return None, set()
except Exception as manifest_err: # noqa: BLE001 - manifest refresh is best-effort
from .. import _print_cli_warning
_print_cli_warning(
"snapshot manifest hashes for",
"integration",
agent_key,
manifest_err,
continuing="Continuing without refreshing manifest hashes.",
)
return None, set()
def _resync_manifest_after_registration(
new_manifest: Any,
agent_key: str,
*,
continuing: str,
unmodified_files: set[str] | None = None,
) -> None:
"""Refresh tracked-file hashes after extensions/presets re-registration.
``_register_extensions_for_agent`` / ``_register_presets_for_agent`` run
after ``new_manifest`` is saved and can overwrite files it already
tracks (e.g. a preset overriding a core command rendered as a skill).
For ``upgrade`` (#4696) and a new-target ``switch`` (#5078), nothing else
touches the project between the manifest save and these calls, so any
tracked file whose bytes now differ was changed by registration. Re-hash
it so ``check_modified()`` doesn't misreport a legitimate override.
``use`` and installed-target ``switch`` reuse an older manifest (#5078).
They must pass ``unmodified_files`` from before registration; only those
files whose bytes changed are refreshed, preserving earlier user edits.
A new-target ``switch`` passes every tracked file, so files registration
didn't change keep their recovered markers.
Best-effort: registration itself is best-effort, so a failure here must
not abort the surrounding upgrade/use/switch transaction.
"""
try:
from .manifest import _sha256, _validate_record_path
changed = False
for rel, expected_hash in new_manifest.files.items():
if unmodified_files is not None and rel not in unmodified_files:
continue
abs_path = new_manifest.project_root / rel
try:
if abs_path.is_symlink() or not abs_path.is_file():
continue
# Only re-hash bytes registration changed: record_existing()
# also clears a file's recovered marker. Check the path the
# way record_existing() does before reading it.
if unmodified_files is not None and _sha256(
_validate_record_path(Path(rel), new_manifest.project_root)
) == expected_hash:
continue
new_manifest.record_existing(rel)
changed = True
except (ValueError, OSError, RuntimeError) as file_err:
from .. import _print_cli_warning
_print_cli_warning(
"resync manifest hash for",
"file",
str(rel),
file_err,
continuing="Continuing with the remaining files.",
)
continue
if changed:
new_manifest.save()
except Exception as resync_err:
from .. import _print_cli_warning
_print_cli_warning(
"resync manifest hashes for",
"integration",
agent_key,
resync_err,
continuing=continuing,
)
def _unregister_presets_for_agent(
project_root: Path,
agent_key: str,
*,
continuing: str,
) -> None:
"""Best-effort removal of ``agent_key``'s preset command/skill artifacts.
Mirrors ``_unregister_extensions_for_agent``: used by ``switch`` when
uninstalling the previous integration so its preset command overrides
and skill mirrors don't linger as orphans in the old agent's directory
once a different (possibly not-yet-installed) integration becomes
active (#2948).
Best-effort: never aborts the surrounding integration operation.
"""
try:
from ..presets import PresetManager
preset_mgr = PresetManager(project_root)
preset_mgr.unregister_agent_artifacts(agent_key)
except Exception as preset_err:
from .. import _print_cli_warning
_print_cli_warning(
"clean up preset artifacts for",
"integration",
agent_key,
preset_err,
continuing=continuing,
)
def _unregister_enabled_extension_commands_for_agent(
project_root: Path,
agent_key: str,
*,
continuing: str,
) -> None:
"""Best-effort removal of enabled extension command artifacts for ``agent_key``."""
_best_effort_extension_op(
project_root,
agent_key,
lambda mgr, key: mgr.unregister_agent_artifacts(
key,
enabled_only=True,
commands_only=True,
),
phase="clean up enabled extension command artifacts for",
continuing=continuing,
)
# ---------------------------------------------------------------------------
# CLI formatting helpers (re-exported from _commands.py)
# ---------------------------------------------------------------------------
def _cli_error_detail(exc: BaseException) -> str:
"""Return a compact one-line exception detail for CLI output."""
return str(exc).replace("\n", " ").strip() or exc.__class__.__name__
def _cli_phase_label(phase: str, target_kind: str, target: str | None = None) -> str:
"""Format a stable operation label for user-visible diagnostics."""
label = f"{phase} {target_kind}".strip()
if target:
label = f"{label} '{target}'"
return label