boxdown 1.0.0

package/docs/features/github-auth-refresh.md

@@ -0,0 +1,64 @@
+# GitHub Auth Refresh
+
+## Commands
+
+```sh
+boxdown refresh-gh-token
+boxdown refresh-gh-token-running
+```
+
+Both commands copy host GitHub CLI auth into the container using the host token
+from:
+
+```sh
+gh auth token
+```
+
+They do not start a browser login or device-code flow.
+
+These commands are explicit on purpose. Normal `boxdown start`, coding-agent
+launches, and SSH proxy connections do not copy GitHub credentials into the
+container.
+
+## refresh-gh-token
+
+`refresh-gh-token` starts or reuses the devcontainer, then refreshes GitHub CLI
+auth inside it.
+
+Use this when the container might not already be running.
+
+## refresh-gh-token-running
+
+`refresh-gh-token-running` requires a running devcontainer for the workspace.
+It fails early when no matching running container exists.
+
+Use this when you want to refresh auth without accidentally starting a
+container.
+
+## Container Work
+
+When a host token is available, Boxdown runs inside the container:
+
+```sh
+gh auth login --hostname github.com --git-protocol https --with-token --insecure-storage
+```
+
+It also configures this repository's local Git config so GitHub remotes use the
+container's authenticated `gh` for `git fetch`, `git pull`, and `git push`.
+For GitHub remotes, Boxdown:
+
+- rewrites fetch and push URLs to `https://github.com/<owner>/<repo>.git`
+- resets inherited `credential.https://github.com.helper` entries locally
+- adds `!gh auth git-credential` as the local GitHub credential helper
+- adds a repository-specific HTTPS self-rewrite so broader host rewrites like
+  `url.git@github.com:.insteadOf=https://github.com/` do not force SSH inside
+  the container
+
+The local Git config changes are written to the workspace repository because the
+host checkout is mounted into the devcontainer.
+
+If host `gh` is missing, logged out, or cannot return a token, the refresh is a
+no-op.
+
+`OP_SERVICE_ACCOUNT_TOKEN`, when present, is a 1Password service account token.
+It is not a GitHub token and is not used by `gh` or GitHub Git operations.

package/docs/features/lifecycle.md

@@ -0,0 +1,64 @@
+# Lifecycle Commands
+
+## Commands
+
+```sh
+boxdown list
+boxdown list --json
+boxdown status
+boxdown status --json
+boxdown stop
+boxdown down
+boxdown doctor
+```
+
+Workspace-targeting commands accept `--workspace <path>`. `status` also accepts
+`--alias <name>` so its output can match a custom SSH host alias.
+
+## List
+
+`list` shows every workspace with Boxdown metadata under the data root,
+regardless of the directory where the command is run. Human output includes
+`STATE`, `REPO`, `PATH`, `SSH ALIAS`, and `CONTAINER` columns.
+
+`list --json` prints the same inventory as structured JSON. Docker state is
+best-effort: if Docker is unavailable, entries still print and their container
+state is `unknown`. If a recorded repository path no longer exists, the entry is
+shown as `missing`.
+
+## Status
+
+`status` is read-only. It reports the resolved workspace, intended cache/data
+paths, generated config path, SSH key paths, SSH alias, and the matching Docker
+container state without recording the workspace in Boxdown metadata.
+
+Human output distinguishes intended values from detected state. For example, an
+SSH alias can be shown as a computed default even when the matching Boxdown SSH
+config block has not been installed. Existing paths are labeled `exists`,
+missing paths are labeled `missing`, and managed SSH config blocks are labeled
+`installed`, `missing`, or `outdated`. Healthy values are color-coded green and
+missing or unhealthy values are color-coded red.
+
+`status --json` prints the same information as structured JSON for scripts.
+`status` exits 0 only when the generated config exists, devcontainer assets
+exist, SSH key material exists, the runtime public key exists, and the
+workspace container is running. Missing setup or a stopped/absent container is
+reported in the output and exits nonzero. Installing an SSH alias is optional
+and is not required for a healthy status exit.
+
+## Stop and Down
+
+`stop` stops the workspace devcontainer when it is running. If the container is
+already stopped or absent, it prints a short message and exits 0.
+
+`down` removes the workspace devcontainer with Docker. It does not remove
+Boxdown cache, generated config, data directories, or SSH keys.
+
+## Doctor
+
+`doctor` validates required host prerequisites: Node, Docker CLI, Docker
+daemon access, SSH tools, packaged devcontainer assets, and Boxdown's packaged
+`@devcontainers/cli` dependency.
+
+GitHub CLI auth is optional. Missing or unauthenticated `gh` is reported as a
+warning rather than a failure.

