shellbase 0.13.6 → 0.14.0

package/README.md

@@ -158,11 +158,28 @@ Claude Code 가 화면을 꽉 채우고 있을 때 `git status` 같은 걸 잠
 - 모나코에서 **JS/TS 타입 기반 자동완성은 빠져 있어요** (그 기능 파일 하나가 6.6MB 라 웹 스토리지 한도를
   넘습니다). 색칠·단축키·검색은 모두 정상이에요.
 
-- 512KB 까지, **글자 파일만** 열려요 (사진·실행파일 같은 이진 파일은 자동으로 걸러집니다)
+- 512KB 까지, **글자 파일만** 열려요 (사진·동영상은 아래의 보기 창으로 열립니다)
 - 저장은 같은 폴더의 임시 파일에 먼저 쓴 뒤 교체해서, 저장 도중 끊겨도 원본이 깨지지 않아요
 - 파일 내용은 터미널 화면과 똑같이 세션 키로 암호화해서 주고받아요
 - 에디터는 **파일을 처음 열 때만 따로 내려받아요** — 터미널만 쓰면 그만큼 안 받습니다
 
+### 사진·동영상 보기 (0.14.0+)
+
+폴더 찾기에서 **사진(🖼)·동영상(🎬)·소리(🎵)·PDF(📕)** 를 탭하면 편집기 대신 **보기 창**이 열려서
+폰에서 그대로 보입니다. 동영상은 재생·되감기까지 돼요.
+
+- 열리는 형식: `png jpg gif webp avif bmp heic tif` · `mp4 mov m4v webm mkv avi` ·
+  `mp3 m4a aac wav ogg opus flac` · `pdf`
+- **64MB 까지**, 그리고 **3MB 가 넘으면 "받을까요?" 를 한 번 물어봐요** — 파일이 터미널 화면과
+  **같은 통로**로 오기 때문에, 큰 동영상을 잘못 누르면 그동안 터미널이 굼떠집니다
+- 받는 동안 진행 막대가 보이고 **그만두기**를 누르면 곧바로 멈춰요 (컴퓨터 쪽도 바로 손을 뗍니다)
+- 속도는 **초당 300KB 남짓**이에요 (실측) — 3MB 사진이면 10초쯤, 10MB 동영상이면 35초쯤
+- 사진은 눌러서 **원래 크기 ↔ 화면 맞추기**를 오갈 수 있어요
+- 파일은 32KB 조각으로 나눠 **세션 키로 암호화**해서 오고, 폰에서만 다시 하나로 붙습니다 —
+  중간에 저장되는 곳은 없어요
+- 브라우저가 못 여는 형식(아이폰 밖에서의 HEIC, mkv·avi 등)은 그렇게 알려주고, **경로를
+  터미널에 넣어주는 버튼**을 보여줘요 — 그 자리에서 `ffmpeg` 로 바꾸면 됩니다
+
 ### 폰에서 사진·스크린샷 첨부 (0.7.0+)
 
 폰 화면의 **클립(📎) 버튼**(PC 는 상단 바)으로 사진을 고르면, 사진이 **이 컴퓨터의
@@ -173,7 +190,7 @@ Claude Code 가 화면을 꽉 채우고 있을 때 `git status` 같은 걸 잠
 - **PC 는 스크린샷 파일을 터미널 위로 끌어다 놓으면(드래그&드롭)** 바로 첨부돼요 (📎 버튼은 폰 전용)
 - 스크린샷을 **복사해서 붙여넣기**(Ctrl+V) 해도 첨부돼요 (PC·폰 공통)
 - 사진은 보내기 전에 폰에서 **긴 변 1568px 로 줄여서** 올라가요(전송이 빠르고 인식 정확도는 그대로)
-- 저장된 사진은 **7일이 지나면 자동으로 지워져요**, 파일 권한은 본인만 읽기(600)
+- 저장된 사진은 **하루가 지나면 자동으로 지워져요**, 파일 권한은 본인만 읽기(600)
 - 사진도 터미널 화면과 똑같이 **세션 키로 암호화**해서 전송돼요
 
 ### 폰에서 마이크로 말하기 (음성 → 글자)
