waitspin 0.1.2 → 0.1.4

package/README.md

@@ -5,25 +5,47 @@ wait-state ads for verified developer surfaces.
 
 ## Install
 
-Run this only after `npm view waitspin version` succeeds in launch evidence:
+Run after `npm view waitspin version` succeeds in launch evidence:
 
 Before install, publisher registration, or Checkout, review:
 
 - Public API and agent docs: `https://waitspin.com/waitspin/docs`
+- Agent markdown: `https://waitspin.com/.well-known/agents.md`
 - Terms: `https://waitspin.com/waitspin/terms`
 - Privacy: `https://waitspin.com/waitspin/privacy`
 
-Refund/account-credit policy: unused prepaid blocks are account credit unless a
-cash refund is required by law or approved through support review. Self-serve
-cash refund requests and credit redemption are not public launch capabilities
-yet.
+Refund/account-credit disclosure: unused prepaid block handling is
+support-reviewed. No automated account-credit balance, redemption flow, or
+self-serve cash refund request flow is shipped yet.
 
 ```bash
 npm view waitspin version
 npx --yes waitspin init --email you@example.com --key-profile control
-export WAITSPIN_API_KEY=wts_live_...
-waitspin extension install --target vscode
+export WAITSPIN_API_KEY=PASTE_CONTROL_KEY
+waitspin bid create --line "Your ad" --url https://example.com --price-per-block 500 --blocks 1
+waitspin bid checkout CAMPAIGN_ID
+npx --yes waitspin init --email you@example.com --key-profile publisher-extension
+
+# Advanced agent install for every detected supported target
+waitspin install --all --dry-run --api-key PASTE_PUBLISHER_EXTENSION_KEY --compose-existing
+waitspin install --all --api-key PASTE_PUBLISHER_EXTENSION_KEY --compose-existing
+waitspin status --all
+
+# Install for VS Code status-bar fallback
+waitspin extension install --target vscode --api-key PASTE_PUBLISHER_EXTENSION_KEY
 waitspin extension status --target vscode
+
+# Or install for Claude Code statusline
+waitspin claude-code install --api-key PASTE_PUBLISHER_EXTENSION_KEY --compose-existing
+waitspin claude-code status
+
+# Or install for MiMo Code shell hook
+waitspin mimocode install --api-key PASTE_PUBLISHER_EXTENSION_KEY
+waitspin mimocode status
+
+# Or install for OpenCode TUI plugin slot
+waitspin opencode install --api-key PASTE_PUBLISHER_EXTENSION_KEY
+waitspin opencode status
 ```
 
 ## Commands
@@ -31,7 +53,7 @@ waitspin extension status --target vscode
 - `waitspin init` — email OTP onboarding
 - `waitspin bid create` — create a campaign draft
 - `waitspin bids list` — list campaigns
-- `waitspin bid checkout <campaign-id>` — Stripe Checkout for blocks
+- `waitspin bid checkout CAMPAIGN_ID` — Stripe Checkout for blocks
 - `waitspin market` — public leaderboard
 - `waitspin wallet connect` — Stripe Connect Express onboarding
 - `waitspin wallet status` — publisher balance, payout, and Connect status
@@ -40,31 +62,60 @@ waitspin extension status --target vscode
 - `waitspin extension install --target vscode` — install the VS Code status-bar fallback
 - `waitspin extension status --target vscode` — inspect managed fallback lifecycle state
 - `waitspin extension uninstall --target vscode` — remove the managed fallback runtime and local state
