@madojs/mado 0.10.1 → 0.11.0

package/scripts/cli/generate.mjs

@@ -0,0 +1,348 @@
+import { access, mkdir, writeFile } from "node:fs/promises";
+import { dirname, join, relative } from "node:path";
+
+const KINDS = [
+  "module",
+  "page",
+  "connector",
+  "resource",
+  "service",
+  "form",
+  "component",
+  "guard",
+  "layout",
+];
+
+export async function runNew(ctx, args) {
+  const [kind, target] = args;
+  if (!kind || !target) {
+    printUsage();
+    process.exit(1);
+  }
+
+  const generators = {
+    module: scaffoldModule,
+    page: scaffoldPage,
+    connector: scaffoldConnector,
+    resource: scaffoldResource,
+    service: scaffoldService,
+    form: scaffoldForm,
+    component: scaffoldComponent,
+    guard: scaffoldGuard,
+    layout: scaffoldLayout,
+  };
+
+  const fn = generators[kind];
+  if (!fn) {
+    console.error(`[mado] unknown generator: ${kind}`);
+    console.error(`[mado] available generators: ${KINDS.join(", ")}`);
+    process.exit(1);
+  }
+
+  await fn(ctx, normalizeTarget(target));
+}
+
+function printUsage() {
+  console.error("usage: mado new <module|page|connector|resource|service|form|component|guard|layout> <path>");
+  console.error("");
+  console.error("examples:");
+  console.error("  mado new module billing");
+  console.error("  mado new page billing/pages/invoices-list");
+  console.error("  mado new connector billing/api/stripe");
+  console.error("  mado new resource billing/data/invoices");
+  console.error("  mado new service billing/cart");
+  console.error("  mado new form billing/invoice");
+  console.error("  mado new component billing/components/invoice-status-badge");
+  console.error("  mado new guard billing/billing");
+  console.error("  mado new layout app-shell");
+}
+
+async function scaffoldModule(ctx, name) {
+  assertSingleSegment("Module", name);
+  const dir = join(srcDir(ctx), "modules", name);
+  const camel = kebabToCamel(name);
+  const Pascal = kebabToPascal(name);
+
+  await writeOnce(
+    join(dir, `${name}.types.ts`),
+    `// Domain types of the ${name} module. Public via ${name}.public.ts.\n\nexport interface ${Pascal} {\n  id: string;\n}\n`,
+  );
+  await writeOnce(
+    join(dir, `${name}.routes.ts`),
+    `// Path prefix is applied in src/app.routes.ts.\n\nexport const ${camel}Routes = {\n  // "/": () => import("./${name}.page"),\n};\n`,
+  );
+  await writeOnce(
+    join(dir, `${name}.public.ts`),
+    `// Public surface of the ${name} module.\n// Anything not re-exported here is private to the module.\n\nexport type { ${Pascal} } from "./${name}.types";\n`,
+  );
+
+  console.log(
+    `\nNext step: wire the module in src/app.routes.ts:\n\n` +
+      `  import { ${camel}Routes } from "./modules/${name}/${name}.routes";\n\n` +
+      `  "/${name}": layout({\n` +
+      `    layout: () => import("./layouts/app-shell.layout"),\n` +
+      `    routes: ${camel}Routes,\n` +
+      `  }),\n`,
+  );
+}
+
+async function scaffoldPage(ctx, target) {
+  const file = moduleFile(ctx, target, ".page.ts");
+  const name = leafName(target);
+  await writeOnce(
+    file,
+    `import { html, page } from "@madojs/mado";
+
+export default page({
+  title: "${kebabToPascal(name)}",
+  view: () => {
+    // 1. LOCAL STATE
+    // 2. DATA
+    // 3. ACTIONS
+
+    // 4. VIEW
+    return html\`
+      <section>
+        <h1>${kebabToPascal(name)}</h1>
+      </section>
+    \`;
+  },
+});
+`,
+  );
+}
+
+async function scaffoldConnector(ctx, target) {
+  const file = moduleFile(ctx, target, ".connector.ts");
+  const name = leafName(target);
+  const api = `${kebabToCamel(name)}Api`;
+  const err = `${kebabToPascal(name)}Error`;
+  const up = relative(dirname(file), join(srcDir(ctx), "shared")).split("\\").join("/");
+
+  await writeOnce(
+    file,
+    `// ${kebabToPascal(name)} connector. One file per external API system.
+// Shape: CONFIG -> MAPPERS -> ENDPOINTS -> ERRORS.
+// Never import signals, resources, html, components, pages, or services here.
+
+import { httpClient } from "${up}/http/http-client";
+import { HttpError } from "${up}/http/http-error";
+
+// 1. CONFIG
+const base = "/api/${name}";
+
+// 2. MAPPERS
+// Map provider DTOs from _contracts/ to domain types from <module>.types.ts.
+
+// 3. ENDPOINTS
+export const ${api} = {
+  list: () => httpClient.get<unknown[]>(base),
+};
+
+// 4. ERRORS
+export class ${err} extends HttpError {
+  override readonly name = "${err}";
+}
+`,
+  );
+}
+
+async function scaffoldResource(ctx, target) {
+  const file = moduleFile(ctx, target, ".resource.ts");
+  const name = leafName(target);
+  const Pascal = kebabToPascal(name);
+  await writeOnce(
+    file,
+    `import { mutation, resource } from "@madojs/mado";
+
+// Resource keys are URL-shaped so mutation invalidation stays predictable.
+const key = "/api/${name}";
+
+export const use${Pascal} = () =>
+  resource(
+    () => key,
+    async () => {
+      throw new Error("TODO: connect use${Pascal}() to a module connector");
+    },
+    { staleTime: 30_000 },
+  );
+
+export const save${Pascal} = mutation(
+  async (_input: unknown) => {
+    throw new Error("TODO: connect save${Pascal}() to a module connector");
+  },
+  { invalidates: ["/api/${name}*"] },
+);
+`,
+  );
+}
+
+async function scaffoldService(ctx, target) {
+  const file = moduleFile(ctx, target, ".service.ts");
+  const name = leafName(target);
+  const camel = kebabToCamel(name);
+  const Pascal = kebabToPascal(name);
+  await writeOnce(
+    file,
+    `import { computed, signal } from "@madojs/mado";
+
+export interface ${Pascal} {
+  id: string;
+}
+
+// 1. PRIVATE STATE
+const _${camel} = signal<${Pascal} | null>(null);
+
+// 2. PUBLIC READS
+export const ${camel} = (): ${Pascal} | null => _${camel}();
+export const has${Pascal} = computed(() => _${camel}() !== null);
+
+// 3. ACTIONS
+export function set${Pascal}(next: ${Pascal} | null): void {
+  _${camel}.set(next);
+}
+
+// 4. INIT
+export function init${Pascal}(): void {}
+`,
+  );
+}
+
+async function scaffoldForm(ctx, target) {
+  const file = moduleFile(ctx, target, ".form.ts");
+  const name = leafName(target);
+  const useName = `use${kebabToPascal(name)}Form`;
+  await writeOnce(
+    file,
+    `import { useForm } from "@madojs/mado";
+
+// Call inside a page view: const form = ${useName}();
+export const ${useName} = () =>
+  useForm({
+    // name: { required: true },
+  });
+`,
+  );
+}
+
+async function scaffoldComponent(ctx, target) {
+  const file = moduleFile(ctx, target, ".component.ts");
+  const name = leafName(target);
+  const tag = name.includes("-") ? name : `x-${name}`;
+  await writeOnce(
+    file,
+    `import { component, css, html } from "@madojs/mado";
+
+component(
+  "${tag}",
+  () => () => html\`<span><slot></slot></span>\`,
+  {
+    styles: css\`
+      :host {
+        display: inline-block;
+      }
+    \`,
+  },
+);
+`,
+  );
+}
+
+async function scaffoldGuard(ctx, target) {
+  const file = moduleFile(ctx, target, ".guard.ts");
+  const name = leafName(target);
+  const Pascal = kebabToPascal(name);
+  await writeOnce(
+    file,
+    `// Return true to allow, a path string to redirect, or false to deny.
+
+export function require${Pascal}(): boolean | string {
+  return true;
+}
+`,
+  );
+}
+
+async function scaffoldLayout(ctx, name) {
+  assertSingleSegment("Layout", name);
+  const file = join(srcDir(ctx), "layouts", `${name}.layout.ts`);
+  await writeOnce(
+    file,
+    `import { html, page } from "@madojs/mado";
+
+export default page({
+  title: "${kebabToPascal(name)}",
+  view: ({ child }) => html\`
+    <div class="layout layout--${name}">
+      <main>\${child}</main>
+    </div>
+  \`,
+});
+`,
+  );
+
+  console.log(
+    `\nNext step: wrap routes with this layout in src/app.routes.ts:\n\n` +
+      `  "/<prefix>": layout({\n` +
+      `    layout: () => import("./layouts/${name}.layout"),\n` +
+      `    routes: <moduleRoutes>,\n` +
+      `  }),\n`,
+  );
+}
+
+function srcDir(ctx) {
+  return join(ctx.projectRoot, "src");
+}
+
+function moduleFile(ctx, target, suffix) {
+  return join(srcDir(ctx), "modules", `${target}${suffix}`);
+}
+
+async function writeOnce(path, content) {
+  if (await exists(path)) {
+    console.error(`[mado] file already exists: ${path}`);
+    process.exit(2);
+  }
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, content, "utf8");
+  console.log(`created ${path}`);
+}
+
+async function exists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function normalizeTarget(target) {
+  return target
+    .split("\\").join("/")
+    .replace(/^src\/modules\//, "")
+    .replace(/^modules\//, "")
+    .replace(/^src\/layouts\//, "")
+    .replace(/^layouts\//, "")
+    .replace(/^\/+|\/+$/g, "");
+}
+
+function leafName(target) {
+  return target.split("/").filter(Boolean).at(-1) ?? target;
+}
+
+function assertSingleSegment(label, name) {
+  if (name.includes("/")) {
+    console.error(`[mado] ${label.toLowerCase()} name must be a single path segment`);
+    process.exit(1);
+  }
+}
+
+function kebabToCamel(s) {
+  return s.replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase());
+}
+
+function kebabToPascal(s) {
+  const c = kebabToCamel(s);
+  return c.charAt(0).toUpperCase() + c.slice(1);
+}

package/scripts/cli/help.mjs

@@ -0,0 +1,27 @@
+export function printHelp(ctx) {
+  const mode = ctx.isRepo ? "repo-mode (framework repository)" : "app-mode";
+  console.log(`mado commands (${mode}):
+
+  Project lifecycle:
+    mado init <name> [--starter default] [--force]
+                           scaffold a new app
+    mado dev               Vite dev server
+    mado build             tsc package compile (writes internal dist/)
+    mado typecheck         tsc --noEmit
+    mado test              run unit tests
+
+  Production:
+    mado bake [--entry <file>] [--template <html>] [--out <dir>] [--base-url <url>]
+                           prerender baked routes  -> out/
+    mado release           typecheck + vite build + bake -> out/
+    mado preview           serve exactly out/ locally
+
+  Generators:
+    mado new <module|page|connector|resource|service|form|component|guard|layout> <path>
+
+  Configuration:
+    Put app/dev/build settings in vite.config.ts.
+    Mado CLI flags are explicit per command.
+
+  Docs: README.md and docs/en/README.md.`);
+}

package/scripts/cli/index.mjs

@@ -0,0 +1,79 @@
+import { readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { detectContext } from "../_config.mjs";
+import { runInit } from "./init.mjs";
+import { runNew } from "./generate.mjs";
+import { printHelp } from "./help.mjs";
+import { runRelease } from "./release.mjs";
+import { hasFlag, listTestFiles, run, runNodeBin, runNodeScript, runVite } from "./run.mjs";
+
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
+
+export async function main(argv) {
+  const projectRoot = resolve(process.cwd());
+  const context = detectContext(projectRoot);
+  const packageJson = JSON.parse(readFileSync(join(PACKAGE_ROOT, "package.json"), "utf8"));
+  const ctx = {
+    packageRoot: PACKAGE_ROOT,
+    projectRoot,
+    packageJson,
+    context,
+    isRepo: context === "repo",
+  };
+
+  const [rawCommand, ...args] = argv;
+  const command = rawCommand ?? "help";
+
+  switch (command) {
+    case "init":
+      await runInit(ctx, args);
+      break;
+    case "build":
+      await runNodeBin(ctx, "typescript/bin/tsc", args);
+      break;
+    case "watch":
+      await runNodeBin(ctx, "typescript/bin/tsc", ["-w", ...args]);
+      break;
+    case "typecheck":
+      await runNodeBin(ctx, "typescript/bin/tsc", ["--noEmit", ...args]);
+      break;
+    case "test": {
+      await runNodeBin(ctx, "typescript/bin/tsc", []);
+      const files = await listTestFiles(projectRoot);
+      await run(process.execPath, ["--test", "--test-timeout=30000", ...files, ...args], {
+        cwd: projectRoot,
+      });
+      break;
+    }
+    case "dev":
+      await runVite(
+        ctx,
+        [...(hasFlag(args, "--host") ? [] : ["--host", "localhost"]), ...args],
+        { defaultConfig: true },
+      );
+      break;
+    case "bake":
+      await runNodeScript(ctx, "scripts/bake.mjs", args);
+      break;
+    case "preview":
+      await runNodeScript(ctx, "scripts/preview.mjs", args);
+      break;
+    case "release":
+      await runRelease(ctx, args);
+      break;
+    case "new":
+      await runNew(ctx, args);
+      break;
+    case "help":
+    case "--help":
+    case "-h":
+      printHelp(ctx);
+      break;
+    default:
+      console.error(`[mado] unknown command: ${command}`);
+      printHelp(ctx);
+      process.exit(1);
+  }
+}

package/scripts/cli/init.mjs

@@ -0,0 +1,153 @@
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { copyFile, cp, mkdir, readFile, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+
+import { parseFlags } from "../_config.mjs";
+
+const STARTERS = ["default"];
+
+export async function runInit(ctx, rawArgs) {
+  const { flags, positional } = parseFlags(rawArgs);
+  const targetArg = positional[0];
+  if (!targetArg) {
+    console.error("[mado] usage: mado init <name> [--starter default] [--force]");
+    process.exit(1);
+  }
+
+  const starter = String(flags.starter ?? "default");
+  if (!STARTERS.includes(starter)) {
+    console.error(`[mado] unknown starter: ${starter}`);
+    console.error(`[mado] available starters: ${STARTERS.join(", ")}`);
+    process.exit(1);
+  }
+
+  const target = resolve(ctx.projectRoot, targetArg);
+  const source = join(ctx.packageRoot, "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 copyCanonicalLLMFiles(ctx, target);
+  await ensureStarterGitignore(target);
+  await ensureStarterPackageJson(ctx, 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 ||
+      `^${ctx.packageJson.version}`,
+    __MADO_VERSION__: ctx.packageJson.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(ctx.projectRoot, target)}`);
+  console.log("  npm install");
+  console.log("  npm run dev");
+  console.log("");
+}
+
+async function copyCanonicalLLMFiles(ctx, target) {
+  for (const file of ["llms.txt"]) {
+    const source = join(ctx.packageRoot, file);
+    const dest = join(target, file);
+    if (existsSync(source) && !existsSync(dest)) await copyFile(source, dest);
+  }
+}
+
+async function ensureStarterGitignore(target) {
+  const file = join(target, ".gitignore");
+  if (existsSync(file)) return;
+  await writeFile(file, "node_modules\nout\n.DS_Store\n*.log\n");
+}
+
+async function ensureStarterPackageJson(ctx, target) {
+  const file = join(target, "package.json");
+  if (!existsSync(file)) return;
+
+  const pkg = JSON.parse(await readFile(file, "utf8"));
+  pkg.dependencies = {
+    ...(pkg.dependencies ?? {}),
+    "@madojs/mado":
+      process.env.MADO_PACKAGE_SPEC ||
+      process.env.MADOJS_PACKAGE_SPEC ||
+      `^${ctx.packageJson.version}`,
+  };
+  const rootDev = ctx.packageJson.devDependencies ?? {};
+  pkg.devDependencies = {
+    ...(pkg.devDependencies ?? {}),
+    typescript: rootDev.typescript ?? "^6.0.3",
+    linkedom: rootDev.linkedom ?? "^0.18.12",
+    lightningcss: rootDev.lightningcss ?? "^1.32.0",
+    vite: rootDev.vite ?? "^8.0.16",
+  };
+
+  await writeFile(file, `${JSON.stringify(pkg, null, 2)}\n`);
+}
+
+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 || ".";
+}