jskelet 0.1.1

package/src/server/router.js

@@ -0,0 +1,121 @@
+/**
+ * Route modüllerini yükler ve Express'e bağlar.
+ *
+ * Dosya sistemine dayalı otomatik URL türetme **yok**: her modül kendi
+ * yollarını `app.get(...)` ile açıkça yazar. Sebep, Next.js'ten taşınırken
+ * öğrenilen bir şey — sıra önemli. `/:slug` gibi tek segmentli bir yakalayıcı
+ * `/about` rotasından önce kaydedilirse "about" bir slug sanılır. Sırayı
+ * dosya adına gizlemek yerine görünür kılmak, teşhisi kolaylaştırıyor.
+ *
+ * Sıra iki şekilde belirlenir:
+ *   1. `jskelet.config.mjs` → `routes: ["./routes/api.js", …]` (açık liste)
+ *   2. Liste yoksa `routes/` dizini alfabetik taranır. Bu durumda dosya adına
+ *      sayısal önek verin: `10-pages.js`, `50-blog.js`, `99-catch-all.js`.
+ *
+ * Modül sözleşmesi: default export ya da `register` adlı named export,
+ * `(app, api) => void | Promise<void>` imzasıyla. `api` içinde `route`,
+ * `renderView`, `renderPage` ve `notFound`/`redirect` hazır gelir, böylece
+ * route dosyaları framework'ten tek tek import yapmak zorunda kalmaz.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { pathToFileURL } from "node:url";
+import { getConfig } from "../config/index.js";
+import { renderPage, renderView, route } from "./render.js";
+import { notFound, permanentRedirect, redirect } from "../http/control-flow.js";
+
+const isDev = process.env.NODE_ENV === "development";
+
+/**
+ * @param {string} dir
+ * @param {string[]} [out]
+ * @returns {string[]}
+ */
+function discover(dir, out = []) {
+  if (!fs.existsSync(dir)) return out;
+
+  const entries = fs
+    .readdirSync(dir, { withFileTypes: true })
+    .sort((a, b) => a.name.localeCompare(b.name));
+
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+
+    if (entry.isDirectory()) {
+      discover(full, out);
+      continue;
+    }
+
+    if (!/\.(js|mjs)$/.test(entry.name)) continue;
+    if (entry.name.startsWith("_")) continue;
+
+    out.push(full);
+  }
+
+  return out;
+}
+
+/**
+ * Route dosyalarına geçilen framework yüzeyi.
+ */
+const api = {
+  route,
+  renderView,
+  renderPage,
+  notFound,
+  redirect,
+  permanentRedirect,
+};
+
+/**
+ * @param {import('express').Express} app
+ * @returns {Promise<number>} Bağlanan modül sayısı.
+ */
+export async function registerRoutes(app) {
+  const config = getConfig();
+
+  const files = config.routes
+    ? config.routes.map((entry) => path.resolve(config.root, entry))
+    : discover(config.dirs.routes);
+
+  if (!files.length) {
+    console.warn(
+      `[router] hiç route modülü bulunamadı — ${path.relative(config.root, config.dirs.routes)}/ boş mu?`,
+    );
+    return 0;
+  }
+
+  let registered = 0;
+
+  for (const file of files) {
+    /** @type {Record<string, unknown>} */
+    let module;
+
+    try {
+      module = await import(pathToFileURL(file).href);
+    } catch (error) {
+      // Dev'de eksik/bozuk bir modül tüm sunucuyu düşürmesin: uyar ve devam
+      // et. Üretimde fırlat — yarım route tablosuyla yayına çıkmak,
+      // sessizce 404 dönen sayfalar demek.
+      if (isDev) {
+        console.warn(`[router] ${path.basename(file)} yüklenemedi, atlandı`, error);
+        continue;
+      }
+      throw error;
+    }
+
+    const register = module.default ?? module.register;
+    if (typeof register !== "function") {
+      console.warn(
+        `[router] ${path.basename(file)} default ya da 'register' fonksiyonu dışa açmıyor, atlandı`,
+      );
+      continue;
+    }
+
+    await register(app, api);
+    registered += 1;
+  }
+
+  return registered;
+}

package/src/server/status-page.js

