Contributing and Licensing

How to contribute code to AstroBaaS: running the project and its tests, opening a pull request, the Contributor License Agreement and the code of conduct. It also summarises the licence, what it allows, and how the separately sold vertical modules relate to the open-source core. It is for contributors and anyone deciding whether they can use AstroBaaS.

The source documents are CONTRIBUTING.md, CLA.md, CODE_OF_CONDUCT.md, LICENSING.md and STABILITY.md.

Get the project running

You need Node 22.12 or later (see .nvmrc).

git clone https://github.com/operator888/astrobaas.git
cd astrobaas
cp .env.example .env       # optional for dev; AUTH_SECRET is required in production
npm install
npm run setup              # optional: set your own admin email and password
npm run dev                # http://localhost:4321

The development credentials are admin@local / admin, and the dashboard warns you to change them. They do not work in production; see Security.

Tests and checks

npm run build and npm test must pass before you open a pull request. CI runs them on every push to main and every pull request.

Command	What it runs
npm run build	Type check (astro check) and production build
npm run test:unit	The unit suite: around 150 files under tests/, run one at a time
npm test	test:unit plus the smoke test on the lowdb driver
npm run smoke	Smoke test against lowdb (db.json)
npm run smoke:libsql	Smoke test against libSQL doc-blob (local SQLite)
npm run smoke:relational	Smoke test against the relational libSQL driver
npm run e2e	Production build, production-gate tests, deep health-check test, then the Playwright browser suite
npm run test:pkg	Builds the npm package and tests importing it from outside
npm run audit:licenses	Checks the production dependency tree's licences

The smoke suite runs the whole API (checkout, stock races, payment webhooks, visibility rules) against a live server. CI runs it on all three storage drivers. If your change touches storage, run all three locally:

npm run smoke && npm run smoke:libsql && npm run smoke:relational

For end-to-end tests, install Chromium once:

npx playwright install chromium
npm run e2e

npm run test:unit is the slow one. While you work, run only the file your change touches, and keep the full run for before you push:

node tests/<name>.test.mjs

CI also runs npm audit --omit=dev --audit-level=high.

Where things live

