@m8t-stack/cli 0.0.1-bootstrap

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Or Keren (m8t)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,213 @@
+# `@m8t-stack/cli`
+
+The `m8t` CLI for managing m8t-stack deployments.
+
+## Install
+
+```bash
+# npm (any OS with Node 20+)
+npm install -g @m8t-stack/cli
+
+# Homebrew (macOS / Linux)
+brew install m8t-run/tap/m8t
+
+# Scoop (Windows)
+scoop bucket add m8t https://github.com/m8t-run/scoop-bucket
+scoop install m8t
+
+# Verify
+m8t version
+```
+
+The CLI bundles the shared workspace types into a single `dist/cli.js`, so the
+npm install is self-contained (only the external runtime deps resolve from npm).
+Publishing is automated by `.github/workflows/release-cli.yml` (OIDC trusted
+publishing); see `publish/npm-trusted-publishing-setup.md`.
+
+### Build from source (contributors)
+
+```bash
+pnpm --filter "@m8t-stack/cli" build   # produces dist/cli.js with shebang
+cd apps/cli && pnpm pack               # produces m8t-stack-cli-<version>.tgz
+npm install -g ./m8t-stack-cli-*.tgz
+```
+
+## Usage
+
+```bash
+m8t version                 # CLI version
+m8t whoami                  # Identity + which gateway you're talking to (probes the backend)
+m8t status                  # Full local snapshot: az identity, config.yaml, gateway cache, azd mode
+m8t doctor                  # Health checks (az · config · tenant align · gateway · Foundry data-plane · model-quota) + fixes
+m8t doctor --agent <name>   # + delivery-grant check: verifies the agent's MI holds Key Vault Secrets User
+m8t open [webapp|foundry|portal]   # Open the deployed app / Foundry portal / resource group in a browser
+
+# Local config (~/.m8t-stack)
+m8t config show                       # config.yaml (tenant/client/project) + the cached gateway
+m8t config set <key> <value>          # set tenantId | clientId | projectEndpoint
+m8t config reset                      # clear the gateway discovery cache
+m8t switch --subscription <id|name>   # re-point local config at another deployment (snapshots first)
+m8t switch <profile>                  # restore a saved profile;  m8t switch --list
+
+# Team management
+m8t team add <handle> --display "<name>" [--telegram <id>] [--slack <id>] [--teams <upn>]
+m8t team list
+m8t team show <handle>
+m8t team add-identity <handle> [--telegram <id>] [--slack <id>] [--teams <upn>]
+m8t team remove-identity <handle> --telegram|--slack|--teams
+m8t team remove <handle>
+
+# Deploy / update the gateway stack (replaces the old deploy/setup.mjs)
+m8t deploy [--client-id <appId>] [--image-ref <ref>] [--location <region>] [--resource-group <name>]
+
+# Brain management
+m8t brain link <name> --repo <owner>/<repo> [--persona <path>] [--allow-non-reasoning]
+# --persona: override the recorded persona file (or use when no local agent yaml exists)
+# --allow-non-reasoning: suppress the reasoning-model warning
+```
+
+### `--subscription <id>` flag
+
+Available on all gateway-using commands (`whoami`, `config show`, `config reset`,
+`team add`, `team list`, `team show`, `team add-identity`, `team remove-identity`,
+`team remove`, `bind add`, `bind list`, `bind show`, `bind remove`, `bind cleanup`).
+Pins gateway discovery to the named subscription, bypassing the active `az`
+subscription. Useful when you manage multiple m8t-stack deployments across
+subscriptions or when your shell's active subscription differs from the deployment
+target.
+
+```bash
+m8t team list --subscription <subscription-id-or-name>
+```
+
+## Local context & config — `status` / `doctor` / `switch`
+
+The CLI reads two local files under `~/.m8t-stack/`: **`config.yaml`** (your `tenantId`, `clientId`, and Foundry `projectEndpoint` — used by the web app + architect) and **`cli-config.yaml`** (the auto-discovered gateway URL cache).
+
+- **`m8t status`** — a read-only snapshot of everything local: your signed-in `az` identity + active subscription/tenant, `config.yaml` (tenant / client / project), the gateway cache, the `azd` auth mode, and whether your `az` tenant matches `config.yaml` (tenant alignment). `--output json` for scripting.
+- **`m8t doctor`** — runs health checks and prints a fix for each failure; exits non-zero if any check FAILs. Checks: `az` signed in · `config.yaml` valid · tenant alignment · gateway reachable (`/api/me`) · **Foundry data-plane reachable** (a 401/403 prints the exact `az role assignment create … "Cognitive Services User"` command) · **model-quota check** (warns for any deployed model with 0 TPM quota in the region). Results stream as each check runs. Pass `--agent <name>` to add a targeted delivery-grant check: reads the agent's deployed env and verifies its managed identity holds `Key Vault Secrets User` on the configured vault.
+- **`m8t config set <key> <value>`** — write `tenantId`, `clientId`, or `projectEndpoint` into `config.yaml` (validated). `m8t config show` now displays `config.yaml` alongside the gateway cache.
+- **`m8t switch`** — re-point your local config at another deployment in one step. `--subscription <id|name>` discovers the gateway there and derives every `config.yaml` value from its container env (zero manual IDs); `<profile>` restores a saved profile; `--list` lists profiles. Every switch **snapshots the outgoing config to a profile first** (label it with `--as <name>`), so it's reversible — e.g. `m8t switch --subscription <new> --as work`, then later `m8t switch personal`.
+
+## Open in the browser — `m8t open`
+
+```bash
+m8t open            # the deployed webapp (gateway URL) — default
+m8t open foundry    # the Microsoft Foundry portal (ai.azure.com)
+m8t open portal     # the resource group in the Azure portal
+m8t open --print    # print the URL instead of launching a browser (pipe-friendly)
+```
+
+## Deploy / update the gateway — `m8t deploy`
+
+Provisions (or updates) the gateway/webapp stack via Bicep — the successor to the old `node deploy/setup.mjs`. See [`deploy/README.md`](../../deploy/README.md) for the full flow.
+
+```bash
+# Bring-your-own app registration (required if you can't create Entra app regs, e.g. a directory guest):
+m8t deploy --client-id <appId> --image-ref <acr-or-ghcr-ref> --location <region>
+```
+
+Key flags: `--client-id <appId>` (reuse an existing app reg + skip **all** Microsoft Graph writes), `--image-ref <ref>` (full image ref; default `ghcr.io/m8t-run/m8t:latest` — pass an `*.azurecr.io/...` ref for ACR images), `--resource-group` (default `rg-m8t-stack`), `--location`, `--suffix`, `--foundry-endpoint`, `--foundry-resource-id`.
+
+> ⚠️ `m8t deploy` is **declarative** — it makes the live stack match the Bicep template. If a deployment was hand-modified after provisioning (e.g. switched to a private-ACR image with a UserAssigned pull identity), re-running the bicep can revert those changes. **Preview with `az deployment group create --what-if` before applying against a live stack.**
+
+## Binding management — `m8t bind`
+
+Wire channel bots (Telegram, Slack, Teams) to Foundry workers. F4 ships
+the management API + CLI scaffolding; the actual adapters (which deliver
+inbound messages from each channel) ship in later features.
+
+```bash
+# Create a binding (requires the channel adapter — Telegram ships in F6)
+m8t bind add telegram \
+  --worker cmo \
+  --bot-token <from-botfather> \
+  --slug cmo-tg \
+  --bot-username "@startup_cmo_bot"
+
+# List all bindings, optionally filtered
+m8t bind list
+m8t bind list --channel telegram
+m8t bind list --status orphaned
+
+# Inspect one binding (token NEVER returned — only the KV URI)
+m8t bind show cmo-tg
+
+# Remove a binding (cascade: unregister webhook → KV → conversations → row)
+m8t bind remove cmo-tg
+m8t bind remove cmo-tg --yes      # skip confirm
+
+# Orphan-only cleanup (refuses to act on active bindings)
+m8t bind cleanup <bindingId>
+m8t bind cleanup --all-orphaned
+```
+
+> `--worker` is the **case-sensitive, lowercase** Foundry agent name as deployed (e.g. `cmo`). A wrong name isn't rejected at bind time — it surfaces later as an orphaned binding on the first message.
+
+### Pre-F6 behavior
+
+`m8t bind add telegram ...` currently fails with:
+
+```
+error: no adapter for channel 'telegram'. This is expected for F4 alone;
+       the channel-specific adapter ships in a later feature.
+```
+
+This is correct. F6 (Telegram adapter) will register the adapter at
+startup and unlock the create flow.
+
+### Cascade-delete idempotency
+
+If `m8t bind remove` fails mid-cascade, it prints which steps completed
+and which step failed, and recommends re-running the command. Each step
+is independently idempotent — a re-run resumes safely from the failure
+point.
+
+## Output modes
+
+Pretty table or key-value block by default; pipe or redirect, and the CLI auto-switches to JSON:
+
+```bash
+m8t team list                   # pretty
+m8t team list | jq              # auto-JSON
+m8t team list --output json     # explicit JSON
+m8t team list --output pretty   # force pretty even on pipe
+```
+
+## Exit codes
+
+- `0` success
+- `1` any failure (auth, network, validation, backend)
+- `2` user-cancelled
+
+Granular error info in stderr's structured JSON envelope.
+
+## Prerequisites
+
+- Node 20+
+- `az login` against the customer's Azure tenant. CLI uses `DefaultAzureCredential` — no per-admin pre-registration.
+
+## Troubleshooting
+
+### `error: You are not signed in to Azure.`
+Run `az login` first. The CLI uses your active `az` session to acquire a token for the gateway.
+
+### `error: No m8t-stack deployment found in subscription <name>.`
+The deployment is in a different subscription. Switch with:
+```bash
+az account set --subscription <other-sub>
+m8t config reset
+m8t team list
+```
+
+### `error: Multiple m8t-stack deployments found ...`
+You have more than one gateway in this subscription. The CLI prompts you to pick one when running interactively (e.g. `m8t whoami`). The choice is cached at `~/.m8t-stack/cli-config.yaml`. Or pass `--subscription <id>` to target a specific subscription and skip the picker entirely.
+
+### `(gateway is starting up...)`
+The deployed gateway is configured with `min-replicas=0` (scale-to-zero). First request after idle pays ~10–20s cold start. The CLI retries once on 502/503/504.
+
+### `error: partial write — <channel-A> succeeded, <channel-B> failed.`
+A multi-identity `m8t team add` partially succeeded. Run `m8t team show <handle>` to verify the current state, then `m8t team add-identity <handle> --<channel-B> <id>` to fill in the missing identity.
+
+### CLI version vs gateway version drift
+The CLI and the gateway share `@m8t-stack/api-contract` types at compile time (the CLI bundles them at build). If the gateway is on an older version and returns a response in an unknown shape, the CLI surfaces `BAD_RESPONSE` with a "this may be a gateway version mismatch" hint.