npm - hadars - Versions diffs - 0.2.1 → 0.2.2-rc.0 - Mend

hadars 0.2.1 → 0.2.2-rc.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (34) hide show

package/README.md +177 -14
package/cli-lib.ts +97 -5
package/dist/{chunk-HWOLYLPF.js → chunk-H72BZXOA.js} +2 -2
package/dist/cli.js +519 -16
package/dist/cloudflare.cjs +2 -2
package/dist/cloudflare.d.cts +1 -1
package/dist/cloudflare.d.ts +1 -1
package/dist/cloudflare.js +1 -1
package/dist/{hadars-DEBSYAQl.d.cts → hadars-mKu5txjW.d.cts} +93 -2
package/dist/{hadars-DEBSYAQl.d.ts → hadars-mKu5txjW.d.ts} +93 -2
package/dist/index.cjs +11 -8
package/dist/index.d.cts +1 -1
package/dist/index.d.ts +1 -1
package/dist/index.js +11 -8
package/dist/lambda.cjs +2 -2
package/dist/lambda.d.cts +1 -1
package/dist/lambda.d.ts +1 -1
package/dist/lambda.js +1 -1
package/dist/utils/Head.tsx +17 -8
package/dist/utils/clientScript.tsx +9 -0
package/index.ts +3 -0
package/package.json +1 -1
package/src/build.ts +29 -0
package/src/index.tsx +3 -0
package/src/source/context.ts +113 -0
package/src/source/graphiql.ts +96 -0
package/src/source/inference.ts +188 -0
package/src/source/runner.ts +114 -0
package/src/source/store.ts +48 -0
package/src/static.ts +106 -0
package/src/types/hadars.ts +91 -1
package/src/utils/Head.tsx +17 -8
package/src/utils/clientScript.tsx +9 -0
package/src/utils/response.tsx +4 -3

package/src/source/graphiql.ts ADDED Viewed

@@ -0,0 +1,96 @@
+/**
+ * GraphiQL dev endpoint — serves the GraphiQL IDE at GET /__hadars/graphql
+ * and a JSON GraphQL API at POST /__hadars/graphql.
+ *
+ * Only mounted in dev mode when config.sources is present.
+ */
+import type { GraphQLExecutor } from '../types/hadars';
+export const GRAPHQL_PATH = '/__hadars/graphql';
+// GraphiQL HTML shell — UMD bundles from unpkg (dev-only).
+// Using UMD avoids ES module peer-dependency conflicts (CodeMirror, etc.)
+// and matches the official GraphiQL standalone embedding guide.
+const GRAPHIQL_HTML = `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>GraphiQL — hadars</title>
+  <style>
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+    body { height: 100vh; overflow: hidden; }
+    #graphiql { height: 100vh; }
+  </style>
+  <link rel="stylesheet" href="https://unpkg.com/graphiql@3/graphiql.min.css" />
+</head>
+<body>
+  <div id="graphiql"></div>
+  <script src="https://unpkg.com/react@18/umd/react.production.min.js" crossorigin></script>
+  <script src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js" crossorigin></script>
+  <script src="https://unpkg.com/graphiql@3/graphiql.min.js" crossorigin></script>
+  <script>
+    const root = ReactDOM.createRoot(document.getElementById('graphiql'));
+    root.render(
+      React.createElement(GraphiQL, {
+        fetcher: GraphiQL.createFetcher({ url: '${GRAPHQL_PATH}' }),
+      })
+    );
+  </script>
+</body>
+</html>`;
+/**
+ * Returns a fetch handler that covers GET and POST for `/__hadars/graphql`.
+ * Returns `undefined` for any other path so callers can chain normally.
+ */
+export function createGraphiqlHandler(
+    executor: GraphQLExecutor,
+): (req: Request) => Promise<Response | undefined> {
+    return async (req: Request): Promise<Response | undefined> => {
+        const url = new URL(req.url);
+        if (url.pathname !== GRAPHQL_PATH) return undefined;
+        // GET — serve GraphiQL IDE
+        if (req.method === 'GET') {
+            return new Response(GRAPHIQL_HTML, {
+                headers: { 'Content-Type': 'text/html; charset=utf-8' },
+            });
+        }
+        // POST — execute GraphQL query
+        if (req.method === 'POST') {
+            let body: { query?: string; variables?: Record<string, unknown>; operationName?: string };
+            try {
+                body = await req.json();
+            } catch {
+                return new Response(JSON.stringify({ errors: [{ message: 'Invalid JSON body' }] }), {
+                    status: 400,
+                    headers: { 'Content-Type': 'application/json' },
+                });
+            }
+            if (!body.query) {
+                return new Response(JSON.stringify({ errors: [{ message: 'Missing "query" field' }] }), {
+                    status: 400,
+                    headers: { 'Content-Type': 'application/json' },
+                });
+            }
+            try {
+                const result = await executor(body.query, body.variables);
+                return new Response(JSON.stringify(result), {
+                    headers: { 'Content-Type': 'application/json' },
+                });
+            } catch (err) {
+                return new Response(JSON.stringify({ errors: [{ message: (err as Error).message }] }), {
+                    status: 500,
+                    headers: { 'Content-Type': 'application/json' },
+                });
+            }
+        }
+        return new Response('Method Not Allowed', { status: 405 });
+    };
+}

