fix(ci): make portless optional for windows installs

docs/agent-playbooks/known-surprises.md

@@ -28,4 +28,12 @@ If uncertain, ask the developer before adding an entry.
 
 ## Entries
 
-No confirmed surprises logged yet.
+### Portless breaks Windows installs
+
+- **Date:** 2026-03-04
+- **Observed by:** Codex
+- **Context:** GitHub Actions `Test Windows` dependency install on `windows-2022`
+- **What was surprising:** `portless@0.5.2` is a local dev-only tool, but keeping it in `devDependencies` makes `yarn install` fail on Windows because the package declares `win32` unsupported.
+- **Impact:** Windows CI fails before build steps run, even though the app does not need `portless` there.
+- **Mitigation:** Keep `portless` in `optionalDependencies` and make `yarn start` fall back to direct `vite` startup when `portless` is unavailable.
+- **Status:** confirmed

package.json

@@ -53,7 +53,7 @@
     "postinstall": "node scripts/patch-capacitor-cli-tar.cjs",
     "prebuild": "yarn sync:directories && yarn generate:assets",
     "prestart": "yarn sync:directories && yarn generate:assets",
-    "start": "portless 5chan vite",
+    "start": "node scripts/start-dev.js",
     "build": "cross-env PUBLIC_URL=./ GENERATE_SOURCEMAP=false vite build",
     "build:preload": "vite build --config electron/vite.preload.config.js",
     "build-vercel": "cross-env NODE_OPTIONS=\"--max_old_space_size=4096\" PUBLIC_URL=./ GENERATE_SOURCEMAP=true VITE_COMMIT_REF=$COMMIT_REF CI='' vite build",
@@ -144,7 +144,6 @@
     "oxfmt": "0.20.0",
     "oxlint": "1.35.0",
     "playwright": "1.56.1",
-    "portless": "0.5.2",
     "progress": "2.0.3",
     "react-doctor": "0.0.28",
     "react-grab": "0.0.98",
@@ -156,6 +155,9 @@
     "vitest": "4.0.15",
     "wait-on": "9.0.3"
   },
+  "optionalDependencies": {
+    "portless": "0.5.2"
+  },
   "resolutions": {
     "axios": "1.13.5",
     "js-yaml": "4.1.1",

scripts/start-dev.js

@@ -0,0 +1,35 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { spawn } from 'node:child_process';
+
+const isWindows = process.platform === 'win32';
+const usePortless = process.env.PORTLESS !== '0' && !isWindows;
+const binDir = join(process.cwd(), 'node_modules', '.bin');
+const executableSuffix = isWindows ? '.cmd' : '';
+const portlessBin = join(binDir, `portless${executableSuffix}`);
+const viteBin = join(binDir, `vite${executableSuffix}`);
+
+const command = usePortless && existsSync(portlessBin) ? portlessBin : viteBin;
+const args =
+  command === portlessBin
+    ? ['5chan', 'vite']
+    : ['--host', '5chan.localhost', '--port', '1355', '--strictPort'];
+
+if (command !== portlessBin && process.env.PORTLESS !== '0') {
+  console.warn('portless unavailable on this platform, using vite directly on http://5chan.localhost:1355');
+}
+
+const child = spawn(command, args, {
+  stdio: 'inherit',
+  env: process.env,
+});
+
+child.on('exit', (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+
+  process.exit(code ?? 0);
+});
+