bangonit 0.2.2 → 0.3.1

package/README.md

@@ -1,6 +1,27 @@
 # Bang On It!
 
-Bang On It! bangs on your apps so you don't have to. It's an AI-powered E2E testing tool that launches a real browser, reads your test plan, and executes it autonomously — clicking, typing, navigating, and verifying everything works.
+Bang On It! bangs on your apps so you don't have to.
+
+Bang On It! replaces annoying manual QA and flakey end-to-end tests with a CLI-friendly AI agent that launches a real browser, reads your test plan, and executes it autonomously — clicking, typing, navigating, and verifying everything works.
+
+## Quick Start
+
+```bash
+
+# Run a single test
+npx bangonit run \
+  --plan "Go to localhost:3000, login as test@test.com (password: 12345), \
+          and click all the buttons in the dashboard and make sure they work"
+
+# Run a suite of test plans
+npx bangonit run testplans/*.md --concurrency 3
+
+# Record a video of your test run in the recordings/ directory
+npx bangonit run testplans/*.md --record
+
+# Initialize your project with full CI integration and S3 video recording storage
+npx bangonit init
+```
 
 ## Why This Matters
 
@@ -36,7 +57,7 @@ npm install -g bangonit
 
 The package provides three aliases: `bangonit`, `bang-on-it`, and `boi`.
 
-## Quick Start
+## Getting started
 
 ```bash
 # Launch the interactive UI
@@ -47,20 +68,20 @@ boi run testplans/checkout-flow.md
 
 # Run an inline test
 boi run --plan "Go to my-app.com, sign up with a test account, and verify the dashboard loads"
-
-# Auto-generate tests from your git changes
-boi run --auto
 ```
 
-### With a config file
+### Set up a project
 
 ```bash
-# Create a .bangonit/config.toml config file
+# Creates config, test plan directories, and optionally GitHub Actions CI
 boi init
 
-# Run all test plans in the configured directory
+# Run all test plans
 boi run
 
+# Run just the smoke tests
+boi run testplans/smoke/
+
 # Filter test plans by name
 boi run -t checkout
 ```
@@ -71,9 +92,10 @@ Run `boi init` to create a `.bangonit/config.toml` in your project root:
 
 ```toml
 testplans = "testplans"
-anthropic_api_key = "${ANTHROPIC_API_KEY}"  # reference env vars with ${VAR}
+# recordings_dir = "recordings"  # default
+# anthropic_api_key = "${ANTHROPIC_API_KEY}"
 
-# Upload test recordings to S3 (or any S3-compatible provider)
+# Optional: upload recordings to S3 (or any S3-compatible provider)
 [s3]
 bucket = "my-recordings"
 region = "us-east-1"
@@ -83,11 +105,13 @@ prefix = "bangonit"
 # secret_key = "${AWS_SECRET_ACCESS_KEY}"
 ```
 
-All fields are optional. The config is loaded from `.bangonit/config.toml` in the current directory by default, or from a custom path with `--config <path>`.
+All fields are optional. The config is loaded from `.bangonit/config.toml` in the current directory (or any parent up to the repo root) by default, or from a custom path with `--config <path>`.
 
-Any string value supports `${ENV_VAR}` interpolation, so you can reference environment variables without committing secrets. The `[s3]` section configures where test recordings are uploaded and works with any S3-compatible provider — set `endpoint` for DigitalOcean Spaces, Backblaze B2, MinIO, etc.
+Any string value supports `${ENV_VAR}` interpolation, so you can reference environment variables without committing secrets.
 
-When `testplans` is set and you run `boi run` without specifying files, it automatically discovers `.md` files in that directory. Without a config file, `boi run` launches the interactive UI.
+- **`testplans`** — directory of `.md` test plan files. When set, `boi run` auto-discovers plans. Without it, `boi run` launches the interactive UI.
+- **`recordings_dir`** — where session recordings are written (default: `recordings`).
+- **`[s3]`** — optional S3 upload for recordings. Works with any S3-compatible provider — set `endpoint` for DigitalOcean Spaces, Backblaze B2, MinIO, etc.
 
 ## How It Works
 
@@ -103,7 +127,25 @@ No selectors. No page objects. No flaky waits. Just describe what to test and le
 
 ## Test Plans
 
