@nomadamas/k-skill 0.1.0

package/skills/korean-scholarship-search/scripts/test_scholarship_filter.py

@@ -0,0 +1,224 @@
+import importlib.util
+import json
+import subprocess
+import sys
+from argparse import Namespace
+from datetime import date, datetime, timezone
+from pathlib import Path
+import unittest
+from unittest import mock
+
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+FILTER_PATH = SCRIPT_DIR / "scholarship_filter.py"
+PLANNER_PATH = SCRIPT_DIR / "university_search_plan.py"
+
+
+def load_module(module_name: str, path: Path):
+    spec = importlib.util.spec_from_file_location(module_name, path)
+    module = importlib.util.module_from_spec(spec)
+    assert spec.loader is not None
+    spec.loader.exec_module(module)
+    return module
+
+
+scholarship_filter = load_module("scholarship_filter", FILTER_PATH)
+university_search_plan = load_module("university_search_plan", PLANNER_PATH)
+
+
+class DeadlineStatusTest(unittest.TestCase):
+    def test_current_kst_date_uses_korea_calendar_day(self):
+        now = datetime(2026, 4, 15, 16, 30, tzinfo=timezone.utc)
+
+        today = scholarship_filter.current_kst_date(now)
+
+        self.assertEqual(today, date(2026, 4, 16))
+
+    def test_resolve_today_falls_back_to_kst_when_missing_or_invalid(self):
+        with mock.patch.object(scholarship_filter, "current_kst_date", return_value=date(2026, 4, 16)):
+            self.assertEqual(scholarship_filter.resolve_today(None), date(2026, 4, 16))
+            self.assertEqual(scholarship_filter.resolve_today("not-a-date"), date(2026, 4, 16))
+
+    def test_infer_deadline_status_overrides_stale_cached_status_with_dates(self):
+        record = {
+            "deadline": {
+                "status": "open",
+                "start": "2026-04-01",
+                "end": "2026-04-14",
+            }
+        }
+
+        status = scholarship_filter.infer_deadline_status(record, date(2026, 4, 15))
+
+        self.assertEqual(status, "closed")
+
+    def test_infer_deadline_status_returns_unknown_for_noncanonical_cached_value_without_dates(self):
+        record = {"deadline": {"status": "d-3"}}
+
+        status = scholarship_filter.infer_deadline_status(record, date(2026, 4, 15))
+
+        self.assertEqual(status, "unknown")
+
+    def test_infer_deadline_status_treats_end_date_equal_to_today_as_open(self):
+        record = {"deadline": {"end": "2026-04-15"}}
+
+        status = scholarship_filter.infer_deadline_status(record, date(2026, 4, 15))
+
+        self.assertEqual(status, "open")
+
+    def test_report_does_not_crash_on_noncanonical_status_and_counts_unknown(self):
+        payload = json.dumps([{"name": "x", "deadline": {"status": "d-3"}}], ensure_ascii=False)
+
+        result = subprocess.run(
+            [sys.executable, str(FILTER_PATH), "report", "--today", "2026-04-15"],
+            input=payload,
+            text=True,
+            capture_output=True,
+            check=True,
+        )
+
+        self.assertIn("- 기준일: 2026-04-15 (Asia/Seoul (KST))", result.stdout)
+        self.assertIn("- 상태 미확인: 1", result.stdout)
+        self.assertIn("## 상태 미확인", result.stdout)
+
+
+class AmountHandlingTest(unittest.TestCase):
+    def test_extract_amount_value_uses_amount_fields_and_ignores_irrelevant_notes(self):
+        from_text = scholarship_filter.extract_amount_value({"amount": {"text": "생활비 250만원 지급"}})
+        ignored_notes = scholarship_filter.extract_amount_value(
+            {
+                "amount": {"text": "등록금 전액"},
+                "notes": ["작년에는 500만원 특별지원"],
+            }
+        )
+
+        self.assertEqual(from_text, 2500000)
+        self.assertIsNone(ignored_notes)
+
+    def test_match_filter_keeps_text_only_amount_by_default_and_marks_it_unknown(self):
+        args = Namespace(
+            q=None,
+            org_type=None,
+            school_kind=None,
+            school_name=None,
+            student_level=None,
+            major=None,
+            department_name=None,
+            grade_year=None,
+            gpa=None,
+            income_band=None,
+            min_amount=2000000,
+            max_amount=None,
+            strict_amount=False,
+            deadline_status=None,
+            today="2026-04-15",
+            only_open_now=False,
+            upcoming_within_days=None,
+            deadline_within_days=None,
+        )
+
+        matched, reasons = scholarship_filter.match_filter({"amount": {"text": "등록금 전액"}}, args)
+
+        self.assertTrue(matched)
+        self.assertIn("amount>=2000000?", reasons)
+
+    def test_match_filter_can_drop_text_only_amount_in_strict_mode(self):
+        args = Namespace(
+            q=None,
+            org_type=None,
+            school_kind=None,
+            school_name=None,
+            student_level=None,
+            major=None,
+            department_name=None,
+            grade_year=None,
+            gpa=None,
+            income_band=None,
+            min_amount=2000000,
+            max_amount=None,
+            strict_amount=True,
+            deadline_status=None,
+            today="2026-04-15",
+            only_open_now=False,
+            upcoming_within_days=None,
+            deadline_within_days=None,
+        )
+
+        matched, reasons = scholarship_filter.match_filter({"amount": {"text": "등록금 전액"}}, args)
+
+        self.assertFalse(matched)
+        self.assertEqual(reasons, [])
+
+
+class SparseFieldPolicyTest(unittest.TestCase):
+    def test_eligibility_returns_indeterminate_when_profile_fields_are_missing(self):
+        args = Namespace(
+            org_type=None,
+            school_kind="university",
+            school_name="서울대학교",
+            student_level="undergraduate",
+            major=None,
+            department_name=None,
+            grade_year=None,
+            gpa=None,
+            income_band=5,
+        )
+
+        result = scholarship_filter.eligibility_result({"name": "테스트 장학금"}, args)
+
+        self.assertEqual(result["status"], "indeterminate")
+        self.assertEqual(result["failed"], [])
+        self.assertEqual(
+            result["unknown"],
+            ["school_kind=?", "school_name=?", "student_level=?", "income_band=?"],
+        )
+
+    def test_school_name_filter_does_not_match_urls_any_more(self):
+        args = Namespace(
+            q=None,
+            org_type=None,
+            school_kind=None,
+            school_name="SNU",
+            student_level=None,
+            major=None,
+            department_name=None,
+            grade_year=None,
+            gpa=None,
+            income_band=None,
+            min_amount=None,
+            max_amount=None,
+            strict_amount=False,
+            deadline_status=None,
+            today="2026-04-15",
+            only_open_now=False,
+            upcoming_within_days=None,
+            deadline_within_days=None,
+        )
+        record = {
+            "organization": {"name": "한국장학재단"},
+            "source_url": "https://www.kosaf.go.kr/snu-notice",
+        }
+
+        matched, reasons = scholarship_filter.match_filter(record, args)
+
+        self.assertFalse(matched)
+        self.assertEqual(reasons, [])
+
+
+class UniversitySearchPlanTest(unittest.TestCase):
+    def test_school_domain_suppresses_broad_ac_kr_fallback_queries(self):
+        payload = university_search_plan.build_school_queries(
+            school_name="서울대학교",
+            school_domain="snu.ac.kr",
+            departments=["컴퓨터공학부"],
+            colleges=[],
+            year=2026,
+        )
+
+        queries = payload["search_queries"]
+        self.assertTrue(any(query.startswith("site:snu.ac.kr ") for query in queries))
+        self.assertFalse(any('site:*.ac.kr "서울대학교"' in query for query in queries))
+
+
+if __name__ == "__main__":
+    unittest.main()

