@seflless/ghosttown 1.6.2 → 1.10.0

package/src/session/types.d.ts

@@ -0,0 +1,221 @@
+/**
+ * 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/types.js

@@ -0,0 +1,8 @@
+/**
+ * Session Management Types
+ *
+ * Core types for the custom PTY session management system that replaces tmux.
+ * Sessions persist across reconnections and server restarts.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/src/session/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

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;
+}