package/docs/features/ssh-config-and-proxy.md

@@ -0,0 +1,60 @@
+# SSH Config and Proxy Workflow
+
+## Commands
+
+```sh
+boxdown ssh-config install
+boxdown ssh-proxy
+```
+
+`boxdown ssh-config` is accepted as a convenience shortcut for
+`boxdown ssh-config install`, but docs use the explicit install form.
+
+`ssh-proxy` is primarily an internal command launched by OpenSSH as a
+`ProxyCommand`.
+
+## SSH Alias Installation
+
+By default, Boxdown creates an alias named:
+
+```text
+<repo-name>-devcontainer
+```
+
+The generated SSH config block includes:
+
+- `User node`
+- a per-workspace host identity file
+- `IdentitiesOnly yes`
+- a `ProxyCommand` that runs the current Boxdown installation's built CLI
+
+The block is wrapped in Boxdown markers so repeated installs replace the managed
+block instead of duplicating it.
+
+`boxdown status` reports whether that Boxdown-managed block is `installed`,
+`missing`, or `outdated`. It only recognizes blocks wrapped in Boxdown's marker
+comments; an unrelated OpenSSH `Host` entry with the same alias is not treated
+as an installed Boxdown alias.
+
+## Proxy Flow
+
+When OpenSSH launches `boxdown ssh-proxy`, Boxdown:
+
+1. Quietly refreshes the SSH config block.
+2. Ensures the per-workspace host key exists.
+3. Reuses a running devcontainer when possible.
+4. Starts the devcontainer when needed.
+5. Runs a throttled coding-agent CLI update preflight inside the container.
+6. Runs the container SSH bootstrap runtime.
+7. Bridges OpenSSH to `/usr/sbin/sshd -i` through `docker exec -i`.
+
+This does not publish an SSH port. The SSH stream travels through Docker exec.
+
+The coding-agent CLI update preflight covers already-running containers, where
+`postStartCommand` does not necessarily run before a new SSH session. Its output
+is routed to stderr so stdout remains reserved for SSH traffic.
+
+## Key Boundary
+
+The private key stays on the host. The container receives only the public key,
+mounted from a public-key-only runtime directory.

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

@@ -0,0 +1,83 @@
+# Start Command
+
+## Commands
+
+```sh
+boxdown start
+boxdown codex
+boxdown claude
+boxdown cc
+boxdown opencode
+boxdown antigravity
+```
+
+`start` targets the current directory by default and accepts:
+
+```sh
+--workspace <path>
+--recreate
+```
+
+`boxdown shell` remains supported as an alias for `boxdown start`, but `start`
+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`.
+
+Pass agent-specific arguments after `--` so Boxdown options stay unambiguous:
+
+```sh
+boxdown claude -- --continue
+```
+
+## Flow
+
+1. Resolve the workspace to a real absolute path.
+2. Ensure per-workspace SSH key material exists.
+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.
+7. Print a dynamic port hint when the configured published port is mapped.
+8. Run `devcontainer exec ... bash` to open an interactive shell.
+
+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`.
+
+## Terminal Width
+
+Some terminal UIs behave poorly when a host terminal reports an extremely wide
+PTY, especially from embedded terminals. Before opening the shell, Boxdown
+clamps interactive terminal width to 120 columns when the reported width is
+larger.
+
+Override the default width when you want a wider layout:
+
+```sh
+BOXDOWN_TTY_MAX_COLUMNS=180 boxdown start
+```
+
+Disable the normalization entirely when you want the container shell to use the
+host terminal size unchanged:
+
+```sh
+BOXDOWN_TTY_NORMALIZE=0 boxdown start
+```
+
+## Recreate
+
+`--recreate` passes `--remove-existing-container` to the Dev Containers CLI.
+Use it when changing create-time settings such as image, features, mounts, or
+Docker `runArgs`.
+
+## Port Hint
+
+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.

