agentbundle 0.2.0__py3-none-any.whl

agentbundle/build/tests/test_validate.py

@@ -0,0 +1,250 @@
+"""Tests for the stdlib JSON-Schema subset validator (T1a)."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+import unittest
+from pathlib import Path
+
+from agentbundle.build.validate import validate
+
+REPO_ROOT = Path(__file__).resolve().parents[5]
+SCHEMA_PATH = REPO_ROOT / "docs" / "contracts" / "adapter.schema.json"
+
+
+class TypeKeywordTests(unittest.TestCase):
+    def test_object_accepts_dict(self) -> None:
+        self.assertEqual(validate({}, {"type": "object"}), [])
+
+    def test_object_rejects_list(self) -> None:
+        errors = validate([], {"type": "object"})
+        self.assertTrue(errors)
+        self.assertIn("expected object", errors[0])
+
+    def test_string_accepts_string(self) -> None:
+        self.assertEqual(validate("x", {"type": "string"}), [])
+
+    def test_string_rejects_integer(self) -> None:
+        errors = validate(7, {"type": "string"})
+        self.assertTrue(errors)
+
+    def test_integer_rejects_boolean(self) -> None:
+        # Python bool is a subclass of int; the validator must reject it.
+        errors = validate(True, {"type": "integer"})
+        self.assertTrue(errors)
+        self.assertIn("boolean", errors[0])
+
+    def test_boolean_accepts_true(self) -> None:
+        self.assertEqual(validate(True, {"type": "boolean"}), [])
+
+    def test_boolean_rejects_integer(self) -> None:
+        errors = validate(1, {"type": "boolean"})
+        self.assertTrue(errors)
+
+    def test_array_accepts_list(self) -> None:
+        self.assertEqual(validate([1, 2], {"type": "array"}), [])
+
+    def test_array_rejects_string(self) -> None:
+        errors = validate("nope", {"type": "array"})
+        self.assertTrue(errors)
+
+
+class RequiredKeywordTests(unittest.TestCase):
+    def test_required_present(self) -> None:
+        schema = {"type": "object", "required": ["a"]}
+        self.assertEqual(validate({"a": 1}, schema), [])
+
+    def test_required_missing(self) -> None:
+        schema = {"type": "object", "required": ["a"]}
+        errors = validate({}, schema)
+        self.assertTrue(errors)
+        self.assertIn("missing required property", errors[0])
+
+
+class EnumKeywordTests(unittest.TestCase):
+    def test_enum_accepts_member(self) -> None:
+        self.assertEqual(validate("a", {"enum": ["a", "b"]}), [])
+
+    def test_enum_rejects_non_member(self) -> None:
+        errors = validate("c", {"enum": ["a", "b"]})
+        self.assertTrue(errors)
+        self.assertIn("not in enum", errors[0])
+
+
+class PatternKeywordTests(unittest.TestCase):
+    def test_pattern_match(self) -> None:
+        self.assertEqual(validate("abc123", {"pattern": "^[a-z]+[0-9]+$"}), [])
+
+    def test_pattern_mismatch(self) -> None:
+        errors = validate("nope!", {"pattern": "^[a-z]+$"})
+        self.assertTrue(errors)
+
+
+class ItemsKeywordTests(unittest.TestCase):
+    def test_items_homogeneous(self) -> None:
+        schema = {"type": "array", "items": {"type": "string"}}
+        self.assertEqual(validate(["a", "b"], schema), [])
+
+    def test_items_rejects_wrong_type(self) -> None:
+        schema = {"type": "array", "items": {"type": "string"}}
+        errors = validate(["a", 1], schema)
+        self.assertTrue(errors)
+
+
+class PropertiesAndAdditionalTests(unittest.TestCase):
+    def test_additional_properties_false(self) -> None:
+        schema = {
+            "type": "object",
+            "properties": {"a": {"type": "string"}},
+            "additionalProperties": False,
+        }
+        errors = validate({"a": "x", "b": "y"}, schema)
+        self.assertTrue(errors)
+        self.assertIn("additional property", errors[0])
+
+    def test_additional_properties_default_allows(self) -> None:
+        schema = {"type": "object", "properties": {"a": {"type": "string"}}}
+        self.assertEqual(validate({"a": "x", "b": "y"}, schema), [])
+
+
+class SchemaJsonSelfValidationTests(unittest.TestCase):
+    """The shipped adapter.schema.json must load and validate at least one minimal
+    contract — a smoke test for T1a's authored schema."""
+
+    def test_schema_loads(self) -> None:
+        schema = json.loads(SCHEMA_PATH.read_text(encoding="utf-8"))
+        self.assertEqual(schema.get("type"), "object")
+
+    def test_schema_accepts_minimal_contract(self) -> None:
+        schema = json.loads(SCHEMA_PATH.read_text(encoding="utf-8"))
+        minimal = {
+            "contract": {"version": "0.1"},
+            "primitive": {
+                "skill": {"source-path": ".apm/skills/"},
+                "agent": {"source-path": ".apm/agents/"},
+                "hook-body": {"source-path": ".apm/hooks/"},
+                "hook-wiring": {"source-path": ".apm/hook-wiring/"},
+                "command": {"source-path": ".apm/commands/"},
+            },
+            "adapter": {
+                "claude-code": {
+                    "projection": [
+                        {
+                            "primitive": "skill",
+                            "mode": "direct-directory",
+                            "target-path": ".claude/skills/",
+                            "on-conflict": "prompt-then-preserve",
+                        }
+                    ]
+                }
+            },
+        }
+        errors = validate(minimal, schema)
+        self.assertEqual(errors, [], f"schema rejected minimal contract: {errors}")
+
+    def test_schema_rejects_unknown_mode(self) -> None:
+        schema = json.loads(SCHEMA_PATH.read_text(encoding="utf-8"))
+        bad = {
+            "contract": {"version": "0.1"},
+            "primitive": {
+                "skill": {"source-path": ".apm/skills/"},
+                "agent": {"source-path": ".apm/agents/"},
+                "hook-body": {"source-path": ".apm/hooks/"},
+                "hook-wiring": {"source-path": ".apm/hook-wiring/"},
+                "command": {"source-path": ".apm/commands/"},
+            },
+            "adapter": {
+                "claude-code": {
+                    "projection": [
+                        {
+                            "primitive": "skill",
+                            "mode": "bogus-mode",
+                            "target-path": ".claude/skills/",
+                            "on-conflict": "prompt-then-preserve",
+                        }
+                    ]
+                }
+            },
+        }
+        errors = validate(bad, schema)
+        self.assertTrue(errors, "schema accepted an unknown projection mode")
+
+
+class CliValidateSubcommandTests(unittest.TestCase):
+    """`python -m agentbundle.build validate <path>` smoke test.
+
+    Uses subprocess so the test exercises the actual argparse wiring.
+    Does not rely on adapter.toml existing (T1b authors that); writes
+    a temp TOML and validates it against the shipped schema.
+    """
+
+    def test_validate_subcommand_exits_zero_on_minimal_contract(self) -> None:
+        import tempfile
+
+        toml_text = """
+[contract]
+version = "0.1"
+
+[primitive.skill]
+source-path = ".apm/skills/"
+
+[primitive.agent]
+source-path = ".apm/agents/"
+
+[primitive.hook-body]
+source-path = ".apm/hooks/"
+
+[primitive.hook-wiring]
+source-path = ".apm/hook-wiring/"
+
+[primitive.command]
+source-path = ".apm/commands/"
+
+[[adapter.claude-code.projection]]
+primitive = "skill"
+mode = "direct-directory"
+target-path = ".claude/skills/"
+on-conflict = "prompt-then-preserve"
+"""
+        with tempfile.NamedTemporaryFile(
+            mode="w", suffix=".toml", delete=False
+        ) as tmp:
+            tmp.write(toml_text)
+            tmp_path = tmp.name
+
+        result = subprocess.run(
+            [sys.executable, "-m", "agentbundle.build", "validate", tmp_path],
+            capture_output=True,
+            text=True,
+            cwd=REPO_ROOT,
+        )
+        self.assertEqual(
+            result.returncode,
+            0,
+            f"validate subcommand failed: stderr={result.stderr}",
+        )
+
+    def test_help_exits_zero(self) -> None:
+        result = subprocess.run(
+            [sys.executable, "-m", "agentbundle.build", "--help"],
+            capture_output=True,
+            text=True,
+            cwd=REPO_ROOT,
+        )
+        self.assertEqual(result.returncode, 0)
+        self.assertIn("validate", result.stdout)
+
+    def test_validate_help_exits_zero(self) -> None:
+        result = subprocess.run(
+            [sys.executable, "-m", "agentbundle.build", "validate", "--help"],
+            capture_output=True,
+            text=True,
+            cwd=REPO_ROOT,
+        )
+        self.assertEqual(result.returncode, 0)
+
+
+if __name__ == "__main__":
+    unittest.main()

