html2rss 0.30.0 → 0.31.0

data/lib/html2rss/link_destination/path_classifier.rb

@@ -7,47 +7,54 @@ module Html2rss
       attr_reader :segments
 
       # Soft utility segments excluded from high-confidence junk (still utility_path).
-      SOFT_UTILITY = %w[
-        for-you join member members membership newsletter newsletters
-        plans plus premium pricing recommended
-      ].to_set.freeze
+      SOFT_UTILITY = Set[
+        'for-you', 'join', 'member', 'members', 'membership', 'newsletter', 'newsletters',
+        'plans', 'plus', 'premium', 'pricing', 'recommended'
+      ].freeze
 
       # Segment groups used to classify article, taxonomy, utility, and vanity routes.
       # Utility = taxonomy ∪ chrome ∪ soft utility (do not re-list taxonomy tokens).
       SEGMENT_SETS = begin
-        content = %w[
-          article articles blog blogs changelog changelogs insight insights
-          launch launches news post posts release releases story stories update updates
-          artikel beitrag beitraege nachrichten neuigkeiten aktuelles
-          articulo articulos noticia noticias entrada entradas publicacion publicaciones
-          actualite actualites nouvelle nouvelles teaser teasers card cards
-        ].to_set.freeze
-        taxonomy = %w[
-          category categories tag tags topic topics
-          kategorie kategorien schlagwort schlagworte thema themen
-          categoria categorias etiqueta etiquetas tema temas
-          categorie etiquette etiquettes sujet sujets theme themes
-        ].to_set.freeze
-        vanity = %w[
-          join membership plus premium pricing plans subscribe signup
-          abonnieren abo suscribirse boletin s-abonner saboner
-        ].to_set.freeze
-        chrome = %w[
-          about account archive archives author authors comment comments contact feedback
-          help login logout notification notifications preference preferences profile register
-          search settings share signup subscribe feed feeds comment-feed comments-feed privacy
-          terms cookie cookies user users autor autoren archiv ueber-uns ueber ueberuns profil
-          kontakt impressum suche hilfe anmelden registrieren konto registrierung anmeldung
-          abonnieren abo datenschutz nutzungsbedingungen agb autores archivos sobre-nosotros
-          sobre quienes-somos buscar busqueda ayuda entrar ingresar registrarse registro cuenta
-          suscribirse boletin privacidad condiciones auteur auteurs a-propos apropos recherche
-          rechercher aide connexion s-inscrire sinscrire inscription compte s-abonner saboner
-          lettre-information confidentialite mentions-legales cgu menu sidebar widget social
-          modal popup banner promo ad ads related recommendation recommendations pagination pager
-          dating jobs job career careers deals deal shopping shop trading broker versicherung
-          tierversicherung insurance vergleich comparison partnerboerse singleboerse krypto crypto
-          casinos casino kreditkarten kreditkarte kredit echtgeld vpn games kaufberater leasing
-        ].to_set.freeze
+        content = Set[
+          'article', 'articles', 'blog', 'blogs', 'changelog', 'changelogs', 'insight', 'insights',
+          'launch', 'launches', 'news', 'post', 'posts', 'release', 'releases', 'story', 'stories',
+          'update', 'updates', 'artikel', 'beitrag', 'beitraege', 'nachrichten', 'neuigkeiten',
+          'aktuelles', 'articulo', 'articulos', 'noticia', 'noticias', 'entrada', 'entradas',
+          'publicacion', 'publicaciones', 'actualite', 'actualites', 'nouvelle', 'nouvelles',
+          'teaser', 'teasers', 'card', 'cards'
+        ].freeze
+        taxonomy = Set[
+          'category', 'categories', 'tag', 'tags', 'topic', 'topics',
+          'kategorie', 'kategorien', 'schlagwort', 'schlagworte', 'thema', 'themen',
+          'categoria', 'categorias', 'etiqueta', 'etiquetas', 'tema', 'temas',
+          'categorie', 'etiquette', 'etiquettes', 'sujet', 'sujets', 'theme', 'themes'
+        ].freeze
+        vanity = Set[
+          'join', 'membership', 'plus', 'premium', 'pricing', 'plans', 'subscribe', 'signup',
+          'abonnieren', 'abo', 'suscribirse', 'boletin', 's-abonner', 'saboner'
+        ].freeze
+        chrome = Set[
+          'about', 'account', 'archive', 'archives', 'author', 'authors', 'comment', 'comments',
+          'contact', 'feedback', 'help', 'login', 'logout', 'notification', 'notifications',
+          'preference', 'preferences', 'profile', 'register', 'search', 'settings', 'share',
+          'signup', 'subscribe', 'feed', 'feeds', 'comment-feed', 'comments-feed', 'privacy',
+          'terms', 'cookie', 'cookies', 'user', 'users', 'autor', 'autoren', 'archiv', 'ueber-uns',
+          'ueber', 'ueberuns', 'profil', 'kontakt', 'impressum', 'suche', 'hilfe', 'anmelden',
+          'registrieren', 'konto', 'registrierung', 'anmeldung', 'abonnieren', 'abo', 'datenschutz',
+          'nutzungsbedingungen', 'agb', 'autores', 'archivos', 'sobre-nosotros', 'sobre',
+          'quienes-somos', 'buscar', 'busqueda', 'ayuda', 'entrar', 'ingresar', 'registrarse',
+          'registro', 'cuenta', 'suscribirse', 'boletin', 'privacidad', 'condiciones', 'auteur',
+          'auteurs', 'a-propos', 'apropos', 'recherche', 'rechercher', 'aide', 'connexion',
+          's-inscrire', 'sinscrire', 'inscription', 'compte', 's-abonner', 'saboner',
+          'lettre-information', 'confidentialite', 'mentions-legales', 'cgu', 'menu', 'sidebar',
+          'widget', 'social', 'modal', 'popup', 'banner', 'promo', 'ad', 'ads', 'related',
+          'recommendation', 'recommendations', 'pagination', 'pager', 'dating', 'jobs', 'job',
+          'career', 'careers', 'deals', 'deal', 'shopping', 'shop', 'trading', 'broker',
+          'versicherung', 'tierversicherung', 'insurance', 'vergleich', 'comparison',
+          'partnerboerse', 'singleboerse', 'krypto', 'crypto', 'casinos', 'casino',
+          'kreditkarten', 'kreditkarte', 'kredit', 'echtgeld', 'vpn', 'games', 'kaufberater',
+          'leasing'
+        ].freeze
         utility = (taxonomy | chrome | SOFT_UTILITY).freeze
         {
           content:,
@@ -55,7 +62,7 @@ module Html2rss
           high_confidence_junk: (utility - SOFT_UTILITY).freeze,
           taxonomy:,
           vanity:,
-          deep_post_context: %w[press newsroom presse pressemitteilungen prensa].to_set.freeze
+          deep_post_context: Set['press', 'newsroom', 'presse', 'pressemitteilungen', 'prensa'].freeze
         }.freeze
       end
       # Path segment that begins with a year-like publishing marker.

