@appkit/llamacpp-cli 1.0.0

package/src/commands/start.ts

@@ -0,0 +1,140 @@
+import chalk from 'chalk';
+import * as path from 'path';
+import { modelScanner } from '../lib/model-scanner';
+import { stateManager } from '../lib/state-manager';
+import { configGenerator, ServerOptions } from '../lib/config-generator';
+import { portManager } from '../lib/port-manager';
+import { launchctlManager } from '../lib/launchctl-manager';
+import { statusChecker } from '../lib/status-checker';
+import { commandExists } from '../utils/process-utils';
+import { formatBytes } from '../utils/format-utils';
+import { ensureDir } from '../utils/file-utils';
+
+interface StartOptions {
+  port?: number;
+  threads?: number;
+  ctxSize?: number;
+  gpuLayers?: number;
+}
+
+export async function startCommand(model: string, options: StartOptions): Promise<void> {
+  // Initialize state manager
+  await stateManager.initialize();
+
+  // 1. Check if llama-server exists
+  if (!(await commandExists('llama-server'))) {
+    throw new Error('llama-server not found. Install with: brew install llama.cpp');
+  }
+
+  // 2. Resolve model path
+  const modelPath = await modelScanner.resolveModelPath(model);
+  if (!modelPath) {
+    throw new Error(`Model not found: ${model}\n\nRun: llamacpp list`);
+  }
+
+  const modelName = path.basename(modelPath);
+
+  // 3. Check if server already exists for this model
+  const existingServer = await stateManager.serverExistsForModel(modelPath);
+  if (existingServer) {
+    throw new Error(`Server already exists for ${modelName}\n\nUse: llamacpp ps`);
+  }
+
+  // 4. Get model size
+  const modelSize = await modelScanner.getModelSize(modelName);
+  if (!modelSize) {
+    throw new Error(`Failed to read model file: ${modelPath}`);
+  }
+
+  // 5. Determine port
+  let port: number;
+  if (options.port) {
+    portManager.validatePort(options.port);
+    const available = await portManager.isPortAvailable(options.port);
+    if (!available) {
+      throw new Error(`Port ${options.port} is already in use`);
+    }
+    port = options.port;
+  } else {
+    port = await portManager.findAvailablePort();
+  }
+
+  // 6. Generate server configuration
+  console.log(chalk.blue(`🚀 Starting server for ${modelName}\n`));
+
+  const serverOptions: ServerOptions = {
+    port: options.port,
+    threads: options.threads,
+    ctxSize: options.ctxSize,
+    gpuLayers: options.gpuLayers,
+  };
+
+  const config = await configGenerator.generateConfig(
+    modelPath,
+    modelName,
+    modelSize,
+    port,
+    serverOptions
+  );
+
+  // Display configuration
+  console.log(chalk.dim(`Model: ${modelPath}`));
+  console.log(chalk.dim(`Size: ${formatBytes(modelSize)}`));
+  console.log(chalk.dim(`Port: ${config.port}${options.port ? '' : ' (auto-assigned)'}`));
+  console.log(chalk.dim(`Threads: ${config.threads}`));
+  console.log(chalk.dim(`Context Size: ${config.ctxSize}`));
+  console.log(chalk.dim(`GPU Layers: ${config.gpuLayers}`));
+  console.log();
+
+  // 7. Ensure log directory exists
+  await ensureDir(path.dirname(config.stdoutPath));
+
+  // 8. Create plist file
+  console.log(chalk.dim('Creating launchctl service...'));
+  await launchctlManager.createPlist(config);
+
+  // 9. Load service
+  try {
+    await launchctlManager.loadService(config.plistPath);
+  } catch (error) {
+    // Clean up plist if load fails
+    await launchctlManager.deletePlist(config.plistPath);
+    throw new Error(`Failed to load service: ${(error as Error).message}`);
+  }
+
+  // 10. Start service
+  try {
+    await launchctlManager.startService(config.label);
+  } catch (error) {
+    // Clean up if start fails
+    await launchctlManager.unloadService(config.plistPath);
+    await launchctlManager.deletePlist(config.plistPath);
+    throw new Error(`Failed to start service: ${(error as Error).message}`);
+  }
+
+  // 11. Wait for startup
+  console.log(chalk.dim('Waiting for server to start...'));
+  const started = await launchctlManager.waitForServiceStart(config.label, 5000);
+
+  if (!started) {
+    // Clean up if startup fails
+    await launchctlManager.stopService(config.label);
+    await launchctlManager.unloadService(config.plistPath);
+    await launchctlManager.deletePlist(config.plistPath);
+    throw new Error('Server failed to start. Check logs with: llamacpp logs --errors');
+  }
+
+  // 12. Update config with running status
+  const updatedConfig = await statusChecker.updateServerStatus(config);
+
+  // 13. Save server config
+  await stateManager.saveServerConfig(updatedConfig);
+
+  // 14. Display success message
+  console.log();
+  console.log(chalk.green('✅ Server started successfully!'));
+  console.log();
+  console.log(chalk.dim(`Connect: http://localhost:${config.port}`));
+  console.log(chalk.dim(`View logs: llamacpp logs ${config.id}`));
+  console.log(chalk.dim(`Stop: llamacpp stop ${config.id}`));
+}

