pptx-cli 1.0.0__py3-none-any.whl

pptx_cli/commands/inspect.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from pptx_cli.core.manifest_store import load_annotations, load_manifest
+from pptx_cli.core.validation import ValidationError
+
+
+def doctor(manifest_dir: Path) -> dict[str, Any]:
+    manifest = load_manifest(manifest_dir)
+    report = manifest.compatibility_report.model_dump(mode="json")
+    report["manifest"] = str(manifest_dir)
+    return report
+
+
+def list_layouts(manifest_dir: Path) -> dict[str, Any]:
+    manifest = load_manifest(manifest_dir)
+    annotations = load_annotations(manifest_dir)
+    annotations_by_layout = {item.layout_id: item for item in annotations.layouts}
+    return {
+        "manifest": str(manifest_dir),
+        "count": len(manifest.layouts),
+        "layouts": [
+            {
+                "id": layout.id,
+                "name": layout.name,
+                "aliases": (
+                    annotations_by_layout[layout.id].aliases
+                    if layout.id in annotations_by_layout
+                    else []
+                ),
+                "description": layout.description,
+                "preview_path": layout.preview_path,
+                "placeholder_count": len(layout.placeholders),
+                "source_layout_index": layout.source_layout_index,
+            }
+            for layout in manifest.layouts
+        ],
+    }
+
+
+def show_layout(manifest_dir: Path, layout_id: str) -> dict[str, Any]:
+    manifest = load_manifest(manifest_dir)
+    layout = next(
+        (item for item in manifest.layouts if item.id == layout_id or item.name == layout_id),
+        None,
+    )
+    if layout is None:
+        raise ValidationError("ERR_VALIDATION_LAYOUT_UNKNOWN", f"Unknown layout: {layout_id}")
+    return layout.model_dump(mode="json")
+
+
+def list_placeholders(manifest_dir: Path, layout_id: str) -> dict[str, Any]:
+    manifest = load_manifest(manifest_dir)
+    layout = next(
+        (item for item in manifest.layouts if item.id == layout_id or item.name == layout_id),
+        None,
+    )
+    if layout is None:
+        raise ValidationError("ERR_VALIDATION_LAYOUT_UNKNOWN", f"Unknown layout: {layout_id}")
+    return {
+        "layout_id": layout.id,
+        "layout_name": layout.name,
+        "placeholders": [item.model_dump(mode="json") for item in layout.placeholders],
+    }
+
+
+def show_theme(manifest_dir: Path) -> dict[str, Any]:
+    manifest = load_manifest(manifest_dir)
+    return manifest.presentation.get("theme", {})
+
+
+def list_assets(manifest_dir: Path) -> dict[str, Any]:
+    manifest = load_manifest(manifest_dir)
+    return {
+        "manifest": str(manifest_dir),
+        "count": len(manifest.assets),
+        "assets": [asset.model_dump(mode="json") for asset in manifest.assets],
+    }

pptx_cli/commands/manifest_ops.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from pptx_cli.core.manifest_store import load_manifest
+from pptx_cli.core.validation import diff_manifests
+from pptx_cli.models.manifest import ManifestDocument
+
+
+def manifest_diff(left_dir: Path, right_dir: Path) -> dict[str, Any]:
+    left = load_manifest(left_dir)
+    right = load_manifest(right_dir)
+    diff = diff_manifests(left, right)
+    return {
+        "left": str(left_dir),
+        "right": str(right_dir),
+        **diff.model_dump(mode="json"),
+    }
+
+
+def manifest_schema() -> dict[str, Any]:
+    return ManifestDocument.model_json_schema()

pptx_cli/commands/validate.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from pptx_cli.core.manifest_store import load_manifest
+from pptx_cli.core.validation import validate_deck
+
+
+def validate_command(manifest_dir: Path, deck_path: Path, *, strict: bool) -> dict[str, Any]:
+    manifest = load_manifest(manifest_dir)
+    result = validate_deck(manifest_dir, manifest, deck_path, strict=strict)
+    return result.model_dump(mode="json")

pptx_cli/commands/wrapper.py

