packager.py

#!/usr/bin/env python3
"""Offline knowledge pack builder — SQLite FTS5 + optional corpus-derived vectors.

Builds portable .db packs from any data source (JSON, CSV, GeoJSON, piped stdin).
Packs support three search modes:
  1. FTS5 full-text search (always available, zero dependencies)
  2. Optional corpus-derived vectors (LSA, TF-IDF SVD, or pre-computed — user/agent decides at build time)
  3. LLM rerank via llama.rn on-device (app-side, not in packager)

Pack spec (.db contract):
  Required: chunks + fts_chunks (FTS5, content-synced, no data duplication) + pack_metadata
  Optional: chunk_vectors (corpus-derived vectors — method described in metadata,
            no neural model reference, user/agent decides at build time)
  Optional: geo_points (spatial), layers (organisational)

Designed to be called from the command line — by any AI agent, automation
script, or human.
Zero external dependencies — uses only Python stdlib (sqlite3, json, csv, struct).

Usage:
    python3 packager.py init --output pack.db --name "au-scams" --country AU
    python3 packager.py add-layer --pack pack.db --name hospitals --tier static_reference --file data.json
    python3 packager.py add-geo --pack pack.db --layer hospitals --lat-field lat --lon-field lon
    python3 packager.py vectorise --pack pack.db --method lsa --dimensions 64
    python3 packager.py vectorise --pack pack.db --method file --file vectors.json
    python3 packager.py build-index --pack pack.db
    python3 packager.py info --pack pack.db
    python3 packager.py query --pack pack.db --search "hospital emergency"
    python3 packager.py archive --pack pack.db --output pack.oapack.zip
    python3 packager.py build --manifest manifest.json --output pack.db --archive

License: Apache-2.0
"""

from __future__ import annotations

import argparse
import csv
import hashlib
import io
import json
import math
import os
import sqlite3
import struct
import sys
import zipfile
from datetime import datetime, timezone
from pathlib import Path
from typing import Any

BUILDER_VERSION = "0.4.0"

ARCHIVE_FORMAT_VERSION = "1.0"
ARCHIVE_ARTIFACT_TYPE = "offlineaid.pack.archive"
ARCHIVE_MANIFEST_FILENAME = "manifest.json"

VALID_TIERS = ("static_reference", "periodic_snapshot", "realtime_cache")

# ── Schema ────────────────────────────────────────────────────────────

SCHEMA_SQL = """
-- Pack metadata (key-value)
CREATE TABLE IF NOT EXISTS pack_metadata (
    key   TEXT PRIMARY KEY,
    value TEXT NOT NULL
);

-- Data layers with tier classification
CREATE TABLE IF NOT EXISTS layers (
    name        TEXT PRIMARY KEY,
    tier        TEXT NOT NULL CHECK(tier IN ('static_reference','periodic_snapshot','realtime_cache')),
    description TEXT,
    row_count   INTEGER DEFAULT 0,
    source_type TEXT,
    source_info TEXT,
    added_at    TEXT NOT NULL,
    -- Provenance (per-source, optional). Trust pillar: a pack composed of
    -- multiple sources carries each source's own publisher/licence so the
    -- on-device nutrition-label UI can attribute every chunk correctly.
    publisher            TEXT,           -- e.g. "ACCC", "NASC", "Department of PM&C"
    license              TEXT,           -- SPDX-style id where possible, e.g. "CC-BY-4.0-AU"
    source_url           TEXT,           -- canonical URL of the upstream source
    reviewed_at          TEXT,           -- ISO-8601 UTC of last human review
    cultural_sensitivity TEXT,           -- free-text flag (e.g. "indigenous-protocols")
    expires_at           TEXT,           -- ISO-8601 UTC; UI may warn if past
    language             TEXT            -- BCP-47 tag of the source content
);

-- Text chunks — the core data store
-- Each row is a searchable chunk of content from a layer.
CREATE TABLE IF NOT EXISTS chunks (
    id       INTEGER PRIMARY KEY AUTOINCREMENT,
    text     TEXT NOT NULL,
    source   TEXT NOT NULL,       -- layer name (matches layers.name)
    section  TEXT DEFAULT '',     -- sub-section within layer (optional)
    data     TEXT,                -- full JSON object (original row)
    tokens   INTEGER DEFAULT 0   -- estimated token count for LLM context budgeting
);

-- FTS5 full-text search index over chunks (Tier 1 search — always available)
CREATE VIRTUAL TABLE IF NOT EXISTS fts_chunks USING fts5(
    text, source, section,
    content='chunks', content_rowid='id'
);

-- Geo-located points of interest (optional, for map features)
CREATE TABLE IF NOT EXISTS geo_points (
    id         INTEGER PRIMARY KEY AUTOINCREMENT,
    name       TEXT NOT NULL,
    name_local TEXT,              -- local language name (e.g. Traditional Chinese)
    category   TEXT NOT NULL,     -- 'hospital', 'embassy', 'fuel', 'shelter', etc.
    lat        REAL NOT NULL,
    lon        REAL NOT NULL,
    address    TEXT,
    address_local TEXT,
    district   TEXT,
    metadata   TEXT,              -- JSON: opening hours, phone, services, etc.
    chunk_id   INTEGER REFERENCES chunks(id),
    layer      TEXT REFERENCES layers(name)
);

CREATE INDEX IF NOT EXISTS idx_geo_category ON geo_points(category);
CREATE INDEX IF NOT EXISTS idx_geo_district ON geo_points(district);
CREATE INDEX IF NOT EXISTS idx_geo_layer ON geo_points(layer);
CREATE INDEX IF NOT EXISTS idx_geo_coords ON geo_points(lat, lon);
CREATE INDEX IF NOT EXISTS idx_chunks_source ON chunks(source);

-- Corpus-derived vectors (optional — user/agent decides at build time)
-- Method (LSA, TF-IDF SVD, etc.) and dimensions stored in pack_metadata,
-- NOT per-row.  No neural model reference — these are corpus-derived.
-- Vectors stored as little-endian float32 blobs for portability.
CREATE TABLE IF NOT EXISTS chunk_vectors (
    chunk_id   INTEGER PRIMARY KEY REFERENCES chunks(id),
    vector     BLOB NOT NULL      -- float32[] as little-endian bytes
);
"""


def _now() -> str:
    return datetime.now(timezone.utc).isoformat()


