@mightybot/mbcli 0.0.1-rc.99

package/README.md

@@ -0,0 +1,225 @@
+# @mightybot/mbcli
+
+The MightyBot `mb` CLI and local design-time MCP server, distributed over npm so
+it can be run with `npx`.
+
+`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.
+
+
+## Start here — one command
+
+With Node.js 16+, this one command is the entire setup — it signs you in and
+registers the MCP server with your AI agents:
+
+```bash
+npx @mightybot/mbcli@latest setup
+```
+
+`setup` = `mb auth login` (browser sign-in) + `mb mcp install --agent all`.
+`npx` fetches the right platform binary on demand — nothing to install first.
+
+Run any other command the same way:
+
+```bash
+npx @mightybot/mbcli@latest workflow list
+npx @mightybot/mbcli@latest version
+```
+
+> Prefer a permanent `mb` on your PATH? `npm i -g @mightybot/mbcli@latest`,
+> then run `mb <cmd>` (re-run the install to upgrade). The MCP server installs to
+> the stable `~/.mightybot/mcp/mb` either way.
+
+### Release channels
+
+- **`@latest`** — the stable release. Use this. *(recommended for everyone)*
+- **`@preprod`** — the newest build, ahead of `@latest`; use it to try the most
+  recent changes before they're promoted.
+
+`@latest` is promoted from a tested `@preprod` build — 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
+```
+
+### Release-age cooldown
+
+If your npm config (or your organization's `.npmrc`) sets `min-release-age` as a
+supply-chain guard, npm refuses any version published in the last N days — so a
+**same-day release fails with `ENOVERSIONS` / "No versions available for
+@mightybot/mbcli"** even though it published fine. Override the cooldown to
+install a fresh build:
+
+```bash
+npx --min-release-age=0 @mightybot/mbcli@latest          # CLI flag, or
+npm_config_min_release_age=0 npx @mightybot/mbcli@latest  # env var
+```
+
+Once the build is older than the cooldown window, plain `npx …` works with no
+flag. (This guard is intentional — it protects against installing a
+freshly-compromised package; the override is only for trusted same-day builds.)
+
+## 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 <your-platform-url>`).
+
+### `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
+```
+
+### `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
+
+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

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+"use strict";
+
+// Thin launcher for the `mb` Go binary distributed over npm.
+//
+// The actual binary ships in a per-platform optional dependency
+// (@mightybot-ai/mbcli-<platform>). npm installs only the package matching the
+// host's os/cpu, so this shim resolves that package's binary and execs it,
+// passing argv and stdio straight through. stdio is inherited so `mb mcp`
+// (a long-lived stdio MCP server) works unchanged.
+
+const { execFileSync } = require("child_process");
+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 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",
+  "darwin-x64",
+  "linux-x64",
+  "linux-arm64",
+  "win32-x64",
+]);
+
+function resolveBinary() {
+  const key = `${process.platform}-${process.arch}`;
+  if (!SUPPORTED.has(key)) {
+    throw new Error(
+      `${SELF_NAME}: unsupported platform "${key}". Supported: ${[...SUPPORTED].join(", ")}.`,
+    );
+  }
+  const pkg = `${SELF_NAME}-${key}`;
+  const exe = process.platform === "win32" ? "mb.exe" : "mb";
+  try {
+    // require.resolve walks node_modules and returns the absolute file path.
+    return require.resolve(`${pkg}/${exe}`);
+  } catch (err) {
+    throw new Error(
+      `${SELF_NAME}: platform package "${pkg}" is not installed for "${key}".\n` +
+        `It is an optionalDependency — reinstall without "--no-optional" / ` +
+        `"--omit=optional".\n` +
+        `Underlying error: ${err.message}`,
+    );
+  }
+}
+
+function main() {
+  let binary;
+  try {
+    binary = resolveBinary();
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+
+  // npm normalizes non-`bin` files to 0644 on install (strips the execute bit),
+  // so ensure the binary is executable before launching. Best-effort: a global
+  // install owned by root may not be chmod-able, but is usually already 0755.
+  if (process.platform !== "win32") {
+    try {
+      fs.chmodSync(binary, 0o755);
+    } catch (_) {
+      /* ignore — fall through to exec, which surfaces a clear error if needed */
+    }
+  }
+
+  try {
+    execFileSync(binary, process.argv.slice(2), { stdio: "inherit" });
+  } catch (err) {
+    // execFileSync throws on any non-zero exit; mirror the child's status.
+    if (typeof err.status === "number") {
+      process.exit(err.status);
+    }
+    if (err.signal) {
+      console.error(`mbcli: mb terminated by signal ${err.signal}`);
+      process.exit(1);
+    }
+    console.error(`mbcli: failed to launch mb: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@mightybot/mbcli",
+  "version": "0.0.1-rc.99",
+  "description": "MightyBot mb CLI and local MCP server",
+  "bin": {
+    "mb": "bin/mb.js"
+  },
+  "files": [
+    "bin/mb.js",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "license": "UNLICENSED",
+  "private": false,
+  "optionalDependencies": {
+    "@mightybot/mbcli-darwin-arm64": "0.0.1-rc.99",
+    "@mightybot/mbcli-darwin-x64": "0.0.1-rc.99",
+    "@mightybot/mbcli-linux-x64": "0.0.1-rc.99",
+    "@mightybot/mbcli-linux-arm64": "0.0.1-rc.99",
+    "@mightybot/mbcli-win32-x64": "0.0.1-rc.99"
+  },
+  "homepage": "https://mightybot.ai"
+}