boxdown 1.0.0 → 1.2.1

package/README.md

@@ -28,7 +28,7 @@ npm install -g boxdown
 You can also run it without installing:
 
 ```sh
-npx boxdown start
+npx boxdown setup
 ```
 
 ## Usage
@@ -36,22 +36,46 @@ npx boxdown start
 From any project repository on your host:
 
 ```sh
-npx boxdown start
+npx boxdown setup
 ```
 
-Boxdown builds or reuses a Dev Container for the current directory, then opens a shell inside it. The target repository stays clean; Boxdown writes generated configuration and SSH keys under user cache/data directories instead of copying `.devcontainer/` into the project.
+Boxdown builds or reuses a Dev Container for the current directory and installs
+an SSH alias for remote tools. The target repository stays clean; Boxdown writes
+generated configuration and SSH keys under user cache/data directories instead
+of copying `.devcontainer/` into the project.
+
+Startup commands print concise progress by default and hide raw Docker,
+Dev Containers, and lifecycle hook logs unless a step fails. Add `--verbose` to
+stream the full command output while setup/start work runs. Boxdown also keeps
+one append-only per-workspace command log under its data directory; `boxdown
+status` shows the exact path. Interactive shell, agent, and tunnel session bytes
+are not tee'd into the log.
+
+Open an interactive shell inside the container when you need one:
+
+```sh
+npx boxdown start
+```
 
 Boxdown ships and invokes its own `@devcontainers/cli` dependency. It does not require a host/global Dev Containers CLI install.
 
 ### Portless SSH
 
-Install an SSH alias for the current project:
+`boxdown setup` installs an SSH alias for the current project. To only install
+or update that alias without starting the devcontainer, use the lower-level SSH
+command:
 
 ```sh
-npx boxdown ssh-config install
+npx boxdown ssh install
 ```
 
-By default this creates a `<repo-name>-devcontainer` SSH host. Validate it with:
+This creates a `<repo-name>-devcontainer` SSH host. When run in an interactive
+terminal, Boxdown also asks whether to install optional targets such as Codex
+and Claude.
+Non-interactive runs skip optional targets and print the explicit `--target`
+form to use in scripts.
+
+Validate the SSH alias with:
 
 ```sh
 ssh <repo-name>-devcontainer 'whoami && pwd'
@@ -59,32 +83,95 @@ ssh <repo-name>-devcontainer 'whoami && pwd'
 
 Use the same alias in Cursor, Claude, Codex, or any SSH-capable tool.
 
+To also add the project to Codex's remote project sidebar or Claude's SSH
+remote list, pass one or more targets during setup or select them from the
+lower-level SSH prompt:
+
+```sh
+npx boxdown setup --target codex
+npx boxdown setup --target claude
+```
+
+The lower-level SSH command also supports the same targets for scripts:
+
+```sh
+npx boxdown ssh install --target codex
+npx boxdown ssh install --target claude
+```
+
+Restart the target app after installing it so it applies the updated remote
+project config.
+
+From the target project directory, forward a dev server running inside the
+container to your host browser:
+
+```sh
+npx boxdown tunnel --port 3030
+```
+
+If `--port` is omitted in an interactive terminal, Boxdown asks which port or
+port mappings to forward and defaults to the generated devcontainer published
+port when available. Non-interactive runs still require `--port`.
+
+This keeps a foreground SSH tunnel open until you press Ctrl-C. The host and
+Codex in-app browser can then open `http://localhost:3030/`. Repeat `--port`
+or use `<local:remote>` mappings when needed:
+
+```sh
+npx boxdown tunnel --port 3030 --port 8080:3031
+```
+
+Use `--workspace <path>` only when running the command from a different
+directory. Repeat it with `down` to remove multiple workspace containers in one
+command. When `down` runs from a directory that is not a known Boxdown
+workspace, interactive terminals show a workspace picker instead.
+
+Remove Boxdown's managed SSH host block and matching Codex/Claude app entries
+when you no longer need the alias:
+
+```sh
+npx boxdown ssh uninstall
+```
+
 ### Commands
 
 ```sh
+boxdown setup
 boxdown start
 boxdown codex
 boxdown claude
-boxdown cc
 boxdown opencode
 boxdown antigravity
 boxdown list
 boxdown status
 boxdown stop
 boxdown down
+boxdown purge
 boxdown doctor
-boxdown ssh-config install
+boxdown ssh install
+boxdown ssh uninstall
 boxdown ssh-proxy
+boxdown tunnel --port 3030
 boxdown refresh-gh-token
 boxdown refresh-gh-token-running
 ```
 
 `boxdown shell` remains supported as an alias for `boxdown start`, but
 documentation uses `start` as the canonical command.
