shellbase 0.5.0 → 0.7.0

package/README.md

@@ -87,6 +87,8 @@ shellbase start --no-restore     # 복구하지 않고 이 폴더 세션 하나
 | 세션 갈아타기 | 터미널 화면 위쪽의 **기기 이름(▾)** 탭 → 원하는 세션 선택 |
 | 세션 끄기 | 목록의 **전원 아이콘**, 또는 터미널 화면의 기기 이름(▾) → **이 세션 끄기** |
 | 화면만 닫기 | `← 목록` 으로 나가기 — 컴퓨터의 세션은 계속 살아있어요 |
+| 파일 열어보기·고치기 | **`📁 폴더 찾기`** → 목록에서 **파일**을 탭하면 에디터가 열려요 (수정 후 `저장`) |
+| 세션 이름 바꾸기 | 기기 이름(▾) → 세션 옆 연필 버튼 |
 
 - **끄기는 진짜로 꺼요.** 컴퓨터에서 돌아가던 그 터미널이 종료되고 목록에서도 자동으로 사라져요
   (`Ctrl+C` 를 누른 것과 같아요). 프로세스가 죽었는데 목록에만 남아있는 항목은 휴지통 아이콘으로
@@ -97,6 +99,50 @@ shellbase start --no-restore     # 복구하지 않고 이 폴더 세션 하나
   종료돼요(그 대신 다음 실행 때 자동 복구됩니다). 세션을 하나만 끄고 싶으면 폰에서 그 세션의 `✕` 를
   쓰세요 — 나머지 세션은 그대로 유지돼요.
 
