Added v0.2 — env_int/env_float numeric env helpers (F-006)

Numeric env helpers with project-prefix fallback that abort with a clear SystemExit naming the variable on a malformed value (Invalid <KEY>='<value>': expected an integer./a number.) instead of an uncaught ValueError. Folds the per-routine _int/_float helpers the WooCommerce family each duplicated (Margin F-032 / Sales F-021 / Stock F-023 / Marketing F-027) into the shared core — review Step 9. Additive; existing names unchanged. 28 tests.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: mwebbers

CHANGELOG.md

@@ -8,6 +8,18 @@ adheres to semantic versioning.
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-06-01
+
+### Added
+- **[F-006]** `env_int(key, default=None, *, prefix="")` and `env_float(...)` —
+  numeric env helpers using the same project-prefix-with-fallback lookup as
+  `env_opt`, returning `default` when unset and aborting with a clear `SystemExit`
+  naming the variable (`Invalid <KEY>='<value>': expected an integer.` /
+  `… a number.`) when the value is set but malformed, instead of an uncaught
+  `ValueError`. Folds the per-routine `_int`/`_float` helpers the WooCommerce
+  family each carried into the shared core (review Step 9). Additive — existing
+  names unchanged.
+
 ## [0.1.0] - 2026-05-31
 
 Initial release: the vendor-agnostic, standard-library-only core, extracted from

CLAUDE.md

@@ -6,9 +6,9 @@ Context for Claude Code in this repo. Keep this short — it loads on every sess
 
 `claude-code-commons` is a **library**, not a routine. It holds the small,
 vendor-agnostic, **standard-library-only** helpers shared by Claude routine
