@seflless/ghosttown 1.6.1 → 1.7.0

package/src/session/types.ts

@@ -0,0 +1,236 @@
+/**
+ * Session Management Types
+ *
+ * Core types for the custom PTY session management system that replaces tmux.
+ * Sessions persist across reconnections and server restarts.
+ */
+
+/**
+ * Unique identifier for a session (UUID v4).
+ * This ID is stable and survives renames, reconnections, and server restarts.
+ */
+export type SessionId = string;
+
+/**
+ * Share permission level for a session connection.
+ */
+export type SharePermission = 'read-only' | 'read-write';
+
+/**
+ * Configuration for sharing a session with others.
+ */
+export interface SharingConfig {
+  /** Whether sharing is currently enabled */
+  enabled: boolean;
+  /** Secure token for share access (32-byte random, base64url) */
+  token: string;
+  /** Permission level for shared access */
+  permissions: SharePermission;
+  /** Unix timestamp when share expires, null for never */
+  expiresAt: number | null;
+  /** Maximum number of concurrent viewers, null for unlimited */
+  maxViewers: number | null;
+}
+
+/**
+ * Process state for a session.
+ * The pid is null after server restart (process was killed).
+ */
+export interface ProcessState {
+  /** Process ID, null if process is not running */
+  pid: number | null;
+  /** Shell executable path (e.g., '/bin/zsh') */
+  shell: string;
+  /** Shell arguments */
+  args: string[];
+  /** Current working directory */
+  cwd: string;
+  /** Environment variables */
+  env: Record<string, string>;
+}
+
+/**
+ * Terminal state for a session.
+ */
+export interface TerminalState {
+  /** Number of columns */
+  cols: number;
+  /** Number of rows */
+  rows: number;
+  /** Cursor X position */
+  cursorX: number;
+  /** Cursor Y position */
+  cursorY: number;
+  /** Cursor style */
+  cursorStyle: 'block' | 'underline' | 'bar';
+  /** Whether cursor is visible */
+  cursorVisible: boolean;
+}
+
+/**
+ * Core session state that survives server restarts.
+ * Persisted to disk as JSON.
+ */
+export interface Session {
+  /** Unique identifier (UUID v4) */
+  id: SessionId;
+  /** User-facing display name */
+  displayName: string;
+  /** Unix timestamp when session was created */
+  createdAt: number;
+  /** Unix timestamp of last activity */
+  lastActivity: number;
+  /** Process state */
+  process: ProcessState;
+  /** Terminal state */
+  terminal: TerminalState;
+  /** Path to scrollback file (relative to session directory) */
+  scrollbackFile: string;
+  /** Total number of lines in scrollback history */
+  scrollbackLength: number;
+  /** Sharing configuration, null if not shared */
+  sharing: SharingConfig | null;
+}
+
+/**
+ * Connection to a session (in-memory, not persisted).
+ */
+export interface Connection {
+  /** Unique connection ID */
+  id: string;
+  /** Session being connected to */
+  sessionId: SessionId;
+  /** User identifier */
+  userId: string;
+  /** Connection type */
+  type: 'owner' | 'viewer';
+  /** Permission level */
+  permissions: SharePermission;
+  /** Unix timestamp when connected */
+  connectedAt: number;
+}
+
+/**
+ * Options for creating a new session.
+ */
+export interface CreateSessionOptions {
+  /** Display name (auto-generated if not provided) */
+  name?: string;
+  /** Shell executable (defaults to user's shell) */
+  shell?: string;
+  /** Shell arguments */
+  args?: string[];
+  /** Working directory (defaults to home directory) */
+  cwd?: string;
+  /** Environment variables to add/override */
+  env?: Record<string, string>;
+  /** Terminal columns (default: 80) */
+  cols?: number;
+  /** Terminal rows (default: 24) */
+  rows?: number;
+  /**
+   * Whether to start the PTY process immediately (default: true).
+   * Set to false for web sessions where output should wait for client connection.
+   */
+  startProcess?: boolean;
+}
+
+/**
+ * Options for connecting to a session.
+ */
+export interface ConnectOptions {
+  /** Session ID to connect to */
+  sessionId: SessionId;
+  /** Share token (required for viewer access) */
+  shareToken?: string;
+  /** User identifier */
+  userId: string;
+}
+
+/**
+ * Session info returned from list operations.
+ */
+export interface SessionInfo {
+  /** Session ID */
+  id: SessionId;
+  /** Display name */
+  displayName: string;
+  /** Unix timestamp of last activity */
+  lastActivity: number;
+  /** Whether a process is currently running */
+  isRunning: boolean;
+  /** Number of active connections */
+  connectionCount: number;
+  /** Whether session is being shared */
+  isShared: boolean;
+}
+
+/**
+ * Result of creating a share link.
+ */
+export interface ShareLink {
+  /** Local URL for LAN access */
+  localUrl: string;
+  /** Public URL for internet access (if tunneling enabled) */
+  publicUrl?: string;
+  /** Share token */
+  token: string;
+  /** Unix timestamp when share expires */
+  expiresAt: number | null;
+}
+
+/**
+ * Options for creating a share link.
+ */
+export interface CreateShareOptions {
+  /** Permission level (default: 'read-only') */
+  permissions?: SharePermission;
+  /** Expiration time in milliseconds from now */
+  expiresIn?: number;
+  /** Maximum concurrent viewers */
+  maxViewers?: number;
+}
+
+/**
+ * Events emitted by SessionManager.
+ */
+export interface SessionManagerEvents {
+  /** Emitted when a new session is created */
+  'session:created': (session: Session) => void;
+  /** Emitted when a session is deleted */
+  'session:deleted': (sessionId: SessionId) => void;
+  /** Emitted when a session's process exits */
+  'session:exit': (sessionId: SessionId, exitCode: number) => void;
+  /** Emitted when a connection is established */
+  'connection:open': (connection: Connection) => void;
+  /** Emitted when a connection is closed */
+  'connection:close': (connectionId: string) => void;
+  /** Emitted when session output is received */
+  'session:output': (sessionId: SessionId, data: string) => void;
+}
+
+/**
+ * Storage paths for session data.
+ */
+export interface SessionPaths {
+  /** Base directory for all session data */
+  baseDir: string;
+  /** Directory for a specific session */
+  sessionDir: (sessionId: SessionId) => string;
+  /** Path to session metadata file */
+  metadataFile: (sessionId: SessionId) => string;
+  /** Path to scrollback file */
+  scrollbackFile: (sessionId: SessionId) => string;
+}
+
+/**
+ * Configuration for SessionManager.
+ */
+export interface SessionManagerConfig {
+  /** Base directory for session storage (default: ~/.config/ghosttown/sessions) */
+  storageDir?: string;
+  /** Maximum scrollback lines per session (default: 10000) */
+  scrollbackLimit?: number;
+  /** Default shell (default: $SHELL or /bin/sh) */
+  defaultShell?: string;
+}

