findmy-cli 0.1.0 → 0.1.2

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+import * as openclaw_plugin_sdk_plugin_entry from 'openclaw/plugin-sdk/plugin-entry';
+
+/**
+ * OpenClaw plugin entry for findmy-cli.
+ *
+ * Registers two tools that shell out to the `findmy` binary to query Find My
+ * friend locations on macOS. The CLI drives FindMy.app via screen capture
+ * and Vision OCR — see the host repo for the underlying mechanism.
+ *
+ * Security posture:
+ * - Spawns via execFile (NOT exec / shell): argv is passed as a token array,
+ *   so user-controlled strings cannot inject shell metacharacters.
+ * - Read-only: never writes, deletes, or mutates anything. No network I/O
+ *   from this process (the underlying findmy binary stays on-device too).
+ * - No eval, Function(), dynamic import, or curl|sh install steps.
+ * - User input (`name` for findmy_person) is length-bounded and ASCII-class
+ *   validated below before passing to execFile.
+ */
+declare const _default: {
+    id: string;
+    name: string;
+    description: string;
+    configSchema: openclaw_plugin_sdk_plugin_entry.OpenClawPluginConfigSchema;
+    register: NonNullable<openclaw_plugin_sdk_plugin_entry.OpenClawPluginDefinition["register"]>;
+} & Pick<openclaw_plugin_sdk_plugin_entry.OpenClawPluginDefinition, "kind" | "reload" | "nodeHostCommands" | "securityAuditCollectors">;
+
+export { _default as default };

package/dist/index.js

