shellbase 0.1.0

package/README.md

@@ -0,0 +1,44 @@
+# shellbase
+
+내 컴퓨터 터미널(특히 [Claude Code](https://claude.com/claude-code) 세션)을 폰 브라우저로
+실시간으로 보고 조작할 수 있게 해주는 데스크톱 에이전트입니다.
+
+## 설치
+
+```bash
+npm install -g shellbase
+```
+
+## 사용법
+
+```bash
+# 구글 계정으로 로그인 (처음이면 자동으로 가입도 됨)
+shellbase login
+
+# 지금 폴더에서 터미널 세션 시작
+shellbase start
+
+# 다른 폴더에서 시작하고 싶으면
+shellbase start --dir ~/projects/my-app --name "내 노트북"
+```
+
+`shellbase start` 를 실행한 뒤 [shellbase.web.connectbase.world](https://shellbase.web.connectbase.world)
+에 같은 계정으로 접속하면 내 데스크톱 목록에 뜹니다. 선택하면 데스크톱에 접속 승인 알림이 뜨고,
+승인하면 폰에서 그대로 타이핑할 수 있어요.
+
+## 명령어
+
+| 명령어 | 설명 |
+|---|---|
+| `shellbase login` | 구글 계정으로 로그인 |
+| `shellbase logout` | 로그아웃 |
+| `shellbase whoami` | 현재 로그인된 계정 확인 |
+| `shellbase start [--dir <path>] [--name <name>]` | 터미널 세션 시작 |
+
+## 참고
+
+- `node-pty` 를 사용해서 설치 시 네이티브 모듈을 컴파일합니다. macOS는 Xcode Command Line Tools,
+  Linux는 `build-essential`(또는 배포판의 동급 패키지), Windows는 Visual Studio Build Tools가
+  필요할 수 있어요.
+- 터미널 내용은 기기별 키로 암호화돼서 전송되고, 모바일에서 접속을 시도할 때마다 데스크톱에서
+  직접 승인해야 입력이 가능합니다.

package/dist/auth.js

@@ -0,0 +1,91 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import crypto from 'node:crypto';
+import { ConnectBase } from 'connectbase-client';
+import { APP_ID, PUBLIC_KEY, CONFIG_DIR, CREDENTIALS_PATH, DEVICE_PATH } from './config.js';
+import { generateFrameKey } from './crypto.js';
+import { loginWithGoogle } from './google-auth.js';
+function ensureConfigDir() {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+}
+function saveCredentials(creds) {
+    ensureConfigDir();
+    fs.writeFileSync(CREDENTIALS_PATH, JSON.stringify(creds, null, 2), { mode: 0o600 });
+}
+function loadCredentials() {
+    try {
+        return JSON.parse(fs.readFileSync(CREDENTIALS_PATH, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function loadOrCreateDevice() {
+    try {
+        return JSON.parse(fs.readFileSync(DEVICE_PATH, 'utf8'));
+    }
+    catch {
+        // realtime userId 는 UUID 형태를 "인증된 멤버 전용"으로 취급해서 거부하므로,
+        // 기기 식별자는 접두사를 붙여 UUID 로 보이지 않게 만든다.
+        const identity = {
+            deviceId: `desktop-${crypto.randomUUID()}`,
+            deviceName: os.hostname(),
+            frameKey: generateFrameKey(),
+        };
+        ensureConfigDir();
+        fs.writeFileSync(DEVICE_PATH, JSON.stringify(identity, null, 2), { mode: 0o600 });
+        return identity;
+    }
+}
+function createClient(onTokens) {
+    return new ConnectBase({
+        appId: APP_ID,
+        publicKey: PUBLIC_KEY,
+        onTokenRefresh: (tokens) => {
+            onTokens?.({ access_token: tokens.accessToken, refresh_token: tokens.refreshToken });
+        },
+    });
+}
+export async function login() {
+    // 이 앱은 구글 로그인만 허용하도록 설정돼 있어서(콘솔에서 이메일/비밀번호 로그인 끔),
+    // CLI도 구글 로그인만 지원. 상세 흐름은 google-auth.ts 참고 (모바일 웹을 통한 중계 방식).
+    const { accessToken, refreshToken, memberId } = await loginWithGoogle();
+    const cb = createClient();
+    cb.setTokens(accessToken, refreshToken);
+    const me = await cb.auth.getMe();
+    saveCredentials({
+        member_id: memberId,
+        nickname: me.nickname,
+        access_token: accessToken,
+        refresh_token: refreshToken,
+    });
+    console.log(`로그인 완료! (${me.nickname})`);
+}
+export async function logout() {
+    try {
+        fs.rmSync(CREDENTIALS_PATH);
+    }
+    catch {
+        // 이미 로그아웃 상태
+    }
+    console.log('로그아웃했어요.');
+}
+export async function whoami() {
+    const { cb, memberId } = await requireClient();
+    const me = await cb.auth.getMe();
+    console.log(`${me.nickname}${me.email ? ` <${me.email}>` : ''} (member_id: ${memberId})`);
+}
+export async function requireClient() {
+    const creds = loadCredentials();
+    if (!creds) {
+        console.error('로그인이 필요해요. 먼저 `shellbase login` 을 실행하세요.');
+        process.exit(1);
+    }
+    const cb = createClient((tokens) => {
+        const current = loadCredentials();
+        if (current)
+            saveCredentials({ ...current, ...tokens });
+    });
+    cb.setTokens(creds.access_token, creds.refresh_token);
+    return { cb, memberId: creds.member_id, nickname: creds.nickname };
+}

package/dist/cli.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { login, logout, whoami } from './auth.js';
+import { startSession } from './session.js';
+const program = new Command();
+program.name('shellbase').description('내 컴퓨터 터미널을 폰에서 접속할 수 있게 해주는 에이전트');
+program
+    .command('login')
+    .description('구글 계정으로 로그인 (처음이면 자동으로 가입도 돼요)')
+    .action(async () => {
+    await login();
+});
+program
+    .command('logout')
+    .description('로그아웃')
+    .action(async () => {
+    await logout();
+});
+program
+    .command('whoami')
+    .description('현재 로그인된 계정 확인')
+    .action(async () => {
+    await whoami();
+});
+program
+    .command('start')
+    .description('이 컴퓨터의 터미널을 열어서 폰 접속을 받을 수 있게 시작')
+    .option('--dir <path>', '이 폴더에서 터미널을 시작해요 (기본: 현재 폴더)')
+    .option('--name <name>', '폰에서 보여줄 이 기기의 이름 (기본: 컴퓨터 이름)')
+    .action(async (opts) => {
+    await startSession(opts);
+});
+program.parseAsync(process.argv).catch((err) => {
+    console.error('실행 중 문제가 생겼어요:', err instanceof Error ? err.message : err);
+    process.exit(1);
+});

package/dist/config.js

@@ -0,0 +1,14 @@
+import os from 'node:os';
+import path from 'node:path';
+export const APP_ID = process.env.SHELLBASE_APP_ID ?? '01a00981-cc7b-79b1-ada4-7338d52a4466';
+export const PUBLIC_KEY = process.env.SHELLBASE_PUBLIC_KEY ?? 'cb_pk_01a00981-cc9d-79c0-85f7-df1b6f1955ce';
+// 실시간 프레임 채널. persist:false로 만들어서 ConnectBase 서버에 내용이 남지 않음.
+export const TERMINAL_CATEGORY = 'shellbase-terminal';
+// 이 앱의 모든 멤버가 같은 채널을 공유하므로, 프레임 자체는 기기별 키로 암호화해서 보낸다 (crypto.ts).
+export const DEVICES_TABLE_ID = '01a009c7-a33d-79ca-9eeb-f9dc2d442c1b';
+// CLI 구글 로그인 중계용 (google-auth.ts) — 짧게 살고 암호화된 채로만 저장됨.
+export const CLI_AUTH_SESSIONS_TABLE_ID = '01a00aa0-802d-7730-88ba-b831b7405188';
+export const WEB_LOGIN_URL = 'https://shellbase.web.connectbase.world/login';
+export const CONFIG_DIR = path.join(os.homedir(), '.shellbase');
+export const CREDENTIALS_PATH = path.join(CONFIG_DIR, 'credentials.json');
+export const DEVICE_PATH = path.join(CONFIG_DIR, 'device.json');

package/dist/crypto.js

@@ -0,0 +1,29 @@
+import crypto from 'node:crypto';
+const ALGO = 'aes-256-gcm';
+const IV_LEN = 12;
+const TAG_LEN = 16;
+// 실시간 채널은 이 ConnectBase 앱의 멤버라면 누구나 구독할 수 있는 공유 채널이라,
+// 프레임 자체를 기기별 키로 암호화해서 다른 사용자가 봐도 알아볼 수 없게 만든다.
+// 지갑 형식은 base64(iv(12) + ciphertext+authTag) — 브라우저 Web Crypto(AES-GCM)의
+// "암호문 뒤에 태그를 붙여 반환" 관례와 그대로 맞춰서, 모바일(Web Crypto)과 바로 호환되게 함.
+export function generateFrameKey() {
+    return crypto.randomBytes(32).toString('base64');
+}
+export function encryptFrame(plaintext, keyB64) {
+    const key = Buffer.from(keyB64, 'base64');
+    const iv = crypto.randomBytes(IV_LEN);
+    const cipher = crypto.createCipheriv(ALGO, key, iv);
+    const ciphertext = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+    const authTag = cipher.getAuthTag();
+    return Buffer.concat([iv, ciphertext, authTag]).toString('base64');
+}
+export function decryptFrame(payloadB64, keyB64) {
+    const key = Buffer.from(keyB64, 'base64');
+    const raw = Buffer.from(payloadB64, 'base64');
+    const iv = raw.subarray(0, IV_LEN);
+    const authTag = raw.subarray(raw.length - TAG_LEN);
+    const ciphertext = raw.subarray(IV_LEN, raw.length - TAG_LEN);
+    const decipher = crypto.createDecipheriv(ALGO, key, iv);
+    decipher.setAuthTag(authTag);
+    return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString('utf8');
+}

package/dist/devices.js

@@ -0,0 +1,34 @@
+import { DEVICES_TABLE_ID } from './config.js';
+export async function registerDevice(cb, params) {
+    const { data: rows } = await cb.database.queryData(DEVICES_TABLE_ID, {
+        where: { device_id: params.deviceId },
+        limit: 1,
+    });
+    const payload = {
+        owner_id: params.ownerId,
+        device_id: params.deviceId,
+        device_name: params.deviceName,
+        status: 'online',
+        cwd: params.cwd,
+        frame_key: params.frameKey,
+        favorite_dirs: params.favoriteDirs,
+        last_seen_at: new Date().toISOString(),
+    };
+    const existing = rows[0];
+    if (existing) {
+        await cb.database.updateData(DEVICES_TABLE_ID, existing.id, { data: payload });
+        return existing.id;
+    }
+    const created = await cb.database.createData(DEVICES_TABLE_ID, { data: payload });
+    return created.id;
+}
+export async function heartbeatDevice(cb, rowId) {
+    await cb.database.updateData(DEVICES_TABLE_ID, rowId, {
+        data: { status: 'online', last_seen_at: new Date().toISOString() },
+    });
+}
+export async function markDeviceOffline(cb, rowId) {
+    await cb.database.updateData(DEVICES_TABLE_ID, rowId, {
+        data: { status: 'offline', last_seen_at: new Date().toISOString() },
+    });
+}

package/dist/google-auth.js

@@ -0,0 +1,64 @@
+import crypto from 'node:crypto';
+import { exec } from 'node:child_process';
+import { ConnectBase } from 'connectbase-client';
+import { APP_ID, PUBLIC_KEY, CLI_AUTH_SESSIONS_TABLE_ID, WEB_LOGIN_URL } from './config.js';
+import { generateFrameKey, decryptFrame } from './crypto.js';
+const API_BASE = 'https://api.connectbase.world';
+const LOGIN_TIMEOUT_MS = 5 * 60_000;
+const POLL_INTERVAL_MS = 1500;
+const SESSION_TTL_MS = 10 * 60_000;
+function openBrowser(url) {
+    const command = process.platform === 'darwin'
+        ? `open "${url}"`
+        : process.platform === 'win32'
+            ? `start "" "${url}"`
+            : `xdg-open "${url}"`;
+    exec(command, () => { });
+}
+// ConnectBase의 app_callback은 이 앱이 실제로 배포된 웹 주소만 허용해서(오픈 리다이렉트 방지),
+// CLI가 임의의 localhost 포트를 콜백으로 쓸 수 없다. 대신: 모바일 웹(WEB_LOGIN_URL)이 구글 로그인을
+// 대신 받고, 임시 DB row(cli_auth_sessions)를 통해 토큰을 CLI에 중계한다. row는 CLI만 아는 랜덤 키로
+// 암호화돼서 저장되므로, 같은 앱의 다른 사용자가 테이블을 봐도 내용을 못 읽는다.
+export async function loginWithGoogle() {
+    const sessionId = crypto.randomBytes(16).toString('hex');
+    const encKey = generateFrameKey();
+    const state = `cli-relay:${sessionId}:${encKey}`;
+    const cb = new ConnectBase({ appId: APP_ID, publicKey: PUBLIC_KEY });
+    const expiresAt = new Date(Date.now() + SESSION_TTL_MS).toISOString();
+    const created = await cb.database.createData(CLI_AUTH_SESSIONS_TABLE_ID, {
+        data: { session_id: sessionId, status: 'pending', expires_at: expiresAt },
+    });
+    const params = new URLSearchParams({ app_callback: WEB_LOGIN_URL, intent: 'signup', state });
+    const res = await fetch(`${API_BASE}/v1/public/oauth/google/authorize/central?${params}`, {
+        headers: { 'X-Public-Key': PUBLIC_KEY },
+    });
+    if (!res.ok) {
+        throw new Error(`구글 로그인 시작에 실패했어요 (HTTP ${res.status}).`);
+    }
+    const { authorization_url } = (await res.json());
+    console.log('브라우저에서 구글 로그인 창을 열게요. 완료하면 자동으로 이어져요...');
+    console.log(`(자동으로 안 열리면 이 주소를 직접 열어주세요: ${authorization_url})`);
+    openBrowser(authorization_url);
+    const deadline = Date.now() + LOGIN_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+        const { data: rows } = await cb.database.queryData(CLI_AUTH_SESSIONS_TABLE_ID, {
+            where: { session_id: sessionId },
+            limit: 1,
+        });
+        const row = rows[0];
+        if (!row)
+            continue;
+        if (row.data.status === 'completed' && row.data.encrypted_payload) {
+            cb.database.deleteData(CLI_AUTH_SESSIONS_TABLE_ID, row.id).catch(() => { });
+            const payload = JSON.parse(decryptFrame(row.data.encrypted_payload, encKey));
+            return {
+                accessToken: payload.access_token,
+                refreshToken: payload.refresh_token,
+                memberId: payload.member_id,
+            };
+        }
+    }
+    cb.database.deleteData(CLI_AUTH_SESSIONS_TABLE_ID, created.id).catch(() => { });
+    throw new Error('로그인 시간이 초과됐어요 (5분). 다시 시도해주세요.');
+}

package/dist/prompt.js

@@ -0,0 +1,23 @@
+import readline from 'node:readline';
+// y/n 승인 프롬프트 — 정해진 시간 안에 응답 없으면 자동 거부(false)
+export function promptApproval(question, timeoutMs) {
+    return new Promise((resolve) => {
+        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+        let done = false;
+        const finish = (result) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            rl.close();
+            resolve(result);
+        };
+        const timer = setTimeout(() => {
+            process.stdout.write('\n(시간 초과 — 자동으로 거부했어요)\n');
+            finish(false);
+        }, timeoutMs);
+        rl.question(question, (answer) => {
+            finish(answer.trim().toLowerCase().startsWith('y'));
+        });
+    });
+}

package/dist/recent-dirs.js

@@ -0,0 +1,23 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { CONFIG_DIR } from './config.js';
+const RECENT_DIRS_PATH = path.join(CONFIG_DIR, 'recent-dirs.json');
+const MAX_ENTRIES = 8;
+function load() {
+    try {
+        return JSON.parse(fs.readFileSync(RECENT_DIRS_PATH, 'utf8'));
+    }
+    catch {
+        return [];
+    }
+}
+// 지금 시작한 폴더를 맨 앞으로 올리고, 홈 디렉터리는 항상 후보에 포함시킴 (모바일 폴더 선택용)
+export function touchRecentDir(cwd) {
+    const home = os.homedir();
+    const existing = load().filter((dir) => dir !== cwd && dir !== home);
+    const updated = [cwd, home, ...existing].slice(0, MAX_ENTRIES);
+    fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(RECENT_DIRS_PATH, JSON.stringify(updated, null, 2), { mode: 0o600 });
+    return updated;
+}

package/dist/session.js

@@ -0,0 +1,148 @@
+import path from 'node:path';
+import * as pty from 'node-pty';
+import { requireClient, loadOrCreateDevice } from './auth.js';
+import { TERMINAL_CATEGORY } from './config.js';
+import { startSleepGuard, stopSleepGuard } from './sleep-guard.js';
+import { encryptFrame, decryptFrame } from './crypto.js';
+import { registerDevice, heartbeatDevice, markDeviceOffline } from './devices.js';
+import { promptApproval } from './prompt.js';
+import { touchRecentDir } from './recent-dirs.js';
+const HEARTBEAT_MS = 20_000;
+const APPROVAL_TIMEOUT_MS = 30_000;
+const SCROLLBACK_MAX = 16_000;
+function resolveShell() {
+    if (process.platform === 'win32')
+        return process.env.COMSPEC ?? 'powershell.exe';
+    return process.env.SHELL ?? '/bin/bash';
+}
+export async function startSession(options) {
+    const { cb, memberId } = await requireClient();
+    const device = loadOrCreateDevice();
+    const deviceName = options.name ?? device.deviceName;
+    const cwd = options.dir ? path.resolve(options.dir) : process.cwd();
+    console.log(`"${deviceName}" 세션을 시작해요 (작업 폴더: ${cwd})`);
+    const deviceRowId = await registerDevice(cb, {
+        ownerId: memberId,
+        deviceId: device.deviceId,
+        deviceName,
+        cwd,
+        frameKey: device.frameKey,
+        favoriteDirs: touchRecentDir(cwd),
+    });
+    const heartbeat = setInterval(() => {
+        heartbeatDevice(cb, deviceRowId).catch((err) => console.error('하트비트 실패:', err.message));
+    }, HEARTBEAT_MS);
+    await cb.realtime.connect({ userId: device.deviceId });
+    const channel = await cb.realtime.subscribe(TERMINAL_CATEGORY);
+    // 이 채널은 앱의 모든 멤버가 공유하므로, 프레임 내용(data)은 기기별 키로 암호화해서 주고받는다.
+    // 다른 사람이 같은 채널을 구독해도 to/kind 정도만 보이고 실제 터미널 내용은 못 읽음.
+    const shell = resolveShell();
+    const ptyProcess = pty.spawn(shell, [], {
+        name: 'xterm-256color',
+        cols: 80,
+        rows: 24,
+        cwd,
+        env: process.env,
+    });
+    // PTY 출력은 30ms 간격으로 모아서 전송 — 잦은 전송으로 메시지 수/요금이 불어나는 것 방지
+    let outBuffer = '';
+    const flush = async () => {
+        if (!outBuffer)
+            return;
+        const chunk = outBuffer;
+        outBuffer = '';
+        try {
+            await channel.send({
+                kind: 'output',
+                to: device.deviceId,
+                data: encryptFrame(chunk, device.frameKey),
+            }, { includeSelf: false });
+        }
+        catch (err) {
+            console.error('출력 전송 실패:', err.message);
+        }
+    };
+    const flushTimer = setInterval(() => void flush(), 30);
+    // 최근 출력을 조금 들고 있다가, 모바일이 (재)접속했을 때 놓친 화면 대신 다시 보여줌
+    let scrollback = '';
+    ptyProcess.onData((data) => {
+        outBuffer += data;
+        scrollback = (scrollback + data).slice(-SCROLLBACK_MAX);
+    });
+    // 모바일이 접속을 시도하면 데스크톱에서 승인해야만 입력이 먹힘 (읽기/출력은 항상 흐름 —
+    // 이미 같은 계정으로 로그인했다는 전제이므로, 승인은 "지금 이 순간 내가 타이핑을 넘겨줄지"
+    // 확인하는 용도). 승인 전에 온 input 프레임은 무시.
+    let inputApproved = false;
+    let approvalInFlight = false;
+    const stopMessages = channel.onMessage((msg) => {
+        const frame = msg.data;
+        if (!frame || frame.to !== device.deviceId)
+            return;
+        if (frame.kind === 'connect_request') {
+            // 화면 보기는 승인 여부와 무관하게 항상 되므로, 승인 물어보기 전에 최근 화면부터 먼저 채워줌
+            // (끊겼다 재접속한 경우든, 처음 들어온 경우든 동일하게 "방금까지 뭐가 있었는지" 보여줌)
+            if (scrollback) {
+                channel
+                    .send({ kind: 'output', to: device.deviceId, data: encryptFrame(scrollback, device.frameKey) }, { includeSelf: false })
+                    .catch((err) => console.error('화면 복구 전송 실패:', err.message));
+            }
+            if (approvalInFlight)
+                return;
+            approvalInFlight = true;
+            promptApproval('\n📱 모바일에서 접속을 요청했어요. 입력을 허용할까요? (y/N, 30초 내 미응답 시 자동 거부): ', APPROVAL_TIMEOUT_MS)
+                .then((approved) => {
+                inputApproved = approved;
+                approvalInFlight = false;
+                return channel.send({ kind: approved ? 'connect_approved' : 'connect_denied', to: device.deviceId }, { includeSelf: false });
+            })
+                .catch((err) => console.error('접속 승인 처리 실패:', err.message));
+            return;
+        }
+        if (frame.kind === 'input' && typeof frame.data === 'string') {
+            if (!inputApproved)
+                return;
+            try {
+                ptyProcess.write(decryptFrame(frame.data, device.frameKey));
+            }
+            catch (err) {
+                console.error('입력 복호화 실패 (다른 기기 키로 보낸 프레임?):', err.message);
+            }
+        }
+        else if (frame.kind === 'resize' && frame.cols && frame.rows) {
+            ptyProcess.resize(frame.cols, frame.rows);
+        }
+    });
+    startSleepGuard();
+    let shuttingDown = false;
+    const shutdown = async () => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        clearInterval(flushTimer);
+        clearInterval(heartbeat);
+        await flush();
+        stopMessages();
+        stopSleepGuard();
+        try {
+            await channel.unsubscribe();
+        }
+        catch {
+            // 이미 끊겼으면 무시
+        }
+        try {
+            await markDeviceOffline(cb, deviceRowId);
+        }
+        catch {
+            // 오프라인 표시 실패해도 종료는 계속 진행
+        }
+        cb.realtime.disconnect();
+        ptyProcess.kill();
+        process.exit(0);
+    };
+    process.on('SIGINT', () => void shutdown());
+    process.on('SIGTERM', () => void shutdown());
+    ptyProcess.onExit(() => {
+        console.log('셸이 종료돼서 세션도 함께 종료해요.');
+        void shutdown();
+    });
+}

package/dist/sleep-guard.js

@@ -0,0 +1,47 @@
+import { spawn } from 'node:child_process';
+let guard = null;
+// 세션이 떠 있는 동안만 컴퓨터가 절전 모드로 들어가지 않게 막고,
+// 세션이 끝나면(stopSleepGuard) 바로 풀어서 평소엔 정상적으로 절전되게 함.
+export function startSleepGuard() {
+    if (guard)
+        return;
+    if (process.platform === 'darwin') {
+        // -w PID: 우리 프로세스가 죽으면 caffeinate 도 자동으로 함께 종료됨
+        guard = spawn('caffeinate', ['-i', '-w', String(process.pid)], { stdio: 'ignore' });
+        guard.on('error', () => {
+            console.warn('절전 방지(caffeinate) 실행에 실패했어요 — 세션 중 컴퓨터가 잠들 수 있어요.');
+            guard = null;
+        });
+        return;
+    }
+    if (process.platform === 'linux') {
+        guard = spawn('systemd-inhibit', ['--what=sleep', '--why=ShellBase session active', 'sleep', 'infinity'], { stdio: 'ignore' });
+        guard.on('error', () => {
+            console.warn('절전 방지(systemd-inhibit)를 못 찾았어요 — 세션 중 컴퓨터가 잠들 수 있어요. (systemd 없는 배포판인가요?)');
+            guard = null;
+        });
+        return;
+    }
+    if (process.platform === 'win32') {
+        // Win32 SetThreadExecutionState(ES_CONTINUOUS | ES_SYSTEM_REQUIRED | ES_DISPLAY_REQUIRED)
+        // 를 PowerShell에서 P/Invoke로 호출 — 이 powershell 프로세스가 살아있는 동안 절전이 안 됨.
+        // caffeinate 의 "-w PID" 같은 부모 프로세스 자동 연동은 없어서, stopSleepGuard()에서 직접 kill.
+        const script = 'Add-Type -Name Win32 -Namespace ShellBase -MemberDefinition ' +
+            '\'[DllImport("kernel32.dll")] public static extern uint SetThreadExecutionState(uint esFlags);\'; ' +
+            '[ShellBase.Win32]::SetThreadExecutionState(0x80000003) | Out-Null; ' +
+            'while ($true) { Start-Sleep -Seconds 60 }';
+        guard = spawn('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', script], {
+            stdio: 'ignore',
+        });
+        guard.on('error', () => {
+            console.warn('절전 방지(PowerShell) 실행에 실패했어요 — 세션 중 컴퓨터가 잠들 수 있어요.');
+            guard = null;
+        });
+        return;
+    }
+    console.warn('이 운영체제에서는 절전 방지를 자동으로 못 해요 — 세션 중에는 컴퓨터가 잠들지 않게 직접 설정해주세요.');
+}
+export function stopSleepGuard() {
+    guard?.kill();
+    guard = null;
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "shellbase",
+  "version": "0.1.0",
+  "description": "내 컴퓨터 터미널(특히 Claude Code 세션)을 폰 브라우저로 실시간 접속하게 해주는 데스크톱 에이전트",
+  "type": "module",
+  "bin": {
+    "shellbase": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "keywords": [
+    "cli",
+    "terminal",
+    "remote",
+    "pty",
+    "claude-code",
+    "mobile"
+  ],
+  "scripts": {
+    "dev": "tsx src/cli.ts",
+    "build": "tsc",
+    "start": "node dist/cli.js"
+  },
+  "dependencies": {
+    "commander": "^15.0.0",
+    "connectbase-client": "^5.13.0",
+    "node-pty": "^1.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsx": "^4.23.12",
+    "typescript": "^6.0.2"
+  }
+}