@browserflow-ai/core 0.0.6

package/src/lockfile.ts

@@ -0,0 +1,209 @@
+/**
+ * Lockfile types for exploration results
+ *
+ * @see bf-aak for implementation task
+ */
+
+import { z } from 'zod';
+import { join } from 'path';
+import { createHash } from 'crypto';
+import { readFile, writeFile } from 'fs/promises';
+import { locatorObjectSchema, type LocatorObject, type LegacyLocatorObject } from './locator-object.js';
+import type { SpecStep, LegacySpecStep } from './spec-schema.js';
+
+// Assertion types
+export type AssertionType =
+  | 'visible'
+  | 'hidden'
+  | 'text_contains'
+  | 'text_equals'
+  | 'url_contains'
+  | 'url_matches'
+  | 'count'
+  | 'attribute'
+  | 'checked'
+  | 'screenshot';
+
+export const assertionTypeSchema = z.enum([
+  'visible',
+  'hidden',
+  'text_contains',
+  'text_equals',
+  'url_contains',
+  'url_matches',
+  'count',
+  'attribute',
+  'checked',
+  'screenshot',
+]);
+
+// Mask interface
+export interface Mask {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  reason: string;
+  locator?: string;
+}
+
+export const maskSchema = z.object({
+  x: z.number(),
+  y: z.number(),
+  width: z.number(),
+  height: z.number(),
+  reason: z.string(),
+  locator: z.string().optional(),
+});
+
+// Assertion interface
+export interface Assertion {
+  id: string;
+  type: AssertionType;
+  target?: LocatorObject;
+  expected?: string | number | boolean;
+  step_id?: string;
+}
+
+export const assertionSchema = z.object({
+  id: z.string(),
+  type: assertionTypeSchema,
+  target: locatorObjectSchema.optional(),
+  expected: z.union([z.string(), z.number(), z.boolean()]).optional(),
+  step_id: z.string().optional(),
+});
+
+// Generation metadata
+export interface GenerationMetadata {
+  format: 'playwright-ts';
+  output_path: string;
+  generated_at?: string;
+}
+
+export const generationMetadataSchema = z.object({
+  format: z.literal('playwright-ts'),
+  output_path: z.string(),
+  generated_at: z.string().optional(),
+});
+
+// Main Lockfile interface
+export interface Lockfile {
+  run_id: string;
+  spec_name: string;
+  spec_hash: string;
+  created_at: string;
+  locators: Record<string, LocatorObject>;
+  masks: Record<string, Mask[]>;
+  assertions: Assertion[];
+  generation: GenerationMetadata;
+}
+
+export const lockfileSchema = z.object({
+  run_id: z.string(),
+  spec_name: z.string(),
+  spec_hash: z.string(),
+  created_at: z.string(),
+  locators: z.record(locatorObjectSchema),
+  masks: z.record(z.array(maskSchema)),
+  assertions: z.array(assertionSchema),
+  generation: generationMetadataSchema,
+});
+
+/**
+ * Validates if an object is a valid Lockfile
+ */
+export function validateLockfile(lockfile: unknown): lockfile is Lockfile {
+  return lockfileSchema.safeParse(lockfile).success;
+}
+
+/**
+ * Computes SHA256 hash of spec file content
+ */
+export function computeSpecHash(content: string): string {
+  return createHash('sha256').update(content).digest('hex');
+}
+
+/**
+ * Reads a lockfile from a run directory
+ */
+export async function readLockfile(runDir: string): Promise<Lockfile> {
+  const lockfilePath = join(runDir, 'lockfile.json');
+  const content = await readFile(lockfilePath, 'utf-8');
+  const parsed = JSON.parse(content);
+
+  const result = lockfileSchema.safeParse(parsed);
+  if (!result.success) {
+    throw new Error(`Invalid lockfile: ${result.error.message}`);
+  }
+
+  return result.data;
+}
+
+/**
+ * Writes a lockfile to a run directory
+ */
+export async function writeLockfile(runDir: string, lockfile: Lockfile): Promise<void> {
+  const lockfilePath = join(runDir, 'lockfile.json');
+  const content = JSON.stringify(lockfile, null, 2);
+  await writeFile(lockfilePath, content, 'utf-8');
+}
+
+// Exploration output - NOT the deterministic lockfile
+// This represents the raw output from an exploration run
+export interface ExplorationReport {
+  spec: string;
+  spec_path: string;
+  spec_description?: string; // Spec-level description for UI display
+  exploration_id: string;
+  timestamp: string;
+  duration_ms: number;
+  browser: 'chromium' | 'firefox' | 'webkit';
+  viewport: { width: number; height: number };
+  base_url: string;
+  steps: ExplorationStep[];
+  outcome_checks: OutcomeCheck[];
+  overall_status: 'completed' | 'failed' | 'timeout';
+  errors: ExplorationError[];
+}
+
+/**
+ * @deprecated Use ExplorationReport instead - this is exploration output, not the deterministic lockfile
+ */
+export type ExplorationLockfile = ExplorationReport;
+
+export interface ExplorationStep {
+  step_index: number;
+  spec_action: LegacySpecStep;
+  execution: StepExecution;
+  screenshots: {
+    before?: string;
+    after?: string;
+  };
+  snapshot_before?: Record<string, unknown>;
+  snapshot_after?: Record<string, unknown>;
+}
+
+export interface StepExecution {
+  status: 'completed' | 'failed' | 'skipped';
+  method?: string;
+  element_ref?: string;
+  selector_used?: string;
+  locator?: LegacyLocatorObject;
+  duration_ms: number;
+  error?: string;
+  value_used?: string;
+  url_used?: string;
+}
+
+export interface OutcomeCheck {
+  check: string;
+  expected: unknown;
+  actual: unknown;
+  passed: boolean;
+}
+
+export interface ExplorationError {
+  step_index?: number;
+  message: string;
+  stack?: string;
+}

