[3.x] Empty the entire output directory before every build

[emmadesilva]

Makes the site output directory disposable build output that is recreated from source on every build.

Follows on from #2585, which added _static as the source-controlled home for arbitrary root-level files. That was the only reason the cleaner had to preserve unknown files, so it no longer needs to.

User-facing changes

• The whole output directory is emptied before every build, including dotfiles and nested directories. In v2 only HTML and JSON files plus the media directory were removed, so anything else left in _site survived indefinitely — including output whose _static source had since been deleted, which is the bug that motivated this.
• Removed hyde.empty_output_directory and hyde.safe_output_directories, along with the confirmation prompt.
• The build fails with an InvalidConfigurationException when the output directory is the project root, escapes the project, or is reached through a symbolic link.

Local builds now match what a clean CI or GitHub Pages build has always produced: if a file should exist after a build, it comes from source.

The safelist and its prompt were a safeguard on a destructive operation, and that safeguard is replaced rather than dropped. _static removes the reason to selectively preserve unknown files in the output; the deterministic-build contract removes the reason for empty_output_directory; but emptying a directory recursively still needs a guard. The replacement is structural and non-interactive, so it also works in CI, and it runs before the build writes anything, so it covers creating a site in the wrong place as well as emptying one.

Validation rules

OutputDirectoryValidator rejects a configured hyde.output_directory that:

• resolves to the project root (empty, or only . segments);
• contains a .. segment;
• has any path component that is a symbolic link;
• overlaps a directory the project needs.

The overlap rule is what keeps app, .git, vendor, and the source directories out of reach. The Hyde-owned entries are derived from runtime state — every registered page class's sourceDirectory() (which already includes source_root), the configured media directory, and _static — so a project that renames its source directories is protected at its own names. Only the structural project directories are a fixed list: .git, .github, app, config, node_modules, resources, tests, vendor. Overlap is checked in both directions, so neither app nor app/storage is accepted, and an output directory that would contain a source directory is rejected too. The comparison is case-insensitive on every platform, because case-insensitive filesystems resolve APP to app/ — verified here, where is_dir('APP') is true. realpath() would not have closed this: on macOS it echoes back the requested casing rather than the canonical one. Both sides also go through the same lexical segment normalization, so a media directory or source root configured as ./assets is matched by an output directory of assets; upwards traversal is left intact there and rejected separately for the output path.

This is not the safelist inverted. The safelist trusted a closed set of output names and interrogated everything else; this allows any name and refuses only what Hyde knows it must not destroy. _site, docs, build, dist, public, and foo/bar are all accepted without a prompt.

The symlink rule is what makes the traversal rules sound. Laravel's deleteDirectory() only skips symlinked children — it iterates the root path it is given, so _site -> app would have emptied app/. That is verified by test: with the symlink check removed, the target directory really is emptied. Rejecting links anywhere in the chain also covers an intermediate link whose final directory does not exist yet, where realpath() returns false and no destination-based check can see where the path leads.

Comparing paths as strings was the earlier approach and is deliberately gone: Hyde's path_join() always joins with / while the kernel base path keeps native separators, so a realpath() prefix comparison would have rejected valid fresh builds on Windows. Working from the configured relative path's segments avoids the comparison entirely.

Internal changes

• Validation runs in BuildSiteCommand::runPreBuildActions() before any work, because a misconfigured output directory is fatal to the whole build rather than to one task. Build tasks report failures without aborting, so a guard only inside CleanSiteDirectory would have skipped the delete and then let compileStaticPages() write the site to the bad path anyway.
• CleanSiteDirectory::handle() calls the same validator, so the destructive primitive keeps its own safety boundary when the task is invoked directly through BuildTaskService. There the exception is caught as a task failure, but nothing is deleted.
• CleanSiteDirectory is now registered unconditionally, so BuildTaskServiceUnitTest expectations include it.
• Fixed StaticFilePassthroughTest leaving an empty _static behind, which made a repeat run fail.

Testing

UnitFramework, FeatureFramework, and FeatureHyde pass, apart from the known pre-existing FeaturedImageUnitTest failure on PHP 8.5 (MediaFile::findHash()). HydeStan reports no errors.

Covered: dotfiles and nested directories removed; _static output disappearing when its source is deleted; project root, .. escape, output-directory symlink, and intermediate symlink all rejected; nothing created outside the project; a nested output directory that does not exist yet still builds; and direct CleanSiteDirectory invocation refusing to empty an invalid destination.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (04c2b13) to head (573db00).
⚠️ Report is 1 commits behind head on master.

Additional details and impacted files

@@             Coverage Diff             @@
##              master     #2586   +/-   ##
===========================================
  Coverage     100.00%   100.00%           
+ Complexity      1815      1811    -4     
===========================================
  Files            184       184           
  Lines           4506      4494   -12     
===========================================
- Hits            4506      4494   -12     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.