Release 0.146.0: Comprehensive Build Validation for Deployment Safety

We’re excited to announce the release of Screeps GPT version 0.146.0, focused on strengthening deployment safety through comprehensive build validation. This release introduces context-aware size thresholds that prevent broken or incomplete builds from reaching production.

Key Features

Context-Aware Build Validation

This release implements a sophisticated two-tier validation system that ensures build artifacts meet minimum quality standards before deployment:

• Monolithic bundles (main.js): Now require a minimum of 50KB to ensure the presence of both kernel and runtime components
• Modular components: Maintain a flexible 500-byte minimum to accommodate type-only modules and small utilities
• Comprehensive test coverage: 11 new regression test cases validate threshold enforcement and edge cases

Technical Details

The Problem: Silent Build Failures

Prior to this release, the build validation system used a single static threshold (500 bytes) for all files. While this prevented completely empty builds from deploying, it couldn’t detect more subtle failures where the bundler produced partial output—a skeleton file with imports but missing the actual implementation code.

For a Screeps bot, deploying a partial build is catastrophic. The main.js file must contain the complete kernel orchestration system, all runtime managers, and the game loop implementation. A 5KB main.js file might technically be “valid JavaScript” but would be completely non-functional in the Screeps environment.

The Solution: Context-Aware Thresholds

The fix introduces intelligent size validation that adapts based on the file being validated:

File: packages/utilities/scripts/lib/buildProject.ts

// Context-aware minimum size thresholds
const MIN_SIZE = checkLoopExport ? 50 * 1024 : 500; // 50KB for main.js, 500B for modules

The checkLoopExport parameter already existed in the codebase—it’s used to verify that main.js exports the required loop function. By leveraging this same parameter for size validation, we can distinguish between:

1. Monolithic builds (main.js): Must export loop() and contain ≥50KB of code
2. Modular builds (individual modules): No loop() export required, minimum 500 bytes

Why 50KB?

The 50KB threshold for main.js was determined through empirical analysis of successful production builds. A fully functional Screeps bot with the kernel, behavior controller, infrastructure managers, and all supporting systems typically produces a bundle in the 95KB-384KB range depending on the build mode (single bundle vs. modular).

Setting the threshold at 50KB provides a safety margin that:

• Catches catastrophic build failures (partial compilation, missing dependencies)
• Allows for future code removal or optimization without triggering false positives
• Remains well below the typical production build size, ensuring reliable detection

Implementation Details

The validation logic in validateFile() now performs a two-stage check:

1. Size validation: Compares file size against the context-appropriate threshold
2. Content validation: For main.js, verifies the presence of the loop export

File: packages/utilities/scripts/lib/buildProject.ts (excerpt)

const fileSize = statSync(filePath).size;
const MIN_SIZE = checkLoopExport ? 50 * 1024 : 500;

if (fileSize === 0) {
  throw new Error(`Build artifact ${fileName} is empty (0 bytes)`);
}

if (fileSize < MIN_SIZE) {
  const sizeType = checkLoopExport ? "main bundle" : "module";
  const minSizeFormatted = checkLoopExport ? "50KB" : "500 bytes";
  throw new Error(
    `Build artifact ${fileName} is too small (${fileSize} bytes) - ` +
    `${sizeType} requires at least ${minSizeFormatted}`
  );
}

This approach maintains the existing validation logic while adding context-aware size enforcement, ensuring that both monolithic and modular builds are properly validated according to their specific requirements.

Bug Fixes

This release addresses a critical deployment safety concern:

• Build Validation Enhancement (Issue #729): The previous single-threshold validation could miss broken builds where the bundler produced partial output. The new context-aware system prevents incomplete builds from passing validation and reaching production.

Testing & Quality Assurance

Quality and reliability are paramount when dealing with automated deployments. This release includes extensive test coverage:

• 11 regression test cases covering:
  • Main bundle threshold enforcement (50KB minimum)
  • Module threshold enforcement (500 bytes minimum)
  • Edge cases (files just above/below thresholds)
  • Content validation for main.js
  • Error message accuracy and clarity

File: tests/regression/build-validation-thresholds.test.ts

The test suite uses actual file fixtures and simulates real-world build scenarios to ensure the validation logic works correctly across all configurations (monolithic, modular, development, production).

Impact

Development Workflow

This release strengthens the deployment pipeline’s quality gates without impacting the development workflow. Developers continue to work as usual, but now have stronger guarantees that broken builds will be caught before deployment.

Deployment Safety

The most significant impact is on deployment safety. By catching partial or incomplete builds during the CI/CD pipeline, we prevent scenarios where:

1. A broken build deploys to production
2. The bot stops functioning in the Screeps environment
3. Manual intervention is required to investigate and fix the issue
4. Valuable CPU cycles and game time are wasted

With context-aware validation, these scenarios are caught immediately during the build step, allowing for rapid iteration and fixes without impacting the live bot.

Foundation for Future Work

This enhancement also establishes a pattern for other validation improvements:

• Bundle size monitoring: Track build size trends over time to detect bloat
• Dependency analysis: Validate that critical dependencies are included
• Performance budgets: Enforce maximum bundle sizes for modular builds
• Content validation: Extend validation to check for specific runtime components

Design Rationale

Why Not Use AST Analysis?

One might ask: why use file size as a validation metric instead of analyzing the Abstract Syntax Tree (AST) to verify the presence of specific functions or classes?

The answer lies in simplicity and performance:

1. Speed: File size checks are instant; AST parsing adds 1-2 seconds to the build
2. Reliability: Size-based validation is immune to code reorganization or refactoring
3. Maintenance: No need to update validation logic when the codebase structure changes
4. Clarity: A 50KB threshold is easy to understand and reason about

That said, the existing content validation (checking for the loop export) does perform basic parsing, striking a balance between thoroughness and simplicity.

Why Not Use Git Hash Validation?

Another approach would be to track known-good build sizes and compare against historical data. We opted against this because:

• Flexibility: Code size naturally varies as features are added or removed
• False Positives: Legitimate optimizations might reduce bundle size below historical averages
• Complexity: Requires maintaining a database of historical build sizes and versions

The fixed 50KB threshold provides a clear, maintainable rule that will remain valid across the bot’s evolution.

What’s Next

Looking ahead, this validation enhancement paves the way for additional build-time quality checks:

• Bundle composition analysis: Verify that critical managers (Kernel, BehaviorController, etc.) are present
• Memory footprint validation: Ensure the bundle fits within Screeps memory constraints
• Performance regression detection: Track CPU usage of the bundled code
• Dependency security scanning: Validate that no vulnerable packages are included

For now, the focus remains on reliability: ensuring that every deployment contains a complete, functional bot.

Acknowledgments

This release addresses concerns raised in issue #729, demonstrating the value of systematic issue tracking and test-driven development. By creating comprehensive regression tests before implementing the fix, we ensure the problem stays solved.

Conclusion

Release 0.146.0 may appear modest in scope—a single validation enhancement—but its impact on deployment reliability is significant. By preventing broken builds from reaching production, we reduce downtime, improve developer confidence, and establish a pattern for future quality gates.

As the Screeps GPT project continues to evolve with increasingly sophisticated autonomous agents and automated workflows, strong validation at every stage becomes even more critical. This release represents another step toward truly reliable autonomous bot development.

---

Upgrade Instructions: This release is fully backward compatible. No configuration changes or manual intervention are required. Simply deploy the new version using the standard CI/CD pipeline.

Full Changelog: See CHANGELOG.md for complete release notes.