100 lines
4.4 KiB
Markdown
100 lines
4.4 KiB
Markdown
# Phase 2: Env Audit and CLI Polish - Context
|
|
|
|
**Gathered:** 2026-04-09
|
|
**Status:** Ready for planning
|
|
|
|
<domain>
|
|
## 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`).
|
|
|
|
</domain>
|
|
|
|
<decisions>
|
|
## 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
|
|
|
|
</decisions>
|
|
|
|
<canonical_refs>
|
|
## 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
|
|
|
|
</canonical_refs>
|
|
|
|
<code_context>
|
|
## 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
|
|
|
|
</code_context>
|
|
|
|
<specifics>
|
|
## 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
|
|
|
|
</specifics>
|
|
|
|
<deferred>
|
|
## Deferred Ideas
|
|
|
|
None — discussion stayed within phase scope
|
|
|
|
</deferred>
|
|
|
|
---
|
|
|
|
*Phase: 02-env-audit-and-cli-polish*
|
|
*Context gathered: 2026-04-09*
|