Contributing — Dev Quickstart

Thanks for helping improve STAN! This project follows a services‑first, test‑first philosophy. Here’s how to get started locally.

Setup

Prereqs:

• Node ≥ 20
• Git

Clone and install:

git clone https://github.com/karmaniverous/stan.git
cd stan
npm i
Copy

Common tasks

Run the suite:

npm run lint
npm run typecheck
npm run test
npm run build
npm run docs
Copy

Dev fallback (bootstrap scripts)

If stan run is temporarily broken while developing STAN itself, use the bootstrap scripts as a stopgap to exercise the pipeline and generate the usual artifacts (outputs and archive) without relying on the CLI:

• Primary orchestrator (runs multiple tasks concurrently and then archives):

  npm run bootstrap
  Copy

  This will:

  • run typecheck, lint, test, build, and docs concurrently,
  • write deterministic outputs to .stan/output/*.txt,
  • and create .stan/output/archive.tar.

• You can also run individual bootstrap tasks:

  npm run bootstrap:typecheck
  npm run bootstrap:lint
  npm run bootstrap:test
  npm run bootstrap:build
  npm run bootstrap:docs
  npm run bootstrap:archive
  Copy

Note: these bootstrap scripts are for STAN development only (fallback tooling). Consumers of STAN should use the CLI directly, e.g. stan run.

Coding standards

• Single‑Responsibility modules; prefer small, testable units.
• Plain unified diffs for patches; never base64.
• Keep .stan/system/stan.todo.md updated with each change set and include a commit message (fenced) in PRs.

Submitting changes

1. Create a feature branch: git checkout -b feature/your-change.
2. Ensure CI tasks pass locally.
3. Open a PR with a clear description and links to any related issues.
4. Expect review on tests, docs updates, and module design.

Questions?

Open a GitHub issue with details or propose a design sketch in the PR description.