bangonit 0.3.0 → 0.3.1

package/bin/src/cli/bangonit.js

@@ -0,0 +1,767 @@
+#!/usr/bin/env node
+"use strict";
+// Bang On It! CLI — starts the webapp and Electron app, forwards all args.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const child_process_1 = require("child_process");
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+const net = __importStar(require("net"));
+const readline = __importStar(require("readline"));
+const TOML = __importStar(require("@iarna/toml"));
+const Minio = __importStar(require("minio"));
+const yargs_1 = __importDefault(require("yargs"));
+const helpers_1 = require("yargs/helpers");
+const is_ci_1 = __importDefault(require("is-ci"));
+const args_1 = require("../../app/desktopapp/src/shared/args");
+const ROOT = path.resolve(__dirname, "..");
+const WEBAPP_DIR = path.join(ROOT, "app", "webapp");
+const DESKTOP_DIR = path.join(ROOT, "app", "desktopapp");
+const LOGS_DIR = path.join(process.cwd(), "logs");
+// Colors
+const c = {
+    reset: "\x1b[0m",
+    bold: "\x1b[1m",
+    dim: "\x1b[2m",
+    red: "\x1b[31m",
+    green: "\x1b[32m",
+    yellow: "\x1b[33m",
+    blue: "\x1b[34m",
+    magenta: "\x1b[35m",
+    cyan: "\x1b[36m",
+};
+function die(msg) {
+    console.error(`${c.red}${msg}${c.reset}`);
+    process.exit(1);
+}
+function getFreePort() {
+    return new Promise((resolve, reject) => {
+        const server = net.createServer();
+        server.once("error", reject);
+        server.listen(0, () => {
+            const port = server.address().port;
+            server.close(() => resolve(port));
+        });
+    });
+}
+function isPortFree(port) {
+    return new Promise((resolve) => {
+        const server = net.createServer();
+        server.once("error", () => resolve(false));
+        server.once("listening", () => {
+            server.close();
+            resolve(true);
+        });
+        server.listen(port);
+    });
+}
+async function waitForPort(port, timeoutMs = 30000) {
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+        const free = await isPortFree(port);
+        if (!free)
+            return;
+        await new Promise((r) => setTimeout(r, 500));
+    }
+    die(`Timed out waiting for port ${port}`);
+}
+function loadEnv() {
+    if (!process.env.ANTHROPIC_API_KEY) {
+        const envPath = path.join(process.cwd(), ".env");
+        if (fs.existsSync(envPath)) {
+            for (const line of fs.readFileSync(envPath, "utf-8").split("\n")) {
+                const match = line.match(/^([A-Z_][A-Z0-9_]*)=(.*)$/);
+                if (match && !process.env[match[1]]) {
+                    process.env[match[1]] = match[2].replace(/^["']|["']$/g, "");
+                }
+            }
+        }
+    }
+}
+// Interpolate ${ENV_VAR} references in string values throughout an object
+function interpolateEnv(obj) {
+    if (typeof obj === "string") {
+        return obj.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_, name) => {
+            return process.env[name] || "";
+        });
+    }
+    if (Array.isArray(obj))
+        return obj.map(interpolateEnv);
+    if (obj && typeof obj === "object") {
+        const result = {};
+        for (const [k, v] of Object.entries(obj)) {
+            result[k] = interpolateEnv(v);
+        }
+        return result;
+    }
+    return obj;
+}
+// Walk up from cwd to find .bangonit/ directory, stopping at .git or filesystem root
+function findProjectDir() {
+    let dir = process.cwd();
+    while (true) {
+        if (fs.existsSync(path.join(dir, ".bangonit")))
+            return dir;
+        if (fs.existsSync(path.join(dir, ".git")))
+            return null;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return null; // filesystem root
+        dir = parent;
+    }
+}
+function loadConfig(configPath) {
+    if (configPath) {
+        if (!fs.existsSync(configPath))
+            die(`Config file not found: ${configPath}`);
+        try {
+            const raw = TOML.parse(fs.readFileSync(configPath, "utf-8"));
+            return interpolateEnv(raw);
+        }
+        catch (err) {
+            die(`Error reading config ${configPath}: ${err.message}`);
+        }
+    }
+    const projectDir = findProjectDir();
+    if (!projectDir)
+        return {};
+    const filePath = path.join(projectDir, ".bangonit", "config.toml");
+    if (!fs.existsSync(filePath))
+        return {};
+    try {
+        const raw = TOML.parse(fs.readFileSync(filePath, "utf-8"));
+        return interpolateEnv(raw);
+    }
+    catch (err) {
+        die(`Error reading config ${filePath}: ${err.message}`);
+    }
+}
+// --- Test plan discovery ---
+function findTestPlans(dir, filter) {
+    const results = [];
+    if (!fs.existsSync(dir))
+        return results;
+    function walk(d) {
+        for (const entry of fs.readdirSync(d, { withFileTypes: true })) {
+            const full = path.join(d, entry.name);
+            if (entry.isDirectory()) {
+                walk(full);
+            }
+            else if (entry.name.endsWith(".md")) {
+                results.push(full);
+            }
+        }
+    }
+    walk(dir);
+    if (filter) {
+        const lower = filter.toLowerCase();
+        return results.filter((f) => path.basename(f).toLowerCase().includes(lower));
+    }
+    return results;
+}
+function createS3Client(opts) {
+    const accessKey = opts.accessKey || process.env.AWS_ACCESS_KEY_ID || "";
+    const secretKey = opts.secretKey || process.env.AWS_SECRET_ACCESS_KEY || "";
+    const region = opts.region || process.env.AWS_REGION || process.env.AWS_DEFAULT_REGION || "us-east-1";
+    if (opts.endpoint) {
+        const useSSL = !opts.endpoint.startsWith("http://");
+        const endPoint = opts.endpoint.replace(/^https?:\/\//, "");
+        return new Minio.Client({ endPoint, useSSL, accessKey, secretKey, region });
+    }
+    return new Minio.Client({
+        endPoint: "s3.amazonaws.com",
+        useSSL: true,
+        accessKey,
+        secretKey,
+        region,
+    });
+}
+async function uploadDir(client, localDir, bucket, prefix) {
+    const entries = fs.readdirSync(localDir, { withFileTypes: true });
+    for (const entry of entries) {
+        const fullPath = path.join(localDir, entry.name);
+        const objectName = `${prefix}/${entry.name}`;
+        if (entry.isDirectory()) {
+            await uploadDir(client, fullPath, bucket, objectName);
+        }
+        else {
+            await client.fPutObject(bucket, objectName, fullPath, {});
+        }
+    }
+}
+async function uploadToS3(localDir, opts) {
+    const client = createS3Client(opts);
+    await uploadDir(client, localDir, opts.bucket, opts.prefix);
+    const region = opts.region || process.env.AWS_REGION || process.env.AWS_DEFAULT_REGION || "us-east-1";
+    if (opts.endpoint) {
+        const proto = opts.endpoint.startsWith("http://") ? "http" : "https";
+        const host = opts.endpoint.replace(/^https?:\/\//, "");
+        return `${proto}://${opts.bucket}.${host}/${opts.prefix}/index.html`;
+    }
+    if (region === "us-east-1") {
+        return `https://${opts.bucket}.s3.amazonaws.com/${opts.prefix}/index.html`;
+    }
+    return `https://${opts.bucket}.s3.${region}.amazonaws.com/${opts.prefix}/index.html`;
+}
+function createPrompter() {
+    let closed = false;
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.on("close", () => { closed = true; });
+    return {
+        ask(question, defaultVal) {
+            if (closed)
+                return Promise.resolve(defaultVal || "");
+            return new Promise((resolve) => {
+                const defStr = defaultVal ? `${c.dim} [${defaultVal}]${c.reset}` : "";
+                rl.question(`  ${c.cyan}?${c.reset} ${question}${defStr} `, (answer) => {
+                    resolve(answer.trim() || defaultVal || "");
+                });
+            });
+        },
+        askChoice(question, choices, defaultVal) {
+            if (closed)
+                return Promise.resolve(defaultVal);
+            const choiceStr = choices.map((ch) => ch === defaultVal ? `${c.bold}${ch}${c.reset}${c.dim}` : ch).join("/");
+            return new Promise((resolve) => {
+                rl.question(`  ${c.cyan}?${c.reset} ${question} ${c.dim}(${choiceStr})${c.reset} `, (answer) => {
+                    const val = answer.trim().toLowerCase() || defaultVal;
+                    resolve(choices.includes(val) ? val : defaultVal);
+                });
+            });
+        },
+        close() { rl.close(); },
+    };
+}
+// --- init command ---
+// Common timezone offsets from UTC (standard time)
+const TIMEZONE_OFFSETS = {
+    "us/eastern": -5, "us/central": -6, "us/mountain": -7, "us/pacific": -8,
+    "europe/london": 0, "europe/berlin": 1, "europe/paris": 1,
+    "asia/tokyo": 9, "asia/shanghai": 8, "asia/kolkata": 5,
+    "australia/sydney": 11,
+};
+function localHourToUtc(localHour, utcOffset) {
+    return ((localHour - utcOffset) % 24 + 24) % 24;
+}
+async function initProject() {
+    const p = createPrompter();
+    console.log(`\n  ${c.bold}${c.magenta}Bang On It! init${c.reset}\n`);
+    const testplans = await p.ask("Test plans directory", "testplans");
+    const apiKey = await p.ask("Anthropic API key (empty to use env var)", "");
+    const recordingsDir = await p.ask("Recordings directory", "recordings");
+    const s3Bucket = await p.ask("S3 bucket for recordings (empty to skip)", "");
+    let s3Endpoint = "";
+    let s3Region = "";
+    let s3Prefix = "";
+    if (s3Bucket) {
+        s3Endpoint = await p.ask("S3 endpoint (empty for AWS, or e.g. nyc3.digitaloceanspaces.com)", "");
+        s3Region = await p.ask("S3 region", "us-east-1");
+        s3Prefix = await p.ask("S3 prefix", "bangonit");
+    }
+    // --- Config file ---
+    let toml = `testplans = "${testplans}"\n`;
+    toml += `recordings_dir = "${recordingsDir}"\n`;
+    if (apiKey) {
+        toml += `anthropic_api_key = "${apiKey}"\n`;
+    }
+    else {
+        toml += `# anthropic_api_key = "\${ANTHROPIC_API_KEY}"\n`;
+    }
+    if (s3Bucket) {
+        toml += `\n[s3]\nbucket = "${s3Bucket}"\n`;
+        if (s3Endpoint)
+            toml += `endpoint = "${s3Endpoint}"\n`;
+        if (s3Region && s3Region !== "us-east-1")
+            toml += `region = "${s3Region}"\n`;
+        if (s3Prefix && s3Prefix !== "bangonit")
+            toml += `prefix = "${s3Prefix}"\n`;
+        toml += `# access_key = "\${AWS_ACCESS_KEY_ID}"\n`;
+        toml += `# secret_key = "\${AWS_SECRET_ACCESS_KEY}"\n`;
+    }
+    const bangDir = path.join(process.cwd(), ".bangonit");
+    fs.mkdirSync(bangDir, { recursive: true });
+    const configOutPath = path.join(bangDir, "config.toml");
+    fs.writeFileSync(configOutPath, toml);
+    console.log(`\n  ${c.green}Created${c.reset} .bangonit/config.toml`);
+    // --- Test plan directories ---
+    const testplanBase = path.join(process.cwd(), testplans);
+    const dirs = ["smoke", "acceptance", "regression"];
+    for (const dir of dirs) {
+        const dirPath = path.join(testplanBase, dir);
+        fs.mkdirSync(dirPath, { recursive: true });
+        const gitkeep = path.join(dirPath, ".gitkeep");
+        if (!fs.existsSync(gitkeep))
+            fs.writeFileSync(gitkeep, "");
+        console.log(`  ${c.green}Created${c.reset} ${testplans}/${dir}/`);
+    }
+    // Write example smoke test
+    const smokeExample = path.join(testplanBase, "smoke", "homepage.md");
+    if (!fs.existsSync(smokeExample)) {
+        fs.writeFileSync(smokeExample, `---
+name: Homepage loads
+---
+
+## Steps
+1. Navigate to http://localhost:3000
+2. Verify the page loads with a heading
+3. Verify there are no console errors
+`);
+        console.log(`  ${c.green}Created${c.reset} ${testplans}/smoke/homepage.md`);
+    }
+    // --- Claude Code skills ---
+    const claudeSkillsDir = path.join(process.cwd(), ".claude", "skills");
+    const testSkillDir = path.join(claudeSkillsDir, "test");
+    fs.mkdirSync(testSkillDir, { recursive: true });
+    fs.writeFileSync(path.join(testSkillDir, "SKILL.md"), `---
+name: test
+description: Run Bang On It! E2E tests locally. Pass test plan files or a filter as $ARGUMENTS (e.g. "testplans/smoke/" or "-t login"). With no arguments, runs all test plans.
+tools: Bash, Read
+---
+
+# Run E2E Tests
+
+Run Bang On It! end-to-end tests locally.
+
+**Arguments:** $ARGUMENTS
+
+## Instructions
+
+1. If $ARGUMENTS is empty, run all test plans:
+   \`\`\`bash
+   boi run --record
+   \`\`\`
+
+2. If $ARGUMENTS contains file paths or directories, run those:
+   \`\`\`bash
+   boi run $ARGUMENTS --record
+   \`\`\`
+
+3. If $ARGUMENTS contains a filter (e.g. "login", "checkout"), run with filter:
+   \`\`\`bash
+   boi run -t $ARGUMENTS --record
+   \`\`\`
+
+4. Wait for tests to complete. Report results and recording paths.
+
+5. If tests fail, read the test plan file and the output to diagnose the failure. Suggest whether the test plan needs updating or there's a real bug.
+`);
+    console.log(`  ${c.green}Created${c.reset} .claude/skills/test/SKILL.md`);
+    const createTestSkillDir = path.join(claudeSkillsDir, "create-test");
+    fs.mkdirSync(createTestSkillDir, { recursive: true });
+    fs.writeFileSync(path.join(createTestSkillDir, "SKILL.md"), `---
+name: create-test
+description: Create new Bang On It! test plan(s). Pass a description of what to test as $ARGUMENTS, or omit to auto-generate from git changes.
+tools: Bash, Read, Write, Glob, Grep
+---
+
+# Create Test Plan
+
+Create new Bang On It! test plan files.
+
+**What to test:** $ARGUMENTS
+
+## Instructions
+
+### Step 0: Determine what to test
+
+- If $ARGUMENTS is provided, use it as the description of what to test.
+- If $ARGUMENTS is empty, auto-discover from git changes:
+  1. Run \`git log master..HEAD --oneline\` and \`git diff master...HEAD --stat\` to see what changed on this branch.
+  2. If no branch divergence, run \`git diff HEAD --stat\` and \`git diff HEAD\` for uncommitted changes.
+  3. If still nothing, run \`git log -1 --format="%H %s"\` and \`git show HEAD --stat\` for the latest commit.
+  4. Analyze the changes and create test plan(s) covering them. Bug fixes get regression tests, new features get acceptance tests.
+  5. Skip changes that are already covered by existing test plans, pure refactors, docs, CI, or dependency updates.
+
+### Step 1: Determine which directory the test belongs in
+   - \`${testplans}/smoke/\` — Quick sanity checks (app loads, critical path works). Keep smoke tests minimal — they run on every commit so they must be fast. Only add here if it tests truly fundamental functionality. Prefer acceptance/ for most tests.
+   - \`${testplans}/acceptance/\` — Core user journeys and happy paths. This is the default for most new tests.
+   - \`${testplans}/regression/\` — Bug fixes and edge cases. Use when the description references a bug or issue.
+
+2. Read existing test plans in that directory to understand conventions:
+   \`\`\`bash
+   ls ${testplans}/smoke/ ${testplans}/acceptance/ ${testplans}/regression/
+   \`\`\`
+
+3. Read the codebase to understand what UI elements and flows are involved. Look at routes, components, and pages relevant to the test.
+
+4. Create the test plan file:
+   - Filename: kebab-case, e.g. \`password-reset.md\`
+   - Use this format:
+
+   \`\`\`markdown
+   ---
+   name: Descriptive test name
+   retries: 1
+   ---
+
+   ## Steps
+   1. Navigate to the relevant page
+   2. Perform the action being tested
+   3. Verify the expected outcome
+   \`\`\`
+
+5. Keep steps concise and actionable. Write from the user's perspective — describe what to click, type, and verify. Don't reference CSS selectors or implementation details.
+
+6. Output the path to the created file.
+`);
+    console.log(`  ${c.green}Created${c.reset} .claude/skills/create-test/SKILL.md`);
+    // --- CI setup ---
+    console.log("");
+    const setupCi = await p.askChoice("Set up GitHub Actions CI?", ["y", "n"], "y");
+    if (setupCi === "y") {
+        console.log("");
+        const baseImage = await p.ask("GitHub Actions runner", "ubuntu-latest");
+        const nodeVersion = await p.ask("Node.js version", "20");
+        const setupCommand = await p.ask("Setup command", "npm install && npm run build");
+        const startCommand = await p.ask("Command to start your web server", "npm start &");
+        const waitUrl = await p.ask("URL to wait for before testing", "http://localhost:3000");
+        const timeout = await p.ask("Test timeout in seconds", "300");
+        const tzNames = Object.keys(TIMEZONE_OFFSETS).join(", ");
+        const tz = await p.ask(`Timezone for full run (${tzNames})`, "us/eastern");
+        const utcOffset = TIMEZONE_OFFSETS[tz.toLowerCase()] ?? -5;
+        const fullUtcHour = localHourToUtc(18, utcOffset);
+        const timeoutMinutes = Math.ceil(parseInt(timeout) / 60) + 5;
+        const stepsYaml = `
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '${nodeVersion}'
+
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y xvfb libnss3 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 libxkbcommon0 libxcomposite1 libxdamage1 libxrandr2 libgbm1 libpango-1.0-0 libcairo2 libasound2
+
+      - name: Setup project
+        run: ${setupCommand}
+
+      - name: Start server
+        run: ${startCommand}
+
+      - name: Wait for server
+        run: npx wait-on ${waitUrl} --timeout 30000
+
+      - name: Install bangonit
+        run: npm install -g bangonit`;
+        const smokeWorkflow = `name: "Bang On It! Smoke Tests"
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+
+jobs:
+  smoke:
+    runs-on: ${baseImage}
+    timeout-minutes: ${timeoutMinutes}
+    env:
+      ANTHROPIC_API_KEY: \${{ secrets.ANTHROPIC_API_KEY }}
+${stepsYaml}
+
+      - name: Run smoke tests
+        run: |
+          xvfb-run --auto-servernum boi run ${testplans}/smoke/ \\
+            --timeout ${timeout} \\
+            --output bangonit-output.json --record
+
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: bangonit-smoke-results
+          path: |
+            bangonit-output.json
+            recordings/
+          if-no-files-found: ignore
+`;
+        const fullWorkflow = `name: "Bang On It! Full Tests"
+
+on:
+  schedule:
+    - cron: '0 ${fullUtcHour} * * *'
+  workflow_dispatch:
+
+jobs:
+  full:
+    runs-on: ${baseImage}
+    timeout-minutes: ${timeoutMinutes * 3}
+    env:
+      ANTHROPIC_API_KEY: \${{ secrets.ANTHROPIC_API_KEY }}
+${stepsYaml}
+
+      - name: Run all tests
+        run: |
+          xvfb-run --auto-servernum boi run \\
+            --timeout ${timeout} \\
+            --output bangonit-output.json --record
+
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: bangonit-full-results
+          path: |
+            bangonit-output.json
+            recordings/
+          if-no-files-found: ignore
+`;
+        const outDir = path.join(process.cwd(), ".github", "workflows");
+        fs.mkdirSync(outDir, { recursive: true });
+        const smokePath = path.join(outDir, "bangonit-smoke.yml");
+        fs.writeFileSync(smokePath, smokeWorkflow);
+        console.log(`\n  ${c.green}Created${c.reset} ${path.relative(process.cwd(), smokePath)}`);
+        const fullPath = path.join(outDir, "bangonit-full.yml");
+        fs.writeFileSync(fullPath, fullWorkflow);
+        console.log(`  ${c.green}Created${c.reset} ${path.relative(process.cwd(), fullPath)}`);
+        console.log(`\n  ${c.yellow}Required GitHub secret:${c.reset}`);
+        console.log(`  ${c.dim}  ANTHROPIC_API_KEY${c.reset} — your Anthropic API key`);
+        console.log(`\n  ${c.dim}Smoke tests run on every push/PR.${c.reset}`);
+        console.log(`  ${c.dim}Full tests run all test plans daily at 6pm ${tz} (${fullUtcHour}:00 UTC).${c.reset}`);
+    }
+    p.close();
+    console.log("");
+}
+async function run(argv, config) {
+    loadEnv();
+    // Config can provide the API key (supports ${ENV_VAR} interpolation)
+    if (config.anthropic_api_key && !process.env.ANTHROPIC_API_KEY) {
+        process.env.ANTHROPIC_API_KEY = config.anthropic_api_key;
+    }
+    if (!process.env.ANTHROPIC_API_KEY) {
+        die("Error: ANTHROPIC_API_KEY is not set.\nSet it in your environment, .env file, or .bangonit/config.toml.");
+    }
+    const recordingsDir = config.recordings_dir
+        ? path.resolve(process.cwd(), config.recordings_dir)
+        : path.join(process.cwd(), "recordings");
+    // Validate test plan files exist before launching anything
+    for (const file of argv.files) {
+        const absPath = path.isAbsolute(file) ? file : path.join(process.cwd(), file);
+        if (!fs.existsSync(absPath)) {
+            die(`Test plan file not found: ${file}`);
+        }
+    }
+    // Discover test plans if no files/plan specified
+    const files = [...argv.files];
+    if (files.length === 0 && !argv.plan && config.testplans) {
+        const testDirPath = path.resolve(process.cwd(), config.testplans);
+        const plans = findTestPlans(testDirPath, argv.filter);
+        if (plans.length > 0) {
+            files.push(...plans);
+        }
+        else if (argv.filter) {
+            die(`No test plans matching "${argv.filter}" found in ${config.testplans}/`);
+        }
+    }
+    else if (files.length === 0 && !argv.plan && argv.filter) {
+        die(`--filter requires a testplans directory configured in .bangonit/config.toml`);
+    }
+    // Hint when launching interactive UI with no config
+    if (files.length === 0 && !argv.plan) {
+        if (!config.testplans) {
+            console.log(`${c.dim}No test plans specified. Launching interactive UI.${c.reset}`);
+            console.log(`${c.dim}Tip: Run ${c.reset}boi init${c.dim} to set up a config file, or pass test plan files directly.${c.reset}\n`);
+        }
+    }
+    // Build structured args for Electron (passed via BANGONIT_ARGS env var)
+    const electronArgs = args_1.electronArgsSchema.parse({
+        testPlanFiles: files,
+        headless: argv.headless,
+        exit: argv.exit,
+        json: argv.json,
+        console: argv.console,
+        record: argv.record,
+        retries: argv.retries ?? 0,
+        output: argv.output || null,
+        plan: argv.plan || null,
+        prompt: argv.prompt || null,
+        concurrency: argv.concurrency ?? 1,
+        timeout: argv.timeout ?? 0,
+        cwd: process.cwd(),
+        recordingsDir: argv.record ? recordingsDir : null,
+    });
+    const PORT = await getFreePort();
+    fs.mkdirSync(LOGS_DIR, { recursive: true });
+    const nextDir = path.join(WEBAPP_DIR, ".next");
+    const isBuilt = fs.existsSync(nextDir);
+    let webappProc;
+    if (isBuilt) {
+        webappProc = (0, child_process_1.spawn)("npx", ["next", "start", "-p", String(PORT)], {
+            cwd: WEBAPP_DIR,
+            env: { ...process.env, NODE_ENV: "production" },
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+    }
+    else {
+        webappProc = (0, child_process_1.spawn)("npx", ["next", "dev", "-p", String(PORT)], {
+            cwd: WEBAPP_DIR,
+            env: { ...process.env },
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+    }
+    const webappLog = fs.createWriteStream(path.join(LOGS_DIR, "webapp.log"));
+    webappProc.stdout.pipe(webappLog);
+    webappProc.stderr.pipe(webappLog);
+    let webappCrashed = false;
+    webappProc.on("exit", (code) => {
+        if (!webappCrashed && code !== null && code !== 0) {
+            webappCrashed = true;
+            die(`Webapp server crashed (exit code ${code}). Check logs/webapp.log for details.`);
+        }
+    });
+    const cleanup = () => {
+        webappCrashed = true; // suppress crash message during normal shutdown
+        try {
+            webappProc.kill();
+        }
+        catch { }
+    };
+    process.on("exit", cleanup);
+    process.on("SIGINT", () => { cleanup(); process.exit(1); });
+    process.on("SIGTERM", () => { cleanup(); process.exit(1); });
+    await waitForPort(PORT);
+    const electronMain = path.join(DESKTOP_DIR, "dist", "main", "index.js");
+    if (!fs.existsSync(electronMain)) {
+        try {
+            (0, child_process_1.execSync)("npx tsc", { cwd: DESKTOP_DIR, stdio: "inherit" });
+        }
+        catch {
+            cleanup();
+            die("Failed to compile Electron app");
+        }
+    }
+    let electronPath;
+    try {
+        electronPath = require(path.join(DESKTOP_DIR, "node_modules", "electron"));
+    }
+    catch {
+        try {
+            electronPath = require("electron");
+        }
+        catch {
+            cleanup();
+            die("Error: electron not found. Run `npm install` in app/desktopapp.");
+        }
+    }
+    const electronProc = (0, child_process_1.spawn)(electronPath, ["."], {
+        cwd: DESKTOP_DIR,
+        env: {
+            ...process.env,
+            [args_1.ELECTRON_ARGS_ENV]: JSON.stringify(electronArgs),
+            WEBAPP_URL: `http://localhost:${PORT}/app`,
+            NODE_ENV: process.env.NODE_ENV || "production",
+        },
+        stdio: ["inherit", "inherit", "ignore"],
+    });
+    electronProc.on("exit", async (code) => {
+        // Upload recordings to S3 if configured
+        if (config.s3?.bucket && argv.record) {
+            if (fs.existsSync(recordingsDir)) {
+                const dirs = fs.readdirSync(recordingsDir).filter((d) => fs.existsSync(path.join(recordingsDir, d, "index.html")));
+                const s3Prefix = config.s3.prefix || "bangonit";
+                for (const dir of dirs) {
+                    const localPath = path.join(recordingsDir, dir);
+                    try {
+                        const url = await uploadToS3(localPath, {
+                            bucket: config.s3.bucket,
+                            prefix: `${s3Prefix}/${dir}`,
+                            region: config.s3.region,
+                            endpoint: config.s3.endpoint,
+                            accessKey: config.s3.access_key,
+                            secretKey: config.s3.secret_key,
+                        });
+                        console.log(`\n${c.green}Recording:${c.reset} ${c.cyan}${url}${c.reset}`);
+                    }
+                    catch (err) {
+                        console.error(`\n${c.red}Failed to upload recording:${c.reset} ${err.message}`);
+                    }
+                }
+            }
+        }
+        cleanup();
+        process.exit(code ?? 1);
+    });
+}
+// --- main ---
+const ciDefaults = is_ci_1.default ? { headless: true, exit: true } : {};
+(0, yargs_1.default)((0, helpers_1.hideBin)(process.argv))
+    .scriptName("boi")
+    .usage("Usage: $0 <command> [options]")
+    .command("init", "Set up Bang On It! (config, test plans, and optionally CI)", {}, () => { initProject(); })
+    .command(["run [files..]", "$0"], "Run test plans (or launch interactive UI)", (y) => y
+    .positional("files", { type: "string", array: true, default: [], describe: "Test plan files" })
+    .option("filter", { alias: "t", type: "string", describe: "Filter test plans by name substring" })
+    .option("config", { type: "string", describe: "Path to config file (default: .bangonit/config.toml)" })
+    .option("plan", { type: "string", describe: "Inline test plan (instead of file)" })
+    .option("prompt", { type: "string", describe: "Additional instructions appended to test plan" })
+    .option("record", { type: "boolean", default: false, describe: "Record session replay" })
+    .option("retries", { type: "number", describe: "Retry failed tests N times (overrides test plan frontmatter)" })
+    .option("headless", { type: "boolean", default: ciDefaults.headless ?? false, describe: "Run without showing the browser window" })
+    .option("exit", { type: "boolean", default: ciDefaults.exit ?? false, describe: "Exit immediately after tests complete" })
+    .option("json", { type: "boolean", default: false, describe: "Stream NDJSON events to stdout" })
+    .option("console", { type: "boolean", default: false, describe: "Forward browser console logs to stdout" })
+    .option("output", { type: "string", describe: "Write JSON results to file" })
+    .option("concurrency", { type: "number", describe: "Number of parallel agents (default: 1)" })
+    .option("timeout", { type: "number", describe: "Test timeout in seconds (0 = none)" }), (argv) => {
+    const config = loadConfig(argv.config);
+    run({
+        files: argv.files,
+        filter: argv.filter,
+        plan: argv.plan,
+        prompt: argv.prompt,
+        record: argv.record,
+        retries: argv.retries,
+        headless: argv.headless,
+        exit: argv.exit,
+        json: argv.json,
+        console: argv.console,
+        output: argv.output,
+        concurrency: argv.concurrency,
+        timeout: argv.timeout,
+    }, config);
+})
+    .example("$0 run test.md", "Run a test plan file")
+    .example("$0 run --plan 'test login flow'", "Run an inline test plan")
+    .example("$0 run -t checkout", "Run test plans matching 'checkout'")
+    .example("$0 run", "Launch interactive UI")
+    .example("$0 init", "Set up config, test plans, and CI")
+    .strict()
+    .help()
+    .alias("h", "help")
+    .parse();