agentbundle 0.2.0__py3-none-any.whl

agentbundle/build/tests/test_load_pack_hook_wiring_safely.py

@@ -0,0 +1,176 @@
+"""T1 (incompatible-hook-event-drop): construction tests for
+``_load_pack_hook_wiring_safely``.
+
+Five tests covering the three refusal paths (hook-wiring symlink, agent
+symlink, TOML parse failure) and the two happy-path shapes (clean pack,
+missing hook-wiring directory).
+
+These tests are written before the implementation exists (TDD red phase).
+"""
+
+from __future__ import annotations
+
+import os
+import tempfile
+import textwrap
+import unittest
+from pathlib import Path
+
+
+def _make_pack(
+    root: Path,
+    pack_name: str,
+    *,
+    wiring: dict[str, str] | None = None,
+    agents: list[str] | None = None,
+    wiring_symlinks: list[str] | None = None,
+    agent_symlinks: list[str] | None = None,
+) -> Path:
+    """Build a minimal pack fixture on disk.
+
+    - ``wiring``: stem → TOML body strings written under `.apm/hook-wiring/`.
+    - ``agents``: stems written as `.md` files under `.apm/agents/`.
+    - ``wiring_symlinks``: stems that become symlinks under `.apm/hook-wiring/`.
+    - ``agent_symlinks``: stems that become symlinks under `.apm/agents/`.
+    """
+    pack = root / pack_name
+    (pack / ".apm" / "hook-wiring").mkdir(parents=True, exist_ok=True)
+    (pack / ".apm" / "agents").mkdir(parents=True, exist_ok=True)
+
+    for stem, body in (wiring or {}).items():
+        (pack / ".apm" / "hook-wiring" / f"{stem}.toml").write_text(
+            body, encoding="utf-8"
+        )
+
+    for stem in agents or []:
+        (pack / ".apm" / "agents" / f"{stem}.md").write_text(
+            f"# {stem}\n", encoding="utf-8"
+        )
+
+    # Create dangling symlinks to simulate the security-rail case.
+    for stem in wiring_symlinks or []:
+        target_path = pack / ".apm" / "hook-wiring" / f"{stem}.toml"
+        # Point at a non-existent target so it's definitely a symlink.
+        os.symlink("/nonexistent/target.toml", target_path)
+
+    for stem in agent_symlinks or []:
+        target_path = pack / ".apm" / "agents" / f"{stem}.md"
+        os.symlink("/nonexistent/target.md", target_path)
+
+    return pack
+
+
+class TestLoadPackHookWiringSafely(unittest.TestCase):
+    """Construction tests for ``_load_pack_hook_wiring_safely``."""
+
+    def _import_helper(self):
+        from agentbundle.build.scope_rails import _load_pack_hook_wiring_safely
+        return _load_pack_hook_wiring_safely
+
+    def test_returns_loaded_tomls_when_clean(self) -> None:
+        """Happy path: valid hook-wiring + agents returns the (wiring_tomls, agent_basenames) tuple."""
+        helper = self._import_helper()
+        with tempfile.TemporaryDirectory() as raw:
+            tmp = Path(raw)
+            pack = _make_pack(
+                tmp,
+                "clean-pack",
+                wiring={
+                    "session-start": textwrap.dedent("""
+                        attach-to-agent = "work-loop"
+
+                        [[hooks.SessionStart]]
+                        command = "python3 tools/hooks/session-start.py"
+                    """).strip()
+                },
+                agents=["work-loop"],
+            )
+            result = helper(pack, "clean-pack")
+            # Should return a tuple, not a string.
+            self.assertIsInstance(result, tuple)
+            wiring_tomls, agent_basenames = result
+            self.assertIsInstance(wiring_tomls, dict)
+            self.assertIsInstance(agent_basenames, set)
+            # The parsed TOML dict should contain the "session-start" key.
+            self.assertIn("session-start", wiring_tomls)
+            # The agents set should contain the work-loop agent.
+            self.assertIn("work-loop", agent_basenames)
+
+    def test_returns_refusal_string_on_hook_wiring_symlink(self) -> None:
+        """Security rail: a symlink under .apm/hook-wiring/ returns a refusal string."""
+        helper = self._import_helper()
+        with tempfile.TemporaryDirectory() as raw:
+            tmp = Path(raw)
+            pack = _make_pack(
+                tmp,
+                "symlink-wiring-pack",
+                wiring_symlinks=["malicious"],
+                agents=["some-agent"],
+            )
+            result = helper(pack, "symlink-wiring-pack")
+            self.assertIsInstance(result, str)
+            self.assertIn("symlink-wiring-pack", result)
+            self.assertIn("hook-wiring entry is a symlink", result)
+
+    def test_returns_refusal_string_on_toml_parse_failure(self) -> None:
+        """Correctness rail: a malformed TOML returns a refusal string."""
+        helper = self._import_helper()
+        with tempfile.TemporaryDirectory() as raw:
+            tmp = Path(raw)
+            pack = _make_pack(
+                tmp,
+                "bad-toml-pack",
+                wiring={"broken": "this is not = valid = toml ["},
+                agents=["some-agent"],
+            )
+            result = helper(pack, "bad-toml-pack")
+            self.assertIsInstance(result, str)
+            self.assertIn("failed to parse", result)
+
+    def test_returns_refusal_string_on_agent_symlink(self) -> None:
+        """Security rail: a symlink under .apm/agents/ returns a refusal string."""
+        helper = self._import_helper()
+        with tempfile.TemporaryDirectory() as raw:
+            tmp = Path(raw)
+            pack = _make_pack(
+                tmp,
+                "symlink-agent-pack",
+                wiring={
+                    "on-prompt": textwrap.dedent("""
+                        attach-to-agent = "work-loop"
+
+                        [[hooks.userPromptSubmit]]
+                        command = "x"
+                    """).strip()
+                },
+                agent_symlinks=["work-loop"],
+            )
+            result = helper(pack, "symlink-agent-pack")
+            self.assertIsInstance(result, str)
+            self.assertIn("symlink-agent-pack", result)
+            self.assertIn("agent entry is a symlink", result)
+
+    def test_empty_hook_wiring_dir_returns_empty_tuple(self) -> None:
+        """Happy path: .apm/ exists but no hook-wiring/ subdir returns ({}, set()).
+
+        The plan specifies returning ({}, set()) for the uniform-type-signature
+        case — the helper short-circuits before agent discovery when there is
+        nothing to load from hook-wiring.
+        """
+        helper = self._import_helper()
+        with tempfile.TemporaryDirectory() as raw:
+            tmp = Path(raw)
+            pack = tmp / "no-wiring-pack"
+            # Only create .apm/ with agents — no hook-wiring/ subdir.
+            (pack / ".apm" / "agents").mkdir(parents=True, exist_ok=True)
+            (pack / ".apm" / "agents" / "work-loop.md").write_text("# work-loop\n", encoding="utf-8")
+            result = helper(pack, "no-wiring-pack")
+            self.assertIsInstance(result, tuple)
+            wiring_tomls, agent_basenames = result
+            self.assertEqual(wiring_tomls, {})
+            # Per the plan: ({}, set()) — short-circuits before agent discovery.
+            self.assertEqual(agent_basenames, set())
+
+
+if __name__ == "__main__":
+    unittest.main()

