@nomadamas/k-skill 0.2.2 → 0.2.4

package/skills/seoul-weather-risk/scripts/seoul_weather_risk.py

@@ -0,0 +1,503 @@
+#!/usr/bin/env python3
+"""Read-only HTTPS client for the ASK Seoul seoul-weather-risk skill API."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import pathlib
+import re
+import sys
+import unicodedata
+from dataclasses import dataclass
+from typing import Any
+from urllib.error import HTTPError, URLError
+from urllib.parse import urlencode, urlparse
+from urllib.request import HTTPRedirectHandler, Request, build_opener
+
+
+SKILL_BUNDLE_ID = "seoul-weather-risk"
+PROXY_BASE_URL_ENV = "KSKILL_PROXY_BASE_URL"
+DEFAULT_PROXY_BASE_URL = "https://k-skill-proxy.nomadamas.org"
+LOCAL_DIRECT_ENV = "KSKILL_LOCAL_DIRECT"
+SKILL_API_BASE_URL_ENV = "ASK_SEOUL_SKILL_API_BASE_URL"
+MARKETPLACE_API_KEY_ENV = "MARKETPLACE_API_KEY"
+PROXY_DISABLED_VALUES = frozenset({"off", "false", "0", "disable", "disabled", "none"})
+LOCAL_DIRECT_ENABLED_VALUES = frozenset({"1", "true", "on", "yes"})
+LOCAL_DIRECT_DOTENV_NAMES = frozenset({
+    LOCAL_DIRECT_ENV,
+    SKILL_API_BASE_URL_ENV,
+    MARKETPLACE_API_KEY_ENV,
+})
+PROXY_ROUTE_ROOT = "/v1/ask-seoul/weather-risk"
+LOCATION_MAPPING_PATH = pathlib.Path(__file__).resolve().parents[1] / "references" / "admin-dong-place-map.json"
+LOCATION_MAPPING_VERSION = "kma_admin_dong_grid_20260325"
+LOCATION_MAPPING_SIZE = 427
+EXACT_PRODUCT_IDS = frozenset({
+    "weather_place_risk_window",
+})
+STATUS_CODES = {
+    401: "unauthorized",
+    403: "forbidden",
+    404: "unknown_product",
+    409: "cursor_expired",
+    429: "rate_limited",
+    503: "product_not_ready",
+}
+
+
+class SkillError(RuntimeError):
+    def __init__(self, code: str, message: str, details: dict[str, Any] | None = None) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.details = details or {}
+
+
+class _NoRedirect(HTTPRedirectHandler):
+    """Do not silently move a read request to an unreviewed proxy origin."""
+
+    def redirect_request(self, _req: Request, _fp: Any, _code: int, _msg: str, _headers: Any, _newurl: str) -> None:
+        return None
+
+
+@dataclass(frozen=True)
+class ApiConfig:
+    base_url: str
+    mode: str = "hosted_proxy"
+    bearer_token: str | None = None
+
+
+def _json(value: Any) -> str:
+    return json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+
+
+def _local_direct_config(values: dict[str, str]) -> ApiConfig:
+    base_url = values.get(SKILL_API_BASE_URL_ENV, "").strip()
+    bearer_token = values.get(MARKETPLACE_API_KEY_ENV, "").strip()
+    if not base_url or base_url == "replace-me":
+        raise SkillError("local_direct_not_configured", "local direct API base URL이 필요합니다.")
+    if not bearer_token or bearer_token == "replace-me":
+        raise SkillError("local_direct_not_configured", "local direct Marketplace API key가 필요합니다.")
+
+    parsed = urlparse(base_url)
+    local_http = parsed.scheme == "http" and parsed.hostname in {"127.0.0.1", "localhost", "::1"}
+    if (parsed.scheme != "https" and not local_http) or not parsed.netloc or parsed.path not in {"", "/"} or parsed.query or parsed.fragment:
+        raise SkillError("invalid_local_direct_base_url", "local direct API base URL은 HTTPS origin이어야 합니다.")
+    if parsed.username or parsed.password:
+        raise SkillError("invalid_local_direct_base_url", "local direct API base URL에 사용자 정보는 포함할 수 없습니다.")
+    return ApiConfig(base_url=base_url.rstrip("/"), mode="local_direct", bearer_token=bearer_token)
+
+
+def _current_directory_dotenv() -> dict[str, str]:
+    path = pathlib.Path.cwd() / ".env"
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines()
+    except OSError:
+        return {}
+
+    values: dict[str, str] = {}
+    for line in lines:
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#") or "=" not in stripped:
+            continue
+        name, value = stripped.split("=", 1)
+        name = name.strip()
+        if name in LOCAL_DIRECT_DOTENV_NAMES:
+            values[name] = value.strip().strip('"').strip("'")
+    return values
+
+
+def _api_config(environ: dict[str, str] | None = None) -> ApiConfig:
+    values = ({**_current_directory_dotenv(), **os.environ} if environ is None else environ)
+    if values.get(LOCAL_DIRECT_ENV, "").strip().casefold() in LOCAL_DIRECT_ENABLED_VALUES:
+        return _local_direct_config(values)
+    configured = values.get(PROXY_BASE_URL_ENV, "").strip()
+    if configured.casefold() in PROXY_DISABLED_VALUES:
+        raise SkillError("proxy_disabled", f"{PROXY_BASE_URL_ENV}가 비활성화되어 있습니다.")
+    base_url = (configured if configured and configured != "replace-me" else DEFAULT_PROXY_BASE_URL).rstrip("/")
+
+    parsed = urlparse(base_url)
+    local_http = parsed.scheme == "http" and parsed.hostname in {"127.0.0.1", "localhost", "::1"}
+    if (parsed.scheme != "https" and not local_http) or not parsed.netloc or parsed.path not in {"", "/"} or parsed.query or parsed.fragment:
+        raise SkillError("invalid_proxy_base_url", "k-skill proxy base URL은 HTTPS origin이어야 합니다.")
+    if parsed.username or parsed.password:
+        raise SkillError("invalid_proxy_base_url", "k-skill proxy base URL에 사용자 정보는 포함할 수 없습니다.")
+    return ApiConfig(base_url=base_url)
+
+
+def _error_payload(raw: bytes) -> dict[str, Any]:
+    try:
+        payload = json.loads(raw.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError):
+        return {}
+    return payload if isinstance(payload, dict) else {}
+
+
+def _problem_error(status: int, raw: bytes, headers: Any) -> SkillError:
+    problem = _error_payload(raw)
+    code = problem.get("code") if isinstance(problem.get("code"), str) else STATUS_CODES.get(status, "api_error")
+    message = problem.get("detail") if isinstance(problem.get("detail"), str) else problem.get("title")
+    if not isinstance(message, str) or not message:
+        message = f"ASK Seoul API가 HTTP {status} 응답을 반환했습니다."
+    details = {"status": status}
+    for name in ("type", "title", "product_id", "blockers", "request_id"):
+        if name in problem:
+            details[name] = problem[name]
+    retry_after = headers.get("Retry-After") if headers else None
+    if retry_after:
+        details["retry_after"] = retry_after
+    return SkillError(code, message, details)
+
+
+def _request_json(config: ApiConfig, path: str, query: dict[str, str] | None = None) -> dict[str, Any]:
+    url = f"{config.base_url}{path}"
+    if query:
+        url = f"{url}?{urlencode(query)}"
+    headers = {
+        "Accept": "application/json",
+        "User-Agent": "k-skill-seoul-weather-risk/1",
+    }
+    if config.bearer_token:
+        headers["Authorization"] = f"Bearer {config.bearer_token}"
+    request = Request(url, headers=headers)
+    try:
+        with build_opener(_NoRedirect).open(request, timeout=15) as response:
+            raw = response.read()
+            content_type = response.headers.get_content_type()
+    except HTTPError as exc:
+        # HTTPError is also a file object. Close it after reading so repeated
+        # typed failures do not leak a response handle into the caller's stderr.
+        raw = exc.read()
+        try:
+            error = _problem_error(exc.code, raw, exc.headers)
+        finally:
+            exc.close()
+        raise error from exc
+    except URLError as exc:
+        raise SkillError("network_error", "ASK Seoul API에 연결할 수 없습니다.") from exc
+
+    if content_type != "application/json":
+        raise SkillError("malformed_response", "ASK Seoul API 성공 응답의 Content-Type이 JSON이 아닙니다.")
+    try:
+        payload = json.loads(raw.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise SkillError("malformed_response", "ASK Seoul API 성공 응답이 JSON 객체가 아닙니다.") from exc
+    if not isinstance(payload, dict):
+        raise SkillError("malformed_response", "ASK Seoul API 성공 응답이 JSON 객체가 아닙니다.")
+    return payload
+
+
+def _contract_error(message: str) -> SkillError:
+    return SkillError("response_contract_invalid", message)
+
+
+def _require(value: dict[str, Any], name: str, expected: type | tuple[type, ...]) -> Any:
+    item = value.get(name)
+    if not isinstance(item, expected):
+        raise _contract_error(f"ASK Seoul API 응답의 {name} 계약이 올바르지 않습니다.")
+    return item
+
+
+def _validate_bundle(payload: dict[str, Any]) -> dict[str, Any]:
+    if payload.get("bundle_id") != SKILL_BUNDLE_ID:
+        raise _contract_error("ASK Seoul API 응답의 bundle_id가 일치하지 않습니다.")
+    _require(payload, "registration_ready", bool)
+    products = _require(payload, "products", list)
+    ids: list[str] = []
+    for product in products:
+        if not isinstance(product, dict):
+            raise _contract_error("ASK Seoul API bundle의 product 항목이 객체가 아닙니다.")
+        product_id = _require(product, "product_id", str)
+        _require(product, "registration_ready", bool)
+        blockers = _require(product, "blockers", list)
+        if not all(isinstance(blocker, str) for blocker in blockers):
+            raise _contract_error("ASK Seoul API bundle의 blockers 계약이 올바르지 않습니다.")
+        publication_id = product.get("publication_id")
+        if publication_id is not None and not isinstance(publication_id, str):
+            raise _contract_error("ASK Seoul API bundle의 publication_id 계약이 올바르지 않습니다.")
+        ids.append(product_id)
+    if set(ids) != EXACT_PRODUCT_IDS or len(ids) != len(EXACT_PRODUCT_IDS):
+        raise _contract_error("ASK Seoul API bundle의 제품 목록이 이 스킬의 단일 제품과 다릅니다.")
+    return payload
+
+
+def _validate_product(payload: dict[str, Any], product_id: str) -> dict[str, Any]:
+    if payload.get("bundle_id") != SKILL_BUNDLE_ID or payload.get("product_id") != product_id:
+        raise _contract_error("ASK Seoul API product 응답의 bundle_id 또는 product_id가 일치하지 않습니다.")
+    _require(payload, "registration_ready", bool)
+    blockers = _require(payload, "blockers", list)
+    if not all(isinstance(blocker, str) for blocker in blockers):
+        raise _contract_error("ASK Seoul API product 응답의 blockers 계약이 올바르지 않습니다.")
+    publication_id = payload.get("publication_id")
+    if publication_id is not None and not isinstance(publication_id, str):
+        raise _contract_error("ASK Seoul API product 응답의 publication_id 계약이 올바르지 않습니다.")
+    metadata = _require(payload, "metadata", dict)
+    columns = metadata.get("columns", [])
+    if not isinstance(columns, list) or any(not isinstance(column, dict) or not isinstance(column.get("name"), str) for column in columns):
+        raise _contract_error("ASK Seoul API product metadata.columns 계약이 올바르지 않습니다.")
+    return payload
+
+
+def _validate_data(payload: dict[str, Any], product_id: str, requested_limit: int) -> dict[str, Any]:
+    if payload.get("bundle_id") != SKILL_BUNDLE_ID or payload.get("product_id") != product_id:
+        raise _contract_error("ASK Seoul API data 응답의 bundle_id 또는 product_id가 일치하지 않습니다.")
+    publication_id = _require(payload, "publication_id", str)
+    if not publication_id:
+        raise _contract_error("ASK Seoul API data 응답의 publication_id가 비어 있습니다.")
+    row_count = _require(payload, "row_count", int)
+    limit = _require(payload, "limit", int)
+    has_more = _require(payload, "has_more", bool)
+    rows = _require(payload, "rows", list)
+    next_cursor = payload.get("next_cursor")
+    if row_count < 0 or row_count != len(rows) or limit != requested_limit or not 1 <= limit <= 500:
+        raise _contract_error("ASK Seoul API data page의 row_count 또는 limit 계약이 올바르지 않습니다.")
+    if next_cursor is not None and not isinstance(next_cursor, str):
+        raise _contract_error("ASK Seoul API data page의 next_cursor 계약이 올바르지 않습니다.")
+    if has_more != (next_cursor is not None):
+        raise _contract_error("ASK Seoul API data page의 has_more와 next_cursor가 일치하지 않습니다.")
+    if not all(isinstance(row, dict) for row in rows):
+        raise _contract_error("ASK Seoul API data page의 rows 계약이 올바르지 않습니다.")
+    return payload
+
+
+def _filters(values: list[str]) -> dict[str, str]:
+    parsed: dict[str, str] = {}
+    for value in values:
+        if "=" not in value:
+            raise SkillError("invalid_filter", "필터는 column=value 형식이어야 합니다.")
+        name, expected = value.split("=", 1)
+        name = name.strip()
+        if not name or name in parsed:
+            raise SkillError("invalid_filter", "필터 이름은 비어 있거나 중복될 수 없습니다.")
+        parsed[name] = expected
+    return parsed
+
+
+def _time_bound(value: str, edge: str) -> str:
+    if (
+        len(value) == len("YYYY-MM-DD")
+        and value[4] == "-"
+        and value[7] == "-"
+        and value[:4].isdigit()
+        and value[5:7].isdigit()
+        and value[8:10].isdigit()
+    ):
+        suffix = "00:00:00" if edge == "from" else "23:59:59"
+        return f"{value} {suffix}"
+    return value
+
+
+def _normalize_location_name(value: str) -> str:
+    return " ".join(unicodedata.normalize("NFC", value).strip().split())
+
+
+def _location_mapping_error(message: str) -> SkillError:
+    return SkillError("location_mapping_invalid", message)
+
+
+def _load_location_mapping(path: pathlib.Path = LOCATION_MAPPING_PATH) -> tuple[str, list[dict[str, str]]]:
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise _location_mapping_error("행정동 매핑 reference를 읽을 수 없습니다.") from exc
+
+    if not isinstance(payload, dict) or payload.get("mapping_version") != LOCATION_MAPPING_VERSION:
+        raise _location_mapping_error("행정동 매핑 버전이 지원 계약과 다릅니다.")
+    if not isinstance(payload.get("source"), str) or not payload["source"]:
+        raise _location_mapping_error("행정동 매핑의 source가 올바르지 않습니다.")
+    if not isinstance(payload.get("generated_at"), str) or not payload["generated_at"]:
+        raise _location_mapping_error("행정동 매핑의 generated_at이 올바르지 않습니다.")
+
+    locations = payload.get("locations")
+    if not isinstance(locations, list) or len(locations) != LOCATION_MAPPING_SIZE:
+        raise _location_mapping_error("행정동 매핑 행 수가 지원 계약과 다릅니다.")
+
+    normalized: list[dict[str, str]] = []
+    place_ids: set[str] = set()
+    location_keys: set[tuple[str, str]] = set()
+    for row in locations:
+        if not isinstance(row, dict) or set(row) != {"admin_dong", "gu", "place_id"}:
+            raise _location_mapping_error("행정동 매핑 행의 필드 계약이 올바르지 않습니다.")
+        if not all(isinstance(row[name], str) and row[name].strip() for name in ("admin_dong", "gu", "place_id")):
+            raise _location_mapping_error("행정동 매핑 행에 비어 있거나 문자열이 아닌 값이 있습니다.")
+
+        admin_dong = _normalize_location_name(row["admin_dong"])
+        gu = _normalize_location_name(row["gu"])
+        place_id = row["place_id"].strip()
+        if not place_id.startswith("seoul_admd_") or len(place_id) != len("seoul_admd_") + 10 or not place_id.removeprefix("seoul_admd_").isdigit():
+            raise _location_mapping_error("행정동 매핑의 place_id 형식이 올바르지 않습니다.")
+        if place_id in place_ids or (admin_dong, gu) in location_keys:
+            raise _location_mapping_error("행정동 매핑에 중복된 place_id 또는 행정동·자치구가 있습니다.")
+
+        place_ids.add(place_id)
+        location_keys.add((admin_dong, gu))
+        normalized.append({"admin_dong": admin_dong, "gu": gu, "place_id": place_id})
+
+    return payload["mapping_version"], normalized
+
+
+def _alias_keys(canonical: str) -> set[str]:
+    compact = re.sub(r"\s+", "", canonical)
+    without_je = re.sub(r"제(?=\d)", "", compact)
+    return {
+        compact,
+        without_je,
+        compact.replace(".", "·"),
+        compact.replace(".", ""),
+        without_je.replace(".", "·"),
+        without_je.replace(".", ""),
+    }
+
+
+def _location_indexes(locations: list[dict[str, str]]) -> tuple[dict[str, list[dict[str, str]]], dict[str, list[dict[str, str]]]]:
+    canonical_index: dict[str, list[dict[str, str]]] = {}
+    alias_index: dict[str, list[dict[str, str]]] = {}
+    for row in locations:
+        canonical_index.setdefault(row["admin_dong"], []).append(row)
+        for alias in _alias_keys(row["admin_dong"]):
+            alias_index.setdefault(alias, []).append(row)
+    return canonical_index, alias_index
+
+
+def _resolve_admin_dong(admin_dong: str, gu: str | None = None) -> dict[str, str]:
+    normalized_dong = _normalize_location_name(admin_dong)
+    normalized_gu = _normalize_location_name(gu) if gu is not None else None
+    _version, locations = _load_location_mapping()
+
+    canonical_index, alias_index = _location_indexes(locations)
+    candidates = canonical_index.get(normalized_dong)
+    if candidates is None:
+        candidates = alias_index.get(re.sub(r"\s+", "", normalized_dong))
+    if not candidates:
+        raise SkillError("unknown_admin_dong", f"지원하는 서울 행정동이 아닙니다: {normalized_dong}")
+
+    candidates = list(candidates)
+
+    if normalized_gu is not None:
+        known_gus = {row["gu"] for row in locations}
+        if normalized_gu not in known_gus:
+            raise SkillError("unknown_gu", f"지원하는 서울 자치구가 아닙니다: {normalized_gu}")
+        candidates = [row for row in candidates if row["gu"] == normalized_gu]
+        if not candidates:
+            raise SkillError("unknown_admin_dong", f"{normalized_gu}의 지원 행정동이 아닙니다: {normalized_dong}")
+
+    candidates.sort(key=lambda item: (item["gu"], item["place_id"]))
+    if len(candidates) > 1:
+        raise SkillError(
+            "ambiguous_admin_dong",
+            "동명이므로 자치구를 함께 입력해야 합니다.",
+            {"candidates": candidates},
+        )
+    return candidates[0]
+
+
+def _validate_product_id(product_id: str) -> None:
+    if product_id not in EXACT_PRODUCT_IDS:
+        raise SkillError("unknown_product", f"지원하지 않는 product_id입니다: {product_id}")
+
+
+def _bundle(config: ApiConfig) -> dict[str, Any]:
+    if config.mode == "local_direct":
+        return _validate_bundle(_request_json(config, f"/skill/v1/bundles/{SKILL_BUNDLE_ID}"))
+    return _validate_bundle(_request_json(config, f"{PROXY_ROUTE_ROOT}/bundle"))
+
+
+def _detail(config: ApiConfig, product_id: str) -> dict[str, Any]:
+    _validate_product_id(product_id)
+    if config.mode == "local_direct":
+        return _validate_product(_request_json(config, f"/skill/v1/products/{product_id}"), product_id)
+    return _validate_product(_request_json(config, f"{PROXY_ROUTE_ROOT}/product"), product_id)
+
+
+def _data(config: ApiConfig, product_id: str, query: dict[str, str], limit: int) -> dict[str, Any]:
+    _validate_product_id(product_id)
+    if config.mode == "local_direct":
+        return _validate_data(_request_json(config, f"/skill/v1/products/{product_id}/data", query), product_id, limit)
+    return _validate_data(_request_json(config, f"{PROXY_ROUTE_ROOT}/data", query), product_id, limit)
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="seoul-weather-risk ASK Seoul HTTPS client")
+    commands = parser.add_subparsers(dest="command", required=True)
+    commands.add_parser("preflight", help="live API 환경 설정 확인(네트워크 호출 없음)")
+    commands.add_parser("catalog", help="weather_place_risk_window bundle 조회")
+
+    describe = commands.add_parser("describe", help="제품 metadata 조회")
+    describe.add_argument("--product-id", required=True)
+
+    query = commands.add_parser("query", help="제품 data page 조회")
+    query.add_argument("--product-id", required=True)
+    query.add_argument("--filter", action="append", default=[], metavar="COLUMN=VALUE")
+    query.add_argument("--admin-dong", help="서울 행정동 이름")
+    query.add_argument("--gu", help="동명이명 해소용 서울 자치구 이름")
+    query.add_argument("--from", dest="from_value")
+    query.add_argument("--to", dest="to_value")
+    query.add_argument("--limit", type=int, default=100)
+    query.add_argument("--cursor")
+    return parser
+
+
+def run(argv: list[str]) -> int:
+    args = _parser().parse_args(argv)
+    try:
+        config = _api_config()
+        if args.command == "preflight":
+            result = {
+                "status": "ok",
+                "mode": config.mode,
+                "live_network": False,
+                "user_api_key_required": config.mode == "local_direct",
+                "proxy_base_url_configured": config.mode == "hosted_proxy",
+                "local_direct_base_url_configured": config.mode == "local_direct",
+            }
+        elif args.command == "catalog":
+            result = _bundle(config)
+        elif args.command == "describe":
+            _bundle(config)
+            result = _detail(config, args.product_id)
+        else:
+            if not 1 <= args.limit <= 500:
+                raise SkillError("invalid_limit", "limit은 1부터 500 사이여야 합니다.")
+            _bundle(config)
+            detail = _detail(config, args.product_id)
+            filters = _filters(args.filter)
+            if args.gu is not None and args.admin_dong is None:
+                raise SkillError("invalid_location_input", "--gu는 --admin-dong과 함께 사용해야 합니다.")
+            if args.admin_dong is not None:
+                if not _normalize_location_name(args.admin_dong):
+                    raise SkillError("invalid_location_input", "--admin-dong은 비어 있을 수 없습니다.")
+                if args.gu is not None and not _normalize_location_name(args.gu):
+                    raise SkillError("invalid_location_input", "--gu는 비어 있을 수 없습니다.")
+                if "place_id" in filters:
+                    raise SkillError(
+                        "conflicting_location_input",
+                        "--admin-dong과 place_id 필터는 동시에 사용할 수 없습니다.",
+                    )
+                resolved = _resolve_admin_dong(args.admin_dong, args.gu)
+                filters["place_id"] = resolved["place_id"]
+            allowed_columns = {column["name"] for column in detail["metadata"].get("columns", [])}
+            unknown = sorted(set(filters) - allowed_columns)
+            if unknown:
+                raise SkillError("unknown_filter", f"공개 projection에 없는 필터입니다: {', '.join(unknown)}")
+            request_query = {**filters, "limit": str(args.limit)}
+            if args.from_value is not None:
+                request_query["from"] = _time_bound(args.from_value, "from")
+            if args.to_value is not None:
+                request_query["to"] = _time_bound(args.to_value, "to")
+            if args.cursor is not None:
+                request_query["cursor"] = args.cursor
+            result = _data(config, args.product_id, request_query, args.limit)
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+        return 0
+    except SkillError as exc:
+        error = {"code": exc.code, "message": exc.message}
+        if exc.details:
+            error["details"] = exc.details
+        print(json.dumps({"error": error}, ensure_ascii=False), file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(run(sys.argv[1:]))

package/skills/seoul-weather-risk/skill.json

@@ -0,0 +1,9 @@
+{
+  "name": "seoul-weather-risk",
+  "description": "서울 행정동 이름을 정식명 우선·허용된 결정적 표기 별칭만으로 정규 place_id로 해석해 ASK 서울의 장소별 기상 위험 예상 시간대(weather_place_risk_window) 단일 제품을 hosted k-skill proxy에서 읽기 전용 조회한다. 기본 경로에는 사용자 API Key와 place_id 입력이 필요 없으며, 등록 전에는 명시적으로 local-direct 검증을 할 수 있다.",
+  "profiles": [
+    "proxy",
+    "lookup"
+  ],
+  "frontmatter": "name: seoul-weather-risk\ndescription: 서울 행정동 이름을 정식명 우선·허용된 결정적 표기 별칭만으로 정규 place_id로 해석해 ASK 서울의 장소별 기상 위험 예상 시간대(weather_place_risk_window) 단일 제품을 hosted k-skill proxy에서 읽기 전용 조회한다. 기본 경로에는 사용자 API Key와 place_id 입력이 필요 없으며, 등록 전에는 명시적으로 local-direct 검증을 할 수 있다.\nlicense: MIT\nmetadata:\n  category: public-data\n  locale: ko-KR\n  phase: live-client"
+}

package/skills/srt-booking/references/TRADEMARK-LEGAL-STATEMENT.md

@@ -0,0 +1,9 @@
+# 상표 사용 법적 고지 — `srt-booking`
+
+이 스킬에서 `SRT` 및 `SR` 명칭은 열차 조회·예약·취소의 **대상 철도 서비스와 운영기관**을 식별하기 위해 사용한다. k-skill의 출처나 운영주체를 SR로 표시하려는 사용이 아니다.
+
+대법원 2005. 6. 10. 선고 [2005도1637 판결](https://www.law.go.kr/LSW/precInfoP.do?precSeq=83920)은 타인의 표장을 출처표시가 아니라 상품 기능 또는 적용 기종을 밝히기 위해 사용하고 상표 사용으로 인식될 수 없는 경우 침해가 아니라고 판시했다. [상표법 제2조](https://www.law.go.kr/법령/상표법/제2조), [제89조](https://www.law.go.kr/법령/상표법/제89조), [제90조](https://www.law.go.kr/법령/상표법/제90조), [제108조](https://www.law.go.kr/법령/상표법/제108조)와 대법원 [2011다18802](https://www.law.go.kr/LSW/precInfoP.do?precSeq=167457), [2019후10418](https://law.go.kr/LSW/precInfoP.do?mode=0&precSeq=230725) 판결에 따라 실제 거래계에서 출처표시로 기능하는지는 표시 태양과 사용 경위 등을 종합해 판단해야 한다.
+
+따라서 이 명칭은 필요한 범위의 평문으로만 사용하고, 별도 근거 없이 로고, 공식·제휴·후원·인증·파트너 표현을 사용하지 않는다. 각 상표의 권리는 해당 권리자에게 있다. 이 문서는 운송계약, API·서비스 약관, 개인정보 또는 예약·결제 흐름의 적법성을 판단하지 않는다.
+
+전체 검토: [제3자 상표의 기능 설명·호환 대상 표시 검토](https://github.com/NomaDamas/k-skill/blob/dev/docs/legal/trademark-use-review.md)

package/skills/store-longevity-radar/instruction.md

@@ -0,0 +1,91 @@
+# 장수 점포 레이더 (상가업소 시계열)
+
+## What this skill does
+
+공공데이터포털 **「소상공인시장진흥공단_상가(상권)정보」** 공개 파일(비회원 다운로드 가능)을 이용해 두 가지를 한다.
+
+1. `current` — 최신 분기 스냅샷(전국 17개 시도 zip)에서 **업종코드/상호 키워드로 점포 전수**를 뽑는다. 스냅샷에 존재 = 해당 시점 영업 중으로 취급되는 데이터다.
+2. `match` — 사용자가 가진 **과거 스냅샷 CSV**(예: 2019년 국가중점데이터 배포본)와 상호·좌표를 매칭해 **"과거에도 존재했고 지금도 존재하는" 장수 점포**를 추출한다.
+
+기본 업종은 문구·완구(`G21302` 문구/회화용품 소매업, `G21306` 장난감 소매업)이며 옵션으로 어떤 업종이든 지정할 수 있다.
+
+## Honest limitations (반드시 사용자에게 고지)
+
+- 이 데이터에는 **사업자등록번호·개업일이 없다.** 산출되는 것은 "최초 관측 시점 하한"(그 시점에 이미 존재)이지 개업일이 아니다.
+- 상호 변경·이전한 점포는 매칭에서 빠진다(과소집계). 동명 상호는 좌표 거리(기본 150m)로 구분하지만 단정하지 않는다.
+- 폐업 확정은 사업자등록번호 확보 후 `nts-business-registration`(국세청 상태조회)으로 하고, 인허가 업종이면 `localdata-business-status`로 인허가일자(업력)를 본다.
+
+## Design principles
+
+- 점수·등급 같은 해석 라벨을 만들지 않는다. 스냅샷 존재 사실 + 매칭 방법만 담는다.
+- 무인증 공개 파일 서버이므로 프록시를 거치지 않고 사용자 머신에서 직접 받는다.
+- 최신 zip은 수백 MB이므로 1일 로컬 캐시(`~/.cache/k-skill/store-longevity-radar/`)한다. 반복 다운로드하지 않는다.
+
+## When to use
+
+- "지금도 영업 중인 오래된 문방구/철물점/레코드점 리스트 뽑아줘"
+- "이 업종 전국 점포 전수 데이터 줘 (주소·좌표 포함)"
+- "10년 전에도 있었고 아직 있는 가게 찾아줘" (과거 스냅샷 CSV 필요)
+
+## Prerequisites
+
+- 인터넷 연결, `python3` (stdlib만 사용)
+- `scripts/store_longevity_radar.py` helper
+- `match`를 쓰려면 과거 스냅샷 CSV 파일 (사용자가 보유하거나 별도 확보; 과거분은 공공데이터포털에서 최신 분기만 배포되므로 강의·연구용 미러 등에서 구한다)
+
+## Credential requirements
+
+- 없음. 무인증 공개 파일 다운로드다.
+
+## Inputs
+
+- `--code`: 상권업종소분류코드 (반복 지정, 기본 `G21302` `G21306`). 다른 업종을 `match`할 때 코드체계가 바뀌었다면 현재 코드와 과거 코드를 모두 반복 지정한다.
+- `--keyword`: 상호 키워드 (반복 지정, 기본 문구/문방구/완구/장난감 — 업종코드 밖 점포 보완용)
+- `--sido`: 시도명 필터 (예: `서울`, `부산`; 생략 시 전국)
+- `--zip`: 이미 받아둔 최신 zip 경로 (생략 시 자동 다운로드+캐시)
+- `--old-csv`: (`match` 전용) 과거 스냅샷 CSV, 반복 지정. `'|'`/`','` 구분자 자동 감지
+- `--max-dist`: (`match` 전용) 동일 상호 허용 좌표 거리(m), 기본 150
+- `--out`, `--format`: 출력 파일/형식 (csv 기본, json 가능)
+
+## CLI examples
+
+```bash
+# 전국 문구·완구 현재 전수 → CSV
+npx -y @nomadamas/k-skill@0 exec store-longevity-radar scripts/store_longevity_radar.py -- \
+  current --out 전국_문구완구.csv
+
+# 서울·부산만, 과거 2019 스냅샷과 매칭해 장수 점포 추출
+npx -y @nomadamas/k-skill@0 exec store-longevity-radar scripts/store_longevity_radar.py -- \
+  match --sido 서울 --sido 부산 --old-csv 상가업소정보_201912_01.csv --out 장수점포.csv
+
+# 다른 업종 예: 철물점 상호 키워드로
+npx -y @nomadamas/k-skill@0 exec store-longevity-radar scripts/store_longevity_radar.py -- \
+  current --code NONE --keyword 철물 --out 전국_철물점.csv
+```
+
+## Workflow
+
+1. `current`부터 실행해 대상 업종 전수를 확보한다. zip 자동 다운로드는 수 분 걸릴 수 있음을 사용자에게 알린다.
+2. 과거 스냅샷 CSV가 있으면 `match`로 장수 점포를 추출한다. 기본 문구·완구 코드는 helper가 2022년 이전 `D08A01`/`D04A01`/`D04A02`를 자동 포함한다. 다른 업종은 현재 코드와 과거 코드를 `--code`로 함께 지정한다.
+3. 결과 전달 시 위 Honest limitations를 함께 요약한다.
+4. 후속 확인이 필요하면 `nts-business-registration`(폐업 확정), `localdata-business-status`(인허가 업력), `kakao-map`(전화번호·현재 등재)을 안내한다.
+
+## Failure modes
+
+- 데이터셋 페이지에서 파일 ID 발견 실패 → `unavailable` + 수동 확인 URL 출력 (분기 개편 시 페이지 구조 변경 가능).
+- 공공데이터포털 접속/다운로드 timeout 또는 HTTP 실패 → `unavailable` + 원인 + 수동 확인 URL 출력.
+- 다운로드 중단 → `.part` 파일만 남고 캐시로 승격되지 않음. 재실행하면 이어서 새로 받는다.
+- `match`에 과거 CSV 미지정 → argparse 에러. 과거분 확보 방법을 사용자에게 안내한다.
+- 0건 매칭: 업종코드가 스냅샷 코드체계와 다를 수 있다. `--keyword`만으로 재시도한다.
+
+## Official surfaces
+
+- 데이터셋: <https://www.data.go.kr/data/15083033/fileData.do>
+- 다운로드: `https://www.data.go.kr/cmm/cmm/fileDownload.do?atchFileId=<FILE_ID>&fileDetailSn=1` (무인증)
+- 관련 스킬: `nts-business-registration`, `localdata-business-status`, `kakao-map`
+
+## Done when
+
+- `current` 결과 건수와 출력 파일 경로가 보고되었다.
+- `match` 사용 시 매칭 방법(상가업소번호/상호+좌표)별 건수가 보고되었다.
+- 개업일이 아닌 "최초 관측 시점 하한"임이 사용자에게 고지되었다.