create-zoijs 0.1.4 → 0.2.0

package/templates/basic/dev-server.mjs

@@ -1,74 +1,124 @@
-// dev-server.mjs — a tiny static file server for this Zoijs app.
-//
-// Zero dependencies (Node built-ins only), no build step, no bundler. It serves
-// the project files so the import map in index.html can load @zoijs/core from
-// node_modules. Tries port 7310, then 7311 / 7312 / 7313 if one is busy.
-//
-//   node dev-server.mjs      (this is what `npm run dev` runs)
-
-import { createServer } from "node:http";
-import { readFile } from "node:fs/promises";
-import { extname, join, normalize } from "node:path";
-
-const PORTS = [7310, 7311, 7312, 7313];
-const ROOT = process.cwd();
-
-const TYPES = {
-  ".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",
-  ".woff2": "font/woff2",
-};
-
-const server = createServer(async (req, res) => {
-  let pathname = decodeURIComponent(new URL(req.url, "http://localhost").pathname);
-  if (pathname === "/") pathname = "/index.html";
-
-  // Resolve inside ROOT and refuse anything that climbs out of it.
-  const filePath = join(ROOT, normalize(pathname));
-  if (!filePath.startsWith(ROOT)) {
-    res.writeHead(403).end("Forbidden");
-    return;
-  }
-  try {
-    const body = await readFile(filePath);
-    res.writeHead(200, { "Content-Type": TYPES[extname(filePath)] || "application/octet-stream" });
-    res.end(body);
-  } catch {
-    res.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" }).end("Not found");
-  }
-});
-
-function start(i = 0) {
-  if (i >= PORTS.length) {
-    console.error(`\nAll dev ports are busy (${PORTS.join(", ")}). Free one and try again.\n`);
-    process.exit(1);
-  }
-  // Paired once-listeners: each attempt removes its sibling so a failed bind
-  // can't leave a stale "listening" handler that prints the wrong port later.
-  const onError = (err) => {
-    server.removeListener("listening", onListening);
-    if (err.code === "EADDRINUSE") start(i + 1);
-    else {
-      console.error(err);
-      process.exit(1);
-    }
-  };
-  const onListening = () => {
-    server.removeListener("error", onError);
-    const lines = ["", "  Zoijs dev server", "", `  - Local:  http://localhost:${PORTS[i]}`];
-    if (i > 0) lines.push(`  (ports ${PORTS.slice(0, i).join(", ")} were busy)`);
-    lines.push("");
-    console.log(lines.join("\n"));
-  };
-  server.once("error", onError);
-  server.once("listening", onListening);
-  server.listen(PORTS[i]);
-}
-
-start();
+// dev-server.mjs — a tiny static file server for this Zoijs app. DEVELOPMENT ONLY.
+//
+// Zero dependencies (Node built-ins only), no build step, no bundler. It serves
+// the project files — index.html, your modules, and whatever its import map points
+// at inside this folder (node_modules/, if you installed). Tries port 7310, then
+// 7311 / 7312 / 7313 if one is busy. The same file ships in every Zoijs template.
+//
+//   node dev-server.mjs      (this is what `npm run dev` runs)
+//
+// Safe defaults for a dev server:
+//   - listens on 127.0.0.1 only — other devices on your network can't reach it.
+//     To test from a phone on your LAN, opt in explicitly: ZOIJS_HOST=0.0.0.0 npm run dev
+//     (anyone on that network can then read your project files while it runs).
+//   - never serves dotfiles or dot-directories (.env, .git/, .npmrc, …);
+//   - never serves anything outside this folder (no `..`, no symlinks pointing out —
+//     except package-manager links inside node_modules/);
+//   - answers malformed URLs with 400 instead of crashing.
+// It is not a production server: deploy the static files to a real host.
+
+import { createServer } from "node:http";
+import { readFile, realpath } from "node:fs/promises";
+import { extname, resolve, relative, isAbsolute } from "node:path";
+
+const PORTS = [7310, 7311, 7312, 7313];
+const HOST = process.env.ZOIJS_HOST || "127.0.0.1";
+const ROOT = resolve(process.cwd());
+
+const TYPES = {
+  ".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",
+  ".woff2": "font/woff2",
+};
+
+const HEADERS = { "X-Content-Type-Options": "nosniff", "Cache-Control": "no-store", "Referrer-Policy": "no-referrer" };
+
+// Is `path` ROOT itself or inside it? (relative() handles separators, case and
+// sibling folders like `app-secrets` correctly — unlike a string-prefix check.)
+const inside = (base, path) => {
+  const rel = relative(base, path);
+  return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+};
+
+function send(res, status, body, type = "text/plain; charset=utf-8") {
+  res.writeHead(status, { ...HEADERS, "Content-Type": type });
+  res.end(body);
+}
+
+const server = createServer(async (req, res) => {
+  try {
+    let pathname;
+    try {
+      // Only the path (never the query string) maps to a file.
+      pathname = decodeURIComponent(new URL(req.url, "http://localhost").pathname);
+    } catch {
+      return send(res, 400, "Bad request");
+    }
+    if (pathname.includes("\0")) return send(res, 400, "Bad request");
+    if (pathname === "/") pathname = "/index.html";
+
+    const segments = pathname.split(/[\\/]+/).filter(Boolean);
+    // Hidden files and folders (.env, .git/, .npmrc, node_modules/.bin, …) are never
+    // served. 404, not 403, so it doesn't reveal whether they exist.
+    if (segments.some((s) => s.startsWith("."))) return send(res, 404, "Not found");
+
+    const filePath = resolve(ROOT, ...segments);
+    if (!inside(ROOT, filePath)) return send(res, 404, "Not found");
+
+    // Don't follow symlinks out of the project. Package managers (npm link, pnpm)
+    // legitimately link packages into node_modules/, so links there are allowed.
+    let real;
+    try {
+      real = await realpath(filePath);
+    } catch {
+      return send(res, 404, "Not found");
+    }
+    if (!inside(ROOT, real) && segments[0] !== "node_modules") return send(res, 404, "Not found");
+
+    const body = await readFile(real);
+    send(res, 200, body, TYPES[extname(filePath)] || "application/octet-stream");
+  } catch {
+    // Directories, permission errors, files deleted mid-request: a generic answer
+    // that never echoes a filesystem path.
+    if (!res.headersSent) send(res, 404, "Not found");
+    else res.destroy();
+  }
+});
+
+function start(i = 0) {
+  if (i >= PORTS.length) {
+    console.error(`\nAll dev ports are busy (${PORTS.join(", ")}). Free one and try again.\n`);
+    process.exit(1);
+  }
+  // Paired once-listeners: each attempt removes its sibling so a failed bind
+  // can't leave a stale "listening" handler that prints the wrong port later.
+  const onError = (err) => {
+    server.removeListener("listening", onListening);
+    if (err.code === "EADDRINUSE") start(i + 1);
+    else {
+      console.error(err);
+      process.exit(1);
+    }
+  };
+  const onListening = () => {
+    server.removeListener("error", onError);
+    const lines = ["", "  Zoijs dev server", "", `  - Local:  http://localhost:${PORTS[i]}`];
+    if (i > 0) lines.push(`  (ports ${PORTS.slice(0, i).join(", ")} were busy)`);
+    if (HOST !== "127.0.0.1" && HOST !== "localhost" && HOST !== "::1") {
+      lines.push(`  ⚠ Listening on ${HOST} (ZOIJS_HOST): other devices on your network can read`, `    this project's files while the server runs. Development only.`);
+    }
+    lines.push("");
+    console.log(lines.join("\n"));
+  };
+  server.once("error", onError);
+  server.once("listening", onListening);
+  server.listen(PORTS[i], HOST);
+}
+
+start();

