boxdown 1.0.0 → 1.2.1

package/docs/superpowers/specs/2026-07-17-runtime-secret-environment-design.md

@@ -0,0 +1,194 @@
+# Runtime Secret Environment Design
+
+## Goal
+
+Keep Boxdown-provided secrets available as ordinary environment variables in
+container user sessions without placing their values in Docker container
+configuration, the workspace, or Boxdown's persistent state and logs.
+
+This design covers `ANTHROPIC_API_KEY`, `SNYK_TOKEN`, and
+`OP_SERVICE_ACCOUNT_TOKEN`. It also prevents the Docker inspection command
+used for image metadata from logging the complete container configuration.
+
+## Non-goals
+
+- Migrating, deleting, or rewriting legacy `.env.development` files.
+- Adding a `boxdown doctor --fix-secrets` command.
+- Preventing a user who can enter the container from reading secrets that are
+  deliberately available to that user's session.
+- Changing GitHub CLI authentication refresh, which already passes its host
+  token over stdin and redacts it from the workspace log.
+
+## Security Model
+
+The user has requested compatibility with the current developer experience:
+the three values above remain ordinary environment variables in Bash-based
+container sessions. This intentionally permits session processes to read them.
+
+The protection boundary is against accidental exposure outside that session:
+
+- Docker inspection must not contain secret values.
+- The repository and its `.env.development` file must not be created,
+  modified, or removed by Boxdown secret handling.
+- Boxdown's persistent workspace data and `boxdown.log` must not contain
+  secret values.
+- Secret files are short-lived, host-private runtime state and are mounted
+  read-only into the container.
+
+## Architecture
+
+### Host runtime secret state
+
+`WorkspaceContext` gains a per-workspace runtime-secret directory under a
+user-private runtime root. The root uses `XDG_RUNTIME_DIR` when available and
+a user-private directory under the system temporary directory otherwise. It
+is distinct from `workspaceDataDir`, which is persistent and contains logs and
+metadata.
+
+The directory and each secret file are created with owner-only permissions
+(`0700` directory, `0600` files). The three files use fixed names matching
+their environment variables. No secret value appears in generated
+configuration, command arguments, progress output, metadata, or diagnostics.
+
+The host-side `initializeCommand` refreshes this directory before each
+Dev Container startup:
+
+1. It creates the runtime directory safely.
+2. It writes `ANTHROPIC_API_KEY` and `SNYK_TOKEN` only when each corresponding
+   host environment value is non-empty.
+3. It retrieves `OP_SERVICE_ACCOUNT_TOKEN` from the existing 1Password item
+   only when `op` is available and can read it.
+4. It atomically replaces files for available values and removes files for
+   unavailable values, preventing a stale token from a previous start.
+
+Failures to retrieve 1Password or an absent host variable are informational
+and non-blocking. The affected variable is absent from the next container
+session.
+
+### Generated Dev Container configuration
+
+The base `runArgs` no longer includes:
+
+```text
+--env-file ${localWorkspaceFolder}/.env.development
+```
+
+The base `containerEnv` no longer includes secret values via `localEnv`.
+`NODE_ENV` remains ordinary non-secret configuration.
+
+Boxdown's generated configuration adds a read-only bind mount from the host
+runtime-secret directory to `/run/boxdown/secrets`. It may contain non-secret
+bootstrap configuration such as `BASH_ENV` and the mounted directory path,
+but never a secret value.
+
+Because mounts are create-time settings, `boxdown start --recreate` is needed
+for an already-created container to receive the new mount. New containers get
+it automatically through every Boxdown lifecycle path (`setup`, `start`,
+`codex`, and the other coding-agent commands).
+
+### Container session bootstrap
+
+A mounted Boxdown bootstrap script reads only the fixed secret files, then
+exports values that are present. It never echoes values or shell source lines.
+It handles missing or unreadable files by leaving the corresponding variable
+unset.
+
+The generated configuration sets the non-secret `BASH_ENV` path so
+non-interactive Bash processes source the bootstrap. The container setup also
+installs the bootstrap in the `node` user's Bash startup path for interactive
+shells and SSH sessions. Boxdown's direct shell and coding-agent launch
+scripts source it explicitly before `exec` as an additional deterministic
+path.
+
+Consequently, an ordinary Bash session can use, for example,
+`$ANTHROPIC_API_KEY`, `$SNYK_TOKEN`, and `$OP_SERVICE_ACCOUNT_TOKEN` as it can
+today. Docker's configured environment contains only the bootstrap path and
+other non-secret values, so `docker inspect` cannot reveal secret contents.
+
+### Workspace file handling
+
+The initialization hook stops creating or editing `.env.development`. The
+post-start hook stops deleting it. Boxdown therefore treats that file as
+project-owned in all cases.
+
+This release deliberately does not modify legacy files. A pre-existing
+`OP_SERVICE_ACCOUNT_TOKEN` value remains the user's responsibility to remove
+or rotate. Documentation will state that Boxdown no longer reads the file and
+that users should remove a legacy accidental entry manually.
+
+### Logging and Docker inspection
+
+Boxdown currently runs `docker inspect --format '{{json .}}'` only to record
+the image ID and image name. The full payload includes `.Config.Env`, and the
+command logger writes all child output even when it is not mirrored to the
+terminal.
+
+The implementation replaces that command with a narrow template that returns
+only the image ID and configured image name. Its parser accepts that narrow,
+non-sensitive output; it never parses a complete inspect object.
+
+The workspace logger also gains structural redaction for assignments of the
+three Boxdown secret variable names. This is a defense-in-depth backstop for
+legacy logs or future accidental command output, not the primary protection.
+Existing value-based redaction remains for dynamically acquired GitHub tokens.
+
+## Lifecycle and Cleanup
+
+- `initializeCommand` is the only writer of runtime secret files.
+- `down` and `purge` remove the runtime-secret directory after stopping or
+  removing the associated container.
+- A new start refreshes values atomically, so no previous value remains when a
+  host value is absent or 1Password lookup fails.
+- Runtime secret state is never written below `workspaceDataDir` and is never
+  included in status output.
+- Existing workspaces require `boxdown start --recreate` to replace the old
+  Docker environment configuration. Boxdown will not automatically migrate
+  existing containers or `.env.development` files.
+
+## Diagnostics and Documentation
+
+Startup output may state whether the optional 1Password token was available,
+but must not print values, file contents, or paths that encode secret data.
+`boxdown doctor` verifies that the runtime-secret mount is constructible and
+that the generated configuration contains neither the legacy `--env-file`
+argument nor secret `containerEnv` entries. Missing optional values are
+warnings, not failures.
+
+Documentation will explain:
+
+- which host values Boxdown forwards;
+- that they are exposed to Bash sessions but not Docker configuration;
+- that `.env.development` is project-owned and ignored by Boxdown;
+- that `--recreate` is required for existing containers; and
+- how to manually remove and rotate a legacy 1Password token if it was
+  previously written to a workspace or log.
+
+## Test Strategy
+
+Tests will cover:
+
+- host secret-state creation, owner-only modes, atomic refresh, and removal of
+  stale files without printing values;
+- success, missing host values, missing `op`, and failed 1Password lookup as
+  non-blocking cases;
+- generated configuration contains the read-only runtime mount and contains no
+  `--env-file`, secret `containerEnv` keys, or secret values;
+- `.env.development` is neither created nor altered by initialization or
+  post-start hooks;
+- interactive, non-interactive, SSH, and Boxdown coding-agent Bash launch
+  paths export available values and leave unavailable values unset;
+- image inspection uses only a narrow projection and workspace logs never
+  receive a synthetic inspect environment value;
+- logger structural redaction for all three known keys;
+- doctor warnings and mount probes, with optional-secret absence non-fatal;
+- focused tests first, then the full test suite, lint, build, Bash syntax
+  checks, and `git diff --check`.
+
+## Decision Record
+
+The chosen design favors compatibility over strict command-level least
+privilege. The three values are intentionally ordinary environment variables
+inside Bash sessions. If this causes unacceptable in-container exposure or
+developer-experience problems, a future design may replace session bootstrap
+with per-command wrappers. That change would be a deliberate compatibility
+break and is not part of this work.

