boxdown 1.0.0 → 1.2.0

package/docs/features/start-and-shell.md

@@ -6,7 +6,6 @@
 boxdown start
 boxdown codex
 boxdown claude
-boxdown cc
 boxdown opencode
 boxdown antigravity
 ```
@@ -16,18 +15,30 @@ boxdown antigravity
 ```sh
 --workspace <path>
 --recreate
+--verbose
 ```
 
+Use `boxdown setup` when you want to prepare the devcontainer and SSH/app
+integration without opening an interactive shell.
+
 `boxdown shell` remains supported as an alias for `boxdown start`, but `start`
 is the canonical command used in help and documentation.
+`boxdown cc` remains supported as an alias for `boxdown claude`, but `claude`
+is the canonical command used in help and documentation.
 
 The coding-agent aliases start or reuse the same workspace devcontainer and
 launch the selected CLI directly:
 
 - `boxdown codex` launches `codex`.
-- `boxdown claude` and `boxdown cc` launch `claude`.
-- `boxdown opencode` launches `opencode`.
-- `boxdown antigravity` launches `agy`.
+- `boxdown claude` launches `claude`.
+- `boxdown opencode` installs/updates OpenCode when needed, then launches
+  `opencode`.
+- `boxdown antigravity` installs/updates Antigravity when needed, then launches
+  `agy`.
+
+Container bring-up eagerly installs only Codex and Claude Code. OpenCode and
+Antigravity are lazy installs so projects that do not use them avoid the extra
+disk usage.
 
 Pass agent-specific arguments after `--` so Boxdown options stay unambiguous:
 
@@ -42,7 +53,7 @@ boxdown claude -- --continue
 3. Generate a Boxdown-owned devcontainer config.
 4. Install or reuse the pinned Dev Containers CLI.
 5. Run `devcontainer up --workspace-folder <repo> --override-config <config>`.
-6. Run container lifecycle hooks, including a best-effort coding-agent CLI refresh.
+6. Run container lifecycle hooks, including a best-effort Codex/Claude CLI refresh.
 7. Print a dynamic port hint when the configured published port is mapped.
 8. Run `devcontainer exec ... bash` to open an interactive shell.
 
@@ -50,6 +61,11 @@ Coding-agent aliases use the same startup flow but skip the port hint, run a
 best-effort refresh for the selected agent, and exec the agent binary instead of
 opening `bash`.
 
+Startup progress is concise by default. Raw Docker, Dev Containers CLI,
+lifecycle hook, and coding-agent install/update logs are captured; on failure,
+Boxdown prints the failed step and a short output tail. Pass `--verbose` to
+stream the full startup output before the interactive shell or agent takes over.
+
 ## Terminal Width
 
 Some terminal UIs behave poorly when a host terminal reports an extremely wide
@@ -57,6 +73,12 @@ PTY, especially from embedded terminals. Before opening the shell, Boxdown
 clamps interactive terminal width to 120 columns when the reported width is
 larger.
 
+Before starting the interactive shell or a coding-agent command, Boxdown also
+checks whether the container recognizes the forwarded `TERM` value. If the
+container does not have terminfo for a host-specific terminal such as Ghostty,
+Boxdown falls back to `xterm-256color` while preserving truecolor support with
+`COLORTERM=truecolor`.
+
 Override the default width when you want a wider layout:
 
 ```sh
@@ -81,3 +103,16 @@ Docker `runArgs`.
 The v1 asset config publishes container port `3000` with a dynamic host port.
 After `up`, Boxdown asks Docker for the mapped host binding and prints the
 result as an HTTP URL when available.
+
+For dev servers that choose another port after the container is already running,
+use the SSH tunnel command instead. Interactive terminals can omit `--port` to
+be prompted for the mapping:
+
+```sh
+boxdown tunnel
+boxdown tunnel --port 3030
+boxdown tunnel --workspace /path/to/project --port 3030
+```
+
+This is the preferred path for host browsers and the Codex in-app browser when a
+server is listening on container-local `localhost`.

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

