eco-helpers 3.2.16 → 3.2.17

data/lib/eco/api/usecases/graphql/samples/pages/template/csv_build/parser.rb

@@ -0,0 +1,98 @@
+require 'csv'
+
+module Eco::API::UseCases::GraphQL::Samples::Pages::Template
+  module CsvBuild
+    # Parse a columnar CSV describing ONE template into an ordered, grouped intermediate structure
+    # (stages → sections → fields) that the `Builder` turns into a WorkflowCommand batch.
+    #
+    # Format specifics live ENTIRELY in `FormatMap` (see its TODO about the ~mid-July format). The
+    # parser only groups RowSpecs by their declared hierarchy while PRESERVING first-seen order, so
+    # the emitted command batch is deterministic and dependency-safe.
+    #
+    #   parser = Parser.new(csv_string)          # or Parser.from_file(path)
+    #   tree   = parser.tree
+    #   tree   # => [ { name:, ordering:, sections: [ { heading:, layout:, ordering:, fields: [...] } ] } ]
+    class Parser
+      # Parsed field, ready for the builder (already format-agnostic).
+      Field = Struct.new(:label, :type, :required, :column, :description, :options, keyword_init: true)
+
+      def self.from_file(path)
+        new(File.read(path))
+      end
+
+      # @param source [String] CSV text (with a header row).
+      def initialize(source)
+        @source = source.to_s
+      end
+
+      # The grouped hierarchy: stages (first-seen order) → sections → fields.
+      def tree
+        @tree ||= build_tree
+      end
+
+      # Flat list of RowSpecs (post FormatMap mapping), skipping blank / header-only rows.
+      def row_specs
+        @row_specs ||= rows.map { |row| FormatMap.row_spec(row) }.
+          reject { |rs| rs.stage.nil? && rs.field_label.nil? }
+      end
+
+      private
+
+      def rows
+        table = CSV.parse(@source, headers: true)
+        table.map(&:to_h)
+      rescue CSV::MalformedCSVError => e
+        raise ArgumentError, "malformed template CSV: #{e.message}"
+      end
+
+      def build_tree
+        stages = {}
+        stage_order    = []
+        section_order  = Hash.new { |h, k| h[k] = [] }
+
+        row_specs.each do |rs|
+          next unless rs.stage # a field row must carry its stage (denormalised format)
+
+          stage = (stages[rs.stage] ||= new_stage(rs, stage_order))
+          section = ensure_section(stage, rs, section_order)
+          section[:fields] << build_field(rs) if rs.field_label
+        end
+
+        stage_order.map { |name| finalize_stage(stages[name]) }
+      end
+
+      def new_stage(row_spec, stage_order)
+        stage_order << row_spec.stage
+        { name: row_spec.stage, ordering: row_spec.stage_ordering, sections: {}, section_order: [] }
+      end
+
+      def ensure_section(stage, row_spec, _section_order)
+        heading = row_spec.section
+        key     = heading.to_s
+        stage[:sections][key] ||= begin
+          stage[:section_order] << key
+          { heading: heading, layout: row_spec.section_layout, ordering: row_spec.section_ordering, fields: [] }
+        end
+      end
+
+      def build_field(row_spec)
+        Field.new(
+          label:       row_spec.field_label,
+          type:        row_spec.field_type,
+          required:    row_spec.field_required,
+          column:      row_spec.field_column,
+          description: row_spec.field_description,
+          options:     row_spec.field_options
+        )
+      end
+
+      def finalize_stage(stage)
+        {
+          name:     stage[:name],
+          ordering: stage[:ordering],
+          sections: stage[:section_order].map { |key| stage[:sections][key] }
+        }
+      end
+    end
+  end
+end

data/lib/eco/api/usecases/graphql/samples/pages/template/csv_build.rb

