@originator/playflow 1.0.0

package/README.md

@@ -0,0 +1,106 @@
+# Playflow
+
+Run Playwright browser flows from a JSON file.
+
+## Install
+
+```bash
+npm install
+```
+
+During install, Playwright will download the Chromium browser automatically.
+
+If you prefer to skip browser downloads (CI or custom caching), set:
+
+```bash
+PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 npm install
+```
+
+Then install Chromium separately:
+
+```bash
+npx playwright install chromium
+```
+
+## Build
+
+```bash
+npm run build
+```
+
+## Run
+
+```bash
+node dist/playflow.js flow_send_direct_message.json --headed
+node dist/playflow.js https://example.com/flow.json --headless
+```
+
+Or after publishing:
+
+```bash
+npx playflow flow_send_direct_message.json --headed
+npx playflow https://example.com/flow.json --headless
+
+If you run with no arguments, Playflow will prompt for a file path or URL:
+
+```bash
+npx playflow
+```
+```
+
+## CLI options
+
+- `--headed` / `--headless`
+- `--slowmo=ms`
+- `--timeout=ms`
+- `--debug`
+
+Chromium is the only supported browser.
+
+## Flow file format
+
+Example:
+
+```json
+{
+  "headless": false,
+  "steps": [
+    { "type": "goto", "url": "https://example.com" },
+    { "type": "click", "selector": "text=Sign in" },
+    { "type": "fill", "selector": "#email", "value": "user@example.com" }
+  ]
+}
+```
+
+### Supported steps
+
+- `goto`: `{ "type": "goto", "url": "https://..." }`
+- `click`: `{ "type": "click", "selector": "..." }`
+- `hover`: `{ "type": "hover", "selector": "..." }`
+- `choose_file`: `{ "type": "choose_file", "selector": "...", "file_name": "file.txt" }`
+- `fill`: `{ "type": "fill", "selector": "...", "value": "..." }`
+- `waitForSelector`: `{ "type": "waitForSelector", "selector": "...", "timeoutMs": 10000 }`
+- `focus`: `{ "type": "focus", "selector": "..." }`
+- `screenshot`: `{ "type": "screenshot", "path": "optional-name.png" }`
+- `keyboard_press`: `{ "type": "keyboard_press", "keys": "Enter" }`
+- `keyboard_type`: `{ "type": "keyboard_type", "text": "hello" }`
+- `keyboard_down`: `{ "type": "keyboard_down", "keys": "Shift" }`
+- `waitForTimeout`: `{ "type": "waitForTimeout", "ms": 1000 }`
+- `waitForLoadState`: `{ "type": "waitForLoadState", "state": "networkidle" }`
+
+### Role-based selectors (optional)
+
+Some steps accept a `role` field:
+
+```json
+{
+  "type": "click",
+  "selector": "button",
+  "role": { "type": "button", "opts": { "name": "Save" } }
+}
+```
+
+## Debug output
+
+Screenshots are saved to `debug-output/` with timestamps. On step failures, a
+DOM snapshot and error screenshot are captured.

package/dist/playflow.js

