Skip to content

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

27.2 KB
Raw Blame
"""
Mistral Vibe CLI integration β€” skills-based agent.

Vibe uses ``.vibe/skills/speckit-<name>/SKILL.md`` layout (enforced since v2.0.0).
"""

from __future__ import annotations

import logging
import os
import re
import tomllib
from collections.abc import Callable, Iterator, Mapping, Sequence
from pathlib import Path
from typing import Any

from ..base import IntegrationOption, SkillsIntegration
from .._file_changes import unlink as _unlink_file, write_bytes as _write_bytes
from ..manifest import IntegrationManifest
from ..._toml_string import escape_toml_basic
from ..._utils import dump_frontmatter

# Per-command frontmatter overrides for skills that should run in a forked
# subagent context.
#
# This is intentionally empty. ``analyze`` was previously forked (added in
# #2511) on the assumption that its heavy reads collapse to a short summary,
# but in practice ``/speckit-analyze`` returns a 300-500 line report that is
# injected back into the main conversation. In long sessions each subsequent
# fork inherits that growing context, compounding overhead until the chat
# freezes (#3185). Until a command genuinely returns a compact result, no
# command opts into ``context: fork``. The injection mechanism below stays in
# place so a future command can be added here when that holds true.
FORK_CONTEXT_COMMANDS: dict[str, dict[str, str]] = {}

# Keep the native Vibe timeout slightly longer than the dispatcher's inner
# timeout so Vibe does not terminate the dispatcher before it can reap its
# child process.
VIBE_EVENT_TIMEOUT_BUFFER = 5

logger = logging.getLogger(__name__)


def _toml_physical_lines(source: str) -> Iterator[str]:
    """Yield TOML physical lines, preserving their original terminators.

    TOML recognizes LF and CRLF only.  In particular, Python's ``splitlines``
    would incorrectly treat bare CR and Unicode line-separator characters as
    physical line boundaries.
    """
    start = 0
    while (newline := source.find("\n", start)) >= 0:
        yield source[start:newline + 1]
        start = newline + 1
    if start < len(source):
        yield source[start:]


