fix(pack): fold zip archive review followups

Co-authored-by: nadav-y <nadav-y@users.noreply.github.com>

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: danielmeppiel

CHANGELOG.md

@@ -18,20 +18,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   unrelated config keys and refusing to overwrite a malformed file). `HERMES_HOME`
   overrides the Hermes home directory. See the [Hermes integration guide](https://microsoft.github.io/apm/integrations/hermes/).
 - Enterprise bootstrap mirror mode lets `install.sh`, `install.ps1`, and `apm self-update` use internal release, installer, and PyPI mirrors with fail-closed public fallback, and closes #1680. (#1733)
-
 - `apm pack --archive-format [zip|tar.gz]` escape hatch (default `zip`) lets
   CI pipelines that depended on the previous `.tar.gz` default opt back in without
   changing the project default. Passing `--archive-format` without `--archive` is
   now a `UsageError`. (#1720)
 
 ### Changed
 
-- `apm pack --archive` now produces `.zip` by default instead of `.tar.gz`. ZIP is
-  natively extractable on Windows without WSL or a tar binary, and matches the format
-  produced by `apm publish` and expected by Claude Code and plugin hosts.
-  ZIP archives are typically 30-130% larger than `.tar.gz` for text-heavy skill
-  bundles due to per-file compression; use `--archive-format tar.gz` if archive size
-  is a priority. (#1720)
+- **BREAKING:** `apm pack --archive` now produces `.zip` by default instead of `.tar.gz`, matching the format produced by `apm publish` and expected by Claude Code and plugin hosts while staying natively extractable on Windows without WSL or a tar binary. Note: ZIP archives are typically 30-130% larger than `.tar.gz` for text-heavy skill bundles due to per-file compression; use `--archive-format tar.gz` if archive size is a priority. (#1720)
 
 ### Fixed
 

docs/src/content/docs/consumer/deploy-a-bundle.md

@@ -1,15 +1,15 @@
 ---
 title: Deploy a local bundle
-description: Install a plugin-format bundle from a directory or tarball without touching apm.yml.
+description: Install a plugin-format bundle from a directory or archive without touching apm.yml.
 ---
 
-You have a bundle on disk -- a directory or `.tar.gz` someone handed you, or
-the output of `apm pack --format plugin`. Drop it into a project with one
-command:
+You have a bundle on disk -- a directory or `.zip` someone handed you (or a
+legacy `.tar.gz`), or the output of `apm pack --format plugin`. Drop it into a
+project with one command:
 
 ```bash
 apm install ./path/to/bundle
-apm install ./dist/my-pkg-1.0.0.tar.gz
+apm install ./dist/my-pkg-1.0.0.zip
 ```
 
 This is a sibling flow to [Install packages](../install-packages/). Instead
@@ -19,8 +19,8 @@ the install is imperative, like `dpkg -i` next to `apt install`.
 
 ## What counts as a bundle
 
-A plugin-format bundle is a directory (or gzipped tarball of one) with a
-`plugin.json` at the root and primitive folders alongside it:
+A plugin-format bundle is a directory, zip archive, or legacy gzipped tarball
+with a `plugin.json` at the root and primitive folders alongside it:
 
 ```
 my-bundle/
@@ -44,16 +44,16 @@ warns and proceeds.
 ## How the install works
 
 ```
-$ apm install ./dist/my-pkg-1.0.0.tar.gz --target copilot
-[>] Installing local bundle from ./dist/my-pkg-1.0.0.tar.gz
+$ apm install ./dist/my-pkg-1.0.0.zip --target copilot
+[>] Installing local bundle from ./dist/my-pkg-1.0.0.zip
 [+] Bundle integrity verified
 [+] Deployed 7 files to .github/
 ```
 
 Steps APM runs:
 
 1. **Detect.** Path exists and contains `plugin.json` at the bundle root
-   (tarballs are extracted to a temp directory first).
+   (zip archives and legacy tarballs are extracted to a temp directory first).
 2. **Verify integrity.** Hash every file listed in `pack.bundle_files`;
    reject any symlink, hash mismatch, or unlisted file.
 3. **Deploy.** Map `agents/`, `skills/`, `commands/`, `hooks/` into the

docs/src/content/docs/consumer/index.md

@@ -18,7 +18,7 @@ You're here because you want to install someone else's APM packages and use them
 | You manage `apm.yml` and need lockfile / dependency commands                   | [Manage dependencies](./manage-dependencies/)           |
 | You want APM to wire MCP servers (GitHub, Atlassian, ...) into your tools      | [Install MCP servers](./install-mcp-servers/)           |
 | You want APM to wire LSP servers into supported runtimes                       | [Install LSP servers](./install-lsp-servers/)           |
-| You received a local `.tar.gz` bundle and need to install it                   | [Deploy a local bundle](./deploy-a-bundle/)             |
+| You received a local `.zip` or `.tar.gz` bundle and need to install it         | [Deploy a local bundle](./deploy-a-bundle/)             |
 | You hit `Drift detected` after a `git pull`                                    | [Drift and secure-by-default](./drift-and-secure-by-default/) |
 | Your org rolled out `apm-policy.yml` and your install is now blocked           | [Governance on the consumer ramp](./governance-on-the-consumer-ramp/) |
 

docs/src/content/docs/integrations/ci-cd.md

@@ -208,6 +208,7 @@ The APM bundle layout below assumes the upstream job ran `apm-action@v1` with `p
 - uses: actions/download-artifact@v4
   with:
     name: agent-config
+# Migrating from .tar.gz? Add --archive-format tar.gz to the apm pack step above.
 - run: unzip -o build/*.zip -d ./
 ```
 

docs/src/content/docs/producer/index.md

@@ -18,7 +18,7 @@ Five steps, in order. Each links to the page that owns it:
 | 1 | [Author primitives](./author-primitives/) | Skills, prompts, instructions, agents, hooks, commands, MCP under `.apm/`        |
 | 2 | [Compile your package](./compile/)        | `apm compile` writes deterministic per-target output you can git-diff            |
 | 3 | [Preview and validate](./preview-and-validate/) | `apm preview` and `apm view` confirm what consumers will receive                 |
-| 4 | [Pack a bundle](./pack-a-bundle/)         | `apm pack` produces a bundle you can ship offline or to a marketplace         |
+| 4 | [Pack a bundle](./pack-a-bundle/)         | `apm pack` produces a `.zip` you can ship offline or to a marketplace        |
 | 5 | [Publish to a marketplace](./publish-to-a-marketplace/) | Others install your package with `apm install <owner>/<repo>`                  |
 
 You don't need a marketplace to start. Step 4 is enough for internal teams; the marketplace step is for public discovery.

docs/src/content/docs/producer/pack-a-bundle.md

@@ -45,7 +45,8 @@ $ apm pack
 
 Add `--archive` to get a single archive (`.zip` by default; use `--archive-format tar.gz`
 for legacy CI pipelines) instead of a directory; use `-o` to change the output location
-(default `./build`).
+(default `./build`). ZIP archives are natively extractable on Windows -- no WSL,
+tar, or additional tooling required.
 
 ```bash
 apm pack --archive -o ./dist

docs/src/content/docs/producer/releasing-from-any-ci.md

@@ -85,7 +85,7 @@ you need to customise any step.
 > **Reference deployment.** [`DevExpGbb/zava-agent-config`](https://github.com/DevExpGbb/zava-agent-config)
 > runs this exact pipeline. The
 > [v6.1.2 release](https://github.com/DevExpGbb/zava-agent-config/releases/tag/v6.1.2)
-> attaches 7 per-plugin tarballs + their `.sha256` companions +
+> attaches 7 per-plugin bundles + their `.sha256` companions +
 > `marketplace-6.1.2.json` (15 assets total) via the workflow in
 > [`.github/workflows/release.yml`](https://github.com/DevExpGbb/zava-agent-config/blob/main/.github/workflows/release.yml).
 > APM `0.16.0` and apm-action `v1.9.1` or newer required.

docs/src/content/docs/reference/cli/pack.md

@@ -29,8 +29,8 @@ Bundles are target-agnostic. The consumer's project decides where files land at
 | Flag | Default | Description |
 |---|---|---|
 | `--format plugin\|apm` | `plugin` | Bundle format. `plugin` emits a Claude Code plugin directory with `plugin.json` and plugin-native subdirs (`agents/`, `skills/`, `commands/`, `instructions/`, `hooks/`). `apm` emits the legacy APM bundle layout, kept for tooling that still consumes it (e.g. `microsoft/apm-action@v1` restore mode). |
-| `--archive` | off | Produce a `.zip` archive instead of a directory (use `--archive-format tar.gz` for legacy CI pipelines). Bundle only. |
-| `--archive-format zip\|tar.gz` | `zip` | Archive format when `--archive` is set. `zip` is natively extractable on Windows and matches the format expected by Claude Code and plugin hosts. `tar.gz` preserves the previous default for pipelines that depend on it. |
+| `--archive` | off | Produce a `.zip` archive instead of a directory (changed from `.tar.gz`; use `--archive-format tar.gz` for legacy CI pipelines). Bundle only. |
+| `--archive-format zip\|tar.gz` | `zip` | Archive format when `--archive` is set. `zip` is natively extractable on Windows and matches the format expected by Claude Code and plugin hosts. `tar.gz` is typically smaller for text-heavy bundles and preserves the previous default for pipelines that depend on it. |
 | `-o`, `--output PATH` | `./build` | Bundle output directory. Does not affect the `marketplace.json` path. |
 | `--force` | off | Allow overwriting on collision. In `plugin` bundle format, last writer wins instead of first; for generated `plugin.json` manifests, overwrites an existing file instead of preserving it. |
 | `--dry-run` | off | Print what would be packed without writing anything. |

packages/apm-guide/.apm/skills/apm-usage/commands.md

@@ -80,7 +80,7 @@ When `apm install` has already deployed instructions to `.claude/rules/`, `apm c
 
 | Command | Purpose | Key flags |
 |---------|---------|-----------|
-| `apm pack` | Build distributable artifacts (bundle and/or marketplace.json -- driven by `apm.yml`). Default output is a Claude Code plugin directory. Bundles are **target-agnostic**: `pack.target` is recorded in every bundle for diagnostic purposes (typically `"all"` for target-agnostic packs, or the project's detected target) and is not authoritative at install time; `pack.bundle_files` (path -> sha256) drives integrity verification. The consumer's project decides where files land. Marketplace-publishing projects (`marketplace:` block, no `dependencies:`) no longer emit the misleading "No plugin.json found" warning; after a successful build, a vendor-neutral catalog of artifact paths is appended together with a single docs pointer (`producer/publish-to-a-marketplace/#consume-from-any-assistant`) listing per-assistant install paths. Release-time gates `--check-versions` and `--check-clean` are opt-in: when present, they run after the build and exit non-zero on misalignment / drift (codes 3 and 4 respectively) so release pipelines can fail fast. When `apm.yml` declares `target: claude` or `target: copilot` (or the plural `targets:` equivalent), `apm pack` also generates an ecosystem-specific `plugin.json`: `.claude-plugin/plugin.json` for Claude (includes `mcpServers` from `.mcp.json` if present) and `.github/plugin/plugin.json` for Copilot (omits `mcpServers`). An existing file at the target path is preserved (a warning is emitted and the write is skipped) unless `--force` is passed; `--dry-run` prevents writes. Credential-bearing keys and secret-shaped values in `.mcp.json` are stripped recursively at any depth from the Claude manifest before writing, so a committed manifest never leaks secrets (see the apm pack reference, `reference/cli/pack/#credential-stripping-claude-mcpservers`). | `-o PATH`, `--archive` (produce an archive instead of a directory), `--archive-format [zip\|tar.gz]` (default `zip`; only active with `--archive`), `--dry-run`, `--format [plugin\|apm]` (default `plugin`), `--force`, `--offline`, `--include-prerelease`, `--marketplace=FORMATS`, `--marketplace-path FORMAT=PATH`, `--json`, `--check-versions` (release gate: per-package versions match `marketplace.versioning.strategy`; exit 3 on failure), `--check-clean` (release gate: regenerate-and-diff against the committed `marketplace.json`; exit 4 on drift). `-t/--target` is **deprecated** (warn only). Exit codes: `0` success, `1` build/runtime error, `2` schema validation error, `3` `--check-versions` misalignment, `4` `--check-clean` drift. |
+| `apm pack` | Build distributable artifacts (bundle and/or marketplace.json -- driven by `apm.yml`). Default output is a Claude Code plugin directory. Bundles are **target-agnostic**: `pack.target` is recorded in every bundle for diagnostic purposes (typically `"all"` for target-agnostic packs, or the project's detected target) and is not authoritative at install time; `pack.bundle_files` (path -> sha256) drives integrity verification. The consumer's project decides where files land. Marketplace-publishing projects (`marketplace:` block, no `dependencies:`) no longer emit the misleading "No plugin.json found" warning; after a successful build, a vendor-neutral catalog of artifact paths is appended together with a single docs pointer (`producer/publish-to-a-marketplace/#consume-from-any-assistant`) listing per-assistant install paths. Release-time gates `--check-versions` and `--check-clean` are opt-in: when present, they run after the build and exit non-zero on misalignment / drift (codes 3 and 4 respectively) so release pipelines can fail fast. When `apm.yml` declares `target: claude` or `target: copilot` (or the plural `targets:` equivalent), `apm pack` also generates an ecosystem-specific `plugin.json`: `.claude-plugin/plugin.json` for Claude (includes `mcpServers` from `.mcp.json` if present) and `.github/plugin/plugin.json` for Copilot (omits `mcpServers`). An existing file at the target path is preserved (a warning is emitted and the write is skipped) unless `--force` is passed; `--dry-run` prevents writes. Credential-bearing keys and secret-shaped values in `.mcp.json` are stripped recursively at any depth from the Claude manifest before writing, so a committed manifest never leaks secrets (see the apm pack reference, `reference/cli/pack/#credential-stripping-claude-mcpservers`). | `-o PATH`, `--archive` (produce a `.zip` archive instead of a directory; changed from `.tar.gz`), `--archive-format [zip\|tar.gz]` (default `zip`; use `tar.gz` for smaller legacy CI artifacts; only active with `--archive`), `--dry-run`, `--format [plugin\|apm]` (default `plugin`), `--force`, `--offline`, `--include-prerelease`, `--marketplace=FORMATS`, `--marketplace-path FORMAT=PATH`, `--json`, `--check-versions` (release gate: per-package versions match `marketplace.versioning.strategy`; exit 3 on failure), `--check-clean` (release gate: regenerate-and-diff against the committed `marketplace.json`; exit 4 on drift). `-t/--target` is **deprecated** (warn only). Exit codes: `0` success, `1` build/runtime error, `2` schema validation error, `3` `--check-versions` misalignment, `4` `--check-clean` drift. |
 | `apm unpack BUNDLE` | **[Deprecated]** Extract a bundle. Use `apm install <bundle-path>` instead -- it deploys directly with integrity verification and target resolution. | `-o PATH`, `--skip-verify`, `--force`, `--dry-run` |
 
 `apm install <BUNDLE-PATH>` -- when the positional argument resolves to a directory containing `plugin.json` at its root, or to a `.zip` (or legacy `.tar.gz`/`.tgz`) archive whose extracted root contains `plugin.json`, install switches to local-bundle mode: the bundle is integrity-verified against its embedded `apm.lock.yaml` (`pack.bundle_files`) and deployed into the consumer's resolved target. Target resolution follows the same precedence as registry installs (`--target` > `apm.yml` > directory detection); the bundle itself carries no target binding. Compile-only targets (opencode, codex, gemini) receive instructions staged under `apm_modules/<slug>/.apm/instructions/` and the install emits a hint to run `apm compile` to merge them. Other existing paths (e.g. a source-package directory without `plugin.json`) still flow through the normal local-path dependency-resolver pipeline. Files are recorded under `local_deployed_files` in the project lockfile -- `apm.yml` is **never** mutated. Honours `--target`, `--global`, `--force`, `--dry-run`, `--verbose`, plus `--as ALIAS` (log/display label only). Resolver/MCP/registry/policy flags (`--update`, `--mcp`, `--parallel-downloads`, `--allow-insecure-host`, `--skill`, ...) are rejected with a single consolidated error -- local-bundle install is an imperative deploy and bypasses those subsystems.

src/apm_cli/bundle/local_bundle.py

@@ -37,14 +37,15 @@
 
 import yaml
 
+from ..utils.archive import MAX_ZIP_ENTRIES, MAX_ZIP_UNCOMPRESSED, safe_extract_zip
 from ..utils.path_security import (
     PathTraversalError,
     ensure_path_within,
     validate_path_segments,
 )
 
-_MAX_ZIP_ENTRIES = 10_000
-_MAX_ZIP_UNCOMPRESSED = 512 * 1024 * 1024  # 512 MB
+_MAX_ZIP_ENTRIES = MAX_ZIP_ENTRIES
+_MAX_ZIP_UNCOMPRESSED = MAX_ZIP_UNCOMPRESSED
 
 
 @dataclass(frozen=True)
@@ -204,44 +205,27 @@ def _find_extracted_root(extract_dir: Path) -> Path | None:
 def _extract_zip_bundle(path: Path) -> LocalBundleInfo | None:
     """Extract a ``.zip`` bundle to a temp dir and return :class:`LocalBundleInfo`.
 
-    Applies the same security checks as the tar.gz branch: rejects absolute
-    paths, path-traversal segments, and Unix symlink entries detected via
-    ``external_attr``.  Returns ``None`` on any validation failure or I/O
-    error so the caller can fall through to a generic error message.
+    Applies the same security checks as the tar.gz branch and enforces the ZIP
+    size quota while streaming each entry. Returns ``None`` only when the file
+    is not a readable ZIP bundle or no ``plugin.json`` root is found; security
+    violations raise ``ValueError`` with a targeted reason.
     """
     temp_dir = Path(tempfile.mkdtemp(prefix="apm-local-bundle-"))
     try:
         with zipfile.ZipFile(path, "r") as zf:
-            members = zf.infolist()
-            # ZIP bomb guard: reject suspiciously large or deep archives
-            if len(members) > _MAX_ZIP_ENTRIES:
-                shutil.rmtree(temp_dir, ignore_errors=True)
-                return None
-            if sum(m.file_size for m in members) > _MAX_ZIP_UNCOMPRESSED:
-                shutil.rmtree(temp_dir, ignore_errors=True)
-                return None
-            for member in members:
-                name = member.filename
-                if (
-                    name.startswith("/")
-                    or PureWindowsPath(name).drive
-                    or PureWindowsPath(name).is_absolute()
-                ):
-                    shutil.rmtree(temp_dir, ignore_errors=True)
-                    return None
-                try:
-                    validate_path_segments(name, context="zip member")
-                except PathTraversalError:
-                    shutil.rmtree(temp_dir, ignore_errors=True)
-                    return None
-                # Detect Unix symlinks stored in zip external_attr
-                if (member.external_attr >> 16) & 0o170000 == 0o120000:
-                    shutil.rmtree(temp_dir, ignore_errors=True)
-                    return None
-            zf.extractall(temp_dir)  # noqa: S202 -- validated above
+            safe_extract_zip(
+                zf,
+                temp_dir,
+                max_entries=_MAX_ZIP_ENTRIES,
+                max_uncompressed=_MAX_ZIP_UNCOMPRESSED,
+                error_type=ValueError,
+            )
     except (zipfile.BadZipFile, OSError):
         shutil.rmtree(temp_dir, ignore_errors=True)
         return None
+    except ValueError:
+        shutil.rmtree(temp_dir, ignore_errors=True)
+        raise
     bundle_root = _find_extracted_root(temp_dir)
     if bundle_root is None:
         shutil.rmtree(temp_dir, ignore_errors=True)