mez-easyjs 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Easy.js contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,40 @@
+# mez-easyjs
+
+Ultra-lightweight frontend framework: **HTML / CSS / JS** SFCs, **no Virtual DOM**, surgical DOM updates. One package includes the **runtime**, **compiler**, and **CLI**.
+
+## Install
+
+```bash
+npm i mez-easyjs
+# or globally for the CLI
+npm i -g mez-easyjs
+```
+
+## Usage
+
+```bash
+npx easy create my-app --template starter --yes
+cd my-app
+npm run dev
+```
+
+```js
+import { createApp, reactive, createRouter, createStore } from 'mez-easyjs';
+import { compile } from 'mez-easyjs/compiler';
+```
+
+Also available: `mez-easyjs/runtime` (same as the main export).
+
+## CLI
+
+| Command | Description |
+|---------|-------------|
+| `easy create [name]` | Interactive scaffold (`minimal` · `starter` · `tailwind`) |
+| `create-easy-app [name]` | Same wizard (npm bin alias) |
+| `easy dev` | Dev server + HMR + error overlay |
+| `easy build` | Production `dist/` (hashed assets, minify) |
+| `easy generate <component\|page> <Name>` | Scaffold files |
+
+## License
+
+MIT

package/bin/create-easy-app.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+/**
+ * npx create-easy-app [name] [--template minimal|starter|tailwind] …
+ * Thin entry that runs the same wizard as `easy create`.
+ */
+import { createProject } from '../src/commands/create.js';
+
+const argv = process.argv.slice(2);
+const flags = {};
+const args = [];
+
+for (let i = 0; i < argv.length; i++) {
+  const a = argv[i];
+  if (a === '--help' || a === '-h') {
+    console.log(`
+create-easy-app — scaffold an Easy.js project
+
+Usage:
+  create-easy-app [name] [options]
+  npx create-easy-app my-app --template starter
+
+Options:
+  --name <n>              Project name
+  --template <id>         minimal | starter | tailwind
+  --lang js               JavaScript only (TypeScript coming soon)
+  --cwd <dir>             Parent directory
+  --yes                   Skip confirmation prompts
+  --skip-install          Skip npm install
+  --skip-git              Skip git init / commit
+`);
+    process.exit(0);
+  }
+  if (a.startsWith('--')) {
+    const key = a.slice(2);
+    const next = argv[i + 1];
+    if (next && !next.startsWith('-')) {
+      flags[key] = next;
+      i++;
+    } else {
+      flags[key] = true;
+    }
+  } else if (a.startsWith('-') && a.length === 2) {
+    const map = { y: 'yes', t: 'template', n: 'name' };
+    const key = map[a[1]] || a[1];
+    const next = argv[i + 1];
+    if (next && !next.startsWith('-') && key !== 'yes') {
+      flags[key] = next;
+      i++;
+    } else {
+      flags[key] = true;
+    }
+  } else {
+    args.push(a);
+  }
+}
+
+createProject(args[0], flags).catch((err) => {
+  console.error(err.message || err);
+  process.exit(1);
+});

package/bin/easy.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { run } from '../src/index.js';
+
+run(process.argv.slice(2)).catch((err) => {
+  console.error(err.message || err);
+  process.exit(1);
+});

