@go-labs-sg/gosh 0.1.0

package/README.md

@@ -0,0 +1,149 @@
+# GOSH CLI
+
+`@go-labs-sg/gosh` provides the `gosh` binary for permission-aware GOSH organizer operations and agent automation. It calls the same tRPC procedures as the web app using the authorizing user's global, organization, and event permissions.
+
+## Runtime and installation
+
+The CLI requires [Bun](https://bun.com/docs/installation) 1.4.0 or newer. npm remains the package distribution channel, while the installed `gosh` command runs under Bun.
+
+Check whether a compatible Bun version is already available:
+
+```bash
+bun --version
+```
+
+If Bun is missing, install it for the current operating system:
+
+**macOS (Homebrew)**
+
+```bash
+brew install oven-sh/bun/bun
+```
+
+**Windows (PowerShell)**
+
+```powershell
+powershell -c "irm bun.sh/install.ps1|iex"
+```
+
+**Linux**
+
+```bash
+curl -fsSL https://bun.com/install | bash
+```
+
+If Bun is installed but older than 1.4.0, run `bun upgrade`. Open a new terminal if the installer changes `PATH`, then verify `bun --version` again. Installation agents should skip the platform installer when Bun 1.4.0 or newer is already available.
+
+Install and verify the CLI:
+
+```bash
+bun add --global @go-labs-sg/gosh
+gosh version
+```
+
+## Authentication
+
+```bash
+gosh auth login
+gosh auth status
+gosh auth whoami
+```
+
+`gosh auth login` opens GOSH in your browser. Sign in through the normal web flow if needed, confirm that the displayed device and code match your terminal, and click **Authorize CLI**. The CLI polls automatically, then stores the product-issued credentials exclusively through `Bun.secrets` in the operating system credential store. No Google credentials are stored by the CLI.
+
+GOSH CLI access is limited to global administrators. The server rechecks the account's current global role and ban state when issuing, refreshing, and authenticating CLI credentials, so removing the admin role immediately blocks further CLI access.
+
+Use `gosh auth logout` to revoke the remote CLI session and remove the local credential. Use `GOSH_API_URL` or `--api-url` to target another HTTPS deployment; plain HTTP is accepted only for localhost development. Pass `--no-browser` when working over SSH or in a container and open the printed URL on another device.
+
+## Commands and JSON input
+
+Discover the current command surface instead of guessing payloads:
+
+```bash
+gosh commands
+gosh help event list
+gosh health status
+gosh organization list
+gosh event list --input '{"organizationId":"acme"}'
+gosh event get --input '{"organizationId":"acme","eventId":"event-id"}'
+```
+
+Commands use `--input '<json>'` for the exact validated tRPC input object. This preserves the GOSH API's typed validation without maintaining a second set of lossy CLI flags. See [command-reference.md](./command-reference.md) or import `@go-labs-sg/gosh/command-manifest` for the generated catalogue.
+
+The command registry covers every callable GOSH tRPC procedure: organizer and global-admin operations, organization invitations and membership, player workflows, public results/login procedures, uploads, and realtime subscriptions. The compile-time registry test fails whenever a new API procedure is added without a CLI command.
+
+### Local file uploads
+
+Upload commands add the local file metadata to the supplied API input, request a permission-scoped signed URL, and upload the bytes directly to storage without sending the GOSH CLI access token to storage:
+
+```bash
+gosh upload branding \
+  --file ./logo.png \
+  --input '{"eventId":"event-id","assetType":"logo"}' \
+  --target event-id \
+  --allow-state-change \
+  --allow-external-write
+
+gosh player mission upload \
+  --file ./proof.mp4 \
+  --input '{"eventId":"event-id","missionId":"mission-id"}' \
+  --target mission-id \
+  --allow-state-change \
+  --allow-external-write
+```
+
+Mission videos use GOSH's multipart upload protocol automatically. Failed multipart uploads are aborted best-effort, and signed URLs are never included in the final JSON envelope or debug output.
+
+### Submission media exports
+
+Queue all original photo and video submissions as a ZIP organized by event and
+then by team or individual participant. GOSH emails the requester when the
+archive is ready and keeps it available for 30 days.
+
+```bash
+gosh event submissions request-image-export \
+	--input '{"organizationId":"acme","eventId":"event-id"}' \
+	--target event-id \
+	--allow-state-change \
+	--allow-email \
+	--allow-external-write
+
+gosh event submissions image-exports \
+	--input '{"organizationId":"acme","eventId":"event-id"}'
+```
+
+### Realtime watches
+
+`gosh player watch` and `gosh submission watch` keep an authenticated SSE connection open and emit one JSON envelope per line. Press Ctrl-C to close the stream cleanly:
+
+```bash
+gosh submission watch --input '{"organizationId":"acme","eventId":"event-id"}'
+```
+
+### Global administration
+
+Global admins can list users, change global roles, and ban or unban accounts under `gosh admin users …`. Banning an account atomically revokes its active browser and CLI sessions.
+
+## Mutation safety
+
+Mutations require `--target` to exactly match an identifier in `--input` (such as an `eventId`, `stationId`, slug, or name), binding the confirmation to the payload. In non-interactive automation, every applicable effect flag is also required:
+
+- `--allow-state-change`
+- `--allow-email`
+- `--allow-external-write`
+- `--allow-delete`
+
+Example after reviewing the event and obtaining explicit approval:
+
+```bash
+gosh event update-status \
+  --input '{"organizationId":"acme","eventId":"event-id","status":"LIVE"}' \
+  --target 'event-id' \
+  --allow-state-change
+```
+
+Without the allow flags, an interactive terminal prints a workflow preview and requires the exact response `CONFIRM`. Read-only commands never prompt.
+
+## Output
+
+One-shot commands write one JSON envelope to stdout. Watch commands write newline-delimited JSON envelopes. Failures and opt-in `--debug` diagnostics go to stderr, and known secrets, payloads, join codes, share tokens, and signed URLs are redacted. `--quiet` or `-q` suppresses diagnostics.