+- `waitspin install --all --dry-run` — preview detected publisher targets without file changes
+- `waitspin install --all` — install every detected supported publisher target
+- `waitspin status --all` — aggregate lifecycle status for every publisher target
+- `waitspin claude-code install --compose-existing` — install the Claude Code statusline command
+- `waitspin claude-code status` — inspect managed Claude Code runtime state
+- `waitspin claude-code uninstall` — restore Claude Code statusline settings and remove managed local state
+- `waitspin mimocode install` — install the MiMo Code shell hook
+- `waitspin mimocode status` — inspect managed MiMo Code runtime state
+- `waitspin mimocode uninstall` — remove managed MiMo Code runtime and bash hook
+- `waitspin opencode install` — install the OpenCode TUI plugin slot
+- `waitspin opencode status` — inspect managed OpenCode runtime state
+- `waitspin opencode uninstall` — remove managed OpenCode runtime and plugin
 
 API base: `https://api.waitspin.com`
 
-The public package currently installs only the verified VS Code status-bar
-fallback. Native Claude/Codex spinner patching is deferred until that lifecycle
-has its own install/status/uninstall proof.
+The public package installs four verified publisher targets: the VS Code
+status-bar fallback, the Claude Code statusline command, the MiMo Code shell
+hook, and the OpenCode TUI plugin slot. Claude Code support uses the official
+`statusLine.command` path and does not patch Claude Code internals. MiMo Code
+uses a bash hook that polls the API for sponsored messages. OpenCode uses its
+TUI `app_bottom` plugin slot.
+
+`waitspin install --all` is an advanced agent command for installing every
+detected supported target. It keeps explicit target commands as the canonical
+debug path, supports `--dry-run`, skips unsupported local tools in
+`skipped_not_detected`, reports recoverable config conflicts in
+`skipped_conflict`, and reports unexpected installer failures in
+`failed_rollback`.
 
 Payout execution is guarded server-side. Public launch proof uses Stripe test
 mode with `waitspin wallet payout --confirm-test-transfer`; live transfers stay
 disabled until the operator enables the explicit live payout flags.
 
-Native Claude Code/Codex spinner patches, account-credit redemption, cash refund
-self-service, and click billing are not public paid-launch capabilities yet.
+Native spinner patches beyond supported status surfaces, account-credit
+redemption, cash refund self-service, and click billing are not public
+paid-launch capabilities yet.
 
-## VS Code publisher credentials
+## Publisher credentials
 
-Use a publisher-extension key for extension polling/events:
+Use a publisher-extension key for publisher polling/events:
 
 ```bash
 npx waitspin init --email you@example.com --key-profile publisher-extension
-npx waitspin extension install --target vscode --api-key wts_live_...
+npx waitspin install --all --dry-run --api-key PASTE_PUBLISHER_EXTENSION_KEY --compose-existing
+npx waitspin install --all --api-key PASTE_PUBLISHER_EXTENSION_KEY --compose-existing
+npx waitspin status --all
+npx waitspin extension install --target vscode --api-key PASTE_PUBLISHER_EXTENSION_KEY
+npx waitspin claude-code install --api-key PASTE_PUBLISHER_EXTENSION_KEY --compose-existing
+npx waitspin mimocode install --api-key PASTE_PUBLISHER_EXTENSION_KEY
+npx waitspin opencode install --api-key PASTE_PUBLISHER_EXTENSION_KEY
 ```
 
 - `WAITSPIN_API_KEY` — temporary publisher-extension key for first activation
-- `WAITSPIN_INSTALL_ID` — from `waitspin extension install`
+- `WAITSPIN_INSTALL_ID` — from `waitspin extension install` or `waitspin claude-code install`
 
 The VS Code extension migrates `waitspin.apiKey` from User settings into VS Code
 SecretStorage on activation. `WAITSPIN_API_KEY` is an env-only temporary
@@ -72,13 +123,28 @@ fallback and is not persisted by the extension. Store `waitspin.installId` in
 User settings; do not store broad control keys or workspace-scoped credentials
 for normal publisher operation.
 
