Implement settings service and routes for file-based settings management

- Add SettingsService to handle reading/writing global and project settings.
- Introduce API routes for managing settings, including global settings, credentials, and project-specific settings.
- Implement migration functionality to transfer settings from localStorage to file-based storage.
- Create common utilities for settings routes and integrate logging for error handling.
- Update server entry point to include new settings routes.

apps/server/src/index.ts

@@ -37,10 +37,12 @@ import {
   isTerminalEnabled,
   isTerminalPasswordRequired,
 } from "./routes/terminal/index.js";
+import { createSettingsRoutes } from "./routes/settings/index.js";
 import { AgentService } from "./services/agent-service.js";
 import { FeatureLoader } from "./services/feature-loader.js";
 import { AutoModeService } from "./services/auto-mode-service.js";
 import { getTerminalService } from "./services/terminal-service.js";
+import { SettingsService } from "./services/settings-service.js";
 import { createSpecRegenerationRoutes } from "./routes/app-spec/index.js";
 
 // Load environment variables
@@ -108,6 +110,7 @@ const events: EventEmitter = createEventEmitter();
 const agentService = new AgentService(DATA_DIR, events);
 const featureLoader = new FeatureLoader();
 const autoModeService = new AutoModeService(events);
+const settingsService = new SettingsService(DATA_DIR);
 
 // Initialize services
 (async () => {
@@ -137,6 +140,7 @@ app.use("/api/running-agents", createRunningAgentsRoutes(autoModeService));
 app.use("/api/workspace", createWorkspaceRoutes());
 app.use("/api/templates", createTemplatesRoutes());
 app.use("/api/terminal", createTerminalRoutes());
+app.use("/api/settings", createSettingsRoutes(settingsService));
 
 // Create HTTP server
 const server = createServer(app);

apps/server/src/lib/automaker-paths.ts

@@ -89,3 +89,38 @@ export async function ensureAutomakerDir(projectPath: string): Promise<string> {
   await fs.mkdir(automakerDir, { recursive: true });
   return automakerDir;
 }
+
+// ============================================================================
+// Global Settings Paths (stored in DATA_DIR from app.getPath('userData'))
+// ============================================================================
+
+/**
+ * Get the global settings file path
+ * DATA_DIR is typically ~/Library/Application Support/automaker (macOS)
+ * or %APPDATA%\automaker (Windows) or ~/.config/automaker (Linux)
+ */
+export function getGlobalSettingsPath(dataDir: string): string {
+  return path.join(dataDir, "settings.json");
+}
+
+/**
+ * Get the credentials file path (separate from settings for security)
+ */
+export function getCredentialsPath(dataDir: string): string {
+  return path.join(dataDir, "credentials.json");
+}
+
+/**
+ * Get the project settings file path within a project's .automaker directory
+ */
+export function getProjectSettingsPath(projectPath: string): string {
+  return path.join(getAutomakerDir(projectPath), "settings.json");
+}
+
+/**
+ * Ensure the global data directory exists
+ */
+export async function ensureDataDir(dataDir: string): Promise<string> {
+  await fs.mkdir(dataDir, { recursive: true });
+  return dataDir;
+}

apps/server/src/routes/settings/common.ts

@@ -0,0 +1,15 @@
+/**
+ * Common utilities for settings routes
+ */
+
+import { createLogger } from "../../lib/logger.js";
+import {
+  getErrorMessage as getErrorMessageShared,
+  createLogError,
+} from "../common.js";
+
+export const logger = createLogger("Settings");
+
+// Re-export shared utilities
+export { getErrorMessageShared as getErrorMessage };
+export const logError = createLogError(logger);

apps/server/src/routes/settings/index.ts

@@ -0,0 +1,38 @@
+/**
+ * Settings routes - HTTP API for persistent file-based settings
+ */
+
+import { Router } from "express";
+import type { SettingsService } from "../../services/settings-service.js";
+import { createGetGlobalHandler } from "./routes/get-global.js";
+import { createUpdateGlobalHandler } from "./routes/update-global.js";
+import { createGetCredentialsHandler } from "./routes/get-credentials.js";
+import { createUpdateCredentialsHandler } from "./routes/update-credentials.js";
+import { createGetProjectHandler } from "./routes/get-project.js";
+import { createUpdateProjectHandler } from "./routes/update-project.js";
+import { createMigrateHandler } from "./routes/migrate.js";
+import { createStatusHandler } from "./routes/status.js";
+
+export function createSettingsRoutes(settingsService: SettingsService): Router {
+  const router = Router();
+
+  // Status endpoint (check if migration needed)
+  router.get("/status", createStatusHandler(settingsService));
+
+  // Global settings
+  router.get("/global", createGetGlobalHandler(settingsService));
+  router.put("/global", createUpdateGlobalHandler(settingsService));
+
+  // Credentials (separate for security)
+  router.get("/credentials", createGetCredentialsHandler(settingsService));
+  router.put("/credentials", createUpdateCredentialsHandler(settingsService));
+
+  // Project settings
+  router.post("/project", createGetProjectHandler(settingsService));
+  router.put("/project", createUpdateProjectHandler(settingsService));
+
+  // Migration from localStorage
+  router.post("/migrate", createMigrateHandler(settingsService));
+
+  return router;
+}

apps/server/src/routes/settings/routes/get-credentials.ts

@@ -0,0 +1,23 @@
+/**
+ * GET /api/settings/credentials - Get credentials (masked for security)
+ */
+
+import type { Request, Response } from "express";
+import type { SettingsService } from "../../../services/settings-service.js";
+import { getErrorMessage, logError } from "../common.js";
+
+export function createGetCredentialsHandler(settingsService: SettingsService) {
+  return async (_req: Request, res: Response): Promise<void> => {
+    try {
+      const credentials = await settingsService.getMaskedCredentials();
+
+      res.json({
+        success: true,
+        credentials,
+      });
+    } catch (error) {
+      logError(error, "Get credentials failed");
+      res.status(500).json({ success: false, error: getErrorMessage(error) });
+    }
+  };
+}

apps/server/src/routes/settings/routes/get-global.ts

@@ -0,0 +1,23 @@
+/**
+ * GET /api/settings/global - Get global settings
+ */
+
+import type { Request, Response } from "express";
+import type { SettingsService } from "../../../services/settings-service.js";
+import { getErrorMessage, logError } from "../common.js";
+
+export function createGetGlobalHandler(settingsService: SettingsService) {
+  return async (_req: Request, res: Response): Promise<void> => {
+    try {
+      const settings = await settingsService.getGlobalSettings();
+
+      res.json({
+        success: true,
+        settings,
+      });
+    } catch (error) {
+      logError(error, "Get global settings failed");
+      res.status(500).json({ success: false, error: getErrorMessage(error) });
+    }
+  };
+}

apps/server/src/routes/settings/routes/get-project.ts

@@ -0,0 +1,34 @@
+/**
+ * POST /api/settings/project - Get project settings
+ * Uses POST because projectPath may contain special characters
+ */
+
+import type { Request, Response } from "express";
+import type { SettingsService } from "../../../services/settings-service.js";
+import { getErrorMessage, logError } from "../common.js";
+
+export function createGetProjectHandler(settingsService: SettingsService) {
+  return async (req: Request, res: Response): Promise<void> => {
+    try {
+      const { projectPath } = req.body as { projectPath?: string };
+
+      if (!projectPath || typeof projectPath !== "string") {
+        res.status(400).json({
+          success: false,
+          error: "projectPath is required",
+        });
+        return;
+      }
+
+      const settings = await settingsService.getProjectSettings(projectPath);
+
+      res.json({
+        success: true,
+        settings,
+      });
+    } catch (error) {
+      logError(error, "Get project settings failed");
+      res.status(500).json({ success: false, error: getErrorMessage(error) });
+    }
+  };
+}

apps/server/src/routes/settings/routes/migrate.ts

@@ -0,0 +1,54 @@
+/**
+ * POST /api/settings/migrate - Migrate settings from localStorage
+ */
+
+import type { Request, Response } from "express";
+import type { SettingsService } from "../../../services/settings-service.js";
+import { getErrorMessage, logError, logger } from "../common.js";
+
+export function createMigrateHandler(settingsService: SettingsService) {
+  return async (req: Request, res: Response): Promise<void> => {
+    try {
+      const { data } = req.body as {
+        data?: {
+          "automaker-storage"?: string;
+          "automaker-setup"?: string;
+          "worktree-panel-collapsed"?: string;
+          "file-browser-recent-folders"?: string;
+          "automaker:lastProjectDir"?: string;
+        };
+      };
+
+      if (!data || typeof data !== "object") {
+        res.status(400).json({
+          success: false,
+          error: "data object is required containing localStorage data",
+        });
+        return;
+      }
+
+      logger.info("Starting settings migration from localStorage");
+
+      const result = await settingsService.migrateFromLocalStorage(data);
+
+      if (result.success) {
+        logger.info(
+          `Migration successful: ${result.migratedProjectCount} projects migrated`
+        );
+      } else {
+        logger.warn(`Migration completed with errors: ${result.errors.join(", ")}`);
+      }
+
+      res.json({
+        success: result.success,
+        migratedGlobalSettings: result.migratedGlobalSettings,
+        migratedCredentials: result.migratedCredentials,
+        migratedProjectCount: result.migratedProjectCount,
+        errors: result.errors,
+      });
+    } catch (error) {
+      logError(error, "Migration failed");
+      res.status(500).json({ success: false, error: getErrorMessage(error) });
+    }
+  };
+}

apps/server/src/routes/settings/routes/status.ts

@@ -0,0 +1,28 @@
+/**
+ * GET /api/settings/status - Get settings migration status
+ * Returns whether settings files exist (to determine if migration is needed)
+ */
+
+import type { Request, Response } from "express";
+import type { SettingsService } from "../../../services/settings-service.js";
+import { getErrorMessage, logError } from "../common.js";
+
+export function createStatusHandler(settingsService: SettingsService) {
+  return async (_req: Request, res: Response): Promise<void> => {
+    try {
+      const hasGlobalSettings = await settingsService.hasGlobalSettings();
+      const hasCredentials = await settingsService.hasCredentials();
+
+      res.json({
+        success: true,
+        hasGlobalSettings,
+        hasCredentials,
+        dataDir: settingsService.getDataDir(),
+        needsMigration: !hasGlobalSettings,
+      });
+    } catch (error) {
+      logError(error, "Get settings status failed");
+      res.status(500).json({ success: false, error: getErrorMessage(error) });
+    }
+  };
+}

apps/server/src/routes/settings/routes/update-credentials.ts

@@ -0,0 +1,39 @@
+/**
+ * PUT /api/settings/credentials - Update credentials
+ */
+
+import type { Request, Response } from "express";
+import type { SettingsService } from "../../../services/settings-service.js";
+import type { Credentials } from "../../../types/settings.js";
+import { getErrorMessage, logError } from "../common.js";
+
+export function createUpdateCredentialsHandler(
+  settingsService: SettingsService
+) {
+  return async (req: Request, res: Response): Promise<void> => {
+    try {
+      const updates = req.body as Partial<Credentials>;
+
+      if (!updates || typeof updates !== "object") {
+        res.status(400).json({
+          success: false,
+          error: "Invalid request body - expected credentials object",
+        });
+        return;
+      }
+
+      await settingsService.updateCredentials(updates);
+
+      // Return masked credentials for confirmation
+      const masked = await settingsService.getMaskedCredentials();
+
+      res.json({
+        success: true,
+        credentials: masked,
+      });
+    } catch (error) {
+      logError(error, "Update credentials failed");
+      res.status(500).json({ success: false, error: getErrorMessage(error) });
+    }
+  };
+}

apps/server/src/routes/settings/routes/update-global.ts

@@ -0,0 +1,34 @@
+/**
+ * PUT /api/settings/global - Update global settings
+ */
+
+import type { Request, Response } from "express";
+import type { SettingsService } from "../../../services/settings-service.js";
+import type { GlobalSettings } from "../../../types/settings.js";
+import { getErrorMessage, logError } from "../common.js";
+
+export function createUpdateGlobalHandler(settingsService: SettingsService) {
+  return async (req: Request, res: Response): Promise<void> => {
+    try {
+      const updates = req.body as Partial<GlobalSettings>;
+
+      if (!updates || typeof updates !== "object") {
+        res.status(400).json({
+          success: false,
+          error: "Invalid request body - expected settings object",
+        });
+        return;
+      }
+
+      const settings = await settingsService.updateGlobalSettings(updates);
+
+      res.json({
+        success: true,
+        settings,
+      });
+    } catch (error) {
+      logError(error, "Update global settings failed");
+      res.status(500).json({ success: false, error: getErrorMessage(error) });
+    }
+  };
+}

apps/server/src/routes/settings/routes/update-project.ts

@@ -0,0 +1,48 @@
+/**
+ * PUT /api/settings/project - Update project settings
+ */
+
+import type { Request, Response } from "express";
+import type { SettingsService } from "../../../services/settings-service.js";
+import type { ProjectSettings } from "../../../types/settings.js";
+import { getErrorMessage, logError } from "../common.js";
+
+export function createUpdateProjectHandler(settingsService: SettingsService) {
+  return async (req: Request, res: Response): Promise<void> => {
+    try {
+      const { projectPath, updates } = req.body as {
+        projectPath?: string;
+        updates?: Partial<ProjectSettings>;
+      };
+
+      if (!projectPath || typeof projectPath !== "string") {
+        res.status(400).json({
+          success: false,
+          error: "projectPath is required",
+        });
+        return;
+      }
+
+      if (!updates || typeof updates !== "object") {
+        res.status(400).json({
+          success: false,
+          error: "updates object is required",
+        });
+        return;
+      }
+
+      const settings = await settingsService.updateProjectSettings(
+        projectPath,
+        updates
+      );
+
+      res.json({
+        success: true,
+        settings,
+      });
+    } catch (error) {
+      logError(error, "Update project settings failed");
+      res.status(500).json({ success: false, error: getErrorMessage(error) });
+    }
+  };
+}

apps/server/src/services/settings-service.ts

@@ -0,0 +1,542 @@
+/**
+ * Settings Service - Handles reading/writing settings to JSON files
+ *
+ * Provides persistent storage for:
+ * - Global settings (DATA_DIR/settings.json)
+ * - Credentials (DATA_DIR/credentials.json)
+ * - Per-project settings ({projectPath}/.automaker/settings.json)
+ */
+
+import fs from "fs/promises";
+import path from "path";
+import { createLogger } from "../lib/logger.js";
+import {
+  getGlobalSettingsPath,
+  getCredentialsPath,
+  getProjectSettingsPath,
+  ensureDataDir,
+  ensureAutomakerDir,
+} from "../lib/automaker-paths.js";
+import type {
+  GlobalSettings,
+  Credentials,
+  ProjectSettings,
+  KeyboardShortcuts,
+  AIProfile,
+  ProjectRef,
+  TrashedProjectRef,
+  BoardBackgroundSettings,
+  WorktreeInfo,
+} from "../types/settings.js";
+import {
+  DEFAULT_GLOBAL_SETTINGS,
+  DEFAULT_CREDENTIALS,
+  DEFAULT_PROJECT_SETTINGS,
+  SETTINGS_VERSION,
+  CREDENTIALS_VERSION,
+  PROJECT_SETTINGS_VERSION,
+} from "../types/settings.js";
+
+const logger = createLogger("SettingsService");
+
+/**
+ * Atomic file write - write to temp file then rename
+ */
+async function atomicWriteJson(filePath: string, data: unknown): Promise<void> {
+  const tempPath = `${filePath}.tmp.${Date.now()}`;
+  const content = JSON.stringify(data, null, 2);
+
+  try {
+    await fs.writeFile(tempPath, content, "utf-8");
+    await fs.rename(tempPath, filePath);
+  } catch (error) {
+    // Clean up temp file if it exists
+    try {
+      await fs.unlink(tempPath);
+    } catch {
+      // Ignore cleanup errors
+    }
+    throw error;
+  }
+}
+
+/**
+ * Safely read JSON file with fallback to default
+ */
+async function readJsonFile<T>(filePath: string, defaultValue: T): Promise<T> {
+  try {
+    const content = await fs.readFile(filePath, "utf-8");
+    return JSON.parse(content) as T;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return defaultValue;
+    }
+    logger.error(`Error reading ${filePath}:`, error);
+    return defaultValue;
+  }
+}
+
+/**
+ * Check if a file exists
+ */
+async function fileExists(filePath: string): Promise<boolean> {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export class SettingsService {
+  private dataDir: string;
+
+  constructor(dataDir: string) {
+    this.dataDir = dataDir;
+  }
+
+  // ============================================================================
+  // Global Settings
+  // ============================================================================
+
+  /**
+   * Get global settings
+   */
+  async getGlobalSettings(): Promise<GlobalSettings> {
+    const settingsPath = getGlobalSettingsPath(this.dataDir);
+    const settings = await readJsonFile<GlobalSettings>(
+      settingsPath,
+      DEFAULT_GLOBAL_SETTINGS
+    );
+
+    // Apply any missing defaults (for backwards compatibility)
+    return {
+      ...DEFAULT_GLOBAL_SETTINGS,
+      ...settings,
+      keyboardShortcuts: {
+        ...DEFAULT_GLOBAL_SETTINGS.keyboardShortcuts,
+        ...settings.keyboardShortcuts,
+      },
+    };
+  }
+
+  /**
+   * Update global settings (partial update)
+   */
+  async updateGlobalSettings(
+    updates: Partial<GlobalSettings>
+  ): Promise<GlobalSettings> {
+    await ensureDataDir(this.dataDir);
+    const settingsPath = getGlobalSettingsPath(this.dataDir);
+
+    const current = await this.getGlobalSettings();
+    const updated: GlobalSettings = {
+      ...current,
+      ...updates,
+      version: SETTINGS_VERSION,
+    };
+
+    // Deep merge keyboard shortcuts if provided
+    if (updates.keyboardShortcuts) {
+      updated.keyboardShortcuts = {
+        ...current.keyboardShortcuts,
+        ...updates.keyboardShortcuts,
+      };
+    }
+
+    await atomicWriteJson(settingsPath, updated);
+    logger.info("Global settings updated");
+
+    return updated;
+  }
+
+  /**
+   * Check if global settings file exists
+   */
+  async hasGlobalSettings(): Promise<boolean> {
+    const settingsPath = getGlobalSettingsPath(this.dataDir);
+    return fileExists(settingsPath);
+  }
+
+  // ============================================================================
+  // Credentials
+  // ============================================================================
+
+  /**
+   * Get credentials
+   */
+  async getCredentials(): Promise<Credentials> {
+    const credentialsPath = getCredentialsPath(this.dataDir);
+    const credentials = await readJsonFile<Credentials>(
+      credentialsPath,
+      DEFAULT_CREDENTIALS
+    );
+
+    return {
+      ...DEFAULT_CREDENTIALS,
+      ...credentials,
+      apiKeys: {
+        ...DEFAULT_CREDENTIALS.apiKeys,
+        ...credentials.apiKeys,
+      },
+    };
+  }
+
+  /**
+   * Update credentials (partial update)
+   */
+  async updateCredentials(
+    updates: Partial<Credentials>
+  ): Promise<Credentials> {
+    await ensureDataDir(this.dataDir);
+    const credentialsPath = getCredentialsPath(this.dataDir);
+
+    const current = await this.getCredentials();
+    const updated: Credentials = {
+      ...current,
+      ...updates,
+      version: CREDENTIALS_VERSION,
+    };
+
+    // Deep merge api keys if provided
+    if (updates.apiKeys) {
+      updated.apiKeys = {
+        ...current.apiKeys,
+        ...updates.apiKeys,
+      };
+    }
+
+    await atomicWriteJson(credentialsPath, updated);
+    logger.info("Credentials updated");
+
+    return updated;
+  }
+
+  /**
+   * Get masked credentials (for UI display - don't expose full keys)
+   */
+  async getMaskedCredentials(): Promise<{
+    anthropic: { configured: boolean; masked: string };
+    google: { configured: boolean; masked: string };
+    openai: { configured: boolean; masked: string };
+  }> {
+    const credentials = await this.getCredentials();
+
+    const maskKey = (key: string): string => {
+      if (!key || key.length < 8) return "";
+      return `${key.substring(0, 4)}...${key.substring(key.length - 4)}`;
+    };
+
+    return {
+      anthropic: {
+        configured: !!credentials.apiKeys.anthropic,
+        masked: maskKey(credentials.apiKeys.anthropic),
+      },
+      google: {
+        configured: !!credentials.apiKeys.google,
+        masked: maskKey(credentials.apiKeys.google),
+      },
+      openai: {
+        configured: !!credentials.apiKeys.openai,
+        masked: maskKey(credentials.apiKeys.openai),
+      },
+    };
+  }
+
+  /**
+   * Check if credentials file exists
+   */
+  async hasCredentials(): Promise<boolean> {
+    const credentialsPath = getCredentialsPath(this.dataDir);
+    return fileExists(credentialsPath);
+  }
+
+  // ============================================================================
+  // Project Settings
+  // ============================================================================
+
+  /**
+   * Get project settings
+   */
+  async getProjectSettings(projectPath: string): Promise<ProjectSettings> {
+    const settingsPath = getProjectSettingsPath(projectPath);
+    const settings = await readJsonFile<ProjectSettings>(
+      settingsPath,
+      DEFAULT_PROJECT_SETTINGS
+    );
+
+    return {
+      ...DEFAULT_PROJECT_SETTINGS,
+      ...settings,
+    };
+  }
+
+  /**
+   * Update project settings (partial update)
+   */
+  async updateProjectSettings(
+    projectPath: string,
+    updates: Partial<ProjectSettings>
+  ): Promise<ProjectSettings> {
+    await ensureAutomakerDir(projectPath);
+    const settingsPath = getProjectSettingsPath(projectPath);
+
+    const current = await this.getProjectSettings(projectPath);
+    const updated: ProjectSettings = {
+      ...current,
+      ...updates,
+      version: PROJECT_SETTINGS_VERSION,
+    };
+
+    // Deep merge board background if provided
+    if (updates.boardBackground) {
+      updated.boardBackground = {
+        ...current.boardBackground,
+        ...updates.boardBackground,
+      };
+    }
+
+    await atomicWriteJson(settingsPath, updated);
+    logger.info(`Project settings updated for ${projectPath}`);
+
+    return updated;
+  }
+
+  /**
+   * Check if project settings file exists
+   */
+  async hasProjectSettings(projectPath: string): Promise<boolean> {
+    const settingsPath = getProjectSettingsPath(projectPath);
+    return fileExists(settingsPath);
+  }
+
+  // ============================================================================
+  // Migration
+  // ============================================================================
+
+  /**
+   * Migrate settings from localStorage data
+   * This is called when the UI detects it has localStorage data but no settings files
+   */
+  async migrateFromLocalStorage(localStorageData: {
+    "automaker-storage"?: string;
+    "automaker-setup"?: string;
+    "worktree-panel-collapsed"?: string;
+    "file-browser-recent-folders"?: string;
+    "automaker:lastProjectDir"?: string;
+  }): Promise<{
+    success: boolean;
+    migratedGlobalSettings: boolean;
+    migratedCredentials: boolean;
+    migratedProjectCount: number;
+    errors: string[];
+  }> {
+    const errors: string[] = [];
+    let migratedGlobalSettings = false;
+    let migratedCredentials = false;
+    let migratedProjectCount = 0;
+
+    try {
+      // Parse the main automaker-storage
+      let appState: Record<string, unknown> = {};
+      if (localStorageData["automaker-storage"]) {
+        try {
+          const parsed = JSON.parse(localStorageData["automaker-storage"]);
+          appState = parsed.state || parsed;
+        } catch (e) {
+          errors.push(`Failed to parse automaker-storage: ${e}`);
+        }
+      }
+
+      // Extract global settings
+      const globalSettings: Partial<GlobalSettings> = {
+        theme: (appState.theme as GlobalSettings["theme"]) || "dark",
+        sidebarOpen:
+          appState.sidebarOpen !== undefined
+            ? (appState.sidebarOpen as boolean)
+            : true,
+        chatHistoryOpen: (appState.chatHistoryOpen as boolean) || false,
+        kanbanCardDetailLevel:
+          (appState.kanbanCardDetailLevel as GlobalSettings["kanbanCardDetailLevel"]) ||
+          "standard",
+        maxConcurrency: (appState.maxConcurrency as number) || 3,
+        defaultSkipTests:
+          appState.defaultSkipTests !== undefined
+            ? (appState.defaultSkipTests as boolean)
+            : true,
+        enableDependencyBlocking:
+          appState.enableDependencyBlocking !== undefined
+            ? (appState.enableDependencyBlocking as boolean)
+            : true,
+        useWorktrees: (appState.useWorktrees as boolean) || false,
+        showProfilesOnly: (appState.showProfilesOnly as boolean) || false,
+        defaultPlanningMode:
+          (appState.defaultPlanningMode as GlobalSettings["defaultPlanningMode"]) ||
+          "skip",
+        defaultRequirePlanApproval:
+          (appState.defaultRequirePlanApproval as boolean) || false,
+        defaultAIProfileId:
+          (appState.defaultAIProfileId as string | null) || null,
+        muteDoneSound: (appState.muteDoneSound as boolean) || false,
+        enhancementModel:
+          (appState.enhancementModel as GlobalSettings["enhancementModel"]) ||
+          "sonnet",
+        keyboardShortcuts:
+          (appState.keyboardShortcuts as KeyboardShortcuts) ||
+          DEFAULT_GLOBAL_SETTINGS.keyboardShortcuts,
+        aiProfiles: (appState.aiProfiles as AIProfile[]) || [],
+        projects: (appState.projects as ProjectRef[]) || [],
+        trashedProjects:
+          (appState.trashedProjects as TrashedProjectRef[]) || [],
+        projectHistory: (appState.projectHistory as string[]) || [],
+        projectHistoryIndex: (appState.projectHistoryIndex as number) || -1,
+        lastSelectedSessionByProject:
+          (appState.lastSelectedSessionByProject as Record<string, string>) ||
+          {},
+      };
+
+      // Add direct localStorage values
+      if (localStorageData["automaker:lastProjectDir"]) {
+        globalSettings.lastProjectDir =
+          localStorageData["automaker:lastProjectDir"];
+      }
+
+      if (localStorageData["file-browser-recent-folders"]) {
+        try {
+          globalSettings.recentFolders = JSON.parse(
+            localStorageData["file-browser-recent-folders"]
+          );
+        } catch {
+          globalSettings.recentFolders = [];
+        }
+      }
+
+      if (localStorageData["worktree-panel-collapsed"]) {
+        globalSettings.worktreePanelCollapsed =
+          localStorageData["worktree-panel-collapsed"] === "true";
+      }
+
+      // Save global settings
+      await this.updateGlobalSettings(globalSettings);
+      migratedGlobalSettings = true;
+      logger.info("Migrated global settings from localStorage");
+
+      // Extract and save credentials
+      if (appState.apiKeys) {
+        const apiKeys = appState.apiKeys as {
+          anthropic?: string;
+          google?: string;
+          openai?: string;
+        };
+        await this.updateCredentials({
+          apiKeys: {
+            anthropic: apiKeys.anthropic || "",
+            google: apiKeys.google || "",
+            openai: apiKeys.openai || "",
+          },
+        });
+        migratedCredentials = true;
+        logger.info("Migrated credentials from localStorage");
+      }
+
+      // Migrate per-project settings
+      const boardBackgroundByProject = appState.boardBackgroundByProject as
+        | Record<string, BoardBackgroundSettings>
+        | undefined;
+      const currentWorktreeByProject = appState.currentWorktreeByProject as
+        | Record<string, { path: string | null; branch: string }>
+        | undefined;
+      const worktreesByProject = appState.worktreesByProject as
+        | Record<string, WorktreeInfo[]>
+        | undefined;
+
+      // Get unique project paths that have per-project settings
+      const projectPaths = new Set<string>();
+      if (boardBackgroundByProject) {
+        Object.keys(boardBackgroundByProject).forEach((p) =>
+          projectPaths.add(p)
+        );
+      }
+      if (currentWorktreeByProject) {
+        Object.keys(currentWorktreeByProject).forEach((p) =>
+          projectPaths.add(p)
+        );
+      }
+      if (worktreesByProject) {
+        Object.keys(worktreesByProject).forEach((p) => projectPaths.add(p));
+      }
+
+      // Also check projects list for theme settings
+      const projects = (appState.projects as ProjectRef[]) || [];
+      for (const project of projects) {
+        if (project.theme) {
+          projectPaths.add(project.path);
+        }
+      }
+
+      // Migrate each project's settings
+      for (const projectPath of projectPaths) {
+        try {
+          const projectSettings: Partial<ProjectSettings> = {};
+
+          // Get theme from project object
+          const project = projects.find((p) => p.path === projectPath);
+          if (project?.theme) {
+            projectSettings.theme =
+              project.theme as ProjectSettings["theme"];
+          }
+
+          if (boardBackgroundByProject?.[projectPath]) {
+            projectSettings.boardBackground =
+              boardBackgroundByProject[projectPath];
+          }
+
+          if (currentWorktreeByProject?.[projectPath]) {
+            projectSettings.currentWorktree =
+              currentWorktreeByProject[projectPath];
+          }
+
+          if (worktreesByProject?.[projectPath]) {
+            projectSettings.worktrees = worktreesByProject[projectPath];
+          }
+
+          if (Object.keys(projectSettings).length > 0) {
+            await this.updateProjectSettings(projectPath, projectSettings);
+            migratedProjectCount++;
+          }
+        } catch (e) {
+          errors.push(`Failed to migrate project settings for ${projectPath}: ${e}`);
+        }
+      }
+
+      logger.info(
+        `Migration complete: ${migratedProjectCount} projects migrated`
+      );
+
+      return {
+        success: errors.length === 0,
+        migratedGlobalSettings,
+        migratedCredentials,
+        migratedProjectCount,
+        errors,
+      };
+    } catch (error) {
+      logger.error("Migration failed:", error);
+      errors.push(`Migration failed: ${error}`);
+      return {
+        success: false,
+        migratedGlobalSettings,
+        migratedCredentials,
+        migratedProjectCount,
+        errors,
+      };
+    }
+  }
+
+  /**
+   * Get the DATA_DIR path (for debugging/info)
+   */
+  getDataDir(): string {
+    return this.dataDir;
+  }
+}

apps/server/src/types/settings.ts

@@ -0,0 +1,269 @@
+/**
+ * Settings Types - Shared types for file-based settings storage
+ */
+
+// Theme modes (matching UI ThemeMode type)
+export type ThemeMode =
+  | "light"
+  | "dark"
+  | "system"
+  | "retro"
+  | "dracula"
+  | "nord"
+  | "monokai"
+  | "tokyonight"
+  | "solarized"
+  | "gruvbox"
+  | "catppuccin"
+  | "onedark"
+  | "synthwave"
+  | "red"
+  | "cream"
+  | "sunset"
+  | "gray";
+
+export type KanbanCardDetailLevel = "minimal" | "standard" | "detailed";
+export type AgentModel = "opus" | "sonnet" | "haiku";
+export type PlanningMode = "skip" | "lite" | "spec" | "full";
+export type ThinkingLevel = "none" | "low" | "medium" | "high" | "ultrathink";
+export type ModelProvider = "claude";
+
+// Keyboard Shortcuts
+export interface KeyboardShortcuts {
+  board: string;
+  agent: string;
+  spec: string;
+  context: string;
+  settings: string;
+  profiles: string;
+  terminal: string;
+  toggleSidebar: string;
+  addFeature: string;
+  addContextFile: string;
+  startNext: string;
+  newSession: string;
+  openProject: string;
+  projectPicker: string;
+  cyclePrevProject: string;
+  cycleNextProject: string;
+  addProfile: string;
+  splitTerminalRight: string;
+  splitTerminalDown: string;
+  closeTerminal: string;
+}
+
+// AI Profile
+export interface AIProfile {
+  id: string;
+  name: string;
+  description: string;
+  model: AgentModel;
+  thinkingLevel: ThinkingLevel;
+  provider: ModelProvider;
+  isBuiltIn: boolean;
+  icon?: string;
+}
+
+// Project reference (minimal info stored in global settings)
+export interface ProjectRef {
+  id: string;
+  name: string;
+  path: string;
+  lastOpened?: string;
+  theme?: string;
+}
+
+// Trashed project reference
+export interface TrashedProjectRef extends ProjectRef {
+  trashedAt: string;
+  deletedFromDisk?: boolean;
+}
+
+// Chat session (minimal info, full content can be loaded separately)
+export interface ChatSessionRef {
+  id: string;
+  title: string;
+  projectId: string;
+  createdAt: string;
+  updatedAt: string;
+  archived: boolean;
+}
+
+/**
+ * Global Settings - stored in {DATA_DIR}/settings.json
+ */
+export interface GlobalSettings {
+  version: number;
+
+  // Theme
+  theme: ThemeMode;
+
+  // UI State
+  sidebarOpen: boolean;
+  chatHistoryOpen: boolean;
+  kanbanCardDetailLevel: KanbanCardDetailLevel;
+
+  // Feature Defaults
+  maxConcurrency: number;
+  defaultSkipTests: boolean;
+  enableDependencyBlocking: boolean;
+  useWorktrees: boolean;
+  showProfilesOnly: boolean;
+  defaultPlanningMode: PlanningMode;
+  defaultRequirePlanApproval: boolean;
+  defaultAIProfileId: string | null;
+
+  // Audio
+  muteDoneSound: boolean;
+
+  // Enhancement
+  enhancementModel: AgentModel;
+
+  // Keyboard Shortcuts
+  keyboardShortcuts: KeyboardShortcuts;
+
+  // AI Profiles
+  aiProfiles: AIProfile[];
+
+  // Projects
+  projects: ProjectRef[];
+  trashedProjects: TrashedProjectRef[];
+  projectHistory: string[];
+  projectHistoryIndex: number;
+
+  // UI Preferences (previously in direct localStorage)
+  lastProjectDir?: string;
+  recentFolders: string[];
+  worktreePanelCollapsed: boolean;
+
+  // Session tracking (per-project, keyed by project path)
+  lastSelectedSessionByProject: Record<string, string>;
+}
+
+/**
+ * Credentials - stored in {DATA_DIR}/credentials.json
+ */
+export interface Credentials {
+  version: number;
+  apiKeys: {
+    anthropic: string;
+    google: string;
+    openai: string;
+  };
+}
+
+/**
+ * Board Background Settings
+ */
+export interface BoardBackgroundSettings {
+  imagePath: string | null;
+  imageVersion?: number;
+  cardOpacity: number;
+  columnOpacity: number;
+  columnBorderEnabled: boolean;
+  cardGlassmorphism: boolean;
+  cardBorderEnabled: boolean;
+  cardBorderOpacity: number;
+  hideScrollbar: boolean;
+}
+
+/**
+ * Worktree Info
+ */
+export interface WorktreeInfo {
+  path: string;
+  branch: string;
+  isMain: boolean;
+  hasChanges?: boolean;
+  changedFilesCount?: number;
+}
+
+/**
+ * Per-Project Settings - stored in {projectPath}/.automaker/settings.json
+ */
+export interface ProjectSettings {
+  version: number;
+
+  // Theme override (null = use global)
+  theme?: ThemeMode;
+
+  // Worktree settings
+  useWorktrees?: boolean;
+  currentWorktree?: { path: string | null; branch: string };
+  worktrees?: WorktreeInfo[];
+
+  // Board background
+  boardBackground?: BoardBackgroundSettings;
+
+  // Last selected session
+  lastSelectedSessionId?: string;
+}
+
+// Default values
+export const DEFAULT_KEYBOARD_SHORTCUTS: KeyboardShortcuts = {
+  board: "K",
+  agent: "A",
+  spec: "D",
+  context: "C",
+  settings: "S",
+  profiles: "M",
+  terminal: "T",
+  toggleSidebar: "`",
+  addFeature: "N",
+  addContextFile: "N",
+  startNext: "G",
+  newSession: "N",
+  openProject: "O",
+  projectPicker: "P",
+  cyclePrevProject: "Q",
+  cycleNextProject: "E",
+  addProfile: "N",
+  splitTerminalRight: "Alt+D",
+  splitTerminalDown: "Alt+S",
+  closeTerminal: "Alt+W",
+};
+
+export const DEFAULT_GLOBAL_SETTINGS: GlobalSettings = {
+  version: 1,
+  theme: "dark",
+  sidebarOpen: true,
+  chatHistoryOpen: false,
+  kanbanCardDetailLevel: "standard",
+  maxConcurrency: 3,
+  defaultSkipTests: true,
+  enableDependencyBlocking: true,
+  useWorktrees: false,
+  showProfilesOnly: false,
+  defaultPlanningMode: "skip",
+  defaultRequirePlanApproval: false,
+  defaultAIProfileId: null,
+  muteDoneSound: false,
+  enhancementModel: "sonnet",
+  keyboardShortcuts: DEFAULT_KEYBOARD_SHORTCUTS,
+  aiProfiles: [],
+  projects: [],
+  trashedProjects: [],
+  projectHistory: [],
+  projectHistoryIndex: -1,
+  lastProjectDir: undefined,
+  recentFolders: [],
+  worktreePanelCollapsed: false,
+  lastSelectedSessionByProject: {},
+};
+
+export const DEFAULT_CREDENTIALS: Credentials = {
+  version: 1,
+  apiKeys: {
+    anthropic: "",
+    google: "",
+    openai: "",
+  },
+};
+
+export const DEFAULT_PROJECT_SETTINGS: ProjectSettings = {
+  version: 1,
+};
+
+export const SETTINGS_VERSION = 1;
+export const CREDENTIALS_VERSION = 1;
+export const PROJECT_SETTINGS_VERSION = 1;