induscode 0.1.0__py3-none-any.whl

induscode/kit/__init__.py

@@ -0,0 +1,82 @@
+"""Kit subsystem — public barrel.
+
+``kit/`` holds the agent's framework-agnostic leaf helpers: small, pure,
+stdlib-only utilities with no dependency on the framework or on any sibling
+subsystem. It re-exports five groups (the TS ``src/kit/index.ts``):
+
+- **tool_fetch** — the managed-binary provisioner stub (fd / rg): managed
+  path resolution, regex-driven release-asset selection, and a download-
+  request builder stamped with this kit's own :data:`KIT_USER_AGENT`. The
+  network is injected, never imported.
+- **image** — PNG / JPEG magic-byte sniffing (interface-dictated signatures)
+  and the ``{token}`` asset-name renderer.
+- **shell** — POSIX shell-argument quoting and command assembly.
+- **clipboard_image** — clipboard → temp PNG staging (best-effort, ``None``
+  on any miss).
+- **external_editor** — ``$VISUAL`` / ``$EDITOR`` / ``vi`` buffer hand-off.
+
+Consumers import from :mod:`induscode.kit` rather than reaching into
+individual modules. The upstream filler libraries (generic array / string /
+date / json / etc. stdlib clones) are intentionally omitted: they had zero
+consumers, so they are not rebuilt here.
+"""
+
+from .clipboard_image import ClipboardImageOptions, read_clipboard_image
+from .external_editor import ExternalEditorOptions, open_in_external_editor
+from .image import (
+    IMAGE_SNIFF_BYTES,
+    AssetNameContext,
+    ByteSource,
+    ImageFormat,
+    ImageMediaType,
+    detect_image_media_type,
+    is_supported_image,
+    media_type_for_image_format,
+    resolve_asset_name,
+    sniff_image_format,
+)
+from .shell import build_shell_command, needs_quoting, quote_arg
+from .tool_fetch import (
+    KIT_USER_AGENT,
+    DownloadRequest,
+    ProvisionPlan,
+    ReleaseAsset,
+    ReleaseInfo,
+    ReleaseLookup,
+    ToolDescriptor,
+    build_download_request,
+    pick_release_asset,
+    plan_provision,
+    resolve_managed_binary_path,
+)
+
+__all__ = [
+    "AssetNameContext",
+    "ByteSource",
+    "ClipboardImageOptions",
+    "DownloadRequest",
+    "ExternalEditorOptions",
+    "IMAGE_SNIFF_BYTES",
+    "ImageFormat",
+    "ImageMediaType",
+    "KIT_USER_AGENT",
+    "ProvisionPlan",
+    "ReleaseAsset",
+    "ReleaseInfo",
+    "ReleaseLookup",
+    "ToolDescriptor",
+    "build_download_request",
+    "build_shell_command",
+    "detect_image_media_type",
+    "is_supported_image",
+    "media_type_for_image_format",
+    "needs_quoting",
+    "open_in_external_editor",
+    "pick_release_asset",
+    "plan_provision",
+    "quote_arg",
+    "read_clipboard_image",
+    "resolve_asset_name",
+    "resolve_managed_binary_path",
+    "sniff_image_format",
+]

induscode/kit/clipboard_image.py

