induscode 0.1.0__py3-none-any.whl

induscode/console/theme/palette.py

@@ -0,0 +1,128 @@
+"""Theme palettes — the console's own re-derived accent ramps.
+
+Port of TS ``src/console/theme/palette.ts``; the hex values are carried over
+VERBATIM. This module owns the four raw
+:class:`~induscode.console.contract.ThemePalette` values the console ships
+with, one per :data:`~induscode.console.contract.ThemeScheme`. A palette is
+the *source* nine-stop ramp a scheme is built from: three accent hues (a cool
+primary, a warm secondary, a muted support tertiary), a three-stop neutral
+text gradient (ink/body/muted), and the three status hues
+(affirm/caution/alarm). Everything the console renders is computed from these
+stops by the token derivation step — no module downstream of here writes a
+literal hex.
+
+The hex values are an original ramp authored for this console. The cool
+primary is a desaturated spring-green/teal, the warm secondary a tangerine
+amber, and the support tertiary a soft periwinkle; the neutral gradient is a
+cool slate. The ``daylight`` variant re-derives the same roles at higher
+saturation / lower luminance so they read on a bright terminal background.
+None of these stops reuse an upstream accent — they were picked fresh against
+a contrast target for each role.
+"""
+
+from __future__ import annotations
+
+from dataclasses import replace
+from types import MappingProxyType
+from typing import Final, Mapping
+
+from ..contract import ThemePalette, ThemeScheme
+
+__all__ = [
+    "DAYLIGHT_CB_PALETTE",
+    "DAYLIGHT_PALETTE",
+    "MIDNIGHT_CB_PALETTE",
+    "MIDNIGHT_PALETTE",
+    "PALETTES",
+]
+
+
+# ---------------------------------------------------------------------------
+# The two raw ramps
+# ---------------------------------------------------------------------------
+
+#: The dark-terminal ramp.
+#:
+#: Cool spring-teal primary against a cool-slate neutral gradient, with a warm
+#: amber secondary for contrast accents and a soft periwinkle support tone.
+MIDNIGHT_PALETTE: Final[ThemePalette] = ThemePalette(
+    primary="#3ad6b4",
+    secondary="#f0a24b",
+    tertiary="#7c9fe8",
+    ink="#f4f6fb",
+    body="#c3c8d4",
+    muted="#7e8696",
+    affirm="#46c98a",
+    caution="#e8b341",
+    alarm="#ef6a6a",
+)
+
+#: The light-terminal ramp.
+#:
+#: The same role assignments re-derived deeper and more saturated so each hue
+#: keeps its contrast against a bright background; the neutral gradient
+#: inverts to a dark-on-light slate.
+DAYLIGHT_PALETTE: Final[ThemePalette] = ThemePalette(
+    primary="#0f8f78",
+    secondary="#c26a10",
+    tertiary="#3a5ec0",
+    ink="#1c2230",
+    body="#3a4253",
+    muted="#6b7382",
+    affirm="#1d9d63",
+    caution="#a9740a",
+    alarm="#c4322f",
+)
+
+
+# ---------------------------------------------------------------------------
+# The daltonized (color-blind-friendly) ramps
+# ---------------------------------------------------------------------------
+
+#: The dark-terminal color-blind-safe ramp.
+#:
+#: A clone of :data:`MIDNIGHT_PALETTE` that re-derives the three *status*
+#: hues so a red-green color-blind user (deuteran/protan, ~8% of men) can
+#: tell success from failure without relying on the red-green axis. Success
+#: moves off green onto a vivid blue (``affirm → #4aa3ff``); failure stays
+#: red but is deepened to a darker tone (``alarm → #c83232``) so it sits well
+#: below the bright blue in lightness, and the amber warning is nudged
+#: brighter — so the three status tones separate by *lightness*, not hue
+#: alone. The three accent hues and the neutral gradient are carried over
+#: unchanged from the base midnight ramp — only the status stops move, so
+#: the overall look stays the midnight scheme.
+MIDNIGHT_CB_PALETTE: Final[ThemePalette] = replace(
+    MIDNIGHT_PALETTE,
+    affirm="#4aa3ff",
+    caution="#f2c75c",
+    alarm="#c83232",
+)
+
+#: The light-terminal color-blind-safe ramp.
+#:
+#: The daylight counterpart of :data:`MIDNIGHT_CB_PALETTE`: clones
+#: :data:`DAYLIGHT_PALETTE` and remaps success to a deeper blue tuned for a
+#: bright background (``affirm → #1f6fd6``), deepens the red alarm
+#: (``alarm → #b02622``) for lightness separation from that blue, and darkens
+#: the amber warning so the three status tones stay separable by lightness on
+#: a light terminal too.
+DAYLIGHT_CB_PALETTE: Final[ThemePalette] = replace(
+    DAYLIGHT_PALETTE,
+    affirm="#1f6fd6",
+    caution="#8a5e00",
+    alarm="#b02622",
+)
+
+#: The raw ramp for each scheme, keyed by
+#: :data:`~induscode.console.contract.ThemeScheme`.
+#:
+#: The token derivation step reads from this table; the resolver returns the
+#: scheme whose palette it expanded.
+PALETTES: Final[Mapping[ThemeScheme, ThemePalette]] = MappingProxyType(
+    {
+        "midnight": MIDNIGHT_PALETTE,
+        "daylight": DAYLIGHT_PALETTE,
+        "midnight-cb": MIDNIGHT_CB_PALETTE,
+        "daylight-cb": DAYLIGHT_CB_PALETTE,
+    }
+)

