feat(decisions): install from URL (Phase B)

`ai-config-kit decisions install <https-url> [--sha256 HEX] [--force]
[--dry-run]` fetches a gzip tarball, extracts it, validates the
manifest, and applies the pack the same way bundled packs are
applied.

Hardening:

- HTTPS-only (rejects http://, file://, anything else)
- 5MB size cap on the download body
- 30s socket timeout
- Optional sha256 verified BEFORE extraction
- Path-traversal guard: any tarball entry starting with `/` or
  containing `..` is refused before extract
- tarfile.extractall(filter="data") (3.12 safety filter)
- Tolerates "top-level dir wraps manifest" tarballs (common when
  GitHub serves a repo archive)

The remote pack reuses `_build_pack` + the same secret-pattern
preflight + per-file copy loop as `decisions_apply`. The CLI flow
mirrors `apply`'s output (written / overwritten / skipped lists).

Audit event `decisions_install` records (pack, url, sha256, force,
counts).

5 new tests (269 total):
- HTTP URL refused
- dry-run returns immediately
- end-to-end via mocked urlopen returning an in-memory tarball
- sha256 mismatch raises before extract
- path-traversal tarball entry rejected

CLI: `decisions install URL [--sha256 HEX] [--force] [--dry-run]`.
Library: `ClaudeConfig.decisions_install(url, sha256=None, force=False,
dry_run=False, max_bytes=5MB, timeout=30s)`.

Closes SPEC §4 Phase B.

Author: imanimanyara

src/ai_config_kit/cli.py

@@ -346,6 +346,28 @@ def _build_parser() -> argparse.ArgumentParser:
     )
     dec_sub = p_dec.add_subparsers(dest="decisions_cmd", required=True, metavar="ACTION")
     dec_sub.add_parser("list", help="Show all bundled packs.")