data/lib/html2rss/mcp/README.md

@@ -24,6 +24,8 @@ Batch: `batch_inspect`, `batch_recon`, `batch_scrape`.
 2. **Reusable feed YAML?** → `capture` → `test` → `apply`. `capture` returns YAML in `payload.yaml`. Strive `enhance: true` (false only when chrome leaks). `test` runs schema + live extraction; optional `compare_enhance` compares enhance off vs on. `apply` is the ship gate (`isError` on zero items). Both `test` and `apply` may include `quality_report.enhance_gains` when `selectors.items.enhance` is true.
 3. **Weak scrape/capture or recon?** → `inspect` (or `batch_inspect`). When alternates warrant it, follow `next_step` to `recon`.
 4. **Config already in hand?** → `validate` (schema only) → `test` → `apply`.
+   - `validate` failures return `payload.issues` (array of `{ path, code, message, expected, actual }`) — not a nested `errors` hash.
+   - `test` schema failures surface the same shape under `payload.validation_issues`.
 
 Prefer `capture` for durable configs; `scrape` / `batch_scrape` for one-shot extraction. Follow envelope `next_step` and `guidance`; do not parse scrape text as a raw item array.
 

data/lib/html2rss/mcp/config_argument.rb

@@ -2,10 +2,12 @@
 
 module Html2rss
   module MCP