package/src/source/inference.ts ADDED Viewed

@@ -0,0 +1,188 @@
+/**
+ * Schema inference — builds a GraphQL schema from the node store automatically,
+ * just like Gatsby does. Uses graphql-js (must be installed in the user's project).
+ *
+ * Dynamically imports graphql so hadars itself does not depend on it.
+ */
+import type { NodeStore } from './store';
+import type { GraphQLExecutor } from '../types/hadars';
+// ── Primitive inference ────────────────────────────────────────────────────────
+type ScalarName = 'String' | 'Int' | 'Float' | 'Boolean' | 'ID';
+function inferScalar(value: unknown): ScalarName {
+    if (typeof value === 'boolean') return 'Boolean';
+    if (typeof value === 'number') return Number.isInteger(value) ? 'Int' : 'Float';
+    return 'String';
+}
+interface FieldShape {
+    type: string;   // e.g. "String", "Int", "Boolean", "[String]", "InternalType"
+    nullable: boolean;
+}
+function inferFieldShape(value: unknown, seenTypes: Set<string>): FieldShape {
+    if (value === null || value === undefined) {
+        return { type: 'String', nullable: true };
+    }
+    if (Array.isArray(value)) {
+        const inner = value.length > 0
+            ? inferFieldShape(value[0], seenTypes)
+            : { type: 'String', nullable: true };
+        return { type: `[${inner.type}]`, nullable: true };
+    }
+    if (typeof value === 'object') {
+        // nested object — we don't recurse deeply for now; use JSON string
+        return { type: 'String', nullable: true };
+    }
+    return { type: inferScalar(value), nullable: true };
+}
+// ── Schema string builder ──────────────────────────────────────────────────────
+const INTERNAL_FIELDS = new Set(['id', 'internal', '__typename', 'parent', 'children']);
+/** Scalar GraphQL types that are safe to use as lookup filter arguments. */
+const FILTERABLE_SCALARS = new Set(['String', 'Int', 'Float', 'Boolean', 'ID']);
+interface InferredField {
+    name: string;
+    type: string;
+    /** True when the base type is a plain scalar (not a list/object). */
+    filterable: boolean;
+}
+function buildTypeFields(nodes: readonly Record<string, unknown>[]): InferredField[] {
+    const fieldMap = new Map<string, InferredField>();
+    for (const node of nodes) {
+        for (const [key, val] of Object.entries(node)) {
+            if (INTERNAL_FIELDS.has(key)) continue;
+            if (fieldMap.has(key)) continue;
+            const { type } = inferFieldShape(val, new Set());
+            fieldMap.set(key, {
+                name: key,
+                type,
+                filterable: FILTERABLE_SCALARS.has(type),
+            });
+        }
+    }
+    return Array.from(fieldMap.values());
+}
+function buildTypeSDL(typeName: string, fields: InferredField[]): string {
+    const lines = [
+        '  id: ID!',
+        ...fields.map(f => `  ${f.name}: ${f.type}`),
+    ];
+    return `type ${typeName} {\n${lines.join('\n')}\n}`;
+}
+// ── Query builder ──────────────────────────────────────────────────────────────
+/** Build allXxx / xxx query names from a type name, matching Gatsby's convention. */
+function queryNames(typeName: string) {
+    const lower = typeName.charAt(0).toLowerCase() + typeName.slice(1);
+    return { single: lower, all: `all${typeName}` };
+}
+/**
+ * Build the SDL argument list for the single-item query.
+ * Includes `id` plus every filterable scalar field so callers can look up
+ * nodes by any natural key (e.g. slug, email) without knowing the hashed id.
+ * The resolver returns the first node where ALL supplied arguments match.
+ */
+function buildSingleArgs(fields: InferredField[]): string {
+    const args = [
+        'id: ID',
+        ...fields.filter(f => f.filterable && f.name !== 'id').map(f => `${f.name}: ${f.type}`),
+    ];
+    return args.join(', ');
+}
+// ── Public API ─────────────────────────────────────────────────────────────────
+/**
+ * Build a GraphQL executor backed by the node store.
+ *
+ * Returns null if graphql-js is not installed — in that case the caller should
+ * surface a clear error message asking the user to install `graphql`.
+ */
+export async function buildSchemaExecutor(
+    store: NodeStore,
+): Promise<GraphQLExecutor | null> {
+    // graphql is an optional peer dependency installed in the user's project,
+    // not in hadars itself. Resolve it from process.cwd() so Node.js finds it
+    // in the user's node_modules rather than the CLI's own node_modules.
+    let gql: any;
+    try {
+        const { createRequire } = await import('node:module');
+        const projectRequire = createRequire(process.cwd() + '/package.json');
+        const graphqlPath = projectRequire.resolve('graphql');
+        gql = await import(graphqlPath);
+    } catch {
+        return null;
+    }
+    const { buildSchema, graphql } = gql;
+    const types = store.getTypes();
+    if (types.length === 0) {
+        // Empty store — return a no-op executor with a dummy schema
+        const schema = buildSchema('type Query { _empty: String }');
+        return (query, variables) => graphql({ schema, source: query, variableValues: variables });
+    }
+    // Infer field shapes once per type — reused for both the SDL and resolvers.
+    const typeFields = new Map(
+        types.map(typeName => {
+            const nodes = store.getNodesByType(typeName) as Record<string, unknown>[];
+            return [typeName, buildTypeFields(nodes)] as const;
+        })
+    );
+    const typeSDLs = types.map(typeName =>
+        buildTypeSDL(typeName, typeFields.get(typeName)!)
+    );
+    const queryFields = types.map(typeName => {
+        const { single, all } = queryNames(typeName);
+        const args = buildSingleArgs(typeFields.get(typeName)!);
+        return [
+            `  ${single}(${args}): ${typeName}`,
+            `  ${all}: [${typeName}!]!`,
+        ].join('\n');
+    });
+    const sdl = [
+        ...typeSDLs,
+        `type Query {\n${queryFields.join('\n')}\n}`,
+    ].join('\n\n');
+    let schema: any;
+    try {
+        schema = buildSchema(sdl);
+    } catch (err) {
+        throw new Error(`[hadars] Failed to build GraphQL schema from node store: ${(err as Error).message}`);
+    }
+    // Build root resolver map
+    const rootValue: Record<string, unknown> = {};
+    for (const typeName of types) {
+        const { single, all } = queryNames(typeName);
+        rootValue[all] = () => store.getNodesByType(typeName);
+        // Single-item resolver: return the first node matching ALL supplied args.
+        rootValue[single] = (args: Record<string, unknown>) => {
+            const nodes = store.getNodesByType(typeName) as Record<string, unknown>[];
+            return nodes.find(node =>
+                Object.entries(args).every(([k, v]) => v === undefined || node[k] === v)
+            ) ?? null;
+        };
+    }
+    return (query, variables) =>
+        graphql({ schema, rootValue, source: query, variableValues: variables }) as any;
+}