package/src/run-store.test.ts

@@ -0,0 +1,232 @@
+/**
+ * Tests for run store (immutable directories)
+ * @see bf-92j
+ */
+
+import { describe, expect, test, beforeEach, afterEach } from 'bun:test';
+import { join } from 'path';
+import { mkdtemp, rm, readlink, stat, readdir, mkdir, writeFile } from 'fs/promises';
+import { tmpdir } from 'os';
+import {
+  createRunStore,
+  createRunId,
+  type RunStore,
+} from './run-store.js';
+
+describe('createRunId', () => {
+  test('generates run ID with correct format', () => {
+    const id = createRunId();
+    expect(id).toMatch(/^run-\d{14}-[a-f0-9]{6}$/);
+  });
+
+  test('generates unique IDs', () => {
+    const ids = new Set<string>();
+    for (let i = 0; i < 100; i++) {
+      ids.add(createRunId());
+    }
+    expect(ids.size).toBe(100);
+  });
+
+  test('includes timestamp in ID', () => {
+    const id = createRunId();
+    const timestamp = id.slice(4, 18);
+    const now = new Date();
+    const year = timestamp.slice(0, 4);
+    expect(parseInt(year)).toBe(now.getFullYear());
+  });
+});
+
+describe('RunStore', () => {
+  let tempDir: string;
+  let store: RunStore;
+
+  beforeEach(async () => {
+    tempDir = await mkdtemp(join(tmpdir(), 'browserflow-test-'));
+    store = createRunStore(tempDir);
+  });
+
+  afterEach(async () => {
+    await rm(tempDir, { recursive: true, force: true });
+  });
+
+  describe('createRun', () => {
+    test('creates run directory with correct structure', async () => {
+      const runPath = await store.createRun('checkout-cart');
+
+      // Check directory exists
+      const stats = await stat(runPath);
+      expect(stats.isDirectory()).toBe(true);
+
+      // Check subdirectories created
+      const artifactsDir = join(runPath, 'artifacts');
+      const screenshotsDir = join(artifactsDir, 'screenshots');
+      const logsDir = join(artifactsDir, 'logs');
+
+      expect((await stat(artifactsDir)).isDirectory()).toBe(true);
+      expect((await stat(screenshotsDir)).isDirectory()).toBe(true);
+      expect((await stat(logsDir)).isDirectory()).toBe(true);
+    });
+
+    test('creates unique run directories', async () => {
+      const run1 = await store.createRun('spec-a');
+      const run2 = await store.createRun('spec-a');
+
+      expect(run1).not.toBe(run2);
+      expect((await stat(run1)).isDirectory()).toBe(true);
+      expect((await stat(run2)).isDirectory()).toBe(true);
+    });
+
+    test('creates run under spec-specific directory', async () => {
+      const runPath = await store.createRun('checkout-cart');
+
+      expect(runPath).toContain('checkout-cart');
+      expect(runPath).toContain('runs');
+    });
+
+    test('updates latest symlink', async () => {
+      const runPath = await store.createRun('checkout-cart');
+
+      const latestPath = join(tempDir, '.browserflow', 'runs', 'checkout-cart', 'latest');
+      const linkTarget = await readlink(latestPath);
+
+      expect(runPath).toContain(linkTarget);
+    });
+
+    test('creates multiple runs for same spec', async () => {
+      const run1 = await store.createRun('checkout-cart');
+      const run2 = await store.createRun('checkout-cart');
+      const run3 = await store.createRun('checkout-cart');
+
+      const runs = await store.listRuns('checkout-cart');
+      expect(runs.length).toBe(3);
+    });
+  });
+
+  describe('getLatestRun', () => {
+    test('returns null for spec with no runs', () => {
+      const latest = store.getLatestRun('nonexistent-spec');
+      expect(latest).toBeNull();
+    });
+
+    test('returns latest run path', async () => {
+      await store.createRun('checkout-cart');
+      await new Promise((r) => setTimeout(r, 10)); // Small delay
+      const run2 = await store.createRun('checkout-cart');
+
+      const latest = store.getLatestRun('checkout-cart');
+      expect(latest).toBe(run2);
+    });
+  });
+
+  describe('listRuns', () => {
+    test('returns empty array for spec with no runs', () => {
+      const runs = store.listRuns('nonexistent-spec');
+      expect(runs).toEqual([]);
+    });
+
+    test('lists all runs newest first', async () => {
+      const run1 = await store.createRun('checkout-cart');
+      await new Promise((r) => setTimeout(r, 10));
+      const run2 = await store.createRun('checkout-cart');
+      await new Promise((r) => setTimeout(r, 10));
+      const run3 = await store.createRun('checkout-cart');
+
+      const runs = store.listRuns('checkout-cart');
+
+      expect(runs.length).toBe(3);
+      expect(runs[0]).toBe(run3);
+      expect(runs[1]).toBe(run2);
+      expect(runs[2]).toBe(run1);
+    });
+
+    test('only lists run directories, not latest symlink', async () => {
+      await store.createRun('checkout-cart');
+      await store.createRun('checkout-cart');
+
+      const runs = store.listRuns('checkout-cart');
+
+      expect(runs.every((r) => r.includes('run-'))).toBe(true);
+      expect(runs.some((r) => r.includes('latest'))).toBe(false);
+    });
+  });
+
+  describe('getRunDir', () => {
+    test('returns full path for run', async () => {
+      const runPath = await store.createRun('checkout-cart');
+      const runId = runPath.split('/').pop()!;
+
+      const dir = store.getRunDir('checkout-cart', runId);
+      expect(dir).toBe(runPath);
+    });
+  });
+
+  describe('runExists', () => {
+    test('returns false for nonexistent run', () => {
+      expect(store.runExists('checkout-cart', 'run-nonexistent')).toBe(false);
+    });
+
+    test('returns true for existing run', async () => {
+      const runPath = await store.createRun('checkout-cart');
+      const runId = runPath.split('/').pop()!;
+
+      expect(store.runExists('checkout-cart', runId)).toBe(true);
+    });
+  });
+
+  describe('immutability', () => {
+    test('never overwrites existing runs', async () => {
+      const run1 = await store.createRun('checkout-cart');
+
+      // Write a file to the run
+      await writeFile(join(run1, 'test.txt'), 'original');
+
+      // Create another run
+      const run2 = await store.createRun('checkout-cart');
+
+      // Original run should be unchanged
+      const content = await Bun.file(join(run1, 'test.txt')).text();
+      expect(content).toBe('original');
+
+      // New run should be different
+      expect(run1).not.toBe(run2);
+    });
+  });
+});
+
+describe('directory structure', () => {
+  let tempDir: string;
+  let store: RunStore;
+
+  beforeEach(async () => {
+    tempDir = await mkdtemp(join(tmpdir(), 'browserflow-test-'));
+    store = createRunStore(tempDir);
+  });
+
+  afterEach(async () => {
+    await rm(tempDir, { recursive: true, force: true });
+  });
+
+  test('creates .browserflow root directory', async () => {
+    await store.createRun('test-spec');
+
+    const browserflowDir = join(tempDir, '.browserflow');
+    const stats = await stat(browserflowDir);
+    expect(stats.isDirectory()).toBe(true);
+  });
+
+  test('creates runs directory', async () => {
+    await store.createRun('test-spec');
+
+    const runsDir = join(tempDir, '.browserflow', 'runs');
+    const stats = await stat(runsDir);
+    expect(stats.isDirectory()).toBe(true);
+  });
+
+  test('creates spec-specific directory', async () => {
+    await store.createRun('checkout-cart');
+
+    const specDir = join(tempDir, '.browserflow', 'runs', 'checkout-cart');
+    const stats = await stat(specDir);
+    expect(stats.isDirectory()).toBe(true);
+  });
+});