-Test plans are Markdown files. Put them in your `testplans/` directory (or wherever `.bangonit/config.toml` points).
+Test plans are Markdown files. `boi init` creates a recommended two-tier structure:
+
+```
+testplans/
+  smoke/          # is the app alive? — run on every push/PR
+    homepage.md
+    login.md
+  acceptance/     # does the app do what it should? — core user journeys
+    checkout.md
+    onboarding.md
+  regression/     # did we break something? — bug fixes, edge cases
+    issue-123.md
+```
+
+- **Smoke** tests should be quick and focused — verify critical paths still work.
+- **Acceptance** tests cover core user journeys and happy paths.
+- **Regression** tests lock down bug fixes and edge cases so they don't recur.
+
+Smoke tests run on every commit. The daily full run discovers everything recursively (smoke + acceptance + regression). Run `boi run testplans/smoke/` to run just the smoke tests.
 
 ```markdown
 ---
@@ -111,17 +153,15 @@ name: Add Todos
 retries: 1
 ---
 
-## Setup
-Navigate to http://localhost:3000
-
-## Test Steps
-1. Verify the page loads with a heading and input field
-2. Type "Buy groceries" and press Enter
-3. Verify the todo appears in the list
-4. Verify the footer shows "1 item left"
+## Steps
+1. Navigate to http://localhost:3000
+2. Verify the page loads with a heading and input field
+3. Type "Buy groceries" and press Enter
+4. Verify the todo appears in the list
+5. Verify the footer shows "1 item left"
 ```
 
-The `---` frontmatter is optional. `name` sets the display name, `retries` enables auto-retry on failure.
+The `---` frontmatter is optional. `name` sets the display name, `retries` enables auto-retry on failure. You can also set retries for all tests via `--retries N` on the CLI (frontmatter takes precedence).
 
 ## Filtering Tests
 
@@ -139,24 +179,16 @@ boi run --filter checkout
 
 You can customize the AI agent's behavior per-project by creating a `.bangonit/system_prompt.md` file in your project root. This content is prepended to the agent's system prompt for all test runs in that directory.
 
-## Session Recordings
-
-Record test runs for debugging and CI artifacts:
+## Claude Code Skills
 
