@auto-engineer/component-implementor-react 1.95.0

package/ketchup-plan.md

@@ -0,0 +1,13 @@
+# Ketchup Plan: component-implementor-react
+
+## TODO
+
+## DONE
+
+- [x] Burst 1: Infrastructure — package.json, tsconfig.json, vitest.config.ts (8d0ef1f1)
+- [x] Burst 2: extract-code-block.ts with test (c272077c)
+- [x] Burst 3: generate-test.ts with test (ca284764)
+- [x] Burst 4: generate-component.ts with test (2263623a)
+- [x] Burst 5: generate-story.ts with test (ceaa70df)
+- [x] Burst 6: implement-component command handler with test (150fcb02)
+- [x] Burst 7: index.ts exports + type-check (a54bd956)

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@auto-engineer/component-implementor-react",
+  "type": "module",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "dependencies": {
+    "ai": "^6.0.0",
+    "debug": "^4.4.1",
+    "@auto-engineer/message-bus": "1.95.0",
+    "@auto-engineer/model-factory": "1.95.0"
+  },
+  "devDependencies": {
+    "vitest": "^3.2.1"
+  },
+  "version": "1.95.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc && tsx ../../scripts/fix-esm-imports.ts",
+    "test": "vitest run --reporter=dot",
+    "type-check": "tsc --noEmit",
+    "release": "pnpm publish --no-git-checks"
+  }
+}

package/src/commands/implement-component.test.ts

@@ -0,0 +1,151 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+vi.mock('ai', () => ({
+  generateText: vi.fn(),
+}));
+
+vi.mock('@auto-engineer/model-factory', () => ({
+  createModelFromEnv: vi.fn(() => 'mock-model'),
+}));
+
+vi.mock('node:fs/promises', () => ({
+  readFile: vi.fn(),
+  writeFile: vi.fn(),
+  mkdir: vi.fn(),
+}));
+
+vi.mock('node:fs', () => ({
+  existsSync: vi.fn(),
+}));
+
+import { existsSync } from 'node:fs';
+import { readFile, writeFile } from 'node:fs/promises';
+import { generateText } from 'ai';
+import { commandHandler, handleImplementComponent } from './implement-component';
+
+function makeCommand(overrides: Record<string, unknown> = {}) {
+  return {
+    type: 'ImplementComponent' as const,
+    data: {
+      targetDir: '/project/client',
+      job: {
+        id: 'job_1',
+        dependsOn: [],
+        target: 'ImplementComponent' as const,
+        payload: {
+          componentId: 'my-button',
+          structure: ['renders a button element'],
+          rendering: ['shows spinner when loading'],
+          interaction: ['calls onClick handler'],
+          styling: ['uses primary class'],
+          storybookPath: 'src/components/ui/MyButton.stories.tsx',
+          files: { create: ['src/components/ui/MyButton.tsx'] },
+        },
+      },
+      ...overrides,
+    },
+    requestId: 'req-1',
+    correlationId: 'cor-1',
+  };
+}
+
+describe('implement-component', () => {
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('handleImplementComponent', () => {
+    it('generates 3 files and returns ComponentImplemented on success', async () => {
+      const mockGenerateText = vi.mocked(generateText);
+      mockGenerateText
+        .mockResolvedValueOnce({ text: 'test file code' } as Awaited<ReturnType<typeof generateText>>)
+        .mockResolvedValueOnce({ text: 'component file code' } as Awaited<ReturnType<typeof generateText>>)
+        .mockResolvedValueOnce({ text: 'story file code' } as Awaited<ReturnType<typeof generateText>>);
+
+      vi.mocked(existsSync).mockReturnValue(false);
+      vi.mocked(writeFile).mockResolvedValue(undefined);
+
+      const result = await handleImplementComponent(makeCommand());
+
+      expect(result).toEqual({
+        type: 'ComponentImplemented',
+        data: {
+          name: 'MyButton',
+          componentPath: '/project/client/src/components/ui/MyButton.tsx',
+          testPath: '/project/client/src/components/ui/MyButton.test.tsx',
+          storyPath: '/project/client/src/components/ui/MyButton.stories.tsx',
+          filesCreated: [
+            '/project/client/src/components/ui/MyButton.test.tsx',
+            '/project/client/src/components/ui/MyButton.tsx',
+            '/project/client/src/components/ui/MyButton.stories.tsx',
+          ],
+        },
+        timestamp: expect.any(Date),
+        requestId: 'req-1',
+        correlationId: 'cor-1',
+      });
+
+      expect(writeFile).toHaveBeenCalledTimes(3);
+    });
+
+    it('reads existing component when modifying', async () => {
+      const mockGenerateText = vi.mocked(generateText);
+      mockGenerateText
+        .mockResolvedValueOnce({ text: 'test code' } as Awaited<ReturnType<typeof generateText>>)
+        .mockResolvedValueOnce({ text: 'component code' } as Awaited<ReturnType<typeof generateText>>)
+        .mockResolvedValueOnce({ text: 'story code' } as Awaited<ReturnType<typeof generateText>>);
+
+      vi.mocked(existsSync).mockReturnValue(true);
+      vi.mocked(readFile).mockResolvedValue('existing component code' as never);
+      vi.mocked(writeFile).mockResolvedValue(undefined);
+
+      const command = makeCommand({
+        job: {
+          id: 'job_2',
+          dependsOn: [],
+          target: 'ImplementComponent',
+          payload: {
+            componentId: 'my-button',
+            structure: ['renders a button'],
+            rendering: [],
+            interaction: [],
+            styling: [],
+            storybookPath: 'src/components/ui/MyButton.stories.tsx',
+            files: { modify: ['src/components/ui/MyButton.tsx'] },
+          },
+        },
+      });
+
+      await handleImplementComponent(command);
+
+      expect(readFile).toHaveBeenCalledWith('/project/client/src/components/ui/MyButton.tsx', 'utf-8');
+    });
+
+    it('returns ComponentImplementationFailed on error', async () => {
+      const mockGenerateText = vi.mocked(generateText);
+      mockGenerateText.mockRejectedValue(new Error('AI service down'));
+
+      vi.mocked(existsSync).mockReturnValue(false);
+
+      const result = await handleImplementComponent(makeCommand());
+
+      expect(result).toEqual({
+        type: 'ComponentImplementationFailed',
+        data: {
+          error: 'AI service down',
+          name: 'MyButton',
+        },
+        timestamp: expect.any(Date),
+        requestId: 'req-1',
+        correlationId: 'cor-1',
+      });
+    });
+  });
+
+  describe('commandHandler', () => {
+    it('has correct metadata', () => {
+      expect(commandHandler.name).toBe('ImplementComponent');
+      expect(commandHandler.alias).toBe('implement:component');
+    });
+  });
+});

