@fiyuu/core 0.1.0

package/src/config.d.ts

@@ -0,0 +1,179 @@
+export interface FiyuuConfig {
+    app?: {
+        name?: string;
+        runtime?: "node" | "bun";
+        port?: number;
+    };
+    ai?: {
+        enabled?: boolean;
+        skillsDirectory?: string;
+        defaultSkills?: string[];
+        graphContext?: boolean;
+        inspector?: {
+            enabled?: boolean;
+            localModelCommand?: string;
+            timeoutMs?: number;
+            autoSetupPrompt?: boolean;
+        };
+    };
+    fullstack?: {
+        client?: boolean;
+        serverActions?: boolean;
+        serverQueries?: boolean;
+        sockets?: boolean;
+    };
+    data?: {
+        driver?: string;
+        path?: string;
+        autosave?: boolean;
+        autosaveIntervalMs?: number;
+        tables?: string[];
+    };
+    security?: {
+        requestEncryption?: boolean;
+        serverSecretFile?: string;
+    };
+    websocket?: {
+        enabled?: boolean;
+        path?: string;
+        heartbeatMs?: number;
+        maxPayloadBytes?: number;
+    };
+    realtime?: {
+        enabled?: boolean;
+        transports?: ("websocket" | "nats")[];
+        websocket?: {
+            path?: string;
+            heartbeatMs?: number;
+            maxPayloadBytes?: number;
+        };
+        nats?: {
+            url?: string;
+            name?: string;
+        };
+    };
+    services?: {
+        enabled?: boolean;
+        directory?: string;
+        failFast?: boolean;
+    };
+    middleware?: {
+        enabled?: boolean;
+    };
+    developerTools?: {
+        enabled?: boolean;
+        renderTiming?: boolean;
+    };
+    observability?: {
+        requestId?: boolean;
+        warningsAsOverlay?: boolean;
+    };
+    auth?: {
+        enabled?: boolean;
+        sessionStrategy?: "cookie" | "token";
+    };
+    analytics?: {
+        enabled?: boolean;
+        provider?: string;
+    };
+    featureFlags?: {
+        enabled?: boolean;
+        defaults?: Record<string, boolean>;
+    };
+    errors?: {
+        /**
+         * Called for every unhandled server error.
+         * Use this to send errors to Sentry, Datadog, etc.
+         */
+        handler?: (error: Error, context: {
+            route: string;
+            method: string;
+            requestId: string;
+        }) => void | Promise<void>;
+        /**
+         * Whether to expose error details (stack trace, message) in responses.
+         * Defaults to true in dev, false in production.
+         */
+        expose?: boolean;
+    };
+    deploy?: {
+        /**
+         * Enables `fiyuu deploy` workflow.
+         * If undefined, deploy command still works when `deploy.ssh` is configured.
+         */
+        enabled?: boolean;
+        /**
+         * Build locally before upload. Defaults to true.
+         */
+        localBuild?: boolean;
+        /**
+         * Extra archive exclude patterns for `tar`.
+         */
+        excludes?: string[];
+        ssh?: {
+            host: string;
+            user: string;
+            port?: number;
+            privateKeyPath?: string;
+            /**
+             * Absolute path on remote server (for example: /var/www/my-app)
+             */
+            destinationPath: string;
+            /**
+             * Number of old releases to keep on the server.
+             */
+            keepReleases?: number;
+        };
+        remote?: {
+            /**
+             * Command executed on remote server in release directory.
+             */
+            installCommand?: string;
+            /**
+             * Command executed on remote server after install.
+             */
+            buildCommand?: string;
+            /**
+             * Command executed on remote server to start/reload the app.
+             */
+            startCommand?: string;
+            /**
+             * Optional validation command after start.
+             */
+            healthcheckCommand?: string;
+        };
+        pm2?: {
+            enabled?: boolean;
+            /**
+             * Auto-generate ecosystem file in project root if missing.
+             */
+            autoCreate?: boolean;
+            ecosystemFile?: string;
+            appName?: string;
+            instances?: number | "max";
+            execMode?: "fork" | "cluster";
+            maxMemoryRestart?: string;
+            env?: Record<string, string>;
+        };
+    };
+    cloud?: {
+        /**
+         * Control-plane API endpoint for `fiyuu cloud`.
+         * Example: https://api.fiyuu.work
+         */
+        endpoint?: string;
+        /**
+         * Default project slug used by `fiyuu cloud deploy`.
+         */
+        project?: string;
+        /**
+         * Extra archive exclude patterns used by cloud deploy packaging.
+         */
+        excludes?: string[];
+    };
+}
+export interface LoadedFiyuuConfig {
+    config: FiyuuConfig;
+    env: Record<string, string>;
+}
+export declare function loadFiyuuConfig(rootDirectory: string, mode?: "dev" | "start"): Promise<LoadedFiyuuConfig>;

