Tom You
93 lines
3.6 KiB
Markdown
93 lines
3.6 KiB
Markdown
# 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
|