induscode 0.1.0__py3-none-any.whl

induscode/launch/invocation/__init__.py

@@ -0,0 +1,39 @@
+"""Invocation subsystem — public barrel.
+
+Bundles the command-line behavior modules that all read the single
+declarative :data:`~.flags.FLAG_SPECS` table:
+
+- :func:`~.read.read_invocation` — the generic, table-driven argv parser that
+  folds a sliced argument vector into a typed
+  :class:`~induscode.launch.contract.Invocation`;
+- :func:`~.usage.render_usage` — the ``--help`` banner generated from that
+  same table, so help and parsing share one source of truth;
+- :func:`~.attachments.gather_attachments` — the ``@file`` expander that
+  resolves references through the inlined path resolver into inlined prose
+  plus base64 media, raising a typed
+  :class:`~.attachments.AttachmentError` on failure.
+
+Consumers import the invocation surface from ``induscode.launch.invocation``
+rather than reaching into the individual modules.
+"""
+
+from __future__ import annotations
+
+from .attachments import AttachmentError, AttachmentErrorKind, gather_attachments
+from .flags import FLAG_GROUPS, FLAG_SPECS, FlagGroup, FlagGroupEntry, GroupedFlagSpec
+from .read import read_file_references, read_invocation
+from .usage import render_usage
+
+__all__ = [
+    "AttachmentError",
+    "AttachmentErrorKind",
+    "FLAG_GROUPS",
+    "FLAG_SPECS",
+    "FlagGroup",
+    "FlagGroupEntry",
+    "GroupedFlagSpec",
+    "gather_attachments",
+    "read_file_references",
+    "read_invocation",
+    "render_usage",
+]

induscode/launch/invocation/attachments.py