-```bash
-boi run testplans/checkout.md --record
-```
+`boi init` installs two [Claude Code](https://claude.com/claude-code) skills into your project:
 
-This creates a `recordings/{timestamp}/` directory with:
-- **`index.html`** — self-contained replay viewer (open in any browser)
-- **`clips/`** — WebM video clips of browser interactions with cursor composited in
-- **`data.json`** — timeline events, messages, console logs
+- **`/test`** — Run tests locally. Pass file paths, directories, or a filter (e.g. `/test testplans/smoke/`, `/test -t login`).
+- **`/create-test`** — Generate a new test plan from a description (e.g. `/create-test user can reset their password`). Reads your codebase to write accurate steps and places the file in the right directory.
 
-Upload recordings to S3 (or any S3-compatible provider) via config or CLI flag:
+## Session Recordings
 
-```bash
-boi run --record --s3-bucket my-bucket
-```
+Record test runs with `--record`. Each recording produces a self-contained HTML replay viewer. Configure where they're saved with `recordings_dir` in your config, and optionally upload to S3 via the `[s3]` config section.
 
 ## CLI Reference
 
@@ -165,19 +197,18 @@ Usage: boi <command> [options]
 
 Commands:
   run [files...] [options]   Run test plans (or launch interactive UI)
-  init                       Create a .bangonit/config.toml config file
-  init-ci                    Generate a GitHub Actions workflow
+  init                       Set up config, test plans, and optionally CI
 
 Run options:
   -t, --filter <text>        Filter test plans by name substring
   --config <path>            Path to config file (default: .bangonit/config.toml)
   --plan <text>              Inline test plan (instead of file)
-  --auto                     Auto-generate test plan from git state
+
   --prompt <text>            Additional instructions appended to test plan
-  --record                   Record session replay to recordings/ directory
-  --s3-bucket <bucket>       Upload recordings to S3 (overrides config)
+  --record                   Record session replay
+  --retries <n>              Retry failed tests N times
   --headless                 Run without showing the browser window
-  --exit                     Exit immediately after tests complete (for CI)
+  --exit                     Exit immediately after tests complete
   --json                     Stream NDJSON events to stdout
   --console                  Forward browser console logs to stdout
   --output <file>            Write JSON results to file
@@ -186,26 +217,16 @@ Run options:
   --help                     Show this help message
 ```
 
-## CI Usage
-
-Generate a GitHub Actions workflow:
-
-```bash
-boi init-ci
-```
+In CI environments, `--headless` and `--exit` default to `true` automatically.
 
-Or run manually in CI:
+## CI Usage
 
-```bash
-# Headless mode with timeout, exit on completion
-boi run --headless --exit --timeout 120
+`boi init` optionally generates two GitHub Actions workflows:
 
-# JSON output for parsing
-boi run --headless --exit --json
+- **Smoke tests** (`bangonit-smoke.yml`) — runs `testplans/smoke/` on every push and PR
+- **Full tests** (`bangonit-full.yml`) — runs all test plans daily at 6pm local time
 
-# Record for artifacts
-boi run --headless --exit --record
-```
+In CI, `--headless` and `--exit` are enabled automatically.
 
 ## Multiple Tests
 

package/app/desktopapp/dist/main/index.js

@@ -43,154 +43,16 @@ const path = __importStar(require("path"));
 const fs = __importStar(require("fs"));
 const ipc_1 = require("./ipc");
 const tabs_1 = require("./tabs");
+const args_1 = require("../shared/args");
 let mainWindow = null;
+// --- Parse args from env (set by CLI) ---
 function parseArgs() {
-    const args = process.argv.slice(2).filter((a) => !a.startsWith("--remote-debugging-port"));
-    const result = {
-        testPlanFiles: [],
-        headless: false,
-        exit: false,
-        json: false,
-        console: false,
-        record: false,
-        auto: false,
-        output: null,
-        plan: null,
-        prompt: null,
-        concurrency: 1,
-        timeout: 0,
-        cwd: process.cwd(),
-    };
-    if (args.includes("--help") || args.includes("-h")) {
-        console.log(`Usage: boi run [test-plan-files...] [options]
-
-Options:
-  --plan <text>         Inline test plan (instead of file)
-  --auto                Auto-generate test plan from git state
-  --prompt <text>       Additional instructions appended to test plan
-  --record              Record session replay to recordings/ directory
-  --headless            Run without showing the browser window
-  --exit                Exit immediately after tests complete (for CI)
-  --json                Stream NDJSON events to stdout
-  --console             Forward browser console logs to stdout
-  --output <file>       Write JSON results to file
-  --concurrency <n>     Number of parallel agents (default: 1)
-  --timeout <seconds>   Test timeout in seconds (0 = none)
-  --cwd <dir>           Working directory (default: current)
-  --help                Show this help message`);
-        process.exit(0);
-    }
-    let i = 0;
-    // Skip "run" subcommand if present
-    if (args[i] === "run")
-        i++;
-    while (i < args.length) {
-        const arg = args[i];
-        if (arg === "--headless") {
-            result.headless = true;
-        }
-        else if (arg === "--exit") {
-            result.exit = true;
-        }
-        else if (arg === "--json") {
-            result.json = true;
-        }
-        else if (arg === "--console") {
-            result.console = true;
-        }
-        else if (arg === "--record") {
-            result.record = true;
-        }
-        else if (arg === "--auto") {
-            result.auto = true;
-        }
-        else if (arg === "--output" && i + 1 < args.length) {
-            result.output = args[++i];
-        }
-        else if (arg === "--plan" && i + 1 < args.length) {
-            result.plan = args[++i];
-        }
-        else if (arg === "--prompt" && i + 1 < args.length) {
-            result.prompt = args[++i];
-        }
-        else if (arg === "--concurrency" && i + 1 < args.length) {
-            result.concurrency = Math.max(1, parseInt(args[++i], 10) || 1);
-        }
-        else if (arg === "--timeout" && i + 1 < args.length) {
-            result.timeout = Math.max(0, parseInt(args[++i], 10) || 0);
-        }
-        else if (arg === "--cwd" && i + 1 < args.length) {
-            result.cwd = args[++i];
-        }
-        else if (!arg.startsWith("-")) {
-            result.testPlanFiles.push(arg);
-        }
-        i++;
+    const raw = process.env[args_1.ELECTRON_ARGS_ENV];
+    if (!raw) {
+        console.error("Error: BANGONIT_ARGS environment variable not set. Run via the boi CLI.");
+        process.exit(1);
     }
-    return result;
-}
-// --- Auto-generate test plan from git state ---
-async function generateTestPlan(cwd) {
-    const { execSync } = require("child_process");
-    const exec = (cmd) => {
-        try {
-            return execSync(cmd, { cwd, encoding: "utf-8", timeout: 10000 }).trim();
-        }
-        catch {
-            return "";
-        }
-    };
-    const diff = exec("git diff") + "\n" + exec("git diff --cached");
-    const status = exec("git status --short");
-    if (diff.trim() || status.trim()) {
-        return `## Auto-generated test plan from uncommitted changes
-
-Analyze the following git changes and generate a comprehensive test plan. Then execute each test step.
-
-### Git Status
-\`\`\`
-${status}
-\`\`\`
-
-### Git Diff
-\`\`\`
-${diff.slice(0, 8000)}
-\`\`\`
-
-Generate test steps that verify the changes work correctly, then execute them.`;
-    }
-    const logDiff = exec("git log master..HEAD --oneline");
-    const codeDiff = exec("git diff master...HEAD");
-    if (logDiff || codeDiff) {
-        return `## Auto-generated test plan from branch divergence
-
-Analyze the following commits diverging from master and generate a comprehensive test plan. Then execute each test step.
-
-### Commits
-\`\`\`
-${logDiff}
-\`\`\`
-
-### Diff from master
-\`\`\`
-${codeDiff.slice(0, 8000)}
-\`\`\`
-
-Generate test steps that verify these changes work correctly, then execute them.`;
-    }
-    const lastCommit = exec("git log -1 --format='%H %s'");
-    const lastDiff = exec("git show HEAD --stat");
-    return `## Auto-generated test plan from latest commit
-
-No test plan provided and no changes unmerged to master. Generating test plan from latest commit.
-
-### Latest Commit
-\`\`\`
-${lastCommit}
-${lastDiff}
-\`\`\`
-
-Generate test steps that verify this commit works correctly, then execute them.`;
+    return args_1.electronArgsSchema.parse(JSON.parse(raw));
 }
 const cliArgs = parseArgs();
 function parseFrontmatter(content) {
@@ -321,7 +183,8 @@ async function createWindow() {
     // Create recordings directory if --record
     if (cliArgs.record) {
         const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
-        const recordDir = path.join(cliArgs.cwd, "recordings", timestamp);
+        const baseDir = cliArgs.recordingsDir || path.join(cliArgs.cwd, "recordings");
+        const recordDir = path.join(baseDir, timestamp);
         fs.mkdirSync(recordDir, { recursive: true });
         (0, ipc_1.setRunDir)(recordDir);
         if (!cliArgs.json)
@@ -361,26 +224,12 @@ async function createWindow() {
                     agentIndex: i,
                     testPlan: parsed[i].body,
                     name: parsed[i].frontmatter.name || names[i],
-                    retries: parsed[i].frontmatter.retries || 0,
+                    retries: parsed[i].frontmatter.retries ?? cliArgs.retries,
                     extraPrompt: cliArgs.prompt || undefined,
                     record: cliArgs.record || undefined,
                 });
             }
         }
