Skip to content

πŸ’« Toolkit to help you get started with SDD or any other process!

14.6 KB
Raw Blame
"""IBM Bob integration.

Bob 2.0 uses the ``.bob/skills/speckit-<name>/SKILL.md`` layout by default.
The legacy ``.bob/commands/*.md`` layout (Bob 1.x) remains available as an
opt-in via ``--integration-options "--legacy-commands"``.

Bob is a *dual-mode* integration: whether it scaffolds skills or commands is
a per-project **configuration** decision (the ``--legacy-commands`` option,
persisted as ``ai_skills`` in init-options), not a property of the class.
It therefore extends :class:`IntegrationBase` (like Copilot, the other
dual-mode agent) and resolves the mode through the ``is_skills_mode`` hook,
delegating the actual scaffolding to a per-layout helper.

Deprecation cycle:
  This release:  Skills layout is the default; legacy ``.bob/commands/`` is
                 opt-in via ``--legacy-commands``.
  Next cycle:    ``--legacy-commands`` flag removed.
"""

from __future__ import annotations

import warnings
from collections.abc import Mapping, Sequence
from pathlib import Path
from typing import Any

import typer

from ..base import (
    IntegrationBase,
    IntegrationOption,
    MarkdownIntegration,
    SkillsIntegration,
)
from ..manifest import IntegrationManifest


def _validate_mode_options(parsed_options: dict[str, Any] | None) -> None:
    """Reject ``--skills`` and ``--legacy-commands`` used together.

    The two flags select opposite layouts, so combining them is ambiguous.
    Fail fast with the same clean exit-1 UX as other bad-option paths rather
    than silently letting one win.
    """
    opts = parsed_options or {}
    if opts.get("skills") and opts.get("legacy_commands"):
        from ..._console import console

        console.print(
            "[red]Error:[/red] --skills and --legacy-commands are mutually "
            "exclusive; pass only one."
        )
        raise typer.Exit(1)


def _warn_legacy_commands_deprecated() -> None:
    warnings.warn(
        "Bob legacy commands mode (.bob/commands/) is deprecated and will be "
        "removed in a future Spec Kit release. Omit --legacy-commands to use "
        "the default skills layout (.bob/skills/).",
        UserWarning,
        stacklevel=3,
    )


class _BobSkillsHelper(SkillsIntegration):
    """Default-mode helper: ``.bob/skills/speckit-<name>/SKILL.md``.

    Not registered in the integration registry β€” used only as a delegate by
    :class:`BobIntegration` for skills-mode ``setup()``.
    """

    key = "bob"
    config = {
        "name": "IBM Bob",
        "folder": ".bob/",
        "commands_subdir": "skills",
        "install_url": None,
        "requires_cli": False,
    }
    registrar_config = {
        "dir": ".bob/skills",
        "format": "markdown",
        "args": "$ARGUMENTS",
        "extension": "/SKILL.md",
    }

    def post_process_skill_content(self, content: str) -> str:
        """Bob skills are intent-activated; no slash-command note is needed."""
        return content


class _BobMarkdownHelper(MarkdownIntegration):
    """Legacy-mode helper: ``.bob/commands/speckit.<name>.md`` (Bob 1.x).

    Not registered in the integration registry β€” used only as a delegate by
    :class:`BobIntegration` when ``--legacy-commands`` is passed.  Declares
    ``invoke_separator="."`` so command-reference tokens render as Bob 1.x
    ``/speckit.<name>`` invocations.
    """

    key = "bob"
    invoke_separator = "."
    config = {
        "name": "IBM Bob",
        "folder": ".bob/",
        "commands_subdir": "commands",
        "install_url": None,
        "requires_cli": False,
    }
    registrar_config = {
        "dir": ".bob/commands",
        "format": "markdown",
        "args": "$ARGUMENTS",
        "extension": ".md",
        "invoke_separator": ".",
    }


