screenhand 0.2.0 → 0.3.1

package/dist/scripts/export-help-center.js

@@ -0,0 +1,112 @@
+#!/usr/bin/env npx tsx
+import { exportHelpCenterToMarkdown } from "../src/platform/help-center-markdown.js";
+async function main() {
+    const options = parseArgs(process.argv.slice(2));
+    if (options.help || !options.url) {
+        printUsage();
+        process.exit(options.help ? 0 : 1);
+    }
+    const result = await exportHelpCenterToMarkdown({
+        startUrl: options.url,
+        outputPath: options.output,
+        maxPages: options.maxPages,
+        headless: options.headless,
+        waitAfterLoadMs: options.waitMs,
+        onProgress: (message) => console.log(message),
+        ...(options.scope ? { scopePrefix: options.scope } : {}),
+    });
+    console.log("");
+    console.log(`Wrote ${result.pageCount} page(s) to ${result.outputPath}`);
+    console.log(`Scope prefix: ${result.scopePrefix}`);
+}
+function parseArgs(args) {
+    const options = {
+        output: "help-center-export.md",
+        maxPages: 25,
+        headless: false,
+        waitMs: 1200,
+        help: false,
+    };
+    for (let index = 0; index < args.length; index++) {
+        const arg = args[index];
+        const next = args[index + 1];
+        if (arg === "--help" || arg === "-h") {
+            options.help = true;
+            continue;
+        }
+        if (arg === "--headless") {
+            options.headless = true;
+            continue;
+        }
+        if (arg === "--headed") {
+            options.headless = false;
+            continue;
+        }
+        if (arg === "--url" && next) {
+            options.url = next;
+            index++;
+            continue;
+        }
+        if (arg.startsWith("--url=")) {
+            options.url = arg.slice("--url=".length);
+            continue;
+        }
+        if (arg === "--output" && next) {
+            options.output = next;
+            index++;
+            continue;
+        }
+        if (arg.startsWith("--output=")) {
+            options.output = arg.slice("--output=".length);
+            continue;
+        }
+        if (arg === "--scope" && next) {
+            options.scope = next;
+            index++;
+            continue;
+        }
+        if (arg.startsWith("--scope=")) {
+            options.scope = arg.slice("--scope=".length);
+            continue;
+        }
+        if (arg === "--max-pages" && next) {
+            options.maxPages = parsePositiveInt(next, "--max-pages");
+            index++;
+            continue;
+        }
+        if (arg.startsWith("--max-pages=")) {
+            options.maxPages = parsePositiveInt(arg.slice("--max-pages=".length), "--max-pages");
+            continue;
+        }
+        if (arg === "--wait-ms" && next) {
+            options.waitMs = parsePositiveInt(next, "--wait-ms");
+            index++;
+            continue;
+        }
+        if (arg.startsWith("--wait-ms=")) {
+            options.waitMs = parsePositiveInt(arg.slice("--wait-ms=".length), "--wait-ms");
+            continue;
+        }
+        throw new Error(`Unknown argument: ${arg}`);
+    }
+    return options;
+}
+function parsePositiveInt(value, flagName) {
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new Error(`${flagName} must be a positive integer`);
+    }
+    return parsed;
+}
+function printUsage() {
+    console.log("Usage:");
+    console.log("  npm run export:help-md -- --url <help-root-url> [--output file.md] [--scope /path/] [--max-pages 25] [--headless]");
+    console.log("");
+    console.log("Examples:");
+    console.log("  npm run export:help-md -- --url https://www.canva.com/en_in/help/topics/ --output docs/canva-help.md --max-pages 40");
+    console.log("  npm run export:help-md -- --url https://www.canva.com/en_in/help/topics/ --scope /en_in/help/ --headless");
+}
+main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+});

package/dist/scripts/marketing-loop.js