@@ -207,6 +224,23 @@ Claude Code 가 화면을 꽉 채우고 있을 때 `git status` 같은 걸 잠
 > 끄는 건 프로세스가 계속 살아있으니 그대로 꺼져요. 컨테이너를 완전히 내리려면 컴퓨터에서
 > `docker stop shellbase-agent` 를 쓰세요.
 
+### 터미널은 셸 시작 파일(rc)을 읽지 않아요
+
+폰에서 여는 터미널은 `~/.bashrc`(zsh 는 `~/.zshrc`) 같은 **시작 파일을 읽지 않고** 맨 셸로 뜹니다
+(`bash --norc --noprofile`, `zsh --no-rcs`, `fish --no-config`, PowerShell `-NoProfile`).
+
+시작 파일은 그 컴퓨터 앞에 앉은 사람이 자기 편하려고 꾸며둔 것이라, 그 컴퓨터에만 있는 명령을
+가리키는 별칭이 흔합니다. 그게 딸려오면 다른 환경에서 명령이 엉뚱하게 깨져요
+(`bash: gnuls: command not found` 같은 증상).
+
+- 대신 **에이전트를 켤 때의 환경변수(PATH 포함)를 그대로 물려받습니다.** 그래서 `shellbase` 를
+  실행할 수 있던 셸에서 켰다면 `claude` 같은 명령은 그대로 잘 찾습니다.
+- 시작 파일에서만 붙던 것(conda 초기화, 개인 별칭, 특정 도구 경로)은 안 따라옵니다.
+  필요하면 그 줄을 **에이전트를 켜는 쪽**에 넣거나, 세션 안에서 그때그때 불러 쓰세요
+  (예: `source ~/miniconda3/etc/profile.d/conda.sh`).
+- 예전처럼 시작 파일을 읽게 하려면 `SHELLBASE_SHELL_RC=1 shellbase start …` 로 켜세요.
+- 프롬프트는 꾸밈 없는 기본값(`bash-5.2$`)이 됩니다.
+
 ## 참고
 
 - `node-pty` 를 사용해서 설치 시 네이티브 모듈을 컴파일합니다. macOS는 Xcode Command Line Tools,

package/dist/agent.js

@@ -17,6 +17,7 @@ import { promptApproval } from './prompt.js';
 import { touchRecentDir } from './recent-dirs.js';
 import { listDirs, createEntry, deleteEntry, renameEntry } from './browse.js';
 import { readTextFile, writeTextFile, chunkContent } from './files.js';
+import { MediaReader, statMedia } from './media.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 { pushSessionDone } from './push.js';
@@ -61,6 +62,18 @@ const MAX_PACK_DEPTH = 12;
 // 전송이 막혀 밀린 출력이 이만큼을 넘으면, 밀린 것을 하나하나 따라 보내는 대신 지금 화면을 통째로
 // 다시 보낸다 — 사용자가 보게 될 최종 화면은 어차피 같고, 훨씬 빨리 따라잡는다.
 const MAX_PENDING_OUTPUT = 256 * 1024;
