@frontendxlab/opencode-computer-use 0.1.4 → 0.1.5

package/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+## 0.1.5 — 2026-10-30
+
+### Setup and discovery
+
+- Register a development checkout with `opencode-computer-use-setup --source .`.
+- Use backed-up JSON/JSONC edits for both global and local setup instead of
+  assuming a particular OpenCode plugin-management subcommand.
+- Reject invalid JSONC and conflicting V1/V2 configurations before writing.
+- Preserve pinned npm entries, avoid duplicate registration across configuration
+  files, retain options when switching to a checkout, and preserve backups on
+  unchanged runs.
+- Return failure for unsuccessful manual setup while keeping dependency
+  postinstall best-effort.
+- Recognize Windows executable/environment-name conventions and resolve npm
+  native-runtime shims without invoking a shell for desktop control.
+- Include guided desktop prerequisite onboarding when lifecycle scripts run.
+
+### Runtime fixes
+
+- Enforce an empty deny-by-default app policy before native app binding.
+- Emit filtered `getState()` and `listApps()` inventories by default and honor
+  `emit: false` without exposing denied apps.
+- Handle native stdio failures as controlled transport errors and clean up the
+  owned child process.
+- Parse executable import syntax instead of rejecting the word `import` inside
+  typed text, strings, comments, regexes, and ordinary property names. Executable
+  imports and the existing VM restrictions remain blocked.
+- Make REPL `--help` exit without starting native automation, and report startup
+  configuration failures without an uncaught stack trace.
+
+### Verification and documentation
+
+- Add regressions for the setup, policy, inventory, transport, import, and CLI
+  failures above.
+- Add an opt-in real OpenCode smoke test with isolated settings and fake/native
+  startup modes, plus a Linux/macOS/Windows CI integration job pinned to 1.19.3.
+- Document checkout installation, correct scoped npm executable commands,
+  registration troubleshooting, per-device installation, and server-host scope.
+- Correct WebMCP API-reference lookups for method names with signatures.
+
+### Support boundaries
+
+The adapter controls the desktop of the machine running its local MCP process.
+This release does not add remote device pairing, a network transport, or mobile
+native runtimes. Linux x64 registration, read-only discovery, and semantic click
+and text-value actions in a disposable GTK fixture are exercised locally.
+Screenshots were unavailable in the tested GNOME Wayland session. Packaged
+macOS/Windows runtimes still require live desktop validation;
+headless adapter or CLI tests do not certify screenshot/input behavior. Wayland
+capture and synthetic input remain dependent on the compositor and target app.

package/README.md

@@ -3,6 +3,9 @@
 A dual-generation OpenCode plugin that provides a Codex-style Computer Use
 session.
 
+It registers a local MCP server named `cua_repl` with two tools, `js` and
+`js_reset`. It does not add a slash command or a dedicated OpenCode panel.
+
 Documentation: https://opencode-computer-use.pages.dev/
 
 The model does not receive a pile of low-level desktop MCP tools. It receives a
@@ -51,25 +54,34 @@ The optional `open-computer-use@0.3.5` package ships native runtimes for:
 - `linux-arm64`, `linux-x64`
 - `win32-arm64`, `win32-x64`
 
-The current project has been exercised against the Linux runtime contract. macOS
-and Windows support is provided by the upstream native packages, but live
-permission and desktop validation must still be run on those operating systems.
+The repository CI is configured to test the adapter headlessly on Linux, macOS,
+and Windows through a GitHub Actions matrix. The native package publishes binaries for the six targets
+above. Live accessibility, capture, focus, and input behavior still depends on
+the host desktop session and must be validated on each operating system.
 
 ### Validation status
 
