port-arranger 0.0.1

package/dist/cli/core/compose-parser.js

@@ -0,0 +1,184 @@
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import yaml from 'js-yaml';
+const OVERRIDE_FILENAME = '.pa-compose-override.yml';
+/**
+ * 포트 문자열을 파싱하여 호스트/컨테이너 포트 추출
+ * 지원 형식:
+ * - "3000" → 3000:3000
+ * - "3000:8000" → 3000:8000
+ * - "127.0.0.1:3000:8000" → 3000:8000 (IP 무시)
+ * - "3000:8000/tcp" → 3000:8000 (tcp)
+ */
+export function parsePortString(portStr) {
+    if (typeof portStr === 'number') {
+        return { hostPort: portStr, containerPort: portStr };
+    }
+    // 프로토콜 분리
+    let protocol;
+    let portPart = portStr;
+    if (portStr.endsWith('/tcp')) {
+        protocol = 'tcp';
+        portPart = portStr.slice(0, -4);
+    }
+    else if (portStr.endsWith('/udp')) {
+        protocol = 'udp';
+        portPart = portStr.slice(0, -4);
+    }
+    const parts = portPart.split(':');
+    if (parts.length === 1) {
+        // "3000" 형태
+        const port = parseInt(parts[0], 10);
+        return { hostPort: port, containerPort: port, protocol };
+    }
+    if (parts.length === 2) {
+        // "3000:8000" 형태
+        return {
+            hostPort: parseInt(parts[0], 10),
+            containerPort: parseInt(parts[1], 10),
+            protocol,
+        };
+    }
+    if (parts.length === 3) {
+        // "127.0.0.1:3000:8000" 형태 (IP:hostPort:containerPort)
+        return {
+            hostPort: parseInt(parts[1], 10),
+            containerPort: parseInt(parts[2], 10),
+            protocol,
+        };
+    }
+    throw new Error(`Unsupported port format: ${portStr}`);
+}
+/**
+ * 포트 객체(long syntax)를 파싱
+ */
+function parsePortObject(portObj) {
+    return {
+        hostPort: portObj.published ? parseInt(String(portObj.published), 10) : portObj.target,
+        containerPort: portObj.target,
+        protocol: portObj.protocol,
+    };
+}
+/**
+ * docker-compose.yml 파일을 파싱
+ */
+export function parseComposeFile(cwd, filename = 'docker-compose.yml') {
+    const composePath = join(cwd, filename);
+    if (!existsSync(composePath)) {
+        throw new Error(`Docker Compose 파일을 찾을 수 없습니다: ${composePath}`);
+    }
+    const content = readFileSync(composePath, 'utf-8');
+    const config = yaml.load(content);
+    if (!config || typeof config !== 'object') {
+        throw new Error('유효하지 않은 Docker Compose 파일입니다');
+    }
+    return config;
+}
+/**
+ * 서비스 이름 목록 추출 (명령어에서 특정 서비스가 지정된 경우)
+ */
+export function extractServiceNames(command) {
+    // "docker compose up service1 service2" 형태에서 서비스명 추출
+    const match = command.match(/docker\s+compose\s+(up|start|run)\s+(.+)/);
+    if (!match) {
+        return []; // 서비스 지정 없음 = 모든 서비스
+    }
+    const servicesPart = match[2];
+    // 옵션 플래그 제거 (-d, --detach 등)
+    const services = servicesPart
+        .split(/\s+/)
+        .filter(s => !s.startsWith('-') && s.length > 0);
+    return services;
+}
+/**
+ * 특정 서비스의 포트 매핑 추출
+ */
+export function extractServicePorts(config, serviceName) {
+    const service = config.services?.[serviceName];
+    if (!service) {
+        throw new Error(`서비스를 찾을 수 없습니다: ${serviceName}`);
+    }
+    if (!service.ports || service.ports.length === 0) {
+        return [];
+    }
+    return service.ports.map(port => {
+        if (typeof port === 'object' && 'target' in port) {
+            return parsePortObject(port);
+        }
+        return parsePortString(port);
+    });
+}
+/**
+ * 모든 서비스의 포트 매핑 추출
+ */
+export function getAllServicePorts(config, serviceNames) {
+    const services = config.services || {};
+    const targetServices = serviceNames && serviceNames.length > 0
+        ? serviceNames
+        : Object.keys(services);
+    const result = [];
+    for (const serviceName of targetServices) {
+        try {
+            const ports = extractServicePorts(config, serviceName);
+            if (ports.length > 0) {
+                result.push({ serviceName, ports });
+            }
+        }
+        catch {
+            // 서비스가 없으면 무시
+        }
+    }
+    return result;
+}
+/**
+ * Override YAML 파일 생성
+ */
+export function generateOverrideYaml(allocatedPorts) {
+    const services = {};
+    for (const [serviceName, ports] of allocatedPorts) {
+        const portStrings = ports.map(p => {
+            const protocol = p.protocol ? `/${p.protocol}` : '';
+            return `"${p.newHostPort}:${p.containerPort}${protocol}"`;
+        });
+        services[serviceName] = {
+            ports: portStrings,
+        };
+    }
+    // YAML 직접 생성 (js-yaml의 dump는 커스텀 태그를 지원하지 않음)
+    // Docker Compose v2.24+에서 !override는 이전 파일의 배열을 완전히 대체함
+    let yamlContent = 'services:\n';
+    for (const [serviceName, config] of Object.entries(services)) {
+        yamlContent += `  ${serviceName}:\n`;
+        yamlContent += `    ports: !override\n`;
+        for (const port of config.ports) {
+            yamlContent += `      - ${port}\n`;
+        }
+    }
+    return yamlContent;
+}
+/**
+ * Override 파일 작성
+ */
+export function writeOverrideFile(cwd, content) {
+    const overridePath = join(cwd, OVERRIDE_FILENAME);
+    writeFileSync(overridePath, content, 'utf-8');
+    return overridePath;
+}
+/**
+ * docker compose 명령어를 override 파일을 포함하도록 변환
+ */
+export function transformComposeCommand(originalCommand, overridePath) {
+    // "docker compose up" → "docker compose -f docker-compose.yml -f .pa-compose-override.yml up"
+    const match = originalCommand.match(/^(docker\s+compose)\s+(up|start|run)(.*)$/);
+    if (!match) {
+        return originalCommand;
+    }
+    const [, dockerCompose, subcommand, rest] = match;
+    return `${dockerCompose} -f docker-compose.yml -f ${OVERRIDE_FILENAME} ${subcommand}${rest}`;
+}
+/**
+ * Override 파일 경로 반환
+ */
+export function getOverrideFilePath(cwd) {
+    return join(cwd, OVERRIDE_FILENAME);
+}

