@react-grab/utils 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Aiden Bai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/client.cjs

@@ -0,0 +1,170 @@
+'use strict';
+
+// src/client.ts
+var CONNECTION_CHECK_TTL_MS = 5e3;
+var STORAGE_KEY = "react-grab:agent-sessions";
+var parseSSEEvent = (eventBlock) => {
+  let eventType = "";
+  let data = "";
+  for (const line of eventBlock.split("\n")) {
+    if (line.startsWith("event:")) eventType = line.slice(6).trim();
+    else if (line.startsWith("data:")) data = line.slice(5).trim();
+  }
+  return { eventType, data };
+};
+var streamSSE = async function* (stream, signal) {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  let aborted = false;
+  const onAbort = () => {
+    aborted = true;
+    reader.cancel().catch(() => {
+    });
+  };
+  signal.addEventListener("abort", onAbort, { once: true });
+  try {
+    if (signal.aborted) {
+      throw new DOMException("Aborted", "AbortError");
+    }
+    while (true) {
+      const result = await reader.read();
+      if (aborted || signal.aborted) {
+        throw new DOMException("Aborted", "AbortError");
+      }
+      const { done, value } = result;
+      if (value) buffer += decoder.decode(value, { stream: true });
+      let boundary;
+      while ((boundary = buffer.indexOf("\n\n")) !== -1) {
+        const { eventType, data } = parseSSEEvent(buffer.slice(0, boundary));
+        buffer = buffer.slice(boundary + 2);
+        if (eventType === "done") return;
+        if (eventType === "error") throw new Error(data || "Agent error");
+        if (data) yield data;
+      }
+      if (done) break;
+    }
+  } finally {
+    signal.removeEventListener("abort", onAbort);
+    try {
+      reader.releaseLock();
+    } catch {
+    }
+  }
+};
+var isRecord = (value) => typeof value === "object" && value !== null;
+var getStoredAgentContext = (storage, sessionId, storageKey = STORAGE_KEY) => {
+  const rawSessions = storage.getItem(storageKey);
+  if (!rawSessions) throw new Error("No sessions to resume");
+  let parsed;
+  try {
+    parsed = JSON.parse(rawSessions);
+  } catch {
+    throw new Error("Failed to parse stored sessions");
+  }
+  if (!isRecord(parsed)) throw new Error("Invalid stored sessions");
+  const storedSession = parsed[sessionId];
+  if (!isRecord(storedSession)) {
+    throw new Error(`Session ${sessionId} not found`);
+  }
+  const context = storedSession.context;
+  if (!isRecord(context)) throw new Error(`Session ${sessionId} is invalid`);
+  const content = context.content;
+  const prompt = context.prompt;
+  if (!Array.isArray(content) || typeof prompt !== "string") {
+    throw new Error(`Session ${sessionId} is invalid`);
+  }
+  const options = context.options;
+  const storedSessionId = context.sessionId;
+  return {
+    content,
+    prompt,
+    options,
+    sessionId: typeof storedSessionId === "string" ? storedSessionId : void 0
+  };
+};
+var streamAgentStatusFromServer = async function* (options, context, signal) {
+  const startTime = Date.now();
+  const sessionId = context.sessionId;
+  const pollIntervalMs = options.pollIntervalMs ?? 100;
+  const agentUrl = `${options.serverUrl}${options.agentPath ?? "/agent"}`;
+  const handleAbort = () => {
+    if (!sessionId) return;
+    const abortPath = options.abortPath?.(sessionId) ?? `/abort/${sessionId}`;
+    fetch(`${options.serverUrl}${abortPath}`, { method: "POST" }).catch(
+      () => {
+      }
+    );
+  };
+  signal.addEventListener("abort", handleAbort, { once: true });
+  try {
+    const response = await fetch(agentUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(context),
+      signal
+    });
+    if (!response.ok) {
+      throw new Error(`Server error: ${response.status}`);
+    }
+    if (!response.body) {
+      throw new Error("No response body");
+    }
+    const iterator = streamSSE(response.body, signal)[Symbol.asyncIterator]();
+    let isDone = false;
+    let pendingNext = iterator.next();
+    let lastStatus = null;
+    while (!isDone) {
+      const result = await Promise.race([
+        pendingNext.then((iteratorResult) => ({
+          type: "status",
+          iteratorResult
+        })),
+        new Promise(
+          (resolve) => setTimeout(() => resolve({ type: "timeout" }), pollIntervalMs)
+        )
+      ]);
+      const elapsedSeconds = (Date.now() - startTime) / 1e3;
+      if (result.type === "status") {
+        const iteratorResult = result.iteratorResult;
+        isDone = iteratorResult.done ?? false;
+        if (!isDone && iteratorResult.value) {
+          lastStatus = iteratorResult.value;
+          pendingNext = iterator.next();
+        }
+      }
+      if (lastStatus === options.completedStatus) {
+        yield `Completed in ${elapsedSeconds.toFixed(1)}s`;
+      } else if (lastStatus) {
+        yield `${lastStatus} ${elapsedSeconds.toFixed(1)}s`;
+      } else {
+        yield `Working\u2026 ${elapsedSeconds.toFixed(1)}s`;
+      }
+    }
+  } finally {
+    signal.removeEventListener("abort", handleAbort);
+  }
+};
+var createCachedConnectionChecker = (checkConnection, ttlMs = CONNECTION_CHECK_TTL_MS) => {
+  let cache = null;
+  return async () => {
+    const now = Date.now();
+    if (cache && now - cache.timestamp < ttlMs) return cache.result;
+    try {
+      const result = await checkConnection();
+      cache = { result, timestamp: now };
+      return result;
+    } catch {
+      cache = { result: false, timestamp: now };
+      return false;
+    }
+  };
+};
+
+exports.CONNECTION_CHECK_TTL_MS = CONNECTION_CHECK_TTL_MS;
+exports.STORAGE_KEY = STORAGE_KEY;
+exports.createCachedConnectionChecker = createCachedConnectionChecker;
+exports.getStoredAgentContext = getStoredAgentContext;
+exports.parseSSEEvent = parseSSEEvent;
+exports.streamAgentStatusFromServer = streamAgentStatusFromServer;
+exports.streamSSE = streamSSE;