+    ConfigArgument = Data.define(:config)
+
     # Feed config supplied over MCP as a hash XOR a YAML string.
     #
     # Config does not know MCP. YAML parsing stays on {Html2rss::Config.from_yaml}.
-    ConfigArgument = Data.define(:config) do
+    class ConfigArgument
       class << self
         ##
         # @param config [Hash, nil] feed configuration hash

data/lib/html2rss/mcp/contract.rb

@@ -16,7 +16,7 @@ module Html2rss
       ALL_ACCEPTED_STRATEGIES = (STRATEGIES + MIGRATION_STRATEGIES).freeze
 
       # Bump when tool names, required inputs, or envelope semantics change (independent of gem +VERSION+).
-      MCP_CONTRACT_VERSION = 2
+      MCP_CONTRACT_VERSION = 3
       public_constant :MCP_CONTRACT_VERSION
 
       # Raised when apply/validate config uses an unpublished MCP request adapter.
@@ -201,26 +201,12 @@ module Html2rss
       # Tool annotations for +validate+ (closed world).
       ANNOTATIONS_VALIDATE = ANNOTATIONS_OPEN_WORLD.merge(open_world_hint: false).freeze
 
-      # Human titles for +tools/list+.
-      TITLES = {
-        scrape: 'Scrape',
-        inspect: 'Inspect',
-        recon: 'Recon',
-        batch_scrape: 'Batch scrape',
-        batch_inspect: 'Batch inspect',
-        batch_recon: 'Batch recon',
-        capture: 'Capture',
-        validate: 'Validate',
-        apply: 'Apply',
-        test: 'Test'
-      }.freeze
-
       # @api private
       CATALOG_ENTRY_LINE = lambda do |entry|
-        schema = entry.fetch(:input_schema)
+        schema = entry.input_schema
         required = Array(schema[:required]).sort.join(',')
         one_of = Array(schema[:oneOf]).map { |branch| Array(branch[:required]).sort.join('+') }.sort.join('|')
-        [entry.fetch(:name), required, one_of].reject(&:empty?).join(':')
+        [entry.name, required, one_of].reject(&:empty?).join(':')
       end.freeze
 
       class << self
@@ -229,7 +215,7 @@ module Html2rss
         #
         # @return [Array<String>]
         def catalog_tools
-          Server::Tools::TOOLS.map { |entry| entry.fetch(:name) }.sort
+          Server::Tools::TOOLS.map(&:name).sort
         end
 
         ##
@@ -239,7 +225,7 @@ module Html2rss
         #
         # @return [String] 16-char hex digest prefix
         def catalog_fingerprint
-          lines = Server::Tools::TOOLS.sort_by { |entry| entry.fetch(:name) }.map(&CATALOG_ENTRY_LINE)
+          lines = Server::Tools::TOOLS.sort_by(&:name).map(&CATALOG_ENTRY_LINE)
           Digest::SHA256.hexdigest(lines.join("\n")).slice(0, 16)
         end
 
@@ -254,7 +240,7 @@ module Html2rss
             required: %w[ok next_step guidance payload],
             properties: {
               ok: { type: 'boolean' },
-              next_step: { type: 'string', enum: Outcome::NextStep::NAMES.map(&:to_s) },
+              next_step: { type: 'string', enum: Outcome::NextStep::ALL.keys.map(&:to_s) },
               guidance: { type: 'string' },
               payload: { type: 'object' }
             }

data/lib/html2rss/mcp/outcome/playbook.rb

