@pablozaiden/devbox 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +105 -0
- package/dist/devbox.js +1802 -0
- package/package.json +49 -0
package/README.md
ADDED
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
# devbox
|
|
2
|
+
|
|
3
|
+
`devbox` is a CLI that turns the devcontainer definition in the current directory into a repeatable "start my workspace and expose an SSH entrypoint" workflow.
|
|
4
|
+
|
|
5
|
+
It does not modify the original `devcontainer.json`. Instead, it generates a derived config next to it, ignores that file locally when possible, and manages the resulting container with stable labels.
|
|
6
|
+
|
|
7
|
+
## What it does
|
|
8
|
+
|
|
9
|
+
- Discovers `.devcontainer/devcontainer.json` or `.devcontainer.json` in the current directory.
|
|
10
|
+
- Reuses or creates the devcontainer with Docker + Dev Container CLI.
|
|
11
|
+
- Names the managed container as `devbox-<project>-<port>`.
|
|
12
|
+
- Publishes the same TCP port on host and container.
|
|
13
|
+
- Mounts the current directory into the container as the workspace.
|
|
14
|
+
- Shares a usable SSH agent socket with the container and copies `known_hosts` into the container.
|
|
15
|
+
- Runs the [`ssh-server-runner`](https://github.com/PabloZaiden/ssh-server-runner) one-liner inside the devcontainer.
|
|
16
|
+
- Persists the runner credentials on the mounted workspace as a local `.sshcred` file, and keeps SSH host keys in `.devbox-ssh-host-keys/`, so they survive `down` / `rebuild`.
|
|
17
|
+
|
|
18
|
+
## Installation
|
|
19
|
+
|
|
20
|
+
Install globally with Bun:
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
bun install -g @pablozaiden/devbox
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
Or install globally with npm:
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
npm install -g @pablozaiden/devbox
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
After either install, `devbox` is available in any directory.
|
|
33
|
+
|
|
34
|
+
## Requirements
|
|
35
|
+
|
|
36
|
+
- macOS or Linux
|
|
37
|
+
- [Node.js](https://nodejs.org/) or [Bun](https://bun.sh/) to run the installed CLI
|
|
38
|
+
- Docker
|
|
39
|
+
- Dev Container CLI available as `devcontainer`
|
|
40
|
+
- For SSH agent sharing: either a valid host `SSH_AUTH_SOCK`, or Docker Desktop host services
|
|
41
|
+
- A devcontainer using `image` or `Dockerfile`
|
|
42
|
+
|
|
43
|
+
`dockerComposeFile`-based devcontainers are intentionally out of scope for v1.
|
|
44
|
+
|
|
45
|
+
## Commands
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
# Start or reuse the devcontainer on port 5001
|
|
49
|
+
devbox 5001
|
|
50
|
+
|
|
51
|
+
# Same as above
|
|
52
|
+
devbox up 5001
|
|
53
|
+
|
|
54
|
+
# Continue even if SSH agent sharing is unavailable
|
|
55
|
+
devbox up 5001 --allow-missing-ssh
|
|
56
|
+
|
|
57
|
+
# Rebuild/recreate the managed devcontainer
|
|
58
|
+
devbox rebuild 5001
|
|
59
|
+
|
|
60
|
+
# Stop and remove the managed container while preserving the workspace-mounted SSH credentials
|
|
61
|
+
devbox down
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
If you omit the port for `up` or `rebuild`, `devbox` will reuse the last port stored for the current workspace.
|
|
65
|
+
|
|
66
|
+
## Development
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
bun install
|
|
70
|
+
bun test
|
|
71
|
+
bun run build
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
The build step emits a bundled executable JS entrypoint at `dist/devbox.js`.
|
|
75
|
+
|
|
76
|
+
For local development from this repository:
|
|
77
|
+
|
|
78
|
+
- use `bun run src/cli.ts` while iterating on source changes
|
|
79
|
+
- use `./dist/devbox.js` after `bun run build` to exercise the packaged artifact
|
|
80
|
+
|
|
81
|
+
For a quick smoke test, this repository includes `examples/smoke-workspace/.devcontainer/devcontainer.json`:
|
|
82
|
+
|
|
83
|
+
```bash
|
|
84
|
+
cd examples/smoke-workspace
|
|
85
|
+
../../dist/devbox.js up 5001 --allow-missing-ssh
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
## Notes
|
|
89
|
+
|
|
90
|
+
- The generated config is written next to the original devcontainer config, using the alternate accepted devcontainer filename so relative Dockerfile paths keep working.
|
|
91
|
+
- `down` removes managed containers but does not delete the workspace `.sshcred` or `.devbox-ssh-host-keys/`, so the SSH password and SSH host identity survive rebuilds.
|
|
92
|
+
- Re-running `devbox` after a host restart recreates the desired state: container up, port published, SSH runner started again.
|
|
93
|
+
- When Docker Desktop host services are available, `devbox` can share the SSH agent without relying on a host-shell `SSH_AUTH_SOCK`.
|
|
94
|
+
- On Docker Desktop, `devbox` prefers the Docker-provided SSH agent socket over the host `SSH_AUTH_SOCK`, which avoids macOS launchd socket mount issues.
|
|
95
|
+
- `--allow-missing-ssh` starts the workspace without mounting an SSH agent and prints a warning instead of failing.
|
|
96
|
+
|
|
97
|
+
## Releasing to npm
|
|
98
|
+
|
|
99
|
+
Publishing is wired through `.github/workflows/release-npm-package.yml`.
|
|
100
|
+
|
|
101
|
+
- Create a GitHub release tagged like `v1.2.3`.
|
|
102
|
+
- The workflow checks out that tag, sets `package.json` to version `1.2.3`, installs dependencies, runs tests, builds the package, and publishes `@pablozaiden/devbox` to npm.
|
|
103
|
+
- The workflow uses npm trusted publishing (`id-token: write`), so no npm token has to be stored in the repository.
|
|
104
|
+
|
|
105
|
+
Before the first release, enable trusted publishing for `@pablozaiden/devbox` in npm and connect it to the `PabloZaiden/devbox` GitHub repository.
|