@appkit/llamacpp-cli 1.0.0

package/src/lib/state-manager.ts

@@ -0,0 +1,177 @@
+import * as path from 'path';
+import * as fs from 'fs/promises';
+import { ServerConfig } from '../types/server-config';
+import { GlobalConfig, DEFAULT_GLOBAL_CONFIG } from '../types/global-config';
+import {
+  ensureDir,
+  writeJsonAtomic,
+  readJson,
+  fileExists,
+  getConfigDir,
+  getServersDir,
+  getLogsDir,
+  getGlobalConfigPath,
+  getModelsDir,
+  getLaunchAgentsDir,
+} from '../utils/file-utils';
+
+export class StateManager {
+  private configDir: string;
+  private serversDir: string;
+  private logsDir: string;
+  private globalConfigPath: string;
+
+  constructor() {
+    this.configDir = getConfigDir();
+    this.serversDir = getServersDir();
+    this.logsDir = getLogsDir();
+    this.globalConfigPath = getGlobalConfigPath();
+  }
+
+  /**
+   * Initialize config directories
+   */
+  async initialize(): Promise<void> {
+    await ensureDir(this.configDir);
+    await ensureDir(this.serversDir);
+    await ensureDir(this.logsDir);
+    await ensureDir(getLaunchAgentsDir());
+
+    // Create default global config if it doesn't exist
+    if (!(await fileExists(this.globalConfigPath))) {
+      const defaultConfig: GlobalConfig = {
+        ...DEFAULT_GLOBAL_CONFIG,
+        modelsDirectory: getModelsDir(),
+      };
+      await this.saveGlobalConfig(defaultConfig);
+    }
+  }
+
+  /**
+   * Load global configuration
+   */
+  async loadGlobalConfig(): Promise<GlobalConfig> {
+    await this.initialize();
+    return await readJson<GlobalConfig>(this.globalConfigPath);
+  }
+
+  /**
+   * Save global configuration
+   */
+  async saveGlobalConfig(config: GlobalConfig): Promise<void> {
+    await writeJsonAtomic(this.globalConfigPath, config);
+  }
+
+  /**
+   * Load a server configuration by ID
+   */
+  async loadServerConfig(id: string): Promise<ServerConfig | null> {
+    const configPath = path.join(this.serversDir, `${id}.json`);
+    if (!(await fileExists(configPath))) {
+      return null;
+    }
+    return await readJson<ServerConfig>(configPath);
+  }
+
+  /**
+   * Save a server configuration
+   */
+  async saveServerConfig(config: ServerConfig): Promise<void> {
+    const configPath = path.join(this.serversDir, `${config.id}.json`);
+    await writeJsonAtomic(configPath, config);
+  }
+
+  /**
+   * Delete a server configuration
+   */
+  async deleteServerConfig(id: string): Promise<void> {
+    const configPath = path.join(this.serversDir, `${id}.json`);
+    if (await fileExists(configPath)) {
+      await fs.unlink(configPath);
+    }
+  }
+
+  /**
+   * Get all server configurations
+   */
+  async getAllServers(): Promise<ServerConfig[]> {
+    await ensureDir(this.serversDir);
+    const files = await fs.readdir(this.serversDir);
+    const configFiles = files.filter((f) => f.endsWith('.json'));
+
+    const servers: ServerConfig[] = [];
+    for (const file of configFiles) {
+      const filePath = path.join(this.serversDir, file);
+      try {
+        const config = await readJson<ServerConfig>(filePath);
+        servers.push(config);
+      } catch (error) {
+        console.error(`Failed to load server config ${file}:`, error);
+      }
+    }
+
+    return servers;
+  }
+
+  /**
+   * Find a server by port
+   */
+  async findServerByPort(port: number): Promise<ServerConfig | null> {
+    const servers = await this.getAllServers();
+    return servers.find((s) => s.port === port) || null;
+  }
+
+  /**
+   * Find a server by model name (fuzzy match)
+   */
+  async findServerByModelName(name: string): Promise<ServerConfig | null> {
+    const servers = await this.getAllServers();
+    const nameLower = name.toLowerCase();
+
+    // Try exact ID match first
+    const exactMatch = servers.find((s) => s.id === nameLower);
+    if (exactMatch) return exactMatch;
+
+    // Try partial match on model name or ID
+    const partialMatch = servers.find(
+      (s) =>
+        s.modelName.toLowerCase().includes(nameLower) ||
+        s.id.toLowerCase().includes(nameLower)
+    );
+    return partialMatch || null;
+  }
+
+  /**
+   * Find a server by identifier (ID, model name, or port)
+   */
+  async findServer(identifier: string): Promise<ServerConfig | null> {
+    // Try as port number
+    const port = parseInt(identifier, 10);
+    if (!isNaN(port)) {
+      const server = await this.findServerByPort(port);
+      if (server) return server;
+    }
+
+    // Try as ID or model name
+    return await this.findServerByModelName(identifier);
+  }
+
+  /**
+   * Check if a server exists for a given model
+   */
+  async serverExistsForModel(modelPath: string): Promise<boolean> {
+    const servers = await this.getAllServers();
+    return servers.some((s) => s.modelPath === modelPath);
+  }
+
+  /**
+   * Get all used ports
+   */
+  async getUsedPorts(): Promise<Set<number>> {
+    const servers = await this.getAllServers();
+    return new Set(servers.map((s) => s.port));
+  }
+}
+
+// Export singleton instance
+export const stateManager = new StateManager();

