poggit-alternative-test/plugin-repository

Purpose and execution model

Axolotl is a GitHub-native trusted distribution pipeline for PocketMine-MP plugins. It turns an untrusted upstream repository commit into a reviewed, preserved source snapshot, an unprivileged PHAR build, and an immutable GitHub Release. The repository is primarily TypeScript CLI tooling and GitHub Actions rather than a web application.

Primary entry points are command-specific CLIs under src/cli/, invoked by workflows such as .github/workflows/validate-submission.yml, .github/workflows/materialize-storage.yml, .github/workflows/build-trusted.yml, and .github/workflows/publish-release.yml.

Registry: declarative source of truth

The registry records plugin identity and version-specific source/release metadata in a filesystem layout rooted at registry/plugins/. Parsing, schema validation, semantic validation, and writing are separated in:

• src/registry/parser.ts

• src/registry/validator.ts

• src/registry/writer.ts

JSON Schemas define the external registry/submission contracts in schemas/plugin.schema.json, schemas/version.schema.json, and schemas/plugin-submission.schema.json. Registry changes are expected to arrive through PRs and be validated before review or downstream processing.

Submission acquisition and inspection boundary

Submission code treats developer repositories as untrusted input. It acquires candidate metadata/source references, parses plugin manifests, composes results, and emits inspection signals/diagnostics:

• src/submission/acquisition.ts

• src/submission/inspection.ts

• src/submission/github.ts

The src/cli/inspect-submission.ts entry point operationalizes this stage. Submission validation is deliberately distinct from approval: automated checks can establish readiness but cannot authorize publication.

Human review and approval state

Review is a separate domain that binds approval to a candidate’s exact identity/SHA and checks reviewer authorization and approval preconditions:

• src/review/candidate-identity.ts

• src/review/approval-preconditions.ts

• src/review/review-state.ts

Review records and persistence abstractions live in src/review/review-record.ts and src/review/review-storage.ts; reviewer policy/configuration is anchored by config/reviewers.yaml. The key trust transition is from validated candidate to approved exact source revision, not from successful CI to trusted artifact.

Storage materialization

After approval, materialization copies or preserves the reviewed source into the dedicated plugin-storage organization/repository namespace. This domain isolates GitHub authentication and API interaction behind client abstractions:

• src/materialization/materialization-service.ts

• src/materialization/github-client.ts

• src/materialization/real-github-client.ts

Repository naming and transport configuration are explicit in src/materialization/repository-naming.ts and src/materialization/tester-transport-config.ts. GitHub App authentication is implemented in src/materialization/github-app-auth.ts, making GitHub the materialization infrastructure boundary.

Trusted build domain

The build stage runs only against materialized source and produces PHAR artifacts, SHA-256/provenance-related diagnostics, without publication credentials. Its orchestration adapters are:

• src/build/index.ts

• src/build/pharynx-runner.ts

• src/build/composer-runner.ts

The isolated builder package under tools/builder/src/ supplies build-oriented filesystem, manifest validation, and security-scanning capabilities. src/cli/build-trusted.ts is the build entry point; .github/workflows/build-trusted.yml supplies its CI execution boundary.

Privileged publication domain

Publication consumes completed build outputs and publishes releases through a provider abstraction, intentionally without executing plugin code:

• src/publication/publication-service.ts

• src/publication/provider.ts

• src/publication/github-provider.ts

src/cli/publish.ts and .github/workflows/publish-release.yml drive this privileged stage. src/publication/fake-provider.ts supports provider substitution, while the GitHub provider represents the immutable-release external service boundary.

End-to-end control flow and trust separation

The lifecycle is: submission/registry PR → validation → human approval of exact SHA → GitHub storage materialization → unprivileged build → privileged GitHub Release publication. CLI layers coordinate each domain, while src/registry, src/submission, src/review, src/materialization, src/build, and src/publication preserve the major security boundaries. GitHub PRs, Actions, GitHub App/API access, storage repositories, and Releases are the material infrastructure; no custom persistent backend is indicated.