damn-my-slow-skt/README.ai-ready.md

AI Agentic Coding Setup — damn-my-slow-skt

이 문서는 AI 에이전트(Codex, Claude Code, OpenCode 등)가 이 프로젝트를 개발/테스트할 때 필요한 환경 설정을 안내합니다. 사람 개발자가 AI 코딩 환경을 구성할 때도 참고하세요.

---

Architecture Overview

┌─────────────────────────────────────────────────────┐
│                   damn-my-slow-skt                    │
│                                                      │
│  CLI (Commander)                                     │
│    ├── init      → 설정 wizard + 스케줄 등록          │
│    ├── run       → Playwright → myspeed.skbroadband.com 측정    │
│    ├── history   → SQLite/JSON DB 조회               │
│    ├── report    → 월간 통계                          │
│    └── schedule  → launchd/systemd/cron 등록         │
│                                                      │
│  Storage: SQLite (Node 22+) / JSON fallback (20+)   │
│  Config:  ~/.damn-my-slow-isp/config-skt.yaml        │
│  Terms:   SKT/SK Broadband agreement required        │
│  No external DB/Redis/Docker required!              │
└─────────────────────────────────────────────────────┘

---

Quick Setup (Local Development)

# 1. Install dependencies
npm install

# 2. Install Playwright browsers (headless Chromium)
npx playwright install chromium

# 3. Build
npm run build

# 4. Create test config (optional — only needed for actual SKT/SK브로드밴드 measurement)
cp config.yaml.example ~/.damn-my-slow-isp/config-skt.yaml
# Edit with your SKT/B world credentials and keep the terms block accepted only after reviewing the official URLs

# 5. Run type check + lint + tests
npm run typecheck
npm run lint
npm test

---

Codex Cloud Setup (Ubuntu 24.04)

Codex Cloud는 Docker를 사용할 수 없습니다. 이 프로젝트는 외부 서비스(MySQL, Redis 등)가 불필요하므로 바로 사용 가능합니다.

Setup Script (네트워크 접근 가능 시)

#!/bin/bash
# Codex Cloud: 초기 설정 (network enabled)
npm install
npx playwright install-deps chromium  # 시스템 의존성 (Ubuntu)
npx playwright install chromium       # Chromium 브라우저 바이너리
npm run build

Maintain Script (브랜치 전환 후)

#!/bin/bash
# Codex Cloud: 브랜치 체크아웃 후 유지보수
npm install
npm run build

---

Required Secrets

Secret	Required	Purpose
SKT/B world ID/Password	Yes (for run only)	SKT/B world 계정 — config-skt.yaml에 설정
SKT/SK Broadband Terms Acceptance	Yes (for run only)	terms block in config-skt.yaml; generated by init or v4 migration
Discord Webhook	No	결과 알림
Telegram Token	No	결과 알림

개발/테스트 시에는 credential 없이도 build, typecheck, lint, test 모두 실행 가능합니다. run 명령만 실제 SKT/B world 계정이 필요합니다. 단, 실행 전 현재 SKT/SK브로드밴드 공식 이용약관 동의(terms.accepted, version, accepted_at)도 필요합니다.

---

Available Commands

Command	Description	Needs Credential
npm run build	TypeScript → JavaScript 컴파일	No
npm run typecheck	tsc --noEmit 타입 체크	No
npm run lint	ESLint 정적 분석	No
npm test	Vitest 단위 테스트	No
npm run dev	ts-node 개발 모드	No

---

Tech Stack Summary

Component	Technology	Notes
Language	TypeScript (ES2020, CommonJS)	strict: true
Runtime	Node.js 20+	Node 22+ 권장 (native SQLite)
CLI	Commander + Inquirer + Chalk v4	CJS 호환 버전
Browser	Playwright (Chromium)	SKT/SK브로드밴드 SLA 측정 자동화
Storage	node:sqlite / JSON fallback	외부 DB 불필요
HTTP	Axios	알림, npm 업데이트 체크
Config	YAML (js-yaml)	~/.damn-my-slow-isp/config-skt.yaml; v4 includes SKT terms acceptance
Lint	ESLint + typescript-eslint	eslint.config.mjs
Test	Vitest	tests/ directory