lastlight 0.1.8 → 0.2.0

package/skills/README.md

@@ -0,0 +1,40 @@
+# Skills
+
+Skill directories staged into the sandbox per workflow phase (and a subset into
+chat). A phase declares `skill: <name>` / `skills: [<name>, …]`; the runner
+stages the whole directory into `<agentCwd>/.agents/skills/<name>/` and
+pi-coding-agent surfaces `name` + `description` in the system prompt. The agent
+reads SKILL.md (and any `references/`) on demand via its `read` tool.
+
+**Authoring guide:** [`docs/agents/writing-skills.md`](../docs/agents/writing-skills.md)
+— the loading contract, the craft, and house conventions. Read it before adding
+or editing a skill.
+
+## Skills
+
+| Skill | Used by | Purpose |
+|-------|---------|---------|
+| [`chat`](chat/) | chat | Conversational assistant for Slack/Discord threads — answer repo/PR/issue questions, guide to natural-language triggers. |
+| [`issue-triage`](issue-triage/) | `issue-triage.yaml`, chat | Move issues through the canonical triage state machine — categorise, label, dedupe, manage stale, write agent briefs. |
+| [`issue-comment`](issue-comment/) | `issue-comment.yaml` | Handle non-build maintainer comments on issues/PRs — close, label, answer briefly, redirect build requests. |
+| [`pr-review`](pr-review/) | `pr-review.yaml`, chat | Review a PR with structured, tiered feedback; build and test from the local checkout; post a formal review. |
+| [`pr-comment`](pr-comment/) | `pr-comment.yaml` | Answer a maintainer's question about an open PR with concrete, code-cited evidence (not a full review). |
+| [`repo-health`](repo-health/) | `repo-health.yaml`, chat | Generate a repository health report — open issues, PR backlog, CI status, action items. |
+| [`security-review`](security-review/) | `security-review.yaml` | Diff-scoped SDLC security review; file one dated summary issue with a task-list of findings. |
+| [`security-feedback`](security-feedback/) | `security-feedback.yaml` | Process a maintainer's comment on a security scan summary — break findings into issues or record suppressions. |
+| [`building`](building/) | build (executor, reviewer), `pr-fix.yaml`, `pr-review.yaml` | Shared craft: install-first + package-manager detection, the test/lint/typecheck gate, and TDD discipline in the sandbox. |
+| [`code-review`](code-review/) | build (reviewer), `pr-review.yaml` | Shared rubric: finding tiers (Critical/Important/Suggestions/Nits) and what-to-check. Referenced by both the branch-diff reviewer and the PR reviewer. |
+| [`verify`](verify/) | `verify.yaml` | Test a behaviour claim as an investigator — CONFIRMED / REFUTED / INCONCLUSIVE with bash-captured evidence. |
+| [`qa-test`](qa-test/) | `qa-test.yaml` | Run an automated QA flow against a CLI or locally-served app and report step-level pass/fail with evidence. |
+| [`browser-qa`](browser-qa/) | `verify.yaml`, `qa-test.yaml`, `demo.yaml` | Drive a real headless browser against a locally-served web UI and capture screenshot (and, for `demo`, video) evidence. Gated to the docker QA image. |
+| [`demo`](demo/) | `demo.yaml` | Record a short demo VIDEO of a PR/feature — drive the web UI, screen-record, and composite a titled, size-capped mp4 with ffmpeg. Gated to the docker QA image. |
+
+`building` and `code-review` are **shared building blocks** — referenced by the
+build-cycle prompts (`workflows/prompts/*.md`) and the PR skills so the install
+gate and review rubric live in one place. They're staged alongside the phase's
+primary skill/prompt and read on demand.
+
+The live set is enforced at startup: `validateAssets()` (`src/workflows/loader.ts`)
+resolves every workflow `skill:` reference and `CHAT_SKILL_NAMES`
+(`src/engine/chat-skills.ts`). Adding a skill here does nothing until a phase or
+the chat list references it.