package/src/source/runner.ts ADDED Viewed

@@ -0,0 +1,114 @@
+/**
+ * Source plugin runner — calls each plugin's `sourceNodes` with a Gatsby-compatible
+ * context object, then returns a populated node store ready for schema inference.
+ *
+ * Handles async plugins (e.g. gatsby-source-filesystem) that return immediately
+ * and create nodes later via file-system events:
+ *  1. Wait for nodes to stop arriving ("settle").
+ *  2. Emit BOOTSTRAP_FINISHED on the plugin's emitter.
+ *  3. Wait for any post-bootstrap nodes to settle.
+ */
+import { EventEmitter } from 'node:events';
+import { createRequire } from 'node:module';
+import { NodeStore } from './store';
+import { makeGatsbyContext } from './context';
+import type { HadarsSourceEntry } from '../types/hadars';
+/** ms without a new createNode call before we consider the plugin settled. */
+const SETTLE_IDLE_MS = 300;
+/** Hard timeout — give up waiting after this many ms. */
+const SETTLE_TIMEOUT_MS = 10_000;
+/**
+ * Wait until no createNode call has been received for SETTLE_IDLE_MS,
+ * or until SETTLE_TIMEOUT_MS elapses, whichever comes first.
+ */
+function waitForSettle(getLastNodeTime: () => number): Promise<void> {
+    return new Promise(resolve => {
+        const deadline = Date.now() + SETTLE_TIMEOUT_MS;
+        const check = () => {
+            const idle = Date.now() - getLastNodeTime();
+            if (idle >= SETTLE_IDLE_MS || Date.now() >= deadline) {
+                resolve();
+            } else {
+                setTimeout(check, 50);
+            }
+        };
+        setTimeout(check, SETTLE_IDLE_MS);
+    });
+}
+export async function runSources(
+    sources: HadarsSourceEntry[],
+): Promise<NodeStore> {
+    const store = new NodeStore();
+    for (const entry of sources) {
+        const { resolve, options = {} } = entry;
+        let mod: { sourceNodes?: (ctx: any, opts?: any) => Promise<void> | void };
+        if (typeof resolve === 'string') {
+            // Resolve from the user's project directory so the package is found
+            // in their node_modules, not in the CLI's own node_modules.
+            const projectRequire = createRequire(process.cwd() + '/package.json');
+            // Gatsby plugins export sourceNodes from gatsby-node.js, not their
+            // package main. Try gatsby-node.js first, fall back to main entry.
+            let pkgPath: string;
+            try {
+                pkgPath = projectRequire.resolve(`${resolve}/gatsby-node`);
+            } catch {
+                pkgPath = projectRequire.resolve(resolve);
+            }
+            mod = await import(pkgPath);
+        } else {
+            mod = resolve as any;
+        }
+        if (typeof mod.sourceNodes !== 'function') {
+            const name = typeof resolve === 'string' ? resolve : '(module)';
+            console.warn(`[hadars] source plugin ${name} does not export sourceNodes — skipping`);
+            continue;
+        }
+        const pluginName = typeof resolve === 'string' ? resolve : 'hadars-source';
+        // Track the last time createNode was called so we can detect settling.
+        let lastNodeTime = Date.now();
+        const trackingStore = new Proxy(store, {
+            get(target, prop) {
+                if (prop === 'createNode') {
+                    return (node: any) => {
+                        lastNodeTime = Date.now();
+                        return target.createNode(node);
+                    };
+                }
+                return (target as any)[prop];
+            },
+        });
+        // Real EventEmitter — plugins subscribe to BOOTSTRAP_FINISHED on this.
+        const emitter = new EventEmitter();
+        const ctx = makeGatsbyContext(trackingStore, pluginName, options, emitter);
+        try {
+            await mod.sourceNodes(ctx, options);
+        } catch (err) {
+            throw new Error(
+                `[hadars] source plugin "${pluginName}" threw during sourceNodes: ${(err as Error).message}`,
+            );
+        }
+        // Phase 1: wait for async initial-scan nodes (e.g. chokidar ready → createFileNode).
+        await waitForSettle(() => lastNodeTime);
+        // Signal Gatsby lifecycle end — some plugins create additional nodes here.
+        emitter.emit('BOOTSTRAP_FINISHED');
+        // Phase 2: wait for any post-bootstrap nodes to settle.
+        await waitForSettle(() => lastNodeTime);
+    }
+    return store;
+}

