@blockrun/franklin 3.1.2 → 3.2.0

package/dist/social/browser.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Native Playwright-core wrapper for Franklin's social subsystem.
+ *
+ * Mirrors the 9 browser primitives social-bot exposes via its `browse` CLI
+ * (open, snapshot, click, type, press, scroll, screenshot, getUrl, close).
+ * Persistent context so login state survives across runs:
+ *
+ *   ~/.blockrun/social-chrome-profile/
+ *
+ * Unlike social-bot's shell=True subprocess calls, every interaction goes
+ * through Playwright's argv-based API — no shell injection surface even if
+ * the LLM generates `$(rm -rf /)` as reply text.
+ */
+export declare const SOCIAL_PROFILE_DIR: string;
+/**
+ * Ref assigned to every interactive AX node. Format matches social-bot:
+ *   [depth-index]
+ * e.g. [0-3], [2-17]. Depth is the tree nesting level; index is the
+ * order within that level.
+ */
+export interface AxRef {
+    id: string;
+    role: string;
+    name: string;
+    selector: string;
+}
+interface AxNode {
+    role?: string;
+    name?: string;
+    value?: string;
+    description?: string;
+    children?: AxNode[];
+}
+/**
+ * Walk an AX tree and produce:
+ *   1. A flat text dump with [depth-idx] refs (for regex-based element finding)
+ *   2. A map of ref ID → role/name/selector for click-by-ref lookups
+ *
+ * The flat text shape intentionally mirrors social-bot's `browse snapshot`
+ * output so code patterns and regexes are directly portable.
+ */
+export declare function serializeAxTree(root: AxNode): {
+    tree: string;
+    refs: Map<string, AxRef>;
+};
+export interface BrowserOptions {
+    headless?: boolean;
+    channel?: 'chrome' | 'chromium' | 'msedge';
+    slowMo?: number;
+    viewport?: {
+        width: number;
+        height: number;
+    };
+}
+/**
+ * Franklin's social browser driver. Lazy-imports playwright-core so the
+ * rest of the CLI stays fast to start.
+ */
+export declare class SocialBrowser {
+    private context;
+    private page;
+    private lastRefs;
+    private opts;
+    constructor(opts?: BrowserOptions);
+    launch(): Promise<void>;
+    close(): Promise<void>;
+    open(url: string): Promise<void>;
+    /**
+     * Capture the page as a flat [N-M] ref tree (social-bot style).
+     * Also stores the ref map internally so click(ref) can find the node.
+     */
+    snapshot(): Promise<string>;
+    /**
+     * Click by ref from the last snapshot. Throws if the ref isn't known.
+     * The ref map is reset on every snapshot() call.
+     */
+    click(ref: string): Promise<void>;
+    clickXY(x: number, y: number): Promise<void>;
+    /**
+     * Type text into the currently focused element. Safe against any content
+     * in `text` — Playwright passes it as argv, not through a shell.
+     */
+    type(text: string): Promise<void>;
+    press(key: string): Promise<void>;
+    scroll(x: number, y: number, dx: number, dy: number): Promise<void>;
+    screenshot(filePath: string): Promise<void>;
+    getUrl(): Promise<string>;
+    getTitle(): Promise<string>;
+    waitForTimeout(ms: number): Promise<void>;
+    /**
+     * Block until the user closes the browser tab (used by the login flow).
+     * Resolves when the context is closed.
+     */
+    waitForClose(): Promise<void>;
+    private requirePage;
+}
+export {};

package/dist/social/browser.js

