Validating changes

buildprint check validates BubbleScript changes and shows what they will change in Bubble before anything is applied.

When validation runs

An agent runs validation after editing BubbleScript and before running buildprint apply.

Edit BubbleScript
      ↓
Run a check
      ↓
Review diagnostics and planned changes
      ↓
Fix any errors and check again
      ↓
Apply the change

Checking only reads the local workspace. It does not change the Bubble app.

Run a targeted check

A targeted check gives fast feedback while the agent works on one file or folder.

buildprint check pages/Dashboard/page.ts
buildprint check data-types/Task.ts
buildprint check pages/Dashboard/workflows

The check includes the selected source and any related files needed to validate it.

A targeted check cannot make the workspace ready to apply. After it passes, the agent must run a full check.

Run a full check

A full check validates all changed BubbleScript and produces the final planned change list.

buildprint check

If it passes, the final line confirms that the BubbleScript changes are ready to apply.

Read a diagnostic

Each diagnostic explains where the problem is, how serious it is and what the agent should do next.

pages/Dashboard/page.ts:42:18 error BSP1204
Unknown element "Button save".

  Action: Use an element name from the current page.
  Accepted: Button save task, Button cancel

data-types/Enquiry Message.ts:16:18 error BSP8020 This privacy rule cannot grant search access because its condition uses This Thing's X's Y. (expression site: privacyRule ["dataType",null,"enquiry_message"].privacyRules.participants_can_view_messages_)
  Action: Set search_for to false or use no more than one field lookup from thisItem()

data-types/Listing.ts:31:18 error BSP8020 This privacy rule cannot grant search access because its condition uses This Thing's X's Y. (expression site: privacyRule ["dataType",null,"listing"].privacyRules.shop_owner_can_view_listing_)
  Action: Set search_for to false or use no more than one field lookup from thisItem()

A diagnostic can contain:

• File, line and column — the source location that needs attention.

• Severity — error, warning or info.

• Code — a stable identifier for the type of diagnostic.

• Message — what is invalid or needs review.

• Action — a suggested correction.

• Accepted — valid names or values when Buildprint can provide them.

Errors block apply. Warnings and information can highlight behaviour the agent should review even when the source is valid.

Review planned changes

A successful check describes the Bubble changes produced by the edited source.

Buildprint checked 2 BubbleScript files.
Apply includes 2 files.
  Change: Add field "Status" in "Task"
  Change: Rename element "Button save" to "Button save task"
Full check passed. The BubbleScript changes are ready to apply.

The change list can include:

• new nodes;

• renames;

• type changes;

• layout, appearance or other presentation changes;

• privacy-rule changes;

• option-value changes and reordering;

• soft deletion and restoration; and

• permanent deletion where that Bubble node supports it.

The agent should compare this list with the requested task before applying. Unexpected changes usually mean the source edit is too broad or an existing identity was not preserved.

Fix safe source problems

--fix applies supported automatic fixes to the BubbleScript source and checks it again.

buildprint check --fix

The output lists any files Buildprint changed. The agent should review those edits before applying.

Buildprint only fixes problems with a defined safe source change. Other diagnostics still need a manual edit.

Filter the output

The agent can reduce the output when it needs to focus on a particular severity.

buildprint check --level warning
buildprint check --level error

warning includes warnings and errors. error shows blocking errors only.

For tools that need structured results, use JSON output:

buildprint check --json

Run a deep check

--deep performs a slower whole-app validation when the change needs extra confidence. Most of the time this shouldn't be done, as it is slower, and BubbleScript workspaces are structured so that changes are localised and only changes need to be validated.

buildprint check --deep

Use it after a broad refactor, before a major release or when a change affects many related parts of the app. Normal edits usually only need targeted checks while working and one full check before apply.

Understand validation results

Every check ends with a clear next action.

• Apply is blocked — fix each reported error and run the check again.

• Targeted check passed — run a full buildprint check.

• Full check passed — the current BubbleScript changes are ready to apply.

When validation becomes out of date

A previous full check no longer applies after the BubbleScript source or its Bubble branch changes.

The agent must check again after:

• editing any affected BubbleScript;

• running buildprint sync;

• resolving a conflict; or

• another change reaches the same Bubble branch.

If the checked source and current state no longer match, buildprint apply stops instead of applying the older result.