Publishing

Reference for what `publish` does, how versioning works, and what changes will break users.

sdk-i99dash publish

Does:

Validate manifest.json (zod).
Build via your buildCommand if set, else copy appRoot/ → distDir/.
Stamp manifest.json into distDir.
Tarball distDir → deterministic .tar.gz in temp.
Request a presigned upload URL from the backend.
Upload the tarball to the presigned URL (direct-to-CDN).
Submit the manifest with the bundle id to the catalog.

--dry-run runs 1–4 and stops. Useful for CI smoke checks before you have an API key provisioned.

Tracks: production vs beta

By default, publish lands on the production track — every user sees the new bundle on next launch. Pass --track beta to ship to a limited cohort of testers instead:

sdk-i99dash publish --track beta --release-notes "Rebased map tiles"

The bundle is the same; only the catalog pointer changes. Full walkthrough — inviting testers, promoting beta to production, and the limits — is at Beta testing.

What "published" means

After submit, your app enters one of two states:

`reviewStatus`	Meaning
`auto-approved`	Your app is live in the catalog immediately.
`pending`	A human review is queued. You can keep iterating locally; re-running `publish` bumps a new bundle under the same review ticket.

The version field is opaque to the backend but has one rule you can't dodge: incrementing is mandatory per publish. The backend rejects a resubmission with the same id and version. Pick semver (1.2.3) so the number reflects the change size.

The id is durable and should never change post-publish — it lives in pinned home-screen shortcuts on users' devices. Rotating id orphans every launcher icon anyone ever pinned for your app.

Updating after publish

Just sdk-i99dash publish again with a new version. No separate "update" command — publish is idempotent per (id, version).

Versioning strategy

You changed…	Bump
Copy / CSS only	patch (`1.2.3` → `1.2.4`)
New feature, backwards compatible	minor (`1.2.3` → `1.3.0`)
Bridge contract dependency (new host version needed)	major (`1.2.3` → `2.0.0`) — bump `minHostVersion` too

What breaks users

Change	Breaks
Rotate `id`	Orphans every pinned home-screen shortcut. Don't.
Drop a locale from `name`	Users on that locale see a fallback. Not strictly broken, but noticeable.
Bump `minHostVersion`	Users on older hosts see an "update your app" card instead of your mini-app.
Change `url` origin	Host rejects at launch unless the new origin is allow-listed. Coordinate with ops.
Flip `safeWhileDriving: true` → `false`	Users get the "not available while driving" dialog they didn't used to see. Communicate in release notes.

CI integration

# .github/workflows/publish.yml
- run: pnpm install --frozen-lockfile
- run: sdk-i99dash validate
- run: sdk-i99dash build
- run: sdk-i99dash publish
  env:
    I99DASH_API_KEY: ${{ secrets.I99DASH_API_KEY }}

Use validate as a PR check; reserve publish for tag-triggered workflows.