wopr-plugin-tailscale-funnel 1.0.0

package/.claude/settings.json

@@ -0,0 +1,9 @@
+{
+  "pluginMarketplaces": [
+    {
+      "name": "wopr-marketplace",
+      "source": "https://github.com/wopr-network/wopr-claude-hooks"
+    }
+  ],
+  "enabledPlugins": ["wopr-hooks@wopr-marketplace"]
+}

package/.github/workflows/claude.yml

@@ -0,0 +1,30 @@
+name: Claude Code Review
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+
+jobs:
+  claude:
+    if: |
+      github.event_name == 'pull_request' ||
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude'))
+    runs-on: [self-hosted, Linux, X64]
+    permissions:
+      contents: read
+      pull-requests: write
+      issues: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          github_token: ${{ secrets.GITHUB_TOKEN }}

package/CLAUDE.md

@@ -0,0 +1,37 @@
+# wopr-plugin-tailscale-funnel
+
+Expose WOPR services externally via Tailscale Funnel — provides a public HTTPS URL without port forwarding.
+
+## Commands
+
+```bash
+npm run build     # tsc
+npm run check     # biome check + tsc --noEmit (run before committing)
+npm run format    # biome format --write src/
+npm test          # vitest run
+```
+
+## Architecture
+
+```
+src/
+  index.ts  # Plugin entry — starts tailscale funnel, registers public URL
+  types.ts  # Plugin-local types
+```
+
+## Key Details
+
+- **Requires Tailscale** installed and authenticated on the host (`tailscale` CLI must be in PATH)
+- Runs `tailscale funnel <port>` to expose the WOPR daemon publicly
+- Registers the resulting public URL with plugins that need it (webhooks, GitHub, Slack HTTP mode, etc.)
+- **Use case**: local dev with webhooks — avoids ngrok, cloudflare tunnel, etc.
+- **Gotcha**: Tailscale Funnel must be enabled in the Tailscale admin console for the device before this works
+- **Gotcha**: Funnel URL is stable per device name — bookmark it
+
+## Plugin Contract
+
+Imports only from `@wopr-network/plugin-types`. Never import from `@wopr-network/wopr` core.
+
+## Issue Tracking
+
+All issues in **Linear** (team: WOPR). Issue descriptions start with `**Repo:** wopr-network/wopr-plugin-tailscale-funnel`.

package/README.md