package/src/source/store.ts ADDED Viewed

@@ -0,0 +1,48 @@
+/**
+ * In-memory node store — the equivalent of Gatsby's internal node database.
+ * Source plugins write nodes here via the context shim; the schema inferencer
+ * reads them to build the GraphQL schema.
+ */
+export interface HadarsNode {
+    id: string;
+    /** Gatsby convention: the node type string, e.g. "MarkdownRemark", "ContentfulBlogPost". */
+    internal: {
+        type: string;
+        contentDigest: string;
+        content?: string;
+        mediaType?: string;
+        description?: string;
+    };
+    [key: string]: unknown;
+}
+export class NodeStore {
+    private byId   = new Map<string, HadarsNode>();
+    private byType = new Map<string, HadarsNode[]>();
+    createNode(node: HadarsNode): void {
+        this.byId.set(node.id, node);
+        const list = this.byType.get(node.internal.type) ?? [];
+        // Replace existing node with same id if present
+        const idx = list.findIndex(n => n.id === node.id);
+        if (idx >= 0) list[idx] = node; else list.push(node);
+        this.byType.set(node.internal.type, list);
+    }
+    getNode(id: string): HadarsNode | undefined {
+        return this.byId.get(id);
+    }
+    getNodes(): HadarsNode[] {
+        return Array.from(this.byId.values());
+    }
+    getNodesByType(type: string): HadarsNode[] {
+        return this.byType.get(type) ?? [];
+    }
+    getTypes(): string[] {
+        return Array.from(this.byType.keys());
+    }
+}