agentbundle/build/tests/test_pack_schema.py

@@ -0,0 +1,265 @@
+"""Tests for pack.schema.json (T1c).
+
+Verifies:
+  - pack.schema.json accepts a governance-extras recommended-on-core
+    example (AC 3).
+  - pack.schema.json rejects a pack.toml missing [pack].
+  - pack.schema.json rejects a pack.toml whose [pack.adaptation]
+    infer-from value is a non-string.
+  - pack.schema.json accepts a pack.toml without [pack.dependencies.required]
+    (required array is optional).
+  - pack.schema.json accepts [pack.seeds] entries that are relative-path
+    strings, and rejects an absolute path or a non-string entry.
+"""
+
+from __future__ import annotations
+
+import json
+import tomllib
+import unittest
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[5]
+PACK_SCHEMA_PATH = (
+    REPO_ROOT / "docs" / "contracts" / "pack.schema.json"
+)
+
+
+def _load_schema() -> dict:
+    return json.loads(PACK_SCHEMA_PATH.read_text(encoding="utf-8"))
+
+
+def _parse_toml(toml_text: str) -> dict:
+    return tomllib.loads(toml_text)
+
+
+class PackSchemaAcceptsValidExamplesTests(unittest.TestCase):
+    """pack.schema.json accepts well-formed pack.toml structures."""
+
+    def test_accepts_governance_extras_recommended_on_core(self) -> None:
+        """Modeled on RFC-0001's governance-extras recommended-on-core example.
+
+        Verifies AC 3: the schema accepts [pack], [pack.dependencies] with a
+        recommended array of {catalogue, pack, version} objects.
+        """
+        from agentbundle.build.validate import validate
+
+        schema = _load_schema()
+        toml_text = """
+[pack]
+name = "governance-extras"
+version = "0.1.0"
+description = "RFC/ADR ceremony skills (new-rfc, new-adr, update-conventions)."
+
+[pack.dependencies]
+recommended = [
+  { catalogue = "agent-ready-repo", pack = "core", version = ">=0.1.0" },
+]
+"""
+        instance = _parse_toml(toml_text)
+        errors = validate(instance, schema)
+        self.assertEqual(
+            errors,
+            [],
+            f"schema rejected valid governance-extras example:\n" + "\n".join(errors),
+        )
+
+    def test_accepts_pack_without_dependencies_required(self) -> None:
+        """A pack.toml without [pack.dependencies.required] is valid.
+
+        The required array is optional — missing-optional != malformed.
+        """
+        from agentbundle.build.validate import validate
+
+        schema = _load_schema()
+        toml_text = """
+[pack]
+name = "governance-extras"
+version = "0.1.0"
+description = "RFC/ADR ceremony skills."
+
+[pack.dependencies]
+recommended = [
+  { catalogue = "agent-ready-repo", pack = "core", version = ">=0.1.0" },
+]
+"""
+        instance = _parse_toml(toml_text)
+        errors = validate(instance, schema)
+        self.assertEqual(
+            errors,
+            [],
+            f"schema rejected pack without dependencies.required:\n"
+            + "\n".join(errors),
+        )
+
+    def test_accepts_pack_without_any_dependencies(self) -> None:
+        """A pack.toml with no [pack.dependencies] section at all is valid."""
+        from agentbundle.build.validate import validate
+
+        schema = _load_schema()
+        toml_text = """
+[pack]
+name = "core"
+version = "0.1.0"
+description = "Core agent skills."
+"""
+        instance = _parse_toml(toml_text)
+        errors = validate(instance, schema)
+        self.assertEqual(
+            errors,
+            [],
+            f"schema rejected pack without any dependencies:\n" + "\n".join(errors),
+        )
+
+    def test_accepts_seeds_with_relative_paths(self) -> None:
+        """[pack.seeds] entries that are relative-path strings are accepted.
+
+        Verifies the [pack.seeds] shape clause of AC 3.
+        """
+        from agentbundle.build.validate import validate
+
+        schema = _load_schema()
+        toml_text = """
+[pack]
+name = "core"
+version = "0.1.0"
+description = "Core agent skills."
+seeds = ["AGENTS.md", "docs/CHARTER.md", "docs/CONVENTIONS.md"]
+"""
+        instance = _parse_toml(toml_text)
+        errors = validate(instance, schema)
+        self.assertEqual(
+            errors,
+            [],
+            f"schema rejected valid relative-path seeds:\n" + "\n".join(errors),
+        )
+
+
+class PackSchemaRejectsInvalidExamplesTests(unittest.TestCase):
+    """pack.schema.json rejects malformed pack.toml structures."""
+
+    def test_rejects_missing_pack_section(self) -> None:
+        """A pack.toml without a [pack] section is rejected."""
+        from agentbundle.build.validate import validate
+
+        schema = _load_schema()
+        # Instance missing the required "pack" key entirely.
+        instance = {"metadata": {"name": "orphan"}}
+        errors = validate(instance, schema)
+        self.assertTrue(
+            errors,
+            "schema accepted a document missing the required [pack] section",
+        )
+        self.assertTrue(
+            any("pack" in e for e in errors),
+            f"error message should mention 'pack'; got: {errors}",
+        )
+
+    def test_rejects_adaptation_infer_from_non_string(self) -> None:
+        """[pack.adaptation] infer-from must be a string; non-string is rejected.
+
+        Shape-only check; the semantic set of legal values lives in the
+        adapt-to-project skill (out of scope here).
+        """
+        from agentbundle.build.validate import validate
+
+        schema = _load_schema()
+        toml_text = """
+[pack]
+name = "core"
+version = "0.1.0"
+
+[pack.adaptation]
+infer-from = 42
+"""
+        instance = _parse_toml(toml_text)
+        errors = validate(instance, schema)
+        self.assertTrue(
+            errors,
+            "schema accepted [pack.adaptation] infer-from as a non-string (integer)",
+        )
+
+    def test_rejects_adaptation_substitution_infer_from_non_string(self) -> None:
+        """infer-from inside a substitutions entry must be a string."""
+        from agentbundle.build.validate import validate
+
+        schema = _load_schema()
+        # Build the instance directly because TOML inline-table syntax
+        # would require tomllib to parse the mixed-type array, which is
+        # not the goal here — this verifies the schema constraint itself.
+        instance = {
+            "pack": {
+                "name": "core",
+                "version": "0.1.0",
+                "adaptation": {
+                    "substitutions": [
+                        {"marker": "<adapt:project-name>", "infer-from": 99}
+                    ]
+                },
+            }
+        }
+        errors = validate(instance, schema)
+        self.assertTrue(
+            errors,
+            "schema accepted substitutions[].infer-from as non-string (integer)",
+        )
+
+    def test_rejects_seeds_with_absolute_path(self) -> None:
+        """A seeds entry starting with '/' is an absolute path and must be rejected.
+
+        Verifies the [pack.seeds] shape clause of AC 3.
+        """
+        from agentbundle.build.validate import validate
+
+        schema = _load_schema()
+        toml_text = """
+[pack]
+name = "core"
+version = "0.1.0"
+seeds = ["/etc/foo"]
+"""
+        instance = _parse_toml(toml_text)
+        errors = validate(instance, schema)
+        self.assertTrue(
+            errors,
+            "schema accepted an absolute path in seeds (must start with non-'/')",
+        )
+
+    def test_rejects_seeds_with_non_string_entry(self) -> None:
+        """A seeds entry that is not a string (e.g. an inline table) is rejected.
+
+        Verifies the [pack.seeds] shape clause of AC 3.
+        """
+        from agentbundle.build.validate import validate
+
+        schema = _load_schema()
+        # Cannot express an inline-table in a seeds array via TOML easily
+        # for this validator, so construct the instance dict directly.
+        instance = {
+            "pack": {
+                "name": "core",
+                "version": "0.1.0",
+                "seeds": [{"path": "AGENTS.md"}],  # dict, not string
+            }
+        }
+        errors = validate(instance, schema)
+        self.assertTrue(
+            errors,
+            "schema accepted a non-string (dict) entry in seeds",
+        )
+
+
+class PackSchemaLoadsTests(unittest.TestCase):
+    """Smoke test: the schema file loads and has the expected top-level shape."""
+
+    def test_schema_loads(self) -> None:
+        schema = _load_schema()
+        self.assertEqual(schema.get("type"), "object")
+
+    def test_schema_requires_pack(self) -> None:
+        schema = _load_schema()
+        self.assertIn("pack", schema.get("required", []))
+
+
+if __name__ == "__main__":
+    unittest.main()