+`boxdown cc` remains supported as an alias for `boxdown claude`, but
+documentation uses `claude` as the canonical command.
+
+`boxdown setup` begins with a host-readiness preflight before it prompts for
+SSH targets, writes workspace state, or starts Docker work. Required failures
+such as an unavailable Docker daemon stop setup with an actionable summary.
+When a local Docker image is available, the preflight also performs a no-pull,
+no-start bind-mount probe for the workspace and Boxdown-managed mount paths.
+Run `boxdown doctor` directly for the complete diagnostic report; an unavailable
+best-effort mount probe is reported as a warning and does not block setup.
 
-The coding-agent commands start or reuse the devcontainer, refresh the selected
-CLI, then launch it directly inside the container. Use `--` to pass arguments to
-the agent:
+Container bring-up installs Codex and Claude Code by default. The OpenCode and
+Antigravity commands stay available, but install/update those CLIs only when you
+launch them. Use `--` to pass arguments to the selected agent:
 
 ```sh
 boxdown claude -- --continue
@@ -94,18 +181,54 @@ List Boxdown-known devcontainer environments from any directory:
 
 ```sh
 boxdown list
+boxdown list --details
 boxdown list --json
+boxdown list --format json
 ```
 
+Human `boxdown list` output shows `STATE`, `REPO`, `PATH`, and `CONTAINER`.
+Use `boxdown list --details` when you need full copyable paths and SSH aliases
+in human output. Use `boxdown list --json` or `boxdown list --format json` for
+the same structured inventory.
+
 Shared options:
 
 ```sh
---workspace <path>  # target project directory, defaults to cwd
+--workspace <path>  # target project directory, defaults to cwd; repeatable with down; purge also accepts list values
 --alias <name>      # SSH alias, defaults to <repo-name>-devcontainer
+--target <name>     # with setup/ssh install, optional target; repeatable; supported: codex, claude
+--port <port>       # tunnel port for `boxdown tunnel`; repeatable
 --recreate          # recreate the devcontainer before starting
 --json              # JSON output for status and list
