fix(windows): force npm cmd shim generation and update install docs (#2558)

Co-authored-by: Dax <[email protected]>
Co-authored-by: GitHub Action <[email protected]>

4 files changed, 88 insertions, 9 deletions

diff --git a/packages/opencode/script/postinstall.mjs b/packages/opencode/script/postinstall.mjs
index 40796562c..b875d158f 100644
--- a/packages/opencode/script/postinstall.mjs
+++ b/packages/opencode/script/postinstall.mjs
@@ -68,10 +68,45 @@ function findBinary() {
   }
 }
 
-function main() {
+async function regenerateWindowsCmdWrappers() {
+  console.log("Windows + npm detected: Forcing npm to rebuild bin links")
+
+  try {
+    const { execSync } = require("child_process")
+    const pkgPath = path.join(__dirname, "..")
+
+    // npm_config_global is string | undefined
+    // if it exists, the value is true
+    const isGlobal = process.env.npm_config_global === "true" || pkgPath.includes(path.join("npm", "node_modules"))
+
+    // The npm rebuild command does 2 things - Execute lifecycle scripts and rebuild bin links
+    // We want to skip lifecycle scripts to avoid infinite loops, so we use --ignore-scripts
+    const cmd = `npm rebuild opencode-ai --ignore-scripts${isGlobal ? " -g" : ""}`
+    const opts = {
+      stdio: "inherit",
+      shell: true,
+      ...(isGlobal ? {} : { cwd: path.join(pkgPath, "..", "..") }), // For local, run from project root
+    }
+
+    console.log(`Running: ${cmd}`)
+    execSync(cmd, opts)
+    console.log("Successfully rebuilt npm bin links")
+  } catch (error) {
+    console.error("Error rebuilding npm links:", error.message)
+    console.error("npm rebuild failed. You may need to manually run: npm rebuild opencode-ai --ignore-scripts")
+  }
+}
+
+async function main() {
   try {
     if (os.platform() === "win32") {
-      console.log("Windows detected, skipping postinstall")
+      // NPM eg format - npm/11.4.2 node/v24.4.1 win32 x64
+      // Bun eg format - bun/1.2.19 npm/? node/v24.3.0 win32 x64
+      if (process.env.npm_config_user_agent.startsWith("npm")) {
+        await regenerateWindowsCmdWrappers()
+      } else {
+        console.log("Windows detected but not npm, skipping postinstall")
+      }
       return
     }
 
@@ -92,4 +127,9 @@ function main() {
   }
 }
 
-main()
+try {
+  main()
+} catch (error) {
+  console.error("Postinstall script error:", error.message)
+  process.exit(0)
+}
diff --git a/packages/opencode/script/preinstall.mjs b/packages/opencode/script/preinstall.mjs
index 49c8db5e5..dfe46d9e7 100644
--- a/packages/opencode/script/preinstall.mjs
+++ b/packages/opencode/script/preinstall.mjs
@@ -13,13 +13,25 @@ function main() {
     return
   }
 
-  const binDir = path.join(__dirname, "bin")
-  const unixScript = path.join(binDir, "opencode")
+  console.log("Windows detected: Modifying package.json bin entry")
 
-  console.log("Windows detected: Configuring bin scripts for Windows")
+  // Read package.json
+  const packageJsonPath = path.join(__dirname, "package.json")
+  const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"))
 
+  // Modify bin to point to .cmd file on Windows
+  packageJson.bin = {
+    opencode: "./bin/opencode.cmd",
+  }
+
+  // Write it back
+  fs.writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2))
+  console.log("Updated package.json bin to use opencode.cmd")
+
+  // Now you can also remove the Unix script if you want
+  const unixScript = path.join(__dirname, "bin", "opencode")
   if (fs.existsSync(unixScript)) {
-    console.log("Removing Unix shell script from bin/")
+    console.log("Removing Unix shell script")
     fs.unlinkSync(unixScript)
   }
 }
diff --git a/packages/web/src/content/docs/index.mdx b/packages/web/src/content/docs/index.mdx
index e57b4b1f4..293950eb0 100644
--- a/packages/web/src/content/docs/index.mdx
+++ b/packages/web/src/content/docs/index.mdx
@@ -62,7 +62,34 @@ You can also install it with the following:
 
 #### Windows
 
-Currently, the automatic installation methods do not work properly on Windows. However you can grab the binary from the [Releases](https://github.com/sst/opencode/releases).
+- **Using Chocolatey**
+
+  ```bash
+  choco install opencode
+  ```
+
+- **Using WinGet**
+
+  ```bash
+  winget install opencode
+  ```
+
+- **Using Scoop**
+
+  ```bash
+  scoop bucket add extras
+  scoop install extras/opencode
+  ```
+
+- **Using NPM**
+
+  ```bash
+  npm install -g opencode-ai
+  ```
+
+Support for installing opencode on Windows using the bun package manager is currently in progress.
+
+You can also grab the binary from the [Releases](https://github.com/sst/opencode/releases).
 
 ---
 
diff --git a/packages/web/src/content/docs/troubleshooting.mdx b/packages/web/src/content/docs/troubleshooting.mdx
index b846bed2d..57fbfe088 100644
--- a/packages/web/src/content/docs/troubleshooting.mdx
+++ b/packages/web/src/content/docs/troubleshooting.mdx
@@ -13,7 +13,7 @@ that it stores locally.
 Log files are written to:
 
 - **macOS/Linux**: `~/.local/share/opencode/log/`
-- **Windows**: `%APPDATA%\opencode\log\`
+- **Windows**: `%USERPROFILE%\.local\share\opencode\log\`
 
 Log files are named with timestamps (e.g., `2025-01-09T123456.log`) and the most recent 10 log files are kept.