-        else if (cliArgs.auto) {
-            // Auto-generate from git state
-            const generated = await generateTestPlan(cliArgs.cwd);
-            const fullPlan = cliArgs.prompt
-                ? `${generated}\n\n## Additional Instructions\n${cliArgs.prompt}`
-                : generated;
-            expectedResults = 1;
-            mainWindow.webContents.send("test-plan", {
-                agentIndex: 0,
-                testPlan: fullPlan,
-                name: "auto-generated",
-                record: cliArgs.record || undefined,
-            });
-        }
         // No test plans provided — interactive UI will show the prompt screen
         // Start timeout if specified
         if (cliArgs.timeout > 0) {

package/app/desktopapp/dist/main/ipc.js

@@ -206,26 +206,6 @@ function registerIpcHandlers() {
         store.delete(`agentSessions.${agentId}`);
         (0, tabs_1.destroyContext)(agentId);
     });
-    // --- Bash (per-agent) ---
-    electron_1.ipcMain.handle("bash-exec", async (_, { agentId, command }) => {
-        const ctx = (0, tabs_1.getOrCreateContext)(agentId);
-        if (!ctx.bashInstance) {
-            const { Bash, OverlayFs } = await Promise.resolve().then(() => __importStar(require("just-bash")));
-            const overlay = new OverlayFs({ root: bangerCwd });
-            const cwd = overlay.getMountPoint();
-            ctx.bashInstance = new Bash({ fs: overlay, cwd });
-            try {
-                ctx.bashInstance.fs.mkdirSync("/home/user/downloads");
-            }
-            catch { }
-            ctx.bashFs = ctx.bashInstance.fs;
-            ctx.bashCwd = cwd;
-        }
-        const result = await ctx.bashInstance.exec(command, { cwd: ctx.bashCwd });
-        return [result.stdout, result.stderr ? `stderr: ${result.stderr}` : "", `exit code: ${result.exitCode}`]
-            .filter(Boolean)
-            .join("\n");
-    });
     electron_1.ipcMain.handle("clear-partition", async (_, agentId) => {
         const partitionName = `persist:agent-${agentId}`;
         const ses = electron_1.session.fromPartition(partitionName);

package/app/desktopapp/dist/main/preload.js

@@ -14,8 +14,6 @@ contextBridge.exposeInMainWorld("bangonit", {
     getAgentSession: (agentId) => ipcRenderer.invoke("get-agent-session", agentId),
     setAgentSession: (agentId, session) => ipcRenderer.invoke("set-agent-session", { agentId, session }),
     deleteAgentSession: (agentId) => ipcRenderer.invoke("delete-agent-session", agentId),
-    // Bash (per-agent)
-    bashExec: (agentId, command) => ipcRenderer.invoke("bash-exec", { agentId, command }),
     // --- Low-level browser primitives ---
     // CDP: send a raw CDP command to the active tab
     cdpSend: (agentId, method, params) => ipcRenderer.invoke("cdp-send", { agentId, method, params }),

package/app/desktopapp/dist/main/tabs.js

@@ -53,12 +53,9 @@ function getOrCreateContext(agentId) {
     const ctx = {
         tabs: new Map(),
         activeTabId: null,
-        bashInstance: null,
-        bashCwd: null,
         nextPopupId: 10000,
         downloadsDir: null,
         downloadSessionsSetup: new WeakSet(),
-        bashFs: null,
     };
     agentContexts.set(agentId, ctx);
     return ctx;
@@ -126,13 +123,6 @@ function setupDownloads(ctx, wc) {
         item.on("done", (_, state) => {
             entry.bytes = item.getReceivedBytes();
             entry.state = state === "completed" ? "completed" : "failed";
-            if (state === "completed" && ctx.bashFs) {
-                try {
-                    const data = fs.readFileSync(savePath);
-                    ctx.bashFs.writeFileSync(`/home/user/downloads/${filename}`, data);
-                }
-                catch { }
-            }
         });
     });
 }

package/app/desktopapp/dist/shared/args.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ELECTRON_ARGS_ENV = exports.electronArgsSchema = void 0;
+const zod_1 = require("zod");
+exports.electronArgsSchema = zod_1.z.object({
+    testPlanFiles: zod_1.z.array(zod_1.z.string()),
+    headless: zod_1.z.boolean(),
+    exit: zod_1.z.boolean(),
+    json: zod_1.z.boolean(),
+    console: zod_1.z.boolean(),
+    record: zod_1.z.boolean(),
+    retries: zod_1.z.number(),
+    output: zod_1.z.string().nullable(),
+    plan: zod_1.z.string().nullable(),
+    prompt: zod_1.z.string().nullable(),
+    concurrency: zod_1.z.number(),
+    timeout: zod_1.z.number(),
+    cwd: zod_1.z.string(),
+    recordingsDir: zod_1.z.string().nullable(),
+});
+exports.ELECTRON_ARGS_ENV = "BANGONIT_ARGS";

package/app/desktopapp/package.json

@@ -13,7 +13,7 @@
   },
   "dependencies": {
     "electron-store": "^8.1.0",
-    "just-bash": "^2.13.1"
+    "zod": "^3.25.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",