CRT
36a8bf9625
- cli/lib/rt.ts: the runtime layer on node: modules (spawn / spawnSync with Bun's defaults, exit codes and "Executable not found", which with PATHEXT, sleep, serve, Glob, hasher, gunzip, stdin, SQLite, packageRoot, config imports with a type-stripping fallback for Node 20); every Bun.* use in cli/ goes through it - tools/gen-embedded.ts -> cli/lib/embedded.ts: templates/, cli/shots/*.html and Play's Data safety form embedded (replaces Bun text imports; the bundle and the compiled sidecar carry them), checked fresh by bun run ci - package.json: bin dist/storebound.mjs (Node ESM bundle, tools/build-node.ts, prepack), engines node >=20 - bun run ci: node bundle + node smoke (real node: --version, help, check same as Bun, scan, release plan --help, init, MCP handshake + tool call); Forgejo CI sets up Node 20; tests/node-compat.test.ts guards cli/ - install writes npx MCP commands when run with Node; bin/storebound falls back to Node - docs: npx storebound init (Node 20+) or bunx storebound init
84 lines
6.6 KiB
Markdown
84 lines
6.6 KiB
Markdown
# 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
|
|
|
|
```sh
|
|
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](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`).
|
|
|
|
## 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).
|