@johnhenry/letterpress 0.0.0 → 0.0.1

package/.github/workflows/ci.yml

@@ -7,17 +7,8 @@ on:
 
 jobs:
   test:
-    strategy:
-      fail-fast: false
-      matrix:
-        # engines.node >=26.0.0 -- test the floor version directly rather
-        # than a matrix of now-unsupported older majors.
-        node-version: [26]
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: ${{ matrix.node-version }}
-      - run: npm ci
-      - run: npm test
+    uses: johnhenry/workflows/.github/workflows/ci.yml@v1
+    with:
+      node-versions: '["26"]'
+      os: '["ubuntu-latest"]'
+      gate-commands: npm test

package/.github/workflows/publish.yml

@@ -3,36 +3,25 @@ name: Publish to npm
 on:
   release:
     types: [published]
+  push:
+    # Redundant with the release trigger above -- see fileable's
+    # publish.yml / johnhenry/workflows' README for the full incident
+    # writeup: creating a release very soon after a push/merge to the
+    # same commit can silently drop the release event for a job whose
+    # body is uses: <external-repo>/...@v1. This gives a second,
+    # idempotency-safe chance to fire.
+    tags:
+      - "v*"
   workflow_dispatch: {}
 
 jobs:
   publish:
-    runs-on: ubuntu-latest
     permissions:
       contents: read
-      id-token: write # npm provenance
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '26'
-          registry-url: 'https://registry.npmjs.org'
-
-      - run: npm ci
-
-      - run: npm test
-
-      - name: Publish
-        # Idempotent: `npm view` exits non-zero for a version that isn't on
-        # the registry yet, which is the signal to publish.
-        run: |
-          PKG_NAME=$(node -p "require('./package.json').name")
-          PKG_VERSION=$(node -p "require('./package.json').version")
-          if npm view "$PKG_NAME@$PKG_VERSION" version >/dev/null 2>&1; then
-            echo "::notice title=Already published::$PKG_NAME@$PKG_VERSION is already on npm; nothing to do."
-            exit 0
-          fi
-          npm publish --access public
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+      id-token: write # required by the reusable workflow's provenance step --
+        # see johnhenry/workflows' README for why this must be declared here too.
+    uses: johnhenry/workflows/.github/workflows/npm-publish.yml@v1
+    with:
+      node-version: "26"
+      gate-commands: npm test
+    secrets: inherit

package/AGENTS.md

@@ -0,0 +1,65 @@
+# Agent playbook
+
+`@johnhenry/letterpress` -- a tagged-template-string HTTP routing library:
+defining and matching request handlers with plain JavaScript syntax. Single
+package, Node >= 26, `node:test` (`npm test` runs `test/index.mjs`), ships
+source directly (`index.mjs` + friends); no build step.
+
+`CLAUDE.md` in this directory is a symlink to this file.
+
+## The verification loop (before every push)
+
+1. `npm test` -- runs `node --test test/index.mjs`, which must itself
+   import every test module (see gotcha below -- this has silently dropped
+   whole suites before).
+2. A genuinely fresh clone:
+   `git clone . /tmp/letterpress-verifyN && cd $_ && npm ci && npm test`.
+   This is the only way to catch "works on my checked-out tree" bugs
+   (missing `files` entries, undeclared deps).
+3. Commit, push, close the issue with a comment naming the commit SHA.
+
+CI (`.github/workflows/ci.yml`) runs the same `npm test` command; match it
+locally.
+
+## Repo-specific gotchas
+
+- **`test/index.mjs` is a hand-maintained list of test-file imports, not a
+  glob.** A past bug imported one file twice and never imported the other,
+  silently dropping an entire suite from `npm test` with a passing exit
+  code. When you add a new `test/*.mjs` file, add its import to
+  `test/index.mjs` and verify the new suite's assertions actually ran (not
+  just that `npm test` exited 0).
+- **`createRoute` substitutions are not escaped.** See
+  `## Honest limitations` in the README before treating unescaped HTML
+  output as a bug to silently "fix" with auto-escaping -- that would be a
+  breaking behavior change, not a bugfix, and needs its own CHANGELOG entry
+  and version bump if done.
+- **`createRouter`'s dispatch loop must `await` the handler.** A past bug
+  called `handler(request, ctx)` without awaiting it, so an async handler
+  that threw crashed as an unhandled rejection instead of being caught by
+  `errorHandler`/`defaultHandler`. Any new dispatch path must await.
+- **`fs-router.mjs`'s synthesized `index.html` temp module is written next
+  to the matched route's own directory, not into `letterpress`'s installed
+  package directory.** A past bug wrote it into the package dir, which
+  broke the whole feature under any read-only install (containers,
+  CI-built images). Keep new temp-file writes scoped to the route
+  directory, and don't `unlink` a temp file when the write that created it
+  already failed (that masks the real error as a misleading `ENOENT`).
+
+## Definition of done
+
+A change is done when all of the following hold, not just when tests pass:
+- A regression test exists for any bug fixed, and is actually wired into
+  `test/index.mjs` (see gotcha above).
+- Anything the feature does **not** do is stated in the README's
+  `## Honest limitations` section, not only in an issue comment.
+- `CHANGELOG.md` has an entry.
+- `api.md` is re-checked against the real exports if the change touches
+  public API shape.
+
+## Releases
+
+Bump `version` in `package.json` in a PR, add the `CHANGELOG.md` entry,
+merge, then `gh release create v<version>` -- the release event triggers
+`.github/workflows/publish.yml`, which is idempotent (skips if the version
+is already on npm).

