Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
63 lines (47 loc) · 2.81 KB

CONTRIBUTING.md

File metadata and controls

63 lines (47 loc) · 2.81 KB
Raw

Contributing

Setup

corepack enable
pnpm install

Node 24 or newer is required. The package is ESM-only and targets NestJS 12 and CapsuleOS 0.2.

Workflow

pnpm run check          # Oxlint, Prettier, and TypeScript
pnpm run test           # unit and compile-time tests
pnpm run build          # tsdown output in dist/
pnpm run verify:pack    # build, Publint, packed declarations, and package shape
pnpm run verify         # every local release gate

Add a Changeset for every user-visible change with pnpm changeset.

After the one-time package-name bootstrap described below, releases run only in GitHub Actions on main through npm Trusted Publishing. The guarded publisher validates Changesets prerelease state and explicitly keeps alpha versions on the alpha dist-tag; never invoke routine npm publication directly from a developer workstation.

First npm publication

npm cannot attach a trusted publisher until the package record exists. The initial @nestm/capsuleos@0.1.0-alpha.0 publication therefore uses the separate, manually dispatched bootstrap-release.yml workflow and a short-lived granular token in the npm-bootstrap environment's NPM_TOKEN secret. The workflow is restricted to main, accepts one exact typed confirmation, verifies the full package, checks the npm identity and package absence, and publishes on the alpha dist-tag without provenance. It cannot publish any later version.

Immediately after that bootstrap succeeds:

  1. Configure the npm trusted publisher for repository nestm-dev/capsuleos, workflow release.yml, and environment release.
  2. Remove the NPM_TOKEN GitHub secret and revoke the bootstrap token unless an explicit security exception keeps it alive elsewhere.
  3. Dispatch release.yml once to prove OIDC publication setup. All subsequent releases use OIDC with provenance and have no token fallback.

The intended GitHub repository must be public before routine provenance-bearing publication. A new package name requires a separately reviewed bootstrap rather than broadening the routine workflow.

Ground rules

  • Keep CapsuleOS providers and native clients application-owned. Nest must never close them.
  • Keep prebuilt Capsule facades application-owned and preserve their identity.
  • Do not load testing, Harness, or concrete provider SDKs from the root entrypoint.
  • Preserve provider aliases and provider-specific request types through public generics.
  • Preserve ESM output and emitted decorator metadata.
  • Unit and packaging tests must not allocate a live sandbox or call a provider API.
  • Harness registration may construct a sandbox provider at bootstrap, but must not create a session.

Pull requests

Keep changes focused, document public behavior, include regression coverage, and make sure pnpm run verify passes before requesting review.