pinglet-cli 0.2.3 → 0.2.5

package/README.md

@@ -1,127 +1,85 @@
-# Pinglet Client
+# Pinglet 💌
 
-AI가 생각하는 동안 다른 개발자의 Ping을 만나는 메시지 네트워크 — 로컬 런타임(CLI).
+**AI가 생각하는 동안, 다른 개발자의 한 줄을 만나세요.**
 
-`pinglet-backend`(NestJS)와 연동되며, 한 번 설치하면 평소처럼 `claude` / `codex`를
-실행하기만 해도 대기 구간에 다른 개발자의 짧은 메시지가 표시된다.
+Claude Code가 코드를 고치는 동안 "Befuddling…" 스피너만 바라보던 그 자리에,
+다른 개발자들이 남긴 짧은 메시지(**Ping**)가 대신 표시됩니다.
 
-## 설치 및 사용
-
-```bash
-npm install -g pinglet-cli   # 설치 후 명령어는 `pinglet`
+```
+✶ 💌 "금요일 오후 배포는 다음 생에 합시다." (12s · ↓ 1.2k tokens)
 ```
 
-npm 글로벌 설치 시 postinstall이 `pinglet install`까지 자동 수행한다.
-(pnpm/bun처럼 postinstall을 차단하는 매니저에서는 `pinglet install`을 직접 실행)
-
-제거할 때는 반드시 integration 정리를 먼저 한다 — npm은 uninstall 시
-스크립트를 실행하지 않으므로 순서가 바뀌면 설정이 남는다:
+## 시작하기
 
 ```bash
-pinglet uninstall
-npm uninstall -g pinglet-cli
+npm install -g pinglet-cli
 ```
 
-개발 시에는 로컬 백엔드에 연결한다:
+설치가 끝나면 자동으로 Claude Code에 연결됩니다. 이후는 평소처럼 `claude`를
+실행하기만 하면 돼요. 자동 설정이 안 됐다면 `pinglet install` 한 번이면 됩니다.
 
-```bash
-npm install
-npm run build
+- 기존 statusline 설정이 있다면 **백업 후 교체할지 물어보고**, 제거 시 원래대로 복원합니다.
+- Codex도 지원합니다(experimental) — turn 완료 시 macOS 알림으로 Ping이 도착합니다.
 
-# 개발 중 로컬 백엔드에 연결
-node dist/cli.js install --api http://localhost:3000
+## Ping 보내기
 
-# 이후 평소처럼
-claude   # statusline에 💌 Ping 표시
-codex    # turn 완료 시 macOS 알림으로 Ping 전달 (experimental)
-```
+Claude Code 세션 안에서 바로:
 
-| 명령 | 설명 |
-|---|---|
-| `pinglet install [--api <url>] [--force]` | Claude Code / Codex 자동 감지 후 integration 설치 + 서버 등록 + 초기 feed 캐시 |
-| `pinglet uninstall [--purge]` | integration 제거, 기존 설정 복원. `--purge`는 `~/.pinglet`까지 삭제 |
-| `pinglet login [--token <jwt>]` | GitHub 로그인 후 익명 설치를 계정에 연결 |
-| `pinglet post "메시지" [--category <c>]` | 메시지 작성 (GitHub 로그인 필요, 읽기는 로그인 없이 가능) |
-| `pinglet doctor` | 설치/캐시/큐/서버 상태 진단 |
-| `pinglet ping` | 메시지 미리보기 (이벤트 기록 없음) |
+```
+> /pinglet 오늘도 빌드가 초록불이길
+```
 
-내부 명령(integration이 호출): `statusline`, `notify`, `flush`, `refresh`
+또는 터미널에서:
 
-### 세션 안에서 바로 작성
+```bash
+pinglet login          # GitHub 로그인 — 브라우저가 열리고 자동으로 완료됩니다 (최초 1회)
+pinglet post "메시지"
+```
 
-Claude Code 세션에서 `/pinglet 메시지`를 입력하면 등록된다.
-install 시 `~/.claude/commands/pinglet.md` slash command가 함께 설치되며,
-등록 자체는 command 안의 인라인 bash 실행(`pinglet post`)이 수행하고
-모델은 결과 한 줄만 전달하므로 토큰 사용이 매우 적다.
+읽기는 로그인 없이 가능하고, **작성에만 GitHub 로그인이 필요합니다.**
+내가 보낸 Ping이 얼마나 퍼졌는지는 statusline에서 바로 확인됩니다:
 
 ```
