@relayfile/sdk 0.10.52 → 0.10.53

package/dist/client.js

@@ -397,7 +397,13 @@ class RelayFileChangeSubscription {
         this.onChange = onChange;
         this.options = options;
         this.globPatterns = globs.map((pattern) => normalizeChangePattern(pattern));
-        this.pathScopes = options?.pathScope?.length ? options.pathScope.map((pattern) => normalizeChangePattern(pattern)) : null;
+        // A wildcard-free pathScope entry (e.g. "/ramp/transactions") is a DIRECTORY
+        // SUBTREE scope: expand it into the exact path plus its "/**" subtree filter
+        // so it matches the directory and everything under it. A bare path is never
+        // exact-file; use a glob for that. See expandDirectoryScope for the rule.
+        this.pathScopes = options?.pathScope?.length
+            ? options.pathScope.flatMap((pattern) => expandDirectoryScope(normalizeChangePattern(pattern)))
+            : null;
         this.shouldCoalesce = (options?.coalesce ?? "fire-once") !== "none";
         this.coalesceMs = Math.max(0, Math.floor(options?.coalesceMs ?? DEFAULT_CHANGE_COALESCE_MS));
     }
@@ -747,6 +753,45 @@ function normalizeChangePattern(pattern) {
     }
     return segments;
 }
+/**
+ * A wildcard-free `pathScope` entry is DEFINED as a DIRECTORY SUBTREE scope: it
+ * matches the path itself AND everything under it. To scope to an exact file,
+ * pass that exact path as a glob in the first `subscribe(globs, ...)` argument
+ * (the `globs` list is matched exactly unless an entry has a `*`/`**` wildcard);
+ * a bare `pathScope` path is never exact-file. This is a deliberate API-design
+ * choice (Option A), not an
+ * accident of the server matcher: it makes the common "watch this directory"
+ * intent Just Work and avoids a silent zero-event foot-gun.
+ *
+ * Why it MUST be subtree, and why "exact-file" is not a safe alternative:
+ * Relayfile creates descendants under file-looking paths (e.g.
+ * `/linear/issues/ENG-1.json/replies/draft.json`), so a bare path can never be
+ * assumed to name a leaf. Treating a wildcard-free entry as directory-scope is
+ * the only consistent rule.
+ *
+ * The data plane (see `webSocketPathMatches` in internal/httpapi/websocket.go)
+ * matches a `path=` filter against an event path with these semantics:
+ *   - exact match: `path` == the event path, OR
+ *   - trailing `**`: `/ramp/transactions/**` matches any STRICT descendant, OR
+ *   - per-segment `*` wildcards, requiring equal segment counts otherwise.
+ * A bare directory prefix like `/ramp/transactions` (no wildcard) would
+ * therefore match ONLY an event whose path is exactly `/ramp/transactions` —
+ * ZERO children — so a caller scoping to `["/ramp/transactions"]` opens a WS
+ * that silently receives no events (proven: `path=/ramp/transactions` -> 0
+ * events; `/**` -> 6). The same count-must-match rule in `matchChangeSegments`
+ * makes the client-side filter agree, so the miss would be doubly silent.
+ *
+ * Implementation: for a wildcard-free entry, emit BOTH the exact path AND the
+ * `.../**` subtree filter — the union matches the directory node itself plus its
+ * entire subtree. Entries that already contain a `*`/`**` wildcard are honored
+ * verbatim — an intentionally precise glob is never broadened.
+ */
+function expandDirectoryScope(segments) {
+    if (segments.some((segment) => segment === "*" || segment === "**")) {
+        return [segments];
+    }
+    return [segments, [...segments, "**"]];
+}
 function normalizeChangePath(path) {
     const normalized = path.startsWith("/") ? path : `/${path}`;
     const trimmed = normalized.replace(/\/+$/, "");

package/dist/types.d.ts

@@ -416,6 +416,22 @@ export interface LayoutManifest {
 export interface SubscribeOptions {
     coalesce?: "none" | "fire-once";
     coalesceMs?: number;
+    /**
+     * Narrow the server-side event stream to one or more path scopes.
+     *
+     * A **wildcard-free** entry is a DIRECTORY SUBTREE scope: `"/ramp/transactions"`
+     * matches that path AND everything under it. A bare path is NOT treated as an
+     * exact-file match — Relayfile creates descendants under file-looking paths
+     * (e.g. `/linear/issues/ENG-1.json/replies/draft.json`), so a wildcard-free
+     * scope always means "this directory and its subtree".
+     *
+     * To scope to something more precise, pass an explicit glob: a trailing `**`
+     * (`"/ramp/transactions/**"`) for a subtree, or per-segment `*` wildcards
+     * (`"/github/repos/acme/api/pulls/*"`); these are honored verbatim. For an
+     * exact single file, pass that exact path as a glob in the first `subscribe`
+     * argument (`subscribe(globs, ...)`, e.g. `["/linear/issues/ENG-1.json"]`) —
+     * the `globs` list is matched exactly unless it contains a `*`/`**` wildcard.
+     */
     pathScope?: string[];
     from?: "now" | "legacy";
     cursor?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relayfile/sdk",
-  "version": "0.10.52",
+  "version": "0.10.53",
   "description": "TypeScript SDK for relayfile — real-time filesystem for humans and agents",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -59,15 +59,15 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@relayfile/core": "0.10.52",
+    "@relayfile/core": "0.10.53",
     "ignore": "^7.0.5",
     "tar": "^7.5.10"
   },
   "optionalDependencies": {
-    "@relayfile/mount-darwin-arm64": "0.10.52",
-    "@relayfile/mount-darwin-x64": "0.10.52",
-    "@relayfile/mount-linux-arm64": "0.10.52",
-    "@relayfile/mount-linux-x64": "0.10.52"
+    "@relayfile/mount-darwin-arm64": "0.10.53",
+    "@relayfile/mount-darwin-x64": "0.10.53",
+    "@relayfile/mount-linux-arm64": "0.10.53",
+    "@relayfile/mount-linux-x64": "0.10.53"
   },
   "devDependencies": {
     "typescript": "^5.7.3",