skit-cli 0.0.1__py3-none-any.whl

skit/tui_settings.py

@@ -0,0 +1,374 @@
+"""Script settings (p): the merged per-script management screen — basics, parameters,
+presets, dependencies in one place.
+
+Enter saves everything in one atomic [tool.skit] rewrite; Esc asks when there are
+unsaved changes. Reference-mode entries show the parameters read-only (skit never
+writes the original file, A7); command entries show the template and placeholders.
+"""
+
+from __future__ import annotations
+
+from typing import override
+
+from rich.markup import escape
+from textual import on
+from textual.app import ComposeResult
+from textual.binding import Binding
+from textual.containers import Horizontal, Vertical, VerticalScroll
+from textual.screen import ModalScreen, Screen
+from textual.widgets import Checkbox, Input, Label, Static
+
+from . import argspec, argstate, metawriter, pep723, reconcile, store, tui_footer
+from .i18n import gettext
+from .models import Entry
+
+
+class DiscardChangesModal(ModalScreen[bool]):
+    BINDINGS = [
+        Binding("y", "discard", gettext("Discard")),
+        Binding("escape,n", "keep", gettext("Keep editing")),
+    ]
+    DEFAULT_CSS = """
+    DiscardChangesModal { align: center middle; }
+    DiscardChangesModal > Vertical { border: round $accent; padding: 1 2; width: auto;
+        height: auto; background: $background; }
+    DiscardChangesModal Static { margin: 1 0 0 0; width: auto; }
+    """
+
+    @override
+    def compose(self) -> ComposeResult:
+        with Vertical():
+            yield Label(gettext("Discard unsaved changes?"))
+            yield Static(
+                tui_footer.bar(
+                    tui_footer.chip("screen.discard", "y", gettext("Discard")),
+                    tui_footer.chip("screen.keep", "Esc", gettext("Keep editing")),
+                ),
+                markup=True,
+            )
+
+    def action_discard(self) -> None:
+        self.dismiss(True)
+
+    def action_keep(self) -> None:
+        self.dismiss(False)
+
+
+class ParamRow(Vertical):
+    """One managed parameter: keep/unmanage, prompt text, secret + env source."""
+
+    DEFAULT_CSS = """
+    ParamRow { height: auto; margin: 0 0 1 2; }
+    ParamRow .p-meta { color: $text-muted; width: auto; }
+    ParamRow Horizontal { height: auto; }
+    ParamRow Horizontal > Checkbox { width: auto; }
+    ParamRow Input { width: 1fr; }
+    """
+
+    def __init__(self, spec: metawriter.ParamSpec) -> None:
+        super().__init__()
+        self.spec: metawriter.ParamSpec = spec
+
+    @override
+    def compose(self) -> ComposeResult:
+        s = self.spec
+        default = "" if s.default is None else repr(s.default)
+        yield Checkbox(f"{escape(s.name)}  [dim]{s.type} {escape(default)}[/dim]", value=True)
+        with Horizontal():
+            yield Static("  " + gettext("Form label:"), classes="p-meta")
+            yield Input(value=s.prompt, placeholder=s.name, classes="p-prompt")
+        with Horizontal():
+            yield Checkbox(
+                gettext("secret (never saved to disk)"), value=s.secret, classes="p-secret"
+            )
+            yield Input(
+                value=s.env_source,
+                placeholder=gettext("env variable to read it from (optional)"),
+                classes="p-env",
+            )
+        yield Static("", classes="p-note")
+
+    def collect(self) -> metawriter.ParamSpec | None:
+        """None when unmanaged (checkbox off)."""
+        if not self.query_one(Checkbox).value:
+            return None
+        s = self.spec
+        s.prompt = self.query_one(".p-prompt", Input).value.strip()
+        s.secret = self.query_one(".p-secret", Checkbox).value
+        s.env_source = self.query_one(".p-env", Input).value.strip() if s.secret else ""
+        return s
+
+    @on(Checkbox.Changed, ".p-secret")
+    def _secret_note(self, event: Checkbox.Changed) -> None:
+        note = self.query_one(".p-note", Static)
+        if event.value and not self.spec.secret:
+            note.update(
+                f"[yellow]{gettext('Anything skit previously remembered for this value will be deleted too.')}[/yellow]"
+            )
+        else:
+            note.update("")
+
+
+class ScriptSettingsScreen(Screen[bool]):
+    """Four sections in one screen; `s` in the Library deep-links to Presets."""
+
+    BINDINGS = [
+        Binding("escape", "close", gettext("Back")),
+        Binding("ctrl+a", "save", gettext("Save"), priority=True),
+        Binding("ctrl+r", "resync", gettext("Resync"), priority=True),
+    ]
+    DEFAULT_CSS = """
+    ScriptSettingsScreen #st-body {
+        padding: 0 1;
+        border: round $skit-box-indigo;
+        border-title-color: ansi_bright_white;
+        border-title-style: bold;
+    }
+    ScriptSettingsScreen .section { color: $accent; margin: 1 0 0 0; }
+    ScriptSettingsScreen .hint { color: $text-muted; }
+    ScriptSettingsScreen #st-keys { dock: bottom; height: 1; color: $text-muted; padding: 0 1; }
+    """
+
+    def __init__(self, entry: Entry, initial_section: str = "") -> None:
+        super().__init__()
+        self._entry: Entry = entry
+        self._initial: str = initial_section
+        self._dirty: bool = False
+        # Widgets can emit Changed while the screen is still composing (initial values
+        # settling); only user edits after mount count as dirt.
+        self._dirt_armed: bool = False
+        self._text: str = ""
+        if entry.meta.kind == "python" and entry.script_path.exists():
+            self._text = entry.script_path.read_text(encoding="utf-8", errors="replace")
+        self._specs: list[metawriter.ParamSpec] = metawriter.read_params(self._text)
+        # The resync outcome (incl. safety-rebind warnings) must survive the recompose that
+        # action_resync triggers — a widget updated in place would be thrown away and rebuilt
+        # empty. Kept on the instance so compose can re-emit it. Already escape()'d for markup.
+        self._resync_report: str = ""
+
+    @override
+    def compose(self) -> ComposeResult:
+        with VerticalScroll(id="st-body"):
+            yield Static(gettext("Basics"), classes="section")
+            yield Input(value=self._entry.meta.name, id="st-name")
+            yield Static(
+                gettext("Renaming keeps everything — remembered values, presets, the stored copy."),
+                classes="hint",
+            )
+            yield Input(
+                value=self._entry.meta.description,
+                placeholder=gettext("Description (shown in the Library)"),
+                id="st-desc",
+            )
+            yield from self._compose_storage()
+            yield from self._compose_params()
+            yield from self._compose_presets()
+            yield from self._compose_deps()
+        yield Static(
+            tui_footer.bar(
+                tui_footer.chip("screen.save", "Ctrl+A", gettext("Save")),
+                tui_footer.chip("screen.resync", "Ctrl+R", gettext("Resync")),
+                tui_footer.chip("screen.close", "Esc", gettext("Back")),
+            ),
+            id="st-keys",
+            markup=True,
+        )
+
+    def _compose_storage(self) -> ComposeResult:
+        meta = self._entry.meta
+        if meta.kind != "python":
+            return
+        yield Static(gettext("Storage"), classes="section")
+        if meta.mode == "copy":
+            yield Static(
+                gettext("Keep a copy — your original file is never modified. Source: %(path)s")
+                % {"path": escape(meta.source)},
+                classes="hint",
+            )
+        else:
+            yield Static(
+                gettext("Linked to the original: %(path)s") % {"path": escape(meta.source)},
+                classes="hint",
+            )
+
+    def _compose_params(self) -> ComposeResult:
+        yield Static(gettext("Parameters (the run form's fields)"), classes="section")
+        meta = self._entry.meta
+        if meta.kind == "command":
+            yield Static(escape(meta.template), classes="hint")
+            for p in meta.params or []:
+                yield Static(f"· {escape(p)}")
+            return
+        if meta.kind != "python":
+            yield Static(gettext("(programs have no managed parameters)"), classes="hint")
+            return
+        if meta.mode == "reference":
+            yield Static(
+                gettext(
+                    "skit doesn't write to this file — maintain the [tool.skit] definitions "
+                    "in the source directly."
+                ),
+                classes="hint",
+            )
+            for s in self._specs:
+                yield Static(f"· {escape(s.name)} ({s.type})")
+            return
+        for s in self._specs:
+            yield ParamRow(s)
+        if self._cli_driven():
+            # This script's form already comes from its own argparse/click/typer surface.
+            # Managing a hardcoded constant would write a [tool.skit] block that shadows
+            # that whole form (plan_for_entry prefers managed params) — a source-flip
+            # trap. Explain instead of offering the manage-these-constants checkboxes.
+            yield Static(
+                gettext(
+                    "This script's run form comes from its own command-line arguments. "
+                    "Managing a hardcoded constant here would replace that form — leave it as is."
+                ),
+                classes="hint",
+            )
+        else:
+            report = reconcile.reconcile(self._text, self._specs) if self._text else None
+            if report is not None and report.new:
+                yield Static(
+                    gettext("Detected but not yet managed — tick to manage:"), classes="hint"
+                )
+                for i, c in enumerate(report.new):
+                    yield Checkbox(
+                        f"{escape(c.name)}  [dim]{c.type} = {escape(repr(c.default))}[/dim]",
+                        value=False,
+                        id=f"st-new-{i}",
+                    )
+        if self._specs and all(s.kind == "input" for s in self._specs):
+            yield Static(
+                gettext("Every input() is managed — this script can now run with --no-input."),
+                classes="hint",
+            )
+        yield Static(self._resync_report, id="st-resync-report", classes="hint", markup=True)
+
+    def _cli_driven(self) -> bool:
+        """Whether the run form currently comes from the script's own CLI surface — i.e.
+        nothing is managed yet AND the script parses its own arguments. (Once anything is
+        managed, plan_for_entry already serves the injected form, so there's no trap.)"""
+        if self._specs or not self._text:
+            return False
+        return argspec.read_cli(self._text) is not None
+
+    def _compose_presets(self) -> ComposeResult:
+        yield Static(gettext("Presets"), classes="section", id="st-presets-section")
+        presets = argstate.load_state(self._entry.slug)["presets"]
+        if not presets:
+            yield Static(
+                gettext("None yet — press Ctrl+S inside the run form to save one."),
+                classes="hint",
+            )
+            return
+        yield Static(gettext("Untick a preset to delete it on save:"), classes="hint")
+        for i, (name, values) in enumerate(sorted(presets.items())):
+            summary = ", ".join(f"{k}={v}" for k, v in values.items())
+            yield Checkbox(
+                f"{escape(name)}  [dim]{escape(summary)}[/dim]", value=True, id=f"st-preset-{i}"
+            )
+
+    def _compose_deps(self) -> ComposeResult:
+        meta = self._entry.meta
+        if meta.kind != "python":
+            return
+        yield Static(gettext("Dependencies"), classes="section")
+        yield Input(
+            value=", ".join(meta.dependencies or []),
+            placeholder=gettext("comma separated, e.g. requests>=2,<3, rich"),
+            id="st-deps",
+        )
+        yield Input(
+            value=meta.requires_python,
+            placeholder=gettext('Python constraint, e.g. ">=3.11" (empty = automatic)'),
+            id="st-python",
+        )
+
+    def on_mount(self) -> None:
+        self.query_one("#st-body").border_title = gettext("Script settings · %(name)s") % {
+            "name": escape(self._entry.meta.name)
+        }
+        self.call_after_refresh(setattr, self, "_dirt_armed", True)
+        if self._initial == "presets":
+            # `s` in the Library deep-links here: land the eye on the Presets section.
+            section = self.query("#st-presets-section")
+            if section:
+                self.call_after_refresh(
+                    self.query_one("#st-body", VerticalScroll).scroll_to_widget, section.first()
+                )
+
+    @on(Input.Changed)
+    @on(Checkbox.Changed)
+    def _mark_dirty(self) -> None:
+        if self._dirt_armed:
+            self._dirty = True
+
+    # ----------------------------------------------------------------- save
+
+    def action_resync(self) -> None:
+        if self._entry.meta.kind != "python" or self._entry.meta.mode != "copy":
+            return
+        result = reconcile.edit_specs(self._text, self._specs, resync=True)
+        self._specs = result.specs
+        # Stash the outcome before recompose rebuilds the screen (updating the live Static
+        # would be lost — recompose replaces it). compose re-emits self._resync_report.
+        if result.warnings:
+            self._resync_report = "\n".join(
+                escape(reconcile.render_warning(w)) for w in result.warnings
+            )
+        else:
+            self._resync_report = gettext("Everything still matches the script.")
+        self.refresh(recompose=True)
+
+    def action_save(self) -> None:
+        entry = self._entry
+        new_name = self.query_one("#st-name", Input).value.strip()
+        if new_name and new_name != entry.meta.name:
+            try:
+                store.rename(entry.slug, new_name)
+            except store.StoreError as exc:
+                self.notify(str(exc), severity="error")
+                return  # stay on the screen; nothing else is saved half-way
+        description = self.query_one("#st-desc", Input).value.strip()
+        if description != entry.meta.description:
+            store.update_description(entry.slug, description)
+        if entry.meta.kind == "python" and entry.meta.mode == "copy" and self._text:
+            new_specs = [s for row in self.query(ParamRow) if (s := row.collect()) is not None]
+            report = reconcile.reconcile(self._text, self._specs) if self._text else None
+            if report is not None:
+                for i, c in enumerate(report.new):
+                    box = self.query(f"#st-new-{i}")
+                    if box and box.first(Checkbox).value:
+                        new_specs.append(metawriter.ParamSpec.from_candidate(c))
+            copy_path = entry.dir / "script.py"
+            copy_path.write_text(metawriter.write_params(self._text, new_specs), encoding="utf-8")
+            purged = argstate.purge_secret(entry.slug, {s.name for s in new_specs if s.secret})
+            if purged:
+                self.notify(
+                    gettext("Deleted previously remembered value(s): %(names)s")
+                    % {"names": ", ".join(sorted(purged))}
+                )
+        if entry.meta.kind == "python":
+            deps = pep723.split_requirements(self.query_one("#st-deps", Input).value)
+            python = self.query_one("#st-python", Input).value.strip()
+            if deps != (entry.meta.dependencies or []) or python != entry.meta.requires_python:
+                store.update_dependencies(entry.slug, deps, requires_python=python)
+        presets = argstate.load_state(entry.slug)["presets"]
+        for i, name in enumerate(sorted(presets)):
+            box = self.query(f"#st-preset-{i}")
+            if box and not box.first(Checkbox).value:
+                argstate.delete_preset(entry.slug, name)
+        self.dismiss(True)
+
+    def action_close(self) -> None:
+        if not self._dirty:
+            self.dismiss(False)
+            return
+
+        def _decided(discard: bool | None) -> None:
+            if discard:
+                self.dismiss(False)
+
+        self.app.push_screen(DiscardChangesModal(), _decided)