package/templates/basic/index.html

@@ -1,22 +1,24 @@
-<!DOCTYPE html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>{{APP_TITLE}}</title>
-    <link rel="stylesheet" href="./src/style.css" />
-    <!-- No build step: an import map points the @zoijs/core name at the package
-         installed in node_modules. `npm install` puts it there. -->
-    <script type="importmap">
-      {
-        "imports": {
-          "@zoijs/core": "./node_modules/@zoijs/core/src/index.js"
-        }
-      }
-    </script>
-  </head>
-  <body>
-    <div id="app"></div>
-    <script type="module" src="./src/app.js"></script>
-  </body>
-</html>
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>{{APP_TITLE}}</title>
+    <link rel="stylesheet" href="./src/style.css" />
+    <!-- No build step: an import map points the @zoijs/core name at the package
+         installed in node_modules. `npm install` puts it there. -->
+    <!-- Development entry (warnings + devtools). When you deploy, point "@zoijs/core"
+         at ./node_modules/@zoijs/core/src/prod.js — the production entry. -->
+    <script type="importmap">
+      {
+        "imports": {
+          "@zoijs/core": "./node_modules/@zoijs/core/src/index.js"
+        }
+      }
+    </script>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="./src/app.js"></script>
+  </body>
+</html>

package/templates/basic/package.json

