@mushi-mushi/cli 0.10.0 → 0.11.0

package/CONTRIBUTING.md

@@ -101,17 +101,6 @@ Releases are fully automated. Maintainers don't run `npm publish` by hand.
 
 If GitHub's anti-loop protection suppresses the auto re-fire (the squash merge can be attributed to `github-actions[bot]`), trigger the workflow manually: **Actions → release → Run workflow → master**.
 
-### Known CI/CD quirks and their automatic safeguards
-
-A handful of GitHub-Actions × Changesets edge cases have caused release-pipeline stalls in the past. Each is now caught automatically — keep these in mind when you see the symptom:
-
-| Symptom | Root cause | Automatic safeguard |
-| --- | --- | --- |
-| The `Build & Test` required check never registers on the `chore: version packages` PR — the PR stays "Required check missing" forever | `changeset-release/master` is pushed by `github-actions[bot]`. GitHub silently drops the downstream `pull_request` event to prevent bot loops (observed on PR #45, #102, #124). | `ci.yml` now also triggers on `push` to `changeset-release/master`, so `Build & Test` reports against the head commit directly. No empty-commit nudge needed. |
-| Release workflow fails with `No commits between master and changeset-release/master` after merging a PR with a new changeset. | A `.changeset/*.md` file whose YAML frontmatter only targets packages listed in `.changeset/config.json#ignore` (e.g. `@mushi-mushi/server`, `@mushi-mushi/admin`). `changeset version` produces no bumps, the version PR is empty, the next push errors (PR #102 / #121, 2026-05-19). | `pnpm check:changeset-orphans` runs in both `ci.yml` and `release.yml`. PR CI fails with an actionable message naming the orphan file *before* it can reach master. If you legitimately need to record an internal-only change, omit the changeset entirely — the diff lives in git history. |
-| Release workflow's `Audit signatures of installed dependencies` step fails with `npm ETARGET / No matching version found for @mushi-mushi/<pkg>@<ver>` seconds after the publish step succeeded. | npm's registry CDN can take up to ~30s to propagate a freshly-published manifest. The audit step shells out to `npm install` against the just-published version and races the CDN (observed 2026-05-20, run 26149167393). | The audit step retries with exponential backoff (1, 2, 4, 8, 16, 32s — 63s total) before failing. Sigstore signatures are written at publish time, so a one-off audit failure never indicates a corrupted package — `pnpm view <pkg> version` is the ground truth. |
-| Push to `master` after merging a PR doesn't fire the `Release` workflow. | Same anti-loop protection: when a squash merge is attributed to `github-actions[bot]`, GitHub may suppress the downstream `push` trigger. Sporadic — observed twice in the last 60 days. | `release.yml` keeps `workflow_dispatch` as the manual fallback. Recovery: **Actions → Release → Run workflow → master**. The `Build & Verify` job re-runs identically to the auto-fired path. |
-
 ### Adding a brand-new publishable package
 
 Trusted Publisher bindings are configured **per package** on `npmjs.com` and require the package to already exist on the registry. New packages therefore need a one-time bootstrap before OIDC can take over.

package/README.md

@@ -1,446 +1,170 @@
-# `@mushi-mushi/cli`
+# @mushi-mushi/cli
 
-> **The mutation that closes the loop** — run Mushi Mushi bug-intelligence from
-> your terminal and CI pipelines, without ever opening a browser.
+CLI for Mushi Mushi — set up the SDK in one command, then triage reports and monitor the pipeline from your terminal.
 
-<div align="center">
-
-<a href="https://kensaur.us/mushi-mushi/docs/" title="Full docs with screenshots">
-  <img src="https://raw.githubusercontent.com/kensaurus/mushi-mushi/main/docs/screenshots/tour-pdca-loop.gif" alt="Admin console PDCA tour — what mushi init wires your project into" width="100%" />
-</a>
-
-<sub>↑ what the CLI connects to · <a href="https://kensaur.us/mushi-mushi/docs/admin/">admin docs with screenshots</a></sub>
-
-</div>
-
-## What it does
-
-Like DNA repair enzymes that scan a genome for transcription errors and patch
-them before the next cell division, `mushi-mushi` scans your live project for
-bug patterns, feeds them back into your toolchain, and tells you which ones are
-still open. The CLI is the command-line face of that repair loop:
-
-| Before `@mushi-mushi/cli` | After `@mushi-mushi/cli` |
-|---|---|
-| Open the console to check if the bug you fixed is actually resolved | `mushi reports show <id>` in 1 second |
-| Manually copy SDK snippets into each new project | `mushi init` auto-detects your framework and installs everything |
-| No idea which mistake rules are active | `mushi lessons list` shows the current rule genome |
-| CI doesn't know about lesson files | `mushi sync-lessons` writes `.mushi/lessons.json` every deploy |
-| Debug auth failures by staring at headers | `mushi whoami` confirms key + endpoint in one shot |
-
----
-
-## Quick start
-
-```bash
-# 1. Install globally (or use npx without installing)
-npm install -g @mushi-mushi/cli   # or: pnpm add -g / yarn global add
-
-# 2. Get your credentials from the Mushi console:
-#    Project ID  → https://kensaur.us/mushi-mushi/projects   (copy chip)
-#    API key     → https://kensaur.us/mushi-mushi/settings/api-keys
-
-# 3. Save credentials
-mushi login \
-  --api-key   mushi_xxxxxxxxxxxxxxxxxxxx \
-  --endpoint  https://<ref>.supabase.co/functions/v1/api \
-  --project-id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
-
-# 4. Verify the connection
-mushi whoami
-
-# 5. Set up the SDK in a project
-cd my-app && mushi init
-```
-
----
-
-## Environment variables
-
-All credentials can be supplied via environment variables — ideal for CI
-where a config file per runner is impractical:
-
-| Variable | Description |
-|---|---|
-| `MUSHI_API_KEY` | SDK API key, looks like `mushi_...` |
-| `MUSHI_PROJECT_ID` | Project UUID, from the Projects page |
-| `MUSHI_API_ENDPOINT` | Supabase edge function URL |
-
-Environment variables override `~/.mushirc`. Explicit command-line flags
-override both.
-
-```bash
-# Example: CI usage without any persistent config file
-export MUSHI_API_KEY=mushi_xxxx
-export MUSHI_PROJECT_ID=542b34e0-019e-41fe-b900-7b637717bb86
-export MUSHI_API_ENDPOINT=https://xyz.supabase.co/functions/v1/api
-
-mushi sync-lessons   # writes .mushi/lessons.json
-mushi status         # print project stats
-mushi ping           # smoke-test connectivity
-```
-
----
-
-## Finding your credentials
-
-### API key
-
-1. Open the Mushi console → **Settings → API Keys**
-   (`https://kensaur.us/mushi-mushi/settings`)
-2. Click **Create API key**
-3. Copy the value — it starts with `mushi_`
-
-### Project ID
-
-1. Open the Mushi console → **Projects**
-   (`https://kensaur.us/mushi-mushi/projects`)
-2. On the project card, click the UUID chip to copy it
-3. The UUID looks like `542b34e0-019e-41fe-b900-7b637717bb86`
-
-### API endpoint
-
-Unless you are self-hosting, use:
-```
-https://dxptnwrhwsqckaftyymj.supabase.co/functions/v1/api
-```
-
----
-
-## Commands
-
-### `mushi init`
-
-Set up the Mushi SDK in the current project. Auto-detects framework, installs
-the right package, and writes a minimal config file.
-
-```bash
-mushi init
-mushi init --project-id <uuid> --api-key <key>   # non-interactive (CI)
-mushi init --framework next                       # force a framework
-mushi init --skip-install                         # print install command only
-mushi init --yes                                  # skip confirmation prompts
-```
-
-Supported frameworks: `next`, `react`, `vue`, `nuxt`, `svelte`, `sveltekit`,
-`angular`, `expo`, `react-native`, `capacitor`, `vanilla`.
-
----
-
-### `mushi login`
-
-Save API credentials to `~/.mushirc` (mode `0o600`, readable only by you).
-
-```bash
-mushi login \
-  --api-key   mushi_xxx \
-  --endpoint  https://xyz.supabase.co/functions/v1/api \
-  --project-id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
-```
-
----
-
-### `mushi whoami`
-
-Verify the API key is valid and print which project it belongs to.
-
-```bash
-mushi whoami
-mushi whoami --json   # machine-readable
-```
-
-Example output:
-```
-✓ Authenticated
-  Project:  My App (542b34e0-019e-41fe-b900-7b637717bb86)
-  Endpoint: https://xyz.supabase.co/functions/v1/api
-  Reports:  47 total · 3 open
-```
-
----
-
-### `mushi ping`
-
-Check that the Mushi backend is reachable. Useful as a CI health gate.
-
-```bash
-mushi ping
-mushi ping --json   # { ok: true, status: 200, latency_ms: 42 }
-```
-
----
-
-### `mushi status`
-
-Print a project health summary: report counts by status and severity, fix and
-lesson totals.
+## One-command setup
 
 ```bash
-mushi status
-mushi status --json
+npx @mushi-mushi/cli init
+# equivalently:
+npx mushi-mushi
 ```
 
----
+The wizard:
 
-### `mushi config`
+1. Detects your framework (Next.js, Nuxt, SvelteKit, Angular, Expo, Capacitor, plain React/Vue/Svelte, or vanilla JS) from `package.json` and config files.
+2. Picks the right SDK package (`@mushi-mushi/react`, `@mushi-mushi/vue`, etc.) plus `@mushi-mushi/web` when the framework SDK is API-only.
+3. Detects your package manager (npm / pnpm / yarn / bun) from your lockfile and installs with that — `shell: false`, with Windows `.cmd` shim resolution.
+4. Writes `MUSHI_PROJECT_ID` and `MUSHI_API_KEY` (with the right framework prefix — `NEXT_PUBLIC_`, `NUXT_PUBLIC_`, `VITE_`) to `.env.local` (or `.env`).
+5. Warns you if `.env.local` isn't in `.gitignore` (covers `.env*.local`, `*.local`, etc.).
+6. Prints the framework-specific provider snippet to copy-paste.
+7. Offers to **send a real test report** so you see your first classified bug in the console immediately. Opt out via `--skip-test-report`.
 
-View or update the config stored in `~/.mushirc`.
+It never silently overwrites existing env vars or modifies application code. Pasted credentials are sanitized (stripped of quotes / CR / LF / NUL) and validated against `^proj_[A-Za-z0-9_-]{10,}$` / `^mushi_[A-Za-z0-9_-]{10,}$` before anything is written to disk.
 
-```bash
-mushi config                                # show all config
-mushi config apiKey mushi_xxx               # update a value
-mushi config endpoint https://...           # update endpoint
-mushi config projectId <uuid>              # update project ID
-```
-
----
-
-### `mushi reports list`
-
-List recent reports for the project.
-
-```bash
-mushi reports list
-mushi reports list --status new --severity critical
-mushi reports list --search "login button"
-mushi reports list --limit 50 --json
-```
-
-Options:
-- `--limit <n>` — max results, 1–100 (default: 20)
-- `--status` — filter: `new`, `triaged`, `in_progress`, `resolved`, `dismissed`
-- `--severity` — filter: `critical`, `high`, `medium`, `low`
-- `--search <query>` — full-text search in summary and description
-- `--json` — machine-readable output
-
----
-
-### `mushi reports show <id>`
-
-Print full details for a single report including environment, breadcrumbs, and
-linked fix.
-
-```bash
-mushi reports show 7f3e8c20-...
-mushi reports show 7f3e8c20-... --json
-```
-
----
-
-### `mushi reports triage <id>`
-
-Update the status and/or severity of a report, and optionally add a note.
+### Flags
 
 ```bash
-mushi reports triage <id> --status triaged --severity high
-mushi reports triage <id> --status in_progress --note "assigned to @alice"
-mushi reports triage <id> --severity critical --json
+mushi init --framework next                             # skip framework detection
+mushi init --project-id proj_xxx --api-key mushi_xxx    # skip credential prompts
+mushi init --skip-install                               # print the install command instead
+mushi init --skip-test-report                           # don't offer to send a test report
+mushi init --cwd apps/web                               # run in a sub-package of a monorepo
+mushi init --endpoint https://mushi.your-company.com    # self-hosted Mushi API
+mushi init -y                                           # accept the detected framework
 ```
 
----
-
-### `mushi reports resolve <id>`
-
-Mark a report resolved. Shorthand for `triage --status resolved`.
+Non-interactive use (CI): pass `--yes --project-id proj_xxx --api-key mushi_xxx` or the wizard exits with a clear error instead of hanging on a prompt.
 
-```bash
-mushi reports resolve <id>
-mushi reports resolve <id> --note "fixed in PR #123"
-```
+Stale-version hint: the wizard checks the npm registry (2s timeout) and prints a one-line upgrade nudge if a newer stable is published. Opt out with `MUSHI_NO_UPDATE_CHECK=1`.
 
----
+Monorepo awareness: if you run the wizard at a workspace root with no framework dep, it scans `apps/*`, `packages/*`, `examples/*` and tells you which sub-package you probably meant (`mushi init --cwd apps/web`).
 
-### `mushi reports reopen <id>`
-
-Reopen a resolved or dismissed report.
+## Install globally
 
 ```bash
-mushi reports reopen <id>
-mushi reports reopen <id> --note "regression in v2.1"
+npm install -g @mushi-mushi/cli
+mushi --help
+mushi --version
 ```
 
----
-
-### `mushi reports dismiss <id>`
-
-Dismiss a report (not a real bug / out of scope).
+## Other commands
 
 ```bash
-mushi reports dismiss <id>
-mushi reports dismiss <id> --note "working as intended"
+mushi login --api-key mushi_xxx     # store credentials in ~/.mushirc (mode 0o600)
+mushi status                         # project overview
+mushi reports list                   # recent reports
+mushi reports show <id>              # one report
+mushi reports triage <id> --status acknowledged --severity high
+mushi deploy check                   # edge-function health probe
+mushi index <path>                   # walk a local repo and feed RAG
+mushi test                           # submit a test report end-to-end
+mushi migrate                        # suggest the most relevant migration guide
+mushi migrate --json                 # machine-readable JSON for CI
+mushi config endpoint https://...    # set API endpoint (https:// required outside localhost)
+mushi sourcemaps upload --release <ver> --dir <dist>   # upload .js.map / .css.map (sha256-idempotent)
 ```
 
----
-
-### `mushi reports search <query>`
-
-Search reports by keyword. Equivalent to `reports list --search <query>`.
-
-```bash
-mushi reports search "button not working"
-mushi reports search "404" --status new --limit 20 --json
-```
-
----
-
-### `mushi lessons list`
-
-List active mistake rules (lessons) extracted from past bug reports.
-
-```bash
-mushi lessons list
-mushi lessons list --severity critical
-mushi lessons list --limit 100 --json
-```
-
----
-
-### `mushi lessons show <id>`
-
-Print full detail for a lesson: rule text, anti-pattern, and summary paragraph.
-
-```bash
-mushi lessons show <lesson-uuid>
-mushi lessons show <lesson-uuid> --json
-```
-
----
-
-### `mushi sync-lessons`
+### `mushi sourcemaps upload`
 
-Pull all active lessons from the Mushi API and write `.mushi/lessons.json`
-into the repo. Used in CI to keep the lesson file fresh for the Mushi MCP
-server and Cursor rules.
+Recursively scans `--dir` for `.js.map` and `.css.map` files and uploads them
+under the given `--release`. Each file is hashed (sha256) and skipped if the
+server already has it for that release, so the command is safe to run from
+every CI build without churning storage.
 
 ```bash
-mushi sync-lessons               # writes .mushi/lessons.json
-mushi sync-lessons --dry-run     # print JSON without writing
-mushi sync-lessons --json        # { ok: true, path: "...", count: 12 }
-mushi sync-lessons --cwd ./apps/mobile
-```
-
-CI example (GitHub Actions):
-```yaml
-- name: Sync Mushi lessons
-  env:
-    MUSHI_API_KEY: ${{ secrets.MUSHI_API_KEY }}
-    MUSHI_PROJECT_ID: ${{ secrets.MUSHI_PROJECT_ID }}
-    MUSHI_API_ENDPOINT: https://dxptnwrhwsqckaftyymj.supabase.co/functions/v1/api
-  run: npx @mushi-mushi/cli sync-lessons
+mushi sourcemaps upload --release 1.4.2 --dir ./dist
+mushi sourcemaps upload --release "$GITHUB_SHA" --dir ./build --dry-run
+mushi sourcemaps upload --release "$GITHUB_SHA" --dir ./build --silent
 ```
 
----
+Requires `MUSHI_API_ENDPOINT` and `MUSHI_API_KEY` (or pass `--endpoint` /
+`--api-key`). Exits non-zero on any upload failure so CI gates fail fast.
 
-### `mushi test`
-
-Submit a synthetic test report to verify the ingestion pipeline end-to-end.
-Run this after deployment to confirm the SDK → API → DB path is healthy.
-
-```bash
-mushi test
-mushi test --json
-```
+### `mushi migrate`
 
----
+Reads `package.json` (deps + devDeps + peerDeps) and prints links to the
+matching guides on the docs site. Detects:
 
-### `mushi index <path>`
+- **In-transition shapes** — Capacitor + React Native side-by-side, Cordova
+  (or `cordova-ios`/`cordova-android`), Create React App.
+- **Competitor SDKs** — Instabug / Luciq, Shake, LogRocket Feedback,
+  BugHerd, Pendo Feedback.
 
-Walk a local repo and upload source code to the Mushi RAG vector index. Used
-for private repos that cannot be auto-indexed via the GitHub App integration.
+Exits non-zero when nothing matches, so it composes in shell scripts:
 
 ```bash
-mushi index ./src
-mushi index ./src --language ts --dry-run
-mushi index . --json                        # { ok: true, files: 42, bytes: 123456 }
+mushi migrate || echo "no migration suggestions for this project"
 ```
 
----
+Only `published` guides ever surface — `draft` entries are filtered out so
+the CLI never points users at a 404. This safety property is unit-pinned in
+`packages/cli/src/migrate.test.ts` (positive control + negative control +
+real-catalog regression guard).
 
-### `mushi sourcemaps upload`
+### `mushi doctor`
 
-Upload source map files (`.map`) for stack trace symbolication.
+Checks CLI and SDK health.  Without flags it verifies local config and endpoint
+reachability only.
 
 ```bash
-mushi sourcemaps upload --release 1.0.0
-mushi sourcemaps upload --release $(git rev-parse --short HEAD) --dir ./dist
-mushi sourcemaps upload --release 1.0.0 --dry-run --silent
+mushi doctor                  # local checks only
+mushi doctor --server         # + calls /preflight on the backend (all 4 dispatch checks)
+mushi doctor --json           # machine-readable JSON output (exits 1 if any check fails)
 ```
 
----
+Local checks performed:
 
-### `mushi migrate`
+| Check | What it verifies |
+|---|---|
+| CLI config | `~/.mushirc` exists, `projectId` and `apiKey` fields are present |
+| Endpoint reachability | `GET /v1/sdk/config?project_id=...` returns 200 |
+| SDK install | `@mushi-mushi/web` or framework-specific SDK is in `node_modules` |
 
-Suggest the most relevant migration guide based on your `package.json`.
+With `--server`, also calls `GET /v1/admin/projects/:id/preflight` (same 4 checks
+the admin console dispatch popover uses) and merges the results.  The four
+server checks (`key` values returned by the endpoint):
 
-```bash
-mushi migrate
-mushi migrate --json
-```
+| `key` | What it verifies |
+|---|---|
+| `github` | A GitHub repo URL is linked (`project_repos.repo_url` or `project_settings.codebase_repo_url`) |
+| `codebase` | Codebase indexing is enabled AND `pgvector` has at least one non-tombstoned file AND `last_indexed_at` is set |
+| `anthropic` | A BYOK Anthropic key is stored in Supabase Vault (`project_settings.byok_anthropic_key_ref`) |
+| `autofix` | The autofix toggle is ON (`project_settings.autofix_enabled = true`) |
 
----
+`--server` requires `adminOrApiKey` credentials — set `MUSHI_API_KEY` to an
+admin key (not a public SDK key).
 
-### `mushi deploy check`
+### `mushi reset <projectId>`
 
-Check that the Mushi edge function is healthy and measure round-trip latency.
+Archives a project and wipes its test data so the full onboarding flow can be
+re-run.  Useful for development and QA.
 
 ```bash
-mushi deploy check
-mushi deploy check --json   # { ok: true, status: 200, latency_ms: 38 }
+mushi reset proj_xxx --confirm   # required flag prevents accidental wipes
 ```
 
----
-
-## Exit codes
+Wipes: `fix_attempts`, `project_codebase_files`, `reports`, `fix_dispatch_jobs`.
+Sets `projects.archived_at`.  **Irreversible.**
 
-| Code | Meaning |
-|------|---------|
-| `0` | Success |
-| `1` | API or runtime error |
-| `2` | Configuration error (missing credentials or endpoint) |
-| `3` | Not found (report or lesson ID does not exist) |
+### `mushi fixes tail --report-id <id>`
 
----
-
-## Self-hosted Mushi
-
-If you run a self-hosted Mushi instance, point the CLI at your edge function:
+Streams dispatch events for a report in real-time via SSE.  Pairs with
+`mushi doctor --server` for headless debugging without opening the admin console.
 
 ```bash
-mushi login \
-  --api-key   mushi_xxx \
-  --endpoint  https://your-ref.supabase.co/functions/v1/api \
-  --project-id <uuid>
+mushi fixes tail --report-id 11111111-2222-3333-4444-555555555555
 ```
 
-Or set `MUSHI_API_ENDPOINT` globally in CI.
-
----
-
-## Biological evolution analogy
-
-Mushi Mushi is modelled on **cumulative selection** (Dawkins, _The Blind
-Watchmaker_) and **closed-loop error correction** (Black Box Thinking, Matthew
-Syed):
-
-1. **Variation** — users report bugs via the SDK widget → raw reports accumulate
-2. **Selection pressure** — the clustering pipeline groups similar bugs and
-   scores them by frequency and severity → weak signals are filtered out
-3. **Memory** — high-signal clusters are promoted to _lessons_ (mistake rules)
-   → the genome of known failure modes grows
-4. **Expression** — the MCP server and CLI inject lessons into AI code review
-   → the codebase adapts before the next mutation slips through
-
-The CLI is the **field instrument** for monitoring this loop:
-- `mushi status` — read the current fitness of your bug pipeline
-- `mushi sync-lessons` — express the latest genome into your repo
-- `mushi reports triage` — apply selection pressure manually when the
-  automated pipeline needs a nudge
-
----
+Exits automatically when the job reaches a terminal status (`completed`,
+`failed`, `cancelled`, `skipped`).
 
-## Changelog
+## Security notes
 
-See [CHANGELOG.md](../../CHANGELOG.md) for release history.
+- `~/.mushirc` is written with mode `0o600` on Unix. Legacy configs with looser permissions are tightened on load.
+- `--endpoint` values are parsed through `new URL()` and required to use `https://` except for `localhost` / `127.0.0.1` / `*.local`.
+- The `--api-key` flag leaks into `ps -ef` — prefer the interactive prompt on shared machines.
+- Full stack traces on error: `DEBUG=mushi mushi init`.
 
 ## License
 

package/dist/chunk-LXO45AYO.js

@@ -0,0 +1,6 @@
+// src/version.ts
+var MUSHI_CLI_VERSION = true ? "0.11.0" : "0.0.0-dev";
+
+export {
+  MUSHI_CLI_VERSION
+};