@browserflow-ai/core 0.0.6

package/src/config.ts

@@ -0,0 +1,112 @@
+/**
+ * Configuration types for BrowserFlow
+ */
+
+/**
+ * Generator output format options
+ */
+export type GeneratorOutputFormat = 'playwright-ts' | 'playwright-js' | 'bash';
+
+/**
+ * Browser types supported by Playwright
+ */
+export type BrowserType = 'chromium' | 'firefox' | 'webkit';
+
+/**
+ * Playwright project configuration
+ */
+export interface PlaywrightProject {
+  name: string;
+  use: {
+    browserName?: BrowserType;
+    viewport?: { width: number; height: number };
+    headless?: boolean;
+    [key: string]: unknown;
+  };
+}
+
+/**
+ * Playwright configuration options for generated tests
+ */
+export interface PlaywrightConfigOptions {
+  /** Test timeout in ms */
+  timeout?: number;
+  /** Number of retries */
+  retries?: number;
+  /** Number of workers */
+  workers?: number;
+  /** Reporter to use */
+  reporter?: 'html' | 'list' | 'dot' | 'json';
+  /** Projects configuration */
+  projects?: PlaywrightProject[];
+  /** Web server configuration */
+  webServer?: {
+    command: string;
+    url: string;
+    reuseExistingServer?: boolean;
+  };
+}
+
+/**
+ * Generator configuration
+ */
+export interface GeneratorConfig {
+  /** Output format for generated tests */
+  outputFormat: GeneratorOutputFormat;
+  /** Include baseline screenshot comparisons */
+  includeBaselineChecks: boolean;
+  /** Directory for baseline screenshots */
+  baselinesDir?: string;
+  /** Playwright config options */
+  playwrightConfig?: PlaywrightConfigOptions;
+}
+
+/**
+ * Review step data
+ */
+export interface ReviewStepData {
+  step_index: number;
+  status: 'approved' | 'rejected' | 'pending';
+  comment?: string;
+  tags?: string[];
+}
+
+/**
+ * Review data for an exploration
+ */
+export interface ReviewData {
+  exploration_id: string;
+  reviewer?: string;
+  started_at: string;
+  updated_at: string;
+  steps: ReviewStepData[];
+  overall_notes?: string;
+  verdict: 'approved' | 'rejected' | 'pending';
+  submitted_at?: string;
+}
+
+/**
+ * Generated test output
+ */
+export interface GeneratedTest {
+  /** Test file path (relative) */
+  path: string;
+  /** Test file content */
+  content: string;
+  /** Spec name this was generated from */
+  specName: string;
+  /** Exploration ID used */
+  explorationId: string;
+  /** Generation timestamp */
+  generatedAt: string;
+}
+
+/**
+ * Generated config output
+ */
+export interface GeneratedConfig {
+  /** Config file path */
+  path: string;
+  /** Config file content */
+  content: string;
+}

package/src/duration.test.ts