@@ -0,0 +1,17 @@
+module Eco::API::UseCases::GraphQL::Samples::Pages::Template
+  # CSV → template BUILD pipeline.
+  #
+  # Parse a columnar CSV describing a template (stages / sections / fields / types / options), emit the
+  # ordered `WorkflowCommand` batch via the EXISTING `Template::CommandEmitter`, and build it via the
+  # released gem's `Builder::Template#create(commands:)`. Offline / dry-run by default; live creation
+  # (`Builder#create!`) needs credentials.
+  #
+  # The exact ~300-template columnar CSV format is due ~mid-July 2026 and is isolated in
+  # `CsvBuild::FormatMap` (see its TODO) so only that file changes when the real format lands.
+  module CsvBuild
+  end
+end
+
+require_relative 'csv_build/format_map'
+require_relative 'csv_build/parser'
+require_relative 'csv_build/builder'

data/lib/eco/api/usecases/graphql/samples/pages/template/deploy/applier.rb

@@ -0,0 +1,141 @@
+module Eco::API::UseCases::GraphQL::Samples::Pages::Template
+  module Deploy
+    # Thin, offline-safe wrapper around a gem `Diff::Deploy` plan.
+    #
+    # The gem's `Diff::Deploy` is INERT until `execute!` is called with an explicit executor — this
+    # applier keeps that safety and adds a **dry-run default**: nothing hits the API unless the caller
+    # opts in with `commit: true` AND supplies a live executor. The dry-run path records the batch it
+    # WOULD send (so the pre/post-diff and the specs can inspect it) and never calls the executor.
+    #
+    # An "executor" is anything responding to `execute_workflow_commands(model_or_id, commands:)` —
+    # in production the gem's `graphql.page` / `Builder::Template` update facade. For dry-run + specs a
+    # capturing stand-in is enough; see `Deploy::RecordingExecutor`.
+    #
+    #   plan     = Ecoportal::API::GraphQL::Diff::Deploy.from_versions(before, after, target_doc: prod)
+    #   applier  = Applier.new(plan, target: prod_template)
+    #   outcome  = applier.apply           # dry-run: records commands, no API call
+    #   outcome  = applier.apply(commit: true, executor: graphql.page)  # live apply
+    #
+    #   outcome.committed?     # => false for dry-run
+    #   outcome.commands       # => the ordered batch that was (or would be) sent
+    #   outcome.unsupported    # => [Change, ...] the plan could not synthesise (needs a human)
+    class Applier
+      # Result of an apply attempt. `committed?` is only true when the batch was actually sent live.
+      Outcome = Struct.new(:committed, :commands, :unsupported, :response, :skipped_reason,
+                           keyword_init: true) do
+        def committed?
+          committed ? true : false
+        end
+
+        def applied?
+          committed? || dry_run?
+        end
+
+        def dry_run?
+          !committed? && skipped_reason.nil?
+        end
+
+        def to_h
+          {
+            committed:      committed?,
+            commands:       commands,
+            unsupported:    Array(unsupported).map { |c| c.respond_to?(:to_h) ? c.to_h : c },
+            skipped_reason: skipped_reason
+          }.compact
+        end
+      end
+
+      attr_reader :plan, :target
+
+      # @param plan   [Ecoportal::API::GraphQL::Diff::Deploy] the gem deploy plan.
+      # @param target [#id, nil] the template/page model the batch applies to (needed for a live
+      #   executor that reads id/patchVer). Optional for dry-run.
+      def initialize(plan, target: nil)
+        @plan   = plan
+        @target = target
+      end
+
+      # Apply the plan's command batch.
+      #
+      # @param commit   [Boolean] false (default) = dry-run, records the batch and returns without
+      #   touching the API. true = live apply (requires an executor).
+      # @param executor [#execute_workflow_commands, nil] the live mutation facade. Ignored on dry-run.
+      # @param allow_partial [Boolean] forwarded to the gem plan: apply even with unsupported changes.
+      # @return [Outcome]
+      def apply(commit: false, executor: nil, allow_partial: false)
+        return blocked_outcome unless deployable?(allow_partial)
+
+        return dry_run_outcome unless commit
+
+        commit_outcome(executor, allow_partial: allow_partial)
+      end
+
+      # The ordered command batch (delegates to the gem plan).
+      def commands
+        plan.commands
+      end
+
+      # Changes the gem plan could not synthesise — surfaced so a human gates the deploy.
+      def unsupported
+        plan.unsupported
+      end
+
+      def fully_supported?
+        plan.fully_supported?
+      end
+
+      private
+
+      # A deploy is refused (never silently no-ops into a live call) when it is not fully supported
+      # and the caller did not explicitly opt into a partial apply.
+      def deployable?(allow_partial)
+        fully_supported? || allow_partial
+      end
+
+      def blocked_outcome
+        Outcome.new(
+          committed:      false,
+          commands:       [],
+          unsupported:    unsupported,
+          skipped_reason: "#{unsupported.size} unsupported change(s); review before deploy"
+        )
+      end
+
+      def dry_run_outcome
+        Outcome.new(committed: false, commands: commands, unsupported: unsupported)
+      end
+
+      def commit_outcome(executor, allow_partial:)
+        raise ArgumentError, 'commit: true requires an executor (execute_workflow_commands)' unless executor
+
+        response = plan.execute!(executor_facade(executor), allow_partial: allow_partial)
+        Outcome.new(committed: true, commands: commands, unsupported: unsupported, response: response)
+      end
+
+      # The gem plan calls `executor.execute_workflow_commands(commands)`. The gem's `Builder::Page`
+      # facade signature is `execute_workflow_commands(model, commands:)`, so bind the target model
+      # here. If the given executor already matches the plan's positional-commands contract, it is
+      # used as-is.
+      def executor_facade(executor)
+        return executor if executor.respond_to?(:arity_ok_for_positional_commands?)
+
+        TargetBoundExecutor.new(executor, target)
+      end
+
+      # Adapts the gem `Builder::Page`-style facade (`execute_workflow_commands(model, commands:)`) to
+      # the positional-commands contract the gem `Diff::Deploy#execute!` expects.
+      class TargetBoundExecutor
+        def initialize(facade, target)
+          @facade = facade
+          @target = target
+        end
+
+        def execute_workflow_commands(commands)
+          raise ArgumentError, 'a target model is required for a live apply' unless @target
+
+          @facade.execute_workflow_commands(@target, commands: commands)
+        end
+      end
+    end
+  end
+end

