feat: AnkiConnect 연결 실패 시 3단계 진단 + 웹 UI 상태 배너

[greenheadHQ]

Summary

AnkiConnect 연결 실패 시 원인을 3단계로 진단(네트워크/포트/애드온)하고, 서버 시작 로그 + API 에러 응답 + 웹 UI 배너로 사용자에게 구체적 원인을 알려주는 개선. 현재는 5초 타임아웃 후 504 TimeoutError만 반환하여 Tailscale 꺼짐/Anki 미실행/AnkiConnect 비활성을 구분할 수 없음.

Context

• 현 상태: ankiConnect() 함수(client.ts:47-81)에서 fetch 실패 시 TimeoutError 또는 AnkiConnectError만 반환. 에러 메시지는 "AnkiConnect 응답 시간 초과. Anki가 실행 중인지 확인하세요"로 고정
• 문제점: MiniPC(100.79.80.95:8765)에 Tailscale VPN으로 연결하는 구조에서, Tailscale 꺼짐 vs Anki 미실행 vs AnkiConnect 애드온 비활성의 구분이 불가능. 서버 시작 시에도 진단 없이 경고만 출력
• 트리거: Tailscale 꺼진 상태에서 bun dev 실행 → 서버 시작은 되지만 모든 API 호출이 5초 타임아웃 → 웹 UI에서 무한 로딩 스피너만 표시

Affected Files

File	Role	Required Change
packages/core/src/anki/diagnostics.ts	신규	3단계 연결 진단 함수 (diagnoseAnkiConnect)
packages/core/src/anki/client.ts	AnkiConnect 클라이언트	에러 메시지에 URL/포트 정보 + 에러 코드 기반 분기 추가
packages/core/src/index.ts	Core export	diagnostics export 추가
packages/server/src/index.ts	서버 엔트리	시작 시 diagnoseAnkiConnect() 호출 + /api/health 확장
packages/web/src/lib/api.ts	API 클라이언트	health 응답 타입에 ankiConnect 필드 추가
packages/web/src/hooks/useAnkiStatus.ts	신규	health 엔드포인트 30초 폴링 훅
packages/web/src/components/AnkiStatusBanner.tsx	신규	연결 끊김 시 상단 경고 배너
packages/web/src/components/layout/Layout.tsx	레이아웃	AnkiStatusBanner 배치

Proposed Changes

• packages/core/src/anki/diagnostics.ts 신규 — diagnoseAnkiConnect() 함수 구현
  • 1단계: TCP 소켓으로 호스트 도달 확인 (ETIMEDOUT/EHOSTUNREACH → "네트워크/Tailscale 연결 확인")
  • 2단계: TCP 소켓으로 포트 열림 확인 (ECONNREFUSED → "Anki가 실행 중이 아닙니다")
  • 3단계: getVersion() HTTP 호출 (실패 → "AnkiConnect 애드온 확인")
• packages/core/src/anki/client.ts 수정 — catch 블록에서 에러 코드(ETIMEDOUT/ECONNREFUSED) 기반으로 구체적 메시지 + ANKI_CONNECT_URL 정보 포함
• packages/server/src/index.ts 수정 — runStartupTasks()에 diagnoseAnkiConnect() 추가 (성공: "✅ AnkiConnect 연결 확인 (v6, 45ms)", 실패: 단계별 경고 메시지)
• packages/server/src/index.ts 수정 — GET /api/health 응답에 ankiConnect: AnkiConnectStatus 필드 추가
• packages/web/src/hooks/useAnkiStatus.ts 신규 — useAnkiStatus() 훅 (30초 폴링)
• packages/web/src/components/AnkiStatusBanner.tsx 신규 — 단계별 배너 (빨강: 네트워크, 주황: Anki 미실행, 노랑: 애드온)
• packages/web/src/components/layout/Layout.tsx 수정 — AnkiStatusBanner를 메인 콘텐츠 상단에 배치

Notes

