@madojs/mado 0.5.1 → 0.6.0

package/scripts/bundle.mjs

@@ -1,40 +1,86 @@
-// Optional production bundle through esbuild. No config files.
+// Production bundle through esbuild. No build config files.
 //
 // Usage:
-//   node scripts/bundle.mjs              # → out/<hash>.js + chunks + out/index.html
-//   ENTRY=src/index.ts HTML=examples/index.html node scripts/bundle.mjs
+//   mado bundle
+//   mado bundle --entry src/main.ts --html index.html --out out
+//
+// Configuration precedence: built-in defaults < mado.config.json < CLI flags
+// < legacy env vars (ENTRY, HTML, OUT_DIR).
 //
 // What it does:
-//   1. Bundles entry with code splitting (each dynamic import → a chunk).
-//   2. Writes out/ index.html with modulepreload for critical chunks.
-//   3. Computes SRI hashes and writes integrity="...".
-//   4. Creates .gz and .br next to each .js for nginx gzip_static.
+//   1. Bundles `entry` with code splitting (each dynamic import → chunk),
+//      writing hashed `main-<hash>.js` and `chunk-<hash>.js` into <out>/assets/.
+//   2. Computes SRI for the entry bundle.
+//   3. Rewrites `html` so its <script type=module> points at the hashed entry,
+//      removes the dev importmap, and adds <link rel=modulepreload> for the
+//      entry and all chunks. Writes the result to <out>/index.html.
+//   4. Pre-compresses every .js into .gz and .br for nginx_gzip_static and
+//      Cloudflare/Netlify Accept-Encoding.
+//   5. Copies optional `favicon.ico`/`favicon.svg`/`assets/` from the project
+//      root if they exist (kept for backwards compatibility; new apps should
+//      put public assets in `public/` so `mado release` copies them).
 //
-// Dependency: esbuild (devDep, only needed when running bundle).
+// In repo-mode (the framework repo itself) the defaults still point at
+// examples/showcase so the framework can dogfood its bundle pipeline against
+// its biggest example.
 
 import { build } from "esbuild";
-import {
-  readFile,
-  writeFile,
-  mkdir,
-  cp,
-  stat,
-  readdir,
-} from "node:fs/promises";
+import { readFile, writeFile, mkdir, cp, stat, readdir } from "node:fs/promises";
 import { createHash } from "node:crypto";
 import { gzipSync, brotliCompressSync, constants as zlibConst } from "node:zlib";
-import { join, basename } from "node:path";
+import { join, basename, resolve, dirname } from "node:path";
 import { existsSync } from "node:fs";
 
-const ENTRY = process.env.ENTRY ?? "examples/showcase/main.ts";
-const OUT_DIR = process.env.OUT_DIR ?? "out";
-const HTML = process.env.HTML ?? "examples/showcase/index.html";
+import { loadConfig, parseFlags, resolveProjectPath } from "./_config.mjs";
 
-await mkdir(OUT_DIR, { recursive: true });
+const { flags } = parseFlags(process.argv.slice(2));
+const cfg = loadConfig({});
 
-console.log(`[bundle] entry: ${ENTRY}`);
+// Defaults are context-aware: in repo-mode they continue to bundle the
+// showcase example; in app-mode they assume the canonical layout.
+const defaultEntry = cfg.context === "repo"
+  ? "examples/showcase/main.ts"
+  : "src/main.ts";
+const defaultHtml = cfg.context === "repo"
+  ? "examples/showcase/index.html"
+  : "index.html";
+
+const ENTRY = resolveProjectPath(
+  cfg,
+  typeof flags.entry === "string" ? flags.entry : process.env.ENTRY ?? defaultEntry,
+);
+const HTML = resolveProjectPath(
+  cfg,
+  typeof flags.html === "string" ? flags.html : process.env.HTML ?? defaultHtml,
+);
+const OUT_DIR = resolveProjectPath(
+  cfg,
+  typeof flags.out === "string" ? flags.out : process.env.OUT_DIR ?? cfg.build.out ?? "out",
+);
+// Where the hashed bundles land. Apps want them under /assets/* to match
+// nginx.conf and _headers; in repo-mode we keep the historical out/main-*.js
+// layout so existing showcase pages continue to work.
+const ASSETS_REL = cfg.context === "repo" ? "" : "assets";
+const ASSETS_DIR = ASSETS_REL ? join(OUT_DIR, ASSETS_REL) : OUT_DIR;
+
+if (!existsSync(ENTRY)) {
+  console.error(`[bundle] entry not found: ${ENTRY}`);
+  console.error("[bundle] set bundle entry in mado.config.json or pass --entry <file>");
+  process.exit(1);
+}
+if (!existsSync(HTML)) {
+  console.error(`[bundle] html template not found: ${HTML}`);
+  console.error("[bundle] pass --html <file> or place index.html at the project root");
+  process.exit(1);
+}
+
+await mkdir(ASSETS_DIR, { recursive: true });
+
+console.log(`[bundle] entry:    ${ENTRY}`);
+console.log(`[bundle] html:     ${HTML}`);
+console.log(`[bundle] out:      ${OUT_DIR}`);
+if (ASSETS_REL) console.log(`[bundle] assets:   ${ASSETS_DIR}`);
 
