@mulsok/traders-client 0.1.0

package/README.md

@@ -0,0 +1,103 @@
+# @mulsok/traders-client
+
+mulsok-traders 데스크톱 클라이언트 — 한국 주식 AI 자율 트레이더 (macOS · claude CLI).
+
+[![npm version](https://img.shields.io/npm/v/@mulsok/traders-client.svg)](https://www.npmjs.com/package/@mulsok/traders-client)
+
+> **베타 1라운드** · macOS only · claude CLI (Claude Code) 권장
+
+## 설치
+
+```bash
+npm install -g @mulsok/traders-client
+```
+
+설치 직후 `postinstall` 이 자동으로:
+
+1. macOS LaunchAgent 등록 (`~/Library/LaunchAgents/com.mulsok.traders.client.plist`)
+2. 부팅 시 자동 시작 + 비정상 종료 시 30초 후 재기동
+3. `http://127.0.0.1:5903` 에서 webui 가동
+
+## 사전 요구사항
+
+```bash
+node --version    # v20.0.0 이상
+claude --version  # 2.x 이상 (https://claude.com/claude-code)
+```
+
+## 첫 사용
+
+1. 브라우저 → `http://127.0.0.1:5903/`
+2. 「설정」 페이지 6 탭 입력:
+   - 구독 (트레이더 받기)
+   - AI 모델 (claude CLI 권장)
+   - 증권사 (키움 AppKey/Secret · 모의투자 권장)
+   - 자본 배정 (미설정 시 계좌 예수금 전체)
+   - 디바이스 토큰 (mulsok-traders.vercel.app 에서 발급)
+   - 안전망 (긴급 정지 토글)
+3. PersonasPage → 「지금 분석」 한 번 → 이후 watchdog 자동
+
+## 명령어
+
+```bash
+mulsok-client status     # 데몬 상태 + readiness
+mulsok-client logs       # 로그 실시간 tail
+mulsok-client update     # 최신 버전 받기 + 자동 재시작
+mulsok-client uninstall  # 데몬 제거 (데이터 보존)
+mulsok-client help       # 도움말
+```
+
+## 업데이트
+
+```bash
+npm update -g @mulsok/traders-client
+# 또는
+mulsok-client update
+```
+
+`postinstall` 이 자동으로 데몬 재시작 — 별도 명령 불필요.
+
+## 데이터 위치
+
+```
+~/.mulsok-traders/
+├── config.json       # 설정 (0600)
+├── market.db         # SQLite (universe + candles + watchers)
+├── logs/             # 데몬 로그
+├── personas/<slug>/  # 페르소나 메모리
+├── trade-journal/    # 의사결정 + 주문 (월별 jsonl)
+└── diary/<slug>/     # 페르소나별 일기
+```
+
+## 제거
+
+```bash
+# 데몬 + 패키지 제거 (데이터 보존)
+npm uninstall -g @mulsok/traders-client
+
+# 데이터까지 완전 삭제 (되돌릴 수 없음)
+rm -rf ~/.mulsok-traders
+```
+
+## ⚠️ 베타 1R 한계
+
+- macOS only (Windows/Linux 추후)
+- **`CLIENT_HOST=0.0.0.0` 으로 바꾸지 마세요** — 인증 미들웨어 미구현
+- 자동 업데이트 X · 사용자가 `mulsok-client update`
+- 장애 대응: 사용자 직접 운영 + 피드백
+
+## 문서
+
+- [DOC-704 · 베타 빠른 시작](https://github.com/TaeeunJang/mulsok-traders/blob/main/docs/ops/beta-quickstart.md)
+- [DOC-703 · 클라이언트 설정 가이드](https://github.com/TaeeunJang/mulsok-traders/blob/main/docs/ops/client-config-guide.md)
+- [Web 대시보드](https://mulsok-traders.vercel.app)
+
+## 보안
+
+- 모든 비밀값 (키움 키 · LLM 키 · 디바이스 토큰) 은 `~/.mulsok-traders/config.json` (0600 권한) 에만 저장
+- 서버는 사용자 자격증명·계좌 정보 보관 X (ADR-008 분산 자율 에이전트)
+- 페르소나 프롬프트는 supabase bundle API 로 동적 fetch (HMAC 검증)
+
+## License
+
+UNLICENSED — 베타 1라운드 · 사용자 운영 책임.

package/bin/cli.js

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+/**
+ * mulsok-client CLI
+ *
+ * 사용:
+ *   mulsok-client install     · 데몬 등록 + 가동 (postinstall 에서 자동 호출)
+ *   mulsok-client uninstall   · 데몬 제거 (데이터 보존)
+ *   mulsok-client status      · 현재 상태 (launchctl + readiness)
+ *   mulsok-client logs        · 로그 실시간 (tail -f)
+ *   mulsok-client update      · npm update + 데몬 재시작
+ *   mulsok-client help        · 이 메시지
+ */
+import { execSync, spawnSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { existsSync } from "node:fs";
+
+const __filename = fileURLToPath(import.meta.url);
+const PKG_ROOT = path.resolve(path.dirname(__filename), "..");
+const SCRIPTS_DIR = path.join(PKG_ROOT, "scripts");
+const HOME = process.env.HOME ?? "";
+const LOG_OUT = path.join(HOME, ".mulsok-traders", "logs", "client.out.log");
+const LOG_ERR = path.join(HOME, ".mulsok-traders", "logs", "client.err.log");
+const LABEL = "com.mulsok.traders.client";
+const HEALTH_URL = "http://127.0.0.1:5903/api/health";
+const READINESS_URL = "http://127.0.0.1:5903/api/readiness";
+
+const cmd = process.argv[2];
+
+function bold(s) { return `\x1b[1m${s}\x1b[0m`; }
+function green(s) { return `\x1b[32m${s}\x1b[0m`; }
+function yellow(s) { return `\x1b[33m${s}\x1b[0m`; }
+function red(s) { return `\x1b[31m${s}\x1b[0m`; }
+
+function isMac() {
+  return process.platform === "darwin";
+}
+
+function runScript(scriptName) {
+  const scriptPath = path.join(SCRIPTS_DIR, scriptName);
+  if (!existsSync(scriptPath)) {
+    console.error(red(`✗ ${scriptName} 을 찾지 못했습니다 (${scriptPath})`));
+    process.exit(1);
+  }
+  const r = spawnSync("bash", [scriptPath], { stdio: "inherit" });
+  process.exit(r.status ?? 0);
+}
+
+function help() {
+  console.log(`${bold("mulsok-client")} · mulsok-traders 데스크톱 클라이언트
+
+  ${bold("명령")}
+    install      데몬 등록 + 가동 (npm install 시 자동 실행)
+    uninstall    데몬 제거 (데이터 보존)
+    status       launchctl 상태 + readiness 6 게이트
+    logs         로그 실시간 tail
+    update       npm update + 데몬 재시작
+    help         이 메시지
+
+  ${bold("운영 위치")}
+    설정/데이터: ~/.mulsok-traders/
+    로그:        ~/.mulsok-traders/logs/client.{out,err}.log
+    LaunchAgent: ~/Library/LaunchAgents/${LABEL}.plist
+
+  ${bold("문서")}
+    https://github.com/TaeeunJang/mulsok-traders/blob/main/docs/ops/beta-quickstart.md
+`);
+}
+
+function status() {
+  if (!isMac()) {
+    console.log(yellow("⚠ macOS 외 OS 는 미지원 (Windows/Linux 추후)"));
+    return;
+  }
+  console.log(bold("▶ 데몬 상태"));
+  try {
+    const out = execSync(`launchctl list | grep ${LABEL} || true`).toString().trim();
+    console.log(out || "  (등록 안 됨)");
+  } catch (e) {
+    console.log(`  launchctl 조회 실패: ${e.message}`);
+  }
+
+  console.log(`\n${bold("▶ 헬스체크")}`);
+  try {
+    const r = execSync(`curl -sf "${HEALTH_URL}"`).toString();
+    console.log(green(`  ✓ ${HEALTH_URL}`));
+    console.log(`  ${r.slice(0, 200)}`);
+  } catch {
+    console.log(red(`  ✗ ${HEALTH_URL} 응답 없음`));
+  }
+
+  console.log(`\n${bold("▶ readiness")}`);
+  try {
+    const r = execSync(`curl -s "${READINESS_URL}" | python3 -m json.tool 2>/dev/null || curl -s "${READINESS_URL}"`).toString();
+    console.log(r);
+  } catch {
+    console.log("  (조회 실패)");
+  }
+}
+
+function logs() {
+  if (!existsSync(LOG_OUT) && !existsSync(LOG_ERR)) {
+    console.log(yellow("⚠ 로그 파일이 아직 없습니다. 데몬 가동 후 다시 시도."));
+    return;
+  }
+  console.log(bold("▶ 로그 실시간 (Ctrl+C 종료)"));
+  console.log(`  ${LOG_OUT}`);
+  console.log(`  ${LOG_ERR}\n`);
+  try {
+    spawnSync("tail", ["-f", LOG_OUT, LOG_ERR], { stdio: "inherit" });
+  } catch (e) {
+    console.error(red(`✗ tail 실패: ${e.message}`));
+  }
+}
+
+function update() {
+  console.log(bold("▶ npm update"));
+  const pkgName = "@mulsok/traders-client";
+  try {
+    execSync(`npm install -g ${pkgName}@latest`, { stdio: "inherit" });
+    console.log(green("✓ 업데이트 완료 — postinstall 이 데몬을 자동 재시작합니다"));
+  } catch (e) {
+    console.error(red(`✗ 업데이트 실패: ${e.message}`));
+    process.exit(1);
+  }
+}
+
+switch (cmd) {
+  case "install":
+    if (!isMac()) {
+      console.error(red("✗ macOS 외 OS 는 미지원입니다 (Windows/Linux 추후 라운드)."));
+      process.exit(1);
+    }
+    runScript("install-daemon.sh");
+    break;
+  case "uninstall":
+    if (!isMac()) {
+      console.error(red("✗ macOS 외 OS 는 미지원입니다."));
+      process.exit(1);
+    }
+    runScript("uninstall-daemon.sh");
+    break;
+  case "status":
+    status();
+    break;
+  case "logs":
+    logs();
+    break;
+  case "update":
+    update();
+    break;
+  case "help":
+  case undefined:
+    help();
+    break;
+  default:
+    console.error(red(`✗ 알 수 없는 명령: ${cmd}`));
+    help();
+    process.exit(1);
+}

package/bin/postinstall.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+/**
+ * postinstall — npm install 직후 자동 실행.
+ *
+ * 동작:
+ *   1. 환경 사전 점검 (macOS · Node 20+ · CI 환경 skip)
+ *   2. dist/server/index.js 존재 확인 (publish 된 tarball 에 포함되어야)
+ *   3. install-daemon.sh 호출 → LaunchAgent 등록 + 데몬 가동
+ *
+ * 실패 시:
+ *   - graceful exit 0 (npm install 자체는 통과)
+ *   - 사용자에게 수동 명령 안내: `mulsok-client install`
+ */
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { existsSync } from "node:fs";
+
+const __filename = fileURLToPath(import.meta.url);
+const PKG_ROOT = path.resolve(path.dirname(__filename), "..");
+const SCRIPT = path.join(PKG_ROOT, "scripts", "install-daemon.sh");
+const DIST_INDEX = path.join(PKG_ROOT, "dist", "server", "index.js");
+
+function gray(s) { return `\x1b[90m${s}\x1b[0m`; }
+function yellow(s) { return `\x1b[33m${s}\x1b[0m`; }
+function green(s) { return `\x1b[32m${s}\x1b[0m`; }
+
+// CI 환경 또는 nested install 은 skip
+if (process.env.CI || process.env.MULSOK_SKIP_POSTINSTALL === "1") {
+  console.log(gray("[mulsok] postinstall skipped (CI 또는 MULSOK_SKIP_POSTINSTALL=1)"));
+  process.exit(0);
+}
+
+// macOS 외 OS — 메시지만 출력하고 통과
+if (process.platform !== "darwin") {
+  console.log(yellow("[mulsok] macOS 외 OS 는 데몬 자동 등록을 건너뜁니다 (현재 베타 1라운드는 macOS only)"));
+  process.exit(0);
+}
+
+// dist 미포함 — 개발용 install 가능성 (workspace 등). skip.
+if (!existsSync(DIST_INDEX)) {
+  console.log(gray("[mulsok] dist/server/index.js 미존재 — 개발용 install 로 간주, 자동 등록 건너뜀"));
+  console.log(gray("           수동 등록: cd apps/client && npm run build && ./scripts/install-daemon.sh"));
+  process.exit(0);
+}
+
+// install-daemon.sh 호출
+console.log(green("[mulsok] LaunchAgent 자동 등록 중..."));
+const r = spawnSync("bash", [SCRIPT], { stdio: "inherit" });
+
+if ((r.status ?? 0) !== 0) {
+  console.log(yellow(`\n[mulsok] 자동 등록 실패 (exit ${r.status}). 수동으로 다시 시도:`));
+  console.log(yellow("           mulsok-client install"));
+}
+
+// 항상 0 으로 종료 — npm install 자체는 통과
+process.exit(0);

package/bin/preuninstall.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+/**
+ * preuninstall — `npm uninstall -g @mulsok/traders-client` 직전 실행.
+ *
+ * 동작:
+ *   - macOS: launchctl bootout + plist 삭제 (uninstall-daemon.sh 호출)
+ *   - 데이터 (~/.mulsok-traders/) 는 보존
+ *
+ * 항상 graceful exit 0 — uninstall 자체는 통과.
+ */
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { existsSync } from "node:fs";
+
+const __filename = fileURLToPath(import.meta.url);
+const PKG_ROOT = path.resolve(path.dirname(__filename), "..");
+const SCRIPT = path.join(PKG_ROOT, "scripts", "uninstall-daemon.sh");
+
+function gray(s) { return `\x1b[90m${s}\x1b[0m`; }
+
+if (process.env.CI || process.env.MULSOK_SKIP_PREUNINSTALL === "1") {
+  process.exit(0);
+}
+
+if (process.platform !== "darwin") {
+  process.exit(0);
+}
+
+if (existsSync(SCRIPT)) {
+  console.log(gray("[mulsok] LaunchAgent 자동 제거..."));
+  spawnSync("bash", [SCRIPT], { stdio: "inherit" });
+}
+
+// 데이터는 보존 — 사용자가 명시적으로 rm -rf ~/.mulsok-traders 해야 삭제됨
+process.exit(0);

package/dist/server/broker/kiwoom/cache.js

@@ -0,0 +1,86 @@
+/**
+ * 인메모리 TTL 캐시 (apps/client · 단일 프로세스 OK)
+ *
+ * 용도:
+ *   - 같은 종목 현재가를 1초 내 여러 페르소나가 요청 → 1회 호출
+ *   - 일봉 60초 캐시 (장 중 빈번 요청)
+ *   - 종목 마스터 24h 캐시
+ *
+ * TTL 정책 가이드:
+ *   - 현재가:    1 초
+ *   - 호가:      1 초
+ *   - 분봉:     10 초
+ *   - 일봉:     60 초
+ *   - 거래량 랭킹: 30 초
+ *   - 종목 정보: 86400 초 (1 일)
+ *
+ * 클래스 대신 단순 함수 + Map · 의도적으로 가벼움 유지
+ */
+const store = new Map();
+/** 만료된 엔트리 자동 정리 (lazy · 다음 get 시) */
+function isFresh(entry) {
+    return entry.expiresAt > Date.now();
+}
+export function cacheGet(key) {
+    const entry = store.get(key);
+    if (!entry)
+        return undefined;
+    if (!isFresh(entry)) {
+        store.delete(key);
+        return undefined;
+    }
+    return entry.value;
+}
+export function cacheSet(key, value, ttlSec) {
+    store.set(key, { value, expiresAt: Date.now() + ttlSec * 1000 });
+}
+export function cacheDelete(key) {
+    store.delete(key);
+}
+/** 패턴 일치 키 모두 삭제 (예: `current-price:*`) · 시뮬에서 종목 invalidate */
+export function cacheDeletePrefix(prefix) {
+    for (const k of store.keys()) {
+        if (k.startsWith(prefix))
+            store.delete(k);
+    }
+}
+/** 현재 캐시 통계 (디버깅용) */
+export function cacheStats() {
+    // 만료 정리
+    for (const [k, v] of store.entries()) {
+        if (!isFresh(v))
+            store.delete(k);
+    }
+    return { size: store.size, keys: Array.from(store.keys()) };
+}
+/**
+ * cache-or-fetch 헬퍼
+ *
+ * 사용:
+ *   const data = await cacheOrFetch(
+ *     `current-price:${code}`,
+ *     1, // TTL 1s
+ *     () => fetchCurrentPrice(code)
+ *   );
+ */
+export async function cacheOrFetch(key, ttlSec, fetcher) {
+    const cached = cacheGet(key);
+    if (cached !== undefined) {
+        return { value: cached, cached: true };
+    }
+    const value = await fetcher();
+    cacheSet(key, value, ttlSec);
+    return { value, cached: false };
+}
+/** TTL 정책 상수 (호출자가 import 해서 일관 유지) */
+export const TTL = {
+    CURRENT_PRICE: 1,
+    ORDERBOOK: 1,
+    MINUTE_CHART: 10,
+    DAILY_CHART: 60,
+    RANKING: 30,
+    STOCK_INFO: 86400,
+    ACCOUNT_DEPOSIT: 5,
+    ACCOUNT_HOLDINGS: 5,
+};
+//# sourceMappingURL=cache.js.map

package/dist/server/broker/kiwoom/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../../../src-server/broker/kiwoom/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAOH,MAAM,KAAK,GAAG,IAAI,GAAG,EAA+B,CAAC;AAErD,sCAAsC;AACtC,SAAS,OAAO,CAAI,KAAoB;IACtC,OAAO,KAAK,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;AACtC,CAAC;AAED,MAAM,UAAU,QAAQ,CAAI,GAAW;IACrC,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAA8B,CAAC;IAC1D,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAC;IAC7B,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACpB,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAClB,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,KAAK,CAAC,KAAK,CAAC;AACrB,CAAC;AAED,MAAM,UAAU,QAAQ,CAAI,GAAW,EAAE,KAAQ,EAAE,MAAc;IAC/D,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,MAAM,GAAG,IAAI,EAAE,CAAC,CAAC;AACnE,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,GAAW;IACrC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;AACpB,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,iBAAiB,CAAC,MAAc;IAC9C,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;QAC7B,IAAI,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC;YAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAC5C,CAAC;AACH,CAAC;AAED,sBAAsB;AACtB,MAAM,UAAU,UAAU;IACxB,QAAQ;IACR,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;QACrC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;YAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IACnC,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;AAC9D,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,GAAW,EACX,MAAc,EACd,OAAyB;IAEzB,MAAM,MAAM,GAAG,QAAQ,CAAI,GAAG,CAAC,CAAC;IAChC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IACzC,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,OAAO,EAAE,CAAC;IAC9B,QAAQ,CAAC,GAAG,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;IAC7B,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;AAClC,CAAC;AAED,uCAAuC;AACvC,MAAM,CAAC,MAAM,GAAG,GAAG;IACjB,aAAa,EAAE,CAAC;IAChB,SAAS,EAAE,CAAC;IACZ,YAAY,EAAE,EAAE;IAChB,WAAW,EAAE,EAAE;IACf,OAAO,EAAE,EAAE;IACX,UAAU,EAAE,KAAK;IACjB,eAAe,EAAE,CAAC;IAClB,gBAAgB,EAAE,CAAC;CACX,CAAC"}