package/src/commands/stop.ts

@@ -0,0 +1,39 @@
+import chalk from 'chalk';
+import { stateManager } from '../lib/state-manager';
+import { launchctlManager } from '../lib/launchctl-manager';
+import { statusChecker } from '../lib/status-checker';
+
+export async function stopCommand(identifier: string): Promise<void> {
+  // Find server
+  const server = await stateManager.findServer(identifier);
+  if (!server) {
+    throw new Error(`Server not found: ${identifier}\n\nUse: llamacpp ps`);
+  }
+
+  // Check if already stopped
+  if (server.status === 'stopped') {
+    console.log(chalk.yellow(`⚠️  Server ${server.modelName} is already stopped`));
+    return;
+  }
+
+  console.log(chalk.blue(`⏹️  Stopping ${server.modelName} (port ${server.port})...`));
+
+  // Stop the service
+  try {
+    await launchctlManager.stopService(server.label);
+  } catch (error) {
+    throw new Error(`Failed to stop service: ${(error as Error).message}`);
+  }
+
+  // Wait for clean shutdown
+  const stopped = await launchctlManager.waitForServiceStop(server.label, 5000);
+
+  if (!stopped) {
+    console.log(chalk.yellow('⚠️  Server did not stop cleanly (timeout)'));
+  }
+
+  // Update server status
+  await statusChecker.updateServerStatus(server);
+
+  console.log(chalk.green('✅ Server stopped'));
+}

package/src/lib/config-generator.ts

