opencode-skills-collection 4.0.73 → 4.0.75

package/bundled-skills/electron-drive-skill/SKILL.md

@@ -0,0 +1,237 @@
+---
+name: electron-drive-skill
+description: "Launch the project's Electron app on a scratch profile and drive it: click, type, screenshot, run renderer or main-process code, read logs. Use to verify UI changes end to end."
+category: testing
+risk: critical
+source: community
+source_repo: Search-3D/electron-drive-skill
+source_type: community
+date_added: "2026-09-23"
+author: Search-3D
+tags: [electron, playwright, desktop, e2e, testing, automation]
+tools: [claude]
+license: "MIT"
+license_source: "https://github.com/Search-3D/electron-drive-skill/blob/main/LICENSE"
+---
+
+# Driving the Electron app
+
+## Overview
+
+`scripts/drive.mjs` launches the project's Electron app under Playwright in a
+background daemon and keeps it running between commands, so each action
+(click, type, snapshot, screenshot, eval) is one fast shell call. Every launch
+uses a scratch profile, so the agent can check a UI change or reproduce a bug
+in the real app, not only in unit tests, without touching the user's data.
+
+## When to Use This Skill
+
+- Use when you need to verify a UI change in the running Electron app.
+- Use when reproducing a renderer or startup bug, or a failure that only
+  shows up in the production build (for example a stricter CSP).
+- Use when checking first-run, onboarding or settings screens.
+- Use when exercising a feature end to end, including IPC through the preload
+  bridge or code in the main process.
+- Do not use it for web apps without Electron, or for multi-window flows (see
+  Limitations).
+
+## How It Works
+
+### Step 1: Check prerequisites
+
+`scripts/drive.mjs`, in this skill's directory, finds the project by the
+nearest `package.json`, so run it from anywhere inside the project. Set `DR`
+to its absolute path.
+
+It needs `electron` and `playwright-core` (1.49 or later) installed in the
+project. If `start` says either is missing, tell the user rather than
+installing it yourself. Launch settings come from `drive.config.json` at the
+project root (see Step 4); with no file, it runs `electron .`.
+
+### Step 2: Start, look, act, stop
+
+```bash
+DR=<this skill's directory>/scripts/drive.mjs
+
+$DR start                  # last build, profile 'default'; prints status
+$DR snapshot               # accessibility tree: find what to click, by role and name
+$DR click 'role=button[name="Get started"]'
+$DR fill 'role=textbox[name="Email"]' 'test@example.com'
+$DR wait 'text=Welcome'
+$DR screenshot             # prints a PNG path; Read it to see the window
+$DR logs --lines 80        # main and renderer console, plus the config's logFile
+$DR stop                   # ALWAYS, before finishing
+```
+
+- **Start options:**
+  - `--build`: run the config's `build` command first. **Needed after any
+    source change** if the app runs from a build, because the build is
+    otherwise stale; `start` prints its age.
+  - `--fresh`: wipe the scratch profile, which gives you the app's first-run
+    state.
+  - `--profile <name>`: a separate scratch profile.
+  - `--dev`: see Step 5.
+- **Targets** are Playwright selectors. Prefer `role=button[name="…"]` from
+  `snapshot` output, then `text=…`, then CSS.
+- **`--`** ends the flags. Put it before text that starts with dashes:
+  `$DR fill 'role=textbox[name="Args"]' -- --verbose`.
+- Other commands: `select <target> <value|label>`, `press <key>`,
+  `status`, `screenshot --selector <css>`. `$DR help` lists everything.
+
+### Step 3: Run code in the app
+
+**`eval <js>`** runs in the renderer, **`main <js>`** in the main process
+(`electron` and `process` are in scope, `require` is not). Use a bare
+expression, or a body with `return`. `-` reads the code from stdin, which
+avoids quoting entirely. The result comes back as JSON, so return plain data:
+a DOM node or a function comes back as `undefined` or `{}`.
+
+To exercise IPC, call whatever the app's preload exposes through `eval`. That
+goes through the real preload bridge, as the app's own renderer code does.
+
+### Step 4: Configure the launch (optional)
+
+`drive.config.json` at the project root; every field is optional:
+
+```json
+{
+  "build": "npm run build",
+  "args": ["."],
+  "env": { "APP_DATA_DIR": "{profile}/data" },
+  "logFile": "logs/main.log",
+  "dev": {
+    "args": ["."],
+    "env": { "ELECTRON_RENDERER_URL": "http://localhost:5173" },
+    "url": "http://localhost:5173"
+  }
+}
+```
+
+- `args`: what Electron is launched with: an app directory whose
+  `package.json` `main` is the built entry point, or the entry file itself.
+- `env`: added to the app's environment. `{profile}` becomes the scratch
+  profile directory (in `env` values only, not in `args`). This is how data
+  kept outside `userData` is redirected: `APP_DATA_DIR` is only an example
+  name, and it has an effect only if the app reads it. Check the app's source
+  for the variable it actually uses.
+- `logFile`: a log file relative to the profile directory, shown by `logs`.
+
+If a project has no config and `start` fails or launches the wrong thing,
+work out these values from the project's `package.json` and build setup,
+then suggest a `drive.config.json` to the user.
+
+### Step 5: Dev mode (optional)
+
+For a fast loop on renderer code, with hot reload and source maps:
+
+1. The user (or a background Bash call) starts the renderer dev server
+   **without** its own Electron. Many templates' `start`/`dev` scripts launch
+   Electron too, and two instances would share state. The config's
+   `dev.url` is checked before launch.
+2. `$DR start --dev` launches Electron with `dev.args` and `dev.env`, and
+   `NODE_ENV=development`.
+
+## Examples
+
+### Example 1: Verify a change to the first-run screen
+
+```bash
+$DR start --build --fresh
+$DR snapshot
+$DR click 'role=button[name=/Next/]'
+$DR screenshot
+$DR logs --lines 40
+$DR stop
+```
+
+### Example 2: Inspect renderer state and call IPC
+
+```bash
+echo "return document.querySelectorAll('button').length" | $DR eval -
+$DR eval "window.api.getSettings()"
+```
+
+### Example 3: Query the main process
+
+```bash
+$DR main "electron.app.getVersion()"
+$DR main "electron.BrowserWindow.getAllWindows().length"
+```
+
+## Best Practices
+
+- ✅ **Look before acting.** Take a `snapshot` or `screenshot` first. The same
+  profile can open differently on a second launch (past the first-run
+  screens), and a click that times out usually means the screen is not what
+  you assumed.
+- ✅ **Check `logs`** for `[renderer:error]` and `[renderer:pageerror]` after
+  each step.
+- ✅ **Prefer the production build.** It catches failures that only show up
+  there, such as a stricter Content-Security-Policy, which the dev server
+  would miss.
+- ✅ **Always `stop`**, including after a failure. `stop` reports how the app
+  went down; anything but "quit via app.quit()" (a hung quit, a SIGKILL) is
+  worth a line in your report.
+- ❌ **Don't use the npm/yarn script wrappers** (e.g. `yarn drive`). Run the
+  script directly. yarn 1 re-splits arguments and drops inner quotes, which
+  silently breaks most JavaScript passed to `eval` and `main`.
+- ❌ **Don't install `electron` or `playwright-core`** yourself; ask the user.
+
+## Limitations
+
+- **One window.** Commands act on the first window that is not DevTools, and
+  there is no way to pick another. `status` shows which window that is; a
+  splash screen is current until it closes.
+- **One app at a time** per project. `start` refuses while one is running.
+- **Windows:** run it as `node scripts/drive.mjs`. The process-tree kill that
+  `stop` falls back to is POSIX only.
+- Requires `electron` and `playwright-core` 1.49+ in the project, and Node.js
+  18+.
+- It does not replace the project's own test suite or a human check of
+  visual design. Stop and ask if the launch settings or data locations are
+  unclear.
+
+## Security & Safety Notes
+
+- **Local-only.** The daemon listens on `127.0.0.1` with a random per-session
+  token. Nothing is sent to third-party services.
+- **Never point it at the user's real data.** Every launch gets
+  `--user-data-dir` set to a scratch profile under
+  `$TMPDIR/electron-drive/<project>/profiles/<name>`, which moves
+  `app.getPath('userData')`. Data the app keeps elsewhere (a documents
+  folder, a path from an env var) is only redirected if `drive.config.json`
+  sets it through `env`. Check that before doing anything that writes data.
+  If the app would touch real user files, stop and tell the user.
+- **`eval` and `main` run arbitrary code** with the app's privileges; the
+  main process has full Node.js access. Only run code needed for the task,
+  and never code that deletes files or makes network calls outside the app's
+  normal behavior without the user's confirmation.
+- **`start --build` runs the `build` command from `drive.config.json` in a
+  shell.** Read the config before the first `--build` in a project you did
+  not set up.
+- **`--fresh` deletes the scratch profile directory** only, never the app's
+  real `userData`.
+
+## Common Pitfalls
+
+- **Problem:** `start` fails.
+  **Solution:** Read the daemon log it prints. Common causes are a missing
+  build (`--build`), `electron` or `playwright-core` not installed, or wrong
+  `args`.
+- **Problem:** "The app is not running".
+  **Solution:** It crashed or quit. Run `logs`, then `stop`, then `start`.
+- **Problem:** The app shows old behavior after a source change.
+  **Solution:** The build is stale. Restart with `start --build`.
+- **Problem:** A click can't find a button whose name includes icon-font text
+  (such as `arrow_forward`).
+  **Solution:** Use a regex name: `role=button[name=/Next/]`.
+- **Problem:** A stuck state after an interrupted session.
+  **Solution:** `$DR stop` cleans up the daemon, the app and the state file,
+  even when the daemon is already gone.
+
+## Related Skills
+
+- `@electron-development` - For building and packaging the Electron app
+  itself; use this skill to verify the result in the running app.
+- `@systematic-debugging` - Pair with this skill to reproduce and narrow down
+  a bug in the real app.

