feat: simplify feed creation flows

AGENTS.md

@@ -15,6 +15,7 @@ This document defines execution constraints for AI agents. For general contribut
 ## Agent-Specific Verification Rules
 
 - Always run Dev Container smoke + `make ready` for changes.
+- For frontend changes or API contract/spec changes, run `make ci-ready` to mirror CI parity checks.
 - For frontend changes, also verify in `chrome-devtools` MCP at `http://127.0.0.1:4001/` while the Dev Container is running.
 - Capture a quick state check for all affected UI states (e.g., guest/member/result) to enforce state parity and avoid duplicate actions.
 

Makefile

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
-.PHONY: help test lint lint-js lint-ruby lintfix lintfix-js lintfix-ruby setup dev clean frontend-setup check-frontend quick-check ready yard-verify-public-docs openapi openapi-verify openapi-client openapi-client-verify openapi-lint openapi-lint-redocly openapi-lint-spectral openai-lint-spectral test-frontend-e2e
+.PHONY: help test lint lint-js lint-ruby lintfix lintfix-js lintfix-ruby setup dev clean frontend-setup check-frontend quick-check ready ci-ready yard-verify-public-docs openapi openapi-verify openapi-client openapi-client-verify openapi-lint openapi-lint-redocly openapi-lint-spectral openai-lint-spectral test-frontend-e2e
+
+RUBOCOP_FLAGS ?= --cache false
 
 # Default target
 help: ## Show this help message
@@ -60,7 +62,7 @@ lint: lint-ruby lint-js ## Run all linters (Ruby + Frontend) - errors when issue
 
 lint-ruby: ## Run Ruby linter (RuboCop) - errors when issues found
 	@echo "Running RuboCop linting..."
-	bundle exec rubocop
+	bundle exec rubocop $(RUBOCOP_FLAGS)
 	@echo "Running Zeitwerk eager-load check..."
 	bundle exec rake zeitwerk:verify
 	@echo "Running YARD public-method docs check..."
@@ -105,6 +107,13 @@ ready: ## Pre-commit gate (quick checks + RSpec)
 	bundle exec rspec
 	@echo "Pre-commit checks complete!"
 
+ci-ready: ## CI parity gate (ready + OpenAPI verify + frontend e2e smoke)
+	@echo "Running CI parity checks..."
+	$(MAKE) ready
+	$(MAKE) openapi-verify
+	$(MAKE) test-frontend-e2e
+	@echo "CI parity checks complete!"
+
 yard-verify-public-docs: ## Verify essential YARD docs for all public methods in app/
 	bundle exec rake yard:verify_public_docs
 

app.rb

@@ -13,6 +13,21 @@
 
 module Html2rss
   module Web
+    DEFAULT_HEADERS = {
+      'X-Content-Type-Options' => 'nosniff',
+      'X-XSS-Protection' => '1; mode=block',
+      'X-Frame-Options' => 'SAMEORIGIN',
+      'X-Permitted-Cross-Domain-Policies' => 'none',
+      'Referrer-Policy' => 'strict-origin-when-cross-origin',
+      'Permissions-Policy' => 'geolocation=(), microphone=(), camera=()',
+      'Strict-Transport-Security' => 'max-age=31536000; includeSubDomains; preload',
+      'Cross-Origin-Embedder-Policy' => 'require-corp',
+      'Cross-Origin-Opener-Policy' => 'same-origin',
+      'Cross-Origin-Resource-Policy' => 'same-origin',
+      'X-DNS-Prefetch-Control' => 'off',
+      'X-Download-Options' => 'noopen'
+    }.freeze
+
     ##
     # Roda app serving RSS feeds via html2rss
     class App < Roda
@@ -41,9 +56,14 @@ def development? = self.class.development?
       use Rack::Cache, metastore: 'file:./tmp/rack-cache-meta', entitystore: 'file:./tmp/rack-cache-body',
                        verbose: development?
 
+      # rubocop:disable Metrics/BlockLength
       plugin :content_security_policy do |csp|
         csp.default_src :none
-        csp.style_src :self, "'unsafe-inline'"
+        if development?
+          csp.style_src :self, "'unsafe-inline'"
+        else
+          csp.style_src :self
+        end
         csp.script_src :self
         csp.connect_src :self
         csp.img_src :self
@@ -65,21 +85,9 @@ def development? = self.class.development?
         csp.block_all_mixed_content
         csp.upgrade_insecure_requests
       end
+      # rubocop:enable Metrics/BlockLength
 
-      plugin :default_headers, {
-        'X-Content-Type-Options' => 'nosniff',
-        'X-XSS-Protection' => '1; mode=block',
-        'X-Frame-Options' => 'SAMEORIGIN',
-        'X-Permitted-Cross-Domain-Policies' => 'none',
-        'Referrer-Policy' => 'strict-origin-when-cross-origin',
-        'Permissions-Policy' => 'geolocation=(), microphone=(), camera=()',
-        'Strict-Transport-Security' => 'max-age=31536000; includeSubDomains; preload',
-        'Cross-Origin-Embedder-Policy' => 'require-corp',
-        'Cross-Origin-Opener-Policy' => 'same-origin',
-        'Cross-Origin-Resource-Policy' => 'same-origin',
-        'X-DNS-Prefetch-Control' => 'off',
-        'X-Download-Options' => 'noopen'
-      }
+      plugin :default_headers, DEFAULT_HEADERS
 
       plugin :json_parser
       plugin :static,
