Persist local user settings

[williamthorsen]

Problem

The Factory sidebar allows orchestration runs to be dismissed from the list, but dismissals are stored in React state (useState) and lost on page refresh. The entire list reappears after any reload.

Proposed solution

Persist user settings to a server-side JSON file via new REST API endpoints. The Express server gains a SettingsStore service that reads/writes settings.json to a configurable directory (FACTORY_SETTINGS_PATH env var, defaulting to ~/.config/codeassembly/factory/). New GET/PATCH /api/settings endpoints expose settings to the client. The useDismissedRuns hook switches from in-memory useState to server-synced state with optimistic updates.

Key design decisions

• Server-persisted to disk (not browser localStorage) because the app runs locally
• Configurable path: FACTORY_SETTINGS_PATH env var > ~/.config/codeassembly/factory/settings.json default (follows existing AI_PROJECTS_PATH pattern)
• Status-aware dismissals: Each dismissed run records the status at dismissal time. If a run's status changes (e.g., re-executed), it reappears automatically
• Extensible settings model: UserSettings interface supports future UI preferences as new top-level keys
• Atomic writes: Write to temp file + rename to prevent corruption on crash
• Graceful degradation: Missing/corrupted settings file falls back to defaults; client falls back to session-only behavior if server is unreachable

Data model

{
  "dismissedRuns": {
    "my-project/TICKET-1/run-001": { "status": "completed" },
    "my-project/TICKET-2/run-002": { "status": "failed" }
  }
}

Acceptance criteria

• Dismissing a run persists to settings.json on disk
• Dismissed runs remain dismissed after page refresh
• A dismissed run reappears if its status changes (e.g., re-executed)
• "Clear all" persists all dismissals at once
• Settings directory is created automatically if it doesn't exist
• Missing or corrupted settings file falls back to empty defaults without crashing
• Settings path is configurable via FACTORY_SETTINGS_PATH env var
• All new code has unit tests (SettingsStore, settings route, updated hook)
• pnpm run check passes

[williamthorsen]

Implementation plan

Persist local user settings — implementation plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Persist dismissed-run state to a server-side JSON file so dismissals survive page refreshes.

Architecture: The Express server gains a SettingsStore service that reads/writes settings.json to a configurable directory (FACTORY_SETTINGS_PATH env var, defaulting to ~/.config/codeassembly/factory/). New REST endpoints (GET/PATCH /api/settings) expose the settings to the client. The existing useDismissedRuns hook switches from in-memory useState to server-synced state with optimistic updates. Dismissed runs store the status at dismissal time; runs whose status changes reappear automatically.

Tech Stack: Express 5, React 19, Zod, Vitest, @testing-library/react

---

Task 1: Shared types and Zod schema for user settings

Files:

• Create: packages/factory/src/shared/types/settings.ts
• Create: packages/factory/src/server/adapters/schemas/settings-schema.ts
• Test: packages/factory/src/server/adapters/schemas/__tests__/settings-schema.test.ts

Step 1: Write the failing test

Create packages/factory/src/server/adapters/schemas/__tests__/settings-schema.test.ts:

import { describe, expect, it } from 'vitest';

import { userSettingsSchema } from '../settings-schema.js';

describe('userSettingsSchema', () => {
  it('accepts empty dismissedRuns', () => {
    const result = userSettingsSchema.safeParse({ dismissedRuns: {} });
    expect(result.success).toBe(true);
  });

  it('accepts valid dismissed run entries', () => {
    const result = userSettingsSchema.safeParse({
      dismissedRuns: {
        'my-project/TICKET-1/run-001': { status: 'completed' },
        'my-project/TICKET-2/run-002': { status: 'failed' },
      },
    });
    expect(result.success).toBe(true);
  });

  it('rejects missing dismissedRuns key', () => {
    const result = userSettingsSchema.safeParse({});
    expect(result.success).toBe(false);
  });

  it('rejects entry without status', () => {
    const result = userSettingsSchema.safeParse({
      dismissedRuns: { 'key': {} },
    });
    expect(result.success).toBe(false);
  });

  it('rejects non-string status', () => {
    const result = userSettingsSchema.safeParse({
      dismissedRuns: { 'key': { status: 42 } },
    });
    expect(result.success).toBe(false);
  });
});

Step 2: Run test to verify it fails

