shellbase 0.4.0 → 0.6.0

package/README.md

@@ -87,6 +87,8 @@ shellbase start --no-restore     # 복구하지 않고 이 폴더 세션 하나
 | 세션 갈아타기 | 터미널 화면 위쪽의 **기기 이름(▾)** 탭 → 원하는 세션 선택 |
 | 세션 끄기 | 목록의 **전원 아이콘**, 또는 터미널 화면의 기기 이름(▾) → **이 세션 끄기** |
 | 화면만 닫기 | `← 목록` 으로 나가기 — 컴퓨터의 세션은 계속 살아있어요 |
+| 파일 열어보기·고치기 | **`📁 폴더 찾기`** → 목록에서 **파일**을 탭하면 에디터가 열려요 (수정 후 `저장`) |
+| 세션 이름 바꾸기 | 기기 이름(▾) → 세션 옆 연필 버튼 |
 
 - **끄기는 진짜로 꺼요.** 컴퓨터에서 돌아가던 그 터미널이 종료되고 목록에서도 자동으로 사라져요
   (`Ctrl+C` 를 누른 것과 같아요). 프로세스가 죽었는데 목록에만 남아있는 항목은 휴지통 아이콘으로
@@ -97,6 +99,16 @@ shellbase start --no-restore     # 복구하지 않고 이 폴더 세션 하나
   종료돼요(그 대신 다음 실행 때 자동 복구됩니다). 세션을 하나만 끄고 싶으면 폰에서 그 세션의 `✕` 를
   쓰세요 — 나머지 세션은 그대로 유지돼요.
 
+### 파일 보기·편집
+
+`📁 폴더 찾기` 목록에는 폴더와 함께 **파일**도 나와요. 파일을 탭하면 문법 강조가 되는 에디터가 열리고,
+고친 뒤 `저장` 을 누르면 그 컴퓨터의 파일이 실제로 바뀝니다.
+
+- 512KB 까지, **글자 파일만** 열려요 (사진·실행파일 같은 이진 파일은 자동으로 걸러집니다)
+- 저장은 같은 폴더의 임시 파일에 먼저 쓴 뒤 교체해서, 저장 도중 끊겨도 원본이 깨지지 않아요
+- 파일 내용은 터미널 화면과 똑같이 세션 키로 암호화해서 주고받아요
+- 에디터는 **파일을 처음 열 때만 따로 내려받아요** — 터미널만 쓰면 그만큼 안 받습니다
+
 > ⚠️ **도커로 돌릴 때, 마지막 세션을 폰에서 끄면 도커가 다시 띄워요.** 세션이 0개가 되면 프로세스가
 > 종료되는데, `--restart unless-stopped` 는 정상 종료(exit 0)에도 컨테이너를 자동 재시작하기 때문이에요
 > (실제로 확인한 동작). 즉 마지막 세션 끄기는 **사실상 재시작**이 됩니다. 세션이 여러 개일 때 하나만

package/dist/agent.js