+--format json       # JSON output for status and list; equivalent to --json
+--details           # detailed human output for list
+```
+
+Use `boxdown purge` when you want to remove the workspace's Boxdown-managed
+environment residue: the devcontainer, its exact recorded Docker image, managed
+SSH/Codex/Claude entries, command log, and Boxdown cache/data for that
+workspace. It does not delete the local repository directory or files inside it.
+Interactive terminals ask for confirmation before purging.
+
+For `purge`, `--workspace` accepts the `PATH` or unambiguous `REPO` value
+shown by `boxdown list`. It also accepts exact `SSH ALIAS` values from
+`boxdown status`, `boxdown list --details`, or JSON list output:
+
+```sh
+boxdown purge
+boxdown purge --workspace my-repo-devcontainer
+boxdown purge --workspace my-repo
+boxdown purge --workspace /path/to/my-repo
 ```
 
+When `boxdown purge` runs without `--workspace` from a directory that is not a
+tracked Boxdown workspace, interactive terminals show a multi-select list of all
+tracked workspaces, including missing/stale entries. The focused row highlights
+the state token: `running` is green, `exited` is yellow, and `absent`,
+`missing`, or `unknown` are red. Non-interactive runs fail safely from
+untracked directories; scripts should call `boxdown purge --workspace <value>`
+for each workspace.
+
 ## Contributing
 
 Please consult [CONTRIBUTING](./CONTRIBUTING.md) for guidelines on contributing to this project.

package/assets/devcontainer/README.md

@@ -1,11 +1,11 @@
 # Dev container
 
-Run this project in a **consistent Node.js 24 + TypeScript** environment without installing toolchains on your machine. Dependencies install automatically; your repo is the workspace inside the container.
+Run this project in a **consistent Node.js 24 + TypeScript** environment without installing toolchains on your machine. The container starts from the slim Node 24 Debian image, then adds only the shared tools Boxdown needs. Dependencies install automatically; your repo is the workspace inside the container.
 
 ## Why use it?
 
-- **Same stack for everyone** — Node 24, pnpm, and tooling match CI and collaborators.
-- **Fast onboarding** — Open the folder in a container; `pnpm install` and local git tweaks run once after create.
+- **Same stack for everyone** — Node 24 plus pinned features provide Git, uv, ripgrep, GitHub CLI, and common shell utilities; Debian Python is installed during post-create.
+- **Fast onboarding** — Open the folder in a container; dependency installation and local git tweaks run once after create. pnpm-based workspaces bootstrap `pnpm@11` when needed.
 - **Host secrets, container dev** — `ANTHROPIC_API_KEY` and `SNYK_TOKEN` are passed from your Mac/Linux session into the container when set locally (see below).
 - **Optional CLI workflow** — Use `start.sh` if you prefer a terminal-driven container instead of only the editor.
 - **Portless SSH workflow** — Install a normal SSH host alias that proxies into the devcontainer without publishing an SSH port.
@@ -14,15 +14,27 @@ Run this project in a **consistent Node.js 24 + TypeScript** environment without
 
 | File | Role |
 | ---- | ---- |
-| `devcontainer.json` | Image, mounts (e.g. your `~/.gitconfig`), lifecycle commands, env forwarding. |
+| `devcontainer.json` | Slim Node base image, pinned feature set/order, Boxdown state mounts, lifecycle commands, env forwarding. |
 | `start.sh` | Brings the dev container up with the Dev Containers CLI, then opens a shell **inside** the container or acts as an SSH `ProxyCommand`. |
 | `ssh-config-install.sh` | Installs/updates a host SSH config alias for Cursor, Claude, or plain `ssh`. |
-| `hooks/initialize.sh` | Runs on the host before container create/start; prepares the env file and optional secrets. |
-| `hooks/post-create.sh` | Runs once after the container is created — e.g. installs [APM](https://github.com/microsoft/apm) (Agent Package Manager), coding-agent CLIs, and OpenSSH server. |
+| `hooks/initialize.sh` | Runs on the host before container create/start; refreshes private runtime secret files and host Git state. |
+| `hooks/post-create.sh` | Runs once after the container is created — e.g. installs OpenSSH server, Debian Python, [APM](https://github.com/microsoft/apm) (Agent Package Manager), and default coding-agent CLIs. |
 | `hooks/post-start.sh` | Runs on each container start; refreshes runtime state such as SSH host keys and authorized keys. |
+| `utils/git-config-bootstrap.sh` | Container-side Git config copy/sanitization helper used by lifecycle scripts. |
+| `utils/python-bootstrap.sh` | Container-side Debian Python runtime helper used by lifecycle scripts. |
 | `utils/ssh-bootstrap.sh` | Container-side OpenSSH install/runtime helper used by lifecycle scripts. |
 | `utils/coding-agent-cli-update.sh` | Shared install/update helper for Codex, OpenCode, Claude Code, and Antigravity CLI. |
-| `utils/deps-install.sh` | Dependency installation helper used by `hooks/post-create.sh`. |
+| `utils/deps-install.sh` | Dependency installation helper used by `hooks/post-create.sh`; bootstraps pnpm/yarn when the slim base does not provide them. |
+
+## Base image
+
+Boxdown uses `node:24-trixie-slim` as the base image to keep the shared image smaller than the full Dev Containers TypeScript/Node image. The devcontainer then installs the required operating-system tools through pinned Dev Container features. `common-utils` and `git` run first so later features and lifecycle hooks can rely on shell basics, `sudo`, package metadata, Git, and related utilities.
+
+Python is installed during `postCreateCommand` from Debian apt packages (`python3`, `python3-venv`, `python3-pip`, and `pipx`). On Debian trixie this currently provides Python 3.13. Boxdown intentionally avoids the Dev Containers Python feature because it added a large Python runtime/dev-tooling layer, including bundled environments for tools such as mypy, black, pylint, pytest, bandit, pipenv, and flake8.
+
+uv remains a separate pinned feature. It provides `uv`/`uvx`, but it does not provide the system Python runtime by default.
+
+JavaScript package managers are handled at workspace setup time: npm comes from the Node image, pnpm is installed as `pnpm@11` for pnpm projects, and Yarn is enabled through Corepack when needed.
 
 ## Usage
 
@@ -40,7 +52,7 @@ From the **repository root** on your host:
 bash .devcontainer/start.sh
 ```
 
