feat(file-ops): Phase 3 - deprecate embedded component

Implemented Phase 3 of the file operations migration plan:

**Phase 3: Deprecation (Month 3)**
- Add deprecation warnings to embedded component
- Create comprehensive migration guide
- Document timeline for removal in v2.0.0

Changes:

1. **Deprecation Warning in Embedded Binary** (tools/file_ops/main.go)
   - Clear, boxed warning message on every execution
   - Highlights benefits of external component:
     • 100x faster startup
     • Cryptographic signing
     • SLSA provenance
   - Can be silenced with FILE_OPS_NO_DEPRECATION_WARNING=1
   - Points to migration guide

2. **Migration Guide** (docs/MIGRATION.md)
   - Comprehensive guide for users
   - Explains why to migrate (performance, security, maintenance)
   - Quick start: most users already using external (no action needed)
   - Timeline showing all 4 phases
   - Troubleshooting section

3. **Build Flag Documentation** (toolchains/BUILD.bazel)
   - Updated comments with deprecation notice
   - Clear marking of "embedded" as deprecated
   - References to MIGRATION.md
   - Timeline for removal in v2.0.0

4. **Test Documentation** (test/file_ops_integration/README.md)
   - Updated with Phase 3 completion status
   - All 4 phases documented
   - Clear progression: Phase 1 ✅, Phase 2 ✅, Phase 3 ✅, Phase 4 🔜

**Testing:**
✅ Deprecation warning displays correctly
✅ Warning can be silenced with env var
✅ File operations still work with embedded
✅ External remains default (no change)

**Timeline:**
- Phase 1: Week 1-2 ✅ (Optional integration)
- Phase 2: Week 5-6 ✅ (External default with AOT)
- **Phase 3: Month 3 ✅ (Deprecation - THIS COMMIT)**
- Phase 4: v2.0.0 🔜 (Complete removal)

**For Users:**
Most users don't need to do anything! External component with AOT
is already the default. Only users explicitly using
`--//toolchains:file_ops_source=embedded` need to remove that flag.

See docs/MIGRATION.md for full details.

Author: avrabe

test/file_ops_integration/README.md

@@ -137,23 +137,33 @@ bazel test //test/file_ops_integration:external_implementation_test \\
 2. Performance regression tracking
 3. Prepare for Phase 2 (make external default)
 
-## Phase 1 Validation Status
+## Phase Status
 
-**Week 1-2: Implementation** ✅ COMPLETE
+**Phase 1: Optional Integration** ✅ COMPLETE (Week 1-2)
 - External component integrated
 - Build flags configured
 - Wrapper binary functional
+- Embedded as default, external opt-in
 
-**Week 3-4: Testing** ✅ COMPLETE
-- Test suite created ✅
-- Signature verification passing ✅
-- Integration validation complete ✅
-
-**Week 5-6: Phase 2** ✅ COMPLETE
+**Phase 2: External as Default** ✅ COMPLETE (Week 5-6)
 - Upgraded to v0.1.0-rc.3 AOT variant
-- AOT extraction integrated for all platforms
-- External with AOT is now the default
+- AOT extraction integrated for all 6 platforms
+- **External with AOT is now the default**
 - 100x faster startup with native code execution
+- Embedded still available as fallback
+
+**Phase 3: Deprecation** ✅ COMPLETE (Month 3)
+- **⚠️ Embedded component is now DEPRECATED**
+- Deprecation warnings added to embedded binary
+- Migration guide created: `docs/MIGRATION.md`
+- Build flag documentation updated
+- Embedded will be removed in v2.0.0 (Phase 4)
+
+**Phase 4: Removal** 🔜 PLANNED (v2.0.0)
+- Complete removal of `tools/file_ops/` (embedded component)
+- External component only
+- Smaller repository size
+- Simplified toolchain configuration
 
 ## Security Verification
 

toolchains/BUILD.bazel