agentbundle/build/tests/test_pack_schema_allowed_adapters.py

@@ -0,0 +1,258 @@
+"""T3 tests for `[pack.install] allowed-adapters` validation
+(RFC-0011 / pack-allowed-adapters AC3, AC7, AC22).
+
+Two surfaces under test:
+
+  - the JSONSchema admits the optional `allowed-adapters` field (shape
+    check; the schema does NOT hardcode the adapter enum);
+  - the Python cross-field check `_validate_allowed_adapters` enforces
+    contract-shipped + user-scope-capable membership.
+
+Plus the `_kiro_target_adapters` literal-gate fix: v0.6 packs no longer
+silently skip the rail.
+"""
+
+from __future__ import annotations
+
+import json
+import tomllib
+import unittest
+from pathlib import Path
+
+from agentbundle.commands.validate import (
+    _kiro_target_adapters,
+    _validate_allowed_adapters,
+)
+
+REPO_ROOT = Path(__file__).resolve().parents[5]
+SCHEMA_PATH = (
+    REPO_ROOT
+    / "packages"
+    / "agentbundle"
+    / "agentbundle"
+    / "_data"
+    / "pack.schema.json"
+)
+
+
+def _load_schema() -> dict:
+    return json.loads(SCHEMA_PATH.read_text(encoding="utf-8"))
+
+
+def _v06_pack(install: dict | None = None, pack_extras: dict | None = None) -> dict:
+    """Build a minimal valid v0.6 pack dict for schema validation."""
+    pack = {
+        "name": "demo",
+        "version": "0.1.0",
+        "adapter-contract": {"version": "0.6"},
+    }
+    if install is not None:
+        pack["install"] = install
+    if pack_extras:
+        pack.update(pack_extras)
+    return {"pack": pack}
+
+
+# ---------------------------------------------------------------------------
+# Schema-shape tests (JSONSchema admits the field)
+# ---------------------------------------------------------------------------
+
+
+class TestSchemaShapeAllowedAdapters(unittest.TestCase):
+    def test_allowed_adapters_is_optional(self) -> None:
+        from agentbundle.build.validate import validate
+
+        # v0.6 pack omitting allowed-adapters: schema accepts.
+        pack = _v06_pack(install={"default-scope": "repo"})
+        errors = validate(pack, _load_schema())
+        self.assertEqual(errors, [])
+
+    def test_allowed_adapters_array_of_strings(self) -> None:
+        from agentbundle.build.validate import validate
+
+        pack = _v06_pack(
+            install={
+                "default-scope": "user",
+                "allowed-scopes": ["user"],
+                "allowed-adapters": ["claude-code", "kiro", "codex"],
+            }
+        )
+        errors = validate(pack, _load_schema())
+        self.assertEqual(errors, [])
+
+    def test_allowed_adapters_empty_array_refused_by_schema(self) -> None:
+        from agentbundle.build.validate import validate
+
+        pack = _v06_pack(
+            install={
+                "default-scope": "repo",
+                "allowed-adapters": [],
+            }
+        )
+        errors = validate(pack, _load_schema())
+        self.assertTrue(errors)
+
+    def test_allowed_adapters_duplicates_refused_by_cross_field(self) -> None:
+        # The bundled validator doesn't enforce JSONSchema uniqueItems;
+        # the cross-field check catches duplicates with a refuse message.
+        pack = _v06_pack(
+            install={
+                "default-scope": "repo",
+                "allowed-adapters": ["claude-code", "claude-code"],
+            }
+        )
+        msg = _validate_allowed_adapters(pack)
+        self.assertIsNotNone(msg)
+        self.assertIn("duplicate", msg)
+
+
+# ---------------------------------------------------------------------------
+# Cross-field check (`_validate_allowed_adapters`)
+# ---------------------------------------------------------------------------
+
+
+class TestValidateAllowedAdaptersCrossField(unittest.TestCase):
+    def test_returns_none_when_field_absent(self) -> None:
+        pack = _v06_pack(install={"default-scope": "repo"})
+        self.assertIsNone(_validate_allowed_adapters(pack))
+
+    def test_repo_only_pack_admits_copilot(self) -> None:
+        """Copilot is shipped but lacks user-scope; a repo-only pack
+        legitimately declares it."""
+        pack = _v06_pack(
+            install={
+                "default-scope": "repo",
+                "allowed-adapters": ["copilot"],
+            }
+        )
+        self.assertIsNone(_validate_allowed_adapters(pack))
+
+    def test_user_scope_pack_accepts_copilot(self) -> None:
+        # RFC-0024 / docs/specs/copilot-full-parity: copilot is now a
+        # user-scope-capable adapter (`[adapter.copilot.scope].user`), so a
+        # user-scope pack declaring it is **accepted** — the inverse of the
+        # repo-only refusal RFC-0012 recorded. (`research`, a user-scope-default
+        # pack, ships exactly this.)
+        pack = _v06_pack(
+            install={
+                "default-scope": "user",
+                "allowed-scopes": ["user"],
+                "allowed-adapters": ["copilot"],
+            }
+        )
+        msg = _validate_allowed_adapters(pack)
+        self.assertIsNone(msg, f"copilot should be accepted at user scope: {msg}")
+
+    def test_unknown_adapter_refused(self) -> None:
+        pack = _v06_pack(
+            install={
+                "default-scope": "repo",
+                "allowed-adapters": ["windsurf"],
+            }
+        )
+        msg = _validate_allowed_adapters(pack)
+        self.assertIsNotNone(msg)
+        self.assertIn("'windsurf'", msg)
+        self.assertIn("not a shipped adapter", msg)
+
+
+# ---------------------------------------------------------------------------
+# `_kiro_target_adapters` literal-gate fix (semantic predicate)
+# ---------------------------------------------------------------------------
+
+
+class TestKiroTargetAdaptersV06Gate(unittest.TestCase):
+    def _make_pack_tree(self, tmp_path: Path, *, with_agents: bool, with_wiring: bool):
+        apm = tmp_path / ".apm"
+        apm.mkdir(parents=True)
+        if with_agents:
+            (apm / "agents").mkdir()
+            (apm / "agents" / "a.md").write_text("dummy", encoding="utf-8")
+        if with_wiring:
+            (apm / "hook-wiring").mkdir()
+            (apm / "hook-wiring" / "w.toml").write_text("event = 'PreToolUse'\n", encoding="utf-8")
+        return tmp_path
+
+    def test_v06_pack_with_on_disk_shape_no_allowed_adapters_fires_rail(self) -> None:
+        """The case the round-1 literal `version != \"0.3\"` gate broke:
+        a v0.6 pack shipping agents + wiring without allowed-adapters
+        should still fire the rail through the on-disk inference path."""
+        import tempfile
+
+        with tempfile.TemporaryDirectory() as td:
+            pack_path = self._make_pack_tree(
+                Path(td), with_agents=True, with_wiring=True
+            )
+            pack_data = _v06_pack(install={"default-scope": "repo"})
+            result = _kiro_target_adapters(pack_data, pack_path)
+            self.assertEqual(result, {"kiro"})
+
+    def test_v06_pack_excluding_kiro_returns_empty(self) -> None:
+        import tempfile
+
+        with tempfile.TemporaryDirectory() as td:
+            pack_path = self._make_pack_tree(
+                Path(td), with_agents=True, with_wiring=True
+            )
+            pack_data = _v06_pack(
+                install={
+                    "default-scope": "user",
+                    "allowed-scopes": ["user"],
+                    "allowed-adapters": ["claude-code"],
+                }
+            )
+            result = _kiro_target_adapters(pack_data, pack_path)
+            self.assertEqual(result, set())
+
+    def test_v06_pack_including_kiro_returns_kiro(self) -> None:
+        import tempfile
+
+        with tempfile.TemporaryDirectory() as td:
+            pack_path = self._make_pack_tree(
+                Path(td), with_agents=False, with_wiring=False  # not even on-disk
+            )
+            pack_data = _v06_pack(
+                install={
+                    "default-scope": "user",
+                    "allowed-scopes": ["user"],
+                    "allowed-adapters": ["kiro"],
+                }
+            )
+            result = _kiro_target_adapters(pack_data, pack_path)
+            self.assertEqual(result, {"kiro"})
+
+    def test_v03_pack_unchanged(self) -> None:
+        import tempfile
+
+        with tempfile.TemporaryDirectory() as td:
+            pack_path = self._make_pack_tree(
+                Path(td), with_agents=True, with_wiring=True
+            )
+            pack_data = {
+                "pack": {
+                    "name": "demo",
+                    "adapter-contract": {"version": "0.3"},
+                }
+            }
+            result = _kiro_target_adapters(pack_data, pack_path)
+            self.assertEqual(result, {"kiro"})
+
+    def test_v02_pack_skips_rail(self) -> None:
+        import tempfile
+
+        with tempfile.TemporaryDirectory() as td:
+            pack_path = self._make_pack_tree(
+                Path(td), with_agents=True, with_wiring=True
+            )
+            pack_data = {
+                "pack": {
+                    "name": "demo",
+                    "adapter-contract": {"version": "0.2"},
+                }
+            }
+            result = _kiro_target_adapters(pack_data, pack_path)
+            self.assertEqual(result, set())
+
+
+if __name__ == "__main__":
+    unittest.main()