update-kit 0.1.0__tar.gz

update_kit-0.1.0/.github/dependabot.yml

@@ -0,0 +1,19 @@
+version: 2
+updates:
+  # Actions stay pinned by commit SHA with a "# vX.Y.Z" comment; Dependabot
+  # understands that form and bumps both the SHA and the comment.
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    commit-message:
+      prefix: "chore(deps)"
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: weekly
+    commit-message:
+      prefix: "chore(deps)"
+    groups:
+      minor-and-patch:
+        update-types: [minor, patch]

update_kit-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,62 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  PYTHONUTF8: "1"
+
+jobs:
+  test:
+    name: Python 3.10 / ${{ matrix.os }}
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [macos-latest, ubuntu-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
+        with:
+          python-version: "3.10"
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+      - name: Install locked dependencies
+        run: uv sync --locked --all-groups
+      - name: Lint
+        run: uv run ruff check .
+      - name: Test
+        run: uv run pytest -v
+      - name: Build distributions
+        run: uv build
+      - name: Validate wheel is importable standalone
+        shell: python
+        run: |
+          import os
+          import pathlib
+          import subprocess
+          import tempfile
+
+          wheel, = pathlib.Path("dist").glob("*.whl")
+          with tempfile.TemporaryDirectory() as directory:
+              environment = pathlib.Path(directory)
+              subprocess.run(["uv", "venv", environment], check=True)
+              scripts = environment / ("Scripts" if os.name == "nt" else "bin")
+              python = scripts / ("python.exe" if os.name == "nt" else "python")
+              subprocess.run(
+                  ["uv", "pip", "install", "--python", python, "--no-index", wheel],
+                  check=True,
+              )
+              subprocess.run([python, "-I", "-c", "import update_kit"], check=True)
+              print("update_kit imports standalone OK")

update_kit-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,63 @@
+name: Release
+
+# PyPI Trusted Publishing binds to this filename: keep it `release.yml` in every repo.
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+  id-token: write
+
+concurrency:
+  group: release-${{ github.ref }}
+
+env:
+  PYTHONUTF8: "1"
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
+        with:
+          python-version: "3.10"
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+      - name: Install locked dependencies
+        run: uv sync --locked --all-groups
+      - name: Check, test, and build
+        run: |
+          uv run ruff check .
+          uv run pytest -v
+          uv build
+      - name: Validate release wheel
+        run: |
+          uv venv .release-venv
+          uv pip install --python .release-venv/bin/python --no-index dist/*.whl
+          reported="$(.release-venv/bin/python -I -c 'import importlib.metadata as m; print(m.version("update-kit"))')"
+          if [ "$reported" != "${GITHUB_REF_NAME#v}" ]; then
+            echo "::error::wheel reports '$reported', expected '${GITHUB_REF_NAME#v}'"
+            exit 1
+          fi
+      - name: Publish to PyPI
+        run: uv publish --trusted-publishing always
+
+      # After publish: uv publish uploads dist/*, and SHA256SUMS is not a distribution.
+      - name: Create checksums
+        run: sha256sum dist/* > dist/SHA256SUMS
+      - name: Create GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh api "repos/${GITHUB_REPOSITORY}/git/refs/tags/$GITHUB_REF_NAME" >/dev/null
+          if gh release view "$GITHUB_REF_NAME" >/dev/null 2>&1; then
+            gh release upload "$GITHUB_REF_NAME" dist/* --clobber
+          else
+            gh release create "$GITHUB_REF_NAME" dist/* --generate-notes --title "$GITHUB_REF_NAME" --verify-tag
+          fi

update_kit-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+.ruff_cache/
+.coverage
+.pytest_cache/

update_kit-0.1.0/CHANGELOG.md

@@ -0,0 +1,46 @@
+## [0.1.0] - 2026-10-15
+
+### 🚀 Features
+
+- Add update-kit 0.1.0
+
+### 🐛 Bug Fixes
+
+- Harden update chain, tag parsing and cache repair
+- **security:** Validate repo URL, end-of-options before URL, run git/install from home
+- Install step never prompts for git credentials; test: kill 4 surviving mutants
+
+### ⚙️ Miscellaneous Tasks
+
+- Add tag-triggered PyPI release workflow
+## [Unreleased]
+
+### 🔒 Security
+
+- The install step (uv / pipx, and the Windows detached chain) runs with `GIT_TERMINAL_PROMPT=0`
+  and `GCM_INTERACTIVE=never`, so the installer's own git fetch fails instead of blocking on a
+  credential prompt
+
+## [0.1.0] - 2026-10-15
+
+### 🚀 Features
+
+- Initial release: `latest_tag`, `install_kind`, `update`, `check`, `hint`, `should_hint`,
+  `normalize_lang` — self-update for git-tag-released CLIs installed with uv tool or pipx,
+  en + zh-TW messages, cached background check in `$HOME/.update-kit/state.json`
+
+### 🔒 Security
+
+- Repo URL (`url=` / `UPDATE_KIT_REPO_URL`) is validated (`https://`, `ssh://`, `file://`,
+  `git@host:path`; no leading `-`, control chars, `ext::` or embedded credentials) and passed to
+  `git ls-remote` after `--` with `protocol.ext.allow=never`, so `--upload-pack=...` can no longer
+  run code from the background `check()`
+- The POSIX install and the Windows detached chain run with the home directory as cwd, so
+  `cmd.exe` no longer resolves `uv` / the after-steps from a planted `uv.bat` / `crw.exe` in the
+  caller's cwd; `git ls-remote` also runs from home. Only `https`, `ssh`, `file` schemes (lowercase)
+  are accepted now (plain `http://` is rejected)
+- git stderr is stripped of control characters and URL userinfo before printing; `update` names
+  `UPDATE_KIT_REPO_URL` when it is in effect (en + zh-TW)
+- Tag parsing: version parts capped at 9 digits, exact `\trefs/tags/` split, no whitespace
+  tolerance on tag names; `check()` only returns strict tags
+- `check()` caches by resolved source URL, so an override can't poison the default entry

update_kit-0.1.0/CLAUDE.md

@@ -0,0 +1,33 @@
+# CLAUDE.md
+
+## Frozen public API
+
+`update_kit`'s public functions (`latest_tag`, `install_kind`, `update`, `check`, `hint`,
+`should_hint`, `normalize_lang`, `UpdateError`) are consumed by aicp, ai-accounts,
+codex-reset-watch and agent-toggle. Signatures, defaults, return codes and the
+`$HOME/.update-kit/state.json` layout are a contract: changing any of them is a breaking
+change (`type(scope)!:` + `BREAKING CHANGE:` footer, minor bump while 0.x).
+
+## Rules
+
+- Stdlib only. No runtime dependencies, no `packaging`.
+- Every user-visible string exists in `en` and `zh-TW` in `_MESSAGES`.
+- Never prompt; never hit the network in tests (use a `file://` repo in `tmp_path` or a fake `run`).
+- Keep `README.md` and `CHANGELOG.md` in sync with user-visible changes.
+
+## Commands
+
+- Test: `uv run pytest`
+- Lint: `uv run ruff check .`
+- Build: `uv build`
+
+## Cross-platform
+
+Code must run on macOS, Linux, and Windows (paths, separators, shell commands, line
+endings, `$HOME` vs `%USERPROFILE%`, file locking, symlinks, terminal/ANSI). Guard
+platform-specific code and say so.
+
+- Reuse the shared platform helpers first: `src/update_kit/__init__.py` (`_IS_WINDOWS`, `_windows_chain`, `_spawn_detached`).
+- Text I/O always passes `encoding="utf-8"` (Windows defaults to cp1252).
+- Windows is verified by CI's `windows-latest` job, not locally; POSIX-only tests are
+  skipped on Windows (`os.name == "nt"`).

update_kit-0.1.0/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 Wes Kao
+
+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 OF THE SOFTWARE.

update_kit-0.1.0/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.5
+Name: update-kit
+Version: 0.1.0
+Summary: Self-update for git-tag-released Python CLIs (uv tool / pipx). Stdlib only.
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# update-kit
+
+Self-update for Python CLIs that are released as git tags (`vX.Y.Z` or `X.Y.Z`) and installed with
+`uv tool` or `pipx`. Stdlib only, Python ≥ 3.10, macOS / Linux / Windows.
+
+- `<cmd> update` installs the newest release tag — no prompts, ever.
+- A cached background check prints a one-line hint on an interactive terminal only.
+- Every message exists in English and Traditional Chinese (`zh-TW`).
+
+## Install
+
+```toml
+# consumer pyproject.toml
+dependencies = ["update-kit>=0.1,<0.2"]
+```
+
+## Wiring a consumer CLI
+
+```python
+import sys
+
+import update_kit
+
+from my_cli import __version__
+
+APP, REPO, DIST = "my-cli", "owner/my-cli", "my-cli"
+
+
+def main(argv=None):
+    argv = sys.argv[1:] if argv is None else argv
+    lang = "zh-TW"  # the app's own current language setting
+
+    # `my-cli update` and `my-cli --update`
+    if argv[:1] == ["update"] or "--update" in argv:
+        sys.exit(update_kit.update(
+            app=APP, repo=REPO, dist=DIST, lang=lang,
+            after=[["my-cli", "migrate"]],  # optional: runs with the NEW binary
+        ))
+
+    # Background hint: stderr, TTY only (never under launchd/timers/--json/pipes).
+    if update_kit.should_hint():
+        latest = update_kit.check(repo=REPO, current=__version__)
+        if latest:
+            print(update_kit.hint("my-cli", latest, __version__, lang), file=sys.stderr)
+    ...
+```
+
+## API
+
+| Function | Does |
+|---|---|
+| `latest_tag(repo, *, timeout=5, url=None) -> str` | Newest strict `v?X.Y.Z` tag (ASCII digits) via `git ls-remote --tags --refs`. Prereleases and other names are ignored. Raises `UpdateError` (offline, no tags, git missing). |
+| `install_kind(dist) -> (kind, detail)` | `"dev"` (PEP 610 local/editable dir, detail = the dir), `"uv"` / `"pipx"` (from `sys.prefix`), else `"unknown"`. |
+| `update(*, app, repo, dist, current=None, lang="en", after=(), out=sys.stderr, run=subprocess.run, url=None) -> int` | Exit code: **0** updated or already up to date · **1** couldn't check (offline/rate limit) or install/after-step failed · **2** dev install (use `git pull`) or unknown install (manual command printed). |
+| `check(*, repo, current, cache_path=None, ttl=86400, timeout=1.5, url=None) -> str \| None` | Newer tag or `None`. Never raises. Results — failures too — are cached for `ttl` in `$HOME/.update-kit/state.json`, keyed by the resolved source URL. |
+| `hint(cmd, latest, current, lang="en") -> str` | `my-cli v1.2.0 is available (you have 1.1.0) — run` `` `my-cli update` `` |
+| `should_hint(stream=sys.stderr) -> bool` | `True` only when `stream` is a TTY. |
+| `normalize_lang(value) -> str` | `zh_TW` / `zh-tw` / `zh-Hant` / `zh_HK` → `"zh-TW"`; anything else → `"en"`. |
+
+Install commands used by `update`:
+
+- uv: `uv tool install --force --no-sources git+<url>@<tag>`
+- pipx: `pipx install --force git+<url>@<tag>`
+
+`<url>` is `url=`, else `$UPDATE_KIT_REPO_URL`, else `https://github.com/<repo>.git`
+(`file://` works, which is how the tests run without a network). Only `https://`, `ssh://`,
+`file://` and `git@host:path` are accepted (`ssh://git@host/...` is fine, `ssh://user:pass@` is not; `git@host:path` is installed as `ssh://git@host/path`); a leading `-`, whitespace/control characters,
+`ext::` or credentials in the URL (`user:pass@`) raise `UpdateError` (`update` returns 1,
+`check` returns `None`). When `$UPDATE_KIT_REPO_URL` is in effect, `update` prints one line
+naming it. `git ls-remote` runs as `git -c protocol.ext.allow=never ls-remote --tags --refs -- <url>`
+from the home directory, and so does the install; git's stderr is stripped of control characters.
+
+**Windows:** the running `.exe` is locked, so `update` starts the install (and the `after`
+steps, chained with `&&`) in a detached `cmd.exe` that waits a few seconds for the app to
+exit, returns 0 and says the update continues in the background. Output goes to
+`%USERPROFILE%\.update-kit\<app>-update.log`. Unlike POSIX (where every after-step runs and
+any failure makes the result 1), the Windows chain stops at the first failing step and the
+outcome is only in the log. An install whose arguments or log path contain a `cmd.exe`
+metacharacter (`& | < > ^ % " ( ) !`) is refused with exit 1 instead of being spawned.
+
+`git ls-remote` never prompts: `GIT_TERMINAL_PROMPT=0`, and `GIT_SSH_COMMAND` defaults to
+`ssh -o BatchMode=yes` when unset. The install step (uv / pipx) also runs with
+`GIT_TERMINAL_PROMPT=0` and `GCM_INTERACTIVE=never`.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check .
+uv build
+```
+
+## License
+
+MIT

update_kit-0.1.0/README.md

@@ -0,0 +1,96 @@
+# update-kit
+
+Self-update for Python CLIs that are released as git tags (`vX.Y.Z` or `X.Y.Z`) and installed with
+`uv tool` or `pipx`. Stdlib only, Python ≥ 3.10, macOS / Linux / Windows.
+
+- `<cmd> update` installs the newest release tag — no prompts, ever.
+- A cached background check prints a one-line hint on an interactive terminal only.
+- Every message exists in English and Traditional Chinese (`zh-TW`).
+
+## Install
+
+```toml
+# consumer pyproject.toml
+dependencies = ["update-kit>=0.1,<0.2"]
+```
+
+## Wiring a consumer CLI
+
+```python
+import sys
+
+import update_kit
+
+from my_cli import __version__
+
+APP, REPO, DIST = "my-cli", "owner/my-cli", "my-cli"
+
+
+def main(argv=None):
+    argv = sys.argv[1:] if argv is None else argv
+    lang = "zh-TW"  # the app's own current language setting
+
+    # `my-cli update` and `my-cli --update`
+    if argv[:1] == ["update"] or "--update" in argv:
+        sys.exit(update_kit.update(
+            app=APP, repo=REPO, dist=DIST, lang=lang,
+            after=[["my-cli", "migrate"]],  # optional: runs with the NEW binary
+        ))
+
+    # Background hint: stderr, TTY only (never under launchd/timers/--json/pipes).
+    if update_kit.should_hint():
+        latest = update_kit.check(repo=REPO, current=__version__)
+        if latest:
+            print(update_kit.hint("my-cli", latest, __version__, lang), file=sys.stderr)
+    ...
+```
+
+## API
+
+| Function | Does |
+|---|---|
+| `latest_tag(repo, *, timeout=5, url=None) -> str` | Newest strict `v?X.Y.Z` tag (ASCII digits) via `git ls-remote --tags --refs`. Prereleases and other names are ignored. Raises `UpdateError` (offline, no tags, git missing). |
+| `install_kind(dist) -> (kind, detail)` | `"dev"` (PEP 610 local/editable dir, detail = the dir), `"uv"` / `"pipx"` (from `sys.prefix`), else `"unknown"`. |
+| `update(*, app, repo, dist, current=None, lang="en", after=(), out=sys.stderr, run=subprocess.run, url=None) -> int` | Exit code: **0** updated or already up to date · **1** couldn't check (offline/rate limit) or install/after-step failed · **2** dev install (use `git pull`) or unknown install (manual command printed). |
+| `check(*, repo, current, cache_path=None, ttl=86400, timeout=1.5, url=None) -> str \| None` | Newer tag or `None`. Never raises. Results — failures too — are cached for `ttl` in `$HOME/.update-kit/state.json`, keyed by the resolved source URL. |
+| `hint(cmd, latest, current, lang="en") -> str` | `my-cli v1.2.0 is available (you have 1.1.0) — run` `` `my-cli update` `` |
+| `should_hint(stream=sys.stderr) -> bool` | `True` only when `stream` is a TTY. |
+| `normalize_lang(value) -> str` | `zh_TW` / `zh-tw` / `zh-Hant` / `zh_HK` → `"zh-TW"`; anything else → `"en"`. |
+
+Install commands used by `update`:
+
+- uv: `uv tool install --force --no-sources git+<url>@<tag>`
+- pipx: `pipx install --force git+<url>@<tag>`
+
+`<url>` is `url=`, else `$UPDATE_KIT_REPO_URL`, else `https://github.com/<repo>.git`
+(`file://` works, which is how the tests run without a network). Only `https://`, `ssh://`,
+`file://` and `git@host:path` are accepted (`ssh://git@host/...` is fine, `ssh://user:pass@` is not; `git@host:path` is installed as `ssh://git@host/path`); a leading `-`, whitespace/control characters,
+`ext::` or credentials in the URL (`user:pass@`) raise `UpdateError` (`update` returns 1,
+`check` returns `None`). When `$UPDATE_KIT_REPO_URL` is in effect, `update` prints one line
+naming it. `git ls-remote` runs as `git -c protocol.ext.allow=never ls-remote --tags --refs -- <url>`
+from the home directory, and so does the install; git's stderr is stripped of control characters.
+
+**Windows:** the running `.exe` is locked, so `update` starts the install (and the `after`
+steps, chained with `&&`) in a detached `cmd.exe` that waits a few seconds for the app to
+exit, returns 0 and says the update continues in the background. Output goes to
+`%USERPROFILE%\.update-kit\<app>-update.log`. Unlike POSIX (where every after-step runs and
+any failure makes the result 1), the Windows chain stops at the first failing step and the
+outcome is only in the log. An install whose arguments or log path contain a `cmd.exe`
+metacharacter (`& | < > ^ % " ( ) !`) is refused with exit 1 instead of being spawned.
+
+`git ls-remote` never prompts: `GIT_TERMINAL_PROMPT=0`, and `GIT_SSH_COMMAND` defaults to
+`ssh -o BatchMode=yes` when unset. The install step (uv / pipx) also runs with
+`GIT_TERMINAL_PROMPT=0` and `GCM_INTERACTIVE=never`.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check .
+uv build
+```
+
+## License
+
+MIT

update_kit-0.1.0/TODO.md

@@ -0,0 +1,10 @@
+# TODO
+
+- [ ] Pin the install to the commit SHA seen by `ls-remote` (TOCTOU: a tag can move between check and install)
+- [ ] Verify release tag signatures before installing
+- [ ] Windows: launch `cmd.exe` (ComSpec) and `git` by absolute path (CreateProcess searches the parent's cwd first)
+- [ ] Run `after` steps with cwd=home too; document that an injected `run` must accept `cwd=`
+- [x] 0.1.0: frozen public API, tests, CI matrix (macOS / Linux / Windows)
+- [ ] Create the GitHub repo, push, tag `v0.1.0` and publish to PyPI (manual hand-off)
+- [ ] Add `.github/workflows/release.yml` (PyPI Trusted Publishing) like telegram-kit
+- [ ] Verify the Windows detached update chain on a real Windows uv tool install

update_kit-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[project]
+name = "update-kit"
+dynamic = ["version"]
+description = "Self-update for git-tag-released Python CLIs (uv tool / pipx). Stdlib only."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+dependencies = []
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+path = "src/update_kit/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/update_kit"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "ruff>=0.15.21",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]