package/docs/testing.md

@@ -21,12 +21,18 @@ Unit tests should avoid starting Docker. Prefer pure tests for:
 - Workspace path resolution and state directory selection.
 - Generated devcontainer config shape.
 - SSH config block creation and idempotent replacement.
+- SSH install target parsing and prompt behavior, including explicit target
+  flags, prompt selection, prompt skip/cancel, and non-TTY fallback.
+- Codex app/global-state target installation, legacy path migration,
+  and idempotent project injection.
 - Lifecycle status and doctor output formatting.
 - Workspace metadata and list output formatting.
 - Safety invariants, such as not packaging `.ssh/` key material.
 
 Use temporary directories for workspace and state tests. Do not write to the
-user's real SSH config in unit tests.
+user's real SSH config or Codex app config in unit tests. Use
+`BOXDOWN_CODEX_APP_CONFIG` or direct helper path overrides for Codex config
+fixtures.
 
 ## Build and CLI Smoke Tests
 
@@ -49,15 +55,42 @@ Confirm `assets/devcontainer/**` is included and `.ssh/` is not.
 Manual Docker acceptance is heavier and should be done intentionally:
 
 ```sh
+boxdown setup --workspace /path/to/repo
+boxdown setup --workspace /path/to/repo --target codex
+boxdown setup --workspace /path/to/repo --target claude
 boxdown start --workspace /path/to/repo
 boxdown list
 boxdown list --json
 boxdown status --workspace /path/to/repo
 boxdown status --workspace /path/to/repo --json
 boxdown doctor --workspace /path/to/repo
-boxdown ssh-config install --workspace /path/to/repo
+boxdown ssh install --workspace /path/to/repo
+boxdown ssh install --workspace /path/to/repo --target codex
+boxdown ssh install --workspace /path/to/repo --target claude
+CI=1 boxdown ssh install --workspace /path/to/repo
 ssh <repo-name>-devcontainer 'whoami && pwd'
+boxdown down --workspace /path/to/repo-a --workspace /path/to/repo-b
+boxdown purge --workspace /path/to/disposable-repo
 ```
 
