@mightybot/mbcli 0.5.398 → 0.5.412

package/README.md

@@ -1,12 +1,244 @@
 # @mightybot/mbcli
 
-The MightyBot `mb` CLI. Run it with npx (no install):
+The MightyBot `mb` CLI and local design-time MCP server, distributed over npm so
+it can be run with `npx`.
 
-```sh
-npx @mightybot/mbcli@latest setup          # log in + register MCP with your agents
-npx @mightybot/mbcli@latest workflow list
+`mb` is a single Go binary. This package is a thin launcher: the binary ships in
+a per-platform optional dependency (`@mightybot/mbcli-<platform>`), and npm
+installs only the one matching your machine.
+
+
+## Run — two ways
+
+The actual command is always **`mb`**; the package name (`@mightybot/mbcli`)
+is just what npm fetches. Pick whichever fits:
+
+### Option A — `npx` (no install, always newest)
+
+```bash
+npx @mightybot/mbcli@latest version       # prod (stable)
+npx @mightybot/mbcli@latest auth login
+npx @mightybot/mbcli@preprod version      # preprod (newest build, pre-promotion)
+```
+
+npm fetches + caches only your platform's binary on first run; `@latest` /
+`@preprod` makes npx re-check the registry each run, so you always get the
+newest build for that channel. Nothing to upgrade.
+
+### Option B — global install (`mb` on PATH, shorter commands)
+
+```bash
+npm i -g @mightybot/mbcli@latest          # or @preprod
+mb version
+mb auth login
+mb setup
+```
+
+Puts a real `mb` command on your PATH — no `npx`, no scope prefix. Faster
+(no per-run resolution), but it does **not** auto-update: you are pinned to the
+version installed until you re-run the install to upgrade:
+
+```bash
+npm i -g @mightybot/mbcli@latest          # upgrade to newest latest
+npm i -g @mightybot/mbcli@preprod         # or newest preprod
+```
+
+| | `npx …@latest` | `npm i -g …@latest` |
+|---|---|---|
+| Command | `npx @mightybot/mbcli@latest <cmd>` | `mb <cmd>` |
+| Always newest | ✅ auto | ❌ frozen at install — re-install to upgrade |
+| Per-run overhead | small | none |
+
+Either way the one-time `~/.npmrc` (above) is required, and `mb setup` works the
+same — it installs the MCP server to the stable `~/.mightybot/mcp/mb`,
+independent of how you run the CLI.
+
+### Release channels
+
+| Tag | Published when | Who uses it |
+|-----|----------------|-------------|
+| `preprod` | every `master` merge (version `0.5.<run>`) | testers validating a build |
+| `latest` | manual promotion of a tested `preprod` version (no rebuild) | everyone |
+
+Promotion moves the `latest` dist-tag onto the exact `preprod` artifact that was
+tested — same bytes, no rebuild.
+
+### Always getting the newest
+
+npx caches by version spec. To avoid running a stale cached copy, either pin the
+channel tag or force a registry check:
+
+```bash
+npx @mightybot/mbcli@latest version          # re-resolves the latest tag
+npx --prefer-online @mightybot/mbcli version  # revalidates cache against the registry
+```
+
+## One-step setup (auth + MCP)
+
+After installing, run **one** command to get fully provisioned — it logs you in
+and registers the MCP server with Codex / Claude Code / OpenCode:
+
+```bash
+npx @mightybot/mbcli@latest setup
+```
+
+`mb setup` = `mb auth login` (browser device auth) + `mb mcp install --agent all`.
+Auth flags pass through, e.g. `setup --base-url https://platform-dev.mightybot.ai`.
+
+## Commands
+
+Every example below uses the bare `mb` (after a global install or inside
+`mb setup`). With `npx`, prefix any command:
+`npx @mightybot/mbcli@latest <command>`.
+
+Get machine-readable help any time:
+
+```bash
+mb help            # human-readable usage
+mb help --json     # full command catalog (command, usage, backend method/path)
+mb version         # build info (version, commit, build date) as JSON
+```
+
+> Builder-step **configuration writes** (workflow schemas, file processing,
+> validation, policies, agent compiler, data trail, views) are **MCP-native** —
+> done by an agent through the `mb mcp` server, not these shell subcommands. The
+> shell commands below cover auth, setup, fleet ops, tests, SDLC, deploy/release,
+> and evidence. After `mb setup`, an agent should start with the MCP tool
+> `mightybot.start_here`.
+
+### `mb setup` — one-step provisioning
+
+```bash
+mb setup [auth flags]   # mb auth login + mb mcp install --agent all
+```
+
+Logs in (browser device auth) and registers the MCP server with all detected
+agents. Auth flags pass through (e.g. `--base-url https://platform-dev.mightybot.ai`).
+
+### `mb auth` — platform authentication
+
+| Command | What it does |
+|---|---|
+| `mb auth login` | Browser device-code login; stores the token under `~/.mightybot`. |
+| `mb auth inspect` | Show the active profile/backend and token status. |
+| `mb auth profile` | Print the current auth profile (tenant, user, backend URL). |
+| `mb auth configure` | Set/switch the backend (base URL, environment). |
+| `mb auth probe-write` | Pre-flight check that the token can perform writes. |
+
+> `mb` has **one** profile slot — the last `mb auth login` wins. Confirm the
+> active backend with `mb auth inspect` before any write.
+
+### `mb mcp` — local design-time MCP server
+
+| Command | What it does |
+|---|---|
+| `mb mcp` | Run the MCP server on stdio (what agents launch). |
+| `mb mcp install [--agent codex,claude,opencode\|all]` | Copy the binary to `~/.mightybot/mcp/mb` and register it with the chosen agents. |
+| `mb mcp register` | Register an already-installed server with an agent. |
+| `mb mcp update` | Re-copy/re-register after a CLI upgrade. |
+| `mb mcp uninstall` | Remove the server registration. |
+| `mb mcp status` / `mb mcp doctor` | Show registration health / diagnose problems. |
+| `mb mcp start` / `mb mcp stop` | Start/stop the managed server. |
+
+### `mb surface` — inspect the workflow surface
+
+```bash
+mb surface overview      # high-level map of the workflow definition
+mb surface resources     # resources referenced by the workflow
+mb surface operations    # available builder operations
+mb surface step          # step-level detail
+```
+
+### `mb workflow` — workflow definitions (read/SDLC)
+
+| Command | What it does |
+|---|---|
+| `mb workflow list` | List workflow definitions. |
+| `mb workflow inspect <id>` | Show a definition's full configuration. |
+| `mb workflow create` / `update` / `duplicate` / `delete` | Manage definitions. |
+| `mb workflow export <id>` | Export a definition (e.g. for diffing/backup). |
+| `mb workflow diff` | Diff two definitions/versions. |
+| `mb workflow validate <id>` | Validate a definition. |
+| `mb workflow versions` / `version` / `version-history` / `version-diff` | Inspect version history and compare versions. |
+
+### `mb git` — git ↔ workflow sync state
+
+```bash
+mb git branches          # branches relevant to workflow definitions
+mb git sync-status       # git/DB sync status
+mb git auto-merge        # auto-merge eligible changes
+mb git resource-state    # per-resource git state
+mb git pr-status         # PR status for workflow changes
+```
+
+### `mb instance` — workflow instances & their files
+
+| Command | What it does |
+|---|---|
+| `mb instance list` / `get <id>` / `stats` | List, fetch, and summarize instances. |
+| `mb instance create` / `patch` / `delete` / `close` | Manage instances. |
+| `mb instance repair` / `backfill` | Maintenance operations. |
+| `mb instance data` | Inspect/manage instance data entries. |
+| `mb instance file upload …` | Upload a file to an instance. |
+
+### `mb run` — workflow runs (tests & evidence)
+
+| Command | What it does |
+|---|---|
+| `mb run test` | Run a workflow end-to-end as a test. |
+| `mb run create` / `partial` | Start a full or partial run. |
+| `mb run rerun` | Re-execute a prior run. |
+| `mb run list` / `inspect <id>` | List runs / inspect one. |
+| `mb run result <id>` / `files <id>` | Fetch a run's result / output files. |
+
+### `mb eval` — evaluations
+
+```bash
+mb eval lists | list        # list eval sets / evals
+mb eval run                 # run an evaluation
+mb eval result              # fetch results
+mb eval annotation          # annotations
+mb eval comment | review    # commenting / review
+mb eval packet              # export an eval packet
 ```
 
