From 65b868e36194262fe741db0e1af3d867a3e487b5 Mon Sep 17 00:00:00 2001
From: Dr_rOot <agalwood.net@gmail.com>
Date: Fri, 17 Jul 2026 11:56:07 +0800
Subject: [PATCH 1/6] ci: add GitHub Actions workflow across os and node matrix
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Run lint, typecheck, test, and build on every push to main and every
PR targeting main, across ubuntu/windows/macos x node 20/22/24 with
fail-fast disabled. The windows runners are the only environment that
exercises the win32 self-update path (cmd.exe escaping, absolute-path
taskkill, exit-code 9009 command-not-found normalization).

pnpm is installed via pnpm/action-setup before setup-node so the
pnpm cache works; the pnpm version comes from the packageManager
field. CI only — publishing stays a manual pnpm publish + OTP.
---
 .github/workflows/ci.yml | 54 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)
 create mode 100644 .github/workflows/ci.yml

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..5086a1f
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,54 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check:
+    name: ${{ matrix.os }} / node ${{ matrix.node }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        node: [20, 22, 24]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node.js ${{ matrix.node }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node }}
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Lint
+        run: pnpm lint
+
+      - name: Typecheck
+        run: pnpm typecheck
+
+      - name: Test
+        run: pnpm test
+
+      - name: Build
+        run: pnpm build

From 3c4f886e006b70d9e98a67a5a474ec699368a998 Mon Sep 17 00:00:00 2001
From: Dr_rOot <agalwood.net@gmail.com>
Date: Fri, 17 Jul 2026 12:00:51 +0800
Subject: [PATCH 2/6] chore: force lf line endings via .gitattributes

GitHub windows runners check out with core.autocrlf=true, converting
every file to crlf and failing pnpm lint (biome.json pins
formatter.lineEnding to lf). Forcing eol=lf at the git layer keeps
checkouts biome-clean on all platforms.
---
 .gitattributes | 3 +++
 1 file changed, 3 insertions(+)
 create mode 100644 .gitattributes

diff --git a/.gitattributes b/.gitattributes
new file mode 100644
index 0000000..71277b2
--- /dev/null
+++ b/.gitattributes
@@ -0,0 +1,3 @@
+# Biome enforces lf (biome.json formatter.lineEnding); force lf on checkout
+# everywhere so windows checkouts (core.autocrlf=true) don't fail lint.
+* text=auto eol=lf

From 3388c6970e2ecc1618043caff35f1724a1c2f8b8 Mon Sep 17 00:00:00 2001
From: Dr_rOot <agalwood.net@gmail.com>
Date: Fri, 17 Jul 2026 12:00:51 +0800
Subject: [PATCH 3/6] ci: install standalone pnpm so node 20 matrix jobs can
 run
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

pnpm 11.13.0 refuses to start on node < 22.13, which killed every
node 20 combo at pnpm install. The standalone @pnpm/exe bundles its
own runtime, while project scripts (vitest/tsc/tsup) still run on the
matrix node — so the node 20 jobs genuinely test the engines floor.
---
 .github/workflows/ci.yml | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 5086a1f..c724737 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -31,6 +31,11 @@ jobs:
 
       - name: Setup pnpm
         uses: pnpm/action-setup@v4
+        with:
+          # pnpm 11 needs node >= 22.13 to run itself; the standalone binary
+          # bundles its own runtime so the node 20 matrix jobs can still
+          # exercise the project's engines.node floor with PATH node 20.
+          standalone: true
 
       - name: Setup Node.js ${{ matrix.node }}
         uses: actions/setup-node@v4

From de60772848127c248bf472cb4892952c83abf23d Mon Sep 17 00:00:00 2001
From: Dr_rOot <agalwood.net@gmail.com>
Date: Fri, 17 Jul 2026 12:11:22 +0800
Subject: [PATCH 4/6] ci: fetch pnpm standalone binary from GitHub release

