robopilot 1.1.0__py3-none-any.whl

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/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")

robopilot/apply_plan/__init__.py

@@ -0,0 +1,13 @@
+"""Read-only apply plan export helpers."""
+
+from robopilot.apply_plan.plan import (
+    ApplyPlanValidationResult,
+    export_apply_plan,
+    validate_apply_plan_file,
+)
+
+__all__ = [
+    "ApplyPlanValidationResult",
+    "export_apply_plan",
+    "validate_apply_plan_file",
+]

robopilot/apply_plan/plan.py

@@ -0,0 +1,216 @@
+"""Export and validate read-only apply plans."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from robopilot.apply_preview.preview import ApplyPreviewResult, preview_apply
+
+
+GENERATED_BY = "RoboPilot ApplyPlan"
+SUPPORTED_FORMATS = {"yaml", "json"}
+REQUIRED_FIELDS = (
+    "generated_by",
+    "spec_path",
+    "project_path",
+    "package_name",
+    "selected_template",
+    "files_to_create",
+    "files_to_update",
+    "files_to_keep",
+    "conflicts",
+    "missing_project",
+    "safety_note",
+    "suggested_next_steps",
+)
+LIST_FIELDS = {
+    "files_to_create",
+    "files_to_update",
+    "files_to_keep",
+    "conflicts",
+    "suggested_next_steps",
+}
+
+
+@dataclass(frozen=True)
+class ApplyPlanValidationResult:
+    """Validation result for a serialized apply plan."""
+
+    is_valid: bool
+    errors: tuple[str, ...]
+
+
+def export_apply_plan(
+    *,
+    spec_path: Path,
+    project_path: Path,
+    output_path: Path,
+    output_format: str = "yaml",
+) -> dict[str, object]:
+    """Export a deterministic apply plan without modifying the project."""
+    normalized_format = output_format.strip().lower()
+    if normalized_format not in SUPPORTED_FORMATS:
+        raise ValueError("Unsupported apply plan format. Use 'yaml' or 'json'.")
+
+    preview = preview_apply(spec_path, project_path)
+    plan = apply_plan_from_preview(preview)
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    if normalized_format == "json":
+        output_path.write_text(json.dumps(plan, indent=2) + "\n", encoding="utf-8")
+    else:
+        output_path.write_text(apply_plan_to_yaml(plan), encoding="utf-8")
+    return plan
+
+
+def apply_plan_from_preview(preview: ApplyPreviewResult) -> dict[str, object]:
+    """Convert an apply-preview result into a stable apply plan mapping."""
+    data = preview.to_dict()
+    return {
+        "generated_by": GENERATED_BY,
+        "spec_path": data["spec_path"],
+        "project_path": data["project_path"],
+        "package_name": data["package_name"],
+        "selected_template": data["selected_template"],
+        "files_to_create": data["files_to_create"],
+        "files_to_update": data["files_to_update"],
+        "files_to_keep": data["files_to_keep"],
+        "conflicts": data["conflicts"],
+        "missing_project": data["missing_project"],
+        "safety_note": data["safety_note"],
+        "suggested_next_steps": data["suggested_next_steps"],
+    }
+
+
+def apply_plan_to_yaml(plan: dict[str, object]) -> str:
+    """Serialize an apply plan using RoboPilot's small YAML-like subset."""
+    lines: list[str] = []
+    for field in REQUIRED_FIELDS:
+        value = plan.get(field)
+        if field in LIST_FIELDS:
+            lines.append(f"{field}:")
+            for item in _list_value(value):
+                lines.append(f'  - "{_quote(str(item))}"')
+            continue
+        if isinstance(value, bool):
+            rendered = "true" if value else "false"
+        else:
+            rendered = f'"{_quote(str(value or ""))}"'
+        lines.append(f"{field}: {rendered}")
+    return "\n".join(lines) + "\n"
+
+
+def validate_apply_plan_file(plan_path: Path) -> ApplyPlanValidationResult:
+    """Validate a serialized apply plan without executing it."""
+    try:
+        plan = load_apply_plan(plan_path)
+    except (OSError, ValueError, json.JSONDecodeError) as exc:
+        return ApplyPlanValidationResult(False, (str(exc),))
+    return validate_apply_plan(plan)
+
+
+def validate_apply_plan(plan: dict[str, object]) -> ApplyPlanValidationResult:
+    """Validate required apply plan fields and basic types."""
+    errors: list[str] = []
+    for field in REQUIRED_FIELDS:
+        if field not in plan:
+            errors.append(f"{field} is required.")
+
+    for field in LIST_FIELDS:
+        if field in plan and not isinstance(plan[field], list):
+            errors.append(f"{field} must be a list.")
+
+    if "missing_project" in plan and not isinstance(plan["missing_project"], bool):
+        errors.append("missing_project must be a boolean.")
+
+    for field in (
+        "generated_by",
+        "spec_path",
+        "project_path",
+        "package_name",
+        "selected_template",
+        "safety_note",
+    ):
+        if field in plan and not isinstance(plan[field], str):
+            errors.append(f"{field} must be a string.")
+
+    return ApplyPlanValidationResult(is_valid=not errors, errors=tuple(errors))
+
+
+def load_apply_plan(plan_path: Path) -> dict[str, object]:
+    """Load a JSON or RoboPilot YAML-like apply plan."""
+    content = plan_path.read_text(encoding="utf-8")
+    if plan_path.suffix.lower() == ".json" or content.lstrip().startswith("{"):
+        data = json.loads(content)
+        if not isinstance(data, dict):
+            raise ValueError("Apply plan JSON must be an object.")
+        return data
+    return apply_plan_from_yaml(content)
+
+
+def apply_plan_from_yaml(content: str) -> dict[str, object]:
+    """Parse RoboPilot's small apply-plan YAML-like subset."""
+    data: dict[str, object] = {}
+    current_list: str | None = None
+    for raw_line in content.splitlines():
+        if not raw_line.strip() or raw_line.lstrip().startswith("#"):
+            continue
+        if not raw_line.startswith(" "):
+            key, value = _split_key_value(raw_line)
+            if value == "" and key in LIST_FIELDS:
+                data[key] = []
+                current_list = key
+                continue
+            current_list = None
+            if key == "missing_project":
+                data[key] = _parse_bool(value)
+            else:
+                data[key] = _unquote(value)
+            continue
+        if current_list is None:
+            raise ValueError(f"Unexpected indented line outside a list: {raw_line}")
+        stripped = raw_line.strip()
+        if not stripped.startswith("- "):
+            raise ValueError(f"Expected list item: {raw_line}")
+        value = _unquote(stripped[2:].strip())
+        current_value = data[current_list]
+        if not isinstance(current_value, list):
+            raise ValueError(f"Expected list field: {current_list}")
+        current_value.append(value)
+    return data
+
+
+def _split_key_value(line: str) -> tuple[str, str]:
+    if ":" not in line:
+        raise ValueError(f"Expected key/value line: {line}")
+    key, value = line.split(":", 1)
+    return key.strip(), value.strip()
+
+
+def _parse_bool(value: str) -> bool:
+    normalized = _unquote(value).strip().lower()
+    if normalized == "true":
+        return True
+    if normalized == "false":
+        return False
+    raise ValueError(f"Expected boolean value, got: {value}")
+
+
+def _quote(value: str) -> str:
+    return value.replace("\\", "\\\\").replace('"', '\\"')
+
+
+def _unquote(value: str) -> str:
+    if len(value) >= 2 and value[0] == '"' and value[-1] == '"':
+        value = value[1:-1]
+    return value.replace('\\"', '"').replace("\\\\", "\\")
+
+
+def _list_value(value: object) -> list[Any]:
+    if isinstance(value, list):
+        return value
+    if isinstance(value, tuple):
+        return list(value)
+    return []