package/skills/korean-scholarship-search/scripts/university_search_plan.py

@@ -0,0 +1,148 @@
+#!/usr/bin/env python3
+"""Generate exhaustive scholarship search queries for any Korean university."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from datetime import date
+
+
+def build_school_queries(
+    school_name: str,
+    school_domain: str | None,
+    departments: list[str],
+    colleges: list[str],
+    year: int,
+) -> dict[str, object]:
+    if school_domain:
+        domain_targets = [f"site:{school_domain}"]
+    else:
+        domain_targets = [f"site:*.ac.kr \"{school_name}\""]
+
+    base_suffixes = [
+        f"{year} 장학 공고",
+        f"{year} 교내 장학",
+        f"{year} 외부 장학",
+        f"{year} 학생지원처 장학",
+        f"{year} 학사공지 장학",
+        "장학 공고",
+        "교내 장학",
+        "외부 장학 추천",
+        "학생지원처 장학",
+        "학사공지 장학",
+    ]
+
+    queries: list[str] = []
+    for target in domain_targets:
+        for suffix in base_suffixes:
+            queries.append(f"{target} {suffix}")
+
+        for college in colleges:
+            queries.append(f"{target} \"{college}\" 장학")
+            queries.append(f"{target} \"{college}\" 외부 장학")
+            queries.append(f"{target} \"{college}\" 장학생 모집")
+
+        for department in departments:
+            queries.append(f"{target} \"{department}\" 장학")
+            queries.append(f"{target} \"{department}\" 외부 장학")
+            queries.append(f"{target} \"{department}\" 공지 장학생")
+            queries.append(f"{target} \"{department}\" 대학원 장학")
+
+    url_hints = [
+        "/scholarship",
+        "/student/scholarship",
+        "/notice",
+        "/bbs",
+        "/board",
+        "/undergraduate/notice",
+        "/graduate/notice",
+        "/academics/undergraduate/scholarship",
+        "/academics/graduate/scholarship",
+    ]
+
+    checklist = [
+        "학교 대표 장학공지",
+        "학생지원처 / 장학팀",
+        "학사공지 / 일반공지",
+        "단과대 공지",
+        "학과 / 전공 공지",
+        "대학원 공지",
+        "첨부 PDF/HWP",
+    ]
+
+    return {
+        "scope": "school",
+        "school_name": school_name,
+        "school_domain": school_domain,
+        "year": year,
+        "departments": departments,
+        "colleges": colleges,
+        "coverage_checklist": checklist,
+        "search_queries": queries,
+        "url_hints": url_hints,
+    }
+
+
+def build_nationwide_queries(year: int) -> dict[str, object]:
+    queries = [
+        f"site:*.ac.kr {year} 장학 공고",
+        f"site:*.ac.kr {year} 교내 장학",
+        f"site:*.ac.kr {year} 외부 장학 추천",
+        f"site:*.ac.kr {year} 학과 장학",
+        f"site:*.ac.kr {year} 대학원 장학",
+        "site:*.ac.kr 장학 공고",
+        "site:*.ac.kr 교내 장학",
+        "site:*.ac.kr 외부 장학 추천",
+        "site:*.ac.kr 학과 장학",
+        "site:*.ac.kr 대학원 장학",
+    ]
+    return {
+        "scope": "nationwide-universities",
+        "year": year,
+        "search_queries": queries,
+        "coverage_notes": [
+            "공개된 *.ac.kr 장학 공지 중심",
+            "학교 본부 -> 단과대 -> 학과 순서로 수집",
+            "검색엔진에 노출되지 않은 게시판은 누락 가능",
+            "첨부 PDF/HWP 확인 필요",
+        ],
+    }
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Generate exhaustive official scholarship search queries for a Korean university or for nationwide university coverage.",
+    )
+    parser.add_argument("--school-name", help="University name, e.g. 서울대학교.")
+    parser.add_argument("--school-domain", help="Official university domain, e.g. snu.ac.kr.")
+    parser.add_argument("--department", action="append", default=[], help="Department or program name. Repeatable.")
+    parser.add_argument("--college", action="append", default=[], help="College/faculty name. Repeatable.")
+    parser.add_argument("--nationwide", action="store_true", help="Generate search queries for all Korean universities.")
+    parser.add_argument("--year", type=int, default=date.today().year, help="Target year for notice search.")
+    return parser
+
+
+def main() -> int:
+    parser = build_parser()
+    args = parser.parse_args()
+
+    if args.nationwide:
+        payload = build_nationwide_queries(args.year)
+    else:
+        if not args.school_name:
+            raise SystemExit("--school-name is required unless --nationwide is used")
+        payload = build_school_queries(
+            school_name=args.school_name,
+            school_domain=args.school_domain,
+            departments=args.department,
+            colleges=args.college,
+            year=args.year,
+        )
+
+    print(json.dumps(payload, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/korean-scholarship-search/skill.json

@@ -0,0 +1,8 @@
+{
+  "name": "korean-scholarship-search",
+  "description": "Search Korean scholarship announcements across official KOSAF, university, foundation, company, and public-sector sources, extract amount and eligibility, and filter results by school, income band, student level, and organization type. Users may invoke it with the phrase 장학금 검색 및 조회. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.",
+  "profiles": [
+    "action:submission"
+  ],
+  "frontmatter": "name: korean-scholarship-search\ndescription: Search Korean scholarship announcements across official KOSAF, university, foundation, company, and public-sector sources, extract amount and eligibility, and filter results by school, income band, student level, and organization type. Users may invoke it with the phrase 장학금 검색 및 조회. 돌쇠에서는 공식 표면을 통한 후속 액션까지 진행한다.\nlicense: MIT\nmetadata:\n  category: education\n  locale: ko-KR\n  phase: v1"
+}

package/skills/korean-slang-writing/instruction.md

@@ -0,0 +1,181 @@
+# Korean Slang Writing
+
+## What this skill does
+
+사용자가 "유행어 섞어서", "요즘 말투로", "밈스럽게", "재치있게" 같은 요청을 했을 때, **검증된 한국 유행어 후보**를 먼저 뽑고 필요하면 나무위키 원문 요약을 확인해 한국어 문장·홍보문·SNS 게시글·댓글을 유행어 느낌으로 작성한다.
+
+- 스킬은 **데이터와 조회 도구**만 제공한다: 큐레이션된 시드 인덱스 검색 + 나무위키 best-effort 요약.
+- 실제 문장 작성은 **에이전트(LLM)** 가 스킬이 돌려준 후보 중에서 사용자 의도에 맞는 표현을 골라 한다.
+- 시드 인덱스 출처는 [나무위키 분류:유행어](https://namu.wiki/w/%EB%B6%84%EB%A5%98:%EC%9C%A0%ED%96%89%EC%96%B4) 를 기준으로 수작업 큐레이션한다.
+- risky 수준의 혐오·차별·집단 조롱 가능성이 있는 표현은 시드에 넣지 않는다.
+
+## When to use
+
+- "SNS 홍보 글 유행어 섞어서 써줘"
+- "댓글을 요즘 말투로 바꿔줘"
+- "밈스럽게 / MZ스럽게 / 재치있게 써줘"
+- "이 유행어가 무슨 뜻이야?" (시드 인덱스 + 나무위키 lookup)
+- "긍정적인 느낌의 유행어 3개 추천해줘"
+- "이 상품 카피에 어울리는 유행어 후보 뽑아줘"
+
+## When NOT to use
+
+- 격식 공문, 보도자료, 법률 문서, 사과문, 공식 발표문 등 유행어 사용이 부적절한 문맥
+- 민감한 사회·정치·종교 주제에 풍자 유행어를 끼얹어야 하는 상황
+- 대량 인덱싱 / 전체 웹 스크래핑 (나무위키 약관·Cloudflare 정책 위반 소지)
+- 불특정 다수 대상의 브랜딩 문구에서 유행어 과다 사용 (저자가 확인·동의하지 않은 경우)
+
+## Policy first
+
+- 유행어는 **자연스럽게 적게** 쓰는 것을 기본값으로 한다. 과다 사용은 오히려 촌스럽다.
+- 뜻과 용례를 확인하지 못한 유행어는 사용하지 않는다.
+- `safety` 가 `spicy` 인 항목은 비격식 컨텍스트에서만 쓰고, 격식 자리에는 피한다.
+- `still_usable: false` 표시가 붙은 구형 유행어는 기본 검색 결과에 포함되지 않는다 (`--include-deprecated` 로 의도적 복원 가능).
+- 나무위키는 best-effort 출처이며 Cloudflare 차단·HTML 구조 변경 시 `fetched: false` 또는 `warning` 으로 응답한다. 이 경우 추측하지 말고 시드 인덱스 meaning_short + 링크만 안내한다.
+
+## Prerequisites
+
+- `python3` 3.10+ (`argparse`, `urllib`, `unittest` 만 사용 — 추가 의존성 없음)
+- 스킬 디렉터리의 `scripts/*.py` helper (설치 시 자동 포함)
+- 나무위키 lookup 에는 인터넷 연결이 필요하지만, 실패해도 시드 인덱스만으로 안전하게 응답할 수 있다.
+
+## Response contract
+
+`slang_search` 결과 스키마 (v1):
+
+```json
+{
+  "query": "중꺾마",
+  "filters_applied": {
+    "mood": ["긍정"],
+    "context": ["SNS"],
+    "safety": ["safe"],
+    "intensity": [],
+    "limit": 10,
+    "include_deprecated": false
+  },
+  "matched_before_limit": 12,
+  "total_candidates": 5,
+  "candidates": [
+    {
+      "term": "중꺾마",
+      "aliases": ["중요한 건 꺾이지 않는 마음"],
+      "meaning_short": "포기하지 않는 불굴의 의지.",
+      "usage_context": ["격려", "스포츠", "SNS"],
+      "mood_tags": ["긍정", "의지"],
+      "intensity": "medium",
+      "safety": "safe",
+      "example_usage": ["힘들지만 중꺾마 정신으로 이겨내자!"],
+      "namuwiki_url": "https://namu.wiki/w/...",
+      "era": "2022",
+      "still_usable": true,
+      "match_reason": "exact"
+    }
+  ],
+  "source": "...",
+  "last_reviewed": "2026-04-22"
+}
+```
+
+`match_reason` 우선순위: `exact` > `alias` > `substring` > `no-query` (필터만 적용한 경우).
+
+`slang_lookup` 결과 스키마:
+
+```json
+{
+  "input": "중꺾마",
+  "url": "https://namu.wiki/w/%EC%A4%91%EA%BA%BE%EB%A7%88",
+  "fetched": true,
+  "title": "중꺾마",
+  "summary": "중꺾마는 ...",
+  "error": null,
+  "block_reason": null,
+  "warning": "optional, when HTML parsing failed"
+}
+```
+
+`fetched: false` 인 경우 `block_reason` 이 `blocked` / `not_found` / `upstream_error` 중 하나이며, 에이전트는 추측하지 않고 원문 링크를 제시하거나 다른 출처 확인을 제안한다.
+
+## Workflow
+
+### 1. 사용자 의도 정리
+
+- 글쓰기 목적 (홍보, 댓글, 자기소개, 제목 등)
+- 유행어 강도 (살짝 / 적당히 / 많이)
+- 톤/무드 (긍정, 부정, 유머, 자조, 감탄 등)
+- 문맥 (SNS, 마케팅, 음식, 스포츠, 직장, 학교 등)
+
+### 2. 시드 인덱스에서 후보 탐색
+
+```bash
+python3 scripts/slang_search.py --mood "긍정,유머" --context "SNS,마케팅" --safety safe --limit 5 --format json
+```
+
+주요 옵션:
+
+| 옵션 | 설명 | 예 |
+|------|------|-----|
+| `--query` | 키워드 매칭 (term/aliases/substring) | `--query 중꺾마` |
+| `--mood` | 무드 태그 (OR 매칭) | `--mood 긍정,유머` |
+| `--context` | 문맥 태그 (OR 매칭) | `--context SNS,마케팅` |
+| `--safety` | 안전 수준 (safe/spicy/risky) | `--safety safe,spicy` |
+| `--intensity` | 강도 (subtle/medium/strong) | `--intensity medium,strong` |
+| `--limit` | 반환 개수 (1~50) | `--limit 5` |
+| `--include-deprecated` | 구형 유행어 포함 | `--include-deprecated` |
+| `--index-path` | 외부 인덱스 JSON 경로 | `--index-path ./my-index.json` |
+| `--format` | `json` 또는 `text` | `--format text` |
+
+### 3. (선택) 나무위키 원문 요약 확인
+
+```bash
+python3 scripts/slang_lookup.py "중꺾마" --format json
+python3 scripts/slang_lookup.py "https://namu.wiki/w/%EC%A4%91%EA%BA%BE%EB%A7%88" --max-length 800
+```
+
+- 성공 시 `title`, `summary` 를 돌려준다.
+- 실패 시 `fetched: false` + `block_reason` + `error` 를 돌려준다. 추측하지 말 것.
+
+### 4. 에이전트가 글 작성
+
+1. 후보 중 문맥에 맞는 1~3개를 선택한다. 많이 넣지 않는다.
+2. `safety` 가 `spicy` 인 표현은 비격식 컨텍스트에서만 쓰고, 사용 의도를 분명히 한다.
+3. 결과물을 1~2문장으로 자연스럽게 녹인다.
+4. 필요하면 "사용한 표현: A, B — 의미 확인: [url]" 을 덧붙여 근거 링크를 보여준다.
+5. 사용자가 더 과한/덜 과한 버전을 원하면 대안을 함께 제공한다.
+
+## CLI examples
+
+```bash
+# 1) 특정 유행어 뜻/메타 바로 확인
+python3 scripts/slang_search.py --query "갓생" --format text
+
+# 2) 긍정 무드의 SNS 마케팅 후보 5개
+python3 scripts/slang_search.py --mood "긍정,유머" --context "SNS,마케팅" --safety safe --limit 5
+
+# 3) 이용자가 지정한 커스텀 인덱스로 전환
+python3 scripts/slang_search.py --query "중꺾마" --index-path ~/Downloads/my-slang.json
+
+# 4) 나무위키 원문 요약 시도
+python3 scripts/slang_lookup.py "럭키비키" --timeout 10 --format text
+```
+
+## Response policy
+
+- 응답에는 **선택한 유행어, 최종 문장, 근거 링크** 세 가지를 포함한다.
+- 유행어를 2개 이상 썼다면 각각 왜 썼는지 한 줄 이유를 붙인다.
+- 사용자가 명시적으로 요청하지 않은 상황에서는 유행어를 끼얹지 않는다.
+- 나무위키 요약이 없을 때는 시드의 `meaning_short` 와 원문 링크로 대체한다. "잘 모르겠다" 를 숨기지 않는다.
+
+## Done when
+
+- `slang_search` 가 JSON 으로 최소 한 개의 후보를 돌려주었거나, 의도적으로 0건 (no match) 을 명확히 전달했다.
+- 유행어를 사용한 경우, 각 표현의 뜻/근거 링크가 함께 제시되었다.
+- `safety=risky` 표현은 시드에 없고, `spicy` 표현을 썼다면 왜 괜찮은 문맥인지 한 줄 설명이 있다.
+- 나무위키 lookup 실패 시 추측 대신 원문 링크로 대체되었다.
+
+## Notes
+
+- 시드 인덱스 위치: `data/seed-slang.json` (약 30개 항목). 확장은 PR 로 검토 후 반영한다.
+- `last_reviewed` 필드를 의미 있게 업데이트하지 않는 변경은 받지 않는 편이 안전하다.
+- 이 스킬은 **나무위키 분류:유행어** 를 기반으로 하지만 전체 인덱싱하지 않는다. Cloudflare 차단·데이터 선도 변화에 보수적으로 설계된 v1 이다.
+- 다음 버전에서는 여러 공개 소스를 통합하거나 `last_reviewed` 기반 자동 만료 로직을 넣을 수 있다.

package/skills/korean-slang-writing/scripts/_slang_http.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+import ssl
+import urllib.error
+import urllib.parse
+import urllib.request
+
+
+NAMUWIKI_BASE = "https://namu.wiki/w/"
+_NAMUWIKI_HOSTS = ("namu.wiki", "en.namu.wiki")
+
+_BROWSER_HEADERS = {
+    "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+    "Accept-Language": "ko,en-US;q=0.9,en;q=0.8",
+    "User-Agent": (
+        "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) "
+        "AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.0.0 Safari/537.36"
+    ),
+}
+
+_ssl_ctx: ssl.SSLContext | None = None
+
+
+class LookupError(Exception):
+    pass
+
+
+class BlockedError(LookupError):
+    pass
+
+
+class NotFoundError(LookupError):
+    pass
+
+
+class UpstreamError(LookupError):
+    pass
+
+
+def _get_ssl_context() -> ssl.SSLContext:
+    global _ssl_ctx
+    if _ssl_ctx is None:
+        _ssl_ctx = ssl.create_default_context()
+    return _ssl_ctx
+
+
+def is_namuwiki_url(url: str) -> bool:
+    parsed = urllib.parse.urlparse(url)
+    if parsed.scheme not in {"http", "https"}:
+        return False
+    host = (parsed.hostname or "").lower()
+    return host in _NAMUWIKI_HOSTS
+
+
+def build_namuwiki_url(term_or_url: str) -> str:
+    value = term_or_url.strip()
+    if not value:
+        raise ValueError("term is empty")
+    if is_namuwiki_url(value):
+        return value
+    # Preserve slash so namuwiki subpage titles (e.g. "한국/서울") survive encoding.
+    quoted = urllib.parse.quote(value, safe="/")
+    return f"{NAMUWIKI_BASE}{quoted}"
+
+
+def browser_headers() -> dict[str, str]:
+    return dict(_BROWSER_HEADERS)
+
+
+def fetch_html(url: str, timeout: int) -> str:
+    if not is_namuwiki_url(url):
+        raise ValueError(f"not a namuwiki URL: {url}")
+    request = urllib.request.Request(url, headers=browser_headers())
+    try:
+        with urllib.request.urlopen(request, timeout=timeout, context=_get_ssl_context()) as response:
+            body = response.read()
+    except urllib.error.HTTPError as error:
+        status = error.code
+        if status == 404:
+            raise NotFoundError(f"HTTP 404: {url}") from error
+        if status in (401, 403, 429):
+            raise BlockedError(
+                f"HTTP {status} (possibly Cloudflare / rate-limited) for {url}"
+            ) from error
+        raise UpstreamError(f"HTTP {status} for {url}") from error
+    except urllib.error.URLError as error:
+        raise UpstreamError(f"URL error for {url}: {error.reason}") from error
+    except TimeoutError as error:
+        raise UpstreamError(f"timeout after {timeout}s for {url}") from error
+
+    return body.decode("utf-8", "ignore")