-// 1) esbuild with code splitting
 const result = await build({
   entryPoints: [ENTRY],
   bundle: true,
@@ -43,7 +89,7 @@ const result = await build({
   format: "esm",
   target: "es2022",
   splitting: true,
-  outdir: OUT_DIR,
+  outdir: ASSETS_DIR,
   entryNames: "main-[hash]",
   chunkNames: "chunk-[hash]",
   assetNames: "asset-[hash]",
@@ -51,79 +97,76 @@ const result = await build({
   legalComments: "none",
 });
 
-// 2) Find the main entry file
-const entryFile = Object.entries(result.metafile.outputs)
-  .find(([name, info]) => info.entryPoint && name.endsWith(".js"))?.[0];
-
-if (!entryFile) {
+const entryOutput = Object.entries(result.metafile.outputs).find(
+  ([name, info]) => info.entryPoint && name.endsWith(".js"),
+);
+if (!entryOutput) {
   console.error("[bundle] entry not found in outputs");
   process.exit(1);
 }
-const mainBundle = basename(entryFile);
+const mainBundle = basename(entryOutput[0]);
 
-// 3) Collect all js chunks (including main)
-const allJs = (await readdir(OUT_DIR)).filter((f) => f.endsWith(".js"));
+// Collect all js chunks in the assets dir.
+const allJs = (await readdir(ASSETS_DIR)).filter((f) => f.endsWith(".js"));
 
-// 4) Compress every .js into .gz and .br (for nginx gzip_static)
+// Pre-compress every .js into .gz and .br.
 let totalRaw = 0;
 let totalGz = 0;
 let totalBr = 0;
-
 for (const f of allJs) {
-  const p = join(OUT_DIR, f);
+  const p = join(ASSETS_DIR, f);
   const buf = await readFile(p);
   totalRaw += buf.length;
-
   const gz = gzipSync(buf, { level: 9 });
   await writeFile(`${p}.gz`, gz);
   totalGz += gz.length;
-
-  const br = brotliCompressSync(buf, {
-    params: { [zlibConst.BROTLI_PARAM_QUALITY]: 11 },
-  });
+  const br = brotliCompressSync(buf, { params: { [zlibConst.BROTLI_PARAM_QUALITY]: 11 } });
   await writeFile(`${p}.br`, br);
   totalBr += br.length;
 }
 
-// 5) SRI for the main bundle
-const mainBuf = await readFile(join(OUT_DIR, mainBundle));
+// SRI for the main bundle.
+const mainBuf = await readFile(join(ASSETS_DIR, mainBundle));
 const sri = "sha384-" + createHash("sha384").update(mainBuf).digest("base64");
 
-// 6) HTML: replace <script> and add modulepreload for main
+// Rewrite HTML: drop dev importmap, swap the <script src>, add preloads.
+const urlPrefix = ASSETS_REL ? `/${ASSETS_REL}/` : "/";
 let html = await readFile(HTML, "utf8");
 
-// modulepreload for main + other chunks. For now preload all chunks; this can
-// later be filtered from metafile analysis.
+html = html.replace(/<script type="importmap">[\s\S]*?<\/script>/, "");
+
 const preloads = allJs
   .map(
     (f) =>
-      `    <link rel="modulepreload" href="/${f}"${
+      `    <link rel="modulepreload" href="${urlPrefix}${f}"${
         f === mainBundle ? ` integrity="${sri}" crossorigin="anonymous"` : ""
       } />`,
   )
   .join("\n");
 
-// Remove the old importmap (it points to dev paths under /dist/src/...).
-html = html.replace(/<script type="importmap">[\s\S]*?<\/script>/, "");
-
-// Replace the script with the new one.
-html = html.replace(
-  /<script\s+type="module"\s+src="[^"]+"[^>]*><\/script>/,
-  `<script type="module" src="/${mainBundle}" integrity="${sri}" crossorigin="anonymous"></script>`,
-);
+const scriptTag = `<script type="module" src="${urlPrefix}${mainBundle}" integrity="${sri}" crossorigin="anonymous"></script>`;
+if (/<script\s+type="module"\s+src="[^"]+"[^>]*><\/script>/.test(html)) {
+  html = html.replace(
+    /<script\s+type="module"\s+src="[^"]+"[^>]*><\/script>/,
+    scriptTag,
+  );
+} else {
+  // No matching dev <script> in the template: inject one before </body>.
+  html = html.replace(/<\/body>/i, `  ${scriptTag}\n  </body>`);
+}
 
-// Insert preloads before </head>.
-html = html.replace(
-  /<\/head>/,
-  `${preloads}\n  </head>`,
-);
+html = html.replace(/<\/head>/, `${preloads}\n  </head>`);
 
+await mkdir(OUT_DIR, { recursive: true });
 await writeFile(join(OUT_DIR, "index.html"), html);
 
-// 7) Static files
-for (const name of ["favicon.ico", "favicon.svg", "assets"]) {
-  const src = join("examples", name);
-  if (existsSync(src)) {
+// Backwards-compatible asset copy (repo-mode only). In app-mode the
+// `mado release` command copies the entire `public/` tree, which is the
+// recommended path for new apps.
+if (cfg.context === "repo") {
+  for (const name of ["favicon.ico", "favicon.svg", "assets"]) {
+    const src = join(cfg.projectRoot, "examples", name);
+    if (!existsSync(src)) continue;
     const s = await stat(src);
     if (s.isDirectory()) {
       await cp(src, join(OUT_DIR, name), { recursive: true });
@@ -133,14 +176,14 @@ for (const name of ["favicon.ico", "favicon.svg", "assets"]) {
   }
 }
 
-// 8) Stats
+// Stats
 const kib = (n) => (n / 1024).toFixed(1);
 console.log(`[bundle] chunks: ${allJs.length}`);
 for (const f of allJs.sort()) {
-  const sz = (await stat(join(OUT_DIR, f))).size;
-  const gz = (await stat(join(OUT_DIR, `${f}.gz`))).size;
+  const sz = (await stat(join(ASSETS_DIR, f))).size;
+  const gz = (await stat(join(ASSETS_DIR, `${f}.gz`))).size;
   const star = f === mainBundle ? " *" : "";
   console.log(`  ${f.padEnd(24)} ${kib(sz).padStart(6)} KB raw, ${kib(gz).padStart(5)} KB gz${star}`);
 }
 console.log(`[bundle] total: ${kib(totalRaw)} KB raw / ${kib(totalGz)} KB gz / ${kib(totalBr)} KB br`);
-console.log(`[bundle] entry SRI: ${sri}`);
+console.log(`[bundle] entry SRI: ${sri}`);

package/scripts/cli.mjs

@@ -2,23 +2,30 @@
 
 import { spawn } from "node:child_process";
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
-import { copyFile, cp, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { copyFile, cp, mkdir, readdir, readFile, writeFile, rm } from "node:fs/promises";
 import http from "node:http";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
+import { detectContext, loadConfig } from "./_config.mjs";
+
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const PROJECT_ROOT = resolve(process.cwd());
 const PACKAGE_JSON = JSON.parse(readFileSync(join(PACKAGE_ROOT, "package.json"), "utf8"));
 const [, , rawCommand, ...args] = process.argv;
 
+// Context detection lives in _config.mjs so every script agrees on what
+// "repo" vs "app" means. CLI uses it to pick safer defaults.
+const CONTEXT = detectContext(PROJECT_ROOT);
+const IS_REPO = CONTEXT === "repo";
+
 const EXAMPLES = [
   ["basic", "minimal API tour"],
   ["tickets", "LLM zero-history CRUD validation"],
   ["showcase", "flagship SaaS CRM pressure app"],
   ["cloudflare", "Cloudflare Workers edge example"],
 ];
-const STARTERS = ["minimal", "crud"];
+const STARTERS = ["minimal", "crud", "admin"];
 
 const command = rawCommand ?? "help";
 
@@ -39,6 +46,8 @@ switch (command) {
     if (args[0] === "browser") {
       await runNodeScript("scripts/showcase-regression.mjs", args.slice(1));
     } else {
+      // Ensure dist/ is fresh so tests that import from ../dist/ work.
+      await runNodeBin("typescript/bin/tsc", []);
       const files = await listTestFiles();
       await run(process.execPath, ["--test", "--test-timeout=20000", ...files, ...args]);
     }
@@ -58,6 +67,9 @@ switch (command) {
   case "preview":
     await runNodeScript("scripts/preview.mjs", args);
     break;
+  case "release":
+    await runRelease(args);
+    break;
   case "new":
     await runNodeScript("scripts/new.mjs", args);
     break;
@@ -198,6 +210,79 @@ async function runDev(example) {
   });
 }
 
+async function runRelease(rawArgs) {
+  // Single "ship it" command. Composes the smaller steps so the user does not
+  // have to remember the order, and so the deploy artifact (out/) is always
+  // assembled the same way.
+  //
+  //   mado release
+  //     → mado typecheck
+  //     → mado build       (tsc → dist/)
+  //     → mado bundle      (esbuild → out/assets/, also copies index.html)
+  //     → mado bake        (HTML  → out/baked/)
+  //     → copy public/* → out/
+  //
+  // Flags are forwarded to bake/bundle.
+  const cfg = loadConfig({ projectRoot: PROJECT_ROOT });
+  const outDir = resolve(cfg.projectRoot, cfg.build.out ?? "out");
+  const publicDir = resolve(cfg.projectRoot, cfg.build.publicDir ?? "public");
+
+  console.log(`[release] context: ${cfg.context}`);
+  console.log(`[release] artifact: ${outDir}`);
+  console.log("");
+
+  console.log("[release] step 1/5  typecheck");
+  await runNodeBin("typescript/bin/tsc", ["--noEmit"]);
+
+  console.log("[release] step 2/5  build (tsc → dist/)");
+  await runNodeBin("typescript/bin/tsc", []);
+
+  console.log("[release] step 3/5  bundle (esbuild → out/assets/)");
+  await runNodeScript("scripts/bundle.mjs", rawArgs);
+
+  console.log("[release] step 4/5  bake (out/baked/)");
+  await runNodeScript("scripts/bake.mjs", rawArgs);
+
+  console.log("[release] step 5/5  copy public/ → out/");
+  if (existsSync(publicDir)) {
+    await mkdir(outDir, { recursive: true });
+    await cp(publicDir, outDir, { recursive: true });
+    console.log(`[release]   copied ${publicDir} → ${outDir}`);
+  } else {
+    console.log(`[release]   no ${publicDir}, skipping`);
+  }
+
+  // Optional CDN config files. Generated only when not already provided.
+  await writeIfMissing(
+    join(outDir, "_redirects"),
+    // Cloudflare Pages / Netlify: SPA fallback so deep links work after a
+    // hard refresh. Baked HTML files are matched first because of
+    // `force: false` / static-priority rules on these hosts.
+    "/* /index.html 200\n",
+  );
+  await writeIfMissing(
+    join(outDir, "_headers"),
+    [
+      "/assets/*",
+      "  Cache-Control: public, max-age=31536000, immutable",
+      "",
+      "/*.html",
+      "  Cache-Control: no-cache, must-revalidate",
+      "",
+    ].join("\n"),
+  );
+
+  console.log("");
+  console.log(`[release] done. Deploy artifact: ${outDir}`);
+  console.log("[release] try:  mado preview");
+}
+
+async function writeIfMissing(path, content) {
+  if (existsSync(path)) return;
+  await writeFile(path, content);
+  console.log(`[release]   wrote ${path}`);
+}
+
 async function copyCanonicalAgentFiles(target) {
   for (const file of ["AGENTS.md", "llms.txt"]) {
     const source = join(PACKAGE_ROOT, file);
@@ -274,19 +359,38 @@ async function listTestFiles() {
 }
 
 function printHelp() {
-  console.log(`mado commands:
-  mado init <name> [--starter minimal|crud] [--force]
-  mado build
-  mado watch
-  mado typecheck
-  mado test [browser]
-  mado serve [basic|tickets|showcase]
-  mado dev [basic|tickets|showcase]
-  mado bake
-  mado bundle
-  mado preview
-  mado new <list|form|detail> <name>
-  mado examples`);
+  const ctx = IS_REPO ? "repo-mode (framework repository)" : "app-mode";
+  console.log(`mado commands (${ctx}):
+
+  Project lifecycle:
+    mado init <name> [--starter minimal|crud|admin] [--force]
+                           scaffold a new app
+    mado dev               tsc -w + dev server with HMR
+    mado build             tsc (writes dist/)
+    mado typecheck         tsc --noEmit
+    mado test [browser]    run unit tests (or browser regression)
+
+  Production:
+    mado bundle            esbuild → out/assets/   (hashed bundles)
+    mado bake [--entry <file>] [--template <html>] [--out <dir>] [--base-url <url>]
+                           prerender baked routes  → out/baked/
+    mado release           typecheck + build + bundle + bake + copy public/ → out/
+                           ← the one command for "ship it"
+    mado preview           serve exactly out/ locally (production rehearsal)
+    mado serve [example]   simple static server (also runs in repo-mode for examples)
+
+  Generators:
+    mado new <list|form|detail> <name>
+
+  Misc:
+    mado examples          list bundled examples
+    mado help              this screen
+
+  Configuration:
+    mado reads ./mado.config.json (dev.proxy, build.out, bake.entry/template/baseUrl, …)
+    CLI flags > mado.config.json > built-in defaults.
+
+  See MADO_V1_PLAN.md for the road to v1.`);
 }
 
 function parseFlags(raw) {

package/scripts/preview.mjs

@@ -1,28 +1,38 @@
-// Preview: a tiny production-like server that emulates nginx.conf on node:http.
+// Preview: a tiny production-like server that serves exactly out/ on node:http.
 //
-//   npm run preview
+//   mado preview
 //
 // What it does:
-//   1. npm run build (tsc)
-//   2. node scripts/bake.mjs   (generates SEO HTML when bake pages exist)
-//   3. node scripts/bundle.mjs (esbuild splitting + .gz/.br)
-//   4. Starts a static server on :4173 with:
+//   1. Reads `mado.config.json` to discover OUT (default `out/`) and PORT.
+//   2. If `out/` is missing AND we are in a project root, refuses to run and
+//      points the user at `mado release`. (Old auto-build behavior is opt-in
+//      via PREVIEW_AUTOBUILD=1 to stay backward-compatible for the framework
+//      repo.)
+//   3. Starts a static server with:
 //        - immutable cache for hashed bundles;
 //        - SPA fallback to index.html;
-//        - baked HTML priority over index.html;
+//        - baked HTML priority over the SPA shell;
 //        - precompressed .gz / .br serving via Accept-Encoding.
 //
-// Goal: see production-like output locally without Docker/nginx.
+// Goal: see production-like output locally without Docker/nginx, identical to
+// what a static host (nginx / Cloudflare Pages / S3) would serve.
 
 import { createServer } from "node:http";
 import { readFile, stat, access } from "node:fs/promises";
 import { extname, join, resolve, sep } from "node:path";
 import { spawnSync } from "node:child_process";
 
-const ROOT = resolve(process.cwd());
-const OUT = resolve(process.env.OUT_DIR ?? "out");
-const PORT = Number(process.env.PORT ?? 4173);
-const SKIP_BUILD = process.env.SKIP_BUILD === "1";
+import { loadConfig } from "./_config.mjs";
+
+const cfg = loadConfig({});
+const ROOT = cfg.projectRoot;
+const OUT = resolve(
+  ROOT,
+  process.env.OUT_DIR ?? cfg.build.out ?? "out",
+);
+const PORT = Number(process.env.PORT ?? cfg.dev?.port ?? 4173);
+const AUTOBUILD = process.env.PREVIEW_AUTOBUILD === "1";
+const SKIP_BUILD = process.env.SKIP_BUILD === "1" || !AUTOBUILD;
 
 const MIME = {
   ".html": "text/html; charset=utf-8",

package/server/serve.mjs

@@ -12,14 +12,30 @@
 // examples/<EXAMPLE>/index.html so the client router works from root, just
 // like a production SPA deploy.
 
-import { createServer } from "node:http";
-import { readFile, readdir, stat } from "node:fs/promises";
-import { watch, existsSync } from "node:fs";
+import { createServer, request as httpRequest } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { readFile, readdir, readFile as readFileAsync, stat } from "node:fs/promises";
+import { watch, existsSync, readFileSync } from "node:fs";
 import { extname, join, resolve, sep } from "node:path";
 import { createHash } from "node:crypto";
 
 const ROOT = resolve(process.cwd());
-const PORT = Number(process.env.PORT ?? 5173);
+
+// Optional mado.config.json — used for dev.proxy and dev.port. Read with a
+// hand-rolled JSON parse to avoid a circular dep with scripts/_config.mjs
+// (this server is launched from cli.mjs and runs in its own Node process).
+const CONFIG = (() => {
+  try {
+    const file = join(ROOT, "mado.config.json");
+    if (!existsSync(file)) return {};
+    return JSON.parse(readFileSync(file, "utf8")) ?? {};
+  } catch {
+    return {};
+  }
+})();
+const PROXY_RULES = Object.entries(CONFIG.dev?.proxy ?? {}); // [["/api", "http://localhost:3000"], ...]
+
+const PORT = Number(process.env.PORT ?? CONFIG.dev?.port ?? 5173);
 const HMR = process.env.NO_HMR !== "1";
 
 const EXAMPLE = process.argv[2] ?? process.env.MADO_EXAMPLE ?? process.env.EXAMPLE ?? "";
@@ -118,6 +134,16 @@ const server = createServer(async (req, res) => {
     const url = new URL(req.url ?? "/", `http://${req.headers.host}`);
     pathname = decodeURIComponent(url.pathname);
 
+    // Dev proxy: forward matching prefixes to an upstream backend, so the
+    // browser can reach the SPA and the API on a single origin without CORS.
+    const proxyRule = PROXY_RULES.find(([prefix]) => pathname.startsWith(prefix));
+    if (proxyRule) {
+      const [prefix, upstream] = proxyRule;
+      await proxyForward({ req, res, prefix, upstream, pathname, search: url.search });
+      reason = `proxy → ${upstream}`;
+      return;
+    }
+
     // SSE endpoint for HMR.
     if (pathname === "/__hmr") {
       res.writeHead(200, {
@@ -279,6 +305,52 @@ server.on("error", (err) => {
   process.exit(1);
 });
 
+async function proxyForward({ req, res, prefix, upstream, pathname, search }) {
+  // Strip the prefix only if the upstream URL itself ends with `/`; otherwise
+  // forward the full pathname so the backend sees /api/...
+  let upstreamUrl;
+  try {
+    upstreamUrl = new URL(upstream);
+  } catch {
+    res.writeHead(502).end(`bad upstream: ${upstream}`);
+    return;
+  }
+  const target = new URL(upstream);
+  // Compose path: <upstream.pathname rstrip "/"> + <pathname> + <search>
+  const tail = pathname; // keep the original /api/... so backends route normally
+  target.pathname = (target.pathname.replace(/\/$/, "")) + tail;
+  target.search = search;
+
+  const lib = target.protocol === "https:" ? httpsRequest : httpRequest;
+  const upstreamReq = lib(
+    target,
+    {
+      method: req.method,
+      headers: {
+        ...req.headers,
+        host: target.host,
+      },
+    },
+    (upstreamRes) => {
+      // Forward status and headers, then pipe the body.
+      res.writeHead(upstreamRes.statusCode ?? 502, upstreamRes.headers);
+      upstreamRes.pipe(res);
+    },
+  );
+  upstreamReq.on("error", (err) => {
+    console.error(`[serve] proxy error for ${pathname} → ${target.href}:`, err.message);
+    if (!res.headersSent) {
+      res.writeHead(502, { "content-type": "text/plain; charset=utf-8" });
+      res.end(`proxy upstream unavailable: ${target.host}\n${err.message}`);
+    } else {
+      res.end();
+    }
+  });
+  req.pipe(upstreamReq);
+  // Reference unused arg so lint is happy.
+  void prefix;
+}
+
 server.listen(PORT, () => {
   const distReady = existsSync(join(ROOT, "dist/src/index.js"))
     || existsSync(join(ROOT, "dist/main.js"));
@@ -295,6 +367,12 @@ server.listen(PORT, () => {
   console.log(`  hmr:      ${HMR ? "on" : "off"}`);
   console.log(`  preload:  ${PRELOAD}`);
   console.log(`  dist:     ${distReady ? "ready" : "missing (run mado build)"}`);
+  if (PROXY_RULES.length > 0) {
+    console.log("  proxy:");
+    for (const [prefix, upstream] of PROXY_RULES) {
+      console.log(`            ${prefix.padEnd(10)} → ${upstream}`);
+    }
+  }
   if (!EXAMPLE && existsSync(EXAMPLES_INDEX)) {
     console.log("  try:      mado serve basic");
     console.log("            mado serve showcase");

package/starters/admin/README.md

@@ -0,0 +1,63 @@
+# __APP_NAME__
+
+A starter Mado admin app: nested routes, a guarded admin shell, a blessed API
+client, and a one-shot release pipeline.
+
+## What you get
+
+- `src/main.ts` — 8 lines: mount the router into `#app`. Layouts are NOT
+  declared here, only in `src/routes.ts`.
+- `src/routes.ts` — nested manifest with three groups:
+  - `/` → public landing (bakeable),
+  - `/login` → centered `auth` layout,
+  - `/admin` → `app` layout, **guarded** by `requireAuth`.
+- `src/layouts/app.ts` — admin shell (top bar + sidebar + content slot).
+- `src/layouts/auth.ts` — centered card for sign-in.
+- `src/lib/api.ts` — `createApiClient(baseUrl)` with bearer token, 401-refresh
+  retry, JSON in/out and a typed `ApiError`.
+- `src/lib/auth.ts` — memory-only `accessToken`, `restoreSession()` from an
+  HttpOnly refresh cookie, and the `requireAuth` guard.
+- `src/components/` — tiny `x-button` and `x-input` Web Components.
+- `mado.config.json` — one config file. Includes a `dev.proxy` for `/api`.
+
+## Commands
+
+```bash
+npm run dev        # tsc -w + dev server on http://localhost:5173, HMR on
+npm run build      # tsc → dist/
+npm run typecheck  # tsc --noEmit
+npm run bundle     # esbuild → out/assets/
+npm run bake       # prerender baked routes → out/baked/
+npm run release    # typecheck + build + bundle + bake + copy public/ → out/
+npm run preview    # serve out/ locally (production rehearsal)
+```
+
+To deploy, run `npm run release` and upload the entire `out/` directory
+anywhere static (nginx, Cloudflare Pages, S3, Netlify, GitHub Pages, …).
+
+## Backend expectations
+
+The blessed `api` client speaks JSON. The auth recipe expects:
+
+- `POST /api/auth/login` → `{ accessToken: string }` (sets refresh cookie)
+- `POST /api/auth/refresh` → `{ accessToken: string }` (reads refresh cookie)
+- `POST /api/auth/logout` → 204 (clears refresh cookie)
+
+Change `mado.config.json#dev.proxy` to point at your backend in development.
+
+## Where things live
+
+| What                | Where                                |
+|---------------------|--------------------------------------|
+| New URL             | `src/pages/*.ts` + add to `routes.ts`|
+| New protected URL   | inside the `/admin` layout block     |
+| New layout          | `src/layouts/*.ts`                   |
+| New reusable widget | `src/components/x-*.ts`              |
+| New API call        | `src/lib/api.ts` (add a method)      |
+| New global signal   | `src/lib/<name>.ts`                  |
+| Static image        | `public/<file>`                      |
+
+See the framework docs:
+[`docs/en/11-layouts.md`](https://github.com/madojs/mado/blob/main/docs/en/11-layouts.md),
+[`docs/en/12-auth-and-api.md`](https://github.com/madojs/mado/blob/main/docs/en/12-auth-and-api.md),
+[`docs/en/13-deployment.md`](https://github.com/madojs/mado/blob/main/docs/en/13-deployment.md).