package/docs/testing.md

@@ -0,0 +1,63 @@
+# Testing
+
+## Standard Checks
+
+Run these before opening a PR:
+
+```sh
+pnpm run lint
+pnpm run build
+pnpm run test
+```
+
+`pnpm run lint` includes ESLint and markdown lint. Documentation under `docs/`
+is intentionally linted.
+
+## Unit Test Strategy
+
+Unit tests should avoid starting Docker. Prefer pure tests for:
+
+- CLI parsing and command aliases.
+- Workspace path resolution and state directory selection.
+- Generated devcontainer config shape.
+- SSH config block creation and idempotent replacement.
+- 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.
+
+## Build and CLI Smoke Tests
+
+After `pnpm run build`, smoke test the built binary:
+
+```sh
+node dist/bin/cli.cjs --help
+```
+
+Use a dry-run pack check when changing package assets or `package.json.files`:
+
+```sh
+npm pack --dry-run --json
+```
+
+Confirm `assets/devcontainer/**` is included and `.ssh/` is not.
+
+## Manual Acceptance
+
+Manual Docker acceptance is heavier and should be done intentionally:
+
+```sh
+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
+ssh <repo-name>-devcontainer 'whoami && pwd'
+```
+
+Run this from at least two repositories when changing workspace isolation,
+container lookup, SSH config generation, or generated config behavior.

package/docs/todo.md

