poops 1.7.0 → 1.8.0

package/README.md

@@ -1,4 +1,4 @@
-# 💩 Poops [![npm version](https://img.shields.io/npm/v/poops)](https://www.npmjs.com/package/poops)
+# 💩 Poops [![npm version](https://img.shields.io/npm/v/poops)](https://www.npmjs.com/package/poops) [![build status](https://github.com/stamat/poops/actions/workflows/ci.yml/badge.svg)](https://github.com/stamat/poops/actions/workflows/ci.yml) [![license](https://img.shields.io/github/license/stamat/poops.svg)](https://github.com/stamat/poops/blob/main/LICENSE)
 
 Straightforward, no-bullshit bundler for the web.
 
@@ -551,6 +551,17 @@ Then use Tailwind utility classes directly in your markup templates. Tailwind v4
 
 **💡 NOTE:** If, for instance, you are building a simple static onepager for your library, and want to pass a version variable from your `package.json`, Poops automatically reads your `package.json` if it exists in your working directory and sets the global variable `package` to the parsed JSON. So you can use it in your markup files, for example like this: `{{ package.version }}`.
 
+**"Edit this page on GitHub" links.** Every page exposes `page.filePath` — its source file path relative to your project root, with posix separators (e.g. `src/markup/docs/index.md`). That is exactly the path GitHub's editor expects, so an edit link is one line in your layout:
+
+```nunjucks
+{% set repoUrl = site.repo or package.homepage %}
+{% if page.filePath and repoUrl %}
+<a href="{{ repoUrl }}/edit/{{ site.branch or 'main' }}/{{ page.filePath }}">✏️ Edit this page on GitHub</a>
+{% endif %}
+```
+
+Put `repo` and `branch` in your `site` data (they fall back to `package.homepage` and `main`). Don't rebuild the path from `page.url` — that is the output URL (`.html`, and `index.md` collapses to a directory), so it can't be reversed to the `.md` source.
+
 Here is a sample markup configuration using the default Nunjucks engine:
 
 ```json
@@ -784,9 +795,9 @@ title: Changelog
 collection: true
 paginate: 10
 taxonomies:
-  - name: tags      # front-matter field to group on
-    path: tag       # URL segment (defaults to name); "tag" for a singular URL
-    paginate: 5     # per-term page size (defaults to the collection's paginate)
+  - name: tags # front-matter field to group on
+    path: tag # URL segment (defaults to name); "tag" for a singular URL
+    paginate: 5 # per-term page size (defaults to the collection's paginate)
 ---
 ```
 
@@ -871,9 +882,15 @@ Output:
 ```
 
 ```html
