browser/plugins/docs/local-development.md

Local Plugin Development

Local development must exercise the same platform-mediated flows used by installed plugins.

Flow

1. Validate the plugin manifest with npm run validate:manifest.
2. Register the validated manifest with platform POST /api/v1/game-plugins/register-manifest using a manifest artifact reference and the manifest payload.
3. Serve plugin page from a local dev server or static directory.
4. Select a test server instance and run endpoint.
5. Use platform bridge calls for jobs, logs, files, artifacts, and AI.

Plugins must not bypass platform authorization by calling run directly.

Manifest validation rejects raw host paths, raw credentials, direct run sockets, and raw AI/provider keys. Platform registration repeats the same safety class of validation before storing registry metadata, so a plugin workspace validation result is not treated as a trusted backend bypass.

For full local stack proof, run the repository local debug workspace:

scripts/dev-start.sh
scripts/dev-smoke.sh

That workflow registers plugins/examples/dev-game-plugin/manifest.json, creates a safe server-local-debug fixture through platform APIs, and verifies that plugin/browser evidence exposes only logical IDs, platform routes, job refs, log refs, artifact refs, and safe metadata.

Lifecycle development checks

When exercising a Client Manager locally, use the real Platform build job and the independent Run checkout. Verify build-to-deploy with a pinned approved HTTPS revision, checksum and chunk resume, then register/heartbeat through the component contract. Key reset must make the old generation unavailable and require rebuild/redeploy. Do not replace lifecycle jobs with JSON plans, synthetic artifacts, shell commands, or local success flags.