-- Linux x64 native discovery, read-only app listing, MCP registration, and the
-  persistent JavaScript session have passed local smoke tests.
-- The current Ubuntu/GNOME Wayland session exposed a Chrome pseudo-window whose
-  AT-SPI tree had no actionable children. The native Linux runtime accepted
-  coordinate and keyboard requests, but those synthetic events did not change
-  that window. The adapter reports the native result rather than claiming that
-  an unsupported input path worked.
-- macOS and Windows have not been live-tested in this environment. Their
-  accessibility, screen-capture, foreground, and OS permission behavior must be
-  verified on those operating systems.
-
-The Codex-style surface is portable, but the native runtime's desktop
-capabilities remain OS and session dependent.
+- The JavaScript adapter, MCP registration, sandbox, timeout recovery, setup,
+  packaging, and fake-native integration suite are designed to run on Linux,
+  macOS, and Windows without a graphical desktop.
+- Linux x64 native discovery, app listing, actual OpenCode 1.19.3 registration,
+  persistent JavaScript bindings, and session reset passed local smoke tests.
+- On 2026-10-30, a disposable GTK 3 window in Ubuntu/GNOME Wayland exposed an
+  actionable accessibility tree. An element-index click changed its counter
+  from 0 to 1, and `setValue` changed its text field; both results were checked
+  against fresh accessibility state and the test application's own state.
+- Screenshot capture for that window returned `Screenshot unavailable`.
+  Keyboard/coordinate input was not certified. Other apps may expose incomplete
+  accessibility trees, and Wayland capture/input behavior remains app- and
+  compositor-dependent. See the dated record in `docs/NATIVE_VALIDATION.md`.
+- macOS and Windows native desktop behavior has not been live-certified from
+  this development machine. Their accessibility, screen-capture, foreground,
+  and OS permission behavior must still be verified on real interactive hosts.
+
+The Codex-style surface is portable across the published x64/ARM64 desktop
+targets, but native desktop capabilities remain OS, permission, display-server,
+and session dependent. Other CPU/OS combinations fail with an explicit target
+diagnostic and can use a compatible custom backend.
 
 ## Requirements
 
@@ -81,9 +93,34 @@ capabilities remain OS and session dependent.
 - Linux AT-SPI and the input/capture services required by the native runtime.
 - Windows UI Automation in the current interactive desktop session.
 
+The V1 integration has been exercised with OpenCode 1.19.3. The V2 entrypoint
+has adapter contract tests; a real OpenCode2 installation remains a separate
+integration check. A native runtime's successful `doctor` exit is a prerequisite
+check, not proof that screenshots, focus, or input work in a particular app.
+
 The plugin cannot control a lock screen, login screen, UAC secure desktop, or
 other OS-owned consent surface. It does not bypass permissions.
 
+## Which computer is controlled?
+
+The controlled desktop belongs to the machine running the OpenCode **server
+and its MCP child process**. There is no built-in device discovery, pairing,
+remote desktop transport, or session synchronization.
+
+| Setup | Desktop controlled |
+| --- | --- |
+| OpenCode runs on computer A | Computer A's signed-in graphical session. |
+| A browser or attached OpenCode client on B connects to the server on A | Still computer A. |
+| Install and run OpenCode plus this plugin separately on B | Computer B, after its own runtime and permission checks. |
+| Copy a configuration containing A's absolute paths to B | Paths must be re-created for B; configuration alone does not install the runtime. |
+
+Cross-platform support means separate installations on the packaged macOS,
+Linux, and Windows targets. Android and iOS are not native targets. Containers,
+WSL, SSH sessions, and background services do not automatically expose another
+machine's or the host operating system's interactive desktop. A custom backend
+must implement the native protocol; selecting `custom` does not add remote
+device support by itself.
+
 ## Install
 
 The published package is `@frontendxlab/opencode-computer-use`. It registers a
@@ -102,12 +139,18 @@ When both generations are installed, it uses an existing `plugin` or `plugins`
 configuration to disambiguate. If that is not possible, it makes no change and
 prints both manual configuration formats.
 
+Both local and global setup use a backed-up JSON/JSONC edit. Setup does not
+depend on a version-specific `opencode plugin add` command. A project install
+affects that project; use `--global` to configure all projects for the current
+user. Package installation and OpenCode registration are separate steps when
+lifecycle scripts are disabled.
+
 You can run setup explicitly at any time:
 
 ```sh
-npx opencode-computer-use-setup
-npx opencode-computer-use-setup --local --v2
-npx opencode-computer-use-setup --global --v1
+npm exec --package=@frontendxlab/opencode-computer-use -- opencode-computer-use-setup --local --v1
+npm exec --package=@frontendxlab/opencode-computer-use -- opencode-computer-use-setup --local --v2
+npm exec --package=@frontendxlab/opencode-computer-use -- opencode-computer-use-setup --global --v1
 ```
 
 Use `--dry-run` to inspect the action without changing files. Set
