@madojs/mado 0.5.0

package/scripts/cli.mjs

@@ -0,0 +1,382 @@
+#!/usr/bin/env node
+
+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 http from "node:http";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+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;
+
+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 command = rawCommand ?? "help";
+
+switch (command) {
+  case "init":
+    await runInit(args);
+    break;
+  case "build":
+    await runNodeBin("typescript/bin/tsc", args);
+    break;
+  case "watch":
+    await runNodeBin("typescript/bin/tsc", ["-w", ...args]);
+    break;
+  case "typecheck":
+    await runNodeBin("typescript/bin/tsc", ["--noEmit", ...args]);
+    break;
+  case "test":
+    if (args[0] === "browser") {
+      await runNodeScript("scripts/showcase-regression.mjs", args.slice(1));
+    } else {
+      const files = await listTestFiles();
+      await run(process.execPath, ["--test", "--test-timeout=10000", ...files, ...args]);
+    }
+    break;
+  case "serve":
+    await runServe(args[0] ?? "");
+    break;
+  case "dev":
+    await runDev(args[0] ?? "");
+    break;
+  case "bake":
+    await runNodeScript("scripts/bake.mjs", args);
+    break;
+  case "bundle":
+    await runNodeScript("scripts/bundle.mjs", args);
+    break;
+  case "preview":
+    await runNodeScript("scripts/preview.mjs", args);
+    break;
+  case "new":
+    await runNodeScript("scripts/new.mjs", args);
+    break;
+  case "examples":
+    printExamples();
+    break;
+  case "help":
+  case "--help":
+  case "-h":
+    printHelp();
+    break;
+  default:
+    console.error(`[mado] unknown command: ${command}`);
+    printHelp();
+    process.exit(1);
+}
+
+async function runServe(example) {
+  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 || "" },
+  });
+}
+
+async function runInit(rawArgs) {
+  const { flags, positional } = parseFlags(rawArgs);
+  const targetArg = positional[0];
+  if (!targetArg) {
+    console.error("[mado] usage: mado init <name> [--starter minimal|crud] [--force]");
+    process.exit(1);
+  }
+
+  const starter = String(flags.starter ?? "minimal");
+  if (!STARTERS.includes(starter)) {
+    console.error(`[mado] unknown starter: ${starter}`);
+    console.error(`[mado] available starters: ${STARTERS.join(", ")}`);
+    process.exit(1);
+  }
+
+  const target = resolve(PROJECT_ROOT, targetArg);
+  const source = join(PACKAGE_ROOT, "starters", starter);
+  if (!existsSync(source)) {
+    console.error(`[mado] missing starter template: ${starter}`);
+    process.exit(1);
+  }
+  if (existsSync(target) && statSync(target).isFile()) {
+    console.error(`[mado] target exists and is a file: ${target}`);
+    process.exit(1);
+  }
+  if (existsSync(target) && readdirSync(target).length > 0 && !flags.force) {
+    console.error(`[mado] target directory is not empty: ${target}`);
+    console.error("[mado] use --force to write into it");
+    process.exit(1);
+  }
+
+  await mkdir(target, { recursive: true });
+  await cp(source, target, { recursive: true, force: true });
+  await copyCanonicalAgentFiles(target);
+
+  const packageName = packageNameFromDir(target);
+  if (!isValidPackageName(packageName)) {
+    console.error(`[mado] invalid package name derived from target: ${packageName}`);
+    process.exit(1);
+  }
+
+  const replacements = {
+    __APP_NAME__: packageName,
+    __PACKAGE_NAME__: packageName,
+    __MADOJS_VERSION__: process.env.MADO_PACKAGE_SPEC || process.env.MADOJS_PACKAGE_SPEC || `^${PACKAGE_JSON.version}`,
+    __MADO_VERSION__: PACKAGE_JSON.version,
+  };
+
+  for (const file of await walkFiles(target)) {
+    const text = await readFile(file, "utf8").catch(() => null);
+    if (text === null) continue;
+    let next = text;
+    for (const [key, value] of Object.entries(replacements)) {
+      next = next.split(key).join(value);
+    }
+    if (next !== text) await writeFile(file, next);
+  }
+
+  console.log("");
+  console.log(`Created ${packageName} with the ${starter} starter.`);
+  console.log("");
+  console.log("Next steps:");
+  console.log(`  cd ${relativePath(PROJECT_ROOT, target)}`);
+  console.log("  npm install");
+  console.log("  npm run build");
+  console.log("  npm run serve");
+  console.log("");
+}
+
+async function runDev(example) {
+  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 tsc = spawn(process.execPath, [resolveBin("typescript/bin/tsc"), "-w"], {
+    cwd: PROJECT_ROOT,
+    stdio: "inherit",
+  });
+
+  const children = [server, tsc];
+  let shuttingDown = false;
+
+  const shutdown = (code = 0) => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    for (const child of children) {
+      if (!child.killed) child.kill("SIGTERM");
+    }
+    setTimeout(() => process.exit(code), 80);
+  };
+
+  process.on("SIGINT", () => shutdown(0));
+  process.on("SIGTERM", () => shutdown(0));
+
+  await Promise.race(
+    children.map(
+      (child) =>
+        new Promise((resolveExit) => {
+          child.on("exit", (code, signal) => resolveExit({ code, signal }));
+        }),
+    ),
+  ).then(({ code, signal }) => {
+    if (signal) shutdown(1);
+    else shutdown(code ?? 0);
+  });
+}
+
+async function copyCanonicalAgentFiles(target) {
+  for (const file of ["AGENTS.md", "llms.txt"]) {
+    const source = join(PACKAGE_ROOT, file);
+    if (existsSync(source)) await copyFile(source, join(target, file));
+  }
+}
+
+async function runNodeBin(bin, args) {
+  await run(process.execPath, [resolveBin(bin), ...args]);
+}
+
+async function runNodeScript(script, args) {
+  await run(process.execPath, [join(PACKAGE_ROOT, script), ...args]);
+}
+
+async function run(cmd, args, options = {}) {
+  const child = spawn(cmd, args, {
+    cwd: PROJECT_ROOT,
+    stdio: "inherit",
+    env: options.env ?? process.env,
+    shell: options.shell ?? false,
+  });
+  const code = await new Promise((resolveExit) => {
+    child.on("exit", (status) => resolveExit(status ?? 1));
+  });
+  if (code !== 0) process.exit(code);
+}
+
+function resolveBin(bin) {
+  const projectPath = join(PROJECT_ROOT, "node_modules", bin);
+  if (existsSync(projectPath)) return projectPath;
+  const path = join(PACKAGE_ROOT, "node_modules", bin);
+  if (!existsSync(path)) {
+    console.error(`[mado] missing ${bin}. Run npm install first.`);
+    process.exit(1);
+  }
+  return path;
+}
+
+function assertExample(name, { serveable }) {
+  const dir = join(PROJECT_ROOT, "examples", name);
+  if (!existsSync(dir)) {
+    console.error(`[mado] unknown example: ${name}`);
+    printExamples();
+    process.exit(1);
+  }
+  if (serveable && !existsSync(join(dir, "index.html"))) {
+    console.error(`[mado] example "${name}" is not a browser SPA example.`);
+    process.exit(1);
+  }
+}
+
+function printExamples() {
+  console.log("Available examples:");
+  for (const [name, description] of EXAMPLES) {
+    const marker = existsSync(join(PROJECT_ROOT, "examples", name, "index.html")) ? "serve" : "docs";
+    console.log(`  ${name.padEnd(10)} ${marker.padEnd(5)} ${description}`);
+  }
+}
+
+async function listTestFiles() {
+  const dir = join(PROJECT_ROOT, "test");
+  const files = await readdir(dir);
+  return files
+    .filter((file) => file.endsWith(".test.mjs"))
+    .sort()
+    .map((file) => join("test", file));
+}
+
+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`);
+}
+
+function parseFlags(raw) {
+  const flags = {};
+  const positional = [];
+  for (let i = 0; i < raw.length; i++) {
+    const arg = raw[i];
+    if (arg === "--") continue;
+    if (arg.startsWith("--")) {
+      const [name, inline] = arg.slice(2).split("=");
+      if (inline !== undefined) flags[name] = inline;
+      else if (raw[i + 1] && !raw[i + 1].startsWith("-")) flags[name] = raw[++i];
+      else flags[name] = true;
+    } else {
+      positional.push(arg);
+    }
+  }
+  return { flags, positional };
+}
+
+function packageNameFromDir(target) {
+  return target
+    .split(/[\\/]/)
+    .filter(Boolean)
+    .at(-1)
+    ?.toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "") || "mado-app";
+}
+
+function isValidPackageName(name) {
+  return /^(?:@[a-z0-9._-]+\/)?[a-z0-9][a-z0-9._-]*$/.test(name)
+    && !name.includes("..")
+    && !name.startsWith(".")
+    && name.length <= 214;
+}
+
+async function walkFiles(dir) {
+  const out = [];
+  for (const entry of readdirSync(dir)) {
+    if (["node_modules", "dist", ".git"].includes(entry)) continue;
+    if (entry === "package-lock.json") continue;
+    const file = join(dir, entry);
+    const stat = statSync(file);
+    if (stat.isDirectory()) out.push(...await walkFiles(file));
+    else out.push(file);
+  }
+  return out;
+}
+
+function relativePath(from, to) {
+  const rel = to.startsWith(from) ? to.slice(from.length).replace(/^[/\\]/, "") : to;
+  return rel || ".";
+}
+
+function contentType(file) {
+  const ext = file.slice(file.lastIndexOf("."));
+  return {
+    ".html": "text/html; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".mjs": "text/javascript; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".json": "application/json; charset=utf-8",
+    ".svg": "image/svg+xml",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".webp": "image/webp",
+    ".ico": "image/x-icon",
+  }[ext] ?? "application/octet-stream";
+}
+
+async function serveStaticProject(rootDir) {
+  const port = Number(process.env.PORT || 5173);
+  const server = http.createServer((req, res) => {
+    const url = new URL(req.url || "/", `http://localhost:${port}`);
+    const pathname = decodeURIComponent(url.pathname);
+    const normalized = pathname.replace(/^\/+/, "");
+    let file = resolve(rootDir, normalized);
+    if (pathname === "/" || !normalized.includes(".")) file = join(rootDir, "index.html");
+    if (!file.startsWith(rootDir) || !existsSync(file) || statSync(file).isDirectory()) {
+      file = join(rootDir, "index.html");
+    }
+
+    if (!existsSync(file)) {
+      res.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
+      res.end("Not found");
+      return;
+    }
+
+    res.writeHead(200, { "content-type": contentType(file) });
+    res.end(readFileSync(file));
+  });
+
+  await new Promise((resolveListen) => {
+    server.listen(port, resolveListen);
+  });
+  console.log(`[mado] serving ${rootDir}`);
+  console.log(`[mado] http://localhost:${port}`);
+}

