visual-remote 0.2.0 → 0.3.1

package/README.md

@@ -18,16 +18,20 @@ Node.js와 pnpm 버전은 각각 `.nvmrc`와 `package.json`에 고정되어 있
 
 ## 가장 빠른 사용
 
-Vite 앱의 `package.json`과 `vite.config`가 있는 폴더에서 한 번만 초기화합니다.
+Vite 또는 Next.js 앱의 `package.json`이 있는 폴더에서 한 번만 초기화합니다.
+Next.js 자동 통합은 `instrumentation-client`를 지원하는 Next.js 15.3 이상이
+필요합니다.
 
 ```bash
 npx --yes visual-remote@latest init
 ```
 
-`init`은 다음 작업을 수행합니다.
+`init`은 프로젝트 종류를 감지하고 다음 작업을 수행합니다.
 
 - 현재 프로젝트에 `visual-remote`를 개발 의존성으로 설치합니다.
-- `vite.config`의 플러그인 배열에 `visualRemote()`를 추가합니다.
+- Vite에서는 `vite.config`에 `visualRemote()` 플러그인을 추가합니다.
+- Next.js에서는 `next.config`에 `withVisualRemote()`를 적용하고
+  `instrumentation-client`에 개발 전용 클라이언트 로더를 추가합니다.
 - 현재 폴더에 `.visualdev/config.yaml`을 생성합니다.
 
 이후에는 앱을 평소처럼 실행합니다.
@@ -42,14 +46,16 @@ npm run dev
 
 ```text
 http://localhost:9011/api/*       → 기존 앱이 그대로 처리
-http://localhost:9011/@vite/*     → 기존 Vite/HMR이 그대로 처리
+http://localhost:9011/@vite/*     → 기존 Vite HMR이 그대로 처리
+http://localhost:9011/_next/*     → 기존 Next.js 자산/HMR이 그대로 처리
 http://localhost:9011/_visual/*   → 내부 Visual Remote Bridge로만 전달
 ```
 
-이미 실행 중이던 개발 서버가 있다면 `init` 후 한 번 재시작해야 변경된 Vite 설정이
+이미 실행 중이던 개발 서버가 있다면 `init` 후 한 번 재시작해야 변경된 설정이
 적용됩니다. Portr를 사용할 때도 내부 Bridge 포트가 아니라 기존 앱 포트만 노출합니다.
 
-현재 자동 통합은 Vite 프로젝트를 지원합니다.
+자동 통합은 Vite와 Next.js 프로젝트를 지원합니다. 다른 프레임워크나 설정 파일을
+자동으로 수정하고 싶지 않은 프로젝트에서는 아래의 `attach` 방식을 사용할 수 있습니다.
 
 ## 저장소에서 개발
 
@@ -79,6 +85,15 @@ node apps/cli/dist/index.js doctor
 
 `doctor`에서 Git 작업 트리, 현재 프로젝트 설정과 Codex 실행 환경을 확인합니다.
 
+Codex 작업 중 `pwd`, 버전 확인, 파일 읽기·검색과 read-only Git 명령은 Bridge가
+등록한 구조화 도구로 실행합니다. 이 경로는 명령을 `argv` 배열과 등록된 workspace
+`cwd`로 전달하고 `shell: false`로 실행하며, 지원되는 명령은 RTK로 자동 압축합니다.
+직접 실행기는 명령별 읽기 전용 문법만 허용하고 경로·symlink를 Git worktree 안으로
+제한하며, 타임아웃 시 하위 프로세스까지 종료합니다. 명령 소요 시간, RTK 사용,
+출력 축약 여부와 Codex가 제공하는 토큰 사용량은 작업 로그에 함께 기록됩니다.
+파일 수정, 테스트·빌드 또는 파이프처럼 셸 문법이 필요한 작업만 Codex의 sandbox
+명령 실행기로 보냅니다.
+
 ## 자동화 셸에서 Node.js 24 사용
 
 비대화형 셸은 `.zshrc`를 읽지 않을 수 있으므로 NVM을 명시적으로 불러와야 합니다.
@@ -98,7 +113,7 @@ corepack pnpm test
 ## 설정
 
 `init`은 명령을 실행한 현재 프로젝트 폴더에 설정을 생성합니다. 모노레포의 하위
-Vite 앱에서 실행하면 Git 루트가 아니라 해당 앱 폴더에 생성됩니다. 기존 설정은
+Vite 또는 Next.js 앱에서 실행하면 Git 루트가 아니라 해당 앱 폴더에 생성됩니다. 기존 설정은
 덮어쓰지 않습니다.
 
 ```yaml
@@ -156,8 +171,14 @@ paths:
     - dist/**
 ```
 
-Vite 플러그인이 개발 서버와 함께 내부 Bridge를 시작하고 종료합니다. `agent`,
-`verification`, `paths` 같은 상세 설정만 YAML에서 조정하면 됩니다.
+`project.workspace`, `paths.allowed`, `paths.denied`는 설정 파일이 가리키는 앱 workspace
+기준입니다. 모노레포의 `apps/web`에서 `init`했다면 `src/**`는
+`apps/web/src/**`로 안전하게 정규화되고 Codex의 기본 cwd도 `apps/web`이 됩니다.
+
+Vite 플러그인 또는 Next.js 설정 래퍼가 개발 서버와 함께 내부 Bridge를 시작합니다.
+`visual dev`가 Bridge를 먼저 소유한 경우 자식 Vite 플러그인은 runtime registry의
+gateway를 재사용하며, 개발 서버가 닫혀도 비소유 Bridge를 종료하지 않습니다.
+`agent`, `verification`, `paths` 같은 상세 설정만 YAML에서 조정하면 됩니다.
 
 ## 기존 attach 방식
 