package/src/lib/status-checker.ts

@@ -0,0 +1,113 @@
+import { ServerConfig, ServerStatus } from '../types/server-config';
+import { launchctlManager, ServiceStatus } from './launchctl-manager';
+import { isPortInUse, isProcessRunning } from '../utils/process-utils';
+import { stateManager } from './state-manager';
+
+export class StatusChecker {
+  /**
+   * Check the real-time status of a server
+   */
+  async checkServer(config: ServerConfig): Promise<ServiceStatus & { portListening: boolean }> {
+    // Get launchctl status
+    const launchStatus = await launchctlManager.getServiceStatus(config.label);
+
+    // Cross-check port
+    const portListening = await isPortInUse(config.port);
+
+    // Verify PID if reported
+    if (launchStatus.pid) {
+      const pidRunning = await isProcessRunning(launchStatus.pid);
+      if (!pidRunning) {
+        // PID reported but process not running
+        return {
+          ...launchStatus,
+          isRunning: false,
+          portListening,
+        };
+      }
+    }
+
+    return {
+      ...launchStatus,
+      portListening,
+    };
+  }
+
+  /**
+   * Determine server status based on checks
+   */
+  determineStatus(serviceStatus: ServiceStatus, portListening: boolean): ServerStatus {
+    if (serviceStatus.isRunning && portListening) {
+      return 'running';
+    }
+
+    if (!serviceStatus.isRunning && serviceStatus.exitCode && serviceStatus.exitCode !== 0) {
+      return 'crashed';
+    }
+
+    return 'stopped';
+  }
+
+  /**
+   * Update a server's status in its config
+   */
+  async updateServerStatus(config: ServerConfig): Promise<ServerConfig> {
+    const status = await this.checkServer(config);
+    const newStatus = this.determineStatus(status, status.portListening);
+
+    const updatedConfig: ServerConfig = {
+      ...config,
+      status: newStatus,
+      pid: status.pid || undefined,
+    };
+
+    // Update timestamps
+    if (newStatus === 'running' && config.status !== 'running') {
+      updatedConfig.lastStarted = new Date().toISOString();
+    } else if (newStatus === 'stopped' && config.status === 'running') {
+      updatedConfig.lastStopped = new Date().toISOString();
+    }
+
+    // Save updated config
+    await stateManager.saveServerConfig(updatedConfig);
+
+    return updatedConfig;
+  }
+
+  /**
+   * Update status for all servers
+   */
+  async updateAllServerStatuses(): Promise<ServerConfig[]> {
+    const servers = await stateManager.getAllServers();
+    const updated: ServerConfig[] = [];
+
+    for (const server of servers) {
+      const updatedServer = await this.updateServerStatus(server);
+      updated.push(updatedServer);
+    }
+
+    return updated;
+  }
+
+  /**
+   * Find crashed servers
+   */
+  async findCrashedServers(): Promise<ServerConfig[]> {
+    const servers = await stateManager.getAllServers();
+    const crashed: ServerConfig[] = [];
+
+    for (const server of servers) {
+      if (server.status === 'running') {
+        const status = await this.checkServer(server);
+        if (!status.isRunning && status.exitCode !== 0 && status.exitCode !== null) {
+          crashed.push(server);
+        }
+      }
+    }
+
+    return crashed;
+  }
+}
+
+// Export singleton instance
+export const statusChecker = new StatusChecker();

package/src/types/global-config.ts

