Detect Dockerfile out of sync with npm package version

[ghostwriternr]

Right now, when users upgrade to a new version of the npm package, it happens often that they forget to update the version on the Dockerfile as well, due to which they run into out-of-sync compatibility issues.

I'd imagine the simplest solution right now is to embed an env variable as part of docker image we build on new releases that contains the version, and compare the npm package version with the image version on startup. Throw an error during development, and a warning on production.

[ghostwriternr]

@claude can you take a stab at this task? Take your time and look at all of these layers:

Where the dockerfile is currently present for the core package
Where initialization happens and how you can hit an endpoint on the container (bun control plane) to get the version from the image env and compare
Upon comparison, be able to detect if we're currently in development or production and throw an error in dev and warning on prod. TBH, I don't think we have a robust way to detect this right now, so if you don't find anything, just log for now with warning level
Make sure the changes are backward compatible? As in, if a user upgrades to a new version of npm package but as described doesn't update the image, they won't even get back a version response because the container doesn't have the new code paths. This should be handled cleanly
If you have any more questions, feel free to ask me. ultrathink

[claude]

Claude finished @ghostwriternr's task —— View job • claude/issue-131-20251022-1721 • Create PR ➔

---

Version sync detection implemented ✅

Tasks

• Read CLAUDE.md for repository guidelines
• Explore codebase structure and locate key files
• Find Dockerfile(s) for the core package
• Locate package.json and initialization code
• Understand the bun control plane architecture
• Implement version embedding in Dockerfile
• Implement version endpoint in container
• Add version client method in utility client
• Implement startup version checking with backward compatibility
• Add environment detection (dev/prod) and appropriate logging
• Add comprehensive tests for new functionality
• Commit and push changes
• Provide PR creation link

Implementation Summary

What was implemented:

1. Version Embedding in Docker Image

   • Modified Dockerfile to accept SANDBOX_VERSION build argument
   • Set as environment variable for runtime access
   • Updated all docker build scripts to pass version from package.json

2. Container Version Endpoint

   • Added /api/version endpoint in misc-handler.ts
   • Returns version from process.env.SANDBOX_VERSION
   • Registered route in routes/setup.ts

3. SDK Version Tracking

   • Created version.ts with SDK_VERSION constant
   • Added getVersion() method to UtilityClient
   • Handles backward compatibility (returns 'unknown' for old containers)

4. Automatic Version Checking

   • Implemented checkVersionCompatibility() in sandbox.ts
   • Runs asynchronously on sandbox startup
   • Logs warnings for version mismatches
   • Gracefully handles missing endpoints (old containers)

5. Test Coverage

   • Added tests for version endpoint in misc-handler.test.ts
   • Added tests for getVersion() in utility-client.test.ts
   • Includes backward compatibility test cases

Key Features:

• ✅ Version embedded in Docker image at build time
• ✅ HTTP endpoint to query container version
• ✅ Automatic startup version checking
• ✅ Warning logs for mismatches (not errors)
• ✅ Backward compatible with old containers
• ✅ Comprehensive test coverage

Files Changed:

• packages/sandbox/Dockerfile - Version build arg & env var
• packages/sandbox/package.json - Updated docker scripts
• packages/sandbox/src/version.ts - NEW SDK version constant
• packages/sandbox/src/sandbox.ts - Version checking logic
• packages/sandbox/src/clients/utility-client.ts - getVersion() method
• packages/sandbox/src/clients/index.ts - Export VersionResponse type
• packages/sandbox-container/src/handlers/misc-handler.ts - Version endpoint
• packages/sandbox-container/src/routes/setup.ts - Route registration
• packages/sandbox-container/tests/handlers/misc-handler.test.ts - Tests
• packages/sandbox/tests/utility-client.test.ts - Tests

---

Job Run | Branch