• 서버 시작 시 AnkiConnect 연결 불가해도 서버는 계속 실행 (MiniPC 배포 시 Anki 재시작 대기 필요)
• Bun의 Bun.connect() TCP 소켓으로 네트워크 vs 앱 레벨 구분 가능
• ANKI_CONNECT_URL 환경변수에서 hostname/port 파싱: new URL(process.env.ANKI_CONNECT_URL || "http://localhost:8765")

[greenheadHQ]

LLM 이행 가이드

대상: packages/core/src/anki/ + packages/server/src/ + packages/web/src/
목표: AnkiConnect 연결 실패 시 3단계 진단(네트워크/포트/애드온)으로 원인을 구분하고, 서버 콘솔 + API + 웹 UI에서 사용자에게 알린다
예상 소요: ~20분 (단일 세션)
난이도: 중간
관련 이슈: #107

핵심 원칙

1. 진실 원천 우선: 이 가이드의 값보다 CLI/파일시스템에서 확인한 실제 값이 우선한다.
2. 기존 패턴 존중: errors.ts의 에러 클래스 패턴, index.ts의 startup task 패턴을 따른다.
3. 서버 불중단: AnkiConnect 연결 불가 시에도 서버는 계속 실행한다 (경고만 출력).

---

Phase 1: 사전 확인

다음 명령으로 현재 상태를 확인한다 (병렬 가능):

# 1. AnkiConnect 클라이언트 — 에러 처리 패턴 확인
cat packages/core/src/anki/client.ts | head -90

# 2. 에러 클래스 — 기존 에러 타입 확인
cat packages/core/src/errors.ts

# 3. 서버 startup — runStartupTasks 구조 확인
grep -n "runStartupTasks\|checkVolume\|validateLLM" packages/server/src/index.ts

# 4. /api/health 엔드포인트 — 현재 응답 구조 확인
grep -A5 "api/health" packages/server/src/index.ts

# 5. 웹 health API — 현재 타입 정의 확인
grep -A3 "health" packages/web/src/lib/api.ts

# 6. Layout 컴포넌트 — 배너 삽입 위치 확인
grep -n "Outlet\|main\|children" packages/web/src/components/layout/Layout.tsx | head -10

# 7. Core export — 현재 export 목록 확인
grep "anki" packages/core/src/index.ts

기대 결과:

• client.ts: getAnkiConnectUrl() → ANKI_CONNECT_URL || "http://localhost:8765", DEFAULT_TIMEOUT = 5000
• errors.ts: AnkiConnectError(502), TimeoutError(504) 존재
• index.ts: runStartupTasks() 내에 checkVolumeWritability(), validateLLMProviders() 존재
• /api/health: { status: "ok", timestamp } 반환
• api.ts: health: () => fetchJson<{ status: string; timestamp: string }>("/health")

Phase 2: Core — 진단 함수 + 에러 개선

2-1. 신규 파일: packages/core/src/anki/diagnostics.ts

/**
 * AnkiConnect 연결 3단계 진단
 *
 * 1. 네트워크: TCP 소켓으로 호스트 도달 확인
 * 2. 포트: TCP 소켓으로 포트 열림 확인 (1과 동일 connect에서 에러 코드로 구분)
 * 3. AnkiConnect: getVersion() HTTP 호출
 */

export type AnkiConnectStatus =
  | { ok: true; version: number; latencyMs: number }
  | { ok: false; stage: "network" | "port" | "anki-connect"; message: string; latencyMs: number };

export async function diagnoseAnkiConnect(): Promise<AnkiConnectStatus>

구현 요점:

• ANKI_CONNECT_URL 파싱: new URL(process.env.ANKI_CONNECT_URL || "http://localhost:8765")에서 hostname, port 추출
• TCP 연결: Bun.connect({ hostname, port, socket: { ... } }) with 2초 타임아웃
  • ETIMEDOUT / EHOSTUNREACH → { stage: "network", message: "호스트 {hostname}에 연결할 수 없습니다. 네트워크/Tailscale 연결을 확인하세요." }
  • ECONNREFUSED → { stage: "port", message: "호스트에 연결되었으나 포트 {port}가 닫혀 있습니다. Anki가 실행 중인지 확인하세요." }