@@ -0,0 +1,128 @@
+# wopr-plugin-tailscale-funnel
+
+Expose WOPR services to the internet via [Tailscale Funnel](https://tailscale.com/kb/1223/funnel).
+
+> **Note:** Tailscale Funnel only supports **one port at a time**. Exposing a new port will automatically stop the previous funnel.
+
+## Prerequisites
+
+- [Tailscale](https://tailscale.com/download) installed and running (`tailscale up`)
+- Funnel enabled on your tailnet (see [Tailscale docs](https://tailscale.com/kb/1223/funnel#setup))
+
+## Installation
+
+```bash
+wopr plugin add wopr-network/wopr-plugin-tailscale-funnel
+```
+
+## Configuration
+
+In your WOPR config (`~/.wopr/config.json`):
+
+```json
+{
+  "plugins": {
+    "wopr-plugin-tailscale-funnel": {
+      "enabled": true,
+      "expose": { "port": 7437, "path": "/" }
+    }
+  }
+}
+```
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | boolean | `true` | Enable/disable the plugin |
+| `expose` | object | - | Port to auto-expose on startup (one port only) |
+
+## CLI Commands
+
+```bash
+# Check funnel status
+wopr funnel status
+
+# Expose a port (replaces any existing funnel)
+wopr funnel expose 8080
+
+# Stop exposing a port
+wopr funnel unexpose 8080
+```
+
+## Extension API
+
+Other plugins can use the funnel extension:
+
+```typescript
+const funnel = ctx.getExtension("funnel") as FunnelExtension;
+
+// Check availability
+const available = await funnel.isAvailable();
+
+// Get public hostname
+const hostname = await funnel.getHostname();
+
+// Expose a port and get public URL (replaces any existing funnel)
+const url = await funnel.expose(8080, "/api");
+
+// Stop exposing
+await funnel.unexpose(8080);
+
+// Get URL for the currently exposed port
+const existingUrl = funnel.getUrl(8080);
+
+// Get full status
+const status = funnel.getStatus();
+```
+
+## How It Works
+
+1. Plugin checks if Tailscale is installed and connected
+2. When exposing a port, it runs `tailscale funnel <port>` in the background
+3. Traffic to `https://<your-hostname>.ts.net/` routes to `localhost:<port>`
+4. Other plugins (like `wopr-plugin-github`) can use the extension to get public URLs
+5. **Only one funnel can be active** - exposing a new port stops the previous one
+
+## Limitations
+
+- **Single port only:** Tailscale Funnel supports one exposed port at a time per machine
+- Exposing a new port will automatically stop any existing funnel
+
+## Operational Notes
+
+### Tailscale Must Be Running First
+
+Tailscale daemon (`tailscaled`) must be running before WOPR starts. In containerized environments:
+
+```bash
+# Ensure tailscale is up
+tailscale up --authkey=<your-key>
+
+# Clear any conflicting listeners before starting funnel
+tailscale serve reset
+
+# Then start WOPR
+wopr daemon
+```
+
+### Container Setup
+
+For Docker containers, run in privileged mode and ensure Tailscale auto-starts:
+
+```dockerfile
+# In your entrypoint
+tailscaled --state=/var/lib/tailscale/tailscaled.state &
+sleep 2
+tailscale up --authkey=${TAILSCALE_AUTHKEY}
+```
+
+### Troubleshooting
+
+- **"listener already exists"**: Run `tailscale serve reset` to clear existing funnels
+- **Funnel not accessible**: Verify funnel is enabled on your tailnet in the admin console
+- **Port not exposed**: Check `tailscale funnel status` for current state
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * WOPR Tailscale Funnel Plugin
+ *
+ * Exposes local WOPR services to the internet via Tailscale Funnel.
+ * Other plugins can use the funnel extension to get public URLs.
+ */
+import type { WOPRPlugin, FunnelExtension, FunnelStatus, FunnelInfo } from "./types.js";
+declare const plugin: WOPRPlugin;
+export default plugin;
+export type { FunnelExtension, FunnelStatus, FunnelInfo };

package/dist/index.js

@@ -0,0 +1,308 @@
+/**
+ * WOPR Tailscale Funnel Plugin
+ *
+ * Exposes local WOPR services to the internet via Tailscale Funnel.
+ * Other plugins can use the funnel extension to get public URLs.
+ */
+import { spawn, execSync, spawnSync } from "node:child_process";
+// ============================================================================
+// State
+// ============================================================================
+let ctx = null;
+let hostname = null;
+let available = null;
+// Tailscale Funnel only supports ONE active funnel at a time
+// Exposing a new port will replace the previous one
+let activeFunnel = null;
+// ============================================================================
+// Tailscale CLI Helpers
+// ============================================================================
+function exec(cmd) {
+    try {
+        return execSync(cmd, { encoding: "utf-8", timeout: 10000 }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+async function checkTailscaleAvailable() {
+    if (available !== null)
+        return available;
+    // Check if tailscale CLI exists (cross-platform: 'where' on Windows, 'which' elsewhere)
+    const isWindows = process.platform === "win32";
+    const whichCmd = isWindows ? "where tailscale" : "which tailscale";
+    const which = exec(whichCmd);
+    if (!which) {
+        ctx?.log.warn("Tailscale CLI not found. Install from https://tailscale.com/download");
+        available = false;
+        return false;
+    }
+    // Check if tailscale is running and connected
+    const status = exec("tailscale status --json");
+    if (!status) {
+        ctx?.log.warn("Tailscale not running or not connected");
+        available = false;
+        return false;
+    }
+    try {
+        const parsed = JSON.parse(status);
+        if (parsed.BackendState !== "Running") {
+            ctx?.log.warn(`Tailscale backend state: ${parsed.BackendState}`);
+            available = false;
+            return false;
+        }
+        // Extract hostname
+        hostname = parsed.Self?.DNSName?.replace(/\.$/, "") || null;
+        if (hostname) {
+            ctx?.log.info(`Tailscale connected: ${hostname}`);
+        }
+        available = true;
+        return true;
+    }
+    catch {
+        available = false;
+        return false;
+    }
+}
+async function getTailscaleHostname() {
+    if (hostname)
+        return hostname;
+    await checkTailscaleAvailable();
+    return hostname;
+}
+async function startFunnel(port, path = "/") {
+    if (!(await checkTailscaleAvailable())) {
+        return null;
+    }
+    if (!hostname) {
+        ctx?.log.error("No Tailscale hostname available");
+        return null;
+    }
+    // Check if already exposed on this port
+    if (activeFunnel?.active && activeFunnel.port === port) {
+        ctx?.log.debug?.(`Port ${port} already exposed at ${activeFunnel.publicUrl}`);
+        return activeFunnel.publicUrl;
+    }
+    // Tailscale only supports ONE funnel at a time - stop any existing funnel
+    if (activeFunnel?.active) {
+        ctx?.log.info(`Replacing existing funnel on port ${activeFunnel.port} with port ${port}`);
+        await stopFunnel(activeFunnel.port);
+    }
+    // Build public URL
+    // Funnel always uses HTTPS on port 443
+    const publicUrl = `https://${hostname}${path === "/" ? "" : path}`;
+    try {
+        // Start funnel in background
+        // tailscale funnel <port> exposes on 443 by default
+        const funnelProcess = spawn("tailscale", ["funnel", String(port)], {
+            detached: true,
+            stdio: "ignore",
+        });
+        // Handle spawn errors (e.g., tailscale not found)
+        funnelProcess.on("error", (err) => {
+            ctx?.log.error(`Funnel process error for port ${port}: ${err.message}`);
+            if (activeFunnel?.port === port) {
+                activeFunnel = null;
+            }
+        });
+        funnelProcess.unref();
+        // Store state - note: we can't verify funnel actually started since it's detached
+        // The error handler above will clear state if spawn fails
+        activeFunnel = {
+            port,
+            path,
+            publicUrl,
+            active: true,
+            pid: funnelProcess.pid,
+        };
+        ctx?.log.info(`Funnel started: ${publicUrl} -> localhost:${port}`);
+        return publicUrl;
+    }
+    catch (err) {
+        ctx?.log.error(`Failed to spawn funnel for port ${port}: ${err}`);
+        return null;
+    }
+}
+async function stopFunnel(port) {
+    if (!activeFunnel || activeFunnel.port !== port) {
+        return false;
+    }
+    // Stop the funnel using spawnSync with args array (safer than shell string)
+    const result = spawnSync("tailscale", ["funnel", String(port), "off"], {
+        encoding: "utf-8",
+        timeout: 10000,
+    });
+    if (result.status !== 0) {
+        ctx?.log.warn(`tailscale funnel ${port} off may have failed: ${result.stderr || ""}`);
+    }
+    // Also try to kill the process if we have the PID
+    if (activeFunnel.pid) {
+        try {
+            process.kill(activeFunnel.pid, "SIGTERM");
+        }
+        catch {
+            // Process may already be dead
+        }
+    }
+    activeFunnel = null;
+    ctx?.log.info(`Funnel stopped for port ${port}`);
+    return true;
+}
+// ============================================================================
+// Extension
+// ============================================================================
+const funnelExtension = {
+    async isAvailable() {
+        return checkTailscaleAvailable();
+    },
+    async getHostname() {
+        return getTailscaleHostname();
+    },
+    async expose(port, path) {
+        return startFunnel(port, path || "/");
+    },
+    async unexpose(port) {
+        return stopFunnel(port);
+    },
+    getUrl(port) {
+        return activeFunnel?.port === port ? activeFunnel.publicUrl : null;
+    },
+    getStatus() {
+        return {
+            available: available ?? false,
+            hostname: hostname || undefined,
+            funnels: activeFunnel ? [activeFunnel] : [],
+        };
+    },
+};
+// ============================================================================
+// Plugin
+// ============================================================================
+const plugin = {
+    name: "wopr-plugin-tailscale-funnel",
+    version: "1.0.0",
+    description: "Expose WOPR services externally via Tailscale Funnel",
+    configSchema: {
+        title: "Tailscale Funnel",
+        description: "Expose a local service to the internet via Tailscale Funnel (one port at a time)",
+        fields: [
+            {
+                name: "enabled",
+                type: "boolean",
+                label: "Enable Funnel",
+                description: "Enable Tailscale Funnel integration",
+                default: true,
+            },
+            {
+                name: "expose",
+                type: "object",
+                label: "Auto-expose port",
+                description: "Port to automatically expose on startup (only one supported)",
+            },
+        ],
+    },
+    commands: [
+        {
+            name: "funnel",
+            description: "Tailscale Funnel management",
+            usage: "wopr funnel <status|expose|unexpose> [port]",
+            async handler(cmdCtx, args) {
+                const [subcommand, portArg] = args;
+                if (subcommand === "status") {
+                    const status = funnelExtension.getStatus();
+                    if (!status.available) {
+                        cmdCtx.log.info("Tailscale Funnel: not available");
+                        cmdCtx.log.info("  Make sure Tailscale is installed and running");
+                        return;
+                    }
+                    cmdCtx.log.info(`Tailscale Funnel: available`);
+                    cmdCtx.log.info(`  Hostname: ${status.hostname}`);
+                    cmdCtx.log.info(`  Active funnels: ${status.funnels.length}`);
+                    for (const f of status.funnels) {
+                        cmdCtx.log.info(`    - ${f.publicUrl} -> localhost:${f.port}`);
+                    }
+                    return;
+                }
+                if (subcommand === "expose") {
+                    if (!portArg) {
+                        cmdCtx.log.error("Usage: wopr funnel expose <port>");
+                        return;
+                    }
+                    const port = parseInt(portArg, 10);
+                    if (isNaN(port)) {
+                        cmdCtx.log.error("Invalid port number");
+                        return;
+                    }
+                    const url = await funnelExtension.expose(port);
+                    if (url) {
+                        cmdCtx.log.info(`Exposed: ${url} -> localhost:${port}`);
+                    }
+                    else {
+                        cmdCtx.log.error("Failed to expose port");
+                    }
+                    return;
+                }
+                if (subcommand === "unexpose") {
+                    if (!portArg) {
+                        cmdCtx.log.error("Usage: wopr funnel unexpose <port>");
+                        return;
+                    }
+                    const port = parseInt(portArg, 10);
+                    if (isNaN(port)) {
+                        cmdCtx.log.error("Invalid port number");
+                        return;
+                    }
+                    const success = await funnelExtension.unexpose(port);
+                    if (success) {
+                        cmdCtx.log.info(`Stopped funnel for port ${port}`);
+                    }
+                    else {
+                        cmdCtx.log.error("Failed to stop funnel");
+                    }
+                    return;
+                }
+                cmdCtx.log.info("Usage: wopr funnel <status|expose|unexpose> [port]");
+            },
+        },
+    ],
+    async init(pluginCtx) {
+        ctx = pluginCtx;
+        const config = ctx.getConfig();
+        if (config?.enabled === false) {
+            ctx.log.info("Tailscale Funnel plugin loaded (disabled)");
+            return;
+        }
+        // Check availability first
+        const isAvailable = await checkTailscaleAvailable();
+        if (!isAvailable) {
+            ctx.log.warn("Tailscale Funnel not available - install Tailscale and run 'tailscale up'");
+            // Don't register extension if Tailscale isn't available
+            return;
+        }
+        // Register extension only after confirming Tailscale is available
+        ctx.registerExtension("funnel", funnelExtension);
+        // Auto-expose configured port (only one supported by Tailscale)
+        if (config?.expose) {
+            // Support both old array format (use first item) and new object format
+            const exposeConfig = Array.isArray(config.expose) ? config.expose[0] : config.expose;
+            if (exposeConfig?.port) {
+                const url = await startFunnel(exposeConfig.port, exposeConfig.path);
+                if (url) {
+                    ctx.log.info(`Auto-exposed: ${url}`);
+                }
+            }
+        }
+        ctx.log.info("Tailscale Funnel plugin initialized");
+    },
+    async shutdown() {
+        // Stop active funnel if any
+        if (activeFunnel) {
+            await stopFunnel(activeFunnel.port);
+        }
+        ctx?.unregisterExtension("funnel");
+        ctx = null;
+        hostname = null;
+        available = null;
+    },
+};
+export default plugin;

package/dist/types.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Tailscale Funnel Plugin Types
+ */
+export interface FunnelConfig {
+    enabled?: boolean;
+    /**
+     * Auto-expose this port on init.
+     * Note: Tailscale Funnel only supports ONE port at a time.
+     * Also accepts array for backwards compatibility (only first item used).
+     */
+    expose?: FunnelExpose | FunnelExpose[];
+}
+export interface FunnelExpose {
+    /** Local port to expose */
+    port: number;
+    /** Optional path prefix (default: /) */
+    path?: string;
+}
+export interface FunnelStatus {
+    available: boolean;
+    hostname?: string;
+    funnels: FunnelInfo[];
+}
+export interface FunnelInfo {
+    port: number;
+    path: string;
+    publicUrl: string;
+    active: boolean;
+}
+/**
+ * Extension interface exposed to other plugins
+ */
+export interface FunnelExtension {
+    /** Check if Tailscale Funnel is available */
+    isAvailable(): Promise<boolean>;
+    /** Get the Tailscale hostname (e.g., wopr.tailnet.ts.net) */
+    getHostname(): Promise<string | null>;
+    /** Expose a local port via funnel, returns public URL */
+    expose(port: number, path?: string): Promise<string | null>;
+    /** Stop exposing a port */
+    unexpose(port: number): Promise<boolean>;
+    /** Get public URL for an exposed port */
+    getUrl(port: number): string | null;
+    /** Get status of all funnels */
+    getStatus(): FunnelStatus;
+}
+export interface WOPRPluginContext {
+    log: {
+        info(msg: string): void;
+        warn(msg: string): void;
+        error(msg: string): void;
+        debug?(msg: string): void;
+    };
+    getConfig<T>(): T | undefined;
+    registerExtension(name: string, extension: unknown): void;
+    unregisterExtension(name: string): void;
+    getExtension(name: string): unknown;
+}
+export interface WOPRPlugin {
+    name: string;
+    version: string;
+    description?: string;
+    configSchema?: {
+        title: string;
+        description: string;
+        fields: Array<{
+            name: string;
+            type: string;
+            label?: string;
+            description?: string;
+            required?: boolean;
+            default?: unknown;
+        }>;
+    };
+    commands?: Array<{
+        name: string;
+        description: string;
+        usage?: string;
+        handler: (ctx: WOPRPluginContext, args: string[]) => Promise<void>;
+    }>;
+    init?(ctx: WOPRPluginContext): Promise<void>;
+    shutdown?(): Promise<void>;
+}

package/dist/types.js

@@ -0,0 +1,4 @@
+/**
+ * Tailscale Funnel Plugin Types
+ */
+export {};

package/package.json

@@ -0,0 +1,29 @@
+{
+  "author": "WOPR",
+  "description": "Expose WOPR services externally via Tailscale Funnel",
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.14",
+    "@types/node": "^25.2.0",
+    "typescript": "^5.3.3"
+  },
+  "keywords": [
+    "wopr",
+    "plugin",
+    "tailscale",
+    "funnel",
+    "tunnel"
+  ],
+  "license": "MIT",
+  "main": "dist/index.js",
+  "name": "wopr-plugin-tailscale-funnel",
+  "scripts": {
+    "build": "tsc",
+    "check": "biome check src/ && tsc --noEmit",
+    "dev": "tsc --watch",
+    "format": "biome format --write src/",
+    "lint": "biome check src/",
+    "lint:fix": "biome check --fix src/"
+  },
+  "type": "module",
+  "version": "1.0.0"
+}

package/src/index.ts

@@ -0,0 +1,360 @@
+/**
+ * WOPR Tailscale Funnel Plugin
+ *
+ * Exposes local WOPR services to the internet via Tailscale Funnel.
+ * Other plugins can use the funnel extension to get public URLs.
+ */
+
+import { spawn, execSync, spawnSync } from "node:child_process";
+import type {
+  WOPRPlugin,
+  WOPRPluginContext,
+  FunnelConfig,
+  FunnelExtension,
+  FunnelStatus,
+  FunnelInfo,
+} from "./types.js";
+
+// ============================================================================
+// State
+// ============================================================================
+
+let ctx: WOPRPluginContext | null = null;
+let hostname: string | null = null;
+let available: boolean | null = null;
+
+// Tailscale Funnel only supports ONE active funnel at a time
+// Exposing a new port will replace the previous one
+let activeFunnel: (FunnelInfo & { pid?: number }) | null = null;
+
+// ============================================================================
+// Tailscale CLI Helpers
+// ============================================================================
+
+function exec(cmd: string): string | null {
+  try {
+    return execSync(cmd, { encoding: "utf-8", timeout: 10000 }).trim();
+  } catch {
+    return null;
+  }
+}
+
+async function checkTailscaleAvailable(): Promise<boolean> {
+  if (available !== null) return available;
+
+  // Check if tailscale CLI exists (cross-platform: 'where' on Windows, 'which' elsewhere)
+  const isWindows = process.platform === "win32";
+  const whichCmd = isWindows ? "where tailscale" : "which tailscale";
+  const which = exec(whichCmd);
+  if (!which) {
+    ctx?.log.warn("Tailscale CLI not found. Install from https://tailscale.com/download");
+    available = false;
+    return false;
+  }
+
+  // Check if tailscale is running and connected
+  const status = exec("tailscale status --json");
+  if (!status) {
+    ctx?.log.warn("Tailscale not running or not connected");
+    available = false;
+    return false;
+  }
+
+  try {
+    const parsed = JSON.parse(status);
+    if (parsed.BackendState !== "Running") {
+      ctx?.log.warn(`Tailscale backend state: ${parsed.BackendState}`);
+      available = false;
+      return false;
+    }
+
+    // Extract hostname
+    hostname = parsed.Self?.DNSName?.replace(/\.$/, "") || null;
+    if (hostname) {
+      ctx?.log.info(`Tailscale connected: ${hostname}`);
+    }
+
+    available = true;
+    return true;
+  } catch {
+    available = false;
+    return false;
+  }
+}
+
+async function getTailscaleHostname(): Promise<string | null> {
+  if (hostname) return hostname;
+  await checkTailscaleAvailable();
+  return hostname;
+}
+
+async function startFunnel(port: number, path: string = "/"): Promise<string | null> {
+  if (!(await checkTailscaleAvailable())) {
+    return null;
+  }
+
+  if (!hostname) {
+    ctx?.log.error("No Tailscale hostname available");
+    return null;
+  }
+
+  // Check if already exposed on this port
+  if (activeFunnel?.active && activeFunnel.port === port) {
+    ctx?.log.debug?.(`Port ${port} already exposed at ${activeFunnel.publicUrl}`);
+    return activeFunnel.publicUrl;
+  }
+
+  // Tailscale only supports ONE funnel at a time - stop any existing funnel
+  if (activeFunnel?.active) {
+    ctx?.log.info(`Replacing existing funnel on port ${activeFunnel.port} with port ${port}`);
+    await stopFunnel(activeFunnel.port);
+  }
+
+  // Build public URL
+  // Funnel always uses HTTPS on port 443
+  const publicUrl = `https://${hostname}${path === "/" ? "" : path}`;
+
+  try {
+    // Start funnel in background
+    // tailscale funnel <port> exposes on 443 by default
+    const funnelProcess = spawn("tailscale", ["funnel", String(port)], {
+      detached: true,
+      stdio: "ignore",
+    });
+
+    // Handle spawn errors (e.g., tailscale not found)
+    funnelProcess.on("error", (err) => {
+      ctx?.log.error(`Funnel process error for port ${port}: ${err.message}`);
+      if (activeFunnel?.port === port) {
+        activeFunnel = null;
+      }
+    });
+
+    funnelProcess.unref();
+
+    // Store state - note: we can't verify funnel actually started since it's detached
+    // The error handler above will clear state if spawn fails
+    activeFunnel = {
+      port,
+      path,
+      publicUrl,
+      active: true,
+      pid: funnelProcess.pid,
+    };
+
+    ctx?.log.info(`Funnel started: ${publicUrl} -> localhost:${port}`);
+    return publicUrl;
+  } catch (err) {
+    ctx?.log.error(`Failed to spawn funnel for port ${port}: ${err}`);
+    return null;
+  }
+}
+
+async function stopFunnel(port: number): Promise<boolean> {
+  if (!activeFunnel || activeFunnel.port !== port) {
+    return false;
+  }
+
+  // Stop the funnel using spawnSync with args array (safer than shell string)
+  const result = spawnSync("tailscale", ["funnel", String(port), "off"], {
+    encoding: "utf-8",
+    timeout: 10000,
+  });
+  if (result.status !== 0) {
+    ctx?.log.warn(`tailscale funnel ${port} off may have failed: ${result.stderr || ""}`);
+  }
+
+  // Also try to kill the process if we have the PID
+  if (activeFunnel.pid) {
+    try {
+      process.kill(activeFunnel.pid, "SIGTERM");
+    } catch {
+      // Process may already be dead
+    }
+  }
+
+  activeFunnel = null;
+  ctx?.log.info(`Funnel stopped for port ${port}`);
+  return true;
+}
+
+// ============================================================================
+// Extension
+// ============================================================================
+
+const funnelExtension: FunnelExtension = {
+  async isAvailable() {
+    return checkTailscaleAvailable();
+  },
+
+  async getHostname() {
+    return getTailscaleHostname();
+  },
+
+  async expose(port: number, path?: string) {
+    return startFunnel(port, path || "/");
+  },
+
+  async unexpose(port: number) {
+    return stopFunnel(port);
+  },
+
+  getUrl(port: number) {
+    return activeFunnel?.port === port ? activeFunnel.publicUrl : null;
+  },
+
+  getStatus(): FunnelStatus {
+    return {
+      available: available ?? false,
+      hostname: hostname || undefined,
+      funnels: activeFunnel ? [activeFunnel] : [],
+    };
+  },
+};
+
+// ============================================================================
+// Plugin
+// ============================================================================
+
+const plugin: WOPRPlugin = {
+  name: "wopr-plugin-tailscale-funnel",
+  version: "1.0.0",
+  description: "Expose WOPR services externally via Tailscale Funnel",
+
+  configSchema: {
+    title: "Tailscale Funnel",
+    description: "Expose a local service to the internet via Tailscale Funnel (one port at a time)",
+    fields: [
+      {
+        name: "enabled",
+        type: "boolean",
+        label: "Enable Funnel",
+        description: "Enable Tailscale Funnel integration",
+        default: true,
+      },
+      {
+        name: "expose",
+        type: "object",
+        label: "Auto-expose port",
+        description: "Port to automatically expose on startup (only one supported)",
+      },
+    ],
+  },
+
+  commands: [
+    {
+      name: "funnel",
+      description: "Tailscale Funnel management",
+      usage: "wopr funnel <status|expose|unexpose> [port]",
+      async handler(cmdCtx, args) {
+        const [subcommand, portArg] = args;
+
+        if (subcommand === "status") {
+          const status = funnelExtension.getStatus();
+          if (!status.available) {
+            cmdCtx.log.info("Tailscale Funnel: not available");
+            cmdCtx.log.info("  Make sure Tailscale is installed and running");
+            return;
+          }
+          cmdCtx.log.info(`Tailscale Funnel: available`);
+          cmdCtx.log.info(`  Hostname: ${status.hostname}`);
+          cmdCtx.log.info(`  Active funnels: ${status.funnels.length}`);
+          for (const f of status.funnels) {
+            cmdCtx.log.info(`    - ${f.publicUrl} -> localhost:${f.port}`);
+          }
+          return;
+        }
+
+        if (subcommand === "expose") {
+          if (!portArg) {
+            cmdCtx.log.error("Usage: wopr funnel expose <port>");
+            return;
+          }
+          const port = parseInt(portArg, 10);
+          if (isNaN(port)) {
+            cmdCtx.log.error("Invalid port number");
+            return;
+          }
+          const url = await funnelExtension.expose(port);
+          if (url) {
+            cmdCtx.log.info(`Exposed: ${url} -> localhost:${port}`);
+          } else {
+            cmdCtx.log.error("Failed to expose port");
+          }
+          return;
+        }
+
+        if (subcommand === "unexpose") {
+          if (!portArg) {
+            cmdCtx.log.error("Usage: wopr funnel unexpose <port>");
+            return;
+          }
+          const port = parseInt(portArg, 10);
+          if (isNaN(port)) {
+            cmdCtx.log.error("Invalid port number");
+            return;
+          }
+          const success = await funnelExtension.unexpose(port);
+          if (success) {
+            cmdCtx.log.info(`Stopped funnel for port ${port}`);
+          } else {
+            cmdCtx.log.error("Failed to stop funnel");
+          }
+          return;
+        }
+
+        cmdCtx.log.info("Usage: wopr funnel <status|expose|unexpose> [port]");
+      },
+    },
+  ],
+
+  async init(pluginCtx) {
+    ctx = pluginCtx;
+    const config = ctx.getConfig<FunnelConfig>();
+
+    if (config?.enabled === false) {
+      ctx.log.info("Tailscale Funnel plugin loaded (disabled)");
+      return;
+    }
+
+    // Check availability first
+    const isAvailable = await checkTailscaleAvailable();
+    if (!isAvailable) {
+      ctx.log.warn("Tailscale Funnel not available - install Tailscale and run 'tailscale up'");
+      // Don't register extension if Tailscale isn't available
+      return;
+    }
+
+    // Register extension only after confirming Tailscale is available
+    ctx.registerExtension("funnel", funnelExtension);
+
+    // Auto-expose configured port (only one supported by Tailscale)
+    if (config?.expose) {
+      // Support both old array format (use first item) and new object format
+      const exposeConfig = Array.isArray(config.expose) ? config.expose[0] : config.expose;
+      if (exposeConfig?.port) {
+        const url = await startFunnel(exposeConfig.port, exposeConfig.path);
+        if (url) {
+          ctx.log.info(`Auto-exposed: ${url}`);
+        }
+      }
+    }
+
+    ctx.log.info("Tailscale Funnel plugin initialized");
+  },
+
+  async shutdown() {
+    // Stop active funnel if any
+    if (activeFunnel) {
+      await stopFunnel(activeFunnel.port);
+    }
+
+    ctx?.unregisterExtension("funnel");
+    ctx = null;
+    hostname = null;
+    available = null;
+  },
+};
+
+export default plugin;
+export type { FunnelExtension, FunnelStatus, FunnelInfo };

package/src/types.ts

@@ -0,0 +1,95 @@
+/**
+ * Tailscale Funnel Plugin Types
+ */
+
+export interface FunnelConfig {
+  enabled?: boolean;
+  /**
+   * Auto-expose this port on init.
+   * Note: Tailscale Funnel only supports ONE port at a time.
+   * Also accepts array for backwards compatibility (only first item used).
+   */
+  expose?: FunnelExpose | FunnelExpose[];
+}
+
+export interface FunnelExpose {
+  /** Local port to expose */
+  port: number;
+  /** Optional path prefix (default: /) */
+  path?: string;
+}
+
+export interface FunnelStatus {
+  available: boolean;
+  hostname?: string;
+  funnels: FunnelInfo[];
+}
+
+export interface FunnelInfo {
+  port: number;
+  path: string;
+  publicUrl: string;
+  active: boolean;
+}
+
+/**
+ * Extension interface exposed to other plugins
+ */
+export interface FunnelExtension {
+  /** Check if Tailscale Funnel is available */
+  isAvailable(): Promise<boolean>;
+
+  /** Get the Tailscale hostname (e.g., wopr.tailnet.ts.net) */
+  getHostname(): Promise<string | null>;
+
+  /** Expose a local port via funnel, returns public URL */
+  expose(port: number, path?: string): Promise<string | null>;
+
+  /** Stop exposing a port */
+  unexpose(port: number): Promise<boolean>;
+
+  /** Get public URL for an exposed port */
+  getUrl(port: number): string | null;
+
+  /** Get status of all funnels */
+  getStatus(): FunnelStatus;
+}
+
+export interface WOPRPluginContext {
+  log: {
+    info(msg: string): void;
+    warn(msg: string): void;
+    error(msg: string): void;
+    debug?(msg: string): void;
+  };
+  getConfig<T>(): T | undefined;
+  registerExtension(name: string, extension: unknown): void;
+  unregisterExtension(name: string): void;
+  getExtension(name: string): unknown;
+}
+
+export interface WOPRPlugin {
+  name: string;
+  version: string;
+  description?: string;
+  configSchema?: {
+    title: string;
+    description: string;
+    fields: Array<{
+      name: string;
+      type: string;
+      label?: string;
+      description?: string;
+      required?: boolean;
+      default?: unknown;
+    }>;
+  };
+  commands?: Array<{
+    name: string;
+    description: string;
+    usage?: string;
+    handler: (ctx: WOPRPluginContext, args: string[]) => Promise<void>;
+  }>;
+  init?(ctx: WOPRPluginContext): Promise<void>;
+  shutdown?(): Promise<void>;
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}