opensteer 0.5.1 → 0.5.3

package/dist/cli/skills-installer.d.ts

@@ -0,0 +1,28 @@
+type ParseMode = 'help' | 'install' | 'error';
+interface ParsedSkillsArgs {
+    mode: ParseMode;
+    passthroughArgs: string[];
+    error?: string;
+}
+interface SkillsInstallInvocation {
+    cliPath: string;
+    cliArgs: string[];
+}
+interface SkillsInstallerDeps {
+    resolveSkillsCliPath: () => string;
+    resolveLocalSkillSourcePath: () => string;
+    spawnInvocation: (invocation: SkillsInstallInvocation) => Promise<number>;
+    writeStdout: (message: string) => void;
+    writeStderr: (message: string) => void;
+}
+declare function parseOpensteerSkillsArgs(rawArgs: string[]): ParsedSkillsArgs;
+declare function resolveLocalSkillSourcePath(): string;
+declare function resolveSkillsCliPath(): string;
+declare function createSkillsInstallInvocation(args: {
+    localSkillSourcePath: string;
+    passthroughArgs: string[];
+    skillsCliPath: string;
+}): SkillsInstallInvocation;
+declare function runOpensteerSkillsInstaller(rawArgs: string[], overrideDeps?: Partial<SkillsInstallerDeps>): Promise<number>;
+
+export { createSkillsInstallInvocation, parseOpensteerSkillsArgs, resolveLocalSkillSourcePath, resolveSkillsCliPath, runOpensteerSkillsInstaller };

package/dist/cli/skills-installer.js