class VibeIntegration(SkillsIntegration):
    """Integration for Mistral Vibe skills."""

    key = "vibe"
    config = {
        "name": "Mistral Vibe",
        "folder": ".vibe/",
        "commands_subdir": "skills",
        "install_url": "https://github.com/mistralai/mistral-vibe",
        "requires_cli": True,
    }
    registrar_config = {
        "dir": ".vibe/skills",
        "format": "markdown",
        "args": "$ARGUMENTS",
        "extension": "/SKILL.md",
    }
    multi_install_safe = True

    # Vibe's hooks schema supports exactly three hook types (HookConfig
    # rejects anything else): pre_tool, post_tool, post_agent. Unsupported
    # canonical events (session_start/session_end/user_prompt_submit) are
    # intentionally absent so install_integration_events skips them with a
    # warning instead of writing entries Vibe would refuse to load.
    CANONICAL_TO_NATIVE = {
        "pre_tool_use": "pre_tool",
        "post_tool_use": "post_tool",
        "stop": "post_agent",
    }
    events_config_file = ".vibe/hooks.toml"
    events_format = "toml-vibe"
    # Vibe parses any non-empty hook stdout as a JSON HookStructuredResponse;
    # plain text is reported as a hook failure and its output dropped. The
    # dispatcher therefore wraps handler stdout as {"decision": "allow",
    # "hook_specific_output": {"additional_context": ...}} for every event:
    # post_tool injects additional_context, pre_tool/post_agent ignore it but
    # still parse cleanly.
    events_context_envelope = {"*": "hook_specific_output"}

    # Set by ``setup()`` from ``--no-model-invocation``; applies to core
    # command skills only, since mandatory extension hooks rely on the model
    # invoking the hook skill. Integrations are process-wide singletons, so
    # preset overrides re-registered later in the same run see the same value.
    # Commands that rewrite skills without calling ``setup()`` (e.g.
    # ``preset add``, ``integration use``) get the default.
    _disable_model_invocation: bool = False

    @classmethod
    def options(cls) -> list[IntegrationOption]:
        opts = super().options()
        opts.append(
            IntegrationOption(
                "--skills",
                is_flag=True,
                default=True,
                help="Install as agent skills",
            ),
        )
        opts.append(
            IntegrationOption(
                "--no-model-invocation",
                is_flag=True,
                default=False,
                help=(
                    "Install core command skills as user-invocable only "
                    "(disable-model-invocation: true)"
                ),
            )
        )
        return opts

    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:
        """Build CLI arguments for non-interactive ``vibe`` execution.

        ``SkillsIntegration``'s default appends ``--model`` and
        ``--output-format``, neither of which exists in the Vibe CLI, so a
        dispatched step exits 2 at argument parsing whenever either flag ends
        up appended (a configured ``model``, or ``output_json=True``). Vibe's
        structured output is ``--output json``. ``model`` is deliberately
        dropped: Vibe has no per-invocation model flag and selects its model
        out of band via ``active_model`` in its config (or ``VIBE_ACTIVE_MODEL``).
        """
        self.validate_runtime_config(integration_args, integration_options)
        args = [self._resolve_executable(), "-p", prompt]
        self._apply_extra_args_env_var(args)
        if output_json:
            args.extend(["--output", "json"])
        return args

    def _render_skill(self, template_name: str, frontmatter: dict[str, Any], body: str) -> str:
        """Render a processed command template as a Vibe skill."""
        skill_name = f"speckit-{template_name.replace('.', '-')}"
        description = frontmatter.get(
            "description",
            f"Spec-kit workflow command: {template_name}",
        )
        skill_frontmatter = self._build_skill_fm(
            skill_name, description, f"templates/commands/{template_name}.md"
        )
        frontmatter_text = dump_frontmatter(skill_frontmatter)
        return f"---\n{frontmatter_text}\n---\n\n{body.strip()}\n"

    def _build_skill_fm(self, name: str, description: str, source: str) -> dict:
        from specify_cli.agents import CommandRegistrar
        return CommandRegistrar.build_skill_frontmatter(
            self.key, name, description, source
        )

    @staticmethod
    def _inject_frontmatter_flag(content: str, key: str, value: str = "true") -> str:
        """Insert ``key: value`` before the closing ``---`` if not already present."""
        lines = content.splitlines(keepends=True)

        # Pre-scan: bail out if already present in frontmatter
        dash_count = 0
        for line in lines:
            stripped = line.rstrip("\n\r")
            if stripped == "---":
                dash_count += 1
                if dash_count == 2:
                    break
                continue
            if dash_count == 1 and stripped.startswith(f"{key}:"):
                return content

        # Inject before the closing --- of frontmatter. Preserve the
        # existing EOL style, but default to "\n" (rather than "") when the
        # closing delimiter is the last line of the file with no trailing
        # newline -- otherwise the injected text glues onto the "---"
        # (e.g. "user-invocable: true---"), destroying the delimiter so a
        # later call's pre-scan/injection never finds a second "---" and
        # silently drops that key entirely.
        out: list[str] = []
        dash_count = 0
        injected = False
        for line in lines:
            stripped = line.rstrip("\n\r")
            if stripped == "---":
                dash_count += 1
                if dash_count == 2 and not injected:
                    if line.endswith("\r\n"):
                        eol = "\r\n"
                    elif line.endswith("\n"):
                        eol = "\n"
                    else:
                        eol = "\n"
                    out.append(f"{key}: {value}{eol}")
                    injected = True
            out.append(line)
        return "".join(out)

    @staticmethod
    def _skill_stem_from_content(content: str) -> str | None:
        """Derive the command stem (e.g. ``analyze``) from a skill's frontmatter.

        Reads the ``name:`` field of the first frontmatter block and strips
        the ``speckit-`` prefix. Returns ``None`` when no name is present.
        """
        name = VibeIntegration._skill_name_from_content(content)
        if name and name.startswith("speckit-"):
            return name[len("speckit-"):]
        return name

    @staticmethod
    def _skill_name_from_content(content: str) -> str | None:
        """Return the ``name:`` field of a skill's first frontmatter block."""
        dash_count = 0
        for line in content.splitlines():
            stripped = line.rstrip("\r\n")
            if stripped == "---":
                dash_count += 1
                if dash_count == 2:
                    break
                continue
            if dash_count == 1 and stripped.startswith("name:"):
                name = stripped[len("name:"):].strip().strip('"').strip("'")
                return name or None
        return None

    @classmethod
    def _is_core_command_skill(cls, content: str) -> bool:
        from specify_cli.extensions import CORE_COMMAND_NAMES  # lazy: avoids circular import

        name = cls._skill_name_from_content(content)
        return bool(name) and name.startswith("speckit-") and (
            name.removeprefix("speckit-") in CORE_COMMAND_NAMES
        )

    def post_process_skill_content(self, content: str) -> str:
        """Inject Vibe-specific frontmatter flags.

        Applied by every skill-generation path (setup, presets, extensions),
        so Vibe-specific frontmatter stays consistent however the SKILL.md
        was produced.

        ``disable-model-invocation`` is ``true`` for core command skills when
        the last ``setup()`` in this process was given
        ``--no-model-invocation``, else ``false``.
        """
        updated = super().post_process_skill_content(content)
        updated = self._inject_frontmatter_flag(updated, "user-invocable")
        disable = self._disable_model_invocation and self._is_core_command_skill(updated)
        updated = self._inject_frontmatter_flag(
            updated, "disable-model-invocation", "true" if disable else "false"
        )

        stem = self._skill_stem_from_content(updated)
        if stem:
            fork_config = FORK_CONTEXT_COMMANDS.get(stem)
            if fork_config:
                for key, value in fork_config.items():
                    updated = self._inject_frontmatter_flag(updated, key, value)
        return updated

    def setup(
        self,
        project_root: Path,
        manifest: IntegrationManifest,
        parsed_options: dict[str, Any] | None = None,
        **opts: Any,
    ) -> list[Path]:
        """Install Vibe skills then inject Vibe-specific flags"""
        import click

        click.secho(
            "Warning: The .vibe/skills layout requires Mistral Vibe v2.0.0 or newer. "
            "Please ensure your installation is up to date.",
            fg="yellow",
            err=True,
        )

        self._disable_model_invocation = (
            (parsed_options or {}).get("no_model_invocation") is True
        )
        try:
            return super().setup(
                project_root, manifest, parsed_options=parsed_options, **opts
            )
        except BaseException:
            self._disable_model_invocation = False
            raise

    @staticmethod
    def _hook_target_os() -> str:
        """Return the shell Vibe uses for hook commands on this host."""
        return "cmd" if os.name == "nt" else "host"

    @staticmethod
    def _toml_quote(value: str) -> str:
        """Render a TOML basic string without exposing Vibe syntax to events."""
        return escape_toml_basic(value)

    @staticmethod
    def _parse_toml_header(code: str) -> tuple[bool, tuple[str | None, ...] | None]:
        """Return a TOML header's kind and key path, or ``None`` if it is not one.

        This deliberately recognizes only header syntax, not full TOML.  Its
        caller has already excluded comments and unterminated strings.  A
        ``None`` key component represents a quoted basic key with an escape:
        it is still a real header, but cannot be the literal ``hooks`` key we
        manage without decoding TOML escapes.
        """
        text = code.strip(" \t")
        is_array = text.startswith("[[")
        if is_array:
            if not text.endswith("]]") or len(text) < 5:
                return False, None
            body = text[2:-2]
        else:
            if not text.startswith("[") or not text.endswith("]") or len(text) < 3:
                return False, None
            body = text[1:-1]

        parts: list[str | None] = []
        index = 0
        length = len(body)
        while True:
            while index < length and body[index] in " \t":
                index += 1
            if index == length:
                return False, None

            if body[index] in "\"'":
                quote = body[index]
                index += 1
                start = index
                escaped = False
                while index < length:
                    char = body[index]
                    if quote == "\"" and escaped:
                        escaped = False
                    elif quote == "\"" and char == "\\":
                        escaped = True
                    elif char == quote:
                        raw_part = body[start:index]
                        parts.append(raw_part if "\\\\" not in raw_part else None)
                        index += 1
                        break
                    index += 1
                else:
                    return False, None
            else:
                start = index
                while index < length and (body[index].isalnum() or body[index] in "_-"):
                    # TOML bare keys are ASCII-only; non-ASCII alphanumerics
                    # make this header ambiguous, so fail closed.
                    if not body[index].isascii():
                        return False, None
                    index += 1
                if start == index:
                    return False, None
                parts.append(body[start:index])

            while index < length and body[index] in " \t":
                index += 1
            if index == length:
                return is_array, tuple(parts)
            if body[index] != ".":
                return False, None
            index += 1

    @staticmethod
    def _managed_hook_spans(source: str) -> list[tuple[int, int]] | None:
        """Find Specify-owned hook blocks in valid TOML without interpreting values.

        The scanner only needs TOML's lexical boundaries: comments, ordinary
        strings, multiline strings, multiline arrays, and standalone table
        headers. A parser validity gate and the scanner both return ``None``
        for malformed or ambiguous input so callers can leave the source
        byte-for-byte untouched.

        A block ends after its last line of TOML and the blank lines right
        after it. A standalone comment that follows stays with the content
        after it, such as the user hook it introduces (#5079).
        """
        try:
            tomllib.loads(source)
        except tomllib.TOMLDecodeError:
            return None

        spans: list[tuple[int, int]] = []
        current_start: int | None = None
        current_end = 0
        current_after_comment = False
        current_is_hooks = False
        current_has_marker = False
        multiline: str | None = None
        array_depth = 0
        offset = 0

        for line in _toml_physical_lines(source):
            content = line.rstrip("\r\n")
            index = 0
            code_end = len(content)
            line_starts_in_multiline_string = multiline is not None
            line_has_multiline_string = line_starts_in_multiline_string
            line_starts_in_array = array_depth > 0
            structural = list(content)
            while index < len(content):
                char = content[index]
                if multiline is not None:
                    if multiline == '"""' and char == "\\":
                        # A basic multiline string may escape its next
                        # character (including a newline continuation).
                        structural[index:min(index + 2, len(content))] = " " * min(
                            2, len(content) - index
                        )
                        index += 2
                        continue
                    if content.startswith(multiline, index):
                        run_end = index
                        while run_end < len(content) and content[run_end] == multiline[0]:
                            run_end += 1
                        if run_end - index > 5:
                            return None
                        if run_end - index >= 3:
                            structural[index:run_end] = " " * (run_end - index)
                            multiline = None
                            index = run_end
                            continue
                    structural[index] = " "
                    index += 1
                    continue

                if char == "#":
                    code_end = index
                    break
                if content.startswith('"""', index) or content.startswith("'''", index):
                    multiline = content[index:index + 3]
                    line_has_multiline_string = True
                    structural[index:index + 3] = "   "
                    index += 3
                    continue
                if char in "\"'":
                    quote = char
                    start = index
                    index += 1
                    while index < len(content):
                        if quote == "\"" and content[index] == "\\":
                            if index + 1 == len(content):
                                return None
                            index += 2
                            continue
                        if content[index] == quote:
                            index += 1
                            structural[start:index] = " " * (index - start)
                            break
                        index += 1
                    else:
                        return None
                    continue
                index += 1

            if multiline is not None and not line.endswith(("\n", "\r")):
                return None

            # A multiline string can contain arbitrary text that resembles a
            # header or marker. A header/assignment cannot validly share its
            # physical line, so ignore that line for ownership purposes.
            code = "" if line_has_multiline_string else content[:code_end]
            is_array, header_path = (
                VibeIntegration._parse_toml_header(code)
                if not line_starts_in_array and not line_has_multiline_string
                else (False, None)
            )
            if header_path is not None:
                if current_start is not None and current_has_marker:
                    spans.append((current_start, current_end))
                current_start = offset
                current_is_hooks = is_array and header_path == ("hooks",)
                current_has_marker = False
            elif (
                not line_starts_in_array
                and not line_starts_in_multiline_string
                and content.lstrip(" \t").startswith("[")
            ):
                # A line that starts like a header but cannot be classified is
                # ambiguous (for example, a malformed header); never remove
                # content from such a file.  Inspect the original line here:
                # triple-quoted tokens are illegal in a header, but would
                # otherwise blank ``code`` before this guard sees it.
                return None
            elif current_is_hooks and re.fullmatch(
                r"[ \t]*speckit_marker[ \t]*=[ \t]*true[ \t]*", code
            ):
                current_has_marker = True

            if header_path is None:
                for char in structural[:code_end]:
                    if char == "[":
                        array_depth += 1
                    elif char == "]":
                        array_depth -= 1
                        if array_depth < 0:
                            return None

            # Lines inside a multiline string or array are part of the value,
            # even when they look like comments.
            if line_starts_in_array or line_has_multiline_string or code.strip(" \t"):
                current_end = offset + len(line)
                current_after_comment = False
            elif content.strip(" \t"):
                current_after_comment = True
            elif not current_after_comment:
                current_end = offset + len(line)

            offset += len(line)

        if multiline is not None or array_depth:
            return None
        if current_start is not None and current_has_marker:
            spans.append((current_start, current_end))
        return spans

    @classmethod
    def _without_managed_hooks(cls, source: str) -> str | None:
        """Remove managed spans, preserving every other source slice verbatim."""
        spans = cls._managed_hook_spans(source)
        if spans is None:
            return None
        if not spans:
            return source
        slices: list[str] = []
        previous_end = 0
        for start, end in spans:
            slices.append(source[previous_end:start])
            previous_end = end
        slices.append(source[previous_end:])
        return "".join(slices)

    def merge_vibe_event_hooks(
        self,
        project_root: Path,
        events: dict[str, list[dict[str, Any]]],
        *,
        build_dispatcher_command: Callable[[str, str, str, Any], str],
        native_timeout: Callable[[Any], int],
        ensure_safe_destination: Callable[[Path], None],
    ) -> bool:
        """Render and merge managed Vibe hooks without disturbing user content.

        This intentionally lives on Vibe rather than in shared events: Vibe's
        flat TOML schema, supported fields, unique-name rule, native shell
        quoting, and ownership-marker cleanup are all Vibe-specific.
        """
        lines: list[str] = []
        used_names: set[str] = set()
        for event, handlers in events.items():
            native = self.CANONICAL_TO_NATIVE[event]
            for config in handlers:
                command = config.get("command", "")
                dispatcher_command = build_dispatcher_command(
                    command,
                    event,
                    self._hook_target_os(),
                    config.get("timeout", 60),
                )
                command_stem = command.split(".")[-1] if command else "unknown"
                command_stem = re.sub(r"[^A-Za-z0-9_-]+", "-", command_stem) or "unknown"
                base_name = f"speckit-{native}-{command_stem}"
                hook_name = base_name
                suffix = 2
                while hook_name in used_names:
                    hook_name = f"{base_name}-{suffix}"
                    suffix += 1
                used_names.add(hook_name)

                lines.extend(
                    [
                        "[[hooks]]",
                        f"name = {self._toml_quote(hook_name)}",
                        f"type = {self._toml_quote(native)}",
                    ]
                )
                matcher = config.get("matcher", "*")
                if matcher and matcher != "*" and native in ("pre_tool", "post_tool"):
                    lines.append(f"match = {self._toml_quote('re:' + matcher)}")
                lines.extend(
                    [
                        f"command = {self._toml_quote(dispatcher_command)}",
                        f"timeout = {native_timeout(config.get('timeout', 60) + VIBE_EVENT_TIMEOUT_BUFFER)}",
                        "speckit_marker = true",
                        "",
                    ]
                )
        return self._merge_managed_hooks(
            project_root / self.events_config_file,
            "\n".join(lines),
            ensure_safe_destination=ensure_safe_destination,
        )

    def remove_vibe_event_hooks(
        self,
        project_root: Path,
        *,
        ensure_safe_destination: Callable[[Path], None],
    ) -> bool:
        """Remove only Specify-owned Vibe hooks and delete an owned-only file."""
        path = project_root / self.events_config_file
        if not path.exists():
            return False
        ensure_safe_destination(path)
        try:
            with path.open(encoding="utf-8", newline="") as file:
                existing = file.read()
        except (OSError, UnicodeDecodeError) as exc:
            logger.warning(
                "Could not read %s (it may be unreadable or not UTF-8); "
                "skipping event-config cleanup to preserve user content.",
                path,
            )
            logger.debug("Read error detail: %s", exc)
            return False

        cleaned = self._without_managed_hooks(existing)
        if cleaned is None:
            return False
        if cleaned == existing:
            return False
        non_comment_content = "\n".join(
            line
            for line in cleaned.splitlines()
            if line.strip() and not line.strip().startswith("#")
        )
        if not non_comment_content:
            _unlink_file(path, missing_ok=True)
            return True
        _write_bytes(path, cleaned.encode("utf-8"))
        return False

    def _merge_managed_hooks(
        self,
        path: Path,
        fragment: str,
        *,
        ensure_safe_destination: Callable[[Path], None],
    ) -> bool:
        """Replace managed entries while retaining unowned content.

        Active merges normalize trailing separators before appending generated
        hooks, so they do not promise byte-for-byte preservation.
        """
        ensure_safe_destination(path)
        existing = ""
        if path.exists():
            try:
                with path.open(encoding="utf-8", newline="") as file:
                    existing = file.read()
            except (OSError, UnicodeDecodeError) as exc:
                logger.warning(
                    "Could not read %s (it may be unreadable or not UTF-8); "
                    "skipping event-config merge to preserve user content.",
                    path,
                )
                logger.debug("Read error detail: %s", exc)
                return False
        cleaned = self._without_managed_hooks(existing)
        if cleaned is None:
            return False
        path.parent.mkdir(parents=True, exist_ok=True)
        _write_bytes(path, (cleaned.rstrip() + "\n\n" + fragment + "\n").encode("utf-8"))
        return True