Skip to content

plugin-bundle.md

Latest commit

 

History

History
44 lines (28 loc) · 4.79 KB

plugin-bundle.md

File metadata and controls

44 lines (28 loc) · 4.79 KB
Raw

Downloadable Alera Plugin

The landing build publishes /downloads/alera-plugin.zip and /downloads/alera-plugin.zip.sha256. The download page links to the archive and /docs/plugin explains manual installation. These are static files generated by landing/config/plugin-download.ts in astro:build:done, so direct astro build and bun run build both include the package. The development server serves the same URLs through middleware.

Package Sources

  • landing/plugin/plugin.json owns package identity, version, listing metadata, asset paths, and onboarding.
  • landing/plugin/mcp.json owns the remote HTTPS MCP endpoint and OAuth discovery preference. It requests read and execute scopes; administrative access is not requested by default.
  • landing/plugin/skills/alera-setup/ owns the plugin-only onboarding workflow.
  • edge/skills/ remains the source of the four MCP workflow skills and all their references. The packager copies the same normalized text as the MCP skill catalog and adds each skill's MCP dependency metadata. It does not copy or install the CLI skills from skills/.
  • assets/logo/alera-logo.png and landing/public/logo.png supply the existing square listing and composer images for light and dark client themes. The package also includes the repository license.

The archive has a single alera/ root with portable plugin.json and mcp.json, skills/, and assets/. Generated .codex-plugin/plugin.json and .mcp.json provide the supported Codex compatibility layout. The hidden .agents/plugins/marketplace.json registers the extracted folder itself as a local marketplace source. Keep hidden files when transferring the package.

Build Outside The Website

cd landing
bun install --frozen-lockfile
bun run package:plugin

This writes the ZIP, checksum, and extracted package to build/plugin/ at the repository root. Pass another output directory with bun run package:plugin /absolute/output/path. Register the extracted package with codex plugin marketplace add /absolute/output/path/alera, then install it with codex plugin add alera@alera or through the desktop plugin directory. The packaging command prepares files only and does not change a user's plugin installation or account.

Versioning And Deployment

The plugin has an independent semantic version in landing/plugin/plugin.json. Bump it for changes to bundled instructions, metadata, onboarding, or assets, including changes under edge/skills/. The four MCP skills keep their own metadata.version rules. The compatibility manifest and web copy derive their version from the portable manifest.

All archive entries have fixed timestamps, stable ordering, and regular-file modes. The SHA-256 identifies the exact generated ZIP. Generated archives and the extracted package stay outside Git; rebuild them rather than maintaining a second copy of the skills.

The website build must have the repository parent sources available: edge/skills/, edge/tool/skill_catalog.ts, assets/logo/alera-logo.png, and LICENSE. For a Vercel project rooted at landing/, enable Include source files outside of the Root Directory in the Build Step and ensure changes to these package inputs trigger the website build. The Landing workflow also runs when these inputs change and uploads the ZIP and checksum as an alera-plugin Actions artifact after its checks pass.

Publishing the website makes the ZIP downloadable. It does not publish to OpenAI's universal Plugins Directory. For that directory, upload the complete ZIP in the OpenAI developer portal, connect the MCP, supply review details and domain verification, and publish after approval. See Package your plugin and Upload and submit your plugin. No submission, domain verification, or production deployment is performed by the packaging scripts.

Validation

cd landing
bun run check

Unit tests extract the archive, compare every MCP skill and reference with its source, verify the manifests and their asset/onboarding paths, parse dependency metadata, check credentials are not configured, and verify deterministic bytes across time zones. Playwright downloads the archive from the built site, verifies its checksum, and checks installation guidance, accessibility, and overflow at desktop and mobile widths. Existing edge/test/mcp_skills.test.ts holds MCP tool coverage and skill-reference conformance.

These automated checks prove package structure and web delivery locally. The initial package was also installed and enabled with Codex 0.162.1 in an isolated, temporary client home without network access. OAuth consent and the setup skill's behavior must still be exercised in a connected client before claiming end-to-end access or public directory acceptance.