# aipctl 통합 CLI 구조

`desktop/packages/cli`는 npm package `aipctl`의 source of truth입니다.

- public bin: `aipctl`
- entrypoint: `build/index.cjs`
- root CLI: TypeScript/Effect (`src/`)
- native MCP commands: Go (`go/`), `install`/`run`/`tunnel`/`logs`
- platform optional package resolver: `binary.cjs`

## Source tree

```text
desktop/packages/cli/
├── src/
│   ├── index.ts              # composition root, help pre-hooks, Command.run(name: aipctl)
│   ├── command-tree.ts       # AIP commands + native top-level commands
│   ├── build-info.ts         # AIPCTL_VERSION / AIPCTL_BUILD_ENV
│   ├── native/               # Go binary bridge, user-facing namespace 아님
│   ├── commands/             # AIP command handlers
│   │   └── admin/            # admin-only command namespaces 포함
│   ├── core/                 # config/credentials/OAuth/API/rate-limit
│   └── help/                 # custom group help renderer
├── go/                       # 기존 Go MCP CLI source
├── scripts/                  # publish and smoke helpers
├── binary.cjs
├── platforms.json
└── package.json
```

## Runtime flow

```text
사용자
  └─ aipctl (build/index.cjs)
      ├─ AIP command → Effect command handler → core ApiService/Config/Credential
      └─ native command → src/native bridge → binary.cjs lazy resolve → Go aipctl binary
```

## Native bridge rules

- `AIPCTL_NATIVE_BINARY`가 있으면 그 경로를 우선 사용합니다.
- 없으면 `build/index.cjs` 기준 `../binary.cjs`를 lazy require해 optional platform package를 찾습니다.
- native command 실행 시점에만 binary resolver를 호출합니다.
- `stdio: "inherit"`, `env: process.env` 정책을 유지합니다.
- `run --help`, `tunnel --help`, `tunnel link --help`는 Effect help보다 먼저 Go help로 위임합니다.
- `prod` build에서는 `logs`를 command tree와 native help hook에서 제외합니다.

## Command ownership

- TypeScript root command: `aipctl`
- AIP user workflows: `auth`, `config`, `org`, `skill`, `agent`, `automation`, `chat`, `drive`, `integration`, `model`
- AIP admin workflows: `admin org|agent|integration|skill|preset|usage|audit|tunnel`
- Go native workflows: `install`, `run`, `tunnel`, `logs` (`prod` 제외)

`aipctl admin tunnel ...`은 AIP admin command입니다. `aipctl tunnel ...`은 native Go MCP command입니다.

## Build/version

- package base version: `0.0.0`
- publish-time CalVer가 `AIPCTL_VERSION`으로 TS bundle과 Go ldflags에 주입됩니다.
- `AIPCTL_BUILD_ENV`는 `local|dev|stage|prod|test` 중 하나이며 `logs` gating에 사용됩니다.

## Dependency direction

```text
src/index.ts
  → command-tree.ts
    → commands/*
      → core/*
  → native/*
    → binary.cjs (lazy runtime only)
```

`core/`는 command를 몰라야 합니다. native bridge는 user-facing namespace가 아니라 Go binary adapter입니다.