package/dist/cli/core/compose-parser.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli/core/compose-parser.test.js

@@ -0,0 +1,262 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdirSync, writeFileSync, rmSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { parsePortString, parseComposeFile, extractServiceNames, extractServicePorts, getAllServicePorts, generateOverrideYaml, writeOverrideFile, transformComposeCommand, } from './compose-parser.js';
+describe('compose-parser', () => {
+    describe('parsePortString', () => {
+        it('숫자만 있는 경우 호스트와 컨테이너 포트가 같다', () => {
+            expect(parsePortString('3000')).toEqual({
+                hostPort: 3000,
+                containerPort: 3000,
+            });
+        });
+        it('숫자 타입도 처리한다', () => {
+            expect(parsePortString(8080)).toEqual({
+                hostPort: 8080,
+                containerPort: 8080,
+            });
+        });
+        it('host:container 형태를 파싱한다', () => {
+            expect(parsePortString('3000:8000')).toEqual({
+                hostPort: 3000,
+                containerPort: 8000,
+            });
+        });
+        it('ip:host:container 형태를 파싱한다 (IP 무시)', () => {
+            expect(parsePortString('127.0.0.1:3000:8000')).toEqual({
+                hostPort: 3000,
+                containerPort: 8000,
+            });
+        });
+        it('프로토콜을 파싱한다', () => {
+            expect(parsePortString('3000:8000/tcp')).toEqual({
+                hostPort: 3000,
+                containerPort: 8000,
+                protocol: 'tcp',
+            });
+            expect(parsePortString('5432:5432/udp')).toEqual({
+                hostPort: 5432,
+                containerPort: 5432,
+                protocol: 'udp',
+            });
+        });
+        it('지원하지 않는 형식은 에러를 던진다', () => {
+            expect(() => parsePortString('a:b:c:d')).toThrow('지원하지 않는 포트 형식');
+        });
+    });
+    describe('extractServiceNames', () => {
+        it('서비스 이름을 추출한다', () => {
+            expect(extractServiceNames('docker compose up web')).toEqual(['web']);
+            expect(extractServiceNames('docker compose up web api')).toEqual(['web', 'api']);
+        });
+        it('옵션 플래그를 제외한다', () => {
+            expect(extractServiceNames('docker compose up -d web')).toEqual(['web']);
+            expect(extractServiceNames('docker compose up --detach web api')).toEqual(['web', 'api']);
+        });
+        it('서비스 지정 없으면 빈 배열 반환', () => {
+            expect(extractServiceNames('docker compose up')).toEqual([]);
+            expect(extractServiceNames('docker compose up -d')).toEqual([]);
+        });
+        it('start/run 명령도 인식한다', () => {
+            expect(extractServiceNames('docker compose start web')).toEqual(['web']);
+            expect(extractServiceNames('docker compose run api')).toEqual(['api']);
+        });
+    });
+    describe('transformComposeCommand', () => {
+        it('up 명령어에 override 파일을 추가한다', () => {
+            const result = transformComposeCommand('docker compose up llm', '.pa-compose-override.yml');
+            expect(result).toBe('docker compose -f docker-compose.yml -f .pa-compose-override.yml up llm');
+        });
+        it('start 명령어도 변환한다', () => {
+            const result = transformComposeCommand('docker compose start web api', '.pa-compose-override.yml');
+            expect(result).toBe('docker compose -f docker-compose.yml -f .pa-compose-override.yml start web api');
+        });
+        it('인식되지 않는 명령어는 원본 반환', () => {
+            const result = transformComposeCommand('docker compose logs', '.pa-compose-override.yml');
+            expect(result).toBe('docker compose logs');
+        });
+    });
+    describe('generateOverrideYaml', () => {
+        it('단일 서비스의 override YAML을 생성한다', () => {
+            const allocatedPorts = new Map();
+            allocatedPorts.set('web', [
+                {
+                    hostPort: 3001,
+                    containerPort: 8000,
+                    originalHostPort: 3000,
+                    newHostPort: 3001,
+                },
+            ]);
+            const yaml = generateOverrideYaml(allocatedPorts);
+            expect(yaml).toContain('services:');
+            expect(yaml).toContain('web:');
+            expect(yaml).toContain('ports: !override');
+            expect(yaml).toContain('"3001:8000"');
+        });
+        it('다중 서비스의 override YAML을 생성한다', () => {
+            const allocatedPorts = new Map();
+            allocatedPorts.set('web', [
+                {
+                    hostPort: 3001,
+                    containerPort: 8000,
+                    originalHostPort: 3000,
+                    newHostPort: 3001,
+                },
+            ]);
+            allocatedPorts.set('api', [
+                {
+                    hostPort: 3002,
+                    containerPort: 8001,
+                    originalHostPort: 3001,
+                    newHostPort: 3002,
+                },
+            ]);
+            const yaml = generateOverrideYaml(allocatedPorts);
+            expect(yaml).toContain('web:');
+            expect(yaml).toContain('api:');
+            expect(yaml).toContain('"3001:8000"');
+            expect(yaml).toContain('"3002:8001"');
+        });
+        it('프로토콜을 포함한다', () => {
+            const allocatedPorts = new Map();
+            allocatedPorts.set('db', [
+                {
+                    hostPort: 5433,
+                    containerPort: 5432,
+                    protocol: 'tcp',
+                    originalHostPort: 5432,
+                    newHostPort: 5433,
+                },
+            ]);
+            const yaml = generateOverrideYaml(allocatedPorts);
+            expect(yaml).toContain('"5433:5432/tcp"');
+        });
+    });
+    describe('parseComposeFile / extractServicePorts / getAllServicePorts', () => {
+        let tmpDir;
+        beforeEach(() => {
+            tmpDir = join(tmpdir(), `pa-test-${Date.now()}`);
+            mkdirSync(tmpDir, { recursive: true });
+        });
+        afterEach(() => {
+            rmSync(tmpDir, { recursive: true, force: true });
+        });
+        it('docker-compose.yml 파일을 파싱한다', () => {
+            const composeContent = `
+services:
+  web:
+    image: nginx
+    ports:
+      - "3000:80"
+  api:
+    image: node
+    ports:
+      - "3001:8000"
+`;
+            writeFileSync(join(tmpDir, 'docker-compose.yml'), composeContent);
+            const config = parseComposeFile(tmpDir);
+            expect(config.services).toBeDefined();
+            expect(config.services?.web).toBeDefined();
+            expect(config.services?.api).toBeDefined();
+        });
+        it('없는 파일은 에러를 던진다', () => {
+            expect(() => parseComposeFile(tmpDir)).toThrow('Docker Compose 파일을 찾을 수 없습니다');
+        });
+        it('서비스의 포트를 추출한다', () => {
+            const composeContent = `
+services:
+  web:
+    ports:
+      - "3000:80"
+      - "3001:443"
+`;
+            writeFileSync(join(tmpDir, 'docker-compose.yml'), composeContent);
+            const config = parseComposeFile(tmpDir);
+            const ports = extractServicePorts(config, 'web');
+            expect(ports).toHaveLength(2);
+            expect(ports[0]).toEqual({ hostPort: 3000, containerPort: 80 });
+            expect(ports[1]).toEqual({ hostPort: 3001, containerPort: 443 });
+        });
+        it('없는 서비스는 에러를 던진다', () => {
+            const composeContent = `
+services:
+  web:
+    ports:
+      - "3000:80"
+`;
+            writeFileSync(join(tmpDir, 'docker-compose.yml'), composeContent);
+            const config = parseComposeFile(tmpDir);
+            expect(() => extractServicePorts(config, 'nonexistent')).toThrow('서비스를 찾을 수 없습니다');
+        });
+        it('모든 서비스의 포트를 가져온다', () => {
+            const composeContent = `
+services:
+  web:
+    ports:
+      - "3000:80"
+  api:
+    ports:
+      - "3001:8000"
+  db:
+    image: postgres
+`;
+            writeFileSync(join(tmpDir, 'docker-compose.yml'), composeContent);
+            const config = parseComposeFile(tmpDir);
+            const allPorts = getAllServicePorts(config);
+            expect(allPorts).toHaveLength(2); // db는 포트 없음
+            expect(allPorts.find(s => s.serviceName === 'web')).toBeDefined();
+            expect(allPorts.find(s => s.serviceName === 'api')).toBeDefined();
+        });
+        it('특정 서비스만 필터링한다', () => {
+            const composeContent = `
+services:
+  web:
+    ports:
+      - "3000:80"
+  api:
+    ports:
+      - "3001:8000"
+`;
+            writeFileSync(join(tmpDir, 'docker-compose.yml'), composeContent);
+            const config = parseComposeFile(tmpDir);
+            const filtered = getAllServicePorts(config, ['web']);
+            expect(filtered).toHaveLength(1);
+            expect(filtered[0].serviceName).toBe('web');
+        });
+        it('long syntax 포트를 파싱한다', () => {
+            const composeContent = `
+services:
+  web:
+    ports:
+      - target: 80
+        published: 3000
+        protocol: tcp
+`;
+            writeFileSync(join(tmpDir, 'docker-compose.yml'), composeContent);
+            const config = parseComposeFile(tmpDir);
+            const ports = extractServicePorts(config, 'web');
+            expect(ports).toHaveLength(1);
+            expect(ports[0]).toEqual({
+                hostPort: 3000,
+                containerPort: 80,
+                protocol: 'tcp',
+            });
+        });
+    });
+    describe('writeOverrideFile', () => {
+        let tmpDir;
+        beforeEach(() => {
+            tmpDir = join(tmpdir(), `pa-test-${Date.now()}`);
+            mkdirSync(tmpDir, { recursive: true });
+        });
+        afterEach(() => {
+            rmSync(tmpDir, { recursive: true, force: true });
+        });
+        it('override 파일을 작성한다', () => {
+            const content = 'test content';
+            const path = writeOverrideFile(tmpDir, content);
+            expect(path).toContain('.pa-compose-override.yml');
+        });
+    });
+});