package/src/commands/implement-component.ts

@@ -0,0 +1,190 @@
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { type Command, defineCommandHandler, type Event } from '@auto-engineer/message-bus';
+import createDebug from 'debug';
+import { generateComponentFile } from '../generate-component';
+import { generateStoryFile } from '../generate-story';
+import { generateTestFile } from '../generate-test';
+
+const debug = createDebug('auto:component-implementor-react:command');
+
+type ComponentJobPayload = {
+  componentId: string;
+  structure: string[];
+  rendering: string[];
+  interaction: string[];
+  styling: string[];
+  storybookPath: string;
+  files: { create?: string[]; modify?: string[] };
+};
+
+type ComponentJob = {
+  id: string;
+  dependsOn: string[];
+  target: 'ImplementComponent';
+  payload: ComponentJobPayload;
+};
+
+export type ImplementComponentCommand = Command<
+  'ImplementComponent',
+  {
+    targetDir: string;
+    job: ComponentJob;
+  }
+>;
+
+export type ComponentImplementedEvent = Event<
+  'ComponentImplemented',
+  {
+    name: string;
+    componentPath: string;
+    testPath: string;
+    storyPath: string;
+    filesCreated: string[];
+  }
+>;
+
+export type ComponentImplementationFailedEvent = Event<
+  'ComponentImplementationFailed',
+  {
+    error: string;
+    name: string;
+  }
+>;
+
+export type ImplementComponentEvents = ComponentImplementedEvent | ComponentImplementationFailedEvent;
+
+function pascalCase(id: string): string {
+  return id
+    .split('-')
+    .map((s) => s.charAt(0).toUpperCase() + s.slice(1))
+    .join('');
+}
+
+function deriveFilePaths(
+  targetDir: string,
+  payload: ComponentJobPayload,
+): { componentPath: string; testPath: string; storyPath: string; componentName: string } {
+  const rawPath = payload.files.modify?.[0] ?? payload.files.create?.[0] ?? '';
+  const componentPath = path.resolve(targetDir, rawPath);
+  const dir = path.dirname(componentPath);
+  const componentName = pascalCase(payload.componentId);
+  const testPath = path.join(dir, `${componentName}.test.tsx`);
+  const storyPath = path.resolve(targetDir, payload.storybookPath);
+
+  return { componentPath, testPath, storyPath, componentName };
+}
+
+export async function handleImplementComponent(
+  command: ImplementComponentCommand,
+): Promise<ComponentImplementedEvent | ComponentImplementationFailedEvent> {
+  const { targetDir, job } = command.data;
+  const { payload } = job;
+  const { componentPath, testPath, storyPath, componentName } = deriveFilePaths(targetDir, payload);
+  const isModify = (payload.files.modify?.length ?? 0) > 0;
+
+  debug('Implementing component: %s', componentName);
+
+  try {
+    let existingComponent: string | undefined;
+    if (isModify && existsSync(componentPath)) {
+      existingComponent = await readFile(componentPath, 'utf-8');
+      debug('Read existing component: %d chars', existingComponent.length);
+    }
+
+    const specDeltas = {
+      structure: payload.structure,
+      rendering: payload.rendering,
+      interaction: payload.interaction,
+      styling: payload.styling,
+    };
+
+    debug('Generating test file...');
+    const testCode = await generateTestFile({
+      componentName,
+      specDeltas,
+      existingComponent,
+    });
+
+    debug('Generating component file...');
+    const componentCode = await generateComponentFile({
+      componentName,
+      specDeltas,
+      testCode,
+      existingComponent,
+    });
+
+    debug('Generating story file...');
+    const storyCode = await generateStoryFile({
+      componentName,
+      specDeltas,
+      componentCode,
+    });
+
+    await mkdir(path.dirname(testPath), { recursive: true });
+    await Promise.all([
+      writeFile(testPath, testCode, 'utf-8'),
+      writeFile(componentPath, componentCode, 'utf-8'),
+      writeFile(storyPath, storyCode, 'utf-8'),
+    ]);
+
+    debug('Wrote 3 files for %s', componentName);
+
+    return {
+      type: 'ComponentImplemented',
+      data: {
+        name: componentName,
+        componentPath,
+        testPath,
+        storyPath,
+        filesCreated: [testPath, componentPath, storyPath],
+      },
+      timestamp: new Date(),
+      requestId: command.requestId,
+      correlationId: command.correlationId,
+    };
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    debug('Implementation failed: %s', errorMessage);
+
+    return {
+      type: 'ComponentImplementationFailed',
+      data: { error: errorMessage, name: componentName },
+      timestamp: new Date(),
+      requestId: command.requestId,
+      correlationId: command.correlationId,
+    };
+  }
+}
+
+export const commandHandler = defineCommandHandler({
+  name: 'ImplementComponent',
+  displayName: 'Implement Component',
+  alias: 'implement:component',
+  description: 'Generate a React component with test and Storybook story from structured spec deltas',
+  category: 'implement',
+  icon: 'component',
+  fields: {
+    targetDir: {
+      description: 'The client project root directory',
+      required: true,
+    },
+    job: {
+      description: 'ComponentJob with structured spec delta payload',
+      required: true,
+    },
+  },
+  examples: [
+    '$ auto implement:component --target-dir=./client --job=\'{"id":"job_1","dependsOn":[],"target":"ImplementComponent","payload":{...}}\'',
+  ],
+  events: [
+    { name: 'ComponentImplemented', displayName: 'Component Implemented' },
+    { name: 'ComponentImplementationFailed', displayName: 'Component Implementation Failed' },
+  ],
+  handle: async (command: Command): Promise<ImplementComponentEvents> => {
+    return handleImplementComponent(command as ImplementComponentCommand);
+  },
+});
+
+export default commandHandler;