+// 사진·동영상을 보낼 때 서버 답을 안 기다리고 잇달아 부치는 조각 수.
+// 하나씩 답을 기다리면 조각마다 왕복 한 번(실측 276ms)이 그대로 지연이 되어 3MB 사진에 몇 분이
+// 걸린다. 그렇다고 통째로 부치면 터미널 화면이 그 뒤로 밀린다 — 통로를 세션들이 나눠 쓰기 때문.
+//
+// **8이면 충분하다는 것은 실측으로 확인했다** (3MB 사진, 2026-08-21):
+// 16·32 로 넓혀도 빨라지지 않았다 (229 → 173 → 183KB/s). 병목이 "답을 기다리는 시간" 이 아니라
+// **통로의 굵기**라는 뜻이다. 그러니 더 넓혀봐야 터미널만 뒤로 밀린다.
+// 올리기만 하는 속도는 394KB/s — 폰은 받는 길이 따로라 실제로는 이쪽에 가깝다.
+const MEDIA_WINDOW = 8;
+// 조각 하나가 실패했을 때 다시 부쳐보는 횟수. 이진 파일은 한 조각만 빠져도 아예 안 열리므로
+// 글자 파일보다 끈질기게 다시 보낸다.
+const MEDIA_RETRIES = 3;
 // 출력 전송 최소 간격. "마지막 전송 후 이 간격이 지났으면 바로 보내고, 아니면 그만큼만 기다렸다 모아서
 // 보낸다"(leading-edge 스로틀). 예전엔 문서의 "최소 100ms" 를 보수적으로 잡아 120ms 로 뒀는데, 실측해보니
 // 서버가 40회 연속 전송도 거부 없이 받아줬고 이 값이 타이핑 체감 지연의 주범이었음(입력·출력 양쪽에서
@@ -173,6 +186,40 @@ function resolveShell() {
         return process.env.COMSPEC ?? 'powershell.exe';
     return process.env.SHELL ?? '/bin/bash';
 }