-<img src="static/photo-thumb-480w.webp"
-     srcset="static/photo-thumb-480w.webp 480w, static/photo-thumb.webp 960w"
-     width="480" height="480" sizes="240px" alt="" loading="lazy">
+<img
+  src="static/photo-thumb-480w.webp"
+  srcset="static/photo-thumb-480w.webp 480w, static/photo-thumb.webp 960w"
+  width="480"
+  height="480"
+  sizes="240px"
+  alt=""
+  loading="lazy"
+/>
 ```
 
 This requires the [poops-images](https://github.com/stamat/poops-images) compile cache (named-size widths are read from it). The `size` name matches a named entry in your `images.sizes` config. The largest member of the group is written without a width suffix (`photo-thumb.webp`) — poops still srcsets it at its real width from the cache.
@@ -1041,7 +1058,7 @@ All filters are available in both engines. The only syntax difference is how arg
 
   poops auto-picks `BlogPosting` (page has a `date`) or `WebPage`. Override `@type` with the `jsonld` object for any schema.org type — common ones search/generative engines act on: `Article`, `NewsArticle`, `HowTo`, `FAQPage`, `QAPage`, `Product`, `Recipe`, `Event`, `Course`, `VideoObject`, `SoftwareApplication`, `Organization`, `Person`, `BreadcrumbList`, `WebSite`. Full list at [schema.org/docs/full](https://schema.org/docs/full.html); validate with the [Rich Results Test](https://search.google.com/test/rich-results). A per-`@type` table with the notable fields is in the [Templating docs](example/src/markup/docs/quick-start/templating-html.md).
 
-- `breadcrumb` — generates a visible breadcrumb `<nav class="breadcrumb"><ol>…</ol></nav>` trail for the page body (blog posts, nested pages), from the same URL-depth data the `jsonld` `BreadcrumbList` uses: the site root, each ancestor folder (humanized, e.g. `docs/static-site` → *Static Site*), then the current page as `aria-current` text. Pass `relativePathPrefix` so links resolve against the current output location (localhost in dev, your deployed subpath in prod) — not the absolute domain.
+- `breadcrumb` — generates a visible breadcrumb `<nav class="breadcrumb"><ol>…</ol></nav>` trail for the page body (blog posts, nested pages), from the same URL-depth data the `jsonld` `BreadcrumbList` uses: the site root, each ancestor folder (humanized, e.g. `docs/static-site` → _Static Site_), then the current page as `aria-current` text. Pass `relativePathPrefix` so links resolve against the current output location (localhost in dev, your deployed subpath in prod) — not the absolute domain.
   - Nunjucks: `{{ page | breadcrumb(site, relativePathPrefix) }}`
   - Liquid: `{{ page | breadcrumb: site, relativePathPrefix }}`
 
@@ -1076,7 +1093,7 @@ All filters are available in both engines. The only syntax difference is how arg
 
 Returns: `static/photo-320w.webp 320w, static/photo-640w.webp 640w, static/photo-960w.webp 960w`
 
-  Pass a named crop/resize group as the second argument to get that group's srcset instead of the default widths: `{{ 'static/photo.jpg' | srcset: 'thumb' }}` → `static/photo-thumb-480w.webp 480w, static/photo-thumb.webp 960w`.
+Pass a named crop/resize group as the second argument to get that group's srcset instead of the default widths: `{{ 'static/photo.jpg' | srcset: 'thumb' }}` → `static/photo-thumb-480w.webp 480w, static/photo-thumb.webp 960w`.
 
 - `exif` — returns the EXIF metadata object for an image from the [poops-images](https://github.com/stamat/poops-images) compile cache (`.poops-images-cache.json` in the output directory), or `null` if there is no cache or no EXIF data. The object includes camera (`make`, `model`, `lensModel`), exposure (`fNumber`, `exposure.formatted`, `iso`, `focalLength35mm`), `dateTime`, and `gps` (`latitude.formatted`, `longitude.formatted`, `altitude`, and a ready-made `googleMapsUrl`).
 
@@ -1241,7 +1258,8 @@ Pages with `published: false` in their front matter are excluded from all output
 A page's front matter `robots: noindex` (or `none`) drops it from the **sitemap and llms.txt** — for drafts, thin or utility pages (a 404, say) you don't want crawled or fed to LLMs. It stays in the search index (that's your own on-site search). Emit the matching crawler directive in your layout `<head>` so the page itself carries it:
 
 ```html
-{% if page.robots %}<meta name="robots" content="{{ page.robots }}">{% endif %}
+{% if page.robots %}<meta name="robots" content="{{ page.robots }}" />{% endif
+%}
 ```
 
 **Navigation tree** builds your page hierarchy as sidebar-ready data, exposed two ways: as the `nav` template global (loaded automatically, always reflecting the current build) and as a nested JSON file for client-side rendering. Subpages nest automatically from URL structure: `guide/index.md` becomes a parent node and `guide/getting-started.md`, `guide/advanced/config.md` become its (and its subsections') children. Add `nav` to your markup config:
@@ -1385,7 +1403,11 @@ Shorthand forms: `"feed": true` (or a filename string) emits an RSS feed for eve
 Point browsers and readers at it from your layout `<head>`:
 
 ```html
