@fiyuu/core 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,17 @@
+{
+  "name": "@fiyuu/core",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": "./src/index.js",
+    "./client": "./src/client.js"
+  },
+  "dependencies": {
+    "zod": "^3.24.2"
+  },
+  "peerDependencies": {
+    "react": "^19.1.0"
+  }
+}

package/src/artifacts.d.ts

@@ -0,0 +1,20 @@
+import { type ProjectGraph } from "./scanner.js";
+export declare function syncProjectArtifacts(rootDirectory: string, appDirectory: string): Promise<ProjectGraph>;
+interface SkillSummary {
+    name: string;
+    description: string;
+    tags: string[];
+    filePath: string;
+}
+export declare function createAiDocs(graph: ProjectGraph, rootDirectory: string, skills?: SkillSummary[]): {
+    project: string;
+    paths: string;
+    states: string;
+    features: string;
+    warnings: string;
+    skills: string;
+    execution: string;
+    interventions: string;
+    doctor: string;
+};
+export {};

package/src/artifacts.js

@@ -0,0 +1,274 @@
+import { existsSync, promises as fs } from "node:fs";
+import path from "node:path";
+import { createProjectGraph } from "./scanner.js";
+export async function syncProjectArtifacts(rootDirectory, appDirectory) {
+    const graph = await createProjectGraph(appDirectory);
+    const outputDirectory = path.join(rootDirectory, ".fiyuu");
+    await fs.mkdir(outputDirectory, { recursive: true });
+    await fs.writeFile(path.join(outputDirectory, "graph.json"), `${JSON.stringify(graph, null, 2)}\n`);
+    const skills = await loadSkillSummaries(rootDirectory);
+    const docs = createAiDocs(graph, rootDirectory, skills);
+    await Promise.all([
+        fs.writeFile(path.join(outputDirectory, "PROJECT.md"), docs.project),
+        fs.writeFile(path.join(outputDirectory, "PATHS.md"), docs.paths),
+        fs.writeFile(path.join(outputDirectory, "STATES.md"), docs.states),
+        fs.writeFile(path.join(outputDirectory, "FEATURES.md"), docs.features),
+        fs.writeFile(path.join(outputDirectory, "WARNINGS.md"), docs.warnings),
+        fs.writeFile(path.join(outputDirectory, "SKILLS.md"), docs.skills),
+        fs.writeFile(path.join(outputDirectory, "EXECUTION.md"), docs.execution),
+        fs.writeFile(path.join(outputDirectory, "INTERVENTIONS.md"), docs.interventions),
+        fs.writeFile(path.join(outputDirectory, "DOCTOR.md"), docs.doctor),
+    ]);
+    return graph;
+}
+async function loadSkillSummaries(rootDirectory) {
+    const skillsDir = path.join(rootDirectory, "skills");
+    if (!existsSync(skillsDir))
+        return [];
+    const entries = await fs.readdir(skillsDir, { withFileTypes: true });
+    const skillFiles = entries.filter((entry) => entry.isFile() && entry.name.endsWith(".ts"));
+    return Promise.all(skillFiles.map(async (entry) => {
+        const filePath = path.join(skillsDir, entry.name);
+        const source = await fs.readFile(filePath, "utf8");
+        const nameMatch = source.match(/name\s*:\s*["'`]([^"'`]+)["'`]/);
+        const descMatch = source.match(/description\s*:\s*["'`]([^"'`]+)["'`]/);
+        const tagsMatch = source.match(/tags\s*:\s*\[([^\]]*)\]/);
+        const tags = tagsMatch
+            ? tagsMatch[1].match(/["'`]([^"'`]+)["'`]/g)?.map((t) => t.replace(/["'`]/g, "")) ?? []
+            : [];
+        return {
+            name: nameMatch?.[1] ?? entry.name.replace(/\.ts$/, ""),
+            description: descMatch?.[1] ?? "no description",
+            tags,
+            filePath: `skills/${entry.name}`,
+        };
+    }));
+}
+export function createAiDocs(graph, rootDirectory, skills = []) {
+    const project = `# Fiyuu Project Context
+
+This file is auto-generated for AI systems reading the project.
+Do not edit manually — run \`fiyuu sync\` to regenerate.
+
+## Summary
+
+- root: ${rootDirectory}
+- routes: ${graph.routes.length}
+- features: ${graph.features.length}
+- actions: ${graph.actions.length}
+- queries: ${graph.queries.length}
+- skills: ${skills.length}
+
+## Architecture
+
+Fiyuu is a file-based fullstack framework built on GEA (@geajs/core).
+Each route is a feature directory under \`app/\` with these fixed files:
+- \`meta.ts\` — intent, title, render mode, SEO (required)
+- \`schema.ts\` — Zod input/output contracts (required)
+- \`page.tsx\` — GEA component for UI (optional)
+- \`query.ts\` — data fetching with \`execute()\` (optional)
+- \`action.ts\` — server mutations with \`execute()\` (optional)
+- \`layout.tsx\` — route-scoped layout wrapper (optional)
+- \`middleware.ts\` — request middleware (optional)
+- \`route.ts\` — raw API route (optional, for \`/api/*\`)
+
+## Route Overview
+
+${graph.features
+        .map((feature) => `- route: ${feature.route}\n  intent: ${feature.intent ?? "missing"}\n  render: ${feature.render}\n  missing: ${feature.missingRequiredFiles.join(", ") || "none"}`)
+        .join("\n")}
+`;
+    const paths = `# Fiyuu Paths
+
+Maps route folders to their fixed files.
+Auto-generated — run \`fiyuu sync\` to update.
+
+${graph.features
+        .map((feature) => {
+        const entries = Object.entries(feature.files)
+            .filter(([, value]) => Boolean(value))
+            .map(([name, value]) => `  - ${name}: ${value}`)
+            .join("\n");
+        return `## ${feature.route}\n- directory: ${feature.directory}\n${entries}`;
+    })
+        .join("\n\n")}
+`;
+    const states = `# Fiyuu States
+
+Current structural state snapshot for AI review.
+Auto-generated — run \`fiyuu sync\` to update.
+
+## Render Modes
+
+${graph.features.map((feature) => `- ${feature.route}: ${feature.render}`).join("\n")}
+
+## Intent State
+
+${graph.features.map((feature) => `- ${feature.route}: ${feature.intent ?? "MISSING"}`).join("\n")}
+
+## Schema Descriptions
+
+${graph.features.map((feature) => `- ${feature.route}: ${feature.descriptions.join(" | ") || "MISSING"}`).join("\n")}
+`;
+    const warnings = `# Fiyuu Warnings
+
+Auto-generated — run \`fiyuu sync\` to update.
+
+${graph.features.some((feature) => feature.warnings.length > 0)
+        ? graph.features
+            .filter((feature) => feature.warnings.length > 0)
+            .map((feature) => `## ${feature.route}\n${feature.warnings.map((w) => `- ${w}`).join("\n")}`)
+            .join("\n\n")
+        : "No structural warnings detected.\n"}`;
+    const features = `# Fiyuu Features
+
+## Runtime Capabilities
+
+- route count: ${graph.routes.length}
+- action count: ${graph.actions.length}
+- query count: ${graph.queries.length}
+
+## Per-Route Capabilities
+
+${graph.features
+        .map((feature) => `- ${feature.route}:\n  render=${feature.render}, page=${Boolean(feature.files["page.tsx"])}, action=${Boolean(feature.files["action.ts"])}, query=${Boolean(feature.files["query.ts"])}`)
+        .join("\n")}
+`;
+    const skillsDoc = skills.length === 0
+        ? `# Fiyuu Skills
+
+No skills found. Create one with \`fiyuu skill new <name>\`.
+
+Skills are project-aware scripts in the \`skills/\` directory.
+AI assistants can read and run them for automated project tasks.
+`
+        : `# Fiyuu Skills
+
+Skills are project-aware scripts AI assistants can read and execute.
+Run a skill: \`fiyuu skill run <name>\`
+
+## Available Skills
+
+${skills
+            .map((skill) => `### ${skill.name}\n- file: ${skill.filePath}\n- description: ${skill.description}\n- tags: ${skill.tags.join(", ") || "none"}`)
+            .join("\n\n")}
+`;
+    const execution = buildExecutionDoc(graph);
+    const interventions = buildInterventionsDoc();
+    const doctor = buildDoctorDoc();
+    return {
+        project: `${project.trim()}\n`,
+        paths: `${paths.trim()}\n`,
+        states: `${states.trim()}\n`,
+        features: `${features.trim()}\n`,
+        warnings: `${warnings.trim()}\n`,
+        skills: skillsDoc,
+        execution,
+        interventions,
+        doctor,
+    };
+}
+function buildExecutionDoc(graph) {
+    const header = `# Fiyuu Execution Graph
+
+Shows the server-side execution chain for every route.
+Auto-generated — run \`fiyuu sync\` to update.
+
+Each request follows this deterministic order:
+  1. Middleware (if middleware.ts exists)
+  2. Query     (if query.ts exists) → fetches data, optional cache
+  3. Layout    (if layout.tsx exists) → wraps page content
+  4. Page      (page.tsx) → renders HTML
+  5. Document  → injects meta, client runtime, scripts
+  6. Response  → sent to browser
+
+`;
+    const routeSections = graph.features
+        .map((feature) => {
+        const steps = [];
+        const hasMiddleware = Boolean(feature.files["middleware.ts"]);
+        const hasQuery = Boolean(feature.files["query.ts"]);
+        const hasLayout = Boolean(feature.files["layout.tsx"]);
+        const hasPage = Boolean(feature.files["page.tsx"]);
+        if (hasMiddleware)
+            steps.push(`  → middleware.ts        intercept / auth / headers`);
+        if (hasQuery)
+            steps.push(`  → query.ts::execute()  fetch data → injected as page props`);
+        if (hasLayout)
+            steps.push(`  → layout.tsx::template() wrap content`);
+        if (hasPage)
+            steps.push(`  → page.tsx::Page()     render HTML  [${feature.render.toUpperCase()}]`);
+        steps.push(`  → renderDocument()     inject meta, runtime, scripts`);
+        steps.push(`  → HTTP 200 text/html`);
+        const flags = [];
+        if (feature.render === "ssg")
+            flags.push("cached after first render");
+        if (feature.render === "csr")
+            flags.push("body empty — client bundle renders");
+        return [
+            `## ${feature.route}`,
+            `- render: ${feature.render}`,
+            `- intent: ${feature.intent ?? "missing"}`,
+            flags.length > 0 ? `- notes: ${flags.join(", ")}` : null,
+            ``,
+            `\`\`\``,
+            `Request GET ${feature.route}`,
+            ...steps,
+            `\`\`\``,
+        ]
+            .filter(Boolean)
+            .join("\n");
+    })
+        .join("\n\n");
+    return `${header}${routeSections}\n`;
+}
+function buildInterventionsDoc() {
+    return `# Fiyuu Interventions
+
+Safe framework interventions that can be applied automatically.
+
+## Supported via \`fiyuu doctor --fix\`
+
+- Replace \`className=\` with \`class=\` in route source files.
+- Add missing \`export async function execute()\` in \`action.ts\` and \`query.ts\`.
+- Create missing \`app/not-found.tsx\` and \`app/error.tsx\` fallback pages.
+- Add missing \`seo.title\` and \`seo.description\` fields in route \`meta.ts\`.
+
+## Not auto-fixed (manual review required)
+
+- \`dangerouslySetInnerHTML\` usage.
+- React imports or hook usage in GEA routes.
+- noJs violations where \`meta.ts\` sets \`noJs: true\` and page uses \`<script>\`.
+
+## SEO baseline
+
+- Use route-specific \`seo.title\`.
+- Keep \`seo.description\` around 12-28 words.
+`;
+}
+function buildDoctorDoc() {
+    return `# Fiyuu Doctor
+
+Command reference for deterministic checks and safe fixes.
+
+## Check only
+
+\`fiyuu doctor\`
+
+- Reports structure violations and quality warnings.
+
+## Check + safe fixes
+
+\`fiyuu doctor --fix\`
+
+- Applies only deterministic, low-risk fixes.
+- Prints each fixed item with \`(fixed)\` marker.
+
+## Typical workflow
+
+1. \`fiyuu sync\`
+2. \`fiyuu doctor --fix\`
+3. \`fiyuu doctor\`
+4. \`fiyuu build\`
+`;
+}

package/src/client.d.ts

@@ -0,0 +1,8 @@
+export * from "./contracts.js";
+export * from "./state.js";
+export * from "./virtual.js";
+export * from "./template.js";
+export * from "./media.js";
+export * from "./responsive.js";
+export * from "./responsive-wrapper.js";
+export * from "./reactive.js";

package/src/client.js

@@ -0,0 +1,8 @@
+export * from "./contracts.js";
+export * from "./state.js";
+export * from "./virtual.js";
+export * from "./template.js";
+export * from "./media.js";
+export * from "./responsive.js";
+export * from "./responsive-wrapper.js";
+export * from "./reactive.js";