preflight-check-cli 1.0.1__tar.gz

preflight_check_cli-1.0.1/.dockerignore

@@ -0,0 +1,21 @@
+# 构建镜像时**不需要**的东西。
+#
+# 为什么值得单独写：不写的话 `.venv/` 和 `.git/` 会一起进构建上下文 ——
+# 前者几百兆、后者带着全部历史，而它们对镜像内容毫无影响。
+# 在慢网络上这一条能省掉几分钟。
+
+.git
+.github
+.venv
+venv
+__pycache__
+*.pyc
+.pytest_cache
+.mypy_cache
+.ruff_cache
+tests
+docs
+scripts
+*.egg-info
+dist
+build

preflight_check_cli-1.0.1/.gitattributes

@@ -0,0 +1,21 @@
+# 换行符统一成 LF。
+#
+# 为什么必须有这个文件：CI 同时在 ubuntu 和 windows 上跑（见 .github/workflows/ci.yml）。
+# 如果仓库里存的是 CRLF、而检出时又按平台转换，两边看到的**字节**就不一样 ——
+# 任何基于文件内容的比较（指纹、快照、golden file）都会一边绿一边红。
+#
+# 这个坑在 fivewhys 上真实发生过：`open("w")` 在 Windows 默认把 \n 转成 CRLF，
+# 于是同一份数据在 Windows 和 Linux 上算出不同的 SHA-256，
+# 「可复现」退化成了「在我机器上可复现」。
+* text=auto eol=lf
+
+# 二进制文件不要碰
+*.png binary
+*.jpg binary
+*.gif binary
+*.ico binary
+*.woff binary
+*.woff2 binary
+
+# PowerShell 脚本在 Windows 上用 LF 也能正常执行（pwsh 5+/7 都行），
+# 不特殊处理 —— 统一比方便重要。

preflight_check_cli-1.0.1/.github/workflows/ci.yml

@@ -0,0 +1,60 @@
+name: ci
+
+# 每次 push / PR 都跑。这是纪律 D1 的自动化版本：
+# 阶段测试可能忘记跑，CI 不会。
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+  # ⚠️ publish.yml 用 `uses:` **复用**这个工作流，而被复用的工作流必须声明
+  # workflow_call。少这一行的表现是隐蔽的：本地全部测试依然全绿、YAML 也合法，
+  # 只有真推 tag 时整个发布运行会在**校验阶段**失败（verify 任务连启动都不会）。
+  # 守它的是 tests/test_workflows.py::test_a_reused_workflow_declares_workflow_call
+  workflow_call:
+
+jobs:
+  check:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        # 开发机是 Windows（本地路径 / 换行符 / 编码的坑都在那里），
+        # 但 CI 跑 Linux 才能证明代码本身不依赖平台。
+        # 两个都跑：只要有一个绿，就不能说是"环境问题"。
+        os: [ubuntu-latest, windows-latest]
+        # ⚠️ **三个版本都要跑，因为 `pyproject.toml` 的 classifiers 里
+        # 声明了三个。**
+        #
+        # 最初的写法是只跑首尾两个（3.11 + 3.13）—— 那是常见的省成本做法，
+        # 而它有一个具体的后果：**3.12 被声明支持，却从没被测试过。**
+        # 一条读 classifiers 的测试立刻抓到了这个不一致。
+        #
+        # 两种修法都成立：要么别声明 3.12，要么测它。
+        # 选后者 —— 3.12 是真实在用的版本，而"只在 3.12 上坏"这种事
+        # 恰恰是最难在事后解释的。
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: 安装
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+
+      - name: 代码风格
+        run: python -m ruff check .
+
+      - name: 格式检查
+        run: python -m ruff format --check .
+
+      - name: 测试
+        run: python -m pytest
+
+      - name: 类型检查
+        run: python -m mypy src

preflight_check_cli-1.0.1/.github/workflows/publish.yml

