@online5880/opensession 0.1.8 → 0.1.9

package/README.ko.md

@@ -90,13 +90,25 @@ function opss { npx -y @online5880/opensession @args }
    opss log --limit 10
    ```
 
-4. **대시보드 실행**: 원하는 뷰어를 선택해 모니터링하세요.
-   ```bash
-   opss tui      # 터미널 대시보드 (추천)
-   opss viewer   # 웹 브라우저 뷰어
-   ```
-
----
+4. **대시보드 실행**: 원하는 뷰어를 선택해 모니터링하세요.
+    ```bash
+    opss tui      # 터미널 대시보드 (추천)
+    opss viewer   # 웹 브라우저 뷰어
+    ```
+
+## 🧪 테스트
+
+- 상세 가이드: [TESTING.md](TESTING.md) | [한국어 가이드](TESTING.ko.md)
+
+```bash
+npm test
+npm run e2e
+```
+
+- `npm test`: `test/*.test.js`에 있는 단위·호환성 테스트를 실행합니다.
+- `npm run e2e`: CLI 명령어 스모크 테스트와 viewer 시작/`/health` 검증 e2e 테스트를 실행합니다.
+
+---
 
 ## 📖 명령어 가이드
 

package/README.md

@@ -77,7 +77,7 @@ npm install -g @online5880/opensession
 
 ---
 
-## 🚀 1-Minute Quickstart
+## 🚀 1-Minute Quickstart
 
 1. **Initialize**: Set up your Supabase URL and API Key.
    ```bash
@@ -94,13 +94,25 @@ npm install -g @online5880/opensession
    opss log --limit 10
    ```
 
-4. **Launch Dashboard**: Choose your preferred view.
-   ```bash
-   opss tui      # Terminal dashboard (Recommended)
-   opss viewer   # Web browser viewer
-   ```
-
----
+4. **Launch Dashboard**: Choose your preferred view.
+   ```bash
+   opss tui      # Terminal dashboard (Recommended)
+   opss viewer   # Web browser viewer
+   ```
+
+## 🧪 Testing
+
+- Detailed guide: [TESTING.md](TESTING.md) | [한국어 가이드](TESTING.ko.md)
+
+```bash
+npm test
+npm run e2e
+```
+
+- `npm test`: Runs unit and compatibility tests under `test/*.test.js`.
+- `npm run e2e`: Runs end-to-end smoke tests for CLI commands and viewer startup/`/health`.
+
+---
 
 ## 📖 Command Reference
 ...

package/TESTING.ko.md

@@ -0,0 +1,58 @@
+# 테스트 가이드
+
+**[영어](TESTING.md) | [한국어](TESTING.ko.md)**
+
+## 1) 로컬 테스트 구성
+
+프로젝트 루트에서 다음 명령을 실행합니다:
+
+- `npm test` — 단위/호환성 테스트 실행 (`test/*.test.js`)
+- `npm run e2e` — E2E 스모크 테스트 실행 (`e2e/*.test.js`)
+- `npm run lint` — 런타임 JS 파일 구문 검사
+
+## 2) 실행 환경
+
+- Node.js 18 이상
+- 네트워크는 원칙적으로 필수가 아닙니다. 테스트는 외부 Supabase를 직접 호출하지 않습니다.
+- 외부 호출이 필요한 별도 스크립트를 직접 실행하지 않는 한 테스트는 임시 파일과 모킹(mock) 기반으로 동작합니다.
+
+## 3) 단위/호환성 테스트
+
+`npm test`는 다음 파일을 실행합니다:
+
+- `test/cli-compatibility.test.js` — CLI 도움말/호환성 플래그 확인
+- `test/config-secrets.test.js` — 비밀값 암호화 저장 및 복호화 동작 확인
+- `test/idempotency.test.js` — 재시도 안전성을 위한 idempotency 유틸 동작 확인
+- `test/supabase-append-event.test.js` — Supabase append 동작과 충돌 처리 검증
+
+### 기대 동작
+
+- 실패 시 비정상 종료 코드(0 이 아닌 값) 발생
+- 성공 시 표준 Node 테스트 결과가 출력되고 `0` 종료 코드로 종료
+
+## 4) E2E 테스트
+
+`npm run e2e`는 다음 파일을 실행합니다:
+
+- `e2e/cli-e2e.test.js` — 임시 HOME를 이용한 CLI 기본 경로/명령 검증
+- `e2e/viewer-e2e.test.js` — 읽기 전용 뷰어 시작 후 `/health` 응답 검증
+
+### 참고
+
+- 뷰어 E2E는 임시 포트를 자동으로 할당해 실행합니다.
+- 로컬 환경 부하가 큰 경우 간헐적으로 실패할 수 있으므로 재실행으로 다수 해결됩니다.
+
+## 5) 권장 검증 순서
+
+변경 후 아래 순서로 실행합니다:
+
+1. `npm run lint`
+2. `npm test`
+3. `npm run e2e`
+
+세 단계가 모두 통과하면 PR 단계의 기본 검증을 통과한 것으로 봅니다.
+
+## 6) 관련 문서
+
+- [README.md](README.md)
+- [README.ko.md](README.ko.md)

package/TESTING.md

@@ -0,0 +1,58 @@
+# Testing Guide
+
+**[English](TESTING.md) | [한국어](TESTING.ko.md)**
+
+## 1) Local Test Matrix
+
+Run these commands from the repository root:
+
+- `npm test` — Unit + compatibility tests (`test/*.test.js`)
+- `npm run e2e` — End-to-end smoke checks (`e2e/*.test.js`)
+- `npm run lint` — Syntax check for runtime JS files
+
+## 2) Required Runtime
+
+- Node.js 18+
+- Internet access is only needed when you run ad-hoc scripts that call remote services
+- Test suites themselves do **not** require real Supabase or network access; all external interactions in tests are mocked or use local temporary files
+
+## 3) Unit and Compatibility Tests
+
+`npm test` executes:
+
+- `test/cli-compatibility.test.js` — validates CLI command help text and compatibility flags
+- `test/config-secrets.test.js` — verifies secret persistence and decryption logic
+- `test/idempotency.test.js` — checks operation idempotency helper behavior
+- `test/supabase-append-event.test.js` — validates Supabase append behavior with conflict handling
+
+### Expected result
+
+- Non-zero exit code indicates at least one failing assertion
+- On success, each test file prints its standard Node test summary and exits with `0`
+
+## 4) End-to-End Tests
+
+`npm run e2e` executes:
+
+- `e2e/cli-e2e.test.js` — validates basic CLI command behavior with temporary isolated config paths
+- `e2e/viewer-e2e.test.js` — starts the viewer in read-only mode and verifies `/health` endpoint response
+
+### Notes
+
+- The viewer e2e test binds to a random free port and tears down the process after verification
+- Failures can occur when the local machine is under heavy resource pressure, usually resolved by re-running the suite
+
+## 5) Recommended Validation Flow
+
+For every change, we use this order:
+
+1. `npm run lint`
+2. `npm test`
+3. `npm run e2e`
+
+When all three pass, the repository is ready for PR-ready validation.
+
+## 6) Related documentation
+
+- [README.md](README.md)
+- [README.ko.md](README.ko.md)

package/e2e/cli-e2e.test.js

@@ -0,0 +1,51 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import os from 'node:os';
+import fs from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const CLI_PATH = path.resolve(__dirname, '../src/cli.js');
+
+function runCli(args, options = {}) {
+  return spawnSync(process.execPath, [CLI_PATH, ...args], {
+    encoding: 'utf8',
+    env: options.env ?? process.env,
+    timeout: 5000
+  });
+}
+
+test('config-path prints isolated config location with custom HOME', async () => {
+  const home = await fs.mkdtemp(path.join(os.tmpdir(), 'opensession-e2e-cli-'));
+  const env = {
+    ...process.env,
+    HOME: home,
+    USERPROFILE: home
+  };
+  const expectedPath = path.join(home, '.opensession', 'config.json');
+
+  const result = runCli(['config-path'], { env });
+
+  assert.equal(result.status, 0);
+  assert.equal(result.stdout.trim(), expectedPath);
+});
+
+test('viewer command help is available through command definition', () => {
+  const result = runCli(['viewer', '--help']);
+
+  assert.equal(result.status, 0);
+  assert.match(result.stdout, /Run read-only web viewer for projects\/sessions\/events/);
+  assert.match(result.stdout, /--host <host>/);
+  assert.match(result.stdout, /--port <port>/);
+  assert.match(result.stdout, /vw/);
+});
+
+test('version command returns a semver-compatible value', () => {
+  const result = runCli(['--version']);
+
+  assert.equal(result.status, 0);
+  assert.match(result.stdout.trim(), /^\d+\.\d+\.\d+/);
+});

package/e2e/viewer-e2e.test.js

@@ -0,0 +1,159 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import net from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const CLI_PATH = path.resolve(__dirname, '../src/cli.js');
+
+function createTempConfig(home) {
+  return fs.mkdir(path.join(home, '.opensession'), { recursive: true }).then(() =>
+    fs.writeFile(
+      path.join(home, '.opensession', 'config.json'),
+      JSON.stringify({
+        supabaseUrl: 'https://example.supabase.co',
+        supabaseAnonKey: 'test-anon-key'
+      })
+    )
+  );
+}
+
+function truncateOutput(text, limit = 1200) {
+  if (text.length <= limit) {
+    return text;
+  }
+  return `...${text.slice(-limit)}`;
+}
+
+function formatProcessOutput(output) {
+  return [
+    output.exitCode === null ? '' : `exitCode=${output.exitCode}`,
+    output.signal ? `signal=${output.signal}` : '',
+    `stdout:\n${truncateOutput(output.stdout || '<empty>')}`,
+    `stderr:\n${truncateOutput(output.stderr || '<empty>')}`
+  ].filter(Boolean).join('\n');
+}
+
+async function getFreePort() {
+  const server = net.createServer();
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', resolve);
+  });
+
+  const address = server.address();
+  const port = typeof address === 'object' && address !== null ? address.port : null;
+  await new Promise((resolve) => {
+    server.close(resolve);
+  });
+
+  if (!port) {
+    throw new Error('Failed to allocate ephemeral port for viewer e2e test.');
+  }
+  return port;
+}
+
+async function waitForHealth(url, timeoutMs = 5000, intervalMs = 120, child, output) {
+  const deadline = Date.now() + timeoutMs;
+  let lastStatus;
+
+  while (Date.now() < deadline) {
+    if (child.exitCode !== null) {
+      throw new Error(`Viewer exited before health endpoint became available. ${formatProcessOutput(output)}`);
+    }
+
+    try {
+      const response = await fetch(url);
+      if (response.status === 200) {
+        return response.json();
+      }
+      lastStatus = response.status;
+    } catch (error) {
+      lastStatus = error.code ?? error.name ?? 'unknown';
+    }
+
+    await new Promise((resolve) => {
+      setTimeout(resolve, intervalMs);
+    });
+  }
+
+  throw new Error(`Timed out waiting for health endpoint after ${timeoutMs}ms (last status ${lastStatus}). ${formatProcessOutput(output)}`);
+}
+
+async function runViewer({ port, env }) {
+  const child = spawn(process.execPath, [CLI_PATH, 'viewer', '--host', '127.0.0.1', '--port', String(port)], {
+    env,
+    stdio: ['ignore', 'pipe', 'pipe']
+  });
+  const output = {
+    stdout: '',
+    stderr: '',
+    exitCode: null,
+    signal: null
+  };
+
+  child.stdout?.on('data', (chunk) => {
+    output.stdout += String(chunk);
+  });
+  child.stderr?.on('data', (chunk) => {
+    output.stderr += String(chunk);
+  });
+  child.on('exit', (code, signal) => {
+    output.exitCode = code;
+    output.signal = signal;
+  });
+
+  try {
+    const healthUrl = `http://127.0.0.1:${port}/health`;
+    const body = await waitForHealth(healthUrl, 5000, 120, child, output);
+    assert.equal(body.ok, true);
+    assert.equal(body.mode, 'read-only');
+  } finally {
+    await new Promise((resolve, reject) => {
+      if (!child || child.exitCode !== null) {
+        resolve();
+        return;
+      }
+
+      if (!child.stdout?.destroyed) {
+        child.stdout?.destroy();
+      }
+      if (!child.stderr?.destroyed) {
+        child.stderr?.destroy();
+      }
+
+      const timeout = setTimeout(() => {
+        child.kill('SIGKILL');
+        reject(new Error(`Timed out waiting for viewer process to stop after SIGINT. ${formatProcessOutput(output)}`));
+      }, 2000);
+
+      child.once('exit', () => {
+        clearTimeout(timeout);
+        resolve();
+      });
+
+      child.kill('SIGINT');
+    });
+  }
+}
+
+test('viewer command starts and health endpoint returns read-only status', async () => {
+  const home = await fs.mkdtemp(path.join(os.tmpdir(), 'opensession-e2e-viewer-'));
+  const port = await getFreePort();
+
+  const env = {
+    ...process.env,
+    HOME: home,
+    USERPROFILE: home
+  };
+
+  await createTempConfig(home);
+  await runViewer({ port, env });
+
+  await fs.rm(home, { recursive: true, force: true });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@online5880/opensession",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Session continuity bridge CLI with Supabase backend",
   "type": "module",
   "bin": {
@@ -10,7 +10,8 @@
   "scripts": {
     "start": "node src/cli.js",
     "lint": "sh -c 'for f in src/*.js; do node --check \"$f\"; done'",
-    "test": "node --test test/*.test.js"
+    "test": "node --test test/*.test.js",
+    "e2e": "node --test e2e/*.test.js"
   },
   "engines": {
     "node": ">=18"

package/site/index.html

@@ -10,18 +10,143 @@
   <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&family=JetBrains+Mono:wght@400;600&display=swap" rel="stylesheet">
   <style>
     :root {--bg:#080b12;--bg-soft:#0f1420;--panel:#121a28;--panel-2:#182234;--text:#e9f1ff;--muted:#99abc9;--line:#22314a;--brand:#64d6ff;--brand-2:#8c7bff;--ok:#37d67a;}
-    *{box-sizing:border-box} body{margin:0;font-family:Inter,system-ui,-apple-system,sans-serif;color:var(--text);background:radial-gradient(1200px 700px at 85% -10%,rgba(140,123,255,.22),transparent 60%),radial-gradient(1000px 600px at 10% -10%,rgba(100,214,255,.18),transparent 58%),var(--bg)}
-    .container{width:min(1120px,92vw);margin:0 auto}.topbar{display:flex;justify-content:space-between;align-items:center;padding:18px 0;border-bottom:1px solid rgba(255,255,255,.06);position:sticky;top:0;backdrop-filter:blur(10px);background:rgba(8,11,18,.75)}
-    .brand{font-weight:800}.brand span{color:var(--brand)}.nav a{color:var(--muted);text-decoration:none;margin-left:18px;font-size:.95rem}.hero{padding:74px 0 34px;text-align:center}
-    .eyebrow{color:var(--brand);font-weight:600;letter-spacing:.12em;text-transform:uppercase;font-size:.78rem}h1{margin:14px auto;max-width:900px;font-size:clamp(2rem,5vw,3.8rem);line-height:1.08}.sub{margin:0 auto;max-width:760px;color:var(--muted);font-size:1.08rem}
-    .cta{margin-top:28px;display:flex;gap:12px;justify-content:center;flex-wrap:wrap}.btn{padding:12px 18px;border-radius:12px;text-decoration:none;font-weight:600}.btn.primary{color:#06121a;background:linear-gradient(90deg,var(--brand),#7de6ff)}.btn.secondary{color:var(--text);border:1px solid #2a3c59;background:rgba(255,255,255,.02)}
-    .metrics{margin-top:28px;display:grid;grid-template-columns:repeat(4,1fr);gap:10px;background:rgba(255,255,255,.02);border:1px solid var(--line);border-radius:14px;padding:10px}.metric{background:linear-gradient(180deg,var(--panel),var(--panel-2));border-radius:10px;padding:14px}.metric .n{font-size:1.1rem;font-weight:800}.metric .l{color:var(--muted);font-size:.85rem;margin-top:4px}
-    section{padding:36px 0}h2{margin:0 0 14px;font-size:1.45rem}.cards{display:grid;grid-template-columns:repeat(3,1fr);gap:12px}.card{border:1px solid var(--line);background:linear-gradient(180deg,var(--panel),#111827);border-radius:14px;padding:16px}.card h3{margin:0 0 8px}.card p{margin:0;color:var(--muted);font-size:.93rem}
-    .arch{border:1px solid var(--line);border-radius:14px;padding:16px;background:linear-gradient(180deg,#101827,#0d1421)}.layers{display:grid;grid-template-columns:repeat(4,1fr);gap:10px;margin-top:12px}.layer{border:1px solid #2a3e60;border-radius:10px;padding:12px;background:#0c1320}
-    .timeline{border-left:2px solid #2a3b5a;margin-left:6px;padding-left:16px}.event{margin:0 0 14px}.event span{color:var(--muted);display:block;margin-top:4px}
-    .code{border:1px solid #2a3f60;border-radius:12px;background:#08111d;overflow:auto;font-family:"JetBrains Mono",monospace;font-size:.9rem;line-height:1.6;padding:14px}.code .ok{color:var(--ok)}.code .cmd{color:#8fd0ff}
-    footer{padding:30px 0 42px;color:var(--muted);font-size:.9rem;border-top:1px solid rgba(255,255,255,.06);margin-top:22px}
-    @media (max-width:900px){.cards{grid-template-columns:1fr}.layers{grid-template-columns:1fr 1fr}.metrics{grid-template-columns:1fr 1fr}}
+    * { box-sizing: border-box; }
+    body {
+      margin: 0;
+      font-family: Inter, system-ui, -apple-system, sans-serif;
+      color: var(--text);
+      background:
+        radial-gradient(1200px 700px at 85% -10%, rgba(140, 123, 255, .22), transparent 60%),
+        radial-gradient(1000px 600px at 10% -10%, rgba(100, 214, 255, .18), transparent 58%),
+        var(--bg);
+    }
+    .container {
+      width: min(1120px, 92vw);
+      margin: 0 auto;
+      padding: 0 8px;
+    }
+    .topbar {
+      display: flex;
+      justify-content: space-between;
+      align-items: center;
+      gap: 12px;
+      padding: 18px 0;
+      border-bottom: 1px solid rgba(255, 255, 255, .06);
+      position: sticky;
+      top: 0;
+      backdrop-filter: blur(10px);
+      background: rgba(8, 11, 18, .75);
+    }
+    .topbar .brand {
+      font-weight: 800;
+      line-height: 1.2;
+      white-space: nowrap;
+    }
+    .brand span { color: var(--brand); }
+    .nav { display: flex; flex-wrap: wrap; justify-content: flex-end; gap: 12px 16px; }
+    .nav a {
+      color: var(--muted);
+      text-decoration: none;
+      font-size: .95rem;
+    }
+    .hero { padding: 74px 0 34px; text-align: center; }
+    .eyebrow {
+      color: var(--brand);
+      font-weight: 600;
+      letter-spacing: .12em;
+      text-transform: uppercase;
+      font-size: .78rem;
+    }
+    h1 {
+      margin: 14px auto;
+      max-width: 900px;
+      font-size: clamp(2rem, 5vw, 3.8rem);
+      line-height: 1.08;
+    }
+    .sub { margin: 0 auto; max-width: 760px; color: var(--muted); font-size: 1.08rem; }
+    .cta {
+      margin-top: 28px;
+      display: flex;
+      gap: 12px;
+      justify-content: center;
+      flex-wrap: wrap;
+    }
+    .btn { padding: 12px 18px; border-radius: 12px; text-decoration: none; font-weight: 600; }
+    .btn.primary { color: #06121a; background: linear-gradient(90deg, var(--brand), #7de6ff); }
+    .btn.secondary { color: var(--text); border: 1px solid #2a3c59; background: rgba(255, 255, 255, .02); }
+    .metrics {
+      margin-top: 28px;
+      display: grid;
+      grid-template-columns: repeat(4, 1fr);
+      gap: 10px;
+      background: rgba(255, 255, 255, .02);
+      border: 1px solid var(--line);
+      border-radius: 14px;
+      padding: 10px;
+    }
+    .metric {
+      background: linear-gradient(180deg, var(--panel), var(--panel-2));
+      border-radius: 10px;
+      padding: 14px;
+    }
+    .metric .n { font-size: 1.1rem; font-weight: 800; }
+    .metric .l { color: var(--muted); font-size: .85rem; margin-top: 4px; }
+    section { padding: 36px 0; }
+    h2 { margin: 0 0 14px; font-size: 1.45rem; }
+    .cards { display: grid; grid-template-columns: repeat(3, 1fr); gap: 12px; }
+    .card {
+      border: 1px solid var(--line);
+      background: linear-gradient(180deg, var(--panel), #111827);
+      border-radius: 14px;
+      padding: 16px;
+    }
+    .card h3 { margin: 0 0 8px; }
+    .card p { margin: 0; color: var(--muted); font-size: .93rem; }
+    .arch {
+      border: 1px solid var(--line);
+      border-radius: 14px;
+      padding: 16px;
+      background: linear-gradient(180deg, #101827, #0d1421);
+    }
+    .layers { display: grid; grid-template-columns: repeat(4, 1fr); gap: 10px; margin-top: 12px; }
+    .layer { border: 1px solid #2a3e60; border-radius: 10px; padding: 12px; background: #0c1320; }
+    .timeline { border-left: 2px solid #2a3b5a; margin-left: 6px; padding-left: 16px; }
+    .event { margin: 0 0 14px; }
+    .event span { color: var(--muted); display: block; margin-top: 4px; }
+    .code {
+      border: 1px solid #2a3f60;
+      border-radius: 12px;
+      background: #08111d;
+      overflow: auto;
+      font-family: "JetBrains Mono", monospace;
+      font-size: .9rem;
+      line-height: 1.6;
+      padding: 14px;
+    }
+    .code .ok { color: var(--ok); }
+    .code .cmd { color: #8fd0ff; }
+    footer {
+      padding: 30px 0 42px;
+      color: var(--muted);
+      font-size: .9rem;
+      border-top: 1px solid rgba(255,255,255,.06);
+      margin-top: 22px;
+    }
+
+    @media (max-width: 900px) {
+      .cards { grid-template-columns: repeat(2, 1fr); }
+      .layers { grid-template-columns: repeat(2, 1fr); }
+      .metrics { grid-template-columns: repeat(2, 1fr); }
+    }
+
+    @media (max-width: 640px) {
+      .hero { padding-top: 56px; }
+      .topbar { flex-direction: column; align-items: flex-start; }
+      .cards { grid-template-columns: 1fr; }
+      .layers { grid-template-columns: 1fr; }
+      .metrics { grid-template-columns: 1fr; }
+      .eyebrow { font-size: .72rem; }
+    }
   </style>
 </head>
 <body><div class="container"><div class="topbar"><div class="brand">Open<span>Session</span></div><div class="nav"><a href="#features">Features</a><a href="#docs">Docs</a><a href="#updates">What's New</a></div></div>

package/src/cli.js

@@ -1280,15 +1280,26 @@ program
     }
   });
 
-program
-  .command('tui')
-  .description('Run interactive Terminal UI (TUI) dashboard')
-  .option('--project-key <projectKey>', 'Project key')
-  .action(async (options) => {
-    const config = await readConfig();
-    const client = getClient(config);
-    await startTui(client, options);
-  });
+program
+  .command('tui')
+  .description('Run interactive Terminal UI (TUI) dashboard')
+  .option('--project-key <projectKey>', 'Project key')
+  .option('--project <projectKey>', 'Alias of --project-key')
+  .action(async (options) => {
+    const config = await readConfig();
+    const client = getClient(config);
+    const projectKey = options.projectKey ?? options.project ?? config.defaultProjectKey ?? config.syncStatus?.project;
+    if (!projectKey) {
+      throw new Error('Missing project key. Pass --project-key, sync --project, or run start first.');
+    }
+
+    const project = await ensureProject(client, projectKey, projectKey);
+    await startTui(client, {
+      ...options,
+      projectKey,
+      projectId: project.id
+    });
+  });
 
 program
   .command('ops')

package/src/tui.js

@@ -1,11 +1,16 @@
 import blessed from 'blessed';
 import { listActiveSessions, getSessionEvents, subscribeToSessionEvents } from './supabase.js';
 
-export async function startTui(client, options = {}) {
-  const screen = blessed.screen({
-    smartCSR: true,
-    title: 'OpenSession TUI Dashboard'
-  });
+export async function startTui(client, options = {}) {
+  const projectId = options.projectId ?? options.project_id;
+  if (!projectId) {
+    throw new Error('Missing project id. Pass a valid project id when starting TUI.');
+  }
+
+  const screen = blessed.screen({
+    smartCSR: true,
+    title: 'OpenSession TUI Dashboard'
+  });
 
   const layout = blessed.layout({
     parent: screen,
@@ -91,13 +96,13 @@ export async function startTui(client, options = {}) {
   let selectedSessionId = null;
   let unsubscribeRealtime = null;
 
-  async function refreshSessions() {
-    try {
-      header.setContent(` Loading sessions... `);
-      screen.render();
-      
-      const activeSessions = await listActiveSessions(client, options.projectKey ?? options.project);
-      sessions = activeSessions || [];
+  async function refreshSessions() {
+    try {
+      header.setContent(` Loading sessions... `);
+      screen.render();
+      
+      const activeSessions = await listActiveSessions(client, projectId);
+      sessions = activeSessions || [];
       
       sessionList.setItems(sessions.map(s => `${s.actor} (${s.id.slice(0, 8)})`));
       header.setContent(` OpenSession TUI Dashboard | Total: ${sessions.length} `);

package/test/cli-compatibility.test.js

@@ -41,12 +41,19 @@ test('approve command help keeps required compatibility flags', () => {
   assert.match(result.stdout, /--idempotency-key <idempotencyKey>/);
 });
 
-test('status command help keeps both project-key and project alias', () => {
-  const result = runCli(['status', '--help']);
-  assert.equal(result.status, 0);
-  assert.match(result.stdout, /--project-key <projectKey>/);
-  assert.match(result.stdout, /--project <projectKey>/);
-});
+test('status command help keeps both project-key and project alias', () => {
+  const result = runCli(['status', '--help']);
+  assert.equal(result.status, 0);
+  assert.match(result.stdout, /--project-key <projectKey>/);
+  assert.match(result.stdout, /--project <projectKey>/);
+});
+
+test('tui command help keeps project key compatibility flags', () => {
+  const result = runCli(['tui', '--help']);
+  assert.equal(result.status, 0);
+  assert.match(result.stdout, /--project-key <projectKey>/);
+  assert.match(result.stdout, /--project <projectKey>/);
+});
 
 test('log command help keeps session and limit flags', () => {
   const result = runCli(['log', '--help']);

package/session.txt

@@ -1,3 +0,0 @@
-Session started: 883d114c-ce11-4f6b-a36a-74fac5dc2bfc
-Project: test-all
-Actor: e2e-user