Package Shape Proposal · Developers Hub

The current extension package is a local directory. A future marketplace package would need an envelope around that directory, but the envelope does not exist in runtime today.

This page defines a proposal vocabulary for future review discussions. It is not a package installer contract.

Current Local Package Shape

Current extension v1 loads this local shape:

app/extensions/{vendor}/
  manifest.json
  bootstrap.php
  actions/
  admin/routes/
  migrations/
  README.md

manifest.json is parsed by MyronExtensionManifest::fromFile(). The parser currently understands:

Field	Current status
`vendor`	Required; snake_case and must match the normalized directory name.
`name`	Required.
`version`	Required.
`requiredScopes`	List of base extension scopes; defaults to `[]` when absent.
`hasMigrations`	Boolean; defaults to `false` when absent.
`adminRoutes`	List of route objects with `key` and relative `path`; defaults to `[]` when absent.

Future Marketplace Envelope

A future marketplace package could wrap the local package with review and distribution metadata:

my_vendor-extension-package/
  marketplace.json        # proposed future envelope; not current runtime
  extension/
    manifest.json
    bootstrap.php
    actions/
    admin/routes/
    migrations/
    README.md
  docs/
    overview.md
    ai-parity.md
    security.md
  checksums.json          # proposed future integrity record

This shape is intentionally separate from current runtime support. A current MyronCMS install does not read marketplace.json, verify checksums.json, or install from this envelope.

Proposed Envelope Fields

These fields are future proposal fields only:

Field	Proposed purpose	Current runtime support
`packageId`	Stable marketplace package identifier.	None.
`vendor`	Must match extension manifest vendor.	Enforced only by current manifest for local package loading.
`version`	Marketplace package version.	Current manifest has extension version only.
`extensionPath`	Path to the local extension package inside the envelope.	None.
`compatibility`	Link or object for future compatibility declaration.	None.
`review`	Future review status or review metadata.	None.
`security`	Future security posture declaration.	None.
`docs`	Paths to package documentation.	None.

Do not put these fields into manifest.json unless a future runtime contract updates ExtensionManifest.php.

Human Path

For current development:

Create the local package under app/extensions/{vendor}/.
Keep the manifest in the current parser-supported shape.
Register and grant the extension through the admin UI.
Use this page only to discuss what a future marketplace envelope may need.

For future package planning, draft a marketplace envelope separately from the current manifest and label it as proposed.

AI Path

An AI coding agent can author the current local package files and can draft a proposed envelope document for review.

An installed MCP client cannot create package envelopes, install package archives, resolve dependencies, verify checksums, or register marketplace packages.

Scopes

Reading or drafting this proposal requires no runtime scope.

Current runtime package behavior still depends on:

operator extension grants,
manifest requiredScopes,
action requiredScope,
caller scope during API or MCP calls.

Artifacts

Current artifacts:

app/extensions/{vendor}/manifest.json
app/extensions/{vendor}/bootstrap.php
optional actions/, admin/routes/, migrations/, local README

Proposed future artifacts:

marketplace.json
package docs folder
checksum or integrity record
review record
compatibility declaration

Safety Boundary

The future envelope must not be documented as loadable by current MyronCMS. Current package code must still obey vendor namespace rules, manifest parser constraints, extension grants, and loader behavior.

Verification

Current package verification remains:

php app/tests/verify-extension-system-foundation.php

Proposal verification is documentary:

Proposed fields are labeled future.
Current manifest fields are not mixed with future envelope fields.
The page does not include install automation instructions.
The page does not imply signing, sandboxing, dependency resolution, or checksums are enforced today.

Failure Modes

Failure	Likely cause	Safe response
`marketplace.json` is treated as current runtime input	Future proposal and current manifest were confused.	Use `manifest.json` only for current runtime loading.
Manifest contains proposed envelope fields	Package shape proposal drifted into parser contract.	Remove unsupported fields or start a runtime contract.
AI client attempts marketplace install	Installed MCP access was overstated.	Mark as no current route and use local authoring.
Package assumes dependency resolution	Future distribution concerns leaked into extension v1.	Vendor the local code responsibly or contract dependency support later.

Current Local Package Shape

Future Marketplace Envelope

Proposed Envelope Fields

Human Path

AI Path

Scopes

Artifacts

Safety Boundary

Verification

Failure Modes

Related Pages