+The Claude Code installer writes a managed statusline runtime/state under
+`~/.waitspin` and updates `~/.claude/settings.json` with a safe
+`statusLine.command`. It fails fast when an existing unmanaged statusline is
+present unless `--compose-existing` is explicitly requested and restorable.
+
+The MiMo Code installer writes a managed runtime script under `~/.local/bin/`
+and a bash hook in `~/.bashrc`. It polls the API for sponsored messages and
+displays them in the terminal.
+
+The OpenCode installer writes a managed runtime/state under `~/.waitspin`,
+installs a TUI plugin under `~/.config/opencode/plugins`, and adds the managed
+entry to `~/.config/opencode/tui.json` so OpenCode mounts the `app_bottom` slot.
+
 ## Release validation
 
 Before advertising the public `npx waitspin` path, release operators should run:
 
 ```bash
-npm pack --dry-run --json
+npm --workspace packages/waitspin pack --dry-run --json
 npm run test:waitspin:distribution
 npm view waitspin version
 npx --yes waitspin --help
+npx --yes waitspin@latest mimocode status
+npx --yes waitspin@latest opencode status
 ```

package/assets/waitspin-mimocode/README.md

@@ -0,0 +1,169 @@
+# WaitSpin MiMo Code Integration
+
+WaitSpin publisher support for MiMo Code CLI — sponsored status-line messages
+in your terminal.
+
+## Quick Start
+
+```bash
+# 1. Get a publisher-extension key
+npx waitspin init --email you@example.com --key-profile publisher-extension
+
+# 2. Install for MiMo Code
+waitspin mimocode install --api-key wts_live_...
+
+# 3. Check status
+waitspin mimocode status
+
+# 4. Restart your shell or run:
+source ~/.bashrc
+```
+
+## How It Works
+
+1. **Install** registers your install ID with WaitSpin and adds a bash hook
+2. **Runtime** polls `POST /v1/serve/next` every 15 seconds for sponsored messages
+3. **Display** shows the ad line in your terminal: `── Sponsored message ──`
+4. **Impression** records a billable view after 5 seconds of visibility
+
+## Commands
+
+### `waitspin mimocode install`
+
+Register publisher and configure shell integration.
+
+```bash
+waitspin mimocode install --api-key wts_live_...
+waitspin mimocode install --dry-run  # preview without changes
+```
+
+Options:
+- `--api-key KEY` — publisher-extension API key (or set `WAITSPIN_API_KEY`)
+- `--dry-run` — show what would be done without making changes
+
+### `waitspin mimocode status`
+
+Show installation state and health.
+
+```bash
+waitspin mimocode status
+```
+
+Output includes:
+- `install_id` — unique install identifier
+- `publisher_id` — registered publisher ID
+- `publisher_registered` — whether registration succeeded
+- `runtime_exists` — whether runtime script is present
+- `bashrc_hook` — whether shell hook is installed
+
+### `waitspin mimocode uninstall`
+
+Remove all managed files and hooks.
+
+```bash
+waitspin mimocode uninstall
+waitspin mimocode uninstall --dry-run  # preview without changes
+```
+
+Removes:
+- `~/.waitspin/mimocode-statusline.json`
+- `~/.waitspin/mimocode-statusline-cache.json`
+- Bash hook from `~/.bashrc`
+
+## Runtime Script
+
+The runtime script (`waitspin-mimocode-runtime`) can be called directly:
+
+```bash
+# Fetch and display one ad line
+waitspin-mimocode-runtime
+
+# Use in a custom prompt
+PS1="$(__waitspin_statusline)\n$ "
+```
+
+The generated runtime strips terminal control characters from sponsor text
+before the bash hook renders it.
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `WAITSPIN_API_KEY` | — | Publisher-extension API key |
+| `WAITSPIN_BASE_URL` | `https://api.waitspin.com` | API base URL |
+| `WAITSPIN_DEV` | — | Must be `1` before dev override executables are honored |
+| `WAITSPIN_CLI_JS` | — | Development-only CLI delegator override |
+| `WAITSPIN_MIMOCODE_RUNTIME` | — | Development-only runtime launcher override |
+
+### State Files
+
+| File | Purpose |
+|------|---------|
+| `~/.waitspin/mimocode-statusline.json` | Install state (API key, install ID) |
+| `~/.waitspin/mimocode-statusline-cache.json` | Runtime cache (active serve) |
+
+## Trust and Warmup
+
+New publishers start at trust level 1/10. The serve endpoint returns empty
+inventory until trust warms up. Expected warmup: ~10 days.
+
+During warmup, `waitspin-mimocode-runtime` exits silently (no output, no errors).
+
+## Security
+
+- API key stored with `chmod 600` (owner read/write only)
+- Runtime never logs or echoes credentials
+- No credentials written to MiMo Code config files
+- State file is isolated in `~/.waitspin/`
+- `WAITSPIN_CLI_JS` and `WAITSPIN_MIMOCODE_RUNTIME` are ignored unless
+  `WAITSPIN_DEV=1`. They are development-only trust-boundary overrides; do not
+  set them in shared shells, CI, or production-like environments unless you
+  intentionally trust the executable.
+
+## Differences from VS Code Extension
+
+| Aspect | VS Code | MiMo Code |
+|--------|---------|-----------|
+| Display | Status bar item | Terminal output |
+| Runtime | Packaged extension | Node.js runtime invoked by bash hook |
+| Auth storage | VS Code SecretStorage | `~/.waitspin/` state file |
+| Polling | Extension host interval | Prompt hook/runtime interval |
+| Impression | After min_visible_ms | After min_visible_ms |
+
+## Architecture
+
+See [MIMOCODE_ARCHITECTURE.md](./MIMOCODE_ARCHITECTURE.md) for detailed
+architecture documentation.
+
+## Files
+
+```
+packages/waitspin/assets/waitspin-mimocode/
+├── README.md                    # This file
+├── mimocode-install.sh          # CLI delegator for install
+├── mimocode-status.sh           # CLI delegator for status
+├── mimocode-uninstall.sh        # CLI delegator for uninstall
+└── mimocode-runtime.sh          # Launcher for generated runtime
+
+docs/waitspin/
+├── MIMOCODE_ARCHITECTURE.md     # Architecture document
+```
+
+## Development
+
+```bash
+# Test with local API
+WAITSPIN_BASE_URL=http://localhost:8787 waitspin mimocode install --dry-run
+
+# Run runtime manually
+WAITSPIN_API_KEY=wts_live_... waitspin-mimocode-runtime
+
+# Check state
+cat ~/.waitspin/mimocode-statusline.json | python3 -m json.tool
+```
+
+## License
+
+MIT — same as the waitspin package.