pnpm/action-setup standalone mode is broken for pnpm 11.13.0: the
@pnpm/* platform packages on npm were published without their binary,
so every installer path leaves @pnpm/exe's placeholder bin in place
(pnpm/action-setup#277). The GitHub release assets are built by a
different pipeline and verified good, so download the standalone
binary directly, versioned by the packageManager field.
---
 .github/workflows/ci.yml | 41 +++++++++++++++++++++++++++++++++-------
 1 file changed, 34 insertions(+), 7 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index c724737..d81bd8d 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -29,13 +29,40 @@ jobs:
         with:
           persist-credentials: false
 
-      - name: Setup pnpm
-        uses: pnpm/action-setup@v4
-        with:
-          # pnpm 11 needs node >= 22.13 to run itself; the standalone binary
-          # bundles its own runtime so the node 20 matrix jobs can still
-          # exercise the project's engines.node floor with PATH node 20.
-          standalone: true
+      # pnpm 11 cannot run on node 20 (it requires node >= 22.13), so the
+      # node 20 jobs need the standalone build, which bundles its own
+      # runtime while project scripts still run on the matrix node. Both
+      # pnpm/action-setup standalone mode and `npm i -g @pnpm/exe` are
+      # broken for 11.13.0 — the @pnpm/* platform packages on npm were
+      # published without their binary (pnpm/action-setup#277) — so fetch
+      # the standalone binary straight from the GitHub release, versioned
+      # by package.json's packageManager field.
+      - name: Setup pnpm (standalone binary)
+        shell: bash
+        run: |
+          version="$(node -p "require('./package.json').packageManager.split('@').pop()")"
+          case "${RUNNER_OS}-${RUNNER_ARCH}" in
+            Linux-X64)     asset="pnpm-linux-x64.tar.gz" ;;
+            Linux-ARM64)   asset="pnpm-linux-arm64.tar.gz" ;;
+            macOS-ARM64)   asset="pnpm-darwin-arm64.tar.gz" ;;
+            Windows-X64)   asset="pnpm-win32-x64.zip" ;;
+            Windows-ARM64) asset="pnpm-win32-arm64.zip" ;;
+            *) echo "no pnpm standalone asset for ${RUNNER_OS}-${RUNNER_ARCH}" >&2; exit 1 ;;
+          esac
+          dest="${RUNNER_TEMP}/pnpm-standalone"
+          mkdir -p "$dest"
+          cd "$dest"
+          curl -fsSL --retry 3 -o "$asset" \
+            "https://github.com/pnpm/pnpm/releases/download/v${version}/${asset}"
+          if [[ "$asset" == *.zip ]]; then
+            powershell.exe -NoProfile -Command "Expand-Archive -Path '${asset}' -DestinationPath '.' -Force"
+          else
+            tar -xzf "$asset"
+            chmod +x pnpm
+          fi
+          rm "$asset"
+          ./pnpm --version
+          echo "$dest" >> "$GITHUB_PATH"
 
       - name: Setup Node.js ${{ matrix.node }}
         uses: actions/setup-node@v4

From 7930132c876c1fb0c92b04349ee021b573e26ffe Mon Sep 17 00:00:00 2001
From: Dr_rOot <agalwood.net@gmail.com>
Date: Fri, 17 Jul 2026 12:30:13 +0800
Subject: [PATCH 5/6] fix(run-command): stop double-escaping args for bare
 non-PM commands
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

looksLikeBatchShim treated every extensionless bare name as a .cmd
shim, so 'node' args got the double meta-escape. cmd.exe parses an
.exe command line only once, leaving literal carets in argv —
node -e <script> broke outright (first observed on windows CI).
Only the JS package managers we invoke by bare name ship as .cmd
shims; classify exactly those, keep explicit .cmd/.bat paths, and
correct the isCommandMissing doc (cmd exits 1, not 9009; the
stderr phrase is the live signal).
---
 src/run-command.ts | 48 +++++++++++++++++++++++++++++++++-------------
 1 file changed, 35 insertions(+), 13 deletions(-)

diff --git a/src/run-command.ts b/src/run-command.ts
index 4eb51ea..70e5ebe 100644
--- a/src/run-command.ts
+++ b/src/run-command.ts
@@ -77,29 +77,51 @@ export function escapeCmdArgument(
   return arg
 }
 
+/**
+ * The JS package managers we invoke by bare name. On Windows they ship as
+ * `.cmd` shims, which cmd.exe re-parses — their arguments need the double
+ * meta-escape (BatBadBut). No other bare name may be treated as a shim:
+ * cmd.exe parses an `.exe` command line only once, so a double-escaped
+ * argument reaches the program with literal carets — `node -e <script>`
+ * breaks outright. (A standalone pnpm.exe invoked as bare `pnpm` still gets
+ * the double escape and its arguments arrive caret-mangled — a pre-existing
+ * limitation, unchanged here, and it fails loudly rather than silently.
+ * Resolving the real extension through PATHEXT, as cross-spawn does, remains
+ * the complete fix.)
+ */
+const BATCH_SHIM_NAMES = new Set([
+  'npm',
+  'npx',
+  'pnpm',
+  'pnpx',
+  'yarn',
+  'corepack',
+])
+
 /**
  * Whether a command, run through cmd.exe, resolves to a `.cmd`/`.bat` shim
- * (which cmd re-parses, requiring double meta-escaping of arguments). The JS
- * package managers (`npm`, `pnpm`, `yarn`) ship as `.cmd` shims on Windows and
- * are passed as bare names; `node`/the resolved bin paths we spawn are `.exe`.
- * Over-including an `.exe` here is harmless for our argument set (none contains
- * a metacharacter once the version spec passes `SPEC_RE`), so a bare name with
- * no extension is conservatively treated as a shim.
+ * (which cmd re-parses, requiring double meta-escaping of arguments). An
+ * explicit `.cmd`/`.bat` path is a shim; a bare name is one only when it is a
+ * known package-manager shim. Paths and extension-bearing names (`node.exe`,
+ * resolved bin paths) are not.
  */
 function looksLikeBatchShim(command: string): boolean {
   if (/\.(?:cmd|bat)$/i.test(command)) return true
-  return !/[\\/]/.test(command) && !/\.[a-z0-9]+$/i.test(command)
+  if (/[\\/]/.test(command) || /\.[a-z0-9]+$/i.test(command)) return false
+  return BATCH_SHIM_NAMES.has(command.toLowerCase())
 }
 
 /**
  * Whether a *completed* process indicates the command was not found. On POSIX
  * a missing binary never reaches here — it fails as a spawn `ENOENT` error
- * (handled separately). On win32 the command runs through cmd.exe, which exits
- * 9009 ("'x' is not recognized as an internal or external command") for a
- * missing command rather than emitting a spawn error. 9009 is the reliable,
- * locale-independent signal; the English phrase is a best-effort backup.
- * Deliberately narrow so a real tool error like npm's `E404 ... not found`
- * (exit 1) is NOT misclassified as a missing command.
+ * (handled separately). On win32 the command runs through cmd.exe, which
+ * prints "'x' is not recognized as an internal or external command" to stderr
+ * and — empirically, under `spawn(..., { shell: true })` — exits 1, not the
+ * documented ERRORLEVEL 9009. The phrase match is therefore the live signal
+ * (English-locale systems; a localized message is missed — accepted
+ * limitation), with 9009 kept as a defensive extra. Deliberately narrow so a
+ * real tool error like npm's `E404 ... not found` (exit 1) is NOT
+ * misclassified as a missing command.
  */
 export function isCommandMissing(
   code: number | null,

From 10fbae90ef383204dc06ec7ee64677ff8a736f70 Mon Sep 17 00:00:00 2001
From: Dr_rOot <agalwood.net@gmail.com>
Date: Fri, 17 Jul 2026 12:30:13 +0800
Subject: [PATCH 6/6] test: make the suite pass on a windows host
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three POSIX assumptions surfaced by the new windows CI jobs:
- path expectations hardcoded '/' while the code joins with the host
  separator — build expectations with join() so the platform-selection
  logic stays covered on every host
- stat.mode & 0o777 === 0o600 — windows has no POSIX mode bits
  (reports 0o666), skip those assertions there
- missing-binary and timeout results — win32 goes through cmd.exe, so
  a missing command is a non-zero exit + 'is not recognized' stderr
  (not a spawn ENOENT), and taskkill yields a non-zero code (not a
  signal null); branch the assertions by platform
---
 src/commands/self-update.test.ts |  7 ++++++-
 src/credentials.test.ts          | 21 ++++++++++++++-------
 src/device-id.test.ts            | 15 ++++++++++-----
 src/discovery.test.ts            | 23 ++++++++++++++++++-----
 src/run-command.test.ts          | 27 ++++++++++++++++++++-------
 5 files changed, 68 insertions(+), 25 deletions(-)

diff --git a/src/commands/self-update.test.ts b/src/commands/self-update.test.ts
index 1ef265e..9156086 100644
--- a/src/commands/self-update.test.ts
+++ b/src/commands/self-update.test.ts
@@ -1,3 +1,4 @@
+import { join } from 'node:path'
 import { describe, expect, it, vi } from 'vitest'
 import { EXIT } from '../errors'
 import type { RunResult } from '../run-command'
@@ -235,7 +236,11 @@ describe('runSelfUpdate — install and verify', () => {
     )
     expect(c.runCommand).toHaveBeenCalledWith(
       'node',
-      [`${NPM_ROOT}/@motrix/cli/dist/bin/motrix.js`, '--version'],
+      // join()-built: the code joins the entry with the HOST separator.
+      [
+        join(NPM_ROOT, '@motrix', 'cli', 'dist', 'bin', 'motrix.js'),
+        '--version',
+      ],
       expect.objectContaining({ cwd: '/tmp' })
     )
   })
