induscode 0.1.0__py3-none-any.whl

induscode/boot/runners/oneshot_runner.py

@@ -0,0 +1,85 @@
+"""Runner: ``oneshot`` — single non-interactive request to stdout.
+
+Port of TS ``src/boot/runners/oneshot-runner.ts``. Drives the oneshot
+channel: it assembles a :class:`~induscode.conductor.SessionConductor` for
+the invocation, builds a :class:`~induscode.channels.ChannelContext` over the
+process stdout (clean text, or a streamed NDJSON event log), runs every
+prompt to settlement via :func:`~induscode.channels.run_oneshot`, and
+resolves the channel exit code. The output shape is NDJSON when the
+invocation carries a ``json`` flag, otherwise clean text.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import Final
+
+from induscode.channels import (
+    ChannelContext,
+    OneshotRequest,
+    OneshotShape,
+    WritableLine,
+    inert_dialog,
+    ndjson_framer,
+    run_oneshot,
+)
+
+from ..contract import BootContext, Invocation, Runner
+from .session import build_session_conductor, oneshot_prompts
+
+__all__ = ["oneshot_runner"]
+
+#: Exit code returned when no request text was supplied to run.
+_EXIT_NO_INPUT: Final[int] = 2
+
+
+class _Stdout:
+    """A :class:`~induscode.channels.WritableLine` backed by the process
+    standard output stream (flushed per chunk so a parent capturing the pipe
+    sees frames promptly)."""
+
+    def write(self, chunk: str) -> object:
+        sys.stdout.write(chunk)
+        sys.stdout.flush()
+        return True
+
+
+#: The shared stdout sink.
+STDOUT: Final[WritableLine] = _Stdout()
+
+
+def _shape_of(inv: Invocation) -> OneshotShape:
+    """Select the output shape: NDJSON when a ``json`` flag is set, else
+    clean text."""
+    raw = inv.flags.get("json")
+    return "ndjson" if raw is True or raw == "true" else "text"
+
+
+def _accepts(inv: Invocation) -> bool:
+    return inv.mode == "oneshot"
+
+
+async def _run(ctx: BootContext) -> int:
+    """Assemble the conductor and channel context, then delegate the run to
+    :func:`~induscode.channels.run_oneshot` and return its exit code. With no
+    request text it writes a short notice and exits non-zero rather than
+    mounting an empty run."""
+    prompts = oneshot_prompts(ctx)
+    if len(prompts) == 0:
+        sys.stderr.write("oneshot: no request text supplied\n")
+        return _EXIT_NO_INPUT
+
+    conductor = await build_session_conductor(ctx)
+    channel = ChannelContext(
+        conductor=conductor,
+        out=STDOUT,
+        framer=ndjson_framer,
+        dialog=inert_dialog,
+    )
+    request = OneshotRequest(shape=_shape_of(ctx.invocation), prompts=tuple(prompts))
+    return await run_oneshot(channel, request)
+
+
+#: The one-shot runner row: accepts invocations whose resolved mode is
+#: ``oneshot``.
+oneshot_runner: Final[Runner] = Runner(id="oneshot", accepts=_accepts, run=_run)

induscode/boot/runners/registry.py

@@ -0,0 +1,46 @@
+"""Runner registry — the table-driven replacement for a mode ``if/else``
+ladder.
+
+Port of TS ``src/boot/runners/registry.ts``. The boot pipeline ends by
+handing the resolved :class:`~..contract.Invocation` to exactly one
+:class:`~..contract.Runner`. Rather than branch on the mode string at the
+call site, dispatch is data: :data:`RUNNERS` lists every available runner in
+priority order, and :func:`select_runner` returns the first whose
+``accepts`` predicate matches. Adding or reordering modes is a one-line edit
+to the table, never a change to control flow.
+
+The interactive REPL is both first in the table and the guaranteed fallback:
+if no runner claims an invocation, :func:`select_runner` returns it, so a
+bare command line lands in the interactive session.
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+from ..contract import Invocation, Runner
+from .link_runner import link_runner
+from .oneshot_runner import oneshot_runner
+from .repl_runner import repl_runner
+
+__all__ = ["RUNNERS", "select_runner"]
+
+
+#: Every runner the boot layer can dispatch to, in match-priority order.
+#: :func:`select_runner` scans this list front-to-back and returns the first
+#: accepting runner; ``repl_runner`` leads the list and also serves as the
+#: default.
+RUNNERS: Final[tuple[Runner, ...]] = (repl_runner, oneshot_runner, link_runner)
+
+
+def select_runner(inv: Invocation) -> Runner:
+    """Choose the runner for a parsed invocation.
+
+    Returns the first runner in :data:`RUNNERS` that accepts the invocation;
+    if none does, falls back to the interactive REPL runner so dispatch is
+    total and a runner is always returned.
+    """
+    for runner in RUNNERS:
+        if runner.accepts(inv):
+            return runner
+    return repl_runner