+### 파일 보기·편집
+
+`📁 폴더 찾기` 목록에는 폴더와 함께 **파일**도 나와요. 파일을 탭하면 편집기가 열리고, 고친 뒤 `저장` 을
+누르면 그 컴퓨터의 파일이 실제로 바뀝니다. **기기에 따라 편집기가 다르게 열려요:**
+
+- **노트북·데스크톱(넓은 화면 + 마우스)**: VS Code 와 같은 **모나코** — 찾기·바꾸기(Ctrl+F), 커서 여러 개,
+  줄 접기, 미니맵, `Ctrl+S` 저장이 그대로 동작해요. 파일을 처음 열 때만 내려받습니다.
+- **폰**: 가벼운 편집기(CodeMirror) — 터치 우선이라 좁은 화면에서 편하고, `Tab` 들여쓰기와 `Ctrl+S` 저장도 됩니다.
+- 모나코에서 **JS/TS 타입 기반 자동완성은 빠져 있어요** (그 기능 파일 하나가 6.6MB 라 웹 스토리지 한도를
+  넘습니다). 색칠·단축키·검색은 모두 정상이에요.
+
+- 512KB 까지, **글자 파일만** 열려요 (사진·실행파일 같은 이진 파일은 자동으로 걸러집니다)
+- 저장은 같은 폴더의 임시 파일에 먼저 쓴 뒤 교체해서, 저장 도중 끊겨도 원본이 깨지지 않아요
+- 파일 내용은 터미널 화면과 똑같이 세션 키로 암호화해서 주고받아요
+- 에디터는 **파일을 처음 열 때만 따로 내려받아요** — 터미널만 쓰면 그만큼 안 받습니다
+
+### 폰에서 사진·스크린샷 첨부 (0.7.0+)
+
+폰 화면의 **클립(📎) 버튼**(PC 는 상단 바)으로 사진을 고르면, 사진이 **이 컴퓨터의
+`~/.shellbase/images/`** 에 파일로 저장되고 그 **파일 경로가 터미널에 자동으로 입력**됩니다.
+이어서 "이 화면 좀 봐줘" 처럼 쓰고 엔터를 누르면 Claude Code 가 그 사진을 읽어요.
+
+- 폰에서는 「사진 찍기 / 사진 보관함」이 함께 떠요 — 방금 찍은 **스크린샷은 보관함**에 있습니다
+- 스크린샷을 **복사해서 붙여넣기**(Ctrl+V) 해도 첨부돼요
+- 사진은 보내기 전에 폰에서 **긴 변 1568px 로 줄여서** 올라가요(전송이 빠르고 인식 정확도는 그대로)
+- 저장된 사진은 **7일이 지나면 자동으로 지워져요**, 파일 권한은 본인만 읽기(600)
+- 사진도 터미널 화면과 똑같이 **세션 키로 암호화**해서 전송돼요
+
+### 폰에서 마이크로 말하기 (음성 → 글자)
+
+폰 화면 오른쪽 아래 **마이크 버튼**을 누르고 말하면, 녹음이 **이 컴퓨터로** 전송돼서 컴퓨터에 떠 있는
+음성인식 서버가 글자로 바꿔줍니다. 기본값은 **말한 뒤 바로 보내기(엔터까지 자동)** 라서, 「완료」만
+누르면 그대로 실행돼요 (Claude Code 에게 말로 시킬 때 편합니다). 확인하고 보내고 싶으면 명령창의
+`말한 뒤 바로 보내기 끄기` 로 예전 방식(받아쓴 글자를 보여주고 `보내기 ↵` 를 누르는 방식)으로 바꿀 수 있어요.
+
+- **녹음은 다른 회사 서버로 나가지 않아요** — 폰 → (암호화된 실시간 채널) → 내 컴퓨터 → 내 음성인식 서버
+- 음성인식 서버는 시작할 때 자동으로 찾아요: `SHELLBASE_STT_URL` → `http://127.0.0.1:5005`
+  → `http://172.17.0.1:5005`(도커 안에서 본 호스트) 순서
+- 주소가 다르면 `SHELLBASE_STT_URL=http://127.0.0.1:9000` 처럼 지정하고 다시 시작하세요.
+  인식 언어는 `SHELLBASE_STT_LANGS=ko,en` 으로 바꿀 수 있어요 (기본 `ko`)
+- 서버가 없으면 마이크 기능만 꺼지고 나머지는 그대로 동작해요 (시작할 때 로그로 알려줍니다)
+- 필요한 서버 형식: `GET /health` 와 `POST /transcribe_json` (`{audio_base64, languages}` → `{ok, text}`) —
+  whisper 계열 서버면 대개 이 형태입니다
+
 > ⚠️ **도커로 돌릴 때, 마지막 세션을 폰에서 끄면 도커가 다시 띄워요.** 세션이 0개가 되면 프로세스가
 > 종료되는데, `--restart unless-stopped` 는 정상 종료(exit 0)에도 컨테이너를 자동 재시작하기 때문이에요
 > (실제로 확인한 동작). 즉 마지막 세션 끄기는 **사실상 재시작**이 됩니다. 세션이 여러 개일 때 하나만

package/dist/agent.js

@@ -12,7 +12,9 @@ import { promptApproval } from './prompt.js';
 import { touchRecentDir } from './recent-dirs.js';
 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';
 const HEARTBEAT_MS = 20_000;
 const APPROVAL_TIMEOUT_MS = 30_000;
 const SCROLLBACK_MAX = 16_000;
