@frontendxlab/opencode-computer-use 0.1.3 → 0.1.5

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

@@ -5,8 +5,8 @@ import { randomUUID } from "node:crypto";
 import { homedir } from "node:os";
 import { delimiter, dirname, join, resolve } from "node:path";
 import { spawnSync } from "node:child_process";
-import { fileURLToPath } from "node:url";
-import { applyEdits, modify, parse, parseTree } from "jsonc-parser";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { applyEdits, modify, parse } from "jsonc-parser";
 
 const PACKAGE_NAME = "@frontendxlab/opencode-computer-use";
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
@@ -36,14 +36,9 @@ For OpenCode2 V2, add this to opencode.json or opencode.jsonc:
   ]
 }
 
-For global OpenCode2 V2 setup, run:
-
-opencode2 plugin add @frontendxlab/opencode-computer-use
-
-After changing configuration, restart OpenCode:
-
-opencode service restart
-opencode2 service restart
+For global setup, rerun with --global and the appropriate --v1 or --v2 flag.
+For a local checkout, also pass --source /absolute/path/to/opencode-computer-use.
+After changing configuration, close and reopen OpenCode.
 `.trim();
 
 function print(text, stream = "stdout") {
@@ -76,6 +71,12 @@ function parseArguments(argv) {
       result.flavor = value === "1" ? "v1" : "v2";
     } else if (argument === "--dry-run") {
       result.dryRun = true;
+    } else if (argument === "--source") {
+      const value = argv[++index];
+      if (!value || value.startsWith("--")) {
+        throw new Error("--source requires a local directory, file path, or file URL");
+      }
+      result.source = value;
     } else if (argument === "--help" || argument === "-h") {
       result.help = true;
     } else if (argument === "--auto") {
@@ -98,18 +99,19 @@ Options:
   --v1                   Configure the OpenCode 1 plugin format
   --v2                   Configure the OpenCode2 V2 plugin format
   --opencode-version 1|2 Select the OpenCode generation explicitly
+  --source PATH_OR_URL   Load a local checkout directory or entrypoint file
   --dry-run              Show the action without changing files
   --help, -h             Show this help
 `;
 }
 
 function executableCandidates(command, env = process.env) {
-  const pathValue = env.PATH || "";
+  const pathKey = Object.keys(env).find((key) => key.toUpperCase() === "PATH");
+  const pathValue = env.PATH || (pathKey && env[pathKey]) || "";
   const directories = pathValue.split(delimiter).filter(Boolean);
   if (process.platform === "win32") {
     const extensions = (env.PATHEXT || ".EXE;.CMD;.BAT").split(";").filter(Boolean);
     return directories.flatMap((directory) => [
-      join(directory, command),
       ...extensions.map((extension) => join(directory, `${command}${extension.toLowerCase()}`)),
       ...extensions.map((extension) => join(directory, `${command}${extension}`)),
     ]);
@@ -131,10 +133,13 @@ function resolveCommand(command, env = process.env) {
 
 function probeCommand(command, env = process.env) {
   const executable = resolveCommand(command, env);
-  const result = spawnSync(executable, ["--version"], {
+  const batchFile = process.platform === "win32" && /\.(?:cmd|bat)$/iu.test(executable);
+  // npm's Windows shims need cmd.exe; a quoted fixed command keeps paths with
+  // spaces intact. The only argument is the fixed --version probe.
+  const result = spawnSync(batchFile ? `"${executable}" --version` : executable, batchFile ? [] : ["--version"], {
     encoding: "utf8",
     env,
-    shell: false,
+    shell: batchFile,
     windowsHide: true,
     timeout: 10_000,
   });
@@ -170,19 +175,32 @@ function packageKey(entry) {
   return undefined;
 }
 
-function hasPackage(entries) {
-  return Array.isArray(entries) && entries.some((entry) => packageKey(entry) === PACKAGE_NAME);
+function isPackageReference(value) {
+  return value === PACKAGE_NAME || (typeof value === "string" && value.startsWith(`${PACKAGE_NAME}@`) && value.length > PACKAGE_NAME.length + 1);
+}
+
+function hasPackage(entries, specifier = PACKAGE_NAME) {
+  return Array.isArray(entries) && entries.some((entry) => {
+    const key = packageKey(entry);
+    return key === specifier || (specifier === PACKAGE_NAME && isPackageReference(key));
+  });
+}
+
+function parseConfiguration(text) {
+  const errors = [];
+  const data = parse(text, errors, { allowTrailingComma: true, allowEmptyContent: true });
+  if (errors.length > 0) throw new Error("configuration is not valid JSON or JSONC");
+  if (!text.trim()) return {};
+  if (!data || typeof data !== "object" || Array.isArray(data)) {
+    throw new Error("configuration is not a JSON or JSONC object");
+  }
+  return data;
 }
 
 function configFlavor(text) {
-  const root = parseTree(text);
-  if (!root || root.type !== "object") return null;
-  const names = (root.children || [])
-    .filter((child) => child.type === "property")
-    .map((property) => property.children?.[0]?.value)
-    .filter((name) => name === "plugin" || name === "plugins");
-  const hasV1 = names.includes("plugin");
-  const hasV2 = names.includes("plugins");
+  const data = parseConfiguration(text);
+  const hasV1 = Object.hasOwn(data, "plugin");
+  const hasV2 = Object.hasOwn(data, "plugins");
   if (hasV1 && hasV2) return "ambiguous";
   if (hasV1) return "v1";
   if (hasV2) return "v2";
@@ -244,40 +262,52 @@ function defaultConfigFile(root, scope, env) {
   return join(configDir, "opencode.json");
 }
 
-function addEntry(entries, flavor) {
-  if (hasPackage(entries)) return { entries, changed: false };
+function addEntry(entries, flavor, specifier) {
+  if (hasPackage(entries, specifier)) return { entries, changed: false };
+  if (specifier !== PACKAGE_NAME) {
+    const index = entries.findIndex((entry) => isPackageReference(packageKey(entry)));
+    if (index !== -1) {
+      const current = entries[index];
+      const replacement = Array.isArray(current)
+        ? [specifier, ...current.slice(1)]
+        : typeof current === "object" ? { ...current, package: specifier } : specifier;
+      const updated = [...entries];
+      updated[index] = replacement;
+      return { entries: updated, changed: true };
+    }
+  }
   const entry = flavor === "v1"
-    ? [PACKAGE_NAME, { ...DEFAULT_V1_OPTIONS }]
-    : PACKAGE_NAME;
+    ? [specifier, { ...DEFAULT_V1_OPTIONS }]
+    : specifier;
   return { entries: [...entries, entry], changed: true };
 }
 
-function newConfig(flavor) {
+function newConfig(flavor, specifier) {
   const key = flavor === "v1" ? "plugin" : "plugins";
   const entry = flavor === "v1"
-    ? [[PACKAGE_NAME, { ...DEFAULT_V1_OPTIONS }]]
-    : [PACKAGE_NAME];
+    ? [[specifier, { ...DEFAULT_V1_OPTIONS }]]
+    : [specifier];
   return {
     $schema: "https://opencode.ai/config.json",
     [key]: entry,
   };
 }
 
-export function updateConfigText(text, flavor) {
-  const parsed = parse(text);
-  if (text.trim() && (parsed === undefined || parsed === null || typeof parsed !== "object" || Array.isArray(parsed))) {
-    throw new Error("configuration is not a JSON or JSONC object");
-  }
-  const data = parsed && typeof parsed === "object" ? parsed : {};
+export function updateConfigText(text, flavor, specifier = PACKAGE_NAME) {
+  const data = parseConfiguration(text);
   if (data.plugin !== undefined && data.plugins !== undefined) {
     throw new Error("configuration contains both plugin and plugins fields");
   }
   const key = flavor === "v1" ? "plugin" : "plugins";
+  const otherKey = flavor === "v1" ? "plugins" : "plugin";
+  if (Object.hasOwn(data, otherKey)) {
+    throw new Error(`selected ${flavor} conflicts with the existing ${otherKey} configuration`);
+  }
   const current = data[key];
   if (current !== undefined && !Array.isArray(current)) {
     throw new Error(`configuration field "${key}" is not an array`);
   }
-  const result = addEntry(current || [], flavor);
+  const result = addEntry(current || [], flavor, specifier);
   if (!result.changed) return { text, changed: false };
   const edits = modify(text, [key], result.entries, {
     formattingOptions: {
@@ -307,20 +337,21 @@ function writeConfig(file, content, dryRun) {
 
 function validateConfigFiles(root, scope, env) {
   for (const file of existingConfigFiles(root, scope, env)) {
-    const text = readFileSync(file, "utf8");
-    const data = parse(text);
-    if (text.trim() && (data === undefined || data === null || typeof data !== "object" || Array.isArray(data))) {
-      throw new Error(`configuration is not valid JSON or JSONC: ${file}`);
+    if (!existsSync(file)) continue;
+    try {
+      parseConfiguration(readFileSync(file, "utf8"));
+    } catch (error) {
+      throw new Error(`${error.message}: ${file}`);
     }
   }
 }
 
-function packageAlreadyConfigured(root, scope, env) {
+function packageAlreadyConfigured(root, scope, env, specifier) {
   for (const file of existingConfigFiles(root, scope, env)) {
     try {
-      const data = parse(readFileSync(file, "utf8"));
+      const data = parseConfiguration(readFileSync(file, "utf8"));
       const key = data?.plugins !== undefined ? "plugins" : data?.plugin !== undefined ? "plugin" : undefined;
-      if (key && hasPackage(data[key])) return file;
+      if (key && hasPackage(data[key], specifier)) return file;
     } catch {
       continue;
     }
@@ -328,31 +359,7 @@ function packageAlreadyConfigured(root, scope, env) {
   return undefined;
 }
 
-function redactMessage(value) {
-  return String(value)
-    .replace(/\b(token|secret|password|api[_-]?key|authorization)\s*[:=]\s*(?:bearer|basic)?[^\n\r,;]*/giu, "$1=[redacted]")
-    .slice(0, 500);
-}
-
-function runPluginCli(flavor, scope, root, env) {
-  const command = flavor === "v1" ? "opencode" : "opencode2";
-  const args = ["plugin", "add", PACKAGE_NAME];
-  if (flavor === "v1" && scope === "global") args.push("--global");
-  const result = spawnSync(resolveCommand(command, env), args, {
-    cwd: root,
-    encoding: "utf8",
-    env,
-    shell: process.platform === "win32",
-    windowsHide: true,
-    timeout: 120_000,
-  });
-  if (result.error || result.status !== 0) {
-    const detail = redactMessage(`${result.stdout || ""}${result.stderr || ""}`.trim());
-    throw new Error(`${command} plugin add failed${detail ? `: ${detail}` : ""}`);
-  }
-}
-
-function configForSetup(root, scope, flavor, env, dryRun) {
+function configForSetup(root, scope, flavor, env, dryRun, specifier) {
   const files = existingConfigFiles(root, scope, env);
   if (files.length > 0) {
     const flavors = files.map((file) => {
@@ -369,14 +376,19 @@ function configForSetup(root, scope, flavor, env, dryRun) {
       throw new Error("multiple conflicting OpenCode configuration files were found");
     }
   }
-  const file = files[0] || defaultConfigFile(root, scope, env);
+  const configured = packageAlreadyConfigured(root, scope, env, specifier);
+  if (configured) return { file: configured, changed: false };
+  // A checkout source replaces an npm registration in its original config,
+  // even when another JSON/JSONC config is also present.
+  const file = (specifier !== PACKAGE_NAME && packageAlreadyConfigured(root, scope, env, PACKAGE_NAME))
+    || files[0] || defaultConfigFile(root, scope, env);
   if (!existsSync(file)) {
-    const content = JSON.stringify(newConfig(flavor), null, 2) + "\n";
+    const content = JSON.stringify(newConfig(flavor, specifier), null, 2) + "\n";
     writeConfig(file, content, dryRun);
     return { file, changed: true };
   }
-  const result = updateConfigText(readFileSync(file, "utf8"), flavor);
-  writeConfig(file, result.text, dryRun);
+  const result = updateConfigText(readFileSync(file, "utf8"), flavor, specifier);
+  if (result.changed) writeConfig(file, result.text, dryRun);
   return { file, changed: result.changed };
 }
 
@@ -394,8 +406,13 @@ function chooseFlavor(requested, detection, config) {
     if (config === "v1" || config === "v2") return config;
     throw new Error("both OpenCode 1 and OpenCode2 are installed, and the configuration is ambiguous");
   }
-  if (detection.v1.available) return "v1";
-  if (detection.v2.available) return "v2";
+  if (detection.v1.available || detection.v2.available) {
+    const detected = detection.v1.available ? "v1" : "v2";
+    if (config && config !== detected) {
+      throw new Error(`detected ${detected} conflicts with the existing ${config} configuration`);
+    }
+    return detected;
+  }
   throw new Error("neither opencode nor opencode2 was found");
 }
 
@@ -405,6 +422,17 @@ function chooseRoot(scope, env) {
   return resolve(initial);
 }
 
+function sourceSpecifier(source, root) {
+  if (source === undefined) return PACKAGE_NAME;
+  if (typeof source !== "string" || !source.trim()) throw new Error("--source requires a local path or file URL");
+  let path = source.startsWith("file:") ? fileURLToPath(source) : resolve(root, source);
+  if (existsSync(path) && statSync(path).isDirectory()) path = join(path, "index.js");
+  if (!existsSync(path) || !statSync(path).isFile()) {
+    throw new Error(`local plugin entrypoint does not exist: ${path}`);
+  }
+  return pathToFileURL(realpathSync(path)).href;
+}
+
 export async function setup(options = {}, env = process.env, io = print) {
   const requestedScope = options.scope || "auto";
   const requestedFlavor = options.flavor || "auto";
@@ -413,31 +441,20 @@ export async function setup(options = {}, env = process.env, io = print) {
   if (env.OPENCODE_CONFIG_CONTENT) {
     throw new Error("OPENCODE_CONFIG_CONTENT is immutable; add the plugin to that configuration manually");
   }
+  validateConfigFiles(root, scope, env);
+  const specifier = sourceSpecifier(options.source, root);
   const detection = detectOpenCode(env);
   const config = detectConfigFlavor(root, scope, env);
   const flavor = chooseFlavor(requestedFlavor, detection, config);
   const dryRun = Boolean(options.dryRun);
-  let result;
-  if (scope === "global" && !dryRun) {
-    validateConfigFiles(root, scope, env);
-    const existing = packageAlreadyConfigured(root, scope, env);
-    if (existing) {
-      result = { file: existing, changed: false };
-    } else {
-      runPluginCli(flavor, scope, root, env);
-      const configured = packageAlreadyConfigured(root, scope, env);
-      if (!configured) throw new Error(`${flavor.toUpperCase()} plugin command did not register the package`);
-      result = { file: configured, changed: true };
-    }
-  } else {
-    result = configForSetup(root, scope, flavor, env, dryRun);
-  }
+  const result = configForSetup(root, scope, flavor, env, dryRun, specifier);
   const action = options.dryRun
     ? (result.changed ? "would configure" : "already configured")
     : (result.changed ? "configured" : "already configured");
   io(`OpenCode Computer Use setup ${action} for ${flavor.toUpperCase()} (${scope}).`);
-  if (result.changed) io(`Configuration: ${result.file}`);
-  return { ...result, scope, flavor, detection };
+  io(`Configuration: ${result.file}`);
+  io(`Plugin: ${specifier}`);
+  return { ...result, scope, flavor, detection, specifier };
 }
 
 export function printHelp() {
@@ -477,9 +494,10 @@ export async function main(argv = process.argv.slice(2), env = process.env, io =
   return setup(options, env, io)
     .then(() => 0)
     .catch((error) => {
-      io(`[opencode-computer-use] Automatic setup was not changed: ${error instanceof Error ? error.message : String(error)}`, "stderr");
+      const automatic = env.npm_lifecycle_event === "postinstall";
+      io(`[opencode-computer-use] ${automatic ? "Automatic setup was not changed" : "Setup failed"}: ${error instanceof Error ? error.message : String(error)}`, "stderr");
       io(FALLBACK_INSTRUCTIONS, "stderr");
-      return 0;
+      return automatic ? 0 : 1;
     });
 }
 

package/docs/NATIVE_VALIDATION.md

@@ -0,0 +1,102 @@
+# Native Desktop Validation
+
+Use this checklist before marking a native operating-system target as live-certified. The headless adapter test suite does not replace these checks.
+
+## Target matrix
+
+- macOS arm64
+- macOS x64
+- Linux arm64
+- Linux x64
+- Windows arm64
+- Windows x64
+
+Run only on a signed-in interactive desktop session. Do not use banking, password-manager, administrator, or other high-value applications for validation.
+
+## 1. Runtime and permissions
+
+```sh
+npm exec --package=@frontendxlab/opencode-computer-use -- opencode-computer-use-permissions --strict
+npm exec --package=open-computer-use@0.3.5 -- open-computer-use list-apps
+```
+
+Confirm that the native runtime starts successfully and that a disposable test application appears in the app list. Resolve Accessibility, Screen Recording, AT-SPI, UI Automation, capture, or input prerequisites before continuing.
+
+## 2. Read-only session
+
+Start OpenCode with `safetyMode: "read-only"` and verify:
+
+- `cua_repl` connects.
+- `cua.listApps()` returns the disposable test application.
+- `cua.getApp(...)` binds it.
+- `getAXState()` returns bounded state.
+- `getScreenshot()` returns an image when the host supports capture.
+- click, type, key, scroll, drag, value, and secondary actions are rejected by the adapter before native execution.
+
+## 3. Controlled mutation
+
+Use a disposable editor or test application and restore `safetyMode: "full"`.
+
+Verify semantic click, text input, keyboard input, scrolling/drag, and a fresh state read. Coordinate/global-pointer fallback must stay disabled unless explicitly enabled. Do not automatically replay a mutating action after a timeout or transport failure; observe first.
+
+## 4. Lifecycle and recovery
+
+Verify `js_reset`, CPU-loop timeout recovery, normal shutdown, native-request interruption recovery, and that no orphan native process remains.
+
+## 5. Platform-specific checks
+
+### macOS
+
+- Accessibility permission is granted only to the expected executable.
+- Screen Recording permission is sufficient for screenshots.
+- Intel and Apple Silicon use the expected packaged executable.
+
+### Linux
+
+- Record desktop environment and session type (X11 or Wayland).
+- Verify AT-SPI exposes actionable elements for the chosen test application.
+- Record the screenshot/input backend used by the native runtime.
+- Treat compositor-blocked synthetic input as unsupported rather than success.
+
+### Windows
+
+- Run in the interactive user desktop, not a service/session-0 context.
+- Verify UI Automation state and keyboard input.
+- Do not cross a UAC secure desktop.
+- Confirm process cleanup terminates the native process tree.
+
+## 6. Certification record
+
+For each target record the OS/version, architecture, Node/OpenCode/native-runtime versions, desktop/session type, permission result, app listing, AX state, screenshot, semantic input, lifecycle/recovery result, and known limitations.
+
+Only then change public documentation from packaged/supported target to live-certified for that target.
+
+## Recorded validation — 2026-10-30, 0.1.5 release candidate
+
+Host: Linux x64, Ubuntu/GNOME Wayland, GTK 3.24. Runtime versions: Node
+26.13.0, OpenCode 1.19.3, `open-computer-use` 0.3.5. The OpenCode integration
+also ran from an independently installed npm tarball with isolated settings.
+
+| Check | Observed result |
+| --- | --- |
+| Adapter regression suite | 70 passed, zero failed on this Linux host. |
+| Syntax/lint and whitespace checks | Passed. |
+| Real OpenCode registration | `cua_repl` connected with options preserved; both fake-backend and native startup modes passed. |
+| Packed installation | Clean tarball install, CLI help, and actual OpenCode fake-backend integration passed. |
+| Native app inventory | Eight running apps returned before opening the disposable fixture. |
+| Persistent JavaScript and reset | A variable survived a second call; `js_reset` succeeded. |
+| Disposable GTK accessibility tree | The test window exposed its counter, text entry, and named button. |
+| Element-index click | Counter changed from 0 to 1, confirmed by fresh state and the fixture's event log. |
+| `setValue` | Text field changed to the test string, confirmed by fresh state and the fixture's event log. |
+| Screenshot | Unavailable for the GTK window in this Wayland session; the adapter returned an explicit error. |
+| Coordinate input, keyboard input, drag, focus recovery | Not validated in this run. |
+| macOS/Windows live desktops | Not available for this run; native behavior remains unverified. |
+| Real OpenCode2 installation | Not exercised; adapter contract coverage only. |
+
+The fixture was a disposable local GTK window with no external action or data.
+Mutating checks allowed access only to that fixture, and global-pointer
+fallback remained off. ATK diagnostic warnings occurred during native tree
+inspection; the checked semantic actions still completed. This record supports
+the specific checks above, not universal Linux desktop certification or
+screenshot-based automation. Remote CI jobs must be checked on the release
+commit; their configuration alone is not evidence of a passed run.