agentbundle 0.12.1__tar.gz → 0.13.0__tar.gz

{agentbundle-0.12.1 → agentbundle-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentbundle
-Version: 0.12.1
+Version: 0.13.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
@@ -64,6 +64,8 @@ agentbundle show core --format json          # stable object for scripts/agents
 agentbundle list-installed
 agentbundle list-installed --no-check       # skip the catalogue check (offline, fast)
 agentbundle list-installed --check-drift    # also count locally edited files
+agentbundle list-installed --format json    # machine-readable JSON (schema_version 1)
+agentbundle list-installed --updates-only   # show only rows needing attention
 
 # Install a whole curated profile — a single-scope set of packs — in one command
 agentbundle install --profile inception
@@ -80,7 +82,7 @@ agentbundle uninstall --pack core --dry-run
 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.
+**`list-installed`** reads your state files (not the catalogue) and reports every installed `(pack, adapter)` at each scope with its version and a four-value status — `up-to-date`, `upgrade-available`, `ahead` (installed version is newer than catalogue), or `unknown`; it degrades to `unknown` (never an error) when the catalogue can't be resolved, and `--no-check` skips the check entirely. `--format json` emits a stable JSON contract (`schema_version: 1`) to stdout — useful for CI automation of upgrade decisions. `--updates-only` hides `up-to-date` rows.
 
 **`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.
 
@@ -88,6 +90,90 @@ A **profile** is a catalogue-curated, single-scope set of packs you install in o
 
 **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).
 
+## Enterprise distribution
+
+For organizations running an internal Artifactory mirror or any static HTTPS server,
+agentbundle's enterprise distribution capabilities handle the full adoption loop —
+from org-wide channel configuration to CI-driven bulk upgrades.
+
+**Install from an internal Artifactory channel:**
+
+```bash
+# Point agentbundle at your org's channel descriptor (one-time per machine,
+# or pre-configured in your org fork — see Org bootstrap below)
+agentbundle config set source catalogue+https://artifactory.example.test/agentbundle/catalogues/core/channels/stable.json
+
+agentbundle install --pack core
+```
+
+The channel descriptor points to an immutable versioned archive; agentbundle
+fetches, verifies its SHA-256 digest, and installs. Pass a bearer token via
+`AGENTBUNDLE_HTTP_BEARER_TOKEN` — it is never stored in state, never printed, and
+never forwarded to a different host.
+
+**JSON output for CI pipelines:**
+
+```bash
+# See what's installed and what needs upgrading — machine-readable
+agentbundle list-installed --format json
+agentbundle list-installed --format json --updates-only
+```
+
+Returns a stable JSON contract (`schema_version` 1) with per-row status
+(`up-to-date` / `upgrade-available` / `ahead` / `unknown`) and machine-readable
+reason codes for unknown rows. Pipe into `jq` or your CI annotation step.
+
+**Bulk upgrade in one scoped command:**
+
+```bash
+# Upgrade all installed packs in a scope — preflights before any write
+agentbundle upgrade --all --scope repo --yes
+agentbundle upgrade --all --scope user --format json --yes
+```
+
+Preflights all rows before writing anything; a blocked row stops the run before the
+filesystem is touched. Partial failure is reported honestly — not described as a
+rollback. Never silently downgrades an `ahead` row.
+
+**Package your catalogue for Artifactory:**
+
+```bash
+agentbundle package-catalogue \
+  --root /path/to/catalogue \
+  --bundle my-packs \
+  --release 1.0.0 \
+  --channel stable \
+  --output dist/
+```
+
+Produces a deterministic, reproducible gzip archive (versioned) and a mutable channel
+descriptor JSON (`stable.json`), ready to upload to Artifactory. Identical inputs
+produce byte-identical archives (honors `SOURCE_DATE_EPOCH`).
+
+**Org bootstrap — ship the default channel in your fork:**
+
+Add an `[organization.artifactory]` block to
+`agentbundle/_data/install-defaults.toml` in your org's agentbundle fork:
+
+```toml
+[organization.artifactory]
+enabled = true
+base-url = "https://artifactory.example.test"
+repository = "agentbundle"
+bundle = "core"
+channel = "stable"
+```
+
+Developers installing from your fork get the internal channel without a manual
+`config set source` step. The block ships `enabled = false` in the public package.
+A malformed `enabled = true` config fails closed — no silent fallback to the public
+source.
+
+See the full enterprise adoption guide at
+`docs/guides/_shared/how-to/use-an-artifactory-catalogue.md` for all six flows
+(org bootstrap, repo-scope CI upgrade, user-scope MDM, source-conflict remediation,
+disconnected hosts, and security controls).
+
 ## Build your own catalogue
 
 `agentbundle` isn't tied to the agent-ready-repo catalogue. Any repo that lays its packs out the same way can use it. A pack is a directory:
@@ -120,6 +206,15 @@ is deliberately lossy per tool.
 
 Point a catalogue URI (a git URL or a local path) at the repo that holds your packs. Then `validate` a pack against the adapter contract, `render` it to preview the projection, and `install` it into a target repo. `scaffold` drops a pack's seeds into a fresh directory to start from. The build pipeline (`agentbundle.build`) is the same engine `make build` runs.
 
+**Org adapter default:** If your org ships a private `agentbundle` wheel (or a fork pinned to your internal catalogue), you can set a default adapter for all developers without requiring them to run `agentbundle config set` or pass `--adapter` on every install. Add an `[organization]` table to `_data/install-defaults.toml` in your fork:
+
+```toml
+[organization]
+preferred_adapter = "cursor"
+```
+
+The org hint fires after the user-config but before the on-disk IDE probe — so `--adapter`, user-config, and upgrade state-hints all take priority. An invalid value exits 1 before writing anything. See the [`agentbundle` reference](https://github.com/eugenelim/agent-ready-repo/blob/main/docs/guides/_shared/reference/agentbundle.md#org-adapter-default) for the full cascade.
+
 See the [pack layout reference](https://github.com/eugenelim/agent-ready-repo/blob/main/docs/architecture/pack-layout.md) and [authoring a skill](https://github.com/eugenelim/agent-ready-repo/blob/main/docs/guides/_shared/how-to/author-a-skill.md).
 
 ## Credentials

{agentbundle-0.12.1 → agentbundle-0.13.0}/README.md

@@ -46,6 +46,8 @@ agentbundle show core --format json          # stable object for scripts/agents
 agentbundle list-installed
 agentbundle list-installed --no-check       # skip the catalogue check (offline, fast)
 agentbundle list-installed --check-drift    # also count locally edited files
+agentbundle list-installed --format json    # machine-readable JSON (schema_version 1)
+agentbundle list-installed --updates-only   # show only rows needing attention
 
 # Install a whole curated profile — a single-scope set of packs — in one command
 agentbundle install --profile inception
@@ -62,7 +64,7 @@ agentbundle uninstall --pack core --dry-run
 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.
+**`list-installed`** reads your state files (not the catalogue) and reports every installed `(pack, adapter)` at each scope with its version and a four-value status — `up-to-date`, `upgrade-available`, `ahead` (installed version is newer than catalogue), or `unknown`; it degrades to `unknown` (never an error) when the catalogue can't be resolved, and `--no-check` skips the check entirely. `--format json` emits a stable JSON contract (`schema_version: 1`) to stdout — useful for CI automation of upgrade decisions. `--updates-only` hides `up-to-date` rows.
 
 **`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.
 
@@ -70,6 +72,90 @@ A **profile** is a catalogue-curated, single-scope set of packs you install in o
 
 **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).
 
