Skip to content

bluefox-upgrade

Upgrade engine for Bluefox app scaffolding. Declarative operations, conflict detection, and multi-step chains with automatic collapsing.

uv add bluefox-upgrade

What it does

  • Seven operation types — ReplaceFile, CreateFile, RemoveFile, UpdateSection, AddDependency, BumpDependency, RemoveDependency
  • Conflict detection — SHA-256 hashing detects user edits before overwriting
  • Three conflict modes — abort, skip (preserve user edits), or force (backup + overwrite)
  • Multi-step chains — jump from v0.1 to v0.5 in one pass
  • Automatic collapsing — redundant operations across steps are merged
  • Section markers — update managed blocks while preserving user code
  • Format-preserving TOML — add, bump, and remove deps without losing formatting
  • Automatic backups — force mode saves originals to .bluefox-backups/

Quick start

from bluefox_upgrade import (
    Upgrade, ReplaceFile, BumpDependency,
    plan_upgrade, check_conflicts, execute_upgrade,
    load_dotfile,
)

# Load project state
dotfile = load_dotfile(project_dir)

# Define upgrades
upgrades = [
    Upgrade(
        from_version="0.1.0",
        to_version="0.2.0",
        description="Update base image and bump FastAPI",
        operations=[
            ReplaceFile(path="Dockerfile", template="dockerfile_v2.jinja", description="update base image"),
            BumpDependency(name="fastapi", old_spec=">=0.115", new_spec=">=0.120"),
        ],
    ),
]

# Plan → check → execute
plan = plan_upgrade(dotfile, upgrades, target="0.2.0")
conflicts = check_conflicts(plan, project_dir, dotfile)
result = execute_upgrade(plan, project_dir, dotfile, render_template)

Requirements

  • Python 3.12+
  • pydantic >= 2.0
  • pyyaml >= 6.0
  • tomlkit >= 0.13

Next steps