@@ -0,0 +1,110 @@
+# Default Commit Signing Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make new Boxdown environments sign commits through the host SSH agent by default, while retaining an unsigned, warning-only fallback.
+
+**Architecture:** A host-side resolver selects one unambiguous public SSH key and snapshots only that key into workspace state. The generated devcontainer config mounts the host agent and the public-key snapshot. A container bootstrap validates a disposable SSH-signed commit and configures global Git for SSH signing or disables it without touching repository-local Git config.
+
+**Tech Stack:** Node.js 24, TypeScript, Bash, Git, OpenSSH, Docker/Dev Containers CLI, Node test runner.
+
+## Global Constraints
+
+- Never copy private signing-key material into Boxdown state or the container.
+- Multiple ambiguous agent identities disable signing and warn; never select one arbitrarily.
+- Signing diagnostics are `warn`, never a setup-preflight failure.
+- Never write `commit.gpgsign` in the repository-local `.git/config`.
+- Docker integration is optional and must not pull images or push commits.
+
+---
+
+### Task 1: Resolve and persist a signing plan
+
+**Files:**
+
+- Create: `src/git-signing.ts`
+- Modify: `src/constants.ts`, `src/paths.ts`, `src/config.ts`
+- Test: `__tests__/app.test.ts`
+
+**Interfaces:**
+
+```ts
+export type GitSigningReason = 'agent-unavailable' | 'no-identities' | 'ambiguous-identities' | 'configured-key-not-loaded' | 'agent-mount-unavailable'
+export interface GitSigningPlan { enabled: boolean, reason?: GitSigningReason, publicKey?: string, agentSocketSource?: string }
+export function parseSshPublicKey(value: string): string | undefined
+export function selectGitSigningKey(identities: string[], configuredKey?: string, githubKeys?: string[]): { key?: string, reason?: GitSigningReason }
+export function writeGitSigningPublicKey(context: WorkspaceContext, key: string): void
+```
+
+- [ ] Write focused failing tests for parsing keys without comments, configured-key selection, a unique GitHub-key match, single-key fallback, ambiguous fallback, and config mount generation.
+- [ ] Run `node --import tsx --test --test-name-pattern='git signing|devcontainer config generation' __tests__/app.test.ts` and confirm the new assertions fail because the module and mounts do not exist.
+- [ ] Add state paths and container constants, implement the pure resolver and public-key snapshot, and let `buildGeneratedDevcontainerConfig(context, signingPlan)` add read-only key-state and agent mounts only for enabled plans.
+- [ ] Rerun the focused tests and confirm they pass.
+
+### Task 2: Configure and validate container-side Git signing
+
+**Files:**
+
+- Create: `assets/devcontainer/utils/git-signing-bootstrap.sh`
+- Modify: `assets/devcontainer/utils/git-config-bootstrap.sh`, `assets/devcontainer/hooks/post-create.sh`, `assets/devcontainer/hooks/post-start.sh`
+- Test: `__tests__/app.test.ts`
+
+**Interfaces:**
+
+```bash
+bash /opt/boxdown/devcontainer/utils/git-signing-bootstrap.sh
+# Reads BOXDOWN_GIT_SIGNING_ENABLED and BOXDOWN_GIT_SIGNING_KEY_PATH.
+# Exits 0 in both signed and unsigned fallback modes.
+```
+
+- [ ] Write failing shell-hook tests for successful SSH configuration, absent-agent fallback, removal of incompatible `gpg.program`, and absence of repository-local `commit.gpgsign` writes.
+- [ ] Run the matching `devcontainer git config hooks` tests and confirm the new assertions fail.
+- [ ] Implement a temporary-repository signing probe using `ssh-add -L`, a temporary allowed-signers file, and `git commit --allow-empty`; set global SSH signing only after it succeeds, otherwise set global `commit.gpgsign=false` and print a warning.
+- [ ] Remove unconditional global signing disablement and all post-create local `commit.gpgsign` mutations; call the bootstrap after create and start.
+- [ ] Rerun the hook tests and confirm they pass.
+
+### Task 3: Use one signing-aware lifecycle for every command
+
+**Files:**
+
+- Modify: `src/devcontainer.ts`, `src/main.ts`
+- Test: `__tests__/app.test.ts`
+
+**Interfaces:**
+
+```ts
+export async function resolveGitSigningPlan(context: WorkspaceContext): Promise<GitSigningPlan>
+export async function ensureContainerGitSigning(context: WorkspaceContext, plan: GitSigningPlan, options?: ContainerCommandOptions): Promise<void>
+```
+
+- [ ] Write failing command-flow tests proving `startDevcontainer` writes a signing-aware config and invokes the non-fatal container signing refresh for fresh and reused containers.
+- [ ] Run the relevant `CLI execution` and `coding-agent command mapping` tests and confirm they fail on the missing signing lifecycle.
+- [ ] Resolve the plan before writing generated config, pass plan state to the lifecycle script, and call the refresh from shared startup so setup, shell, coding agents, SSH proxy, and tunnels all inherit it.
+- [ ] Ensure refresh failures only warn and do not change the command exit code.
+- [ ] Rerun focused lifecycle tests and confirm they pass.
+
+### Task 4: Add doctor/preflight warnings and user documentation
+
+**Files:**
+
+- Modify: `src/doctor.ts`, `src/main.ts`, `README.md`, `docs/features/setup.md`, `docs/architecture.md`, `docs/features/README.md`
+- Create: `docs/features/commit-signing.md`, `.changeset/<generated-name>.md`
+- Test: `__tests__/app.test.ts`
+
+- [ ] Write failing doctor tests for unavailable agent, ambiguous identities, unusable mount, missing GitHub signing registration, and warning-only setup behavior.
+- [ ] Run the `doctor output` and setup-preflight tests and confirm the new checks are absent.
+- [ ] Add warning-only host signing checks, including an optional GitHub signing-key query; do not add account mutations or required preflight failures.
+- [ ] Document automatic selection order, unsigned fallback, Docker mount limitations, agent security exposure, and GitHub's one-time separate signing-key registration.
+- [ ] Add a changeset for default-on best-effort commit signing.
+- [ ] Rerun focused doctor/setup tests and lint changed Markdown.
+
+### Task 5: Verify the full feature
+
+**Files:**
+
+- Test: `__tests__/app.test.ts`
+
+- [ ] Run `node --import tsx --test __tests__/**/*.test.ts`; record the two known unrelated baseline failures and require no additional failures.
+- [ ] Run `npm run build` and `npm run lint` using local project tooling where available.
+- [ ] With Docker and a loaded agent available, create a disposable container using the generated mount, make an empty signed commit, and verify its SSH fingerprint; do not push it.
+- [ ] Review `git diff --check`, changed docs, and the implementation against `docs/superpowers/specs/2026-07-11-default-commit-signing-design.md`.