package/bundled-skills/electron-drive-skill/drive.config.json.example

@@ -0,0 +1,10 @@
+{
+  "build": "pnpm build",
+  "args": ["release/app"],
+  "env": { "APP_DATA_DIR": "{profile}/data" },
+  "logFile": "data/app.log",
+  "dev": {
+    "args": ["."],
+    "url": "http://localhost:1212"
+  }
+}

package/bundled-skills/electron-drive-skill/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "electron-drive-skill",
+  "version": "1.0.0",
+  "description": "Enable your agents to interact with your Electron application automatically. Start/Stop, screenshot, clicking, filling in text, etc.",
+  "keywords": [
+    "agent",
+    "skill",
+    "electron",
+    "control"
+  ],
+  "homepage": "https://github.com/Search-3D/electron-drive-skill#readme",
+  "bugs": {
+    "url": "https://github.com/Search-3D/electron-drive-skill/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Search-3D/electron-drive-skill.git"
+  },
+  "license": "MIT",
+  "author": "Search3D <github.com/Search-3D>",
+  "type": "module",
+  "scripts": {
+    "test": "node scripts/lib.test.mjs"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/bundled-skills/electron-drive-skill/scripts/daemon.mjs

@@ -0,0 +1,352 @@
+/**
+ * The long-lived half of the driver: launches the app through Playwright,
+ * keeps it up between commands, and answers them over loopback HTTP.
+ *
+ * Started detached by `drive start`; never run by hand.
+ */
+import { execFileSync } from 'node:child_process'
+import { randomBytes } from 'node:crypto'
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import http from 'node:http'
+import { createRequire } from 'node:module'
+import path from 'node:path'
+
+import {
+  asFunctionBody,
+  childEnv,
+  daemonLogPath,
+  loadConfig,
+  PROJECT_ROOT,
+  screenshotDir,
+  statePath
+} from './lib.mjs'
+
+const [, , mode, profile, dataDir] = process.argv
+const config = loadConfig()
+
+const log = (message) => {
+  // stdout is daemon.log (drive.mjs redirects it).
+  console.log(`${new Date().toISOString()} ${message}`)
+}
+
+/** Recent console output from both processes, for `logs`. */
+const output = []
+const remember = (line) => {
+  output.push(line)
+  if (output.length > 500) output.shift()
+}
+
+let app
+let electronPid
+
+/**
+ * The app's window, not DevTools. A dev build may open DevTools as a window of
+ * its own, and it can be the first one to appear.
+ */
+const getPage = async (timeoutMs = 30_000) => {
+  const deadline = Date.now() + timeoutMs
+  while (Date.now() < deadline) {
+    const page = app.windows().find((candidate) => !candidate.url().startsWith('devtools://'))
+    if (page) return page
+    await new Promise((resolve) => setTimeout(resolve, 250))
+  }
+  throw new Error(`No app window appeared within ${timeoutMs}ms.`)
+}
+
+const watchPage = (page) => {
+  page.on('console', (message) => remember(`[renderer:${message.type()}] ${message.text()}`))
+  page.on('pageerror', (error) => remember(`[renderer:pageerror] ${error.message}`))
+}
+
+const launch = async () => {
+  // Both come from the project, not from this skill, so the skill can live
+  // anywhere. Outside Electron, `require('electron')` is the binary's path.
+  const projectRequire = createRequire(path.join(PROJECT_ROOT, 'package.json'))
+  const load = (name) => {
+    try {
+      return projectRequire(name)
+    } catch {
+      return null
+    }
+  }
+  const playwright = load('playwright-core') ?? load('playwright')
+  if (!playwright) throw new Error(`playwright-core is not installed in ${PROJECT_ROOT}. Run: npm i -D playwright-core`)
+  const electronPath = load('electron')
+  if (!electronPath) throw new Error(`electron is not installed in ${PROJECT_ROOT}.`)
+
+  const launchConfig = mode === 'dev' ? config.dev : config
+  // --user-data-dir moves app.getPath('userData'), and with it localStorage,
+  // IndexedDB, cookies and most apps' settings, into the scratch profile.
+  const args = [...launchConfig.args, `--user-data-dir=${dataDir}`]
+  log(`Launching ${mode}: electron ${args.join(' ')} (profile ${profile})`)
+  app = await playwright._electron.launch({
+    executablePath: electronPath,
+    args,
+    cwd: PROJECT_ROOT,
+    env: childEnv(process.env, dataDir, mode, { ...config.env, ...(mode === 'dev' ? config.dev.env : {}) }),
+    timeout: 90_000
+  })
+
+  const child = app.process()
+  electronPid = child.pid
+  const lines = (tag) => (chunk) =>
+    String(chunk).split('\n').filter(Boolean).forEach((line) => remember(`[${tag}] ${line}`))
+  child.stdout?.on('data', lines('main'))
+  child.stderr?.on('data', lines('main:err'))
+  app.on('window', watchPage)
+  app.on('close', () => {
+    log('The app exited.')
+    remember('[driver] the app exited')
+  })
+
+  const page = await getPage(90_000)
+  watchPage(page)
+  await page.waitForLoadState('domcontentloaded')
+  log(`Window up: ${await page.title()} (${page.url()})`)
+}
+
+const isRunning = (pid) => {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch {
+    return false
+  }
+}
+
+const appExited = () => electronPid !== undefined && !isRunning(electronPid)
+
+const waitForExit = async (pid, ms) => {
+  const deadline = Date.now() + ms
+  while (Date.now() < deadline) {
+    if (!isRunning(pid)) return true
+    await new Promise((resolve) => setTimeout(resolve, 100))
+  }
+  return !isRunning(pid)
+}
+
+/** Every descendant of `pid`, deepest first, via `pgrep -P`. POSIX only. */
+const descendants = (pid) => {
+  if (process.platform === 'win32') return []
+  let children = []
+  try {
+    children = execFileSync('pgrep', ['-P', String(pid)], { encoding: 'utf8' })
+      .split('\n')
+      .filter(Boolean)
+      .map(Number)
+  } catch {
+    return []
+  }
+  return children.flatMap((child) => [...descendants(child), child])
+}
+
+const within = (ms, promise) =>
+  Promise.race([promise, new Promise((resolve) => setTimeout(resolve, ms))])
+
+/**
+ * End the app, and say how. `app.quit()` first, as a user quitting would; then
+ * Playwright's close; then SIGKILL on the whole tree, for apps whose quit
+ * handlers hang or that ignore SIGTERM.
+ */
+const stop = async () => {
+  if (!electronPid || !isRunning(electronPid)) return 'already exited'
+  const pid = electronPid
+  const tree = descendants(pid)
+
+  // The quit can tear down the connection before the evaluate returns.
+  await within(1000, app.evaluate(({ app: electronApp }) => electronApp.quit())).catch(() => {})
+  if (await waitForExit(pid, 5000)) return 'quit via app.quit()'
+
+  await within(3000, app.close()).catch(() => {})
+  if (await waitForExit(pid, 2000)) return 'closed by Playwright after app.quit() did not exit within 5s'
+
+  for (const victim of [...tree, pid]) {
+    try {
+      process.kill(victim, 'SIGKILL')
+    } catch {
+      // Already gone.
+    }
+  }
+  await waitForExit(pid, 2000)
+  return 'SIGKILLed (process tree) after app.quit() and Playwright close both failed'
+}
+
+const handlers = {
+  async status() {
+    const page = appExited() ? null : await getPage(2000).catch(() => null)
+    return {
+      mode,
+      profile,
+      dataDir,
+      electronPid,
+      running: !appExited(),
+      window: page ? { title: await page.title(), url: page.url() } : null
+    }
+  },
+
+  async snapshot() {
+    const page = await getPage()
+    return page.locator('body').ariaSnapshot()
+  },
+
+  async screenshot({ out, selector }) {
+    const page = await getPage()
+    mkdirSync(screenshotDir(), { recursive: true })
+    const file = out ?? path.join(screenshotDir(), `${new Date().toISOString().replace(/[:.]/g, '-')}.png`)
+    if (selector) await page.locator(selector).first().screenshot({ path: file })
+    else await page.screenshot({ path: file })
+    return file
+  },
+
+  async click({ target }) {
+    const page = await getPage()
+    await page.locator(target).first().click({ timeout: 10_000 })
+    return `clicked ${target}`
+  },
+
+  async fill({ target, text }) {
+    const page = await getPage()
+    await page.locator(target).first().fill(text, { timeout: 10_000 })
+    return `filled ${target}`
+  },
+
+  async select({ target, value }) {
+    const page = await getPage()
+    // A string matches an option's value or its visible label.
+    const chosen = await page.locator(target).first().selectOption(value, { timeout: 10_000 })
+    return `selected ${chosen.join(', ')} in ${target}`
+  },
+
+  async press({ key }) {
+    const page = await getPage()
+    await page.keyboard.press(key)
+    return `pressed ${key}`
+  },
+
+  async wait({ target, timeout }) {
+    const page = await getPage()
+    await page.locator(target).first().waitFor({ timeout: timeout ?? 10_000 })
+    return `found ${target}`
+  },
+
+  async eval({ code }) {
+    const page = await getPage()
+    // CDP evaluation, so the page's CSP (no 'unsafe-eval') does not apply to it.
+    return page.evaluate(`(async () => { ${asFunctionBody(code)} })()`)
+  },
+
+  async main({ code }) {
+    // Playwright takes a string as an *expression*, so a function written as a
+    // string comes back as the function, not its result. The body is passed as
+    // an argument instead and compiled in main, where there is no CSP. In scope:
+    // `electron` (the main process's module) and Node's globals (`process`,
+    // `Buffer`); `require` is not.
+    return app.evaluate(async (electron, body) => {
+      const AsyncFunction = Object.getPrototypeOf(async () => {}).constructor
+      return new AsyncFunction('electron', body)(electron)
+    }, asFunctionBody(code))
+  },
+
+  async logs({ lines }) {
+    const count = lines ?? 60
+    let fileTail = ''
+    if (config.logFile) {
+      const file = path.resolve(dataDir, config.logFile)
+      const tail = existsSync(file)
+        ? readFileSync(file, 'utf8').split('\n').slice(-count).join('\n')
+        : '(not written yet)'
+      fileTail = `--- ${file} (last ${count}) ---\n${tail}\n`
+    }
+    return `${fileTail}--- console (last ${count}) ---\n${output.slice(-count).join('\n')}`
+  }
+}
+
+const main = async () => {
+  const token = randomBytes(24).toString('hex')
+
+  try {
+    await launch()
+  } catch (e) {
+    log(`Launch failed: ${e?.stack ?? e}`)
+    if (electronPid) await stop().catch(() => {})
+    process.exit(1)
+  }
+
+  const server = http.createServer((request, response) => {
+    let body = ''
+    request.on('data', (chunk) => {
+      body += chunk
+    })
+    request.on('end', async () => {
+      const reply = (status, payload) => {
+        response.writeHead(status, { 'content-type': 'application/json' })
+        response.end(JSON.stringify(payload))
+      }
+      let parsed
+      try {
+        parsed = JSON.parse(body)
+      } catch {
+        reply(400, { ok: false, error: 'Bad request.' })
+        return
+      }
+      if (parsed.token !== token) {
+        reply(403, { ok: false, error: 'Bad token.' })
+        return
+      }
+
+      if (parsed.command === 'stop') {
+        const how = await stop()
+        log(`Stopped: ${how}`)
+        reply(200, { ok: true, result: how })
+        rmSync(statePath(), { force: true })
+        server.close()
+        setTimeout(() => process.exit(0), 100)
+        return
+      }
+
+      const handler = handlers[parsed.command ?? '']
+      if (!handler) {
+        reply(404, { ok: false, error: `Unknown command '${parsed.command}'.` })
+        return
+      }
+      if (parsed.command !== 'status' && parsed.command !== 'logs' && appExited()) {
+        reply(409, {
+          ok: false,
+          error: "The app is not running (it exited or crashed). Run 'drive logs', then 'drive stop' and start again."
+        })
+        return
+      }
+      try {
+        reply(200, { ok: true, result: await handler(parsed.args ?? {}) })
+      } catch (e) {
+        reply(200, { ok: false, error: e?.message ?? String(e) })
+      }
+    })
+  })
+
+  server.listen(0, '127.0.0.1', () => {
+    const state = {
+      pid: process.pid,
+      port: server.address().port,
+      token,
+      mode,
+      profile,
+      dataDir,
+      electronPid,
+      startedAt: new Date().toISOString()
+    }
+    writeFileSync(statePath(), JSON.stringify(state, null, 2), { mode: 0o600 })
+    log(`Listening on 127.0.0.1:${state.port}`)
+  })
+
+  const shutdown = async () => {
+    await stop().catch(() => {})
+    rmSync(statePath(), { force: true })
+    process.exit(0)
+  }
+  process.on('SIGTERM', shutdown)
+  process.on('SIGINT', shutdown)
+}
+
+log(`Daemon ${process.pid} starting; log at ${daemonLogPath()}`)
+main()