@reefclaw/openclaw-plugin 0.1.0

package/bridge/setup.d.ts

@@ -0,0 +1,32 @@
+export interface ConnectBundle {
+    token?: string;
+    userId?: string;
+    relayUrl?: string;
+}
+/**
+ * Extract token / userId / relayUrl from the onboarding "connect message"
+ * (or a bare token). Deterministic, order-independent, tolerant of any prose
+ * the agent/user wraps around it — so `--setup "<pasted message>"` works whether
+ * the user pasted just the token or the full three-line bundle. Mirrors the
+ * format produced by webapp onboarding (token/userId/relayUrl lines).
+ */
+export declare function parseConnectBundle(text: string): ConnectBundle;
+export declare function validateToken(token: string): {
+    valid: boolean;
+    error?: string;
+};
+/**
+ * Attempts a WebSocket connection to the relay to verify the token is valid.
+ * Connects, waits for auth ack, then disconnects.
+ * Returns { success, message }.
+ */
+export declare function testConnection(token: string, userId: string, relayUrl?: string): Promise<{
+    success: boolean;
+    message: string;
+}>;
+/**
+ * Run the setup flow.
+ * - If token provided: validate, test, save to config
+ * - If no token: print instructions
+ */
+export declare function runSetup(tokenOrBundle?: string, userId?: string, relayUrl?: string): Promise<void>;

package/bridge/setup.js