@@ -98,9 +106,20 @@ def development? = self.class.development?
 
       route do |r|
         r.public
+        r.root do
+          if development?
+            render_development_api_landing(r)
+          else
+            render_index_page(r)
+          end
+        end
 
         Routes::ApiV1.call(r) ||
-          Routes::FeedPages.call(r, index_renderer: ->(router_ctx) { render_index_page(router_ctx) })
+          Routes::FeedPages.call(
+            r,
+            index_renderer: ->(router_ctx) { render_index_page(router_ctx) },
+            serve_spa: !development?
+          )
       end
 
       private
@@ -109,6 +128,11 @@ def render_index_page(router)
         router.response['Content-Type'] = 'text/html'
         File.exist?(FRONTEND_INDEX_PATH) ? File.read(FRONTEND_INDEX_PATH) : FALLBACK_HTML
       end
+
+      def render_development_api_landing(router)
+        router.response['Content-Type'] = 'text/html'
+        DevelopmentLandingPage::HTML
+      end
     end
   end
 end

app/web/api/v1/contract.rb

@@ -4,17 +4,158 @@ module Html2rss
   module Web
     module Api
       module V1
-        module Contract
+        ##
+        # Shared API v1 contract constants and payload builders.
+        module Contract # rubocop:disable Metrics/ModuleLength
           CODES = {
             unauthorized: Html2rss::Web::UnauthorizedError::CODE,
             forbidden: Html2rss::Web::ForbiddenError::CODE,
             internal_server_error: Html2rss::Web::InternalServerError::CODE
           }.freeze
 
+          ERROR_KINDS = {
+            auth: 'auth',
+            input: 'input',
+            network: 'network',
+            server: 'server'
+          }.freeze
+
+          NEXT_ACTIONS = {
+            enter_token: 'enter_token',
+            correct_input: 'correct_input',
+            retry: 'retry',
+            wait: 'wait',
+            none: 'none'
+          }.freeze
+
+          RETRY_ACTIONS = {
+            alternate: 'alternate',
+            primary: 'primary',
+            none: 'none'
+          }.freeze
+
+          READINESS_PHASES = {
+            link_created: 'link_created',
+            feed_ready: 'feed_ready',
+            feed_not_ready_yet: 'feed_not_ready_yet',
+            preview_unavailable: 'preview_unavailable'
+          }.freeze
+
+          PREVIEW_STATUSES = {
+            pending: 'pending',
+            ready: 'ready',
+            degraded: 'degraded',
+            unavailable: 'unavailable'
+          }.freeze
+
           MESSAGES = {
             auto_source_disabled: 'Auto source feature is disabled',
             health_check_failed: 'Health check failed'
           }.freeze
+
+          class << self
+            # Builds the structured API error envelope used by JSON API routes.
+            #
+            # @param error [StandardError]
+            # @return [Hash{Symbol=>Object}] structured API error details.
+            def failure_payload(error)
+              metadata = failure_metadata(error)
+              base = {
+                message: client_message_for(error),
+                code: error_code_for(error),
+                kind: metadata[:kind],
+                retryable: metadata[:retryable],
+                next_action: metadata[:next_action],
+                retry_action: metadata[:retry_action]
+              }
+              metadata[:next_strategy] ? base.merge(next_strategy: metadata[:next_strategy]) : base
+            end
+
+            # Builds a warning entry for readiness/status responses.
+            #
+            # @param code [String]
+            # @param message [String]
+            # @param retryable [Boolean]
+            # @param next_action [String]
+            # @return [Hash{Symbol=>Object}] structured warning payload.
+            def warning(code:, message:, retryable:, next_action:)
+              {
+                code: code,
+                message: message,
+                retryable: retryable,
+                next_action: next_action
+              }
+            end
+
+            private
+
+            # @param error [StandardError]
+            # @return [Hash{Symbol=>Object}]
+            def failure_metadata(error)
+              case error
+              when Html2rss::Web::AutoSourceDisabledError, Html2rss::Web::HealthCheckFailedError
+                non_retryable_server_failure_metadata
+              when Html2rss::Web::UnauthorizedError then auth_failure_metadata
+              when Html2rss::Web::BadRequestError, Html2rss::Web::ForbiddenError then input_failure_metadata
+              else
+                generic_failure_metadata(error)
+              end
+            end
+
+            # @param error [StandardError]
+            # @return [Hash{Symbol=>Object}]
+            def generic_failure_metadata(error)
+              kind = Html2rss::Web::ErrorClassification.network_error?(error) ? :network : :server
+              {
+                kind: ERROR_KINDS[kind],
+                retryable: true,
+                next_action: NEXT_ACTIONS[:retry],
+                retry_action: RETRY_ACTIONS[:primary]
+              }
+            end
+
+            # @return [Hash{Symbol=>Object}]
+            def auth_failure_metadata
+              {
+                kind: ERROR_KINDS[:auth],
+                retryable: false,
+                next_action: NEXT_ACTIONS[:enter_token],
+                retry_action: RETRY_ACTIONS[:none]
+              }
+            end
+
+            # @return [Hash{Symbol=>Object}]
+            def input_failure_metadata
+              {
+                kind: ERROR_KINDS[:input],
+                retryable: false,
+                next_action: NEXT_ACTIONS[:correct_input],
+                retry_action: RETRY_ACTIONS[:none]
+              }
+            end
+
+            # @return [Hash{Symbol=>Object}]
+            def non_retryable_server_failure_metadata
+              {
+                kind: ERROR_KINDS[:server],
+                retryable: false,
+                next_action: NEXT_ACTIONS[:none],
+                retry_action: RETRY_ACTIONS[:none]
+              }
+            end
+
+            # @param error [StandardError]
+            # @return [String]
+            def client_message_for(error)
+              error.is_a?(Html2rss::Web::HttpError) ? error.message : Html2rss::Web::HttpError::DEFAULT_MESSAGE
+            end
+
+            # @param error [StandardError]
+            # @return [String]
+            def error_code_for(error)
+              error.respond_to?(:code) ? error.code : CODES[:internal_server_error]
+            end
+          end
         end
       end
     end