induscode/console/theme/resolve.py

@@ -0,0 +1,123 @@
+"""Theme resolution — assemble the fully-resolved :class:`ConsoleTheme` for
+each scheme and expose the picker entry points.
+
+Port of TS ``src/console/theme/resolve.ts``. This is the top of the theme
+engine. It runs the pipeline once per scheme at module load:
+
+.. code-block:: text
+
+    palette ──derive_tokens──▶ tokens ──theme_bundle──▶ framework bundle
+       └─────────────────────────┴────────────────────────────┘
+                            ConsoleTheme
+
+The four assembled themes are frozen into :data:`THEMES`;
+:func:`resolve_theme` is the single sanctioned way the surface obtains the
+theme for a scheme name. Because the heavy work (adapter + Textual Theme +
+Pygments style construction) happens here at the config-load boundary, the
+render path only ever reads an already-built :class:`ConsoleTheme` — it never
+re-derives colours.
+
+Port delta (locked; analysis 02 §5): each theme carries a full framework
+``ThemeBundle``; the M5-wave-2 ``ConsoleApp`` registers every bundle's
+Textual Theme at startup so ``scheme:set`` becomes a native
+``app.theme = scheme`` live retheme. The Textual dark flag is derived from
+the ramp the same way the token math picks its background anchor: a light
+``ink`` implies a dark terminal.
+"""
+
+from __future__ import annotations
+
+from types import MappingProxyType
+from typing import Final, Mapping
+
+from ..contract import (
+    DEFAULT_SCHEME,
+    ConsoleTheme,
+    ThemePalette,
+    ThemeScheme,
+    is_theme_scheme,
+)
+from .adapter import theme_bundle
+from .palette import PALETTES
+from .tokens import derive_tokens, luminance
+
+__all__ = [
+    "THEMES",
+    "THEME_SCHEMES",
+    "resolve_theme",
+]
+
+
+# ---------------------------------------------------------------------------
+# Assembly
+# ---------------------------------------------------------------------------
+
+
+def _assemble_theme(scheme: ThemeScheme, palette: ThemePalette) -> ConsoleTheme:
+    """Run the full pipeline for one scheme: derive tokens from the ramp,
+    build the framework bundle from those tokens, and box everything into a
+    :class:`ConsoleTheme`.
+
+    :param scheme: the scheme identity this resolves
+    :param palette: the raw ramp the scheme is built from
+    """
+    tokens = derive_tokens(palette)
+    # A light high-contrast ink means a dark terminal — the same anchor logic
+    # the diff-background derivation uses.
+    bundle = theme_bundle(scheme, tokens, dark=luminance(palette.ink) >= 0.5)
+    return ConsoleTheme(
+        scheme=scheme,
+        palette=palette,
+        tokens=tokens,
+        adapter=bundle.adapter,
+        bundle=bundle,
+    )
+
+
+# ---------------------------------------------------------------------------
+# The resolved theme table
+# ---------------------------------------------------------------------------
+
+#: The built-in themes, fully resolved and keyed by
+#: :data:`~induscode.console.contract.ThemeScheme`.
+#:
+#: Assembled once at load time from :data:`~.palette.PALETTES`. This is the
+#: table the theme picker lists and :func:`resolve_theme` reads; it is the
+#: console's complete shipped theme set.
+THEMES: Final[Mapping[ThemeScheme, ConsoleTheme]] = MappingProxyType(
+    {
+        "midnight": _assemble_theme("midnight", PALETTES["midnight"]),
+        "daylight": _assemble_theme("daylight", PALETTES["daylight"]),
+        "midnight-cb": _assemble_theme("midnight-cb", PALETTES["midnight-cb"]),
+        "daylight-cb": _assemble_theme("daylight-cb", PALETTES["daylight-cb"]),
+    }
+)
+
+
+# ---------------------------------------------------------------------------
+# The resolver
+# ---------------------------------------------------------------------------
+
+
+def resolve_theme(scheme: str | None = None) -> ConsoleTheme:
+    """Resolve a scheme name to its fully-built :class:`ConsoleTheme`.
+
+    The single entry point the surface and the loader use to turn a scheme
+    name (from settings, a slash argument, or the
+    :data:`~induscode.console.contract.DEFAULT_SCHEME`) into a theme. An
+    unrecognised or absent name falls back to the default rather than
+    raising, so a corrupt preference never blanks the console.
+
+    :param scheme: a candidate scheme name, possibly invalid or ``None``
+    :returns: the resolved theme for that scheme, or the default theme
+    """
+    if isinstance(scheme, str) and is_theme_scheme(scheme):
+        return THEMES[scheme]
+    return THEMES[DEFAULT_SCHEME]
+
+
+#: The schemes the console offers, in picker order.
+#:
+#: Derived from :data:`THEMES` so adding a scheme to the table adds it to the
+#: picker with no second list to update.
+THEME_SCHEMES: Final[tuple[ThemeScheme, ...]] = tuple(THEMES.keys())