package/src/config.js

@@ -0,0 +1,58 @@
+import { existsSync } from "node:fs";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+export async function loadFiyuuConfig(rootDirectory, mode = "dev") {
+    const env = await loadFiyuuEnvironment(rootDirectory, mode);
+    const configPath = path.join(rootDirectory, "fiyuu.config.ts");
+    if (!existsSync(configPath)) {
+        applyEnv(env);
+        return { config: {}, env };
+    }
+    const moduleUrl = pathToFileURL(configPath).href;
+    const loaded = await import(`${moduleUrl}?t=${Date.now()}`);
+    const config = (loaded.default ?? loaded.config ?? {}) ?? {};
+    applyEnv(env);
+    return { config, env };
+}
+async function loadFiyuuEnvironment(rootDirectory, mode) {
+    const directory = path.join(rootDirectory, ".fiyuu");
+    const files = [
+        path.join(directory, "env"),
+        path.join(directory, `${mode}.env`),
+        path.join(directory, "SECRET"),
+    ];
+    const env = {};
+    for (const filePath of files) {
+        if (!existsSync(filePath)) {
+            continue;
+        }
+        const name = path.basename(filePath);
+        if (name === "SECRET") {
+            env.FIYUU_SECRET = (await fs.readFile(filePath, "utf8")).trim();
+            continue;
+        }
+        const content = await fs.readFile(filePath, "utf8");
+        for (const line of content.split(/\r?\n/)) {
+            const trimmed = line.trim();
+            if (!trimmed || trimmed.startsWith("#")) {
+                continue;
+            }
+            const separator = trimmed.indexOf("=");
+            if (separator <= 0) {
+                continue;
+            }
+            const key = trimmed.slice(0, separator).trim();
+            const value = trimmed.slice(separator + 1).trim();
+            env[key] = value;
+        }
+    }
+    return env;
+}
+function applyEnv(env) {
+    for (const [key, value] of Object.entries(env)) {
+        if (process.env[key] === undefined) {
+            process.env[key] = value;
+        }
+    }
+}

package/src/contracts.d.ts

