flight-alloc 0.0.1__py3-none-any.whl

src/web/core/static_files.py

@@ -0,0 +1,85 @@
+"""Serve the ``static/`` tree.
+
+The front end is a directory of ES modules and CSS partials rather than
+two flat files, so this resolves an arbitrary relative path — but only
+inside STATIC_DIR, and only for an allow-listed extension. A path that
+resolves outside the tree (``../``, an absolute path, a symlink out) is
+a 404, not a read.
+
+Every response carries ``Cache-Control: no-store`` (set by the request
+loop), and index.html gets the tree's newest mtime stamped onto its
+entry-point URLs, so the browser always pulls current code after an
+edit even if a proxy ignores the header.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from .responses import Response, not_found
+
+STATIC_DIR = Path(__file__).resolve().parents[1] / "static"
+
+INDEX = "index.html"
+
+#: Extension -> Content-Type. An extension absent from this map is not
+#: servable, which is the allow-list.
+CONTENT_TYPES = {
+    ".html": "text/html; charset=utf-8",
+    ".js":   "application/javascript; charset=utf-8",
+    ".mjs":  "application/javascript; charset=utf-8",
+    ".css":  "text/css; charset=utf-8",
+    ".json": "application/json; charset=utf-8",
+    ".svg":  "image/svg+xml",
+    ".png":  "image/png",
+    ".ico":  "image/x-icon",
+    ".woff": "font/woff",
+    ".woff2": "font/woff2",
+}
+
+#: URLs in index.html that get a ?v= cache-buster stamped on.
+_VERSIONED = re.compile(r'((?:href|src)=")(/static/[^"?]+\.(?:css|js))(")')
+
+
+def _tree_version() -> int:
+    """Newest mtime across the served tree. One number for the whole
+    front end: a change to any module busts the entry points, which is
+    what the browser actually re-requests."""
+    newest = 0
+    for path in STATIC_DIR.rglob("*"):
+        if path.suffix in CONTENT_TYPES and path.is_file():
+            newest = max(newest, int(path.stat().st_mtime))
+    return newest
+
+
+def _resolve(rel: str) -> Path | None:
+    """Map a URL path to a file inside STATIC_DIR, or None if it escapes
+    the tree, has a non-servable extension, or doesn't exist."""
+    rel = rel.lstrip("/")
+    if not rel:
+        rel = INDEX
+    candidate = (STATIC_DIR / rel).resolve()
+    try:
+        candidate.relative_to(STATIC_DIR.resolve())
+    except ValueError:
+        return None          # traversal attempt — outside the tree
+    if candidate.suffix not in CONTENT_TYPES or not candidate.is_file():
+        return None
+    return candidate
+
+
+def serve(rel_path: str) -> Response:
+    """Read one file out of ``static/`` and wrap it in a Response."""
+    path = _resolve(rel_path)
+    if path is None:
+        return not_found()
+    body = path.read_bytes()
+    if path.name == INDEX:
+        version = _tree_version()
+        text = _VERSIONED.sub(rf"\g<1>\g<2>?v={version}\g<3>", body.decode("utf-8"))
+        body = text.encode("utf-8")
+    return Response(status=200, body=body, content_type=CONTENT_TYPES[path.suffix])
+
+
+__all__ = ["CONTENT_TYPES", "INDEX", "STATIC_DIR", "serve"]

src/web/overrides/__init__.py

