# AGENTS.md — damn-my-slow-skt

> AI Agent rules and codebase documentation. Update this file when completing tasks.

## Project Overview
- **Name**: damn-my-slow-skt v0.5.x
- **Purpose**: SKT/SK Broadband internet SLA speed measurement automation + fee reduction CLI tool
- **What it does**: Automates the flow of entering SK Broadband Myspeed, running SLA speed tests, storing results, and preparing fee-reduction handling when speed is below the SLA threshold.
- **Stack**: TypeScript (ES2020, CommonJS), Node.js 20+, Playwright, SQLite (node:sqlite), Commander CLI
- **Package manager**: npm (use `npm install`, never yarn/pnpm)
- **License**: MIT
- **npm package**: `damn-my-slow-skt`
- **Language of product**: Korean (UI strings, README, commit messages)
- **Language of code**: English (variable names, comments explain why)

## Development Setup

```bash
npm install
npx playwright install chromium
npm run build
npm run typecheck
npm run lint
npm test
```

- No external DB, Redis, or Docker required
- Config file: `~/.damn-my-slow-isp/config-skt.yaml` (YAML, not .env)
- Config requires explicit SKT/SK Broadband official terms acceptance under `terms`
- `run` command requires real SKT/B world credentials or SK Broadband authentication; all other dev tasks work without credentials

## Codebase Structure

```
src/
├── index.ts
├── cli.ts
├── config.ts
├── db.ts
├── skt.ts          # SKT/SK Broadband Myspeed Playwright automation
├── migration.ts
├── notify.ts
├── report.ts
├── scheduler.ts
└── updater.ts
tests/
├── config.test.ts
├── db.test.ts
```

### Key Files Explained
- **skt.ts**: Core browser automation. Drives SK Broadband Myspeed SLA flow. Do not change live-site selectors without browser verification against myspeed.skbroadband.com.
- **cli.ts**: Commander commands. `run` validates required config fields before execution.
- **config.ts**: YAML config load/save, interfaces, defaults, required field validation.
- **scheduler.ts**: Generates launchd/systemd/cron triggers from `max_attempts` and `retry_interval_minutes`.
- **db.ts**: Dual storage backend: `node:sqlite` first, JSON fallback on Node 20.

## Coding Conventions

### TypeScript
- **Module**: CommonJS compatible dependencies
- **Target**: ES2020, `strict: true`
- **Error handling**: Always `catch (e: unknown)`, then narrow to `Error`
- **No new `any`**: Use `unknown` and type guards
- **String formatting**: Template literals
- **Async**: async/await

### Console Output
- Use `chalk` for colors
- Use emoji as status indicators (✅ ❌ 📊 ⏱ 📡 🐌)
- Check `process.stdout.isTTY` for interactive vs cron mode

### Config System
- YAML-based, not .env
- Deep-merged with defaults on load
- Config version tracked in `_config_version` (current: 4)
- `terms` stores current SKT/SK Broadband terms acceptance metadata and is required for `run`
- Migrations are interactive

## Restrictions
- **Never commit credentials** — local config files are gitignored
- **Never break CJS compatibility**
- **Never modify SK Broadband automation selectors** without testing against the live site
- **Never use `process.exit()` in library code** — only CLI entry points
- **Node 20 minimum** — do not use Node 22+ APIs without fallback

## Mandatory Practices
- Update AGENTS.md when completing tasks that change structure, conventions, or dependencies
- Run: `npm run typecheck && npm run lint && npm run build && npm test`
- Use Korean conventional commits
- Keep screenshot-on-error pattern in `skt.ts`
- Test with `--dry-run` when possible to avoid filing real complaints