@@ -0,0 +1,176 @@
+import { z } from "zod";
+export type AnyZodSchema = z.ZodTypeAny;
+export interface SchemaContract<TInput extends AnyZodSchema = AnyZodSchema, TOutput extends AnyZodSchema = AnyZodSchema> {
+    input: TInput;
+    output: TOutput;
+    description: string;
+}
+export interface ActionDefinition<TInput extends AnyZodSchema = AnyZodSchema, TOutput extends AnyZodSchema = AnyZodSchema> extends SchemaContract<TInput, TOutput> {
+    kind: "action";
+}
+export interface QueryDefinition<TInput extends AnyZodSchema = AnyZodSchema, TOutput extends AnyZodSchema = AnyZodSchema> extends SchemaContract<TInput, TOutput> {
+    kind: "query";
+}
+export interface QueryCacheConfig {
+    /** Cache TTL in seconds. Set to 0 to disable. */
+    ttl: number;
+    /** Cache key varies by these URL query string parameters. */
+    vary?: string[];
+}
+export interface MetaDefinition {
+    intent: string;
+    title?: string;
+    render?: RenderMode;
+    /**
+     * Mark this page as zero-JS.
+     * `fiyuu doctor` will warn if <script> tags are detected in page.tsx.
+     */
+    noJs?: boolean;
+    /**
+     * Revalidate interval in seconds for `render: "ssg"` pages.
+     * Works like ISR: stale HTML is served immediately and refreshed in background.
+     */
+    revalidate?: number;
+    seo?: {
+        title?: string;
+        description?: string;
+    };
+}
+export interface PageDefinition {
+    kind: "page";
+    intent: string;
+}
+export interface LayoutDefinition {
+    kind: "layout";
+    name?: string;
+}
+export type RenderMode = "ssr" | "csr" | "ssg";
+export interface PageProps<TData = unknown> {
+    data: TData | null;
+    route: string;
+    intent: string;
+    render: RenderMode;
+    /** Dynamic route parameters extracted from the URL, e.g. { id: "42" } for /blog/[id] */
+    params: Record<string, string>;
+}
+export interface LayoutProps {
+    children: string;
+    route: string;
+}
+export declare function defineAction<TInput extends AnyZodSchema, TOutput extends AnyZodSchema>(config: SchemaContract<TInput, TOutput>): ActionDefinition<TInput, TOutput>;
+export declare function defineQuery<TInput extends AnyZodSchema, TOutput extends AnyZodSchema>(config: SchemaContract<TInput, TOutput>): QueryDefinition<TInput, TOutput>;
+export declare function definePage(config: {
+    intent: string;
+}): PageDefinition;
+export declare function defineLayout(config?: {
+    name?: string;
+}): LayoutDefinition;
+export declare function defineMeta(config: MetaDefinition): MetaDefinition;
+/** TypeScript output type inferred from a QueryDefinition's output Zod schema. */
+export type InferQueryOutput<T extends QueryDefinition> = z.infer<T["output"]>;
+/** TypeScript input type inferred from a QueryDefinition's input Zod schema. */
+export type InferQueryInput<T extends QueryDefinition> = z.infer<T["input"]>;
+/** TypeScript input type inferred from an ActionDefinition's input Zod schema. */
+export type InferActionInput<T extends ActionDefinition> = z.infer<T["input"]>;
+/** TypeScript output type inferred from an ActionDefinition's output Zod schema. */
+export type InferActionOutput<T extends ActionDefinition> = z.infer<T["output"]>;
+/**
+ * Context passed to query `execute()` functions.
+ *
+ * @example
+ * export async function execute({ request, params }: QueryContext) {
+ *   const sessionId = getSessionIdFromRequest(request as any);
+ *   ...
+ * }
+ */
+export interface QueryContext {
+    /** Incoming HTTP request (Node.js IncomingMessage). Cast to `any` if you need raw access. */
+    request: unknown;
+    /** Dynamic URL parameters, e.g. { id: "42" } for route /blog/[id] */
+    params: Record<string, string>;
+}
+/**
+ * Context passed to action `execute()` functions.
+ * Pass `typeof action` as the generic to get fully typed `input`.
+ *
+ * @example
+ * export const action = defineAction({ input: z.object({ title: z.string() }), ... });
+ *
+ * export async function execute({ input, request }: ActionContext<typeof action>) {
+ *   // input.title is typed as string — no manual type annotation needed
+ * }
+ */
+export interface ActionContext<T extends ActionDefinition = ActionDefinition> {
+    /** Action input, typed from the action's Zod input schema. */
+    input: z.infer<T["input"]>;
+    /** Incoming HTTP request (Node.js IncomingMessage). Cast to `any` if you need raw access. */
+    request: unknown;
+    /** Dynamic URL parameters, e.g. { id: "42" } for route /blog/[id] */
+    params: Record<string, string>;
+}
+/**
+ * Context object passed to every middleware handler.
+ *
+ * @example
+ * export const middleware = defineMiddleware(async ({ url, request }, next) => {
+ *   if (url.pathname === "/secret") { ... }
+ *   await next();
+ * });
+ */
+export interface FiyuuMiddlewareContext {
+    /** Incoming HTTP request — Node.js `IncomingMessage`. */
+    request: unknown;
+    /** Parsed request URL. */
+    url: URL;
+    /** Mutable response headers that will be sent with the final response. */
+    responseHeaders: Record<string, string>;
+    /** Unique ID for this request (useful for logging). */
+    requestId: string;
+    /** Non-fatal warnings accumulated during request handling. */
+    warnings: string[];
+}
+/**
+ * Return this from a middleware to short-circuit the request.
+ *
+ * @example
+ * // Redirect to login
+ * return {
+ *   headers: { Location: "/auth" },
+ *   response: { status: 302, body: "" },
+ * };
+ */
+export interface FiyuuMiddlewareResult {
+    /** Extra response headers to send (e.g. `Location` for redirects). */
+    headers?: Record<string, string>;
+    response?: {
+        /** HTTP status code. */
+        status?: number;
+        /** JSON body — serialised automatically. */
+        json?: unknown;
+        /** Raw string body. */
+        body?: string;
+    };
+}
+/** Call this to continue to the next middleware or the route handler. */
+export type FiyuuMiddlewareNext = () => Promise<void>;
+/**
+ * A single middleware function.
+ * Return `FiyuuMiddlewareResult` to short-circuit, or call `next()` to continue.
+ */
+export type FiyuuMiddlewareHandler = (context: FiyuuMiddlewareContext, next: FiyuuMiddlewareNext) => Promise<FiyuuMiddlewareResult | void> | FiyuuMiddlewareResult | void;
+/**
+ * Wraps your middleware function and gives it full type inference.
+ * Import from `@fiyuu/core` — no need to touch `@fiyuu/runtime`.
+ *
+ * @example  app/middleware.ts
+ * import { defineMiddleware } from "@fiyuu/core";
+ *
+ * export const middleware = defineMiddleware(async ({ url, request }, next) => {
+ *   if (url.pathname.startsWith("/dashboard")) {
+ *     const user = await getSessionUser(request);
+ *     if (!user) return { headers: { Location: "/auth" }, response: { status: 302, body: "" } };
+ *   }
+ *   await next();
+ * });
+ */
+export declare function defineMiddleware(handler: FiyuuMiddlewareHandler): FiyuuMiddlewareHandler;

