Skip to content

Commit e4fb656

Browse files
huberphuberp
committed
Create new issue: feat: native executable build via Bun compile
1 parent fa81620 commit e4fb656

1 file changed

Lines changed: 121 additions & 0 deletions

File tree

‎issues/1.md‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
## Summary
2+
3+
Add a native single-binary build target for `agentloop` using [Bun's `--compile` flag](https://bun.sh/docs/bundler/executables), producing self-contained executables for Linux, macOS, and Windows that require no Node.js or `npm install` on the target machine.
4+
5+
---
6+
7+
## Motivation
8+
9+
Currently, running `agentloop` requires:
10+
1. Node.js 20+ installed
11+
2. `npm install` to materialize `node_modules`
12+
3. `npx tsx ...` or `node dist/...` to launch
13+
14+
A compiled binary removes all three steps — users just download and run a single file. This is particularly valuable for:
15+
- Distribution as a CLI tool
16+
- CI/CD environments where installing Node + deps is undesirable
17+
- End-users who are not Node.js developers
18+
19+
---
20+
21+
## Why Bun `--compile`
22+
23+
The existing dependency profile (`ink`, `react`, `js-tiktoken` WASM, ESM-only packages) rules out legacy tools like `pkg` (archived) and `nexe` (no ESM support). Node.js built-in SEA is too early-stage for this dependency mix.
24+
25+
Bun handles:
26+
- ✅ TypeScript natively — no `tsc` pre-step needed
27+
- ✅ ESM modules (`ink`, `react`, `tidy-url`, MCP SDK)
28+
- ✅ WASM files (`js-tiktoken`) — embedded automatically with `--compile`
29+
- ✅ Cross-compilation to Linux, macOS (arm64/x64), and Windows from a single build machine
30+
- ✅ `.env` files still work (read from filesystem next to the binary)
31+
32+
---
33+
34+
## Implementation Steps
35+
36+
### 1. Verify Bun compatibility
37+
- Run `bun install` and confirm all dependencies resolve under Bun
38+
- Run `bun run src/start-cli.ts` to validate runtime compatibility
39+
- Pay special attention to `jsdom` (used by `web-fetch`) — test that it initializes correctly under Bun
40+
41+
### 2. Add `build:binary` scripts to `package.json`
42+
43+
```json
44+
"build:binary": "bun build src/start-cli.ts --compile --outfile dist/agentloop",
45+
"build:binary:linux": "bun build src/start-cli.ts --compile --target=bun-linux-x64 --outfile dist/agentloop-linux",
46+
"build:binary:macos": "bun build src/start-cli.ts --compile --target=bun-darwin-arm64 --outfile dist/agentloop-macos",
47+
"build:binary:win": "bun build src/start-cli.ts --compile --target=bun-windows-x64 --outfile dist/agentloop.exe"
48+
```
49+
50+
### 3. Handle tool auto-discovery (`loadFromDirectory`)
51+
`AgentProfileRegistry`, `SkillRegistry`, and `ToolRegistry` all use `fs.readdir` on paths resolved relative to `__dirname`. Inside a Bun binary, `__dirname` resolves correctly to the binary's directory — but the `src/tools/`, `src/agents/builtin/`, and `src/skills/builtin/` directories are **embedded** in the bundle, not on disk.
52+
53+
Options to investigate:
54+
- **Preferred:** Use Bun's [`import.meta.dir`](https://bun.sh/docs/api/import-meta) and verify directory scanning works inside the compiled bundle
55+
- **Fallback:** Eagerly register all builtin tools/profiles/skills at compile time (static imports instead of directory scan) when running as a compiled binary, detected via `process.isBun`
56+
57+
### 4. Handle `.env` / config
58+
- `dotenv` reads `.env` from `process.cwd()` — this works unchanged next to the binary
59+
- Document that users should place `.env` in the same directory as the binary
60+
61+
### 5. Add `bun` as a dev dependency (or document install)
62+
63+
```json
64+
"devDependencies": {
65+
"bun-types": "^1.0.0"
66+
}
67+
```
68+
69+
Or document `curl -fsSL https://bun.sh/install | bash` in the build prerequisites.
70+
71+
### 6. Add a GitHub Actions workflow for cross-platform binary releases
72+
73+
```yaml
74+
# .github/workflows/release-binaries.yml
75+
name: Build release binaries
76+
on:
77+
release:
78+
types: [created]
79+
jobs:
80+
build:
81+
runs-on: ubuntu-latest
82+
steps:
83+
- uses: actions/checkout@v4
84+
- uses: oven-sh/setup-bun@v2
85+
- run: bun install
86+
- run: bun run build:binary:linux
87+
- run: bun run build:binary:macos
88+
- run: bun run build:binary:win
89+
- uses: softprops/action-gh-release@v2
90+
with:
91+
files: |
92+
dist/agentloop-linux
93+
dist/agentloop-macos
94+
dist/agentloop.exe
95+
```
96+
97+
### 7. Update `docs/getting-started.md`
98+
Add a "Download pre-built binary" section as the first / easiest install path.
99+
100+
---
101+
102+
## Known Risks & Mitigations
103+
104+
| Risk | Mitigation |
105+
|---|---|
106+
| `jsdom` native internals break under Bun | Lazy-import `jsdom` only when `web-fetch` tool is invoked; add a Bun smoke test |
107+
| `loadFromDirectory()` finds no files inside binary | Detect `process.isBun` + compiled mode, fall back to static registration |
108+
| Binary size too large | Acceptable trade-off; `bun build --minify` can reduce size |
109+
| TUI (`ink` + `react`) rendering differences under Bun | Test `npm run startTui` equivalent under Bun before shipping |
110+
111+
---
112+
113+
## Acceptance Criteria
114+
115+
- [ ] `bun run build:binary` produces a working `dist/agentloop` binary on the build machine
116+
- [ ] The binary starts the CLI REPL, accepts a prompt, and calls at least one tool successfully
117+
- [ ] Cross-compilation scripts produce binaries for all three platforms
118+
- [ ] `jsdom`-backed `web-fetch` tool works inside the compiled binary
119+
- [ ] Tool auto-discovery (builtins) works inside the compiled binary
120+
- [ ] GitHub Actions workflow builds and attaches binaries to GitHub Releases
121+
- [ ] `docs/getting-started.md` documents the binary install path

0 commit comments

Comments
 (0)