data/lib/eco/api/usecases/graphql/samples/pages/template/deploy/drift_report.rb

@@ -0,0 +1,104 @@
+module Eco::API::UseCases::GraphQL::Samples::Pages::Template
+  module Deploy
+    # Post-deploy verification: did the applied delta == the intended delta?
+    #
+    # After a deploy, re-read the target template and run a **self-version diff** (gem
+    # `Diff::VersionDiff`) between the PRE-deploy snapshot and the POST-deploy snapshot. That "applied
+    # delta" is then compared, op/kind/attribute-wise, against the "intended delta" (the changelog of
+    # the diff that produced the deploy batch).
+    #
+    # We compare on a normalised signature per change (op + kind + attribute + before/after) rather
+    # than on Mongo ids, because a cross-object deploy re-homes ids on the target — the SHAPE of the
+    # change is what must match. Any change present in one side but not the other is reported honestly
+    # as drift; nothing is hand-waved as "close enough".
+    #
+    #   report = DriftReport.new(
+    #     intended: source_diff,                       # the VersionDiff the deploy batch came from
+    #     applied:  Diff::VersionDiff.new(pre, post)   # pre/post self-diff of the target
+    #   )
+    #   report.match?          # => true when applied delta == intended delta (shape-wise)
+    #   report.missing         # => intended changes NOT observed on the target (under-applied)
+    #   report.unexpected      # => changes observed on the target that were NOT intended (over/side-effect)
+    #   report.report          # => human summary for a ticket / log
+    class DriftReport
+      attr_reader :intended, :applied
+
+      # @param intended [#changes] the source diff the deploy batch was synthesised from.
+      # @param applied  [#changes] the pre/post self-version diff of the deployed target.
+      def initialize(intended:, applied:)
+        @intended = intended
+        @applied  = applied
+      end
+
+      # Signatures present in the intended delta but missing from the applied delta.
+      def missing
+        @missing ||= (intended_signatures.keys - applied_signatures.keys).map { |sig| intended_signatures[sig] }
+      end
+
+      # Signatures present in the applied delta but not intended (side effects / over-apply).
+      def unexpected
+        @unexpected ||= (applied_signatures.keys - intended_signatures.keys).map { |sig| applied_signatures[sig] }
+      end
+
+      # True when the applied delta exactly matches the intended delta (no drift either way).
+      def match?
+        missing.empty? && unexpected.empty?
+      end
+
+      def to_h
+        {
+          match:      match?,
+          intended:   intended_signatures.size,
+          applied:    applied_signatures.size,
+          missing:    missing.map { |c| describe(c) },
+          unexpected: unexpected.map { |c| describe(c) }
+        }
+      end
+
+      def report
+        return 'DEPLOY VERIFY OK — applied delta matches intended delta.' if match?
+
+        lines = ['DEPLOY DRIFT detected:']
+        lines << "  Missing (intended but not applied): #{missing.size}"
+        missing.each { |c| lines << "    - #{describe(c)}" }
+        lines << "  Unexpected (applied but not intended): #{unexpected.size}"
+        unexpected.each { |c| lines << "    + #{describe(c)}" }
+        lines.join("\n")
+      end
+
+      private
+
+      def intended_signatures
+        @intended_signatures ||= signatures(@intended)
+      end
+
+      def applied_signatures
+        @applied_signatures ||= signatures(@applied)
+      end
+
+      # Index changes by a shape signature. Duplicate signatures (unlikely across a single template
+      # delta) collapse — acceptable for a drift verdict, which is set-membership, not count.
+      def signatures(diff)
+        Array(diff.changes).to_h do |change|
+          [signature(change), change]
+        end
+      end
+
+      # id-free shape signature: what changed, not which Mongo doc it landed on.
+      def signature(change)
+        [change.op, change.kind, change.attribute, norm(change.before), norm(change.after),
+         change.respond_to?(:label) ? change.label : nil]
+      end
+
+      def norm(value)
+        value.nil? ? nil : value
+      end
+
+      def describe(change)
+        return change.description if change.respond_to?(:description)
+
+        change.to_h.inspect
+      end
+    end
+  end
+end