@@ -0,0 +1,219 @@
+/**
+ * Native Playwright-core wrapper for Franklin's social subsystem.
+ *
+ * Mirrors the 9 browser primitives social-bot exposes via its `browse` CLI
+ * (open, snapshot, click, type, press, scroll, screenshot, getUrl, close).
+ * Persistent context so login state survives across runs:
+ *
+ *   ~/.blockrun/social-chrome-profile/
+ *
+ * Unlike social-bot's shell=True subprocess calls, every interaction goes
+ * through Playwright's argv-based API — no shell injection surface even if
+ * the LLM generates `$(rm -rf /)` as reply text.
+ */
+import path from 'node:path';
+import fs from 'node:fs';
+import os from 'node:os';
+// ─── Persistent profile location ───────────────────────────────────────────
+export const SOCIAL_PROFILE_DIR = path.join(os.homedir(), '.blockrun', 'social-chrome-profile');
+function ensureProfileDir() {
+    if (!fs.existsSync(SOCIAL_PROFILE_DIR)) {
+        fs.mkdirSync(SOCIAL_PROFILE_DIR, { recursive: true });
+    }
+}
+/**
+ * Walk an AX tree and produce:
+ *   1. A flat text dump with [depth-idx] refs (for regex-based element finding)
+ *   2. A map of ref ID → role/name/selector for click-by-ref lookups
+ *
+ * The flat text shape intentionally mirrors social-bot's `browse snapshot`
+ * output so code patterns and regexes are directly portable.
+ */
+export function serializeAxTree(root) {
+    const lines = [];
+    const refs = new Map();
+    // Counter per-depth so each depth gets sequential indexes
+    const depthCounters = [];
+    // Counter per (role,name) to disambiguate multiple same-named elements
+    const nameOccurrences = new Map();
+    function walk(node, depth) {
+        if (!node)
+            return;
+        const role = node.role || '';
+        const name = (node.name || '').trim().slice(0, 120);
+        // Skip uninteresting nodes — they'd pollute the tree
+        const isInteresting = role && role !== 'none' && role !== 'presentation' && role !== 'generic';
+        if (isInteresting) {
+            while (depthCounters.length <= depth)
+                depthCounters.push(0);
+            const idx = depthCounters[depth]++;
+            const id = `${depth}-${idx}`;
+            const labelStr = name || (node.value || '').trim().slice(0, 120);
+            const indent = '  '.repeat(depth);
+            lines.push(`${indent}[${id}] ${role}: ${labelStr}`);
+            // Build a Playwright locator. Prefer getByRole+name, fall back to
+            // nth match if there are duplicates.
+            const key = `${role}||${labelStr}`;
+            const occ = nameOccurrences.get(key) || 0;
+            nameOccurrences.set(key, occ + 1);
+            let selector;
+            if (labelStr) {
+                // Escape quotes in the name
+                const escaped = labelStr.replace(/"/g, '\\"');
+                selector = occ === 0
+                    ? `role=${role}[name="${escaped}"]`
+                    : `role=${role}[name="${escaped}"] >> nth=${occ}`;
+            }
+            else {
+                selector = `role=${role} >> nth=${idx}`;
+            }
+            refs.set(id, { id, role, name: labelStr, selector });
+        }
+        if (node.children) {
+            for (const child of node.children) {
+                walk(child, isInteresting ? depth + 1 : depth);
+            }
+        }
+    }
+    walk(root, 0);
+    return { tree: lines.join('\n'), refs };
+}
+/**
+ * Franklin's social browser driver. Lazy-imports playwright-core so the
+ * rest of the CLI stays fast to start.
+ */
+export class SocialBrowser {
+    context = null;
+    page = null;
+    lastRefs = new Map();
+    opts;
+    constructor(opts = {}) {
+        this.opts = {
+            headless: opts.headless ?? false,
+            channel: opts.channel ?? 'chrome',
+            slowMo: opts.slowMo ?? 150,
+            viewport: opts.viewport ?? { width: 1280, height: 900 },
+        };
+    }
+    async launch() {
+        ensureProfileDir();
+        // Lazy import — playwright-core is ~2MB and we don't want to pay the
+        // import cost on every franklin command (e.g. `franklin --version`)
+        const { chromium } = await import('playwright-core');
+        try {
+            this.context = await chromium.launchPersistentContext(SOCIAL_PROFILE_DIR, {
+                headless: this.opts.headless,
+                channel: this.opts.channel,
+                slowMo: this.opts.slowMo,
+                viewport: this.opts.viewport,
+                // Pretend to be a regular Chrome (not headless fingerprint)
+                args: [
+                    '--disable-blink-features=AutomationControlled',
+                    '--no-default-browser-check',
+                ],
+            });
+        }
+        catch (err) {
+            const msg = err.message;
+            if (msg.includes('Executable doesn') || msg.includes("wasn't found")) {
+                throw new Error(`Chrome/Chromium not found. Run:\n  franklin social setup\n\n` +
+                    `Or install manually:\n  npx playwright install chromium\n\n` +
+                    `Original error: ${msg}`);
+            }
+            throw err;
+        }
+        // Reuse existing tab if any, else open new
+        const existing = this.context.pages();
+        this.page = existing.length > 0 ? existing[0] : await this.context.newPage();
+    }
+    async close() {
+        if (this.context) {
+            await this.context.close().catch(() => { });
+            this.context = null;
+            this.page = null;
+        }
+    }
+    // ─── Primitives ────────────────────────────────────────────────────────
+    async open(url) {
+        this.requirePage();
+        await this.page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30000 });
+    }
+    /**
+     * Capture the page as a flat [N-M] ref tree (social-bot style).
+     * Also stores the ref map internally so click(ref) can find the node.
+     */
+    async snapshot() {
+        this.requirePage();
+        // Playwright's accessibility snapshot returns a full AX tree
+        const axRoot = await this.page.accessibility.snapshot({ interestingOnly: false });
+        if (!axRoot)
+            return '';
+        const { tree, refs } = serializeAxTree(axRoot);
+        this.lastRefs = refs;
+        return tree;
+    }
+    /**
+     * Click by ref from the last snapshot. Throws if the ref isn't known.
+     * The ref map is reset on every snapshot() call.
+     */
+    async click(ref) {
+        this.requirePage();
+        const axRef = this.lastRefs.get(ref);
+        if (!axRef) {
+            throw new Error(`Unknown ref "${ref}". Refs are only valid until the next snapshot() call. Known refs: ${this.lastRefs.size}`);
+        }
+        await this.page.locator(axRef.selector).first().click({ timeout: 15000 });
+    }
+    async clickXY(x, y) {
+        this.requirePage();
+        await this.page.mouse.click(x, y);
+    }
+    /**
+     * Type text into the currently focused element. Safe against any content
+     * in `text` — Playwright passes it as argv, not through a shell.
+     */
+    async type(text) {
+        this.requirePage();
+        await this.page.keyboard.type(text, { delay: 20 });
+    }
+    async press(key) {
+        this.requirePage();
+        await this.page.keyboard.press(key);
+    }
+    async scroll(x, y, dx, dy) {
+        this.requirePage();
+        await this.page.mouse.move(x, y);
+        await this.page.mouse.wheel(dx, dy);
+    }
+    async screenshot(filePath) {
+        this.requirePage();
+        await this.page.screenshot({ path: filePath, fullPage: false });
+    }
+    async getUrl() {
+        this.requirePage();
+        return this.page.url();
+    }
+    async getTitle() {
+        this.requirePage();
+        return this.page.title();
+    }
+    async waitForTimeout(ms) {
+        this.requirePage();
+        await this.page.waitForTimeout(ms);
+    }
+    /**
+     * Block until the user closes the browser tab (used by the login flow).
+     * Resolves when the context is closed.
+     */
+    async waitForClose() {
+        this.requirePage();
+        await new Promise((resolve) => {
+            this.context.on('close', () => resolve());
+            this.page.on('close', () => resolve());
+        });
+    }
+    requirePage() {
+        if (!this.page)
+            throw new Error('SocialBrowser not launched — call launch() first');
+    }
+}

