feat(inbound-api): surface method compile errors to operators — api-method validate/recompile + compile state on get (ScadaBridge#75)

The data plane answers a broken inbound method with the generic "Script
compilation failed for this method"; the Roslyn diagnostic reached only the
central log, and the known-bad cache could not be observed or reset per method.

- InboundScriptExecutor keeps the diagnostics with each known-bad record and
  exposes GetCompileState(name, currentScript): IsCompiled / IsKnownBad /
  LastCompileError, judged against the current script text (a record for older
  text is reported as not compiled yet).
- Management: ValidateApiMethodCommand (compile the stored script, return
  ApiMethodCompileResult, register nothing, cache untouched) and
  RecompileApiMethodCommand (CompileAndRegister without re-sending the entity,
  drops the node's ApiMethodCache row, audited "Recompile"). Both Designer, like
  UpdateApiMethod; dispatched through the shared ApiMethodCompileOperations.
  GetApiMethod keeps the entity fields top-level and adds isCompiled,
  isKnownBad, lastCompileError and compileStateNode. Compile state is per
  central node and every result names the node.
- CLI: api-method validate --id, api-method recompile --id.
- Central UI: the API-method edit page shows the saved script's compile state
  and last error, with Validate and Recompile actions (same operations, same
  Designer gate, fresh DI scope).
- RequiredRoleMatrixTests entries; ManagementSurfaceParityTests covers the new
  CLI leaves; ApiMethodCompileDiagnosticsTests + an executor CompileState test.
- Docs: CLI README, Component-CLI/ManagementService/InboundAPI, components/*.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
This commit is contained in:
Joseph Doherty
2026-11-09 15:28:41 -05:00
parent 65ffa1dad4
commit 3dd492a77f
18 changed files with 542 additions and 15 deletions
@@ -7,3 +7,18 @@ public record CreateApiMethodCommand(string Name, string Script, int TimeoutSeco
/// <param name="TraceAllCalls">Flow Debugger (design 2026-09-05 §5.2): <c>null</c> leaves the stored value unchanged so an older CLI never resets it.</param>
public record UpdateApiMethodCommand(int ApiMethodId, string Script, int TimeoutSeconds, string? ParameterDefinitions, string? ReturnDefinition, bool? TraceAllCalls = null);
public record DeleteApiMethodCommand(int ApiMethodId);
/// <summary>
/// Compiles the method's stored script on the receiving central node and returns the
/// diagnostics, without registering the handler or touching the known-bad cache
/// (ScadaBridge#75). Operators see the real compile error here; the data plane keeps
/// returning its generic message.
/// </summary>
/// <param name="ApiMethodId">The API method to validate.</param>
public record ValidateApiMethodCommand(int ApiMethodId);
/// <summary>
/// Re-runs <c>CompileAndRegister</c> for the method's stored script on the receiving central
/// node, replacing its cached handler or known-bad record, without re-sending the entity
/// (ScadaBridge#75). Returns the diagnostics.
/// </summary>
/// <param name="ApiMethodId">The API method to recompile.</param>
public record RecompileApiMethodCommand(int ApiMethodId);
@@ -0,0 +1,25 @@
namespace ZB.MOM.WW.ScadaBridge.Commons.Types.InboundApi;
/// <summary>
/// Result of <c>ValidateApiMethodCommand</c> / <c>RecompileApiMethodCommand</c>
/// (ScadaBridge#75): the outcome of compiling an inbound API method's stored script on one
/// central node, with the compiler / trust-model diagnostics an operator needs.
/// </summary>
/// <param name="ApiMethodId">The API method id.</param>
/// <param name="Name">The API method name.</param>
/// <param name="Success">True when the script compiled.</param>
/// <param name="Errors">The compile / trust-model errors; empty on success.</param>
/// <param name="Node">The central node that compiled it (compile state is per node), when known.</param>
public sealed record ApiMethodCompileResult(
int ApiMethodId, string Name, bool Success, IReadOnlyList<string> Errors, string? Node);
/// <summary>
/// One central node's runtime compile state for an inbound API method (ScadaBridge#75),
/// judged against the method's current stored script.
/// </summary>
/// <param name="IsCompiled">A handler compiled from the current script is cached on this node.</param>
/// <param name="IsKnownBad">The current script failed to compile on this node; requests fast-fail.</param>
/// <param name="LastCompileError">The diagnostics of that failure, when <paramref name="IsKnownBad"/>.</param>
/// <param name="Node">The central node the state was read from, when known.</param>
public sealed record ApiMethodCompileStatus(
bool IsCompiled, bool IsKnownBad, string? LastCompileError, string? Node);