package/src/extract-code-block.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest';
+import { extractCodeBlock } from './extract-code-block';
+
+describe('extractCodeBlock', () => {
+  it('returns plain text unchanged', () => {
+    expect(extractCodeBlock('const x = 1;')).toBe('const x = 1;');
+  });
+
+  it('strips tsx fenced code block', () => {
+    const input = '```tsx\nconst x = 1;\n```';
+    expect(extractCodeBlock(input)).toBe('const x = 1;');
+  });
+
+  it('strips typescript fenced code block', () => {
+    const input = '```typescript\nconst x = 1;\n```';
+    expect(extractCodeBlock(input)).toBe('const x = 1;');
+  });
+
+  it('strips ts fenced code block', () => {
+    const input = '```ts\nconst x = 1;\n```';
+    expect(extractCodeBlock(input)).toBe('const x = 1;');
+  });
+
+  it('strips bare fenced code block', () => {
+    const input = '```\nconst x = 1;\n```';
+    expect(extractCodeBlock(input)).toBe('const x = 1;');
+  });
+
+  it('trims surrounding whitespace', () => {
+    const input = '  ```tsx\n  const x = 1;\n  ```  ';
+    expect(extractCodeBlock(input)).toBe('const x = 1;');
+  });
+});

package/src/extract-code-block.ts