@@ -0,0 +1,89 @@
+name: publish
+
+# 打 tag 就发布 —— **不需要任何 token**。
+#
+# ## 为什么用可信发布（Trusted Publishing）而不是 API token
+#
+# 一个存在 GitHub Secrets 里的 PyPI token 是一个**长期凭证**：
+# 它不会过期、泄漏了很难发现、而且它能发布的包不止这一个。
+#
+# 可信发布走的是 OIDC：GitHub 临时签一个短命的身份断言，
+# PyPI 校验"这次上传确实来自这个仓库的这个工作流"。
+# 结果是**没有可以泄漏的秘密**，而且 PyPI 页面上会显示构建来源
+# （attestation），别人能验证这个包是从哪段代码构建出来的。
+#
+# 要启用它，先在 PyPI 上登记一个发布者。项目**还不存在**的时候，是在账号设置里
+# 加一个 "pending publisher"（不是项目设置 —— 项目要等第一次上传才被创建）：
+#     PyPI Project Name: preflight-check-cli
+#     Owner: lddd1026    Repository: preflight
+#     Workflow: publish.yml    Environment: pypi
+#
+# ⚠️ 项目名写错不是"报个错就算了"：PyPI 会先按登记的名字把项目建出来，
+# 再发现上传的元数据名字对不上，于是你会得到一个名字写错的空项目，
+# 得手动删掉再重建登记。而版本号/文件名一旦用过就不能复用。
+#
+# ## 为什么先跑一遍测试
+#
+# 发布是不可逆的：PyPI 上的一个版本号不能被复用，删掉也没用
+# （别人已经装了）。所以这个工作流**先跑 check，绿了才发布**。
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  # ⚠️ 复用 ci.yml 的那套检查，而不是重写一遍 ——
+  # 两份定义会漂移，而漂移之后"发布前跑了什么"就成了一个问题。
+  verify:
+    uses: ./.github/workflows/ci.yml
+
+  build:
+    needs: verify
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: 构建 sdist 和 wheel
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+
+      # 这一步**必须**在发布前跑：twine check 会告诉你
+      # README 在 PyPI 上渲染会不会报错、元数据是不是合法。
+      # 而这两件事在上传之后才发现就晚了 —— 版本号已经用掉了。
+      - name: 校验元数据和 README 渲染
+        run: |
+          python -m pip install --upgrade twine
+          python -m twine check dist/*
+
+      # 让"包里到底有什么"在 CI 日志里可见 —— 出问题时不用重新构建
+      - name: 列出 wheel 内容
+        run: python -m zipfile --list dist/*.whl | head -40
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    # ⚠️ environment 是**人在回路**的那一步：在 GitHub 上把它配成需要
+    # 人工批准，于是一次误打的 tag 也不会直接推到 PyPI。
+    environment: pypi
+    permissions:
+      # 这两项是可信发布的要求：id-token 用来签 OIDC 断言，
+      # attestations 让 PyPI 能把构建来源写进 provenance。
+      id-token: write
+      attestations: write
+      contents: read
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

preflight_check_cli-1.0.1/.gitignore

@@ -0,0 +1,29 @@
+# ---- Python ----
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+
+# ---- 工具缓存（这些会落在项目目录里）----
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# ---- preflight 自己的运行时产物 ----
+# 检查结果落盘的位置。它是运行时数据，不是源码。
+.preflight/
+
+# ---- 环境与密钥 ----
+.env
+*.env
+!.env.example
+
+# ---- 编辑器 / 系统 ----
+.vscode/
+.idea/
+Thumbs.db
+desktop.ini

preflight_check_cli-1.0.1/Dockerfile

@@ -0,0 +1,58 @@
+# preflight 的干净容器 —— **S8 的"干净环境测试"就是靠它做的**。
+#
+# ## 这个 Dockerfile 同时也是 CI 的替身
+#
+# 项目从 S0 起就配了 Ubuntu + Windows 双平台的 CI，但它**一次都没跑过**
+# （没有 remote）。而"只在 Windows 上验证过"这件事的风险是具体的：
+# 路径分隔符、换行符、编码、文件权限 —— 每一个都可能在 Linux 上炸。
+#
+# 所以这个容器不是"顺便加的"，它是**唯一真正验证过 Linux 的手段**。
+# 跑一次 `docker build && docker run` 比"等 CI 配好"快得多。
+#
+# ## 为什么基础镜像选 slim 而不是 alpine
+#
+# alpine 用 musl libc，而 Python 生态里不少 wheel 只有 manylinux 版本 ——
+# 装的时候会退化成源码编译，慢且容易缺构建依赖。
+# 这个镜像的目的不是"最小"，是"干净"。
+
+FROM python:3.13-slim
+
+# 不让 Python 写 .pyc、不让它缓冲输出 —— 容器里的标准做法。
+# 缓冲会让日志在崩溃时丢掉最后几行，而那几行常常正是原因。
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1
+
+WORKDIR /app
+
+# 先只拷元数据和源码 —— 让 pip 的层缓存有意义
+#
+# ⚠️ **`LICENSE` 不是可选的。** `pyproject.toml` 里写了
+# `license = { file = "LICENSE" }`，构建元数据时会去读那个文件 ——
+# 没拷进来就直接
+#
+#     OSError: License file does not exist: LICENSE
+#
+# 而本地构建永远发现不了（那个文件就在旁边）。
+# 又一次是"干净环境"才暴露出来的问题 —— 这一轮里第三次了。
+# 现在有一条测试守着这份清单（`test_the_dockerfile_copies_everything_the_build_needs`）。
+COPY pyproject.toml README.md LICENSE ./
+COPY src ./src
+
+# ⚠️ **不装 `[tools]` / `[llm]`**。
+#
+# 两个理由：
+# 1. 镜像要能**离线跑出 demo**，装 litellm 是几十兆的浪费
+# 2. 那两组本来就是可选的 —— 不装时对应规则明确报"跳过"，
+#    这正是适配器层的设计。把它装上去反而演示不了这个行为
+# ⚠️ 显式的重试参数不是可选项。
+#
+# 实测：默认设置（15 秒超时、5 次重试）在这台机器上拉 `rich` 时反复超时 ——
+# 而 pip 的默认重试是**指数退避**的，5 次之后直接失败。
+#
+# 60 秒超时 + 10 次重试把这一类抖动吸收掉。它不掩盖真正的问题
+# （包不存在、版本冲突），只是不让"网络抖一下"变成"镜像构建不了"。
+RUN pip install --no-cache-dir --retries 10 --timeout 60 .
+
+# 随包发布的 demo 素材在 src/preflight/demo/ 里，`preflight-check demo` 用它 ——
+# **不配 API Key、不联网**就能看到 broken-agent vs clean-agent 的对比。
+CMD ["preflight-check", "demo"]

preflight_check_cli-1.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 刘达
+
+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.