Repository navigation
Description
CookieMonster system CLI installer plan
Status
Planning document only. None of this behavior is implemented yet.
Goal
Install CookieMonster and a terminal-visible opencode command in one installer flow on Windows and macOS. Open Design must not require a second software installation after the temporary WPP administrator password expires.
WPP SSO remains a separate, unprivileged first-launch step. The installer must not store WPP cookies, passwords, or tokens.
Scope
This plan covers:
- CookieMonster-branded Windows NSIS installers.
- CookieMonster-branded macOS PKG installers.
- CLI installation, command discovery, upgrades, repair, and removal.
- Packaging configuration, CI artifacts, and native installer smoke tests.
- The boundary between privileged software installation and later WPP SSO.
This plan does not change:
- Upstream OpenCode
betaorproddesktop installers. - Linux packaging.
- The WPP bridge protocol or model roster.
- The CLI executable itself.
Current state
packages/desktop/scripts/prebuild.tsdownloads the platform CLI whenOPENCODE_CHANNEL=dev.packages/desktop/scripts/utils.tswritesresources/opencode-cliorresources/opencode-cli.exe.packages/desktop/electron-builder.config.tsincludes that binary as an unpacked resource fordev.- CookieMonster CI sets
OPENCODE_CHANNEL=dev,CM_BRAND=1, andCM_UNSIGNED=1. packages/desktop/src/main/background-cli.tsstages a private copy under ElectronuserData.- That private copy is not on
PATH, so Open Design cannot discover it asopencode. - Windows ships an NSIS
.exe. - macOS ships a drag-and-drop
.dmg. - Preload exposes an
install-clirequest, but main does not register the matching IPC handler.
Required behavior
After installation:
opencode --versionworks in a newly opened terminal.- The command resolves to the CLI bundled with the installed CookieMonster release.
- CookieMonster continues to use its private sidecar path, independent of shell
PATH. - Upgrades replace the CLI without duplicating command registration.
- Uninstall removes only command registration owned by CookieMonster.
- Existing unrelated OpenCode installations are never deleted.
- CLI registration failure prevents the installer from reporting success.
- No WPP secrets are copied into the CLI installation.
CookieMonster must still be running when Open Design sends WPP-backed requests because the provider uses the local bridge at 127.0.0.1:8787.
Shared packaging
Keep resources/opencode-cli and resources/opencode-cli.exe for the desktop sidecar. Add an installer-facing copy named as the public command:
| Platform | Packaged path |
|---|---|
| Windows | resources/cli/opencode.exe |
| macOS | Contents/Resources/cli/opencode |
Both copies must come from the same downloaded artifact. Do not download the CLI twice.
Update packages/desktop/scripts/utils.ts and packages/desktop/scripts/prebuild.ts to:
- Produce both names for branded builds.
- Verify that they are byte-identical before platform signing.
- Preserve executable mode on macOS.
- Fail prebuild if either required output is missing.
Update packages/desktop/electron-builder.config.ts to include the public CLI only when CM_BRAND=1. Introduce one packaging-time branded boolean derived from CM_BRAND; do not use OPENCODE_CHANNEL=dev as a branding test because upstream development builds use that channel too.
Use narrow ownership rules:
- Windows owns only its exact user
PATHentry for the installedresources\clidirectory. - macOS owns
/usr/local/bin/opencodeonly when it is a symlink to a CookieMonster app CLI path. - Neither installer may remove a regular file, another application's symlink, or an unrelated
PATHentry.
Windows implementation
Installation layout
Keep the existing per-user NSIS installation:
- Application: the existing
$INSTDIR. - Public CLI:
$INSTDIR\resources\cli\opencode.exe. - User
PATHentry:$INSTDIR\resources\cli.
Do not switch nsis.perMachine to true unless WPP deployment policy explicitly requires a machine-wide installation. A per-user app and HKCU PATH entry preserve the current update model and do not require machine-wide environment changes.
The NSIS installer must perform desktop and CLI installation in one run. CLI installation must not be deferred to first app launch.
NSIS integration
Add packages/desktop/resources/windows/cli-install.nsh.
Set nsis.include to this file only for CookieMonster-branded builds. Implement Electron Builder's NSIS extension macros:
customInstallcustomUnInstall
customInstall must:
- Verify
$INSTDIR\resources\cli\opencode.exeexists. - Execute
opencode.exe --versionand require exit code zero. - Read the current user
PATHfromHKCU\Environment. - Parse
PATHas semicolon-delimited entries. - Compare entries case-insensitively after normalizing quotes and trailing separators.
- Prepend
$INSTDIR\resources\clionly when the exact normalized entry is absent. - Write the updated value as
REG_EXPAND_SZ. - Broadcast
WM_SETTINGCHANGEforEnvironment. - Abort installation with a clear message if validation or registry update fails.
Do not use substring matching. For example, C:\CookieMonster-old\resources\cli must not count as the current entry.
customUnInstall must:
- Read the current user
PATH. - Remove only the exact normalized
$INSTDIR\resources\clientry. - Preserve every unrelated entry and its order.
- Delete the registry value only if it becomes empty.
- Broadcast
WM_SETTINGCHANGE.
Electron Builder removes the CLI binary with the rest of $INSTDIR; the custom uninstall hook owns only PATH cleanup.
Existing OpenCode commands
Prepending CookieMonster's directory makes its compatible CLI win in new processes while CookieMonster is installed. Do not delete another opencode.exe.
If another installation has an identical command earlier in a process's inherited environment, diagnostics must report it. A newly opened terminal should use the updated user PATH.
After CookieMonster is uninstalled, removing its exact entry restores the previous command resolution.
Upgrades
NSIS upgrades reuse $INSTDIR:
- Electron Builder replaces
resources\cli\opencode.exe. customInstallsees the existing exactPATHentry and does not duplicate it.- The command changes version with the app.
- The old app-owned executable disappears through normal installer replacement.
Repair action
Restore the missing install-cli IPC handler as an optional repair path, not as the primary installation flow.
The handler may:
- Verify that the packaged public CLI exists.
- Restore the current user's exact
PATHentry. - Broadcast the environment change.
- Return the installed command path.
It must reject unpackaged or unbranded builds unless separate development behavior is explicitly designed.
Windows tests
Add unit tests for pure PATH transformations:
- Empty
PATH. - Entry absent.
- Entry already present.
- Different casing.
- Quotes and trailing separator differences.
- Similar prefix that is not the same entry.
- Duplicate owned entries collapse to one on install and zero on uninstall.
- Uninstall preserves unrelated entries and order.
Extend packages/desktop/electron-builder.config.test.ts to assert:
- Branded Windows builds include
resources/cli/opencode.exe. - Branded Windows builds set
nsis.include. - Unbranded builds do not include the custom installer hook.
- Existing signing and unsigned behavior remains unchanged.
Add a Windows CI smoke test:
- Save the runner user's original
PATH. - Run the NSIS installer silently.
- Start a new PowerShell process so it reloads the user environment.
- Assert
Get-Command opencoderesolves inside CookieMonster's install directory. - Assert
opencode --versionexits successfully. - Run the uninstaller silently.
- Start another PowerShell process.
- Assert CookieMonster's exact
PATHentry is gone. - Assert unrelated
PATHentries are unchanged.
macOS implementation
Add a PKG installer
A DMG cannot reliably perform privileged command registration. Add a CookieMonster .pkg artifact and make it the supported installer for Open Design.
Configure the branded macOS build with:
- Electron Builder's
pkgtarget. - Install location
/Applications. - App path
/Applications/CookieMonster.app. - Relocation disabled.
- Installation outside
/Applicationsdisabled. - Scripts directory
packages/desktop/resources/macos/pkg-scripts.
The existing DMG may remain for one transition release, but it must be described as app-only because it does not satisfy the Open Design CLI prerequisite.
PKG postinstall
The package contains:
/Applications/CookieMonster.app/Contents/Resources/cli/opencode
Add an executable packages/desktop/resources/macos/pkg-scripts/postinstall script. It must:
- Use absolute paths and
set -eu. - Verify the bundled CLI exists and is executable.
- Run the bundled CLI with
--versionand require exit code zero. - Create
/usr/local/binwith mode0755only when it does not exist. - Leave an existing
/usr/local/bindirectory's owner and mode unchanged. - Inspect
/usr/local/bin/opencodebefore changing it. - Replace the link when it points to CookieMonster's current or known legacy bundled CLI path.
- Create the new symlink atomically.
- Fail with an actionable installer error when the destination is a regular file or a symlink owned by another installation.
- Never edit
.zshrc,.zprofile,.bashrc, or another user's home directory.
Using /usr/local/bin avoids guessing the logged-in user's home while the PKG script runs as root. Verify during macOS acceptance testing that WPP's supported terminal and Open Design environments include /usr/local/bin.
Existing OpenCode commands
Do not silently overwrite an unrelated /usr/local/bin/opencode.
The installer should stop and tell the user to remove or relocate the existing command, then rerun the same PKG while temporary administrator access is still active. This is safer than replacing an unknown Homebrew, npm, or manual installation.
A user-level ~/.opencode/bin/opencode may still take precedence depending on shell configuration. Add diagnostics for all discovered command paths and document command -v -a opencode. Do not edit shell profiles from the PKG.
Upgrades
PKG upgrades reinstall the app at the fixed /Applications/CookieMonster.app path:
- App replacement updates the bundled CLI.
- The symlink target remains stable.
postinstallvalidates and recreates the link idempotently.- No shell profile or
PATHmutation is required.
Removal
macOS packages do not receive an automatic uninstall hook when a user drags an app to Trash.
Add packages/desktop/scripts/uninstall-macos-cli.sh for IT and support. It must remove /usr/local/bin/opencode only if the link points inside /Applications/CookieMonster.app. It must leave regular files and unrelated links untouched.
Document the supported full removal sequence:
- Run the CLI cleanup script with administrator authorization.
- Remove
/Applications/CookieMonster.app. - Optionally forget the package receipt if IT policy requires it.
If the app is deleted without cleanup, the remaining symlink is dangling but contains no executable code. A later PKG installation repairs it.
Launch and WPP SSO
Do not launch the app as root from postinstall.
The PKG conclusion page should tell the user to open CookieMonster and complete WPP SSO. CLI installation is complete at that point, so the temporary administrator credential is no longer needed.
CookieMonster must be running whenever Open Design uses the WPP-backed provider. First launch writes the provider configuration and starts the local bridge.
macOS tests
Extend packages/desktop/electron-builder.config.test.ts to assert:
- Branded macOS builds include
pkg. - PKG install location is
/Applications. - PKG relocation is disabled.
- PKG scripts point to the checked-in scripts directory.
- Unbranded builds retain their existing targets and behavior.
Add shell-level tests for link ownership decisions:
- Missing destination.
- Existing CookieMonster-owned symlink.
- Known legacy CookieMonster symlink.
- Dangling CookieMonster-owned symlink.
- Symlink to another installation.
- Existing regular file.
- Missing bundled CLI.
- Non-executable bundled CLI.
Add a macOS CI smoke test:
- Install the PKG with
sudo installer -pkg ... -target /. - Assert
/Applications/CookieMonster.appexists. - Assert
/usr/local/bin/opencoderesolves to the app's bundled CLI. - Assert
/usr/local/bin/opencode --versionexits successfully. - Install the same PKG again and assert the operation is idempotent.
- Run the cleanup script.
- Assert the symlink is removed without modifying unrelated files.
Application integration
The system command and desktop sidecar serve different entry points but use the same CLI build:
- Keep
startBackgroundCli()onopencode-cli(.exe)so desktop startup is independent of shellPATH. - Keep WPP provider configuration in
proxy/providerConfig.mjs. - Continue writing CookieMonster provider configuration on app boot.
- Do not embed bridge credentials in the installed CLI or global config.
- Keep the bridge bound to loopback.
Add non-fatal startup diagnostics for:
- Bundled CLI version.
- Expected public command path.
- Whether registration is correct.
- Whether another
opencodeshadows CookieMonster.
A registration problem must not prevent CookieMonster from starting. It should be visible in diagnostics and repairable.
CI and release
Update .github/workflows/cookiemonster-desktop.yml to:
- Build PKG on macOS, optionally retaining DMG for one transition release.
- Upload
.pkgartifacts. - Include
.pkgin release assets. - Run native Windows and macOS installation smoke tests before upload.
- Keep
CM_BRAND=1,CM_UNSIGNED=1, andOPENCODE_CHANNEL=dev. - Keep each installer on its native runner.
Update internal installation guidance:
- Windows users run the
.exe. - macOS Open Design users run the
.pkg, not the.dmg. - Both installers include the CLI.
- Windows users open a new terminal after installation.
- Users launch CookieMonster and complete WPP SSO before using Open Design.
- CookieMonster must remain running for WPP-backed requests.
- Unsigned builds still trigger SmartScreen or Gatekeeper warnings.
Expected file changes
| File | Change |
|---|---|
packages/desktop/scripts/utils.ts |
Produce internal and public CLI resource names from one download |
packages/desktop/scripts/prebuild.ts |
Require both CLI outputs in branded builds |
packages/desktop/electron-builder.config.ts |
Gate public resources, NSIS include, and PKG settings behind CM_BRAND |
packages/desktop/resources/windows/cli-install.nsh |
Register and unregister the Windows command |
packages/desktop/resources/macos/pkg-scripts/postinstall |
Register /usr/local/bin/opencode |
packages/desktop/scripts/uninstall-macos-cli.sh |
Remove only the CookieMonster-owned symlink |
packages/desktop/src/main/system-cli.ts |
Diagnostics and optional repair logic |
packages/desktop/src/main/ipc.ts |
Restore the install-cli repair handler |
packages/desktop/electron-builder.config.test.ts |
Assert branded and upstream package separation |
packages/desktop/src/main/system-cli.test.ts |
Test path and ownership decisions |
.github/workflows/cookiemonster-desktop.yml |
Build, smoke-test, upload, and release new artifacts |
AGENTS.md |
Update packaging commands and artifact guidance |
Implementation order
- Refactor CLI preparation to emit both resource names.
- Add branded packaging guards and configuration tests.
- Implement and test Windows
PATHregistration. - Add NSIS install and uninstall hooks.
- Implement and test macOS link ownership.
- Add PKG postinstall and support cleanup scripts.
- Restore or replace the stale repair action.
- Add native installer smoke tests.
- Update release artifact selection and documentation.
- Complete manual Open Design acceptance testing.
Manual acceptance
Run on clean Windows and macOS test machines:
- Start the temporary WPP administrator window.
- Run exactly one CookieMonster installer.
- Confirm the installer reports success only after CLI registration succeeds.
- Open a new terminal.
- Run
opencode --version. - Launch CookieMonster.
- Complete WPP SSO.
- Confirm
http://127.0.0.1:8787/bridge/healthreports healthy. - Confirm the CookieMonster provider and
CM_*models appear. - Launch Open Design and verify it discovers
opencode. - Run one Open Design request through a
CM_*model. - Upgrade CookieMonster and verify the command version changes without another registration entry.
- Uninstall and verify only CookieMonster-owned command registration is removed.
Repeat with:
- A previous CookieMonster version installed.
- An unrelated
opencodealready installed. - An installation path containing spaces.
- A non-admin user who receives temporary elevation.
- Apple Silicon and Intel macOS artifacts when both architectures are distributed.
- Windows x64 and ARM64 artifacts when both architectures are distributed.
Completion criteria
- Windows installs the app and discoverable CLI in one NSIS run.
- macOS installs the app and discoverable CLI in one PKG run.
- No first-launch elevation is needed.
- Upgrade and removal ownership tests pass.
- Native CI runs the installed CLI successfully.
- Open Design completes an end-to-end WPP-backed request on both platforms.
- Packaging is unchanged when
CM_BRANDis absent.
Activity
trmosala commentedon Sep 22, 2026
Implemented the remaining macOS ownership/validation changes and pushed 0b12470 on sqlite-lock-probe. macOS is now the sole CookieMonster release target. Windows/Linux implementation remains in source for compatibility but is not built by this workflow.
Changes:
Local macOS validation: ownership shell tests PASS; packaging configuration 12 pass / 65 expectations; full desktop suite 569 pass, 4 skips, 0 failures / 4,003 expectations; desktop typecheck and shell syntax checks PASS. Formatting passed for workflow/support documentation, with existing unrelated AGENTS.md formatting differences left untouched. Two-axis source review cleared implementation; its documentation mismatch was corrected. Normal push hook: 31 typechecks successful, 30 cached.
Native CI validation attempted without release publication: https://github.com/trmosala/opencode/actions/runs/35688756323
GitHub refused to start the macOS job: “recent account payments have failed or your spending limit needs to be increased.” No package build/install validation or release occurred. The local installed CookieMonster app was not replaced or restarted.
Keeping #4 open for the native PKG install/reinstall/discovery/removal evidence once Actions billing is restored. The owner explicitly chose to retain live Open Design/WPP end-to-end verification as documented manual acceptance; that check is not claimed complete.
trmosala commentedon Sep 22, 2026
Local macOS release validation completed at
cc308d72f3after GitHub Actions capacity was exhausted.Built locally with the workflow's production settings:
CM_BRAND=1,CM_UNSIGNED=1, andOPENCODE_CHANNEL=prod. Electron Builder explicitly skipped signing and notarization and produced arm64 PKG, DMG, and ZIP artifacts for CookieMonster 1.18.27.Validation completed:
com.ogilvy.cookiemonster, arm64 app/CLI/native-entry binaries, bundled browser/AE plugins, byte-identical public/private CLI, native helper present./Applications, verified the removal state, and reinstalled the PKG. The final app remains installed and running./usr/local/bin/opencodepoints to/Applications/CookieMonster.app/Contents/Resources/cli/opencode; a fresh login shell resolves that path;opencode --versionreturnsopencode2 v0.0.0-next-16350./healthand/bridge/healthreport healthy, and/v1/modelsadvertises the CookieMonster model roster. A stale orphaned Electron 42 crash handler from the replaced build was terminated.Artifacts:
f02d757b255b86f3ceef7df36bb5ce1a2596ec641f126e9ebe60f40b7358b3cbca21c2e4589a1e05bc97671d6c90ddfea244eeaca7c3137c231530b71a88f5a64c11227d3abd84220d66914651bbf0c89317a43d1507b0c672bfdcfbb4fcbb9bmacOS is the sole CookieMonster release target. Windows/Linux requirements in the original planning body are historical. The owner-selected live Open Design request through WPP remains documented manual acceptance and is not claimed by this automated/native evidence.