package/skills/browser-qa/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: browser-qa
+description: Drive a real headless browser against a locally-served web UI and capture screenshot evidence, reporting step-level PASS/FAIL/BLOCKED with extracted DOM text and console errors. Use when a phase on the docker QA image must exercise a rendered UI and attach screenshots — it complements the text-evidence verify/qa-test skills.
+version: 1.0.0
+tags: [browser, qa, screenshots, evidence]
+---
+
+# Browser QA
+
+Drive a web UI with a real headless Chromium and report **step-level
+pass/fail with evidence**: extracted DOM text, assertion results, console
+errors, and screenshot files. The deliverable is a QA report — partial
+coverage with documented failures is the expected output.
+
+This skill is the **browser/screenshot path** that `verify` and `qa-test`
+scope out to "a separate docker-gated capability". It only works on the
+`lastlight-sandbox-qa:latest` docker image, which bakes in Playwright +
+Chromium. You have bash + file tools but **no vision** — you reason over the
+driver's JSON stdout (extracted text, assertion results, console errors).
+The PNG screenshots are **human evidence only**; you never see them.
+
+This skill uses the **building** skill for installing dependencies and
+starting the repo's dev-server.
+
+## When this applies
+
+A phase running on the docker QA image whose target is a **web app** the
+repo serves on `localhost` and where rendered-UI behaviour or visual
+evidence matters. For a CLI or a curl-able API, use `qa-test`/`verify`
+instead — don't launch a browser you don't need.
+
+## FIRST — probe for a browser
+
+The driver lives in this skill's bundle at
+`<skill-dir>/scripts/agent-browser.mjs`. Resolve `<skill-dir>` from the
+available-skills catalogue (it gives the absolute staged path of this
+skill); do not assume a relative path from `$PWD` — the agent's cwd is the
+checked-out repo, the bundle is a sibling.
+
+Run the runtime probe before anything else:
+
+```bash
+node <skill-dir>/scripts/agent-browser.mjs doctor
+```
+
+- Exit 0 with `{"ok":true,"chromium":"..."}` → Chromium is available; proceed.
+- Exit non-zero (e.g. `playwright not available …`, or no Chromium — the lean
+  default image, or a gondolin run) → **DO NOT attempt browser QA.** Fall back
+  to the text path (`verify`/`qa-test` style: curl the dev-server, capture
+  stdout) and **say in your report that the browser path was unavailable** and
+  you used the text path.
+
+## Start the app
+
+Follow the **building** skill to install dependencies, then start the repo's
+dev-server **in the background** and wait until it is listening on
+`localhost:PORT` (poll with `curl` until it answers). Note the port — you
+pass it as `--base-url`.
+
+## Author a flow
+
+Write a `flow.json` describing the QA flow. Shape:
+
+```json
+{
+  "baseUrl": "http://localhost:3000",
+  "viewport": { "width": 1280, "height": 800 },
+  "steps": [
+    { "name": "home", "goto": "/" },
+    { "click": "text=Login" },
+    { "fill": ["#email", "a@b.com"] },
+    { "type": ["#password", "hunter2"] },
+    { "press": "Enter" },
+    { "waitFor": "#dashboard" },
+    { "assertText": "Welcome" },
+    { "text": "h1" },
+    { "screenshot": "after-login" }
+  ]
+}
+```
+
+Step keys (a step may combine an action **plus** a trailing `screenshot`):
+
+| Key          | Value                | Effect                                                            |
+|--------------|----------------------|------------------------------------------------------------------|
+| `goto`       | path or URL          | Navigate (resolved against `baseUrl`). **Failure is fatal.**      |
+| `click`      | selector             | Click the element.                                               |
+| `fill`       | `[selector, value]`  | Set an input's value.                                            |
+| `type`       | `[selector, value]`  | Type key-by-key into an input.                                   |
+| `press`      | key (e.g. `Enter`)   | Press a keyboard key.                                            |
+| `waitFor`    | selector             | Wait until the element is visible (~10s timeout).                |
+| `assertText` | string               | Pass if the text is visible anywhere on the page; else step FAIL.|
+| `text`       | selector             | Extract `textContent` into the step result (for you to read).    |
+| `screenshot` | basename             | Write `<out-dir>/<basename>.png` (full page).                    |
+
+The whole flow runs in **one Chromium session** — login state, cookies, and
+navigation persist across steps.
+
+## Run the flow
+
+```bash
+node <skill-dir>/scripts/agent-browser.mjs run flow.json \
+  --base-url http://localhost:PORT \
+  --out-dir <artifact-dir>
+```
+
+The driver prints a single JSON report:
+
+```json
+{ "ok": false,
+  "baseUrl": "http://localhost:3000",
+  "steps": [
+    { "index": 0, "action": "goto", "ok": true, "ms": 412 },
+    { "index": 6, "action": "assertText", "ok": false, "ms": 10003,
+      "error": "assertText not found: \"Welcome\"" },
+    { "index": 7, "action": "text", "ok": true, "ms": 5, "text": "Dashboard" },
+    { "index": 8, "action": "screenshot", "ok": true, "ms": 88,
+      "screenshot": "/…/after-login.png" }
+  ],
+  "consoleErrors": ["Uncaught TypeError: …"],
+  "screenshots": ["/…/after-login.png"] }
+```
+
+- A step error (selector not found, assertion miss, timeout) is recorded
+  `ok:false` and the run **continues** — best-effort coverage. The exception
+  is a `goto` that fails: that is fatal and the remaining steps are skipped.
+- `ok` at the top level is true only when **every** step passed. The process
+  exits 0 even when steps failed — judge from the JSON, not the exit code.
+  A non-zero exit means a fatal harness error (bad flow file, launch failure).
+
+## Screenshots & artifacts
+
+Pass `--out-dir <artifact-dir>` pointing at the run's artifact directory the
+**prompt provides** (commonly the run's `.lastlight/<issueKey>/` dir,
+referenced as the template variable the prompt passes in). Saving there lets
+the harness **harvest** the PNGs into the dashboard Artifacts view. Reference
+each screenshot path in your report.
+
+Screenshot delivery requires **server-mode build-assets**. If the PNGs can't
+be persisted (no artifact dir was provided, or build-assets is repo-mode),
+still report the text/DOM observations and console errors, and say the
+screenshots were **not retained**.
+
+## Evidence rules
+
+Mirror `verify`/`qa-test` — you are an investigator, not an advocate:
+
+- **Never fake a pass.** Don't hardcode expected text or edit the code under
+  test to force a green step.
+- **Report real failures.** A step that genuinely fails is a finding — record
+  it `FAIL` with the assertion/selector and the driver's error, and don't bury
+  it.
+- **Treat `consoleErrors` and page errors as findings**, even if the visible
+  flow "worked" — surface them in the report.
+- If the browser is unavailable (probe failed), fall back to text and say so —
+  don't pretend a UI step ran.
+
+## Report
+
+Produce your report as your **final message** — the workflow posts it for you
+(don't `github_add_issue_comment` yourself; that would double-post).
+
+**Be concise, and stay in the browser.** The deliverable is short: a one-line
+environment summary, the results table, the screenshots, console errors, and a
+one-line coverage note. Do **not** read or analyse the repo's source code (the
+text pass already did) and do **not** narrate every step or dump extracted DOM
+text — surface a `text`/assertion value only when it's the actual evidence for a
+row (e.g. a FAIL).
+
+```
+## Browser QA: <target>
+
+**Environment:** <branch / commit, package manager, how served, Chromium version>
+
+### Results
+| Step | Status | Evidence |
+|------|--------|----------|
+| <step description> | PASS / FAIL / BLOCKED | <terse evidence + inline screenshot if any> |
+
+### Console errors
+- <each consoleErrors / pageerror entry, or "none observed">
+
+### Coverage
+<one or two lines: what was driven, and anything not tested and why>
+```
+
+Reference screenshots **inline** as raw Markdown images when the prompt gives
+you a public artifact base URL — write `![caption](<base>/<name>.png)` directly
+in the report body (or table cell), **never** wrapped in backticks or a code
+fence (inside a code span it renders as literal text, not an image). Otherwise
+reference them by filename. Every step in the flow must
+have a row and a result. Never report a flow as "passed" with steps you didn't
+actually run — list them as untested instead.