• AnkiConnect 확인: ankiConnect<number>("version") 호출
  • 성공 → { ok: true, version, latencyMs }
  • 실패 → { stage: "anki-connect", message: "Anki는 응답하나 AnkiConnect 애드온이 응답하지 않습니다." }
• latencyMs: performance.now() 기준 측정

2-2. 수정: packages/core/src/anki/client.ts

catch 블록(현재 line 68-81)의 에러 메시지를 구체화:

BEFORE:

if (error instanceof Error && error.name === "TimeoutError") {
  throw new TimeoutError(
    `AnkiConnect 응답 시간 초과 (${timeoutMs}ms). Anki가 실행 중인지 확인하세요.`,
  );
}
throw new AnkiConnectError(
  "AnkiConnect에 연결할 수 없습니다. Anki가 실행 중이고 AnkiConnect 애드온이 활성화되어 있는지 확인하세요.",
);

AFTER:

const url = getAnkiConnectUrl();
if (error instanceof Error && error.name === "TimeoutError") {
  throw new TimeoutError(
    `AnkiConnect 응답 시간 초과 (${timeoutMs}ms). 네트워크/Tailscale 연결을 확인하세요. (${url})`,
  );
}
const code = (error as NodeJS.ErrnoException).code;
if (code === "ECONNREFUSED") {
  throw new AnkiConnectError(
    `AnkiConnect 연결 거부 — Anki가 실행 중인지 확인하세요. (${url})`,
  );
}
throw new AnkiConnectError(
  `AnkiConnect에 연결할 수 없습니다. (${url}) — ${error instanceof Error ? error.message : String(error)}`,
);

2-3. 수정: packages/core/src/index.ts

export 추가:

export { diagnoseAnkiConnect, type AnkiConnectStatus } from "./anki/diagnostics.js";

Phase 3: Server + Web — health 확장 + UI 배너

3-1. 수정: packages/server/src/index.ts

startup 진단 추가 — runStartupTasks() 안에:

import { diagnoseAnkiConnect } from "@anki-splitter/core";

// runStartupTasks() 내 — checkVolumeWritability() 다음에 추가:
const ankiStatus = await diagnoseAnkiConnect();
if (ankiStatus.ok) {
  console.log(`✅ AnkiConnect 연결 확인 (v${ankiStatus.version}, ${ankiStatus.latencyMs}ms)`);
} else {
  console.warn(`⚠️ AnkiConnect 연결 실패 [${ankiStatus.stage}]: ${ankiStatus.message}`);
}

/api/health 확장:

BEFORE:

app.get("/api/health", (c) => {
  return c.json({ status: "ok", timestamp: new Date().toISOString() });
});

AFTER:

app.get("/api/health", async (c) => {
  const ankiConnect = await diagnoseAnkiConnect();
  return c.json({
    status: "ok",
    timestamp: new Date().toISOString(),
    ankiConnect,
  });
});

3-2. 수정: packages/web/src/lib/api.ts

health 응답 타입 확장:

BEFORE:

health: () => fetchJson<{ status: string; timestamp: string }>("/health"),

AFTER:

health: () => fetchJson<{
  status: string;
  timestamp: string;
  ankiConnect: {
    ok: boolean;
    version?: number;
    latencyMs: number;
    stage?: "network" | "port" | "anki-connect";
    message?: string;
  };
}>("/health"),

3-3. 신규 파일: packages/web/src/hooks/useAnkiStatus.ts

import { useQuery } from "@tanstack/react-query";
import { api } from "../lib/api";

export function useAnkiStatus() {
  return useQuery({
    queryKey: ["anki-status"],
    queryFn: () => api.health(),
    refetchInterval: 30_000,
    select: (data) => data.ankiConnect,
  });
}