induscode/console/theme/tokens.py

@@ -0,0 +1,185 @@
+"""Token derivation — expand a raw :class:`ThemePalette` into the semantic
+:class:`ThemeTokens` the console actually renders against.
+
+Port of TS ``src/console/theme/tokens.ts``; the hex math (parse / format /
+blend / luminance / anchor) is carried over exactly, including JS
+``Math.round`` semantics for channel rounding.
+
+The console body never names a hex or a palette stop; it names a *role*
+(``signal``, ``frame``, ``body_text``, ``alarm``, …). This module is the one
+place the thirteen roles are bound to ramp stops. The mapping is pure and
+total: every field of :class:`ThemeTokens` is assigned exactly once from a
+:class:`ThemePalette` field, so a ramp that is missing a stop fails at
+construction rather than producing an undefined colour at render time.
+
+Role → stop assignments (identical structure for both schemes; the schemes
+differ only in the underlying ramp):
+
+- ``signal``         ← ``primary``    (the dominant accent: focus, selection)
+- ``frame``          ← ``tertiary``   (default structural border lines)
+- ``quiet_frame``    ← ``muted``      (de-emphasised separators)
+- ``prompt_surface`` ← ``secondary``  (the composer's active tint)
+- ``card_accent``    ← ``secondary``  (row gutters and headers)
+- ``body_text``      ← ``body``       (default answer foreground)
+- ``muted_text``     ← ``muted``      (timestamps, hints, metadata)
+- ``ink_text``       ← ``ink``        (high-contrast text on an accent)
+- ``notice``         ← ``tertiary``   (informational tone)
+- ``affirm``         ← ``affirm``     (success tone)
+- ``caution``        ← ``caution``    (warning tone)
+- ``alarm``          ← ``alarm``      (error/fault tone)
+- ``pending``        ← ``primary``    (busy/in-flight tone)
+
+Rich-render roles (markdown / diff / syntax highlighting) are derived from
+the same nine stops so the styled-transcript / colored-diff / fenced-code
+surfaces recolour with the scheme and need no extra palette stop:
+
+- ``code_inline``       ← ``primary``                    (inline code accent)
+- ``heading``           ← ``primary``                    (heading accent)
+- ``blockquote_bar``    ← ``muted``                      (dim quote bar)
+- ``diff_added_bg``     ← ``affirm`` blended to anchor   (added-line tint)
+- ``diff_removed_bg``   ← ``alarm``  blended to anchor   (removed-line tint)
+- ``diff_added_text``   ← ``affirm``                     (added fg / ``+``)
+- ``diff_removed_text`` ← ``alarm``                      (removed fg / ``-``)
+- ``syn_keyword``       ← ``primary``                    (keywords)
+- ``syn_string``        ← ``affirm``                     (strings)
+- ``syn_number``        ← ``caution``                    (numbers)
+- ``syn_comment``       ← ``muted``                      (comments)
+- ``syn_type``          ← ``tertiary``                   (types / classes)
+
+Deriving the two diff backgrounds (rather than adding raw stops) keeps the
+:class:`ThemePalette` a flat nine-stop ramp while guaranteeing every scheme —
+including the color-blind variants — gets a legible ``+``/``-`` tint that
+tracks its own success/alarm hue.
+"""
+
+from __future__ import annotations
+
+import math
+
+from ..contract import ThemePalette, ThemeTokens
+
+__all__ = [
+    "derive_tokens",
+    "luminance",
+]
+
+
+# ---------------------------------------------------------------------------
+# Hex helpers — derive the diff-background tints
+# ---------------------------------------------------------------------------
+
+
+def _parse_hex(hex_color: str) -> tuple[int, int, int]:
+    """Parse a ``#rrggbb`` (or ``#rgb``) string into an ``(r, g, b)`` triple
+    (0–255)."""
+    h = hex_color.strip()
+    if h.startswith("#"):
+        h = h[1:]
+    if len(h) == 3:
+        h = "".join(c + c for c in h)
+    try:
+        n = int(h[:6].ljust(6, "0"), 16)
+    except ValueError:
+        # TS Number.parseInt yields NaN here; the bit-shifts then read 0.
+        n = 0
+    return ((n >> 16) & 0xFF, (n >> 8) & 0xFF, n & 0xFF)
+
+
+def _js_round(value: float) -> int:
+    """JS ``Math.round`` — half-up toward +infinity (Python ``round`` banks)."""
+    return math.floor(value + 0.5)
+
+
+def _to_hex(rgb: tuple[float, float, float]) -> str:
+    """Format an ``(r, g, b)`` triple back into a ``#rrggbb`` string."""
+    r, g, b = rgb
+    clamped = (max(0, min(255, _js_round(v))) for v in (r, g, b))
+    return "#" + "".join(f"{v:02x}" for v in clamped)
+
+
+def _mix_hex(a: str, b: str, t: float) -> str:
+    """Linearly blend two hex colours; ``t`` is the weight of ``b`` (0 → ``a``,
+    1 → ``b``). Used to pull a saturated status hue toward a neutral anchor so
+    the resulting diff-line tint is dark/quiet enough for content to read on
+    top of it."""
+    ar, ag, ab = _parse_hex(a)
+    br, bg, bb = _parse_hex(b)
+    return _to_hex(
+        (
+            ar + (br - ar) * t,
+            ag + (bg - ag) * t,
+            ab + (bb - ab) * t,
+        )
+    )
+
+
+def _diff_background(hue: str, anchor: str) -> str:
+    """Derive a diff-line background tint from a status hue by blending it
+    heavily (78%) toward the scheme's implied terminal background. We keep
+    ~22% of the hue so the tint is recognisably green/red (or blue/red on the
+    CB schemes) without overpowering the foreground text painted on top."""
+    return _mix_hex(hue, anchor, 0.78)
+
+
+def luminance(hex_color: str) -> float:
+    """Relative luminance (0 dark → 1 light) of a hex colour, for anchor
+    choice (and the resolver's Textual dark-flag derivation)."""
+    r, g, b = _parse_hex(hex_color)
+    return (0.2126 * r + 0.7152 * g + 0.0722 * b) / 255
+
+
+def _background_anchor(palette: ThemePalette) -> str:
+    """The neutral a diff tint should be pulled toward — the scheme's implied
+    terminal background. A scheme whose high-contrast ``ink`` is light (a
+    dark terminal) implies a near-black background, so we blend the status
+    hue toward black; a scheme with dark ``ink`` (a light terminal) blends
+    toward white. This keeps the added/removed tints quiet enough for the
+    diff content painted on top to stay legible in either scheme family."""
+    return "#000000" if luminance(palette.ink) >= 0.5 else "#ffffff"
+
+
+# ---------------------------------------------------------------------------
+# Derivation
+# ---------------------------------------------------------------------------
+
+
+def derive_tokens(palette: ThemePalette) -> ThemeTokens:
+    """Map a raw accent ramp onto the closed semantic token set.
+
+    Pure and deterministic: the same palette always yields the same tokens,
+    and the returned object is a fresh frozen value the resolver can cache.
+    The role assignments are shared by both schemes — only the ramp handed in
+    differs.
+
+    :param palette: the raw nine-stop ramp for a scheme
+    :returns: the full semantic token map (status + rich-render roles)
+    """
+    anchor = _background_anchor(palette)
+    return ThemeTokens(
+        signal=palette.primary,
+        frame=palette.tertiary,
+        quiet_frame=palette.muted,
+        prompt_surface=palette.secondary,
+        card_accent=palette.secondary,
+        body_text=palette.body,
+        muted_text=palette.muted,
+        ink_text=palette.ink,
+        notice=palette.tertiary,
+        affirm=palette.affirm,
+        caution=palette.caution,
+        alarm=palette.alarm,
+        pending=palette.primary,
+        # Rich-render roles — derived from the same nine stops.
+        code_inline=palette.primary,
+        heading=palette.primary,
+        blockquote_bar=palette.muted,
+        diff_added_bg=_diff_background(palette.affirm, anchor),
+        diff_removed_bg=_diff_background(palette.alarm, anchor),
+        diff_added_text=palette.affirm,
+        diff_removed_text=palette.alarm,
+        syn_keyword=palette.primary,
+        syn_string=palette.affirm,
+        syn_number=palette.caution,
+        syn_comment=palette.muted,
+        syn_type=palette.tertiary,
+    )