package/assets/waitspin-mimocode/mimocode-install.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# WaitSpin MiMo Code install script.
+# Delegates to the canonical waitspin CLI implementation.
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage: mimocode-install.sh [waitspin mimocode install options]
+
+This asset intentionally does not duplicate install, registration, or JSON
+logic. Use the package CLI as the single source of truth:
+
+  waitspin mimocode install --api-key KEY
+
+For trusted development only, set WAITSPIN_DEV=1 and WAITSPIN_CLI_JS to a
+local dist/cli.js path.
+EOF
+}
+
+if [ "${1:-}" = "-h" ] || [ "${1:-}" = "--help" ]; then
+  usage
+  exit 0
+fi
+
+if [ -n "${WAITSPIN_CLI_JS:-}" ]; then
+  if [ "${WAITSPIN_DEV:-}" != "1" ]; then
+    echo "WAITSPIN_CLI_JS requires WAITSPIN_DEV=1." >&2
+    exit 126
+  fi
+  exec node "$WAITSPIN_CLI_JS" mimocode install "$@"
+fi
+
+if command -v waitspin >/dev/null 2>&1; then
+  exec waitspin mimocode install "$@"
+fi
+
+cat >&2 <<'EOF'
+waitspin CLI was not found.
+
+Install the package or run from a built checkout, then retry:
+  npm --workspace packages/waitspin run build
+  node packages/waitspin/dist/cli.js mimocode install --api-key KEY
+EOF
+exit 127

