@madojs/mado 0.10.0 → 0.11.0

package/scripts/preview.mjs

@@ -3,15 +3,14 @@
 //   mado preview
 //
 // What it does:
-//   1. Reads `mado.config.json` to discover OUT (default `out/`) and PORT.
+//   1. Serves OUT_DIR or `out/`.
 //   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.)
+//      points the user at `mado release`. Auto-build is opt-in via
+//      PREVIEW_AUTOBUILD=1.
 //   3. Starts a static server with:
 //        - immutable cache for hashed bundles;
 //        - SPA fallback to index.html;
-//        - baked HTML priority over the SPA shell;
+//        - exact `out/` route files before SPA fallback;
 //        - precompressed .gz / .br serving via Accept-Encoding.
 //
 // Goal: see production-like output locally without Docker/nginx, identical to
@@ -22,8 +21,6 @@ import { readFile, stat, access } from "node:fs/promises";
 import { extname, join, resolve, sep } from "node:path";
 import { spawnSync } from "node:child_process";
 
-import { loadConfig } from "./_config.mjs";
-
 // Tiny argv parser. Supports --flag, --flag=value, --flag value.
 function parsePreviewArgs(argv) {
   const flags = {};
@@ -51,22 +48,10 @@ function parsePreviewArgs(argv) {
 
 const PREVIEW_FLAGS = parsePreviewArgs(process.argv.slice(2));
 
-const cfg = loadConfig({});
-const ROOT = cfg.projectRoot;
-const OUT = resolve(
-  ROOT,
-  process.env.OUT_DIR ?? cfg.build.out ?? "out",
-);
-// Baked HTML lives in <out>/baked/ by default (see scripts/bake.mjs and
-// mado.config.json bake.outDir). Preview serves it with priority over the
-// SPA shell so URLs that have a prerendered HTML page render real markup
-// instead of an empty <div id="app"></div>.
-const BAKED = resolve(
-  ROOT,
-  process.env.BAKED_DIR ?? cfg.bake?.outDir ?? join(cfg.build.out ?? "out", "baked"),
-);
-const PORT = Number(PREVIEW_FLAGS.port ?? process.env.PORT ?? cfg.dev?.port ?? 4173);
-const HOST = String(PREVIEW_FLAGS.host ?? process.env.HOST ?? cfg.dev?.host ?? "localhost");
+const ROOT = resolve(process.cwd());
+const OUT = resolve(ROOT, process.env.OUT_DIR ?? "out");
+const PORT = Number(PREVIEW_FLAGS.port ?? process.env.PORT ?? 4173);
+const HOST = String(PREVIEW_FLAGS.host ?? process.env.HOST ?? "localhost");
 const AUTOBUILD = process.env.PREVIEW_AUTOBUILD === "1";
 const SKIP_BUILD = process.env.SKIP_BUILD === "1" || !AUTOBUILD;
 
@@ -87,23 +72,16 @@ const MIME = {
   ".map": "application/json; charset=utf-8",
 };
 
-// ---------- 1-3) Full build ----------
+// ---------- Optional release ----------
 
 if (!SKIP_BUILD) {
-  console.log("[preview] step 1/3 — tsc");
-  run("npx", ["tsc"]);
-
-  // bake is optional (only when there are pages with bake config)
-  console.log("[preview] step 2/3 — bake (optional)");
-  run("node", ["scripts/bake.mjs"], { allowFail: true });
-
-  console.log("[preview] step 3/3 — bundle");
-  run("node", ["scripts/bundle.mjs"]);
+  console.log("[preview] PREVIEW_AUTOBUILD=1 — running mado release");
+  run("node", ["scripts/cli.mjs", "release"]);
 }
 
 if (!(await exists(OUT))) {
   console.error(
-    `[preview] missing ${OUT}/ — run \`mado release\` (or \`mado bundle\`) first.`,
+    `[preview] missing ${OUT}/ — run \`mado release\` first.`,
   );
   process.exit(1);
 }
@@ -111,7 +89,7 @@ if (!(await exists(OUT))) {
 const spaShell = join(OUT, "index.html");
 if (!(await exists(spaShell))) {
   console.error(
-    `[preview] missing ${spaShell} — \`mado bundle\` did not produce an HTML entry.\n` +
+    `[preview] missing ${spaShell} — \`mado release\` did not produce an HTML entry.\n` +
       `[preview] Without it any non-baked route will 404 instead of falling back to the SPA.`,
   );
   process.exit(1);
@@ -120,7 +98,7 @@ if (!(await exists(spaShell))) {
 // ---------- 4) Server ----------
 
 const isImmutable = (filename) =>
-  /^(main|chunk|asset)-[A-Z0-9]+\.js$/i.test(filename);
+  /\.[A-Za-z0-9_-]{6,}\.(js|css|png|jpg|jpeg|webp|svg|woff2?)$/i.test(filename);
 
 const server = createServer(async (req, res) => {
   try {
@@ -178,12 +156,10 @@ server.on("error", (err) => {
 
 server.listen(PORT, HOST, async () => {
   const urlHost = HOST === "0.0.0.0" || HOST === "::" ? "localhost" : HOST;
-  const bakedReady = await exists(BAKED);
   console.log("");
   console.log("Mado preview (production-like)");
   console.log(`  url:    http://${urlHost}:${PORT}/`);
   console.log(`  out:    ${OUT}`);
-  console.log(`  baked:  ${bakedReady ? BAKED : "(none — SPA-only)"}`);
   console.log("  (Ctrl-C to stop)");
   console.log("");
 });
@@ -215,30 +191,10 @@ function basenameSafe(p) {
 async function resolveTarget(pathname) {
   if (pathname === "/") pathname = "/index.html";
 
-  // 1) Baked HTML wins. `mado bake` writes prerendered pages into
-  //    <out>/baked/<path>/index.html. Serve them with priority over the
-  //    SPA shell so search engines AND human users hitting a prerendered
-  //    URL see real content immediately. Without this branch preview
-  //    served the empty SPA shell for every URL, which looked like a
-  //    "blank page" bug even when bake had succeeded.
-  if (await exists(BAKED)) {
-    if (!extname(pathname) || pathname.endsWith("/index.html")) {
-      const bakedDir = join(BAKED, pathname.replace(/\/index\.html$/, ""));
-      const bakedIdx = join(bakedDir, "index.html");
-      if (await exists(bakedIdx)) return bakedIdx;
-    }
-    // Direct file (sitemap.xml etc.) from the baked dir.
-    const bakedFile = resolve(join(BAKED, pathname));
-    if (bakedFile.startsWith(BAKED + sep) && (await exists(bakedFile))) {
-      const s = await stat(bakedFile);
-      if (!s.isDirectory()) return bakedFile;
-    }
-  }
-
   const candidate = resolve(join(OUT, pathname));
   if (!candidate.startsWith(OUT + sep) && candidate !== OUT) return null;
 
-  // 2) Exact match inside out/.
+  // 1) Exact match inside out/.
   if (await exists(candidate)) {
     const s = await stat(candidate);
     if (s.isDirectory()) {
@@ -249,13 +205,13 @@ async function resolveTarget(pathname) {
     }
   }
 
-  // 3) /foo → /foo/index.html (for sub-folders without trailing slash).
+  // 2) /foo → /foo/index.html (for sub-folders without trailing slash).
   if (!extname(pathname)) {
     const asDir = join(OUT, pathname, "index.html");
     if (await exists(asDir)) return asDir;
   }
 
-  // 4) SPA-fallback: any non-asset path falls back to the SPA shell so
+  // 3) SPA-fallback: any non-asset path falls back to the SPA shell so
   //    client-side routing handles it. Asset-looking paths (with an
   //    extension) deliberately 404 instead — otherwise a 200 on
   //    /missing.png would mask real bugs.

package/scripts/size-budget.mjs

@@ -7,7 +7,7 @@ import { join } from "node:path";
 import { gzipSync } from "node:zlib";
 
 const API_ENTRY = "src/index.ts";
-const SAMPLE_ENTRY = "examples/showcase/main.ts";
+const SAMPLE_ENTRY = "starters/default/src/main.ts";
 const API_GZIP_LIMIT = readLimit("MADO_SIZE_API_GZIP_LIMIT", 16 * 1024);
 const SAMPLE_GZIP_LIMIT = readLimit("MADO_SIZE_SAMPLE_GZIP_LIMIT", 42 * 1024);
 
@@ -17,7 +17,7 @@ const api = await bundlePublicApi();
 report("public API", api.gzip, API_GZIP_LIMIT);
 
 const sample = await bundleSampleApp();
-report("showcase app", sample.gzip, SAMPLE_GZIP_LIMIT);
+report("starter app", sample.gzip, SAMPLE_GZIP_LIMIT);
 
 if (failed) process.exit(1);
 
@@ -49,6 +49,9 @@ async function bundleSampleApp() {
       platform: "browser",
       splitting: true,
       outdir,
+      alias: {
+        "@madojs/mado": "./src/index.ts",
+      },
       legalComments: "none",
     });
 

package/scripts/vite.default.mjs

@@ -0,0 +1,11 @@
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  appType: "spa",
+  publicDir: "public",
+  build: {
+    outDir: "out",
+    assetsDir: "assets",
+    target: "es2022",
+  },
+});

package/starters/default/.editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false

package/starters/default/README.md

@@ -0,0 +1,74 @@
+# Mado Starter
+
+Canonical starter for Mado business apps: admin panels, internal tools and
+long-lived SPAs.
+
+## Commands
+
+```bash
+npm install
+npm run dev
+npm run release
+```
+
+`npm run release` writes the deploy artifact to `out/`.
+
+## Shape
+
+```txt
+public/                  static assets copied by Vite
+src/
+  main.ts                imports global CSS and mounts the router
+  app.routes.ts          app map: zones, layouts, guards and modules
+  layouts/               app-zone shells
+  shared/
+    http/                HTTP client and interceptors
+    lib/                 pure utilities
+    styles/              tokens, reset, shell and content CSS
+    ui/                  reusable x-* components
+  modules/               business modules
+    <name>/
+      <name>.routes.ts
+      <name>.public.ts
+      <name>.types.ts
+      pages/
+      data/
+      api/
+      components/
+      _contracts/
+```
+
+## CSS Contract
+
+- `tokens.css` defines CSS custom properties and is safe for Shadow DOM
+  components through `var(...)`.
+- `reset.css` normalizes the document/light DOM surface.
+- `shell.css` styles app-zone layouts from `src/layouts/`.
+- `content.css` styles page-level light DOM: forms, tables, prose and simple
+  states.
+- Reusable leaf components keep their own styles in ``css`...` `` inside
+  `component()` options.
+
+Vite uses Lightning CSS for CSS transforms/minification in this starter.
+
+## Generate Files
+
+```bash
+npm run new -- module billing
+npm run new -- page billing/pages/invoices-list
+npm run new -- connector billing/api/stripe
+npm run new -- resource billing/data/invoices
+npm run new -- service billing/cart
+npm run new -- form billing/invoice
+npm run new -- component billing/components/invoice-status-badge
+npm run new -- guard billing/billing
+npm run new -- layout admin-shell
+```
+
+The generator writes files only. Wire new routes in `src/app.routes.ts` or the
+module route map by hand.
+
+## More
+
+The full architecture guide lives in the framework docs:
+https://github.com/madojs/mado/tree/main/docs/en

package/starters/default/eslint.config.mjs

@@ -0,0 +1,256 @@
+// ESLint config for the Mado modular starter.
+//
+// Goals:
+//   1. Enforce architectural boundaries (shared/ vs modules/, public surface).
+//   2. Enforce file-form conventions (a *.connector.ts cannot import a *.page.ts, etc.).
+//   3. Forbid barrel files and runtime CSS imports outside main.ts.
+//
+// One ESLint config, always strict. There is no "loose" mode.
+
+import tseslint from "@typescript-eslint/eslint-plugin";
+import tsparser from "@typescript-eslint/parser";
+import boundaries from "eslint-plugin-boundaries";
+
+export default [
+  {
+    files: ["src/**/*.ts"],
+    languageOptions: {
+      parser: tsparser,
+      parserOptions: {
+        ecmaVersion: 2022,
+        sourceType: "module",
+        project: "./tsconfig.json",
+      },
+    },
+    plugins: {
+      "@typescript-eslint": tseslint,
+      boundaries,
+    },
+    settings: {
+      "boundaries/elements": [
+        // App composition root — entry points + manifest.
+        { type: "app-root", pattern: "src/{main,app.routes}.ts", mode: "file" },
+
+        // App-level layouts. Live in src/layouts/ because they describe
+        // app zones (auth zone, app zone, marketing zone), not domains.
+        { type: "app-layout", pattern: "src/layouts/*.layout.ts", mode: "file" },
+
+        // Cross-cutting layer.
+        { type: "shared", pattern: "src/shared/**" },
+
+        // Module sub-layers (more specific patterns first).
+        // NB: there is no `module-layout` — modules don't own layouts.
+        { type: "module-public", pattern: "src/modules/*/*.public.ts", mode: "file" },
+        { type: "module-types", pattern: "src/modules/*/*.types.ts", mode: "file" },
+        { type: "module-routes", pattern: "src/modules/*/*.routes.ts", mode: "file" },
+        { type: "module-guard", pattern: "src/modules/*/*.guard.ts", mode: "file" },
+        { type: "module-contracts", pattern: "src/modules/*/_contracts/**" },
+        { type: "module-connector", pattern: "src/modules/**/*.connector.ts", mode: "file" },
+        { type: "module-resource", pattern: "src/modules/**/*.resource.ts", mode: "file" },
+        { type: "module-service", pattern: "src/modules/**/*.service.ts", mode: "file" },
+        { type: "module-form", pattern: "src/modules/**/*.form.ts", mode: "file" },
+        { type: "module-page", pattern: "src/modules/**/*.page.ts", mode: "file" },
+        { type: "module-component", pattern: "src/modules/**/*.component.ts", mode: "file" },
+        { type: "module-internal", pattern: "src/modules/*/**" },
+      ],
+      "boundaries/include": ["src/**/*.ts"],
+    },
+    rules: {
+      // ---------------------------------------------------------------------
+      // 1. Module boundaries
+      // ---------------------------------------------------------------------
+      "boundaries/element-types": [
+        2,
+        {
+          default: "disallow",
+          rules: [
+            // app-root may import anything (it composes the app)
+            { from: "app-root", allow: ["*"] },
+
+            // app-layout: pure UI wrapper. May read other modules' public
+            // for nav state (auth, i18n…). No connectors/resources/services.
+            {
+              from: "app-layout",
+              allow: ["shared", "module-public", "module-types"],
+            },
+
+            // shared/* lives in isolation
+            { from: "shared", allow: ["shared"] },
+
+            // module-public: gateway only re-exports module internals
+            {
+              from: "module-public",
+              allow: [
+                "shared",
+                "module-internal",
+                "module-types",
+                "module-service",
+                "module-resource",
+                "module-form",
+                "module-guard",
+              ],
+            },
+
+            // module-types are pure types
+            { from: "module-types", allow: ["module-types"] },
+
+            // module-routes: plain map of paths to lazy pages of THIS module.
+            // Modules do not own layouts — composition happens in app.routes.ts.
+            {
+              from: "module-routes",
+              allow: ["module-page"],
+            },
+
+            // module-guard: reads service state of its own module
+            {
+              from: "module-guard",
+              allow: ["module-service", "module-public", "module-types", "shared"],
+            },
+
+            // _contracts are private DTOs of one connector
+            { from: "module-contracts", allow: ["module-contracts"] },
+
+            // Connectors talk to HTTP and contracts. No UI, no signals.
+            {
+              from: "module-connector",
+              allow: ["shared", "module-contracts", "module-types"],
+            },
+
+            // Resources/mutations bridge connector ↔ app
+            {
+              from: "module-resource",
+              allow: ["shared", "module-connector", "module-types", "module-public"],
+            },
+
+            // Services hold module state. May talk to other modules' public.
+            {
+              from: "module-service",
+              allow: [
+                "shared",
+                "module-connector",
+                "module-resource",
+                "module-types",
+                "module-public",
+              ],
+            },
+
+            // Forms = schema + validators
+            {
+              from: "module-form",
+              allow: ["shared", "module-types", "module-public"],
+            },
+
+            // Pages may use everything inside their own module + shared + others' public
+            {
+              from: "module-page",
+              allow: [
+                "shared",
+                "module-component",
+                "module-service",
+                "module-resource",
+                "module-form",
+                "module-types",
+                "module-public",
+                "module-internal",
+              ],
+            },
+
+            // Reusable components stay UI-only: no business state.
+            {
+              from: "module-component",
+              allow: ["shared", "module-component", "module-types"],
+            },
+
+            // Fallback for module-internal helpers (_parts/*, etc.)
+            {
+              from: "module-internal",
+              allow: ["shared", "module-internal", "module-types", "module-public"],
+            },
+          ],
+        },
+      ],
+
+      // ---------------------------------------------------------------------
+      // 2. No barrel files. Encourages explicit imports, helps tree-shaking
+      //    and reduces LLM context noise.
+      // ---------------------------------------------------------------------
+      "no-restricted-syntax": [
+        "error",
+        {
+          selector: "ExportAllDeclaration",
+          message:
+            "Barrel re-exports are forbidden. Re-export individual symbols in *.public.ts.",
+        },
+      ],
+
+      // ---------------------------------------------------------------------
+      // 3. Imports
+      // ---------------------------------------------------------------------
+      "no-restricted-imports": [
+        "error",
+        {
+          patterns: [
+            {
+              group: ["**/index", "**/index.ts", "**/index.js"],
+              message: "Do not import from index files. Import the file directly.",
+            },
+          ],
+        },
+      ],
+
+      // ---------------------------------------------------------------------
+      // 4. TypeScript hygiene
+      // ---------------------------------------------------------------------
+      "@typescript-eslint/consistent-type-imports": ["error", { prefer: "type-imports" }],
+      "@typescript-eslint/no-explicit-any": "warn",
+      "@typescript-eslint/no-unused-vars": [
+        "error",
+        { argsIgnorePattern: "^_", varsIgnorePattern: "^_" },
+      ],
+    },
+  },
+
+  // Only main.ts may import CSS at runtime.
+  {
+    files: ["src/**/*.ts"],
+    ignores: ["src/main.ts"],
+    rules: {
+      "no-restricted-imports": [
+        "error",
+        {
+          patterns: [
+            {
+              group: ["*.css", "**/*.css"],
+              message:
+                "Import CSS only in src/main.ts. Component styles must use css`` inside the component file.",
+            },
+            {
+              group: ["**/index", "**/index.ts", "**/index.js"],
+              message: "Do not import from index files. Import the file directly.",
+            },
+          ],
+        },
+      ],
+    },
+  },
+
+  // _contracts are DTOs for connectors only.
+  {
+    files: ["src/**/*.ts"],
+    ignores: ["src/**/*.connector.ts"],
+    rules: {
+      "no-restricted-imports": [
+        "error",
+        {
+          patterns: [
+            {
+              group: ["**/_contracts/*"],
+              message:
+                "External DTOs (_contracts) are private to the connector. Use the domain type instead.",
+            },
+          ],
+        },
+      ],
+    },
+  },
+];

package/starters/default/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <link rel="icon" href="/favicon.svg" />
+    <title>Mado App</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

package/starters/default/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "__APP_NAME__",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "mado dev",
+    "build": "mado release",
+    "typecheck": "mado typecheck",
+    "test": "npm run typecheck && npm run lint",
+    "release": "mado release",
+    "preview": "mado preview",
+    "lint": "eslint \"src/**/*.ts\"",
+    "lint:fix": "eslint \"src/**/*.ts\" --fix",
+    "new": "mado new"
+  },
+  "dependencies": {
+    "@madojs/mado": "__MADOJS_VERSION__"
+  },
+  "devDependencies": {
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "eslint": "^9.0.0",
+    "eslint-plugin-boundaries": "^5.0.0",
+    "linkedom": "^0.18.12",
+    "lightningcss": "^1.32.0",
+    "typescript": "^5.5.0",
+    "vite": "^8.0.16"
+  }
+}

package/starters/default/public/favicon.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">
+  <rect width="64" height="64" rx="14" fill="#0f172a"/>
+  <path fill="#fff" d="M16 45V19h8l8 12 8-12h8v26h-8V31l-8 12-8-12v14z"/>
+</svg>

package/starters/default/src/app.routes.ts

@@ -0,0 +1,39 @@
+// Single source of truth for the application route table.
+//
+// This file is the APP MAP. Reading it = understanding the app.
+//
+// One rule:
+//   Modules export plain `routes` maps. The choice of SHELL and GUARD for
+//   each zone of the app is made HERE, by wrapping a module's routes with
+//   a `layout({...})` block.
+//
+// `manifest` is exported separately so `mado bake` can discover pages that
+// declare `bake: { paths, data }`.
+
+import { layout, routes } from "@madojs/mado";
+
+import { requireAuth } from "./modules/auth/auth.public";
+import { authRoutes } from "./modules/auth/auth.routes";
+import { billingRoutes } from "./modules/billing/billing.routes";
+
+export const manifest = {
+  // Public landing (no shell, no guard).
+  "/": () => import("./modules/home/home.page"),
+
+  // AUTH ZONE — centered card, no guard.
+  "/login": layout({
+    layout: () => import("./layouts/auth-shell.layout"),
+    routes: authRoutes,
+  }),
+
+  // APP ZONE — header + nav, guarded by requireAuth.
+  "/billing": layout({
+    layout: () => import("./layouts/app-shell.layout"),
+    guard: requireAuth,
+    routes: billingRoutes,
+  }),
+
+  "*": () => import("./modules/home/not-found.page"),
+};
+
+export default routes(manifest);

package/starters/default/src/layouts/app-shell.layout.ts

@@ -0,0 +1,35 @@
+// App-wide shell used by the authenticated zone (every module that lives
+// behind requireAuth).
+//
+// A layout is a STRAIGHTFORWARD wrapper:
+//   - it owns the chrome (header / nav / footer);
+//   - it does NOT know which page is rendered inside (`child` is anonymous);
+//   - it does NOT keep per-route state;
+//   - it MAY read cross-cutting modules' public surfaces (auth, i18n…).
+//
+// Layouts live in src/layouts/ because they describe APP ZONES, not domains.
+
+import { html, page } from "@madojs/mado";
+
+import { isAuthed, logout, user } from "../modules/auth/auth.public";
+import "../shared/ui/x-button.component";
+
+export default page({
+  title: "Mado App",
+  view: ({ child }) => html`
+    <div class="layout layout--app">
+      <header class="app-header">
+        <a href="/" class="brand">Mado App</a>
+        <nav>
+          <a href="/billing/invoices">Invoices</a>
+          ${() =>
+            isAuthed()
+              ? html`<span class="who">${() => user()?.email ?? ""}</span>
+                  <x-button variant="ghost" @click=${logout}>Sign out</x-button>`
+              : html`<a href="/login">Sign in</a>`}
+        </nav>
+      </header>
+      <main class="app-main">${child}</main>
+    </div>
+  `,
+});