def _file_sha256(path: str) -> str:
    """Compute a hex SHA-256 digest for a file."""
    hasher = hashlib.sha256()
    with open(path, "rb") as f:
        while chunk := f.read(1024 * 1024):
            hasher.update(chunk)
    return hasher.hexdigest()


def _pack_metadata(path: str) -> dict[str, str]:
    """Read pack metadata from an existing SQLite pack."""
    conn: sqlite3.Connection | None = None
    try:
        conn = sqlite3.connect(path)
        meta = dict(conn.execute("SELECT key, value FROM pack_metadata").fetchall())
    except sqlite3.Error as exc:
        raise ValueError(f"{path} is not a valid OfflineAid pack database: {exc}") from exc
    finally:
        if conn is not None:
            conn.close()

    if not meta.get("name"):
        raise ValueError(f"{path} is missing required pack metadata ('name').")
    return meta


def _default_archive_output(pack_path: str) -> str:
    """Return the default archive output path for a .db pack."""
    pack = Path(pack_path)
    return str(pack.with_name(f"{pack.stem}.oapack.zip"))


def _archive_checksum_filename(db_filename: str) -> str:
    return f"{db_filename}.sha256"


def _checksum_contents(db_filename: str, db_sha256: str) -> str:
    return f"{db_sha256}  {db_filename}\n"


def _build_archive_manifest(pack_path: str, created_at: str | None = None) -> dict[str, str]:
    """Build the transport manifest for an archived pack."""
    meta = _pack_metadata(pack_path)
    return {
        "format_version": ARCHIVE_FORMAT_VERSION,
        "artifact_type": ARCHIVE_ARTIFACT_TYPE,
        "pack_name": meta["name"],
        "pack_version": meta.get("version", "1.0.0"),
        "db_filename": Path(pack_path).name,
        "db_sha256": _file_sha256(pack_path),
        "builder_version": meta.get("builder_version", BUILDER_VERSION),
        "created_at": created_at or _now(),
    }


def _parse_checksum_contents(contents: str, db_filename: str) -> str:
    """Parse a checksum sidecar file and return the hex digest."""
    stripped = contents.strip()
    if not stripped:
        raise ValueError("Checksum file is empty.")

    parts = stripped.split()
    digest = parts[0].lower()
    if len(digest) != 64 or any(c not in "0123456789abcdef" for c in digest):
        raise ValueError("Checksum file does not contain a valid SHA-256 digest.")

    if len(parts) > 1 and parts[1].lstrip("*") != db_filename:
        raise ValueError("Checksum file does not reference the archived database filename.")

    return digest


def _validate_archive_contract(archive_path: str) -> dict[str, Any]:
    """Validate an OfflineAid archive and return its manifest."""
    try:
        with zipfile.ZipFile(archive_path, "r") as zf:
            file_names = [info.filename for info in zf.infolist() if not info.is_dir()]
            if not file_names:
                raise ValueError("Archive is empty.")

            if any(Path(name).name != name for name in file_names):
                raise ValueError("Archive entries must be top-level files.")

            db_files = [name for name in file_names if name.lower().endswith(".db")]
            if len(db_files) != 1:
                raise ValueError("Archive must contain exactly one SQLite .db file.")

            manifest_count = file_names.count(ARCHIVE_MANIFEST_FILENAME)
            if manifest_count != 1:
                raise ValueError("Archive must contain exactly one manifest.json file.")

            checksum_files = [name for name in file_names if name.lower().endswith(".sha256")]
            if len(checksum_files) > 1:
                raise ValueError("Archive may contain at most one checksum file.")

            allowed = {db_files[0], ARCHIVE_MANIFEST_FILENAME, *checksum_files}
            extras = [name for name in file_names if name not in allowed]
            if extras:
                raise ValueError(f"Archive contains unexpected files: {', '.join(sorted(extras))}")

            try:
                manifest = json.loads(zf.read(ARCHIVE_MANIFEST_FILENAME))
            except json.JSONDecodeError as exc:
                raise ValueError("Archive manifest.json is not valid JSON.") from exc

            required_fields = {
                "format_version",
                "artifact_type",
                "pack_name",
                "pack_version",
                "db_filename",
                "db_sha256",
                "builder_version",
                "created_at",
            }
            missing = sorted(required_fields - set(manifest))
            if missing:
                raise ValueError(f"Archive manifest is missing required fields: {', '.join(missing)}")

            if manifest["format_version"] != ARCHIVE_FORMAT_VERSION:
                raise ValueError(
                    f"Unsupported archive format version: {manifest['format_version']}"
                )
            if manifest["artifact_type"] != ARCHIVE_ARTIFACT_TYPE:
                raise ValueError(f"Unsupported archive artifact type: {manifest['artifact_type']}")

            db_filename = manifest["db_filename"]
            if db_filename != db_files[0]:
                raise ValueError("Archive manifest db_filename does not match the packaged .db file.")

            db_sha256 = hashlib.sha256(zf.read(db_filename)).hexdigest()
            if db_sha256 != manifest["db_sha256"]:
                raise ValueError("Archive manifest db_sha256 does not match the packaged database.")

            if checksum_files:
                checksum_name = checksum_files[0]
                expected_checksum_name = _archive_checksum_filename(db_filename)
                if checksum_name != expected_checksum_name:
                    raise ValueError(
                        "Checksum filename must match the archived database filename."
                    )
                checksum_sha256 = _parse_checksum_contents(
                    zf.read(checksum_name).decode("utf-8"),
                    db_filename,
                )
                if checksum_sha256 != manifest["db_sha256"]:
                    raise ValueError("Checksum file does not match the manifest digest.")
    except zipfile.BadZipFile as exc:
        raise ValueError(f"{archive_path} is not a valid ZIP archive.") from exc

    return manifest