-> /pinglet 금요일 오후 배포는 다음 생에 합시다.
+💌 내 Ping "오늘도 빌드가 초록불이길" → 도달률 17%
 ```
 
-## Integration 방식
-
-- **Claude Adapter** — `~/.claude/settings.json`의 `statusLine` hook에
-  `node <cli> statusline`을 연결한다. statusline은 UI 영역이라 LLM context에
-  전혀 들어가지 않으며(Zero Token), Thinking/Working 중에 메시지가 보인다.
-  기존 statusLine 설정은 백업 후 uninstall 시 복원한다.
-  - **Spinner verbs (pool=1 회전)** — `spinnerVerbs`(mode: "replace")에 메시지를
-    **한 번에 하나만** 등록해 "Befuddling…" 자리에 Ping이 표시된다. statusline이
-    60초마다 다음 메시지로 교체하며, Claude Code가 설정을 핫리로드하므로 세션
-    중에도 즉시 반영된다. pool이 1개라 "spinner가 돌았다 = 이 메시지가 표시됐다"가
-    확정된다. Pinglet verb는 zero-width space 마커로 식별하므로 사용자가 직접
-    등록한 verb는 건드리지 않고, uninstall 시 원래대로 복원한다.
-- **Codex Adapter (experimental)** — `~/.codex/config.toml`의 `notify` hook에 연결.
-  notify는 TUI 밖 프로세스라 터미널 안에 그릴 수 없어, MVP에서는 turn 완료 시
-  macOS 알림으로 전달한다.
-
-## 아키텍처 원칙 구현
-
-- **Local-first Rendering** — 서버 feed를 30~50개 미리 받아 `~/.pinglet/feed.json`에
-  캐시하고, 렌더링 순간에는 로컬 파일만 동기 I/O로 읽는다. 렌더링 path에
-  네트워크가 절대 들어가지 않는다.
-- **오프라인 동작** — 서버 미연결 시 시드 메시지로 동작하고, 등록/feed 갱신은
-  백그라운드 `refresh`가 온라인이 되면 자동 재시도한다.
-- **DELIVERED / QUALIFIED_IMPRESSION 분리** — 메시지가 spinner에 armed되면
-  DELIVERED(설치당 1회), armed된 동안 spinner가 3초 이상 실제로 돌았으면
-  QUALIFIED_IMPRESSION(visibleMs 포함)으로 정산한다. "실제로 돌았는지"는
-  statusline hook이 받는 `cost.total_api_duration_ms` 증가분으로 측정한다 —
-  pool이 1개이므로 API 활동 시간만큼 그 메시지가 표시된 것이 확정된다.
-- **Async Telemetry** — 이벤트는 `~/.pinglet/events.jsonl`(Local Event Queue)에
-  append하고, 20개 이상 또는 60초 주기로 detached 프로세스가 batch 전송한다.
-  전송 성공분만 큐에서 제거하므로 실패분은 자동 재시도되며, 재전송 중복은
-  서버가 `eventId`로 dedupe한다.
-- **Privacy** — prompt/응답/코드/환경변수를 읽지 않는다. 수집하는 것은
-  installationId, agentType, OS, clientVersion, 메시지 delivery 이벤트뿐이다.
-
-## 백엔드 API 사용 (pinglet-backend)
-
-| 엔드포인트 | 용도 |
-|---|---|
-| `POST /installations` | agent별 익명 설치 등록 → `{installationId, token}` |
-| `GET /feed?limit=50` | 로컬 캐시용 feed 수신 (installation JWT) |
-| `POST /events/batch` | 이벤트 batch 전송 (최대 200개, eventId dedupe) |
-| `POST /messages` | 메시지 작성 (`post` 명령, 유저 JWT 또는 installation JWT) |
-| `POST /installations/heartbeat` | lastSeenAt 갱신 |
-| `POST /installations/link` | 로그인 후 설치를 계정에 연결 |
-| `GET /auth/github` | GitHub OAuth 시작 (login 명령이 브라우저로 연다) |
+## 명령어
 
-## 로컬 파일
+| 명령 | 설명 |
+|---|---|
+| `pinglet install` | Claude Code / Codex 감지 후 연결 |
+| `pinglet login` | GitHub 계정 연결 (메시지 작성에 필요) |
+| `pinglet post "메시지"` | Ping 보내기 |
+| `pinglet ping` | 지금 표시될 메시지 미리보기 |
+| `pinglet doctor` | 설치·연결 상태 진단 |
+| `pinglet uninstall` | 연결 해제 및 기존 설정 복원 |
+
+## 안심하고 쓰세요
+
+- **토큰 사용량 0** — 메시지는 Claude Code의 UI 영역(statusline/spinner)에만
+  표시되고 모델 컨텍스트에는 전혀 들어가지 않습니다. API 비용과 응답 품질에
+  영향이 없습니다.
+- **코드를 읽지 않습니다** — prompt, 응답, 코드, 환경변수에 접근하지 않습니다.
+  수집하는 것은 설치 ID, OS 종류, 클라이언트 버전, 메시지 노출 이벤트뿐입니다.
+- **터미널이 느려지지 않습니다** — 표시는 로컬 캐시만 읽어서 그리며, 네트워크는
+  백그라운드에서만 사용합니다. 오프라인에서도 동작합니다.
+- **모든 메시지는 검수를 거칩니다** — URL·개인정보·제어문자·부적절한 표현은
+  자동으로 걸러지며, 문제가 되는 메시지는 발견 시 바로 내려주세요
+  (아래 문의·피드백 링크).
+
+## 제거
 
+```bash
+pinglet uninstall            # 연결 해제 + 기존 설정 복원 (npm 제거보다 먼저!)
+npm uninstall -g pinglet-cli
 ```
-~/.pinglet/
-  config.json    # apiBaseUrl, agent별 installation 토큰, adapter 설치 정보
-  feed.json      # Local Feed Cache
-  state.json     # 현재 표시 중 메시지, seen 카운트, flush/refresh 타이밍
-  events.jsonl   # Local Event Queue (append-only)
-```
+
+로컬 데이터(`~/.pinglet`)까지 지우려면 `pinglet uninstall --purge`.
 
 ## 약관 및 개인정보처리방침
 
