AGENTS.md

1# bin/ - Published Launcher Shim
2 
3## OVERVIEW
4 
5Node-side launch surface for every public CLI alias. The root shim resolves a platform package and spawns its generated `bin/oh-my-opencode.js` launcher payload; it is not the TypeScript CLI implementation.
6 
7## WHERE TO LOOK
8 
9| Task | Location | Notes |
10|------|----------|-------|
11| Main launcher | `oh-my-opencode.js` | Entry for `oh-my-opencode`, `oh-my-openagent`, `omo`, `lazycodex`, and `lazycodex-ai` |
12| Platform selection | `platform.js` | OS/arch/libc package candidates and baseline fallback |
13| Platform types | `platform.d.ts` | Public declarations for the plain-JS selector |
14| Version mismatch output | `version-mismatch.js` | User-facing installed-wrapper/platform-package mismatch diagnostics |
15| Behavior tests | `*.test.ts` | Bun tests for invocation routing, platform selection, and diagnostics |
16 
17## RUNTIME FLOW
18 
19`oh-my-opencode.js` derives the invocation name, optionally routes the LazyCodex Node installer, resolves an ordered list of `oh-my-opencode-*` or `oh-my-openagent-*` platform package candidates, then spawns the first installed package's generated `bin/oh-my-opencode.js` launcher. Each generated Node launcher runs root `dist/cli` with Bun and, when Bun is missing or exits with `SIGILL`, falls back to root `dist/cli-node` with Node. The root shim retains ordered package fallback compatibility, including x64 `-baseline` candidates, but current generated platform payloads are identical Node scripts, so a Bun `SIGILL` is normally handled inside the selected launcher rather than by switching to a baseline package.
20 
21## CONVENTIONS
22 
23- Keep this surface Node-compatible; the root shim and generated launcher payloads are plain Node scripts.
24- Preserve all five aliases. Alias-to-platform-family behavior is shared with `postinstall.mjs` and publish-time package rewrites.
25- Keep error output actionable: report the detected platform and the ordered package candidates.
26- Tests run from the root with `bun test bin` or as part of `bun test`.
27 
28## ANTI-PATTERNS
29 
30- Do not import adapter source from `packages/omo-opencode/src/`; this shim must remain usable from the published package layout.
31- Do not hard-code one npm package family. `oh-my-opencode` and `oh-my-openagent` wrappers share the launcher.
32- Do not edit generated launcher payloads under `packages/oh-my-opencode-*/bin/`; regenerate them through `script/build-binaries.ts`.
33- Do not remove baseline fallback without updating platform tests and publish-platform coverage.
34