nanoclaw/docs/setup-flow.md

# Setup flow

This document is the contract for NanoClaw's end-to-end scripted setup
(`bash nanoclaw.sh` → `pnpm run setup:auto`). Read it before adding a new
step, fixing a regression, or changing how output is rendered.

## The three output levels

Every setup step produces output at **three distinct levels**. They have
different audiences, go to different places, and are formatted differently.
Don't conflate them.

| Level | Audience | Destination | Format |
|---|---|---|---|
| 1. User-facing | The operator running setup | Terminal (via clack) | Branded, concise, informational — "product content" |
| 2. Progression | Future debuggers, AI agents reviewing a failed run, release support | `logs/setup.log` (one file, append-only) | Structured per-step blocks, linear chronology, human + machine readable |
| 3. Raw | Whoever is deep-debugging a specific step | `logs/setup-steps/NN-step-name.log` (one file per step) | Full raw child stdout + stderr, verbatim |

Think of it as: the user sees a **summary**, the progression log is an
**index with key facts**, the raw logs are the **evidence**.

### Level 1: user-facing (clack)

Rendered by `setup/auto.ts` via `@clack/prompts`. This is our *product
surface* for setup — every line should read as if we designed it for a
stranger on day one.

- Clack spinners for in-progress work. Show elapsed time.
- `p.log.success` / `p.log.step` / `p.log.warn` for permanent status
  markers.
- `p.note` for multi-line information (pairing code, next steps).
- `p.text` / `p.select` / `p.password` for prompts.
- Brand palette: `brand()` / `brandBold()` / `brandChip()` helpers in
  `setup/auto.ts`. Truecolor when the terminal supports it, 16-color
  cyan fallback otherwise, plain text when piped / `NO_COLOR`.

Rules:
- **No discontinuity.** Every sub-step belongs to the same visual flow.
  The only exception is Anthropic credential registration (see below).
- **No raw child output.** Never `stdio: 'inherit'` a child whose output
  wasn't written by us. Capture it and show it on failure only.
- **No debug-style prefixes** (`[add-telegram] …`, `INFO …`, timestamps).
  Those belong in levels 2 and 3.
- **No emoji** unless the clack glyph requires it.

### Level 2: progression log

`logs/setup.log` — one file per setup run, append-only, cumulative across
a multi-run install (if a run fails midway and is re-attempted, the new
entries append). It's the thing you'd ask an operator to paste when they
report a setup bug, and the thing an AI agent would read to understand
what happened.

Entry format:

```
=== [2026-04-22T22:14:12Z] bootstrap [45.1s] → success ===
  platform: linux
  is_wsl: false
  node_version: 22.22.2
  deps_ok: true
  native_ok: true
  raw: logs/setup-steps/01-bootstrap.log

=== [2026-04-22T22:14:57Z] environment [2.3s] → success ===
  docker: running
  apple_container: not_found
  raw: logs/setup-steps/02-environment.log

=== [2026-04-22T22:15:00Z] container [92.4s] → success ===
  runtime: docker
  image: nanoclaw-agent:latest
  build_ok: true
  raw: logs/setup-steps/03-container.log
```

Design constraints:
- Start-time timestamp (UTC, ISO-8601) on the opening line so a `grep`
  gives you the sequence.
- Duration in seconds with one decimal — fast steps read as "0.5s", not
  "0ms".
- Status is one of: `success`, `skipped`, `failed`, `aborted`.
- Fields are step-specific but **must** be short scalar values. No JSON,
  no multi-line. If a value is long, put it in the raw log and reference
  it.
- Always emit a `raw:` pointer, even on success — makes debugging the
  second failure easier.
- **User choices** are their own entries, not nested inside a step:

  ```
  === [2026-04-22T22:17:44Z] user-input → display_name ===
    value: gav

  === [2026-04-22T22:17:51Z] user-input → channel_choice ===
    value: telegram
  ```

  These matter because the path through the setup flow depends on them.

The log opens with a header block identifying the run, and closes with
a completion block:

```
## 2026-04-22T22:14:12Z · setup:auto started
  user: exedev
  cwd: /home/exedev/nanoclaw
  branch: branded-setup
  commit: 6e0d742

… (step entries) …

## 2026-04-22T22:18:54Z · completed (total 4m42s)
```

On failure the completion block names the failing step and its error:

```
## 2026-04-22T22:16:40Z · aborted at container (err=cache_miss)
```

### Level 3: raw per-step logs

`logs/setup-steps/NN-step-name.log` — one file per step, numbered in
execution order (zero-padded 2-digit prefix for natural sorting). Full
verbatim stdout + stderr from the child process. Truncated and rewritten
on each run (not appended).

Contents are whatever the step emits: apt output, docker build layers,
pnpm install spam, `curl` bodies, etc. This is the evidence plane —
"what did the shell actually see?" Nothing is filtered.

