@online5880/opensession 0.1.3 → 0.1.5

package/HANDOVER.md

@@ -0,0 +1,78 @@
+# OpenSession Project Handover & Progress Report
+
+> **작성일**: 2026년 3월 15일
+> **목적**: 현재까지 진행된 개발 내역을 정리하고, 향후 작업을 매끄럽게 이어가기 위한 인수인계 문서입니다.
+
+---
+
+## 🚀 1. 현재까지 진행된 핵심 작업 (Completed)
+
+### (1) OpenSession CLI 고도화 (v0.1.3)
+- **TUI 대시보드 추가 (`opss tui`)**: `blessed` 라이브러리를 활용하여 터미널 내에서 세션 목록과 실시간 이벤트를 모니터링할 수 있는 대화형 인터페이스를 구축했습니다.
+- **TUI 실시간 자동 갱신(Auto-refresh)**: 선택한 세션의 이벤트를 5초 간격으로 자동 폴링(Polling)하여 화면 새로고침 없이 최신 상태를 보여줍니다.
+- **글로벌화 (영문화)**: CLI의 모든 프롬프트(`init`, 에러 메시지, 결과 출력 등)를 영어로 번역하여 글로벌 사용자 접근성을 높였습니다.
+- **용어 전문화**: Supabase의 내부 용어인 `ANON KEY` 대신 사용자 친화적인 **`Public API Key`**로 용어를 일괄 변경했습니다.
+- **Product-grade README**: 영문/국문(`README.md`, `README.ko.md`) 버전을 분리하여 작성하고, 아키텍처 다이어그램 및 배지(Badges)를 추가하여 제품의 신뢰도를 높였습니다.
+
+### (2) 랜딩 페이지 (`opensession-site`) 고도화
+- **다중 언어 (i18n)**: 한국어/영어 스위처를 우측 상단에 구현했습니다.
+- **다크/라이트 모드 (Theme)**: 달/해 아이콘을 통해 테마를 전환할 수 있으며, 최신 웹 트렌드에 맞춘 Vibe 디자인을 적용했습니다.
+- **사용자 경험(UX) 개선**:
+  - `npm install` 명령어를 원클릭으로 복사할 수 있는 버튼 추가.
+  - Windows 사용자를 위한 **PowerShell 설정 함수** 가이드 추가.
+  - `Bash/Zsh` 와 `PowerShell` 코드를 시각적으로 전환할 수 있는 버튼 탭 구현.
+- **Git 연동 및 배포**: `opensession.pages.dev` 도메인에 연결할 수 있도록 Cloudflare Pages 구조를 세팅하고 GitHub 원격 저장소 푸시를 완료했습니다.
+
+---
+
+## 🏗️ 2. 현재 시스템 아키텍처 요약
+
+- **Backend**: Supabase (PostgreSQL) - 세션 메타데이터(`projects`, `sessions`)와 실시간 로그(`session_events`)를 영속적으로 저장합니다.
+- **Continuity Engine**: `opensession` CLI 패키지 (`cli.js`, `supabase.js`, `idempotency.js`).
+- **3-Layer Interface**:
+  1. **CLI**: 가장 빠르고 가벼운 명령어 흐름 제어.
+  2. **Web Viewer (`opss viewer`)**: 브라우저 기반의 JSON 페이로드 분석 및 28일 KPI 통계.
+  3. **TUI (`opss tui`)**: 실시간 터미널 대시보드.
+
+---
+
+## 🔮 3. 향후 개발 로드맵 (Next Steps)
+
+나중에 작업을 이어가실 때 아래 항목들을 우선적으로 고려하시면 좋습니다.
+
+### [Phase 4] 실시간 웹소켓 스트리밍
+- 현재 TUI는 5초마다 REST API를 폴링(Polling)하여 이벤트를 가져옵니다. 이를 **Supabase Realtime (WebSocket)** 구독 방식으로 변경하면 서버 부하를 줄이고 훨씬 더 즉각적인 반응(Real-time)을 얻을 수 있습니다.
+
+### [Phase 5] SDK 및 언어 생태계 확장
+- 현재는 Node.js 기반 CLI 중심이지만, Python 생태계(LangChain, CrewAI 등)나 Go 언어에서 OpenSession 백엔드와 직접 통신할 수 있는 **경량 SDK**를 제공하면 파급력이 커집니다.
+
+### [Phase 6] 엔터프라이즈 SaaS화 (상품화 단계)
+- 본 저장소의 핵심 코드는 오픈소스로 유지(Open Core 전략)하되, 여러 명의 에이전트와 사람 팀원이 협업할 수 있는 **역할 기반(RBAC) 멀티 테넌트 대시보드**를 비공개 저장소에서 개발하여 유료 서비스(SaaS)로 전환할 수 있습니다.
+- Slack / Discord 실시간 알림 웹훅(Webhook) 기능 강화.
+
+---
+
+## 📋 4. 작업 재개 가이드
+
+다음번 세션 시작 시, 이 문서를 참고하여 현재 위치를 파악하세요.
+
+1. **로컬 테스트 환경 구동**:
+   ```powershell
+   cd E:\019_gemini\opensession
+   node src/cli.js tui
+   ```
+2. **랜딩 페이지 수정 시**:
+   ```powershell
+   cd E:\019_gemini\opensession-site
+   python -m http.server 8080
+   # 접속: http://localhost:8080
+   ```
+3. **NPM 패키지 배포 (새 기능 추가 시)**:
+   ```powershell
+   # 1. package.json 버전 올리기
+   # 2. 터미널에서 로그인 및 배포
+   npm login
+   npm publish --access public
+   ```
+
+*본 문서는 프로젝트의 지속성을 위해 작성되었습니다. 화이팅입니다!* 🚀

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@online5880/opensession",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Session continuity bridge CLI with Supabase backend",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -93,7 +93,7 @@ async function readInitWizardInputs(current, options) {
     const existingActor = typeof current?.actor === 'string' ? current.actor.trim() : '';
 
     const url = (await rl.question('Enter Supabase URL: ')).trim();
-    const anonKey = (await rl.question('Enter Supabase ANON KEY: ')).trim();
+    const anonKey = (await rl.question('Enter Supabase Public API Key: ')).trim();
 
     let projectKey = typeof options.projectKey === 'string' ? options.projectKey.trim() : '';
     if (!projectKey) {
@@ -677,21 +677,28 @@ program
   .command('start')
   .alias('st')
   .description('Start a new session and emit a start event')
-  .requiredOption('--project-key <projectKey>', 'Project key')
+  .option('--project-key <projectKey>', 'Project key (defaults to configured project key)')
+  .option('--project <projectKey>', 'Alias of --project-key')
   .option('--project-name <projectName>', 'Project display name')
   .option('--actor <actor>', 'Actor override')
   .action(async (options) => {
     const config = await readConfig();
     const client = getClient(config);
+    const projectKey = options.project ?? options.projectKey ?? config.defaultProjectKey ?? config.syncStatus?.project;
+    
+    if (!projectKey) {
+      throw new Error("Missing project key. Pass --project-key or set a default via 'opss init'.");
+    }
+    
     const actor = options.actor ?? config.actor ?? 'anonymous';
     const operationId = randomUUID();
 
-    const project = await ensureProject(client, options.projectKey, options.projectName);
+    const project = await ensureProject(client, projectKey, options.projectName);
     const session = await startSession(client, project.id, actor, { operationId });
 
     await writeConfig(
       mergeConfig(config, {
-        defaultProjectKey: options.projectKey,
+        defaultProjectKey: projectKey,
         lastSessionId: session.id
       })
     );