@@ -0,0 +1,6 @@
+export function extractCodeBlock(text: string): string {
+  return text
+    .replace(/```(?:tsx?|typescript)?/g, '')
+    .replace(/```/g, '')
+    .trim();
+}

package/src/generate-component.test.ts

@@ -0,0 +1,93 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { generateComponentFile } from './generate-component';
+
+vi.mock('ai', () => ({
+  generateText: vi.fn(),
+}));
+
+vi.mock('@auto-engineer/model-factory', () => ({
+  createModelFromEnv: vi.fn(() => 'mock-model'),
+}));
+
+import { generateText } from 'ai';
+
+const specDeltas = {
+  structure: ['renders a Button element'],
+  rendering: ['shows loading spinner when loading=true'],
+  interaction: ['calls onClick when clicked'],
+  styling: ['applies primary variant by default'],
+};
+
+describe('generateComponentFile', () => {
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('returns generated component code from AI', async () => {
+    const mockGenerateText = vi.mocked(generateText);
+    mockGenerateText.mockResolvedValue({
+      text: '```tsx\nexport function Button() { return <button />; }\n```',
+    } as Awaited<ReturnType<typeof generateText>>);
+
+    const result = await generateComponentFile({
+      componentName: 'Button',
+      specDeltas,
+      testCode: 'import { render } from "@testing-library/react";',
+    });
+
+    expect(result).toBe('export function Button() { return <button />; }');
+  });
+
+  it('includes spec deltas and test code in the prompt', async () => {
+    const mockGenerateText = vi.mocked(generateText);
+    mockGenerateText.mockResolvedValue({
+      text: 'component code',
+    } as Awaited<ReturnType<typeof generateText>>);
+
+    await generateComponentFile({
+      componentName: 'Button',
+      specDeltas,
+      testCode: 'describe("Button", () => {})',
+    });
+
+    const prompt = mockGenerateText.mock.calls[0][0].prompt as string;
+    expect(prompt).toContain('## Structure');
+    expect(prompt).toContain('renders a Button element');
+    expect(prompt).toContain('## Test File');
+    expect(prompt).toContain('describe("Button", () => {})');
+  });
+
+  it('includes existing component code when provided', async () => {
+    const mockGenerateText = vi.mocked(generateText);
+    mockGenerateText.mockResolvedValue({
+      text: 'updated code',
+    } as Awaited<ReturnType<typeof generateText>>);
+
+    await generateComponentFile({
+      componentName: 'Button',
+      specDeltas,
+      testCode: 'test code',
+      existingComponent: 'export function Button() {}',
+    });
+
+    const prompt = mockGenerateText.mock.calls[0][0].prompt as string;
+    expect(prompt).toContain('## Existing Component');
+    expect(prompt).toContain('export function Button() {}');
+  });
+
+  it('uses system prompt referencing React component generation', async () => {
+    const mockGenerateText = vi.mocked(generateText);
+    mockGenerateText.mockResolvedValue({
+      text: 'code',
+    } as Awaited<ReturnType<typeof generateText>>);
+
+    await generateComponentFile({
+      componentName: 'Button',
+      specDeltas,
+      testCode: 'test',
+    });
+
+    const system = mockGenerateText.mock.calls[0][0].system as string;
+    expect(system).toContain('React');
+  });
+});

package/src/generate-component.ts

