hyper-agent-browser 0.1.0

package/src/snapshot/reference-store.ts

@@ -0,0 +1,97 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { Session } from "../session/store";
+
+/**
+ * Stores and retrieves element reference mappings for a session
+ * Maps @eN references to actual CSS selectors
+ */
+export class ReferenceStore {
+  private sessionDir: string;
+  private mappingsFile: string;
+  private mappings: Map<string, string> = new Map();
+
+  constructor(session: Session) {
+    this.sessionDir = join(session.userDataDir, "..");
+    this.mappingsFile = join(this.sessionDir, "element-mappings.json");
+  }
+
+  /**
+   * Load mappings from disk
+   */
+  async load(): Promise<void> {
+    if (!existsSync(this.mappingsFile)) {
+      this.mappings.clear();
+      return;
+    }
+
+    try {
+      const content = await readFile(this.mappingsFile, "utf-8");
+      const data = JSON.parse(content);
+      this.mappings = new Map(Object.entries(data));
+    } catch (error) {
+      console.error("Failed to load element mappings:", error);
+      this.mappings.clear();
+    }
+  }
+
+  /**
+   * Save mappings to disk
+   */
+  async save(): Promise<void> {
+    try {
+      // Ensure directory exists
+      if (!existsSync(this.sessionDir)) {
+        await mkdir(this.sessionDir, { recursive: true, mode: 0o700 });
+      }
+
+      const data = Object.fromEntries(this.mappings);
+      await writeFile(this.mappingsFile, JSON.stringify(data, null, 2), "utf-8");
+    } catch (error) {
+      console.error("Failed to save element mappings:", error);
+    }
+  }
+
+  /**
+   * Store a new mapping
+   */
+  set(ref: string, selector: string): void {
+    this.mappings.set(ref, selector);
+  }
+
+  /**
+   * Get selector for a reference
+   */
+  get(ref: string): string | undefined {
+    return this.mappings.get(ref);
+  }
+
+  /**
+   * Update all mappings at once
+   */
+  setAll(mappings: Map<string, string>): void {
+    this.mappings = new Map(mappings);
+  }
+
+  /**
+   * Clear all mappings
+   */
+  clear(): void {
+    this.mappings.clear();
+  }
+
+  /**
+   * Get all mappings
+   */
+  getAll(): Map<string, string> {
+    return new Map(this.mappings);
+  }
+
+  /**
+   * Check if a reference exists
+   */
+  has(ref: string): boolean {
+    return this.mappings.has(ref);
+  }
+}

package/src/utils/config.ts