+// 폰에서 여는 터미널은 셸의 '시작 파일'(bash 의 ~/.bashrc, zsh 의 ~/.zshrc 같은 것)을 읽지 않는다.
+// 시작 파일은 그 컴퓨터의 사람이 앉아서 쓰려고 꾸며둔 것이라, 그 컴퓨터에만 있는 명령을 가리키는
+// 별칭이 흔하다. 그게 그대로 딸려오면 엉뚱한 곳에서 명령이 깨진다 (`gnuls: command not found`
+// 사건 — PLAN.md §8.12). 그래서 껍데기 셸만 띄우고, 실행에 필요한 경로·환경변수는 시작 파일이
+// 아니라 **에이전트를 켤 때의 환경**을 그대로 물려주는 쪽으로 통일한다 (sessionEnv 참고).
+// 예전처럼 시작 파일을 읽게 하려면 SHELLBASE_SHELL_RC=1 을 주고 에이전트를 다시 시작하면 된다.
+function shellArgs(shell) {
+    if (process.env.SHELLBASE_SHELL_RC)
+        return [];
+    const name = path.basename(shell).toLowerCase();
+    // 로그인용 파일(~/.profile 등)은 애초에 로그인 셸일 때만 읽히지만, 혹시 몰라 같이 막아둔다
+    if (name.includes('bash'))
+        return ['--norc', '--noprofile'];
+    if (name.includes('zsh'))
+        return ['--no-rcs'];
+    if (name.includes('fish'))
+        return ['--no-config'];
+    if (name.includes('pwsh') || name.includes('powershell'))
+        return ['-NoProfile'];
+    // sh·dash·ksh 는 이런 옵션이 없고 $ENV / $BASH_ENV 에 적힌 파일을 읽는다 — 그건 sessionEnv 에서 지운다
+    return [];
+}
+// 이 터미널이 어느 세션인지 환경변수로 심어둔다. 이 안에서 실행되는 모든 것(Claude Code,
+// 그리고 Claude Code 가 끝날 때 실행하는 `shellbase notify`)이 그대로 물려받으므로,
+// 알림이 왔을 때 어느 세션인지 바로 알 수 있다 (notify.ts).
+function sessionEnv(deviceId) {
+    const env = { ...process.env, [SESSION_ENV]: deviceId };
+    if (!process.env.SHELLBASE_SHELL_RC) {
+        // sh·dash·ksh 계열은 옵션 대신 이 변수에 적힌 파일을 시작하면서 읽는다 — 같이 비운다
+        delete env.ENV;
+        delete env.BASH_ENV;
+    }
+    return env;
+}
 function readControl(data, key) {
     if (typeof data !== 'string')
         return null;
@@ -735,15 +782,12 @@ export async function runAgent(options) {
             name: explicitName ?? (temporary ? `${defaultName(cwd)} (임시)` : defaultName(cwd)),
             cwd,
             rowId: '',
-            pty: pty.spawn(shell, [], {
+            pty: pty.spawn(shell, shellArgs(shell), {
                 name: 'xterm-256color',
                 cols: 80,
                 rows: 24,
                 cwd,
-                // 이 터미널이 어느 세션인지 환경변수로 심어둔다. 이 안에서 실행되는 모든 것(Claude Code,
-                // 그리고 Claude Code 가 끝날 때 실행하는 `shellbase notify`)이 그대로 물려받으므로,
-                // 알림이 왔을 때 어느 세션인지 바로 알 수 있다 (notify.ts).
-                env: { ...process.env, [SESSION_ENV]: deviceId },
+                env: sessionEnv(deviceId),
             }),
             screen: new HeadlessTerminal({
                 cols: 80,
@@ -777,6 +821,7 @@ export async function runAgent(options) {
             viewerSeenAt: Date.now(),
             // 폰이 접속하면서 "압축 읽을 수 있다" 고 알려주기 전까지는 압축하지 않는다
             gzipOk: false,
+            mediaId: null,
         };
         session.screen.loadAddon(session.serializer);
         session.pty.onData((data) => {
@@ -1095,6 +1140,96 @@ export async function runAgent(options) {
                 console.log(`📱 폰에서 파일을 저장했어요: ${filePath}`);
             return;
         }
+        // 폰에서 사진·동영상·소리 파일 보기 — **두 걸음**으로 나눠서 준다.
+        //   ① { path } 만 오면 "무슨 파일이고 얼마나 큰지"(media_meta)만 알려준다
+        //   ② 폰이 { path, mid, start: true } 로 다시 물어야 그때 조각을 보낸다
+        // 한 걸음으로 하면 동영상을 잘못 누른 순간 수십 MB 가 통로로 쏟아진다. 크기를 먼저 알려주면
+        // 폰이 "40MB 예요, 받을까요?" 를 물어본 뒤에 시작할 수 있다.
+        if (frame.kind === 'read_media') {
+            const control = readControl(frame.data, session.frameKey);
+            if (!control || typeof control.path !== 'string')
+                return;
+            const filePath = control.path;
+            const mid = typeof control.mid === 'string' ? control.mid : '';
+            const fail = (reason) => void send({
+                kind: 'media_error',
+                to: session.deviceId,
+                data: encryptFrame(JSON.stringify({ path: filePath, mid, reason }), session.frameKey),
+            });
+            // 「그만두기」 — 보내던 것을 멈추기만 한다 (보내는 쪽이 조각마다 이 표를 확인한다)
+            if (control.stop) {
+                if (!mid || session.mediaId === mid)
+                    session.mediaId = null;
+                return;
+            }
+            const info = statMedia(filePath);
+            if (!info.ok) {
+                fail(info.reason);
+                return;
+            }
+            if (!control.start) {
+                void send({
+                    kind: 'media_meta',
+                    to: session.deviceId,
+                    data: encryptFrame(JSON.stringify({
+                        path: filePath,
+                        mid,
+                        mime: info.mime,
+                        kind: info.kind,
+                        size: info.size,
+                        total: info.total,
+                    }), session.frameKey),
+                });
+                return;
+            }
+            // 새 받기가 시작되면 앞서 보내던 것은 스스로 멈춘다 (표가 바뀌었으므로)
+            session.mediaId = mid;
+            void (async () => {
+                let reader;
+                try {
+                    reader = new MediaReader(info);
+                }
+                catch (err) {
+                    fail(`파일을 열지 못했어요: ${err.message}`);
+                    return;
+                }
+                try {
+                    for (let from = 0; from < info.total; from += MEDIA_WINDOW) {
+                        if (session.mediaId !== mid || session.closing)
+                            return;
+                        const to = Math.min(from + MEDIA_WINDOW, info.total);
+                        let pending = [];
+                        for (let index = from; index < to; index++)
+                            pending.push(index);
+                        for (let attempt = 0; attempt < MEDIA_RETRIES && pending.length > 0; attempt++) {
+                            const results = await Promise.allSettled(pending.map((index) => sendFrame({
+                                kind: 'media_chunk',
+                                to: session.deviceId,
+                                mid,
+                                seq: index,
+                                total: info.total,
+                                data: encryptBytes(reader.chunk(index), session.frameKey),
+                            })));
+                            if (session.mediaId !== mid)
+                                return;
+                            pending = pending.filter((_, at) => results[at].status === 'rejected');
+                        }
+                        if (pending.length > 0) {
+                            fail('보내는 도중에 통로가 막혔어요. 잠시 뒤 다시 받아보세요.');
+                            return;
+                        }
+                    }
+                    const label = { image: '사진', video: '동영상', audio: '소리', pdf: 'PDF' }[info.kind];
+                    console.log(`📱 폰으로 ${label} 을 보냈어요: ${filePath}`);
+                }
+                finally {
+                    reader.close();
+                    if (session.mediaId === mid)
+                        session.mediaId = null;
+                }
+            })();
+            return;
+        }
         // 폰에서 마이크로 말한 녹음 — 조각이 다 모이면 이 컴퓨터의 음성인식 서버로 넘겨 글자로 돌려준다.
         // 녹음은 인터넷의 다른 음성인식 서비스로 나가지 않고 이 컴퓨터 안에서만 처리된다.
         if (frame.kind === 'stt_audio') {

package/dist/media.js

@@ -0,0 +1,139 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+// 폰에서 사진·동영상·소리 파일을 **보이게** 하는 부분.
+// 글자 파일(files.ts)과 통로는 같지만 다루는 것이 다르다:
+//   · 글자는 조각을 이어 붙이면 그만이지만, 이진 파일은 한 바이트라도 틀리면 아예 안 열린다
+//   · 크기가 글자 파일과 자릿수가 다르다 (메모 몇 KB ↔ 동영상 수십 MB)
+// 그래서 base64 를 한 겹 더 씌우지 않고 **바이트 그대로 암호화해서**(crypto.ts 의 encryptBytes)
+// 보낸다 — 같은 프레임에 3분의 1을 더 실을 수 있다.
+// 한 조각에 담는 원본 바이트 수. 암호화하면 base64 로 약 1.34배가 되므로
+// 32KB → 약 43KB 로, 프레임 한도(56KB)에 여유를 두고 들어간다.
+export const MEDIA_CHUNK_BYTES = 32 * 1024;
+// 이보다 큰 파일은 아예 보내지 않는다. 실시간 통로는 터미널 화면과 **같이 쓰는 길**이라
+// (세션 여럿이 채널 하나를 나눠 쓴다) 너무 큰 파일은 그동안 터미널을 굼뜨게 만든다.
+export const MAX_MEDIA_SIZE = 64 * 1024 * 1024;
+// 확장자로 어떤 종류인지 본다. 파일 안을 뜯어보지 않는 이유는, 폰 브라우저도 결국
+// 여기서 정한 종류(mime)를 믿고 재생하기 때문이다 — 판단 기준을 한 곳에만 두는 편이 낫다.
+const MIME_BY_EXT = {
+    // 사진
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    gif: 'image/gif',
+    webp: 'image/webp',
+    avif: 'image/avif',
+    bmp: 'image/bmp',
+    ico: 'image/x-icon',
+    heic: 'image/heic',
+    heif: 'image/heif',
+    tif: 'image/tiff',
+    tiff: 'image/tiff',
+    // 동영상
+    mp4: 'video/mp4',
+    m4v: 'video/mp4',
+    mov: 'video/quicktime',
+    webm: 'video/webm',
+    ogv: 'video/ogg',
+    mkv: 'video/x-matroska',
+    avi: 'video/x-msvideo',
+    // 소리
+    mp3: 'audio/mpeg',
+    m4a: 'audio/mp4',
+    aac: 'audio/aac',
+    wav: 'audio/wav',
+    ogg: 'audio/ogg',
+    oga: 'audio/ogg',
+    opus: 'audio/ogg',
+    flac: 'audio/flac',
+    // 문서 — 폰 브라우저가 그대로 띄워준다
+    pdf: 'application/pdf',
+};
+export function mediaMime(name) {
+    const ext = path.extname(name).slice(1).toLowerCase();
+    return MIME_BY_EXT[ext] ?? null;
+}
+export function mediaKind(name) {
+    const mime = mediaMime(name);
+    if (!mime)
+        return null;
+    if (mime.startsWith('image/'))
+        return 'image';
+    if (mime.startsWith('video/'))
+        return 'video';
+    if (mime.startsWith('audio/'))
+        return 'audio';
+    return 'pdf';
+}
+function expand(target) {
+    if (target.startsWith('~'))
+        return path.join(os.homedir(), target.slice(1));
+    return path.resolve(target);
+}
+// 보내기 전에 "이 파일이 뭔지, 몇 조각인지" 만 먼저 알아본다.
+// 폰은 이 답을 보고 큰 파일이면 "받을까요?" 를 한 번 물어본 뒤에야 받기를 시작한다.
+export function statMedia(target) {
+    const full = expand(target);
+    let stat;
+    try {
+        stat = fs.statSync(full);
+    }
+    catch {
+        return { ok: false, reason: `파일을 찾을 수 없어요: ${full}` };
+    }
+    if (stat.isDirectory())
+        return { ok: false, reason: '폴더는 열 수 없어요.' };
+    const mime = mediaMime(full);
+    const kind = mediaKind(full);
+    if (!mime || !kind)
+        return { ok: false, reason: '폰에서 보여줄 수 있는 형식이 아니에요.' };
+    if (stat.size === 0)
+        return { ok: false, reason: '파일이 비어 있어요.' };
+    if (stat.size > MAX_MEDIA_SIZE) {
+        return {
+            ok: false,
+            reason: `파일이 너무 커요 (${Math.round(stat.size / 1024 / 1024)}MB) — ` +
+                `${MAX_MEDIA_SIZE / 1024 / 1024}MB 까지만 보낼 수 있어요.`,
+        };
+    }
+    return {
+        ok: true,
+        full,
+        mime,
+        kind,
+        size: stat.size,
+        total: Math.ceil(stat.size / MEDIA_CHUNK_BYTES),
+    };
+}
+// 파일을 열어두고 조각을 하나씩 꺼내 쓰는 손잡이. 통째로 메모리에 올리지 않는 이유는,
+// 64MB 짜리를 여러 세션에서 동시에 열면 에이전트가 그만큼을 계속 들고 있게 되기 때문이다.
+export class MediaReader {
+    info;
+    fd;
+    constructor(info, fd) {
+        this.info = info;
+        this.fd = fd ?? fs.openSync(info.full, 'r');
+    }
+    chunk(index) {
+        const offset = index * MEDIA_CHUNK_BYTES;
+        const length = Math.min(MEDIA_CHUNK_BYTES, this.info.size - offset);
+        const buffer = Buffer.allocUnsafe(length);
+        let read = 0;
+        // 한 번에 다 안 읽히는 경우가 있어서(네트워크 드라이브 등) 다 찰 때까지 이어 읽는다
+        while (read < length) {
+            const got = fs.readSync(this.fd, buffer, read, length - read, offset + read);
+            if (got <= 0)
+                break;
+            read += got;
+        }
+        return read === length ? buffer : buffer.subarray(0, read);
+    }
+    close() {
+        try {
+            fs.closeSync(this.fd);
+        }
+        catch {
+            // 이미 닫혔으면 그만
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shellbase",
-  "version": "0.13.6",
+  "version": "0.14.0",
   "description": "내 컴퓨터 터미널(특히 Claude Code 세션)을 폰 브라우저로 실시간 접속하게 해주는 데스크톱 에이전트",
   "type": "module",
   "bin": {