dialectic 0.1.0

package/tests/clarifications.spec.ts

@@ -0,0 +1,128 @@
+// Mock OpenAI SDK to avoid network calls during CLI tests
+jest.mock('openai', () => {
+  return {
+    __esModule: true,
+    default: class OpenAIMock {
+      public chat = {
+        completions: {
+          create: async (_: any) => ({ choices: [{ message: { content: 'Solution text' } }] }),
+        },
+      };
+      constructor(_opts: any) {}
+    },
+  };
+});
+
+// Mock env-loader
+jest.mock('../src/utils/env-loader', () => ({
+  loadEnvironmentFile: jest.fn()
+}));
+
+// Mock readline module
+jest.mock('readline', () => {
+  let mockAnswers: string[] = [];
+  let currentIndex = 0;
+  
+  return {
+    __esModule: true,
+    default: {
+      createInterface: () => ({
+        question: (_: any, cb: (ans: string) => void) => {
+          const ans = currentIndex < mockAnswers.length ? mockAnswers[currentIndex++] : '';
+          // Use setImmediate to make it async like real readline
+          setImmediate(() => cb(String(ans)));
+        },
+        close: () => {},
+      })
+    },
+    // Helper function to set mock answers
+    __setMockAnswers: (answers: string[]) => {
+      mockAnswers = answers;
+      currentIndex = 0;
+    }
+  };
+});
+
+import os from 'os';
+import path from 'path';
+import fs from 'fs';
+import { runCli } from '../src/cli/index';
+import { loadEnvironmentFile } from '../src/utils/env-loader';
+import { RoleBasedAgent } from '../src/agents/role-based-agent';
+
+const mockedLoadEnvironmentFile = loadEnvironmentFile as jest.MockedFunction<typeof loadEnvironmentFile>;
+
+describe('CLI clarifications phase', () => {
+  let stderrSpy: jest.SpyInstance;
+  let stdoutSpy: jest.SpyInstance;
+  const originalEnv = process.env;
+
+  beforeEach(() => {
+    process.env = { ...originalEnv, OPENAI_API_KEY: 'test' };
+    stderrSpy = jest.spyOn(process.stderr, 'write').mockImplementation(() => true as any);
+    stdoutSpy = jest.spyOn(process.stdout, 'write').mockImplementation(() => true as any);
+    mockedLoadEnvironmentFile.mockClear();
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
+    stderrSpy.mockRestore();
+    stdoutSpy.mockRestore();
+    jest.restoreAllMocks();
+    jest.resetModules();
+  });
+
+  function mockReadlineWithAnswers(answers: string[]) {
+    // Set mock answers for the readline mock
+    const readlineMock = require('readline');
+    if (readlineMock.__setMockAnswers) {
+      readlineMock.__setMockAnswers(answers);
+    }
+  }
+
+  it('runs clarifications when --clarify and collects answers (including NA)', async () => {
+    // Two questions total across agents; provide one answer and one empty -> NA
+    mockReadlineWithAnswers(['My answer', '']);
+
+    const spy = jest.spyOn(RoleBasedAgent.prototype as any, 'askClarifyingQuestions')
+      .mockResolvedValueOnce({ questions: [{ id: 'q1', text: 'What is the SLA?' }] })
+      .mockResolvedValueOnce({ questions: [{ id: 'q1', text: 'Any data retention rules?' }] });
+
+    const tmpReport = path.join(os.tmpdir(), `clarify-report-${Date.now()}.md`);
+
+    await runCli(['debate', 'Design Y', '--clarify', '--report', tmpReport]);
+
+    expect(spy).toHaveBeenCalled();
+    const content = fs.readFileSync(tmpReport, 'utf-8');
+    expect(content).toContain('## Clarifications');
+    expect(content).toContain('Question (q1):');
+    // Should include the explicit answer
+    expect(content).toContain('My answer');
+    // And NA for the unanswered one
+    expect(content).toContain('\n```text\nNA\n```');
+  });
+
+  it('does not run clarifications without --clarify (default off)', async () => {
+    const spy = jest.spyOn(RoleBasedAgent.prototype as any, 'askClarifyingQuestions')
+      .mockResolvedValue({ questions: [] });
+
+    await runCli(['debate', 'Design Z']);
+    expect(spy).not.toHaveBeenCalled();
+  });
+
+  it('truncates questions per agent and warns', async () => {
+    // Return 7 questions to trigger truncation to default 5
+    const many = Array.from({ length: 7 }, (_, i) => ({ id: `q${i + 1}`, text: `Q${i + 1}` }));
+    const spy = jest.spyOn(RoleBasedAgent.prototype as any, 'askClarifyingQuestions')
+      .mockResolvedValue({ questions: many });
+
+    mockReadlineWithAnswers(new Array(10).fill('A'));
+
+    await runCli(['debate', 'Design W', '--clarify']);
+    expect(spy).toHaveBeenCalled();
+    const stderr = (stderrSpy.mock.calls.map(args => String(args[0])).join(''));
+    expect(stderr).toMatch(/limited to 5/);
+  });
+});
+
+

