edapitool 0.6.3__py3-none-any.whl

APITool/export.py

@@ -0,0 +1,987 @@
+"""
+Export functionality for Elite Dangerous data.
+
+Supports exporting fleet carrier and other data to:
+- CSV files
+- JSON files
+- (Future) Google Sheets
+"""
+
+import csv
+import json
+import re
+from datetime import datetime
+from pathlib import Path
+from typing import Optional, Union, TextIO
+
+from .models import (
+    FleetCarrier,
+    CargoItem,
+    CommodityOrder,
+    MicroResourceOrder,
+    LockerItem,
+    ServiceCrew,
+    JumpRecord,
+)
+
+
+class CSVExporter:
+    """Export data to CSV format."""
+
+    def __init__(self, output_dir: Optional[Path] = None):
+        """
+        Initialize CSV exporter.
+
+        Args:
+            output_dir: Directory for output files (default: current directory)
+        """
+        self.output_dir = output_dir or Path.cwd()
+        self.output_dir.mkdir(parents=True, exist_ok=True)
+
+    def _generate_filename(self, prefix: str, callsign: str = "") -> Path:
+        """Generate a timestamped filename."""
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        if callsign:
+            return self.output_dir / f"{prefix}_{callsign}_{timestamp}.csv"
+        return self.output_dir / f"{prefix}_{timestamp}.csv"
+
+    def export_carrier_summary(
+        self,
+        carrier: FleetCarrier,
+        filepath: Optional[Path] = None,
+    ) -> Path:
+        """
+        Export carrier summary to CSV.
+
+        Args:
+            carrier: FleetCarrier data
+            filepath: Optional specific filepath
+
+        Returns:
+            Path to created file
+        """
+        filepath = filepath or self._generate_filename(
+            "carrier_summary", carrier.identity.callsign
+        )
+
+        with open(filepath, "w", newline="", encoding="utf-8") as f:
+            writer = csv.writer(f)
+
+            # Header info
+            writer.writerow(["Fleet Carrier Summary"])
+            writer.writerow(["Export Date", datetime.now().isoformat()])
+            writer.writerow([])
+
+            # Identity
+            writer.writerow(["Identity"])
+            writer.writerow(["Callsign", carrier.identity.callsign])
+            writer.writerow(["Name", carrier.identity.display_name])
+            writer.writerow([])
+
+            # Location
+            writer.writerow(["Location & Status"])
+            writer.writerow(["Current System", carrier.location.system])
+            writer.writerow(["State", carrier.location.state])
+            writer.writerow(["Docking Access", carrier.location.docking_access])
+            writer.writerow(["Tritium Fuel", carrier.fuel])
+            writer.writerow(["Theme", carrier.theme])
+            writer.writerow([])
+
+            # Finances
+            writer.writerow(["Finances"])
+            writer.writerow(["Bank Balance", carrier.finance.balance])
+            writer.writerow(["Reserved Balance", carrier.finance.reserved_balance])
+            writer.writerow(["Weekly Core Cost", carrier.finance.core_cost])
+            writer.writerow(["Weekly Services Cost", carrier.finance.services_cost])
+            writer.writerow(["Weekly Upkeep", carrier.finance.weekly_upkeep])
+            writer.writerow([])
+
+            # Capacity
+            writer.writerow(["Capacity"])
+            writer.writerow(["Ship Packs", carrier.capacity.ship_packs])
+            writer.writerow(["Module Packs", carrier.capacity.module_packs])
+            writer.writerow(["Cargo For Sale", carrier.capacity.cargo_for_sale])
+            writer.writerow(["Cargo Not For Sale", carrier.capacity.cargo_not_for_sale])
+            writer.writerow(["Cargo Reserved", carrier.capacity.cargo_reserved])
+            writer.writerow([])
+
+            # Services
+            writer.writerow(["Enabled Services"])
+            for service in carrier.enabled_services:
+                writer.writerow(["", service])
+
+        return filepath
+
+    def export_commodity_orders(
+        self,
+        carrier: FleetCarrier,
+        filepath: Optional[Path] = None,
+    ) -> Path:
+        """
+        Export commodity orders to CSV.
+
+        Args:
+            carrier: FleetCarrier data
+            filepath: Optional specific filepath
+
+        Returns:
+            Path to created file
+        """
+        filepath = filepath or self._generate_filename(
+            "commodities", carrier.identity.callsign
+        )
+
+        with open(filepath, "w", newline="", encoding="utf-8") as f:
+            writer = csv.writer(f)
+
+            writer.writerow([
+                "Commodity",
+                "Type",
+                "Stock/Demand",
+                "Outstanding",
+                "Price",
+                "Black Market",
+            ])
+
+            # Sales
+            for order in carrier.commodity_sales:
+                writer.writerow([
+                    order.name,
+                    "SELL",
+                    order.stock,
+                    "",
+                    order.price,
+                    "Yes" if order.blackmarket else "No",
+                ])
+
+            # Purchases
+            for order in carrier.commodity_purchases:
+                writer.writerow([
+                    order.name,
+                    "BUY",
+                    order.demand,
+                    order.outstanding,
+                    order.price,
+                    "",
+                ])
+
+        return filepath
+
+    def export_microresources(
+        self,
+        carrier: FleetCarrier,
+        filepath: Optional[Path] = None,
+    ) -> Path:
+        """
+        Export microresource orders to CSV.
+
+        Args:
+            carrier: FleetCarrier data
+            filepath: Optional specific filepath
+
+        Returns:
+            Path to created file
+        """
+        filepath = filepath or self._generate_filename(
+            "microresources", carrier.identity.callsign
+        )
+
+        with open(filepath, "w", newline="", encoding="utf-8") as f:
+            writer = csv.writer(f)
+
+            writer.writerow([
+                "Resource",
+                "Localized Name",
+                "Type",
+                "Stock/Demand",
+                "Outstanding",
+                "Price",
+            ])
+
+            # Sales
+            for order in carrier.micro_sales:
+                writer.writerow([
+                    order.name,
+                    order.localized_name,
+                    "SELL",
+                    order.stock,
+                    "",
+                    order.price,
+                ])
+
+            # Purchases
+            for order in carrier.micro_purchases:
+                writer.writerow([
+                    order.name,
+                    order.localized_name,
+                    "BUY",
+                    order.demand,
+                    order.outstanding,
+                    order.price,
+                ])
+
+        return filepath
+
+    def export_locker_inventory(
+        self,
+        carrier: FleetCarrier,
+        filepath: Optional[Path] = None,
+    ) -> Path:
+        """
+        Export carrier locker inventory to CSV.
+
+        Args:
+            carrier: FleetCarrier data
+            filepath: Optional specific filepath
+
+        Returns:
+            Path to created file
+        """
+        filepath = filepath or self._generate_filename(
+            "locker", carrier.identity.callsign
+        )
+
+        with open(filepath, "w", newline="", encoding="utf-8") as f:
+            writer = csv.writer(f)
+
+            writer.writerow([
+                "Item",
+                "Localized Name",
+                "Category",
+                "Quantity",
+            ])
+
+            for item in carrier.locker_items:
+                writer.writerow([
+                    item.name,
+                    item.localized_name,
+                    item.category.title(),
+                    item.quantity,
+                ])
+
+        return filepath
+
+    def export_cargo(
+        self,
+        carrier: FleetCarrier,
+        filepath: Optional[Path] = None,
+    ) -> Path:
+        """
+        Export fleet carrier cargo inventory to CSV.
+
+        This is the main commodity storage on the carrier - the items
+        like Meta-Alloys, Tea, Steel, etc. that the user needs to track.
+
+        Args:
+            carrier: FleetCarrier data
+            filepath: Optional specific filepath
+
+        Returns:
+            Path to created file
+        """
+        filepath = filepath or self._generate_filename(
+            "cargo", carrier.identity.callsign
+        )
+
+        with open(filepath, "w", newline="", encoding="utf-8") as f:
+            writer = csv.writer(f)
+
+            writer.writerow([
+                "Commodity",
+                "Display Name",
+                "Quantity",
+                "Value (CR)",
+                "Stolen",
+                "Mission",
+                "Origin System",
+            ])
+
+            # Sort by localized name for easier reading
+            sorted_cargo = sorted(carrier.cargo, key=lambda c: c.localized_name)
+
+            for item in sorted_cargo:
+                writer.writerow([
+                    item.commodity,
+                    item.localized_name,
+                    item.quantity,
+                    item.value,
+                    "Yes" if item.stolen else "No",
+                    "Yes" if item.mission else "No",
+                    item.origin_system or "",
+                ])
+
+            # Add summary row
+            if carrier.cargo:
+                writer.writerow([])
+                total_qty = sum(c.quantity for c in carrier.cargo)
+                total_value = sum(c.value for c in carrier.cargo)
+                writer.writerow(["TOTAL", "", total_qty, total_value, "", "", ""])
+
+        return filepath
+
+    def export_cargo_aggregated(
+        self,
+        carrier: FleetCarrier,
+        filepath: Optional[Path] = None,
+    ) -> Path:
+        """
+        Export fleet carrier cargo with quantities aggregated by commodity.
+
+        Same commodity from different sources is combined into a single row.
+        This is the simplified view for inventory tracking.
+
+        Args:
+            carrier: FleetCarrier data
+            filepath: Optional specific filepath
+
+        Returns:
+            Path to created file
+        """
+        filepath = filepath or self._generate_filename(
+            "cargo_summary", carrier.identity.callsign
+        )
+
+        # Aggregate by commodity name
+        aggregated: dict[str, dict] = {}
+        for item in carrier.cargo:
+            key = item.commodity
+            if key not in aggregated:
+                aggregated[key] = {
+                    "commodity": item.commodity,
+                    "localized_name": item.localized_name,
+                    "quantity": 0,
+                    "value": 0,
+                }
+            aggregated[key]["quantity"] += item.quantity
+            aggregated[key]["value"] += item.value
+
+        with open(filepath, "w", newline="", encoding="utf-8") as f:
+            writer = csv.writer(f)
+
+            writer.writerow([
+                "Commodity",
+                "Display Name",
+                "Quantity",
+                "Value (CR)",
+            ])
+
+            # Sort by localized name
+            sorted_items = sorted(aggregated.values(), key=lambda x: x["localized_name"])
+
+            for item in sorted_items:
+                writer.writerow([
+                    item["commodity"],
+                    item["localized_name"],
+                    item["quantity"],
+                    item["value"],
+                ])
+
+            # Add summary row
+            if aggregated:
+                writer.writerow([])
+                total_qty = sum(item["quantity"] for item in aggregated.values())
+                total_value = sum(item["value"] for item in aggregated.values())
+                writer.writerow(["TOTAL", "", total_qty, total_value])
+
+        return filepath
+
+    def export_cargo_gsheet(
+        self,
+        carrier: FleetCarrier,
+        filepath: Optional[Path] = None,
+        include_stolen: bool = False,
+        include_mission: bool = False,
+    ) -> Path:
+        """
+        Export fleet carrier cargo in Google Sheets-ready format.
+
+        This format is optimized for VLOOKUP references:
+        - Row 1: Empty
+        - Row 2: Headers (Column A empty for margin)
+        - Row 3: Totals with formulas
+        - Row 4+: Data sorted alphabetically
+
+        Filters out stolen and mission cargo by default.
+        Unit price is derived from the highest-quantity stack.
+
+        Args:
+            carrier: FleetCarrier data
+            filepath: Optional specific filepath
+            include_stolen: Include stolen cargo items
+            include_mission: Include mission-reserved cargo items
+
+        Returns:
+            Path to created file
+        """
+        filepath = filepath or self._generate_filename(
+            "cargo_gsheet", carrier.identity.callsign
+        )
+
+        # Step 1: Filter cargo based on flags
+        filtered = [
+            c for c in carrier.cargo
+            if (include_stolen or not c.stolen)
+            and (include_mission or not c.mission)
+            and c.quantity > 0  # Skip zero-quantity items
+        ]
+
+        # Step 2: Group by commodity, track max-qty stack for each
+        groups: dict[str, dict] = {}
+        for item in filtered:
+            key = item.commodity
+            if key not in groups:
+                groups[key] = {
+                    "items": [],
+                    "max_qty_item": item,
+                    "total_qty": 0,
+                    "display_name": item.localized_name,
+                }
+            groups[key]["items"].append(item)
+            groups[key]["total_qty"] += item.quantity
+            # Track the item with highest quantity for pricing
+            if item.quantity > groups[key]["max_qty_item"].quantity:
+                groups[key]["max_qty_item"] = item
+
+        # Step 3: Calculate unit prices and prepare data
+        data = []
+        for key, group in groups.items():
+            max_item = group["max_qty_item"]
+            # Unit price from the largest stack
+            unit_price = max_item.value // max_item.quantity if max_item.quantity > 0 else 0
+            data.append({
+                "display_name": group["display_name"],
+                "quantity": group["total_qty"],
+                "unit_price": unit_price,
+            })
+
+        # Step 4: Sort alphabetically by display name
+        data.sort(key=lambda x: x["display_name"])
+
+        # Step 5: Write CSV with Google Sheets layout
+        with open(filepath, "w", newline="", encoding="utf-8") as f:
+            writer = csv.writer(f)
+
+            # Row 1: Empty
+            writer.writerow([])
+
+            # Row 2: Headers (Column A empty for margin)
+            writer.writerow(["", "Display Name", "Quantity", "Unit Price", "Total Value"])
+
+            # Row 3: Totals with formulas (Column A empty)
+            # Formulas reference Row 4 onwards
+            writer.writerow(["", "TOTAL", "=SUM(C4:C)", "", "=SUM(E4:E)"])
+
+            # Row 4+: Data with formulas for Total Value
+            for i, item in enumerate(data):
+                row_num = 4 + i
+                writer.writerow([
+                    "",  # Column A empty
+                    item["display_name"],
+                    item["quantity"],
+                    item["unit_price"],
+                    f"=C{row_num}*D{row_num}",  # Total Value formula
+                ])
+
+        return filepath
+
+    def export_crew(
+        self,
+        carrier: FleetCarrier,
+        filepath: Optional[Path] = None,
+    ) -> Path:
+        """
+        Export crew information to CSV.
+
+        Args:
+            carrier: FleetCarrier data
+            filepath: Optional specific filepath
+
+        Returns:
+            Path to created file
+        """
+        filepath = filepath or self._generate_filename(
+            "crew", carrier.identity.callsign
+        )
+
+        with open(filepath, "w", newline="", encoding="utf-8") as f:
+            writer = csv.writer(f)
+
+            writer.writerow([
+                "Service",
+                "Crew Name",
+                "Gender",
+                "Faction",
+                "Weekly Salary",
+                "Enabled",
+            ])
+
+            for crew in carrier.crew:
+                writer.writerow([
+                    crew.service,
+                    crew.name,
+                    crew.gender,
+                    crew.faction,
+                    crew.salary,
+                    "Yes" if crew.enabled else "No",
+                ])
+
+        return filepath
+
+    def export_jump_history(
+        self,
+        carrier: FleetCarrier,
+        filepath: Optional[Path] = None,
+    ) -> Path:
+        """
+        Export jump history to CSV.
+
+        Args:
+            carrier: FleetCarrier data
+            filepath: Optional specific filepath
+
+        Returns:
+            Path to created file
+        """
+        filepath = filepath or self._generate_filename(
+            "jumps", carrier.identity.callsign
+        )
+
+        with open(filepath, "w", newline="", encoding="utf-8") as f:
+            writer = csv.writer(f)
+
+            writer.writerow([
+                "System",
+                "Arrival Time",
+                "Departure Time",
+                "Visit Duration (hrs)",
+                "Success",
+            ])
+
+            for jump in carrier.jump_history:
+                duration_hrs = jump.visit_duration / 3600
+                writer.writerow([
+                    jump.system,
+                    jump.arrival_time.isoformat() if jump.arrival_time else "",
+                    jump.departure_time.isoformat() if jump.departure_time else "",
+                    f"{duration_hrs:.1f}",
+                    "Yes" if jump.success else "No",
+                ])
+
+        return filepath
+
+    def export_all(
+        self,
+        carrier: FleetCarrier,
+        prefix: str = "",
+    ) -> dict[str, Path]:
+        """
+        Export all carrier data to separate CSV files.
+
+        Args:
+            carrier: FleetCarrier data
+            prefix: Optional prefix for filenames
+
+        Returns:
+            Dictionary mapping export type to file path
+        """
+        callsign = carrier.identity.callsign
+
+        return {
+            "summary": self.export_carrier_summary(carrier),
+            "cargo": self.export_cargo(carrier),
+            "cargo_summary": self.export_cargo_aggregated(carrier),
+            "commodities": self.export_commodity_orders(carrier),
+            "microresources": self.export_microresources(carrier),
+            "locker": self.export_locker_inventory(carrier),
+            "crew": self.export_crew(carrier),
+            "jumps": self.export_jump_history(carrier),
+        }
+
+
+class MarketExporter:
+    """
+    Export a station market as plain data.
+
+    Deliberately knows nothing about spreadsheets, requirements, or markers. A
+    market is a fact about a station -- what it sells, at what price, in what
+    quantity -- and it stays useful to anyone regardless of what they intend to
+    do with it. Whoever consumes this decides how to display it.
+
+    Mirrors CSVExporter/JSONExporter's shape so the market path and the carrier
+    path look the same to a caller.
+    """
+
+    def __init__(self, output_dir: Optional[Path] = None):
+        self.output_dir = output_dir or Path.cwd()
+        self.output_dir.mkdir(parents=True, exist_ok=True)
+
+    def _generate_filename(self, market, suffix: str) -> Path:
+        """Timestamped, and named after the station it describes."""
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        slug = re.sub(r"[^A-Za-z0-9]+", "-", market.station or "market").strip("-")
+        return self.output_dir / f"market_{slug}_{timestamp}.{suffix}"
+
+    def export_csv(self, market, filepath: Optional[Path] = None) -> Path:
+        """
+        One self-contained row per commodity.
+
+        Station, system and timestamp repeat on every row so files from
+        different stations concatenate into a usable dataset, and any single
+        row still says where and when it came from.
+        """
+        from .market import FLAT_FIELDS, flat_rows
+
+        filepath = filepath or self._generate_filename(market, "csv")
+        rows = flat_rows(market)
+        with open(filepath, "w", newline="", encoding="utf-8") as handle:
+            writer = csv.DictWriter(handle, fieldnames=FLAT_FIELDS)
+            writer.writeheader()
+            writer.writerows(rows)
+        return filepath
+
+    def export_json(self, market, filepath: Optional[Path] = None) -> Path:
+        """The same rows, with the market's identity hoisted out of them."""
+        from .market import flat_rows
+
+        filepath = filepath or self._generate_filename(market, "json")
+        payload = {
+            "station": market.station,
+            "system": market.system,
+            "market_id": market.market_id,
+            "timestamp": market.timestamp.isoformat() if market.timestamp else None,
+            "source": market.source,
+            "item_count": len(market.items),
+            "commodities": flat_rows(market),
+        }
+        with open(filepath, "w", encoding="utf-8") as handle:
+            json.dump(payload, handle, indent=2, ensure_ascii=False)
+        return filepath
+
+
+class ShipCargoExporter:
+    """
+    Export the current ship's hold as plain data.
+
+    The ship's hold and the fleet carrier's hold are different inventories, so
+    this is a peer of the carrier exporters rather than a variation on them.
+    Like MarketExporter, it knows nothing about spreadsheets: what is aboard is
+    a fact about the ship, useful to anyone regardless of what they do next.
+    """
+
+    def __init__(self, output_dir: Optional[Path] = None):
+        self.output_dir = output_dir or Path.cwd()
+        self.output_dir.mkdir(parents=True, exist_ok=True)
+
+    def _generate_filename(self, cargo, suffix: str) -> Path:
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        slug = re.sub(r"[^A-Za-z0-9]+", "-", cargo.vessel or "ship").strip("-").lower()
+        return self.output_dir / f"shipcargo_{slug}_{timestamp}.{suffix}"
+
+    def export_csv(self, cargo, filepath: Optional[Path] = None) -> Path:
+        """
+        One self-contained row per commodity aboard.
+
+        Vessel and timestamp repeat on every row, so snapshots taken over a
+        trading run concatenate into something you can actually read.
+        """
+        from .ship import FLAT_FIELDS, flat_rows
+
+        filepath = filepath or self._generate_filename(cargo, "csv")
+        rows = flat_rows(cargo)
+        with open(filepath, "w", newline="", encoding="utf-8") as handle:
+            writer = csv.DictWriter(handle, fieldnames=FLAT_FIELDS)
+            writer.writeheader()
+            writer.writerows(rows)
+        return filepath
+
+    def export_json(self, cargo, filepath: Optional[Path] = None) -> Path:
+        """The same rows, with the hold's identity hoisted out of them."""
+        from .ship import flat_rows
+
+        filepath = filepath or self._generate_filename(cargo, "json")
+        with open(filepath, "w", encoding="utf-8") as handle:
+            json.dump(ship_payload(cargo), handle, indent=2, ensure_ascii=False)
+        return filepath
+
+
+def ship_payload(cargo) -> dict:
+    """
+    The hold as one JSON-ready dict.
+
+    Shared by the file exporter and the CLI's ``--json``, so the structure a
+    script reads off stdout is byte-for-byte the structure it reads out of a
+    saved file. Two code paths producing "almost the same" JSON is a trap for
+    whoever writes the consumer.
+    """
+    from .ship import flat_rows
+
+    return {
+        "vessel": cargo.vessel,
+        "is_ship": cargo.is_ship,
+        "timestamp": cargo.timestamp.isoformat() if cargo.timestamp else None,
+        "reported_count": cargo.count,
+        "itemised_total": cargo.total,
+        "item_count": len(cargo.items),
+        "commodities": flat_rows(cargo),
+    }
+
+
+class JSONExporter:
+    """Export data to JSON format."""
+
+    def __init__(self, output_dir: Optional[Path] = None):
+        """
+        Initialize JSON exporter.
+
+        Args:
+            output_dir: Directory for output files (default: current directory)
+        """
+        self.output_dir = output_dir or Path.cwd()
+        self.output_dir.mkdir(parents=True, exist_ok=True)
+
+    def export_carrier(
+        self,
+        carrier: FleetCarrier,
+        filepath: Optional[Path] = None,
+        include_raw: bool = False,
+    ) -> Path:
+        """
+        Export carrier data to JSON.
+
+        Args:
+            carrier: FleetCarrier data
+            filepath: Optional specific filepath
+            include_raw: Include raw CAPI response
+
+        Returns:
+            Path to created file
+        """
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        filepath = filepath or (
+            self.output_dir
+            / f"carrier_{carrier.identity.callsign}_{timestamp}.json"
+        )
+
+        data = {
+            "export_date": datetime.now().isoformat(),
+            "identity": {
+                "callsign": carrier.identity.callsign,
+                "name": carrier.identity.display_name,
+            },
+            "location": {
+                "system": carrier.location.system,
+                "state": carrier.location.state,
+                "docking_access": carrier.location.docking_access,
+            },
+            "finance": {
+                "balance": carrier.finance.balance,
+                "weekly_upkeep": carrier.finance.weekly_upkeep,
+            },
+            "fuel": carrier.fuel,
+            "commodity_orders": [
+                {
+                    "name": o.name,
+                    "type": o.order_type,
+                    "quantity": o.stock if o.order_type == "sell" else o.demand,
+                    "price": o.price,
+                }
+                for o in carrier.all_commodities
+            ],
+            "microresource_orders": [
+                {
+                    "name": o.localized_name,
+                    "type": o.order_type,
+                    "quantity": o.stock if o.order_type == "sell" else o.demand,
+                    "price": o.price,
+                }
+                for o in carrier.all_microresources
+            ],
+            "locker": [
+                {
+                    "name": i.localized_name,
+                    "category": i.category,
+                    "quantity": i.quantity,
+                }
+                for i in carrier.locker_items
+            ],
+        }
+
+        if include_raw:
+            data["raw_capi_response"] = carrier.raw_data
+
+        with open(filepath, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2, ensure_ascii=False)
+
+        return filepath
+
+
+class ConstructionExporter:
+    """
+    Export a colony construction site's requirements as plain data.
+
+    A peer of MarketExporter and ShipCargoExporter, and like them it knows
+    nothing about spreadsheets: what a site still needs is a fact about the
+    site, useful to anyone regardless of what they do with it next.
+    """
+
+    def __init__(self, output_dir: Optional[Path] = None):
+        self.output_dir = output_dir or Path.cwd()
+        self.output_dir.mkdir(parents=True, exist_ok=True)
+
+    def _generate_filename(self, site, suffix: str) -> Path:
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        return self.output_dir / f"construction_{site.market_id or 'site'}_{timestamp}.{suffix}"
+
+    def export_csv(self, site, filepath: Optional[Path] = None) -> Path:
+        """
+        One self-contained row per commodity the site wants.
+
+        The site's identity and progress repeat on every row, so snapshots
+        taken across a build concatenate into something readable -- the same
+        choice ShipCargoExporter makes, for the same reason.
+        """
+        filepath = filepath or self._generate_filename(site, "csv")
+        fields = [
+            "market_id", "timestamp", "progress", "complete",
+            "commodity", "symbol", "required", "provided", "remaining", "payment",
+        ]
+        stamp = site.timestamp.isoformat() if site.timestamp else ""
+        with open(filepath, "w", newline="", encoding="utf-8") as handle:
+            writer = csv.DictWriter(handle, fieldnames=fields)
+            writer.writeheader()
+            for resource in site.resources:
+                writer.writerow({
+                    "market_id": site.market_id,
+                    "timestamp": stamp,
+                    "progress": round(site.progress, 6),
+                    "complete": site.complete,
+                    "commodity": resource.name,
+                    "symbol": resource.symbol,
+                    "required": resource.required,
+                    "provided": resource.provided,
+                    "remaining": resource.remaining,
+                    "payment": resource.payment,
+                })
+        return filepath
+
+    def export_json(self, site, filepath: Optional[Path] = None) -> Path:
+        """The same data, with the site's identity hoisted out of the rows."""
+        filepath = filepath or self._generate_filename(site, "json")
+        with open(filepath, "w", encoding="utf-8") as handle:
+            json.dump(construction_payload(site), handle, indent=2, ensure_ascii=False)
+        return filepath
+
+
+def construction_payload(site) -> dict:
+    """
+    One construction site as a JSON-ready dict.
+
+    Shared by the file exporter and the CLI's ``--json`` for the same reason
+    ship_payload is: a script reading stdout and a script reading a saved file
+    must see the identical structure. Two near-identical builders is precisely
+    the defect that let a live regression through earlier in this project --
+    the CLI and the daemon each had their own copy of one grid function.
+    """
+    return {
+        "market_id": site.market_id,
+        "timestamp": site.timestamp.isoformat() if site.timestamp else None,
+        "progress": site.progress,
+        "complete": site.complete,
+        "failed": site.failed,
+        "total_required": site.total_required,
+        "total_provided": site.total_provided,
+        "total_remaining": site.total_remaining,
+        "resources": [
+            {
+                "symbol": r.symbol,
+                "name": r.name,
+                "required": r.required,
+                "provided": r.provided,
+                "remaining": r.remaining,
+                "payment": r.payment,
+            }
+            for r in site.resources
+        ],
+    }
+
+
+# The two header rows the block carries, and where the commodity table
+# begins. Named rather than counted at the call site so a sheet formula's
+# range and the writer's own idea of where the table starts cannot drift.
+CONSTRUCTION_REGION_META = [
+    "Site", "System", "MarketID", "Updated (UTC)", "State",
+    "Progress", "Required", "Provided", "Remaining",
+]
+CONSTRUCTION_REGION_HEADERS = [
+    "Symbol", "Commodity", "Required", "Provided", "Remaining", "Payment",
+]
+# Rows 1-2 are the metadata header and its values, row 3 is blank, row 4 is
+# the table's own header. The table therefore starts at row 5 -- the same row
+# the settlement tabs in this workbook start their commodities on, so a
+# commodity in column B lands on the same line as its counterpart in the
+# block and the two can be checked against each other by eye.
+CONSTRUCTION_REGION_TABLE_ROW = 5
+
+
+def construction_region_rows(site, location=None) -> list[list]:
+    """
+    One construction site as a grid, for publishing into a region of a tab.
+
+    A metadata header and its values, a blank line, then the commodity table
+    with its own headers. A spreadsheet reads the table with the same VLOOKUP
+    idiom it already uses for MarketData and ShipCargo. Nothing here decides
+    what the numbers mean: the tool states what the game said, and the sheet's
+    own formulas turn that into "buy this many".
+
+    Why the metadata is labelled
+    ---------------------------
+    The first version emitted those nine values with no header at all, and the
+    first question anyone asked of it was "what are the numbers after
+    'active'?". A hidden region is still read by a person -- when they set it
+    up, and every time something looks wrong -- and ``8517`` alone in a cell
+    tells them nothing.
+
+    Why the table starts at row 5
+    -----------------------------
+    Because the settlement tabs this is published beside start their own
+    commodities on row 5. A commodity in column B therefore lands on the same
+    line as its counterpart in the block, and the two can be checked against
+    each other by eye without counting rows. A vertical label/value list was
+    considered and rejected for exactly this: it reads well on its own and
+    pushes the table down past any such alignment.
+
+    Pure, and separate from any writer, for the same reason the other grid
+    builders are: a grid you cannot construct without a network connection is
+    a grid nobody tests.
+
+    ``location`` is optional because a site is identified by its MarketID and
+    is perfectly reportable without ever having learned its name -- which is
+    the normal case for a site seen only in passing.
+    """
+    name = system = ""
+    if location is not None:
+        name = location.short_station or ""
+        system = location.system or ""
+
+    stamp = site.timestamp.isoformat() if site.timestamp else ""
+    state = "complete" if site.complete else ("failed" if site.failed else "active")
+
+    # The block is as wide as its widest row. Every row is padded to match, so
+    # the grid is rectangular -- a ragged one is a separate write per row.
+    width = len(CONSTRUCTION_REGION_META)
+
+    def pad(cells: list) -> list:
+        return list(cells) + [""] * (width - len(cells))
+
+    rows: list[list] = [
+        pad(CONSTRUCTION_REGION_META),
+        pad([name, system, site.market_id, stamp, state, site.progress,
+             site.total_required, site.total_provided, site.total_remaining]),
+        pad([]),
+        pad(CONSTRUCTION_REGION_HEADERS),
+    ]
+    for r in site.resources:
+        rows.append(pad([
+            r.symbol, r.name, r.required, r.provided, r.remaining, r.payment,
+        ]))
+    return rows