dimicheck-tui 0.1.0__tar.gz

dimicheck_tui-0.1.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: dimicheck-tui
+Version: 0.1.0
+Summary: DimiCheck terminal dashboard
+Author: DimiCheck
+Project-URL: Homepage, https://dimicheck.com
+Project-URL: Repository, https://github.com/hjun1052/dimicheck4
+Keywords: dimicheck,tui,textual,oauth,school
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Education
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: keyring>=25.0.0
+Requires-Dist: requests==2.31.0
+Requires-Dist: textual>=0.89.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+
+# DimiCheck TUI
+
+DimiCheck TUI is a terminal dashboard for DimiCheck students. It uses the public OAuth PKCE flow and calls only the student app API surface for v1.
+
+## Install
+
+Use `pipx` for the public install path:
+
+```bash
+pipx install dimicheck-tui
+dimicheck
+```
+
+For local development from this checkout:
+
+```bash
+cd packages/dimicheck-tui
+uv run dimicheck --help
+uv run dimicheck
+```
+
+Set `DIMICHECK_BASE_URL` when testing against a local or staging server:
+
+```bash
+cd packages/dimicheck-tui
+DIMICHECK_BASE_URL=http://127.0.0.1:5000 uv run dimicheck
+```
+
+## Authentication
+
+The TUI never asks for a password in the terminal. On first launch it opens the browser, signs in through DimiCheck OAuth, and stores tokens through the OS credential store.
+
+- macOS: Keychain
+- Windows: Credential Manager
+- Linux: Secret Service compatible keyring
+
+If the OS keyring is unavailable, the app fails closed by default. For controlled environments you can explicitly allow a local token file:
+
+```bash
+dimicheck --allow-plaintext-token
+```
+
+That fallback writes a `0600` permission file. Do not use it on shared machines.
+
+## Commands
+
+```bash
+dimicheck                 # open the TUI dashboard
+dimicheck login           # browser OAuth login
+dimicheck logout          # revoke refresh token and delete local tokens
+dimicheck status get      # print current status
+dimicheck status set toilet
+dimicheck status set etc --reason "상담"
+dimicheck schoollife      # print today's timetable and meal
+```
+
+TUI shortcuts:
+
+- `S`: change status
+- `R`: refresh dashboard
+- `L`: logout
+- `Q`: quit
+
+## v1 Scope
+
+The public v1 supports:
+
+- current student status read/write
+- today's schoollife summary
+- OAuth PKCE login/logout
+
+It intentionally does not expose routine editing, teacher/admin tools, browser session cookies, remember tokens, or `/api/mcp/state`.
+
+## Server Notes
+
+The server seeds a dedicated public OAuth client:
+
+- client id: `dimicheck-tui-public`
+- redirect URI ports: `45831` through `45835`
+- scopes: `openid basic student_info status.read status.write`
+
+Server deployments should happen from the repository root. This package is intentionally separate so the public TUI release does not include Flask, database, or Google Sheets dependencies.

dimicheck_tui-0.1.0/README.md

@@ -0,0 +1,82 @@
+# DimiCheck TUI
+
+DimiCheck TUI is a terminal dashboard for DimiCheck students. It uses the public OAuth PKCE flow and calls only the student app API surface for v1.
+
+## Install
+
+Use `pipx` for the public install path:
+
+```bash
+pipx install dimicheck-tui
+dimicheck
+```
+
+For local development from this checkout:
+
+```bash
+cd packages/dimicheck-tui
+uv run dimicheck --help
+uv run dimicheck
+```
+
+Set `DIMICHECK_BASE_URL` when testing against a local or staging server:
+
+```bash
+cd packages/dimicheck-tui
+DIMICHECK_BASE_URL=http://127.0.0.1:5000 uv run dimicheck
+```
+
+## Authentication
+
+The TUI never asks for a password in the terminal. On first launch it opens the browser, signs in through DimiCheck OAuth, and stores tokens through the OS credential store.
+
+- macOS: Keychain
+- Windows: Credential Manager
+- Linux: Secret Service compatible keyring
+
+If the OS keyring is unavailable, the app fails closed by default. For controlled environments you can explicitly allow a local token file:
+
+```bash
+dimicheck --allow-plaintext-token
+```
+
+That fallback writes a `0600` permission file. Do not use it on shared machines.
+
+## Commands
+
+```bash
+dimicheck                 # open the TUI dashboard
+dimicheck login           # browser OAuth login
+dimicheck logout          # revoke refresh token and delete local tokens
+dimicheck status get      # print current status
+dimicheck status set toilet
+dimicheck status set etc --reason "상담"
+dimicheck schoollife      # print today's timetable and meal
+```
+
+TUI shortcuts:
+
+- `S`: change status
+- `R`: refresh dashboard
+- `L`: logout
+- `Q`: quit
+
+## v1 Scope
+
+The public v1 supports:
+
+- current student status read/write
+- today's schoollife summary
+- OAuth PKCE login/logout
+
+It intentionally does not expose routine editing, teacher/admin tools, browser session cookies, remember tokens, or `/api/mcp/state`.
+
+## Server Notes
+
+The server seeds a dedicated public OAuth client:
+
+- client id: `dimicheck-tui-public`
+- redirect URI ports: `45831` through `45835`
+- scopes: `openid basic student_info status.read status.write`
+
+Server deployments should happen from the repository root. This package is intentionally separate so the public TUI release does not include Flask, database, or Google Sheets dependencies.