package/dist/client.d.cts

@@ -0,0 +1,30 @@
+declare const CONNECTION_CHECK_TTL_MS = 5000;
+declare const STORAGE_KEY = "react-grab:agent-sessions";
+interface SSEEvent {
+    eventType: string;
+    data: string;
+}
+declare const parseSSEEvent: (eventBlock: string) => SSEEvent;
+declare const streamSSE: (stream: ReadableStream<Uint8Array>, signal: AbortSignal) => AsyncGenerator<string, void, unknown>;
+interface StoredAgentContext {
+    content: string[];
+    prompt: string;
+    options?: unknown;
+    sessionId?: string;
+}
+declare const getStoredAgentContext: (storage: {
+    getItem: (key: string) => string | null;
+}, sessionId: string, storageKey?: string) => StoredAgentContext;
+interface StreamAgentStatusFromServerOptions {
+    serverUrl: string;
+    completedStatus: string;
+    agentPath?: string;
+    abortPath?: (sessionId: string) => string;
+    pollIntervalMs?: number;
+}
+declare const streamAgentStatusFromServer: <TContext extends {
+    sessionId?: string;
+}>(options: StreamAgentStatusFromServerOptions, context: TContext, signal: AbortSignal) => AsyncGenerator<string, void, unknown>;
+declare const createCachedConnectionChecker: (checkConnection: () => Promise<boolean>, ttlMs?: number) => (() => Promise<boolean>);
+
+export { CONNECTION_CHECK_TTL_MS, type SSEEvent, STORAGE_KEY, type StoredAgentContext, type StreamAgentStatusFromServerOptions, createCachedConnectionChecker, getStoredAgentContext, parseSSEEvent, streamAgentStatusFromServer, streamSSE };

package/dist/client.d.ts

