boxdown 1.2.0 → 1.3.0

package/README.md

@@ -169,6 +169,16 @@ 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.
 
+`boxdown start` is standalone: it can create or reuse the devcontainer even if
+`boxdown setup` was skipped or its preflight failed. Setup-only SSH aliases and
+Codex/Claude application integrations are still installed only by `setup`.
+
+Before a command creates or starts a container, Boxdown waits up to 60 seconds
+for the Docker daemon and the selected Docker Buildx builder. If Buildx is not
+installed, the bundled Dev Containers CLI uses its supported classic-build
+fallback and Boxdown continues with a warning. Boxdown does not retry an actual
+Dev Containers build failure.
+
 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:

package/assets/devcontainer/README.md

@@ -17,7 +17,7 @@ Run this project in a **consistent Node.js 24 + TypeScript** environment without
 | `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/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. |
@@ -28,7 +28,18 @@ Run this project in a **consistent Node.js 24 + TypeScript** environment without
 
 ## 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.
+Boxdown uses `node:24-trixie-slim` as the base-image update track to keep the
+shared image smaller than the full Dev Containers TypeScript/Node image. The
+template appends the upstream multi-platform OCI index digest, making rebuilds
+immutable while allowing AMD64 and ARM64 hosts to select the matching platform
+manifest from the same pinned release set. Renovate checks the packaged
+template monthly and opens a pull request when that tag's index digest changes,
+so base-image updates remain explicit and auditable.
+
+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.
 
@@ -175,10 +186,22 @@ export ANTHROPIC_API_KEY=sk-...
 export SNYK_TOKEN=...
 ```
 
-They are wired in `devcontainer.json` under `containerEnv` via `localEnv`.
-
-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 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.
+
+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
 

package/assets/devcontainer/devcontainer.json

