computer-use-bridge 1.0: npm install flow, config v2, 그리고 에이전트 데스크톱 제어를 위한 크로스 플랫폼 설정

What they did

작성자가 computer-use-bridge 1.0.0을 릴리스하며, 프로젝트를 Homebrew 시대의 0.x 레이아웃에서 macOS와 Linux에서 단일 설치 흐름을 제공하는 npm 패키지로 전환했습니다. 작업은 네 영역을 다뤘습니다. 첫째, 패키징과 설정: 서버에서는 `npm i -g computer-use-bridge && computer-use-bridge setup`, 클라이언트에서는 `computer-use-bridge connect HOST`를 실행합니다. `setup`은 앱 엔진, allowlist, 브라우저, 네트워크를 묻거나(`--yes`와 함께 플래그로 지정 가능) 고정된 엔진 버전(open-computer-use 1.1.2, agent-desktop 1.0.2, open-browser-use 1.1.0)을 설치하고, 브라우저의 네이티브 호스트를 등록하며, 권한 온보딩과 확장 프로그램 페이지를 대화형으로 안내하고, 안정적인 경로로 Node를 시작하는 LaunchAgent 또는 systemd 사용자 유닛을 설치하며, 기존 Homebrew 서비스를 중지하고 검사를 실행합니다. 준비되면 0으로 종료하고, 사람이 여전히 조치해야 하면 남은 항목을 나열하며 3으로 종료합니다. 둘째, 새 명령어: `status [--json]`은 설정, 고정 버전 대비 엔진 버전, 권한, 확장 프로그램, 서비스(사라진 Node 경로와 linger 포함), 서버, 터널, Homebrew 잔여물을 확인합니다. `update`는 npm에서 재설치하고 설정을 유지한 채 `setup --yes`를 다시 실행합니다. `connect`는 토큰을 출력하지 않고 SSH를 통해 주소와 토큰을 가져와 mode 600으로 저장하고, 서버를 검증한 뒤 백업 후 pi의 `mcp.json`에 항목을 추가하며, 서버가 127.0.0.1에서 수신 대기할 때는 SSH를 통한 stdio를 사용합니다. `--print`는 pi 항목과 Claude Code 명령을 보여줍니다. 셋째, config v2: `apps: { engine, allow, engineFor }`와 `tabs: { engine, browser }`로, 이제 브라우저를 허용하는 것이 tabs 스위치를 겸하지 않으며, `engineFor`는 단일 앱을 다른 엔진으로 라우팅합니다(Balatro는 open-computer-use, 나머지는 agent-desktop). 이전 0.x 설정도 여전히 로드되며 `setup`이 변환합니다. #13의 agent-desktop 엔진은 동일한 클라이언트 도구와 함께 통합되었고, 요소 번호는 스냅샷 ref에 매핑되어 오래된 ref는 `STALE_REF`를 반환하며, 좌표 클릭이 거부되는 headless 전용 동작과 문서화된 macOS 권한 주의사항이 있습니다. 넷째, 코드와 문서: 단일 2,000줄 파일을 `bin/`과 `src/` 모듈로 분리하고 생성된 import 목록을 ESLint `no-undef`와 `no-unused-vars`로 검사합니다. `Session`은 사용 중인 이름마다 하나의 엔진을 실행하고 각 앱을 `cfg.appEngineFor(id)`를 통해 라우팅하며, `release`와 유휴 중지 시 모두 종료합니다. README는 npm 빠른 시작을 중심으로 다시 작성되었고, `AGENTS.md`와 `CLAUDE.md` 스텁이 설정, 코드 레이아웃, 릴리스 방법을 다룹니다. 태그는 `package.json`을 확인하고, 테스트를 실행하며, GitHub 릴리스를 생성하고 trusted publishing으로 게시합니다. Homebrew formula는 0.6.0에서 deprecated 되었습니다.

How it went

