lecodes-cli 2.0.1 → 2.0.3

package/src/web/build.ts

@@ -0,0 +1,171 @@
+import { createHash } from "node:crypto"
+import { copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs"
+import { dirname, extname, join, resolve } from "node:path"
+import { collectLocalEntries } from "../compile/collectLocal"
+import { applyProjectFonts } from "../compile/fonts"
+import { applyAppAssetIcons } from "../compile/assetIcons"
+import { ambiguousEntryWarning, compileProject } from "../compile/projectCompile"
+import { readAppConfigAt } from "../commands/app/shared"
+import type { Manifest } from "../project/manifest"
+import { CliError } from "../cli"
+
+/*
+ * `lecodes web build`: the project as a FOLDER a static hosting serves.
+ *
+ *   index.html            the page (name, icon, theme color of app.json)
+ *   app.<hash>.js         the bundle — the same code every platform runs
+ *   lite.js, assets/…     the page of Web Lite (lecodes-web-lite's dist): its script, its font,
+ *                         the tween engine
+ *   assets/<path>         the project's assets — only the ones the bundle names
+ *   404.html              in `path` mode: the page again, for the hostings that answer an unknown
+ *                         path with it
+ *
+ * Every url in the folder is RELATIVE: it works at the root of a domain and in a folder of one.
+ * In `path` mode (app.json `web.urls: "path"`) the routes are paths under `web.base`, so the page
+ * names that base (`<base href>`) and the hosting has to answer every path under it with the page.
+ */
+
+export type WebConfig = {
+  /** How a route is written in the address: `#/product/42` (default) or `/product/42`. */
+  urls?: "hash" | "path"
+  /** `path` mode: the folder the site is served from ("/" by default). */
+  base?: string
+  /** The page's title (default: the app's name). */
+  title?: string
+  /** The browser's chrome around the page (a phone's address bar); default black. */
+  themeColor?: string
+  /** The page's language (`<html lang>`). */
+  lang?: string
+}
+
+export type WebBuildOptions = {
+  root: string
+  manifest: Manifest | null
+  name: string
+  /** The built page of Web Lite (lecodes-web-lite's dist). */
+  lite: string
+  out: string
+  entry?: string
+  /** Inline the source map into the bundle (errors name the app's lines; the bundle grows). */
+  sourcemap?: boolean
+  minify?: boolean
+}
+
+export type WebBuildResult = {
+  out: string
+  bundle: string
+  files: { path: string, bytes: number }[]
+  warnings: string[]
+}
+
+const escapeHtml = (text: string): string => text.replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" }[c]!))
+
+const normalBase = (base: string | undefined): string => {
+  const b = (base ?? "/").trim() || "/"
+  return (b.startsWith("/") ? b : `/${b}`).replace(/\/*$/, "/")
+}
+
+const walk = (dir: string, prefix = ""): { path: string, bytes: number }[] => {
+  const out: { path: string, bytes: number }[] = []
+  for (const name of readdirSync(dir)) {
+    const abs = join(dir, name)
+    const stat = statSync(abs)
+    if (stat.isDirectory()) out.push(...walk(abs, `${prefix}${name}/`))
+    else out.push({ path: prefix + name, bytes: stat.size })
+  }
+  return out
+}
+
+export const buildWeb = async (options: WebBuildOptions): Promise<WebBuildResult> => {
+  const { root, manifest, name, lite } = options
+  const out = resolve(root, options.out)
+  if (out === resolve(root) || resolve(root).startsWith(out + "\\") || resolve(root).startsWith(out + "/")) {
+    throw new CliError(`The output folder is cleaned before a build: "${options.out}" holds the project itself.`)
+  }
+  const config: WebConfig = (readAppConfigAt(root) as { web?: WebConfig } | null)?.web ?? {}
+  const mode = config.urls === "path" ? "path" : "hash"
+  const base = normalBase(config.base)
+  const warnings: string[] = []
+
+  // ---- the bundle: every asset a url relative to the page ------------------------------------------------
+  const assetUrl = (path: string) => "assets" + encodeURI(path)
+  const collected = collectLocalEntries(root, manifest, "assets")
+  const entries = collected.entries.filter((e) => {
+    // what a build made is no part of the project
+    const abs = e.absPath ? resolve(e.absPath) : null
+    return !(abs && (abs === out || abs.startsWith(out + "\\") || abs.startsWith(out + "/")))
+  })
+  for (const w of collected.warnings) if (!/shaders compile on the server/.test(w)) warnings.push(w)
+  const fontsHeader = await applyProjectFonts(entries, {
+    mode: "vendor", root, vendorDir: root, vendorPrefix: "", publicUrl: "", relative: true,
+    makeResourceEntry: (path, absPath) => ({ path, type: "resource", fileSrc: assetUrl(path), absPath }),
+  })
+  const iconsHeader = await applyAppAssetIcons(entries)
+  if (!options.entry) {
+    const ambiguous = ambiguousEntryWarning(entries)
+    if (ambiguous) warnings.push(ambiguous)
+  }
+  const compiled = await compileProject({
+    entries, name, publicUrl: "", entryOverride: options.entry, header: true, fontsHeader, iconsHeader,
+    sourcemap: options.sourcemap === true, minify: options.minify,
+    onWarning: (w) => warnings.push(w),
+  })
+  // The same project builds into the same bytes: the bundle's name is its hash, and a hosting
+  // keeps a file of that name for good. The header's time stamp is the one line that would
+  // differ (the line stays, for the source map's count of lines).
+  const js = compiled.replace(/^\/\/ last-updated: .*$/m, "// last-updated: -")
+  const header = js.slice(0, 2000)
+  if (!/^\/\/ gl: disable/m.test(header) || /^\/\/ 2d: enable/m.test(header)) {
+    warnings.push("This project uses 3D or 2D scenes, which Web Lite does not show yet: the page runs its UI, a scene's calls fail. (`lecodes dev --web` runs the whole app on the web player.)")
+  }
+
+  // ---- the folder ----------------------------------------------------------------------------------------------
+  rmSync(out, { recursive: true, force: true })
+  mkdirSync(out, { recursive: true })
+  cpSync(lite, out, { recursive: true })
+
+  const bundle = `app.${createHash("sha256").update(js).digest("hex").slice(0, 10)}.js`
+  writeFileSync(join(out, bundle), js)
+
+  // the project's assets: the ones the bundle names
+  for (const entry of entries) {
+    if (entry.type !== "resource" || !entry.absPath || !entry.fileSrc) continue
+    if (!js.includes(entry.fileSrc)) continue
+    const to = join(out, "assets", ...entry.path.split("/").filter(Boolean))
+    if (existsSync(to)) { warnings.push(`${entry.path}: a file of the page has this name in the built folder — the project's file was not copied`); continue }
+    mkdirSync(dirname(to), { recursive: true })
+    copyFileSync(entry.absPath, to)
+  }
+
+  // ---- the page ----------------------------------------------------------------------------------------------
+  const app = readAppConfigAt(root)
+  let html = readFileSync(join(lite, "index.html"), "utf8")
+  const head: string[] = []
+  head.push(`<meta name="theme-color" content="${escapeHtml(config.themeColor ?? "#000000")}" />`)
+  if (app?.icon) {
+    const icon = resolve(root, app.icon)
+    if (existsSync(icon)) {
+      const file = `icon${extname(icon).toLowerCase() || ".png"}`
+      copyFileSync(icon, join(out, file))
+      head.push(`<link rel="icon" href="${file}" />`, `<link rel="apple-touch-icon" href="${file}" />`)
+    } else {
+      warnings.push(`app.json icon "${app.icon}" is not there — the page has no icon`)
+    }
+  }
+  // in path mode a route is a path: what the page names relatively is under the base, whatever the route
+  if (mode === "path") head.unshift(`<base href="${escapeHtml(base)}" />`)
+  const attrs = [`data-src="${bundle}"`, ...(mode === "path" ? [`data-urls="path"`, `data-base="${escapeHtml(base)}"`] : [])].join(" ")
+  const replace = (from: string | RegExp, to: string) => {
+    const next = html.replace(from, to)
+    if (next === html) throw new CliError(`The page of Web Lite has no ${String(from)} to fill — this CLI and its page are of different versions.`)
+    html = next
+  }
+  replace(/<title>[^<]*<\/title>/, `<title>${escapeHtml(config.title ?? app?.name ?? name)}</title>`)
+  replace(`<div id="app"></div>`, `<div id="app" ${attrs}></div>`)
+  replace("</head>", `  ${head.join("\n    ")}\n  </head>`)
+  if (config.lang) replace(/<html lang="[^"]*">/, `<html lang="${escapeHtml(config.lang)}">`)
+  writeFileSync(join(out, "index.html"), html)
+  if (mode === "path") writeFileSync(join(out, "404.html"), html)
+
+  return { out, bundle, files: walk(out), warnings }
+}

package/src/web/preview.ts

@@ -0,0 +1,50 @@
+import { createReadStream, existsSync, statSync } from "node:fs"
+import { createServer, type Server } from "node:http"
+import { join, resolve } from "node:path"
+import { contentType } from "../dev/devServer"
+
+/*
+ * `lecodes web preview`: a built folder, served as a static hosting serves it — files by their
+ * path, `index.html` for a folder. A folder built in `path` mode (it has a 404.html) gets what
+ * such a hosting is set up to give: the page for every path that is no file.
+ */
+
+export type PreviewServer = { url: string, port: number, close(): void }
+
+export const startPreview = async (dir: string, port: number): Promise<PreviewServer> => {
+  const root = resolve(dir)
+  const fallback = existsSync(join(root, "404.html")) ? join(root, "index.html") : null
+
+  const server: Server = createServer((req, res) => {
+    let path: string
+    try {
+      path = decodeURIComponent(new URL(req.url ?? "/", "http://localhost").pathname)
+    } catch {
+      res.writeHead(400); res.end(); return
+    }
+    const parts = path.split("/").filter(Boolean)
+    if (parts.some((p) => p === ".." || p === ".")) { res.writeHead(400); res.end(); return }
+    let file = join(root, ...parts)
+    if (existsSync(file) && statSync(file).isDirectory()) file = join(file, "index.html")
+    let status = 200
+    if (!existsSync(file) || !statSync(file).isFile()) {
+      // a file that is missing is missing; a route is the page's
+      if (!fallback || /\.[a-z0-9]+$/i.test(parts[parts.length - 1] ?? "")) { res.writeHead(404, { "content-type": "text/plain" }); res.end("Not found"); return }
+      file = fallback
+    }
+    res.writeHead(status, {
+      "content-type": contentType(file),
+      // what carries its hash in its name never changes; the page and the entry are asked for again
+      "cache-control": /[.-][0-9a-f]{8,}\.[a-z0-9]+$/i.test(file) ? "max-age=31536000, immutable" : "no-cache",
+    })
+    createReadStream(file).pipe(res)
+  })
+
+  await new Promise<void>((done, reject) => {
+    server.once("error", reject)
+    server.listen(port, "0.0.0.0", () => { server.removeListener("error", reject); done() })
+  })
+  const address = server.address()
+  const bound = typeof address === "object" && address !== null ? address.port : port
+  return { url: `http://localhost:${bound}/`, port: bound, close: () => server.close() }
+}