@@ -0,0 +1,201 @@
+// src/cli/skills-installer.ts
+import { spawn } from "child_process";
+import { createRequire } from "module";
+import { existsSync, realpathSync } from "fs";
+import { dirname, join, resolve } from "path";
+var HELP_TEXT = `Usage: opensteer skills <install|add> [options]
+
+Installs the first-party Opensteer skill using the upstream "skills" CLI.
+
+Commands:
+  install                  Install the opensteer skill
+  add                      Alias for install
+
+Supported Options:
+  -a, --agent <agents...>  Target specific agent(s)
+  -g, --global             Install globally
+  -y, --yes                Skip confirmations
+  --copy                   Copy files instead of symlinking
+  --all                    Install to all agents
+  -h, --help               Show this help
+
+Examples:
+  opensteer skills install
+  opensteer skills add --agent codex --global --yes
+  opensteer skills install --all --yes
+`;
+function parseOpensteerSkillsArgs(rawArgs) {
+  if (rawArgs.length === 0) {
+    return { mode: "help", passthroughArgs: [] };
+  }
+  const [subcommand, ...rest] = rawArgs;
+  if (subcommand === "help" || subcommand === "--help" || subcommand === "-h") {
+    return { mode: "help", passthroughArgs: [] };
+  }
+  if (subcommand !== "install" && subcommand !== "add") {
+    return {
+      mode: "error",
+      passthroughArgs: [],
+      error: `Unsupported skills subcommand "${subcommand}". Use "install" or "add".`
+    };
+  }
+  const passthroughArgs = [];
+  for (let i = 0; i < rest.length; i += 1) {
+    const arg = rest[i];
+    if (arg === "--help" || arg === "-h") {
+      return { mode: "help", passthroughArgs: [] };
+    }
+    if (arg === "--global" || arg === "-g") {
+      passthroughArgs.push(arg);
+      continue;
+    }
+    if (arg === "--yes" || arg === "-y") {
+      passthroughArgs.push(arg);
+      continue;
+    }
+    if (arg === "--copy" || arg === "--all") {
+      passthroughArgs.push(arg);
+      continue;
+    }
+    if (arg === "--agent" || arg === "-a") {
+      passthroughArgs.push(arg);
+      if (i + 1 >= rest.length || rest[i + 1]?.startsWith("-")) {
+        return {
+          mode: "error",
+          passthroughArgs: [],
+          error: `${arg} requires at least one value.`
+        };
+      }
+      while (i + 1 < rest.length && !rest[i + 1]?.startsWith("-")) {
+        i += 1;
+        const agent = rest[i];
+        if (agent) {
+          passthroughArgs.push(agent);
+        }
+      }
+      continue;
+    }
+    if (arg.startsWith("-")) {
+      return {
+        mode: "error",
+        passthroughArgs: [],
+        error: `Unsupported option "${arg}" for "opensteer skills".`
+      };
+    }
+    return {
+      mode: "error",
+      passthroughArgs: [],
+      error: `Unexpected argument "${arg}".`
+    };
+  }
+  return {
+    mode: "install",
+    passthroughArgs
+  };
+}
+function resolveLocalSkillSourcePath() {
+  const packageRoot = resolvePackageRoot();
+  const sourcePath = join(packageRoot, "skills");
+  if (!existsSync(sourcePath)) {
+    throw new Error(
+      `Opensteer skill source was not found at "${sourcePath}".`
+    );
+  }
+  return sourcePath;
+}
+function resolveSkillsCliPath() {
+  const require2 = createRequire(resolveCliEntrypointPath());
+  const skillsPackagePath = require2.resolve("skills/package.json");
+  const skillsPackageDir = dirname(skillsPackagePath);
+  const cliPath = join(skillsPackageDir, "bin", "cli.mjs");
+  if (!existsSync(cliPath)) {
+    throw new Error(`skills CLI entrypoint was not found at "${cliPath}".`);
+  }
+  return cliPath;
+}
+function resolveCliEntrypointPath() {
+  const cliEntrypoint = process.argv[1];
+  if (!cliEntrypoint) {
+    throw new Error("Unable to resolve CLI entrypoint path for skills installer.");
+  }
+  return realpathSync(cliEntrypoint);
+}
+function resolvePackageRoot() {
+  const cliEntrypointPath = resolveCliEntrypointPath();
+  const binDir = dirname(cliEntrypointPath);
+  return resolve(binDir, "..");
+}
+function createSkillsInstallInvocation(args) {
+  return {
+    cliPath: args.skillsCliPath,
+    cliArgs: [
+      "add",
+      args.localSkillSourcePath,
+      "--skill",
+      "opensteer",
+      ...args.passthroughArgs
+    ]
+  };
+}
+async function spawnInvocation(invocation) {
+  return await new Promise((resolvePromise, rejectPromise) => {
+    const child = spawn(process.execPath, [invocation.cliPath, ...invocation.cliArgs], {
+      stdio: "inherit",
+      env: process.env,
+      cwd: process.cwd()
+    });
+    child.once("error", (error) => {
+      rejectPromise(error);
+    });
+    child.once("exit", (code) => {
+      if (typeof code === "number") {
+        resolvePromise(code);
+        return;
+      }
+      resolvePromise(1);
+    });
+  });
+}
+function createDefaultDeps() {
+  return {
+    resolveSkillsCliPath,
+    resolveLocalSkillSourcePath,
+    spawnInvocation,
+    writeStdout(message) {
+      process.stdout.write(message);
+    },
+    writeStderr(message) {
+      process.stderr.write(message);
+    }
+  };
+}
+async function runOpensteerSkillsInstaller(rawArgs, overrideDeps = {}) {
+  const deps = {
+    ...createDefaultDeps(),
+    ...overrideDeps
+  };
+  const parsed = parseOpensteerSkillsArgs(rawArgs);
+  if (parsed.mode === "help") {
+    deps.writeStdout(HELP_TEXT);
+    return 0;
+  }
+  if (parsed.mode === "error") {
+    deps.writeStderr(`${parsed.error}
+`);
+    deps.writeStderr('Run "opensteer skills --help" for usage.\n');
+    return 1;
+  }
+  const invocation = createSkillsInstallInvocation({
+    localSkillSourcePath: deps.resolveLocalSkillSourcePath(),
+    passthroughArgs: parsed.passthroughArgs,
+    skillsCliPath: deps.resolveSkillsCliPath()
+  });
+  return await deps.spawnInvocation(invocation);
+}
+export {
+  createSkillsInstallInvocation,
+  parseOpensteerSkillsArgs,
+  resolveLocalSkillSourcePath,
+  resolveSkillsCliPath,
+  runOpensteerSkillsInstaller
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opensteer",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "Open-source browser automation SDK with robust selectors and deterministic replay.",
   "license": "MIT",
   "type": "module",
@@ -20,6 +20,7 @@
   "files": [
     "dist",
     "bin",
+    "skills",
     "README.md",
     "LICENSE",
     "CHANGELOG.md"
@@ -37,6 +38,7 @@
     "dotenv": "^17.2.4",
     "openai": "^6.25.0",
     "playwright": "^1.50.0",
+    "skills": "1.4.3",
     "ws": "^8.18.0",
     "zod": "^4.3.6"
   },
@@ -63,8 +65,12 @@
     "type": "git",
     "url": "https://github.com/steerlabs/opensteer"
   },