@@ -0,0 +1,175 @@
+/**
+ * Tests for duration string parser
+ * @see bf-x1q
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { parseDuration, formatDuration, isValidDuration } from './duration.js';
+
+describe('parseDuration', () => {
+  describe('basic units', () => {
+    test('parses milliseconds', () => {
+      expect(parseDuration('500ms')).toBe(500);
+      expect(parseDuration('0ms')).toBe(0);
+      expect(parseDuration('1ms')).toBe(1);
+    });
+
+    test('parses seconds', () => {
+      expect(parseDuration('3s')).toBe(3000);
+      expect(parseDuration('1s')).toBe(1000);
+      expect(parseDuration('30s')).toBe(30000);
+    });
+
+    test('parses minutes', () => {
+      expect(parseDuration('2m')).toBe(120000);
+      expect(parseDuration('1m')).toBe(60000);
+      expect(parseDuration('5m')).toBe(300000);
+    });
+
+    test('parses hours', () => {
+      expect(parseDuration('1h')).toBe(3600000);
+      expect(parseDuration('2h')).toBe(7200000);
+    });
+  });
+
+  describe('combined units', () => {
+    test('parses minute and seconds', () => {
+      expect(parseDuration('1m30s')).toBe(90000);
+      expect(parseDuration('2m15s')).toBe(135000);
+    });
+
+    test('parses hours and minutes', () => {
+      expect(parseDuration('1h30m')).toBe(5400000);
+      expect(parseDuration('2h45m')).toBe(9900000);
+    });
+
+    test('parses complex combinations', () => {
+      expect(parseDuration('1h30m45s')).toBe(5445000);
+      expect(parseDuration('1m30s500ms')).toBe(90500);
+    });
+  });
+
+  describe('numeric input', () => {
+    test('treats numeric input as milliseconds', () => {
+      expect(parseDuration(500)).toBe(500);
+      expect(parseDuration(3000)).toBe(3000);
+      expect(parseDuration(0)).toBe(0);
+    });
+
+    test('parses plain number strings as milliseconds', () => {
+      expect(parseDuration('500')).toBe(500);
+      expect(parseDuration('3000')).toBe(3000);
+    });
+  });
+
+  describe('whitespace handling', () => {
+    test('trims whitespace', () => {
+      expect(parseDuration('  3s  ')).toBe(3000);
+      expect(parseDuration('\t2m\n')).toBe(120000);
+    });
+
+    test('handles lowercase conversion', () => {
+      expect(parseDuration('3S')).toBe(3000);
+      expect(parseDuration('2M')).toBe(120000);
+      expect(parseDuration('1H')).toBe(3600000);
+    });
+  });
+
+  describe('error handling', () => {
+    test('throws for empty string', () => {
+      expect(() => parseDuration('')).toThrow('Duration must be a non-empty string');
+    });
+
+    test('throws for whitespace-only string', () => {
+      expect(() => parseDuration('   ')).toThrow('Duration must be a non-empty string');
+    });
+
+    test('throws for invalid format', () => {
+      expect(() => parseDuration('3 seconds')).toThrow(/Invalid duration/);
+      expect(() => parseDuration('abc')).toThrow(/Invalid duration/);
+      expect(() => parseDuration('3x')).toThrow(/Invalid duration/);
+    });
+
+    test('provides helpful error message', () => {
+      try {
+        parseDuration('invalid');
+      } catch (e) {
+        expect((e as Error).message).toContain('3s');
+        expect((e as Error).message).toContain('2m');
+        expect((e as Error).message).toContain('500ms');
+        expect((e as Error).message).toContain('1m30s');
+      }
+    });
+  });
+
+  describe('edge cases', () => {
+    test('handles fractional values', () => {
+      expect(parseDuration('1.5s')).toBe(1500);
+      expect(parseDuration('0.5m')).toBe(30000);
+    });
+
+    test('handles zero values', () => {
+      expect(parseDuration('0s')).toBe(0);
+      expect(parseDuration('0m')).toBe(0);
+    });
+  });
+});
+
+describe('formatDuration', () => {
+  test('formats milliseconds', () => {
+    expect(formatDuration(500)).toBe('500ms');
+    expect(formatDuration(0)).toBe('0ms');
+    expect(formatDuration(999)).toBe('999ms');
+  });
+
+  test('formats seconds', () => {
+    expect(formatDuration(1000)).toBe('1s');
+    expect(formatDuration(3000)).toBe('3s');
+    expect(formatDuration(30000)).toBe('30s');
+  });
+
+  test('formats minutes', () => {
+    expect(formatDuration(60000)).toBe('1m');
+    expect(formatDuration(120000)).toBe('2m');
+  });
+
+  test('formats hours', () => {
+    expect(formatDuration(3600000)).toBe('1h');
+    expect(formatDuration(7200000)).toBe('2h');
+  });
+
+  test('formats combinations', () => {
+    expect(formatDuration(90000)).toBe('1m30s');
+    expect(formatDuration(5400000)).toBe('1h30m');
+    expect(formatDuration(5445000)).toBe('1h30m45s');
+  });
+
+  test('formats sub-second remainders to seconds', () => {
+    // formatDuration uses floor, so sub-second parts are dropped
+    expect(formatDuration(1500)).toBe('1s');
+    expect(formatDuration(90500)).toBe('1m30s');
+  });
+});
+
+describe('isValidDuration', () => {
+  test('returns true for valid durations', () => {
+    expect(isValidDuration('3s')).toBe(true);
+    expect(isValidDuration('2m')).toBe(true);
+    expect(isValidDuration('1h')).toBe(true);
+    expect(isValidDuration('500ms')).toBe(true);
+    expect(isValidDuration('1m30s')).toBe(true);
+    expect(isValidDuration('1h30m')).toBe(true);
+  });
+
+  test('returns false for invalid durations', () => {
+    expect(isValidDuration('')).toBe(false);
+    expect(isValidDuration('abc')).toBe(false);
+    expect(isValidDuration('3 seconds')).toBe(false);
+    expect(isValidDuration('3x')).toBe(false);
+  });
+
+  test('returns true for plain number strings', () => {
+    expect(isValidDuration('500')).toBe(true);
+    expect(isValidDuration('3000')).toBe(true);
+  });
+});

package/src/duration.ts

@@ -0,0 +1,128 @@
+/**
+ * Duration string parser
+ *
+ * Parses human-readable duration strings like "30s", "5m", "1h30m"
+ * into milliseconds.
+ *
+ * @see bf-x1q for implementation task
+ */
+
+const UNITS: Record<string, number> = {
+  ms: 1,
+  s: 1000,
+  m: 60 * 1000,
+  h: 60 * 60 * 1000,
+};
+
+/**
+ * Validates a duration string without parsing it.
+ *
+ * @param input - Duration string to validate
+ * @returns true if valid, false otherwise
+ */
+export function isValidDuration(input: string): boolean {
+  if (typeof input !== 'string') {
+    return false;
+  }
+
+  const trimmed = input.trim().toLowerCase();
+  if (!trimmed) {
+    return false;
+  }
+
+  // Plain number (milliseconds)
+  if (/^\d+$/.test(trimmed)) {
+    return true;
+  }
+
+  // Duration with units
+  const regex = /(\d+(?:\.\d+)?)(ms|s|m|h)/g;
+  let hasMatch = false;
+
+  // Check if entire string matches expected pattern
+  let lastIndex = 0;
+  let match;
+  while ((match = regex.exec(trimmed)) !== null) {
+    if (match.index !== lastIndex) {
+      return false; // Gap in matching
+    }
+    hasMatch = true;
+    lastIndex = regex.lastIndex;
+  }
+
+  return hasMatch && lastIndex === trimmed.length;
+}
+
+/**
+ * Parses a duration string into milliseconds.
+ *
+ * Supported formats:
+ * - "30s" -> 30000
+ * - "5m" -> 300000
+ * - "1h" -> 3600000
+ * - "1h30m" -> 5400000
+ * - "500ms" -> 500
+ * - "500" -> 500 (plain numbers treated as ms)
+ *
+ * @param input - Duration string to parse
+ * @returns Duration in milliseconds
+ * @throws Error if format is invalid
+ */
+export function parseDuration(input: string | number): number {
+  if (typeof input === 'number') {
+    return input;
+  }
+
+  if (typeof input !== 'string' || !input.trim()) {
+    throw new Error('Duration must be a non-empty string');
+  }
+
+  const trimmed = input.trim().toLowerCase();
+
+  // Plain number (milliseconds)
+  if (/^\d+$/.test(trimmed)) {
+    return parseInt(trimmed, 10);
+  }
+
+  let total = 0;
+  const regex = /(\d+(?:\.\d+)?)(ms|s|m|h)/g;
+  let match;
+  let hasMatch = false;
+
+  while ((match = regex.exec(trimmed)) !== null) {
+    hasMatch = true;
+    const [, value, unit] = match;
+    total += parseFloat(value) * UNITS[unit];
+  }
+
+  if (!hasMatch) {
+    throw new Error(
+      `Invalid duration "${input}". Use format like "3s", "2m", "500ms", or "1m30s"`
+    );
+  }
+
+  return Math.round(total);
+}
+
+/**
+ * Formats milliseconds into a human-readable duration string.
+ *
+ * @param ms - Duration in milliseconds
+ * @returns Human-readable duration string
+ */
+export function formatDuration(ms: number): string {
+  if (ms < 1000) {
+    return `${ms}ms`;
+  }
+
+  const hours = Math.floor(ms / 3600000);
+  const minutes = Math.floor((ms % 3600000) / 60000);
+  const seconds = Math.floor((ms % 60000) / 1000);
+
+  const parts: string[] = [];
+  if (hours > 0) parts.push(`${hours}h`);
+  if (minutes > 0) parts.push(`${minutes}m`);
+  if (seconds > 0) parts.push(`${seconds}s`);
+
+  return parts.join('') || '0s';
+}