data/lib/eco/api/usecases/graphql/samples/pages/template/deploy/loop.rb

@@ -0,0 +1,155 @@
+module Eco::API::UseCases::GraphQL::Samples::Pages::Template
+  module Deploy
+    # Deploy → verify → monitor orchestration (Phase 5).
+    #
+    # Ties the four offline-safe pieces into one pass:
+    #   1. APPLY   — hand a gem `Diff::Deploy` plan to the `Applier` (dry-run by DEFAULT; live only
+    #                behind an explicit `commit: true` + executor).
+    #   2. DRIFT   — re-read the target and run a pre/post self-version diff, then compare the applied
+    #                delta to the intended delta (`DriftReport`). Reports drift honestly.
+    #   3. VERIFY  — run the post-deploy template doc through a `Verifier` (ecoportal-qa when present,
+    #                else the null verifier).
+    #   4. MONITOR — optional sync-readiness scan of a register subset against the post-deploy template.
+    #
+    # Everything is OFFLINE against fixtures. The two seams that would touch a live API — applying the
+    # batch and re-reading the target — are injected as callables, so specs (and dry-runs) drive them
+    # with fixtures and a `RecordingExecutor`:
+    #
+    #   loop = Deploy::Loop.new(
+    #     plan:       gem_deploy_plan,
+    #     intended:   source_version_diff,        # the diff the plan was built from
+    #     pre_doc:    target_before_doc,          # the target template BEFORE apply
+    #     reread:     -> { recording_executor.doc } # how to fetch the target AFTER apply (post-deploy doc)
+    #   )
+    #   result = loop.run(commit: false, executor: recording_executor, entries: register_entries)
+    #
+    #   result.applied            # => Applier::Outcome
+    #   result.drift              # => DriftReport (nil if pre_doc/reread not supplied)
+    #   result.verdict            # => Verifier::Verdict
+    #   result.sync_readiness     # => SyncReadiness (nil if no entries)
+    #   result.ok?                # => apply not blocked && drift match && verify pass
+    #   result.report             # => aggregate human summary
+    class Loop
+      # Aggregate outcome of one deploy→verify→monitor pass.
+      Result = Struct.new(:applied, :drift, :verdict, :sync_readiness, keyword_init: true) do
+        # Overall gate: the apply was not blocked, the drift (if checked) matched, and verify passed.
+        def ok?
+          applied_ok? && drift_ok? && verify_ok?
+        end
+
+        def applied_ok?
+          applied && applied.skipped_reason.nil?
+        end
+
+        def drift_ok?
+          drift.nil? || drift.match?
+        end
+
+        def verify_ok?
+          verdict.nil? || verdict.pass?
+        end
+
+        def to_h
+          {
+            ok:             ok?,
+            applied:        applied&.to_h,
+            drift:          drift&.to_h,
+            verdict:        verdict&.to_h,
+            sync_readiness: sync_readiness&.to_h
+          }.compact
+        end
+
+        def report
+          [
+            "DEPLOY LOOP: #{ok? ? 'OK' : 'ATTENTION NEEDED'}",
+            applied_line,
+            drift&.report,
+            verdict&.report,
+            sync_readiness&.report
+          ].compact.join("\n\n")
+        end
+
+        private
+
+        def applied_line
+          if applied.skipped_reason
+            "APPLY: BLOCKED — #{applied.skipped_reason}"
+          elsif applied.committed?
+            "APPLY: committed #{applied.commands.size} command(s)"
+          else
+            "APPLY: dry-run — #{applied.commands.size} command(s) would be sent"
+          end
+        end
+      end
+
+      # @param plan     [Ecoportal::API::GraphQL::Diff::Deploy] the gem deploy plan.
+      # @param intended [#changes, nil] the source diff the plan was built from (for drift check).
+      # @param pre_doc  [Hash, nil] the target template doc BEFORE apply (for drift check).
+      # @param reread   [#call, nil] returns the target template doc AFTER apply (for drift + verify).
+      # @param target   [#id, nil] the target model, forwarded to the Applier for a live apply.
+      # @param verifier [Verifier, nil] injected verifier; defaults to Verifier.default.
+      # @param diff_builder [#call, nil] `diff_builder.call(pre_doc, post_doc)` returns the applied
+      #   self-version diff (must expose `#changes`). Defaults to the gem's `Diff::VersionDiff` — which
+      #   lives in the (currently unreleased) gem Diff module, so it is resolved LAZILY at drift time,
+      #   never at load. Injectable so offline callers/specs can supply their own diff builder.
+      def initialize(plan:, intended: nil, pre_doc: nil, reread: nil, target: nil, verifier: nil,
+                     diff_builder: nil)
+        @plan         = plan
+        @intended     = intended
+        @pre_doc      = pre_doc
+        @reread       = reread
+        @target       = target
+        @verifier     = verifier || Verifier.default
+        @diff_builder = diff_builder
+      end
+
+      # Run the full pass.
+      #
+      # @param commit   [Boolean] false = dry-run (default). true = live apply.
+      # @param executor [#execute_workflow_commands, nil] the mutation facade (live) or a
+      #   RecordingExecutor (offline). Required for both commit AND for an offline drift check
+      #   (the RecordingExecutor replays the batch to produce the post-deploy doc).
+      # @param allow_partial [Boolean] forwarded to the Applier / gem plan.
+      # @param entries [Array, nil] register subset for the sync-readiness monitor (optional).
+      # @return [Result]
+      def run(commit: false, executor: nil, allow_partial: false, entries: nil)
+        applied = Applier.new(@plan, target: @target).apply(
+          commit: commit, executor: executor, allow_partial: allow_partial
+        )
+
+        post_doc = applied.skipped_reason.nil? ? reread_post_doc : nil
+        drift    = build_drift(post_doc)
+        verdict  = post_doc ? @verifier.verify(post_doc) : nil
+        monitor  = build_monitor(post_doc, entries)
+
+        Result.new(applied: applied, drift: drift, verdict: verdict, sync_readiness: monitor)
+      end
+
+      private
+
+      def reread_post_doc
+        @reread&.call
+      end
+
+      def build_drift(post_doc)
+        return nil unless @intended && @pre_doc && post_doc
+
+        DriftReport.new(intended: @intended, applied: diff_builder.call(@pre_doc, post_doc))
+      end
+
+      # The gem's Diff::VersionDiff is the default applied-diff builder. Resolved lazily so this file
+      # never forces the (unreleased) gem Diff module at load time.
+      def diff_builder
+        @diff_builder ||= lambda do |pre, post|
+          Ecoportal::API::GraphQL::Diff::VersionDiff.new(pre, post)
+        end
+      end
+
+      def build_monitor(post_doc, entries)
+        return nil if entries.nil? || Array(entries).empty?
+
+        SyncReadiness.new(template_doc: post_doc || @pre_doc, entries: entries)
+      end
+    end
+  end
+end