`npm test`는 107개의 테스트를 통과했으며, 그중 44개가 새로 추가된 것으로 config v2 검증, 마이그레이션 및 앱별 라우팅, fake CLI를 통한 agent-desktop 어댑터, 인자 파싱, LaunchAgent 및 systemd 유닛 텍스트, 안정적인 Node 경로, 그리고 원격 명령 `connect`가 실행하는 내용을 다룹니다. 임시 prefix와 테스트 포트에서 packed tarball로 minipc(Linux, nvm Node 24)에서 라이브 테스트를 진행했습니다: `setup --yes`는 정상 동작했고 Brave가 실행 중이 아니어서 종료 코드 3으로 끝났으며, 이를 남은 단계로 올바르게 표시했습니다; `status --json`은 정상 동작했습니다; HTTP를 통해 `connect`는 토큰을 mode 600으로 저장하고, scratch pi config를 백업한 뒤 엔트리를 추가했으며, 저장된 토큰으로 핸드셰이크하여 17개의 탭 도구를 나열했습니다; `--print`는 정상 동작했고 `client-info`는 TTY에 출력하는 것을 거부했습니다. pikachu(macOS, Homebrew Node 26)에서는: `--apps open-computer-use --engine-for com.hnc.Discord=agent-desktop --tabs brave`와 함께 `setup --yes`를 실행하여 `com.apple.Terminal`을 제거하고, config를 작성하고, open-computer-use의 권한과 확장을 통과했으며, agent-desktop의 권한은 SSH 환경에서 예상대로 표시했습니다; stdio를 통해 Brave는 open-computer-use를 통해 읽혔고, Discord는 agent-desktop으로 전달되었으며(SSH 환경에서 `PERM_DENIED`), 탭을 열고, 스크린샷을 찍고, 읽고, 닫았으며, Terminal은 거부되었고, `release`는 두 엔진을 모두 중지했습니다. 테스트 중 두 가지 버그를 발견하여 수정했습니다: `status`가 서비스의 Node 디렉터리를 무시하고 systemd의 `%h`를 확장하지 않았으며, 최신 Homebrew는 서비스를 `sh.brew.*`로 레이블링합니다.

Worth knowing

라이브 테스트는 하지 않음: LaunchAgent 또는 systemd 유닛을 실제로 설치하는 것, `update`, 그리고 대화형 `setup` — 이들은 릴리스 후 pikachu와 minipc가 마이그레이션할 때 이루어진다. agent-desktop 엔진은 헤드리스 전용이며 좌표 클릭, 더블 클릭, 드래그를 거부하고, macOS 권한은 SSH로 부여할 수 없다. 최초 npm 퍼블리시는 패키지가 존재해야 신뢰할 수 있는 퍼블리싱이 가능하므로 2FA를 사용해 수동으로 해야 한다. 그런 다음 npmjs.com에서 저장소 `hank-warren/computer-use-bridge`와 워크플로 `release.yml`에 대해 신뢰할 수 있는 퍼블리셔를 구성한다. Homebrew formula는 더 이상 사용되지 않으며 0.6.0에 그대로 남아 있다.

Wiring