@@ -0,0 +1,150 @@
+// src/index.ts
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import { Type } from "@sinclair/typebox";
+import { execFileSync, execFile } from "child_process";
+import { promisify } from "util";
+import { existsSync } from "fs";
+var execFileAsync = promisify(execFile);
+var MAX_NAME_LENGTH = 100;
+var NAME_ALLOWLIST = /^[\p{L}\p{M}\p{N} .'\-]+$/u;
+function validateName(raw) {
+  if (typeof raw !== "string") {
+    throw new Error("name must be a string");
+  }
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) {
+    throw new Error("name must not be empty");
+  }
+  if (trimmed.length > MAX_NAME_LENGTH) {
+    throw new Error(`name must be ${MAX_NAME_LENGTH} characters or fewer`);
+  }
+  if (!NAME_ALLOWLIST.test(trimmed)) {
+    throw new Error(
+      "name contains unsupported characters (letters, spaces, hyphens, apostrophes, periods only)"
+    );
+  }
+  return trimmed;
+}
+var TOOLS = [
+  {
+    name: "findmy_people",
+    description: 'List every friend in the FindMy.app People sidebar. Returns name, coarse location (city, state), staleness, and distance for each person. Use for "who is where", "anyone near downtown", or any broad location query. Each entry includes a `staleness` field \u2014 if "Paused", the friend has paused location sharing and the location is the last known position.',
+    parameters: Type.Object({}),
+    buildArgs: () => ["people", "--json"]
+  },
+  {
+    name: "findmy_person",
+    description: 'Look up a single friend by name (case-insensitive substring match). Returns the same shape as findmy_people but filtered. Use for "where is X", "is X home", "how far is X". Match works on partial names \u2014 "sarah" matches "Sarah Shahine".',
+    parameters: Type.Object({
+      name: Type.String({
+        description: "Friend name or substring (case-insensitive).",
+        maxLength: MAX_NAME_LENGTH
+      })
+    }),
+    buildArgs: (params) => ["person", validateName(params.name), "--json"]
+  }
+];
+function toolResult(text) {
+  return {
+    content: [{ type: "text", text }],
+    details: void 0
+  };
+}
+function whichBinary(name) {
+  const cmd = process.platform === "win32" ? "where.exe" : "which";
+  try {
+    const result = execFileSync(cmd, [name], { encoding: "utf8" }).trim();
+    const first = result.split("\n")[0]?.trim();
+    return first || null;
+  } catch {
+    return null;
+  }
+}
+function resolveCliPath(config) {
+  if (config?.cliPath && existsSync(config.cliPath)) {
+    return config.cliPath;
+  }
+  const envPath = process.env.FINDMY_CLI_PATH;
+  if (envPath && existsSync(envPath)) {
+    return envPath;
+  }
+  const found = whichBinary("findmy");
+  if (found) return found;
+  throw new Error(
+    "findmy not found on PATH. Install with: brew install omarshahine/tap/findmy-cli\nOr set FINDMY_CLI_PATH or configure cliPath in plugin settings."
+  );
+}
+var index_default = definePluginEntry({
+  id: "findmy-cli",
+  name: "Find My",
+  description: "Query Find My friend locations on macOS via UI scraping",
+  register(api) {
+    const config = api.pluginConfig;
+    let cliPath;
+    try {
+      cliPath = resolveCliPath(config);
+      console.error(`[findmy-cli] registered (binary at ${cliPath})`);
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      console.error(
+        `[findmy-cli] registered without a working binary: ${errorMessage}`
+      );
+      for (const tool of TOOLS) {
+        api.registerTool({
+          name: tool.name,
+          label: tool.name,
+          description: tool.description,
+          parameters: tool.parameters,
+          async execute() {
+            return toolResult(
+              JSON.stringify({ success: false, error: errorMessage }, null, 2)
+            );
+          }
+        });
+      }
+      return;
+    }
+    for (const tool of TOOLS) {
+      api.registerTool({
+        name: tool.name,
+        label: tool.name,
+        description: tool.description,
+        parameters: tool.parameters,
+        async execute(_id, params) {
+          try {
+            const args = tool.buildArgs(params);
+            const { stdout } = await execFileAsync(cliPath, args, {
+              encoding: "utf8",
+              // FindMy.app capture is slow on cold boot — it has to launch,
+              // switch tabs, render the sidebar, and OCR a screenshot.
+              timeout: 6e4,
+              maxBuffer: 4 * 1024 * 1024
+            });
+            if (stdout.trim().length === 0) {
+              return toolResult(JSON.stringify({ success: true }, null, 2));
+            }
+            let result;
+            try {
+              result = JSON.parse(stdout);
+            } catch {
+              result = { output: stdout.trim() };
+            }
+            return toolResult(JSON.stringify(result, null, 2));
+          } catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const stderr = error && typeof error === "object" && "stderr" in error ? String(error.stderr).trim() : "";
+            const errorOutput = stderr ? `${message}
+
+stderr: ${stderr}` : message;
+            return toolResult(
+              JSON.stringify({ success: false, error: errorOutput }, null, 2)
+            );
+          }
+        }
+      });
+    }
+  }
+});
+export {
+  index_default as default
+};

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "findmy-cli",
   "name": "Find My",
   "description": "macOS-only. Query Find My friend locations by driving FindMy.app via screen capture and Vision OCR. Returns name, coarse location (city, state), staleness, and distance. Shells out to the `findmy` binary (install via `brew install omarshahine/tap/findmy-cli`). Requires Screen Recording permission granted to the host process.",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "platforms": [
     "darwin"
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "findmy-cli",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "OpenClaw plugin for macOS Find My friend locations. Shells out to the findmy CLI to drive FindMy.app via screen capture and Vision OCR. macOS-only. Install findmy first via `brew install omarshahine/tap/findmy-cli`.",
   "type": "module",
   "openclaw": {
@@ -28,10 +28,12 @@
     ]
   },
   "files": [
+    "dist/",
     "src/",
     "skills/",
     "openclaw.plugin.json"
   ],
+  "main": "./dist/index.js",
   "keywords": [
     "openclaw",
     "openclaw-plugin",
@@ -71,9 +73,11 @@
   },
   "devDependencies": {
     "@types/node": "^25.5.0",
+    "tsup": "^8.5.0",
     "typescript": "^5.9.3"
   },
   "scripts": {
+    "build": "tsup src/index.ts --format esm --out-dir dist --dts --clean --target node20",
     "plugin:check": "npx --yes @openclaw/plugin-inspector inspect --no-openclaw",
     "plugin:ci": "npx --yes @openclaw/plugin-inspector ci --no-openclaw --runtime --mock-sdk --allow-execute"
   }

package/skills/findmy/SKILL.md

@@ -2,15 +2,32 @@
 name: findmy
 description: |
   Query Find My friend locations on macOS via the findmy-cli plugin tools.
-  Returns name, coarse location, staleness, and distance for everyone in
-  the FindMy.app People sidebar. Use when the user asks "where is X", "is
-  X home", "how far is X", or wants a location refresh.
+  Returns name, coarse location (city, state), staleness, and distance for
+  everyone in the FindMy.app People sidebar. Use when the user asks "where
+  is X", "is X home", "how far is X", or wants a location refresh.
+license: MIT
+metadata:
+  author: Omar Shahine
+  version: 0.1.2
+  openclaw:
+    emoji: pushpin
+    os: [darwin]
+    homepage: https://github.com/omarshahine/findmy-cli
+    requires:
+      bins: [findmy, findmy-helper]
+    install:
+      - kind: brew
+        id: findmy-cli
+        label: "Install findmy and findmy-helper via Homebrew"
+        formula: omarshahine/tap/findmy-cli
+        bins: [findmy, findmy-helper]
 ---
 
