kwcli 1.0.0__tar.gz → 1.0.2__tar.gz

{kwcli-1.0.0 → kwcli-1.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: kwcli
-Version: 1.0.0
+Version: 1.0.2
 Summary: Kiwoom OpenAPI toolkit
 License-File: LICENSE.md
 Requires-Python: >=3.13

{kwcli-1.0.0 → kwcli-1.0.2}/kiwoom/core/auth.py

@@ -328,8 +328,19 @@ class KiwoomAuth:
 
     @staticmethod
     def _credential_fingerprint(credentials: CredentialSet) -> str:
-        raw = f"{credentials.appkey}:{credentials.secretkey}".encode("utf-8")
-        return hashlib.sha256(raw).hexdigest()
+        return credential_fingerprint(credentials)
+
+
+def credential_fingerprint(credentials: CredentialSet) -> str:
+    """Non-reversible identity of an appkey/secret pair.
+
+    Stored beside a cached token so a token issued for one key pair is never
+    reused after the credentials change (`_load_valid_token`), and used by the
+    runtime to seed a pre-issued token (`KIWOOM_ACCESS_TOKEN`) with the
+    fingerprint the auth object will check it against.
+    """
+    raw = f"{credentials.appkey}:{credentials.secretkey}".encode("utf-8")
+    return hashlib.sha256(raw).hexdigest()
 
 
 def _safe_json(response: requests.Response) -> dict:

{kwcli-1.0.0 → kwcli-1.0.2}/kiwoom/core/client.py

@@ -6,10 +6,11 @@ import requests
 
 from kiwoom.core.auth import KiwoomAuth, get_base_url
 from kiwoom.core.errors import (
-    AUTH_RETRY_RETURN_CODES,
     AuthenticationError,
     HTTPRequestError,
+    auth_retry_code,
     normalize_return_code,
+    raise_for_error_code,
 )
 from kiwoom.core.types import Continuation, KiwoomResponse
 
@@ -81,7 +82,9 @@ class KiwoomClient:
             }
 
         return_code = normalize_return_code(data.get("return_code"))
