induscode 0.1.0__py3-none-any.whl

induscode/launch/packages.py

@@ -0,0 +1,299 @@
+"""Package command — :func:`run_package_command`.
+
+The top-level ``install`` / ``remove`` / ``update`` / ``list`` / ``config``
+surface that manages the extension-package sources the launcher loads. A
+source is a plain string the loader understands — an ``npm:`` spec, a
+``git:`` / ``https:`` repo, or a bare local path — and the configured set
+lives in the user settings under the ``extensionPackages`` key, persisted
+through the :class:`~induscode.settings.PreferenceStore`.
+
+The command owns the first positional token only: it returns
+``handled=False`` when that token is not one of the recognised subcommands,
+so the orchestrator can call this first and fall through to a normal launch
+on a miss. It never raises for an expected failure — a bad argument is
+reported as a printed line and a non-zero :attr:`PackageResult.code`.
+
+I/O is injected. The default :class:`PackageIo` wraps stdout / stderr, but
+tests drive the whole flow over an in-memory stand-in and a store pinned to a
+temp directory, so the real home is never touched.
+
+(Port of TS ``src/launch/packages.ts``.)
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Final, Literal, Protocol, TypeAlias
+
+from ..settings import FIELD_TO_JSON_KEY, SETTING_KEYS, PreferenceStore
+
+__all__ = [
+    "PACKAGE_COMMANDS",
+    "PackageCommand",
+    "PackageIo",
+    "PackageResult",
+    "default_package_io",
+    "run_package_command",
+]
+
+
+# ---------------------------------------------------------------------------
+# Subcommand vocabulary
+# ---------------------------------------------------------------------------
+
+#: The five subcommands the package command recognises as the first token.
+PackageCommand: TypeAlias = Literal["install", "remove", "update", "list", "config"]
+
+#: Every :data:`PackageCommand`, as a frozen tuple for membership tests.
+PACKAGE_COMMANDS: Final[tuple[PackageCommand, ...]] = (
+    "install",
+    "remove",
+    "update",
+    "list",
+    "config",
+)
+
+
+def _as_package_command(token: str | None) -> PackageCommand | None:
+    """Narrow an arbitrary token to a known :data:`PackageCommand`."""
+    if token is not None and token in PACKAGE_COMMANDS:
+        return token  # type: ignore[return-value]  # narrowed by membership
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Injected I/O
+# ---------------------------------------------------------------------------
+
+
+class PackageIo(Protocol):
+    """The console seam the package command writes through. Pinned to a
+    normal line and an error line so a test can capture both streams without a
+    real terminal."""
+
+    def print(self, line: str) -> None:
+        """Emit one line of human-facing text to the standard stream."""
+        ...
+
+    def print_error(self, line: str) -> None:
+        """Emit one line to the error stream."""
+        ...
+
+
+class _DefaultPackageIo:
+    """The default :class:`PackageIo` backed by stdout / stderr."""
+
+    def print(self, line: str) -> None:
+        sys.stdout.write(line if line.endswith("\n") else f"{line}\n")
+
+    def print_error(self, line: str) -> None:
+        sys.stderr.write(line if line.endswith("\n") else f"{line}\n")
+
+
+def default_package_io() -> PackageIo:
+    """Build the live terminal-backed :class:`PackageIo`."""
+    return _DefaultPackageIo()
+
+
+# ---------------------------------------------------------------------------
+# Command surface
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class PackageResult:
+    """The outcome of :func:`run_package_command`.
+
+    :attr:`handled` reports whether the first token was a recognised
+    subcommand; when ``False``, the caller proceeds to a normal launch
+    unchanged. :attr:`code` is the process exit code for a handled command —
+    zero on success, non-zero when a required argument was missing or
+    invalid."""
+
+    # Whether this invocation was a package subcommand.
+    handled: bool
+    # The subcommand that ran, when handled is True.
+    command: PackageCommand | None = None
+    # Process exit code for a handled command (zero on success).
+    code: int | None = None
+
+
+#: The settings key the configured package sources are stored under.
+_PACKAGES_KEY: Final[str] = "extensionPackages"
+
+
+def _source_key(source: str) -> str:
+    """Classify a source for equality so two spellings of the same package
+    compare equal: an ``npm:`` spec ignores any trailing ``@version``, a git
+    url drops its scheme and ``.git`` suffix, and a local path matches
+    verbatim."""
+    trimmed = source.strip()
+    if trimmed.startswith("npm:"):
+        spec = trimmed[len("npm:") :]
+        at = spec.rfind("@")
+        # Keep a leading scope `@`; only a later `@` marks a version.
+        name = spec[:at] if at > 0 else spec
+        return f"npm:{name}"
+    gitlike = (
+        trimmed.startswith("git:")
+        or trimmed.startswith("http://")
+        or trimmed.startswith("https://")
+    )
+    if gitlike:
+        without_scheme = re.sub(r"^git:", "", trimmed)
+        without_scheme = re.sub(r"^https?://", "", without_scheme)
+        without_version = without_scheme.split("@")[0]
+        without_suffix = re.sub(r"\.git$", "", without_version)
+        return f"git:{without_suffix}"
+    return f"local:{trimmed}"
+
+
+def _sources_match(a: str, b: str) -> bool:
+    """Whether two sources name the same package under :func:`_source_key`."""
+    return _source_key(a) == _source_key(b)
+
+
+def _read_sources(store: PreferenceStore) -> list[str]:
+    """Read the configured package sources from the resolved settings."""
+    value = store.get(_PACKAGES_KEY)
+    return [str(item) for item in value] if isinstance(value, (list, tuple)) else []
+
+
+def _write_sources(store: PreferenceStore, sources: list[str]) -> None:
+    """Persist a package-source list through the store's project tier."""
+    store.set(_PACKAGES_KEY, sources)
+    store.save()
+
+
+def _read_source(rest: Sequence[str]) -> str | None:
+    """Pull the source argument from a subcommand tail, skipping any switches.
+    The first bare (non-``-``) token is the source."""
+    return next((token for token in rest if not token.startswith("-")), None)
+
+
+async def run_package_command(
+    argv: Sequence[str],
+    *,
+    store: PreferenceStore,
+    io: PackageIo | None = None,
+) -> PackageResult:
+    """Run the package command.
+
+    Returns ``handled=False`` immediately when ``argv[0]`` is not a recognised
+    subcommand, so the orchestrator can call this first and fall through on a
+    miss. Otherwise it performs the subcommand against the injected store and
+    resolves a :class:`PackageResult` — never raising for an expected failure.
+
+    :param argv: the raw token list following the program name
+    :param store: the settings store the package sources read from / write to
+    :param io: the console seam; defaults to stdout / stderr
+    """
+    command = _as_package_command(argv[0] if len(argv) > 0 else None)
+    if command is None:
+        return PackageResult(handled=False)
+
+    live_io = io if io is not None else default_package_io()
+    rest = list(argv[1:])
+
+    match command:
+        case "install":
+            return _do_install(rest, store, live_io)
+        case "remove":
+            return _do_remove(rest, store, live_io)
+        case "update":
+            return _do_update(store, live_io)
+        case "list":
+            return _do_list(store, live_io)
+        case "config":
+            return _do_config(store, live_io)
+
+
+def _do_install(
+    rest: Sequence[str], store: PreferenceStore, io: PackageIo
+) -> PackageResult:
+    """Add a package source to the configured set (idempotent under
+    :func:`_sources_match`)."""
+    source = _read_source(rest)
+    if source is None:
+        io.print_error(
+            "install: a package source is required (npm:, git:, https:, or a local path)."
+        )
+        return PackageResult(handled=True, command="install", code=1)
+
+    sources = _read_sources(store)
+    if any(_sources_match(existing, source) for existing in sources):
+        io.print(f"Already installed: {source}")
+        return PackageResult(handled=True, command="install", code=0)
+
+    _write_sources(store, [*sources, source])
+    io.print(f"Installed {source}")
+    return PackageResult(handled=True, command="install", code=0)
+
+
+def _do_remove(
+    rest: Sequence[str], store: PreferenceStore, io: PackageIo
+) -> PackageResult:
+    """Remove a package source from the configured set."""
+    source = _read_source(rest)
+    if source is None:
+        io.print_error("remove: a package source is required.")
+        return PackageResult(handled=True, command="remove", code=1)
+
+    sources = _read_sources(store)
+    remaining = [existing for existing in sources if not _sources_match(existing, source)]
+    if len(remaining) == len(sources):
+        io.print_error(f"remove: not installed: {source}")
+        return PackageResult(handled=True, command="remove", code=1)
+
+    _write_sources(store, remaining)
+    io.print(f"Removed {source}")
+    return PackageResult(handled=True, command="remove", code=0)
+
+
+def _do_update(store: PreferenceStore, io: PackageIo) -> PackageResult:
+    """Re-read the configured sources and report them. The launcher resolves
+    package sources lazily at startup, so there is no separate fetch step to
+    drive here: ``update`` re-reads the persisted set and confirms what is
+    configured."""
+    store.reload()
+    sources = _read_sources(store)
+    if not sources:
+        io.print("No packages to update.")
+        return PackageResult(handled=True, command="update", code=0)
+    plural = "" if len(sources) == 1 else "s"
+    io.print(f"Refreshed {len(sources)} package source{plural}.")
+    for source in sources:
+        io.print(f"  {source}")
+    return PackageResult(handled=True, command="update", code=0)
+
+
+def _do_list(store: PreferenceStore, io: PackageIo) -> PackageResult:
+    """Print the configured package sources."""
+    sources = _read_sources(store)
+    if not sources:
+        io.print("No packages installed.")
+        return PackageResult(handled=True, command="list", code=0)
+    io.print("Installed packages:")
+    for source in sources:
+        io.print(f"  {source}")
+    return PackageResult(handled=True, command="list", code=0)
+
+
+def _do_config(store: PreferenceStore, io: PackageIo) -> PackageResult:
+    """Print the resolved settings file locations and their merged contents
+    (camelCase JSON keys, matching the on-disk spelling)."""
+    locations = store.paths()
+    io.print(f"Global settings: {locations.global_path}")
+    io.print(f"Project settings: {locations.project_path}")
+    io.print("Resolved settings:")
+    snapshot = store.snapshot()
+    payload = {
+        FIELD_TO_JSON_KEY.get(field, field): getattr(snapshot, field)
+        for field in SETTING_KEYS
+    }
+    io.print(json.dumps(payload, indent=2, default=list))
+    return PackageResult(handled=True, command="config", code=0)

