Contributing to Stewarrd

Issues and pull requests are welcome on GitHub. For anything else, email james@ltl.so. The documentation is at stewarrd.app.

Discuss changes to client behavior, destructive actions, dependencies, or data formats before implementing them. Keep fixes focused. Prefer removing duplication to adding another abstraction, and extend existing tests when practical. Be respectful, specific, and considerate when reviewing others' work.

Development

Use Node 24.20 or newer within Node 24, npm, and TypeScript ESM.

npm ci --ignore-scripts
git config core.hooksPath .githooks
npm run check
npm run build
npm start

The server listens on port 8787 and creates local state in data/. For UI changes, also run npm run dev; Vite proxies API calls to the server. Never use production credentials for automated tests.

• npm run typecheck: strict TypeScript.
• npm run lint: oxlint, with warnings treated as errors.
• npm run format: oxfmt; use npm run format:check to verify.
• npm test: colocated Vitest behavior checks.
• npx playwright install chromium, then env -u NO_COLOR npx playwright test: browser checks with disposable local state.
• npm run docs:build: generate the public documentation in .site/.
• docker compose build: checks and builds the production container.

Before a pull request, run the relevant tests, types, lint, and formatting. Tests should prove behavior at a boundary, especially wrong external writes or data loss. Confirm a regression assertion fails when its safeguard is removed. Do not add coverage solely to increase the test count.

Never send commands to real download clients as part of a test without explicit permission for that environment. Dry-run policies do not make manual controls read-only. Do not commit credentials, private logs, tokens, or personal paths.

Pull requests and reports

Describe the problem, the resulting behavior, and the checks you ran. Include sanitized reproduction steps and the Stewarrd/client versions for bug reports. Report vulnerabilities privately using SECURITY.md. Contributions are licensed under the project's MIT license.

Maintainer releases

The application version is in package.json and package-lock.json. A stable vX.Y.Z tag must match both files. The release workflow reruns CI, then publishes Linux AMD64 images tagged X.Y.Z and latest to Docker Hub. Configure Actions variable DOCKERHUB_USERNAME and secret DOCKERHUB_TOKEN with repository write access. Tags are permanent; publish versions in increasing order.

Only after release approval, use npm version patch (or minor/major), then git push origin main --follow-tags. Pushing an ordinary commit or publishing the documentation does not publish an application image.

Documentation

The Pages workflow publishes only .site/ from main. It renders the public README, automation guide, contributing guide, security policy, and license into the shared layout in site/. Preview it locally with python3 -m http.server --directory .site. The custom domain is configured in GitHub Pages settings.