package/src/static.ts ADDED Viewed

@@ -0,0 +1,106 @@
+/**
+ * Static site export core — rendering and file I/O.
+ *
+ * Imported by cli-lib.ts (bundled into dist/cli.js via esbuild) and by tests.
+ * Has no dependency on the rspack build pipeline — only SSR utilities.
+ */
+import { cp, mkdir, writeFile } from 'node:fs/promises';
+import { join, dirname, basename } from 'node:path';
+import { parseRequest } from './utils/request';
+import { getReactResponse, buildHeadHtml } from './utils/response';
+import { buildSsrHtml, makePrecontentHtmlGetter } from './utils/ssrHandler';
+import type { HadarsEntryModule, HadarsStaticContext, GraphQLExecutor } from './types/hadars';
+export interface StaticRenderResult {
+    /** URL paths that were successfully rendered. */
+    rendered: string[];
+    /** Paths that failed, with the caught error. */
+    errors: Array<{ path: string; error: Error }>;
+}
+/**
+ * Pre-renders a list of URL paths to HTML files and copies static assets.
+ *
+ * Pages are rendered serially — `getReactResponse` writes to
+ * `globalThis.__hadarsUnsuspend / __hadarsContext` which are not re-entrant-safe.
+ */
+export async function renderStaticSite(opts: {
+    ssrModule:   HadarsEntryModule<any>;
+    htmlSource:  string;
+    staticSrc:   string;
+    paths:       string[];
+    outputDir:   string;
+    graphql?:    GraphQLExecutor;
+}): Promise<StaticRenderResult> {
+    const { ssrModule, htmlSource, staticSrc, paths, outputDir } = opts;
+    const staticCtx: HadarsStaticContext = {
+        graphql: opts.graphql ?? (() => Promise.reject(
+            new Error('[hadars] No graphql executor configured. Add a `graphql` function to your hadars.config.'),
+        )),
+    };
+    const getPrecontentHtml = makePrecontentHtmlGetter(Promise.resolve(htmlSource));
+    await mkdir(outputDir, { recursive: true });
+    const rendered: string[] = [];
+    const errors: Array<{ path: string; error: Error }> = [];
+    for (const urlPath of paths) {
+        try {
+            const req = parseRequest(new Request('http://localhost' + urlPath));
+            const { head, getAppBody, finalize } = await getReactResponse(req, {
+                document: {
+                    body:          ssrModule.default as any,
+                    getInitProps:  ssrModule.getInitProps,
+                    getFinalProps: ssrModule.getFinalProps,
+                },
+                staticCtx,
+            });
+            const bodyHtml        = await getAppBody();
+            const { clientProps } = await finalize();
+            const headHtml        = buildHeadHtml(head);
+            // Inject a flag so the client knows it's a static export and should
+            // fetch index.json sidecars directly instead of hitting a live server.
+            const staticClientProps = { ...clientProps, __hadarsStatic: true };
+            const html = await buildSsrHtml(bodyHtml, staticClientProps, headHtml, getPrecontentHtml);
+            // '/'      → <outputDir>/index.html
+            // '/about' → <outputDir>/about/index.html
+            const cleanPath = urlPath.replace(/\/$/, '');
+            const pageDir   = cleanPath === '' ? outputDir : join(outputDir, cleanPath);
+            await mkdir(pageDir, { recursive: true });
+            await writeFile(join(pageDir, 'index.html'), html, 'utf-8');
+            // Write a JSON sidecar so useServerData can hydrate on client-side
+            // navigation without a live server. The format matches the live
+            // server's Accept: application/json response: { serverData: {...} }.
+            const serverData = (staticClientProps as any).__serverData ?? {};
+            await writeFile(
+                join(pageDir, 'index.json'),
+                JSON.stringify({ serverData }),
+                'utf-8',
+            );
+            rendered.push(urlPath);
+        } catch (err: any) {
+            errors.push({
+                path:  urlPath,
+                error: err instanceof Error ? err : new Error(String(err)),
+            });
+        }
+    }
+    // Copy .hadars/static/ → <outputDir>/static/, excluding the SSR template.
+    const staticDest = join(outputDir, 'static');
+    await mkdir(staticDest, { recursive: true });
+    await cp(staticSrc, staticDest, {
+        recursive: true,
+        filter: (src: string) => basename(src) !== 'out.html',
+    });
+    return { rendered, errors };
+}

