Add automation framework, typing, and runner for the autobuyer

Turns the autobuyer from a page scraper into something that acts. A dashboard
button queues a run; a desktop process executes it against the real browser.

lib/automations.ts — automations are declarative step lists nested inside the
firm whose site they drive. Steps are click / type / wait / navigate, and they
inherit the firm's tab pattern and URL, so one firm's automation can't act on
another's tab. Adding a button means adding an entry here; the page renders
buttons from the API and the runner receives steps from the server, so neither
needs editing. Runs key on firm:automation — every firm will plausibly have its
own "buy-accounts", and a bare id would resolve to the wrong one.

clicker/runner.py — the daemon behind the buttons. Claims a queued run, works
through the steps, reports each one back for the page's live log. Only one run
executes at a time: two processes driving one physical mouse would interleave
clicks. Heartbeats on its own thread, because a step can block for tens of
seconds and folding the beat into the main loop would show the runner as offline
in the middle of the run it was executing.

clicker/actions.py — one implementation of the safety checks, shared by the CLI
and the runner. Refuses to act when the element is covered by an overlay, when
coordinates fall off-screen, when the browser can't be confirmed frontmost, or
(for type) when the target isn't an editable field.

Typing: uneven human cadence, and the field is read back afterwards and compared
against what was typed — a field that never took focus fails silently and looks
identical to success otherwise. Non-ASCII is rejected because pyautogui skips
those characters without complaint, and newlines because Enter may submit the
form. Typos are deliberately not simulated: a mistyped digit in a trading form
is a real loss, and the correction is the part that can go wrong.

Extension: opens the firm's page when no tab matches, navigates to a specific
page for a navigate step (skipped when already there, so page state survives),
and retries the locate while a freshly loaded React app mounts — `complete` only
means the document loaded.

Staleness reporting, after it cost three debugging rounds: Chrome doesn't reload
an unpacked extension and Python doesn't reload a running process, so both now
report their version. A stale runner gets a red banner naming both versions and
the automation buttons are disabled, rather than failing mid-run on a step type
it predates.

Scale detection is now conservative: a raw OS/browser width ratio is only
trusted when it lands on a real scaling factor. On this multi-monitor desktop
the previous logic would have silently halved every coordinate.

Verified end to end against the live browser: navigate, locate, and a real
click (run #12, all three steps). API round-trips, claim-once semantics, run
cancellation, the heartbeat online/offline lifecycle, motion geometry and
timing, focus activation, and typing verification all pass.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

app/api/autobuyer/automations/route.ts

@@ -0,0 +1,53 @@
+import { NextRequest } from 'next/server';
+import { FIRMS, findAutomation, automationKey, describeStep } from '@/lib/automations';
+import { createRun, getSetting } from '@/lib/db';
+import { corsJson, corsPreflight } from '../cors';
+
+/** The dashboard renders a tab per firm, and a button per automation inside it. */
+export async function GET() {
+    return corsJson({
+        firms: FIRMS.map((firm) => ({
+            id: firm.id,
+            label: firm.label,
+            urlPattern: firm.urlPattern,
+            automations: firm.automations.map((a) => ({
+                key: automationKey(firm.id, a.id),
+                id: a.id,
+                label: a.label,
+                description: a.description,
+                confirm: a.confirm ?? null,
+                steps: a.steps.map(describeStep),
+            })),
+        })),
+    });
+}
+
+/** Queue a run. The Python runner picks it up. */
+export async function POST(req: NextRequest) {
+    try {
+        const body = await req.json() as { automationId?: unknown };
+        if (typeof body.automationId !== 'string') {
+            return corsJson({ error: '`automationId` is required' }, { status: 400 });
+        }
+        const found = findAutomation(body.automationId);
+        if (!found) {
+            return corsJson({ error: `No automation "${body.automationId}"` }, { status: 404 });
+        }
+        if (found.automation.steps.length === 0) {
+            return corsJson({ error: `"${found.automation.label}" has no steps yet` }, { status: 400 });
+        }
+        // The dashboard switch is the master arm for anything that drives the mouse.
+        if (getSetting('autobuyer_enabled') !== '1') {
+            return corsJson({ error: 'AutoBuyer is switched off' }, { status: 409 });
+        }
+
+        const run = createRun(body.automationId, found.automation.steps.length);
+        return corsJson({ runId: run.id, totalSteps: run.total_steps });
+    } catch (err: any) {
+        return corsJson({ error: err?.message ?? 'Failed to queue run' }, { status: 500 });
+    }
+}
+
+export async function OPTIONS() {
+    return corsPreflight();
+}

app/api/autobuyer/locate/claim/route.ts

@@ -12,6 +12,8 @@ export async function POST() {
             selector: row.selector,
             index: row.match_index,
             urlPattern: row.url_pattern,
+            openUrl: row.open_url,
+            navigateUrl: row.navigate_url,
         },
     });
 }

