refactor-cli 0.1.2__tar.gz → 0.2.0__tar.gz

{refactor_cli-0.1.2 → refactor_cli-0.2.0}/.gitignore

@@ -1,3 +1,5 @@
+notes.md
+testing-dir
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[codz]
@@ -138,6 +140,8 @@ celerybeat.pid
 .env
 .envrc
 .venv
+.venv-pypi
+
 env/
 venv/
 ENV/

refactor_cli-0.2.0/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: refactor-cli
+Version: 0.2.0
+Summary: CLI tool to organize files using AI
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer
+Requires-Dist: requests
+Requires-Dist: python-dotenv
+Dynamic: license-file
+
+# refactor.ai
+
+`refactor.ai` is a Python CLI for inspecting local directories before automating file organization. The package is published as [`refactor-cli`](https://pypi.org/project/refactor-cli/) and targets Python 3.8+.
+
+## Current scope
+
+The CLI entry point in [refactor/cli.py](refactor/cli.py) provides:
+
+- `version` — prints the installed package version.
+- `tree` — prints a recursive directory tree through [refactor/tree.py](refactor/tree.py).
+- `scan` — collects basic file and directory metadata through [refactor/scanner.py](refactor/scanner.py) and [refactor/metadata.py](refactor/metadata.py).
+- `setup` — configures a multimodal backend (`hosted` or `local`), persisted to `~/.refactor/config.json`.
+- `get-image-context` — obtains Imagga V3 tags/captions, asks Gemini to choose a
+  destination category, and writes JSON context.
+- `refactor-images` — automatically refreshes image context, then moves images
+  into Gemini-selected existing or new category folders (`--copy` is available
+  when the originals must be retained).
+- Path checks through [refactor/validation.py](refactor/validation.py), including existence, directory type, and read access.
+- Optional filename exclusions through [refactor/ignore.py](refactor/ignore.py).
+
+On first CLI run, users are prompted to run setup. They can rerun setup anytime with `refactor setup` or edit `~/.refactor/config.json` directly.
+
+## Setup workflow
+
+After installing `refactor-cli`, the first CLI run prompts:
+
+1. **Hosted model (bring your own API keys)**  
+   - Prompts for `IMAGGA_API_KEY`, `IMAGGA_API_SECRET`, and `GEMINI_API_KEY`  
+   - Saves credentials to `~/.refactor/.env` with restricted file permissions
+2. **Local multimodal recommendation (stub)**  
+   - Detects basic hardware (CPU, memory, NVIDIA GPU/VRAM if available)  
+   - Recommends an OSS multimodal model and records it in config  
+   - Uses a local shim stub today (full local runtime integration is a follow-up)
+
+For the hosted workflow, local images are uploaded to Imagga and classified with
+the V3 `/tags` endpoint using `model=light` and `include_caption=true`. The
+resulting tags/caption and the destination root's current folders are sent to
+Gemini. Gemini selects one safe category name per image, reusing a suitable
+folder where possible and naming a new category otherwise. The organizer creates
+that directory as needed. The shim layer provides one interface for image
+classification, regardless of hosted/local backend, so future modalities can
+reuse the same abstraction.
+
+Run `refactor refactor-images ./incoming --output-dir ./organized` to generate
+fresh context and move the images. Add `--dry-run` to inspect destinations or
+`--copy` to retain the originals.
+
+## Techniques used
+
+- **Recursive traversal with `pathlib`** — [refactor/scanner.py](refactor/scanner.py) uses [`Path.rglob()`](https://docs.python.org/3/library/pathlib.html#pathlib.Path.rglob) to discover nested paths. [refactor/tree.py](refactor/tree.py) recursively walks directory entries to render a text tree.
+
+- **Filesystem metadata from stat data** — [refactor/metadata.py](refactor/metadata.py) reads [`Path.stat()`](https://docs.python.org/3/library/pathlib.html#pathlib.Path.stat) and combines it with path properties such as `name`, `suffix`, and `is_dir()`.
+
+- **Glob-based ignore matching** — [refactor/ignore.py](refactor/ignore.py) loads patterns from an optional `.refactorignore` file and evaluates them with Python’s [`fnmatch`](https://docs.python.org/3/library/fnmatch.html). This keeps ignore rules lightweight while supporting familiar wildcard patterns.
+
+- **Fail-fast input validation** — [refactor/validation.py](refactor/validation.py) validates paths before traversal and checks read permissions with [`os.access()`](https://docs.python.org/3/library/os.html#os.access). CLI commands convert validation failures into clear non-zero exits.
+
+- **Declarative command registration** — [refactor/cli.py](refactor/cli.py) uses decorators to register commands on a Typer application. The package exports the `refactor` command through the console-script entry point in [pyproject.toml](pyproject.toml).
+
+- **Versioning from Git tags** — [pyproject.toml](pyproject.toml) delegates package version discovery to [`setuptools-scm`](https://setuptools-scm.readthedocs.io/). Release versions can come from repository tags instead of being duplicated in source files.
+
+## Technologies and libraries
+
+- [Typer](https://typer.tiangolo.com/) — CLI framework built around Python type hints. It provides command dispatch, help output, and exit handling.
+- [setuptools](https://setuptools.pypa.io/) — package build backend.
+- [setuptools-scm](https://setuptools-scm.readthedocs.io/) — derives the distribution version from source-control metadata.
+- [pathlib](https://docs.python.org/3/library/pathlib.html) — standard-library object model for portable path operations.
+- [importlib.metadata](https://docs.python.org/3/library/importlib.metadata.html) — reads the installed package version at runtime.
+
+The project currently has no web UI, image assets, or bundled fonts.
+
+## Project structure
+
+```text
+.
+├── LICENSE
+├── README.md
+├── pyproject.toml
+└── refactor/
+```
+
+- [refactor/](refactor/) contains the CLI and filesystem logic.
+- [pyproject.toml](pyproject.toml) defines packaging metadata, the `refactor` command, supported Python version, and build configuration.
+- [LICENSE](LICENSE) contains the Apache License 2.0 terms.
+
+## Next steps
+
+The package metadata describes the broader goal as AI-assisted file organization. The next development work can build on the current inspection layer:
+
+- Add an AI integration that proposes organization decisions from scanned metadata.
+- Add a review step so users can inspect proposed changes before any write operation.
+- Implement explicit rename and move operations with dry-run support.
+- Expand ignore handling beyond filename-only matching where needed.
+- Add automated tests for traversal, ignore patterns, validation, and planned write operations.
+- Provide structured scan output for scripts and other tooling.

refactor_cli-0.2.0/README.md

@@ -0,0 +1,95 @@
+# refactor.ai
+
+`refactor.ai` is a Python CLI for inspecting local directories before automating file organization. The package is published as [`refactor-cli`](https://pypi.org/project/refactor-cli/) and targets Python 3.8+.
+
+## Current scope
+
+The CLI entry point in [refactor/cli.py](refactor/cli.py) provides:
+
+- `version` — prints the installed package version.
+- `tree` — prints a recursive directory tree through [refactor/tree.py](refactor/tree.py).
+- `scan` — collects basic file and directory metadata through [refactor/scanner.py](refactor/scanner.py) and [refactor/metadata.py](refactor/metadata.py).
+- `setup` — configures a multimodal backend (`hosted` or `local`), persisted to `~/.refactor/config.json`.
+- `get-image-context` — obtains Imagga V3 tags/captions, asks Gemini to choose a
+  destination category, and writes JSON context.
+- `refactor-images` — automatically refreshes image context, then moves images
+  into Gemini-selected existing or new category folders (`--copy` is available
+  when the originals must be retained).
+- Path checks through [refactor/validation.py](refactor/validation.py), including existence, directory type, and read access.
+- Optional filename exclusions through [refactor/ignore.py](refactor/ignore.py).
+
+On first CLI run, users are prompted to run setup. They can rerun setup anytime with `refactor setup` or edit `~/.refactor/config.json` directly.
+
+## Setup workflow
+
+After installing `refactor-cli`, the first CLI run prompts:
+
+1. **Hosted model (bring your own API keys)**  
+   - Prompts for `IMAGGA_API_KEY`, `IMAGGA_API_SECRET`, and `GEMINI_API_KEY`  
+   - Saves credentials to `~/.refactor/.env` with restricted file permissions
+2. **Local multimodal recommendation (stub)**  
+   - Detects basic hardware (CPU, memory, NVIDIA GPU/VRAM if available)  
+   - Recommends an OSS multimodal model and records it in config  
+   - Uses a local shim stub today (full local runtime integration is a follow-up)
+
+For the hosted workflow, local images are uploaded to Imagga and classified with
+the V3 `/tags` endpoint using `model=light` and `include_caption=true`. The
+resulting tags/caption and the destination root's current folders are sent to
+Gemini. Gemini selects one safe category name per image, reusing a suitable
+folder where possible and naming a new category otherwise. The organizer creates
+that directory as needed. The shim layer provides one interface for image
+classification, regardless of hosted/local backend, so future modalities can
+reuse the same abstraction.
+
+Run `refactor refactor-images ./incoming --output-dir ./organized` to generate
+fresh context and move the images. Add `--dry-run` to inspect destinations or
+`--copy` to retain the originals.
+
+## Techniques used
+
+- **Recursive traversal with `pathlib`** — [refactor/scanner.py](refactor/scanner.py) uses [`Path.rglob()`](https://docs.python.org/3/library/pathlib.html#pathlib.Path.rglob) to discover nested paths. [refactor/tree.py](refactor/tree.py) recursively walks directory entries to render a text tree.
+
+- **Filesystem metadata from stat data** — [refactor/metadata.py](refactor/metadata.py) reads [`Path.stat()`](https://docs.python.org/3/library/pathlib.html#pathlib.Path.stat) and combines it with path properties such as `name`, `suffix`, and `is_dir()`.
+
+- **Glob-based ignore matching** — [refactor/ignore.py](refactor/ignore.py) loads patterns from an optional `.refactorignore` file and evaluates them with Python’s [`fnmatch`](https://docs.python.org/3/library/fnmatch.html). This keeps ignore rules lightweight while supporting familiar wildcard patterns.
+
+- **Fail-fast input validation** — [refactor/validation.py](refactor/validation.py) validates paths before traversal and checks read permissions with [`os.access()`](https://docs.python.org/3/library/os.html#os.access). CLI commands convert validation failures into clear non-zero exits.
+
+- **Declarative command registration** — [refactor/cli.py](refactor/cli.py) uses decorators to register commands on a Typer application. The package exports the `refactor` command through the console-script entry point in [pyproject.toml](pyproject.toml).
+
+- **Versioning from Git tags** — [pyproject.toml](pyproject.toml) delegates package version discovery to [`setuptools-scm`](https://setuptools-scm.readthedocs.io/). Release versions can come from repository tags instead of being duplicated in source files.
+
+## Technologies and libraries
+
+- [Typer](https://typer.tiangolo.com/) — CLI framework built around Python type hints. It provides command dispatch, help output, and exit handling.
+- [setuptools](https://setuptools.pypa.io/) — package build backend.
+- [setuptools-scm](https://setuptools-scm.readthedocs.io/) — derives the distribution version from source-control metadata.
+- [pathlib](https://docs.python.org/3/library/pathlib.html) — standard-library object model for portable path operations.
+- [importlib.metadata](https://docs.python.org/3/library/importlib.metadata.html) — reads the installed package version at runtime.
+
+The project currently has no web UI, image assets, or bundled fonts.
+
+## Project structure
+
+```text
+.
+├── LICENSE
+├── README.md
+├── pyproject.toml
+└── refactor/
+```
+
+- [refactor/](refactor/) contains the CLI and filesystem logic.
+- [pyproject.toml](pyproject.toml) defines packaging metadata, the `refactor` command, supported Python version, and build configuration.
+- [LICENSE](LICENSE) contains the Apache License 2.0 terms.
+
+## Next steps
+
+The package metadata describes the broader goal as AI-assisted file organization. The next development work can build on the current inspection layer:
+
+- Add an AI integration that proposes organization decisions from scanned metadata.
+- Add a review step so users can inspect proposed changes before any write operation.
+- Implement explicit rename and move operations with dry-run support.
+- Expand ignore handling beyond filename-only matching where needed.
+- Add automated tests for traversal, ignore patterns, validation, and planned write operations.
+- Provide structured scan output for scripts and other tooling.

{refactor_cli-0.1.2 → refactor_cli-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ dynamic = ["version"]
 description = "CLI tool to organize files using AI"
 readme = "README.md"
 requires-python = ">=3.8"
-dependencies = ["typer"]
+dependencies = ["typer", "requests", "python-dotenv"]
 
 [project.scripts]
 refactor = "refactor.cli:app"

refactor_cli-0.2.0/refactor/cli.py

@@ -0,0 +1,291 @@
+import typer
+from importlib.metadata import version as get_version
+
+from refactor.context_store import DEFAULT_CACHE_FILE, save_context
+from refactor.ignore import load_ignore_patterns
+from refactor.image_scanner import scan_images
+from refactor.metadata import get_metadata
+from refactor.organizer import (
+    execute_moves,
+    managed_category_dirs,
+    plan_moves,
+    save_managed_category_dirs,
+)
+from refactor.scanner import scan_directory
+from refactor.setup import command_setup, ensure_backend_configured, maybe_run_first_time_setup
+from refactor.shim import build_image_classifier, choose_category_folders
+from refactor.tree import print_tree
+from refactor.validation import validate_path
+
+app = typer.Typer(no_args_is_help=True)
+
+
+@app.callback()
+def bootstrap() -> None:
+    maybe_run_first_time_setup()
+
+
+@app.command()
+def version() -> None:
+    """Print version information"""
+    print(get_version("refactor-cli"))
+
+
+@app.command()
+def setup() -> None:
+    """Configure hosted or local multimodal backend."""
+    command_setup()
+
+
+@app.command()
+def tree(path: str = ".") -> None:
+    """Display folder structure of given path"""
+    try:
+        validate_path(path)
+        print_tree(path)
+    except ValueError as e:
+        typer.echo(f"Error: {e}")
+        raise typer.Exit(code=1)
+
+
+@app.command()
+def scan(path: str = ".") -> None:
+    """Scan directory and display metadata"""
+    try:
+        validate_path(path)
+        patterns = load_ignore_patterns()
+        items = scan_directory(path, patterns)
+
+        for item in items:
+            print(get_metadata(item))
+
+    except ValueError as e:
+        typer.echo(f"Error: {e}")
+        raise typer.Exit(code=1)
+
+
+@app.command(name="get-image-context")
+def get_image_context(
+    path: str = typer.Argument(".", help="Directory to scan for images"),
+    output: str = typer.Option(
+        ".refactor_image_context.json",
+        "--output",
+        "-o",
+        help="Path to write the JSON context cache",
+    ),
+    min_confidence: float = typer.Option(
+        40.0,
+        "--min-confidence",
+        help="Minimum tag confidence to include (hosted backend only)",
+    ),
+    verbose: bool = typer.Option(
+        False,
+        "--verbose",
+        "-v",
+        help="Print per-image tag results to stdout",
+    ),
+    category_root: str = typer.Option(
+        ".",
+        "--category-root",
+        help="Directory whose existing folders Gemini may reuse",
+    ),
+    write_context: bool = typer.Option(
+        True,
+        "--write-context/--no-write-context",
+        hidden=True,
+    ),
+) -> list:
+    """
+    Scan directory images using configured backend shim and save
+    tags/captions to JSON context cache.
+    """
+    from pathlib import Path
+
+    try:
+        validate_path(path)
+        if not Path(category_root).exists() or not Path(category_root).is_dir():
+            raise ValueError(f"Category root is not a directory: {category_root}")
+        config = ensure_backend_configured()
+    except (ValueError, EnvironmentError) as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(code=1)
+
+    patterns = load_ignore_patterns()
+    source_root = Path(path).resolve()
+    destination_root = Path(category_root).resolve()
+    excluded_dirs = (
+        managed_category_dirs(destination_root)
+        if source_root == destination_root else set()
+    )
+    images = scan_images(path, patterns, excluded_dirs)
+
+    if not images:
+        typer.echo("No image files found in the specified directory.")
+        raise typer.Exit(code=0)
+
+    typer.echo(f"Found {len(images)} image(s) in '{path}'")
+
+    try:
+        classifier = build_image_classifier(config, min_confidence=min_confidence)
+    except EnvironmentError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(code=1)
+
+    results = []
+    failed = 0
+
+    with typer.progressbar(images, label="Analysing images") as progress:
+        for img_path in progress:
+            try:
+                ctx = classifier.classify_image(img_path)
+                results.append(ctx)
+
+            except Exception as exc:
+                typer.echo(f"\n  [!] Skipping {img_path.name}: {exc}", err=True)
+                failed += 1
+
+    if results:
+        try:
+            results = choose_category_folders(config, results, Path(category_root))
+        except Exception as exc:
+            # Folder selection is an essential part of the hosted workflow; do
+            # not silently fall back to an Imagga top-tag directory.
+            typer.echo(f"Error: Gemini folder selection failed: {exc}", err=True)
+            raise typer.Exit(code=1)
+
+    if verbose:
+        for ctx in results:
+            typer.echo(f"\n  {Path(ctx.file_path).name}")
+            typer.echo(f"    Folder   : {ctx.primary_folder}")
+            typer.echo(f"    Tags     : {', '.join(ctx.tags[:5])}")
+            typer.echo(f"    Caption  : {ctx.caption}")
+
+    output_path = Path(output)
+    if write_context:
+        save_context(results, path, output_path)
+
+    typer.echo(f"\n{'─' * 52}")
+    typer.echo(f"  Processed : {len(results)} image(s)")
+    if failed:
+        typer.echo(f"  Failed    : {failed} image(s)")
+    if write_context:
+        typer.echo(f"  Cache     : {output_path.resolve()}")
+    typer.echo(f"{'─' * 52}")
+
+    if results:
+        typer.echo(f"\n{'Filename':<30} {'Folder':<20} {'Top tags'}")
+        typer.echo("─" * 80)
+        for ctx in results:
+            fname = Path(ctx.file_path).name
+            top_tags = ", ".join(ctx.tags[:3])
+            typer.echo(f"  {fname:<28} {ctx.primary_folder:<20} {top_tags}")
+
+    return results
+
+
+@app.command(name="refactor-images")
+def refactor_images(
+    path: str = typer.Argument(".", help="Directory containing images to organize"),
+    context: str = typer.Option(
+        ".refactor_image_context.json",
+        "--context",
+        "-c",
+        help="Path to context cache (defaults to the source directory)",
+    ),
+    output_dir: str = typer.Option(
+        ".",
+        "--output-dir",
+        "-d",
+        help="Root directory where tag-named folders will be created",
+    ),
+    dry_run: bool = typer.Option(
+        False,
+        "--dry-run",
+        help="Print the planned moves without executing them",
+    ),
+    move: bool = typer.Option(
+        True,
+        "--move/--copy",
+        help="Move files into categories. Use --copy to preserve source files.",
+    ),
+    min_confidence: float = typer.Option(
+        40.0,
+        "--min-confidence",
+        help="Minimum Imagga tag confidence to retain",
+    ),
+) -> None:
+    """
+    Generate fresh Imagga and Gemini context, then organise images into
+    Gemini-selected subdirectories. The context cache is refreshed on every run.
+
+    By default, images are MOVED. Use --copy to preserve source files.
+    """
+    from pathlib import Path
+    try:
+        validate_path(path)
+        out = Path(output_dir)
+        if not out.exists() or not out.is_dir():
+            raise ValueError(f"Output directory is not a directory: {output_dir}")
+    except ValueError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(code=1)
+
+    context_path = Path(context)
+    if context == DEFAULT_CACHE_FILE:
+        context_path = Path(path) / DEFAULT_CACHE_FILE
+
+    excluded = managed_category_dirs(out) if Path(path).resolve() == out.resolve() else set()
+    if excluded:
+        typer.echo(f"Skipping {len(excluded)} folder(s) created by an earlier Refactor run.")
+
+    typer.echo("Generating image context with Imagga and Gemini...")
+    contexts = get_image_context(
+        path=path,
+        output=str(context_path),
+        min_confidence=min_confidence,
+        verbose=False,
+        category_root=output_dir,
+        write_context=not dry_run,
+    )
+
+    if not contexts:
+        typer.echo("Context cache is empty. Nothing to organize.")
+        raise typer.Exit(code=0)
+
+    moves = plan_moves(contexts, out)
+
+    action_word = "Move" if move else "Copy"
+
+    if dry_run:
+        verb_plural = "moves" if move else "copies"
+        verb_past = "moved" if move else "copied"
+        typer.echo(f"\n[Dry Run] Planned {verb_plural} ({len(moves)} files):\n")
+        typer.echo(f"  {'Source':<40} {'Destination'}")
+        typer.echo("  " + "─" * 76)
+        for src, dst in moves:
+            typer.echo(f"  {src.name:<40} {dst}")
+        typer.echo(f"\n  No files were {verb_past}.")
+        raise typer.Exit(code=0)
+
+    folders = {dst.parent.name for _, dst in moves}
+    typer.echo(f"\nWill {action_word.lower()} {len(moves)} image(s) into {len(folders)} folder(s):")
+    for folder in sorted(folders):
+        count = sum(1 for _, dst in moves if dst.parent.name == folder)
+        typer.echo(f"  {out / folder}  ({count} file(s))")
+
+    summary = execute_moves(moves, copy=not move)
+    if not summary["failed"]:
+        save_managed_category_dirs(out, folders)
+
+    typer.echo(f"\n{'─' * 52}")
+    count = summary["moved"] if move else summary["copied"]
+    verb_past = "moved" if move else "copied"
+    typer.echo(f"  {verb_past.capitalize():<8}: {count} file(s)")
+    if summary["failed"]:
+        typer.echo(f"  Failed  : {summary['failed']} file(s)")
+    typer.echo(f"  Output  : {out.resolve()}")
+    typer.echo(f"{'─' * 52}")
+
+
+if __name__ == "__main__":
+    app()

refactor_cli-0.2.0/refactor/config.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+CONFIG_DIR = Path.home() / ".refactor"
+CONFIG_FILE = CONFIG_DIR / "config.json"
+ENV_FILE = CONFIG_DIR / ".env"
+
+
+def _ensure_config_dir() -> None:
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+
+
+def default_config() -> dict[str, Any]:
+    return {
+        "version": 1,
+        "backend": "unconfigured",
+        "setup_skipped": False,
+        "hosted": {
+            "provider": "imagga_gemini",
+            "imagga_api_key_env": "IMAGGA_API_KEY",
+            "imagga_api_secret_env": "IMAGGA_API_SECRET",
+            "gemini_api_key_env": "GEMINI_API_KEY",
+        },
+        "local": {
+            "runtime": "ollama",
+            "recommended_model": "",
+            "status": "stub",
+        },
+    }
+
+
+def config_exists() -> bool:
+    return CONFIG_FILE.exists()
+
+
+def load_config() -> dict[str, Any]:
+    if not CONFIG_FILE.exists():
+        return default_config()
+
+    with open(CONFIG_FILE, "r", encoding="utf-8") as f:
+        payload = json.load(f)
+
+    merged = default_config()
+    merged.update(payload)
+    return merged
+
+
+def save_config(config: dict[str, Any]) -> None:
+    _ensure_config_dir()
+
+    with open(CONFIG_FILE, "w", encoding="utf-8") as f:
+        json.dump(config, f, indent=2, ensure_ascii=False)
+
+
+def save_env_vars(values: dict[str, str]) -> None:
+    _ensure_config_dir()
+
+    existing: dict[str, str] = {}
+    if ENV_FILE.exists():
+        for line in ENV_FILE.read_text(encoding="utf-8").splitlines():
+            if "=" not in line or line.strip().startswith("#"):
+                continue
+            key, value = line.split("=", 1)
+            existing[key.strip()] = value.strip()
+
+    existing.update(values)
+
+    lines = [f"{k}={v}" for k, v in existing.items()]
+    ENV_FILE.write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+    try:
+        ENV_FILE.chmod(0o600)
+    except OSError:
+        pass

refactor_cli-0.2.0/refactor/context_store.py

@@ -0,0 +1,48 @@
+"""
+refactor/context_store.py
+~~~~~~~~~~~~~~~~~~~~~~~~~
+Manages reading and writing the JSON context cache produced by get-image-context.
+
+Default cache filename: .refactor_image_context.json
+"""
+
+from __future__ import annotations
+import json
+from dataclasses import asdict
+from datetime import datetime, timezone
+from pathlib import Path
+
+from refactor.imagga import ImageContext
+
+DEFAULT_CACHE_FILE = ".refactor_image_context.json"
+
+
+def save_context(
+    results: list[ImageContext],
+    source_dir: str,
+    output_path: Path,
+) -> None:
+    """Serialise a list of ImageContext objects to a JSON cache file."""
+    payload = {
+        "generated_at": datetime.now(timezone.utc).isoformat(),
+        "source_dir": str(Path(source_dir).resolve()),
+        "images": [asdict(ctx) for ctx in results],
+    }
+
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    with open(output_path, "w", encoding="utf-8") as f:
+        json.dump(payload, f, indent=2, ensure_ascii=False)
+
+
+def load_context(input_path: Path) -> list[ImageContext]:
+    """Load ImageContext objects from a JSON cache file."""
+    if not input_path.exists():
+        raise FileNotFoundError(
+            f"Context cache not found: {input_path}\n"
+            "Run 'refactor get-image-context <path>' first."
+        )
+
+    with open(input_path, "r", encoding="utf-8") as f:
+        payload = json.load(f)
+
+    return [ImageContext(**img) for img in payload.get("images", [])]