feat(integration): add multi-install support and redesign integration state schema

- Introduce integration.json schema v1 with default_integration,
  installed_integrations, and integration_settings fields; migrate
  legacy v0 format on first read
- Add 'integration install' multi-install support: allow multiple
  multi_install_safe integrations to coexist without --force
- Add 'integration use' command to switch default integration
  without uninstall/reinstall
- Update 'integration switch' to set default when target is already
  installed, or perform full uninstall/reinstall otherwise
- Update 'integration uninstall' to handle multi-install state and
  refresh templates for the new default on default removal
- Update 'integration upgrade' to skip template refresh when
  upgrading a non-default integration
- Add 'Multi-install Safe' column to 'integration list' table
- Enforce integration_state_schema version guard in list/install/etc.
- Export _refresh_shared_templates, _parse_integration_options,
  select_with_arrows, and urllib from __init__ for test monkeypatching
- Delegate _install_shared_infra to shared_infra.install_shared_infra
  to gain symlink-safe writes and atomic template updates
- Write integration.json in schema v1 format during 'init'
- Fix remove_catalog bool priority to fall back to yaml index
- Fix extension/workflow catalog list to use is_dir() instead of exists()
- Split long Rich console messages onto separate lines to prevent
  ANSI span wrapping in narrow terminal environments

Author: darion-yaphet

src/specify_cli/__init__.py

@@ -27,6 +27,9 @@
 """
 
 import sys
+import urllib
+import urllib.request
+import urllib.error
 from pathlib import Path
 
 from typing import Optional
@@ -41,14 +44,74 @@
 from ._assets import _asset_service as _svc
 from ._git import _git_service as _git_svc
 from ._version import _version_service as _ver_svc
-from ._fs import save_init_options, merge_json_files, handle_vscode_settings
+from ._fs import save_init_options as save_init_options, load_init_options as load_init_options, merge_json_files as merge_json_files, handle_vscode_settings as handle_vscode_settings
 from ._helpers import (
     check_tool,
     get_speckit_version,
     AGENT_CONFIG,
-    AI_ASSISTANT_ALIASES,
-    AI_ASSISTANT_HELP,
+    AI_ASSISTANT_ALIASES as AI_ASSISTANT_ALIASES,
+    AI_ASSISTANT_HELP as AI_ASSISTANT_HELP,
+    _get_skills_dir as _get_skills_dir,
+    _parse_integration_options as _parse_integration_options,
 )
+from ._ui import select_with_arrows as select_with_arrows
+
+
+def _install_shared_infra(
+    project_path: Path,
+    script_type: str,
+    tracker=None,
+    force: bool = False,
+    invoke_separator: str = ".",
+) -> bool:
+    """Install shared infrastructure files into *project_path*."""
+    from .shared_infra import install_shared_infra
+    from ._assets import _asset_service as _svc
+
+    def _get_version() -> str:
+        import importlib.metadata
+        try:
+            return importlib.metadata.version("specify-cli")
+        except Exception:
+            return "unknown"
+
+    return install_shared_infra(
+        project_path,
+        script_type,
+        version=_get_version(),
+        core_pack=_svc.locate_core_pack(),
+        repo_root=Path(__file__).parent.parent.parent,
+        console=console,
+        force=force,
+        invoke_separator=invoke_separator,
+    )
+
+
+def _refresh_shared_templates(
+    project_path: Path,
+    invoke_separator: str,
+    force: bool = False,
+) -> None:
+    """Refresh default-sensitive shared templates without touching scripts."""
+    from .shared_infra import refresh_shared_templates
+    from ._assets import _asset_service as _svc
+
+    def _get_version() -> str:
+        import importlib.metadata
+        try:
+            return importlib.metadata.version("specify-cli")
+        except Exception:
+            return "unknown"
+
+    refresh_shared_templates(
+        project_path,
+        version=_get_version(),
+        core_pack=_svc.locate_core_pack(),
+        repo_root=Path(__file__).parent.parent.parent,
+        console=console,
+        invoke_separator=invoke_separator,
+        force=force,
+    )
 from .commands import init as _init_cmd
 from .commands.extension import extension_app
 from .commands.integration import integration_app

src/specify_cli/_helpers.py

@@ -202,108 +202,37 @@ def check_tool(tool: str, tracker: StepTracker = None) -> bool:
 def _install_shared_infra(
     project_path: Path,
     script_type: str,
-    tracker: StepTracker | None = None,
+    tracker=None,
     force: bool = False,
     invoke_separator: str = ".",
 ) -> bool:
     """Install shared infrastructure files into *project_path*.
 
