port-arranger 0.0.1

package/.vite/build/index.cjs

@@ -0,0 +1,2 @@
+"use strict";const i=require("electron"),d=require("path"),A=require("chokidar"),h=require("fs/promises"),j=require("child_process"),I=require("os"),M=require("tree-kill"),E=d.join(I.homedir(),".port-arranger","state.json");function N(e){const t=new Map;try{const o=`${["/usr/local/bin","/opt/homebrew/bin","/usr/bin"].join(":")}:${process.env.PATH||""}`,p=j.execSync("docker compose ps -a --format json",{cwd:e,encoding:"utf-8",stdio:["pipe","pipe","pipe"],env:{...process.env,PATH:o},shell:"/bin/zsh"}).trim().split(`
+`).filter(Boolean);for(const r of p)try{const f=JSON.parse(r),g=f.Service||f.Name,y=(f.State||"").toLowerCase()==="running";(!t.has(g)||y)&&t.set(g,y)}catch{}}catch{}return t}let c=null,u=null;const l=new Set,q=3e3;async function m(){var e;try{const t=await h.readFile(E,"utf-8"),o=JSON.parse(t).mappings;for(const n of Object.values(o))if(n.injectionType==="compose"&&((e=n.composePorts)!=null&&e.length)){const p=N(n.cwd);n.composePorts=n.composePorts.map(r=>({...r,running:p.get(r.serviceName)??!1}))}return o}catch{return{}}}async function w(){const e=await m();l.forEach(t=>t(e))}function $(){c||(c=A.watch(E,{persistent:!0,ignoreInitial:!1,awaitWriteFinish:{stabilityThreshold:100,pollInterval:50}}),c.on("add",()=>w()),c.on("change",()=>w()),c.on("unlink",()=>{l.forEach(e=>e({}))}),u=setInterval(()=>{w()},q))}function L(){c&&(c.close(),c=null),u&&(clearInterval(u),u=null),l.clear()}function O(e){return l.add(e),m().then(e),()=>{l.delete(e)}}async function W(){return m()}const b=d.join(I.homedir(),".port-arranger","state.json");async function S(){try{const e=await h.readFile(b,"utf-8");return JSON.parse(e)}catch{return{mappings:{}}}}async function v(e){await h.writeFile(b,JSON.stringify(e,null,2),"utf-8")}function P(e){return new Promise((t,s)=>{M(e,"SIGTERM",o=>{o?s(o):t()})})}function T(e,t){try{j.execSync("docker compose down",{cwd:e,stdio:"pipe"})}catch{M(t,"SIGTERM")}}function H(e){i.ipcMain.handle("stop-process",async(t,s)=>{const o=await S(),n=o.mappings[s];if(!n)throw new Error(`Process not found: ${s}`);n.injectionType==="compose"?T(n.cwd,n.pid):await P(n.pid);const{[s]:p,...r}=o.mappings;await v({...o,mappings:r})}),i.ipcMain.handle("restart-process",async(t,s)=>{const o=await S(),n=o.mappings[s];if(!n)throw new Error(`Process not found: ${s}`);n.injectionType==="compose"?T(n.cwd,n.pid):await P(n.pid);const{[s]:p,...r}=o.mappings;await v({...o,mappings:r})}),i.ipcMain.handle("open-browser",async(t,s)=>{await i.shell.openExternal(`http://localhost:${s}`)}),i.ipcMain.handle("set-always-on-top",async(t,s)=>{e.setAlwaysOnTop(s)}),i.ipcMain.on("minimize-window",()=>{e.minimize()}),i.ipcMain.on("close-window",()=>{e.close()})}let a=null;function _(){a=new i.BrowserWindow({width:410,height:500,minWidth:320,minHeight:300,frame:!1,transparent:!1,resizable:!0,webPreferences:{preload:d.join(__dirname,"preload.cjs"),contextIsolation:!0,nodeIntegration:!1}}),a.loadFile(d.join(__dirname,"../renderer/main_window/index.html")),H(a),$(),i.ipcMain.handle("get-processes",async()=>W());const e=O(t=>{a&&!a.isDestroyed()&&a.webContents.send("processes-update",t)});a.on("closed",()=>{e(),a=null})}i.app.whenReady().then(()=>{_(),i.app.on("activate",()=>{i.BrowserWindow.getAllWindows().length===0&&_()})});i.app.on("window-all-closed",()=>{L(),process.platform!=="darwin"&&i.app.quit()});

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Changmin (Chris) Kang (https://github.com/mindori)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,192 @@
+<div align="center">
+
+# port-arranger
+
+**Run multiple dev servers without port conflicts**
+
+[Quick Start](#quick-start) · [Usage Guide](#usage-guide) · [Commands](#commands) · [How It Works](#how-it-works)
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/port-arranger"><img src="https://img.shields.io/npm/v/port-arranger.svg" alt="npm version"></a>
+  <img src="https://img.shields.io/github/license/mindori/port-arranger" alt="license">
+  <img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen" alt="node version">
+  <img src="https://img.shields.io/badge/AI-Claude-blueviolet" alt="AI powered by Claude">
+</p>
+
+</div>
+
+<br />
+
+<div align="center">
+  <img src="assets/demo.gif" alt="port-arranger demo" width="600" />
+</div>
+
+<br />
+
+## Why port-arranger?
+
+### The Problem
+
+```bash
+# Terminal 1
+npm run dev  # localhost:3000
+
+# Terminal 2
+npm run dev  # Error: Port 3000 is already in use
+```
+
+When running multiple projects simultaneously during development, port conflicts are inevitable. You end up manually changing ports or hunting down processes to kill.
+
+### The Solution
+
+```bash
+pa run "npm run dev"  # Automatically assigns an available port
+```
+
+port-arranger wraps your dev server commands and automatically finds and assigns available ports. No more port conflicts, ever.
+
+### Key Features
+
+|                    | Feature                  | Description                                          |
+| ------------------ | ------------------------ | ---------------------------------------------------- |
+| :zap:              | **Auto Port Assignment** | Automatically finds and assigns available ports      |
+| :mag:              | **Framework Detection**  | Recognizes Next.js, Vite, Express, FastAPI, and more |
+| :clipboard:        | **Process Management**   | List, monitor, and stop running servers              |
+| :desktop_computer: | **GUI Dashboard**        | Visual server management with Electron-based UI      |
+
+## Requirements
+
+- **Node.js 18+**
+
+## Quick Start
+
+```bash
+# Install globally
+npm install -g port-arranger
+
+# Run your dev server
+pa run "npm run dev"
+```
+
+That's it! port-arranger handles the rest.
+
+## Usage Guide
+
+### Step 1: Run a Server
+
+```bash
+# Basic usage
+pa run "npm run dev"
+
+# With a custom name
+pa run "npm run dev" --name my-frontend
+
+# With a preferred port (falls back to available port if taken)
+pa run "npm run dev" --port 3000
+```
+
+### Step 2: Manage Servers
+
+```bash
+# List all running servers
+pa list
+
+# Stop a specific server
+pa stop my-frontend
+
+# Stop all servers
+pa stop --all
+```
+
+### Step 3: GUI Dashboard
+
+Launch the visual dashboard for an overview of all your running servers:
+
+```bash
+pa ui
+```
+
+## Commands
+
+| Command                   | Description                             | Example                            |
+| ------------------------- | --------------------------------------- | ---------------------------------- |
+| `pa run <cmd>`            | Run a command with auto port assignment | `pa run "npm run dev"`             |
+| `pa run <cmd> --name <n>` | Run with a custom project name          | `pa run "npm run dev" --name api`  |
+| `pa run <cmd> --port <p>` | Run with a preferred port               | `pa run "npm run dev" --port 3000` |
+| `pa list`                 | List all running servers                | `pa list`                          |
+| `pa stop <name>`          | Stop a server by name                   | `pa stop my-project`               |
+| `pa stop --all`           | Stop all running servers                | `pa stop --all`                    |
+| `pa ui`                   | Open the GUI dashboard                  | `pa ui`                            |
+
+## Supported Frameworks
+
+| Framework          | Port Injection Method | Example                        |
+| ------------------ | --------------------- | ------------------------------ |
+| Next.js            | Environment variable  | `PORT=3001 npm run dev`        |
+| Vite               | CLI flag              | `vite --port 3001`             |
+| Express            | Environment variable  | `PORT=3001 node server.js`     |
+| FastAPI / uvicorn  | CLI flag              | `uvicorn main:app --port 3001` |
+| Python http.server | Argument              | `python -m http.server 3001`   |
+
+## How It Works
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  pa run "npm run dev"                                       │
+└─────────────────────────────────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│  1. Parse Command                                           │
+│     Detect framework pattern (Next.js, Vite, Express, etc.) │
+└─────────────────────────────────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│  2. Find Available Port                                     │
+│     Use detect-port to find an open port                    │
+└─────────────────────────────────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│  3. Inject Port                                             │
+│     Apply framework-specific injection (env, flag, arg)     │
+└─────────────────────────────────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│  4. Spawn & Track Process                                   │
+│     Save process info to ~/.port-arranger/state.json        │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Configuration
+
+port-arranger stores state in `~/.port-arranger/state.json`:
+
+```json
+{
+  "processes": [
+    {
+      "name": "my-frontend",
+      "port": 3001,
+      "pid": 12345,
+      "command": "npm run dev",
+      "cwd": "/path/to/project",
+      "startedAt": "2024-01-15T10:30:00.000Z"
+    }
+  ]
+}
+```
+
+## Contributing
+
+Contributions are welcome! Feel free to:
+
+- 🐛 Report bugs
+- 💡 Suggest features
+- 🔧 Submit pull requests
+
+## Author
+
+[Changmin (Chris) Kang](https://github.com/mindori)

package/dist/cli/commands/list.d.ts

@@ -0,0 +1 @@
+export declare function listCommand(): Promise<void>;

package/dist/cli/commands/list.js

@@ -0,0 +1,87 @@
+import chalk from 'chalk';
+import { getAllProcesses } from '../core/state.js';
+import { isProcessRunning, getComposeServicesStatus } from '../core/process-manager.js';
+export async function listCommand() {
+    const processes = await getAllProcesses();
+    const entries = Object.entries(processes);
+    if (entries.length === 0) {
+        console.log(chalk.gray('No running processes.'));
+        console.log(chalk.gray('Start a process with \'pa run "<command>"\''));
+        return;
+    }
+    console.log(chalk.bold('\nRunning processes:\n'));
+    // 테이블 헤더
+    console.log(chalk.gray(padEnd('Name', 20) +
+        padEnd('Port', 8) +
+        padEnd('PID', 10) +
+        padEnd('Status', 10) +
+        'Command'));
+    console.log(chalk.gray('─'.repeat(80)));
+    for (const [name, mapping] of entries) {
+        const running = isProcessRunning(mapping.pid);
+        const status = running
+            ? chalk.green('Running')
+            : chalk.red('Stopped');
+        const pid = String(mapping.pid);
+        const cmd = truncate(mapping.originalCommand, 30);
+        // compose인 경우 서비스별로 하위 표시
+        if (mapping.injectionType === 'compose' && mapping.composePorts?.length) {
+            // 각 서비스의 실제 상태 조회
+            const serviceStatuses = await getComposeServicesStatus(mapping.cwd);
+            // 실행 중인 서비스 수 계산
+            const services = mapping.composePorts;
+            const runningCount = services.filter(s => serviceStatuses.get(s.serviceName)).length;
+            const totalCount = services.length;
+            // 프로젝트 레벨 상태: 항상 N/M 형식으로 표시
+            let projectStatus;
+            if (runningCount === totalCount) {
+                projectStatus = chalk.green(`${runningCount}/${totalCount}`);
+            }
+            else if (runningCount > 0) {
+                projectStatus = chalk.yellow(`${runningCount}/${totalCount}`);
+            }
+            else {
+                projectStatus = chalk.red(`${runningCount}/${totalCount}`);
+            }
+            console.log(padEnd(name, 20) +
+                padEnd(chalk.gray('-'), 8) +
+                padEnd(pid, 10) +
+                padEnd(projectStatus, 10) +
+                chalk.gray(cmd));
+            // 서비스별 표시 (상태 포함)
+            for (let i = 0; i < services.length; i++) {
+                const svc = services[i];
+                const isLast = i === services.length - 1;
+                const prefix = isLast ? '  └─ ' : '  ├─ ';
+                const svcRunning = serviceStatuses.get(svc.serviceName) ?? false;
+                const svcStatus = svcRunning ? chalk.green('●') : chalk.red('●');
+                const portColor = svcRunning ? chalk.cyan : chalk.gray;
+                console.log(chalk.gray(prefix) +
+                    svcStatus + ' ' +
+                    padEnd(svc.serviceName, 13) +
+                    portColor(String(svc.port)));
+            }
+        }
+        else {
+            const port = chalk.cyan(String(mapping.port));
+            console.log(padEnd(name, 20) +
+                padEnd(port, 8) +
+                padEnd(pid, 10) +
+                padEnd(status, 10) +
+                chalk.gray(cmd));
+        }
+    }
+    console.log();
+}
+function padEnd(str, length) {
+    // ANSI 코드 제거 후 길이 계산
+    const plainStr = str.replace(/\x1b\[[0-9;]*m/g, '');
+    const padding = Math.max(0, length - plainStr.length);
+    return str + ' '.repeat(padding);
+}
+function truncate(str, maxLength) {
+    if (str.length <= maxLength) {
+        return str;
+    }
+    return str.slice(0, maxLength - 3) + '...';
+}

package/dist/cli/commands/run.d.ts

@@ -0,0 +1,7 @@
+interface RunOptions {
+    name?: string;
+    dryRun?: boolean;
+    port?: number;
+}
+export declare function runCommand(command: string, options: RunOptions): Promise<void>;
+export {};

package/dist/cli/commands/run.js

@@ -0,0 +1,151 @@
+import { basename } from 'path';
+import chalk from 'chalk';
+import { findAvailablePort } from '../core/port-finder.js';
+import { injectPort, getDefaultPort } from '../core/port-injector.js';
+import { spawnProcess } from '../core/process-manager.js';
+import { addProcess } from '../core/state.js';
+import { parseComposeFile, getAllServicePorts, extractServiceNames, generateOverrideYaml, writeOverrideFile, transformComposeCommand, } from '../core/compose-parser.js';
+export async function runCommand(command, options) {
+    const projectName = options.name || basename(process.cwd());
+    const cwd = process.cwd();
+    // 포트 주입 (패턴 인식)
+    const injection = injectPort(command, options.port || 3000);
+    // Docker Compose 처리
+    if (injection.injectionType === 'compose') {
+        await runComposeCommand(command, projectName, cwd, options);
+        return;
+    }
+    // 일반 명령어 처리
+    await runNormalCommand(command, injection, projectName, cwd, options);
+}
+async function runNormalCommand(command, injection, projectName, cwd, options) {
+    const defaultPort = getDefaultPort(command);
+    const preferredPort = options.port || defaultPort;
+    const availablePort = await findAvailablePort(preferredPort);
+    // 포트 재주입 (실제 할당된 포트로)
+    const finalInjection = injectPort(command, availablePort);
+    console.log(chalk.blue(`[${projectName}]`) + ` Port ${chalk.green(availablePort)} assigned`);
+    if (options.dryRun) {
+        console.log(chalk.yellow('\n[dry-run] Not actually executing'));
+        return;
+    }
+    const pid = await spawnProcess(projectName, finalInjection.command, finalInjection.env, cwd);
+    const mapping = {
+        port: availablePort,
+        pid,
+        command: finalInjection.command,
+        originalCommand: command,
+        injectionType: finalInjection.injectionType,
+        cwd,
+        startedAt: new Date().toISOString(),
+        status: 'running',
+    };
+    await addProcess(projectName, mapping);
+    console.log(chalk.green(`\n✓ Process started (PID: ${pid})`));
+    console.log(chalk.gray(`http://localhost:${availablePort}`));
+}
+async function runComposeCommand(command, projectName, cwd, options) {
+    console.log(chalk.blue(`[${projectName}]`) + ' Docker Compose mode');
+    // 1. docker-compose.yml 파싱
+    const config = parseComposeFile(cwd);
+    const serviceNames = extractServiceNames(command);
+    const servicePorts = getAllServicePorts(config, serviceNames.length > 0 ? serviceNames : undefined);
+    if (servicePorts.length === 0) {
+        console.log(chalk.yellow('No services with exposed ports. Running original command.'));
+        if (!options.dryRun) {
+            const pid = await spawnProcess(projectName, command, {}, cwd);
+            await addProcess(projectName, {
+                port: 0,
+                pid,
+                command,
+                originalCommand: command,
+                injectionType: 'compose',
+                cwd,
+                startedAt: new Date().toISOString(),
+                status: 'running',
+            });
+        }
+        return;
+    }
+    // 2. 각 서비스의 각 포트에 대해 사용 가능한 포트 할당
+    const allocatedPorts = new Map();
+    const portSummary = [];
+    for (const service of servicePorts) {
+        const allocated = [];
+        for (const port of service.ports) {
+            const newHostPort = await findAvailablePort(port.hostPort);
+            allocated.push({
+                ...port,
+                originalHostPort: port.hostPort,
+                newHostPort,
+            });
+            if (port.hostPort !== newHostPort) {
+                portSummary.push(`  ${chalk.cyan(service.serviceName)}: ${chalk.yellow(port.hostPort)} → ${chalk.green(newHostPort)}`);
+            }
+            else {
+                portSummary.push(`  ${chalk.cyan(service.serviceName)}: ${chalk.green(port.hostPort)}`);
+            }
+        }
+        allocatedPorts.set(service.serviceName, allocated);
+    }
+    // 3. 포트 충돌이 있는 경우에만 override 파일 생성
+    const hasConflict = Array.from(allocatedPorts.values())
+        .flat()
+        .some(p => p.originalHostPort !== p.newHostPort);
+    let finalCommand = command;
+    if (hasConflict) {
+        const overrideYaml = generateOverrideYaml(allocatedPorts);
+        const overridePath = writeOverrideFile(cwd, overrideYaml);
+        finalCommand = transformComposeCommand(command, overridePath);
+        console.log(chalk.gray(`Override 파일 생성: ${overridePath}`));
+    }
+    // 4. 포트 할당 결과 출력
+    console.log(chalk.blue('\nPort assignments:'));
+    for (const line of portSummary) {
+        console.log(line);
+    }
+    if (options.dryRun) {
+        console.log(chalk.yellow('\n[dry-run] Not actually executing'));
+        console.log(chalk.gray(`Command: ${finalCommand}`));
+        return;
+    }
+    // 5. 프로세스 실행
+    const pid = await spawnProcess(projectName, finalCommand, {}, cwd);
+    // 6. 상태 저장 (첫 번째 서비스의 첫 번째 포트를 대표 포트로 사용)
+    const firstService = servicePorts[0];
+    const firstAllocated = allocatedPorts.get(firstService.serviceName)?.[0];
+    const representativePort = firstAllocated?.newHostPort || 0;
+    // compose 서비스별 포트 정보 수집
+    const composePorts = [];
+    for (const service of servicePorts) {
+        const allocated = allocatedPorts.get(service.serviceName);
+        if (allocated && allocated.length > 0) {
+            composePorts.push({
+                serviceName: service.serviceName,
+                port: allocated[0].newHostPort,
+            });
+        }
+    }
+    const mapping = {
+        port: representativePort,
+        pid,
+        command: finalCommand,
+        originalCommand: command,
+        injectionType: 'compose',
+        cwd,
+        startedAt: new Date().toISOString(),
+        status: 'running',
+        composePorts,
+    };
+    await addProcess(projectName, mapping);
+    console.log(chalk.green(`\n✓ Docker Compose started (PID: ${pid})`));
+    // 각 서비스별 URL 출력
+    for (const service of servicePorts) {
+        const allocated = allocatedPorts.get(service.serviceName);
+        if (allocated) {
+            for (const port of allocated) {
+                console.log(chalk.gray(`${service.serviceName}: http://localhost:${port.newHostPort}`));
+            }
+        }
+    }
+}

package/dist/cli/commands/stop.d.ts

@@ -0,0 +1,5 @@
+interface StopOptions {
+    all?: boolean;
+}
+export declare function stopCommand(name: string | undefined, options: StopOptions): Promise<void>;
+export {};

package/dist/cli/commands/stop.js

@@ -0,0 +1,105 @@
+import chalk from 'chalk';
+import { execSync } from 'child_process';
+import { getAllProcesses, removeProcess, getProcess } from '../core/state.js';
+import { killProcess, isProcessRunning } from '../core/process-manager.js';
+export async function stopCommand(name, options) {
+    if (options.all) {
+        await stopAllProcesses();
+        return;
+    }
+    if (!name) {
+        console.log(chalk.red('Specify a process name or use --all option.'));
+        console.log(chalk.gray('Usage: pa stop <name> or pa stop --all'));
+        return;
+    }
+    await stopSingleProcess(name);
+}
+async function stopComposeProcess(name, mapping) {
+    const { cwd, pid } = mapping;
+    try {
+        execSync('docker compose down', {
+            cwd,
+            stdio: 'pipe',
+        });
+    }
+    catch {
+        // compose down 실패 시 fallback으로 프로세스 kill
+        if (isProcessRunning(pid)) {
+            await killProcess(pid);
+        }
+    }
+}
+async function stopSingleProcess(name) {
+    const mapping = await getProcess(name);
+    if (!mapping) {
+        console.log(chalk.red(`Process '${name}' not found.`));
+        console.log(chalk.gray("Use 'pa list' to see running processes."));
+        return;
+    }
+    const { pid } = mapping;
+    // Docker Compose인 경우 다른 방식으로 종료
+    if (mapping.injectionType === 'compose') {
+        try {
+            await stopComposeProcess(name, mapping);
+            await removeProcess(name);
+            console.log(chalk.green(`✓ ${name} (Docker Compose stopped)`));
+        }
+        catch (error) {
+            console.log(chalk.red(`Failed to stop Docker Compose: ${error.message}`));
+        }
+        return;
+    }
+    if (!isProcessRunning(pid)) {
+        console.log(chalk.yellow(`Process '${name}' already stopped.`));
+        await removeProcess(name);
+        console.log(chalk.gray('Removed from state'));
+        return;
+    }
+    try {
+        await killProcess(pid);
+        await removeProcess(name);
+        console.log(chalk.green(`✓ Process '${name}' stopped (PID: ${pid})`));
+    }
+    catch (error) {
+        console.log(chalk.red(`Failed to stop process: ${error.message}`));
+    }
+}
+async function stopAllProcesses() {
+    const processes = await getAllProcesses();
+    const entries = Object.entries(processes);
+    if (entries.length === 0) {
+        console.log(chalk.gray('No processes to stop.'));
+        return;
+    }
+    console.log(chalk.blue(`Stopping ${entries.length} processes...`));
+    let successCount = 0;
+    let failCount = 0;
+    for (const [name, mapping] of entries) {
+        try {
+            if (mapping.injectionType === 'compose') {
+                await stopComposeProcess(name, mapping);
+                console.log(chalk.green(`  ✓ ${name} (Docker Compose stopped)`));
+            }
+            else if (isProcessRunning(mapping.pid)) {
+                await killProcess(mapping.pid);
+                console.log(chalk.green(`  ✓ ${name} (PID: ${mapping.pid})`));
+            }
+            else {
+                console.log(chalk.gray(`  - ${name} (already stopped)`));
+            }
+            await removeProcess(name);
+            successCount++;
+        }
+        catch (error) {
+            console.log(chalk.red(`  ✗ ${name}: ${error.message}`));
+            failCount++;
+        }
+    }
+    console.log();
+    if (failCount === 0) {
+        console.log(chalk.green(`✓ All processes stopped (${successCount})`));
+    }
+    else {
+        console.log(chalk.yellow(`Complete: ${successCount} succeeded, ${failCount} failed`));
+    }
+}

package/dist/cli/commands/ui.d.ts

@@ -0,0 +1 @@
+export declare function uiCommand(): Promise<void>;

package/dist/cli/commands/ui.js

@@ -0,0 +1,29 @@
+import { spawn } from 'child_process';
+import { existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+export async function uiCommand() {
+    // Electron 실행 파일 경로 찾기
+    const projectRoot = join(__dirname, '..', '..', '..');
+    const electronPath = join(projectRoot, 'node_modules', '.bin', 'electron');
+    if (!existsSync(electronPath)) {
+        throw new Error('Electron is not installed.\n' +
+            'Run npm install and try again.');
+    }
+    // Vite 빌드 결과물 확인
+    const mainPath = join(projectRoot, '.vite', 'build', 'index.cjs');
+    if (!existsSync(mainPath)) {
+        throw new Error('GUI is not built.\n' +
+            'Run npm run build:gui and try again.');
+    }
+    // Electron 프로세스를 detached 모드로 실행
+    const child = spawn(electronPath, [mainPath], {
+        detached: true,
+        stdio: 'ignore',
+        cwd: projectRoot,
+    });
+    child.unref();
+    console.log('Port Arranger GUI launched.');
+}

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

@@ -0,0 +1,56 @@
+import type { ComposePortMapping, ComposeServicePorts, AllocatedComposePort } from '../../shared/types.js';
+interface ComposeService {
+    ports?: (string | number | PortObject)[];
+    [key: string]: unknown;
+}
+interface PortObject {
+    target: number;
+    published?: number | string;
+    protocol?: 'tcp' | 'udp';
+}
+interface ComposeConfig {
+    services?: Record<string, ComposeService>;
+    [key: string]: unknown;
+}
+/**
+ * 포트 문자열을 파싱하여 호스트/컨테이너 포트 추출
+ * 지원 형식:
+ * - "3000" → 3000:3000
+ * - "3000:8000" → 3000:8000
+ * - "127.0.0.1:3000:8000" → 3000:8000 (IP 무시)
+ * - "3000:8000/tcp" → 3000:8000 (tcp)
+ */
+export declare function parsePortString(portStr: string | number): ComposePortMapping;
+/**
+ * docker-compose.yml 파일을 파싱
+ */
+export declare function parseComposeFile(cwd: string, filename?: string): ComposeConfig;
+/**
+ * 서비스 이름 목록 추출 (명령어에서 특정 서비스가 지정된 경우)
+ */
+export declare function extractServiceNames(command: string): string[];
+/**
+ * 특정 서비스의 포트 매핑 추출
+ */
+export declare function extractServicePorts(config: ComposeConfig, serviceName: string): ComposePortMapping[];
+/**
+ * 모든 서비스의 포트 매핑 추출
+ */
+export declare function getAllServicePorts(config: ComposeConfig, serviceNames?: string[]): ComposeServicePorts[];
+/**
+ * Override YAML 파일 생성
+ */
+export declare function generateOverrideYaml(allocatedPorts: Map<string, AllocatedComposePort[]>): string;
+/**
+ * Override 파일 작성
+ */
+export declare function writeOverrideFile(cwd: string, content: string): string;
+/**
+ * docker compose 명령어를 override 파일을 포함하도록 변환
+ */
+export declare function transformComposeCommand(originalCommand: string, overridePath: string): string;
+/**
+ * Override 파일 경로 반환
+ */
+export declare function getOverrideFilePath(cwd: string): string;
+export {};