@@ -0,0 +1,191 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from pptx_cli.core.ids import slugify
+from pptx_cli.core.io import atomic_write_text, ensure_directory
+from pptx_cli.core.manifest_store import load_manifest
+
+
+def wrapper_generate(manifest_dir: Path, output_dir: Path, *, dry_run: bool) -> dict[str, Any]:
+    manifest = load_manifest(manifest_dir)
+    package_name = f"{slugify(manifest.template.name).replace('-', '_')}_wrapper"
+    cli_name = f"{slugify(manifest.template.name)}-pptx"
+    files = {
+        output_dir / "pyproject.toml": _pyproject(package_name, cli_name),
+        output_dir / "README.md": _readme(cli_name),
+        output_dir
+        / "src"
+        / package_name
+        / "__init__.py": '"""Generated wrapper for pptx-cli."""\n',
+        output_dir / "src" / package_name / "cli.py": _cli_module(package_name),
+    }
+    changes = [
+        {
+            "target": str(path),
+            "operation": "replace" if path.exists() else "create",
+            "artifact_type": "python-source" if path.suffix == ".py" else "project-file",
+        }
+        for path in files
+    ]
+    if not dry_run:
+        for path, content in files.items():
+            ensure_directory(path.parent)
+            atomic_write_text(path, content)
+    return {
+        "dry_run": dry_run,
+        "manifest": str(manifest_dir),
+        "out": str(output_dir),
+        "package_name": package_name,
+        "cli_name": cli_name,
+        "changes": changes,
+        "summary": {"artifacts": len(files)},
+    }
+
+
+def _pyproject(package_name: str, cli_name: str) -> str:
+    distribution_name = package_name.replace("_", "-")
+    return (
+        "[build-system]\n"
+        'requires = ["hatchling>=1.27.0"]\n'
+        'build-backend = "hatchling.build"\n\n'
+        "[project]\n"
+        f'name = "{distribution_name}"\n'
+        'version = "0.1.0"\n'
+        'description = "Generated wrapper for pptx-cli"\n'
+        'requires-python = ">=3.12"\n'
+        'dependencies = ["pptx-cli>=0.1.0", "typer>=0.15.1"]\n\n'
+        "[project.scripts]\n"
+        f'{cli_name} = "{package_name}.cli:main"\n\n'
+        "[tool.hatch.build.targets.wheel]\n"
+        f'packages = ["src/{package_name}"]\n'
+    )
+
+
+def _readme(cli_name: str) -> str:
+    return (
+        f"# {cli_name}\n\n"
+        "Generated template wrapper for `pptx-cli`.\n\n"
+        "This wrapper delegates to the shared engine and expects a colocated manifest "
+        "package or a manually supplied path.\n"
+    )
+
+
+def _cli_module(package_name: str) -> str:
+    return (
+        "from __future__ import annotations\n\n"
+        "from pathlib import Path\n"
+        "from typing import Annotated\n\n"
+        "import typer\n\n"
+        "from pptx_cli.cli import emit_json\n"
+        "from pptx_cli.commands.compose import deck_build, slide_create\n"
+        "from pptx_cli.commands.inspect import list_layouts\n"
+        "from pptx_cli.commands.validate import validate_command\n"
+        "from pptx_cli.core.runtime import build_runtime_context\n"
+        "from pptx_cli.models.envelope import Envelope, Metrics\n\n"
+        'app = typer.Typer(help="Generated wrapper CLI for a specific manifest package.")\n\n'
+        "\n"
+        "def _default_manifest() -> Path:\n"
+        '    return Path(__file__).resolve().parents[2] / "manifest"\n\n'
+        "\n"
+        '@app.command("guide")\n'
+        "def guide() -> None:\n"
+        "    runtime = build_runtime_context()\n"
+        "    envelope = Envelope(\n"
+        "        request_id=runtime.request_id,\n"
+        "        ok=True,\n"
+        '        command="guide.show",\n'
+        "        result={\n"
+        '            "wrapper": True,\n'
+        '            "commands": [\n'
+        '                "layouts list",\n'
+        '                "slide create",\n'
+        '                "deck build",\n'
+        '                "validate",\n'
+        "            ],\n"
+        '            "manifest": str(_default_manifest()),\n'
+        "        },\n"
+        "        warnings=[],\n"
+        "        errors=[],\n"
+        "        metrics=Metrics(duration_ms=runtime.duration_ms),\n"
+        "    )\n"
+        "    emit_json(envelope)\n\n"
+        "\n"
+        '@app.command("layouts-list")\n'
+        "def layouts_list(\n"
+        '    manifest: Annotated[Path, typer.Option("--manifest")] = _default_manifest(),\n'
+        ") -> None:\n"
+        "    runtime = build_runtime_context()\n"
+        "    result = list_layouts(manifest)\n"
+        "    envelope = Envelope(\n"
+        "        request_id=runtime.request_id,\n"
+        "        ok=True,\n"
+        '        command="layouts.list",\n'
+        "        result=result,\n"
+        "        warnings=[],\n"
+        "        errors=[],\n"
+        "        metrics=Metrics(duration_ms=runtime.duration_ms),\n"
+        "    )\n"
+        "    emit_json(envelope)\n\n"
+        "\n"
+        '@app.command("slide-create")\n'
+        "def slide_create_command(\n"
+        '    layout: Annotated[str, typer.Option("--layout")],\n'
+        '    out: Annotated[Path, typer.Option("--out")],\n'
+        '    set_values: Annotated[list[str] | None, typer.Option("--set")] = None,\n'
+        '    manifest: Annotated[Path, typer.Option("--manifest")] = _default_manifest(),\n'
+        ") -> None:\n"
+        "    runtime = build_runtime_context()\n"
+        "    result = slide_create(manifest, layout, list(set_values or []), out, dry_run=False)\n"
+        "    envelope = Envelope(\n"
+        "        request_id=runtime.request_id,\n"
+        "        ok=True,\n"
+        '        command="slide.create",\n'
+        "        result=result,\n"
+        "        warnings=[],\n"
+        "        errors=[],\n"
+        "        metrics=Metrics(duration_ms=runtime.duration_ms),\n"
+        "    )\n"
+        "    emit_json(envelope)\n\n"
+        "\n"
+        '@app.command("deck-build")\n'
+        "def deck_build_command(\n"
+        '    spec: Annotated[Path, typer.Option("--spec")],\n'
+        '    out: Annotated[Path, typer.Option("--out")],\n'
+        '    manifest: Annotated[Path, typer.Option("--manifest")] = _default_manifest(),\n'
+        ") -> None:\n"
+        "    runtime = build_runtime_context()\n"
+        "    result = deck_build(manifest, spec, out, dry_run=False)\n"
+        "    envelope = Envelope(\n"
+        "        request_id=runtime.request_id,\n"
+        "        ok=True,\n"
+        '        command="deck.build",\n'
+        "        result=result,\n"
+        "        warnings=[],\n"
+        "        errors=[],\n"
+        "        metrics=Metrics(duration_ms=runtime.duration_ms),\n"
+        "    )\n"
+        "    emit_json(envelope)\n\n"
+        "\n"
+        '@app.command("validate")\n'
+        "def validate_command_wrapper(\n"
+        '    deck: Annotated[Path, typer.Option("--deck")],\n'
+        '    manifest: Annotated[Path, typer.Option("--manifest")] = _default_manifest(),\n'
+        ") -> None:\n"
+        "    runtime = build_runtime_context()\n"
+        "    result = validate_command(manifest, deck, strict=False)\n"
+        "    envelope = Envelope(\n"
+        "        request_id=runtime.request_id,\n"
+        '        ok=result["ok"],\n'
+        '        command="validate.run",\n'
+        "        result=result,\n"
+        "        warnings=[],\n"
+        "        errors=[],\n"
+        "        metrics=Metrics(duration_ms=runtime.duration_ms),\n"
+        "    )\n"
+        "    emit_json(envelope)\n\n"
+        "\n"
+        "def main() -> None:\n"
+        "    app()\n"
+    )

