@orieljs/http 0.1.0-alpha.6 → 0.1.0-alpha.7

package/NOTICE

@@ -10,3 +10,7 @@ The Oriel name and logo are not covered by that license; see TRADEMARKS.md
 
 @orieljs/support (and @orieljs/framework, which bundles it) includes transliteration data from
 voku/portable-ascii (https://github.com/voku/portable-ascii), Copyright (C) 2019 Lars Moelleken, MIT License.
+
+@orieljs/notifications (and @orieljs/framework, which bundles it) includes the HTML and CSS of
+Laravel's default notification mail (laravel/framework, https://github.com/laravel/framework),
+Copyright (c) Taylor Otwell, MIT License.

package/README.md

@@ -0,0 +1,33 @@
+# @orieljs/http
+
+The HTTP layer of Oriel: the request, responses and redirects, the middleware kernel, the error handler and its error pages, and the server for Node and Bun. It is Oriel's counterpart of Laravel's HTTP layer. Http is part of `@orieljs/framework`, which every Oriel app already installs, and is re-exported from it. In an app, import it from `@orieljs/framework`; `@orieljs/http` is also published on its own.
+
+```bash
+npm install @orieljs/framework
+```
+
+```ts title="app/Http/Controllers/SearchController.ts"
+import { request, response } from '@orieljs/framework'
+import { Post } from '../../Models/Post'
+import { Controller } from './Controller'
+
+export class SearchController extends Controller {
+  async index() {
+    const term = request().input('q', '')
+    const posts = await Post.whereLike('title', `%${term}%`).latest().get()
+    return response().json({ term, posts }, 200, { 'Cache-Control': 'no-store' })
+  }
+}
+```
+
+`request()` is the current `IncomingRequest`, with `input()`, `string()`, `boolean()`, `integer()`, `only()`, `file()` and `header()`; `await request().user()` is the signed-in user, or `undefined` for a guest. `response()`, `redirect()` and `back()` build responses, and `abort()`, `abortIf()` and `abortUnless()` stop a request with an HTTP error. `await serve(app)` runs the app on Node or Bun.
+
+Documentation: https://orieljs.vercel.app/docs/requests
+
+Status: early alpha. APIs will change.
+
+## License
+
+Oriel is open-source software licensed under the Apache License 2.0 (Apache-2.0; see `LICENSE` and `NOTICE`). The Oriel name and logo are trademarks; see `TRADEMARKS.md`.
+
+Website: https://orieljs.vercel.app

package/TRADEMARKS.md

@@ -0,0 +1,33 @@
+# Oriel trademark policy
+
+The Oriel code is open source under the Apache License 2.0. The **Oriel name and logo** are not: the license covers
+the code only (section 6 of the license says so), and the name and logo stay with the project. This page explains
+what you can and can't do with them. The goal is simple: people should always be able to tell what is the real Oriel
+and what isn't.
+
+## You can, without asking
+
+- Use, change, ship and sell the code, as the license allows.
+- Say that your app or package is "built with Oriel", "for Oriel" or "compatible with Oriel".
+- Name a package `oriel-<something>` or `<something>-for-oriel` when it works with Oriel, as long as it is clear that
+  it is not official (for example, don't publish it under the `@orieljs` npm scope).
+- Use the name and logo to write about Oriel, teach it, or link to it, in articles, talks, videos and courses.
+- Use the unmodified logo to point to the project, as it is (no recolouring, cropping or
+  distortion).
+
+## You can't, without written permission
+
+- Call a fork, a modified copy or a competing product "Oriel", or anything likely to be confused with it.
+- Use the name or logo as the name, logo or domain of your own product, company or service.
+- Suggest that the Oriel project made, endorses or supports your work when it doesn't.
+- Sell merchandise with the name or logo.
+
+## Forks
+
+Forks are welcome. Please give yours a different name and logo, keep the `LICENSE` and `NOTICE` files, and say that
+it is based on Oriel.
+
+## Questions
+
+Open an issue at https://github.com/orieljs/framework or email meeeet.dev@gmail.com. If you're unsure whether a use
+is fine, ask; the answer is usually yes.

package/dist/index.d.ts

@@ -1,6 +1,7 @@
-import { HttpRequest, CookieJar, Session, Container, RedirectResponse, HeadersInit, Redirector, UploadedFile, Rules, OrielError, RouteName, ResponseFactory, BodyInit, UrlGenerator, HttpKernel, Application, MiddlewareClass, Middleware, Next, MiddlewareConfigurator, Router, ConfigRepository, ExceptionHandler, ExceptionsConfigurator, ConsoleKernel, Route } from '@orieljs/contracts';
+import { HttpRequest, CookieJar, Session, Container, RedirectResponse, HeadersInit, MessageBag, Redirector, UploadedFile, Rules, InferValidatedType, OrielError, RouteName, RouteArguments, ResponseFactory, BodyInit, UrlGenerator, HttpKernel, Application, MiddlewareClass, Middleware, Next, MiddlewareConfigurator, Router, ConfigRepository, ExceptionHandler, ExceptionsConfigurator, ConsoleKernel, Route } from '@orieljs/contracts';
 import { FileType, Stringable, ServiceProvider } from '@orieljs/support';
 import { IncomingMessage, ServerResponse } from 'node:http';
+import { SpawnOptions, ChildProcess } from 'node:child_process';
 
 /**
  * Whether a JSON text nests objects and arrays deeper than `maxDepth`, found by scanning (no parsing, no recursion):
@@ -18,9 +19,7 @@ declare function currentRequest(): HttpRequest | undefined;
 declare function optionalSession(): Session | undefined;
 declare function optionalCookieJar(): CookieJar | undefined;
 
-type ErrorsInput = Record<string, string | string[]> | {
-    toObject(): Record<string, string[]>;
-};
+type ErrorsInput = Record<string, string | string[]> | MessageBag;
 /**
  * Laravel's RedirectResponse. with()/withErrors()/withInput() flash to the request's Session immediately, like
  * Laravel; without a bound Session (an API-only app) they are skipped silently.
@@ -182,10 +181,17 @@ declare class IncomingRequest implements HttpRequest {
     /** One route parameter (after model binding), or all of them. */
     route<T = unknown>(key?: string): T;
     session(): Session;
-    user<T = unknown>(guard?: string): T | undefined;
+    /**
+     * The signed-in user, through the resolver Auth sets, else the current scope's guard (the default, or `guard`).
+     * The guard keeps the user it found, so it is looked up once per request. Undefined for a guest or without auth.
+     */
+    user<T = unknown>(guard?: string): Promise<T | undefined>;
     setUserResolver(resolver: (guard?: string) => unknown): void;
-    /** Validates all() through the ValidationFactory; throws its Validation error on failure. */
-    validate<T = Record<string, unknown>>(rules: Rules, messages?: Record<string, string>, attributes?: Record<string, string>): Promise<T>;
+    /**
+     * Validates all() through the ValidationFactory; throws its Validation error on failure. The data is typed from the
+     * rules: `validate({ title: 'required|string' })` is `{ title: string }`.
+     */
+    validate<const R extends Rules>(rules: R, messages?: Record<string, string>, attributes?: Record<string, string>): Promise<InferValidatedType<R>>;
 }
 
 /** Helpers for request input: PHP-style bracket keys, safe cloning (no prototype pollution) and blank checks. */
@@ -245,9 +251,9 @@ declare function request<T = unknown>(key: string, defaultValue?: T): T;
 /** response() → the ResponseFactory; response(content, status, headers) → a Response. */
 declare function response(): ResponseFactory;
 declare function response(content: BodyInit | null, status?: number, headers?: HeadersInit): Response;
-/** The Redirector with its route() typed by the generated route names. */
+/** The Redirector with its route() typed by the generated route names and their parameters. */
 type TypedRedirector = Omit<Redirector, 'route'> & {
-    route(name: RouteName, parameters?: unknown, status?: number): RedirectResponse;
+    route<N extends RouteName>(name: N, ...args: RouteArguments<N, [status?: number]>): RedirectResponse;
 };
 /** redirect() → the Redirector; redirect('/path', status) → a RedirectResponse. */
 declare function redirect(): TypedRedirector;
@@ -257,8 +263,11 @@ declare function back(fallback?: string, status?: number): RedirectResponse;
 /** url() → the UrlGenerator; url('/path', query, absolute) → a URL. */
 declare function url(): UrlGenerator;
 declare function url(path: string, query?: Record<string, unknown>, absolute?: boolean): string;
-/** The URL of a named route. */
-declare function route(name: RouteName, parameters?: unknown, absolute?: boolean): string;
+/**
+ * The URL of a named route: route('posts.show', post), route('posts.show', { post, page: 2 }). Once `oriel
+ * route:types` has run, the name and the route's parameters are checked.
+ */
+declare function route<N extends RouteName>(name: N, ...args: RouteArguments<N>): string;
 /** abort(404), abort(403, 'Nope', headers), or abort(response) to send a ready response. */
 declare function abort(status: number | Response, message?: string, headers?: Record<string, string>): never;
 declare function abortIf(condition: unknown, status: number | Response, message?: string, headers?: Record<string, string>): void;
@@ -384,7 +393,10 @@ declare class ExceptionsConfiguration implements ExceptionsConfigurator {
 /** Runs the withExceptions() callbacks against a handler (the provider does this when the handler is built). */
 declare function applyExceptionCallbacks(app: Application, handler: ErrorHandler): void;
 
-/** Laravel's wording for the status (its error pages say "Server Error" and "Page Expired"). */
+/**
+ * The text an error page shows for a status: Laravel's own wording where it has a view ("Server Error", "Page
+ * Expired"), else Symfony's `Response::$statusTexts`, which Laravel shows for the others.
+ */
 declare function statusText(status: number): string;
 declare function escapeHtml(value: string): string;
 /** Laravel's minimal error page: "404 | Not Found". */
@@ -473,6 +485,28 @@ declare function serve(app: Application, options?: ServeOptions): Promise<Runnin
  */
 declare function servePublicFile(publicPath: string, request: Request): Promise<Response | undefined>;
 
+interface FileWatcher {
+    close(): void;
+}
+
+/** node:child_process's spawn(), replaceable in tests. */
+type SpawnServer = (command: string, args: string[], options: SpawnOptions) => ChildProcess;
+interface WatchedServerOptions {
+    /** The server's command line: the runtime, its flags, the CLI script, then `serve --host=… --port=…`. */
+    command: readonly string[];
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    /** Starts watching: calls back with the changed files (relative to the base path) once they settle. */
+    watch(onChange: (files: string[]) => void): FileWatcher;
+    info(message: string): void;
+    error(message: string): void;
+    /** How long a server may take to stop before it is killed, in ms. Default 15000 (serve gives requests 10 s). */
+    stopTimeout?: number;
+    /** The signals that stop it. Default SIGINT, SIGTERM and SIGHUP. */
+    signals?: readonly NodeJS.Signals[];
+    spawn?: SpawnServer;
+}
+
 interface RouteListRow {
     /** 'GET|HEAD' */
     readonly method: string;
@@ -512,6 +546,8 @@ interface HttpCommandOptions {
     serve?: (app: Application, options: ServeOptions) => Promise<RunningServer>;
     /** The terminal width for route:list. Default: process.stdout.columns, else 120. */
     terminalWidth?: () => number;
+    /** Replaces `serve --watch`'s restarting server (tests). Resolves the command's exit code. */
+    watch?: (options: WatchedServerOptions) => Promise<number>;
 }
 /** Registers `serve`, `route:list` and `install:api` as closure commands (PC1). */
 declare function registerHttpCommands(kernel: ConsoleKernel, app: Application, options?: HttpCommandOptions): void;

package/dist/index.js

@@ -352,6 +352,7 @@ var FormUploadedFile = class _FormUploadedFile {
 
 // IncomingRequest.ts
 import {
+  AuthFactory,
   CurrentRoute,
   Session as Session2,
   ValidationFactory
@@ -768,13 +769,23 @@ var IncomingRequest = class {
   session() {
     return inject3(Session2);
   }
-  user(guard) {
-    return this.#userResolver?.(guard);
+  /**
+   * The signed-in user, through the resolver Auth sets, else the current scope's guard (the default, or `guard`).
+   * The guard keeps the user it found, so it is looked up once per request. Undefined for a guest or without auth.
+   */
+  async user(guard) {
+    if (this.#userResolver !== void 0) return await this.#userResolver(guard);
+    const container = currentContainer2();
+    if (container === void 0 || !container.bound(AuthFactory)) return void 0;
+    return await container.make(AuthFactory).guard(guard).user();
   }
   setUserResolver(resolver) {
     this.#userResolver = resolver;
   }
-  /** Validates all() through the ValidationFactory; throws its Validation error on failure. */
+  /**
+   * Validates all() through the ValidationFactory; throws its Validation error on failure. The data is typed from the
+   * rules: `validate({ title: 'required|string' })` is `{ title: string }`.
+   */
   validate(rules, messages, attributes) {
     return inject3(ValidationFactory).make(this.all(), rules, messages, attributes).validated();
   }
@@ -818,7 +829,8 @@ function url(path, query, absolute) {
   const generator = inject4(UrlGenerator2);
   return path === void 0 ? generator : generator.to(path, query, absolute);
 }
-function route(name, parameters, absolute) {
+function route(name, ...args) {
+  const [parameters, absolute] = args;
   return inject4(UrlGenerator2).route(name, parameters, absolute);
 }
 function abort(status, message = "", headers = {}) {
@@ -1183,18 +1195,41 @@ var STATUS_TEXTS = {
   403: "Forbidden",
   404: "Not Found",
   405: "Method Not Allowed",
+  406: "Not Acceptable",
+  407: "Proxy Authentication Required",
   408: "Request Timeout",
   409: "Conflict",
   410: "Gone",
+  411: "Length Required",
+  412: "Precondition Failed",
   413: "Content Too Large",
+  414: "URI Too Long",
   415: "Unsupported Media Type",
+  416: "Range Not Satisfiable",
+  417: "Expectation Failed",
+  418: "I'm a teapot",
   419: "Page Expired",
+  421: "Misdirected Request",
   422: "Unprocessable Content",
+  423: "Locked",
+  424: "Failed Dependency",
+  425: "Too Early",
+  426: "Upgrade Required",
+  428: "Precondition Required",
   429: "Too Many Requests",
+  431: "Request Header Fields Too Large",
+  451: "Unavailable For Legal Reasons",
   500: "Server Error",
+  501: "Not Implemented",
   502: "Bad Gateway",
   503: "Service Unavailable",
-  504: "Gateway Timeout"
+  504: "Gateway Timeout",
+  505: "HTTP Version Not Supported",
+  506: "Variant Also Negotiates",
+  507: "Insufficient Storage",
+  508: "Loop Detected",
+  510: "Not Extended",
+  511: "Network Authentication Required"
 };
 function statusText(status) {
   return STATUS_TEXTS[status] ?? (status >= 500 ? "Server Error" : "Error");
@@ -1370,8 +1405,7 @@ var ErrorHandler = class {
     else if (this.shouldReturnJson(http, error)) response2 = this.#renderJson(error);
     else response2 = await this.#renderHtml(http, error);
     const headers = error?.headers;
-    if (headers !== void 0) for (const [name, value] of Object.entries(headers)) response2.headers.set(name, value);
-    return response2;
+    return headers === void 0 ? response2 : withHeaders(response2, headers);
   }
   /** An error with its own render(request) or toResponse(request) (Laravel's renderable exceptions / Responsable). */
   async #renderCustom(request2, error) {
@@ -1491,6 +1525,11 @@ var ErrorHandler = class {
     return currentContainer4() ?? this.app;
   }
 };
+function withHeaders(response2, extra) {
+  const headers = new Headers(response2.headers);
+  for (const [name, value] of Object.entries(extra)) headers.set(name, value);
+  return new Response(response2.body, { status: response2.status, statusText: response2.statusText, headers });
+}
 
 // ExceptionsConfiguration.ts
 import { ExceptionCallbacks } from "@orieljs/contracts";
@@ -1579,9 +1618,9 @@ async function handleSafely(app, request2, publicPath) {
     return plainServerError();
   }
 }
-function exitOnSignals(close, closed) {
+function exitOnSignals(close, closed, app) {
   const onSignal = () => {
-    void close().then(() => process.exit(0));
+    void close().then(() => app.shutdown()).then(() => process.exit(0));
   };
   process.once("SIGINT", onSignal);
   process.once("SIGTERM", onSignal);
@@ -1625,7 +1664,7 @@ async function serveBun(app, options) {
     clearTimeout(timer);
     markClosed();
   })();
-  if (options.signals) exitOnSignals(close, closed);
+  if (options.signals) exitOnSignals(close, closed, app);
   return {
     runtime: "bun",
     hostname: options.hostname,
@@ -1763,7 +1802,7 @@ async function serveNode(app, options) {
     clearInterval(idle);
     clearTimeout(force);
   })();
-  if (options.signals) exitOnSignals(close, closed);
+  if (options.signals) exitOnSignals(close, closed, app);
   return {
     runtime: "node",
     hostname: options.hostname,
@@ -1795,12 +1834,255 @@ async function serve(app, options = {}) {
 }
 
 // commands.ts
-import { existsSync } from "fs";
+import { existsSync as existsSync3 } from "fs";
 import { mkdir, readFile as readFile2, writeFile } from "fs/promises";
 import { dirname } from "path";
 import {
   Router as Router3
 } from "@orieljs/contracts";
+
+// watch/environment.ts
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+import * as util from "util";
+var launchEnvironment = Object.freeze({ ...process.env });
+var BUN_ENV_FILES = [
+  ".env",
+  ".env.development",
+  ".env.production",
+  ".env.test",
+  ".env.local",
+  ".env.development.local",
+  ".env.production.local",
+  ".env.test.local"
+];
+var expand = (value, env) => value.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g, (_match, braced, bare) => env[braced ?? bare] ?? "");
+function serverEnvironment(options = {}) {
+  const launched = options.launched ?? launchEnvironment;
+  const env = { ...launched };
+  if (!(options.bun ?? process.versions.bun !== void 0)) return env;
+  const parseEnv2 = "parseEnv" in options ? options.parseEnv : util.parseEnv;
+  if (typeof parseEnv2 !== "function") return env;
+  const cwd = options.cwd ?? process.cwd();
+  for (const name of BUN_ENV_FILES) {
+    const file = join(cwd, name);
+    if (!existsSync(file)) continue;
+    let values;
+    try {
+      values = parseEnv2(readFileSync(file, "utf8"));
+    } catch {
+      continue;
+    }
+    for (const [key, raw] of Object.entries(values)) {
+      const value = launched[key];
+      if (raw !== void 0 && value !== void 0 && (value === raw || value === expand(raw, launched))) delete env[key];
+    }
+  }
+  return env;
+}
+
+// watch/files.ts
+import { existsSync as existsSync2, statSync, watch as watchPath } from "fs";
+import { join as join2 } from "path";
+var WATCHED_FOLDERS = ["app", "bootstrap", "config", "lang", "resources/lang", "resources/views", "routes"];
+var WATCHED_ROOT_FILES = ["package.json", "tsconfig.json"];
+var IGNORED_FOLDERS = ["bootstrap/ssr", "bootstrap/cache"];
+var CODE_FILE = /\.(?:[cm]?[jt]sx?|json)$/;
+var DECLARATION_FILE = /\.d\.[cm]?ts$/;
+var EDITOR_FILE = /(?:\.sw[a-px]|~|___jb_(?:tmp|old)___)$/;
+var isEnvironmentFile = (name) => (name === ".env" || name.startsWith(".env.")) && name !== ".env.example" && !EDITOR_FILE.test(name);
+function isWatchedPath(path) {
+  const segments = path.split("/");
+  if (segments.length === 1) return isEnvironmentFile(path) || WATCHED_ROOT_FILES.includes(path);
+  if (!WATCHED_FOLDERS.some((folder) => path.startsWith(`${folder}/`))) return false;
+  if (IGNORED_FOLDERS.some((folder) => path === folder || path.startsWith(`${folder}/`))) return false;
+  if (segments.some((segment) => segment.startsWith(".") || segment === "node_modules")) return false;
+  const name = segments.at(-1);
+  if (DECLARATION_FILE.test(name)) return false;
+  return CODE_FILE.test(name) || !name.includes(".");
+}
+var toSlashes = (file) => file.split("\\").join("/");
+function watchFiles(basePath, onChange, options = {}) {
+  const watch = options.watch ?? ((path, watchOptions, listener) => watchPath(path, watchOptions, listener));
+  const debounce = options.debounce ?? 200;
+  const onError = options.onError ?? (() => {
+  });
+  const changed = /* @__PURE__ */ new Set();
+  let timer;
+  const settle = options.settle ?? 1e3;
+  const startedAt = Date.now();
+  const reportedLate = (path) => {
+    if (Date.now() - startedAt >= settle) return false;
+    try {
+      const modified = statSync(join2(basePath, path), { throwIfNoEntry: false })?.mtimeMs;
+      return modified === void 0 || modified < startedAt + 1;
+    } catch {
+      return false;
+    }
+  };
+  const record = (path) => {
+    if (!isWatchedPath(path) || reportedLate(path)) return;
+    changed.add(path);
+    clearTimeout(timer);
+    timer = setTimeout(() => {
+      const files = [...changed];
+      changed.clear();
+      onChange(files);
+    }, debounce);
+  };
+  const handles = [];
+  const start = (folder, recursive, toPath) => {
+    try {
+      const handle = watch(folder === "." ? basePath : join2(basePath, folder), { recursive }, (_event, file) => {
+        const path = toPath(file);
+        if (path !== void 0) record(path);
+      });
+      handle.on("error", (error) => onError(folder, error));
+      handles.push(handle);
+    } catch (error) {
+      onError(folder, error);
+    }
+  };
+  start(".", false, (file) => file === null ? void 0 : toSlashes(file));
+  for (const folder of WATCHED_FOLDERS) {
+    if (existsSync2(join2(basePath, folder))) start(folder, true, (file) => `${folder}/${file === null ? "" : toSlashes(file)}`);
+  }
+  return {
+    close() {
+      clearTimeout(timer);
+      changed.clear();
+      for (const handle of handles) handle.close();
+    }
+  };
+}
+
+// watch/port.ts
+import { createServer as createServer2 } from "net";
+function claimPort(hostname, port) {
+  return new Promise((resolve2, reject) => {
+    const server = createServer2();
+    server.once("error", reject);
+    try {
+      server.listen({ port, host: hostname, exclusive: true }, () => {
+        const { port: claimed } = server.address();
+        server.close(() => resolve2(claimed));
+      });
+    } catch (error) {
+      reject(error);
+    }
+  });
+}
+var REASONS = {
+  EADDRINUSE: "Address already in use",
+  EACCES: "Permission denied",
+  EADDRNOTAVAIL: "Can't assign requested address"
+};
+function listenFailure(hostname, port, error) {
+  const { code, message } = error;
+  return `Failed to listen on ${displayHost(hostname)}:${port} (reason: ${code !== void 0 && REASONS[code] || message})`;
+}
+
+// watch/WatchedServer.ts
+import { spawn as spawnProcess } from "child_process";
+var WatchedServer = class {
+  constructor(options) {
+    this.options = options;
+  }
+  options;
+  running;
+  restarting = false;
+  stopping = false;
+  finish = () => {
+  };
+  /** Starts the server and keeps it current until stopped. Resolves 0 once the last server has exited. */
+  run() {
+    const done = new Promise((resolve2) => this.finish = resolve2);
+    const stopListening = this.listenForSignals();
+    const watcher = this.options.watch((files) => void this.changed(files));
+    this.start();
+    return done.finally(() => {
+      watcher.close();
+      stopListening();
+    });
+  }
+  /** Stops the server and ends run(); called again, kills the server at once. */
+  stop() {
+    if (this.stopping) {
+      this.running?.child.kill("SIGKILL");
+      return;
+    }
+    this.stopping = true;
+    void this.stopServer().then(() => this.finish(0));
+  }
+  async changed(files) {
+    if (this.stopping || this.restarting || files.length === 0) return;
+    this.restarting = true;
+    try {
+      this.options.info(
+        files.some(isEnvironmentFile) ? "Environment modified. Restarting server..." : `Application change detected in [${files[0]}]. Restarting server...`
+      );
+      await this.stopServer();
+      if (!this.stopping) this.start();
+    } finally {
+      this.restarting = false;
+    }
+  }
+  start() {
+    const [command, ...args] = this.options.command;
+    const child = (this.options.spawn ?? spawnProcess)(command, args, {
+      cwd: this.options.cwd,
+      env: this.options.env,
+      stdio: ["ignore", "inherit", "inherit"]
+    });
+    const running = { child, stopping: false, killed: false, exited: Promise.resolve() };
+    running.exited = new Promise((resolve2) => {
+      let settled = false;
+      const settle = (report) => {
+        if (settled) return;
+        settled = true;
+        if (this.running === running) this.running = void 0;
+        if (!running.stopping && !this.stopping) this.options.error(`${report}. Waiting for changes before restarting...`);
+        resolve2();
+      };
+      child.once("exit", (code, signal) => settle(signal !== null ? `The server stopped (signal ${signal})` : `The server stopped (exit code ${code})`));
+      child.once("error", (error) => {
+        if (child.pid === void 0) settle(`The server could not start (${error.message})`);
+      });
+    });
+    this.running = running;
+  }
+  /** Sends SIGTERM once and waits for the exit, killing the server after stopTimeout. */
+  async stopServer() {
+    const running = this.running;
+    if (running === void 0) return;
+    if (!running.stopping) {
+      running.stopping = true;
+      running.child.kill("SIGTERM");
+    }
+    const timeout = this.options.stopTimeout ?? 15e3;
+    const timer = setTimeout(() => {
+      if (running.killed) return;
+      running.killed = true;
+      this.options.error(`The server did not stop within ${timeout / 1e3} seconds and was killed.`);
+      running.child.kill("SIGKILL");
+    }, timeout);
+    try {
+      await running.exited;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  listenForSignals() {
+    const signals = this.options.signals ?? ["SIGINT", "SIGTERM", "SIGHUP"];
+    const handler = () => this.stop();
+    for (const signal of signals) process.on(signal, handler);
+    return () => {
+      for (const signal of signals) process.off(signal, handler);
+    };
+  }
+};
+
+// commands.ts
 function io(command) {
   return {
     option: (name) => {
@@ -1874,11 +2156,36 @@ ${web[1]}api: 'routes/api.ts',`);
 ${create[0]}`);
   return void 0;
 }
+async function serveWatching(app, out, port, run) {
+  const hostname = out.option("host") ?? "127.0.0.1";
+  const requested = port !== void 0 ? Number(port) : Number(process.env.PORT ?? process.env.SERVER_PORT ?? 8e3);
+  let claimed;
+  try {
+    claimed = await claimPort(hostname, requested);
+  } catch (error) {
+    out.error(listenFailure(hostname, requested, error));
+    return 1;
+  }
+  const script = process.argv[1];
+  if (script === void 0) {
+    out.error("serve --watch can't tell which script started this process, so it can't start the server.");
+    return 1;
+  }
+  return run({
+    command: [process.execPath, ...process.execArgv, script, "serve", `--host=${hostname}`, `--port=${claimed}`],
+    cwd: process.cwd(),
+    env: serverEnvironment(),
+    watch: (onChange) => watchFiles(app.basePath(), onChange, { onError: (folder, error) => out.warn(`Unable to watch [${folder}] for changes: ${error.message}`) }),
+    info: (message) => out.info(message),
+    error: (message) => out.error(message)
+  });
+}
 function registerHttpCommands(kernel, app, options = {}) {
   const serveApp = options.serve ?? serve;
   const terminalWidth = options.terminalWidth ?? (() => process.stdout.columns ?? 120);
+  const runWatching = options.watch ?? ((watchOptions) => new WatchedServer(watchOptions).run());
   kernel.command(
-    "serve {--host=127.0.0.1 : The host address to serve the application on} {--port= : The port to serve the application on}",
+    "serve {--host=127.0.0.1 : The host address to serve the application on} {--port= : The port to serve the application on} {--watch : Automatically restart the server when the application is modified}",
     async function() {
       const out = io(this);
       const port = out.option("port");
@@ -1886,6 +2193,7 @@ function registerHttpCommands(kernel, app, options = {}) {
         out.error("The --port option must be a number.");
         return 1;
       }
+      if (out.flag("watch")) return serveWatching(app, out, port, runWatching);
       const server = await serveApp(app, {
         hostname: out.option("host") ?? "127.0.0.1",
         ...port !== void 0 && { port: Number(port) },
@@ -1933,7 +2241,7 @@ function registerHttpCommands(kernel, app, options = {}) {
   kernel.command("install:api {--force : Overwrite any existing API routes file}", async function() {
     const out = io(this);
     const routesFile = app.basePath("routes/api.ts");
-    if (existsSync(routesFile) && !out.flag("force")) {
+    if (existsSync3(routesFile) && !out.flag("force")) {
       out.error("API routes file already exists.");
     } else {
       await mkdir(dirname(routesFile), { recursive: true });
@@ -1941,7 +2249,7 @@ function registerHttpCommands(kernel, app, options = {}) {
       out.info("Published API routes file.");
     }
     const bootstrapFile = app.bootstrapPath("app.ts");
-    const source = existsSync(bootstrapFile) ? await readFile2(bootstrapFile, "utf8") : void 0;
+    const source = existsSync3(bootstrapFile) ? await readFile2(bootstrapFile, "utf8") : void 0;
     const updated = source === void 0 ? void 0 : addApiRouting(source);
     if (updated === void 0) {
       out.warn(
@@ -1950,7 +2258,7 @@ function registerHttpCommands(kernel, app, options = {}) {
     } else if (updated !== source) {
       await writeFile(bootstrapFile, updated);
     }
-    out.info("API scaffolding installed. Run [oriel migrate] to create the personal access tokens table.");
+    out.info("API scaffolding installed.");
     return 0;
   }).purpose("Create an API routes file and prepare the application for API authentication");
 }