@reefclaw/connect 0.1.0

package/dist/bridge.js

@@ -0,0 +1,25 @@
+// Install the ReefClaw connector (the relay bridge daemon). Places the skill
+// dist, installs deps, vendors shared. The bridge reads ALL its config from
+// ~/.openclaw/openclaw.json at startup (skills.entries.reefclaw for the relay
+// token/userId/relayUrl, gateway.auth.token for the local gateway) — so we do
+// NOT write a token here; the user supplies it later by pasting the connect
+// message to their agent, and the bridge picks it up on its next restart.
+import { join } from 'node:path';
+import { BRIDGE_DIR, assetsDir, ASSET_BRIDGE, ASSET_SHARED } from './paths.js';
+import { copyAsset, writePackageJson, npmInstall, vendorShared } from './deps.js';
+import { step, ok, info, warn } from './ui.js';
+// Bridge runtime deps — exact-pinned to match deploy-skill.py / the lockfile.
+const BRIDGE_DEPS = { ws: '8.19.0', json5: '2.2.3' };
+export function installBridge() {
+    step('Installing the ReefClaw connector');
+    const assets = assetsDir();
+    copyAsset(join(assets, ASSET_BRIDGE), BRIDGE_DIR);
+    info(`placed connector at ${BRIDGE_DIR}`);
+    writePackageJson(BRIDGE_DIR, 'reefclaw-bridge', BRIDGE_DEPS);
+    info('installing connector dependencies…');
+    if (!npmInstall(BRIDGE_DIR)) {
+        warn('npm install reported a problem; the connector may still start if deps resolved.');
+    }
+    vendorShared(BRIDGE_DIR, join(assets, ASSET_SHARED));
+    ok('connector files ready');
+}

package/dist/bundle.js

@@ -0,0 +1,33 @@
+// Parse the onboarding "connect message" (or a bare token) into its fields.
+//
+// Deterministic, order-independent, tolerant of any prose wrapped around it —
+// so the user can paste the whole message from reefclaw.com/onboarding and we
+// extract exactly the three fields the bridge needs. This is a standalone copy
+// of skill/src/setup.ts:parseConnectBundle (the installer ships independently;
+// the small parser is duplicated rather than shared, same rationale as the ×3
+// redact.ts copies). Keep the two in sync.
+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;
+}
+const DEFAULT_RELAY_URL = 'wss://reefclaw.radunlupsa.partykit.dev';
+/** A bundle is usable iff it carries at least a token + userId (relayUrl
+ *  defaults). Token alone cannot reach the relay — the room URL is keyed by
+ *  userId (skill/src/setup.ts). */
+export function bundleIsComplete(b) {
+    return Boolean(b.token && b.userId);
+}
+export function withDefaults(b) {
+    return { ...b, relayUrl: b.relayUrl || DEFAULT_RELAY_URL };
+}