@@ -1,12 +1,12 @@
-{
-  "name": "{{APP_NAME}}",
-  "version": "0.0.0",
-  "private": true,
-  "type": "module",
-  "scripts": {
-    "dev": "node dev-server.mjs"
-  },
-  "dependencies": {
-    "@zoijs/core": "^1.1.0"
-  }
-}
+{
+  "name": "{{APP_NAME}}",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "node dev-server.mjs"
+  },
+  "dependencies": {
+    "@zoijs/core": "^{{ZOIJS_CORE_VERSION}}"
+  }
+}

package/templates/basic/src/app.js

@@ -1,18 +1,18 @@
-import { html, mount, createState } from "@zoijs/core";
-
-// A complete Zoijs app: state, markup, and one mount call. No build step.
-function App() {
-  const count = createState(0);
-
-  return html`
-    <main>
-      <h1>{{APP_TITLE}}</h1>
-      <p>Edit <code>src/app.js</code> and reload.</p>
-      <button onclick=${() => count.set(count.get() + 1)}>
-        Clicked ${() => count.get()} times
-      </button>
-    </main>
-  `;
-}
-
-mount(App, "#app");
+import { html, mount, createState } from "@zoijs/core";
+
+// A complete Zoijs app: state, markup, and one mount call. No build step.
+function App() {
+  const count = createState(0);
+
+  return html`
+    <main>
+      <h1>{{APP_TITLE}}</h1>
+      <p>Edit <code>src/app.js</code> and reload.</p>
+      <button onclick=${() => count.set(count.get() + 1)}>
+        Clicked ${() => count.get()} times
+      </button>
+    </main>
+  `;
+}
+
+mount(App, "#app");

package/templates/basic/src/style.css

@@ -1,33 +1,33 @@
-:root {
-  color-scheme: light dark;
-  font-family: system-ui, sans-serif;
-}
-
-body {
-  margin: 0;
-  display: grid;
-  place-items: center;
-  min-height: 100vh;
-}
-
-main {
-  text-align: center;
-  padding: 2rem;
-}
-
-h1 {
-  margin: 0 0 0.5rem;
-}
-
-button {
-  font: inherit;
-  padding: 0.6rem 1.2rem;
-  border: 1px solid currentColor;
-  border-radius: 8px;
-  background: transparent;
-  cursor: pointer;
-}
-
-button:hover {
-  background: rgba(127, 127, 127, 0.12);
-}
+:root {
+  color-scheme: light dark;
+  font-family: system-ui, sans-serif;
+}
+
+body {
+  margin: 0;
+  display: grid;
+  place-items: center;
+  min-height: 100vh;
+}
+
+main {
+  text-align: center;
+  padding: 2rem;
+}
+
+h1 {
+  margin: 0 0 0.5rem;
+}
+
+button {
+  font: inherit;
+  padding: 0.6rem 1.2rem;
+  border: 1px solid currentColor;
+  border-radius: 8px;
+  background: transparent;
+  cursor: pointer;
+}
+
+button:hover {
+  background: rgba(127, 127, 127, 0.12);
+}

package/templates/library/package.json

@@ -29,10 +29,10 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@zoijs/core": "^1.2.0"
+    "@zoijs/core": "^{{ZOIJS_CORE_VERSION}}"
   },
   "devDependencies": {
-    "@zoijs/core": "^1.2.0",
+    "@zoijs/core": "^{{ZOIJS_CORE_VERSION}}",
     "typescript": "^5.9.3"
   }
 }

package/templates/minimal/README.md

@@ -1,23 +1,44 @@
 # {{APP_TITLE}}
 
