Problem
Bringing the project up from a fresh clone is currently a multi-step, easy-to-fumble sequence spread across the README (build backend, start daemon, then a separate frontend install/approve/dev). A couple of footguns make it worse for new users:
- The frontend needs
pnpm approve-builds before pnpm dev will launch. A plain pnpm install prints Ignored build scripts: electron, electron-winstaller and does not download the Electron runtime (node_modules/electron/dist/ is absent), so electron-forge start fails. This is non-obvious.
frontend/pnpm-workspace.yaml tries to pre-approve this via allowBuilds: electron: true, but allowBuilds is not a valid pnpm key (the real one is onlyBuiltDependencies). pnpm silently ignores it, so the manual approve step is still required. Worth fixing that key as part of this, or documenting why the manual step stays.
Proposal
Add a one-liner bootstrap script runnable as:
that takes a fresh checkout to a running app end to end:
- Build the backend:
cd backend && go build -o /tmp/ao ./cmd/ao (or a repo-local bin path).
- Start the daemon:
/tmp/ao start and wait for /readyz.
- Frontend deps:
cd frontend && pnpm install.
- Approve Electron's build script (the step plain
pnpm install skips).
- Launch:
pnpm dev.
The interactive snag to handle
pnpm approve-builds is interactive — it opens a prompt to tick which packages may run scripts, so it needs a TTY and can't be dropped into a non-interactive script as-is. The script should use a non-interactive equivalent instead. Verified working option:
pnpm rebuild electron # runs electron's postinstall; downloads dist/Electron.app
(or fix frontend/pnpm-workspace.yaml to use onlyBuiltDependencies: [electron, electron-winstaller] so the build is approved at install time and no extra step is needed).
Notes
- Prereqs to check/document up front: Go 1.25+, pnpm,
zellij on PATH, gh/GITHUB_TOKEN for the SCM observer.
- The daemon binds
127.0.0.1:3001 by default and fails fast if the port is taken — the script should surface that clearly if a daemon is already running.
pnpm dev does not start the daemon; the script ordering (daemon first) matters.
All of the above (the ignored-build-scripts behavior, the dead allowBuilds key, and the pnpm rebuild electron fix) was verified locally on pnpm 10.11.1.
Problem
Bringing the project up from a fresh clone is currently a multi-step, easy-to-fumble sequence spread across the README (build backend, start daemon, then a separate frontend install/approve/dev). A couple of footguns make it worse for new users:
pnpm approve-buildsbeforepnpm devwill launch. A plainpnpm installprintsIgnored build scripts: electron, electron-winstallerand does not download the Electron runtime (node_modules/electron/dist/is absent), soelectron-forge startfails. This is non-obvious.frontend/pnpm-workspace.yamltries to pre-approve this viaallowBuilds: electron: true, butallowBuildsis not a valid pnpm key (the real one isonlyBuiltDependencies). pnpm silently ignores it, so the manual approve step is still required. Worth fixing that key as part of this, or documenting why the manual step stays.Proposal
Add a one-liner bootstrap script runnable as:
that takes a fresh checkout to a running app end to end:
cd backend && go build -o /tmp/ao ./cmd/ao(or a repo-local bin path)./tmp/ao startand wait for/readyz.cd frontend && pnpm install.pnpm installskips).pnpm dev.The interactive snag to handle
pnpm approve-buildsis interactive — it opens a prompt to tick which packages may run scripts, so it needs a TTY and can't be dropped into a non-interactive script as-is. The script should use a non-interactive equivalent instead. Verified working option:pnpm rebuild electron # runs electron's postinstall; downloads dist/Electron.app(or fix
frontend/pnpm-workspace.yamlto useonlyBuiltDependencies: [electron, electron-winstaller]so the build is approved at install time and no extra step is needed).Notes
zellijon PATH,gh/GITHUB_TOKENfor the SCM observer.127.0.0.1:3001by default and fails fast if the port is taken — the script should surface that clearly if a daemon is already running.pnpm devdoes not start the daemon; the script ordering (daemon first) matters.All of the above (the ignored-build-scripts behavior, the dead
allowBuildskey, and thepnpm rebuild electronfix) was verified locally on pnpm 10.11.1.