spolvero 0.3.0__py3-none-any.whl

spolvero/templates/LICENSE.txt

@@ -0,0 +1,42 @@
+Bundled template: minimal_flowchart.vsdx
+=========================================
+
+This file is derived from the test fixture `media/media.vsdx` shipped with the
+`vsdx` Python library (https://github.com/dave-howard/vsdx), which is
+distributed under the BSD 3-Clause License. We re-distribute it here under the
+same terms as a stamp template for the `vsdx-template` engine.
+
+Original copyright:
+
+    BSD 3-Clause License
+
+    Copyright (c) 2020, Dave Howard
+    All rights reserved.
+
+    Redistribution and use in source and binary forms, with or without
+    modification, are permitted provided that the following conditions are met:
+
+    1. Redistributions of source code must retain the above copyright notice,
+       this list of conditions and the following disclaimer.
+
+    2. Redistributions in binary form must reproduce the above copyright
+       notice, this list of conditions and the following disclaimer in the
+       documentation and/or other materials provided with the distribution.
+
+    3. Neither the name of the copyright holder nor the names of its
+       contributors may be used to endorse or promote products derived from
+       this software without specific prior written permission.
+
+    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+    AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+    IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+    ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+    LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+    CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+    SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+    INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+    CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+    ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+    POSSIBILITY OF SUCH DAMAGE.
+
+Users may supply their own template via the CLI flag `--template PATH`.

spolvero/topology/__init__.py

@@ -0,0 +1,27 @@
+"""Topology IR for network diagrams and Technical Reference Diagrams (TRDs).
+
+Public surface:
+
+- :func:`parse_topology` — turn a raw YAML/JSON topology source into the IR.
+- :func:`is_topology_ir` — discriminator used by builder/render dispatch.
+- :data:`STENCIL_MAP` — kind → display label + glyph used by previews and
+  workbooks. Unknown kinds degrade to ``"generic"`` with a warning.
+"""
+
+from __future__ import annotations
+
+from .model import (
+    STENCIL_MAP,
+    SUPPORTED_NODE_KINDS,
+    SUPPORTED_CONTAINER_KINDS,
+    is_topology_ir,
+    parse_topology,
+)
+
+__all__ = [
+    "STENCIL_MAP",
+    "SUPPORTED_NODE_KINDS",
+    "SUPPORTED_CONTAINER_KINDS",
+    "is_topology_ir",
+    "parse_topology",
+]

spolvero/topology/model.py

@@ -0,0 +1,275 @@
+"""Topology IR data model, source parsing, and stencil taxonomy."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from typing import Any
+
+from spolvero.constants import SCHEMA_VERSION
+from spolvero.models import DiagramSource
+
+# Glyphs are geometric primitives recognized by the topology preview renderer.
+_GLYPH_RECT = "rect"
+_GLYPH_ROUNDED = "rounded"
+_GLYPH_DIAMOND = "diamond"
+_GLYPH_CYLINDER = "cylinder"
+_GLYPH_CLOUD = "cloud"
+_GLYPH_CIRCLE = "circle"
+
+# kind -> {label (Visio "Shape Type" / workbook), glyph (preview)}
+STENCIL_MAP: dict[str, dict[str, str]] = {
+    "router": {"label": "Router", "glyph": _GLYPH_ROUNDED},
+    "switch": {"label": "Switch", "glyph": _GLYPH_RECT},
+    "firewall": {"label": "Firewall", "glyph": _GLYPH_DIAMOND},
+    "load_balancer": {"label": "Load Balancer", "glyph": _GLYPH_DIAMOND},
+    "server": {"label": "Server", "glyph": _GLYPH_RECT},
+    "database": {"label": "Database", "glyph": _GLYPH_CYLINDER},
+    "storage": {"label": "Storage", "glyph": _GLYPH_CYLINDER},
+    "client": {"label": "Client", "glyph": _GLYPH_RECT},
+    "cloud": {"label": "Cloud", "glyph": _GLYPH_CLOUD},
+    "internet": {"label": "Internet", "glyph": _GLYPH_CLOUD},
+    "application": {"label": "Application", "glyph": _GLYPH_RECT},
+    "service": {"label": "Service", "glyph": _GLYPH_ROUNDED},
+    "actor": {"label": "Actor", "glyph": _GLYPH_CIRCLE},
+    "datastore": {"label": "Data Store", "glyph": _GLYPH_CYLINDER},
+    "external_system": {"label": "External System", "glyph": _GLYPH_ROUNDED},
+    "generic": {"label": "Process", "glyph": _GLYPH_RECT},
+}
+
+SUPPORTED_NODE_KINDS = frozenset(STENCIL_MAP.keys())
+SUPPORTED_CONTAINER_KINDS = frozenset(
+    {"subnet", "zone", "region", "environment", "vpc", "system", "boundary"}
+)
+
+
+def is_topology_ir(ir: dict[str, Any]) -> bool:
+    return ir.get("diagram_type") == "topology"
+
+
+def parse_topology(diagram: DiagramSource) -> dict[str, Any]:
+    """Parse a topology source (YAML or JSON) into the topology IR.
+
+    YAML support requires PyYAML (the ``[topology]`` extra). JSON sources work
+    with the stdlib alone.
+    """
+
+    raw_text = diagram.text
+    fmt = (diagram.source_type or "").rsplit(".", 1)[-1].lower()
+    warnings: list[str] = list(diagram.warnings)
+
+    data, parse_warning = _load_source(raw_text, fmt)
+    if parse_warning:
+        warnings.append(parse_warning)
+    if not isinstance(data, dict):
+        warnings.append("Topology source did not parse to a mapping; producing empty IR.")
+        return _empty_ir(diagram, warnings)
+
+    nodes_raw = _list_or_empty(data.get("nodes"), "nodes", warnings)
+    edges_raw = _list_or_empty(data.get("edges"), "edges", warnings)
+    containers_raw = _list_or_empty(data.get("containers"), "containers", warnings)
+
+    nodes: list[dict[str, Any]] = []
+    seen_ids: set[str] = set()
+    explicit_node_containers: set[str] = set()
+    for index, raw in enumerate(nodes_raw, start=1):
+        if not isinstance(raw, dict):
+            warnings.append(f"Node #{index} is not a mapping; skipped.")
+            continue
+        nid = _str_or_none(raw.get("id")) or f"N{index:03d}"
+        if nid in seen_ids:
+            warnings.append(f"Duplicate node id '{nid}' at position {index}; skipped.")
+            continue
+        seen_ids.add(nid)
+        kind = str(raw.get("kind") or "generic").strip().lower()
+        if kind not in SUPPORTED_NODE_KINDS:
+            warnings.append(f"Unknown node kind '{kind}' for '{nid}'; mapped to 'generic'.")
+            kind = "generic"
+        container = _str_or_none(raw.get("container"))
+        if container:
+            explicit_node_containers.add(nid)
+        nodes.append(
+            {
+                "id": nid,
+                "label": str(raw.get("label") or nid),
+                "kind": kind,
+                "container": container,
+                "metadata": _metadata_or_empty(raw.get("metadata"), f"Node '{nid}'", warnings),
+            }
+        )
+    node_by_id = {node["id"]: node for node in nodes}
+
+    edges: list[dict[str, Any]] = []
+    for index, raw in enumerate(edges_raw, start=1):
+        if not isinstance(raw, dict):
+            warnings.append(f"Edge #{index} is not a mapping; skipped.")
+            continue
+        src = str(raw.get("from") or "").strip()
+        dst = str(raw.get("to") or "").strip()
+        eid = str(raw.get("id") or f"E{index:03d}")
+        if not src or not dst:
+            warnings.append(f"Edge #{index} missing from/to; skipped.")
+            continue
+        if src not in seen_ids:
+            warnings.append(f"Edge {index} source '{src}' not declared as a node; skipped.")
+            continue
+        if dst not in seen_ids:
+            warnings.append(f"Edge {index} target '{dst}' not declared as a node; skipped.")
+            continue
+        edges.append(
+            {
+                "id": eid,
+                "from": src,
+                "to": dst,
+                "label": str(raw.get("label") or ""),
+                "kind": str(raw.get("kind") or "link"),
+                "metadata": _metadata_or_empty(raw.get("metadata"), f"Edge '{eid}'", warnings),
+            }
+        )
+
+    containers: list[dict[str, Any]] = []
+    seen_container_ids: set[str] = set()
+    member_assignments: dict[str, str] = {}
+    for index, raw in enumerate(containers_raw, start=1):
+        if not isinstance(raw, dict):
+            warnings.append(f"Container #{index} is not a mapping; skipped.")
+            continue
+        cid = _str_or_none(raw.get("id")) or f"C{index:03d}"
+        if cid in seen_container_ids:
+            warnings.append(f"Duplicate container id '{cid}' at position {index}; skipped.")
+            continue
+        seen_container_ids.add(cid)
+        kind = str(raw.get("kind") or "zone").strip().lower()
+        if kind not in SUPPORTED_CONTAINER_KINDS:
+            warnings.append(f"Unknown container kind '{kind}' for '{cid}'; rendered as zone.")
+            kind = "zone"
+        for member_id in _member_ids(raw.get("members"), cid, warnings):
+            node = node_by_id.get(member_id)
+            if node is None:
+                warnings.append(f"Container '{cid}' members[] references unknown node id '{member_id}'; skipped.")
+                continue
+            node_container = node.get("container")
+            if member_id in explicit_node_containers and node_container:
+                if node_container != cid:
+                    warnings.append(
+                        f"Node '{member_id}' already declares container '{node_container}'; "
+                        f"container '{cid}' members[] assignment ignored."
+                    )
+                continue
+            previous = member_assignments.get(member_id)
+            if previous and previous != cid:
+                warnings.append(
+                    f"Node '{member_id}' is listed in containers '{previous}' and '{cid}'; "
+                    f"keeping '{previous}'."
+                )
+                continue
+            member_assignments[member_id] = cid
+            node["container"] = cid
+        containers.append(
+            {
+                "id": cid,
+                "label": str(raw.get("label") or cid),
+                "kind": kind,
+                "parent": _str_or_none(raw.get("parent")),
+            }
+        )
+
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "id": diagram.id,
+        "title": str(data.get("title") or diagram.title),
+        "diagram_type": "topology",
+        "orientation": str(data.get("orientation") or "left_to_right"),
+        "pages": [{"id": "page-001", "title": diagram.title, "size": "Letter Landscape"}],
+        "nodes": nodes,
+        "edges": edges,
+        "containers": containers,
+        "warnings": list(dict.fromkeys(warnings)),
+    }
+
+
+def _load_source(text: str, fmt: str) -> tuple[Any, str | None]:
+    """Try JSON first, then YAML (gated on PyYAML)."""
+
+    text = text.strip()
+    if not text:
+        return None, "Topology source is empty."
+
+    if fmt == "json" or text.startswith("{"):
+        try:
+            return json.loads(text), None
+        except json.JSONDecodeError as exc:
+            if fmt == "json":
+                return None, f"Topology JSON parse error: {exc}"
+
+    try:
+        import yaml  # type: ignore[import-not-found]
+    except ImportError:
+        return None, (
+            "Topology YAML detected but PyYAML is not installed. Install with: "
+            "pip install 'spolvero[topology]'."
+        )
+    try:
+        return yaml.safe_load(text), None
+    except yaml.YAMLError as exc:  # pragma: no cover - thin wrapper
+        return None, f"Topology YAML parse error: {exc}"
+
+
+def _str_or_none(value: Any) -> str | None:
+    if value is None:
+        return None
+    text = str(value).strip()
+    return text or None
+
+
+def _list_or_empty(value: Any, field: str, warnings: list[str]) -> list[Any]:
+    if value is None:
+        return []
+    if isinstance(value, list):
+        return value
+    warnings.append(f"Topology field '{field}' must be a list; skipped.")
+    return []
+
+
+def _metadata_or_empty(value: Any, owner: str, warnings: list[str]) -> dict[str, Any]:
+    if value is None:
+        return {}
+    if isinstance(value, Mapping):
+        return dict(value)
+    warnings.append(f"{owner} metadata must be a mapping; using empty metadata.")
+    return {}
+
+
+def _member_ids(value: Any, container_id: str, warnings: list[str]) -> list[str]:
+    if value is None:
+        return []
+    if not isinstance(value, list):
+        warnings.append(f"Container '{container_id}' members must be a list of node ids; ignored.")
+        return []
+    members: list[str] = []
+    seen: set[str] = set()
+    for index, raw in enumerate(value, start=1):
+        member_id = _str_or_none(raw)
+        if member_id is None:
+            warnings.append(f"Container '{container_id}' member #{index} is blank; skipped.")
+            continue
+        if member_id in seen:
+            continue
+        seen.add(member_id)
+        members.append(member_id)
+    return members
+
+
+def _empty_ir(diagram: DiagramSource, warnings: list[str]) -> dict[str, Any]:
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "id": diagram.id,
+        "title": diagram.title,
+        "diagram_type": "topology",
+        "orientation": "left_to_right",
+        "pages": [{"id": "page-001", "title": diagram.title, "size": "Letter Landscape"}],
+        "nodes": [],
+        "edges": [],
+        "containers": [],
+        "warnings": list(dict.fromkeys(warnings)),
+    }

spolvero/utils.py

@@ -0,0 +1,57 @@
+"""Small IO and formatting helpers."""
+
+from __future__ import annotations
+
+import datetime as dt
+import html
+import json
+import textwrap
+from pathlib import Path
+from typing import Any
+
+
+def write_json(path: Path, data: Any) -> None:
+    path.write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+
+
+def write_text(path: Path, content: str) -> None:
+    path.write_text(content, encoding="utf-8", newline="\n")
+
+
+def rel(path: Path | None, root: Path) -> str | None:
+    if path is None:
+        return None
+    return path.resolve().relative_to(root.resolve()).as_posix()
+
+
+def escape(value: Any) -> str:
+    return html.escape(str(value), quote=False)
+
+
+def escape_attr(value: Any) -> str:
+    return html.escape(str(value), quote=True)
+
+
+def wrap_label(label: str, width: int = 18) -> list[str]:
+    lines: list[str] = []
+    for raw in str(label).splitlines() or [""]:
+        wrapped = textwrap.wrap(raw, width=width) or [raw]
+        lines.extend(wrapped)
+    return lines[:4] or [""]
+
+
+def column_name(index: int) -> str:
+    name = ""
+    while index:
+        index, remainder = divmod(index - 1, 26)
+        name = chr(65 + remainder) + name
+    return name
+
+
+def backup_if_manual_candidate(path: Path) -> None:
+    if not path.exists():
+        return
+    stamp = dt.datetime.now().strftime("%Y%m%d-%H%M%S")
+    backup = path.with_name(f"{path.stem}.bak-{stamp}{path.suffix}")
+    path.replace(backup)
+

spolvero/workbook.py

@@ -0,0 +1,200 @@
+"""Minimal XLSX writer for Visio Data Visualizer tables."""
+
+from __future__ import annotations
+
+import datetime as dt
+import zipfile
+from pathlib import Path
+from typing import Any
+
+from spolvero.constants import DATA_VIS_HEADERS, SHAPE_TYPE_MAP, SKILL_ID
+from spolvero.utils import column_name, escape, escape_attr
+
+
+def write_data_visualizer_workbook(path: Path, ir: dict[str, Any]) -> None:
+    rows = data_visualizer_rows(ir)
+    write_xlsx_table(path, "Process Map", DATA_VIS_HEADERS, rows, "ProcessMap")
+
+
+def data_visualizer_rows(ir: dict[str, Any]) -> list[list[str]]:
+    outgoing: dict[str, list[dict[str, Any]]] = {}
+    for edge in ir.get("edges", []):
+        outgoing.setdefault(edge["from"], []).append(edge)
+
+    container_labels: dict[str, str] = {
+        container["id"]: container.get("label", container["id"])
+        for container in ir.get("containers", [])
+    }
+
+    is_topology = ir.get("diagram_type") == "topology"
+    if is_topology:
+        from spolvero.topology import STENCIL_MAP
+
+    # Visio Data Visualizer requires `Process Step ID` to be unique. For
+    # branching nodes, fan-out must be expressed as comma-separated values in
+    # the `Next Step ID` and `Connector Label` columns.
+    rows: list[list[str]] = []
+    for node in ir.get("nodes", []):
+        node_edges = outgoing.get(node["id"], [])
+        next_ids = ",".join(edge.get("to", "") for edge in node_edges)
+        connector_labels = ",".join(edge.get("label", "") for edge in node_edges)
+        metadata = node.get("metadata", {})
+        container_id = node.get("container", "") or ""
+        function = container_labels.get(container_id, container_id)
+        phase = metadata.get("phase") or (function if is_topology else "")
+        if is_topology:
+            kind = node.get("kind", "generic")
+            shape_type = STENCIL_MAP.get(kind, STENCIL_MAP["generic"])["label"]
+        else:
+            shape_type = SHAPE_TYPE_MAP.get(node.get("shape_kind", "process"), "Process")
+        rows.append(
+            [
+                node["id"],
+                node.get("label", node["id"]),
+                next_ids,
+                connector_labels,
+                shape_type,
+                function,
+                phase,
+                metadata.get("system", ""),
+                metadata.get("owner", ""),
+                metadata.get("criticality", ""),
+                metadata.get("source_ref", ""),
+            ]
+        )
+    return rows
+
+
+def write_xlsx_table(path: Path, sheet_name: str, headers: list[str], rows: list[list[str]], table_name: str) -> None:
+    ref = f"A1:{column_name(len(headers))}{len(rows) + 1}"
+    now = dt.datetime.now(dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    sheet_rows = [headers] + rows
+
+    with zipfile.ZipFile(path, "w", zipfile.ZIP_DEFLATED) as zf:
+        zf.writestr("[Content_Types].xml", content_types_xml())
+        zf.writestr("_rels/.rels", root_rels_xml())
+        zf.writestr("docProps/core.xml", core_props_xml(now))
+        zf.writestr("docProps/app.xml", app_props_xml())
+        zf.writestr("xl/workbook.xml", workbook_xml(sheet_name))
+        zf.writestr("xl/_rels/workbook.xml.rels", workbook_rels_xml())
+        zf.writestr("xl/styles.xml", styles_xml())
+        zf.writestr("xl/worksheets/sheet1.xml", sheet_xml(sheet_rows, ref))
+        zf.writestr("xl/worksheets/_rels/sheet1.xml.rels", sheet_rels_xml())
+        zf.writestr("xl/tables/table1.xml", table_xml(table_name, ref, headers))
+
+
+def content_types_xml() -> str:
+    return """<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">
+  <Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>
+  <Default Extension="xml" ContentType="application/xml"/>
+  <Override PartName="/docProps/core.xml" ContentType="application/vnd.openxmlformats-package.core-properties+xml"/>
+  <Override PartName="/docProps/app.xml" ContentType="application/vnd.openxmlformats-officedocument.extended-properties+xml"/>
+  <Override PartName="/xl/workbook.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml"/>
+  <Override PartName="/xl/worksheets/sheet1.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml"/>
+  <Override PartName="/xl/styles.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.styles+xml"/>
+  <Override PartName="/xl/tables/table1.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.table+xml"/>
+</Types>
+"""
+
+
+def root_rels_xml() -> str:
+    return """<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
+  <Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="xl/workbook.xml"/>
+  <Relationship Id="rId2" Type="http://schemas.openxmlformats.org/package/2006/relationships/metadata/core-properties" Target="docProps/core.xml"/>
+  <Relationship Id="rId3" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/extended-properties" Target="docProps/app.xml"/>
+</Relationships>
+"""
+
+
+def workbook_xml(sheet_name: str) -> str:
+    return f"""<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<workbook xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships">
+  <sheets>
+    <sheet name="{escape_attr(sheet_name)}" sheetId="1" r:id="rId1"/>
+  </sheets>
+</workbook>
+"""
+
+
+def workbook_rels_xml() -> str:
+    return """<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
+  <Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet" Target="worksheets/sheet1.xml"/>
+  <Relationship Id="rId2" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles" Target="styles.xml"/>
+</Relationships>
+"""
+
+
+def sheet_rels_xml() -> str:
+    return """<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
+  <Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/table" Target="../tables/table1.xml"/>
+</Relationships>
+"""
+
+
+def styles_xml() -> str:
+    return """<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<styleSheet xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main">
+  <fonts count="1"><font><sz val="11"/><name val="Calibri"/></font></fonts>
+  <fills count="1"><fill><patternFill patternType="none"/></fill></fills>
+  <borders count="1"><border><left/><right/><top/><bottom/><diagonal/></border></borders>
+  <cellStyleXfs count="1"><xf numFmtId="0" fontId="0" fillId="0" borderId="0"/></cellStyleXfs>
+  <cellXfs count="1"><xf numFmtId="0" fontId="0" fillId="0" borderId="0" xfId="0"/></cellXfs>
+  <cellStyles count="1"><cellStyle name="Normal" xfId="0" builtinId="0"/></cellStyles>
+</styleSheet>
+"""
+
+
+def sheet_xml(rows: list[list[str]], ref: str) -> str:
+    row_xml = []
+    for r_index, row in enumerate(rows, start=1):
+        cells = []
+        for c_index, value in enumerate(row, start=1):
+            cell_ref = f"{column_name(c_index)}{r_index}"
+            cells.append(f'<c r="{cell_ref}" t="inlineStr"><is><t>{escape(value)}</t></is></c>')
+        row_xml.append(f'<row r="{r_index}">' + "".join(cells) + "</row>")
+    return f"""<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<worksheet xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships">
+  <dimension ref="{ref}"/>
+  <sheetViews><sheetView workbookViewId="0"/></sheetViews>
+  <sheetFormatPr defaultRowHeight="15"/>
+  <sheetData>{''.join(row_xml)}</sheetData>
+  <tableParts count="1"><tablePart r:id="rId1"/></tableParts>
+</worksheet>
+"""
+
+
+def table_xml(table_name: str, ref: str, headers: list[str]) -> str:
+    columns = "".join(
+        f'<tableColumn id="{index}" name="{escape_attr(header)}"/>' for index, header in enumerate(headers, start=1)
+    )
+    return f"""<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<table xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main" id="1" name="{table_name}" displayName="{table_name}" ref="{ref}" totalsRowShown="0">
+  <autoFilter ref="{ref}"/>
+  <tableColumns count="{len(headers)}">{columns}</tableColumns>
+  <tableStyleInfo name="TableStyleMedium2" showFirstColumn="0" showLastColumn="0" showRowStripes="1" showColumnStripes="0"/>
+</table>
+"""
+
+
+def core_props_xml(now: str) -> str:
+    return f"""<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<cp:coreProperties xmlns:cp="http://schemas.openxmlformats.org/package/2006/metadata/core-properties" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:dcterms="http://purl.org/dc/terms/" xmlns:dcmitype="http://purl.org/dc/dcmitype/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+  <dc:creator>{SKILL_ID}</dc:creator>
+  <cp:lastModifiedBy>{SKILL_ID}</cp:lastModifiedBy>
+  <dcterms:created xsi:type="dcterms:W3CDTF">{now}</dcterms:created>
+  <dcterms:modified xsi:type="dcterms:W3CDTF">{now}</dcterms:modified>
+</cp:coreProperties>
+"""
+
+
+def app_props_xml() -> str:
+    return """<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<Properties xmlns="http://schemas.openxmlformats.org/officeDocument/2006/extended-properties" xmlns:vt="http://schemas.openxmlformats.org/officeDocument/2006/docPropsVTypes">
+  <Application>Spolvero</Application>
+</Properties>
+"""
+