@@ -0,0 +1,30 @@
+declare const CONNECTION_CHECK_TTL_MS = 5000;
+declare const STORAGE_KEY = "react-grab:agent-sessions";
+interface SSEEvent {
+    eventType: string;
+    data: string;
+}
+declare const parseSSEEvent: (eventBlock: string) => SSEEvent;
+declare const streamSSE: (stream: ReadableStream<Uint8Array>, signal: AbortSignal) => AsyncGenerator<string, void, unknown>;
+interface StoredAgentContext {
+    content: string[];
+    prompt: string;
+    options?: unknown;
+    sessionId?: string;
+}
+declare const getStoredAgentContext: (storage: {
+    getItem: (key: string) => string | null;
+}, sessionId: string, storageKey?: string) => StoredAgentContext;
+interface StreamAgentStatusFromServerOptions {
+    serverUrl: string;
+    completedStatus: string;
+    agentPath?: string;
+    abortPath?: (sessionId: string) => string;
+    pollIntervalMs?: number;
+}
+declare const streamAgentStatusFromServer: <TContext extends {
+    sessionId?: string;
+}>(options: StreamAgentStatusFromServerOptions, context: TContext, signal: AbortSignal) => AsyncGenerator<string, void, unknown>;
+declare const createCachedConnectionChecker: (checkConnection: () => Promise<boolean>, ttlMs?: number) => (() => Promise<boolean>);
+
+export { CONNECTION_CHECK_TTL_MS, type SSEEvent, STORAGE_KEY, type StoredAgentContext, type StreamAgentStatusFromServerOptions, createCachedConnectionChecker, getStoredAgentContext, parseSSEEvent, streamAgentStatusFromServer, streamSSE };

package/dist/client.js