@@ -0,0 +1,281 @@
+"""The attachment gatherer — expands ``@file`` references into one
+:class:`~induscode.launch.contract.Attachments` value.
+
+Each ``@file`` token collected by the reader is resolved through the inlined
+path resolver (:func:`_resolve_read_path`, which handles ``~`` expansion and
+the cwd — the framework publishes no ``resolveReadPath`` export, so the
+~5-line shim lives here per the port plan), classified by extension, and
+folded into the result:
+
+- **text files** are read as UTF-8 and inlined into ``Attachments.prose``
+  wrapped in a delimited block keyed by the resolved path, so the model sees
+  which file each block came from;
+- **image files** are read as bytes, base64-encoded, and collected as
+  framework :class:`~indusagi.ai.ImageContent` in ``Attachments.media``.
+
+Guard rails:
+
+- an unknown extension, an oversized file, a missing file, or a read error
+  raises a typed :class:`AttachmentError` (with an :data:`AttachmentErrorKind`
+  discriminant) rather than a string or a process exit;
+- size caps bound the inlined text and the decoded image before either is
+  materialised onto the message;
+- an empty file is skipped silently — it contributes neither prose nor media.
+
+The ``@file`` syntax, the extension classification, and base64 image
+attachment are kept behaviours; only the typed-error model and the explicit
+caps are owned here. (Port of TS ``src/launch/invocation/attachments.ts``.)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import os
+from pathlib import Path
+from typing import Final, Literal, Sequence, TypeAlias
+
+from indusagi.ai import ImageContent
+
+from ..contract import AttachmentOptions, Attachments
+
+__all__ = ["AttachmentError", "AttachmentErrorKind", "gather_attachments"]
+
+
+#: Upper bound on an inlined text file: larger files are rejected, not
+#: truncated.
+_MAX_TEXT_BYTES: Final[int] = 10 * 1024 * 1024
+
+#: Upper bound on a decoded image file before base64 encoding.
+_MAX_IMAGE_BYTES: Final[int] = 20 * 1024 * 1024
+
+#: Lower-cased file extensions inlined as text prose.
+_TEXT_EXTENSIONS: Final[frozenset[str]] = frozenset(
+    {
+        ".txt",
+        ".md",
+        ".markdown",
+        ".json",
+        ".jsonc",
+        ".yaml",
+        ".yml",
+        ".toml",
+        ".ini",
+        ".csv",
+        ".tsv",
+        ".xml",
+        ".html",
+        ".htm",
+        ".css",
+        ".scss",
+        ".ts",
+        ".tsx",
+        ".js",
+        ".jsx",
+        ".mjs",
+        ".cjs",
+        ".py",
+        ".rb",
+        ".go",
+        ".rs",
+        ".java",
+        ".kt",
+        ".c",
+        ".h",
+        ".cc",
+        ".cpp",
+        ".hpp",
+        ".cs",
+        ".php",
+        ".sh",
+        ".bash",
+        ".zsh",
+        ".sql",
+        ".log",
+        ".env",
+        ".gitignore",
+        ".dockerfile",
+    }
+)
+
+#: Lower-cased image extensions mapped to their media type for
+#: :class:`~indusagi.ai.ImageContent`.
+_IMAGE_MIME_BY_EXT: Final[dict[str, str]] = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".bmp": "image/bmp",
+    ".svg": "image/svg+xml",
+}
+
+
+#: The closed set of attachment failure categories. A consumer switches on
+#: :attr:`AttachmentError.kind`, never on message text:
+#:
+#: - ``unsupported``  — the file extension is neither text nor image.
+#: - ``too-large``    — the file exceeds its kind's size cap.
+#: - ``not-found``    — the resolved path does not exist.
+#: - ``read-failed``  — the file could not be read or stat-ed.
+AttachmentErrorKind: TypeAlias = Literal[
+    "unsupported", "too-large", "not-found", "read-failed"
+]
+
+
+class AttachmentError(Exception):
+    """A typed ``@file`` expansion failure. Carries the offending reference
+    and the resolved path for diagnostics; :attr:`cause` preserves any wrapped
+    error."""
+
+    # The failure category (the discriminant).
+    kind: AttachmentErrorKind
+    # The raw @file reference as supplied on the command line.
+    reference: str
+    # The resolved absolute path, when resolution succeeded.
+    resolved_path: str | None
+    # The wrapped underlying error, if any.
+    cause: object | None
+
+    def __init__(
+        self,
+        kind: AttachmentErrorKind,
+        message: str,
+        *,
+        reference: str,
+        resolved_path: str | None = None,
+        cause: object | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.kind = kind
+        self.reference = reference
+        self.resolved_path = resolved_path
+        self.cause = cause
+
+
+def _resolve_read_path(reference: str, cwd: str) -> str:
+    """The inlined path resolver (the framework's ``resolveReadPath`` has no
+    Python export — port plan §1 gap #3): expand a leading ``~``, keep an
+    absolute reference verbatim, and resolve a relative one against ``cwd``
+    (lexically — no symlink resolution, so the path the user supplied is the
+    path reported back)."""
+    expanded = Path(reference).expanduser()
+    if expanded.is_absolute():
+        return str(expanded)
+    return os.path.normpath(os.path.join(cwd, str(expanded)))
+
+
+def _extension_of(path: str) -> str:
+    """The lower-cased extension of a path, including the leading dot."""
+    return Path(path).suffix.lower()
+
+
+async def _size_of(resolved_path: str, reference: str) -> int:
+    """Stat a resolved path, mapping a missing file to a typed
+    :class:`AttachmentError`."""
+    try:
+        info = await asyncio.to_thread(os.stat, resolved_path)
+        return info.st_size
+    except FileNotFoundError as error:
+        raise AttachmentError(
+            "not-found",
+            f"No such file: {reference}",
+            reference=reference,
+            resolved_path=resolved_path,
+            cause=error,
+        ) from error
+    except OSError as error:
+        raise AttachmentError(
+            "read-failed",
+            f"Could not access file: {reference}",
+            reference=reference,
+            resolved_path=resolved_path,
+            cause=error,
+        ) from error
+
+
+def _wrap_text_block(resolved_path: str, body: str) -> str:
+    """Wrap one resolved text file in a path-keyed delimited block for the
+    prose stream."""
+    return f'<file path="{resolved_path}">\n{body}\n</file>'
+
+
+async def gather_attachments(
+    references: Sequence[str],
+    options: AttachmentOptions,
+) -> Attachments:
+    """Expand the ``@file`` references into a single
+    :class:`~induscode.launch.contract.Attachments` value.
+
+    Resolves each reference against ``options.cwd``, classifies it by
+    extension, enforces the per-kind size cap, and appends either a text block
+    to the prose or an :class:`~indusagi.ai.ImageContent` to the media. The
+    references list is taken in order; the prose blocks are joined with a
+    blank line between them. An empty references list yields an empty
+    :class:`Attachments` (the caller decides whether to attach it at all).
+
+    :param references: the raw ``@file`` paths (without the leading ``@``)
+    :param options: the cwd the references resolve against
+    :raises AttachmentError: on an unsupported extension, an oversized file, a
+        missing file, or a read failure
+    """
+    blocks: list[str] = []
+    media: list[ImageContent] = []
+
+    for reference in references:
+        resolved_path = _resolve_read_path(reference, options.cwd)
+        ext = _extension_of(resolved_path)
+
+        image_mime = _IMAGE_MIME_BY_EXT.get(ext)
+        is_text = ext in _TEXT_EXTENSIONS
+
+        if image_mime is None and not is_text:
+            raise AttachmentError(
+                "unsupported",
+                f"Unsupported attachment type: {reference}",
+                reference=reference,
+                resolved_path=resolved_path,
+            )
+
+        size = await _size_of(resolved_path, reference)
+        if size == 0:
+            continue  # Skip empty files silently.
+
+        cap = _MAX_IMAGE_BYTES if image_mime is not None else _MAX_TEXT_BYTES
+        if size > cap:
+            raise AttachmentError(
+                "too-large",
+                f"Attachment exceeds the size limit: {reference}",
+                reference=reference,
+                resolved_path=resolved_path,
+            )
+
+        try:
+            if image_mime is not None:
+                data = await asyncio.to_thread(Path(resolved_path).read_bytes)
+                media.append(
+                    ImageContent(
+                        data=base64.b64encode(data).decode("ascii"),
+                        mimeType=image_mime,
+                    )
+                )
+            else:
+                # errors="replace" mirrors Buffer.toString("utf8"): invalid
+                # sequences degrade to replacement characters, never raise.
+                body = await asyncio.to_thread(
+                    Path(resolved_path).read_text,
+                    encoding="utf-8",
+                    errors="replace",
+                )
+                if len(body) > 0:
+                    blocks.append(_wrap_text_block(resolved_path, body))
+        except OSError as error:
+            raise AttachmentError(
+                "read-failed",
+                f"Could not read file: {reference}",
+                reference=reference,
+                resolved_path=resolved_path,
+                cause=error,
+            ) from error
+
+    return Attachments(prose="\n\n".join(blocks), media=tuple(media))

induscode/launch/invocation/flags.py

@@ -0,0 +1,210 @@
+"""The single declarative flag table.
+
+Every recognised command-line option is described here exactly once, as one
+:class:`GroupedFlagSpec` row. Two consumers walk this same table:
+
+- the reader (:func:`~.read.read_invocation`) indexes it by canonical name
+  and alias to bind raw tokens into the parsed
+  :class:`~induscode.launch.contract.Invocation`; and
+- the usage generator (:func:`~.usage.render_usage`) enumerates it to render
+  the option reference — there is no second, hand-maintained help string for
+  it to drift against.
+
+Because both sides read the same rows, the help text and the parser cannot
+disagree about which flags exist, what they take, or what they mean. The order
+of the rows is the order options appear in the generated usage, grouped by the
+:data:`FLAG_GROUPS` sidecar list below; keeping that order intentional is the
+only editorial concern when a row is added.
+
+Flag names and their semantics are a stable product contract (and largely an
+industry convention), so they are kept as-is; only the table that declares
+them and the code that reads it are owned here. (Port of TS
+``src/launch/invocation/flags.ts`` — all 17 rows verbatim.)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Final, Literal, TypeAlias
+
+from ..contract import THINKING_EFFORTS, FlagSpec
+
+__all__ = [
+    "FLAG_GROUPS",
+    "FLAG_SPECS",
+    "FlagGroup",
+    "FlagGroupEntry",
+    "GroupedFlagSpec",
+]
+
+
+#: The heading a flag is filed under in the generated usage. Purely an
+#: editorial grouping for the renderer; it has no effect on parsing.
+FlagGroup: TypeAlias = Literal["output", "model", "context", "tools", "meta"]
+
+
+@dataclass(frozen=True, slots=True)
+class GroupedFlagSpec(FlagSpec):
+    """A :class:`~induscode.launch.contract.FlagSpec` carrying its usage
+    section. The extra :attr:`group` field is inert at parse time; the reader
+    ignores it and only the renderer reads it."""
+
+    # The usage section this row is rendered under.
+    group: FlagGroup = field(kw_only=True)
+
+
+@dataclass(frozen=True, slots=True)
+class FlagGroupEntry:
+    """One usage section: its :data:`FlagGroup` id and human-readable title."""
+
+    id: FlagGroup
+    title: str
+
+
+#: Human-readable titles for each :data:`FlagGroup`, in render order. The
+#: usage generator walks this list, then within each group emits the matching
+#: rows from :data:`FLAG_SPECS` in declaration order.
+FLAG_GROUPS: Final[tuple[FlagGroupEntry, ...]] = (
+    FlagGroupEntry(id="output", title="Output"),
+    FlagGroupEntry(id="model", title="Model"),
+    FlagGroupEntry(id="context", title="Context"),
+    FlagGroupEntry(id="tools", title="Tools"),
+    FlagGroupEntry(id="meta", title="Meta"),
+)
+
+
+#: The ascending reasoning-effort rungs accepted by ``--thinking``, rendered
+#: into its description so the usage text enumerates the accepted values from
+#: the same source the validator uses.
+_THINKING_CHOICES: Final[str] = ", ".join(THINKING_EFFORTS)
+
+
+#: The one declarative option table. Every recognised flag is one row; the
+#: reader and the usage generator both index this and nothing else.
+#:
+#: Conventions:
+#:
+#: - ``name`` is the canonical long spelling (leading dashes included) and
+#:   also the key the parsed value lands under in ``Invocation.flags`` (sans
+#:   the dashes).
+#: - ``aliases`` hold short forms and synonyms; every alias hit normalises to
+#:   ``name``.
+#: - ``kind`` fixes the value vocabulary: ``boolean`` switches, ``string`` /
+#:   ``number`` value flags, and accumulating ``list`` flags.
+FLAG_SPECS: Final[tuple[GroupedFlagSpec, ...]] = (
+    # ---- Output -----------------------------------------------------------
+    GroupedFlagSpec(
+        name="--print",
+        aliases=("-p",),
+        kind="boolean",
+        group="output",
+        describe="Run a single request, print only the result, and exit.",
+    ),
+    GroupedFlagSpec(
+        name="--json",
+        aliases=("--rpc",),
+        kind="boolean",
+        group="output",
+        describe="Speak the headless line protocol for a driving parent process.",
+    ),
+    GroupedFlagSpec(
+        name="--interactive",
+        aliases=("-i",),
+        kind="boolean",
+        group="output",
+        describe="Force the interactive session even when a prompt is supplied.",
+    ),
+    # ---- Model ------------------------------------------------------------
+    GroupedFlagSpec(
+        name="--model",
+        aliases=("-m",),
+        kind="string",
+        group="model",
+        describe="Select the model, provider-qualified or bare (e.g. provider/name).",
+    ),
+    GroupedFlagSpec(
+        name="--account",
+        kind="string",
+        group="model",
+        describe="Authenticate the run with a named stored credential account.",
+    ),
+    GroupedFlagSpec(
+        name="--thinking",
+        kind="string",
+        group="model",
+        describe=f"Set the reasoning effort (one of: {_THINKING_CHOICES}).",
+    ),
+    GroupedFlagSpec(
+        name="--list-models",
+        kind="string",
+        group="model",
+        describe="List the available models (optionally filtered by a substring) and exit.",
+    ),
+    # ---- Context ----------------------------------------------------------
+    GroupedFlagSpec(
+        name="--cwd",
+        kind="string",
+        group="context",
+        describe="Scope the run to a working directory (default: the current directory).",
+    ),
+    GroupedFlagSpec(
+        name="--system",
+        kind="string",
+        group="context",
+        describe="Replace the built-in system prompt with the given text.",
+    ),
+    GroupedFlagSpec(
+        name="--append-system",
+        kind="string",
+        group="context",
+        describe="Append extra text after the system prompt.",
+    ),
+    GroupedFlagSpec(
+        name="--resume",
+        aliases=("-r",),
+        kind="boolean",
+        group="context",
+        describe="Pick a previous session to resume.",
+    ),
+    GroupedFlagSpec(
+        name="--continue",
+        aliases=("-c",),
+        kind="boolean",
+        group="context",
+        describe="Continue the most recent session in this directory.",
+    ),
+    # ---- Tools ------------------------------------------------------------
+    GroupedFlagSpec(
+        name="--tools",
+        kind="list",
+        group="tools",
+        describe="Allow only the named built-in tools (comma-separated or repeated).",
+    ),
+    GroupedFlagSpec(
+        name="--no-tools",
+        kind="boolean",
+        group="tools",
+        describe="Disable every built-in tool for this run.",
+    ),
+    GroupedFlagSpec(
+        name="--mcp",
+        kind="list",
+        group="tools",
+        describe="Attach an external MCP server endpoint (comma-separated or repeated).",
+    ),
+    # ---- Meta -------------------------------------------------------------
+    GroupedFlagSpec(
+        name="--help",
+        aliases=("-h",),
+        kind="boolean",
+        group="meta",
+        describe="Show this usage and exit.",
+    ),
+    GroupedFlagSpec(
+        name="--version",
+        aliases=("-v",),
+        kind="boolean",
+        group="meta",
+        describe="Show the version and exit.",
+    ),
+)