claude-dev-env 8.7.0 → 8.9.0

package/scripts/claude_account_profile.py

@@ -0,0 +1,371 @@
+#!/usr/bin/env python3
+"""Keep the second account's Claude profile linked to the main Claude home.
+
+The second account runs Claude with its own sign-in and history, and with
+everything else the main home holds: skills, rules, plugins, settings, docs::
+
+    main home                 profile home (second account)
+    skills/          <-----   skills/            link
+    CLAUDE.md        <-----   CLAUDE.md          link
+    .credentials.json         .credentials.json  its own sign-in
+    projects/                 projects/          its own history
+
+Each run converges the profile on that picture. A stale copy moves into
+``.replaced/<time>/`` with its content kept, a link whose main entry is gone
+is removed, a main link under an account-local name such as a credentials
+backup is removed, and a second run changes nothing. The run also writes the
+``claude-ev.cmd`` launcher that starts Claude on this profile.
+
+::
+
+    python claude_account_profile.py
+    {"linked": ["CLAUDE.md"], "moved_aside": [], "unlinked": [],
+     "launcher": "C:/Users/me/.local/bin/claude-ev.cmd"}
+"""
+
+from __future__ import annotations
+
+import argparse
+import filecmp
+import json
+import os
+import subprocess
+import sys
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+
+from dev_env_scripts_constants.claude_account_constants import (
+    ALL_ACCOUNT_LOCAL_NAME_PREFIXES,
+    ALL_ACCOUNT_LOCAL_NAMES,
+    ALL_WINDOWS_JUNCTION_COMMAND_PREFIX,
+    JSON_LAUNCHER_KEY,
+    JSON_LINKED_KEY,
+    JSON_MOVED_ASIDE_KEY,
+    JSON_UNLINKED_KEY,
+    ALL_LAUNCHER_DIRECTORY_RELATIVE_PARTS,
+    LAUNCHER_FILE_NAME,
+    LAUNCHER_REPLACED_SUFFIX,
+    LAUNCHER_TEXT_TEMPLATE,
+    MAIN_CLAUDE_HOME_DIRECTORY_NAME,
+    PROFILES_ROOT_DIRECTORY_NAME,
+    PROFILES_ROOT_ENVIRONMENT_VARIABLE,
+    REPLACED_DIRECTORY_NAME,
+    REPLACED_STAMP_FORMAT,
+    SECOND_ACCOUNT_PROFILE_NAME,
+    TEXT_ENCODING,
+    WINDOWS_EXTENDED_PATH_PREFIX,
+    WINDOWS_OS_NAME,
+)
+
+
+@dataclass(frozen=True)
+class ProfileSyncReport:
+    """What one sync run changed, by top-level entry name."""
+
+    all_linked: tuple[str, ...]
+    all_moved_aside: tuple[str, ...]
+    all_unlinked: tuple[str, ...]
+
+
+def default_profile_home() -> Path:
+    """Locate the second account's profile directory.
+
+    Returns:
+        The profile under the profiles root the environment names, else under
+        the default profiles root in the user home.
+    """
+    profiles_root = os.environ.get(PROFILES_ROOT_ENVIRONMENT_VARIABLE)
+    root = (
+        Path(profiles_root)
+        if profiles_root
+        else Path.home() / PROFILES_ROOT_DIRECTORY_NAME
+    )
+    return root / SECOND_ACCOUNT_PROFILE_NAME
+
+
+def is_account_local(entry_name: str) -> bool:
+    """Tell whether a Claude home entry belongs to one account only.
+
+    ::
+
+        ".credentials.json", "projects", ".claude.json.backup" -> True
+        ".credentials.json.bak"                                 -> True
+        "skills", "CLAUDE.md", "settings.json"                  -> False
+
+    Args:
+        entry_name: A top-level entry name in a Claude home.
+
+    Returns:
+        True when the entry holds one account's sign-in, state, or history.
+    """
+    return entry_name in ALL_ACCOUNT_LOCAL_NAMES or entry_name.startswith(
+        ALL_ACCOUNT_LOCAL_NAME_PREFIXES
+    )
+
+
+def _is_link(entry_path: Path) -> bool:
+    try:
+        os.readlink(entry_path)
+    except OSError:
+        return False
+    return True
+
+
+def _comparable_path(path_text: str) -> str:
+    return os.path.normcase(
+        os.path.abspath(path_text.removeprefix(WINDOWS_EXTENDED_PATH_PREFIX))
+    )
+
+
+def _link_target_text(link_path: Path) -> str:
+    target_text = os.readlink(link_path)
+    if os.path.isabs(target_text.removeprefix(WINDOWS_EXTENDED_PATH_PREFIX)):
+        return target_text
+    return os.path.join(os.path.dirname(link_path), target_text)
+
+
+def links_to(link_path: Path, source_path: Path) -> bool:
+    """Tell whether a profile entry already resolves to its main-home source.
+
+    ::
+
+        profile/rules -> main/rules      (link or junction)  -> True
+        profile/CLAUDE.md, hard link to main/CLAUDE.md        -> True
+        profile/rules -> old-shared/rules                     -> False
+        profile/CLAUDE.md, a separate copy                    -> False
+
+    Args:
+        link_path: The entry in the profile home.
+        source_path: The entry in the main home it should resolve to.
+
+    Returns:
+        True when the entry is a link to the source or the same file on disk.
+    """
+    if _is_link(link_path):
+        return _comparable_path(_link_target_text(link_path)) == _comparable_path(
+            str(source_path)
+        )
+    if link_path.is_file() and source_path.is_file():
+        return os.path.samefile(link_path, source_path)
+    return False
+
+
+def _link_directory(source_path: Path, link_path: Path) -> None:
+    if os.name == WINDOWS_OS_NAME:
+        subprocess.run(
+            [*ALL_WINDOWS_JUNCTION_COMMAND_PREFIX, str(link_path), str(source_path)],
+            check=True,
+            capture_output=True,
+        )
+        return
+    os.symlink(source_path, link_path, target_is_directory=True)
+
+
+def _link_file(source_path: Path, link_path: Path) -> None:
+    try:
+        os.symlink(source_path, link_path)
+    except OSError:
+        os.link(source_path, link_path)
+
+
+def _create_link(source_path: Path, link_path: Path) -> None:
+    if source_path.is_dir():
+        _link_directory(source_path, link_path)
+        return
+    _link_file(source_path, link_path)
+
+
+def _remove_link(link_path: Path) -> None:
+    try:
+        os.rmdir(link_path)
+    except NotADirectoryError:
+        os.unlink(link_path)
+
+
+def _is_same_content_copy(entry_path: Path, source_path: Path) -> bool:
+    return (
+        not _is_link(entry_path)
+        and entry_path.is_file()
+        and source_path.is_file()
+        and filecmp.cmp(entry_path, source_path, shallow=False)
+    )
+
+
+def _stamp(now: datetime) -> str:
+    return now.astimezone(timezone.utc).strftime(REPLACED_STAMP_FORMAT)
+
+
+def _is_inside(candidate_text: str, directory: Path) -> bool:
+    comparable_directory = _comparable_path(str(directory))
+    return _comparable_path(candidate_text).startswith(comparable_directory + os.sep)
+
+
+def _unlink_orphaned_links(main_home: Path, profile_home: Path) -> tuple[str, ...]:
+    all_unlinked: list[str] = []
+    for each_entry in sorted(profile_home.iterdir()):
+        if not _is_link(each_entry) or each_entry.exists():
+            continue
+        if not _is_inside(_link_target_text(each_entry), main_home):
+            continue
+        _remove_link(each_entry)
+        all_unlinked.append(each_entry.name)
+    return tuple(all_unlinked)
+
+
+def _unlink_local_names_linked_to_main(
+    main_home: Path, profile_home: Path
+) -> tuple[str, ...]:
+    all_unlinked: list[str] = []
+    for each_entry in sorted(profile_home.iterdir()):
+        if not is_account_local(each_entry.name):
+            continue
+        if not links_to(each_entry, main_home / each_entry.name):
+            continue
+        _remove_link(each_entry)
+        all_unlinked.append(each_entry.name)
+    return tuple(all_unlinked)
+
+
+def _clear_entry(entry_path: Path, source_path: Path, replaced_directory: Path) -> bool:
+    if _is_same_content_copy(entry_path, source_path):
+        entry_path.unlink()
+        return False
+    replaced_directory.mkdir(parents=True, exist_ok=True)
+    os.replace(entry_path, replaced_directory / entry_path.name)
+    return True
+
+
+def _link_shared_entries(
+    main_home: Path, profile_home: Path, replaced_directory: Path
+) -> tuple[tuple[str, ...], tuple[str, ...]]:
+    all_linked: list[str] = []
+    all_moved_aside: list[str] = []
+    for each_source in sorted(main_home.iterdir()):
+        entry_path = profile_home / each_source.name
+        if is_account_local(each_source.name) or links_to(entry_path, each_source):
+            continue
+        if os.path.lexists(entry_path) and _clear_entry(
+            entry_path, each_source, replaced_directory
+        ):
+            all_moved_aside.append(each_source.name)
+        _create_link(each_source, entry_path)
+        all_linked.append(each_source.name)
+    return tuple(all_linked), tuple(all_moved_aside)
+
+
+def sync_profile(
+    *, main_home: Path, profile_home: Path, now: datetime
+) -> ProfileSyncReport:
+    """Link every shared main-home entry into the profile home.
+
+    Args:
+        main_home: The main account's Claude home.
+        profile_home: The second account's Claude home.
+        now: The run time that names the folder stale entries move into.
+
+    Returns:
+        The entries the run linked, moved aside, and unlinked.
+    """
+    profile_home.mkdir(parents=True, exist_ok=True)
+    all_unlinked = tuple(
+        sorted(
+            _unlink_orphaned_links(main_home, profile_home)
+            + _unlink_local_names_linked_to_main(main_home, profile_home)
+        )
+    )
+    all_linked, all_moved_aside = _link_shared_entries(
+        main_home, profile_home, profile_home / REPLACED_DIRECTORY_NAME / _stamp(now)
+    )
+    return ProfileSyncReport(
+        all_linked=all_linked,
+        all_moved_aside=all_moved_aside,
+        all_unlinked=all_unlinked,
+    )
+
+
+def _moved_launcher_name(now: datetime) -> str:
+    return f"{LAUNCHER_FILE_NAME}{LAUNCHER_REPLACED_SUFFIX}{_stamp(now)}"
+
+
+def write_launcher(
+    *, launcher_directory: Path, profile_home: Path, now: datetime
+) -> Path:
+    """Write the launcher that runs Claude under the second account's profile.
+
+    ::
+
+        claude-ev -p "fix the test"
+        -> CLAUDE_CONFIG_DIR=<profile home>, then claude -p "fix the test"
+        an older claude-ev.cmd -> claude-ev.cmd.replaced-<time>
+
+    Args:
+        launcher_directory: The directory on PATH that holds the launcher.
+        profile_home: The second account's Claude home.
+        now: The run time that names a moved older launcher.
+
+    Returns:
+        The launcher path.
+    """
+    launcher_path = launcher_directory / LAUNCHER_FILE_NAME
+    launcher_text = LAUNCHER_TEXT_TEMPLATE.format(profile_home=profile_home)
+    launcher_bytes = launcher_text.encode(TEXT_ENCODING)
+    if launcher_path.is_file() and launcher_path.read_bytes() == launcher_bytes:
+        return launcher_path
+    if launcher_path.is_file():
+        os.replace(launcher_path, launcher_path.with_name(_moved_launcher_name(now)))
+    launcher_directory.mkdir(parents=True, exist_ok=True)
+    launcher_path.write_bytes(launcher_bytes)
+    return launcher_path
+
+
+def _build_argument_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Link the main Claude home into the second account's profile."
+    )
+    parser.add_argument(
+        "--main-home", type=Path, default=Path.home() / MAIN_CLAUDE_HOME_DIRECTORY_NAME
+    )
+    parser.add_argument("--profile-home", type=Path, default=default_profile_home())
+    parser.add_argument(
+        "--launcher-directory",
+        type=Path,
+        default=Path.home().joinpath(*ALL_LAUNCHER_DIRECTORY_RELATIVE_PARTS),
+    )
+    return parser
+
+
+def main(all_command_arguments: list[str]) -> int:
+    """Sync the profile, write the launcher, and print what changed as JSON.
+
+    Args:
+        all_command_arguments: Command-line arguments after the program name.
+
+    Returns:
+        Zero once the profile and launcher match the main home.
+    """
+    arguments = _build_argument_parser().parse_args(all_command_arguments)
+    now = datetime.now(timezone.utc)
+    report = sync_profile(
+        main_home=arguments.main_home, profile_home=arguments.profile_home, now=now
+    )
+    launcher_path = write_launcher(
+        launcher_directory=arguments.launcher_directory,
+        profile_home=arguments.profile_home,
+        now=now,
+    )
+    print(
+        json.dumps(
+            {
+                JSON_LINKED_KEY: list(report.all_linked),
+                JSON_MOVED_ASIDE_KEY: list(report.all_moved_aside),
+                JSON_UNLINKED_KEY: list(report.all_unlinked),
+                JSON_LAUNCHER_KEY: str(launcher_path),
+            }
+        )
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/scripts/claude_chain_usage.py

@@ -136,8 +136,25 @@ def _load_resolve_usage_window_module() -> ModuleType:
     return loaded_module
 
 
-def _probe_weekly_utilization(credentials_path: Path) -> float:
-    usage_window_resolver = _load_resolve_usage_window_module()
+@dataclass(frozen=True)
+class AccountUsageMeters:
+    """One account's 5-hour and weekly meters, each field None when unread.
+
+    ::
+
+        {"five_hour": {"utilization": 42, ...}, "seven_day": {...}}
+        -> AccountUsageMeters(42.0, <5-hour reset>, 63.0, <weekly reset>)
+    """
+
+    session_utilization: float | None
+    session_resets_at: datetime | None
+    weekly_utilization: float | None
+    weekly_resets_at: datetime | None
+
+
+def _fetch_account_usage_payload(
+    usage_window_resolver: ModuleType, credentials_path: Path
+) -> dict[str, object]:
     now = datetime.now().astimezone()
     try:
         access_token = usage_window_resolver.read_oauth_access_token(
@@ -147,7 +164,7 @@ def _probe_weekly_utilization(credentials_path: Path) -> float:
             raise WeeklyUtilizationProbeError(
                 NO_ACCESS_TOKEN_ERROR_TEMPLATE.format(credentials_path=credentials_path)
             )
-        usage_payload = usage_window_resolver._fetch_usage_payload(access_token)
+        return usage_window_resolver._fetch_usage_payload(access_token)
     except WeeklyUtilizationProbeError:
         raise
     except (
@@ -160,10 +177,37 @@ def _probe_weekly_utilization(credentials_path: Path) -> float:
         raise WeeklyUtilizationProbeError(
             USAGE_PROBE_FAILED_ERROR_TEMPLATE.format(error=probe_error)
         ) from probe_error
+
+
+def probe_account_meters(credentials_path: Path) -> AccountUsageMeters:
+    """Read one account's usage meters through the usage-pause OAuth probe.
+
+    Args:
+        credentials_path: The account's CLI credential file.
+
+    Returns:
+        The account's 5-hour and weekly meters.
+
+    Raises:
+        WeeklyUtilizationProbeError: When the credential yields no usable token
+            or the probe request fails.
+    """
+    usage_window_resolver = _load_resolve_usage_window_module()
+    usage_payload = _fetch_account_usage_payload(usage_window_resolver, credentials_path)
     usage_windows = usage_window_resolver.extract_usage_windows(usage_payload)
-    if usage_windows.weekly_utilization is None:
+    return AccountUsageMeters(
+        session_utilization=usage_windows.session_utilization,
+        session_resets_at=usage_windows.session_resets_at,
+        weekly_utilization=usage_windows.weekly_utilization,
+        weekly_resets_at=usage_windows.weekly_resets_at,
+    )
+
+
+def _probe_weekly_utilization(credentials_path: Path) -> float:
+    weekly_utilization = probe_account_meters(credentials_path).weekly_utilization
+    if weekly_utilization is None:
         raise WeeklyUtilizationProbeError(WEEKLY_UTILIZATION_MISSING_ERROR)
-    return float(usage_windows.weekly_utilization)
+    return float(weekly_utilization)
 
 
 weekly_utilization_probe: WeeklyUtilizationProbe = _probe_weekly_utilization

package/scripts/dev_env_scripts_constants/claude_account_constants.py

@@ -0,0 +1,181 @@
+"""Named constants for the second Claude account: its profile, launcher, and picker.
+
+The profile sync links the main Claude home into a second account's profile
+directory. The launcher points Claude at that profile. The picker reads both
+accounts' usage meters and names the account a job runs on, protecting the
+main account so its owner never runs out.
+"""
+
+from __future__ import annotations
+
+from datetime import timedelta
+
+MAIN_CLAUDE_HOME_DIRECTORY_NAME: str = ".claude"
+"""Directory under the user home that holds the main account's Claude home."""
+
+PROFILES_ROOT_DIRECTORY_NAME: str = ".claude-profiles"
+"""Directory under the user home that holds named Claude profiles."""
+
+PROFILES_ROOT_ENVIRONMENT_VARIABLE: str = "LLM_SETTINGS_PROFILES_ROOT"
+"""Environment variable that relocates the profiles root."""
+
+SECOND_ACCOUNT_PROFILE_NAME: str = "ev"
+"""Profile directory name the second account signs in under."""
+
+ALL_LAUNCHER_DIRECTORY_RELATIVE_PARTS: tuple[str, ...] = (".local", "bin")
+"""Path parts under the user home of the directory on PATH that holds the launcher."""
+
+LAUNCHER_FILE_NAME: str = "claude-ev.cmd"
+"""File name of the launcher that runs Claude under the second account."""
+
+LAUNCHER_TEXT_TEMPLATE: str = (
+    "@echo off\r\n"
+    "setlocal\r\n"
+    'set "CLAUDE_CONFIG_DIR={profile_home}"\r\n'
+    "claude %*\r\n"
+    "exit /b %ERRORLEVEL%\r\n"
+)
+"""Launcher body: point Claude at the profile and pass every argument through."""
+
+LAUNCHER_REPLACED_SUFFIX: str = ".replaced-"
+"""Suffix, before the run time, of an older launcher the sync moved aside."""
+
+ALL_WINDOWS_JUNCTION_COMMAND_PREFIX: tuple[str, ...] = ("cmd", "/c", "mklink", "/J")
+"""Command that links a directory as a junction on Windows, before link and target."""
+
+CREDENTIALS_FILE_NAME: str = ".credentials.json"
+"""File in a Claude home that holds that account's sign-in."""
+
+ALL_ACCOUNT_LOCAL_NAMES: frozenset[str] = frozenset(
+    {
+        ".credentials.json",
+        "projects",
+        "sessions",
+        "session-env",
+        "shell-snapshots",
+        "todos",
+        "statsig",
+        "file-history",
+        "history.jsonl",
+        "ide",
+        "debug",
+        "telemetry",
+        "logs",
+        "tasks",
+        "plans",
+        "backups",
+        "cache",
+        "paste-cache",
+        "stats-cache.json",
+    }
+)
+"""Top-level Claude home entries that belong to one account and are never linked."""
+
+ALL_ACCOUNT_LOCAL_NAME_PREFIXES: tuple[str, ...] = (".claude.json", ".credentials.json")
+"""Name prefixes of per-account state files, covering the global config and its backups."""
+
+REPLACED_DIRECTORY_NAME: str = ".replaced"
+"""Profile subdirectory that holds entries the sync moved aside, one folder per run."""
+
+REPLACED_STAMP_FORMAT: str = "%Y%m%dT%H%M%SZ"
+"""UTC time format naming each run's folder under the replaced directory."""
+
+WINDOWS_EXTENDED_PATH_PREFIX: str = "\\\\?\\"
+"""Prefix Windows puts on a junction target that the link comparison strips."""
+
+WINDOWS_OS_NAME: str = "nt"
+"""Value of ``os.name`` on Windows, where directories link as junctions."""
+
+TEXT_ENCODING: str = "utf-8"
+"""Encoding for the launcher file and the JSON reports."""
+
+MAIN_SPEND_WINDOW: timedelta = timedelta(hours=24)
+"""Main takes jobs only when its weekly window resets within this span."""
+
+MAIN_WEEKLY_USED_CEILING_PERCENT: float = 90.0
+"""Main takes jobs only while its weekly use is under this percent."""
+
+MAIN_SESSION_USED_CEILING_PERCENT: float = 50.0
+"""Main takes jobs only while its 5-hour use is under this percent."""
+
+SECOND_WEEKLY_USED_CEILING_PERCENT: float = 95.0
+"""The second account takes jobs while its weekly use is under this percent."""
+
+SECOND_SESSION_USED_CEILING_PERCENT: float = 90.0
+"""The second account takes jobs while its 5-hour use is under this percent."""
+
+FULL_PERCENT: float = 100.0
+"""Percent scale ceiling, so remaining is this minus used."""
+
+SECONDS_PER_HOUR: int = 3600
+"""Seconds in one hour, for reason text that names hours until a reset."""
+
+CHOICE_MAIN: str = "main"
+"""Picker answer: run the job on the main account."""
+
+CHOICE_SECOND: str = "second"
+"""Picker answer: run the job on the second account."""
+
+CHOICE_WAIT: str = "wait"
+"""Picker answer: neither account has room, so the job waits."""
+
+REASON_MAIN_EXPIRING_TEMPLATE: str = (
+    "main week resets in {hours_until_reset} hours with {remaining_percent:.0f}% left"
+)
+"""Reason when main spends leftover usage that expires soon."""
+
+REASON_SECOND_HAS_ROOM_TEMPLATE: str = (
+    "second account has {weekly_remaining_percent:.0f}% of its week"
+    " and {session_remaining_percent:.0f}% of its 5-hour window left"
+)
+"""Reason when the second account takes the job."""
+
+REASON_SECOND_UNREAD: str = (
+    "second account meter unreadable; its own run refreshes the sign-in"
+)
+"""Reason when the second account's meter cannot be read and it takes the job anyway."""
+
+REASON_WAIT_TEMPLATE: str = (
+    "second account is at {weekly_used_percent:.0f}% of its week"
+    " and {session_used_percent:.0f}% of its 5-hour window; next reset {next_reset}"
+)
+"""Reason when neither account has room."""
+
+UNKNOWN_RESET_TEXT: str = "unknown"
+"""Reset text when the blocking meter carries no reset time."""
+
+JSON_ACCOUNT_KEY: str = "account"
+"""Picker JSON key naming the chosen account."""
+
+JSON_CONFIG_DIRECTORY_KEY: str = "config_dir"
+"""Picker JSON key naming the Claude home the chosen account runs under."""
+
+JSON_REASON_KEY: str = "reason"
+"""Picker JSON key carrying the plain-words reason for the choice."""
+
+JSON_METERS_KEY: str = "meters"
+"""Picker JSON key carrying both accounts' meters, each None when unread."""
+
+JSON_SESSION_USED_PERCENT_KEY: str = "session_used_percent"
+"""Meters JSON key for the percent of the 5-hour window used."""
+
+JSON_SESSION_RESETS_AT_KEY: str = "session_resets_at"
+"""Meters JSON key for when the 5-hour window resets."""
+
+JSON_WEEKLY_USED_PERCENT_KEY: str = "weekly_used_percent"
+"""Meters JSON key for the percent of the week used."""
+
+JSON_WEEKLY_RESETS_AT_KEY: str = "weekly_resets_at"
+"""Meters JSON key for when the week resets."""
+
+JSON_LINKED_KEY: str = "linked"
+"""Sync JSON key listing entries the run linked."""
+
+JSON_MOVED_ASIDE_KEY: str = "moved_aside"
+"""Sync JSON key listing entries the run moved into the replaced directory."""
+
+JSON_UNLINKED_KEY: str = "unlinked"
+"""Sync JSON key listing links the run removed because main no longer has the entry."""
+
+JSON_LAUNCHER_KEY: str = "launcher"
+"""Sync JSON key naming the launcher file the run wrote or confirmed."""

package/scripts/dev_env_scripts_constants/gh_artifact_upload_constants.py

@@ -41,3 +41,30 @@ NOTES_FILE_SUFFIX: str = ".md"
 
 UTF8_ENCODING: str = "utf-8"
 """Text encoding for subprocess output and temp files."""
+
+PNG_SUFFIX: str = ".png"
+"""Suffix of a file the upload shrinks with oxipng before it sends."""
+
+OXIPNG_BINARY_NAME: str = "oxipng"
+"""The oxipng executable name, looked up on PATH."""
+
+ALL_OXIPNG_LOSSLESS_ARGUMENTS: tuple[str, ...] = (
+    "--opt",
+    "4",
+    "--strip",
+    "none",
+    "--nb",
+    "--nc",
+    "--quiet",
+)
+"""Oxipng options: a slow lossless search that keeps every chunk, the bit
+depth, and the color type."""
+
+OXIPNG_MISSING_MESSAGE: str = (
+    "oxipng is not on PATH. Install the release binary from "
+    "https://github.com/oxipng/oxipng/releases, then upload again."
+)
+"""Failure text when a PNG upload finds no oxipng to shrink it first."""
+
+SIZE_REPORT_TEMPLATE: str = "{name}: {original_size} -> {optimized_size} bytes"
+"""Line naming an upload and its size before and after oxipng."""