Publishing

Third-party plugins are published through VibeLands-hosted infrastructure. Local server installation is no longer the public distribution path.

1. Validate Locally

vibelands check .
vibelands check . --review

check catches manifest errors, missing entries, compile errors, forbidden host imports, bundled singleton copies, and budget violations before upload. check --review additionally validates review-metadata.json so marketplace description, support/privacy notes, and permission rationale are ready before submission.

2. Upload Source

vibelands serve .

The CLI uploads a source archive to the hosted sandbox build API on https://playvibelands.com:

POST /api/plugins/sandbox/uploads

The sandbox builder compiles, scans, signs, and deploys the plugin into a temporary clone of the hosted world you choose. The CLI prints the build/status URL and hosted game URL returned by the service. Use --direct-world only when you intentionally want to test against the original world.

Use --json when wiring the sandbox loop into CI or a developer portal:

vibelands serve . --json

The structured result includes the build links and sandbox runtime diagnostics, including sandbox.error when the build published but the test runtime could not be prepared.

This creates a sandbox build. It is not yet a public marketplace release.

3. Submit For Review

Public marketplace publishing is a review flow:

vibelands publish <buildId> --metadata review-metadata.json

The publish command targets a sandbox build or uploads a fresh source archive, then creates a review submission. A version already published to Marketplace is immutable and updates require a newer semver. When a reviewer requests changes, the corrected Sandbox build can be resubmitted at the same not-yet-published version.

Browser developers can use Submit Review in /sandbox instead. The dialog loads prior submissions and Marketplace history, then presents the correct first-release, version-update, or reviewer-follow-up flow.

Use a metadata file so reviewers receive the public listing context and permission rationale with the build:

{
  "description": "Adds checkpoint coin races for small community worlds.",
  "tags": ["activity", "racing"],
  "media": ["https://example.com/screenshot.png"],
  "license": "MIT",
  "supportUrl": "https://example.com/support",
  "privacyNotes": "Stores per-world high scores only. Does not export player data.",
  "permissionRationale": {
    "storage": "Persists high scores and active event state.",
    "players.modify": "Grants XP and money rewards when a run is completed."
  },
  "testNotes": "Start the Coin Sprint activity near the town square and complete one lap.",
  "changelog": "Initial marketplace submission."
}

vibelands create generates review-metadata.json; fill it in before your first review submission.

description, tags, and license fall back to the plugin manifest when available. The hosted review API rejects missing description, tags, license, valid support URL, privacy notes, changelog, or rationale for a requested permission, so custom clients cannot bypass the publishing form. Missing media and reviewer test notes remain visible as reviewMetadataWarnings.

vibelands publish ... --json returns a machine-readable review submission summary with submissionId, buildId, pluginId, version, status, submissionUrl, and reviewMetadataWarnings.

Reviewers process submissions through /ops-console or the admin ops API:

• GET /api/admin/ops/plugins/review-submissions?status=submitted
• PATCH /api/admin/ops/plugins/review-submissions/:id with action: "publish" to create the public marketplace listing/version.

Review requires:

• automated build, scan, signing, and sandbox smoke checks;
• changelog, description, tags, license, support URL, privacy notes, and permission rationale (media and focused reviewer test notes are recommended);
• manual approval before the version becomes public and installable.

Track your submission from the CLI:

vibelands reviews
vibelands review <submissionId>

4. Marketplace Install

Approved versions are installed into worlds by version pin through the hosted control plane. World owners choose when to install or update a plugin; runtime startup resolves the pinned version to a signed release artifact.

After approval, verify public discovery from the CLI:

vibelands marketplace <plugin-name-or-tag>
vibelands marketplace:show <slug>

World owners can install the approved version from the CLI or the in-game Plugin Store:

vibelands marketplace:install <slug> --world-id <worldId>
vibelands marketplace:install <slug> --world-id <worldId> --version <old-version>  # rollback
vibelands marketplace:uninstall <slug> --world-id <worldId>
vibelands marketplace:world --world-id <worldId>

For an operator smoke after a review submission exists:

node scripts/plugin-marketplace-e2e-smoke.mjs \
  --remote https://playvibelands.com \
  --cookie "vibelands_session=..." \
  --world-id <worldId> \
  --submission-id <reviewSubmissionId>

Use --skip-publish --plugin-id <pluginId> to only verify marketplace install for an already-published listing.

5. Runtime Trust Model

• Third-party browser JavaScript is allowed only as reviewed React/R3F plugin bundles produced by the hosted build pipeline.
• Client-facing plugin behavior must go through entries.client, shared-module shims, integrity checks, plugin SDK APIs, and marketplace review.
• Server logic runs in isolated worker containers.
• Plugin workers do not receive database credentials and cannot mutate world state directly.
• The world runtime validates worker-requested effects through permissions, quotas, and circuit breakers.

See the in-repo architecture note: docs/SECURE_PLUGIN_AND_HOSTING_ARCHITECTURE.md.