@@ -115,21 +158,30 @@ Use `--dry-run` to inspect the action without changing files. Set
 skips automatically when `CI=1` or `CI=true`. Restart OpenCode after a
 successful setup so the plugin is loaded.
 
-The postinstall flow also runs the native permission check. To rerun it later:
+Explicit setup returns a nonzero exit status when it fails; automatic dependency
+`postinstall` remains best-effort and prints manual instructions. Check the
+reported configuration path. The shorthand `npx opencode-computer-use-setup`
+only selects this package's executable when it is already installed locally;
+the scoped `npm exec --package=...` form above also works from a fresh directory.
+
+Starting with v0.1.5, desktop prerequisite onboarding is part of `postinstall` when lifecycle scripts are allowed.
+After OpenCode configuration, the installer runs `opencode-computer-use-permissions --install`:
+
+- macOS runs the native `doctor` check and opens the Open Computer Use onboarding/System Settings when Accessibility or Screen Recording is missing. Apple still requires the user to click the protected privacy toggles.
+- GNOME Linux best-effort enables `org.gnome.desktop.interface toolkit-accessibility` and then runs the native AT-SPI/session check. Other Linux desktops get diagnostics without changing desktop settings.
+- Windows runs the UI Automation/session check. Windows has no separate UI Automation permission toggle; it must run in the signed-in interactive desktop session.
+
+Rerun the guided check at any time:
 
 ```sh
-npx opencode-computer-use-permissions
+npm exec --package=@frontendxlab/opencode-computer-use -- opencode-computer-use-permissions --strict
 # or, from a pnpm project
-pnpm exec opencode-computer-use-permissions
+pnpm exec opencode-computer-use-permissions --strict
 ```
 
-The command delegates to the native `open-computer-use doctor` flow. macOS runs
-the native Accessibility and Screen Recording onboarding when needed. Linux
-reports AT-SPI and desktop-session requirements. Windows reports UI Automation
-and interactive-session requirements. The command never changes permissions
-automatically. Use `--strict` when a missing or failed native
-check should return a nonzero exit status, or set
-`OPENCODE_COMPUTER_USE_SKIP_PERMISSIONS=1` to skip it.
+Set `OPENCODE_COMPUTER_USE_SKIP_PERMISSIONS=1` to skip install-time desktop onboarding.
+CI and package-development installs skip it automatically. The helper never bypasses macOS TCC,
+Windows secure desktops, or other OS permission boundaries.
 
 Recent pnpm releases may require explicit approval before running lifecycle
 scripts from dependencies. If pnpm reports `ERR_PNPM_IGNORED_BUILDS`, approve
@@ -142,8 +194,30 @@ pnpm install
 
 If scripts are intentionally disabled, run `pnpm exec opencode-computer-use-setup` manually instead.
 
-A local checkout can be loaded by replacing the package name with its absolute
-path.
+### Run this checkout
+
+Cloning this repository does not register it in OpenCode. A development
+`npm install` intentionally skips the automatic configuration and desktop
+onboarding hooks. Run these commands from the checkout:
+
+```sh
+npm ci --ignore-scripts
+node bin/opencode-computer-use-setup.js --local --v1 --source .
+node bin/opencode-computer-use-permissions.js --strict
+opencode mcp list
+```
+
+Close and reopen an already-running OpenCode session. The MCP list should show
+`cua_repl` as connected. To make this checkout available to all projects, replace
+`--local` with `--global`. For OpenCode2, select `--v2` and use that runtime's MCP
+status command. The `--source` flag accepts a directory, an entrypoint file, or
+a file URL and writes the canonical absolute `file://` URL. It requires this
+checkout's updated setup script; an older published package may not have it.
+
+The generated local `opencode.json` is machine-specific and ignored by this
+repository. Re-run setup on a second computer rather than copying its absolute
+path. Install dependencies on that computer; do not copy `node_modules` between
+operating systems or CPU architectures.
 
 ### OpenCode 1
 
