Chapter 5: Files, Diff, and Locking

Welcome to Chapter 5: Files, Diff, and Locking. In this part of bolt.diy Tutorial: Build and Operate an Open Source AI App Builder, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.

This chapter focuses on the most important safety layer in AI-assisted coding: how generated edits are reviewed, constrained, and reversible.

Why This Layer Is Critical

Model quality can still produce:

• logically plausible but incorrect changes
• unintended edits in adjacent files
• silent config or security regressions

Diff review and file controls are your primary defenses.

Safe Edit Lifecycle

flowchart TD
    A[Prompt Submitted] --> B[Candidate Patch Generated]
    B --> C[Diff Inspection]
    C --> D{Accept?}
    D -- No --> E[Reject and Refine Prompt]
    E --> A
    D -- Yes --> F[Apply Changes]
    F --> G[Run Validation Commands]
    G --> H{Pass?}
    H -- No --> I[Rollback or New Fix Iteration]
    H -- Yes --> J[Commit-ready State]

High-Risk File Categories

Lock or require elevated review for:

• authentication and authorization modules
• environment/config loaders
• deployment and infra descriptors
• billing/usage logic
• security-sensitive integrations

Treat these as protected zones in team workflows.

Diff Review Rubric

Lens	Review Question
Scope	Are only intended files touched?
Intent	Does each hunk map to prompt objective?
Side effects	Could this alter unrelated behavior?
Security	Any new secret handling, unsafe defaults, or auth drift?
Testability	Is there clear command evidence for correctness?

Reject Conditions (Non-Negotiable)

Reject the patch when any of these occur:

• unrelated file modifications
• unexplained dependency or build config edits
• broad formatting churn hiding logic changes
• validation command omitted or failing
• summary does not explain risky hunks

Snapshot and Rollback Strategy

Before large edits, capture a rollback point.

Recommended snapshot triggers:

• multi-directory changes
• migration or schema modifications
• provider/config policy edits
• security-sensitive code changes

Rollback is not failure; it is controlled experimentation.

Suggested Team Policy

1. every accepted patch must include validation evidence
2. critical-file edits need second reviewer or stricter approval
3. no direct acceptance for multi-file high-risk changes
4. run post-accept smoke checks before merge

Practical Diff Triage Pattern

When a patch is large:

1. group hunks by subsystem
2. review highest-risk files first
3. validate compile/tests after each accepted group
4. reject and split if risk cannot be reasoned about quickly

This keeps review human-scale.

Auditability Minimum Standard

For each accepted task, retain:

• prompt intent summary
• changed file list
• validation commands and outcomes
• rollback reference (if used)

This helps incident response and long-term quality analysis.

Chapter Summary

You now have a robust governance model for generated edits:

• diff-first acceptance
• protected file strategy
• rollback discipline
• audit-ready review evidence

Next: Chapter 6: Integrations and MCP

Source Code Walkthrough

app/lib/runtime/message-parser.ts

The message parser in app/lib/runtime/message-parser.ts processes the streamed LLM output and extracts file operations (create, update, delete) from the structured XML-like action tags bolt.diy uses in its system prompt.

This file is the core of the diff/files layer: it converts raw model text into typed FileAction objects that the runtime then applies. For the locking and diff governance patterns in this chapter, this is where you intercept generated changes before they reach disk — for example, to check whether an action targets a protected file path.

app/lib/stores/files.ts

The file store in app/lib/stores/files.ts is the in-memory representation of the virtual filesystem managed by bolt.diy's WebContainer runtime. It maps file paths to content and tracks dirty/modified state.

For diff and locking controls, this store is where you read the pre-edit content to construct a diff and where file-lock checks would be applied: if a file path is in the protected list, the store update should be blocked and surfaced to the user for review.

app/lib/runtime/action-runner.ts

The action runner in app/lib/runtime/action-runner.ts is responsible for executing parsed file and shell actions against the WebContainer. It reads from the message parser output and writes to the file store and terminal.

This is the last enforcement point before a change lands. Adding a pre-execution check here — comparing the target path against a deny list or requiring explicit approval — is the most direct way to implement the high-risk file protection patterns described in this chapter.

How These Components Connect

flowchart TD
    A[LLM streams action tags]
    B[message-parser.ts extracts FileActions]
    C[action-runner.ts queues actions]
    D{Protected file check}
    E[files.ts store updated]
    F[Diff shown to user]
    G[Change blocked or flagged]
    A --> B
    B --> C
    C --> D
    D -- allowed --> E
    E --> F
    D -- protected --> G