induscode 0.1.0__py3-none-any.whl

induscode/addons/loader.py

@@ -0,0 +1,314 @@
+"""Addon loader — the SINGLE importlib-backed :class:`ModuleLoader`.
+
+This module turns a path on disk into a loaded :class:`AddonManifest`. It is
+the one place the app dynamically imports user code.
+
+Port note — the jiti / virtual-module machinery is DROPPED
+----------------------------------------------------------
+The TS ``sandbox.ts`` existed to solve two Node-shaped problems:
+
+1. **TypeScript on the fly** — addons shipped as ``.ts`` and needed jiti to
+   transpile them at load time. Python addons are plain ``.py`` source; the
+   standard ``importlib`` machinery loads them directly.
+2. **A compiled binary has no ``node_modules``** — an addon's
+   ``import "indusagi/agent"`` could not resolve against the filesystem, so
+   jiti bridged the ``BUNDLED_NAMESPACES`` as virtual modules (or resolved
+   aliases under Node). In Python the ``indusagi`` framework (and
+   ``induscode`` itself) are ordinary installed packages on ``sys.path``, so
+   a plain ``import indusagi.agent`` inside an addon **just works** — no
+   bridge, no alias map, no namespace objects. ``BUNDLED_NAMESPACES`` is kept
+   in the contract as vestigial vocabulary only.
+
+What survives verbatim is the loader's input-hygiene story: the
+:func:`scrub_invisible` invisible-codepoint scrub (the explicit, auditable
+list — not an opaque regex class), :func:`expand_path` home expansion, and
+the :func:`resolve_path` normalizer every loader entry funnels through.
+
+Cache behavior parity: jiti ran with ``moduleCache: false`` so re-loading an
+edited addon during a session picked up the new source. The importlib loader
+mirrors that by executing every load under a **fresh synthetic module name**
+(a process-wide counter), so a repeated ``load`` of the same path re-executes
+the file instead of returning a stale cached module. The synthetic module is
+left registered in ``sys.modules`` (modules must be importable by name while
+executing — dataclasses, ``__package__`` machinery — and unregistering would
+break later introspection of live objects).
+
+The loader is deliberately injectable: :func:`create_module_loader` is the
+default :class:`ModuleLoader`, but every consumer takes the Protocol, so a
+test can inject a scripted fake that returns a manifest with no import and no
+disk.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import itertools
+import os
+import re
+import sys
+from dataclasses import dataclass
+from types import ModuleType
+
+from .contract import AddonManifest, ModuleLoader
+from .manifest import PACKAGE_ENTRY
+
+__all__ = [
+    "create_module_loader",
+    "expand_path",
+    "resolve_path",
+    "scrub_invisible",
+]
+
+
+# ---------------------------------------------------------------------------
+# Path hygiene — invisible-whitespace scrub + home expansion
+# ---------------------------------------------------------------------------
+
+#: Code points that render as whitespace (or nothing) yet are not the plain
+#: ASCII space/tab/newline a path is expected to contain. A path string copied
+#: out of a rich text source, a chat message, or a terminal can carry these
+#: invisibly, which makes an otherwise-correct path fail to resolve. This set
+#: is kept as an explicit, auditable list (verbatim from the TS lineage)
+#: rather than a single opaque regex class.
+#:
+#: - ``U+00A0`` no-break space
+#: - ``U+200B``–``U+200D`` zero-width space / non-joiner / joiner
+#: - ``U+200E`` / ``U+200F`` left-to-right / right-to-left marks
+#: - ``U+2060`` word joiner
+#: - ``U+FEFF`` zero-width no-break space (BOM)
+#: - the ``U+2000``–``U+200A`` range of fixed-width typographic spaces
+#: - ``U+202F`` narrow no-break space, ``U+205F`` medium mathematical space
+#: - ``U+3000`` ideographic space
+_INVISIBLE_CODE_POINTS: tuple[int, ...] = (
+    0x00A0, 0x200B, 0x200C, 0x200D, 0x200E, 0x200F, 0x2060, 0xFEFF, 0x202F,
+    0x205F, 0x3000,
+    # U+2000 … U+200A inclusive
+    0x2000, 0x2001, 0x2002, 0x2003, 0x2004, 0x2005, 0x2006, 0x2007, 0x2008,
+    0x2009, 0x200A,
+)
+
+#: The invisible code points as a fast-membership set, computed once.
+_INVISIBLE_SET: frozenset[int] = frozenset(_INVISIBLE_CODE_POINTS)
+
+
+def scrub_invisible(raw: str) -> str:
+    """Strip invisible / non-standard whitespace from a path string and trim
+    ordinary leading and trailing whitespace.
+
+    Walks the string by code point (so astral characters survive intact),
+    dropping any member of the invisible set, then trims the edges. Written
+    as an explicit scan rather than a regex so the exact handled set is
+    visible at the call site.
+
+    :param raw: the path as supplied (possibly carrying invisible characters)
+    """
+    out = "".join(char for char in raw if ord(char) not in _INVISIBLE_SET)
+    return out.strip()
+
+
+def expand_path(raw: str, home: str | None = None) -> str:
+    """Expand a leading ``~`` (or ``~/``) to the user's home directory.
+
+    Only a ``~`` that begins the (already-scrubbed) string is treated as the
+    home marker; a ``~`` anywhere else is an ordinary character. ``~`` alone
+    becomes the home directory; ``~/x`` becomes ``<home>/x``. A ``home``
+    override is accepted for tests and embedding so the function never reads
+    the environment implicitly when one is supplied.
+
+    :param raw: the path, possibly beginning with a home marker
+    :param home: the home directory to expand against; defaults to the user's
+    """
+    resolved_home = home if home is not None else os.path.expanduser("~")
+    cleaned = scrub_invisible(raw)
+    if cleaned == "~":
+        return resolved_home
+    if cleaned.startswith("~/") or cleaned.startswith("~\\"):
+        return resolved_home + cleaned[1:]
+    return cleaned
+
+
+def resolve_path(raw: str, base: str | None = None, home: str | None = None) -> str:
+    """Resolve a path to an absolute, invisible-free path.
+
+    Scrubs invisible whitespace, expands a leading home marker, then anchors
+    the result against ``base`` (the working directory) when it is not
+    already absolute. The single normalizer every loader entry funnels
+    through, so input hygiene is applied in exactly one place.
+
+    :param raw: the path as supplied
+    :param base: the directory a relative path resolves against; defaults to
+        the process working directory
+    :param home: the home directory ``~`` expands against; defaults to the user's
+    """
+    expanded = expand_path(raw, home)
+    if os.path.isabs(expanded):
+        return os.path.normpath(expanded)
+    base_dir = base if base is not None else os.getcwd()
+    return os.path.abspath(os.path.join(base_dir, expanded))
+
+
+# ---------------------------------------------------------------------------
+# importlib spec loading
+# ---------------------------------------------------------------------------
+
+#: Process-wide counter minting a fresh synthetic module name per load — the
+#: Python analogue of jiti's ``moduleCache: false`` (an edited addon re-loads
+#: from its new source instead of a stale ``sys.modules`` hit).
+_LOAD_SEQ = itertools.count()
+
+
+def _module_name_for(absolute: str) -> str:
+    """A unique, importable synthetic module name for one load of ``absolute``.
+
+    Carries the sanitized file stem (or the enclosing package name for an
+    ``__init__.py`` entry) for readable tracebacks, plus the load sequence so
+    repeated loads never collide.
+    """
+    stem = os.path.splitext(os.path.basename(absolute))[0]
+    if stem == "__init__":
+        stem = os.path.basename(os.path.dirname(absolute))
+    safe = re.sub(r"[^0-9A-Za-z_]", "_", stem) or "addon"
+    return f"_induscode_addon_{next(_LOAD_SEQ)}_{safe}"
+
+
+def _import_module(absolute: str) -> ModuleType:
+    """Spec-load the module file at ``absolute`` under a fresh synthetic name.
+
+    A :data:`PACKAGE_ENTRY` (``__init__.py``) is loaded as a package (its
+    directory becomes the submodule search path, so intra-package imports
+    work); any other ``.py`` file is a plain module. Raises on any import
+    failure — the host converts the raise into a ``load`` fault.
+    """
+    name = _module_name_for(absolute)
+    if os.path.basename(absolute) == PACKAGE_ENTRY:
+        spec = importlib.util.spec_from_file_location(
+            name,
+            absolute,
+            submodule_search_locations=[os.path.dirname(absolute)],
+        )
+    else:
+        spec = importlib.util.spec_from_file_location(name, absolute)
+    if spec is None or spec.loader is None:
+        raise ImportError(f"cannot build an import spec for {absolute}")
+    module = importlib.util.module_from_spec(spec)
+    # Modules must be reachable by name during execution (dataclasses,
+    # relative-import machinery); register before exec, unwind on failure.
+    sys.modules[name] = module
+    try:
+        spec.loader.exec_module(module)
+    except BaseException:
+        sys.modules.pop(name, None)
+        raise
+    return module
+
+
+# ---------------------------------------------------------------------------
+# Manifest extraction
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class _LoadedManifest:
+    """The :class:`AddonManifest`-shaped record the loader extracts from an
+    imported module: the resolved ``register`` callable plus the optional
+    string ``id`` / ``version`` it declared."""
+
+    register: object  # Callable[[AddonSurface], None | Awaitable[None]]
+    id: str | None = None
+    version: str | None = None
+
+
+def _pick_manifest_object(imported: object) -> object | None:
+    """Unwrap the candidate manifest object from an imported module.
+
+    Accepts, in order: the module itself when it exposes a module-level
+    callable ``register``; otherwise a ``manifest`` attribute; otherwise a
+    ``default`` attribute (the TS default-export idiom) — whichever first
+    carries a callable ``register``. Returns ``None`` when none is usable.
+
+    :param imported: the module object importlib returned for the addon
+    """
+    if callable(getattr(imported, "register", None)):
+        return imported
+    for attr in ("manifest", "default"):
+        candidate = getattr(imported, attr, None)
+        if candidate is not None and callable(getattr(candidate, "register", None)):
+            return candidate
+    return None
+
+
+def _to_manifest(imported: object) -> AddonManifest | None:
+    """Narrow an arbitrary imported module to an :class:`AddonManifest`.
+
+    An addon module is accepted when it (or its ``manifest``/``default``
+    object) exposes a callable ``register``. The optional ``id`` / ``version``
+    are copied through only when they are strings, so a malformed field
+    cannot poison the loaded manifest.
+
+    :param imported: the module object importlib returned for the addon
+    """
+    candidate = _pick_manifest_object(imported)
+    if candidate is None:
+        return None
+    register = getattr(candidate, "register")
+    raw_id = getattr(candidate, "id", None)
+    raw_version = getattr(candidate, "version", None)
+    loaded = _LoadedManifest(
+        register=register,
+        id=raw_id if isinstance(raw_id, str) else None,
+        version=raw_version if isinstance(raw_version, str) else None,
+    )
+    # _LoadedManifest carries `register` as a plain callable field, which
+    # satisfies the structural AddonManifest Protocol at runtime.
+    return loaded  # type: ignore[return-value]
+
+
+# ---------------------------------------------------------------------------
+# The default loader
+# ---------------------------------------------------------------------------
+
+
+class _ImportlibLoader:
+    """The default importlib-backed :class:`ModuleLoader`.
+
+    Normalizes the supplied path (scrub + ``~`` + base anchoring), spec-loads
+    it under a fresh synthetic name, and extracts the
+    :class:`AddonManifest`. A module that does not expose a callable
+    ``register`` is rejected, so the host converts the raise into a load
+    fault.
+    """
+
+    def __init__(self, base: str | None, home: str | None) -> None:
+        self._base = base
+        self._home = home
+
+    async def load(self, path: str) -> AddonManifest:
+        absolute = resolve_path(path, self._base, self._home)
+        module = _import_module(absolute)
+        manifest = _to_manifest(module)
+        if manifest is None:
+            raise ValueError(
+                f"addon at {absolute} does not export a register() entry point"
+            )
+        return manifest
+
+
+def create_module_loader(
+    *, base: str | None = None, home: str | None = None
+) -> ModuleLoader:
+    """Construct the default importlib-backed :class:`ModuleLoader`.
+
+    All options default to the live runtime, but each is overridable so a
+    test can pin the working directory or home without touching the process.
+    These options only steer how a supplied path is normalized before it is
+    imported.
+
+    This is the production loader; tests inject a fake implementing the same
+    Protocol, exercising the registry/host without any real import or disk.
+
+    :param base: directory a relative addon path resolves against; defaults
+        to the process working directory
+    :param home: home directory a leading ``~`` expands against; defaults to
+        the user's
+    """
+    return _ImportlibLoader(base, home)

induscode/addons/manifest.py

@@ -0,0 +1,232 @@
+"""Addon discovery — scanning a workspace for addon entry modules.
+
+Where ``loader.py`` answers "how do I load *this* path", this module answers
+"*which* paths are there to load". It walks the per-workspace
+:data:`ADDONS_DIR` (``.indus/addons`` — the dirname is kept verbatim from the
+TS lineage) one level deep and yields the absolute entry-module paths a
+:class:`ModuleLoader` will resolve.
+
+Python addon convention (locked, plan §3) — two candidate shapes are
+recognised inside that directory:
+
+1. **A bare module file** — ``something.py`` sitting directly in the addons
+   directory *is* its own entry.
+2. **A package directory** — a subdirectory holding an ``__init__.py``; that
+   ``__init__.py`` is the entry. (The TS ``package.json`` ``indusAddon``
+   pointer and ``index.*`` probing collapse to this one Python-native rule.)
+
+Discovery is filesystem-only and never imports a module: it produces *paths*,
+leaving the actual import to the loader. Hidden entries (dot-files and
+dot-directories) are skipped so editor and VCS detritus is never treated as
+an addon (``__pycache__`` directories fall out naturally — they hold no
+``__init__.py``). The scan is resilient: a missing addons directory yields an
+empty list rather than an error, and an unreadable entry is silently skipped.
+
+Two entry points are exposed:
+
+- :func:`discover_addons` — the low-level "scan one directory, return paths".
+- :func:`discover_sources` — folds an :class:`AddonDiscovery` config
+  (workspace + explicit paths) into a deduplicated, id-stamped
+  :class:`AddonSource` list the host feeds to the loader.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Literal
+
+from .contract import ADDONS_DIR, AddonDiscovery, AddonId, AddonSource, addon_id
+
+__all__ = [
+    "ENTRY_EXTENSIONS",
+    "PACKAGE_ENTRY",
+    "discover_addons",
+    "discover_sources",
+]
+
+
+# ---------------------------------------------------------------------------
+# Recognised module shapes
+# ---------------------------------------------------------------------------
+
+#: File extensions a loadable addon entry can carry. The TS list spanned the
+#: jiti-transpilable set (.ts/.tsx/.mts/.cts/.js/.mjs/.cjs); Python addons are
+#: plain source modules, so the set collapses to ``.py`` — kept data-sourced
+#: so widening it stays a one-line edit.
+ENTRY_EXTENSIONS: tuple[str, ...] = (".py",)
+
+#: The conventional entry file a package directory must hold to be an addon.
+#: Replaces the TS ``package.json`` ``indusAddon`` pointer + ``index.*``
+#: probing with the one Python-native marker.
+PACKAGE_ENTRY = "__init__.py"
+
+
+def _is_hidden(name: str) -> bool:
+    """Whether ``name`` is a hidden entry (begins with a dot) that discovery
+    skips."""
+    return name.startswith(".")
+
+
+def _has_entry_extension(name: str) -> bool:
+    """Whether ``name`` carries one of the recognised :data:`ENTRY_EXTENSIONS`."""
+    return os.path.splitext(name)[1].lower() in ENTRY_EXTENSIONS
+
+
+# ---------------------------------------------------------------------------
+# Filesystem probes (total — never raise)
+# ---------------------------------------------------------------------------
+
+
+def _entry_kind(path: str) -> Literal["file", "directory"] | None:
+    """The kind of a filesystem entry, or ``None`` when it cannot be stat'd.
+
+    Wraps the stat probes so a transient/permission error during a scan
+    degrades to "skip this entry" instead of aborting the whole discovery
+    pass.
+    """
+    try:
+        if os.path.isdir(path):
+            return "directory"
+        if os.path.isfile(path):
+            return "file"
+    except OSError:
+        return None
+    return None
+
+
+def _list_names(dir: str) -> list[str]:
+    """The names directly inside ``dir``, or an empty list when ``dir`` is
+    absent or unreadable. Total so a missing addons directory is a no-op, not
+    a failure."""
+    try:
+        return os.listdir(dir)
+    except OSError:
+        return []
+
+
+# ---------------------------------------------------------------------------
+# Per-candidate resolution
+# ---------------------------------------------------------------------------
+
+
+def _resolve_package_entry(package_dir: str) -> str | None:
+    """Resolve a package directory's entry module to an absolute path.
+
+    A directory is an addon package exactly when it holds a
+    :data:`PACKAGE_ENTRY` (``__init__.py``). Returns ``None`` otherwise.
+
+    :param package_dir: the candidate package directory
+    """
+    candidate = os.path.join(package_dir, PACKAGE_ENTRY)
+    return candidate if _entry_kind(candidate) == "file" else None
+
+
+def _resolve_top_level_entry(dir: str, name: str) -> str | None:
+    """Resolve a single top-level entry of the addons directory to its addon
+    entry path, or ``None`` when it is not a recognised addon shape.
+
+    - a non-hidden file with a recognised extension is its own entry;
+    - a non-hidden directory resolves through :func:`_resolve_package_entry`.
+
+    :param dir: the addons directory being scanned
+    :param name: a top-level entry name within it
+    """
+    if _is_hidden(name):
+        return None
+    path = os.path.join(dir, name)
+    kind = _entry_kind(path)
+    if kind == "file":
+        return path if _has_entry_extension(name) else None
+    if kind == "directory":
+        return _resolve_package_entry(path)
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Public discovery
+# ---------------------------------------------------------------------------
+
+
+def discover_addons(dir: str) -> list[str]:
+    """Scan one addons directory and return the absolute entry-module paths it
+    holds.
+
+    Walks ``dir`` a single level deep, resolving each non-hidden child through
+    :func:`_resolve_top_level_entry`. The result is sorted by path for a
+    stable, deterministic load order, and is empty when ``dir`` is missing or
+    holds no recognised addon. This is the low-level primitive;
+    :func:`discover_sources` layers the config (workspace + explicit paths)
+    and id-stamping on top.
+
+    :param dir: absolute path to an addons directory (typically
+        ``<workspace>/.indus/addons``)
+    """
+    entries: list[str] = []
+    for name in _list_names(dir):
+        entry = _resolve_top_level_entry(dir, name)
+        if entry is not None:
+            entries.append(entry)
+    return sorted(entries)
+
+
+def _derive_addon_id(entry_path: str) -> AddonId:
+    """Derive a stable :data:`AddonId` for a discovered entry path.
+
+    Uses the entry's enclosing folder name when the file is the conventional
+    package entry (so ``<ws>/.indus/addons/foo/__init__.py`` is identified as
+    ``foo``), otherwise the file's own base name without extension. The full
+    path is the ultimate uniqueness guarantee; this id is the human-facing
+    label used in diagnostics.
+
+    :param entry_path: the absolute entry-module path
+    """
+    file = os.path.basename(entry_path)
+    stem = os.path.splitext(file)[0]
+    if file == PACKAGE_ENTRY or stem == "__init__":
+        label = os.path.basename(os.path.dirname(entry_path))
+    else:
+        label = stem
+    return addon_id(label if len(label) > 0 else entry_path)
+
+
+def _addons_dir_for(workspace: str, dir: str | None = None) -> str:
+    """The default addons directory for a workspace, joined from
+    :data:`ADDONS_DIR`.
+
+    :param workspace: absolute workspace root
+    :param dir: directory relative to the workspace; defaults to :data:`ADDONS_DIR`
+    """
+    return os.path.abspath(os.path.join(workspace, dir if dir is not None else ADDONS_DIR))
+
+
+def discover_sources(discovery: AddonDiscovery) -> list[AddonSource]:
+    """Fold an :class:`AddonDiscovery` config into the ordered, deduplicated
+    list of :class:`AddonSource` entries the host hands to the loader.
+
+    Concatenates, in this order: the entries discovered under the workspace's
+    addons directory (when a ``workspace`` is given), then any
+    :attr:`AddonDiscovery.explicit_paths` (resolved to absolute paths;
+    already-absolute paths pass through verbatim, exactly as in TS — they are
+    the fake-loader table keys in tests). Duplicate paths are collapsed — the
+    first occurrence wins — and each surviving path is stamped with a derived
+    :data:`AddonId`. Discovery touches the filesystem only to enumerate; it
+    never imports a module.
+
+    :param discovery: the discovery configuration (workspace, dir, explicit paths)
+    """
+    paths: list[str] = []
+
+    if discovery.workspace is not None:
+        paths.extend(discover_addons(_addons_dir_for(discovery.workspace, discovery.dir)))
+
+    for explicit in discovery.explicit_paths or ():
+        paths.append(explicit if os.path.isabs(explicit) else os.path.abspath(explicit))
+
+    seen: set[str] = set()
+    sources: list[AddonSource] = []
+    for path in paths:
+        if path in seen:
+            continue
+        seen.add(path)
+        sources.append(AddonSource(id=_derive_addon_id(path), path=path))
+    return sources