jskelet 0.5.5 → 0.6.0

package/src/server/port-guard.js

@@ -0,0 +1,255 @@
+/**
+ * Dinlenecek port doluysa başlamadan önce net bir hata verilir; `--murder`
+ * verilmişse o porttaki dinleyici süreçler öldürülüp bağlama denenir.
+ *
+ * Windows: `netstat` + `taskkill`. Unix: `lsof` (yoksa `ss`) + `process.kill`.
+ * Bu süreçlerin PID'lerini okumak için yerleşik bir Node API'si yok.
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import process from "node:process";
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * @param {number} ms
+ * @returns {Promise<void>}
+ */
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * `netstat -ano -p tcp` çıktısından LISTENING PID'lerini çıkarır.
+ * `3000` ile `30001` karışmasın diye porttan sonra rakam olmamalı.
+ *
+ * @param {string} stdout
+ * @param {number} port
+ * @returns {number[]}
+ */
+export function parseWindowsNetstat(stdout, port) {
+  const re = new RegExp(
+    String.raw`TCP\s+\S*:${port}(?!\d)\s+\S+\s+LISTENING\s+(\d+)`,
+    "gi",
+  );
+  /** @type {number[]} */
+  const pids = [];
+  for (const match of stdout.matchAll(re)) {
+    pids.push(Number(match[1]));
+  }
+  return pids;
+}
+
+/**
+ * `lsof -t` çıktısı: satır başına bir PID.
+ *
+ * @param {string} stdout
+ * @returns {number[]}
+ */
+export function parseLsofPids(stdout) {
+  return stdout
+    .split(/\r?\n/)
+    .map((line) => Number(line.trim()))
+    .filter((pid) => Number.isInteger(pid) && pid > 0);
+}
+
+/**
+ * `ss -H -lptn` satırlarından `pid=` değerlerini alır.
+ *
+ * @param {string} stdout
+ * @returns {number[]}
+ */
+export function parseSsPids(stdout) {
+  /** @type {number[]} */
+  const pids = [];
+  for (const match of stdout.matchAll(/pid=(\d+)/g)) {
+    pids.push(Number(match[1]));
+  }
+  return pids;
+}
+
+/**
+ * Bu süreç ve ebeveyni öldürülmesin: `--murder` yenilemede kendi CLI'sını
+ * ya da henüz dinlemeyen kendisini vurmasın.
+ *
+ * @param {number} pid
+ * @returns {boolean}
+ */
+function isSafeToKill(pid) {
+  return pid > 0 && pid !== process.pid && pid !== process.ppid;
+}
+
+/**
+ * @param {number} port
+ * @returns {Promise<number[]>}
+ */
+async function listWindows(port) {
+  const { stdout } = await execFileAsync("netstat", ["-ano", "-p", "tcp"], {
+    windowsHide: true,
+    maxBuffer: 10 * 1024 * 1024,
+  });
+  return parseWindowsNetstat(stdout, port);
+}
+
+/**
+ * @param {number} port
+ * @returns {Promise<number[]>}
+ */
+async function listUnix(port) {
+  try {
+    const { stdout } = await execFileAsync(
+      "lsof",
+      ["-nP", `-iTCP:${port}`, "-sTCP:LISTEN", "-t"],
+      { maxBuffer: 1024 * 1024 },
+    );
+    return parseLsofPids(stdout);
+  } catch (error) {
+    // lsof yoksa (exit 1 = dinleyen yok; ENOENT = komut yok) ss'e düş.
+    if (/** @type {NodeJS.ErrnoException} */ (error).code === "ENOENT") {
+      return listUnixSs(port);
+    }
+    const status = /** @type {{ status?: number | null }} */ (error).status;
+    if (status === 1) return [];
+    throw error;
+  }
+}
+
+/**
+ * @param {number} port
+ * @returns {Promise<number[]>}
+ */
+async function listUnixSs(port) {
+  try {
+    const { stdout } = await execFileAsync(
+      "ss",
+      ["-H", "-lptn", `sport = :${port}`],
+      { maxBuffer: 1024 * 1024 },
+    );
+    return parseSsPids(stdout);
+  } catch (error) {
+    if (/** @type {NodeJS.ErrnoException} */ (error).code === "ENOENT") {
+      return [];
+    }
+    const status = /** @type {{ status?: number | null }} */ (error).status;
+    if (status === 1) return [];
+    throw error;
+  }
+}
+
+/**
+ * Portu dinleyen yabancı süreçlerin PID listesi.
+ *
+ * @param {number} port
+ * @returns {Promise<number[]>}
+ */
+export async function listListeningPids(port) {
+  const raw =
+    process.platform === "win32"
+      ? await listWindows(port)
+      : await listUnix(port);
+  return [...new Set(raw)].filter(isSafeToKill);
+}
+
+/**
+ * @param {number} pid
+ * @returns {Promise<void>}
+ */
+async function killPid(pid) {
+  if (process.platform === "win32") {
+    try {
+      await execFileAsync("taskkill", ["/PID", String(pid), "/F"], {
+        windowsHide: true,
+      });
+    } catch (error) {
+      // Süreç zaten gitmiş olabilir.
+      const status = /** @type {{ status?: number | null }} */ (error).status;
+      if (status === 128 || status === 1) return;
+      throw error;
+    }
+    return;
+  }
+
+  try {
+    process.kill(pid, "SIGTERM");
+  } catch (error) {
+    if (/** @type {NodeJS.ErrnoException} */ (error).code === "ESRCH") return;
+    throw error;
+  }
+
+  await sleep(200);
+  try {
+    process.kill(pid, 0);
+    process.kill(pid, "SIGKILL");
+  } catch {
+    // ESRCH: SIGTERM yetmiş.
+  }
+}
+
+/**
+ * Porttaki dinleyicileri öldürür ve soketin boşalmasını kısa süre bekler.
+ *
+ * @param {number} port
+ * @returns {Promise<number[]>} öldürülen PID'ler
+ */
+export async function murderPort(port) {
+  const pids = await listListeningPids(port);
+  for (const pid of pids) {
+    await killPid(pid);
+  }
+
+  const deadline = Date.now() + 3000;
+  while (Date.now() < deadline) {
+    const still = await listListeningPids(port);
+    if (still.length === 0) return pids;
+    await sleep(50);
+  }
+
+  return pids;
+}
+
+/**
+ * Port doluysa ya net hata fırlatır ya da `--murder` ile temizler.
+ *
+ * Dinleyici listesi alınamazsa (araç yok / yetki) sessizce geçer; asıl bağlama
+ * `EADDRINUSE` ile yine düşer.
+ *
+ * @param {number} port
+ * @param {{ murder?: boolean }} [options]
+ * @returns {Promise<void>}
+ */
+export async function ensurePortFree(port, options = {}) {
+  const murder = options.murder === true;
+
+  /** @type {number[]} */
+  let pids;
+  try {
+    pids = await listListeningPids(port);
+  } catch {
+    return;
+  }
+
+  if (pids.length === 0) return;
+
+  if (!murder) {
+    const error = new Error(
+      `port ${port} is already in use (pid ${pids.join(", ")}). ` +
+        `Pass --murder to kill it and start, or set PORT to another value.`,
+    );
+    /** @type {NodeJS.ErrnoException} */ (error).code = "EADDRINUSE";
+    throw error;
+  }
+
+  console.error(
+    `[jskelet] port ${port} in use by pid ${pids.join(", ")} — killing (--murder)`,
+  );
+  await murderPort(port);
+
+  const still = await listListeningPids(port);
+  if (still.length > 0) {
+    const error = new Error(
+      `port ${port} still in use after --murder (pid ${still.join(", ")})`,
+    );
+    /** @type {NodeJS.ErrnoException} */ (error).code = "EADDRINUSE";
+    throw error;
+  }
+}

