skit-cli 0.0.1__py3-none-any.whl

skit/i18n.py

@@ -0,0 +1,324 @@
+"""i18n core (GNU gettext).
+
+Design notes:
+- Catalogs are standard gettext with **source-string msgids**: the English text is the msgid, so an
+  untranslated entry falls back to the English source automatically. English therefore ships no .mo
+  (it is the identity). Translations live at locales/<gettext_locale>/LC_MESSAGES/skit.mo — POSIX
+  underscore dirs (zh_CN), while the public tags stay hyphenated (zh-CN).
+- Edit the .po sources, then recompile with `python scripts/i18n.py compile` (Babel). Runtime uses the
+  stdlib `gettext` module only — zero third-party i18n dependencies.
+- Locale negotiation chain: SKIT_LANG > config.toml [language] > LC_ALL > LC_MESSAGES > LANG > system
+  locale > en. Each candidate expands into a fallback chain (zh-TW -> zh-Hant alias -> zh -> en),
+  wired into gettext via its language list so a missing translation falls back entry by entry and
+  always ends at the English source. The macrolanguage step is script-aware (_zh_family): a
+  Traditional tag's bare-"zh" fallback resolves back to zh-TW, not zh-CN, so a msgid missing from
+  zh_TW.mo surfaces in English rather than in Simplified glyphs — and symmetrically for Simplified.
+- Pseudo-locale (x-pseudo): an ⟦bracket + stretch⟧ transform over English, used to visually catch
+  hard-coded / untranslated strings and truncation. Placeholders (%(name)s) are preserved so
+  %-substitution at the call site still works.
+- Headless: no CLI/TUI dependency; store/launcher can import it safely.
+"""
+
+from __future__ import annotations
+
+import gettext as _gt
+import os
+import re
+import sys
+import tomllib
+from pathlib import Path
+
+from .atomic import atomic_write_toml, load_toml_recoverable
+from .paths import config_dir
+
+_LOCALES_DIR = Path(__file__).parent / "locales"
+_DOMAIN = "skit"
+DEFAULT_LOCALE = "en"
+PSEUDO_LOCALE = "x-pseudo"
+
+# Alias -> the locale we actually ship.
+_ALIASES = {
+    "zh": "zh-CN",
+    "zh-hans": "zh-CN",
+    "zh-sg": "zh-CN",
+    "zh-my": "zh-CN",
+    "zh-hant": "zh-TW",
+    "zh-hk": "zh-TW",
+    "zh-mo": "zh-TW",
+}
+
+# Script/region hints that identify which shipped Chinese locale a "zh-*" tag belongs to. Used by
+# _zh_family() to make the bare-macrolanguage fallback step ("zh" on its own, reached by truncating
+# e.g. zh-TW down to zh) resolve within the same script family instead of always defaulting to
+# Simplified.
+#
+# Split into script vs. region tiers because they must be checked in that order: BCP-47 treats the
+# script subtag as more specific than the region subtag, so a tag carrying both must let script
+# decide when they disagree (zh-Hans-TW is Simplified despite the Traditional-associated "TW"
+# region; zh-Hant-CN is Traditional despite the Simplified-associated "CN" region). Region hints
+# are only consulted when the tag has no script subtag at all.
+_HANT_SCRIPT = {"hant"}
+_HANS_SCRIPT = {"hans"}
+_HANT_REGION_HINTS = {"hk", "mo", "tw"}
+_HANS_REGION_HINTS = {"cn", "sg", "my"}
+
+_translations: _gt.NullTranslations | None = None
+_active: str = DEFAULT_LOCALE
+_pseudo: bool = False
+
+
+def _gt_dir(tag: str) -> str:
+    """Public hyphen tag -> gettext locale dir (POSIX underscore): 'zh-CN' -> 'zh_CN'."""
+    return tag.replace("-", "_")
+
+
+def available_locales() -> list[str]:
+    """Locales we ship: English (identity) plus every dir with a compiled catalog."""
+    found = {DEFAULT_LOCALE}
+    if _LOCALES_DIR.is_dir():
+        for p in _LOCALES_DIR.iterdir():
+            if (p / "LC_MESSAGES" / f"{_DOMAIN}.mo").is_file():  # pragma: no mutate — fs-case
+                found.add(p.name.replace("_", "-"))
+    return sorted(found)
+
+
+def _normalize(tag: str) -> str:
+    """'zh_TW.UTF-8' -> 'zh-TW'; normalizes casing."""
+    tag = tag.split(".", maxsplit=1)[0].split("@", maxsplit=1)[0]  # pragma: no mutate
+    tag = tag.replace("_", "-").strip()
+    if not tag:
+        return ""
+    parts = tag.split("-")
+    out = [parts[0].lower()]
+    for p in parts[1:]:
+        if len(p) == 2:
+            out.append(p.upper())
+        elif len(p) == 4:
+            out.append(p.capitalize())
+        else:
+            out.append(p.lower())
+    return "-".join(out)
+
+
+def _zh_family(tag: str) -> str | None:
+    """Which shipped Chinese locale a "zh-*" tag's script/region hints point to: "zh-TW"
+    (Traditional) or "zh-CN" (Simplified). None if tag isn't zh-rooted, or is the bare "zh"
+    macrolanguage itself with no script/region qualifier at all (that case is left to the plain
+    _ALIASES lookup, which defaults it to zh-CN — the conventional "zh" == Simplified reading).
+
+    Script subtag is authoritative over region when a tag carries both and they disagree (BCP-47
+    treats script as the more specific signal): zh-Hant-CN is Traditional despite the "CN" region,
+    and zh-Hans-TW is Simplified despite the "TW" region. Region hints are only consulted when no
+    script subtag is present.
+
+    Used by _expand_chain so that truncating a qualified tag (zh-TW, zh-HK, zh-Hant, zh-Hans, ...)
+    down to the bare macrolanguage subtag "zh" resolves within the *same* script family, rather
+    than unconditionally injecting zh-CN into a Traditional tag's fallback chain — which would
+    surface Simplified glyphs for any msgid untranslated in zh_TW.mo, instead of falling through to
+    the English source as the module docstring's negotiation chain intends.
+    """
+    parts = [p.lower() for p in tag.split("-")]
+    if parts[0] != "zh" or len(parts) == 1:
+        return None
+    rest = parts[1:]
+    if any(p in _HANT_SCRIPT for p in rest):
+        return "zh-TW"
+    if any(p in _HANS_SCRIPT for p in rest):
+        return "zh-CN"
+    if any(p in _HANT_REGION_HINTS for p in rest):
+        return "zh-TW"
+    if any(p in _HANS_REGION_HINTS for p in rest):
+        return "zh-CN"
+    return None
+
+
+def _expand_chain(tag: str) -> list[str]:
+    """Expand a single tag into a fallback chain: zh-Hant-TW -> [zh-Hant-TW, zh-Hant, zh] + alias
+    resolution.
+
+    Script-aware: when truncation reaches the bare macrolanguage subtag "zh" for a tag that carried
+    a script/region hint (zh-TW, zh-HK, zh-Hant, zh-Hans, zh-CN, ...), that step's alias resolves
+    within the same script family (see _zh_family) instead of unconditionally defaulting to zh-CN —
+    otherwise every Traditional tag's chain would gain a Simplified candidate ahead of en. A
+    genuinely bare "zh" request (no hint at all) still defaults to zh-CN via _ALIASES.
+    """
+    family = _zh_family(tag)
+    chain: list[str] = []
+    parts = tag.split("-")
+    while parts:
+        cand = "-".join(parts)
+        if family is not None and cand.lower() == "zh":
+            alias = family
+        else:
+            alias = _ALIASES.get(cand.lower(), cand)
+        for c in (cand, alias):
+            if c not in chain:
+                chain.append(c)
+        parts.pop()
+    return chain
+
+
+def _config_language() -> str:
+    path = config_dir() / "config.toml"  # pragma: no mutate — fs-case-dependent
+    if not path.is_file():
+        return ""
+    try:
+        with open(path, "rb") as f:
+            return str(tomllib.load(f).get("language", ""))
+    except (OSError, tomllib.TOMLDecodeError):
+        return ""
+
+
+def _env(name: str) -> str:
+    return os.environ.get(name, "")  # pragma: no mutate — default only matters via truthiness
+
+
+def detect_locale() -> str:
+    """Return the raw tag the user requested (un-negotiated).
+
+    An empty string means no preference was found.
+    """
+    for source in (
+        _env("SKIT_LANG"),
+        _config_language(),
+        _env("LC_ALL"),
+        _env("LC_MESSAGES"),
+        _env("LANG"),
+    ):
+        tag = _normalize(source) if source and source.lower() != "c" else ""
+        if tag:
+            return tag
+    try:
+        import locale as _locale
+
+        loc = _locale.getlocale()[0]
+        if loc:
+            return _normalize(loc)
+    except (ValueError, TypeError):
+        pass
+    return ""
+
+
+def is_supported(tag: str) -> bool:
+    """Whether the tag (or any candidate on its fallback chain) maps to a shipped locale.
+    The pseudo-locale is always considered supported. Used to validate entry points like the CLI
+    `lang` command."""
+    normalized = _normalize(tag)
+    if not normalized:
+        return False
+    if normalized.lower() == PSEUDO_LOCALE:
+        return True
+    shipped = set(available_locales())
+    return any(c in shipped for c in _expand_chain(normalized))
+
+
+def negotiate(requested: str) -> tuple[str, list[str]]:
+    """Negotiate (primary locale, full fallback chain ending in en)."""
+    shipped = set(available_locales())
+    chain: list[str] = []
+    if requested:
+        for cand in _expand_chain(requested):
+            if cand in shipped and cand not in chain:
+                chain.append(cand)
+    if DEFAULT_LOCALE not in chain:
+        chain.append(DEFAULT_LOCALE)
+    return chain[0], chain
+
+
+def init(lang: str | None = None) -> str:
+    """Initialize (or reinitialize) the message system; return the effective primary locale."""
+    global _translations, _active, _pseudo
+    requested = _normalize(lang) if lang else detect_locale()
+    _pseudo = requested.lower() == PSEUDO_LOCALE
+    if _pseudo:
+        primary, chain = DEFAULT_LOCALE, [DEFAULT_LOCALE]
+        _active = PSEUDO_LOCALE
+    else:
+        primary, chain = negotiate(requested)
+        _active = primary
+    # English is the msgid itself (identity), so only non-en locales need a catalog; gettext chains
+    # them as fallbacks in order and returns the English source for anything still untranslated.
+    languages = [_gt_dir(c) for c in chain if c != DEFAULT_LOCALE]
+    _translations = _gt.translation(_DOMAIN, _LOCALES_DIR, languages=languages, fallback=True)
+    return _active
+
+
+def current_locale() -> str:
+    return _active
+
+
+_PSEUDO_TABLE = str.maketrans("aeiouAEIOU", "àéîöûÀÉÎÖÛ")
+_PLACEHOLDER = re.compile(r"%\([^)]*\)[sdr]|%[sdrifgeExXoc%]")
+
+
+def _pseudoize(text: str) -> str:
+    """en -> pseudo: bracket markers + vowel transforms (~30% inflation), leaving %(...)s
+    placeholders untouched so call-site %-substitution still resolves."""
+    parts: list[str] = []
+    last = 0  # pragma: no mutate — text[None:x] == text[0:x]
+    for m in _PLACEHOLDER.finditer(text):
+        parts.append(text[last : m.start()].translate(_PSEUDO_TABLE))
+        parts.append(m.group())
+        last = m.end()
+    parts.append(text[last:].translate(_PSEUDO_TABLE))
+    return f"⟦{''.join(parts)}~~⟧"
+
+
+def gettext(message: str) -> str:
+    """Translate a source-string message (falls back to the English source; never raises)."""
+    if _translations is None:
+        init()
+    if _translations is None:  # pragma: no cover — init() guarantees it is set
+        raise RuntimeError("i18n init failed")
+    text = _translations.gettext(message)
+    return _pseudoize(text) if _pseudo else text
+
+
+def ngettext(singular: str, plural: str, n: int) -> str:
+    """Translate a source-string message with plural selection (CLDR rules per the target locale)."""
+    if _translations is None:
+        init()
+    if _translations is None:  # pragma: no cover — init() guarantees it is set
+        raise RuntimeError("i18n init failed")
+    text = _translations.ngettext(singular, plural, n)
+    return _pseudoize(text) if _pseudo else text
+
+
+def set_language(tag: str) -> str:
+    """Write config.toml and take effect immediately. Returns the effective locale. An empty tag
+    clears the setting (back to auto-detection).
+
+    Uses atomic.load_toml_recoverable() for the read step, so a present-but-corrupt config.toml is
+    backed up to config.toml.bak (and the user warned on stderr) instead of being silently wiped —
+    matching config.save_editor()/save_mirror(). This module can't import config.py for the same
+    recovery helper those use (config.py imports gettext from here, so the reverse would cycle);
+    the neutral atomic module is what both safely share.
+    """
+    path = config_dir() / "config.toml"  # pragma: no mutate — fs-case-dependent
+    recovery = load_toml_recoverable(path)
+    doc = recovery.doc
+    if recovery.corrupt:
+        if recovery.backup_path is not None:
+            print(
+                gettext(
+                    "%(path)s is corrupt and could not be parsed. It has been backed up to "
+                    "%(backup)s before this change; recover any lost settings from that file."
+                )
+                % {"path": str(path), "backup": str(recovery.backup_path)},
+                file=sys.stderr,
+            )
+        else:
+            print(
+                gettext(
+                    "%(path)s is corrupt and could not be parsed, and it could not be backed up "
+                    "either; the settings it contained will be lost when this change is saved."
+                )
+                % {"path": str(path)},
+                file=sys.stderr,
+            )
+    if tag:
+        doc["language"] = _normalize(tag)
+    else:
+        doc.pop("language", None)
+    atomic_write_toml(path, doc)
+    return init(tag or None)

