jskelet 0.1.1

package/src/build/tasks/client.mjs

@@ -0,0 +1,268 @@
+/**
+ * Island bundle'ı: esbuild, ESM, code splitting.
+ *
+ * `client/entries/*.js` içindeki her dosya bir entry'dir. `main.js` her sayfada
+ * yüklenen ortak island bootstrap'ıdır; ek entry'ler yalnızca onları isteyen
+ * sayfalarda (`controller` → `entries: ["chart.js"]`) yüklenir.
+ *
+ * Hedef tarayıcılar `package.json` → `browserslist` yerine burada sabit: ESM +
+ * dinamik import + `IntersectionObserver` island modelinin zaten alt sınırı,
+ * daha eskisine transpile etmek çıktıyı büyütüp hiçbir ziyaretçi kazandırmıyor.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import * as esbuild from "esbuild";
+import { paths, patchManifest, pruneAssets } from "../paths.mjs";
+import * as log from "../../log.mjs";
+
+/**
+ * `@/` alias'ını proje köküne çözer — Node tarafındaki `alias-hooks.mjs` ile
+ * aynı davranış, böylece `lib/` altındaki modüller hem sunucuda hem
+ * tarayıcıda aynı import stilini kullanabilir.
+ *
+ * @param {string} root
+ * @returns {esbuild.Plugin}
+ */
+function aliasPlugin(root) {
+  return {
+    name: "jskelet-alias",
+    setup(build) {
+      build.onResolve({ filter: /^@\// }, (args) => ({
+        path: resolveWithExtension(path.join(root, args.path.slice(2))),
+      }));
+    },
+  };
+}
+
+/**
+ * Tarayıcıda `process` yoktur; sunucuyla paylaşılan modüller yine de
+ * `process.env` okur. `clientEnv` ile bildirilen anahtarlar build zamanında
+ * gömülür — Next'teki `NEXT_PUBLIC_*` ile aynı sözleşme, ama hangi anahtarın
+ * herkese açık olduğu isimden değil config'ten belli.
+ *
+ * `process.env`in tamamı tek nesne olarak define edilir: listede olmayan bir
+ * anahtar okunduğunda çökme yerine `undefined` döner.
+ *
+ * @param {string[]} keys
+ * @returns {Record<string, string>}
+ */
+function publicEnv(keys) {
+  /** @type {Record<string, string>} */
+  const env = { NODE_ENV: process.env.NODE_ENV ?? "production" };
+  for (const key of keys) {
+    const value = process.env[key];
+    if (value != null) env[key] = value;
+  }
+  return env;
+}
+
+/**
+ * @param {string} base
+ * @returns {string}
+ */
+function resolveWithExtension(base) {
+  const candidates = [
+    base,
+    `${base}.js`,
+    `${base}.mjs`,
+    `${base}.json`,
+    path.join(base, "index.js"),
+  ];
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) return candidate;
+  }
+  return base;
+}
+
+/**
+ * @param {import('../../config/index.js').ResolvedConfig} config
+ * @param {{ watch?: boolean }} [options]
+ * @returns {Promise<Record<string, string>>}
+ */
+export async function buildClient(config, { watch = false } = {}) {
+  const entryDir = path.join(config.dirs.client, "entries");
+  const outDir = path.join(paths.assets, "js");
+
+  if (!fs.existsSync(entryDir)) {
+    log.detail("entry yok, atlandı");
+    return {};
+  }
+
+  const entryPoints = fs
+    .readdirSync(entryDir)
+    .filter((file) => file.endsWith(".js"))
+    .map((file) => path.join(entryDir, file));
+
+  if (!entryPoints.length) {
+    log.detail("entry yok, atlandı");
+    return {};
+  }
+
+  fs.rmSync(outDir, { recursive: true, force: true });
+  pruneAssets(["js/"]);
+
+  const entryRoot = path
+    .relative(config.root, entryDir)
+    .split(path.sep)
+    .join("/");
+
+  /** @type {esbuild.BuildOptions} */
+  const options = {
+    entryPoints,
+    outdir: outDir,
+    absWorkingDir: config.root,
+    bundle: true,
+    splitting: true,
+    format: "esm",
+    target: ["chrome111", "edge111", "firefox111", "safari16.4"],
+    minify: true,
+    sourcemap: true,
+    metafile: true,
+    entryNames: "[name].[hash]",
+    chunkNames: "chunks/[name].[hash]",
+    legalComments: "none",
+    plugins: [aliasPlugin(config.root)],
+    define: {
+      "process.env": JSON.stringify(publicEnv(config.clientEnv)),
+    },
+  };
+
+  if (watch) {
+    const context = await esbuild.context({
+      ...options,
+      plugins: [...options.plugins, rebuildReporter(config, entryRoot)],
+    });
+    const result = await context.rebuild();
+    await context.watch();
+    writeMetafile(result.metafile);
+    const manifest = toManifest(result.metafile, config, entryRoot);
+    const entries = Object.keys(manifest).length;
+    log.detail(`${entries} ${entries === 1 ? "entry" : "entries"}`);
+    return manifest;
+  }
+
+  const result = await esbuild.build(options);
+  writeMetafile(result.metafile);
+  const manifest = toManifest(result.metafile, config, entryRoot);
+  const bytes = Object.values(result.metafile.outputs).reduce(
+    (sum, output) => sum + output.bytes,
+    0,
+  );
+  const entries = Object.keys(manifest).length;
+  log.detail(`${entries} ${entries === 1 ? "entry" : "entries"}, ${log.size(bytes)}`);
+  return manifest;
+}
+
+/**
+ * Metafile diske yazılır: dev panelindeki chunk analizi giriş/çıkış
+ * kırılımını buradan okur. Çalışma zamanı bu dosyaya bağımlı değildir.
+ *
+ * @param {esbuild.Metafile} [metafile]
+ */
+function writeMetafile(metafile) {
+  if (!metafile) return;
+  try {
+    fs.mkdirSync(paths.generated, { recursive: true });
+    fs.writeFileSync(
+      path.join(paths.generated, "metafile.json"),
+      JSON.stringify(metafile),
+    );
+  } catch {
+    // Analiz verisi en iyi çaba; build'i düşürmez.
+  }
+}
+
+/**
+ * Watch turlarını canlı olarak bildirir; ilk build zaten adım satırında görünür.
+ *
+ * @param {import('../../config/index.js').ResolvedConfig} config
+ * @param {string} entryRoot
+ * @returns {esbuild.Plugin}
+ */
+function rebuildReporter(config, entryRoot) {
+  // İlk `rebuild()` ve `watch()`'un kendi açılış turu adım satırında zaten
+  // görünüyor; canlı bildirim gerçek değişikliklerle başlar.
+  let skip = 2;
+  let started = 0;
+
+  return {
+    name: "jskelet-rebuild-log",
+    setup(build) {
+      build.onStart(() => {
+        started = Date.now();
+      });
+
+      build.onEnd((result) => {
+        if (result.metafile) {
+          writeMetafile(result.metafile);
+          // Entry adları hash'li: yeni hash manifest'e yazılmazsa HTML eski
+          // (artık var olmayan) bundle'ı ister ve island'ların hiçbiri açılmaz.
+          for (const [key, url] of Object.entries(
+            toManifest(result.metafile, config, entryRoot),
+          )) {
+            patchManifest(key, url);
+          }
+        }
+
+        if (skip > 0) {
+          skip -= 1;
+          return;
+        }
+
+        if (result.errors.length) {
+          const [first] = result.errors;
+          log.errorBox({
+            title: "Client Build Error",
+            name: "BuildError",
+            message: first.text,
+            lines: [
+              first.location
+                ? `${first.location.file}:${first.location.line}:${first.location.column}`
+                : "",
+              result.errors.length > 1
+                ? `+${result.errors.length - 1} more errors`
+                : "",
+            ].filter(Boolean),
+          });
+          return;
+        }
+
+        log.event({
+          scope: "client",
+          message: "rebuilt",
+          time: Date.now() - started,
+        });
+      });
+    },
+  };
+}
+
+/**
+ * esbuild metafile → { "main.js": "/assets/js/main.abc.js" }
+ *
+ * Dinamik import'lar da `entryPoint` taşır; yalnızca gerçek entry'ler
+ * manifest'e girer, yoksa her island ayrı bir manifest anahtarı olurdu.
+ *
+ * @param {esbuild.Metafile} metafile
+ * @param {import('../../config/index.js').ResolvedConfig} config
+ * @param {string} entryRoot
+ * @returns {Record<string, string>}
+ */
+function toManifest(metafile, config, entryRoot) {
+  /** @type {Record<string, string>} */
+  const manifest = {};
+
+  for (const [outputPath, output] of Object.entries(metafile.outputs)) {
+    if (!output.entryPoint?.startsWith(entryRoot)) continue;
+
+    const name = `${path.basename(output.entryPoint, ".js")}.js`;
+    const absolute = path.resolve(config.root, outputPath);
+    manifest[name] = `/${path
+      .relative(config.dirs.public, absolute)
+      .split(path.sep)
+      .join("/")}`;
+  }
+
+  return manifest;
+}

