jskelet 0.1.1

package/src/server/assets.js

@@ -0,0 +1,119 @@
+/**
+ * Build çıktısı manifest'ine erişim: mantıksal isim → hash'li public URL.
+ *
+ * Build çalışmadıysa uygulama yine ayağa kalkar. `asset()` `/assets/<isim>`
+ * döner ve `hasAsset()` false olur; layout stylesheet/script etiketlerini hiç
+ * basmaz. Böylece `jskelet build` unutulduğunda hata yerine stilsiz ama
+ * çalışan bir sayfa görürsünüz.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { getConfig } from "../config/index.js";
+
+const isDev = process.env.NODE_ENV === "development";
+
+/** @type {{ manifest: Record<string, string> } | null} */
+let cached = null;
+let warned = false;
+
+function load() {
+  const { generated } = getConfig().dirs;
+
+  /** @type {Record<string, string>} */
+  let manifest = {};
+
+  try {
+    manifest = JSON.parse(
+      fs.readFileSync(path.join(generated, "manifest.json"), "utf8"),
+    );
+  } catch {
+    if (!warned) {
+      warned = true;
+      console.warn("[assets] manifest yok — `jskelet build` çalıştırın.");
+    }
+  }
+
+  return { manifest };
+}
+
+function state() {
+  // Dev'de her istekte yeniden okunur (watch build hash'leri değiştirir);
+  // prod'da bir kez.
+  if (isDev || !cached) cached = load();
+  return cached;
+}
+
+/**
+ * @param {string} name Örn. "app.css", "main.js", "sprite.svg"
+ * @returns {string}
+ */
+export function asset(name) {
+  return state().manifest[name] ?? `/assets/${name}`;
+}
+
+/**
+ * @param {string} name
+ * @returns {boolean}
+ */
+export function hasAsset(name) {
+  return Boolean(state().manifest[name]);
+}
+
+/**
+ * @typedef {{ width: number, height: number,
+ *   variants: { width: number, url: string }[] }} OptimizedImage
+ */
+
+/** @type {Record<string, OptimizedImage> | null} */
+let images = null;
+
+/**
+ * `build/tasks/images.mjs` çıktısı: kaynak yolundan webp varyantlarına.
+ * Build çalışmadıysa boş kalır ve görseller orijinalleriyle servis edilir.
+ *
+ * @param {string} [src] Örn. "/hero.png"
+ * @returns {OptimizedImage | undefined}
+ */
+export function optimizedImage(src) {
+  if (isDev || !images) {
+    try {
+      const file = path.join(getConfig().dirs.generated, "images.json");
+      images = JSON.parse(fs.readFileSync(file, "utf8")).images ?? {};
+    } catch {
+      images = {};
+    }
+  }
+
+  return src ? images[src] : undefined;
+}
+
+/** @type {{ url: string, ids: Set<string> } | null} */
+let spriteIds = null;
+
+/**
+ * Sprite'taki sembol kimlikleri. Sprite yalnızca kaynakta **statik olarak**
+ * görülen ikon adlarını içerir; adı çalışma anında hesaplanan bir `icon()`
+ * çağrısı eksik sembole işaret ederse ekranda sessizce boşluk kalır. Dev'de
+ * `icon()` bu kümeye bakıp uyarır.
+ *
+ * @returns {Set<string>}
+ */
+export function getSpriteIds() {
+  const url = asset("sprite.svg");
+  if (spriteIds?.url === url) return spriteIds.ids;
+
+  /** @type {Set<string>} */
+  const ids = new Set();
+
+  try {
+    const file = path.join(getConfig().dirs.public, url.replace(/^\//, ""));
+    const svg = fs.readFileSync(file, "utf8");
+    for (const match of svg.matchAll(/<symbol id="([^"]+)"/g)) ids.add(match[1]);
+  } catch {
+    // Sprite okunamazsa uyarı üretilmez; asıl akış etkilenmez.
+  }
+
+  spriteIds = { url, ids };
+  return ids;
+}

package/src/server/create-app.js

@@ -0,0 +1,167 @@
+/**
+ * Express uygulamasını kurar ve dinlemeye başlar.
+ *
+ * Middleware **sırası** bu dosyanın asıl değeri; her konumun bir sebebi var
+ * ve yer değiştirmek sessiz bozulmalara yol açıyor:
+ *
+ *   1. rewrites(beforeFiles) — statik dosyalardan da önce çalışmalı, yoksa
+ *      `/assets/x.js` yolunu başka bir yere taşıyan kural işlemez.
+ *   2. compression — static'ten önce; sonra gelirse statik dosyalar sıkışmaz.
+ *   3. headers → devGate → redirects — gate'in 404'ü redirect'ten önce.
+ *   4. staticPrecompressed → express.static — build'de üretilmiş `.br`/`.gz`
+ *      kopyalar varsa onlar servis edilir (kalite 11), yoksa istek altındaki
+ *      static'e düşer ve middleware anında sıkıştırır (kalite 5).
+ *   5. body parser'lar — statikten sonra: görsel isteklerinde gövde ayrıştırma
+ *      maliyeti ödenmesin.
+ *   6. rewrites(afterFiles) — statik denendikten sonra, sayfalardan önce.
+ *   7. route'lar → 404 → hata yönetimi.
+ */
+import path from "node:path";
+import process from "node:process";
+import express from "express";
+import { compression } from "./middleware/compression.js";
+import { headersMiddleware } from "./middleware/headers.js";
+import { staticPrecompressed } from "./middleware/static-precompressed.js";
+import { devGate } from "./middleware/dev-gate.js";
+import { redirects } from "./middleware/redirects.js";
+import { configRewrites } from "./middleware/upstream-proxy.js";
+import { getConfig, loadConfig } from "../config/index.js";
+import { IMMUTABLE_CACHE } from "../config/defaults.js";
+import { registerRoutes } from "./router.js";
+import { renderNotFound } from "./render.js";
+import { renderStatusPage, statusFromError } from "./status-page.js";
+import { startPrewarm } from "./prewarm.js";
+import { isNotFoundError, isRedirectError } from "../http/control-flow.js";
+
+/**
+ * @param {{ root?: string, configFile?: string }} [options]
+ * @returns {Promise<import('express').Express>}
+ */
+export async function createApp(options = {}) {
+  // Config middleware'lerden önce okunur; yoksa uyarı basar, akış durmaz.
+  await loadConfig(options);
+  const config = getConfig();
+
+  const app = express();
+
+  app.disable("x-powered-by");
+  app.use((req, res, next) => {
+    res.setHeader("X-Powered-By", config.brand.poweredBy);
+    next();
+  });
+
+  app.set("etag", "strong");
+  // Ters proxy arkasında doğru protokol ve istemci IP'si için.
+  app.set("trust proxy", true);
+
+  app.use(configRewrites("beforeFiles"));
+  app.use(compression());
+  app.use(headersMiddleware());
+  app.use(devGate());
+  app.use(redirects());
+
+  app.use(staticPrecompressed(config.dirs.public));
+  app.use(
+    express.static(config.dirs.public, {
+      index: false,
+      redirect: false,
+      // Hash'siz dosyalar (favicon, robots eki, elle konmuş görseller) içerik
+      // değişse de aynı adla kalıyor; bir yıllık cache onları güncellenemez
+      // hâle getiriyordu. Hash'li çıktı aşağıda ayrıca immutable işaretlenir.
+      maxAge: "1h",
+      setHeaders(res, filePath) {
+        if (filePath.includes(`${path.sep}assets${path.sep}`)) {
+          res.setHeader("Cache-Control", IMMUTABLE_CACHE);
+        }
+      },
+    }),
+  );
+
+  // Dev overlay yalnızca development'ta; dinamik import sayesinde prod
+  // sürecine hiçbir şey yüklenmez.
+  if (process.env.NODE_ENV === "development") {
+    const { mountDevtools } = await import("./dev/devtools.js");
+    mountDevtools(app);
+  }
+
+  app.use(express.urlencoded({ extended: false, limit: "64kb" }));
+  app.use(express.json({ limit: "256kb" }));
+
+  app.use(configRewrites("afterFiles"));
+
+  await registerRoutes(app);
+
+  app.use(async (req, res, next) => {
+    try {
+      res.status(404).type("html").send(await renderNotFound());
+    } catch (error) {
+      next(error);
+    }
+  });
+
+  // Hata yönetimi: notFound/redirect kontrol akışı burada da yakalanır,
+  // çünkü bir controller dışında (ör. middleware içinde) fırlatılabilir.
+  app.use(async (error, req, res, next) => {
+    if (res.headersSent) {
+      next(error);
+      return;
+    }
+
+    if (isRedirectError(error)) {
+      res.redirect(error.statusCode, error.location);
+      return;
+    }
+
+    if (isNotFoundError(error)) {
+      res.status(404).type("html").send(await renderNotFound());
+      return;
+    }
+
+    const status = statusFromError(error);
+    console.error(`[${status}] ${req.method} ${req.originalUrl}`, error);
+
+    // Hata sayfası hiçbir katmanda saklanmamalı: geçici bir upstream arızası
+    // CDN'de dakikalarca yaşayan bir 500 sayfasına dönüşmesin.
+    res.setHeader("Cache-Control", "no-store");
+    res
+      .status(status)
+      .type("html")
+      .send(await renderStatusPage(status, { error }));
+  });
+
+  return app;
+}
+
+/**
+ * Uygulamayı kurup dinlemeye başlar. CLI `jskelet start` bunu çağırır;
+ * gömülü kullanımda `createApp()` tercih edilir.
+ *
+ * @param {{ root?: string, configFile?: string, port?: number, host?: string }} [options]
+ * @returns {Promise<import('http').Server>}
+ */
+export async function startServer(options = {}) {
+  const app = await createApp(options);
+  const port = Number(options.port ?? process.env.PORT ?? 3000);
+  const host = options.host ?? process.env.HOST ?? "0.0.0.0";
+
+  // Tek bir istek hatası süreci düşürmesin; logla ve ayakta kal. Bir haber
+  // sitesinde tek sayfanın hatası tüm siteyi indirmemeli.
+  process.on("unhandledRejection", (reason) => {
+    console.error("[unhandledRejection]", reason);
+  });
+  process.on("uncaughtException", (error) => {
+    console.error("[uncaughtException]", error);
+  });
+
+  return new Promise((resolve) => {
+    const server = app.listen(port, host, () => {
+      // Bu satırın biçimi sözleşme: `jskelet dev` sunucunun hazır olduğunu
+      // buradan anlar ve özet satırını ona göre basar.
+      console.log(
+        `jskelet → http://localhost:${port} (${process.env.NODE_ENV ?? "production"})`,
+      );
+      startPrewarm({ port });
+      resolve(server);
+    });
+  });
+}

package/src/server/dev/devtools.js

@@ -0,0 +1,383 @@
+/**
+ * Dev overlay'in sunucu tarafı: istek/render ölçümleri, hata günlüğü ve
+ * overlay modülünün servisi.
+ *
+ * Yalnızca `NODE_ENV=development` iken `create-app.js` tarafından mount
+ * edilir; build çıktısına hiçbir şey eklemez (overlay dosyası esbuild
+ * entry'si değil, doğrudan diskten servis edilir).
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import express from "express";
+import * as log from "../../log.mjs";
+import { FRAMEWORK_ROOT, getConfig } from "../../config/index.js";
+import { prewarm, prewarmProgress } from "../prewarm.js";
+import { clearHtmlCache } from "../html-cache.js";
+import {
+  buildReport,
+  clearPageReports,
+  recordPageReport,
+  trackServerFetch,
+} from "./report.js";
+
+/** Overlay dosyaları framework paketinden servis edilir, uygulamadan değil. */
+const DEVTOOLS_DIR = path.join(FRAMEWORK_ROOT, "src", "client", "devtools");
+const OVERLAY_FILE = path.join(DEVTOOLS_DIR, "overlay.js");
+const LOGO_FILE = path.join(FRAMEWORK_ROOT, "src", "logo.png");
+
+/** @type {ReturnType<typeof getConfig>["brand"]} */
+let brand;
+
+/** Her sürecin kendine özgü kimliği; overlay restart'ı buradan anlar. */
+const BOOT_ID = `${Date.now()}-${process.pid}`;
+
+const MAX_ENTRIES = 50;
+
+// Kayıtlar süreç belleğinde durursa `node --watch` her yeniden başlatmada
+// geçmişi siler ve overlay boşalır. Bu dosya restart'lar arasında istek/hata
+// geçmişini taşır.
+//
+// Proje ağacına yazılmaz: her yazma `node --watch`'u tetikleyip sunucuyu
+// yeniden başlatıyordu ve bu kendini besleyen bir döngü kuruyordu
+// (restart → açılış uyarısı → yazma → restart).
+const STATE_FILE = path.join(
+  os.tmpdir(),
+  `jskelet-devtools-${createHash("sha1")
+    .update(getConfig().root)
+    .digest("hex")
+    .slice(0, 10)}.json`,
+);
+
+/** @type {{ id: number, method: string, url: string, status: number, ms: number, cache: string | null, at: number }[]} */
+let requests = [];
+
+/** @type {{ id: number, level: string, message: string, stack: string | null, url: string | null, at: number }[]} */
+let errors = [];
+
+let nextId = 1;
+
+/** Süreç başlarken önceki turun kayıtlarını geri yükler. */
+function restore() {
+  try {
+    const saved = JSON.parse(fs.readFileSync(STATE_FILE, "utf8"));
+    requests = saved.requests ?? [];
+    errors = saved.errors ?? [];
+    nextId =
+      Math.max(0, ...requests.map((item) => item.id), ...errors.map((item) => item.id)) + 1;
+  } catch {
+    // İlk çalıştırma ya da bozuk dosya: temiz başla.
+  }
+}
+
+/** @type {NodeJS.Timeout | null} */
+let saveTimer = null;
+
+/** Yazma her istekte değil, kısa bir sessizlikten sonra yapılır. */
+function persist() {
+  if (saveTimer) return;
+
+  saveTimer = setTimeout(() => {
+    saveTimer = null;
+    try {
+      fs.mkdirSync(path.dirname(STATE_FILE), { recursive: true });
+      fs.writeFileSync(STATE_FILE, JSON.stringify({ requests, errors }));
+    } catch {
+      // Günlük kalıcılığı en iyi çaba; başarısızlık dev akışını durdurmamalı.
+    }
+  }, 300);
+
+  saveTimer.unref?.();
+}
+
+/**
+ * @param {unknown[]} list
+ */
+function trim(list) {
+  while (list.length > MAX_ENTRIES) list.shift();
+}
+
+/**
+ * @param {string} level
+ * @param {string} message
+ * @param {{ stack?: string | null, url?: string | null }} [extra]
+ */
+export function recordServerError(level, message, extra = {}) {
+  errors.push({
+    id: nextId++,
+    level,
+    message,
+    stack: extra.stack ?? null,
+    url: extra.url ?? null,
+    at: Date.now(),
+  });
+  trim(errors);
+  persist();
+}
+
+/**
+ * `console.error` / `console.warn` çıktısını da overlay'e taşır: sunucudaki
+ * uyarılar terminalde kaybolmasın.
+ */
+function patchConsole() {
+  for (const level of /** @type {const} */ (["error", "warn"])) {
+    const original = console[level].bind(console);
+    console[level] = (...args) => {
+      const error = args.find((arg) => arg instanceof Error);
+      recordServerError(level, args.map(format).join(" "), {
+        stack: error?.stack ?? null,
+      });
+      original(...args);
+    };
+  }
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+function format(value) {
+  if (typeof value === "string") return value;
+  if (value instanceof Error) return `${value.name}: ${value.message}`;
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+
+/** Her HTML isteğinin süresini ve cache durumunu kaydeder. */
+function timing() {
+  /** @type {import('express').RequestHandler} */
+  return (req, res, next) => {
+    if (req.path.startsWith(brand.devBasePath)) return next();
+
+    // Önbellek ısıtması yüzlerce istek atıyor; terminali ve panelin istek
+    // listesini doldurmasın. İlerlemesi baloncuğun yanındaki rozette görünür.
+    if (req.headers["user-agent"] === brand.prewarmUserAgent) return next();
+
+    const started = process.hrtime.bigint();
+
+    res.on("finish", () => {
+      const type = res.getHeader("Content-Type");
+      if (!String(type ?? "").includes("text/html")) return;
+
+      const entry = {
+        id: nextId++,
+        method: req.method,
+        url: req.originalUrl,
+        status: res.statusCode,
+        ms: Number(process.hrtime.bigint() - started) / 1e6,
+        cache: /** @type {string | null} */ (res.getHeader(brand.cacheHeader) ?? null),
+        at: Date.now(),
+      };
+
+      requests.push(entry);
+      trim(requests);
+      persist();
+      // Terminalde canlı istek satırı.
+      log.http(entry);
+    });
+
+    next();
+  };
+}
+
+/* ------------------------------------------------------------ live reload */
+
+/** @type {Set<import('express').Response>} */
+const clients = new Set();
+
+/**
+ * @param {import('express').Response} res
+ * @param {object} payload
+ */
+function send(res, payload) {
+  res.write(`data: ${JSON.stringify(payload)}\n\n`);
+}
+
+/** @param {object} payload */
+function broadcast(payload) {
+  for (const client of clients) send(client, payload);
+}
+
+/**
+ * Build watch'ı manifest'i her turda yeniden yazar. CSS değiştiyse sayfa
+ * yenilenmeden stylesheet takas edilir (durum ve kaydırma korunur); JS ya da
+ * başka bir varlık değiştiyse tam yenileme gerekir.
+ */
+function watchManifest() {
+  const file = path.join(getConfig().dirs.generated, "manifest.json");
+
+  /** @returns {Record<string, string>} */
+  const read = () => {
+    try {
+      return JSON.parse(fs.readFileSync(file, "utf8"));
+    } catch {
+      return {};
+    }
+  };
+
+  let previous = read();
+  /** @type {NodeJS.Timeout | null} */
+  let timer = null;
+
+  try {
+    fs.watch(path.dirname(file), (event, name) => {
+      if (name !== "manifest.json") return;
+
+      clearTimeout(timer);
+      timer = setTimeout(() => {
+        const next = read();
+        const changed = Object.keys(next).filter((key) => next[key] !== previous[key]);
+        previous = next;
+
+        if (!changed.length) return;
+
+        // Önbellekteki HTML eski hash'li varlık URL'lerini taşıyor; temizlenmezse
+        // sayfa silinmiş dosyayı istemeye devam eder.
+        clearHtmlCache();
+
+        if (changed.length === 1 && changed[0] === "app.css") {
+          broadcast({ type: "css", href: next["app.css"] });
+          return;
+        }
+
+        broadcast({ type: "reload" });
+      }, 120);
+    });
+  } catch {
+    // Watch desteklenmiyorsa live reload devre dışı kalır; gerisi çalışır.
+  }
+}
+
+/**
+ * Overlay script'i + istatistik uçları.
+ * @returns {import('express').Router}
+ */
+function router() {
+  const api = express.Router();
+
+  api.get("/overlay.js", (req, res) => {
+    res.type("application/javascript");
+    res.setHeader("Cache-Control", "no-store");
+    fs.createReadStream(OVERLAY_FILE).pipe(res);
+  });
+
+  api.get("/logo.png", (req, res) => {
+    res.type("image/png");
+    res.setHeader("Cache-Control", "no-store");
+    fs.createReadStream(LOGO_FILE).pipe(res);
+  });
+
+  api.get("/events", (req, res) => {
+    res.writeHead(200, {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-store",
+      Connection: "keep-alive",
+    });
+
+    send(res, { type: "hello", boot: BOOT_ID });
+    clients.add(res);
+    req.on("close", () => clients.delete(res));
+  });
+
+  api.get("/stats", (req, res) => {
+    const usage = process.memoryUsage();
+    res.setHeader("Cache-Control", "no-store");
+    res.json({
+      pid: process.pid,
+      // Overlay yeniden başlatmayı bu kimlikten anlar; kendi durumunu
+      // sıfırlamadan yalnızca "restarted" bilgisini gösterir.
+      boot: BOOT_ID,
+      uptime: process.uptime(),
+      node: process.version,
+      memory: { rss: usage.rss, heapUsed: usage.heapUsed },
+      prewarm: { ...prewarmProgress },
+      requests: requests.slice(-25).reverse(),
+      errors: errors.slice(-25).reverse(),
+    });
+  });
+
+  // Detaylı rapor: kendi sayfası, script'i ve veri ucu.
+  api.get("/report", (req, res) => {
+    res.type("html");
+    res.setHeader("Cache-Control", "no-store");
+    fs.createReadStream(path.join(DEVTOOLS_DIR, "report.html")).pipe(res);
+  });
+
+  api.get("/report.js", (req, res) => {
+    res.type("application/javascript");
+    res.setHeader("Cache-Control", "no-store");
+    fs.createReadStream(path.join(DEVTOOLS_DIR, "report.js")).pipe(res);
+  });
+
+  api.get("/report/data", (req, res) => {
+    res.setHeader("Cache-Control", "no-store");
+    res.json(
+      buildReport({
+        requests: requests.slice().reverse(),
+        errors: errors.slice().reverse(),
+      }),
+    );
+  });
+
+  // Overlay her sayfadan ölçüm paketi gönderir; rapor bunları biriktirir.
+  api.post("/vitals", express.json({ limit: "512kb" }), (req, res) => {
+    recordPageReport(req.body);
+    res.status(204).end();
+  });
+
+  api.post("/report/clear", (req, res) => {
+    clearPageReports();
+    res.json({ ok: true });
+  });
+
+  // Panelden ısıtmayı elle tetikleme. Gövdede `paths` gelirse yalnızca o
+  // yollar denenir; boşsa sitemap'in tamamı baştan taranır.
+  api.post("/prewarm", express.json({ limit: "256kb" }), (req, res) => {
+    if (prewarmProgress.active) {
+      res.status(409).json({ ok: false, reason: "active" });
+      return;
+    }
+
+    const requested = Array.isArray(req.body?.paths) ? req.body.paths : [];
+    const paths = requested.filter(
+      (value) => typeof value === "string" && value.startsWith("/"),
+    );
+
+    prewarm({
+      origin: `${req.protocol}://${req.get("host")}`,
+      paths: paths.length ? paths : undefined,
+    }).catch((error) => {
+      console.error("[prewarm] elle tetikleme başarısız", error);
+    });
+
+    res.json({ ok: true, scope: paths.length || "all" });
+  });
+
+  api.post("/clear", express.json({ limit: "8kb" }), (req, res) => {
+    errors.length = 0;
+    requests.length = 0;
+    persist();
+    res.json({ ok: true });
+  });
+
+  return api;
+}
+
+/**
+ * Dev araçlarını uygulamaya bağlar.
+ * @param {import('express').Express} app
+ */
+export function mountDevtools(app) {
+  brand = getConfig().brand;
+
+  restore();
+  patchConsole();
+  trackServerFetch();
+  watchManifest();
+  app.use(timing());
+  app.use(brand.devBasePath, router());
+}