robopilot/apply_preview/__init__.py

@@ -0,0 +1,5 @@
+"""Read-only apply preview helpers."""
+
+from robopilot.apply_preview.preview import ApplyPreviewResult, preview_apply
+
+__all__ = ["ApplyPreviewResult", "preview_apply"]

robopilot/apply_preview/preview.py

@@ -0,0 +1,156 @@
+"""Read-only preview of applying a ProjectSpec to a project directory."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from robopilot.generator.project_generator import render_project_files
+from robopilot.spec.io import load_spec
+from robopilot.spec.validator import validate_spec
+
+
+SAFETY_NOTE = (
+    "This is a read-only apply preview. RoboPilot did not modify project files, "
+    "execute ROS2, run launch files, run colcon, or execute generated Python code."
+)
+
+
+@dataclass(frozen=True)
+class ApplyPreviewResult:
+    """Structured apply preview result."""
+
+    spec_path: str
+    project_path: str
+    package_name: str
+    selected_template: str
+    files_to_create: tuple[str, ...]
+    files_to_update: tuple[str, ...]
+    files_to_keep: tuple[str, ...]
+    conflicts: tuple[str, ...]
+    missing_project: bool
+    safety_note: str
+    suggested_next_steps: tuple[str, ...]
+
+    def to_dict(self) -> dict[str, object]:
+        """Return a stable JSON-serializable representation."""
+        return {
+            "spec_path": self.spec_path,
+            "project_path": self.project_path,
+            "package_name": self.package_name,
+            "selected_template": self.selected_template,
+            "files_to_create": list(self.files_to_create),
+            "files_to_update": list(self.files_to_update),
+            "files_to_keep": list(self.files_to_keep),
+            "conflicts": list(self.conflicts),
+            "missing_project": self.missing_project,
+            "safety_note": self.safety_note,
+            "suggested_next_steps": list(self.suggested_next_steps),
+        }
+
+
+def preview_apply(spec_path: Path, project_path: Path) -> ApplyPreviewResult:
+    """Preview what applying a ProjectSpec would change without writing files."""
+    spec = load_spec(spec_path)
+    validation = validate_spec(spec)
+    if not validation.is_valid:
+        raise ValueError("Invalid ProjectSpec: " + "; ".join(validation.errors))
+
+    expected_files = render_project_files(spec)
+    missing_project = not project_path.exists()
+    files_to_create: list[str] = []
+    files_to_update: list[str] = []
+    files_to_keep: list[str] = []
+
+    for relative_path, expected_content in expected_files.items():
+        normalized = _normalize_path(relative_path)
+        target = project_path / relative_path
+        if missing_project or not target.exists():
+            files_to_create.append(normalized)
+            continue
+        if not target.is_file():
+            files_to_update.append(normalized)
+            continue
+        try:
+            existing_content = target.read_text(encoding="utf-8")
+        except UnicodeDecodeError:
+            files_to_update.append(normalized)
+            continue
+        if existing_content == expected_content:
+            files_to_keep.append(normalized)
+        else:
+            files_to_update.append(normalized)
+
+    conflicts = _detect_conflicts(project_path, set(expected_files))
+    return ApplyPreviewResult(
+        spec_path=str(spec_path),
+        project_path=str(project_path),
+        package_name=spec.package_name,
+        selected_template=spec.selected_template,
+        files_to_create=tuple(sorted(files_to_create)),
+        files_to_update=tuple(sorted(files_to_update)),
+        files_to_keep=tuple(sorted(files_to_keep)),
+        conflicts=conflicts,
+        missing_project=missing_project,
+        safety_note=SAFETY_NOTE,
+        suggested_next_steps=_suggest_next_steps(
+            missing_project=missing_project,
+            files_to_create=files_to_create,
+            files_to_update=files_to_update,
+            conflicts=conflicts,
+            spec_path=spec_path,
+            project_path=project_path,
+        ),
+    )
+
+
+def _detect_conflicts(project_path: Path, expected_paths: set[Path]) -> tuple[str, ...]:
+    if not project_path.exists() or not project_path.is_dir():
+        return ()
+
+    conflicts: list[str] = []
+    for path in project_path.rglob("*"):
+        if not path.is_file():
+            continue
+        relative_path = path.relative_to(project_path)
+        if _is_ignored_artifact(relative_path):
+            continue
+        if relative_path not in expected_paths:
+            conflicts.append(_normalize_path(relative_path))
+    return tuple(sorted(conflicts))
+
+
+def _suggest_next_steps(
+    *,
+    missing_project: bool,
+    files_to_create: list[str],
+    files_to_update: list[str],
+    conflicts: tuple[str, ...],
+    spec_path: Path,
+    project_path: Path,
+) -> tuple[str, ...]:
+    steps: list[str] = []
+    if missing_project:
+        steps.append("Create the project with robopilot generate --spec before applying future changes.")
+    if files_to_create or files_to_update:
+        steps.append(f"Review this preview before generating from {spec_path}.")
+    if conflicts:
+        steps.append("Review conflicts manually; RoboPilot will not overwrite unexpected files blindly.")
+    if not steps:
+        steps.append("No file changes are needed for the expected generated files.")
+    steps.append(f"Run robopilot inspect {project_path} for a static project health check.")
+    return tuple(steps)
+
+
+def _is_ignored_artifact(relative_path: Path) -> bool:
+    parts = set(relative_path.parts)
+    return (
+        "__pycache__" in parts
+        or ".robopilot_backups" in parts
+        or ".robopilot_history" in parts
+        or relative_path.suffix in {".pyc", ".pyo"}
+    )
+
+
+def _normalize_path(path: Path) -> str:
+    return path.as_posix()

robopilot/debugger/__init__.py

@@ -0,0 +1,6 @@
+"""Offline robotics error log analysis helpers."""
+
+from robopilot.debugger.log_analyzer import LogAnalysis, analyze_log
+
+__all__ = ["LogAnalysis", "analyze_log"]
+