@@ -233,6 +307,29 @@ syntax:
 The custom command must implement the native MCP operations used by `cua`:
 `initialize`, `tools/list`, `tools/call`, and notifications.
 
+If plugin loading is unavailable in your host version, the same REPL can also
+be registered directly as a local MCP server. Use exactly one registration:
+
+```json
+{
+  "mcp": {
+    "cua_repl": {
+      "type": "local",
+      "command": ["node", "/absolute/path/to/opencode-computer-use/bin/opencode-computer-use-repl.js"],
+      "environment": {
+        "OPENCODE_COMPUTER_USE_SAFETY_MODE": "read-only"
+      },
+      "enabled": true
+    }
+  }
+}
+```
+
+This example uses read-only mode for initial validation. Replace the path with
+the actual installed checkout path, and use an absolute Node path if the host
+cannot resolve `node`. Plugin options do not apply to a separately configured
+MCP server; use the matching environment variables in that case.
+
 ## Model workflow
 
 The `js` tool accepts:
@@ -272,6 +369,10 @@ The `cua` API includes:
 - `app.setValue(elementIndex, value)`
 - `app.performSecondaryAction(elementIndex, action)`
 
+`cua.getState()` and `cua.listApps()` emit the permitted app inventory by default.
+Use `{ emit: false }` when assigning it to a variable and writing your own output.
+Both the returned inventory and its visible output honor `appAccess` rules.
+
 Use `nodeRepl.write(value)` for text output and
 `await nodeRepl.emitImage(bytesOrDataUrl)` for screenshots or other images.
 
@@ -334,24 +435,50 @@ Policy, and a compatible browser or Cloudflare Browser Run lab session.
 Before asking an agent to act, run the native runtime's read-only checks:
 
 ```bash
-open-computer-use doctor
-open-computer-use list-apps
+npm exec --package=open-computer-use@0.3.5 -- open-computer-use doctor
+npm exec --package=open-computer-use@0.3.5 -- open-computer-use list-apps
 ```
 
 The first screenshot may trigger a desktop permission dialog. A screenshot,
 accessibility tree, or typed value can contain sensitive data and should stay
 local.
 
+## Troubleshooting registration and desktop access
+
+| Symptom | Check and remedy |
+| --- | --- |
+| No `cua_repl` in OpenCode | Run setup for the right project/global scope and generation, check its printed config path, then restart OpenCode and run `opencode mcp list`. A clone or dependency install by itself is not registration. |
+| Installed from npm but new fixes are missing | Compare `npm view @frontendxlab/opencode-computer-use version` with the checkout's `package.json`. Use `--source .` to test the checkout before publication. |
+| `--pure` / `OPENCODE_PURE` is enabled | OpenCode deliberately skips external plugins. Start it with plugins enabled. |
+| An existing `cua_repl` entry is disabled or points elsewhere | The plugin preserves that entry by default. Correct it, or explicitly use the plugin's `override: true` option after reviewing the replacement. |
+| `node` cannot be found | Set `OPENCODE_NODE` to the absolute Node executable in the environment that starts OpenCode. A desktop launcher may have a different `PATH` from a terminal. |
+| Native runtime unavailable | Install the optional `open-computer-use@0.3.5` dependency; check whether the package manager omitted optional packages. Run the permissions helper from the same graphical session. |
+| `cua_repl` connects but the app list is empty | Verify the signed-in desktop/session and accessibility prerequisites. An MCP handshake does not prove native app access. |
+| Linux actions return but the app does not change | Refresh accessibility state and verify the result. Wayland may block synthetic input or capture; prefer semantic AT-SPI actions when the app exposes them. |
+| Works on one computer but not another | Install on each supported desktop and re-run its permission/session checks. Absolute paths, environment, architecture, and app accessibility differ. |
+
+For Windows npm command shims, the backend resolves the adjacent packaged native
+`.exe` without invoking a shell. A nonstandard `.cmd`/`.bat` installation without
+that executable must use an absolute native `OPEN_COMPUTER_USE_NATIVE_COMMAND`.
+
 ## Development
 
 ```bash
-npm install
+npm ci --ignore-scripts
 npm test
 npm run lint
+npm run test:opencode
 ```
 
 The adapter tests use a fake native MCP server and never require a real desktop.
