abelworkflow 0.6.0 → 0.6.2

package/lib/cli.mjs

@@ -1086,9 +1086,16 @@ function commandExists(command) {
   return result.status === 0;
 }
 
+function getRunCommandSpawnOptions(platform = getPlatform()) {
+  return {
+    stdio: "inherit",
+    shell: platform === "win32"
+  };
+}
+
 async function runCommand(command, args) {
   await new Promise((resolvePromise, rejectPromise) => {
-    const child = spawn(command, args, { stdio: "inherit" });
+    const child = spawn(command, args, getRunCommandSpawnOptions());
     child.on("error", rejectPromise);
     child.on("close", (code) => {
       if (code === 0) {
@@ -2029,6 +2036,7 @@ async function main() {
 
 export {
   buildCodexConfigContent,
+  getRunCommandSpawnOptions,
   main,
   mergeCodexAuthData,
   mergeClaudeSettingsWithDefaults,

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "abelworkflow",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "Install AbelWorkflow into ~/.agents and create Claude/Codex symlinks.",
   "type": "module",
   "bin": {
-    "abelworkflow": "./bin/abelworkflow.mjs"
+    "abelworkflow": "bin/abelworkflow.mjs"
   },
   "files": [
     "bin",

package/skills/dev-browser/SKILL.md

@@ -15,64 +15,80 @@ Browser automation that maintains page state across script executions. Write sma
 
 ## Setup
 
-Two modes available. Ask the user if unclear which to use.
+Two supported startup modes are available on **Linux** and **native Windows**. Run the following commands from the installed `dev-browser` skill directory. Bash, Git Bash, and WSL are not required.
 
-### Resolving SKILL_DIR
+### Standalone Mode (Default)
 
-Prepend this to every Bash snippet (each starts a fresh shell). All examples below use `### SKILL_DIR ###` as a placeholder for this block:
+Launches a new Chromium browser for fresh automation sessions.
 
-```bash
-SKILL_DIR=$(bash skills/dev-browser/resolve-skill-dir.sh 2>/dev/null) || { echo "Skill not found: dev-browser" >&2; exit 1; }
+```text
+npx tsx scripts/start.ts standalone
 ```
 
-### Standalone Mode (Default)
-
-Launches a new Chromium browser for fresh automation sessions.
+Add `--headless` if needed:
 
-```bash
-### SKILL_DIR ###
-bash "$SKILL_DIR/server.sh" &
+```text
+npx tsx scripts/start.ts standalone --headless
 ```
 
-Add `--headless` flag if user requests it. **Wait for the `Ready` message before running scripts.**
+Wait for the stable readiness line `Ready` before running scripts.
 
 ### Extension Mode
 
-Connects to user's existing Chrome browser. Use this when:
+Connects to the user's existing Chrome browser. Use this when:
 
 - The user is already logged into sites and wants you to do things behind an authed experience that isn't local dev.
-- The user asks you to use the extension
-
-**Important**: The core flow is still the same. You create named pages inside of their browser.
+- The user asks you to use the extension.
 
-**Start the relay server:**
+Start the relay server with:
 
-```bash
-### SKILL_DIR ###
-(cd "$SKILL_DIR" && npm i && npm run start-extension) &
+```text
+npx tsx scripts/start.ts extension
 ```
 
-Wait for `Waiting for extension to connect...` followed by `Extension connected` in the console. To know that a client has connected and the browser is ready to be controlled.
-**Workflow:**
-
-1. Scripts call `client.page("name")` just like the normal mode to create new pages / connect to existing ones.
-2. Automation runs on the user's actual browser session
+Wait for `Waiting for extension to connect...`. Once the browser extension attaches, the relay logs `Extension connected`.
 
 If the extension hasn't connected yet, tell the user to launch and activate it. Download link: https://github.com/SawyerHood/dev-browser/releases
 
+## Support Matrix
+
+| Mode | Linux | Native Windows | Readiness signal | Notes |
+|------|-------|----------------|------------------|-------|
+| standalone mode | Supported | Supported | `Ready` | Launches a managed Chromium profile under `profiles/` |
+| extension mode | Supported | Supported | `Waiting for extension to connect...` then `Extension connected` | Requires the external browser extension to attach |
+
+## Verification Checklist
+
+- Start `standalone mode` with `npx tsx scripts/start.ts standalone`
+- Observe the readiness line `Ready`
+- Connect with `connect()` and create a named page
+- Start `extension mode` with `npx tsx scripts/start.ts extension`
+- Observe `Waiting for extension to connect...`
+- Attach the browser extension and confirm `Extension connected`
+
+## Known Differences
+
+- `standalone mode` launches and owns its own Chromium profile under this skill directory.
+- `extension mode` depends on the external browser extension and the user's existing Chrome session.
+- In `extension mode`, relay readiness means the server is waiting for the extension; it does not imply browser control is available until `Extension connected` appears.
+- `standalone mode` is the default path for deterministic local automation; `extension mode` is for working inside an already-authenticated browser.
+
+## Non-goal Environments
+
+- `WSL` and `Git Bash` are not part of the supported Windows path for this skill.
+- Native Windows support means PowerShell / Command Prompt can use the documented entrypoints directly.
+- If a user runs inside WSL or Git Bash, treat that as a separate environment rather than the official Windows support contract.
+
 ## Writing Scripts
 
-> **Each standalone Bash snippet resolves `SKILL_DIR` inside the same snippet before changing directories.** The `@/` import alias requires the skill root's config.
+Use small TypeScript files under `tmp/` instead of shell heredocs. Run them from the same `dev-browser` skill directory so the `@/` import alias resolves correctly.
 
-Execute scripts inline using heredocs:
+Example script (`tmp/example.ts`):
 
-```bash
-### SKILL_DIR ###
-(cd "$SKILL_DIR" && npx tsx <<'EOF'
+```typescript
 import { connect, waitForPageLoad } from "@/client.js";
 
 const client = await connect();
-// Create page with custom viewport size (optional)
 const page = await client.page("example", { viewport: { width: 1920, height: 1080 } });
 
 await page.goto("https://example.com");
@@ -80,8 +96,12 @@ await waitForPageLoad(page);
 
 console.log({ title: await page.title(), url: page.url() });
 await client.disconnect();
-EOF
-)
+```
+
+Run it with:
+
+```text
+npx tsx tmp/example.ts
 ```
 
 **Write to `tmp/` files only when** the script needs reuse, is complex, or user explicitly requests it.
@@ -202,11 +222,9 @@ await element.click();
 
 ## Error Recovery
 
-Page state persists after failures. Re-resolve `SKILL_DIR` (see top of file) before debugging:
+Page state persists after failures. To inspect the current state, save a short script such as `tmp/debug.ts` and run it from the `dev-browser` skill directory:
 
-```bash
-### SKILL_DIR ###
-(cd "$SKILL_DIR" && npx tsx <<'EOF'
+```typescript
 import { connect } from "@/client.js";
 
 const client = await connect();
@@ -220,6 +238,10 @@ console.log({
 });
 
 await client.disconnect();
-EOF
-)
+```
+
+Run it with:
+
+```text
+npx tsx tmp/debug.ts
 ```

package/skills/dev-browser/bun.lock

@@ -5,14 +5,21 @@
     "": {
       "name": "dev-browser",
       "dependencies": {
+        "@hono/node-server": "^1.19.7",
+        "@hono/node-ws": "^1.2.0",
         "express": "^4.21.0",
+        "hono": "^4.11.1",
         "playwright": "^1.49.0",
       },
       "devDependencies": {
         "@types/express": "^5.0.0",
         "tsx": "^4.21.0",
+        "typescript": "^5.0.0",
         "vitest": "^2.1.0",
       },
+      "optionalDependencies": {
+        "@rollup/rollup-linux-x64-gnu": "^4.0.0",
+      },
     },
   },
   "packages": {
@@ -68,6 +75,10 @@
 
     "@esbuild/win32-x64": ["@esbuild/win32-x64@0.27.1", "", { "os": "win32", "cpu": "x64" }, "sha512-d5X6RMYv6taIymSk8JBP+nxv8DQAMY6A51GPgusqLdK9wBz5wWIXy1KjTck6HnjE9hqJzJRdk+1p/t5soSbCtw=="],
 
+    "@hono/node-server": ["@hono/node-server@1.19.14", "", { "peerDependencies": { "hono": "^4" } }, "sha512-GwtvgtXxnWsucXvbQXkRgqksiH2Qed37H9xHZocE5sA3N8O8O8/8FA3uclQXxXVzc9XBZuEOMK7+r02FmSpHtw=="],
+
+    "@hono/node-ws": ["@hono/node-ws@1.3.0", "", { "dependencies": { "ws": "^8.17.0" }, "peerDependencies": { "@hono/node-server": "^1.19.2", "hono": "^4.6.0" } }, "sha512-ju25YbbvLuXdqBCmLZLqnNYu1nbHIQjoyUqA8ApZOeL1k4skuiTcw5SW77/5SUYo2Xi2NVBJoVlfQurnKEp03Q=="],
+
     "@jridgewell/sourcemap-codec": ["@jridgewell/sourcemap-codec@1.5.5", "", {}, "sha512-cYQ9310grqxueWbl+WuIUIaiUaDcj7WOq5fVhEljNVgRfOUhY9fy2zTvfoqWsnebh8Sl70VScFbICvJnLKB0Og=="],
 
     "@rollup/rollup-android-arm-eabi": ["@rollup/rollup-android-arm-eabi@4.53.3", "", { "os": "android", "cpu": "arm" }, "sha512-mRSi+4cBjrRLoaal2PnqH82Wqyb+d3HsPUN/W+WslCXsZsyHa9ZeQQX/pQsZaVIWDkPcpV6jJ+3KLbTbgnwv8w=="],
@@ -234,6 +245,8 @@
 
     "hasown": ["hasown@2.0.2", "", { "dependencies": { "function-bind": "^1.1.2" } }, "sha512-0hJU9SCPvmMzIBdZFqNPXWa6dqh7WdH0cII9y+CyS8rG3nL48Bclra9HmKhVVUHyPWNH5Y7xDwAB7bfgSjkUMQ=="],
 
+    "hono": ["hono@4.12.12", "", {}, "sha512-p1JfQMKaceuCbpJKAPKVqyqviZdS0eUxH9v82oWo1kb9xjQ5wA6iP3FNVAPDFlz5/p7d45lO+BpSk1tuSZMF4Q=="],
+
     "http-errors": ["http-errors@2.0.1", "", { "dependencies": { "depd": "~2.0.0", "inherits": "~2.0.4", "setprototypeof": "~1.2.0", "statuses": "~2.0.2", "toidentifier": "~1.0.1" } }, "sha512-4FbRdAX+bSdmo4AUFuS0WNiPz8NgFt+r8ThgNWmlrjQjt1Q7ZR9+zTlce2859x4KSXrwIsaeTqDoKQmtP8pLmQ=="],
 
     "iconv-lite": ["iconv-lite@0.4.24", "", { "dependencies": { "safer-buffer": ">= 2.1.2 < 3" } }, "sha512-v3MXnZAcvnywkTUEZomIActle7RXXeedOR31wwl7VlyoXO4Qi9arvSenNQWne1TcRwhCL1HwLI21bEqdpj8/rA=="],
@@ -342,6 +355,8 @@
 
     "type-is": ["type-is@1.6.18", "", { "dependencies": { "media-typer": "0.3.0", "mime-types": "~2.1.24" } }, "sha512-TkRKr9sUTxEH8MdfuCSP7VizJyzRNMjj2J2do2Jr3Kym598JVdEksuzPQCnlFPW4ky9Q+iA+ma9BGm06XQBy8g=="],
 
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
     "undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],
 
     "unpipe": ["unpipe@1.0.0", "", {}, "sha512-pjy2bYhSsufwWlKwPc+l3cN7+wuJlK6uz0YdJEOlQDbl6jo/YlPi4mb8agUkVC8BF7V8NuzeyPNqRksA3hztKQ=="],
@@ -358,6 +373,8 @@
 
     "why-is-node-running": ["why-is-node-running@2.3.0", "", { "dependencies": { "siginfo": "^2.0.0", "stackback": "0.0.2" }, "bin": { "why-is-node-running": "cli.js" } }, "sha512-hUrmaWBdVDcxvYqnyh09zunKzROWjbZTiNy8dBEjkS7ehEDQibXJ7XvlmtbwuTclUiIyN+CyXQD4Vmko8fNm8w=="],
 
+    "ws": ["ws@8.20.0", "", { "peerDependencies": { "bufferutil": "^4.0.1", "utf-8-validate": ">=5.0.2" }, "optionalPeers": ["bufferutil", "utf-8-validate"] }, "sha512-sAt8BhgNbzCtgGbt2OxmpuryO63ZoDk/sqaB/znQm94T4fCEsy/yV+7CdC1kJhOU9lboAEU7R3kquuycDoibVA=="],
+
     "body-parser/debug": ["debug@2.6.9", "", { "dependencies": { "ms": "2.0.0" } }, "sha512-bC7ElrdJaJnPbAP+1EotYvqZsb3ecl5wi6Bfi6BJTUcNowp6cvspg0jXznRTKDjm/E7AdgFBVeAPVMNcKGsHMA=="],
 
     "express/debug": ["debug@2.6.9", "", { "dependencies": { "ms": "2.0.0" } }, "sha512-bC7ElrdJaJnPbAP+1EotYvqZsb3ecl5wi6Bfi6BJTUcNowp6cvspg0jXznRTKDjm/E7AdgFBVeAPVMNcKGsHMA=="],

package/skills/dev-browser/package.json

@@ -6,8 +6,8 @@
     "@/*": "./src/*"
   },
   "scripts": {
-    "start-server": "npx tsx scripts/start-server.ts",
-    "start-extension": "npx tsx scripts/start-relay.ts",
+    "start-server": "npx tsx scripts/start.ts standalone",
+    "start-extension": "npx tsx scripts/start.ts extension",
     "dev": "npx tsx --watch src/index.ts",
     "test": "vitest run",
     "test:watch": "vitest"

package/skills/dev-browser/scripts/start.ts

@@ -0,0 +1,279 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync } from "node:fs";
+import { spawn, spawnSync } from "node:child_process";
+import { join } from "node:path";
+
+import { formatHttpUrl, parseEntrypointArgs, resolveHostForProbe } from "@/entrypoint.js";
+import {
+  commandExists,
+  findAvailablePackageManager,
+  getMissingPackageDependencies,
+  isPlaywrightChromiumInstalled,
+  resolveSkillDirFromEntrypoint,
+  resolveRuntimePaths,
+  shouldUseShellForPackageCommands,
+} from "@/runtime.js";
+import {
+  ensurePlaywrightChromium,
+  preflightStandaloneStartup,
+  runEntrypoint,
+} from "@/startup.js";
+
+const runtimePaths = resolveRuntimePaths(resolveSkillDirFromEntrypoint(import.meta.url));
+const useShell = shouldUseShellForPackageCommands(process.platform);
+
+async function main() {
+  const args = parseEntrypointArgs(process.argv.slice(2));
+  await ensureSkillDependencies();
+
+  await runEntrypoint(args, {
+    runtimePaths,
+    mkdir: mkdirSync,
+    serveStandalone: async (options) => {
+      const { serve } = await import("@/index.js");
+      return serve(options);
+    },
+    serveExtension: async (options) => {
+      const { serveRelay } = await import("@/relay.js");
+      return serveRelay(options);
+    },
+    registerShutdown,
+    keepAlive: () => new Promise(() => {}),
+    log: (line) => console.log(line),
+    ensureBrowser: () =>
+      ensurePlaywrightChromium({
+        isInstalled: () =>
+          isPlaywrightChromiumInstalled({
+            platform: process.platform,
+            env: process.env,
+            exists: existsSync,
+            readDir: readdirSync,
+          }),
+        findPackageManager: () =>
+          findAvailablePackageManager((command) =>
+            commandExists(command, (candidate) =>
+              spawnSync(candidate, ["--version"], {
+                stdio: "ignore",
+                shell: useShell,
+                windowsHide: useShell,
+              })
+            )
+          ),
+        runCommand,
+        log: (line) => console.log(line),
+      }),
+    preflightStandalone: () =>
+      preflightStandaloneStartup(args, {
+        checkServer: async (host, port) => {
+          try {
+            const response = await fetch(formatHttpUrl(resolveHostForProbe(host), port), {
+              signal: AbortSignal.timeout(1000),
+            });
+            if (!response.ok) {
+              return { ok: false };
+            }
+            const info = (await response.json()) as { wsEndpoint?: string };
+            return { ok: true, info };
+          } catch {
+            return { ok: false };
+          }
+        },
+        isPortInUse,
+        browserDataDir: runtimePaths.browserDataDir,
+        recoverStaleBrowser: ({ cdpPort, browserDataDir }) =>
+          recoverStaleDevBrowserChromium({
+            cdpPort,
+            browserDataDir,
+            isPortInUse,
+            log: (line) => console.log(line),
+          }),
+        log: (line) => console.log(line),
+      }),
+  });
+}
+
+async function ensureSkillDependencies() {
+  const packageJson = JSON.parse(readFileSync(join(runtimePaths.skillDir, "package.json"), "utf8")) as {
+    dependencies?: Record<string, string>;
+  };
+  const missingDependencies = getMissingPackageDependencies({
+    skillDir: runtimePaths.skillDir,
+    dependencies: Object.keys(packageJson.dependencies ?? {}),
+    exists: existsSync,
+  });
+
+  if (missingDependencies.length === 0) {
+    return;
+  }
+
+  console.log("dev-browser dependencies not found. Installing local packages...");
+  await runCommand("npm", ["install"]);
+  console.log("dev-browser dependencies installed.");
+}
+
+async function runCommand(command: string, args: string[]) {
+  await new Promise<void>((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd: runtimePaths.skillDir,
+      stdio: "inherit",
+      shell: useShell,
+      windowsHide: useShell,
+    });
+    child.on("error", reject);
+    child.on("close", (code) => {
+      if (code === 0) {
+        resolve();
+        return;
+      }
+      reject(new Error(`${command} ${args.join(" ")} exited with code ${code}`));
+    });
+  });
+}
+
+async function isPortInUse(port: number) {
+  const socket = await import("node:net");
+  return await new Promise<boolean>((resolve) => {
+    const server = socket.createServer();
+    server.once("error", () => resolve(true));
+    server.once("listening", () => {
+      server.close(() => resolve(false));
+    });
+    server.listen(port, "127.0.0.1");
+  });
+}
+
+async function recoverStaleDevBrowserChromium({
+  cdpPort,
+  browserDataDir,
+  isPortInUse,
+  log,
+}: {
+  cdpPort: number;
+  browserDataDir: string;
+  isPortInUse: (port: number) => Promise<boolean>;
+  log: (line: string) => void;
+}) {
+  const pid = findListeningPid(cdpPort);
+  if (!pid) {
+    return false;
+  }
+
+  const commandLine = readProcessCommandLine(pid);
+  if (!commandLine || !isOwnedDevBrowserProcess(commandLine, browserDataDir, cdpPort)) {
+    return false;
+  }
+
+  log(`Cleaning up stale dev-browser Chromium on CDP port ${cdpPort} (PID: ${pid})`);
+  if (!terminateProcess(pid)) {
+    return false;
+  }
+
+  const deadline = Date.now() + 3000;
+  while (Date.now() < deadline) {
+    if (!(await isPortInUse(cdpPort))) {
+      return true;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+
+  return !(await isPortInUse(cdpPort));
+}
+
+function findListeningPid(port: number): number | null {
+  if (process.platform === "win32") {
+    const result = runCapture("powershell.exe", [
+      "-NoProfile",
+      "-Command",
+      `Get-NetTCPConnection -LocalPort ${port} -State Listen -ErrorAction SilentlyContinue | Select-Object -ExpandProperty OwningProcess -First 1`,
+    ]);
+    return parsePid(result.stdout);
+  }
+
+  const result = runCapture("lsof", ["-nP", `-iTCP:${port}`, "-sTCP:LISTEN", "-t"]);
+  return parsePid(result.stdout);
+}
+
+function readProcessCommandLine(pid: number): string | null {
+  if (process.platform === "win32") {
+    const result = runCapture("powershell.exe", [
+      "-NoProfile",
+      "-Command",
+      `(Get-CimInstance Win32_Process -Filter "ProcessId = ${pid}").CommandLine`,
+    ]);
+    return normalizeOutput(result.stdout);
+  }
+
+  const result = runCapture("ps", ["-p", String(pid), "-o", "args="]);
+  return normalizeOutput(result.stdout);
+}
+
+function isOwnedDevBrowserProcess(commandLine: string, browserDataDir: string, cdpPort: number): boolean {
+  const normalizedCommandLine = normalizePathLike(commandLine);
+  const normalizedBrowserDataDir = normalizePathLike(browserDataDir);
+
+  return (
+    normalizedCommandLine.includes(`--remote-debugging-port=${cdpPort}`) &&
+    normalizedCommandLine.includes("--user-data-dir=") &&
+    normalizedCommandLine.includes(normalizedBrowserDataDir)
+  );
+}
+
+function terminateProcess(pid: number): boolean {
+  if (process.platform === "win32") {
+    return runCapture("taskkill", ["/PID", String(pid), "/T", "/F"]).status === 0;
+  }
+
+  try {
+    process.kill(pid, "SIGKILL");
+    return true;
+  } catch (error) {
+    return error instanceof Error && "code" in error && error.code === "ESRCH";
+  }
+}
+
+function runCapture(command: string, args: string[]) {
+  const result = spawnSync(command, args, {
+    cwd: runtimePaths.skillDir,
+    encoding: "utf8",
+    shell: false,
+    windowsHide: true,
+  });
+
+  return {
+    status: result.status,
+    stdout: typeof result.stdout === "string" ? result.stdout : "",
+  };
+}
+
+function parsePid(stdout: string): number | null {
+  const value = normalizeOutput(stdout);
+  if (!value) {
+    return null;
+  }
+
+  const pid = Number.parseInt(value.split(/\s+/)[0] ?? "", 10);
+  return Number.isInteger(pid) && pid > 0 ? pid : null;
+}
+
+function normalizeOutput(stdout: string): string | null {
+  const value = stdout.trim();
+  return value.length > 0 ? value : null;
+}
+
+function normalizePathLike(value: string): string {
+  return value.replaceAll("\\", "/").toLowerCase();
+}
+
+function registerShutdown(stop: () => Promise<void>) {
+  const shutdown = async () => {
+    await stop();
+    process.exit(0);
+  };
+
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+}
+
+main().catch((error) => {
+  console.error("Failed to start dev-browser:", error);
+  process.exit(1);
+});

package/skills/dev-browser/src/entrypoint.ts

@@ -0,0 +1,157 @@
+export type EntrypointMode = "standalone" | "extension";
+
+export interface EntrypointArgs {
+  mode: EntrypointMode;
+  host: string;
+  port: number;
+  cdpPort: number;
+  headless: boolean;
+}
+
+export interface StandaloneReadinessInfo {
+  mode: "standalone";
+  host: string;
+  port: number;
+  wsEndpoint: string;
+  tmpDir: string;
+  profileDir: string;
+}
+
+export interface ExtensionReadinessInfo {
+  mode: "extension";
+  host: string;
+  port: number;
+  wsEndpoint: string;
+}
+
+export type ReadinessInfo = StandaloneReadinessInfo | ExtensionReadinessInfo;
+
+export const DEFAULT_HOST = "localhost";
+const DEFAULT_PORT = 9222;
+const DEFAULT_CDP_PORT = 9223;
+
+export function formatHostForUrl(host: string): string {
+  const normalizedHost =
+    host.startsWith("[") && host.endsWith("]") ? host.slice(1, -1) : host;
+  return normalizedHost.includes(":") ? `[${normalizedHost}]` : normalizedHost;
+}
+
+export function formatHttpUrl(host: string, port: number): string {
+  return `http://${formatHostForUrl(host)}:${port}`;
+}
+
+export function formatWsUrl(host: string, port: number, path = ""): string {
+  return `ws://${formatHostForUrl(host)}:${port}${path}`;
+}
+
+export function resolveHostForProbe(host: string): string {
+  const normalizedHost =
+    host.startsWith("[") && host.endsWith("]") ? host.slice(1, -1) : host;
+
+  if (normalizedHost === "0.0.0.0") {
+    return "127.0.0.1";
+  }
+
+  if (normalizedHost === "::") {
+    return "::1";
+  }
+
+  return normalizedHost;
+}
+
+export function parseEntrypointArgs(
+  argv: string[],
+  env: Record<string, string | undefined> = process.env
+): EntrypointArgs {
+  let index = 0;
+  let mode: EntrypointMode = "standalone";
+
+  const first = argv[0];
+  if (first && !first.startsWith("--")) {
+    if (first !== "standalone" && first !== "extension") {
+      throw new Error(`Unknown mode: ${first}`);
+    }
+    mode = first;
+    index = 1;
+  }
+
+  const args: EntrypointArgs = {
+    mode,
+    host: env.HOST?.trim() || DEFAULT_HOST,
+    port: readEnvPort(env.PORT, "PORT") ?? DEFAULT_PORT,
+    cdpPort: DEFAULT_CDP_PORT,
+    headless: env.HEADLESS?.trim().toLowerCase() === "true",
+  };
+
+  while (index < argv.length) {
+    const token = argv[index++];
+    switch (token) {
+      case "--headless":
+        args.headless = true;
+        break;
+      case "--host":
+        args.host = readValue(argv, index - 1);
+        index += 1;
+        break;
+      case "--port":
+        args.port = parsePort(readValue(argv, index - 1), "port");
+        index += 1;
+        break;
+      case "--cdp-port":
+        args.cdpPort = parsePort(readValue(argv, index - 1), "cdpPort");
+        index += 1;
+        break;
+      default:
+        throw new Error(`Unknown argument: ${token}`);
+    }
+  }
+
+  return args;
+}
+
+export function formatReadinessLines(info: ReadinessInfo): string[] {
+  if (info.mode === "standalone") {
+    return [
+      "Dev browser server started",
+      `  HTTP: ${formatHttpUrl(info.host, info.port)}`,
+      `  WebSocket: ${info.wsEndpoint}`,
+      `  Tmp directory: ${info.tmpDir}`,
+      `  Profile directory: ${info.profileDir}`,
+      "",
+      "Ready",
+    ];
+  }
+
+  return [
+    "CDP relay server started",
+    `  HTTP: ${formatHttpUrl(info.host, info.port)}`,
+    `  CDP endpoint: ${info.wsEndpoint}`,
+    `  Extension endpoint: ${formatWsUrl(info.host, info.port, "/extension")}`,
+    "",
+    "Waiting for extension to connect...",
+  ];
+}
+
+function readValue(argv: string[], optionIndex: number): string {
+  const value = argv[optionIndex + 1];
+  if (!value || value.startsWith("--")) {
+    throw new Error(`Missing value for ${argv[optionIndex]}`);
+  }
+  return value;
+}
+
+function parsePort(value: string, label: string): number {
+  const port = Number.parseInt(value, 10);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new Error(`Invalid ${label}: ${value}`);
+  }
+  return port;
+}
+
+function readEnvPort(value: string | undefined, label: string): number | undefined {
+  const normalized = value?.trim();
+  if (!normalized) {
+    return undefined;
+  }
+  return parsePort(normalized, label);
+}

package/skills/dev-browser/src/index.ts

@@ -3,6 +3,7 @@ import { chromium, type BrowserContext, type Page } from "playwright";
 import { mkdirSync } from "fs";
 import { join } from "path";
 import type { Socket } from "net";
+import { formatHttpUrl } from "./entrypoint";
 import type {
   ServeOptions,
   GetPageRequest,
@@ -53,6 +54,7 @@ function withTimeout<T>(promise: Promise<T>, ms: number, message: string): Promi
 
 export async function serve(options: ServeOptions = {}): Promise<DevBrowserServer> {
   const port = options.port ?? 9222;
+  const host = options.host ?? "localhost";
   const headless = options.headless ?? false;
   const cdpPort = options.cdpPort ?? 9223;
   const profileDir = options.profileDir;
@@ -191,8 +193,8 @@ export async function serve(options: ServeOptions = {}): Promise<DevBrowserServe
   });
 
   // Start the server
-  const server = app.listen(port, () => {
-    console.log(`HTTP API server running on port ${port}`);
+  const server = app.listen(port, host, () => {
+    console.log(`HTTP API server running on ${formatHttpUrl(host, port)}`);
   });
 
   // Track active connections for clean shutdown

package/skills/dev-browser/src/runtime.ts

@@ -0,0 +1,147 @@
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export interface CommandStatusResult {
+  status: number | null;
+}
+
+export interface PackageManager {
+  name: "bun" | "pnpm" | "npm";
+  command: string;
+  args: string[];
+}
+
+export interface ChromiumInstallCheckOptions {
+  platform: NodeJS.Platform;
+  env: NodeJS.ProcessEnv;
+  exists: (path: string) => boolean;
+  readDir: (path: string) => string[];
+}
+
+export interface MissingPackageDependenciesOptions {
+  skillDir: string;
+  dependencies: string[];
+  exists: (path: string) => boolean;
+}
+
+export function commandExists(
+  command: string,
+  runCheck: (command: string) => CommandStatusResult
+): boolean {
+  return runCheck(command).status === 0;
+}
+
+export function findAvailablePackageManager(
+  hasCommand: (command: string) => boolean
+): PackageManager | null {
+  const candidates: PackageManager[] = [
+    {
+      name: "bun",
+      command: "bunx",
+      args: ["playwright", "install", "chromium"],
+    },
+    {
+      name: "pnpm",
+      command: "pnpm",
+      args: ["exec", "playwright", "install", "chromium"],
+    },
+    {
+      name: "npm",
+      command: "npx",
+      args: ["playwright", "install", "chromium"],
+    },
+  ];
+
+  for (const candidate of candidates) {
+    const probe = candidate.name === "npm" ? "npm" : candidate.name;
+    if (hasCommand(probe)) {
+      return candidate;
+    }
+  }
+
+  return null;
+}
+
+export function getPlaywrightInstallCommand(manager: PackageManager): string {
+  return [manager.command, ...manager.args].join(" ");
+}
+
+export function getPlaywrightBrowserRoots({
+  platform,
+  env,
+}: {
+  platform: NodeJS.Platform;
+  env: NodeJS.ProcessEnv;
+}): string[] {
+  const explicitPath = env.PLAYWRIGHT_BROWSERS_PATH?.trim();
+  if (explicitPath) {
+    return [explicitPath];
+  }
+
+  if (platform === "win32") {
+    const userProfile = env.USERPROFILE ?? env.HOME;
+    return userProfile ? [join(userProfile, "AppData", "Local", "ms-playwright")] : [];
+  }
+
+  const home = env.HOME ?? env.USERPROFILE;
+  return home ? [join(home, ".cache", "ms-playwright")] : [];
+}
+
+export function isPlaywrightChromiumInstalled({
+  platform,
+  env,
+  exists,
+  readDir,
+}: ChromiumInstallCheckOptions): boolean {
+  for (const root of getPlaywrightBrowserRoots({ platform, env })) {
+    if (!exists(root)) {
+      continue;
+    }
+
+    try {
+      const entries = readDir(root);
+      if (entries.some((entry) => entry.startsWith("chromium"))) {
+        return true;
+      }
+    } catch {
+      // Ignore unreadable directories and continue probing.
+    }
+  }
+
+  return false;
+}
+
+export function getMissingPackageDependencies({
+  skillDir,
+  dependencies,
+  exists,
+}: MissingPackageDependenciesOptions): string[] {
+  return dependencies.filter(
+    (dependency) =>
+      !exists(join(skillDir, "node_modules", ...dependency.split("/"), "package.json"))
+  );
+}
+
+export function resolveRuntimePaths(skillDir: string) {
+  const tmpDir = join(skillDir, "tmp");
+  const profileDir = join(skillDir, "profiles");
+
+  return {
+    skillDir,
+    tmpDir,
+    profileDir,
+    browserDataDir: join(profileDir, "browser-data"),
+  };
+}
+
+export function resolveImportMetaDir(moduleUrl: string): string {
+  return dirname(fileURLToPath(moduleUrl));
+}
+
+export function resolveSkillDirFromEntrypoint(moduleUrl: string): string {
+  return dirname(resolveImportMetaDir(moduleUrl));
+}
+
+export function shouldUseShellForPackageCommands(platform: NodeJS.Platform): boolean {
+  return platform === "win32";
+}

package/skills/dev-browser/src/snapshot/browser-script.ts

@@ -11,6 +11,7 @@
 
 import * as fs from "fs";
 import * as path from "path";
+import { fileURLToPath } from "node:url";
 
 // Cache the bundled script
 let cachedScript: string | null = null;
@@ -26,7 +27,7 @@ export function getSnapshotScript(): string {
   if (cachedScript) return cachedScript;
 
   // Read the compiled JavaScript files
-  const snapshotDir = path.dirname(new URL(import.meta.url).pathname);
+  const snapshotDir = path.dirname(fileURLToPath(import.meta.url));
 
   // For now, we'll inline the functions directly
   // In production, we could use a bundler like esbuild to create a single file

package/skills/dev-browser/src/startup.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, it, vi } from "vitest";
+
+import {
+  DEFAULT_HOST,
+  formatHttpUrl,
+  formatReadinessLines,
+  parseEntrypointArgs,
+  resolveHostForProbe,
+} from "./entrypoint.js";
+import { preflightStandaloneStartup } from "./startup.js";
+
+describe("entrypoint host handling", () => {
+  it("defaults standalone host to localhost", () => {
+    const args = parseEntrypointArgs([], {});
+
+    expect(args.host).toBe(DEFAULT_HOST);
+    expect(args.host).toBe("localhost");
+  });
+
+  it("formats IPv6 hosts in readiness output", () => {
+    expect(formatHttpUrl("::1", 9222)).toBe("http://[::1]:9222");
+
+    expect(
+      formatReadinessLines({
+        mode: "standalone",
+        host: "::1",
+        port: 9222,
+        wsEndpoint: "ws://127.0.0.1:9223/devtools/browser/test",
+        tmpDir: "/tmp/dev-browser",
+        profileDir: "/tmp/dev-browser/profile",
+      })
+    ).toContain("  HTTP: http://[::1]:9222");
+  });
+
+  it("normalizes wildcard hosts to a reachable probe target", () => {
+    expect(resolveHostForProbe("0.0.0.0")).toBe("127.0.0.1");
+    expect(resolveHostForProbe("::")).toBe("::1");
+    expect(resolveHostForProbe("[::1]")).toBe("::1");
+    expect(resolveHostForProbe("localhost")).toBe("localhost");
+  });
+});
+
+describe("preflightStandaloneStartup", () => {
+  it("checks the configured host before starting", async () => {
+    const checkServer = vi.fn().mockResolvedValue({ ok: false });
+    const isPortInUse = vi.fn().mockResolvedValue(false);
+    const log = vi.fn();
+
+    await expect(
+      preflightStandaloneStartup(
+        {
+          mode: "standalone",
+          host: "::1",
+          port: 9222,
+          cdpPort: 9223,
+          headless: false,
+        },
+        {
+          checkServer,
+          isPortInUse,
+          log,
+        }
+      )
+    ).resolves.toBe(true);
+
+    expect(checkServer).toHaveBeenCalledWith("::1", 9222);
+  });
+
+  it("short-circuits when the configured host already has a server", async () => {
+    const checkServer = vi.fn().mockResolvedValue({ ok: true, info: { wsEndpoint: "ws://test" } });
+    const isPortInUse = vi.fn();
+    const log = vi.fn();
+
+    await expect(
+      preflightStandaloneStartup(
+        {
+          mode: "standalone",
+          host: "localhost",
+          port: 9222,
+          cdpPort: 9223,
+          headless: false,
+        },
+        {
+          checkServer,
+          isPortInUse,
+          log,
+        }
+      )
+    ).resolves.toBe(false);
+
+    expect(checkServer).toHaveBeenCalledWith("localhost", 9222);
+    expect(isPortInUse).not.toHaveBeenCalled();
+    expect(log).toHaveBeenCalledWith("Server already running on port 9222");
+  });
+});

package/skills/dev-browser/src/startup.ts

@@ -0,0 +1,153 @@
+import { formatReadinessLines, type EntrypointArgs } from "./entrypoint.js";
+import type { PackageManager } from "./runtime.js";
+
+export interface RuntimePaths {
+  skillDir: string;
+  tmpDir: string;
+  profileDir: string;
+  browserDataDir: string;
+}
+
+interface StandaloneServer {
+  port: number;
+  wsEndpoint: string;
+  stop: () => Promise<void>;
+}
+
+interface ExtensionServer {
+  port: number;
+  wsEndpoint: string;
+  stop: () => Promise<void>;
+}
+
+export interface RunEntrypointDeps {
+  runtimePaths: RuntimePaths;
+  mkdir: (path: string, options: { recursive: true }) => void;
+  serveStandalone: (options: {
+    port: number;
+    host: string;
+    headless: boolean;
+    cdpPort: number;
+    profileDir: string;
+  }) => Promise<StandaloneServer>;
+  serveExtension: (options: { port: number; host: string }) => Promise<ExtensionServer>;
+  registerShutdown: (stop: () => Promise<void>) => void;
+  keepAlive: () => Promise<void>;
+  log: (line: string) => void;
+  ensureBrowser?: () => Promise<void>;
+  preflightStandalone?: () => Promise<boolean>;
+}
+
+export interface EnsurePlaywrightChromiumDeps {
+  isInstalled: () => boolean;
+  findPackageManager: () => PackageManager | null;
+  runCommand: (command: string, args: string[]) => Promise<void>;
+  log: (line: string) => void;
+}
+
+export interface PreflightStandaloneStartupDeps {
+  checkServer: (host: string, port: number) => Promise<{ ok: boolean; info?: { wsEndpoint?: string } }>;
+  isPortInUse: (port: number) => Promise<boolean>;
+  browserDataDir?: string;
+  recoverStaleBrowser?: (options: { cdpPort: number; browserDataDir: string }) => Promise<boolean>;
+  log: (line: string) => void;
+}
+
+export async function preflightStandaloneStartup(
+  args: EntrypointArgs,
+  deps: PreflightStandaloneStartupDeps
+): Promise<boolean> {
+  const serverCheck = await deps.checkServer(args.host, args.port);
+  if (serverCheck.ok) {
+    deps.log(`Server already running on port ${args.port}`);
+    return false;
+  }
+
+  if (await deps.isPortInUse(args.cdpPort)) {
+    const recovered =
+      deps.browserDataDir && deps.recoverStaleBrowser
+        ? await deps.recoverStaleBrowser({
+            cdpPort: args.cdpPort,
+            browserDataDir: deps.browserDataDir,
+          })
+        : false;
+
+    if (!recovered && (await deps.isPortInUse(args.cdpPort))) {
+      throw new Error(`CDP port ${args.cdpPort} is already in use by another process`);
+    }
+  }
+
+  return true;
+}
+
+export async function ensurePlaywrightChromium(deps: EnsurePlaywrightChromiumDeps) {
+  if (deps.isInstalled()) {
+    deps.log("Playwright Chromium already installed.");
+    return;
+  }
+
+  deps.log("Playwright Chromium not found. Installing (this may take a minute)...");
+  const manager = deps.findPackageManager();
+  if (!manager) {
+    throw new Error("No package manager found (tried bun, pnpm, npm)");
+  }
+
+  deps.log(`Using ${manager.name} to install Playwright...`);
+  await deps.runCommand(manager.command, manager.args);
+  deps.log("Chromium installed successfully.");
+}
+
+export async function runEntrypoint(args: EntrypointArgs, deps: RunEntrypointDeps) {
+  deps.mkdir(deps.runtimePaths.tmpDir, { recursive: true });
+
+  if (args.mode === "extension") {
+    const server = await deps.serveExtension({
+      port: args.port,
+      host: args.host,
+    });
+
+    for (const line of formatReadinessLines({
+      mode: "extension",
+      host: args.host,
+      port: args.port,
+      wsEndpoint: server.wsEndpoint,
+    })) {
+      deps.log(line);
+    }
+
+    deps.registerShutdown(() => server.stop());
+    await deps.keepAlive();
+    return;
+  }
+
+  deps.mkdir(deps.runtimePaths.profileDir, { recursive: true });
+
+  const shouldStart = await deps.preflightStandalone?.();
+  if (shouldStart === false) {
+    return;
+  }
+
+  await deps.ensureBrowser?.();
+
+  const server = await deps.serveStandalone({
+    port: args.port,
+    host: args.host,
+    headless: args.headless,
+    cdpPort: args.cdpPort,
+    profileDir: deps.runtimePaths.profileDir,
+  });
+
+  for (const line of formatReadinessLines({
+    mode: "standalone",
+    host: args.host,
+    port: args.port,
+    wsEndpoint: server.wsEndpoint,
+    tmpDir: deps.runtimePaths.tmpDir,
+    profileDir: deps.runtimePaths.profileDir,
+  })) {
+    deps.log(line);
+  }
+
+  deps.registerShutdown(() => server.stop());
+  await deps.keepAlive();
+}

package/skills/dev-browser/src/types.ts

@@ -2,6 +2,7 @@
 
 export interface ServeOptions {
   port?: number;
+  host?: string;
   headless?: boolean;
   cdpPort?: number;
   /** Directory to store persistent browser profiles (cookies, localStorage, etc.) */

package/skills/context7-auto-research/.env

@@ -1,4 +0,0 @@
-# Context7 API Key Configuration
-# Get your API key from: https://context7.com/dashboard
-
-CONTEXT7_API_KEY=ctx7sk-d4d4d513-e3ae-44ae-b67d-30c046898ecf

package/skills/dev-browser/scripts/start-relay.ts

@@ -1,32 +0,0 @@
-/**
- * Start the CDP relay server for Chrome extension mode
- *
- * Usage: npm run start-extension
- */
-
-import { serveRelay } from "@/relay.js";
-
-const PORT = parseInt(process.env.PORT || "9222", 10);
-const HOST = process.env.HOST || "127.0.0.1";
-
-async function main() {
-  const server = await serveRelay({
-    port: PORT,
-    host: HOST,
-  });
-
-  // Handle shutdown
-  const shutdown = async () => {
-    console.log("\nShutting down relay server...");
-    await server.stop();
-    process.exit(0);
-  };
-
-  process.on("SIGINT", shutdown);
-  process.on("SIGTERM", shutdown);
-}
-
-main().catch((err) => {
-  console.error("Failed to start relay server:", err);
-  process.exit(1);
-});

package/skills/dev-browser/scripts/start-server.ts

@@ -1,117 +0,0 @@
-import { serve } from "@/index.js";
-import { execSync } from "child_process";
-import { mkdirSync, existsSync, readdirSync } from "fs";
-import { join, dirname } from "path";
-import { fileURLToPath } from "url";
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const tmpDir = join(__dirname, "..", "tmp");
-const profileDir = join(__dirname, "..", "profiles");
-
-// Create tmp and profile directories if they don't exist
-console.log("Creating tmp directory...");
-mkdirSync(tmpDir, { recursive: true });
-console.log("Creating profiles directory...");
-mkdirSync(profileDir, { recursive: true });
-
-// Install Playwright browsers if not already installed
-console.log("Checking Playwright browser installation...");
-
-function findPackageManager(): { name: string; command: string } | null {
-  const managers = [
-    { name: "bun", command: "bunx playwright install chromium" },
-    { name: "pnpm", command: "pnpm exec playwright install chromium" },
-    { name: "npm", command: "npx playwright install chromium" },
-  ];
-
-  for (const manager of managers) {
-    try {
-      execSync(`which ${manager.name}`, { stdio: "ignore" });
-      return manager;
-    } catch {
-      // Package manager not found, try next
-    }
-  }
-  return null;
-}
-
-function isChromiumInstalled(): boolean {
-  const homeDir = process.env.HOME || process.env.USERPROFILE || "";
-  const playwrightCacheDir = join(homeDir, ".cache", "ms-playwright");
-
-  if (!existsSync(playwrightCacheDir)) {
-    return false;
-  }
-
-  // Check for chromium directories (e.g., chromium-1148, chromium_headless_shell-1148)
-  try {
-    const entries = readdirSync(playwrightCacheDir);
-    return entries.some((entry) => entry.startsWith("chromium"));
-  } catch {
-    return false;
-  }
-}
-
-try {
-  if (!isChromiumInstalled()) {
-    console.log("Playwright Chromium not found. Installing (this may take a minute)...");
-
-    const pm = findPackageManager();
-    if (!pm) {
-      throw new Error("No package manager found (tried bun, pnpm, npm)");
-    }
-
-    console.log(`Using ${pm.name} to install Playwright...`);
-    execSync(pm.command, { stdio: "inherit" });
-    console.log("Chromium installed successfully.");
-  } else {
-    console.log("Playwright Chromium already installed.");
-  }
-} catch (error) {
-  console.error("Failed to install Playwright browsers:", error);
-  console.log("You may need to run: npx playwright install chromium");
-}
-
-// Check if server is already running
-console.log("Checking for existing servers...");
-try {
-  const res = await fetch("http://localhost:9222", {
-    signal: AbortSignal.timeout(1000),
-  });
-  if (res.ok) {
-    console.log("Server already running on port 9222");
-    process.exit(0);
-  }
-} catch {
-  // Server not running, continue to start
-}
-
-// Clean up stale CDP port if HTTP server isn't running (crash recovery)
-// This handles the case where Node crashed but Chrome is still running on 9223
-try {
-  const pid = execSync("lsof -ti:9223", { encoding: "utf-8" }).trim();
-  if (pid) {
-    console.log(`Cleaning up stale Chrome process on CDP port 9223 (PID: ${pid})`);
-    execSync(`kill -9 ${pid}`);
-  }
-} catch {
-  // No process on CDP port, which is expected
-}
-
-console.log("Starting dev browser server...");
-const headless = process.env.HEADLESS === "true";
-const server = await serve({
-  port: 9222,
-  headless,
-  profileDir,
-});
-
-console.log(`Dev browser server started`);
-console.log(`  WebSocket: ${server.wsEndpoint}`);
-console.log(`  Tmp directory: ${tmpDir}`);
-console.log(`  Profile directory: ${profileDir}`);
-console.log(`\nReady`);
-console.log(`\nPress Ctrl+C to stop`);
-
-// Keep the process running
-await new Promise(() => {});

package/skills/dev-browser/server.sh

@@ -1,24 +0,0 @@
-#!/bin/bash
-
-# Get the directory where this script is located
-SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
-
-# Change to the script directory
-cd "$SCRIPT_DIR"
-
-# Parse command line arguments
-HEADLESS=false
-while [[ "$#" -gt 0 ]]; do
-    case $1 in
-        --headless) HEADLESS=true ;;
-        *) echo "Unknown parameter: $1"; exit 1 ;;
-    esac
-    shift
-done
-
-echo "Installing dependencies..."
-npm install
-
-echo "Starting dev-browser server..."
-export HEADLESS=$HEADLESS
-npx tsx scripts/start-server.ts

package/skills/prompt-enhancer/.env

@@ -1,2 +0,0 @@
-OPENAI_API_KEY=dummy
-PE_MODEL=