package/skills/browser-qa/scripts/agent-browser.mjs

@@ -0,0 +1,380 @@
+#!/usr/bin/env node
+// agent-browser.mjs — bundled headless-browser driver for Tier B browser QA.
+//
+// CONTRACT
+// --------
+// Runs inside the `lastlight-sandbox-qa:latest` docker image, which bakes in
+// Playwright + Chromium at PLAYWRIGHT_BROWSERS_PATH=/opt/playwright-browsers and
+// makes the global `playwright` package resolvable via NODE_PATH. The calling
+// agent has bash + file tools but NO vision: it reasons over this CLI's JSON
+// stdout (extracted text, assertion results, console errors). The PNG
+// screenshots are human evidence only — the agent never "sees" them.
+//
+// Subcommands:
+//   doctor
+//     Runtime probe. Launches headless Chromium (--no-sandbox), opens
+//     about:blank, closes. On success prints {"ok":true,"chromium":"<version>"}
+//     and exits 0; on ANY failure prints {"ok":false,"error":"..."} and exits 1.
+//     The skill runs this first to decide browser-vs-text.
+//
+//   run <flow.json> [--base-url URL] [--out-dir DIR] [--record-dir DIR]
+//     Executes a FLOW in ONE Chromium session (state preserved across steps) and
+//     prints a single JSON report.
+//
+//     With --record-dir DIR (or `"record": true` in the flow), the whole session
+//     is screen-recorded via Playwright's native recordVideo and saved to
+//     <record-dir>/session.webm (default: the out-dir). The saved path is
+//     reported as `video` in the JSON. Used by the `/demo` workflow, which then
+//     composites the raw webm into a titled mp4 with compose-demo.sh.
+//
+//     Flow shape:
+//       { "baseUrl": "http://localhost:3000",
+//         "viewport": {"width":1280,"height":800},
+//         "steps": [
+//           {"name":"home", "goto":"/"},
+//           {"click":"text=Login"},
+//           {"fill":["#email","a@b.com"]},
+//           {"type":["#search","hello"]},
+//           {"press":"Enter"},
+//           {"waitFor":"#dashboard"},
+//           {"assertText":"Welcome"},
+//           {"text":"h1"},
+//           {"screenshot":"after-login"}
+//         ] }
+//     A step may combine an action plus a trailing `screenshot`.
+//
+//     Per-step semantics:
+//       - A step error (selector not found, assertion fail, timeout) is recorded
+//         {ok:false} and the run CONTINUES (best-effort QA) — EXCEPT a `goto`
+//         that throws is FATAL: remaining steps are marked skipped.
+//       - assertText passes if the text is visible anywhere on the page; on miss
+//         the step is {ok:false} but the run continues.
+//       - text extracts a selector's textContent into the step result.
+//       - screenshot writes <out-dir>/<basename>.png (full page).
+//
+//     Final stdout: one JSON object
+//       { ok, baseUrl, steps:[{index,action,ok,ms,text?,screenshot?,error?}],
+//         consoleErrors:[...], screenshots:[paths] }
+//     Exit 0 even when steps failed (the agent reads the JSON to judge). Exit
+//     non-zero only on a FATAL harness error (bad flow file, launch failure).
+//
+// Dependency-free apart from playwright.
+
+import { readFileSync, mkdirSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import { createRequire } from 'node:module';
+
+// This file is ESM (.mjs); playwright is a CJS package. createRequire gives us
+// a `require` that resolves an absolute package-dir path (see loadPlaywright).
+const require = createRequire(import.meta.url);
+
+const WAIT_TIMEOUT = 10_000; // sane default for waitFor / assertText probes
+
+function emit(obj) {
+  process.stdout.write(JSON.stringify(obj) + '\n');
+}
+
+async function loadPlaywright() {
+  // Resolve playwright via CJS `require`: it handles an absolute package-dir
+  // path ($LASTLIGHT_PLAYWRIGHT, baked into the QA image) by reading the
+  // package.json `main` — which ESM `import()` of a directory does NOT do — and
+  // it honours NODE_PATH for the bare-specifier fallback. playwright ships a CJS
+  // entry, so `require` returns { chromium, … } directly.
+  const candidates = [process.env.LASTLIGHT_PLAYWRIGHT, 'playwright'].filter(Boolean);
+  for (const spec of candidates) {
+    try {
+      return require(spec);
+    } catch {
+      // try the next candidate
+    }
+  }
+  emit({
+    ok: false,
+    error:
+      'playwright not available — browser QA needs the lastlight-sandbox-qa image',
+  });
+  process.exit(1);
+}
+
+async function doctor() {
+  const { chromium } = await loadPlaywright();
+  let browser;
+  try {
+    browser = await chromium.launch({ headless: true, args: ['--no-sandbox'] });
+    const page = await browser.newPage();
+    await page.goto('about:blank');
+    const version = browser.version();
+    await page.close();
+    emit({ ok: true, chromium: version });
+    process.exit(0);
+  } catch (err) {
+    emit({ ok: false, error: String(err && err.message ? err.message : err) });
+    process.exit(1);
+  } finally {
+    if (browser) await browser.close().catch(() => {});
+  }
+}
+
+// Resolve a goto target against the base URL. Absolute URLs pass through.
+function resolveUrl(target, baseUrl) {
+  if (/^https?:\/\//i.test(target)) return target;
+  if (!baseUrl) return target;
+  return baseUrl.replace(/\/+$/, '') + '/' + String(target).replace(/^\/+/, '');
+}
+
+// Returns the action name for a step (for reporting) — first recognized key.
+function actionOf(step) {
+  for (const k of [
+    'goto',
+    'click',
+    'fill',
+    'type',
+    'press',
+    'waitFor',
+    'assertText',
+    'text',
+  ]) {
+    if (k in step) return k;
+  }
+  if ('screenshot' in step) return 'screenshot';
+  return 'noop';
+}
+
+async function execStep(page, step, baseUrl, outDir, screenshots) {
+  const result = {};
+  let fatal = false;
+
+  if ('goto' in step) {
+    // Navigation failure is FATAL.
+    try {
+      await page.goto(resolveUrl(step.goto, baseUrl), {
+        waitUntil: 'load',
+        timeout: WAIT_TIMEOUT * 3,
+      });
+    } catch (err) {
+      throw Object.assign(new Error(`goto failed: ${err.message}`), {
+        fatal: true,
+      });
+    }
+  } else if ('click' in step) {
+    await page.click(step.click, { timeout: WAIT_TIMEOUT });
+  } else if ('fill' in step) {
+    const [sel, val] = step.fill;
+    await page.fill(sel, val, { timeout: WAIT_TIMEOUT });
+  } else if ('type' in step) {
+    const [sel, val] = step.type;
+    await page.locator(sel).first().pressSequentially(val, {
+      timeout: WAIT_TIMEOUT,
+    });
+  } else if ('press' in step) {
+    await page.keyboard.press(step.press);
+  } else if ('waitFor' in step) {
+    await page.locator(step.waitFor).first().waitFor({
+      state: 'visible',
+      timeout: WAIT_TIMEOUT,
+    });
+  } else if ('assertText' in step) {
+    // Pass if visible anywhere on the page; miss => step fails, run continues.
+    try {
+      await page
+        .getByText(step.assertText, { exact: false })
+        .first()
+        .waitFor({ state: 'visible', timeout: WAIT_TIMEOUT });
+    } catch {
+      throw new Error(`assertText not found: ${JSON.stringify(step.assertText)}`);
+    }
+  } else if ('text' in step) {
+    const txt = await page
+      .locator(step.text)
+      .first()
+      .textContent({ timeout: WAIT_TIMEOUT });
+    result.text = txt == null ? '' : txt.trim();
+  }
+
+  // A trailing screenshot can ride along with any action (or stand alone).
+  if ('screenshot' in step) {
+    const base = String(step.screenshot).replace(/[^a-zA-Z0-9._-]/g, '_');
+    const path = join(outDir, `${base}.png`);
+    await page.screenshot({ path, fullPage: true });
+    result.screenshot = path;
+    screenshots.push(path);
+  }
+
+  return { result, fatal };
+}
+
+async function run(flowPath, baseUrlArg, outDirArg, recordDirArg) {
+  let flow;
+  try {
+    flow = JSON.parse(readFileSync(resolve(flowPath), 'utf8'));
+  } catch (err) {
+    emit({ ok: false, error: `cannot read flow file: ${err.message}` });
+    process.exit(1);
+  }
+  if (!flow || !Array.isArray(flow.steps)) {
+    emit({ ok: false, error: 'flow file must have a "steps" array' });
+    process.exit(1);
+  }
+
+  const baseUrl = baseUrlArg || flow.baseUrl || '';
+  const outDir = resolve(outDirArg || process.cwd());
+  // Record the session when --record-dir is passed OR the flow opts in with
+  // `"record": true`. The .webm lands in the record dir (default: out-dir).
+  const doRecord = !!recordDirArg || flow.record === true;
+  const videoDir = resolve(recordDirArg || outDir);
+  try {
+    mkdirSync(outDir, { recursive: true });
+  } catch {
+    /* best effort */
+  }
+  if (doRecord) {
+    try {
+      mkdirSync(videoDir, { recursive: true });
+    } catch {
+      /* best effort */
+    }
+  }
+
+  const viewport = flow.viewport || { width: 1280, height: 800 };
+  const { chromium } = await loadPlaywright();
+  let browser;
+  const steps = [];
+  const screenshots = [];
+  const consoleErrors = [];
+  let videoPath = null;
+
+  try {
+    browser = await chromium.launch({ headless: true, args: ['--no-sandbox'] });
+  } catch (err) {
+    emit({
+      ok: false,
+      error: `browser launch failed: ${err && err.message ? err.message : err}`,
+    });
+    process.exit(1);
+  }
+
+  try {
+    const context = await browser.newContext({
+      viewport,
+      // Playwright records video per-context; the size matches the viewport so
+      // the clip isn't letterboxed. The .webm is flushed on context.close().
+      ...(doRecord ? { recordVideo: { dir: videoDir, size: viewport } } : {}),
+    });
+    const page = await context.newPage();
+
+    page.on('console', (msg) => {
+      if (msg.type() === 'error') consoleErrors.push(msg.text());
+    });
+    page.on('pageerror', (err) => {
+      consoleErrors.push(String(err && err.message ? err.message : err));
+    });
+
+    let fatalHit = false;
+    for (let i = 0; i < flow.steps.length; i++) {
+      const step = flow.steps[i];
+      const action = actionOf(step);
+
+      if (fatalHit) {
+        steps.push({ index: i, action, ok: false, ms: 0, error: 'skipped (prior fatal step)' });
+        continue;
+      }
+
+      const started = Date.now();
+      try {
+        const { result } = await execStep(page, step, baseUrl, outDir, screenshots);
+        steps.push({ index: i, action, ok: true, ms: Date.now() - started, ...result });
+      } catch (err) {
+        const entry = {
+          index: i,
+          action,
+          ok: false,
+          ms: Date.now() - started,
+          error: String(err && err.message ? err.message : err),
+        };
+        steps.push(entry);
+        if (err && err.fatal) fatalHit = true; // navigation failure: skip the rest
+      }
+    }
+
+    // Finalize a recording (if any) BEFORE emitting: saving the video requires
+    // the context to close, which flushes the .webm to disk. A save failure is a
+    // reported finding, not a fatal run error.
+    if (doRecord) {
+      const video = page.video();
+      await context.close();
+      if (video) {
+        const target = join(videoDir, 'session.webm');
+        try {
+          await video.saveAs(target);
+          videoPath = target;
+          await video.delete().catch(() => {});
+        } catch (err) {
+          consoleErrors.push(
+            `video save failed: ${err && err.message ? err.message : err}`,
+          );
+        }
+      }
+    }
+
+    emit({
+      ok: steps.every((s) => s.ok),
+      baseUrl,
+      steps,
+      consoleErrors,
+      screenshots,
+      ...(videoPath ? { video: videoPath } : {}),
+    });
+    process.exit(0);
+  } catch (err) {
+    // Unexpected harness error mid-run — still emit a JSON object.
+    emit({
+      ok: false,
+      error: String(err && err.message ? err.message : err),
+      baseUrl,
+      steps,
+      consoleErrors,
+      screenshots,
+      ...(videoPath ? { video: videoPath } : {}),
+    });
+    process.exit(1);
+  } finally {
+    if (browser) await browser.close().catch(() => {});
+  }
+}
+
+async function main() {
+  const [cmd, ...rest] = process.argv.slice(2);
+
+  if (cmd === 'doctor') {
+    await doctor();
+    return;
+  }
+
+  if (cmd === 'run') {
+    const positional = [];
+    let baseUrl;
+    let outDir;
+    let recordDir;
+    for (let i = 0; i < rest.length; i++) {
+      const a = rest[i];
+      if (a === '--base-url') baseUrl = rest[++i];
+      else if (a === '--out-dir') outDir = rest[++i];
+      else if (a === '--record-dir') recordDir = rest[++i];
+      else positional.push(a);
+    }
+    if (!positional[0]) {
+      emit({ ok: false, error: 'usage: agent-browser.mjs run <flow.json> [--base-url URL] [--out-dir DIR] [--record-dir DIR]' });
+      process.exit(1);
+    }
+    await run(positional[0], baseUrl, outDir, recordDir);
+    return;
+  }
+
+  emit({ ok: false, error: 'usage: agent-browser.mjs <doctor|run> ...' });
+  process.exit(1);
+}
+
+main().catch((err) => {
+  emit({ ok: false, error: String(err && err.message ? err.message : err) });
+  process.exit(1);
+});