@@ -0,0 +1,162 @@
+// src/client.ts
+var CONNECTION_CHECK_TTL_MS = 5e3;
+var STORAGE_KEY = "react-grab:agent-sessions";
+var parseSSEEvent = (eventBlock) => {
+  let eventType = "";
+  let data = "";
+  for (const line of eventBlock.split("\n")) {
+    if (line.startsWith("event:")) eventType = line.slice(6).trim();
+    else if (line.startsWith("data:")) data = line.slice(5).trim();
+  }
+  return { eventType, data };
+};
+var streamSSE = async function* (stream, signal) {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  let aborted = false;
+  const onAbort = () => {
+    aborted = true;
+    reader.cancel().catch(() => {
+    });
+  };
+  signal.addEventListener("abort", onAbort, { once: true });
+  try {
+    if (signal.aborted) {
+      throw new DOMException("Aborted", "AbortError");
+    }
+    while (true) {
+      const result = await reader.read();
+      if (aborted || signal.aborted) {
+        throw new DOMException("Aborted", "AbortError");
+      }
+      const { done, value } = result;
+      if (value) buffer += decoder.decode(value, { stream: true });
+      let boundary;
+      while ((boundary = buffer.indexOf("\n\n")) !== -1) {
+        const { eventType, data } = parseSSEEvent(buffer.slice(0, boundary));
+        buffer = buffer.slice(boundary + 2);
+        if (eventType === "done") return;
+        if (eventType === "error") throw new Error(data || "Agent error");
+        if (data) yield data;
+      }
+      if (done) break;
+    }
+  } finally {
+    signal.removeEventListener("abort", onAbort);
+    try {
+      reader.releaseLock();
+    } catch {
+    }
+  }
+};
+var isRecord = (value) => typeof value === "object" && value !== null;
+var getStoredAgentContext = (storage, sessionId, storageKey = STORAGE_KEY) => {
+  const rawSessions = storage.getItem(storageKey);
+  if (!rawSessions) throw new Error("No sessions to resume");
+  let parsed;
+  try {
+    parsed = JSON.parse(rawSessions);
+  } catch {
+    throw new Error("Failed to parse stored sessions");
+  }
+  if (!isRecord(parsed)) throw new Error("Invalid stored sessions");
+  const storedSession = parsed[sessionId];
+  if (!isRecord(storedSession)) {
+    throw new Error(`Session ${sessionId} not found`);
+  }
+  const context = storedSession.context;
+  if (!isRecord(context)) throw new Error(`Session ${sessionId} is invalid`);
+  const content = context.content;
+  const prompt = context.prompt;
+  if (!Array.isArray(content) || typeof prompt !== "string") {
+    throw new Error(`Session ${sessionId} is invalid`);
+  }
+  const options = context.options;
+  const storedSessionId = context.sessionId;
+  return {
+    content,
+    prompt,
+    options,
+    sessionId: typeof storedSessionId === "string" ? storedSessionId : void 0
+  };
+};
+var streamAgentStatusFromServer = async function* (options, context, signal) {
+  const startTime = Date.now();
+  const sessionId = context.sessionId;
+  const pollIntervalMs = options.pollIntervalMs ?? 100;
+  const agentUrl = `${options.serverUrl}${options.agentPath ?? "/agent"}`;
+  const handleAbort = () => {
+    if (!sessionId) return;
+    const abortPath = options.abortPath?.(sessionId) ?? `/abort/${sessionId}`;
+    fetch(`${options.serverUrl}${abortPath}`, { method: "POST" }).catch(
+      () => {
+      }
+    );
+  };
+  signal.addEventListener("abort", handleAbort, { once: true });
+  try {
+    const response = await fetch(agentUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(context),
+      signal
+    });
+    if (!response.ok) {
+      throw new Error(`Server error: ${response.status}`);
+    }
+    if (!response.body) {
+      throw new Error("No response body");
+    }
+    const iterator = streamSSE(response.body, signal)[Symbol.asyncIterator]();
+    let isDone = false;
+    let pendingNext = iterator.next();
+    let lastStatus = null;
+    while (!isDone) {
+      const result = await Promise.race([
+        pendingNext.then((iteratorResult) => ({
+          type: "status",
+          iteratorResult
+        })),
+        new Promise(
+          (resolve) => setTimeout(() => resolve({ type: "timeout" }), pollIntervalMs)
+        )
+      ]);
+      const elapsedSeconds = (Date.now() - startTime) / 1e3;
+      if (result.type === "status") {
+        const iteratorResult = result.iteratorResult;
+        isDone = iteratorResult.done ?? false;
+        if (!isDone && iteratorResult.value) {
+          lastStatus = iteratorResult.value;
+          pendingNext = iterator.next();
+        }
+      }
+      if (lastStatus === options.completedStatus) {
+        yield `Completed in ${elapsedSeconds.toFixed(1)}s`;
+      } else if (lastStatus) {
+        yield `${lastStatus} ${elapsedSeconds.toFixed(1)}s`;
+      } else {
+        yield `Working\u2026 ${elapsedSeconds.toFixed(1)}s`;
+      }
+    }
+  } finally {
+    signal.removeEventListener("abort", handleAbort);
+  }
+};
+var createCachedConnectionChecker = (checkConnection, ttlMs = CONNECTION_CHECK_TTL_MS) => {
+  let cache = null;
+  return async () => {
+    const now = Date.now();
+    if (cache && now - cache.timestamp < ttlMs) return cache.result;
+    try {
+      const result = await checkConnection();
+      cache = { result, timestamp: now };
+      return result;
+    } catch {
+      cache = { result: false, timestamp: now };
+      return false;
+    }
+  };
+};
+
+export { CONNECTION_CHECK_TTL_MS, STORAGE_KEY, createCachedConnectionChecker, getStoredAgentContext, parseSSEEvent, streamAgentStatusFromServer, streamSSE };

package/dist/server.cjs

