# Contributing

This repo packages [SpacesOps](https://git.spacesops.com/spacesops/spacesops)
for StartOS.

## Documentation — keep it in sync

- **`README.md`** — what this package is and how it's built (image, volume,
  interface, dependency, actions). For developers and AI assistants.
- **`instructions.md`** — the user-facing instructions packed into the `.s9pk`
  and shown on the **Instructions** tab in StartOS.
- **`CONTRIBUTING.md`** — this file.

**Any code change that warrants it must update `README.md` and `instructions.md`
in the same change** — a new or renamed action, an added or removed volume /
port / interface / dependency, a changed default, a new limitation, any altered
user-visible behavior. A package that ships with a stale README or stale
instructions is not done, even if the code is perfect. Content rules:
[Writing READMEs](https://docs.start9.com/packaging/writing-readmes.html).

## Building

See the [StartOS Packaging Guide](https://docs.start9.com/packaging/) for
environment setup, then:

```bash
npm ci            # install dependencies
make              # build the .s9pk for x86_64 and aarch64
```

`npm run check` runs the TypeScript type-check; `npm run build` bundles
`startos/` into `javascript/index.js` with `@vercel/ncc` (which inlines
`nostr-tools`, used to derive and encode the operator keypair).

## Updating the upstream version

SpacesOps runs the `docker.io/spacesops/spacesops` image. To track a new
upstream release:

1. Bump `dockerTag` in `startos/manifest/index.ts` to
   `spacesops/spacesops:<new version>`.
2. Update `version` and `releaseNotes` in the file under `startos/versions/`,
   renaming it to the new version string. A *new* version file is only needed
   when the bump carries an `up`/`down` migration, or when you want the old
   release notes preserved in git history — see
   [Versions](https://docs.start9.com/packaging/versions.html).
3. Rebuild (`make`), sideload the `.s9pk`, and confirm it starts and connects to
   Spaces.
4. Review `README.md` and `instructions.md` for anything the bump changed.

## How auto-wiring to Spaces works

`startos/main.ts` mounts the Spaces `main` volume read-only at `/spaces-data`,
execs `cat /spaces-data/store.json` inside the subcontainer, and reads
`spacedAuth.{username,password}` to populate `SPACED_RPC_USER` /
`SPACED_RPC_PASSWORD`. If the file or credentials are missing, it throws so
StartOS restarts the service until Spaces is ready. The Spaces dependency must
expose its `spaces-api` interface and seed `spacedAuth` (Spaces `>=0.0.9:3`).