Step 3: Write the shared types

Create packages/factory/src/shared/types/settings.ts:

export interface DismissedRunEntry {
  status: string;
}

export interface UserSettings {
  dismissedRuns: Record<string, DismissedRunEntry>;
}

Step 4: Write the Zod schema

Create packages/factory/src/server/adapters/schemas/settings-schema.ts:

import { z } from 'zod';

const dismissedRunEntrySchema = z.object({
  status: z.string(),
});

export const userSettingsSchema = z.object({
  dismissedRuns: z.record(z.string(), dismissedRunEntrySchema),
});

Step 5: Run test to verify it passes

Step 6: Commit

---

Task 2: SettingsStore service

Files:

• Create: packages/factory/src/server/services/settings-store.ts
• Test: packages/factory/src/server/services/__tests__/settings-store.test.ts

Reference: Look at project-scanner.ts for constructor pattern (optional path > env var > default). Look at type-guards.ts for isEnoent. Look at run-index-schema.ts for Zod validation pattern.

Step 1: Write the failing tests

Create packages/factory/src/server/services/__tests__/settings-store.test.ts:

import { mkdir, readFile, writeFile } from 'node:fs/promises';
import { join } from 'node:path';

import { afterEach, beforeEach, describe, expect, it } from 'vitest';

import type { UserSettings } from '../../../shared/types/settings.js';
import { SettingsStore } from '../settings-store.js';

let tmpDir: string;
let settingsPath: string;

beforeEach(async () => {
  const { mkdtemp } = await import('node:fs/promises');
  const { tmpdir } = await import('node:os');
  tmpDir = await mkdtemp(join(tmpdir(), 'settings-store-test-'));
  settingsPath = join(tmpDir, 'settings.json');
});

afterEach(async () => {
  const { rm } = await import('node:fs/promises');
  await rm(tmpDir, { recursive: true, force: true });
});

describe('SettingsStore', () => {
  describe('load', () => {
    it('returns defaults when file does not exist', async () => {
      const store = new SettingsStore(settingsPath);
      const settings = await store.load();
      expect(settings).toEqual({ dismissedRuns: {} });
    });

    it('returns parsed settings from valid file', async () => {
      const data: UserSettings = {
        dismissedRuns: { 'proj/T-1/run-1': { status: 'completed' } },
      };
      await writeFile(settingsPath, JSON.stringify(data), 'utf8');
      const store = new SettingsStore(settingsPath);
      const settings = await store.load();
      expect(settings).toEqual(data);
    });

    it('returns defaults when file contains invalid JSON', async () => {
      await writeFile(settingsPath, 'not valid json!!!', 'utf8');
      const store = new SettingsStore(settingsPath);
      const settings = await store.load();
      expect(settings).toEqual({ dismissedRuns: {} });
    });

    it('returns defaults when file contains JSON that does not match schema', async () => {
      await writeFile(settingsPath, JSON.stringify({ wrong: true }), 'utf8');
      const store = new SettingsStore(settingsPath);
      const settings = await store.load();
      expect(settings).toEqual({ dismissedRuns: {} });
    });
  });

  describe('save', () => {
    it('writes settings to disk', async () => {
      const store = new SettingsStore(settingsPath);
      const data: UserSettings = {
        dismissedRuns: { 'proj/T-1/run-1': { status: 'failed' } },
      };
      await store.save(data);
      const raw = await readFile(settingsPath, 'utf8');
      expect(JSON.parse(raw)).toEqual(data);
    });

    it('creates parent directory if it does not exist', async () => {
      const nested = join(tmpDir, 'nested', 'deep', 'settings.json');
      const store = new SettingsStore(nested);
      await store.save({ dismissedRuns: {} });
      const raw = await readFile(nested, 'utf8');
      expect(JSON.parse(raw)).toEqual({ dismissedRuns: {} });
    });
  });

  describe('patch', () => {
    it('merges partial settings into existing file', async () => {
      const initial: UserSettings = {
        dismissedRuns: { 'proj/T-1/run-1': { status: 'completed' } },
      };
      await writeFile(settingsPath, JSON.stringify(initial), 'utf8');
      const store = new SettingsStore(settingsPath);
      const result = await store.patch({
        dismissedRuns: {
          'proj/T-1/run-1': { status: 'completed' },
          'proj/T-2/run-2': { status: 'failed' },
        },
      });
      expect(result.dismissedRuns).toEqual({
        'proj/T-1/run-1': { status: 'completed' },
        'proj/T-2/run-2': { status: 'failed' },
      });
      const reloaded = await store.load();
      expect(reloaded).toEqual(result);
    });

    it('creates file from defaults when patching non-existent file', async () => {
      const store = new SettingsStore(settingsPath);
      const result = await store.patch({
        dismissedRuns: { 'proj/T-1/run-1': { status: 'completed' } },
      });
      expect(result).toEqual({
        dismissedRuns: { 'proj/T-1/run-1': { status: 'completed' } },
      });
    });
  });

  describe('path resolution', () => {
    it('uses constructor path when provided', () => {
      const store = new SettingsStore('/custom/path/settings.json');
      expect(store.getFilePath()).toBe('/custom/path/settings.json');
    });

    it('falls back to FACTORY_SETTINGS_PATH env var', () => {
      const original = process.env.FACTORY_SETTINGS_PATH;
      try {
        process.env.FACTORY_SETTINGS_PATH = '/env/path';
        const store = new SettingsStore();
        expect(store.getFilePath()).toBe('/env/path/settings.json');
      } finally {
        if (original === undefined) {
          delete process.env.FACTORY_SETTINGS_PATH;
        } else {
          process.env.FACTORY_SETTINGS_PATH = original;
        }
      }
    });

    it('falls back to default path when no constructor arg or env var', () => {
      const original = process.env.FACTORY_SETTINGS_PATH;
      try {
        delete process.env.FACTORY_SETTINGS_PATH;
        const store = new SettingsStore();
        expect(store.getFilePath()).toContain('.config/codeassembly/factory/settings.json');
      } finally {
        if (original !== undefined) {
          process.env.FACTORY_SETTINGS_PATH = original;
        }
      }
    });
  });
});