package/dist/cli.js

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+// ReefClaw connect — `npx @reefclaw/connect`.
+//
+// Installs the ReefClaw trading plugin + connector into the user's OpenClaw and
+// starts the connector as a background service. It does NOT take the connection
+// token — the user links their account afterwards by pasting the connect
+// message from reefclaw.com/onboarding to their agent (paste-to-agent stays the
+// primary connect path). The bridge reads that config from openclaw.json and
+// connects within seconds.
+import { installPlugin } from './plugin.js';
+import { installBridge } from './bridge.js';
+import { installSkill } from './skill.js';
+import { installDaemon } from './daemon.js';
+import { checkGateway } from './validate.js';
+import { readConfig, writeConfig, mergeReefClawConfig, gatewayAuthDowngradeNeeded, openClawInstalled, openClawConfigPath, readGatewayPort, } from './openclaw.js';
+import { run, which } from './exec.js';
+import { step, ok, info, warn, fail, banner, bold, green, cyan, dim } from './ui.js';
+const DASHBOARD = 'https://www.reefclaw.com/dashboard';
+const ONBOARDING = 'https://www.reefclaw.com/onboarding';
+function preflight() {
+    const major = Number(process.versions.node.split('.')[0]);
+    if (Number.isFinite(major) && major < 20) {
+        fail(`Node ${process.versions.node} detected — OpenClaw + ReefClaw need Node 20+.`);
+        process.exit(1);
+    }
+    if (!openClawInstalled()) {
+        fail("Couldn't find an OpenClaw install (no ~/.openclaw directory).");
+        info('Install and run OpenClaw first, then re-run `npx @reefclaw/connect`.');
+        info(`(If your config lives elsewhere, set OPENCLAW_CONFIG_PATH. Looked at: ${openClawConfigPath()})`);
+        process.exit(1);
+    }
+}
+/** Re-write openclaw.json: preserve the user's existing config, overlay the
+ *  ENTIRE plugins section the link wrote (the link can wipe other sections, so
+ *  we start from the PRE snapshot — same approach as deploy-full.py), then
+ *  ensure the sandbox allowlist + gateway scope flags + reefclaw skill entry.
+ *
+ *  The whole plugins section — not just plugins.installs — must come from the
+ *  POST config: `openclaw plugins install --link` writes plugins.load.paths
+ *  (what the gateway actually loads from), plugins.entries.<id>.enabled, AND
+ *  plugins.installs.<id>. Overlaying only `installs` silently drops
+ *  load.paths, and the gateway never loads the plugin (verified live on
+ *  2026.6.11 — deploy-full.py gets away with it only because prod's PRE
+ *  snapshot already contains load.paths from the original manual install). */
+function wireConfig(pre) {
+    step('Wiring OpenClaw config');
+    const post = readConfig();
+    const base = { ...pre };
+    if (post.plugins) {
+        base.plugins = post.plugins;
+    }
+    // Disclose the local gateway auth relaxation the merge is about to apply —
+    // only when it actually changes something (the user's config didn't already
+    // have both flags set). Checked against the pre-link snapshot.
+    if (gatewayAuthDowngradeNeeded(pre)) {
+        warn('Relaxing local gateway device-identity auth (dangerouslyDisableDeviceAuth + allowInsecureAuth).');
+        info('This is required for OpenClaw v2026.4.2+ to keep operator scopes on the WS connection; keep the gateway bound to localhost.');
+    }
+    const merged = mergeReefClawConfig(base);
+    writeConfig(merged);
+    ok('sandbox allowlist (group:plugins) + gateway scope + reefclaw entry ensured');
+    return merged;
+}
+/** The gateway only loads plugins at startup — a plugin registered while it
+ *  runs stays invisible until restart (the bridge would log "No trading tools
+ *  found" forever). Best-effort: a user without a managed gateway just gets
+ *  the manual hint. */
+function restartGateway() {
+    step('Restarting the OpenClaw gateway to load the plugin');
+    if (!which('openclaw')) {
+        info('openclaw CLI not on PATH — restart your gateway manually to load the trading tools.');
+        return;
+    }
+    const r = run('openclaw', ['gateway', 'restart'], { timeoutMs: 120_000 });
+    if (r.ok) {
+        ok('gateway restarted');
+    }
+    else {
+        warn('could not restart the gateway automatically.');
+        info('Restart it yourself (e.g. `openclaw gateway restart`) so the trading tools load.');
+    }
+}
+function nextSteps() {
+    banner(green('✓ ReefClaw is installed.'));
+    process.stdout.write(`\n${bold('One step left — link your account:')}\n` +
+        `  1. Open ${cyan(ONBOARDING)}\n` +
+        `  2. Generate your token, then paste the ${bold('connect message')} to your OpenClaw agent.\n` +
+        `  3. The dashboard lights up ${green('green / Connected')} on its own within a few seconds.\n\n` +
+        dim(`Dashboard: ${DASHBOARD}\n`));
+}
+async function main() {
+    banner(bold(cyan('ReefClaw connect')) + dim('  — link your OpenClaw agent to ReefClaw (paper trading)'));
+    preflight();
+    const pre = readConfig();
+    const plugin = installPlugin();
+    const merged = wireConfig(pre);
+    // After wireConfig: the config is schema-valid (flat legacy keys migrated),
+    // which `openclaw skills install` requires — the CLI refuses to run on an
+    // invalid config.
+    const skill = installSkill();
+    installBridge();
+    const startedService = installDaemon();
+    if (plugin.registered)
+        restartGateway();
+    await checkGateway(readGatewayPort(merged));
+    if (!plugin.registered) {
+        warn('The plugin was placed but not auto-registered — see the message above to finish it.');
+    }
+    if (!skill.installed) {
+        warn('The agent skill was placed but not registered — see the message above to finish it.');
+    }
+    if (!startedService) {
+        warn('The connector was installed but not auto-started — see the run command above.');
+    }
+    nextSteps();
+}
+main().catch((err) => {
+    fail(`Install failed: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+});

package/dist/daemon.js

@@ -0,0 +1,104 @@
+// Keep the bridge running across reboots. Linux/systemd-user is implemented
+// fully; macOS and Windows fall back to printing the manual run command (a
+// launchd/Task-Scheduler unit is a follow-up). The bridge reads its config from
+// ~/.openclaw/openclaw.json, so until the user pastes their connect message the
+// service will start, find no token, and restart — harmless; it connects within
+// seconds of the agent writing the config.
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir, userInfo } from 'node:os';
+import { BRIDGE_DIR } from './paths.js';
+import { run, which } from './exec.js';
+import { step, ok, info, warn } from './ui.js';
+const SERVICE_NAME = 'reefclaw-bridge';
+const NODE = process.execPath; // absolute path to the node running the installer
+/**
+ * Build the systemd user-unit text. Pure + exported so the path-quoting is
+ * unit-testable. Both `node` (process.execPath) and `bridgeDir` (under the
+ * user's home) can contain spaces. Quoting rules differ per directive:
+ *  - ExecStart= is parsed with shell-like word splitting, so an unquoted
+ *    `ExecStart=/home/a b/node …` reads the binary as `/home/a` — QUOTE both
+ *    the binary and the script path.
+ *  - WorkingDirectory= takes the raw value after `=` as a single path (no word
+ *    splitting) — spaces are safe UNQUOTED, and quotes are treated as literal
+ *    characters, failing the unit with "path is not absolute" (verified live
+ *    on systemd 255 / Ubuntu 24.04). Do NOT quote it.
+ */
+export function buildSystemdUnit(node, bridgeDir) {
+    const indexJs = join(bridgeDir, 'index.js');
+    return `[Unit]
+Description=ReefClaw connector - bridges OpenClaw to the ReefClaw dashboard
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+WorkingDirectory=${bridgeDir}
+ExecStart="${node}" "${indexJs}" --provider gateway --log-level info
+Restart=always
+RestartSec=5s
+
+[Install]
+WantedBy=default.target
+`;
+}
+function manualHint() {
+    warn('Could not set up an auto-start service on this OS yet.');
+    info('Keep the connector running with this command (leave it open / use your own service manager):');
+    info(`  "${NODE}" "${join(BRIDGE_DIR, 'index.js')}" --provider gateway`);
+}
+function installSystemd() {
+    if (!which('systemctl'))
+        return false;
+    const unitDir = join(homedir(), '.config', 'systemd', 'user');
+    mkdirSync(unitDir, { recursive: true });
+    const unit = buildSystemdUnit(NODE, BRIDGE_DIR);
+    writeFileSync(join(unitDir, `${SERVICE_NAME}.service`), unit, 'utf-8');
+    run('systemctl', ['--user', 'daemon-reload']);
+    const enabled = run('systemctl', ['--user', 'enable', '--now', `${SERVICE_NAME}.service`]);
+    if (!enabled.ok) {
+        warn('systemd --user enable/start did not succeed:');
+        if (enabled.stderr.trim())
+            info(enabled.stderr.trim().split('\n').slice(-2).join('\n'));
+        info(`Try:  systemctl --user enable --now ${SERVICE_NAME}.service`);
+        return false;
+    }
+    // `enable --now` can exit 0 while the unit failed to load (e.g. a bad unit
+    // file setting) — verify the unit actually came up before claiming ✓.
+    // 'active' = running; 'activating' = the expected pre-token restart loop
+    // (the bridge exits until the user pastes their connect message, and
+    // Restart=always re-launches it). Anything else (inactive/failed) means the
+    // unit never loaded.
+    const active = run('systemctl', ['--user', 'is-active', `${SERVICE_NAME}.service`]);
+    const state = active.stdout.trim();
+    if (state !== 'active' && state !== 'activating') {
+        warn(`the service did not come up (state: ${state || 'unknown'}).`);
+        info(`Inspect:  systemctl --user status ${SERVICE_NAME}.service`);
+        return false;
+    }
+    // Linger lets the user service run without an active login session (servers).
+    // Best-effort: needs privileges; non-fatal if it fails.
+    const linger = run('loginctl', ['enable-linger', userInfo().username]);
+    if (linger.ok) {
+        info('enabled linger (service survives logout / reboot)');
+    }
+    else {
+        info('note: run `sudo loginctl enable-linger $USER` so the connector survives logout.');
+    }
+    return true;
+}
+export function installDaemon() {
+    step('Starting the connector as a background service');
+    if (process.platform === 'linux') {
+        if (installSystemd()) {
+            ok(`connector running as a systemd user service (${SERVICE_NAME})`);
+            info(`logs:  journalctl --user -u ${SERVICE_NAME} -f`);
+            return true;
+        }
+        manualHint();
+        return false;
+    }
+    // macOS / Windows: manual for now (launchd / Task Scheduler unit is a follow-up).
+    manualHint();
+    return false;
+}

package/dist/deps.js

@@ -0,0 +1,41 @@
+// Dependency handling for the placed plugin/bridge dirs. Mirrors what the prod
+// deploy scripts do remotely: write a package.json, `npm install --omit=dev`,
+// then vendor the un-published @reefclaw/shared workspace package into
+// node_modules AFTER install (so npm's prune doesn't drop it).
+import { writeFileSync, cpSync, mkdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { run } from './exec.js';
+export function writePackageJson(dir, name, deps, extra = {}) {
+    const pkg = {
+        name,
+        version: '0.1.0',
+        private: true,
+        type: 'module',
+        main: 'index.js',
+        dependencies: deps,
+        ...extra,
+    };
+    writeFileSync(join(dir, 'package.json'), JSON.stringify(pkg, null, 2) + '\n', 'utf-8');
+}
+export function npmInstall(dir) {
+    const r = run('npm', ['install', '--omit=dev', '--no-audit', '--no-fund'], {
+        cwd: dir,
+        timeoutMs: 600_000,
+    });
+    return r.ok;
+}
+/** Vendor @reefclaw/shared (un-published workspace pkg) into <dir>/node_modules. */
+export function vendorShared(dir, sharedAssetDir) {
+    const dest = join(dir, 'node_modules', '@reefclaw', 'shared');
+    mkdirSync(dest, { recursive: true });
+    // sharedAssetDir holds the shared package's dist/
+    cpSync(sharedAssetDir, join(dest, 'dist'), { recursive: true });
+    writeFileSync(join(dest, 'package.json'), JSON.stringify({ name: '@reefclaw/shared', version: '0.1.0', type: 'module', main: 'dist/index.js' }, null, 2) + '\n', 'utf-8');
+}
+export function copyAsset(srcDir, destDir) {
+    if (!existsSync(srcDir)) {
+        throw new Error(`bundled asset missing: ${srcDir} (was the package built with bundle-assets?)`);
+    }
+    mkdirSync(destDir, { recursive: true });
+    cpSync(srcDir, destDir, { recursive: true });
+}

package/dist/exec.js

@@ -0,0 +1,28 @@
+// Small wrappers around child_process for the installer. Synchronous (the
+// install is a linear script) and resilient — callers decide whether a non-zero
+// exit is fatal.
+import { spawnSync } from 'node:child_process';
+/** Run a command, capturing output. Never throws. */
+export function run(cmd, args, opts = {}) {
+    const r = spawnSync(cmd, args, {
+        cwd: opts.cwd,
+        timeout: opts.timeoutMs ?? 600_000,
+        encoding: 'utf-8',
+        shell: false,
+    });
+    return {
+        ok: r.status === 0,
+        code: r.status,
+        stdout: (r.stdout ?? '').toString(),
+        stderr: (r.stderr ?? '').toString(),
+    };
+}
+/** True if a command resolves on PATH. */
+export function which(cmd) {
+    const probe = process.platform === 'win32' ? 'where' : 'which';
+    const r = run(probe, [cmd], { timeoutMs: 10_000 });
+    if (!r.ok)
+        return null;
+    const first = r.stdout.split(/\r?\n/).map((s) => s.trim()).find(Boolean);
+    return first ?? null;
+}

package/dist/openclaw.js

@@ -0,0 +1,153 @@
+// OpenClaw config discovery + idempotent merge of the ReefClaw settings.
+//
+// We NEVER overwrite the user's openclaw.json — we read it, merge in only the
+// keys ReefClaw needs (preserving everything else), and write it back 0600. The
+// plugin itself is registered by shelling out to `openclaw plugins install
+// --link` (which writes plugins.installs); that must run BEFORE this merge,
+// because that command can wipe channels/gateway/skills sections (see
+// deploy-full.py:145), and this merge then restores/sets our keys on top.
+import { readFileSync, writeFileSync, mkdirSync, existsSync, chmodSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import JSON5 from 'json5';
+/** Core sandbox tools OpenClaw needs PLUS group:plugins — without the latter,
+ *  the plugin's tools are invisible to the agent (plugin-integration.md rule 2). */
+export const REQUIRED_SANDBOX_TOOLS = [
+    'exec',
+    'process',
+    'read',
+    'write',
+    'edit',
+    'apply_patch',
+    'image',
+    'sessions_list',
+    'sessions_history',
+    'sessions_send',
+    'sessions_spawn',
+    'session_status',
+    'group:plugins',
+];
+export function openClawConfigPath() {
+    if (process.env.OPENCLAW_CONFIG_PATH)
+        return process.env.OPENCLAW_CONFIG_PATH;
+    return join(homedir(), '.openclaw', 'openclaw.json');
+}
+export function openClawInstalled(configPath = openClawConfigPath()) {
+    // The .openclaw dir existing is the signal OpenClaw has been run at least
+    // once; the config file itself may not exist yet on a brand-new install.
+    return existsSync(dirname(configPath));
+}
+export function readConfig(configPath = openClawConfigPath()) {
+    try {
+        return JSON5.parse(readFileSync(configPath, 'utf-8'));
+    }
+    catch {
+        return {};
+    }
+}
+function asObject(parent, key) {
+    if (typeof parent[key] !== 'object' || parent[key] === null || Array.isArray(parent[key])) {
+        parent[key] = {};
+    }
+    return parent[key];
+}
+/**
+ * Pure, idempotent merge. Returns a NEW config object with the ReefClaw keys
+ * ensured; never removes or reorders the user's existing settings.
+ *  - tools.sandbox.tools.allow ⊇ REQUIRED_SANDBOX_TOOLS (union, de-duped)
+ *  - gateway.controlUi.{dangerouslyDisableDeviceAuth, allowInsecureAuth} = true
+ *  - skills.entries.reefclaw.{token,userId,relayUrl} set when provided
+ */
+export function mergeReefClawConfig(input, connect = {}) {
+    const cfg = JSON.parse(JSON.stringify(input));
+    // --- sandbox allowlist (union) ---
+    const tools = asObject(cfg, 'tools');
+    const sandbox = asObject(tools, 'sandbox');
+    const sandboxTools = asObject(sandbox, 'tools');
+    const existingAllow = Array.isArray(sandboxTools.allow) ? sandboxTools.allow.map(String) : [];
+    const merged = [...existingAllow];
+    for (const t of REQUIRED_SANDBOX_TOOLS) {
+        if (!merged.includes(t))
+            merged.push(t);
+    }
+    sandboxTools.allow = merged;
+    // --- tool profile widening ---
+    // `openclaw setup` defaults tools.profile to "coding" (2026.6+), whose fixed
+    // core allowlist filters out ALL plugin tools — the agent would see none of
+    // the 62 trading tools. tools.alsoAllow explicitly widens the profile;
+    // group:plugins covers every plugin-provided tool. Union, never replace.
+    const existingAlsoAllow = Array.isArray(tools.alsoAllow) ? tools.alsoAllow.map(String) : [];
+    if (!existingAlsoAllow.includes('group:plugins')) {
+        tools.alsoAllow = [...existingAlsoAllow, 'group:plugins'];
+    }
+    // --- gateway controlUi scope flags (v2026.4.2+ WS scope preservation) ---
+    const gateway = asObject(cfg, 'gateway');
+    const controlUi = asObject(gateway, 'controlUi');
+    controlUi.dangerouslyDisableDeviceAuth = true;
+    controlUi.allowInsecureAuth = true;
+    // --- skills.entries.reefclaw (connection config) ---
+    // OpenClaw's skills.entries.<name> schema only allows {enabled, apiKey, env,
+    // config} — custom fields MUST nest under `config`. Flat fields fail config
+    // validation on OpenClaw 2026.6+ and the GATEWAY REFUSES TO BOOT (verified
+    // live: `skills.entries.reefclaw: Invalid input` → crash loop). Migrate any
+    // legacy flat keys into the nested shape.
+    const skills = asObject(cfg, 'skills');
+    const entries = asObject(skills, 'entries');
+    const reefclaw = asObject(entries, 'reefclaw');
+    const entryConfig = asObject(reefclaw, 'config');
+    for (const key of ['token', 'userId', 'relayUrl']) {
+        if (typeof reefclaw[key] === 'string' && entryConfig[key] === undefined) {
+            entryConfig[key] = reefclaw[key];
+        }
+        delete reefclaw[key];
+    }
+    if (connect.token)
+        entryConfig.token = connect.token;
+    if (connect.userId)
+        entryConfig.userId = connect.userId;
+    if (connect.relayUrl)
+        entryConfig.relayUrl = connect.relayUrl;
+    return cfg;
+}
+export function writeConfig(config, configPath = openClawConfigPath()) {
+    mkdirSync(dirname(configPath), { recursive: true, mode: 0o700 });
+    // File holds the connection token → owner-only.
+    writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', { encoding: 'utf-8', mode: 0o600 });
+    // writeFileSync's `mode` is ONLY applied when the file is created; the common
+    // case here is re-writing an existing openclaw.json, which keeps its old
+    // (possibly world-readable) perms. chmod unconditionally so a token-bearing
+    // config is never left readable by other users. Best-effort — chmod is a
+    // no-op / unsupported on some Windows filesystems, so failure is non-fatal.
+    try {
+        chmodSync(configPath, 0o600);
+    }
+    catch {
+        /* best-effort: some filesystems (Windows) don't support POSIX modes */
+    }
+}
+/**
+ * True when writing our config would flip gateway.controlUi device-identity
+ * auth OFF (either flag not already `true`). The installer sets these to
+ * preserve WS operator scopes on OpenClaw v2026.4.2+, but it relaxes local
+ * gateway auth, so the CLI discloses it to the user when it actually changes
+ * something. Pure so it's unit-testable and callable before the merge.
+ */
+export function gatewayAuthDowngradeNeeded(config) {
+    const gateway = config.gateway;
+    const controlUi = gateway?.controlUi;
+    return controlUi?.dangerouslyDisableDeviceAuth !== true || controlUi?.allowInsecureAuth !== true;
+}
+/** Read the gateway auth token OpenClaw already configured — the bridge needs
+ *  it to call the local gateway. Returns undefined if not set. */
+export function readGatewayToken(config = readConfig()) {
+    const gateway = config.gateway;
+    const auth = gateway?.auth;
+    const token = auth?.token;
+    return typeof token === 'string' ? token : undefined;
+}
+/** Read the gateway port (default 18789). */
+export function readGatewayPort(config = readConfig()) {
+    const gateway = config.gateway;
+    const port = gateway?.port;
+    return typeof port === 'number' ? port : 18789;
+}

package/dist/paths.js

@@ -0,0 +1,23 @@
+// Filesystem layout for a local ReefClaw install.
+//
+// OpenClaw owns ~/.openclaw (config + its own state). ReefClaw's mechanism code
+// lives under ~/.reefclaw so an uninstall is a single rm -rf and we never write
+// into OpenClaw's tree except its config file (via openclaw.ts).
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { dirname } from 'node:path';
+export const REEFCLAW_HOME = join(homedir(), '.reefclaw');
+export const PLUGIN_DIR = join(REEFCLAW_HOME, 'plugin');
+export const BRIDGE_DIR = join(REEFCLAW_HOME, 'bridge');
+/** Directory holding the bundled plugin/bridge/shared dist, shipped inside the
+ *  published npm package. Resolved relative to the compiled cli.js
+ *  (dist/cli.js → ../assets). */
+export function assetsDir() {
+    const here = dirname(fileURLToPath(import.meta.url)); // .../installer/dist
+    return join(here, '..', 'assets');
+}
+export const ASSET_PLUGIN = 'plugin';
+export const ASSET_BRIDGE = 'bridge';
+export const ASSET_SHARED = 'shared';
+export const ASSET_SKILL = 'skill';

package/dist/plugin.js

@@ -0,0 +1,48 @@
+// Install + register the ReefClaw trading plugin (reefclaw-paper-trading) into
+// the user's OpenClaw. Mirrors deploy-full.py: place dist, install deps, vendor
+// shared, then `openclaw plugins install --link`.
+import { join } from 'node:path';
+import { PLUGIN_DIR, assetsDir, ASSET_PLUGIN, ASSET_SHARED } from './paths.js';
+import { copyAsset, writePackageJson, npmInstall, vendorShared } from './deps.js';
+import { run, which } from './exec.js';
+import { step, ok, info, warn, fail } from './ui.js';
+// Plugin runtime deps (mirror plugin/package.json). ws + ccxt; ccxt is large.
+const PLUGIN_DEPS = { ccxt: '^4.4.0', ws: '^8.18.0' };
+export function installPlugin() {
+    step('Installing the ReefClaw trading plugin');
+    const assets = assetsDir();
+    copyAsset(join(assets, ASSET_PLUGIN), PLUGIN_DIR);
+    info(`placed plugin at ${PLUGIN_DIR}`);
+    // `openclaw.extensions` is required by `openclaw plugins install --link`
+    // (2026.6+ hard-fails without it). The placed dir holds the built dist at top
+    // level, so the entry is ./index.js — NOT ./src/index.ts like the repo's
+    // plugin/package.json (see CLAUDE.md "dist/package.json's openclaw entry").
+    writePackageJson(PLUGIN_DIR, 'reefclaw-paper-trading', PLUGIN_DEPS, {
+        openclaw: { extensions: ['./index.js'] },
+    });
+    info('installing plugin dependencies (this can take a minute — ccxt is large)…');
+    if (!npmInstall(PLUGIN_DIR)) {
+        warn('npm install reported a problem; the plugin may still work if deps resolved.');
+    }
+    vendorShared(PLUGIN_DIR, join(assets, ASSET_SHARED));
+    ok('plugin files ready');
+    // Register into OpenClaw. The CLI writes plugins.installs in openclaw.json and
+    // is the canonical path; without it on PATH we cannot reliably register.
+    const cli = which('openclaw');
+    if (!cli) {
+        fail('the `openclaw` CLI is not on your PATH — cannot register the plugin.');
+        info(`Once OpenClaw is on PATH, run:  openclaw plugins install --link ${PLUGIN_DIR}`);
+        return { registered: false };
+    }
+    info('registering the plugin with OpenClaw…');
+    const r = run('openclaw', ['plugins', 'install', '--link', PLUGIN_DIR], { timeoutMs: 300_000 });
+    if (!r.ok) {
+        warn('`openclaw plugins install --link` returned non-zero:');
+        if (r.stderr.trim())
+            info(r.stderr.trim().split('\n').slice(-3).join('\n'));
+        info(`Retry manually:  openclaw plugins install --link ${PLUGIN_DIR}`);
+        return { registered: false };
+    }
+    ok('plugin registered with OpenClaw');
+    return { registered: true };
+}

package/dist/skill.js

@@ -0,0 +1,35 @@
+// Install the ReefClaw bootstrap skill (SKILL.md) into the user's OpenClaw
+// workspace via `openclaw skills install`. This is the local half of the
+// distribution split (docs/TOOL_DISTRIBUTION_ARCHITECTURE.md): the agent needs
+// the config schema + connect instructions BEFORE it has ever connected
+// (chicken-and-egg — there is no central channel yet). Post-connect content
+// updates arrive through the relay OTA channel, not reinstalls.
+import { join } from 'node:path';
+import { REEFCLAW_HOME, assetsDir, ASSET_SKILL } from './paths.js';
+import { copyAsset } from './deps.js';
+import { run, which } from './exec.js';
+import { step, ok, info, warn } from './ui.js';
+const SKILL_DIR = join(REEFCLAW_HOME, 'skill');
+export function installSkill() {
+    step('Installing the ReefClaw agent skill');
+    const assets = assetsDir();
+    copyAsset(join(assets, ASSET_SKILL), SKILL_DIR);
+    info(`placed skill at ${SKILL_DIR}`);
+    const cli = which('openclaw');
+    if (!cli) {
+        warn('the `openclaw` CLI is not on your PATH — cannot register the skill.');
+        info(`Once OpenClaw is on PATH, run:  openclaw skills install ${SKILL_DIR}`);
+        return { installed: false };
+    }
+    // Idempotent: re-install overwrites the workspace copy.
+    const r = run('openclaw', ['skills', 'install', SKILL_DIR], { timeoutMs: 120_000 });
+    if (!r.ok) {
+        warn('`openclaw skills install` returned non-zero:');
+        if (r.stderr.trim())
+            info(r.stderr.trim().split('\n').slice(-3).join('\n'));
+        info(`Retry manually:  openclaw skills install ${SKILL_DIR}`);
+        return { installed: false };
+    }
+    ok('agent skill installed into the OpenClaw workspace');
+    return { installed: true };
+}

package/dist/ui.js

@@ -0,0 +1,29 @@
+// Tiny zero-dependency terminal UI helpers. Colour only when stdout is a TTY.
+const isTTY = process.stdout.isTTY;
+const c = (code, s) => (isTTY ? `\x1b[${code}m${s}\x1b[0m` : s);
+export const bold = (s) => c('1', s);
+export const dim = (s) => c('2', s);
+export const green = (s) => c('32', s);
+export const yellow = (s) => c('33', s);
+export const red = (s) => c('31', s);
+export const cyan = (s) => c('36', s);
+let stepN = 0;
+export function step(msg) {
+    stepN += 1;
+    process.stdout.write(`\n${bold(cyan(`[${stepN}]`))} ${bold(msg)}\n`);
+}
+export function ok(msg) {
+    process.stdout.write(`    ${green('✓')} ${msg}\n`);
+}
+export function info(msg) {
+    process.stdout.write(`    ${dim(msg)}\n`);
+}
+export function warn(msg) {
+    process.stdout.write(`    ${yellow('!')} ${msg}\n`);
+}
+export function fail(msg) {
+    process.stdout.write(`    ${red('✗')} ${msg}\n`);
+}
+export function banner(msg) {
+    process.stdout.write(`\n${bold(msg)}\n`);
+}