<!-- task=03+node_setup_cli plan=1 tag=NODECLI-FOLLOWUP -->

# Node Setup CLI Follow-up Plan

## 이 파일을 읽는 구현 에이전트에게

**구현 마지막 단계에서 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채우는 것은 필수다. 이 파일을 채우기 전에는 작업이 완료된 것이 아니다.** 구현 체크리스트를 기준으로 작업하고 리뷰 스텁을 채워라. 리뷰 파일의 아카이브 지시와 `코드리뷰 전용 체크리스트`는 리뷰 에이전트 전용이다.

## 배경

`plan=0` 구현은 node `config check`와 `setup` 기능 자체는 동작하지만, 코드리뷰에서 WARN 3개가 남았다.

- `iop-node setup --help`가 Global `--config` 기본값을 `configs/node.yaml`로 표시해 실제 setup 기본값(`/etc/iop/node.yaml`)과 충돌한다.
- `docs/architecture.md`에 `iop-node setup`이 아직 `03+node_setup_cli 구현 예정`으로 남아 있다.
- `apps/*/cmd/**` 변경 후 요구되는 `bin/edge.sh` + `bin/node.sh` 기반 사용자 흐름 검증 기록이 없다.

이번 follow-up은 위 WARN을 닫는 데만 집중한다. 새 node 기능, edge CLI 기능, hostsetup 동작 확장은 범위에 넣지 않는다.

## 의존 관계 및 구현 순서

- 선행 로그: `agent-task/03+node_setup_cli/plan_cloud_G07_0.log`, `agent-task/03+node_setup_cli/code_review_cloud_G07_0.log`
- 구현 대상은 node CLI help/default 정리, node setup 관련 문서 정리, 검증 기록 보강이다.
- `packages/hostsetup`은 기존 동작 검증 대상으로만 포함한다. 새 동작을 추가하지 않는다.

## 분석 결과

### 읽은 파일

- `agent-ops/rules/project/rules.md`
- `agent-ops/rules/project/domain/node/rules.md`
- `agent-ops/rules/project/domain/platform-common/rules.md`
- `agent-ops/rules/project/domain/testing/rules.md`
- `agent-task/03+node_setup_cli/plan_cloud_G07_0.log`
- `agent-task/03+node_setup_cli/code_review_cloud_G07_0.log`
- `apps/node/cmd/node/main.go`
- `apps/node/cmd/node/main_test.go`
- `apps/node/README.md`
- `docs/architecture.md`
- `docs/deploy-dev.md`
- `packages/hostsetup/setup.go`
- `packages/hostsetup/setup_test.go`

### 리뷰 WARN 대응

| WARN | 대응 |
|---|---|
| setup help의 `--config` 기본값 불일치 | node CLI의 config 기본값 표시와 실제 command별 기본값을 일치시킨다. |
| architecture 문서의 구현 예정 잔재 | `docs/architecture.md`를 현재 구현 상태로 갱신한다. |
| bin shell 사용자 흐름 검증 누락 | `bin/edge.sh` + `bin/node.sh` 기반 검증을 실제 수행하거나, 수행 불가 시 명확한 blocker와 남은 위험을 기록한다. |

### 구현 방향

`setup --help`에서 거짓 기본값을 노출하지 않도록 node CLI의 config 기본값 처리 방식을 정리한다. 권장 방향은 root persistent `--config`의 기본 문자열을 비워 두고, command 실행 시점에 다음 기본값을 적용하는 것이다.

- `serve`, `config print`, `config check`: config가 비어 있으면 `configs/node.yaml`
- `setup`: config가 비어 있으면 `hostsetup.NodeSpec().DefaultConfig`(`/etc/iop/node.yaml`)
- 명시적 `--config`는 root 위치(`node --config X setup`)와 subcommand 뒤 위치(`node setup --config X`) 모두 기존처럼 동작해야 한다.

구현 중 cobra flag shadowing 같은 대안을 선택할 수는 있지만, 최종적으로 `go run ./apps/node/cmd/node setup --help`가 `configs/node.yaml`을 setup 기본값처럼 보여주면 안 된다.

## 구현 체크리스트

- [ ] [NODECLI-FOLLOWUP-1] node `setup --help`의 config 기본값 표시와 실제 setup 기본값을 일치시킨다.
- [ ] [NODECLI-FOLLOWUP-2] node setup 관련 architecture 문서 잔재를 현재 구현 상태로 갱신한다.
- [ ] [NODECLI-FOLLOWUP-3] testing domain rule 기준 검증을 실행하고 수행 여부/출력을 기록한다.
- [ ] 중간 검증과 최종 검증 명령을 실행하고 실제 출력을 기록한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

### [NODECLI-FOLLOWUP-1] node `setup --help`의 config 기본값 표시와 실제 setup 기본값을 일치시킨다

#### 문제

`apps/node/cmd/node/main.go`의 root persistent `--config` 기본값은 `configs/node.yaml`이다. `setup` 실행은 내부에서 `/etc/iop/node.yaml`로 보정하지만, `setup --help`는 Global Flag 기본값으로 `configs/node.yaml`을 보여준다.

#### 해결 방법

- command별 config 기본값 helper를 추가한다.
- `serve`, `config print`, `config check`는 dev 기본값을 유지한다.
- `setup`은 operation 기본값을 유지한다.
- help 출력 테스트를 추가해 `setup --help`에 `default "configs/node.yaml"`가 나오지 않도록 고정한다.
- explicit config 테스트는 root 위치와 subcommand 뒤 위치를 모두 확인한다.

#### 수정 파일 및 체크리스트

