specify-cli 1.2.0__py3-none-any.whl → 1.2.2__py3-none-any.whl

specify_cli/_invocation_style.py

@@ -13,7 +13,18 @@ DOLLAR_SKILLS_AGENTS: frozenset[str] = frozenset({"codex", "zcode", "command-cod
 
 # Agents that always render /speckit-<name>, regardless of ai_skills.
 ALWAYS_SLASH_AGENTS: frozenset[str] = frozenset(
-    {"devin", "droid", "dsh", "grok", "mcode", "muse", "qodercli", "trae", "zed"}
+    {
+        "devin",
+        "docker-agent",
+        "droid",
+        "dsh",
+        "grok",
+        "mcode",
+        "muse",
+        "qodercli",
+        "trae",
+        "zed",
+    }
 )
 
 # Agents that render /speckit-<name> only when ai_skills is enabled.

specify_cli/bundles/command_init.py

@@ -48,4 +48,9 @@ def bundle_init(
         f"{_escape_markup(str(project_root))}."
     )
     if bundle:
-        bundle_install(bundle, integration=integration, offline=offline)
+        bundle_install(
+            bundle,
+            integration=integration,
+            offline=offline,
+            refresh=False,
+        )

specify_cli/bundles/manifest.py

@@ -211,6 +211,17 @@ class BundleManifest:
                 errors.append(
                     f"{ref.kind[:-1]} '{ref.id}' has invalid version '{ref.version}'."
                 )
+            # Preset and extension installs refuse a priority below 1, which
+            # would otherwise surface only mid-install, after earlier components.
+            if (
+                ref.kind in ("extensions", "presets")
+                and ref.priority is not None
+                and ref.priority < 1
+            ):
+                errors.append(
+                    f"{ref.kind[:-1]} '{ref.id}' priority must be 1 or higher, "
+                    f"got {ref.priority}."
+                )
 
         for ref in self.presets:
             if ref.priority is None:

specify_cli/command_init.py

@@ -1077,8 +1077,6 @@ def register(app: typer.Typer) -> None:
         muse_skill_mode = selected_ai == "muse" and _is_skills_integration
         grok_skill_mode = selected_ai == "grok" and _is_skills_integration
         dsh_skill_mode = selected_ai == "dsh" and _is_skills_integration
-        cline_skill_mode = selected_ai == "cline"
-        forge_skill_mode = selected_ai == "forge"
         bob_skill_mode = selected_ai == "bob" and _is_skills_integration
         native_skill_mode = (
             codex_skill_mode
@@ -1155,28 +1153,18 @@ def register(app: typer.Typer) -> None:
             step_num += 1
         usage_label = "skills" if native_skill_mode else "slash commands"
 
-        from ._invocation_style import (
-            is_dollar_skills_agent as _is_dollar_skills_agent,
-            is_slash_skills_agent as _is_slash_skills_agent,
+        invoke_prefix = _invoke_prefix_for_integration(
+            resolved_integration,
+            resolved_integration.key,
+            integration_parsed_options or None,
+            project_path,
+        )
+        invoke_separator = resolved_integration.effective_invoke_separator(
+            integration_parsed_options or None, project_root=project_path
         )
-
-        # `_is_skills_integration` means the integration is installed in
-        # skills mode, which is the semantic equivalent of `ai_skills_enabled`
-        # used by `is_slash_skills_agent()`.
-        _ai_skills_enabled = _is_skills_integration
 
         def _display_cmd(name: str) -> str:
-            if _is_dollar_skills_agent(selected_ai, _ai_skills_enabled):
-                return f"$speckit-{name}"
-            if kimi_skill_mode:
-                return f"/skill:speckit-{name}"
-            if (
-                _is_slash_skills_agent(selected_ai, _ai_skills_enabled)
-                or cline_skill_mode
-                or forge_skill_mode
-            ):
-                return f"/speckit-{name}"
-            return f"/speckit.{name}"
+            return f"{invoke_prefix}speckit{invoke_separator}{name}"
 
         steps_lines.append(
             f"{step_num}. Start using {usage_label} with your coding agent:"

specify_cli/command_mcp.py

@@ -6,7 +6,7 @@ import typer
 
 
 def mcp() -> None:
-    """Run the experimental version-only MCP server over stdio."""
+    """Run the experimental MCP server over stdio."""
     from .mcp_server import run_stdio_server
 
     run_stdio_server()

specify_cli/core_pack/scripts/bash/check-prerequisites.sh

@@ -148,6 +148,12 @@ if [[ ! -f "$IMPL_PLAN" ]]; then
     exit 1
 fi
 
+if [[ ! -s "$IMPL_PLAN" ]]; then
+    echo "ERROR: plan.md is empty in $FEATURE_DIR" >&2
+    echo "Populate it, or remove the empty file and rerun $(format_speckit_command plan "$REPO_ROOT") with a valid plan template." >&2
+    exit 1
+fi
+
 # Check for spec.md if required
 if $REQUIRE_SPEC && [[ ! -f "$FEATURE_SPEC" ]]; then
     echo "ERROR: spec.md not found in $FEATURE_DIR" >&2

specify_cli/core_pack/scripts/bash/setup-plan.sh

@@ -43,7 +43,15 @@ if [[ -f "$IMPL_PLAN" ]]; then
         echo "Plan already exists at $IMPL_PLAN, skipping template copy"
     fi
 else
-    if resolve_template_content "plan-template" "$REPO_ROOT" > "$IMPL_PLAN"; then
+    template_file=$(mktemp)
+    trap 'rm -f "$template_file"' EXIT
+    if resolve_template_content "plan-template" "$REPO_ROOT" > "$template_file"; then
+        if [[ ! -s "$template_file" ]]; then
+            echo "ERROR: Plan template is empty; no new plan.md was created." >&2
+            echo "Restore a valid plan template and rerun plan setup." >&2
+            exit 1
+        fi
+        cat "$template_file" > "$IMPL_PLAN"
         if $JSON_MODE; then
             echo "Copied plan template to $IMPL_PLAN" >&2
         else
@@ -51,16 +59,12 @@ else
         fi
     else
         resolve_status=$?
-        rm -f "$IMPL_PLAN"
         if [ "$resolve_status" -ne 1 ]; then
             exit "$resolve_status"
         fi
-        if $JSON_MODE; then
-            echo "Warning: Plan template not found" >&2
-        else
-            echo "Warning: Plan template not found"
-        fi
-        touch "$IMPL_PLAN"
+        echo "ERROR: Plan template not found; no new plan.md was created." >&2
+        echo "Restore a valid plan template and rerun plan setup." >&2
+        exit 1
     fi
 fi
 

specify_cli/core_pack/scripts/powershell/check-prerequisites.ps1

@@ -101,13 +101,22 @@ if (-not (Test-Path $paths.FEATURE_DIR -PathType Container)) {
     exit 1
 }
 
-if (-not (Test-Path $paths.IMPL_PLAN -PathType Leaf)) {
+if (-not (Test-Path -LiteralPath $paths.IMPL_PLAN -PathType Leaf)) {
     [Console]::Error.WriteLine("ERROR: plan.md not found in $($paths.FEATURE_DIR)")
     $planCommand = Format-SpecKitCommand -CommandName 'plan' -RepoRoot $paths.REPO_ROOT
     [Console]::Error.WriteLine("Run $planCommand first to create the implementation plan.")
     exit 1
 }
 
+if ((Get-Item -LiteralPath $paths.IMPL_PLAN).Length -eq 0) {
+    [Console]::Error.WriteLine("ERROR: plan.md is empty in $($paths.FEATURE_DIR)")
+    $planCommand = Format-SpecKitCommand -CommandName 'plan' -RepoRoot $paths.REPO_ROOT
+    [Console]::Error.WriteLine(
+        "Populate it, or remove the empty file and rerun $planCommand with a valid plan template."
+    )
+    exit 1
+}
+
 # Check for spec.md if required
 if ($RequireSpec -and -not (Test-Path $paths.FEATURE_SPEC -PathType Leaf)) {
     [Console]::Error.WriteLine("ERROR: spec.md not found in $($paths.FEATURE_DIR)")

specify_cli/core_pack/scripts/powershell/setup-plan.ps1

@@ -39,7 +39,7 @@ if (-not $paths) {
 New-Item -ItemType Directory -Path $paths.FEATURE_DIR -Force | Out-Null
 
 # Copy plan template if plan doesn't already exist
-if (Test-Path $paths.IMPL_PLAN -PathType Leaf) {
+if (Test-Path -LiteralPath $paths.IMPL_PLAN -PathType Leaf) {
     if ($Json) {
         [Console]::Error.WriteLine("Plan already exists at $($paths.IMPL_PLAN), skipping template copy")
     } else {
@@ -48,6 +48,13 @@ if (Test-Path $paths.IMPL_PLAN -PathType Leaf) {
 } else {
     $content = Resolve-TemplateContent -TemplateName 'plan-template' -RepoRoot $paths.REPO_ROOT
     if ($null -ne $content) {
+        if ($content.Length -eq 0) {
+            [Console]::Error.WriteLine(
+                "ERROR: Plan template is empty; no new plan.md was created."
+            )
+            [Console]::Error.WriteLine("Restore a valid plan template and rerun plan setup.")
+            exit 1
+        }
         $utf8NoBom = New-Object System.Text.UTF8Encoding($false)
         [System.IO.File]::WriteAllText($paths.IMPL_PLAN, $content, $utf8NoBom)
         # Emit the copy status like the bash twin (setup-plan.sh); route to stderr
@@ -58,16 +65,11 @@ if (Test-Path $paths.IMPL_PLAN -PathType Leaf) {
             Write-Output "Copied plan template to $($paths.IMPL_PLAN)"
         }
     } else {
-        # Match the bash twin's wording and stream routing (stderr in -Json so
-        # stdout stays pure JSON, stdout otherwise), consistent with the sibling
-        # "Copied plan template" message above.
-        if ($Json) {
-            [Console]::Error.WriteLine("Warning: Plan template not found")
-        } else {
-            Write-Output "Warning: Plan template not found"
-        }
-        # Create a basic plan file if template doesn't exist
-        New-Item -ItemType File -Path $paths.IMPL_PLAN -Force | Out-Null
+        [Console]::Error.WriteLine(
+            "ERROR: Plan template not found; no new plan.md was created."
+        )
+        [Console]::Error.WriteLine("Restore a valid plan template and rerun plan setup.")
+        exit 1
     }
 }
 

specify_cli/core_pack/scripts/python/check_prerequisites.py

@@ -236,6 +236,16 @@ def main(argv: list[str] | None = None) -> int:
         )
         return 1
 
+    if paths.impl_plan.stat().st_size == 0:
+        print(f"ERROR: plan.md is empty in {paths.feature_dir}", file=sys.stderr)
+        print(
+            "Populate it, or remove the empty file and rerun "
+            f"{format_speckit_command('plan', paths.repo_root)} "
+            "with a valid plan template.",
+            file=sys.stderr,
+        )
+        return 1
+
     if args.require_spec and not paths.feature_spec.is_file():
         print(f"ERROR: spec.md not found in {paths.feature_dir}", file=sys.stderr)
         print(

specify_cli/core_pack/scripts/python/setup_plan.py

@@ -70,11 +70,28 @@ def main(argv: list[str] | None = None) -> int:
             print(f"Error: {exc}", file=sys.stderr)
             return 1
         if template_content is not None:
+            if template_content == "":
+                print(
+                    "ERROR: Plan template is empty; no new plan.md was created.",
+                    file=sys.stderr,
+                )
+                print(
+                    "Restore a valid plan template and rerun plan setup.",
+                    file=sys.stderr,
+                )
+                return 1
             paths.impl_plan.write_bytes(template_content.encode("utf-8"))
             print(f"Copied plan template to {paths.impl_plan}", file=status_stream)
         else:
-            print("Warning: Plan template not found", file=status_stream)
-            paths.impl_plan.touch()
+            print(
+                "ERROR: Plan template not found; no new plan.md was created.",
+                file=sys.stderr,
+            )
+            print(
+                "Restore a valid plan template and rerun plan setup.",
+                file=sys.stderr,
+            )
+            return 1
 
     if json_mode:
         sys.stdout.write(

specify_cli/events/__init__.py

@@ -32,6 +32,8 @@ import typer
 from ..integrations._file_changes import unlink as _unlink_file, write_text as _write_text
 
 if TYPE_CHECKING:
+    from collections.abc import Iterable
+
     from ..integrations.base import IntegrationBase
     from ..integrations.manifest import IntegrationManifest
 
@@ -2153,13 +2155,15 @@ def _remove_opencode_entries(config_path: Path) -> bool:
     if existing is None:
         return False
     plugins = existing.get("plugin", [])
-    if isinstance(plugins, list):
-        ref = "./.opencode/plugin/speckit-events.ts"
-        plugins = [p for p in plugins if p != ref]
-        if plugins:
-            existing["plugin"] = plugins
-        else:
-            existing.pop("plugin", None)
+    ref = "./.opencode/plugin/speckit-events.ts"
+    # No Spec Kit plugin ref to strip: leave the user's file untouched.
+    if not isinstance(plugins, list) or ref not in plugins:
+        return False
+    plugins = [p for p in plugins if p != ref]
+    if plugins:
+        existing["plugin"] = plugins
+    else:
+        existing.pop("plugin", None)
     if not existing:
         _unlink_file(config_path, missing_ok=True)
         return True
@@ -2376,8 +2380,9 @@ def _remove_copilot_entries(dst: Path) -> bool:
     if not isinstance(existing, dict):
         return False
     hooks = existing.get("hooks", {})
-    if not isinstance(hooks, dict):
-        hooks = {}
+    # Nothing Specify-owned to strip: leave the user's file untouched.
+    if not isinstance(hooks, dict) or not _has_marked_entry(hooks.values()):
+        return False
     cleaned: dict[str, list] = {}
     for event, entries in hooks.items():
         if not isinstance(entries, list):
@@ -2505,7 +2510,8 @@ def _remove_json_root_entries(dst: Path) -> bool:
     existing = _load_user_json(dst)
     if existing is None:
         return False
-    if not isinstance(existing, dict):
+    # Nothing Specify-owned to strip: leave the user's file untouched.
+    if not isinstance(existing, dict) or not _has_marked_entry(existing.values()):
         return False
     cleaned: dict[str, Any] = {}
     for event, entries in existing.items():
@@ -2627,7 +2633,10 @@ def _remove_json_entries(dst: Path) -> bool:
     if existing is None:
         return False
     hooks = existing.get("hooks", {})
-    if not isinstance(hooks, dict):
+    # Nothing Specify-owned to strip: leave the user's file untouched, so a
+    # no-op event refresh neither reformats nor deletes it (the JSON
+    # counterpart of the TOML guard added for #4563).
+    if not isinstance(hooks, dict) or not _has_marked_entry(hooks.values()):
         return False
     cleaned: dict[str, list] = {}
     for event, entries in hooks.items():
@@ -2671,6 +2680,16 @@ def _has_marker(entry: Any) -> bool:
     return False
 
 
+def _has_marked_entry(groups: Iterable[Any]) -> bool:
+    """Return True if any list among *groups* holds a Specify-marked entry."""
+    return any(
+        _has_marker(entry)
+        for entries in groups
+        if isinstance(entries, list)
+        for entry in entries
+    )
+
+
 def register(app: typer.Typer) -> None:
     """Attach the event command group to the root application."""
     from . import command_run  # noqa: F401 -- registers handler

specify_cli/extensions/_command_update_transaction.py

@@ -564,6 +564,10 @@ def run_update_command(extension: str | None) -> None:
                             if cfg_file.is_file():
                                 shutil.copy2(cfg_file, new_extension_dir / cfg_file.name)
 
+                    # Scaffold config templates the new version declares, as
+                    # `extension add` does; the configs restored above are kept.
+                    scaffolded, _, unscaffolded = manager.scaffold_config(extension_id)
+
                     # 9. Restore metadata from backup (installed_at, enabled state)
                     if backup_registry_entry and isinstance(backup_registry_entry, dict):
                         init_options = _commands.load_init_options(project_root)
@@ -630,6 +634,17 @@ def run_update_command(extension: str | None) -> None:
                 console.print(
                     f"   [green]✓[/green] Updated to v{update.available}"
                 )
+                config_home = f".specify/extensions/{_escape_markup(extension_id)}"
+                for cfg in scaffolded:
+                    console.print(
+                        f"   Config scaffolded: {config_home}/{_escape_markup(cfg)}"
+                    )
+                if unscaffolded:
+                    console.print(
+                        "   [yellow]Warning:[/yellow] Config templates not scaffolded: "
+                        f"{_escape_markup(', '.join(unscaffolded))}. "
+                        "Verify the extension manifest and template files."
+                    )
                 if cleanup_error is not None:
                     console.print(
                         "   [yellow]Warning:[/yellow] Could not fully remove "

specify_cli/extensions/_commands.py

@@ -121,6 +121,38 @@ def _refresh_events_and_warn(project_root: Path) -> None:
             console.print(f"    {key}: {_escape_markup(detail)}")
 
 
+def _registered_command_name(project_root: Path, command_name: str) -> str:
+    """Return *command_name* the way the project's active agent registers it.
+
+    Skills projects register extension commands as ``speckit-<ext>-<cmd>``
+    skills, which needs no integration lookup, so installed adapters stay
+    unloaded. In command mode, agents whose command references use ``-``
+    (such as Cline, Forge, and Junie) register the same hyphenated name; the
+    others, and agents that are not loaded, keep the manifest's dotted name.
+    Deriving this from the integration keeps command listings in step with
+    registration instead of a list of agents.
+    """
+    from .._init_options import is_ai_skills_enabled
+    from ..integrations import get_integration
+    from . import ExtensionManager
+
+    opts = load_init_options(project_root)
+    selected_ai = opts.get("ai") if isinstance(opts, dict) else None
+    if not isinstance(selected_ai, str) or not selected_ai:
+        return command_name
+    # Check skills mode before the integration: generic's command-mode
+    # separator applies to both of its layouts, and inspection commands such
+    # as `extension info` do not load installed adapters.
+    if is_ai_skills_enabled(opts):
+        return ExtensionManager._skill_name_for_command(command_name)
+    integration = get_integration(selected_ai)
+    if integration is None or (
+        integration.invoke_separator_for_mode(False) != "-"
+    ):
+        return command_name
+    return ExtensionManager._skill_name_for_command(command_name)
+
+
 def install_extension_from_url(
     manager,
     project_root: Path,

specify_cli/extensions/catalog/command_remove.py

@@ -5,6 +5,8 @@ Registered by ``catalog.register()``; shared catalog helpers live in
 """
 from __future__ import annotations
 
+import os
+
 import typer
 from rich.markup import escape as _escape_markup
 
@@ -48,19 +50,38 @@ def catalog_remove(
         _commands.console.print(f"[red]Error:[/red] Catalog '{safe_name}' not found.")
         raise typer.Exit(1)
 
-    config["catalogs"] = catalogs
-    config_path.write_text(
-        _commands.yaml.safe_dump(
-            config,
-            default_flow_style=False,
-            sort_keys=False,
-            allow_unicode=True,
-        ),
-        encoding="utf-8",
-    )
+    if catalogs:
+        config["catalogs"] = catalogs
+        config_path.write_text(
+            _commands.yaml.safe_dump(
+                config,
+                default_flow_style=False,
+                sort_keys=False,
+                allow_unicode=True,
+            ),
+            encoding="utf-8",
+        )
+    else:
+        # The catalog loader rejects an existing config with no entries, so
+        # delete the file instead of writing ``catalogs: []``.
+        try:
+            config_path.unlink(missing_ok=True)
+        except OSError as error:
+            config_label = _escape_markup(
+                str(_commands._display_project_path(project_root, config_path))
+            )
+            _commands.console.print(
+                f"[red]Error:[/red] Failed to delete {config_label}: "
+                f"{_escape_markup(str(error))}"
+            )
+            raise typer.Exit(1)
 
     _commands.console.print(f"[green]✓[/green] Removed catalog '{safe_name}'")
     if not catalogs:
+        if os.environ.get("SPECKIT_CATALOG_URL"):
+            fallback = "the SPECKIT_CATALOG_URL environment variable still takes precedence"
+        else:
+            fallback = "user configuration or built-in defaults will be used"
         _commands.console.print(
-            "\n[dim]No catalogs remain in config. Built-in defaults will be used.[/dim]"
+            f"\n[dim]Project catalog override removed; {fallback}.[/dim]"
         )

specify_cli/extensions/command_add.py

@@ -297,22 +297,9 @@ def extension_add(
         for warning in manifest.warnings:
             console.print(f"\n[yellow]⚠  Compatibility warning:[/yellow] {_escape_markup(str(warning))}")
 
-        selected_ai = _commands.load_init_options(project_root).get("ai")
-        is_cline = selected_ai == "cline"
-        is_forge = selected_ai == "forge"
-
-        if is_cline:
-            from specify_cli.integrations.cline import format_cline_command_name
-        if is_forge:
-            from specify_cli.integrations.forge import format_forge_command_name
-
         console.print("\n[bold cyan]Provided commands:[/bold cyan]")
         for cmd in manifest.commands:
-            cmd_name = cmd['name']
-            if is_cline:
-                cmd_name = format_cline_command_name(cmd_name)
-            elif is_forge:
-                cmd_name = format_forge_command_name(cmd_name)
+            cmd_name = _commands._registered_command_name(project_root, cmd['name'])
             console.print(f"  • {_escape_markup(str(cmd_name))} - {_escape_markup(str(cmd.get('description', '')))}")
 
         # Report agent skills registration

specify_cli/extensions/command_info.py

@@ -123,29 +123,14 @@ def extension_info(
             _commands.console.print()
 
             if ext_manifest.commands:
-                # Print each command the way the active agent registers it.
-                # Cline and Forge hyphenate command names (e.g. Forge invokes
-                # `/speckit-jira-sync`, not the manifest's dotted
-                # `speckit.jira.sync`), so mirror the same formatting used by
-                # `extension add`'s "Provided commands" listing — otherwise the
-                # names shown here don't match what the user actually types.
-                selected_ai = _commands.load_init_options(project_root).get("ai")
-                if selected_ai == "cline":
-                    from specify_cli.integrations.cline import (
-                        format_cline_command_name as _format_command_name,
-                    )
-                elif selected_ai == "forge":
-                    from specify_cli.integrations.forge import (
-                        format_forge_command_name as _format_command_name,
-                    )
-                else:
-                    _format_command_name = None
-
+                # Print each command the way the active agent registers it
+                # (e.g. Codex registers `speckit-jira-sync`, not the manifest's
+                # dotted `speckit.jira.sync`), matching `extension add`'s
+                # "Provided commands" listing, so the names shown here are the
+                # ones the user actually types.
                 _commands.console.print("[bold]Commands:[/bold]")
                 for cmd in ext_manifest.commands:
-                    cmd_name = cmd['name']
-                    if _format_command_name is not None:
-                        cmd_name = _format_command_name(cmd_name)
+                    cmd_name = _commands._registered_command_name(project_root, cmd['name'])
                     _commands.console.print(f"  • {_escape_markup(str(cmd_name))}: {_escape_markup(str(cmd.get('description', '')))}")
                 _commands.console.print()