package/dist/cli/core/port-finder.d.ts

@@ -0,0 +1,2 @@
+export declare function findAvailablePort(preferredPort?: number, excludePorts?: Set<number>): Promise<number>;
+export declare function clearSessionAllocatedPorts(): void;

package/dist/cli/core/port-finder.js

@@ -0,0 +1,52 @@
+import detectPort from 'detect-port';
+import { getAllProcesses } from './state.js';
+import { isProcessRunning } from './process-manager.js';
+const DEFAULT_PORT = 3000;
+// 세션 내에서 이미 할당된 포트 추적 (compose 등에서 여러 포트를 순차 할당 시 사용)
+const sessionAllocatedPorts = new Set();
+async function getUsedPorts() {
+    const processes = await getAllProcesses();
+    const usedPorts = new Set();
+    for (const [, mapping] of Object.entries(processes)) {
+        // 실행 중인 프로세스의 포트만 추가
+        if (mapping.status === 'running' && isProcessRunning(mapping.pid)) {
+            usedPorts.add(mapping.port);
+        }
+    }
+    return usedPorts;
+}
+export async function findAvailablePort(preferredPort = DEFAULT_PORT, excludePorts) {
+    const usedPorts = await getUsedPorts();
+    // 세션 내 할당된 포트와 excludePorts 병합
+    const allExcluded = new Set([
+        ...usedPorts,
+        ...sessionAllocatedPorts,
+        ...(excludePorts || []),
+    ]);
+    let port = preferredPort;
+    const maxAttempts = 100;
+    for (let i = 0; i < maxAttempts; i++) {
+        // 1. 제외 목록에서 이미 사용 중인지 확인
+        if (allExcluded.has(port)) {
+            port++;
+            continue;
+        }
+        // 2. 시스템에서 실제로 사용 가능한지 확인
+        const availablePort = await detectPort(port);
+        if (availablePort === port) {
+            sessionAllocatedPorts.add(port);
+            return port;
+        }
+        // detect-port가 다른 포트를 제안하면 해당 포트도 확인
+        if (!allExcluded.has(availablePort)) {
+            sessionAllocatedPorts.add(availablePort);
+            return availablePort;
+        }
+        port = availablePort + 1;
+    }
+    throw new Error('Could not find an available port');
+}
+// 세션 종료 시 할당된 포트 초기화 (테스트용)
+export function clearSessionAllocatedPorts() {
+    sessionAllocatedPorts.clear();
+}