package/src/contracts.js

@@ -0,0 +1,45 @@
+export function defineAction(config) {
+    return {
+        kind: "action",
+        ...config,
+    };
+}
+export function defineQuery(config) {
+    return {
+        kind: "query",
+        ...config,
+    };
+}
+export function definePage(config) {
+    return {
+        kind: "page",
+        ...config,
+    };
+}
+export function defineLayout(config = {}) {
+    return {
+        kind: "layout",
+        ...config,
+    };
+}
+export function defineMeta(config) {
+    return config;
+}
+/**
+ * Wraps your middleware function and gives it full type inference.
+ * Import from `@fiyuu/core` — no need to touch `@fiyuu/runtime`.
+ *
+ * @example  app/middleware.ts
+ * import { defineMiddleware } from "@fiyuu/core";
+ *
+ * export const middleware = defineMiddleware(async ({ url, request }, next) => {
+ *   if (url.pathname.startsWith("/dashboard")) {
+ *     const user = await getSessionUser(request);
+ *     if (!user) return { headers: { Location: "/auth" }, response: { status: 302, body: "" } };
+ *   }
+ *   await next();
+ * });
+ */
+export function defineMiddleware(handler) {
+    return handler;
+}

package/src/generator.d.ts

@@ -0,0 +1,2 @@
+export declare function generatePageFeature(appDirectory: string, featureName: string): Promise<string[]>;
+export declare function generateActionFeature(appDirectory: string, featureName: string): Promise<string[]>;

package/src/generator.js

@@ -0,0 +1,124 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+const PAGE_TEMPLATE = `import { Component } from "@geajs/core";
+import { definePage, html, optimizedImage, responsiveStyle, fluid, type PageProps } from "fiyuu/client";
+
+type {{Title}}Data = Record<string, unknown>;
+
+export const page = definePage({
+  intent: "{{intent}}",
+});
+
+export default class {{Title}}Page extends Component<PageProps<{{Title}}Data>> {
+  template({ data, intent }: PageProps<{{Title}}Data> = this.props) {
+    // Strings interpolated into html\`\` are auto-escaped — no need for escapeHtml().
+    // For pre-rendered HTML fragments, use raw() to prevent double-escaping.
+    const responsive = responsiveStyle(".feature-shell", "padding:16px;max-width:100%;", {
+      md: "padding:24px;",
+      lg: "padding:32px;max-width:960px;margin-inline:auto;",
+    });
+    return html\`<main style="padding:48px;font-family:ui-sans-serif,system-ui,sans-serif">
+      \${responsive}
+      <section class="feature-shell">
+      <h1 style="margin:0;font-size:2.5rem">{{title}}</h1>
+      <p style="margin-top:12px;color:#4b5b4c;font-size:\${fluid(16, 20)}">\${intent}</p>
+      \${optimizedImage({ src: "/assets/hero.jpg", alt: "{{title}}", width: 1280, height: 720, sizes: "(min-width: 1024px) 960px, 100vw" })}
+      </section>
+    </main>\`;
+  }
+}
+`;
+const ACTION_TEMPLATE = `import { z } from "zod";
+import { defineAction } from "fiyuu/client";
+
+export const action = defineAction({
+  input: z.object({}),
+  output: z.object({ success: z.boolean() }),
+  description: "{{description}}",
+});
+
+export async function execute(input: Record<string, unknown>) {
+  return { success: true };
+}
+`;
+const QUERY_TEMPLATE = `import { z } from "zod";
+import { defineQuery } from "fiyuu/client";
+
+export const query = defineQuery({
+  input: z.object({}),
+  output: z.object({}),
+  description: "{{description}}",
+});
+
+export async function execute() {
+  return {};
+}
+`;
+const SCHEMA_TEMPLATE = `import { z } from "zod";
+
+export const input = z.object({});
+
+export const output = z.object({
+  success: z.boolean(),
+});
+
+export const description = "{{description}}";
+`;
+const META_TEMPLATE = `import { defineMeta } from "fiyuu/client";
+
+export default defineMeta({
+  intent: "{{intent}}",
+  title: "{{title}}",
+  render: "ssr",
+  seo: {
+    title: "{{title}}",
+    description: "{{description}}",
+  },
+});
+`;
+export async function generatePageFeature(appDirectory, featureName) {
+    const featureDirectory = path.join(appDirectory, featureName);
+    await fs.mkdir(featureDirectory, { recursive: true });
+    const title = titleCase(featureName);
+    const intent = `${title} page for user-facing interactions`;
+    const description = `Fetches data for ${title}`;
+    const files = [
+        ["page.tsx", PAGE_TEMPLATE],
+        ["query.ts", QUERY_TEMPLATE],
+        ["schema.ts", SCHEMA_TEMPLATE],
+        ["meta.ts", META_TEMPLATE],
+    ];
+    await Promise.all(files.map(([fileName, template]) => fs.writeFile(path.join(featureDirectory, fileName), hydrate(template, { title, intent, description, Title: pascalCase(featureName) }))));
+    return files.map(([fileName]) => path.join(featureDirectory, fileName));
+}
+export async function generateActionFeature(appDirectory, featureName) {
+    const featureDirectory = path.join(appDirectory, featureName);
+    await fs.mkdir(featureDirectory, { recursive: true });
+    const title = titleCase(featureName);
+    const intent = `${title} workflow for server-side mutations`;
+    const description = `Performs ${title} mutation`;
+    const files = [
+        ["action.ts", ACTION_TEMPLATE],
+        ["schema.ts", SCHEMA_TEMPLATE],
+        ["meta.ts", META_TEMPLATE],
+    ];
+    await Promise.all(files.map(([fileName, template]) => fs.writeFile(path.join(featureDirectory, fileName), hydrate(template, { title, intent, description, Title: pascalCase(featureName) }))));
+    return files.map(([fileName]) => path.join(featureDirectory, fileName));
+}
+function hydrate(template, replacements) {
+    return Object.entries(replacements).reduce((content, [key, value]) => content.replaceAll(`{{${key}}}`, value), template);
+}
+function titleCase(value) {
+    return value
+        .split(/[\/-]/)
+        .filter(Boolean)
+        .map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1))
+        .join(" ");
+}
+function pascalCase(value) {
+    return value
+        .split(/[\/-_]/)
+        .filter(Boolean)
+        .map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1))
+        .join("");
+}