app/api/autobuyer/locate/route.ts

@@ -5,14 +5,16 @@ import { corsJson, corsPreflight } from '../cors';
 /** Python enqueues "find this selector and tell me where it is on screen". */
 export async function POST(req: NextRequest) {
     try {
-        const body = await req.json() as { selector?: unknown; index?: unknown; urlPattern?: unknown };
+        const body = await req.json() as { selector?: unknown; index?: unknown; urlPattern?: unknown; openUrl?: unknown; navigateUrl?: unknown };
         if (typeof body.selector !== 'string' || !body.selector.trim()) {
             return corsJson({ error: '`selector` is required' }, { status: 400 });
         }
         const index = Number.isInteger(body.index) ? Number(body.index) : 0;
         const urlPattern = typeof body.urlPattern === 'string' ? body.urlPattern : '';
+        const openUrl = typeof body.openUrl === 'string' ? body.openUrl : '';
+        const navigateUrl = typeof body.navigateUrl === 'string' ? body.navigateUrl : '';
 
-        const row = createLocateRequest(body.selector.trim(), index, urlPattern);
+        const row = createLocateRequest(body.selector.trim(), index, urlPattern, openUrl, navigateUrl);
         return corsJson({ id: row.id, status: row.status });
     } catch (err: any) {
         return corsJson({ error: err?.message ?? 'Failed to queue request' }, { status: 500 });

app/api/autobuyer/runner/route.ts

@@ -0,0 +1,44 @@
+import { NextRequest } from 'next/server';
+import { setRunnerHeartbeat, getRunnerHeartbeat, RUNNER_TIMEOUT_MS, RUNNER_EXPECTED_VERSION } from '@/lib/db';
+import { corsJson, corsPreflight } from '../cors';
+
+/** The runner checks in. Timestamped server-side so a runner with a skewed clock
+ *  doesn't read as permanently offline (or permanently online). */
+export async function POST(req: NextRequest) {
+    try {
+        const body = await req.json().catch(() => ({})) as Record<string, unknown>;
+        setRunnerHeartbeat({
+            host: typeof body.host === 'string' ? body.host : undefined,
+            pid: typeof body.pid === 'number' ? body.pid : undefined,
+            dryRun: body.dryRun === true,
+            version: typeof body.version === 'string' ? body.version : undefined,
+            busy: body.busy === true,
+        });
+        return corsJson({ ok: true });
+    } catch (err: any) {
+        return corsJson({ error: err?.message ?? 'Failed to record heartbeat' }, { status: 500 });
+    }
+}
+
+export async function GET() {
+    const hb = getRunnerHeartbeat();
+    if (!hb) return corsJson({ online: false, lastSeen: null, ageMs: null });
+
+    const ageMs = Date.now() - hb.at;
+    return corsJson({
+        online: ageMs < RUNNER_TIMEOUT_MS,
+        lastSeen: hb.at,
+        ageMs,
+        host: hb.host ?? null,
+        pid: hb.pid ?? null,
+        dryRun: !!hb.dryRun,
+        busy: !!hb.busy,
+        version: hb.version ?? null,
+        expectedVersion: RUNNER_EXPECTED_VERSION,
+        stale: (hb.version ?? '') !== RUNNER_EXPECTED_VERSION,
+    });
+}
+
+export async function OPTIONS() {
+    return corsPreflight();
+}

app/api/autobuyer/runs/claim/route.ts

@@ -0,0 +1,33 @@
+import { claimRun, getSetting } from '@/lib/db';
+import { findAutomation, resolveSteps } from '@/lib/automations';
+import { corsJson, corsPreflight } from '../../cors';
+
+/** The Python runner polls this. Returns the run plus the steps to execute, so
+ *  the runner never needs its own copy of the automation definitions. */
+export async function POST() {
+    if (getSetting('autobuyer_enabled') !== '1') {
+        return corsJson({ run: null, reason: 'AutoBuyer is switched off' });
+    }
+
+    const row = claimRun();
+    if (!row) return corsJson({ run: null });
+
+    const found = findAutomation(row.automation_id);
+    if (!found) {
+        return corsJson({ run: null, reason: `Unknown automation ${row.automation_id}` });
+    }
+
+    return corsJson({
+        run: {
+            id: row.id,
+            automationId: row.automation_id,
+            firm: found.firm.label,
+            label: found.automation.label,
+            steps: resolveSteps(found.firm, found.automation),
+        },
+    });
+}
+
+export async function OPTIONS() {
+    return corsPreflight();
+}

app/api/autobuyer/runs/progress/route.ts

@@ -0,0 +1,48 @@
+import { NextRequest } from 'next/server';
+import { appendRunLog, finishRun, getRun } from '@/lib/db';
+import { corsJson, corsPreflight } from '../../cors';
+
+interface ProgressBody {
+    id?: unknown;
+    stepIndex?: unknown;
+    step?: unknown;
+    ok?: unknown;
+    detail?: unknown;
+    /** Present only on the final call. */
+    finish?: unknown;
+    error?: unknown;
+}
+
+/** The runner reports each step, then a final finish. */
+export async function POST(req: NextRequest) {
+    try {
+        const body = await req.json() as ProgressBody;
+        const id = Number(body.id);
+        const row = getRun(id);
+        if (!row) return corsJson({ error: 'No such run' }, { status: 404 });
+
+        if (typeof body.step === 'string') {
+            appendRunLog(id, {
+                at: Date.now(),
+                step: body.step,
+                ok: body.ok !== false,
+                detail: typeof body.detail === 'string' ? body.detail : undefined,
+            }, Number(body.stepIndex) || row.step_index);
+        }
+
+        if (body.finish === true) {
+            const error = typeof body.error === 'string' && body.error ? body.error : null;
+            finishRun(id, error ? 'error' : 'done', error);
+        }
+
+        // The runner reads this to notice the Stop button between steps.
+        const now = getRun(id);
+        return corsJson({ ok: true, status: now?.status ?? 'error' });
+    } catch (err: any) {
+        return corsJson({ error: err?.message ?? 'Failed to record progress' }, { status: 500 });
+    }
+}
+
+export async function OPTIONS() {
+    return corsPreflight();
+}

app/api/autobuyer/runs/route.ts

@@ -0,0 +1,43 @@
+import { NextRequest } from 'next/server';
+import { getRun, getRecentRuns, cancelRun } from '@/lib/db';
+import { findAutomation } from '@/lib/automations';
+import { corsJson, corsPreflight } from '../cors';
+
+function shape(row: NonNullable<ReturnType<typeof getRun>>) {
+    return {
+        id: row.id,
+        automationId: row.automation_id,
+        automationLabel: findAutomation(row.automation_id)?.automation.label ?? row.automation_id,
+        status: row.status,
+        stepIndex: row.step_index,
+        totalSteps: row.total_steps,
+        log: (() => { try { return JSON.parse(row.log); } catch { return []; } })(),
+        error: row.error,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    };
+}
+
+/** `?id=` for one run, otherwise the recent history the dashboard shows. */
+export async function GET(req: NextRequest) {
+    const idParam = req.nextUrl.searchParams.get('id');
+    if (idParam) {
+        const row = getRun(Number(idParam));
+        if (!row) return corsJson({ error: 'No such run' }, { status: 404 });
+        return corsJson({ run: shape(row) });
+    }
+    return corsJson({ runs: getRecentRuns(5).map(shape) });
+}
+
+/** Stop button. A queued run never starts; a running one halts at the next step. */
+export async function DELETE(req: NextRequest) {
+    const id = Number(req.nextUrl.searchParams.get('id'));
+    if (!Number.isInteger(id) || id <= 0) {
+        return corsJson({ error: '`id` is required' }, { status: 400 });
+    }
+    return corsJson({ cancelled: cancelRun(id) });
+}
+
+export async function OPTIONS() {
+    return corsPreflight();
+}