@@ -0,0 +1,164 @@
+/**
+ * Framework'ün kendi hata sayfaları (404, 500, 503…).
+ *
+ * Uygulama kendi sayfasını vermediğinde ziyaretçinin Express'in düz metin
+ * "Internal Server Error" çıktısını görmesi istenmiyor; bu yüzden framework
+ * şablonsuz, tek dosyada duran minimal bir HTML üretir.
+ *
+ * Metin bilinçli olarak yalın: yalnızca bir şeyin ters gittiğini söyler.
+ * Marka adı, ürün tanıtımı ya da hata ayrıntısı yok — hata sayfası
+ * ziyaretçiye bir şey satmaz ve sunucunun içini dışa açmaz.
+ *
+ * Ezme yolları (öncelik sırasıyla):
+ *   1. `hooks.notFound()` — yalnızca 404 için, geriye dönük uyumluluk.
+ *   2. `hooks.error({ status })` — tüm durumlar için; sayfa tanımı ya da
+ *      doğrudan HTML string döner.
+ *   3. Aşağıdaki gömülü HTML.
+ */
+import { getConfig, hook } from "../config/index.js";
+import { esc } from "../views/helpers/html.js";
+
+/**
+ * Durum koduna karşılık gelen sayfayı üretir. Hiçbir koşulda fırlatmaz:
+ * hata sayfasının kendisi patlarsa ziyaretçi boş yanıt görür, bu yüzden her
+ * başarısızlık gömülü HTML'e düşer.
+ *
+ * @param {number} status
+ * @param {{ error?: unknown }} [options]
+ * @returns {Promise<string>}
+ */
+export async function renderStatusPage(status, options = {}) {
+  const page =
+    (status === 404 ? await hook("notFound", null) : null) ??
+    (await hook("error", null, { status, error: options.error }));
+
+  if (typeof page === "string") return page;
+  if (!page) return fallbackPage(status);
+
+  try {
+    // Dinamik import: render.js bu modülü kendisi kullanıyor, statik ithal
+    // iki modül arasında döngü kurardı.
+    const { renderPage } = await import("./render.js");
+    return await renderPage({ pathname: `/${status}`, ...page });
+  } catch (error) {
+    console.error(`[render] ${status} sayfası render edilemedi`, error);
+    return fallbackPage(status);
+  }
+}
+
+/**
+ * Bir hatadan HTTP durum kodu çıkarır. Uygulama kodu `error.statusCode` ya da
+ * `error.status` ile kendi kodunu bildirebilir; tanınmayan her şey 500'dür.
+ *
+ * @param {unknown} error
+ * @returns {number}
+ */
+export function statusFromError(error) {
+  const raw =
+    error && typeof error === "object"
+      ? /** @type {{ statusCode?: unknown, status?: unknown }} */ (error).statusCode ??
+        /** @type {{ status?: unknown }} */ (error).status
+      : undefined;
+
+  const status = Number(raw);
+  return Number.isInteger(status) && status >= 400 && status <= 599 ? status : 500;
+}
+
+/**
+ * Durum başlıkları. Yalnızca framework'ün kendi ürettiği yanıtlar için;
+ * uygulamanın diline ait metinler `hooks.error()` üzerinden gelir.
+ *
+ * @type {Record<string, Record<number | "4xx" | "5xx", [string, string]>>}
+ */
+const MESSAGES = {
+  tr: {
+    400: ["Geçersiz istek", "İstek anlaşılamadı."],
+    401: ["Yetki gerekiyor", "Bu sayfayı görmek için oturum açmanız gerekiyor."],
+    403: ["Erişim yok", "Bu sayfaya erişim izniniz yok."],
+    404: ["Sayfa bulunamadı", "Aradığınız sayfa burada değil."],
+    408: ["İstek zaman aşımına uğradı", "Lütfen tekrar deneyin."],
+    410: ["Sayfa kaldırıldı", "Bu sayfa artık yayında değil."],
+    429: ["Çok fazla istek", "Kısa bir süre sonra tekrar deneyin."],
+    500: ["Bir hata oluştu", "Lütfen daha sonra tekrar deneyin."],
+    503: ["Servis kullanılamıyor", "Lütfen daha sonra tekrar deneyin."],
+    "4xx": ["İstek karşılanamadı", "Lütfen adresi kontrol edin."],
+    "5xx": ["Bir hata oluştu", "Lütfen daha sonra tekrar deneyin."],
+  },
+  en: {
+    400: ["Bad request", "The request could not be understood."],
+    401: ["Sign in required", "You need to sign in to view this page."],
+    403: ["No access", "You do not have permission to view this page."],
+    404: ["Page not found", "The page you are looking for is not here."],
+    408: ["Request timed out", "Please try again."],
+    410: ["Page removed", "This page is no longer available."],
+    429: ["Too many requests", "Please try again in a moment."],
+    500: ["Something went wrong", "Please try again later."],
+    503: ["Service unavailable", "Please try again later."],
+    "4xx": ["Request failed", "Please check the address."],
+    "5xx": ["Something went wrong", "Please try again later."],
+  },
+};
+
+/**
+ * @param {number} status
+ * @returns {{ lang: string, title: string, detail: string }}
+ */
+function statusText(status) {
+  // Config yüklenmeden de çağrılabilir (ör. loadConfig() patladıysa);
+  // hata sayfası bu yüzden getConfig()'in fırlatmasına dayanmaz.
+  let lang = "en";
+  try {
+    lang = getConfig().brand.lang ?? "en";
+  } catch {
+    /* varsayılan kalır */
+  }
+
+  const table = MESSAGES[lang.slice(0, 2).toLowerCase()] ?? MESSAGES.en;
+  const [title, detail] =
+    table[status] ?? table[status >= 500 ? "5xx" : "4xx"];
+
+  return { lang, title, detail };
+}
+
+/**
+ * Şablonsuz, varlıksız hata sayfası: tek istekte biter, build çıktısına ve
+ * uygulamanın layout'una bağlı değildir. `noindex` bilinçli — hata sayfası
+ * arama sonuçlarında görünmemeli.
+ *
+ * @param {number} status
+ * @returns {string}
+ */
+function fallbackPage(status) {
+  const { lang, title, detail } = statusText(status);
+
+  return `<!DOCTYPE html>
+<html lang="${esc(lang)}">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="robots" content="noindex, nofollow">
+<title>${status} — ${esc(title)}</title>
+<style>
+:root { color-scheme: light dark; --fg: #18181b; --muted: #71717a; --bg: #fafafa; }
+@media (prefers-color-scheme: dark) {
+  :root { --fg: #f4f4f5; --muted: #a1a1aa; --bg: #09090b; }
+}
+html, body { height: 100%; margin: 0; background: var(--bg); color: var(--fg); }
+body {
+  display: grid; place-items: center; padding: 2rem; text-align: center;
+  font: 1rem/1.6 system-ui, -apple-system, "Segoe UI", sans-serif;
+}
+.code { font-size: 3.5rem; font-weight: 600; letter-spacing: -0.02em; margin: 0; }
+h1 { font-size: 1.125rem; font-weight: 600; margin: 0.75rem 0 0; }
+p { margin: 0.375rem 0 0; color: var(--muted); }
+</style>
+</head>
+<body>
+<main>
+<p class="code">${status}</p>
+<h1>${esc(title)}</h1>
+<p>${esc(detail)}</p>
+</main>
+</body>
+</html>`;
+}

