# Live Recipe Reload Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Add an SSE endpoint that pushes recipe-change events to browsers, triggering automatic page reload on the index and recipe detail pages.

**Architecture:** A `ChangeLog` `IORef (Int, [(Int, FilePath)])` records every recipe change with a monotonic version. The watcher appends to it. A new `/events` route returns a streaming `text/event-stream` response — each connection polls the ChangeLog every 500ms and pushes new events. Client-side JS uses `EventSource` to listen and `location.reload()` on match.

**Tech Stack:** Haskell, WAI streaming responses, native browser `EventSource` API.

---

## File Map

| File | Action | Purpose |
|---|---|---|
| `src/Roux/Server.hs` | Modify | Add ChangeLog, SSE handler, router; thread ChangeLog through watcher |
| `src/Roux/Html.hs` | Modify | Add SSE client JS to index page and recipe detail page |

---

### Task 1: Add SSE infrastructure to `Server.hs`

**Files:**
- Modify: `src/Roux/Server.hs`

This is the main implementation task. All server-side changes are in one file.

- [ ] **Step 1: Add required imports**

Add to the import block in `src/Roux/Server.hs`:

```haskell
import Control.Exception (IOException, SomeException, catch, finally, try)
import qualified Data.ByteString.Lazy.Char8 as LB8
import Data.IORef (IORef, atomicModifyIORef', newIORef, readIORef, writeIORef)
import Data.Time.Clock (UTCTime, getCurrentTime, diffUTCTime)
```

Replace the existing `import Control.Exception (IOException, SomeException, catch, try)` and `import Data.IORef (IORef, atomicModifyIORef', newIORef, readIORef)` lines with the above (adds `finally`, `writeIORef`, `Data.Time.Clock` imports, and `LB8`).

- [ ] **Step 2: Add the `ChangeLog` type alias and `recordChange` function**

Add after the `where` clause of `app` (before `watchRecipes`):

```haskell
-- | A change log with a monotonic version counter and
-- the last N changed filenames (newest first).
type ChangeLog = IORef (Int, [(Int, FilePath)])

-- | Record a recipe file change in the change log.
recordChange :: ChangeLog -> FilePath -> IO ()
recordChange changeLog path = atomicModifyIORef' changeLog $ \(version, entries) ->
    let newVersion = version + 1
        newEntries = (newVersion, path) : take 99 entries
    in ((newVersion, newEntries), ())
```

- [ ] **Step 3: Add the SSE handler**

Add after `recordChange` (before `handleRequest`):

```haskell
{- | SSE endpoint — streams recipe-change events to connected clients.
Polls 'ChangeLog' every 500ms and pushes any new events since the
client's last seen version. Sends a @ping@ event every 30s as a
keepalive. Client disconnect is detected by Warp when the write
action throws.
-}
sseHandler :: ChangeLog -> Wai.Application
sseHandler changeLog _request respond = do
    respond $
        Wai.responseStream
            HTTP.status200
            [ ("Content-Type", "text/event-stream")
            , ("Cache-Control", "no-cache")
            , ("Connection", "keep-alive")
            ]
            $ \write flush -> do
                lastSent <- newIORef 0
                lastPing <- newIORef 0
                let sendPing = do
                        write "event: ping\ndata: keepalive\n\n"
                        flush
                let go = do
                        now <- getCurrentTime
                        (version, entries) <- readIORef changeLog
                        sent <- readIORef lastSent
                        when (version > sent) $ do
                            let newEntries = takeWhile (\(v, _) -> v > sent) entries
                            forM_ newEntries $ \(_v, path) -> do
                                write $ LB8.unlines
                                    [ "event: recipe-changed"
                                    , "data: " <> LB8.pack path
                                    , ""
                                    , ""
                                    ]
                            writeIORef lastSent version
                            flush
                        pingTime <- readIORef lastPing
                        when (diffUTCTime now pingTime > 30) $ do
                            writeIORef lastPing now
                            sendPing
                        threadDelay 500_000  -- 500ms poll interval
                        go
                -- Send an initial ping so the client detects connection immediately
                pingTime <- getCurrentTime
                writeIORef lastPing pingTime
                sendPing
                go `finally` pure ()
```