package/tests/cli.debate.spec.ts

@@ -0,0 +1,144 @@
+// Mock OpenAI SDK to avoid network calls during CLI tests
+jest.mock('openai', () => {
+  return {
+    __esModule: true,
+    default: class OpenAIMock {
+      public chat = {
+        completions: {
+          create: async (_: any) => ({ choices: [{ message: { content: 'Solution text' } }] }),
+        },
+      };
+      constructor(_opts: any) {}
+    },
+  };
+});
+
+// Mock env-loader
+jest.mock('../src/utils/env-loader', () => ({
+  loadEnvironmentFile: jest.fn()
+}));
+
+import { runCli } from '../src/cli/index';
+import { EXIT_CONFIG_ERROR, EXIT_INVALID_ARGS } from '../src/utils/exit-codes';
+import { loadEnvironmentFile } from '../src/utils/env-loader';
+
+const mockedLoadEnvironmentFile = loadEnvironmentFile as jest.MockedFunction<typeof loadEnvironmentFile>;
+
+describe('CLI debate command', () => {
+  const originalEnv = process.env;
+  let stderrSpy: jest.SpyInstance;
+  let stdoutSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    process.env = { ...originalEnv };
+    stderrSpy = jest.spyOn(process.stderr, 'write').mockImplementation(() => true);
+    stdoutSpy = jest.spyOn(process.stdout, 'write').mockImplementation(() => true);
+    mockedLoadEnvironmentFile.mockClear();
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
+    stderrSpy.mockRestore();
+    stdoutSpy.mockRestore();
+  });
+
+  it('exits with config error when OPENAI_API_KEY is missing', async () => {
+    delete process.env.OPENAI_API_KEY;
+    await expect(runCli(['debate', 'Design a system'])).rejects.toHaveProperty('code', EXIT_CONFIG_ERROR);
+    expect(stderrSpy).toHaveBeenCalled();
+  });
+
+  it('prints only minimal solution to stdout (non-verbose)', async () => {
+    process.env.OPENAI_API_KEY = 'test';
+    await runCli(['debate', 'Design a rate limiting system']);
+    expect(stdoutSpy).toHaveBeenCalled();
+  });
+
+  it('prints verbose header and summary with metadata when --verbose', async () => {
+    process.env.OPENAI_API_KEY = 'test';
+    const capturedStdout: string[] = [];
+    const capturedStderr: string[] = [];
+    const stdoutWriteSpy = jest.spyOn(process.stdout, 'write').mockImplementation((chunk: any) => {
+      capturedStdout.push(String(chunk));
+      return true as any;
+    });
+    const stderrWriteSpy = jest.spyOn(process.stderr, 'write').mockImplementation((chunk: any) => {
+      capturedStderr.push(String(chunk));
+      return true as any;
+    });
+
+    await runCli(['debate', 'Design X', '--rounds', '2', '--verbose']);
+
+    const stdout = capturedStdout.join('');
+    const stderr = capturedStderr.join('');
+    
+    // Main solution should be on stdout
+    expect(stdout).toContain('Solution text');
+    
+    // Verbose diagnostics should be on stderr
+    expect(stderr).toContain('Running debate (verbose)');
+    expect(stderr).toContain('Summary (verbose)');
+    expect(stderr).toMatch(/Round\s+1/);
+    // Progress UI provides real-time updates, verbose summary shows final details
+    expect(stderr).toMatch(/latency=.+, tokens=/);
+
+    stdoutWriteSpy.mockRestore();
+    stderrWriteSpy.mockRestore();
+  });
+
+  it('should error when neither problem string nor --problemDescription are provided', async () => {
+    process.env.OPENAI_API_KEY = 'test';
+    
+    await expect(runCli(['debate']))
+      .rejects.toHaveProperty('code', EXIT_INVALID_ARGS);
+    expect(stderrSpy).toHaveBeenCalledWith(
+      expect.stringContaining('Invalid arguments: problem is required (provide <problem> or --problemDescription)')
+    );
+  });
+
+  describe('environment file loading', () => {
+    it('should call loadEnvironmentFile with default parameters', async () => {
+      process.env.OPENAI_API_KEY = 'test';
+      
+      await runCli(['debate', 'Design a system']);
+      
+      expect(mockedLoadEnvironmentFile).toHaveBeenCalledWith(undefined, undefined);
+    });
+
+    it('should call loadEnvironmentFile with custom env file path', async () => {
+      process.env.OPENAI_API_KEY = 'test';
+      
+      await runCli(['debate', 'Design a system', '--env-file', 'custom.env']);
+      
+      expect(mockedLoadEnvironmentFile).toHaveBeenCalledWith('custom.env', undefined);
+    });
+
+    it('should call loadEnvironmentFile with verbose flag', async () => {
+      process.env.OPENAI_API_KEY = 'test';
+      
+      await runCli(['debate', 'Design a system', '--verbose']);
+      
+      expect(mockedLoadEnvironmentFile).toHaveBeenCalledWith(undefined, true);
+    });
+
+    it('should call loadEnvironmentFile with both custom env file and verbose flag', async () => {
+      process.env.OPENAI_API_KEY = 'test';
+      
+      await runCli(['debate', 'Design a system', '--env-file', 'production.env', '--verbose']);
+      
+      expect(mockedLoadEnvironmentFile).toHaveBeenCalledWith('production.env', true);
+    });
+
+    it('should handle env loading errors gracefully', async () => {
+      process.env.OPENAI_API_KEY = 'test';
+      mockedLoadEnvironmentFile.mockImplementation(() => {
+        throw new Error('Environment file not found: /path/to/missing.env');
+      });
+      
+      await expect(runCli(['debate', 'Design a system', '--env-file', 'missing.env']))
+        .rejects.toThrow('Environment file not found: /path/to/missing.env');
+      
+      expect(mockedLoadEnvironmentFile).toHaveBeenCalledWith('missing.env', undefined);
+    });
+  });
+});