-Requires Docker running. The script resolves Boxdown's packaged `@devcontainers/cli` dependency and uses that binary to `up` the workspace and `exec` into `bash`; it does not install or use a host/global Dev Containers CLI package.
+Requires Docker running. The script resolves Boxdown's packaged `@devcontainers/cli` dependency and uses that binary to `up` the workspace and `exec` into `bash`; it does not install or use a host/global Dev Containers CLI package. Startup output is concise by default; pass `--verbose` to stream raw Docker, Dev Containers, and hook logs.
 
 ### GitHub CLI auth from host `gh`
 
@@ -71,10 +83,13 @@ use HTTPS and ask the container's `gh` for credentials during `git fetch`,
 `git pull`, and `git push`. This is intentionally tied to the explicit refresh
 command; regular SSH remote connections do not copy GitHub credentials.
 
-If your host `.gitconfig` is mounted into the container, Boxdown adds local
-repository settings that neutralize incompatible host-only helpers such as
-`/opt/homebrew/bin/gh` and broad rewrites such as
-`url.git@github.com:.insteadOf=https://github.com/`.
+Boxdown snapshots your host `.gitconfig` into workspace state before container
+creation, mounts that snapshot read-only, and copies it to a normal writable
+`/home/node/.gitconfig` during `postCreateCommand`. The container copy is then
+sanitized to neutralize incompatible host-only helpers such as
+`/opt/homebrew/bin/gh`, broad rewrites such as
+`url.git@github.com:.insteadOf=https://github.com/`, and host-only signing
+settings.
 
 If the container is already running and you only want to refresh its GitHub auth:
 
@@ -92,7 +107,7 @@ first when you need to repair host GitHub auth.
 From the **repository root** on your host, install or update the SSH alias:
 
 ```bash
-bash .devcontainer/start.sh ssh-config install
+bash .devcontainer/start.sh ssh install
 ```
 
 By default, this creates:
@@ -112,7 +127,7 @@ Then use the same host alias in Cursor, Claude, or any other SSH client:
 - **SSH Host:** `<repo-name>-devcontainer`
 - **SSH Port:** leave empty
 - **Identity File:** leave empty if the client reads `~/.ssh/config`; otherwise use `.devcontainer/.ssh/id_ed25519`
-- **Remote Folder:** select `<repo-name>` from the default home folder, or enter `/workspaces/<repo-name>`
+- **Remote Folder:** enter `/workspaces/<repo-name>`
 
 To customize the alias, run:
 
@@ -129,7 +144,7 @@ If you are a coding agent running on the host OS, prefer the SSH alias workflow.
 From the repository root on the host:
 
 ```bash
-bash .devcontainer/start.sh ssh-config install
+bash .devcontainer/start.sh ssh install
 ssh <repo-name>-devcontainer 'whoami && pwd'
 ```
 
