agentbundle 0.10.2__tar.gz → 0.11.0__tar.gz

{agentbundle-0.10.2 → agentbundle-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentbundle
-Version: 0.10.2
+Version: 0.11.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
@@ -55,6 +55,10 @@ The install auto-detects your agent (`--adapter` overrides). Multi-IDE? Install
 agentbundle list-packs
 agentbundle list-profiles
 
+# See what a single pack contains — skills and agents, derived live from its tree
+agentbundle show core
+agentbundle show core --format json          # stable object for scripts/agents
+
 # See what YOU have installed — pack, adapter, scope, version, and whether
 # an upgrade is available (both scopes by default)
 agentbundle list-installed
@@ -78,6 +82,8 @@ agentbundle uninstall --pack core --yes
 
 **`list-installed`** reads your state files (not the catalogue) and reports every installed `(pack, adapter)` at each scope with its version and an `up-to-date` / `upgrade-available` / `unknown` status; it degrades to `unknown` (never an error) when the catalogue can't be resolved, and `--no-check` skips the check entirely.
 
+**`show <pack>`** answers "what skills and agents does this pack contain?" by walking the pack's source tree live on each call — so the answer can't drift, and nothing is persisted. `--format json` emits a stable object (`name`, `version`, `description`, `skills`, `agents`, `source`) for scripts and agents. When the catalogue can't be resolved, an *installed* pack still reports its inventory from your state files (marked `source: installed-state`); a not-installed pack errors.
+
 A **profile** is a catalogue-curated, single-scope set of packs you install in one command — it declares its own scope, so `--scope` doesn't apply. **Upgrade takes no version** — the target is whatever the catalogue you point at declares; to pin a past version, point the catalogue at that git ref. Install a pack that's **already there** and `agentbundle` offers to `upgrade` it instead (`--yes` runs it straight away).
 
 **Mutating commands ask first.** `uninstall`, the `--force` cleanup, and the upgrade offer all preview what they'll do and confirm before touching anything; `--dry-run` previews without writing, and `--yes` skips the prompt for non-interactive / CI use (where, without it, they refuse rather than hang).

{agentbundle-0.10.2 → agentbundle-0.11.0}/README.md

@@ -37,6 +37,10 @@ The install auto-detects your agent (`--adapter` overrides). Multi-IDE? Install
 agentbundle list-packs
 agentbundle list-profiles
 
+# See what a single pack contains — skills and agents, derived live from its tree
+agentbundle show core
+agentbundle show core --format json          # stable object for scripts/agents
+
 # See what YOU have installed — pack, adapter, scope, version, and whether
 # an upgrade is available (both scopes by default)
 agentbundle list-installed
@@ -60,6 +64,8 @@ agentbundle uninstall --pack core --yes
 
 **`list-installed`** reads your state files (not the catalogue) and reports every installed `(pack, adapter)` at each scope with its version and an `up-to-date` / `upgrade-available` / `unknown` status; it degrades to `unknown` (never an error) when the catalogue can't be resolved, and `--no-check` skips the check entirely.
 
+**`show <pack>`** answers "what skills and agents does this pack contain?" by walking the pack's source tree live on each call — so the answer can't drift, and nothing is persisted. `--format json` emits a stable object (`name`, `version`, `description`, `skills`, `agents`, `source`) for scripts and agents. When the catalogue can't be resolved, an *installed* pack still reports its inventory from your state files (marked `source: installed-state`); a not-installed pack errors.
+
 A **profile** is a catalogue-curated, single-scope set of packs you install in one command — it declares its own scope, so `--scope` doesn't apply. **Upgrade takes no version** — the target is whatever the catalogue you point at declares; to pin a past version, point the catalogue at that git ref. Install a pack that's **already there** and `agentbundle` offers to `upgrade` it instead (`--yes` runs it straight away).
 
 **Mutating commands ask first.** `uninstall`, the `--force` cleanup, and the upgrade offer all preview what they'll do and confirm before touching anything; `--dry-run` previews without writing, and `--yes` skips the prompt for non-interactive / CI use (where, without it, they refuse rather than hang).

{agentbundle-0.10.2 → agentbundle-0.11.0}/agentbundle/build/lint_packs.py

@@ -35,6 +35,7 @@ import tomllib
 from typing import NamedTuple, Pattern
 from pathlib import Path
 
+from agentbundle.pack_inventory import apm_entries
 from agentbundle.safety import PathJailError, assert_portable_name
 
 # Subtrees in a pack that ship to adopters. `seeds/` is the
@@ -278,10 +279,10 @@ def _extract_frontmatter_fields(
 
 def _check_skill_metadata(pack_dir: Path, constraints: Constraints) -> list[str]:
     findings: list[str] = []
-    skills_dir = pack_dir / ".apm" / "skills"
-    if not skills_dir.is_dir():
-        return findings
-    for entry in sorted(skills_dir.iterdir()):
+    # Enumeration lives in one place (RFC-0060 AC9): the shared raw walk.
+    # Lint keeps its own per-entry filtering (it lints SKILL.md-less dirs too,
+    # which `show` excludes) — the walk is shared, the filter is not.
+    for entry in apm_entries(pack_dir, "skills"):
         if not entry.is_dir():
             continue
         dir_name = entry.name
@@ -331,10 +332,8 @@ def _check_skill_metadata(pack_dir: Path, constraints: Constraints) -> list[str]
 
 def _check_agent_metadata(pack_dir: Path, constraints: Constraints) -> list[str]:
     findings: list[str] = []
-    agents_dir = pack_dir / ".apm" / "agents"
-    if not agents_dir.is_dir():
-        return findings
-    for entry in sorted(agents_dir.iterdir()):
+    # Shared raw walk (RFC-0060 AC9); lint keeps its own .md-file filter.
+    for entry in apm_entries(pack_dir, "agents"):
         if not entry.is_file() or entry.suffix != ".md":
             continue
         stem = entry.stem

{agentbundle-0.10.2 → agentbundle-0.11.0}/agentbundle/build/tests/test_shipped_packs_v08_declarations.py

@@ -12,6 +12,8 @@ The `research` pack (shipped later by the `research-pack` spec) also
 declared v0.8 at birth. A future pack landing at v0.8 should add itself to
 ``V08_PACKS`` so this test surfaces the new declaration.
 
+  - ``catalogue-curation`` (RFC-0059) landed at v0.8 and is registered here.
+
 Packs in-tree NOT at v0.8:
 
   - ``credential-brokers``: still at v0.7 (RFC-0013 shipped on v0.7 and
@@ -37,6 +39,7 @@ PACKS_DIR = REPO_ROOT / "packs"
 
 V08_PACKS = (
     "atlassian",
+    "catalogue-curation",
     "contracts",
     "converters",
     "figma",

{agentbundle-0.10.2 → agentbundle-0.11.0}/agentbundle/cli.py

@@ -274,6 +274,31 @@ def _build_parser() -> argparse.ArgumentParser:
     )
     sp.set_defaults(func=_lazy("list_installed"))
 
+    # --- show --- (catalogue query; walks a pack's .apm/ tree live)
+    sp = subparsers.add_parser(
+        "show",
+        help=(
+            "Show a pack's skills and agents, derived live from its .apm/ tree. "
+            "Falls back to the install state when the catalogue is unresolvable."
+        ),
+    )
+    sp.add_argument("pack", help="Pack name to inspect (e.g. core).")
+    sp.add_argument(
+        "--format",
+        choices=("table", "json"),
+        default="table",
+        help="Output format (default: table).",
+    )
+    sp.add_argument(
+        "--root",
+        default=".",
+        help=(
+            "Repo root used to locate the repo-scope install-state file for the "
+            "catalogue-unresolvable fallback. Default: current directory."
+        ),
+    )
+    sp.set_defaults(func=_lazy("show"))
+
     # --- scaffold --- (no --scope; always repo-targeted)
     sp = subparsers.add_parser(
         "scaffold",

agentbundle-0.11.0/agentbundle/commands/show.py

@@ -0,0 +1,272 @@
+"""``agentbundle show <pack>`` subcommand.
+
+Answers "what skills and agents does pack X contain?" by walking the pack's
+``.apm/`` source tree **live** on each call (ADR-0049 / RFC-0060): nothing is
+persisted and no manifest is touched, so the answer cannot drift from what the
+pack actually ships.
+
+Two honest, state-differentiated sources:
+
+  - **Primary — catalogue.** Resolve the pack in the active catalogue, walk
+    ``.apm/skills/`` and ``.apm/agents/``, and print the pack's ``pack.toml``
+    metadata alongside its full, sorted skill + agent inventory
+    (``source: catalogue``).
+  - **Degrade — install state.** When the catalogue is unresolvable, an
+    *installed* pack still yields its inventory from the install-state file —
+    the union of skill/agent names across every adapter row in both the user
+    and repo scope (``source: installed-state``) — while a *not-installed* pack
+    fails with a one-line error, because there is no source to read.
+
+``--format json`` emits the same as a single stable object for programmatic
+consumers. The inventory is never filtered (``show`` reports what *exists*, not
+what a user can invoke), and it is the full, untagged set — every skill under
+``.apm/skills/``, not the ``[pack.evals].skills`` subset.
+
+Exit codes:
+  0  — success (catalogue path or installed-state fallback).
+  1  — unknown pack, or unresolvable-catalogue-and-not-installed (one-line
+       stderr, empty stdout — including under ``--format json``).
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import argparse
+
+    from agentbundle.config import State
+
+
+def run(args: "argparse.Namespace") -> int:
+    """Entry point for ``agentbundle show``."""
+    from agentbundle.catalogue import CatalogueError, resolve_catalogue
+    from agentbundle.commands._common import resolve_catalogue_uri
+    from agentbundle.pack_inventory import agent_names, skill_names
+
+    pack_name: str = args.pack
+    fmt: str = getattr(args, "format", "table")
+
+    # ── Resolve the catalogue (authoritative primary source) ──────────────────
+    try:
+        catalogue_dir = resolve_catalogue(resolve_catalogue_uri(args))
+    except CatalogueError:
+        # Honest, state-differentiated degrade (ADR-0049).
+        return _degrade(args, pack_name, fmt)
+
+    # ── Name-match the pack in the catalogue ──────────────────────────────────
+    match = _find_pack_dir(catalogue_dir, pack_name)
+    if match is None:
+        print(f"show: pack {pack_name!r} not found in catalogue", file=sys.stderr)
+        return 1
+
+    pack_dir, toml = match
+    pack = toml.get("pack", {})
+    _emit(
+        fmt,
+        name=pack.get("name") or pack_dir.name,
+        # Pass metadata through as-is: an *absent* key is null; a present
+        # (even empty) value is not coerced, so "declared empty" and "absent"
+        # stay distinguishable on the authoritative catalogue path.
+        version=pack.get("version"),
+        description=pack.get("description"),
+        skills=skill_names(pack_dir),
+        agents=agent_names(pack_dir),
+        source="catalogue",
+    )
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# Primary path — catalogue lookup
+# ---------------------------------------------------------------------------
+
+
+def _find_pack_dir(catalogue_dir: Path, pack_name: str) -> tuple[Path, dict] | None:
+    """Return ``(pack_dir, parsed pack.toml)`` for *pack_name*, or None.
+
+    Reuses ``list-packs``' ``_discover_pack_dirs`` so the accepted catalogue
+    layouts stay identical, then matches on the pack's declared ``[pack].name``
+    (falling back to the directory name) — the step the AC5 "unknown pack" path
+    depends on.
+    """
+    from agentbundle.commands.list_packs import _discover_pack_dirs
+    from agentbundle.config import ConfigError, load_pack_toml
+
+    for pack_dir in _discover_pack_dirs(catalogue_dir):
+        try:
+            toml = load_pack_toml(pack_dir / "pack.toml")
+        except ConfigError:
+            continue
+        # A declared ``[pack].name`` is authoritative (list-packs keys display
+        # on it); fall back to the directory name only when it is absent, so a
+        # coincidental dir-name match never shadows a pack declaring a different
+        # name.
+        name = toml.get("pack", {}).get("name") or pack_dir.name
+        if name == pack_name:
+            return pack_dir, toml
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Degrade path — install-state fallback
+# ---------------------------------------------------------------------------
+
+
+def _degrade(args: "argparse.Namespace", pack_name: str, fmt: str) -> int:
+    """Recover the inventory from the install state when the catalogue is gone.
+
+    Reads both the user and repo scope (mirroring ``list-installed``). An
+    *installed* pack yields the union of skill/agent names across every adapter
+    row in both scopes, deduped + sorted (``source: installed-state``, metadata
+    null); a *not-installed* pack errors and exits non-zero.
+    """
+    states = _load_states(args)
+    if not any(state.has_pack(pack_name) for state in states):
+        print(
+            f"show: catalogue unavailable and pack {pack_name!r} is not installed",
+            file=sys.stderr,
+        )
+        return 1
+
+    skills: set[str] = set()
+    agents: set[str] = set()
+    for state in states:
+        for pack_state in state.rows_for_pack(pack_name).values():
+            for relpath in pack_state.files:
+                skill = _skill_from_relpath(relpath)
+                if skill:
+                    skills.add(skill)
+                agent = _agent_from_relpath(relpath)
+                if agent:
+                    agents.add(agent)
+
+    _emit(
+        fmt,
+        name=pack_name,  # the argument passed to `show`; state has no pack name
+        version=None,  # inventory-only fallback — never fabricated from state
+        description=None,
+        skills=sorted(skills),
+        agents=sorted(agents),
+        source="installed-state",
+    )
+    return 0
+
+
+def _load_states(args: "argparse.Namespace") -> list["State"]:
+    """Load the user- and repo-scope install-state files, read-only.
+
+    Mirrors ``list-installed``'s two-scope gather: user
+    (``~/.agentbundle/state.toml`` via ``scope.resolve_user_root``) and repo
+    (``<--root>/.agentbundle-state.toml``). An unresolvable user home is skipped;
+    an absent state file loads as an empty ``State``; a legacy/incompatible file
+    (``StateFileLegacy`` — a ``ConfigError``) is skipped, not fatal.
+    """
+    from agentbundle import scope as scope_mod
+    from agentbundle.config import ConfigError, load_state
+
+    candidates: list[tuple[str, Path]] = []
+    try:
+        user_root = scope_mod.resolve_user_root()
+    except scope_mod.UserScopeUnresolvable:
+        pass
+    else:
+        candidates.append(("user", user_root / ".agentbundle" / "state.toml"))
+    repo_root = Path(getattr(args, "root", ".") or ".").resolve()
+    candidates.append(("repo", repo_root / ".agentbundle-state.toml"))
+
+    states: list["State"] = []
+    for scope_name, path in candidates:
+        try:
+            states.append(load_state(path))
+        except ConfigError as exc:
+            # Mirror `list-installed`: a legacy/incompatible state file is
+            # warned-and-skipped, not silently dropped — otherwise an installed
+            # pack whose only row lives there would masquerade as not-installed
+            # on this degrade path with no hint why.
+            print(f"show: skipping {scope_name} scope: {exc}", file=sys.stderr)
+    return states
+
+
+def _skill_from_relpath(relpath: str) -> str | None:
+    """Skill name = the path segment immediately after a ``skills/`` component.
+
+    Layout-agnostic across ``.claude/skills/``, the shared ``.agents/skills/``
+    (codex/copilot/cursor/gemini), and ``.kiro/skills/``. Any projected file
+    under ``skills/<name>/`` maps to ``<name>``; the caller dedupes.
+    """
+    parts = Path(relpath).parts
+    for i, part in enumerate(parts):
+        if part == "skills" and i + 1 < len(parts):
+            return parts[i + 1]
+    return None
+
+
+def _agent_from_relpath(relpath: str) -> str | None:
+    """Agent name = the filename directly under an ``agents/`` component, with
+    its extension stripped by an **extension-agnostic** rule.
+
+    Strip a trailing ``.agent.md`` (copilot's double-suffix) if present, else
+    ``Path.stem`` (the single final extension). Recovers ``<n>`` uniformly from
+    ``.claude/agents/<n>.md``, ``.codex/agents/<n>.toml``,
+    ``.kiro/agents/<n>.json``, and ``.github/agents/<n>.agent.md`` — so
+    co-installed adapter rows dedupe to one entry.
+    """
+    path = Path(relpath)
+    parts = path.parts
+    # A top-level ``agents/`` component only — never an ``agents/`` dir nested
+    # inside a skill's payload (``.../skills/<n>/agents/helper.md``), which would
+    # surface a phantom agent.
+    if len(parts) >= 2 and parts[-2] == "agents" and "skills" not in parts:
+        name = path.name
+        if name.endswith(".agent.md"):
+            return name[: -len(".agent.md")]
+        return path.stem
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Rendering
+# ---------------------------------------------------------------------------
+
+
+def _emit(
+    fmt: str,
+    *,
+    name: str,
+    version: str | None,
+    description: str | None,
+    skills: list[str],
+    agents: list[str],
+    source: str,
+) -> None:
+    """Render the inventory as a table block or a single JSON object."""
+    if fmt == "json":
+        import json
+
+        obj = {
+            "name": name,
+            "version": version,
+            "description": description,
+            "skills": skills,
+            "agents": agents,
+            "source": source,
+        }
+        print(json.dumps(obj))
+        return
+
+    from agentbundle.commands._common import render_table
+
+    rows: list[list[str]] = [["name", name]]
+    # Fallback (installed-state) omits version/description — the state has neither.
+    if version is not None:
+        rows.append(["version", version])
+    if description is not None:
+        rows.append(["description", description])
+    rows.append(["skills", ", ".join(skills) if skills else "-"])
+    rows.append(["agents", ", ".join(agents) if agents else "-"])
+    render_table(["FIELD", "VALUE"], rows, wrap_col=1)
+    if source != "catalogue":
+        print(f"source: {source} (catalogue unavailable)")

agentbundle-0.11.0/agentbundle/pack_inventory.py

@@ -0,0 +1,61 @@
+"""Live pack-inventory walk over a pack's ``.apm/`` source tree.
+
+A pack's authoritative contents live under ``<pack>/.apm/``:
+
+  - skills at ``.apm/skills/<name>/SKILL.md``  → ``<name>``
+  - agents at ``.apm/agents/<name>.md``        → ``<name>``
+
+This module is the single enumeration path for that tree (ADR-0049 /
+RFC-0060 AC9): both ``agentbundle show`` and ``build/lint_packs`` walk it
+through :func:`apm_entries`, so the directory traversal lives in one place.
+The primitive returns **raw sorted entries** — each caller applies its own
+filter (``show`` counts only ``SKILL.md``-bearing skill dirs and ``.md``
+agent files; ``lint_packs`` lints every entry, ``SKILL.md`` or not).
+
+Pure stdlib ``pathlib`` — no I/O beyond reading the directory tree, and
+nothing is persisted (ADR-0049: derive live, persist nothing).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def apm_entries(pack_dir: Path, subdir: str) -> list[Path]:
+    """Return the sorted direct children of ``<pack_dir>/.apm/<subdir>``.
+
+    Returns ``[]`` when the directory is absent (AC4) — a pack that ships no
+    skills, or no agents, is not an error. Sorted ascending by path so every
+    consumer sees a deterministic order. This is the shared raw walk (AC9);
+    callers filter the entries themselves.
+    """
+    d = pack_dir / ".apm" / subdir
+    if not d.is_dir():
+        return []
+    return sorted(d.iterdir())
+
+
+def skill_names(pack_dir: Path) -> list[str]:
+    """Sorted names of ``.apm/skills/<name>/`` dirs that contain a ``SKILL.md``.
+
+    A skills subdirectory without a ``SKILL.md`` is not a skill (AC2); a
+    missing ``.apm/skills/`` yields ``[]`` (AC4).
+    """
+    return [
+        entry.name
+        for entry in apm_entries(pack_dir, "skills")
+        if entry.is_dir() and (entry / "SKILL.md").is_file()
+    ]
+
+
+def agent_names(pack_dir: Path) -> list[str]:
+    """Sorted stems of ``.apm/agents/*.md`` files.
+
+    Non-``.md`` entries and subdirectories are ignored (AC2); a missing
+    ``.apm/agents/`` yields ``[]`` (AC4).
+    """
+    return [
+        entry.stem
+        for entry in apm_entries(pack_dir, "agents")
+        if entry.is_file() and entry.suffix == ".md"
+    ]

{agentbundle-0.10.2 → agentbundle-0.11.0}/agentbundle/version.py

@@ -14,7 +14,7 @@ import tomllib
 from importlib.resources import files
 from pathlib import Path
 
-CLI_VERSION = "0.10.2"
+CLI_VERSION = "0.11.0"
 
 _HERE = Path(__file__).resolve().parent
 

{agentbundle-0.10.2 → agentbundle-0.11.0}/agentbundle.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentbundle
-Version: 0.10.2
+Version: 0.11.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
@@ -55,6 +55,10 @@ The install auto-detects your agent (`--adapter` overrides). Multi-IDE? Install
 agentbundle list-packs
 agentbundle list-profiles
 
+# See what a single pack contains — skills and agents, derived live from its tree
+agentbundle show core
+agentbundle show core --format json          # stable object for scripts/agents
+
 # See what YOU have installed — pack, adapter, scope, version, and whether
 # an upgrade is available (both scopes by default)
 agentbundle list-installed
@@ -78,6 +82,8 @@ agentbundle uninstall --pack core --yes
 
 **`list-installed`** reads your state files (not the catalogue) and reports every installed `(pack, adapter)` at each scope with its version and an `up-to-date` / `upgrade-available` / `unknown` status; it degrades to `unknown` (never an error) when the catalogue can't be resolved, and `--no-check` skips the check entirely.
 
+**`show <pack>`** answers "what skills and agents does this pack contain?" by walking the pack's source tree live on each call — so the answer can't drift, and nothing is persisted. `--format json` emits a stable object (`name`, `version`, `description`, `skills`, `agents`, `source`) for scripts and agents. When the catalogue can't be resolved, an *installed* pack still reports its inventory from your state files (marked `source: installed-state`); a not-installed pack errors.
+
 A **profile** is a catalogue-curated, single-scope set of packs you install in one command — it declares its own scope, so `--scope` doesn't apply. **Upgrade takes no version** — the target is whatever the catalogue you point at declares; to pin a past version, point the catalogue at that git ref. Install a pack that's **already there** and `agentbundle` offers to `upgrade` it instead (`--yes` runs it straight away).
 
 **Mutating commands ask first.** `uninstall`, the `--force` cleanup, and the upgrade offer all preview what they'll do and confirm before touching anything; `--dry-run` previews without writing, and `--yes` skips the prompt for non-interactive / CI use (where, without it, they refuse rather than hang).

{agentbundle-0.10.2 → agentbundle-0.11.0}/agentbundle.egg-info/SOURCES.txt

@@ -6,6 +6,7 @@ agentbundle/catalogue.py
 agentbundle/categories.py
 agentbundle/cli.py
 agentbundle/config.py
+agentbundle/pack_inventory.py
 agentbundle/render.py
 agentbundle/safety.py
 agentbundle/scope.py
@@ -119,6 +120,7 @@ agentbundle/commands/profile.py
 agentbundle/commands/reconcile.py
 agentbundle/commands/render.py
 agentbundle/commands/scaffold.py
+agentbundle/commands/show.py
 agentbundle/commands/uninstall.py
 agentbundle/commands/upgrade.py
 agentbundle/commands/validate.py

{agentbundle-0.10.2 → agentbundle-0.11.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agentbundle"
-version = "0.10.2"
+version = "0.11.0"
 description = "npm for your coding agent. Install packs of skills, subagents, and hooks into any repo, for every major agent."
 requires-python = ">=3.11"
 dependencies = []