eco-helpers 3.2.14 → 3.2.23

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

@@ -0,0 +1,126 @@
+module Eco::API::UseCases::GraphQL::Samples::Pages::Template
+  module CsvBuild
+    # CSV → template BUILD pipeline.
+    #
+    # Ties the pieces together: a `Parser` turns a columnar CSV into a stage/section/field tree, this
+    # Builder replays that tree onto the EXISTING `Template::CommandEmitter` (reused verbatim — same
+    # placeholder-id threading the create path already relies on), and then hands the resulting ordered
+    # `WorkflowCommand` batch to the released gem's `Builder::Template#create(commands:)`.
+    #
+    # Offline / dry-run by DEFAULT — real creation needs credentials, so `build` only assembles and
+    # returns the command batch; `create!` is the explicit live path (requires a gem `Builder::Template`
+    # or `GraphQL#template` facade).
+    #
+    #   builder  = CsvBuild::Builder.from_csv(csv_string)
+    #   commands = builder.commands            # ordered { commandKey => kwargs } batch, offline
+    #   # live (needs creds):
+    #   builder.create!(graphql.template)      # => gem create mutation response
+    #
+    # SECTION / FIELD IDENTITY: each field's `description` (from FormatMap) is passed to the emitter's
+    # `field(description:)`, and a hidden anchor per section carries the section identity — so a rebuilt
+    # template stays pair-able against a prior version by the diff engine. When the field type is
+    # `select`, the parsed options are emitted as addSelectFieldOption commands.
+    #
+    # ⚠ HONEST LIMITATION: the RELEASED gem's `addField` input drops any key outside
+    # placeholderId/fieldType/label/stageId/sectionId/column (see CommandEmitter#field note). So today
+    # the `description` identity token is NOT persisted through addField — the hidden ANCHOR FIELD's
+    # presence (its label) is the only identity signal that currently survives to the batch. The
+    # description wiring is in place so identity flows end-to-end the moment the gem's addField input
+    # gains a description key. Until then, section/field identity relies on the anchor + heading/label.
+    class Builder
+      # Hidden marker field type used to anchor SECTION identity across rebuilds (identity convention:
+      # hidden-field + description). Kept as a constant so it is trivial to retune when the real format
+      # / platform convention for the anchor is confirmed.
+      SECTION_ANCHOR_TYPE  = 'hidden'.freeze
+      SECTION_ANCHOR_LABEL = '__section_id'.freeze
+
+      def self.from_csv(csv_string, **opts)
+        new(Parser.new(csv_string), **opts)
+      end
+
+      def self.from_file(path, **opts)
+        new(Parser.from_file(path), **opts)
+      end
+
+      # @param parser [Parser]
+      # @param section_anchors [Boolean] emit a hidden anchor field per section for stable identity
+      #   (default true — the CSV-pipeline identity convention). Set false for a plain build.
+      def initialize(parser, section_anchors: true)
+        @parser          = parser
+        @section_anchors = section_anchors
+      end
+
+      # The ordered command batch — PURE, no client needed. This is what specs assert against.
+      def commands
+        @commands ||= begin
+          emitter = CommandEmitter.new
+          emit_tree(emitter)
+          emitter.commands
+        end
+      end
+
+      # LIVE build (needs creds). `template_facade` is the gem `Builder::Template` (a.k.a.
+      # `graphql.template`) exposing `create(commands:)`.
+      def create!(template_facade, &block)
+        unless template_facade.respond_to?(:create)
+          raise ArgumentError,
+                'template facade must respond to #create(commands:)'
+        end
+
+        template_facade.create(commands: commands, &block)
+      end
+
+      # Human preview of the batch (for a dry-run / simulate log).
+      def preview
+        ["CSV build — #{commands.size} workflow command(s):",
+         *commands.map { |c| "  * #{c.keys.first}: #{c.values.first.inspect}" }].join("\n")
+      end
+
+      private
+
+      def emit_tree(emitter)
+        @parser.tree.each do |stage|
+          emitter.stage(name: stage[:name], ordering: stage[:ordering]) do |stage_builder|
+            stage[:sections].each { |section| emit_section(stage_builder, section) }
+          end
+        end
+      end
+
+      def emit_section(stage_builder, section)
+        stage_builder.section(layout: section[:layout]) do |section_builder|
+          emit_section_anchor(section_builder, section) if @section_anchors
+          section[:fields].each { |field| emit_field(section_builder, field) }
+        end
+      end
+
+      # Hidden anchor field carrying the section identity in its description (identity convention).
+      def emit_section_anchor(section_builder, section)
+        section_builder.field(
+          label:       SECTION_ANCHOR_LABEL,
+          field_type:  SECTION_ANCHOR_TYPE,
+          description: section_identity(section)
+        )
+      end
+
+      def emit_field(section_builder, field)
+        section_builder.field(
+          label:       field.label,
+          field_type:  field.type,
+          column:      field.column,
+          required:    field.required,
+          description: field.description
+        ) do |field_builder|
+          Array(field.options).each do |opt|
+            field_builder.option(label: opt[:label], weight: opt[:weight])
+          end
+        end
+      end
+
+      # Stable section identity token. Uses the section heading; a hidden anchor field carries it so
+      # the diff/pairing engine can re-home the section on a rebuild.
+      def section_identity(section)
+        "section:#{section[:heading]}"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,108 @@
+module Eco::API::UseCases::GraphQL::Samples::Pages::Template
+  module CsvBuild
+    # ISOLATED column-format mapping for the CSV → template build pipeline.
+    #
+    # ============================ IMPORTANT / TODO ============================
+    # The EXACT columnar CSV format for the ~300-template bulk build is due ~mid-July 2026 and is NOT
+    # yet confirmed. This class is the SINGLE place the assumed format is encoded, precisely so that
+    # when the real format lands, only THIS file (and its spec) needs to change — the Parser and
+    # Builder are written against the neutral intermediate `RowSpec`, not against column names.
+    #
+    # Assumed format (documented here, one row per FIELD, hierarchy carried on each row):
+    #
+    #   stage,stage_ordering,section,section_ordering,section_layout,
+    #   field_label,field_type,field_required,field_column,field_description,field_options
+    #
+    #   * `field_type`     — a template field type accepted by addField (e.g. plain_text, select,
+    #                        date, number, gauge, rich_text, people, ...). Passed through verbatim.
+    #   * `field_options`  — for select-type fields: pipe-separated `label:weight` pairs,
+    #                        e.g. "High:10|Medium:5|Low:0". Weight optional ("High|Medium|Low").
+    #   * `field_description` — carries the SECTION/FIELD IDENTITY convention (see below).
+    #
+    # SECTION / FIELD IDENTITY CONVENTION (per the CSV-pipeline project notes): stable identity for a
+    # section/field across rebuilds is expressed via a HIDDEN marker field + a DESCRIPTION token, not
+    # via the volatile Mongo id. The parser threads `field_description` through so the builder can
+    # stamp a deterministic identity token; sections inherit identity from their heading + a hidden
+    # anchor field. This keeps a rebuilt template pair-able against a prior version by the diff engine.
+    # ==========================================================================
+    #
+    # To adapt to the real format: change COLUMNS + the `#value`/`#options` readers here. Everything
+    # downstream consumes `RowSpec`, which is format-agnostic.
+    module FormatMap
+      # Logical field  =>  CSV header name (assumed). CHANGE HERE when the real format arrives.
+      COLUMNS = {
+        stage:             'stage',
+        stage_ordering:    'stage_ordering',
+        section:           'section',
+        section_ordering:  'section_ordering',
+        section_layout:    'section_layout',
+        field_label:       'field_label',
+        field_type:        'field_type',
+        field_required:    'field_required',
+        field_column:      'field_column',
+        field_description: 'field_description',
+        field_options:     'field_options'
+      }.freeze
+
+      # Delimiters (assumed). CHANGE HERE if the real format differs.
+      OPTIONS_DELIMITER = '|'.freeze
+      OPTION_WEIGHT_SEPARATOR = ':'.freeze
+
+      # Neutral, format-agnostic row: what the Builder consumes. Only THIS is passed downstream.
+      RowSpec = Struct.new(:stage, :stage_ordering, :section, :section_ordering, :section_layout,
+                           :field_label, :field_type, :field_required, :field_column,
+                           :field_description, :field_options, keyword_init: true)
+
+      module_function
+
+      # Map one CSV row (a Hash keyed by header string) to a RowSpec.
+      def row_spec(row)
+        RowSpec.new(
+          stage:             value(row, :stage),
+          stage_ordering:    integer(row, :stage_ordering),
+          section:           value(row, :section),
+          section_ordering:  integer(row, :section_ordering),
+          section_layout:    value(row, :section_layout) || 'content',
+          field_label:       value(row, :field_label),
+          field_type:        value(row, :field_type),
+          field_required:    truthy?(row, :field_required),
+          field_column:      integer(row, :field_column) || 0,
+          field_description: value(row, :field_description),
+          field_options:     options(value(row, :field_options))
+        )
+      end
+
+      # Parse the options cell into [ { label:, weight: }, ... ]. Empty → [].
+      def options(cell)
+        return [] if cell.nil? || cell.to_s.strip.empty?
+
+        cell.to_s.split(OPTIONS_DELIMITER).map do |token|
+          label, weight = token.split(OPTION_WEIGHT_SEPARATOR, 2).map(&:strip)
+          { label: label, weight: (weight && !weight.empty? ? Integer(weight, exception: false) : nil) }
+        end
+      end
+
+      def value(row, logical)
+        header = COLUMNS.fetch(logical)
+        raw    = row[header]
+        raw = row[header.to_sym] if raw.nil? && row.respond_to?(:key?)
+        return nil if raw.nil?
+
+        str = raw.to_s.strip
+        str.empty? ? nil : str
+      end
+
+      def integer(row, logical)
+        raw = value(row, logical)
+        raw && Integer(raw, exception: false)
+      end
+
+      def truthy?(row, logical)
+        raw = value(row, logical)
+        return false if raw.nil?
+
+        %w[1 true yes y required].include?(raw.downcase)
+      end
+    end
+  end
+end

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