@madojs/mado 0.11.1 → 0.13.0

package/scripts/cli/run.mjs

@@ -3,6 +3,8 @@ import { existsSync } from "node:fs";
 import { readdir, readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 
+import { logger } from "../logger.mjs";
+
 export async function run(cmd, args, options = {}) {
   const child = spawn(cmd, args, {
     cwd: options.cwd,
@@ -48,7 +50,7 @@ export function resolvePackageBin(ctx, pkg, binPath) {
   if (existsSync(projectPath)) return projectPath;
   const packagePath = join(ctx.packageRoot, "node_modules", pkg, binPath);
   if (existsSync(packagePath)) return packagePath;
-  console.error(`[mado] missing ${pkg}. Install it in this project: npm i -D ${pkg}`);
+  logger.error("mado", "missing-package", `missing ${pkg}. Install it in this project: npm i -D ${pkg}`);
   process.exit(1);
 }
 
@@ -57,7 +59,7 @@ export function resolveBin(ctx, bin) {
   if (existsSync(projectPath)) return projectPath;
   const packagePath = join(ctx.packageRoot, "node_modules", bin);
   if (!existsSync(packagePath)) {
-    console.error(`[mado] missing ${bin}. Run npm install first.`);
+    logger.error("mado", "missing-binary", `missing ${bin}. Run npm install first.`);
     process.exit(1);
   }
   return packagePath;
@@ -66,7 +68,7 @@ export function resolveBin(ctx, bin) {
 export async function writeIfMissing(path, content, logPrefix = "[mado]") {
   if (existsSync(path)) return;
   await writeFile(path, content);
-  console.log(`${logPrefix} wrote ${path}`);
+  logger.info("release", "write", `wrote ${path}`, { prefix: logPrefix });
 }
 
 export async function listTestFiles(projectRoot) {

package/scripts/logger.mjs

@@ -0,0 +1,117 @@
+const LEVELS = { debug: 10, info: 20, warn: 30, error: 40, silent: 50 };
+const COLORS = {
+  debug: "\u001b[2m",
+  info: "\u001b[36m",
+  warn: "\u001b[33m",
+  error: "\u001b[31m",
+};
+
+let level = normaliseLevel(process.env.MADO_LOG_LEVEL) ?? "info";
+let format = normaliseFormat(process.env.MADO_LOG_FORMAT) ?? "auto";
+
+export function configureLogger(argv) {
+  const clean = [];
+  for (let index = 0; index < argv.length; index++) {
+    const arg = argv[index];
+    const [name, inline] = arg.split("=", 2);
+    if (name === "--log-level" || name === "--log-format") {
+      const value = inline ?? argv[++index];
+      if (!value) throw new Error(`${name} requires a value`);
+      if (name === "--log-level") {
+        const next = normaliseLevel(value);
+        if (!next) throw new Error(`invalid log level: ${value}`);
+        level = next;
+      } else {
+        const next = normaliseFormat(value);
+        if (!next) throw new Error(`invalid log format: ${value}`);
+        format = next;
+      }
+      continue;
+    }
+    if (arg === "--no-color") {
+      format = "plain";
+      continue;
+    }
+    clean.push(arg);
+  }
+  return clean;
+}
+
+export function diagnostic(levelName, scope, code, message, data) {
+  if (LEVELS[levelName] < LEVELS[level]) return;
+  const record = {
+    timestamp: new Date().toISOString(),
+    level: levelName,
+    scope,
+    code,
+    message,
+    ...(data === undefined ? {} : { data }),
+  };
+  const stream = levelName === "warn" || levelName === "error"
+    ? process.stderr
+    : process.stdout;
+  if (resolvedFormat(stream) === "json") {
+    stream.write(`${JSON.stringify(record, safeJson)}\n`);
+    return;
+  }
+  const prefix = scope === "mado" ? "[mado]" : `[${scope}]`;
+  const suffix = data === undefined ? "" : ` ${safePreview(data)}`;
+  const line = `${prefix}${code ? ` ${code}` : ""} ${message}${suffix}`;
+  if (resolvedFormat(stream) === "pretty") {
+    stream.write(`${COLORS[levelName] ?? ""}${line}\u001b[0m\n`);
+  } else {
+    stream.write(`${line}\n`);
+  }
+}
+
+export const logger = {
+  debug(scope, code, message, data) {
+    diagnostic("debug", scope, code, message, data);
+  },
+  info(scope, code, message, data) {
+    diagnostic("info", scope, code, message, data);
+  },
+  warn(scope, code, message, data) {
+    diagnostic("warn", scope, code, message, data);
+  },
+  error(scope, code, message, data) {
+    diagnostic("error", scope, code, message, data);
+  },
+};
+
+function resolvedFormat(stream) {
+  if (format !== "auto") return format;
+  if (process.env.NO_COLOR !== undefined || !stream.isTTY) return "plain";
+  return "pretty";
+}
+
+function normaliseLevel(value) {
+  if (!value) return null;
+  const candidate = String(value).toLowerCase();
+  return Object.hasOwn(LEVELS, candidate) ? candidate : null;
+}
+
+function normaliseFormat(value) {
+  if (!value) return null;
+  const candidate = String(value).toLowerCase();
+  return ["auto", "pretty", "plain", "json"].includes(candidate)
+    ? candidate
+    : null;
+}
+
+function safeJson(_key, value) {
+  if (typeof value === "bigint") return `${value}n`;
+  if (value instanceof Error) {
+    return { name: value.name, message: value.message, stack: value.stack };
+  }
+  return value;
+}
+
+function safePreview(value) {
+  try {
+    const text = JSON.stringify(value, safeJson);
+    return text.length > 500 ? `${text.slice(0, 497)}...` : text;
+  } catch {
+    return String(value);
+  }
+}

package/scripts/output-guard.mjs

@@ -0,0 +1,128 @@
+import { existsSync } from "node:fs";
+import { mkdir, readdir, realpath, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+
+export const OUTPUT_SENTINEL = ".mado-output";
+const BUILD_BRIDGE = join("_mado", "build.json");
+const PROTECTED_PROJECT_DIRS = new Set([
+  ".git",
+  "docs",
+  "node_modules",
+  "scripts",
+  "src",
+  "starters",
+  "test",
+]);
+
+export async function prepareOutputDirectory({
+  projectRoot,
+  outDir,
+  clean = true,
+  force = false,
+}) {
+  const safe = await resolveSafeOutput(projectRoot, outDir);
+  const state = await ownershipState(safe.outDir);
+
+  if (state === "foreign" && !force) {
+    throw new Error(
+      `[mado:output] refusing to use non-empty directory not owned by Mado: ${safe.outDir}\n` +
+        `Choose an empty directory or pass --force-output after checking the path.`,
+    );
+  }
+
+  if (clean && existsSync(safe.outDir)) {
+    await rm(safe.outDir, { recursive: true, force: true });
+  }
+  await mkdir(safe.outDir, { recursive: true });
+  await writeSentinel(safe.outDir, safe.projectRoot);
+  return safe.outDir;
+}
+
+export async function claimOutputDirectory({ projectRoot, outDir, force = false }) {
+  const safe = await validateOutputDirectory({ projectRoot, outDir, force });
+  await mkdir(safe.outDir, { recursive: true });
+  await writeSentinel(safe.outDir, safe.projectRoot);
+  return safe.outDir;
+}
+
+export async function validateOutputDirectory({ projectRoot, outDir, force = false }) {
+  const safe = await resolveSafeOutput(projectRoot, outDir);
+  const state = await ownershipState(safe.outDir);
+  if (state === "foreign" && !force) {
+    throw new Error(
+      `[mado:output] refusing to write into non-empty directory not owned by Mado: ${safe.outDir}\n` +
+        `Run a Mado/Vite build first, choose another --out, or pass --force-output.`,
+    );
+  }
+  return safe;
+}
+
+export async function resolveSafeOutput(projectRoot, outDir) {
+  const project = await canonicalPath(resolve(projectRoot));
+  const output = await canonicalPath(resolve(projectRoot, outDir));
+  const home = await canonicalPath(homedir());
+
+  if (isFilesystemRoot(output)) {
+    throw new Error(`[mado:output] refusing filesystem root: ${output}`);
+  }
+  if (output === project) {
+    throw new Error(`[mado:output] refusing project root: ${output}`);
+  }
+  if (output === home) {
+    throw new Error(`[mado:output] refusing home directory: ${output}`);
+  }
+  if (isInside(output, project)) {
+    throw new Error(`[mado:output] refusing a parent of the project: ${output}`);
+  }
+
+  const projectRelative = relative(project, output);
+  if (projectRelative && !projectRelative.startsWith("..") && !isAbsolute(projectRelative)) {
+    const first = projectRelative.split(/[\\/]/, 1)[0];
+    if (PROTECTED_PROJECT_DIRS.has(first)) {
+      throw new Error(`[mado:output] refusing protected project directory: ${output}`);
+    }
+  }
+
+  return { projectRoot: project, outDir: output };
+}
+
+async function ownershipState(outDir) {
+  if (!existsSync(outDir)) return "empty";
+  const entries = await readdir(outDir);
+  if (entries.length === 0) return "empty";
+  if (existsSync(join(outDir, OUTPUT_SENTINEL))) return "owned";
+  // A build bridge is emitted by the Mado Vite plugin and is sufficient
+  // evidence for a direct `mado static` invocation after `mado build`.
+  if (existsSync(join(outDir, BUILD_BRIDGE))) return "owned";
+  return "foreign";
+}
+
+async function writeSentinel(outDir, projectRoot) {
+  await writeFile(
+    join(outDir, OUTPUT_SENTINEL),
+    `${JSON.stringify({ owner: "@madojs/mado", projectRoot }, null, 2)}\n`,
+  );
+}
+
+async function canonicalPath(path) {
+  let cursor = path;
+  const suffix = [];
+  while (!existsSync(cursor)) {
+    const parent = dirname(cursor);
+    if (parent === cursor) break;
+    suffix.unshift(relative(parent, cursor));
+    cursor = parent;
+  }
+  const base = await realpath(cursor).catch(() => resolve(cursor));
+  return resolve(base, ...suffix);
+}
+
+function isFilesystemRoot(path) {
+  return dirname(path) === path;
+}
+
+function isInside(parent, child) {
+  const rel = relative(parent, child);
+  return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
+}

package/scripts/preview.mjs

@@ -9,7 +9,7 @@
 //      PREVIEW_AUTOBUILD=1.
 //   3. Starts a static server with:
 //        - immutable cache for hashed bundles;
-//        - SPA fallback to index.html;
+//        - SPA fallback to _mado/spa.html when present, else index.html;
 //        - exact `out/` route files before SPA fallback;
 //        - precompressed .gz / .br serving via Accept-Encoding.
 //
@@ -17,10 +17,13 @@
 // what a static host (nginx / Cloudflare Pages / S3) would serve.
 
 import { createServer } from "node:http";
+import { existsSync, readFileSync } from "node:fs";
 import { readFile, stat, access } from "node:fs/promises";
 import { extname, join, resolve, sep } from "node:path";
 import { spawnSync } from "node:child_process";
 
+import { configureLogger, logger } from "./logger.mjs";
+
 // Tiny argv parser. Supports --flag, --flag=value, --flag value.
 function parsePreviewArgs(argv) {
   const flags = {};
@@ -46,7 +49,7 @@ function parsePreviewArgs(argv) {
   return flags;
 }
 
-const PREVIEW_FLAGS = parsePreviewArgs(process.argv.slice(2));
+const PREVIEW_FLAGS = parsePreviewArgs(configureLogger(process.argv.slice(2)));
 
 const ROOT = resolve(process.cwd());
 const OUT = resolve(ROOT, process.env.OUT_DIR ?? "out");
@@ -55,6 +58,68 @@ 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;
 
+// Active Vite base. We try the internal build bridge first (the
+// `@madojs/mado/vite` plugin writes `_mado/build.json` during `vite
+// build`); if `mado static` has already dropped that file before
+// shipping the production artifact, we fall back to parsing the asset
+// prefix out of `out/index.html`. Both paths converge on the same
+// canonical "/" or "/prefix/" form so the preview server replays the
+// real deployment URL shape regardless of pipeline stage.
+const BASE = detectDeployedBase(OUT);
+
+function detectDeployedBase(out) {
+  const fromBridge = readBridgeBase(out);
+  if (fromBridge != null) return fromBridge;
+  const fromHtml = readHtmlBase(out);
+  if (fromHtml != null) return fromHtml;
+  return "/";
+}
+
+function readBridgeBase(out) {
+  try {
+    const meta = JSON.parse(
+      readFileSync(join(out, "_mado/build.json"), "utf8"),
+    );
+    return meta?.base ? normalizeBase(meta.base) : null;
+  } catch {
+    return null;
+  }
+}
+
+function readHtmlBase(out) {
+  try {
+    const html = readFileSync(join(out, "index.html"), "utf8");
+    // Look at the first hashed asset; Vite always prefixes it with
+    // the deployed base.
+    const match = /(?:href|src)="(\/[^"]*?\/)assets\//.exec(html);
+    if (match && match[1]) return normalizeBase(match[1]);
+    // No prefix means root-deployed.
+    if (/(?:href|src)="\/assets\//.test(html)) return "/";
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+function normalizeBase(raw) {
+  if (!raw) return "/";
+  let s = String(raw).trim();
+  if (!s || s === "/") return "/";
+  if (!s.startsWith("/")) s = "/" + s;
+  if (!s.endsWith("/")) s = s + "/";
+  return s.replace(/\/+/g, "/");
+}
+
+function stripBase(pathname) {
+  if (BASE === "/") return pathname.startsWith("/") ? pathname : "/" + pathname;
+  if (pathname === BASE || pathname === BASE.slice(0, -1)) return "/";
+  if (pathname.startsWith(BASE)) {
+    const rest = pathname.slice(BASE.length - 1);
+    return rest || "/";
+  }
+  return pathname;
+}
+
 const MIME = {
   ".html": "text/html; charset=utf-8",
   ".js": "text/javascript; charset=utf-8",
@@ -75,23 +140,20 @@ const MIME = {
 // ---------- Optional release ----------
 
 if (!SKIP_BUILD) {
-  console.log("[preview] PREVIEW_AUTOBUILD=1 — running mado release");
+  logger.info("preview", "autobuild", "PREVIEW_AUTOBUILD=1 — running mado release");
   run("node", ["scripts/cli.mjs", "release"]);
 }
 
 if (!(await exists(OUT))) {
-  console.error(
-    `[preview] missing ${OUT}/ — run \`mado release\` first.`,
-  );
+  logger.error("preview", "missing-output", `missing ${OUT}/ — run \`mado release\` first`);
   process.exit(1);
 }
 
-const spaShell = join(OUT, "index.html");
+const spaShell = existsSync(join(OUT, "_mado", "spa.html"))
+  ? join(OUT, "_mado", "spa.html")
+  : join(OUT, "index.html");
 if (!(await exists(spaShell))) {
-  console.error(
-    `[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.`,
-  );
+  logger.error("preview", "missing-shell", `missing ${spaShell}; mado release did not produce an HTML entry`);
   process.exit(1);
 }
 
@@ -103,7 +165,24 @@ const isImmutable = (filename) =>
 const server = createServer(async (req, res) => {
   try {
     const url = new URL(req.url ?? "/", `http://${req.headers.host}`);
-    const pathname = decodeURIComponent(url.pathname);
+    const fullPathname = decodeURIComponent(url.pathname);
+    // Honour the deployed Vite base: redirect bare `/` to `/${base}/` and
+    // strip the prefix before any lookup, so `out/index.html`,
+    // `out/assets/...` and `out/docs/index.html` are reachable through
+    // the same URL shape the CDN serves.
+    if (BASE !== "/") {
+      const bareBase = BASE.slice(0, -1);
+      if (fullPathname === "/" || fullPathname === bareBase) {
+        res.writeHead(302, { location: BASE });
+        res.end();
+        return;
+      }
+      if (!fullPathname.startsWith(BASE) && fullPathname !== bareBase) {
+        res.writeHead(404).end("not found");
+        return;
+      }
+    }
+    const pathname = stripBase(fullPathname);
     const accepts = (req.headers["accept-encoding"] ?? "").toString();
 
     const target = await resolveTarget(pathname);
@@ -134,22 +213,17 @@ const server = createServer(async (req, res) => {
     res.writeHead(200, headers);
     res.end(data);
   } catch (err) {
-    console.error("[preview] error:", err);
+    logger.error("preview", "request", "request failed", err);
     res.writeHead(500).end(String(err));
   }
 });
 
 server.on("error", (err) => {
   if (err.code === "EPERM" || err.code === "EACCES") {
-    console.error(
-      `[preview] failed to bind ${HOST}:${PORT}: ${err.message}\n` +
-        `[preview] tip: this sandbox may disallow binding "${HOST}".\n` +
-        `[preview] try:  mado preview --host 127.0.0.1`,
-    );
+    logger.error("preview", "bind", `failed to bind ${HOST}:${PORT}: ${err.message}`);
+    logger.info("preview", "bind-hint", "try: mado preview --host 127.0.0.1");
   } else {
-    console.error(
-      `[preview] failed to listen on ${HOST}:${PORT}: ${err.message}`,
-    );
+    logger.error("preview", "listen", `failed to listen on ${HOST}:${PORT}: ${err.message}`);
   }
   process.exit(1);
 });
@@ -158,7 +232,12 @@ server.listen(PORT, HOST, async () => {
   const urlHost = HOST === "0.0.0.0" || HOST === "::" ? "localhost" : HOST;
   console.log("");
   console.log("Mado preview (production-like)");
-  console.log(`  url:    http://${urlHost}:${PORT}/`);
+  // Print the URL the server actually serves the app at. When the
+  // deployment uses a non-trivial Vite `base`, the bare root just
+  // 302-redirects to the base prefix, which surprises users who copy
+  // the logged URL into a browser and land on "Not Found".
+  console.log(`  url:    http://${urlHost}:${PORT}${BASE}`);
+  console.log(`  base:   ${BASE}`);
   console.log(`  out:    ${OUT}`);
   console.log("  (Ctrl-C to stop)");
   console.log("");
@@ -169,7 +248,7 @@ server.listen(PORT, HOST, async () => {
 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}`);
+    logger.error("preview", "child-exit", `command "${cmd} ${args.join(" ")}" exited with ${r.status}`);
     process.exit(r.status ?? 1);
   }
 }
@@ -216,7 +295,9 @@ async function resolveTarget(pathname) {
   //    extension) deliberately 404 instead — otherwise a 200 on
   //    /missing.png would mask real bugs.
   if (!extname(pathname)) {
-    const spa = join(OUT, "index.html");
+    const spa = existsSync(join(OUT, "_mado", "spa.html"))
+      ? join(OUT, "_mado", "spa.html")
+      : join(OUT, "index.html");
     if (await exists(spa)) return spa;
   }