@relauts/spotcheck-service 1.0.0

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@relauts/spotcheck-service",
+  "version": "1.0.0",
+  "description": "Local HTTP API that runs a Gemini computer-use agent in a Playwright Chromium session",
+  "license": "AGPL-3.0-or-later",
+  "author": "Relauts Pvt. Ltd.",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://github.com/relauts/spotcheck-service#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/relauts/spotcheck-service.git"
+  },
+  "bugs": {
+    "url": "https://github.com/relauts/spotcheck-service/issues"
+  },
+  "keywords": [
+    "ai",
+    "browser-automation",
+    "computer-use",
+    "playwright",
+    "api"
+  ],
+  "files": [
+    "relauts-spotcheck-service-config.example.json",
+    "dist",
+    "src",
+    "files",
+    "openapi.yaml",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "bin": {
+    "spotcheck-service": "dist/api/server.js"
+  },
+  "engines": {
+    "node": ">=18.18.0"
+  },
+  "main": "dist/api/server.js",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build",
+    "start": "npm run build && node dist/api/server.js",
+    "dev": "tsx src/api/server.ts",
+    "agent": "tsx src/computer-use/index.ts",
+    "test": "tsx --test tests/shared/*.test.ts tests/playwright/*.test.ts tests/api/*.test.ts tests/computer-use/*.test.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@google/genai": "^2.17.1",
+    "playwright": "^1.55.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "tsx": "^4.20.4",
+    "typescript": "^5.9.2"
+  }
+}

package/relauts-spotcheck-service-config.example.json

@@ -0,0 +1,19 @@
+{
+  "apiToken": "replace-me",
+  "geminiApiKey": "replace-me",
+  "targetUrl": "https://example.com",
+  "port": 18732,
+  "headless": true,
+  "chromiumSandbox": true,
+  "navigationTimeoutMs": 30000,
+  "viewportWidth": 1024,
+  "viewportHeight": 768,
+  "geminiModel": "gemini-3.6-flash",
+  "geminiThinkingLevel": "minimal",
+  "agentMaxTurns": 15,
+  "corsOrigins": [],
+  "savedDir": "saved",
+  "processedDir": "processed",
+  "historyDir": "history",
+  "maxSavedRuns": 2
+}

package/src/api/auth.ts

@@ -0,0 +1,40 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+
+/**
+ * Extracts the raw token from an Authorization header.
+ * Only the Bearer scheme is accepted.
+ */
+export function extractBearerToken(authorizationHeader: string | undefined): string | undefined {
+  if (!authorizationHeader) {
+    return undefined;
+  }
+
+  const match = /^Bearer\s+(\S+)\s*$/i.exec(authorizationHeader);
+  if (!match) {
+    return undefined;
+  }
+
+  return match[1];
+}
+
+/**
+ * Compares tokens in constant time by hashing both to fixed-length digests first.
+ * Avoids leaking token length via early return on Buffer length mismatch.
+ */
+export function tokensEqual(expected: string, provided: string): boolean {
+  const expectedDigest = createHash("sha256").update(expected, "utf8").digest();
+  const providedDigest = createHash("sha256").update(provided, "utf8").digest();
+  return timingSafeEqual(expectedDigest, providedDigest);
+}
+
+export function isAuthorized(
+  authorizationHeader: string | undefined,
+  expectedToken: string,
+): boolean {
+  const provided = extractBearerToken(authorizationHeader);
+  if (provided === undefined) {
+    return false;
+  }
+
+  return tokensEqual(expectedToken, provided);
+}

package/src/api/history.ts