package/dist/cli/core/port-finder.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli/core/port-finder.test.js

@@ -0,0 +1,106 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { createServer } from 'net';
+import { findAvailablePort, clearSessionAllocatedPorts } from './port-finder.js';
+import { setStatePath, addProcess, saveState } from './state.js';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { rm } from 'fs/promises';
+describe('findAvailablePort', () => {
+    let server = null;
+    // 테스트용으로 높은 포트 번호 사용 (충돌 방지)
+    const TEST_PORT = 19876;
+    beforeEach(() => {
+        // 각 테스트 전에 세션 상태 초기화
+        clearSessionAllocatedPorts();
+    });
+    afterEach(async () => {
+        if (server) {
+            await new Promise((resolve) => {
+                server.close(() => resolve());
+            });
+            server = null;
+        }
+    });
+    const occupyPort = (port) => {
+        return new Promise((resolve, reject) => {
+            const s = createServer();
+            s.listen(port, () => {
+                resolve(s);
+            });
+            s.on('error', reject);
+        });
+    };
+    it('지정한 포트가 사용 가능하면 그대로 반환해야 한다', async () => {
+        const port = await findAvailablePort(TEST_PORT);
+        expect(port).toBe(TEST_PORT);
+    });
+    it('지정한 포트가 사용 중이면 다른 포트를 반환해야 한다', async () => {
+        server = await occupyPort(TEST_PORT);
+        const port = await findAvailablePort(TEST_PORT);
+        expect(port).not.toBe(TEST_PORT);
+        expect(port).toBeGreaterThan(0);
+    });
+    it('포트 번호는 유효한 범위 내에 있어야 한다', async () => {
+        const port = await findAvailablePort(TEST_PORT);
+        expect(port).toBeGreaterThanOrEqual(1);
+        expect(port).toBeLessThanOrEqual(65535);
+    });
+    it('기본 포트(3000)를 사용할 때 유효한 포트를 반환해야 한다', async () => {
+        const port = await findAvailablePort();
+        expect(port).toBeGreaterThanOrEqual(1);
+        expect(port).toBeLessThanOrEqual(65535);
+    });
+});
+describe('findAvailablePort - 상태 파일 참조', () => {
+    const TEST_PORT = 19877;
+    let testStatePath;
+    beforeEach(async () => {
+        // 세션 상태 초기화
+        clearSessionAllocatedPorts();
+        // 테스트용 임시 상태 파일 설정
+        testStatePath = join(tmpdir(), `pa-test-${Date.now()}.json`);
+        setStatePath(testStatePath);
+        // 빈 상태로 초기화
+        await saveState({ mappings: {} });
+    });
+    afterEach(async () => {
+        // 테스트 상태 파일 정리
+        try {
+            await rm(testStatePath);
+        }
+        catch {
+            // 파일이 없어도 무시
+        }
+    });
+    it('상태 파일에 있는 실행 중인 프로세스의 포트를 피해야 한다', async () => {
+        // 상태 파일에 TEST_PORT 사용 중 기록 (현재 프로세스 PID로 실행 중 상태)
+        await addProcess('test-app', {
+            port: TEST_PORT,
+            pid: process.pid, // 현재 프로세스 PID (실행 중으로 판단)
+            command: 'node test.js',
+            originalCommand: 'node test.js',
+            injectionType: 'env',
+            cwd: '/tmp',
+            startedAt: new Date().toISOString(),
+            status: 'running',
+        });
+        const port = await findAvailablePort(TEST_PORT);
+        expect(port).not.toBe(TEST_PORT); // TEST_PORT가 아닌 다른 포트 반환
+    });
+    it('상태 파일에 있지만 종료된 프로세스의 포트는 사용 가능해야 한다', async () => {
+        // 상태 파일에 TEST_PORT 기록하지만 존재하지 않는 PID
+        await addProcess('dead-app', {
+            port: TEST_PORT,
+            pid: 99999999, // 존재하지 않는 PID
+            command: 'node test.js',
+            originalCommand: 'node test.js',
+            injectionType: 'env',
+            cwd: '/tmp',
+            startedAt: new Date().toISOString(),
+            status: 'running',
+        });
+        const port = await findAvailablePort(TEST_PORT);
+        // 실제 TEST_PORT가 사용 가능하면 TEST_PORT 반환
+        expect(port).toBe(TEST_PORT);
+    });
+});

package/dist/cli/core/port-injector.d.ts

@@ -0,0 +1,3 @@
+import type { InjectionResult } from '../../shared/types.js';
+export declare function getDefaultPort(command: string): number;
+export declare function injectPort(originalCommand: string, port: number): InjectionResult;