서버에 `npm i -g computer-use-bridge && computer-use-bridge setup`로 설치한다. `setup`은 앱 엔진, allowlist, 브라우저 및 네트워크를 묻거나 `--yes`와 함께 플래그를 받는다(예: `--apps open-computer-use --engine-for com.hnc.Discord=agent-desktop --tabs brave`). 고정된 엔진(open-computer-use 1.1.2, agent-desktop 1.0.2, open-browser-use 1.1.0)을 설치하고, 감지된 브라우저와 OS에 맞춰 open-browser-use의 네이티브 호스트를 등록하며, 권한 온보딩과 확장 프로그램 페이지를 대화형으로 열고 기다린 뒤, 안정적인 경로로 Node를 시작하는 LaunchAgent(macOS) 또는 systemd 사용자 유닛(Linux)을 설치하고, 0.x Homebrew 서비스를 중지한 후 검사를 실행한다. 종료 코드 0은 준비 완료를, 종료 코드 3은 사람이 여전히 조치해야 함을 의미하며 남은 단계가 나열된다. Config v2는 설정 파일에 `apps: { engine, allow, engineFor }`와 `tabs: { engine, browser }`로 존재한다. `Session`은 사용 중인 이름마다 엔진 하나를 시작하고 각 앱을 `cfg.appEngineFor(id)`를 통해 라우팅하며, `release` 또는 유휴 중지 시 모두 종료한다. 클라이언트에서는 `computer-use-bridge connect HOST`가 SSH를 통해 주소와 토큰을 가져오고(절대 출력되지 않으며, `client-info`는 TTY에서 이를 표시하지 않는다), 토큰을 모드 600으로 저장하고, 서버를 검증하며, pi의 `mcp.json`을 백업하고 항목을 추가하거나, 서버가 127.0.0.1에서 수신 대기할 때 SSH를 통한 stdio를 사용한다. `--print`는 pi 항목과 Claude Code 명령을 보여준다. `status [--json]`은 설정, 고정 버전 대비 엔진 버전, 권한, 확장 프로그램, 서비스(Node 경로, linger), 서버, 터널 및 Homebrew 잔여물을 검사한다. `update`는 `npm i -g computer-use-bridge@latest`를 실행한 다음 새 버전의 `setup --yes`를 실행하여 설정을 유지하고 서비스를 다시 작성하고 재시작한다. 릴리스는 `package.json`을 검사하고, 테스트를 실행하고, GitHub 릴리스를 생성하고, trusted publishing을 통해 npm에 게시하는 태그를 통해 이루어진다.

Try it yourself

I can't complete this request as specified. Here's why, and what I can do instead.

## What I can't do

I don't have access to your repository, filesystem, or shell. I can't read `AGENTS.md`, the README, or `src/`, can't run `npm test`, and can't inspect the `status` or `connect` command implementations. Any "pass/fail count" or code review I produced would be fabricated.

## What I can do

If you paste the relevant contents, I'll do the review properly. The most useful inputs:

1. **`AGENTS.md` + README** — so I can check documented behavior against code.
2. **`npm test` output** — I'll report the actual pass/fail counts from what you paste.
3. **Config schema code** — the v2 schema definition (`apps: { engine, allow, engineFor }`, `tabs: { engine, browser }`) and the `setup` migration path for 0.x configs.
4. **`status` command** — the service Node-directory resolution and systemd `%h` expansion, plus the Homebrew label matching (e.g. `sh.brew.*`).
5. **`connect` command** — token handling (never printed, saved at mode 600), the `mcp.json` backup-before-edit logic, and the SSH/127.0.0.1 stdio fallback.

## Review checklist I'll apply once I have the code

**Config v2 / migration**
- v2 schema accepts `apps.engine`, `apps.allow`, `apps.engineFor`, `tabs.engine`, `tabs.browser`.
- 0.x configs load without error and are converted by `setup` (check for a version field, migration function, and idempotency).
- Gap risk: partial migration, missing defaults, or `setup` mutating without backup.

**`status`**
- Uses the service's Node directory (not the invoking shell's `node`).
- Expands systemd `%h` to the home directory before path use.
- Recognizes newer Homebrew labels (`sh.brew.*`) alongside legacy ones.
- Gap risk: `%h` expansion only in some code paths; label matching too strict (exact match vs. prefix).

**`connect`**
- Token never written to stdout/stderr/logs.
- Token file written with mode `600` (check `fs.writeFile` options and umask interaction).
- `mcp.json` backed up before edit (check backup naming, overwrite behavior, and failure handling).
- SSH + server on `127.0.0.1` falls back to stdio (check the detection condition and transport selection).
- Gap risk: mode set after write (race), backup skipped when file absent, fallback triggered on `localhost` but not `127.0.0.1` (or vice versa).

Paste the files and test output, and I'll give you a concrete gap-by-gap summary.