shellbase 0.7.2 → 0.8.0

package/README.md

@@ -167,7 +167,11 @@ shellbase start --no-restore     # 복구하지 않고 이 폴더 세션 하나
 컴퓨터가 꺼지지 않는 이상 자동으로 살아있게 하고 싶다면(예: 항상 켜져 있는 리눅스 서버), 아래처럼
 OS의 자동 재시작 기능을 직접 설정하면 됩니다. **실제로 테스트해서 확인한 방법이에요:**
 
-### Linux (systemd, 실제 검증됨)
+### Linux (systemd, 실제 검증됨) — **권장**
+
+> 도커로 감싸는 것보다 이 방법을 권합니다. 컨테이너 안에서는 그 터미널이 호스트의 `docker`·`systemctl`·
+> 다른 컨테이너·호스트 서비스에 손을 댈 수 없어서, 정작 컴퓨터를 관리하려고 폰에서 접속했을 때 막힙니다.
+> systemd 로 띄우면 재부팅 자동 복구는 똑같이 되면서 터미널 권한은 온전합니다.
 
 ```bash
 mkdir -p ~/.config/systemd/user
@@ -211,7 +215,13 @@ systemctl --user enable --now shellbase.service
 작업 스케줄러(Task Scheduler)에서 "로그온 시 시작" + "실패 시 다시 시작" 옵션으로 등록하면 비슷하게
 됩니다. 아직 저희가 Windows에서 직접 검증은 못 했어요.
 
-### Docker (Linux, 실제 검증됨)
+### Docker (Linux, 실제 검증됨) — 격리가 꼭 필요할 때만
+
+> ⚠️ **컨테이너 안 터미널은 호스트 시스템에 손이 닿지 않습니다.** 파일 작업(프로젝트 편집·빌드·git)은
+> 홈 폴더를 마운트하므로 100% 동일하지만, `docker`/`systemctl`/다른 컨테이너/호스트 서비스는 못 씁니다
+> (도커의 정상적인 격리 동작). 컴퓨터 관리까지 폰에서 하려면 위의 systemd 방식을 쓰세요.
+> `/var/run/docker.sock` 을 마운트하면 도커 제어는 가능해지지만, 그 순간 컨테이너가 호스트 전체를
+> 조종할 수 있게 되어 격리의 의미가 사라집니다 — 권하지 않습니다.
 
 컨테이너 안은 이 컴퓨터의 실제 환경과 분리돼 있어서, 홈 폴더를 통째로 볼륨(`-v`)으로 연결해야
 git 설정·SSH 키·진짜 작업 파일들이 컨테이너 밖과 똑같이 보여요. 아래는 실제로 빌드해서 재부팅 시나리오

package/dist/agent.js

@@ -3,6 +3,11 @@ import path from 'node:path';
 import os from 'node:os';
 import crypto from 'node:crypto';
 import * as pty from 'node-pty';
+import { createRequire } from 'node:module';
+import { SerializeAddon } from '@xterm/addon-serialize';
+// @xterm/headless 는 CommonJS 라 ESM 이름 가져오기가 안 돼서(default 만 노출) require 로 가져온다
+const requireCjs = createRequire(import.meta.url);
+const { Terminal: HeadlessTerminal } = requireCjs('@xterm/headless');
 import { requireClient } from './auth.js';
 import { TERMINAL_CATEGORY, CONTROL_TOKEN } from './config.js';
 import { startSleepGuard, stopSleepGuard } from './sleep-guard.js';
@@ -14,10 +19,15 @@ import { listDirs } from './browse.js';
 import { readTextFile, writeTextFile, chunkContent } from './files.js';
 import { AUDIO_CHUNK_TTL_MS, MAX_AUDIO_BASE64, STT_SETUP_HINT, findSttServer, transcribe, } from './stt.js';
 import { loadOpenSessions, saveOpenSessions } from './open-sessions.js';
-import { IMAGE_CHUNK_TTL_MS, saveImage } from './images.js';
+import { IMAGE_CHUNK_TTL_MS, pruneImages, saveImage } from './images.js';
 const HEARTBEAT_MS = 20_000;
+// 올린 사진 정리 주기 — 보관 기한이 하루라, 오래 켜둔 컴퓨터에서도 반나절 안에 치워진다
+const IMAGE_SWEEP_MS = 6 * 60 * 60 * 1000;
 const APPROVAL_TIMEOUT_MS = 30_000;
-const SCROLLBACK_MAX = 16_000;
+// 복원해서 보낼 때 함께 보낼 이전 줄 수 (화면 위로 올려볼 수 있는 분량)
+const RESTORE_SCROLLBACK_LINES = 300;
+// 프레임 하나에 들어갈 수 있는 크기가 제한돼 있어서(실측 16KB 성공/64KB 실패) 나눠 보낸다
+const RESTORE_CHUNK = 12 * 1024;
 // 출력 전송 최소 간격. "마지막 전송 후 이 간격이 지났으면 바로 보내고, 아니면 그만큼만 기다렸다 모아서
 // 보낸다"(leading-edge 스로틀). 예전엔 문서의 "최소 100ms" 를 보수적으로 잡아 120ms 로 뒀는데, 실측해보니
 // 서버가 40회 연속 전송도 거부 없이 받아줬고 이 값이 타이핑 체감 지연의 주범이었음(입력·출력 양쪽에서
@@ -179,7 +189,13 @@ export async function runAgent(options) {
                 cwd,
                 env: process.env,
             }),
-            scrollback: '',
+            screen: new HeadlessTerminal({
+                cols: 80,
+                rows: 24,
+                scrollback: 2000,
+                allowProposedApi: true,
+            }),
+            serializer: new SerializeAddon(),
             inputApproved: false,
             approvalInFlight: false,
             outBuffer: '',
@@ -188,10 +204,11 @@ export async function runAgent(options) {
             pendingFlush: null,
             closing: false,
         };
+        session.screen.loadAddon(session.serializer);
         session.pty.onData((data) => {
             session.outBuffer += data;
-            // 최근 출력을 조금 들고 있다가, 모바일이 (재)접속했을 때 놓친 화면 대신 다시 보여줌
-            session.scrollback = (session.scrollback + data).slice(-SCROLLBACK_MAX);
+            // 화면 상태를 그대로 따라 그려둔다 (재접속 복원용)
+            session.screen.write(data);
             scheduleFlush(session);
         });
         session.pty.onExit(() => {
@@ -242,6 +259,7 @@ export async function runAgent(options) {
         catch {
             // 이미 죽었으면 무시
         }
+        session.screen.dispose();
         if (opts.deliberate)
             persistOpenSessions();
         console.log(`"${session.name}" 세션을 닫았어요. (남은 세션 ${sessions.size}개)`);
@@ -258,6 +276,7 @@ export async function runAgent(options) {
             return;
         shuttingDown = true;
         clearInterval(heartbeat);
+        clearInterval(imageSweep);
         for (const session of [...sessions.values()]) {
             session.closing = true;
             if (session.pendingFlush !== null)
@@ -303,14 +322,26 @@ export async function runAgent(options) {
         if (!session || session.closing)
             return;
         if (frame.kind === 'connect_request') {
-            // 화면 보기는 승인 여부와 무관하게 항상 되므로, 승인을 묻기 전에 최근 화면부터 먼저 채워줌
-            if (session.scrollback) {
-                void send({
-                    kind: 'output',
-                    to: session.deviceId,
-                    data: encryptFrame(session.scrollback, session.frameKey),
-                });
-            }
+            // 화면 보기는 승인 여부와 무관하게 항상 되므로, 승인을 묻기 전에 지금 화면부터 그대로 복원해준다.
+            // 화면을 먼저 지우고(2J·3J) 복원 내용을 보내야, 폰에 남아있던 예전 화면과 섞이지 않는다.
+            void (async () => {
+                let snapshot;
+                try {
+                    snapshot = session.serializer.serialize({ scrollback: RESTORE_SCROLLBACK_LINES });
+                }
+                catch (err) {
+                    console.error('화면 복원 준비 실패:', err.message);
+                    return;
+                }
+                const payload = `\x1b[H\x1b[2J\x1b[3J${snapshot}`;
+                for (let i = 0; i < payload.length; i += RESTORE_CHUNK) {
+                    await send({
+                        kind: 'output',
+                        to: session.deviceId,
+                        data: encryptFrame(payload.slice(i, i + RESTORE_CHUNK), session.frameKey),
+                    });
+                }
+            })();
             // 승인을 묻지 않는 기본 설정에서는 요청이 올 때마다 곧바로 답한다.
             // (예전엔 "승인 진행 중"이면 건너뛰었는데, 그 사이 온 요청은 영영 답을 못 받아서
             //  폰이 "승인 대기 중" 화면에 갇히는 일이 생겼음 — 자동 승인은 기다릴 게 없으므로 항상 응답)
@@ -576,6 +607,13 @@ export async function runAgent(options) {
         }
         if (frame.kind === 'resize' && frame.cols && frame.rows) {
             session.pty.resize(frame.cols, frame.rows);
+            // 복원용 화면도 같은 크기로 맞춰야 다음 접속 때 줄바꿈이 어긋나지 않는다
+            try {
+                session.screen.resize(frame.cols, frame.rows);
+            }
+            catch {
+                // 크기 값이 이상하면 무시 (PTY 는 이미 반영됨)
+            }
         }
     });
     const heartbeat = setInterval(() => {
@@ -592,6 +630,16 @@ export async function runAgent(options) {
             ? `🎤 음성인식 서버를 찾았어요: ${url} — 폰에서 마이크로 말할 수 있어요.`
             : '🎤 음성인식 서버가 없어요 — 폰 마이크 기능은 꺼진 상태예요 (SHELLBASE_STT_URL 로 주소를 지정할 수 있어요).');
     });
+    // 올린 사진은 하루가 지나면 치운다. 예전엔 "새 사진을 저장할 때"만 청소해서, 사진을 한동안 안 올리면
+    // 기한이 지난 파일이 계속 남아 있었다 — 시작할 때 한 번, 그리고 켜져 있는 동안 주기적으로도 돌린다.
+    const removedAtStart = pruneImages();
+    if (removedAtStart > 0)
+        console.log(`🧹 하루 지난 사진 ${removedAtStart}장을 정리했어요.`);
+    const imageSweep = setInterval(() => {
+        const removed = pruneImages();
+        if (removed > 0)
+            console.log(`🧹 하루 지난 사진 ${removed}장을 정리했어요.`);
+    }, IMAGE_SWEEP_MS);
     startSleepGuard();
     process.on('SIGINT', () => void shutdownProcess());
     process.on('SIGTERM', () => void shutdownProcess());

package/dist/images.js

@@ -9,8 +9,9 @@ export const IMAGE_DIR = join(homedir(), '.shellbase', 'images');
 export const IMAGE_CHUNK_TTL_MS = 180_000;
 // base64 글자 수 상한 (약 6MB 원본). 폰에서 이미 줄여서 보내지만 안전장치로 둔다.
 export const MAX_IMAGE_BASE64 = 8 * 1024 * 1024;
-// 올린 지 오래된 사진은 저장할 때마다 조용히 치운다 (디스크가 계속 차지 않게)
-const KEEP_MS = 7 * 24 * 60 * 60 * 1000;
+// 올린 지 오래된 사진은 조용히 치운다 (디스크가 계속 차지 않게).
+// 사진은 "경로를 터미널에 넣어 바로 쓰는" 임시 파일이라 하루면 충분 — 오래 두면 쌓이기만 한다.
+export const IMAGE_KEEP_MS = 24 * 60 * 60 * 1000;
 const EXT_BY_TYPE = {
     'image/png': 'png',
     'image/jpeg': 'jpg',
@@ -18,14 +19,20 @@ const EXT_BY_TYPE = {
     'image/webp': 'webp',
     'image/gif': 'gif',
 };
-function pruneOld() {
+// 오래된 사진 치우기 — 지운 개수를 돌려준다(시작할 때 안내를 찍으려고).
+// 저장할 때뿐 아니라 `shellbase start` 와 하루 주기 타이머에서도 부른다: 예전엔 저장할 때만 돌아서
+// 사진을 한동안 안 올리면 기한이 지난 파일이 계속 남아 있었다.
+export function pruneImages() {
+    let removed = 0;
     try {
         const now = Date.now();
         for (const name of readdirSync(IMAGE_DIR)) {
             const full = join(IMAGE_DIR, name);
             try {
-                if (now - statSync(full).mtimeMs > KEEP_MS)
+                if (now - statSync(full).mtimeMs > IMAGE_KEEP_MS) {
                     unlinkSync(full);
+                    removed += 1;
+                }
             }
             catch {
                 // 지우다 실패해도 사진 저장 자체를 막지는 않는다
@@ -35,6 +42,7 @@ function pruneOld() {
     catch {
         // 폴더가 아직 없으면 지울 것도 없다
     }
+    return removed;
 }
 // 두 자리로 맞춘 시간 문자열 (파일 이름이 시간순으로 정렬되게)
 function stamp(date) {
@@ -60,7 +68,7 @@ export function saveImage(base64, mime) {
         return { ok: false, reason: '사진이 비어 있어요. 다시 골라주세요.' };
     try {
         mkdirSync(IMAGE_DIR, { recursive: true });
-        pruneOld();
+        pruneImages();
         // 같은 초에 여러 장을 올려도 안 겹치도록 뒤에 짧은 임의 글자를 붙인다
         const suffix = Math.random().toString(36).slice(2, 6);
         const path = join(IMAGE_DIR, `${stamp(new Date())}-${suffix}.${ext}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shellbase",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "description": "내 컴퓨터 터미널(특히 Claude Code 세션)을 폰 브라우저로 실시간 접속하게 해주는 데스크톱 에이전트",
   "type": "module",
   "bin": {
@@ -27,6 +27,8 @@
     "start": "node dist/cli.js"
   },
   "dependencies": {
+    "@xterm/addon-serialize": "^0.14.0",
+    "@xterm/headless": "^6.0.0",
     "commander": "^15.0.0",
     "connectbase-client": "^5.13.0",
     "node-pty": "^1.1.0"