@@ -250,14 +250,20 @@ string_flag(
     ],
 )
 
-# File Operations Source Selection (Phase 2: External with AOT)
-# Build flag for choosing between embedded and external component
+# File Operations Source Selection
+# Phase 3: DEPRECATION - Embedded component will be removed in v2.0.0
+#
+# The embedded component (tools/file_ops/) is DEPRECATED and will be removed in v2.0.0.
+# See docs/MIGRATION.md for migration guide.
+#
+# Default is "external" with AOT support (100x faster startup)
+# Only use "embedded" if you encounter critical issues - this option will be removed soon.
 string_flag(
     name = "file_ops_source",
-    build_setting_default = "external",  # Phase 2: External with AOT is now default
+    build_setting_default = "external",  # Phase 2+: External with AOT is default
     values = [
-        "embedded",  # Use embedded Go binary (legacy fallback)
-        "external",  # Use external pre-built WASM component with AOT (default, Phase 2)
+        "embedded",  # DEPRECATED - Will be removed in v2.0.0 (Phase 4)
+        "external",  # RECOMMENDED - External component with AOT (default)
     ],
 )
 

tools/file_ops/main.go

@@ -340,6 +340,31 @@ func (r *FileOpsRunner) validateConfig() error {
 }
 
 func main() {
+	// Phase 3 Deprecation Warning (Month 3)
+	// This embedded file operations tool is deprecated and will be removed in v2.0.0
+	if os.Getenv("FILE_OPS_NO_DEPRECATION_WARNING") == "" {
+		fmt.Fprintf(os.Stderr, "\n")
+		fmt.Fprintf(os.Stderr, "╔════════════════════════════════════════════════════════════════════════╗\n")
+		fmt.Fprintf(os.Stderr, "║                         DEPRECATION WARNING                            ║\n")
+		fmt.Fprintf(os.Stderr, "╠════════════════════════════════════════════════════════════════════════╣\n")
+		fmt.Fprintf(os.Stderr, "║ The embedded file operations component is DEPRECATED.                 ║\n")
+		fmt.Fprintf(os.Stderr, "║                                                                        ║\n")
+		fmt.Fprintf(os.Stderr, "║ Please switch to the external component with AOT support:             ║\n")
+		fmt.Fprintf(os.Stderr, "║   • 100x faster startup with native code execution                    ║\n")
+		fmt.Fprintf(os.Stderr, "║   • Cryptographically signed with Cosign                              ║\n")
+		fmt.Fprintf(os.Stderr, "║   • SLSA provenance for supply chain security                         ║\n")
+		fmt.Fprintf(os.Stderr, "║                                                                        ║\n")
+		fmt.Fprintf(os.Stderr, "║ The external component is now the DEFAULT. To use it:                 ║\n")
+		fmt.Fprintf(os.Stderr, "║   (No action needed - already default in Phase 2)                     ║\n")
+		fmt.Fprintf(os.Stderr, "║                                                                        ║\n")
+		fmt.Fprintf(os.Stderr, "║ This embedded version will be REMOVED in v2.0.0 (Phase 4)            ║\n")
+		fmt.Fprintf(os.Stderr, "║                                                                        ║\n")
+		fmt.Fprintf(os.Stderr, "║ To silence this warning: FILE_OPS_NO_DEPRECATION_WARNING=1           ║\n")
+		fmt.Fprintf(os.Stderr, "║ Migration guide: docs/MIGRATION.md                                     ║\n")
+		fmt.Fprintf(os.Stderr, "╚════════════════════════════════════════════════════════════════════════╝\n")
+		fmt.Fprintf(os.Stderr, "\n")
+	}
+
 	if len(os.Args) != 2 {
 		fmt.Fprintf(os.Stderr, "Usage: %s <config.json>\n", os.Args[0])
 		fmt.Fprintf(os.Stderr, "\nHermetic file operations tool for Bazel rules_wasm_component\n")