@auxiora/tailscale 1.0.0

package/dist/types.js

@@ -0,0 +1,7 @@
+export const DEFAULT_TAILSCALE_CONFIG = {
+    enabled: false,
+    mode: 'serve',
+    localPort: 3000,
+    https: true,
+};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAiBA,MAAM,CAAC,MAAM,wBAAwB,GAAoB;IACvD,OAAO,EAAE,KAAK;IACd,IAAI,EAAE,OAAO;IACb,SAAS,EAAE,IAAI;IACf,KAAK,EAAE,IAAI;CACZ,CAAC"}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@auxiora/tailscale",
+  "version": "1.0.0",
+  "description": "Tailscale Serve/Funnel integration for exposing Auxiora without manual port forwarding",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@auxiora/logger": "1.0.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/__tests__/tailscale.test.ts

@@ -0,0 +1,224 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import type { CommandExecutor } from '../types.js';
+import { TailscaleManager } from '../manager.js';
+
+function makeMockRunner(): CommandExecutor & {
+  calls: Array<{ command: string; args: string[] }>;
+  setResponse(stdout: string, stderr?: string, exitCode?: number): void;
+  setResponseForArgs(args: string[], stdout: string, stderr?: string, exitCode?: number): void;
+} {
+  const responses = new Map<string, { stdout: string; stderr: string; exitCode: number }>();
+  let defaultResponse = { stdout: '', stderr: '', exitCode: 0 };
+  const calls: Array<{ command: string; args: string[] }> = [];
+
+  return {
+    calls,
+    setResponse(stdout: string, stderr = '', exitCode = 0) {
+      defaultResponse = { stdout, stderr, exitCode };
+    },
+    setResponseForArgs(args: string[], stdout: string, stderr = '', exitCode = 0) {
+      responses.set(args.join(' '), { stdout, stderr, exitCode });
+    },
+    async run(command: string, args: string[]) {
+      calls.push({ command, args });
+      const key = args.join(' ');
+      return responses.get(key) ?? defaultResponse;
+    },
+  };
+}
+
+const TAILSCALE_STATUS_JSON = JSON.stringify({
+  BackendState: 'Running',
+  Self: {
+    HostName: 'my-machine',
+    DNSName: 'my-machine.tail1234.ts.net.',
+    TailscaleIPs: ['100.64.0.1', 'fd7a:115c::1'],
+  },
+  CurrentTailnet: {
+    Name: 'tail1234.ts.net',
+  },
+});
+
+describe('TailscaleManager', () => {
+  let runner: ReturnType<typeof makeMockRunner>;
+  let manager: TailscaleManager;
+
+  beforeEach(() => {
+    runner = makeMockRunner();
+    manager = new TailscaleManager({ enabled: true, localPort: 3000 }, runner);
+  });
+
+  it('requires a CommandExecutor', () => {
+    expect(() => new TailscaleManager()).toThrow('CommandExecutor is required');
+  });
+
+  describe('detect', () => {
+    it('returns true when tailscale CLI is found', async () => {
+      runner.setResponse('1.62.0\n  go1.22');
+      const result = await manager.detect();
+      expect(result).toBe(true);
+      expect(runner.calls[0]).toEqual({ command: 'tailscale', args: ['version'] });
+    });
+
+    it('returns false when tailscale CLI is not found', async () => {
+      runner.setResponse('', 'command not found', 127);
+      const result = await manager.detect();
+      expect(result).toBe(false);
+      expect(manager.getStatus()).toBe('not-installed');
+    });
+  });
+
+  describe('getInfo', () => {
+    it('returns not-installed if tailscale is missing', async () => {
+      runner.setResponse('', 'not found', 127);
+      const info = await manager.getInfo();
+      expect(info.status).toBe('not-installed');
+    });
+
+    it('returns not-running if status command fails', async () => {
+      runner.setResponseForArgs(['version'], '1.62.0', '', 0);
+      runner.setResponseForArgs(['status', '--json'], '', 'daemon not running', 1);
+      const info = await manager.getInfo();
+      expect(info.status).toBe('not-running');
+    });
+
+    it('returns ready with machine info when running', async () => {
+      runner.setResponseForArgs(['version'], '1.62.0', '', 0);
+      runner.setResponseForArgs(['status', '--json'], TAILSCALE_STATUS_JSON, '', 0);
+      const info = await manager.getInfo();
+      expect(info.status).toBe('ready');
+      expect(info.hostname).toBe('my-machine');
+      expect(info.tailnet).toBe('tail1234.ts.net');
+      expect(info.ipAddress).toBe('100.64.0.1');
+    });
+
+    it('returns not-logged-in when backend needs login', async () => {
+      runner.setResponseForArgs(['version'], '1.62.0', '', 0);
+      runner.setResponseForArgs(
+        ['status', '--json'],
+        JSON.stringify({ BackendState: 'NeedsLogin' }),
+        '',
+        0,
+      );
+      const info = await manager.getInfo();
+      expect(info.status).toBe('not-logged-in');
+    });
+
+    it('returns error on invalid JSON', async () => {
+      runner.setResponseForArgs(['version'], '1.62.0', '', 0);
+      runner.setResponseForArgs(['status', '--json'], 'not-json', '', 0);
+      const info = await manager.getInfo();
+      expect(info.status).toBe('error');
+    });
+  });
+
+  describe('serve', () => {
+    it('starts tailscale serve and returns info', async () => {
+      runner.setResponseForArgs(['serve', 'https://localhost:3000'], '', '', 0);
+      runner.setResponseForArgs(['version'], '1.62.0', '', 0);
+      runner.setResponseForArgs(['status', '--json'], TAILSCALE_STATUS_JSON, '', 0);
+
+      const info = await manager.serve();
+      expect(info.status).toBe('serving');
+      expect(info.serveUrl).toBe('https://my-machine.tail1234.ts.net');
+      expect(manager.getActiveMode()).toBe('serve');
+    });
+
+    it('uses custom port', async () => {
+      runner.setResponseForArgs(['serve', 'https://localhost:8080'], '', '', 0);
+      runner.setResponseForArgs(['version'], '1.62.0', '', 0);
+      runner.setResponseForArgs(['status', '--json'], TAILSCALE_STATUS_JSON, '', 0);
+
+      await manager.serve(8080);
+      expect(runner.calls[0]).toEqual({
+        command: 'tailscale',
+        args: ['serve', 'https://localhost:8080'],
+      });
+    });
+
+    it('throws on failure', async () => {
+      runner.setResponse('', 'access denied', 1);
+      await expect(manager.serve()).rejects.toThrow('Tailscale serve failed: access denied');
+    });
+  });
+
+  describe('funnel', () => {
+    it('starts tailscale funnel and returns info', async () => {
+      runner.setResponseForArgs(['funnel', 'https://localhost:3000'], '', '', 0);
+      runner.setResponseForArgs(['version'], '1.62.0', '', 0);
+      runner.setResponseForArgs(['status', '--json'], TAILSCALE_STATUS_JSON, '', 0);
+
+      const info = await manager.funnel();
+      expect(info.status).toBe('serving');
+      expect(info.publicUrl).toBe('https://my-machine.tail1234.ts.net');
+      expect(manager.getActiveMode()).toBe('funnel');
+    });
+
+    it('throws on failure', async () => {
+      runner.setResponse('', 'funnel not enabled', 1);
+      await expect(manager.funnel()).rejects.toThrow('Tailscale funnel failed: funnel not enabled');
+    });
+  });
+
+  describe('stop', () => {
+    it('does nothing when no active mode', async () => {
+      await manager.stop();
+      expect(runner.calls).toHaveLength(0);
+    });
+
+    it('stops active serve', async () => {
+      runner.setResponseForArgs(['serve', 'https://localhost:3000'], '', '', 0);
+      runner.setResponseForArgs(['version'], '1.62.0', '', 0);
+      runner.setResponseForArgs(['status', '--json'], TAILSCALE_STATUS_JSON, '', 0);
+      await manager.serve();
+
+      runner.calls.length = 0;
+      runner.setResponse('', '', 0);
+
+      await manager.stop();
+      expect(runner.calls[0]).toEqual({
+        command: 'tailscale',
+        args: ['serve', '--remove'],
+      });
+      expect(manager.getActiveMode()).toBeNull();
+      expect(manager.getStatus()).toBe('ready');
+    });
+
+    it('stops active funnel', async () => {
+      runner.setResponseForArgs(['funnel', 'https://localhost:3000'], '', '', 0);
+      runner.setResponseForArgs(['version'], '1.62.0', '', 0);
+      runner.setResponseForArgs(['status', '--json'], TAILSCALE_STATUS_JSON, '', 0);
+      await manager.funnel();
+
+      runner.calls.length = 0;
+      runner.setResponse('', '', 0);
+
+      await manager.stop();
+      expect(runner.calls[0]).toEqual({
+        command: 'tailscale',
+        args: ['funnel', '--remove'],
+      });
+    });
+  });
+
+  describe('config', () => {
+    it('uses http when https is disabled', async () => {
+      const mgr = new TailscaleManager({ https: false, localPort: 3000 }, runner);
+      runner.setResponse('', '', 0);
+      runner.setResponseForArgs(['version'], '1.62.0', '', 0);
+      runner.setResponseForArgs(['status', '--json'], TAILSCALE_STATUS_JSON, '', 0);
+
+      await mgr.serve();
+      expect(runner.calls[0]).toEqual({
+        command: 'tailscale',
+        args: ['serve', 'http://localhost:3000'],
+      });
+    });
+
+    it('returns a copy of config', () => {
+      const config = manager.getConfig();
+      expect(config.localPort).toBe(3000);
+      expect(config.enabled).toBe(true);
+    });
+  });
+});

