fix(zfa build): scaffold build.yaml when missing, fail loudly when zorphy builder unregistered (#276)

lib/src/commands/build_command.dart

@@ -1,5 +1,8 @@
 import 'dart:io';
 import 'package:args/command_runner.dart';
+import 'package:path/path.dart' as p;
+
+import 'build_yaml_guard.dart';
 
 class BuildCommand extends Command {
   @override
@@ -40,6 +43,10 @@ class BuildCommand extends Command {
       await _cleanBuildCache();
     }
 
+    // Self-healing pre-flight (zuraffa#276): ensure build.yaml registers the
+    // zorphy builder, otherwise build_runner exits 0 having written 0 outputs
+    // and we'd silently report success. Run BEFORE announcing the build so a
+    // misconfigured project fails fast without invoking build_runner.
     if (dryRun) {
       print('🔍 Dry-run mode: previewing changes...');
       print('   Entities: $entityCount, Dart files: $dartFileCount');
@@ -50,20 +57,31 @@ class BuildCommand extends Command {
           '   🧠 Smart merge: will preserve user code and @preserve blocks',
         );
       }
+      _reportBuildYamlDryRun();
       print('');
     } else {
-      print('🔨 Running build_runner build...');
       print('   Entities: $entityCount, Dart files: $dartFileCount');
       if (force) {
         print('   ⚠️  Force mode: regenerating from scratch');
       }
+      final guardResult = await _ensureBuildYaml();
+      if (!guardResult) {
+        // _ensureBuildYaml already printed an actionable error.
+        exit(1);
+      }
+      print('🔨 Running build_runner build...');
     }
 
     final exitCode = await _runBuild();
 
     if (exitCode == 0) {
       if (!dryRun) print('');
       print(dryRun ? '✅ Dry-run completed' : '✅ Build completed successfully');
+      // Safety net: if build_runner wrote 0 outputs while @Zorphy sources
+      // exist, warn loudly so silent regressions don't slip through.
+      if (!dryRun) {
+        _warnIfNoOutputsGenerated();
+      }
     } else if (!clean) {
       print(
         '\n⚠️  Build failed (exit $exitCode). Retrying with clean cache...',
@@ -72,6 +90,7 @@ class BuildCommand extends Command {
       final retryCode = await _runBuild();
       if (retryCode == 0) {
         print('\n✅ Build completed successfully after cache clean');
+        _warnIfNoOutputsGenerated();
       } else {
         print('\n❌ Build failed with exit code $retryCode');
       }
@@ -80,12 +99,115 @@ class BuildCommand extends Command {
     }
   }
 
+  /// Ensures `build.yaml` is in a state that lets build_runner produce zorphy
+  /// outputs. Returns `true` when the build may proceed; `false` when the
+  /// project has a `build.yaml` that omits the zorphy builder (the caller
+  /// should abort — the user must fix their config).
+  Future<bool> _ensureBuildYaml() async {
+    final status = BuildYamlGuard.check();
+    switch (status) {
+      case BuildYamlStatus.ok:
+        return true;
+      case BuildYamlStatus.missing:
+        print(
+          '🛠  No build.yaml found — scaffolding one that registers the zorphy builder.',
+        );
+        await BuildYamlGuard.scaffold();
+        print('   Created: build.yaml');
+        return true;
+      case BuildYamlStatus.missingZorphyBuilder:
+        print(BuildYamlGuard.missingZorphyBuilderMessage);
+        return false;
+    }
+  }
+
+  /// Dry-run counterpart of [_ensureBuildYaml]: reports what would happen
+  /// without writing.
+  void _reportBuildYamlDryRun() {
+    final status = BuildYamlGuard.check();
+    switch (status) {
+      case BuildYamlStatus.ok:
+        break;
+      case BuildYamlStatus.missing:
+        print('   Would scaffold: build.yaml (registers zorphy builder)');
+        break;
+      case BuildYamlStatus.missingZorphyBuilder:
+        print(
+          '   ⚠️  build.yaml exists but omits the zorphy builder — build would write 0 outputs.',
+        );
+        print('       Add `zorphy:zorphy` under targets.\$default.builders.');
+        break;
+    }
+  }
+
+  /// Warns (non-fatally) when build_runner exited 0 but produced no `.zorphy`
+  /// / `.g.dart` outputs despite `@Zorphy`-annotated sources being present.
+  /// Catches misconfigurations the pre-flight check can't detect statically.
+  void _warnIfNoOutputsGenerated() {
+    try {
+      final hasZorphySources = _hasZorphyAnnotatedSources();
+      final hasOutputs = _hasGeneratedOutputs();
+      if (hasZorphySources && !hasOutputs) {
+        print(
+          '\n⚠️  build_runner wrote 0 outputs although @Zorphy sources exist.\n'
+          '   Check build.yaml registers `zorphy:zorphy` for lib/src/** and\n'
+          '   that the annotated files are under the configured generate_for\n'
+          '   glob. Run `zfa setup` to regenerate a known-good build.yaml.',
+        );
+      }
+    } catch (_) {
+      // Best-effort safety net — never fail the build from this path.
+    }
+  }
+
+  bool _hasGeneratedOutputs() {
+    final libDir = Directory('lib');
+    if (!libDir.existsSync()) return false;
+    bool found = false;
+    for (final entity in libDir.listSync(recursive: true)) {
+      if (entity is File) {
+        final name = p.basename(entity.path);
+        if (name.endsWith('.zorphy.dart') || name.endsWith('.g.dart')) {
+          found = true;
+          break;
+        }
+      }
+    }
+    return found;
+  }
+
+  bool _hasZorphyAnnotatedSources() {
+    final libDir = Directory('lib');
+    if (!libDir.existsSync()) return false;
+    bool found = false;
+    for (final entity in libDir.listSync(recursive: true)) {
+      if (entity is File && entity.path.endsWith('.dart')) {
+        // Skip generated files themselves.
+        final name = p.basename(entity.path);
+        if (name.endsWith('.zorphy.dart') || name.endsWith('.g.dart')) continue;
+        try {
+          final src = entity.readAsStringSync();
+          if (src.contains('@Zorphy') || src.contains('@ZorphyMixin')) {
+            found = true;
+            break;
+          }
+        } catch (_) {
+          // Ignore unreadable files.
+        }
+      }
+    }
+    return found;
+  }
+
   Future<int> _runBuild() async {
-    final args = [
+    // `--delete-conflicting-outputs` was removed in build_runner 2.16.0 and
+    // emits a "These options have been removed" warning on every invocation.
+    // build_runner now resolves conflicting outputs via the build cache, so
+    // the flag is no longer needed.
+    final args = <String>[
       'run',
       'build_runner',
       'build',
-      '--delete-conflicting-outputs',
     ];
 
     final process = await Process.start(

lib/src/commands/build_yaml_guard.dart

@@ -0,0 +1,93 @@
+import 'dart:io';
+
+import 'package:path/path.dart' as p;
+
+import '../core/dependencies/dependency_wirer.dart';
+
+/// Outcome of inspecting a project's `build.yaml` from the build command.
+enum BuildYamlStatus {
+  /// No `build.yaml` exists at the project root. [BuildYamlGuard.scaffold]
+  /// can create one that registers the zorphy builder.
+  missing,
+
+  /// A `build.yaml` exists but it does not register the `zorphy:zorphy`
+  /// builder. build_runner will exit 0 having written 0 outputs, silently.
+  /// The user must be told to add the zorphy builder registration.
+  missingZorphyBuilder,
+
+  /// A `build.yaml` exists and registers the `zorphy:zorphy` builder.
+  ok,
+}
+
+/// Self-healing guard for `zfa build`.
+///
+/// Before delegating to `build_runner`, [BuildCommand] asks this guard whether
+/// the project's `build.yaml` is in a state that will actually produce
+/// `.zorphy.dart` / `.g.dart` outputs. When the file is missing, the build
+/// command scaffolds it (reusing [DependencyWirer.buildYamlContent]); when the
+/// file exists but omits the zorphy builder, the build command fails loudly
+/// with an actionable error instead of silently reporting success with 0
+/// outputs (zuraffa#276).
+class BuildYamlGuard {
+  /// The builder key that must appear in `build.yaml` for zorphy codegen to
+  /// run. Matches `DependencyWirer.buildYamlContent`.
+  static const String zorphyBuilderKey = 'zorphy:zorphy';
+
+  /// Returns the current [BuildYamlStatus] for [projectRoot]
+  /// (defaults to [Directory.current]).
+  static BuildYamlStatus check({String? projectRoot}) {
+    final root = projectRoot ?? Directory.current.path;
+    final file = File(p.join(root, 'build.yaml'));
+    if (!file.existsSync()) {
+      return BuildYamlStatus.missing;
+    }
+    final contents = file.readAsStringSync();
+    if (!_registersZorphyBuilder(contents)) {
+      return BuildYamlStatus.missingZorphyBuilder;
+    }
+    return BuildYamlStatus.ok;
+  }
+
+  /// Scaffolds a `build.yaml` that registers the zorphy + json_serializable
+  /// builders. Only call when [check] returned [BuildYamlStatus.missing] —
+  /// never overwrite an existing `build.yaml`.
+  static Future<void> scaffold({String? projectRoot}) async {
+    final root = projectRoot ?? Directory.current.path;
+    final file = File(p.join(root, 'build.yaml'));
+    await file.writeAsString(DependencyWirer.buildYamlContent);
+  }
+
+  /// True when [contents] enables the `zorphy:zorphy` builder.
+  ///
+  /// Accepts either the `builders:` mapping form or a bare `zorphy:zorphy`
+  /// reference, and tolerates leading whitespace. This is intentionally a
+  /// substring/regex check rather than a full YAML parse so the guard stays
+  /// dependency-free and robust to hand-edited formatting.
+  static bool _registersZorphyBuilder(String contents) {
+    if (contents.isEmpty) return false;
+    // Match `zorphy:zorphy` possibly followed by `:` (mapping) or whitespace,
+    // at the start of a line (builder keys are map keys under `builders:`).
+    final re = RegExp(r'^\s*zorphy:zorphy\s*:?', multiLine: true);
+    return re.hasMatch(contents);
+  }
+
+  /// The actionable error message shown when `build.yaml` exists but does not
+  /// register the zorphy builder. Kept here so tests can assert against it.
+  static const String missingZorphyBuilderMessage = '''
+❌ build.yaml exists but does not register the zorphy builder.
+
+   build_runner ran successfully but wrote 0 outputs because no builder is
+   configured to process @Zorphy annotations. Add the following under
+   `targets:\$default.builders:` in build.yaml:
+
+       builders:
+         zorphy:zorphy:
+           enabled: true
+           generate_for:
+             - lib/src/**
+             - test/**
+
+   Alternatively, run `zfa setup` to regenerate a correct build.yaml, or
+   delete build.yaml and re-run `zfa build` to have it scaffolded for you.
+''';
+}