Added v0.1 — vendor-agnostic stdlib core extracted from commons (T-1 / option C)

code_commons: env_required/env_opt/env_get (F-001), parse_num (F-002), build_remote_path (F-003), currency_symbol (F-004), log (F-005). Standard library only, requires-python >=3.9, CI 3.9/3.11/3.12 matrix. 24 tests, green.

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

Author: mwebbers

.github/workflows/test.yml

@@ -0,0 +1,20 @@
+name: test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[test]"
+      - run: pytest

.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+.venv/
+venv/
+*.egg-info/
+build/
+dist/
+.DS_Store
+
+# Secrets and local runtime config — never commit.
+.env
+.env.*
+!.env.example

CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this package are documented here. Each behaviour change
+references the SCOPE.md feature ID(s) it implements.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/); the project
+adheres to semantic versioning.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-05-31
+
+Initial release: the vendor-agnostic, standard-library-only core, extracted from
+`claude-woocommerce-commons` so every routine — not only the WooCommerce family —
+can share one tested copy of the generic plumbing instead of re-implementing it
+(review thread T-1 / option C: a dependency-light core + a thin vendor toolkit on
+top).
+
+### Added
+- **F-001** `env_required` / `env_opt` / `env_get` environment helpers with the
+  project-prefix-with-fallback lookup.
+- **F-002** Tolerant `parse_num()` (comma thousands separators; comma-decimal
+  locale input documented as out of scope).
+- **F-003** `build_remote_path(base, folder, filename)` remote-path builder.
+- **F-004** `currency_symbol()` 3-letter-code → display symbol.
+- **F-005** `log()` timestamped run-log line.

CLAUDE.md