package/src/index.ts

@@ -0,0 +1,9 @@
+export type {
+  TailscaleConfig,
+  TailscaleMode,
+  TailscaleStatus,
+  TailscaleInfo,
+  CommandExecutor,
+} from './types.js';
+export { DEFAULT_TAILSCALE_CONFIG } from './types.js';
+export { TailscaleManager } from './manager.js';

package/src/manager.ts

@@ -0,0 +1,179 @@
+import { getLogger } from '@auxiora/logger';
+import type {
+  TailscaleConfig,
+  TailscaleInfo,
+  TailscaleMode,
+  TailscaleStatus,
+  CommandExecutor,
+} from './types.js';
+import { DEFAULT_TAILSCALE_CONFIG } from './types.js';
+
+const logger = getLogger('tailscale');
+
+/**
+ * Manages Tailscale Serve and Funnel for exposing Auxiora
+ * to the local tailnet or the public internet.
+ */
+export class TailscaleManager {
+  private config: TailscaleConfig;
+  private runner: CommandExecutor;
+  private currentStatus: TailscaleStatus = 'not-installed';
+  private activeMode: TailscaleMode | null = null;
+
+  constructor(config?: Partial<TailscaleConfig>, runner?: CommandExecutor) {
+    this.config = { ...DEFAULT_TAILSCALE_CONFIG, ...config };
+    if (!runner) {
+      throw new Error('CommandExecutor is required — use ProcessCommandRunner for production');
+    }
+    this.runner = runner;
+  }
+
+  /** Detect whether the Tailscale CLI is installed and reachable. */
+  async detect(): Promise<boolean> {
+    const result = await this.runner.run('tailscale', ['version']);
+    if (result.exitCode !== 0) {
+      this.currentStatus = 'not-installed';
+      logger.debug('Tailscale CLI not found');
+      return false;
+    }
+    logger.info('Tailscale CLI detected', { version: result.stdout.trim().split('\n')[0] });
+    return true;
+  }
+
+  /** Get detailed status information from Tailscale. */
+  async getInfo(): Promise<TailscaleInfo> {
+    const installed = await this.detect();
+    if (!installed) {
+      return { status: 'not-installed' };
+    }
+
+    const result = await this.runner.run('tailscale', ['status', '--json']);
+    if (result.exitCode !== 0) {
+      this.currentStatus = 'not-running';
+      return { status: 'not-running' };
+    }
+
+    try {
+      const status = JSON.parse(result.stdout) as {
+        Self?: {
+          HostName?: string;
+          DNSName?: string;
+          TailscaleIPs?: string[];
+        };
+        CurrentTailnet?: { Name?: string };
+        BackendState?: string;
+      };
+
+      if (status.BackendState !== 'Running') {
+        this.currentStatus = status.BackendState === 'NeedsLogin' ? 'not-logged-in' : 'not-running';
+        return { status: this.currentStatus };
+      }
+
+      const hostname = status.Self?.HostName;
+      const dnsName = status.Self?.DNSName;
+      const tailnet = status.CurrentTailnet?.Name;
+      const ipAddress = status.Self?.TailscaleIPs?.[0];
+
+      this.currentStatus = this.activeMode ? 'serving' : 'ready';
+
+      const info: TailscaleInfo = {
+        status: this.currentStatus,
+        hostname,
+        tailnet,
+        ipAddress,
+      };
+
+      if (dnsName && this.activeMode === 'serve') {
+        info.serveUrl = `https://${dnsName.replace(/\.$/, '')}`;
+      }
+      if (dnsName && this.activeMode === 'funnel') {
+        info.publicUrl = `https://${dnsName.replace(/\.$/, '')}`;
+      }
+
+      return info;
+    } catch {
+      this.currentStatus = 'error';
+      return { status: 'error' };
+    }
+  }
+
+  /** Start Tailscale Serve — expose Auxiora on the local tailnet. */
+  async serve(port?: number): Promise<TailscaleInfo> {
+    const targetPort = port ?? this.config.localPort;
+    logger.info('Starting Tailscale Serve', { port: targetPort });
+
+    const proto = this.config.https ? 'https' : 'http';
+    const result = await this.runner.run('tailscale', [
+      'serve',
+      `${proto}://localhost:${targetPort}`,
+    ]);
+
+    if (result.exitCode !== 0) {
+      logger.error('Failed to start Tailscale Serve', { error: new Error(result.stderr) });
+      throw new Error(`Tailscale serve failed: ${result.stderr}`);
+    }
+
+    this.activeMode = 'serve';
+    this.currentStatus = 'serving';
+    logger.info('Tailscale Serve started');
+    return this.getInfo();
+  }
+
+  /** Start Tailscale Funnel — expose Auxiora to the public internet. */
+  async funnel(port?: number): Promise<TailscaleInfo> {
+    const targetPort = port ?? this.config.localPort;
+    logger.info('Starting Tailscale Funnel', { port: targetPort });
+
+    const proto = this.config.https ? 'https' : 'http';
+    const result = await this.runner.run('tailscale', [
+      'funnel',
+      `${proto}://localhost:${targetPort}`,
+    ]);
+
+    if (result.exitCode !== 0) {
+      logger.error('Failed to start Tailscale Funnel', { error: new Error(result.stderr) });
+      throw new Error(`Tailscale funnel failed: ${result.stderr}`);
+    }
+
+    this.activeMode = 'funnel';
+    this.currentStatus = 'serving';
+    logger.info('Tailscale Funnel started');
+    return this.getInfo();
+  }
+
+  /** Stop any active Tailscale Serve or Funnel. */
+  async stop(): Promise<void> {
+    if (!this.activeMode) {
+      logger.debug('No active Tailscale serve/funnel to stop');
+      return;
+    }
+
+    logger.info('Stopping Tailscale serve/funnel', { mode: this.activeMode });
+
+    const command = this.activeMode === 'funnel' ? 'funnel' : 'serve';
+    const result = await this.runner.run('tailscale', [command, '--remove']);
+
+    if (result.exitCode !== 0) {
+      logger.warn('Failed to cleanly stop Tailscale', { error: new Error(result.stderr) });
+    }
+
+    this.activeMode = null;
+    this.currentStatus = 'ready';
+    logger.info('Tailscale stopped');
+  }
+
+  /** Get the current status. */
+  getStatus(): TailscaleStatus {
+    return this.currentStatus;
+  }
+
+  /** Get the active mode (serve, funnel, or null). */
+  getActiveMode(): TailscaleMode | null {
+    return this.activeMode;
+  }
+
+  /** Get the current config. */
+  getConfig(): TailscaleConfig {
+    return { ...this.config };
+  }
+}