package/scripts/new.mjs

@@ -0,0 +1,80 @@
+// Scaffold a new page from templates/.
+//
+//   node scripts/new.mjs list users
+//   node scripts/new.mjs form sign-up
+//   node scripts/new.mjs detail post
+//
+// Result: examples/pages/<name>.ts (or src/pages/, when present)
+// with __name__ / __Name__ placeholders replaced.
+//
+// Zero dependencies.
+
+import { readFile, writeFile, mkdir, access } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const PROJECT_ROOT = resolve(process.cwd());
+
+const [, , kind, rawName] = process.argv;
+
+if (!kind || !rawName) {
+  console.error("usage: node scripts/new.mjs <list|form|detail> <name>");
+  process.exit(1);
+}
+
+const templates = {
+  list: "templates/page-list.ts",
+  form: "templates/page-form.ts",
+  detail: "templates/page-detail.ts",
+};
+
+const tplPath = templates[kind];
+if (!tplPath) {
+  console.error(`unknown template: ${kind} (available: list, form, detail)`);
+  process.exit(1);
+}
+
+// name → kebab-case (for file names and tags)
+const kebab = rawName.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+// Name → PascalCase for titles
+const pascal = kebab
+  .split("-")
+  .filter(Boolean)
+  .map((p) => p[0].toUpperCase() + p.slice(1))
+  .join("");
+
+const targetDir = (await exists("src/pages"))
+  ? "src/pages"
+  : (await exists("examples/basic/pages"))
+    ? "examples/basic/pages"
+    : "src/pages";
+await mkdir(targetDir, { recursive: true });
+
+const targetFile = join(
+  targetDir,
+  kind === "detail" ? `${kebab}-detail.ts` : `${kebab}.ts`,
+);
+
+if (await exists(targetFile)) {
+  console.error(`already exists: ${targetFile}`);
+  process.exit(1);
+}
+
+const src = await readFile(join(PACKAGE_ROOT, tplPath), "utf8");
+const out = src.replaceAll("__name__", kebab).replaceAll("__Name__", pascal);
+
+await writeFile(targetFile, out);
+console.log(`✓ created: ${targetFile}`);
+console.log(`  remember to add this to routes.ts:`);
+const routePath = kind === "detail" ? `/${kebab}/:id` : `/${kebab}`;
+console.log(`    '${routePath}': () => import('./pages/${kebab}${kind === "detail" ? "-detail" : ""}.js'),`);
+
+async function exists(p) {
+  try {
+    await access(join(PROJECT_ROOT, p));
+    return true;
+  } catch {
+    return false;
+  }
+}

