feat(catalog): extend plugin.json and signed catalog with capability metadata pilot

[xcv58]

Summary

Extend the existing per-plugin plugin.json source and signed Marketplace catalog so MacTools can describe plugin products and capabilities before installation.

The change should begin with a small representative pilot rather than migrating every official plugin at once. This issue defines and validates the metadata foundation. Rich Marketplace rendering is tracked separately in #308.

Motivation

The current catalog is primarily a package index. It answers:

• Which plugin package is available?
• Which version is current?
• Is it compatible with the host?
• Where can it be downloaded?
• Which broad UI surfaces does it support?
• Which permissions are declared?

It does not adequately answer:

• What user problems does the plugin solve?
• Which individual actions does it provide?
• Which MacTools surfaces can use those actions?
• Which applications, hardware, or executables are required?
• What data does the plugin read, store, or send?
• What setup occurs after installation?
• Which plugins and workflows complement it?
• Whether action entries are static or discovered from the local Mac

These omissions limit Marketplace details, pre-install search, onboarding, website generation, and recipe discovery.

Decision

Use the existing Plugins/<Plugin>/plugin.json as the single checked-in metadata source for each plugin. Do not introduce a required parallel marketplace.json.

The source manifest may contain optional product-oriented sections that:

• The runtime package loader may ignore
• The catalog generator validates and projects into the signed catalog
• The website generator uses at build time
• CI compares with installed runtime action definitions

Generated catalogs and website data may remain separate artifacts. The checked-in source remains singular.

---

Proposed Optional Sections

presentation

Product-facing information:

• Long description
• Short examples
• Screenshot asset references
• Documentation reference
• Support reference
• Publisher
• License reference

discovery

Search-oriented information:

• Keywords
• Localized synonyms
• Use cases
• User-goal categories
• Related plugin IDs
• Alternative plugin IDs where genuine overlap exists

requirements

Runtime and setup requirements:

• Minimum macOS version where more specific than the package floor
• Supported architectures
• Required hardware
• Required applications
• Required executables
• Required permissions
• Setup complexity
• Relaunch requirement

privacy

A structured declaration of:

• Data observed
• Data persisted
• Retention behavior
• Network use
• Declared network domains
• Telemetry behavior
• Whether sensitive user content may be processed
• Whether diagnostic exports contain user data

Note: This is product disclosure metadata, not a macOS sandbox entitlement system.

actions

Pre-install action information:

• Static action descriptors
• Dynamic action templates
• Supported action surfaces
• Risk
• Parameter summary
• Required permissions
• Automatic-execution eligibility
• External-invocation eligibility

setup

First-use metadata:

• Setup steps
• Suggested test action
• Optional next surfaces
• Help text for missing dependencies

relationships

Composition metadata:

• Related plugins
• Included packs
• Suggested recipes
• Replaced or superseded plugin IDs

---

Static and Dynamic Action Models

Static Actions

A static descriptor should include:

• Provider ID
• Action ID
• Localized title
• Localized description
• Keywords
• System image
• Permission IDs
• Risk
• Supported surfaces
• Automatic-execution state
• External-invocation state

After installation, the runtime ActionDefinition remains authoritative.

Dynamic Actions

Plugins such as AppVolume cannot enumerate machine-local action entries before installation. They should declare one or more dynamic templates, for example:

• “Set volume for a currently playing application”
• Entry source: active audio applications
• Parameter summary: local application identifier and volume
• Local-only identity
• Required system-audio permission

The catalog must not fabricate local entries.

Mixed Providers

A plugin may have both static actions and dynamic entries. The metadata model should support static, dynamic, and mixed provider behavior.

---

Pilot Plugins

Begin with three or four plugins that exercise different requirements. Do not begin with every plugin.

• Appearance
  • Covers: Simple static actions, no external dependency, safe reversible behavior, multiple action surfaces.
• AppVolume
  • Covers: Dynamic action entries, local-only parameters, runtime permission, contextual availability, audio category.
• IPOverview
  • Covers: Network access, privacy disclosure, workspace settings, static copy actions, dynamic diagnostic state.
• WindowSwitcher (optional fourth pilot)
  • Covers: Accessibility permission, foreground-interactive action, required global shortcut, contextual availability.

---

Source and Runtime Models