@@ -0,0 +1,215 @@
+"""Clipboard-image kit — pull a raster image off the OS clipboard and stage it
+on disk as a temp PNG, returning the path the composer can splice into a
+prompt.
+
+The terminal can only carry text, so an image on the clipboard cannot ride a
+normal paste. Instead this helper shells out to the platform's clipboard
+tool, captures the raw bytes, writes them to a temp file, and hands back the
+path — the agent then attaches the file by reference.
+
+Platform strategy (each is the conventional tool for its OS):
+
+- **macOS** — ``pngpaste -`` dumps a clipboard image to stdout; when it is not
+  installed we fall back to an ``osascript`` one-liner that asks the clipboard
+  for its «class PNGf» data and stages it through a temp file.
+- **Linux/Wayland** — ``wl-paste --type image/png`` writes the image to stdout.
+- **Linux/X11** — ``xclip -selection clipboard -t image/png -o`` does the same.
+
+Every spawn is best-effort: a missing tool, a non-zero exit, a timeout, or an
+empty clipboard all collapse to ``None`` so the caller can warn rather than
+throw. The :mod:`subprocess` / :mod:`os` / :mod:`tempfile` stdlib modules are
+the only dependencies; nothing here touches the framework or a sibling
+subsystem.
+
+Port of TS ``src/kit/clipboard-image.ts``.
+"""
+
+from __future__ import annotations
+
+import os
+import random
+import subprocess
+import sys
+import tempfile
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Final, Mapping, Sequence
+
+__all__ = [
+    "ClipboardImageOptions",
+    "read_clipboard_image",
+]
+
+# ---------------------------------------------------------------------------
+# Tunables
+# ---------------------------------------------------------------------------
+
+#: How long a clipboard tool may run before we give up on it (seconds; the TS
+#: kit's 3000 ms).
+_READ_TIMEOUT_SECONDS: Final[float] = 3.0
+
+#: Ceiling on the captured image size; a larger blob is treated as a miss
+#: (50 MiB). Node's ``maxBuffer`` kills the child at the limit; Python has no
+#: equivalent knob, so the cap is enforced on the captured bytes instead —
+#: same outcome (an oversized capture is a ``None`` miss).
+_MAX_BUFFER_BYTES: Final[int] = 50 * 1024 * 1024
+
+# ---------------------------------------------------------------------------
+# Spawning
+# ---------------------------------------------------------------------------
+
+
+def _capture_stdout(command: str, args: Sequence[str]) -> bytes | None:
+    """Run a clipboard tool and return its stdout bytes, or ``None`` on any
+    failure.
+
+    A spawn error (binary absent), a timeout, a non-zero exit, an oversized
+    capture, or empty output all yield ``None`` — the helper never raises, so
+    a probe for an absent tool is cheap.
+    """
+    try:
+        result = subprocess.run(
+            [command, *args],
+            capture_output=True,
+            timeout=_READ_TIMEOUT_SECONDS,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    if result.returncode != 0:
+        return None
+    out = result.stdout
+    if not out or len(out) > _MAX_BUFFER_BYTES:
+        return None
+    return out
+
+
+def _capture_via_osascript() -> bytes | None:
+    """macOS fallback when ``pngpaste`` is absent: drive ``osascript`` to write
+    the clipboard's PNG payload to a temp file and echo its path, then read it
+    back.
+
+    Returns the raw bytes or ``None`` when the clipboard holds no PNG data,
+    the script errored, or the staged file came back empty.
+    """
+    try:
+        result = subprocess.run(
+            [
+                "osascript",
+                "-e",
+                "try",
+                "-e",
+                "set png to (the clipboard as «class PNGf»)",
+                "-e",
+                'set fp to (path to temporary items as string) & "indus-clip.png"',
+                "-e",
+                "set fh to open for access file fp with write permission",
+                "-e",
+                "set eof fh to 0",
+                "-e",
+                "write png to fh",
+                "-e",
+                "close access fh",
+                "-e",
+                "POSIX path of fp",
+                "-e",
+                "on error",
+                "-e",
+                'return ""',
+                "-e",
+                "end try",
+            ],
+            capture_output=True,
+            timeout=_READ_TIMEOUT_SECONDS,
+            encoding="utf-8",
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    if result.returncode != 0:
+        return None
+    path = (result.stdout or "").strip()
+    if len(path) == 0:
+        return None
+    try:
+        data = Path(path).read_bytes()
+    except OSError:
+        return None
+    return data if len(data) > 0 else None
+
+
+def _read_clipboard_bytes(platform: str, env: Mapping[str, str]) -> bytes | None:
+    """Read the clipboard image bytes for the host platform, trying the most
+    likely tool first and falling back where a platform offers more than one
+    route.
+    """
+    if platform == "darwin":
+        return _capture_stdout("pngpaste", ["-"]) or _capture_via_osascript()
+    if platform == "linux":
+        wayland = bool(env.get("WAYLAND_DISPLAY")) or env.get("XDG_SESSION_TYPE") == "wayland"
+        if wayland:
+            from_wayland = _capture_stdout("wl-paste", ["--type", "image/png", "--no-newline"])
+            if from_wayland:
+                return from_wayland
+        return _capture_stdout("xclip", ["-selection", "clipboard", "-t", "image/png", "-o"])
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Public surface
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class ClipboardImageOptions:
+    """Options for :func:`read_clipboard_image` — injectable so tests stay
+    hermetic.
+    """
+
+    # Override the host platform (defaults to :data:`sys.platform`).
+    platform: str | None = None
+    # Override the environment consulted for the Wayland probe.
+    env: Mapping[str, str] | None = None
+    # Override the temp directory the captured PNG is written to.
+    dir: str | os.PathLike[str] | None = None
+
+
+#: The digit alphabet used by the temp-name stamp (JS ``toString(36)``).
+_BASE36_DIGITS: Final[str] = "0123456789abcdefghijklmnopqrstuvwxyz"
+
+
+def _to_base36(value: int) -> str:
+    """Render a non-negative integer in base 36 (the JS ``toString(36)``)."""
+    if value == 0:
+        return "0"
+    digits: list[str] = []
+    while value:
+        value, remainder = divmod(value, 36)
+        digits.append(_BASE36_DIGITS[remainder])
+    return "".join(reversed(digits))
+
+
+def read_clipboard_image(options: ClipboardImageOptions | None = None) -> str | None:
+    """Pull an image off the OS clipboard, write it to a temp PNG, and return
+    the file path — or ``None`` when no image is on the clipboard, the
+    platform's tool is missing, or the write fails.
+
+    The returned path is unique per call (millisecond + random suffix) so two
+    pastes never collide. The caller owns the temp file thereafter.
+    """
+    resolved = options if options is not None else ClipboardImageOptions()
+    platform = resolved.platform if resolved.platform is not None else sys.platform
+    env: Mapping[str, str] = resolved.env if resolved.env is not None else os.environ
+    data = _read_clipboard_bytes(platform, env)
+    if data is None:
+        return None
+
+    directory = resolved.dir if resolved.dir is not None else tempfile.gettempdir()
+    stamp = _to_base36(int(time.time() * 1000))
+    suffix = "".join(random.choices(_BASE36_DIGITS, k=6))
+    name = f"indus-clipboard-{stamp}-{suffix}.png"
+    path = os.path.join(directory, name)
+    try:
+        Path(path).write_bytes(data)
+        return path
+    except OSError:
+        return None

induscode/kit/external_editor.py

@@ -0,0 +1,120 @@
+"""External-editor kit — hand the composer buffer off to the user's
+``$EDITOR``, wait for them to close it, and read the edited text back.
+
+Composing a long prompt at a single-line terminal caret is painful; this
+helper stages the current buffer in a temp file, launches the configured
+editor against it with the terminal shared (so vi/nano/etc. take over the
+screen), blocks until the editor exits, then reads the file back as the new
+buffer.
+
+The editor is resolved from ``$VISUAL``, then ``$EDITOR``, then a ``vi``
+fallback — the conventional precedence. The spawn is synchronous and inherits
+this process's stdio so the editor owns the real terminal; on return the temp
+file is removed. Any failure (no editor that runs, a non-zero exit, an
+unreadable file) yields ``None`` and the caller keeps the original buffer.
+
+Only :mod:`subprocess` / :mod:`os` / :mod:`tempfile` stdlib modules are used;
+nothing here depends on the framework or a sibling subsystem.
+
+Port of TS ``src/kit/external-editor.ts``.
+"""
+
+from __future__ import annotations
+
+import os
+import random
+import re
+import subprocess
+import tempfile
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Final, Mapping
+
+__all__ = [
+    "ExternalEditorOptions",
+    "open_in_external_editor",
+]
+
+#: The editor used when neither ``$VISUAL`` nor ``$EDITOR`` is set.
+_FALLBACK_EDITOR: Final[str] = "vi"
+
+
+@dataclass(frozen=True, slots=True)
+class ExternalEditorOptions:
+    """Options for :func:`open_in_external_editor` — injectable so tests stay
+    hermetic.
+    """
+
+    # Override the environment consulted for ``$VISUAL`` / ``$EDITOR``.
+    env: Mapping[str, str] | None = None
+    # Override the temp directory the scratch file is written to.
+    dir: str | os.PathLike[str] | None = None
+
+
+def _resolve_editor(env: Mapping[str, str]) -> list[str]:
+    """Resolve the editor command line, splitting it into an argv so an editor
+    set with flags (e.g. ``"code --wait"``) is honored. Falls back to ``vi``.
+
+    ``$VISUAL`` then ``$EDITOR`` with *truthy* (TS ``||``) semantics: an empty
+    or unset value falls through.
+    """
+    configured = env.get("VISUAL") or env.get("EDITOR") or _FALLBACK_EDITOR
+    parts = [part for part in re.split(r"\s+", configured) if len(part) > 0]
+    return parts if len(parts) > 0 else [_FALLBACK_EDITOR]
+
+
+#: The digit alphabet used by the temp-name stamp (JS ``toString(36)``).
+_BASE36_DIGITS: Final[str] = "0123456789abcdefghijklmnopqrstuvwxyz"
+
+
+def _to_base36(value: int) -> str:
+    """Render a non-negative integer in base 36 (the JS ``toString(36)``)."""
+    if value == 0:
+        return "0"
+    digits: list[str] = []
+    while value:
+        value, remainder = divmod(value, 36)
+        digits.append(_BASE36_DIGITS[remainder])
+    return "".join(reversed(digits))
+
+
+def open_in_external_editor(
+    buffer: str,
+    options: ExternalEditorOptions | None = None,
+) -> str | None:
+    """Stage ``buffer`` in a temp file, open it in the user's editor sharing
+    this terminal, block until the editor exits, and return the edited text —
+    or ``None`` when the editor could not run or exited non-zero.
+
+    A single trailing newline (most editors add one on save) is stripped so
+    the round-trip does not silently grow the buffer. The temp file is always
+    removed.
+    """
+    resolved = options if options is not None else ExternalEditorOptions()
+    env: Mapping[str, str] = resolved.env if resolved.env is not None else os.environ
+    directory = resolved.dir if resolved.dir is not None else tempfile.gettempdir()
+    stamp = _to_base36(int(time.time() * 1000))
+    suffix = "".join(random.choices(_BASE36_DIGITS, k=6))
+    name = f"indus-editor-{stamp}-{suffix}.md"
+    path = Path(os.path.join(directory, name))
+
+    editor, *editor_args = _resolve_editor(env)
+
+    try:
+        path.write_text(buffer, encoding="utf-8")
+        # No capture: the child inherits this process's stdio (the TS
+        # `stdio: "inherit"`), so a full-screen editor owns the terminal.
+        result = subprocess.run([editor, *editor_args, str(path)])
+        if result.returncode != 0:
+            return None
+        text = path.read_text(encoding="utf-8")
+        # Strip exactly one trailing "\n" (the TS `.replace(/\n$/, "")`).
+        return text[:-1] if text.endswith("\n") else text
+    except OSError:
+        return None
+    finally:
+        try:
+            path.unlink()
+        except OSError:
+            pass  # best-effort cleanup

induscode/kit/image.py

@@ -0,0 +1,188 @@
+"""Image kit — magic-byte sniffing for the two raster formats the agent ships
+support for, plus a tiny asset-naming helper.
+
+This is a leaf utility: framework-agnostic, stdlib-only, and pure apart from
+the byte reads it is handed. Two unrelated jobs live here because both are
+small and both are about turning opaque bytes / platform tuples into a stable
+name:
+
+- :func:`sniff_image_format` / :func:`detect_image_media_type` classify a byte
+  buffer as PNG or JPEG by inspecting its leading signature bytes. The
+  signatures are an interface-dictated constant — they are fixed by the PNG
+  and JFIF/EXIF container specifications, not a choice we make.
+- :func:`resolve_asset_name` renders a release-asset file name from a small
+  template by substituting platform / architecture / version tokens, so a
+  provisioner can locate the right download for the host without a per-tool
+  switch.
+
+Nothing here performs I/O: callers read the bytes (a file head, a clipboard
+blob, a fetched body) and pass them in. That keeps the module trivially
+testable and usable from any host.
+
+Port of TS ``src/kit/image.ts``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Final, Literal, Sequence, TypeAlias
+
+__all__ = [
+    "AssetNameContext",
+    "ByteSource",
+    "IMAGE_SNIFF_BYTES",
+    "ImageFormat",
+    "ImageMediaType",
+    "detect_image_media_type",
+    "is_supported_image",
+    "media_type_for_image_format",
+    "resolve_asset_name",
+    "sniff_image_format",
+]
+
+# ---------------------------------------------------------------------------
+# Image format detection
+# ---------------------------------------------------------------------------
+
+#: The raster image formats this kit can recognise from their leading bytes.
+#:
+#: Deliberately tiny — the agent only ever needs to tell PNG and JPEG apart
+#: for its attachment / clipboard paths; anything else is reported as
+#: unrecognised (``None``) rather than guessed.
+ImageFormat: TypeAlias = Literal["png", "jpeg"]
+
+#: The IANA media types :data:`ImageFormat` values map to.
+#:
+#: Used when a recognised format must be handed to the framework attachment
+#: model, which speaks media-type strings.
+ImageMediaType: TypeAlias = Literal["image/png", "image/jpeg"]
+
+#: The PNG file signature: the eight fixed bytes every PNG stream opens with.
+#:
+#: ``89 50 4E 47 0D 0A 1A 0A`` — interface-dictated by the PNG container
+#: format (the high bit set on the first byte, the ASCII tag, then CR LF SUB
+#: LF to catch transfer corruption). Not a value we are free to change.
+_PNG_SIGNATURE: Final[tuple[int, ...]] = (0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A)
+
+#: The JPEG Start-Of-Image marker: the first three bytes of every JFIF / EXIF
+#: stream.
+#:
+#: ``FF D8 FF`` — interface-dictated by the JPEG/JFIF container; the third
+#: byte begins the first marker segment. Three bytes is enough to distinguish
+#: JPEG from the other formats the agent handles.
+_JPEG_SIGNATURE: Final[tuple[int, ...]] = (0xFF, 0xD8, 0xFF)
+
+#: The widest signature checked, so a caller knows the minimum head to read.
+IMAGE_SNIFF_BYTES: Final[int] = len(_PNG_SIGNATURE)
+
+#: A byte source this module can read a leading window from.
+#:
+#: ``bytes`` / ``bytearray`` and a plain list of ints all satisfy this, so a
+#: caller never has to convert before sniffing (the Python analogue of the TS
+#: ``ArrayLike<number>``).
+ByteSource: TypeAlias = Sequence[int]
+
+
+def _starts_with(data: ByteSource, signature: tuple[int, ...]) -> bool:
+    """Whether ``data`` opens with the given fixed signature.
+
+    Compares byte-for-byte from offset zero; a buffer shorter than the
+    signature can never match (and short-circuits without reading past its
+    end).
+    """
+    if len(data) < len(signature):
+        return False
+    for index, expected in enumerate(signature):
+        if data[index] != expected:
+            return False
+    return True
+
+
+def sniff_image_format(data: ByteSource) -> ImageFormat | None:
+    """Classify a byte buffer as PNG or JPEG by its leading signature.
+
+    Reads at most :data:`IMAGE_SNIFF_BYTES` bytes from the front of ``data``
+    and returns the matching :data:`ImageFormat`, or ``None`` when neither
+    signature matches (an empty buffer, a truncated head, or any other
+    format). Pure: it inspects the buffer and allocates nothing.
+
+    :param data: the leading bytes of a candidate image (a file head is enough)
+    """
+    if _starts_with(data, _PNG_SIGNATURE):
+        return "png"
+    if _starts_with(data, _JPEG_SIGNATURE):
+        return "jpeg"
+    return None
+
+
+def media_type_for_image_format(format: ImageFormat) -> ImageMediaType:
+    """Map a recognised :data:`ImageFormat` to its IANA media type."""
+    return "image/png" if format == "png" else "image/jpeg"
+
+
+def detect_image_media_type(data: ByteSource) -> ImageMediaType | None:
+    """Detect the media type of a byte buffer, or ``None`` when unrecognised.
+
+    A convenience over :func:`sniff_image_format` for callers that speak
+    media-type strings (e.g. the framework attachment model) rather than the
+    internal :data:`ImageFormat` tag.
+
+    :param data: the leading bytes of a candidate image
+    """
+    format = sniff_image_format(data)
+    return None if format is None else media_type_for_image_format(format)
+
+
+def is_supported_image(data: ByteSource) -> bool:
+    """Whether ``data`` is a buffer this kit recognises as a supported image."""
+    return sniff_image_format(data) is not None
+
+
+# ---------------------------------------------------------------------------
+# Asset-name resolution
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class AssetNameContext:
+    """The platform / architecture / version facts a :func:`resolve_asset_name`
+    template can interpolate.
+
+    Field names mirror the substitution tokens; every member is optional so a
+    template that only references some of them can be rendered from a partial
+    context (a missing token resolves to an empty string).
+    """
+
+    # The host operating system, e.g. ``"darwin"`` / ``"linux"`` / ``"win32"``.
+    platform: str | None = None
+    # The host CPU architecture, e.g. ``"arm64"`` / ``"x64"``.
+    arch: str | None = None
+    # The release version, e.g. ``"1.2.3"`` (with or without a leading ``v``).
+    version: str | None = None
+    # The bare tool / binary name, e.g. ``"fd"`` / ``"rg"``.
+    name: str | None = None
+
+
+#: The substitution tokens :func:`resolve_asset_name` understands inside a
+#: template, each written as ``{token}``.
+_ASSET_TOKENS: Final[tuple[str, ...]] = ("platform", "arch", "version", "name")
+
+
+def resolve_asset_name(template: str, context: AssetNameContext) -> str:
+    """Render a release-asset file name from a ``{token}`` template.
+
+    Replaces each ``{platform}`` / ``{arch}`` / ``{version}`` / ``{name}``
+    occurrence with the matching :class:`AssetNameContext` field (an absent
+    field becomes the empty string), leaving every other character verbatim.
+    This lets a provisioner declare one template per tool — e.g.
+    ``"{name}-{version}-{arch}-{platform}.tar.gz"`` — instead of branching on
+    the host. Pure string work, no I/O.
+
+    :param template: the asset-name pattern with ``{token}`` placeholders
+    :param context: the platform / arch / version / name facts to substitute
+    """
+    rendered = template
+    for token in _ASSET_TOKENS:
+        value: str | None = getattr(context, token)
+        rendered = rendered.replace(f"{{{token}}}", value if value is not None else "")
+    return rendered

induscode/kit/shell.py

@@ -0,0 +1,89 @@
+"""Shell kit — POSIX shell-argument quoting and command assembly.
+
+A leaf utility for safely turning argument strings into a single shell line.
+The agent shells out to provisioned binaries (fd / rg) and to user commands;
+any argument carrying a space, a glob, a quote, or a metacharacter must be
+quoted so the shell passes it through as one literal token rather than
+re-parsing it.
+
+The strategy is the conventional POSIX one: wrap the argument in single
+quotes and escape any embedded single quote by closing the quote, emitting an
+escaped quote, and reopening — ``it's`` becomes ``'it'\\''s'``. Inside single
+quotes the shell treats every other character literally, so this is robust
+against spaces, ``$``, backticks, ``*``, ``;``, newlines, and the rest.
+Arguments that contain only safe characters are passed through unquoted to
+keep the rendered line readable.
+
+Pure and framework-agnostic: no process spawn, no environment, no I/O.
+
+Port of TS ``src/kit/shell.ts``. Deliberately *not* :func:`shlex.quote` —
+the pass-through readability rule (its safe-character class) is this module's
+own, kept verbatim from the TS source.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Final, Sequence
+
+__all__ = [
+    "build_shell_command",
+    "needs_quoting",
+    "quote_arg",
+]
+
+# ---------------------------------------------------------------------------
+# Quoting
+# ---------------------------------------------------------------------------
+
+#: The characters that are safe to leave unquoted on a POSIX shell line.
+#:
+#: Letters, digits, and a small set of punctuation the shell never treats
+#: specially in argument position. Anything outside this class forces quoting.
+#: Applied via ``fullmatch`` rather than ``^...$`` anchors: Python's ``$``
+#: tolerates a trailing newline, which would wrongly classify ``"foo\n"`` as
+#: safe — ``fullmatch`` restores the strict whole-string semantics of the TS
+#: ``/^[A-Za-z0-9_@%+=:,./-]+$/``.
+_SHELL_SAFE: Final[re.Pattern[str]] = re.compile(r"[A-Za-z0-9_@%+=:,./-]+")
+
+
+def quote_arg(arg: str) -> str:
+    """Quote a single argument for a POSIX shell.
+
+    Returns the argument unchanged when it is non-empty and made up entirely
+    of shell-safe characters; otherwise wraps it in single quotes, escaping
+    embedded single quotes with the ``'\\''`` idiom. An empty string becomes
+    ``''`` so it survives as a distinct (empty) argument rather than
+    vanishing.
+
+    :param arg: the raw argument value to quote
+    """
+    if len(arg) == 0:
+        return "''"
+    if _SHELL_SAFE.fullmatch(arg):
+        return arg
+    return "'" + arg.replace("'", "'\\''") + "'"
+
+
+def needs_quoting(arg: str) -> bool:
+    """Whether an argument would need quoting on a POSIX shell line.
+
+    ``True`` when the value is empty or contains any character outside the
+    shell-safe class. Useful for diagnostics or for deciding whether to render
+    a command differently; :func:`quote_arg` applies the same test internally.
+
+    :param arg: the raw argument value to test
+    """
+    return len(arg) == 0 or _SHELL_SAFE.fullmatch(arg) is None
+
+
+def build_shell_command(args: Sequence[str]) -> str:
+    """Assemble a list of arguments into a single space-separated shell line.
+
+    Each element is run through :func:`quote_arg`, so the result is safe to
+    hand to a shell as one command string. The argument order is preserved; an
+    empty list yields an empty string.
+
+    :param args: the command and its arguments, in invocation order
+    """
+    return " ".join(quote_arg(arg) for arg in args)