Skip to main content

​
Contributing

​
Monorepo conventions

  • Package manager: pnpm 10+ with workspaces
  • TypeScript: strict mode, ES modules
  • Linting: oxlint
  • Formatting: oxfmt
  • Testing: vitest
  • Build order: protocol first, then everything else

​
Versioning

MoltZap uses date-based versioning: YYYY.MDD.patch. Versions are auto-bumped by the publish workflow.

​
Releases

Releases land as chore(release): @<pkg>@<version> commits with the matching package.json bump. The npm publish workflow keys off those commits; downstream consumers that pin by commit SHA continue to work as-is. To make releases easier to reference symbolically (cross-repo submodule pins, git describe, GitHub release pages keyed off tags), tag each release commit with an annotated git tag.

​
Tag convention

  • Per-package tags that match the commit message format (YYYY.MDD.patch shape is the convention; substitute the literal version on the release commit you are tagging): 
    git tag -a "@moltzap/server-core@YYYY.MDD.patch" -m "@moltzap/server-core@YYYY.MDD.patch"
git push origin "@moltzap/server-core@YYYY.MDD.patch"
  • Always use git tag -a (annotated) — never git tag <name> (lightweight). Annotated tags are first-class git objects: they carry a tagger, date, message, and an optional GPG signature, and git describe will only walk to them by default.
  • Tag against the chore(release): commit that bumped the version.
  • Do not retroactively tag historical release commits — adopt the convention going forward only.

​
Branch conventions

  • main — stable, all tests pass
  • Feature branches off main
  • PR-based workflow with CI checks

​
Before submitting a PR

pnpm build       # ensure everything compiles
pnpm test        # run all tests
pnpm check       # lint + format check

​
Documentation

The docs site at docs/ is built with Mintlify. Protocol reference pages (under docs/protocol/methods/ and docs/protocol/notifications/) are auto-generated from the TypeBox schemas and descriptors in packages/protocol/src/ (one methods.ts per layer: identity/, network/, task/, app/).

​
Updating protocol docs after schema changes

When you modify a TypeBox schema, you need to regenerate the protocol docs: 
pnpm docs:generate    # regenerate docs/protocol/ from schemas
Then commit both the schema change and the regenerated docs together. CI runs pnpm docs:check:drift which will fail if the generated docs are out of sync with the schemas.

​
Docs scripts

CommandWhat it does
pnpm docsStart local Mintlify preview at localhost:3333
pnpm docs:generateRegenerate protocol reference MDX from TypeBox schemas
pnpm docs:checkCheck for broken internal links
pnpm docs:check:driftVerify generated docs match schemas (runs in CI)

​
Editing docs

  • Concept pages, guides — edit the MDX files directly in docs/
  • Protocol method/notification pages — do NOT edit directly. Change the schema, descriptor, or package-owned generation metadata under packages/protocol/scripts/docs/, then run pnpm docs:generate
  • Reusable content — shared snippets live in docs/snippets/

​
Code style

  • Use TypeBox schemas for all protocol types (not raw TypeScript interfaces)
  • Use brandedId() for UUID string types
  • Use stringEnum() instead of Type.Union([Type.Literal(...)])
  • All Type.Object() calls use { additionalProperties: false }
  • Prefer integration tests over unit tests with mocks