@madojs/mado 0.5.1 → 0.6.1

package/scripts/bundle.mjs

@@ -1,40 +1,109 @@
-// 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, rm } 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({});
+
+// 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);
+}
+
+// Clean stale assets from previous bundles.
+//
+// Without this step, hashed chunks from prior runs (main-<oldhash>.js,
+// chunk-<oldhash>.js) accumulate in ASSETS_DIR. We later list ASSETS_DIR
+// (via readdir below) and emit <link rel="modulepreload"> for every
+// .js file we find — so stale chunks would be preloaded as if they were
+// still part of the app, polluting the production HTML and shipping dead
+// code over the wire. SRI is also only computed for the fresh entry, so
+// stale preloads would lack integrity checks.
+//
+// In app-mode the entire <out>/assets/ folder is owned by the bundler,
+// so wiping it is safe. In repo-mode the historical layout drops assets
+// directly into <out>/ alongside non-bundle artifacts, so we only remove
+// the recognisable hashed files there.
+if (ASSETS_REL) {
+  await rm(ASSETS_DIR, { recursive: true, force: true });
+} else if (existsSync(ASSETS_DIR)) {
+  for (const f of await readdir(ASSETS_DIR)) {
+    if (/^(main|chunk|asset)-[A-Z0-9]+\.(js|css)(\.map|\.gz|\.br)?$/i.test(f)) {
+      await rm(join(ASSETS_DIR, f), { force: true });
+    }
+  }
+}
+await mkdir(ASSETS_DIR, { recursive: true });
 
-console.log(`[bundle] entry: ${ENTRY}`);
+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 +112,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 +120,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 +199,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,15 +46,17 @@ 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]);
     }
     break;
   case "serve":
-    await runServe(args[0] ?? "");
+    await runServe(args);
     break;
   case "dev":
-    await runDev(args[0] ?? "");
+    await runDev(args);
     break;
   case "bake":
     await runNodeScript("scripts/bake.mjs", 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;
@@ -75,15 +87,25 @@ switch (command) {
     process.exit(1);
 }
 
-async function runServe(example) {
+async function runServe(rawArgs) {
+  // Split args into [example?, ...flags]. The first non-flag positional is the
+  // example name; everything else (including `--host`, `--port`, etc.) is
+  // forwarded verbatim to server/serve.mjs.
+  const { example, forwarded } = splitDevArgs(rawArgs);
   if (!example && PROJECT_ROOT !== PACKAGE_ROOT) {
     await serveStaticProject(PROJECT_ROOT);
     return;
   }
   if (example) assertExample(example, { serveable: true });
-  await run(process.execPath, [join(PACKAGE_ROOT, "server/serve.mjs"), example].filter(Boolean), {
-    env: { ...process.env, EXAMPLE: example || process.env.EXAMPLE || "" },
-  });
+  await run(
+    process.execPath,
+    [join(PACKAGE_ROOT, "server/serve.mjs"), example, ...forwarded].filter(
+      Boolean,
+    ),
+    {
+      env: { ...process.env, EXAMPLE: example || process.env.EXAMPLE || "" },
+    },
+  );
 }
 
 async function runInit(rawArgs) {
@@ -156,15 +178,25 @@ async function runInit(rawArgs) {
   console.log("");
 }
 
-async function runDev(example) {
+async function runDev(rawArgs) {
+  // Forward unknown flags (e.g. --host, --port) to server/serve.mjs so callers
+  // can write `mado dev --host 127.0.0.1` without the CLI mistaking `--host`
+  // for an example name.
+  const { example, forwarded } = splitDevArgs(rawArgs);
   if (example) assertExample(example, { serveable: true });
 
   const env = { ...process.env, EXAMPLE: example || process.env.EXAMPLE || "" };
-  const server = spawn(process.execPath, [join(PACKAGE_ROOT, "server/serve.mjs"), example].filter(Boolean), {
-    cwd: PROJECT_ROOT,
-    env,
-    stdio: "inherit",
-  });
+  const server = spawn(
+    process.execPath,
+    [join(PACKAGE_ROOT, "server/serve.mjs"), example, ...forwarded].filter(
+      Boolean,
+    ),
+    {
+      cwd: PROJECT_ROOT,
+      env,
+      stdio: "inherit",
+    },
+  );
   const tsc = spawn(process.execPath, [resolveBin("typescript/bin/tsc"), "-w"], {
     cwd: PROJECT_ROOT,
     stdio: "inherit",
@@ -198,6 +230,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 +379,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) {
@@ -307,6 +431,50 @@ function parseFlags(raw) {
   return { flags, positional };
 }
 
+/**
+ * Split args for `mado dev` / `mado serve` into:
+ *   - example: the first non-flag positional (or undefined)
+ *   - forwarded: every remaining token (flags, their values, leftover
+ *     positionals), preserved in order so server/serve.mjs sees them
+ *     unchanged.
+ *
+ * This is what lets `mado dev -- --host 127.0.0.1` and
+ * `mado dev showcase --port 6000` both work without the CLI confusing
+ * `--host` for an example name.
+ */
+function splitDevArgs(raw) {
+  if (!Array.isArray(raw) || raw.length === 0) {
+    return { example: "", forwarded: [] };
+  }
+  let example = "";
+  const forwarded = [];
+  let pickedExample = false;
+  for (let i = 0; i < raw.length; i++) {
+    const a = raw[i];
+    if (a === "--") {
+      forwarded.push(...raw.slice(i + 1));
+      break;
+    }
+    if (a.startsWith("-")) {
+      forwarded.push(a);
+      // Lookahead: if the next token is the flag's VALUE (does not start with
+      // "-"), forward it too — but only when the flag is in inline form
+      // (--flag value), not --flag=value.
+      if (!a.includes("=") && raw[i + 1] !== undefined && !raw[i + 1].startsWith("-")) {
+        forwarded.push(raw[++i]);
+      }
+      continue;
+    }
+    if (!pickedExample) {
+      example = a;
+      pickedExample = true;
+    } else {
+      forwarded.push(a);
+    }
+  }
+  return { example, forwarded };
+}
+
 function packageNameFromDir(target) {
   return target
     .split(/[\\/]/)