jskelet 0.1.1

package/AGENTS.md

@@ -0,0 +1,127 @@
+# AGENTS.md
+
+Bu depo **JSkelet** framework'ünün kaynağıdır: Express 5 + EJS sunucu render,
+vanilla JS island'lar, Tailwind v4 ve süreç belleğinde yaşayan HTML TTL cache.
+React ve TypeScript yok; düz JavaScript + JSDoc.
+
+Bir JSkelet **uygulamasında** çalışıyorsan (framework'ün kendisinde değil), aynı
+kuralların uygulama tarafı karşılıkları için [docs/](./docs/README.md) yeterli;
+özellikle 03, 05 ve 07.
+
+## Değişiklik yapmadan önce
+
+Framework'ün davranışını değiştiren bir iş alıyorsan ilgili belgeyi oku. Bu
+dosyalar kararların **gerekçelerini** taşıyor ve çoğu "iyileştirme" fikri orada
+zaten tartışılmış:
+
+| Dokunacağın yer | Önce oku |
+| --- | --- |
+| `src/server/render.js`, şablonlar | [04-render-ve-sablonlar.md](./docs/04-render-ve-sablonlar.md) |
+| `src/server/html-cache.js`, `route()` | [06-cache.md](./docs/06-cache.md) |
+| `src/server/create-app.js`, middleware | [02-mimari.md](./docs/02-mimari.md) |
+| `src/client/**` | [05-islands.md](./docs/05-islands.md) |
+| `src/build/**` | [08-build.md](./docs/08-build.md) |
+| `src/config/**` | [07-yapilandirma.md](./docs/07-yapilandirma.md) |
+| `src/dev-server.mjs`, `src/server/dev/**` | [09-dev-araclari.md](./docs/09-dev-araclari.md) |
+
+## Doğrulama
+
+**Lint yeterli, tam build zorunlu değil.**
+
+```bash
+npm run lint
+npm test     # desen derleyicisi ve HTML cache için birim testler
+```
+
+Davranış değiştiren bir iş yaptıysan örneklerden biriyle uçtan uca dene:
+
+```bash
+npm --prefix examples/blog install     # ilk seferde
+npm --prefix examples/blog run build
+npm --prefix examples/blog run start   # ayrı terminalde
+node examples/blog/smoke.mjs
+```
+
+`examples/blog` bilinçli olarak framework'ün her yüzeyini kullanır (dinamik
+route, tüm config bölümleri, fragment, form, prewarm, RSS/sitemap, dört island).
+Bir şeyi bozduysan smoke testi genelde yakalar.
+
+## Mimari kurallar
+
+**Framework domain bilgisi taşımaz.** `src/` altında hiçbir yerde uygulamaya
+özel URL, marka adı, metin ya da veri şekli olmaz. Uygulamaya ait mantık
+`hooks` üzerinden gelir (`metadata`, `layoutContext`, `notFound`,
+`prewarmPaths`), görünen adlar `brand` üzerinden.
+
+**Yol hesabı tek yerde.** Hiçbir modül `../..` sayarak dizin bulmaz;
+`getConfig().dirs` kullanılır. Framework `node_modules/` içine girdiğinde
+göreli yol sayan her satır bozulur.
+
+**Yapılandırma hatası siteyi düşürmez.** Bozuk bir `jskelet.config.mjs`, hata
+veren bir `headers()` ya da fırlatan bir hook uyarı basar ve varsayılana döner.
+
+**Build çıktısı olmadan da ayağa kalkar.** `asset()` manifest yoksa hash'siz
+yola döner, `hasAsset()` false olur ve layout etiketi basmaz. `jskelet build`
+unutulduğunda hata değil, stilsiz ama çalışan bir sayfa görülür.
+
+**Opsiyonel bağımlılıklar sessizce atlanır.** `sharp`, `postcss`,
+`@phosphor-icons/core` yoksa ilgili build adımı çalışmaz. Peer bağımlılıklar
+**uygulamanın** `node_modules`'ünden çözülmeli: `src/build/resolve-peer.mjs`
+içindeki `importFromApp` / `tryImportFromApp` kullanılır, doğrudan `import
+"postcss"` yazılmaz.
+
+**Middleware sırası sözleşmedir.** `src/server/create-app.js` başındaki
+numaralı yorum sırayı ve her konumun gerekçesini anlatır. Sıra değiştirmek
+sessiz bozulmalara yol açar; değiştiriyorsan yorumu da güncelle.
+
+**Cache'lenen HTML herkese aynı gider.** Kişiye özel hiçbir şey `route()` ile
+render edilen sayfaya girmez. Tema gibi kararlar client'ta, kullanıcıya özel
+parçalar ayrı ve `no-store` işaretli fragment uçlarında.
+
+## Kod stili
+
+- **JSDoc zorunlu**: dışa açık her fonksiyonda parametre ve dönüş tipleri.
+- **Yorumlar Türkçe** ve *neden*i anlatır. Kodun ne yaptığını tekrar eden yorum
+  yazma; bir kararın gerekçesini, bir takası ya da bir tuzağı yaz.
+- Sunucu ve build tarafı `node:` önekli çekirdek modülleri kullanır.
+- `src/client/**` tarayıcıda çalışır: Node API'si, `process` (build sırasında
+  değiştirilen `clientEnv` dışında) ve senkron ağ yok.
+- Yeni bir dışa açık yüzey ekliyorsan `package.json` → `exports` ve
+  `src/index.js` / `src/client/index.js` barrel'larını güncelle; belgelerde
+  yalnızca `exports` haritasındaki belirteçler kullanılır (`jskelet`,
+  `jskelet/client`, `jskelet/html`, `jskelet/tags`).
+
+## EJS tuzakları
+
+- `include` **async**'tir: `await include('partials/x')` yalnızca şablonun kendi
+  gövdesinde çalışır. Bir `forEach` callback'i içinde derleme hatası verir —
+  `for` döngüsü kullan.
+- `views/components/**` altındaki her named export otomatik olarak şablon local'i
+  olur; import gerekmez. Bileşenler EJS değil, HTML string döndüren
+  fonksiyonlardır.
+- Şablona giden her kullanıcı verisi `<%= %>` ile ya da `esc()` üzerinden
+  geçmeli; `<%- %>` yalnızca güvenli bildiğin HTML için.
+
+## Tailwind
+
+Sınıf taraması `styles/globals.css` içindeki `@source` direktiflerine bağlıdır
+ve otomatik tespit `source(none)` ile kapatılmıştır. Sınıf kullanmaya başladığın
+yeni bir dizin varsa oraya bir `@source` satırı eklemek gerekir; yoksa sınıflar
+sessizce çıktıdan düşer.
+
+## Örnekleri güncel tut
+
+Framework'ün genel yüzeyini değiştirdiysen (`route()` imzası, hook adları,
+config alanları, client API'si) `examples/minimal`, `examples/blog` ve
+`examples/marketing`'i de güncelle. Örnekler belgelerdeki kod parçalarının kaynağı; kaymaları en hızlı
+fark edilen yer orası.
+
+## Windows notları
+
+Bu depo Windows üzerinde geliştiriliyor ve iki tuzak tekrar tekrar çıkıyor:
+
+- `--import` argümanı modül belirteci bekler. `H:\...` gibi mutlak bir yol `h:`
+  şemalı URL sanılıp reddedilir; `pathToFileURL(...).href` kullan.
+- `fs.watch` bir dosya yazıldığında komşuları için de olay üretebiliyor. Dev
+  sunucusu bu yüzden olayları `mtime` karşılaştırmasıyla eler; watcher mantığını
+  değiştirirken bu elemeyi kaldırma.