induscode/console_slash/__init__.py

@@ -0,0 +1,111 @@
+"""Slash command framework — contracts, registry assembly, line resolution,
+and the shared command toolkit.
+
+Port of the *framework* half of TS ``src/console/slash`` (``contract.ts``'s
+slash types, ``registry.ts``, ``resolve.ts``, ``commands/shared.ts``), in
+three pure pieces:
+
+- **The contracts** — :class:`SlashCommand` rows, the
+  :class:`Handled` / :class:`Prompt` / :class:`Unknown` outcome union, the
+  :class:`SlashContext` dataclass of callables a handler acts through, and
+  the frozen :class:`SlashRegistry` shape.
+- **The registry** — :func:`build_registry` folds an ordered command list
+  into the registry (commands + a name/alias index, duplicate tokens
+  rejected loudly), and the derived lookups (:func:`match_prefix`,
+  :func:`find_command`, :func:`commands_in_family`, :func:`list_families`)
+  power resolution, completion, and grouped listing.
+- **Resolution** — :func:`resolve_slash` parses a typed composer line and
+  resolves it against a registry to a discriminated
+  :class:`NotSlash` / :class:`Match` / :class:`Miss` outcome.
+
+Milestone note (M1)
+-------------------
+This package lands under ``induscode.console_slash`` for M1: it is a pure
+leaf with no console dependency. The full console package
+(``induscode.console``) arrives with M5 and will re-export this surface as
+its ``slash`` layer; M5 also brings the command catalog itself —
+``builtins.py`` with the explicit ``build_catalog(cwd, home)`` assembly (no
+import-time I/O) and the pre-folded default registry (the TS
+``DEFAULT_SLASH_REGISTRY``) — plus the command groups
+(``transcript`` / ``workbench`` / ``integrations`` / ``dynamic``). The
+effectful dispatcher (which awaits a matched command's ``run``) likewise
+lives outside this barrel; everything exported here is pure.
+"""
+
+from .contract import (
+    Handled,
+    OpenModal,
+    Prompt,
+    SlashCommand,
+    SlashContext,
+    SlashOutcome,
+    SlashRegistry,
+    SlashRun,
+    Unknown,
+)
+from .registry import (
+    build_registry,
+    commands_in_family,
+    find_command,
+    list_families,
+    match_prefix,
+    tokens_of,
+)
+from .resolve import (
+    SLASH_PREFIX,
+    Match,
+    Miss,
+    NotSlash,
+    SlashLine,
+    SlashResolution,
+    looks_like_slash,
+    parse_slash,
+    resolve_slash,
+)
+from .shared import (
+    FAMILY,
+    HANDLED,
+    FamilyLabels,
+    SubCommand,
+    VerbSplit,
+    family_runner,
+    info,
+    split_verb,
+    warn,
+)
+
+__all__ = [
+    "FAMILY",
+    "FamilyLabels",
+    "HANDLED",
+    "Handled",
+    "Match",
+    "Miss",
+    "NotSlash",
+    "OpenModal",
+    "Prompt",
+    "SLASH_PREFIX",
+    "SlashCommand",
+    "SlashContext",
+    "SlashLine",
+    "SlashOutcome",
+    "SlashRegistry",
+    "SlashResolution",
+    "SlashRun",
+    "SubCommand",
+    "Unknown",
+    "VerbSplit",
+    "build_registry",
+    "commands_in_family",
+    "family_runner",
+    "find_command",
+    "info",
+    "list_families",
+    "looks_like_slash",
+    "match_prefix",
+    "parse_slash",
+    "resolve_slash",
+    "split_verb",
+    "tokens_of",
+    "warn",
+]