agentbundle/build/validate.py

@@ -0,0 +1,141 @@
+"""Stdlib-only JSON-Schema subset validator.
+
+The build pipeline depends on stdlib only (per spec § Boundaries —
+Never do), so we cannot import a JSON-Schema library. This module
+ships the subset RFC-0001 + spec AC #6 commit to:
+
+Supported keywords:
+  - `type`: one of "object", "array", "string", "integer", "boolean"
+  - `properties`: object → schema map (only meaningful when type=object)
+  - `required`: list of property names (only meaningful when type=object)
+  - `enum`: list of allowed scalar values
+  - `pattern`: regex string applied to strings (via `re`)
+  - `items`: schema applied element-wise (only meaningful when type=array)
+  - `additionalProperties`: bool or schema (only meaningful when type=object)
+  - `minItems`: integer; array must have at least this many items
+  - `contains`: subschema; array must have at least one item matching it
+  - `if` / `then` / `else`: conditional subschemas (all three applied to
+    the same instance as the parent). RFC-0004's pack.schema.json uses
+    this trio to express "v0.2 packs require `[pack.install]`" and
+    "default-scope ∈ allowed-scopes."
+
+Unsupported by design: `$ref`, `$defs`, `oneOf`, `anyOf`, `allOf`,
+`not`, `format`, `minimum`/`maximum`, `minLength`/`maxLength`. If the
+contract grows a need, an RFC amends this subset; the validator does
+not silently expand.
+
+`validate(instance, schema)` returns a list of error strings — empty
+list means valid. Callers decide how to surface (the CLI's `validate`
+subcommand prints them to stderr and exits non-zero).
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+_TYPE_PYTHON = {
+    "object": dict,
+    "array": list,
+    "string": str,
+    "integer": int,
+    "boolean": bool,
+}
+
+
+def validate(instance: Any, schema: dict, path: str = "$") -> list[str]:
+    """Validate `instance` against `schema`. Return a list of error strings."""
+    errors: list[str] = []
+    if not isinstance(schema, dict):
+        return [f"{path}: schema is not an object"]
+
+    expected_type = schema.get("type")
+    if expected_type is not None:
+        if expected_type not in _TYPE_PYTHON:
+            return [f"{path}: unsupported type {expected_type!r}"]
+        py_type = _TYPE_PYTHON[expected_type]
+        # bool is a subclass of int in Python; reject bool when integer is expected
+        # and reject int when boolean is expected.
+        if expected_type == "integer" and isinstance(instance, bool):
+            errors.append(f"{path}: expected integer, got boolean")
+            return errors
+        if expected_type == "boolean" and not isinstance(instance, bool):
+            errors.append(f"{path}: expected boolean, got {type(instance).__name__}")
+            return errors
+        if not isinstance(instance, py_type):
+            errors.append(
+                f"{path}: expected {expected_type}, got {type(instance).__name__}"
+            )
+            return errors
+
+    if "enum" in schema:
+        if instance not in schema["enum"]:
+            errors.append(
+                f"{path}: value {instance!r} not in enum {schema['enum']!r}"
+            )
+
+    if "pattern" in schema and isinstance(instance, str):
+        if re.search(schema["pattern"], instance) is None:
+            errors.append(
+                f"{path}: value {instance!r} does not match pattern {schema['pattern']!r}"
+            )
+
+    # `required`, `properties`, `additionalProperties` apply whenever the
+    # instance is a dict — per JSON-Schema 2020-12, these keywords are
+    # vacuously true for non-object instances. Gating on `expected_type ==
+    # "object"` (the previous shape) caused subschemas with no `type`
+    # declaration (e.g. RFC-0004's `if`/`then` blocks) to silently skip
+    # their constraints — surprising callers and breaking the cross-field
+    # `default-scope ∈ allowed-scopes` invariant. Stay safe-by-default:
+    # apply when the instance matches.
+    if isinstance(instance, dict):
+        for required_key in schema.get("required", []):
+            if required_key not in instance:
+                errors.append(f"{path}: missing required property {required_key!r}")
+        properties = schema.get("properties", {})
+        for key, value in instance.items():
+            subpath = f"{path}.{key}"
+            if key in properties:
+                errors.extend(validate(value, properties[key], subpath))
+            else:
+                additional = schema.get("additionalProperties", True)
+                if additional is False:
+                    errors.append(f"{path}: additional property {key!r} not allowed")
+                elif isinstance(additional, dict):
+                    errors.extend(validate(value, additional, subpath))
+
+    if isinstance(instance, list):
+        item_schema = schema.get("items")
+        if isinstance(item_schema, dict):
+            for index, element in enumerate(instance):
+                errors.extend(validate(element, item_schema, f"{path}[{index}]"))
+        min_items = schema.get("minItems")
+        # bool is a subclass of int in Python — accept only true integers.
+        if isinstance(min_items, int) and not isinstance(min_items, bool):
+            if len(instance) < min_items:
+                errors.append(
+                    f"{path}: array has {len(instance)} item(s), minItems={min_items}"
+                )
+        contains_schema = schema.get("contains")
+        if isinstance(contains_schema, dict):
+            if not any(
+                not validate(element, contains_schema, f"{path}[{index}]")
+                for index, element in enumerate(instance)
+            ):
+                errors.append(
+                    f"{path}: no item matches the 'contains' subschema"
+                )
+
+    # Conditional subschemas — applied last so type/required/enum errors on
+    # the instance surface before any conditional branch fires. The 'if'
+    # subschema is evaluated silently (its errors are not surfaced); only
+    # the chosen branch's errors propagate. Per JSON-Schema 2020-12,
+    # missing 'then' or 'else' is a no-op for that branch.
+    if "if" in schema and isinstance(schema["if"], dict):
+        if_errors = validate(instance, schema["if"], path)
+        branch_key = "then" if not if_errors else "else"
+        branch_schema = schema.get(branch_key)
+        if isinstance(branch_schema, dict):
+            errors.extend(validate(instance, branch_schema, path))
+
+    return errors

agentbundle/catalogue.py

@@ -0,0 +1,164 @@
+"""Catalogue URI resolver — T5 deliverable, reused by T6/T8/T11/T12.
+
+Accepts:
+  - Local relative or absolute paths.
+  - ``git+https://github.com/<owner>/<repo>[@<ref>]``
+
+For ``git+https://`` URIs the resolver:
+  1. Parses owner, repo, and optional ref.
+  2. Constructs a GitHub archive URL (tag, branch, or SHA — tried in
+     that order by a light heuristic: tags contain only ``v`` + semver
+     chars or no slash; SHAs are exactly 40 hex chars; everything else
+     is a branch).
+  3. Fetches with ``urllib.request.urlopen`` — no subprocess, no git.
+  4. Extracts with ``tarfile`` into a per-call tempdir and returns the
+     inner ``<repo>-<ref>/`` directory.
+
+``git+ssh://`` URIs raise ``CatalogueError`` immediately — SSH is
+deferred to v1.1.
+
+Unreachable URLs raise ``CatalogueError`` with the tarball URL in the
+message so the caller can report exactly what was attempted.
+
+No subprocess calls anywhere in this module.
+"""
+
+from __future__ import annotations
+
+import atexit
+import re
+import shutil
+import tarfile
+import tempfile
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+_SSH_PREFIX = "git+ssh://"
+_HTTPS_PREFIX = "git+https://"
+
+# Match git+https://github.com/<owner>/<repo>[@<ref>]
+# Group 1: owner, Group 2: repo (no .git suffix), Group 3: ref (optional)
+_HTTPS_RE = re.compile(
+    r"^git\+https://github\.com/([^/]+)/([^/@]+?)(?:\.git)?(?:@([^@]+))?$"
+)
+
+# A SHA is exactly 40 lowercase hex digits (or 7–40 for abbreviated SHAs;
+# we accept the full pattern only to keep the heuristic simple).
+_SHA_RE = re.compile(r"^[0-9a-f]{7,40}$")
+
+
+class CatalogueError(ValueError):
+    """Raised when a catalogue URI cannot be resolved."""
+
+
+def resolve_catalogue(uri: str) -> Path:
+    """Resolve *uri* to a local directory rooted at the catalogue.
+
+    Returns a ``Path`` to the local directory. For ``git+https://`` URIs
+    the path lives inside a per-call tempdir registered with ``atexit``
+    so it's removed at process exit — see ``_resolve_https``. Callers
+    must not assume the directory survives past process termination.
+    """
+    if uri.startswith(_SSH_PREFIX):
+        raise CatalogueError(
+            "SSH git URLs deferred to v1.1; use https or local path."
+        )
+
+    if uri.startswith(_HTTPS_PREFIX):
+        return _resolve_https(uri)
+
+    # Local path — relative or absolute.
+    return Path(uri)
+
+
+def _resolve_https(uri: str) -> Path:
+    m = _HTTPS_RE.match(uri)
+    if not m:
+        raise CatalogueError(
+            f"Cannot parse git+https URI: {uri!r}. "
+            "Expected format: git+https://github.com/<owner>/<repo>[@<ref>]"
+        )
+    owner, repo, ref = m.group(1), m.group(2), m.group(3)
+    if not ref:
+        ref = "main"
+
+    tarball_url = _github_archive_url(owner, repo, ref)
+    tmpdir = Path(tempfile.mkdtemp(prefix="agentbundle-catalogue-"))
+    # Best-effort cleanup at process exit — atexit handlers run on normal
+    # interpreter shutdown; for crash paths the OS reaps /tmp eventually.
+    atexit.register(shutil.rmtree, str(tmpdir), True)
+    _fetch_and_extract(tarball_url, tmpdir)
+    # The GitHub archive extracts to <repo>-<ref>/ (with '/' → '-' in SHAs).
+    inner = _find_inner_dir(tmpdir)
+    return inner
+
+
+def _ref_type(ref: str) -> str:
+    """Heuristically classify a ref as 'tag', 'sha', or 'branch'.
+
+    The plan specifies: try tag, then branch, then SHA order — but we
+    need to pick exactly one URL at construction time because the caller
+    doesn't retry across URL forms (the tarball fetch either succeeds or
+    raises ``CatalogueError``).
+
+    Heuristic:
+      - Exactly 40 lowercase hex chars → SHA.
+      - Looks like a version tag (optional 'v' + digits/dots, e.g. v1.0
+        or 1.0.0) → tag.
+      - Anything else → branch.
+
+    This matches the plan's examples: ``v1.0`` → tag, ``main`` → branch,
+    ``deadbeef`` (7 chars) or a full 40-char SHA → sha.
+
+    Abbreviated SHAs (7–39 chars, all hex) are treated as SHA because
+    that's the most likely intent and ``archive/<sha>`` accepts prefixes.
+    """
+    if _SHA_RE.match(ref):
+        return "sha"
+    # Version tag pattern: optional 'v', one or more numeric segments
+    if re.match(r"^v?\d+(\.\d+)*$", ref):
+        return "tag"
+    return "branch"
+
+
+def _github_archive_url(owner: str, repo: str, ref: str) -> str:
+    rtype = _ref_type(ref)
+    if rtype == "tag":
+        return f"https://github.com/{owner}/{repo}/archive/refs/tags/{ref}.tar.gz"
+    if rtype == "branch":
+        return f"https://github.com/{owner}/{repo}/archive/refs/heads/{ref}.tar.gz"
+    # SHA
+    return f"https://github.com/{owner}/{repo}/archive/{ref}.tar.gz"
+
+
+def _fetch_and_extract(url: str, dest: Path) -> None:
+    try:
+        with urllib.request.urlopen(url) as resp:  # noqa: S310 — url is assembled from parsed owner/repo/ref
+            with tarfile.open(fileobj=resp, mode="r|gz") as tf:
+                # filter="data" rejects unsafe members (absolute paths, ..
+                # links, devices, setuid bits) — Python 3.12+ default but
+                # explicit for 3.11 compatibility and to silence the 3.14
+                # DeprecationWarning. Path-jail is belt; this is braces.
+                tf.extractall(path=dest, filter="data")  # noqa: S202
+    except urllib.error.URLError as exc:
+        raise CatalogueError(
+            f"Failed to fetch catalogue archive: {url} — {exc.reason}"
+        ) from exc
+    except tarfile.TarError as exc:
+        raise CatalogueError(
+            f"Failed to extract tarball from {url}: {exc}"
+        ) from exc
+
+
+def _find_inner_dir(tmpdir: Path) -> Path:
+    """Return the single top-level directory inside *tmpdir*.
+
+    GitHub archives always produce exactly one top-level directory
+    (``<repo>-<ref>/``). If the extraction produced something else,
+    return *tmpdir* itself so callers still have something to work with.
+    """
+    children = [p for p in tmpdir.iterdir() if p.is_dir()]
+    if len(children) == 1:
+        return children[0]
+    return tmpdir