pptx_cli/core/__init__.py

@@ -0,0 +1 @@
+"""Core runtime helpers."""

pptx_cli/core/composition.py

@@ -0,0 +1,280 @@
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from pptx import Presentation
+from pptx.chart.data import ChartData
+from pptx.enum.chart import XL_CHART_TYPE
+
+from pptx_cli.core.io import load_json_or_yaml
+from pptx_cli.core.manifest_store import template_copy_path
+from pptx_cli.models.manifest import DeckSpec, LayoutContract, ManifestDocument, SlideSpec
+
+
+class CompositionError(ValueError):
+    code: str
+
+    def __init__(self, code: str, message: str) -> None:
+        super().__init__(message)
+        self.code = code
+
+
+def resolve_layout(manifest: ManifestDocument, layout_id: str) -> LayoutContract:
+    for layout in manifest.layouts:
+        if layout.id == layout_id or layout.name == layout_id or layout_id in layout.aliases:
+            return layout
+    raise CompositionError("ERR_VALIDATION_LAYOUT_UNKNOWN", f"Unknown layout: {layout_id}")
+
+
+def parse_set_arguments(items: list[str]) -> dict[str, Any]:
+    parsed: dict[str, Any] = {}
+    for item in items:
+        if "=" not in item:
+            raise CompositionError("ERR_VALIDATION_SET_FORMAT", f"Invalid --set entry: {item}")
+        key, raw_value = item.split("=", 1)
+        parsed[key] = _load_inline_or_file_value(raw_value)
+    return parsed
+
+
+def _load_inline_or_file_value(raw_value: str) -> Any:
+    if raw_value.startswith("@"):
+        path = Path(raw_value[1:])
+        if not path.exists():
+            raise CompositionError("ERR_IO_NOT_FOUND", f"Referenced content file not found: {path}")
+        if path.suffix.lower() in {".json", ".yaml", ".yml"}:
+            return load_json_or_yaml(path)
+        if path.suffix.lower() in {".md", ".txt"}:
+            kind = "markdown-text" if path.suffix.lower() == ".md" else "text"
+            return {
+                "kind": kind,
+                "value": path.read_text(encoding="utf-8"),
+            }
+        return {"kind": "image", "path": str(path)}
+
+    if raw_value.startswith("{") or raw_value.startswith("["):
+        try:
+            return json.loads(raw_value)
+        except json.JSONDecodeError:
+            return raw_value
+    return raw_value
+
+
+def create_single_slide_spec(layout: str, content: dict[str, Any]) -> DeckSpec:
+    return DeckSpec(slides=[SlideSpec(layout=layout, content=content)])
+
+
+def build_presentation(manifest_dir: Path, manifest: ManifestDocument, spec: DeckSpec) -> Any:
+    template_path = manifest_dir / manifest.template.stored_template_path
+    if not template_path.exists():
+        template_path = template_copy_path(manifest_dir)
+    prs = Presentation(str(template_path))
+    _remove_all_slides(prs)
+
+    for slide_spec in spec.slides:
+        layout_contract = resolve_layout(manifest, slide_spec.layout)
+        slide_layout = prs.slide_layouts[layout_contract.source_layout_index]
+        slide = prs.slides.add_slide(slide_layout)
+        _populate_slide(slide, layout_contract, slide_spec.content)
+
+    _apply_deck_metadata(prs, spec.metadata)
+    return prs
+
+
+def save_presentation(prs: Any, output_path: Path) -> None:
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    with tempfile.NamedTemporaryFile(
+        delete=False,
+        suffix=output_path.suffix,
+        dir=output_path.parent,
+    ) as handle:
+        temp_path = Path(handle.name)
+    try:
+        prs.save(str(temp_path))
+        os.replace(temp_path, output_path)
+    finally:
+        if temp_path.exists():
+            temp_path.unlink(missing_ok=True)
+
+
+def _remove_all_slides(prs: Any) -> None:
+    slide_id_list = list(prs.slides._sldIdLst)
+    for slide_id in slide_id_list:
+        relationship_id = slide_id.rId
+        prs.part.drop_rel(relationship_id)
+        prs.slides._sldIdLst.remove(slide_id)
+
+
+def _apply_deck_metadata(prs: Any, metadata: dict[str, Any]) -> None:
+    core_properties = prs.core_properties
+    title = metadata.get("title")
+    author = metadata.get("author")
+    if isinstance(title, str):
+        core_properties.title = title
+    if isinstance(author, str):
+        core_properties.author = author
+
+
+def _populate_slide(slide: Any, layout: LayoutContract, content: dict[str, Any]) -> None:
+    expected = {placeholder.logical_name: placeholder for placeholder in layout.placeholders}
+    unknown_keys = sorted(set(content) - set(expected))
+    if unknown_keys:
+        raise CompositionError(
+            "ERR_VALIDATION_PLACEHOLDER_UNKNOWN",
+            f"Unknown placeholders for layout {layout.id}: {', '.join(unknown_keys)}",
+        )
+
+    missing_required = [
+        name
+        for name, placeholder in expected.items()
+        if placeholder.required and name not in content
+    ]
+    if missing_required:
+        raise CompositionError(
+            "ERR_VALIDATION_PLACEHOLDER_REQUIRED",
+            f"Missing required placeholders for layout {layout.id}: {', '.join(missing_required)}",
+        )
+
+    for key, value in content.items():
+        placeholder = expected[key]
+        shape = _find_slide_placeholder(slide, placeholder.placeholder_idx)
+        if shape is None:
+            raise CompositionError(
+                "ERR_INTERNAL_PLACEHOLDER_MISSING",
+                f"Placeholder {key} was not found on generated slide",
+            )
+        _apply_content_value(shape, placeholder.supported_content_types, value)
+
+
+def _find_slide_placeholder(slide: Any, placeholder_idx: int) -> Any | None:
+    for shape in slide.placeholders:
+        if shape.placeholder_format.idx == placeholder_idx:
+            return shape
+    return None
+
+
+def _apply_content_value(shape: Any, supported_types: list[str], value: Any) -> None:
+    content = _normalize_content_value(value)
+    kind = content["kind"]
+    if kind not in supported_types:
+        raise CompositionError(
+            "ERR_VALIDATION_CONTENT_TYPE",
+            f"Content type {kind!r} is not supported for this placeholder",
+        )
+
+    if kind in {"text", "markdown-text"}:
+        _apply_text(shape, str(content["value"]), markdown=kind == "markdown-text")
+        return
+    if kind == "image":
+        image_path = Path(str(content["path"]))
+        if not image_path.exists():
+            raise CompositionError("ERR_IO_NOT_FOUND", f"Image not found: {image_path}")
+        shape.insert_picture(str(image_path))
+        return
+    if kind == "table":
+        _apply_table(shape, content)
+        return
+    if kind == "chart":
+        _apply_chart(shape, content)
+        return
+
+    raise CompositionError("ERR_VALIDATION_CONTENT_TYPE", f"Unsupported content type: {kind}")
+
+
+def _normalize_content_value(value: Any) -> dict[str, Any]:
+    if isinstance(value, dict) and "kind" in value:
+        return value
+    if isinstance(value, str):
+        return {"kind": "text", "value": value}
+    if isinstance(value, (int, float, bool)):
+        return {"kind": "text", "value": str(value)}
+    if isinstance(value, list):
+        return {"kind": "markdown-text", "value": "\n".join(f"- {item}" for item in value)}
+    raise CompositionError("ERR_VALIDATION_CONTENT_TYPE", f"Unsupported content payload: {value!r}")
+
+
+def _apply_text(shape: Any, text: str, *, markdown: bool) -> None:
+    value = _markdown_to_text(text) if markdown else text
+    text_frame = shape.text_frame
+    text_frame.clear()
+    lines = value.splitlines() or [""]
+    first_paragraph = text_frame.paragraphs[0]
+    first_paragraph.text = lines[0]
+    for line in lines[1:]:
+        paragraph = text_frame.add_paragraph()
+        paragraph.text = line
+
+
+def _markdown_to_text(markdown: str) -> str:
+    cleaned_lines: list[str] = []
+    for raw_line in markdown.splitlines():
+        line = raw_line.strip()
+        for prefix in ("# ", "## ", "### ", "- ", "* ", "> "):
+            if line.startswith(prefix):
+                line = line[len(prefix) :]
+        cleaned_lines.append(line.replace("**", "").replace("__", "").replace("`", ""))
+    return "\n".join(cleaned_lines).strip()
+
+
+def _apply_table(shape: Any, content: dict[str, Any]) -> None:
+    columns = content.get("columns", [])
+    rows = content.get("rows", [])
+    if not isinstance(columns, list) or not isinstance(rows, list):
+        raise CompositionError(
+            "ERR_VALIDATION_TABLE_PAYLOAD",
+            "Table payload requires 'columns' and 'rows' lists",
+        )
+
+    row_count = len(rows) + (1 if columns else 0)
+    col_count = len(columns) if columns else (len(rows[0]) if rows else 0)
+    if row_count <= 0 or col_count <= 0:
+        raise CompositionError(
+            "ERR_VALIDATION_TABLE_PAYLOAD",
+            "Table payload must contain at least one row and one column",
+        )
+
+    graphic_frame = shape.insert_table(row_count, col_count)
+    table = graphic_frame.table
+    row_offset = 0
+    if columns:
+        for column_index, heading in enumerate(columns):
+            table.cell(0, column_index).text = str(heading)
+        row_offset = 1
+    for row_index, row in enumerate(rows, start=row_offset):
+        for column_index, cell in enumerate(row):
+            table.cell(row_index, column_index).text = str(cell)
+
+
+def _apply_chart(shape: Any, content: dict[str, Any]) -> None:
+    chart_data = ChartData()
+    categories = content.get("categories", [])
+    series = content.get("series", [])
+    chart_type_name = str(content.get("chart_type", "column_clustered")).upper()
+    if not isinstance(categories, list) or not isinstance(series, list):
+        raise CompositionError(
+            "ERR_VALIDATION_CHART_PAYLOAD",
+            "Chart payload requires 'categories' and 'series' lists",
+        )
+
+    chart_data.categories = categories
+    for series_entry in series:
+        if not isinstance(series_entry, dict):
+            raise CompositionError(
+                "ERR_VALIDATION_CHART_PAYLOAD",
+                "Each chart series must be an object",
+            )
+        chart_data.add_series(
+            str(series_entry.get("name", "Series")),
+            series_entry.get("values", []),
+        )
+
+    if not hasattr(XL_CHART_TYPE, chart_type_name):
+        raise CompositionError(
+            "ERR_VALIDATION_CHART_PAYLOAD",
+            f"Unsupported chart_type: {chart_type_name.lower()}",
+        )
+    chart_type = getattr(XL_CHART_TYPE, chart_type_name)
+    shape.insert_chart(chart_type, chart_data)

