@myteril/hammock-cli 0.0.0-stage → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 myteril
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,164 @@
-# Temporary Holding Version
+# Hammock
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> Turn a folder of JSON files into a working mock API with one command — no backend code, no config files, no dependencies.
+
+![Node.js 22+](https://img.shields.io/badge/Node.js-22+-339933?logo=node.js&logoColor=white) ![MIT License](https://img.shields.io/badge/license-MIT-blue) ![0 dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)
+
+**English Documentation** · [Turkish Documentation](README.tur.md)
+
+## Local-only warning
+
+> [!WARNING]
+> **Hammock is for local development only, and it is not secured.** It has no authentication, no authorization, no CORS control. Never use it in production or on a public server, and never expose it through port forwarding, a reverse proxy, or a tunnel.
+>
+> **Serve a dedicated folder that holds only synthetic mock data.** Every routable `.json` file in that folder, including dot-prefixed hidden files, can be read whenever its route is known or guessed, and the absence of a directory listing is not confidentiality. Do not place secrets, tokens, credentials, private keys, production data, or customer data in the served folder.
+>
+> **Do not start Hammock from your home directory, a real project or repository root, or an untrusted project**, because files such as `package.json` would become routable. Stop the server with Ctrl+C when you are done.
+
+## Why Hammock?
+
+- **One command, zero setup.** Run `hammock` inside a folder and every JSON file in it becomes an endpoint.
+- **Routes mirror your folders.** Any nesting depth works, and the URL pattern never changes.
+- **No extra packages.** Hammock runs on Node.js built-in modules only.
+- **Ports pick themselves.** Hammock takes the first free port from `3000`; `--port` pins a specific one.
+- **Always current.** Files are re-read on every request, so edits show up without a restart.
+
+Hammock fits frontend work: prototype a screen, demo a feature, or hand a client realistic responses before the real API exists.
+
+## Quick start
+
+Hammock needs Node.js 22 or newer:
+
+```bash
+node --version
+```
+
+Install it globally:
+
+```bash
+npm install -g @myteril/hammock-cli
+```
+
+Create a folder with a JSON file or two:
+
+```text
+my-project/
+├── users.json
+└── orders/
+    └── latest.json
+```
+
+```json
+{
+  "id": 1,
+  "name": "Ada Lovelace",
+  "role": "developer"
+}
+```
+
+Start Hammock from that folder:
+
+```bash
+cd my-project
+hammock
+```
+
+```text
+Serving /path/to/my-project
+Listening on http://127.0.0.1:3000
+```
+
+Both endpoints are now live:
+
+- http://127.0.0.1:3000/users
+- http://127.0.0.1:3000/orders/latest
+
+Hammock serves the folder you start it from and listens on `127.0.0.1` only, so those endpoints work on your machine alone.
+
+## How routes work
+
+Hammock appends `.json` to the last segment of the URL, so routes never carry the extension:
+
+| File | URL |
+|---|---|
+| `users.json` | `/users` |
+| `orders/latest.json` | `/orders/latest` |
+| `api/v1/products.json` | `/api/v1/products` |
+
+- Query parameters are ignored: `/users?role=admin` serves `users.json`.
+- A URL whose last segment already ends in `.json` returns `404`, so request `/users`, not `/users.json`.
+- Nested folders work to any depth, and directory listings are never served.
+- Symbolic links that resolve outside the served folder are not served and return `404`.
+- Every request re-reads the file from disk and loads it fully into memory, so keep mock files reasonably small.
+
+## Requests and browser access
+
+Hammock is read-only: it never creates, modifies, or deletes files. Read-only behavior prevents writes, not reads, and is not an access-control boundary.
+
+| Method | Result |
+|---|---|
+| `GET`, `POST`, `PUT` | The same JSON file is returned |
+| `OPTIONS` | `204` preflight response |
+| Anything else | `405` with an `Allow` header |
+
+POST and PUT bodies are read and discarded. A body larger than `1 MiB` is rejected with `413`.
+
+> **CORS is permissive, not disabled.** Hammock reflects any single syntactically valid `http` or `https` `Origin` in `Access-Control-Allow-Origin`, always as the exact origin and never as `*`, and it sends `Access-Control-Allow-Credentials: true` for those requests. Credentialed `fetch` requests such as `credentials: 'include'` and `XMLHttpRequest` requests with `withCredentials = true` are therefore supported. Preflight requests approve `GET`, `POST`, `PUT`, and `OPTIONS`; a syntactically valid `Access-Control-Request-Headers` value such as `Content-Type, Authorization` is echoed in `Access-Control-Allow-Headers`, while a missing or invalid value omits that header instead of falling back to `*`. Error responses such as `400`, `404`, `405`, `413`, and `500` carry the same CORS headers, so browser code can read them. A missing, invalid, multiple, `null`, or non-HTTP(S) `Origin` gets no CORS response headers, but the request is still processed normally. Origin reflection is not an origin allowlist: any `http` or `https` page your browser allows to reach this server — including sites you did not create — can read the served JSON, with credentials if it asks for them, and non-browser clients can ignore CORS entirely. Hammock still has no authentication and no authorization and never validates or uses credentials; the browser merely carries them, and the server does not protect them. Cookies are host-scoped and generally ignore ports, so a request to `127.0.0.1:3000` may carry cookies another local service set for `127.0.0.1`, subject to browser cookie policy. `Origin: null`, `file://` pages, sandboxed frames, and non-HTTP(S) origins are unsupported; serve the frontend from a normal local `http` origin instead. 
+
+## Options
+
+| Option | Description |
+|---|---|
+| `-p, --port <number>` | Use a specific port: an integer from `1` to `65535` |
+| `--https` | Serve over HTTPS; requires `--cert` and `--key` |
+| `--cert <path>` | PEM certificate or certificate chain |
+| `--key <path>` | PEM private key |
+| `-h, --help` | Show the help text |
+| `-v, --version` | Show the version number |
+
+Without `--port`, Hammock starts at `3000` and moves upward until it finds a free port. With `--port`, a busy port stops startup with an error; drop the option to let Hammock choose, or pick another port. `--cert` and `--key` are valid only together with `--https`, and `--https` fails if either of them is missing.
+
+## HTTPS
+
+```bash
+hammock --https --cert ./cert.pem --key ./key.pem
+```
+
+The certificate must be trusted by your browser and valid for `127.0.0.1`, ideally with `localhost` in its Subject Alternative Names; an untrusted certificate earns a browser warning. Hammock does not create certificates, download them, or contact a certificate authority. If the certificate or key cannot be read or loaded, the server does not start — it never falls back to HTTP.
+
+HTTPS protects transport only. It does not make public exposure, proxying, or tunneling safe.
+
+> [!IMPORTANT]
+> **Keep certificate and key files outside the served folder, and restrict access to the private key.** Never reuse or commit a production private key; use a certificate dedicated to local development.
+
+On macOS or Linux you can tighten the key file permissions:
+
+```bash
+chmod 600 key.pem
+```
+
+For a locally trusted certificate you can use `mkcert`:
+
+```bash
+mkcert -install
+mkcert -cert-file cert.pem -key-file key.pem 127.0.0.1 localhost
+```
+
+`mkcert -install` installs a local root CA that browsers and applications trust. Run it only on a machine you control and understand.
+
+## Troubleshooting
+
+| Problem | Fix |
+|---|---|
+| `404` although the file exists | The URL probably ends in `.json` or the path is wrong; request `/orders/latest`, not `/orders/latest.json`. |
+| `404` for a symlinked file | The link resolves outside the served folder, so Hammock refuses to serve it. |
+| Port already in use | The `--port` value is taken; omit `--port` or choose a different port. |
+| Browser certificate warning | The certificate is not trusted or does not cover `127.0.0.1`; check trust and Subject Alternative Names. |
+| `413` | A POST or PUT body is larger than `1 MiB`. |
+| `405` | The method is not `GET`, `POST`, `PUT`, or `OPTIONS`. |
+| No CORS headers in `curl` | No valid `Origin` header was sent; this is expected and the request was still served. |
+| Credentialed request fails with a CORS error | Serve the page from a normal `http` or `https` origin, not `file://` or a sandboxed `null` origin, and check that the response carries the exact reflected `Origin` plus `Access-Control-Allow-Credentials: true`. |
+
+## License
+
+Hammock is released under the MIT License. See [LICENSE](LICENSE) for the full text.

package/README.tur.md

@@ -0,0 +1,164 @@
+# Hammock
+
+> Bir JSON klasörünü tek komutla çalışan bir mock API'ye dönüştürün — arka uç kodu yok, yapılandırma dosyası yok, bağımlılık yok.
+
+![Node.js 22+](https://img.shields.io/badge/Node.js-22+-339933?logo=node.js&logoColor=white) ![MIT Lisansı](https://img.shields.io/badge/license-MIT-blue) ![0 bağımlılık](https://img.shields.io/badge/dependencies-0-brightgreen)
+
+[English Documentation](README.md) · **Türkçe Belgeler**
+
+## Yerel kullanım uyarısı
+
+> [!WARNING]
+> **Hammock yalnızca yerel geliştirme içindir.** Kimlik doğrulama yoktur, yetkilendirme, CORS denetimi yoktur. Üretim ortamında veya genel erişime açık bir sunucuda asla kullanmayın; port yönlendirme, ters proxy ya da tünel üzerinden asla genel erişime açmayın.
+>
+> **Yalnızca sentetik mock verisi barındıran ayrı bir klasör sunun.** O klasördeki adreslenebilir her `.json` dosyası — nokta ile başlayan gizli dosyalar dahil — adresi bilindiğinde veya tahmin edildiğinde okunabilir; dizin listelemesinin olmaması gizlilik anlamına gelmez. Sunulan klasöre gizli bilgiler, token'lar, kimlik bilgileri, özel anahtarlar, üretim verisi ya da müşteri verisi koymayın.
+>
+> **Hammock'u ev dizininizden, gerçek bir proje ya da depo kökünden veya güvenmediğiniz bir projeden başlatmayın**, çünkü `package.json` gibi dosyalar da adreslenebilir hale gelir. İşiniz bittiğinde sunucuyu Ctrl+C ile durdurun.
+
+## Neden Hammock?
+
+- **Tek komut, sıfır kurulum.** Bir klasörün içinde `hammock` komutunu çalıştırın; içindeki her JSON dosyası bir uç noktaya dönüşür.
+- **Adresler klasörlerinizi yansıtır.** Adres derinliği iç içe klasörleri ifade eder ve URL düzeni hiç değişmez.
+- **Ek paket gerekmez.** Hammock yalnızca Node.js'in yerleşik modülleriyle çalışır.
+- **Portu kendisi seçer.** Hammock `3000` portundan başlayarak ilk boş portu alır. İsterseniz `--port`komutuyla belirli bir portu sabitler.
+- **Her zaman güncel.** Dosyalar her istekte yeniden okunur, bu yüzden değişiklikler yeniden başlatma gerektirmeden görünür.
+
+Hammock ön yüz çalışmalarına uygundur: bir ekranı prototipleyin, bir özelliğin ön gösterimini (demo) oluşturun ya da gerçek API ortaya çıkmadan müşteriye gerçekçi yanıtlar verin.
+
+## Hızlı başlangıç
+
+Hammock için Node.js 22 sürümü veya daha yenisi gerekir:
+
+```bash
+node --version
+```
+
+Global olarak kurun:
+
+```bash
+npm install -g @myteril/hammock-cli
+```
+
+Bir iki JSON dosyası olan bir klasör oluşturun:
+
+```text
+projem/
+├── kullanicilar.json
+└── siparisler/
+    └── son.json
+```
+
+```json
+{
+  "id": 1,
+  "isim": "Ada Lovelace",
+  "rol": "gelistirici"
+}
+```
+
+Hammock'u o klasörden başlatın:
+
+```bash
+cd projem
+hammock
+```
+
+```text
+Serving /path/to/my-project
+Listening on http://127.0.0.1:3000
+```
+
+İki uç nokta artık çalışıyor:
+
+- http://127.0.0.1:3000/kullanicilar
+- http://127.0.0.1:3000/siparisler/son
+
+Hammock başlatıldığı klasörü sunar ve yalnızca `127.0.0.1` üzerinde dinler, bu yüzden bu uç noktalar yalnızca sizin makinenizde çalışır.
+
+## Adresler nasıl çalışır?
+
+Hammock, URL'nin son bölümüne `.json` ekler, bu yüzden adreslerde uzantı yer almaz:
+
+| Dosya | URL |
+|---|---|
+| `kullanicilar.json` | `/kullanicilar` |
+| `siparisler/son.json` | `/siparisler/son` |
+| `api/v1/urunler.json` | `/api/v1/urunler` |
+
+- Sorgu parametreleri yok sayılır: `/kullanicilar?rol=admin` isteği `kullanicilar.json` dosyasını sunar.
+- Son bölümü `.json` ile biten bir URL `404` döndürür; yani `/kullanicilar.json` değil `/kullanicilar` isteyin.
+- İç içe klasörler her derinlikte çalışır ve dizin listelemesi hiçbir zaman sunulmaz.
+- Sunulan klasörün dışına çıkan sembolik bağlantılar sunulmaz ve `404` döndürür.
+- Her istek dosyayı diskten yeniden okur ve tamamen belleğe alır, bu yüzden mock dosyaları makul boyutta tutun.
+
+## İstekler ve tarayıcı erişimi
+
+Hammock sadece okur: hiçbir dosyayı oluşturmaz, değiştirmez veya silmez.
+
+| Yöntem | Sonuç |
+|---|---|
+| `GET`, `POST`, `PUT` | Aynı JSON dosyası döndürülür |
+| `OPTIONS` | `204` ön kontrol yanıtı |
+| Diğerleri | `Allow` başlığıyla `405` |
+
+POST ve PUT gövdeleri okunur ve görmezden gelinir. `1 MiB` değerinden büyük bir gövde `413` ile reddedilir.
+
+> **CORS olabildiğince serbest bırakılmıştır.** Hammock, sözdizimsel olarak geçerli tek bir `http` veya `https` `Origin` değerini `Access-Control-Allow-Origin` başlığında her zaman tam kaynak olarak yansıtır ve asla `*` kullanmaz; bu istekler için `Access-Control-Allow-Credentials: true` başlığını da gönderir. Böylece `credentials: 'include'` gibi kimlik bilgisi içeren `fetch` istekleri ve `withCredentials = true` kullanan `XMLHttpRequest` istekleri desteklenir. Ön kontrol istekleri `GET`, `POST`, `PUT` ve `OPTIONS` yöntemlerini onaylar; `Content-Type, Authorization` gibi sözdizimsel olarak geçerli bir `Access-Control-Request-Headers` değeri `Access-Control-Allow-Headers` başlığında yansıtılır, eksik veya geçersiz olduğunda ise bu başlık `*` yerine hiç gönderilmez. `400`, `404`, `405`, `413` ve `500` gibi hata yanıtları da aynı CORS başlıklarını taşır, böylece tarayıcı kodu bu yanıtları okuyabilir. Eksik, geçersiz, birden çok, `null` veya HTTP(S) dışı bir `Origin` için CORS yanıt başlığı gönderilmez, ancak istek yine normal şekilde işlenir. Kaynak yansıtma bir kaynak izin listesi değildir: tarayıcınızın bu sunucuya erişmesine izin verdiği her `http` veya `https` sayfası, sizin oluşturmadığınız siteler dâhil, sunulan JSON'u okuyabilir; isterse kimlik bilgileriyle de okuyabilir ve tarayıcı olmayan istemciler CORS'u tamamen yok sayabilir. Hammock'ta kimlik doğrulama ve yetkilendirme yoktur; kimlik bilgilerini hiçbir zaman doğrulamaz veya kullanmaz. Kimlik bilgilerini yalnızca tarayıcı taşır ve sunucu bunları korumaz. Çerezler ana makineye (host) göre gönderilir ve genellikle portları yok sayar; bu yüzden `127.0.0.1:3000` adresine yapılan bir istek, başka bir yerel servisin `127.0.0.1` için ayarladığı çerezleri taşıyabilir; tarayıcı çerez ilkesi yine de geçerlidir. `Origin: null`, `file://` sayfaları, korumalı alan (sandbox) çerçeveleri ve HTTP(S) dışı kaynaklar desteklenmez; ön yüzü bunun yerine normal bir yerel `http` kaynağından sunun. 
+
+## Seçenekler
+
+| Seçenek | Açıklama |
+|---|---|
+| `-p, --port <number>` | Belirli bir port kullanır: `1` ile `65535` arasında bir tam sayı |
+| `--https` | HTTPS üzerinden sunar; `--cert` ve `--key` gerektirir |
+| `--cert <path>` | PEM sertifikası veya sertifika zinciri |
+| `--key <path>` | PEM özel anahtarı |
+| `-h, --help` | Yardım metnini gösterir |
+| `-v, --version` | Sürüm numarasını gösterir |
+
+`--port` verilmezse Hammock `3000` portundan başlar ve boş bir port bulana kadar yukarı doğru ilerler. `--port` verildiğinde dolu bir port başlatmayı hatayla durdurur; byle bir durumda seçeneği kaldırıp Hammock'un portu seçmesine izin verin veya başka bir port seçin. `--cert` ve `--key` yalnızca `--https` ile birlikte geçerlidir ve bunlardan biri eksikse `--https` başarısız olur.
+
+## HTTPS
+
+```bash
+hammock --https --cert ./cert.pem --key ./key.pem
+```
+
+Sertifika tarayıcınız tarafından güvenilir olmalı ve `127.0.0.1` için geçerli olmalıdır; `Subject Alternative Names` alanında `localhost` bulunması ideal olur. Hammock sertifika oluşturmaz, indirmez ve bir sertifika otoritesiyle iletişim kurmaz. Sertifika veya anahtar okunamaz ya da yüklenemezse sunucu başlamaz; hiçbir zaman HTTP'ye geri dönmez.
+
+HTTPS yalnızca taşıma katmanını korur. Genel erişime açmayı, proxy kullanmayı veya tünellemeyi güvenli hale getirmez.
+
+> [!IMPORTANT]
+> **Sertifika ve anahtar dosyalarını sunulan klasörün dışında tutun ve özel anahtara erişimi kısıtlayın.** Üretim özel anahtarını asla yeniden kullanmayın veya sürüm kontrolüne eklemeyin; yerel geliştirmeye özel bir sertifika kullanın.
+
+macOS veya Linux'ta anahtar dosyasının izinlerini sıkılaştırabilirsiniz:
+
+```bash
+chmod 600 key.pem
+```
+
+Yerel olarak güvenilen bir sertifika için `mkcert` kullanabilirsiniz:
+
+```bash
+mkcert -install
+mkcert -cert-file cert.pem -key-file key.pem 127.0.0.1 localhost
+```
+
+`mkcert -install` tarayıcıların ve uygulamaların güvendiği yerel bir kök sertifika otoritesi kurar. Bu komutu yalnızca sahibi olduğunuz ve anladığınız bir makinede çalıştırın.
+
+## Sorun giderme
+
+| Sorun | Çözüm |
+|---|---|
+| Dosya var olduğu halde `404` | URL muhtemelen `.json` ile bitiyor ya da yol yanlış; `/siparisler/son.json` değil `/siparisler/son`'a gitmeyi deneyin. |
+| Sembolik bağlantılı dosyada `404` | Bağlantı sunulan klasörün dışına çıkıyor, bu yüzden Hammock onu sunmayı reddeder. |
+| Port zaten kullanımda | `--port`ile sabitlenen port kullanılıyor; `--port` seçeneğini kaldırın veya farklı bir port seçin. |
+| Tarayıcı sertifika uyarısı | Sertifika güvenilir değil ya da `127.0.0.1` adresini kapsamıyor; güveni ve `Subject Alternative Names` alanını kontrol edin. |
+| `413` | Bir POST veya PUT gövdesi `1 MiB` değerinden büyük. |
+| `405` | Yöntem `GET`, `POST`, `PUT` veya `OPTIONS` değil. |
+| `curl` çıktısında CORS başlığı yok | Geçerli bir `Origin` başlığı gönderilmedi; bu beklenen bir durumdur ve istek yine de sunulur. |
+| Kimlik bilgisi içeren istek CORS hatasıyla başarısız oluyor | Sayfayı `file://` ya da korumalı alan (sandbox) kaynaklı `null` bir kaynaktan değil, normal bir `http` veya `https` kaynağından sunun ve yanıtta tam yansıtılmış `Origin` ile `Access-Control-Allow-Credentials: true` başlığının bulunduğunu doğrulayın. |
+
+## Lisans
+
+Hammock MIT Lisansı ile yayımlanır. Tam metin için [LICENSE](LICENSE) dosyasına bakın.

package/bin/hammock.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+'use strict';
+
+const { main } = require('../src/cli');
+
+main();

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "@myteril/hammock-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.1.0",
+  "description": "A zero-dependency CLI that serves JSON files from the current folder as a local mock API.",
+  "type": "commonjs",
+  "scripts": {
+    "test": "node --test"
+  },
+  "bin": {
+    "hammock": "bin/hammock.js"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "keywords": [
+    "api",
+    "cli",
+    "development",
+    "json",
+    "mock",
+    "server"
+  ]
 }

package/src/cli.js

@@ -0,0 +1,210 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const tls = require('node:tls');
+const { parseArgs } = require('node:util');
+
+const pkg = require('../package.json');
+
+const HELP = `Usage: hammock [options]
+
+Start a read-only mock JSON API for the current folder.
+
+Options:
+  -p, --port <number>  Port to use (1-65535); default: first free port from 3000
+      --https          Serve over HTTPS (requires --cert and --key)
+      --cert <path>    PEM certificate or certificate chain
+      --key <path>     PEM private key
+  -h, --help           Show this help
+  -v, --version        Show the version
+`;
+
+const SERVER_LOAD_ERROR = 'Unable to load the server implementation.';
+const HTTPS_CREATE_ERROR =
+  'Unable to create the HTTPS server. Check the certificate and key files.';
+
+class CliError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'CliError';
+  }
+}
+
+function sanitize(value, limit = 500) {
+  const text = String(value ?? '')
+    .replace(/[\u0000-\u001f\u007f-\u009f]/g, ' ')
+    .trim();
+  return text.length > limit ? `${text.slice(0, limit - 3)}...` : text;
+}
+
+function formatArgumentError(error) {
+  if (error && error.code === 'ERR_PARSE_ARGS_UNEXPECTED_POSITIONAL') {
+    return 'Positional arguments are not supported.';
+  }
+  return sanitize(error && error.message) || 'Invalid arguments.';
+}
+
+function parsePort(value) {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (!/^[1-9][0-9]{0,4}$/.test(value) || Number(value) > 65535) {
+    throw new CliError('Invalid value for --port. Use an integer from 1 to 65535.');
+  }
+  return Number(value);
+}
+
+function parseOptions(args) {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args,
+      allowPositionals: false,
+      strict: true,
+      options: {
+        port: { type: 'string', short: 'p' },
+        https: { type: 'boolean' },
+        cert: { type: 'string' },
+        key: { type: 'string' },
+        help: { type: 'boolean', short: 'h' },
+        version: { type: 'boolean', short: 'v' }
+      }
+    });
+  } catch (error) {
+    throw new CliError(formatArgumentError(error));
+  }
+
+  const values = parsed.values;
+  if (values.help) {
+    return { action: 'help' };
+  }
+  if (values.version) {
+    return { action: 'version' };
+  }
+
+  const hasCert = values.cert !== undefined;
+  const hasKey = values.key !== undefined;
+  if (values.https) {
+    if (!values.cert || !values.key) {
+      throw new CliError('--https requires both --cert and --key.');
+    }
+  } else if (hasCert || hasKey) {
+    throw new CliError('--cert and --key require --https.');
+  }
+
+  return {
+    action: 'serve',
+    port: parsePort(values.port),
+    https: Boolean(values.https),
+    cert: values.cert,
+    key: values.key
+  };
+}
+
+function readPem(label, filePath) {
+  try {
+    return fs.readFileSync(path.resolve(filePath));
+  } catch {
+    throw new CliError(`Unable to read the ${label} file.`);
+  }
+}
+
+function validateTlsMaterial(cert, key) {
+  try {
+    tls.createSecureContext({ cert, key });
+  } catch {
+    throw new CliError(HTTPS_CREATE_ERROR);
+  }
+}
+
+function loadExport(modulePath, exportName) {
+  let loaded;
+  try {
+    loaded = require(modulePath);
+  } catch {
+    throw new CliError(SERVER_LOAD_ERROR);
+  }
+
+  const fn = typeof loaded === 'function' ? loaded : loaded && loaded[exportName];
+  if (typeof fn !== 'function') {
+    throw new CliError(SERVER_LOAD_ERROR);
+  }
+  return fn;
+}
+
+async function start(options, stdout) {
+  const rootDir = process.cwd();
+  const cert = options.https ? readPem('certificate', options.cert) : undefined;
+  const key = options.https ? readPem('key', options.key) : undefined;
+  if (options.https) {
+    validateTlsMaterial(cert, key);
+  }
+  const createServer = loadExport('./server', 'createServer');
+  const listen = loadExport('./port', 'listen');
+
+  let server;
+  try {
+    server = await createServer({
+      rootDir,
+      https: options.https,
+      cert,
+      key
+    });
+  } catch {
+    throw new CliError(
+      options.https
+        ? HTTPS_CREATE_ERROR
+        : 'Unable to create the server.'
+    );
+  }
+
+  try {
+    await listen(server, options.port);
+  } catch (error) {
+    if (server.listening) {
+      server.close();
+    }
+    throw error;
+  }
+
+  const address = server.address();
+  if (!address || address.address !== '127.0.0.1') {
+    server.close();
+    throw new CliError('The server did not bind to 127.0.0.1.');
+  }
+
+  const port = address.port;
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    server.close();
+    throw new CliError('The server did not report a valid port.');
+  }
+
+  stdout.write(`Serving ${sanitize(rootDir)}\n`);
+  stdout.write(`Listening on ${options.https ? 'https' : 'http'}://127.0.0.1:${port}\n`);
+}
+
+async function main(argv = process.argv.slice(2), streams = process) {
+  try {
+    const options = parseOptions(argv);
+    if (options.action === 'help') {
+      streams.stdout.write(HELP);
+      return;
+    }
+    if (options.action === 'version') {
+      streams.stdout.write(`${pkg.version}\n`);
+      return;
+    }
+    await start(options, streams.stdout);
+  } catch (error) {
+    const message = sanitize(error && error.message) || 'Unexpected error.';
+    streams.stderr.write(`hammock: ${message}\n`);
+    process.exitCode = 1;
+  }
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = { main };

package/src/port.js

@@ -0,0 +1,77 @@
+'use strict';
+
+const HOST = '127.0.0.1';
+const FIRST_PORT = 3000;
+const LAST_PORT = 65535;
+
+function bind(server, port) {
+  return new Promise((resolve, reject) => {
+    function onError(error) {
+      server.off('listening', onListening);
+      reject(error);
+    }
+
+    function onListening() {
+      server.off('error', onError);
+      resolve();
+    }
+
+    server.once('error', onError);
+    server.once('listening', onListening);
+
+    try {
+      server.listen(port, HOST);
+    } catch (error) {
+      server.off('error', onError);
+      server.off('listening', onListening);
+      reject(error);
+    }
+  });
+}
+
+function isValidPort(port) {
+  return Number.isInteger(port) && port >= 1 && port <= LAST_PORT;
+}
+
+function bindError(error, port) {
+  if (error && error.code === 'EACCES') {
+    return new Error(`Permission denied while binding to ${HOST}:${port}.`);
+  }
+  return new Error(`Unable to bind to ${HOST}:${port}.`);
+}
+
+async function listen(server, requestedPort) {
+  if (requestedPort !== undefined) {
+    if (!isValidPort(requestedPort)) {
+      throw new Error('The port must be an integer from 1 to 65535.');
+    }
+
+    try {
+      await bind(server, requestedPort);
+    } catch (error) {
+      if (error && error.code === 'EADDRINUSE') {
+        throw new Error(
+          `Port ${requestedPort} is already in use. Omit --port to let Hammock choose a free port, or choose a different port.`
+        );
+      }
+      throw bindError(error, requestedPort);
+    }
+    return;
+  }
+
+  for (let port = FIRST_PORT; port <= LAST_PORT; port += 1) {
+    try {
+      await bind(server, port);
+      return;
+    } catch (error) {
+      if (error && error.code === 'EADDRINUSE') {
+        continue;
+      }
+      throw bindError(error, port);
+    }
+  }
+
+  throw new Error(`No free port is available between ${FIRST_PORT} and ${LAST_PORT}.`);
+}
+
+module.exports = { listen };

package/src/server.js

@@ -0,0 +1,386 @@
+'use strict';
+
+const fs = require('node:fs');
+const http = require('node:http');
+const https = require('node:https');
+const path = require('node:path');
+
+const BODY_LIMIT = 1024 * 1024;
+const ALLOWED_METHODS = 'GET, POST, PUT, OPTIONS';
+const SERVING_METHODS = new Set(['GET', 'POST', 'PUT']);
+const ERROR_MESSAGES = {
+  400: 'Bad request.',
+  404: 'Not found.',
+  405: 'Method not allowed.',
+  413: 'Payload too large.',
+  500: 'Internal server error.'
+};
+const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f-\u009f]/;
+const RAW_UNSAFE_SEQUENCE = /%(?:2f|5c|00)/i;
+const HEADER_LIST = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+(?:[ \t]*,[ \t]*[!#$%&'*+\-.^_`|~0-9A-Za-z]+)*$/;
+
+function allowHeaders(req) {
+  const requested = req.headers['access-control-request-headers'];
+  if (
+    typeof requested === 'string' &&
+    requested.length <= 1024 &&
+    HEADER_LIST.test(requested)
+  ) {
+    return requested;
+  }
+  return undefined;
+}
+
+function requestOrigin(req) {
+  const rawHeaders = req && req.rawHeaders;
+  if (!Array.isArray(rawHeaders)) {
+    return undefined;
+  }
+
+  let count = 0;
+  let origin;
+  for (let index = 0; index < rawHeaders.length; index += 2) {
+    const name = rawHeaders[index];
+    if (typeof name === 'string' && name.toLowerCase() === 'origin') {
+      count += 1;
+      origin = rawHeaders[index + 1];
+    }
+  }
+
+  if (count !== 1 || typeof origin !== 'string') {
+    return undefined;
+  }
+  if (origin.length === 0 || origin.length > 1024) {
+    return undefined;
+  }
+  if (/\s/.test(origin) || origin.includes(',') || CONTROL_CHARACTERS.test(origin)) {
+    return undefined;
+  }
+
+  let parsed;
+  try {
+    parsed = new URL(origin);
+  } catch {
+    return undefined;
+  }
+
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    return undefined;
+  }
+  if (parsed.origin !== origin) {
+    return undefined;
+  }
+
+  return origin;
+}
+
+function responseHeaders(req) {
+  const headers = {
+    'Cache-Control': 'no-store',
+    'Vary': 'Origin, Access-Control-Request-Headers',
+    'X-Content-Type-Options': 'nosniff'
+  };
+
+  const origin = requestOrigin(req);
+  if (origin !== undefined && req.headers) {
+    const allowedHeaders = allowHeaders(req);
+    if (allowedHeaders !== undefined) {
+      headers['Access-Control-Allow-Headers'] = allowedHeaders;
+    }
+    headers['Access-Control-Allow-Credentials'] = 'true';
+    headers['Access-Control-Allow-Methods'] = ALLOWED_METHODS;
+    headers['Access-Control-Allow-Origin'] = origin;
+  }
+
+  return headers;
+}
+
+function sendJson(res, status, message, headers, extraHeaders = {}) {
+  if (res.writableEnded || res.destroyed) {
+    return;
+  }
+  if (res.headersSent) {
+    res.end();
+    return;
+  }
+
+  const body = Buffer.from(JSON.stringify({ error: message }));
+  res.writeHead(status, {
+    ...headers,
+    ...extraHeaders,
+    'Content-Length': body.length,
+    'Content-Type': 'application/json; charset=utf-8'
+  });
+  res.end(body);
+}
+
+function sendError(res, status, headers, extraHeaders) {
+  sendJson(res, status, ERROR_MESSAGES[status] || 'Request failed.', headers, extraHeaders);
+}
+
+function sendNoContent(res, headers, extraHeaders = {}) {
+  if (res.writableEnded || res.destroyed) {
+    return;
+  }
+  if (res.headersSent) {
+    res.end();
+    return;
+  }
+
+  res.writeHead(204, { ...headers, ...extraHeaders });
+  res.end();
+}
+
+function closeWhenDone(req, res) {
+  res.once('finish', () => {
+    if (!req.destroyed) {
+      req.destroy();
+    }
+  });
+}
+
+function declaredTooLarge(req) {
+  const declared = req.headers['content-length'];
+  if (declared === undefined) {
+    return false;
+  }
+  const length = Number(declared);
+  return Number.isFinite(length) && length > BODY_LIMIT;
+}
+
+function drainBody(req) {
+  if (req.readableEnded) {
+    return Promise.resolve('complete');
+  }
+
+  return new Promise((resolve) => {
+    let received = 0;
+    let settled = false;
+
+    function cleanup() {
+      req.off('data', onData);
+      req.off('end', onEnd);
+      req.off('error', onError);
+      req.off('aborted', onAborted);
+    }
+
+    function finish(result) {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      cleanup();
+      resolve(result);
+    }
+
+    function onData(chunk) {
+      received += chunk.length;
+      if (received > BODY_LIMIT) {
+        req.pause();
+        finish('overflow');
+      }
+    }
+
+    function onEnd() {
+      finish('complete');
+    }
+
+    function onError() {
+      finish('aborted');
+    }
+
+    function onAborted() {
+      finish('aborted');
+    }
+
+    req.on('data', onData);
+    req.once('end', onEnd);
+    req.once('error', onError);
+    req.once('aborted', onAborted);
+  });
+}
+
+function isInside(root, target) {
+  const relative = path.relative(root, target);
+  return (
+    relative !== '' &&
+    relative !== '..' &&
+    !relative.startsWith(`..${path.sep}`) &&
+    !path.isAbsolute(relative)
+  );
+}
+
+function parseRequestPath(rawUrl) {
+  if (typeof rawUrl !== 'string') {
+    return { status: 404 };
+  }
+
+  const queryIndex = rawUrl.indexOf('?');
+  const rawPath = queryIndex === -1 ? rawUrl : rawUrl.slice(0, queryIndex);
+  if (!rawPath.startsWith('/') || rawPath === '/' || rawPath.endsWith('/')) {
+    return { status: 404 };
+  }
+  if (RAW_UNSAFE_SEQUENCE.test(rawPath) || CONTROL_CHARACTERS.test(rawPath)) {
+    return { status: 404 };
+  }
+
+  const rawSegments = rawPath.slice(1).split('/');
+  if (rawSegments.some((segment) => segment === '')) {
+    return { status: 404 };
+  }
+
+  let segments;
+  try {
+    segments = rawSegments.map((segment) => decodeURIComponent(segment));
+  } catch {
+    return { status: 400 };
+  }
+
+  for (const segment of segments) {
+    if (
+      segment === '' ||
+      segment === '.' ||
+      segment === '..' ||
+      segment.includes('/') ||
+      segment.includes('\\') ||
+      segment.includes(':') ||
+      CONTROL_CHARACTERS.test(segment) ||
+      /[. ]$/.test(segment)
+    ) {
+      return { status: 404 };
+    }
+  }
+
+  const lastIndex = segments.length - 1;
+  if (segments[lastIndex].endsWith('.json')) {
+    return { status: 404 };
+  }
+
+  segments[lastIndex] += '.json';
+  return { status: 200, segments };
+}
+
+function statusForError(error) {
+  if (
+    error &&
+    (error.code === 'ENOENT' || error.code === 'ENOTDIR' || error.code === 'ELOOP')
+  ) {
+    return 404;
+  }
+  return 500;
+}
+
+async function locateTarget(realRoot, rawUrl) {
+  const parsed = parseRequestPath(rawUrl);
+  if (parsed.status !== 200) {
+    return parsed;
+  }
+
+  const candidate = path.resolve(realRoot, ...parsed.segments);
+  if (!isInside(realRoot, candidate)) {
+    return { status: 404 };
+  }
+
+  let target;
+  try {
+    target = await fs.promises.realpath(candidate);
+  } catch (error) {
+    return { status: statusForError(error) };
+  }
+
+  if (!isInside(realRoot, target)) {
+    return { status: 404 };
+  }
+
+  try {
+    const info = await fs.promises.stat(target);
+    if (!info.isFile()) {
+      return { status: 404 };
+    }
+  } catch (error) {
+    return { status: statusForError(error) };
+  }
+
+  return { status: 200, target };
+}
+
+function createServer({ rootDir, https: useHttps, cert, key } = {}) {
+  const realRoot = fs.realpathSync(path.resolve(rootDir));
+  if (!fs.statSync(realRoot).isDirectory()) {
+    throw new Error('The root must be a directory.');
+  }
+
+  const handler = async (req, res) => {
+    const headers = responseHeaders(req);
+
+    try {
+      if (req.method === 'OPTIONS') {
+        sendNoContent(res, headers, { Connection: 'close' });
+        closeWhenDone(req, res);
+        return;
+      }
+
+      if (!SERVING_METHODS.has(req.method)) {
+        sendError(res, 405, headers, {
+          Allow: ALLOWED_METHODS,
+          Connection: 'close'
+        });
+        closeWhenDone(req, res);
+        return;
+      }
+
+      if (declaredTooLarge(req)) {
+        sendError(res, 413, headers, { Connection: 'close' });
+        closeWhenDone(req, res);
+        return;
+      }
+
+      const bodyState = await drainBody(req);
+      if (bodyState === 'aborted') {
+        return;
+      }
+      if (bodyState === 'overflow') {
+        sendError(res, 413, headers, { Connection: 'close' });
+        closeWhenDone(req, res);
+        return;
+      }
+
+      const resolved = await locateTarget(realRoot, req.url);
+      if (resolved.status !== 200) {
+        sendError(res, resolved.status, headers);
+        return;
+      }
+
+      let body;
+      try {
+        body = await fs.promises.readFile(resolved.target);
+      } catch (error) {
+        sendError(res, statusForError(error), headers);
+        return;
+      }
+
+      if (res.writableEnded || res.destroyed) {
+        return;
+      }
+      res.writeHead(200, {
+        ...headers,
+        'Content-Length': body.length,
+        'Content-Type': 'application/json; charset=utf-8'
+      });
+      res.end(body);
+    } catch {
+      sendError(res, 500, headers);
+    }
+  };
+
+  if (useHttps) {
+    if (!cert || !key) {
+      throw new Error('HTTPS requires a certificate and key.');
+    }
+    return https.createServer({ cert, key }, handler);
+  }
+  return http.createServer(handler);
+}
+
+module.exports = createServer;
+module.exports.createServer = createServer;