3-4. 신규 파일: packages/web/src/components/AnkiStatusBanner.tsx

연결 끊김 시 페이지 상단에 단계별 색상 배너:

• stage: "network" → 빨간 배경: "🔴 네트워크 연결 끊김 — Tailscale/VPN 연결을 확인하세요"
• stage: "port" → 주황 배경: "🟠 Anki 미실행 — Anki 데스크탑을 시작하세요"
• stage: "anki-connect" → 노랑 배경: "🟡 AnkiConnect 비활성 — 애드온을 확인하세요"
• ok: true → 배너 미표시

useAnkiStatus() 훅을 사용하여 30초마다 자동 갱신.

3-5. 수정: packages/web/src/components/layout/Layout.tsx

<Outlet /> 위에 <AnkiStatusBanner /> 배치:

<main>
  <AnkiStatusBanner />
  <Outlet />
</main>

Phase 4: 검증 + 커밋

정적 검증

# 새 파일 존재 확인 (병렬 가능)
test -f packages/core/src/anki/diagnostics.ts
test -f packages/web/src/hooks/useAnkiStatus.ts
test -f packages/web/src/components/AnkiStatusBanner.tsx

# export 확인
grep "diagnoseAnkiConnect" packages/core/src/index.ts

빌드 검증

cd packages/core && bun run build
cd ../server && bun run build
cd ../web && bun run build

기능 검증

# 1. Tailscale 끈 상태에서 서버 시작 — 콘솔에 "⚠️ AnkiConnect 연결 실패 [network]" 출력 확인
bun run dev:server

# 2. health 엔드포인트 확인
curl -s localhost:3000/api/health -H "X-API-Key: $ANKI_SPLITTER_API_KEY" | python3 -m json.tool

# 3. 브라우저에서 빨간 배너 표시 확인 (chrome-devtools MCP 사용 권장)

# 4. Tailscale 켠 후 30초 이내 배너 소멸 + 콘솔 "✅ AnkiConnect 연결 확인" 확인

커밋

git add packages/core/src/anki/diagnostics.ts \
  packages/core/src/anki/client.ts \
  packages/core/src/index.ts \
  packages/server/src/index.ts \
  packages/web/src/lib/api.ts \
  packages/web/src/hooks/useAnkiStatus.ts \
  packages/web/src/components/AnkiStatusBanner.tsx \
  packages/web/src/components/layout/Layout.tsx

git commit -m "$(cat <<'EOF'
feat(core): AnkiConnect 연결 실패 시 3단계 진단 + 웹 UI 배너

- 신규: diagnoseAnkiConnect() — TCP 소켓 기반 3단계 진단
  (network → port → anki-connect)
- client.ts: 에러 메시지에 ANKI_CONNECT_URL + 에러 코드 기반 분기 추가
- server: 시작 시 진단 로그 + /api/health에 ankiConnect 상태 포함
- web: useAnkiStatus 훅 (30s 폴링) + AnkiStatusBanner (Layout 상단)

Closes #107
EOF
)"

DA 피드백 (권장)

구현 완료 후, /run-da for_pr 스킬을 실행하여 코드 품질을 검증하고,
/parallel-audit로 전수조사를 수행한 뒤 /create-pr 스킬로 PR을 생성한다.

---

주의사항

• Bun.connect 사용: TCP 소켓은 Bun 전용 API. Node.js 호환이 필요하면 net.createConnection 대체 필요하나, 이 프로젝트는 Bun 전용이므로 Bun.connect 사용.
• health 엔드포인트 지연: diagnoseAnkiConnect()가 최대 2초(TCP timeout) 소요. /api/health가 느려질 수 있으나, 인증 미들웨어 밖이라 사용자 체감 영향 적음.
• 30초 폴링: useAnkiStatus의 refetchInterval: 30_000은 네트워크 비용 최소화와 상태 반영 속도의 트레이드오프. 필요시 조절.