diff --git a/.planning/phases/02-env-audit-and-cli-polish/02-CONTEXT.md b/.planning/phases/02-env-audit-and-cli-polish/02-CONTEXT.md new file mode 100644 index 0000000..f5851b0 --- /dev/null +++ b/.planning/phases/02-env-audit-and-cli-polish/02-CONTEXT.md @@ -0,0 +1,100 @@ +# Phase 2: Env Audit and CLI Polish - Context + +**Gathered:** 2026-04-09 +**Status:** Ready for planning + + +## Phase Boundary + +Add pre-launch transparency and diagnostic CLI flags to claudebox. User can review exactly what enters the sandbox before launch (`env audit`), skip review (`--yes`/`-y`), inspect the bwrap command (`--dry-run`), and verify prerequisites (`--check`). + + + + +## Implementation Decisions + +### Env Audit Display +- **D-01:** Group env vars by source in three labeled sections: "Sandbox-generated" (HOME, PATH, SHELL, TMPDIR, etc.), "Host (allowlisted)" (TERM, EDITOR, ANTHROPIC_API_KEY, etc.), "Extra (CLAUDEBOX_EXTRA_ENV)" (user-added vars). Display to stderr. +- **D-02:** PATH is split by `:` and displayed one entry per line (indented under PATH=) for readability. +- **D-03:** Use plain ANSI escape codes for color/formatting — no external dependency like gum. Bold section headers, colored section labels. +- **D-04:** Auto-mask values where the variable name matches `*KEY*`, `*TOKEN*`, `*SECRET*`, `*PASSWORD*`, `*CREDENTIAL*` (case-insensitive). Show first 7 + last 4 characters with `...` in between. This catches ANTHROPIC_API_KEY and any user-added secrets via CLAUDEBOX_EXTRA_ENV. + +### Confirmation Prompt +- **D-05:** Use `Proceed? [Y/n]` prompt — default is proceed (Enter launches). User must type `n` or `no` to abort. +- **D-06:** If stdin is not a TTY (piped input, CI, scripts), abort with an error message telling the user to pass `--yes`/`-y`. Do NOT auto-proceed in non-interactive mode. +- **D-07:** All audit output and the prompt go to stderr. Keeps stdout clean. + +### CLI Flags +- **D-08:** `--yes` / `-y` skips the env audit display and confirmation entirely — launches immediately. (Per Phase 1 D-01, claudebox claims its own flags and passes the rest to claude.) +- **D-09:** `--dry-run` prints the full bwrap command without executing. Claude's discretion on exact format (multiline, annotated, etc.). +- **D-10:** `--check` verifies prerequisites: bwrap exists, required Nix packages available, `~/.claudebox` exists. Claude's discretion on diagnostic depth and output format. + +### Claude's Discretion +- `--dry-run` output format (single-line vs multiline, annotated vs raw) +- `--check` diagnostic depth (existence-only vs version checks vs connectivity tests) +- Exact ANSI color choices and spacing +- Flag parsing order and error messages for invalid flag combinations + + + + +## Canonical References + +**Downstream agents MUST read these before planning or implementing.** + +### Project Docs +- `.planning/PROJECT.md` — Core value, constraints, key decisions +- `.planning/REQUIREMENTS.md` — UX-01 through UX-05 requirement definitions +- `.planning/ROADMAP.md` — Phase 2 success criteria + +### Phase 1 Context +- `.planning/phases/01-minimal-viable-sandbox/01-CONTEXT.md` — D-01 (flag passthrough), D-03 (env allowlist + CLAUDEBOX_EXTRA_ENV) + +### Implementation +- `claudebox.sh` — Current script with ENV_ARGS array, HOST_ALLOWLIST, CLAUDEBOX_EXTRA_ENV parsing, bwrap invocation +- `flake.nix` — Nix derivation structure, runtimeInputs, SANDBOX_PATH injection + + + + +## Existing Code Insights + +### Reusable Assets +- `ENV_ARGS` array in claudebox.sh — already structures all env vars as `--setenv key value` pairs, can be iterated for audit display +- `HOST_ALLOWLIST` array — provides the list of host-passed vars +- `CLAUDEBOX_EXTRA_ENV` parsing block — already splits comma-separated extras +- Flag parsing `case/esac` block — extend with `--yes`, `-y`, `--dry-run`, `--check` + +### Established Patterns +- `writeShellApplication` with shellcheck and `set -euo pipefail` +- Flag parsing via `for arg in "$@"` with case/esac +- Temp file cleanup via trap + +### Integration Points +- Env audit logic goes between env construction and `exec bwrap` +- `--dry-run` replaces the `exec bwrap` call with a print +- `--check` is an early-exit path before any env construction +- Flag parsing extends the existing case/esac block + + + + +## Specific Ideas + +- PATH display: split by `:`, one Nix store path per line, indented under `PATH=` +- Masking regex: case-insensitive match on var name containing KEY, TOKEN, SECRET, PASSWORD, CREDENTIAL +- Non-interactive detection: `[[ -t 0 ]]` check on stdin + + + + +## Deferred Ideas + +None — discussion stayed within phase scope + + + +--- + +*Phase: 02-env-audit-and-cli-polish* +*Context gathered: 2026-04-09* diff --git a/.planning/phases/02-env-audit-and-cli-polish/02-DISCUSSION-LOG.md b/.planning/phases/02-env-audit-and-cli-polish/02-DISCUSSION-LOG.md new file mode 100644 index 0000000..71c0678 --- /dev/null +++ b/.planning/phases/02-env-audit-and-cli-polish/02-DISCUSSION-LOG.md @@ -0,0 +1,100 @@ +# Phase 2: Env Audit and CLI Polish - Discussion Log + +> **Audit trail only.** Do not use as input to planning, research, or execution agents. +> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered. + +**Date:** 2026-04-09 +**Phase:** 02-env-audit-and-cli-polish +**Areas discussed:** Env audit display format, Confirmation and non-interactive behavior + +--- + +## Env Audit Display Format + +### Grouping + +| Option | Description | Selected | +|--------|-------------|----------| +| Grouped by source | Three sections: Sandbox-generated, Host (allowlisted), Extra (CLAUDEBOX_EXTRA_ENV) | ✓ | +| Flat key=value list | Simple sorted list, no categories | | +| You decide | Claude's discretion | | + +**User's choice:** Grouped by source +**Notes:** User wants PATH split by `:` with one entry per line. Wants automatic spacing and color coding. + +### Color/Formatting + +| Option | Description | Selected | +|--------|-------------|----------| +| gum (Charm TUI) | Rich formatting, handles terminal detection, adds ~15MB | | +| Plain ANSI codes | printf with escape sequences, zero dependencies | ✓ | +| You decide | Claude's discretion | | + +**User's choice:** Plain ANSI codes +**Notes:** User initially considered gum but chose zero-dependency approach. + +### Value Masking + +| Option | Description | Selected | +|--------|-------------|----------| +| Mask sensitive values | Pattern-match on var name, show first 7 + last 4 chars | ✓ | +| Show full values | Display everything as-is | | +| You decide | Claude's discretion | | + +**User's choice:** Mask sensitive values +**Notes:** User asked about dependency for secret detection. Decided pattern-matching on var names is sufficient. + +### Masking Approach + +| Option | Description | Selected | +|--------|-------------|----------| +| Pattern-match var names | Regex: *KEY*, *TOKEN*, *SECRET*, *PASSWORD*, *CREDENTIAL* | ✓ | +| Hardcoded list | Only mask ANTHROPIC_API_KEY specifically | | + +**User's choice:** Pattern-match var names + +--- + +## Confirmation and Non-Interactive Behavior + +### Prompt Style + +| Option | Description | Selected | +|--------|-------------|----------| +| y/N prompt | Default abort, user must type 'y' | | +| Y/n prompt | Default proceed, Enter launches | ✓ | +| You decide | Claude's discretion | | + +**User's choice:** Y/n prompt (default proceed) + +### Non-TTY Behavior + +| Option | Description | Selected | +|--------|-------------|----------| +| Auto-proceed | Behave as if --yes in non-interactive | | +| Abort if no TTY | Refuse to run without explicit --yes | ✓ | +| You decide | Claude's discretion | | + +**User's choice:** Abort if no TTY — forces scripts to opt-in with --yes + +### Output Destination + +| Option | Description | Selected | +|--------|-------------|----------| +| stderr | Audit and prompt to stderr, stdout clean | ✓ | +| stdout | Everything to stdout | | + +**User's choice:** stderr + +--- + +## Claude's Discretion + +- `--dry-run` output format +- `--check` diagnostic depth and format +- Exact ANSI color choices +- Flag parsing order + +## Deferred Ideas + +None