@@ -0,0 +1,119 @@
+import * as os from 'os';
+import * as path from 'path';
+import { ServerConfig, sanitizeModelName } from '../types/server-config';
+import { getLogsDir, getLaunchAgentsDir } from '../utils/file-utils';
+import { stateManager } from './state-manager';
+
+export interface ServerOptions {
+  port?: number;
+  threads?: number;
+  ctxSize?: number;
+  gpuLayers?: number;
+  embeddings?: boolean;
+  jinja?: boolean;
+}
+
+export interface SmartDefaults {
+  threads: number;
+  ctxSize: number;
+  gpuLayers: number;
+}
+
+export class ConfigGenerator {
+  /**
+   * Calculate smart defaults based on model size
+   */
+  calculateSmartDefaults(modelSizeBytes: number): SmartDefaults {
+    const sizeGB = modelSizeBytes / (1024 ** 3);
+
+    // Context size based on model size
+    let ctxSize: number;
+    if (sizeGB < 1) {
+      ctxSize = 2048;        // < 1GB: small context
+    } else if (sizeGB < 3) {
+      ctxSize = 4096;        // 1-3GB: medium
+    } else if (sizeGB < 6) {
+      ctxSize = 8192;        // 3-6GB: large
+    } else {
+      ctxSize = 16384;       // 6GB+: very large
+    }
+
+    // GPU layers - always max for Metal (macOS)
+    const gpuLayers = 60;  // llama.cpp auto-detects optimal value
+
+    // Threads - use half of available cores (better performance)
+    const cpuCount = os.cpus().length;
+    const threads = Math.max(4, Math.floor(cpuCount / 2));
+
+    return { threads, ctxSize, gpuLayers };
+  }
+
+  /**
+   * Generate server configuration
+   */
+  async generateConfig(
+    modelPath: string,
+    modelName: string,
+    modelSize: number,
+    port: number,
+    options?: ServerOptions
+  ): Promise<ServerConfig> {
+    // Calculate smart defaults
+    const smartDefaults = this.calculateSmartDefaults(modelSize);
+
+    // Apply user overrides
+    const threads = options?.threads ?? smartDefaults.threads;
+    const ctxSize = options?.ctxSize ?? smartDefaults.ctxSize;
+    const gpuLayers = options?.gpuLayers ?? smartDefaults.gpuLayers;
+    const embeddings = options?.embeddings ?? true;
+    const jinja = options?.jinja ?? true;
+
+    // Generate server ID
+    const id = sanitizeModelName(modelName);
+
+    // Generate paths
+    const label = `com.llama.${id}`;
+    const plistPath = path.join(getLaunchAgentsDir(), `${label}.plist`);
+    const logsDir = getLogsDir();
+    const stdoutPath = path.join(logsDir, `${id}.stdout`);
+    const stderrPath = path.join(logsDir, `${id}.stderr`);
+
+    const config: ServerConfig = {
+      id,
+      modelPath,
+      modelName,
+      port,
+      threads,
+      ctxSize,
+      gpuLayers,
+      embeddings,
+      jinja,
+      status: 'stopped',
+      createdAt: new Date().toISOString(),
+      plistPath,
+      label,
+      stdoutPath,
+      stderrPath,
+    };
+
+    return config;
+  }
+
+  /**
+   * Merge global defaults with user options
+   */
+  async mergeWithGlobalDefaults(options?: ServerOptions): Promise<Partial<ServerOptions>> {
+    const globalConfig = await stateManager.loadGlobalConfig();
+
+    return {
+      threads: options?.threads ?? globalConfig.defaults.threads,
+      ctxSize: options?.ctxSize ?? globalConfig.defaults.ctxSize,
+      gpuLayers: options?.gpuLayers ?? globalConfig.defaults.gpuLayers,
+      embeddings: options?.embeddings ?? true,
+      jinja: options?.jinja ?? true,
+    };
+  }
+}
+
+// Export singleton instance
+export const configGenerator = new ConfigGenerator();

package/src/lib/launchctl-manager.ts

