@daloyjs/core 0.12.0 → 0.13.1

package/README.md

@@ -8,6 +8,8 @@
 
 > A **runtime-portable TypeScript web framework** with built-in **contract-first routing**, **validation**, **OpenAPI (Hey API)**, **typed client generation**, **large-scale maintainability**, and **security-focused runtime plus supply-chain posture**.
 
+**One-line API docs.** `new App({ openapi: { info: ... }, docs: true })` auto-mounts `GET /docs` (Scalar), `GET /openapi.json`, and `GET /openapi.yaml` — the same DX as FastAPI, without leaving TypeScript.
+
 DaloyJS is maintained in the GitHub organization at <https://github.com/daloyjs>; the canonical framework repository is <https://github.com/daloyjs/daloy>.
 
 ---
@@ -16,7 +18,7 @@ DaloyJS exists to be the framework you'd build if you took the best ideas from e
 
 | You want                                                | Today's best-of                                       | What DaloyJS gives you                                                                                                       |
 | ------------------------------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
-| Best **OpenAPI ergonomics**                             | [FastAPI](https://fastapi.tiangolo.com)               | First-class OpenAPI 3.1 generation from a single route definition.                                                           |
+| Best **OpenAPI ergonomics**                             | [FastAPI](https://fastapi.tiangolo.com)               | First-class OpenAPI 3.1 generation from a single route definition; one-line `docs: true` auto-mounts `/docs` and `/openapi.json`.                                                           |
 | Best **Vercel / serverless / edge fit**                 | [Hono](https://hono.dev/docs/)                        | Web-standard `Request → Response` core, multi-runtime adapters.                                                              |
 | Mature **Swagger / docs / ops** in Node                 | [Fastify](https://fastify.dev/docs/latest/Reference/) | Encapsulated plugins, structured logger, graceful shutdown, request ids, hooks.                                              |
 | Modern **TS-first DX**, Bun acceptable                  | [Elysia](https://elysiajs.com/at-glance.html)         | End-to-end typed handlers, typed context, typed client.                                                                      |
@@ -182,15 +184,67 @@ const r = await client.getBookById({ params: { id: "1" } });
 
 ---
 
-## Built-in docs UI (Swagger UI / Scalar)
+## Built-in docs UI (Scalar / Swagger UI)
+
+FastAPI-style. One line on the `App` constructor mounts `GET /docs`, `GET /openapi.json`, and `GET /openapi.yaml` for you,
+with a strict CSP and CDN-hosted assets:
 
 ```ts
-import { swaggerUiHtml, htmlResponse } from "@daloyjs/core/docs";
-// returns a self-contained HTML page that loads /openapi.json
+import { App } from "@daloyjs/core";
+
+const app = new App({
+  openapi: { info: { title: "My API", version: "1.0.0" } },
+  docs: true, // mounts GET /docs (Scalar), GET /openapi.json, GET /openapi.yaml
+});
 ```
 
-Mount at `/docs` and the UI is always contract-accurate — never stale.
-`create-daloy@0.2.0` mounts Swagger UI at `/docs` and the live spec at `/openapi.json` by default.
+Use `docs: "auto"` to mount only when `production: false`, or the object form for full control:
+
+```ts
+new App({
+  openapi: { info: { title: "My API", version: "1.0.0" } },
+  docs: {
+    ui: "swagger",
+    path: "/reference",
+    openapiPath: "/spec.json",
+    openapiYamlPath: "/spec.yaml", // or `false` to disable the YAML route
+    tags: ["Docs"],
+  },
+});
+```
+
+Prefer to mount manually? Import the helpers directly:
+
+```ts
+import { swaggerUiHtml, scalarHtml, htmlResponse } from "@daloyjs/core/docs";
+import { generateOpenAPI } from "@daloyjs/core/openapi";
+```
+
+The UI is always contract-accurate — never stale. `create-daloy` templates opt in with `docs: true`.
+
+If you omit `openapi.info.title` / `info.version`, Daloy reads your project's `package.json` (`name`, `version`, `description`) automatically — no boilerplate. Deno projects without a `package.json` fall back to `deno.json` / `deno.jsonc`. Explicit values always win.
+
+Prefer a factory? `createApp(options)` is exported as an alias of `new App(options)`.
+
+```ts
+import { createApp } from "@daloyjs/core";
+
+const app = createApp({ docs: true });
+```
+
+### `daloy dev` — one-command watch mode
+
+`daloy dev [entry]` delegates to the host runtime's native watch tool, with no extra config:
+
+| Runtime | Spawned command                                                 |
+| ------- | --------------------------------------------------------------- |
+| Node    | `node --import tsx --watch <entry>`                             |
+| Bun     | `bun --hot <entry>`                                             |
+| Deno    | `deno run --watch --allow-net --allow-env --allow-read <entry>` |
+
+Entry defaults to `src/index.ts`, `src/main.ts`, `src/server.ts`, or `src/app.ts`. Install `tsx` as a dev dependency on Node for TypeScript entries.
+
+Pass `--runtime <node|bun|deno>` to override runtime detection. This is required when running `daloy dev` from a `package.json` script on Bun or Deno, because the CLI binary's `#!/usr/bin/env node` shebang otherwise forces Node detection. The `bun-basic` template ships `"dev": "daloy dev --runtime bun"` for this reason.
 
 ---
 
@@ -321,6 +375,9 @@ What works today, at a glance:
 - WebSocket primitives with the same Bun-style handler shape (`open`/`message`/`close`/`drain`/`error`) running on both Node and Bun adapters, plus typed `app.ws(path, handler)` registration and route-table awareness so the upgrade listener is only installed when WS routes exist.
 - Pretty `printStartupBanner()` / `formatStartupBanner()` startup helpers at `@daloyjs/core/banner`, used by every starter template so `pnpm dev` greets you with a colorized boxed panel (TTY + `NO_COLOR` / `FORCE_COLOR` aware, with an ASCII fallback for dumb terminals).
 - In-process test client (`app.request()`), contract-test runner, in-process typed client, and Hey API codegen via `pnpm gen`.
+- One-command watch loop: `daloy dev` delegates to the host runtime's native watcher (`node --import tsx --watch`, `bun --hot`, or `deno run --watch`) with a `--runtime` override for cross-runtime `package.json` scripts.
+- Zero-config OpenAPI `info` autofill from `package.json` (Node / Bun) or `deno.json` / `deno.jsonc` (Deno) — explicit `openapi.info` values always win.
+- Live OpenAPI 3.1 spec served as both JSON (`GET /openapi.json`) and YAML (`GET /openapi.yaml`) when `docs: true` — covers Swagger UI's `swagger.yaml` convention out of the box.
 - `pnpm create daloy` scaffolder with Node, Bun, Deno, Cloudflare Worker, and Vercel Edge templates, plus optional `--with-ci` GitHub Actions / Dependabot / CODEOWNERS / SECURITY.md hardening.
 - Plugin encapsulation, decorators, structured logging, request-id propagation, lifecycle events (`onPluginInstalled`, `onShutdown`, `onClose`), and graceful shutdown.
 - Integration guides for transactional email providers — AWS SES, SendGrid, Resend, Postmark, Mailgun, and Mailtrap — with a common `EmailSender` plugin pattern and runtime-compatibility matrix.

package/bin/daloy.mjs

@@ -10,6 +10,7 @@
 import { pathToFileURL, fileURLToPath } from "node:url";
 import { resolve, dirname } from "node:path";
 import { existsSync, readFileSync } from "node:fs";
+import { spawn } from "node:child_process";
 import { runCli } from "../dist/cli.js";
 
 const PKG = JSON.parse(
@@ -42,11 +43,46 @@ async function importEntry(specifier) {
   return import(pathToFileURL(abs).href);
 }
 
+function spawnDev(command, args) {
+  return new Promise((resolvePromise, reject) => {
+    const child = spawn(command, args, { stdio: "inherit", shell: false });
+    const forward = (sig) => {
+      try {
+        child.kill(sig);
+      } catch {
+        /* ignore */
+      }
+    };
+    process.on("SIGINT", forward);
+    process.on("SIGTERM", forward);
+    child.on("error", (err) => {
+      if (err && err.code === "ENOENT") {
+        reject(
+          new Error(
+            `\`${command}\` was not found on PATH. ` +
+              (command === "node"
+                ? "Install `tsx` as a dev dependency (`pnpm add -D tsx`) and ensure Node.js is on PATH."
+                : `Install ${command} or run daloy dev from the runtime that hosts it.`)
+          )
+        );
+        return;
+      }
+      reject(err);
+    });
+    child.on("exit", (code, signal) => {
+      process.off("SIGINT", forward);
+      process.off("SIGTERM", forward);
+      resolvePromise(signal ? 1 : (code ?? 0));
+    });
+  });
+}
+
 const result = await runCli(process.argv.slice(2), {
   stdout: (chunk) => process.stdout.write(chunk),
   stderr: (chunk) => process.stderr.write(chunk),
   importEntry,
   version: PKG.version,
+  spawn: spawnDev,
 });
 
 process.exit(result.exitCode);

package/dist/app.d.ts

@@ -1,6 +1,8 @@
 import { WebSocketRegistry, type WebSocketHandler } from "./websocket.js";
 import { type Logger } from "./logger.js";
 import type { HttpMethod, Hooks, PathString, RequestSchemas, ResponsesMap, RouteDefinition } from "./types.js";
+import { type OpenAPIInfo, type OpenAPIOptions } from "./openapi.js";
+import { type DocsContentSecurityPolicyOptions } from "./docs.js";
 /**
  * Configuration accepted by {@link App}'s constructor. Every field is
  * optional; sensible production defaults are applied.
@@ -47,6 +49,93 @@ export interface AppOptions {
     mockMode?: boolean;
     /** Global hooks applied to every route. */
     hooks?: Hooks;
+    /**
+     * OpenAPI 3.1 document metadata used by the built-in auto-mounted
+     * `/openapi.json` route and any other consumer that calls
+     * `generateOpenAPI(app)` without its own options. When `info.title` /
+     * `info.version` are omitted they fall back to the top-level
+     * {@link AppOptions.title} / {@link AppOptions.version} fields, then to
+     * `"DaloyJS API"` / `"0.0.0"`.
+     *
+     * @since 0.3.0
+     */
+    openapi?: AppOpenAPIOptions;
+    /**
+     * Enable the built-in API documentation surface — a `/openapi.json` route
+     * that serves the live OpenAPI 3.1 spec and a `/docs` route that serves a
+     * Scalar (default) or Swagger UI HTML page that loads it. This is the
+     * one-line equivalent of FastAPI's automatic `/docs` UI.
+     *
+     * - `false` (default) — never mount. Write your own with `generateOpenAPI`
+     *   + `swaggerUiHtml` / `scalarHtml` for full control.
+     * - `true` — always mount on `/openapi.json` and `/docs`.
+     * - `"auto"` — mount when `NODE_ENV !== "production"`; otherwise skip. This
+     *   is a "secure by default" choice: production deployments should opt in
+     *   explicitly so internal APIs do not accidentally publish a browsable
+     *   schema.
+     * - object — full configuration (custom paths, UI choice, title, CSP
+     *   overrides). The `enabled` field on the object can override the
+     *   auto/prod rule.
+     *
+     * The default is `false` so adding a new `App({ ... })` to an existing app
+     * never silently changes its public surface; scaffolded projects from
+     * `create-daloy` set `docs: true` for the auto-mount experience.
+     *
+     * @since 0.3.0
+     */
+    docs?: boolean | "auto" | DocsRouteOptions;
+}
+/**
+ * Subset of {@link OpenAPIOptions} accepted by `new App({ openapi })`. All
+ * fields are optional; `info.title` / `info.version` fall back to the
+ * top-level {@link AppOptions.title} / {@link AppOptions.version}.
+ *
+ * @since 0.3.0
+ */
+export interface AppOpenAPIOptions {
+    info?: Partial<OpenAPIInfo>;
+    servers?: OpenAPIOptions["servers"];
+    securitySchemes?: OpenAPIOptions["securitySchemes"];
+    webhooks?: OpenAPIOptions["webhooks"];
+}
+/**
+ * Configuration for the auto-mounted docs surface. Pass to
+ * `new App({ docs: { ... } })` to override defaults; omit to take all
+ * defaults.
+ *
+ * @since 0.3.0
+ */
+export interface DocsRouteOptions {
+    /** Path the docs UI is served from. Default `"/docs"`. */
+    path?: PathString;
+    /** Path the OpenAPI 3.1 JSON spec is served from. Default `"/openapi.json"`. */
+    openapiPath?: PathString;
+    /**
+     * Path the OpenAPI 3.1 YAML spec is served from. Default `"/openapi.yaml"`.
+     * Set to `false` to disable the YAML route.
+     *
+     * @since 0.13.1
+     */
+    openapiYamlPath?: PathString | false;
+    /** Which built-in UI to render. Default `"scalar"` (smaller payload, modern UI). */
+    ui?: "scalar" | "swagger";
+    /** Page `<title>`. Defaults to the resolved OpenAPI `info.title`. */
+    title?: string;
+    /**
+     * Force the docs to mount regardless of `NODE_ENV`. When `"auto"` (default
+     * for the object form), behaves like the top-level `docs: "auto"` setting.
+     */
+    enabled?: boolean | "auto";
+    /**
+     * Tags attached to the auto-mounted operations in the generated spec.
+     * Default: `["Docs"]`. Pass an empty array to omit tags entirely.
+     */
+    tags?: string[];
+    /**
+     * Override the Content-Security-Policy applied to the docs HTML response.
+     * Forwarded to {@link docsContentSecurityPolicy}.
+     */
+    csp?: DocsContentSecurityPolicyOptions;
 }
 /** Information passed to {@link App.onPluginInstalled} listeners. */
 export interface PluginInstalledEvent {
@@ -161,6 +250,21 @@ export declare class App {
     private inflight;
     private draining;
     constructor(options?: AppOptions);
+    /**
+     * Resolve whether the app is running in production. Honours the explicit
+     * `production` option first, then falls back to `NODE_ENV === "production"`.
+     * Used by the docs auto-mount and error response detail stripping.
+     */
+    private isProduction;
+    /**
+     * Resolve the {@link AppOptions.docs} option and, when enabled, register
+     * the `/openapi.json` + `/docs` routes. Called once during construction so
+     * the routes appear in `app.routes` for introspection and so the spec
+     * served at runtime includes every route registered afterwards (the spec
+     * is generated lazily inside the request handler).
+     */
+    private maybeMountDocs;
+    private mountDocs;
     /**
      * Register a single route on the application.
      *
@@ -386,4 +490,28 @@ export declare class App {
      */
     shutdown(timeoutMs?: number, reason?: string): Promise<void>;
 }
+/**
+ * Factory alias for `new App(options)`. Lets callers who prefer a
+ * functional style (or who avoid `new`) write:
+ *
+ * ```ts
+ * import { createApp } from "@daloyjs/core";
+ *
+ * const app = createApp({ openapi: { info: { title: "My API", version: "1.0.0" } }, docs: true });
+ * ```
+ *
+ * Behaviour is identical to `new App(options)` — the alias exists purely
+ * for ergonomics and matches the factory pattern used by Express, Fastify,
+ * and Hono adapters.
+ *
+ * @since 0.3.0
+ */
+export declare function createApp(options?: AppOptions): App;
+/**
+ * Test helper: clear the cached package.json read so each test starts
+ * from a fresh lookup. Not part of the public API.
+ *
+ * @internal
+ */
+export declare function _resetPackageJsonCacheForTests(): void;
 //# sourceMappingURL=app.d.ts.map

package/dist/app.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"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"}

package/dist/app.js

@@ -4,6 +4,8 @@ import { BadRequestError, HttpError, InternalError, MethodNotAllowedError, NotFo
 import { validate } from "./schema.js";
 import { readBodyLimited, safeJsonParse, randomId } from "./security.js";
 import { createLogger, noopLogger } from "./logger.js";
+import { generateOpenAPI, openapiToYAML, } from "./openapi.js";
+import { docsContentSecurityPolicy, scalarHtml, swaggerUiHtml, } from "./docs.js";
 const DEFAULTS = {
     bodyLimitBytes: 1024 * 1024,
     requestTimeoutMs: 30_000,
@@ -96,6 +98,144 @@ export class App {
                     typeof options.logger.info === "function"
                     ? options.logger
                     : createLogger({ level: options.logger?.level ?? "info" });
+        this.maybeMountDocs();
+    }
+    /**
+     * Resolve whether the app is running in production. Honours the explicit
+     * `production` option first, then falls back to `NODE_ENV === "production"`.
+     * Used by the docs auto-mount and error response detail stripping.
+     */
+    isProduction() {
+        if (this.options.production !== undefined)
+            return this.options.production;
+        return (typeof process !== "undefined" &&
+            typeof process.env !== "undefined" &&
+            process.env.NODE_ENV === "production");
+    }
+    /**
+     * Resolve the {@link AppOptions.docs} option and, when enabled, register
+     * the `/openapi.json` + `/docs` routes. Called once during construction so
+     * the routes appear in `app.routes` for introspection and so the spec
+     * served at runtime includes every route registered afterwards (the spec
+     * is generated lazily inside the request handler).
+     */
+    maybeMountDocs() {
+        const raw = this.options.docs;
+        if (raw === undefined || raw === false)
+            return;
+        let resolvedOpts;
+        if (raw === true) {
+            resolvedOpts = {};
+        }
+        else if (raw === "auto") {
+            if (this.isProduction())
+                return;
+            resolvedOpts = {};
+        }
+        else {
+            // object form
+            const enabled = raw.enabled ?? true;
+            if (enabled === false)
+                return;
+            if (enabled === "auto" && this.isProduction())
+                return;
+            resolvedOpts = raw;
+        }
+        this.mountDocs(resolvedOpts);
+    }
+    mountDocs(opts) {
+        const openapiPath = (opts.openapiPath ?? "/openapi.json");
+        const openapiYamlPath = opts.openapiYamlPath === false
+            ? null
+            : (opts.openapiYamlPath ?? "/openapi.yaml");
+        const docsPath = (opts.path ?? "/docs");
+        const ui = opts.ui ?? "scalar";
+        const tags = opts.tags ?? ["Docs"];
+        // Best-effort lazy read of the host project's package.json so that
+        // `new App({ docs: true })` with no explicit `openapi.info` still produces
+        // a spec titled after the user's package (`name` → title,
+        // `version` → version, `description` → description). Silently skipped on
+        // edge runtimes that lack `node:fs`.
+        const resolveInfo = async () => {
+            const fromOpenapi = this.options.openapi?.info ?? {};
+            const fromPkg = await readHostPackageJsonInfo();
+            const title = fromOpenapi.title ?? this.options.title ?? fromPkg.title ?? "DaloyJS API";
+            const version = fromOpenapi.version ?? this.options.version ?? fromPkg.version ?? "0.0.0";
+            const description = fromOpenapi.description ?? this.options.description ?? fromPkg.description;
+            return description ? { title, version, description } : { title, version };
+        };
+        const generate = async () => generateOpenAPI(this, {
+            info: await resolveInfo(),
+            ...(this.options.openapi?.servers
+                ? { servers: this.options.openapi.servers }
+                : {}),
+            ...(this.options.openapi?.securitySchemes
+                ? { securitySchemes: this.options.openapi.securitySchemes }
+                : {}),
+            ...(this.options.openapi?.webhooks
+                ? { webhooks: this.options.openapi.webhooks }
+                : {}),
+        });
+        this.route({
+            method: "GET",
+            path: openapiPath,
+            operationId: "getOpenAPIDocument",
+            ...(tags.length ? { tags } : {}),
+            summary: "OpenAPI 3.1 document",
+            responses: {
+                200: { description: "OpenAPI 3.1 document for this application." },
+            },
+            handler: async () => ({
+                status: 200,
+                body: await generate(),
+            }),
+        });
+        if (openapiYamlPath) {
+            this.route({
+                method: "GET",
+                path: openapiYamlPath,
+                operationId: "getOpenAPIDocumentYaml",
+                ...(tags.length ? { tags } : {}),
+                summary: "OpenAPI 3.1 document (YAML)",
+                responses: {
+                    200: { description: "OpenAPI 3.1 document for this application, in YAML." },
+                },
+                handler: async () => ({
+                    status: 200,
+                    body: openapiToYAML(await generate()),
+                    headers: {
+                        "content-type": "application/yaml; charset=utf-8",
+                        "x-content-type-options": "nosniff",
+                    },
+                }),
+            });
+        }
+        this.route({
+            method: "GET",
+            path: docsPath,
+            operationId: "getDocsUI",
+            ...(tags.length ? { tags } : {}),
+            summary: "Interactive API reference",
+            responses: {
+                200: { description: "Interactive API documentation UI." },
+            },
+            handler: async () => {
+                const title = opts.title ?? (await resolveInfo()).title;
+                const html = ui === "swagger"
+                    ? swaggerUiHtml({ specUrl: openapiPath, title })
+                    : scalarHtml({ specUrl: openapiPath, title });
+                return {
+                    status: 200,
+                    body: html,
+                    headers: {
+                        "content-type": "text/html; charset=utf-8",
+                        "content-security-policy": docsContentSecurityPolicy(opts.csp),
+                        "x-content-type-options": "nosniff",
+                        "referrer-policy": "no-referrer",
+                    },
+                };
+            },
+        });
     }
     // ---------- registration ----------
     /**
@@ -172,7 +312,10 @@ export class App {
      * @returns This `App` instance for chaining.
      */
     group(prefix, config, register) {
-        const child = new App(this.options);
+        // Child apps share the parent's router/routes/etc. Disable docs auto-mount
+        // on the child so it does not re-register the parent's `/openapi.json` and
+        // `/docs` routes (which would throw "Duplicate route").
+        const child = new App({ ...this.options, docs: false });
         child.router = this.router;
         child.routes = this.routes;
         child.webSocketRoutes = this.webSocketRoutes;
@@ -884,4 +1027,125 @@ function serializeErr(err) {
     }
     return { value: String(err) };
 }
+/**
+ * Factory alias for `new App(options)`. Lets callers who prefer a
+ * functional style (or who avoid `new`) write:
+ *
+ * ```ts
+ * import { createApp } from "@daloyjs/core";
+ *
+ * const app = createApp({ openapi: { info: { title: "My API", version: "1.0.0" } }, docs: true });
+ * ```
+ *
+ * Behaviour is identical to `new App(options)` — the alias exists purely
+ * for ergonomics and matches the factory pattern used by Express, Fastify,
+ * and Hono adapters.
+ *
+ * @since 0.3.0
+ */
+export function createApp(options = {}) {
+    return new App(options);
+}
+const PACKAGE_JSON_CACHE = {};
+/**
+ * Best-effort lazy read of the host project's `package.json` so that
+ * `new App({ docs: true })` with no explicit `openapi.info` still produces
+ * a spec titled after the user's package. Reads `package.json` first; if
+ * none is found while walking up from `process.cwd()`, falls back to
+ * `deno.json` / `deno.jsonc` so Deno projects get the same DX without a
+ * `package.json`. Returns an empty object on edge runtimes (Cloudflare
+ * Workers, Vercel Edge) where `node:fs` is absent, on any I/O or parse
+ * error, and when nothing is found.
+ *
+ * The result is memoized at module scope: manifests do not change
+ * during a process lifetime and we never want this to add latency to
+ * subsequent docs requests.
+ */
+function readHostPackageJsonInfo() {
+    if (PACKAGE_JSON_CACHE.value !== undefined)
+        return PACKAGE_JSON_CACHE.value;
+    const promise = (async () => {
+        const empty = {};
+        const proc = globalThis.process;
+        if (!proc || typeof proc.cwd !== "function")
+            return empty;
+        let fs;
+        let path;
+        try {
+            fs = await import("node:fs");
+            path = await import("node:path");
+        }
+        catch {
+            return empty;
+        }
+        let dir;
+        try {
+            dir = proc.cwd();
+        }
+        catch {
+            return empty;
+        }
+        const parseManifest = (raw, allowComments) => {
+            // deno.jsonc allows // line comments and /* block */ comments. Strip
+            // them before parsing — naively, but well enough for typical manifests.
+            const text = allowComments
+                ? raw
+                    .replace(/\/\*[\s\S]*?\*\//g, "")
+                    .replace(/(^|[^:\\])\/\/.*$/gm, "$1")
+                : raw;
+            return JSON.parse(text);
+        };
+        const extractInfo = (json) => {
+            const result = {};
+            if (typeof json.name === "string" && json.name.length > 0) {
+                result.title = json.name;
+            }
+            if (typeof json.version === "string" && json.version.length > 0) {
+                result.version = json.version;
+            }
+            if (typeof json.description === "string" && json.description.length > 0) {
+                result.description = json.description;
+            }
+            return result;
+        };
+        // Walk up to the filesystem root looking for a manifest. Cap depth so
+        // a deeply-nested cwd can't cause excessive stat calls. At each level,
+        // prefer package.json, then deno.json, then deno.jsonc.
+        for (let i = 0; i < 12; i++) {
+            const pkg = path.join(dir, "package.json");
+            const denoJson = path.join(dir, "deno.json");
+            const denoJsonc = path.join(dir, "deno.jsonc");
+            try {
+                if (fs.existsSync(pkg)) {
+                    return extractInfo(parseManifest(fs.readFileSync(pkg, "utf8"), false));
+                }
+                if (fs.existsSync(denoJson)) {
+                    return extractInfo(parseManifest(fs.readFileSync(denoJson, "utf8"), false));
+                }
+                if (fs.existsSync(denoJsonc)) {
+                    return extractInfo(parseManifest(fs.readFileSync(denoJsonc, "utf8"), true));
+                }
+            }
+            catch {
+                return empty;
+            }
+            const parent = path.dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+        return empty;
+    })();
+    PACKAGE_JSON_CACHE.value = promise;
+    return promise;
+}
+/**
+ * Test helper: clear the cached package.json read so each test starts
+ * from a fresh lookup. Not part of the public API.
+ *
+ * @internal
+ */
+export function _resetPackageJsonCacheForTests() {
+    PACKAGE_JSON_CACHE.value = undefined;
+}
 //# sourceMappingURL=app.js.map