@fiyuu/runtime 0.1.0

package/README.md

@@ -0,0 +1,194 @@
+# Fiyuu
+
+Fiyuu is an **AI-native fullstack framework** built on GEA.
+It makes app structure deterministic and exports machine-readable artifacts so both developers and AI tools can work with the same reliable context.
+
+## What problem does Fiyuu solve?
+
+Routing and rendering are already solved by strong frameworks.
+Fiyuu focuses on a different bottleneck: **AI and humans often misread intent in large, fast-changing codebases**.
+
+Fiyuu enforces fixed route contracts (`page.tsx`, `query.ts`, `action.ts`, `schema.ts`, `meta.ts`) and generates `.fiyuu/graph.json` plus AI docs (`PROJECT.md`, `PATHS.md`, `EXECUTION.md`, and more). This reduces guesswork in generation, refactors, and review flows.
+
+## Why Fiyuu?
+
+- **AI-native project context** — `fiyuu sync` exports graph + AI docs from real app structure
+- **Deterministic fullstack contracts** — fixed file conventions reduce hidden behavior and drift
+- **GEA-first runtime** — app route code stays React-free at the framework layer
+- **Built-in diagnostics** — `fiyuu doctor` validates structure and common anti-patterns
+- **AI assistant bridge** — `fiyuu ai "<prompt>"` prints route-aware context for external LLM workflows
+
+## Measurable differentiation
+
+Fiyuu tracks performance and DX scorecards by release.
+
+| Metric | How to measure | Current (v0.1.x) | Target (v0.2) |
+| --- | --- | --- | --- |
+| Cold build time | `time npm run build` | Baseline pending | >= 20% better on reference app profile |
+| SSR latency (avg/p95) | `npm run benchmark:gea` | Baseline pending | >= 15% lower p95 on reference profile |
+| Client JS bundle size | `npm run benchmark:gea` (bundle output) | Baseline pending | >= 20% smaller on reference profile |
+| AI context readiness time | `time fiyuu sync` | Baseline pending | <= 1s for 100-route reference app |
+
+Until public scorecards are published, treat Fiyuu as an early-stage framework.
+
+## Performance and benchmark tooling
+
+Fiyuu uses Node.js native HTTP server (no Express). Client assets are bundled with esbuild. SSG routes are cached in memory with optional `meta.revalidate` (ISR-style TTL). Query results support TTL caching with in-flight de-duplication. Navigation responses and HTML support ETag/304, and client navigation prefetches links on hover/focus/viewport.
+
+For app-layer UI performance, `fiyuu/client` also provides `optimizedImage`, `optimizedVideo`, and responsive helpers (`responsiveStyle`, `mediaUp`, `fluid`, etc.) so teams can ship faster pages without adding heavy UI runtime dependencies.
+
+## Built-in Database (FiyuuDB)
+
+Fiyuu includes a lightweight, always-in-memory database with SQL-like query support:
+
+```typescript
+// In query.ts or action.ts
+import { db } from "@fiyuu/db";
+
+// SQL-like queries
+const users = await db.query("SELECT * FROM users WHERE age > ? AND status = ?", [18, "active"]);
+await db.query("INSERT INTO users (name, email) VALUES (?, ?)", ["Ali", "ali@test.com"]);
+await db.query("UPDATE users SET status = ? WHERE id = ?", ["inactive", "u_123"]);
+
+// Table API
+const table = db.table("users");
+const admins = table.find({ role: "admin" });
+const one = table.findOne({ email: "a@b.com" });
+table.insert({ name: "Ahmet", email: "ahmet@test.com" });
+```
+
+## Real-time Channels
+
+Fiyuu provides built-in real-time communication via WebSocket and NATS:
+
+```typescript
+// Server-side (app/services/realtime-sync.ts)
+import { defineService } from "@fiyuu/runtime";
+import { realtime } from "@fiyuu/realtime";
+
+export default defineService({
+  name: "realtime-sync",
+  start({ realtime, db }) {
+    const chat = realtime.channel("chat");
+    chat.on("message", async (data, socket) => {
+      chat.broadcast("new-message", { text: data.text, user: socket.userId });
+      await db.query("INSERT INTO messages (text, user) VALUES (?, ?)", [data.text, socket.userId]);
+    });
+  },
+});
+```
+
+```html
+<!-- Client-side -->
+<script>
+  const chat = fiyuu.channel("chat");
+  chat.on("new-message", (data) => console.log(data));
+  chat.emit("message", { text: "Hello!" });
+</script>
+```
+
+## Service-based Lifecycle (Always-Alive App)
+
+Unlike Next.js (request-driven), Fiyuu apps stay alive continuously with background services:
+
+```typescript
+// app/services/data-sync.ts
+import { defineService } from "@fiyuu/runtime";
+
+export default defineService({
+  name: "data-sync",
+  async start({ db, realtime, config, log }) {
+    // Runs on boot, continuously in background
+    setInterval(async () => {
+      const stats = await db.query("SELECT COUNT(*) as c FROM users WHERE active = 1");
+      realtime.channel("stats").emit("update", stats[0]);
+    }, 30000);
+  },
+  async stop({ log }) {
+    // Cleanup on shutdown
+  },
+});
+```
+
+Run benchmark:
+
+```bash
+npm run benchmark:gea
+npm run benchmark:scorecard
+```
+
+This reports per-route latency (`avg`, `p50`, `p95`, `min`, `max`) and total client bundle size.
+The scorecard command also records build/sync/doctor outputs into `docs/benchmarks/latest-scorecard.md`.
+
+## Current scope (v2 direction)
+
+- Primary: **AI-first routing framework** with deterministic contracts
+- Shipping priority: graph tooling, diagnostics, and SSR + cache primitives
+- Secondary: broader adapters, plugin ecosystem depth, CSR/SSG parity
+
+## Competitive snapshot
+
+Fiyuu is not positioned as a full replacement for Next.js, Nuxt, or Astro today.
+It is positioned as an AI-native framework workflow where deterministic graph context is a first-class feature.
+
+- Ecosystem breadth: behind mature frameworks (current reality)
+- AI-readable architecture context: core investment area
+- Public benchmark scorecards: in progress (`docs/benchmark-matrix.md`)
+
+## Use cases
+
+- **AI-assisted teams** using Copilot, Cursor, or local LLM pipelines
+- **React-free app layer** teams that prefer explicit route contracts
+- **Internal tools and dashboards** where deterministic structure matters more than maximal abstraction
+
+## Quick Start
+
+```bash
+npm create fiyuu-app@latest my-app
+cd my-app
+npm install
+npm run dev
+```
+
+## Useful commands
+
+```bash
+fiyuu dev
+fiyuu build
+fiyuu start
+fiyuu deploy
+fiyuu cloud help
+fiyuu cloud login <token> --endpoint https://api.fiyuu.work
+fiyuu cloud project create mysite
+fiyuu cloud deploy mysite
+fiyuu sync
+fiyuu doctor
+fiyuu doctor --fix
+fiyuu graph stats
+fiyuu graph export --format markdown --out docs/graph.md
+fiyuu ai "explain route dependencies for /requests"
+fiyuu skill list
+fiyuu skill run seo-baseline
+fiyuu feat list
+fiyuu feat socket on
+fiyuu feat socket off
+```
+
+## Default starter
+
+- One-page home layout
+- Optional feature selection during setup (interactive multi-select)
+- Optional light/dark theme toggle with localStorage persistence
+- Built-in `app/not-found.tsx` and `app/error.tsx`
+
+## Documentation
+
+- English: `docs/en.md`
+- Turkish: `docs/tr.md`
+- Skills (EN): `docs/skills.md`
+- Skills (TR): `docs/skills.tr.md`
+- v2 Product Spec (TR): `docs/v2-product-spec.tr.md`
+- Benchmark Matrix: `docs/benchmark-matrix.md`
+- Benchmarks Folder: `docs/benchmarks/README.md`
+- AI Demo Walkthrough: `docs/ai-demo.md`
+- AI-for-Framework Guide: `docs/ai-for-framework.md`

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@fiyuu/runtime",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./cli": "./src/cli.js"
+  },
+  "dependencies": {
+    "@geajs/core": "^1.0.12",
+    "@fiyuu/core": "0.1.0",
+    "@fiyuu/db": "0.3.0",
+    "@fiyuu/realtime": "0.3.0",
+    "chokidar": "^4.0.3",
+    "esbuild": "^0.25.2",
+    "ws": "^8.18.1"
+  },
+  "peerDependencies": {
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0"
+  }
+}

