fix(release): tarball + frozen-binary import errors blocking v1.0.x (#41)

Second hot-fix to the v1.0.0 pipeline. v1.0.1 unblocked Swift; the
arch-tarball step then hit two more issues:

1. scripts/package_release.sh called tar with GNU-only flags
   (--owner=0 --group=0 --numeric-owner) that macOS bsdtar rejects.
   The fallback branch I added for --no-mac-metadata also kept
   those flags, so the second tar invocation failed too. End-state
   on macos-14: workflow died at "==> tarballing" with no asset
   uploaded.
2. PyInstaller-frozen binary crashed on first run with
   `ImportError: attempted relative import with no known parent
   package`. PyInstaller compiled src/diting/cli.py as a top-level
   script, stripping the diting package context that the module's
   `from .x import y` imports rely on. Only surfaces when the
   frozen binary is actually executed — the tarball would have
   uploaded successfully and install.sh would have downloaded a
   broken binary.

Both fixes verified end-to-end by running
`uv run --group release bash scripts/package_release.sh 1.0.2-rc`
locally, extracting the resulting tarball, and confirming
`diting --help` exits 0 with usage text.

Fixes:
- scripts/package_release.sh: drop GNU-only tar flags; plain
  `tar -czf` runs everywhere. SHA256 in SHASUMS256.txt is the real
  integrity guarantee.
- scripts/frozen_entry.py (new): PyInstaller entry stub that does
  `from diting.cli import main; main()` so the package context is
  preserved.
- scripts/build_frozen.py: target the stub via --paths src/, not
  src/diting/cli.py.
- .gitignore: ignore the PyInstaller-generated diting.spec and the
  Claude Code scheduled-task lockfile.

Bump to v1.0.2; v1.0.0 and v1.0.1 never produced consumable assets,
so end users should install v1.0.2 directly. install.sh resolves
"latest" by default, so curl ... | bash auto-picks v1.0.2 with no
flag change.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: chenchaoyi

.gitignore

@@ -8,6 +8,11 @@ build/
 dist/
 *.egg-info/
 *.egg
+# PyInstaller writes <name>.spec at the repo root on the first run
+# of `scripts/build_frozen.py`. The build script is the source of
+# truth for the freeze config; the generated .spec is regenerated
+# every build and never checked in.
+diting.spec
 
 # Virtual environments (uv puts venvs at .venv by default)
 .venv/
@@ -63,3 +68,6 @@ snapshot-output/
 # Personal/meeting notes — never commit. Keep these out of the public repo.
 会议纪要_*.md
 /会议纪要*.md
+
+# Claude Code scheduled-task local state.
+.claude/scheduled_tasks.lock

CHANGELOG.md

@@ -9,6 +9,40 @@ the project follows [Semantic Versioning](https://semver.org/) where
 practical. The leading `v0.x` line is allowed to break minor
 behaviours between releases.
 
+## [1.0.2] — 2026-05-13
+
+Second hot-fix to the v1.0.0 release pipeline. v1.0.1 unblocked the
+Swift helper build but the per-arch tarball step then failed on
+two further issues that surfaced once the pipeline got further:
+
+1. `scripts/package_release.sh` invoked `tar` with GNU-only flags
+   (`--owner=0 --group=0 --numeric-owner`) which macOS bsdtar
+   rejects outright. The fallback path I added for
+   `--no-mac-metadata` still kept those flags, so the tarball
+   command failed on the hosted runners.
+2. The PyInstaller-frozen binary crashed on first run with
+   `ImportError: attempted relative import with no known parent
+   package`. PyInstaller compiled `cli.py` as a top-level script,
+   stripping the `diting` package context that the module's
+   `from .x import y` imports rely on.
+
+End users with v1.0.0 or v1.0.1 should install v1.0.2 — those tags
+never produced consumable assets. `install.sh` resolves "latest"
+by default, so the curl one-liner picks v1.0.2 automatically.
+
+### Fixed
+- **Tarball builds on macOS bsdtar.** Drop the GNU-only
+  `--owner=0 --group=0 --numeric-owner` flags from
+  `scripts/package_release.sh`; plain `tar -czf` runs everywhere.
+  Tarball reproducibility (deterministic uid/gid headers) was a
+  nice-to-have, not load-bearing — SHA256 in `SHASUMS256.txt`
+  remains the integrity guarantee.
+- **Frozen binary preserves package context.** New
+  `scripts/frozen_entry.py` stub imports `diting.cli:main`, and
+  PyInstaller now compiles the stub (with `--paths src`) instead
+  of `cli.py` directly. Relative imports inside the diting
+  package resolve correctly at runtime.
+
 ## [1.0.1] — 2026-05-13
 
 Hot-fix for the v1.0.0 release pipeline. The Swift helper source

docs/zh/CHANGELOG.md

@@ -8,6 +8,36 @@
 [Semantic Versioning](https://semver.org/)。`v0.x` 阶段允许破坏性的次要
 行为变更。
 
+## [1.0.2] — 2026-05-13
+
+第二个针对 v1.0.0 发布流水线的热修复。v1.0.1 解开了 Swift helper 构建
+那一卡，分架构 tarball 那一步又卡在另外两个问题上：
+
+1. `scripts/package_release.sh` 调 `tar` 时带了 GNU-only 标志
+   （`--owner=0 --group=0 --numeric-owner`），macOS bsdtar 直接拒绝。
+   我为 `--no-mac-metadata` 写的回退分支也带着这些 GNU 标志，所以
+   tarball 那一步在托管 runner 上就死了。
+2. PyInstaller 冻结后的 binary 首次运行就崩在
+   `ImportError: attempted relative import with no known parent
+   package`。PyInstaller 把 `cli.py` 当顶层脚本编译，丢掉了模块自身
+   `from .x import y` 依赖的 `diting` 包上下文。
+
+装了 v1.0.0 / v1.0.1 的最终用户应该装 v1.0.2 —— 那两个 tag 都没产出
+可消费的发布产物。`install.sh` 默认解析最新 tag，所以 curl 一行会自
+动取 v1.0.2。
+
+### 修复
+- **Tarball 在 macOS bsdtar 上能正常打**。从
+  `scripts/package_release.sh` 里去掉 GNU-only 的
+  `--owner=0 --group=0 --numeric-owner`，纯 `tar -czf` 哪里都能跑。
+  原本想要的 tarball 可复现（uid/gid 头一致）只是 nice-to-have，
+  不是关键 —— SHASUMS256.txt 的 SHA256 才是真正的完整性保证。
+- **冻结 binary 保留包上下文**。新增
+  `scripts/frozen_entry.py` stub，里面只 import `diting.cli:main`
+  并调用；PyInstaller 现在编译这个 stub（外加 `--paths src`），
+  而不是直接编译 `cli.py`。diting 包内部的相对 import 运行时能正
+  常 resolve。
+
 ## [1.0.1] — 2026-05-13
 
 v1.0.0 发布流水线的热修复。Swift helper 源码里一个函数调用参数列表的

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "diting"
-version = "1.0.1"
+version = "1.0.2"
 description = "macOS terminal listening post for Wi-Fi, BLE, link health, and the RF environment — your Mac hears more than it tells you"
 readme = "README.md"
 license = "MIT"

scripts/build_frozen.py

@@ -104,12 +104,19 @@ def main() -> None:
         # data files. They live under src/diting/data/ and are read
         # via importlib.resources at runtime.
         "--add-data", f"{REPO_ROOT / 'src' / 'diting' / 'data'}:diting/data",
+        # PyInstaller needs to know where to find the `diting`
+        # package since the entry stub imports it. Pointing
+        # --paths at src/ lets the analyzer walk the package
+        # tree.
+        "--paths", str(REPO_ROOT / "src"),
         # Strip debug symbols from binaries. Knocks ~6 MB off a
         # release build at no runtime cost.
         "--strip",
-        # The entry script — the CLI dispatcher that pyproject.toml's
-        # [project.scripts] maps `diting` to.
-        str(REPO_ROOT / "src" / "diting" / "cli.py"),
+        # Entry stub that imports `diting.cli:main` rather than
+        # PyInstaller-compiling `cli.py` directly. Compiling cli.py
+        # as a top-level script breaks `from .x import y` relative
+        # imports inside the package.
+        str(REPO_ROOT / "scripts" / "frozen_entry.py"),
     ]
 
     # Invoke PyInstaller; let its output stream straight to our

scripts/frozen_entry.py

@@ -0,0 +1,17 @@
+"""PyInstaller entry-point stub.
+
+PyInstaller compiles the script you point it at AS a top-level
+module, which breaks ``from .x import y`` style relative imports
+inside the diting package. A stub that imports ``diting.cli.main``
+preserves the package context — the same way pyproject.toml's
+``[project.scripts]`` entry calls into ``main`` via ``diting.cli:main``.
+
+Only used by ``scripts/build_frozen.py``. Never invoked directly.
+"""
+from __future__ import annotations
+
+from diting.cli import main
+
+
+if __name__ == "__main__":
+    main()

scripts/package_release.sh

@@ -103,26 +103,19 @@ cp -R helper/diting-tianer.app "$STAGE_DIR/share/diting-tianer.app"
 
 # ---- produce tarball ----
 
-# Reproducibility-ish: pin the mtime so a rebuild of the same
-# version doesn't produce a byte-different tarball. --owner / --group
-# / --numeric-owner make the archive look the same regardless of
-# whose machine produced it (helps SHASUMS verification land
-# consistently across CI matrix jobs).
+# Plain `tar -czf`. We do NOT pass `--owner=0 --group=0
+# --numeric-owner` here even though it would produce a more
+# reproducible archive — those are GNU-tar-only flags and macOS
+# ships bsdtar, which rejects them outright (bsdtar accepts a
+# different `--uid`/`--gid` syntax that doesn't ride alongside).
+# Per-arch tarballs are built fresh on clean hosted runners, so the
+# uid/gid baked into the archive header is whatever the runner uses
+# (uid 502 in practice). SHA256 verification of the resulting
+# tarball is what the install.sh path actually relies on for
+# integrity; a deterministic header would be nice-to-have, not
+# load-bearing.
 echo "==> tarballing into ${TARBALL}"
-tar \
-  --no-mac-metadata 2>/dev/null \
-  --owner=0 --group=0 --numeric-owner \
-  -czf "$TARBALL" \
-  -C dist \
-  "${STAGE_NAME}" || tar \
-  --owner=0 --group=0 --numeric-owner \
-  -czf "$TARBALL" \
-  -C dist \
-  "${STAGE_NAME}"
-# (the `|| tar ...` fallback drops `--no-mac-metadata` on platforms
-# where bsdtar doesn't recognise that flag — older macOS releases
-# accept it, brand-new GNU tar does not. The tarball still produces
-# correct contents either way.)
+tar -czf "$TARBALL" -C dist "${STAGE_NAME}"
 
 # SHA256 sidecar so CI can stitch SHASUMS256.txt together across
 # matrix jobs without re-hashing.