data/lib/eco/api/usecases/graphql/samples/pages/template/deploy/recording_executor.rb

@@ -0,0 +1,58 @@
+module Eco::API::UseCases::GraphQL::Samples::Pages::Template
+  module Deploy
+    # Offline stand-in for a live workflow-command executor.
+    #
+    # Records every batch it is handed and (optionally) applies each command to an in-memory template
+    # doc via a caller-supplied `mutator`, so a deploy loop can compute a faithful POST-deploy snapshot
+    # WITHOUT any API call. This is what makes the pre/post self-version drift check runnable offline:
+    # the applied delta is derived from replaying the batch onto the pre-deploy doc.
+    #
+    # It satisfies BOTH executor contracts the gem may call:
+    #   * `execute_workflow_commands(commands)`            (gem Diff::Deploy#execute! positional)
+    #   * `execute_workflow_commands(model, commands:)`    (gem Builder::Page facade)
+    #
+    #   rec = RecordingExecutor.new(doc: before_doc.dup, mutator: my_replayer)
+    #   plan.execute!(rec)
+    #   rec.batches         # => [[cmd, cmd, ...]]
+    #   rec.doc             # => the mutated post-deploy doc (if a mutator was given)
+    class RecordingExecutor
+      attr_reader :batches, :doc
+
+      # @param doc     [Hash, nil] a template/page doc to mutate as commands are replayed.
+      # @param mutator [#call, nil] `mutator.call(doc, command)` applies one command to `doc`
+      #   in place (or returns the new doc). When nil, the doc is left untouched (record-only).
+      def initialize(doc: nil, mutator: nil)
+        @doc     = doc
+        @mutator = mutator
+        @batches = []
+      end
+
+      def execute_workflow_commands(model_or_commands, commands: nil)
+        batch = commands || model_or_commands
+        @batches << batch
+        replay(batch) if @mutator
+        record_response(batch)
+      end
+
+      # Marker so the applier does not double-wrap this executor.
+      def arity_ok_for_positional_commands?
+        true
+      end
+
+      # Every command across all recorded batches, flattened, in order.
+      def all_commands
+        @batches.flatten(1)
+      end
+
+      private
+
+      def replay(batch)
+        Array(batch).each { |command| @doc = @mutator.call(@doc, command) || @doc }
+      end
+
+      def record_response(batch)
+        { recorded: batch.size }
+      end
+    end
+  end
+end