@@ -0,0 +1,66 @@
+"""Override mutations exposed by the web UI's drawer.
+
+Three concerns, three modules:
+
+    rows          the drawer's override table, the recommender's
+                  one-click fixes, and the staged add/remove forms
+    airports      list / add / remove international airport codes
+    break_time    the floating mid-shift break length
+    filters       write-through of the extraction-filter list
+    config_yaml   the shared config.yml handle + write lock
+
+``airports``, ``break_time`` and ``filters`` edit ``configs/config.yml`` so the
+engine picks the change up on the next run with no manual edit step.
+The edits are targeted line splices rather than a YAML round-trip, so
+the file's commentary survives.
+
+Import from here — the sub-module split is an implementation detail.
+"""
+
+from __future__ import annotations
+
+from .airports import (
+    add_intl_airport_code,
+    list_intl_airports,
+    preview_intl_airport_yaml_diff,
+    remove_intl_airport_code,
+    validate_intl_airport,
+)
+from .break_time import get_break_length, set_break_length
+from .config_yaml import CONFIG_YML, config_write_lock
+from .filters import (
+    add_extraction_filter,
+    list_extraction_filters,
+    remove_extraction_filter,
+    update_extraction_filter,
+)
+from .rows import (
+    add_override,
+    apply_phase_r_override,
+    clear_all_overrides,
+    delete_override,
+    update_override,
+    write_staged_override,
+)
+
+__all__ = [
+    "CONFIG_YML",
+    "add_extraction_filter",
+    "add_intl_airport_code",
+    "add_override",
+    "apply_phase_r_override",
+    "clear_all_overrides",
+    "config_write_lock",
+    "delete_override",
+    "get_break_length",
+    "list_extraction_filters",
+    "list_intl_airports",
+    "preview_intl_airport_yaml_diff",
+    "remove_extraction_filter",
+    "remove_intl_airport_code",
+    "set_break_length",
+    "update_extraction_filter",
+    "update_override",
+    "validate_intl_airport",
+    "write_staged_override",
+]

src/web/overrides/airports.py

