@browserflow-ai/core 0.0.6

package/dist/lockfile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lockfile.d.ts","sourceRoot":"","sources":["../src/lockfile.ts"],"names":[],"mappings":"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"}

package/dist/lockfile.js

@@ -0,0 +1,86 @@
+/**
+ * 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 } from './locator-object.js';
+export const assertionTypeSchema = z.enum([
+    'visible',
+    'hidden',
+    'text_contains',
+    'text_equals',
+    'url_contains',
+    'url_matches',
+    'count',
+    'attribute',
+    'checked',
+    'screenshot',
+]);
+export const maskSchema = z.object({
+    x: z.number(),
+    y: z.number(),
+    width: z.number(),
+    height: z.number(),
+    reason: z.string(),
+    locator: z.string().optional(),
+});
+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(),
+});
+export const generationMetadataSchema = z.object({
+    format: z.literal('playwright-ts'),
+    output_path: z.string(),
+    generated_at: z.string().optional(),
+});
+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) {
+    return lockfileSchema.safeParse(lockfile).success;
+}
+/**
+ * Computes SHA256 hash of spec file content
+ */
+export function computeSpecHash(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+/**
+ * Reads a lockfile from a run directory
+ */
+export async function readLockfile(runDir) {
+    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, lockfile) {
+    const lockfilePath = join(runDir, 'lockfile.json');
+    const content = JSON.stringify(lockfile, null, 2);
+    await writeFile(lockfilePath, content, 'utf-8');
+}
+//# sourceMappingURL=lockfile.js.map

package/dist/lockfile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lockfile.js","sourceRoot":"","sources":["../src/lockfile.ts"],"names":[],"mappings":"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"}

package/dist/run-store.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Immutable run directory management
+ *
+ * Manages .browserflow/ directories for storing exploration runs,
+ * screenshots, and generated artifacts.
+ *
+ * @see bf-92j for implementation task
+ */
+/**
+ * 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 declare function createRunId(): string;
+/**
+ * Creates a RunStore instance for a project root.
+ */
+export declare function createRunStore(projectRoot: string): RunStore;
+/**
+ * Gets paths for a run directory.
+ *
+ * @param projectRoot - Root of the project (where .browserflow lives)
+ * @param explorationId - Unique exploration identifier
+ * @returns Paths object
+ */
+export declare function getRunPaths(projectRoot: string, explorationId: string): RunDirectoryPaths;
+/**
+ * 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 declare function generateExplorationId(specName: string): string;
+/**
+ * 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 declare function getScreenshotPath(screenshotsDir: string, stepIndex: number, type: 'before' | 'after'): string;
+//# sourceMappingURL=run-store.d.ts.map

package/dist/run-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-store.d.ts","sourceRoot":"","sources":["../src/run-store.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAOH;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,QAAQ;IACvB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7C,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC9C,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACrC,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IACnD,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CACrD;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAQpC;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,QAAQ,CAyG5D;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,WAAW,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,iBAAiB,CAazF;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAe9D;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,cAAc,EAAE,MAAM,EACtB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,QAAQ,GAAG,OAAO,GACvB,MAAM,CAER"}

package/dist/run-store.js

@@ -0,0 +1,181 @@
+/**
+ * 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';
+/**
+ * Generates a unique run ID.
+ *
+ * Format: run-<YYYYMMDDHHMMSS>-<random>
+ * Example: run-20260115031000-a3f2dd
+ */
+export function createRunId() {
+    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) {
+    const browserflowDir = join(projectRoot, '.browserflow');
+    const runsDir = join(browserflowDir, 'runs');
+    return {
+        async createRun(specName) {
+            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) {
+            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) {
+            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, runId) {
+            return join(runsDir, specName, runId);
+        },
+        runExists(specName, runId) {
+            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, explorationId) {
+    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) {
+    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, stepIndex, type) {
+    return join(screenshotsDir, `step-${stepIndex}-${type}.png`);
+}
+//# sourceMappingURL=run-store.js.map

package/dist/run-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-store.js","sourceRoot":"","sources":["../src/run-store.ts"],"names":[],"mappings":"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"}

package/dist/spec-loader.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Spec loading and normalization utilities
+ * @see bf-7ne - preconditions.page string coercion
+ */
+import type { Preconditions, BrowserFlowSpec } from './spec-schema.js';
+import type { z } from 'zod';
+/**
+ * Normalize preconditions to handle backward-compatible formats
+ * Coerces string page values to object format
+ */
+export declare function normalizePreconditions(preconditions: unknown): Preconditions;
+/**
+ * Load and validate a spec with normalization
+ * Returns a Zod SafeParseReturnType for detailed error handling
+ */
+export declare function loadSpec(rawSpec: unknown): z.SafeParseReturnType<unknown, BrowserFlowSpec>;
+//# sourceMappingURL=spec-loader.d.ts.map

package/dist/spec-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-loader.d.ts","sourceRoot":"","sources":["../src/spec-loader.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAEvE,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,aAAa,EAAE,OAAO,GAAG,aAAa,CAa5E;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,CAAC,CAAC,mBAAmB,CAAC,OAAO,EAAE,eAAe,CAAC,CAc1F"}

package/dist/spec-loader.js

@@ -0,0 +1,37 @@
+/**
+ * Spec loading and normalization utilities
+ * @see bf-7ne - preconditions.page string coercion
+ */
+import { specSchema } from './spec-schema.js';
+/**
+ * Normalize preconditions to handle backward-compatible formats
+ * Coerces string page values to object format
+ */
+export function normalizePreconditions(preconditions) {
+    if (!preconditions || typeof preconditions !== 'object') {
+        return {};
+    }
+    const pre = { ...preconditions };
+    // Coerce string page to object format
+    if (typeof pre.page === 'string') {
+        pre.page = { url: pre.page };
+    }
+    return pre;
+}
+/**
+ * Load and validate a spec with normalization
+ * Returns a Zod SafeParseReturnType for detailed error handling
+ */
+export function loadSpec(rawSpec) {
+    if (!rawSpec || typeof rawSpec !== 'object') {
+        return specSchema.safeParse(rawSpec);
+    }
+    const spec = { ...rawSpec };
+    // Normalize preconditions if present
+    if (spec.preconditions) {
+        spec.preconditions = normalizePreconditions(spec.preconditions);
+    }
+    // Validate with Zod schema
+    return specSchema.safeParse(spec);
+}
+//# sourceMappingURL=spec-loader.js.map

package/dist/spec-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-loader.js","sourceRoot":"","sources":["../src/spec-loader.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAG9C;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CAAC,aAAsB;IAC3D,IAAI,CAAC,aAAa,IAAI,OAAO,aAAa,KAAK,QAAQ,EAAE,CAAC;QACxD,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,GAAG,GAAG,EAAE,GAAG,aAAa,EAA6B,CAAC;IAE5D,sCAAsC;IACtC,IAAI,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QACjC,GAAG,CAAC,IAAI,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC;IAC/B,CAAC;IAED,OAAO,GAAoB,CAAC;AAC9B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,QAAQ,CAAC,OAAgB;IACvC,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;QAC5C,OAAO,UAAU,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IACvC,CAAC;IAED,MAAM,IAAI,GAAG,EAAE,GAAG,OAAO,EAA6B,CAAC;IAEvD,qCAAqC;IACrC,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;QACvB,IAAI,CAAC,aAAa,GAAG,sBAAsB,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IAClE,CAAC;IAED,2BAA2B;IAC3B,OAAO,UAAU,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;AACpC,CAAC"}