@@ -0,0 +1,57 @@
+import { createModelFromEnv } from '@auto-engineer/model-factory';
+import { generateText } from 'ai';
+import { extractCodeBlock } from './extract-code-block';
+
+type SpecDeltas = {
+  structure: string[];
+  rendering: string[];
+  interaction: string[];
+  styling: string[];
+};
+
+type GenerateComponentInput = {
+  componentName: string;
+  specDeltas: SpecDeltas;
+  testCode: string;
+  existingComponent?: string;
+};
+
+function buildSpecSection(heading: string, items: string[]): string {
+  if (items.length === 0) return '';
+  return `## ${heading}\n${items.map((i) => `- ${i}`).join('\n')}`;
+}
+
+function buildPrompt(input: GenerateComponentInput): string {
+  const sections = [
+    buildSpecSection('Structure', input.specDeltas.structure),
+    buildSpecSection('Rendering', input.specDeltas.rendering),
+    buildSpecSection('Interaction', input.specDeltas.interaction),
+    buildSpecSection('Styling', input.specDeltas.styling),
+  ]
+    .filter(Boolean)
+    .join('\n\n');
+
+  const existingContext = input.existingComponent
+    ? `\n\n## Existing Component\n\`\`\`tsx\n${input.existingComponent}\n\`\`\``
+    : '';
+
+  return `Component: ${input.componentName}\n\n${sections}${existingContext}\n\n## Test File\n\`\`\`tsx\n${input.testCode}\n\`\`\``;
+}
+
+const SYSTEM_PROMPT = `You are a React component expert. Write a React component (.tsx) that satisfies the spec and passes the provided test.
+
+Rules:
+- Use functional components with TypeScript
+- Export the component as a named export
+- Use Tailwind CSS classes for styling
+- The component must pass the provided test
+- Return ONLY the component file code, no commentary`;
+
+export async function generateComponentFile(input: GenerateComponentInput): Promise<string> {
+  const { text } = await generateText({
+    model: createModelFromEnv(),
+    system: SYSTEM_PROMPT,
+    prompt: buildPrompt(input),
+  });
+  return extractCodeBlock(text);
+}

package/src/generate-story.test.ts

@@ -0,0 +1,75 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { generateStoryFile } from './generate-story';
+
+vi.mock('ai', () => ({
+  generateText: vi.fn(),
+}));
+
+vi.mock('@auto-engineer/model-factory', () => ({
+  createModelFromEnv: vi.fn(() => 'mock-model'),
+}));
+
+import { generateText } from 'ai';
+
+const specDeltas = {
+  structure: ['renders a Button element'],
+  rendering: ['shows loading spinner when loading=true'],
+  interaction: ['calls onClick when clicked'],
+  styling: ['applies primary variant by default'],
+};
+
+describe('generateStoryFile', () => {
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('returns generated story code from AI', async () => {
+    const mockGenerateText = vi.mocked(generateText);
+    mockGenerateText.mockResolvedValue({
+      text: '```tsx\nimport type { Meta } from "@storybook/react";\n```',
+    } as Awaited<ReturnType<typeof generateText>>);
+
+    const result = await generateStoryFile({
+      componentName: 'Button',
+      specDeltas,
+      componentCode: 'export function Button() { return <button />; }',
+    });
+
+    expect(result).toBe('import type { Meta } from "@storybook/react";');
+  });
+
+  it('includes spec deltas and component code in the prompt', async () => {
+    const mockGenerateText = vi.mocked(generateText);
+    mockGenerateText.mockResolvedValue({
+      text: 'story code',
+    } as Awaited<ReturnType<typeof generateText>>);
+
+    await generateStoryFile({
+      componentName: 'Button',
+      specDeltas,
+      componentCode: 'export function Button() {}',
+    });
+
+    const prompt = mockGenerateText.mock.calls[0][0].prompt as string;
+    expect(prompt).toContain('## Structure');
+    expect(prompt).toContain('renders a Button element');
+    expect(prompt).toContain('## Component Code');
+    expect(prompt).toContain('export function Button() {}');
+  });
+
+  it('uses system prompt referencing Storybook', async () => {
+    const mockGenerateText = vi.mocked(generateText);
+    mockGenerateText.mockResolvedValue({
+      text: 'code',
+    } as Awaited<ReturnType<typeof generateText>>);
+
+    await generateStoryFile({
+      componentName: 'Button',
+      specDeltas,
+      componentCode: 'code',
+    });
+
+    const system = mockGenerateText.mock.calls[0][0].system as string;
+    expect(system).toContain('Storybook');
+  });
+});