@senrijs/senri 0.0.0-stage → 0.2.0

package/dist/src/dev/dashboard/record.js

@@ -0,0 +1,50 @@
+import { buildErrorPageData } from "../error-page.js";
+import { maskHeaders, maskQuery } from "./mask.js";
+function requestPath(c) {
+    let query = "";
+    try {
+        // ?token=... のような機密値は伏せる
+        query = maskQuery(new URL(c.req.url).search);
+    }
+    catch {
+        // URL として読めなくても記録はする
+    }
+    try {
+        return { path: c.path, query };
+    }
+    catch {
+        // デコードできないパス(400)は、届いたままのものを出す
+        return { path: c.req.url, query };
+    }
+}
+export async function buildRecord(input) {
+    const { id, time, c, res, layerNames } = input;
+    // タイムラインの 0 は、いちばん外側の層に入った時刻にする
+    // (c.timings の start は app.fetch の開始が基準で、ルートのマッチなど、層に入る前の準備の分だけずれている。
+    //  全体の時間 durationMs はいちばん外側の層の total なので、基準をそろえないと棒がはみ出す)
+    const base = c.timings[0]?.start ?? 0;
+    const layers = layerNames.map(({ name, order }, depth) => {
+        const t = c.timings[depth];
+        // 計測がない = そこまで届かなかった
+        if (!t)
+            return { name, order, depth, start: 0, total: 0, self: 0, state: "skipped" };
+        const state = t.failed ? "failed" : t.stopped ? "stopped" : "ok";
+        return { name, order, depth, start: t.start - base, total: t.total, self: t.self, state };
+    });
+    // 5xx で、例外が残っていれば(意図した 4xx の HttpError は c.error に入らない)、エラーページと同じ中身を取っておく
+    const error = res.status >= 500 && c.error !== undefined ? await buildErrorPageData(c.error, c, res) : null;
+    return {
+        id,
+        time,
+        method: c.req.method,
+        ...requestPath(c),
+        route: c.route ?? null,
+        params: c.params,
+        status: res.status,
+        durationMs: c.timings[0]?.total ?? 0,
+        layers,
+        requestHeaders: maskHeaders(c.req.headers),
+        responseHeaders: maskHeaders(res.headers),
+        error,
+    };
+}

package/dist/src/dev/dashboard/routes.d.ts

@@ -0,0 +1,7 @@
+import type { DashboardPageData, RequestSummary } from "../page-data.ts";
+import type { Dashboard } from "./index.ts";
+import type { DashboardRecord } from "./record.ts";
+export declare function summarize(r: DashboardRecord): RequestSummary;
+export declare function applies(prefix: string[] | null, route: string[]): "yes" | "no" | "maybe";
+export declare function pageData(d: Dashboard): DashboardPageData;
+export declare function handleDashboard(d: Dashboard, req: Request, segments: readonly string[], events: (req: Request) => Response): Promise<Response>;

package/dist/src/dev/dashboard/routes.js