package/src/session-utils.js

@@ -0,0 +1,91 @@
+/**
+ * Session Utilities
+ *
+ * Helper functions for working with SessionManager sessions.
+ * Simplified for UUID-based session IDs (no longer depends on tmux).
+ */
+
+/**
+ * @typedef {Object} SessionInfo
+ * @property {string} id - UUID
+ * @property {string} displayName - User-facing name
+ */
+
+/**
+ * Validate a session display name.
+ *
+ * @param {string} name - The name to validate
+ * @returns {{ valid: boolean, error?: string }} Validation result
+ */
+export function validateSessionName(name) {
+  if (!name || name.length === 0) {
+    return { valid: false, error: 'Session name cannot be empty' };
+  }
+  if (name.length > 50) {
+    return { valid: false, error: 'Session name too long (max 50 chars)' };
+  }
+  // Reserved name for system use
+  if (name === 'ghosttown-host') {
+    return { valid: false, error: "'ghosttown-host' is a reserved name" };
+  }
+  // Allow letters, numbers, hyphens, underscores for URL safety
+  // Note: Purely numeric names are now OK since we use UUIDs for session identity
+  if (!/^[a-zA-Z0-9_-]+$/.test(name)) {
+    return {
+      valid: false,
+      error: 'Session name can only contain letters, numbers, hyphens, and underscores',
+    };
+  }
+  return { valid: true };
+}
+
+/**
+ * Find a session by display name from a list.
+ *
+ * @param {SessionInfo[]} sessions - List from SessionManager.listSessions()
+ * @param {string} displayName - The display name to search for
+ * @returns {SessionInfo|null} The matching session, or null if not found
+ */
+export function findByDisplayName(sessions, displayName) {
+  return sessions.find((s) => s.displayName === displayName) || null;
+}
+
+/**
+ * Find a session by ID or display name.
+ * Useful for CLI commands that accept either.
+ *
+ * @param {SessionInfo[]} sessions - List from SessionManager.listSessions()
+ * @param {string} identifier - UUID, short UUID prefix, or display name
+ * @returns {SessionInfo|null} The matching session, or null if not found
+ */
+export function findSession(sessions, identifier) {
+  if (!identifier) {
+    return null;
+  }
+
+  // Try exact ID match first
+  const byId = sessions.find((s) => s.id === identifier);
+  if (byId) {
+    return byId;
+  }
+
+  // Try short ID prefix match (for convenience)
+  const byPrefix = sessions.find((s) => s.id.startsWith(identifier));
+  if (byPrefix) {
+    return byPrefix;
+  }
+
+  // Try by display name
+  return findByDisplayName(sessions, identifier);
+}
+
+/**
+ * Check if a display name already exists in the session list.
+ *
+ * @param {SessionInfo[]} sessions - List from SessionManager.listSessions()
+ * @param {string} displayName - The display name to check
+ * @returns {boolean} True if the name already exists
+ */
+export function displayNameExists(sessions, displayName) {
+  return findByDisplayName(sessions, displayName) !== null;
+}