Introduce a build-tool manifest model representing the complete source schema. The existing runtime PluginPackageManifest may remain focused on fields required to load and validate a package.

The source model should:

• Decode all product fields
• Validate cross-field relationships
• Produce the package projection
• Produce the catalog projection
• Produce website data
• Produce localization diagnostics

Unknown optional product fields should not cause older runtime loaders to reject an otherwise compatible package.

Catalog Schema

Create a new catalog schema version with optional product and capability fields.

Requirements:

• Existing sparse entries remain decodable.
• Older catalog caches fail or fall back safely according to current compatibility policy.
• The catalog signature covers all new metadata.
• Presentation assets are identified by stable references and checksums.
• The catalog does not include build-only paths.
• Dynamic local values never enter the signed catalog.

Validation

Add schema and semantic validation for:

• Unique plugin IDs
• Unique static action keys
• Valid permission identifiers
• Valid categories
• Valid surface identifiers
• Valid related-plugin references
• Valid test-action references
• Valid asset references
• Localization fallback
• Network-domain syntax
• Static action consistency
• Dynamic-template completeness
• Runtime consistency

For built pilot plugins, CI should compare catalog action descriptors against runtime action definitions. Fail when:

• A catalog static action does not exist at runtime
• Provider or action IDs differ
• Risk conflicts
• Permission declarations conflict
• External-invocation declarations conflict
• A declared static action is actually only dynamic
• A required metadata action is missing

Allow presentation text to differ when the runtime value is localized dynamically, provided identity and policy remain consistent.

Asset Handling

Presentation assets should live in the plugin source tree under a conventional directory. The build should:

• Verify that referenced assets exist
• Validate media type
• Enforce size and dimension limits
• Compute SHA-256
• Copy generated website variants
• Exclude unreferenced assets where practical
• Reject executable or unsupported content

Do not embed image bytes or base64 content in plugin.json.

---

Implementation Plan

1. Foundation

• Define the source-manifest schema.
• Add a versioned JSON Schema or equivalent validator.
• Add optional product sections to the build-tool model.
• Define the catalog v3 projection.
• Add backward-decoding tests.
• Add semantic validation.

2. Pilot

• Migrate Appearance.
• Migrate AppVolume.
• Migrate IPOverview.
• Optionally migrate WindowSwitcher.
• Generate a local development catalog.
• Verify current Marketplace behavior remains unchanged with ignored optional fields.

3. Action Validation

• Extract or load runtime action definitions for pilot plugins.
• Compare static action identity and policy.
• Validate dynamic templates.
• Add CI failure messages that identify the owning plugin and field.

4. Integration

• Expose the enriched catalog model to feat(marketplace): add rich plugin detail pages backed by capability metadata #308.
• Expose installable capability metadata to Unified Search.
• Expose the same generated data to the website build.
• Document the authoring format.

---

Testing

Include tests for:

• Sparse legacy manifest
• Rich source manifest
• Sparse legacy catalog & Rich catalog
• Static action & Dynamic action template
• Mixed provider
• Invalid action key
• Missing permission, related plugin, or asset
• Invalid network domain
• Localization fallback
• Duplicate action
• Runtime-policy mismatch
• Unknown optional field
• Deterministic generation
• Signature verification with enriched metadata

---

Acceptance Criteria

• One checked-in plugin.json remains the source for each pilot plugin.
• The source supports optional product, discovery, requirements, privacy, action, and onboarding metadata.
• A signed catalog contains the validated projection.
• Existing sparse plugins continue working.
• At least three representative plugins use the enriched schema.
• Static action identity and policy are validated against runtime definitions.
• Dynamic providers use templates rather than fabricated local entries.
• feat(marketplace): add rich plugin detail pages backed by capability metadata #308 can render pilot plugin details without hard-coded plugin-specific data.
• The website can consume generated pilot metadata.
• CI reports stale or inconsistent metadata clearly.

Non-Goals

• Migrating every plugin in the first pull request
• Opening the ecosystem to third-party executable plugins
• Replacing runtime action definitions
• Storing machine-local action entries in the catalog
• Adding Marketplace ratings or reviews
• Implementing the complete Marketplace detail UI
• Implementing recipes or packs in this issue
• Introducing a second required per-plugin JSON source