app/web/api/v1/create_feed.rb

@@ -11,18 +11,21 @@ module V1
         # Creates stable feed records from authenticated API requests.
         module CreateFeed # rubocop:disable Metrics/ModuleLength
           FEED_ATTRIBUTE_KEYS =
-            %i[id name url strategy feed_token public_url json_public_url created_at updated_at].freeze
+            %i[id name url feed_token public_url json_public_url created_at updated_at].freeze
           class << self # rubocop:disable Metrics/ClassLength
             # Creates a feed and returns a normalized API success payload.
             #
             # @param request [Rack::Request] HTTP request with auth context.
             # @return [Hash{Symbol=>Object}] API response payload.
-            def call(request)
+            def call(request) # rubocop:disable Metrics/MethodLength
               params, feed_data = build_feed_from_request(request)
               emit_create_success(params)
               Response.success(response: request.response,
                                status: 201,
-                               data: { feed: feed_attributes(feed_data) },
+                               data: {
+                                 feed: feed_attributes(feed_data),
+                                 conversion: FeedStatus.initial_conversion
+                               },
                                meta: { created: true })
             rescue StandardError => error
               emit_create_failure(error)
@@ -33,7 +36,7 @@ def call(request)
 
             # @return [void]
             def ensure_auto_source_enabled!
-              raise Html2rss::Web::ForbiddenError, Contract::MESSAGES[:auto_source_disabled] unless AutoSource.enabled?
+              raise Html2rss::Web::AutoSourceDisabledError unless AutoSource.enabled?
             end
 
             # @param request [Rack::Request]
@@ -52,8 +55,7 @@ def build_create_params(params, account)
               url = validated_url(params['url'], account)
               FeedMetadata::CreateParams.new(
                 url: url,
-                name: FeedMetadata.site_title_for(url),
-                strategy: normalize_strategy(params['strategy'])
+                name: FeedMetadata.site_title_for(url)
               )
             end
 
@@ -101,33 +103,6 @@ def hostname_input?(url)
               }ix.match?(url)
             end
 
-            # @param raw_strategy [String, nil]
-            # @return [String]
-            def normalize_strategy(raw_strategy)
-              strategy = raw_strategy.to_s.strip
-              strategy = default_strategy if strategy.empty?
-
-              raise Html2rss::Web::BadRequestError, 'Unsupported strategy' unless supported_strategy?(strategy)
-
-              strategy
-            end
-
-            # @return [Array<String>] supported strategy identifiers.
-            def supported_strategies
-              Html2rss::RequestService.strategy_names.map(&:to_s)
-            end
-
-            # @param strategy [String]
-            # @return [Boolean]
-            def supported_strategy?(strategy)
-              supported_strategies.include?(strategy)
-            end
-
-            # @return [String] default strategy identifier.
-            def default_strategy
-              Html2rss::RequestService.default_strategy_name.to_s
-            end
-
             # @param feed_data [Hash, Html2rss::Web::Api::V1::FeedMetadata::Metadata]
             # @return [Hash{Symbol=>Object}]
             def feed_attributes(feed_data)
@@ -167,7 +142,7 @@ def build_feed_from_request(request)
               ensure_auto_source_enabled!
               params = build_create_params(request_params(request), account)
 
-              feed_data = AutoSource.create_stable_feed(params.name, params.url, account, params.strategy)
+              feed_data = AutoSource.create_stable_feed(params.name, params.url, account)
               raise Html2rss::Web::InternalServerError, 'Failed to create feed' unless feed_data
 
               [params, feed_data]
@@ -179,7 +154,7 @@ def emit_create_success(params)
               Observability.emit(
                 event_name: 'feed.create',
                 outcome: 'success',
-                details: { strategy: params.strategy, url: params.url },
+                details: { url: params.url },
                 level: :info
               )
             end