@@ -11,6 +11,8 @@ import { registerDevice, heartbeatDevice, unregisterDevice, listOnlineDirs, rena
 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';
 const HEARTBEAT_MS = 20_000;
 const APPROVAL_TIMEOUT_MS = 30_000;
@@ -25,6 +27,8 @@ const SEND_PENALTY_MS = 500;
 const PENALTY_INTERVAL_MS = 250;
 // 실수나 버그로 세션이 무한정 늘어나는 것을 막는 상한 (한 컴퓨터에서 이 이상 필요한 경우는 사실상 없음)
 const MAX_SESSIONS = 20;
+// 저장 중인 파일 조각을 모아두는 시간 — 중간에 폰이 끊기면 조용히 버린다
+const WRITE_BUFFER_TTL_MS = 60_000;
 // 폰의 폴더 탐색기를 열 때 "지금 셸이 있는 폴더"에서 시작하려면, 세션을 시작한 폴더가 아니라
 // 셸 프로세스의 실제 작업 폴더를 봐야 한다(사용자가 cd 로 옮겨 다니므로). 리눅스는 /proc 로 바로 알 수 있고,
 // 없는 OS(맥·윈도)에서는 세션 시작 폴더로 되돌아간다.
@@ -41,9 +45,6 @@ function resolveShell() {
         return process.env.COMSPEC ?? 'powershell.exe';
     return process.env.SHELL ?? '/bin/bash';
 }
-// 폰이 보내는 제어 프레임(끄기 / 새 세션 / 폴더 목록)은 그 세션의 키로 풀려야만 받아들인다.
-// 키는 devices 테이블의 내 row 에만 있고 RLS 로 주인만 읽을 수 있으니, 복호화에 성공했다는 것 자체가
-// "주인이 보낸 요청"이라는 증거가 된다 (입력 승인과는 별개 — 승인은 타이핑 권한용).
 function readControl(data, key) {
     if (typeof data !== 'string')
         return null;
@@ -75,6 +76,12 @@ export async function runAgent(options) {
     const hostLabel = options.name ?? os.hostname();
     const shell = resolveShell();
     const sessions = new Map();
+    // 폰에서 저장 중인 파일 조각 모음 (경로별)
+    const writeBuffers = new Map();
+    // 폰에서 온 녹음 조각 모음 (파일 저장과 같은 방식)
+    const audioBuffers = new Map();
+    // 이 컴퓨터에서 찾은 음성인식 서버 주소 — 시작할 때 한 번 찾고, 없으면 요청이 올 때 다시 찾는다
+    let sttUrl = null;
     function defaultName(cwd) {
         return cwd === os.homedir() ? hostLabel : `${hostLabel} · ${path.basename(cwd)}`;
     }
@@ -338,6 +345,135 @@ export async function runAgent(options) {
             });
             return;
         }
+        // 폰에서 파일 열기 — 실시간 프레임 크기 제한(20KB 남짓) 때문에 조각으로 나눠 보낸다
+        if (frame.kind === 'read_file') {
+            const control = readControl(frame.data, session.frameKey);
+            if (!control || typeof control.path !== 'string')
+                return;
+            const filePath = control.path;
+            const result = readTextFile(filePath);
+            if (!result.ok) {
+                void send({
+                    kind: 'file_error',
+                    to: session.deviceId,
+                    data: encryptFrame(JSON.stringify({ path: filePath, reason: result.reason }), session.frameKey),
+                });
+                return;
+            }
+            const chunks = chunkContent(result.content);
+            void (async () => {
+                for (let index = 0; index < chunks.length; index++) {
+                    await send({
+                        kind: 'file_chunk',
+                        to: session.deviceId,
+                        data: encryptFrame(JSON.stringify({ path: filePath, index, total: chunks.length, chunk: chunks[index] }), session.frameKey),
+                    });
+                }
+            })();
+            return;
+        }
+        // 폰에서 파일 저장 — 조각이 다 모이면 임시 파일에 쓴 뒤 교체한다 (files.ts)
+        if (frame.kind === 'write_file') {
+            const control = readControl(frame.data, session.frameKey);
+            if (!control ||
+                typeof control.path !== 'string' ||
+                typeof control.chunk !== 'string' ||
+                typeof control.index !== 'number' ||
+                typeof control.total !== 'number') {
+                return;
+            }
+            const key = `${session.deviceId}:${control.path}`;
+            const now = Date.now();
+            for (const [bufferKey, buffer] of writeBuffers) {
+                if (now - buffer.at > WRITE_BUFFER_TTL_MS)
+                    writeBuffers.delete(bufferKey);
+            }
+            const buffer = control.index === 0
+                ? { parts: [], total: control.total, at: now }
+                : (writeBuffers.get(key) ?? { parts: [], total: control.total, at: now });
+            buffer.parts[control.index] = control.chunk;
+            buffer.at = now;
+            writeBuffers.set(key, buffer);
+            if (buffer.parts.filter((part) => typeof part === 'string').length < buffer.total)
+                return;
+            writeBuffers.delete(key);
+            const filePath = control.path;
+            const result = writeTextFile(filePath, buffer.parts.join(''));
+            void send(result.ok
+                ? {
+                    kind: 'file_saved',
+                    to: session.deviceId,
+                    data: encryptFrame(JSON.stringify({ path: filePath }), session.frameKey),
+                }
+                : {
+                    kind: 'file_error',
+                    to: session.deviceId,
+                    data: encryptFrame(JSON.stringify({ path: filePath, reason: result.reason }), session.frameKey),
+                });
+            if (result.ok)
+                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;
+        }
         if (frame.kind === 'list_dirs') {
             const control = readControl(frame.data, session.frameKey);
             if (!control)
@@ -394,6 +530,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/browse.js

@@ -12,6 +12,7 @@ export function listDirs(dir) {
         parent: up === target ? null : up,
         home: os.homedir(),
         entries: [],
+        files: [],
     };
     let items;
     try {
@@ -40,9 +41,22 @@ export function listDirs(dir) {
     })
         .map((entry) => entry.name)
         .sort((a, b) => a.localeCompare(b));
+    // 파일은 이름과 크기만 — 열어볼 수 있는지 폰에서 미리 판단할 수 있게 한다
+    const files = items
+        .filter((entry) => !entry.name.startsWith('.') && entry.isFile())
+        .map((entry) => {
+        try {
+            return { name: entry.name, size: fs.statSync(path.join(target, entry.name)).size };
+        }
+        catch {
+            return { name: entry.name, size: 0 };
+        }
+    })
+        .sort((a, b) => a.name.localeCompare(b.name));
     return {
         ...base,
         entries: names.slice(0, MAX_ENTRIES),
-        truncated: names.length > MAX_ENTRIES,
+        files: files.slice(0, MAX_ENTRIES),
+        truncated: names.length > MAX_ENTRIES || files.length > MAX_ENTRIES,
     };
 }

package/dist/files.js

@@ -0,0 +1,69 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+// 폰에서 파일을 열어보고 고칠 수 있게 하는 읽기/쓰기. 실시간 프레임은 한 번에 20KB 남짓만 보낼 수 있어서
+// (실측: 16KB 성공 / 64KB 거부) 파일은 조각으로 나눠 주고받는다.
+export const CHUNK_SIZE = 12 * 1024;
+export const MAX_FILE_SIZE = 512 * 1024;
+function expand(target) {
+    if (target.startsWith('~'))
+        return path.join(os.homedir(), target.slice(1));
+    return path.resolve(target);
+}
+export function readTextFile(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: '폴더는 열 수 없어요.' };
+    if (stat.size > MAX_FILE_SIZE) {
+        return {
+            ok: false,
+            reason: `파일이 너무 커요 (${Math.round(stat.size / 1024)}KB) — ${MAX_FILE_SIZE / 1024}KB 까지만 열 수 있어요.`,
+        };
+    }
+    let buffer;
+    try {
+        buffer = fs.readFileSync(full);
+    }
+    catch (err) {
+        return { ok: false, reason: `파일을 읽지 못했어요: ${err.message}` };
+    }
+    // 사진·실행파일 같은 이진 파일은 에디터에서 의미가 없고 깨져 보이기만 하므로 미리 거른다
+    if (buffer.subarray(0, 8192).includes(0)) {
+        return { ok: false, reason: '글자 파일이 아니에요 (이진 파일은 열 수 없어요).' };
+    }
+    return { ok: true, content: buffer.toString('utf8'), size: stat.size };
+}
+export function writeTextFile(target, content) {
+    const full = expand(target);
+    try {
+        // 같은 폴더에 임시 파일로 먼저 쓰고 교체 — 저장 도중 끊겨도 원본이 깨지지 않는다
+        const tmp = path.join(path.dirname(full), `.${path.basename(full)}.shellbase-tmp`);
+        let mode;
+        try {
+            mode = fs.statSync(full).mode;
+        }
+        catch {
+            // 새 파일이면 기본 권한
+        }
+        fs.writeFileSync(tmp, content, mode === undefined ? undefined : { mode });
+        fs.renameSync(tmp, full);
+        return { ok: true };
+    }
+    catch (err) {
+        return { ok: false, reason: `저장하지 못했어요: ${err.message}` };
+    }
+}
+export function chunkContent(content) {
+    const chunks = [];
+    for (let i = 0; i < content.length; i += CHUNK_SIZE) {
+        chunks.push(content.slice(i, i + CHUNK_SIZE));
+    }
+    return chunks.length > 0 ? chunks : [''];
+}

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.4.0",
+  "version": "0.6.0",
   "description": "내 컴퓨터 터미널(특히 Claude Code 세션)을 폰 브라우저로 실시간 접속하게 해주는 데스크톱 에이전트",
   "type": "module",
   "bin": {