package/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+While the project is on `0.x`, minor releases may contain breaking changes; each
+one is listed under a **Breaking** heading.
+
+## [Unreleased]
+
+### Added
+
+- English `README`, plus `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md`,
+  a `LICENSE` file, issue and pull request templates, and a CI workflow.
+
+## [0.1.0]
+
+Initial release.
+
+### Added
+
+- Express 5 server with EJS rendering: `createApp()`, `startServer()`,
+  `route()`, `renderPage()`, `renderView()`, `renderNotFound()`.
+- In-process HTML TTL cache with stale-while-revalidate, plus prewarm at boot.
+- Island runtime with visibility, eager and idle hydration strategies, a small
+  cross-island store, and DOM helpers.
+- Configuration through `jskelet.config.mjs`: `brand`, `paths`, `navigation`,
+  `icons`, `fonts`, `clientEnv`, `redirects()`, `rewrites()`, `headers()`,
+  `cache()` and `hooks`.
+- Build pipeline: fonts, SVG sprite from used icons, Tailwind v4 CSS, esbuild
+  bundles with code splitting, webp variants, hashed output and brotli/gzip
+  precompression.
+- Dev server with watch build, CSS hot-swap, automatic restart and a devtools
+  overlay (requests, errors, upstream calls, cache dump, Web Vitals).
+- CLI: `jskelet dev`, `jskelet build`, `jskelet start`, `jskelet init`.
+- Documentation under `docs/` and three examples: `minimal`, `blog`,
+  `marketing`.
+
+[Unreleased]: https://github.com/ayberkenis/jskelet/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/ayberkenis/jskelet/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ayberk Enis and JSkelet contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,342 @@
+# JSkelet
+
+**A framework that feels like no framework** — for sites where SEO and speed are
+the product.
+
+JSkelet renders **complete HTML** on an Express 5 server with EJS, adds
+interactivity through vanilla JS **islands**, compiles CSS into a **single
+Tailwind v4 stylesheet**, and instead of ISR keeps an in-process **HTML TTL
+cache** with stale-while-revalidate. No React, no TypeScript — plain JavaScript
+with JSDoc.
+
+[![Node.js 22+](https://img.shields.io/badge/node-%3E%3D22-brightgreen)](https://nodejs.org)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
+
+- [Quick start](#quick-start)
+- [What it looks like](#what-it-looks-like)
+- [How it works](#how-it-works)
+- [What you get](#what-you-get)
+- [What it deliberately does not do](#what-it-deliberately-does-not-do)
+- [Project layout](#project-layout)
+- [Configuration](#configuration)
+- [CLI](#cli)
+- [Public API](#public-api)
+- [Deployment](#deployment)
+- [Documentation](#documentation)
+- [Examples](#examples)
+- [Contributing](#contributing)
+
+## Quick start
+
+```bash
+mkdir my-site && cd my-site
+npm init -y && npm pkg set type=module
+npm install jskelet
+npm install -D postcss @tailwindcss/postcss tailwindcss lightningcss
+npx jskelet init
+npx jskelet dev
+```
+
+`http://localhost:3000` serves a page that was rendered on the server, stored in
+the HTML cache, and whose island hydrates when it scrolls into view.
+
+Requirements:
+
+- **Node.js 22 or newer.**
+- Everything else is an **optional peer dependency**: `postcss`,
+  `@tailwindcss/postcss`, `tailwindcss` and `lightningcss` for styles,
+  `@phosphor-icons/core` for the icon sprite, `sharp` for image optimization. If
+  a package is missing, the matching build step is skipped with a warning and
+  the site keeps working.
+
+## What it looks like
+
+A route module receives the app and returns page descriptions. Nothing is
+inferred from the file system — URLs are written out.
+
+```js
+// routes/10-pages.mjs
+import { getPost, getPosts } from "../lib/posts.js";
+
+export default function register(app, { route, notFound }) {
+  app.get("/", route(
+    async () => ({
+      view: "pages/home",
+      metadata: { title: "Home", canonical: "/" },
+      data: { posts: getPosts() },
+    }),
+    { revalidate: 60 }, // keep this HTML for 60 seconds
+  ));
+
+  app.get("/blog/:slug", route(async ({ params }) => {
+    const post = getPost(params.slug);
+    if (!post) notFound();
+    return { view: "pages/blog-post", data: { post } };
+  }));
+}
+```
+
+Templates are EJS. Every named export under `views/components/**` becomes a
+template local automatically, so components need no imports — they are plain
+functions returning HTML strings.
+
+```html
+<!-- views/pages/home.ejs -->
+<section class="wrapper">
+  <h1 class="text-3xl font-bold">Latest posts</h1>
+  <% posts.forEach(function (post) { %>
+  <%- postCard({ post }) %>
+  <% }); %>
+
+  <!-- downloaded and wired up once visible -->
+  <div data-island="newsletter"></div>
+</section>
+```
+
+Islands are modules with a default export that receives their root element.
+
+```js
+// client/islands/newsletter.js
+export default function newsletter(el) {
+  const form = el.querySelector("form");
+  form.addEventListener("submit", async (event) => {
+    event.preventDefault();
+    await fetch("/api/subscribe", { method: "POST", body: new FormData(form) });
+  });
+}
+```
+
+## How it works
+
+A request goes through a fixed middleware order that is documented in the
+numbered comment at the top of `src/server/create-app.js`; changing that order
+causes silent breakage.
+
+1. **Config** (`jskelet.config.mjs`) is loaded once and exposed through
+   `getConfig()`. `redirects()`, `rewrites()`, `headers()` and `cache()` follow
+   the subset of `next.config` syntax people actually use. A broken config, a
+   throwing `headers()` or a failing hook logs a warning and falls back to
+   defaults — it never takes the site down.
+2. **Static assets** are served from `public/` with hashed filenames and
+   long-lived cache headers, and precompressed `.br` / `.gz` variants are picked
+   automatically.
+3. **`route()`** wraps your controller. It builds a cache key, checks the HTML
+   TTL cache, and on a miss renders the page. When a cached entry is stale it is
+   returned immediately while revalidation runs in the background.
+4. **Render** composes metadata, layout context and your view into one HTML
+   document. Hooks (`metadata`, `layoutContext`, `notFound`, `prewarmPaths`)
+   are where application knowledge lives — the framework itself carries none.
+5. **Hydration** happens in the browser: the island registry finds
+   `data-island` elements and dynamically imports the matching chunk when it
+   becomes visible (or eagerly / on idle, if asked).
+
+Because cached HTML is shared by every visitor, nothing personalized may appear
+in a page rendered through `route()`. Per-user markup belongs in separate
+fragment endpoints marked `no-store`, and decisions like theme are made on the
+client.
+
+## What you get
+
+- **Full HTML from the server.** First paint does not wait for JavaScript, and
+  crawlers see the complete document because content is never assembled in the
+  browser.
+- **Islands.** Interactivity attaches to elements carrying `data-island`.
+  Modules are dynamically imported on visibility by default;
+  `data-island-eager` and `data-island-idle` pick a different strategy. A small
+  store handles sharing state between islands.
+- **HTML TTL cache.** Per-route `revalidate`, stale-while-revalidate on expiry,
+  and prewarm that fills the cache at boot so the first visitor is not the one
+  who pays for rendering.
+- **Fast navigation.** The `navigation` config section emits Speculation Rules
+  to prefetch or prerender links and enables view transitions — without adding
+  any client runtime.
+- **Familiar configuration.** `redirects()`, `rewrites()`, `headers()`,
+  `cache()`, plus `brand`, `images`, `security` and `hooks` sections.
+- **A real build pipeline.** Fonts, an SVG sprite generated from the icons you
+  actually use, Tailwind v4 CSS, esbuild bundles with code splitting, webp
+  variants, hashed output and brotli/gzip precompression.
+- **Developer experience.** One command, one terminal: watch build plus server,
+  CSS hot-swap, automatic restart, and a devtools overlay on Alt+D showing
+  requests, errors, upstream calls, a cache dump and Web Vitals.
+- **Graceful degradation.** Without build output `asset()` returns the unhashed
+  path and `hasAsset()` returns false, so forgetting `jskelet build` yields an
+  unstyled but working page instead of a crash.
+
+## What it deliberately does not do
+
+- **No file-system routing.** Paths are written explicitly in route modules.
+- **No streaming or RSC.** A page is flushed as one document; slow sections are
+  fetched from separate fragment endpoints.
+- **No targeted cache invalidation.** There is TTL and there is "clear
+  everything".
+- **No global state management** beyond the small island store.
+
+If you are building an app-shaped interface behind a login — a dashboard, an
+editor, an admin panel — page HTML cannot be cached and this framework is the
+wrong tool. The reasoning and a feature-by-feature comparison with Next.js live
+in [docs/11-tasima.md](./docs/11-tasima.md).
+
+## Project layout
+
+`jskelet init` scaffolds this shape, and every directory is configurable through
+the `paths` section of the config:
+
+```
+my-site/
+├── jskelet.config.mjs   # config, hooks, headers, redirects
+├── routes/              # loaded in filename order (10-, 20-, …)
+├── views/
+│   ├── pages/           # EJS pages
+│   ├── partials/        # header, footer, …
+│   └── components/      # named exports become template locals
+├── client/
+│   ├── entries/main.js  # registers islands, calls start()
+│   └── islands/         # one module per island
+├── styles/globals.css   # Tailwind entry with @source directives
+├── lib/                 # your data access
+└── public/              # build output plus static files
+```
+
+Two things bite newcomers:
+
+- **Tailwind class scanning follows `@source` directives** in
+  `styles/globals.css`, because automatic detection is turned off with
+  `source(none)`. A new directory that uses classes needs an `@source` line, or
+  its classes silently vanish from the stylesheet.
+- **`include` in EJS is async.** `await include('partials/x')` only works in a
+  template's own body; inside a `forEach` callback it is a compile error, so use
+  a `for` loop there.
+
+## Configuration
+
+`jskelet.config.mjs` exports a single object. Every section is optional.
+
+```js
+export default {
+  brand: { name: "My Site", lang: "en" },
+  icons: { scan: ["views", "client"] },
+
+  // Speculation Rules plus @view-transition, with no client runtime.
+  navigation: { prefetch: "moderate", prerender: "conservative", viewTransition: true },
+
+  async redirects() {
+    return [{ source: "/old", destination: "/new", permanent: true }];
+  },
+
+  async headers() {
+    return [{ source: "/:path*", headers: [{ key: "X-Frame-Options", value: "DENY" }] }];
+  },
+
+  async cache() {
+    return {
+      html: { "/": 3600, "/pricing": 3600 },
+      prewarm: { enabled: true, max: 50, concurrency: 4 },
+    };
+  },
+
+  hooks: {
+    metadata: () => ({ titleTemplate: "%s · My Site", siteUrl: "https://example.com" }),
+    layoutContext: ({ pathname }) => ({ pathname, year: new Date().getFullYear() }),
+    prewarmPaths: async () => ["/", "/pricing"],
+  },
+};
+```
+
+The complete reference — every field, default and failure mode — is
+[docs/07-yapilandirma.md](./docs/07-yapilandirma.md).
+
+## CLI
+
+| Command | What it does |
+| --- | --- |
+| `jskelet dev` | Watch build plus server, live reload, devtools overlay |
+| `jskelet build` | Production build: fonts → sprite → CSS → JS → images → manifest → precompress |
+| `jskelet start` | Production server; builds first if output is missing |
+| `jskelet init` | Scaffolds a minimal skeleton into the current directory |
+
+## Public API
+
+Only the specifiers in the `exports` map are supported:
+
+| Specifier | Contents |
+| --- | --- |
+| `jskelet` | `route`, `createApp`, `startServer`, `notFound`, `redirect`, `cache`, `asset`, `getConfig`, HTML cache and prewarm helpers |
+| `jskelet/client` | `register`, `registerAll`, `hydrate`, `start`, `createStore`, DOM helpers |
+| `jskelet/html` | `attrs`, `cn`, `cx`, `esc`, `jsonScript` |
+| `jskelet/tags` | `icon`, `image`, `link`, `preloadImage` |
+
+Anything reachable by a deeper path is internal and may change without notice.
+
+## Deployment
+
+The server is a plain Express 5 app, so anything that can run a Node process
+works: a `Dockerfile` (see `examples/marketing/Dockerfile`), a systemd unit, or
+a PaaS. Run `jskelet build` at image build time, put a reverse proxy in front
+for TLS, and expose a health endpoint (the default dev gate bypass list already
+includes `/api/healthcheck`, so a route there is reachable in every mode).
+Details, including cache sizing
+behind multiple instances, are in [docs/10-dagitim.md](./docs/10-dagitim.md).
+
+## Documentation
+
+The full reference lives under [docs/](./docs/README.md). It is currently
+written in Turkish; translations are a welcome contribution.
+
+| Document | Topic |
+| --- | --- |
+| [01-baslangic](./docs/01-baslangic.md) | Installation, first route, first island, directory layout, CLI |
+| [02-mimari](./docs/02-mimari.md) | Decisions and their reasoning, middleware order |
+| [03-routing](./docs/03-routing.md) | Route modules, controller contract, load order |
+| [04-render-ve-sablonlar](./docs/04-render-ve-sablonlar.md) | Layout, components, helpers, metadata |
+| [05-islands](./docs/05-islands.md) | Island contract, hydration, store, DOM helpers |
+| [06-cache](./docs/06-cache.md) | TTL, stale-while-revalidate, keys, prewarm |
+| [07-yapilandirma](./docs/07-yapilandirma.md) | Complete `jskelet.config.mjs` reference |
+| [08-build](./docs/08-build.md) | Build pipeline, manifest, Tailwind `@source`, sprite |
+| [09-dev-araclari](./docs/09-dev-araclari.md) | Dev workflow, overlay, report page, dev gate |
+| [10-dagitim](./docs/10-dagitim.md) | Production, Docker, reverse proxy, health checks |
+| [11-tasima](./docs/11-tasima.md) | Migrating from Next.js: mapping table and plan |
+
+If you work with AI agents, [AGENTS.md](./AGENTS.md) summarizes the rules that
+apply to this repository.
+
+## Examples
+
+```bash
+npm --prefix examples/minimal   install && npm --prefix examples/minimal   run dev
+npm --prefix examples/blog      install && npm --prefix examples/blog      run dev
+npm --prefix examples/marketing install && npm --prefix examples/marketing run dev
+```
+
+- **`examples/minimal`** — two routes, one component, one island. The smallest
+  thing that runs.
+- **`examples/blog`** — dynamic routes, tag pages, every config section,
+  fragment-loaded tabs, a form, prewarm, RSS and sitemap, four islands. It
+  intentionally touches every surface of the framework.
+- **`examples/marketing`** — the framework's own marketing site: comparison
+  table, changelog and download pages, long TTLs, prewarm covering every page.
+  The byte counts on the page are measured from that site's own build output, the
+  version details are read from the installed package, and the latency numbers
+  are measured in the browser; there are no invented benchmarks. It is also
+  bilingual — English at the root, Turkish under `/tr` — which shows how to build
+  a multi-language site on a framework that ships no i18n of its own.
+
+With a server running, `node smoke.mjs` inside an example verifies that its
+endpoints respond as expected.
+
+## Contributing
+
+Bug reports, documentation fixes and pull requests are welcome. Start with
+[CONTRIBUTING.md](./CONTRIBUTING.md) for the workflow and local checks, and note
+that participation is covered by our
+[Code of Conduct](./CODE_OF_CONDUCT.md). Security issues should follow
+[SECURITY.md](./SECURITY.md) instead of the public issue tracker.
+
+```bash
+npm install
+npm run lint
+npm test
+```
+
+## License
+
+[MIT](./LICENSE) © JSkelet contributors

package/bin/jskelet.mjs

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+/**
+ * JSkelet CLI.
+ *
+ *   jskelet dev      build watch + sunucu, canlı yenileme, dev overlay
+ *   jskelet build    tek seferlik prod build (fontlar, sprite, CSS, JS, görseller)
+ *   jskelet start    prod sunucu (build eksikse önce üretir)
+ *   jskelet init     bulunduğun dizine minimal iskelet kurar
+ *
+ * Alt komutlar ayrı süreçlerde çalışır. Sebep: `dev` iki uzun ömürlü süreci
+ * (build watch + sunucu) yönetiyor ve sunucunun ESM resolve hook'larına
+ * (`--import`) ihtiyacı var; bunlar süreç başlarken kurulmak zorunda.
+ */
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const SRC = path.resolve(fileURLToPath(import.meta.url), "..", "..", "src");
+
+/**
+ * `--import` bir modül **belirteci** bekler, dosya yolu değil. Windows'ta
+ * `H:\...` mutlak yolu `h:` şemalı bir URL sanılıp reddediliyor; file:// URL'e
+ * çevirmek her platformda doğru.
+ */
+const REGISTER = pathToFileURL(path.join(SRC, "runtime", "register.mjs")).href;
+
+const [command, ...rest] = process.argv.slice(2);
+
+/**
+ * `.env` yalnızca varsa geçilir: `--env-file-if-exists` dosya yokken de bir
+ * bildirim satırı basıyor ve bu satır dev çıktısında hata gibi görünüyor.
+ * `--import` alias hook'larını kurar; uygulama kodu `@/…` yazabilsin diye.
+ *
+ * @param {string} file
+ * @param {{ env?: Record<string, string>, args?: string[], hooks?: boolean }} [options]
+ * @returns {import('node:child_process').ChildProcess}
+ */
+function run(file, options = {}) {
+  const args = [
+    ...(fs.existsSync(path.join(process.cwd(), ".env"))
+      ? ["--env-file=.env"]
+      : []),
+    ...(options.hooks === false ? [] : ["--import", REGISTER]),
+    file,
+    ...(options.args ?? []),
+  ];
+
+  return spawn(process.execPath, args, {
+    stdio: "inherit",
+    env: { ...process.env, ...(options.env ?? {}) },
+  });
+}
+
+/** @param {import('node:child_process').ChildProcess} child */
+function exitWith(child) {
+  child.on("exit", (code) => process.exit(code ?? 0));
+}
+
+switch (command) {
+  case "dev": {
+    exitWith(run(path.join(SRC, "dev-server.mjs"), { hooks: false, args: rest }));
+    break;
+  }
+
+  case "build": {
+    exitWith(
+      run(path.join(SRC, "build", "build.mjs"), {
+        env: { NODE_ENV: process.env.NODE_ENV ?? "production" },
+        args: rest,
+      }),
+    );
+    break;
+  }
+
+  case "start": {
+    exitWith(
+      run(path.join(SRC, "start.mjs"), {
+        env: { NODE_ENV: process.env.NODE_ENV ?? "production" },
+        args: rest,
+      }),
+    );
+    break;
+  }
+
+  case "init": {
+    const { init } = await import("../src/init.mjs");
+    await init(process.cwd());
+    break;
+  }
+
+  default: {
+    const known = command ? `bilinmeyen komut: ${command}\n\n` : "";
+    process.stderr.write(
+      `${known}kullanım: jskelet <dev|build|start|init>\n\n` +
+        "  dev     build watch + sunucu (canlı yenileme, dev overlay)\n" +
+        "  build   prod build\n" +
+        "  start   prod sunucu\n" +
+        "  init    bulunduğun dizine minimal iskelet kurar\n",
+    );
+    process.exit(command ? 1 : 0);
+  }
+}