@blockrun/franklin 3.0.0

package/dist/plugins/registry.js

@@ -0,0 +1,155 @@
+/**
+ * Plugin Registry — discovers, loads, and manages plugins.
+ *
+ * Core stays plugin-agnostic: it knows about the *interface*, not specific plugins.
+ * Plugins are discovered from:
+ *   1. Bundled: <runcode>/plugins-bundled/* (ships with runcode)
+ *   2. User: ~/.blockrun/plugins/* (installed via `runcode plugin install`)
+ *   3. Local dev: $RUNCODE_PLUGINS_DIR/* (env var for development)
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import os from 'node:os';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// ─── Plugin Discovery Paths ───────────────────────────────────────────────
+export function getBundledPluginsDir() {
+    // From dist/plugins/registry.js, plugins-bundled is at ../plugins-bundled
+    // (built from src/plugins-bundled by tsc + copy-plugin-assets)
+    return path.resolve(__dirname, '..', 'plugins-bundled');
+}
+export function getUserPluginsDir() {
+    return path.join(os.homedir(), '.blockrun', 'plugins');
+}
+function getDevPluginsDir() {
+    return process.env.RUNCODE_PLUGINS_DIR || null;
+}
+const loaded = new Map();
+// ─── Discovery ────────────────────────────────────────────────────────────
+/** Find all plugin manifests across discovery paths */
+export function discoverPluginManifests() {
+    const found = [];
+    const seen = new Set();
+    const searchPaths = [];
+    const dev = getDevPluginsDir();
+    if (dev && fs.existsSync(dev))
+        searchPaths.push(dev);
+    const user = getUserPluginsDir();
+    if (fs.existsSync(user))
+        searchPaths.push(user);
+    const bundled = getBundledPluginsDir();
+    if (fs.existsSync(bundled))
+        searchPaths.push(bundled);
+    for (const base of searchPaths) {
+        let entries = [];
+        try {
+            entries = fs.readdirSync(base);
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const pluginDir = path.join(base, entry);
+            const manifestPath = path.join(pluginDir, 'plugin.json');
+            if (!fs.existsSync(manifestPath))
+                continue;
+            try {
+                const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+                if (!manifest.id || seen.has(manifest.id))
+                    continue;
+                seen.add(manifest.id);
+                found.push({ manifest, dir: pluginDir });
+            }
+            catch {
+                // Invalid manifest — skip
+            }
+        }
+    }
+    return found;
+}
+// ─── Loading ──────────────────────────────────────────────────────────────
+/** Load a single plugin from its directory */
+export async function loadPlugin(manifest, pluginDir) {
+    // Resolve entry path. Plugin's entry should point to a built JS file.
+    // For bundled plugins, entry might be "dist/index.js" but we ship from src/.
+    // Check both — prefer dist if present.
+    let entryPath = path.join(pluginDir, manifest.entry);
+    if (!fs.existsSync(entryPath)) {
+        // Try .js extension swap (TS source vs built)
+        const jsEntry = entryPath.replace(/\.ts$/, '.js');
+        if (fs.existsSync(jsEntry))
+            entryPath = jsEntry;
+    }
+    if (!fs.existsSync(entryPath)) {
+        process.stderr.write(`[plugin:${manifest.id}] entry not found: ${manifest.entry}\n`);
+        return null;
+    }
+    try {
+        // Dynamic import — works for both ESM and CJS
+        const mod = await import(entryPath);
+        const plugin = mod.default ?? mod.plugin ?? mod;
+        if (!plugin || typeof plugin !== 'object') {
+            process.stderr.write(`[plugin:${manifest.id}] invalid plugin export\n`);
+            return null;
+        }
+        // Inject manifest if plugin didn't include it
+        plugin.manifest = manifest;
+        return plugin;
+    }
+    catch (err) {
+        process.stderr.write(`[plugin:${manifest.id}] load failed: ${err.message}\n`);
+        return null;
+    }
+}
+/** Discover and load all plugins. Returns the loaded registry. */
+export async function loadAllPlugins() {
+    if (loaded.size > 0)
+        return loaded;
+    const manifests = discoverPluginManifests();
+    for (const { manifest, dir } of manifests) {
+        const plugin = await loadPlugin(manifest, dir);
+        if (plugin) {
+            loaded.set(manifest.id, { manifest, pluginDir: dir, plugin });
+            // Lifecycle hook
+            if (plugin.onLoad) {
+                try {
+                    await plugin.onLoad({
+                        runcodeVersion: getRuncodeVersion(),
+                        dataDir: path.join(os.homedir(), '.blockrun', 'plugins', manifest.id),
+                        pluginDir: dir,
+                        log: (msg) => process.stderr.write(`[${manifest.id}] ${msg}\n`),
+                    });
+                }
+                catch (err) {
+                    process.stderr.write(`[plugin:${manifest.id}] onLoad failed: ${err.message}\n`);
+                }
+            }
+        }
+    }
+    return loaded;
+}
+// ─── Query API ────────────────────────────────────────────────────────────
+export function getPlugin(id) {
+    return loaded.get(id);
+}
+export function listPlugins() {
+    return Array.from(loaded.values());
+}
+/** Get all plugins that provide workflows */
+export function listWorkflowPlugins() {
+    return listPlugins().filter(p => p.plugin.workflows && Object.keys(p.plugin.workflows).length > 0);
+}
+/** Get all plugins that provide channels */
+export function listChannelPlugins() {
+    return listPlugins().filter(p => p.plugin.channels && Object.keys(p.plugin.channels).length > 0);
+}
+// ─── Helpers ──────────────────────────────────────────────────────────────
+function getRuncodeVersion() {
+    try {
+        const pkgPath = path.resolve(__dirname, '..', '..', 'package.json');
+        return JSON.parse(fs.readFileSync(pkgPath, 'utf-8')).version || '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}

package/dist/plugins/runner.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Workflow Runner — orchestrates execution of any Workflow.
+ *
+ * Plugin-agnostic: takes a Workflow + config, runs steps, handles
+ * model dispatch, dedup, tracking, dry-run.
+ */
+import { ModelClient } from '../agent/llm.js';
+import type { Workflow, WorkflowConfig, WorkflowResult } from '../plugin-sdk/workflow.js';
+import type { WorkflowStats, TrackedAction } from '../plugin-sdk/tracker.js';
+export declare function loadWorkflowConfig(workflowId: string): WorkflowConfig | null;
+export declare function saveWorkflowConfig(workflowId: string, config: WorkflowConfig): void;
+interface TrackerEntry extends TrackedAction {
+}
+export declare function getStats(workflow: string): WorkflowStats;
+export declare function getByAction(workflow: string, action: string): TrackerEntry[];
+export declare function runWorkflow(workflow: Workflow, config: WorkflowConfig, client: ModelClient, options?: {
+    dryRun?: boolean;
+}): Promise<WorkflowResult>;
+export declare function formatWorkflowResult(workflow: Workflow, result: WorkflowResult): string;
+export declare function formatWorkflowStats(workflow: Workflow, stats: WorkflowStats): string;
+export {};

package/dist/plugins/runner.js

@@ -0,0 +1,453 @@
+/**
+ * Workflow Runner — orchestrates execution of any Workflow.
+ *
+ * Plugin-agnostic: takes a Workflow + config, runs steps, handles
+ * model dispatch, dedup, tracking, dry-run.
+ */
+import path from 'node:path';
+import os from 'node:os';
+import fs from 'node:fs';
+import { estimateCost } from '../pricing.js';
+import { USER_AGENT } from '../config.js';
+import { DEFAULT_MODEL_TIERS } from '../plugin-sdk/workflow.js';
+// ─── Storage ──────────────────────────────────────────────────────────────
+const WORKFLOW_DIR = path.join(os.homedir(), '.blockrun', 'workflows');
+function ensureDir() {
+    fs.mkdirSync(WORKFLOW_DIR, { recursive: true });
+}
+function getDbPath(workflow) {
+    return path.join(WORKFLOW_DIR, `${workflow}.jsonl`);
+}
+function getConfigPath(workflow) {
+    return path.join(WORKFLOW_DIR, `${workflow}.config.json`);
+}
+// ─── Config Persistence ───────────────────────────────────────────────────
+export function loadWorkflowConfig(workflowId) {
+    try {
+        const p = getConfigPath(workflowId);
+        if (fs.existsSync(p)) {
+            const raw = JSON.parse(fs.readFileSync(p, 'utf-8'));
+            raw.models = { ...DEFAULT_MODEL_TIERS, ...raw.models };
+            raw.name = workflowId;
+            return raw;
+        }
+    }
+    catch { /* corrupt */ }
+    return null;
+}
+export function saveWorkflowConfig(workflowId, config) {
+    ensureDir();
+    fs.writeFileSync(getConfigPath(workflowId), JSON.stringify(config, null, 2) + '\n', { mode: 0o600 });
+}
+function trackAction(workflow, action, key, metadata = {}, costUsd = 0) {
+    ensureDir();
+    const entry = {
+        workflow,
+        action,
+        key,
+        metadata,
+        costUsd,
+        createdAt: new Date().toISOString(),
+    };
+    fs.appendFileSync(getDbPath(workflow), JSON.stringify(entry) + '\n');
+}
+function isDuplicate(workflow, key) {
+    const dbPath = getDbPath(workflow);
+    if (!fs.existsSync(dbPath))
+        return false;
+    try {
+        const lines = fs.readFileSync(dbPath, 'utf-8').split('\n').filter(Boolean);
+        for (const line of lines) {
+            try {
+                const entry = JSON.parse(line);
+                if (entry.key === key)
+                    return true;
+            }
+            catch { /* skip */ }
+        }
+    }
+    catch { /* no db */ }
+    return false;
+}
+export function getStats(workflow) {
+    const stats = {
+        totalRuns: 0,
+        totalActions: 0,
+        totalCostUsd: 0,
+        todayActions: 0,
+        todayCostUsd: 0,
+        byAction: {},
+    };
+    const dbPath = getDbPath(workflow);
+    if (!fs.existsSync(dbPath))
+        return stats;
+    const today = new Date().toISOString().slice(0, 10);
+    try {
+        const lines = fs.readFileSync(dbPath, 'utf-8').split('\n').filter(Boolean);
+        for (const line of lines) {
+            try {
+                const entry = JSON.parse(line);
+                stats.totalActions++;
+                stats.totalCostUsd += entry.costUsd;
+                stats.byAction[entry.action] = (stats.byAction[entry.action] || 0) + 1;
+                if (entry.action === 'run_start')
+                    stats.totalRuns++;
+                if (entry.createdAt.startsWith(today)) {
+                    stats.todayActions++;
+                    stats.todayCostUsd += entry.costUsd;
+                }
+                stats.lastRun = entry.createdAt;
+            }
+            catch { /* skip */ }
+        }
+    }
+    catch { /* no db */ }
+    return stats;
+}
+export function getByAction(workflow, action) {
+    const dbPath = getDbPath(workflow);
+    if (!fs.existsSync(dbPath))
+        return [];
+    try {
+        const lines = fs.readFileSync(dbPath, 'utf-8').split('\n').filter(Boolean);
+        return lines.map(l => { try {
+            return JSON.parse(l);
+        }
+        catch {
+            return null;
+        } })
+            .filter((e) => e !== null && e.action === action);
+    }
+    catch {
+        return [];
+    }
+}
+// ─── Model Tier Resolution ────────────────────────────────────────────────
+function resolveModel(tier, tiers) {
+    switch (tier) {
+        case 'free': return tiers.free;
+        case 'cheap': return tiers.cheap;
+        case 'premium': return tiers.premium;
+        case 'none': return null;
+    }
+}
+// ─── Channel Search Adapter ───────────────────────────────────────────────
+import { listChannelPlugins } from './registry.js';
+/** Default web search fallback using DuckDuckGo HTML */
+async function defaultWebSearch(query, options) {
+    const maxResults = Math.min(Math.max(options?.maxResults ?? 8, 1), 20);
+    const domainHints = (options?.sources ?? [])
+        .map(sourceToDomainHint)
+        .filter((domain) => Boolean(domain));
+    const scopedQueries = Array.from(new Set([
+        ...domainHints.map((domain) => `${query} site:${domain}`),
+        query,
+    ])).slice(0, 3);
+    const merged = [];
+    const seenUrls = new Set();
+    for (const scoped of scopedQueries) {
+        const results = await searchDuckDuckGo(scoped, maxResults);
+        for (const result of results) {
+            if (seenUrls.has(result.url))
+                continue;
+            seenUrls.add(result.url);
+            merged.push(result);
+            if (merged.length >= maxResults)
+                return merged;
+        }
+    }
+    if (merged.length === 0 && scopedQueries[scopedQueries.length - 1] !== query) {
+        return searchDuckDuckGo(query, maxResults);
+    }
+    return merged;
+}
+function sourceToDomainHint(source) {
+    const normalized = source.toLowerCase();
+    if (normalized === 'reddit')
+        return 'reddit.com';
+    if (normalized === 'x' || normalized === 'twitter')
+        return 'x.com';
+    if (normalized === 'web')
+        return null;
+    return null;
+}
+async function searchDuckDuckGo(query, maxResults) {
+    try {
+        const url = `https://html.duckduckgo.com/html/?q=${encodeURIComponent(query)}`;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 15_000);
+        const response = await fetch(url, {
+            signal: controller.signal,
+            headers: { 'User-Agent': USER_AGENT },
+        });
+        clearTimeout(timer);
+        if (!response.ok)
+            return [];
+        const html = await response.text();
+        return parseDuckDuckGoResults(html, maxResults);
+    }
+    catch {
+        return [];
+    }
+}
+function parseDuckDuckGoResults(html, maxResults) {
+    const results = [];
+    const linkRegex = /<a[^>]*class="result__a"[^>]*href="([^"]*)"[^>]*>([\s\S]*?)<\/a>/gi;
+    const snippetRegex = /<a[^>]*class="result__snippet"[^>]*>([\s\S]*?)<\/a>/gi;
+    let links = [...html.matchAll(linkRegex)];
+    const snippets = [...html.matchAll(snippetRegex)];
+    if (links.length === 0) {
+        const fallbackLink = /<a[^>]*class="[^"]*result[^"]*"[^>]*href="([^"]*)"[^>]*>([\s\S]*?)<\/a>/gi;
+        links = [...html.matchAll(fallbackLink)];
+    }
+    for (let i = 0; i < Math.min(links.length, maxResults); i++) {
+        const link = links[i];
+        const snippet = snippets[i];
+        const decodedUrl = decodeDuckDuckGoUrl(link[1] ?? '');
+        if (!decodedUrl || decodedUrl.startsWith('/') || decodedUrl.includes('duckduckgo.com'))
+            continue;
+        results.push({
+            title: stripHtml(link[2] ?? '').trim(),
+            url: decodedUrl,
+            snippet: stripHtml(snippet?.[1] ?? '').trim(),
+            source: inferSource(decodedUrl),
+        });
+    }
+    return results;
+}
+function decodeDuckDuckGoUrl(url) {
+    const uddg = url.match(/[?&]uddg=([^&]+)/);
+    if (uddg?.[1]) {
+        try {
+            return decodeURIComponent(uddg[1]);
+        }
+        catch {
+            return url;
+        }
+    }
+    return url;
+}
+function inferSource(url) {
+    const lower = url.toLowerCase();
+    if (lower.includes('reddit.com'))
+        return 'reddit';
+    if (lower.includes('x.com') || lower.includes('twitter.com'))
+        return 'x';
+    return 'web';
+}
+function stripHtml(input) {
+    return input
+        .replace(/<[^>]+>/g, '')
+        .replace(/&amp;/g, '&')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, '\'')
+        .replace(/&nbsp;/g, ' ')
+        .replace(/\s+/g, ' ');
+}
+/** Resolve channel by id and call its search method */
+async function searchViaChannel(channelId, query, options) {
+    const channelPlugins = listChannelPlugins();
+    for (const cp of channelPlugins) {
+        if (cp.plugin.channels?.[channelId]) {
+            const channel = cp.plugin.channels[channelId]();
+            try {
+                const result = await channel.search(query, {
+                    log: (msg) => process.stderr.write(`[${channelId}] ${msg}\n`),
+                    dryRun: false,
+                }, { maxResults: options?.maxResults });
+                return result.posts.map(p => ({
+                    title: p.title,
+                    url: p.url,
+                    snippet: p.body,
+                    source: p.platform,
+                    author: p.author,
+                    timestamp: p.createdAt,
+                    score: p.score,
+                    commentCount: p.commentCount,
+                }));
+            }
+            catch (err) {
+                process.stderr.write(`[${channelId}] search failed: ${err.message}\n`);
+            }
+        }
+    }
+    return [];
+}
+// ─── Workflow Runner ──────────────────────────────────────────────────────
+export async function runWorkflow(workflow, config, client, options = {}) {
+    const dryRun = options.dryRun ?? false;
+    const start = Date.now();
+    const stepResults = [];
+    let totalCost = 0;
+    let itemsProcessed = 0;
+    const data = {};
+    const tiers = config.models ?? DEFAULT_MODEL_TIERS;
+    trackAction(workflow.id, 'run_start', `run-${Date.now()}`, { dryRun });
+    // Lifecycle hook
+    if (workflow.beforeRun) {
+        try {
+            await workflow.beforeRun(config);
+        }
+        catch (err) {
+            process.stderr.write(`[${workflow.id}] beforeRun failed: ${err.message}\n`);
+        }
+    }
+    const ctx = {
+        data,
+        config,
+        dryRun,
+        callModel: async (tier, prompt, system) => {
+            if (tier === 'none')
+                throw new Error('Cannot call model with tier "none"');
+            const model = resolveModel(tier, tiers);
+            if (!model)
+                throw new Error(`No model resolved for tier ${tier}`);
+            const result = await client.complete({
+                model,
+                messages: [{ role: 'user', content: prompt }],
+                system,
+                max_tokens: 4096,
+                stream: true,
+            });
+            let text = '';
+            for (const part of result.content) {
+                if (part.type === 'text')
+                    text += part.text;
+            }
+            const cost = estimateCost(model, result.usage.inputTokens, result.usage.outputTokens, 1);
+            totalCost += cost;
+            return text;
+        },
+        search: async (query, opts) => {
+            // Try channel search first if scope hints at a channel
+            if (opts?.sources && opts.sources.length > 0) {
+                for (const source of opts.sources) {
+                    const results = await searchViaChannel(source, query, opts);
+                    if (results.length > 0)
+                        return results;
+                }
+            }
+            return defaultWebSearch(query, opts);
+        },
+        sendMessage: async (channelId, message) => {
+            if (dryRun) {
+                process.stderr.write(`[${workflow.id}] [dry-run] would send to ${channelId}\n`);
+                return;
+            }
+            const channelPlugins = listChannelPlugins();
+            for (const cp of channelPlugins) {
+                if (cp.plugin.channels?.[channelId]) {
+                    const channel = cp.plugin.channels[channelId]();
+                    await channel.post(message, {
+                        log: (msg) => process.stderr.write(`[${channelId}] ${msg}\n`),
+                        dryRun,
+                    });
+                    return;
+                }
+            }
+            throw new Error(`Channel "${channelId}" not found`);
+        },
+        log: (msg) => process.stderr.write(`[${workflow.id}] ${msg}\n`),
+        track: async (action, metadata) => {
+            trackAction(workflow.id, action, `${action}-${Date.now()}`, metadata, 0);
+        },
+        isDuplicate: async (key) => isDuplicate(workflow.id, key),
+    };
+    for (const step of workflow.steps) {
+        if (dryRun && step.skipInDryRun) {
+            stepResults.push({ name: step.name, summary: '[dry-run] skipped', cost: 0, status: 'skipped' });
+            continue;
+        }
+        process.stderr.write(`[${workflow.id}] → ${step.name}...\n`);
+        try {
+            const result = await step.execute(ctx);
+            if (result.data)
+                Object.assign(data, result.data);
+            const stepCost = result.cost ?? 0;
+            totalCost += stepCost;
+            if (result.data?.itemCount)
+                itemsProcessed += result.data.itemCount;
+            stepResults.push({
+                name: step.name,
+                summary: result.summary ?? 'done',
+                cost: stepCost,
+                status: result.abort ? 'aborted' : 'ok',
+            });
+            if (result.abort) {
+                process.stderr.write(`[${workflow.id}] ⚠ ${step.name}: ${result.summary ?? 'aborted'}\n`);
+                break;
+            }
+        }
+        catch (err) {
+            const errMsg = err.message;
+            process.stderr.write(`[${workflow.id}] ✗ ${step.name}: ${errMsg}\n`);
+            stepResults.push({ name: step.name, summary: `error: ${errMsg}`, cost: 0, status: 'error' });
+            break;
+        }
+    }
+    const result = {
+        steps: stepResults,
+        totalCost,
+        itemsProcessed,
+        durationMs: Date.now() - start,
+        dryRun,
+    };
+    trackAction(workflow.id, 'run_complete', `run-${Date.now()}`, {
+        dryRun, totalCost, itemsProcessed, durationMs: result.durationMs,
+    }, totalCost);
+    if (workflow.afterRun) {
+        try {
+            await workflow.afterRun(result);
+        }
+        catch (err) {
+            process.stderr.write(`[${workflow.id}] afterRun failed: ${err.message}\n`);
+        }
+    }
+    return result;
+}
+// ─── Display ──────────────────────────────────────────────────────────────
+export function formatWorkflowResult(workflow, result) {
+    const lines = [];
+    const sep = '─'.repeat(50);
+    lines.push(`\n${sep}`);
+    lines.push(`${workflow.name.toUpperCase()} ${result.dryRun ? '[DRY RUN]' : 'COMPLETE'}`);
+    lines.push(sep);
+    for (const step of result.steps) {
+        const costStr = step.cost > 0 ? ` ($${step.cost.toFixed(4)})` : '';
+        const icon = step.status === 'error'
+            ? '✗'
+            : step.status === 'aborted'
+                ? '⚠'
+                : step.status === 'skipped'
+                    ? '○'
+                    : '✓';
+        lines.push(`  ${icon} ${step.name}: ${step.summary}${costStr}`);
+    }
+    lines.push(sep);
+    lines.push(`  Items: ${result.itemsProcessed}  Cost: $${result.totalCost.toFixed(4)}  Time: ${(result.durationMs / 1000).toFixed(1)}s`);
+    lines.push(`${sep}\n`);
+    return lines.join('\n');
+}
+export function formatWorkflowStats(workflow, stats) {
+    const lines = [];
+    const sep = '─'.repeat(40);
+    lines.push(`\n${sep}\n${workflow.name.toUpperCase()} STATS\n${sep}`);
+    lines.push(`  Total runs: ${stats.totalRuns}`);
+    lines.push(`  Total actions: ${stats.totalActions}`);
+    lines.push(`  Total cost: $${stats.totalCostUsd.toFixed(4)}`);
+    lines.push(`  Today: ${stats.todayActions} actions, $${stats.todayCostUsd.toFixed(4)}`);
+    if (stats.lastRun)
+        lines.push(`  Last run: ${stats.lastRun}`);
+    if (Object.keys(stats.byAction).length > 0) {
+        lines.push(`  By action:`);
+        for (const [action, count] of Object.entries(stats.byAction)) {
+            if (action !== 'run_start' && action !== 'run_complete') {
+                lines.push(`    ${action}: ${count}`);
+            }
+        }
+    }
+    lines.push(`${sep}\n`);
+    return lines.join('\n');
+}

package/dist/plugins-bundled/social/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Social Workflow Plugin.
+ *
+ * IMPORTANT: This file ONLY imports from `../../plugin-sdk/`.
+ * It does NOT import from `src/agent/`, `src/commands/`, `src/social/`, etc.
+ * This is the boundary that keeps plugins decoupled from core internals.
+ */
+import type { Plugin } from '../../plugin-sdk/index.js';
+declare const plugin: Plugin;
+export default plugin;