@@ -0,0 +1,209 @@
+import * as path from 'path';
+import * as fs from 'fs/promises';
+import { ServerConfig } from '../types/server-config';
+import { execCommand, execAsync } from '../utils/process-utils';
+import { writeFileAtomic, fileExists } from '../utils/file-utils';
+
+export interface ServiceStatus {
+  isRunning: boolean;
+  pid: number | null;
+  exitCode: number | null;
+  lastExitReason?: string;
+}
+
+export class LaunchctlManager {
+  /**
+   * Generate plist XML content for a server
+   */
+  generatePlist(config: ServerConfig): string {
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
+  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+  <dict>
+    <key>Label</key>
+    <string>${config.label}</string>
+
+    <key>ProgramArguments</key>
+    <array>
+      <string>/opt/homebrew/bin/llama-server</string>
+      <string>--model</string>
+      <string>${config.modelPath}</string>
+      <string>--port</string>
+      <string>${config.port}</string>
+      <string>--threads</string>
+      <string>${config.threads}</string>
+      <string>--ctx-size</string>
+      <string>${config.ctxSize}</string>
+      <string>--gpu-layers</string>
+      <string>${config.gpuLayers}</string>
+      <string>--embeddings</string>
+      <string>--jinja</string>
+    </array>
+
+    <key>RunAtLoad</key>
+    <false/>
+
+    <key>KeepAlive</key>
+    <dict>
+      <key>Crashed</key>
+      <true/>
+      <key>SuccessfulExit</key>
+      <false/>
+    </dict>
+
+    <key>StandardOutPath</key>
+    <string>${config.stdoutPath}</string>
+
+    <key>StandardErrorPath</key>
+    <string>${config.stderrPath}</string>
+
+    <key>WorkingDirectory</key>
+    <string>/tmp</string>
+
+    <key>ThrottleInterval</key>
+    <integer>10</integer>
+  </dict>
+</plist>
+`;
+  }
+
+  /**
+   * Create and write plist file
+   */
+  async createPlist(config: ServerConfig): Promise<void> {
+    const plistContent = this.generatePlist(config);
+    await writeFileAtomic(config.plistPath, plistContent);
+  }
+
+  /**
+   * Delete plist file
+   */
+  async deletePlist(plistPath: string): Promise<void> {
+    if (await fileExists(plistPath)) {
+      await fs.unlink(plistPath);
+    }
+  }
+
+  /**
+   * Load service (register with launchctl)
+   */
+  async loadService(plistPath: string): Promise<void> {
+    await execCommand(`launchctl load "${plistPath}"`);
+  }
+
+  /**
+   * Unload service (unregister from launchctl)
+   */
+  async unloadService(plistPath: string): Promise<void> {
+    try {
+      await execCommand(`launchctl unload "${plistPath}"`);
+    } catch (error) {
+      // Ignore errors if service is not loaded
+    }
+  }
+
+  /**
+   * Start service
+   */
+  async startService(label: string): Promise<void> {
+    await execCommand(`launchctl start ${label}`);
+  }
+
+  /**
+   * Stop service
+   */
+  async stopService(label: string): Promise<void> {
+    await execCommand(`launchctl stop ${label}`);
+  }
+
+  /**
+   * Get service status from launchctl
+   */
+  async getServiceStatus(label: string): Promise<ServiceStatus> {
+    try {
+      const { stdout } = await execAsync(`launchctl list | grep ${label}`);
+      const lines = stdout.trim().split('\n');
+
+      for (const line of lines) {
+        const parts = line.split(/\s+/);
+        if (parts.length >= 3) {
+          const pidStr = parts[0].trim();
+          const exitCodeStr = parts[1].trim();
+          const serviceLabel = parts[2].trim();
+
+          // Match the exact label
+          if (serviceLabel === label) {
+            const pid = pidStr !== '-' ? parseInt(pidStr, 10) : null;
+            const exitCode = exitCodeStr !== '-' ? parseInt(exitCodeStr, 10) : null;
+            const isRunning = pid !== null;
+
+            return {
+              isRunning,
+              pid,
+              exitCode,
+              lastExitReason: this.interpretExitCode(exitCode),
+            };
+          }
+        }
+      }
+
+      // Service not found
+      return {
+        isRunning: false,
+        pid: null,
+        exitCode: null,
+      };
+    } catch (error) {
+      // Service not found or not loaded
+      return {
+        isRunning: false,
+        pid: null,
+        exitCode: null,
+      };
+    }
+  }
+
+  /**
+   * Interpret exit code to human-readable reason
+   */
+  private interpretExitCode(code: number | null): string | undefined {
+    if (code === null || code === 0) return undefined;
+    if (code === -9) return 'Force killed (SIGKILL)';
+    if (code === -15) return 'Terminated (SIGTERM)';
+    return `Exit code: ${code}`;
+  }
+
+  /**
+   * Wait for service to start (with timeout)
+   */
+  async waitForServiceStart(label: string, timeoutMs = 5000): Promise<boolean> {
+    const startTime = Date.now();
+    while (Date.now() - startTime < timeoutMs) {
+      const status = await this.getServiceStatus(label);
+      if (status.isRunning) {
+        return true;
+      }
+      await new Promise((resolve) => setTimeout(resolve, 500));
+    }
+    return false;
+  }
+
+  /**
+   * Wait for service to stop (with timeout)
+   */
+  async waitForServiceStop(label: string, timeoutMs = 5000): Promise<boolean> {
+    const startTime = Date.now();
+    while (Date.now() - startTime < timeoutMs) {
+      const status = await this.getServiceStatus(label);
+      if (!status.isRunning) {
+        return true;
+      }
+      await new Promise((resolve) => setTimeout(resolve, 500));
+    }
+    return false;
+  }
+}
+
+// Export singleton instance
+export const launchctlManager = new LaunchctlManager();