agentbundle 0.6.0__tar.gz → 0.7.0__tar.gz

{agentbundle-0.6.0 → agentbundle-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentbundle
-Version: 0.6.0
+Version: 0.7.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
@@ -22,43 +22,57 @@ Description-Content-Type: text/markdown
 [![Python](https://img.shields.io/pypi/pyversions/agentbundle)](https://pypi.org/project/agentbundle/)
 [![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue)](https://github.com/eugenelim/agent-ready-repo#license)
 
-**The installer for [agent-ready-repo](https://github.com/eugenelim/agent-ready-repo).** Think npm, but for the skills, subagents, and hooks your coding agent runs on.
+**The installer for [agent-ready-repo](https://github.com/eugenelim/agent-ready-repo).** Think npm, but for the skills, subagents, and hooks your coding agent runs on. One pack, one command, every major agent — Claude Code, Codex, Cursor, Copilot, Gemini, and Kiro (both the CLI and the IDE).
 
-`agentbundle` installs packs of agent primitives into your repo or your home directory. It projects each primitive into the layout every agent expects. One pack. One command. Every major agent.
+## Quick start
 
 ```bash
 pip install agentbundle
+```
+
+**Install into a repo** — so everyone who clones it gets the pack. `core` is the flagship pack, the loop itself:
+
+```bash
 agentbundle install --pack core git+https://github.com/eugenelim/agent-ready-repo
 ```
 
-That lands `core`, the flagship pack and the loop itself, in your repo. Claude Code, Codex, Cursor, Copilot, Gemini, and Kiro — both the CLI and the IDE — all read it, subagents and skills included.
+It lands in the repo's agent config — subagents and skills included — and you commit it like any other project file. This is the default scope: the pack belongs to the project and the whole team.
 
-## Common commands
+**Install for yourself, everywhere** — so a pack follows you across every project, with no per-repo setup:
 
 ```bash
-# See what's in a catalogue
-agentbundle list-packs git+https://github.com/eugenelim/agent-ready-repo
+agentbundle install --pack research git+https://github.com/eugenelim/agent-ready-repo --scope user
+```
+
+User-scope packs land in your home directory, not the repo — they're yours, not the team's, and they're there in every project you open.
+
+A catalogue is a git URL or a local path, and the install auto-detects your agent (`--adapter` overrides).
 
-# See the catalogue's curated install profiles
+## More commands
+
+```bash
+# See what a catalogue offers
+agentbundle list-packs    git+https://github.com/eugenelim/agent-ready-repo
 agentbundle list-profiles git+https://github.com/eugenelim/agent-ready-repo
 
 # Install a whole curated profile — a single-scope set of packs — in one command
 agentbundle install --profile inception git+https://github.com/eugenelim/agent-ready-repo
 
-# Install the flagship loop into this repo
-agentbundle install --pack core git+https://github.com/eugenelim/agent-ready-repo
-
-# Install a pack at user scope, so it follows you across every project
-agentbundle install --pack research git+https://github.com/eugenelim/agent-ready-repo --scope user
-
-# Preview an install without writing a file
+# Preview any install without writing a file
 agentbundle install --pack core git+https://github.com/eugenelim/agent-ready-repo --dry-run
 
-# Upgrade a pack; it reports the .upstream files you need to reconcile
-agentbundle upgrade --pack core --to 0.4.0 git+https://github.com/eugenelim/agent-ready-repo
+# Upgrade to the version the catalogue ships — shows installed → target, asks first
+agentbundle upgrade --pack core git+https://github.com/eugenelim/agent-ready-repo
+agentbundle upgrade --pack core git+https://github.com/eugenelim/agent-ready-repo --yes  # skip the prompt (CI)
+
+# Uninstall — previews remove (Tier-1) vs keep (your edits), asks first
+agentbundle uninstall --pack core --dry-run
+agentbundle uninstall --pack core --yes
 ```
 
-A catalogue is a git URL or a local path. Installs auto-detect your agent; pass `--adapter` to override. 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.
+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).
 
 ## Build your own catalogue
 

{agentbundle-0.6.0 → agentbundle-0.7.0}/README.md

@@ -4,43 +4,57 @@
 [![Python](https://img.shields.io/pypi/pyversions/agentbundle)](https://pypi.org/project/agentbundle/)
 [![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue)](https://github.com/eugenelim/agent-ready-repo#license)
 
-**The installer for [agent-ready-repo](https://github.com/eugenelim/agent-ready-repo).** Think npm, but for the skills, subagents, and hooks your coding agent runs on.
+**The installer for [agent-ready-repo](https://github.com/eugenelim/agent-ready-repo).** Think npm, but for the skills, subagents, and hooks your coding agent runs on. One pack, one command, every major agent — Claude Code, Codex, Cursor, Copilot, Gemini, and Kiro (both the CLI and the IDE).
 
-`agentbundle` installs packs of agent primitives into your repo or your home directory. It projects each primitive into the layout every agent expects. One pack. One command. Every major agent.
+## Quick start
 
 ```bash
 pip install agentbundle
+```
+
+**Install into a repo** — so everyone who clones it gets the pack. `core` is the flagship pack, the loop itself:
+
+```bash
 agentbundle install --pack core git+https://github.com/eugenelim/agent-ready-repo
 ```
 
-That lands `core`, the flagship pack and the loop itself, in your repo. Claude Code, Codex, Cursor, Copilot, Gemini, and Kiro — both the CLI and the IDE — all read it, subagents and skills included.
+It lands in the repo's agent config — subagents and skills included — and you commit it like any other project file. This is the default scope: the pack belongs to the project and the whole team.
 
-## Common commands
+**Install for yourself, everywhere** — so a pack follows you across every project, with no per-repo setup:
 
 ```bash
-# See what's in a catalogue
-agentbundle list-packs git+https://github.com/eugenelim/agent-ready-repo
+agentbundle install --pack research git+https://github.com/eugenelim/agent-ready-repo --scope user
+```
+
+User-scope packs land in your home directory, not the repo — they're yours, not the team's, and they're there in every project you open.
+
+A catalogue is a git URL or a local path, and the install auto-detects your agent (`--adapter` overrides).
 
-# See the catalogue's curated install profiles
+## More commands
+
+```bash
+# See what a catalogue offers
+agentbundle list-packs    git+https://github.com/eugenelim/agent-ready-repo
 agentbundle list-profiles git+https://github.com/eugenelim/agent-ready-repo
 
 # Install a whole curated profile — a single-scope set of packs — in one command
 agentbundle install --profile inception git+https://github.com/eugenelim/agent-ready-repo
 
-# Install the flagship loop into this repo
-agentbundle install --pack core git+https://github.com/eugenelim/agent-ready-repo
-
-# Install a pack at user scope, so it follows you across every project
-agentbundle install --pack research git+https://github.com/eugenelim/agent-ready-repo --scope user
-
-# Preview an install without writing a file
+# Preview any install without writing a file
 agentbundle install --pack core git+https://github.com/eugenelim/agent-ready-repo --dry-run
 
-# Upgrade a pack; it reports the .upstream files you need to reconcile
-agentbundle upgrade --pack core --to 0.4.0 git+https://github.com/eugenelim/agent-ready-repo
+# Upgrade to the version the catalogue ships — shows installed → target, asks first
+agentbundle upgrade --pack core git+https://github.com/eugenelim/agent-ready-repo
+agentbundle upgrade --pack core git+https://github.com/eugenelim/agent-ready-repo --yes  # skip the prompt (CI)
+
+# Uninstall — previews remove (Tier-1) vs keep (your edits), asks first
+agentbundle uninstall --pack core --dry-run
+agentbundle uninstall --pack core --yes
 ```
 
-A catalogue is a git URL or a local path. Installs auto-detect your agent; pass `--adapter` to override. 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.
+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).
 
 ## Build your own catalogue
 

{agentbundle-0.6.0 → agentbundle-0.7.0}/agentbundle/_data/adapter.toml

@@ -77,7 +77,14 @@
 # the default agent's `.kiro/skills` auto-discovery (RFC-0022 E4; kiro
 # #6887/#6888/#4993). Additive `inject-resources` on BOTH the kiro-cli and
 # kiro-ide agent projections (CLI → agent JSON, IDE → quoted .md frontmatter).
-version = "0.15"
+# RFC-0040 / ADR-0030 / docs/specs/consolidated-pack-layout (v0.16): pack.toml
+# gains an optional scope-keyed [pack.layout] table (optional .repo / .user
+# sub-tables, each a `parent` base and/or a within-pack template-path) naming
+# where a consuming pack's durable output lands. Consumed by the new installer
+# `_append_layout_section` step (append-if-exists / never-create / never-
+# overwrite) into an adopter-owned `agentbundle-layout.toml`. Additive +
+# optional — packs pinned below v0.16 build and validate unchanged.
+version = "0.16"
 
 # Sibling schemas this contract references — pack metadata and the
 # per-pack Claude-plugin manifest. Defined by spec AC #3 + #4.

{agentbundle-0.6.0 → agentbundle-0.7.0}/agentbundle/_data/pack.schema.json

@@ -131,6 +131,25 @@
             "type": "string",
             "pattern": "^[^/].*"
           }
+        },
+        "layout": {
+          "type": "object",
+          "properties": {
+            "repo": {
+              "type": "object",
+              "properties": {
+                "parent": {"type": "string"},
+                "template": {"type": "string"}
+              }
+            },
+            "user": {
+              "type": "object",
+              "properties": {
+                "parent": {"type": "string"},
+                "template": {"type": "string"}
+              }
+            }
+          }
         }
       },
       "if": {

{agentbundle-0.6.0 → agentbundle-0.7.0}/agentbundle/build/tests/test_adapter_cursor.py

@@ -53,10 +53,11 @@ class CursorContractTests(unittest.TestCase):
     def test_contract_version_is_0_11(self) -> None:
         """AC1 — contract bumped to 0.11 by cursor-full-parity; subsequently
         0.12 (copilot-skills-and-web), 0.13 (docs/specs/gemini-full-parity),
-        0.14 (docs/specs/enriched-pack-manifest), then 0.15
-        (docs/specs/kiro-cli-agent-skill-resources).
+        0.14 (docs/specs/enriched-pack-manifest), 0.15
+        (docs/specs/kiro-cli-agent-skill-resources), then 0.16
+        (docs/specs/consolidated-pack-layout).
         Name preserved to keep the diff small."""
-        self.assertEqual(self.contract["contract"]["version"], "0.15")
+        self.assertEqual(self.contract["contract"]["version"], "0.16")
 
     def test_cursor_block_projects_five_primitives(self) -> None:
         """AC2 — the five standard primitives are in the projection array."""

{agentbundle-0.6.0 → agentbundle-0.7.0}/agentbundle/build/tests/test_adapter_gemini.py

@@ -151,9 +151,9 @@ class GeminiContractTests(unittest.TestCase):
         cls.contract = load_contract(CONTRACT_PATH)
 
     def test_contract_version_is_0_14(self) -> None:
-        """Contract version is 0.15 (docs/specs/kiro-cli-agent-skill-resources
-        bumped it from enriched-pack-manifest's 0.14). Name preserved."""
-        self.assertEqual(self.contract["contract"]["version"], "0.15")
+        """Contract version is 0.16 (docs/specs/consolidated-pack-layout
+        bumped it from kiro-cli-agent-skill-resources' 0.15). Name preserved."""
+        self.assertEqual(self.contract["contract"]["version"], "0.16")
 
     def test_gemini_block_projects_five_primitives(self) -> None:
         """AC2 — five standard primitives with their gemini targets."""

{agentbundle-0.6.0 → agentbundle-0.7.0}/agentbundle/build/tests/test_adapter_kiro_ide.py

@@ -172,13 +172,13 @@ class KiroIdeAdapterTests(unittest.TestCase):
         self.assertIn(".kiro.hook", target_repo)
 
     def test_contract_version_is_0_9(self) -> None:
-        """Contract version is 0.15 (docs/specs/kiro-cli-agent-skill-resources,
-        atop enriched-pack-manifest's 0.14 and gemini-full-parity's 0.13).
+        """Contract version is 0.16 (docs/specs/consolidated-pack-layout,
+        atop kiro-cli-agent-skill-resources' 0.15 and enriched-pack-manifest's 0.14).
         Name preserved to keep the diff small."""
         self.assertEqual(
             self.contract["contract"]["version"],
-            "0.15",
-            "adapter.toml [contract] version must be '0.15' after kiro-cli-agent-skill-resources",
+            "0.16",
+            "adapter.toml [contract] version must be '0.16' after consolidated-pack-layout",
         )
 
     def test_kiro_ide_hook_projects_with_flat_prefix_path(self) -> None:

{agentbundle-0.6.0 → agentbundle-0.7.0}/agentbundle/build/tests/test_contract.py

@@ -452,16 +452,16 @@ class ContractV05Tests(unittest.TestCase):
         self.schema = _load_schema()
 
     def test_contract_version_is_v05(self) -> None:
-        """tomllib.loads of adapter.toml returns contract.version == "0.15"
-        (bumped from enriched-pack-manifest's "0.14" by
-        docs/specs/kiro-cli-agent-skill-resources: kiro-cli agents inject a
-        skill-resources glob so headless `--agent` runs reach skills).
-        Class/method names preserved to avoid churn.
+        """tomllib.loads of adapter.toml returns contract.version == "0.16"
+        (bumped from kiro-cli-agent-skill-resources' "0.15" by
+        docs/specs/consolidated-pack-layout: pack.toml gains an optional
+        scope-keyed [pack.layout] table). Class/method names preserved to
+        avoid churn.
         """
         self.assertEqual(
             self.contract["contract"]["version"],
-            "0.15",
-            "adapter.toml [contract] version must be '0.15' after kiro-cli-agent-skill-resources",
+            "0.16",
+            "adapter.toml [contract] version must be '0.16' after consolidated-pack-layout",
         )
 
     def test_claude_code_install_routes_includes_apm(self) -> None:

{agentbundle-0.6.0 → agentbundle-0.7.0}/agentbundle/build/tests/test_pack_schema.py

@@ -399,6 +399,85 @@ description = "Core skills."
         self.assertEqual(errors, [], "\n".join(errors))
 
 
+class PackSchemaLayoutTests(unittest.TestCase):
+    """consolidated-pack-layout T1: optional scope-keyed [pack.layout] table.
+
+    pack.schema.json gains an optional `[pack.layout]` table with optional
+    `.repo` / `.user` sub-tables, each carrying a `parent` base and/or a
+    within-pack `template` path. Every field is optional and the change is
+    additive — a manifest omitting it must still validate (legacy invariance),
+    and a pack may declare only `.repo` (the three current consumers do, since
+    their output is per-repo and they have no sensible absolute user default).
+    """
+
+    def test_accepts_layout_with_repo_and_user(self) -> None:
+        """A manifest carrying [pack.layout.repo] and [pack.layout.user] validates."""
+        from agentbundle.build.validate import validate
+
+        schema = _load_schema()
+        toml_text = """
+[pack]
+name = "research"
+version = "0.5.0"
+
+[pack.layout.repo]
+parent = ".context/research"
+
+[pack.layout.user]
+parent = "~/research-projects"
+template = "references/agentbundle-layout.toml"
+"""
+        instance = _parse_toml(toml_text)
+        errors = validate(instance, schema)
+        self.assertEqual(errors, [], "\n".join(errors))
+
+    def test_accepts_layout_repo_only(self) -> None:
+        """A pack may declare only [pack.layout.repo] — the consumer shape."""
+        from agentbundle.build.validate import validate
+
+        schema = _load_schema()
+        toml_text = """
+[pack]
+name = "product-engineering"
+version = "0.5.0"
+
+[pack.layout.repo]
+parent = "docs/product"
+"""
+        instance = _parse_toml(toml_text)
+        errors = validate(instance, schema)
+        self.assertEqual(errors, [], "\n".join(errors))
+
+    def test_accepts_manifest_omitting_layout(self) -> None:
+        """Optionality: a manifest with no [pack.layout] validates (legacy invariance)."""
+        from agentbundle.build.validate import validate
+
+        schema = _load_schema()
+        toml_text = """
+[pack]
+name = "core"
+version = "0.4.0"
+"""
+        instance = _parse_toml(toml_text)
+        errors = validate(instance, schema)
+        self.assertEqual(errors, [], "\n".join(errors))
+
+    def test_rejects_non_string_parent(self) -> None:
+        """[pack.layout.repo].parent must be a string; a non-string is rejected."""
+        from agentbundle.build.validate import validate
+
+        schema = _load_schema()
+        instance = {
+            "pack": {
+                "name": "core",
+                "version": "0.1.0",
+                "layout": {"repo": {"parent": 42}},
+            }
+        }
+        errors = validate(instance, schema)
+        self.assertTrue(errors, "schema accepted a non-string layout.repo.parent")
+
+
 class PackSchemaLoadsTests(unittest.TestCase):
     """Smoke test: the schema file loads and has the expected top-level shape."""
 

{agentbundle-0.6.0 → agentbundle-0.7.0}/agentbundle/cli.py

@@ -1,4 +1,4 @@
-"""`agentbundle` CLI dispatcher — argparse over the eleven F-cli subcommands.
+"""`agentbundle` CLI dispatcher — argparse over the F-cli subcommands.
 
 Subcommand order on the parser matches the canonical install-workflow order
 from the spec (discovery-first): `list-packs`, `list-profiles`, `list-targets`,
@@ -11,9 +11,12 @@ Each subcommand's `run(args) -> int` lives under `agentbundle.commands.*`;
 this module wires `argparse` and prints `--version`. No business logic here.
 
 RFC-0004 surface additions:
-  - `--scope {repo,user}` on install, uninstall, upgrade, diff, init-state,
-    list-targets (the six subcommands enumerated in spec § *Install-scope
-    dimension*).
+  - `--scope {repo,user}` on install, uninstall, upgrade, diff, init-state
+    (the spec § *Install-scope dimension* subcommands). The original RFC-0004
+    set also listed `list-targets`, and `reconcile` carried a single-value
+    `--scope user`; both were dead (parsed-but-never-read / only-legal-value-
+    equals-default) and dropped in the CLI-hygiene sweep, so passing `--scope`
+    to either now surfaces `unknown flag for <verb>: --scope`.
   - `--force` on install only (cross-scope conflict bypass; see
     spec § *Dual-scope install conflict*).
   - Forbidden flags on the five excluded subcommands surface with the
@@ -202,12 +205,11 @@ def _build_parser() -> argparse.ArgumentParser:
     sp.add_argument("catalogue", help="Catalogue URI (local path or git+https://...).")
     sp.set_defaults(func=_lazy("list_profiles"))
 
-    # --- list-targets --- (--scope as read-only filter)
+    # --- list-targets --- (no flags; queries the adapter registry)
     sp = subparsers.add_parser(
         "list-targets",
         help="List adapter targets the CLI supports (claude-code, kiro-ide, kiro-cli, kiro (deprecated → kiro-ide), copilot, codex).",
     )
-    sp.add_argument("--scope", choices=("repo", "user"))
     sp.set_defaults(func=_lazy("list_targets"))
 
     # --- scaffold --- (no --scope; always repo-targeted)
@@ -309,6 +311,17 @@ def _build_parser() -> argparse.ArgumentParser:
             "successful preview, even with Tier-2 collisions present."
         ),
     )
+    sp.add_argument(
+        "--yes",
+        action="store_true",
+        help=(
+            "Answer yes to install's interactive confirmations: the --force "
+            "destructive-cleanup prompt (removing leftover files), and the "
+            "offer to upgrade a pack already installed at the requested scope. "
+            "Required for non-interactive use of those paths; without it they "
+            "prompt on a TTY and refuse rather than block on a non-TTY."
+        ),
+    )
     sp.set_defaults(func=_lazy("install"))
 
     # --- validate --- (no --scope; schema + rails A/B/C)
@@ -374,15 +387,28 @@ def _build_parser() -> argparse.ArgumentParser:
         help="Upgrade a pack or a single primitive within a pack.",
     )
     sp.add_argument("--pack", required=True)
-    sp.add_argument("--to", required=True, dest="to_version", help="Target pack version.")
-    sp.add_argument("--skill")
-    sp.add_argument("--agent")
-    sp.add_argument("--hook")
-    sp.add_argument("--seed")
-    sp.add_argument("--command")
+    # 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
+    # than silently upgrading only the first.
+    prim_group = sp.add_mutually_exclusive_group()
+    prim_group.add_argument("--skill")
+    prim_group.add_argument("--agent")
+    prim_group.add_argument("--hook")
+    prim_group.add_argument("--seed")
+    prim_group.add_argument("--command")
     sp.add_argument("catalogue", help="Catalogue URI to fetch the new version from.")
     sp.add_argument("--root", default=".")
     sp.add_argument("--scope", choices=("repo", "user"))
+    sp.add_argument(
+        "--yes",
+        action="store_true",
+        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."
+        ),
+    )
     sp.add_argument(
         "--dry-run",
         action="store_true",
@@ -402,6 +428,24 @@ def _build_parser() -> argparse.ArgumentParser:
     sp.add_argument("--pack", required=True)
     sp.add_argument("--root", default=".")
     sp.add_argument("--scope", choices=("repo", "user"))
+    sp.add_argument(
+        "--yes",
+        action="store_true",
+        help=(
+            "Skip the uninstall confirmation prompt. Required for non-interactive "
+            "use (CI, pipes); without it the uninstall asks before removing any "
+            "file, and refuses rather than blocking when stdin is not a TTY."
+        ),
+    )
+    sp.add_argument(
+        "--dry-run",
+        action="store_true",
+        help=(
+            "Preview the per-file plan (remove tier-1 / keep tier-2) without "
+            "removing anything — no file removed, no hook-wiring unproject, no "
+            "state change. Exits 0."
+        ),
+    )
     sp.set_defaults(func=_lazy("uninstall"))
 
     # --- init-state --- (--scope selector; --migrate flag)
@@ -453,10 +497,9 @@ def _build_parser() -> argparse.ArgumentParser:
             "RFC-0005: read-only orphan reporter — walks Claude Code "
             "settings.json and Kiro agent JSONs named in user-scope state, "
             "reports entries the file/state pair disagrees on. Read-only; "
-            "no --apply flag."
+            "no --apply flag. User-scope only; no --scope flag."
         ),
     )
-    sp.add_argument("--scope", choices=("user",), default="user")
     sp.set_defaults(func=_lazy("reconcile"))
 
     return parser

{agentbundle-0.6.0 → agentbundle-0.7.0}/agentbundle/commands/_common.py

@@ -243,3 +243,51 @@ def summarize_plan(actions: list[str]) -> str:
     ]
     body = ", ".join(parts) if parts else "no files"
     return f"dry-run: {len(actions)} file(s) — {body}. Nothing written."
+
+
+# ---------------------------------------------------------------------------
+# Destructive-confirmation mechanics (shared by `uninstall`, `install --force`,
+# the `install`→`upgrade` offer, and `upgrade`)
+# ---------------------------------------------------------------------------
+
+
+def confirm_or_refuse(
+    *,
+    yes: bool,
+    question: str,
+    refuse_message: str,
+    abort_message: str,
+) -> bool:
+    """Decide whether a destructive command may proceed.
+
+    The single home for the confirm / non-TTY-refuse / ``--yes`` mechanics first
+    introduced for ``upgrade`` in PR #374, so ``uninstall``, ``install --force``,
+    and the ``install``→``upgrade`` offer share one implementation:
+
+      - ``yes`` (the ``--yes`` flag) → return ``True`` without touching stdin.
+      - non-interactive stdin (``not sys.stdin.isatty()``) → print
+        ``refuse_message`` to stderr and return ``False`` (never block on
+        ``input()``).
+      - interactive stdin → prompt with ``question``; return ``True`` only when
+        the reply is ``y``/``yes`` (case-insensitive, stripped). Any other reply
+        — including EOF — prints ``abort_message`` to stderr and returns
+        ``False``.
+
+    The caller owns the ``--dry-run`` short-circuit (a dry run writes nothing, so
+    it must return *before* calling this), and owns every command-specific
+    message string passed in here — so each call site preserves its own exact
+    stderr contract.
+    """
+    if yes:
+        return True
+    if not sys.stdin.isatty():
+        print(refuse_message, file=sys.stderr)
+        return False
+    try:
+        reply = input(question)
+    except EOFError:
+        reply = ""
+    if reply.strip().lower() not in ("y", "yes"):
+        print(abort_message, file=sys.stderr)
+        return False
+    return True