-Pinglet은 GitHub 계정 정보(로그인 시), 설치 환경 정보, 접속 IP를 서비스 제공·어뷰징
-방지 목적으로 처리합니다. 로그인하여 메시지를 작성하면 아래 문서에 동의한 것으로
-간주됩니다.
+로그인하여 메시지를 작성하면 아래 문서에 동의한 것으로 간주됩니다.
 
-- [이용약관](https://pinglet.halluci.co.kr/terms)
-- [개인정보처리방침](https://pinglet.halluci.co.kr/privacy)
+- [이용약관](https://pinglet.halluci.co.kr/terms) · [개인정보처리방침](https://pinglet.halluci.co.kr/privacy)
 
-문의: leeyeonggyun@naver.com
+문의·피드백: leeyeonggyun@naver.com · [GitHub Issues](https://github.com/mabyko/pinglet-client/issues)

package/dist/commands/login.js

@@ -35,9 +35,11 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runLogin = runLogin;
 const child_process_1 = require("child_process");
+const http = __importStar(require("http"));
 const readline = __importStar(require("readline"));
 const config_1 = require("../config");
 const api_1 = require("../api");
+const LOGIN_TIMEOUT_MS = 180_000;
 function prompt(question) {
     const rl = readline.createInterface({
         input: process.stdin,
@@ -48,10 +50,72 @@ function prompt(question) {
         resolve(answer);
     }));
 }
+function openBrowser(url) {
+    const cmd = process.platform === "darwin"
+        ? ["open", url]
+        : process.platform === "win32"
+            ? ["cmd", "/c", "start", "", url]
+            : ["xdg-open", url];
+    try {
+        (0, child_process_1.spawn)(cmd[0], cmd.slice(1), { stdio: "ignore" }).unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+const RESULT_HTML = (ok) => `<!doctype html>
+<html lang="ko"><head><meta charset="utf-8"><title>Pinglet</title>
+<style>body{font-family:-apple-system,sans-serif;display:flex;align-items:center;
+justify-content:center;height:100vh;margin:0;background:#0f1115;color:#e6e9ef}
+div{text-align:center}p{color:#8b93a3}</style></head><body><div>
+<h1>${ok ? "💌 로그인 완료" : "✗ 로그인 실패"}</h1>
+<p>${ok ? "이 창을 닫고 터미널로 돌아가세요." : "터미널에서 다시 시도해 주세요."}</p>
+</div></body></html>`;
 /**
- * GitHub OAuth 로그인.
- * 브라우저에서 /auth/github → callback JSON의 token을 CLI에 붙여넣는 방식 (MVP).
+ * 루프백 로그인: 일회용 로컬 서버를 띄우고 브라우저에서 OAuth를 마치면
+ * 서버가 http://127.0.0.1:{port}/callback?token=... 으로 토큰을 넘겨준다.
+ * 타임아웃/실패 시 null — 호출부가 수동 붙여넣기로 폴백한다.
  */
+function loginViaLoopback(apiBaseUrl) {
+    return new Promise((resolve) => {
+        let finished = false;
+        const done = (token) => {
+            if (finished)
+                return;
+            finished = true;
+            clearTimeout(timer);
+            // 마지막 응답이 flush될 시간을 주고 닫는다.
+            setTimeout(() => {
+                server.closeAllConnections?.();
+                server.close();
+            }, 200).unref();
+            resolve(token);
+        };
+        const timer = setTimeout(() => done(null), LOGIN_TIMEOUT_MS);
+        const server = http.createServer((req, res) => {
+            const url = new URL(req.url ?? "/", "http://127.0.0.1");
+            if (url.pathname !== "/callback") {
+                res.statusCode = 404;
+                res.end();
+                return;
+            }
+            const token = url.searchParams.get("token");
+            res.setHeader("content-type", "text/html; charset=utf-8");
+            res.end(RESULT_HTML(Boolean(token)));
+            done(token);
+        });
+        server.on("error", () => done(null));
+        server.listen(0, "127.0.0.1", () => {
+            const port = server.address().port;
+            const url = `${apiBaseUrl}/auth/github?cli_port=${port}`;
+            console.log("브라우저에서 GitHub 로그인을 완료해 주세요…");
+            console.log(`  ${url}\n`);
+            openBrowser(url);
+        });
+    });
+}
+/** GitHub OAuth 로그인 — 루프백 자동 수신, 실패 시 수동 붙여넣기 폴백. */
 async function runLogin(args) {
     const config = (0, config_1.loadConfig)();
     let token;
@@ -60,19 +124,14 @@ async function runLogin(args) {
         token = args[tokenIndex + 1];
     }
     if (!token) {
-        const url = `${config.apiBaseUrl}/auth/github`;
         console.log(`\n로그인하면 이용약관(${config.apiBaseUrl}/terms)과 개인정보처리방침(${config.apiBaseUrl}/privacy)에 동의하는 것으로 간주됩니다.`);
-        console.log("브라우저에서 GitHub 로그인 후, 응답 JSON의 token 값을 붙여넣어 주세요.");
-        console.log(`  ${url}\n`);
-        if (process.platform === "darwin") {
-            try {
-                (0, child_process_1.spawn)("open", [url], { stdio: "ignore" }).unref();
-            }
-            catch {
-                // 브라우저를 못 열어도 URL은 출력했으므로 진행
-            }
+        token = (await loginViaLoopback(config.apiBaseUrl)) ?? undefined;
+        if (!token) {
+            // SSH 등 브라우저와 터미널이 다른 기계인 경우를 위한 폴백.
+            console.log("자동 로그인에 실패했습니다. 아래 URL에서 로그인 후 응답 JSON의 token 값을 붙여넣어 주세요.");
+            console.log(`  ${config.apiBaseUrl}/auth/github\n`);
+            token = (await prompt("token: ")).trim();
         }
-        token = (await prompt("token: ")).trim();
     }
     if (!token) {
         console.log("✗ token이 비어 있습니다.");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pinglet-cli",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "AI가 생각하는 동안 다른 개발자의 Ping을 만나는 메시지 네트워크 — Claude Code / Codex integration",
   "license": "MIT",
   "repository": {