skit/uvman.py

@@ -0,0 +1,288 @@
+"""UvManager: when uv is missing, auto-download a managed copy into a private bin (A9, the pattern
+rye validated).
+
+- PIN a known-good version rather than chasing latest (reproducible, testable).
+- Download/extract with pure stdlib (urllib + tarfile/zipfile); no extra dependencies.
+- Download progress goes to stderr (stdout is reserved for the script's output).
+"""
+
+from __future__ import annotations
+
+import contextlib
+import hashlib
+import os
+import platform
+import shutil
+import sys
+import tarfile
+import tempfile
+import urllib.request
+import zipfile
+from pathlib import Path
+
+from . import config
+from .i18n import gettext
+from .paths import private_bin_dir
+
+# Pinned rather than chasing latest: the download URL is built from the version, so users get
+# exactly what CI tested (reproducible); chasing latest would turn the fallback path into untested
+# code on every upstream release and add an API lookup as a failure point. This is only the
+# fallback for "the system has no uv" — if find_uv() locates a system uv, the system one wins.
+# Bump: change this line -> REFRESH _UV_SHA256 below from the official `.sha256` sidecars for the new
+# version (the pinned hashes are version-specific — a stale table would reject every download) -> run
+# tests/test_uvman.py (URL liveness + the SKIT_NET_TESTS sidecar cross-check) -> three-platform CI green.
+UV_VERSION = "0.11.26"  # bumped 2026-07-04 (latest at the time)
+
+# Official SHA256 of each release archive, from Astral's per-asset `.sha256` sidecars for UV_VERSION.
+# The downloaded archive is verified against this table BEFORE extraction, so a hostile or compromised
+# mirror (or a corrupt transfer) can never get skit to extract and execute a trojaned uv — the fetch
+# fails closed on any mismatch, and equally if a triple is missing here. These 8 triples are exactly
+# what _triple() can emit: {x86_64, aarch64} x {apple-darwin, unknown-linux-gnu, unknown-linux-musl,
+# pc-windows-msvc} — the musl pair covers Alpine and other musl-libc Linux userlands (see _is_musl).
+# MUST be refreshed alongside UV_VERSION (see the bump note above).
+_UV_SHA256: dict[str, str] = {
+    "aarch64-apple-darwin": "8f7fbf1708399b921857bce71e1d60f0d3ccf52a30caebc1c1a2f175dce13ab6",
+    "x86_64-apple-darwin": "922b460202707dd5f4ccacbadbe7f6a546cc46e82a99bf50ca99a7977a78eddd",
+    "aarch64-unknown-linux-gnu": "befa1a59c91e96eb601b0fd9a97c03dd666f17baba644b2b4db9c59a767e387e",
+    "x86_64-unknown-linux-gnu": "6426a73c3837e6e2483ee344cbc00f36394d179afcba6183cb77437e67db4af0",
+    "aarch64-unknown-linux-musl": "47418cfdb34b1ca42e503da72631ac8c475602e2411ac6c39aa84c2373fe6324",
+    "x86_64-unknown-linux-musl": "62bf1a53501adf4083224b69b33737450ac516935f5a5e483e9dfaf2665084de",
+    "aarch64-pc-windows-msvc": "98246149741f558e25e45ecf2b0b20f34de0634269f2bf0dcb4012d4b6ba289a",
+    "x86_64-pc-windows-msvc": "4e1278ede866be6c0bf32d2f466cc6de7a9fb399ecf20c9ce2d186e52424be47",
+}
+
+
+class UvDownloadError(Exception):
+    pass
+
+
+class UvDeclinedError(UvDownloadError):
+    """The user explicitly declined the download. The message includes self-install guidance."""
+
+
+def _ask_consent(dest_dir: Path) -> bool:
+    """Ask once before downloading on an interactive terminal; non-interactive (pipe/CI) keeps A9's
+    zero-action behavior but has already been told via stderr.
+
+    - Pulling an executable from the network shouldn't be entirely silent, but the default is Y: the
+      target user is someone who "grabbed a script and just wants to run it".
+    - The prompt goes to stderr (stdout is reserved for the script's output); EOF counts as consent
+      (common in semi-interactive environments).
+    """
+    if not (sys.stdin.isatty() and sys.stderr.isatty()):
+        return True
+    print(
+        gettext(
+            "skit needs Astral's uv to run Python scripts, but it wasn't found on this system. Download uv %(version)s into skit's private directory (%(path)s)? This won't touch your PATH or global environment. [Y/n]"
+        )
+        % {"version": UV_VERSION, "path": str(dest_dir)},
+        file=sys.stderr,
+        flush=True,
+        end=" ",
+    )
+    try:
+        answer = input()
+    except EOFError:
+        return True
+    return answer.strip().lower() not in ("n", "no")
+
+
+_MUSL_LD_DIR = Path("/lib")
+_MUSL_LD_GLOB = "ld-musl-*.so.1"
+
+
+def _is_musl() -> bool:
+    """Best-effort detection of a musl libc userland (Alpine Linux and similar).
+
+    musl's dynamic linker always installs at the fixed path /lib/ld-musl-<arch>.so.1 — baked
+    into the PT_INTERP field of every musl-linked ELF binary, unlike glibc's version- and
+    distro-dependent ld-linux naming — so this file's presence is a reliable, dependency-free
+    signal. Deliberately avoids shelling out to `ldd`/`getconf` or parsing ELF headers ourselves:
+    a plain path check can't fail in a way that blocks the download. Only meaningful (and only
+    called) under sys.platform == "linux"; harmless to call elsewhere since musl never installs
+    at this path outside Linux.
+    """
+    return any(_MUSL_LD_DIR.glob(_MUSL_LD_GLOB))
+
+
+def _triple() -> str:
+    machine = platform.machine().lower()
+    arch = {
+        "x86_64": "x86_64",
+        "amd64": "x86_64",
+        "arm64": "aarch64",
+        "aarch64": "aarch64",
+    }.get(machine)
+    if arch is None:
+        raise UvDownloadError(
+            gettext("Unsupported platform: %(platform)s")
+            % {"platform": f"{sys.platform}/{machine}"}
+        )
+    if sys.platform == "darwin":
+        return f"{arch}-apple-darwin"
+    if sys.platform == "win32":
+        return f"{arch}-pc-windows-msvc"
+    libc = "musl" if _is_musl() else "gnu"
+    return f"{arch}-unknown-linux-{libc}"
+
+
+_UV_RELEASES = "https://github.com/astral-sh/uv/releases/download"
+
+
+def download_url(triple: str | None = None) -> str:
+    triple = triple or _triple()
+    ext = "zip" if "windows" in triple else "tar.gz"
+    base = config.uv_binary_base() or _UV_RELEASES
+    return f"{base}/{UV_VERSION}/uv-{triple}.{ext}"
+
+
+def _fsync_path(path: Path) -> None:
+    """Fsync `path` (a file or a directory) so its data — or, for a directory, the rename/link
+    entries within it — is durable on stable storage, not just sitting in the page cache.
+
+    Flag choice is platform-split: on POSIX, fsync() flushes the inode's dirty pages regardless of
+    the fd's access mode, and directories can never be opened for writing, so O_RDONLY works for
+    both the staged file and (only on POSIX) the directory fsync. On Windows, os.fsync maps to the
+    CRT `_commit`, which requires a *writable* fd — a read-only handle fails with EBADF — and the
+    directory fsync isn't attempted there anyway (os.open can't open a directory), so this is only
+    ever called on the staged file, which we can safely open O_RDWR.
+    """
+    # The Windows arm can't be exercised on the POSIX mutation runner: there O_RDONLY and O_RDWR are
+    # equivalent for fsync, and a flipped condition only opens the dir fd O_RDWR (EISDIR, swallowed
+    # by the caller's contextlib.suppress) — so no mutant is observable. Hence: no mutate.
+    flags = os.O_RDWR if sys.platform == "win32" else os.O_RDONLY  # pragma: no mutate
+    fd = os.open(path, flags)
+    try:
+        os.fsync(fd)
+    finally:
+        os.close(fd)
+
+
+def _extract_uv(archive: Path, dest_dir: Path) -> Path:
+    """Extract the uv executable from the archive into dest_dir and return the final path.
+
+    Installs atomically (mirrors atomic.py's tmp + os.replace pattern, C7): the executable is
+    copied into a throwaway file inside dest_dir, fsync'd, and only os.replace()'d onto the real
+    `dest` path once the copy, chmod, and fsync have all fully succeeded. If the process is killed
+    or the disk fills up partway through that copy, the only thing left behind is the throwaway
+    tmp file — `dest` itself either holds the complete, verified, executable binary or does not
+    exist at all. This matters because ensure_uv_downloaded and launcher.find_uv both gate purely
+    on dest.exists(): without this, a truncated file at `dest` would look "already installed"
+    forever and skit would never self-heal by re-downloading. The same-directory tmp file also
+    makes concurrent first runs safe (last os.replace wins, never a torn file).
+
+    The fsync of the staged file's data BEFORE os.replace is what makes the "complete or absent"
+    guarantee hold across power loss, not just SIGKILL/ENOSPC: os.replace() is atomic with respect
+    to concurrent readers (they see either the old or the new dest, never a torn file), but that
+    says nothing about whether the staged file's bytes have actually reached disk yet — without
+    the fsync, a crash right after the rename commits but before the page cache writes back could
+    leave `dest` renamed-in with zero-length/garbage contents. The directory fsync afterward is a
+    best-effort extra: it durably persists the rename's directory-entry update too, but isn't
+    required for the dest-content guarantee above (and isn't attempted on Windows, where
+    directories can't be opened via os.open).
+    """
+    exe_name = "uv.exe" if sys.platform == "win32" else "uv"
+    dest = dest_dir / exe_name
+    with tempfile.TemporaryDirectory() as tmp:
+        tmp_path = Path(tmp)
+        if archive.suffix == ".zip":
+            with zipfile.ZipFile(archive) as zf:
+                zf.extractall(tmp_path)  # noqa: S202 — official release zip, extracted to a temp dir
+        else:
+            with tarfile.open(
+                archive, "r:gz"
+            ) as tf:  # pragma: no mutate — "r" mode auto-detects gzip compression
+                tf.extractall(tmp_path, filter="data")
+        candidates = list(tmp_path.rglob(exe_name))
+        if not candidates:
+            raise UvDownloadError(
+                gettext("No uv binary found inside the archive: %(path)s") % {"path": str(archive)}
+            )
+        dest_dir.mkdir(parents=True, exist_ok=True)
+        fd, staged_name = tempfile.mkstemp(dir=dest_dir, prefix=f".{exe_name}.", suffix=".tmp")
+        os.close(fd)
+        staged = Path(staged_name)
+        try:
+            shutil.copy2(candidates[0], staged)
+            staged.chmod(staged.stat().st_mode | 0o755)
+            _fsync_path(staged)  # durable on disk BEFORE the rename, not just BEFORE this return
+            os.replace(staged, dest)
+            if sys.platform != "win32":  # os.open can't open a directory on Windows
+                with contextlib.suppress(OSError):
+                    _fsync_path(dest_dir)  # best-effort: persist the rename's directory entry too
+        except BaseException:
+            with contextlib.suppress(OSError):
+                staged.unlink()
+            raise
+    return dest
+
+
+def _verify_checksum(archive: Path, triple: str) -> None:
+    """Verify the downloaded archive against the pinned official SHA256 for its platform triple.
+
+    Fails closed: an unknown triple (no pinned hash) or any digest mismatch raises UvDownloadError, so
+    skit never extracts or runs a uv binary it could not authenticate. This is the defense that hardens
+    BOTH the GitHub path and the China-mirror / custom-host path against a compromised or corrupt
+    download — the pinned hashes come from Astral's official release, not from wherever we fetched.
+    """
+    expected = _UV_SHA256.get(triple)
+    if expected is None:  # no pin for this triple -> refuse rather than trust an unverified binary
+        raise UvDownloadError(
+            gettext("No pinned checksum for platform %(triple)s; refusing to run an unverified uv.")
+            % {"triple": triple}
+        )
+    actual = hashlib.sha256(archive.read_bytes()).hexdigest()
+    if actual != expected:
+        raise UvDownloadError(
+            gettext(
+                "Downloaded uv failed its checksum (the mirror may be compromised or the file corrupt). Expected %(expected)s, got %(actual)s."
+            )
+            % {"expected": expected, "actual": actual}
+        )
+
+
+def ensure_uv_downloaded(*, quiet: bool = False) -> str:
+    """Download the pinned uv into the private bin and return the path. If it already exists, return
+    it directly."""
+    exe_name = "uv.exe" if sys.platform == "win32" else "uv"
+    dest = private_bin_dir() / exe_name
+    if dest.exists():
+        return str(dest)
+    if not quiet and not _ask_consent(private_bin_dir()):
+        raise UvDeclinedError(
+            gettext(
+                "Download declined. Install uv yourself (https://docs.astral.sh/uv/getting-started/installation/) and skit will pick it up automatically."
+            )
+        )
+    triple = _triple()
+    url = download_url(triple)
+    if not quiet:
+        print(
+            gettext("First run — downloading uv %(version)s…") % {"version": UV_VERSION},
+            file=sys.stderr,
+            flush=True,
+        )
+    try:
+        with tempfile.TemporaryDirectory() as tmp:
+            archive = Path(tmp) / url.rsplit("/", 1)[-1]  # pragma: no mutate — [1]==[-1]
+            # A timeout is mandatory: urlretrieve has no timeout parameter, and a hung network would
+            # stall the first run forever.
+            with urllib.request.urlopen(url, timeout=60) as resp, open(archive, "wb") as f:  # noqa: S310 — url is always https: the GitHub default/presets are https, the wizard rejects a non-https custom mirror (cli._prompt_uv_binary), and config.load_mirror blanks a non-https hand-edited uv_binary (falling back to the GitHub default)
+                shutil.copyfileobj(resp, f)
+            # Verify integrity BEFORE extraction/execution: a compromised mirror or corrupt transfer
+            # must fail closed here, never reach _extract_uv + chmod +x. The UvDownloadError raised on
+            # mismatch propagates as-is (below), so the user sees the checksum error, not "Failed to
+            # download".
+            _verify_checksum(archive, triple)
+            path = _extract_uv(archive, private_bin_dir())
+    except UvDownloadError:
+        raise
+    except Exception as exc:  # wrap network/extraction failures uniformly
+        raise UvDownloadError(
+            gettext("Failed to download uv: %(error)s") % {"error": str(exc)}
+        ) from exc
+    if not quiet:
+        print(
+            gettext("uv installed at: %(path)s") % {"path": str(path)}, file=sys.stderr, flush=True
+        )
+    return str(path)