package/src/bundler.d.ts

@@ -0,0 +1,9 @@
+import type { FeatureRecord, RenderMode } from "@fiyuu/core";
+export interface ClientAsset {
+    route: string;
+    feature: string;
+    render: RenderMode;
+    bundleFile: string;
+    publicPath: string;
+}
+export declare function bundleClient(features: FeatureRecord[], outputDirectory: string): Promise<ClientAsset[]>;

package/src/bundler.js

@@ -0,0 +1,124 @@
+import { promises as fs, existsSync } from "node:fs";
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { build } from "esbuild";
+const buildCache = new Map();
+export async function bundleClient(features, outputDirectory) {
+    await fs.mkdir(outputDirectory, { recursive: true });
+    const pageFeatures = features.filter((feature) => feature.files["page.tsx"] && feature.render === "csr");
+    const assets = await Promise.all(pageFeatures.map(async (feature) => {
+        const safeFeatureName = feature.feature.length > 0 ? feature.feature.replaceAll("/", "_") : "home";
+        const pageFile = feature.files["page.tsx"];
+        const layoutFiles = resolveLayoutFiles(feature, pageFile);
+        const signature = await createBuildSignature([pageFile, ...layoutFiles]);
+        const signatureHash = createHash("sha1").update(signature).digest("hex").slice(0, 10);
+        const bundleName = `${safeFeatureName}.${signatureHash}.js`;
+        const bundleFile = path.join(outputDirectory, bundleName);
+        const cacheKey = feature.route;
+        const publicPath = `/__fiyuu/client/${bundleName}`;
+        const cached = buildCache.get(cacheKey);
+        if (cached && cached.signature === signature && existsSync(cached.asset.bundleFile)) {
+            return {
+                ...cached.asset,
+                render: feature.render,
+            };
+        }
+        await build({
+            stdin: {
+                contents: createClientEntry(pageFile, layoutFiles),
+                resolveDir: path.dirname(pageFile),
+                sourcefile: `${feature.feature}-client.tsx`,
+                loader: "tsx",
+            },
+            bundle: true,
+            format: "esm",
+            jsx: "automatic",
+            jsxImportSource: "@geajs/core",
+            minify: true,
+            outfile: bundleFile,
+            platform: "browser",
+            sourcemap: false,
+            target: ["es2022"],
+        });
+        const asset = {
+            route: feature.route,
+            feature: feature.feature,
+            render: feature.render,
+            bundleFile,
+            publicPath,
+        };
+        if (cached && cached.asset.bundleFile !== asset.bundleFile && existsSync(cached.asset.bundleFile)) {
+            try {
+                await fs.unlink(cached.asset.bundleFile);
+            }
+            catch {
+                // ignore stale artifact cleanup failures
+            }
+        }
+        buildCache.set(cacheKey, { signature, asset });
+        return asset;
+    }));
+    return assets;
+}
+async function createBuildSignature(filePaths) {
+    const signatures = await Promise.all(filePaths.map(async (filePath) => {
+        const stats = await fs.stat(filePath);
+        return `${filePath}:${stats.size}:${Math.floor(stats.mtimeMs)}`;
+    }));
+    return signatures.join("|");
+}
+function createClientEntry(pageFile, layoutFiles) {
+    const layoutImports = layoutFiles
+        .map((layoutFile, index) => `import * as LayoutModule${index} from ${JSON.stringify(layoutFile)};`)
+        .join("\n");
+    const layoutWrappers = layoutFiles
+        .map((_, index) => `const Layout${index} = LayoutModule${index}.default; if (Layout${index}) { const wrapped = new Layout${index}({ route, children: String(component) }); component = wrapped; }`)
+        .reverse()
+        .join("\n    ");
+    return `
+    import { Component } from "@geajs/core";
+    import Page from ${JSON.stringify(pageFile)};
+    ${layoutImports}
+
+    const data = window.__FIYUU_DATA__ ?? null;
+    const route = window.__FIYUU_ROUTE__ ?? "/";
+    const intent = window.__FIYUU_INTENT__ ?? "";
+    const render = window.__FIYUU_RENDER__ ?? "csr";
+    const rootElement = document.getElementById("app");
+    const pageProps = { data, route, intent, render };
+    if (!(Page && Page.prototype instanceof Component)) {
+      throw new Error("Fiyuu Gea mode expects page default export to extend @geajs/core Component.");
+    }
+    let component = new Page(pageProps);
+    ${layoutWrappers}
+
+    if (rootElement) {
+      rootElement.innerHTML = "";
+      component.render(rootElement);
+
+      // Re-execute any <script> tags injected by the component.
+      // innerHTML assignment does not execute scripts — this is a browser security rule.
+      // We collect all script tags and recreate them so they run normally.
+      const injectedScripts = rootElement.querySelectorAll("script");
+      for (const oldScript of injectedScripts) {
+        const newScript = document.createElement("script");
+        for (const attr of oldScript.attributes) {
+          newScript.setAttribute(attr.name, attr.value);
+        }
+        newScript.textContent = oldScript.textContent;
+        oldScript.parentNode?.replaceChild(newScript, oldScript);
+      }
+    }
+  `;
+}
+function resolveLayoutFiles(feature, pageFile) {
+    const featureParts = feature.feature ? feature.feature.split("/") : [];
+    const featureDirectory = path.dirname(pageFile);
+    const appDirectory = featureParts.length > 0
+        ? path.resolve(featureDirectory, ...Array(featureParts.length).fill(".."))
+        : featureDirectory;
+    const directories = [appDirectory, ...featureParts.map((_, index) => path.join(appDirectory, ...featureParts.slice(0, index + 1)))];
+    return directories
+        .map((directory) => path.join(directory, "layout.tsx"))
+        .filter((layoutPath) => existsSync(layoutPath));
+}