package/docs/superpowers/plans/2026-07-11-progress-ci-regression.md

@@ -0,0 +1,125 @@
+# Progress CI Regression Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Restore CI by making progress checklist cleanup mode-independent and updating stale spinner-label source assertions.
+
+**Architecture:** Preserve the existing `ProgressReporter` API and output behavior. Move only internal cleanup ahead of rendering guards, then loosen two source-presence assertions while leaving runtime checklist-output coverage intact.
+
+**Tech Stack:** TypeScript, Node.js 24 test runner, `node:assert`, pnpm, ESLint, tsdown
+
+## Global Constraints
+
+- Do not change progress APIs, spinner copy, output formatting, or command flow.
+- Use Node.js 24 for tests because the current Node.js 26 host runtime is incompatible with an installed CommonJS test dependency.
+- Commit documentation separately from the implementation, as explicitly requested.
+
+---
+
+### Task 1: Commit the approved documentation
+
+**Files:**
+
+- Create: `docs/superpowers/specs/2026-07-11-progress-ci-regression-design.md`
+- Create: `docs/superpowers/plans/2026-07-11-progress-ci-regression.md`
+
+**Interfaces:**
+
+- Consumes: The user-approved diagnosis and design.
+- Produces: Durable design and execution context for the CI fix.
+
+- [ ] **Step 1: Verify documentation formatting**
+
+Run:
+
+```bash
+git diff --check
+fnm exec --using v24.15.0 node ../../node_modules/markdownlint-cli/markdownlint.js \
+  -c .github/.markdownlint.yml -i 'apm_modules/**' -i '.git' -i '__tests__' \
+  -i '.github' -i '.changeset' -i 'CODE_OF_CONDUCT.md' -i 'CHANGELOG.md' \
+  -i 'node_modules' -i 'dist' '**/**.md'
+```
+
+Expected: PASS with no whitespace or Markdown lint errors.
+
+- [ ] **Step 2: Commit documentation only**
+
+```bash
+git add docs/superpowers/specs/2026-07-11-progress-ci-regression-design.md docs/superpowers/plans/2026-07-11-progress-ci-regression.md
+git commit -m "docs: design progress CI regression fix"
+```
+
+Expected: A commit containing only the design specification and implementation plan.
+
+### Task 2: Fix progress cleanup and stale assertions
+
+**Files:**
+
+- Modify: `src/progress.ts:147`
+- Test: `__tests__/app.test.ts:3080`
+- Test: `__tests__/app.test.ts:3427`
+
+**Interfaces:**
+
+- Consumes: `ProgressReporter.end()` and `ProgressReporter.isChecklistActive()`.
+- Produces: Mode-independent reporter cleanup without API changes.
+
+- [ ] **Step 1: Verify the existing tests reproduce both CI failures**
+
+Run:
+
+```bash
+fnm exec --using v24.15.0 node --import tsx --test \
+  --test-name-pattern='reports whether a checklist is active|hidden command helpers use friendly spinner labels' \
+  __tests__/app.test.ts
+```
+
+Expected: FAIL because checklist state remains active in `none` mode and the SSH label regular expressions require an outdated direct-property expression.
+
+- [ ] **Step 2: Make cleanup independent of rendering mode**
+
+In `ProgressReporter.end()`, clear internal state immediately after stopping timers:
+
+```ts
+this.#steps = []
+this.#renderedStepLineCount = 0
+```
+
+Remove the existing duplicate cleanup after the interactive section terminator.
+
+- [ ] **Step 3: Make the source-presence assertions expression-shape independent**
+
+Replace the two SSH assertions with:
+
+```ts
+assert.match(sshKeySource, /Generating Boxdown SSH identity/)
+assert.match(sshKeySource, /Writing Boxdown SSH public key/)
+```
+
+- [ ] **Step 4: Verify the focused regression tests pass**
+
+Run the Step 1 command again.
+
+Expected: PASS for both selected tests.
+
+- [ ] **Step 5: Run full verification**
+
+Run:
+
+```bash
+fnm exec --using v24.15.0 node ../../node_modules/c8/bin/c8.js node --import tsx --test __tests__/**/*.test.ts
+fnm exec --using v24.15.0 node ../../node_modules/eslint/bin/eslint.js .
+fnm exec --using v24.15.0 node ../../node_modules/typescript/bin/tsc
+fnm exec --using v24.15.0 node ../../node_modules/tsdown/dist/run.mjs
+```
+
+Expected: All tests pass, ESLint reports no errors, TypeScript compilation succeeds, and tsdown builds successfully.
+
+- [ ] **Step 6: Commit the implementation separately**
+
+```bash
+git add src/progress.ts __tests__/app.test.ts
+git commit -m "fix(progress): clear checklist state in every mode"
+```
+
+Expected: A second commit containing only the production fix and updated assertions.