- [ ] **Step 4: Add the router function**

Add after `sseHandler` (before `handleRequest`):

```haskell
-- | Route requests — SSE endpoint or recipe pages.
router :: IORef (Map FilePath Idx.RecipeInfo) -> ChangeLog -> Wai.Application
router state changeLog request respond =
    case Wai.pathInfo request of
        ["events"] -> sseHandler changeLog request respond
        _          -> handleRequest state request respond
```

- [ ] **Step 5: Update `app` to create ChangeLog and use router**

Change the end of `app` — replace:

```haskell
    pure (handleRequest state)
```

with:

```haskell
    changeLog <- newIORef (0, [])
    _ <-
        forkIO $
            watchRecipes absDir state changeLog `catch` \e ->
                putStrLn $ "[roux] watcher thread crashed: " <> show (e :: SomeException)
    pure (router state changeLog)
```

Note: remove the existing `forkIO` for `watchRecipes` — the new one above replaces both `state` and `changeLog` setup.

The full `app` function body after the change should look like:

```haskell
app :: FilePath -> IO Wai.Application
app recipeDir = do
    putStrLn $ "[roux] scanning recipes from " <> recipeDir
    recipes <- Idx.scanRecipes recipeDir
    let count = length recipes
        ok = length [() | r <- recipes, isRight (Idx.riRecipe r)]
        errs = count - ok
    putStrLn $ "[roux] found " <> show count <> " recipe(s)"
    when (errs > 0) $
        putStrLn $
            "[roux] " <> show errs <> " had parse errors"
    -- Build initial map keyed by lowercased filename (without .cook extension)
    let recipeMap = Map.fromList [(map toLower (stripCookExt (Idx.riFilename r)), r) | r <- recipes]
    state <- newIORef recipeMap
    -- Resolve to absolute path so makeRelative works with fsnotify events
    absDir <- makeAbsolute recipeDir
    -- Change log for SSE notifications
    changeLog <- newIORef (0, [])
    -- Start the filesystem watcher
    _ <-
        forkIO $
            watchRecipes absDir state changeLog `catch` \e ->
                putStrLn $ "[roux] watcher thread crashed: " <> show (e :: SomeException)
    pure (router state changeLog)
```

- [ ] **Step 6: Update `watchRecipes` signature and body to accept `ChangeLog`**

Replace the `watchRecipes` signature and body:

```haskell
watchRecipes :: FilePath -> IORef (Map FilePath Idx.RecipeInfo) -> ChangeLog -> IO ()
```

And update the callback to pass `changeLog` to `reReadRecipe`:

```haskell
watchRecipes dir state changeLog = do
    putStrLn $ "[roux] watching " <> dir <> " for changes"
    let cfg = defaultConfig{confWatchMode = WatchModeOS}
    withManagerConf cfg $ \mgr -> do
        _stopListening <- watchDir mgr dir (const True) $ \ev ->
            catch
                ( do
                    when (eventIsDirectory ev == IsFile && ".cook" `isSuffixOf` eventPath ev) $ do
                        let path = makeRelative dir (eventPath ev)
                        reReadRecipe dir path state changeLog
                )
                ( \e ->
                    putStrLn $
                        "[roux] watchDir callback error: " <> show (e :: SomeException)
                )
        -- Keep the thread alive (watchDir runs the callback on the manager thread)
        forever $ threadDelay 1000000
```

- [ ] **Step 7: Update `reReadRecipe` signature and body to accept and use `ChangeLog`**

Replace the `reReadRecipe` signature:

```haskell
reReadRecipe :: FilePath -> FilePath -> IORef (Map FilePath Idx.RecipeInfo) -> ChangeLog -> IO ()
```

And update the two mutation sites to also record the change:

In the delete case (`Right False`), replace:

```haskell
            atomicModifyIORef' state $ \m ->
                (Map.delete key m, ())
```

with:

```haskell
            atomicModifyIORef' state $ \m ->
                (Map.delete key m, ())
            recordChange changeLog path
```

In the successful update case (`Right _`), replace:

```haskell
                        atomicModifyIORef' state $ \m ->
                            (Map.insert key info m, ())
```

with:

```haskell
                        atomicModifyIORef' state $ \m ->
                            (Map.insert key info m, ())
                        recordChange changeLog path
```

- [ ] **Step 8: Build to verify compilation**

Run: `./hs stack build`
Expected: compiles without errors.

- [ ] **Step 9: Run tests to verify nothing broke**

Run: `./hs stack test`
Expected: all tests pass.

- [ ] **Step 10: Commit**

```bash
git add src/Roux/Server.hs
git commit -m "feat: add SSE endpoint and ChangeLog for live recipe reload"
```

---

### Task 2: Add SSE client JS to the recipe pages

**Files:**
- Modify: `src/Roux/Html.hs`

- [ ] **Step 1: Add SSE JavaScript constant for the recipe detail page**

Add a new top-level constant near `searchJs` in `src/Roux/Html.hs`:

```haskell
-- | Inline JavaScript for SSE live-reload on the recipe detail page.
sseRecipeJs :: Text
sseRecipeJs =
    T.unlines
        [ "(function(){"
        , "'use strict';"
        , "if (!window.EventSource) return;"
        , "const currentRecipe = document.getElementById('roux-current-recipe').textContent;"
        , "if (!currentRecipe) return;"
        , "const es = new EventSource('/events');"
        , "es.addEventListener('recipe-changed', function(e) {"
        , "  if (e.data === currentRecipe) location.reload();"
        , "});"
        , "})();"
        ]

-- | Inline JavaScript for SSE live-reload on the index page.
sseIndexJs :: Text
sseIndexJs =
    T.unlines
        [ "(function(){"
        , "'use strict';"
        , "if (!window.EventSource) return;"
        , "const es = new EventSource('/events');"
        , "es.addEventListener('recipe-changed', function() { location.reload(); });"
        , "})();"
        ]
```

- [ ] **Step 2: Add hidden filename span and SSE script to `recipePage`**

In `recipePage`, wrap the content passed to `page` to include the hidden span and SSE script. Replace the current body of `recipePage`:

```haskell
recipePage :: Idx.RecipeInfo -> ByteString
recipePage info =
    case Idx.riRecipe info of
        Left err ->
            page "Parse Error" $ do
                H.nav $ H.ul $ H.li $ H.a ! A.href "/" $ "← Back"
                H.h2 "Parse Error"
                H.p $ H.toHtml (Idx.riTitle info <> ": " <> T.pack err)
                hiddenRecipeSpan info
                sseScript
        Right recipe ->
            page (titleText recipe) $ do
                renderRecipe recipe
                hiddenRecipeSpan info
                sseScript
  where
    hiddenRecipeSpan rInfo =
        H.span ! A.id "roux-current-recipe" ! A.style "display:none;" $
            H.toHtml (T.pack (Idx.riFilename rInfo))
    sseScript =
        H.script ! A.type_ "text/javascript" $ H.preEscapedText sseRecipeJs
```

- [ ] **Step 3: Add SSE script to `indexPage`**

In `indexPage`, after the existing `searchJs` script block, add a new script block for the SSE listener. Find this line in `indexPage`:

```haskell
        H.script ! A.type_ "text/javascript" $ H.preEscapedText searchJs
```

And add a second script block right after it:

```haskell
        -- Inline JS for SSE live-reload
        H.script ! A.type_ "text/javascript" $ H.preEscapedText sseIndexJs
```

- [ ] **Step 4: Build to verify compilation**

Run: `./hs stack build`
Expected: compiles without errors.

- [ ] **Step 5: Run tests to verify nothing broke**

Run: `./hs stack test`
Expected: all tests pass.

- [ ] **Step 6: Commit**

```bash
git add src/Roux/Html.hs
git commit -m "feat: add SSE client JS for live recipe reload on detail and index pages"
```