@@ -0,0 +1,121 @@
+// /_senri 以下へのリクエストを処理する(ページ、JSON の API、SSE、クリア)
+// 利用者のミドルウェアは通さず、記録もしない(app.ts が先にここへ回す)
+import { splitPattern } from "../../router.js";
+import { errorFallback } from "../fallback.js";
+import { PAGE_HTML } from "../page.generated.js";
+import { renderPage } from "../render.js";
+import { sameOrigin } from "./access.js";
+const json = (data, status = 200) => new Response(JSON.stringify(data), {
+    status,
+    headers: { "content-type": "application/json; charset=utf-8", "cache-control": "no-store" },
+});
+const html = (body) => new Response(body, { headers: { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" } });
+const notFound = () => json({ error: "not found" }, 404);
+export function summarize(r) {
+    return {
+        id: r.id,
+        time: r.time,
+        method: r.method,
+        path: r.path,
+        status: r.status,
+        durationMs: r.durationMs,
+        hasError: r.error !== null,
+    };
+}
+// パス指定のミドルウェア(prefix)が、ルートのパターンにかかるか
+// セグメントごとに比べ、ルートのほうがパラメーター(":id")なら「パスによる」
+export function applies(prefix, route) {
+    if (prefix === null)
+        return "yes";
+    if (route.length < prefix.length)
+        return "no";
+    let maybe = false;
+    for (let i = 0; i < prefix.length; i++) {
+        if (route[i].startsWith(":"))
+            maybe = true;
+        else if (route[i] !== prefix[i])
+            return "no";
+    }
+    return maybe ? "maybe" : "yes";
+}
+function routeRows(d) {
+    const middlewares = d.source.middlewares();
+    return d.source.routes().map((r) => {
+        const segments = splitPattern(r.path);
+        return {
+            method: r.method,
+            path: r.path,
+            middlewares: middlewares.map((m) => ({
+                name: m.name,
+                applies: applies(m.path === null ? null : splitPattern(m.path), segments),
+            })),
+        };
+    });
+}
+function middlewareRows(d) {
+    const records = d.log.list();
+    return d.source.middlewares().map((m, i) => {
+        // 名前ではなく登録順(order)で数える(同じ名前のミドルウェアが2つあっても、別々に集計される)
+        const order = i + 1;
+        const selfs = records.flatMap((r) => r.layers.filter((l) => l.order === order && l.state !== "skipped").map((l) => l.self));
+        return {
+            order,
+            name: m.name,
+            anonymous: m.anonymous,
+            path: m.path,
+            runs: selfs.length,
+            avgSelfMs: selfs.length === 0 ? null : selfs.reduce((a, b) => a + b, 0) / selfs.length,
+        };
+    });
+}
+export function pageData(d) {
+    return {
+        kind: "dashboard",
+        max: d.log.max,
+        requests: d.log.list().map(summarize),
+        routes: routeRows(d),
+        middlewares: middlewareRows(d),
+    };
+}
+// segments: c.segments の "_senri" より後ろ(["api", "requests", "12"] など)
+export async function handleDashboard(d, req, segments, events) {
+    const [first, second, id, sub] = segments;
+    const method = req.method;
+    // ページ本体
+    if (segments.length === 0) {
+        return method === "GET" || method === "HEAD" ? html(renderPage(PAGE_HTML, pageData(d))) : notFound();
+    }
+    if (first !== "api")
+        return notFound();
+    if (second === "clear" && segments.length === 2) {
+        if (method !== "POST")
+            return notFound();
+        // ほかのサイトのページから、こっそり POST させられないように
+        if (!sameOrigin(req))
+            return json({ error: "forbidden" }, 403);
+        d.log.clear();
+        return new Response(null, { status: 204 });
+    }
+    if (method !== "GET")
+        return notFound();
+    if (second === "events" && segments.length === 2)
+        return events(req);
+    if (second === "routes" && segments.length === 2)
+        return json(routeRows(d));
+    if (second === "middleware" && segments.length === 2)
+        return json(middlewareRows(d));
+    if (second === "requests") {
+        if (segments.length === 2)
+            return json(d.log.list().map(summarize));
+        const record = id === undefined ? undefined : d.log.get(id);
+        if (!record)
+            return notFound();
+        if (segments.length === 3)
+            return json(record);
+        // 500 のときのエラーページ(記録しておいた中身から作り直す)
+        if (sub === "error" && segments.length === 4 && record.error) {
+            return html(renderPage(PAGE_HTML, record.error, errorFallback(record.error)));
+        }
+    }
+    return notFound();
+}

package/dist/src/dev/dashboard/sse.d.ts

@@ -0,0 +1,7 @@
+import type { RequestLog } from "./log.ts";
+import type { DashboardRecord } from "./record.ts";
+export type EventStreamOptions = {
+    heartbeatMs?: number;
+    maxQueued?: number;
+};
+export declare function eventStream(log: RequestLog<DashboardRecord>, req: Request, options?: EventStreamOptions): Response;

package/dist/src/dev/dashboard/sse.js

@@ -0,0 +1,73 @@
+import { summarize } from "./routes.js";
+export function eventStream(log, req, options = {}) {
+    const encoder = new TextEncoder();
+    const heartbeatMs = options.heartbeatMs ?? 5000;
+    const maxQueued = options.maxQueued ?? 32;
+    let closed = false;
+    let cleanup = () => { };
+    const stream = new ReadableStream({
+        start(controller) {
+            const send = (text) => {
+                if (closed)
+                    return;
+                // desiredSize は「あと何件ためられるか」。0 以下なら、読まれないまま上限までたまっている
+                if (controller.desiredSize !== null && controller.desiredSize <= 0) {
+                    cleanup();
+                    return;
+                }
+                try {
+                    controller.enqueue(encoder.encode(text));
+                }
+                catch {
+                    // もう閉じていて書けない(クライアントが切れた)
+                    cleanup();
+                }
+            };
+            const unsubscribe = log.subscribe((event) => {
+                if (event.type === "request") {
+                    // JSON.stringify は改行をエスケープするので、data は必ず1行になる
+                    send(`event: request\ndata: ${JSON.stringify(summarize(event.item))}\n\n`);
+                }
+                else {
+                    send("event: clear\ndata: {}\n\n");
+                }
+            });
+            const timer = setInterval(() => send(": ping\n\n"), heartbeatMs);
+            // テストなどで、この ping のせいでプロセスが終われなくならないように(Node / Bun)
+            timer.unref?.();
+            const onAbort = () => cleanup();
+            // 後片付けは、接続が切れたとき(req.signal)と、読む側がやめたとき(cancel)のどちらからでも1回だけ
+            cleanup = () => {
+                if (closed)
+                    return;
+                closed = true;
+                unsubscribe();
+                clearInterval(timer);
+                req.signal.removeEventListener("abort", onAbort);
+                try {
+                    controller.close();
+                }
+                catch {
+                    // すでに閉じている
+                }
+            };
+            if (req.signal.aborted) {
+                cleanup();
+                return;
+            }
+            req.signal.addEventListener("abort", onAbort, { once: true });
+            send(`retry: 2000\n\n`);
+        },
+        cancel() {
+            cleanup();
+        },
+    }, new CountQueuingStrategy({ highWaterMark: maxQueued }));
+    return new Response(stream, {
+        headers: {
+            "content-type": "text/event-stream; charset=utf-8",
+            "cache-control": "no-store",
+            // 間にプロキシ(nginx など)があっても、ためずにすぐ流してもらう
+            "x-accel-buffering": "no",
+        },
+    });
+}

package/dist/src/dev/editor-url.d.ts

@@ -0,0 +1,14 @@
+export type EditorId = "vscode" | "cursor" | "webstorm" | "zed" | "copy";
+export declare const EDITORS: {
+    id: EditorId;
+    label: string;
+    experimental?: boolean;
+}[];
+export type Location = {
+    file: string;
+    line: number;
+    col: number;
+    root: string | null;
+};
+export declare function editorUrl(editor: EditorId, loc: Location): string | null;
+export declare function copyText({ file, line, col }: Location): string;

package/dist/src/dev/editor-url.js

@@ -0,0 +1,61 @@
+// エディタでファイルを開く URL を作る。サーバーでもブラウザ(エラーページ)でも使うので、
+// ランタイムに頼らない純粋な関数だけを置く
+//
+// 確かめた形式(2026-10):
+// - VS Code: vscode://file/<絶対パス>:行:列
+// - Cursor:  cursor://file/<絶対パス>:行:列 (VS Code と同じ形。公式ドキュメントはなく、コミュニティの情報)
+// - Zed:     zed://file/<絶対パス>:行:列    (Zed のソース open_listener.rs で確認)
+// - WebStorm: jetbrains://web-storm/navigate/reference?project=<名前>&path=<相対パス>:行:列
+//            JetBrains Toolbox が必要で、公式ドキュメントはない(実験的)
+export const EDITORS = [
+    { id: "vscode", label: "VS Code" },
+    { id: "cursor", label: "Cursor" },
+    { id: "webstorm", label: "WebStorm", experimental: true },
+    { id: "zed", label: "Zed" },
+    { id: "copy", label: "コピーのみ" },
+];
+// 1つずつのフォルダ名をエンコードする("#" や "?" が URL の区切りと間違えられないように)
+// Windows のドライブ "C:" の ":" はそのまま残す("/C:/..." と分けると2番目に来る)
+function encodePath(path) {
+    return path
+        .split("/")
+        .map((part, i) => (i <= 1 && /^[A-Za-z]:$/.test(part) ? part : encodeURIComponent(part)))
+        .join("/");
+}
+function fileUrl(scheme, { file, line, col }) {
+    // POSIX は "/home/..." なのでそのまま、Windows は "C:/..." なので "/" を足す
+    const path = file.startsWith("/") ? file : `/${file}`;
+    return `${scheme}://file${encodePath(path)}:${line}:${col}`;
+}
+function relativeTo(file, root) {
+    const fold = (p) => (/^[A-Za-z]:\//.test(p) ? p.toLowerCase() : p);
+    const r = root.replace(/\/$/, "");
+    if (!fold(file).startsWith(`${fold(r)}/`))
+        return null;
+    return file.slice(r.length + 1);
+}
+export function editorUrl(editor, loc) {
+    switch (editor) {
+        case "vscode":
+        case "cursor":
+        case "zed":
+            return fileUrl(editor, loc);
+        case "webstorm": {
+            // Toolbox の形式は「プロジェクト名 + その中の相対パス」で指定する
+            if (!loc.root)
+                return null;
+            const rel = relativeTo(loc.file, loc.root);
+            if (rel === null)
+                return null;
+            const project = loc.root.replace(/\/$/, "").split("/").at(-1);
+            return (`jetbrains://web-storm/navigate/reference?project=${encodeURIComponent(project)}` +
+                `&path=${encodePath(rel)}:${loc.line}:${loc.col}`);
+        }
+        case "copy":
+            return null;
+    }
+}
+// コピーボタンで入れる文字列。多くのエディタの「ファイルを開く」にそのまま貼れる
+export function copyText({ file, line, col }) {
+    return `${file}:${line}:${col}`;
+}

package/dist/src/dev/editor.d.ts

@@ -0,0 +1,6 @@
+import type { EditorId } from "./editor-url.ts";
+export type EditorGuess = {
+    id: EditorId;
+    detected: boolean;
+};
+export declare function guessEditor(env?: (name: string) => string | undefined): EditorGuess;

package/dist/src/dev/editor.js

@@ -0,0 +1,14 @@
+import * as runtime from "../runtime.js";
+export function guessEditor(env = runtime.env) {
+    // Cursor は TERM_PROGRAM=vscode も付くので、先に見る
+    if (env("CURSOR_TRACE_ID"))
+        return { id: "cursor", detected: true };
+    const termProgram = env("TERM_PROGRAM");
+    if (termProgram === "vscode")
+        return { id: "vscode", detected: true };
+    if (termProgram === "zed" || env("ZED_TERM") === "true")
+        return { id: "zed", detected: true };
+    if (env("TERMINAL_EMULATOR") === "JetBrains-JediTerm")
+        return { id: "webstorm", detected: true };
+    return { id: "vscode", detected: false };
+}

package/dist/src/dev/error-page.d.ts

@@ -0,0 +1,3 @@
+import type { Context } from "../context.ts";
+import type { ErrorPageData } from "./page-data.ts";
+export declare function buildErrorPageData(err: unknown, c: Context, res: Response): Promise<ErrorPageData>;

package/dist/src/dev/error-page.js

@@ -0,0 +1,69 @@
+import { conversionOriginOf, HttpError } from "../errors.js";
+import { guessEditor } from "./editor.js";
+import { hintFor } from "./hints.js";
+import * as runtime from "../runtime.js";
+import { dashboardLinkOf } from "./dashboard/links.js";
+import { readCodeFrame } from "./source.js";
+import { parseStack } from "./stack.js";
+// Bun などは statusText が空のことがあるので、よく使うものだけ用意しておく
+const STATUS_TEXT = {
+    500: "Internal Server Error",
+    501: "Not Implemented",
+    502: "Bad Gateway",
+    503: "Service Unavailable",
+    504: "Gateway Timeout",
+};
+// 本番(dev: false)で、このエラーのときに返る本文(errors.ts の defaultOnError と同じ考え方)
+function productionText(err) {
+    return err instanceof HttpError ? err.message : "500 Internal Server Error";
+}
+function toPageFrame(frame, root) {
+    const prefix = root ? `${root.replace(/\/$/, "")}/` : null;
+    const fold = (p) => (/^[A-Za-z]:\//.test(p) ? p.toLowerCase() : p);
+    const display = prefix && fold(frame.file).startsWith(fold(prefix)) ? frame.file.slice(prefix.length) : frame.file;
+    return { ...frame, display };
+}
+function requestPath(c) {
+    try {
+        return c.path;
+    }
+    catch {
+        // デコードできないパス(400)でも、ページは出せるように
+        return c.req.url;
+    }
+}
+export async function buildErrorPageData(err, c, res) {
+    const root = runtime.cwd();
+    const error = err instanceof Error ? { name: err.name, message: err.message } : { name: "throw", message: String(err) };
+    const stack = err instanceof Error && typeof err.stack === "string" ? parseStack(err.stack) : [];
+    const frames = stack.map((f) => toPageFrame(f, root));
+    // 返した値をレスポンスにする途中で失敗したときは、スタックの利用者のコードは
+    // 「返した場所」ではなく外側のミドルウェアの `await next()` なので、場所としては出さない
+    const origin = conversionOriginOf(err);
+    const first = origin ? null : (stack.find((f) => f.kind === "user") ?? null);
+    return {
+        kind: "error",
+        status: res.status,
+        statusText: res.statusText || STATUS_TEXT[res.status] || "",
+        // いちばん外側の層の total が、リクエスト全体の時間
+        durationMs: c.timings[0]?.total ?? null,
+        error,
+        origin,
+        location: first ? toPageFrame(first, root) : null,
+        code: first ? await readCodeFrame(first, { root }) : null,
+        hint: hintFor(err, stack),
+        frames,
+        request: {
+            method: c.req.method,
+            path: requestPath(c),
+            route: c.route ?? null,
+            params: c.params,
+            userAgent: c.req.headers.get("user-agent"),
+        },
+        layers: c.timings.map((t) => ({ name: t.name, self: t.self, total: t.total, failed: t.failed })),
+        editor: guessEditor(),
+        root,
+        production: productionText(err),
+        dashboardUrl: dashboardLinkOf(c),
+    };
+}

package/dist/src/dev/explain.d.ts

@@ -0,0 +1,2 @@
+export declare function explainText(err: unknown): string | null;
+export declare function explain(err: unknown): unknown;

package/dist/src/dev/explain.js

@@ -0,0 +1,37 @@
+// 本体が投げるエラー(短い英語 + code)に、開発モードで日本語の説明を付ける
+// 本体を小さくするため、長い説明はこちらに置いている(src/errors.ts の senriError)
+import { errorCode } from "../errors.js";
+const JA = {
+    route_duplicate: "同じメソッド・同じ形のパスが、すでに登録されています(パラメーター名だけが違うものも同じとみなします)。あとから登録したほうは呼ばれません",
+    param_empty: "パラメーター名が空です(\":\" のあとに名前を書いてください)",
+    param_twice: "1つのパスで、同じパラメーター名が2回使われています",
+    method_invalid: "メソッド名に使えない文字があります",
+    method_unsupported: "CONNECT / TRACE / TRACK は扱いません(登録できません)",
+    no_handler: "ハンドラーがありません。app.get(path, { params, query, body }, handler) のように、スキーマのあとにハンドラーを渡してください",
+    no_middleware: "ミドルウェアがありません",
+    no_method: "メソッドがありません",
+    on_all: "すべてのメソッドで動かすには app.all() を使ってください",
+    route_key: "ルートの書き方が違います。\"GET /hello\" のように、メソッドとパスの間にスペースを入れてください",
+    not_app: "app.route(prefix, app) には createApp() で作ったアプリを渡してください",
+    not_router: "createRouter() で作ったルーターを渡してください",
+    router_cycle: "ルーターが自分自身を含んでいます",
+    cookie_name: "Cookie の名前に使えない文字があります",
+    no_valid: "c.valid() で読めるのは、ルートに { query } や { body } のスキーマを渡したものだけです",
+    no_execution_ctx: "c.executionCtx は Cloudflare Workers で、app.fetch(req, env, ctx) として呼ばれたときだけ使えます",
+    returned_function: "ハンドラーが関数を返しました。呼び出し忘れではありませんか？",
+    returned_nothing: "ハンドラーが何も返していません(undefined / null)",
+    next_twice: "next() が2回呼ばれました。1つのミドルウェアで呼べるのは1回だけです",
+    no_response: "ミドルウェアが何も返さず、next() も呼んでいません",
+};
+// 日本語の説明(なければ null)
+export function explainText(err) {
+    const code = errorCode(err);
+    return code ? (JA[code] ?? null) : null;
+}
+// エラーの message の前に、日本語の説明を付ける(code や種類はそのまま)
+export function explain(err) {
+    const ja = explainText(err);
+    if (ja && err instanceof Error && !err.message.startsWith(ja))
+        err.message = `${ja}\n${err.message}`;
+    return err;
+}

package/dist/src/dev/fallback.d.ts

@@ -0,0 +1,3 @@
+import type { ErrorPageData, NotFoundPageData } from "./page-data.ts";
+export declare function errorFallback(d: ErrorPageData): string;
+export declare function notFoundFallback(d: NotFoundPageData): string;

package/dist/src/dev/fallback.js

@@ -0,0 +1,40 @@
+// スクリプトが動かないときに見える、最低限の HTML
+//
+// ページは Vue(インラインのスクリプト)で描画するので、利用者のミドルウェアが
+// Content-Security-Policy を付けていると、スクリプトが止められて真っ白になってしまう。
+// そこで <div id="app"> の中に、サーバー側で作った簡易表示を最初から入れておく。
+// Vue が動けば丸ごと置き換わり、止められればこれがそのまま見える
+// (中身は全部 escapeHtml を通す。エラーメッセージやパスは攻撃者が決められるので)
+import { escapeHtml } from "./html.js";
+import { originText } from "./messages.js";
+const NOTICE = "このページの詳しい表示には JavaScript が必要です。Content-Security-Policy などでスクリプトが止められているときは、この簡易表示になります。";
+export function errorFallback(d) {
+    const where = d.origin
+        ? originText(d.origin)
+        : d.location
+            ? `${d.location.display}:${d.location.line}:${d.location.col}`
+            : null;
+    const frames = d.frames
+        .filter((f) => f.kind !== "senri" && f.kind !== "runtime")
+        .map((f) => `${f.fn}  ${f.display}:${f.line}:${f.col}`)
+        .join("\n");
+    return [
+        "<main>",
+        `<p>${escapeHtml(`${d.request.method} ${d.request.path} · ${d.status} ${d.statusText}`)}</p>`,
+        `<h1>${escapeHtml(`${d.error.name}: ${d.error.message}`)}</h1>`,
+        where ? `<p>--&gt; ${escapeHtml(where)}</p>` : "",
+        frames ? `<pre>${escapeHtml(frames)}</pre>` : "",
+        `<p>${escapeHtml(NOTICE)}</p>`,
+        "</main>",
+    ].join("");
+}
+export function notFoundFallback(d) {
+    return [
+        "<main>",
+        "<p>404 Not Found</p>",
+        `<h1>${escapeHtml(`${d.method} ${d.path}`)} は見つかりませんでした</h1>`,
+        d.suggestion ? `<p>もしかして: ${escapeHtml(`${d.suggestion.method} ${d.suggestion.path}`)}</p>` : "",
+        `<p>${escapeHtml(NOTICE)}</p>`,
+        "</main>",
+    ].join("");
+}

package/dist/src/dev/hints.d.ts

@@ -0,0 +1,6 @@
+import type { StackFrame } from "./stack.ts";
+export type Hint = {
+    text: string;
+    code?: string;
+};
+export declare function hintFor(err: unknown, frames?: StackFrame[]): Hint | null;

package/dist/src/dev/hints.js

@@ -0,0 +1,85 @@
+// よくあるエラーに、直し方のヒントを付ける(ルールベース。当てはまらなければ何も出さない)
+// エラーメッセージの書き方はランタイムで違う(Bun と、V8 の Node / Deno)ので、両方を見る
+import { errorCode } from "../errors.js";
+// 利用者のコードが投げたエラーか(ランタイム内部のフレームは飛ばして、いちばん上を見る)
+// スタックが分からなければ、利用者のものとして扱う
+function thrownByUser(frames) {
+    const top = frames?.find((f) => f.kind !== "runtime");
+    return top === undefined || top.kind === "user";
+}
+// プロパティ名を取り出す
+// V8:  Cannot read properties of undefined (reading 'name')
+// Bun: undefined is not an object (evaluating 'user.name')
+function propertyOfNothing(message) {
+    const v8 = /^Cannot read properties of (?:undefined|null) \(reading '([^']+)'\)/.exec(message);
+    if (v8)
+        return v8[1];
+    const bun = /^(?:undefined|null) is not an object \(evaluating '.*\.([\w$]+)'\)/.exec(message);
+    return bun ? bun[1] : null;
+}
+const rules = [
+    // Senri 自身が投げるエラー
+    (err) => errorCode(err) === "next_twice"
+        ? {
+            text: "1つのミドルウェアで `next()` を2回呼んでいます。`await next()` は1回だけにして、結果を変数に入れて使ってください。",
+            code: "const res = await next();",
+        }
+        : null,
+    (err) => errorCode(err) === "returned_function"
+        ? { text: "関数を呼び出さずに返しています。`()` を付けて呼び出した結果を返してください。", code: "return getUser();" }
+        : null,
+    (err) => errorCode(err) === "returned_nothing"
+        ? { text: "ハンドラーが値を返していません。`return` を忘れていないか確かめてください。", code: 'return "ok";' }
+        : null,
+    // undefined / null のプロパティを読んだ
+    (err) => {
+        if (!(err instanceof TypeError))
+            return null;
+        const prop = propertyOfNothing(err.message);
+        if (!prop)
+            return null;
+        return {
+            text: `\`undefined\` か \`null\` の値から \`${prop}\` を読もうとしました。\`await\` のし忘れや、\`c.get()\` で値が入っていない場合がよくあります。なくてもよい値なら \`?.\` で読めます。`,
+            code: `value?.${prop}`,
+        };
+    },
+    // 関数でないものを呼んだ
+    (err) => err instanceof TypeError && / is not a function/.test(err.message)
+        ? { text: "呼び出そうとしたものが関数ではありません。名前のつづりや、import しているものを確かめてください。" }
+        : null,
+    // BigInt を JSON にしようとした
+    // V8: Do not know how to serialize a BigInt / Bun: JSON.stringify cannot serialize BigInt.
+    (err) => err instanceof TypeError && /serialize (?:a )?BigInt/.test(err.message)
+        ? {
+            text: "`BigInt` は JSON にできません。文字列や数値に変換してから返してください。",
+            code: "String(value)",
+        }
+        : null,
+    // リクエストのボディが JSON として読めない(c.req.json())
+    // V8: ... in JSON at position 1 / ... is not valid JSON、Bun: JSON Parse error: ...
+    (err) => err instanceof SyntaxError && /JSON/.test(err.message)
+        ? {
+            text: "JSON として読めませんでした。`c.req.json()` なら、送られてきたボディが壊れています。受け取った側の問題なので、400 で返すのがおすすめです。",
+            code: 'const body = await c.req.json().catch(() => {\n    throw new HttpError(400, "JSON が正しくありません");\n});',
+        }
+        : null,
+    // 普通の Error を投げた(意図したエラーなら HttpError でステータスを決められる)
+    // - HttpError や、継承した独自のエラーは、利用者が意図して作ったものなので案内しない
+    // - ライブラリ(node_modules)が投げたものも案内しない(DB のエラーを 400 にするのは、たいてい間違い)
+    (err, frames) => Object.getPrototypeOf(err) === Error.prototype && thrownByUser(frames)
+        ? {
+            text: "ハンドラーやミドルウェアで投げたエラーが、どこでもキャッチされませんでした。意図したエラーなら `HttpError` でステータスコードを指定できます。",
+            code: `throw new HttpError(400, ${JSON.stringify(err.message)})`,
+        }
+        : null,
+];
+export function hintFor(err, frames) {
+    if (!(err instanceof Error))
+        return null;
+    for (const rule of rules) {
+        const hint = rule(err, frames);
+        if (hint)
+            return hint;
+    }
+    return null;
+}

package/dist/src/dev/html.d.ts

@@ -0,0 +1 @@
+export declare function escapeHtml(value: unknown): string;

package/dist/src/dev/html.js

@@ -0,0 +1,14 @@
+// HTML に埋め込む前に必ず通す(エラーページやダッシュボード用)
+// リクエストのパスやエラーメッセージは攻撃者が自由に決められるので、
+// そのまま埋め込むと <script> を仕込まれる(反射型 XSS)
+const ENTITIES = {
+    "&": "&amp;",
+    "<": "&lt;",
+    ">": "&gt;",
+    '"': "&quot;",
+    "'": "&#39;",
+};
+export function escapeHtml(value) {
+    // 1文字ずつ置き換えるので、& を先に処理しなくても二重にエスケープされない
+    return String(value).replace(/[&<>"']/g, (ch) => ENTITIES[ch]);
+}

package/dist/src/dev/index.d.ts

@@ -0,0 +1,3 @@
+import type { DevHooks } from "../app.ts";
+export declare function devtools(): DevHooks | undefined;
+export declare function isLocalUrl(url: string): boolean;