-Or install globally: `npm i -g @mightybot/mbcli`, then `mb <cmd>`.
+### `mb deploy` — deploys
+
+| Command | What it does |
+|---|---|
+| `mb deploy draft` / `preview` | Stage and preview a deploy. |
+| `mb deploy release` | Cut a release/deploy. |
+| `mb deploy status` / `release-status` | Check deploy/release status. |
+| `mb deploy list` / `releases` | List deploys / releases. |
+
+### `mb release` — release tagging
+
+```bash
+mb release tag suggest      # suggest the next release tag
+mb release tag create       # create a release tag
+```
+
+### `mb view-serving` — view-serving checks
+
+```bash
+mb view-serving smoke       # smoke-test served views
+mb view-serving test        # run view-serving tests
+```
+
+### Global flags
+
+- `--home <dir>` — override `HOME` (where `~/.mightybot` lives); useful for
+  isolated/CI runs.
+- `--json` after `help` — emit the full command catalog as JSON.
+
+### Under the hood
+
+`setup` copies the binary to a stable location (`~/.mightybot/mcp/mb`, alongside
+its docs, re-signed for macOS) and registers *that* path — so the long-lived MCP
+server does not depend on the ephemeral npx cache. Re-run `setup` after an
+upgrade, then restart your agent so it reloads MCP.
+
+## Supported platforms
 
