[tellaho]

Category: new-feature

User Impact: Plugin packages can include signed README content and a validated icon that remain intact through install, update, reload, and rollback.

Base: Targets main directly. It does not depend on #1145's discovery metadata, and can land independently of it.

Problem: API v1 plugin releases can currently carry only a manifest and executable module, so publishers cannot package conventional documentation or branding with the same integrity guarantees. Adding arbitrary asset paths would broaden the runtime and filesystem trust boundary.

Solution: Add optional, typed README.md, icon.png, and icon.jpg release content with strict byte and image bounds, cover it with the existing artifact hash and publisher signature, and expose content only through an integrity-checked on-demand read. Both icon formats can coexist and are returned independently so clients decide which to prefer. Existing { manifest, code } artifacts and plugin apiVersion: 1 remain compatible.

File changes

Cargo.lock
Locks the base64 and PNG-decoding dependencies used by release packaging and validation.

crates/plugin-manager/Cargo.toml
Adds narrowly configured base64, PNG, and JPEG support to the plugin manager.

crates/plugin-manager/src/imports.rs
Reads exact-name conventional assets from folder and Git previews, preserving captured bytes while enforcing file limits and rejecting optional-file symlinks consistently. Preview candidates expose only content revisions, not full asset payloads.

crates/plugin-manager/src/lib.rs
Extends the backward-compatible artifact envelope, validates README and PNG/JPEG content with explicit decoder allocation/dimension limits, preserves independent content revisions through lifecycle transitions, signs the complete package, and returns stored base64 icons through an integrity-checked native content read.

crates/plugin-manager/tests/management.rs
Covers missing assets, invalid UTF-8 and PNG/JPEG inputs, byte/dimension/pixel limits, signed tampering, update continuity, restart, on-demand reads, and rollback preservation, including both icon formats in one package.

docs/plugin-architecture.md
Documents the package contract, the reserved asset filenames and how to migrate existing source trees, compatibility behavior, size limits, the trust boundary, and requirements for safe rendering later. The native plugin_content command and its capability are deferred until a details surface consumes Manager::content.

src/app/PluginImport.test.tsx
Verifies that import previews disclose changed and removed package content without implying endorsement.

src/app/PluginImport.tsx
Shows README/icon presence or changes in the existing import review surface.

src/plugins/types.ts
Defines compact, symmetric PNG/JPEG content revisions. The native read is available for a future details surface; unused frontend adapters are deferred until that surface has a caller.

Reproduction steps

1. Build an API v1 plugin whose output folder contains manifest.json, plugin.js, and optional README.md, icon.png, and/or icon.jpg files.
2. Sign the folder with buzzodz plugin sign DIST_DIRECTORY; confirm the generated artifact changes when any optional file changes.
3. In desktop Settings → Plugins, load the folder and select the candidate; confirm the preview reports each packaged file and states that inclusion is not a Buzz endorsement.
4. Install the plugin, change an optional file, sign again with the same publisher, and load the update; confirm the preview identifies changed, added, or removed package content before installation.
5. Disable and reload a folder install or roll back an update; confirm the package content revision follows the selected executable revision.

Validation

• At 396987be83dd81d7cc6bc865b2ae25302d689bd6: cargo test -p buzzodz-plugins — 55 tests passed; import-preview tests — 15 passed; TypeScript and mandatory commit/push hooks passed.
• Compressed-profile regression: a 1×1 PNG carries a compressed 32 MiB iCCP profile. The decoder discards the over-budget profile; removing the allocation limit makes the test fail, restoring it passes.

Compatibility and validation limits

Old { manifest, code } artifacts remain supported. New asset-bearing artifacts and registry entries require a supporting host; older hosts reject unknown fields, so downgrading after installing them is unsupported. Absent revision fields are omitted from the registry. PNG/JPEG revisions compare canonical encoded content without extra decoding.

The 16 MiB allocation budget applies before header parsing and decode; it is not a total-process memory quota. Validation checks the first image; later animation frames and trailing bytes are not certified. Publisher content remains inert package data. Princess Donut reviewed 24150cf69; the repairs at 396987be8 have not received a separate independent review.

Screenshots / demos

Not included: external plugin import is a native desktop-only flow that requires the real OS folder picker; the browser host deliberately has no import capability. This change does not add a mock or fixture-only capture path, and no automated real-Tauri screenshot path exists in this checkout.

This remains a draft: the repository's human desktop verification and review-completion marker have not been claimed.

[tellaho]

🤖 Carl, AI coding agent — review and repair record.

Princess Donut independently reviewed bbfe13366..24150cf69 at the author's request. She read the full feature diff and ran standalone image-validator probes; she did not run the PR suites or desktop app.

The blocking finding was memory exhaustion during icon preview: compressed PNG metadata could expand before the dimension check. Fixed in 396987be83dd81d7cc6bc865b2ae25302d689bd6 with one reader configured before header parsing for dimension limits and a 16 MiB decoder allocation budget. A generated 1×1 PNG with a compressed 32 MiB iCCP profile verifies that over-budget optional metadata is discarded; removing the allocation limit makes this regression fail, and restoring it passes. This budget is a decoder limit, not a claim about total process RSS.

Also addressed: return stored base64 icon strings over IPC; use symmetric PNG/JPEG revision names; parse each validated release once and avoid repeated base64 decoding for revision comparisons; omit absent registry fields; enforce exact conventional asset names and reject optional-file symlinks consistently in folder/Git imports; hide empty package-content previews; remove frontend read adapters that had no caller.

Disposition of optional concerns: documented that validation covers the first image and permits trailing bytes; animation-frame/container strictness remains outside this packaging change. Documented downgrade limits for packages/registry entries containing new fields. Signing already rejected file symlinks at the reviewed base (read_limited checks symlink_metadata and uses O_NOFOLLOW on Unix), so this is preserved behavior rather than a newly stricter signing policy.

Validation at repair commit: cargo test -p buzzodz-plugins (55 tests), pnpm exec vitest run src/app/PluginImport.test.tsx (15 tests), TypeScript, and mandatory commit/push hooks passed.

The repair commit has not received a separate independent review. The PR remains draft; real desktop capture and human acceptance remain outstanding. This record does not claim final-head approval or buzz-review-completed.

[tellaho]

🤖 Posted by Princess Donut (AI agent) on Taylor's behalf.

• Rebased onto main. The three existing commits were moved onto main @ 0201b54c4. The patches are unchanged; git range-diff shows = for each.
• Repair re-review. The memory blocker is fixed: icon decoding is now limited before the header is parsed. Findings 1–7 are resolved, with no new blockers.
• New commit 9ac879fd7. The signed-envelope asset fields are now camelCase (iconPng/iconJpg), matching the manifest, registry and IPC naming before the format ships. Legacy { manifest, code } artifacts are unaffected.
• Checks at 9ac879fd7. cargo test -p buzzodz-plugins passed (54 tests), along with the pre-push hooks (types/unit tests, design-system, clippy, push-org).
• CLI run against a throwaway home directory:
  • Install, update and rollback each recorded the matching README/icon revisions.
  • Removing an icon dropped its field from registry.json.
  • A tampered artifact was refused.
  • A 907 KiB PNG carrying a ~900 MiB compressed colour profile installed with 80 MB peak memory.
  • A symlinked icon was rejected.
  • A lowercase readme.md was ignored.
• Not yet exercised: the desktop import-preview UI.

[kalvinnchau]

🤖 Two findings to resolve before approval. Native app-webview acceptance also remains unverified.

[kalvinnchau]

🤖 Approved. Previous findings are resolved; no new blocking defects found. Native asset import/reload workflows remain unverified.