ucu-mcp 0.3.4 → 0.3.7

package/CHANGELOG.md

@@ -5,6 +5,56 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.7] - 2026-06-07
+
+### Fixed
+
+- `find_element` value-schema test is no longer a tautology. The 0.3.6 release fixed a *symptom* of the bug (the old test called `handler()` directly, bypassing the McpServer schema-validation wrapper, and then asserted `r.isError === true` which was `undefined`); the underlying tautology remained: the test re-created a local `z.string().min(1).optional()` instead of exercising the real schema. 0.3.7 exports the actual `findElementInputSchema` from `src/mcp/tools.ts` and the test now imports it via `findElementInputSchema.value`, so the assertion genuinely pins the production schema. Pins the 0.3.2 commit `46d4ddd` semantic.
+- CHANGELOG/JXA `textMatches` comment math is now correct: 3 sources → 1 RegExp = **2 fewer** compilations per matched element. The 0.3.5/0.3.6 wording "three fewer" was off by one and has been corrected in both `src/platform/macos.ts` and this CHANGELOG.
+
+### Tests
+
+- `macos-platform`: text-side regex pre-validation now has a regression test mirroring the existing value-side test (`findElement({text:"[", textMode:"regex"})` throws `PlatformError` with an `Invalid regex pattern` message). Pins the original text-side guard that the 0.3.2 commit mirrored onto the value side.
+- `macos-platform`: all-no-bounds edge case for the `near` sort — when every result is missing `bounds`, the original JXA order is preserved. Pins the 0.3.2 commit `0710eca` no-bounds fallback against a future refactor that introduces a non-stable comparator.
+
+### Hygiene
+
+- `findElementInputSchema` is now a named export from `src/mcp/tools.ts` (with a JSDoc comment explaining why the schema is exported) so the unit test can assert the production schema directly instead of constructing a local copy.
+- Added `prepublishOnly` script to `package.json` that runs `npm test && npm run build` before `npm publish`. This is a structural guard against the yank rhythm that hit 0.3.3 and 0.3.5: a failed test or build will now block the publish at the npm level, not at the human level. (Raman review Minor #3)
+
+## [0.3.5] - 2026-06-06  *(Yanked — see 0.3.6)*
+
+### Tests
+
+- `macos-platform`: new regression test for the value-field regex pre-validation (`findElement({value:"[", textMode:"regex"})` throws `PlatformError` with an `Invalid regex pattern` message). Pins the 0.3.2 commit `0710eca` behavior change.
+- `macos-platform`: new regression test for the near-sort bounds fallback (elements without `bounds` are pushed to the end of the sorted result, instead of implicitly being centered at (0,0)). Pins the 0.3.2 commit `0710eca` second behavior change.
+- `tools-layer`: new regression test that `find_element({value:""})` returns `isError: true`. Pins the 0.3.2 commit `46d4ddd` schema tightening (`z.string().min(1).optional()`).
+
+### Changed
+
+- JXA `textMatches` regex branch now compiles the `RegExp` once per element instead of once per source (name / value / description) — three fewer compilations per matched element when `textMode="regex"`. The TS-side pre-validation in `findElement` guarantees the pattern is valid, so the `RegExp` constructor cannot throw here. (Herschel review perf Minor)
+- JXA `textMatches` regex branch now compiles the `RegExp` once per element instead of once per source (name / value / description) — **two** fewer compilations per matched element when `textMode="regex"` (corrected in 0.3.7; 0.3.5/0.3.6 said "three fewer" which was off by one: 3 sources → 1 regex = 2 saved). The TS-side pre-validation in `findElement` guarantees the pattern is valid, so the `RegExp` constructor cannot throw here. (Herschel review perf Minor)
+
+### Fixed
+
+- Comment on the JXA `matchesValue` helper no longer claims "JXA function declarations are order-sensitive" (they aren't — JXA hoists them like any ES engine). The comment now correctly notes that the leading placement is for readability. (Herschel review comment Minor)
+
+## [0.3.6] - 2026-06-06
+
+### Re-publish of 0.3.5
+
+0.3.5 was published with a test that didn't account for the McpServer
+schema-validation wrapper. The test called `handler({value:""})`
+directly, which bypasses the schema validation, so the assertion
+`r.isError === true` saw `undefined` instead. The actual fix
+(asserting the zod schema constraint directly) was a one-test rewrite;
+0.3.6 carries the same code as 0.3.5 plus the test fix.
+
+### Yanked
+
+`ucu-mcp@0.3.5` was unpublished (yanked) within minutes of release
+due to the broken test. Users on `@latest` are now on 0.3.6.
+
 ## [0.3.4] - 2026-06-06
 
 ### Re-publish of 0.3.3
@@ -25,7 +75,7 @@ contents and CHANGELOG entry as 0.3.3 plus this note.
 `ucu-mcp@0.3.3` was unpublished (yanked) shortly after release due to
 the test file compile error. Users on `@latest` are now on 0.3.4.
 
-## [0.3.3] - 2026-06-06
+## [0.3.3] - 2026-06-06  *(Yanked — see 0.3.4)*
 
 ### Tests
 

package/dist/src/mcp/tools.d.ts

@@ -5,11 +5,32 @@
  * a shared safety/permission/retry pipeline (`withSafety`).
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
 import type { AppTarget } from "../platform/base.js";
 /**
  * Get the currently active target context (set by focus_app).
  */
 export declare function getActiveTarget(): AppTarget | undefined;
+export declare const findElementInputSchema: {
+    text: z.ZodOptional<z.ZodString>;
+    role: z.ZodOptional<z.ZodString>;
+    app: z.ZodOptional<z.ZodString>;
+    depth: z.ZodOptional<z.ZodNumber>;
+    includeBounds: z.ZodDefault<z.ZodBoolean>;
+    maxResults: z.ZodDefault<z.ZodNumber>;
+    textMode: z.ZodDefault<z.ZodEnum<{
+        contains: "contains";
+        exact: "exact";
+        regex: "regex";
+    }>>;
+    visibleOnly: z.ZodDefault<z.ZodBoolean>;
+    value: z.ZodOptional<z.ZodString>;
+    index: z.ZodOptional<z.ZodNumber>;
+    near: z.ZodOptional<z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, z.core.$strip>>;
+};
 export declare function startUserActivityMonitor(): void;
 export declare function stopUserActivityMonitor(): void;
 export declare function registerTools(server: McpServer): void;

package/dist/src/mcp/tools.js

@@ -37,6 +37,24 @@ const captureAfterFields = {
     captureMaxWidth: z.number().default(1280).describe("Maximum width for the post-action screenshot"),
     captureFormat: z.enum(["png", "jpeg"]).default("jpeg").describe("Format for the post-action screenshot"),
 };
+// Exported so unit tests can pin the schema constraint directly instead
+// of going through the McpServer wrapper (which `handler()` calls
+// bypass). (Herschel review Major: 0.3.5's value='' test was a
+// tautology because it re-created a local zod schema instead of
+// asserting against this one.)
+export const findElementInputSchema = {
+    text: z.string().optional().describe("Text to search"),
+    role: z.string().optional().describe("AX role"),
+    app: z.string().optional().describe("Target app"),
+    depth: z.number().optional().describe("AX tree depth"),
+    includeBounds: z.boolean().default(true).describe("Include bounds"),
+    maxResults: z.number().min(1).max(200).default(50).describe("Max results"),
+    textMode: z.enum(["contains", "exact", "regex"]).default("contains").describe("Text matching mode: contains (default), exact, or regex"),
+    visibleOnly: z.boolean().default(false).describe("Only return elements with valid on-screen bounds"),
+    value: z.string().min(1).optional().describe("Filter by AX element value (text/regex/exact, see textMode). Empty string is treated as unset (omit the field instead)."),
+    index: z.number().int().nonnegative().optional().describe("Return only the Nth match (0-based) after all other filtering and sorting"),
+    near: z.object({ x: z.number(), y: z.number() }).optional().describe("Sort results by ascending distance to this point and return closest first"),
+};
 async function resolvePoint(x, y, windowId) {
     if (!windowId)
         return { x, y };
@@ -547,15 +565,7 @@ export function registerTools(server) {
         return actionResponse("move", { moved: true, x: pt.x, y: pt.y }, { x: pt.x, y: pt.y, windowId: params.windowId }, params.captureAfter, params.captureFormat, params.captureMaxWidth);
     });
     registry.register("move");
-    registerTool("find_element", "Find accessibility elements by text, role, or value. Supports value/index/near selectors.", {
-        text: z.string().optional().describe("Text to search"), role: z.string().optional().describe("AX role"), app: z.string().optional().describe("Target app"),
-        depth: z.number().optional().describe("AX tree depth"), includeBounds: z.boolean().default(true).describe("Include bounds"), maxResults: z.number().min(1).max(200).default(50).describe("Max results"),
-        textMode: z.enum(["contains", "exact", "regex"]).default("contains").describe("Text matching mode: contains (default), exact, or regex"),
-        visibleOnly: z.boolean().default(false).describe("Only return elements with valid on-screen bounds"),
-        value: z.string().min(1).optional().describe("Filter by AX element value (text/regex/exact, see textMode). Empty string is treated as unset (omit the field instead)."),
-        index: z.number().int().nonnegative().optional().describe("Return only the Nth match (0-based) after all other filtering and sorting"),
-        near: z.object({ x: z.number(), y: z.number() }).optional().describe("Sort results by ascending distance to this point and return closest first"),
-    }, async (params) => {
+    registerTool("find_element", "Find accessibility elements by text, role, or value. Supports value/index/near selectors.", findElementInputSchema, async (params) => {
         const effectiveApp = params.app || getActiveTarget()?.appName;
         const response = await withSafety({ action: "find_element", params: {}, requiresAccessibility: true,
             execute: () => getPlatform().findElement({ text: params.text, role: params.role, app: effectiveApp, depth: params.depth, includeBounds: params.includeBounds, maxResults: params.maxResults, textMode: params.textMode, visibleOnly: params.visibleOnly, value: params.value, index: params.index, near: params.near }) });

package/dist/src/platform/macos.js

@@ -866,9 +866,9 @@ export class MacOSPlatform {
       // Shared filter helper. textMatches and valueMatches used to be near
       // copies of the same three-branch dispatch (contains / exact / regex);
       // this consolidates the logic so the two callers only differ in which
-      // sources they iterate. Declared before textMatches/valueMatches
-      // because JXA function declarations are order-sensitive within a
-      // script. (Singer Nit)
+      // sources they iterate. Declared before textMatches/valueMatches for
+      // readability — JXA's function declarations are hoisted, so order
+      // doesn't affect callability. (Singer Nit + Herschel comment fix)
       function matchesValue(filter, value, mode) {
         if (filter === null) return true;
         if (mode === "exact") {
@@ -886,8 +886,18 @@ export class MacOSPlatform {
       function textMatches(elemName, elemValue, elemDesc) {
         if (textFilter === null) return true;
         var sources = [elemName, elemValue, elemDesc];
-        for (var i = 0; i < sources.length; i++) {
-          if (matchesValue(textFilter, sources[i], textMode)) return true;
+        // Hoist regex compilation out of the loop. The TS-side pre-validation
+        // in findElement guarantees the pattern is valid, so the RegExp
+        // constructor cannot throw here. (Herschel perf Minor)
+        if (textMode === "regex") {
+          var reText = new RegExp(textFilter, "i");
+          for (var i = 0; i < sources.length; i++) {
+            if (reText.test(sources[i])) return true;
+          }
+          return false;
+        }
+        for (var j = 0; j < sources.length; j++) {
+          if (matchesValue(textFilter, sources[j], textMode)) return true;
         }
         return false;
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ucu-mcp",
-  "version": "0.3.4",
+  "version": "0.3.7",
   "description": "MCP server for Universal Computer Use — desktop automation for AI agents via Model Context Protocol",
   "type": "module",
   "bin": {
@@ -26,6 +26,7 @@
     "test:integration": "vitest run tests/integration/",
     "test:macos-gui": "UCU_MACOS_GUI_SMOKE=1 vitest run tests/integration/macos-gui-smoke.test.ts",
     "test:client-cli": "UCU_CLIENT_CLI_SMOKE=1 vitest run tests/integration/client-cli-smoke.test.ts",
+    "prepublishOnly": "npx vitest run tests/unit/ && npm run build",
     "build:native": "cd native/cgevent && swiftc -O -o cgevent-helper main.swift -framework CoreGraphics -framework Foundation && cd ../ocr && swiftc -O -o ocr-helper main.swift -framework Vision -framework AppKit"
   },
   "keywords": [