+  "homepage": "https://opensteer.com",
+  "bugs": {
+    "url": "https://github.com/steerlabs/opensteer/issues"
+  },
   "scripts": {
-    "build": "tsup src/index.ts src/cli/server.ts --dts --format esm,cjs --clean --external ai --external zod --external @ai-sdk/openai --external @ai-sdk/anthropic --external @ai-sdk/google --external @ai-sdk/xai --external @ai-sdk/groq --external openai --external @anthropic-ai/sdk --external @google/genai",
+    "build": "tsup src/index.ts src/cli/server.ts src/cli/skills-installer.ts --dts --format esm,cjs --clean --external ai --external zod --external @ai-sdk/openai --external @ai-sdk/anthropic --external @ai-sdk/google --external @ai-sdk/xai --external @ai-sdk/groq --external openai --external @anthropic-ai/sdk --external @google/genai",
     "test": "vitest run",
     "test:live-web": "vitest run --config vitest.live-web.config.ts",
     "test:unit": "vitest run tests/html tests/element-path tests/config.test.ts tests/storage",

package/skills/README.md

@@ -0,0 +1,29 @@
+# Opensteer Skills
+
+This directory contains Opensteer-maintained skill packs.
+
+## Layout
+
+Use this structure for each skill:
+
+```text
+skills/<skill-name>/
+  SKILL.md
+  references/
+    *.md
+  templates/
+    *
+```
+
+## Conventions
+
+- Keep one canonical skill per folder (`<skill-name>`).
+- Use `SKILL.md` frontmatter with at least `name` and `description`.
+- Put detailed instructions in `references/` and link them from `SKILL.md`.
+- Put reusable snippets in `templates/` when needed.
+- Use relative Markdown links.
+
+## Built-in Skills
+
+- `opensteer`: [skills/opensteer/SKILL.md](./opensteer/SKILL.md)
+- `electron`: [skills/electron/SKILL.md](./electron/SKILL.md)

package/skills/electron/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: electron
+description: "Automate Electron desktop apps (Slack, VS Code, Discord, Notion, and other Chromium-based desktop apps) with Opensteer by connecting to a running Chrome DevTools endpoint. Use when tasks require interacting with Electron UI, testing desktop app workflows, extracting structured data from app windows, or capturing Electron screenshots."
+---
+
+# Electron App Automation with Opensteer
+
+Use this skill when a task targets an Electron desktop app instead of a normal browser tab.
+
+Read [opensteer-electron-workflow.md](references/opensteer-electron-workflow.md) first for the Opensteer connection model and execution flow.
+
+## Core Workflow
+
+1. Launch the Electron app with `--remote-debugging-port=<port>`.
+2. Connect Opensteer with `open --connect-url http://127.0.0.1:<port>`.
+3. List windows/webviews with `tabs`, then switch with `tab-switch`.
+4. Run `snapshot action`, interact (`click`, `input`, `press`), then re-snapshot.
+5. Use `snapshot extraction` and `extract` for structured data.
+
+```bash
+# Connect Opensteer to a running Electron app on port 9222
+opensteer open --connect-url http://127.0.0.1:9222 --session slack-desktop --name slack-desktop
+
+# Discover available windows/webviews
+opensteer tabs --session slack-desktop
+opensteer tab-switch 0 --session slack-desktop
+
+# Standard action loop
+opensteer snapshot action --session slack-desktop
+opensteer click 12 --session slack-desktop
+opensteer input 8 "release notes" --pressEnter --session slack-desktop
+opensteer snapshot action --session slack-desktop
+```
+
+## Launching Electron Apps
+
+If the app is already running, quit it first, then relaunch with the debugging flag.
+
+```bash
+# macOS examples
+open -a "Slack" --args --remote-debugging-port=9222
+open -a "Visual Studio Code" --args --remote-debugging-port=9223
+open -a "Discord" --args --remote-debugging-port=9224
+
+# Linux examples
+slack --remote-debugging-port=9222
+code --remote-debugging-port=9223
+discord --remote-debugging-port=9224
+```
+
+## Structured Extraction Pattern
+
+```bash
+opensteer snapshot extraction --session slack-desktop
+
+opensteer extract '{"channels":[{"name":{"element":21},"unread":{"element":22}}]}' \
+  --description "sidebar channels with unread state" \
+  --session slack-desktop
+```
+
+Use `--description` when possible so selector paths persist for replay.
+
+## Multiple Apps at Once
+
+Use one Opensteer session per app:
+
+```bash
+opensteer open --connect-url http://127.0.0.1:9222 --session slack --name slack-electron
+opensteer open --connect-url http://127.0.0.1:9223 --session vscode --name vscode-electron
+
+opensteer snapshot action --session slack
+opensteer snapshot action --session vscode
+```
+
+## Guardrails
+
+- Prefer Opensteer commands over raw Playwright for interaction/extraction.
+- Re-snapshot after each navigation or large UI change before reusing counters.
+- Keep `--name` stable inside a session for deterministic selector replay.
+- Close sessions when done: `opensteer close --session <id>`.
+
+## References
+
+- [opensteer-electron-workflow.md](references/opensteer-electron-workflow.md)
+- [opensteer-electron-recipes.md](references/opensteer-electron-recipes.md)

package/skills/electron/references/opensteer-electron-recipes.md

@@ -0,0 +1,86 @@
+# Opensteer Electron Recipes
+
+## Launch Commands
+
+Relaunch the app with a debugging port before connecting.
+
+```bash
+# macOS
+open -a "Slack" --args --remote-debugging-port=9222
+open -a "Visual Studio Code" --args --remote-debugging-port=9223
+open -a "Discord" --args --remote-debugging-port=9224
+
+# Linux
+slack --remote-debugging-port=9222
+code --remote-debugging-port=9223
+discord --remote-debugging-port=9224
+
+# Windows (PowerShell examples)
+"$env:LOCALAPPDATA\slack\slack.exe" --remote-debugging-port=9222
+"$env:LOCALAPPDATA\Programs\Microsoft VS Code\Code.exe" --remote-debugging-port=9223
+```
+
+Optional health check:
+
+```bash
+curl -s http://127.0.0.1:9222/json/version
+```
+
+## Connect and Select Target
+
+```bash
+opensteer open --connect-url http://127.0.0.1:9222 --session electron --name electron
+opensteer tabs --session electron
+opensteer tab-switch 0 --session electron
+opensteer snapshot action --session electron
+```
+
+If the wrong content appears, iterate with `tab-switch` and `snapshot action` until you reach the correct window/webview.
+
+## Navigation and Interaction
+
+```bash
+opensteer snapshot action --session electron
+opensteer click 11 --description "left sidebar channel" --session electron
+opensteer input 7 "deployment notes" --pressEnter --description "search input" --session electron
+opensteer press Enter --session electron
+opensteer screenshot electron-state.png --session electron
+```
+
+## Structured Data Extraction
+
+```bash
+# Inspect extraction-focused DOM
+opensteer snapshot extraction --session electron
+
+# Build schema from observed counters
+opensteer extract '{"items":[{"title":{"element":15},"meta":{"element":16}}]}' \
+  --description "visible item list with metadata" \
+  --session electron
+```
+
+## Multi-App Pattern
+
+```bash
+# Slack
+opensteer open --connect-url http://127.0.0.1:9222 --session slack --name slack-electron
+
+# VS Code
+opensteer open --connect-url http://127.0.0.1:9223 --session vscode --name vscode-electron
+
+opensteer snapshot action --session slack
+opensteer snapshot action --session vscode
+```
+
+## Troubleshooting
+
+- `connection refused`:
+  - App was not launched with `--remote-debugging-port`.
+  - Port is wrong or blocked by another process.
+- Empty or incorrect snapshot:
+  - You are in the wrong target window; use `tabs` and `tab-switch`.
+  - The app has not finished rendering; wait briefly and snapshot again.
+- Counter failures (`element not found`):
+  - UI changed and counters are stale; take a fresh `snapshot action`.
+- Wrong selectors on replay:
+  - `--description` string differs from the original text; use exact wording.

package/skills/electron/references/opensteer-electron-workflow.md

@@ -0,0 +1,85 @@
+# Opensteer Electron Workflow
+
+This document describes the Opensteer-native flow for automating Electron apps.
+
+## 1. Connection Model
+
+Electron apps embed Chromium. Opensteer connects through Chrome DevTools Protocol (CDP):
+
+- Launch app with `--remote-debugging-port=<port>`
+- Attach with `opensteer open --connect-url http://127.0.0.1:<port>`
+
+Example:
+
+```bash
+opensteer open --connect-url http://127.0.0.1:9222 --session electron --name electron
+```
+
+`--session` controls runtime routing (which daemon/browser instance handles commands).
+`--name` controls selector cache namespace for deterministic replay.
+
+## 2. Window/Webview Targeting
+
+Electron apps often expose multiple targets. After connecting:
+
+```bash
+opensteer tabs --session electron
+opensteer tab-switch 0 --session electron
+opensteer snapshot action --session electron
+```
+
+Iterate `tab-switch` + `snapshot action` until you are on the correct app window/webview.
+
+## 3. Action Loop
+
+Use this loop for all interactions:
+
+1. `snapshot action`
+2. `click` / `input` / `press`
+3. re-run `snapshot action`
+
+Example:
+
+```bash
+opensteer snapshot action --session electron
+opensteer click 10 --description "navigation item" --session electron
+opensteer input 6 "release checklist" --pressEnter --description "search input" --session electron
+opensteer snapshot action --session electron
+```
+
+## 4. Extraction Loop
+
+For structured data:
+
+1. `snapshot extraction`
+2. build schema from element counters
+3. `extract <schema-json>`
+
+Example:
+
+```bash
+opensteer snapshot extraction --session electron
+opensteer extract '{"rows":[{"title":{"element":14},"status":{"element":15}}]}' \
+  --description "current visible rows with status" \
+  --session electron
+```
+
+## 5. Replay Stability
+
+- Keep `--name` stable for the same automation namespace.
+- Keep `--description` text exact across runs.
+- Re-snapshot after meaningful UI changes before reusing counters.
+
+## 6. Session Cleanup
+
+Close the session when done:
+
+```bash
+opensteer close --session electron
+```
+
+Or list active sessions:
+
+```bash
+opensteer sessions
+```