package/dist/social/config.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Typed config for Franklin's social subsystem.
+ * Stored at ~/.blockrun/social-config.json. Default written on first run.
+ */
+export interface ProductConfig {
+    name: string;
+    description: string;
+    trigger_keywords: string[];
+}
+export interface SocialConfig {
+    version: 1;
+    handle: string;
+    products: ProductConfig[];
+    x: {
+        search_queries: string[];
+        daily_target: number;
+        min_delay_seconds: number;
+        max_length: number;
+        login_detection: string;
+    };
+    reply_style: {
+        rules: string[];
+        model_tier: 'free' | 'cheap' | 'premium';
+    };
+}
+export declare const CONFIG_PATH: string;
+/**
+ * Load config from disk. If missing, write defaults and return them.
+ * Returns the parsed config or throws on malformed JSON.
+ */
+export declare function loadConfig(): SocialConfig;
+/**
+ * Persist config back to disk.
+ */
+export declare function saveConfig(cfg: SocialConfig): void;
+/**
+ * Whether the config is "ready" to run — has a handle and at least one
+ * product with keywords.
+ */
+export declare function isConfigReady(cfg: SocialConfig): {
+    ready: boolean;
+    reason?: string;
+};

package/dist/social/config.js

@@ -0,0 +1,83 @@
+/**
+ * Typed config for Franklin's social subsystem.
+ * Stored at ~/.blockrun/social-config.json. Default written on first run.
+ */
+import path from 'node:path';
+import fs from 'node:fs';
+import os from 'node:os';
+export const CONFIG_PATH = path.join(os.homedir(), '.blockrun', 'social-config.json');
+const DEFAULT_CONFIG = {
+    version: 1,
+    handle: '',
+    products: [
+        {
+            name: 'Your Product',
+            description: 'Replace this with a one-paragraph description of what your product does, ' +
+                'who it is for, and what pain it solves. Franklin will use this verbatim as ' +
+                'the AI persona when replying to relevant posts.',
+            trigger_keywords: [],
+        },
+    ],
+    x: {
+        search_queries: [],
+        daily_target: 20,
+        min_delay_seconds: 300,
+        max_length: 260,
+        login_detection: '',
+    },
+    reply_style: {
+        rules: [
+            'Sound like a real human with experience, not a bot',
+            'Be specific — reference details from the post you are replying to',
+            'Maximum 2-3 sentences, conversational tone',
+            'No marketing speak, no emojis, no hashtags',
+            'If the product fits naturally, mention it once and only once',
+            'If the product does not fit, reply with just: SKIP',
+        ],
+        model_tier: 'cheap',
+    },
+};
+/**
+ * Load config from disk. If missing, write defaults and return them.
+ * Returns the parsed config or throws on malformed JSON.
+ */
+export function loadConfig() {
+    const dir = path.dirname(CONFIG_PATH);
+    if (!fs.existsSync(dir))
+        fs.mkdirSync(dir, { recursive: true });
+    if (!fs.existsSync(CONFIG_PATH)) {
+        fs.writeFileSync(CONFIG_PATH, JSON.stringify(DEFAULT_CONFIG, null, 2));
+        return { ...DEFAULT_CONFIG };
+    }
+    const raw = fs.readFileSync(CONFIG_PATH, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (parsed.version !== 1) {
+        throw new Error(`Unsupported social config version ${parsed.version} (expected 1)`);
+    }
+    return parsed;
+}
+/**
+ * Persist config back to disk.
+ */
+export function saveConfig(cfg) {
+    const dir = path.dirname(CONFIG_PATH);
+    if (!fs.existsSync(dir))
+        fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(CONFIG_PATH, JSON.stringify(cfg, null, 2));
+}
+/**
+ * Whether the config is "ready" to run — has a handle and at least one
+ * product with keywords.
+ */
+export function isConfigReady(cfg) {
+    if (!cfg.handle)
+        return { ready: false, reason: 'handle not set' };
+    if (cfg.products.length === 0)
+        return { ready: false, reason: 'no products configured' };
+    const hasKeywords = cfg.products.some((p) => p.trigger_keywords.length > 0);
+    if (!hasKeywords)
+        return { ready: false, reason: 'no trigger keywords on any product' };
+    if (cfg.x.search_queries.length === 0)
+        return { ready: false, reason: 'no x.search_queries configured' };
+    return { ready: true };
+}

package/dist/social/db.d.ts

@@ -0,0 +1,102 @@
+/**
+ * JSONL-backed dedup + reply log for Franklin's social subsystem.
+ *
+ * Deliberately avoids SQLite (no new native dep). Two files at:
+ *
+ *   ~/.blockrun/social-replies.jsonl    — append-only reply log
+ *   ~/.blockrun/social-prekeys.jsonl    — append-only snippet-level dedup
+ *
+ * Both are read into memory at startup for O(1) lookups. At 30 replies/day
+ * this hits 10K rows after a year — still <1MB, still fits in memory.
+ *
+ * Schema improvements over social-bot's bot/db.py:
+ *   - `status: 'failed'` does NOT block retry (social-bot blacklists failures
+ *     permanently, which breaks on transient network errors)
+ *   - Pre-key dedup happens BEFORE LLM call, saving tokens on duplicates
+ *   - Per-platform + per-handle scoping so running the bot with two accounts
+ *     against the same DB doesn't cross-contaminate
+ */
+export type ReplyStatus = 'posted' | 'failed' | 'skipped' | 'drafted';
+export type Platform = 'x' | 'reddit';
+export interface ReplyRecord {
+    platform: Platform;
+    handle: string;
+    post_url: string;
+    post_title: string;
+    post_snippet: string;
+    reply_text: string;
+    product?: string;
+    status: ReplyStatus;
+    error_msg?: string;
+    cost_usd?: number;
+    created_at: string;
+}
+export interface PreKeyRecord {
+    platform: Platform;
+    handle: string;
+    pre_key: string;
+    created_at: string;
+}
+/**
+ * Compute a stable pre-key for a candidate post from its snippet fields.
+ * Used BEFORE the LLM generates a reply so we can skip duplicates without
+ * wasting any tokens.
+ */
+export declare function computePreKey(parts: {
+    author?: string;
+    snippet: string;
+    time?: string;
+}): string;
+/**
+ * Has this post been seen before (by pre-key)? If true, skip generation.
+ */
+export declare function hasPreKey(platform: Platform, handle: string, preKey: string): boolean;
+/**
+ * Commit a pre-key so we don't re-consider this post. Called after we've
+ * decided to act on a post (either drafted, posted, or skipped by AI).
+ */
+export declare function commitPreKey(platform: Platform, handle: string, preKey: string): void;
+/**
+ * Has this canonical URL been successfully posted to before?
+ *
+ * Only counts status='posted' — unlike social-bot, we do NOT permanently
+ * blacklist 'failed' attempts, so transient errors can be retried.
+ */
+export declare function hasPosted(platform: Platform, handle: string, postUrl: string): boolean;
+/**
+ * Count today's successful posts for a handle/platform (used for daily caps).
+ */
+export declare function countPostedToday(platform: Platform, handle: string): number;
+/**
+ * Append a reply record. Status can be 'drafted' (dry-run), 'posted',
+ * 'failed' (transient, retry OK), or 'skipped' (AI returned SKIP).
+ */
+export declare function logReply(rec: Omit<ReplyRecord, 'created_at' | 'post_url'> & {
+    post_url: string;
+}): void;
+/**
+ * Stats summary for `franklin social stats`.
+ */
+export declare function getStats(platform?: Platform, handle?: string): {
+    total: number;
+    posted: number;
+    failed: number;
+    skipped: number;
+    drafted: number;
+    today: number;
+    totalCost: number;
+    byProduct: Record<string, number>;
+};
+/**
+ * Canonicalise a URL for stable dedup keys:
+ *   - lowercase host
+ *   - strip trailing slash
+ *   - strip tracking params (?s=, ?t=, utm_*)
+ *   - x.com and twitter.com are aliases
+ */
+export declare function normaliseUrl(raw: string): string;
+/**
+ * Test helper — reset in-memory indexes so the next call re-reads from disk.
+ * Not exported from the public API via index.ts.
+ */
+export declare function _resetForTest(): void;