diff --git a/src/credentials.test.ts b/src/credentials.test.ts
index 84a66f7..cd3691b 100644
--- a/src/credentials.test.ts
+++ b/src/credentials.test.ts
@@ -9,16 +9,18 @@ import {
   tokenForEndpoint,
 } from './credentials'
 
+// Expectations are join()-built: credentialsFilePath joins with the HOST
+// separator, so literal `/` strings would fail on a Windows host.
 describe('credentialsFilePath', () => {
   it('lands under ~/.config/motrix by default', () => {
     expect(credentialsFilePath({}, '/home/me')).toBe(
-      '/home/me/.config/motrix/credentials.json'
+      join('/home/me', '.config', 'motrix', 'credentials.json')
     )
   })
 
   it('honors XDG_CONFIG_HOME', () => {
     expect(credentialsFilePath({ XDG_CONFIG_HOME: '/cfg' }, '/home/me')).toBe(
-      '/cfg/motrix/credentials.json'
+      join('/cfg', 'motrix', 'credentials.json')
     )
   })
 })
@@ -50,11 +52,16 @@ describe('credentials store', () => {
     expect(await tokenForEndpoint('http://127.0.0.1:16801', path)).toBe('tok-a')
   })
 
-  it('writes the file at mode 0600', async () => {
-    await saveToken('http://x', { token: 't' }, path)
-    const st = await stat(path)
-    expect(st.mode & 0o777).toBe(0o600)
-  })
+  // Windows has no POSIX permission bits (stat.mode reports 0o666); the
+  // chmod call is still exercised there as a no-op by the other tests.
+  it.skipIf(process.platform === 'win32')(
+    'writes the file at mode 0600',
+    async () => {
+      await saveToken('http://x', { token: 't' }, path)
+      const st = await stat(path)
+      expect(st.mode & 0o777).toBe(0o600)
+    }
+  )
 
   it('normalizes a trailing slash in the endpoint key', async () => {
     await saveToken('http://nas.local:16801/', { token: 'tok-b' }, path)
diff --git a/src/device-id.test.ts b/src/device-id.test.ts
index dd0aa3e..a02f8d2 100644
--- a/src/device-id.test.ts
+++ b/src/device-id.test.ts
@@ -40,11 +40,16 @@ describe('device-id store', () => {
     expect(a).not.toBe(b)
   })
 
-  it('writes the store file with 0600 permissions', async () => {
-    await ensureDeviceId('http://127.0.0.1:1', path)
-    const mode = (await stat(path)).mode & 0o777
-    expect(mode).toBe(0o600)
-  })
+  // Windows has no POSIX permission bits (stat.mode reports 0o666); the
+  // mode-setting write path is still exercised there by the other tests.
+  it.skipIf(process.platform === 'win32')(
+    'writes the store file with 0600 permissions',
+    async () => {
+      await ensureDeviceId('http://127.0.0.1:1', path)
+      const mode = (await stat(path)).mode & 0o777
+      expect(mode).toBe(0o600)
+    }
+  )
 
   async function seed(obj: unknown): Promise<void> {
     await mkdir(dirname(path), { recursive: true })
diff --git a/src/discovery.test.ts b/src/discovery.test.ts
index f8e2892..1bdc4d9 100644
--- a/src/discovery.test.ts
+++ b/src/discovery.test.ts
@@ -1,3 +1,4 @@
+import { join } from 'node:path'
 import { describe, expect, it } from 'vitest'
 import {
   type EndpointFile,
@@ -17,34 +18,46 @@ const file: EndpointFile = {
   writtenAt: 1,
 }
 
+// Expectations are join()-built: the code under test joins with the HOST
+// separator even when simulating another platform, so literal `/` strings
+// would fail on a Windows host.
 describe('userDataDir', () => {
   it('resolves the macOS Application Support path', () => {
     expect(userDataDir('darwin', {}, '/Users/me')).toBe(
-      '/Users/me/Library/Application Support/Motrix'
+      join('/Users/me', 'Library', 'Application Support', 'Motrix')
     )
   })
 
   it('resolves the Linux XDG config path', () => {
-    expect(userDataDir('linux', {}, '/home/me')).toBe('/home/me/.config/Motrix')
+    expect(userDataDir('linux', {}, '/home/me')).toBe(
+      join('/home/me', '.config', 'Motrix')
+    )
   })
 
   it('honors XDG_CONFIG_HOME on Linux', () => {
     expect(userDataDir('linux', { XDG_CONFIG_HOME: '/cfg' }, '/home/me')).toBe(
-      '/cfg/Motrix'
+      join('/cfg', 'Motrix')
     )
   })
 
   it('resolves the Windows APPDATA path', () => {
     expect(
       userDataDir('win32', { APPDATA: 'C:\\Users\\me\\AppData\\Roaming' }, 'C:')
-    ).toContain('Motrix')
+    ).toBe(join('C:\\Users\\me\\AppData\\Roaming', 'Motrix'))
   })
 })
 
 describe('endpointFilePath', () => {
   it('lands under <userData>/bridge/endpoint.json', () => {
     expect(endpointFilePath('darwin', {}, '/Users/me')).toBe(
-      '/Users/me/Library/Application Support/Motrix/bridge/endpoint.json'
+      join(
+        '/Users/me',
+        'Library',
+        'Application Support',
+        'Motrix',
+        'bridge',
+        'endpoint.json'
+      )
     )
   })
 })
diff --git a/src/run-command.test.ts b/src/run-command.test.ts
index daaee23..356acd9 100644
--- a/src/run-command.test.ts
+++ b/src/run-command.test.ts
@@ -71,12 +71,19 @@ describe('runCommand', () => {
     expect(r).toMatchObject({ code: 3, stderr: 'bad' })
   })
 
-  it('reports a spawn failure as code null with the error attached', async () => {
+  it('reports a missing binary through the platform signal', async () => {
     const r = await runCommand('motrix-test-no-such-binary-xyz', [])
-    expect(r.code).toBe(null)
-    expect(r.spawnError).toBeDefined()
-    // A POSIX ENOENT is a missing command; on win32 it surfaces via 9009.
-    if (process.platform !== 'win32') expect(r.commandMissing).toBe(true)
+    expect(r.commandMissing).toBe(true)
+    if (process.platform === 'win32') {
+      // Through cmd.exe a missing command is not a spawn failure: cmd runs,
+      // prints "... is not recognized ..." and exits non-zero.
+      expect(r.code).not.toBe(0)
+      expect(r.code).not.toBe(null)
+    } else {
+      // POSIX: the spawn itself fails with ENOENT.
+      expect(r.code).toBe(null)
+      expect(r.spawnError).toBeDefined()
+    }
   })
 
   it('kills a process that exceeds the timeout and flags timedOut', async () => {
@@ -84,8 +91,14 @@ describe('runCommand', () => {
       timeoutMs: 200,
     })
     expect(r.timedOut).toBe(true)
-    // Killed → no clean exit code.
-    expect(r.code).toBe(null)
+    if (process.platform === 'win32') {
+      // taskkill /f terminates the cmd.exe wrapper with a non-zero exit code.
+      expect(r.code).not.toBe(0)
+      expect(r.code).not.toBe(null)
+    } else {
+      // Killed by signal → no clean exit code.
+      expect(r.code).toBe(null)
+    }
   })
 
   it('caps captured output and flags truncation', async () => {