Simplify feed creation review follow-ups

Author: gildesmarais

app/web/api/v1/create_feed.rb

@@ -12,6 +12,8 @@ module V1
         module CreateFeed
           FEED_ATTRIBUTE_KEYS =
             %i[id name url feed_token public_url json_public_url created_at updated_at].freeze
+          FEED_METADATA_KEYS =
+            %i[id name url username feed_token public_url json_public_url].freeze
 
           class << self
             # Creates a feed and returns a normalized API success payload.
@@ -138,7 +140,13 @@ def create_feed(params, account)
               feed_data = AutoSource.create_stable_feed(params.name, params.url, account)
               raise Html2rss::Web::InternalServerError, 'Failed to create feed' unless feed_data
 
-              feed_data.is_a?(FeedMetadata::Metadata) ? feed_data : FeedMetadata::Metadata.new(**feed_data)
+              feed_data.is_a?(FeedMetadata::Metadata) ? feed_data : feed_metadata(feed_data)
+            end
+
+            # @param feed_data [Hash]
+            # @return [Html2rss::Web::Api::V1::FeedMetadata::Metadata]
+            def feed_metadata(feed_data)
+              FeedMetadata::Metadata.new(**feed_data.slice(*FEED_METADATA_KEYS))
             end
 
             # @param feed_data [Html2rss::Web::Api::V1::FeedMetadata::Metadata]

app/web/api/v1/feed_metadata.rb

@@ -34,7 +34,6 @@ def metadata_attributes(attributes)
                 name: attributes[:name],
                 url: attributes[:url],
                 username: attributes[:username],
-                strategy: attributes[:strategy],
                 feed_token: attributes[:feed_token],
                 public_url: public_url(attributes[:feed_token]),
                 json_public_url: json_public_url(attributes[:feed_token])
@@ -73,15 +72,14 @@ def to_h
 
           ##
           # Feed metadata contract used between creation services and API responses.