class BobIntegration(IntegrationBase):
    """Integration for IBM Bob IDE (dual-mode; skills by default).

    Whether a project uses the skills or the legacy commands layout is a
    configuration choice resolved by :meth:`is_skills_mode`, not the class
    hierarchy.  ``setup()`` delegates to the matching helper.

    ``registrar_config`` mirrors the *commands* layout (``extension: ".md"``,
    ``dir: ".bob/commands"``) β€” the same pattern Copilot uses β€” so that
    ``CommandRegistrar.AGENT_CONFIGS["bob"]`` drives extension/preset
    registration into ``.bob/commands/`` for legacy-mode projects, while
    skills-mode projects have that command registration transparently skipped
    (``skills_mode_active`` becomes ``True`` because ``ai_skills=True`` and
    ``extension != "/SKILL.md"``) and receive extension skills instead.
    ``invoke_separator = "-"`` matches the default (skills) layout.
    """

    key = "bob"
    invoke_separator = "-"
    config = {
        "name": "IBM Bob",
        "folder": ".bob/",
        "commands_subdir": "commands",
        "install_url": None,
        "requires_cli": False,
    }
    registrar_config = {
        "dir": ".bob/commands",
        "format": "markdown",
        "args": "$ARGUMENTS",
        "extension": ".md",
    }

    @classmethod
    def options(cls) -> list[IntegrationOption]:
        return [
            IntegrationOption(
                "--skills",
                is_flag=True,
                default=False,
                help=(
                    "Force the default skills layout (.bob/skills/), overriding "
                    "on-disk auto-detection. Use this to migrate a legacy "
                    "commands install to skills, e.g. "
                    "`integration upgrade bob --integration-options \"--skills\"`"
                ),
            ),
            IntegrationOption(
                "--legacy-commands",
                is_flag=True,
                default=False,
                help=(
                    "Scaffold commands as legacy .bob/commands/*.md files "
                    "(Bob 1.x layout, deprecated) instead of the default "
                    "skills layout"
                ),
            ),
        ]

    def is_skills_mode(
        self,
        parsed_options: dict[str, Any] | None = None,
        project_root: Path | None = None,
    ) -> bool:
        """Bob is skills-first; ``--legacy-commands`` opts out.

        Precedence:

        1. Explicit ``--skills`` wins β€” it *forces* skills mode regardless of
           what is already on disk.  This is the supported migration / opt-in
           path: ``integration upgrade bob --integration-options "--skills"``
           converts a legacy commands install to the skills layout (setup()
           scaffolds ``.bob/skills`` and the upgrade's stale-file pass removes
           the old ``.bob/commands`` files).
        2. Explicit ``--legacy-commands`` opts out to the Bob 1.x layout.
        3. Otherwise, when a *project_root* is supplied, the layout is inferred
           from **managed Spec Kit artifacts** (see below).
        4. A fresh project (no managed artifacts, no flags) defaults to skills.

        The disk-detection fallback exists because on ``use`` / ``switch`` /
        ``upgrade`` (without an explicit ``--skills`` / ``--legacy-commands``)
        *parsed_options* is typically empty: no flag was passed, and existing
        Bob 1.x installs never persisted a ``legacy_commands`` option to
        recover.  This is independent of whether ``setup()`` runs β€” ``upgrade``
        *does* call :meth:`setup` (see ``command_upgrade.integration_upgrade``),
        but it passes those same empty *parsed_options*, so without disk
        detection the mode would resolve to the skills default.  Defaulting to
        skills there would rewrite such a project's ``ai_skills`` flag to
        ``True`` even though it still only contains a command layout, silently
        switching its extension / command-reference handling.  So the layout is
        inferred from managed Spec Kit artifacts, not the mere presence of a
        ``.bob/skills/`` directory: a user may keep unrelated Bob 2 skills in
        ``.bob/skills/`` while their Spec Kit commands still live in
        ``.bob/commands/speckit.*.md``.  We therefore treat the project as
        legacy (command) mode only when managed Spec Kit command files exist
        and no managed Spec Kit skills (``speckit-*`` skill dirs) do.  Passing
        ``--skills`` overrides this so users are never trapped in legacy mode.
        """
        opts = parsed_options or {}
        _validate_mode_options(opts)
        if opts.get("skills", False):
            return True
        if opts.get("legacy_commands", False):
            return False
        if project_root is not None:
            bob_dir = Path(project_root) / ".bob"
            has_managed_skills = any((bob_dir / "skills").glob("speckit-*"))
            has_managed_commands = any((bob_dir / "commands").glob("speckit.*.md"))
            if has_managed_commands and not has_managed_skills:
                return False
        return True

    def effective_invoke_separator(
        self,
        parsed_options: dict[str, Any] | None = None,
        project_root: Path | None = None,
    ) -> str:
        """``"."`` for the legacy commands layout, ``"-"`` for skills.

        *project_root* lets the ``use`` / ``switch`` / ``upgrade`` path β€” which
        refreshes shared infrastructure *before* persisting init-options β€”
        detect an already-installed legacy layout, so core command references
        are rendered with the correct separator instead of defaulting to the
        skills ``-``.
        """
        return "-" if self.is_skills_mode(parsed_options, project_root) else "."

    def invoke_separator_for_mode(self, skills_enabled: bool) -> str:
        """Resolve the command-ref separator from a project's persisted mode.

        Skills projects render ``/speckit-<cmd>``; legacy command projects
        render Bob 1.x ``/speckit.<cmd>``.  Extension/preset registration
        consults this (via the persisted ``ai_skills`` flag) so both layouts
        get the correct separator despite sharing one static ``AGENT_CONFIGS``
        entry.
        """
        return "-" if skills_enabled else "."

    def build_command_invocation(
        self,
        command_name: str,
        args: str = "",
        *,
        project_root: Path | None = None,
    ) -> str:
        """Render ``/speckit-<cmd>`` for skills mode, ``/speckit.<cmd>`` legacy.

        ``IntegrationBase`` hardcodes ``.``; Bob's skills live at
        ``.bob/skills/speckit-<cmd>/SKILL.md``, so the base rendering names a
        command that does not exist in a skills-mode project.  The two layouts
        differ in the *separator* and in how a dotted extension command is
        spelled: skills flatten every dot (``speckit.git.commit`` ->
        ``/speckit-git-commit``, matching the installed
        ``.bob/skills/speckit-git-commit/`` directory), while legacy commands
        keep them (``/speckit.git.commit``).

        *project_root* is keyword-only so this stays a superset of the base
        signature that every other integration implements.  It is resolved
        through :meth:`is_skills_mode`, so a ``None`` root falls back to the
        same skills default that :meth:`effective_invoke_separator` and
        ``is_skills_mode`` rule 4 already apply -- the class answers
        "unknown project" consistently, whichever hook is asked.
        """
        if not self.is_skills_mode(None, project_root):
            return super().build_command_invocation(command_name, args)

        stem = command_name
        stem = stem.removeprefix("speckit.")
        invocation = "/speckit-" + stem.replace(".", "-")
        return f"{invocation} {args}" if args else invocation

    def _build_dispatch_prompt(
        self,
        command_name: str,
        args: str,
        project_root: Path | None,
    ) -> str:
        """Resolve the layout from *project_root* at dispatch time.

        Dispatch is the one caller that knows the target project, so it is
        where a legacy install can be detected and given ``/speckit.<cmd>``
        instead of the skills default.

        A ``None`` root resolves to the working directory rather than being
        passed through: ``dispatch_command`` runs ``bob`` with
        ``cwd = project_root or <the current directory>``, so when no root is
        given the cwd *is* the project being dispatched into.  Detecting its
        layout beats falling back to the layout-unknown default, which would
        send a legacy install the skills spelling.
        """
        root = project_root if project_root is not None else Path.cwd()
        return self.build_command_invocation(
            command_name, args, project_root=root
        )

    def build_exec_args(
        self,
        prompt: str,
        *,
        model: str | None = None,
        output_json: bool = True,
        integration_args: Sequence[str] | None = None,
        integration_options: Mapping[str, Any] | None = None,
        project_root: Path | None = None,
    ) -> list[str] | None:
        """Non-interactive dispatch through ``bob run``.

        The prompt is **positional and last** -- Bob Shell 2.x has no ``-p`` on
        ``run``.  ``--trust`` is per-invocation (``run`` never persists it) and
        ``--accept-license`` is required non-interactively.

        *model* is ignored: ``run`` exposes no model flag; model choice comes
        from ``session.model`` in Bob's settings.
        """
        self.validate_runtime_config(integration_args, integration_options)
        args = [
            self._resolve_executable(),
            "run",
            "--trust",
            "--accept-license",
            "-f",
            "json" if output_json else "pretty",
        ]
        self._apply_extra_args_env_var(args)
        args.append(prompt)
        return args

    def post_process_skill_content(self, content: str) -> str:
        """Bob skills are intent-activated; no slash-command note is injected.

        Preset/extension skill generators call this on the *registered*
        ``BobIntegration`` instance, not on :class:`_BobSkillsHelper`, so the
        no-op must be repeated here (delegating to the helper) β€” otherwise
        those paths would inherit ``IntegrationBase``'s default and inject
        ``/speckit-*`` hook guidance that core Bob skills intentionally omit.
        """
        return _BobSkillsHelper().post_process_skill_content(content)

    def setup(
        self,
        project_root: Path,
        manifest: IntegrationManifest,
        parsed_options: dict[str, Any] | None = None,
        **opts: Any,
    ) -> list[Path]:
        parsed_options = parsed_options or {}
        if self.is_skills_mode(parsed_options, project_root):
            return _BobSkillsHelper().setup(
                project_root, manifest, parsed_options, **opts
            )
        _warn_legacy_commands_deprecated()
        return MarkdownIntegration.setup(
            _BobMarkdownHelper(), project_root, manifest, parsed_options, **opts
        )