robopilot 1.1.0__tar.gz

robopilot-1.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 J1angJJ
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

robopilot-1.1.0/PKG-INFO

@@ -0,0 +1,207 @@
+Metadata-Version: 2.4
+Name: robopilot
+Version: 1.1.0
+Summary: No-ROS-required static engineering toolchain for ROS-style projects.
+Author: J1angJJ
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/J1angJJ/RoboPilot
+Project-URL: Repository, https://github.com/J1angJJ/RoboPilot
+Project-URL: Issues, https://github.com/J1angJJ/RoboPilot/issues
+Project-URL: Changelog, https://github.com/J1angJJ/RoboPilot/blob/main/CHANGELOG.md
+Keywords: robotics,ros,ros1,ros2,developer-tools,code-generation,static-analysis,migration
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: <3.12,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.12.0
+Requires-Dist: rich>=13.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Provides-Extra: llm
+Requires-Dist: openai>=1.0.0; extra == "llm"
+Dynamic: license-file
+
+# RoboPilot
+
+[English](README.md) | [中文](README.zh-CN.md)
+
+[![Tests](https://github.com/J1angJJ/RoboPilot/actions/workflows/tests.yml/badge.svg)](https://github.com/J1angJJ/RoboPilot/actions/workflows/tests.yml)
+
+RoboPilot is a no-ROS-required static engineering toolchain for ROS-style projects.
+
+It helps robotics learners and developers plan, refine, validate, generate, inspect, update, roll back, document, and review ROS/ROS2-style project structure without installing ROS, ROS2, catkin, colcon, simulator runtimes, or robot hardware.
+
+## What RoboPilot Does
+
+- Creates and validates `ProjectSpec` files from robotics tasks.
+- Renders deterministic ROS-style Python package skeletons.
+- Refines and diffs specs before generation.
+- Previews, exports, applies, backs up, rolls back, and journals safe project updates.
+- Inspects projects and exports read-only reports.
+- Detects RoboPilot, ROS1, ROS2, mixed, non-ROS, and unknown project types.
+- Statically inspects ROS1 catkin packages.
+- Analyzes declared and detected dependencies.
+- Builds static ROS1-to-ROS2 migration plans, validates/diffs them, and previews file-level migration work.
+- Provides small offline utilities for robotics error logs and Mermaid workflow graphs.
+- Optionally uses an LLM only to produce or refine validated `ProjectSpec` data.
+
+RoboPilot does not run ROS, ROS2, launch files, generated code, `catkin_make`, or `colcon`.
+
+## Quick Start
+
+Supported Python versions for this release line are Python 3.10 and 3.11. Package metadata declares `>=3.10,<3.12`; Python 3.12 and 3.13 are not claimed until the test suite passes there.
+
+Install from source for now:
+
+```bash
+python -m venv .venv
+.venv\Scripts\activate
+python -m pip install -U pip
+pip install -e ".[dev]"
+robopilot --help
+```
+
+After PyPI release:
+
+```bash
+pip install robopilot
+robopilot --help
+```
+
+On Windows, if pytest has temporary directory permission issues:
+
+```bash
+python -m pytest --basetemp=".pytest_tmp" -p no:cacheprovider
+```
+
+## Core Workflows
+
+Spec-first generation:
+
+```bash
+robopilot plan --name demo_detector --task "Create an object detection pipeline" --output robopilot.yaml
+robopilot validate --spec robopilot.yaml
+robopilot generate --spec robopilot.yaml
+```
+
+Iterative spec review:
+
+```bash
+robopilot refine --spec robopilot.yaml --instruction "Add a tracker node after the detector" --output refined.yaml
+robopilot diff --old robopilot.yaml --new refined.yaml
+```
+
+Safe project update loop:
+
+```bash
+robopilot apply-preview --spec refined.yaml --project outputs/demo_detector
+robopilot apply-plan --spec refined.yaml --project outputs/demo_detector --output apply_plan.yaml
+robopilot apply --plan apply_plan.yaml
+robopilot apply --plan apply_plan.yaml --confirm
+robopilot history --project outputs/demo_detector
+```
+
+Static project review:
+
+```bash
+robopilot inspect examples/generated_projects/demo_detector
+robopilot repair-suggest examples/generated_projects/demo_detector
+robopilot report examples/generated_projects/demo_detector --output report.md
+```
+
+ROS-style static analysis:
+
+```bash
+robopilot detect path/to/project
+robopilot inspect-ros1 path/to/ros1_package
+robopilot deps path/to/project
+```
+
+ROS1 to ROS2 migration planning:
+
+```bash
+robopilot migrate-plan --from path/to/ros1_package --to ros2 --output migration_plan.yaml
+robopilot migrate-plan-validate --plan migration_plan.yaml
+robopilot migrate-preview --plan migration_plan.yaml --project path/to/ros1_package
+```
+
+## Documentation
+
+- [Command Reference](docs/command_reference.md)
+- [Workflows](docs/workflows.md)
+- [Architecture](docs/architecture.md)
+- [Developer Setup](docs/developer_setup.md)
+- [Testing](docs/testing.md)
+- [Release Process](docs/release_process.md)
+- [PyPI Publishing](docs/pypi_publish.md)
+- [Compatibility](docs/compatibility.md)
+- [Known Limitations](docs/known_limitations.md)
+- [Stability Policy](docs/stability_policy.md)
+- [Demo Script](docs/demo_script.md)
+- [v1.0.0 Scope](docs/v1_scope.md)
+- [Changelog](CHANGELOG.md)
+- [Roadmap](roadmap.md)
+
+## Safety Model
+
+RoboPilot is designed around static analysis and explicit review:
+
+- Default planning, validation, diff, inspection, report, detection, dependency, and migration commands are read-only.
+- `apply` is dry-run by default and writes only with `--confirm`.
+- Confirmed updates write only files listed in a validated apply plan.
+- Existing files are backed up before updates.
+- `rollback` is dry-run by default and restores only files from RoboPilot backup directories.
+- Migration planning, validation, diff, and preview do not modify source projects.
+- Optional LLM paths are limited to `ProjectSpec` planning/refinement and must pass validation before generation or apply workflows.
+
+## Example Output
+
+A static generated demo project is committed at:
+
+```txt
+examples/generated_projects/demo_detector/
+```
+
+Transient generated projects should go under `outputs/`, which is intentionally ignored by git.
+
+## Project Status
+
+Current release line: `v1.1.0`.
+
+RoboPilot's no-ROS-required static engineering workflow remains the stable v1 baseline:
+
+```txt
+plan -> refine -> diff -> validate -> generate
+      -> apply-preview -> apply-plan -> apply -> rollback -> history
+      -> inspect -> repair-suggest -> report
+      -> detect -> inspect-ros1 -> deps
+      -> migrate-plan -> migrate-plan-validate -> migrate-plan-diff -> migrate-preview
+```
+
+## Development
+
+Run tests:
+
+```bash
+python -m pytest
+```
+
+Windows fallback:
+
+```bash
+python -m pytest --basetemp=".pytest_tmp" -p no:cacheprovider
+```
+
+## License
+
+MIT

robopilot-1.1.0/README.md

@@ -0,0 +1,174 @@
+# RoboPilot
+
+[English](README.md) | [中文](README.zh-CN.md)
+
+[![Tests](https://github.com/J1angJJ/RoboPilot/actions/workflows/tests.yml/badge.svg)](https://github.com/J1angJJ/RoboPilot/actions/workflows/tests.yml)
+
+RoboPilot is a no-ROS-required static engineering toolchain for ROS-style projects.
+
+It helps robotics learners and developers plan, refine, validate, generate, inspect, update, roll back, document, and review ROS/ROS2-style project structure without installing ROS, ROS2, catkin, colcon, simulator runtimes, or robot hardware.
+
+## What RoboPilot Does
+
+- Creates and validates `ProjectSpec` files from robotics tasks.
+- Renders deterministic ROS-style Python package skeletons.
+- Refines and diffs specs before generation.
+- Previews, exports, applies, backs up, rolls back, and journals safe project updates.
+- Inspects projects and exports read-only reports.
+- Detects RoboPilot, ROS1, ROS2, mixed, non-ROS, and unknown project types.
+- Statically inspects ROS1 catkin packages.
+- Analyzes declared and detected dependencies.
+- Builds static ROS1-to-ROS2 migration plans, validates/diffs them, and previews file-level migration work.
+- Provides small offline utilities for robotics error logs and Mermaid workflow graphs.
+- Optionally uses an LLM only to produce or refine validated `ProjectSpec` data.
+
+RoboPilot does not run ROS, ROS2, launch files, generated code, `catkin_make`, or `colcon`.
+
+## Quick Start
+
+Supported Python versions for this release line are Python 3.10 and 3.11. Package metadata declares `>=3.10,<3.12`; Python 3.12 and 3.13 are not claimed until the test suite passes there.
+
+Install from source for now:
+
+```bash
+python -m venv .venv
+.venv\Scripts\activate
+python -m pip install -U pip
+pip install -e ".[dev]"
+robopilot --help
+```
+
+After PyPI release:
+
+```bash
+pip install robopilot
+robopilot --help
+```
+
+On Windows, if pytest has temporary directory permission issues:
+
+```bash
+python -m pytest --basetemp=".pytest_tmp" -p no:cacheprovider
+```
+
+## Core Workflows
+
+Spec-first generation:
+
+```bash
+robopilot plan --name demo_detector --task "Create an object detection pipeline" --output robopilot.yaml
+robopilot validate --spec robopilot.yaml
+robopilot generate --spec robopilot.yaml
+```
+
+Iterative spec review:
+
+```bash
+robopilot refine --spec robopilot.yaml --instruction "Add a tracker node after the detector" --output refined.yaml
+robopilot diff --old robopilot.yaml --new refined.yaml
+```
+
+Safe project update loop:
+
+```bash
+robopilot apply-preview --spec refined.yaml --project outputs/demo_detector
+robopilot apply-plan --spec refined.yaml --project outputs/demo_detector --output apply_plan.yaml
+robopilot apply --plan apply_plan.yaml
+robopilot apply --plan apply_plan.yaml --confirm
+robopilot history --project outputs/demo_detector
+```
+
+Static project review:
+
+```bash
+robopilot inspect examples/generated_projects/demo_detector
+robopilot repair-suggest examples/generated_projects/demo_detector
+robopilot report examples/generated_projects/demo_detector --output report.md
+```
+
+ROS-style static analysis:
+
+```bash
+robopilot detect path/to/project
+robopilot inspect-ros1 path/to/ros1_package
+robopilot deps path/to/project
+```
+
+ROS1 to ROS2 migration planning:
+
+```bash
+robopilot migrate-plan --from path/to/ros1_package --to ros2 --output migration_plan.yaml
+robopilot migrate-plan-validate --plan migration_plan.yaml
+robopilot migrate-preview --plan migration_plan.yaml --project path/to/ros1_package
+```
+
+## Documentation
+
+- [Command Reference](docs/command_reference.md)
+- [Workflows](docs/workflows.md)
+- [Architecture](docs/architecture.md)
+- [Developer Setup](docs/developer_setup.md)
+- [Testing](docs/testing.md)
+- [Release Process](docs/release_process.md)
+- [PyPI Publishing](docs/pypi_publish.md)
+- [Compatibility](docs/compatibility.md)
+- [Known Limitations](docs/known_limitations.md)
+- [Stability Policy](docs/stability_policy.md)
+- [Demo Script](docs/demo_script.md)
+- [v1.0.0 Scope](docs/v1_scope.md)
+- [Changelog](CHANGELOG.md)
+- [Roadmap](roadmap.md)
+
+## Safety Model
+
+RoboPilot is designed around static analysis and explicit review:
+
+- Default planning, validation, diff, inspection, report, detection, dependency, and migration commands are read-only.
+- `apply` is dry-run by default and writes only with `--confirm`.
+- Confirmed updates write only files listed in a validated apply plan.
+- Existing files are backed up before updates.
+- `rollback` is dry-run by default and restores only files from RoboPilot backup directories.
+- Migration planning, validation, diff, and preview do not modify source projects.
+- Optional LLM paths are limited to `ProjectSpec` planning/refinement and must pass validation before generation or apply workflows.
+
+## Example Output
+
+A static generated demo project is committed at:
+
+```txt
+examples/generated_projects/demo_detector/
+```
+
+Transient generated projects should go under `outputs/`, which is intentionally ignored by git.
+
+## Project Status
+
+Current release line: `v1.1.0`.
+
+RoboPilot's no-ROS-required static engineering workflow remains the stable v1 baseline:
+
+```txt
+plan -> refine -> diff -> validate -> generate
+      -> apply-preview -> apply-plan -> apply -> rollback -> history
+      -> inspect -> repair-suggest -> report
+      -> detect -> inspect-ros1 -> deps
+      -> migrate-plan -> migrate-plan-validate -> migrate-plan-diff -> migrate-preview
+```
+
+## Development
+
+Run tests:
+
+```bash
+python -m pytest
+```
+
+Windows fallback:
+
+```bash
+python -m pytest --basetemp=".pytest_tmp" -p no:cacheprovider
+```
+
+## License
+
+MIT

robopilot-1.1.0/pyproject.toml

@@ -0,0 +1,66 @@
+[project]
+name = "robopilot"
+version = "1.1.0"
+description = "No-ROS-required static engineering toolchain for ROS-style projects."
+readme = "README.md"
+requires-python = ">=3.10,<3.12"
+license = "MIT"
+authors = [
+    { name = "J1angJJ" }
+]
+keywords = [
+    "robotics",
+    "ros",
+    "ros1",
+    "ros2",
+    "developer-tools",
+    "code-generation",
+    "static-analysis",
+    "migration"
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Education",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Topic :: Software Development :: Code Generators",
+    "Topic :: Software Development :: Quality Assurance",
+    "Topic :: Scientific/Engineering"
+]
+
+dependencies = [
+    "typer>=0.12.0",
+    "rich>=13.0.0"
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0"
+]
+llm = [
+    "openai>=1.0.0"
+]
+
+[project.scripts]
+robopilot = "robopilot.main:app"
+
+[project.urls]
+Homepage = "https://github.com/J1angJJ/RoboPilot"
+Repository = "https://github.com/J1angJJ/RoboPilot"
+Issues = "https://github.com/J1angJJ/RoboPilot/issues"
+Changelog = "https://github.com/J1angJJ/RoboPilot/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["setuptools>=77.0.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

robopilot-1.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

robopilot-1.1.0/src/robopilot/apply/__init__.py

@@ -0,0 +1,5 @@
+"""Safe apply execution helpers."""
+
+from robopilot.apply.apply_plan import ApplySummary, apply_from_plan
+
+__all__ = ["ApplySummary", "apply_from_plan"]

robopilot-1.1.0/src/robopilot/apply/apply_plan.py

@@ -0,0 +1,218 @@
+"""Safely apply a previously exported apply plan."""
+
+from __future__ import annotations
+
+import shutil
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+
+from robopilot.apply_plan.plan import (
+    apply_plan_from_preview,
+    load_apply_plan,
+    validate_apply_plan,
+)
+from robopilot.apply_preview.preview import preview_apply
+from robopilot.generator.project_generator import render_project_files
+from robopilot.history.journal import record_history_entry
+from robopilot.spec.io import load_spec
+from robopilot.spec.validator import validate_spec
+
+
+SAFETY_NOTE = (
+    "RoboPilot apply validates the plan, re-runs apply-preview, refuses stale "
+    "plans and conflicts, and only writes files listed in files_to_create or "
+    "files_to_update when --confirm is provided."
+)
+
+
+@dataclass(frozen=True)
+class ApplySummary:
+    """Summary of a dry-run or confirmed apply operation."""
+
+    plan_path: str
+    project_path: str
+    dry_run: bool
+    files_created: tuple[str, ...]
+    files_updated: tuple[str, ...]
+    files_kept: tuple[str, ...]
+    backups_created: tuple[str, ...]
+    skipped_files: tuple[str, ...]
+    conflicts: tuple[str, ...]
+    safety_note: str
+
+    def to_dict(self) -> dict[str, object]:
+        """Return a stable JSON-serializable representation."""
+        return {
+            "plan_path": self.plan_path,
+            "project_path": self.project_path,
+            "dry_run": self.dry_run,
+            "files_created": list(self.files_created),
+            "files_updated": list(self.files_updated),
+            "files_kept": list(self.files_kept),
+            "backups_created": list(self.backups_created),
+            "skipped_files": list(self.skipped_files),
+            "conflicts": list(self.conflicts),
+            "safety_note": self.safety_note,
+        }
+
+
+def apply_from_plan(plan_path: Path, *, confirm: bool = False) -> ApplySummary:
+    """Dry-run or apply a saved plan after conservative safety checks."""
+    plan = load_apply_plan(plan_path)
+    validation = validate_apply_plan(plan)
+    if not validation.is_valid:
+        raise ValueError("Invalid apply plan: " + "; ".join(validation.errors))
+
+    spec_path = Path(_string_field(plan, "spec_path"))
+    project_path = Path(_string_field(plan, "project_path"))
+    spec = load_spec(spec_path)
+    spec_validation = validate_spec(spec)
+    if not spec_validation.is_valid:
+        raise ValueError("Invalid ProjectSpec: " + "; ".join(spec_validation.errors))
+
+    fresh_preview = preview_apply(spec_path, project_path)
+    fresh_plan = apply_plan_from_preview(fresh_preview)
+    _ensure_plan_is_fresh(plan, fresh_plan)
+
+    conflicts = tuple(_list_field(plan, "conflicts"))
+    if confirm and conflicts:
+        raise ValueError("Refusing to apply because conflicts are present.")
+
+    files_to_create = tuple(_validate_relative_paths(_list_field(plan, "files_to_create")))
+    files_to_update = tuple(_validate_relative_paths(_list_field(plan, "files_to_update")))
+    files_to_keep = tuple(_validate_relative_paths(_list_field(plan, "files_to_keep")))
+    expected_files = {
+        path.as_posix(): content for path, content in render_project_files(spec).items()
+    }
+
+    _ensure_planned_files_are_expected(files_to_create + files_to_update, expected_files)
+
+    if not confirm:
+        return ApplySummary(
+            plan_path=str(plan_path),
+            project_path=str(project_path),
+            dry_run=True,
+            files_created=(),
+            files_updated=(),
+            files_kept=files_to_keep,
+            backups_created=(),
+            skipped_files=tuple(sorted(files_to_create + files_to_update + files_to_keep + conflicts)),
+            conflicts=conflicts,
+            safety_note="Dry run only. No files were modified. " + SAFETY_NOTE,
+        )
+
+    created: list[str] = []
+    updated: list[str] = []
+    backups: list[str] = []
+    backup_root = project_path / ".robopilot_backups" / _timestamp()
+
+    for relative_path in files_to_create:
+        target = project_path / relative_path
+        if target.exists():
+            raise ValueError(f"Refusing to create existing file: {relative_path}")
+        _write_expected_file(target, expected_files[relative_path])
+        created.append(relative_path)
+
+    for relative_path in files_to_update:
+        target = project_path / relative_path
+        if not target.is_file():
+            raise ValueError(f"Refusing to update missing file: {relative_path}")
+        backup_path = backup_root / relative_path
+        backup_path.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(target, backup_path)
+        backups.append(backup_path.relative_to(project_path).as_posix())
+        _write_expected_file(target, expected_files[relative_path])
+        updated.append(relative_path)
+
+    summary = ApplySummary(
+        plan_path=str(plan_path),
+        project_path=str(project_path),
+        dry_run=False,
+        files_created=tuple(sorted(created)),
+        files_updated=tuple(sorted(updated)),
+        files_kept=files_to_keep,
+        backups_created=tuple(sorted(backups)),
+        skipped_files=tuple(sorted(files_to_keep + conflicts)),
+        conflicts=conflicts,
+        safety_note=SAFETY_NOTE,
+    )
+    record_history_entry(
+        project_path=project_path,
+        operation="apply",
+        plan_path=str(plan_path),
+        dry_run=False,
+        success=True,
+        files_created=summary.files_created,
+        files_updated=summary.files_updated,
+        files_kept=summary.files_kept,
+        conflicts=summary.conflicts,
+        skipped_files=summary.skipped_files,
+        summary=(
+            f"Applied plan with {len(summary.files_created)} files created "
+            f"and {len(summary.files_updated)} files updated."
+        ),
+    )
+    return summary
+
+
+def _ensure_plan_is_fresh(
+    saved_plan: dict[str, object],
+    fresh_plan: dict[str, object],
+) -> None:
+    compared_fields = (
+        "spec_path",
+        "project_path",
+        "package_name",
+        "selected_template",
+        "files_to_create",
+        "files_to_update",
+        "files_to_keep",
+        "conflicts",
+        "missing_project",
+    )
+    for field in compared_fields:
+        if saved_plan.get(field) != fresh_plan.get(field):
+            raise ValueError(f"Refusing to apply stale plan: {field} changed.")
+
+
+def _ensure_planned_files_are_expected(
+    relative_paths: tuple[str, ...],
+    expected_files: dict[str, str],
+) -> None:
+    for relative_path in relative_paths:
+        if relative_path not in expected_files:
+            raise ValueError(f"Refusing to modify unexpected file: {relative_path}")
+
+
+def _write_expected_file(path: Path, content: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+
+
+def _string_field(plan: dict[str, object], field: str) -> str:
+    value = plan.get(field)
+    if not isinstance(value, str):
+        raise ValueError(f"{field} must be a string.")
+    return value
+
+
+def _list_field(plan: dict[str, object], field: str) -> tuple[str, ...]:
+    value = plan.get(field)
+    if not isinstance(value, list):
+        raise ValueError(f"{field} must be a list.")
+    return tuple(str(item) for item in value)
+
+
+def _validate_relative_paths(paths: tuple[str, ...]) -> tuple[str, ...]:
+    validated: list[str] = []
+    for raw_path in paths:
+        path = Path(raw_path)
+        if path.is_absolute() or ".." in path.parts:
+            raise ValueError(f"Refusing unsafe relative path: {raw_path}")
+        validated.append(path.as_posix())
+    return tuple(validated)
+
+
+def _timestamp() -> str:
+    return datetime.now().strftime("%Y%m%d_%H%M%S")