@@ -0,0 +1,723 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const os_1 = require("os");
+const http_1 = __importDefault(require("http"));
+const https_1 = __importDefault(require("https"));
+const readline_1 = __importDefault(require("readline"));
+const child_process_1 = require("child_process");
+const playwright_1 = require("playwright");
+function parseArgs(argv) {
+    const args = { _: [] };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--headless") {
+            args.headless = true;
+        }
+        else if (arg === "--headed") {
+            args.headless = false;
+        }
+        else if (arg.startsWith("--slowmo=")) {
+            args.slowMo = Number(arg.split("=")[1]);
+        }
+        else if (arg === "--slowmo") {
+            args.slowMo = Number(argv[i + 1]);
+            i += 1;
+        }
+        else if (arg.startsWith("--timeout=")) {
+            args.timeout = Number(arg.split("=")[1]);
+        }
+        else if (arg === "--timeout") {
+            args.timeout = Number(argv[i + 1]);
+            i += 1;
+        }
+        else if (arg === "--debug") {
+            args.debug = true;
+        }
+        else if (arg === "-h" || arg === "--help") {
+            args.help = true;
+        }
+        else if (arg.startsWith("-")) {
+            args.unknown = args.unknown || [];
+            args.unknown.push(arg);
+        }
+        else {
+            args._.push(arg);
+        }
+    }
+    return args;
+}
+function printUsage() {
+    console.log([
+        "Usage:",
+        "  playflow <flow.json|flow-url> [--headed|--headless]",
+        "          [--slowmo=ms] [--timeout=ms] [--debug]",
+        "",
+        "Example:",
+        "  playflow flow_send_direct_message.json --headed --slowmo=100 --debug",
+        "  playflow https://example.com/flow.json --headless",
+    ].join("\n"));
+}
+const ui = {
+    reset: "\u001b[0m",
+    bold: "\u001b[1m",
+    dim: "\u001b[2m",
+    cyan: "\u001b[36m",
+    green: "\u001b[32m",
+    yellow: "\u001b[33m",
+};
+function formatBox(lines) {
+    const contentWidth = Math.max(...lines.map((line) => line.length), 0);
+    const top = `+${"-".repeat(contentWidth + 2)}+`;
+    const bottom = top;
+    return [
+        top,
+        ...lines.map((line) => `| ${line.padEnd(contentWidth, " ")} |`),
+        bottom,
+    ];
+}
+function clearScreen() {
+    if (process.stdout.isTTY) {
+        process.stdout.write("\u001b[2J\u001b[H");
+    }
+}
+async function selectSimpleMenu(title, options, fallback) {
+    if (!process.stdin.isTTY ||
+        !process.stdout.isTTY ||
+        typeof process.stdin.setRawMode !== "function") {
+        return fallback;
+    }
+    process.stdin.resume();
+    readline_1.default.emitKeypressEvents(process.stdin);
+    process.stdin.setRawMode(true);
+    let selected = 0;
+    const render = () => {
+        clearScreen();
+        console.log(`${ui.cyan}${ui.bold}Playflow${ui.reset} ${ui.dim}- ${title}${ui.reset}`);
+        console.log("");
+        options.forEach((option, index) => {
+            const isActive = index === selected;
+            const cursor = isActive ? `${ui.green}›${ui.reset}` : " ";
+            const label = isActive ? `${ui.bold}${option.label}${ui.reset}` : option.label;
+            const hint = option.hint ? ` ${ui.dim}${option.hint}${ui.reset}` : "";
+            console.log(` ${cursor} ${label}${hint}`);
+        });
+        console.log("");
+        console.log(`${ui.dim}Use ↑/↓ to move, Enter to select, Q to quit.${ui.reset}`);
+    };
+    return new Promise((resolve, reject) => {
+        const cleanup = () => {
+            process.stdin.setRawMode(false);
+            process.stdin.removeListener("keypress", onKeypress);
+            process.stdin.pause();
+        };
+        const onKeypress = (_, key) => {
+            if (key.ctrl && key.name === "c") {
+                cleanup();
+                process.exit(1);
+            }
+            if (key.name === "up") {
+                selected = (selected - 1 + options.length) % options.length;
+                render();
+                return;
+            }
+            if (key.name === "down") {
+                selected = (selected + 1) % options.length;
+                render();
+                return;
+            }
+            if (key.name === "return") {
+                const choice = options[selected];
+                cleanup();
+                clearScreen();
+                resolve(choice.value);
+                return;
+            }
+            if (key.name === "q") {
+                cleanup();
+                clearScreen();
+                console.log("Bye!");
+                process.exit(0);
+            }
+        };
+        process.stdin.on("keypress", onKeypress);
+        render();
+    });
+}
+async function selectMenu(options) {
+    if (!process.stdin.isTTY ||
+        !process.stdout.isTTY ||
+        typeof process.stdin.setRawMode !== "function") {
+        return "file";
+    }
+    process.stdin.resume();
+    readline_1.default.emitKeypressEvents(process.stdin);
+    process.stdin.setRawMode(true);
+    let selected = 0;
+    const render = () => {
+        clearScreen();
+        console.log(`${ui.cyan}${ui.bold}Playflow${ui.reset} ${ui.dim}- choose input type${ui.reset}`);
+        console.log("");
+        options.forEach((option, index) => {
+            const isActive = index === selected;
+            const cursor = isActive ? `${ui.green}›${ui.reset}` : " ";
+            const label = isActive ? `${ui.bold}${option.label}${ui.reset}` : option.label;
+            const hint = option.hint ? ` ${ui.dim}${option.hint}${ui.reset}` : "";
+            console.log(` ${cursor} ${label}${hint}`);
+        });
+        console.log("");
+        console.log(`${ui.dim}Use ↑/↓ to move, Enter to select, Q to quit.${ui.reset}`);
+    };
+    return new Promise((resolve, reject) => {
+        const cleanup = () => {
+            process.stdin.setRawMode(false);
+            process.stdin.removeListener("keypress", onKeypress);
+            process.stdin.pause();
+        };
+        const onKeypress = (_, key) => {
+            if (key.ctrl && key.name === "c") {
+                cleanup();
+                process.exit(1);
+            }
+            if (key.name === "up") {
+                selected = (selected - 1 + options.length) % options.length;
+                render();
+                return;
+            }
+            if (key.name === "down") {
+                selected = (selected + 1) % options.length;
+                render();
+                return;
+            }
+            if (key.name === "return") {
+                const choice = options[selected];
+                cleanup();
+                clearScreen();
+                resolve(choice.value);
+                return;
+            }
+            if (key.name === "q") {
+                cleanup();
+                clearScreen();
+                console.log("Bye!");
+                process.exit(0);
+            }
+        };
+        process.stdin.on("keypress", onKeypress);
+        render();
+    });
+}
+async function promptRunAgain() {
+    const rl = readline_1.default.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    try {
+        const answer = (await askQuestion(rl, `${ui.bold}Run another flow?${ui.reset} (y/N): `))
+            .trim()
+            .toLowerCase();
+        return answer === "y" || answer === "yes";
+    }
+    finally {
+        rl.close();
+    }
+}
+function tryMacFolderPicker() {
+    if (process.platform !== "darwin")
+        return null;
+    try {
+        const result = (0, child_process_1.execSync)('osascript -e \'POSIX path of (choose folder with prompt "Select a folder to save the video")\'', { stdio: ["ignore", "pipe", "ignore"] })
+            .toString("utf8")
+            .trim();
+        return result || null;
+    }
+    catch {
+        return null;
+    }
+}
+async function promptForFolderPath(prompt) {
+    const picked = tryMacFolderPicker();
+    if (picked)
+        return picked;
+    const rl = readline_1.default.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    try {
+        const answer = (await askQuestion(rl, prompt)).trim();
+        return answer || null;
+    }
+    finally {
+        rl.close();
+    }
+}
+async function promptForVideoChoice() {
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        return { enabled: false };
+    }
+    const choice = await selectSimpleMenu("Record a video?", [
+        { label: "No", value: "no", hint: "(default)" },
+        { label: "Yes", value: "yes", hint: "(save after run)" },
+    ], "no");
+    if (choice === "yes") {
+        const dir = fs_1.default.mkdtempSync(path_1.default.join((0, os_1.tmpdir)(), "playflow-video-"));
+        return { enabled: true, dir };
+    }
+    return { enabled: false };
+}
+function printWelcome() {
+    clearScreen();
+    const header = `${ui.cyan}${ui.bold}Playflow${ui.reset}`;
+    const subtitle = `${ui.dim}Run browser flows from JSON${ui.reset}`;
+    const body = [
+        `${ui.bold}Quick start${ui.reset}`,
+        `- File: ${ui.dim}./artifact/test_flow.json${ui.reset}`,
+        `- URL : ${ui.dim}https://example.com/flow.json${ui.reset}`,
+        "",
+        `${ui.dim}Tip:${ui.reset} add ${ui.bold}--headed${ui.reset} or ${ui.bold}--headless${ui.reset} to override.`,
+    ];
+    const box = formatBox([
+        `${header}  ${subtitle}`,
+        "",
+        ...body,
+    ]);
+    console.log(["", ...box, ""].join("\n"));
+}
+function getDebugOutputDir() {
+    const debugDir = path_1.default.join(process.cwd(), "debug-output");
+    if (!fs_1.default.existsSync(debugDir)) {
+        fs_1.default.mkdirSync(debugDir, { recursive: true });
+    }
+    return debugDir;
+}
+function getScreenshotPath(originalPath) {
+    const debugDir = getDebugOutputDir();
+    const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const baseName = originalPath
+        ? originalPath.replace(/\.png$/i, "")
+        : "screenshot";
+    return path_1.default.join(debugDir, `${baseName}_${timestamp}.png`);
+}
+function extractUsefulDom(html, maxLength = 10000) {
+    let cleaned = html.replace(/<!DOCTYPE[^>]*>/gi, "");
+    cleaned = cleaned.replace(/<head[^>]*>[\s\S]*?<\/head>/gi, "");
+    cleaned = cleaned.replace(/<script[^>]*>[\s\S]*?<\/script>/gi, "");
+    cleaned = cleaned.replace(/<style[^>]*>[\s\S]*?<\/style>/gi, "");
+    cleaned = cleaned.replace(/<link[^>]*\/?>/gi, "");
+    cleaned = cleaned.replace(/<meta[^>]*\/?>/gi, "");
+    cleaned = cleaned.replace(/<noscript[^>]*>[\s\S]*?<\/noscript>/gi, "");
+    cleaned = cleaned.replace(/<!--[\s\S]*?-->/g, "");
+    cleaned = cleaned.replace(/\s+style="[^"]*"/gi, "");
+    cleaned = cleaned.replace(/\s+class="([^"]*)"/gi, (match, classes) => {
+        if (classes.length < 50)
+            return match;
+        const meaningfulClasses = classes
+            .split(/\s+/)
+            .filter((cls) => !cls.match(/^(flex|grid|p-|m-|w-|h-|bg-|text-|border-|rounded-|shadow-|hover:|focus:|active:|min-|max-|overflow-|transition-|duration-|ease-|transform|translate|scale|rotate|skew|origin-|cursor-|pointer-|select-|resize-|fill-|stroke-|opacity-|z-|gap-|space-|divide-|place-|justify-|items-|content-|self-|order-|col-|row-|auto-|sr-|not-|group-|peer-|first:|last:|odd:|even:|disabled:|checked:|required:|invalid:|placeholder:|before:|after:|dark:|sm:|md:|lg:|xl:|2xl:)/))
+            .join(" ");
+        return meaningfulClasses ? ` class="${meaningfulClasses}"` : "";
+    });
+    cleaned = cleaned.replace(/\s+data-(?!testid)[a-z-]+="[^"]*"/gi, "");
+    cleaned = cleaned.replace(/\s+/g, " ");
+    cleaned = cleaned.replace(/<(\w+)[^>]*>\s*<\/\1>/g, "");
+    cleaned = cleaned.trim();
+    if (cleaned.length > maxLength) {
+        const cutPoint = cleaned.lastIndexOf(">", maxLength);
+        if (cutPoint > maxLength * 0.8) {
+            cleaned = cleaned.substring(0, cutPoint + 1) + "... [truncated]";
+        }
+        else {
+            cleaned = cleaned.substring(0, maxLength) + "... [truncated]";
+        }
+    }
+    return cleaned;
+}
+function isUrl(value) {
+    return /^https?:\/\//i.test(value);
+}
+function askQuestion(rl, prompt) {
+    return new Promise((resolve) => rl.question(prompt, resolve));
+}
+function tryMacFilePicker() {
+    if (process.platform !== "darwin")
+        return null;
+    try {
+        const result = (0, child_process_1.execSync)('osascript -e \'POSIX path of (choose file with prompt "Select a Playflow JSON file")\'', { stdio: ["ignore", "pipe", "ignore"] })
+            .toString("utf8")
+            .trim();
+        return result || null;
+    }
+    catch {
+        return null;
+    }
+}
+async function promptForFilePath(rl) {
+    const picked = tryMacFilePicker();
+    if (picked)
+        return picked;
+    while (true) {
+        const answer = (await askQuestion(rl, `${ui.bold}File path${ui.reset}: `)).trim();
+        if (!answer) {
+            console.log(`${ui.yellow}Please enter a file path.${ui.reset}`);
+            continue;
+        }
+        const localPath = path_1.default.resolve(process.cwd(), answer);
+        if (!fs_1.default.existsSync(localPath)) {
+            console.log(`${ui.yellow}File not found:${ui.reset} ${localPath}`);
+            continue;
+        }
+        return answer;
+    }
+}
+async function promptForUrl(rl) {
+    while (true) {
+        const answer = (await askQuestion(rl, `${ui.bold}Flow URL${ui.reset}: `)).trim();
+        if (!answer) {
+            console.log(`${ui.yellow}Please enter a URL.${ui.reset}`);
+            continue;
+        }
+        if (!isUrl(answer)) {
+            console.log(`${ui.yellow}URL must start with http:// or https://.${ui.reset}`);
+            continue;
+        }
+        return answer;
+    }
+}
+async function promptForFlowInput() {
+    const rl = readline_1.default.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    try {
+        while (true) {
+            let selection;
+            try {
+                selection = await selectMenu([
+                    { label: "File", value: "file", hint: "(open selector / path)" },
+                    { label: "URL", value: "url", hint: "(https://...)" },
+                ]);
+            }
+            catch {
+                console.log(`${ui.yellow}Selection cancelled.${ui.reset}`);
+                process.exit(1);
+            }
+            if (selection === "file") {
+                const filePath = await promptForFilePath(rl);
+                return { kind: "file", value: filePath };
+            }
+            if (selection === "url") {
+                const url = await promptForUrl(rl);
+                return { kind: "url", value: url };
+            }
+            console.log(`${ui.yellow}Please choose a valid option.${ui.reset}`);
+        }
+    }
+    finally {
+        rl.close();
+    }
+}
+function fetchJsonFromUrl(url) {
+    return new Promise((resolve, reject) => {
+        const client = url.startsWith("https://") ? https_1.default : http_1.default;
+        client
+            .get(url, (res) => {
+            if (!res.statusCode || res.statusCode >= 400) {
+                reject(new Error(`Failed to fetch flow URL (${res.statusCode ?? "unknown"})`));
+                res.resume();
+                return;
+            }
+            const chunks = [];
+            res.on("data", (chunk) => chunks.push(chunk));
+            res.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+        })
+            .on("error", (err) => reject(err));
+    });
+}
+async function loadFlowFromSource(source) {
+    if (isUrl(source)) {
+        const body = await fetchJsonFromUrl(source);
+        return JSON.parse(body);
+    }
+    const flowPath = path_1.default.resolve(process.cwd(), source);
+    return JSON.parse(fs_1.default.readFileSync(flowPath, "utf8"));
+}
+async function loadFlowFromInput(input) {
+    if (input.kind === "url") {
+        const body = await fetchJsonFromUrl(input.value);
+        return JSON.parse(body);
+    }
+    const flowPath = path_1.default.resolve(process.cwd(), input.value);
+    return JSON.parse(fs_1.default.readFileSync(flowPath, "utf8"));
+}
+async function getElement(selector, role, page) {
+    let element = page.locator(selector);
+    if (role) {
+        element = element.getByRole(role.type, role.opts);
+    }
+    const el = element.first();
+    if (!el) {
+        throw new Error(`Element not found: ${selector}`);
+    }
+    await el.scrollIntoViewIfNeeded();
+    return el;
+}
+async function runStep(step, page) {
+    switch (step.type) {
+        case "goto":
+            console.log(`goto ${step.url}`);
+            await page.goto(step.url);
+            break;
+        case "click":
+            console.log(`click ${step.selector}`);
+            await (await getElement(step.selector, step.role, page)).click();
+            break;
+        case "hover":
+            console.log(`hover ${step.selector}`);
+            await (await getElement(step.selector, step.role, page)).hover();
+            break;
+        case "choose_file": {
+            console.log(`choose_file ${step.selector} ${step.file_name}`);
+            const fileChooserPromise = page.waitForEvent("filechooser");
+            await (await getElement(step.selector, step.role, page)).click();
+            const fileChooser = await fileChooserPromise;
+            const tempFilePath = path_1.default.join((0, os_1.tmpdir)(), `${step.file_name}`);
+            const folderPath = path_1.default.join((0, os_1.tmpdir)(), step.file_name.split("/").slice(0, -1).join("/"));
+            if (folderPath && !fs_1.default.existsSync(folderPath)) {
+                fs_1.default.mkdirSync(folderPath, { recursive: true });
+            }
+            fs_1.default.writeFileSync(tempFilePath, `Hello, world! ${step.file_name}`);
+            await fileChooser.setFiles(tempFilePath);
+            break;
+        }
+        case "fill":
+            console.log(`fill ${step.selector}`);
+            await (await getElement(step.selector, step.role, page)).fill(step.value);
+            break;
+        case "waitForSelector":
+            console.log(`waitForSelector ${step.selector} ${step.timeoutMs ?? 10000}`);
+            await (await getElement(step.selector, step.role, page)).waitFor({
+                timeout: step.timeoutMs ?? 10000,
+            });
+            break;
+        case "focus":
+            console.log(`focus ${step.selector}`);
+            await (await getElement(step.selector, step.role, page)).focus();
+            break;
+        case "screenshot": {
+            const screenshotPath = getScreenshotPath(step.path);
+            await page.screenshot({ path: screenshotPath });
+            console.log(`Screenshot saved to: ${screenshotPath}`);
+            break;
+        }
+        case "keyboard_press":
+            console.log(`keyboard_press ${step.keys}`);
+            await page.keyboard.press(step.keys);
+            break;
+        case "keyboard_type":
+            console.log(`keyboard_type ${step.text}`);
+            await page.keyboard.type(step.text);
+            break;
+        case "keyboard_down":
+            console.log(`keyboard_down ${step.keys}`);
+            await page.keyboard.down(step.keys);
+            break;
+        case "waitForTimeout":
+            await page.waitForTimeout(step.ms);
+            break;
+        case "waitForLoadState":
+            await page.waitForLoadState(step.state, { timeout: step.timeout });
+            break;
+        default: {
+            const unreachable = step;
+            throw new Error(`Unsupported step type: ${unreachable}`);
+        }
+    }
+}
+async function captureFailureContext(page, step, stepIndex, stepsTotal, error) {
+    const pageUrl = page.url();
+    let screenshotPath;
+    let domSnapshot;
+    try {
+        const screenshotBuffer = await page.screenshot({ fullPage: true });
+        screenshotPath = getScreenshotPath(`error_step${stepIndex + 1}_${step.type}`);
+        fs_1.default.writeFileSync(screenshotPath, screenshotBuffer);
+    }
+    catch {
+        console.warn("Failed to capture screenshot after step failure");
+    }
+    try {
+        const content = await page.content();
+        domSnapshot = extractUsefulDom(content, 8000);
+    }
+    catch {
+        console.warn("Failed to capture DOM snapshot after step failure");
+    }
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    const selector = "selector" in step ? step.selector : undefined;
+    console.error("Step execution failed", {
+        stepIndex,
+        stepType: step.type,
+        selector,
+        pageUrl,
+        error: errorMessage,
+        message: `Step ${stepIndex + 1}/${stepsTotal} failed`,
+    });
+    return {
+        stepIndex,
+        stepType: step.type,
+        selector,
+        pageUrl,
+        errorMessage,
+        screenshotPath,
+        domSnapshot,
+    };
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    if (args.help) {
+        printUsage();
+        process.exit(0);
+    }
+    if (args.unknown?.length) {
+        console.error(`Unknown flags: ${args.unknown.join(", ")}`);
+        printUsage();
+        process.exit(1);
+    }
+    const interactive = args._.length === 0;
+    const runOnce = async () => {
+        if (interactive) {
+            printWelcome();
+            const input = await promptForFlowInput();
+            return await loadFlowFromInput(input);
+        }
+        const flowSource = args._[0];
+        return await loadFlowFromSource(flowSource);
+    };
+    while (true) {
+        const flow = await runOnce();
+        const videoConfig = interactive ? await promptForVideoChoice() : { enabled: false };
+        if (!Array.isArray(flow.steps)) {
+            throw new Error("Flow file must include a steps array.");
+        }
+        const headless = typeof args.headless === "boolean"
+            ? args.headless
+            : typeof flow.headless === "boolean"
+                ? flow.headless
+                : false;
+        const slowMo = typeof args.slowMo === "number"
+            ? args.slowMo
+            : typeof flow.slowMo === "number"
+                ? flow.slowMo
+                : undefined;
+        let browser = null;
+        let page = null;
+        let currentStepIndex = -1;
+        let recordedVideoPath = null;
+        let runFailed = false;
+        try {
+            browser = await playwright_1.chromium.launch({ headless, slowMo });
+            const contextOptions = {
+                ...(flow.contextOptions || {}),
+            };
+            if (videoConfig.enabled && videoConfig.dir) {
+                contextOptions.recordVideo = { dir: videoConfig.dir };
+            }
+            const context = await browser.newContext(contextOptions);
+            page = await context.newPage();
+            if (typeof args.timeout === "number") {
+                page.setDefaultTimeout(args.timeout);
+            }
+            else if (typeof flow.timeout === "number") {
+                page.setDefaultTimeout(flow.timeout);
+            }
+            for (let i = 0; i < flow.steps.length; i += 1) {
+                currentStepIndex = i;
+                const step = flow.steps[i];
+                if (args.debug) {
+                    console.log(`Step ${i + 1}/${flow.steps.length}: ${step.type}`);
+                }
+                try {
+                    await runStep(step, page);
+                }
+                catch (stepError) {
+                    await captureFailureContext(page, step, i, flow.steps.length, stepError);
+                    runFailed = true;
+                    break;
+                }
+            }
+            if (!runFailed && args.debug) {
+                console.log("Run completed successfully.");
+            }
+        }
+        catch (error) {
+            console.error("Error running playwright flow", {
+                error: error instanceof Error ? error.message : String(error),
+                currentStepIndex,
+            });
+            runFailed = true;
+        }
+        finally {
+            if (page) {
+                const pageVideo = page.video();
+                await page.close();
+                if (pageVideo) {
+                    try {
+                        recordedVideoPath = await pageVideo.path();
+                    }
+                    catch {
+                        recordedVideoPath = null;
+                    }
+                }
+            }
+            await browser?.close();
+        }
+        if (videoConfig.enabled && recordedVideoPath) {
+            const saveFolder = await promptForFolderPath(`${ui.bold}Save video folder${ui.reset}: `);
+            if (saveFolder) {
+                const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+                const filename = `playflow-${timestamp}.webm`;
+                const destination = path_1.default.join(saveFolder, filename);
+                try {
+                    fs_1.default.renameSync(recordedVideoPath, destination);
+                    console.log(`Video saved to: ${destination}`);
+                }
+                catch {
+                    fs_1.default.copyFileSync(recordedVideoPath, destination);
+                    console.log(`Video saved to: ${destination}`);
+                }
+            }
+            else {
+                console.log(`Video saved to: ${recordedVideoPath}`);
+            }
+        }
+        if (!interactive) {
+            process.exitCode = runFailed ? 1 : 0;
+            break;
+        }
+        let runAgain = false;
+        if (process.stdin.isTTY && process.stdout.isTTY) {
+            const next = await selectSimpleMenu("Run another flow?", [
+                { label: "Yes, choose another flow", value: "yes", hint: "(repeat)" },
+                { label: "No, exit Playflow", value: "no", hint: "(quit)" },
+            ], "no");
+            runAgain = next === "yes";
+        }
+        else {
+            runAgain = await promptRunAgain();
+        }
+        if (!runAgain) {
+            console.log("Bye!");
+            process.exitCode = runFailed ? 1 : 0;
+            break;
+        }
+    }
+}
+main().catch((error) => {
+    console.error(error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@originator/playflow",
+  "version": "1.0.0",
+  "main": "./dist/playflow.js",
+  "bin": {
+    "playflow": "./dist/playflow.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "postinstall": "playwright install chromium",
+    "prepublishOnly": "npm run build",
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "test:flow": "node dist/playflow.js ./artifact/test_flow.json --headless"
+  },
+  "description": "Run Playwright browser flows from JSON",
+  "readme": "# Playflow\n\nRun Playwright browser flows from a JSON file.\n\nSee README.md for full documentation.\n",
+  "keywords": [
+    "playwright",
+    "cli",
+    "automation",
+    "browser",
+    "flows"
+  ],
+  "author": "Hamza Lhioui",
+  "license": "ISC",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "playwright": "^1.57.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.9",
+    "typescript": "^5.9.3"
+  }
+}