Contributing

Full guide lives at CONTRIBUTING.md in the repo. This page is the short version.

Setup

git clone https://github.com/apprider/gemmapod
cd gemmapod
pnpm install
pnpm build:core                # rebuilds @gemmapod/core (Rust → WASM)
pnpm -r --filter "./packages/*" build
pnpm --filter @gemmapod/dartc test
pnpm --filter @gemmapod/signal test

You need:

Node 22+
pnpm 9+ (corepack enable && corepack prepare pnpm@9 --activate)
Rust stable + wasm32-unknown-unknown + wasm-pack — only if rebuilding @gemmapod/core. Otherwise the committed packages/core/pkg{,-node}/ artefacts work.

Testing the CLI locally before publishing

The dev:gemmapod script runs pnpm --filter gemmapod dev, which puts your shell's cwd inside packages/gemmapod/. Relative paths like examples/raj-card/pod.toml resolve from there, not from the workspace root — so you'll see ENOENT: ... /packages/gemmapod/examples/raj-card/pod.toml. Pass an absolute path, or use one of the methods below.

Pick a method based on what you're testing:

Method 1 — Build once, run from any cwd

Best for fast iteration on the CLI itself. Relative paths work because you control cwd directly.

pnpm -C packages/gemmapod build
pnpm -C packages/host build      # if you touched the host package

# Then from any directory:
node packages/gemmapod/dist/cli.js run examples/raj-card/pod.toml
node packages/gemmapod/dist/cli.js status
node packages/gemmapod/dist/cli.js kill

Method 2 — `pnpm link --global`

Closest to what an npm user gets, while still resolving @gemmapod/host, @gemmapod/core, @gemmapod/shim to your local workspace sources. Best for end-to-end testing of uncommitted host changes.

pnpm -C packages/host build
pnpm -C packages/gemmapod build
pnpm -C packages/gemmapod link --global

# From anywhere:
gemmapod run /path/to/pod.toml
gemmapod status

# Cleanup:
pnpm -C packages/gemmapod unlink --global

Method 3 — `npm pack` + `npx`

Full publish simulation. Catches missing files in package.json#files, broken bin shebangs, and wrong dependency declarations. Workspace deps resolve to the npm-published versions of @gemmapod/*, so this is "would a fresh user see the same behavior?" — not a way to test uncommitted changes in sibling packages.

pnpm build
cd packages/gemmapod
npm pack                                # → gemmapod-X.Y.Z.tgz

mkdir -p /tmp/gemmapod-smoke && cd /tmp/gemmapod-smoke
npx /abs/path/to/gemmapod-X.Y.Z.tgz run /abs/path/to/pod.toml

Suggested smoke checklist before tagging a release

# Terminal A: start Host on the default port
node packages/gemmapod/dist/cli.js start --port 57447
# → confirm dashboard loads at http://localhost:57447

# Terminal B:
node packages/gemmapod/dist/cli.js status          # all green
node packages/gemmapod/dist/cli.js run /abs/path/to/raj-card/pod.toml
#   → open dashboard, click "Quit GemmaPod" → farewell screen appears
#   → restart, then test Ctrl+C twice (graceful drain → force quit)
node packages/gemmapod/dist/cli.js kill            # clean shutdown
ls ~/.gemmapod/                                    # discovery file gone
lsof -iTCP:57447 -sTCP:LISTEN                      # nothing listening

Branch + PR flow

Open an issue for non-trivial changes so we agree on direction.
Branch from main.
Add a changeset (pnpm changeset) for anything that affects a published package.
Open the PR. CI runs build + dartc + cloud tests + npm pack --dry-run + an end-to-end CLI smoke. If you touched packages/host/**, the native build matrix also runs on macOS / Linux / Windows.

Versioning policy

npm packages follow semver. We are at 0.x; minor bumps may include breaking changes — flagged in CHANGELOG.md.
DARTC wire format carries its own v0.2 version. A patch bump of any package MUST NOT change the wire format. More →
Signed manifest CBOR carries its own v=1 schema. Backwards- compatible additions only without a version bump.

Style

TypeScript strict mode is on. No any without a reason in a comment.
Rust (packages/core): keep the wasm-bindgen surface narrow.
Don't write comments that restate the code. Comment why: a hidden constraint, a security invariant, a browser quirk.
Don't ship feature flags or backwards-compatibility shims for code that hasn't been released.

Snapshot releases for PR testing

Maintainers can publish a snapshot of any open PR (e.g. @gemmapod/shim@0.1.1-pr-42-<sha>) so consumers can test before merge:

pnpm changeset:snapshot

Security issues

Don't open a public issue. Use GitHub's private security advisory flow or email raj.design@gmail.com with subject [gemmapod-sec].

License

By contributing you agree your contributions are licensed under the MIT License (see LICENSE).

On this page