openremap 0.1.0__py3-none-any.whl

openremap/__init__.py

@@ -0,0 +1,7 @@
+"""
+openremap — ECU binary analysis and patching toolkit.
+
+Diff, validate, and apply tuning recipes to automotive ECU binaries.
+"""
+
+__version__ = "0.1.0"

openremap/cli/commands/cook.py

@@ -0,0 +1,224 @@
+"""
+openremap cook <original> <modified> --output recipe.json
+
+Cook a recipe by diffing an original and a modified ECU binary.
+
+Examples:
+    openremap cook stock.bin stage1.bin --output recipe.json
+    openremap cook stock.bin stage1.bin --output recipe.json --pretty
+    openremap cook stock.bin stage1.bin --context-size 64 --output recipe.json
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from openremap.tuning.services.recipe_builder import ECUDiffAnalyzer
+
+app = typer.Typer(
+    help="Cook a recipe by diffing an original and a modified ECU binary.",
+    no_args_is_help=True,
+)
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+_ALLOWED = (".bin", ".ori")
+
+
+def _check_bin(path: Path, label: str) -> None:
+    """Validate that a path points to an allowed, non-empty binary file."""
+    if path.suffix.lower() not in _ALLOWED:
+        typer.echo(
+            typer.style(
+                f"Error: {label} file '{path.name}' must be a .bin or .ori file.",
+                fg=typer.colors.RED,
+                bold=True,
+            ),
+            err=True,
+        )
+        raise typer.Exit(code=1)
+
+
+def _read_bin(path: Path, label: str) -> bytes:
+    """Read binary file contents with user-friendly error handling."""
+    _check_bin(path, label)
+    try:
+        data = path.read_bytes()
+    except OSError as exc:
+        typer.echo(
+            typer.style(
+                f"Error reading {label} file: {exc}", fg=typer.colors.RED, bold=True
+            ),
+            err=True,
+        )
+        raise typer.Exit(code=1)
+
+    if not data:
+        typer.echo(
+            typer.style(
+                f"Error: {label} file '{path.name}' is empty.",
+                fg=typer.colors.RED,
+                bold=True,
+            ),
+            err=True,
+        )
+        raise typer.Exit(code=1)
+
+    return data
+
+
+def _print_summary(recipe: dict, output: Optional[Path]) -> None:
+    """Print a compact summary of the produced recipe to stdout."""
+    ecu = recipe.get("ecu", {})
+    stats = recipe.get("statistics", {})
+    meta = recipe.get("metadata", {})
+
+    family = ecu.get("ecu_family") or "Unknown"
+    manufacturer = ecu.get("manufacturer") or "Unknown"
+    match_key = ecu.get("match_key") or "n/a"
+    total_changes = stats.get("total_changes", 0)
+    total_bytes = stats.get("total_bytes_changed", 0)
+    fmt_version = meta.get("format_version", "?")
+
+    typer.echo("")
+    typer.echo(
+        typer.style("  ✅ Recipe built successfully", fg=typer.colors.GREEN, bold=True)
+    )
+    typer.echo("")
+
+    col = 22
+    rows = [
+        ("ECU", f"{manufacturer} · {family}"),
+        ("Match Key", match_key),
+        ("Format Version", fmt_version),
+        ("Instructions", f"{total_changes:,}"),
+        ("Bytes Changed", f"{total_bytes:,}"),
+        ("Original", meta.get("original_file", "?")),
+        ("Modified", meta.get("modified_file", "?")),
+    ]
+    for label, value in rows:
+        typer.echo(f"  {label:<{col}} {value}")
+
+    typer.echo("")
+    if output:
+        typer.echo(
+            f"  Recipe saved to {typer.style(str(output), fg=typer.colors.CYAN, bold=True)}"
+        )
+    typer.echo("")
+
+
+# ---------------------------------------------------------------------------
+# Command
+# ---------------------------------------------------------------------------
+
+
+@app.callback(invoke_without_command=True)
+def cook(
+    original: Path = typer.Argument(
+        ...,
+        help="The unmodified (stock) ECU binary (.bin or .ori).",
+        exists=True,
+        file_okay=True,
+        dir_okay=False,
+        readable=True,
+        resolve_path=True,
+    ),
+    modified: Path = typer.Argument(
+        ...,
+        help="The tuned ECU binary (.bin or .ori).",
+        exists=True,
+        file_okay=True,
+        dir_okay=False,
+        readable=True,
+        resolve_path=True,
+    ),
+    output: Optional[Path] = typer.Option(
+        None,
+        "--output",
+        "-o",
+        help=(
+            "File path to write the recipe JSON to. "
+            "If omitted, the recipe is printed to stdout."
+        ),
+        writable=True,
+        resolve_path=True,
+    ),
+    context_size: int = typer.Option(
+        32,
+        "--context-size",
+        "-c",
+        help="Number of bytes of context to capture before each changed block (default: 32).",
+        min=8,
+        max=128,
+    ),
+    pretty: bool = typer.Option(
+        True,
+        "--pretty/--compact",
+        help="Pretty-print JSON output with indentation (default: pretty).",
+    ),
+) -> None:
+    """
+    Cook a recipe by diffing an original and a modified ECU binary.
+
+    The recipe captures every changed byte block along with its offset,
+    original bytes (ob), modified bytes (mb), and a context anchor (ctx)
+    used during patching. The ECU identity block is derived automatically
+    from the original binary.
+
+    Save the output recipe — it is the input for all validate and patch commands.
+    """
+    original_data = _read_bin(original, "Original")
+    modified_data = _read_bin(modified, "Modified")
+
+    typer.echo(
+        f"\n  Cooking recipe from "
+        f"{typer.style(original.name, fg=typer.colors.CYAN)} vs "
+        f"{typer.style(modified.name, fg=typer.colors.CYAN)} …"
+    )
+
+    try:
+        analyzer = ECUDiffAnalyzer(
+            original_data=original_data,
+            modified_data=modified_data,
+            original_filename=original.name,
+            modified_filename=modified.name,
+            context_size=context_size,
+        )
+        recipe = analyzer.build_recipe()
+    except Exception as exc:
+        typer.echo(
+            typer.style(
+                f"\n  Error: cook failed — {exc}", fg=typer.colors.RED, bold=True
+            ),
+            err=True,
+        )
+        raise typer.Exit(code=1)
+
+    indent = 2 if pretty else None
+    json_content = json.dumps(recipe, indent=indent, ensure_ascii=False)
+
+    if output:
+        try:
+            output.parent.mkdir(parents=True, exist_ok=True)
+            output.write_text(json_content, encoding="utf-8")
+        except OSError as exc:
+            typer.echo(
+                typer.style(
+                    f"\n  Error: could not write recipe to '{output}': {exc}",
+                    fg=typer.colors.RED,
+                    bold=True,
+                ),
+                err=True,
+            )
+            raise typer.Exit(code=1)
+    else:
+        typer.echo(json_content)
+
+    _print_summary(recipe, output)

openremap/cli/commands/identify.py

@@ -0,0 +1,180 @@
+"""
+openremap identify <file>
+
+Identify a single ECU binary and print its metadata.
+
+Examples:
+    openremap identify ecu.bin
+    openremap identify ecu.bin --json
+    openremap identify ecu.bin --json --output result.json
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from openremap.tuning.services.identifier import identify_ecu
+
+app = typer.Typer(
+    help="Identify an ECU binary — manufacturer, family, software version, and more.",
+    no_args_is_help=True,
+)
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+_LABELS: list[tuple[str, str]] = [
+    ("manufacturer", "Manufacturer"),
+    ("ecu_family", "ECU Family"),
+    ("ecu_variant", "ECU Variant"),
+    ("software_version", "Software Version"),
+    ("hardware_number", "Hardware Number"),
+    ("calibration_id", "Calibration ID"),
+    ("match_key", "Match Key"),
+    ("file_size", "File Size"),
+    ("sha256", "SHA-256"),
+]
+
+
+def _format_table(result: dict) -> str:
+    """Render the identity dict as a two-column aligned table."""
+    rows: list[tuple[str, str]] = []
+    for key, label in _LABELS:
+        value = result.get(key)
+        if key == "file_size" and value is not None:
+            display = f"{value:,} bytes"
+        elif value is None:
+            display = typer.style("unknown", fg=typer.colors.YELLOW)
+        else:
+            display = str(value)
+        rows.append((label, display))
+
+    col_width = max(len(label) for label, _ in rows)
+    lines = []
+    for label, value in rows:
+        lines.append(f"  {label:<{col_width}}  {value}")
+    return "\n".join(lines)
+
+
+def _write_output(content: str, output: Optional[Path]) -> None:
+    """Write content to a file or stdout."""
+    if output:
+        output.write_text(content, encoding="utf-8")
+        typer.echo(f"Saved to {output}")
+    else:
+        typer.echo(content)
+
+
+# ---------------------------------------------------------------------------
+# Command
+# ---------------------------------------------------------------------------
+
+
+@app.callback(invoke_without_command=True)
+def identify(
+    file: Path = typer.Argument(
+        ...,
+        help="ECU binary file to identify (.bin or .ori).",
+        exists=True,
+        file_okay=True,
+        dir_okay=False,
+        readable=True,
+        resolve_path=True,
+    ),
+    as_json: bool = typer.Option(
+        False,
+        "--json",
+        help="Output result as JSON instead of a human-readable table.",
+    ),
+    output: Optional[Path] = typer.Option(
+        None,
+        "--output",
+        "-o",
+        help="Save the result to a file instead of printing to stdout.",
+        writable=True,
+        resolve_path=True,
+    ),
+) -> None:
+    """
+    Identify a single ECU binary.
+
+    Prints manufacturer, ECU family, software version, hardware number,
+    calibration ID, match key, file size, and SHA-256 hash.
+    """
+    suffix = file.suffix.lower()
+    if suffix not in (".bin", ".ori"):
+        typer.echo(
+            typer.style(
+                f"Error: '{file.name}' is not a .bin or .ori file.",
+                fg=typer.colors.RED,
+                bold=True,
+            ),
+            err=True,
+        )
+        raise typer.Exit(code=1)
+
+    try:
+        data = file.read_bytes()
+    except OSError as exc:
+        typer.echo(
+            typer.style(f"Error reading file: {exc}", fg=typer.colors.RED, bold=True),
+            err=True,
+        )
+        raise typer.Exit(code=1)
+
+    if not data:
+        typer.echo(
+            typer.style(
+                f"Error: '{file.name}' is empty.", fg=typer.colors.RED, bold=True
+            ),
+            err=True,
+        )
+        raise typer.Exit(code=1)
+
+    try:
+        result = identify_ecu(data=data, filename=file.name)
+    except Exception as exc:
+        typer.echo(
+            typer.style(
+                f"Identification failed: {exc}", fg=typer.colors.RED, bold=True
+            ),
+            err=True,
+        )
+        raise typer.Exit(code=1)
+
+    if as_json:
+        content = json.dumps(result, indent=2)
+        _write_output(content, output)
+        return
+
+    # --- Table output ---
+    header = typer.style(f"\n  {file.name}", fg=typer.colors.CYAN, bold=True)
+
+    identified = result.get("ecu_family") is not None
+    status_colour = typer.colors.GREEN if identified else typer.colors.YELLOW
+    status_label = (
+        f"{result['manufacturer']} · {result['ecu_family']}"
+        if identified
+        else "Unknown ECU — no extractor matched this binary"
+    )
+    status_line = "  " + typer.style(status_label, fg=status_colour, bold=True)
+
+    table = _format_table(result)
+
+    full_output = f"{header}\n{status_line}\n\n{table}\n"
+
+    if output:
+        # Strip ANSI codes when writing to a file
+        import re
+
+        plain = re.sub(r"\x1b\[[0-9;]*m", "", full_output)
+        output.write_text(plain, encoding="utf-8")
+        typer.echo(f"Saved to {output}")
+    else:
+        typer.echo(full_output)