@@ -77,6 +79,12 @@ export async function runAgent(options) {
     const sessions = new Map();
     // 폰에서 저장 중인 파일 조각 모음 (경로별)
     const writeBuffers = new Map();
+    // 폰에서 온 녹음 조각 모음 (파일 저장과 같은 방식)
+    const audioBuffers = new Map();
+    // 폰에서 온 사진 조각 모음 (녹음과 같은 방식)
+    const imageBuffers = new Map();
+    // 이 컴퓨터에서 찾은 음성인식 서버 주소 — 시작할 때 한 번 찾고, 없으면 요청이 올 때 다시 찾는다
+    let sttUrl = null;
     function defaultName(cwd) {
         return cwd === os.homedir() ? hostLabel : `${hostLabel} · ${path.basename(cwd)}`;
     }
@@ -409,6 +417,112 @@ export async function runAgent(options) {
                 console.log(`📱 폰에서 파일을 저장했어요: ${filePath}`);
             return;
         }
+        // 폰에서 마이크로 말한 녹음 — 조각이 다 모이면 이 컴퓨터의 음성인식 서버로 넘겨 글자로 돌려준다.
+        // 녹음은 인터넷의 다른 음성인식 서비스로 나가지 않고 이 컴퓨터 안에서만 처리된다.
+        if (frame.kind === 'stt_audio') {
+            const control = readControl(frame.data, session.frameKey);
+            if (!control ||
+                typeof control.id !== 'string' ||
+                typeof control.chunk !== 'string' ||
+                typeof control.index !== 'number' ||
+                typeof control.total !== 'number') {
+                return;
+            }
+            const recordId = control.id;
+            const key = `${session.deviceId}:${recordId}`;
+            const now = Date.now();
+            for (const [bufferKey, buffer] of audioBuffers) {
+                if (now - buffer.at > AUDIO_CHUNK_TTL_MS)
+                    audioBuffers.delete(bufferKey);
+            }
+            const buffer = control.index === 0
+                ? { parts: [], total: control.total, at: now }
+                : (audioBuffers.get(key) ?? { parts: [], total: control.total, at: now });
+            buffer.parts[control.index] = control.chunk;
+            buffer.at = now;
+            audioBuffers.set(key, buffer);
+            if (buffer.parts.filter((part) => typeof part === 'string').length < buffer.total)
+                return;
+            audioBuffers.delete(key);
+            const audioBase64 = buffer.parts.join('');
+            const fail = (reason) => send({
+                kind: 'stt_error',
+                to: session.deviceId,
+                data: encryptFrame(JSON.stringify({ id: recordId, reason }), session.frameKey),
+            });
+            if (audioBase64.length > MAX_AUDIO_BASE64) {
+                void fail('녹음이 너무 길어요. 조금 짧게 나눠서 말해주세요.');
+                return;
+            }
+            void (async () => {
+                if (!sttUrl)
+                    sttUrl = await findSttServer();
+                if (!sttUrl) {
+                    await fail(STT_SETUP_HINT);
+                    return;
+                }
+                const result = await transcribe(sttUrl, audioBase64);
+                if (!result.ok) {
+                    // 서버가 꺼졌을 수도 있으니 다음 요청 때 다시 찾도록 주소를 비운다
+                    sttUrl = null;
+                    await fail(result.reason);
+                    return;
+                }
+                console.log(`📱 폰에서 말한 내용을 받아썼어요: "${result.text}"`);
+                await send({
+                    kind: 'stt_text',
+                    to: session.deviceId,
+                    data: encryptFrame(JSON.stringify({ id: recordId, text: result.text }), session.frameKey),
+                });
+            })();
+            return;
+        }
+        // 폰에서 올린 사진 — 조각이 다 모이면 ~/.shellbase/images 에 파일로 저장하고 경로를 돌려준다.
+        // 폰은 그 경로를 터미널에 넣어서 Claude Code 가 그림을 읽게 한다.
+        if (frame.kind === 'image_upload') {
+            const control = readControl(frame.data, session.frameKey);
+            if (!control ||
+                typeof control.id !== 'string' ||
+                typeof control.mime !== 'string' ||
+                typeof control.chunk !== 'string' ||
+                typeof control.index !== 'number' ||
+                typeof control.total !== 'number') {
+                return;
+            }
+            const uploadId = control.id;
+            const mime = control.mime;
+            const key = `${session.deviceId}:${uploadId}`;
+            const now = Date.now();
+            for (const [bufferKey, buffer] of imageBuffers) {
+                if (now - buffer.at > IMAGE_CHUNK_TTL_MS)
+                    imageBuffers.delete(bufferKey);
+            }
+            const buffer = control.index === 0
+                ? { parts: [], total: control.total, at: now }
+                : (imageBuffers.get(key) ?? { parts: [], total: control.total, at: now });
+            buffer.parts[control.index] = control.chunk;
+            buffer.at = now;
+            imageBuffers.set(key, buffer);
+            if (buffer.parts.filter((part) => typeof part === 'string').length < buffer.total)
+                return;
+            imageBuffers.delete(key);
+            const result = saveImage(buffer.parts.join(''), mime);
+            if (!result.ok) {
+                void send({
+                    kind: 'image_error',
+                    to: session.deviceId,
+                    data: encryptFrame(JSON.stringify({ id: uploadId, reason: result.reason }), session.frameKey),
+                });
+                return;
+            }
+            console.log(`📱 폰에서 사진을 받았어요: ${result.path}`);
+            void send({
+                kind: 'image_saved',
+                to: session.deviceId,
+                data: encryptFrame(JSON.stringify({ id: uploadId, path: result.path }), session.frameKey),
+            });
+            return;
+        }
         if (frame.kind === 'list_dirs') {
             const control = readControl(frame.data, session.frameKey);
             if (!control)
@@ -465,6 +579,13 @@ export async function runAgent(options) {
             heartbeatDevice(cb, session.rowId).catch((err) => console.error(`하트비트 실패(${session.name}):`, err.message));
         }
     }, HEARTBEAT_MS);
