@madojs/mado 0.5.0 → 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=examples/main.ts 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/main.ts";
-const OUT_DIR = process.env.OUT_DIR ?? "out";
-const HTML = process.env.HTML ?? "examples/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,8 +46,10 @@ 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=10000", ...files, ...args]);
+      await run(process.execPath, ["--test", "--test-timeout=20000", ...files, ...args]);
     }
     break;
   case "serve":
@@ -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;
@@ -120,6 +132,7 @@ async function runInit(rawArgs) {
   await mkdir(target, { recursive: true });
   await cp(source, target, { recursive: true, force: true });
   await copyCanonicalAgentFiles(target);
+  await ensureStarterGitignore(target);
 
   const packageName = packageNameFromDir(target);
   if (!isValidPackageName(packageName)) {
@@ -197,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);
@@ -204,6 +290,12 @@ async function copyCanonicalAgentFiles(target) {
   }
 }
 
+async function ensureStarterGitignore(target) {
+  const file = join(target, ".gitignore");
+  if (existsSync(file)) return;
+  await writeFile(file, "node_modules\ndist\nout\n.DS_Store\n*.log\n");
+}
+
 async function runNodeBin(bin, args) {
   await run(process.execPath, [resolveBin(bin), ...args]);
 }
@@ -267,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",