+## Enterprise distribution
+
+For organizations running an internal Artifactory mirror or any static HTTPS server,
+agentbundle's enterprise distribution capabilities handle the full adoption loop —
+from org-wide channel configuration to CI-driven bulk upgrades.
+
+**Install from an internal Artifactory channel:**
+
+```bash
+# Point agentbundle at your org's channel descriptor (one-time per machine,
+# or pre-configured in your org fork — see Org bootstrap below)
+agentbundle config set source catalogue+https://artifactory.example.test/agentbundle/catalogues/core/channels/stable.json
+
+agentbundle install --pack core
+```
+
+The channel descriptor points to an immutable versioned archive; agentbundle
+fetches, verifies its SHA-256 digest, and installs. Pass a bearer token via
+`AGENTBUNDLE_HTTP_BEARER_TOKEN` — it is never stored in state, never printed, and
+never forwarded to a different host.
+
+**JSON output for CI pipelines:**
+
+```bash
+# See what's installed and what needs upgrading — machine-readable
+agentbundle list-installed --format json
+agentbundle list-installed --format json --updates-only
+```
+
+Returns a stable JSON contract (`schema_version` 1) with per-row status
+(`up-to-date` / `upgrade-available` / `ahead` / `unknown`) and machine-readable
+reason codes for unknown rows. Pipe into `jq` or your CI annotation step.
+
+**Bulk upgrade in one scoped command:**
+
+```bash
+# Upgrade all installed packs in a scope — preflights before any write
+agentbundle upgrade --all --scope repo --yes
+agentbundle upgrade --all --scope user --format json --yes
+```
+
+Preflights all rows before writing anything; a blocked row stops the run before the
+filesystem is touched. Partial failure is reported honestly — not described as a
+rollback. Never silently downgrades an `ahead` row.
+
+**Package your catalogue for Artifactory:**
+
+```bash
+agentbundle package-catalogue \
+  --root /path/to/catalogue \
+  --bundle my-packs \
+  --release 1.0.0 \
+  --channel stable \
+  --output dist/
+```
+
+Produces a deterministic, reproducible gzip archive (versioned) and a mutable channel
+descriptor JSON (`stable.json`), ready to upload to Artifactory. Identical inputs
+produce byte-identical archives (honors `SOURCE_DATE_EPOCH`).
+
+**Org bootstrap — ship the default channel in your fork:**
+
+Add an `[organization.artifactory]` block to
+`agentbundle/_data/install-defaults.toml` in your org's agentbundle fork:
+
+```toml
+[organization.artifactory]
+enabled = true
+base-url = "https://artifactory.example.test"
+repository = "agentbundle"
+bundle = "core"
+channel = "stable"
+```
+
+Developers installing from your fork get the internal channel without a manual
+`config set source` step. The block ships `enabled = false` in the public package.
+A malformed `enabled = true` config fails closed — no silent fallback to the public
+source.
+
+See the full enterprise adoption guide at
+`docs/guides/_shared/how-to/use-an-artifactory-catalogue.md` for all six flows
+(org bootstrap, repo-scope CI upgrade, user-scope MDM, source-conflict remediation,
+disconnected hosts, and security controls).
+
 ## Build your own catalogue
 
 `agentbundle` isn't tied to the agent-ready-repo catalogue. Any repo that lays its packs out the same way can use it. A pack is a directory:
