agentbundle 0.29.8__tar.gz → 0.31.0__tar.gz

{agentbundle-0.29.8 → agentbundle-0.31.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentbundle
-Version: 0.29.8
+Version: 0.31.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: Apache-2.0 OR MIT
@@ -269,7 +269,10 @@ ignore them there; the separation is structural, not incidental.
 `keywords` once; the build projects the cleanly-mappable subset — plus the
 pack's `README.md` — into each distribution route's manifest (the `plugin.json`
 / `marketplace.json` entry), so the catalogue describes each pack richly rather
-than with a single sentence. A marketplace entry's `source` is a `git-subdir`
+than with a single sentence. The Claude-plugin route carries only packs whose
+`[pack.install] allowed-scopes` admits `user`: a plugin's code lands in the
+adopter's global cache, so a repo-only pack gets no `marketplace.json` entry
+and is reached with `agentbundle install` instead. A marketplace entry's `source` is a `git-subdir`
 object (`url`, `path`, and one of `ref`/`sha`) pointing at the pack's directory
 on the published distribution branch, and every entry is schema-validated at
 build time against `marketplace-entry.schema.json`. Extra fields stay in `pack.toml`; the projection
@@ -305,13 +308,30 @@ pip install 'agentbundle[lint]'
 agentbundle catalogue lint --root . --deep
 ```
 
-**Check self-host projection drift** — verifies that adapter-projected files (skills, agents, hooks) match their `.apm/` sources without writing anything:
+**Verify a catalogue before you ship it** — runs the full read-only contract and
+self-host checks in one command:
+
+```bash
+agentbundle catalogue verify --root .
+```
+
+For a self-host-enabled catalogue with `.adapt-discovery.toml`, that includes the
+self-host classifier. It treats generated targets as projected and known
+repository-owned paths as excluded from projection. A genuinely unknown Git-visible
+path remains an informational `unclassified` notice; it does not fail an otherwise
+clean catalogue. Missing, modified, or orphaned projections do fail verification,
+including generated executables under `.agentbundle/bin/` and vendored user libraries
+under `.agentbundle/lib/`. Git filenames are read losslessly, and a failed Git listing
+is reported as a warning rather than mistaken for a fully classified inventory.
+
+To check only self-host projection drift, or to regenerate projected files locally:
 
 ```bash
 agentbundle catalogue self-host --check --root .
+agentbundle catalogue self-host --write --root .
 ```
 
-Exits non-zero if any projected file is out of date. Safe to run in CI as a required check; use `--write` locally to regenerate.
+Both check commands are safe to run in CI. The write command changes projected files.
 
 By default projects for `claude-code` and `codex`. Downstream repos that use a single adapter (e.g. `kiro-ide`) can declare it in `catalogue.toml` — only that adapter is then projected, and its output files participate in the drift check:
 

{agentbundle-0.29.8 → agentbundle-0.31.0}/README-pypi.md

@@ -247,7 +247,10 @@ ignore them there; the separation is structural, not incidental.
 `keywords` once; the build projects the cleanly-mappable subset — plus the
 pack's `README.md` — into each distribution route's manifest (the `plugin.json`
 / `marketplace.json` entry), so the catalogue describes each pack richly rather
-than with a single sentence. A marketplace entry's `source` is a `git-subdir`
+than with a single sentence. The Claude-plugin route carries only packs whose
+`[pack.install] allowed-scopes` admits `user`: a plugin's code lands in the
+adopter's global cache, so a repo-only pack gets no `marketplace.json` entry
+and is reached with `agentbundle install` instead. A marketplace entry's `source` is a `git-subdir`
 object (`url`, `path`, and one of `ref`/`sha`) pointing at the pack's directory
 on the published distribution branch, and every entry is schema-validated at
 build time against `marketplace-entry.schema.json`. Extra fields stay in `pack.toml`; the projection
@@ -283,13 +286,30 @@ pip install 'agentbundle[lint]'
 agentbundle catalogue lint --root . --deep
 ```
 
-**Check self-host projection drift** — verifies that adapter-projected files (skills, agents, hooks) match their `.apm/` sources without writing anything:
+**Verify a catalogue before you ship it** — runs the full read-only contract and
+self-host checks in one command:
+
+```bash
+agentbundle catalogue verify --root .
+```
+
+For a self-host-enabled catalogue with `.adapt-discovery.toml`, that includes the
+self-host classifier. It treats generated targets as projected and known
+repository-owned paths as excluded from projection. A genuinely unknown Git-visible
+path remains an informational `unclassified` notice; it does not fail an otherwise
+clean catalogue. Missing, modified, or orphaned projections do fail verification,
+including generated executables under `.agentbundle/bin/` and vendored user libraries
+under `.agentbundle/lib/`. Git filenames are read losslessly, and a failed Git listing
+is reported as a warning rather than mistaken for a fully classified inventory.
+
+To check only self-host projection drift, or to regenerate projected files locally:
 
 ```bash
 agentbundle catalogue self-host --check --root .
+agentbundle catalogue self-host --write --root .
 ```
 
-Exits non-zero if any projected file is out of date. Safe to run in CI as a required check; use `--write` locally to regenerate.
+Both check commands are safe to run in CI. The write command changes projected files.
 
 By default projects for `claude-code` and `codex`. Downstream repos that use a single adapter (e.g. `kiro-ide`) can declare it in `catalogue.toml` — only that adapter is then projected, and its output files participate in the drift check:
 

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

@@ -46,12 +46,31 @@ model reads to decide whether to **activate** the primitive. Length is load-bear
 there and shortening it degrades activation; per-target caps in
 `contracts/target-vocab.toml` govern it. Do not carry habits from one to the other.
 
-**Shape.** First sentence names the job the adopter accomplishes — verb-first, and
-readable on its own. An optional second sentence carries a compressed capability list
-or the one thing that distinguishes this pack. Then stop.
+**Shape.** Open on the job the adopter accomplishes, in their words. Say what they
+get. Then stop.
 
-> Supervised coding from brief to merged PR. A plan, execute, verify, review loop with
-> spec-driven development, adversarial and security reviewers, and pre-commit gates.
+Beyond that, let the pack decide the shape. Some need one sentence:
+
+> Write the OpenAPI or AsyncAPI contract before anyone writes a handler.
+
+Others earn three:
+
+> Ship it the way production will see it. Deploy to a throwaway environment, run
+> the tests, read the telemetry, and go round again until it holds. Then it stops
+> and asks, because the next step is the one you cannot undo.
+
+**Do not run every description through one mould.** An earlier pass here applied a
+single shape — verb-first sentence, then a comma-list of capabilities — to all
+22 packs. The result measured as 20 of 22 at exactly two sentences, 14 with a
+comma-list second sentence, four opening on the identical "Turn X into Y" frame.
+Every fact was right and the set still read as machine-written, because uniform
+rhythm and symmetrical construction are themselves the tell. Vary sentence count
+and length to match what each pack actually is.
+
+Reach for the concrete. A real thing the user says (`"convert this PDF to
+Markdown"`), a real artifact (`a Google-style design doc`), or a real check
+(`the empty state and the focus ring you forgot`) all beat an abstract capability
+noun.
 
 **Anti-patterns**, each of which has shipped here before:
 

{agentbundle-0.29.8 → agentbundle-0.31.0}/agentbundle/_data/catalogue-scaffold/manifest.json

@@ -1,14 +1,14 @@
 {
   "files": {
-    "guides/_shared/reference/catalogue-authoring-standards.md": "f5e41498139ca335b8a679644eb02d2a35abb2234a77b5b14e7ff90da02722b9",
+    "guides/_shared/reference/catalogue-authoring-standards.md": "ff4bdc203affda0a2f41641c1155b3f4e90aade022e122999a82e7093e94d2ee",
     "guides/_shared/reference/catalogue-ci-contract.md": "fae793ab47989b6dd3c731afcb0b4cda21c7d08bbe7fa40fca6d3abb3d158141",
     "packs/AGENTS.md": "9bfeda4069826e518a4f4fdae45bd40f4393c1c5aaf146149d3eb4aece30be83",
     "packs/README.md": "d2de5f9556f4c8e521103474bde74636e02cc805f9bf5312a3a61a1f3eb45d8f",
     "packs/_example/.apm/skills/example-skill/SKILL.md": "33be8cbf4b2c014a5a63e788b7d0b350ad8061c6c4b2579369a3e984135bf9f1",
     "packs/_example/.apm/skills/example-skill/evals/eval_queries.json": "f41ecda0834a22f3b4823c81ab02e58b0e4beba610e3b40c185579abff9cfeee",
-    "packs/_example/.claude-plugin/plugin.json": "d38c8456640d5e2f9296361f7e3e675e368ddd3eb22a6245267560f460155f41",
+    "packs/_example/.claude-plugin/plugin.json": "7f94084a56260eed225ec47ac82042fe9029c594557cca760a459885d03ccc26",
     "packs/_example/README.md": "ef130c9c1f97a75a07cc59fc55fc5b3bf71846dd2f06c3cddf5a1154023b6ef6",
-    "packs/_example/pack.toml": "94e2c7fd25d4d115858728c7ecb8f739adfd0f594b29596c106daba0791a4b94",
+    "packs/_example/pack.toml": "f19a0be9fca99a6a0e3ce2d5cd188bf98000f0a4f186954fb42a0c99c6859701",
     "profiles/AGENTS.md": "8950438d9e0f57c13613104c88c90b598b53196c91bfdced6d63e4e01b5e9254",
     "profiles/README.md": "a0b0268edc57fc575f7fea08f3363ba7da9f6e67dc4a0a6f8bd38c9668c97922",
     "profiles/_example/README.md": "164494df049ddce3e57cb44ed604cb3d39be0a6ec2072e609ea3fa4bbfc74c72",

{agentbundle-0.29.8 → agentbundle-0.31.0}/agentbundle/_data/catalogue-scaffold/packs/_example/pack.toml

@@ -1,7 +1,7 @@
 [pack]
 name            = "example-pack"
 version         = "0.1.0"
-description     = "A minimal example pack demonstrating the standard authoring layout."
+description     = "The skeleton to copy when you start a new pack."
 display_name    = "Example Pack"
 categories      = ["productivity"]
 keywords        = ["example", "template"]

{agentbundle-0.29.8 → agentbundle-0.31.0}/agentbundle/_data/install-marker.py

@@ -1,9 +1,13 @@
 """Canonical stdlib-only install-marker writer for the Claude-plugins and APM install routes.
 
 This script is invoked by a ``SessionStart`` hook derived by ``agentbundle build``
-into every pack's projected output:
-  - ``dist/claude-plugins/<pack>/.claude-plugin/plugin.json``  — claude-plugins route
-  - ``dist/apm/<pack>/.apm/hooks/install-marker.json``         — APM route
+into each pack's projected output:
+  - ``dist/claude-plugins/<pack>/.claude-plugin/plugin.json``  — claude-plugins
+    route, for user-capable packs only (a plugin's code lands in the adopter's
+    global cache, so a pack whose ``allowed-scopes`` omits ``user`` is not
+    projected onto this route at all)
+  - ``dist/apm/<pack>/.apm/hooks/install-marker.json``         — APM route,
+    every pack
 
 It detects first-install-or-update and writes a ``[[packs-installed]]`` entry
 to the scope-correct ``.adapt-install-marker.toml`` file so the existing core

{agentbundle-0.29.8 → agentbundle-0.31.0}/agentbundle/build/adapter_root_bins.py

@@ -36,11 +36,19 @@ from __future__ import annotations
 
 import contextlib
 import os
-import shutil
+import stat
 from dataclasses import dataclass
 from pathlib import Path
 
 from . import shared_libs
+from .projection_io import (
+    ProjectionTypeError,
+    copy_file_atomic_no_follow,
+    ensure_directory_no_follow,
+    open_directory_no_follow,
+    read_regular_file_no_follow,
+    render_diagnostic_path,
+)
 
 # Pin the source path so a downstream consumer that wants to enumerate
 # sources doesn't hardcode the literal repeatedly.
@@ -72,6 +80,11 @@ SHIM_COMPANION_BASENAME = "credentials_shim.py"
 SHIM_IMPORT_GREP = b"from .credentials_shim import"
 
 
+def _display(path: Path, base: Path) -> str:
+    """Render one path relative to its diagnostic base on one line."""
+    return render_diagnostic_path(path.relative_to(base))
+
+
 @dataclass(frozen=True)
 class AdapterRootBinProjection:
     """One concrete projection: copy ``source`` to ``target``."""
@@ -100,9 +113,12 @@ def collect_sources(packs_dir: Path) -> dict[str, Path]:
             continue
         for src in sorted(bins.glob("*.py")):
             if src.name in sources:
+                basename = render_diagnostic_path(Path(src.name))
+                first_source = _display(sources[src.name], packs_dir.parent)
+                second_source = _display(src, packs_dir.parent)
                 raise ValueError(
-                    f"adapter-root-bins collision: '{src.name}' shipped by both "
-                    f"{sources[src.name]} and {src}"
+                    f"adapter-root-bins collision: {basename} shipped by both "
+                    f"{first_source} and {second_source}"
                 )
             sources[src.name] = src
     return sources
@@ -155,9 +171,12 @@ def _assert_shim_companion_present(packs_dir: Path) -> None:
             if SHIM_IMPORT_GREP in body:
                 offenders.append(src.name)
         if offenders:
-            offender_list = ", ".join(offenders)
+            offender_list = ", ".join(
+                render_diagnostic_path(Path(SOURCE_SUBDIR) / offender)
+                for offender in offenders
+            )
             raise ValueError(
-                f"adapter-root-bins/{{{offender_list}}} imports "
+                f"{offender_list} imports "
                 f".credentials_shim but .apm/shared-libs/credentials_shim.py "
                 f"is missing in pack {pack.name!r} — the importing module's "
                 f"Tier-2 dispatch would degrade silently on macOS/Windows"
@@ -286,6 +305,27 @@ def _is_companion_projection(proj: AdapterRootBinProjection) -> bool:
     return proj.source.parent.name == shared_libs_leaf
 
 
+def _target_python_names(target_dir: Path, target_fd: int | None) -> list[str]:
+    """List non-directory ``*.py`` entries through an already-held directory."""
+    if target_fd is None:
+        return [
+            path.name for path in target_dir.glob("*.py") if not path.is_dir()
+        ]
+    names: list[str] = []
+    for name in os.listdir(target_fd):  # noqa: PTH208 — directory descriptor
+        if not name.endswith(".py"):
+            continue
+        try:
+            entry_stat = os.stat(
+                name, dir_fd=target_fd, follow_symlinks=False
+            )
+        except FileNotFoundError:
+            continue
+        if not stat.S_ISDIR(entry_stat.st_mode):
+            names.append(name)
+    return names
+
+
 def apply_projection(working_tree: Path, packs_dir: Path) -> None:
     """Write every projection target and remove orphans.
 
@@ -307,20 +347,28 @@ def apply_projection(working_tree: Path, packs_dir: Path) -> None:
     _assert_shim_companion_present(packs_dir)
     projections = compute_projections(working_tree, packs_dir)
     expected_targets = {p.target for p in projections}
+    ensure_directory_no_follow(working_tree, TARGET_SUBDIR)
     for proj in projections:
-        proj.target.parent.mkdir(parents=True, exist_ok=True)
-        shutil.copyfile(proj.source, proj.target)
-        if os.name == "posix":
-            with contextlib.suppress(OSError):
-                proj.target.chmod(EXECUTABLE_MODE)
+        copy_file_atomic_no_follow(
+            proj.source,
+            proj.target,
+            base=working_tree,
+            mode=EXECUTABLE_MODE,
+        )
     # Orphan removal: any *.py file under <working_tree>/.agentbundle/bin/
     # not claimed by an expected target.
     target_dir = working_tree / TARGET_SUBDIR
-    if target_dir.is_dir():
-        for existing in sorted(target_dir.glob("*.py")):
-            if existing not in expected_targets:
-                with contextlib.suppress(FileNotFoundError):  # pragma: no cover — race-only
+    with open_directory_no_follow(working_tree, TARGET_SUBDIR) as target_fd:
+        for name in sorted(_target_python_names(target_dir, target_fd)):
+            existing = target_dir / name
+            if existing in expected_targets:
+                continue
+            if target_fd is None:
+                with contextlib.suppress(FileNotFoundError):  # pragma: no cover
                     existing.unlink()
+            else:
+                with contextlib.suppress(FileNotFoundError):  # pragma: no cover
+                    os.unlink(name, dir_fd=target_fd)
 
 
 def check_drift(working_tree: Path, packs_dir: Path) -> list[str]:
@@ -348,6 +396,33 @@ def check_drift(working_tree: Path, packs_dir: Path) -> list[str]:
     target_dir = working_tree / TARGET_SUBDIR
     expected_targets: set[Path] = set()
 
+    current = working_tree
+    for part in TARGET_SUBDIR.parts:
+        current /= part
+        try:
+            current_stat = current.lstat()
+        except FileNotFoundError:
+            break
+        except OSError as exc:
+            drifts.append(
+                f"[adapter-root-bins] unreadable: "
+                f"{_display(current, working_tree)}: {exc}"
+            )
+            return drifts
+        if not stat.S_ISDIR(current_stat.st_mode):
+            kind = (
+                "a symlink"
+                if stat.S_ISLNK(current_stat.st_mode)
+                else "not a directory"
+            )
+            drifts.append(
+                f"[adapter-root-bins] type mismatch: "
+                f"{_display(current, working_tree)} is {kind}; "
+                f"expected a directory inside the working tree; "
+                f"run: make build-self FORCE=1"
+            )
+            return drifts
+
     for proj in compute_projections(working_tree, packs_dir):
         expected_targets.add(proj.target)
         prefix = (
@@ -360,34 +435,75 @@ def check_drift(working_tree: Path, packs_dir: Path) -> list[str]:
         except OSError as exc:  # pragma: no cover — defensive
             drifts.append(f"{prefix} source unreadable: {exc}")
             continue
-        if not proj.target.exists():
+        try:
+            target_bytes, target_stat = read_regular_file_no_follow(
+                proj.target,
+                base=working_tree,
+            )
+        except FileNotFoundError:
             drifts.append(
                 f"{prefix} missing: "
-                f"{proj.target.relative_to(working_tree).as_posix()} "
+                f"{_display(proj.target, working_tree)} "
                 f"(source: "
-                f"{proj.source.relative_to(packs_dir.parent).as_posix()}); "
+                f"{_display(proj.source, packs_dir.parent)}); "
                 f"run: make build-self FORCE=1"
             )
             continue
-        if proj.target.read_bytes() != source_bytes:
+        except ProjectionTypeError as exc:
+            drifts.append(
+                f"{prefix} type mismatch: "
+                f"{_display(proj.target, working_tree)} {exc}; "
+                f"expected a regular projected file; run: make build-self FORCE=1"
+            )
+            continue
+        except OSError as exc:
+            drifts.append(
+                f"{prefix} unreadable: "
+                f"{_display(proj.target, working_tree)}: {exc}"
+            )
+            continue
+        if (
+            os.name == "posix"
+            and stat.S_IMODE(target_stat.st_mode) != EXECUTABLE_MODE
+        ):
+            drifts.append(
+                f"{prefix} mode drift: "
+                f"{_display(proj.target, working_tree)} has "
+                f"{oct(stat.S_IMODE(target_stat.st_mode))}, expected "
+                f"{oct(EXECUTABLE_MODE)}; run: make build-self FORCE=1"
+            )
+        if target_bytes != source_bytes:
             drifts.append(
                 f"{prefix} modified: "
-                f"{proj.target.relative_to(working_tree).as_posix()} "
+                f"{_display(proj.target, working_tree)} "
                 f"diverges from "
-                f"{proj.source.relative_to(packs_dir.parent).as_posix()}; "
+                f"{_display(proj.source, packs_dir.parent)}; "
                 f"run: make build-self FORCE=1"
             )
 
     # Orphan check.
-    if target_dir.is_dir():
-        for existing in sorted(target_dir.glob("*.py")):
-            if existing not in expected_targets:
-                drifts.append(
-                    f"[adapter-root-bins] orphaned: "
-                    f"{existing.relative_to(working_tree).as_posix()} "
-                    f"present but no pack ships "
-                    f"adapter-root-bins/{existing.name}; "
-                    f"run: make build-self FORCE=1"
-                )
+    try:
+        with open_directory_no_follow(working_tree, TARGET_SUBDIR) as target_fd:
+            target_names = _target_python_names(target_dir, target_fd)
+    except FileNotFoundError:
+        target_names = []
+    except OSError as exc:
+        drifts.append(
+            f"[adapter-root-bins] unreadable: "
+            f"{render_diagnostic_path(TARGET_SUBDIR)}: {exc}; "
+            f"run: make build-self FORCE=1"
+        )
+        target_names = []
+    for name in sorted(target_names):
+        existing = target_dir / name
+        if existing not in expected_targets:
+            source_hint = render_diagnostic_path(Path("adapter-root-bins") / name)
+            drifts.append(
+                f"[adapter-root-bins] orphaned: "
+                f"{render_diagnostic_path(existing.relative_to(working_tree))} "
+                f"present but no pack ships "
+                f"{source_hint}; "
+                f"run: make build-self FORCE=1"
+            )
 
     return drifts