connectbase-client 0.15.1 → 0.16.1

package/CHANGELOG.md

@@ -0,0 +1,157 @@
+# Changelog
+
+본 SDK 의 모든 주요 변경사항을 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/) 형식으로 기록합니다.
+버전은 [Semantic Versioning](https://semver.org/lang/ko/) 을 따릅니다.
+
+## [0.16.1] - 2026-04-17
+
+MCP/SDK 문서-코드 정합성 검증에서 발견된 불일치 소규모 정정. 런타임 동작 변경은 없으며, 이전 릴리스에서 도입된 타입 회귀를 롤백.
+
+### Fixed
+
+- **`FetchDataResponse` 필드명 회귀 롤백**: `0.16.0` 에서 `datas→data`, `total_size→total_count` 로 바꿨으나 실제 서버 wire 는 여전히 `datas` / `total_size` 였음. 타입 정의를 서버 응답 그대로 `{ datas, total_size }` 로 되돌려 런타임 미스매치 제거.
+- `cb.push.subscribeTopic()` JSDoc 예제가 `device_token` 인자 누락된 구 시그니처로 표기되던 문제 정정 (실 시그니처는 `subscribeTopic(deviceToken, topic)`).
+- CLI 안내 문구·`setupMonorepoRoot` 로 추가되는 `cb:update`/`cb:docs`/`cb:mcp` 스크립트가 `connectbase-client` 를 가리키던 것을 정규 bin 이름인 `connectbase` 로 통일. 두 bin 은 모두 동작하지만 문서와 자동 생성 스크립트는 단일 이름 기준으로 일관화.
+
+### Documentation
+
+- README `### Push Notifications` 섹션의 예제를 실제 공개 API 와 일치하도록 수정: `push.register()` / `push.subscribeToTopic()` / `push.unsubscribeFromTopic()` (존재하지 않는 메서드) → `push.registerDevice()` / `push.subscribeTopic(deviceToken, topic)` / `push.unsubscribeTopic(deviceToken, topic)` / Web Push 등록 예제 추가.
+
+### Changed
+
+- `package.json` 메타데이터 보강: `author`, `homepage`, `bugs`, `sideEffects: false` 필드 추가, `files` 에 `LICENSE`/`CHANGELOG.md`/`README.md` 명시적 포함.
+- 저장소 루트에 `LICENSE` (MIT) 파일 신설 (이전에는 `license: "MIT"` 선언만 존재).
+
+## [0.16.0] - 2026-04-17
+
+CLI `update` 커맨드와 신규 저장소 API 옵션, 토큰 영속성 옵션 추가. 일부 타입 정정.
+
+### Added
+
+- **CLI `update` 커맨드**: 현재 설치된 `connectbase-client` 버전을 npm 과 비교하고 `docs`·`mcp` 산출물을 일괄 최신화.
+- **모노레포 지원**: `connectbase init --setup-root` 로 모노레포 루트 `package.json` 에 `cb:update`/`cb:docs`/`cb:mcp` 편의 스크립트 설치.
+- **Storage `getFiles()` `parentId` 옵션**: 특정 폴더 하위 파일 목록 조회 지원.
+- **토큰 영속성(persistence) 옵션**: `new ConnectBase({ persistence: 'localStorage' | 'sessionStorage' | 'none' })`.
+  - `localStorage` (기본값): 브라우저 종료 후에도 토큰 유지.
+  - `sessionStorage`: 탭 종료 시 삭제.
+  - `none`: 메모리에만 저장.
+  - 생성자에서 저장된 토큰 자동 복원 (명시적 토큰 전달 시 스킵). SSR 환경(`window` undefined) 안전 처리.
+- **OAuthProvider 확장**: `kakao`, `apple` 프로바이더 추가 (서버 enum 과 동기화).
+
+### Changed
+
+- `VERSION` 상수가 `package.json` 에서 동적으로 로드되도록 변경 (이전: `0.10.6` 하드코딩).
+- `FetchDataResponse` 필드명 변경: `datas` → `data`, `total_size` → `total_count` (서버 응답과 일치를 의도함).
+  - **⚠️ 본 변경은 실제 서버 wire 와 맞지 않는 회귀였으며 `0.16.1` 에서 롤백됩니다.** `0.16.0` 사용자는 `0.16.1` 이상으로 즉시 업그레이드 권장.
+
+### Documentation
+
+- SDK 문서 전체 감사 및 누락 섹션 보강.
+
+## [0.15.0] - 2026-04-16
+
+Web Analytics SDK 모듈 신설 및 터널 유틸 리팩터.
+
+### Added
+
+- **AnalyticsAPI** 모듈 (`cb.analytics`): `init` / `trackEvent` / `trackPageView` / `identify` / `setConsent` / `enableHeatmap` / `enableHeartbeat` / `destroy`.
+- **SessionManager**: 30분 타임아웃, `visitor_uid` localStorage 영속화.
+- 백엔드 측 12개 서비스·9개 Ent 스키마(이벤트/퍼널/세션/코호트/어트리뷰션/세그먼트/A-B 테스트/히트맵/녹화/프라이버시) 와 매칭.
+
+### Changed
+
+- CLI 내부에서 tunnel 관련 로직을 `src/tunnel-utils.ts` 로 추출 (테스트 용이성 확보).
+- `vitest` 도입 및 tunnel/analytics 단위 테스트 23건 추가.
+
+## [0.14.0] - 2026-04-15
+
+Tunnel 안정성 개선.
+
+### Added
+
+- **Tunnel lockfile**: 앱+포트 기반 lockfile 로 동일 터널 중복 실행을 차단. stale lockfile 자동 감지(PID 생존 확인).
+- `--force` 플래그: lockfile 무시 옵션.
+
+### Changed
+
+- 서버의 `tunnel_error code=replaced` 수신 시 재연결을 중단하고 안내 메시지 출력 (이전에는 끊임없이 재연결 시도).
+- `TunnelMessage` 타입에 `code` / `error` / `message` 필드 추가.
+
+## [0.13.0] - 2026-04-14
+
+Database API 정합성 및 완성도 대규모 개선.
+
+### Breaking Changes
+
+- **`TableSchema` 응답 구조 전면 재정의**: 서버 ent 모델 (`backend/cmd/data-server/ent/schema/table.go`) 과 1:1 일치하도록 변경.
+  - `name` → `title`
+  - `columns: ColumnSchema[]` → `schema: TableSchemaDefinition` (평면 또는 중첩 맵)
+  - `created_at` → `create_time` (※ G2 작업에서 다시 `created_at` 로 표준화 예정)
+  - `updated_at` → `update_time`
+  - 신규 필드: `app_id`, `access_level`, `is_active`, `validation_schema?`
+- **`CreateTableRequest` 형태 변경**: 서버 DTO 와 일치.
+  - `schema?: TableSchemaDefinition` 신규 필드. 평면 맵 (`{email: 'string'}`) 또는 중첩 객체 (`{email: {type: 'string', required: true}}`) 모두 지원. `$required` 키로 필수 컬럼 지정.
+  - `accessLevel?: 'Creator' | 'Public' | 'AppMember'` (기본 `'Creator'`)
+  - `description` 은 `@deprecated` — 서버에 저장되지 않음
+- **`createTable()` 반환 타입**: `Promise<TableSchema>` → `Promise<void>`. 서버는 `{message}` 만 반환하므로 거짓 타입 제거.
+- **`createColumn()` / `updateColumn()` 반환 타입**: 동일한 이유로 `Promise<void>` 로 변경.
+- **`updateTable()` 시맨틱 정정**: PATCH 부분 업데이트가 정상 동작. 이전 버전에서는 모든 필드가 required 라 부분 업데이트 시 400 오류가 발생했음.
+- **`DataType` 정렬**: 서버 `ValidSchemaTypes` 와 일치하도록 변경.
+  - 제거: `'boolean'`
+  - 추가: `'int'`, `'bool'`, `'uuid'`
+  - 최종 union: `'string' | 'int' | 'number' | 'bool' | 'uuid' | 'date' | 'object' | 'array'`
+- **`CreateColumnRequest`**:
+  - `is_required` 가 optional 로 변경 (기본 false)
+  - `default_value` 타입 `string` → `unknown` (서버는 임의 타입 허용)
+  - `order`, `validation_rule` 은 `@deprecated` (서버 미지원)
+- **`UpdateColumnRequest`**:
+  - `default_value` 타입 `string` → `unknown`
+  - `name` `@deprecated` (서버는 컬럼 rename 미지원)
+  - `order`, `validation_rule` `@deprecated`
+- **`ColumnSchema`**:
+  - SDK 가 합성하는 객체임을 명시
+  - `default_value` 타입 `string` → `unknown`
+  - `created_at` 은 테이블의 `create_time` 으로 대체 (컬럼 개별 타임스탬프 없음)
+  - `order` 는 SDK 가 부여한 인덱스
+  - `updated_at`, `validation_rule` `@deprecated`
+
+### Added
+
+- `TableSchemaDefinition` interface — 컬럼 정의 맵 타입. 플랫 / 중첩 / `$required` 모두 지원.
+- `TableColumnDef` union type — 단일 컬럼 정의 (플랫 string 또는 중첩 객체).
+- `TableAccessLevel` type — `'Creator' | 'Public' | 'AppMember'`.
+- `database.createTable()` 가 초기 schema 와 access level 을 한 번에 받아 1-step 생성 지원.
+- `database.getColumns()` 가 플랫 / 중첩 schema 모두 정확히 파싱.
+- `database` 모듈의 `getPublicPrefix()` 가 항상 `/v1/public` 반환 (이전: 인증 종류에 따라 `/v1/public` 또는 `/v1` — 후자는 dead path).
+- `database.getValidationSchema()`, `setValidationSchema()`, `deleteValidationSchema()` — 테이블 검증 스키마 CRUD.
+- `MemberInfoResponse` 에 `email?`, `role?` 필드 추가 — RLS `auth.email`/`auth.role` 과 일치.
+- MCP `update_column` 툴 신설 (description, encrypted, data_type, is_required, default_value 변경).
+- MCP `get_validation_schema`, `set_validation_schema`, `delete_validation_schema` 툴 신설.
+
+### Fixed
+
+- **🔴 `database.createTable()` 가 어떤 키로도 동작하지 않던 broken 상태 해결**.
+  - Public Key 경로: 요청 body 가 서버 DTO 와 불일치 (필드명 `name`/`title`, 누락 `access_level`, 빈 `schema`)
+  - Secret Key 경로: 존재하지 않는 `/v1/tables` 경로 호출 → 404
+  - 두 경로 모두 본 릴리스에서 정상 동작.
+- **MCP `create_table` 툴이 빈 schema 거부로 항상 실패** 하던 문제 해결 (서버 hook 이 explicit 빈 맵을 거부했음). 서버 DTO/repository/MCP tool 세 곳을 동시에 수정.
+- 서버 측 `CreateTableRequest.Schema` 가 `binding:"required"` 였으나 schema 생략 가능하도록 변경.
+- 서버 측 `EditTableInternal` (PATCH) 가 full-replace 시맨틱이라 부분 업데이트 불가능했던 문제 해결. `PatchTableRequest` DTO 와 `PatchTable` repository 메서드 신설.
+- MCP `create_column`, `update_column` 툴의 `data_type` enum 이 `'boolean'` 을 포함했으나 서버는 `'bool'` 만 허용 → 정정.
+- `getColumns()` 가 플랫 schema (`"email": "string"`) 를 모두 `'string'` 으로 잘못 반환하던 문제 해결.
+
+### Documentation
+
+- `secretKey` 의 JSDoc 명확화: 앱 DB API 에는 사용 불가, CLI / tunnel 전용임을 명시.
+- embedded SDK 문서 (04-sdk-database.md, 11-mcp-tools.md, 25-app-packaging.md) 의 `boolean` → `bool`, `auth.email`/`auth.role` 정합성 정리, `createTable` 예제 갱신.
+- `TableSchemaDefinition` 의 `$required` 키 사용법, `TableColumnDef` 평면/중첩 형태 모두 JSDoc 예제 포함.
+
+### Notes
+
+본 변경의 대부분은 backwards-incompat 이지만, 이전 버전 (`0.12.x`) 의 `createTable` 자체가 broken 상태였으므로 해당 메서드를 사용하던 코드는 어차피 동작하지 않았습니다. read 메서드 (`getTables`, `getTable`, `getColumns`) 는 사용자 코드가 escape-hatch 캐스팅 (`as any`) 으로 우회하던 경우만 영향받습니다.
+
+---
+
+## [0.12.2] - 2026-04-?? (이전)
+
+이전 릴리스 — 본 CHANGELOG 도입 이전. git history 참조.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Connect Base
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -89,7 +89,7 @@ Deploy your web application to Connect Base Web Storage with a single command.
 
 ```bash
 # 1. Initialize (one-time setup)
-npx connectbase-client init
+npx connectbase init
 
 # 2. Deploy
 npm run deploy
@@ -115,7 +115,7 @@ The `init` command will:
 If you prefer not to use `init`, you can pass options directly:
 
 ```bash
-npx connectbase-client deploy ./dist -s <storage-id> -k <public-key>
+npx connectbase deploy ./dist -s <storage-id> -k <public-key>
 ```
 
 ### Options
@@ -136,14 +136,14 @@ Expose a local server to the internet through a secure WebSocket tunnel. Useful
 
 ```bash
 # Expose local port 8084 to the internet
-npx connectbase-client tunnel 8084 -k <public-key>
+npx connectbase tunnel 8084 -k <public-key>
 
 # With environment variable
 export CONNECTBASE_PUBLIC_KEY=your-public-key
-npx connectbase-client tunnel 8084
+npx connectbase tunnel 8084
 
 # For GPU servers or long-running tasks (e.g., image generation)
-npx connectbase-client tunnel 7860 --timeout 300 --max-body 50
+npx connectbase tunnel 7860 --timeout 300 --max-body 50
 ```
 
 The tunnel creates a public URL like `https://tunnel.connectbase.world/<tunnel-id>/` that proxies all HTTP requests to your local service.
@@ -181,7 +181,7 @@ The `init` command creates `.connectbaserc` automatically. You can also create i
 ```bash
 export CONNECTBASE_PUBLIC_KEY=your-public-key
 export CONNECTBASE_STORAGE_ID=your-storage-id
-npx connectbase-client deploy ./dist
+npx connectbase deploy ./dist
 ```
 
 ### Requirements
@@ -439,19 +439,19 @@ await cb.auth.signOut()
 
 ```typescript
 // Query data
-const { data } = await cb.database.getData('table-id', {
+const { datas, total_size } = await cb.database.getData('table-id', {
   where: { status: 'active' },
   limit: 10
 })
 
 // Query with field selection (Projection) - improves response speed
-const { data } = await cb.database.getData('table-id', {
+const { datas } = await cb.database.getData('table-id', {
   select: ['id', 'name', 'thumbnail'],  // Only return these fields
   limit: 20
 })
 
 // Exclude specific fields (e.g., large HTML/CSS content)
-const { data } = await cb.database.getData('table-id', {
+const { datas } = await cb.database.getData('table-id', {
   exclude: ['html_content', 'css_content'],
   limit: 20
 })
@@ -764,17 +764,27 @@ await session.stop()
 ### Push Notifications
 
 ```typescript
-// Register for push notifications
-await cb.push.register({
-  token: 'fcm-token-or-apns-token',
-  platform: 'android' // or 'ios', 'web'
+// Register a device (FCM for Android, APNS for iOS)
+const device = await cb.push.registerDevice({
+  device_token: 'fcm-token-or-apns-token',
+  platform: 'android', // 'android' | 'ios' | 'web'
+  device_name: 'Galaxy S24'
 })
 
-// Subscribe to topics
-await cb.push.subscribeToTopic('news')
+// Subscribe the device to a topic (deviceToken is required)
+await cb.push.subscribeTopic(device.device_token, 'news')
 
-// Unsubscribe from topic
-await cb.push.unsubscribeFromTopic('news')
+// Unsubscribe the device from a topic
+await cb.push.unsubscribeTopic(device.device_token, 'news')
+
+// Web Push (browsers)
+const vapidKey = await cb.push.getVAPIDPublicKey()
+const registration = await navigator.serviceWorker.ready
+const subscription = await registration.pushManager.subscribe({
+  userVisibleOnly: true,
+  applicationServerKey: vapidKey.public_key
+})
+await cb.push.registerWebPush(subscription)
 ```
 
 ### WebRTC

package/dist/cli.js

@@ -108,7 +108,18 @@ function handleTunnelError(msg, appId, localPort) {
 }
 
 // src/cli.ts
-var VERSION = "0.10.6";
+function getPackageVersion() {
+  try {
+    const pkgPath = path2.join(__dirname, "..", "package.json");
+    if (fs2.existsSync(pkgPath)) {
+      const pkg = JSON.parse(fs2.readFileSync(pkgPath, "utf-8"));
+      return pkg.version || "0.0.0";
+    }
+  } catch {
+  }
+  return "0.15.1";
+}
+var VERSION = getPackageVersion();
 var DEFAULT_BASE_URL = "https://api.connectbase.world";
 var colors = {
   reset: "\x1B[0m",
@@ -300,8 +311,8 @@ async function deploy(directory, config, isDev = false) {
     try {
       const pkg = JSON.parse(fs2.readFileSync(pkgPath, "utf-8"));
       if (pkg.scripts?.build) {
-        warn(`\uBC30\uD3EC \uC804 \uBE4C\uB4DC\uB97C \uBA3C\uC800 \uC2E4\uD589\uD558\uC138\uC694: ${colors.cyan}npm run build && npx connectbase-client deploy${colors.reset}`);
-        warn(`\uB610\uB294 package.json\uC5D0 deploy \uC2A4\uD06C\uB9BD\uD2B8\uB97C \uB4F1\uB85D\uD558\uC138\uC694: ${colors.cyan}npx connectbase-client init${colors.reset}`);
+        warn(`\uBC30\uD3EC \uC804 \uBE4C\uB4DC\uB97C \uBA3C\uC800 \uC2E4\uD589\uD558\uC138\uC694: ${colors.cyan}npm run build && npx connectbase deploy${colors.reset}`);
+        warn(`\uB610\uB294 package.json\uC5D0 deploy \uC2A4\uD06C\uB9BD\uD2B8\uB97C \uB4F1\uB85D\uD558\uC138\uC694: ${colors.cyan}npx connectbase init${colors.reset}`);
       }
     } catch {
     }
@@ -782,7 +793,7 @@ function addDeployScript(deployDir) {
       info(`package.json\uC5D0 \uC774\uBBF8 deploy \uC2A4\uD06C\uB9BD\uD2B8\uAC00 \uC788\uC2B5\uB2C8\uB2E4: "${pkg.scripts.deploy}"`);
       return;
     }
-    const deployCmd = `connectbase-client deploy ${deployDir}`;
+    const deployCmd = `connectbase deploy ${deployDir}`;
     pkg.scripts.deploy = pkg.scripts.build ? `${pkg.scripts.build} && ${deployCmd}` : deployCmd;
     fs2.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
     success(`package.json\uC5D0 deploy \uC2A4\uD06C\uB9BD\uD2B8 \uCD94\uAC00 \uC644\uB8CC`);
@@ -1043,6 +1054,229 @@ async function setupClaudeCode(publicKey, secretKey, projectRoot) {
   await downloadDocs(publicKey, void 0, root);
   await setupMcp(secretKey);
 }
+async function fetchLatestVersion(packageName) {
+  try {
+    const res = await makeRequest(
+      `https://registry.npmjs.org/${packageName}/latest`,
+      "GET",
+      {}
+    );
+    if (res.status === 200) {
+      const data = res.data;
+      return data.version || null;
+    }
+  } catch {
+  }
+  return null;
+}
+function compareVersions(a, b) {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    const diff = (pa[i] || 0) - (pb[i] || 0);
+    if (diff !== 0) return diff > 0 ? 1 : -1;
+  }
+  return 0;
+}
+function findSubPackagesWithConfig(gitRoot) {
+  const results = [];
+  const candidates = ["apps", "packages", "projects", "services", "libs"];
+  for (const candidate of candidates) {
+    const dir = path2.join(gitRoot, candidate);
+    if (!fs2.existsSync(dir)) continue;
+    try {
+      const entries = fs2.readdirSync(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (!entry.isDirectory() || entry.name.startsWith(".")) continue;
+        const subDir = path2.join(dir, entry.name);
+        if (fs2.existsSync(path2.join(subDir, ".connectbaserc"))) {
+          results.push(subDir);
+        }
+      }
+    } catch {
+    }
+  }
+  try {
+    const entries = fs2.readdirSync(gitRoot, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory() || entry.name.startsWith(".") || candidates.includes(entry.name)) continue;
+      if (entry.name === "node_modules") continue;
+      const subDir = path2.join(gitRoot, entry.name);
+      if (fs2.existsSync(path2.join(subDir, ".connectbaserc")) && !results.includes(subDir)) {
+        results.push(subDir);
+      }
+    }
+  } catch {
+  }
+  return results;
+}
+async function update(config, opts) {
+  log(`
+${colors.cyan}ConnectBase Update${colors.reset}
+`);
+  const gitRoot = getGitRoot();
+  const projectRoot = gitRoot || process.cwd();
+  const monorepo = detectMonorepo(projectRoot);
+  info("\uCD5C\uC2E0 \uBC84\uC804 \uD655\uC778 \uC911...");
+  const latestVersion = await fetchLatestVersion("connectbase-client");
+  if (latestVersion) {
+    const cmp = compareVersions(VERSION, latestVersion);
+    if (cmp >= 0) {
+      success(`\uCD5C\uC2E0 \uBC84\uC804\uC785\uB2C8\uB2E4 (v${VERSION})`);
+    } else {
+      warn(`\uC0C8 \uBC84\uC804\uC774 \uC788\uC2B5\uB2C8\uB2E4: v${VERSION} \u2192 v${colors.green}${latestVersion}${colors.reset}`);
+      log(`  ${colors.cyan}npm install connectbase-client@latest${colors.reset}`);
+      log(`  ${colors.cyan}pnpm add connectbase-client@latest${colors.reset}`);
+      log("");
+    }
+  } else {
+    warn("npm \uB808\uC9C0\uC2A4\uD2B8\uB9AC\uC5D0\uC11C \uBC84\uC804 \uC815\uBCF4\uB97C \uAC00\uC838\uC62C \uC218 \uC5C6\uC2B5\uB2C8\uB2E4");
+  }
+  if (opts.checkOnly) {
+    return;
+  }
+  if (monorepo.type !== "none") {
+    info(`\uBAA8\uB178\uB808\uD3EC \uAC10\uC9C0: ${monorepo.type} (\uB8E8\uD2B8: ${projectRoot})`);
+    const subPackages = findSubPackagesWithConfig(projectRoot);
+    if (subPackages.length > 0) {
+      info(`ConnectBase\uB97C \uC0AC\uC6A9\uD558\uB294 \uC11C\uBE0C \uD328\uD0A4\uC9C0 ${subPackages.length}\uAC1C \uBC1C\uACAC:`);
+      for (const sp of subPackages) {
+        log(`  ${colors.dim}\u2022 ${path2.relative(projectRoot, sp)}${colors.reset}`);
+      }
+    }
+  }
+  if (!opts.skipDocs) {
+    log("");
+    info("SDK \uBB38\uC11C \uC5C5\uB370\uC774\uD2B8 \uC911...");
+    let docsKey = config.publicKey || config.secretKey;
+    if (!docsKey) {
+      const rootRcPath = path2.join(projectRoot, ".connectbaserc");
+      if (fs2.existsSync(rootRcPath)) {
+        try {
+          const rc = JSON.parse(fs2.readFileSync(rootRcPath, "utf-8"));
+          docsKey = rc.publicKey || rc.secretKey;
+        } catch {
+        }
+      }
+    }
+    if (!docsKey && monorepo.type !== "none") {
+      const subPackages = findSubPackagesWithConfig(projectRoot);
+      for (const sp of subPackages) {
+        try {
+          const rc = JSON.parse(fs2.readFileSync(path2.join(sp, ".connectbaserc"), "utf-8"));
+          if (rc.publicKey || rc.secretKey) {
+            docsKey = rc.publicKey || rc.secretKey;
+            break;
+          }
+        } catch {
+        }
+      }
+    }
+    if (docsKey) {
+      await downloadDocs(docsKey, void 0, projectRoot);
+    } else {
+      warn("Public Key\uB97C \uCC3E\uC744 \uC218 \uC5C6\uC5B4 \uBB38\uC11C \uC5C5\uB370\uC774\uD2B8\uB97C \uAC74\uB108\uB701\uB2C8\uB2E4");
+      info(".connectbaserc \uD30C\uC77C\uC774\uB098 --public-key \uC635\uC158\uC73C\uB85C \uD0A4\uB97C \uC9C0\uC815\uD558\uC138\uC694");
+    }
+  }
+  if (!opts.skipMcp) {
+    log("");
+    const mcpConfigPath = path2.join(projectRoot, ".mcp.json");
+    if (fs2.existsSync(mcpConfigPath)) {
+      let secretKey = config.secretKey;
+      if (!secretKey) {
+        const rootRcPath = path2.join(projectRoot, ".connectbaserc");
+        if (fs2.existsSync(rootRcPath)) {
+          try {
+            const rc = JSON.parse(fs2.readFileSync(rootRcPath, "utf-8"));
+            secretKey = rc.secretKey;
+          } catch {
+          }
+        }
+      }
+      if (!secretKey && monorepo.type !== "none") {
+        const subPackages = findSubPackagesWithConfig(projectRoot);
+        for (const sp of subPackages) {
+          try {
+            const rc = JSON.parse(fs2.readFileSync(path2.join(sp, ".connectbaserc"), "utf-8"));
+            if (rc.secretKey) {
+              secretKey = rc.secretKey;
+              break;
+            }
+          } catch {
+          }
+        }
+      }
+      if (secretKey) {
+        try {
+          const mcpConfig = JSON.parse(fs2.readFileSync(mcpConfigPath, "utf-8"));
+          const servers = mcpConfig.mcpServers || {};
+          if (servers["connect-base"]) {
+            servers["connect-base"] = {
+              type: "http",
+              url: "https://mcp.connectbase.world/mcp",
+              headers: { Authorization: `Bearer ${secretKey}` }
+            };
+            mcpConfig.mcpServers = servers;
+            fs2.writeFileSync(mcpConfigPath, JSON.stringify(mcpConfig, null, 2) + "\n");
+            success("MCP \uC124\uC815 \uC5C5\uB370\uC774\uD2B8 \uC644\uB8CC");
+          } else {
+            info('.mcp.json\uC5D0 connect-base \uD56D\uBAA9\uC774 \uC5C6\uC2B5\uB2C8\uB2E4. "connectbase mcp"\uB85C \uC124\uC815\uD558\uC138\uC694');
+          }
+        } catch {
+          warn(".mcp.json \uC5C5\uB370\uC774\uD2B8 \uC2E4\uD328");
+        }
+      } else {
+        info("Secret Key\uAC00 \uC5C6\uC5B4 MCP \uC124\uC815 \uC5C5\uB370\uC774\uD2B8\uB97C \uAC74\uB108\uB701\uB2C8\uB2E4");
+      }
+    } else {
+      info('.mcp.json\uC774 \uC5C6\uC2B5\uB2C8\uB2E4. "connectbase mcp"\uB85C \uCD5C\uCD08 \uC124\uC815\uD558\uC138\uC694');
+    }
+  }
+  if (opts.setupRoot || monorepo.type !== "none" && monorepo.isSubPackage) {
+    log("");
+    setupMonorepoRoot(projectRoot, monorepo);
+  }
+  log(`
+${colors.green}\uC5C5\uB370\uC774\uD2B8 \uC644\uB8CC!${colors.reset}
+`);
+}
+function setupMonorepoRoot(projectRoot, monorepo) {
+  const rootPkgPath = path2.join(projectRoot, "package.json");
+  if (!fs2.existsSync(rootPkgPath)) {
+    warn("\uD504\uB85C\uC81D\uD2B8 \uB8E8\uD2B8\uC5D0 package.json\uC774 \uC5C6\uC5B4 \uD3B8\uC758 \uC2A4\uD06C\uB9BD\uD2B8\uB97C \uCD94\uAC00\uD560 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4");
+    return;
+  }
+  try {
+    const pkg = JSON.parse(fs2.readFileSync(rootPkgPath, "utf-8"));
+    if (!pkg.scripts) pkg.scripts = {};
+    let changed = false;
+    if (!pkg.scripts["cb:update"]) {
+      pkg.scripts["cb:update"] = "npx connectbase update";
+      changed = true;
+    }
+    if (!pkg.scripts["cb:docs"]) {
+      pkg.scripts["cb:docs"] = "npx connectbase docs";
+      changed = true;
+    }
+    if (!pkg.scripts["cb:mcp"]) {
+      pkg.scripts["cb:mcp"] = "npx connectbase mcp";
+      changed = true;
+    }
+    if (changed) {
+      fs2.writeFileSync(rootPkgPath, JSON.stringify(pkg, null, 2) + "\n");
+      success("\uBAA8\uB178\uB808\uD3EC \uB8E8\uD2B8\uC5D0 \uD3B8\uC758 \uC2A4\uD06C\uB9BD\uD2B8 \uCD94\uAC00 \uC644\uB8CC");
+      log(`  ${colors.dim}\uC0AC\uC6A9\uBC95:${colors.reset}`);
+      log(`  ${colors.cyan}${monorepo.type === "pnpm" ? "pnpm" : monorepo.type === "yarn" ? "yarn" : "npm run"} cb:update${colors.reset}  \u2014 SDK \uC5C5\uB370\uC774\uD2B8 + \uBB38\uC11C \uAC31\uC2E0`);
+      log(`  ${colors.cyan}${monorepo.type === "pnpm" ? "pnpm" : monorepo.type === "yarn" ? "yarn" : "npm run"} cb:docs${colors.reset}    \u2014 \uBB38\uC11C\uB9CC \uAC31\uC2E0`);
+      log(`  ${colors.cyan}${monorepo.type === "pnpm" ? "pnpm" : monorepo.type === "yarn" ? "yarn" : "npm run"} cb:mcp${colors.reset}     \u2014 MCP \uC124\uC815`);
+    } else {
+      info("\uBAA8\uB178\uB808\uD3EC \uB8E8\uD2B8\uC5D0 \uC774\uBBF8 \uD3B8\uC758 \uC2A4\uD06C\uB9BD\uD2B8\uAC00 \uC124\uC815\uB418\uC5B4 \uC788\uC2B5\uB2C8\uB2E4");
+    }
+  } catch {
+    warn("\uB8E8\uD2B8 package.json \uC218\uC815\uC5D0 \uC2E4\uD328\uD588\uC2B5\uB2C8\uB2E4");
+  }
+}
 function createWsTextFrame(payload) {
   const data = Buffer.from(payload, "utf-8");
   const len = data.length;
@@ -1576,13 +1810,14 @@ ${colors.dim}Ctrl+C\uB85C \uC885\uB8CC${colors.reset}
 }
 function showHelp() {
   log(`
-${colors.cyan}connectbase-client${colors.reset} - Connect Base SDK & CLI
+${colors.cyan}connectbase${colors.reset} - Connect Base SDK & CLI
 
 ${colors.yellow}\uC0AC\uC6A9\uBC95:${colors.reset}
-  npx connectbase-client <command> [options]
+  npx connectbase <command> [options]
 
 ${colors.yellow}\uBA85\uB839\uC5B4:${colors.reset}
   init                  \uD504\uB85C\uC81D\uD2B8 \uCD08\uAE30\uD654 (\uC571 \uC0DD\uC131, MCP \uC124\uC815, SDK \uBB38\uC11C \uB2E4\uC6B4\uB85C\uB4DC)
+  update                SDK \uBC84\uC804 \uCCB4\uD06C + \uBB38\uC11C/MCP \uC77C\uAD04 \uC5C5\uB370\uC774\uD2B8 (\uBAA8\uB178\uB808\uD3EC \uB8E8\uD2B8 \uC9C0\uC6D0)
   docs                  SDK \uBB38\uC11C \uB2E4\uC6B4\uB85C\uB4DC/\uC5C5\uB370\uC774\uD2B8 (\uBAA8\uB178\uB808\uD3EC \uC790\uB3D9 \uAC10\uC9C0)
   mcp                   MCP \uC11C\uBC84 \uC124\uC815 (.mcp.json \uC0DD\uC131/\uC5C5\uB370\uC774\uD2B8, \uBAA8\uB178\uB808\uD3EC \uC790\uB3D9 \uAC10\uC9C0)
   deploy <directory>    \uC6F9 \uC2A4\uD1A0\uB9AC\uC9C0\uC5D0 \uD30C\uC77C \uBC30\uD3EC (--dev: Dev \uD658\uACBD)
@@ -1603,25 +1838,35 @@ ${colors.yellow}\uC635\uC158:${colors.reset}
   --max-body <MB>       \uD130\uB110 \uCD5C\uB300 \uBC14\uB514 \uD06C\uAE30 (MB, tunnel \uC804\uC6A9)
   --force               \uD130\uB110 lockfile \uBB34\uC2DC (\uC911\uBCF5 \uC2E4\uD589 \uAC15\uC81C, tunnel \uC804\uC6A9)
   -d, --dev             Dev \uD658\uACBD\uC5D0 \uBC30\uD3EC (deploy \uC804\uC6A9)
-  (docs, mcp\uB294 \uBAA8\uB178\uB808\uD3EC\uB97C \uC790\uB3D9 \uAC10\uC9C0\uD558\uC5EC \uD504\uB85C\uC81D\uD2B8 \uB8E8\uD2B8\uC5D0 \uC0DD\uC131)
+  --check               \uBC84\uC804\uB9CC \uD655\uC778 (update \uC804\uC6A9)
+  --skip-docs           \uBB38\uC11C \uC5C5\uB370\uC774\uD2B8 \uAC74\uB108\uB6F0\uAE30 (update \uC804\uC6A9)
+  --skip-mcp            MCP \uC5C5\uB370\uC774\uD2B8 \uAC74\uB108\uB6F0\uAE30 (update \uC804\uC6A9)
+  --setup-root          \uBAA8\uB178\uB808\uD3EC \uB8E8\uD2B8\uC5D0 \uD3B8\uC758 \uC2A4\uD06C\uB9BD\uD2B8 \uCD94\uAC00 (update \uC804\uC6A9)
+  (docs, mcp, update\uB294 \uBAA8\uB178\uB808\uD3EC\uB97C \uC790\uB3D9 \uAC10\uC9C0\uD558\uC5EC \uD504\uB85C\uC81D\uD2B8 \uB8E8\uD2B8\uC5D0 \uC0DD\uC131)
   -h, --help            \uB3C4\uC6C0\uB9D0 \uD45C\uC2DC
   -v, --version         \uBC84\uC804 \uD45C\uC2DC
 
 ${colors.yellow}\uBE60\uB978 \uC2DC\uC791:${colors.reset}
   ${colors.dim}# 1. \uCD08\uAE30\uD654 (\uCD5C\uCD08 1\uD68C)${colors.reset}
-  npx connectbase-client init
+  npx connectbase init
+
+  ${colors.dim}# 2. SDK \uC804\uCCB4 \uC5C5\uB370\uC774\uD2B8 (\uBC84\uC804 \uCCB4\uD06C + \uBB38\uC11C + MCP)${colors.reset}
+  npx connectbase update
 
-  ${colors.dim}# 2. SDK \uBB38\uC11C \uC5C5\uB370\uC774\uD2B8${colors.reset}
+  ${colors.dim}# 2-1. \uBAA8\uB178\uB808\uD3EC \uB8E8\uD2B8\uC5D0 \uD3B8\uC758 \uC2A4\uD06C\uB9BD\uD2B8 \uC124\uCE58${colors.reset}
+  npx connectbase update --setup-root
+
+  ${colors.dim}# 3. SDK \uBB38\uC11C\uB9CC \uC5C5\uB370\uC774\uD2B8${colors.reset}
   npx connectbase docs
 
-  ${colors.dim}# 3. MCP \uC11C\uBC84 \uC124\uC815${colors.reset}
+  ${colors.dim}# 4. MCP \uC11C\uBC84 \uC124\uC815${colors.reset}
   npx connectbase mcp
 
   ${colors.dim}# 4. Prod \uBC30\uD3EC${colors.reset}
   npm run deploy
 
   ${colors.dim}# 4. Dev \uD658\uACBD \uBC30\uD3EC (\uB0B4\uBD80 QA\uC6A9)${colors.reset}
-  npx connectbase-client deploy ./dist --dev
+  npx connectbase deploy ./dist --dev
 
   ${colors.dim}# 5. \uD130\uB110 (\uAE30\uBCF8)${colors.reset}
   npx connectbase tunnel 3000
@@ -1671,6 +1916,14 @@ function parseArgs(args) {
       result.options.force = "true";
     } else if (arg === "-d" || arg === "--dev") {
       result.options.dev = "true";
+    } else if (arg === "--check") {
+      result.options.check = "true";
+    } else if (arg === "--skip-docs") {
+      result.options.skipDocs = "true";
+    } else if (arg === "--skip-mcp") {
+      result.options.skipMcp = "true";
+    } else if (arg === "--setup-root") {
+      result.options.setupRoot = "true";
     } else if (arg === "-h" || arg === "--help") {
       result.options.help = "true";
     } else if (arg === "-v" || arg === "--version") {
@@ -1689,7 +1942,7 @@ function parseArgs(args) {
 async function main() {
   const parsed = parseArgs(process.argv.slice(2));
   if (parsed.options.version) {
-    log(`connectbase-client v${VERSION}`);
+    log(`connectbase v${VERSION}`);
     return;
   }
   if (parsed.options.help || !parsed.command) {
@@ -1705,6 +1958,13 @@ async function main() {
   };
   if (parsed.command === "init") {
     await init();
+  } else if (parsed.command === "update") {
+    await update(config, {
+      checkOnly: parsed.options.check === "true",
+      skipDocs: parsed.options.skipDocs === "true",
+      skipMcp: parsed.options.skipMcp === "true",
+      setupRoot: parsed.options.setupRoot === "true"
+    });
   } else if (parsed.command === "docs") {
     let docsPublicKey = config.publicKey ?? config.publicKey;
     if (!docsPublicKey) {
@@ -1720,11 +1980,11 @@ async function main() {
   } else if (parsed.command === "deploy") {
     const directory = parsed.args[0] || fileConfig.deployDir || ".";
     if (!config.publicKey && !config.publicKey) {
-      error('Public Key\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4. "npx connectbase-client init"\uC73C\uB85C \uC124\uC815\uD558\uAC70\uB098 -k \uC635\uC158\uC744 \uC0AC\uC6A9\uD558\uC138\uC694');
+      error('Public Key\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4. "npx connectbase init"\uC73C\uB85C \uC124\uC815\uD558\uAC70\uB098 -k \uC635\uC158\uC744 \uC0AC\uC6A9\uD558\uC138\uC694');
       process.exit(1);
     }
     if (!config.storageId) {
-      error('\uC2A4\uD1A0\uB9AC\uC9C0 ID\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4. "npx connectbase-client init"\uC73C\uB85C \uC124\uC815\uD558\uAC70\uB098 -s \uC635\uC158\uC744 \uC0AC\uC6A9\uD558\uC138\uC694');
+      error('\uC2A4\uD1A0\uB9AC\uC9C0 ID\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4. "npx connectbase init"\uC73C\uB85C \uC124\uC815\uD558\uAC70\uB098 -s \uC635\uC158\uC744 \uC0AC\uC6A9\uD558\uC138\uC694');
       process.exit(1);
     }
     const isDev = parsed.options.dev === "true";
@@ -1732,7 +1992,7 @@ async function main() {
   } else if (parsed.command === "tunnel") {
     const portStr = parsed.args[0];
     if (!portStr) {
-      error("\uD3EC\uD2B8 \uBC88\uD638\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4. \uC608: npx connectbase-client tunnel 8084");
+      error("\uD3EC\uD2B8 \uBC88\uD638\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4. \uC608: npx connectbase tunnel 8084");
       process.exit(1);
     }
     const port = parseInt(portStr, 10);