-        if return_code in AUTH_RETRY_RETURN_CODES and retry_on_auth_failure:
+        # 키움은 만료/무효 토큰을 top-level return_code=8005로도, return_code=3 +
+        # return_msg "[8005:...]"로도 돌려준다 — 어느 쪽이든 한 번 재발급 후 재시도.
+        if retry_on_auth_failure and auth_retry_code(return_code, data.get("return_msg")) is not None:
             self.auth.recover_from_auth_failure()
             return self.request(
                 api_id=resolved_api_id,
@@ -97,6 +100,14 @@ class KiwoomClient:
             if return_code not in (None, 0):
                 message = f"{message} (return_code={data['return_code']})"
             raise HTTPRequestError(response.status_code, message)
+
+        # 키움은 업무 오류도 HTTP 200으로 내려보내고 실패 여부는 본문 return_code에만 담는다.
+        if return_code not in (None, 0):
+            raise_for_error_code(
+                return_code,
+                str(data.get("return_msg") or "API 요청에 실패했습니다."),
+            )
+
         return _build_response(data, response.headers)
 
     def fetch_page(

{kwcli-1.0.0 → kwcli-1.0.2}/kiwoom/core/errors.py

@@ -1,9 +1,31 @@
+import re
 from pathlib import Path
 
 # Kiwoom auth-expiry return codes that warrant a one-shot credential
 # recovery + retry (shared by the REST client and the WebSocket client).
 AUTH_RETRY_RETURN_CODES = frozenset({8005, 8031, 8103})
 
+# Kiwoom often reports a generic top-level ``return_code`` (e.g. 3 = "인증에
+# 실패했습니다") and puts the specific code inside ``return_msg`` as
+# ``[8005:Token이 유효하지 않습니다]`` (REST) or ``CODE=8005`` (WebSocket).
+_EMBEDDED_CODE_RE = re.compile(r"\[(\d{3,5}):|CODE=(\d{3,5})")
+
+
+def embedded_return_code(return_msg: object) -> int | None:
+    """Return the specific code embedded in a Kiwoom ``return_msg``, if any."""
+    match = _EMBEDDED_CODE_RE.search(str(return_msg or ""))
+    if match is None:
+        return None
+    return int(match.group(1) or match.group(2))
+
+
+def auth_retry_code(return_code: int | None, return_msg: object) -> int | None:
+    """The auth-expiry code (top-level or embedded) that warrants recovery, else None."""
+    if return_code in AUTH_RETRY_RETURN_CODES:
+        return return_code
+    embedded = embedded_return_code(return_msg)
+    return embedded if embedded in AUTH_RETRY_RETURN_CODES else None
+
 
 def normalize_return_code(value: object) -> int | None:
     """Normalize a Kiwoom ``return_code`` payload value.
@@ -137,6 +159,13 @@ class DeviceAuthenticationError(AuthenticationError):
         self.return_msg = return_msg
 
 
+class DemoUnsupportedError(APIError):
+    """Raised when the API exists but is not served in demo (모의투자) mode."""
+
+    def __init__(self, return_code: int, return_msg: str):
+        super().__init__(return_code, f"모의투자에서 지원하지 않는 API입니다. ({return_msg})")
+
+
 INPUT_VALIDATION_CODES = {
     1501,
     1504,
@@ -151,15 +180,35 @@ INPUT_VALIDATION_CODES = {
     1687,
     8020,
 }
-RATE_LIMIT_CODES = {1700}
-SYMBOL_NOT_FOUND_CODES = {1901, 1902}
+RATE_LIMIT_CODES = {1700, 1701, 1702}
+SYMBOL_NOT_FOUND_CODES = {1901, 1902, 1903}
 INVALID_CREDENTIAL_CODES = {8001, 8002, 8011, 8012}
 INVALID_TOKEN_CODES = {8003, 8005, 8006, 8009, 8015, 8016}
 MODE_MISMATCH_CODES = {8030, 8031}
 DEVICE_AUTH_CODES = {8010, 8040, 8050, 8103}
+DEMO_UNSUPPORTED_CODES = {8104}
+
+
+_CLASSIFIED_CODES = (
+    INPUT_VALIDATION_CODES
+    | RATE_LIMIT_CODES
+    | SYMBOL_NOT_FOUND_CODES
+    | INVALID_CREDENTIAL_CODES
+    | INVALID_TOKEN_CODES
+    | MODE_MISMATCH_CODES
+    | DEVICE_AUTH_CODES
+    | DEMO_UNSUPPORTED_CODES
+)
 
 
 def raise_for_error_code(return_code: int, return_msg: str) -> None:
+    # A generic top-level code (3, 5, ...) with a specific code embedded in the
+    # message is classified by the embedded code, so callers get the same
+    # error class either way; the message keeps Kiwoom's original text.
+    if return_code not in _CLASSIFIED_CODES:
+        embedded = embedded_return_code(return_msg)
+        if embedded in _CLASSIFIED_CODES:
+            return_code = embedded
     if return_code in INPUT_VALIDATION_CODES:
         raise InputValidationError(return_code, return_msg)
     if return_code in RATE_LIMIT_CODES:
@@ -174,4 +223,8 @@ def raise_for_error_code(return_code: int, return_msg: str) -> None:
         raise ModeMismatchError(return_code, return_msg)
     if return_code in DEVICE_AUTH_CODES:
         raise DeviceAuthenticationError(return_code, return_msg)
+    if return_code in DEMO_UNSUPPORTED_CODES:
+        raise DemoUnsupportedError(return_code, return_msg)
+    # 1999(예기치 못한 오류)·8200(법인 미지원)처럼 분류해도 대응이 달라지지 않는 코드는
+    # 원문 메시지를 그대로 노출하는 APIError로 남긴다.
     raise APIError(return_code, return_msg)

{kwcli-1.0.0 → kwcli-1.0.2}/kiwoom/core/runtime.py

@@ -1,18 +1,30 @@
 from dataclasses import dataclass
+from datetime import UTC, datetime
 from typing import Literal
 
-from kiwoom.core.auth import KiwoomAuth, get_base_url as _auth_base_url, get_ws_base_url as _auth_ws_base_url
+from kiwoom.core.auth import (
+    KiwoomAuth,
+    credential_fingerprint,
+    get_base_url as _auth_base_url,
+    get_ws_base_url as _auth_ws_base_url,
+)
 from kiwoom.core.client import KiwoomClient
 from kiwoom.core.errors import ModeNotConfiguredError
 from kiwoom.core.profiles import AuthProfile, get_current_profile, get_profile
 from kiwoom.core.secrets import SecretProvider, default_secret_provider
-from kiwoom.core.settings import get_mode_from_env, get_profile_from_env
-from kiwoom.core.token_store import FileTokenStore, MemoryTokenStore
-from kiwoom.core.types import Mode, normalize_mode
+from kiwoom.core.settings import (
+    ACCESS_TOKEN_ENV_VAR,
+    TOKEN_STORE_ENV_VAR,
+    PreissuedToken,
+    get_mode_from_env,
+    get_preissued_token_from_env,
+    get_profile_from_env,
+    get_token_store_kind_from_env,
+)
+from kiwoom.core.token_store import FileTokenStore, MemoryTokenStore, TokenRecord
+from kiwoom.core.types import Mode, TokenStoreKind, normalize_mode
 from kiwoom.core.ws_client import KiwoomWebSocketClient
 
-TokenStoreKind = Literal["file", "memory"]
-
 SelectionSource = Literal[
     "--profile",
     "KIWOOM_PROFILE",
@@ -102,15 +114,28 @@ def get_auth(
     *,
     profile: str | None = None,
     secret_provider: SecretProvider | None = None,
-    token_store_kind: TokenStoreKind = "file",
+    token_store_kind: TokenStoreKind | None = None,
 ) -> KiwoomAuth:
+    """Build the auth object for the selected target.
+
+    `token_store_kind=None` (the default) resolves via `resolve_token_store_kind`,
+    i.e. `KIWOOM_TOKEN_STORE` when set, else the on-disk file cache. Pass an
+    explicit kind to override the environment (setup does this for its
+    throwaway validation auth).
+    """
     selection = _resolve_selection(mode=mode, profile=profile)
     profile_alias = selection.profile.alias if selection.profile else None
+    provider = secret_provider or default_secret_provider(profile=profile_alias)
     return KiwoomAuth(
         mode=selection.mode,
         profile=profile_alias,
-        secret_provider=secret_provider or default_secret_provider(profile=profile_alias),
-        token_store=_build_token_store(token_store_kind),
+        secret_provider=provider,
+        token_store=_build_token_store(
+            resolve_token_store_kind(token_store_kind),
+            mode=selection.mode,
+            profile=profile_alias,
+            secret_provider=provider,
+        ),
     )
 
 
@@ -145,9 +170,59 @@ def get_ws_base_url(mode: str | None = None, *, profile: str | None = None) -> s
     return _auth_ws_base_url(resolve_mode(mode, profile=profile))
 
 
-def _build_token_store(token_store_kind: TokenStoreKind):
+def resolve_token_store_kind(token_store_kind: TokenStoreKind | None = None) -> TokenStoreKind:
+    """Explicit argument > `KIWOOM_TOKEN_STORE` > `file`."""
+    if token_store_kind is not None:
+        return token_store_kind
+    return get_token_store_kind_from_env() or "file"
+
+
+def _build_token_store(
+    token_store_kind: TokenStoreKind,
+    *,
+    mode: Mode,
+    profile: str | None,
+    secret_provider: SecretProvider,
+):
+    preissued = get_preissued_token_from_env()
     if token_store_kind == "file":
+        if preissued is not None:
+            raise ValueError(f"{ACCESS_TOKEN_ENV_VAR} requires {TOKEN_STORE_ENV_VAR}=memory.")
         return FileTokenStore()
     if token_store_kind == "memory":
-        return MemoryTokenStore()
+        store = MemoryTokenStore()
+        if preissued is not None:
+            _seed_preissued_token(store, preissued, mode=mode, profile=profile, secret_provider=secret_provider)
+        return store
     raise ValueError(f"unsupported token_store_kind: {token_store_kind}")
+
+
+def _seed_preissued_token(
+    store: MemoryTokenStore,
+    preissued: PreissuedToken,
+    *,
+    mode: Mode,
+    profile: str | None,
+    secret_provider: SecretProvider,
+) -> None:
+    """Place a token handed in via env into the in-memory store.
+
+    The record carries the fingerprint of the credentials this process resolves,
+    so `KiwoomAuth._load_valid_token` accepts it exactly as it would a token it
+    issued itself; if the credentials are missing the token is not seeded and the
+    usual credentials error surfaces on first use.
+    """
+    credentials = secret_provider.get_credentials(mode)
+    if credentials is None:
+        return
+    store.save(
+        TokenRecord(
+            access_token=preissued.access_token,
+            token_type="bearer",
+            expires_at=preissued.expires_at.astimezone(UTC),
+            mode=mode,
+            profile=profile,
+            credential_fingerprint=credential_fingerprint(credentials),
+            saved_at=datetime.now(UTC),
+        )
+    )

{kwcli-1.0.0 → kwcli-1.0.2}/kiwoom/core/secrets.py

@@ -25,6 +25,29 @@ class SecretProvider(Protocol):
     def clear_credentials(self, mode: Mode) -> bool: ...
 
 
+class StaticSecretProvider:
+    """Read-only provider holding one appkey/secret pair in memory.
+
+    Used where credentials arrive for a single operation and must not be
+    persisted: setup's validation call before anything is stored, and a
+    server issuing a token for credentials received on a request.
+    """
+
+    def __init__(self, appkey: str, secretkey: str, *, source: str = "static") -> None:
+        self.appkey = appkey
+        self.secretkey = secretkey
+        self.source = source
+
+    def get_credentials(self, mode: Mode) -> CredentialSet | None:
+        return CredentialSet(appkey=self.appkey, secretkey=self.secretkey, source=self.source)
+
+    def set_credentials(self, mode: Mode, appkey: str, secretkey: str) -> None:
+        raise RuntimeError("정적 자격 증명 공급자는 읽기 전용입니다.")
+
+    def clear_credentials(self, mode: Mode) -> bool:
+        raise RuntimeError("정적 자격 증명 공급자는 읽기 전용입니다.")
+
+
 class EnvSecretProvider:
     def get_credentials(self, mode: Mode) -> CredentialSet | None:
         appkey_var, secretkey_var = env_var_names(mode)

kwcli-1.0.2/kiwoom/core/settings.py

@@ -0,0 +1,114 @@
+import os
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from tempfile import NamedTemporaryFile
+
+from kiwoom.core.errors import InvalidModeError, SettingsError
+from kiwoom.core.platform_paths import config_dir, ensure_private_directory, protect_file
+from kiwoom.core.types import Mode, TokenStoreKind, normalize_mode, normalize_token_store_kind
+
+
+SETTINGS_FILE_NAME = "settings.json"
+MODE_ENV_VAR = "KIWOOM_MODE"
+PROFILE_ENV_VAR = "KIWOOM_PROFILE"
+TOKEN_STORE_ENV_VAR = "KIWOOM_TOKEN_STORE"
+ACCESS_TOKEN_ENV_VAR = "KIWOOM_ACCESS_TOKEN"
+ACCESS_TOKEN_EXPIRES_AT_ENV_VAR = "KIWOOM_ACCESS_TOKEN_EXPIRES_AT"
+
+
+def get_mode_from_env() -> Mode | None:
+    value = os.getenv(MODE_ENV_VAR)
+    if not value:
+        return None
+    try:
+        return normalize_mode(value)
+    except ValueError as exc:
+        raise InvalidModeError(value) from exc
+
+
+def get_profile_from_env() -> str | None:
+    value = os.getenv(PROFILE_ENV_VAR)
+    if not value:
+        return None
+    return value.strip() or None
+
+
+def get_token_store_kind_from_env() -> TokenStoreKind | None:
+    """Return the token store kind selected by KIWOOM_TOKEN_STORE, or None.
+
+    `file` (default when unset) caches the access token under the user cache
+    directory; `memory` keeps it in-process only, so a short-lived process
+    (e.g. one MCP request → one kiwoomcli subprocess) leaves no token on disk.
+    """
+    value = os.getenv(TOKEN_STORE_ENV_VAR)
+    if not value:
+        return None
+    return normalize_token_store_kind(value.strip().lower())
+
+
+@dataclass(frozen=True)
+class PreissuedToken:
+    access_token: str
+    expires_at: datetime
+
+
+def get_preissued_token_from_env() -> PreissuedToken | None:
+    """Return the token in KIWOOM_ACCESS_TOKEN + KIWOOM_ACCESS_TOKEN_EXPIRES_AT, or None.
+
+    A caller that already holds a valid token for the same credentials (e.g. a
+    server that issued it once and keeps it in memory) hands it to a short-lived
+    process this way, so the process does not spend a `/oauth2/token` call of
+    its own. Both variables must be set together; expires_at is ISO 8601 with a
+    timezone. Only meaningful with KIWOOM_TOKEN_STORE=memory (see runtime).
+    """
+    token = os.getenv(ACCESS_TOKEN_ENV_VAR)
+    expires_raw = os.getenv(ACCESS_TOKEN_EXPIRES_AT_ENV_VAR)
+    if not token and not expires_raw:
+        return None
+    if not token or not expires_raw:
+        raise ValueError(
+            f"{ACCESS_TOKEN_ENV_VAR} and {ACCESS_TOKEN_EXPIRES_AT_ENV_VAR} must be set together."
+        )
+    try:
+        expires_at = datetime.fromisoformat(expires_raw.strip())
+    except ValueError as exc:
+        raise ValueError(f"{ACCESS_TOKEN_EXPIRES_AT_ENV_VAR} must be an ISO 8601 datetime.") from exc
+    if expires_at.tzinfo is None:
+        raise ValueError(f"{ACCESS_TOKEN_EXPIRES_AT_ENV_VAR} must include a timezone offset.")
+    return PreissuedToken(access_token=token.strip(), expires_at=expires_at)
+
+
+def settings_path() -> Path:
+    return config_dir() / SETTINGS_FILE_NAME
+
+
+def snapshot_settings() -> str | None:
+    path = settings_path()
+    if not path.exists():
+        return None
+    try:
+        return path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise SettingsError("settings.json 파일을 읽을 수 없습니다.") from exc
+
+
+def restore_settings(snapshot: str | None) -> None:
+    path = settings_path()
+    if snapshot is None:
+        path.unlink(missing_ok=True)
+        return
+
+    directory = ensure_private_directory(config_dir(), strict=False)
+    with NamedTemporaryFile(
+        "w",
+        encoding="utf-8",
+        dir=directory,
+        delete=False,
+    ) as tmp:
+        tmp.write(snapshot)
+        temp_path = Path(tmp.name)
+
+    protect_file(temp_path, strict=False)
+    temp_path.replace(path)
+    protect_file(path, strict=False)

{kwcli-1.0.0 → kwcli-1.0.2}/kiwoom/core/types.py

@@ -7,6 +7,10 @@ Mode = Literal["real", "demo"]
 
 VALID_MODES = ("real", "demo")
 
+TokenStoreKind = Literal["file", "memory"]
+
+VALID_TOKEN_STORE_KINDS = ("file", "memory")
+
 
 def normalize_mode(value: str) -> Mode:
     if value not in VALID_MODES:
@@ -14,6 +18,14 @@ def normalize_mode(value: str) -> Mode:
     return value  # type: ignore[return-value]
 
 
+def normalize_token_store_kind(value: str) -> TokenStoreKind:
+    if value not in VALID_TOKEN_STORE_KINDS:
+        raise ValueError(
+            f"Unsupported token store kind: {value!r}. Expected one of {VALID_TOKEN_STORE_KINDS}."
+        )
+    return value  # type: ignore[return-value]
+
+
 @dataclass(frozen=True)
 class Continuation:
     has_next: bool

{kwcli-1.0.0 → kwcli-1.0.2}/kiwoom/core/ws_client.py

@@ -5,7 +5,7 @@ from collections.abc import AsyncIterator, Callable
 from typing import Any
 
 from kiwoom.core.auth import KiwoomAuth, get_ws_base_url
-from kiwoom.core.errors import AUTH_RETRY_RETURN_CODES, normalize_return_code
+from kiwoom.core.errors import auth_retry_code, normalize_return_code
 
 logger = logging.getLogger(__name__)
 
@@ -194,9 +194,7 @@ class KiwoomWebSocketClient:
 
 
 def _is_auth_retry_login_error(exc: WebSocketLoginError) -> bool:
-    if exc.return_code in AUTH_RETRY_RETURN_CODES:
-        return True
-    return any(f"CODE={code}" in exc.return_msg for code in AUTH_RETRY_RETURN_CODES)
+    return auth_retry_code(exc.return_code, exc.return_msg) is not None
 
 
 async def _default_connect(uri: str, timeout_seconds: int) -> Any:

{kwcli-1.0.0 → kwcli-1.0.2}/kiwoom_cli/README.md

@@ -16,8 +16,9 @@ actions. Runtime/auth logic stays in `kiwoom/core/`; CLI use cases stay under
 ## Quickstart
 
 The everyday flow for both humans and AI agents is discovery first, then a
-single command. See [`docs/MANUAL_CLI.md`](../docs/MANUAL_CLI.md) for the user
-manual, and use `-h` on any command for its live, mapped contract.
+single command. The user manual is `docs/NOTICE_CLI.md` in this delivery tree
+(the same text becomes the PyPI package README). Use `-h` on any command for
+its live, mapped contract.
 
 ```sh
 1. kiwoomcli setup                         # onboard: alias, demo/real, keys, verify
@@ -554,7 +555,7 @@ separate account/`.env` for 금현물 where the demo account differs. All order
 writes (domestic stock/credit/gold and overseas) are `guarded` and submit with
 `--confirm`; no rows remain `preview-only`.
 
-See [`docs/MANUAL_CLI.md`](../docs/MANUAL_CLI.md) for installation, command
+See [`docs/NOTICE_CLI.md`](../docs/NOTICE_CLI.md) for installation, command
 groups, output formats, streaming, and order safety guidance.
 
 Policy-design API families:
@@ -625,7 +626,7 @@ Rules:
 - New CLI behavior must acquire runtime objects through the package facade:
   `get_auth`, `get_client`, or `get_ws_client`.
 - New implemented CLI behavior must update this README and
-  `docs/MANUAL_CLI.md`.
+  `docs/NOTICE_CLI.md`.
 
 Preferred runtime pattern:
 
@@ -638,40 +639,46 @@ response = client.fetch_page(api_id=api_id, path=path, body=body, method=method)
 
 ## Internal Layout
 
-Current CLI implementation layout:
+Current CLI implementation layout (see [`docs/DEVELOPER_CLI.md`](../docs/DEVELOPER_CLI.md)):
 
 ```text
 kiwoom_cli/
   main.py            # router only: parse args, dispatch to args.handler, error funnel
   arguments.py
-  executor.py
+  argument_maps.py
   output.py
   registry.py
   safety.py
   setup.py           # setup command parser/handler + onboarding logic
   doctor.py          # doctor command parser/handler
   order_confirmation.py
+  banner.py
+  errors.py
+  auth_context.py
   README.md
-  commands/          # one module per command group, each add_*_parser + handlers
+  executor/          # REST, WebSocket, condition search, waits
+    rest.py
+    websocket.py
+    condition.py
+    waits.py
+  commands/
+    groups.py        # MappedGroup table for pure mapped groups
+    mapped.py        # shared mapped REST parser/runner
+    stocks.py        # stocks-only parser (domestic/overseas)
+    orders.py        # order writes + --confirm
+    streams.py
+    exchange.py
     auth.py
     spec.py
-    accounts.py
-    candles.py
-    elws.py
-    etfs.py
-    investors.py
-    orderbooks.py
-    orders.py
-    quotes.py
-    rankings.py
-    securities_lending.py
-    short_selling.py
-    stocks.py
-    streams.py
-    themes.py
   maps/
     api_commands.csv
     arguments.csv
+    positional_arguments.csv
+    coupled_arguments.csv
+    order_price_policies.csv
+    order_confirmation_commands.csv
+    order_confirmation_fields.csv
+    order_value_labels.csv
     README.md
 ```
 
@@ -679,39 +686,11 @@ kiwoom_cli/
 domestic stock 206, and US stock 129. All rows are implemented; coverage is
 `public` (252) or `guarded` (85).
 
-As additional domain commands are implemented, add small modules and maps:
-
-```text
-kiwoom_cli/
-  registry.py
-  arguments.py
-  executor.py
-  output.py
-  safety.py
-  commands/
-    accounts.py
-    stocks.py
-    quotes.py
-    orderbooks.py
-    candles.py
-    rankings.py
-    etfs.py
-    elws.py
-    investors.py
-    short_selling.py
-    securities_lending.py
-    themes.py
-    orders.py
-    streams.py
-  maps/
-    api_commands.csv
-    arguments.csv
-    positional_arguments.csv
-    order_price_policies.csv
-    order_confirmation_commands.csv
-    order_confirmation_fields.csv
-    order_value_labels.csv
-```
+New commands go into `maps/*.csv` and `commands/groups.py` (`MappedGroup`)
+when the behavior is a pure mapping. Only stocks/orders/streams/exchange keep
+dedicated modules. Do not add a new `commands/<group>.py` per API family.
+See [`docs/DEVELOPER_CLI.md`](../docs/DEVELOPER_CLI.md) and
+[`docs/DEVELOPER_EXTEND.md`](../docs/DEVELOPER_EXTEND.md).
 
 Domain modules should register command groups and delegate to shared execution.
 They should not call `requests` directly, issue tokens directly, construct
@@ -719,7 +698,9 @@ ad-hoc request bodies, or bypass common safety checks.
 
 ## Documentation Contract
 
-- [`docs/MANUAL_CLI.md`](../docs/MANUAL_CLI.md) is the Korean user manual.
+- [`docs/NOTICE_CLI.md`](../docs/NOTICE_CLI.md) is the Korean user manual.
+- [`docs/DEVELOPER_CLI.md`](../docs/DEVELOPER_CLI.md) is the architecture /
+  maintenance guide (command pipeline, safety gate, how to add commands).
 - This README documents the package structure and complete command inventory.
 - `kiwoom_cli/maps/README.md` documents map files and current API counts.
 - Maps and documentation must remain synchronized with

{kwcli-1.0.0 → kwcli-1.0.2}/kiwoom_cli/maps/README.md

@@ -2,8 +2,8 @@
 
 This folder contains the runtime maps bundled with the full Kiwoom CLI.
 The current map covers all 337 APIs: OAuth 2, domestic stock 206, and US stock
-129. `tools/process_active_kiwoom_cli.py` copies the generated maps from
-`kiwoom-dev` and validates them against the bundled specification.
+129. The delivery pipeline copies generated maps from the development registry
+and validates them against the bundled specification.
 
 ## Files
 
@@ -76,16 +76,15 @@ coverage is either `public` (252) or `guarded` (85).
 
 ## Validation Scope
 
-`tools/process_active_kiwoom_cli.py` validates the maps before and after
-replacing the Active Project output:
+The bundled maps are validated against the packaged spec before they ship:
 
 - bundled spec and `api_commands.csv` contain the same 337 API IDs;
 - category counts are OAuth 2, domestic stock 206, and US stock 129;
 - domestic and overseas command paths use their corresponding parser roots;
 - every map row is implemented and Python sources compile;
 - `exchange.py` and `coupled_arguments.csv` remain available;
-- `kiwoom_cli_prove/domestic` and `kiwoom_cli_prove/overseas` contain only
-  mapped `{api_id}/{command}.{txt|png}` evidence.
+- CLI prove evidence, when present, is stored as
+  `{domestic|overseas}/{api_id}/{command}.{txt|png}`.
 
 Domestic and overseas order writes remain guarded: without `--confirm`, the CLI
 prints a 미전송 주문 확인 and does not submit the order.

{kwcli-1.0.0 → kwcli-1.0.2}/kiwoom_cli/setup.py

@@ -1,5 +1,5 @@
 import argparse
-from dataclasses import dataclass, replace
+from dataclasses import replace
 from datetime import timedelta, timezone
 from getpass import getpass
 import sys
@@ -16,8 +16,8 @@ from kiwoom.core.profiles import (
     validate_profile_alias,
 )
 from kiwoom.core.secrets import (
-    CredentialSet,
     EnvSecretProvider,
+    StaticSecretProvider,
     default_secret_provider,
 )
 from kiwoom.core.settings import restore_settings, snapshot_settings
@@ -85,21 +85,6 @@ def handle_setup(args: argparse.Namespace) -> None:
     )
 
 
-@dataclass
-class _EphemeralSecretProvider:
-    appkey: str
-    secretkey: str
-
-    def get_credentials(self, mode: Mode) -> CredentialSet | None:
-        return CredentialSet(appkey=self.appkey, secretkey=self.secretkey, source="prompt")
-
-    def set_credentials(self, mode: Mode, appkey: str, secretkey: str) -> None:
-        raise RuntimeError("임시 자격 증명 공급자는 읽기 전용입니다.")
-
-    def clear_credentials(self, mode: Mode) -> bool:
-        raise RuntimeError("임시 자격 증명 공급자는 읽기 전용입니다.")
-
-
 def run_setup(*, alias: str | None = None, mode: str | None = None) -> None:
     print_banner()
     print()
@@ -327,7 +312,7 @@ def _validate_credentials(mode: Mode, appkey: str, secretkey: str) -> tuple[Toke
     _wz_note("입력한 자격 증명을 확인하는 중입니다…")
     auth = get_auth(
         mode=mode,
-        secret_provider=_EphemeralSecretProvider(appkey=appkey, secretkey=secretkey),
+        secret_provider=StaticSecretProvider(appkey, secretkey, source="prompt"),
         token_store_kind="memory",
     )
     client = get_client(auth=auth)

{kwcli-1.0.0 → kwcli-1.0.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "kwcli"
-version = "1.0.0"
+version = "1.0.2"
 description = "Kiwoom OpenAPI toolkit"
 readme = "README.md"
 requires-python = ">=3.13"

kwcli-1.0.0/kiwoom/core/settings.py

@@ -1,64 +0,0 @@
-import os
-from pathlib import Path
-from tempfile import NamedTemporaryFile
-
-from kiwoom.core.errors import InvalidModeError, SettingsError
-from kiwoom.core.platform_paths import config_dir, ensure_private_directory, protect_file
-from kiwoom.core.types import Mode, normalize_mode
-
-
-SETTINGS_FILE_NAME = "settings.json"
-MODE_ENV_VAR = "KIWOOM_MODE"
-PROFILE_ENV_VAR = "KIWOOM_PROFILE"
-
-
-def get_mode_from_env() -> Mode | None:
-    value = os.getenv(MODE_ENV_VAR)
-    if not value:
-        return None
-    try:
-        return normalize_mode(value)
-    except ValueError as exc:
-        raise InvalidModeError(value) from exc
-
-
-def get_profile_from_env() -> str | None:
-    value = os.getenv(PROFILE_ENV_VAR)
-    if not value:
-        return None
-    return value.strip() or None
-
-
-def settings_path() -> Path:
-    return config_dir() / SETTINGS_FILE_NAME
-
-
-def snapshot_settings() -> str | None:
-    path = settings_path()
-    if not path.exists():
-        return None
-    try:
-        return path.read_text(encoding="utf-8")
-    except OSError as exc:
-        raise SettingsError("settings.json 파일을 읽을 수 없습니다.") from exc
-
-
-def restore_settings(snapshot: str | None) -> None:
-    path = settings_path()
-    if snapshot is None:
-        path.unlink(missing_ok=True)
-        return
-
-    directory = ensure_private_directory(config_dir(), strict=False)
-    with NamedTemporaryFile(
-        "w",
-        encoding="utf-8",
-        dir=directory,
-        delete=False,
-    ) as tmp:
-        tmp.write(snapshot)
-        temp_path = Path(tmp.name)
-
-    protect_file(temp_path, strict=False)
-    temp_path.replace(path)
-    protect_file(path, strict=False)