package/tests/config-loading.spec.ts

@@ -0,0 +1,206 @@
+import { loadConfig } from '../src/cli/commands/debate';
+import { DEFAULT_SUMMARIZATION_ENABLED, DEFAULT_SUMMARIZATION_THRESHOLD, DEFAULT_SUMMARIZATION_MAX_LENGTH, DEFAULT_SUMMARIZATION_METHOD } from '../src/types/config.types';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+// RED-phase: config loader behavior tests; module not implemented yet.
+
+describe('Configuration loading', () => {
+  it('uses built-in defaults when ./debate-config.json is missing and emits a stderr notice', async () => {
+    const defaultConfigPath = path.resolve(process.cwd(), 'debate-config.json');
+    const configExists = fs.existsSync(defaultConfigPath);
+    let configBackup: string | undefined;
+    
+    // Temporarily remove config file if it exists
+    if (configExists) {
+      configBackup = fs.readFileSync(defaultConfigPath, 'utf-8');
+      fs.unlinkSync(defaultConfigPath);
+    }
+    
+    try {
+      const stderrSpy = jest.spyOn(process.stderr, 'write').mockImplementation(() => true);
+      const cfg = await loadConfig(undefined);
+      expect(cfg).toBeDefined();
+      expect(stderrSpy).toHaveBeenCalled();
+      stderrSpy.mockRestore();
+    } finally {
+      // Restore config file if it existed
+      if (configExists && configBackup) {
+        fs.writeFileSync(defaultConfigPath, configBackup, 'utf-8');
+      }
+    }
+  });
+});
+
+describe('Summarization configuration loading', () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'config-test-'));
+  });
+
+  afterEach(() => {
+    try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch {}
+  });
+
+  it('should load default summarization config when not specified', async () => {
+    const stderrSpy = jest.spyOn(process.stderr, 'write').mockImplementation(() => true);
+    const cfg = await loadConfig(undefined);
+    
+    expect(cfg.debate?.summarization).toBeDefined();
+    expect(cfg.debate?.summarization?.enabled).toBe(DEFAULT_SUMMARIZATION_ENABLED);
+    expect(cfg.debate?.summarization?.threshold).toBe(DEFAULT_SUMMARIZATION_THRESHOLD);
+    expect(cfg.debate?.summarization?.maxLength).toBe(DEFAULT_SUMMARIZATION_MAX_LENGTH);
+    expect(cfg.debate?.summarization?.method).toBe(DEFAULT_SUMMARIZATION_METHOD);
+    
+    stderrSpy.mockRestore();
+  });
+
+  it('should load custom summarization config from file', async () => {
+    const configPath = path.join(tmpDir, 'test-config.json');
+    const configContent = {
+      agents: [
+        {
+          id: 'test-agent',
+          name: 'Test Agent',
+          role: 'architect',
+          model: 'gpt-4',
+          provider: 'openai',
+          temperature: 0.5
+        }
+      ],
+      debate: {
+        rounds: 3,
+        terminationCondition: { type: 'fixed' },
+        synthesisMethod: 'judge',
+        includeFullHistory: true,
+        timeoutPerRound: 300000,
+        summarization: {
+          enabled: false,
+          threshold: 3000,
+          maxLength: 1500,
+          method: 'length-based'
+        }
+      }
+    };
+
+    fs.writeFileSync(configPath, JSON.stringify(configContent, null, 2));
+
+    const cfg = await loadConfig(configPath);
+    
+    expect(cfg.debate?.summarization).toBeDefined();
+    expect(cfg.debate?.summarization?.enabled).toBe(false);
+    expect(cfg.debate?.summarization?.threshold).toBe(3000);
+    expect(cfg.debate?.summarization?.maxLength).toBe(1500);
+    expect(cfg.debate?.summarization?.method).toBe('length-based');
+  });
+
+  it('should support per-agent summarization override', async () => {
+    const configPath = path.join(tmpDir, 'test-config.json');
+    const configContent = {
+      agents: [
+        {
+          id: 'test-agent',
+          name: 'Test Agent',
+          role: 'architect',
+          model: 'gpt-4',
+          provider: 'openai',
+          temperature: 0.5,
+          summarization: {
+            enabled: true,
+            threshold: 2000,
+            maxLength: 1000,
+            method: 'length-based'
+          }
+        }
+      ],
+      debate: {
+        rounds: 3,
+        terminationCondition: { type: 'fixed' },
+        synthesisMethod: 'judge',
+        includeFullHistory: true,
+        timeoutPerRound: 300000
+      }
+    };
+
+    fs.writeFileSync(configPath, JSON.stringify(configContent, null, 2));
+
+    const cfg = await loadConfig(configPath);
+    
+    const agent = cfg.agents[0];
+    expect(agent).toBeDefined();
+    expect(agent!.summarization).toBeDefined();
+    expect(agent!.summarization?.enabled).toBe(true);
+    expect(agent!.summarization?.threshold).toBe(2000);
+    expect(agent!.summarization?.maxLength).toBe(1000);
+  });
+
+  it('should support summaryPromptPath in agent config', async () => {
+    const configPath = path.join(tmpDir, 'test-config.json');
+    const configContent = {
+      agents: [
+        {
+          id: 'test-agent',
+          name: 'Test Agent',
+          role: 'architect',
+          model: 'gpt-4',
+          provider: 'openai',
+          temperature: 0.5,
+          summaryPromptPath: './prompts/custom-summary.md'
+        }
+      ],
+      debate: {
+        rounds: 3,
+        terminationCondition: { type: 'fixed' },
+        synthesisMethod: 'judge',
+        includeFullHistory: true,
+        timeoutPerRound: 300000
+      }
+    };
+
+    fs.writeFileSync(configPath, JSON.stringify(configContent, null, 2));
+
+    const cfg = await loadConfig(configPath);
+    
+    const agent = cfg.agents[0];
+    expect(agent).toBeDefined();
+    expect(agent!.summaryPromptPath).toBe('./prompts/custom-summary.md');
+  });
+
+  it('should support partial summarization config', async () => {
+    const configPath = path.join(tmpDir, 'test-config.json');
+    const configContent = {
+      agents: [
+        {
+          id: 'test-agent',
+          name: 'Test Agent',
+          role: 'architect',
+          model: 'gpt-4',
+          provider: 'openai',
+          temperature: 0.5
+        }
+      ],
+      debate: {
+        rounds: 3,
+        terminationCondition: { type: 'fixed' },
+        synthesisMethod: 'judge',
+        includeFullHistory: true,
+        timeoutPerRound: 300000,
+        summarization: {
+          threshold: 10000
+          // Other fields should use defaults
+        }
+      }
+    };
+
+    fs.writeFileSync(configPath, JSON.stringify(configContent, null, 2));
+
+    const cfg = await loadConfig(configPath);
+    
+    expect(cfg.debate?.summarization).toBeDefined();
+    expect(cfg.debate?.summarization?.threshold).toBe(10000);
+    // Partial config should work with merging at runtime
+  });
+});
+