- [ ] `apps/node/cmd/node/main.go` 수정.
- [ ] `apps/node/cmd/node/main_test.go` 수정.

#### 테스트 작성

- `TestSetupHelpDoesNotAdvertiseDevConfigDefault`
- `TestConfigCheckUsesNodeDevDefault`
- `TestSetupDryRunAcceptsExplicitConfigBeforeSubcommand`
- `TestSetupDryRunAcceptsExplicitConfigAfterSubcommand`

#### 중간 검증

```bash
gofmt -w apps/node/cmd/node
go test -count=1 ./apps/node/cmd/node
go run ./apps/node/cmd/node setup --help
go run ./apps/node/cmd/node config check
go run ./apps/node/cmd/node setup --dry-run --binary /usr/local/bin/iop-node
go run ./apps/node/cmd/node --config /tmp/node.yaml setup --dry-run --binary /usr/local/bin/iop-node
go run ./apps/node/cmd/node setup --config /tmp/node.yaml --dry-run --binary /usr/local/bin/iop-node
```

### [NODECLI-FOLLOWUP-2] node setup 관련 architecture 문서 잔재를 현재 구현 상태로 갱신한다

#### 문제

`docs/architecture.md`가 구현 이후에도 `iop-node setup`을 `03+node_setup_cli 구현 예정`으로 설명한다.

#### 해결 방법

- `docs/architecture.md`의 node setup 상태를 현재 구현 완료 상태로 갱신한다.
- `docs/deploy-dev.md`와 `apps/node/README.md`의 node setup 설명과 충돌하지 않는지 확인한다.

#### 수정 파일 및 체크리스트

- [ ] `docs/architecture.md` 수정.
- [ ] 필요 시 `docs/deploy-dev.md`, `apps/node/README.md` 문구 정합성만 최소 수정.

#### 중간 검증

```bash
rg --sort path -n "03\\+node_setup_cli|구현 예정" docs apps/node/README.md
rg --sort path -n "service install|service status|\\brender\\b" docs apps/node/README.md
```

첫 번째 명령은 출력이 없어야 한다. 두 번째 명령은 금지 명령이 공식 경로로 소개되지 않는지 확인하고, 출력이 있으면 모두 금지 문맥인지 CODE_REVIEW에 기록한다.

### [NODECLI-FOLLOWUP-3] testing domain rule 기준 검증을 실행하고 수행 여부/출력을 기록한다

#### 문제

`apps/node/cmd/node/**` 변경은 사용자 실행 파이프라인에 닿는 변경으로 분류된다. `testing` domain rule은 일반 Go 테스트뿐 아니라 `bin/edge.sh` + `bin/node.sh` 기반 bin shell 사용자 흐름 검증 수행 여부를 요구한다.

#### 해결 방법

- 일반 Go 테스트와 직접 CLI 실행 검증을 수행한다.
- `bin/edge.sh`와 `bin/node.sh`를 별도 프로세스로 실행해 edge console에서 메시지 2회와 command 응답을 확인한다.
- 수행이 불가능하면, 단순 생략하지 말고 정확한 blocker와 남은 위험을 CODE_REVIEW에 기록한다.

#### 검증 체크리스트

- [ ] `go test ./...`
- [ ] `bin/edge.sh` + `bin/node.sh`를 직접 실행한다.
- [ ] edge console에서 `/nodes` 확인.
- [ ] edge console에서 같은 session으로 메시지 2회를 보내고 각 요청의 `[edge] sent`, `[node-*-event] start`, 비어 있지 않은 `[node-*-message]`, `[node-*-event] complete`를 확인.
- [ ] edge console에서 `/capabilities`, `/transport`, `/sessions`를 확인.
- [ ] persistent profile이면 `/terminate-session`도 확인.
- [ ] 보조 smoke를 실행했다면 `make test-e2e` 또는 사용한 명령과 출력을 별도 기록. 단, 보조 smoke만으로 완료 처리하지 않는다.

## 수정 파일 요약

| 파일 | 항목 |
|---|---|
| `apps/node/cmd/node/main.go` | NODECLI-FOLLOWUP-1 |
| `apps/node/cmd/node/main_test.go` | NODECLI-FOLLOWUP-1 |
| `docs/architecture.md` | NODECLI-FOLLOWUP-2 |
| `docs/deploy-dev.md` | NODECLI-FOLLOWUP-2 필요 시 |
| `apps/node/README.md` | NODECLI-FOLLOWUP-2 필요 시 |
| `agent-task/03+node_setup_cli/CODE_REVIEW-cloud-G07.md` | NODECLI-FOLLOWUP-3 |

## 최종 검증

```bash
gofmt -w apps/node/cmd/node
gofmt -l apps/node/cmd/node packages/hostsetup
go test -count=1 ./apps/node/cmd/node ./packages/hostsetup
go test ./...
go run ./apps/node/cmd/node setup --help
go run ./apps/node/cmd/node config check
go run ./apps/node/cmd/node setup --dry-run --binary /usr/local/bin/iop-node
go run ./apps/node/cmd/node --config /tmp/node.yaml setup --dry-run --binary /usr/local/bin/iop-node
go run ./apps/node/cmd/node setup --config /tmp/node.yaml --dry-run --binary /usr/local/bin/iop-node
rg --sort path -n "03\\+node_setup_cli|구현 예정" docs apps/node/README.md
rg --sort path -n "service install|service status|\\brender\\b" docs apps/node/README.md
```

추가로 `testing` domain rule의 bin shell 사용자 흐름 검증을 수행하고, 실제 stdout/stderr 또는 blocker를 `CODE_REVIEW-cloud-G07.md`에 기록한다.

모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.
