터미널 위장형 증권 시세 데스크톱 앱 (Electron + TypeScript, electron-vite). 토스증권 OpenAPI 연동. 공개 시세 조회 + 본인 계좌 포트폴리오를 명령어와 단축키로만 확인한다. GUI 버튼 없음.
API 레퍼런스: https://developers.tossinvest.com/docs · 로컬 사본:
docs/toss/
- 진짜 터미널처럼 — macOS 네이티브 신호등 · 중앙 정렬 제목 · 깜빡이는 블록 커서 · 오버레이 스크롤바. 따뜻한 macOS Terminal 톤으로 위장이 자연스럽다.
- 명령어 + 단축키 only — GUI 버튼 0개. 멀티탭 · 중첩 분할(임의 그리드) · 드래그로 분할/탭 순서 변경.
- 키보드 접근성 — WAI-ARIA 탭(roving tabindex ·
←→/Home/End ·Delete닫기) ·:focus-visible링 · 시맨틱<button>. - 디자인 토큰 — 색은 전부 CSS 변수 → dark/light 런타임 전환. 하드코딩 hex 금지.
- 실 데이터 전용 — 토스 OpenAPI만, mock 없음. 실패는 정직하게
✗로 표시.
git clone https://github.com/leejpsd/stock-term.git && cd stock-term && npm install && npm startnpm start # 실행 (빌드 + 프리뷰 — 사용자용, devtools 없음)
npm run dev # 개발 (electron-vite HMR + devtools 도킹)배포는 클론>실행 방식만 제공한다(개발자 타깃). unsigned .dmg 는 Gatekeeper 마찰이 커서 접음 — 개인용 패키징은
npm run dist로 여전히 가능.
데이터는 실제 토스 OpenAPI 전용(mock 없음). 미연결·실패 시 정직하게 ✗ 실패로 표시한다.
본인 토스 계좌 + OpenAPI 키가 필요하다. 시크릿은 메인 프로세스/로컬에만 저장되고 외부로 안 나간다.
- 개발: 루트에
.env작성(.env.example복사) →TOSS_CLIENT_ID/TOSS_CLIENT_SECRET/TOSS_ACCOUNT. 시작 시 자동 로그인. - 배포 사용자: 터미널에
login입력 →API_KEY=/SECRET_KEY=인터랙티브 입력(secret 가림) → 로컬 저장 후 자동 토큰 발급. 이후login은 저장된 키로 자동. 키는settings에서 마스킹 표시. ⚠️ 토스 포털에서 허용 IP 등록 필요(WTS 설정 → Open API → 허용 IP). 미등록 시 403.
| 명령 | 설명 |
|---|---|
stock <종목> [-w] |
단일 시세 (예: stock 삼성전자). -w로 실시간 폴링 |
watch <종목...> / unwatch |
실시간 와칭 / 해제 (Ctrl+C 중단) |
top / top 등락률 |
시총 상위 / 등락률 상위 (실시간) |
login / logout |
토스 연동 / 해제 |
accounts |
내 계좌 목록(accountSeq 확인) |
portfolio [-w] / pnl |
내 보유종목(-w 실시간) / 평가손익 |
alias 이름 = 명령 |
나만의 명령어 (예: alias 내주식 = portfolio -w) |
tab [이름] |
새 탭 |
split / vsplit / zoom / swap / exit |
분할 / 최대화 / 위치교환 / 닫기 |
settings / theme <dark|light> / pin / clear |
설정 / 테마 / 항상위 / 화면 지움 |
help |
명령어 목록 |
종목은 코드(005930)·티커(AAPL)·종목명(대형주) 모두 인식. 입력 중 회색 고스트 텍스트를 Tab/→로 채택.
⌘/Ctrl+⇧P— 명령어 팔레트 ·⌘/Ctrl+K— clear (터미널 관례)⌘/Ctrl+T— 새 탭 ·⌘/Ctrl+1~9— 탭 전환 ·?— 도움말(help인라인 출력)- 탭(키보드):
Tab/Shift+Tab로 탭바 포커스 →←/→이동 ·Delete닫기 ·Enter진입 (드래그로 순서 변경도 가능) ⌘/Ctrl+D좌우 /⌘/Ctrl+⇧D상하 분할 ·⌘/Ctrl+⇧Enter패널 최대화⌘/Ctrl+⌥방향키·⌘[·⌘]패널 포커스 이동 ·⌘⇧[·⌘⇧]위치 교환↑/↓히스토리 ·Ctrl+Lclear ·Ctrl+C와칭 중단(입력값도 지움) ·Esc오버레이 닫기⌘/Ctrl+B— boss-key (위장 화면, 한 손 토글)
dark / light 2종 — macOS Terminal 풍의 따뜻한 중성 팔레트. 색은 전부 CSS 변수(디자인 토큰)로 관리, theme(무인자=토글) 또는 설정에서 런타임 전환. 크롬(타이틀바·탭·상태바)은 sans-serif, 본문만 mono로 진짜 터미널 대비를 살렸다. 시세 색은 한국 관례(상승=빨강, 하락=파랑).
src/
├── shared/
│ └── types.ts # 메인↔렌더러 공유 도메인 모델 + IPC 계약(StocktermBridge)
├── main/
│ ├── index.ts # 프레임리스 윈도우, IPC
│ └── toss.ts # 토스 OpenAPI 클라이언트 (시크릿은 여기만)
├── preload/
│ └── index.ts # contextBridge 안전 브릿지 (nodeIntegration off)
└── renderer/
├── index.html # 터미널 UI 마크업 (GUI 버튼 없음, 상태바 힌트만)
└── src/ # 변경 경계로 분리된 기능 모듈
├── app.ts # 엔트리: boot + 사이드이펙트 모듈 와이어링 (thin)
├── panes.ts # 멀티탭·분할 트리·드래그(분할/탭 reorder)·키보드 탭 내비(WAI-ARIA)
├── input.ts # 패널 입력: 자동완성 고스트·구문강조·블록 커서
├── commands.ts # CMDS + 명령어 구현 + exec 디스패치
├── overlays.ts · keys.ts · statusbar.ts · theme.ts · persist.ts · boss.ts
├── data.ts · poller.ts · output.ts · format.ts · state.ts · bridge.ts
├── styles.scss # 디자인 토큰(CSS 변수)·스타일 (Vite 가 번들·주입)
└── core/
├── parser.ts # 순수 로직(resolve/fmtQuote/tokenize/rankTop/sparkline/matchSymbols)
└── universe.ts # 탑N 후보 풀(대형주 코드 시드)
docs/toss/ # 토스 OpenAPI 로컬 사본(openapi.json 정본)
tests/ # Vitest (parser·정규화 + 렌더러 부팅 스모크)
타입 안전: 메인↔렌더러는 src/shared/types.ts 의 StocktermBridge 계약에만 의존한다(렌더러는 구현체를 모름 · DIP). 조회 IPC 결과는 ApiResult<T> = {ok,data} | {ok:false,error} 로 통일.
npm run dev # electron-vite dev (HMR)
npm run build # out/ 번들 (main/preload/renderer)
npm run dist # build + electron-builder 패키징 → dist/*.dmg (unsigned, arm64)
npm run typecheck # tsc --noEmit (strict)
npm test # Vitest
npm run lint # ESLint (typescript-eslint) · npm run format (Prettier)기여·컨벤션(주석 규칙 포함): CONTRIBUTING.md
데이터 연동 메모: 토스 OpenAPI엔 순위/시총상위·KOSPI 지수 엔드포인트가 없어 top은 후보 풀(universe.ts) 위에서 직접 계산한다. 모든 watch/top/stock 구독은 중앙 폴러가 심볼을 합쳐 dedup → 주기당 batch 1회만 호출한다.
- 토스 약관: 시세는 본인 매매 목적만. 제3자 제공·재배포·상업적 활용 금지 → BYO-key 구조 유지.
- 시크릿 키는 메인 프로세스/로컬에만. 외부 서버 전송 금지.
.env는 gitignore. - 주문 기능 미포함(조회 전용) — 오발주 리스크 회피.
- 개인 도구 목적. 투자 책임은 사용자 본인.