package/src/types/hadars.ts CHANGED Viewed

@@ -1,6 +1,35 @@
 import type { LinkHTMLAttributes, MetaHTMLAttributes, ScriptHTMLAttributes, StyleHTMLAttributes } from "react";
-export type HadarsGetInitialProps<T extends {}> = (req: HadarsRequest) => Promise<T> | T;
+/**
+ * In-process GraphQL executor passed to `getInitProps` and `paths` during
+ * `hadars export static`. Hadars is executor-agnostic — configure it in
+ * `hadars.config.ts` using any GraphQL library (e.g. `graphql-js`):
+ *
+ * ```ts
+ * import { graphql as gql, buildSchema } from 'graphql';
+ * const schema = buildSchema(`type Query { hello: String }`);
+ * const rootValue = { hello: () => 'world' };
+ *
+ * export default {
+ *   graphql: (query, variables) =>
+ *     gql({ schema, rootValue, source: query, variableValues: variables }),
+ * } satisfies HadarsOptions;
+ * ```
+ */
+export type GraphQLExecutor = (
+    query: string,
+    variables?: Record<string, unknown>,
+) => Promise<{ data?: any; errors?: ReadonlyArray<{ message: string }> }>;
+/**
+ * Context passed as the second argument to `getInitProps` and `paths`
+ * during `hadars export static`. Not present in dev/run mode.
+ */
+export interface HadarsStaticContext {
+    graphql: GraphQLExecutor;
+}
+export type HadarsGetInitialProps<T extends {}> = (req: HadarsRequest, ctx?: HadarsStaticContext) => Promise<T> | T;
 export type HadarsGetClientProps<T extends {}> = (props: T) => Promise<T> | T;
 export type HadarsGetFinalProps<T extends {}> = (props: HadarsProps<T>) => Promise<T> | T;
 export type HadarsApp<T extends {}> = React.FC<HadarsProps<T>>;