def _estimate_tokens(text: str) -> int:
    """Rough token estimate (~4 chars per token for English, ~2 for CJK)."""
    # Count CJK characters
    cjk = sum(1 for c in text if '\u4e00' <= c <= '\u9fff' or '\u3400' <= c <= '\u4dbf')
    non_cjk = len(text) - cjk
    return (non_cjk // 4) + (cjk // 2)


def _flatten_to_text(obj: dict) -> str:
    """Flatten a dict to a searchable text string."""
    parts = []
    for k, v in obj.items():
        if v is None or k.startswith("_"):
            continue
        if isinstance(v, (dict, list)):
            parts.append(json.dumps(v, ensure_ascii=False))
        else:
            parts.append(str(v))
    return " ".join(parts)


def _vector_to_blob(vec: list[float]) -> bytes:
    """Pack a float32 vector into a little-endian bytes blob."""
    return struct.pack(f"<{len(vec)}f", *vec)


def _blob_to_vector(blob: bytes) -> list[float]:
    """Unpack a little-endian bytes blob into a float32 list."""
    n = len(blob) // 4
    return list(struct.unpack(f"<{n}f", blob))


def _cosine_similarity(a: list[float], b: list[float]) -> float:
    """Compute cosine similarity between two vectors."""
    dot = sum(x * y for x, y in zip(a, b))
    norm_a = math.sqrt(sum(x * x for x in a))
    norm_b = math.sqrt(sum(x * x for x in b))
    if norm_a == 0 or norm_b == 0:
        return 0.0
    return dot / (norm_a * norm_b)


# ── Data readers ──────────────────────────────────────────────────────


def _read_json(path: str) -> list[dict]:
    """Read a JSON file (array of objects, single object, CKAN response, or GeoJSON)."""
    with open(path, "r", encoding="utf-8") as f:
        data = json.load(f)
    if isinstance(data, dict):
        if "result" in data and isinstance(data["result"], list):
            return data["result"]
        if "results" in data and isinstance(data["results"], list):
            return data["results"]
        if "features" in data and isinstance(data["features"], list):
            return [
                {**feat.get("properties", {}), "_geometry": feat.get("geometry")}
                for feat in data["features"]
            ]
        return [data]
    if isinstance(data, list):
        return data
    raise ValueError(f"Unsupported JSON structure in {path}")


def _read_csv(path: str) -> list[dict]:
    with open(path, "r", encoding="utf-8-sig") as f:
        return list(csv.DictReader(f))


def _read_stdin(fmt: str) -> list[dict]:
    if fmt == "csv":
        return list(csv.DictReader(sys.stdin))
    data = json.load(sys.stdin)
    return data if isinstance(data, list) else [data]


def _read_data(file_path: str | None, fmt: str, from_stdin: bool) -> list[dict]:
    if from_stdin:
        return _read_stdin(fmt)
    if file_path is None:
        raise ValueError("Either --file or --from-stdin is required")
    if fmt == "csv":
        return _read_csv(file_path)
    if fmt in ("json", "geojson"):
        return _read_json(file_path)
    try:
        return _read_json(file_path)
    except (json.JSONDecodeError, ValueError):
        return _read_csv(file_path)


# ── API ──────────────────────────────────────────────────────────────


def init_pack(
    output: str,
    name: str,
    version: str = "1.0.0",
    country: str = "",
    scenario: str = "",
    force: bool = False,
) -> str:
    """Initialize a new pack database (API)."""
    if os.path.exists(output) and not force:
        raise FileExistsError(f"{output} already exists. Use force=True to overwrite.")
    if os.path.exists(output) and force:
        os.remove(output)

    os.makedirs(os.path.dirname(output) or ".", exist_ok=True)
    conn = sqlite3.connect(output)
    try:
        conn.executescript(SCHEMA_SQL)
        meta = {
            "name": name,
            "version": version,
            "country": country,
            "scenario": scenario,
            "created_at": _now(),
            "builder_version": BUILDER_VERSION,
            "sources": "[]",
        }
        with conn:
            conn.executemany(
                "INSERT OR REPLACE INTO pack_metadata (key, value) VALUES (?, ?)",
                meta.items(),
            )
    finally:
        conn.close()
    return output


def add_layer(
    pack_path: str,
    name: str,
    tier: str,
    rows: list[dict[str, Any]],
    description: str = "",
    section: str = "",
    source_info: str = "",
    source_type: str = "agent",
    provenance: dict[str, str | None] | None = None,
) -> dict[str, Any]:
    """Add a data layer to an existing pack (API)."""
    if not os.path.exists(pack_path):
        raise FileNotFoundError(f"Pack {pack_path} does not exist.")

    if tier not in VALID_TIERS:
        raise ValueError(f"Tier must be one of {VALID_TIERS}")

    if not rows:
        return {"name": name, "row_count": 0, "status": "no_data"}

    conn = sqlite3.connect(pack_path)
    now = _now()
    chunks = []
    for row in rows:
        if not isinstance(row, dict):
            row = {"value": row}
        text = _flatten_to_text(row)
        tokens = _estimate_tokens(text)
        # Allow row to override layer-level section
        row_section = row.get("section", section)
        chunks.append((
            text,
            name,       # source = layer name
            row_section,
            json.dumps(row, ensure_ascii=False),
            tokens,
        ))

    p = provenance or {}
    try:
        with conn:
            conn.execute(
                """INSERT OR REPLACE INTO layers (
                       name, tier, description, row_count, source_type, source_info, added_at,
                       publisher, license, source_url, reviewed_at,
                       cultural_sensitivity, expires_at, language
                   ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
                (
                    name, tier, description, len(rows), source_type, source_info, now,
                    p.get("publisher"),
                    p.get("license"),
                    p.get("source_url"),
                    p.get("reviewed_at"),
                    p.get("cultural_sensitivity"),
                    p.get("expires_at"),
                    p.get("language"),
                ),
            )
            # Remove stale chunks so re-running add-layer is idempotent (§26.2.1).
            conn.execute("DELETE FROM chunks WHERE source = ?", (name,))
            conn.executemany(
                "INSERT INTO chunks (text, source, section, data, tokens) VALUES (?, ?, ?, ?, ?)",
                chunks,
            )
    finally:
        conn.close()
    return {"name": name, "row_count": len(rows), "tier": tier}


def add_geo_points(
    pack_path: str,
    layer: str,
    points: list[dict[str, Any]],
) -> dict[str, Any]:
    """Add geo points for a layer (API).

    Expected point format: {
        "lat": float, "lon": float, "name": str, "chunk_id": int (optional),
        "name_local": str, "address": str, "address_local": str, "district": str,
        "category": str, "metadata": dict
    }
    """
    conn = sqlite3.connect(pack_path)
    try:
        # Verify layer exists
        exists = conn.execute("SELECT name FROM layers WHERE name = ?", (layer,)).fetchone()
        if not exists:
            raise ValueError(f"Layer '{layer}' not found.")

        geo_rows = []
        for p in points:
            lat = p.get("lat")
            lon = p.get("lon")
            if lat is None or lon is None:
                continue
            
            metadata = p.get("metadata")
            geo_rows.append((
                str(p.get("name", "")),
                p.get("name_local"),
                p.get("category") or layer,
                float(lat),
                float(lon),
                p.get("address"),
                p.get("address_local"),
                p.get("district"),
                json.dumps(metadata, ensure_ascii=False) if metadata else None,
                p.get("chunk_id"),
                layer,
            ))

        with conn:
            conn.execute("DELETE FROM geo_points WHERE layer = ?", (layer,))
            conn.executemany(
                """INSERT INTO geo_points (name, name_local, category, lat, lon, address,
                   address_local, district, metadata, chunk_id, layer)
                   VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
                geo_rows,
            )
    finally:
        conn.close()
    return {"layer": layer, "point_count": len(geo_rows)}


def build_index(pack_path: str) -> dict[str, Any]:
    """Rebuild the FTS5 search index (API)."""
    conn = sqlite3.connect(pack_path)
    try:
        with conn:
            conn.execute("INSERT INTO fts_chunks(fts_chunks) VALUES('rebuild')")
        count = conn.execute("SELECT COUNT(*) FROM chunks").fetchone()[0]
    finally:
        conn.close()
    return {"chunks_indexed": count}


def archive_pack(
    pack_path: str,
    output: str | None = None,
    force: bool = False,
) -> str:
    """Package a built .db into an OfflineAid transport archive (API)."""
    if not os.path.exists(pack_path):
        raise FileNotFoundError(f"Pack {pack_path} does not exist.")

    out = output or _default_archive_output(pack_path)
    if os.path.exists(out) and not force:
        raise FileExistsError(f"{out} already exists. Use force=True to overwrite.")
    if os.path.exists(out) and force:
        os.remove(out)

    manifest = _build_archive_manifest(pack_path)
    db_filename = manifest["db_filename"]
    checksum_filename = _archive_checksum_filename(db_filename)

    os.makedirs(os.path.dirname(out) or ".", exist_ok=True)
    with zipfile.ZipFile(out, "w", compression=zipfile.ZIP_DEFLATED, compresslevel=9) as zf:
        zf.write(pack_path, arcname=db_filename)
        zf.writestr(
            ARCHIVE_MANIFEST_FILENAME,
            json.dumps(manifest, indent=2, ensure_ascii=False) + "\n",
        )
        zf.writestr(
            checksum_filename,
            _checksum_contents(db_filename, manifest["db_sha256"]),
        )

    _validate_archive_contract(out)
    return out


def verify_pack_archive(archive_path: str) -> dict[str, Any]:
    """Verify an OfflineAid archive (API)."""
    if not os.path.exists(archive_path):
        raise FileNotFoundError(f"{archive_path} does not exist.")
    return _validate_archive_contract(archive_path)


# ── Commands ──────────────────────────────────────────────────────────


def cmd_init(args: argparse.Namespace) -> None:
    """Initialize a new pack database."""
    try:
        init_pack(
            output=args.output,
            name=args.name,
            version=args.version or "1.0.0",
            country=args.country or "",
            scenario=args.scenario or "",
            force=args.force,
        )
    except FileExistsError as exc:
        print(f"Error: {exc}", file=sys.stderr)
        sys.exit(1)
    print(f"Initialized pack: {args.output} ({args.name})")


def cmd_add_layer(args: argparse.Namespace) -> None:
    """Add a data layer to an existing pack."""
    data = _read_data(args.file, args.format or "json", args.from_stdin)
    if not data:
        print("Warning: no data rows found.", file=sys.stderr)
        return

    source_type = "stdin" if args.from_stdin else ("file" if args.file else "unknown")
    source_info = args.file or "stdin"
    provenance = {
        "publisher": getattr(args, "publisher", None),
        "license": getattr(args, "license", None),
        "source_url": getattr(args, "source_url", None),
        "reviewed_at": getattr(args, "reviewed_at", None),
        "cultural_sensitivity": getattr(args, "cultural_sensitivity", None),
        "expires_at": getattr(args, "expires_at", None),
        "language": getattr(args, "language", None),
    }

    try:
        res = add_layer(
            pack_path=args.pack,
            name=args.name,
            tier=args.tier,
            rows=data,
            description=args.description or "",
            section=args.section or "",
            source_info=source_info,
            source_type=source_type,
            provenance=provenance,
        )
    except (FileNotFoundError, ValueError) as exc:
        print(f"Error: {exc}", file=sys.stderr)
        sys.exit(1)

    print(f"Added layer '{res['name']}' ({res['row_count']} rows, tier={res['tier']}) to {args.pack}")


def cmd_add_geo(args: argparse.Namespace) -> None:
    """Extract geo points from an existing layer's chunks."""
    conn = sqlite3.connect(args.pack)
    try:
        layer_row = conn.execute("SELECT name FROM layers WHERE name = ?", (args.layer,)).fetchone()
        if not layer_row:
            print(f"Error: layer '{args.layer}' not found.", file=sys.stderr)
            sys.exit(1)

        lat_field = args.lat_field
        lon_field = args.lon_field
        name_field = args.name_field or "name"
        name_local_field = args.name_local_field
        category = args.category or args.layer

        rows = conn.execute(
            "SELECT id, data FROM chunks WHERE source = ?", (args.layer,)
        ).fetchall()
    finally:
        conn.close()

    points = []
    for chunk_id, data_json in rows:
        if not data_json:
            continue
        try:
            obj = json.loads(data_json)
        except json.JSONDecodeError:
            continue

        lat = obj.get(lat_field)
        lon = obj.get(lon_field)
        if lat is None or lon is None:
            continue
        try:
            lat, lon = float(lat), float(lon)
        except (ValueError, TypeError):
            continue

        name = str(obj.get(name_field, ""))
        name_local = str(obj.get(name_local_field, "")) if name_local_field else None
        address = obj.get("address", obj.get("address_en", ""))
        address_local = obj.get("address_local", obj.get("address_tc", ""))
        district = obj.get("district", "")

        skip = {lat_field, lon_field, name_field, "address", "address_en", "address_tc",
                "address_local", "district"}
        if name_local_field:
            skip.add(name_local_field)
        metadata = {k: v for k, v in obj.items() if k not in skip and not k.startswith("_")}

        points.append({
            "name": name,
            "name_local": name_local,
            "category": category,
            "lat": lat,
            "lon": lon,
            "address": str(address) if address else None,
            "address_local": str(address_local) if address_local else None,
            "district": str(district) if district else None,
            "metadata": metadata if metadata else None,
            "chunk_id": chunk_id,
        })

    try:
        res = add_geo_points(
            pack_path=args.pack,
            layer=args.layer,
            points=points,
        )
    except ValueError as exc:
        print(f"Error: {exc}", file=sys.stderr)
        sys.exit(1)

    print(f"Added {res['point_count']} geo points for layer '{args.layer}' (category={category})")


def cmd_build_index(args: argparse.Namespace) -> None:
    """Rebuild the FTS5 search index."""
    res = build_index(args.pack)
    print(f"FTS5 index rebuilt: {res['chunks_indexed']} chunks indexed")


def _tfidf_vectors(texts: list[str], dimensions: int) -> list[list[float]]:
    """Build TF-IDF matrix then reduce to `dimensions` via truncated SVD.

    Pure stdlib implementation — no numpy/scipy/sklearn required.
    Uses power-iteration SVD approximation for portability.
    """
    import re
    from collections import Counter

    # Tokenise
    tokenised = [re.findall(r"\w+", t.lower()) for t in texts]
    n_docs = len(tokenised)

    # Build vocabulary (top terms by doc frequency, cap at 5000 for speed)
    df: dict[str, int] = Counter()
    for tokens in tokenised:
        for w in set(tokens):
            df[w] += 1
    # Filter: must appear in ≥2 docs and ≤80 % of docs
    vocab_list = [
        w for w, c in df.most_common(5000)
        if c >= 2 and c <= 0.8 * n_docs
    ]
    if not vocab_list:
        vocab_list = [w for w, _ in df.most_common(min(500, len(df)))]
    vocab = {w: i for i, w in enumerate(vocab_list)}
    v_size = len(vocab)

    if v_size == 0 or n_docs == 0:
        return [[0.0] * dimensions for _ in texts]

    # Build TF-IDF sparse rows
    idf = {}
    for w, c in df.items():
        if w in vocab:
            idf[w] = math.log((1 + n_docs) / (1 + c)) + 1

    # Sparse matrix as list of dicts
    tfidf_rows: list[dict[int, float]] = []
    for tokens in tokenised:
        tf = Counter(tokens)
        row: dict[int, float] = {}
        for w, count in tf.items():
            if w in vocab:
                row[vocab[w]] = (1 + math.log(count)) * idf.get(w, 1.0)
        # L2 normalise
        norm = math.sqrt(sum(v * v for v in row.values())) or 1.0
        row = {k: v / norm for k, v in row.items()}
        tfidf_rows.append(row)

    # Truncated SVD via power iteration (sparse-friendly)
    dims = min(dimensions, v_size, n_docs)
    import random
    random.seed(42)

    # Random projection matrix V: dims x v_size
    V = [[random.gauss(0, 1) for _ in range(v_size)] for _ in range(dims)]
    # Normalise rows of V
    for row in V:
        norm = math.sqrt(sum(x * x for x in row)) or 1.0
        for j in range(len(row)):
            row[j] /= norm

    # Power iterations: A^T A V^T  (A is n_docs x v_size sparse)
    for _ in range(5):
        # AV^T => n_docs x dims
        AV = []
        for sparse_row in tfidf_rows:
            r = []
            for vi in range(dims):
                s = sum(sparse_row.get(j, 0.0) * V[vi][j] for j in sparse_row)
                r.append(s)
            AV.append(r)

        # A^T (AV) => v_size x dims
        AtAV = [[0.0] * dims for _ in range(v_size)]
        for doc_i, sparse_row in enumerate(tfidf_rows):
            for j in sparse_row:
                for d in range(dims):
                    AtAV[j][d] += sparse_row[j] * AV[doc_i][d]

        # QR via Gram-Schmidt on AtAV columns (transposed = dims x v_size)
        V_new = []
        for d in range(dims):
            col = [AtAV[j][d] for j in range(v_size)]
            # Orthogonalise against previous
            for prev in V_new:
                dot = sum(a * b for a, b in zip(col, prev))
                col = [c - dot * p for c, p in zip(col, prev)]
            norm = math.sqrt(sum(x * x for x in col)) or 1.0
            V_new.append([x / norm for x in col])
        V = V_new

    # Project: each doc => dims-dimensional vector
    result = []
    for sparse_row in tfidf_rows:
        vec = []
        for vi in range(dims):
            s = sum(sparse_row.get(j, 0.0) * V[vi][j] for j in sparse_row)
            vec.append(s)
        # L2 normalise
        norm = math.sqrt(sum(x * x for x in vec)) or 1.0
        result.append([x / norm for x in vec])

    return result


def cmd_vectorise(args: argparse.Namespace) -> None:
    """Generate corpus-derived vectors for all chunks.

    Supports three methods:
    1. --method lsa     : TF-IDF + truncated SVD (pure stdlib, zero deps)
    2. --method tfidf   : alias for lsa
    3. --method file    : reads pre-computed vectors from a JSON file
       File format: [{"chunk_id": 1, "vector": [0.1, 0.2, ...]}, ...]

    Vector method and dimensions are stored in pack_metadata (NOT per-row).
    No neural model reference — these are corpus-derived.
    """
    conn = sqlite3.connect(args.pack)
    method = args.method
    dims = args.dimensions or 64

    if method == "file":
        # Load pre-computed vectors from JSON
        with open(args.file, "r") as f:
            vectors = json.load(f)

        if not vectors:
            print("No vectors found in file.", file=sys.stderr)
            return

        actual_dims = len(vectors[0]["vector"])
        method_name = args.method_name or Path(args.file).stem

        conn.execute("DELETE FROM chunk_vectors")
        for item in vectors:
            conn.execute(
                "INSERT INTO chunk_vectors (chunk_id, vector) VALUES (?, ?)",
                (item["chunk_id"], _vector_to_blob(item["vector"])),
            )

        conn.execute("INSERT OR REPLACE INTO pack_metadata VALUES ('has_vectors', 'true')")
        conn.execute("INSERT OR REPLACE INTO pack_metadata VALUES ('vector_method', ?)", (method_name,))
        conn.execute("INSERT OR REPLACE INTO pack_metadata VALUES ('vector_dimensions', ?)", (str(actual_dims),))
        conn.commit()
        conn.close()
        print(f"Loaded {len(vectors)} vectors from file ({actual_dims}d, method={method_name})")
        return

    # Corpus-derived: LSA / TF-IDF SVD (pure stdlib)
    chunks = conn.execute("SELECT id, text FROM chunks").fetchall()
    if not chunks:
        print("No chunks in pack — add layers first.", file=sys.stderr)
        conn.close()
        return

    total = len(chunks)
    ids = [cid for cid, _ in chunks]
    texts = [text for _, text in chunks]

    print(f"Computing {method.upper()} vectors for {total} chunks (dimensions={dims})...")
    vectors = _tfidf_vectors(texts, dims)
    actual_dims = len(vectors[0]) if vectors else dims

    conn.execute("DELETE FROM chunk_vectors")
    for i, vec in enumerate(vectors):
        conn.execute(
            "INSERT INTO chunk_vectors (chunk_id, vector) VALUES (?, ?)",
            (ids[i], _vector_to_blob(vec)),
        )

    method_label = f"tfidf-svd-{actual_dims}d"
    conn.execute("INSERT OR REPLACE INTO pack_metadata VALUES ('has_vectors', 'true')")
    conn.execute("INSERT OR REPLACE INTO pack_metadata VALUES ('vector_method', ?)", (method_label,))
    conn.execute("INSERT OR REPLACE INTO pack_metadata VALUES ('vector_dimensions', ?)", (str(actual_dims),))
    conn.commit()
    conn.close()
    print(f"Done: {total} vectors ({actual_dims}d, method={method_label}) written to pack")


def cmd_info(args: argparse.Namespace) -> None:
    """Show pack metadata and statistics."""
    conn = sqlite3.connect(args.pack)

    meta = dict(conn.execute("SELECT key, value FROM pack_metadata").fetchall())
    layers = conn.execute(
        "SELECT name, tier, row_count, description FROM layers ORDER BY name"
    ).fetchall()
    total_chunks = conn.execute("SELECT COUNT(*) FROM chunks").fetchone()[0]
    total_geo = conn.execute("SELECT COUNT(*) FROM geo_points").fetchone()[0]

    try:
        fts_count = conn.execute("SELECT COUNT(*) FROM fts_chunks").fetchone()[0]
    except sqlite3.OperationalError:
        fts_count = 0

    try:
        vec_count = conn.execute("SELECT COUNT(*) FROM chunk_vectors").fetchone()[0]
    except sqlite3.OperationalError:
        vec_count = 0

    file_size = os.path.getsize(args.pack)
    conn.close()

    print(f"Pack: {meta.get('name', '?')} v{meta.get('version', '?')}")
    print(f"Country: {meta.get('country', '?')} | Scenario: {meta.get('scenario', '?')}")
    print(f"Created: {meta.get('created_at', '?')}")
    print(f"Builder: v{meta.get('builder_version', '?')}")
    print(f"Size: {file_size:,} bytes ({file_size / 1024 / 1024:.1f} MB)")
    print(f"Chunks: {total_chunks:,} | FTS indexed: {fts_count:,} | Geo points: {total_geo:,}")

    has_vec = meta.get("has_vectors") == "true"
    if has_vec:
        print(f"Vectors: {vec_count:,} ({meta.get('vector_dimensions', '?')}d, method={meta.get('vector_method', '?')})")
    else:
        print("Vectors: none (run 'vectorise' command to add)")

    print()
    if layers:
        print(f"{'Layer':<30} {'Tier':<20} {'Rows':>8}  Description")
        print("-" * 90)
        for name, tier, row_count, desc in layers:
            print(f"{name:<30} {tier:<20} {row_count:>8}  {desc or ''}")
    else:
        print("No layers added yet.")


def _sanitise_fts_query(q: str) -> str:
    """Strip FTS5 syntax chars that raise OperationalError (§26.2.2).

    FTS5 reserves: : * " ( ) ^ - and the operators NEAR AND OR NOT.
    Strip punctuation, then quote any token that is a reserved operator so
    it is treated as a literal search term rather than a query modifier.
    """
    import re
    q = re.sub(r'[":*()^-]+', " ", q)
    tokens = q.split()
    safe = []
    for t in tokens:
        if t.upper() in {"NEAR", "AND", "OR", "NOT"}:
            t = f'"{t}"'
        safe.append(t)
    return " ".join(safe).strip() or '""'


def cmd_query(args: argparse.Namespace) -> None:
    """Search the pack — FTS5 with optional vector rerank."""
    conn = sqlite3.connect(args.pack)

    # Step 1: FTS5 search
    sql = """
        SELECT c.id, c.source, c.data, c.text,
               highlight(fts_chunks, 0, '>>>', '<<<') AS snippet
        FROM fts_chunks f
        JOIN chunks c ON c.id = f.rowid
        WHERE fts_chunks MATCH ?
    """
    params: list[Any] = [_sanitise_fts_query(args.search)]
    if args.layer:
        sql += " AND c.source = ?"
        params.append(args.layer)

    fts_limit = args.limit * 5 if args.vector else args.limit
    sql += f" LIMIT {fts_limit}"

    fts_rows = conn.execute(sql, params).fetchall()

    if not fts_rows:
        print("No results found.")
        conn.close()
        return

    # Step 2: Optional vector rerank
    if args.vector:
        meta = dict(conn.execute("SELECT key, value FROM pack_metadata").fetchall())
        if meta.get("has_vectors") != "true":
            print("Warning: no vectors in pack, falling back to FTS-only results.", file=sys.stderr)
            args.vector = False
        else:
            # Load query vector from file
            query_vec = None
            if args.query_vector_file:
                with open(args.query_vector_file) as f:
                    query_vec = json.load(f)

            if query_vec:
                # Score each FTS result by cosine similarity
                scored = []
                chunk_ids = [row[0] for row in fts_rows]
                placeholders = ",".join("?" * len(chunk_ids))
                vec_rows = conn.execute(
                    f"SELECT chunk_id, vector FROM chunk_vectors WHERE chunk_id IN ({placeholders})",
                    chunk_ids,
                ).fetchall()
                vec_map = {cid: _blob_to_vector(blob) for cid, blob in vec_rows}

                for row in fts_rows:
                    cid = row[0]
                    vec = vec_map.get(cid)
                    sim = _cosine_similarity(query_vec, vec) if vec else 0.0
                    scored.append((sim, row))

                scored.sort(key=lambda x: x[0], reverse=True)
                fts_rows = [row for _, row in scored[:args.limit]]
            else:
                print("Warning: no query vector provided for rerank, using FTS-only.", file=sys.stderr)
                fts_rows = fts_rows[:args.limit]
    else:
        fts_rows = fts_rows[:args.limit]

    results = []
    for row in fts_rows:
        cid, source, data_json, text, snippet = row
        try:
            data = json.loads(data_json) if data_json else {}
        except json.JSONDecodeError:
            data = {"raw": data_json}
        results.append({"chunk_id": cid, "layer": source, "data": data, "snippet": snippet})

    conn.close()
    print(json.dumps(results, indent=2, ensure_ascii=False))


def cmd_geo_query(args: argparse.Namespace) -> None:
    """Query geo points within a bounding box."""
    conn = sqlite3.connect(args.pack)

    sql = """
        SELECT g.name, g.name_local, g.lat, g.lon, g.category, g.layer,
               g.address, g.metadata, c.data
        FROM geo_points g
        LEFT JOIN chunks c ON c.id = g.chunk_id
        WHERE g.lat BETWEEN ? AND ? AND g.lon BETWEEN ? AND ?
    """
    params: list[Any] = [args.south, args.north, args.west, args.east]
    if args.layer:
        sql += " AND g.layer = ?"
        params.append(args.layer)
    if args.category:
        sql += " AND g.category = ?"
        params.append(args.category)
    sql += f" LIMIT {args.limit}"

    rows = conn.execute(sql, params).fetchall()
    conn.close()

    results = []
    for name, name_local, lat, lon, category, layer, address, metadata_json, data_json in rows:
        entry: dict[str, Any] = {
            "name": name, "lat": lat, "lon": lon, "category": category, "layer": layer
        }
        if name_local:
            entry["name_local"] = name_local
        if address:
            entry["address"] = address
        if metadata_json:
            try:
                entry["metadata"] = json.loads(metadata_json)
            except json.JSONDecodeError:
                pass
        if data_json:
            try:
                entry["data"] = json.loads(data_json)
            except json.JSONDecodeError:
                pass
        results.append(entry)

    print(json.dumps(results, indent=2, ensure_ascii=False))


def cmd_build(args: argparse.Namespace) -> None:
    """Build a complete pack from a manifest file."""
    with open(args.manifest, "r", encoding="utf-8") as f:
        manifest = json.load(f)

    output = args.output or f"./output/{manifest['name']}.db"

    init_args = argparse.Namespace(
        output=output,
        name=manifest["name"],
        version=manifest.get("version", "1.0.0"),
        country=manifest.get("country", ""),
        scenario=manifest.get("scenario", ""),
        force=args.force,
    )
    cmd_init(init_args)

    for layer in manifest.get("layers", []):
        source = layer.get("source", {})
        source_type = source.get("type", "")

        provenance = {
            "publisher": layer.get("publisher"),
            "license": layer.get("license"),
            "source_url": layer.get("source_url"),
            "reviewed_at": layer.get("reviewed_at"),
            "cultural_sensitivity": layer.get("cultural_sensitivity"),
            "expires_at": layer.get("expires_at"),
            "language": layer.get("language"),
        }

        if source_type == "file":
            layer_args = argparse.Namespace(
                pack=output, name=layer["name"],
                tier=layer.get("tier", "static_reference"),
                file=source["path"], format=source.get("format", "json"),
                description=layer.get("description", ""),
                section=layer.get("section", ""),
                from_stdin=False,
                **provenance,
            )
            cmd_add_layer(layer_args)

        elif source_type == "inline":
            inline_data = source.get("data", [])
            if inline_data:
                old_stdin = sys.stdin
                try:
                    sys.stdin = io.TextIOWrapper(
                        io.BytesIO(json.dumps(inline_data).encode("utf-8")),
                        encoding="utf-8",
                    )
                    layer_args = argparse.Namespace(
                        pack=output, name=layer["name"],
                        tier=layer.get("tier", "static_reference"),
                        file=None, format="json",
                        description=layer.get("description", ""),
                        section=layer.get("section", ""),
                        from_stdin=True,
                        **provenance,
                    )
                    cmd_add_layer(layer_args)
                finally:
                    sys.stdin = old_stdin

        elif source_type in ("mcp", "url", "scrape"):
            print(
                f"Skipping layer '{layer['name']}' — source type '{source_type}' "
                "requires agent resolution. Save data as a file first.",
                file=sys.stderr,
            )
            continue
        else:
            print(f"Skipping layer '{layer['name']}' — unknown source type '{source_type}'", file=sys.stderr)
            continue

        # Add geo points if specified
        geo = layer.get("geo_fields")
        if geo:
            fields = geo if isinstance(geo, dict) else {}
            if isinstance(geo, str):
                parts = [part.strip() for part in geo.split(",")]
                if len(parts) < 2 or not parts[0] or not parts[1]:
                    raise ValueError("geo_fields string must include lat_field and lon_field")
                fields = {"lat_field": parts[0], "lon_field": parts[1]}
                if len(parts) > 2:
                    fields["name_field"] = parts[2]

            geo_args = argparse.Namespace(
                pack=output, layer=layer["name"],
                lat_field=fields.get("lat_field", "lat"),
                lon_field=fields.get("lon_field", "lon"),
                name_field=fields.get("name_field", "name"),
                name_local_field=fields.get("name_local_field"),
                category=fields.get("category", layer["name"]),
            )
            cmd_add_geo(geo_args)

    # Build FTS index
    cmd_build_index(argparse.Namespace(pack=output))

    if getattr(args, "archive", False):
        cmd_archive(argparse.Namespace(pack=output, output=None, force=args.force))

    # Final info
    cmd_info(argparse.Namespace(pack=output))


def cmd_archive(args: argparse.Namespace) -> None:
    """Package a built .db into an OfflineAid transport archive."""
    try:
        output = archive_pack(
            pack_path=args.pack,
            output=args.output,
            force=args.force,
        )
    except (FileNotFoundError, FileExistsError, ValueError) as exc:
        print(f"Error: {exc}", file=sys.stderr)
        sys.exit(1)

    print(f"Archived pack: {output}")


def cmd_verify(args: argparse.Namespace) -> None:
    """Verify an OfflineAid archive's structural and cryptographic integrity."""
    try:
        manifest = verify_pack_archive(args.archive)
    except (FileNotFoundError, ValueError) as exc:
        print(f"FAIL  {exc}", file=sys.stderr)
        sys.exit(1)

    print(f"OK    {args.archive}")
    print(f"      pack:     {manifest['pack_name']} v{manifest['pack_version']}")
    print(f"      db:       {manifest['db_filename']}")
    print(f"      sha256:   {manifest['db_sha256']}")
    print(f"      format:   {manifest['format_version']}")
    print(f"      builder:  {manifest['builder_version']}")
    print(f"      created:  {manifest['created_at']}")


# ── CLI ───────────────────────────────────────────────────────────────


def main() -> None:
    parser = argparse.ArgumentParser(
        description="Offline knowledge pack builder — SQLite FTS5 + optional corpus-derived vectors",
        formatter_class=argparse.RawDescriptionHelpFormatter,
    )
    sub = parser.add_subparsers(dest="command", required=True)

    # init
    p = sub.add_parser("init", help="Initialize a new pack database")
    p.add_argument("--output", "-o", required=True, help="Output .db file path")
    p.add_argument("--name", "-n", required=True, help="Pack name")
    p.add_argument("--version", "-v", default="1.0.0", help="Pack version")
    p.add_argument("--country", "-c", help="Country code (e.g. AU, US, GB)")
    p.add_argument("--scenario", "-s", help="Scenario description")
    p.add_argument("--force", "-f", action="store_true", help="Overwrite existing")

    # add-layer
    p = sub.add_parser("add-layer", help="Add a data layer to the pack")
    p.add_argument("--pack", "-p", required=True, help="Pack .db file")
    p.add_argument("--name", "-n", required=True, help="Layer name")
    p.add_argument("--tier", "-t", required=True, choices=VALID_TIERS, help="Data tier")
    p.add_argument("--file", help="Input data file (JSON or CSV)")
    p.add_argument("--format", choices=["json", "csv", "geojson"], help="File format")
    p.add_argument("--description", "-d", default="", help="Layer description")
    p.add_argument("--section", default="", help="Sub-section within layer")
    p.add_argument("--from-stdin", action="store_true", help="Read data from stdin")
    # Provenance (all optional; written to layers.* for the nutrition-label UI)
    p.add_argument("--publisher", help="Source publisher (e.g. ACCC, NASC)")
    p.add_argument("--license", help="Source licence id (e.g. CC-BY-4.0-AU)")
    p.add_argument("--source-url", help="Canonical URL of the upstream source")
    p.add_argument("--reviewed-at", help="ISO-8601 UTC timestamp of last human review")
    p.add_argument("--cultural-sensitivity", help="Free-text sensitivity flag")
    p.add_argument("--expires-at", help="ISO-8601 UTC timestamp after which the data is stale")
    p.add_argument("--language", help="BCP-47 language tag of the source content")

    # add-geo
    p = sub.add_parser("add-geo", help="Extract geo points from a layer")
    p.add_argument("--pack", "-p", required=True, help="Pack .db file")
    p.add_argument("--layer", "-l", required=True, help="Layer name")
    p.add_argument("--lat-field", required=True, help="Latitude field name")
    p.add_argument("--lon-field", required=True, help="Longitude field name")
    p.add_argument("--name-field", default="name", help="Name field (default: name)")
    p.add_argument("--name-local-field", help="Local language name field")
    p.add_argument("--category", help="POI category (default: layer name)")

    # vectorise
    p = sub.add_parser("vectorise", help="Generate corpus-derived vectors for chunks")
    p.add_argument("--pack", "-p", required=True, help="Pack .db file")
    p.add_argument("--method", "-m", default="lsa", choices=["lsa", "tfidf", "file"],
                   help="Vector method: lsa/tfidf (corpus-derived, zero deps) or file (pre-computed)")
    p.add_argument("--dimensions", "-d", type=int, default=64, help="Vector dimensions (for lsa/tfidf)")
    p.add_argument("--file", help="Pre-computed vectors JSON file (for --method file)")
    p.add_argument("--method-name", help="Method label for metadata (auto-detected)")

    # build-index
    p = sub.add_parser("build-index", help="Rebuild FTS5 search index")
    p.add_argument("--pack", "-p", required=True, help="Pack .db file")

    # info
    p = sub.add_parser("info", help="Show pack metadata and statistics")
    p.add_argument("--pack", "-p", required=True, help="Pack .db file")

    # query
    p = sub.add_parser("query", help="Search the pack (FTS5 + optional vector rerank)")
    p.add_argument("--pack", "-p", required=True, help="Pack .db file")
    p.add_argument("--search", "-s", required=True, help="Search query")
    p.add_argument("--layer", "-l", help="Filter by layer name")
    p.add_argument("--limit", type=int, default=10, help="Max results")
    p.add_argument("--vector", action="store_true", help="Use vector rerank if chunk_vectors available")
    p.add_argument("--query-vector-file", help="Pre-computed query vector JSON file")

    # geo-query
    p = sub.add_parser("geo-query", help="Query geo points in a bounding box")
    p.add_argument("--pack", "-p", required=True, help="Pack .db file")
    p.add_argument("--south", type=float, required=True)
    p.add_argument("--north", type=float, required=True)
    p.add_argument("--west", type=float, required=True)
    p.add_argument("--east", type=float, required=True)
    p.add_argument("--layer", "-l", help="Filter by layer")
    p.add_argument("--category", help="Filter by POI category")
    p.add_argument("--limit", type=int, default=50, help="Max results")

    # build
    p = sub.add_parser("build", help="Build pack from a manifest file")
    p.add_argument("--manifest", "-m", required=True, help="Manifest JSON file")
    p.add_argument("--output", "-o", help="Output .db file")
    p.add_argument("--archive", action="store_true", help="Also emit a .oapack.zip archive")
    p.add_argument("--force", "-f", action="store_true", help="Overwrite existing")

    # archive
    p = sub.add_parser("archive", help="Package an existing .db as a .oapack.zip archive")
    p.add_argument("--pack", "-p", required=True, help="Pack .db file")
    p.add_argument("--output", "-o", help="Output .oapack.zip file")
    p.add_argument("--force", "-f", action="store_true", help="Overwrite existing")

    p = sub.add_parser("verify", help="Verify structural and cryptographic integrity of a .oapack.zip")
    p.add_argument("archive", help="Archive file to verify")

    args = parser.parse_args()
    commands = {
        "init": cmd_init, "add-layer": cmd_add_layer, "add-geo": cmd_add_geo,
        "vectorise": cmd_vectorise, "build-index": cmd_build_index, "info": cmd_info,
        "query": cmd_query, "geo-query": cmd_geo_query, "build": cmd_build,
        "archive": cmd_archive, "verify": cmd_verify,
    }
    commands[args.command](args)


if __name__ == "__main__":
    main()