-<link rel="alternate" type="application/rss+xml" href="{{ site.url }}/blog/feed.rss">
+<link
+  rel="alternate"
+  type="application/rss+xml"
+  href="{{ site.url }}/blog/feed.rss"
+/>
 ```
 
 ### Images (optional)

package/lib/copy.js

@@ -5,7 +5,7 @@ import {
   mkDir,
   copyDirectory,
   buildTime,
-  toPosix
+  replacePathSegment
 } from './utils/helpers.js'
 import fs from 'node:fs'
 import path from 'node:path'
@@ -92,8 +92,10 @@ export default class Copy {
       copyPaths.out = path.join(copyPaths.out, inBaseName)
     }
 
-    // Watcher paths arrive with native separators, config `in` uses `/`
-    file = toPosix(file).replace(copyPaths.in, copyPaths.out)
+    // Watcher paths arrive with native separators, config `in` uses `/`.
+    // Segment-aware swap so an `in` that also appears as a substring inside an
+    // earlier path segment doesn't rewrite the wrong part (and delete a wrong file).
+    file = replacePathSegment(file, copyPaths.in, copyPaths.out)
 
     const outputFilePath = path.resolve(process.cwd(), file)
 

package/lib/markup/engines/liquid.js

@@ -252,6 +252,30 @@ function registerGoogleFontsTag(engine) {
   })
 }
 
+// Splits an {% image %} arg string on top-level commas only, so a quoted value
+// with commas (e.g. sizes: "(max-width: 600px) 100vw, 50vw") stays one part.
+function splitArgsOutsideQuotes(str) {
+  const parts = []
+  let cur = ''
+  let quote = null
+  for (const ch of str) {
+    if (quote) {
+      if (ch === quote) quote = null
+      cur += ch
+    } else if (ch === '"' || ch === "'") {
+      quote = ch
+      cur += ch
+    } else if (ch === ',') {
+      parts.push(cur.trim())
+      cur = ''
+    } else {
+      cur += ch
+    }
+  }
+  parts.push(cur.trim())
+  return parts
+}
+
 function registerImageTag(engine, getOutputDir) {
   engine.registerTag('image', {
     parse(tagToken) {
@@ -259,7 +283,7 @@ function registerImageTag(engine, getOutputDir) {
     },
     * render(ctx) {
       const argsStr = this.args.trim()
-      const parts = argsStr.split(',').map(s => s.trim())
+      const parts = splitArgsOutsideQuotes(argsStr)
 
       let imagePath = parts[0]
       if (imagePath.startsWith('"') || imagePath.startsWith("'")) {

package/lib/markup/engines/nunjucks.js

@@ -15,8 +15,9 @@ class RelativeLoader extends nunjucks.Loader {
   constructor(templatesDir, includePaths, onTouch) {
     super()
     this.templatesDir = templatesDir
-    this.includePaths = includePaths || []
-    this.includePaths.push('_*')
+    // Copy, don't alias+mutate: the caller reuses this array to build the
+    // markup glob exclusions, so pushing '_*' here would leak into it.
+    this.includePaths = [...(includePaths || []), '_*']
     // Reports every compiled-template cache touch (hit or write) with the
     // backing file path — the Environment reads loader.cache directly on
     // hits, so getSource alone never sees reuse of already-compiled templates.

package/lib/markup/indexer.js

@@ -52,7 +52,9 @@ export function extractKeywords(htmlContent, options = {}) {
   const text = htmlContent.replace(/<[^>]*>/g, ' ')
   const words = text
     .toLowerCase()
-    .replace(/[^a-z0-9\-\s]/g, ' ')
+    // Keep any-script letters/numbers (\p{L}\p{N}) so non-English sites get
+    // keywords too — an ASCII-only class stripped every accented/CJK char.
+    .replace(/[^\p{L}\p{N}\-\s]/gu, ' ')
     .split(/\s+/)
     .filter(w => w.length >= minWordLength && !stopWords.has(w) && !/^\d+$/.test(w))
 
@@ -158,6 +160,7 @@ export function generateSearchIndex(pageEntries, outputDir, config) {
   // resolve, not join: outputDir may be absolute (join would mangle it,
   // e.g. cross-drive temp dirs on Windows)
   const outputPath = path.resolve(process.cwd(), outputDir, config.output)
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true })
   fs.writeFileSync(outputPath, JSON.stringify(entries, null, 2))
   log({ tag: 'indexer', text: 'Generated search index:', link: path.relative(process.cwd(), outputPath), size: fileSize(outputPath) })
 }
@@ -188,6 +191,7 @@ export function generateSitemap(pageEntries, outputDir, siteUrl, config) {
   // resolve, not join: outputDir may be absolute (join would mangle it,
   // e.g. cross-drive temp dirs on Windows)
   const outputPath = path.resolve(process.cwd(), outputDir, config.output)
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true })
   fs.writeFileSync(outputPath, xml)
   log({ tag: 'indexer', text: 'Generated sitemap:', link: path.relative(process.cwd(), outputPath), size: fileSize(outputPath) })
 }
@@ -369,6 +373,7 @@ export function generateRobotsTxt(outputDir, siteUrl, config, sitemapOutput) {
   if (sitemapUrl) lines.push('', `Sitemap: ${sitemapUrl}`)
 
   const outputPath = path.resolve(process.cwd(), outputDir, config.output)
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true })
   fs.writeFileSync(outputPath, lines.join('\n') + '\n')
   log({ tag: 'indexer', text: 'Generated robots.txt:', link: path.relative(process.cwd(), outputPath), size: fileSize(outputPath) })
 }
@@ -512,6 +517,7 @@ export function generateNav(pageEntries, outputDir, config) {
   // resolve, not join: outputDir may be absolute (join would mangle it,
   // e.g. cross-drive temp dirs on Windows)
   const outputPath = path.resolve(process.cwd(), outputDir, config.output)
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true })
   fs.writeFileSync(outputPath, JSON.stringify(tree, null, 2))
   log({ tag: 'indexer', text: 'Generated nav:', link: path.relative(process.cwd(), outputPath), size: fileSize(outputPath) })
 }

package/lib/markups.js

@@ -144,13 +144,19 @@ export default class Markups {
 
     const loadedKeys = new Set()
     for (const dataFile of resolved) {
+      const globalKeyName = path.basename(dataFile, path.extname(dataFile)).replace(/[.\-\s]/g, '_')
+      // Two data files with the same basename collide on one global (last wins) —
+      // warn, since it's silent data loss otherwise.
+      if (loadedKeys.has(globalKeyName)) {
+        log({ tag: 'markup', warn: true, text: `Data file overrides global "${globalKeyName}" (duplicate basename):`, link: dataFile })
+      }
       try {
         const data = readDataFile(path.resolve(process.cwd(), dataDir, dataFile))
-        const globalKeyName = path.basename(dataFile, path.extname(dataFile)).replace(/[.\-\s]/g, '_')
         this.engine.setGlobal(globalKeyName, data)
         loadedKeys.add(globalKeyName)
       } catch (err) {
-        log({ tag: 'error', text: 'Data file not found:', link: dataFile })
+        // Covers both a missing file and a parse error — surface which.
+        log({ tag: 'error', text: `Failed loading data file (${err.message}):`, link: dataFile })
         continue
       }
     }
@@ -347,7 +353,12 @@ export default class Markups {
       relativePathPrefix: getRelativePathPrefix(markupOutDir, fromPath, this.baseURL),
       // output-relative so page.url matches nav.json urls (getPageUrlRelativeToOutput),
       // otherwise `item.url == page.url` sidebar/active checks never fire
-      _url: getPageUrlRelativeToOutput(markupOut, this.markupOut)
+      _url: getPageUrlRelativeToOutput(markupOut, this.markupOut),
+      // source path relative to cwd/repo-root (posix), matching collection items'
+      // filePath, so templates can build "edit on GitHub" links as
+      // repoUrl + /edit/<branch>/ + filePath. .html output can't be reversed to
+      // the .md source reliably; cwd is the repo root
+      _page: { filePath: toPosix(path.relative(process.cwd(), path.resolve(file))) }
     }
 
     const shouldIndex = pageEntries && this.engine.indexableExtensions.has(path.extname(file))

package/lib/server.js

@@ -0,0 +1,146 @@
+/* Minimal static file server replacing connect + serve-static.
+   Supports single-range requests (in-browser video seeking, Safari playback).
+   ponytail: no ETag/Cache-Control — dev server wants fresh responses, not 304s. */
+import fs from 'node:fs'
+import path from 'node:path'
+import { pathExists } from './utils/helpers.js'
+
+const MIME_TYPES = {
+  '.html': 'text/html; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.map': 'application/json; charset=utf-8',
+  '.xml': 'application/xml; charset=utf-8',
+  '.txt': 'text/plain; charset=utf-8',
+  '.md': 'text/markdown; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.avif': 'image/avif',
+  '.ico': 'image/x-icon',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf',
+  '.otf': 'font/otf',
+  '.mp4': 'video/mp4',
+  '.webm': 'video/webm',
+  '.mp3': 'audio/mpeg',
+  '.wav': 'audio/wav',
+  '.ogg': 'audio/ogg',
+  '.pdf': 'application/pdf',
+  '.wasm': 'application/wasm',
+  '.webmanifest': 'application/manifest+json; charset=utf-8'
+}
+
+// Parse a single-range `Range: bytes=start-end` header against a file size.
+// Returns { start, end } (inclusive), null when absent/ignorable (multipart,
+// malformed — RFC says serve the full file then), or 'unsatisfiable' for a
+// well-formed range outside the file (→ 416).
+export function parseRange(header, size) {
+  if (!header) return null
+  const match = /^bytes=(\d*)-(\d*)$/.exec(header.trim())
+  if (!match || (match[1] === '' && match[2] === '')) return null
+
+  let start, end
+  if (match[1] === '') {
+    // Suffix range: last N bytes
+    const suffix = parseInt(match[2])
+    if (suffix === 0) return 'unsatisfiable'
+    start = Math.max(size - suffix, 0)
+    end = size - 1
+  } else {
+    start = parseInt(match[1])
+    end = match[2] === '' ? size - 1 : Math.min(parseInt(match[2]), size - 1)
+  }
+
+  if (start >= size || start > end) return 'unsatisfiable'
+  return { start, end }
+}
+
+export function createStaticHandler(base) {
+  const notFoundPage = path.join(base, '404.html')
+
+  const notFound = (res) => {
+    res.statusCode = 404
+    if (pathExists(notFoundPage)) {
+      res.setHeader('Content-Type', 'text/html; charset=utf-8')
+      fs.createReadStream(notFoundPage).on('error', () => res.destroy()).pipe(res)
+    } else {
+      res.end('Not Found')
+    }
+  }
+
+  return (req, res) => {
+    if (req.method !== 'GET' && req.method !== 'HEAD') {
+      res.statusCode = 405
+      res.setHeader('Allow', 'GET, HEAD')
+      return res.end('Method Not Allowed')
+    }
+
+    let url, pathname
+    try {
+      url = new URL(req.url, 'http://localhost')
+      pathname = decodeURIComponent(url.pathname)
+    } catch {
+      res.statusCode = 400
+      return res.end('Bad Request')
+    }
+
+    // Contain resolution inside `base` — rejects `..` traversal and null bytes
+    if (pathname.includes('\0')) return notFound(res)
+    let filePath = path.normalize(path.join(base, pathname))
+    if (filePath !== base && !filePath.startsWith(base + path.sep)) return notFound(res)
+
+    let stat
+    try {
+      stat = fs.statSync(filePath)
+    } catch {
+      return notFound(res)
+    }
+
+    if (stat.isDirectory()) {
+      // Redirect /dir → /dir/ so the page's relative URLs resolve correctly
+      if (!pathname.endsWith('/')) {
+        res.statusCode = 301
+        res.setHeader('Location', encodeURI(pathname) + '/' + url.search)
+        return res.end()
+      }
+      filePath = path.join(filePath, 'index.html')
+      try {
+        stat = fs.statSync(filePath)
+      } catch {
+        return notFound(res)
+      }
+    }
+
+    res.setHeader('Content-Type', MIME_TYPES[path.extname(filePath).toLowerCase()] || 'application/octet-stream')
+    res.setHeader('Accept-Ranges', 'bytes')
+
+    const range = parseRange(req.headers.range, stat.size)
+    if (range === 'unsatisfiable') {
+      res.statusCode = 416
+      res.setHeader('Content-Range', `bytes */${stat.size}`)
+      return res.end()
+    }
+
+    const streamOpts = {}
+    if (range) {
+      res.statusCode = 206
+      res.setHeader('Content-Range', `bytes ${range.start}-${range.end}/${stat.size}`)
+      res.setHeader('Content-Length', range.end - range.start + 1)
+      streamOpts.start = range.start
+      streamOpts.end = range.end
+    } else {
+      res.statusCode = 200
+      res.setHeader('Content-Length', stat.size)
+    }
+
+    if (req.method === 'HEAD') return res.end()
+    fs.createReadStream(filePath, streamOpts).on('error', () => res.destroy()).pipe(res)
+  }
+}

package/lib/utils/helpers.js

@@ -165,6 +165,22 @@ export function stripDirNavSegments(filePath) {
   return toPosix(path.normalize(filePath)).replace(/(\.\.\/|\.\/|\/\.\.|\.\.\\|\.\\|\\\.\.)/g, '')
 }
 
+// Index in filePath's segment list where `segParts` first appears as a
+// contiguous run, or -1. Segment-boundary matching: `src` matches `src/app.js`
+// and `x/src/y` but never `mysrc/app.js` or `dist/src-maps/x` — a plain
+// substring test would false-positive on all three.
+function findSegmentRun(fileParts, segParts) {
+  if (segParts.length === 0) return -1
+  for (let i = 0; i + segParts.length <= fileParts.length; i++) {
+    let match = true
+    for (let j = 0; j < segParts.length; j++) {
+      if (fileParts[i + j] !== segParts[j]) { match = false; break }
+    }
+    if (match) return i
+  }
+  return -1
+}
+
 export function pathContainsPathSegment(filePath, segment) {
   // Watcher paths arrive with native separators, config segments with `/`
   filePath = toPosix(filePath)
@@ -173,9 +189,23 @@ export function pathContainsPathSegment(filePath, segment) {
     segment = convertGlobToRegex(segment)
     if (!segment) return false
     return segment.test(filePath)
-  } else {
-    return filePath.includes(segment)
   }
+  const segParts = segment.split('/').filter(Boolean)
+  return findSegmentRun(filePath.split('/').filter(Boolean), segParts) !== -1
+}
+
+// Swaps the first segment-boundary occurrence of `from` in `filePath` for
+// `to`, both posix. Segment-aware so `src`→`dist` on `mysrc/src/x` rewrites the
+// real `src` segment, not the substring inside `mysrc` (what String.replace would hit).
+export function replacePathSegment(filePath, from, to) {
+  const fileParts = toPosix(filePath).split('/')
+  const nonEmpty = fileParts.filter(Boolean)
+  const offset = fileParts.length - nonEmpty.length // leading '' from an absolute path
+  const fromParts = toPosix(from).split('/').filter(Boolean)
+  const at = findSegmentRun(nonEmpty, fromParts)
+  if (at === -1) return toPosix(filePath)
+  const i = at + offset
+  return [...fileParts.slice(0, i), to, ...fileParts.slice(i + fromParts.length)].join('/')
 }
 
 export function doesFileBelongToPath(filePath, configPaths) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "poops",
   "description": "Straightforward, no-bullshit bundler for the web.",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "license": "MIT",
   "type": "module",
   "main": "poops.js",
@@ -48,13 +48,15 @@
   "scripts": {
     "build": "node ./poops.js -b",
     "lint": "eslint .",
-    "test": "NODE_OPTIONS='--experimental-vm-modules' jest"
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js"
+  },
+  "engines": {
+    "node": ">=20"
   },
   "dependencies": {
     "argoyle": "^1.0.0",
     "book-of-spells": "^1.3.0",
     "chokidar": "^3.5.3",
-    "connect": "^3.7.0",
     "dayjs": "^1.11.19",
     "esbuild": "^0.25.0",
     "glob": "^13.0.6",
@@ -66,12 +68,10 @@
     "marked-github-emoji": "^1.0.2",
     "marked-github-footnote": "^1.0.0",
     "nunjucks": "^3.2.4",
-    "portscanner": "^2.2.0",
     "printstyle": "^1.0.0",
     "sass": "^1.63.4",
     "sass-path-resolver": "^1.0.2",
     "sass-token-importer": "^1.0.0",
-    "serve-static": "^1.15.0",
     "yaml": "^2.3.1"
   },
   "devDependencies": {

package/poops.js

@@ -1,25 +1,24 @@
 #!/usr/bin/env node
 
 import chokidar from 'chokidar'
-import connect from 'connect'
 import Copy from './lib/copy.js'
 import runExec, { validateExec } from './lib/exec.js'
-import { pathExists, doesFileBelongToPath, pathContainsPathSegment, deriveWatchDirs } from './lib/utils/helpers.js'
+import { pathExists, doesFileBelongToPath, pathContainsPathSegment, deriveWatchDirs, toPosix } from './lib/utils/helpers.js'
 import http from 'node:http'
+import net from 'node:net'
 import os from 'node:os'
 import fs from 'node:fs'
 import livereload from 'livereload'
 import Markups from './lib/markups.js'
 import Images from './lib/images.js'
 import path from 'node:path'
-import serveStatic from 'serve-static'
 import Reactor from './lib/reactor.js'
+import { createStaticHandler } from './lib/server.js'
 import Scripts from './lib/scripts.js'
 import log, { styledLog, hasLoggedErrors } from './lib/utils/log.js'
 import Styles from './lib/styles.js'
 import PostCSS from './lib/postcss.js'
 import Argoyle from 'argoyle'
-import portscanner from 'portscanner'
 
 const cwd = process.cwd() // Current Working Directory
 const pkg = JSON.parse(fs.readFileSync(new URL('./package.json', import.meta.url), 'utf-8'))
@@ -47,7 +46,7 @@ const overrideLivereloadPort = flags['livereload-port']
 const overrideBaseURL = flags['base-url']
 
 let configPath = path.join(cwd, defaultConfigPath)
-if (!pathExists(configPath)) configPath = path.join(cwd, '💩.json') // TODO: Ok dude, I know it's late, but you can do better than this.
+if (!pathExists(configPath)) configPath = path.join(cwd, '💩.json') // the canonical alternative config name
 
 async function resolveLiveReloadPort(config) {
   if (!config.livereload) return null
@@ -91,10 +90,12 @@ function reload(file) {
 // The css output paths of the styles entries — what the styles chain reports
 // to reload() so style edits hot-swap. A directory `out` maps to the entry
 // point's basename, mirroring how the styles compiler names its output file.
+// toPosix: the livereload client matches these against URL paths, so Windows
+// backslashes would silently break the CSS hot-swap.
 function styleOutputs(config) {
   return [config.styles].flat()
     .filter((entry) => entry && entry.in && entry.out)
-    .map((entry) => (path.extname(entry.out)
+    .map((entry) => toPosix(path.extname(entry.out)
       ? entry.out
       : path.join(entry.out, path.basename(entry.in).replace(/\.(sass|scss)$/i, '.css'))))
 }
@@ -126,6 +127,10 @@ function setupWatchers(config, modules) {
   // compiler, or watch loops forever. Zones are the dirs the compilers write
   // into; only their own extensions are skipped there, so e.g. a hand-edited
   // .liquid asset in the same dir still rebuilds markup.
+  // markup/images outs are deliberately NOT zoned: markup sources legitimately
+  // live beside markup output (Shopify theme dirs), so zoning them would stop
+  // hand-edits from rebuilding. Constraint: keep markup.out/images.out outside
+  // the watch list, or every compile retriggers itself.
   const outputZones = [config.scripts, config.styles].flat()
     .filter((entry) => entry && entry.out)
     .map((entry) => (path.extname(entry.out) ? path.dirname(entry.out) : entry.out))
@@ -230,6 +235,10 @@ function setupWatchers(config, modules) {
 
   chokidar.watch(config.watch, {
     ignoreInitial: true,
+    // Reactor's temp wrapper/bundle files are written next to the component
+    // source (a watched dir) — without this they'd retrigger the script/
+    // reactor rebuild that created them, looping the watcher.
+    ignored: /\.reactor-(tmp|bundle)-/,
     awaitWriteFinish: { stabilityThreshold: 150, pollInterval: 50 }
   }).on('change', compileChanged)
     .on('add', (file) => {
@@ -302,6 +311,17 @@ if (!pathExists(configPath)) {
 // Load poops.json
 const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'))
 
+// A typo'd top-level key ("stlyes") is otherwise silently ignored — warn, same
+// idea as validateExec for exec stages. `ssg` is the reactor alias; `pkg` feeds
+// banner templates; livereload_port/reactorData are set internally but tolerated
+// here in case a config hardcodes them.
+const KNOWN_CONFIG_KEYS = new Set(['watch', 'includePaths', 'scripts', 'styles', 'postcss', 'reactor', 'ssg', 'markup', 'copy', 'images', 'serve', 'livereload', 'exec', 'banner', 'pkg', 'livereload_port', 'reactorData'])
+for (const key of Object.keys(config)) {
+  if (!KNOWN_CONFIG_KEYS.has(key)) {
+    log({ tag: 'info', warn: true, text: `Unknown config key "${key}" — ignored. Valid: ${[...KNOWN_CONFIG_KEYS].join(', ')}` })
+  }
+}
+
 if (config.watch === true) {
   config.watch = deriveWatchDirs(config)
 } else if (config.watch) {
@@ -329,16 +349,23 @@ if (config.images && typeof config.images === 'object' && config.images.configDi
   config.images.configDir = path.dirname(configPath)
 }
 
+// Bind probe on 0.0.0.0 — the same interface the servers listen on, so a
+// "free" answer here can't be beaten to the port by a localhost-only check.
+function isPortFree(port) {
+  return new Promise((resolve) => {
+    const probe = net.createServer()
+    probe.once('error', () => resolve(false))
+    probe.once('listening', () => probe.close(() => resolve(true)))
+    probe.listen(port, '0.0.0.0')
+  })
+}
+
 async function getAvailablePort(port, max) {
-  while (port < max) {
-    const status = await portscanner.checkPortStatus(port, 'localhost')
-    if (status === 'closed') {
-      return port
-    } else {
-      port++
-    }
+  for (; port <= max; port++) {
+    if (await isPortFree(port)) return port
   }
-  return port
+  log({ tag: 'error', text: `No free port found in range ${max - 10}-${max}.` })
+  process.exit(1)
 }
 
 function getLocalIP() {
@@ -354,30 +381,16 @@ function getLocalIP() {
 async function startServer() {
   await resolveLiveReloadPort(config)
   await poops() // Initial compilation before starting the server
-  const app = connect()
 
   const base = config.serve.base && pathExists(cwd, config.serve.base)
     ? path.join(cwd, config.serve.base)
     : cwd
 
-  app.use(serveStatic(base))
-
-  // Serve 404.html for unmatched routes
-  const notFoundPage = path.join(base, '404.html')
-  app.use((req, res) => {
-    res.statusCode = 404
-    if (pathExists(notFoundPage)) {
-      fs.createReadStream(notFoundPage).pipe(res)
-    } else {
-      res.end('Not Found')
-    }
-  })
-
   let port = overridePort || config.serve.port || 4040
   if (!overridePort) port = await getAvailablePort(port, port + 10)
 
   // eslint-disable-next-line @stylistic/space-before-function-paren
-  http.createServer(app).listen(parseInt(port), '0.0.0.0', async () => {
+  http.createServer(createStaticHandler(base)).listen(parseInt(port), '0.0.0.0', async () => {
     console.log()
     styledLog(`🏠 {dim}Local server:{/} {underline|http://localhost:${port}}`)
     styledLog(`🛜 {dim} Network     :{/} {underline|http://${getLocalIP()}:${port}}`)
@@ -385,14 +398,22 @@ async function startServer() {
   })
 }
 
+// A rejection here is a startup failure (port scan, initial compile) — exit
+// loudly instead of dying as an unhandled rejection.
+const die = (err) => {
+  console.error(err)
+  process.exit(1)
+}
+
 // Start the webserver
 if (!build && config.serve) {
-  startServer()
+  startServer().catch(die)
 } else if (!build && config.livereload) {
   // livereload without serve: still needs the livereload server
   resolveLiveReloadPort(config)
     .then(poops)
     .then(() => setupLiveReloadServer(config))
+    .catch(die)
 } else {
-  poops()
+  poops().catch(die)
 }