package/tests/context-summarizer.spec.ts

@@ -0,0 +1,131 @@
+import { LengthBasedSummarizer } from '../src/utils/context-summarizer';
+import { LLMProvider } from '../src/providers/llm-provider';
+import { SummarizationConfig, SUMMARIZATION_METHODS } from '../src/types/debate.types';
+import { AGENT_ROLES } from '../src/types/agent.types';
+
+// Mock LLM Provider
+class MockLLMProvider implements LLMProvider {
+  private mockResponse: string;
+  private shouldFail: boolean;
+
+  constructor(mockResponse: string = 'This is a test summary.', shouldFail: boolean = false) {
+    this.mockResponse = mockResponse;
+    this.shouldFail = shouldFail;
+  }
+
+  async complete(_request: any): Promise<any> {
+    if (this.shouldFail) {
+      throw new Error('Mock LLM failure');
+    }
+    return {
+      text: this.mockResponse,
+      usage: { totalTokens: 100 }
+    };
+  }
+}
+
+describe('LengthBasedSummarizer', () => {
+  const config: SummarizationConfig = {
+    enabled: true,
+    threshold: 5000,
+    maxLength: 2500,
+    method: SUMMARIZATION_METHODS.LENGTH_BASED,
+  };
+
+  it('should return summary with correct metadata (configured values)', async () => {
+    const provider = new MockLLMProvider('Test summary content');
+    const summarizer = new LengthBasedSummarizer(provider, { model: 'gpt-4o', temperature: 0.55, provider: 'openai' as any });
+    
+    const content = 'This is the debate history to summarize.';
+    const role = AGENT_ROLES.ARCHITECT;
+    const systemPrompt = 'You are an architect.';
+    const summaryPrompt = 'Summarize this content.';
+
+    const result = await summarizer.summarize(content, role, config, systemPrompt, summaryPrompt);
+
+    expect(result.summary).toBe('Test summary content');
+    expect(result.metadata.beforeChars).toBe(content.length);
+    expect(result.metadata.afterChars).toBe('Test summary content'.length);
+    expect(result.metadata.method).toBe(SUMMARIZATION_METHODS.LENGTH_BASED);
+    expect(result.metadata.timestamp).toBeInstanceOf(Date);
+    expect(result.metadata.latencyMs).toBeGreaterThanOrEqual(0);
+    expect(result.metadata.tokensUsed).toBe(100);
+    expect(result.metadata.model).toBe('gpt-4o');
+    expect(result.metadata.temperature).toBe(0.55);
+    expect(result.metadata.provider).toBe('openai');
+  });
+
+  it('should call LLM provider with correct prompts (defaults as fallbacks)', async () => {
+    const provider = new MockLLMProvider();
+    const completeSpy = jest.spyOn(provider, 'complete');
+    const summarizer = new LengthBasedSummarizer(provider);
+    
+    const content = 'Content to summarize';
+    const systemPrompt = 'System prompt';
+    const summaryPrompt = 'Summary prompt';
+
+    await summarizer.summarize(content, AGENT_ROLES.ARCHITECT, config, systemPrompt, summaryPrompt);
+
+    expect(completeSpy).toHaveBeenCalledWith({
+      model: 'gpt-4',
+      temperature: 0.3,
+      systemPrompt: 'System prompt',
+      userPrompt: 'Summary prompt',
+    });
+  });
+
+  it('should truncate summary to maxLength if needed', async () => {
+    const longSummary = 'a'.repeat(3000);
+    const provider = new MockLLMProvider(longSummary);
+    const summarizer = new LengthBasedSummarizer(provider);
+    
+    const result = await summarizer.summarize('content', AGENT_ROLES.ARCHITECT, config, 'sys', 'sum');
+
+    expect(result.summary.length).toBe(config.maxLength);
+    expect(result.summary).toBe('a'.repeat(config.maxLength));
+  });
+
+  it('should measure latency correctly', async () => {
+    const provider = new MockLLMProvider();
+    const summarizer = new LengthBasedSummarizer(provider);
+    
+    const result = await summarizer.summarize('content', AGENT_ROLES.ARCHITECT, config, 'sys', 'sum');
+
+    expect(result.metadata.latencyMs).toBeDefined();
+    expect(result.metadata.latencyMs).toBeGreaterThanOrEqual(0);
+  });
+
+  it('should handle LLM errors gracefully', async () => {
+    const provider = new MockLLMProvider('', true);
+    const summarizer = new LengthBasedSummarizer(provider);
+    
+    await expect(
+      summarizer.summarize('content', AGENT_ROLES.ARCHITECT, config, 'sys', 'sum')
+    ).rejects.toThrow('Mock LLM failure');
+  });
+
+  it('should include token usage when provided by LLM', async () => {
+    const provider = new MockLLMProvider('Summary');
+    const summarizer = new LengthBasedSummarizer(provider);
+    
+    const result = await summarizer.summarize('content', AGENT_ROLES.ARCHITECT, config, 'sys', 'sum');
+
+    expect(result.metadata.tokensUsed).toBe(100);
+  });
+
+  it('should handle missing token usage from LLM', async () => {
+    class NoTokenProvider implements LLMProvider {
+      async complete(_request: any): Promise<any> {
+        return { text: 'Summary' };
+      }
+    }
+    
+    const provider = new NoTokenProvider();
+    const summarizer = new LengthBasedSummarizer(provider);
+    
+    const result = await summarizer.summarize('content', AGENT_ROLES.ARCHITECT, config, 'sys', 'sum');
+
+    expect(result.metadata.tokensUsed).toBeUndefined();
+  });
+});
+

package/tests/debate-config-custom.json

@@ -0,0 +1,38 @@
+{
+  "agents": [
+    {
+      "id": "agent-architect",
+      "name": "System Architect (Custom)",
+      "role": "architect",
+      "model": "gpt-4",
+      "provider": "openai",
+      "temperature": 0.5,
+      "systemPromptPath": "./prompts/architect.md",
+      "enabled": true
+    },
+    {
+      "id": "agent-performance",
+      "name": "Performance Engineer",
+      "role": "performance",
+      "model": "gpt-4",
+      "provider": "openai",
+      "temperature": 0.5,
+      "enabled": true
+    }
+  ],
+  "judge": {
+    "id": "judge-main",
+    "name": "Technical Judge",
+    "role": "generalist",
+    "model": "gpt-4",
+    "provider": "openai",
+    "temperature": 0.3
+  },
+  "debate": {
+    "rounds": 2,
+    "terminationCondition": { "type": "fixed" },
+    "synthesisMethod": "judge",
+    "includeFullHistory": true,
+    "timeoutPerRound": 300000
+  }
+}