merge: v0.11.7 release

Author: tbitcs

CHANGELOG.md

@@ -5,6 +5,29 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.11.7] - 2026-05-24
+
+### Added
+
+- **Pipx-only enforcement** — `specsmith` now rejects invocations from any
+  non-pipx Python environment at startup. Running via `pip install`, an editable
+  dev install, or inside a project venv raises a clear error with install
+  instructions. Override for CI with `SPECSMITH_ALLOW_NON_PIPX=1`.
+- **Persistent 24-hour update check** — `_maybe_notify_pypi_update()` now
+  persists the last-check timestamp to `~/.specsmith/last-update-check` and
+  contacts PyPI at most once per `SPECSMITH_UPDATE_INTERVAL_HOURS` hours
+  (default 24). Previously fired a network call on every shell session; now
+  zero-latency within the window. Disable with `SPECSMITH_NO_UPDATE_CHECK=1`.
+- **Hardened `is_pipx_install()`** — correctly detects Windows pipx venvs at
+  `~/pipx/venvs/` without requiring `PIPX_HOME` env var, plus Linux/macOS
+  `~/.local/pipx/venvs/` paths.
+
+### Fixed
+
+- Removed competing pip-editable `__editable__.specsmith-0.11.3.pth` and
+  `__editable__.specsmith-0.11.5.pth` from the system Python site-packages
+  that caused `import specsmith` to resolve to stale dev copies.
+
 ## [0.11.6] - 2026-05-21
 
 ### Fixed

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "specsmith"
-version = "0.11.6"
+version = "0.11.7"
 description = "Applied Epistemic Engineering toolkit — AEE agent sessions, execution profiles, FPGA/HDL governance, tool installer, 50+ CLI commands."
 readme = "README.md"
 license = "MIT"

src/specsmith/__init__.py

@@ -8,4 +8,4 @@
 try:
     __version__: str = _pkg_version("specsmith")
 except PackageNotFoundError:  # running from source without install
-    __version__ = "0.11.6"  # fallback: keep in sync with pyproject.toml
+    __version__ = "0.11.7"  # fallback: keep in sync with pyproject.toml

src/specsmith/cli.py

@@ -97,12 +97,31 @@ class _AutoUpdateGroup(click.Group):
 
     def invoke(self, ctx: click.Context) -> object:
         import os
-
-        # Skip if explicitly disabled or if this is a meta-command
-        # ctx.protected_args is deprecated in Click 9.0; suppress the warning
-        # on access (it still works in 8.x). In 9.0 the subcommand moves to args.
         import warnings
 
+        # ── Pipx-only enforcement ─────────────────────────────────────────────
+        # specsmith MUST be installed and invoked through pipx.
+        # Any invocation from a non-pipx Python environment is rejected unless
+        # the escape hatch SPECSMITH_ALLOW_NON_PIPX=1 is set (CI / dev only).
+        if not os.environ.get("SPECSMITH_ALLOW_NON_PIPX"):
+            from specsmith.updater import is_pipx_install
+            if not is_pipx_install():
+                click.echo(
+                    "ERROR: specsmith must be installed and run via pipx only.\n"
+                    "  Any pip install, venv install, or editable dev install\n"
+                    "  is rejected to prevent version conflicts.\n"
+                    "\n"
+                    "  Install:      pipx install specsmith\n"
+                    "  Upgrade:      pipx upgrade specsmith\n"
+                    "  Remove other: pip uninstall specsmith\n"
+                    "\n"
+                    "  CI/testing override: set SPECSMITH_ALLOW_NON_PIPX=1",
+                    err=True,
+                )
+                raise SystemExit(1)
+
+        # ── Version checks (skip for meta-commands) ───────────────────────────
+        # ctx.protected_args is deprecated in Click 9.0; suppress the warning.
         with warnings.catch_warnings():
             warnings.simplefilter("ignore", DeprecationWarning)
             protected = list(ctx.protected_args)  # [subcommand] in 8.x, [] in 9.0
@@ -182,17 +201,55 @@ def _maybe_prompt_project_update() -> None:
 def _maybe_notify_pypi_update() -> None:
     """Check PyPI for a newer specsmith version. Prints one-liner if outdated.
 
-    Runs at most once per shell session (tracked via env var). Uses a 3-second
-    timeout to avoid blocking the CLI. Only checks stable versions.
+    Persists the last-check timestamp to ``~/.specsmith/last-update-check``
+    so the network call is only made when it has been more than
+    ``SPECSMITH_UPDATE_INTERVAL_HOURS`` hours since the previous check
+    (default: 24h).  Within that window the function returns immediately
+    without any I/O — adding zero latency to every CLI invocation.
+
+    Override the interval::
+
+        SPECSMITH_UPDATE_INTERVAL_HOURS=4 specsmith audit
+
+    Disable entirely::
+
+        SPECSMITH_NO_UPDATE_CHECK=1 specsmith audit
+
+    Uses a 3-second network timeout so a slow/offline connection never
+    blocks the user.
     """
     import os