package/src/build/tasks/css.mjs

@@ -0,0 +1,124 @@
+/**
+ * Tailwind v4 → tek statik stylesheet.
+ *
+ * Ayrı bir "critical CSS" üretilmez. Ölçümde inline kritik CSS ilk ekranı tam
+ * kapsamadığı için sheet gelince sayfa yeniden akıyordu (bir liste sayfasında
+ * CLS 0.307) ve aynı ~27 KB her HTML yanıtında tekrar ediyordu. Sıkıştırılmış
+ * tek sheet'i render-blocking bırakmak hem daha hızlı hem CLS'siz; ikinci
+ * ziyarette zaten immutable önbellekten geliyor.
+ *
+ * Tailwind'in sınıf taraması `globals.css` içindeki `@source` direktiflerine
+ * bağlıdır. Otomatik tespit yalnızca stylesheet'in bulunduğu dizini tarar,
+ * bu yüzden şablonlarda geçen varyantlar (`data-[active=false]:…`) sessizce
+ * düşer. Yeni bir üst dizin eklediğinizde `@source` satırını da ekleyin.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { patchManifest, pruneAssets, writeAsset } from "../paths.mjs";
+import { importFromApp, tryImportFromApp } from "../resolve-peer.mjs";
+import * as log from "../../log.mjs";
+
+/**
+ * PostCSS boru hattı bir kez kurulur: Tailwind'in kendi önbelleği plugin
+ * örneğinde yaşıyor, her derlemede yeniden oluşturmak watch turlarını
+ * belirgin şekilde yavaşlatıyor.
+ *
+ * @param {string} root
+ * @returns {Promise<(inputPath: string) => Promise<string>>}
+ */
+async function createCompiler(root) {
+  const [{ default: postcss }, { default: tailwindcss }] = await Promise.all([
+    importFromApp(root, "postcss"),
+    importFromApp(root, "@tailwindcss/postcss"),
+  ]);
+
+  // lightningcss opsiyonel: yoksa Tailwind'in kendi çıktısı kullanılır,
+  // yalnızca birkaç kB daha büyük olur.
+  const lightning = await tryImportFromApp(root, "lightningcss");
+  const processor = postcss([tailwindcss()]);
+
+  return async (inputPath) => {
+    const css = fs.readFileSync(inputPath, "utf8");
+    const result = await processor.process(css, { from: inputPath, to: inputPath });
+
+    if (!lightning) return result.css;
+
+    const minified = lightning.transform({
+      filename: path.basename(inputPath),
+      code: Buffer.from(result.css),
+      minify: true,
+    });
+
+    return minified.code.toString("utf8");
+  };
+}
+
+/**
+ * @param {import('../../config/index.js').ResolvedConfig} config
+ * @param {{ watch?: boolean }} [options]
+ * @returns {Promise<Record<string, string>>}
+ */
+export async function buildCss(config, { watch = false } = {}) {
+  const input = config.dirs.styles;
+  const compile = await createCompiler(config.root);
+
+  const run = async () => {
+    const started = Date.now();
+    pruneAssets(["app."]);
+    const css = await compile(input);
+    const url = writeAsset("app.css", css);
+    return { url, bytes: Buffer.byteLength(css), elapsed: Date.now() - started };
+  };
+
+  const first = await run();
+  log.detail(log.size(first.bytes));
+
+  if (watch) {
+    watchCssSources(config, async () => {
+      try {
+        const result = await run();
+        // Yeni hash manifest'e yazılmazsa HTML silinmiş dosyayı ister.
+        patchManifest("app.css", result.url);
+        log.event({
+          scope: "css",
+          message: "rebuilt",
+          note: log.size(result.bytes),
+          time: result.elapsed,
+        });
+      } catch (error) {
+        log.event({
+          symbol: log.symbols.fail,
+          scope: "css",
+          message: "failed",
+          note: error.message,
+        });
+      }
+    });
+  }
+
+  return { "app.css": first.url };
+}
+
+/**
+ * Şablon ve island dosyaları da izlenir: Tailwind sınıfları oradan geliyor,
+ * yalnızca `styles/` izlemek yeni bir utility yazıldığında rebuild etmez.
+ *
+ * @param {import('../../config/index.js').ResolvedConfig} config
+ * @param {() => void} onChange
+ */
+function watchCssSources(config, onChange) {
+  const targets = [
+    path.dirname(config.dirs.styles),
+    config.dirs.views,
+    config.dirs.client,
+  ];
+
+  let timer = null;
+  for (const target of targets) {
+    if (!fs.existsSync(target)) continue;
+    fs.watch(target, { recursive: true }, () => {
+      clearTimeout(timer);
+      timer = setTimeout(onChange, 120);
+    });
+  }
+}

