charmfix 0.1.0__tar.gz

charmfix-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Václav Vinklát
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

charmfix-0.1.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: charmfix
+Version: 0.1.0
+Summary: Repair broken or missing EXIF metadata in Kodak Charmera (Generalplus) JPEGs without touching image data
+Keywords: exif,jpeg,kodak,charmera,photos,metadata
+Author: Václav Vinklát
+Author-email: Václav Vinklát <vin@email.cz>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Graphics
+Requires-Dist: piexif>=1.1.3
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/vinklat/charmfix
+Project-URL: Source, https://github.com/vinklat/charmfix
+Project-URL: Issues, https://github.com/vinklat/charmfix/issues
+Project-URL: Documentation, https://github.com/vinklat/charmfix/blob/main/CLI.md
+Description-Content-Type: text/markdown
+
+# charmfix
+
+Repair the EXIF metadata of Kodak Charmera photos so Apple Photos, and everything else, shows the
+right date, size and camera. Only metadata changes: every byte of image data stays the same (→
+[REPAIRS.md](https://github.com/vinklat/charmfix/blob/v0.1.0/REPAIRS.md#invariant)), and charmfix checks this before it writes each file (→
+[REPAIRS.md](https://github.com/vinklat/charmfix/blob/v0.1.0/REPAIRS.md#verification)). Source files are never modified (→
+[CLI.md](https://github.com/vinklat/charmfix/blob/v0.1.0/CLI.md#source-safety)). Repaired copies go to a separate folder.
+
+## What is wrong with Charmera files
+
+The Charmera uses a Generalplus chip; its JPEGs carry a `GPEncoder` comment. Most files have **no
+EXIF at all**, so Photos falls back to the import or copy date. Other firmware writes broken EXIF:
+dates like `2026:03:03:12:16:29`, a 640×480 size on a 1440×1080 image, or a MakerNote that points
+outside the EXIF block. charmfix fixes all of these; the exact rules are in
+[REPAIRS.md](https://github.com/vinklat/charmfix/blob/v0.1.0/REPAIRS.md).
+
+## Install
+
+Released versions are published to [PyPI](https://pypi.org/project/charmfix/). With
+[uv](https://docs.astral.sh/uv/):
+
+```sh
+uv tool install charmfix   # puts `charmfix` on your PATH
+uvx charmfix -h            # or run it without installing
+```
+
+`pipx install charmfix` works too. Before the first release, or to run unreleased changes, install
+from a checkout of this repository (→ [DEVELOPMENT.md](https://github.com/vinklat/charmfix/blob/v0.1.0/DEVELOPMENT.md#quality-gates)):
+
+```sh
+uv tool install .
+uvx --from . charmfix -h
+```
+
+Supported Python versions → [DEVELOPMENT.md](https://github.com/vinklat/charmfix/blob/v0.1.0/DEVELOPMENT.md#prerequisites-and-setup).
+
+## Usage
+
+```sh
+charmfix /Volumes/CHARMERA                     # writes to ~/Pictures/Kodak Charmera Repaired
+charmfix /Volumes/CHARMERA -o ~/Desktop/fixed --report ~/Desktop/charmfix-report.json
+charmfix /Volumes/CHARMERA --dry-run -v        # show what would change, write nothing
+```
+
+Without `-o`, copies go to the default output folder → [CLI.md](https://github.com/vinklat/charmfix/blob/v0.1.0/CLI.md#options). All options, exit
+codes and the report format are in [CLI.md](https://github.com/vinklat/charmfix/blob/v0.1.0/CLI.md). Each file gets a status →
+[REPAIRS.md](https://github.com/vinklat/charmfix/blob/v0.1.0/REPAIRS.md#status). Running charmfix again on the same card skips files it has already
+written → [CLI.md](https://github.com/vinklat/charmfix/blob/v0.1.0/CLI.md#output-files).
+
+**Run it on the card itself.** When a file has no usable EXIF date (often no EXIF at all), the
+capture date is the file's modification time, which the camera sets when it takes the photo
+([rule 1a](https://github.com/vinklat/charmfix/blob/v0.1.0/REPAIRS.md#rules)). Use the mounted card, or a copy that kept the times (`cp -p`, Finder
+copy). Downloaded or exported files usually carry the copy time instead.
+
+**macOS blocks the card?** Follow the hint charmfix prints (→ [CLI.md](https://github.com/vinklat/charmfix/blob/v0.1.0/CLI.md#discovery)): allow the
+app you run it from under System Settings → Privacy & Security → Files and Folders → Removable
+Volumes (or Full Disk Access), then restart that app.
+
+## Apple Photos workflow
+
+1. Insert the card and run `charmfix /Volumes/<card> --report ~/charmfix-report.json`.
+2. Check the summary and look at any `partial` or `failed` lines.
+3. In Photos, choose **File → Import…** and pick the output folder.
+
+## Documentation
+
+| Location | Audience | Authority |
+| -- | -- | -- |
+| [CLI.md](https://github.com/vinklat/charmfix/blob/v0.1.0/CLI.md) | Users, developers and AI agents | Canonical contract |
+| [REPAIRS.md](https://github.com/vinklat/charmfix/blob/v0.1.0/REPAIRS.md), [DEVELOPMENT.md](https://github.com/vinklat/charmfix/blob/v0.1.0/DEVELOPMENT.md), [TESTING.md](https://github.com/vinklat/charmfix/blob/v0.1.0/TESTING.md) | Developers and AI agents | Canonical contracts |
+| [AGENTS.md](https://github.com/vinklat/charmfix/blob/v0.1.0/AGENTS.md), [CLAUDE.md](https://github.com/vinklat/charmfix/blob/v0.1.0/CLAUDE.md) (imports AGENTS.md) | AI agents | How to use the contracts |
+| `README.md` | Users | Non-canonical user guide |
+
+## License
+
+MIT → [LICENSE](https://github.com/vinklat/charmfix/blob/v0.1.0/LICENSE).

charmfix-0.1.0/README.md

@@ -0,0 +1,76 @@
+# charmfix
+
+Repair the EXIF metadata of Kodak Charmera photos so Apple Photos, and everything else, shows the
+right date, size and camera. Only metadata changes: every byte of image data stays the same (→
+[REPAIRS.md](https://github.com/vinklat/charmfix/blob/v0.1.0/REPAIRS.md#invariant)), and charmfix checks this before it writes each file (→
+[REPAIRS.md](https://github.com/vinklat/charmfix/blob/v0.1.0/REPAIRS.md#verification)). Source files are never modified (→
+[CLI.md](https://github.com/vinklat/charmfix/blob/v0.1.0/CLI.md#source-safety)). Repaired copies go to a separate folder.
+
+## What is wrong with Charmera files
+
+The Charmera uses a Generalplus chip; its JPEGs carry a `GPEncoder` comment. Most files have **no
+EXIF at all**, so Photos falls back to the import or copy date. Other firmware writes broken EXIF:
+dates like `2026:03:03:12:16:29`, a 640×480 size on a 1440×1080 image, or a MakerNote that points
+outside the EXIF block. charmfix fixes all of these; the exact rules are in
+[REPAIRS.md](https://github.com/vinklat/charmfix/blob/v0.1.0/REPAIRS.md).
+
+## Install
+
+Released versions are published to [PyPI](https://pypi.org/project/charmfix/). With
+[uv](https://docs.astral.sh/uv/):
+
+```sh
+uv tool install charmfix   # puts `charmfix` on your PATH
+uvx charmfix -h            # or run it without installing
+```
+
+`pipx install charmfix` works too. Before the first release, or to run unreleased changes, install
+from a checkout of this repository (→ [DEVELOPMENT.md](https://github.com/vinklat/charmfix/blob/v0.1.0/DEVELOPMENT.md#quality-gates)):
+
+```sh
+uv tool install .
+uvx --from . charmfix -h
+```
+
+Supported Python versions → [DEVELOPMENT.md](https://github.com/vinklat/charmfix/blob/v0.1.0/DEVELOPMENT.md#prerequisites-and-setup).
+
+## Usage
+
+```sh
+charmfix /Volumes/CHARMERA                     # writes to ~/Pictures/Kodak Charmera Repaired
+charmfix /Volumes/CHARMERA -o ~/Desktop/fixed --report ~/Desktop/charmfix-report.json
+charmfix /Volumes/CHARMERA --dry-run -v        # show what would change, write nothing
+```
+
+Without `-o`, copies go to the default output folder → [CLI.md](https://github.com/vinklat/charmfix/blob/v0.1.0/CLI.md#options). All options, exit
+codes and the report format are in [CLI.md](https://github.com/vinklat/charmfix/blob/v0.1.0/CLI.md). Each file gets a status →
+[REPAIRS.md](https://github.com/vinklat/charmfix/blob/v0.1.0/REPAIRS.md#status). Running charmfix again on the same card skips files it has already
+written → [CLI.md](https://github.com/vinklat/charmfix/blob/v0.1.0/CLI.md#output-files).
+
+**Run it on the card itself.** When a file has no usable EXIF date (often no EXIF at all), the
+capture date is the file's modification time, which the camera sets when it takes the photo
+([rule 1a](https://github.com/vinklat/charmfix/blob/v0.1.0/REPAIRS.md#rules)). Use the mounted card, or a copy that kept the times (`cp -p`, Finder
+copy). Downloaded or exported files usually carry the copy time instead.
+
+**macOS blocks the card?** Follow the hint charmfix prints (→ [CLI.md](https://github.com/vinklat/charmfix/blob/v0.1.0/CLI.md#discovery)): allow the
+app you run it from under System Settings → Privacy & Security → Files and Folders → Removable
+Volumes (or Full Disk Access), then restart that app.
+
+## Apple Photos workflow
+
+1. Insert the card and run `charmfix /Volumes/<card> --report ~/charmfix-report.json`.
+2. Check the summary and look at any `partial` or `failed` lines.
+3. In Photos, choose **File → Import…** and pick the output folder.
+
+## Documentation
+
+| Location | Audience | Authority |
+| -- | -- | -- |
+| [CLI.md](https://github.com/vinklat/charmfix/blob/v0.1.0/CLI.md) | Users, developers and AI agents | Canonical contract |
+| [REPAIRS.md](https://github.com/vinklat/charmfix/blob/v0.1.0/REPAIRS.md), [DEVELOPMENT.md](https://github.com/vinklat/charmfix/blob/v0.1.0/DEVELOPMENT.md), [TESTING.md](https://github.com/vinklat/charmfix/blob/v0.1.0/TESTING.md) | Developers and AI agents | Canonical contracts |
+| [AGENTS.md](https://github.com/vinklat/charmfix/blob/v0.1.0/AGENTS.md), [CLAUDE.md](https://github.com/vinklat/charmfix/blob/v0.1.0/CLAUDE.md) (imports AGENTS.md) | AI agents | How to use the contracts |
+| `README.md` | Users | Non-canonical user guide |
+
+## License
+
+MIT → [LICENSE](https://github.com/vinklat/charmfix/blob/v0.1.0/LICENSE).

charmfix-0.1.0/pyproject.toml

@@ -0,0 +1,86 @@
+[project]
+name = "charmfix"
+version = "0.1.0"
+description = "Repair broken or missing EXIF metadata in Kodak Charmera (Generalplus) JPEGs without touching image data"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+dependencies = ["piexif>=1.1.3"]
+keywords = [
+    "exif",
+    "jpeg",
+    "kodak",
+    "charmera",
+    "photos",
+    "metadata",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Multimedia :: Graphics",
+]
+
+[[project.authors]]
+name = "Václav Vinklát"
+email = "vin@email.cz"
+
+[project.urls]
+Homepage = "https://github.com/vinklat/charmfix"
+Source = "https://github.com/vinklat/charmfix"
+Issues = "https://github.com/vinklat/charmfix/issues"
+Documentation = "https://github.com/vinklat/charmfix/blob/main/CLI.md"
+
+[project.scripts]
+charmfix = "charmfix.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.12.23,<0.14.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pillow>=11",
+    "hypothesis>=6",
+    "ruff>=0.8",
+    "mypy>=1.13",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "W",
+    "I",
+    "B",
+    "UP",
+    "SIM",
+    "RUF",
+]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+
+[[tool.mypy.overrides]]
+module = [
+    "piexif",
+    "piexif.*",
+]
+ignore_missing_imports = true

charmfix-0.1.0/pyproject.toml.orig

@@ -0,0 +1,66 @@
+[project]
+name = "charmfix"
+version = "0.1.0"
+description = "Repair broken or missing EXIF metadata in Kodak Charmera (Generalplus) JPEGs without touching image data"
+readme = "README.md"
+authors = [
+    { name = "Václav Vinklát", email = "vin@email.cz" }
+]
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+dependencies = ["piexif>=1.1.3"]
+keywords = ["exif", "jpeg", "kodak", "charmera", "photos", "metadata"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Multimedia :: Graphics",
+]
+
+[project.urls]
+Homepage = "https://github.com/vinklat/charmfix"
+Source = "https://github.com/vinklat/charmfix"
+Issues = "https://github.com/vinklat/charmfix/issues"
+Documentation = "https://github.com/vinklat/charmfix/blob/main/CLI.md"
+
+[project.scripts]
+charmfix = "charmfix.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.12.23,<0.14.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pillow>=11",
+    "hypothesis>=6",
+    "ruff>=0.8",
+    "mypy>=1.13",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "SIM", "RUF"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+
+[[tool.mypy.overrides]]
+module = ["piexif", "piexif.*"]
+ignore_missing_imports = true

charmfix-0.1.0/src/charmfix/__init__.py

@@ -0,0 +1,10 @@
+"""charmfix: repair EXIF metadata of Kodak Charmera JPEGs without touching image data."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("charmfix")
+except PackageNotFoundError:  # run from a source tree that was never installed
+    __version__ = "0+unknown"

charmfix-0.1.0/src/charmfix/cli.py

@@ -0,0 +1,233 @@
+"""Command-line entry point."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+from typing import TextIO
+
+from . import __version__
+from .discovery import unreadable_reason
+from .pipeline import DiskFullError, Job, RunOptions, prepare, process_file
+from .report import FileResult, Summary, build_report, write_report
+
+DEFAULT_OUTPUT = Path.home() / "Pictures" / "Kodak Charmera Repaired"
+MACOS_PERMISSION_HINT = (
+    "macOS is blocking access. Allow the app you run charmfix from (Terminal, iTerm, "
+    "VS Code, ...) under System Settings > Privacy & Security > Files and Folders > "
+    "Removable Volumes (or Full Disk Access), then restart that app and try again."
+)
+EXIT_OK, EXIT_FAILURES, EXIT_FATAL, EXIT_INTERRUPTED = 0, 1, 2, 130
+
+log = logging.getLogger("charmfix")
+
+
+class _Progress:
+    """A single status line rewritten on stderr, only when stderr is a terminal."""
+
+    def __init__(self, stream: TextIO, enabled: bool) -> None:
+        self.stream, self.enabled, self.active = stream, enabled, False
+
+    def update(self, text: str) -> None:
+        if self.enabled:
+            self.stream.write("\r\x1b[K" + text[:120])
+            self.stream.flush()
+            self.active = True
+
+    def clear(self) -> None:
+        if self.active:
+            self.stream.write("\r\x1b[K")
+            self.stream.flush()
+            self.active = False
+
+
+class _ProgressAwareHandler(logging.StreamHandler):  # type: ignore[type-arg]
+    def __init__(self, progress: _Progress) -> None:
+        super().__init__(sys.stderr)
+        self.progress = progress
+
+    def emit(self, record: logging.LogRecord) -> None:
+        self.progress.clear()
+        super().emit(record)
+
+
+def _parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="charmfix",
+        description="Write copies of Kodak Charmera JPEGs with repaired EXIF metadata. "
+        "Image data is never changed and source files are never modified.",
+    )
+    p.add_argument("input", type=Path, help="folder (e.g. the mounted SD card) or a single JPEG")
+    p.add_argument(
+        "-o",
+        "--output",
+        type=Path,
+        default=DEFAULT_OUTPUT,
+        help=f"output folder (default: {DEFAULT_OUTPUT})",
+    )
+    p.add_argument(
+        "--recursive",
+        action=argparse.BooleanOptionalAction,
+        default=True,
+        help="descend into subfolders (default: yes)",
+    )
+    p.add_argument("-n", "--dry-run", action="store_true", help="analyse only; write no images")
+    p.add_argument("--force", action="store_true", help="overwrite existing output files")
+    p.add_argument("-v", "--verbose", action="store_true", help="log details for every file")
+    p.add_argument("--report", type=Path, help="write a JSON report to this path")
+    p.add_argument(
+        "--no-preserve-structure",
+        dest="preserve_structure",
+        action="store_false",
+        help="put all outputs directly in the output folder",
+    )
+    p.add_argument(
+        "--no-assume-charmera",
+        dest="assume_charmera",
+        action="store_false",
+        help="do not set Make/Model to Kodak/Charmera on files with only a GPEncoder comment",
+    )
+    p.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    return p
+
+
+def _same(a: Path, b: Path) -> bool:
+    """Same file or folder on disk, whatever the spelling (letter case, Unicode form).
+
+    A path that cannot be statted counts as different: nothing can be written there either.
+    """
+    if a == b:
+        return True
+    try:
+        return a.samefile(b)
+    except OSError:
+        return False
+
+
+def _within(path: Path, root: Path) -> bool:
+    """``path`` is ``root`` or lies under it, judged by identity on disk."""
+    return any(_same(p, root) for p in (path, *path.parents))
+
+
+def _refusal(
+    input_path: Path, is_folder: bool, output_root: Path, report_path: Path | None
+) -> str | None:
+    """Why these paths would put a source file at risk (CLI.md source safety), or None."""
+    if is_folder:
+        if _within(output_root, input_path) or _within(input_path, output_root):
+            return "input and output folders must not overlap"
+        if report_path and _within(report_path, input_path):
+            return "the report must not be written inside the input folder"
+    else:
+        if _same(output_root, input_path.parent):
+            return "the output folder must not be the input file's folder"
+        if report_path and _same(report_path, input_path):
+            return "the report must not replace the input file"
+    return None
+
+
+def _log_result(r: FileResult) -> None:
+    if r.status == "failed":
+        log.error("FAILED  %s: %s", r.rel_path, r.error)
+    elif r.status == "partial":
+        log.warning("partial %s: %s", r.rel_path, "; ".join(r.partial_reasons))
+    elif r.warnings:
+        log.warning("%-7s %s: %s", r.status, r.rel_path, "; ".join(r.warnings))
+    else:
+        log.debug("%-7s %s", r.status, r.rel_path)
+    if r.status not in ("skipped", "failed"):
+        log.debug(
+            "  SOF %s, old sizes %s; date %r -> %s (source: %s); identity %s; MakerNote %s",
+            r.sof_size,
+            r.old_sizes,
+            r.raw_date,
+            r.date_written,
+            r.timestamp_source,
+            r.identity,
+            r.makernote,
+        )
+        for change in r.changes:
+            log.debug("  change: %s", change)
+    elif r.reason:
+        log.debug("  reason: %s", r.reason)
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = _parser().parse_args(argv)
+    progress = _Progress(sys.stderr, enabled=sys.stderr.isatty() and not args.verbose)
+    handler = _ProgressAwareHandler(progress)
+    handler.setFormatter(logging.Formatter("%(message)s"))
+    log.handlers[:] = [handler]
+    log.setLevel(logging.DEBUG if args.verbose else logging.INFO)
+    log.propagate = False
+
+    input_path: Path = args.input.expanduser().resolve()
+    output_root: Path = args.output.expanduser().resolve()
+    if not input_path.exists():
+        log.error("input not found: %s", args.input)
+        return EXIT_FATAL
+    report_path = args.report.expanduser().resolve() if args.report else None
+    is_folder = input_path.is_dir()  # anything else is one file, as in discovery
+    refusal = _refusal(input_path, is_folder, output_root, report_path)
+    if refusal:
+        log.error(refusal)
+        return EXIT_FATAL
+
+    opts = RunOptions(
+        output_root=output_root,
+        recursive=args.recursive,
+        preserve_structure=args.preserve_structure,
+        force=args.force,
+        dry_run=args.dry_run,
+        assume_charmera=args.assume_charmera,
+    )
+    input_root = input_path if is_folder else input_path.parent
+    reason = unreadable_reason(input_root)
+    if reason is not None:
+        log.error("cannot read %s: %s", input_root, reason)
+        if sys.platform == "darwin" and reason == "Operation not permitted":
+            log.error(MACOS_PERMISSION_HINT)
+        return EXIT_FATAL
+
+    summary = Summary()
+    results: list[FileResult] = []
+    exit_code = EXIT_OK
+    try:
+        jobs: list[Job] = prepare(input_path, opts)  # walks the card: Ctrl-C may land here too
+        if not jobs:
+            log.warning("no .jpg/.jpeg files found in %s", input_path)
+        summary.discovered = len(jobs)
+        for i, job in enumerate(jobs, 1):
+            progress.update(f"[{i}/{len(jobs)}] {job.candidate.rel.as_posix()}")
+            r = process_file(job, opts)
+            results.append(r)
+            summary.add(r)
+            _log_result(r)
+    except DiskFullError as exc:
+        summary.stopped = str(exc)
+        log.error("stopping: %s", exc)
+        exit_code = EXIT_FATAL
+    except KeyboardInterrupt:
+        summary.stopped = "interrupted"
+        exit_code = EXIT_INTERRUPTED
+    finally:
+        progress.clear()
+
+    print(summary.render(args.dry_run))
+    if report_path:
+        try:
+            write_report(report_path, build_report(results, summary, opts.report_options()))
+        except OSError as exc:
+            log.error("cannot write the report: %s", exc.strerror or exc.__class__.__name__)
+            if exit_code != EXIT_INTERRUPTED:
+                exit_code = EXIT_FATAL
+    if exit_code == EXIT_OK and summary.failed:
+        exit_code = EXIT_FAILURES
+    return exit_code
+
+
+if __name__ == "__main__":
+    sys.exit(main())

charmfix-0.1.0/src/charmfix/dates.py

@@ -0,0 +1,54 @@
+"""EXIF date parsing and formatting. Dates are naive local wall-clock times."""
+
+from __future__ import annotations
+
+import re
+from datetime import datetime, timedelta
+
+EXIF_FORMAT = "%Y:%m:%d %H:%M:%S"
+
+# Accepts the standard "YYYY:MM:DD HH:MM:SS" and the broken variants seen in the
+# wild, e.g. the Charmera's six-part "YYYY:MM:DD:HH:MM:SS", or "T"/"-" separators.
+_DATE_RE = re.compile(r"^\s*(\d{4})[:\-](\d{2})[:\-](\d{2})[ :T\-](\d{2}):(\d{2}):(\d{2})\s*$")
+_NORMAL_RE = re.compile(r"^\d{4}:\d{2}:\d{2} \d{2}:\d{2}:\d{2}$")
+
+
+def _text(raw: bytes | str) -> str:
+    if isinstance(raw, bytes):
+        raw = raw.decode("ascii", errors="replace")
+    return raw.rstrip("\x00")
+
+
+def normalize(raw: bytes | str | None) -> datetime | None:
+    """Parse an EXIF-ish date string; None for blank, zero or impossible dates."""
+    if raw is None:
+        return None
+    m = _DATE_RE.match(_text(raw))
+    if not m:
+        return None
+    year, month, day, hour, minute, second = (int(g) for g in m.groups())
+    try:
+        return datetime(year, month, day, hour, minute, second)
+    except ValueError:
+        return None
+
+
+def is_normal_form(raw: bytes | str | None) -> bool:
+    """True when the value is already a valid, standard EXIF date string."""
+    if raw is None:
+        return False
+    text = _text(raw)
+    return bool(_NORMAL_RE.match(text)) and normalize(text) is not None
+
+
+def format_exif(dt: datetime) -> str:
+    return dt.strftime(EXIF_FORMAT)
+
+
+def sanity_warning(dt: datetime, now: datetime) -> str | None:
+    """A warning for dates that parse but look implausible; the date is still used."""
+    if dt.year < 2000:
+        return f"capture date {format_exif(dt)} is before 2000 (camera clock not set?)"
+    if dt > now + timedelta(days=1):
+        return f"capture date {format_exif(dt)} is in the future"
+    return None