package/API.md

@@ -1,4 +1,4 @@
-# Route API Documentation
+# Letterpress API Documentation
 
 ## Table of Contents
 
@@ -98,7 +98,7 @@ Content-Type: application/json
 
 ## Utility Functions
 
-Route provides several utility functions to help with request and response handling:
+Letterpress provides several utility functions to help with request and response handling:
 
 > Note: `@johnhenry/letterpress` does not export a `serve` function or a `tagRequest` function. To run a server, pair it with [leserve](https://www.npmjs.com/package/@johnhenry/leserve) (imported directly, e.g. `import serve from "@johnhenry/leserve"`) or any server of your choice. To build a `Request` from a template literal, use `createRequest` (see below).
 
@@ -171,4 +171,4 @@ const message = cook`GET /api/users/${123} HTTP/1.1`;
 // "GET /api/users/123 HTTP/1.1"
 ```
 
-This API documentation provides an overview of the main functions and utilities provided by the Route library. For more detailed information on specific use cases and advanced features, please refer to the README.md and the source code.
+This API documentation provides an overview of the main functions and utilities provided by the Letterpress library. For more detailed information on specific use cases and advanced features, please refer to the README.md and the source code.

package/CHANGELOG.md

@@ -0,0 +1,108 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
+
+This project will adhere to [Semantic Versioning](https://semver.org/spec/v2.0.0.html) once it reaches 1.0.0.
+
+## [0.0.1] - 2026-09-26
+
+### Fixed
+
+- 🐛 **Security/reliability**: The colon-form header matcher documented in
+  the README (`` router.endpoint`GET /protected [Authorization: Bearer *]` ``)
+  parsed the `:` and everything up to the wildcard as part of the header
+  *name* instead of stopping the name at `:`, so `headers.get()` threw
+  `TypeError: invalid header name`. Because `createRouter`'s dispatch loop
+  calls matchers inside a top-level try/catch, this 500'd **every** request
+  routed through a router with such a route registered — not just requests
+  matching that path — for any consumer who followed the README's own
+  documented syntax. `parseHeaderMatcher`'s header-name capture now stops at
+  `:` (in addition to the existing operator characters), and the value
+  after the colon is treated as a wildcard-match pattern (`*` matches any
+  run of characters), so `[Authorization: Bearer *]` matches any bearer
+  token instead of crashing. The operator-form equivalent,
+  `[Authorization^=Bearer]`, is unaffected and continues to work
+  ([#4](https://github.com/johnhenry/letterpress/issues/4))
+- 🐛 **Bundling**: The main barrel (`index.mjs`) re-exported `createFSRouter`
+  from `fs-router.mjs`, which imports `node:fs`, `node:path`, and
+  `theres-waldo` (itself using `node:url`'s `fileURLToPath`) at module top
+  level. Those imports run at *import* time, so simply importing anything
+  from `@johnhenry/letterpress` — even `HTTPExpression` or `createRoute`,
+  which have nothing to do with the filesystem router — pulled in
+  Node-only code and broke browser bundlers (e.g. Vite), even when the
+  Node builtins were shimmed, because the fs-router module body still ran.
+  `createFSRouter` is no longer re-exported from the main barrel; it's now
+  reachable via a dedicated `@johnhenry/letterpress/fs` subpath (added to a
+  new `package.json` `"exports"` map, alongside a `"./*"` wildcard so
+  existing deep-path imports like
+  `@johnhenry/letterpress/utility/http-expression.mjs` keep working
+  unchanged). Everything else in the barrel (`createRouter`, `createRoute`,
+  `createRequest`, `createResponse`, `HTTPExpression`) was already pure and
+  is now verified to bundle cleanly for the browser
+  ([#6](https://github.com/johnhenry/letterpress/issues/6))
+
+### Changed (breaking)
+
+- **`createFSRouter` is no longer exported from the main `@johnhenry/letterpress`
+  barrel.** Import it from `@johnhenry/letterpress/fs` instead. This is the
+  only export affected; everything else's import path is unchanged.
+
+## [0.0.0] - npm scope migration - 2026-09-19
+
+### Changed (breaking)
+
+- **Renamed the package from `leroute` to `@johnhenry/letterpress`**, and
+  restarted the version at `0.0.0` (previously published as `leroute`, last
+  unscoped version `0.0.1`).
+- **Renamed the exported identifiers to match**: `createLeRoute` →
+  `createRoute`, `createLeRouter` → `createRouter`, `LeRoute` → `Route`,
+  `LeRouteInit` → `RouteInit`, `LeRouteMiddleware` → `RouteMiddleware`,
+  `LeRouter` → `Router`, `LeRouterExtension` → `RouterExtension`,
+  `LeRouterInit` → `RouterInit`, `LeRouterMiddleware` → `RouterMiddleware`.
+  `create-leroute.mjs`/`create-lerouter.mjs` were also renamed to
+  `create-route.mjs`/`create-router.mjs` (and their test files
+  correspondingly), matching the new export names.
+- **Raised `engines.node` to `>=26.0.0`**, matching the rest of the
+  `@johnhenry/*` family's floor.
+
+### Fixed
+
+- 🐛 `test/index.mjs` imported `lerouter.mjs` twice and never imported `leroute.mjs`, silently dropping the `createRoute` test suite from `npm test`
+- 🐛 `test/leroute.mjs` imported `createRoute` from `create-router.mjs` (which doesn't export it) instead of `create-route.mjs`, which would have thrown once the missing import above was fixed
+- 🐛 `package.json` declared `"license": "ISC"` while the `LICENSE` file and README badge are MIT; changed to `"license": "MIT"` to match
+- 📝 README and API docs referenced `serve` and `tagRequest` as exports of `leroute`; neither is exported — `serve` comes from the separate `leserve` package, and `tagRequest` doesn't exist. Docs corrected to list the real exports
+- 📝 API docs showed `HTTPExpression(...)` as a constructor with `.method`/`.path`/`.version` properties; corrected to show it as a tagged-template function returning `{ test(request), exec(request) }`
+- 🔒 **Security**: `router.endpoint` reused the per-request context object (which carries the incoming request's `Headers`) as the response-init object passed to `createRoute`, so every incoming request header — `Authorization`, `Cookie`, arbitrary custom headers — was echoed back on every response
+- 🐛 `createRouter`'s dispatch loop called `handler(request, ctx)` without `await`, so an async handler that threw was never caught by the configured `errorHandler`/`defaultHandler` and instead crashed as an unhandled rejection
+- 🐛 `createRoute` threw `Cannot read properties of null/undefined (reading 'toString')` on a `${null}`/`${undefined}` substitution instead of rendering nothing (ordinary template-literal semantics), even though a substitution *function* returning `undefined` was already treated as "no output"
+- 🐛 A substitution *function* returning a `ReadableStream`/`Blob`/`ArrayBuffer`/`Uint8Array` fell through to `.toString()`, producing the literal string `"[object ReadableStream]"` instead of streaming the actual content (direct substitutions of these types already worked correctly)
+- 🐛 `utility/dynamic-run.mjs` unconditionally attempted to `fs.unlink()` its temp file even when `fs.writeFile()` itself had failed, masking the real write error behind a misleading `ENOENT` — which `fs-router.mjs` then silently treated as "route not found" instead of surfacing a genuine permissions/disk-full failure. A cleanup (`unlink`) failure *after* a successful import also discarded the successful result
+- 🐛 `fs-router.mjs`'s `index.html` handling wrote its synthesized temp module into leroute's own installed package directory instead of the matched route's directory — breaking the feature entirely in any deployment where the package install directory is read-only (containers, CI-built images)
+
+### Added
+
+- `"types"` field in `package.json` pointing to the existing `types.d.ts`
+- A real `description` and `keywords` in `package.json` (previously empty)
+
+### Removed
+
+- Deleted `utility/cd.mjs`, an unused debug scratch file with no imports and no tests
+
+## 0.0.0 (as `Route`/`loute`, pre-rename) - 2024-08-26
+
+> Disambiguation: this is the *original* initial release, under an earlier
+> name and a separate version-number sequence (`phrouter` 1.0.0 -> `loute`
+> 0.0.0 -> `leroute` 0.0.0 -> `leroute` 0.0.1), predating the npm scope
+> migration entry above, which is also numbered `0.0.0` per family
+> convention (the version resets on scope import). These are two different
+> releases that happen to share a version number.
+
+### Added
+
+- 🎉 Initial release of Route
+- 🛠 Core routing functionality
+- 🛠 HTTP request and response handling
+- 🛠 TypeScript definitions
+- 🛠 Support for route parameters and query strings

package/{readme.md → README.md}

@@ -1,7 +1,10 @@
 # Letterpress
 
-[![npm version](https://badge.fury.io/js/%40johnhenry%2Fletterpress.svg)](https://www.npmjs.com/package/@johnhenry/letterpress)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![npm version](https://img.shields.io/npm/v/%40johnhenry%2Fletterpress.svg)](https://www.npmjs.com/package/@johnhenry/letterpress)
+[![CI](https://github.com/johnhenry/letterpress/actions/workflows/ci.yml/badge.svg)](https://github.com/johnhenry/letterpress/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/%40johnhenry%2Fletterpress.svg)](license)
+
+Full documentation: [opensource.johnhenry.me/letterpress](https://opensource.johnhenry.me/letterpress/)
 
 <img alt="Letterpress Logo" width="512" height="512" src="./logo.jpeg" style="width:512px;height:512px"/>
 
@@ -12,6 +15,18 @@ Letterpress is a flexible and powerful routing library for handling HTTP request
 
 Letterpress works great with [leserve](https://www.npmjs.com/package/@johnhenry/leserve), a library for serving endpoints.
 
+## Contents
+
+- [Features](#-features)
+- [Installation](#-installation)
+- [Usage](#-usage)
+- [API Reference](#-api-reference)
+- [Honest limitations](#honest-limitations)
+- [Changelog](#-changelog)
+- [Family](#family)
+- [Contributing](#-contributing)
+- [License](#-license)
+
 ## 🚀 Features
 
 - Intuitive API using tagged template strings for route creation
@@ -51,10 +66,10 @@ router.endpoint`GET /``
   <head>
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>Welcome to Route</title>
+    <title>Welcome to Letterpress</title>
   </head>
   <body>
-    <h1>Welcome to Route!</h1>
+    <h1>Welcome to Letterpress!</h1>
     <p>The current time is: ${() => new Date().toISOString()}</p>
   </body>
 </html>
@@ -164,74 +179,72 @@ Tagged-template functions for building `Request`/`Response` objects from raw HTT
 
 Builds a `Router` from a filesystem-based route directory.
 
+```javascript
+import { createFSRouter } from "@johnhenry/letterpress/fs";
+```
+
+> `createFSRouter` is imported from the `@johnhenry/letterpress/fs`
+> subpath, not the main `@johnhenry/letterpress` barrel. It's the only
+> piece of Letterpress that touches Node built-ins (`node:fs`, `node:path`)
+> and the `theres-waldo` dependency, so it's kept out of the main entry
+> point to keep that entry point bundler-friendly for browser use. Everything
+> else (`createRouter`, `createRoute`, `createRequest`, `createResponse`,
+> `HTTPExpression`) is pure and safe to bundle for the browser.
+
 ### `deconstruct`, `cook`
 
 Lower-level utility functions used to parse and process tagged HTTP template literals. See [api.md](./api.md) for details.
 
 > Note: `@johnhenry/letterpress` does not export a `serve` function. To actually run a server, pair it with [leserve](https://www.npmjs.com/package/@johnhenry/leserve) (or any server of your choice) as shown in the usage examples above.
 
-## 📜 Changelog
-
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
+## Honest limitations
+
+- **`createRoute` template substitutions are not HTML-escaped.** A
+  substitution value is inserted via `.toString()` and spliced directly
+  into the response body; there is no auto-escaping step, even though the
+  default `Content-Type` is `text/html`. Interpolating untrusted input
+  (request params, headers, query values) directly into an
+  `` router.endpoint`GET /...`` `` HTML template -- e.g.
+  `` `<p>${(_, {params}) => params.id}</p>` `` -- reflects that value
+  byte-for-byte into the response. Escape anything derived from the request
+  yourself (e.g. a small HTML-escaping helper) before interpolating it, the
+  same way you would with any other unescaped template-literal HTML
+  response.
+- **`createFSRouter`'s `index.html` handling evaluates the file as live
+  JavaScript, not literal text.** To reuse `createRoute`'s own template
+  engine for static `index.html` files, `fs-router.mjs` reads the file's
+  raw content and splices it directly into a synthesized module string as
+  a template literal (`` export default createRoute()`${file}` ``), then
+  dynamically imports and runs that module. Any literal backtick or
+  `${...}` sequence inside that `index.html` file is interpreted as real
+  JavaScript in the synthesized module's scope, not rendered as text. This
+  is fine for trusted, hand-authored `index.html` files (the intended use),
+  but `index.html` files under a filesystem route tree should be treated as
+  code, not as passive markup, if their contents are ever user-editable.
 
-This project will adhere to [Semantic Versioning](https://semver.org/spec/v2.0.0.html) once it reaches 1.0.0.
-
-### [Unreleased]
-
-#### Changed (breaking)
-
-- **Renamed the package from `leroute` to `@johnhenry/letterpress`**, and
-  restarted the version at `0.0.0` (previously published as `leroute`, last
-  unscoped version `0.0.1`).
-- **Renamed the exported identifiers to match**: `createLeRoute` →
-  `createRoute`, `createLeRouter` → `createRouter`, `LeRoute` → `Route`,
-  `LeRouteInit` → `RouteInit`, `LeRouteMiddleware` → `RouteMiddleware`,
-  `LeRouter` → `Router`, `LeRouterExtension` → `RouterExtension`,
-  `LeRouterInit` → `RouterInit`, `LeRouterMiddleware` → `RouterMiddleware`.
-  `create-leroute.mjs`/`create-lerouter.mjs` were also renamed to
-  `create-route.mjs`/`create-router.mjs` (and their test files
-  correspondingly), matching the new export names.
-- **Raised `engines.node` to `>=26.0.0`**, matching the rest of the
-  `@johnhenry/*` family's floor.
-
-#### Fixed
-
-- 🐛 `test/index.mjs` imported `lerouter.mjs` twice and never imported `leroute.mjs`, silently dropping the `createRoute` test suite from `npm test`
-- 🐛 `test/leroute.mjs` imported `createRoute` from `create-router.mjs` (which doesn't export it) instead of `create-route.mjs`, which would have thrown once the missing import above was fixed
-- 🐛 `package.json` declared `"license": "ISC"` while the `LICENSE` file and README badge are MIT; changed to `"license": "MIT"` to match
-- 📝 README and API docs referenced `serve` and `tagRequest` as exports of `leroute`; neither is exported — `serve` comes from the separate `leserve` package, and `tagRequest` doesn't exist. Docs corrected to list the real exports
-- 📝 API docs showed `HTTPExpression(...)` as a constructor with `.method`/`.path`/`.version` properties; corrected to show it as a tagged-template function returning `{ test(request), exec(request) }`
-- 🔒 **Security**: `router.endpoint` reused the per-request context object (which carries the incoming request's `Headers`) as the response-init object passed to `createRoute`, so every incoming request header — `Authorization`, `Cookie`, arbitrary custom headers — was echoed back on every response
-- 🐛 `createRouter`'s dispatch loop called `handler(request, ctx)` without `await`, so an async handler that threw was never caught by the configured `errorHandler`/`defaultHandler` and instead crashed as an unhandled rejection
-- 🐛 `createRoute` threw `Cannot read properties of null/undefined (reading 'toString')` on a `${null}`/`${undefined}` substitution instead of rendering nothing (ordinary template-literal semantics), even though a substitution *function* returning `undefined` was already treated as "no output"
-- 🐛 A substitution *function* returning a `ReadableStream`/`Blob`/`ArrayBuffer`/`Uint8Array` fell through to `.toString()`, producing the literal string `"[object ReadableStream]"` instead of streaming the actual content (direct substitutions of these types already worked correctly)
-- 🐛 `utility/dynamic-run.mjs` unconditionally attempted to `fs.unlink()` its temp file even when `fs.writeFile()` itself had failed, masking the real write error behind a misleading `ENOENT` — which `fs-router.mjs` then silently treated as "route not found" instead of surfacing a genuine permissions/disk-full failure. A cleanup (`unlink`) failure *after* a successful import also discarded the successful result
-- 🐛 `fs-router.mjs`'s `index.html` handling wrote its synthesized temp module into leroute's own installed package directory instead of the matched route's directory — breaking the feature entirely in any deployment where the package install directory is read-only (containers, CI-built images)
-
-#### Added
-
-- `"types"` field in `package.json` pointing to the existing `types.d.ts`
-- A real `description` and `keywords` in `package.json` (previously empty)
-
-#### Removed
+## 📜 Changelog
 
-- Deleted `utility/cd.mjs`, an unused debug scratch file with no imports and no tests
+See [CHANGELOG.md](./CHANGELOG.md) for the full history of changes.
 
-### [0.0.0] - 2024-08-26
+## Family
 
-#### Added
+Letterpress isn't a standalone server -- it deliberately doesn't export a
+`serve` function (see the note at the end of the API Reference above), and
+is designed to pair with a sibling package that does.
 
-- 🎉 Initial release of Route
-- 🛠 Core routing functionality
-- 🛠 HTTP request and response handling
-- 🛠 TypeScript definitions
-- 🛠 Support for route parameters and query strings
+- **[`@johnhenry/leserve`](https://github.com/johnhenry/leserve)** -- a
+  library for serving endpoints. `createRouter()`'s output (a `Route`
+  function matching `(request, additionalContext) => Promise<Response>`) is
+  exactly the shape `leserve`'s `serve()` accepts as its handler, so pairing
+  the two needs no adapter -- `serve({ port }, router)`, as shown throughout
+  this README's usage examples. Any other server that can call a
+  `Route`-shaped function works too; `leserve` is the tested, documented
+  pairing, not a hard dependency (it's a `devDependency` here, used only in
+  the demo scripts).
 
 ## 🤝 Contributing
 
-We welcome contributions to Route! Here's how you can help:
+We welcome contributions to Letterpress! Here's how you can help:
 
 1. Fork the repository
 2. Create a new branch: `git checkout -b feature/your-feature-name`
@@ -247,7 +260,7 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 ## 🙏 Acknowledgements
 
-- Thanks to all contributors who have helped shape Route
+- Thanks to all contributors who have helped shape Letterpress
 - Inspired by modern web development practices and the need for flexible routing solutions
 
 ## 📬 Contact
@@ -256,4 +269,4 @@ For questions, suggestions, or issues, please open an issue on the GitHub reposi
 
 ---
 
-Happy routing with Route! 🚀
+Happy routing with Letterpress! 🚀

package/index.mjs

@@ -2,7 +2,17 @@ export { createRequest } from "./create-request.mjs";
 export { createRouter } from "./create-router.mjs";
 export { createRoute } from "./create-route.mjs";
 export { createResponse } from "./create-response.mjs";
-export { createFSRouter } from "./fs-router.mjs";
 export * from "./utility/index.mjs";
 export { deconstruct } from "./utility/deconstruct.mjs";
 export { cook } from "./utility/cook.mjs";
+
+// `createFSRouter` is intentionally NOT re-exported from this barrel.
+// fs-router.mjs imports `node:fs`, `node:path`, and `theres-waldo` (which
+// itself uses `fileURLToPath` from `node:url`) at module top level. Those
+// side effects run at *import* time, not call time, so merely having this
+// barrel import fs-router.mjs breaks browser bundlers (e.g. Vite) for every
+// consumer, even ones who never call createFSRouter -- and shimming
+// `node:fs`/`node:path` doesn't help, since the fs-router module body still
+// executes on import. Import createFSRouter from the dedicated Node-only
+// subpath instead:
+//   import { createFSRouter } from "@johnhenry/letterpress/fs";

package/package.json

@@ -1,9 +1,15 @@
 {
   "name": "@johnhenry/letterpress",
-  "version": "0.0.0",
+  "version": "0.0.1",
   "description": "A tagged-template-string HTTP routing library for defining and matching request handlers with plain JavaScript syntax.",
   "main": "index.mjs",
   "types": "types.d.ts",
+  "exports": {
+    ".": "./index.mjs",
+    "./fs": "./fs-router.mjs",
+    "./package.json": "./package.json",
+    "./*": "./*"
+  },
   "publishConfig": {
     "access": "public",
     "provenance": true

package/test/exports.mjs

@@ -0,0 +1,64 @@
+import { test } from "node:test";
+import assert from "node:assert";
+
+// Regression tests for https://github.com/johnhenry/letterpress/issues/6:
+// the main barrel used to re-export `createFSRouter` from `fs-router.mjs`,
+// which imports `node:fs`, `node:path`, and `theres-waldo` (which itself
+// uses `node:url`) at module top level. That broke browser bundlers (e.g.
+// Vite) for every consumer of the barrel, even ones who never touch
+// `createFSRouter`, because those Node-only imports run at *import* time.
+//
+// These tests lock in the shape the fix depends on: the pure/browser-safe
+// exports stay on the main barrel, `createFSRouter` moves to a dedicated
+// `./fs` subpath, and both resolve correctly via the package's own name
+// (self-reference), matching how an external consumer would import them.
+// The actual "does this bundle for the browser" claim is verified
+// separately with a real esbuild --platform=browser build (see PR
+// description) since node:test can't drive a bundler.
+
+test("Main barrel does not export createFSRouter", async () => {
+  const barrel = await import("../index.mjs");
+  assert.strictEqual(
+    "createFSRouter" in barrel,
+    false,
+    "createFSRouter should not be re-exported from the main barrel " +
+      "(it pulls in node:fs/node:path/theres-waldo at import time)"
+  );
+  // The rest of the barrel should still be there.
+  for (const name of [
+    "createRouter",
+    "createRoute",
+    "createRequest",
+    "createResponse",
+    "HTTPExpression",
+  ]) {
+    assert.strictEqual(
+      typeof barrel[name],
+      "function",
+      `expected barrel to still export ${name}`
+    );
+  }
+});
+
+test("createFSRouter is exported from fs-router.mjs directly", async () => {
+  const fsRouterModule = await import("../fs-router.mjs");
+  assert.strictEqual(typeof fsRouterModule.createFSRouter, "function");
+});
+
+test("package.json exposes a ./fs subpath export for createFSRouter", async () => {
+  const pkg = await import("../package.json", { with: { type: "json" } });
+  const exportsMap = pkg.default.exports;
+  assert.ok(exportsMap, "package.json should declare an exports map");
+  assert.strictEqual(exportsMap["./fs"], "./fs-router.mjs");
+  assert.strictEqual(exportsMap["."], "./index.mjs");
+});
+
+test("@johnhenry/letterpress/fs resolves createFSRouter via self-reference", async () => {
+  const fsSubpath = await import("@johnhenry/letterpress/fs");
+  assert.strictEqual(typeof fsSubpath.createFSRouter, "function");
+});
+
+test("@johnhenry/letterpress (self-reference) does not carry createFSRouter", async () => {
+  const barrel = await import("@johnhenry/letterpress");
+  assert.strictEqual("createFSRouter" in barrel, false);
+});

package/test/http-expression.mjs

@@ -599,4 +599,64 @@ test("HTTPExpression - Additional Tests", async (t) => {
     });
     assert.strictEqual(expr.test(request), true);
   });
+
+  // Regression tests for https://github.com/johnhenry/letterpress/issues/4:
+  // `[Authorization: Bearer *]` (the README's colon-form matcher) used to
+  // fold ": Bearer" into the header *name*, so `headers.get()` threw
+  // `TypeError: invalid header name` -- and since the router calls matchers
+  // inside a top-level try/catch, that 500'd EVERY request routed through
+  // a matcher registered with this syntax, not just matching requests.
+  await t.test(
+    "Colon-form header matcher does not throw when the header is absent (issue #4 repro)",
+    () => {
+      const expr = HTTPExpression(["GET /admin [Authorization: Bearer *]"]);
+      const request = new Request("http://localhost/admin", {
+        method: "GET",
+      });
+      assert.doesNotThrow(() => expr.test(request));
+      // No Authorization header present, so the wildcard match fails.
+      assert.strictEqual(expr.test(request), false);
+    }
+  );
+
+  await t.test(
+    "Colon-form header matcher wildcard-matches any bearer token",
+    () => {
+      const expr = HTTPExpression(["GET /admin [Authorization: Bearer *]"]);
+      const request = new Request("http://localhost/admin", {
+        method: "GET",
+        headers: { Authorization: "Bearer eyJhbGciOiJIUzI1NiJ9.abc" },
+      });
+      assert.strictEqual(expr.test(request), true);
+    }
+  );
+
+  await t.test(
+    "Colon-form header matcher rejects a non-matching value",
+    () => {
+      const expr = HTTPExpression(["GET /admin [Authorization: Bearer *]"]);
+      const request = new Request("http://localhost/admin", {
+        method: "GET",
+        headers: { Authorization: "Basic dXNlcjpwYXNz" },
+      });
+      assert.strictEqual(expr.test(request), false);
+    }
+  );
+
+  await t.test(
+    "Starts-with operator form [Authorization^=Bearer] keeps working alongside the colon form",
+    () => {
+      const expr = HTTPExpression(["GET /admin [Authorization^=Bearer]"]);
+      const matching = new Request("http://localhost/admin", {
+        method: "GET",
+        headers: { Authorization: "Bearer token123" },
+      });
+      const nonMatching = new Request("http://localhost/admin", {
+        method: "GET",
+        headers: { Authorization: "Basic dXNlcjpwYXNz" },
+      });
+      assert.strictEqual(expr.test(matching), true);
+      assert.strictEqual(expr.test(nonMatching), false);
+    }
+  );
 });

package/test/index.mjs

@@ -4,3 +4,4 @@ import "./route.mjs";
 import "./req-res.mjs";
 import "./fs-router.mjs";
 import "./dynamic-run.mjs";
+import "./exports.mjs";

package/utility/http-expression.mjs

@@ -88,19 +88,38 @@ export const HTTPExpression = (strings, ...expressions) => {
 };
 
 const parseHeaderMatcher = (headerString) => {
-  const match = headerString.match(/\[(!?)([^=~^$*<>]+)([=~^$*<>]+)?(.+)?\]/);
+  // Header name stops at ':' (colon form, e.g. `[Authorization: Bearer *]`)
+  // as well as at any operator character (`=~^$*<>`, e.g. `[Authorization^=Bearer]`).
+  // Without excluding ':' here, a colon-form matcher gets its ": Bearer"
+  // folded into the header *name*, which then throws when passed to
+  // `Headers.get()` (colons/whitespace are invalid header-name characters).
+  const match = headerString.match(
+    /\[(!?)([^=~^$*<>:]+)(?:(:)\s*|([=~^$*<>]+))?(.+)?\]/
+  );
   if (!match) {
     throw new Error(`Invalid header matcher: ${headerString}`);
   }
-  const [, negation, name, operator, value] = match;
+  const [, negation, name, colon, operator, value] = match;
   return createHeaderMatcherFunction({
     name: name.trim(),
-    operator: operator?.trim(),
+    // Colon form has no operator character of its own; treat the value
+    // that follows the ':' as a wildcard-match pattern (`*` matches any
+    // run of characters), so `[Authorization: Bearer *]` matches any
+    // bearer token instead of requiring an exact value.
+    operator: colon ? "wildcard" : operator?.trim(),
     value: value?.trim(),
     negate: !!negation,
   });
 };
 
+const escapeRegExpLiteral = (str) =>
+  str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+const wildcardToRegExp = (pattern) =>
+  new RegExp(
+    "^" + pattern.split("*").map(escapeRegExpLiteral).join(".*") + "$"
+  );
+
 const createHeaderMatcherFunction = ({ name, operator, value, negate }) => {
   return (headers) => {
     const headerValue = headers.get(name);
@@ -135,6 +154,9 @@ const createHeaderMatcherFunction = ({ name, operator, value, negate }) => {
         case "*=":
           match = headerValue.includes(value || "");
           break;
+        case "wildcard":
+          match = wildcardToRegExp(value || "").test(headerValue);
+          break;
         case ">":
           match = parseFloat(headerValue) > parseFloat(value || "0");
           break;