✨ Add watch command to CLI for automatic re-rendering

- Implement `quickthumb watch <spec.json>` command to monitor changes in the spec file and re-render automatically.
- Require `watchfiles` for file watching functionality, updating installation instructions accordingly.
- Validate output format and quality parameters, ensuring proper error handling for invalid inputs.
- Update documentation to reflect changes in dependencies and command usage.

Author: sjquant

pyproject.toml

@@ -47,6 +47,7 @@ rembg = [
 ]
 cli = [
     "typer>=0.24.1,<0.25.0",
+    "watchfiles>=1.0.0,<2.0.0",
 ]
 
 [project.scripts]

quickthumb/cli.py

@@ -109,5 +109,92 @@ def replace(match: re.Match) -> str:
     return result
 
 
+@app.command()
+def watch(
+    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:
+    """Watch a JSON spec file and re-render on changes."""
+    try:
+        from watchfiles import watch as _watch  # type: ignore[import-untyped]
+    except ImportError:
+        typer.echo(
+            "watchfiles is not installed. Install it with: pip install 'quickthumb[cli]'",
+            err=True,
+        )
+        raise typer.Exit(1) from None
+
+    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)
+
+    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)
+
+    variables: dict[str, str] = {}
+    if var:
+        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
+
+    def _render_once() -> None:
+        try:
+            text = spec.read_text()
+        except (FileNotFoundError, PermissionError) as e:
+            typer.echo(str(e), err=True)
+            return
+
+        if variables:
+            try:
+                text = _substitute_vars(text, variables)
+            except ValidationError as e:
+                typer.echo(str(e), err=True)
+                return
+
+        try:
+            canvas = Canvas.from_json(text)
+        except (json.JSONDecodeError, ValidationError) as e:
+            typer.echo(str(e), err=True)
+            return
+
+        try:
+            canvas.render(
+                str(output),
+                format=fmt.upper() if fmt else None,  # type: ignore[arg-type]
+                quality=quality,
+            )
+            typer.echo(str(output))
+        except (RenderingError, OSError) as e:
+            typer.echo(str(e), err=True)
+
+    typer.echo(f"Watching {spec} … (Ctrl+C to stop)")
+    _render_once()
+
+    try:
+        for _ in _watch(spec):
+            _render_once()
+    except KeyboardInterrupt:
+        pass
+
+
 if __name__ == "__main__":
     main()

specs/SPEC.md

@@ -73,7 +73,7 @@ Parameters:
 
 #### `watch` (stretch goal)
 
-Re-render automatically when the spec file changes. Requires `watchdog`.
+Re-render automatically when the spec file changes. Requires `watchfiles`.
 
 ```bash
 quickthumb watch spec.json -o thumbnail.png
@@ -82,7 +82,7 @@ quickthumb watch spec.json -o thumbnail.png
 Install with:
 
 ```bash
-uv pip install "quickthumb[cli,watch]"
+uv pip install "quickthumb[cli]"
 ```
 
 ### Pipeline
@@ -103,7 +103,7 @@ uv pip install "quickthumb[cli,watch]"
 ### Notes
 
 - `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.
+- `quickthumb watch` exits with code 1 if `watchfiles` is not installed.
 - Errors print to stderr; the rendered image path prints to stdout on success.
 
 ---

specs/TASKS.md

@@ -1,31 +1,36 @@
 ## Tasks
 
 ### P0 — Critical / Quick Wins
+
 - [DONE] Export `RenderingError` from `__init__.py` so users can `from quickthumb import RenderingError`
 - [DONE] Raise `ValidationError` when `canvas.background()` is called with no `color`, `gradient`, or `image`
 - [DONE] Remove dead `_get_style_string` method in `canvas.py` (defined but never called)
 
 ### 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`
 - [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]`)
+
 - [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]`)
+- [DONE] Add `quickthumb watch <spec.json>` subcommand using `watchfiles` (`quickthumb[cli]`)
 - [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
 - [TODO] Raise `ValidationError` on unresolved placeholders before JSON parsing
 - [TODO] Add `Canvas.register_template(name, path)` and `Canvas.unregister_template(name)` registry
 - [TODO] Create `quickthumb/templates/` directory with starter templates: `youtube-16x9`, `instagram-square`, `twitter-card`, `og-image`
 
 #### Gradient / Image-Filled Text (Knockout Text)
+
 - [TODO] Add `TextFillImage` model with `path` and `fit` fields and `type: Literal["image"]` discriminator
 - [TODO] Add `fill` parameter to `TextLayer` accepting `LinearGradient`, `RadialGradient`, or `TextFillImage`
 - [TODO] Add `fill` parameter to `TextPart` for per-segment fill overrides
@@ -34,6 +39,7 @@
 - [TODO] Add JSON round-trip support using `type` discriminators (`linear_gradient`, `radial_gradient`, `image`)
 
 #### Noise / Grain Effect
+
 - [TODO] Add `Grain` effect model: `intensity`, `monochrome`, `blend_mode`, `opacity` fields with `type: "grain"` discriminator
 - [TODO] Add `Grain` to `BackgroundEffect` and `ImageEffect` unions
 - [TODO] Implement grain rendering using Pillow only (no NumPy)
@@ -42,12 +48,14 @@
 - [TODO] Add JSON round-trip for both per-layer `Grain` effect and top-level `GrainLayer`
 
 ### P2 — Docs & Discoverability
+
 - [TODO] Homepage headline: make the AI/JSON workflow angle front and center (currently buried)
 - [TODO] Add "Common LLM Mistakes" section to the JSON schema page (invalid hex, wrong position format, unsupported effects, etc.)
 - [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)
@@ -58,19 +66,23 @@
 - [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
 - [TODO] Split `canvas.py` (currently 2466 lines) into smaller modules before it becomes a maintenance burden
 
 ## Handoff Notes
+
 -
 -