✨ Add CLI, harden font cache, and fix review issues

- Add `quickthumb/cli.py` with `typer`: `render` subcommand with `-o`,
  `--format`, `--quality`, `--var` flags and proper exit codes (0/1/2)
- Validate `--format` (PNG/JPEG/WEBP), `--quality` range (1-95), and
  `--var` KEY=VALUE syntax; raise on unresolved `$VAR` placeholders
- Catch `FileNotFoundError`, `PermissionError`, `json.JSONDecodeError`
  in `render` and map to exit code 1; narrow render errors to
  `RenderingError`/`OSError` to avoid masking real bugs
- Add `quickthumb[cli]` optional dependency and entry point in
  `pyproject.toml`
- Support `QUICKTHUMB_FONT_CACHE_DIR` env var for font cache location;
  auto-create the directory if it does not exist (`makedirs exist_ok`)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: sjquant

pyproject.toml

@@ -45,6 +45,12 @@ rembg = [
     "onnxruntime>=1.24.1,<2.0.0",
     "rembg>=2.0.50,<3.0.0",
 ]
+cli = [
+    "typer>=0.24.1,<0.25.0",
+]
+
+[project.scripts]
+quickthumb = "quickthumb.cli:main"
 
 [dependency-groups]
 docs = [

quickthumb/canvas.py

@@ -2329,6 +2329,7 @@ def _download_and_cache_font(self, url: str) -> str:
         extension = os.path.splitext(url)[1] or ".ttf"
         cache_filename = f"quickthumb_font_{url_hash}{extension}"
         cache_dir = os.environ.get("QUICKTHUMB_FONT_CACHE_DIR", "/tmp")
+        os.makedirs(cache_dir, exist_ok=True)
         cache_path = os.path.join(cache_dir, cache_filename)
 
         if os.path.exists(cache_path):

quickthumb/cli.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from quickthumb.canvas import Canvas
+from quickthumb.errors import RenderingError, ValidationError
+
+_VALID_FORMATS = {"PNG", "JPEG", "WEBP"}
+
+app = typer.Typer(help="QuickThumb — programmatic thumbnail generation")
+
+
+@app.callback()
+def _callback() -> None:
+    """QuickThumb CLI."""
+
+
+def main() -> None:
+    app()
+
+
+@app.command()
+def render(
+    spec: Annotated[Path, typer.Argument(help="Path to a JSON spec file")],
+    output: Annotated[
+        Path,
+        typer.Option("-o", "--output", help="Output file path"),
+    ] = Path("output.png"),
+    fmt: Annotated[
+        str | None,
+        typer.Option("--format", help="Output format: PNG, JPEG, or WEBP"),
+    ] = None,
+    quality: Annotated[
+        int | None,
+        typer.Option("--quality", help="Quality for JPEG/WEBP (1-95)"),
+    ] = None,
+    var: Annotated[
+        list[str] | None,
+        typer.Option("--var", help="Variable substitution as KEY=VALUE"),
+    ] = None,
+) -> None:
+    """Render a JSON spec file to an image."""
+    # Validate --format early
+    if fmt is not None and fmt.upper() not in _VALID_FORMATS:
+        typer.echo(f"Invalid format '{fmt}'. Must be one of: PNG, JPEG, WEBP", err=True)
+        raise typer.Exit(1)
+
+    # Validate --quality range
+    if quality is not None and not (1 <= quality <= 95):
+        typer.echo(f"Invalid quality {quality}. Must be between 1 and 95.", err=True)
+        raise typer.Exit(1)
+
+    try:
+        try:
+            text = spec.read_text()
+        except (FileNotFoundError, PermissionError) as e:
+            typer.echo(str(e), err=True)
+            raise typer.Exit(1) from e
+
+        if var:
+            variables: dict[str, str] = {}
+            for item in var:
+                key, sep, value = item.partition("=")
+                if not sep:
+                    typer.echo(f"Invalid --var '{item}': expected KEY=VALUE format.", err=True)
+                    raise typer.Exit(1)
+                variables[key] = value
+            text = _substitute_vars(text, variables)
+
+        try:
+            canvas = Canvas.from_json(text)
+        except (json.JSONDecodeError, ValidationError) as e:
+            typer.echo(str(e), err=True)
+            raise typer.Exit(1) from e
+
+    except typer.Exit:
+        raise
+
+    try:
+        canvas.render(
+            str(output),
+            format=fmt.upper() if fmt else None,  # type: ignore[arg-type]
+            quality=quality,
+        )
+    except (RenderingError, OSError) as e:
+        typer.echo(str(e), err=True)
+        raise typer.Exit(2) from e
+
+    typer.echo(str(output))
+
+
+def _substitute_vars(text: str, variables: dict[str, str]) -> str:
+    def replace(match: re.Match) -> str:
+        key = match.group(1) or match.group(2)
+        return variables.get(key, match.group(0))
+
+    result = re.sub(r"\$\{(\w+)\}|\$(\w+)", replace, text)
+
+    unresolved = re.findall(r"\$\{(\w+)\}|\$(\w+)", result)
+    if unresolved:
+        names = [k1 or k2 for k1, k2 in unresolved]
+        raise ValidationError(f"Unresolved placeholder(s): {', '.join(names)}")
+
+    return result
+
+
+if __name__ == "__main__":
+    main()

specs/SPEC.md

@@ -4,22 +4,22 @@ This document specifies planned and exploratory features for QuickThumb. It is a
 
 ### Status Legend
 
-| Status | Meaning |
-|--------|---------|
-| `planned` | Committed for implementation; not yet shipped |
-| `in progress` | Actively being developed |
-| `done` | Shipped; refer to README.md for the final API |
-| `exploratory` | Under consideration; design not committed |
+| Status        | Meaning                                       |
+| ------------- | --------------------------------------------- |
+| `planned`     | Committed for implementation; not yet shipped |
+| `in progress` | Actively being developed                      |
+| `done`        | Shipped; refer to README.md for the final API |
+| `exploratory` | Under consideration; design not committed     |
 
 ### Feature Status
 
-| # | Feature | Status |
-|---|---------|--------|
-| 1 | CLI (`quickthumb` command) | `planned` |
-| 2 | Template System | `planned` |
-| 3 | Gradient / Image-Filled Text | `planned` |
-| 4 | Noise / Grain Effect | `planned` |
-| 5 | Presentation & Video | `exploratory` |
+| #   | Feature                      | Status        |
+| --- | ---------------------------- | ------------- |
+| 1   | CLI (`quickthumb` command)   | `planned`     |
+| 2   | Template System              | `planned`     |
+| 3   | Gradient / Image-Filled Text | `planned`     |
+| 4   | Noise / Grain Effect         | `planned`     |
+| 5   | Presentation & Video         | `exploratory` |
 
 ---
 
@@ -29,7 +29,7 @@ A `quickthumb` command-line tool for rendering JSON specs without writing Python
 
 ### Installation
 
-The CLI is an optional extra to avoid pulling `click` into the core dependency set.
+The CLI is an optional extra to avoid pulling `typer` into the core dependency set.
 
 ```bash
 uv pip install "quickthumb[cli]"
@@ -94,15 +94,15 @@ uv pip install "quickthumb[cli,watch]"
 
 ### Exit Codes
 
-| Code | Meaning |
-|------|---------|
-| 0 | Success |
-| 1 | Validation error (bad spec, missing required field, unknown layer type) |
-| 2 | Rendering error (missing file, download failure, unsupported format) |
+| Code | Meaning                                                                 |
+| ---- | ----------------------------------------------------------------------- |
+| 0    | Success                                                                 |
+| 1    | Validation error (bad spec, missing required field, unknown layer type) |
+| 2    | Rendering error (missing file, download failure, unsupported format)    |
 
 ### Notes
 
-- `click` is only imported inside `quickthumb/cli.py`; the rest of the library does not depend on it.
+- `typer` is only imported inside `quickthumb/cli.py`; the rest of the library does not depend on it.
 - `quickthumb watch` exits with code 1 if `watchdog` is not installed.
 - Errors print to stderr; the rendered image path prints to stdout on success.
 
@@ -171,12 +171,12 @@ Parameters:
 
 QuickThumb ships a small set of starter templates in `quickthumb/templates/`:
 
-| Name | Aspect Ratio | Description |
-|------|-------------|-------------|
-| `youtube-16x9` | 16:9 (1280×720) | Title left, subject image right |
-| `instagram-square` | 1:1 (1080×1080) | Centered headline with background image |
-| `twitter-card` | 2:1 (1200×600) | Logo + title + subtitle |
-| `og-image` | 1.91:1 (1200×630) | Open Graph social card |
+| Name               | Aspect Ratio      | Description                             |
+| ------------------ | ----------------- | --------------------------------------- |
+| `youtube-16x9`     | 16:9 (1280×720)   | Title left, subject image right         |
+| `instagram-square` | 1:1 (1080×1080)   | Centered headline with background image |
+| `twitter-card`     | 2:1 (1200×600)    | Logo + title + subtitle                 |
+| `og-image`         | 1.91:1 (1200×630) | Open Graph social card                  |
 
 Access by name:
 
@@ -310,7 +310,10 @@ Fallback rule: if `fill` is `None`, `color` is used as before.
   "fill": {
     "type": "linear_gradient",
     "angle": 90,
-    "stops": [["#FF6B6B", 0.0], ["#4ECDC4", 1.0]]
+    "stops": [
+      ["#FF6B6B", 0.0],
+      ["#4ECDC4", 1.0]
+    ]
   },
   "position": ["50%", "50%"],
   "align": "center",

specs/TASKS.md

@@ -8,16 +8,16 @@
 ### P1 — High Impact Features
 - [DONE] Rich text word-wrapping: auto-wrap `list[TextPart]` content when `max_width` is set (currently only plain string content wraps)
 - [DONE] Long-word overflow: truncate or warn when a single word exceeds `max_width` in `_wrap_text`
-- [TODO] Configurable font cache directory via `QUICKTHUMB_FONT_CACHE_DIR` env var (currently hardcoded to `/tmp`)
+- [DONE] Configurable font cache directory via `QUICKTHUMB_FONT_CACHE_DIR` env var (currently hardcoded to `/tmp`)
 
 ### P1 — Planned Features (see SPEC.md)
 
 #### CLI (`quickthumb[cli]`)
-- [TODO] Create `quickthumb/cli.py` with `click`; add `quickthumb[cli]` optional extra in `pyproject.toml`
-- [TODO] Implement `quickthumb render <spec.json>` with `-o`, `--format`, `--quality` flags
-- [TODO] Implement `--var KEY=VALUE` template variable substitution in the `render` subcommand
+- [DONE] Create `quickthumb/cli.py` with `click`; add `quickthumb[cli]` optional extra in `pyproject.toml`
+- [DONE] Implement `quickthumb render <spec.json>` with `-o`, `--format`, `--quality` flags
+- [DONE] Implement `--var KEY=VALUE` template variable substitution in the `render` subcommand
 - [TODO] Add `quickthumb watch <spec.json>` subcommand using `watchdog` (`quickthumb[cli,watch]`)
-- [TODO] Wire up exit codes: 0 success, 1 `ValidationError`, 2 `RenderingError`
+- [DONE] Wire up exit codes: 0 success, 1 `ValidationError`, 2 `RenderingError`
 
 #### Template System
 - [TODO] Implement `Canvas.from_template(spec_or_path, variables={})` with `$var` / `${var}` string substitution
@@ -47,6 +47,25 @@
 - [TODO] Add "Why not X" section: brief comparison vs raw Pillow and html2image to help developers justify the dependency
 - [TODO] Add community entry point: link to GitHub issues/discussions for bug reports and questions
 
+### P1 — CLI Hardening (from code review)
+- [DONE] CLI `render`: catch `FileNotFoundError` / `PermissionError` from `spec.read_text()` and exit with code 1
+- [DONE] CLI `render`: catch `json.JSONDecodeError` from `Canvas.from_json()` and exit with code 1
+- [DONE] `_substitute_vars`: raise `ValidationError` on unresolved `$VAR` / `${VAR}` placeholders (currently passes them through silently)
+- [TODO] Guard CLI entrypoint import: print a helpful message and exit if `typer` is not installed instead of crashing with `ImportError`
+- [DONE] CLI `render`: validate `--var` entries contain `=`; raise a clear error when `--var keyonly` is passed (currently silently maps to empty string)
+- [DONE] CLI `render`: replace bare `except Exception` with `except (RenderingError, OSError)` to avoid masking real bugs
+- [DONE] CLI `render`: validate `--quality` is in `1–95` range (`typer.Option(..., min=1, max=95)`)
+- [DONE] CLI `render`: validate `--format` is one of `PNG`, `JPEG`, `WEBP`; reject unknown values early
+
+### P2 — Font Cache Hardening (from code review)
+- [TODO] Use `tempfile.gettempdir()` instead of hardcoded `"/tmp"` as the default font cache dir (fixes Windows compatibility)
+- [TODO] Validate downloaded font content before writing to cache (currently writes arbitrary data from any URL)
+- [DONE] Call `os.makedirs(cache_dir, exist_ok=True)` before writing cached font; `QUICKTHUMB_FONT_CACHE_DIR` pointing to a non-existent dir currently crashes with `FileNotFoundError`
+
+### P2 — CLI Polish (from code review)
+- [TODO] Rename `format` parameter to `fmt` or `output_format` internally — currently shadows Python's built-in `format()`
+- [TODO] Widen typer version pin from `>=0.24.1,<0.25.0` to `>=0.24.1,<1.0` to avoid unnecessary resolver conflicts
+
 ### P3 — Lower Priority
 - [TODO] Fix color tuple JSON round-trip: `BackgroundLayer.color` accepts RGB tuples but they break `to_json()` / `from_json()`
 - [TODO] Font metadata reading: use `fonttools` to read font weight/style from file metadata instead of relying on filename parsing

tests/test_canvas.py

@@ -424,6 +424,37 @@ def test_should_default_to_tmp_when_font_cache_dir_not_set(self, monkeypatch):
 
         assert result.startswith("/tmp")
 
+    def test_should_create_font_cache_dir_if_not_exists(self, monkeypatch):
+        """_download_and_cache_font creates QUICKTHUMB_FONT_CACHE_DIR if it does not exist"""
+        import os
+        import tempfile
+        from unittest.mock import MagicMock, patch
+
+        from quickthumb import Canvas
+
+        canvas = Canvas(100, 100)
+
+        with tempfile.TemporaryDirectory() as base:
+            new_dir = os.path.join(base, "nested", "cache")
+            monkeypatch.setenv("QUICKTHUMB_FONT_CACHE_DIR", new_dir)
+
+            fake_font_data = b"fake font data"
+            mock_response = MagicMock()
+            mock_response.__enter__ = lambda s: s
+            mock_response.__exit__ = MagicMock(return_value=False)
+            mock_response.read.return_value = fake_font_data
+
+            # Given: cache dir does not exist yet
+            assert not os.path.exists(new_dir)
+
+            # When: downloading a font
+            with patch("quickthumb.canvas.urlopen", return_value=mock_response):
+                result = canvas._download_and_cache_font("https://example.com/font3.ttf")
+
+            # Then: the directory is created and the font is written there
+            assert os.path.exists(new_dir)
+            assert result.startswith(new_dir)
+
     def test_should_raise_error_when_custom_callback_returns_different_size(self):
         """custom callback should preserve canvas dimensions when returning an image"""
         import os