<!-- task=07_node_command_ops_surface plan=0 tag=NCO -->

# 07 Node Command Ops Surface Plan - NCO

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

**필수: 구현 마지막에는 반드시 `CODE_REVIEW-*-G??.md`의 모든 섹션을 실제 구현 내용과 명령 출력으로 채운다.**
이 task는 ops console이 사용할 조회성 NodeCommand surface 확장을 다룬다.

## 배경

Edge-local ops console이 유지되면 `/status` 하나만으로는 부족하다. Capabilities, session list, transport/runtime 상태처럼 HTTP/API와 CLI가 같이 쓸 node command contract가 필요하다.

## 분석 결과

### 읽은 파일

- `agent-ops/skills/common/plan/SKILL.md`
- `agent-ops/rules/project/domain/edge/rules.md`
- `agent-ops/rules/project/domain/node/rules.md`
- `agent-ops/rules/project/domain/platform-common/rules.md`
- `proto/iop/runtime.proto`
- `apps/edge/internal/service/service.go`
- `apps/edge/internal/service/service_test.go`
- `apps/edge/internal/transport/server_test.go`
- `apps/node/internal/runtime/types.go`
- `apps/node/internal/node/node.go`
- `apps/node/internal/node/node_test.go`
- `apps/node/internal/transport/parser.go`
- `apps/node/internal/transport/parser_test.go`
- `apps/node/internal/adapters/cli/cli.go`

### 테스트 커버리지 공백

- `NodeCommandType`은 usage status만 테스트한다.
- unsupported command의 명시적 error 정책은 일부만 있다.
- capabilities/session/transport command 테스트가 없다.

### 심볼 참조

- `NodeCommandType`: `runtime.proto:83`.
- `BuildUsageStatusRequest`: `service.go:213`.
- `toDomainCommandRequest`: `node.go:231`.
- `toProtoCommandResponse`: `node.go:247`.
- `CommandTypeUsageStatus`: `types.go:107`.

### 범위 결정 근거

- 실제 control-plane 화면/API는 제외한다.
- session list는 adapter별 지원 가능 범위만 노출한다. 불가능한 adapter는 explicit unsupported를 반환한다.
- generated pb는 수동 편집하지 않는다.

### 빌드 등급

- Build `cloud-G09`: protobuf, edge service, node runtime, transport parser까지 걸친 계약 변경.
- Review `cloud-G09`: schema compatibility와 unsupported behavior 검토 필요.

### [NCO-1] NodeCommand schema 확장

#### 문제

`NodeCommandType`이 `USAGE_STATUS` 하나만 제공한다.

#### 해결 방법

- `NODE_COMMAND_TYPE_CAPABILITIES`
- `NODE_COMMAND_TYPE_SESSION_LIST`
- `NODE_COMMAND_TYPE_TRANSPORT_STATUS`
- Response에는 dedicated message 또는 metadata map 중 하나를 명확히 선택한다. 우선 metadata map으로 시작해도 된다.

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

- [ ] `proto/iop/runtime.proto`
- [ ] `proto/gen/iop/runtime.pb.go`
- [ ] edge/node transport parser tests

#### 테스트 작성

- `TestNodeParserMap_NodeCommandRequest_NewTypes`
- `TestEdgeParserMap_NodeCommandResponse_NewTypes`

#### 중간 검증

```bash
make proto
go test -count=1 ./apps/edge/internal/transport ./apps/node/internal/transport
```

### [NCO-2] Node runtime command mapping

#### 문제

Node maps only usage status to domain command.

#### 해결 방법

- `runtime.CommandType` constants를 확장한다.
- `toDomainCommandRequest`와 `toProtoCommandResponse` mapping을 확장한다.
- unsupported command는 empty success가 아니라 explicit error를 반환한다.

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

- [ ] `apps/node/internal/runtime/types.go`
- [ ] `apps/node/internal/node/node.go`
- [ ] `apps/node/internal/node/node_test.go`

#### 테스트 작성

- capabilities command success or explicit unsupported
- unspecified command explicit error

#### 중간 검증

```bash
go test -count=1 ./apps/node/internal/runtime ./apps/node/internal/node
```

### [NCO-3] Edge service와 opsconsole command 추가

#### 문제

Edge service exposes only `UsageStatus`.

#### 해결 방법

- Generic `SendNodeCommand` 또는 typed methods를 추가한다.
- opsconsole에 `/capabilities`, `/sessions`, `/transport` 같은 명령을 추가한다.
- unsupported 출력은 명확히 보여준다.

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

- [ ] `apps/edge/internal/service/service.go`
- [ ] `apps/edge/internal/service/service_test.go`
- [ ] `apps/edge/internal/opsconsole/console.go`
- [ ] `apps/edge/internal/opsconsole/console_test.go`
- [ ] `apps/edge/README.md`

#### 테스트 작성

- service command builder tests
- opsconsole command parser/render tests

#### 중간 검증

```bash
go test -count=1 ./apps/edge/internal/service ./apps/edge/internal/opsconsole
```

## 수정 파일 요약

| 파일 | 항목 |
|---|---|
| `proto/iop/runtime.proto` | NCO-1 |
| `proto/gen/iop/runtime.pb.go` | NCO-1 |
| `apps/edge/internal/transport/server_test.go` | NCO-1 |
| `apps/node/internal/transport/parser_test.go` | NCO-1 |
| `apps/node/internal/runtime/types.go` | NCO-2 |
| `apps/node/internal/node/node.go` | NCO-2 |
| `apps/node/internal/node/node_test.go` | NCO-2 |
| `apps/edge/internal/service/service.go` | NCO-3 |
| `apps/edge/internal/service/service_test.go` | NCO-3 |
| `apps/edge/internal/opsconsole/console.go` | NCO-3 |
| `apps/edge/README.md` | NCO-3 |

## 최종 검증

```bash
make proto
go test -count=1 ./apps/node/internal/runtime ./apps/node/internal/node ./apps/node/internal/transport ./apps/edge/internal/transport ./apps/edge/internal/service ./apps/edge/internal/opsconsole
go test -count=1 ./...
```

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