package/src/server/render.js

@@ -1,5 +1,6 @@
 /**
- * EJS render katmanı + HTML TTL cache (ISR ikamesi).
+ * Render katmanı + HTML TTL cache (ISR ikamesi).
+ * Varsayılan şablon yolu derlenmiş `.jsk`; EJS opsiyonel legacy peer.
  *
  * Controller sözleşmesi:
  *   async (ctx) => { view, data?, metadata?, status?, revalidate?, head?,
@@ -16,10 +17,9 @@ import path from "node:path";
 import process from "node:process";
 import fs from "node:fs";
 import { pathToFileURL } from "node:url";
-import ejs from "ejs";
 import { withHtmlCache } from "./html-cache.js";
 import { buildVaryPrefix } from "./cache-vary.js";
-import { getConfig, hook } from "../config/index.js";
+import { getConfig, hook, FRAMEWORK_ROOT } from "../config/index.js";
 import { matchPattern } from "../config/pattern.js";
 import { encodeText, negotiateEncoding } from "./middleware/compression.js";
 import { navigationHints, preconnectHints } from "./head-hints.js";
@@ -48,15 +48,16 @@ import {
   getComponentDirs,
   getViewRoots,
 } from "../compile/index.js";
+import { renderEjsFile } from "./ejs-adapter.js";
 
 const isDev = process.env.NODE_ENV === "development";
 
 /**
- * Şablonlara otomatik geçen yardımcılar ve EJS ayarları. Bileşen taraması
- * dosya sistemine dokunduğu için bir kez yapılır; config yüklenmeden
+ * Şablonlara otomatik geçen yardımcılar ve (legacy) EJS ayarları. Bileşen
+ * taraması dosya sistemine dokunduğu için bir kez yapılır; config yüklenmeden
  * hesaplanamaz, bu yüzden ilk render'da kurulur.
  *
- * @type {{ helpers: Record<string, unknown>, options: ejs.Options,
+ * @type {{ helpers: Record<string, unknown>, options: Record<string, unknown>,
  *   viewsDir: string, viewRoots: string[], layout: string,
  *   compiled: Map<string, (data: object, helpers: object) => string>,
  *   layoutRender: ((data: object, helpers: object) => string) | null
@@ -89,6 +90,9 @@ async function getEngine() {
     Icon: (props) => tags.icon(props),
     CsrfField: () => tags.csrfField(),
     PreloadImage: (props) => tags.preloadImage(props),
+    Stylesheets: (props) => tags.stylesheets(props),
+    BodyScripts: (props) => tags.bodyScripts(props),
+    JsonLd: (props) => tags.jsonLd(props),
   };
 
   // camelCase JS bileşenlerini PascalCase etiket adıyla da erişilebilir yap.
@@ -99,7 +103,21 @@ async function getEngine() {
     if (!(pascal in helpers)) helpers[pascal] = value;
   }
 
-  const { compiled, layoutRender } = await loadCompiledTemplates(config, helpers);
+  const { compiled, layoutRender: appLayoutRender } = await loadCompiledTemplates(
+    config,
+    helpers,
+  );
+
+  // Yalnızca framework varsayılan layout'una düşüldüğünde hazır modülü kullan;
+  // uygulamanın kendi layout.jsk'si derlenmemişse sessizce framework'e kayma.
+  let layoutRender = appLayoutRender;
+  if (!layoutRender) {
+    const fwLayout = path.join(FRAMEWORK_ROOT, "src", "templates", "layout.jsk");
+    if (path.resolve(config.layout) === path.resolve(fwLayout)) {
+      const fw = await import("../templates/layout.render.js");
+      if (typeof fw.render === "function") layoutRender = fw.render;
+    }
+  }
 
   engine = {
     viewsDir,
@@ -212,7 +230,7 @@ export async function renderView(view, data = {}) {
   const file =
     findEjsView(viewRoots.length ? viewRoots : [viewsDir], view) ??
     path.join(viewsDir, `${view}.ejs`);
-  return ejs.renderFile(file, { ...helpers, ...data }, options);
+  return renderEjsFile(file, { ...helpers, ...data }, options);
 }
 
 /**
@@ -277,7 +295,7 @@ export async function renderPage(page) {
     );
   }
 
-  return ejs.renderFile(layout, locals, options);
+  return renderEjsFile(layout, locals, options);
 }
 
 /**

package/src/server/status-page.js

@@ -5,11 +5,12 @@
  * "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.
+ * Production metni 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. Development'ta
+ * 5xx için ayrıntılı teşhis sayfası üretilir (aşağıya bak).
  *
- * Ezme yolları (öncelik sırasıyla):
+ * Ezme yolları (öncelik sırasıyla; development 5xx hariç):
  *   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.
@@ -23,11 +24,19 @@ import { esc } from "../views/helpers/html.js";
  * 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.
  *
+ * Development'ta 5xx yanıtları `hooks.error` ve gömülü 500 sayfasını atlar;
+ * yığın izini içeren bir teşhis sayfası döner. Production'da ayrıntı
+ * gösterilmez — sunucu içi ziyaretçiye açılmaz.
+ *
  * @param {number} status
  * @param {{ error?: unknown }} [options]
  * @returns {Promise<string>}
  */
 export async function renderStatusPage(status, options = {}) {
+  if (process.env.NODE_ENV === "development" && status >= 500) {
+    return developmentErrorPage(status, options.error);
+  }
+
   const page =
     (status === 404 ? await hook("notFound", null) : null) ??
     (await hook("error", null, { status, error: options.error }));
@@ -162,3 +171,95 @@ p { margin: 0.375rem 0 0; color: var(--muted); }
 </body>
 </html>`;
 }
+
+/**
+ * Development teşhis sayfası: mesaj + yığın izi. Yalnızca
+ * `NODE_ENV=development` iken `renderStatusPage` üzerinden çağrılır;
+ * production yolu buraya hiç girmez.
+ *
+ * @param {number} status
+ * @param {unknown} [error]
+ * @returns {string}
+ */
+function developmentErrorPage(status, error) {
+  const name =
+    error instanceof Error && error.name ? error.name : "Error";
+  const message =
+    error instanceof Error
+      ? error.message || "(no message)"
+      : error == null
+        ? "(no error object)"
+        : String(error);
+  const body = serializeError(error);
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="robots" content="noindex, nofollow">
+<title>${status} — ${esc(name)}: ${esc(message)}</title>
+<style>
+:root { color-scheme: light dark; --fg: #18181b; --muted: #71717a; --bg: #fafafa; --panel: #fff; --border: #e4e4e7; }
+@media (prefers-color-scheme: dark) {
+  :root { --fg: #f4f4f5; --muted: #a1a1aa; --bg: #09090b; --panel: #18181b; --border: #27272a; }
+}
+html, body { margin: 0; background: var(--bg); color: var(--fg); }
+body {
+  padding: 1.5rem; max-width: 56rem; margin: 0 auto;
+  font: 1rem/1.5 system-ui, -apple-system, "Segoe UI", sans-serif;
+}
+.banner {
+  display: inline-block; margin: 0 0 1rem; padding: 0.2rem 0.5rem;
+  font-size: 0.75rem; font-weight: 600; letter-spacing: 0.04em;
+  text-transform: uppercase; color: var(--muted); border: 1px solid var(--border);
+}
+.code { font-size: 2.5rem; font-weight: 600; letter-spacing: -0.02em; margin: 0; }
+h1 { font-size: 1.25rem; font-weight: 600; margin: 0.5rem 0 0; word-break: break-word; }
+pre {
+  margin: 1.25rem 0 0; padding: 1rem; overflow: auto;
+  background: var(--panel); border: 1px solid var(--border);
+  font: 0.8125rem/1.55 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  white-space: pre-wrap; word-break: break-word;
+}
+</style>
+</head>
+<body>
+<p class="banner">Development only — not shown in production</p>
+<p class="code">${status}</p>
+<h1>${esc(name)}: ${esc(message)}</h1>
+<pre>${esc(body)}</pre>
+</body>
+</html>`;
+}
+
+/**
+ * Hata nesnesini yığın izi + `cause` zinciriyle metne çevirir.
+ *
+ * @param {unknown} error
+ * @returns {string}
+ */
+function serializeError(error) {
+  if (error == null) return "(no error object)";
+
+  /** @type {string[]} */
+  const parts = [];
+  /** @type {unknown} */
+  let current = error;
+  let depth = 0;
+
+  while (current != null && depth < 6) {
+    if (depth > 0) parts.push("\nCaused by:");
+
+    if (current instanceof Error) {
+      parts.push(current.stack || `${current.name}: ${current.message}`);
+      current = "cause" in current ? current.cause : undefined;
+    } else {
+      parts.push(String(current));
+      break;
+    }
+    depth += 1;
+  }
+
+  return parts.join("\n");
+}