@@ -0,0 +1,170 @@
+# Todo and Next Plans
+
+This file is a handoff for the next Boxdown implementation session. It assumes
+v1 exists as a CLI-first package that stores reusable devcontainer assets under
+`assets/devcontainer/`, generates per-workspace override config outside target
+repositories, and supports start (with `shell` as an alias), SSH proxy, SSH
+config install, lifecycle status/stop/down/doctor commands, and GitHub auth
+refresh commands.
+
+## Current Baseline
+
+- Boxdown has no root `.devcontainer/` directory.
+- Reusable devcontainer source lives in `assets/devcontainer/`.
+- Generated config uses the Dev Containers CLI with `--workspace-folder` and
+  `--override-config`.
+- Workspace cache state defaults to `~/.cache/boxdown`.
+- Workspace persistent state defaults to `~/.local/share/boxdown`.
+- Host private SSH keys stay on the host; the container receives only a public
+  key mount.
+- Lifecycle commands report status, color-code unhealthy status output, check
+  host prerequisites, stop containers, and remove containers without deleting
+  Boxdown state or SSH keys.
+- Unit tests cover parsing, generated config shape, SSH config block generation,
+  lifecycle output formatting, and packaging safety.
+
+## Next Implementation Tracks
+
+### 1. Manual Acceptance and Runtime Fixes (completed)
+
+The real Docker and SSH workflow was tested from linked local `boxdown`
+commands. Runtime fixes from that pass included interactive terminal width
+normalization and command alias cleanup.
+
+Acceptance commands:
+
+```sh
+boxdown start --workspace ~/projects/repos/gh-cp
+boxdown ssh-config 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
+ssh lirantaldotcom-devcontainer 'whoami && pwd'
+```
+
+### 2. Lifecycle Commands and CLI UX (completed)
+
+Added practical commands around the existing start flow:
+
+- `boxdown status` to show workspace, generated config path, container ID,
+  running state, SSH alias, and key paths.
+- `boxdown stop` to stop the workspace container.
+- `boxdown down` to remove the workspace container.
+- `boxdown doctor` to validate Node, Docker, SSH, packaged `@devcontainers/cli`,
+  optional `gh`, and asset presence.
+- `boxdown status --json` for machine-readable status output.
+
+Lifecycle commands keep destructive behavior explicit and conservative. They do
+not remove generated state or SSH keys.
+
+### 3. Editor Stub Support
+
+Add an optional command for users who want native VS Code or Cursor Dev
+Containers discovery:
+
+```sh
+boxdown init-editor-stub
+```
+
+The stub should be opt-in and small. It can either create a minimal
+`.devcontainer/devcontainer.json` that delegates to Boxdown-generated config or
+document why native editor discovery still requires a project-local file.
+
+Do not make editor stubs part of the default workflow. The v1 invariant is that
+target repositories stay clean unless the user explicitly asks for a file.
+
+### 4. Customization and Profiles
+
+Design a small user configuration surface for common changes:
+
+- Extra forwarded ports.
+- Extra host mounts for agent config directories.
+- Feature toggles for tools such as Snyk, 1Password, Codex CLI, or APM.
+- Image or Node version overrides.
+- Per-project SSH alias defaults.
+
+Prefer a Boxdown-owned config file under user config/state locations before
+adding target-repo config. If target-repo config is needed, make precedence and
+security implications explicit.
+
+### 5. Dev Container Feature Packaging
+
+Investigate moving the container-side OpenSSH bootstrap and runtime setup into a
+proper Dev Container Feature. This could make lifecycle behavior more
+spec-native and reduce reliance on mounted shell assets.
+
+Questions to answer:
+
+- Should the feature be published to GHCR?
+- Does publishing a feature complicate local development?
+- Which setup should remain as mounted assets for offline or unreleased use?
+
+### 6. Asset Sync Workflow
+
+Decide whether `gh-cp/.devcontainer` remains the canonical source or whether
+Boxdown now owns the canonical asset copy.
+
+If `gh-cp` remains canonical, add a documented sync command or maintainer script
+that copies only tracked files and excludes `.ssh/`. If Boxdown becomes
+canonical, update docs in both repos so future changes happen in the right
+place.
+
+### 7. Integration Test Harness
+
+Add tests beyond pure unit coverage without making CI fragile:
+
+- Fake `docker`, `npm`, `gh`, and `devcontainer` binaries for command argument
+  assertions.
+- Temporary HOME, cache, data, and SSH config paths.
+- Golden tests for generated `devcontainer.json`.
+- Optional local-only integration tests that start real containers.
+
+Keep real Docker tests out of default CI until they are fast, deterministic, and
+safe for GitHub Actions runners.
+
+### 8. Release Polish
+
+Before the first serious npm release:
+
+- Confirm package contents with `npm pack --dry-run --json`.
+- Confirm `npx boxdown --help` works from a packed tarball.
+- Add examples for common agent workflows.
+- Confirm the changeset summary is user-facing.
+- Consider whether `dist` should be committed or only generated in release CI.
+
+## What a Fresh Session Needs to Know
+
+Read these files first:
+
+- `docs/architecture.md`
+- `docs/features/generated-config-and-state.md`
+- `docs/features/ssh-config-and-proxy.md`
+- `src/config.ts`
+- `src/devcontainer.ts`
+- `src/ssh-config.ts`
+- `src/ssh-key.ts`
+
+Confirm these facts before implementation:
+
+- Whether real Docker/SSH manual acceptance is allowed in the current session.
+- Which host platforms are in scope for the next release: macOS, Linux, WSL, or
+  Windows OpenSSH.
+- Whether Boxdown or `gh-cp` should own canonical devcontainer assets going
+  forward.
+- Whether target repositories may ever contain generated files by default.
+- Whether user configuration should live only in Boxdown state or may be read
+  from the target repository.
+- Which editor gets first-class support if editor stubs are built.
+- Whether GitHub auth refresh should keep using `--insecure-storage` inside the
+  container or offer a more configurable credential strategy.
+
+## Suggested Fresh-Session Prompt
+
+```text
+Continue Boxdown after v1. Read docs/todo.md, docs/architecture.md, and the
+feature docs first. Start with manual Docker and SSH acceptance for two repos,
+then fix any runtime issues while preserving the invariants: no root
+.devcontainer in Boxdown, no .devcontainer copied into target repos, no private
+SSH key mounted into containers, and generated config/state owned by Boxdown.
+```

package/package.json