package/src/run-store.ts

@@ -0,0 +1,240 @@
+/**
+ * Immutable run directory management
+ *
+ * Manages .browserflow/ directories for storing exploration runs,
+ * screenshots, and generated artifacts.
+ *
+ * @see bf-92j for implementation task
+ */
+
+import { join } from 'path';
+import { randomBytes } from 'crypto';
+import { mkdir, symlink, unlink } from 'fs/promises';
+import { existsSync, statSync, readdirSync } from 'fs';
+
+/**
+ * Run directory structure:
+ * .browserflow/
+ *   runs/
+ *     <spec-name>/
+ *       run-20260115-031000-abc123/
+ *         exploration.json
+ *         review.json
+ *         lockfile.json
+ *         artifacts/
+ *           screenshots/
+ *           trace.zip
+ *           logs/
+ *       run-20260115-041500-def456/
+ *         ...
+ *       latest -> run-20260115-041500-def456
+ *   cache/
+ *   tmp/
+ */
+
+export interface RunDirectoryPaths {
+  root: string;
+  runsDir: string;
+  runDir: string;
+  lockfile: string;
+  screenshotsDir: string;
+  reviewFile: string;
+}
+
+export interface RunStore {
+  createRun(specName: string): Promise<string>;
+  getLatestRun(specName: string): string | null;
+  listRuns(specName: string): string[];
+  getRunDir(specName: string, runId: string): string;
+  runExists(specName: string, runId: string): boolean;
+}
+
+/**
+ * Generates a unique run ID.
+ *
+ * Format: run-<YYYYMMDDHHMMSS>-<random>
+ * Example: run-20260115031000-a3f2dd
+ */
+export function createRunId(): string {
+  const now = new Date();
+  const ts = now
+    .toISOString()
+    .replace(/[-:T]/g, '')
+    .slice(0, 14); // YYYYMMDDHHMMSS
+  const rand = randomBytes(3).toString('hex');
+  return `run-${ts}-${rand}`;
+}
+
+/**
+ * Creates a RunStore instance for a project root.
+ */
+export function createRunStore(projectRoot: string): RunStore {
+  const browserflowDir = join(projectRoot, '.browserflow');
+  const runsDir = join(browserflowDir, 'runs');
+
+  return {
+    async createRun(specName: string): Promise<string> {
+      const specDir = join(runsDir, specName);
+      const runId = createRunId();
+      const runDir = join(specDir, runId);
+
+      // Create directory structure
+      await mkdir(runDir, { recursive: true });
+      await mkdir(join(runDir, 'artifacts', 'screenshots'), { recursive: true });
+      await mkdir(join(runDir, 'artifacts', 'logs'), { recursive: true });
+
+      // Update "latest" symlink atomically
+      const latestPath = join(specDir, 'latest');
+      const tempLatestPath = join(specDir, `.latest-${Date.now()}`);
+
+      try {
+        // Create symlink to new location
+        await symlink(runId, tempLatestPath);
+
+        // Atomic rename (replaces old symlink)
+        try {
+          await unlink(latestPath);
+        } catch {
+          // Ignore if doesn't exist
+        }
+        await symlink(runId, latestPath);
+        await unlink(tempLatestPath);
+      } catch (error) {
+        // Cleanup temp symlink on error
+        try {
+          await unlink(tempLatestPath);
+        } catch {
+          // Ignore
+        }
+        throw error;
+      }
+
+      return runDir;
+    },
+
+    getLatestRun(specName: string): string | null {
+      const specDir = join(runsDir, specName);
+      const latestPath = join(specDir, 'latest');
+
+      try {
+        // Check if latest symlink exists
+        if (!existsSync(latestPath)) {
+          return null;
+        }
+
+        // Read symlink target synchronously
+        const target = readdirSync(specDir)
+          .filter((name) => name.startsWith('run-'))
+          .map((name) => ({
+            name,
+            path: join(specDir, name),
+            mtime: statSync(join(specDir, name)).mtime.getTime(),
+          }))
+          .sort((a, b) => b.mtime - a.mtime)[0];
+
+        return target ? target.path : null;
+      } catch {
+        return null;
+      }
+    },
+
+    listRuns(specName: string): string[] {
+      const specDir = join(runsDir, specName);
+
+      try {
+        if (!existsSync(specDir)) {
+          return [];
+        }
+
+        return readdirSync(specDir)
+          .filter((name) => name.startsWith('run-'))
+          .map((name) => ({
+            name,
+            path: join(specDir, name),
+            mtime: statSync(join(specDir, name)).mtime.getTime(),
+          }))
+          .sort((a, b) => b.mtime - a.mtime)
+          .map((item) => item.path);
+      } catch {
+        return [];
+      }
+    },
+
+    getRunDir(specName: string, runId: string): string {
+      return join(runsDir, specName, runId);
+    },
+
+    runExists(specName: string, runId: string): boolean {
+      const runDir = join(runsDir, specName, runId);
+      try {
+        return existsSync(runDir) && statSync(runDir).isDirectory();
+      } catch {
+        return false;
+      }
+    },
+  };
+}
+
+/**
+ * Gets paths for a run directory.
+ *
+ * @param projectRoot - Root of the project (where .browserflow lives)
+ * @param explorationId - Unique exploration identifier
+ * @returns Paths object
+ */
+export function getRunPaths(projectRoot: string, explorationId: string): RunDirectoryPaths {
+  const root = join(projectRoot, '.browserflow');
+  const runsDir = join(root, 'runs');
+  const runDir = join(runsDir, explorationId);
+
+  return {
+    root,
+    runsDir,
+    runDir,
+    lockfile: join(runDir, 'lockfile.json'),
+    screenshotsDir: join(runDir, 'screenshots'),
+    reviewFile: join(runDir, 'review.json'),
+  };
+}
+
+/**
+ * Generates a unique exploration ID.
+ *
+ * Format: <spec-slug>-<timestamp>-<random>
+ * Example: login-flow-20240115-143022-abc123
+ *
+ * @param specName - Name of the spec
+ * @returns Unique exploration ID
+ */
+export function generateExplorationId(specName: string): string {
+  const slug = specName
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '')
+    .slice(0, 30);
+
+  const timestamp = new Date()
+    .toISOString()
+    .replace(/[-:T]/g, '')
+    .slice(0, 14);
+
+  const random = Math.random().toString(36).slice(2, 8);
+
+  return `${slug}-${timestamp}-${random}`;
+}
+
+/**
+ * Gets the screenshot path for a step.
+ *
+ * @param screenshotsDir - Screenshots directory path
+ * @param stepIndex - Step index (0-based)
+ * @param type - "before" or "after"
+ * @returns Screenshot file path
+ */
+export function getScreenshotPath(
+  screenshotsDir: string,
+  stepIndex: number,
+  type: 'before' | 'after'
+): string {
+  return join(screenshotsDir, `step-${stepIndex}-${type}.png`);
+}