@@ -138,15 +153,16 @@ Use the generated host alias when configuring the agent:
 - **SSH Host:** `<repo-name>-devcontainer`
 - **SSH Port:** leave empty
 - **Identity File:** leave empty if the agent honors `~/.ssh/config`; otherwise use `.devcontainer/.ssh/id_ed25519`
-- **Remote Folder:** select `<repo-name>` from the default home folder, or enter `/workspaces/<repo-name>`
+- **Remote Folder:** enter `/workspaces/<repo-name>`
 
 `start.sh` has two modes:
 
 - `bash .devcontainer/start.sh` starts or reuses the devcontainer and opens an interactive shell. Use this for a local terminal session.
-- `bash .devcontainer/start.sh ssh-config install` installs or refreshes the host SSH alias and exits.
+- `bash .devcontainer/start.sh ssh install` installs or refreshes the host SSH alias and exits.
 - `bash .devcontainer/start.sh --ssh-proxy` refreshes the SSH alias, starts or reuses the devcontainer, and then bridges SSH over `docker exec`. Do not keep this running manually in a terminal; it is meant to be launched by OpenSSH as the `ProxyCommand` in the generated SSH config.
 - `bash .devcontainer/start.sh --refresh-gh-token` starts or reuses the devcontainer, then refreshes container `gh` auth from host `gh` when a token is available.
 - `bash .devcontainer/start.sh --refresh-gh-token-running` refreshes container `gh` auth from host `gh` only when the devcontainer is already running.
+- Add `--verbose` to any startup mode when debugging raw devcontainer, Docker, or hook output.
 
 If the devcontainer does not exist yet, the first SSH connection through `<repo-name>-devcontainer` will create it with `@devcontainers/cli up`, including `initializeCommand`, features, mounts, `postCreateCommand`, and `postStartCommand`. The first connection may take longer while the container is created.
 
