feat(core): cross-platform Maestro view-hierarchy resolver + screenshot filePath relay + fallback observability

.gitignore

@@ -11,4 +11,10 @@ packages/logger/test/client.js
 packages/sdk-utils/test/client.js
 packs
 docs/
-.claude/
+
+# bstack-ai-harness:begin (managed — do not edit between markers)
+bstack-ai-harness.yml
+.harness-docs.json
+CLAUDE.md
+.claude/
+# bstack-ai-harness:end

.semgrepignore

@@ -19,3 +19,22 @@ packages/core/src/lock.js
 # (the resolve happens *inside* validateArchiveDir itself) so it flags
 # every join. Suppress at the file level with this rationale.
 packages/core/src/archive.js
+
+# api.js path-traversal guards live at the top of the /percy/maestro-screenshot
+# route handler: `name` and `sessionId` are both validated against
+# /^[a-zA-Z0-9_-]+$/ (SAFE_ID, line ~322) BEFORE any path.join() runs.
+# Traversal sequences (`..`, `/`, `\0`) are rejected with 400 there. The
+# fallback walker is also depth-capped at 15 levels. semgrep's
+# path-join-resolve-traversal rule cannot follow the regex validation
+# chain across the function body, so it flags the joins on lines 445
+# and 462. Inline `// nosemgrep` directives (preceding and same-line)
+# were not honored by the semgrep CI version in use — suppress at the
+# file level with this rationale.
+packages/core/src/api.js
+
+# Test files load fixtures from hardcoded subpaths under
+# test/fixtures/maestro-{hierarchy,ios-hierarchy}. The fixture filenames
+# are static literals in each test; semgrep flags the path.join() used
+# in the file-load helper anyway. No user input flows here.
+packages/core/test/unit/maestro-hierarchy.test.js
+packages/core/test/unit/maestro-hierarchy.parity.test.js

packages/core/package.json

@@ -50,15 +50,19 @@
     "@percy/logger": "1.31.15-beta.0",
     "@percy/monitoring": "1.31.15-beta.0",
     "@percy/webdriver-utils": "1.31.15-beta.0",
+    "@grpc/grpc-js": "^1.14.3",
+    "@grpc/proto-loader": "^0.8.0",
     "content-disposition": "^0.5.4",
     "cross-spawn": "^7.0.3",
     "extract-zip": "^2.0.1",
     "fast-glob": "^3.2.11",
+    "fast-xml-parser": "^4.4.1",
     "micromatch": "^4.0.8",
     "mime-types": "^2.1.34",
     "pako": "^2.1.0",
     "path-to-regexp": "^6.3.0",
     "rimraf": "^3.0.2",
+    "busboy": "^1.6.0",
     "ws": "^8.17.1",
     "yaml": "^2.4.1"
   },