@@ -0,0 +1,251 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { SavedNameError, SavedNotFoundError, normalizeSavedFileName, type SavedPromptItem } from "./saved.js";
+
+export const HISTORY_DIR = path.resolve(process.cwd(), "history");
+
+export const HISTORY_RUN_STATUSES = ["running", "done", "error", "stopped"] as const;
+export type HistoryRunStatus = (typeof HISTORY_RUN_STATUSES)[number];
+export type HistoryItemStatus = "pending" | "running" | "done" | "error" | "skipped";
+
+export interface HistoryRunSummary {
+  readonly historyFile: string;
+  readonly status: HistoryRunStatus;
+}
+
+export interface HistoryDetailItem {
+  readonly sequence: number;
+  readonly prompt: string;
+  readonly model: string;
+  readonly resultText?: string;
+  readonly screenshots: readonly string[];
+}
+
+function isHistoryRunStatus(value: unknown): value is HistoryRunStatus {
+  return typeof value === "string" && (HISTORY_RUN_STATUSES as readonly string[]).includes(value);
+}
+
+export interface HistoryItem {
+  readonly sequence: number;
+  readonly id: string;
+  readonly prompt: string;
+  readonly model: string;
+  readonly status: HistoryItemStatus;
+  readonly resultText?: string;
+  readonly costUsd?: number;
+  readonly error?: string;
+}
+
+export interface HistoryDocument {
+  readonly fileName: string;
+  readonly status: HistoryRunStatus;
+  readonly current: number;
+  readonly total: number;
+  readonly items: readonly HistoryItem[];
+}
+
+export function makeHistoryFileName(savedFileName: string, now = new Date()): string {
+  const name = normalizeSavedFileName(savedFileName);
+  const stem = name.slice(0, -".json".length);
+  const stamp = now.toISOString().replace(/[:.]/g, "-");
+  return `${stem}-${stamp}.json`;
+}
+
+export function createHistoryDocument(
+  savedFileName: string,
+  items: readonly SavedPromptItem[],
+): HistoryDocument {
+  return {
+    fileName: normalizeSavedFileName(savedFileName),
+    status: "running",
+    current: 0,
+    total: items.length,
+    items: items.map((item) => ({
+      sequence: item.sequence,
+      id: item.id,
+      prompt: item.prompt,
+      model: item.model,
+      status: "pending",
+    })),
+  };
+}
+
+export function serializeHistoryDetailItem(
+  item: HistoryItem,
+  screenshots: readonly string[],
+): HistoryDetailItem {
+  return {
+    sequence: item.sequence,
+    prompt: item.prompt,
+    model: item.model,
+    ...(item.resultText ? { resultText: item.resultText } : {}),
+    screenshots: [...screenshots],
+  };
+}
+
+export function serializeHistoryItem(item: HistoryItem): HistoryItem {
+  return {
+    sequence: item.sequence,
+    id: item.id,
+    prompt: item.prompt,
+    model: item.model,
+    status: item.status,
+    ...(item.resultText ? { resultText: item.resultText } : {}),
+    ...(typeof item.costUsd === "number" ? { costUsd: item.costUsd } : {}),
+    ...(item.error ? { error: item.error } : {}),
+  };
+}
+
+export function serializeHistoryDocument(document: HistoryDocument): HistoryDocument {
+  return {
+    fileName: document.fileName,
+    status: document.status,
+    current: document.current,
+    total: document.total,
+    items: document.items.map(serializeHistoryItem),
+  };
+}
+
+export async function writeHistoryFile(
+  historyFileName: string,
+  document: HistoryDocument,
+  directory = HISTORY_DIR,
+): Promise<string> {
+  const name = normalizeSavedFileName(historyFileName);
+  await fs.mkdir(directory, { recursive: true });
+  const body = `${JSON.stringify(serializeHistoryDocument(document), null, 2)}\n`;
+  const filePath = path.join(directory, name);
+  const tempPath = `${filePath}.${process.pid}.tmp`;
+  await fs.writeFile(tempPath, body);
+  await fs.rename(tempPath, filePath);
+  return name;
+}
+
+export async function readHistoryFile(
+  historyFileName: string,
+  directory = HISTORY_DIR,
+): Promise<HistoryDocument> {
+  const name = normalizeSavedFileName(historyFileName);
+  const filePath = path.join(directory, name);
+  let raw: string;
+  try {
+    raw = await fs.readFile(filePath, "utf8");
+  } catch (error: unknown) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      throw new SavedNotFoundError(`History file not found: ${name}`);
+    }
+
+    throw error;
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new SavedNameError("History file is not valid JSON");
+  }
+
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new SavedNameError("History file must be a JSON object");
+  }
+
+  return parsed as HistoryDocument;
+}
+
+export interface LatestHistoryMatch {
+  readonly historyFile: string;
+  readonly document: HistoryDocument;
+}
+
+export async function listHistoryRuns(directory = HISTORY_DIR): Promise<HistoryRunSummary[]> {
+  let names: string[];
+  try {
+    names = await fs.readdir(directory);
+  } catch (error: unknown) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return [];
+    }
+
+    throw error;
+  }
+
+  const ranked: Array<{ historyFile: string; status: HistoryRunStatus; mtimeMs: number }> = [];
+  for (const name of names) {
+    if (!name.toLowerCase().endsWith(".json")) {
+      continue;
+    }
+
+    try {
+      const document = await readHistoryFile(name, directory);
+      if (!isHistoryRunStatus(document.status)) {
+        continue;
+      }
+
+      const stats = await fs.stat(path.join(directory, name));
+      ranked.push({ historyFile: name, status: document.status, mtimeMs: stats.mtimeMs });
+    } catch {
+      // Skip unreadable or invalid files.
+    }
+  }
+
+  ranked.sort((left, right) => {
+    if (right.mtimeMs !== left.mtimeMs) {
+      return right.mtimeMs - left.mtimeMs;
+    }
+
+    return right.historyFile.localeCompare(left.historyFile);
+  });
+
+  return ranked.map(({ historyFile, status }) => ({ historyFile, status }));
+}
+
+export async function findLatestHistory(
+  savedFileName: string,
+  directory = HISTORY_DIR,
+): Promise<LatestHistoryMatch> {
+  const wanted = normalizeSavedFileName(savedFileName);
+  let names: string[];
+  try {
+    names = await fs.readdir(directory);
+  } catch (error: unknown) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      throw new SavedNotFoundError(`History file not found for: ${wanted}`);
+    }
+
+    throw error;
+  }
+
+  const ranked: Array<{ historyFile: string; document: HistoryDocument; mtimeMs: number }> = [];
+  for (const name of names) {
+    if (!name.toLowerCase().endsWith(".json")) {
+      continue;
+    }
+
+    try {
+      const document = await readHistoryFile(name, directory);
+      if (normalizeSavedFileName(document.fileName) !== wanted) {
+        continue;
+      }
+
+      const stats = await fs.stat(path.join(directory, name));
+      ranked.push({ historyFile: name, document, mtimeMs: stats.mtimeMs });
+    } catch {
+      // Skip unreadable or invalid files.
+    }
+  }
+
+  ranked.sort((left, right) => {
+    if (right.mtimeMs !== left.mtimeMs) {
+      return right.mtimeMs - left.mtimeMs;
+    }
+
+    return right.historyFile.localeCompare(left.historyFile);
+  });
+
+  const latest = ranked[0];
+  if (!latest) {
+    throw new SavedNotFoundError(`History file not found for: ${wanted}`);
+  }
+
+  return { historyFile: latest.historyFile, document: latest.document };
+}