damn-my-slow-skt/AGENTS.md

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

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