boxdown 1.2.0 → 1.3.0

package/docs/superpowers/specs/2026-07-11-default-commit-signing-design.md

@@ -115,6 +115,12 @@ Boxdown resolves a signing identity in this order:
 4. With zero or multiple unresolved identities, produce a disabled signing
    plan and a warning reason. Do not guess.
 
+`user.signingKey` accepts an inline SSH public key, Git's `key::` public-key
+form, an absolute path, a `~/` path, or a path relative to the workspace.
+Boxdown reads public-key files only. An explicitly configured key is
+authoritative: unreadable, malformed, or unloaded configured keys disable
+signing and never fall through to GitHub or single-identity selection.
+
 Failure to execute `ssh-add`, query GitHub, parse a public key, or resolve a
 single identity is non-fatal.
 
@@ -321,7 +327,10 @@ testable. At minimum, reasons distinguish:
 - host agent unavailable;
 - no loaded identities;
 - ambiguous loaded identities;
+- configured host SSH signing key unreadable or malformed;
 - configured host SSH signing key not loaded;
+- host agent socket unavailable;
+- no local Docker image available for the agent mount probe;
 - Docker agent bridge unavailable;
 - public-key snapshot failure;
 - selected identity missing in the container;
@@ -333,6 +342,17 @@ Human-readable warnings state that commits will remain unsigned but are not
 blocked. A missing GitHub registration warning instead states that commits are
 signed locally but will not appear Verified on GitHub.
 
+User-facing lifecycle commands print the concise warning. The workspace
+command log additionally records the stable reason code and sanitized detail,
+without public-key material or secrets. Internal SSH proxy startup remains
+log-only. Generated configuration passes the stable host reason into container
+bootstrap so later lifecycle warnings preserve the original diagnosis.
+
+Docker Desktop may expose the mounted host-agent socket only to root. Boxdown
+therefore relays it through a root-owned Unix-socket proxy to a node-owned
+socket. Explicit user Git-signing preferences remain authoritative; Boxdown
+uses SSH signing only as the default when no preference exists.
+
 ## Testing Strategy
 
 ### Unit tests

package/docs/superpowers/specs/2026-07-17-node-ssh-agent-proxy-design.md

@@ -0,0 +1,63 @@
+# Node SSH-Agent Proxy for Commit Signing
+
+## Goal
+
+Make Boxdown's default SSH commit signing usable by the container's `node`
+user when Docker Desktop mounts the host agent socket as `root:root` with mode
+`0660`. Signing must remain best-effort and never expose a private key.
+
+## Root Cause
+
+The host preflight and the raw socket mount both succeed, but lifecycle hooks
+run as `node`. In the reproduced environment, `ssh-add -L` succeeds as root
+and fails as `node` with `Permission denied`. The signing bootstrap therefore
+sets `commit.gpgsign=false` and reports `container-agent-unavailable`.
+
+## Architecture
+
+Boxdown continues to bind-mount the host-facing agent socket at
+`/run/boxdown/ssh-agent.sock`. A small Node Unix-socket proxy runs as root and
+forwards each connection from that raw socket to
+`/run/boxdown/ssh-agent-node.sock`. The proxy creates the latter socket with
+ownership and permissions suitable for `node`. Generated configuration sets
+`SSH_AUTH_SOCK` to the node-facing socket and exposes the raw path only through
+`BOXDOWN_GIT_SIGNING_SOURCE_SOCKET` for the proxy.
+
+The post-create hook starts the proxy with passwordless `sudo`, waits briefly
+for its socket, verifies `ssh-add -L` as `node`, then invokes the existing
+signing bootstrap. A proxy failure is non-blocking and has its own stable
+reason code.
+
+## Git Configuration Precedence
+
+**Decision:** Boxdown does not make its SSH configuration authoritative over
+explicit user Git signing preferences. This is intentional because the
+container begins from a writable copy of the user's Git configuration.
+
+- With no explicit global or repository-local signing preference, Boxdown
+  configures SSH signing as the default.
+- With an explicit SSH preference, Boxdown preserves the selected identity;
+  it only translates an inaccessible host public-key path to the mounted
+  public-key snapshot in the container.
+- With `commit.gpgsign=false`, a non-SSH `gpg.format`, or an explicit
+  `gpg.program`, Boxdown preserves that preference and does not replace it.
+
+Repository-local settings retain Git's normal precedence. In particular, a
+local `commit.gpgsign=false` keeps commits unsigned even when agent forwarding
+is healthy. A future product decision may deliberately reverse this policy and
+make Boxdown authoritative; that would be a behavior change, not a bug fix.
+
+## Failure Handling
+
+The proxy never reads, copies, or logs private-key material. It reports
+`container-agent-proxy-unavailable` when `sudo`, Node, proxy readiness, or the
+node-user agent probe fails. The signing bootstrap remains non-blocking and
+preserves explicit user configuration rather than setting a contradictory
+global value.
+
+## Validation
+
+Tests cover forwarding a real Unix-socket request through the proxy, a proxy
+startup failure, generated socket environment values, successful default SSH
+signing, and preservation of global and local user preferences. Documentation
+will require `--recreate` after upgrade.

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/superpowers/specs/2026-07-18-architecture-aware-1password-installer-design.md

