💫 Toolkit to help you get started with SDD or any other process!
"""The ``specify integration upgrade`` command and its layout guards."""
from __future__ import annotations
import os
from pathlib import PurePath
import typer
from rich.markup import escape
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,
with_integration_setting as _with_integration_setting,
)
from ..integration_state import default_integration_key as _default_integration_key, installed_integration_keys as _installed_integration_keys
from ._command_upgrade_layout import (
_PresetRegistryUnreadableError,
_installed_command_presets_affecting_agent,
_installed_presets_affecting_agent,
_legacy_command_root_changed,
_legacy_command_root_upgrade_pending,
_manifest_tracks_skill_layout,
)
from ._commands import integration_app
from ._lifecycle import external_lifecycle, lifecycle_success
from ._helpers import _MANIFEST_READ_ERRORS, _SharedTemplateRefreshError, _cli_error_detail, _cli_phase_label, _get_speckit_version, _read_integration_json, _refresh_init_options_speckit_version, _register_extensions_for_agent, _register_presets_for_agent, _resolve_integration_options, _resolve_integration_script_type, _resync_manifest_after_registration, _unregister_enabled_extension_commands_for_agent, _update_init_options_for_integration, _write_integration_json
@integration_app.command("upgrade")
@external_lifecycle("upgrade")
def integration_upgrade(
key: str | None = typer.Argument(None, help="Integration key to upgrade (default: current integration)"),
force: bool = typer.Option(False, "--force", help="Force upgrade even if files are modified"),
script: str | None = typer.Option(None, "--script", help="Script type: sh, ps, or py (default: from init-options.json or platform default)"),
integration_options: str | None = typer.Option(None, "--integration-options", help="Options for the integration"),
trust_integration: bool = typer.Option(False, "--trust-integration", help="Authorize executing a reviewed external integration update without prompting"),
):
"""Upgrade an integration by reinstalling with diff-aware file handling.
Compares manifest hashes to detect locally modified files and
blocks the upgrade unless --force is used.
"""
from . import get_integration
from .manifest import IntegrationManifest
from .. import _require_specify_project, _install_shared_infra_or_exit, _install_shared_infra
project_root = _require_specify_project()
current = _read_integration_json(project_root)
installed_key = _default_integration_key(current)
installed_keys = _installed_integration_keys(current)
if key is None:
if not installed_key:
console.print("[yellow]No integration is currently installed.[/yellow]")
raise typer.Exit(0)
key = installed_key
if key not in installed_keys:
console.print(f"[red]Error:[/red] Integration '{key}' is not installed.")
raise typer.Exit(1)
integration = get_integration(key)
if integration is None:
console.print(f"[red]Error:[/red] Unknown integration '{key}'")
raise typer.Exit(1)
manifest_path = project_root / ".specify" / "integrations" / f"{key}.manifest.json"
if not manifest_path.exists():
console.print(f"[yellow]No manifest found for integration '{key}'. Nothing to upgrade.[/yellow]")
console.print(f"Run [cyan]specify integration install {key}[/cyan] to perform a fresh install.")
raise typer.Exit(0)
try:
old_manifest = IntegrationManifest.load(key, project_root)
except _MANIFEST_READ_ERRORS as exc:
console.print(f"[red]Error:[/red] Integration manifest for '{key}' is unreadable: {exc}")
raise typer.Exit(1)
# Detect modified files via manifest hashes
modified = old_manifest.check_modified()
if modified and not force:
console.print(f"[yellow]âš [/yellow] {len(modified)} file(s) have been modified since installation:")
for rel in modified:
console.print(f" {rel}")
console.print("\nUse [cyan]--force[/cyan] to overwrite modified files, or resolve manually.")
raise typer.Exit(1)
selected_script = _resolve_integration_script_type(project_root, current, key, script)
# Build parsed options from --integration-options so the integration
# can determine its effective invoke separator before shared infra
# is installed.
raw_options, parsed_options = _resolve_integration_options(
integration, current, key, integration_options
)
legacy_command_root_upgrade_pending = _legacy_command_root_upgrade_pending(
integration,
old_manifest,
)
# Guard: Kilo's legacy command root moves from .kilocode/workflows to
# .kilo/commands. Preset command artifacts are tracked outside the
# integration manifest, and their agent-scoped rescaffold is best-effort,
# not transactional with command-root cleanup. Refuse before setup writes
# .kilo/commands rather than risking orphaned legacy files or missing
# registry-tracked overrides in the canonical directory.
if key == "kilocode" and legacy_command_root_upgrade_pending:
config = integration.registrar_config or {}
legacy = config.get("legacy_dir", "legacy command directory")
canonical = config.get("dir", "canonical command directory")
try:
affected_presets = _installed_command_presets_affecting_agent(
project_root,
key,
)
except _PresetRegistryUnreadableError as exc:
console.print(
f"[red]Error:[/red] Cannot migrate '{key}' command directory "
f"from [cyan]{legacy}[/cyan] to [cyan]{canonical}[/cyan]: "
"the preset registry could not be read to verify installed presets."
)
console.print(f"[dim]Details:[/dim] {_cli_error_detail(exc)}")
console.print(
"A command directory migration cannot reconcile preset command "
"artifacts while the preset registry state is unknown. Fix or "
"restore [cyan].specify/presets/.registry[/cyan] and retry."
)
raise typer.Exit(1)
if affected_presets:
preset_list = ", ".join(sorted(affected_presets))
console.print(
f"[red]Error:[/red] Cannot migrate '{key}' command directory "
f"from [cyan]{legacy}[/cyan] to [cyan]{canonical}[/cyan] while "
f"preset override(s) are installed: [bold]{preset_list}[/bold]."
)
console.print(
"Preset command artifacts cannot yet be reconciled across this "
"command directory migration, so the upgrade is refused before "
"changing files."
)
console.print(
"Remove the preset(s), run the upgrade, then reinstall them:\n"
f" [cyan]specify preset remove <id>[/cyan]\n"
f" [cyan]specify integration upgrade {key} --script {selected_script} --force[/cyan]\n"
f" [cyan]specify preset add <id>[/cyan]"
)
raise typer.Exit(1)
# Reject command↔skills layout changes while preset artifacts are tracked
# for the integration (review #3415). Preset rescaffolding is best-effort:
# an enabled preset can still have a missing/corrupt manifest or command
# source, or fail during a write. Phase 2 would otherwise delete the
# old-layout file before a replacement is known to exist. Refuse before
# any mutation; same-layout upgrades still rescaffold the active agent.
if _manifest_tracks_skill_layout(old_manifest) != integration.is_skills_mode(
parsed_options, project_root
):
try:
affected_presets = _installed_presets_affecting_agent(project_root, key)
except _PresetRegistryUnreadableError as exc:
console.print(
f"[red]Error:[/red] Cannot change '{key}' command layout: the "
f"preset registry could not be read to verify installed presets."
)
console.print(f"[dim]Details:[/dim] {_cli_error_detail(exc)}")
console.print(
"A layout change cannot reconcile preset artifacts, so the "
"migration is refused while the preset registry state is "
"unknown. Fix or restore "
"[cyan].specify/presets/.registry[/cyan] and retry."
)
raise typer.Exit(1)
if affected_presets:
preset_list = ", ".join(sorted(affected_presets))
console.print(
f"[red]Error:[/red] Cannot change '{key}' command layout while "
f"preset override(s) are installed: [bold]{preset_list}[/bold]."
)
console.print(
"Preset artifacts cannot be safely reconciled across a "
"command↔skills layout change, so the migration is refused "
"before changing files."
)
console.print(
"Remove the preset(s), run the upgrade, then reinstall them:\n"
f" [cyan]specify preset remove <id>[/cyan]\n"
f" [cyan]specify integration upgrade {key} "
f"--integration-options \"...\"[/cyan]\n"
f" [cyan]specify preset add <id>[/cyan]"
)
raise typer.Exit(1)
# Ensure shared infrastructure is up to date; --force overwrites existing files.
infra_integration = integration
infra_key = key
infra_parsed = parsed_options
if installed_key and installed_key != key:
default_integration = get_integration(installed_key)
if default_integration is not None:
infra_integration = default_integration
infra_key = installed_key
_, infra_parsed = _resolve_integration_options(
default_integration, current, installed_key, None
)
_install_shared_infra_or_exit(
project_root,
selected_script,
force=force,
invoke_separator=_invoke_separator_for_integration(
infra_integration, current, infra_key, infra_parsed,
project_root=project_root,
),
invoke_prefix=_invoke_prefix_for_integration(
infra_integration, infra_key, infra_parsed, project_root
),
)
if os.name != "nt":
from .. import ensure_executable_scripts
ensure_executable_scripts(project_root)
# Phase 1: Install new files (overwrites existing; old-only files remain)
console.print(f"Upgrading integration: [cyan]{key}[/cyan]")
new_manifest = IntegrationManifest(key, project_root, version=_get_speckit_version())
from ..events import resolve_events
events_map = resolve_events(
key,
integration.config,
project_root,
parsed_options,
)
try:
integration.setup(
project_root,
new_manifest,
parsed_options=parsed_options,
script_type=selected_script,
raw_options=raw_options,
events=events_map,
force=force,
)
settings = _with_integration_setting(
current,
key,
integration,
script_type=selected_script,
raw_options=raw_options,
parsed_options=parsed_options,
project_root=project_root,
)
if installed_key == key:
try:
_install_shared_infra(
project_root,
selected_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=force,
refresh_managed=True,
)
except (ValueError, OSError) as exc:
raise _SharedTemplateRefreshError(
f"Failed to refresh shared infrastructure for '{key}': {exc}"
) from exc
if os.name != "nt":
from .. import ensure_executable_scripts
ensure_executable_scripts(project_root)
new_manifest.save()
_write_integration_json(project_root, installed_key, installed_keys, settings)
if installed_key == key:
_update_init_options_for_integration(
project_root,
integration,
script_type=selected_script,
parsed_options=parsed_options,
)
else:
_refresh_init_options_speckit_version(project_root)
except Exception as exc:
# Don't teardown — setup overwrites in-place, so teardown would
# delete files that were working before the upgrade. Just report.
console.print(f"[red]Error:[/red] Failed to {_cli_phase_label('upgrade', 'integration', key)}.")
console.print(f"[dim]Details:[/dim] {_cli_error_detail(exc)}")
console.print("[yellow]The previous integration files may still be in place.[/yellow]")
raise typer.Exit(1)
# Phase 2: Remove stale files from old manifest that are not in the new one
old_files = old_manifest.files
new_files = new_manifest.files
# Exclude integration-declared paths that use conditional manifest tracking
# (e.g. merge targets like .vscode/settings.json) so they are never deleted
# as "stale" while still being actively managed. Manifest keys are stored
# in POSIX form, so normalize the exclusions the same way before subtracting
# (an integration may build paths with os.path.join / backslashes).
exclusions = {PurePath(p).as_posix() for p in integration.stale_cleanup_exclusions()}
stale_keys = (set(old_files) - set(new_files)) - exclusions
if stale_keys:
stale_manifest = IntegrationManifest(key, project_root, version="stale-cleanup")
stale_manifest._files = {k: old_files[k] for k in stale_keys}
stale_manifest._ownership_modes = {k: old_manifest.ownership_modes[k] for k in stale_keys}
# remove_manifest=False: this throwaway manifest shares ``key`` with the
# real one just saved above (new_manifest.save()). Letting uninstall()
# delete ``{key}.manifest.json`` would wipe the freshly-written manifest
# whenever an upgrade shrinks the tracked file set (e.g. Bob migrating
# from the legacy commands layout to skills), leaving the integration
# untracked and un-upgradeable.
stale_removed, _ = stale_manifest.uninstall(
project_root, force=True, remove_manifest=False
)
if stale_removed:
console.print(f" Removed {len(stale_removed)} stale file(s) from previous install")
legacy_command_root_changed = _legacy_command_root_changed(
integration,
project_root,
old_manifest,
new_manifest,
)
if legacy_command_root_changed:
_unregister_enabled_extension_commands_for_agent(
project_root,
key,
continuing=(
"The integration command directory changed, but legacy enabled "
"extension artifacts may need manual cleanup."
),
)
# Re-register enabled extensions and presets only when upgrading the
# active integration. Inactive integrations remain untouched until
# `use` or `switch` activates and rescaffolds them (#2948). This runs
# after the core upgrade transaction, so failures remain best-effort.
if key == installed_key:
_register_extensions_for_agent(
project_root,
key,
force=True,
continuing="The integration was upgraded, but installed extensions may need re-registration.",
)
_register_presets_for_agent(
project_root,
key,
continuing="The integration was upgraded, but installed presets may need re-registration.",
)
_resync_manifest_after_registration(
new_manifest,
key,
continuing=(
"The integration was upgraded, but the manifest may report "
"preset/extension overrides as modified files."
),
)
name = (integration.config or {}).get("name", key)
lifecycle_success(f"\n[green]✓[/green] Integration '{escape(str(name))}' upgraded successfully")