dimicheck_tui-0.1.0/dimicheck_tui/__init__.py

@@ -0,0 +1,5 @@
+"""DimiCheck public terminal app."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

dimicheck_tui-0.1.0/dimicheck_tui/api.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+import time
+from typing import Any
+
+import requests
+
+from .auth import AuthError, OAuthClient
+from .config import TuiConfig
+from .token_store import TokenSet, TokenStore
+
+
+class ApiError(RuntimeError):
+    pass
+
+
+class DimiCheckAPI:
+    def __init__(
+        self,
+        config: TuiConfig,
+        store: TokenStore,
+        *,
+        auth_client: OAuthClient | None = None,
+        session: requests.Session | None = None,
+    ) -> None:
+        self.config = config
+        self.store = store
+        self.session = session or requests.Session()
+        self.auth_client = auth_client or OAuthClient(config, session=self.session)
+
+    def ensure_tokens(self) -> TokenSet:
+        tokens = self.store.load()
+        if tokens is None:
+            self.store.ensure_can_save()
+            tokens = self.auth_client.login()
+            self.store.save(tokens)
+            return tokens
+        if tokens.expires_at <= time.time():
+            tokens = self.auth_client.refresh(tokens.refresh_token)
+            self.store.save(tokens)
+        return tokens
+
+    def logout(self) -> None:
+        tokens = self.store.load()
+        if tokens:
+            self.auth_client.revoke(tokens.refresh_token)
+        self.store.delete()
+
+    def get_status(self) -> dict[str, Any]:
+        return self._request_json("GET", "/api/app/status/me")
+
+    def set_status(self, status_code: str, *, reason: str | None = None) -> dict[str, Any]:
+        payload: dict[str, Any] = {"statusCode": status_code}
+        if reason:
+            payload["reason"] = reason
+        return self._request_json("PUT", "/api/app/status", json=payload)
+
+    def get_schoollife(self) -> dict[str, Any]:
+        return self._request_json("GET", "/api/app/schoollife/today")
+
+    def _request_json(self, method: str, path: str, **kwargs: Any) -> dict[str, Any]:
+        tokens = self.ensure_tokens()
+        response = self.session.request(
+            method,
+            f"{self.config.base_url}{path}",
+            headers={"Authorization": f"Bearer {tokens.access_token}"},
+            timeout=15,
+            **kwargs,
+        )
+        if response.status_code == 401 and tokens.refresh_token:
+            try:
+                tokens = self.auth_client.refresh(tokens.refresh_token)
+            except AuthError as exc:
+                self.store.delete()
+                raise ApiError("로그인이 만료되었습니다. 다시 로그인해 주세요.") from exc
+            self.store.save(tokens)
+            response = self.session.request(
+                method,
+                f"{self.config.base_url}{path}",
+                headers={"Authorization": f"Bearer {tokens.access_token}"},
+                timeout=15,
+                **kwargs,
+            )
+        if response.status_code >= 400:
+            message = response.text
+            try:
+                payload = response.json()
+                message = payload.get("error") or payload.get("message") or message
+            except ValueError:
+                pass
+            raise ApiError(f"HTTP {response.status_code}: {message}")
+        return response.json()

dimicheck_tui-0.1.0/dimicheck_tui/app.py

@@ -0,0 +1,193 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from textual.app import App, ComposeResult
+from textual.containers import Container, Horizontal, Vertical
+from textual.screen import ModalScreen
+from textual.widgets import Button, Footer, Header, Input, Label, RadioButton, RadioSet, Static
+
+from .api import ApiError, DimiCheckAPI
+
+
+STATUS_CHOICES = [
+    ("section", "교실"),
+    ("toilet", "화장실(물)"),
+    ("hallway", "복도"),
+    ("club", "동아리"),
+    ("afterschool", "방과후"),
+    ("project", "프로젝트"),
+    ("early", "조기입실"),
+    ("etc", "기타"),
+    ("absence", "결석(조퇴)"),
+]
+
+
+class StatusModal(ModalScreen[tuple[str, str | None] | None]):
+    CSS = """
+    StatusModal {
+        align: center middle;
+    }
+    #status-dialog {
+        width: 56;
+        padding: 1 2;
+        border: thick $accent;
+        background: $surface;
+    }
+    #reason-input {
+        margin-top: 1;
+    }
+    #status-actions {
+        margin-top: 1;
+        height: auto;
+    }
+    """
+
+    def compose(self) -> ComposeResult:
+        with Vertical(id="status-dialog"):
+            yield Label("상태 변경")
+            with RadioSet(id="status-radio"):
+                for code, label in STATUS_CHOICES:
+                    yield RadioButton(label, id=f"status-{code}")
+            yield Input(placeholder="기타 사유", id="reason-input")
+            with Horizontal(id="status-actions"):
+                yield Button("적용", id="apply", variant="primary")
+                yield Button("취소", id="cancel")
+
+    def on_mount(self) -> None:
+        self.query_one("#status-section", RadioButton).value = True
+
+    def on_button_pressed(self, event: Button.Pressed) -> None:
+        if event.button.id == "cancel":
+            self.dismiss(None)
+            return
+        selected = self.query_one(RadioSet).pressed_button
+        status_code = "section"
+        if selected and selected.id:
+            status_code = selected.id.removeprefix("status-")
+        reason = self.query_one("#reason-input", Input).value.strip() or None
+        self.dismiss((status_code, reason))
+
+
+class DashboardApp(App[None]):
+    TITLE = "DimiCheck"
+    BINDINGS = [
+        ("s", "change_status", "상태 변경"),
+        ("r", "refresh", "새로고침"),
+        ("l", "logout", "로그아웃"),
+        ("q", "quit", "종료"),
+    ]
+    CSS = """
+    Screen {
+        background: #08111f;
+    }
+    #page {
+        padding: 1 2;
+    }
+    .card {
+        border: round #5aa9ff;
+        padding: 1 2;
+        margin-bottom: 1;
+        background: #0f1f35;
+    }
+    #hero {
+        border: tall #77d970;
+    }
+    #status-label {
+        text-style: bold;
+        color: #77d970;
+    }
+    .muted {
+        color: #91a4bd;
+    }
+    #error {
+        color: #ff7b7b;
+    }
+    """
+
+    def __init__(self, api: DimiCheckAPI) -> None:
+        super().__init__()
+        self.api = api
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        with Container(id="page"):
+            yield Static("불러오는 중...", id="hero", classes="card")
+            yield Static("", id="status-card", classes="card")
+            yield Static("", id="schoollife-card", classes="card")
+            yield Static("", id="error")
+        yield Footer()
+
+    def on_mount(self) -> None:
+        self.refresh_dashboard()
+
+    def action_refresh(self) -> None:
+        self.refresh_dashboard()
+
+    def action_change_status(self) -> None:
+        def apply_status(result: tuple[str, str | None] | None) -> None:
+            if result is None:
+                return
+            code, reason = result
+            try:
+                self.api.set_status(code, reason=reason)
+                self.refresh_dashboard()
+            except Exception as exc:  # pylint: disable=broad-except
+                self._show_error(str(exc))
+
+        self.push_screen(StatusModal(), apply_status)
+
+    def action_logout(self) -> None:
+        try:
+            self.api.logout()
+        finally:
+            self.exit()
+
+    def refresh_dashboard(self) -> None:
+        try:
+            status = self.api.get_status()
+            schoollife = self.api.get_schoollife()
+        except (ApiError, Exception) as exc:  # pylint: disable=broad-except
+            self._show_error(str(exc))
+            return
+        self._show_error("")
+        self.query_one("#hero", Static).update(self._render_hero(status))
+        self.query_one("#status-card", Static).update(self._render_status(status))
+        self.query_one("#schoollife-card", Static).update(self._render_schoollife(schoollife))
+
+    def _render_hero(self, status: dict[str, Any]) -> str:
+        today = datetime.now().strftime("%Y년 %m월 %d일")
+        identity = f"{status.get('grade')}학년 {status.get('section')}반 {status.get('number')}번"
+        return f"DimiCheck\n{today} · {identity}"
+
+    def _render_status(self, status: dict[str, Any]) -> str:
+        label = status.get("statusLabel") or status.get("statusCode") or "-"
+        reason = status.get("reason")
+        favorite = status.get("favoriteStatus") or "없음"
+        lines = ["지금 상태", f"[b green]{label}[/]"]
+        if reason:
+            lines.append(f"사유  {reason}")
+        lines.append(f"즐겨찾기  {favorite}")
+        return "\n".join(lines)
+
+    def _render_schoollife(self, payload: dict[str, Any]) -> str:
+        timetable = payload.get("timetable") or {}
+        meal = payload.get("meal") or {}
+        lessons = timetable.get("lessons") or []
+        lines = ["오늘 학교생활"]
+        if lessons:
+            for lesson in lessons[:8]:
+                period = lesson.get("period") or lesson.get("periodName") or "-"
+                subject = lesson.get("subject") or lesson.get("name") or "-"
+                lines.append(f"{period}교시  {subject}")
+        else:
+            lines.append(str(timetable.get("message") or "시간표 정보가 없습니다."))
+        lunch = meal.get("lunch") or "급식 정보가 없습니다."
+        lines.append("")
+        lines.append("급식")
+        lines.append(str(lunch).replace("\n", " · "))
+        return "\n".join(lines)
+
+    def _show_error(self, message: str) -> None:
+        self.query_one("#error", Static).update(message)

dimicheck_tui-0.1.0/dimicheck_tui/auth.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+import base64
+import hashlib
+import secrets
+import threading
+import time
+import webbrowser
+from dataclasses import dataclass
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from typing import Any
+from urllib.parse import parse_qs, urlencode, urlparse
+
+import requests
+
+from .config import CALLBACK_PATH, TuiConfig
+from .token_store import TokenSet
+
+
+class AuthError(RuntimeError):
+    pass
+
+
+@dataclass(frozen=True)
+class CallbackResult:
+    code: str
+    state: str
+
+
+def build_pkce_pair() -> tuple[str, str]:
+    verifier = base64.urlsafe_b64encode(secrets.token_bytes(48)).rstrip(b"=").decode("ascii")
+    digest = hashlib.sha256(verifier.encode("ascii")).digest()
+    challenge = base64.urlsafe_b64encode(digest).rstrip(b"=").decode("ascii")
+    return verifier, challenge
+
+
+def _make_callback_handler(result: dict[str, Any]):
+    class CallbackHandler(BaseHTTPRequestHandler):
+        def do_GET(self) -> None:  # noqa: N802 - stdlib callback name
+            parsed = urlparse(self.path)
+            if parsed.path != CALLBACK_PATH:
+                self.send_response(404)
+                self.end_headers()
+                return
+            params = parse_qs(parsed.query)
+            error = params.get("error", [""])[0]
+            if error:
+                result["error"] = error
+            else:
+                result["code"] = params.get("code", [""])[0]
+                result["state"] = params.get("state", [""])[0]
+            self.send_response(200)
+            self.send_header("Content-Type", "text/html; charset=utf-8")
+            self.end_headers()
+            self.wfile.write(
+                "<!doctype html><meta charset='utf-8'><title>DimiCheck</title>"
+                "<body>로그인이 완료되었습니다. 이 창을 닫고 터미널로 돌아가세요.</body>".encode("utf-8")
+            )
+
+        def log_message(self, _format: str, *_args: Any) -> None:
+            return
+
+    return CallbackHandler
+
+
+class OAuthClient:
+    def __init__(self, config: TuiConfig, *, session: requests.Session | None = None) -> None:
+        self.config = config
+        self.session = session or requests.Session()
+
+    def login(self, *, open_browser: bool = True, timeout_seconds: int = 180) -> TokenSet:
+        server, port, result = self._start_callback_server()
+        verifier, challenge = build_pkce_pair()
+        state = secrets.token_urlsafe(32)
+        authorize_url = self._authorize_url(port=port, state=state, challenge=challenge)
+
+        thread = threading.Thread(target=server.handle_request, daemon=True)
+        thread.start()
+        try:
+            if open_browser and not webbrowser.open(authorize_url):
+                raise AuthError(f"브라우저를 열 수 없습니다. 다음 주소를 직접 여세요: {authorize_url}")
+            deadline = time.monotonic() + timeout_seconds
+            while thread.is_alive() and time.monotonic() < deadline:
+                thread.join(timeout=0.1)
+            if thread.is_alive():
+                raise AuthError("브라우저 로그인 대기 시간이 초과되었습니다.")
+            if result.get("error"):
+                raise AuthError(f"OAuth error: {result['error']}")
+            callback = CallbackResult(code=str(result.get("code") or ""), state=str(result.get("state") or ""))
+            if not callback.code:
+                raise AuthError("OAuth callback did not include an authorization code")
+            if callback.state != state:
+                raise AuthError("OAuth state mismatch")
+            return self.exchange_code(code=callback.code, verifier=verifier, redirect_uri=self.config.redirect_uri(port))
+        finally:
+            server.server_close()
+
+    def exchange_code(self, *, code: str, verifier: str, redirect_uri: str) -> TokenSet:
+        response = self.session.post(
+            f"{self.config.base_url}/oauth/token",
+            data={
+                "grant_type": "authorization_code",
+                "client_id": self.config.client_id,
+                "code": code,
+                "redirect_uri": redirect_uri,
+                "code_verifier": verifier,
+            },
+            timeout=15,
+        )
+        if response.status_code != 200:
+            raise AuthError(f"토큰 교환 실패: HTTP {response.status_code}")
+        return TokenSet.from_oauth_response(response.json(), now=time.time())
+
+    def refresh(self, refresh_token: str) -> TokenSet:
+        response = self.session.post(
+            f"{self.config.base_url}/oauth/token",
+            data={
+                "grant_type": "refresh_token",
+                "client_id": self.config.client_id,
+                "refresh_token": refresh_token,
+            },
+            timeout=15,
+        )
+        if response.status_code != 200:
+            raise AuthError(f"토큰 갱신 실패: HTTP {response.status_code}")
+        return TokenSet.from_oauth_response(response.json(), now=time.time())
+
+    def revoke(self, token: str) -> None:
+        self.session.post(
+            f"{self.config.base_url}/oauth/revoke",
+            data={"client_id": self.config.client_id, "token": token},
+            timeout=15,
+        )
+
+    def _authorize_url(self, *, port: int, state: str, challenge: str) -> str:
+        query = urlencode(
+            {
+                "response_type": "code",
+                "client_id": self.config.client_id,
+                "redirect_uri": self.config.redirect_uri(port),
+                "scope": self.config.scopes,
+                "state": state,
+                "code_challenge": challenge,
+                "code_challenge_method": "S256",
+            }
+        )
+        return f"{self.config.base_url}/oauth/authorize?{query}"
+
+    def _start_callback_server(self) -> tuple[HTTPServer, int, dict[str, Any]]:
+        result: dict[str, Any] = {}
+        handler = _make_callback_handler(result)
+        last_error: OSError | None = None
+        for port in self.config.redirect_ports:
+            try:
+                return HTTPServer(("127.0.0.1", port), handler), port, result
+            except OSError as exc:
+                last_error = exc
+        raise AuthError("사용 가능한 OAuth callback 포트를 찾지 못했습니다.") from last_error

dimicheck_tui-0.1.0/dimicheck_tui/cli.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from . import __version__
+from .api import ApiError, DimiCheckAPI
+from .config import TuiConfig
+from .token_store import TokenStore, TokenStorageError
+
+
+def build_api(*, allow_plaintext_token: bool) -> DimiCheckAPI:
+    config = TuiConfig.from_env()
+    store = TokenStore(account=config.base_url, allow_plaintext_file=allow_plaintext_token)
+    return DimiCheckAPI(config, store)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="dimicheck", description="DimiCheck terminal dashboard")
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    parser.add_argument("--allow-plaintext-token", action="store_true", help="OS keyring 실패 시 권한 제한 파일 저장 허용")
+    subparsers = parser.add_subparsers(dest="command")
+
+    subparsers.add_parser("login", help="브라우저 OAuth 로그인")
+    subparsers.add_parser("logout", help="토큰 폐기 후 로그아웃")
+    subparsers.add_parser("schoollife", help="오늘 학교생활 출력")
+    status_parser = subparsers.add_parser("status", help="내 상태 조회/변경")
+    status_subparsers = status_parser.add_subparsers(dest="status_command")
+    status_subparsers.add_parser("get", help="현재 상태 조회")
+    set_parser = status_subparsers.add_parser("set", help="상태 변경")
+    set_parser.add_argument("status_code")
+    set_parser.add_argument("--reason")
+
+    args = parser.parse_args(argv)
+    api = build_api(allow_plaintext_token=args.allow_plaintext_token)
+
+    try:
+        if args.command == "login":
+            api.ensure_tokens()
+            print("로그인 완료")
+            return 0
+        if args.command == "logout":
+            api.logout()
+            print("로그아웃 완료")
+            return 0
+        if args.command == "schoollife":
+            print(format_schoollife(api.get_schoollife()))
+            return 0
+        if args.command == "status":
+            if args.status_command == "set":
+                payload = api.set_status(args.status_code, reason=args.reason)
+                print(format_status(payload.get("status") or payload))
+                return 0
+            print(format_status(api.get_status()))
+            return 0
+        from .app import DashboardApp
+
+        DashboardApp(api).run()
+        return 0
+    except (ApiError, TokenStorageError, Exception) as exc:  # pylint: disable=broad-except
+        print(f"dimicheck: {exc}", file=sys.stderr)
+        return 1
+
+
+def format_status(payload: dict) -> str:
+    label = payload.get("statusLabel") or payload.get("statusCode") or "-"
+    reason = payload.get("reason")
+    identity = f"{payload.get('grade')}학년 {payload.get('section')}반 {payload.get('number')}번"
+    lines = [f"{identity}", f"상태: {label}"]
+    if reason:
+        lines.append(f"사유: {reason}")
+    return "\n".join(lines)
+
+
+def format_schoollife(payload: dict) -> str:
+    timetable = payload.get("timetable") or {}
+    meal = payload.get("meal") or {}
+    lines = [f"오늘 학교생활 ({payload.get('date') or '-'})"]
+    lessons = timetable.get("lessons") or []
+    if lessons:
+        for lesson in lessons:
+            period = lesson.get("period") or lesson.get("periodName") or "-"
+            subject = lesson.get("subject") or lesson.get("name") or "-"
+            lines.append(f"{period}교시  {subject}")
+    else:
+        lines.append(str(timetable.get("message") or "시간표 정보가 없습니다."))
+    lines.append("")
+    lines.append("급식")
+    lines.append(str(meal.get("lunch") or "급식 정보가 없습니다.").replace("\n", " · "))
+    errors = payload.get("errors") or {}
+    if errors:
+        lines.append("")
+        lines.append(f"일부 정보를 불러오지 못했습니다: {json.dumps(errors, ensure_ascii=False)}")
+    return "\n".join(lines)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

dimicheck_tui-0.1.0/dimicheck_tui/config.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+
+CLIENT_ID = "dimicheck-tui-public"
+SCOPES = "openid basic student_info status.read status.write"
+REDIRECT_PORTS = (45831, 45832, 45833, 45834, 45835)
+CALLBACK_PATH = "/oauth-callback"
+DEFAULT_BASE_URL = "https://dimicheck.com"
+
+
+@dataclass(frozen=True)
+class TuiConfig:
+    base_url: str
+    client_id: str = CLIENT_ID
+    scopes: str = SCOPES
+    redirect_ports: tuple[int, ...] = REDIRECT_PORTS
+
+    @classmethod
+    def from_env(cls) -> "TuiConfig":
+        return cls(base_url=os.getenv("DIMICHECK_BASE_URL", DEFAULT_BASE_URL).rstrip("/"))
+
+    def redirect_uri(self, port: int) -> str:
+        return f"http://127.0.0.1:{port}{CALLBACK_PATH}"

dimicheck_tui-0.1.0/dimicheck_tui/token_store.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+import json
+import os
+import stat
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any
+
+
+SERVICE_NAME = "dimicheck-tui"
+
+
+class TokenStorageError(RuntimeError):
+    """Raised when tokens cannot be stored safely."""
+
+
+@dataclass
+class TokenSet:
+    access_token: str
+    refresh_token: str
+    expires_at: float
+    scope: str = ""
+    token_type: str = "Bearer"
+
+    @classmethod
+    def from_oauth_response(cls, payload: dict[str, Any], *, now: float) -> "TokenSet":
+        access_token = str(payload.get("access_token") or "")
+        refresh_token = str(payload.get("refresh_token") or "")
+        if not access_token or not refresh_token:
+            raise ValueError("OAuth response did not include access_token and refresh_token")
+        expires_in = int(payload.get("expires_in") or 3600)
+        return cls(
+            access_token=access_token,
+            refresh_token=refresh_token,
+            expires_at=now + max(expires_in - 30, 1),
+            scope=str(payload.get("scope") or ""),
+            token_type=str(payload.get("token_type") or "Bearer"),
+        )
+
+    @classmethod
+    def from_json(cls, raw: str) -> "TokenSet":
+        payload = json.loads(raw)
+        return cls(
+            access_token=str(payload["access_token"]),
+            refresh_token=str(payload["refresh_token"]),
+            expires_at=float(payload["expires_at"]),
+            scope=str(payload.get("scope") or ""),
+            token_type=str(payload.get("token_type") or "Bearer"),
+        )
+
+    def to_json(self) -> str:
+        return json.dumps(asdict(self), ensure_ascii=False)
+
+
+def default_token_file() -> Path:
+    override = os.getenv("DIMICHECK_TOKEN_FILE")
+    if override:
+        return Path(override).expanduser()
+    if os.name == "nt":
+        base = Path(os.getenv("APPDATA") or Path.home() / "AppData" / "Roaming")
+        return base / "DimiCheck" / "tokens.json"
+    return Path(os.getenv("XDG_CONFIG_HOME", Path.home() / ".config")) / "dimicheck" / "tokens.json"
+
+
+class TokenStore:
+    def __init__(
+        self,
+        *,
+        account: str,
+        allow_plaintext_file: bool = False,
+        token_file: Path | None = None,
+        keyring_module: Any | None = None,
+    ) -> None:
+        self.account = account
+        self.allow_plaintext_file = allow_plaintext_file
+        self.token_file = token_file or default_token_file()
+        self._keyring = keyring_module
+
+    def load(self) -> TokenSet | None:
+        try:
+            raw = self._keyring_get()
+        except Exception:
+            raw = None
+        if raw:
+            return TokenSet.from_json(raw)
+        if not self.allow_plaintext_file or not self.token_file.exists():
+            return None
+        self._assert_private_file(self.token_file)
+        return TokenSet.from_json(self.token_file.read_text(encoding="utf-8"))
+
+    def ensure_can_save(self) -> None:
+        try:
+            self._keyring_set("__dimicheck_tui_probe__")
+            self._keyring_delete()
+            return
+        except Exception as exc:
+            if not self.allow_plaintext_file:
+                raise TokenStorageError(
+                    "OS keyring에 토큰을 저장할 수 없습니다. Keychain/Credential Manager/Secret Service를 설정하거나 "
+                    "--allow-plaintext-token 옵션을 명시하세요."
+                ) from exc
+        self.token_file.parent.mkdir(parents=True, exist_ok=True)
+        if self.token_file.exists():
+            self._assert_private_file(self.token_file)
+        else:
+            fd = os.open(self.token_file, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+            os.close(fd)
+            self.token_file.unlink()
+
+    def save(self, tokens: TokenSet) -> None:
+        raw = tokens.to_json()
+        try:
+            self._keyring_set(raw)
+            return
+        except Exception as exc:
+            if not self.allow_plaintext_file:
+                raise TokenStorageError(
+                    "OS keyring에 토큰을 저장할 수 없습니다. Keychain/Credential Manager/Secret Service를 설정하거나 "
+                    "--allow-plaintext-token 옵션을 명시하세요."
+                ) from exc
+        self.token_file.parent.mkdir(parents=True, exist_ok=True)
+        fd = os.open(self.token_file, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            handle.write(raw)
+        os.chmod(self.token_file, 0o600)
+
+    def delete(self) -> None:
+        try:
+            self._keyring_delete()
+        except Exception:
+            pass
+        if self.token_file.exists():
+            self.token_file.unlink()
+
+    def _keyring_module(self) -> Any:
+        if self._keyring is not None:
+            return self._keyring
+        import keyring  # type: ignore
+
+        return keyring
+
+    def _keyring_get(self) -> str | None:
+        return self._keyring_module().get_password(SERVICE_NAME, self.account)
+
+    def _keyring_set(self, raw: str) -> None:
+        self._keyring_module().set_password(SERVICE_NAME, self.account, raw)
+
+    def _keyring_delete(self) -> None:
+        self._keyring_module().delete_password(SERVICE_NAME, self.account)
+
+    @staticmethod
+    def _assert_private_file(path: Path) -> None:
+        if os.name == "nt":
+            return
+        mode = stat.S_IMODE(path.stat().st_mode)
+        if mode & (stat.S_IRWXG | stat.S_IRWXO):
+            raise TokenStorageError(f"{path} 권한이 너무 넓습니다. chmod 600 후 다시 실행하세요.")

dimicheck_tui-0.1.0/dimicheck_tui.egg-info/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: dimicheck-tui
+Version: 0.1.0
+Summary: DimiCheck terminal dashboard
+Author: DimiCheck
+Project-URL: Homepage, https://dimicheck.com
+Project-URL: Repository, https://github.com/hjun1052/dimicheck4
+Keywords: dimicheck,tui,textual,oauth,school
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Education
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: keyring>=25.0.0
+Requires-Dist: requests==2.31.0
+Requires-Dist: textual>=0.89.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+
+# DimiCheck TUI
+
+DimiCheck TUI is a terminal dashboard for DimiCheck students. It uses the public OAuth PKCE flow and calls only the student app API surface for v1.
+
+## Install
+
+Use `pipx` for the public install path:
+
+```bash
+pipx install dimicheck-tui
+dimicheck
+```
+
+For local development from this checkout:
+
+```bash
+cd packages/dimicheck-tui
+uv run dimicheck --help
+uv run dimicheck
+```
+
+Set `DIMICHECK_BASE_URL` when testing against a local or staging server:
+
+```bash
+cd packages/dimicheck-tui
+DIMICHECK_BASE_URL=http://127.0.0.1:5000 uv run dimicheck
+```
+
+## Authentication
+
+The TUI never asks for a password in the terminal. On first launch it opens the browser, signs in through DimiCheck OAuth, and stores tokens through the OS credential store.
+
+- macOS: Keychain
+- Windows: Credential Manager
+- Linux: Secret Service compatible keyring
+
+If the OS keyring is unavailable, the app fails closed by default. For controlled environments you can explicitly allow a local token file:
+
+```bash
+dimicheck --allow-plaintext-token
+```
+
+That fallback writes a `0600` permission file. Do not use it on shared machines.
+
+## Commands
+
+```bash
+dimicheck                 # open the TUI dashboard
+dimicheck login           # browser OAuth login
+dimicheck logout          # revoke refresh token and delete local tokens
+dimicheck status get      # print current status
+dimicheck status set toilet
+dimicheck status set etc --reason "상담"
+dimicheck schoollife      # print today's timetable and meal
+```
+
+TUI shortcuts:
+
+- `S`: change status
+- `R`: refresh dashboard
+- `L`: logout
+- `Q`: quit
+
+## v1 Scope
+
+The public v1 supports:
+
+- current student status read/write
+- today's schoollife summary
+- OAuth PKCE login/logout
+
+It intentionally does not expose routine editing, teacher/admin tools, browser session cookies, remember tokens, or `/api/mcp/state`.
+
+## Server Notes
+
+The server seeds a dedicated public OAuth client:
+
+- client id: `dimicheck-tui-public`
+- redirect URI ports: `45831` through `45835`
+- scopes: `openid basic student_info status.read status.write`
+
+Server deployments should happen from the repository root. This package is intentionally separate so the public TUI release does not include Flask, database, or Google Sheets dependencies.

dimicheck_tui-0.1.0/dimicheck_tui.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+README.md
+pyproject.toml
+dimicheck_tui/__init__.py
+dimicheck_tui/api.py
+dimicheck_tui/app.py
+dimicheck_tui/auth.py
+dimicheck_tui/cli.py
+dimicheck_tui/config.py
+dimicheck_tui/token_store.py
+dimicheck_tui.egg-info/PKG-INFO
+dimicheck_tui.egg-info/SOURCES.txt
+dimicheck_tui.egg-info/dependency_links.txt
+dimicheck_tui.egg-info/entry_points.txt
+dimicheck_tui.egg-info/requires.txt
+dimicheck_tui.egg-info/top_level.txt
+tests/test_dimicheck_tui.py

dimicheck_tui-0.1.0/dimicheck_tui.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

dimicheck_tui-0.1.0/dimicheck_tui.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+dimicheck = dimicheck_tui.cli:main

dimicheck_tui-0.1.0/dimicheck_tui.egg-info/requires.txt

@@ -0,0 +1,6 @@
+keyring>=25.0.0
+requests==2.31.0
+textual>=0.89.0
+
+[dev]
+pytest>=8.0.0

dimicheck_tui-0.1.0/dimicheck_tui.egg-info/top_level.txt

@@ -0,0 +1 @@
+dimicheck_tui

dimicheck_tui-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[project]
+name = "dimicheck-tui"
+version = "0.1.0"
+description = "DimiCheck terminal dashboard"
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [
+    { name = "DimiCheck" },
+]
+keywords = ["dimicheck", "tui", "textual", "oauth", "school"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Education",
+]
+dependencies = [
+    "keyring>=25.0.0",
+    "requests==2.31.0",
+    "textual>=0.89.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+]
+
+[project.scripts]
+dimicheck = "dimicheck_tui.cli:main"
+
+[project.urls]
+Homepage = "https://dimicheck.com"
+Repository = "https://github.com/hjun1052/dimicheck4"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+packages = ["dimicheck_tui"]

dimicheck_tui-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

dimicheck_tui-0.1.0/tests/test_dimicheck_tui.py

@@ -0,0 +1,205 @@
+import json
+from pathlib import Path
+
+import pytest
+
+from dimicheck_tui.api import ApiError, DimiCheckAPI
+from dimicheck_tui.cli import format_schoollife, format_status
+from dimicheck_tui.config import TuiConfig
+from dimicheck_tui.token_store import TokenSet, TokenStorageError, TokenStore
+
+
+class FakeKeyring:
+    def __init__(self, *, fail: bool = False):
+        self.fail = fail
+        self.value = None
+
+    def get_password(self, _service, _account):
+        if self.fail:
+            raise RuntimeError("keyring unavailable")
+        return self.value
+
+    def set_password(self, _service, _account, value):
+        if self.fail:
+            raise RuntimeError("keyring unavailable")
+        self.value = value
+
+    def delete_password(self, _service, _account):
+        if self.fail:
+            raise RuntimeError("keyring unavailable")
+        self.value = None
+
+
+def _tokens(access="access", refresh="refresh", expires_at=9999999999):
+    return TokenSet(access_token=access, refresh_token=refresh, expires_at=expires_at, scope="status.read")
+
+
+def test_token_store_uses_keyring():
+    keyring = FakeKeyring()
+    store = TokenStore(account="https://dimicheck.com", keyring_module=keyring)
+    tokens = _tokens()
+
+    store.save(tokens)
+
+    loaded = store.load()
+    assert loaded == tokens
+
+    store.delete()
+    assert store.load() is None
+
+
+def test_token_store_requires_explicit_plaintext_fallback(tmp_path):
+    store = TokenStore(
+        account="https://dimicheck.com",
+        keyring_module=FakeKeyring(fail=True),
+        token_file=tmp_path / "tokens.json",
+    )
+
+    with pytest.raises(TokenStorageError):
+        store.save(_tokens())
+
+
+def test_token_store_preflight_requires_explicit_plaintext_fallback(tmp_path):
+    store = TokenStore(
+        account="https://dimicheck.com",
+        keyring_module=FakeKeyring(fail=True),
+        token_file=tmp_path / "tokens.json",
+    )
+
+    with pytest.raises(TokenStorageError):
+        store.ensure_can_save()
+
+
+def test_token_store_plaintext_fallback_writes_private_file(tmp_path):
+    token_file = tmp_path / "tokens.json"
+    store = TokenStore(
+        account="https://dimicheck.com",
+        allow_plaintext_file=True,
+        keyring_module=FakeKeyring(fail=True),
+        token_file=token_file,
+    )
+
+    store.save(_tokens())
+
+    assert token_file.exists()
+    assert oct(token_file.stat().st_mode & 0o777) == "0o600"
+    assert json.loads(token_file.read_text(encoding="utf-8"))["access_token"] == "access"
+    assert store.load().refresh_token == "refresh"
+
+
+def test_token_store_plaintext_preflight_does_not_leave_probe_file(tmp_path):
+    token_file = tmp_path / "tokens.json"
+    store = TokenStore(
+        account="https://dimicheck.com",
+        allow_plaintext_file=True,
+        keyring_module=FakeKeyring(fail=True),
+        token_file=token_file,
+    )
+
+    store.ensure_can_save()
+
+    assert not token_file.exists()
+
+
+def test_cli_formatters_are_human_readable():
+    assert format_status({
+        "grade": 2,
+        "section": 4,
+        "number": 7,
+        "statusLabel": "화장실(물)",
+    }) == "2학년 4반 7번\n상태: 화장실(물)"
+
+    schoollife = format_schoollife({
+        "date": "2026-06-14",
+        "timetable": {"lessons": [{"period": 1, "subject": "국어"}]},
+        "meal": {"lunch": "김치볶음밥\n요구르트"},
+        "errors": {},
+    })
+    assert "오늘 학교생활 (2026-06-14)" in schoollife
+    assert "1교시  국어" in schoollife
+    assert "김치볶음밥 · 요구르트" in schoollife
+
+
+class FakeStore:
+    def __init__(self, tokens):
+        self.tokens = tokens
+        self.deleted = False
+
+    def load(self):
+        return self.tokens
+
+    def save(self, tokens):
+        self.tokens = tokens
+
+    def delete(self):
+        self.deleted = True
+        self.tokens = None
+
+
+class FakeAuth:
+    def __init__(self, refreshed=None, fail=False):
+        self.refreshed = refreshed
+        self.fail = fail
+
+    def login(self):
+        return self.refreshed
+
+    def refresh(self, _refresh_token):
+        if self.fail:
+            from dimicheck_tui.auth import AuthError
+
+            raise AuthError("refresh failed")
+        return self.refreshed
+
+    def revoke(self, _token):
+        return None
+
+
+class FakeResponse:
+    def __init__(self, status_code, payload):
+        self.status_code = status_code
+        self.payload = payload
+        self.text = json.dumps(payload)
+
+    def json(self):
+        return self.payload
+
+
+class FakeSession:
+    def __init__(self, responses):
+        self.responses = list(responses)
+        self.requests = []
+
+    def request(self, method, url, **kwargs):
+        self.requests.append((method, url, kwargs))
+        return self.responses.pop(0)
+
+
+def test_api_refreshes_once_after_unauthorized_response():
+    config = TuiConfig(base_url="https://dimicheck.test")
+    store = FakeStore(_tokens(access="old", refresh="refresh", expires_at=9999999999))
+    refreshed = _tokens(access="new", refresh="new-refresh", expires_at=9999999999)
+    session = FakeSession([
+        FakeResponse(401, {"error": "invalid_token"}),
+        FakeResponse(200, {"statusCode": "section"}),
+    ])
+    api = DimiCheckAPI(config, store, auth_client=FakeAuth(refreshed=refreshed), session=session)
+
+    payload = api.get_status()
+
+    assert payload == {"statusCode": "section"}
+    assert store.tokens.access_token == "new"
+    assert session.requests[0][2]["headers"]["Authorization"] == "Bearer old"
+    assert session.requests[1][2]["headers"]["Authorization"] == "Bearer new"
+
+
+def test_api_deletes_tokens_when_refresh_fails():
+    config = TuiConfig(base_url="https://dimicheck.test")
+    store = FakeStore(_tokens(access="old", refresh="refresh", expires_at=9999999999))
+    session = FakeSession([FakeResponse(401, {"error": "invalid_token"})])
+    api = DimiCheckAPI(config, store, auth_client=FakeAuth(fail=True), session=session)
+
+    with pytest.raises(ApiError):
+        api.get_status()
+
+    assert store.deleted is True