@@ -180,6 +209,67 @@ export interface HadarsOptions {
      */
     cache?: (req: HadarsRequest) => { key: string; ttl?: number } | null | undefined
                                   | Promise<{ key: string; ttl?: number } | null | undefined>;
+    /**
+     * Static export path list. Required for `hadars export static`.
+     *
+     * Return an array of URL paths (e.g. `['/', '/about', '/blog/hello']`) that
+     * should be pre-rendered to HTML files. May be async.
+     *
+     * @example
+     * paths: () => ['/', '/about', '/contact']
+     *
+     * @example
+     * paths: async () => {
+     *   const posts = await fetchBlogPosts();
+     *   return ['/', ...posts.map(p => `/blog/${p.slug}`)];
+     * }
+     */
+    /**
+     * In-process GraphQL executor. Supply this to use the GraphQL data layer
+     * in `paths` and `getInitProps` during `hadars export static`.
+     * Has no effect in `dev` / `run` mode.
+     */
+    graphql?: GraphQLExecutor;
+    paths?: (ctx: HadarsStaticContext) => Promise<string[]> | string[];
+    /**
+     * Gatsby-compatible source plugins to run before `hadars export static`.
+     *
+     * Each entry mirrors Gatsby's `gatsby-config.js` plugin object format:
+     * `{ resolve: 'gatsby-source-contentful', options: { spaceId: '...', accessToken: '...' } }`
+     *
+     * The plugin must export a `sourceNodes` function with the standard Gatsby API.
+     * Hadars provides a thin shim covering the most-used surface:
+     * `actions.createNode`, `createNodeId`, `createContentDigest`, `cache`, `reporter`,
+     * `getNode`, `getNodes`, `getNodesByType`.
+     *
+     * After all sources have run, hadars auto-generates a GraphQL schema from the
+     * collected nodes and makes it available via `config.graphql` in `getInitProps`
+     * and `paths`. Requires `graphql` to be installed in the project.
+     *
+     * @example
+     * sources: [
+     *   {
+     *     resolve: 'gatsby-source-filesystem',
+     *     options: { name: 'posts', path: './content/posts' },
+     *   },
+     * ]
+     */
+    sources?: HadarsSourceEntry[];
+}
+/**
+ * A Gatsby-compatible source plugin entry, matching the format used in
+ * `gatsby-config.js` / `gatsby-config.ts`.
+ */
+export interface HadarsSourceEntry {
+    /**
+     * Package name (e.g. `'gatsby-source-contentful'`) or a pre-imported module
+     * object that exports `sourceNodes`. Using a module object lets you pass
+     * local source plugins without publishing them to npm.
+     */
+    resolve: string | { sourceNodes?: (ctx: any, opts?: any) => Promise<void> | void };
+    /** Plugin options forwarded as the second argument to `sourceNodes`. */
+    options?: Record<string, unknown>;
 }