induscode 0.1.0__py3-none-any.whl

induscode/console/slash_commands/workbench.py

@@ -0,0 +1,430 @@
+"""Workbench slash commands — the pickers, display blocks, and help surfaces.
+
+Port of TS ``src/console/slash/commands/workbench.ts``. This group covers
+the overlays a user reaches for to inspect or retune the session: the model
+pickers, the per-scope routing editor, the settings list, the command
+palette (``/help``), the keyboard map (``/keys``), the project changelog
+(``/whats-new``), and a diagnostics dump (``/debug``). The picker handlers
+stay thin — they raise an overlay through ``SlashContext.open_modal`` or
+flip a reducer flag — while the help, keys, whats-new, and debug handlers do
+real work: they read the live slash catalog, the grounded keymap, a
+``CHANGELOG.md`` on disk, and the conductor's session statistics, then
+surface the result as a display block or a written file rather than a dead
+placeholder.
+
+``/help`` catalog sourcing — the cycle-killer (plan analysis 03 §6.5/§7):
+the TS build reached the assembled ``SLASH_COMMANDS`` through a *call-time
+dynamic import* of ``builtins.ts``, because ``builtins`` imports this very
+module to assemble the catalog. The Python port replaces that with a
+module-level **late-bound provider**: the catalog assembler installs the
+fully-assembled registry via :func:`set_help_registry_provider` at console
+mount (so ``/help`` always sees dynamic skill/template rows too — fixing the
+TS quirk that dynamic rows were frozen at process start), and until one is
+installed ``/help`` falls back to the static transcript + workbench groups.
+The :class:`~induscode.console_slash.SlashContext` contract is untouched.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+import time
+from collections.abc import Callable, Sequence
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Final, TypeAlias
+
+from indusagi.react_ink import UiDisplayBlock
+
+from induscode.conductor import message_to_dict
+from induscode.console_slash import (
+    FAMILY,
+    HANDLED,
+    SlashCommand,
+    SlashContext,
+    SlashOutcome,
+    SubCommand,
+    family_runner,
+    info,
+    warn,
+)
+from induscode.console.slash_commands.transcript import transcript_commands
+
+__all__ = [
+    "HelpRegistryProvider",
+    "set_help_registry_provider",
+    "workbench_commands",
+]
+
+
+# ---------------------------------------------------------------------------
+# Scoped-model routing family
+# ---------------------------------------------------------------------------
+
+
+async def _scoped_edit(ctx: SlashContext, rest: str) -> SlashOutcome:
+    ctx.open_modal("scopedModels")
+    return HANDLED
+
+
+async def _scoped_show(ctx: SlashContext, rest: str) -> SlashOutcome:
+    ctx.open_modal("scopedModels", {"focus": "summary"})
+    return HANDLED
+
+
+async def _scoped_reset(ctx: SlashContext, rest: str) -> SlashOutcome:
+    ctx.open_modal("scopedModels", {"intent": "reset"})
+    ctx.set_status(info("Per-scope model overrides cleared."))
+    return HANDLED
+
+
+#: The verb table backing ``/models-for``. Each verb routes to the same
+#: per-scope picker overlay with a different intent payload, so the picker
+#: can open straight onto the relevant facet rather than its landing view.
+_SCOPED_MODEL_VERBS: Final[tuple[SubCommand, ...]] = (
+    SubCommand(
+        verb="edit",
+        describe="open the per-scope routing editor",
+        run=_scoped_edit,
+    ),
+    SubCommand(
+        verb="show",
+        describe="review the active per-scope assignments",
+        run=_scoped_show,
+    ),
+    SubCommand(
+        verb="reset",
+        describe="clear every per-scope override",
+        run=_scoped_reset,
+    ),
+)
+
+_run_scoped_models = family_runner(FAMILY.scoped_models, _SCOPED_MODEL_VERBS)
+
+
+# ---------------------------------------------------------------------------
+# Display-block helper
+# ---------------------------------------------------------------------------
+
+_BASE36_DIGITS: Final = "0123456789abcdefghijklmnopqrstuvwxyz"
+
+
+def _base36(value: int) -> str:
+    """Render a non-negative int in base 36 (TS ``Number.toString(36)``)."""
+    if value <= 0:
+        return "0"
+    digits: list[str] = []
+    while value:
+        value, rem = divmod(value, 36)
+        digits.append(_BASE36_DIGITS[rem])
+    return "".join(reversed(digits))
+
+
+def _now_ms() -> int:
+    """Epoch milliseconds (TS ``Date.now()``)."""
+    return int(time.time() * 1000)
+
+
+def _block(slug: str, title: str, markdown: str) -> UiDisplayBlock:
+    """Mint a display block with a fresh id and timestamp.
+
+    The framework's display-block surface carries a single markdown body
+    under the ``changelog`` kind, so every text panel the workbench drops —
+    the command palette, the hotkey map, and the changelog itself — rides
+    that one block kind with its own title. The id slug keeps successive
+    invocations distinct rows.
+
+    :param slug:     short id prefix identifying which panel this is
+    :param title:    the human-facing heading the block renders
+    :param markdown: the panel body, in markdown
+    """
+    return UiDisplayBlock(
+        id=f"{slug}-{_base36(_now_ms())}",
+        title=title,
+        markdown=markdown,
+        timestamp=_now_ms(),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Command palette (/help)
+# ---------------------------------------------------------------------------
+
+#: A zero-argument callable yielding the live slash catalog ``/help``
+#: renders — typically a closure over the console's assembled registry.
+HelpRegistryProvider: TypeAlias = Callable[[], Sequence[SlashCommand]]
+
+#: The late-bound catalog source. Installed once per console mount by the
+#: catalog assembler; ``None`` selects the static-groups fallback.
+_help_registry_provider: HelpRegistryProvider | None = None
+
+
+def set_help_registry_provider(provider: HelpRegistryProvider | None) -> None:
+    """Install the catalog source ``/help`` renders (``None`` restores the
+    static fallback — useful for tests). See the module docstring for why
+    this replaces the TS dynamic-import cycle-breaker."""
+    global _help_registry_provider
+    _help_registry_provider = provider
+
+
+def _help_catalog() -> Sequence[SlashCommand]:
+    """The catalog ``/help`` lists: the installed provider's registry when
+    one is bound, otherwise the static transcript + workbench groups."""
+    if _help_registry_provider is not None:
+        return _help_registry_provider()
+    return (*transcript_commands, *workbench_commands)
+
+
+def _help_block() -> UiDisplayBlock:
+    """Render the full flat command list as a markdown block.
+
+    Reads the live catalog through :func:`_help_catalog` so every command —
+    built-in and any dynamic skill/template rows spliced in at assembly
+    time — appears with its one-line summary.
+    """
+    catalog = _help_catalog()
+    lines = []
+    for command in catalog:
+        alts = f" _(/{', /'.join(command.aliases)})_" if command.aliases else ""
+        lines.append(f"- **/{command.name}**{alts} — {command.summary}")
+    body = "\n".join(
+        [f"{len(catalog)} commands available. Type `/` to complete.", "", *lines]
+    )
+    return _block("help", "Commands", body)
+
+
+# ---------------------------------------------------------------------------
+# Keyboard map (/keys)
+# ---------------------------------------------------------------------------
+
+#: The real keyboard shortcuts, grounded in the console keymap and surface.
+#: Each row is a ``(chord, effect)`` pair the hotkey block renders as a table.
+HOTKEYS: Final[tuple[tuple[str, str], ...]] = (
+    ("Enter", "Submit the current turn"),
+    ("Shift+Enter", "Insert a soft newline in the composer"),
+    ("Esc", "Dismiss an overlay / abort the in-flight turn"),
+    ("Esc Esc", "Open the transcript-tree navigator"),
+    ("Shift+Tab", "Step the reasoning-effort (thinking) level"),
+    ("Tab", "Accept the highlighted completion"),
+    ("Ctrl+C", "Interrupt the running turn"),
+    ("Ctrl+T", "Toggle reasoning / thinking rows"),
+    ("Ctrl+V", "Attach an image from the clipboard"),
+    ("Ctrl+G", "Edit the composer in your external editor"),
+    ("Ctrl+O", "Expand or collapse full tool output"),
+    ("Ctrl+L", "Open the model picker"),
+    ("Ctrl+R", "Open the session resume list"),
+    ("Ctrl+N / Ctrl+P", "Cycle the active model"),
+    ("Ctrl+A / Ctrl+E", "Jump to start / end of the line"),
+    ("Ctrl+U", "Clear the composer line (twice: exit)"),
+    ("Ctrl+J", "Insert a newline"),
+    ("Ctrl+Z", "Suspend the process"),
+    ("Alt+Up", "Pull the newest queued input back into the composer"),
+    ("! <cmd>", "Run a shell command (kept in context)"),
+    ("!! <cmd>", "Run a shell command (excluded from context)"),
+)
+
+
+def _hotkeys_block() -> UiDisplayBlock:
+    """Render the hotkey map as a markdown block."""
+    rows = [f"| `{chord}` | {effect} |" for chord, effect in HOTKEYS]
+    body = "\n".join(["| Shortcut | Action |", "| --- | --- |", *rows])
+    return _block("hotkeys", "Keyboard shortcuts", body)
+
+
+# ---------------------------------------------------------------------------
+# Changelog (/whats-new)
+# ---------------------------------------------------------------------------
+
+#: Candidate locations a project changelog may live at, relative to the cwd.
+_CHANGELOG_NAMES: Final[tuple[str, ...]] = (
+    "CHANGELOG.md",
+    "CHANGELOG",
+    "changelog.md",
+)
+
+#: The fallback body shown when no ``CHANGELOG.md`` is present on disk.
+_CHANGELOG_FALLBACK: Final = "\n".join(
+    [
+        "No `CHANGELOG.md` was found at the workspace root.",
+        "",
+        "Recent highlights in this build:",
+        "- Model and per-scope routing pickers reachable from the composer.",
+        "- `/help` and `/keys` render live command and shortcut references.",
+        "- Colour scheme switches inline between **midnight** and **daylight**.",
+    ]
+)
+
+
+def _read_changelog(cwd: str) -> str | None:
+    """Read the project changelog from disk, returning its markdown when one
+    of the candidate files is present and readable, or ``None`` when none is.
+
+    :param cwd: the workspace directory to resolve the candidates against
+    """
+    for name in _CHANGELOG_NAMES:
+        try:
+            text = Path(cwd, name).read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError):
+            # Not present or unreadable here — try the next candidate.
+            continue
+        if text.strip():
+            return text
+    return None
+
+
+async def _run_changelog(ctx: SlashContext) -> SlashOutcome:
+    """Drop the changelog block, reading a real ``CHANGELOG.md`` when present
+    and falling back to the build highlights otherwise."""
+    markdown = _read_changelog(os.getcwd())
+    ctx.append_block(
+        _block("changelog", "Changelog", markdown)
+        if markdown is not None
+        else _block("changelog", "What's new", _CHANGELOG_FALLBACK)
+    )
+    return HANDLED
+
+
+# ---------------------------------------------------------------------------
+# Diagnostics dump (/debug)
+# ---------------------------------------------------------------------------
+
+
+def _iso_now() -> str:
+    """UTC now in the TS ``Date.toISOString()`` shape (millisecond ``Z``)."""
+    return (
+        datetime.now(timezone.utc)
+        .isoformat(timespec="milliseconds")
+        .replace("+00:00", "Z")
+    )
+
+
+async def _run_debug(ctx: SlashContext) -> SlashOutcome:
+    """Write a JSONL diagnostics log for the active session and report its
+    path.
+
+    Each line is one JSON record: a header carrying the ``SessionStats``
+    tally plus the active model, followed by one record per live transcript
+    message (``role``/``content`` read via duck-typing and projected through
+    the one message⇄dict codec — plan cross-cutting rule 2). Writing it to a
+    fresh temp directory makes the dump a real artifact a user can open,
+    attach to a bug report, or ``tail``, rather than a transient toast. The
+    diagnostics view toggle is flipped as well so on-screen verbosity tracks
+    it.
+    """
+    ctx.dispatch({"type": "toggle:reasoning"})
+
+    stats = ctx.conductor.stats()
+    messages = ctx.conductor.messages()
+    snapshot = ctx.conductor.snapshot()
+
+    records: list[dict[str, object]] = [
+        {
+            "type": "session",
+            "at": _iso_now(),
+            "sessionId": stats.sessionId,
+            "modelId": snapshot.modelId,
+            "phase": snapshot.phase,
+            "stats": message_to_dict(stats),
+        }
+    ]
+    for index, message in enumerate(messages):
+        role = getattr(message, "role", None)
+        record: dict[str, object] = {
+            "type": "message",
+            "index": index,
+            "role": "unknown" if role is None else message_to_dict(role),
+        }
+        content = getattr(message, "content", None)
+        if content is not None:
+            # parity: JSON.stringify dropped an undefined `content` key.
+            record["content"] = message_to_dict(content)
+        records.append(record)
+    jsonl = "\n".join(json.dumps(record) for record in records) + "\n"
+
+    try:
+        directory = tempfile.mkdtemp(prefix="indus-debug-")
+        path = os.path.join(directory, f"session-{stats.sessionId or 'unknown'}.jsonl")
+        Path(path).write_text(jsonl, encoding="utf-8")
+        ctx.set_status(info(f"Diagnostics written to {path}"))
+    except Exception as cause:
+        ctx.set_status(warn(f"Could not write the diagnostics log ({cause})."))
+    return HANDLED
+
+
+# ---------------------------------------------------------------------------
+# Thin picker handlers
+# ---------------------------------------------------------------------------
+
+
+async def _run_model(ctx: SlashContext) -> SlashOutcome:
+    ctx.open_modal("models")
+    return HANDLED
+
+
+async def _run_settings(ctx: SlashContext) -> SlashOutcome:
+    ctx.open_modal("settings")
+    return HANDLED
+
+
+async def _run_help(ctx: SlashContext) -> SlashOutcome:
+    ctx.append_block(_help_block())
+    return HANDLED
+
+
+async def _run_keys(ctx: SlashContext) -> SlashOutcome:
+    ctx.append_block(_hotkeys_block())
+    return HANDLED
+
+
+# ---------------------------------------------------------------------------
+# The catalog
+# ---------------------------------------------------------------------------
+
+#: The workbench command rows, in listing order. Pickers and help surfaces
+#: open an overlay; the changelog drops a display block; debug flips a
+#: toggle and reports it.
+workbench_commands: list[SlashCommand] = [
+    SlashCommand(
+        name="model",
+        summary="Switch the model bound to this session",
+        run=_run_model,
+        aliases=("models",),
+    ),
+    SlashCommand(
+        name="models-for",
+        summary="Edit, show, or reset per-scope model routing",
+        run=_run_scoped_models,
+        aliases=("scoped-models",),
+        family=FAMILY.scoped_models,
+        takes_args=True,
+    ),
+    SlashCommand(
+        name="settings",
+        summary="Open the settings overlay",
+        run=_run_settings,
+    ),
+    SlashCommand(
+        name="help",
+        summary="List the available commands",
+        run=_run_help,
+        aliases=("?",),
+    ),
+    SlashCommand(
+        name="keys",
+        summary="Show the keyboard shortcut map",
+        run=_run_keys,
+        aliases=("hotkeys",),
+    ),
+    SlashCommand(
+        name="whats-new",
+        summary="Show what changed in this build",
+        run=_run_changelog,
+        aliases=("changelog",),
+    ),
+    SlashCommand(
+        name="debug",
+        summary="Write a session diagnostics log and toggle verbose view",
+        run=_run_debug,
+    ),
+]