package/assets/waitspin-mimocode/mimocode-runtime.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# WaitSpin MiMo Code statusline runtime launcher.
+# The real runtime is generated by `waitspin mimocode install`.
+set -euo pipefail
+
+if [ -n "${WAITSPIN_MIMOCODE_RUNTIME:-}" ]; then
+  if [ "${WAITSPIN_DEV:-}" != "1" ]; then
+    exit 0
+  fi
+  runtime="$WAITSPIN_MIMOCODE_RUNTIME"
+else
+  runtime="$HOME/.local/bin/waitspin-mimocode-runtime"
+fi
+
+if [ ! -x "$runtime" ]; then
+  exit 0
+fi
+
+exec "$runtime" "$@"

package/assets/waitspin-mimocode/mimocode-status.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# WaitSpin MiMo Code status script.
+# Delegates to the canonical waitspin CLI implementation.
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage: mimocode-status.sh [waitspin mimocode status options]
+
+This asset intentionally does not duplicate status, path-safety, or JSON logic.
+Use the package CLI as the single source of truth:
+
+  waitspin mimocode status
+
+For trusted development only, set WAITSPIN_DEV=1 and WAITSPIN_CLI_JS to a
+local dist/cli.js path.
+EOF
+}
+
+if [ "${1:-}" = "-h" ] || [ "${1:-}" = "--help" ]; then
+  usage
+  exit 0
+fi
+
+if [ -n "${WAITSPIN_CLI_JS:-}" ]; then
+  if [ "${WAITSPIN_DEV:-}" != "1" ]; then
+    echo "WAITSPIN_CLI_JS requires WAITSPIN_DEV=1." >&2
+    exit 126
+  fi
+  exec node "$WAITSPIN_CLI_JS" mimocode status "$@"
+fi
+
+if command -v waitspin >/dev/null 2>&1; then
+  exec waitspin mimocode status "$@"
+fi
+
+cat >&2 <<'EOF'
+waitspin CLI was not found.
+
+Install the package or run from a built checkout, then retry:
+  npm --workspace packages/waitspin run build
+  node packages/waitspin/dist/cli.js mimocode status
+EOF
+exit 127

package/assets/waitspin-mimocode/mimocode-uninstall.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# WaitSpin MiMo Code uninstall script.
+# Delegates to the canonical waitspin CLI implementation.
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage: mimocode-uninstall.sh [waitspin mimocode uninstall options]
+
+This asset intentionally does not duplicate uninstall, restore, path-safety, or
+JSON logic. Use the package CLI as the single source of truth:
+
+  waitspin mimocode uninstall
+
+For trusted development only, set WAITSPIN_DEV=1 and WAITSPIN_CLI_JS to a
+local dist/cli.js path.
+EOF
+}
+
+if [ "${1:-}" = "-h" ] || [ "${1:-}" = "--help" ]; then
+  usage
+  exit 0
+fi
+
+if [ -n "${WAITSPIN_CLI_JS:-}" ]; then
+  if [ "${WAITSPIN_DEV:-}" != "1" ]; then
+    echo "WAITSPIN_CLI_JS requires WAITSPIN_DEV=1." >&2
+    exit 126
+  fi
+  exec node "$WAITSPIN_CLI_JS" mimocode uninstall "$@"
+fi
+
+if command -v waitspin >/dev/null 2>&1; then
+  exec waitspin mimocode uninstall "$@"
+fi
+
+cat >&2 <<'EOF'
+waitspin CLI was not found.
+
+Install the package or run from a built checkout, then retry:
+  npm --workspace packages/waitspin run build
+  node packages/waitspin/dist/cli.js mimocode uninstall
+EOF
+exit 127