@@ -102,6 +188,15 @@ is deliberately lossy per tool.
 
 Point a catalogue URI (a git URL or a local path) at the repo that holds your packs. Then `validate` a pack against the adapter contract, `render` it to preview the projection, and `install` it into a target repo. `scaffold` drops a pack's seeds into a fresh directory to start from. The build pipeline (`agentbundle.build`) is the same engine `make build` runs.
 
+**Org adapter default:** If your org ships a private `agentbundle` wheel (or a fork pinned to your internal catalogue), you can set a default adapter for all developers without requiring them to run `agentbundle config set` or pass `--adapter` on every install. Add an `[organization]` table to `_data/install-defaults.toml` in your fork:
+
+```toml
+[organization]
+preferred_adapter = "cursor"
+```
+
+The org hint fires after the user-config but before the on-disk IDE probe — so `--adapter`, user-config, and upgrade state-hints all take priority. An invalid value exits 1 before writing anything. See the [`agentbundle` reference](https://github.com/eugenelim/agent-ready-repo/blob/main/docs/guides/_shared/reference/agentbundle.md#org-adapter-default) for the full cascade.
+
 See the [pack layout reference](https://github.com/eugenelim/agent-ready-repo/blob/main/docs/architecture/pack-layout.md) and [authoring a skill](https://github.com/eugenelim/agent-ready-repo/blob/main/docs/guides/_shared/how-to/author-a-skill.md).
 
 ## Credentials

agentbundle-0.13.0/agentbundle/_data/install-defaults.toml

@@ -0,0 +1,19 @@
+# Optional organisation Artifactory bootstrap — layer 3 of the catalogue-source
+# resolution chain (RFC-0072 D2 / ADR-0036). When the ``enabled`` boolean is
+# set to ``true``, agentbundle constructs the URL:
+#   catalogue+<base-url>/<repository>/catalogues/<bundle>/channels/<channel>.json
+# as the default source for developers installing from this fork.
+# Public default ships ``enabled = false``; no real org endpoints are stored here.
+[organization.artifactory]
+enabled = false
+
+# Packaged install default — layer 5 of the catalogue-source resolution chain
+# (RFC-0046 / ADR-0036). When `agentbundle install`/`upgrade` is run with no
+# `catalogue` positional and layers 1–4 (explicit arg, user config, org
+# Artifactory bootstrap, editable detection) yield nothing, this source is used.
+#
+# Private-fork pattern: blank the `source` value below (or delete this file
+# entirely) to disable the packaged GitHub default — layers 1–4 still apply, so
+# an editable clone or a `config set source` still resolves.
+[defaults]
+source = "git+https://github.com/eugenelim/agent-ready-repo"

{agentbundle-0.12.1 → agentbundle-0.13.0}/agentbundle/catalogue.py

@@ -65,6 +65,19 @@ def resolve_catalogue(uri: str) -> Path:
             "SSH git URLs deferred to v1.1; use https or local path."
         )
 
+    # Explicit reject for http:// variants — layer-1 explicit arg bypasses
+    # _is_valid_source, so we must guard here to avoid silent local-path fallback.
+    if uri.startswith(("catalogue+http://", "archive+http://")):
+        raise CatalogueError(
+            "HTTPS-only: catalogue+http:// and archive+http:// are not supported; "
+            "use catalogue+https:// or archive+https://"
+        )
+
+    # Dispatch new HTTPS catalogue schemes (RFC-0072)
+    if uri.startswith(("catalogue+https://", "archive+https://")):
+        from agentbundle.https_catalogue import fetch_catalogue_archive
+        return fetch_catalogue_archive(uri)
+
     if uri.startswith(_HTTPS_PREFIX):
         return _resolve_https(uri)
 

{agentbundle-0.12.1 → agentbundle-0.13.0}/agentbundle/cli.py

@@ -3,9 +3,9 @@
 Subcommand order on the parser matches the canonical install-workflow order
 from the spec (discovery-first): `list-packs`, `list-profiles`, `list-targets`,
 `scaffold`, `install`, `validate`, `render`, `adapt`, `diff`, `upgrade`,
-`uninstall`, `init-state`, `config`, `reconcile`. `list-profiles` (RFC-0034)
-lists the catalogue's curated single-scope install profiles; `install
---profile <name>` installs one.
+`uninstall`, `init-state`, `config`, `reconcile`, `package-catalogue`.
+`list-profiles` (RFC-0034) lists the catalogue's curated single-scope install
+profiles; `install --profile <name>` installs one.
 
 Each subcommand's `run(args) -> int` lives under `agentbundle.commands.*`;
 this module wires `argparse` and prints `--version`. No business logic here.
@@ -243,9 +243,9 @@ def _build_parser() -> argparse.ArgumentParser:
         nargs="?",
         default=None,
         help=(
-            "Catalogue URI to compare installed versions against. Optional: when "
-            "omitted, the source is resolved from your config, an editable clone, "
-            "or the packaged default (RFC-0047). Ignored under --no-check."
+            "[Deprecated] Catalogue URI -- now ignored; rows are resolved against "
+            "their recorded provenance. Use --no-check to skip catalogue resolution "
+            "entirely."
         ),
     )
     sp.add_argument("--root", default=".")
@@ -272,6 +272,21 @@ def _build_parser() -> argparse.ArgumentParser:
             "install (on-disk SHA differs from the recorded SHA)."
         ),
     )
+    sp.add_argument(
+        "--format",
+        choices=["table", "json"],
+        default="table",
+        help="Output format: table (default) or json.",
+    )
+    sp.add_argument(
+        "--updates-only",
+        action="store_true",
+        default=False,
+        help=(
+            "Show only rows needing attention (upgrade-available, ahead, unknown). "
+            "Summary counts always reflect the full set. No effect under --no-check."
+        ),
+    )
     sp.set_defaults(func=_lazy("list_installed"))
 
     # --- show --- (catalogue query; walks a pack's .apm/ tree live)
@@ -491,7 +506,24 @@ def _build_parser() -> argparse.ArgumentParser:
         "upgrade",
         help="Upgrade a pack or a single primitive within a pack.",
     )
-    sp.add_argument("--pack", required=True)
+    # --pack and --all are mutually exclusive; exactly one is required (AC1).
+    mode_group = sp.add_mutually_exclusive_group(required=True)
+    mode_group.add_argument(
+        "--pack",
+        help="Upgrade a single named pack (whole-pack or per-primitive).",
+    )
+    mode_group.add_argument(
+        "--all",
+        action="store_true",
+        dest="all",
+        default=False,
+        help=(
+            "Upgrade all installed packs at the given --scope. "
+            "Requires --scope repo|user. Rejects --adapter and positional "
+            "<catalogue>. Uses each row's recorded provenance for source "
+            "resolution."
+        ),
+    )
     # The five per-primitive flags are mutually exclusive: a pack-version
     # upgrade is for the whole pack or exactly one named primitive, never two
     # at once. Grouping them lets argparse reject `--skill a --agent b` rather
@@ -509,7 +541,7 @@ def _build_parser() -> argparse.ArgumentParser:
         help=(
             "Catalogue URI to fetch the new version from. Optional: when "
             "omitted, the source is resolved from your config, an editable "
-            "clone, or the packaged default (RFC-0046)."
+            "clone, or the packaged default (RFC-0046). Rejected with --all."
         ),
     )
     sp.add_argument("--root", default=".")
@@ -520,7 +552,18 @@ def _build_parser() -> argparse.ArgumentParser:
         help=(
             "Disambiguate when the pack is installed for multiple adapters at "
             "the resolved scope (RFC-0052). Inferred when the pack has a single "
-            "adapter row; required when it has more than one."
+            "adapter row; required when it has more than one. Rejected with --all."
+        ),
+    )
+    sp.add_argument(
+        "--format",
+        choices=("table", "json"),
+        default="table",
+        help=(
+            "Output format. 'table' (default) prints a human-readable plan "
+            "table. 'json' emits a machine-readable JSON document to stdout "
+            "(requires --yes for non-dry-run applies; not yet supported with "
+            "--pack)."
         ),
     )
     sp.add_argument(
@@ -529,7 +572,8 @@ def _build_parser() -> argparse.ArgumentParser:
         help=(
             "Skip the upgrade confirmation prompt. Required for non-interactive "
             "use (CI, pipes); without it the upgrade asks before writing, and "
-            "refuses rather than blocking when stdin is not a TTY."
+            "refuses rather than blocking when stdin is not a TTY. Required for "
+            "--format json with --all (non-dry-run)."
         ),
     )
     sp.add_argument(
@@ -636,6 +680,33 @@ def _build_parser() -> argparse.ArgumentParser:
     )
     sp.set_defaults(func=_lazy("reconcile"))
 
+    # --- package-catalogue --- (maintainer/CI only; RFC-0072 D1/D5)
+    sp = subparsers.add_parser(
+        "package-catalogue",
+        help="Package a catalogue repository into an Artifactory artifact layout (maintainer/CI only).",
+    )
+    sp.add_argument("--root", required=True, help="Catalogue repository root directory.")
+    sp.add_argument("--bundle", required=True, help="Bundle name (e.g. engineering).")
+    sp.add_argument("--release", required=True, help="Release tag (e.g. 0.13.0).")
+    sp.add_argument("--channel", required=True, help="Channel name (e.g. stable).")
+    sp.add_argument("--output", required=True, help="Output root directory.")
+    sp.add_argument(
+        "--source-revision",
+        default=None,
+        help="Git commit or tag (CI supplies this; no git shell-out).",
+    )
+    sp.add_argument(
+        "--minimum-agentbundle-version",
+        default=None,
+        help="Minimum agentbundle version for the channel descriptor.",
+    )
+    sp.add_argument(
+        "--published-at",
+        default=None,
+        help="Publication timestamp for the channel descriptor (ISO-8601).",
+    )
+    sp.set_defaults(func=_lazy("package_catalogue"))
+
     return parser