@@ -0,0 +1,35 @@
+'use strict';
+
+// src/server.ts
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var COMMAND_INSTALL_MAP = {
+  "cursor-agent": "Install Cursor (https://cursor.com) and ensure 'cursor-agent' is in your PATH.",
+  gemini: "Install the Gemini CLI: npm install -g @anthropic-ai/gemini-cli\nOr see: https://github.com/google-gemini/gemini-cli",
+  claude: "Install Claude Code: npm install -g @anthropic-ai/claude-code\nOr see: https://github.com/anthropics/claude-code"
+};
+var formatSpawnError = (error, commandName) => {
+  const spawnError = error;
+  const isNotFound = spawnError.code === "ENOENT" || spawnError.message && spawnError.message.includes("ENOENT");
+  if (isNotFound) {
+    const installInfo = COMMAND_INSTALL_MAP[commandName];
+    const baseMessage = `Command '${commandName}' not found.`;
+    if (installInfo) {
+      return `${baseMessage}
+
+${installInfo}`;
+    }
+    return `${baseMessage}
+
+Make sure '${commandName}' is installed and available in your PATH.`;
+  }
+  const isPermissionDenied = spawnError.code === "EACCES" || spawnError.message && spawnError.message.includes("EACCES");
+  if (isPermissionDenied) {
+    return `Permission denied when trying to run '${commandName}'.
+
+Check that the command is executable: chmod +x $(which ${commandName})`;
+  }
+  return error.message;
+};
+
+exports.formatSpawnError = formatSpawnError;
+exports.sleep = sleep;

package/dist/server.d.cts

@@ -0,0 +1,13 @@
+declare const sleep: (ms: number) => Promise<void>;
+interface AgentMessage {
+    type: "status" | "error" | "done";
+    content: string;
+}
+interface AgentCoreOptions {
+    cwd?: string;
+    signal?: AbortSignal;
+    sessionId?: string;
+}
+declare const formatSpawnError: (error: Error, commandName: string) => string;
+
+export { type AgentCoreOptions, type AgentMessage, formatSpawnError, sleep };

package/dist/server.d.ts

@@ -0,0 +1,13 @@
+declare const sleep: (ms: number) => Promise<void>;
+interface AgentMessage {
+    type: "status" | "error" | "done";
+    content: string;
+}
+interface AgentCoreOptions {
+    cwd?: string;
+    signal?: AbortSignal;
+    sessionId?: string;
+}
+declare const formatSpawnError: (error: Error, commandName: string) => string;
+
+export { type AgentCoreOptions, type AgentMessage, formatSpawnError, sleep };

package/dist/server.js

@@ -0,0 +1,32 @@
+// src/server.ts
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var COMMAND_INSTALL_MAP = {
+  "cursor-agent": "Install Cursor (https://cursor.com) and ensure 'cursor-agent' is in your PATH.",
+  gemini: "Install the Gemini CLI: npm install -g @anthropic-ai/gemini-cli\nOr see: https://github.com/google-gemini/gemini-cli",
+  claude: "Install Claude Code: npm install -g @anthropic-ai/claude-code\nOr see: https://github.com/anthropics/claude-code"
+};
+var formatSpawnError = (error, commandName) => {
+  const spawnError = error;
+  const isNotFound = spawnError.code === "ENOENT" || spawnError.message && spawnError.message.includes("ENOENT");
+  if (isNotFound) {
+    const installInfo = COMMAND_INSTALL_MAP[commandName];
+    const baseMessage = `Command '${commandName}' not found.`;
+    if (installInfo) {
+      return `${baseMessage}
+
+${installInfo}`;
+    }
+    return `${baseMessage}
+
+Make sure '${commandName}' is installed and available in your PATH.`;
+  }
+  const isPermissionDenied = spawnError.code === "EACCES" || spawnError.message && spawnError.message.includes("EACCES");
+  if (isPermissionDenied) {
+    return `Permission denied when trying to run '${commandName}'.
+
+Check that the command is executable: chmod +x $(which ${commandName})`;
+  }
+  return error.message;
+};
+
+export { formatSpawnError, sleep };

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@react-grab/utils",
+  "version": "0.1.3",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js",
+      "require": "./dist/client.cjs"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js",
+      "require": "./dist/server.cjs"
+    }
+  },
+  "devDependencies": {
+    "tsup": "^8.4.0"
+  },
+  "scripts": {
+    "dev": "tsup --watch",
+    "build": "rm -rf dist && NODE_ENV=production tsup"
+  }
+}