-Live desktop validation must be run separately on each supported OS.
+The repository CI is configured to run them on Linux, macOS, and Windows across
+the declared Node compatibility matrix. `test:opencode` additionally requires an
+installed OpenCode CLI and checks actual plugin registration/MCP startup in an
+isolated configuration with a fake native backend. Use `npm run test:opencode --
+--native` on an interactive host to check registration with its native backend.
+Neither smoke test sends desktop input. Live desktop validation remains a separate release check for native input,
+capture, focus, and accessibility behavior.
+Use `docs/NATIVE_VALIDATION.md` for the per-OS certification checklist.
 
 ## License and attribution
 

package/SECURITY.md

@@ -28,8 +28,12 @@ sandbox.
   conflicting or malformed configuration. Ambiguous setup is non-destructive
   and prints manual instructions. CI and explicit skip environments bypass
   postinstall mutation.
-- The permission command delegates to the native runtime's `doctor` flow. It
-  may open macOS onboarding, but it never grants or changes permissions.
+- Install-time permission onboarding is guided and best-effort. The postinstall
+  hook delegates to the native runtime's `doctor` flow. On macOS it may open
+  Accessibility/Screen Recording onboarding, but the protected TCC toggles still
+  require user approval. On GNOME Linux it may enable toolkit accessibility.
+  Windows only validates UI Automation/session requirements. The installer never
+  bypasses OS permission boundaries or grants protected permissions silently.
 
 ## Operator responsibilities
 

package/THIRD_PARTY_NOTICES.md

@@ -18,6 +18,10 @@ The automatic setup command uses `jsonc-parser@3.3.1`, copyright Microsoft
 Corporation and contributors, under the MIT license. It is used only to make
 targeted edits to OpenCode JSONC configuration files.
 
+The import-syntax guard uses `acorn@8.19.0` under the MIT license to parse
+JavaScript without executing it. Acorn's license is included in its separately
+installed dependency package.
+
 The adapter was changed to resolve the optional runtime package, use a
 minimal desktop environment allowlist, expose the session through the
 OpenCode plugin entrypoint, and run model code in a restricted VM context.

package/bin/opencode-computer-use-permissions.js

@@ -11,35 +11,84 @@ const SKIP_ENV = "OPENCODE_COMPUTER_USE_SKIP_PERMISSIONS";
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 
 function print(text, stream = "stdout") {
-  process[stream].write(`${text}\n`);
+  process[stream].write(String(text) + "\n");
 }
 
 export function usage() {
-  return `Usage: opencode-computer-use-permissions [options]
-
-Run the native Open Computer Use permission and runtime onboarding check.
-
-Options:
-  --strict       Return a failure when the native check cannot run
-  --help, -h     Show this help
-
-The command uses the installed open-computer-use runtime:
-  macOS   checks or launches Accessibility and Screen Recording onboarding
-  Linux   reports AT-SPI and signed-in desktop-session requirements
-  Windows reports UI Automation and interactive-session requirements
-`;
+  return [
+    "Usage: opencode-computer-use-permissions [options]",
+    "",
+    "Run the native Open Computer Use permission and runtime onboarding check.",
+    "",
+    "Options:",
+    "  --install      Guided install mode used by the package postinstall hook",
+    "  --strict       Return a failure when the native check cannot run",
+    "  --help, -h     Show this help",
+    "",
+    "The command uses the installed open-computer-use runtime:",
+    "  macOS   checks or launches Accessibility and Screen Recording onboarding.",
+    "          macOS still requires the user to approve protected TCC toggles.",
+    "  Linux   checks AT-SPI and the signed-in desktop session. On GNOME, install",
+    "          mode best-effort enables toolkit accessibility with gsettings.",
+    "  Windows checks UI Automation and the interactive signed-in desktop session.",
+  ].join("\n");
 }
 
 function parseArguments(argv) {
-  const options = { strict: false, help: false };
+  const options = { install: false, strict: false, help: false };
   for (const argument of argv) {
-    if (argument === "--strict") options.strict = true;
+    if (argument === "--install") options.install = true;
+    else if (argument === "--strict") options.strict = true;
     else if (argument === "--help" || argument === "-h") options.help = true;
-    else throw new Error(`Unknown permission option: ${argument}`);
+    else throw new Error("Unknown permission option: " + argument);
   }
   return options;
 }
 
