agentbundle 0.2.0__py3-none-any.whl

agentbundle/commands/list_packs.py

@@ -0,0 +1,170 @@
+"""``agentbundle list-packs`` subcommand.
+
+Resolves a catalogue URI, enumerates every ``packs/*/pack.toml``, and prints
+a stable table of name, version, description, and dependencies to stdout.
+
+Catalogue layout accepted:
+  - ``<root>/packs/<name>/pack.toml``  — standard catalogue layout.
+  - ``<root>/<name>/pack.toml``        — root *is* the packs directory
+    (every subdir with a pack.toml counts).
+
+Exit codes:
+  0  — success.
+  1  — catalogue resolution error (one-line stderr from CatalogueError).
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import argparse
+
+
+def run(args: "argparse.Namespace") -> int:
+    """Entry point for ``agentbundle list-packs``.
+
+    Args:
+        args.catalogue — catalogue URI (local path or git+https://...).
+
+    Returns 0 on success, 1 on catalogue resolution failure.
+    """
+    from agentbundle.catalogue import CatalogueError, resolve_catalogue
+    from agentbundle.config import ConfigError, load_pack_toml
+
+    catalogue_uri: str = args.catalogue
+
+    # ── Resolve catalogue URI ──────────────────────────────────────────────────
+    try:
+        catalogue_dir = resolve_catalogue(catalogue_uri)
+    except CatalogueError as exc:
+        print(f"list-packs: {exc}", file=sys.stderr)
+        return 1
+
+    # ── Discover packs ────────────────────────────────────────────────────────
+    pack_dirs = _discover_pack_dirs(catalogue_dir)
+    if not pack_dirs:
+        # Nothing to show is not an error; just print the (empty) header.
+        _print_table([])
+        return 0
+
+    # ── Parse each pack.toml ──────────────────────────────────────────────────
+    from agentbundle.commands._common import check_spec_version_gate
+
+    rows: list[dict] = []
+    for pack_dir in pack_dirs:
+        try:
+            toml = load_pack_toml(pack_dir / "pack.toml")
+        except ConfigError as exc:
+            print(f"list-packs: skipping {pack_dir.name}: {exc}", file=sys.stderr)
+            continue
+        # Spec-version gate per pack; refuse cataloguing an incompatible
+        # pack with a uniform message rather than silently listing it.
+        if check_spec_version_gate(toml) is not None:
+            return 1
+        rows.append(_extract_row(toml))
+
+    # Sort deterministically by pack name so output is stable across runs.
+    rows.sort(key=lambda r: r["name"])
+    _print_table(rows)
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _discover_pack_dirs(catalogue_dir: Path) -> list[Path]:
+    """Return pack directories found under *catalogue_dir*.
+
+    Tries ``<catalogue_dir>/packs/`` first (standard layout). If that
+    directory doesn't exist or contains no packs, falls back to treating
+    every direct subdirectory of *catalogue_dir* that contains a
+    ``pack.toml`` as a pack.
+    """
+    packs_subdir = catalogue_dir / "packs"
+    if packs_subdir.is_dir():
+        candidates = [p for p in packs_subdir.iterdir() if p.is_dir()]
+        found = [p for p in candidates if (p / "pack.toml").exists()]
+        if found:
+            return sorted(found, key=lambda p: p.name)
+
+    # Fallback: catalogue root itself may be a packs directory.
+    if catalogue_dir.is_dir():
+        fallback = [
+            p for p in catalogue_dir.iterdir()
+            if p.is_dir() and (p / "pack.toml").exists()
+        ]
+        return sorted(fallback, key=lambda p: p.name)
+
+    return []
+
+
+def _extract_row(toml: dict) -> dict:
+    """Pull display fields out of a parsed pack.toml dict."""
+    pack = toml.get("pack", {})
+    name = pack.get("name", "")
+    version = pack.get("version", "")
+    description = pack.get("description", "")
+
+    # Dependencies: look for [[pack.dependencies.required]] and
+    # [[pack.dependencies.recommended]].
+    deps: list[str] = []
+    dep_table = pack.get("dependencies", {})
+    if isinstance(dep_table, dict):
+        for kind in ("required", "recommended"):
+            for entry in dep_table.get(kind, []) or []:
+                if isinstance(entry, dict):
+                    dep_name = entry.get("pack", "")
+                    dep_version = entry.get("version", "")
+                    dep_str = dep_name
+                    if dep_version:
+                        dep_str += f"@{dep_version}"
+                    if dep_str:
+                        deps.append(dep_str)
+
+    return {
+        "name": name,
+        "version": version,
+        "description": description,
+        "dependencies": deps,
+    }
+
+
+def _print_table(rows: list[dict]) -> None:
+    """Print a fixed-column table to stdout.
+
+    Columns: name, version, description, dependencies.
+    Output is deterministic: rows are already sorted by caller; column
+    widths are derived from content so the table is alignment-stable.
+    """
+    headers = ["NAME", "VERSION", "DESCRIPTION", "DEPENDENCIES"]
+
+    # Convert deps list to a display string.
+    display_rows = [
+        {
+            "name": r["name"],
+            "version": r["version"],
+            "description": r["description"],
+            "dependencies": ", ".join(r["dependencies"]) if r["dependencies"] else "-",
+        }
+        for r in rows
+    ]
+
+    # Compute column widths.
+    col_keys = ["name", "version", "description", "dependencies"]
+    widths = [len(h) for h in headers]
+    for row in display_rows:
+        for i, key in enumerate(col_keys):
+            widths[i] = max(widths[i], len(row[key]))
+
+    # Format string: left-justify each column.
+    fmt = "  ".join(f"{{:<{w}}}" for w in widths)
+
+    print(fmt.format(*headers))
+    print(fmt.format(*("-" * w for w in widths)))
+    for row in display_rows:
+        print(fmt.format(*(row[k] for k in col_keys)))

agentbundle/commands/list_targets.py

@@ -0,0 +1,23 @@
+"""`agentbundle list-targets` subcommand.
+
+Prints one adapter name per line, in stable sort order, then exits 0.
+
+The list is derived from `agentbundle.render.list_adapters()`, which queries
+the runtime registry at `agentbundle.build.adapters.registry` — not a
+hardcoded constant.  Adding an adapter to the registry makes it appear here
+automatically.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from agentbundle.render import list_adapters
+
+
+def run(args: argparse.Namespace) -> int:  # noqa: ARG001
+    """Print one adapter name per line; exit 0."""
+    for name in list_adapters():
+        print(name)
+    return 0

agentbundle/commands/reconcile.py

@@ -0,0 +1,161 @@
+"""``agentbundle reconcile`` — read-only orphan reporter.
+
+Per RFC-0005 § Follow-on artifacts and AC26: walks the Claude Code
+settings file (``~/.claude/settings.json``) and every Kiro agent JSON
+named in user-scope state, comparing the on-disk ``hooks.<event>``
+arrays against the state file's ``hook-wiring-owned`` rows to surface
+two classes of orphan:
+
+  - **orphan-in-file** — the target file claims an id-tagged entry the
+    state file doesn't know about. Surfaces when a hand-edit on the
+    settings file (or on a Kiro agent JSON) adds an entry with an id
+    that no installed pack owns.
+  - **orphan-in-state** — the state file claims ownership of an entry
+    the target file doesn't have. Surfaces when the adopter
+    hand-deletes an entry without uninstalling the pack, or when
+    multi-machine sync moves a state row without its corresponding
+    target-file content.
+
+Output is grouped by adapter (one heading per adapter that has any
+orphans, plus an "all clean" line when there are none). The
+subcommand is **read-only**: it does not register an ``--apply`` flag.
+A write-mode reconciler would re-create the merge-discipline problems
+RFC-0005 is designed to avoid; the adopter takes manual action from
+this report.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import argparse
+
+
+def run(args: "argparse.Namespace") -> int:
+    """Entry point for ``agentbundle reconcile``.
+
+    The only supported scope today is ``user`` (RFC-0005's report
+    surface). A future RFC may extend to repo scope; ``--scope``
+    is accepted with that single value for now.
+    """
+    from agentbundle import scope as scope_mod
+    from agentbundle.config import ConfigError, load_state
+
+    cli_scope: str | None = getattr(args, "scope", None)
+    if cli_scope != "user":
+        print(
+            "reconcile: only --scope user is supported today",
+            file=sys.stderr,
+        )
+        return 1
+
+    try:
+        user_root = scope_mod.resolve_user_root()
+    except scope_mod.UserScopeUnresolvable:
+        print(
+            "reconcile: cannot resolve user scope: $HOME unset or invalid",
+            file=sys.stderr,
+        )
+        return 1
+
+    state_path = user_root / ".agentbundle" / "state.toml"
+    if not state_path.exists():
+        # An absent state file means no installs at user scope; no
+        # orphans to report against. Cleanly exit 0 with the all-clean
+        # line so wrapper scripts can short-circuit.
+        print("reconcile: all clean (no user-scope state)")
+        return 0
+
+    try:
+        state = load_state(state_path)
+    except ConfigError as exc:
+        print(f"reconcile: {exc}", file=sys.stderr)
+        return 1
+
+    orphans_by_adapter = _collect_orphans(state, user_root)
+    return _print_report(orphans_by_adapter)
+
+
+def _collect_orphans(state, user_root: Path) -> dict[str, list[str]]:
+    """Walk the target files referenced by state and compute orphans.
+
+    Returns a dict of adapter name → list of orphan lines (each line
+    a human-readable description suitable for direct print).
+    """
+    # Group state's hook-wiring-owned rows by (adapter, target-file)
+    # so we read each target file exactly once. The default target for
+    # claude-code rows is ``~/.claude/settings.json``; kiro rows always
+    # carry an explicit ``target-file``.
+    grouped: dict[tuple[str, str], set[tuple[str, str]]] = {}
+    for pack_name, pack_state in state.packs.items():
+        if pack_state.scope != "user":
+            continue
+        adapter = pack_state.adapter or "claude-code"
+        for row in pack_state.hook_wiring_owned:
+            event = row.get("event")
+            entry_id = row.get("id")
+            if not (isinstance(event, str) and isinstance(entry_id, str)):
+                continue
+            target_rel = row.get("target-file")
+            if not target_rel:
+                target_rel = (
+                    ".claude/settings.json" if adapter == "claude-code" else ""
+                )
+            if not target_rel:
+                continue
+            grouped.setdefault((adapter, target_rel), set()).add((event, entry_id))
+
+    orphans_by_adapter: dict[str, list[str]] = {}
+    for (adapter, target_rel), owned_pairs in grouped.items():
+        target_path = user_root / target_rel.lstrip("/")
+        file_pairs: set[tuple[str, str]] = set()
+        if target_path.exists():
+            try:
+                data = json.loads(target_path.read_text(encoding="utf-8"))
+            except (json.JSONDecodeError, OSError) as exc:
+                orphans_by_adapter.setdefault(adapter, []).append(
+                    f"  unparseable target {target_rel}: {exc}"
+                )
+                continue
+            if isinstance(data, dict):
+                hooks = data.get("hooks", {})
+                if isinstance(hooks, dict):
+                    for event, entries in hooks.items():
+                        if not isinstance(entries, list):
+                            continue
+                        for entry in entries:
+                            if isinstance(entry, dict) and isinstance(entry.get("id"), str):
+                                file_pairs.add((event, entry["id"]))
+
+        # orphan-in-file: present in file, absent from state.
+        for event, entry_id in sorted(file_pairs - owned_pairs):
+            orphans_by_adapter.setdefault(adapter, []).append(
+                f"  orphan-in-file: {target_rel} carries (event={event}, id={entry_id}) "
+                f"but no installed pack owns it"
+            )
+        # orphan-in-state: present in state, absent from file.
+        for event, entry_id in sorted(owned_pairs - file_pairs):
+            orphans_by_adapter.setdefault(adapter, []).append(
+                f"  orphan-in-state: state records ownership of (event={event}, "
+                f"id={entry_id}) in {target_rel} but the entry is missing on disk"
+            )
+
+    return orphans_by_adapter
+
+
+def _print_report(orphans_by_adapter: dict[str, list[str]]) -> int:
+    if not orphans_by_adapter:
+        print("reconcile: all clean")
+        return 0
+    for adapter in sorted(orphans_by_adapter.keys()):
+        lines = orphans_by_adapter[adapter]
+        if not lines:
+            continue
+        print(f"reconcile: {adapter}")
+        for line in lines:
+            print(line)
+    return 0

agentbundle/commands/render.py

@@ -0,0 +1,165 @@
+"""`agentbundle render` — project a pack to --output via the F-build pipeline.
+
+Option (b) from the task spec: call `render.render_pack()` in-memory,
+then walk the dict-of-bytes and write each entry via `safety.write_jailed`.
+This is the more defensive shape: the path-jail check fires on every write,
+not just as a pre-flight.
+
+The three RFC-0001 default recipes are run when --target is absent. When
+--target is given, only recipes whose adapter matches the target are run
+(the aggregate `marketplace` recipe has no adapter and is included unless
+filtered by a named target that doesn't match it).
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from agentbundle import render as _render
+from agentbundle.build.main import DEFAULT_RECIPES, load_recipe
+from agentbundle.commands._common import check_spec_version_gate
+from agentbundle.config import ConfigError, load_pack_toml
+from agentbundle.safety import PathJailError, write_jailed
+
+
+def run(args) -> int:
+    """Entry point for `agentbundle render <pack_path> --output <dir> [--target <t>]`."""
+    pack_path = Path(args.pack_path).resolve()
+    output_dir = Path(args.output).resolve()
+
+    # Validate pack_path
+    if not (pack_path / "pack.toml").exists():
+        print(
+            f"render: no pack.toml found at {pack_path}",
+            file=sys.stderr,
+        )
+        return 1
+
+    # Spec-version gate (AC #14 — uniform refusal across subcommands).
+    try:
+        gate = check_spec_version_gate(load_pack_toml(pack_path / "pack.toml"))
+    except ConfigError as exc:
+        print(f"render: {exc}", file=sys.stderr)
+        return 1
+    if gate is not None:
+        return gate
+
+    # Determine recipe set
+    recipes = _select_recipes(getattr(args, "target", None))
+    if recipes is None:
+        # Unknown target
+        from agentbundle.build.adapters import ADAPTERS
+
+        known = sorted(ADAPTERS.keys())
+        target = getattr(args, "target", None)
+        print(
+            f"render: unknown target {target!r}; known targets: {', '.join(known)}",
+            file=sys.stderr,
+        )
+        return 1
+
+    # Render in-memory
+    try:
+        file_tree = _render.render_pack(pack_path, recipes=recipes)
+    except FileNotFoundError as exc:
+        print(f"render: {exc}", file=sys.stderr)
+        return 1
+    except ValueError as exc:
+        print(f"render: schema error: {exc}", file=sys.stderr)
+        return 1
+
+    # Tier-2 awareness is opt-in via --self-host. Without the flag,
+    # `render` writes the projection wholesale (matching `make build`'s
+    # dist/ semantic) even if a state file happens to sit at --output.
+    # With the flag, --output is treated as an adopter root: collisions
+    # with adopter-edited content produce .upstream.<ext> companions.
+    self_host_mode = bool(getattr(args, "self_host", False))
+    state_path = output_dir / ".agentbundle-state.toml"
+    state = None
+    if self_host_mode:
+        if not state_path.exists():
+            print(
+                f"render: --self-host requires .agentbundle-state.toml at {output_dir} "
+                f"(install or init-state first)",
+                file=sys.stderr,
+            )
+            return 1
+        from agentbundle.config import load_state
+
+        try:
+            state = load_state(state_path)
+        except ConfigError as exc:
+            print(f"render: {exc}", file=sys.stderr)
+            return 1
+
+    # Write each file via write_jailed (path-jail is non-optional)
+    output_dir.mkdir(parents=True, exist_ok=True)
+    for relpath, content in sorted(file_tree.items()):
+        target = output_dir / relpath
+        if self_host_mode and target.exists():
+            from agentbundle import safety as _safety
+
+            if _safety.sha256_file(target) != _safety.sha256_bytes(content):
+                # Adopter-edited Tier-2; drop companion, leave original.
+                try:
+                    _safety.write_companion(output_dir, relpath, content)
+                except PathJailError as exc:
+                    print(f"render: {exc}", file=sys.stderr)
+                    return 1
+                print(f"{relpath} (companion)")
+                continue
+        try:
+            write_jailed(output_dir, relpath, content)
+        except PathJailError as exc:
+            print(f"render: {exc}", file=sys.stderr)
+            return 1
+        print(relpath)
+
+    return 0
+
+
+def _canonicalise_target(name: str) -> str | None:
+    """Return the hyphenated canonical adapter name, or None if unknown.
+
+    Accepts both the contract-form `claude-code` and the Python-module form
+    `claude_code` so adopters don't have to remember which the CLI flag
+    expects. Single source of truth for the hyphen/underscore duality;
+    `list-targets` calls this too.
+
+    The literal `apm` is a special case — an aggregate recipe in F-build,
+    not a per-adapter projection — and is accepted as a recipe filter even
+    though it isn't in the module-keyed `registry`.
+    """
+    from agentbundle.build.adapters import ADAPTERS
+
+    known_hyphenated = set(ADAPTERS.keys()) | {"apm"}
+    if name in known_hyphenated:
+        return name
+    if name.replace("_", "-") in known_hyphenated:
+        return name.replace("_", "-")
+    return None
+
+
+def _select_recipes(target: str | None) -> list[str] | None:
+    """Return the recipe list for the given target (or DEFAULT_RECIPES if None).
+
+    Returns None if the target is specified but unknown.
+    """
+    if target is None:
+        return list(DEFAULT_RECIPES)
+
+    canonical = _canonicalise_target(target)
+    if canonical is None:
+        return None
+
+    # Filter DEFAULT_RECIPES to those whose adapter matches, plus adapter-less recipes.
+    selected: list[str] = []
+    for recipe_name in DEFAULT_RECIPES:
+        try:
+            recipe = load_recipe(recipe_name)
+        except FileNotFoundError:
+            continue
+        if recipe.adapter is None or recipe.adapter == canonical:
+            selected.append(recipe_name)
+    return selected

agentbundle/commands/scaffold.py

@@ -0,0 +1,69 @@
+"""T4: `scaffold` subcommand — drop a pack's seeds/ into --output.
+
+Iterates the pack's `seeds/` subdirectory recursively. For each file:
+
+  - Absent on disk (Tier-1 fast-path):  write the seed.
+  - Present, content matches:           no-op (already in sync).
+  - Present, content differs (Tier-2):  write a `.upstream.<ext>` companion
+                                         next to the original; leave original
+                                         untouched.
+
+Every write routes through `safety.write_jailed` (path-jail is non-optional).
+`scaffold` does NOT write `.agentbundle-state.toml` — that is `install`'s job.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from agentbundle import safety
+from agentbundle.commands._common import check_spec_version_gate, deliver_seeds
+from agentbundle.config import ConfigError, load_pack_toml
+
+
+def run(args: argparse.Namespace) -> int:
+    """Entry point for `agentbundle scaffold`.
+
+    Returns 0 on success, 1 on error.
+    """
+    packs_dir = Path(args.packs_dir)
+    pack_name = args.pack
+    output = Path(args.output)
+
+    pack_dir = packs_dir / pack_name
+    seeds_dir = pack_dir / "seeds"
+
+    pack_toml_path = pack_dir / "pack.toml"
+    if pack_toml_path.exists():
+        try:
+            gate = check_spec_version_gate(load_pack_toml(pack_toml_path))
+        except ConfigError as exc:
+            print(f"scaffold: {exc}", file=sys.stderr)
+            return 1
+        if gate is not None:
+            return gate
+
+    if not seeds_dir.is_dir():
+        print(f"no seeds/ in pack {pack_name}", file=sys.stderr)
+        return 1
+
+    # Seed delivery (Tier-1/2/3, composition-fragment handling) is shared with
+    # `install`; see ``commands._common.deliver_seeds``. `scaffold` does NOT
+    # write `.agentbundle-state.toml` — that is `install`'s job.
+    try:
+        deliveries = deliver_seeds(seeds_dir, output)
+    except safety.PathJailError as exc:
+        print(f"scaffold: {exc}", file=sys.stderr)
+        return 1
+
+    for rec in deliveries:
+        if rec.action == "wrote":
+            print(f"{rec.relpath}: wrote (new)")
+        elif rec.action == "skipped":
+            print(f"{rec.relpath}: up-to-date (skipped)")
+        else:  # companion
+            print(f"{rec.relpath}: kept original, wrote companion {rec.companion_relpath}")
+
+    return 0