package/scripts/preview.mjs

@@ -0,0 +1,176 @@
+// Preview: a tiny production-like server that emulates nginx.conf on node:http.
+//
+//   npm run 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:
+//        - immutable cache for hashed bundles;
+//        - SPA fallback to index.html;
+//        - baked HTML priority over index.html;
+//        - precompressed .gz / .br serving via Accept-Encoding.
+//
+// Goal: see production-like output locally without Docker/nginx.
+
+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";
+
+const MIME = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".mjs": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".ico": "image/x-icon",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".webp": "image/webp",
+  ".woff2": "font/woff2",
+  ".xml": "application/xml; charset=utf-8",
+  ".map": "application/json; charset=utf-8",
+};
+
+// ---------- 1-3) Full build ----------
+
+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"]);
+}
+
+if (!(await exists(OUT))) {
+  console.error(`[preview] missing ${OUT}/ — check the steps above`);
+  process.exit(1);
+}
+
+// ---------- 4) Server ----------
+
+const isImmutable = (filename) =>
+  /^(main|chunk|asset)-[A-Z0-9]+\.js$/i.test(filename);
+
+const server = createServer(async (req, res) => {
+  try {
+    const url = new URL(req.url ?? "/", `http://${req.headers.host}`);
+    const pathname = decodeURIComponent(url.pathname);
+    const accepts = (req.headers["accept-encoding"] ?? "").toString();
+
+    const target = await resolveTarget(pathname);
+    if (!target) {
+      res.writeHead(404).end("not found");
+      return;
+    }
+
+    // Choose encoding: br > gz > raw.
+    let { path: filePath, encoding } = await pickEncoding(target, accepts);
+    const data = await readFile(filePath);
+    const baseExt = extname(target).toLowerCase();
+    const type = MIME[baseExt] ?? "application/octet-stream";
+
+    const cache = isImmutable(basenameSafe(target))
+      ? "public, max-age=31536000, immutable"
+      : baseExt === ".html"
+        ? "no-cache, must-revalidate"
+        : "public, max-age=86400";
+
+    const headers = {
+      "content-type": type,
+      "cache-control": cache,
+      vary: "Accept-Encoding",
+    };
+    if (encoding) headers["content-encoding"] = encoding;
+
+    res.writeHead(200, headers);
+    res.end(data);
+  } catch (err) {
+    console.error("[preview] error:", err);
+    res.writeHead(500).end(String(err));
+  }
+});
+
+server.listen(PORT, () => {
+  console.log(`\n[preview] http://localhost:${PORT}/  (Ctrl-C — stop)\n`);
+});
+
+// ---------- helpers ----------
+
+function run(cmd, args, { allowFail = false } = {}) {
+  const r = spawnSync(cmd, args, { stdio: "inherit" });
+  if (r.status !== 0 && !allowFail) {
+    console.error(`[preview] command "${cmd} ${args.join(" ")}" exited with ${r.status}`);
+    process.exit(r.status ?? 1);
+  }
+}
+
+async function exists(p) {
+  try {
+    await access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function basenameSafe(p) {
+  const i = Math.max(p.lastIndexOf("/"), p.lastIndexOf(sep));
+  return i >= 0 ? p.slice(i + 1) : p;
+}
+
+async function resolveTarget(pathname) {
+  if (pathname === "/") pathname = "/index.html";
+
+  const candidate = resolve(join(OUT, pathname));
+  if (!candidate.startsWith(OUT + sep) && candidate !== OUT) return null;
+
+  // 1) Exact match
+  if (await exists(candidate)) {
+    const s = await stat(candidate);
+    if (s.isDirectory()) {
+      // Baked priority: /product/foo/ → /product/foo/index.html
+      const idx = join(candidate, "index.html");
+      if (await exists(idx)) return idx;
+    } else {
+      return candidate;
+    }
+  }
+
+  // 2) /foo → /foo/index.html (for baked pages without trailing slash)
+  if (!extname(pathname)) {
+    const asDir = join(OUT, pathname, "index.html");
+    if (await exists(asDir)) return asDir;
+  }
+
+  // 3) SPA-fallback
+  const spa = join(OUT, "index.html");
+  if (await exists(spa)) return spa;
+
+  return null;
+}
+
+async function pickEncoding(file, accepts) {
+  if (file.endsWith(".js") || file.endsWith(".css") || file.endsWith(".html")) {
+    if (accepts.includes("br") && (await exists(`${file}.br`))) {
+      return { path: `${file}.br`, encoding: "br" };
+    }
+    if (accepts.includes("gzip") && (await exists(`${file}.gz`))) {
+      return { path: `${file}.gz`, encoding: "gzip" };
+    }
+  }
+  return { path: file, encoding: null };
+}

package/scripts/release-notes.mjs

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+import { execSync } from "node:child_process";
+
+function sh(command) {
+  return execSync(command, { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+}
+
+function safe(command) {
+  try {
+    return sh(command);
+  } catch {
+    return "";
+  }
+}
+
+const tag = process.env.GITHUB_REF_NAME || safe("git describe --tags --exact-match") || "HEAD";
+const previous = safe(`git describe --tags --abbrev=0 ${tag}^`);
+const range = previous ? `${previous}..${tag}` : tag;
+const log = safe(`git log --format=%s ${range}`);
+
+const groups = [
+  ["Features", /^feat(?:\(.+\))?:\s+(.+)/],
+  ["Fixes", /^fix(?:\(.+\))?:\s+(.+)/],
+  ["Documentation", /^docs(?:\(.+\))?:\s+(.+)/],
+  ["Tests", /^test(?:\(.+\))?:\s+(.+)/],
+  ["CI", /^ci(?:\(.+\))?:\s+(.+)/],
+  ["Maintenance", /^(?:chore|refactor)(?:\(.+\))?:\s+(.+)/],
+];
+
+const notes = new Map(groups.map(([name]) => [name, []]));
+const other = [];
+
+for (const line of log.split("\n").map((item) => item.trim()).filter(Boolean)) {
+  let matched = false;
+  for (const [name, pattern] of groups) {
+    const match = line.match(pattern);
+    if (match) {
+      notes.get(name).push(match[1]);
+      matched = true;
+      break;
+    }
+  }
+  if (!matched) other.push(line);
+}
+
+console.log(`# ${tag}`);
+console.log("");
+if (previous) console.log(`Changes since ${previous}.`);
+else console.log("First public release.");
+console.log("");
+
+for (const [name] of groups) {
+  const items = notes.get(name);
+  if (!items.length) continue;
+  console.log(`## ${name}`);
+  console.log("");
+  for (const item of items) console.log(`- ${item}`);
+  console.log("");
+}
+
+if (other.length) {
+  console.log("## Other");
+  console.log("");
+  for (const item of other) console.log(`- ${item}`);
+  console.log("");
+}