spark-control/docs/guides/startos-package.md

paths

paths
package/**

StartOS package (package/)

TypeScript wrapper that ships the Docker image as an s9pk. @start9labs/start-sdk pinned 1.3.3, Node ≥22, bundled by @vercel/ncc.

Commands

cd package
npm i          # one-time
make x86       # typecheck + ncc bundle + docker build + pack → spark-control_x86_64.s9pk
make install   # sideload to the Start9 server; needs "host: http(s)://<server>.local" in ~/.startos/config.yaml
npm run check      # tsc --noEmit — run after any startos/ edit; make x86 also runs it
npm run prettier   # prettier --write startos (no semicolons, single quotes, trailing commas)

make aarch64 for ARM Start9 servers. make install picks the newest *.s9pk in package/ and restarts the live spark-control service — get a go/no-go first.

Versioning & release notes

• Version format is X.Y.Z:N (:N = revision). Bump in package/startos/versions/v0_1_0.ts; replace the release notes — never leave old notes behind under an extra key (any unknown key fails tsc).
• New external-facing endpoints get noted in release notes for downstream app developers (Recap Relay, Ten31 Transcripts, CRM, Signal Engine consume these APIs).

Releasing to Gitea

The s9pk is distributed via Gitea Releases (the binary is gitignored — never commit it). Adopters pull the latest asset with a read-only token. Per-version ritual:

# 1. bump version in startos/versions/v0_1_0.ts (+ replace release notes), then:
cd package && make x86                       # build
# 2. commit + push the source change
git tag vX.Y.Z && git push gitea vX.Y.Z      # tag — plain vX.Y.Z, NO ':' (git refs forbid it)
make install                                 # optional: sideload to your own server (restarts it — go/no-go)
# 3. publish the s9pk as a release asset (needs a write-scoped token):
GITEA_URL=https://<gitea-host> GITEA_TOKEN=<write-token> make release

make release → scripts/gitea-release.sh: creates/reuses the release for the tag and uploads (replacing) the s9pk asset; idempotent, fails loud on real HTTP errors. GITEA_INSECURE=1 skips TLS verify for a self-signed LAN cert. Hand adopters a read-only token (repository: Read), ideally on a dedicated reader account; their agent then GETs /api/v1/repos/<owner>/spark-control/releases/latest and downloads the .s9pk asset. Note Gitea returns browser_download_url on its configured ROOT_URL (may be a .local name) — an off-LAN adopter pulls via whatever address actually reaches the Gitea.

Layout

• package/startos/ — manifest, interfaces, actions (configureSparks, showPublicKey), versions/v0_1_0.ts (current version string + release notes).
• The "Reapply speech-model patches" action is not a StartOS action — it's a dashboard action implemented in image/app/speech_models.py.