-          Metadata = Data.define(:id, :name, :url, :username, :strategy, :feed_token, :public_url, :json_public_url) do
+          Metadata = Data.define(:id, :name, :url, :username, :feed_token, :public_url, :json_public_url) do
             # @return [Hash{Symbol=>Object}]
             def to_h
               {
                 id: id,
                 name: name,
                 url: url,
                 username: username,
-                strategy: strategy,
                 feed_token: feed_token,
                 public_url: public_url,
                 json_public_url: json_public_url

app/web/feeds/source_resolver.rb

@@ -133,7 +133,10 @@ def token_generator_input(url, strategy)
 
           # @return [String]
           def default_strategy_name
-            return Html2rss::Config.default_strategy_name.to_s if Html2rss::Config.respond_to?(:default_strategy_name)
+            if Html2rss::Config.respond_to?(:default_strategy_name)
+              configured = Html2rss::Config.default_strategy_name.to_s
+            end
+            return configured unless configured.to_s.strip.empty?
 
             'auto'
           end

docs/README.md

@@ -75,7 +75,7 @@ To change or add API endpoints, follow this sequence:
 1. **Ruby Request Spec**: Define the new behavior or endpoint in `spec/html2rss/web/app_integration_spec.rb` or a dedicated request spec.
 2. **OpenAPI Generation**: Run `make openapi` inside the Dev Container to regenerate `public/openapi.yaml` from the spec metadata.
 3. **Verify Contract**: Run `make openapi-verify` and `make openapi-lint` to ensure the generated file matches the specs and is valid.
-4. **Frontend Client**: The frontend generated client in `frontend/src/api/generated` is updated by the build process.
+4. **Frontend Client**: Keep generated client artifacts in `frontend/src/api/generated` aligned with `public/openapi.yaml`.
 
 Always verify the contract before committing API changes.
 
@@ -218,19 +218,11 @@ Critical-path event families: auth, feed create, feed render, request errors.
 When `SENTRY_DSN` is present, Sentry is enabled. `BUILD_TAG` and `GIT_SHA` become the release identifier, and
 `RACK_ENV` becomes the environment tag.
 
-First-15-minute triage checklist:
+Triage starts with the newest `feed.create`, `feed.render`, and `request.error` events. Confirm the release tag,
+route group, strategy, and outcome before deciding whether the failure is retryable, terminal, or user-facing.
 
-1. Open the newest `feed.create`, `feed.render`, and `request.error` events.
-2. Confirm the release tag matches the deployed build.
-3. Check the breadcrumb trail for the failing path, strategy, and outcome.
-4. Decide whether the failure is retryable or terminal before paging the user-facing incident path.
-
-Alert baseline:
-
-1. Page on sustained `request.error` spikes in production.
-2. Page on a repeated `feed.render` failure burst, especially when success drops to zero for a route or strategy.
-3. Track the first recovery signal after fallback or retry succeeds so the incident can be closed quickly.
-4. Keep the initial threshold simple; tune after a few real incidents instead of pre-optimizing for every edge case.
+Alert on sustained production `request.error` spikes or repeated `feed.render` failures, then tune thresholds from
+real incidents.
 
 ---
 

frontend/e2e/smoke.spec.ts

@@ -42,10 +42,11 @@ test.describe('frontend smoke', () => {
     await page.getByRole('button', { name: 'Back' }).click();
     await expect(page).toHaveURL(/#\/create(?:\?.*)?$/);
     await expect(page.getByRole('button', { name: 'Generate feed URL' })).toBeVisible();
-    await expect(page.locator('.form-shell')).toHaveAttribute('data-state', 'idle');
+    await expect(page.locator('.form-shell')).toHaveAttribute('data-state', 'create');
+    await expect(page.getByLabel('Utilities')).toBeVisible();
   });
 
-  test('restores result deep links and shows a recovery state when snapshot is missing', async ({ page }) => {
+  test('shows result after successful feed creation without snapshot recovery', async ({ page }) => {
     await page.route(/\/api\/v1$/, async (route) => {
       await route.fulfill({
         status: 200,
@@ -70,12 +71,13 @@ test.describe('frontend smoke', () => {
       });
     });
 
-    await page.addInitScript(() => {
-      localStorage.setItem(
-        'html2rss_feed_result_snapshot:generated-token',
-        JSON.stringify({
-          savedAt: '2026-04-05T09:00:00.000Z',
-          result: {
+    await page.route(/\/api\/v1\/feeds$/, async (route) => {
+      await route.fulfill({
+        status: 201,
+        contentType: 'application/json',
+        body: JSON.stringify({
+          success: true,
+          data: {
             feed: {
               id: 'feed-123',
               name: 'Example Feed',
@@ -86,45 +88,50 @@ test.describe('frontend smoke', () => {
               created_at: '2026-04-05T08:59:00.000Z',
               updated_at: '2026-04-05T09:00:00.000Z',
             },
-            preview: {
-              items: [
-                {
-                  title: 'Sample preview item',
-                  excerpt: 'Current restore snapshots include preview content.',
-                  publishedLabel: 'April 5, 2026',
-                  url: 'https://example.com/articles/sample-preview-item',
-                },
-              ],
-              isLoading: false,
-            },
-            workflowState: 'preview_ready' as const,
-            warnings: [],
           },
-        })
-      );
+        }),
+      });
+    });
+
+    await page.route(/\/api\/v1\/feeds\/generated-token\.json$/, async (route) => {
+      await route.fulfill({
+        status: 200,
+        contentType: 'application/feed+json',
+        body: JSON.stringify({
+          items: [
+            {
+              title: 'Sample preview item',
+              content_text: 'Current preview fetch includes rendered content.',
+              date_published: '2026-04-05T09:00:00.000Z',
+              url: 'https://example.com/articles/sample-preview-item',
+            },
+          ],
+        }),
+      });
     });
 
-    await page.goto('/#/result/generated-token');
+    await page.addInitScript(() => {
+      sessionStorage.setItem('html2rss_access_token', 'token-123');
+    });
+
+    await page.goto('/');
+    await page.getByLabel('Page URL').fill('https://example.com/articles');
+    await page.getByRole('button', { name: 'Generate feed URL' }).click();
 
     await expect(page.getByRole('heading', { name: 'Feed ready' })).toBeVisible();
-    await expect(page.locator('.result-shell')).toHaveAttribute('data-state', 'ready');
+    await expect(page.locator('.result-shell')).toHaveAttribute('data-state', 'result');
     await expect(page.getByText('Example Feed')).toBeVisible();
     await expect(page.getByRole('link', { name: 'Open feed' })).toBeVisible();
     await expect(page.getByRole('link', { name: 'Open JSON Feed' })).toBeVisible();
     await expect(page.getByRole('link', { name: 'Open in feed reader' })).toBeVisible();
     await expect(page.getByRole('button', { name: 'Create another feed' })).toBeVisible();
     await expect(page.getByText('Sample preview item')).toBeVisible();
-    await expect(page.getByText('Current restore snapshots include preview content.')).toBeVisible();
-
-    await page.evaluate(() => {
-      localStorage.removeItem('html2rss_feed_result_snapshot:missing-token');
-    });
+    await expect(page.getByText('Current preview fetch includes rendered content.')).toBeVisible();
 
     await page.goto('/#/result/missing-token');
 
-    await expect(page.getByText('Saved result unavailable')).toBeVisible();
-    await expect(page.getByText('Create a new feed link to continue.')).toBeVisible();
-    await expect(page.getByRole('button', { name: 'Go to create' })).toBeVisible();
-    await expect(page.locator('.result-recovery')).toHaveAttribute('data-state', 'failed');
+    await expect(page.getByLabel('Page URL')).toBeVisible();
+    await expect(page.getByText('Saved result unavailable')).toHaveCount(0);
+    await expect(page.locator('.result-recovery')).toHaveCount(0);
   });
 });

frontend/src/__tests__/App.contract.test.tsx

@@ -105,7 +105,7 @@ describe('App contract', () => {
     await waitFor(() => {
       expect(screen.getByText('Feed ready')).toBeInTheDocument();
       expect(screen.getByText('Example Feed')).toBeInTheDocument();
-      expect(document.querySelector('.result-shell')).toHaveAttribute('data-state', 'ready');
+      expect(document.querySelector('.result-shell')).toHaveAttribute('data-state', 'result');
       expect(screen.getByLabelText('Feed URL')).toBeInTheDocument();
       expect(screen.getByRole('button', { name: 'Copy feed URL' })).toBeInTheDocument();
       expect(screen.getByRole('button', { name: 'Create another feed' })).toBeInTheDocument();

frontend/src/__tests__/App.test.tsx

@@ -47,7 +47,6 @@ describe('App', () => {
   const mockClearConversionError = vi.fn();
   const mockClearResult = vi.fn();
   const mockRetryPreviewFetch = vi.fn();
-  const mockRestoreResult = vi.fn();
 
   beforeEach(() => {
     vi.clearAllMocks();
@@ -91,7 +90,6 @@ describe('App', () => {
       clearError: mockClearConversionError,
       clearResult: mockClearResult,
       retryPreviewFetch: mockRetryPreviewFetch,
-      restoreResult: mockRestoreResult,
     });
   });
 
@@ -104,7 +102,7 @@ describe('App', () => {
     expect(screen.queryByRole('combobox')).not.toBeInTheDocument();
     expect(screen.getByLabelText('Utilities')).toBeInTheDocument();
     expect(screen.getByRole('link', { name: 'Bookmarklet' })).toBeInTheDocument();
-    expect(document.querySelector('.form-shell')).toHaveAttribute('data-state', 'idle');
+    expect(document.querySelector('.form-shell')).toHaveAttribute('data-state', 'create');
   });
 
   it('keeps the page url field permissive enough for hostname-only input', () => {
@@ -170,61 +168,13 @@ describe('App', () => {
     });
   });
 
-  it('restores result state from local snapshot when opening a result deep link', async () => {
-    globalThis.localStorage.setItem(
-      'html2rss_feed_result_snapshot:generated-token',
-      JSON.stringify({
-        savedAt: '2026-04-05T09:00:00.000Z',
-        result: {
-          feed: {
-            id: 'feed-123',
-            name: 'Example Feed',
-            url: 'https://example.com/articles',
-            feed_token: 'generated-token',
-            public_url: '/api/v1/feeds/generated-token',
-            json_public_url: '/api/v1/feeds/generated-token.json',
-            created_at: '2026-04-05T08:59:00.000Z',
-            updated_at: '2026-04-05T09:00:00.000Z',
-          },
-          preview: {
-            items: [],
-            isLoading: false,
-          },
-          workflowState: 'preview_ready' as const,
-          warnings: [],
-        },
-      })
-    );
+  it('shows the create flow when opening a stale result deep link', async () => {
     globalThis.history.replaceState({}, '', 'http://localhost:3000/#/result/generated-token');
 
     render(<App />);
 
-    await waitFor(() => {
-      expect(mockRestoreResult).toHaveBeenCalledTimes(1);
-      expect(mockRestoreResult).toHaveBeenCalledWith(
-        expect.objectContaining({
-          feed: expect.objectContaining({ feed_token: 'generated-token' }),
-          workflowState: 'preview_ready',
-        })
-      );
-    });
-  });
-
-  it('shows a recovery notice when result deep link has no snapshot to restore', async () => {
-    globalThis.history.replaceState({}, '', 'http://localhost:3000/#/result/missing-token');
-
-    render(<App />);
-
-    await waitFor(() => {
-      expect(screen.getByRole('heading', { name: 'Saved result unavailable' })).toBeInTheDocument();
-    });
-
-    expect(screen.getByRole('alert')).toHaveClass('result-shell', 'result-recovery');
-    expect(screen.getByRole('alert')).toHaveAttribute('data-state', 'failed');
-    expect(document.querySelector('.result-recovery .ui-hero')).toBeInTheDocument();
-    expect(document.querySelector('.result-recovery .layout-rail-reading')).toBeInTheDocument();
-    expect(screen.getAllByRole('button')).toHaveLength(1);
-    expect(screen.getByRole('button', { name: 'Go to create' })).toHaveClass('btn--primary');
+    expect(screen.getByLabelText('Page URL')).toBeInTheDocument();
+    expect(screen.queryByRole('heading', { name: 'Saved result unavailable' })).not.toBeInTheDocument();
   });
 
   it('shows inline token prompt when submitting without a token', async () => {
@@ -237,10 +187,10 @@ describe('App', () => {
 
     expect(screen.getByText('Enter access token')).toBeInTheDocument();
     expect(globalThis.location.hash).toMatch(/^#\/token/);
-    expect(document.querySelector('.form-shell')).toHaveAttribute('data-state', 'token_required');
+    expect(document.querySelector('.form-shell')).toHaveAttribute('data-state', 'token_prompt');
     expect(screen.getByLabelText('Page URL')).toBeDisabled();
     expect(screen.queryByRole('combobox')).not.toBeInTheDocument();
-    expect(screen.queryByLabelText('Utilities')).not.toBeInTheDocument();
+    expect(screen.getByLabelText('Utilities')).toBeInTheDocument();
     expect(screen.getByRole('link', { name: 'Set up your own instance with Docker.' })).toBeInTheDocument();
     expect(screen.getByText('Required by this instance.')).toBeInTheDocument();
     expect(screen.queryByText('Paste an access token to keep going.')).not.toBeInTheDocument();
@@ -319,12 +269,11 @@ describe('App', () => {
       clearError: mockClearConversionError,
       clearResult: mockClearResult,
       retryPreviewFetch: mockRetryPreviewFetch,
-      restoreResult: mockRestoreResult,
     });
 
     render(<App />);
 
-    expect(document.querySelector('.result-shell')).toHaveAttribute('data-state', 'failed');
+    expect(document.querySelector('.result-shell')).toHaveAttribute('data-state', 'result');
     expect(screen.getByRole('button', { name: 'Create another feed' })).toBeInTheDocument();
     expect(screen.getByRole('link', { name: 'Open feed' })).toBeInTheDocument();
     expect(screen.getByRole('link', { name: 'Bookmarklet' })).toBeInTheDocument();
@@ -354,7 +303,6 @@ describe('App', () => {
       clearError: mockClearConversionError,
       clearResult: mockClearResult,
       retryPreviewFetch: mockRetryPreviewFetch,
-      restoreResult: mockRestoreResult,
     });
 
     render(<App />);
@@ -372,7 +320,6 @@ describe('App', () => {
       clearError: mockClearConversionError,
       clearResult: mockClearResult,
       retryPreviewFetch: mockRetryPreviewFetch,
-      restoreResult: mockRestoreResult,
     });
 
     render(<App />);
@@ -563,7 +510,6 @@ describe('App', () => {
       clearError: mockClearConversionError,
       clearResult: mockClearResult,
       retryPreviewFetch: mockRetryPreviewFetch,
-      restoreResult: mockRestoreResult,
     });
     mockUseAccessToken.mockReturnValue({
       token: 'saved-token',
@@ -604,7 +550,6 @@ describe('App', () => {
       clearError: mockClearConversionError,
       clearResult: mockClearResult,
       retryPreviewFetch: mockRetryPreviewFetch,
-      restoreResult: mockRestoreResult,
     });
     mockUseAccessToken.mockReturnValue({
       token: 'saved-token',
@@ -643,7 +588,6 @@ describe('App', () => {
       clearError: mockClearConversionError,
       clearResult: mockClearResult,
       retryPreviewFetch: mockRetryPreviewFetch,
-      restoreResult: mockRestoreResult,
     });
     mockUseAccessToken.mockReturnValue({
       token: 'saved-token',
@@ -682,7 +626,6 @@ describe('App', () => {
       clearError: mockClearConversionError,
       clearResult: mockClearResult,
       retryPreviewFetch: mockRetryPreviewFetch,
-      restoreResult: mockRestoreResult,
     });
     mockUseAccessToken.mockReturnValue({
       token: 'saved-token',