Step 2: Run test to verify it fails

Step 3: Write the SettingsStore implementation

Create packages/factory/src/server/services/settings-store.ts:

import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
import { homedir } from 'node:os';
import { dirname, join } from 'node:path';

import type { UserSettings } from '../../shared/types/settings.js';
import { userSettingsSchema } from '../adapters/schemas/settings-schema.js';
import { isEnoent } from '../type-guards.js';

const DEFAULT_SETTINGS: UserSettings = { dismissedRuns: {} };
const SETTINGS_FILENAME = 'settings.json';

export class SettingsStore {
  private readonly filePath: string;

  constructor(filePath?: string) {
    if (filePath) {
      this.filePath = filePath;
    } else {
      const dir = process.env.FACTORY_SETTINGS_PATH ?? join(homedir(), '.config', 'codeassembly', 'factory');
      this.filePath = join(dir, SETTINGS_FILENAME);
    }
  }

  getFilePath(): string {
    return this.filePath;
  }

  async load(): Promise<UserSettings> {
    let raw: string;
    try {
      raw = await readFile(this.filePath, 'utf8');
    } catch (error) {
      if (isEnoent(error)) return { ...DEFAULT_SETTINGS };
      console.warn('Failed to read settings file:', error);
      return { ...DEFAULT_SETTINGS };
    }

    let parsed: unknown;
    try {
      parsed = JSON.parse(raw);
    } catch {
      console.warn('Settings file contains invalid JSON, using defaults');
      return { ...DEFAULT_SETTINGS };
    }

    const result = userSettingsSchema.safeParse(parsed);
    if (!result.success) {
      console.warn('Settings file does not match schema, using defaults:', result.error.message);
      return { ...DEFAULT_SETTINGS };
    }
    return result.data;
  }

  async save(settings: UserSettings): Promise<void> {
    const dir = dirname(this.filePath);
    await mkdir(dir, { recursive: true });
    const tmpPath = `${this.filePath}.tmp`;
    await writeFile(tmpPath, JSON.stringify(settings, null, 2), 'utf8');
    await rename(tmpPath, this.filePath);
  }

  async patch(partial: Partial<UserSettings>): Promise<UserSettings> {
    const current = await this.load();
    const merged: UserSettings = { ...current, ...partial };
    await this.save(merged);
    return merged;
  }
}

Step 4: Run test to verify it passes

Step 5: Commit

---

Task 3: Settings route

Files:

• Create: packages/factory/src/server/routes/settings.ts
• Test: packages/factory/src/server/routes/__tests__/settings.test.ts

Step 1: Write the failing tests

Create packages/factory/src/server/routes/__tests__/settings.test.ts with tests for:

• GET / returns default settings when no file exists
• GET / returns persisted settings
• PATCH / merges and returns updated settings
• PATCH / returns 400 for invalid body

Step 2: Run test to verify it fails

Step 3: Write the route

Create packages/factory/src/server/routes/settings.ts:

import type { Request, Response } from 'express';
import { Router } from 'express';

import { userSettingsSchema } from '../adapters/schemas/settings-schema.js';
import type { SettingsStore } from '../services/settings-store.js';

export function createSettingsRouter(store: SettingsStore): Router {
  const router = Router();

  router.get('/', async (_req: Request, res: Response) => {
    try {
      const settings = await store.load();
      res.json(settings);
    } catch (error) {
      console.error('Failed to load settings:', error);
      res.status(500).json({ error: 'Failed to load settings' });
    }
  });

  router.patch('/', async (req: Request, res: Response) => {
    const parseResult = userSettingsSchema.partial().safeParse(req.body);
    if (!parseResult.success) {
      res.status(400).json({ error: 'Invalid settings', details: parseResult.error.message });
      return;
    }
    try {
      const merged = await store.patch(parseResult.data);
      res.json(merged);
    } catch (error) {
      console.error('Failed to save settings:', error);
      res.status(500).json({ error: 'Failed to save settings' });
    }
  });

  return router;
}

Step 4: Run test to verify it passes

Step 5: Commit

---

Task 4: Register settings route in server

Files:

• Modify: packages/factory/src/server/index.ts

Add imports for createSettingsRouter and SettingsStore. Instantiate new SettingsStore() and register app.use('/api/settings', createSettingsRouter(settingsStore)).

Run typecheck, then commit.

---

Task 5: Client API functions for settings

Files:

• Modify: packages/factory/src/client/api/client.ts

Add fetchSettings() and patchSettings(partial) functions. fetchSettings uses the existing fetchJson helper. patchSettings uses fetch with PATCH method and Content-Type: application/json.

Run typecheck, then commit.

---

Task 6: Rewrite useDismissedRuns hook with server persistence

Files:

• Modify: packages/factory/src/client/hooks/useDismissedRuns.ts
• Rewrite: packages/factory/src/client/hooks/__tests__/useDismissedRuns.test.ts

The hook changes from Set<string> to Record<string, DismissedRunEntry>. On mount, it fetches settings from server. On dismiss, it optimistically updates local state and fires patchSettings in background. The dismiss function now takes (key, status) and dismissAll takes DismissEntry[].

Write tests first (mock fetchSettings and patchSettings), then rewrite the hook.

---

Task 7: Update App.tsx and RunList.tsx for new dismissal API

Files:

• Modify: packages/factory/src/client/App.tsx
• Modify: packages/factory/src/client/components/RunList.tsx

Update visibleRuns filter: a run is visible if not in dismissed record OR if its current status differs from stored status. Update onDismissRun prop to pass (key, status). Update handleDismissAll to pass DismissEntry[].

In RunList.tsx, update onDismissRun prop type to (key: string, status: string) => void and pass run.status in the click handler.

---

Task 8: Run full quality checks

Run pnpm run check (typecheck, lint, format, tests). Fix any issues and commit.

---

Summary of files changed

Action	File
Create	packages/factory/src/shared/types/settings.ts
Create	packages/factory/src/server/adapters/schemas/settings-schema.ts
Create	packages/factory/src/server/adapters/schemas/__tests__/settings-schema.test.ts
Create	packages/factory/src/server/services/settings-store.ts
Create	packages/factory/src/server/services/__tests__/settings-store.test.ts
Create	packages/factory/src/server/routes/settings.ts
Create	packages/factory/src/server/routes/__tests__/settings.test.ts
Modify	packages/factory/src/server/index.ts
Modify	packages/factory/src/client/api/client.ts
Modify	packages/factory/src/client/hooks/useDismissedRuns.ts
Rewrite	packages/factory/src/client/hooks/__tests__/useDismissedRuns.test.ts
Modify	packages/factory/src/client/App.tsx
Modify	packages/factory/src/client/components/RunList.tsx