@@ -0,0 +1,48 @@
+# CLAUDE.md
+
+Context for Claude Code in this repo. Keep this short — it loads on every session.
+
+## What this is
+
+`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**.
+
+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.
+`claude-woocommerce-commons`), which own their own runtime contracts.
+
+## Read first
+
+Read `SCOPE.md` before changing anything. Every feature has an ID (`F-001`…) and
+must stay covered by a test (`tests/test_scope_coverage.py` enforces it).
+
+## Working rules
+
+- Any behaviour change starts in `SCOPE.md`: add/edit a feature ID, then write or
+  update its test, then change the code. Never the other way around.
+- Every test is tagged `@pytest.mark.feature("F-00X")`.
+- Run `pytest` after any change.
+- After a behaviour change, add a line under `[Unreleased]` in `CHANGELOG.md`.
+- **No third-party dependency, ever.** The whole point is that a routine can
+  install this without pulling in heavier libraries. Anything needing `requests`,
+  `openpyxl`, etc. belongs in a vendor toolkit that depends on this, not here.
+- **This is a dependency of routines and vendor toolkits.** A breaking change to a
+  public name must bump the version and be rolled out to each consumer by bumping
+  its pin. Prefer additive changes.
+
+## Deployment floor
+
+`requires-python` is `>=3.9` and CI runs a `3.9` / `3.11` / `3.12` matrix. The
+Cowork sandbox that runs scheduled routines is **Python 3.11**, so a consumer that
+`pip install`s this must be able to; keeping the floor at the lowest interpreter
+any routine runs on (and testing it) guarantees that.
+
+## Commands
+
+- Install (editable, with tests): `pip install -e ".[test]"`
+- Run tests: `pytest`
+- The package exposes a single top-level module:
+  `from code_commons import env_required, env_opt, parse_num, build_remote_path, currency_symbol, log`

README.md

@@ -0,0 +1,47 @@
+# Claude Code Commons
+
+Vendor-agnostic, **standard-library-only** plumbing shared by Claude routine
+repos. One tiny installable package, versioned and tested in isolation, so a fix
+lands in every routine at once instead of being copy-pasted — and with **no
+third-party dependency**, so a routine can adopt it without pulling in a web
+client or spreadsheet engine.
+
+It contains **no vendor or report logic** — only the generic helpers routines
+have in common. Heavier, vendor-specific toolkits (e.g.
+`claude-woocommerce-commons`) build on top of it.
+
+## What's inside
+
+| Area | API |
+|------|-----|
+| Env | `env_required(key, *, prefix)`, `env_opt(key, default, *, prefix)`, `env_get` (alias of `env_opt`) |
+| Parsing | `parse_num()` — tolerant of loose JSON (comma thousands separators) |
+| Currency | `currency_symbol(code)` — 3-letter code → display symbol |
+| Paths | `build_remote_path(base, folder, filename)` — slash-normalised join |
+| Logging | `log(msg)` — `[HH:MM:SS] msg`, flushed |
+
+See `SCOPE.md` for the full feature contract.
+
+## Install
+
+```bash
+pip install -e ".[test]"        # local dev (editable) + pytest
+```
+
+The package exposes a single top-level module:
+
+```python
+from code_commons import env_required, env_opt, parse_num, build_remote_path, log
+
+url = env_required("WC_URL", prefix="STOCK")        # STOCK_WC_URL, else WC_URL
+path = build_remote_path("/Reports", "Stock", "report.xlsx")  # /Reports/Stock/report.xlsx
+```
+
+## Tests
+
+```bash
+pytest
+```
+
+A coverage test (`tests/test_scope_coverage.py`) fails if any `SCOPE.md` feature
+lacks a test or a test references a feature not in `SCOPE.md`.

SCOPE.md

@@ -0,0 +1,72 @@
+# Scope
+
+This document is the **single source of truth** for what this package does and
+why. The README explains *how to use* it; this file defines *what it must do*.
+Every feature below has an ID. Every feature ID must be covered by at least one
+test (enforced by `tests/test_scope_coverage.py`). Do not add, change, or remove
+a feature here without updating the tests — that is how current behaviour is
+guaranteed across future changes.
+
+## Purpose
+
+`claude-code-commons` is the small, **vendor-agnostic, standard-library-only**
+toolkit shared by Claude routine repos. It owns the generic helpers every routine
+tends to re-implement — environment lookup, tolerant number parsing, currency
+symbols, remote-path building and a run-log line — with **no third-party
+dependency**, so any routine can install it without dragging in a web client or a
+spreadsheet engine. Vendor-specific toolkits (e.g. a WooCommerce REST client)
+build on top of it.
+
+## Why it exists
+
+Every routine needs the same handful of helpers. Copying them into each repo lets
+the copies drift — a fix made in one is missed in the others. One tiny,
+dependency-free package, versioned and tested in isolation, removes that hazard
+and keeps the heavier vendor toolkits thin: they import the core and add only
+their vendor-specific parts.
+
+## Features (acceptance criteria)
+
+Each feature is testable. The ID in brackets is referenced by tests via
+`@pytest.mark.feature("F-00X")`.
+
+- **[F-001] Environment helpers with project-prefix fallback.** `env_required(key,
+  *, prefix="")` and `env_opt(key, default, *, prefix="")` — with `env_get` as a
+  convenience alias of `env_opt` — resolve a variable by trying `<prefix>_<key>`
+  first and falling back to the unprefixed `<key>` (plain `<key>` with no prefix,
+  backward compatible). `env_required` aborts with a clear `SystemExit` naming the
+  variable when neither form is set; `env_opt`/`env_get` return `default`. This
+  lets a family of routines share one environment: shared values set once
+  unprefixed, per-routine values set prefixed so they never collide.
+
+- **[F-002] Tolerant number parsing.** `parse_num()` accepts comma **thousands**
+  separators (`"1,234"` → `1234.0`), plain numbers and numeric strings, and
+  returns `0.0` for `None`, `""` or unparseable input — it never raises. A comma
+  is always a thousands separator (dot-decimal domain); comma-**decimal** locale
+  input (`"1,5"` → `15.0`, not `1.5`) is out of scope and handled by per-routine
+  locale parsers.
+
+- **[F-003] Remote-path builder.** `build_remote_path(base, folder, filename)`
+  joins an optional base directory, an optional sub-folder and a filename into one
+  absolute, slash-normalised path. Lets a family share one base
+  (`DROPBOX_PATH`) while each writes into its own `<PREFIX>_DROPBOX_FOLDER`
+  sub-folder: base `/Reports` + folder `Stock` → `/Reports/Stock/<filename>`. An
+  empty/None folder drops the file straight into `base`; an empty/None base falls
+  back to the root — so an unset folder reproduces the previous single-directory
+  behaviour (backward compatible).
+
+- **[F-004] Currency symbols.** `currency_symbol(code)` maps a 3-letter currency
+  code to a display symbol (case-insensitive), falling back to the upper-cased
+  code itself for unmapped currencies.
+
+- **[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.
+
+## Out of scope
+
+Anything vendor-specific (a WooCommerce/Shopify/… client, shop meta keys);
+network access of any kind (this package makes no network calls); spreadsheet or
+file I/O; currency *conversion* (only symbol labelling); and locale-aware
+comma-decimal parsing. Vendor toolkits and the routines themselves own those. If a
+new generic, dependency-free helper is ever needed, add a feature ID here first,
+then a test, then the code.

pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "claude-code-commons"
+version = "0.1.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.
+requires-python = ">=3.9"
+dependencies = []
+
+[project.optional-dependencies]
+test = ["pytest>=8"]
+
+# A single top-level module, `code_commons`, living under src/. Installing this
+# package makes `from code_commons import env_required, parse_num, ...` work in
+# the consuming routines and vendor toolkits.
+[tool.setuptools]
+py-modules = ["code_commons"]
+
+[tool.setuptools.package-dir]
+"" = "src"
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+addopts = "--strict-markers"
+markers = [
+    "feature: link a test to a SCOPE.md feature ID, e.g. feature('F-001')",
+]