skit/inlineform.py

@@ -0,0 +1,61 @@
+"""The CLI's inline mini-form: the run form opened in place, in the same terminal.
+
+`skit run NAME` on a TTY (with `form = "tui"`, the default) opens the same RunFormScreen
+the TUI uses — via Textual's inline mode, so there's no alternate screen and the
+scrollback survives. Submit collapses the form and the script runs right below it;
+`--plain` / `form = "plain"` / TERM=dumb fall back to line prompts instead.
+
+The extra-arguments row is hidden here: on the CLI, passthrough args already arrived
+via `skit run NAME -- <args>` (argv owns them; two sources would fight).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, override
+
+from textual.app import App
+
+from . import flows, theme
+from .theme import CLAUDE_THEME
+from .tui_form import FormResult, RunFormScreen
+
+if TYPE_CHECKING:
+    from .models import Entry
+
+
+class _InlineFormApp(App[FormResult]):
+    ENABLE_COMMAND_PALETTE = False
+    CSS = theme.CHROME_CSS
+
+    def __init__(self, entry: Entry, plan: flows.FormPlan, prefill: dict[str, str]) -> None:
+        super().__init__()
+        self._entry: Entry = entry
+        self._plan: flows.FormPlan = plan
+        self._prefill: dict[str, str] = prefill
+
+    @override
+    def get_css_variables(self) -> dict[str, str]:
+        # The first stylesheet parse runs before on_mount activates the theme; the
+        # screen CSS needs $skit-box-* resolvable from the very first frame.
+        return {**super().get_css_variables(), **theme.BOX_VARIABLES}
+
+    def on_mount(self) -> None:
+        self.register_theme(CLAUDE_THEME)
+        self.theme = "skit-claude"
+
+        def _done(result: FormResult) -> None:
+            self.exit(result)
+
+        self.push_screen(
+            RunFormScreen(self._entry, self._plan, self._prefill, include_extra=False), _done
+        )
+
+
+def collect(entry: Entry, plan: flows.FormPlan, prefill: dict[str, str]) -> dict[str, str] | None:
+    """Run the inline form; returns raw values, or None when the user cancelled."""
+    app = _InlineFormApp(entry, plan, prefill)
+    result = app.run(inline=True)
+    if result is None:
+        return None
+    values, _extra = result
+    return values