@@ -159,17 +175,45 @@ export ANTHROPIC_API_KEY=sk-...
 export SNYK_TOKEN=...
 ```
 
-They are wired in `devcontainer.json` under `containerEnv` via `localEnv`.
+Boxdown writes available values to owner-only files in per-workspace runtime
+state outside the repository, then mounts that directory read-only. Bash
+sessions export the values as ordinary environment variables, but Docker
+container configuration and `docker inspect` do not contain their values.
+
+When the host `op` CLI can read Boxdown's configured service-account item,
+Boxdown provides `OP_SERVICE_ACCOUNT_TOKEN` through the same runtime mount. A
+missing host value or failed 1Password lookup is non-blocking; the variable is
+simply absent. This token is not a GitHub token and does not authenticate `gh`
+or GitHub Git remotes.
 
-If `OP_SERVICE_ACCOUNT_TOKEN` is present, it authenticates the 1Password CLI.
-It is not a GitHub token and does not authenticate `gh` or GitHub Git remotes.
+Boxdown never creates, modifies, reads, or deletes a project
+`.env.development` file. Existing containers created by an older Boxdown need
+`boxdown start --recreate` to stop receiving legacy Docker environment values.
+If an older version left a service-account token in `.env.development` or
+`boxdown.log`, remove it manually and rotate the token.
 
 ## Optional customization
 
 - **Global agent config** — Boxdown automatically mounts host `~/.agents`
   read-only at `/home/node/.agents` when that directory exists. Recreate the
   devcontainer after creating or removing it so the mount set is refreshed.
-- **Agent config on the host** — Uncomment the `mounts` entries in `devcontainer.json` to bind `~/.claude`, `~/.gemini`, or `~/.codex` into the container so coding agents see your existing settings.
+- **Codex auth on the host** — Boxdown automatically mounts host
+  `~/.codex/auth.json` read-only at `/home/node/.codex/auth.json` when that file
+  exists. Recreate the devcontainer after creating or removing it so the mount
+  set is refreshed.
+- **Other agent config on the host** — Uncomment the `mounts` entries in
+  `devcontainer.json` to bind directories such as `~/.claude` or `~/.gemini`
+  into the container so coding agents see your existing settings.
+- **Coding-agent defaults** — Container create/start installs or refreshes
+  Codex and Claude Code by default. OpenCode and Antigravity CLI remain
+  available through `boxdown opencode` and `boxdown antigravity`, but install
+  lazily only when those commands are launched.
+- **Agent CLI cleanup** — After a successful coding-agent CLI install/update,
+  Boxdown removes stale agent artifacts: old Codex standalone releases, old
+  Claude Code versions, OpenCode installer temp directories, and Antigravity
+  staging cache. Codex keeps only the active standalone release by default; set
+  `BOXDOWN_CODEX_STANDALONE_RELEASES_KEEP_PREVIOUS` to keep extra rollback
+  releases.
 - **1Password / other CLIs** — Follow the commented blocks in `devcontainer.json` and `hooks/post-create.sh` if you need them; keep the image lean by default.
 
 ---

package/assets/devcontainer/devcontainer.json

@@ -1,17 +1,35 @@
 {
     "name": "Project Devcontainer",
-    "image": "mcr.microsoft.com/devcontainers/typescript-node:24-trixie",
+    "image": "node:24-trixie-slim",
     "features": {
-        "ghcr.io/devcontainers/features/python@sha256:fbcad6955caeecc5ad3f7886baf652e25cba5225a6c4c2287c536de2e5607511": {
-            "version": "3.12",
-            "installPythonDevDependencies": true
+        "ghcr.io/devcontainers/features/common-utils@sha256:cb0c4d3c276f157eed17935747e364178d75fee17f55c4e129966f64633deb3a": {
+            "username": "node"
         },
+        "ghcr.io/devcontainers/features/git@sha256:a3e43ff91b9f5f6bd2c14bd510d43e5e698f1266dc41027ba4e04e7e45be607a": {
+            "version": "os-provided"
+        },
+        // Removed from the active feature set after measuring roughly 900MB of
+        // layer growth. Keep this reference for future Python 3.12/dev-tooling needs.
+        // "ghcr.io/devcontainers/features/python@sha256:fbcad6955caeecc5ad3f7886baf652e25cba5225a6c4c2287c536de2e5607511": {
+        //     "version": "3.12",
+        //     "installPythonDevDependencies": true
+        // },
         "ghcr.io/devcontainer-community/devcontainer-features/astral.sh-uv@sha256:36f95b90080248a05aba7b1b3cecf8018bb6d7222f6274f03f050b502abd4fe7": {
             "shellautocompletion": true
         },
         "ghcr.io/devcontainers-extra/features/ripgrep@sha256:0dfc0ac16f0d6aa754d006a138fd4cb4a62c245d308306edf8ad1b7a80b8fdf2": {},
         "ghcr.io/devcontainers/features/github-cli@sha256:d22f50b70ed75339b4eed1ba9ecde3a1791f90e88d37936517e3bace0bbad671": {}
     },
+    "overrideFeatureInstallOrder": [
+        "ghcr.io/devcontainers/features/common-utils@sha256:cb0c4d3c276f157eed17935747e364178d75fee17f55c4e129966f64633deb3a",
+        "ghcr.io/devcontainers/features/git@sha256:a3e43ff91b9f5f6bd2c14bd510d43e5e698f1266dc41027ba4e04e7e45be607a",
+        // Python is installed during post-create from Debian apt to avoid the
+        // heavy Dev Containers Python feature layer.
+        // "ghcr.io/devcontainers/features/python@sha256:fbcad6955caeecc5ad3f7886baf652e25cba5225a6c4c2287c536de2e5607511",
+        "ghcr.io/devcontainer-community/devcontainer-features/astral.sh-uv@sha256:36f95b90080248a05aba7b1b3cecf8018bb6d7222f6274f03f050b502abd4fe7",
+        "ghcr.io/devcontainers-extra/features/ripgrep@sha256:0dfc0ac16f0d6aa754d006a138fd4cb4a62c245d308306edf8ad1b7a80b8fdf2",
+        "ghcr.io/devcontainers/features/github-cli@sha256:d22f50b70ed75339b4eed1ba9ecde3a1791f90e88d37936517e3bace0bbad671"
+    ],
     // Ask the editor to forward these container ports (no Docker appPort).
     "forwardPorts": [8787, 3005, 3001, 3000],
 
@@ -51,24 +69,20 @@
     },
 
     "mounts": [
-        "source=${localEnv:HOME}/.gitconfig,target=/home/node/.gitconfig,type=bind,consistency=cached",
         // mount host user home directories for agents:
         // "source=${localEnv:HOME}/.claude,target=/home/node/.claude,type=bind,consistency=cached",
-        // "source=${localEnv:HOME}/.gemini,target=/home/node/.claude,type=bind,consistency=cached",
-        // "source=${localEnv:HOME}/.codex,target=/home/node/.codex,type=bind,consistency=cached"
+        // "source=${localEnv:HOME}/.gemini,target=/home/node/.claude,type=bind,consistency=cached"
+        // Codex auth.json is mounted automatically by Boxdown's generated config when present.
     ],
 
-    // Initialize optional host-side secrets before container create/start.
+    // Initialize host runtime state before container create/start.
     "initializeCommand": "bash .devcontainer/hooks/initialize.sh",
     // After up, discover the published host binding, e.g.:
     // docker port <container-name-or-id> 3000/tcp
     "runArgs": [
         // publish container port 3000 with dynamic host port (CLI / start.sh)
         "-p",
-        "127.0.0.1::3000",
-        // pass the development environment file to the container
-        "--env-file",
-        "${localWorkspaceFolder}/.env.development"
+        "127.0.0.1::3000"
     ],
     // --
     "postCreateCommand": "bash .devcontainer/hooks/post-create.sh",
@@ -76,8 +90,6 @@
     "remoteUser": "node",
     "workspaceFolder": "/workspaces/${localWorkspaceFolderBasename}",
     "containerEnv": {
-        "NODE_ENV": "development",
-        "ANTHROPIC_API_KEY": "${localEnv:ANTHROPIC_API_KEY}",
-        "SNYK_TOKEN": "${localEnv:SNYK_TOKEN}"
+        "NODE_ENV": "development"
     }
 }

package/assets/devcontainer/hooks/initialize.sh

@@ -1,55 +1,109 @@
 #!/usr/bin/env bash
 # initialize: runs on host before container create/start (initializeCommand).
-# Prepares .env.development and, when possible, injects OP_SERVICE_ACCOUNT_TOKEN from 1Password.
+# Refreshes private runtime secret files and snapshots host Git config.
 
 set -euo pipefail
 
-HOOKS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-WORKSPACE_DIR="${BOXDOWN_WORKSPACE_FOLDER:-$(cd "${HOOKS_DIR}/../.." && pwd)}"
-ENV_FILE="${WORKSPACE_DIR}/.env.development"
+HOST_GITCONFIG_PATH="${BOXDOWN_HOST_GITCONFIG_PATH:-${HOME:-}/.gitconfig}"
+HOST_GITCONFIG_SNAPSHOT_PATH="${BOXDOWN_HOST_GITCONFIG_SNAPSHOT_PATH:-}"
+SECRET_ENV_DIR="${BOXDOWN_SECRET_ENV_DIR:-}"
 OP_TOKEN_REFERENCE="op://Private/1Password op CLI Service Account for DevContainers/password"
 
 main() {
-  ensure_env_file_exists
-  maybe_inject_1password_service_account_token
+  progress "Snapshotting host Git config"
+  snapshot_host_gitconfig
+  progress "Refreshing runtime secret environment"
+  refresh_runtime_secret_environment
 }
 
-ensure_env_file_exists() {
-  if [[ ! -f "${ENV_FILE}" ]]; then
-    : > "${ENV_FILE}"
+progress() {
+  if [[ "${BOXDOWN_PROGRESS:-0}" == "1" ]]; then
+    printf 'BOXDOWN_PROGRESS: %s\n' "$*"
   fi
 }
 
-maybe_inject_1password_service_account_token() {
+snapshot_host_gitconfig() {
+  local snapshot_dir
+
+  if [[ -z "${HOST_GITCONFIG_SNAPSHOT_PATH}" ]]; then
+    echo "initialize.sh: host gitconfig snapshot path is not configured; skipping gitconfig snapshot."
+    return 0
+  fi
+
+  snapshot_dir="$(dirname "${HOST_GITCONFIG_SNAPSHOT_PATH}")"
+  mkdir -p "${snapshot_dir}"
+
+  if [[ -f "${HOST_GITCONFIG_PATH}" ]]; then
+    cp "${HOST_GITCONFIG_PATH}" "${HOST_GITCONFIG_SNAPSHOT_PATH}"
+    chmod 0644 "${HOST_GITCONFIG_SNAPSHOT_PATH}"
+    return 0
+  fi
+
+  rm -f "${HOST_GITCONFIG_SNAPSHOT_PATH}"
+}
+
+prepare_secret_env_dir() {
+  if [[ -z "${SECRET_ENV_DIR}" ]]; then
+    echo "initialize.sh: runtime secret directory is not configured; skipping optional secrets." >&2
+    return 1
+  fi
+
+  umask 077
+  mkdir -p "${SECRET_ENV_DIR}"
+  chmod 0700 "${SECRET_ENV_DIR}"
+}
+
+write_secret_file() {
+  local name="$1"
+  local value="$2"
+  local temporary_path
+
+  temporary_path="$(mktemp "${SECRET_ENV_DIR}/.${name}.XXXXXX")"
+  printf '%s' "${value}" > "${temporary_path}"
+  chmod 0600 "${temporary_path}"
+  mv -f "${temporary_path}" "${SECRET_ENV_DIR}/${name}"
+}
+
+refresh_host_environment_secret() {
+  local name="$1"
+  local value="${!name:-}"
+
+  if [[ -n "${value}" ]]; then
+    write_secret_file "${name}" "${value}"
+  else
+    rm -f "${SECRET_ENV_DIR}/${name}"
+  fi
+}
+
+refresh_1password_service_account_token() {
   local token
 
   if ! command -v op >/dev/null 2>&1; then
-    echo "initialize.sh: op CLI not found; leaving ${ENV_FILE} unchanged."
+    rm -f "${SECRET_ENV_DIR}/OP_SERVICE_ACCOUNT_TOKEN"
     return 0
   fi
 
   if ! token="$(op read "${OP_TOKEN_REFERENCE}" 2>/dev/null)"; then
-    echo "initialize.sh: could not read OP service token from 1Password; leaving ${ENV_FILE} unchanged."
+    rm -f "${SECRET_ENV_DIR}/OP_SERVICE_ACCOUNT_TOKEN"
     return 0
   fi
 
   if [[ -z "${token}" ]]; then
-    echo "initialize.sh: OP service token is empty; leaving ${ENV_FILE} unchanged."
+    rm -f "${SECRET_ENV_DIR}/OP_SERVICE_ACCOUNT_TOKEN"
     return 0
   fi
 
-  upsert_env_var "OP_SERVICE_ACCOUNT_TOKEN" "${token}"
+  write_secret_file "OP_SERVICE_ACCOUNT_TOKEN" "${token}"
 }
 
-upsert_env_var() {
-  local key="$1"
-  local value="$2"
-  local tmp_file
+refresh_runtime_secret_environment() {
+  if ! prepare_secret_env_dir; then
+    return 0
+  fi
 
-  tmp_file="$(mktemp)"
-  awk -F= -v k="${key}" '$1 != k' "${ENV_FILE}" > "${tmp_file}"
-  printf '%s=%s\n' "${key}" "${value}" >> "${tmp_file}"
-  mv "${tmp_file}" "${ENV_FILE}"
+  refresh_host_environment_secret "ANTHROPIC_API_KEY"
+  refresh_host_environment_secret "SNYK_TOKEN"
+  refresh_1password_service_account_token
 }
 
 main "$@"