@gbdx/devis 1.0.0

package/README.md

@@ -0,0 +1,201 @@
+# devis
+
+pnpm 모노레포의 **로컬 개발 데스크톱 앱**. 시스템에 한 번 설치해 두고, 여러
+모노레포의 워크스페이스를 한 창에서 등록·전환·관리한다. 사이드바에서 모노레포를
+고르면 그 워크스페이스의 프로젝트·프로세스·로그를 보고, pm2/docker/pnpm 을 UI 에서
+직접 조작한다.
+
+## 기능
+
+- **Workspaces 사이드바** — 등록된 모노레포 전환. 드래그로 순서 변경. 활성
+  모노레포의 컨텍스트만 표시·조작.
+- **Workspace 탭** — 모노레포 전체 패키지를 카테고리(App/Module/Infra)별로
+  조회. pm2 프로세스의 상태·CPU·메모리·업타임 실시간 표시 (CPU/메모리는 프로세스
+  트리 전체 합산이라 실제 워크로드 값). 시작/재시작/정지/삭제 UI 에서 바로.
+- **Docker 탭** — 로컬 컨테이너 목록·시작/중지/재시작/삭제·실시간 로그.
+- **로그 뷰어** — 가상 스크롤 (라이브 ≤2000줄, history 무제한), ANSI 색상.
+- **도구 버튼** — 프로젝트 위치에서 WebStorm·VS Code·터미널·Finder 한 번에 열기.
+
+## 설치
+
+### 글로벌 설치 (권장)
+
+```sh
+pnpm install -g @gbdx/devis
+```
+
+또는 임시 실행:
+
+```sh
+pnpx @gbdx/devis
+```
+
+> 문서·예제는 **pnpm/pnpx** 표기만 사용한다 (devis 가 pnpm 모노레포 전용 도구
+> 라 도구체인을 일관시킴). npm/npx 도 동일하게 동작은 한다.
+
+설치 직후 자동 수행:
+- `prepare` — CLI 번들 빌드 (`dist/cli/index.js`)
+- `postinstall` — caddy 바이너리 다운로드 (`.bin/caddy`)
+
+> pnpm 10+ 는 의존성의 `postinstall`/`prepare` 를 기본 차단한다. 첫 설치 시
+> `pnpm approve-builds` 로 한 번 승인해야 한다.
+
+> **Neutralino 런타임**: 첫 실행 시 OS·arch 에 맞는 프레임워크 바이너리(~2MB)를
+> `~/.devis/neutralino/<version>/` 으로 lazy 다운로드 (이후 재사용).
+
+### 요구사항
+
+- **Node 24+** — devis CLI 런타임
+- **pnpm** — 모노레포 도구. catalog 등의 기능을 가정
+- **macOS / Linux / Windows** — 시스템 webview 사용
+  - macOS: WKWebView (기본 포함)
+  - Linux: `libwebkit2gtk-4.0-37` 또는 `4.1-0`
+  - Windows: WebView2 (Win11 기본 포함, Win10 은 별도 설치)
+
+## 시작하기
+
+모노레포로 이동해서 실행:
+
+```sh
+cd /path/to/your/monorepo
+devis
+```
+
+처음 호출 흐름:
+1. cwd 의 모노레포(`pnpm-workspace.yaml` 위치) 가 `~/.devis/workspaces/` 에 자동 등록
+2. `devis.config.jsonc` 가 없으면 자동 생성, `node_modules/.cache/devis/schema.json` 도 동기화
+3. 활성 워크스페이스로 설정
+4. 데스크톱 앱이 글로벌 캐시에 없으면 조립
+5. 앱 실행 (Dock/작업표시줄에 고정해 두면 클릭만으로 재실행 가능)
+
+같은 명령을 다른 모노레포에서 실행하면 — 이미 떠 있는 인스턴스의 사이드바가
+새 모노레포로 자동 전환 (file watcher 기반). 등록도 자동.
+
+## CLI 명령
+
+```sh
+# 워크스페이스 관리
+devis                      # UI 실행 (cwd 가 모노레포면 등록·활성화)
+devis register [path]      # 워크스페이스 수동 등록 (기본: cwd)
+devis unregister <slug>    # 등록 해제
+devis workspaces           # 등록 목록 (* = 활성)
+
+# fleet 관리 — cwd 의 모노레포에 작용. 모노레포 밖이면 에러.
+devis up [name|all]        # 앱 실행 (포트·인증서·Caddy·pm2 자동)
+devis down [name|all]      # 정리
+devis status (ps)          # 프로세스 표
+devis logs [name]          # 실시간 로그
+devis restart [name|all]
+devis stop [name|all]
+devis caddy                # Caddy 만 단독 기동
+```
+
+UI 의 "시작" 버튼은 내부적으로 `devis up <name>` 을 활성 워크스페이스 cwd 로
+호출 — 항상 정확한 모노레포에 적용.
+
+## 설정
+
+설정은 **모노레포별로** `devis.config.jsonc` 에 둔다. 활성 워크스페이스의 config
+를 그때그때 읽는다. `.env` 등은 사용하지 않는다.
+
+| 파일 | 용도 | 커밋 |
+|------|------|------|
+| `devis.config.jsonc` | 팀 공용 설정 | ✅ |
+| `devis.config.local.jsonc` | 개인 로컬 오버라이드 | ❌ (gitignore) |
+
+워크스페이스에서 devis 를 처음 실행하면 `devis.config.jsonc` 가 없을 때 자동
+생성된다 — `workspaceSlug` 는 루트 `package.json` name 에서 도출. 두 파일 모두
+없어도 기본값으로 동작한다.
+
+자동완성·검증은 매 실행 시 `node_modules/.cache/devis/schema.json` 에 떨궈지는
+JSON Schema 가 담당. 생성된 config 의 `$schema` 가 그 상대 경로를 가리킨다.
+
+```jsonc
+// devis.config.jsonc
+{
+  "$schema": "./node_modules/.cache/devis/schema.json",
+
+  // pm2 namespace · Caddy 라우트 식별자. 기본: 루트 package.json name.
+  "workspaceSlug": "myapp",
+
+  // 로컬 HTTPS 도메인. 기본: `<workspaceSlug>.lvh.me`
+  // "internalDomain": "myapp.lvh.me",
+
+  // 외부 퍼블릭 도메인 (옵션). 설정 시 ACME 인증서 자동 발급.
+  // "publicDomain": "myapp.example.com"
+}
+```
+
+| 필드 | 기본값 | 설명 |
+|------|--------|------|
+| `workspaceSlug` | 루트 `package.json` name (`@scope/foo` → `scope-foo`) | pm2 namespace / Caddy 라우트 식별 |
+| `internalDomain` | `<workspaceSlug>.lvh.me` | 로컬 HTTPS 도메인 |
+| `caddyAdmin` | `http://localhost:2019` | Caddy Admin API |
+| `publicDomain` | — | 퍼블릭 도메인 (선택) |
+| `tls` | — | 기존 인증서 직접 지정 (선택) |
+
+## 글로벌 상태 위치
+
+```
+~/.devis/
+├── workspaces/<slug>/workspace.json   # 등록 워크스페이스 메타데이터
+├── active                              # 활성 슬러그 (텍스트 한 줄)
+├── preferences.json                    # 사용자 설정
+├── neutralino/<ver>/                   # 프레임워크 바이너리 캐시
+├── app/<ver>/Devis.app                 # 조립된 데스크톱 앱 (macOS)
+├── pm2/                                # 전용 PM2_HOME
+├── lock                                # 싱글톤 PID
+└── logs/
+```
+
+- 특정 모노레포 빼기: `devis unregister <slug>` (또는 디렉터리 삭제)
+- 전체 초기화: `rm -rf ~/.devis`
+- 위치 override: 환경변수 `DEVIS_HOME`
+
+## 아키텍처
+
+```
+┌──────────────────────────────────────────────────┐
+│ devis CLI (Node.js, 글로벌 설치 또는 pnpx)         │
+│  - cwd 의 모노레포 감지·자동 등록                  │
+│  - 다른 인스턴스 있으면 active 만 갱신 후 종료      │
+│  - 안 떠 있으면 글로벌 캐시에 앱 조립 + 실행        │
+└────────────────────────┬─────────────────────────┘
+                         ▼
+┌──────────────────────────────────────────────────┐
+│ Devis 데스크톱 앱 (Neutralino webview)             │
+│  ┌──────────────┬──────────────────────────────┐ │
+│  │ Workspaces   │ React SPA                    │ │
+│  │ 사이드바     │   └─► os.execCommand/spawn   │ │
+│  │              │      → pnpm/pm2/docker 직접  │ │
+│  └──────────────┴──────────────────────────────┘ │
+└──────────────────────────────────────────────────┘
+                         │
+                         ▼
+           ~/.devis/  (글로벌 홈)
+```
+
+자세한 설계 결정은 [`docs/adr/`](./docs/adr/) 참고.
+
+## 외부 의존성
+
+| 의존성 | 역할 | 설치 방식 |
+|--------|------|----------|
+| **Neutralino** | 데스크톱 셸 (시스템 webview) | 첫 실행 시 자동 다운로드 |
+| **pm2** | 워크스페이스 앱들의 백그라운드 관리 | npm (번들) |
+| **caddy** | 워크스페이스 앱들의 HTTPS 리버스 프록시 | postinstall 자동 / 시스템 caddy 감지 |
+| **devcert** | 로컬 CA + HTTPS 인증서 | npm |
+| **@resvg/resvg-js** | 앱 아이콘 SVG → PNG 라스터 | npm (prebuilt) |
+| **zod** | 글로벌 상태 파일 스키마 검증 | npm |
+| **docker** | (선택) 컨테이너 조회·제어 | 시스템 |
+
+docker 는 없어도 동작 — Docker 탭에 안내 메시지만.
+
+## 기여
+
+기여자·AI 에이전트를 위한 가이드는 [`AGENTS.md`](./AGENTS.md) 와 모듈별
+`*/AGENTS.md` 참고. 설계 결정은 [`docs/adr/`](./docs/adr/).
+
+## 라이선스
+
+[AGPL-3.0-or-later](./LICENSE).