package/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/src/cli.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { existsSync } from "node:fs";
+import { scanApp } from "@fiyuu/core";
+import { bundleClient } from "./bundler.js";
+async function main() {
+    const [, , command, rootDirectory] = process.argv;
+    if (command !== "bundle" || !rootDirectory) {
+        throw new Error("Usage: runtime bundle <rootDirectory>");
+    }
+    const appDirectory = resolveAppDirectory(rootDirectory);
+    const features = await scanApp(appDirectory);
+    const outputDirectory = path.join(rootDirectory, ".fiyuu", "client");
+    await bundleClient(features, outputDirectory);
+    console.log(`Bundled client assets to ${outputDirectory}`);
+}
+function resolveAppDirectory(rootDirectory) {
+    const rootAppDirectory = path.join(rootDirectory, "app");
+    const exampleAppDirectory = path.join(rootDirectory, "examples", "basic-app", "app");
+    return existsSync(rootAppDirectory) ? rootAppDirectory : exampleAppDirectory;
+}
+main().catch((error) => {
+    console.error(error instanceof Error ? error.message : "Unknown bundle error");
+    process.exitCode = 1;
+});

package/src/client-runtime.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Fiyuu Client Runtime
+ *
+ * A small script injected into every page that provides:
+ *   - fiyuu.theme   — dark/light mode management
+ *   - fiyuu.state   — simple reactive state with DOM binding
+ *   - fiyuu.bind    — shorthand for updating element text / html
+ *   - fiyuu.router  — client-side navigation without page reload
+ *   - fiyuu.partial — replace a DOM element with a fetched route's content
+ *   - fiyuu.onError — global client-side error handler
+ *   - fiyuu.ws      — WebSocket connection helper
+ *
+ * Everything is accessible via window.fiyuu in page scripts.
+ */
+export declare function buildClientRuntime(websocketPath: string): string;