package/src/build/tasks/fonts.mjs

@@ -0,0 +1,146 @@
+/**
+ * `next/font/google` yerine self-host font dosyaları.
+ *
+ * Dosyalar `public/fonts/` altında **sabit isimlerle** durur (hash yok), çünkü
+ * `@font-face` içindeki `url()` yolları elle yazılıyor; hash'lemek her build'de
+ * stylesheet'i de değiştirmek zorunda bırakırdı.
+ *
+ * Dosya yoksa bir kez Google Fonts'tan indirilir ve **commit edilmesi
+ * beklenir**: build'in ağa bağımlı olması CI'da kırılgan. İndirme başarısız
+ * olursa uyarı basılır ve sayfa sistem font yığınına düşer — build durmaz.
+ *
+ * Yapılandırma:
+ *   fonts: [{ family: "Inter", weights: [400, 700] }]
+ * Çıktı: `public/fonts/inter-400.woff2`, manifest anahtarı aynı dosya adı.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import * as log from "../../log.mjs";
+
+/** woff2 döndürmesi için modern tarayıcı UA'sı gerekir. */
+const UA =
+  "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 " +
+  "(KHTML, like Gecko) Chrome/124.0 Safari/537.36";
+
+/**
+ * @param {string} family
+ * @returns {string}
+ */
+function toSlug(family) {
+  return family.trim().toLowerCase().replace(/\s+/g, "-");
+}
+
+/**
+ * @param {string} family
+ * @param {number[]} weights
+ * @returns {string}
+ */
+function cssUrl(family, weights) {
+  const name = family.trim().replace(/\s+/g, "+");
+  const wght = [...weights].sort((a, b) => a - b).join(";");
+  return `https://fonts.googleapis.com/css2?family=${name}:wght@${wght}&display=swap`;
+}
+
+/**
+ * @param {import('../../config/index.js').ResolvedConfig} config
+ * @returns {Promise<Record<string, string>>}
+ */
+export async function copyFonts(config) {
+  const fontsDir = config.dirs.fonts;
+  fs.mkdirSync(fontsDir, { recursive: true });
+
+  /** @type {Record<string, string>} */
+  const manifest = {};
+  let expected = 0;
+
+  for (const family of config.fonts) {
+    const slug = family.slug ?? toSlug(family.family);
+    const weights = family.weights ?? [400];
+    expected += weights.length;
+
+    /** @type {number[]} */
+    const missing = [];
+
+    for (const weight of weights) {
+      const fileName = `${slug}-${weight}.woff2`;
+      if (fs.existsSync(path.join(fontsDir, fileName))) {
+        manifest[fileName] = `/fonts/${fileName}`;
+        continue;
+      }
+      missing.push(weight);
+    }
+
+    if (!missing.length) continue;
+
+    const downloaded = await downloadFromGoogle(
+      cssUrl(family.family, missing),
+      missing,
+    );
+
+    for (const [weight, buffer] of downloaded) {
+      const fileName = `${slug}-${weight}.woff2`;
+      fs.writeFileSync(path.join(fontsDir, fileName), buffer);
+      manifest[fileName] = `/fonts/${fileName}`;
+      log.detail(`${fileName} downloaded (${log.size(buffer.byteLength)})`);
+    }
+
+    const stillMissing = missing.filter(
+      (weight) => !manifest[`${slug}-${weight}.woff2`],
+    );
+    if (stillMissing.length) {
+      log.warn(
+        `${family.family} ${stillMissing.join(", ")} indirilemedi — sistem font yığınına düşülecek.`,
+      );
+    }
+  }
+
+  log.summary(`${Object.keys(manifest).length}/${expected} weights`);
+  return manifest;
+}
+
+/**
+ * Google'ın döndürdüğü CSS'te her ağırlık ve her subset için ayrı bir
+ * `@font-face` bloğu var. Latin subset'i (`U+0000-00FF`) seçilir: diğerleri
+ * çoğu site için ölü ağırlık ve `unicode-range` olmadan hepsini indirmek
+ * font boyutunu katlar.
+ *
+ * @param {string} url
+ * @param {number[]} weights
+ * @returns {Promise<[number, Buffer][]>}
+ */
+async function downloadFromGoogle(url, weights) {
+  /** @type {[number, Buffer][]} */
+  const out = [];
+
+  let css;
+  try {
+    const response = await fetch(url, { headers: { "User-Agent": UA } });
+    if (!response.ok) throw new Error(`HTTP ${response.status}`);
+    css = await response.text();
+  } catch (error) {
+    log.warn(`Google Fonts CSS alınamadı (${error.message})`);
+    return out;
+  }
+
+  const blocks = css.split("@font-face").slice(1);
+
+  for (const weight of weights) {
+    const block = blocks.find(
+      (candidate) =>
+        candidate.includes(`font-weight: ${weight}`) &&
+        candidate.includes("U+0000-00FF"),
+    );
+    const fileUrl = block?.match(/url\((https:[^)]+\.woff2)\)/)?.[1];
+    if (!fileUrl) continue;
+
+    try {
+      const response = await fetch(fileUrl, { headers: { "User-Agent": UA } });
+      if (!response.ok) throw new Error(`HTTP ${response.status}`);
+      out.push([weight, Buffer.from(await response.arrayBuffer())]);
+    } catch (error) {
+      log.warn(`${weight} indirilemedi (${error.message})`);
+    }
+  }
+
+  return out;
+}