+    // 음성인식 서버가 이 컴퓨터에 떠 있으면 폰에서 마이크 버튼을 쓸 수 있다 (없어도 나머지 기능은 그대로)
+    void findSttServer().then((url) => {
+        sttUrl = url;
+        console.log(url
+            ? `🎤 음성인식 서버를 찾았어요: ${url} — 폰에서 마이크로 말할 수 있어요.`
+            : '🎤 음성인식 서버가 없어요 — 폰 마이크 기능은 꺼진 상태예요 (SHELLBASE_STT_URL 로 주소를 지정할 수 있어요).');
+    });
     startSleepGuard();
     process.on('SIGINT', () => void shutdownProcess());
     process.on('SIGTERM', () => void shutdownProcess());

package/dist/images.js

@@ -0,0 +1,76 @@
+// 폰에서 찍거나 고른 사진을 이 컴퓨터에 파일로 내려놓는 부분.
+// Claude Code 는 "파일 경로"만 프롬프트에 있으면 그림을 직접 읽을 수 있어서,
+// 여기 저장한 뒤 경로를 폰으로 돌려주면 폰에서 그 경로를 터미널에 넣어 쓰게 된다.
+import { mkdirSync, readdirSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+export const IMAGE_DIR = join(homedir(), '.shellbase', 'images');
+// 조각(chunk)이 다 모이기를 기다리는 시간 — 사진은 녹음보다 조각이 많아서 넉넉하게
+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;
+const EXT_BY_TYPE = {
+    'image/png': 'png',
+    'image/jpeg': 'jpg',
+    'image/jpg': 'jpg',
+    'image/webp': 'webp',
+    'image/gif': 'gif',
+};
+function pruneOld() {
+    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)
+                    unlinkSync(full);
+            }
+            catch {
+                // 지우다 실패해도 사진 저장 자체를 막지는 않는다
+            }
+        }
+    }
+    catch {
+        // 폴더가 아직 없으면 지울 것도 없다
+    }
+}
+// 두 자리로 맞춘 시간 문자열 (파일 이름이 시간순으로 정렬되게)
+function stamp(date) {
+    const pad = (value) => String(value).padStart(2, '0');
+    return (`${date.getFullYear()}${pad(date.getMonth() + 1)}${pad(date.getDate())}` +
+        `-${pad(date.getHours())}${pad(date.getMinutes())}${pad(date.getSeconds())}`);
+}
+export function saveImage(base64, mime) {
+    if (base64.length > MAX_IMAGE_BASE64) {
+        return { ok: false, reason: '사진이 너무 커요. 조금 작은 사진으로 다시 올려주세요.' };
+    }
+    const ext = EXT_BY_TYPE[mime.toLowerCase()];
+    if (!ext)
+        return { ok: false, reason: '이 형식의 사진은 아직 못 받아요 (png·jpg·webp·gif 만).' };
+    let bytes;
+    try {
+        bytes = Buffer.from(base64, 'base64');
+    }
+    catch {
+        return { ok: false, reason: '사진이 오는 도중에 깨졌어요. 다시 시도해주세요.' };
+    }
+    if (bytes.length === 0)
+        return { ok: false, reason: '사진이 비어 있어요. 다시 골라주세요.' };
+    try {
+        mkdirSync(IMAGE_DIR, { recursive: true });
+        pruneOld();
+        // 같은 초에 여러 장을 올려도 안 겹치도록 뒤에 짧은 임의 글자를 붙인다
+        const suffix = Math.random().toString(36).slice(2, 6);
+        const path = join(IMAGE_DIR, `${stamp(new Date())}-${suffix}.${ext}`);
+        writeFileSync(path, bytes, { mode: 0o600 });
+        return { ok: true, path };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            reason: `사진을 저장하지 못했어요: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+}

package/dist/stt.js

@@ -0,0 +1,65 @@
+// 폰에서 보낸 녹음을 "이 컴퓨터에 떠 있는 음성인식 서버"로 넘겨 글자로 바꾼다.
+// 녹음이 컴퓨터 밖으로 나가지 않는 게 핵심 — 폰 → (암호화된 실시간 채널) → 이 컴퓨터 → 로컬 whisper.
+// 실시간 프레임은 한 번에 20KB 남짓만 보낼 수 있어서 녹음도 파일과 같은 방식으로 조각내 받는다
+export const AUDIO_CHUNK_TTL_MS = 60_000;
+// 대략 1~2분 분량 (base64 로 부풀린 크기 기준)
+export const MAX_AUDIO_BASE64 = 2 * 1024 * 1024;
+// 서버를 찾는 순서: 직접 지정한 주소 → 이 컴퓨터 → 도커 안에서 본 호스트
+function candidates() {
+    const list = [];
+    const configured = process.env.SHELLBASE_STT_URL?.trim();
+    if (configured)
+        list.push(configured.replace(/\/$/, ''));
+    list.push('http://127.0.0.1:5005', 'http://172.17.0.1:5005', 'http://host.docker.internal:5005');
+    return list;
+}
+async function isAlive(baseUrl) {
+    try {
+        const res = await fetch(`${baseUrl}/health`, { signal: AbortSignal.timeout(1500) });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}
+// 시작할 때 한 번 찾아두고, 못 찾으면 요청이 올 때 다시 한 번 찾아본다(그 사이에 켰을 수도 있으니)
+export async function findSttServer() {
+    for (const url of candidates()) {
+        if (await isAlive(url))
+            return url;
+    }
+    return null;
+}
+export async function transcribe(baseUrl, audioBase64) {
+    const languages = (process.env.SHELLBASE_STT_LANGS ?? 'ko')
+        .split(',')
+        .map((lang) => lang.trim())
+        .filter(Boolean);
+    try {
+        const res = await fetch(`${baseUrl}/transcribe_json`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ audio_base64: audioBase64, languages }),
+            signal: AbortSignal.timeout(60_000),
+        });
+        if (!res.ok) {
+            return { ok: false, reason: `음성인식 서버가 오류를 돌려줬어요 (HTTP ${res.status}).` };
+        }
+        const body = (await res.json());
+        if (body.ok === false) {
+            return { ok: false, reason: body.error ?? '음성을 알아듣지 못했어요.' };
+        }
+        const text = (body.text ?? '').trim();
+        if (!text)
+            return { ok: false, reason: '말소리가 들리지 않았어요. 다시 한 번 말해주세요.' };
+        return { ok: true, text };
+    }
+    catch (err) {
+        const reason = err.name === 'TimeoutError'
+            ? '음성인식이 너무 오래 걸려서 멈췄어요.'
+            : `음성인식 서버에 연결하지 못했어요: ${err.message}`;
+        return { ok: false, reason };
+    }
+}
+export const STT_SETUP_HINT = '이 컴퓨터에서 음성인식 서버를 찾지 못했어요. whisper 같은 음성인식 서버를 켜고, 주소가 다르면 ' +
+    'SHELLBASE_STT_URL=http://127.0.0.1:5005 처럼 지정한 뒤 에이전트를 다시 시작해주세요.';

package/package.json

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