package/src/types.ts

@@ -0,0 +1,52 @@
+/** Tailscale exposure mode. */
+export type TailscaleMode = 'serve' | 'funnel';
+
+/** Configuration for Tailscale integration. */
+export interface TailscaleConfig {
+  /** Whether Tailscale integration is enabled. */
+  enabled: boolean;
+  /** Exposure mode: serve (local tailnet) or funnel (public internet). */
+  mode: TailscaleMode;
+  /** Custom hostname for the Tailscale machine (optional). */
+  hostname?: string;
+  /** Local port to proxy traffic to. */
+  localPort: number;
+  /** Whether to use HTTPS on the Tailscale side. */
+  https: boolean;
+}
+
+export const DEFAULT_TAILSCALE_CONFIG: TailscaleConfig = {
+  enabled: false,
+  mode: 'serve',
+  localPort: 3000,
+  https: true,
+};
+
+/** Status of the Tailscale integration. */
+export type TailscaleStatus =
+  | 'not-installed'
+  | 'not-running'
+  | 'not-logged-in'
+  | 'ready'
+  | 'serving'
+  | 'error';
+
+/** Information about the current Tailscale state. */
+export interface TailscaleInfo {
+  status: TailscaleStatus;
+  /** The Tailscale hostname (e.g., "my-machine"). */
+  hostname?: string;
+  /** The tailnet domain (e.g., "tail1234.ts.net"). */
+  tailnet?: string;
+  /** The public URL when serving via funnel. */
+  publicUrl?: string;
+  /** The local tailnet URL when serving via serve. */
+  serveUrl?: string;
+  /** The Tailscale IP address. */
+  ipAddress?: string;
+}
+
+/** Interface for running CLI commands (injectable for testing). */
+export interface CommandExecutor {
+  run(command: string, args: string[]): Promise<{ stdout: string; stderr: string; exitCode: number }>;
+}

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"],
+  "references": [
+    { "path": "../logger" }
+  ]
+}