@@ -0,0 +1,183 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { z } from "zod";
+
+export const ConfigSchema = z.object({
+  version: z.string(),
+  defaults: z.object({
+    session: z.string(),
+    headed: z.boolean(),
+    channel: z.enum(["chrome", "msedge", "chromium"]),
+    timeout: z.number(),
+  }),
+  sessions: z
+    .object({
+      dataDir: z.string(),
+    })
+    .optional(),
+  browser: z
+    .object({
+      args: z.array(z.string()).optional(),
+      ignoreDefaultArgs: z.array(z.string()).optional(),
+    })
+    .optional(),
+  snapshot: z
+    .object({
+      interactiveRoles: z.array(z.string()).optional(),
+    })
+    .optional(),
+});
+
+export type Config = z.infer<typeof ConfigSchema>;
+
+const DEFAULT_CONFIG: Config = {
+  version: "1.0",
+  defaults: {
+    session: "default",
+    headed: false,
+    channel: "chrome",
+    timeout: 30000,
+  },
+  sessions: {
+    dataDir: join(homedir(), ".hab", "sessions"),
+  },
+  browser: {
+    args: ["--disable-blink-features=AutomationControlled"],
+    ignoreDefaultArgs: ["--enable-automation"],
+  },
+  snapshot: {
+    interactiveRoles: [
+      "button",
+      "link",
+      "textbox",
+      "checkbox",
+      "radio",
+      "combobox",
+      "menuitem",
+      "tab",
+    ],
+  },
+};
+
+export function getConfigPath(): string {
+  const envPath = process.env.HAB_CONFIG;
+  if (envPath) {
+    return envPath;
+  }
+  return join(homedir(), ".hab", "config.json");
+}
+
+export async function loadConfig(): Promise<Config> {
+  const configPath = getConfigPath();
+
+  if (!existsSync(configPath)) {
+    return DEFAULT_CONFIG;
+  }
+
+  try {
+    const content = await readFile(configPath, "utf-8");
+    const data = JSON.parse(content);
+    const validated = ConfigSchema.parse(data);
+    return validated;
+  } catch (error) {
+    console.error(`Warning: Failed to load config from ${configPath}:`, error);
+    return DEFAULT_CONFIG;
+  }
+}
+
+export async function saveConfig(config: Config): Promise<void> {
+  const configPath = getConfigPath();
+  const configDir = join(configPath, "..");
+
+  // Ensure directory exists
+  if (!existsSync(configDir)) {
+    await mkdir(configDir, { recursive: true, mode: 0o700 });
+  }
+
+  await writeFile(configPath, JSON.stringify(config, null, 2), "utf-8");
+
+  // Security: Set file permissions to 0o600 (owner read/write only)
+  // Protects sensitive configuration from other users
+  const { chmod } = await import("node:fs/promises");
+  await chmod(configPath, 0o600);
+}
+
+export async function getConfigValue(key: string): Promise<unknown> {
+  const config = await loadConfig();
+  const keys = key.split(".");
+
+  let value: any = config;
+  for (const k of keys) {
+    if (value && typeof value === "object" && k in value) {
+      value = value[k];
+    } else {
+      return undefined;
+    }
+  }
+
+  return value;
+}
+
+// Whitelist of config keys that can be modified via CLI
+const ALLOWED_CONFIG_KEYS = [
+  "defaults.session",
+  "defaults.headed",
+  "defaults.channel",
+  "defaults.timeout",
+];
+
+// Dangerous browser arguments that should be blocked
+const DANGEROUS_BROWSER_ARGS = [
+  "remote-debugging-port",
+  "disable-web-security",
+  "disable-site-isolation",
+  "disable-features=IsolateOrigins",
+  "disable-setuid-sandbox",
+];
+
+export async function setConfigValue(key: string, value: unknown): Promise<void> {
+  // Security: Whitelist check - only allow safe config keys
+  if (!ALLOWED_CONFIG_KEYS.includes(key)) {
+    throw new Error(
+      `Config key '${key}' cannot be modified via CLI. ` +
+        `Allowed keys: ${ALLOWED_CONFIG_KEYS.join(", ")}`,
+    );
+  }
+
+  // Security: Validate browser.args if being set
+  if (key === "browser.args" && Array.isArray(value)) {
+    for (const arg of value as string[]) {
+      for (const dangerous of DANGEROUS_BROWSER_ARGS) {
+        if (arg.toLowerCase().includes(dangerous)) {
+          throw new Error(`Dangerous browser argument blocked: ${arg}`);
+        }
+      }
+    }
+  }
+
+  const config = await loadConfig();
+  const keys = key.split(".");
+
+  if (keys.length === 0) {
+    throw new Error("Invalid config key");
+  }
+
+  let obj: any = config;
+  for (let i = 0; i < keys.length - 1; i++) {
+    const k = keys[i];
+    if (!(k in obj) || typeof obj[k] !== "object") {
+      obj[k] = {};
+    }
+    obj = obj[k];
+  }
+
+  const lastKey = keys[keys.length - 1];
+  obj[lastKey] = value;
+
+  // Validate updated config
+  ConfigSchema.parse(config);
+
+  await saveConfig(config);
+}

package/src/utils/errors.ts