-repos: `env_required`/`env_opt`/`env_get`, `parse_num`, `currency_symbol`,
-`build_remote_path`, `log`. It has **no vendor or report logic and no third-party
-dependency**.
+repos: `env_required`/`env_opt`/`env_get`, `env_int`/`env_float`, `parse_num`,
+`currency_symbol`, `build_remote_path`, `log`. It has **no vendor or report logic
+and no third-party dependency**.
 
 There is no scheduled-task/operator section here — this package does not run on
 its own. It is consumed by the routine repos and by vendor toolkits (e.g.

SCOPE.md

@@ -62,6 +62,16 @@ Each feature is testable. The ID in brackets is referenced by tests via
 - **[F-005] Timestamped run log.** `log(msg)` prints a flushed `[HH:MM:SS] msg`
   line to stdout — the shared run-log format the routines use.
 
+- **[F-006] Numeric environment helpers with clear errors.** `env_int(key,
+  default=None, *, prefix="")` and `env_float(key, default=None, *, prefix="")`
+  resolve a variable via the same project-prefix-with-fallback lookup as `env_opt`,
+  return `default` when unset, and parse the value as an `int`/`float`. When the
+  value is **set but malformed**, they abort with a clear `SystemExit` naming the
+  variable (`Invalid <KEY>='<value>': expected an integer.` / `… a number.`)
+  instead of raising an uncaught `ValueError` mid-run — so a typo in a numeric knob
+  fails a routine's `--dry-run` config validation cleanly. Replaces the per-routine
+  `_int`/`_float` helpers the WooCommerce family each carried (review Step 9).
+
 ## Out of scope
 
 Anything vendor-specific (a WooCommerce/Shopify/… client, shop meta keys);

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "claude-code-commons"
-version = "0.1.0"
+version = "0.2.0"
 description = "Vendor-agnostic, standard-library-only helpers (env lookup, tolerant parsing, currency symbols, remote-path builder, run log) shared by Claude routine repos"
 # Standard library only — a broad floor so it installs in any routine runtime,
 # including a Python 3.11 scheduled-task sandbox. Verified on 3.9 and 3.12.

src/code_commons.py

@@ -67,6 +67,37 @@ def env_opt(key: str, default: str | None = None, *, prefix: str = "") -> str |
 env_get = env_opt
 
 
+def env_int(key: str, default: int | None = None, *, prefix: str = "") -> int | None:
+    """Optional env var parsed as an ``int``, via the project-prefix-with-fallback
+    lookup. Returns ``default`` when neither form is set.
+
+    When the value **is** set but is not a valid integer, this aborts with a clear
+    ``SystemExit`` naming the variable (``Invalid <KEY>='<value>': expected an
+    integer.``) instead of raising an uncaught ``ValueError`` mid-run — so a typo in
+    a numeric knob fails a routine's ``--dry-run`` config check cleanly. ``default``
+    is returned as-is and never re-parsed (F-006)."""
+    raw = _env_lookup(key, prefix)
+    if raw is None:
+        return default
+    try:
+        return int(raw)
+    except (TypeError, ValueError):
+        raise SystemExit(f"Invalid {key}={raw!r}: expected an integer.")
+
+
+def env_float(key: str, default: float | None = None, *, prefix: str = "") -> float | None:
+    """Optional env var parsed as a ``float`` (see :func:`env_int`). Returns
+    ``default`` when unset; aborts with a clear ``SystemExit`` naming the variable
+    (``Invalid <KEY>='<value>': expected a number.``) when set but malformed (F-006)."""
+    raw = _env_lookup(key, prefix)
+    if raw is None:
+        return default
+    try:
+        return float(raw)
+    except (TypeError, ValueError):
+        raise SystemExit(f"Invalid {key}={raw!r}: expected a number.")
+
+
 # ---------------------------------------------------------------------------
 # Tolerant numeric parsing
 # ---------------------------------------------------------------------------

tests/test_code_commons.py

@@ -67,6 +67,56 @@ def test_env_required_missing_names_both_forms(monkeypatch):
     assert "WC_URL" in msg and "STOCK_WC_URL" in msg
 
 
+# ---------------------------------------------------------------------------
+# F-006 Numeric environment helpers with clear errors
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.feature("F-006")
+def test_env_int_float_parse_with_default_and_prefix(monkeypatch):
+    for k in ("PAGES", "STOCK_PAGES", "RATE", "STOCK_RATE"):
+        monkeypatch.delenv(k, raising=False)
+    # Unset → default returned as-is (an int/float, not re-parsed); no default → None.
+    assert C.env_int("PAGES", 50, prefix="STOCK") == 50
+    assert C.env_float("RATE", 1.5, prefix="STOCK") == 1.5
+    assert C.env_int("PAGES") is None
+    assert C.env_float("RATE") is None
+    # Set & valid: parsed; the prefixed form wins over the unprefixed fallback.
+    monkeypatch.setenv("PAGES", "10")
+    monkeypatch.setenv("STOCK_PAGES", "200")
+    assert C.env_int("PAGES", 50, prefix="STOCK") == 200
+    monkeypatch.delenv("STOCK_PAGES", raising=False)
+    assert C.env_int("PAGES", 50, prefix="STOCK") == 10
+    monkeypatch.setenv("RATE", "2.5")
+    assert C.env_float("RATE", 1.0) == 2.5
+
+
+@pytest.mark.feature("F-006")
+def test_env_int_malformed_aborts_naming_the_variable(monkeypatch):
+    monkeypatch.setenv("PAGES", "abc")
+    with pytest.raises(SystemExit) as exc:
+        C.env_int("PAGES")
+    msg = str(exc.value)
+    assert "PAGES" in msg and "abc" in msg and "integer" in msg
+
+
+@pytest.mark.feature("F-006")
+def test_env_int_rejects_a_non_integer_number(monkeypatch):
+    # "10.5" is a valid float but not an int — env_int must reject it, not truncate.
+    monkeypatch.setenv("PAGES", "10.5")
+    with pytest.raises(SystemExit):
+        C.env_int("PAGES")
+
+
+@pytest.mark.feature("F-006")
+def test_env_float_malformed_aborts_naming_the_variable(monkeypatch):
+    monkeypatch.setenv("RATE", "x")
+    with pytest.raises(SystemExit) as exc:
+        C.env_float("RATE")
+    msg = str(exc.value)
+    assert "RATE" in msg and "number" in msg
+
+
 # ---------------------------------------------------------------------------
 # F-002 Tolerant number parsing
 # ---------------------------------------------------------------------------