@@ -0,0 +1,128 @@
+{
+  "name": "boxdown",
+  "version": "1.0.0",
+  "description": "Run a reusable devcontainer sandbox for any local project",
+  "types": "dist/main.d.mts",
+  "type": "module",
+  "bin": {
+    "boxdown": "./dist/bin/cli.cjs"
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/main.d.mts",
+        "default": "./dist/main.mjs"
+      },
+      "require": {
+        "types": "./dist/main.d.cts",
+        "default": "./dist/main.cjs"
+      },
+      "default": "./dist/main.mjs"
+    },
+    "./dist/*": {
+      "types": "./dist/*.d.mts",
+      "import": "./dist/*.mjs",
+      "require": "./dist/*.cjs"
+    }
+  },
+  "engines": {
+    "node": ">=24.0.0",
+    "pnpm": ">=11.0.0"
+  },
+  "devEngines": {
+    "packageManager": {
+      "name": "pnpm",
+      "version": ">=11.0.0",
+      "onFail": "download"
+    }
+  },
+  "files": [
+    "assets",
+    "docs",
+    "dist",
+    "src",
+    "bin"
+  ],
+  "author": {
+    "name": "Liran Tal",
+    "email": "liran.tal@gmail.com",
+    "url": "git+https://github.com/lirantal"
+  },
+  "publishConfig": {
+    "provenance": true,
+    "access": "public"
+  },
+  "license": "Apache-2.0",
+  "keywords": [
+    "devcontainer",
+    "docker",
+    "development-environment",
+    "ssh",
+    "sandbox"
+  ],
+  "homepage": "https://github.com/lirantal/boxdown",
+  "bugs": {
+    "url": "https://github.com/lirantal/boxdown/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lirantal/boxdown.git"
+  },
+  "dependencies": {
+    "@devcontainers/cli": "0.84.1"
+  },
+  "devDependencies": {
+    "@changesets/changelog-github": "^0.5.0",
+    "@changesets/cli": "^2.27.7",
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^25.5.0",
+    "c8": "^11.0.0",
+    "eslint": "^10.2.1",
+    "eslint-plugin-n": "^17.24.0",
+    "eslint-plugin-security": "^4.0.0",
+    "husky": "^9.0.11",
+    "lint-staged": "^16.2.7",
+    "markdownlint-cli": "0.48.0",
+    "tsdown": "^0.21.5",
+    "tsx": "^4.19.4",
+    "typescript": "^5.5.3",
+    "typescript-eslint": "^8.59.0",
+    "validate-conventional-commit": "^1.0.4"
+  },
+  "lint-staged": {
+    "**/*.{js,json}": [
+      "pnpm run lint:fix"
+    ]
+  },
+  "c8": {
+    "exclude": [
+      "dist/**",
+      "coverage/**",
+      "__tests__/**",
+      "**/*.test.ts",
+      "**/*.test.js"
+    ],
+    "include": [
+      "src/**"
+    ],
+    "reporter": [
+      "text",
+      "lcov",
+      "html"
+    ]
+  },
+  "scripts": {
+    "start": "tsx src/bin/cli.ts",
+    "build": "tsc && tsdown",
+    "lint": "eslint . && pnpm run lint:markdown",
+    "lint:markdown": "markdownlint -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'",
+    "lint:markdown:fix": "markdownlint -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' --fix",
+    "lint:fix": "eslint . --fix",
+    "test": "c8 node --import tsx --test __tests__/**/*.test.ts",
+    "test:watch": "c8 node --import tsx --test --watch __tests__/**/*.test.ts",
+    "coverage:view": "open coverage/lcov-report/index.html",
+    "version": "changeset version",
+    "release": "changeset publish",
+    "release:create": "changeset && git add .changeset && git commit -m \"chore: release\" && git push origin HEAD --no-verify"
+  }
+}

package/src/bin/cli.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { runCli } from '../main.ts'
+
+runCli().then((exitCode) => {
+  process.exitCode = exitCode
+}, (error: unknown) => {
+  process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`)
+  process.exitCode = 1
+})

package/src/coding-agents.ts

@@ -0,0 +1,22 @@
+export type CodingAgentCli = 'codex' | 'opencode' | 'claude' | 'antigravity'
+export type CodingAgentCommandAlias = CodingAgentCli | 'cc'
+
+const CODING_AGENT_ALIASES: Record<CodingAgentCommandAlias, CodingAgentCli> = {
+  codex: 'codex',
+  opencode: 'opencode',
+  claude: 'claude',
+  cc: 'claude',
+  antigravity: 'antigravity'
+}
+
+export function codingAgentFromCommand (command: string): CodingAgentCli | undefined {
+  return CODING_AGENT_ALIASES[command as CodingAgentCommandAlias]
+}
+
+export function codingAgentBinary (agent: CodingAgentCli): string {
+  if (agent === 'antigravity') {
+    return 'agy'
+  }
+
+  return agent
+}