@@ -8,7 +8,7 @@ module Html2rss
       # and prompt bodies. {Server} delegates here — do not duplicate prose in
       # +server.rb+.
       class Playbook
-        # Default guidance copy keyed by {Outcome::NextStep::NAMES}.
+        # Default guidance copy; {Outcome::NextStep::ALL} is built from these keys.
         GUIDANCE = {
           done: 'Done. Read payload for the result.',
           inspect: 'Call inspect next. Read payload for diagnostics (final_url, status, ' \
@@ -16,7 +16,7 @@ module Html2rss
           recon: 'Call recon next. Read payload for verdict and native_feed preference.',
           validate: 'Call validate with payload.yaml or a config hash (XOR, not both).',
           apply: 'Call apply next. Confirm payload.item_count before shipping.',
-          scrape: 'Call scrape for articles now. strategy auto already runs Faraday then Botasaurus ' \
+          scrape: 'Call scrape for articles now. strategy auto already runs default (HTTPX) then Botasaurus ' \
                   'and promotes native RSS/Atom when present.',
           capture: 'Call capture for a reusable YAML draft, then follow next_step.',
           read_runtime: 'Read html2rss://runtime. Compare mcp_contract_version and catalog_fingerprint ' \

data/lib/html2rss/mcp/outcome.rb

@@ -13,24 +13,16 @@ module Html2rss
       NextStep = Data.define(:name, :guidance)
 
       ##
-      # Closed set of agent next actions. Invalid names cannot be constructed.
+      # Closed set of agent next actions. Names are owned by {Playbook::GUIDANCE}.
       class NextStep
-        # Wire names for +next_step+.
-        NAMES = %i[done inspect recon validate apply scrape capture read_runtime test].freeze
+        # Frozen name → instance table built from {Playbook::GUIDANCE}.
+        ALL = Playbook::GUIDANCE.to_h { |name, guidance| [name, new(name:, guidance:)] }.freeze
+        private_class_method :new
 
         ##
         # @param name [Symbol, String]
-        # @param guidance [String, nil]
-        def initialize(name:, guidance: nil)
-          step = name.to_sym
-          raise ArgumentError, "unknown next_step: #{name.inspect}" unless NAMES.include?(step)
-
-          super(name: step, guidance: (guidance || Playbook::GUIDANCE.fetch(step)).freeze)
-        end
-
-        class << self
-          NAMES.each { |step| define_method(step) { new(name: step) } }
-        end
+        # @return [NextStep]
+        def self.[](name) = ALL.fetch(name.to_sym) { raise ArgumentError, "unknown next_step: #{name.inspect}" }
       end
 
       ##
@@ -107,12 +99,13 @@ module Html2rss
         end
 
         ##
-        # @param errors [Hash, nil] schema errors; +nil+ means success
+        # @param report [Html2rss::Config::ValidationReport]
         # @return [Outcome]
-        def validate(errors:)
-          ok = errors.nil?
-          next_step = ok ? NextStep.test : NextStep.validate
-          new(ok:, next_step:, guidance: next_step.guidance, payload: ok ? {} : { errors: })
+        def validate(report:)
+          ok = report.success?
+          next_step = ok ? NextStep[:test] : NextStep[:validate]
+          payload = ok ? {} : { issues: report.issues.map(&:to_h) }
+          new(ok:, next_step:, guidance: next_step.guidance, payload:)
         end
 
         ##
@@ -131,17 +124,17 @@ module Html2rss
         ##
         # @param batch_result [Html2rss::Batch::BatchResult]
         # @return [Outcome]
-        def batch_scrape(batch_result) = batch(batch_result, NextStep.scrape)
+        def batch_scrape(batch_result) = batch(batch_result, NextStep[:scrape])
 
         ##
         # @param batch_result [Html2rss::Batch::BatchResult]
         # @return [Outcome]
-        def batch_inspect(batch_result) = batch(batch_result, NextStep.inspect)
+        def batch_inspect(batch_result) = batch(batch_result, NextStep[:inspect])
 
         ##
         # @param batch_result [Html2rss::Batch::BatchResult]
         # @return [Outcome]
-        def batch_recon(batch_result) = batch(batch_result, NextStep.recon)
+        def batch_recon(batch_result) = batch(batch_result, NextStep[:recon])
 
         ##
         # @param rss [String]
@@ -151,7 +144,7 @@ module Html2rss
         # @return [Outcome]
         def apply(rss:, item_count:, empty: item_count.zero?, quality_report: nil)
           ok = !empty
-          next_step = ok ? NextStep.done : NextStep.inspect
+          next_step = ok ? NextStep[:done] : NextStep[:inspect]
           payload = { rss:, item_count: }
           payload[:quality_report] = quality_report if quality_report
           new(ok:, next_step:, guidance: next_step.guidance, payload:)
@@ -169,15 +162,15 @@ module Html2rss
         private
 
         def batch(batch_result, failure_step)
-          step = batch_result.successful.positive? ? NextStep.done : failure_step
+          step = batch_result.successful.positive? ? NextStep[:done] : failure_step
           new(ok: true, next_step: step, guidance: step.guidance, payload: batch_result.to_h)
         end
 
         def scrape_next_step(empty, botasaurus_configured:)
-          return NextStep.done unless empty
-          return NextStep.read_runtime unless botasaurus_configured
+          return NextStep[:done] unless empty
+          return NextStep[:read_runtime] unless botasaurus_configured
 
-          NextStep.inspect
+          NextStep[:inspect]
         end
 
         def scrape_payload(items:, requested_strategy:, channel_title:, admission_drops:)
@@ -188,33 +181,33 @@ module Html2rss
         end
 
         def inspect_next_step(report)
-          return NextStep.recon if report.alternate_feeds?
-          return NextStep.capture if report.articles_count.positive?
+          return NextStep[:recon] if report.alternate_feeds?
+          return NextStep[:capture] if report.articles_count.positive?
 
-          NextStep.scrape
+          NextStep[:scrape]
         end
 
         def recon_next_step(result)
-          return NextStep.done if result.defer?
-          return NextStep.capture if result.build?
+          return NextStep[:done] if result.defer?
+          return NextStep[:capture] if result.build?
 
-          NextStep.scrape
+          NextStep[:scrape]
         end
 
         def capture_next_step(articles_count:, has_selectors:, native_feed: nil)
-          return NextStep.done if native_feed
+          return NextStep[:done] if native_feed
 
-          articles_count.positive? && has_selectors ? NextStep.test : NextStep.inspect
+          articles_count.positive? && has_selectors ? NextStep[:test] : NextStep[:inspect]
         end
 
         def test_next_step(test_result)
-          return NextStep.apply if test_result.success
+          return NextStep[:apply] if test_result.success
 
           kind = test_result.failure_kind
-          return NextStep.validate if kind&.schema?
-          return NextStep.capture if kind&.execution? || kind&.min_items? || kind&.quality?
+          return NextStep[:validate] if kind&.schema?
+          return NextStep[:capture] if kind&.execution? || kind&.min_items? || kind&.quality?
 
-          NextStep.capture
+          NextStep[:capture]
         end
 
         def test_guidance(test_result, next_step)
@@ -244,15 +237,15 @@ module Html2rss
 
         def next_step_for_error(error)
           case error
-          when RequestService::BotasaurusConfigurationError then NextStep.read_runtime
-          when Contract::UnpublishedRequestError then NextStep.validate
+          when RequestService::BotasaurusConfigurationError then NextStep[:read_runtime]
+          when Contract::UnpublishedRequestError then NextStep[:validate]
           when ArgumentError then argument_error_next_step(error)
-          else NextStep.inspect
+          else NextStep[:inspect]
           end
         end
 
         def argument_error_next_step(error)
-          XOR_ERROR.match?(error.message) ? NextStep.validate : NextStep.inspect
+          XOR_ERROR.match?(error.message) ? NextStep[:validate] : NextStep[:inspect]
         end
       end
     end