Address PR #37 review: harden gen-api-key.py + correct semver bump

Triage of Qodo findings on #37:

- #1 (rule 796119): CHANGELOG `~/.model-gear` → `$HOME/.model-gear`. (The .py
  --help/docstring keep `~/.model-gear` to match the repo-wide CLI help text;
  Qodo's docs/config rule only flags the markdown.)
- #2 (unreadable/dir .env crash): main() preflights that .env is a regular file
  and wraps the read/update/write in try/except OSError -> EXIT_ENV_ERROR,
  matching _read_key()'s graceful degradation.
- #3 (under-scoped bump): a new documented capability is a minor, not a patch —
  0.18.1 -> 0.19.0.
- #4 (unhandled chmod): os.chmod is now best-effort (try/except OSError with a
  note), so a chmod-unsupported FS doesn't crash after a successful write.
- #5 (unvalidated --bytes): reject `< 16` (128-bit floor) with a user error
  before generating, so no weak key or token_urlsafe stack trace.

New tests: too-few-bytes and non-regular-file .env.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: OriNachum

CHANGELOG.md

@@ -4,18 +4,20 @@ All notable changes to this project are documented here. 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.18.1] - 2026-06-09
+## [0.19.0] - 2026-06-09
 
 ### Added
 
 - **`scripts/gen-api-key.py`** — generate or rotate the bearer key
   (`CULTURE_VLLM_API_KEY`) that gates the served API. The secret is created with
   the stdlib `secrets` module and **never hardcoded**, so the script is safe in the
   open-source repo; the key only ever lands in the gitignored deployment `.env`
-  (written `0o600`). Hidden by default (no echo into logs/scrollback); `--show`
-  prints it, `--force` rotates an existing key. Resolves the deployment dir like
-  the `model` CLI (`--dir` → `$MODEL_GEAR_DIR` → `~/.model-gear`). Referenced from
-  the README "Expose the API" section.
+  (written `0o600`, best-effort). Hidden by default (no echo into logs/scrollback);
+  `--show` prints it, `--force` rotates an existing key, and `--bytes` (min 16) is
+  validated. Resolves the deployment dir like the `model` CLI (`--dir` →
+  `$MODEL_GEAR_DIR` → `$HOME/.model-gear`), degrades gracefully on an unreadable or
+  non-regular `.env`, and runs from a wheel install (no `model_gear` import).
+  Referenced from the README "Expose the API" section.
 
 ## [0.18.0] - 2026-06-09
 

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "model-gear"
-version = "0.18.1"
+version = "0.19.0"
 description = "model-gear — run, assess, and switch the local vLLM model."
 readme = "README.md"
 license = "MIT"

scripts/gen-api-key.py

@@ -31,6 +31,7 @@
 
 KEY = "CULTURE_VLLM_API_KEY"
 PREFIX = "mg-"  # human-readable provenance marker; not a secret
+MIN_BYTES = 16  # 128-bit floor — below this the key is too weak to gate a public API
 
 
 def _deploy_dir(explicit: str | None) -> Path:
@@ -68,7 +69,11 @@ def _write_key(env_path: Path, value: str) -> None:
     if not seen:
         out.append(f"{KEY}={value}")
     env_path.write_text("\n".join(out) + "\n", encoding="utf-8")
-    os.chmod(env_path, 0o600)  # the .env holds a secret — keep it owner-only
+    try:
+        os.chmod(env_path, 0o600)  # the .env holds a secret — keep it owner-only
+    except OSError:
+        # best-effort hardening; some filesystems / platforms don't support chmod
+        print(f">> note: could not set 0o600 on {env_path} (left as-is)", file=sys.stderr)
 
 
 def main(argv: list[str] | None = None) -> int:
@@ -78,7 +83,10 @@ def main(argv: list[str] | None = None) -> int:
     parser.add_argument("--dir", help="Deployment dir (default: $MODEL_GEAR_DIR or ~/.model-gear).")
     parser.add_argument("--force", action="store_true", help="Rotate even if a key already exists.")
     parser.add_argument(
-        "--bytes", type=int, default=32, help="Token entropy in bytes (default: 32)."
+        "--bytes",
+        type=int,
+        default=32,
+        help=f"Token entropy in bytes (default: 32, min: {MIN_BYTES}).",
     )
     parser.add_argument(
         "--show", action="store_true", help="Print the key on stdout (else hidden)."
@@ -93,6 +101,12 @@ def main(argv: list[str] | None = None) -> int:
         )
         print("hint: run 'model init --apply' to scaffold it first", file=sys.stderr)
         return 2
+    if env_path.exists() and not env_path.is_file():
+        print(f"error: {env_path} exists but is not a regular file", file=sys.stderr)
+        return 2
+    if args.bytes < MIN_BYTES:
+        print(f"error: --bytes must be at least {MIN_BYTES} (got {args.bytes})", file=sys.stderr)
+        return 1
 
     existing = _read_key(env_path)
     if existing and not args.force:
@@ -101,7 +115,11 @@ def main(argv: list[str] | None = None) -> int:
         return 1
 
     token = PREFIX + secrets.token_urlsafe(args.bytes)
-    _write_key(env_path, token)
+    try:
+        _write_key(env_path, token)
+    except OSError as exc:
+        print(f"error: could not write {env_path}: {exc}", file=sys.stderr)
+        return 2
 
     verb = "rotated" if existing else "set"
     print(f">> {verb} {KEY} in {env_path}", file=sys.stderr)

tests/test_gen_api_key.py

@@ -72,3 +72,16 @@ def test_env_perms_are_owner_only(tmp_path) -> None:
     env.write_text("", encoding="utf-8")
     gen.main(["--dir", str(tmp_path)])
     assert (env.stat().st_mode & 0o777) == 0o600
+
+
+def test_rejects_too_few_bytes(tmp_path, capsys) -> None:
+    (tmp_path / ".env").write_text("", encoding="utf-8")
+    assert gen.main(["--dir", str(tmp_path), "--bytes", "4"]) == 1
+    assert "at least" in capsys.readouterr().err
+    assert gen._read_key(tmp_path / ".env") is None  # nothing written
+
+
+def test_non_regular_env_is_env_error(tmp_path, capsys) -> None:
+    (tmp_path / ".env").mkdir()  # a directory where a regular .env is expected
+    assert gen.main(["--dir", str(tmp_path)]) == 2
+    assert "not a regular file" in capsys.readouterr().err