Path	What
src/middleware.ts	Auth, CSRF, CORS, rate limits, security headers
src/lib/auth.ts	Session signing and PBKDF2 password hashing
src/lib/localdb.ts	The storage wrapper every route goes through
src/lib/storage/	libSQL and relational drivers
src/lib/sanitize.ts	HTML allow-list for user content
src/lib/validate.ts	The schema validator every API handler uses
src/lib/migrations.ts	Schema migrations
src/pages/api/*	REST endpoints
src/pages/admin/*	Admin pages
tests/	Unit tests, smoke.mjs and Playwright specs

API endpoints always return { success: true, data } or { success: false, error: { message, code } }. See Architecture.

Pull requests

• Keep pull requests small enough that the diff fits on one screen.
• Add a line to CHANGELOG.md under [Unreleased] if users would notice the change.
• If you change an API contract, add or update the matching check in tests/smoke.mjs.
• Never commit db.json, dist/ or anything under public/uploads/.
• The checklist is a merge gate. Open the pull request with the repository's template and tick every box, including the CLA box. A workflow fails the pull request if any box is still unticked or the checklist is missing. Draft pull requests are exempt until you mark them ready. If a box genuinely cannot be ticked, say so in the pull request.

Changing the data shape

If existing databases need transforming (a new required field, a renamed value, a backfill), add a migration in src/lib/migrations.ts:

• Append an entry with the next integer version. Never edit, reorder or renumber a migration that has shipped; append a corrective one instead.
• Write up() against the Storage interface so it upgrades all three drivers.
• It must be idempotent: a no-op when the data is already in the target shape.
• Add cases to tests/migrations.test.mjs. The smoke suite exercises it on each driver.

Good first contributions

From CONTRIBUTING.md and the README's "What's not done yet":

• a Postgres storage adapter (the relational libSQL driver is a good template);
• localising the stock home page's hard-coded English headings;
• an accessibility check in CI, or unit tests for the upload magic-byte sniffer and the backup-import path-traversal guard.

Issues

The most useful issues are bug reports (the route, what you did, what happened, what you expected, and a log line) and offers to pick up an open issue. Say "I want to take this one" on the issue, then send a pull request. Report security problems privately, never as issues; see Security.

Contributor License Agreement

Pull requests are gated on a one-time CLA (CLA.md, version 1.0).

How to sign. Open your pull request as normal. A bot comments asking you to sign. Reply on that pull request with exactly this sentence:

I have read the CLA Document and I hereby sign the CLA

The bot matches it literally, so paste it. You sign once, and later pull requests are not gated again. Signatures are recorded in a separate repository. CLA.md also describes how to sign out of band.

What it means:

• You keep your copyright. Nothing is assigned or transferred.
• You grant the project owner a licence to use your contribution under any terms, including commercially, as well as under the GPL. This is what makes paid modules on top of an open core possible, and those fund the project.
• Your contribution stays open. The owner commits to keeping every merged contribution available under an OSI-approved licence. It can be licensed additionally, never withdrawn.
• Attribution is kept in the Git history and file notices.
• It has no non-compete and does not restrict what you do with your own code.

CLA.md closes with a section called "Why this exists" that states the asymmetry plainly. It is not legal advice; if you contribute for an employer, have your own counsel read it.

If you would rather not sign, that is fine and not held against you. Open an issue describing the change instead. It will be implemented independently, and you will be credited in the commit message.

Code of conduct

The project follows the Contributor Covenant, version 2.1. By taking part you agree to uphold it. The address for reporting unacceptable behaviour is given in the Enforcement section of CODE_OF_CONDUCT.md. Reports are handled in confidence.

Licence

AstroBaaS is free software under the GNU General Public License, version 3 or later (GPL-3.0-or-later). The full text is in LICENSE.

What you may do

Everything the GPL grants, for any purpose, including commercial use:

• Run it. Any number of installs and shops. No fee, no key, no registration. There is no licence check anywhere in the code.
• Read and change it. It is your copy.
• Redistribute it, modified or not, including selling it, as long as you pass on the same freedoms and make the corresponding source available under the GPL.

Running AstroBaaS to serve your own site is not distribution. Your content, customisations and data are yours, and nothing reports home.

Paid vertical modules

What is sold separately sits one level above the core: vertical modules. Each is a theme plus plugins built for one trade, such as optical and eyewear shops, hotels and short stays, or restaurants.

• None of them is in this repository, and none is on sale yet. The core carries only the plugin hooks such a module would load through. See Plugins.
• Commerce is not one of them. The shop, payments and checkout are part of the GPL core. See Commerce.
• The core behaves the same without them. Nothing is removed from core to create a gap for a module.
• No licence check on the request path, and nothing in this repository refuses to run.

Third-party plugins and themes

Whether a plugin running inside a GPL host is a derivative work is an unsettled question. The project takes no position and asserts nothing against plugin authors. Get your own advice if it matters to your business.

Dependencies and the name

• Runtime dependencies are permissive (MIT, ISC, Apache-2.0, BSD). Exceptions and their obligations are listed in THIRD-PARTY-NOTICES.md. npm run audit:licenses runs on every pull request.
• "AstroBaaS" is the project's name. The GPL covers the code, not the name, so a fork is free to exist and compete under a name of its own.

API stability

If you build themes, plugins or storefronts, depend only on the public surface:

• astrobaas/core, astrobaas/plugins and astrobaas/client.
• Anything under src/lib/*, src/pages/* or src/components/* is internal and can change in any release.
• AstroBaaS is pre-1.0. Additive changes can land in any minor release. Breaking changes to the public surface are allowed but listed under Breaking in the changelog, with the reason and a migration note. Hook names in PLUGIN_HOOKS are never silently renamed or removed.
• From 1.0, the public surface follows semver.
• The on-disk db.json format and the admin's HTML structure are not covered.

tests/stability.test.mjs checks that every export of the three public entry points is documented.

See also

• Architecture: how the pieces fit
• Plugins and Themes: writing extensions
• SDK-CLI-and-MCP: the public client packages
• Security: reporting vulnerabilities
• Upgrading: breaking changes between releases
• LICENSE