package/src/server/upstream-tracking.js

@@ -0,0 +1,51 @@
+/**
+ * Render başına upstream API hatalarını toplar.
+ *
+ * `render.js` her sayfayı bu bağlam içinde üretir; uygulamanın HTTP istemcisi
+ * başarısız bir upstream yanıtında `reportUpstreamFailure()` çağırır. Böylece
+ * HTML önbelleği "bu çıktı eksik veriyle üretildi" bilgisine sahip olur ve
+ * bozuk sayfayı saklamaz.
+ *
+ * Bağımlılık yönü bilinçli olarak tersine çevrilmiş: framework veri katmanını
+ * tanımaz, veri katmanı framework'e haber verir. Hiç çağıran olmazsa maliyet
+ * boş bir dizidir.
+ *
+ * Kullanım (uygulamanın `lib/api/client.js` içinde):
+ *
+ *   import { reportUpstreamFailure } from "jskelet/server";
+ *
+ *   if (!response.ok) {
+ *     reportUpstreamFailure({ status: response.status, path: url });
+ *   }
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+
+/**
+ * @typedef {{ status: number, path: string }} UpstreamFailure
+ *   `status: 0` ağ hatası anlamına gelir (yanıt hiç gelmedi).
+ */
+
+/** @type {AsyncLocalStorage<{ failures: UpstreamFailure[] }>} */
+const storage = new AsyncLocalStorage();
+
+/**
+ * @param {UpstreamFailure} failure
+ * @returns {void}
+ */
+export function reportUpstreamFailure(failure) {
+  storage.getStore()?.failures.push(failure);
+}
+
+/**
+ * @param {() => T} run
+ * @returns {T}
+ * @template T
+ */
+export function withUpstreamTracking(run) {
+  return storage.run({ failures: [] }, run);
+}
+
+/** @returns {UpstreamFailure[]} */
+export function getUpstreamFailures() {
+  return storage.getStore()?.failures ?? [];
+}

package/src/start.mjs