-Homepage: https://mightybot.ai
+macOS arm64 (Apple Silicon), macOS x64 (Intel), Linux x64, Linux arm64,
+Windows x64 — npm installs only the package matching your machine.

package/bin/mb.js

@@ -14,9 +14,9 @@ const fs = require("fs");
 const path = require("path");
 
 // Derive the platform packages from THIS package's own name, so the same shim
-// works under any scope/name it is published as (e.g. @mightybot-ai/mbcli and
-// @mightybot/mbflow). The binary ships in `<self>-<platform>` (e.g.
-// @mightybot/mbflow-darwin-arm64).
+// works under any scope it is published as (e.g. @mightybot-ai/mbcli private and
+// @mightybot/mbcli public). The binary ships in `<self>-<platform>` (e.g.
+// @mightybot/mbcli-darwin-arm64).
 const SELF_NAME = require(path.join(__dirname, "..", "package.json")).name;
 const SUPPORTED = new Set([
   "darwin-arm64",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mightybot/mbcli",
-  "version": "0.5.398",
+  "version": "0.5.412",
   "description": "MightyBot mb CLI and local design-time MCP server",
   "bin": {
     "mb": "bin/mb.js"
@@ -15,11 +15,11 @@
   "license": "UNLICENSED",
   "private": false,
   "optionalDependencies": {
-    "@mightybot/mbcli-darwin-arm64": "0.5.398",
-    "@mightybot/mbcli-darwin-x64": "0.5.398",
-    "@mightybot/mbcli-linux-x64": "0.5.398",
-    "@mightybot/mbcli-linux-arm64": "0.5.398",
-    "@mightybot/mbcli-win32-x64": "0.5.398"
+    "@mightybot/mbcli-darwin-arm64": "0.5.412",
+    "@mightybot/mbcli-darwin-x64": "0.5.412",
+    "@mightybot/mbcli-linux-x64": "0.5.412",
+    "@mightybot/mbcli-linux-arm64": "0.5.412",
+    "@mightybot/mbcli-win32-x64": "0.5.412"
   },
   "homepage": "https://mightybot.ai"
 }