@@ -0,0 +1,261 @@
+"""The Setup sidebar's international airport codes: list, add, remove.
+
+Edits ``io.sv_portal.international_airport_codes`` in
+``configs/config.yml`` so the engine picks the change up on the next run
+with no manual edit step. Validation for an add is split out from the
+write so the caller can preview the diff before anything touches the
+file.
+"""
+
+from __future__ import annotations
+
+import re
+
+import yaml
+
+from .config_yaml import CONFIG_YML, config_write_lock
+
+_INTL_CODE_RE = re.compile(r"^[A-Z]{3}$")
+_INTL_HEADER_RE = re.compile(r"^\s*international_airport_codes\s*:\s*(#.*)?$")
+_INTL_ITEM_RE = re.compile(r"^(\s*-\s+)([A-Z]{3})\s*(?:#\s*(.*))?$")
+
+
+def _find_intl_block(lines: list[str]) -> tuple[int, list[int]]:
+    """Locate the ``international_airport_codes`` list in config.yml.
+
+    Returns ``(header_idx, item_idxs)``: the header line and every
+    ``- XXX`` item line under it, in file order. ``header_idx`` is -1
+    when the section is missing.
+    """
+    header_idx = -1
+    item_idxs: list[int] = []
+    for i, ln in enumerate(lines):
+        if header_idx < 0:
+            if _INTL_HEADER_RE.match(ln):
+                header_idx = i
+            continue
+        if _INTL_ITEM_RE.match(ln):
+            item_idxs.append(i)
+            continue
+        # Stop scanning once we leave the list block: a line at
+        # less-or-equal indent than the header, or a new YAML key at
+        # the io.sv_portal level.
+        if ln.strip() and not ln.startswith(" " * 6):
+            break
+    return header_idx, item_idxs
+
+
+def _read_existing_intl_codes() -> list[str]:
+    raw = yaml.safe_load(CONFIG_YML.read_text(encoding="utf-8"))
+    return list(
+        raw.get("io", {})
+        .get("sv_portal", {})
+        .get("international_airport_codes", [])
+    )
+
+
+def _read_routing_drop_dep_codes() -> list[str]:
+    """Read ``io.sv_portal.routing_drop_dep_codes`` — Gulf-3 airports
+    whose departing flights are dropped at Step 1 extraction (Phase 3,
+    2026-05-14, Change 1). Validation rejects adding these to the
+    international list (they're a different concept — dropped flights
+    can't be allocated as INTL).
+
+    Empty list when the key is missing; caller treats that as "no
+    exclusions configured."
+    """
+    raw = yaml.safe_load(CONFIG_YML.read_text(encoding="utf-8"))
+    return list(
+        raw.get("io", {})
+        .get("sv_portal", {})
+        .get("routing_drop_dep_codes", [])
+    )
+
+
+def validate_intl_airport(
+    code: str, name: str | None = None,
+) -> tuple[str, str]:
+    """Sanitize + validate a proposed international-airport addition.
+
+    Returns ``(sanitized_code, sanitized_name)``. Raises ``ValueError``
+    with a user-facing message on any failure. The three checks are:
+
+      1. Code matches the IATA 3-uppercase-letter convention.
+      2. Code is not already in ``international_airport_codes``.
+      3. Code is not in ``routing_drop_dep_codes`` (Gulf-3 — AUH/DOH/DXB
+         by default). Flights departing from those airports are dropped
+         at Step 1 (Phase 3 / Change 1, 2026-05-14), so classifying them
+         as INTL would never take effect.
+
+    Pure function: does NOT touch disk. Callers compose it with
+    ``_apply_intl_airport_to_yaml`` for the actual mutation, either
+    directly (the existing operator route) or via the approval chassis
+    (the new agent tool).
+    """
+    if not isinstance(code, str):
+        raise ValueError("code must be a string")
+    raw = code.strip()
+    # Strict check BEFORE upper-casing: Phase 2 spec rejects lowercase
+    # outright (it's an API contract violation — the UI uppercases on
+    # input so a lowercase request can only come from a script). This
+    # changed 2026-05-13; previous behavior silently upper-cased.
+    if not _INTL_CODE_RE.match(raw):
+        raise ValueError(
+            f"code must be exactly 3 uppercase letters (got {code!r})"
+        )
+    code = raw  # already validated as uppercase
+    existing = {c.upper() for c in _read_existing_intl_codes()}
+    if code in existing:
+        raise ValueError(f"{code} is already in the international list")
+    drop_codes = {c.upper() for c in _read_routing_drop_dep_codes()}
+    if code in drop_codes:
+        raise ValueError(
+            f"{code} is in routing_drop_dep_codes (the Gulf-3 "
+            "AUH/DOH/DXB list). Flights departing from those airports "
+            "are dropped at Step 1, so adding the code to the INTL list "
+            "would have no effect. Use a different code or update "
+            "routing_drop_dep_codes directly."
+        )
+    cleaned_name = ""
+    if name:
+        cleaned_name = re.sub(r"[^\w\s\-/().,]", "", str(name)).strip()
+    return code, cleaned_name
+
+
+def _apply_intl_airport_to_yaml(code: str, name: str = "") -> None:
+    """Insert ``code`` (with optional ``name`` as a trailing comment)
+    under ``international_airport_codes`` in ``configs/config.yml``.
+
+    Pure mutation: assumes the caller has already validated. The file
+    edit is a targeted line-insertion (not a YAML round-trip) so the
+    file's commentary survives. Locates the last existing entry under
+    the list header and inserts after it, matching that entry's
+    indentation.
+
+    Raises ``ValueError`` if the section can't be found at all — that's
+    a structural problem with the config, not a validation error, and
+    callers should bubble it up.
+    """
+    with config_write_lock:
+        text = CONFIG_YML.read_text(encoding="utf-8")
+        lines = text.splitlines(keepends=False)
+        header_idx, item_idxs = _find_intl_block(lines)
+        if header_idx < 0:
+            raise ValueError(
+                "could not find international_airport_codes section in config.yml"
+            )
+        item_prefix = "      - "  # fallback if no item present yet
+        last_item_idx = -1
+        if item_idxs:
+            last_item_idx = item_idxs[-1]
+            item_prefix = _INTL_ITEM_RE.match(lines[last_item_idx]).group(1)
+        insert_at = (last_item_idx if last_item_idx >= 0 else header_idx) + 1
+        new_line = f"{item_prefix}{code}"
+        if name:
+            new_line = f"{new_line}  # {name}"
+        lines.insert(insert_at, new_line)
+        CONFIG_YML.write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+
+def preview_intl_airport_yaml_diff(code: str, name: str = "") -> str:
+    """Return a unified-diff-ish string of what ``_apply_intl_airport_to_yaml``
+    would do. Used by the agent approval preview.
+
+    Cheap: just rebuilds the would-be insert line and returns a small
+    diff string. Does NOT touch disk; safe to call inside the preview
+    builder.
+    """
+    item_prefix = "      - "
+    new_line = f"{item_prefix}{code}"
+    if name:
+        new_line = f"{new_line}  # {name}"
+    return (
+        f"--- configs/config.yml (before)\n"
+        f"+++ configs/config.yml (after)\n"
+        f"@@ io.sv_portal.international_airport_codes @@\n"
+        f"+{new_line}\n"
+    )
+
+
+def add_intl_airport_code(code: str, name: str | None = None) -> dict[str, str]:
+    """Validate + mutate in one shot. Existing direct-write entry point
+    (kept for the override drawer's airport form / direct API route).
+
+    The agent tool (``src.agent.tools.add_intl_airport``) uses
+    the two underlying functions (``validate_intl_airport`` and
+    ``_apply_intl_airport_to_yaml``) separately so the approval chassis
+    can preview the diff before any write happens.
+    """
+    sanitized_code, sanitized_name = validate_intl_airport(code, name)
+    _apply_intl_airport_to_yaml(sanitized_code, sanitized_name)
+    return {"code": sanitized_code, "name": sanitized_name}
+
+
+def list_intl_airports() -> list[dict[str, str]]:
+    """Every configured international airport, in file order, as
+    ``{"code", "name"}``. ``name`` is the trailing ``# comment`` the add
+    form writes, or "" when there is none.
+
+    The codes come from the parsed YAML — exactly what the engine will
+    read — and the names from the raw lines, since YAML drops comments.
+    """
+    text = CONFIG_YML.read_text(encoding="utf-8")
+    lines = text.splitlines(keepends=False)
+    _, item_idxs = _find_intl_block(lines)
+    names: dict[str, str] = {}
+    for i in item_idxs:
+        m = _INTL_ITEM_RE.match(lines[i])
+        names.setdefault(m.group(2), (m.group(3) or "").strip())
+    codes = (
+        (yaml.safe_load(text) or {})
+        .get("io", {})
+        .get("sv_portal", {})
+        .get("international_airport_codes")
+    ) or []
+    out: list[dict[str, str]] = []
+    seen: set[str] = set()
+    for c in codes:
+        code = str(c).strip().upper()
+        if not code or code in seen:
+            continue
+        seen.add(code)
+        out.append({"code": code, "name": names.get(code, "")})
+    return out
+
+
+def remove_intl_airport_code(code: str) -> dict[str, str]:
+    """Delete ``code`` from ``international_airport_codes`` in
+    ``configs/config.yml``. Returns the removed ``{"code", "name"}``.
+
+    Same targeted line splice as the add path, so the file's commentary
+    survives. Raises ``ValueError`` with a user-facing message when the
+    code isn't in the list, or when it is the last one left — an empty
+    list would leave a bare ``international_airport_codes:`` key that
+    YAML reads as null.
+    """
+    if not isinstance(code, str) or not _INTL_CODE_RE.match(code.strip()):
+        raise ValueError(f"code must be exactly 3 uppercase letters (got {code!r})")
+    code = code.strip()
+    with config_write_lock:
+        text = CONFIG_YML.read_text(encoding="utf-8")
+        lines = text.splitlines(keepends=False)
+        header_idx, item_idxs = _find_intl_block(lines)
+        if header_idx < 0:
+            raise ValueError(
+                "could not find international_airport_codes section in config.yml"
+            )
+        matches = [
+            i for i in item_idxs if _INTL_ITEM_RE.match(lines[i]).group(2) == code
+        ]
+        if not matches:
+            raise ValueError(f"{code} is not in the international list")
+        if len(matches) == len(item_idxs):
+            raise ValueError(
+                f"{code} is the last international airport code. Add "
+                "another code before removing it."
+            )
+        name = (_INTL_ITEM_RE.match(lines[matches[0]]).group(3) or "").strip()
+        for i in reversed(matches):
+            del lines[i]
+        CONFIG_YML.write_text("\n".join(lines) + "\n", encoding="utf-8")
+    return {"code": code, "name": name}

