Skip to content

Latest commit

 

History

History
72 lines (65 loc) · 5.83 KB

desktop-terminal-command.md

File metadata and controls

72 lines (65 loc) · 5.83 KB

Desktop-owned terminal command

How OpenCodex Desktop puts its bundled ocx first on the user's PATH, how it records what it owns, and what it refuses to touch. The shell surrounding this feature (startup sequence, tray, update page) is described in Desktop shell; design history is in devlog/_fin/261009_desktop_owned_path_cli/.

desktop/src-tauri/src/cli_command.rs schedules one blocking reconcile after launch-origin adoption, independently of proxy startup. Stable macOS apps, Windows installs and Linux deb installs configure the command by default; off survives launch and removal. AppImage, temporary, translocated, debug and unpackaged launches do not install it.

desktop/src-tauri/src/cli_command_record.rs owns the private .opencodex-desktop/cli.json record (64 KiB cap), OS-backed lock and external pending journals with before/after digests. The record grants generated-file ownership only, never runtime, service or shutdown authority. Lock acquisition is nonblocking and excludes a second open in the same process. An owning guard explicitly unlocks before closing, including on failed opens: Unix releases the shared file description with LOCK_UN; Windows releases offset 0, length 1 with UnlockFileEx. An enabled record carries a validated host-platform bundle even on its first pending save; disabled intent wins over pending work. Invalid records and journal conflicts block mutation; unreferenced journals are deleted only under the lock after a valid (or absent) record read. Every private path must be user-owned without extended ACLs (macOS/Linux) or carry a protected user/SYSTEM/Administrators DACL (Windows root; children inherit it), otherwise nothing is written. Atomic replacement flushes and closes its write handle before publishing the new file by rename, so the published executable is never held open for writing by the replacing thread. desktop/src-tauri/src/process_spawn.rs owns a production process-wide Unix read/write gate. Executable atomic writes take it exclusively before opening the temporary file and release it after closing and publishing; ordinary record and rc writes do not take it. Process creation takes a shared guard through exec, so no child inherits the writable executable descriptor. Closing only the parent's close-on-exec descriptor would leave a forked duplicate writable until that child's exec. The same guard covers runtime start (sidecar.rs), resolve, claim and stop output futures, macOS launchctl/plutil probes (login_registration.rs), browser and Login Items launchers, updater install helpers and app restart. Shell-plugin output futures take the guard while being polled, including the initial synchronous spawn, and release it before yielding; waiting for output never retains a guard. The configured LaunchAgent registration and Linux autostart write files without spawning commands. Windows uses the same call sites without a lock. Rust fixture writers and spawners use this production mechanism too; tests cover exclusion in both directions, spawn errors and async Pending release. A queued writer permits further spawns until existing launchers finish, avoiding deadlock when a plugin waits for a main-thread callback that launches another process. Only an active writer blocks spawns.

desktop/src-tauri/src/cli_command_posix.rs generates a fail-closed shim, shared PATH helper and final managed zsh/bash/fish blocks. Reconcile separates desired rc targets from recorded ownership; remove walks the recorded list and preserves modified blocks and unsafe files. An rc file with an ACL is never rewritten (rc-acl-present). The shim captures exported Anthropic slot names with an argv-bound random proof before dotenv; failure keeps stripping. Persistent bundle registration rejects raw and canonical locations under system and OS temporary directories. A caller-selected TMPDIR counts only when it resolves inside a recognized temporary root or a shared sticky directory, so ordinary /Applications and user Applications bundles remain eligible even beneath a custom temporary-directory override.

desktop/src-tauri/src/cli_command_windows.rs preserves raw HKCU Path text/type, changes only the owned entry and broadcasts Environment; a top-level notifyPending debt survives crashes and removal until a broadcast succeeds. Machine-Path conflicts are partial; open shells unobserved.

The tray and desktop-only dashboard entry beside Desktop update open desktop/ui/cli.html; desktop/ui/cli.js renders only the newest status or action response and never sends a path. gui/src/lib/desktop-shell.ts selects the platform's exact app origin. Four path-free commands are guarded by the main window's local CLI page; Back uses return_to_dashboard, guarded for the update and CLI pages, falling back to the startup page when no dashboard is ready. Removal saves off first. Configuration cannot enforce selection against aliases or later PATH edits.

For eligible POSIX npm/pnpm calls, src/lib/desktop-cli-handoff.mjs keeps a settled, enabled Desktop selection even when the target disappears: validation fails with target-unusable, and a synchronous or asynchronous spawn failure returns spawn-failed. Neither failure resumes package/Bun execution. Repair the Desktop command, disable it, or explicitly use OCX_NO_DESKTOP_HANDOFF=1 for a package invocation. Missing/disabled records, maintenance exclusions and Windows PATH selection retain their existing behavior. The launcher's SIGINT/SIGTERM/SIGHUP forwarders (src/lib/launcher-signal-forwarding.mjs) are installed before the Desktop target or the Bun child is spawned. A signal that arrives once the child has started, even before spawn() returns, therefore reaches that child; it cannot kill the launcher by default action and orphan the child while the sync mutex stays held. tests/cli/ocx-launcher-desktop-handoff.test.ts exercises refusal and restored-target handoff.