@@ -0,0 +1,121 @@
+export class HBAError extends Error {
+  code: string;
+  hint?: string;
+
+  constructor(message: string, code: string, hint?: string) {
+    super(message);
+    this.name = this.constructor.name;
+    this.code = code;
+    this.hint = hint;
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+
+export class SessionNotFoundError extends HBAError {
+  constructor(sessionName: string) {
+    super(
+      `Session '${sessionName}' not found`,
+      "SESSION_NOT_FOUND",
+      "Run 'hab sessions' to see available sessions",
+    );
+  }
+}
+
+export class ElementNotFoundError extends HBAError {
+  constructor(selector: string) {
+    super(
+      `Element not found: ${selector}`,
+      "ELEMENT_NOT_FOUND",
+      "Run 'hab snapshot -i' to see available elements",
+    );
+  }
+}
+
+export class BrowserNotRunningError extends HBAError {
+  constructor() {
+    super("Browser not running", "BROWSER_NOT_RUNNING", "Run 'hab open <url>' first");
+  }
+}
+
+export class TimeoutError extends HBAError {
+  constructor(operation: string, timeout: number) {
+    super(
+      `Operation timed out: ${operation} (${timeout}ms)`,
+      "TIMEOUT",
+      "Increase timeout with --timeout option",
+    );
+  }
+}
+
+export class NavigationError extends HBAError {
+  constructor(url: string, reason?: string) {
+    super(
+      `Navigation failed: ${url}${reason ? ` (${reason})` : ""}`,
+      "NAVIGATION_FAILED",
+      "Check if the URL is accessible and valid",
+    );
+  }
+}
+
+export class SelectorError extends HBAError {
+  constructor(selector: string) {
+    super(
+      `Invalid selector: ${selector}`,
+      "INVALID_SELECTOR",
+      "Use @eN, css=..., text=..., or xpath=...",
+    );
+  }
+}
+
+export class ConfigError extends HBAError {
+  constructor(message: string) {
+    super(message, "CONFIG_ERROR", "Check ~/.hab/config.json for syntax errors");
+  }
+}
+
+export class PermissionError extends HBAError {
+  constructor(path: string) {
+    super(`Permission denied: ${path}`, "PERMISSION_ERROR", "Check file/directory permissions");
+  }
+}
+
+/**
+ * Format error for CLI output
+ */
+export function formatError(error: Error): string {
+  let output = `Error: ${error.message}`;
+
+  if (error instanceof HBAError) {
+    if (error.hint) {
+      output += `\n  Hint: ${error.hint}`;
+    }
+    output += `\n  Code: ${error.code}`;
+  }
+
+  return output;
+}
+
+/**
+ * Get exit code for error type
+ */
+export function getExitCode(error: Error): number {
+  if (error instanceof HBAError) {
+    switch (error.code) {
+      case "INVALID_SELECTOR":
+        return 2; // Argument error
+      case "SESSION_NOT_FOUND":
+      case "CONFIG_ERROR":
+        return 3; // Session error
+      case "BROWSER_NOT_RUNNING":
+      case "NAVIGATION_FAILED":
+        return 4; // Browser error
+      case "ELEMENT_NOT_FOUND":
+        return 5; // Element error
+      case "TIMEOUT":
+        return 6; // Timeout
+      default:
+        return 1; // General error
+    }
+  }
+  return 1; // General error
+}

package/src/utils/logger.ts

@@ -0,0 +1,12 @@
+export function log(message: string, verbose = false) {
+  if (verbose) {
+    console.log(`[HBA] ${message}`);
+  }
+}
+
+export function error(message: string, hint?: string) {
+  console.error(`Error: ${message}`);
+  if (hint) {
+    console.error(`  Hint: ${hint}`);
+  }
+}

package/src/utils/selector.ts

@@ -0,0 +1,23 @@
+export type SelectorType = "ref" | "css" | "text" | "xpath";
+
+export interface ParsedSelector {
+  type: SelectorType;
+  value: string;
+}
+
+export function parseSelector(selector: string): ParsedSelector {
+  if (selector.startsWith("@e")) {
+    return { type: "ref", value: selector.slice(1) };
+  }
+  if (selector.startsWith("css=")) {
+    return { type: "css", value: selector.slice(4) };
+  }
+  if (selector.startsWith("text=")) {
+    return { type: "text", value: selector.slice(5) };
+  }
+  if (selector.startsWith("xpath=")) {
+    return { type: "xpath", value: selector.slice(6) };
+  }
+  // Default to CSS
+  return { type: "css", value: selector };
+}