storebound/CONTRIBUTING.md

Contributing

Thanks for wanting to help. storebound is my own toolchain that I open-sourced, so it stays small and opinionated, but fixes, store rule updates and new engines / AI tools are very welcome.

Setup

bun install                 # Bun 1.1+; playwright is a dev dependency (renders, web capture)
bun run ci:quick            # inner loop: typecheck + the tests your change touches + scrub (seconds)
bun run ci                  # full gate before pushing: every check and test (adapters, API tables, typecheck,
                            # desktop build and boot check, Rust host when it changed, scrub)

Which one when. Run bun run ci:quick while you work: it diffs against origin/main (committed, staged, unstaged and new files), maps the changed files to the tests that import them (directly, through other modules, or by naming a fixture or page) and runs those, plus tsc (incremental) and the scrub. A change to package.json, bun.lock, bunfig.toml, tsconfig.json or the test preload runs every test. Run the full bun run ci before every push and check its exit code: it is the gate, ci:quick is not.

tools/ci.ts runs the steps as a task graph (independent steps at the same time, output prefixed with the step name, the first failure stops the rest, a time-per-step summary at the end). The tests run as parallel shards (CPU cores - 1, at most 8; STOREBOUND_CI_SHARDS=n overrides) balanced by the durations of the last run, kept in node_modules/.cache/storebound-ci/; the browser suites get a shard each. So tests must be shard-safe: temp folders from mkdtempSync, servers on port 0, no fixed sleeps (wait for the event), no state shared through files in the checkout. The desktop Rust host (cargo test, clippy) runs only when apps/desktop/src-tauri/ or tools/build-sidecars.ts changed against origin/main; CI=full bun run ci always runs it (Forgejo CI does).

Try the screenshot and video pipeline on the demo game without any store account: see examples/demo-game/README.md.

Rules of the house

• Bun + TypeScript strict, zero runtime dependencies. fetch against the official store APIs, node: built-ins, external tools (ffmpeg, xcrun, adb) only through argv builders. Playwright is resolved from the user's project.
• Runs on Node 20+ and Bun. Development, tests and CI use Bun; users run the npm bundle with Node (npx) or Bun (bunx). The CLI never touches the Bun global, bun: modules, import.meta.dir or text imports: everything goes through cli/lib/rt.ts (spawn, which, sleep, serve, glob, hashing, stdin, the package folder, config imports), and text files the CLI ships are embedded by bun tools/gen-embedded.ts (templates/, cli/shots/*.html, Play's form export: run it after changing one). tests/node-compat.test.ts fails on a direct Bun use; bun run ci builds the bundle (tools/build-node.ts) and runs it with the real node (tools/node-smoke.ts).
• Pure where possible. Rules, argv builders, plans and parsers are pure functions with tests in tests/; the IO stays in the command's run. Tests never need a store account, a simulator or a network.
• Every write command takes --dry and is idempotent. New MCP write tools default to dry_run: true. Nothing public or irreversible (submit, release, rollout resume / complete, cancel, delete) goes into MCP.
• Store facts need a source. When you change a size, limit or rule, cite the official page in the code comment and the skill (Apple Developer / App Store Connect Help, Play Console Help, API references) with the date you checked it.
• Skills are the single source. Edit skills/*/SKILL.md or docs/agents-core.md, then run bun tools/gen-adapters.ts; never edit AGENTS.md, GEMINI.md, the plugin manifests or the Cursor / Copilot files by hand. Frontmatter is name + description only.
• New or renamed flags: run bun tools/gen-flags.ts. The CLI rejects a flag a command does not read (cli/data/flags.json, generated from the commands and their imports in cli/commands.ts); a flag read with a computed name goes into DYNAMIC in that tool. tests/cli-help.test.ts fails on a stale table, on a command whose --help does anything but print its usage, and on an MCP / desktop tool that passes a flag its command does not take.
• No secrets, no real ids, no personal data in code, tests, fixtures or examples: use com.example.*, example.com and obviously fake values. bun run ci runs the scrub.
• No hand-written SVG. Charts come from visx, icons from Phosphor (@phosphor-icons/react in the desktop app, one per-icon import each; the site's icons are Phosphor's own files from @phosphor-icons/core), the App Store and Google Play marks from simple-icons (vendored with the licences by bun tools/site-icons.ts into site/img/icons/ and apps/desktop/src/ui/store-marks/, byte-equal to the packages), diagrams from Mermaid (docs/diagrams/*.mmd, rendered by bun tools/diagrams.ts), the desktop fixtures' art from bun tools/fixture-art.ts. The logo files (app icons, favicons, header marks, site/og.png) are PNG / ICO / ICNS from tools/brand-assets.py (brand/README.md). tests/no-handmade-svg.test.ts fails on new inline <svg> / <path> drawing in apps/desktop/src and site/*.html and on SVG files that are not vendored or rendered. These libraries are desktop dependencies (bundled by Vite) or devDependencies; the CLI package keeps zero runtime dependencies.
• Every bug found in real use becomes a guardrail. Add an entry to docs/pitfalls.md and to skills/store-pitfalls/SKILL.md (symptom, cause, what to do, what guards it) and, where possible, a check or a test with recorded store answers that fails without the fix. A --dry run prints the plan (dryPlan in cli/lib/dry.ts), not only a count; tests/pitfalls.test.ts enforces it.
• Plain English in docs and messages, short sentences, no marketing words.

Releasing the npm package

npm pack and npm publish run prepack, which builds dist/storebound.mjs (the bin, #!/usr/bin/env node, gitignored) with bun tools/build-node.ts. Before publishing: bun run ci green (it smoke-tests the bundle with Node), npm pack --dry-run lists dist/storebound.mjs, the privacy scan on the tree and on the bundle, and a run of the packed tarball in an empty folder (npx --yes ./storebound-<version>.tgz --version, then init).

The npm package and the desktop app are one release with one version (bun tools/desktop-version.ts --set <version> writes it everywhere): publish the desktop artifacts of that version first (docs/desktop-release.md), then npm publish, so npx storebound desktop of the new CLI finds its own app.

Pull requests

One topic per PR, bun run ci green, a line in CHANGELOG.md under an "Unreleased" heading, and for anything that talks to a store: how you verified it (--dry output, a test app, or "not verified" said plainly).