Skip to content

DEVELOPMENT.md

Latest commit

 

History

History
98 lines (62 loc) · 2.86 KB

DEVELOPMENT.md

File metadata and controls

98 lines (62 loc) · 2.86 KB
Raw

Development

ContextLevy is a Node.js project with a dual build: a bundled GitHub Action and a published npm CLI.

Setup

Install dependencies:

npm install

Run tests:

npm test

Run Biome, typecheck, tests, and Fallow dead-code checks:

npm run check

Run the full check suite plus build:

npm run all

Run dead-code analysis with Fallow:

npm run check:fallow

Fallow config lives in .fallowrc.json. It declares Action and CLI entry points, ignores dogfood fixtures under examples/, and treats GitHub Action build dependencies as used.

Build

Build the action bundle and CLI:

npm run build          # both
npm run build:action   # GitHub Action only → dist/index.js
npm run build:cli      # local CLI only → lib/

Commit dist/index.js after building the action so workflow consumers do not need to install runtime dependencies. The CLI (lib/) is built automatically on npm publish via prepack.

Verify the npm tarball before publishing:

npm run pack:check

Module layout

See ARCHITECTURE.md for the module map, dependency rules, and where to add new features.

Releasing

Releases are automated when a version bump lands on main. The release workflow detects a package.json version change, runs tests, verifies dist/, creates a GitHub Release, pushes the semver tag, publishes the CLI to npm via trusted publishing (OIDC), and updates the major tag.

Do not push semver tags manually. Bump the version in package.json, package-lock.json, and CHANGELOG.md, push to main, and CI handles the tag, GitHub Release, and npm publish.

On npmjs.com → Package settings → Trusted publishing, configure GitHub Actions with repository nonlooped/contextlevy and workflow filename release.yml. No NPM_TOKEN secret is required.

If npm publish fails after a version bump, re-run the Release workflow from the Actions tab (workflow_dispatch) once the package is missing on npm — it will retry without another version bump.

Example release sequence:

# After updating package.json, package-lock.json, and CHANGELOG.md
git push origin main

The workflow updates the major-version tag (v2) automatically.

First npm publish (manual)

Before trusted publishing is configured, publish the CLI once from a clean checkout:

npm ci
npm run pack:check
npm publish --access public

Then add the trusted publisher on npmjs.com as described above. Later version bumps on main publish automatically via OIDC.

Consumers should usually pin:

- uses: nonlooped/contextlevy@v2

For maximum supply-chain safety, consumers can pin a full commit SHA.