@@ -0,0 +1,26 @@
+export interface GlobalConfig {
+  version: string;
+  defaultPort: number;
+  modelsDirectory: string;      // ~/models expanded to full path
+  llamaServerBinary: string;    // /opt/homebrew/bin/llama-server
+  defaults: {
+    threads: number;
+    ctxSize: number;
+    gpuLayers: number;
+  };
+}
+
+/**
+ * Default global configuration
+ */
+export const DEFAULT_GLOBAL_CONFIG: GlobalConfig = {
+  version: '1.0.0',
+  defaultPort: 9000,
+  modelsDirectory: '',  // Set at runtime
+  llamaServerBinary: '/opt/homebrew/bin/llama-server',
+  defaults: {
+    threads: 8,
+    ctxSize: 8192,
+    gpuLayers: 60,
+  },
+};

package/src/types/model-info.ts

@@ -0,0 +1,8 @@
+export interface ModelInfo {
+  filename: string;         // Original filename
+  path: string;             // Full absolute path
+  size: number;             // File size in bytes
+  sizeFormatted: string;    // Human-readable size (e.g., "1.9 GB")
+  modified: Date;           // Last modified date
+  exists: boolean;          // File exists and is readable
+}

package/src/types/server-config.ts

@@ -0,0 +1,42 @@
+export type ServerStatus = 'running' | 'stopped' | 'crashed';
+
+export interface ServerConfig {
+  id: string;              // Sanitized model name (unique identifier)
+  modelPath: string;       // Full path to GGUF file
+  modelName: string;       // Display name (original filename)
+  port: number;            // Server port
+
+  // llama-server configuration
+  threads: number;
+  ctxSize: number;
+  gpuLayers: number;
+  embeddings: boolean;     // Always true
+  jinja: boolean;          // Always true
+
+  // State tracking
+  status: ServerStatus;
+  pid?: number;
+  createdAt: string;       // ISO timestamp
+  lastStarted?: string;    // ISO timestamp
+  lastStopped?: string;    // ISO timestamp
+
+  // launchctl metadata
+  plistPath: string;       // Full path to plist file
+  label: string;           // launchctl service label (com.llama.<id>)
+
+  // Logging
+  stdoutPath: string;      // Path to stdout log
+  stderrPath: string;      // Path to stderr log
+}
+
+/**
+ * Sanitize a model filename to create a valid server ID
+ * Example: "llama-3.2-3b-instruct-q4_k_m.gguf" → "llama-3-2-3b-instruct-q4-k-m"
+ */
+export function sanitizeModelName(modelName: string): string {
+  return modelName
+    .replace(/\.gguf$/i, '')           // Remove .gguf extension
+    .replace(/[^a-zA-Z0-9]+/g, '-')    // Replace non-alphanumeric with hyphens
+    .toLowerCase()                      // Lowercase
+    .replace(/^-+|-+$/g, '');          // Trim hyphens from ends
+}

package/src/utils/file-utils.ts