@@ -0,0 +1,226 @@
+// Interactive setup helper for the ReefClaw skill.
+// Validates token format, tests relay connection, saves to OpenClaw config.
+import WebSocket from 'ws';
+import { execSync } from 'node:child_process';
+import { writeOpenClawConfig } from './config.js';
+import { logger } from './logger.js';
+const TAG = 'setup';
+const DEFAULT_RELAY_URL = 'wss://reefclaw.radunlupsa.partykit.dev';
+const TOKEN_PREFIX = 'rc_';
+const TOKEN_MIN_LENGTH = 10; // rc_ + at least 7 chars
+const CONNECTION_TEST_TIMEOUT_MS = 10_000;
+/**
+ * Extract token / userId / relayUrl from the onboarding "connect message"
+ * (or a bare token). Deterministic, order-independent, tolerant of any prose
+ * the agent/user wraps around it — so `--setup "<pasted message>"` works whether
+ * the user pasted just the token or the full three-line bundle. Mirrors the
+ * format produced by webapp onboarding (token/userId/relayUrl lines).
+ */
+export function parseConnectBundle(text) {
+    const out = {};
+    if (!text)
+        return out;
+    const tokenMatch = text.match(/rc_[A-Za-z0-9_-]{7,}/);
+    if (tokenMatch)
+        out.token = tokenMatch[0];
+    const uuidMatch = text.match(/[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}/);
+    if (uuidMatch)
+        out.userId = uuidMatch[0];
+    const relayMatch = text.match(/wss:\/\/[^\s'"]+/);
+    if (relayMatch)
+        out.relayUrl = relayMatch[0];
+    return out;
+}
+// ---- Token validation ----
+export function validateToken(token) {
+    if (!token) {
+        return { valid: false, error: 'Token is empty' };
+    }
+    if (!token.startsWith(TOKEN_PREFIX)) {
+        return { valid: false, error: `Token must start with "${TOKEN_PREFIX}"` };
+    }
+    if (token.length < TOKEN_MIN_LENGTH) {
+        return { valid: false, error: `Token is too short (minimum ${TOKEN_MIN_LENGTH} characters)` };
+    }
+    return { valid: true };
+}
+// ---- Connection test ----
+/**
+ * Attempts a WebSocket connection to the relay to verify the token is valid.
+ * Connects, waits for auth ack, then disconnects.
+ * Returns { success, message }.
+ */
+export async function testConnection(token, userId, relayUrl = DEFAULT_RELAY_URL) {
+    return new Promise((resolve) => {
+        // Token is sent via Authorization header so it doesn't appear in edge/proxy/access logs
+        // that capture full request URIs. Same rationale as connector.ts buildUrl().
+        const url = `${relayUrl}/parties/reefclaw/${userId}`;
+        const timer = setTimeout(() => {
+            ws.close();
+            resolve({ success: false, message: 'Connection timed out — relay may be unreachable' });
+        }, CONNECTION_TEST_TIMEOUT_MS);
+        const ws = new WebSocket(url, {
+            headers: { Authorization: `Bearer ${token}` },
+        });
+        ws.on('open', () => {
+            logger.debug(TAG, 'Test connection open, awaiting auth ack');
+        });
+        ws.on('message', (data) => {
+            try {
+                const frame = JSON.parse(data.toString());
+                if (frame.type === 'res' && frame.id === '_connect') {
+                    clearTimeout(timer);
+                    ws.close(1000, 'Setup test complete');
+                    if (frame.ok) {
+                        resolve({ success: true, message: 'Token verified — connection to relay successful' });
+                    }
+                    else {
+                        resolve({
+                            success: false,
+                            message: `Auth rejected: ${frame.error?.message ?? 'unknown error'}`,
+                        });
+                    }
+                }
+            }
+            catch {
+                // Ignore unparseable messages during test
+            }
+        });
+        ws.on('error', (err) => {
+            clearTimeout(timer);
+            resolve({ success: false, message: `Connection failed: ${err.message}` });
+        });
+        ws.on('close', (code) => {
+            clearTimeout(timer);
+            if (code === 4001 || code === 4002) {
+                resolve({ success: false, message: 'Authentication failed — check your token and user ID' });
+            }
+            // Normal close after successful test handled by message handler
+        });
+    });
+}
+// ---- Setup flow ----
+/**
+ * Run the setup flow.
+ * - If token provided: validate, test, save to config
+ * - If no token: print instructions
+ */
+export async function runSetup(tokenOrBundle, userId, relayUrl) {
+    console.log('');
+    console.log('  ReefClaw Skill Setup');
+    console.log('  ====================');
+    console.log('');
+    if (!tokenOrBundle) {
+        printSetupInstructions();
+        return;
+    }
+    // Accept either a bare token OR the full onboarding connect message (which
+    // also carries userId + relayUrl). Explicit args win over parsed values.
+    const parsed = parseConnectBundle(tokenOrBundle);
+    const token = parsed.token ?? tokenOrBundle.trim();
+    const resolvedUserId = userId ?? parsed.userId;
+    const resolvedRelayUrl = relayUrl ?? parsed.relayUrl;
+    // Validate token format
+    const validation = validateToken(token);
+    if (!validation.valid) {
+        console.error(`  Error: ${validation.error}`);
+        console.error('');
+        console.error('  Your token should look like: rc_a1b2c3d4e5f6...');
+        console.error('  Get one at https://reefclaw.com/onboarding');
+        process.exit(1);
+    }
+    console.log('  Token format: OK');
+    // Test connection if userId is available
+    if (resolvedUserId) {
+        console.log('  Testing relay connection...');
+        const result = await testConnection(token, resolvedUserId, resolvedRelayUrl);
+        if (result.success) {
+            console.log(`  Connection: ${result.message}`);
+        }
+        else {
+            console.warn(`  Connection: ${result.message}`);
+            console.warn('  (Token will be saved anyway — you can retry later)');
+        }
+    }
+    else {
+        console.log('  No user ID found — the skill cannot reach the relay without it.');
+        console.log('  Paste the full connect message from https://reefclaw.com/onboarding');
+        console.log('  (it includes the userId line), or pass --user-id <id>.');
+    }
+    // Save to config
+    writeOpenClawConfig(token, resolvedUserId, resolvedRelayUrl);
+    // Create heartbeat cron job if none exists
+    ensureHeartbeatCron();
+    console.log('');
+    console.log('  Setup complete! Token saved to ~/.openclaw/config.json');
+    console.log('');
+    console.log('  Next steps:');
+    console.log('    1. Start your OpenClaw agent');
+    console.log('    2. Open https://reefclaw.com/dashboard');
+    console.log('    3. The skill will connect automatically');
+    console.log('    4. Your agent checks the market every 15 minutes (adjustable via chat)');
+    console.log('');
+}
+// ---- Heartbeat cron ----
+/**
+ * Ensures a heartbeat cron job exists for ReefClaw.
+ * Checks `openclaw cron list` for an existing job with "reefclaw" in the name.
+ * If none found, creates one with 15m default interval.
+ * Non-fatal — if openclaw CLI isn't available or cron fails, setup still succeeds.
+ */
+function ensureHeartbeatCron() {
+    try {
+        // Check if a reefclaw cron already exists
+        const listOutput = execSync('openclaw cron list --json 2>/dev/null', {
+            encoding: 'utf-8',
+            timeout: 15_000,
+        });
+        // Look for any job with "reefclaw" in the name
+        try {
+            const jobs = JSON.parse(listOutput);
+            const existing = (Array.isArray(jobs) ? jobs : []).find((j) => j.name?.toLowerCase().includes('reefclaw'));
+            if (existing) {
+                console.log(`  Heartbeat cron: already exists (${existing.name})`);
+                return;
+            }
+        }
+        catch {
+            // JSON parse failed — maybe not JSON output, check raw text
+            if (listOutput.toLowerCase().includes('reefclaw')) {
+                console.log('  Heartbeat cron: already exists');
+                return;
+            }
+        }
+        // No existing job — create one
+        console.log('  Creating heartbeat cron (every 15m)...');
+        execSync('openclaw cron add --name reefclaw-heartbeat --every 15m --session isolated ' +
+            "--message 'Heartbeat. Run SESSION START mandatory checks, then the full Decision Loop (Steps 0-9) from SKILL.md. Check tradingMode from fetch_balance — it is your source of truth for paper vs live. Use tools in parallel where possible.' 2>&1", { encoding: 'utf-8', timeout: 15_000 });
+        console.log('  Heartbeat cron: created (every 15 minutes)');
+        console.log('  Tip: Ask your agent "change heartbeat to 10 minutes" to adjust');
+    }
+    catch (err) {
+        // Non-fatal — user can create cron manually or agent can create it on first session
+        const msg = err instanceof Error ? err.message : String(err);
+        if (msg.includes('not found') || msg.includes('ENOENT')) {
+            console.log('  Heartbeat cron: skipped (openclaw CLI not in PATH)');
+        }
+        else {
+            console.log(`  Heartbeat cron: skipped (${msg.split('\n')[0]})`);
+        }
+    }
+}
+function printSetupInstructions() {
+    console.log('  To connect your OpenClaw agent to ReefClaw:');
+    console.log('');
+    console.log('  1. Go to https://reefclaw.com and create an account');
+    console.log('  2. Copy your connection token from the onboarding page');
+    console.log('  3. Run this command with your token:');
+    console.log('');
+    console.log('     node dist/index.js --setup rc_YOUR_TOKEN_HERE --user-id YOUR_USER_ID');
+    console.log('');
+    console.log('  Or tell your OpenClaw agent:');
+    console.log('     "Here\'s my ReefClaw token: rc_YOUR_TOKEN_HERE"');
+    console.log('');
+    console.log('  The agent will save it automatically. No manual config editing needed.');
+    console.log('');
+}