@@ -0,0 +1,117 @@
+#!/usr/bin/env npx tsx
+/**
+ * ScreenHand Marketing Automation Loop
+ *
+ * Architecture:
+ *   Claude Code (this script via /loop)
+ *     → ScreenHand CDP → Codex (content generation)
+ *     → ScreenHand browser → Social platforms (execution)
+ *
+ * Platforms: X/Twitter, Threads, LinkedIn, Reddit
+ * Goal: Increase GitHub stars for ScreenHand (github.com/manushi4/Screenhand)
+ */
+// Marketing task types with weights for rotation
+const TASK_TYPES = [
+    { type: 'search_engage', weight: 30, platforms: ['x', 'threads', 'linkedin'] },
+    { type: 'create_post', weight: 20, platforms: ['x', 'threads', 'linkedin'] },
+    { type: 'reply_contextual', weight: 25, platforms: ['x', 'threads', 'reddit'] },
+    { type: 'like_repost', weight: 15, platforms: ['x', 'threads'] },
+    { type: 'dm_outreach', weight: 10, platforms: ['x', 'linkedin'] },
+];
+// Search queries to find relevant conversations
+const SEARCH_QUERIES = [
+    'claude code',
+    'desktop automation AI',
+    'MCP server',
+    'browser automation agent',
+    'AI agent desktop control',
+    'anthropic claude tools',
+    'cursor automation',
+    'computer use API',
+    'accessibility automation mac',
+    'screenhand',
+    'AI coding assistant',
+    'claude MCP',
+    'openai codex desktop',
+    'AI agent framework',
+    'playwright alternative AI',
+];
+// Content angles for posts
+const CONTENT_ANGLES = [
+    'Show how ScreenHand gives AI agents native desktop control — 82 MCP tools',
+    'Demo: Claude Code using ScreenHand to automate a real workflow',
+    'ScreenHand vs browser-only automation — why desktop control matters',
+    'Open source AI desktop automation — ScreenHand on npm',
+    'How ScreenHand handles the focus-stealing problem in Electron apps',
+    'Building multi-agent systems with ScreenHand supervisor + job system',
+    'ScreenHand memory system — AI agents that learn from mistakes',
+    'Cross-platform desktop automation: macOS Swift + Windows C# native bridges',
+    'The playbook system — reusable automation recipes for any platform',
+    'Why we built ScreenHand: the gap between AI coding and AI doing',
+];
+// Rate limits per platform (actions per hour)
+const RATE_LIMITS = {
+    x: 8,
+    threads: 10,
+    linkedin: 6,
+    reddit: 4,
+};
+const state = {
+    startTime: Date.now(),
+    actionsPerformed: { x: 0, threads: 0, linkedin: 0, reddit: 0 },
+    lastActionTime: { x: 0, threads: 0, linkedin: 0, reddit: 0 },
+    postsCreated: [],
+    repliesSent: [],
+    searchesPerformed: [],
+    errors: [],
+    currentCycle: 0,
+};
+function pickWeightedRandom(items) {
+    const total = items.reduce((s, i) => s + i.weight, 0);
+    let r = Math.random() * total;
+    for (const item of items) {
+        r -= item.weight;
+        if (r <= 0)
+            return item;
+    }
+    return items[0];
+}
+function pickRandom(arr) {
+    return arr[Math.floor(Math.random() * arr.length)];
+}
+function canActOnPlatform(platform) {
+    const hourMs = 60 * 60 * 1000;
+    const now = Date.now();
+    const limit = RATE_LIMITS[platform] ?? 5;
+    const count = state.actionsPerformed[platform] ?? 0;
+    const elapsed = now - state.startTime;
+    const hoursElapsed = Math.max(1, elapsed / hourMs);
+    return count / hoursElapsed < limit;
+}
+function getNextTask() {
+    state.currentCycle++;
+    // Pick task type
+    const task = pickWeightedRandom(TASK_TYPES);
+    // Pick platform that hasn't hit rate limit
+    const availablePlatforms = task.platforms.filter(p => canActOnPlatform(p));
+    if (availablePlatforms.length === 0) {
+        return { type: 'wait', platform: 'none' };
+    }
+    const platform = pickRandom(availablePlatforms);
+    return {
+        type: task.type,
+        platform,
+        query: pickRandom(SEARCH_QUERIES),
+        angle: pickRandom(CONTENT_ANGLES),
+    };
+}
+function formatStatus() {
+    const elapsed = Math.round((Date.now() - state.startTime) / 60000);
+    const total = Object.values(state.actionsPerformed).reduce((s, n) => s + n, 0);
+    return `[Cycle ${state.currentCycle} | ${elapsed}m elapsed | ${total} actions | ` +
+        `X:${state.actionsPerformed.x} T:${state.actionsPerformed.threads} ` +
+        `L:${state.actionsPerformed.linkedin} R:${state.actionsPerformed.reddit} | ` +
+        `${state.errors.length} errors]`;
+}
+// Export for use by the loop controller
+export { getNextTask, formatStatus, state, SEARCH_QUERIES, CONTENT_ANGLES, canActOnPlatform };

package/dist/scripts/observer-daemon.js