-The smallest possible [Zoijs](https://zoijs.dev) app — **two files, no install, no
-build step.** A blank canvas.
+The smallest possible [Zoijs](https://zoijs.dev) app — **two source files, no install,
+no build step.** A blank canvas.
 
 ## Run it
 
-Any static file server works. The simplest:
-
 ```bash
-npx serve . -l 7310
+npm run dev
 ```
 
-Then open <http://localhost:7310>.
+Then open <http://localhost:7310>. No `npm install` needed: `@zoijs/core` comes from the
+CDN, and `npm run dev` just runs `node dev-server.mjs` — a tiny static server that
+ships in this folder (Node built-ins only, nothing is downloaded). It is for
+**development only**: it listens on `127.0.0.1`, never serves dotfiles (`.env`, `.git/`)
+or anything outside this folder, and falls back to 7311–7313 if 7310 is busy. To try the
+app from a phone on your network, opt in with `ZOIJS_HOST=0.0.0.0 npm run dev` (anyone
+on that network can then read these files while it runs).
+
+Any other static file server works too, but `file://` doesn't — browsers won't load
+ES modules from disk.
+
+
+## Deploy
+
+In `index.html`, point `"@zoijs/core"` at the production entry —
+`{{ZOIJS_CORE_CDN}}prod.js` (its integrity hash is already in the map) — so
+development warnings and the devtools hook are off. Keep the exact version; to upgrade,
+change it deliberately and update every URL and integrity hash together.
+
+Before going live, go through the
+[production security checklist](https://zoijs.dev/production-security) — your CSP must
+allow `https://cdn.jsdelivr.net` and your import map's hash.
 
 ## What's here
 
-- `index.html` — loads `@zoijs/core` from a CDN (pinned to the `v1` major) and
-  mounts `app.js`.
+- `index.html` — loads `@zoijs/core` {{ZOIJS_CORE_VERSION}} from jsDelivr (that exact version,
+  integrity-checked) and mounts `app.js`.
 - `app.js` — a counter: state, markup, and one `mount` call.
+- `dev-server.mjs` + `package.json` — the local development server and its `dev` script
+  (no dependencies). Don't deploy them; deploy `index.html` and `app.js`.
 
 That's the whole project. Edit `app.js` and reload — there is nothing to build.
 

package/templates/minimal/dev-server.mjs

@@ -0,0 +1,124 @@
+// dev-server.mjs — a tiny static file server for this Zoijs app. DEVELOPMENT ONLY.
+//
+// Zero dependencies (Node built-ins only), no build step, no bundler. It serves
+// the project files — index.html, your modules, and whatever its import map points
+// at inside this folder (node_modules/, if you installed). Tries port 7310, then
+// 7311 / 7312 / 7313 if one is busy. The same file ships in every Zoijs template.
+//
+//   node dev-server.mjs      (this is what `npm run dev` runs)
+//
+// Safe defaults for a dev server:
+//   - listens on 127.0.0.1 only — other devices on your network can't reach it.
+//     To test from a phone on your LAN, opt in explicitly: ZOIJS_HOST=0.0.0.0 npm run dev
+//     (anyone on that network can then read your project files while it runs).
+//   - never serves dotfiles or dot-directories (.env, .git/, .npmrc, …);
+//   - never serves anything outside this folder (no `..`, no symlinks pointing out —
+//     except package-manager links inside node_modules/);
+//   - answers malformed URLs with 400 instead of crashing.
+// It is not a production server: deploy the static files to a real host.
+
+import { createServer } from "node:http";
+import { readFile, realpath } from "node:fs/promises";
+import { extname, resolve, relative, isAbsolute } from "node:path";
+
+const PORTS = [7310, 7311, 7312, 7313];
+const HOST = process.env.ZOIJS_HOST || "127.0.0.1";
+const ROOT = resolve(process.cwd());
+
+const TYPES = {
+  ".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",
+  ".woff2": "font/woff2",
+};
+
+const HEADERS = { "X-Content-Type-Options": "nosniff", "Cache-Control": "no-store", "Referrer-Policy": "no-referrer" };
+
+// Is `path` ROOT itself or inside it? (relative() handles separators, case and
+// sibling folders like `app-secrets` correctly — unlike a string-prefix check.)
+const inside = (base, path) => {
+  const rel = relative(base, path);
+  return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+};
+
+function send(res, status, body, type = "text/plain; charset=utf-8") {
+  res.writeHead(status, { ...HEADERS, "Content-Type": type });
+  res.end(body);
+}
+
+const server = createServer(async (req, res) => {
+  try {
+    let pathname;
+    try {
+      // Only the path (never the query string) maps to a file.
+      pathname = decodeURIComponent(new URL(req.url, "http://localhost").pathname);
+    } catch {
+      return send(res, 400, "Bad request");
+    }
+    if (pathname.includes("\0")) return send(res, 400, "Bad request");
+    if (pathname === "/") pathname = "/index.html";
+
+    const segments = pathname.split(/[\\/]+/).filter(Boolean);
+    // Hidden files and folders (.env, .git/, .npmrc, node_modules/.bin, …) are never
+    // served. 404, not 403, so it doesn't reveal whether they exist.
+    if (segments.some((s) => s.startsWith("."))) return send(res, 404, "Not found");
+
+    const filePath = resolve(ROOT, ...segments);
+    if (!inside(ROOT, filePath)) return send(res, 404, "Not found");
+
+    // Don't follow symlinks out of the project. Package managers (npm link, pnpm)
+    // legitimately link packages into node_modules/, so links there are allowed.
+    let real;
+    try {
+      real = await realpath(filePath);
+    } catch {
+      return send(res, 404, "Not found");
+    }
+    if (!inside(ROOT, real) && segments[0] !== "node_modules") return send(res, 404, "Not found");
+
+    const body = await readFile(real);
+    send(res, 200, body, TYPES[extname(filePath)] || "application/octet-stream");
+  } catch {
+    // Directories, permission errors, files deleted mid-request: a generic answer
+    // that never echoes a filesystem path.
+    if (!res.headersSent) send(res, 404, "Not found");
+    else res.destroy();
+  }
+});
+
+function start(i = 0) {
+  if (i >= PORTS.length) {
+    console.error(`\nAll dev ports are busy (${PORTS.join(", ")}). Free one and try again.\n`);
+    process.exit(1);
+  }
+  // Paired once-listeners: each attempt removes its sibling so a failed bind
+  // can't leave a stale "listening" handler that prints the wrong port later.
+  const onError = (err) => {
+    server.removeListener("listening", onListening);
+    if (err.code === "EADDRINUSE") start(i + 1);
+    else {
+      console.error(err);
+      process.exit(1);
+    }
+  };
+  const onListening = () => {
+    server.removeListener("error", onError);
+    const lines = ["", "  Zoijs dev server", "", `  - Local:  http://localhost:${PORTS[i]}`];
+    if (i > 0) lines.push(`  (ports ${PORTS.slice(0, i).join(", ")} were busy)`);
+    if (HOST !== "127.0.0.1" && HOST !== "localhost" && HOST !== "::1") {
+      lines.push(`  ⚠ Listening on ${HOST} (ZOIJS_HOST): other devices on your network can read`, `    this project's files while the server runs. Development only.`);
+    }
+    lines.push("");
+    console.log(lines.join("\n"));
+  };
+  server.once("error", onError);
+  server.once("listening", onListening);
+  server.listen(PORTS[i], HOST);
+}
+
+start();

package/templates/minimal/index.html

@@ -4,10 +4,12 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>{{APP_TITLE}}</title>
-    <!-- Zero install, zero build: load @zoijs/core straight from a CDN.
-         Pin the major version (@1) so your app never breaks unexpectedly. -->
+    <!-- Zero install, zero build: @zoijs/core {{ZOIJS_CORE_VERSION}} from jsDelivr, pinned to that
+         exact version, with an integrity hash for every module file (the browser refuses
+         a file whose bytes don't match). If you use a strict CSP, allow
+         https://cdn.jsdelivr.net in script-src — or vendor the files instead. -->
     <script type="importmap">
-      { "imports": { "@zoijs/core": "https://esm.sh/@zoijs/core@1" } }
+      {{ZOIJS_CORE_IMPORTMAP}}
     </script>
   </head>
   <body>

package/templates/minimal/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "{{APP_NAME}}",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "node dev-server.mjs"
+  }
+}

package/templates/typescript/README.md

@@ -22,6 +22,26 @@ npm run dev
 
 Open the printed URL (it falls back to 7311–7313 if the port is busy).
 
+The dev server is for **development only**: it listens on `127.0.0.1` (this machine),
+never serves dotfiles (`.env`, `.git/`, …) or anything outside the project folder, and is
+not meant for hosting. To try the app from a phone on your network, opt in explicitly with
+`ZOIJS_HOST=0.0.0.0 npm run dev` — while it runs, anyone on that network can read the
+project's files.
+
+## Deploy
+
+This page loads the **development** entry of `@zoijs/core` (helpful warnings, devtools).
+When you deploy, change the import map in `index.html` to the **production** entry —
+same API, warnings and the devtools hook off:
+
+```html
+"@zoijs/core": "./node_modules/@zoijs/core/src/prod.js"
+```
+
+Then deploy the files to a static host (not the dev server) and go through the
+[production security checklist](https://zoijs.dev/production-security) — security headers,
+a Content-Security-Policy with your import map's hash, CSRF, and more.
+
 ## Type-check
 
 ```bash

package/templates/typescript/_gitignore

@@ -1 +1 @@
-node_modules
+node_modules