@@ -0,0 +1,63 @@
+# Architecture-Aware 1Password Installer Design
+
+## Goal
+
+Install the pinned 1Password CLI archive that matches the devcontainer's Linux
+architecture, and add fast CI coverage for both supported architecture paths.
+
+## Current Problem
+
+`assets/devcontainer/hooks/post-create.sh` always downloads the 1Password
+`op_linux_arm64` archive. On amd64 devcontainers this installs an incompatible
+binary. The existing CI job runs on amd64, but its tests never execute the
+installer's architecture selection, so the mismatch is not detected.
+
+## Design
+
+Keep the existing pinned 1Password CLI version and prebuilt zip installation
+flow. Inside `install_1password_cli`, map the value from `uname -m` to the
+1Password archive architecture:
+
+- `x86_64` and `amd64` select `amd64`.
+- `aarch64` and `arm64` select `arm64`.
+- Any other value prints a warning and returns successfully without downloading
+  or installing a binary.
+
+The selected architecture becomes part of the existing archive URL. No source
+build, Buildx configuration, QEMU emulation, version change, or installer
+refactor is required.
+
+## Test Coverage
+
+Add behavioral smoke tests that source the real post-create hook and invoke
+`install_1password_cli` with controlled command shims. The shims replace
+network and privileged filesystem operations while recording the requested
+download URL.
+
+The tests cover:
+
+- `x86_64` selecting the `op_linux_amd64` archive.
+- `aarch64` selecting the `op_linux_arm64` archive.
+- An unsupported architecture returning successfully, warning, and performing
+  no download.
+
+These tests run in the existing `pnpm run test` CI step on `ubuntu-latest`.
+This gives the amd64 CI runner explicit coverage of both supported selection
+branches without downloading 1Password or building a multi-architecture
+container.
+
+## Scope
+
+- Modify `assets/devcontainer/hooks/post-create.sh` only for 1Password archive
+  selection and unsupported-architecture handling.
+- Add focused tests to `__tests__/app.test.ts` using the repository's existing
+  shell-script test conventions.
+- Do not alter the Snyk installer, devcontainer image, CI runner matrix, or
+  other lifecycle behavior.
+
+## Verification
+
+Use test-driven development: add the focused architecture tests and confirm
+they fail against the hard-coded arm64 URL, implement the minimum shell change,
+then rerun the focused tests. Finish with the repository's full test, lint,
+build, shell syntax, and diff checks.

package/docs/superpowers/specs/2026-07-18-devcontainer-node-image-digest-design.md