## Contract for a new step

When you add a step (either a TS step in `setup/<name>.ts` or a bash
installer invoked from `auto.ts`), it must:

1. **Receive a raw-log path** from the caller. Write all stdout + stderr
   there. Don't write to the terminal directly.
2. **Emit a single terminal status block** at the end, containing
   `STATUS: success|skipped|failed` and any step-specific fields:

   ```
   === NANOCLAW SETUP: STEP_NAME ===
   STATUS: success
   KEY: value
   KEY: value
   === END ===
   ```

   Field names are `UPPER_SNAKE_CASE`. Values are short scalars.

3. If it's a long-running step, optionally emit **sub-status blocks**
   mid-stream. `auto.ts` parses them live and can render intermediate
   UI (as `pair-telegram` does with `PAIR_TELEGRAM_CODE` /
   `PAIR_TELEGRAM_ATTEMPT`).

4. **Exit non-zero** on hard failure so `auto.ts` can distinguish
   "step ran to completion and reported failed" from "step crashed".

The driver handles the rest: spinner in level 1, structured append to
level 2, raw capture to level 3.

## The Anthropic exception

Anthropic credential registration (`setup/register-claude-token.sh`) is
the **one** permitted break in the visual flow. Why:

- `claude setup-token` opens a browser, runs its own OAuth prompt, and
  prints the token. It owns the TTY via `script(1)`.
- We don't want to re-implement the OAuth device flow ourselves.
- We don't want to intercept / mirror the token (it appears in the
  user's terminal already — mirroring it adds attack surface).

So during this step:
- The clack flow explicitly pauses (a `p.log.step` marker says "this
  part is interactive, you're handing off to Anthropic").
- The child inherits stdio fully.
- When control returns, clack resumes on the next line with a success
  marker.

The level-2 log still gets an entry (`auth [interactive] → success`
with the method — subscription / oauth-token / api-key). Level-3 captures
are optional here; mirroring `script -q` output is tricky and the risk of
leaking the token to disk outweighs the debugging value.

## File reference

| File | Role |
|---|---|
| `nanoclaw.sh` | Top-level wrapper. Phase 1 (bootstrap) and phase 2 (setup:auto) orchestration. Writes bootstrap's raw log + progression entry. |
| `setup.sh` | Phase 1 bootstrap: Node, pnpm, native-module verify. Emits its own `BOOTSTRAP` status block (historically printed to stdout; now goes to the bootstrap raw log). |
| `setup/auto.ts` | Phase 2 driver. Orchestrates the clack UI, step execution, user prompts, and writes to all three log levels for every step it spawns. |
| `setup/logs.ts` | The logging primitives (`logStep`, `logUserInput`, `logComplete`, `stepRawLog`, `initSetupLog`). Single source of truth for level 2/3 formatting and file paths. |
| `setup/<step>.ts` | Individual step implementations. Must emit one terminal status block; must not write directly to the terminal. |
| `setup/register-claude-token.sh` | The Anthropic exception. Inherits stdio, prints its own UI, returns a status to the driver. |
| `setup/add-telegram.sh` | Non-interactive adapter installer. Reads `TELEGRAM_BOT_TOKEN` from env; never prompts. User-facing bits live in `auto.ts`. |
| `setup/pair-telegram.ts` | Emits `PAIR_TELEGRAM_CODE` / `PAIR_TELEGRAM_ATTEMPT` / `PAIR_TELEGRAM` status blocks. Never prints UI. The driver renders it via clack notes. |

## Common pitfalls

- **Printing debug output from inside a step.** Tempting during
  development; forbidden in checked-in code. All runtime messaging goes
  through status blocks (level 2) or raw log writes (level 3).
- **Adding a `console.log` that "just this once" goes to the terminal.**
  It breaks the clack flow — the spinner line gets torn. Use
  `log.info` / `log.error` from `src/log.ts` (writes to the raw log)
  instead.
- **`stdio: 'inherit'` for a non-exception child.** See Anthropic above.
  Anything else needs `pipe` + explicit capture.
- **Tee-ing to stderr.** Clack's spinner owns the terminal during a step.
  Even stderr writes tear the frame. Pipe everything, then choose what
  to surface.
- **UTF-8 in bash `$VAR…` positions.** Bash's lexer can pull the first
  byte of a multi-byte character into the variable name and trip
  `set -u`. Always brace: `${VAR}…`.

## Future work (not yet implemented)

- **Progression log rotation.** Today's implementation truncates on each
  run. Future: roll prior runs to `logs/setup.log.1`, `.2`, etc.
- **Raw log rotation for multi-run installs.** Currently each run
  overwrites. Fine for now; revisit if support needs to compare
  successive attempts.
- **Structured output from `register-claude-token.sh`.** The interactive
  step emits no machine-readable status today. Future could add a
  post-interaction status block with the method used.