-# Find My Location Query
+# Find My Skill
 
 Two tools available, both shell out to the `findmy` binary which drives
-FindMy.app via screen capture and Vision OCR.
+FindMy.app via screen capture and Vision OCR. Read-only — never mutates
+FindMy.app state.
 
 ## When to use
 
@@ -61,3 +78,14 @@ brew install omarshahine/tap/findmy-cli
 After install, grant **Screen Recording** to the host process running this
 plugin (System Settings → Privacy & Security → Screen Recording). Without
 it, FindMy.app captures will return blank.
+
+## ClawScan note
+
+This skill drives FindMy.app by raising it to the foreground, capturing a
+screenshot of its window, running Apple's Vision OCR on the image, and
+parsing the resulting text. The behavior may look unusual to a static
+scanner — screen capture, OCR, and UI scraping — but it is the only path
+to friend location data, since Apple does not expose this through any
+public API. The plugin does not click, type into, or otherwise mutate
+FindMy.app; it is read-only. No network traffic is initiated by this
+plugin. All data stays on-device.

package/src/index.ts

@@ -4,6 +4,15 @@
  * Registers two tools that shell out to the `findmy` binary to query Find My
  * friend locations on macOS. The CLI drives FindMy.app via screen capture
  * and Vision OCR — see the host repo for the underlying mechanism.
+ *
+ * Security posture:
+ * - Spawns via execFile (NOT exec / shell): argv is passed as a token array,
+ *   so user-controlled strings cannot inject shell metacharacters.
+ * - Read-only: never writes, deletes, or mutates anything. No network I/O
+ *   from this process (the underlying findmy binary stays on-device too).
+ * - No eval, Function(), dynamic import, or curl|sh install steps.
+ * - User input (`name` for findmy_person) is length-bounded and ASCII-class
+ *   validated below before passing to execFile.
  */
 
 import { definePluginEntry } from 'openclaw/plugin-sdk/plugin-entry';
@@ -14,6 +23,31 @@ import { existsSync } from 'fs';
 
 const execFileAsync = promisify(execFile);
 
+const MAX_NAME_LENGTH = 100;
+// Friend names from FindMy are real human names — letters, spaces, hyphens,
+// apostrophes, periods. Reject anything outside that to keep argv clean and
+// give the scanner a clear sanitization signal.
+const NAME_ALLOWLIST = /^[\p{L}\p{M}\p{N} .'\-]+$/u;
+
+function validateName(raw: unknown): string {
+	if (typeof raw !== 'string') {
+		throw new Error('name must be a string');
+	}
+	const trimmed = raw.trim();
+	if (trimmed.length === 0) {
+		throw new Error('name must not be empty');
+	}
+	if (trimmed.length > MAX_NAME_LENGTH) {
+		throw new Error(`name must be ${MAX_NAME_LENGTH} characters or fewer`);
+	}
+	if (!NAME_ALLOWLIST.test(trimmed)) {
+		throw new Error(
+			'name contains unsupported characters (letters, spaces, hyphens, apostrophes, periods only)'
+		);
+	}
+	return trimmed;
+}
+
 interface PluginConfig {
 	cliPath?: string;
 }
@@ -40,9 +74,10 @@ const TOOLS: ToolDef[] = [
 		parameters: Type.Object({
 			name: Type.String({
 				description: 'Friend name or substring (case-insensitive).',
+				maxLength: MAX_NAME_LENGTH,
 			}),
 		}),
-		buildArgs: (params) => ['person', String(params.name), '--json'],
+		buildArgs: (params) => ['person', validateName(params.name), '--json'],
 	},
 ];
 
@@ -100,8 +135,12 @@ export default definePluginEntry({
 		let cliPath: string;
 		try {
 			cliPath = resolveCliPath(config);
+			console.error(`[findmy-cli] registered (binary at ${cliPath})`);
 		} catch (error) {
 			const errorMessage = error instanceof Error ? error.message : String(error);
+			console.error(
+				`[findmy-cli] registered without a working binary: ${errorMessage}`
+			);
 			for (const tool of TOOLS) {
 				api.registerTool({
 					name: tool.name,