package/src/index.ts

@@ -0,0 +1,136 @@
+/**
+ * @browserflow-ai/core - Shared types, schemas, and utilities
+ */
+
+// Spec schema and types
+export {
+  specSchema,
+  specStepSchema,
+  stepSchema,
+  actionTypeSchema,
+  verifyCheckSchema,
+  expectedOutcomeSchema,
+  highlightRegionSchema,
+  maskRegionSchema,
+  durationSchema,
+  targetSchema,
+  preconditionsSchema,
+  stateSchema,
+  type ActionType,
+  type VerifyCheck,
+  type HighlightRegion,
+  type MaskRegion,
+  type SpecStep,
+  type LegacySpecStep,
+  type ExpectedOutcome,
+  type BrowserFlowSpec,
+  type Target,
+  type State,
+  type Preconditions,
+} from './spec-schema.js';
+
+// Spec loading and normalization
+export { normalizePreconditions, loadSpec } from './spec-loader.js';
+
+// Locator types and resolution
+export {
+  type LocatorObject,
+  type LocatorStrategy,
+  type LocatorStrategyType,
+  type LocatorScoping,
+  type LocatorProof,
+  type DOMFingerprint,
+  type BoundingBox,
+  type ResolveOptions,
+  type LocatorMethod,
+  type LocatorArgs,
+  type LegacyLocatorObject,
+  locatorObjectSchema,
+  locatorStrategySchema,
+  locatorStrategyTypeSchema,
+  locatorScopingSchema,
+  locatorProofSchema,
+  domFingerprintSchema,
+  boundingBoxSchema,
+  resolveLocator,
+  strategyToLocator,
+  resolveLegacyLocator,
+} from './locator-object.js';
+
+// Lockfile types
+export {
+  type Lockfile,
+  type Mask,
+  type Assertion,
+  type AssertionType,
+  type GenerationMetadata,
+  type ExplorationReport,
+  type ExplorationLockfile,
+  type ExplorationStep,
+  type StepExecution,
+  type OutcomeCheck,
+  type ExplorationError,
+  lockfileSchema,
+  maskSchema,
+  assertionSchema,
+  assertionTypeSchema,
+  generationMetadataSchema,
+  validateLockfile,
+  computeSpecHash,
+  readLockfile,
+  writeLockfile,
+} from './lockfile.js';
+
+// Duration utilities
+export { parseDuration, formatDuration, isValidDuration } from './duration.js';
+
+// Run store utilities
+export {
+  type RunDirectoryPaths,
+  type RunStore,
+  createRunStore,
+  createRunId,
+  getRunPaths,
+  generateExplorationId,
+  getScreenshotPath,
+} from './run-store.js';
+
+// Configuration types
+export {
+  type GeneratorOutputFormat,
+  type BrowserType,
+  type PlaywrightProject,
+  type PlaywrightConfigOptions,
+  type GeneratorConfig,
+  type ReviewStepData,
+  type ReviewData,
+  type GeneratedTest,
+  type GeneratedConfig,
+} from './config.js';
+
+// Browserflow config schema (for browserflow.yaml validation)
+export {
+  browserflowConfigSchema,
+  browserTypeSchema,
+  viewportSchema,
+  projectConfigSchema,
+  runtimeConfigSchema,
+  locatorsConfigSchema,
+  explorationConfigSchema,
+  reviewConfigSchema,
+  outputConfigSchema,
+  ciConfigSchema,
+  validateBrowserflowConfig,
+  parseBrowserflowConfig,
+  type BrowserTypeConfig,
+  type ViewportConfig,
+  type ProjectConfig,
+  type RuntimeConfig,
+  type LocatorsConfig,
+  type ExplorationConfig,
+  type ReviewConfig,
+  type OutputConfig,
+  type CiConfig,
+  type BrowserflowConfig,
+} from './config-schema.js';
+