@@ -0,0 +1,106 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as os from 'os';
+
+/**
+ * Ensure a directory exists, creating it if necessary
+ */
+export async function ensureDir(dirPath: string): Promise<void> {
+  try {
+    await fs.mkdir(dirPath, { recursive: true, mode: 0o755 });
+  } catch (error) {
+    // Ignore error if directory already exists
+    if ((error as NodeJS.ErrnoException).code !== 'EEXIST') {
+      throw error;
+    }
+  }
+}
+
+/**
+ * Write a file atomically (write to temp, then rename)
+ */
+export async function writeFileAtomic(filePath: string, content: string): Promise<void> {
+  const tempPath = `${filePath}.tmp`;
+  await fs.writeFile(tempPath, content, 'utf-8');
+  await fs.rename(tempPath, filePath);
+}
+
+/**
+ * Write JSON to a file atomically
+ */
+export async function writeJsonAtomic(filePath: string, data: any): Promise<void> {
+  const content = JSON.stringify(data, null, 2);
+  await writeFileAtomic(filePath, content);
+}
+
+/**
+ * Read and parse JSON file
+ */
+export async function readJson<T>(filePath: string): Promise<T> {
+  const content = await fs.readFile(filePath, 'utf-8');
+  return JSON.parse(content);
+}
+
+/**
+ * Check if a file exists
+ */
+export async function fileExists(filePath: string): Promise<boolean> {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get the llamacpp config directory (~/.llamacpp)
+ */
+export function getConfigDir(): string {
+  return path.join(os.homedir(), '.llamacpp');
+}
+
+/**
+ * Get the servers directory (~/.llamacpp/servers)
+ */
+export function getServersDir(): string {
+  return path.join(getConfigDir(), 'servers');
+}
+
+/**
+ * Get the logs directory (~/.llamacpp/logs)
+ */
+export function getLogsDir(): string {
+  return path.join(getConfigDir(), 'logs');
+}
+
+/**
+ * Get the global config file path
+ */
+export function getGlobalConfigPath(): string {
+  return path.join(getConfigDir(), 'config.json');
+}
+
+/**
+ * Get the models directory (~/models)
+ */
+export function getModelsDir(): string {
+  return path.join(os.homedir(), 'models');
+}
+
+/**
+ * Get the LaunchAgents directory
+ */
+export function getLaunchAgentsDir(): string {
+  return path.join(os.homedir(), 'Library', 'LaunchAgents');
+}
+
+/**
+ * Expand tilde (~) in path to home directory
+ */
+export function expandHome(filePath: string): string {
+  if (filePath.startsWith('~/')) {
+    return path.join(os.homedir(), filePath.slice(2));
+  }
+  return filePath;
+}

package/src/utils/format-utils.ts

@@ -0,0 +1,80 @@
+/**
+ * Format bytes to human-readable size
+ * Example: 1900000000 → "1.9 GB"
+ */
+export function formatBytes(bytes: number): string {
+  const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+  let size = bytes;
+  let unitIndex = 0;
+
+  while (size >= 1024 && unitIndex < units.length - 1) {
+    size /= 1024;
+    unitIndex++;
+  }
+
+  return `${size.toFixed(1)} ${units[unitIndex]}`;
+}
+
+/**
+ * Format a date to a human-readable string
+ * Example: "Nov 20, 2025 10:30 AM"
+ */
+export function formatDate(date: Date | string): string {
+  const d = typeof date === 'string' ? new Date(date) : date;
+  return d.toLocaleString('en-US', {
+    month: 'short',
+    day: 'numeric',
+    year: 'numeric',
+    hour: 'numeric',
+    minute: '2-digit',
+  });
+}
+
+/**
+ * Format a date to a short string (no time)
+ * Example: "Nov 20"
+ */
+export function formatDateShort(date: Date | string): string {
+  const d = typeof date === 'string' ? new Date(date) : date;
+  return d.toLocaleString('en-US', {
+    month: 'short',
+    day: 'numeric',
+  });
+}
+
+/**
+ * Calculate uptime from start time
+ * Example: "2d 4h" or "45m" or "30s"
+ */
+export function formatUptime(startTime: string): string {
+  const start = new Date(startTime).getTime();
+  const now = Date.now();
+  const seconds = Math.floor((now - start) / 1000);
+
+  if (seconds < 60) return `${seconds}s`;
+
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m`;
+
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h`;
+
+  const days = Math.floor(hours / 24);
+  const remainingHours = hours % 24;
+  return remainingHours > 0 ? `${days}d ${remainingHours}h` : `${days}d`;
+}
+
+/**
+ * Truncate a string to a maximum length
+ */
+export function truncate(str: string, maxLength: number): string {
+  if (str.length <= maxLength) return str;
+  return str.slice(0, maxLength - 3) + '...';
+}
+
+/**
+ * Pad a string to a specific length
+ */
+export function pad(str: string, length: number, char = ' '): string {
+  return str.padEnd(length, char);
+}

package/src/utils/process-utils.ts

@@ -0,0 +1,60 @@
+import { exec } from 'child_process';
+import { promisify } from 'util';
+
+export const execAsync = promisify(exec);
+
+/**
+ * Execute a command and return stdout
+ * Throws on non-zero exit code
+ */
+export async function execCommand(command: string): Promise<string> {
+  const { stdout } = await execAsync(command);
+  return stdout.trim();
+}
+
+/**
+ * Execute a command and return both stdout and stderr
+ */
+export async function execCommandFull(command: string): Promise<{ stdout: string; stderr: string }> {
+  const { stdout, stderr } = await execAsync(command);
+  return {
+    stdout: stdout.trim(),
+    stderr: stderr.trim(),
+  };
+}
+
+/**
+ * Check if a command exists in PATH
+ */
+export async function commandExists(command: string): Promise<boolean> {
+  try {
+    await execAsync(`which ${command}`);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if a process is running by PID
+ */
+export async function isProcessRunning(pid: number): Promise<boolean> {
+  try {
+    await execAsync(`ps -p ${pid}`);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if a port is in use
+ */
+export async function isPortInUse(port: number): Promise<boolean> {
+  try {
+    await execAsync(`lsof -iTCP:${port} -sTCP:LISTEN -t`);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "moduleResolution": "node"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}