Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
58 lines (44 loc) · 2.87 KB

CONTRIBUTING.md

File metadata and controls

58 lines (44 loc) · 2.87 KB
Raw

Contributing

Use Node.js 24 and the pnpm version declared in package.json.

This repository intentionally develops against local unreleased upstream workspaces:

  • ../../concepta/agentportal
  • ../../concepta/capsuleos

Install and build those workspaces before installing this repository. Do not replace the local link: development dependencies with registry packages in a feature change; release preparation owns that transition.

pnpm install
pnpm run verify
pnpm run test:cross-repository

The verification gate runs linting, formatting, source and declaration type checks, unit tests, Express and Fastify E2E tests, packaging checks, strict Publint, isolated tarball consumers, and Are The Types Wrong. Ordinary tests must remain deterministic and must not call a live agent or sandbox provider.

test:cross-repository additionally expects the sibling ../capsuleos and ../ai-sdk repositories plus ../../concepta/agentportal and ../../concepta/capsuleos. It packs all five repositories into one isolated Nest 12 consumer and executes both independent agent paths without provider credentials.

Keep root imports isolated from optional subpaths. If a subpath gains a dependency, update its optional peer declaration, packed-consumer closure test, README dependency table, and security notes together.

Add a Changeset for every public behavior change. Do not commit generated dist, coverage, tarballs, credentials, local databases, or provider state.

Publishing

Routine releases use npm trusted publishing from the release.yml GitHub Actions workflow. The workflow requests an OIDC identity and deliberately disables npm source-provenance attestations; it must not receive NODE_AUTH_TOKEN or NPM_TOKEN.

The first release uses the manually dispatched bootstrap-release.yml workflow because npm cannot configure a trusted publisher before the package record exists. Put a short-lived granular token in the npm-bootstrap environment's NPM_TOKEN secret, type the workflow's exact confirmation, and publish only @nestm/agentportal@0.1.0-alpha.0 on the alpha tag without provenance.

After it succeeds, configure the package-scoped trusted publisher for nestm-dev/agentportal, .github/workflows/release.yml, and the release environment, then delete the GitHub bootstrap secret. All subsequent releases are OIDC-only; the bootstrap script permanently refuses any other package name or version.

Source-based cross-repository jobs compile the private btwld/agentportal and btwld/capsuleos repositories with separate read-only deploy keys. Store them as AGENTPORTAL_UPSTREAM_DEPLOY_KEY and CAPSULEOS_UPSTREAM_DEPLOY_KEY; never replace them with a broad personal access token. The credentials are used only for source checkout and are never forwarded to npm or the packed consumer. Routine verification and release use published upstream packages after the initial SDK bootstrap.