@@ -1,6 +1,6 @@
 {
     "name": "Project Devcontainer",
-    "image": "node:24-trixie-slim",
+    "image": "node:24-trixie-slim@sha256:ae91dcc111a68c9d2d81ff2a17bda61be126426176fde6fe7d08ab13b7f50573",
     "features": {
         "ghcr.io/devcontainers/features/common-utils@sha256:cb0c4d3c276f157eed17935747e364178d75fee17f55c4e129966f64633deb3a": {
             "username": "node"
@@ -75,17 +75,14 @@
         // 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",
@@ -93,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,23 +1,19 @@
 #!/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() {
-  progress "Preparing workspace environment file"
-  ensure_env_file_exists
   progress "Snapshotting host Git config"
   snapshot_host_gitconfig
-  progress "Checking 1Password service account token"
-  maybe_inject_1password_service_account_token
+  progress "Refreshing runtime secret environment"
+  refresh_runtime_secret_environment
 }
 
 progress() {
@@ -26,12 +22,6 @@ progress() {
   fi
 }
 
-ensure_env_file_exists() {
-  if [[ ! -f "${ENV_FILE}" ]]; then
-    : > "${ENV_FILE}"
-  fi
-}
-
 snapshot_host_gitconfig() {
   local snapshot_dir
 
@@ -52,36 +42,68 @@ snapshot_host_gitconfig() {
   rm -f "${HOST_GITCONFIG_SNAPSHOT_PATH}"
 }
 
-maybe_inject_1password_service_account_token() {
+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 "$@"

package/assets/devcontainer/hooks/post-create.sh

@@ -8,6 +8,7 @@ main() {
   run_step "Configuring global Git" configure_global_git
   run_step "Configuring Git commit signing" configure_git_signing
   run_step "Configuring workspace Git" configure_local_git
+  run_step "Configuring runtime secret environment" configure_runtime_secret_environment
   run_step "Installing OpenSSH server" install_openssh_server
   run_step "Installing Python runtime" install_python_runtime
   run_step "Installing Agent Package Manager" install_apm
@@ -49,6 +50,16 @@ configure_local_git() {
   fi
 }
 
+configure_runtime_secret_environment() {
+  local bashrc="${HOME}/.bashrc"
+  local source_line='source /opt/boxdown/devcontainer/utils/secret-env-bootstrap.sh'
+
+  touch "${bashrc}"
+  if ! grep -Fqx "${source_line}" "${bashrc}"; then
+    printf '%s\n' "${source_line}" >> "${bashrc}"
+  fi
+}
+
 install_apm() {
   # Agent Package Manager: https://github.com/microsoft/apm
   local installer
@@ -100,7 +111,18 @@ install_snyk_cli() {
 
 install_1password_cli() {
   local op_version="2.32.1"
-  curl -fsSL "https://cache.agilebits.com/dist/1P/op2/pkg/v${op_version}/op_linux_arm64_v${op_version}.zip" -o /tmp/op.zip
+  local op_arch
+
+  case "$(uname -m)" in
+    aarch64 | arm64) op_arch="arm64" ;;
+    x86_64 | amd64) op_arch="amd64" ;;
+    *)
+      echo "post-create: skipping 1Password CLI (unsupported arch: $(uname -m))" >&2
+      return 0
+      ;;
+  esac
+
+  curl -fsSL "https://cache.agilebits.com/dist/1P/op2/pkg/v${op_version}/op_linux_${op_arch}_v${op_version}.zip" -o /tmp/op.zip
   python3 -c "import zipfile; zipfile.ZipFile('/tmp/op.zip').extract('op', '/tmp')"
   sudo mv /tmp/op /usr/local/bin/op && chmod +x /usr/local/bin/op && rm /tmp/op.zip
 }

package/assets/devcontainer/hooks/post-start.sh

@@ -13,7 +13,6 @@ DEVCONTAINER_DIR="$(cd "${HOOKS_DIR}/.." && pwd)"
 main() {
   run_step "Preparing SSH runtime" configure_sshd_runtime
   run_step "Refreshing coding-agent CLIs" refresh_coding_agent_clis
-  run_step "Cleaning ephemeral environment file" remove_ephemeral_env_file_if_present
 }
 
 progress() {
@@ -39,13 +38,4 @@ refresh_coding_agent_clis() {
     echo "post-start: warning: one or more coding-agent CLI refreshes failed." >&2
 }
 
-# When initializeCommand + runArgs inject secrets via .env.development, remove the file
-# after start so it is not left on disk and tooling that assumes absence does not break.
-remove_ephemeral_env_file_if_present() {
-  local env_file=".env.development"
-  if [[ -f "$env_file" ]]; then
-    rm -f "$env_file"
-  fi
-}
-
 main "$@"

package/assets/devcontainer/utils/git-signing-bootstrap.sh

@@ -6,22 +6,75 @@ set -euo pipefail
 TARGET_PATH="${BOXDOWN_GITCONFIG_TARGET_PATH:-/home/node/.gitconfig}"
 KEY_PATH="${BOXDOWN_GIT_SIGNING_KEY_PATH:-/opt/boxdown/state/git-signing/signing-key.pub}"
 ENABLED="${BOXDOWN_GIT_SIGNING_ENABLED:-0}"
+HOST_REASON="${BOXDOWN_GIT_SIGNING_REASON:-host-preflight-unavailable}"
 
 git_global() {
   GIT_CONFIG_GLOBAL="${TARGET_PATH}" git config --global "$@"
 }
 
+git_local_value() {
+  git config --local --get "$1" 2>/dev/null || true
+}
+
+git_global_value() {
+  git_global --get "$1" 2>/dev/null || true
+}
+
+preserve_user_signing_preference() {
+  local local_commit global_commit local_format global_format local_program global_program
+  local_commit="$(git_local_value commit.gpgsign)"
+  global_commit="$(git_global_value commit.gpgsign)"
+  local_format="$(git_local_value gpg.format)"
+  global_format="$(git_global_value gpg.format)"
+  local_program="$(git_local_value gpg.program)"
+  global_program="$(git_global_value gpg.program)"
+
+  [[ "${local_commit}" == "false" || "${global_commit}" == "false" ]] && return 0
+  [[ -n "${local_program}" || -n "${global_program}" ]] && return 0
+  [[ -n "${local_format}" && "${local_format}" != "ssh" ]] && return 0
+  [[ -n "${global_format}" && "${global_format}" != "ssh" ]] && return 0
+  return 1
+}
+
 disable_signing() {
+  local reason="${1:-unknown}"
+  if preserve_user_signing_preference; then
+    printf 'boxdown: commit signing configuration preserved (reason: %s).\n' "${reason}" >&2
+    return 0
+  fi
   git_global --unset-all gpg.format >/dev/null 2>&1 || true
   git_global --unset-all user.signingkey >/dev/null 2>&1 || true
   git_global --unset-all gpg.program >/dev/null 2>&1 || true
   git_global --replace-all commit.gpgsign false
-  printf '%s\n' 'boxdown: commit signing unavailable; commits will remain unsigned.' >&2
+  printf 'boxdown: commit signing unavailable (reason: %s); commits will remain unsigned.\n' "${reason}" >&2
 }
 
 enable_signing() {
-  if [[ ! -r "${KEY_PATH}" ]] || ! ssh-add -L | grep -qF "$(awk 'NR == 1 { print $1 " " $2 }' "${KEY_PATH}")"; then
-    disable_signing
+  if preserve_user_signing_preference; then
+    printf '%s\n' 'boxdown: preserving explicit user Git signing configuration.' >&2
+    return 0
+  fi
+
+  if [[ ! -r "${KEY_PATH}" ]]; then
+    disable_signing 'container-key-unavailable'
+    return 0
+  fi
+
+  if ! bash "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/ssh-agent-proxy-bootstrap.sh"; then
+    disable_signing 'container-agent-proxy-unavailable'
+    return 0
+  fi
+
+  local agent_identities
+  if ! agent_identities="$(ssh-add -L 2>/dev/null)"; then
+    disable_signing 'container-agent-unavailable'
+    return 0
+  fi
+
+  local selected_key
+  selected_key="$(awk 'NR == 1 { print $1 " " $2 }' "${KEY_PATH}")"
+  if ! grep -qF -- "${selected_key}" <<<"${agent_identities}"; then
+    disable_signing 'container-key-not-loaded'
     return 0
   fi
 
@@ -43,7 +96,7 @@ enable_signing() {
     git commit --allow-empty -m 'boxdown signing probe' >/dev/null
   ); then
     rm -rf "${probe_dir}"
-    disable_signing
+    disable_signing 'container-signing-probe-failed'
     return 0
   fi
   rm -rf "${probe_dir}"
@@ -52,5 +105,5 @@ enable_signing() {
 if [[ "${ENABLED}" == "1" ]]; then
   enable_signing
 else
-  disable_signing
+  disable_signing "${HOST_REASON}"
 fi

package/assets/devcontainer/utils/secret-env-bootstrap.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# Shell bootstrap for Boxdown runtime-mounted secret environment files.
+
+SECRET_ENV_DIR="${BOXDOWN_SECRET_ENV_DIR:-/run/boxdown/secrets}"
+
+export_if_present() {
+  local name="$1"
+  local path="${SECRET_ENV_DIR}/${name}"
+  local value
+
+  [[ -r "${path}" ]] || return 0
+  IFS= read -r value < "${path}" || true
+
+  if [[ -n "${value}" ]]; then
+    export "${name}=${value}"
+  fi
+}
+
+export_if_present ANTHROPIC_API_KEY
+export_if_present SNYK_TOKEN
+export_if_present OP_SERVICE_ACCOUNT_TOKEN
+unset value

package/assets/devcontainer/utils/ssh-agent-proxy-bootstrap.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# Expose a root-only forwarded SSH-agent socket to the non-root container user.
+
+set -euo pipefail
+
+SOURCE_SOCKET="${BOXDOWN_GIT_SIGNING_SOURCE_SOCKET:-/run/boxdown/ssh-agent.sock}"
+TARGET_SOCKET="${SSH_AUTH_SOCK:-/run/boxdown/ssh-agent-node.sock}"
+PROXY_SCRIPT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/ssh-agent-proxy.mjs"
+
+if ssh-add -L >/dev/null 2>&1; then
+  exit 0
+fi
+
+if ! command -v sudo >/dev/null 2>&1 || ! command -v node >/dev/null 2>&1; then
+  exit 1
+fi
+
+sudo -n node "${PROXY_SCRIPT}" --source "${SOURCE_SOCKET}" --target "${TARGET_SOCKET}" --uid "$(id -u)" --gid "$(id -g)" >/dev/null 2>&1 &
+
+for _ in $(seq 1 20); do
+  if [[ -S "${TARGET_SOCKET}" ]] && ssh-add -L >/dev/null 2>&1; then
+    exit 0
+  fi
+  sleep 0.1
+done
+
+exit 1

package/assets/devcontainer/utils/ssh-agent-proxy.mjs

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+
+import { chmodSync, chownSync, existsSync, unlinkSync } from 'node:fs'
+import { createConnection, createServer } from 'node:net'
+
+function option (name) {
+  const index = process.argv.indexOf(name)
+  return index === -1 ? undefined : process.argv[index + 1]
+}
+
+const source = option('--source')
+const target = option('--target')
+const uid = Number(option('--uid'))
+const gid = Number(option('--gid'))
+
+if (source === undefined || target === undefined || !Number.isInteger(uid) || !Number.isInteger(gid)) {
+  process.stderr.write('ssh-agent-proxy: expected --source, --target, --uid, and --gid.\n')
+  process.exit(2)
+}
+
+if (existsSync(target)) unlinkSync(target)
+
+const server = createServer((client) => {
+  const upstream = createConnection(source)
+  client.pipe(upstream)
+  upstream.pipe(client)
+  client.on('error', () => upstream.destroy())
+  upstream.on('error', () => client.destroy())
+})
+
+server.on('error', (error) => {
+  process.stderr.write(`ssh-agent-proxy: ${error.message}\n`)
+  process.exit(1)
+})
+
+server.listen(target, () => {
+  chmodSync(target, 0o600)
+  chownSync(target, uid, gid)
+})

package/dist/bin/cli.cjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-const require_main = require('../main-Df4E8ARj.cjs');
+const require_main = require('../main-CT2n9qcb.cjs');
 
 //#region src/bin/cli.ts
 require_main.runCli().then((exitCode) => {

package/dist/bin/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { o as runCli } from "../main-XMBsKjIK.mjs";
+import { c as runCli } from "../main-O__JaiXe.mjs";
 
 //#region src/bin/cli.ts
 runCli().then((exitCode) => {