@@ -0,0 +1,108 @@
+# Devcontainer Node Image Digest Pinning
+
+## Goal
+
+Make Boxdown's packaged devcontainer base image reproducible across rebuilds
+and host architectures while preserving the existing Node 24, Debian trixie,
+and slim-image track. Keep the immutable image reference current through
+reviewable automated pull requests.
+
+## Scope
+
+This change applies to the reusable devcontainer template at
+`assets/devcontainer/devcontainer.json`. It does not change Boxdown's runtime
+generation model, the Dev Container Feature pins, npm dependency automation,
+or GitHub Actions dependency automation.
+
+## Image Reference
+
+The template will replace the mutable reference:
+
+```text
+node:24-trixie-slim
+```
+
+with the same tag plus `@sha256:` and the verified 64-hex-character
+multi-platform index digest.
+
+The implementation will resolve the current digest from the upstream Node
+image registry and verify that it identifies the multi-platform image index,
+not an architecture-specific child manifest. Keeping the tag documents the
+intended Node 24 and Debian trixie slim update track. The digest makes the
+actual selected index immutable, so AMD64 and ARM64 hosts resolve their
+platform image from the same pinned release set.
+
+The tag deliberately remains at Node major-version precision. Node patch
+releases and upstream rebuilds stay explicit through digest-update pull
+requests without moving Boxdown to another Node major or Debian variant.
+
+## Update Automation
+
+A root `renovate.json` will configure Renovate's native devcontainer manager.
+The configuration will:
+
+- enable only the devcontainer manager, avoiding overlap with the existing
+  Dependabot npm and GitHub Actions configuration;
+- extend devcontainer file matching to
+  `assets/devcontainer/devcontainer.json`, which is outside Renovate's default
+  root `.devcontainer` locations;
+- disable Dev Container Feature updates so the existing digest-pinned Feature
+  set remains outside this change;
+- match only the `node` image dependency in the packaged template;
+- preserve the `24-trixie-slim` tag and update its digest; and
+- allow digest-refresh pull requests on a monthly schedule.
+
+The Renovate GitHub app performs the registry lookup and opens the pull
+request. Boxdown does not add a repository-owned scheduled workflow or a
+repository token. Enabling the app for the repository is an operational
+prerequisite outside the committed code.
+
+## Documentation
+
+The packaged devcontainer README will describe the tag-plus-index-digest
+reference, its cross-platform reproducibility property, and Renovate's role in
+refreshing it through auditable pull requests. Existing documentation about
+the Node 24 trixie slim base and digest-pinned Features remains accurate.
+
+## Test Strategy
+
+A focused repository test will read the packaged devcontainer source and
+assert that:
+
+- its base image is exactly the intended `node:24-trixie-slim` tag followed by
+  a 64-hex-character SHA-256 digest;
+- the Renovate configuration enables only the devcontainer manager;
+- the additional manager file pattern covers the packaged template;
+- Feature dependencies are disabled; and
+- the Node image rule enables digest pinning on the monthly schedule.
+
+The test will be added before the production configuration changes and must be
+observed failing for the missing digest and Renovate configuration. After the
+change, verification will run the focused test, full test suite, lint, build,
+JSON and JSON-with-comments parsing, registry inspection of the pinned index,
+and `git diff --check`.
+
+## Alternatives Considered
+
+### Dependabot through a Dockerfile
+
+Moving the base reference into a Dockerfile would let Dependabot's Docker
+ecosystem update it, but it would change the devcontainer architecture solely
+to accommodate the updater. GitHub's `devcontainers` ecosystem updates
+Features rather than the `image` field, so it cannot directly maintain the
+current template.
+
+### Repository-owned scheduled workflow
+
+A custom workflow could resolve the tag, edit the digest, and open pull
+requests. It would duplicate registry, scheduling, authentication, and pull
+request behavior already provided by Renovate and would add workflow and token
+maintenance.
+
+## Decision Record
+
+Use Renovate's native devcontainer support and retain the human-readable
+`node:24-trixie-slim` tag. Pin the verified multi-platform index digest and
+scope automation to only that image in the packaged template. This yields
+immutable rebuild inputs without broadening Boxdown's dependency automation
+or changing its generated-devcontainer architecture.