agentbundle 0.33.3__tar.gz → 0.34.0__tar.gz

{agentbundle-0.33.3/agentbundle.egg-info → agentbundle-0.34.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentbundle
-Version: 0.33.3
+Version: 0.34.0
 Summary: npm for your coding agent. Install packs of skills, subagents, and hooks into any repo, for every major agent.
 Author-email: eugenelim <eugenelim@users.noreply.github.com>
 License-Expression: Apache-2.0 OR MIT
@@ -34,17 +34,25 @@ python -m pip install agentbundle
 
 Requires Python 3.11+. Runs on macOS, Linux, and Windows.
 
-## What's new in 0.33.3
+## What's new in 0.34.0
 
-`agentbundle catalogue self-host --write` now updates writable existing files
-without attempting owner-only timestamp or mode changes. This supports CI and
-development checkouts where projected files are owned by a different user;
-ownership, inode, and mode remain intact, while `--check` continues to report
-mode drift that the writer cannot repair.
+Inspect the exact public contracts bundled with the installed AgentBundle
+version without network access:
 
-The Windows compatibility command covers AgentBundle and pack portability;
-CredBroker maintainers should run that package's test suite separately on
-Windows.
+```bash
+agentbundle catalogue contracts list
+agentbundle catalogue contracts show pack.schema.json
+agentbundle catalogue contracts export --output ./reference-contracts
+```
+
+`list` and `show` are read-only. `export` writes reference copies through a
+no-follow, preflighted batch writer; those copies do not override the contracts
+AgentBundle uses for validation.
+
+Successful `agentbundle catalogue init` output now points to the scaffolded
+`guides/_shared/reference/catalogue-authoring-standards.md`, contract discovery,
+and catalogue verification. The guide's bundled-contract section documents all
+three commands. JSON init output remains unchanged.
 
 **Install into a repo** — so everyone who clones it gets the pack. `core` is the flagship pack, the loop itself:
 
@@ -263,6 +271,10 @@ agentbundle catalogue init --target /path/to/new-catalogue
 
 Scaffolds `catalogue.toml`, the required directory tree (`packs/`, `profiles/`, `contracts/`, `.claude-plugin/`), and a starter `marketplace.json`. Skips files that already exist; reports conflicts without overwriting. Pass `--dry-run` to preview.
 
+After initialization, use `agentbundle catalogue contracts list` to find the
+contract names bundled with your installed version. `show` prints one contract;
+`export --output <dir>` copies the full public set for offline reference.
+
 **Bootstrap a self-hosted enterprise catalogue** from an existing source:
 
 ```bash

{agentbundle-0.33.3 → agentbundle-0.34.0}/README-pypi.md

@@ -14,17 +14,25 @@ python -m pip install agentbundle
 
 Requires Python 3.11+. Runs on macOS, Linux, and Windows.
 
-## What's new in 0.33.3
+## What's new in 0.34.0
 
-`agentbundle catalogue self-host --write` now updates writable existing files
-without attempting owner-only timestamp or mode changes. This supports CI and
-development checkouts where projected files are owned by a different user;
-ownership, inode, and mode remain intact, while `--check` continues to report
-mode drift that the writer cannot repair.
+Inspect the exact public contracts bundled with the installed AgentBundle
+version without network access:
 
-The Windows compatibility command covers AgentBundle and pack portability;
-CredBroker maintainers should run that package's test suite separately on
-Windows.
+```bash
+agentbundle catalogue contracts list
+agentbundle catalogue contracts show pack.schema.json
+agentbundle catalogue contracts export --output ./reference-contracts
+```
+
+`list` and `show` are read-only. `export` writes reference copies through a
+no-follow, preflighted batch writer; those copies do not override the contracts
+AgentBundle uses for validation.
+
+Successful `agentbundle catalogue init` output now points to the scaffolded
+`guides/_shared/reference/catalogue-authoring-standards.md`, contract discovery,
+and catalogue verification. The guide's bundled-contract section documents all
+three commands. JSON init output remains unchanged.
 
 **Install into a repo** — so everyone who clones it gets the pack. `core` is the flagship pack, the loop itself:
 
@@ -243,6 +251,10 @@ agentbundle catalogue init --target /path/to/new-catalogue
 
 Scaffolds `catalogue.toml`, the required directory tree (`packs/`, `profiles/`, `contracts/`, `.claude-plugin/`), and a starter `marketplace.json`. Skips files that already exist; reports conflicts without overwriting. Pass `--dry-run` to preview.
 
+After initialization, use `agentbundle catalogue contracts list` to find the
+contract names bundled with your installed version. `show` prints one contract;
+`export --output <dir>` copies the full public set for offline reference.
+
 **Bootstrap a self-hosted enterprise catalogue** from an existing source:
 
 ```bash

{agentbundle-0.33.3 → agentbundle-0.34.0}/agentbundle/_data/catalogue-scaffold/guides/_shared/reference/catalogue-authoring-standards.md

@@ -407,6 +407,23 @@ every optional pack.
 
 ---
 
+## 12. Bundled contract inspection
+
+List, inspect, or export the contracts bundled with the running AgentBundle version
+without network access:
+
+```bash
+agentbundle catalogue contracts list
+agentbundle catalogue contracts show <name>
+agentbundle catalogue contracts export --output <dir>
+```
+
+`list` and `show` are read-only. `export` writes one regular file per listed contract
+to the selected directory. These are reference copies only. They do not override the
+contracts used for validation by this agentbundle version.
+
+---
+
 ## Journey format
 
 > **Not yet available.** Wave 4 of the catalogue-contracts initiative will define the

{agentbundle-0.33.3 → agentbundle-0.34.0}/agentbundle/_data/catalogue-scaffold/manifest.json

@@ -1,6 +1,6 @@
 {
   "files": {
-    "guides/_shared/reference/catalogue-authoring-standards.md": "ff4bdc203affda0a2f41641c1155b3f4e90aade022e122999a82e7093e94d2ee",
+    "guides/_shared/reference/catalogue-authoring-standards.md": "3217e6bfcc15dc116d40e1b327b6bf19b66212c7e13553e42966f9982b3c3487",
     "guides/_shared/reference/catalogue-ci-contract.md": "fae793ab47989b6dd3c731afcb0b4cda21c7d08bbe7fa40fca6d3abb3d158141",
     "packs/AGENTS.md": "9bfeda4069826e518a4f4fdae45bd40f4393c1c5aaf146149d3eb4aece30be83",
     "packs/README.md": "d2de5f9556f4c8e521103474bde74636e02cc805f9bf5312a3a61a1f3eb45d8f",

agentbundle-0.34.0/agentbundle/_data/public-contracts.txt

@@ -0,0 +1,12 @@
+adapter.schema.json
+adapter.toml
+catalogue.schema.json
+guide.schema.json
+marketplace-entry.schema.json
+pack.schema.json
+plugin-manifest.derived.schema.json
+plugin-manifest.schema.json
+profile.schema.json
+skill-manifest.schema.json
+skill.schema.json
+target-vocab.toml

{agentbundle-0.33.3 → agentbundle-0.34.0}/agentbundle/build/projection_io.py

@@ -15,6 +15,10 @@ from contextlib import contextmanager
 from pathlib import Path
 from typing import Literal
 
+from agentbundle.safety import _is_reparse_point as _safety_is_reparse_point
+from agentbundle.safety import _secure_dir_fd_available as _safety_secure_dir_fd_available
+from agentbundle.safety import _write_all as _safety_write_all
+
 
 class ProjectionTypeError(OSError):
     """A projected target exists but is not a regular file."""
@@ -30,9 +34,11 @@ def render_diagnostic_path(path: Path) -> str:
 
 
 def _secure_dir_fd_available() -> bool:
-    return os.name == "posix" and all(
-        hasattr(os, name) for name in ("O_DIRECTORY", "O_NOFOLLOW")
-    )
+    """Re-exported from ``agentbundle.safety`` — see that module for the rule.
+
+    Kept as a module-level name so tests can monkeypatch it here.
+    """
+    return _safety_secure_dir_fd_available()
 
 
 def _validate_relative(relative: Path) -> None:
@@ -40,10 +46,7 @@ def _validate_relative(relative: Path) -> None:
         raise ValueError(f"projection path must stay relative to its base: {relative}")
 
 
-def _is_reparse_point(path_stat: os.stat_result) -> bool:
-    attributes = getattr(path_stat, "st_file_attributes", 0)
-    reparse_flag = getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0)
-    return bool(attributes & reparse_flag)
+_is_reparse_point = _safety_is_reparse_point
 
 
 def _validate_fallback_path(
@@ -159,14 +162,7 @@ def open_directory_no_follow(base: Path, relative: Path) -> Iterator[int | None]
         os.close(base_fd)
 
 
-def _write_all(file_descriptor: int, content: bytes) -> None:
-    """Write all ``content`` to an open descriptor."""
-    view = memoryview(content)
-    while view:
-        written = os.write(file_descriptor, view)
-        if written == 0:
-            raise OSError(errno.EIO, "projection write made no progress")
-        view = view[written:]
+_write_all = _safety_write_all
 
 
 def _read_bounded(

agentbundle-0.34.0/agentbundle/catalogue_tooling/contracts_inspector.py

@@ -0,0 +1,112 @@
+"""Read and export the public contracts bundled with AgentBundle."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from importlib.resources import files as resource_files
+from importlib.resources.abc import Traversable
+from pathlib import Path
+
+from agentbundle.safety import assert_portable_name, write_files_no_follow
+
+_INVENTORY = "public-contracts.txt"
+
+
+class ContractResourceError(RuntimeError):
+    """A bundled public-contract resource is missing or invalid."""
+
+
+@dataclass(frozen=True)
+class ContractInfo:
+    """Metadata for one public bundled contract."""
+
+    name: str
+    kind: str
+    file: str
+
+
+def _data_dir() -> Traversable:
+    """Return the package-data root without consulting source checkout paths."""
+    return resource_files("agentbundle").joinpath("_data")
+
+
+def _inventory_names() -> list[str]:
+    """Read and validate the generated positive-membership inventory."""
+    try:
+        inventory = _data_dir().joinpath(_INVENTORY).read_text(encoding="utf-8")
+    except (OSError, UnicodeError) as exc:
+        raise ContractResourceError(
+            "bundled contract inventory is unavailable"
+        ) from exc
+    names = [line for line in inventory.splitlines() if line]
+    # An empty inventory means a truncated or mis-built wheel. Without this
+    # check `contracts list` prints a bare header and exits 0 — reporting
+    # success for an installation that ships no contracts at all.
+    if not names:
+        raise ContractResourceError("bundled contract inventory is empty")
+    if names != sorted(names) or len(names) != len(set(names)):
+        raise ContractResourceError("bundled contract inventory is invalid")
+    for name in names:
+        if (
+            name in {".", ".."}
+            or "/" in name
+            or "\\" in name
+            or not name.endswith((".json", ".toml"))
+        ):
+            raise ContractResourceError("bundled contract inventory is invalid")
+        # `assert_portable_name` covers Windows-poisonous names but not
+        # control characters; a NUL would otherwise reach
+        # `Traversable.joinpath` and surface as an uncaught ValueError.
+        if any(character < " " or character == "\x7f" for character in name):
+            raise ContractResourceError("bundled contract inventory is invalid")
+        try:
+            assert_portable_name(name)
+        except ValueError as exc:
+            raise ContractResourceError(
+                "bundled contract inventory is invalid"
+            ) from exc
+    return names
+
+
+def _kind(name: str) -> str:
+    if name.endswith(".schema.json"):
+        return "json-schema"
+    if name.endswith(".toml"):
+        return "toml"
+    return "json"
+
+
+def list_bundled_contracts() -> list[ContractInfo]:
+    """Return ordered metadata for positively inventoried public contracts."""
+    return [
+        ContractInfo(name=name, kind=_kind(name), file=name)
+        for name in _inventory_names()
+    ]
+
+
+def show_contract(name: str) -> str | None:
+    """Return one public bundled contract, or ``None`` for an unknown name."""
+    if "/" in name or "\\" in name:
+        return None
+    if name not in {contract.name for contract in list_bundled_contracts()}:
+        return None
+    try:
+        return _data_dir().joinpath(name).read_text(encoding="utf-8")
+    except (OSError, UnicodeError) as exc:
+        raise ContractResourceError("bundled contract resource is unavailable") from exc
+
+
+def export_contracts(output_dir: Path) -> list[str]:
+    """Export every public bundled contract through the no-follow batch writer."""
+    contracts = list_bundled_contracts()
+    data = _data_dir()
+    try:
+        contents = {
+            contract.file: data.joinpath(contract.file).read_bytes()
+            for contract in contracts
+        }
+    except OSError as exc:
+        raise ContractResourceError("bundled contract resource is unavailable") from exc
+    # Report what the writer actually wrote, not what we intended to write —
+    # the two can only diverge through a bug, and this way the manifest says so.
+    return [path.name for path in write_files_no_follow(output_dir, contents)]

{agentbundle-0.33.3 → agentbundle-0.34.0}/agentbundle/cli.py

@@ -1049,6 +1049,40 @@ def _build_parser() -> argparse.ArgumentParser:
     )
     _init_p.set_defaults(func=_lazy("catalogue_init"))
 
+    # catalogue contracts
+    _contracts_p = cat_subs.add_parser(
+        "contracts",
+        help="Inspect contracts bundled with this agentbundle version.",
+    )
+    _contracts_subs = _contracts_p.add_subparsers(
+        dest="contracts_sub", metavar="<sub>"
+    )
+    _contracts_p.set_defaults(func=_lazy("catalogue_contracts"))
+
+    _contracts_list_p = _contracts_subs.add_parser(
+        "list", help="List all bundled contracts."
+    )
+    _contracts_list_p.add_argument(
+        "--format", choices=("table", "json"), default="table"
+    )
+    _contracts_list_p.set_defaults(func=_lazy("catalogue_contracts"))
+
+    _contracts_show_p = _contracts_subs.add_parser(
+        "show", help="Show content of a bundled contract."
+    )
+    _contracts_show_p.add_argument(
+        "name", metavar="<name>", help="Contract name (from 'contracts list')."
+    )
+    _contracts_show_p.set_defaults(func=_lazy("catalogue_contracts"))
+
+    _contracts_export_p = _contracts_subs.add_parser(
+        "export", help="Export all bundled contracts to a directory."
+    )
+    _contracts_export_p.add_argument(
+        "--output", required=True, metavar="<dir>", help="Output directory."
+    )
+    _contracts_export_p.set_defaults(func=_lazy("catalogue_contracts"))
+
     # --- lint packs --- (Wave 2; implemented)
     lint_parser = subparsers.add_parser(
         "lint",

agentbundle-0.34.0/agentbundle/commands/catalogue_contracts.py

@@ -0,0 +1,105 @@
+"""``agentbundle catalogue contracts`` command handler."""
+
+from __future__ import annotations
+
+import dataclasses
+import json
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from agentbundle.catalogue_tooling.contracts_inspector import (
+    ContractResourceError,
+    export_contracts,
+    list_bundled_contracts,
+    show_contract,
+)
+from agentbundle.safety import WriteError
+
+if TYPE_CHECKING:
+    import argparse
+
+_REFERENCE_NOTICE = (
+    "These are reference copies only. They do not override the contracts used "
+    "for validation by this agentbundle version."
+)
+
+
+def _run_list(args: argparse.Namespace) -> int:
+    try:
+        contracts = list_bundled_contracts()
+    except ContractResourceError:
+        print("error: bundled contract resources are unavailable", file=sys.stderr)
+        return 1
+    if getattr(args, "format", "table") == "json":
+        print(json.dumps([dataclasses.asdict(contract) for contract in contracts]))
+        return 0
+
+    rows = [("NAME", "KIND", "FILE")] + [
+        (contract.name, contract.kind, contract.file) for contract in contracts
+    ]
+    # Pad to the widest cell so the header actually labels its column.
+    widths = [max(len(row[column]) for row in rows) for column in range(3)]
+    for row in rows:
+        print(f"{row[0]:<{widths[0]}}  {row[1]:<{widths[1]}}  {row[2]}")
+    return 0
+
+
+def _run_show(args: argparse.Namespace) -> int:
+    name = str(args.name)
+    try:
+        content = show_contract(name)
+    except (ContractResourceError, OSError, ValueError):
+        print("error: bundled contract resources are unavailable", file=sys.stderr)
+        return 1
+    if content is None:
+        print(f"error: unrecognized bundled contract {name!r}", file=sys.stderr)
+        return 1
+    sys.stdout.write(content)
+    return 0
+
+
+def _run_export(args: argparse.Namespace) -> int:
+    try:
+        written = export_contracts(Path(args.output))
+    except ContractResourceError:
+        print("error: bundled contract resources are unavailable", file=sys.stderr)
+        return 2
+    except ValueError as exc:
+        message = str(exc).replace("\n", " ")
+        print(f"error: cannot export bundled contracts: {message}", file=sys.stderr)
+        return 2
+    except WriteError as exc:
+        # WriteError subclasses OSError, so it must be caught first. Its
+        # messages name only the user-supplied output path and are the one
+        # actionable signal here ("permission denied", "no space left").
+        message = str(exc).replace("\n", " ")
+        print(f"error: cannot export bundled contracts: {message}", file=sys.stderr)
+        return 2
+    except OSError:
+        print(
+            "error: cannot export bundled contracts: filesystem operation failed",
+            file=sys.stderr,
+        )
+        return 2
+    for filename in written:
+        print(filename)
+    print(_REFERENCE_NOTICE, file=sys.stderr)
+    return 0
+
+
+def run(args: argparse.Namespace) -> int:
+    """Dispatch a bundled-contract operation."""
+    subcommand = getattr(args, "contracts_sub", None)
+    if subcommand == "list":
+        return _run_list(args)
+    if subcommand == "show":
+        return _run_show(args)
+    if subcommand == "export":
+        return _run_export(args)
+    print(
+        "agentbundle catalogue contracts: specify a subcommand "
+        "(list, show, export)",
+        file=sys.stderr,
+    )
+    return 1

{agentbundle-0.33.3 → agentbundle-0.34.0}/agentbundle/commands/catalogue_init.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import dataclasses
 import json
+import shlex
 import sys
 from pathlib import Path
 from typing import TYPE_CHECKING
@@ -134,6 +135,33 @@ def _run_plain(args: argparse.Namespace) -> int:
                 f"Catalogue '{result.catalogue.name}' initialized at {result.target}",
                 file=sys.stderr,
             )
+            print("", file=sys.stderr)
+            print("  Next steps:", file=sys.stderr)
+            # Anchor the path to the initialized target: the guide lives at
+            # <target>/guides/..., so a bare relative path only resolves if
+            # the reader has already cd'd in.
+            standards_path = shlex.quote(
+                f"{result.target.rstrip('/')}/guides/_shared/reference/"
+                "catalogue-authoring-standards.md"
+            )
+            print(
+                f"    • See {standards_path} for authoring standards.",
+                file=sys.stderr,
+            )
+            print(
+                "    • Run 'agentbundle catalogue contracts list' to view "
+                "bundled contract schemas.",
+                file=sys.stderr,
+            )
+            # No surrounding quotes: shlex.quote already adds them when the
+            # target needs them, and nesting produces an uncopyable command.
+            verify_command = (
+                f"agentbundle catalogue verify --root {shlex.quote(result.target)}"
+            )
+            print(
+                f"    • Run {verify_command} to validate your catalogue.",
+                file=sys.stderr,
+            )
     else:
         s = result.summary
         if s.conflict > 0: