screenhand 0.2.0 → 0.3.1

package/dist/src/community/fetcher.js

@@ -0,0 +1,109 @@
+// Copyright (C) 2025 Clazro Technology Private Limited
+// SPDX-License-Identifier: AGPL-3.0-only
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { RemoteCommunityAPI } from "./remote-api.js";
+/**
+ * PlaybookFetcher — fetches community playbooks from local disk
+ * and optionally from a remote API (when SCREENHAND_COMMUNITY_URL is set).
+ *
+ * Local repo is always read. Remote results are merged and deduplicated.
+ */
+export class PlaybookFetcher {
+    repoDir;
+    cache = null;
+    remote;
+    constructor(repoDir, remote) {
+        this.repoDir = repoDir ?? path.join(os.homedir(), ".screenhand", "community");
+        this.remote = remote ?? RemoteCommunityAPI.fromEnv();
+    }
+    /**
+     * Fetch community playbooks matching the query.
+     * Reads from local disk; async variant also merges remote results.
+     */
+    fetch(query) {
+        return this.filterAndRank(this.loadAll(), query);
+    }
+    /**
+     * Fetch with remote API merge (when SCREENHAND_COMMUNITY_URL is set).
+     * Local results are always included; remote results are deduplicated and merged.
+     */
+    async fetchWithRemote(query) {
+        const local = this.loadAll();
+        if (!this.remote) {
+            return this.filterAndRank(local, query);
+        }
+        try {
+            const remote = await this.remote.fetch(query);
+            // Deduplicate: local wins on ID collision
+            const localIds = new Set(local.map((pb) => pb.id));
+            const merged = [...local, ...remote.filter((pb) => !localIds.has(pb.id))];
+            return this.filterAndRank(merged, query);
+        }
+        catch {
+            return this.filterAndRank(local, query);
+        }
+    }
+    filterAndRank(all, query) {
+        return all
+            .filter((pb) => {
+            if (query.platform && pb.platform !== query.platform)
+                return false;
+            if (query.bundleId && pb.bundleId !== query.bundleId)
+                return false;
+            if (query.workflow) {
+                const lower = query.workflow.toLowerCase();
+                if (!pb.name.toLowerCase().includes(lower) &&
+                    !pb.description.toLowerCase().includes(lower) &&
+                    !pb.metadata.tags.some((t) => t.toLowerCase().includes(lower))) {
+                    return false;
+                }
+            }
+            if (query.minScore !== undefined && pb.ratings.score < query.minScore)
+                return false;
+            return true;
+        })
+            .sort((a, b) => {
+            const scoreA = a.metadata.successRate * Math.max(a.ratings.score, 1);
+            const scoreB = b.metadata.successRate * Math.max(b.ratings.score, 1);
+            return scoreB - scoreA;
+        })
+            .slice(0, query.limit ?? 20);
+    }
+    /**
+     * Get a specific playbook by ID.
+     */
+    get(id) {
+        const all = this.loadAll();
+        return all.find((pb) => pb.id === id) ?? null;
+    }
+    /**
+     * Invalidate the cache (after a new playbook is published).
+     */
+    invalidateCache() {
+        this.cache = null;
+    }
+    loadAll() {
+        if (this.cache)
+            return this.cache;
+        const playbooks = [];
+        try {
+            if (!fs.existsSync(this.repoDir))
+                return playbooks;
+            const files = fs.readdirSync(this.repoDir);
+            for (const file of files) {
+                if (!file.endsWith(".json"))
+                    continue;
+                try {
+                    const raw = fs.readFileSync(path.join(this.repoDir, file), "utf-8");
+                    playbooks.push(JSON.parse(raw));
+                }
+                catch { /* skip malformed */ }
+            }
+        }
+        catch { /* dir not found */ }
+        this.cache = playbooks;
+        return playbooks;
+    }
+}

package/dist/src/community/index.js

@@ -0,0 +1,6 @@
+// Copyright (C) 2025 Clazro Technology Private Limited
+// SPDX-License-Identifier: AGPL-3.0-only
+export { PlaybookPublisher } from "./publisher.js";
+export { PlaybookFetcher } from "./fetcher.js";
+export { PlaybookValidator } from "./validator.js";
+export { RemoteCommunityAPI } from "./remote-api.js";

package/dist/src/community/publisher.js

@@ -0,0 +1,191 @@
+// Copyright (C) 2025 Clazro Technology Private Limited
+// SPDX-License-Identifier: AGPL-3.0-only
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { writeFileAtomicSync } from "../util/atomic-write.js";
+import { RemoteCommunityAPI } from "./remote-api.js";
+/**
+ * PlaybookPublisher — prepares and publishes validated playbooks
+ * to a local shared repository and optionally to a remote API
+ * (when SCREENHAND_COMMUNITY_URL is set).
+ */
+export class PlaybookPublisher {
+    repoDir;
+    remote;
+    constructor(repoDir, remote) {
+        this.repoDir = repoDir ?? path.join(os.homedir(), ".screenhand", "community");
+        this.remote = remote ?? RemoteCommunityAPI.fromEnv();
+        fs.mkdirSync(this.repoDir, { recursive: true });
+    }
+    /**
+     * Publish a validated local playbook to the community repository.
+     * Requires the playbook to have been run successfully at least minRuns times.
+     */
+    publish(playbook, successRate, executionCount, _minRuns) {
+        // Server-side minimum — cannot be overridden by caller
+        const MIN_RUNS = 3;
+        if (!Number.isFinite(executionCount) || executionCount < MIN_RUNS)
+            return null;
+        if (!Number.isFinite(successRate) || successRate < 0.5)
+            return null;
+        // Cross-check client-provided metrics against actual playbook data.
+        // ALWAYS use the playbook's own tracked counts — never trust client values.
+        // If the playbook has no tracked runs, it cannot be verified for publishing.
+        const actualRuns = playbook.successCount + playbook.failCount;
+        if (actualRuns < MIN_RUNS)
+            return null; // No tracked data = not publishable
+        const verifiedRate = playbook.successCount / actualRuns;
+        if (verifiedRate < 0.5)
+            return null;
+        const shared = {
+            id: `community_${playbook.id}_${Date.now().toString(36)}`,
+            name: playbook.name,
+            description: playbook.description,
+            platform: playbook.platform,
+            bundleId: playbook.bundleId ?? "",
+            version: "1.0.0",
+            steps: this.convertSteps(playbook.steps),
+            metadata: {
+                author: "anonymous",
+                publishedAt: new Date().toISOString(),
+                updatedAt: new Date().toISOString(),
+                os: process.platform,
+                successRate: verifiedRate,
+                executionCount: actualRuns,
+                tags: playbook.tags ?? [],
+            },
+            ratings: {
+                upvotes: 0,
+                downvotes: 0,
+                score: 0,
+                reportCount: 0,
+            },
+        };
+        // Strip sensitive data from params
+        for (const step of shared.steps) {
+            this.sanitizeParams(step.params);
+        }
+        // Sanitize ID to prevent path traversal
+        const safeId = shared.id.replace(/[^a-zA-Z0-9_\-]/g, "_");
+        const filePath = path.join(this.repoDir, `${safeId}.json`);
+        // Verify the file stays inside repoDir
+        const resolved = path.resolve(filePath);
+        if (!resolved.startsWith(path.resolve(this.repoDir))) {
+            return null;
+        }
+        writeFileAtomicSync(filePath, JSON.stringify(shared, null, 2) + "\n");
+        // Best-effort sync to remote API
+        if (this.remote) {
+            void this.remote.publish(shared).catch(() => { });
+        }
+        return shared;
+    }
+    /**
+     * List all published playbooks in the local repository.
+     */
+    list() {
+        const playbooks = [];
+        try {
+            const files = fs.readdirSync(this.repoDir);
+            for (const file of files) {
+                if (!file.endsWith(".json"))
+                    continue;
+                try {
+                    const raw = fs.readFileSync(path.join(this.repoDir, file), "utf-8");
+                    playbooks.push(JSON.parse(raw));
+                }
+                catch { /* skip */ }
+            }
+        }
+        catch { /* dir not found */ }
+        return playbooks;
+    }
+    convertSteps(steps) {
+        return steps.map((step) => ({
+            action: step.action,
+            tool: this.actionToTool(step.action),
+            params: this.extractParams(step),
+            description: step.description ?? `${step.action} step`,
+        }));
+    }
+    extractParams(step) {
+        const params = {};
+        if (step.target !== undefined)
+            params.target = step.target;
+        if (step.text !== undefined)
+            params.text = step.text;
+        if (step.url !== undefined)
+            params.url = step.url;
+        if (step.keys !== undefined)
+            params.keys = step.keys;
+        if (step.menuPath !== undefined)
+            params.menuPath = step.menuPath;
+        if (step.ms !== undefined)
+            params.ms = step.ms;
+        if (step.direction !== undefined)
+            params.direction = step.direction;
+        if (step.amount !== undefined)
+            params.amount = step.amount;
+        // Normalize to MCP tool param shapes
+        if (Array.isArray(params.keys)) {
+            params.combo = params.keys.join("+");
+            delete params.keys;
+        }
+        if (Array.isArray(params.menuPath)) {
+            params.menuPath = params.menuPath.join("/");
+        }
+        return params;
+    }
+    actionToTool(action) {
+        switch (action) {
+            case "click": return "click_with_fallback";
+            case "type": return "type_with_fallback";
+            case "press": return "key";
+            case "navigate": return "browser_navigate";
+            case "wait": return "wait_for_state";
+            case "scroll": return "scroll_with_fallback";
+            default: return action;
+        }
+    }
+    /**
+     * Remove potentially sensitive values from params.
+     */
+    sanitizeParams(params) {
+        const sensitiveKeys = [
+            "password", "token", "secret", "credential",
+            "apikey", "api_key", "auth_token", "secret_key",
+            "access_key", "private_key",
+        ];
+        /** Patterns that indicate sensitive values regardless of key name */
+        const sensitiveValuePatterns = [
+            /sk-ant-api/i, // Anthropic API keys
+            /sk-[a-zA-Z0-9]{20,}/i, // OpenAI-style keys
+            /^ghp_[a-zA-Z0-9]{36}$/i, // GitHub PATs
+            /^xox[bpsar]-/i, // Slack tokens
+            /\bexport\s+\w*(?:KEY|TOKEN|SECRET|PASSWORD)\b/i, // env var exports
+        ];
+        for (const key of Object.keys(params)) {
+            if (sensitiveKeys.some((s) => key.toLowerCase() === s || key.toLowerCase().replace(/[^a-z_]/g, "") === s)) {
+                delete params[key];
+                continue;
+            }
+            const val = params[key];
+            // Check string values for sensitive patterns
+            if (typeof val === "string") {
+                if (sensitiveValuePatterns.some((p) => p.test(val))) {
+                    delete params[key];
+                    continue;
+                }
+                // Strip absolute file paths
+                if (val.startsWith("/") && (val.includes("/Users/") || val.includes("/home/"))) {
+                    params[key] = path.basename(val);
+                }
+            }
+            // Recurse into nested objects
+            if (val && typeof val === "object" && !Array.isArray(val)) {
+                this.sanitizeParams(val);
+            }
+        }
+    }
+}

package/dist/src/community/remote-api.js

@@ -0,0 +1,121 @@
+// Copyright (C) 2025 Clazro Technology Private Limited
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * RemoteCommunityAPI — optional remote backend for community playbook sharing.
+ *
+ * When `SCREENHAND_COMMUNITY_URL` is set, publish/fetch operations
+ * go to the remote API in addition to local disk. The local repo
+ * remains the source of truth; remote is best-effort sync.
+ *
+ * Expected API endpoints:
+ *   POST /playbooks         — publish a playbook
+ *   GET  /playbooks?...     — search playbooks (query params from PlaybookQuery)
+ *   GET  /playbooks/:id     — get a single playbook
+ *   POST /playbooks/:id/rate — rate a playbook { score: 1 | -1 }
+ */
+export class RemoteCommunityAPI {
+    baseUrl;
+    timeoutMs;
+    constructor(baseUrl, timeoutMs = 5_000) {
+        // Strip trailing slash
+        this.baseUrl = baseUrl.replace(/\/+$/, "");
+        this.timeoutMs = timeoutMs;
+    }
+    /**
+     * Get the configured remote URL, or null if not configured.
+     */
+    static fromEnv() {
+        const url = process.env["SCREENHAND_COMMUNITY_URL"];
+        if (!url)
+            return null;
+        return new RemoteCommunityAPI(url);
+    }
+    /**
+     * Publish a playbook to the remote API.
+     * Returns the server-assigned ID, or null on failure.
+     */
+    async publish(playbook) {
+        try {
+            const res = await fetchWithTimeout(`${this.baseUrl}/playbooks`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify(playbook),
+            }, this.timeoutMs);
+            if (!res.ok)
+                return null;
+            const body = (await res.json());
+            return body.id ?? playbook.id;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Fetch playbooks from the remote API matching a query.
+     */
+    async fetch(query) {
+        try {
+            const params = new URLSearchParams();
+            if (query.platform)
+                params.set("platform", query.platform);
+            if (query.bundleId)
+                params.set("bundleId", query.bundleId);
+            if (query.workflow)
+                params.set("workflow", query.workflow);
+            if (query.minScore !== undefined)
+                params.set("minScore", String(query.minScore));
+            if (query.limit !== undefined)
+                params.set("limit", String(query.limit));
+            const res = await fetchWithTimeout(`${this.baseUrl}/playbooks?${params.toString()}`, { method: "GET" }, this.timeoutMs);
+            if (!res.ok)
+                return [];
+            return (await res.json());
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * Get a specific playbook by ID.
+     */
+    async get(id) {
+        try {
+            const res = await fetchWithTimeout(`${this.baseUrl}/playbooks/${encodeURIComponent(id)}`, { method: "GET" }, this.timeoutMs);
+            if (!res.ok)
+                return null;
+            return (await res.json());
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Rate a playbook (upvote/downvote).
+     */
+    async rate(id, score) {
+        try {
+            const res = await fetchWithTimeout(`${this.baseUrl}/playbooks/${encodeURIComponent(id)}/rate`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ score }),
+            }, this.timeoutMs);
+            return res.ok;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+/**
+ * Fetch with AbortController timeout.
+ */
+async function fetchWithTimeout(url, init, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await fetch(url, { ...init, signal: controller.signal });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/src/community/types.js

@@ -0,0 +1,3 @@
+// Copyright (C) 2025 Clazro Technology Private Limited
+// SPDX-License-Identifier: AGPL-3.0-only
+export {};

package/dist/src/community/validator.js

@@ -0,0 +1,95 @@
+// Copyright (C) 2025 Clazro Technology Private Limited
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Tools that community playbooks are allowed to call.
+ * Excludes: applescript (arbitrary code exec), browser_js (XSS),
+ * browser_stealth (anti-detection), memory_* (data exfil),
+ * supervisor_* (system control), job_* (persistence).
+ */
+const SAFE_TOOLS = new Set([
+    "click", "click_text", "click_with_fallback", "type_text", "type_with_fallback",
+    "key", "drag", "scroll", "scroll_with_fallback", "focus", "launch",
+    "screenshot", "screenshot_file", "ocr", "ui_tree", "ui_find", "ui_press",
+    "ui_set_value", "menu_click", "wait_for_state", "read_with_fallback",
+    "locate_with_fallback", "select_with_fallback",
+    "browser_open", "browser_navigate", "browser_click", "browser_type",
+    "browser_dom", "browser_wait", "browser_page_info", "browser_tabs",
+    "browser_fill_form", "browser_human_click",
+    "windows", "apps",
+]);
+/**
+ * PlaybookValidator — tests a community playbook against the live app
+ * before accepting it into the local collection.
+ */
+export class PlaybookValidator {
+    executeTool;
+    constructor(executeTool) {
+        this.executeTool = executeTool;
+    }
+    /**
+     * Validate a community playbook by executing its steps.
+     * Runs all steps and reports success/failure.
+     */
+    async validate(playbook) {
+        if (playbook.steps.length === 0) {
+            return {
+                playbook,
+                success: false,
+                stepsCompleted: 0,
+                totalSteps: 0,
+                errors: ["Playbook has no steps"],
+                validatedAt: new Date().toISOString(),
+            };
+        }
+        const errors = [];
+        let stepsCompleted = 0;
+        // Pre-validate: reject playbooks that use unsafe tools
+        for (const step of playbook.steps) {
+            if (!SAFE_TOOLS.has(step.tool)) {
+                return {
+                    playbook,
+                    success: false,
+                    stepsCompleted: 0,
+                    totalSteps: playbook.steps.length,
+                    errors: [`Step "${step.description}" uses blocked tool "${step.tool}". Community playbooks cannot use this tool.`],
+                    validatedAt: new Date().toISOString(),
+                };
+            }
+        }
+        for (const step of playbook.steps) {
+            try {
+                const result = await this.executeTool(step.tool, step.params);
+                if (result.ok) {
+                    stepsCompleted++;
+                }
+                else {
+                    errors.push(`Step ${stepsCompleted + 1} ("${step.description}") failed: ${result.error ?? "unknown error"}`);
+                    break; // Stop on first failure
+                }
+            }
+            catch (err) {
+                errors.push(`Step ${stepsCompleted + 1} ("${step.description}") threw: ${err instanceof Error ? err.message : String(err)}`);
+                break;
+            }
+        }
+        return {
+            playbook,
+            success: stepsCompleted === playbook.steps.length,
+            stepsCompleted,
+            totalSteps: playbook.steps.length,
+            errors,
+            validatedAt: new Date().toISOString(),
+        };
+    }
+    /**
+     * Validate multiple playbooks and return the best one.
+     */
+    async findBest(playbooks) {
+        for (const pb of playbooks) {
+            const result = await this.validate(pb);
+            if (result.success)
+                return result;
+        }
+        return null;
+    }
+}