@@ -0,0 +1,288 @@
+#!/usr/bin/env npx tsx
+/**
+ * Observer Daemon — background app-level visual monitor.
+ *
+ * Captures a single app window via cg.captureWindow (CGWindowListCreateImage).
+ * Uses pixel-hash frame diff to skip OCR when nothing changed.
+ * Persists state to ~/.screenhand/observer/state.json for the engine to read.
+ *
+ * Zero overhead on the main execution path — engine reads a JSON file, daemon
+ * does the heavy lifting in a separate process.
+ *
+ * Usage:
+ *   npx tsx scripts/observer-daemon.ts --bundleId com.blackmagic-design.DaVinciResolve --windowId 1234
+ *   npx tsx scripts/observer-daemon.ts --bundleId com.blackmagic-design.DaVinciResolve --windowId 1234 --interval 2000
+ *
+ * State files:
+ *   ~/.screenhand/observer/state.json    — observer state (latest OCR, popup detection)
+ *   ~/.screenhand/observer/observer.pid  — PID of this process
+ *   ~/.screenhand/observer/observer.log  — log output
+ */
+import path from "node:path";
+import fs from "node:fs";
+import crypto from "node:crypto";
+import { BridgeClient } from "../src/native/bridge-client.js";
+import { writeObserverState, readObserverCommands, writeObserverCommands, acquireCaptureLock, releaseCaptureLock } from "../src/observer/state.js";
+import { detectPopup } from "../src/observer/state.js";
+import { OBSERVER_DIR, OBSERVER_PID_FILE, OBSERVER_LOG_FILE } from "../src/observer/types.js";
+// ── Config from CLI args ──
+const args = process.argv.slice(2);
+function getArg(name, fallback) {
+    const idx = args.indexOf("--" + name);
+    if (idx === -1)
+        return fallback;
+    return args[idx + 1] ?? fallback;
+}
+const BUNDLE_ID = getArg("bundleId");
+const WINDOW_ID = Number(getArg("windowId", "0"));
+const INTERVAL_MS = Number(getArg("interval", "2000"));
+if (!BUNDLE_ID || !WINDOW_ID) {
+    process.stderr.write("Usage: observer-daemon.ts --bundleId <id> --windowId <id> [--interval <ms>]\n");
+    process.exit(1);
+}
+// ── Logging ──
+fs.mkdirSync(OBSERVER_DIR, { recursive: true });
+const logStream = fs.createWriteStream(OBSERVER_LOG_FILE, { flags: "a" });
+let daemonized = false;
+function log(msg) {
+    const line = `[${new Date().toISOString()}] ${msg}`;
+    logStream.write(line + "\n");
+    if (!daemonized)
+        process.stderr.write(line + "\n");
+}
+// ── Bridge setup ──
+const scriptDir = import.meta.dirname ?? path.dirname(new URL(import.meta.url).pathname);
+const projectRoot = scriptDir.includes("/dist/")
+    ? path.resolve(scriptDir, "../..")
+    : path.resolve(scriptDir, "..");
+const bridgePath = process.platform === "win32"
+    ? path.resolve(projectRoot, "native/windows-bridge/bin/Release/net8.0-windows/windows-bridge.exe")
+    : path.resolve(projectRoot, "native/macos-bridge/.build/release/macos-bridge");
+const bridge = new BridgeClient(bridgePath);
+let bridgeReady = false;
+async function ensureBridge() {
+    if (!bridgeReady) {
+        await bridge.start();
+        bridgeReady = true;
+    }
+}
+// ── Frame diff via file hash ──
+let lastFrameHash = null;
+function hashFile(filePath) {
+    const data = fs.readFileSync(filePath);
+    return crypto.createHash("md5").update(data).digest("hex");
+}
+// ── State ──
+let stopped = false;
+let framesCaptured = 0;
+let framesChanged = 0;
+let ocrRuns = 0;
+let lastFrame = null;
+let lastPopup = null;
+let lastError = null;
+const startedAt = new Date().toISOString();
+function buildState() {
+    return {
+        pid: process.pid,
+        running: !stopped,
+        startedAt,
+        bundleId: BUNDLE_ID,
+        windowId: WINDOW_ID,
+        intervalMs: INTERVAL_MS,
+        framesCaptured,
+        framesChanged,
+        ocrRuns,
+        lastFrame,
+        popup: lastPopup,
+        lastError,
+    };
+}
+function persistState() {
+    try {
+        writeObserverState(buildState());
+    }
+    catch {
+        // Non-fatal
+    }
+}
+// ── Capture loop ──
+async function captureFrame() {
+    // Acquire capture lock to prevent concurrent captures with perception coordinator
+    if (!acquireCaptureLock()) {
+        log("Skipping capture — lock held by perception coordinator");
+        return;
+    }
+    try {
+        await ensureBridge();
+        // 1. Capture window (app-level, not full screen)
+        let shot;
+        try {
+            shot = await bridge.call("cg.captureWindow", { windowId: WINDOW_ID });
+        }
+        catch (err) {
+            lastError = `Capture failed: ${err instanceof Error ? err.message : String(err)}`;
+            return;
+        }
+        framesCaptured++;
+        // 2. Frame diff — hash the image file, skip OCR if identical
+        const currentHash = hashFile(shot.path);
+        const pixelsChanged = currentHash !== lastFrameHash;
+        lastFrameHash = currentHash;
+        if (!pixelsChanged) {
+            // Frame identical — update timestamp only, skip expensive OCR
+            if (lastFrame) {
+                lastFrame.capturedAt = new Date().toISOString();
+                lastFrame.changed = false;
+            }
+            return;
+        }
+        framesChanged++;
+        // 3. OCR only on changed frames
+        let ocrText = "";
+        try {
+            const ocr = await bridge.call("vision.ocr", {
+                imagePath: shot.path,
+            });
+            ocrText = ocr.text;
+            ocrRuns++;
+        }
+        catch (err) {
+            lastError = `OCR failed: ${err instanceof Error ? err.message : String(err)}`;
+            ocrText = lastFrame?.ocrText ?? "";
+        }
+        // 4. Update frame
+        lastFrame = {
+            capturedAt: new Date().toISOString(),
+            ocrText,
+            changed: true,
+        };
+        // 5. Popup detection on the new OCR text
+        lastPopup = detectPopup(ocrText);
+        if (lastPopup) {
+            log(`Popup detected: "${lastPopup.pattern}" → ${lastPopup.dismissAction}`);
+        }
+        lastError = null;
+        // Clean up temp screenshot
+        try {
+            fs.unlinkSync(shot.path);
+        }
+        catch { /* ignore */ }
+    }
+    finally {
+        releaseCaptureLock();
+    }
+}
+// ── Command processing ──
+async function processCommands() {
+    let commands;
+    try {
+        commands = readObserverCommands();
+    }
+    catch {
+        return; // No commands file or corrupt — skip
+    }
+    const pending = commands.filter((c) => c.status === "pending");
+    if (pending.length === 0)
+        return;
+    let changed = false;
+    for (const cmd of pending) {
+        if (cmd.type !== "ocr_roi") {
+            cmd.status = "error";
+            cmd.error = `Unknown command type: ${cmd.type}`;
+            changed = true;
+            continue;
+        }
+        cmd.status = "running";
+        changed = true;
+        try {
+            await ensureBridge();
+            const targetWindowId = cmd.windowId ?? WINDOW_ID;
+            // Use vision.ocrRegion for targeted ROI OCR
+            const result = await bridge.call("vision.ocrRegion", {
+                windowId: targetWindowId,
+                region: cmd.roi,
+            });
+            cmd.status = "done";
+            cmd.result = {
+                text: result.text ?? "",
+                regions: result.regions ?? [],
+                completedAt: new Date().toISOString(),
+            };
+            ocrRuns++;
+            log(`Command ${cmd.id}: OCR ROI completed (${cmd.result.regions.length} regions)`);
+        }
+        catch (err) {
+            cmd.status = "error";
+            cmd.error = err instanceof Error ? err.message : String(err);
+            log(`Command ${cmd.id}: failed — ${cmd.error}`);
+        }
+    }
+    if (changed) {
+        writeObserverCommands(commands);
+    }
+}
+// ── Main loop ──
+async function main() {
+    // Enforce single daemon
+    try {
+        const existingPid = fs.readFileSync(OBSERVER_PID_FILE, "utf-8").trim();
+        const pid = Number(existingPid);
+        if (!Number.isNaN(pid) && pid !== process.pid) {
+            try {
+                process.kill(pid, 0); // Check if alive
+                log(`Another observer daemon already running (pid=${pid}). Aborting.`);
+                process.exit(1);
+            }
+            catch {
+                // Stale PID — safe to continue
+            }
+        }
+    }
+    catch {
+        // No PID file — first run
+    }
+    fs.writeFileSync(OBSERVER_PID_FILE, String(process.pid));
+    daemonized = true;
+    log(`Observer daemon started (pid=${process.pid})`);
+    log(`Watching: bundleId=${BUNDLE_ID} windowId=${WINDOW_ID} interval=${INTERVAL_MS}ms`);
+    persistState();
+    while (!stopped) {
+        try {
+            await captureFrame();
+            await processCommands();
+            persistState();
+        }
+        catch (err) {
+            lastError = `Frame error: ${err instanceof Error ? err.message : String(err)}`;
+            log(lastError);
+        }
+        await sleep(INTERVAL_MS);
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+// ── Graceful shutdown ──
+process.on("SIGINT", shutdown);
+process.on("SIGTERM", shutdown);
+async function shutdown() {
+    if (stopped)
+        return;
+    stopped = true;
+    log("Shutting down...");
+    persistState();
+    try {
+        fs.unlinkSync(OBSERVER_PID_FILE);
+    }
+    catch { /* ignore */ }
+    try {
+        await bridge.stop();
+    }
+    catch { /* ignore */ }
+    logStream.end();
+    process.exit(0);
+}
+main().catch((err) => {
+    log(`Fatal: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+});