@bhargavvc/sdd-cc 1.35.0 → 1.42.3

package/sdk/src/phase-prompt.test.ts

@@ -0,0 +1,535 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { PromptFactory, extractBlock, extractSteps, PHASE_WORKFLOW_MAP } from './phase-prompt.js';
+import { PhaseType } from './types.js';
+import type { ContextFiles, ParsedPlan, PlanFrontmatter } from './types.js';
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+async function createTempDir(): Promise<string> {
+  return mkdtemp(join(tmpdir(), 'sdd-prompt-'));
+}
+
+function makeWorkflowContent(purpose: string, steps: string[]): string {
+  const stepBlocks = steps
+    .map((s, i) => `<step name="step_${i + 1}">\n${s}\n</step>`)
+    .join('\n\n');
+  return `<purpose>\n${purpose}\n</purpose>\n\n<process>\n${stepBlocks}\n</process>`;
+}
+
+function makeAgentDef(name: string, tools: string, role: string): string {
+  return `---\nname: ${name}\ntools: ${tools}\n---\n\n<role>\n${role}\n</role>`;
+}
+
+function makeParsedPlan(overrides?: Partial<ParsedPlan>): ParsedPlan {
+  return {
+    frontmatter: {
+      phase: 'execute',
+      plan: 'test-plan',
+      type: 'feature',
+      wave: 1,
+      depends_on: [],
+      files_modified: [],
+      autonomous: true,
+      requirements: [],
+      must_haves: { truths: [], artifacts: [], key_links: [] },
+    } as PlanFrontmatter,
+    objective: 'Test objective',
+    execution_context: [],
+    context_refs: [],
+    tasks: [],
+    raw: '',
+    ...overrides,
+  };
+}
+
+// ─── extractBlock tests ──────────────────────────────────────────────────────
+
+describe('extractBlock', () => {
+  it('extracts content from a simple block', () => {
+    const content = '<purpose>\nDo the thing.\n</purpose>';
+    expect(extractBlock(content, 'purpose')).toBe('Do the thing.');
+  });
+
+  it('extracts content from block with attributes', () => {
+    const content = '<step name="init" priority="first">\nLoad context.\n</step>';
+    expect(extractBlock(content, 'step')).toBe('Load context.');
+  });
+
+  it('returns empty string for missing block', () => {
+    const content = '<purpose>Something</purpose>';
+    expect(extractBlock(content, 'role')).toBe('');
+  });
+
+  it('extracts multiline content', () => {
+    const content = '<role>\nLine 1\nLine 2\nLine 3\n</role>';
+    expect(extractBlock(content, 'role')).toBe('Line 1\nLine 2\nLine 3');
+  });
+});
+
+describe('extractSteps', () => {
+  it('extracts multiple steps from process content', () => {
+    const process = `
+<step name="init">Initialize</step>
+<step name="execute">Run tasks</step>
+<step name="verify">Check results</step>`;
+
+    const steps = extractSteps(process);
+    expect(steps).toHaveLength(3);
+    expect(steps[0]).toEqual({ name: 'init', content: 'Initialize' });
+    expect(steps[1]).toEqual({ name: 'execute', content: 'Run tasks' });
+    expect(steps[2]).toEqual({ name: 'verify', content: 'Check results' });
+  });
+
+  it('returns empty array for no steps', () => {
+    expect(extractSteps('no steps here')).toEqual([]);
+  });
+
+  it('handles steps with priority attributes', () => {
+    const process = '<step name="init" priority="first">\nDo first.\n</step>';
+    const steps = extractSteps(process);
+    expect(steps).toHaveLength(1);
+    expect(steps[0].name).toBe('init');
+    expect(steps[0].content).toBe('Do first.');
+  });
+});
+
+// ─── PromptFactory tests ─────────────────────────────────────────────────────
+
+describe('PromptFactory', () => {
+  let tempDir: string;
+  let workflowsDir: string;
+  let agentsDir: string;
+
+  beforeEach(async () => {
+    tempDir = await createTempDir();
+    workflowsDir = join(tempDir, 'workflows');
+    agentsDir = join(tempDir, 'agents');
+    await mkdir(workflowsDir, { recursive: true });
+    await mkdir(agentsDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(tempDir, { recursive: true, force: true });
+  });
+
+  function makeFactory(): PromptFactory {
+    // sdkPromptsDir points to a non-existent temp subdir so real sdk/prompts/ files
+    // don't interfere — tests control exactly which files exist on disk.
+    return new PromptFactory({
+      sddInstallDir: tempDir,
+      agentsDir,
+      sdkPromptsDir: join(tempDir, 'sdk-prompts-does-not-exist'),
+    });
+  }
+
+  describe('buildPrompt', () => {
+    it('assembles research prompt with role + purpose + process + context', async () => {
+      await writeFile(
+        join(workflowsDir, 'research-phase.md'),
+        makeWorkflowContent('Research the phase.', ['Gather info', 'Analyze findings']),
+      );
+      await writeFile(
+        join(agentsDir, 'sdd-phase-researcher.md'),
+        makeAgentDef('sdd-phase-researcher', 'Read, Grep, Bash', 'You are a researcher.'),
+      );
+
+      const factory = makeFactory();
+      const contextFiles: ContextFiles = {
+        state: '# State\nproject: test',
+        roadmap: '# Roadmap\nphases listed',
+      };
+
+      const prompt = await factory.buildPrompt(PhaseType.Research, null, contextFiles);
+
+      expect(prompt).toContain('## Agent Instructions');
+      expect(prompt).toContain('You are a researcher.');
+      expect(prompt).toContain('## Purpose');
+      expect(prompt).toContain('Research the phase.');
+      expect(prompt).toContain('## Process');
+      expect(prompt).toContain('Gather info');
+      expect(prompt).toContain('## Context');
+      expect(prompt).toContain('# State');
+      expect(prompt).toContain('# Roadmap');
+
+      // Cache-friendly ordering (#1614): stable prefix before variable context
+      const agentIdx = prompt.indexOf('## Agent Instructions');
+      const contextIdx = prompt.indexOf('## Context');
+      expect(agentIdx).toBeLessThan(contextIdx);
+    });
+
+    it('assembles plan prompt with all context files', async () => {
+      await writeFile(
+        join(workflowsDir, 'plan-phase.md'),
+        makeWorkflowContent('Plan the implementation.', ['Break down tasks']),
+      );
+      await writeFile(
+        join(agentsDir, 'sdd-planner.md'),
+        makeAgentDef('sdd-planner', 'Read, Write, Bash', 'You are a planner.'),
+      );
+
+      const factory = makeFactory();
+      const contextFiles: ContextFiles = {
+        state: '# State',
+        roadmap: '# Roadmap',
+        context: '# Context',
+        research: '# Research',
+        requirements: '# Requirements',
+      };
+
+      const prompt = await factory.buildPrompt(PhaseType.Plan, null, contextFiles);
+
+      expect(prompt).toContain('You are a planner.');
+      expect(prompt).toContain('Plan the implementation.');
+      expect(prompt).toContain('# State');
+      expect(prompt).toContain('# Research');
+      expect(prompt).toContain('# Requirements');
+      expect(prompt).toContain('You are a planner.');
+    });
+
+    it('delegates execute phase with plan to buildExecutorPrompt', async () => {
+      await writeFile(
+        join(agentsDir, 'sdd-executor.md'),
+        makeAgentDef('sdd-executor', 'Read, Write, Edit, Bash', 'You are an executor.'),
+      );
+
+      const factory = makeFactory();
+      const plan = makeParsedPlan({ objective: 'Build the auth system' });
+      const contextFiles: ContextFiles = { state: '# State' };
+
+      const prompt = await factory.buildPrompt(PhaseType.Execute, plan, contextFiles);
+
+      // buildExecutorPrompt produces structured output with ## Objective
+      expect(prompt).toContain('## Objective');
+      expect(prompt).toContain('Build the auth system');
+      expect(prompt).toContain('## Role');
+      expect(prompt).toContain('You are an executor.');
+    });
+
+    it('handles execute phase without plan (non-delegation path)', async () => {
+      await writeFile(
+        join(workflowsDir, 'execute-plan.md'),
+        makeWorkflowContent('Execute the plan.', ['Run tasks']),
+      );
+      await writeFile(
+        join(agentsDir, 'sdd-executor.md'),
+        makeAgentDef('sdd-executor', 'Read, Write, Edit, Bash', 'You are an executor.'),
+      );
+
+      const factory = makeFactory();
+      const contextFiles: ContextFiles = { state: '# State' };
+
+      const prompt = await factory.buildPrompt(PhaseType.Execute, null, contextFiles);
+
+      // Falls through to general assembly path
+      expect(prompt).toContain('## Agent Instructions');
+      expect(prompt).toContain('You are an executor.');
+      expect(prompt).toContain('## Purpose');
+      expect(prompt).toContain('Execute the plan.');
+    });
+
+    it('assembles verify prompt with phase instructions', async () => {
+      await writeFile(
+        join(workflowsDir, 'verify-phase.md'),
+        makeWorkflowContent('Verify phase goals.', ['Check artifacts', 'Run tests']),
+      );
+      await writeFile(
+        join(agentsDir, 'sdd-verifier.md'),
+        makeAgentDef('sdd-verifier', 'Read, Bash, Grep', 'You are a verifier.'),
+      );
+
+      const factory = makeFactory();
+      const contextFiles: ContextFiles = {
+        state: '# State',
+        roadmap: '# Roadmap',
+        requirements: '# Requirements',
+      };
+
+      const prompt = await factory.buildPrompt(PhaseType.Verify, null, contextFiles);
+
+      expect(prompt).toContain('You are a verifier.');
+      expect(prompt).toContain('Verify phase goals.');
+      expect(prompt).toContain('You are a verifier.');
+    });
+
+    it('assembles discuss prompt without agent role (no dedicated agent)', async () => {
+      await writeFile(
+        join(workflowsDir, 'discuss-phase.md'),
+        makeWorkflowContent('Discuss implementation decisions.', ['Identify areas']),
+      );
+
+      const factory = makeFactory();
+      const contextFiles: ContextFiles = { state: '# State' };
+
+      const prompt = await factory.buildPrompt(PhaseType.Discuss, null, contextFiles);
+
+      // Discuss has no agent, so no Agent Instructions section
+      expect(prompt).not.toContain('## Agent Instructions');
+      expect(prompt).toContain('## Purpose');
+      expect(prompt).toContain('Discuss implementation decisions.');
+    });
+
+    it('handles missing workflow file gracefully', async () => {
+      // No workflow files on disk
+      await writeFile(
+        join(agentsDir, 'sdd-phase-researcher.md'),
+        makeAgentDef('sdd-phase-researcher', 'Read, Bash', 'You are a researcher.'),
+      );
+
+      const factory = makeFactory();
+      const contextFiles: ContextFiles = { state: '# State' };
+
+      const prompt = await factory.buildPrompt(PhaseType.Research, null, contextFiles);
+
+      // Should still produce a prompt with agent instructions and context
+      expect(prompt).toContain('## Agent Instructions');
+      expect(prompt).toContain('## Context');
+      expect(prompt).not.toContain('## Purpose');
+    });
+
+    it('handles missing agent def gracefully', async () => {
+      await writeFile(
+        join(workflowsDir, 'research-phase.md'),
+        makeWorkflowContent('Research the phase.', ['Gather info']),
+      );
+      // No agent file on disk
+
+      const factory = makeFactory();
+      const contextFiles: ContextFiles = { state: '# State' };
+
+      const prompt = await factory.buildPrompt(PhaseType.Research, null, contextFiles);
+
+      expect(prompt).not.toContain('## Agent Instructions');
+      expect(prompt).toContain('## Purpose');
+      expect(prompt).toContain('Research the phase.');
+    });
+
+    it('omits empty context section when no files provided', async () => {
+      await writeFile(
+        join(workflowsDir, 'discuss-phase.md'),
+        makeWorkflowContent('Discuss things.', ['Talk']),
+      );
+
+      const factory = makeFactory();
+      const contextFiles: ContextFiles = {};
+
+      const prompt = await factory.buildPrompt(PhaseType.Discuss, null, contextFiles);
+
+      expect(prompt).not.toContain('## Context');
+    });
+  });
+
+  describe('loadWorkflowFile', () => {
+    it('loads existing workflow file', async () => {
+      await writeFile(
+        join(workflowsDir, 'research-phase.md'),
+        'workflow content',
+      );
+
+      const factory = makeFactory();
+      const content = await factory.loadWorkflowFile(PhaseType.Research);
+      expect(content).toBe('workflow content');
+    });
+
+    it('returns undefined for missing workflow file', async () => {
+      const factory = makeFactory();
+      const content = await factory.loadWorkflowFile(PhaseType.Research);
+      expect(content).toBeUndefined();
+    });
+  });
+
+  describe('loadAgentDef', () => {
+    it('loads agent def from agents dir', async () => {
+      await writeFile(
+        join(agentsDir, 'sdd-executor.md'),
+        'agent content',
+      );
+
+      const factory = makeFactory();
+      const content = await factory.loadAgentDef(PhaseType.Execute);
+      expect(content).toBe('agent content');
+    });
+
+    it('returns undefined for phases with no agent (discuss)', async () => {
+      const factory = makeFactory();
+      const content = await factory.loadAgentDef(PhaseType.Discuss);
+      expect(content).toBeUndefined();
+    });
+
+    it('falls back to project agents dir', async () => {
+      const projectAgentsDir = join(tempDir, 'project-agents');
+      await mkdir(projectAgentsDir, { recursive: true });
+      await writeFile(
+        join(projectAgentsDir, 'sdd-executor.md'),
+        'project agent content',
+      );
+
+      const factory = new PromptFactory({
+        sddInstallDir: tempDir,
+        agentsDir,
+        projectAgentsDir,
+        sdkPromptsDir: join(tempDir, 'sdk-prompts-does-not-exist'),
+      });
+
+      const content = await factory.loadAgentDef(PhaseType.Execute);
+      expect(content).toBe('project agent content');
+    });
+
+    it('prefers user agents dir over project agents dir', async () => {
+      const projectAgentsDir = join(tempDir, 'project-agents');
+      await mkdir(projectAgentsDir, { recursive: true });
+      await writeFile(join(agentsDir, 'sdd-executor.md'), 'user agent');
+      await writeFile(join(projectAgentsDir, 'sdd-executor.md'), 'project agent');
+
+      const factory = new PromptFactory({
+        sddInstallDir: tempDir,
+        agentsDir,
+        projectAgentsDir,
+        sdkPromptsDir: join(tempDir, 'sdk-prompts-does-not-exist'),
+      });
+
+      const content = await factory.loadAgentDef(PhaseType.Execute);
+      expect(content).toBe('user agent');
+    });
+  });
+
+  // ─── Headless prompt loading ─────────────────────────────────────────────
+
+  describe('headless prompt loading', () => {
+    it('loadWorkflowFile prefers installed SDD over sdkPromptsDir', async () => {
+      const sdkDir = join(tempDir, 'sdk-prompts');
+      await mkdir(join(sdkDir, 'workflows'), { recursive: true });
+
+      // Write both: installed SDD and SDK bundled version
+      await writeFile(join(workflowsDir, 'research-phase.md'), 'SDD-1 original');
+      await writeFile(join(sdkDir, 'workflows', 'research-phase.md'), 'SDK bundled version');
+
+      const factory = new PromptFactory({
+        sddInstallDir: tempDir,
+        agentsDir,
+        sdkPromptsDir: sdkDir,
+      });
+
+      const content = await factory.loadWorkflowFile(PhaseType.Research);
+      expect(content).toBe('SDD-1 original');
+    });
+
+    it('loadWorkflowFile falls back to SDD-1 when sdkPromptsDir file missing', async () => {
+      const sdkDir = join(tempDir, 'sdk-prompts');
+      await mkdir(join(sdkDir, 'workflows'), { recursive: true });
+
+      // Only SDD-1 original exists, no SDK version
+      await writeFile(join(workflowsDir, 'research-phase.md'), 'SDD-1 original');
+
+      const factory = new PromptFactory({
+        sddInstallDir: tempDir,
+        agentsDir,
+        sdkPromptsDir: sdkDir,
+      });
+
+      const content = await factory.loadWorkflowFile(PhaseType.Research);
+      expect(content).toBe('SDD-1 original');
+    });
+
+    it('loadAgentDef prefers installed agents over sdkPromptsDir', async () => {
+      const sdkDir = join(tempDir, 'sdk-prompts');
+      await mkdir(join(sdkDir, 'agents'), { recursive: true });
+
+      // Write both: installed agent and SDK bundled agent
+      await writeFile(join(agentsDir, 'sdd-executor.md'), 'user agent');
+      await writeFile(join(sdkDir, 'agents', 'sdd-executor.md'), 'SDK bundled agent');
+
+      const factory = new PromptFactory({
+        sddInstallDir: tempDir,
+        agentsDir,
+        sdkPromptsDir: sdkDir,
+      });
+
+      const content = await factory.loadAgentDef(PhaseType.Execute);
+      expect(content).toBe('user agent');
+    });
+
+    it('loadAgentDef falls back to user agents when sdkPromptsDir file missing', async () => {
+      const sdkDir = join(tempDir, 'sdk-prompts');
+      await mkdir(join(sdkDir, 'agents'), { recursive: true });
+
+      // Only user agent exists, no SDK version
+      await writeFile(join(agentsDir, 'sdd-executor.md'), 'user agent');
+
+      const factory = new PromptFactory({
+        sddInstallDir: tempDir,
+        agentsDir,
+        sdkPromptsDir: sdkDir,
+      });
+
+      const content = await factory.loadAgentDef(PhaseType.Execute);
+      expect(content).toBe('user agent');
+    });
+
+    it('buildPrompt sanitizes interactive patterns from output', async () => {
+      // Use separate lines so non-interactive content survives stripping
+      await writeFile(
+        join(workflowsDir, 'research-phase.md'),
+        makeWorkflowContent('Research the codebase thoroughly.', [
+          'Gather data from the project.\nAskUserQuestion("what?")\nAnalyze findings.',
+          'Run the analysis.\n/sdd:analyze --deep\nDocument results.',
+        ]),
+      );
+      await writeFile(
+        join(agentsDir, 'sdd-phase-researcher.md'),
+        makeAgentDef('sdd-phase-researcher', 'Read, Bash', 'You are a researcher.\nSTOP and wait for user input.\nBe thorough.'),
+      );
+
+      const factory = makeFactory();
+      const contextFiles: ContextFiles = { state: '# State' };
+
+      const prompt = await factory.buildPrompt(PhaseType.Research, null, contextFiles);
+
+      // Interactive patterns should be stripped by sanitizePrompt()
+      expect(prompt).not.toContain('AskUserQuestion');
+      expect(prompt).not.toContain('/sdd:');
+      expect(prompt).not.toMatch(/\bSTOP\s+and\s+wait/);
+
+      // Non-interactive content on separate lines should remain
+      expect(prompt).toContain('You are a researcher.');
+      expect(prompt).toContain('Be thorough.');
+      expect(prompt).toContain('Gather data from the project.');
+      expect(prompt).toContain('Analyze findings.');
+    });
+
+    it('buildPrompt with execute+plan sanitizes output from buildExecutorPrompt', async () => {
+      await writeFile(
+        join(agentsDir, 'sdd-executor.md'),
+        makeAgentDef('sdd-executor', 'Read, Write, Edit, Bash', 'You are an executor.\nSTOP and wait for user.\nExecute thoroughly.'),
+      );
+
+      const factory = makeFactory();
+      const plan = makeParsedPlan({ objective: 'Build the auth system' });
+      const contextFiles: ContextFiles = { state: '# State' };
+
+      const prompt = await factory.buildPrompt(PhaseType.Execute, plan, contextFiles);
+
+      // Objective should remain (no interactive pattern on that line)
+      expect(prompt).toContain('Build the auth system');
+      // The role's STOP directive should be stripped
+      expect(prompt).not.toMatch(/\bSTOP\s+and\s+wait/);
+      // Non-interactive role content should remain
+      expect(prompt).toContain('You are an executor.');
+    });
+  });
+});
+
+describe('PHASE_WORKFLOW_MAP', () => {
+  it('maps all phase types to workflow filenames', () => {
+    for (const phase of Object.values(PhaseType)) {
+      expect(PHASE_WORKFLOW_MAP[phase]).toBeDefined();
+      expect(PHASE_WORKFLOW_MAP[phase]).toMatch(/\.md$/);
+    }
+  });
+
+  it('execute phase maps to execute-plan.md (not execute-phase.md)', () => {
+    expect(PHASE_WORKFLOW_MAP[PhaseType.Execute]).toBe('execute-plan.md');
+  });
+});