package/src/start.mjs

@@ -1,7 +1,22 @@
 /**
  * Prod sunucu girişi. Build çıktısı yoksa önce üretir, sonra dinlemeye başlar.
+ *
+ * `jskelet start --murder` → dolu porttaki dinleyiciyi öldürüp başlar.
+ * Port kontrolü build'den önce: doluysa pahalı üretimi hiç başlatma.
  */
-import "./build/ensure-build.mjs";
-import { startServer } from "./server/create-app.js";
+import process from "node:process";
+import { ensurePortFree } from "./server/port-guard.js";
 
-await startServer();
+const port = Number(process.env.PORT ?? 3000);
+const murder = process.argv.includes("--murder");
+
+try {
+  await ensurePortFree(port, { murder });
+  await import("./build/ensure-build.mjs");
+  const { startServer } = await import("./server/create-app.js");
+  await startServer({ murder, port });
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`${message}\n`);
+  process.exit(1);
+}

package/src/templates/layout.ejs

@@ -1,9 +1,10 @@
 <%#
-  JSkelet varsayılan layout'u.
+  JSkelet varsayılan layout'unun legacy EJS kopyası.
 
-  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.
+  Yeni uygulamalar `jskelet/layout` (.jsk) kullanır. Bu dosya yalnızca EJS
+  peer'i kurulu eski şablonlar için `jskelet/layout/ejs` üzerinden erişilir.
+  Uygulama `views/layout.jsk` veya `views/layout.ejs` oluşturduğu anda
+  framework layout'u devre dışı kalır.
 
   Kullanılabilir local'ler: metadata, headMeta, extraHead, structuredData,
   body, bodyClass, entries, styles, pathname, lang, devtools, devBasePath,