+
+    p_dec_install = dec_sub.add_parser(
+        "install",
+        help="Fetch + apply a decision pack from an HTTPS URL (.tar.gz).",
+    )
+    p_dec_install.add_argument("url", type=str, help="HTTPS URL of a .tar.gz pack.")
+    p_dec_install.add_argument(
+        "--sha256",
+        type=str,
+        default=None,
+        help="Hex-encoded sha256 of the tarball. Verified before extraction.",
+    )
+    p_dec_install.add_argument(
+        "--force",
+        action="store_true",
+        help="Overwrite existing files in the content dir.",
+    )
+    p_dec_install.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Print what would happen; do not fetch.",
+    )
     p_dec_show = dec_sub.add_parser("show", help="Print a pack's manifest + README.")
     p_dec_show.add_argument("name")
     p_dec_apply = dec_sub.add_parser(
@@ -724,6 +746,29 @@ def main(argv: list[str] | None = None) -> int:
                             print(f"    = {f}")
                 return 0
 
+            if args.decisions_cmd == "install":
+                inst_report = cfg.decisions_install(
+                    args.url,
+                    sha256=args.sha256,
+                    force=args.force,
+                    dry_run=args.dry_run,
+                )
+                print(inst_report.summary())
+                if not args.quiet and not inst_report.dry_run:
+                    if inst_report.written:
+                        print("  written:")
+                        for f in inst_report.written:
+                            print(f"    + {f}")
+                    if inst_report.overwritten:
+                        print("  overwritten:")
+                        for f in inst_report.overwritten:
+                            print(f"    ~ {f}")
+                    if inst_report.skipped:
+                        print("  skipped (already present; --force to overwrite):")
+                        for f in inst_report.skipped:
+                            print(f"    = {f}")
+                return 0
+
         if args.cmd == "reconcile":
             recon_report = cfg.reconcile(force_reapply=args.force)
             print(recon_report.summary())

src/ai_config_kit/manager.py

@@ -2864,6 +2864,159 @@ def decisions_list(self) -> DecisionsListReport:
             packs.append(self._build_pack(data, entry))
         return DecisionsListReport(packs=packs)
 
+    # ---- remote pack installation (Phase B) ---------------------------
+
+    def decisions_install(
+        self,
+        url: str,
+        sha256: str | None = None,
+        force: bool = False,
+        dry_run: bool = False,
+        max_bytes: int = 5 * 1024 * 1024,
+        timeout: float = 30.0,
+    ) -> DecisionsApplyReport:
+        """Fetch a decision pack from an HTTPS URL and apply it.
+
+        The URL must point at a gzip-compressed tarball whose root
+        contains a ``manifest.json`` in the standard pack schema. The
+        tarball is downloaded into a temp dir (size + tls-validated)
+        and extracted; the extracted tree is then treated as a one-off
+        pack-root and passed through the same ``decisions_apply``
+        path as a bundled pack.
+
+        @param url       HTTPS URL of the tarball.
+        @param sha256    optional hex digest. If given, the download is
+                         verified before extraction.
+        @param force     overwrite existing files in src_dir (default no).
+        @param dry_run   print what would happen; don't extract or write.
+        @param max_bytes hard cap on response body (default 5MB).
+        @param timeout   socket timeout (default 30s).
+        @return DecisionsApplyReport — same shape as a local-pack apply.
+        @raises ConfigError on http/ssl/integrity/manifest failures.
+        """
+        from urllib.parse import urlparse
+
+        parsed = urlparse(url)
+        if parsed.scheme != "https":
+            raise ConfigError(f"decisions install URL must be https://, got {parsed.scheme}://")
+        if not parsed.netloc:
+            raise ConfigError(f"decisions install URL has no host: {url!r}")
+
+        if dry_run:
+            return DecisionsApplyReport(pack=url, dry_run=True)
+
+        import io
+        import tarfile
+        import tempfile
+        import urllib.request
+
+        # Fetch
+        req = urllib.request.Request(url, headers={"User-Agent": "ai-config-kit"})
+        try:
+            with urllib.request.urlopen(req, timeout=timeout) as resp:
+                buf = resp.read(max_bytes + 1)
+        except (OSError, ValueError) as e:
+            raise ConfigError(f"decisions install: fetch failed: {e}") from e
+        if len(buf) > max_bytes:
+            raise ConfigError(
+                f"decisions install: response exceeds {max_bytes} bytes"
+            )
+
+        # SHA verify
+        if sha256:
+            got = hashlib.sha256(buf).hexdigest()
+            if got.lower() != sha256.lower():
+                raise ConfigError(
+                    f"decisions install: sha256 mismatch (expected {sha256}, got {got})"
+                )
+
+        # Extract to a temp dir; validate manifest at root.
+        with tempfile.TemporaryDirectory(prefix="ai-config-kit-pack-") as tmp:
+            tmp_root = Path(tmp)
+            try:
+                with tarfile.open(fileobj=io.BytesIO(buf), mode="r:gz") as tar:
+                    # Refuse paths that escape the extraction root.
+                    for member in tar.getmembers():
+                        if member.name.startswith("/") or ".." in Path(member.name).parts:
+                            raise ConfigError(
+                                f"decisions install: tarball entry escapes root: {member.name!r}"
+                            )
+                    tar.extractall(tmp_root, filter="data")
+            except tarfile.TarError as e:
+                raise ConfigError(f"decisions install: tar extract failed: {e}") from e
+
+            # Locate manifest. Either at the root, or one-level-down
+            # (common when tarballs include a top-level dir).
+            pack_root = tmp_root
+            if not (pack_root / "manifest.json").is_file():
+                children = [p for p in tmp_root.iterdir() if p.is_dir()]
+                if len(children) == 1 and (children[0] / "manifest.json").is_file():
+                    pack_root = children[0]
+                else:
+                    raise ConfigError(
+                        "decisions install: tarball does not contain manifest.json at root "
+                        "(or single top-level dir)"
+                    )
+
+            data = json.loads((pack_root / "manifest.json").read_text(encoding="utf-8"))
+            name = str(data.get("name", "")) or pack_root.name
+            self.src_dir.mkdir(parents=True, exist_ok=True)
+            pack = self._build_pack(data, pack_root)
+
+            # Pre-flight: refuse if any dest matches a secret pattern.
+            for f in pack.files:
+                if self._matches_secret(Path(f.dest).name):
+                    raise ConfigError(
+                        f"pack '{name}': dest '{f.dest}' matches a secret pattern; "
+                        "refusing to apply"
+                    )
+
+            written: list[str] = []
+            skipped: list[str] = []
+            overwritten: list[str] = []
+            for f in pack.files:
+                src = pack_root / f.src
+                if not src.is_file():
+                    raise ConfigError(f"pack '{name}': missing source file {f.src}")
+                target = self.src_dir / f.dest
+                exists = target.exists()
+                if exists and not force:
+                    skipped.append(f.dest)
+                    continue
+                target.parent.mkdir(parents=True, exist_ok=True)
+                target.write_bytes(src.read_bytes())
+                if f.mode is not None:
+                    try:
+                        mode_bits = int(f.mode, 8) & 0o7777
+                    except ValueError as e:
+                        raise ConfigError(
+                            f"pack '{name}': invalid mode '{f.mode}' for {f.dest}"
+                        ) from e
+                    with contextlib.suppress(OSError):
+                        target.chmod(mode_bits)
+                if exists:
+                    overwritten.append(f.dest)
+                else:
+                    written.append(f.dest)
+
+            self._audit(
+                "decisions_install",
+                pack=name,
+                url=url,
+                sha256=sha256 or "",
+                force=force,
+                written=len(written),
+                overwritten=len(overwritten),
+                skipped=len(skipped),
+            )
+            return DecisionsApplyReport(
+                pack=name,
+                written=written,
+                skipped=skipped,
+                overwritten=overwritten,
+                dry_run=False,
+            )
+
     def decisions_show(self, name: str) -> DecisionPack:
         """Return the manifest + file list for a single pack."""
         root = self._decisions_root()

tests/test_manager.py

@@ -934,6 +934,156 @@ def test_decisions_diff_unknown_pack_raises(cfg: ClaudeConfig) -> None:
         cfg.decisions_diff("does-not-exist")
 
 
+# --- remote packs (Phase B) ----------------------------------------------
+
+
+def _make_tarball(tmp_path: Path, manifest: dict, files: dict[str, str]) -> bytes:
+    """Build a gzip tarball with the given manifest + content files. Bytes only."""
+    import io
+    import json as _json
+    import tarfile
+
+    buf = io.BytesIO()
+    with tarfile.open(fileobj=buf, mode="w:gz") as tar:
+        manifest_bytes = _json.dumps(manifest).encode("utf-8")
+        m = tarfile.TarInfo(name="manifest.json")
+        m.size = len(manifest_bytes)
+        tar.addfile(m, io.BytesIO(manifest_bytes))
+        for src, content in files.items():
+            data = content.encode("utf-8")
+            info = tarfile.TarInfo(name=src)
+            info.size = len(data)
+            tar.addfile(info, io.BytesIO(data))
+    return buf.getvalue()
+
+
+def test_decisions_install_rejects_non_https(cfg: ClaudeConfig) -> None:
+    with pytest.raises(ConfigError, match="must be https"):
+        cfg.decisions_install("http://example.com/pack.tar.gz")
+
+
+def test_decisions_install_dry_run(cfg: ClaudeConfig) -> None:
+    r = cfg.decisions_install("https://example.com/pack.tar.gz", dry_run=True)
+    assert r.dry_run
+    assert "pack.tar.gz" in r.pack
+
+
+def test_decisions_install_e2e_via_local_url(
+    cfg: ClaudeConfig, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """End-to-end: mock urlopen to return a local tarball; verify files land."""
+    tarball = _make_tarball(
+        tmp_path,
+        manifest={
+            "name": "remote-test-pack",
+            "description": "test",
+            "version": "0.1.0",
+            "files": [{"src": "files/hello.md", "dest": "commands/hello.md"}],
+        },
+        files={"files/hello.md": "# hello\n"},
+    )
+
+    class _FakeResponse:
+        def __init__(self, payload: bytes) -> None:
+            self._payload = payload
+
+        def read(self, n: int) -> bytes:
+            return self._payload[:n]
+
+        def __enter__(self) -> _FakeResponse:
+            return self
+
+        def __exit__(self, *_a: object) -> None:
+            return None
+
+    def fake_urlopen(req, timeout=30.0):  # type: ignore[no-untyped-def]
+        return _FakeResponse(tarball)
+
+    monkeypatch.setattr("urllib.request.urlopen", fake_urlopen)
+
+    r = cfg.decisions_install("https://example.com/pack.tar.gz", force=False)
+    assert r.written == ["commands/hello.md"]
+    target = cfg.src_dir / "commands" / "hello.md"
+    assert target.read_text(encoding="utf-8") == "# hello\n"
+
+
+def test_decisions_install_sha256_mismatch(
+    cfg: ClaudeConfig, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """Wrong sha256 -> ConfigError before extraction."""
+    tarball = _make_tarball(
+        tmp_path,
+        manifest={
+            "name": "x",
+            "description": "x",
+            "version": "0.0.1",
+            "files": [],
+        },
+        files={},
+    )
+
+    class _Resp:
+        def __init__(self, payload: bytes) -> None:
+            self._p = payload
+
+        def read(self, n: int) -> bytes:
+            return self._p[:n]
+
+        def __enter__(self) -> _Resp:
+            return self
+
+        def __exit__(self, *_a: object) -> None:
+            return None
+
+    monkeypatch.setattr(
+        "urllib.request.urlopen",
+        lambda req, timeout=30.0: _Resp(tarball),
+    )
+    with pytest.raises(ConfigError, match="sha256 mismatch"):
+        cfg.decisions_install(
+            "https://example.com/pack.tar.gz", sha256="00" * 32
+        )
+
+
+def test_decisions_install_rejects_path_traversal(
+    cfg: ClaudeConfig, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """Tarball containing `../escape` entry is refused."""
+    import io
+    import json as _json
+    import tarfile
+
+    buf = io.BytesIO()
+    with tarfile.open(fileobj=buf, mode="w:gz") as tar:
+        m_bytes = _json.dumps({"name": "bad", "files": []}).encode("utf-8")
+        m = tarfile.TarInfo(name="manifest.json")
+        m.size = len(m_bytes)
+        tar.addfile(m, io.BytesIO(m_bytes))
+        bad = tarfile.TarInfo(name="../escape.md")
+        bad.size = 1
+        tar.addfile(bad, io.BytesIO(b"x"))
+
+    class _R:
+        def __init__(self, p: bytes) -> None:
+            self._p = p
+
+        def read(self, n: int) -> bytes:
+            return self._p[:n]
+
+        def __enter__(self) -> _R:
+            return self
+
+        def __exit__(self, *_a: object) -> None:
+            return None
+
+    monkeypatch.setattr(
+        "urllib.request.urlopen",
+        lambda req, timeout=30.0: _R(buf.getvalue()),
+    )
+    with pytest.raises(ConfigError, match="escapes root"):
+        cfg.decisions_install("https://example.com/bad.tar.gz")
+
+
 # --- memory hygiene (Phase C) --------------------------------------------