src/web/overrides/break_time.py

@@ -0,0 +1,83 @@
+"""The Setup sidebar's shift break length.
+
+Stored as ``break_pass.length_minutes`` in ``configs/config.yml`` and
+read by the floating-break post-pass (``allocator/postpass_break.py``)
+on every Allocate run. The write is a targeted line splice so the
+file's commentary survives; a config written before the setting
+existed gets the section appended.
+"""
+
+from __future__ import annotations
+
+import re
+
+from ...config import (
+    BREAK_MINUTES_HIGHEST,
+    BREAK_MINUTES_LOWEST,
+    load_config,
+)
+from .config_yaml import CONFIG_YML, config_write_lock
+
+_SECTION_RE = re.compile(r"^break_pass\s*:\s*(#.*)?$")
+_LENGTH_RE = re.compile(r"^(\s+length_minutes\s*:\s*)\d+(\s*(?:#.*)?)$")
+
+
+def get_break_length() -> int:
+    """The break length the next Allocate run will use."""
+    return load_config(CONFIG_YML).break_pass.length_minutes
+
+
+def validate_break_length(value: object) -> int:
+    """Whole minutes within the allowed band, or ``ValueError`` with a
+    user-facing message."""
+    if isinstance(value, bool) or not isinstance(value, (int, str)):
+        raise ValueError("break length must be a whole number of minutes")
+    try:
+        minutes = int(str(value).strip())
+    except ValueError:
+        raise ValueError(
+            "break length must be a whole number of minutes"
+        ) from None
+    if not BREAK_MINUTES_LOWEST <= minutes <= BREAK_MINUTES_HIGHEST:
+        raise ValueError(
+            f"break length must be between {BREAK_MINUTES_LOWEST} and "
+            f"{BREAK_MINUTES_HIGHEST} minutes (got {minutes})"
+        )
+    return minutes
+
+
+def set_break_length(value: object) -> int:
+    """Validate ``value`` and write it to config.yml. Returns the saved
+    minutes."""
+    minutes = validate_break_length(value)
+    with config_write_lock:
+        lines = CONFIG_YML.read_text(encoding="utf-8").splitlines(keepends=False)
+        header_idx = next(
+            (i for i, ln in enumerate(lines) if _SECTION_RE.match(ln)), -1,
+        )
+        if header_idx < 0:
+            lines += [
+                "",
+                "# Floating mid-shift break (allocator/postpass_break.py).",
+                "# Editable from the Setup sidebar.",
+                "break_pass:",
+                f"  length_minutes: {minutes}",
+            ]
+        else:
+            length_idx = -1
+            for i in range(header_idx + 1, len(lines)):
+                ln = lines[i]
+                if ln.strip() and not ln[0].isspace():
+                    break  # next top-level key: left the section
+                if _LENGTH_RE.match(ln):
+                    length_idx = i
+                    break
+            if length_idx >= 0:
+                lines[length_idx] = _LENGTH_RE.sub(
+                    lambda m: f"{m.group(1)}{minutes}{m.group(2)}",
+                    lines[length_idx],
+                )
+            else:
+                lines.insert(header_idx + 1, f"  length_minutes: {minutes}")
+        CONFIG_YML.write_text("\n".join(lines) + "\n", encoding="utf-8")
+    return minutes

src/web/overrides/config_yaml.py

@@ -0,0 +1,21 @@
+"""Shared handle on ``configs/config.yml`` for the drawer's write-through
+edits.
+
+The edits here are targeted line splices rather than a YAML round-trip,
+so the file's commentary survives a save. Every writer takes
+``config_write_lock`` first — two drawer forms submitted back to back
+land on different request threads.
+"""
+
+from __future__ import annotations
+
+import threading
+from pathlib import Path
+
+#: Absolute path, so a write works whatever CWD the server was launched from.
+CONFIG_YML = Path(__file__).resolve().parents[3] / "configs" / "config.yml"
+
+#: Serialises every read-modify-write against CONFIG_YML.
+config_write_lock = threading.Lock()
+
+__all__ = ["CONFIG_YML", "config_write_lock"]