@@ -0,0 +1,7 @@
+/**
+ * Prod sunucu girişi. Build çıktısı yoksa önce üretir, sonra dinlemeye başlar.
+ */
+import "./build/ensure-build.mjs";
+import { startServer } from "./server/create-app.js";
+
+await startServer();

package/src/templates/layout.ejs

@@ -0,0 +1,44 @@
+<%#
+  JSkelet varsayılan layout'u.
+
+  Uygulama `views/layout.ejs` oluşturduğu anda bu dosya devre dışı kalır;
+  amacı yeni bir projenin tek route ile çalışabilmesi. Kopyalayıp başlangıç
+  noktası olarak kullanın.
+
+  Kullanılabilir local'ler: metadata, headMeta, extraHead, structuredData,
+  body, bodyClass, entries, pathname, lang, devtools, devBasePath, asset,
+  hasAsset + tüm html/tag helper'ları ve views/components/** export'ları.
+  `hooks.layoutContext()` döndürdüğü her alan da buraya eklenir.
+-%>
+<!DOCTYPE html>
+<html lang="<%= lang %>">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <%# Kaynak ipuçları en başta: preconnect ve LCP preload'ını geciktirmek
+        doğrudan LCP'ye yazılır. Sayfaya özel head buradan gelir. %>
+    <%- extraHead %>
+    <%# Tek, render-blocking stylesheet — build çalışmadıysa hiç basılmaz. %>
+    <% if (hasAsset('app.css')) { %>
+    <link rel="stylesheet" href="<%= asset('app.css') %>">
+    <% } %>
+    <%- headMeta %>
+    <% structuredData.forEach(function (item) { %>
+    <script type="application/ld+json"><%- jsonScript(item) %></script>
+    <% }); %>
+  </head>
+  <body class="<%= bodyClass %>">
+    <%- body %>
+    <%# Island runtime; entry yoksa sayfa yine tam çalışır (sadece JS'siz). %>
+    <% if (hasAsset('main.js')) { %>
+    <script type="module" src="<%= asset('main.js') %>"></script>
+    <% } %>
+    <% entries.forEach(function (entry) { %>
+    <script type="module" src="<%= asset(entry) %>"></script>
+    <% }); %>
+    <%# Dev overlay: prod build'de yok, yalnızca `jskelet dev` sunucusundan. %>
+    <% if (devtools) { %>
+    <script type="module" src="<%= devBasePath %>/overlay.js"></script>
+    <% } %>
+  </body>
+</html>

package/src/version.mjs

@@ -0,0 +1,17 @@
+/**
+ * Framework sürümü. `package.json`'dan okunur; paket bir kez yayınlandıktan
+ * sonra sürümü iki yerde tutmak kaçınılmaz olarak birbirinden ayrılıyor.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { FRAMEWORK_ROOT } from "./config/index.js";
+
+/** @type {string} */
+export const FRAMEWORK_VERSION = (() => {
+  try {
+    const file = path.join(FRAMEWORK_ROOT, "package.json");
+    return JSON.parse(fs.readFileSync(file, "utf8")).version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+})();

package/src/views/components/loader.js

@@ -0,0 +1,85 @@
+/**
+ * `views/components/**` altındaki tüm modülleri yükler ve named export'larını
+ * tek bir nesnede birleştirir. Bu nesne EJS şablonlarına local olarak geçer,
+ * böylece `<%- card({ … }) %>` gibi çağrılar import gerektirmeden çalışır.
+ *
+ * Elle bakılan bir barrel dosyası yok: yeni bir bileşen eklemek için dosyayı
+ * oluşturmak yeterli.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+/** Bileşen olmayan altyapı dosyaları. */
+const SKIP_FILES = new Set(["loader.js", "index.js"]);
+
+/**
+ * Barrel önce, en düşük öncelikle yüklenir: tek amacı `lib/` yeniden
+ * ihraçlarını şablon local'i yapmak. Bileşenlerin kendi dosyaları sonradan
+ * gelip sessizce üzerine yazar.
+ */
+const BARREL = "index.js";
+
+/**
+ * @param {string} dir
+ * @param {string[]} [out]
+ * @returns {string[]}
+ */
+function collect(dir, out = []) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+
+    if (entry.isDirectory()) {
+      collect(full, out);
+      continue;
+    }
+
+    if (!entry.name.endsWith(".js")) continue;
+    if (SKIP_FILES.has(entry.name)) continue;
+
+    out.push(full);
+  }
+
+  return out;
+}
+
+/**
+ * @param {string} dir `views/components` dizininin mutlak yolu. Dizin yoksa
+ *   boş nesne döner: bileşen kullanmayan bir proje de çalışmalı.
+ * @returns {Promise<Record<string, unknown>>}
+ */
+export async function loadComponents(dir) {
+  if (!dir || !fs.existsSync(dir)) return {};
+
+  /** @type {Record<string, unknown>} */
+  const components = {};
+  /** @type {Map<string, string>} */
+  const origin = new Map();
+
+  const barrel = path.join(dir, BARREL);
+  const files = [
+    ...(fs.existsSync(barrel) ? [barrel] : []),
+    ...collect(dir).sort(),
+  ];
+
+  for (const file of files) {
+    const relative = path.relative(dir, file).split(path.sep).join("/");
+    const module = await import(pathToFileURL(file).href);
+
+    for (const [name, value] of Object.entries(module)) {
+      if (name === "default") continue;
+
+      const previous = origin.get(name);
+      if (previous && previous !== BARREL && previous !== relative) {
+        console.warn(
+          `[components] '${name}' iki kez tanımlı: ${previous} ve ${relative} — ikincisi kazanıyor.`,
+        );
+      }
+
+      components[name] = value;
+      origin.set(name, relative);
+    }
+  }
+
+  return components;
+}