package/compiler.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Minimal TypeScript stubs for the mez-easyjs compiler.
+ */
+
+export interface CompileOptions {
+  filename?: string;
+  id?: string;
+}
+
+export interface CompileResult {
+  code: string;
+  map: null;
+  scopeId: string;
+  styles: string;
+  dependencies: string[];
+}
+
+export function compile(source: string, options?: CompileOptions): CompileResult;
+
+export function parseSFC(source: string, filename?: string): unknown;
+export function parseTemplate(html: string, options?: { filename?: string }): unknown;
+export function scopeCSS(css: string, scopeId: string): string;
+export function compileExpression(
+  expression: string,
+  options?: { locals?: string[] }
+): { code: string; keys: string[] };
+export function stripTypeScript(source: string): string;
+
+export class CompileError extends Error {
+  filename?: string;
+  line?: number;
+  column?: number;
+  hint?: string;
+}
+
+export function formatCompileError(err: CompileError): string;
+export function buildFrame(source: string, line: number, column: number): string;

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "mez-easyjs",
+  "version": "0.1.0",
+  "description": "Ultra-lightweight frontend framework — runtime, compiler, and CLI in one package",
+  "type": "module",
+  "bin": {
+    "easy": "bin/easy.js",
+    "easyjs": "bin/easy.js",
+    "create-easy-app": "bin/create-easy-app.js"
+  },
+  "main": "./src/runtime/index.js",
+  "module": "./src/runtime/index.js",
+  "types": "./runtime.d.ts",
+  "exports": {
+    ".": {
+      "types": "./runtime.d.ts",
+      "import": "./src/runtime/index.js",
+      "default": "./src/runtime/index.js"
+    },
+    "./runtime": {
+      "types": "./runtime.d.ts",
+      "import": "./src/runtime/index.js",
+      "default": "./src/runtime/index.js"
+    },
+    "./compiler": {
+      "types": "./compiler.d.ts",
+      "import": "./src/compiler/index.js",
+      "default": "./src/compiler/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "files": [
+    "bin",
+    "src",
+    "templates",
+    "runtime.d.ts",
+    "compiler.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "esbuild": "^0.25.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "easyjs",
+    "easy.js",
+    "frontend",
+    "reactivity",
+    "compiler",
+    "sfc",
+    "cli",
+    "create-easy-app",
+    "no-vdom",
+    "csp",
+    "xss"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/easyjs/easy-js.git",
+    "directory": "packages/easyjs"
+  },
+  "homepage": "https://github.com/easyjs/easy-js#readme",
+  "bugs": {
+    "url": "https://github.com/easyjs/easy-js/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT"
+}

package/runtime.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Minimal TypeScript stubs for the mez-easyjs runtime public API.
+ * Enough for TS consumers to import; not a full type rewrite.
+ */
+
+export interface ReactiveOptions {
+  [key: string]: unknown;
+}
+
+export function reactive<T extends object>(target: T): T;
+export function isReactive(value: unknown): boolean;
+export function raw<T>(value: T): T;
+
+export interface EasyApp {
+  config: { dev: boolean };
+  use(plugin: unknown, options?: unknown): EasyApp;
+  provide(key: string | symbol, value: unknown): EasyApp;
+  mount(selectorOrEl: string | Element): unknown;
+  unmount(): void;
+}
+
+export function createApp(rootComponent: unknown): EasyApp;
+
+export function defineComponent(options: Record<string, unknown>): unknown;
+export function mountComponent(
+  component: unknown,
+  host: Element,
+  props?: Record<string, unknown>,
+  appContext?: Record<string, unknown>
+): unknown;
+export function unmountComponent(instance: unknown): void;
+
+export function createRouter(options: Record<string, unknown>): unknown;
+export function useRouter(): unknown;
+export const RouterView: unknown;
+
+export function createStore<T extends object>(initial: T): T;
+
+export function injectStyles(id: string, css: string): void;
+export function removeStyles(id: string): void;
+export function replaceStyles(id: string, css: string): void;
+
+export function setupDelegation(
+  root: Element,
+  getContext: (node: Element) => unknown
+): void;
+export function createEventContext(
+  methods: Record<string, unknown>,
+  state: unknown,
+  extras?: Record<string, unknown>
+): unknown;
+export function on(
+  el: Element,
+  type: string,
+  fn: EventListener,
+  options?: boolean | AddEventListenerOptions
+): () => void;
+export function off(
+  el: Element,
+  type: string,
+  fn: EventListener,
+  options?: boolean | EventListenerOptions
+): void;
+
+export function nextTick(fn?: () => void): Promise<void>;
+export function queueJob(job: () => void): void;
+
+export function escapeHtml(value: unknown): string;
+export function escapeAttr(value: unknown): string;
+export function sanitizeUrl(value: unknown): string;
+export function isEventAttr(name: string): boolean;
+export function isUrlAttr(name: string): boolean;
+export const URL_ATTRS: Set<string>;
+
+export class EasyError extends Error {
+  hint?: string;
+  filename?: string;
+  component?: string;
+  cause?: unknown;
+}
+
+export function reportError(err: unknown, meta?: Record<string, unknown>): void;
+export function setOverlayHandler(fn: ((err: unknown) => void) | null): void;
+export function pushBoundary(boundary: unknown): () => void;
+export function peekBoundary(): unknown;
+export function withErrorBoundary<T>(boundary: unknown, fn: () => T): T;
+export function createBoundary(host: Element, options?: Record<string, unknown>): unknown;
+
+export function installOverlay(): void;
+export function showOverlay(err: unknown, meta?: Record<string, unknown>): void;
+export function hideOverlay(): void;
+
+export function enableHmr(): unknown;
+export function isHmrEnabled(): boolean;
+export function registerHmrInstance(
+  moduleId: string,
+  instance: unknown,
+  meta?: Record<string, unknown>
+): () => void;
+export function applyHmrUpdate(moduleId: string, mod: unknown): void;
+export function replaceScopedStyles(scopeId: string, css: string): void;
+export function snapshotState(instance: unknown): unknown;
+export function restoreState(instance: unknown, snap: unknown): void;

package/src/commands/build.js

@@ -0,0 +1,284 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import * as esbuild from 'esbuild';
+import { compile } from '../compiler/index.js';
+import { loadConfig } from '../transform.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const RUNTIME_ENTRY = path.resolve(__dirname, '../runtime/index.js');
+
+/**
+ * Production build — Vite/React-like output:
+ *   dist/index.html
+ *   dist/assets/index-[hash].js
+ *   dist/assets/index-[hash].css
+ *   dist/assets/[chunk]-[hash].js  (code-split routes)
+ */
+export async function runBuild(flags = {}) {
+  const root = path.resolve(flags.cwd || process.cwd());
+  const config = await loadConfig(root);
+  const outDir = path.resolve(root, flags.outDir || config.outDir || 'dist');
+  const minify = flags['no-minify'] ? false : flags.minify !== false && flags['minify'] !== 'false';
+  const entryRel = config.entry || 'src/main.js';
+  const entry = path.resolve(root, entryRel);
+
+  if (!fs.existsSync(entry)) {
+    throw new Error(`Entry not found: ${entryRel}`);
+  }
+
+  console.log(`Building ${root} → ${outDir}`);
+
+  fs.rmSync(outDir, { recursive: true, force: true });
+  const assetsDir = path.join(outDir, 'assets');
+  fs.mkdirSync(assetsDir, { recursive: true });
+
+  // Copy public assets to dist root (favicon, etc.)
+  const publicDir = path.join(root, config.publicDir || 'public');
+  if (fs.existsSync(publicDir)) {
+    copyDir(publicDir, outDir);
+  }
+
+  const collectedCss = [];
+  const cssSeen = new Set();
+
+  // Global stylesheet linked from index.html
+  const indexHtmlPath = path.join(root, 'index.html');
+  let html = fs.existsSync(indexHtmlPath)
+    ? fs.readFileSync(indexHtmlPath, 'utf8')
+    : defaultHtml(entryRel);
+
+  const linkCss = [...html.matchAll(/<link[^>]+href=["']([^"']+\.css)["'][^>]*>/gi)];
+  for (const m of linkCss) {
+    const href = m[1];
+    if (/^https?:/i.test(href)) continue;
+    const cssPath = path.resolve(root, href.replace(/^\//, ''));
+    if (fs.existsSync(cssPath) && !cssSeen.has(cssPath)) {
+      cssSeen.add(cssPath);
+      collectedCss.push(`/* ${path.relative(root, cssPath)} */\n` + fs.readFileSync(cssPath, 'utf8'));
+    }
+  }
+
+  const result = await esbuild.build({
+    absWorkingDir: root,
+    entryPoints: [entry],
+    bundle: true,
+    splitting: true,
+    format: 'esm',
+    platform: 'browser',
+    target: ['es2020'],
+    outdir: assetsDir,
+    entryNames: minify ? 'index-[hash]' : 'index',
+    chunkNames: minify ? '[name]-[hash]' : '[name]',
+    assetNames: minify ? 'asset-[name]-[hash]' : 'asset-[name]',
+    minify,
+    sourcemap: false,
+    metafile: true,
+    write: true,
+    logLevel: 'warning',
+    define: {
+      'process.env.NODE_ENV': '"production"',
+      __EASY_DEV__: 'false'
+    },
+    plugins: [
+      easyPlugin({
+        root,
+        collectedCss,
+        cssSeen,
+        runtimeEntry: RUNTIME_ENTRY
+      })
+    ]
+  });
+
+  // Write CSS bundle
+  const cssSource = collectedCss.filter(Boolean).join('\n\n');
+  const cssHash = shortHash(cssSource || 'empty');
+  const cssFileName = minify ? `index-${cssHash}.css` : 'index.css';
+  const cssOut = path.join(assetsDir, cssFileName);
+  const minCss = minify ? minifyCss(cssSource) : cssSource;
+  fs.writeFileSync(cssOut, minCss || '/* no styles */\n');
+
+  // Find main JS entry from metafile
+  const outputs = Object.keys(result.metafile.outputs);
+  const entryOut = outputs.find((o) => {
+    const meta = result.metafile.outputs[o];
+    return meta.entryPoint && path.resolve(root, meta.entryPoint) === entry;
+  }) || outputs.find((o) => /index[^/\\]*\.js$/i.test(o) && !o.includes('chunk-'));
+
+  if (!entryOut) {
+    throw new Error('Build produced no JS entry — check entry point and .easy compilation.');
+  }
+
+  const jsFileName = path.basename(entryOut);
+
+  // Rewrite index.html → single entry + assets
+  html = html.replace(/<script[^>]*\/@easy\/hmr\.js[^>]*><\/script>\s*/gi, '');
+  html = html.replace(/<link[^>]+href=["'][^"']+\.css["'][^>]*>\s*/gi, (tag) =>
+    /https?:/i.test(tag) ? tag : ''
+  );
+  html = html.replace(/<script[^>]+src=["'][^"']+["'][^>]*><\/script>\s*/gi, (tag) =>
+    /type=["']module["']/i.test(tag) || /src=["'][^"']*main/i.test(tag) ? '' : tag
+  );
+
+  if (!/<link[^>]+rel=["']stylesheet["']/i.test(html)) {
+    html = html.replace(
+      /<\/head>/i,
+      `  <link rel="stylesheet" href="./assets/${cssFileName}" />\n</head>`
+    );
+  } else {
+    html = html.replace(
+      /<\/head>/i,
+      `  <link rel="stylesheet" href="./assets/${cssFileName}" />\n</head>`
+    );
+  }
+
+  if (!/<script[^>]+type=["']module["']/i.test(html)) {
+    html = html.replace(
+      /<\/body>/i,
+      `  <script type="module" src="./assets/${jsFileName}"></script>\n</body>`
+    );
+  } else {
+    html = html.replace(
+      /<\/body>/i,
+      `  <script type="module" src="./assets/${jsFileName}"></script>\n</body>`
+    );
+  }
+
+  // Ensure we didn't leave duplicate empty gaps; collapse multiple stylesheet/script we may have doubled
+  html = dedupeAssetTags(html, cssFileName, jsFileName);
+
+  fs.writeFileSync(path.join(outDir, 'index.html'), html);
+
+  const jsFiles = fs.readdirSync(assetsDir).filter((f) => f.endsWith('.js'));
+  const cssFiles = fs.readdirSync(assetsDir).filter((f) => f.endsWith('.css'));
+
+  console.log(`✔ Build complete → ${outDir}`);
+  console.log(`  index.html`);
+  for (const f of cssFiles) console.log(`  assets/${f}`);
+  for (const f of jsFiles) console.log(`  assets/${f}`);
+  console.log(`  Serve with any static host, e.g. npx serve dist`);
+}
+
+function easyPlugin({ root, collectedCss, cssSeen, runtimeEntry }) {
+  return {
+    name: 'easy-js',
+    setup(build) {
+      // Resolve mez-easyjs / mez-easyjs/runtime → source package
+      build.onResolve({ filter: /^mez-easyjs(\/runtime(\/.*)?)?$/ }, (args) => {
+        if (
+          args.path === 'mez-easyjs' ||
+          args.path === 'mez-easyjs/runtime' ||
+          args.path === 'mez-easyjs/runtime/'
+        ) {
+          return { path: runtimeEntry };
+        }
+        const sub = args.path.replace(/^mez-easyjs\/runtime\//, '');
+        const file = path.resolve(
+          path.dirname(runtimeEntry),
+          sub.endsWith('.js') ? sub : `${sub}.js`
+        );
+        return { path: file };
+      });
+
+      // Compile .easy / .ejs SFCs
+      build.onLoad({ filter: /\.(easy|ejs)$/ }, async (args) => {
+        const source = await fs.promises.readFile(args.path, 'utf8');
+        const result = compile(source, {
+          filename: path.basename(args.path)
+        });
+        if (result.styles && result.styles.trim() && !cssSeen.has(args.path + ':styles')) {
+          cssSeen.add(args.path + ':styles');
+          collectedCss.push(
+            `/* ${path.relative(root, args.path)} */\n` + result.styles
+          );
+        }
+        // Production: styles are in the CSS asset — skip duplicate runtime injection
+        let code = result.code;
+        if (result.styles && result.styles.trim()) {
+          code = code
+            .replace(
+              /replaceStyles\(__SCOPE,\s*__STYLES\);/g,
+              '/* styles extracted to assets/*.css */'
+            )
+            .replace(
+              /injectStyles\([^)]+\);/g,
+              '/* styles extracted to assets/*.css */'
+            );
+        }
+        // Rewrite .easy imports stay as .easy — esbuild will load them via this plugin
+        return {
+          contents: code,
+          loader: 'js',
+          resolveDir: path.dirname(args.path)
+        };
+      });
+
+      // Plain CSS imported from JS
+      build.onLoad({ filter: /\.css$/ }, async (args) => {
+        const css = await fs.promises.readFile(args.path, 'utf8');
+        if (!cssSeen.has(args.path)) {
+          cssSeen.add(args.path);
+          collectedCss.push(`/* ${path.relative(root, args.path)} */\n` + css);
+        }
+        return { contents: 'export default {};', loader: 'js' };
+      });
+    }
+  };
+}
+
+function dedupeAssetTags(html, cssFileName, jsFileName) {
+  // Keep a single stylesheet + single module script pointing at our hashed assets
+  let out = html;
+  const cssTag = `  <link rel="stylesheet" href="./assets/${cssFileName}" />`;
+  const jsTag = `  <script type="module" src="./assets/${jsFileName}"></script>`;
+
+  out = out.replace(/<link[^>]+href=["']\.\/assets\/[^"']+\.css["'][^>]*>\s*/gi, '');
+  out = out.replace(/<script[^>]+src=["']\.\/assets\/[^"']+\.js["'][^>]*><\/script>\s*/gi, '');
+
+  if (!/<\/head>/i.test(out)) {
+    out = `<!DOCTYPE html><html><head>${cssTag}</head><body><div id="app"></div>${jsTag}</body></html>`;
+    return out;
+  }
+  out = out.replace(/<\/head>/i, `${cssTag}\n</head>`);
+  out = out.replace(/<\/body>/i, `${jsTag}\n</body>`);
+  return out;
+}
+
+function defaultHtml(entryRel) {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Easy.js App</title>
+</head>
+<body>
+  <div id="app"></div>
+  <script type="module" src="/${entryRel.replace(/\\\\/g, '/')}"></script>
+</body>
+</html>
+`;
+}
+
+function minifyCss(css) {
+  return String(css || '')
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/\s+/g, ' ')
+    .replace(/\s*([{}:;,])\s*/g, '$1')
+    .trim();
+}
+
+function shortHash(s) {
+  return createHash('sha256').update(s).digest('hex').slice(0, 8);
+}
+
+function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const name of fs.readdirSync(src)) {
+    const from = path.join(src, name);
+    const to = path.join(dest, name);
+    if (fs.statSync(from).isDirectory()) copyDir(from, to);
+    else fs.copyFileSync(from, to);
+  }
+}