findmy-cli 0.1.0 → 0.1.1

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.1",
   "platforms": [
     "darwin"
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "findmy-cli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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.1
+  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,