induscode/launch/pickers.py

@@ -0,0 +1,291 @@
+"""Launch pickers — :func:`pick_resume_target` and :func:`browse_settings`.
+
+Two thin, injectable selection surfaces:
+
+- :func:`pick_resume_target` loads the resumable sessions (current cwd plus
+  every directory), de-duplicates by path, sorts newest-first, and lets the
+  user choose one through an injectable picker. On a non-interactive stdin it
+  skips the picker and resolves the newest session, so a piped invocation
+  still resumes deterministically.
+
+- :func:`browse_settings` prints a plain listing of the resolved settings and
+  the discovered user resources, then waits for a keypress. No TUI — a flat
+  console dump the user reads and dismisses.
+
+Both keep their effectful pieces (the picker mount, the input pause, the TTY
+probe) behind injectable seams so the selection logic is unit-testable without
+a terminal.
+
+Port notes
+----------
+- The TS picker mounted the framework React-Ink ``StartupSessionPicker``. The
+  Python framework's picker is a Textual screen
+  (``indusagi.react_ink.components.dialogs.startup_picker``) that must live
+  inside a running Textual app. The **default** :class:`ResumeDeps` in this
+  module keeps the live TTY probe but its ``mount_picker`` raises by design —
+  the launch layer is terminal-agnostic and owns no Textual mount. The boot
+  ``repl_runner`` injects a Textual-backed :class:`ResumeDeps`
+  (``induscode.console.resume_picker.default_startup_resume_deps``) that runs
+  the real picker before the console mounts, so ``pindus --resume`` on a TTY
+  shows the session list and resumes the chosen session — the same UX the TS
+  Ink mount gave. The **non-TTY newest-session fast path is fully live** and
+  is what oneshot/link runs exercise; it never reaches ``mount_picker``.
+
+(Port of TS ``src/launch/pickers.ts``.)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Protocol
+
+from .contract import (
+    ResumeFault,
+    ResumeRef,
+    SessionLoader,
+    SettingsBrowseOptions,
+)
+
+__all__ = [
+    "ResumeDeps",
+    "ResumeOutcome",
+    "SettingsBrowseIo",
+    "browse_settings",
+    "default_resume_deps",
+    "default_settings_browse_io",
+    "merge_sessions",
+    "pick_resume_target",
+    "render_settings_listing",
+]
+
+
+# ---------------------------------------------------------------------------
+# Resume picker
+# ---------------------------------------------------------------------------
+
+
+class ResumeDeps(Protocol):
+    """The effectful seams :func:`pick_resume_target` depends on. Injected so
+    a test can report a non-interactive terminal and stub the picker mount."""
+
+    def is_interactive(self) -> bool:
+        """Whether stdin is an interactive terminal (drives the non-TTY
+        fast-path)."""
+        ...
+
+    async def mount_picker(
+        self, sessions: Sequence[ResumeRef], total_count: int
+    ) -> ResumeRef | None:
+        """Mount the picker over the session list and resolve with the chosen
+        session, or ``None`` when the user dismisses it."""
+        ...
+
+
+@dataclass(frozen=True, slots=True)
+class _DefaultResumeDeps:
+    """The launch-layer default :class:`ResumeDeps`: a real TTY probe; the
+    picker mount is the console runner's seam (see the module docstring) and
+    raises because the launch layer owns no Textual mount. The boot
+    ``repl_runner`` injects a Textual-backed :class:`ResumeDeps` on the
+    interactive path, so this raising mount is reached only when a caller
+    drives an interactive resume *without* supplying real deps."""
+
+    def is_interactive(self) -> bool:
+        return bool(sys.stdin.isatty() and sys.stdout.isatty())
+
+    async def mount_picker(
+        self, sessions: Sequence[ResumeRef], total_count: int
+    ) -> ResumeRef | None:
+        del sessions, total_count
+        # The Textual StartupSessionPicker must run inside an app; the repl
+        # runner supplies real deps for that. Raising here lands in
+        # pick_resume_target's typed-fault fallback, matching the TS behaviour
+        # for a picker that fails to mount.
+        raise RuntimeError(
+            "The interactive session picker is wired by the console runner."
+        )
+
+
+def default_resume_deps() -> ResumeDeps:
+    """Build the live :class:`ResumeDeps` (TTY probe + console-owned picker
+    seam)."""
+    return _DefaultResumeDeps()
+
+
+def merge_sessions(
+    current: Sequence[ResumeRef],
+    all_sessions: Sequence[ResumeRef],
+) -> list[ResumeRef]:
+    """Merge two session lists into one newest-first list de-duplicated by
+    path.
+
+    Earlier entries win the path key, then the merged set is sorted by
+    ``lastModified`` descending. Pure; the picker and the fast-path both
+    consume it."""
+    by_path: dict[str, ResumeRef] = {}
+    for session in [*current, *all_sessions]:
+        if session.path not in by_path:
+            by_path[session.path] = session
+    return sorted(by_path.values(), key=lambda s: s.lastModified, reverse=True)
+
+
+@dataclass(frozen=True, slots=True)
+class ResumeOutcome:
+    """The outcome of :func:`pick_resume_target`: the chosen session path, or
+    ``None`` when there was nothing to resume or the user dismissed the
+    picker. A typed :class:`~.contract.ResumeFault` is returned (never
+    raised) when the load or mount failed."""
+
+    # The selected session file path, or None for none.
+    path: str | None
+    # A typed failure, present only when the resume flow could not run.
+    fault: ResumeFault | None = None
+
+
+async def pick_resume_target(
+    load_current: SessionLoader,
+    load_all: SessionLoader,
+    deps: ResumeDeps | None = None,
+) -> ResumeOutcome:
+    """Choose a session to resume.
+
+    Loads the current-directory and all-directory session lists, merges them
+    (de-dupe by path, newest first), and either mounts the injected picker or
+    — on a non-interactive stdin — resolves the newest session directly. An
+    empty merged list resolves to ``ResumeOutcome(path=None)``.
+
+    :param load_current: loader for sessions started in the active cwd
+    :param load_all: loader for sessions across every directory
+    :param deps: injectable TTY probe and picker mount (defaults to live)
+    """
+    live_deps = deps if deps is not None else default_resume_deps()
+    try:
+        current, all_sessions = await asyncio.gather(load_current(), load_all())
+    except Exception as cause:
+        return ResumeOutcome(
+            path=None,
+            fault=ResumeFault(message="Failed to load resumable sessions.", cause=cause),
+        )
+
+    sessions = merge_sessions(current, all_sessions)
+    if not sessions:
+        return ResumeOutcome(path=None)
+
+    if not live_deps.is_interactive():
+        return ResumeOutcome(path=sessions[0].path)
+
+    try:
+        chosen = await live_deps.mount_picker(sessions, len(sessions))
+        return ResumeOutcome(path=None if chosen is None else chosen.path)
+    except Exception as cause:
+        return ResumeOutcome(
+            path=None,
+            fault=ResumeFault(message="The session picker failed to start.", cause=cause),
+        )
+
+
+# ---------------------------------------------------------------------------
+# Settings browser
+# ---------------------------------------------------------------------------
+
+
+class SettingsBrowseIo(Protocol):
+    """The effectful seams :func:`browse_settings` depends on: a line sink and
+    a pause that waits for the user to press a key. Injected so a test
+    captures the listing and resolves the pause immediately."""
+
+    def print(self, line: str) -> None:
+        """Emit one line of the listing."""
+        ...
+
+    async def pause(self, prompt: str) -> None:
+        """Wait for the user to dismiss the listing (e.g. press Enter)."""
+        ...
+
+
+class _DefaultSettingsBrowseIo:
+    """The live :class:`SettingsBrowseIo`: stdout plus an :func:`input`
+    pause."""
+
+    def print(self, line: str) -> None:
+        sys.stdout.write(line if line.endswith("\n") else line + "\n")
+
+    async def pause(self, prompt: str) -> None:
+        await asyncio.to_thread(input, prompt)
+
+
+def default_settings_browse_io() -> SettingsBrowseIo:
+    """Build the live stdout/input-backed :class:`SettingsBrowseIo`."""
+    return _DefaultSettingsBrowseIo()
+
+
+def _render_section(title: str, paths: Sequence[str]) -> list[str]:
+    """Build the listing lines for one named resource category. Pure."""
+    if not paths:
+        return [f"{title}: (none)"]
+    return [f"{title}:", *(f"  - {path}" for path in paths)]
+
+
+def render_settings_listing(opts: SettingsBrowseOptions) -> list[str]:
+    """Build the entire settings listing as a list of lines. Pure — it
+    consumes the resolved settings, the active cwd, the profile directory, and
+    the grouped resource paths, and produces the flat dump
+    :func:`browse_settings` prints. Kept separate so a test can assert the
+    content without an io seam."""
+    lines: list[str] = []
+    lines.append("Configuration")
+    lines.append(f"  Working directory: {opts.cwd}")
+    lines.append(f"  Profile directory: {opts.profile_dir}")
+    lines.append("")
+
+    lines.append("Settings")
+    default_model = (
+        opts.settings.default_model
+        if opts.settings.default_model is not None
+        else "(unset)"
+    )
+    lines.append(f"  Default model: {default_model}")
+    lines.append(
+        "  System prompt: "
+        + ("(custom)" if opts.settings.system_prompt is not None else "(default)")
+    )
+    servers = opts.settings.mcp_servers
+    server_count = len(servers) if servers is not None else 0
+    lines.append(f"  MCP servers: {server_count}")
+    lines.append("")
+
+    categories = sorted(opts.resolved_paths.keys())
+    if not categories:
+        lines.append("Resources: (none discovered)")
+    else:
+        lines.append("Resources")
+        for category in categories:
+            lines.extend(
+                _render_section(f"  {category}", list(opts.resolved_paths[category]))
+            )
+
+    return lines
+
+
+async def browse_settings(
+    opts: SettingsBrowseOptions,
+    io: SettingsBrowseIo | None = None,
+) -> None:
+    """Print the settings / resource listing and wait for the user to dismiss
+    it.
+
+    A plain console dump — no TUI. It renders the resolved settings summary
+    and the discovered resources grouped by category, then pauses for a
+    keypress so the listing stays on screen.
+
+    :param opts: the resolved settings, resource paths, cwd, and profile dir
+    :param io: the injectable line sink and pause (defaults to stdout + input)
+    """
+    live_io = io if io is not None else default_settings_browse_io()
+    for line in render_settings_listing(opts):
+        live_io.print(line)
+    live_io.print("")
+    await live_io.pause("Press Enter to continue. ")