pptx_cli/core/ids.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+import re
+
+_SLUG_RE = re.compile(r"[^a-z0-9]+")
+
+
+def slugify(value: str) -> str:
+    normalized = _SLUG_RE.sub("-", value.strip().lower()).strip("-")
+    return normalized or "item"
+
+
+def uniquify(candidate: str, existing: set[str]) -> str:
+    if candidate not in existing:
+        existing.add(candidate)
+        return candidate
+
+    index = 2
+    while f"{candidate}-{index}" in existing:
+        index += 1
+
+    unique_value = f"{candidate}-{index}"
+    existing.add(unique_value)
+    return unique_value

pptx_cli/core/io.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+def ensure_directory(path: Path) -> None:
+    path.mkdir(parents=True, exist_ok=True)
+
+
+def atomic_write_text(path: Path, content: str) -> None:
+    ensure_directory(path.parent)
+    temp_path: Path | None = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            "w",
+            encoding="utf-8",
+            dir=path.parent,
+            delete=False,
+        ) as handle:
+            handle.write(content)
+            handle.flush()
+            os.fsync(handle.fileno())
+            temp_path = Path(handle.name)
+        os.replace(temp_path, path)
+    except BaseException:
+        if temp_path is not None and temp_path.exists():
+            temp_path.unlink(missing_ok=True)
+        raise
+
+
+def atomic_write_bytes(path: Path, content: bytes) -> None:
+    ensure_directory(path.parent)
+    with tempfile.NamedTemporaryFile("wb", dir=path.parent, delete=False) as handle:
+        handle.write(content)
+        handle.flush()
+        os.fsync(handle.fileno())
+        temp_path = Path(handle.name)
+    os.replace(temp_path, path)
+
+
+def write_json(path: Path, payload: Any) -> None:
+    atomic_write_text(path, json.dumps(payload, indent=2, sort_keys=False) + "\n")
+
+
+def write_yaml(path: Path, payload: Any) -> None:
+    atomic_write_text(path, yaml.safe_dump(payload, sort_keys=False, allow_unicode=True))
+
+
+def load_json_or_yaml(path: Path) -> Any:
+    suffix = path.suffix.lower()
+    text = path.read_text(encoding="utf-8")
+    if suffix == ".json":
+        return json.loads(text)
+    return yaml.safe_load(text)