@@ -18,33 +19,12 @@
     <%# 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 %>
-    <%# Global sheet + controller `styles: [...]` sayfa sheet'leri.
-        data-jskelet-css: dev hot-swap doğru link'i bulsun diye. %>
-    <% if (hasAsset('app.css')) { %>
-    <link rel="stylesheet" href="<%= asset('app.css') %>" data-jskelet-css="app.css">
-    <% } %>
-    <% styles.forEach(function (sheet) { %>
-      <% if (hasAsset(sheet)) { %>
-    <link rel="stylesheet" href="<%= asset(sheet) %>" data-jskelet-css="<%= sheet %>">
-      <% } %>
-    <% }); %>
+    <%- stylesheets({ styles }) %>
     <%- headMeta %>
-    <% structuredData.forEach(function (item) { %>
-    <script type="application/ld+json"><%- jsonScript(item) %></script>
-    <% }); %>
+    <%- jsonLd({ items: structuredData }) %>
   </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>
-    <% } %>
+    <%- bodyScripts({ entries, devtools, devBasePath }) %>
   </body>
 </html>

package/src/templates/layout.jsk

@@ -0,0 +1,30 @@
+{#
+  JSkelet varsayılan layout'u.
+
+  Uygulama `views/layout.jsk` (veya legacy `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, styles, 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.
+
+  Stylesheets / JsonLd / BodyScripts: `.jsk` ifade dilinde fonksiyon çağrısı
+  olmadığı için asset döngüleri bu yerleşik etiketlere taşındı.
+#}
+<!DOCTYPE html>
+<html :lang="lang">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    {{{ extraHead }}}
+    <Stylesheets :styles="styles" />
+    {{{ headMeta }}}
+    <JsonLd :items="structuredData" />
+  </head>
+  <body :class="bodyClass">
+    {{{ body }}}
+    <BodyScripts :entries="entries" :devtools="devtools" :devBasePath="devBasePath" />
+  </body>
+</html>

package/src/templates/layout.render.js

@@ -0,0 +1,41 @@
+/** @generated by scripts/compile-framework-layout.mjs — do not edit */
+/**
+ * @param {Record<string, unknown>} data
+ * @param {Record<string, any>} helpers
+ * @returns {string}
+ */
+export function render(data, helpers) {
+  let s = "";
+  s += "\r\n";
+  s += "<!DOCTYPE html>";
+  s += "\r\n";
+  s += "<html" + helpers.attrs({"lang": data.lang}) + ">";
+  s += "\r\n  ";
+  s += "<head>";
+  s += "\r\n    ";
+  s += "<meta charset=\"utf-8\">";
+  s += "\r\n    ";
+  s += "<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">";
+  s += "\r\n    ";
+  s += (data.extraHead ?? "");
+  s += "\r\n    ";
+  s += (helpers.Stylesheets({ "styles": data.styles }) ?? "");
+  s += "\r\n    ";
+  s += (data.headMeta ?? "");
+  s += "\r\n    ";
+  s += (helpers.JsonLd({ "items": data.structuredData }) ?? "");
+  s += "\r\n  ";
+  s += "</head>";
+  s += "\r\n  ";
+  s += "<body" + helpers.attrs({"class": data.bodyClass}) + ">";
+  s += "\r\n    ";
+  s += (data.body ?? "");
+  s += "\r\n    ";
+  s += (helpers.BodyScripts({ "entries": data.entries, "devtools": data.devtools, "devBasePath": data.devBasePath }) ?? "");
+  s += "\r\n  ";
+  s += "</body>";
+  s += "\r\n";
+  s += "</html>";
+  s += "\r\n";
+  return s;
+}