+export function platformGuidance(platform = process.platform) {
+  if (platform === "darwin") {
+    return [
+      "macOS permission setup:",
+      "  - Requires macOS 14 or newer.",
+      "  - Open Computer Use needs Accessibility and Screen Recording.",
+      "  - The installer runs the native doctor; if either permission is missing,",
+      "    the Open Computer Use onboarding window opens and guides you to System Settings.",
+      "  - macOS requires a human approval for these protected TCC permissions.",
+      "  - Manual: open-computer-use doctor",
+      '  - Accessibility pane: open "x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility"',
+      '  - Screen Recording pane: open "x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture"',
+    ];
+  }
+  if (platform === "linux") {
+    return [
+      "Linux desktop setup:",
+      "  - There is no macOS-style permission dialog.",
+      "  - Open Computer Use needs a signed-in graphical session with AT-SPI2/D-Bus.",
+      "  - On GNOME, install mode best-effort enables toolkit accessibility with:",
+      "    gsettings set org.gnome.desktop.interface toolkit-accessibility true",
+      "  - Wayland screenshot and coordinate input support remains compositor-dependent.",
+      "  - Manual verification: open-computer-use doctor && open-computer-use call list_apps",
+    ];
+  }
+  if (platform === "win32") {
+    return [
+      "Windows desktop setup:",
+      "  - There is no separate UI Automation permission toggle to grant.",
+      "  - Open Computer Use must run in the signed-in interactive desktop session.",
+      "  - Detached services/session 0 cannot control the user's desktop.",
+      "  - Manual verification: open-computer-use doctor && open-computer-use call list_apps",
+    ];
+  }
+  return [
+    "Desktop permission setup is not defined for " + platform + ".",
+    "Use a supported macOS, Linux, or Windows native runtime.",
+  ];
+}
+
+function printPlatformGuidance(platform, io) {
+  for (const line of platformGuidance(platform)) io(line);
+}
+
 function shouldSkip(env) {
   const developmentInstall = env.npm_lifecycle_event === "postinstall"
     && env.INIT_CWD
@@ -47,15 +96,67 @@ function shouldSkip(env) {
   return developmentInstall || env.CI === "true" || env.CI === "1" || env[SKIP_ENV] === "1";
 }
 
+function commandAvailable(command, env) {
+  const result = spawnSync(command, ["--version"], {
+    env,
+    stdio: "ignore",
+    windowsHide: true,
+    timeout: 5_000,
+  });
+  return !result.error && result.status === 0;
+}
+
+function maybeEnableGnomeAccessibility(env, io) {
+  const desktop = ((env.XDG_CURRENT_DESKTOP || "") + " " + (env.DESKTOP_SESSION || "")).toLowerCase();
+  if (!desktop.includes("gnome")) {
+    io("Linux accessibility auto-enable skipped: GNOME was not detected; AT-SPI will be verified by the native runtime.");
+    return;
+  }
+  if (!commandAvailable("gsettings", env)) {
+    io("Linux accessibility auto-enable skipped: gsettings is unavailable.");
+    return;
+  }
+  const result = spawnSync(
+    "gsettings",
+    ["set", "org.gnome.desktop.interface", "toolkit-accessibility", "true"],
+    {
+      env,
+      encoding: "utf8",
+      windowsHide: true,
+      timeout: 10_000,
+    },
+  );
+  if (result.error || result.status !== 0) {
+    io("Linux accessibility auto-enable could not update GNOME settings. Run the documented gsettings command manually.");
+    return;
+  }
+  io("GNOME toolkit accessibility enabled.");
+}
+
+function printInstallSessionHint(platform, env, io) {
+  if (platform === "linux") {
+    io("Desktop: " + (env.XDG_CURRENT_DESKTOP || env.DESKTOP_SESSION || "unknown")
+      + "; session: " + (env.XDG_SESSION_TYPE || "unknown") + ".");
+    if (!env.DBUS_SESSION_BUS_ADDRESS) {
+      io("No DBUS_SESSION_BUS_ADDRESS is visible to the installer; the native runtime will try to discover the signed-in user's session automatically.");
+    }
+  } else if (platform === "win32") {
+    io("Windows session: " + (env.SESSIONNAME || "unknown")
+      + ". UI Automation requires the signed-in interactive desktop.");
+  }
+}
+
 export function main(argv = process.argv.slice(2), env = process.env, io = print) {
   let options;
   try {
     options = parseArguments(argv);
   } catch (error) {
-    io(`[opencode-computer-use-permissions] ${error instanceof Error ? error.message : String(error)}`, "stderr");
+    io("[opencode-computer-use-permissions] "
+      + (error instanceof Error ? error.message : String(error)), "stderr");
     io(usage(), "stderr");
     return 2;
   }
+
   if (options.help) {
     io(usage());
     return 0;
@@ -65,12 +166,19 @@ export function main(argv = process.argv.slice(2), env = process.env, io = print
     return 0;
   }
 
+  if (options.install) {
+    io("OpenCode Computer Use is checking desktop prerequisites as part of installation.");
+    printPlatformGuidance(process.platform, io);
+    printInstallSessionHint(process.platform, env, io);
+    if (process.platform === "linux") maybeEnableGnomeAccessibility(env, io);
+  }
+
   let backend;
   try {
     backend = resolveBackend({ backend: "native" }, env);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    io(`[opencode-computer-use-permissions] Native permission check unavailable: ${message}`);
+    io("[opencode-computer-use-permissions] Native permission check unavailable: " + message);
     if (options.strict) return 1;
     io("Install the optional open-computer-use runtime, then run this command again.");
     return 0;
@@ -83,13 +191,18 @@ export function main(argv = process.argv.slice(2), env = process.env, io = print
     timeout: 120_000,
   });
   if (result.error) {
-    io(`[opencode-computer-use-permissions] Permission check failed: ${result.error.message}`);
+    io("[opencode-computer-use-permissions] Permission check failed: " + result.error.message);
     return options.strict ? 1 : 0;
   }
   if (result.status !== 0) {
-    io(`[opencode-computer-use-permissions] Native permission check exited with status ${result.status}.`);
+    io("[opencode-computer-use-permissions] Native permission check exited with status "
+      + result.status + ".");
     return options.strict ? 1 : 0;
   }
+  if (options.install) {
+    io("Desktop onboarding check complete.");
+    io("You can rerun it any time with: npx opencode-computer-use-permissions --strict");
+  }
   return 0;
 }
 

package/bin/opencode-computer-use-repl.js

@@ -2,11 +2,33 @@
 
 import { resolveNativeCommand, runServer } from "../lib/repl.mjs";
 
-const native = resolveNativeCommand(process.argv.slice(2));
-runServer(native).catch((error) => {
+const argv = process.argv.slice(2);
+const help = `Usage: opencode-computer-use-repl [-- native-command [args...]]
+
+Start the local stdio MCP server exposing js and js_reset.
+With no command override, use the configured open-computer-use native runtime.
+
+Options:
+  --help, -h  Show this help without starting the native runtime
+
+Configuration: OPENCODE_COMPUTER_USE_* environment variables.
+Desktop access requires the server host's signed-in graphical session.
+`;
+
+try {
+  if (argv.length === 1 && (argv[0] === "--help" || argv[0] === "-h")) {
+    process.stdout.write(help);
+  } else {
+    if (argv.length > 0 && argv[0] !== "--") {
+      throw new Error(`Unknown REPL option: ${argv[0]}. Use --help or -- followed by a native command.`);
+    }
+    const native = resolveNativeCommand(argv);
+    await runServer(native);
+  }
+} catch (error) {
   const message = (error instanceof Error ? error.message : String(error))
     .replace(/\b(token|secret|password|api[_-]?key|authorization)\s*[:=]\s*(?:bearer|basic)?[^\n\r,;]*/giu, "$1=[redacted]")
     .slice(0, 4_000);
   process.stderr.write(`[opencode-computer-use] ${message}\n`);
   process.exitCode = 1;
-});
+}