+    import time
+    from pathlib import Path
 
+    if os.environ.get("SPECSMITH_NO_UPDATE_CHECK"):
+        return
+
+    # One check per shell session — never fire twice in the same process tree.
     session_key = "SPECSMITH_PYPI_CHECKED"
     if os.environ.get(session_key):
         return
     os.environ[session_key] = "1"
 
     try:
+        interval_h = float(os.environ.get("SPECSMITH_UPDATE_INTERVAL_HOURS", "24"))
+        interval_s = interval_h * 3600
+
+        stamp_file = Path.home() / ".specsmith" / "last-update-check"
+        now = time.time()
+
+        # Read persisted last-check time (best-effort).
+        last_check = 0.0
+        if stamp_file.is_file():
+            try:
+                last_check = float(stamp_file.read_text(encoding="utf-8").strip())
+            except (ValueError, OSError):
+                pass
+
+        # Not due yet — skip entirely (no network call).
+        if now - last_check < interval_s:
+            return
+
         import json as _json  # noqa: PLC0415
         from urllib.request import urlopen  # noqa: PLC0415
 
@@ -202,9 +259,16 @@ def _maybe_notify_pypi_update() -> None:
         if not latest:
             return
 
-        # Simple version comparison: split into tuples of ints
+        # Persist the timestamp now that we have a successful response.
+        try:
+            stamp_file.parent.mkdir(parents=True, exist_ok=True)
+            stamp_file.write_text(str(now), encoding="utf-8")
+        except OSError:
+            pass  # Never fail the CLI over a timestamp write error
+
+        # Simple version comparison — no packaging dep needed.
         def _ver(v: str) -> tuple[int, ...]:
-            import re
+            import re  # noqa: PLC0415
 
             clean = re.match(r"(\d+\.\d+\.\d+)", v)
             return tuple(int(x) for x in clean.group(1).split(".")) if clean else (0,)

src/specsmith/config.py

@@ -115,7 +115,7 @@ class ProjectConfig(BaseModel):
         ),
     )
     language: str = Field(default="python", description="Primary language/runtime")
-    spec_version: str = Field(default="0.11.6", description="Spec version to scaffold from")
+    spec_version: str = Field(default="0.11.7", description="Spec version to scaffold from")
     description: str = Field(default="", description="Short project description")
 
     # Options

src/specsmith/updater.py

@@ -66,17 +66,35 @@ def is_outdated() -> bool:
 def is_pipx_install() -> bool:
     """Return True if specsmith was installed via pipx.
 
-    Checks sys.executable path and PIPX_HOME / PIPX_LOCAL_VENVS env vars.
+    Checks sys.executable path against known pipx venv locations and the
+    PIPX_HOME / PIPX_LOCAL_VENVS env vars.  Robust on Windows where pipx
+    stores venvs in ``~/pipx/venvs/`` without setting PIPX_HOME.
     """
     import os
     import sys
+    from pathlib import Path
 
     exe = sys.executable.replace("\\", "/").lower()
-    return (
-        "pipx" in exe
-        or bool(os.environ.get("PIPX_HOME"))
-        or bool(os.environ.get("PIPX_LOCAL_VENVS"))
-    )
+
+    # 1. Executable path contains 'pipx' (catches most OS defaults)
+    if "pipx" in exe:
+        return True
+
+    # 2. Explicit pipx env vars (set by some CI / pipx versions)
+    if os.environ.get("PIPX_HOME") or os.environ.get("PIPX_LOCAL_VENVS"):
+        return True
+
+    # 3. Windows default: ~/pipx/venvs/<pkg>/Scripts/python.exe
+    win_pipx = (Path.home() / "pipx" / "venvs").as_posix().lower()
+    if exe.startswith(win_pipx):
+        return True
+
+    # 4. Linux/macOS default: ~/.local/pipx/venvs/<pkg>/bin/python
+    unix_pipx = (Path.home() / ".local" / "pipx" / "venvs").as_posix().lower()
+    if exe.startswith(unix_pipx):
+        return True
+
+    return False
 
 
 def run_self_update(