# Mission Control (unified operator console)

Next.js application in this monorepo: **launchpad** links to existing UIs, **guided runbooks** collect inputs and execute **allowlisted** repo scripts with **live SSE trace**, **graded touchpoints**, **compliance assertions**, and a **downloadable ZIP audit pack** (manifest, events, logs, checksums).

## Run locally

From the **monorepo root**:

```bash
pnpm install
pnpm mission-control:dev
```

Open **http://localhost:3010** (Proxmox helper site can stay on 3000).

### Runbook catalog

- **Hand-written specs:** `mission-control/runbooks/specs/*.json` (short ids like `health-self-check`).
- **All documentation runbooks:** `mission-control/runbooks/doc-manifest.json` is generated from every `docs/**/**RUNBOOK**.md` (excluding master index files). Each entry runs **real** `scripts/...` or `explorer-monorepo/scripts/...` paths extracted from that markdown (up to 14 steps), with **Proxmox host**, **RPC override**, and **Practice mode** inputs.

Regenerate the doc manifest after editing runbook markdown:

```bash
pnpm --filter mission-control run generate:runbooks
```

`pnpm mission-control:build` runs **prebuild** → `generate:runbooks` automatically.

### Environment

| Variable | Purpose |
|----------|---------|
| `MISSION_CONTROL_PROJECT_ROOT` | Optional absolute monorepo root. If set but the path does not exist, Mission Control logs a warning and auto-detects from cwd instead (avoids a hard 500). |
| `GIT_BASH_PATH` | Windows: full path to `bash.exe` if not under default Git paths. |
| `NEXT_PUBLIC_HELPER_SCRIPTS_URL` | Launchpad link for helper site (default `http://localhost:3000`). |
| `NEXT_PUBLIC_EXPLORER_URL` | Launchpad link for explorer (default `https://explorer.d-bis.org`). |

## Test

```bash
pnpm mission-control:test
```

Runs a real **health-self-check** (Node child process) against the allowlisted executor.

## Build / production

```bash
pnpm mission-control:build
pnpm mission-control:start
```

Use a **production process manager** (systemd, PM2, container) with `NODE_ENV=production`. The runner executes **only** scripts mapped in `src/lib/allowlist.ts`—no arbitrary shell from the UI.

## Security notes

- Treat this console as **privileged**: anyone who can POST `/api/runs` can trigger allowlisted automation on the host.
- Place **authentication / network restrictions** in front (reverse proxy, VPN, mTLS) for non-local use.
- Secrets in runbook forms: mark `sensitive: true` in JSON specs; values are redacted in `inputs.redacted.json` inside the audit bundle.

## Adding a runbook

**Option A — markdown in `docs/`:** Name the file with `RUNBOOK` in the filename. Reference scripts as `scripts/...` or `explorer-monorepo/scripts/...`. Run `pnpm --filter mission-control run generate:runbooks` and commit the updated `doc-manifest.json`.

**Option B — curated JSON:** Add `runbooks/specs/<id>.json` (see `src/lib/runbook-schema.ts`). Every spec must include an **`execution`** block with allowlisted script paths. Hand-written specs override doc-manifest entries if they share the same `id`.

Execution is allowlisted by path prefix only: **`scripts/`** and **`explorer-monorepo/scripts/`** (see `src/lib/execution-path-validator.ts`).

## Timeline

See [TIMELINE.md](./TIMELINE.md) for phased delivery and estimates.