package/src/views/helpers/html.js

@@ -0,0 +1,102 @@
+/** HTML üretimi için ortak yardımcılar (React'in kaçış davranışının karşılığı). */
+import { twMerge } from "tailwind-merge";
+
+const ESCAPE_MAP = {
+  "&": "&",
+  "<": "&lt;",
+  ">": "&gt;",
+  '"': "&quot;",
+  "'": "&#39;",
+};
+
+/**
+ * Metin içeriği ve attribute değerleri için kaçış.
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function esc(value) {
+  if (value == null || value === false) return "";
+  return String(value).replace(/[&<>"']/g, (char) => ESCAPE_MAP[char]);
+}
+
+/**
+ * `<script type="application/ld+json">` gövdesi için güvenli JSON.
+ * `</script`, `<!--` ve U+2028/2029 kaçırılır.
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function jsonScript(value) {
+  return JSON.stringify(value)
+    .replace(/</g, "\\u003c")
+    .replace(/>/g, "\\u003e")
+    .replace(/&/g, "\\u0026")
+    .replace(/\u2028/g, "\\u2028")
+    .replace(/\u2029/g, "\\u2029");
+}
+
+/**
+ * Attribute nesnesini string'e çevirir. `false`/`null`/`undefined` atlanır,
+ * `true` boolean attribute olarak yazılır.
+ * @param {Record<string, unknown>} attrs
+ * @returns {string}
+ */
+export function attrs(attrs) {
+  const parts = [];
+  for (const [key, value] of Object.entries(attrs)) {
+    if (value == null || value === false) continue;
+    if (value === true) {
+      parts.push(key);
+      continue;
+    }
+    parts.push(`${key}="${esc(value)}"`);
+  }
+  return parts.length ? ` ${parts.join(" ")}` : "";
+}
+
+/**
+ * `clsx` karşılığı — koşullu sınıf birleştirme, çakışma çözümü yok.
+ * @param {...unknown} inputs
+ * @returns {string}
+ */
+export function cx(...inputs) {
+  const out = [];
+
+  for (const input of inputs) {
+    if (!input) continue;
+
+    if (typeof input === "string" || typeof input === "number") {
+      out.push(String(input));
+      continue;
+    }
+
+    if (Array.isArray(input)) {
+      const nested = cx(...input);
+      if (nested) out.push(nested);
+      continue;
+    }
+
+    if (typeof input === "object") {
+      for (const [key, active] of Object.entries(input)) {
+        if (active) out.push(key);
+      }
+    }
+  }
+
+  return out.join(" ");
+}
+
+/**
+ * `lib/ui/cn.js` ile aynı davranış: birleştir, sonra Tailwind çakışmalarını çöz.
+ *
+ * `tailwind-merge` çalışma zamanı bağımlılığı olarak korunur çünkü sınıf
+ * hesabı **yalnızca sunucuda** yapılır — client bundle'a hiç girmez, dolayısıyla
+ * sayfa ağırlığına etkisi yoktur. Elle yazılmış bir grup tablosu ise
+ * `border-2` + `border-transparent` gibi genişlik/renk çiftlerini birbirine
+ * karıştırıp sınıf düşürdüğü için görsel regresyon üretiyordu.
+ *
+ * @param {...unknown} inputs
+ * @returns {string}
+ */
+export function cn(...inputs) {
+  return twMerge(cx(...inputs));
+}