Apply Engine
The apply engine is the final stage of the pipeline. It plans a task set, backs up modified files, installs dependencies in one batch, runs the tasks, and reports errors.
Plan, then execute
Section titled “Plan, then execute”Planning is side-effect free, so a preview is exact and execution replays the plan unchanged.
The plan collects, for the selected tasks:
- Each task’s status, reusing statuses computed while the session opened
- The diffs for tasks that are not skipped or conflicting
- The dependencies each runnable task declares
- The unique file paths in the diffs, which are also the backup set
Execution replays the plan:
- Back up every affected file once and write a run manifest for the
undocommand. - Install the collected dependencies in one batch.
- Run each task’s apply in sequence, collecting per-task errors instead of aborting.
- Return the applied count, skipped count, collected errors, and timing.
Backups
Section titled “Backups”Before any file is modified, the engine writes a timestamped copy under .xtarterize/backups/ and indexes it in .xtarterize/backups/.index.json for restore. Each unique file path is backed up once per run, even when several tasks modify it. The .xtarterize/ directory is added to .gitignore automatically.
Error handling
Section titled “Error handling”Errors are collected and reported without aborting the run:
- A check that throws becomes a
conflictwith the error message, and the task is skipped. - A dry-run failure is reported and the task is skipped without a backup.
- A failed dependency install is recorded in the result. Tasks that need the missing packages fail individually, while file-only tasks still run.
- A failed apply is logged with the task id and message, and later tasks continue.
Backup or manifest failures stop execution before any task runs. Tasks declared from a synchronous or Promise-returning spec follow the same rules as Effect-based tasks.