test_integration_base_toml.py

"""Reusable test mixin for standard TomlIntegration subclasses.

Each per-agent test file sets ``KEY``, ``FOLDER``, ``COMMANDS_SUBDIR``,
``REGISTRAR_DIR``, and ``CONTEXT_FILE``, then inherits all verification
logic from ``TomlIntegrationTests``.

Mirrors ``MarkdownIntegrationTests`` closely — same test structure,
adapted for TOML output format.
"""

import os
import tomllib

import pytest

from specify_cli.integrations import INTEGRATION_REGISTRY, get_integration
from specify_cli.integrations.base import TomlIntegration
from specify_cli.integrations.manifest import IntegrationManifest

from .conftest import AF_EXTENSION_COMMANDS, AF_EXTENSION_FILES


class TomlIntegrationTests:
    """Mixin — set class-level constants and inherit these tests.

    Required class attrs on subclass::

        KEY: str              — integration registry key
        FOLDER: str           — e.g. ".gemini/"
        COMMANDS_SUBDIR: str  — e.g. "commands"
        REGISTRAR_DIR: str    — e.g. ".gemini/commands"
        CONTEXT_FILE: str     — e.g. "GEMINI.md"
    """

    KEY: str
    FOLDER: str
    COMMANDS_SUBDIR: str
    REGISTRAR_DIR: str
    CONTEXT_FILE: str

    # -- Registration -----------------------------------------------------

    def test_registered(self):
        assert self.KEY in INTEGRATION_REGISTRY
        assert get_integration(self.KEY) is not None

    def test_is_toml_integration(self):
        assert isinstance(get_integration(self.KEY), TomlIntegration)

    # -- Config -----------------------------------------------------------

    def test_config_folder(self):
        i = get_integration(self.KEY)
        assert i.config["folder"] == self.FOLDER

    def test_config_commands_subdir(self):
        i = get_integration(self.KEY)
        assert i.config["commands_subdir"] == self.COMMANDS_SUBDIR

    def test_registrar_config(self):
        i = get_integration(self.KEY)
        assert i.registrar_config["dir"] == self.REGISTRAR_DIR
        assert i.registrar_config["format"] == "toml"
        assert i.registrar_config["args"] == "{{args}}"
        assert i.registrar_config["extension"] == ".toml"

    def test_context_file(self):
        i = get_integration(self.KEY)
        assert i.context_file == self.CONTEXT_FILE

    # -- Setup / teardown -------------------------------------------------

    def test_setup_creates_files(self, tmp_path):
        i = get_integration(self.KEY)
        m = IntegrationManifest(self.KEY, tmp_path)
        created = i.setup(tmp_path, m)
        assert len(created) > 0
        cmd_files = [f for f in created if "scripts" not in f.parts]
        for f in cmd_files:
            assert f.exists()
            assert f.name.startswith("speckit.")
            assert f.name.endswith(".toml")

    def test_setup_writes_to_correct_directory(self, tmp_path):
        i = get_integration(self.KEY)
        m = IntegrationManifest(self.KEY, tmp_path)
        created = i.setup(tmp_path, m)
        expected_dir = i.commands_dest(tmp_path)
        assert expected_dir.exists(), f"Expected directory {expected_dir} was not created"
        cmd_files = [f for f in created if "scripts" not in f.parts]
        assert len(cmd_files) > 0, "No command files were created"
        for f in cmd_files:
            assert f.resolve().parent == expected_dir.resolve(), (
                f"{f} is not under {expected_dir}"
            )

    def test_templates_are_processed(self, tmp_path):
        """Command files must have placeholders replaced and be valid TOML."""
        i = get_integration(self.KEY)
        m = IntegrationManifest(self.KEY, tmp_path)
        created = i.setup(tmp_path, m)
        cmd_files = [f for f in created if "scripts" not in f.parts]
        assert len(cmd_files) > 0
        for f in cmd_files:
            content = f.read_text(encoding="utf-8")
            assert "{SCRIPT}" not in content, f"{f.name} has unprocessed {{SCRIPT}}"
            assert "__AGENT__" not in content, f"{f.name} has unprocessed __AGENT__"
            assert "{ARGS}" not in content, f"{f.name} has unprocessed {{ARGS}}"

    def test_toml_has_description(self, tmp_path):
        """Every TOML command file should have a description key."""
        i = get_integration(self.KEY)
        m = IntegrationManifest(self.KEY, tmp_path)
        created = i.setup(tmp_path, m)
        cmd_files = [f for f in created if "scripts" not in f.parts]
        for f in cmd_files:
            content = f.read_text(encoding="utf-8")
            assert 'description = "' in content, f"{f.name} missing description key"

    def test_toml_has_prompt(self, tmp_path):
        """Every TOML command file should have a prompt key."""
        i = get_integration(self.KEY)
        m = IntegrationManifest(self.KEY, tmp_path)
        created = i.setup(tmp_path, m)
        cmd_files = [f for f in created if "scripts" not in f.parts]
        for f in cmd_files:
            content = f.read_text(encoding="utf-8")
            assert "prompt = " in content, f"{f.name} missing prompt key"

    def test_toml_uses_correct_arg_placeholder(self, tmp_path):
        """TOML commands must use {{args}} (from {ARGS} replacement)."""
        i = get_integration(self.KEY)
        m = IntegrationManifest(self.KEY, tmp_path)
        created = i.setup(tmp_path, m)
        cmd_files = [f for f in created if "scripts" not in f.parts]
        # At least one file should contain {{args}} from the {ARGS} placeholder
        has_args = any("{{args}}" in f.read_text(encoding="utf-8") for f in cmd_files)
        assert has_args, "No TOML command file contains {{args}} placeholder"

    @pytest.mark.parametrize(
        ("frontmatter", "expected"),
        [
            (
                "---\ndescription: |\n  First line\n  Second line\n---\nBody\n",
                "First line\nSecond line\n",
            ),
            (
                "---\ndescription: >\n  First line\n  Second line\n---\nBody\n",
                "First line Second line\n",
            ),
            (
                "---\ndescription: |-\n  First line\n  Second line\n---\nBody\n",
                "First line\nSecond line",
            ),
            (
                "---\ndescription: >-\n  First line\n  Second line\n---\nBody\n",
                "First line Second line",
            ),
        ],
    )
    def test_toml_extract_description_supports_block_scalars(self, frontmatter, expected):
        assert TomlIntegration._extract_description(frontmatter) == expected

    def test_split_frontmatter_ignores_indented_delimiters(self):
        content = (
            "---\n"
            "description: |\n"
            "  line one\n"
            "  ---\n"
            "  line two\n"
            "---\n"
            "Body\n"
        )

        frontmatter, body = TomlIntegration._split_frontmatter(content)

        assert "line two" in frontmatter
        assert body == "Body\n"

    def test_toml_prompt_excludes_frontmatter(self, tmp_path, monkeypatch):
        i = get_integration(self.KEY)
        template = tmp_path / "sample.md"
        template.write_text(
            "---\n"
            "description: Summary line one\n"
            "scripts:\n"
            "  sh: scripts/bash/example.sh\n"
            "---\n"
            "Body line one\n"
            "Body line two\n",
            encoding="utf-8",
        )
        monkeypatch.setattr(i, "list_command_templates", lambda: [template])

        m = IntegrationManifest(self.KEY, tmp_path)
        created = i.setup(tmp_path, m)
        cmd_files = [f for f in created if "scripts" not in f.parts]
        assert len(cmd_files) == 1

        generated = cmd_files[0].read_text(encoding="utf-8")
        parsed = tomllib.loads(generated)

        assert parsed["description"] == "Summary line one"
        assert parsed["prompt"] == "Body line one\nBody line two"
        assert "description:" not in parsed["prompt"]
        assert "scripts:" not in parsed["prompt"]
        assert "---" not in parsed["prompt"]

    def test_toml_no_ambiguous_closing_quotes(self, tmp_path, monkeypatch):
        """Multiline body ending with `"` must not produce `""""` (#2113)."""
        i = get_integration(self.KEY)
        template = tmp_path / "sample.md"
        template.write_text(
            "---\n"
            "description: Test\n"
            "scripts:\n"
            "  sh: echo ok\n"
            "---\n"
            "Check the following:\n"
            '- Correct: "Is X clearly specified?"\n',
            encoding="utf-8",
        )
        monkeypatch.setattr(i, "list_command_templates", lambda: [template])

        m = IntegrationManifest(self.KEY, tmp_path)
        created = i.setup(tmp_path, m)
        cmd_files = [f for f in created if "scripts" not in f.parts]
        assert len(cmd_files) == 1

        raw = cmd_files[0].read_text(encoding="utf-8")
        assert '""""' not in raw, "closing delimiter must not merge with body quote"
        assert '"""\n' in raw, "body must use multiline basic string"
        parsed = tomllib.loads(raw)
        assert parsed["prompt"].endswith('specified?"')
        assert not parsed["prompt"].endswith("\n"), "parsed value must not gain a trailing newline"

    def test_toml_triple_double_and_single_quote_ending(self, tmp_path, monkeypatch):
        """Body containing `\"\"\"` and ending with `'` falls back to escaped basic string."""
        i = get_integration(self.KEY)
        template = tmp_path / "sample.md"
        template.write_text(
            "---\n"
            "description: Test\n"
            "scripts:\n"
            "  sh: echo ok\n"
            "---\n"
            'Use """triple""" quotes\n'
            "and end with 'single'\n",
            encoding="utf-8",
        )
        monkeypatch.setattr(i, "list_command_templates", lambda: [template])

        m = IntegrationManifest(self.KEY, tmp_path)
        created = i.setup(tmp_path, m)
        cmd_files = [f for f in created if "scripts" not in f.parts]
        assert len(cmd_files) == 1

        raw = cmd_files[0].read_text(encoding="utf-8")
        assert "''''" not in raw, "literal string must not produce ambiguous closing quotes"
        parsed = tomllib.loads(raw)
        assert parsed["prompt"].endswith("'single'")
        assert '"""triple"""' in parsed["prompt"]
        assert not parsed["prompt"].endswith("\n"), "parsed value must not gain a trailing newline"

    def test_toml_closing_delimiter_inline_when_safe(self, tmp_path, monkeypatch):
        """Body NOT ending with `"` keeps closing `\"\"\"` inline (no extra newline)."""
        i = get_integration(self.KEY)
        template = tmp_path / "sample.md"
        template.write_text(
            "---\n"
            "description: Test\n"
            "scripts:\n"
            "  sh: echo ok\n"
            "---\n"
            "Line one\n"
            "Plain body content\n",
            encoding="utf-8",
        )
        monkeypatch.setattr(i, "list_command_templates", lambda: [template])

        m = IntegrationManifest(self.KEY, tmp_path)
        created = i.setup(tmp_path, m)
        cmd_files = [f for f in created if "scripts" not in f.parts]
        assert len(cmd_files) == 1

        raw = cmd_files[0].read_text(encoding="utf-8")
        parsed = tomllib.loads(raw)
        assert parsed["prompt"] == "Line one\nPlain body content"
        assert raw.rstrip().endswith('content"""'), \
            "closing delimiter should be inline when body does not end with a quote"

    def test_toml_is_valid(self, tmp_path):
        """Every generated TOML file must parse without errors."""
        i = get_integration(self.KEY)
        m = IntegrationManifest(self.KEY, tmp_path)
        created = i.setup(tmp_path, m)
        cmd_files = [f for f in created if "scripts" not in f.parts]
        for f in cmd_files:
            raw = f.read_bytes()
            try:
                parsed = tomllib.loads(raw.decode("utf-8"))
            except Exception as exc:
                raise AssertionError(f"{f.name} is not valid TOML: {exc}") from exc
            assert "prompt" in parsed, f"{f.name} parsed TOML has no 'prompt' key"

    def test_all_files_tracked_in_manifest(self, tmp_path):
        i = get_integration(self.KEY)
        m = IntegrationManifest(self.KEY, tmp_path)
        created = i.setup(tmp_path, m)
        for f in created:
            rel = f.resolve().relative_to(tmp_path.resolve()).as_posix()
            assert rel in m.files, f"{rel} not tracked in manifest"

    def test_install_uninstall_roundtrip(self, tmp_path):
        i = get_integration(self.KEY)
        m = IntegrationManifest(self.KEY, tmp_path)
        created = i.install(tmp_path, m)
        assert len(created) > 0
        m.save()
        for f in created:
            assert f.exists()
        removed, skipped = i.uninstall(tmp_path, m)
        assert len(removed) == len(created)
        assert skipped == []

    def test_modified_file_survives_uninstall(self, tmp_path):
        i = get_integration(self.KEY)
        m = IntegrationManifest(self.KEY, tmp_path)
        created = i.install(tmp_path, m)
        m.save()
        modified_file = created[0]
        modified_file.write_text("user modified this", encoding="utf-8")
        removed, skipped = i.uninstall(tmp_path, m)
        assert modified_file.exists()
        assert modified_file in skipped

    # -- Scripts ----------------------------------------------------------

    def test_setup_installs_update_context_scripts(self, tmp_path):
        i = get_integration(self.KEY)
        m = IntegrationManifest(self.KEY, tmp_path)
        created = i.setup(tmp_path, m)
        scripts_dir = tmp_path / ".specify" / "integrations" / self.KEY / "scripts"
        assert scripts_dir.is_dir(), f"Scripts directory not created for {self.KEY}"
        assert (scripts_dir / "update-context.sh").exists()
        assert (scripts_dir / "update-context.ps1").exists()

    def test_scripts_tracked_in_manifest(self, tmp_path):
        i = get_integration(self.KEY)
        m = IntegrationManifest(self.KEY, tmp_path)
        i.setup(tmp_path, m)
        script_rels = [k for k in m.files if "update-context" in k]
        assert len(script_rels) >= 2

    def test_sh_script_is_executable(self, tmp_path):
        i = get_integration(self.KEY)
        m = IntegrationManifest(self.KEY, tmp_path)
        i.setup(tmp_path, m)
        sh = tmp_path / ".specify" / "integrations" / self.KEY / "scripts" / "update-context.sh"
        assert os.access(sh, os.X_OK)

    # -- CLI auto-promote -------------------------------------------------

    def test_ai_flag_auto_promotes(self, tmp_path):
        from typer.testing import CliRunner
        from specify_cli import app

        project = tmp_path / f"promote-{self.KEY}"
        project.mkdir()
        old_cwd = os.getcwd()
        try:
            os.chdir(project)
            runner = CliRunner()
            result = runner.invoke(app, [
                "init", "--here", "--ai", self.KEY, "--script", "sh", "--no-git",
                "--ignore-agent-tools",
            ], catch_exceptions=False)
        finally:
            os.chdir(old_cwd)
        assert result.exit_code == 0, f"init --ai {self.KEY} failed: {result.output}"
        i = get_integration(self.KEY)
        cmd_dir = i.commands_dest(project)
        assert cmd_dir.is_dir(), f"--ai {self.KEY} did not create commands directory"

    def test_integration_flag_creates_files(self, tmp_path):
        from typer.testing import CliRunner
        from specify_cli import app

        project = tmp_path / f"int-{self.KEY}"
        project.mkdir()
        old_cwd = os.getcwd()
        try:
            os.chdir(project)
            runner = CliRunner()
            result = runner.invoke(app, [
                "init", "--here", "--integration", self.KEY, "--script", "sh", "--no-git",
                "--ignore-agent-tools",
            ], catch_exceptions=False)
        finally:
            os.chdir(old_cwd)
        assert result.exit_code == 0, f"init --integration {self.KEY} failed: {result.output}"
        i = get_integration(self.KEY)
        cmd_dir = i.commands_dest(project)
        assert cmd_dir.is_dir(), f"Commands directory {cmd_dir} not created"
        commands = sorted(cmd_dir.glob("speckit.*.toml"))
        assert len(commands) > 0, f"No command files in {cmd_dir}"

    # -- Complete file inventory ------------------------------------------

    COMMAND_STEMS = [
        "analyze", "checklist", "clarify", "constitution",
        "implement", "plan", "specify", "tasks", "taskstoissues",
    ]

    def _expected_files(self, script_variant: str) -> list[str]:
        """Build the expected file list for this integration + script variant."""
        i = get_integration(self.KEY)
        cmd_dir = i.registrar_config["dir"]
        files = []

        # Command files (.toml)
        for stem in self.COMMAND_STEMS:
            files.append(f"{cmd_dir}/speckit.{stem}.toml")

        # Integration scripts
        files.append(f".specify/integrations/{self.KEY}/scripts/update-context.ps1")
        files.append(f".specify/integrations/{self.KEY}/scripts/update-context.sh")

        # Framework files
        files.append(f".specify/integration.json")
        files.append(f".specify/init-options.json")
        files.append(f".specify/integrations/{self.KEY}.manifest.json")
        files.append(f".specify/integrations/speckit.manifest.json")

        if script_variant == "sh":
            for name in ["check-prerequisites.sh", "common.sh", "create-new-feature.sh",
                         "setup-plan.sh", "update-agent-context.sh"]:
                files.append(f".specify/scripts/bash/{name}")
        else:
            for name in ["check-prerequisites.ps1", "common.ps1", "create-new-feature.ps1",
                         "setup-plan.ps1", "update-agent-context.ps1"]:
                files.append(f".specify/scripts/powershell/{name}")

        for name in ["agent-file-template.md", "checklist-template.md",
                     "constitution-template.md", "plan-template.md",
                     "spec-template.md", "tasks-template.md"]:
            files.append(f".specify/templates/{name}")

        files.append(".specify/memory/constitution.md")
        # AF bundled extension
        files += AF_EXTENSION_FILES
        for cmd in AF_EXTENSION_COMMANDS:
            files.append(f"{cmd_dir}/speckit.{cmd}.toml")
        return sorted(files)

    def test_complete_file_inventory_sh(self, tmp_path):
        """Every file produced by specify init --integration <key> --script sh."""
        from typer.testing import CliRunner
        from specify_cli import app

        project = tmp_path / f"inventory-sh-{self.KEY}"
        project.mkdir()
        old_cwd = os.getcwd()
        try:
            os.chdir(project)
            result = CliRunner().invoke(app, [
                "init", "--here", "--integration", self.KEY, "--script", "sh",
                "--no-git", "--ignore-agent-tools",
            ], catch_exceptions=False)
        finally:
            os.chdir(old_cwd)
        assert result.exit_code == 0, f"init failed: {result.output}"
        actual = sorted(p.relative_to(project).as_posix()
                        for p in project.rglob("*") if p.is_file())
        expected = self._expected_files("sh")
        assert actual == expected, (
            f"Missing: {sorted(set(expected) - set(actual))}\n"
            f"Extra: {sorted(set(actual) - set(expected))}"
        )

    def test_complete_file_inventory_ps(self, tmp_path):
        """Every file produced by specify init --integration <key> --script ps."""
        from typer.testing import CliRunner
        from specify_cli import app

        project = tmp_path / f"inventory-ps-{self.KEY}"
        project.mkdir()
        old_cwd = os.getcwd()
        try:
            os.chdir(project)
            result = CliRunner().invoke(app, [
                "init", "--here", "--integration", self.KEY, "--script", "ps",
                "--no-git", "--ignore-agent-tools",
            ], catch_exceptions=False)
        finally:
            os.chdir(old_cwd)
        assert result.exit_code == 0, f"init failed: {result.output}"
        actual = sorted(p.relative_to(project).as_posix()
                        for p in project.rglob("*") if p.is_file())
        expected = self._expected_files("ps")
        assert actual == expected, (
            f"Missing: {sorted(set(expected) - set(actual))}\n"
            f"Extra: {sorted(set(actual) - set(expected))}"
        )