+The plain `ssh install` command should show the optional target selector when
+run in an interactive terminal. The explicit `--target codex` and
+`--target claude` commands verify scriptable target installation, and the `CI=1`
+command verifies the non-interactive skip path without blocking.
+
+The plain `tunnel` command should prompt for ports in an interactive terminal.
+Use `boxdown tunnel --workspace /path/to/repo --port 3030` when testing the
+non-interactive or fully explicit path.
+
+When checking browser access, start a dev server inside the container and keep a
+foreground tunnel open from the host:
+
+```sh
+boxdown tunnel --workspace /path/to/repo
+boxdown tunnel --workspace /path/to/repo --port 3030
+```
+
+Confirm `http://localhost:3030/` works, then stop the tunnel with Ctrl-C.
+
 Run this from at least two repositories when changing workspace isolation,
 container lookup, SSH config generation, or generated config behavior.

package/docs/todo.md

@@ -35,11 +35,11 @@ Acceptance commands:
 
 ```sh
 boxdown start --workspace ~/projects/repos/gh-cp
-boxdown ssh-config install --workspace ~/projects/repos/gh-cp
+CI=1 boxdown ssh install --workspace ~/projects/repos/gh-cp
 ssh gh-cp-devcontainer 'whoami && pwd'
 
 boxdown start --workspace ~/projects/repos/lirantaldotcom
-boxdown ssh-config install --workspace ~/projects/repos/lirantaldotcom
+CI=1 boxdown ssh install --workspace ~/projects/repos/lirantaldotcom
 ssh lirantaldotcom-devcontainer 'whoami && pwd'
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "boxdown",
-  "version": "1.0.0",
+  "version": "1.2.1",
   "description": "Run a reusable devcontainer sandbox for any local project",
   "types": "dist/main.d.mts",
   "type": "module",

package/src/claude-app-config.ts

@@ -0,0 +1,304 @@
+import { randomUUID } from 'node:crypto'
+import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+import type { WorkspaceContext } from './paths.ts'
+
+export const CLAUDE_APP_SUPPORT_DIRNAME = 'Claude'
+export const CLAUDE_SSH_CONFIGS_FILENAME = 'ssh_configs.json'
+
+export interface ClaudeSshConfigEntry {
+  name: string
+  sshHost: string
+  id: string
+  source?: string
+  [key: string]: unknown
+}
+
+export interface ClaudeSshConfigs {
+  configs: ClaudeSshConfigEntry[]
+  trustedHosts: string[]
+  [key: string]: unknown
+}
+
+export interface ClaudeSshConfigTargetEntry {
+  name: string
+  sshHost: string
+}
+
+export interface InstallClaudeSshConfigResult {
+  configPath: string
+  backupPath?: string
+  changed: boolean
+}
+
+export interface UninstallClaudeSshConfigResult {
+  configPath: string
+  backupPath?: string
+  changed: boolean
+}
+
+function isRecord (value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function parseRequiredString (value: unknown, key: string): string {
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw new Error(`Invalid Claude SSH config: ${key} must be a nonempty string`)
+  }
+
+  return value.trim()
+}
+
+function parseOptionalString (value: unknown, key: string): string | undefined {
+  if (value === undefined) {
+    return undefined
+  }
+
+  if (typeof value !== 'string') {
+    throw new Error(`Invalid Claude SSH config: ${key} must be a string`)
+  }
+
+  return value
+}
+
+function parseStringArray (value: unknown, key: string): string[] {
+  if (value === undefined) {
+    return []
+  }
+
+  if (!Array.isArray(value)) {
+    throw new Error(`Invalid Claude SSH config: ${key} must be an array`)
+  }
+
+  return value.map((item) => {
+    if (typeof item !== 'string') {
+      throw new Error(`Invalid Claude SSH config: ${key} entries must be strings`)
+    }
+
+    return item
+  })
+}
+
+function parseClaudeSshConfigEntry (value: unknown): ClaudeSshConfigEntry {
+  if (!isRecord(value)) {
+    throw new Error('Invalid Claude SSH config: configs entries must be objects')
+  }
+
+  const source = parseOptionalString(value.source, 'source')
+  const parsed: ClaudeSshConfigEntry = {
+    ...value,
+    name: parseRequiredString(value.name, 'name'),
+    sshHost: parseRequiredString(value.sshHost, 'sshHost'),
+    id: parseRequiredString(value.id, 'id')
+  }
+
+  if (source !== undefined) {
+    parsed.source = source
+  } else {
+    delete parsed.source
+  }
+
+  return parsed
+}
+
+export function parseClaudeSshConfigs (value: unknown): ClaudeSshConfigs {
+  if (!isRecord(value)) {
+    throw new Error('Invalid Claude SSH config: top-level value must be an object')
+  }
+
+  const configs = value.configs
+  if (configs !== undefined && !Array.isArray(configs)) {
+    throw new Error('Invalid Claude SSH config: configs must be an array')
+  }
+
+  return {
+    ...value,
+    configs: (configs ?? []).map((config) => parseClaudeSshConfigEntry(config)),
+    trustedHosts: parseStringArray(value.trustedHosts, 'trustedHosts')
+  }
+}
+
+export function defaultClaudeSshConfigsPath (
+  env: NodeJS.ProcessEnv = process.env,
+  platform: NodeJS.Platform = process.platform
+): string {
+  if (env.BOXDOWN_CLAUDE_SSH_CONFIGS !== undefined) {
+    return env.BOXDOWN_CLAUDE_SSH_CONFIGS
+  }
+
+  const home = env.HOME ?? homedir()
+
+  if (platform === 'darwin') {
+    return join(home, 'Library', 'Application Support', CLAUDE_APP_SUPPORT_DIRNAME, CLAUDE_SSH_CONFIGS_FILENAME)
+  }
+
+  if (platform === 'win32') {
+    return join(env.APPDATA ?? join(home, 'AppData', 'Roaming'), CLAUDE_APP_SUPPORT_DIRNAME, CLAUDE_SSH_CONFIGS_FILENAME)
+  }
+
+  return join(env.XDG_CONFIG_HOME ?? join(home, '.config'), CLAUDE_APP_SUPPORT_DIRNAME, CLAUDE_SSH_CONFIGS_FILENAME)
+}
+
+export function claudeSshConfigEntryForWorkspace (context: WorkspaceContext, sshHost: string): ClaudeSshConfigTargetEntry {
+  return {
+    name: context.workspaceBasename,
+    sshHost
+  }
+}
+
+function readClaudeSshConfigsFile (configPath: string): ClaudeSshConfigs {
+  if (!existsSync(configPath)) {
+    return {
+      configs: [],
+      trustedHosts: []
+    }
+  }
+
+  let parsed: unknown
+
+  try {
+    parsed = JSON.parse(readFileSync(configPath, 'utf8')) as unknown
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      throw new Error(`Invalid Claude SSH config JSON: ${configPath}`, { cause: error })
+    }
+
+    throw error
+  }
+
+  return parseClaudeSshConfigs(parsed)
+}
+
+function backupPathFor (configPath: string, now: Date): string {
+  return `${configPath}.${now.toISOString().replace(/[:.]/gu, '-')}.bak`
+}
+
+function writeJsonAtomic (path: string, json: string): void {
+  const tmpPath = `${path}.tmp-${process.pid}-${Date.now()}`
+  writeFileSync(tmpPath, json)
+  renameSync(tmpPath, path)
+}
+
+function withTrustedHost (trustedHosts: readonly string[], sshHost: string): string[] {
+  return [...new Set([...trustedHosts, sshHost])]
+}
+
+export function mergeClaudeSshConfigHost (
+  config: ClaudeSshConfigs,
+  entry: ClaudeSshConfigTargetEntry,
+  createId: () => string = randomUUID
+): ClaudeSshConfigs {
+  let matched = false
+  const configs = config.configs.map((configEntry) => {
+    if (configEntry.sshHost !== entry.sshHost) {
+      return configEntry
+    }
+
+    matched = true
+    return {
+      ...configEntry,
+      name: entry.name,
+      sshHost: entry.sshHost
+    }
+  })
+
+  if (!matched) {
+    configs.push({
+      name: entry.name,
+      sshHost: entry.sshHost,
+      id: createId(),
+      source: 'desktop'
+    })
+  }
+
+  return {
+    ...config,
+    configs,
+    trustedHosts: withTrustedHost(config.trustedHosts, entry.sshHost)
+  }
+}
+
+export function removeClaudeSshConfigHost (
+  config: ClaudeSshConfigs,
+  entry: ClaudeSshConfigTargetEntry
+): ClaudeSshConfigs {
+  return {
+    ...config,
+    configs: config.configs.filter((configEntry) => configEntry.sshHost !== entry.sshHost),
+    trustedHosts: config.trustedHosts.filter((trustedHost) => trustedHost !== entry.sshHost)
+  }
+}
+
+export function installClaudeSshConfigHost (
+  entry: ClaudeSshConfigTargetEntry,
+  options: { configPath?: string, now?: Date, createId?: () => string } = {}
+): InstallClaudeSshConfigResult {
+  const configPath = options.configPath ?? defaultClaudeSshConfigsPath()
+  const configDir = dirname(configPath)
+  const existingConfigExists = existsSync(configPath)
+  const existingConfig = readClaudeSshConfigsFile(configPath)
+  const nextConfig = mergeClaudeSshConfigHost(existingConfig, entry, options.createId)
+  const nextJson = `${JSON.stringify(nextConfig, null, 2)}\n`
+  const existingJson = existingConfigExists ? readFileSync(configPath, 'utf8') : undefined
+
+  if (existingJson === nextJson) {
+    return {
+      configPath,
+      changed: false
+    }
+  }
+
+  mkdirSync(configDir, { recursive: true })
+
+  let backupPath: string | undefined
+  if (existingConfigExists) {
+    backupPath = backupPathFor(configPath, options.now ?? new Date())
+    copyFileSync(configPath, backupPath)
+  }
+
+  writeJsonAtomic(configPath, nextJson)
+
+  return {
+    configPath,
+    ...(backupPath === undefined ? {} : { backupPath }),
+    changed: true
+  }
+}
+
+export function uninstallClaudeSshConfigHost (
+  entry: ClaudeSshConfigTargetEntry,
+  options: { configPath?: string, now?: Date } = {}
+): UninstallClaudeSshConfigResult {
+  const configPath = options.configPath ?? defaultClaudeSshConfigsPath()
+  const existingConfigExists = existsSync(configPath)
+
+  if (!existingConfigExists) {
+    return {
+      configPath,
+      changed: false
+    }
+  }
+
+  const existingConfig = readClaudeSshConfigsFile(configPath)
+  const nextConfig = removeClaudeSshConfigHost(existingConfig, entry)
+
+  if (JSON.stringify(existingConfig) === JSON.stringify(nextConfig)) {
+    return {
+      configPath,
+      changed: false
+    }
+  }
+
+  const nextJson = `${JSON.stringify(nextConfig, null, 2)}\n`
+  const backupPath = backupPathFor(configPath, options.now ?? new Date())
+  copyFileSync(configPath, backupPath)
+  writeJsonAtomic(configPath, nextJson)
+
+  return {
+    configPath,
+    backupPath,
+    changed: true
+  }
+}

package/src/cli-style.ts

@@ -0,0 +1,43 @@
+export const ansi = {
+  bold: '\u001B[1m',
+  cyan: '\u001B[36m',
+  dim: '\u001B[2m',
+  green: '\u001B[32m',
+  red: '\u001B[31m',
+  yellow: '\u001B[33m',
+  reset: '\u001B[0m'
+} as const
+
+export type CliColor = keyof typeof ansi
+
+export function color (value: string, colorName: CliColor): string {
+  return `${ansi[colorName]}${value}${ansi.reset}`
+}
+
+export function selectedMark (): string {
+  return color('■', 'green')
+}
+
+export function emptyMark (isFocused: boolean): string {
+  return color('□', isFocused ? 'cyan' : 'dim')
+}
+
+export function promptRail (): string {
+  return color('│', 'cyan')
+}
+
+export function formatPromptTitle (title: string): string {
+  return `${color('◆', 'cyan')}  ${color(title, 'bold')}`
+}
+
+export function formatPromptEnd (): string {
+  return color('└', 'cyan')
+}
+
+export function formatPromptLabel (label: string, isFocused: boolean): string {
+  return color(label, isFocused ? 'bold' : 'dim')
+}
+
+export function formatPromptDetailLine (detail: string): string {
+  return `${promptRail()}  ${color(detail, 'dim')}`
+}