package/src/index.d.ts

@@ -0,0 +1,11 @@
+export * from "./contracts.js";
+export * from "./artifacts.js";
+export * from "./config.js";
+export * from "./generator.js";
+export * from "./media.js";
+export * from "./responsive.js";
+export * from "./responsive-wrapper.js";
+export * from "./scanner.js";
+export * from "./state.js";
+export * from "./virtual.js";
+export * from "./reactive.js";

package/src/index.js

@@ -0,0 +1,11 @@
+export * from "./contracts.js";
+export * from "./artifacts.js";
+export * from "./config.js";
+export * from "./generator.js";
+export * from "./media.js";
+export * from "./responsive.js";
+export * from "./responsive-wrapper.js";
+export * from "./scanner.js";
+export * from "./state.js";
+export * from "./virtual.js";
+export * from "./reactive.js";

package/src/media.d.ts

@@ -0,0 +1,44 @@
+export interface OptimizedImageSource {
+    srcSet: string;
+    media?: string;
+    type?: string;
+    sizes?: string;
+}
+export interface OptimizedImageProps {
+    src: string;
+    alt: string;
+    width?: number;
+    height?: number;
+    sizes?: string;
+    srcSet?: string;
+    sources?: OptimizedImageSource[];
+    loading?: "lazy" | "eager";
+    decoding?: "async" | "sync" | "auto";
+    fetchPriority?: "high" | "low" | "auto";
+    class?: string;
+    style?: string;
+    id?: string;
+}
+export interface OptimizedVideoSource {
+    src: string;
+    type?: string;
+    media?: string;
+}
+export interface OptimizedVideoProps {
+    src?: string;
+    sources?: OptimizedVideoSource[];
+    poster?: string;
+    preload?: "none" | "metadata" | "auto";
+    controls?: boolean;
+    muted?: boolean;
+    loop?: boolean;
+    autoPlay?: boolean;
+    playsInline?: boolean;
+    width?: number;
+    height?: number;
+    class?: string;
+    style?: string;
+    id?: string;
+}
+export declare function optimizedImage(props: OptimizedImageProps): string;
+export declare function optimizedVideo(props: OptimizedVideoProps): string;