@@ -167,13 +188,15 @@ Vite 플러그인이 개발 서버와 함께 내부 Bridge를 시작하고 종
 npx --yes visual-remote@latest http://localhost:9011
 ```
 
-이 방식은 별도 Gateway 주소를 열어 앱 전체를 프록시하므로 Origin에 민감한 API나
-쿠키가 있는 앱에는 권장하지 않습니다. Vite 프로젝트에서는 `init` 통합을 사용하고
-원래 앱 주소로 접속합니다.
+이 방식은 별도 Gateway 주소를 열어 앱 전체를 프록시합니다. 자동 통합을 사용할 수
+있는 Vite와 Next.js 프로젝트에서는 `init`을 사용하고 원래 앱 주소로 접속합니다.
+설정 파일을 변경하지 않거나 다른 프레임워크에 붙일 때는 `attach`를 사용합니다.
+업스트림에 연결된 뒤 연결 실패가 5초간 계속되면 `attach` Bridge도 자동 종료됩니다.
 
 ## 브라우저에서 변경 요청
 
-1. 평소 사용하는 앱 주소를 엽니다.
+1. 개발 서버가 출력한 `Pair:` 주소를 엽니다. 토큰은 URL fragment에서 즉시 제거되고
+   현재 탭의 sessionStorage에만 보관됩니다.
 2. `Command+Shift+G` 또는 `Ctrl+Shift+G`로 오버레이를 열고 닫습니다.
 3. 전체 작업 내역을 보려면 `작업 보드 ↗`를 눌러 별도 탭을 엽니다.
 4. 변경을 요청하려면 요소 하나, 여러 요소, 영역 또는 페이지 전체를 선택합니다.
@@ -181,9 +204,10 @@ npx --yes visual-remote@latest http://localhost:9011
 6. 진행 단계, 로그, 변경 파일, 차이와 검증 결과를 확인합니다.
 7. 변경을 유지하거나, 최신 작업을 되돌리거나, 후속 요청을 보냅니다.
 
-진행 패널의 `작업 숨기기`를 누르면 작업은 백그라운드에서 계속되고 다른 요소를
-선택해 다음 요청을 추가할 수 있습니다. `작업 보기`로 패널을 복원하고, 작업이
-끝난 뒤에는 `닫기`로 패널만 치울 수 있습니다. 작업 내역은 작업 보드에 남습니다.
+진행 패널의 `작업 최소화`를 누르면 작업은 백그라운드에서 계속되고, 현재 단계와
+원래 요청 내용은 작은 진행 바로 남습니다. 다른 요소를 선택해 다음 요청을 추가할 수
+있으며 `작업 펼치기`로 전체 패널을 복원합니다. 작업이 끝난 뒤에는 `닫기`로
+패널만 치울 수 있고 작업 내역은 작업 보드에 남습니다.
 
 작업 보드는 새 작업과 상태·로그·diff를 WebSocket으로 자동 갱신합니다. 보드에는
 별도의 읽기 전용 세션 토큰만 전달되므로 작업 생성, 취소, 유지 또는 되돌리기 API를
@@ -210,7 +234,7 @@ visual status
 visual doctor
 ```
 
-- `init`: 현재 Vite 앱에 개발 전용 통합을 설치합니다.
+- `init`: 현재 Vite 또는 Next.js 앱에 개발 전용 통합을 설치합니다.
 - `attach`: 기본 명령의 명시적 이름이며 기존 사용법과 호환됩니다.
 - `dev`: `init` 설정을 사용해 앱과 브리지를 함께 실행하는 선택 명령입니다.
 - `status`: 현재 Git 작업 트리의 브리지 실행 상태를 확인합니다.
@@ -231,6 +255,7 @@ corepack pnpm audit --prod
 - 단위 및 통합 테스트는 작업 큐, Git 스냅샷, Gateway, 에이전트와 검증 흐름을
   확인합니다.
 - 빌드는 브라우저 오버레이와 Node.js 명령줄 프로그램을 각각 생성합니다.
+- Pull request와 `main` push에서는 같은 테스트, 타입 검사와 빌드를 CI가 실행합니다.
 
 빌드 결과는 다음 위치에 생성됩니다.
 
@@ -239,6 +264,9 @@ packages/overlay/dist/client.js
 packages/overlay/dist/viewer.js
 apps/cli/dist/index.js
 apps/cli/dist/vite.js
+apps/cli/dist/next.js
+apps/cli/dist/next-client.js
+apps/cli/dist/direct-exec-mcp.js
 ```
 
 ## 저장소 구조
@@ -278,6 +306,7 @@ node --version
 
 ### 설정 파일 경고가 표시되는 경우
 
-Vite 앱의 `package.json`과 `vite.config`가 있는 폴더에서 `visual init`을 실행한 뒤
-`doctor`를 다시 실행합니다. 모노레포에서는 Git 루트가 아니라 실제 앱 폴더에서
-실행합니다.
+Vite 또는 Next.js 앱의 `package.json`이 있는 폴더에서 `visual init`을 실행한 뒤
+`doctor`를 다시 실행합니다. Vite는 `vite.config`, Next.js는 `next.config`와
+`instrumentation-client`가 구성되어야 합니다. 모노레포에서는 Git 루트가 아니라
+실제 앱 폴더에서 실행합니다.