induscode/boot/runners/repl_runner.py

@@ -0,0 +1,340 @@
+"""Runner: ``repl`` — interactive terminal session.
+
+Port of TS ``src/boot/runners/repl-runner.ts``. The runner performs
+everything that precedes the console mount, exactly as TS did:
+
+1. assemble the :class:`~induscode.conductor.SessionConductor`;
+2. honour ``--resume`` / ``--continue`` BEFORE mounting (so the console
+   renders the restored transcript from its first frame), degrading to a
+   fresh session on any failure;
+3. assemble the overlay service bundle (:class:`ReplServices` — the
+   preference store, the cwd-scoped session library, the credential vault,
+   and the launch sign-in helpers);
+4. hand everything to the **injectable console mount seam**.
+
+The mount seam (:data:`ConsoleMount`, swapped via :func:`set_console_mount`)
+defaults to the real M5 Textual console: the default mount projects the
+:class:`ReplServices` bundle onto the console's ``OverlayServices`` shape and
+awaits :func:`induscode.console.mount.mount_console` (imported lazily so the
+boot layer never pays the console import cost on headless paths). The seam
+stays injectable so tests can observe the assembled services or swap in a
+scripted surface.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any, Final
+
+from induscode.conductor import SessionConductor
+from induscode.launch import (
+    ResumeRef,
+    list_login_providers,
+    open_login_url,
+    pick_resume_target,
+    start_oauth_login,
+)
+from induscode.launch.contract import AuthVault
+from induscode.launch.pickers import ResumeDeps
+from induscode.sessions import SavedSession, SessionLibrary
+from induscode.settings import PreferenceStore
+
+from ..auth_vault import create_auth_vault
+from ..contract import BootContext, Invocation, Runner
+from .session import build_session_conductor, session_scope_dir
+
+__all__ = [
+    "ConsoleMount",
+    "ReplServices",
+    "repl_runner",
+    "set_console_mount",
+    "set_resume_deps",
+]
+
+
+# ---------------------------------------------------------------------------
+# Overlay services
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class ReplServices:
+    """The service bundle the interactive overlays drive (the TS
+    ``OverlayServices``, assembled here so M5's console receives everything
+    ready-made).
+
+    Everything is resolved from the boot context: the preference store and
+    session library from the workspace paths (and the run cwd for the
+    project tier), the credential vault from the resolved ``auth.json``
+    location, and the sign-in directory / OAuth flow from the launch layer.
+    The conductor is the live one the console renders.
+    """
+
+    #: The live session this console drives.
+    conductor: SessionConductor
+    #: Two-tier preference store (global + project tier for the run cwd).
+    settings: PreferenceStore
+    #: Session catalog scoped to the run cwd's sessions directory.
+    sessions: SessionLibrary
+    #: The merged sign-in directory lister.
+    list_login_providers: Callable[[], Any]
+    #: The browser sign-in flow.
+    start_oauth_login: Callable[..., Any]
+    #: The platform browser launcher.
+    open_login_url: Callable[[str], Any]
+    #: The disk credential vault.
+    vault: AuthVault
+
+
+def _build_services(ctx: BootContext, conductor: SessionConductor) -> ReplServices:
+    """Assemble the :class:`ReplServices` for a boot context and the live
+    conductor."""
+    cwd = ctx.invocation.cwd if ctx.invocation.cwd is not None else os.getcwd()
+    return ReplServices(
+        conductor=conductor,
+        settings=PreferenceStore.from_workspace(ctx.workspace, cwd),
+        sessions=SessionLibrary(
+            sessions_dir=session_scope_dir(ctx.workspace.sessions_dir, cwd)
+        ),
+        list_login_providers=list_login_providers,
+        start_oauth_login=start_oauth_login,
+        open_login_url=open_login_url,
+        vault=create_auth_vault(ctx.workspace.auth_path),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Console mount seam (M5 plugs in here)
+# ---------------------------------------------------------------------------
+
+#: The console mount: given the live conductor, the service bundle, and the
+#: optional initial input, render the interactive surface and resolve the
+#: process exit code once it is dismissed.
+ConsoleMount = Callable[[SessionConductor, ReplServices, "str | None"], Awaitable[int]]
+
+
+async def _default_console_mount(
+    conductor: SessionConductor,
+    services: ReplServices,
+    initial_input: str | None,
+) -> int:
+    """The default mount: the real M5 Textual console.
+
+    Projects the boot-layer :class:`ReplServices` bundle onto the console's
+    ``OverlayServices`` shape (field-for-field — the bundles were designed to
+    line up) and awaits the console mount. Imports are deferred so the boot
+    layer never pays the console (Textual) import cost on headless paths.
+    """
+    from induscode.console.contract import OverlayServices
+    from induscode.console.mount import mount_console
+
+    overlay_services = OverlayServices(
+        conductor=conductor,
+        settings=services.settings,
+        sessions=services.sessions,
+        list_login_providers=services.list_login_providers,
+        start_oauth_login=services.start_oauth_login,
+        open_login_url=services.open_login_url,
+        vault=services.vault,
+    )
+    return await mount_console(conductor, overlay_services, initial_input=initial_input)
+
+
+#: The active mount. Module-held so a test (or an alternative surface) can
+#: swap in a scripted console without touching the runner logic.
+_console_mount: ConsoleMount = _default_console_mount
+
+
+def set_console_mount(mount: ConsoleMount | None) -> None:
+    """Install the console mount the repl runner drives (``None`` restores
+    the real console default). Tests use this seam to observe the assembled
+    services or to stub the interactive surface."""
+    global _console_mount
+    _console_mount = mount if mount is not None else _default_console_mount
+
+
+# ---------------------------------------------------------------------------
+# Resume picker seam (the Textual startup picker plugs in here)
+# ---------------------------------------------------------------------------
+
+
+def _default_resume_deps() -> ResumeDeps:
+    """The live :class:`~induscode.launch.pickers.ResumeDeps` for the
+    interactive ``--resume`` picker: a real TTY probe plus a ``mount_picker``
+    that runs the framework Textual ``StartupSessionPicker`` (the same picker
+    the in-console ``/resume`` command reaches). The console module is
+    imported lazily so the boot layer never pays the Textual import cost on a
+    headless / non-interactive ``--resume`` path — the launch fast-path
+    resolves the newest session there without ever touching ``mount_picker``."""
+    from induscode.console.resume_picker import default_startup_resume_deps
+
+    return default_startup_resume_deps()
+
+
+#: The resume-deps factory the runner injects into ``pick_resume_target``.
+#: Module-held so a test can swap in a fake picker mount (and a fake TTY
+#: probe) without a terminal; ``None`` restores the live Textual default.
+_resume_deps_factory: Callable[[], ResumeDeps] = _default_resume_deps
+
+
+def set_resume_deps(factory: Callable[[], ResumeDeps] | None) -> None:
+    """Install the :class:`~induscode.launch.pickers.ResumeDeps` factory the
+    repl runner injects into the ``--resume`` picker (``None`` restores the
+    live Textual default). Tests use this seam to drive the picker over a fake
+    mount that returns a scripted selection, pinning that the raising launch
+    default is never reached on the interactive path."""
+    global _resume_deps_factory
+    _resume_deps_factory = factory if factory is not None else _default_resume_deps
+
+
+# ---------------------------------------------------------------------------
+# Resume handling
+# ---------------------------------------------------------------------------
+
+
+def _to_resume_ref(row: SavedSession) -> ResumeRef:
+    """Project a :class:`~induscode.sessions.SavedSession` catalog row onto
+    the framework ``SessionInfo`` the resume picker lists. The picker only
+    ever reads ``path`` / ``id`` / ``name`` / ``lastModified`` for display,
+    so the conversational counters and message text are filled defensively
+    from what the shallow row carries (zero / empty when it was not
+    deep-read), keeping the mapping total without re-opening every file."""
+    last_modified = row.lastModified if row.lastModified is not None else 0
+    stamp = datetime.fromtimestamp(last_modified / 1000, tz=timezone.utc)
+    return ResumeRef(
+        id=row.id,
+        path=row.path,
+        cwd="",
+        lastModified=int(last_modified),
+        created=stamp,
+        modified=stamp,
+        messageCount=row.messageCount if row.messageCount is not None else 0,
+        firstMessage=row.preview if row.preview is not None else "",
+        allMessagesText=row.preview if row.preview is not None else "",
+        name=row.name,
+        size=row.size,
+    )
+
+
+async def _choose_resume_target(
+    ctx: BootContext, library: SessionLibrary
+) -> str | None:
+    """Resolve the session id to resume for an invocation, or ``None`` for a
+    fresh session.
+
+    Mirrors how the in-app sessions overlay resumes: it hands
+    ``conductor.resume`` the bare session **id** (the filename stem the
+    store loads by), never a path. ``--continue`` takes the newest row from
+    the library's newest-first list; ``--resume`` runs the shared
+    :func:`~induscode.launch.pick_resume_target` picker over the same rows
+    and maps the chosen file path back to its originating id. Either flag
+    yielding nothing resolves to ``None``.
+    """
+    inv = ctx.invocation
+
+    if inv.continue_latest is True:
+        # The library lists newest-first, so the head row is the most recent
+        # session in the cwd; resume by its bare id exactly as the overlay
+        # does.
+        rows = await library.list()
+        return rows[0].id if len(rows) > 0 else None
+
+    # `--resume`: list once, project to the picker's ResumeRef shape, and
+    # keep a path→id index so the chosen file path can be mapped back to the
+    # id the conductor resumes by. The two loaders share the one list (the
+    # library is already scoped to the cwd's sessions dir).
+    rows = await library.list()
+    if len(rows) == 0:
+        return None
+    refs = [_to_resume_ref(row) for row in rows]
+    id_by_path = {row.path: row.id for row in rows}
+
+    async def load() -> list[ResumeRef]:
+        return refs
+
+    # Inject the Textual-backed resume deps so the interactive picker actually
+    # mounts (the launch default's `mount_picker` raises by design — the
+    # console runner owns the live mount). The non-TTY fast path inside
+    # `pick_resume_target` short-circuits to the newest session before
+    # `mount_picker` is ever called, so these deps' picker is reached only on
+    # a real terminal.
+    outcome = await pick_resume_target(load, load, _resume_deps_factory())
+    if outcome.fault is not None:
+        cause = outcome.fault.cause
+        if isinstance(cause, BaseException):
+            raise cause
+        raise RuntimeError(outcome.fault.message)
+    if outcome.path is None:
+        return None
+    return id_by_path.get(outcome.path)
+
+
+async def _apply_resume(ctx: BootContext, conductor: SessionConductor) -> None:
+    """Honour ``--resume`` / ``--continue`` before the console mounts.
+
+    No-op unless one of the flags is set. Picks the target session id, then
+    asks the live conductor to resume it. A failure (load, picker mount, or
+    resume) degrades to the fresh session the conductor already holds — a
+    one-line stderr notice is printed and the launch continues rather than
+    crashing. Selecting nothing also falls through to fresh.
+    """
+    inv = ctx.invocation
+    if inv.resume is not True and inv.continue_latest is not True:
+        return
+
+    library = SessionLibrary(
+        sessions_dir=session_scope_dir(
+            ctx.workspace.sessions_dir,
+            inv.cwd if inv.cwd is not None else os.getcwd(),
+        )
+    )
+    try:
+        session_id = await _choose_resume_target(ctx, library)
+        if session_id is None:
+            sys.stderr.write("No prior session to resume; starting a fresh one.\n")
+            return
+        await conductor.resume(session_id)
+        # `conductor.resume` swallows a missing-session load into a typed
+        # fault on its signal stream rather than raising; detect that so a
+        # stale id still falls back to fresh instead of mounting onto a
+        # faulted state.
+        state = conductor.snapshot()
+        if state.phase == "faulted":
+            sys.stderr.write(
+                f'Could not resume session "{session_id}"; starting a fresh one.\n'
+            )
+    except Exception as cause:  # noqa: BLE001 — degrade to a fresh session
+        detail = str(cause) if str(cause) else type(cause).__name__
+        sys.stderr.write(f"Resume failed ({detail}); starting a fresh session.\n")
+
+
+# ---------------------------------------------------------------------------
+# The runner
+# ---------------------------------------------------------------------------
+
+
+def _accepts(inv: Invocation) -> bool:
+    return inv.mode == "repl"
+
+
+async def _run(ctx: BootContext) -> int:
+    """Assemble the conductor, honour ``--resume`` / ``--continue``, and
+    mount the (injectable) console."""
+    conductor = await build_session_conductor(ctx)
+    # Resume a prior session BEFORE wiring services / mounting, so the
+    # console renders the restored transcript from its first frame. A resume
+    # failure is handled inside `_apply_resume`, which leaves the fresh
+    # session in place.
+    await _apply_resume(ctx, conductor)
+    services = _build_services(ctx, conductor)
+    return await _console_mount(conductor, services, ctx.invocation.prompt)
+
+
+#: The interactive-REPL runner row: matches invocations whose resolved mode
+#: is ``repl``; it is also the registry default, so it is reached for the
+#: empty / interactive command line.
+repl_runner: Final[Runner] = Runner(id="repl", accepts=_accepts, run=_run)