feat(static): add opt-in directory listing via dirListing

[pi0x]

Summary

Adds a dirListing option to serveStatic that serves a minimal HTML directory listing as a 404 fallback when a request names a directory with no index file (index.html). Off by default; the srvx CLI enables it in dev mode only.

serveStatic({ dir: "./public", dirListing: true });

Behaviour

The resolution order is static files → your handler → listing:

• A real route always wins — when no static file matches, next() runs first, and only a 404 response is replaced by the listing. A server route named like a directory in the static dir (e.g. /api) keeps working.
• Custom 404 pages keep working — a downstream 404 is replaced only when the path actually names a listable directory; everywhere else it passes through untouched, body and all.
• Index always wins — a directory with an index.html serves the index, never a listing (the index candidate is already probed by the existing lookup loop).
• Triggers on a request naming a directory: the root, a trailing-slash path (/files/), or an extension-less path (/files).
• Absolute hrefs — entry links are built from the request pathname with a guaranteed trailing slash, so links resolve identically whether the directory was requested with a trailing slash or without.
• Directories first, then alphabetical; directory entries get a trailing /. A ../ parent link appears everywhere but the root. HEAD returns the headers without a body.

Security

The listing re-asserts the same boundaries a file request gets, so it never names anything a direct request would refuse to serve:

• Lexical containment, then symlink-resolved containment (a link inside dir could point the directory out of the root).
• The dot-path deny check (dotfiles) on both the requested path and each entry — so .env/.git are hidden while .well-known shows, matching what is actually servable.
• Only names are revealed, never file contents. Filenames are encodeURIComponent-encoded then HTML-escaped before interpolation.

CLI

Enabled automatically in dev, off in prod:

serveStatic({ dir: cliOpts.static, dirListing: !cliOpts.prod })

Static-only mode (no server entry) now answers a miss with an ordinary 404 instead of a 501 "Server Entry Not Found" page — the correct status for that mode, and the one the fallback keys on.

Tests

New directory listing (dirListing) suite covering: off-by-default fall-through, non-404 downstream responses winning over the listing, custom-404 passthrough for non-directory paths, listing render, dot-segment hiding, index precedence (including root), extension-less routes, HEAD, symlink-escape denial, and missing directories. Full suite (1253 tests) passes; lint, format, and typecheck clean.

Verified end-to-end via the CLI: a /api route beats a same-name static directory, an entry 404 falls back to the listing, a custom 404 page passes through, and prod keeps the listing off.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Added an opt-in HTML directory listing fallback for static requests when no index exists.
  • Added CLI flags --dir-listing / --no-dir-listing, supporting dev defaults and explicit production override.
• Bug Fixes
  • Improved fallback behavior for missing server entries and tuned directory listing behavior in production vs dev.
  • Hardened listings (hidden/dot paths, symlink escape handling) with correct headers and HEAD handling.
• Documentation
  • Updated CLI and middleware guides to describe directory listing behavior and options.
• Tests
  • Expanded unit and integration coverage for listings, security, headers, and production behavior.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 5d00ebeb-61ac-4f8b-924c-be793d88b11a

📥 Commits

Reviewing files that changed from the base of the PR and between 0813146 and c7254f8.

📒 Files selected for processing (3)

• docs/1.guide/4.middleware.md
• src/static.ts
• test/static.test.ts

🚧 Files skipped from review as they are similar to previous changes (3)

• test/static.test.ts
• src/static.ts
• docs/1.guide/4.middleware.md

---

📝 Walkthrough

Walkthrough

Directory listing support is added to static serving with secure symlink and dotfile filtering, escaped HTML output, CLI controls, production-aware defaults, documentation, and coverage for routing, headers, HEAD requests, and fallback behavior.

Changes

Directory listing

Layer / File(s)	Summary
Listing option and CLI wiring src/static.ts, src/cli/*, docs/1.guide/*	Adds dirListing, CLI flags, production-aware defaults, server fallback handling, help text, and documentation.
Safe directory enumeration src/static.ts, test/static.test.ts	Enumerates entries while enforcing containment, symlink-target, and dotfile rules.
Listing response and validation src/static.ts, test/static.test.ts, test/cli.test.ts	Renders escaped listings with defensive headers and HEAD handling, with tests for precedence, routing, security, and CLI integration.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Possibly related PRs

• h3js/srvx#168: Shares CLI server-entry and fetch fallback behavior.

Suggested reviewers: pi0

Poem

I hop through folders, neat and bright,
Escaping names in HTML light.
Hidden dots stay out of view,
Safe paths guide each link anew.
HEAD gets headers, no body to bear—
A tidy listing blooms there!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 75.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: adding an opt-in static directory listing via dirListing.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/dir-list

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/srvx@277

commit: c7254f8

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/static.ts`:
- Around line 364-366: Update the directory-entry mapping in the static listing
flow to resolve each child’s canonical target, verify it remains under root, and
apply dot-path filtering to the resolved path before including it. Classify
included entries using the resolved target rather than the symlink’s directory
flag, and add coverage for symlinks escaping root or resolving to denied dot
paths.
- Line 693: Update the URL generation around the base-path normalization in the
static request handling flow so extension-less nested paths such as /docs/api
resolve the parent URL to /docs/ rather than /. Derive an absolute parent path
from the normalized base and apply the same correction to the corresponding
logic also used around lines 748-751.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 52b8d831-f879-45d2-8659-66e96cd7c33a

📥 Commits

Reviewing files that changed from the base of the PR and between 0e77d9f and 9739a0c.

📒 Files selected for processing (3)

• src/cli/serve.ts
• src/static.ts
• test/static.test.ts