secpipw 1.0.0__tar.gz

secpipw-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (C) 2026 Weilin Du
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

secpipw-1.0.0/PKG-INFO

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: secpipw
+Version: 1.0.0
+Summary: A defensive pip wrapper with supply-chain preflight checks.
+Author: Weilin Du (LamentXU)
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: packaging<26,>=24.0
+Requires-Dist: python-Levenshtein<0.28,>=0.27
+Dynamic: license-file
+
+*Not Finished Yet. Contribution Welcome. Site at https://spip.lamentxu.top/*
+# secpipw
+English | [简体中文](./README.zh-CN.md)
+
+[![Test](https://github.com/LamentXU123/spip/actions/workflows/test.yml/badge.svg)](https://github.com/LamentXU123/spip/actions/workflows/test.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+![Python_version](https://img.shields.io/pypi/pyversions/secpipw.svg?logo=python&logoColor=FBE071)
+![PyPI Version](https://img.shields.io/pypi/v/secpipw)
+[![Codecov](https://codecov.io/gh/LamentXU123/spip/graph/badge.svg)](https://codecov.io/gh/LamentXU123/spip)
+
+An open-source, free, powerful, light-weight guard for your pip to avoid supply-chain attacks.
+
+By using this, you can avoid being screwed by the poisoned LiteLLM, etc. just because you type `pip install`
+
+Although `secpipw` is designed for low learning budget, we still recommend you to read our [docs](https://spip.lamentxu.top/docs) before you try this product in your production environment.
+
+## What?
+
+Currently, supply chain attacks are one of the major security concerns all over the world. The `secpipw` project is a future `pip` wrapper focused on supply-chain risk controls.
+
+## Wait, What?
+
+You can use
+
+```bash
+spip install requests
+```
+
+Instead of
+
+```bash
+pip install requests
+```
+
+To install a package more safely in the scope of supply chain security.
+
+You do not need to configure. You do not need to learn. Just pure install-to-master.
+
+In other words, you can completely replace `pip install` with `spip install` to make your installation safer :)
+
+## Package manager support
+
+secpipw now has diversified package-manager support:
+
+- [x] `pip`: `spip install requests`
+- [x] `pipx`: `spipx install black`
+- [x] `poetry`: `spoetry add requests`
+- [x] `uv`: `suv pip install requests`
+- [ ] `conda`: planned
+
+You can guard common `pipx`, `poetry`, and `uv` package additions:
+
+```bash
+spipx install black
+spoetry add requests
+suv pip install requests
+```
+
+The package installs `spipx`, `spoetry`, and `suv` dedicated entry points.
+Supported guarded commands are
+`pipx install`, `pipx inject`, `pipx run`, `poetry add`, `poetry self add`,
+`uv pip install`, `uv add`, `uv tool install`, and `uv tool run`. Other
+non-install commands are passed through unchanged. Commands that would install
+packages but cannot be translated into a pip install plan, such as
+`pipx upgrade`, `poetry add --source internal ...`, or `uv run ...`, are refused
+instead of running without checks.
+
+If you want a near drop-in experience, you can set a shell alias from `pip` to `spip`.
+
+Command Prompt (Windows):
+
+```cmd
+pip install secpipw
+doskey pip=spip $*
+```
+
+Bash (Linux):
+
+```bash
+pip install secpipw
+echo "alias pip='spip'" >> ~/.bashrc
+source ~/.bashrc
+```
+
+Zsh (macOS):
+
+```zsh
+pip install secpipw
+echo "alias pip='spip'" >> ~/.zshrc
+source ~/.zshrc
+```
+
+The `secpipw` project will actively check for all the supply chain risks and avoid you installing potentially malicious packages when typing `spip install`
+
+For `install`, `secpipw` uses pip's own resolver and then checks the selected install plan before pip builds or installs the resolved distributions. If the checks pass, the same pip install flow continues; `secpipw` does not run a second `pip install` for the already-resolved packages.
+
+Except for the `install` commands, the project behaves exactly the same as the original `pip` program. That is, you can always use `spip` instead of `pip` in any case :)
+
+For `pipx`, `poetry`, and `uv`, secpipw runs a pip-compatible preflight
+resolution and artifact check before handing control to the original tool. The
+original tool still performs the actual environment update.
+
+For more details, please see our docs: https://spip.lamentxu.top/docs
+
+## What problem do secpipw solved?
+
+Supply-chain poisoning has always been a persistent security problem. Existing solutions include mature but expensive-to-run tools like GuardDog, and lightweight tools like sfw that rely entirely on a paid Socket API. GuardDog is too heavy for everyday CI usage and is better suited to static analysis by security researchers. Running GuardDog against every artifact downloaded by `pip install`, including all dependencies, would slow installs down. sfw is lighter, but its dependence on a paid API creates another cost for everyday developers.
+
+secpipw solves this by hooking into pip's installer and merging security checks directly into the pip install download and installation flow. At the same time, the performance impact is usually small. secpipw is completely free for everyone.
+
+Today, many independent developers have suffered CI server compromises that leak secret keys and cause serious damage. With secpipw installed, that risk is greatly reduced, while requiring no payment, no extra performance budget, and no learning or configuration. Install it once with `pip install secpipw`, set an alias once, and keep using pip while gaining an important protection layer in the background.
+
+## Warning policies
+
+## TODO
+
+Contributions welcome:
+
+- Framework
+    - [x] Support guarded `uv pip install`, `uv add`, `uv tool install`, and `uv tool run`
+    - [x] Support guarded `pipx install`, `pipx inject`, and `pipx run`
+    - [x] Support guarded `poetry add` and `poetry self add`
+    - [ ] Support `conda`
+- CI
+    - [x] Write a benchmark CI in the github workflow to compare the performance of `spip install` and `pip install`
+- Documentation
+    - [ ] Use some modern documentation framework to refactor the /doc/docs directory.
+    - [ ] Support website view on mobile phones. @didongji91
+- Checks
+    - [x] Record and compare installed package entry-point and `.pth` baselines across `spip` installs
+        - [x] If new or changed `.pth` file is added
+        - [x] If entry-point metadata or script files change
+    - [x] Detect yanked releases from pip's resolved install report
+    - [x] Compare archive hashes with already available PyPI release metadata
+    - [ ] Add check of the diff between the last version of the package and the to-be-installed version, search for malicious changes
+        - [ ] If setup.py has been changed
+
+We currently have three install warning policies:
+
+- `HIGH`: pause installation and require `--spip-ignore-warning`
+- `MEDIUM`: prompt `y/n` before continuing
+- `LOW`: warn and continue
+
+The default sensitivity is `low`, which uses the policy above. You can make
+the gate stricter with `--sensitivity medium` or `--sensitivity high`:
+
+- `--sensitivity medium`: `MEDIUM` and above pause installation; `LOW` prompts.
+- `--sensitivity high`: `LOW` and above pause installation.
+
+Use `--spip-ignore <level>` to completely ignore warnings at that severity and below.
+For example, `--spip-ignore LOW` suppresses `LOW` warnings, while `--spip-ignore MEDIUM`
+suppresses both `LOW` and `MEDIUM` warnings. Ignored warnings are not printed,
+and checks that can only produce ignored severities are skipped.
+
+## Caches
+
+secpipw stores PyPI name, release-time, and maintainer email history caches in
+the user's cache directory by default, so the same cache is reused across projects.
+Set `SPIP_CACHE_DIR` to override the cache directory.
+
+## Benchmark
+
+Run the local benchmark with:
+
+```bash
+python scripts/benchmark_install.py --runs 5 --warmups 0
+```
+
+The default benchmark compares `pip install ruff` and `spip install ruff`,
+timing package download and installation together. It uses `--no-cache-dir`,
+`--no-deps`, and a fresh `--target` directory for each measured run, so the
+result focuses on repeated installs of one well-known package body rather than a
+dependency tree. The Benchmark GitHub Actions workflow runs on relevant `main` changes, on a
+weekly schedule, or by manual dispatch. It publishes the latest
+`benchmark.json` to the remote `benchmark-data` branch, and the website renders
+`x1.0742`-style median ratios from that data. Benchmark updates do not advance
+`main`.
+
+When `secpipw` detects a potential risk, a warning will be raised, with the level depending on the severity the risk is.
+
+For now, the project has several major check points:
+
+- [x] Fake typo checks: Hackers often use "fake typos" to inject a malicious dependency package into the poisoned source file. `secpipw` detects this by first resolving all the packages that `pip install` is going to download, and then comparing non-popular resolved package names with a local hot-package list. Warning levels:
+    - Medium severity: `requsets` vs `requests`
+    - Medium severity: `panda` vs `pandas`
+    - Low severity: `sixth` vs `six`
+- [x] Direct URL dependency checks: If the install target or a resolved dependency uses a direct URL, VCS URL, or PEP 508 direct reference, `secpipw` will raise a `MEDIUM` warning.
+- [x] Fresh release checks: If the selected PyPI release was published less than 8 hours ago, `secpipw` will raise a `MEDIUM` warning; if it was published less than 48 hours ago, `secpipw` will raise a `LOW` warning.
+- [x] Yanked release checks: If pip resolves a release that is marked as yanked, `secpipw` will raise a `MEDIUM` warning using pip's install report.
+- [x] Archive hash checks: If PyPI release metadata is already available and the selected wheel/sdist digest does not match the resolved archive hash, `secpipw` will raise a `HIGH` warning.
+- [x] Empty description checks: If the selected PyPI release metadata has no summary and no long description, `secpipw` will raise a `LOW` warning.
+- [x] Suspicious metadata URL checks: If PyPI metadata points to a shortener, raw IP, suspicious TLD, embedded credentials, or similar suspicious URL, `secpipw` will raise a `LOW` warning.
+- [x] Repository mismatch checks: If PyPI metadata points to a GitHub/GitLab repository whose repo name appears unrelated to the package name, `secpipw` will raise a `LOW` warning.
+- [x] Maintainer email domain drift checks: If a package's maintainer email domain changes compared with the local `secpipw` history cache, `secpipw` will raise a `LOW` warning.
+- [x] Zero-version checks: If the selected package version is `0.0` or `0.0.0`, `secpipw` will raise a `LOW` warning.
+- [x] `.pth` file detection: Instead of directly injecting malicious code inside the package, today most hackers will place their bad stuff under a `.pth` file, with an `import` as the beginning. `secpipw` only checks the installed file-system diff after installation. The warning level is always `MEDIUM`, and `secpipw` will ask whether to delete the suspicious installed `.pth` file.
+- [ ] TODO ...

secpipw-1.0.0/README.md

@@ -0,0 +1,197 @@
+*Not Finished Yet. Contribution Welcome. Site at https://spip.lamentxu.top/*
+# secpipw
+English | [简体中文](./README.zh-CN.md)
+
+[![Test](https://github.com/LamentXU123/spip/actions/workflows/test.yml/badge.svg)](https://github.com/LamentXU123/spip/actions/workflows/test.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+![Python_version](https://img.shields.io/pypi/pyversions/secpipw.svg?logo=python&logoColor=FBE071)
+![PyPI Version](https://img.shields.io/pypi/v/secpipw)
+[![Codecov](https://codecov.io/gh/LamentXU123/spip/graph/badge.svg)](https://codecov.io/gh/LamentXU123/spip)
+
+An open-source, free, powerful, light-weight guard for your pip to avoid supply-chain attacks.
+
+By using this, you can avoid being screwed by the poisoned LiteLLM, etc. just because you type `pip install`
+
+Although `secpipw` is designed for low learning budget, we still recommend you to read our [docs](https://spip.lamentxu.top/docs) before you try this product in your production environment.
+
+## What?
+
+Currently, supply chain attacks are one of the major security concerns all over the world. The `secpipw` project is a future `pip` wrapper focused on supply-chain risk controls.
+
+## Wait, What?
+
+You can use
+
+```bash
+spip install requests
+```
+
+Instead of
+
+```bash
+pip install requests
+```
+
+To install a package more safely in the scope of supply chain security.
+
+You do not need to configure. You do not need to learn. Just pure install-to-master.
+
+In other words, you can completely replace `pip install` with `spip install` to make your installation safer :)
+
+## Package manager support
+
+secpipw now has diversified package-manager support:
+
+- [x] `pip`: `spip install requests`
+- [x] `pipx`: `spipx install black`
+- [x] `poetry`: `spoetry add requests`
+- [x] `uv`: `suv pip install requests`
+- [ ] `conda`: planned
+
+You can guard common `pipx`, `poetry`, and `uv` package additions:
+
+```bash
+spipx install black
+spoetry add requests
+suv pip install requests
+```
+
+The package installs `spipx`, `spoetry`, and `suv` dedicated entry points.
+Supported guarded commands are
+`pipx install`, `pipx inject`, `pipx run`, `poetry add`, `poetry self add`,
+`uv pip install`, `uv add`, `uv tool install`, and `uv tool run`. Other
+non-install commands are passed through unchanged. Commands that would install
+packages but cannot be translated into a pip install plan, such as
+`pipx upgrade`, `poetry add --source internal ...`, or `uv run ...`, are refused
+instead of running without checks.
+
+If you want a near drop-in experience, you can set a shell alias from `pip` to `spip`.
+
+Command Prompt (Windows):
+
+```cmd
+pip install secpipw
+doskey pip=spip $*
+```
+
+Bash (Linux):
+
+```bash
+pip install secpipw
+echo "alias pip='spip'" >> ~/.bashrc
+source ~/.bashrc
+```
+
+Zsh (macOS):
+
+```zsh
+pip install secpipw
+echo "alias pip='spip'" >> ~/.zshrc
+source ~/.zshrc
+```
+
+The `secpipw` project will actively check for all the supply chain risks and avoid you installing potentially malicious packages when typing `spip install`
+
+For `install`, `secpipw` uses pip's own resolver and then checks the selected install plan before pip builds or installs the resolved distributions. If the checks pass, the same pip install flow continues; `secpipw` does not run a second `pip install` for the already-resolved packages.
+
+Except for the `install` commands, the project behaves exactly the same as the original `pip` program. That is, you can always use `spip` instead of `pip` in any case :)
+
+For `pipx`, `poetry`, and `uv`, secpipw runs a pip-compatible preflight
+resolution and artifact check before handing control to the original tool. The
+original tool still performs the actual environment update.
+
+For more details, please see our docs: https://spip.lamentxu.top/docs
+
+## What problem do secpipw solved?
+
+Supply-chain poisoning has always been a persistent security problem. Existing solutions include mature but expensive-to-run tools like GuardDog, and lightweight tools like sfw that rely entirely on a paid Socket API. GuardDog is too heavy for everyday CI usage and is better suited to static analysis by security researchers. Running GuardDog against every artifact downloaded by `pip install`, including all dependencies, would slow installs down. sfw is lighter, but its dependence on a paid API creates another cost for everyday developers.
+
+secpipw solves this by hooking into pip's installer and merging security checks directly into the pip install download and installation flow. At the same time, the performance impact is usually small. secpipw is completely free for everyone.
+
+Today, many independent developers have suffered CI server compromises that leak secret keys and cause serious damage. With secpipw installed, that risk is greatly reduced, while requiring no payment, no extra performance budget, and no learning or configuration. Install it once with `pip install secpipw`, set an alias once, and keep using pip while gaining an important protection layer in the background.
+
+## Warning policies
+
+## TODO
+
+Contributions welcome:
+
+- Framework
+    - [x] Support guarded `uv pip install`, `uv add`, `uv tool install`, and `uv tool run`
+    - [x] Support guarded `pipx install`, `pipx inject`, and `pipx run`
+    - [x] Support guarded `poetry add` and `poetry self add`
+    - [ ] Support `conda`
+- CI
+    - [x] Write a benchmark CI in the github workflow to compare the performance of `spip install` and `pip install`
+- Documentation
+    - [ ] Use some modern documentation framework to refactor the /doc/docs directory.
+    - [ ] Support website view on mobile phones. @didongji91
+- Checks
+    - [x] Record and compare installed package entry-point and `.pth` baselines across `spip` installs
+        - [x] If new or changed `.pth` file is added
+        - [x] If entry-point metadata or script files change
+    - [x] Detect yanked releases from pip's resolved install report
+    - [x] Compare archive hashes with already available PyPI release metadata
+    - [ ] Add check of the diff between the last version of the package and the to-be-installed version, search for malicious changes
+        - [ ] If setup.py has been changed
+
+We currently have three install warning policies:
+
+- `HIGH`: pause installation and require `--spip-ignore-warning`
+- `MEDIUM`: prompt `y/n` before continuing
+- `LOW`: warn and continue
+
+The default sensitivity is `low`, which uses the policy above. You can make
+the gate stricter with `--sensitivity medium` or `--sensitivity high`:
+
+- `--sensitivity medium`: `MEDIUM` and above pause installation; `LOW` prompts.
+- `--sensitivity high`: `LOW` and above pause installation.
+
+Use `--spip-ignore <level>` to completely ignore warnings at that severity and below.
+For example, `--spip-ignore LOW` suppresses `LOW` warnings, while `--spip-ignore MEDIUM`
+suppresses both `LOW` and `MEDIUM` warnings. Ignored warnings are not printed,
+and checks that can only produce ignored severities are skipped.
+
+## Caches
+
+secpipw stores PyPI name, release-time, and maintainer email history caches in
+the user's cache directory by default, so the same cache is reused across projects.
+Set `SPIP_CACHE_DIR` to override the cache directory.
+
+## Benchmark
+
+Run the local benchmark with:
+
+```bash
+python scripts/benchmark_install.py --runs 5 --warmups 0
+```
+
+The default benchmark compares `pip install ruff` and `spip install ruff`,
+timing package download and installation together. It uses `--no-cache-dir`,
+`--no-deps`, and a fresh `--target` directory for each measured run, so the
+result focuses on repeated installs of one well-known package body rather than a
+dependency tree. The Benchmark GitHub Actions workflow runs on relevant `main` changes, on a
+weekly schedule, or by manual dispatch. It publishes the latest
+`benchmark.json` to the remote `benchmark-data` branch, and the website renders
+`x1.0742`-style median ratios from that data. Benchmark updates do not advance
+`main`.
+
+When `secpipw` detects a potential risk, a warning will be raised, with the level depending on the severity the risk is.
+
+For now, the project has several major check points:
+
+- [x] Fake typo checks: Hackers often use "fake typos" to inject a malicious dependency package into the poisoned source file. `secpipw` detects this by first resolving all the packages that `pip install` is going to download, and then comparing non-popular resolved package names with a local hot-package list. Warning levels:
+    - Medium severity: `requsets` vs `requests`
+    - Medium severity: `panda` vs `pandas`
+    - Low severity: `sixth` vs `six`
+- [x] Direct URL dependency checks: If the install target or a resolved dependency uses a direct URL, VCS URL, or PEP 508 direct reference, `secpipw` will raise a `MEDIUM` warning.
+- [x] Fresh release checks: If the selected PyPI release was published less than 8 hours ago, `secpipw` will raise a `MEDIUM` warning; if it was published less than 48 hours ago, `secpipw` will raise a `LOW` warning.
+- [x] Yanked release checks: If pip resolves a release that is marked as yanked, `secpipw` will raise a `MEDIUM` warning using pip's install report.
+- [x] Archive hash checks: If PyPI release metadata is already available and the selected wheel/sdist digest does not match the resolved archive hash, `secpipw` will raise a `HIGH` warning.
+- [x] Empty description checks: If the selected PyPI release metadata has no summary and no long description, `secpipw` will raise a `LOW` warning.
+- [x] Suspicious metadata URL checks: If PyPI metadata points to a shortener, raw IP, suspicious TLD, embedded credentials, or similar suspicious URL, `secpipw` will raise a `LOW` warning.
+- [x] Repository mismatch checks: If PyPI metadata points to a GitHub/GitLab repository whose repo name appears unrelated to the package name, `secpipw` will raise a `LOW` warning.
+- [x] Maintainer email domain drift checks: If a package's maintainer email domain changes compared with the local `secpipw` history cache, `secpipw` will raise a `LOW` warning.
+- [x] Zero-version checks: If the selected package version is `0.0` or `0.0.0`, `secpipw` will raise a `LOW` warning.
+- [x] `.pth` file detection: Instead of directly injecting malicious code inside the package, today most hackers will place their bad stuff under a `.pth` file, with an `import` as the beginning. `secpipw` only checks the installed file-system diff after installation. The warning level is always `MEDIUM`, and `secpipw` will ask whether to delete the suspicious installed `.pth` file.
+- [ ] TODO ...

secpipw-1.0.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+license = "MIT"
+name = "secpipw"
+version = "1.0.0"
+description = "A defensive pip wrapper with supply-chain preflight checks."
+readme = "README.md"
+requires-python = ">=3.10"
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+]
+authors = [
+  { name = "Weilin Du (LamentXU)" }
+]
+dependencies = [
+  "packaging>=24.0,<26",
+  "python-Levenshtein>=0.27,<0.28"
+]
+
+[project.scripts]
+spip = "secpipw.cli:main"
+spipx = "secpipw.cli:pipx_main"
+spoetry = "secpipw.cli:poetry_main"
+suv = "secpipw.cli:uv_main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+secpipw = ["data/*.json"]

secpipw-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

secpipw-1.0.0/src/secpipw/__init__.py

@@ -0,0 +1,5 @@
+from secpipw.severity import Severity, parse_severity
+
+__all__ = ["__version__", "Severity", "parse_severity"]
+
+__version__ = "8.0"

secpipw-1.0.0/src/secpipw/__main__.py

@@ -0,0 +1,4 @@
+from secpipw.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

secpipw-1.0.0/src/secpipw/cache_refresh.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable
+
+from secpipw.pypi_api import OfficialPyPIClient
+
+
+@dataclass(frozen=True)
+class CacheRefreshResult:
+    key: str
+    description: str
+    count: int
+    location: str
+
+
+@dataclass(frozen=True)
+class CacheRefreshTask:
+    key: str
+    description: str
+    run: Callable[[OfficialPyPIClient], CacheRefreshResult]
+
+
+def _refresh_project_name_cache(client: OfficialPyPIClient) -> CacheRefreshResult:
+    count = client.refresh_project_name_cache()
+    return CacheRefreshResult(
+        key="pypi-project-names",
+        description="PyPI project name cache",
+        count=count,
+        location=str(client.cache_path),
+    )
+
+
+REFRESH_TASKS: tuple[CacheRefreshTask, ...] = (
+    CacheRefreshTask(
+        key="pypi-project-names",
+        description="PyPI project name cache",
+        run=_refresh_project_name_cache,
+    ),
+)
+
+
+def refresh_all_caches(
+    client: OfficialPyPIClient | None = None,
+) -> list[CacheRefreshResult]:
+    client = client or OfficialPyPIClient()
+    return [task.run(client) for task in REFRESH_TASKS]