-    Copies ``.specify/scripts/`` and ``.specify/templates/`` from the
-    bundled core_pack or source checkout.  Tracks all installed files
-    in ``speckit.manifest.json``.
-
-    Page templates are processed to resolve ``__SPECKIT_COMMAND_<NAME>__``
-    placeholders using *invoke_separator* (``"."`` for markdown agents,
-    ``"-"`` for skills agents).
-
-    When *force* is ``True``, existing files are overwritten with the
-    latest bundled versions.  When ``False`` (default), only missing
-    files are added and existing ones are skipped.
+    Delegates to ``shared_infra.install_shared_infra`` which provides
+    symlink-safe writes and atomic template updates.
 
     Returns ``True`` on success.
     """
     import importlib.metadata
+    from .shared_infra import install_shared_infra
+    from ._assets import _asset_service as _svc
 
     def _get_version() -> str:
         try:
             return importlib.metadata.version("specify-cli")
         except Exception:
             return "unknown"
 
-    from .integrations.base import IntegrationBase
-    from .integrations.manifest import IntegrationManifest
-    from ._assets import _asset_service as _svc
-
-    core = _svc.locate_core_pack()
-    manifest = IntegrationManifest("speckit", project_path, version=_get_version())
-
-    # Scripts
-    if core and (core / "scripts").is_dir():
-        scripts_src = core / "scripts"
-    else:
-        repo_root = Path(__file__).parent.parent.parent
-        scripts_src = repo_root / "scripts"
-
-    skipped_files: list[str] = []
-
-    if scripts_src.is_dir():
-        dest_scripts = project_path / ".specify" / "scripts"
-        dest_scripts.mkdir(parents=True, exist_ok=True)
-        variant_dir = "bash" if script_type == "sh" else "powershell"
-        variant_src = scripts_src / variant_dir
-        if variant_src.is_dir():
-            dest_variant = dest_scripts / variant_dir
-            dest_variant.mkdir(parents=True, exist_ok=True)
-            for src_path in variant_src.rglob("*"):
-                if src_path.is_file():
-                    rel_path = src_path.relative_to(variant_src)
-                    dst_path = dest_variant / rel_path
-                    if dst_path.exists() and not force:
-                        skipped_files.append(str(dst_path.relative_to(project_path)))
-                    else:
-                        dst_path.parent.mkdir(parents=True, exist_ok=True)
-                        shutil.copy2(src_path, dst_path)
-                        rel = dst_path.relative_to(project_path).as_posix()
-                        manifest.record_existing(rel)
-
-    # Page templates (not command templates, not vscode-settings.json)
-    if core and (core / "templates").is_dir():
-        templates_src = core / "templates"
-    else:
-        repo_root = Path(__file__).parent.parent.parent
-        templates_src = repo_root / "templates"
-
-    if templates_src.is_dir():
-        dest_templates = project_path / ".specify" / "templates"
-        dest_templates.mkdir(parents=True, exist_ok=True)
-        for f in templates_src.iterdir():
-            if f.is_file() and f.name != "vscode-settings.json" and not f.name.startswith("."):
-                dst = dest_templates / f.name
-                if dst.exists() and not force:
-                    skipped_files.append(str(dst.relative_to(project_path)))
-                else:
-                    content = f.read_text(encoding="utf-8")
-                    content = IntegrationBase.resolve_command_refs(
-                        content, invoke_separator
-                    )
-                    dst.write_text(content, encoding="utf-8")
-                    rel = dst.relative_to(project_path).as_posix()
-                    manifest.record_existing(rel)
-
-    if skipped_files:
-        console.print(
-            f"[yellow]⚠[/yellow]  {len(skipped_files)} shared infrastructure file(s) already exist and were not updated:"
-        )
-        for f in skipped_files:
-            console.print(f"    {f}")
-        console.print(
-            "To refresh shared infrastructure, run "
-            "[cyan]specify init --here --force[/cyan] or "
-            "[cyan]specify integration upgrade --force[/cyan]."
-        )
-
-    manifest.save()
-    return True
+    return install_shared_infra(
+        project_path,
+        script_type,
+        version=_get_version(),
+        core_pack=_svc.locate_core_pack(),
+        repo_root=Path(__file__).parent.parent.parent,
+        console=console,
+        force=force,
+        invoke_separator=invoke_separator,
+    )
 
 
 def ensure_executable_scripts(project_path: Path, tracker: StepTracker | None = None) -> None:

src/specify_cli/commands/extension.py

@@ -260,7 +260,7 @@ def extension_list(
 
     # Check if we're in a spec-kit project
     specify_dir = project_root / _SPECIFY_DIR
-    if not specify_dir.exists():
+    if not specify_dir.is_dir():
         console.print("[red]Error:[/red] Not a spec-kit project (no .specify/ directory)")
         console.print("Run this command from a spec-kit project root")
         raise typer.Exit(1)
@@ -300,7 +300,7 @@ def catalog_list() -> None:
     project_root = Path.cwd()
 
     specify_dir = project_root / _SPECIFY_DIR
-    if not specify_dir.exists():
+    if not specify_dir.is_dir():
         console.print("[red]Error:[/red] Not a spec-kit project (no .specify/ directory)")
         console.print("Run this command from a spec-kit project root")
         raise typer.Exit(1)
@@ -369,7 +369,7 @@ def catalog_add(
     project_root = Path.cwd()
 
     specify_dir = project_root / _SPECIFY_DIR
-    if not specify_dir.exists():
+    if not specify_dir.is_dir():
         console.print("[red]Error:[/red] Not a spec-kit project (no .specify/ directory)")
         console.print("Run this command from a spec-kit project root")
         raise typer.Exit(1)
@@ -432,7 +432,7 @@ def catalog_remove(
     project_root = Path.cwd()
 
     specify_dir = project_root / _SPECIFY_DIR
-    if not specify_dir.exists():
+    if not specify_dir.is_dir():
         console.print("[red]Error:[/red] Not a spec-kit project (no .specify/ directory)")
         console.print("Run this command from a spec-kit project root")
         raise typer.Exit(1)
@@ -481,7 +481,7 @@ def extension_add(
 
     # Check if we're in a spec-kit project
     specify_dir = project_root / _SPECIFY_DIR
-    if not specify_dir.exists():
+    if not specify_dir.is_dir():
         console.print("[red]Error:[/red] Not a spec-kit project (no .specify/ directory)")
         console.print("Run this command from a spec-kit project root")
         raise typer.Exit(1)
@@ -663,7 +663,7 @@ def extension_remove(
 
     # Check if we're in a spec-kit project
     specify_dir = project_root / _SPECIFY_DIR
-    if not specify_dir.exists():
+    if not specify_dir.is_dir():
         console.print("[red]Error:[/red] Not a spec-kit project (no .specify/ directory)")
         console.print("Run this command from a spec-kit project root")
         raise typer.Exit(1)
@@ -739,7 +739,7 @@ def extension_search(
 
     # Check if we're in a spec-kit project
     specify_dir = project_root / _SPECIFY_DIR
-    if not specify_dir.exists():
+    if not specify_dir.is_dir():
         console.print("[red]Error:[/red] Not a spec-kit project (no .specify/ directory)")
         console.print("Run this command from a spec-kit project root")
         raise typer.Exit(1)
@@ -823,7 +823,7 @@ def extension_info(
 
     # Check if we're in a spec-kit project
     specify_dir = project_root / _SPECIFY_DIR
-    if not specify_dir.exists():
+    if not specify_dir.is_dir():
         console.print("[red]Error:[/red] Not a spec-kit project (no .specify/ directory)")
         console.print("Run this command from a spec-kit project root")
         raise typer.Exit(1)
@@ -925,7 +925,7 @@ def extension_update(
 
     # Check if we're in a spec-kit project
     specify_dir = project_root / _SPECIFY_DIR
-    if not specify_dir.exists():
+    if not specify_dir.is_dir():
         console.print("[red]Error:[/red] Not a spec-kit project (no .specify/ directory)")
         console.print("Run this command from a spec-kit project root")
         raise typer.Exit(1)
@@ -1321,7 +1321,7 @@ def extension_enable(
 
     # Check if we're in a spec-kit project
     specify_dir = project_root / _SPECIFY_DIR
-    if not specify_dir.exists():
+    if not specify_dir.is_dir():
         console.print("[red]Error:[/red] Not a spec-kit project (no .specify/ directory)")
         console.print("Run this command from a spec-kit project root")
         raise typer.Exit(1)
@@ -1368,7 +1368,7 @@ def extension_disable(
 
     # Check if we're in a spec-kit project
     specify_dir = project_root / _SPECIFY_DIR
-    if not specify_dir.exists():
+    if not specify_dir.is_dir():
         console.print("[red]Error:[/red] Not a spec-kit project (no .specify/ directory)")
         console.print("Run this command from a spec-kit project root")
         raise typer.Exit(1)
@@ -1418,7 +1418,7 @@ def extension_set_priority(
 
     # Check if we're in a spec-kit project
     specify_dir = project_root / _SPECIFY_DIR
-    if not specify_dir.exists():
+    if not specify_dir.is_dir():
         console.print("[red]Error:[/red] Not a spec-kit project (no .specify/ directory)")
         console.print("Run this command from a spec-kit project root")
         raise typer.Exit(1)

src/specify_cli/commands/init.py

@@ -349,6 +349,13 @@ def init(
         console.print(f"[cyan]Selected coding agent integration:[/cyan] {selected_ai}")
         console.print(f"[cyan]Selected script type:[/cyan] {selected_script}")
 
+        if not no_git:
+            console.print(
+                "\n[dim]Note: The git extension is currently enabled by default during `specify init`.\n"
+                "Starting with v0.10.0, this will require an explicit opt-in via\n"
+                "[bold]specify extension add git[/bold].[/dim]"
+            )
+
         tracker = StepTracker("Initialize Specify Project")
 
         sys._specify_tracker_active = True
@@ -405,11 +412,19 @@ def init(
                 )
                 manifest.save()
 
-                # Write .specify/integration.json
+                # Write .specify/integration.json (v1 schema)
                 integration_json = project_path / ".specify" / "integration.json"
                 integration_json.parent.mkdir(parents=True, exist_ok=True)
+                _int_key = resolved_integration.key
+                _int_sep = resolved_integration.effective_invoke_separator(integration_parsed_options)
                 integration_json.write_text(json.dumps({
-                    "integration": resolved_integration.key,
+                    "integration_state_schema": 1,
+                    "integration": _int_key,
+                    "default_integration": _int_key,
+                    "installed_integrations": [_int_key],
+                    "integration_settings": {
+                        _int_key: {"invoke_separator": _int_sep},
+                    },
                     "version": get_speckit_version(),
                 }, indent=2) + "\n", encoding="utf-8")