Contributing Guide¶

// ✅ Good
class ContainerManager {
  private readonly containers: Map<string, Container> = new Map();

  async startContainer(name: string): Promise<void> {
    const container = this.containers.get(name);
    if (!container) {
      throw new Error(`Container ${name} not found`);
    }

    await container.start();
  }
}

// ❌ Bad
class containerManager {
  private containers: any;

  startContainer(name) {
    return this.containers.get(name).start();
  }
}

// file: src/utils/ContainerUtils.ts

import { Container, ContainerStatus } from '../types';
import { DockerClient } from '../core/DockerClient';
import { Logger } from './Logger';

/**
 * Utilities for managing Docker containers
 */
export class ContainerUtils {
  private static readonly logger = new Logger('ContainerUtils');

  /**
   * Checks if a container is running
   * @param container Container to check
   * @returns true if running
   */
  static isRunning(container: Container): boolean {
    return container.status === ContainerStatus.Running;
  }

  /**
   * Gets containers by status
   * @param client Docker client
   * @param status Desired status
   * @returns List of containers
   */
  static async getByStatus(
    client: DockerClient,
    status: ContainerStatus
  ): Promise<Container[]> {
    try {
      const containers = await client.listContainers();
      return containers.filter(c => c.status === status);
    } catch (error) {
      this.logger.error('Error getting containers by status', error);
      throw error;
    }
  }
}

// ✅ Good - Specific handling
async function stopContainer(name: string): Promise<void> {
  try {
    const container = await findContainer(name);
    if (!container) {
      throw new ContainerNotFoundError(`Container ${name} not found`);
    }

    await container.stop();
    logger.info(`Container ${name} stopped successfully`);
  } catch (error) {
    if (error instanceof ContainerNotFoundError) {
      logger.warn(`Container ${name} not found`);
    } else {
      logger.error(`Error stopping container ${name}`, error);
    }
    throw error;
  }
}

// ❌ Bad - Generic handling
async function stopContainer(name: string): Promise<void> {
  try {
    const container = await findContainer(name);
    await container.stop();
  } catch (error) {
    console.log('Error:', error);
  }
}

/**
 * Manages Docker container operations
 *
 * @example
 * ```typescript
 * const manager = new ContainerManager();
 * await manager.start('nginx');
 * ```
 */
export class ContainerManager {
  /**
   * Starts a container
   *
   * @param name Container name
   * @param options Start options
   * @throws {ContainerNotFoundError} When container doesn't exist
   * @throws {ContainerAlreadyRunningError} When container is already running
   * @returns Promise that resolves when container starts
   */
  async start(name: string, options?: StartOptions): Promise<void> {
    // implementation
  }
}

// file: tests/unit/utils/ContainerUtils.test.ts

import { ContainerUtils } from '../../../src/utils/ContainerUtils';
import { Container, ContainerStatus } from '../../../src/types';
import { createMockContainer } from '../../helpers/mocks';

describe('ContainerUtils', () => {
  describe('isRunning', () => {
    it('should return true for running container', () => {
      // Arrange
      const container = createMockContainer({
        status: ContainerStatus.Running
      });

      // Act
      const result = ContainerUtils.isRunning(container);

      // Assert
      expect(result).toBe(true);
    });

    it('should return false for stopped container', () => {
      // Arrange
      const container = createMockContainer({
        status: ContainerStatus.Exited
      });

      // Act
      const result = ContainerUtils.isRunning(container);

      // Assert
      expect(result).toBe(false);
    });
  });

  describe('getByStatus', () => {
    it('should filter containers by status', async () => {
      // Arrange
      const mockClient = {
        listContainers: jest.fn().mockResolvedValue([
          createMockContainer({ status: ContainerStatus.Running }),
          createMockContainer({ status: ContainerStatus.Exited }),
          createMockContainer({ status: ContainerStatus.Running })
        ])
      };

      // Act
      const result = await ContainerUtils.getByStatus(
        mockClient as any,
        ContainerStatus.Running
      );

      // Assert
      expect(result).toHaveLength(2);
      expect(result.every(c => c.status === ContainerStatus.Running)).toBe(true);
    });
  });
});

// file: tests/integration/docker/ContainerManager.test.ts

import { ContainerManager } from '../../../src/core/ContainerManager';
import { DockerClient } from '../../../src/core/DockerClient';
import { setupTestEnvironment, teardownTestEnvironment } from '../../helpers/setup';

describe('ContainerManager Integration', () => {
  let containerManager: ContainerManager;
  let dockerClient: DockerClient;

  beforeAll(async () => {
    await setupTestEnvironment();
    dockerClient = new DockerClient();
    containerManager = new ContainerManager(dockerClient);
  });

  afterAll(async () => {
    await teardownTestEnvironment();
  });

  beforeEach(async () => {
    // Clean test containers
    await dockerClient.pruneContainers();
  });

  it('should create and start container', async () => {
    // Arrange
    const containerName = 'test-nginx';
    const image = 'nginx:alpine';

    // Act
    await containerManager.create(containerName, image);
    await containerManager.start(containerName);

    // Assert
    const container = await dockerClient.getContainer(containerName);
    expect(container.status).toBe('running');
  });
});

// file: tests/e2e/cli/container-commands.test.ts

import { execSync } from 'child_process';
import { setupTestEnvironment } from '../../helpers/setup';

describe('Container Commands E2E', () => {
  beforeAll(async () => {
    await setupTestEnvironment();
  });

  it('should list containers via CLI', () => {
    // Act
    const output = execSync('docker-pilot list containers', {
      encoding: 'utf8'
    });

    // Assert
    expect(output).toContain('CONTAINER ID');
    expect(output).toContain('IMAGE');
    expect(output).toContain('STATUS');
  });

  it('should start container via CLI', () => {
    // Arrange
    execSync('docker run -d --name test-nginx nginx:alpine');

    // Act
    const output = execSync('docker-pilot start test-nginx', {
      encoding: 'utf8'
    });

    // Assert
    expect(output).toContain('Container test-nginx started');
  });
});

// file: tests/helpers/mocks.ts

import { Container, ContainerStatus } from '../../src/types';

export function createMockContainer(overrides: Partial<Container> = {}): Container {
  return {
    id: 'mock-container-id',
    name: 'mock-container',
    image: 'nginx:latest',
    status: ContainerStatus.Running,
    created: new Date(),
    ports: [],
    volumes: [],
    networks: [],
    ...overrides
  };
}

export function createMockDockerClient() {
  return {
    listContainers: jest.fn(),
    getContainer: jest.fn(),
    createContainer: jest.fn(),
    startContainer: jest.fn(),
    stopContainer: jest.fn(),
    removeContainer: jest.fn()
  };
}