induscode 0.1.0__py3-none-any.whl

induscode/kit/tool_fetch.py

@@ -0,0 +1,288 @@
+"""Tool-fetch kit — a managed-binary provisioner stub for the native helpers
+the agent shells out to (a fast file finder and a fast content grep, fd / rg).
+
+The agent prefers native binaries when present and otherwise provisions them
+from a project release page into a managed directory. This module owns the
+*resolution and URL-building* half of that flow as a small, injectable stub:
+
+- :func:`resolve_managed_binary_path` computes where a managed binary lives on
+  disk (the managed ``bin/`` directory + the platform-correct file name),
+  without touching the filesystem;
+- :func:`pick_release_asset` selects the right release asset for the host by
+  matching a per-tool :class:`re.Pattern` against the asset names a release
+  exposes — a regex matcher rather than a per-tool string switch;
+- :func:`build_download_request` renders the asset download URL plus the
+  outbound request headers, stamping this kit's own :data:`KIT_USER_AGENT`.
+
+The network is *optional and injectable*: nothing here issues a request. A
+caller supplies a :class:`ReleaseLookup` (e.g. backed by a release REST
+endpoint, a fixture, or a cache) and this module turns its result into a
+concrete request. That keeps the module pure, host-agnostic, and trivially
+testable offline.
+
+Port of TS ``src/kit/tool-fetch.ts`` (the platform tags — ``"darwin"`` /
+``"linux"`` / ``"win32"`` — are shared between ``process.platform`` and
+:data:`sys.platform`, so the win32 check ports verbatim).
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import sys
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import Awaitable, Final, Mapping, Protocol
+
+__all__ = [
+    "DownloadRequest",
+    "KIT_USER_AGENT",
+    "ProvisionPlan",
+    "ReleaseAsset",
+    "ReleaseInfo",
+    "ReleaseLookup",
+    "ToolDescriptor",
+    "build_download_request",
+    "pick_release_asset",
+    "plan_provision",
+    "resolve_managed_binary_path",
+]
+
+# ---------------------------------------------------------------------------
+# Identity
+# ---------------------------------------------------------------------------
+
+#: The ``User-Agent`` this kit stamps on every outbound provisioning request.
+#:
+#: A fresh, self-describing token owned by this module — release hosts expect
+#: a non-empty agent string, and a distinctive one keeps the agent's traffic
+#: identifiable in server logs. Versioned so the string can move with the kit.
+#: Kept verbatim from the TS kit.
+KIT_USER_AGENT: Final[str] = "indusagi-kit-provisioner/1.0"
+
+
+# ---------------------------------------------------------------------------
+# Tool descriptors
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class ToolDescriptor:
+    """A declarative description of one provisionable native helper.
+
+    The provisioner is driven entirely off a sequence of these: there is no
+    per-tool branch anywhere in the flow. :attr:`asset_matcher` is the
+    load-bearing field — a compiled :class:`re.Pattern` searched against each
+    candidate asset name to pick the host build, replacing the old
+    per-platform name templates.
+    """
+
+    # The bare binary name the agent invokes, e.g. ``"fd"`` / ``"rg"``.
+    bin: str
+    # The owner/repo coordinate the release is fetched from, e.g. ``"owner/tool"``.
+    repo: str
+    # A regex selecting this tool's asset for the *current host* from a
+    # release's asset list. The caller composes platform / arch fragments into
+    # the pattern; the matcher then does the selection, so adding a tool is
+    # data, not code. Searched (not anchored) to match the TS `RegExp.test`.
+    asset_matcher: re.Pattern[str]
+
+
+# ---------------------------------------------------------------------------
+# Path resolution
+# ---------------------------------------------------------------------------
+
+
+def resolve_managed_binary_path(
+    bin_dir: str | os.PathLike[str],
+    bin: str,
+    platform: str = sys.platform,
+) -> str:
+    """Compute the on-disk path of a managed binary without touching the
+    filesystem.
+
+    Joins the managed binaries directory with the platform-correct executable
+    name — the bare ``bin`` name on POSIX, the same name with a ``.exe``
+    suffix on Windows. Pure: it builds a string and never stats the path, so a
+    caller can decide separately whether the binary is actually present.
+
+    :param bin_dir: the managed binaries directory (e.g. the workspace ``bin/``)
+    :param bin: the bare binary name, e.g. ``"fd"``
+    :param platform: the host platform tag (defaults to :data:`sys.platform`)
+    """
+    file_name = f"{bin}.exe" if platform == "win32" else bin
+    return os.path.join(bin_dir, file_name)
+
+
+# ---------------------------------------------------------------------------
+# Release lookup (injected network)
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class ReleaseAsset:
+    """One downloadable asset on a release, reduced to the two fields the
+    matcher and the request builder need.
+    """
+
+    # The asset file name matched against a :attr:`ToolDescriptor.asset_matcher`.
+    name: str
+    # The fully-qualified URL the asset bytes are fetched from.
+    url: str
+
+
+@dataclass(frozen=True, slots=True)
+class ReleaseInfo:
+    """A resolved release: its tag and the assets it exposes.
+
+    Whatever produces this — a live REST call, a fixture, a cache — is the
+    caller's concern; this module only consumes the shape.
+    """
+
+    # The release tag, e.g. ``"v1.2.3"``; surfaced for path / version templating.
+    tag: str
+    # Every downloadable asset on the release.
+    assets: tuple[ReleaseAsset, ...]
+
+
+class ReleaseLookup(Protocol):
+    """The injected, optional network boundary.
+
+    A caller supplies a callable that resolves an ``owner/repo`` coordinate to
+    its latest :class:`ReleaseInfo`. This module never imports an HTTP client;
+    the lookup is the single seam where real network access (or a stub) is
+    plugged in, keeping :func:`build_download_request` pure and
+    offline-testable. Any ``async def lookup(repo: str) -> ReleaseInfo``
+    satisfies it structurally.
+    """
+
+    def __call__(self, repo: str, /) -> Awaitable[ReleaseInfo]: ...
+
+
+# ---------------------------------------------------------------------------
+# Asset selection
+# ---------------------------------------------------------------------------
+
+
+def pick_release_asset(
+    descriptor: ToolDescriptor,
+    release: ReleaseInfo,
+) -> ReleaseAsset | None:
+    """Select the release asset matching a tool's
+    :attr:`ToolDescriptor.asset_matcher`.
+
+    Tests each asset name against the descriptor's regex and returns the first
+    match, or ``None`` when no asset fits the host (a release that lacks a
+    build for this platform / arch). Pure: it filters the supplied list and
+    performs no I/O.
+
+    :param descriptor: the tool whose asset is being located
+    :param release: the release whose assets are searched
+    """
+    for asset in release.assets:
+        # `.search` (not `.match`): TS `RegExp.test` scans the whole string.
+        if descriptor.asset_matcher.search(asset.name):
+            return asset
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Download request
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class DownloadRequest:
+    """A ready-to-issue download request: the URL plus the outbound headers.
+
+    The caller hands this to whatever HTTP client it owns; this module builds
+    it but never sends it (the network stays injectable).
+    """
+
+    # The asset URL to fetch.
+    url: str
+    # The asset file name (useful for the unpack / install step).
+    asset_name: str
+    # The outbound request headers, including this kit's :data:`KIT_USER_AGENT`.
+    headers: Mapping[str, str]
+
+
+def build_download_request(asset: ReleaseAsset) -> DownloadRequest:
+    """Render the download request for a selected release asset.
+
+    Stamps the kit :data:`KIT_USER_AGENT` and an octet-stream ``Accept`` so
+    the release host returns the raw asset rather than a metadata document,
+    then carries through the asset URL and name. Pure string assembly —
+    issuing the request is the caller's job.
+
+    :param asset: the asset chosen by :func:`pick_release_asset`
+    """
+    return DownloadRequest(
+        url=asset.url,
+        asset_name=asset.name,
+        headers=MappingProxyType(
+            {
+                "User-Agent": KIT_USER_AGENT,
+                "Accept": "application/octet-stream",
+            }
+        ),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Provisioning plan
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class ProvisionPlan:
+    """A computed provisioning plan for one tool: where the binary should land
+    and how to fetch its bytes.
+
+    This is the stub's terminal value — everything needed to perform the
+    install (download :attr:`DownloadRequest.url`, unpack, move to
+    :attr:`target_path`, mark executable) without this module performing any
+    of it.
+    """
+
+    # The bare binary name being provisioned.
+    bin: str
+    # Where the installed binary should live (from :func:`resolve_managed_binary_path`).
+    target_path: str
+    # The release tag the plan was built against.
+    tag: str
+    # The request that fetches the matching asset for the host.
+    download: DownloadRequest
+
+
+async def plan_provision(
+    descriptor: ToolDescriptor,
+    bin_dir: str | os.PathLike[str],
+    lookup: ReleaseLookup,
+    platform: str = sys.platform,
+) -> ProvisionPlan | None:
+    """Build a :class:`ProvisionPlan` for a tool by looking up its latest
+    release and selecting the host asset.
+
+    Resolves the release through the injected :class:`ReleaseLookup`, picks
+    the asset via :func:`pick_release_asset`, and assembles the on-disk target
+    path and the download request. The network touch is entirely the
+    caller-supplied ``lookup``; this function adds no I/O of its own. Returns
+    ``None`` when the release exposes no asset for the host, so a caller can
+    fall back to a system-installed binary.
+
+    :param descriptor: the tool to provision
+    :param bin_dir: the managed binaries directory the binary installs into
+    :param lookup: the injected release resolver (the only network seam)
+    :param platform: the host platform tag (defaults to :data:`sys.platform`)
+    """
+    release = await lookup(descriptor.repo)
+    asset = pick_release_asset(descriptor, release)
+    if asset is None:
+        return None
+    return ProvisionPlan(
+        bin=descriptor.bin,
+        target_path=resolve_managed_binary_path(bin_dir, descriptor.bin, platform),
+        tag=release.tag,
+        download=build_download_request(asset),
+    )

induscode/launch/__init__.py

@@ -0,0 +1,224 @@
+"""Launch subsystem — public barrel.
+
+Re-exports the frozen contract surface: the parsed
+:class:`~.contract.Invocation` and its :data:`~.contract.OutputMode` /
+:data:`~.contract.ThinkingEffort` / :data:`~.contract.ToolName` vocabularies,
+the declarative flag table types, the gathered :class:`~.contract.Attachments`
+shape, the typed :class:`~.contract.CredentialFault` union and its
+:class:`~.contract.AuthVault` Protocol seam, the model-catalog filter, and the
+resume / settings-browser option shapes. Behavior modules (the reader, the
+usage renderer, the credential command, the attachment gatherer, the OAuth
+adapter, the package command, the catalog printer, the resume picker, the
+settings browser) attach their exports here, so consumers import the launch
+surface from ``induscode.launch`` rather than reaching into individual
+modules.
+
+NOTE: importing this barrel has **no side effects** — in particular the OAuth
+adapter registry is *not* primed here (the TS barrel primed it on import; the
+port plan forbids import-time registration). Boot primes it explicitly via
+:func:`register_built_in_oauth_providers`.
+"""
+
+from __future__ import annotations
+
+from .catalog import (
+    CatalogIo,
+    CatalogModelSource,
+    catalog_source,
+    default_catalog_io,
+    print_model_catalog,
+)
+from .contract import (
+    THINKING_EFFORTS,
+    TOOL_NAMES,
+    AttachmentOptions,
+    Attachments,
+    AuthVault,
+    CatalogFilter,
+    CredentialFault,
+    CredentialFaultKind,
+    CredentialVerb,
+    FlagDefault,
+    FlagKind,
+    FlagSpec,
+    FlagValue,
+    ImageContent,
+    Invocation,
+    OAuthCredentials,
+    OutputMode,
+    ProviderEntry,
+    ResumeFault,
+    ResumeRef,
+    SessionLoader,
+    Settings,
+    SettingsBrowseOptions,
+    ThinkingEffort,
+    ThinkingLevel,
+    ToolName,
+    credential_fault,
+    is_output_mode,
+    is_thinking_effort,
+    is_tool_name,
+)
+from .credentials import (
+    PROVIDER_DIRECTORY,
+    CredentialIo,
+    CredentialResult,
+    SigninMethod,
+    as_signin_method,
+    default_credential_io,
+    find_provider,
+    format_credential_fault,
+    is_oauth_capable,
+    run_credential_command,
+    validate_account_name,
+    validate_api_key,
+)
+from .invocation import (
+    FLAG_GROUPS,
+    FLAG_SPECS,
+    AttachmentError,
+    AttachmentErrorKind,
+    FlagGroup,
+    FlagGroupEntry,
+    GroupedFlagSpec,
+    gather_attachments,
+    read_file_references,
+    read_invocation,
+    render_usage,
+)
+from .oauth import (
+    AuthKind,
+    LoginDriver,
+    LoginProvider,
+    OAuthAuthorization,
+    OAuthLoginCallbacks,
+    OAuthLoginError,
+    OAuthLoginResult,
+    OAuthPrompt,
+    OAuthProviderAdapter,
+    RefreshDriver,
+    get_oauth_provider,
+    get_oauth_providers,
+    github_copilot_adapter,
+    list_login_providers,
+    open_login_url,
+    refresh_oauth_credentials,
+    register_built_in_oauth_providers,
+    register_oauth_provider,
+    start_oauth_login,
+)
+from .packages import (
+    PACKAGE_COMMANDS,
+    PackageCommand,
+    PackageIo,
+    PackageResult,
+    default_package_io,
+    run_package_command,
+)
+from .pickers import (
+    ResumeDeps,
+    ResumeOutcome,
+    SettingsBrowseIo,
+    browse_settings,
+    default_resume_deps,
+    default_settings_browse_io,
+    merge_sessions,
+    pick_resume_target,
+    render_settings_listing,
+)
+
+__all__ = [
+    "AttachmentError",
+    "AttachmentErrorKind",
+    "AttachmentOptions",
+    "Attachments",
+    "AuthKind",
+    "AuthVault",
+    "CatalogFilter",
+    "CatalogIo",
+    "CatalogModelSource",
+    "CredentialFault",
+    "CredentialFaultKind",
+    "CredentialIo",
+    "CredentialResult",
+    "CredentialVerb",
+    "FLAG_GROUPS",
+    "FLAG_SPECS",
+    "FlagDefault",
+    "FlagGroup",
+    "FlagGroupEntry",
+    "FlagKind",
+    "FlagSpec",
+    "FlagValue",
+    "GroupedFlagSpec",
+    "ImageContent",
+    "Invocation",
+    "LoginDriver",
+    "LoginProvider",
+    "OAuthAuthorization",
+    "OAuthCredentials",
+    "OAuthLoginCallbacks",
+    "OAuthLoginError",
+    "OAuthLoginResult",
+    "OAuthPrompt",
+    "OAuthProviderAdapter",
+    "OutputMode",
+    "PACKAGE_COMMANDS",
+    "PROVIDER_DIRECTORY",
+    "PackageCommand",
+    "PackageIo",
+    "PackageResult",
+    "ProviderEntry",
+    "RefreshDriver",
+    "ResumeDeps",
+    "ResumeFault",
+    "ResumeOutcome",
+    "ResumeRef",
+    "SessionLoader",
+    "Settings",
+    "SettingsBrowseIo",
+    "SettingsBrowseOptions",
+    "SigninMethod",
+    "THINKING_EFFORTS",
+    "TOOL_NAMES",
+    "ThinkingEffort",
+    "ThinkingLevel",
+    "ToolName",
+    "as_signin_method",
+    "browse_settings",
+    "catalog_source",
+    "credential_fault",
+    "default_catalog_io",
+    "default_credential_io",
+    "default_package_io",
+    "default_resume_deps",
+    "default_settings_browse_io",
+    "find_provider",
+    "format_credential_fault",
+    "gather_attachments",
+    "get_oauth_provider",
+    "get_oauth_providers",
+    "github_copilot_adapter",
+    "is_oauth_capable",
+    "is_output_mode",
+    "is_thinking_effort",
+    "is_tool_name",
+    "list_login_providers",
+    "merge_sessions",
+    "open_login_url",
+    "pick_resume_target",
+    "print_model_catalog",
+    "read_file_references",
+    "read_invocation",
+    "refresh_oauth_credentials",
+    "register_built_in_oauth_providers",
+    "register_oauth_provider",
+    "render_settings_listing",
+    "render_usage",
+    "run_credential_command",
+    "run_package_command",
+    "start_oauth_login",
+    "validate_account_name",
+    "validate_api_key",
+]