package/src/session-utils.test.js

@@ -0,0 +1,229 @@
+/**
+ * Session Utilities Tests
+ *
+ * Tests for session lookup and validation helpers.
+ * Simplified for UUID-based session IDs (no longer depends on tmux).
+ */
+
+import { describe, expect, test } from 'bun:test';
+import {
+  displayNameExists,
+  findByDisplayName,
+  findSession,
+  validateSessionName,
+} from './session-utils.js';
+
+describe('validateSessionName', () => {
+  describe('valid names', () => {
+    test('accepts simple text name', () => {
+      const result = validateSessionName('my-project');
+      expect(result).toEqual({ valid: true });
+    });
+
+    test('accepts name with numbers', () => {
+      const result = validateSessionName('project-123');
+      expect(result).toEqual({ valid: true });
+    });
+
+    test('accepts name with underscores', () => {
+      const result = validateSessionName('my_project_2');
+      expect(result).toEqual({ valid: true });
+    });
+
+    test('accepts single character name', () => {
+      const result = validateSessionName('x');
+      expect(result).toEqual({ valid: true });
+    });
+
+    test('accepts purely numeric name (now allowed with UUID-based IDs)', () => {
+      const result = validateSessionName('123');
+      expect(result).toEqual({ valid: true });
+    });
+  });
+
+  describe('invalid names', () => {
+    test('rejects empty name', () => {
+      expect(validateSessionName('')).toEqual({
+        valid: false,
+        error: 'Session name cannot be empty',
+      });
+    });
+
+    test('rejects null/undefined', () => {
+      expect(validateSessionName(null)).toEqual({
+        valid: false,
+        error: 'Session name cannot be empty',
+      });
+      expect(validateSessionName(undefined)).toEqual({
+        valid: false,
+        error: 'Session name cannot be empty',
+      });
+    });
+
+    test('rejects name over 50 characters', () => {
+      const longName = 'a'.repeat(51);
+      expect(validateSessionName(longName)).toEqual({
+        valid: false,
+        error: 'Session name too long (max 50 chars)',
+      });
+    });
+
+    test('rejects reserved name ghosttown-host', () => {
+      expect(validateSessionName('ghosttown-host')).toEqual({
+        valid: false,
+        error: "'ghosttown-host' is a reserved name",
+      });
+    });
+
+    test('rejects names with spaces', () => {
+      expect(validateSessionName('my project')).toEqual({
+        valid: false,
+        error: 'Session name can only contain letters, numbers, hyphens, and underscores',
+      });
+    });
+
+    test('rejects names with special characters', () => {
+      expect(validateSessionName('my.project')).toEqual({
+        valid: false,
+        error: 'Session name can only contain letters, numbers, hyphens, and underscores',
+      });
+      expect(validateSessionName('my:project')).toEqual({
+        valid: false,
+        error: 'Session name can only contain letters, numbers, hyphens, and underscores',
+      });
+      expect(validateSessionName('my/project')).toEqual({
+        valid: false,
+        error: 'Session name can only contain letters, numbers, hyphens, and underscores',
+      });
+    });
+  });
+});
+
+describe('findByDisplayName', () => {
+  const sessions = [
+    { id: 'abc-123', displayName: 'project-1' },
+    { id: 'def-456', displayName: 'project-2' },
+    { id: 'ghi-789', displayName: 'my-app' },
+  ];
+
+  test('finds session by exact display name', () => {
+    const result = findByDisplayName(sessions, 'project-1');
+    expect(result).toEqual({ id: 'abc-123', displayName: 'project-1' });
+  });
+
+  test('finds session with different name', () => {
+    const result = findByDisplayName(sessions, 'my-app');
+    expect(result).toEqual({ id: 'ghi-789', displayName: 'my-app' });
+  });
+
+  test('returns null for non-existent name', () => {
+    expect(findByDisplayName(sessions, 'nonexistent')).toBeNull();
+  });
+
+  test('returns null for empty name', () => {
+    expect(findByDisplayName(sessions, '')).toBeNull();
+  });
+
+  test('returns null for empty sessions list', () => {
+    expect(findByDisplayName([], 'anything')).toBeNull();
+  });
+
+  test('is case-sensitive', () => {
+    expect(findByDisplayName(sessions, 'Project-1')).toBeNull();
+    expect(findByDisplayName(sessions, 'PROJECT-1')).toBeNull();
+  });
+});
+
+describe('findSession', () => {
+  const sessions = [
+    { id: 'abc12345-6789-0123-4567-890abcdef012', displayName: 'project-1' },
+    { id: 'def45678-9012-3456-7890-123456789abc', displayName: 'project-2' },
+    { id: 'ghi78901-2345-6789-0123-456789abcdef', displayName: 'my-app' },
+  ];
+
+  describe('by exact ID', () => {
+    test('finds session by full UUID', () => {
+      const result = findSession(sessions, 'abc12345-6789-0123-4567-890abcdef012');
+      expect(result?.displayName).toBe('project-1');
+    });
+
+    test('finds different session by full UUID', () => {
+      const result = findSession(sessions, 'ghi78901-2345-6789-0123-456789abcdef');
+      expect(result?.displayName).toBe('my-app');
+    });
+  });
+
+  describe('by ID prefix', () => {
+    test('finds session by short prefix', () => {
+      const result = findSession(sessions, 'abc12345');
+      expect(result?.displayName).toBe('project-1');
+    });
+
+    test('finds session by very short prefix', () => {
+      const result = findSession(sessions, 'def');
+      expect(result?.displayName).toBe('project-2');
+    });
+  });
+
+  describe('by display name', () => {
+    test('finds session by display name when ID does not match', () => {
+      const result = findSession(sessions, 'my-app');
+      expect(result?.id).toBe('ghi78901-2345-6789-0123-456789abcdef');
+    });
+
+    test('prefers ID match over display name match', () => {
+      // If a session had displayName that looks like another session's ID prefix,
+      // ID matching should take precedence
+      const sessionsWithConflict = [
+        { id: 'abc-123', displayName: 'def' },
+        { id: 'def-456', displayName: 'other' },
+      ];
+      const result = findSession(sessionsWithConflict, 'def');
+      // Should match 'def-456' by ID prefix, not 'abc-123' by displayName
+      expect(result?.displayName).toBe('other');
+    });
+  });
+
+  describe('not found', () => {
+    test('returns null for non-existent identifier', () => {
+      expect(findSession(sessions, 'nonexistent')).toBeNull();
+    });
+
+    test('returns null for null identifier', () => {
+      expect(findSession(sessions, null)).toBeNull();
+    });
+
+    test('returns null for undefined identifier', () => {
+      expect(findSession(sessions, undefined)).toBeNull();
+    });
+
+    test('returns null for empty identifier', () => {
+      expect(findSession(sessions, '')).toBeNull();
+    });
+
+    test('returns null for empty sessions list', () => {
+      expect(findSession([], 'anything')).toBeNull();
+    });
+  });
+});
+
+describe('displayNameExists', () => {
+  const sessions = [
+    { id: 'abc-123', displayName: 'project-1' },
+    { id: 'def-456', displayName: 'project-2' },
+  ];
+
+  test('returns true for existing name', () => {
+    expect(displayNameExists(sessions, 'project-1')).toBe(true);
+    expect(displayNameExists(sessions, 'project-2')).toBe(true);
+  });
+
+  test('returns false for non-existent name', () => {
+    expect(displayNameExists(sessions, 'project-3')).toBe(false);
+    expect(displayNameExists(sessions, 'nonexistent')).toBe(false);
+  });
+
+  test('returns false for empty sessions list', () => {
+    expect(displayNameExists([], 'anything')).toBe(false);
+  });
+});