hadars 0.2.0 → 0.2.2-rc.0

package/src/index.tsx

@@ -7,11 +7,11 @@ export type {
     HadarsGetClientProps,
     HadarsEntryModule,
     HadarsApp,
+    HadarsStaticContext,
+    GraphQLExecutor,
+    HadarsSourceEntry,
 } from "./types/hadars";
 export { Head as HadarsHead, useServerData, initServerDataCache } from './utils/Head';
-import { AppProviderSSR, AppProviderCSR } from "./utils/Head";
-
-export const HadarsContext = typeof window === 'undefined' ? AppProviderSSR : AppProviderCSR;
 
 /**
  * Dynamically loads a module with target-aware behaviour:

package/src/source/context.ts

@@ -0,0 +1,113 @@
+/**
+ * Gatsby sourceNodes context shim.
+ *
+ * Gatsby passes a rich object to each source plugin's `sourceNodes` function.
+ * We implement the subset that the vast majority of CMS source plugins actually
+ * use so that existing plugins work without modification.
+ */
+
+import { createHash } from 'node:crypto';
+import { EventEmitter } from 'node:events';
+import type { NodeStore, HadarsNode } from './store';
+
+// ── Types ─────────────────────────────────────────────────────────────────────
+
+export interface GatsbyCache {
+    get(key: string): Promise<unknown>;
+    set(key: string, value: unknown): Promise<void>;
+}
+
+export interface GatsbyReporter {
+    info(message: string): void;
+    warn(message: string): void;
+    error(message: string, err?: Error): void;
+    panic(message: string, err?: Error): never;
+    activityTimer(name: string): { start(): void; end(): void };
+    verbose(message: string): void;
+}
+
+export interface GatsbyActions {
+    createNode(node: HadarsNode): void;
+    deleteNode(node: { id: string }): void;
+    touchNode(node: { id: string }): void;
+}
+
+export interface GatsbyNodeHelpers {
+    actions: GatsbyActions;
+    createNodeId(input: string): string;
+    createContentDigest(content: unknown): string;
+    getNode(id: string): HadarsNode | undefined;
+    getNodes(): HadarsNode[];
+    getNodesByType(type: string): HadarsNode[];
+    cache: GatsbyCache;
+    reporter: GatsbyReporter;
+    // Gatsby passes these; many plugins destructure but never call them
+    store: unknown;
+    emitter: unknown;
+    tracing: unknown;
+    schema: unknown;
+    /** Available in Gatsby 4+ — mostly unused by source plugins. */
+    parentSpan: unknown;
+}
+
+// ── Factory ───────────────────────────────────────────────────────────────────
+
+export function makeGatsbyContext(
+    store: NodeStore,
+    pluginName: string,
+    pluginOptions: Record<string, unknown> = {},
+    emitter: EventEmitter = new EventEmitter(),
+): GatsbyNodeHelpers {
+    // A simple in-memory cache per plugin instance
+    const cacheMap = new Map<string, unknown>();
+    const cache: GatsbyCache = {
+        get: (key) => Promise.resolve(cacheMap.get(key)),
+        set: (key, value) => { cacheMap.set(key, value); return Promise.resolve(); },
+    };
+
+    const reporter: GatsbyReporter = {
+        info:    (msg) => console.log(`[${pluginName}] ${msg}`),
+        warn:    (msg) => console.warn(`[${pluginName}] WARN: ${msg}`),
+        error:   (msg, err) => console.error(`[${pluginName}] ERROR: ${msg}`, err ?? ''),
+        panic:   (msg, err) => { console.error(`[${pluginName}] PANIC: ${msg}`, err ?? ''); process.exit(1); },
+        verbose: (msg) => { if (process.env.HADARS_VERBOSE) console.log(`[${pluginName}] ${msg}`); },
+        activityTimer: (name) => ({
+            start: () => { if (process.env.HADARS_VERBOSE) console.log(`[${pluginName}] ▶ ${name}`); },
+            end:   () => { if (process.env.HADARS_VERBOSE) console.log(`[${pluginName}] ■ ${name}`); },
+        }),
+        // Gatsby 4+ reporter extras — used by some plugins but safe to no-op
+        setErrorMap: () => {},
+        log:         (msg: string) => console.log(`[${pluginName}] ${msg}`),
+        success:     (msg: string) => console.log(`[${pluginName}] ✓ ${msg}`),
+    } as any;
+
+    const actions: GatsbyActions = {
+        createNode: (node) => store.createNode(node),
+        deleteNode: ({ id }) => {
+            // NodeStore doesn't expose delete — it's rarely needed by source plugins
+            // on first run, so we silently no-op. A full implementation would add
+            // store.deleteNode().
+        },
+        touchNode: () => { /* no-op — only relevant for Gatsby's caching layer */ },
+    };
+
+    return {
+        actions,
+        createNodeId:       (input) => createHash('sha256').update(pluginName + input).digest('hex'),
+        createContentDigest: (content) => {
+            const str = typeof content === 'string' ? content : JSON.stringify(content);
+            return createHash('md5').update(str).digest('hex');
+        },
+        getNode:         (id) => store.getNode(id),
+        getNodes:        ()   => store.getNodes(),
+        getNodesByType:  (t)  => store.getNodesByType(t),
+        cache,
+        reporter,
+        // Stubs for rarely-used Gatsby internals that plugins may destructure
+        store:      {},
+        emitter,
+        tracing:    { startSpan: () => ({ finish: () => {} }) },
+        schema:     {},
+        parentSpan: null,
+    };
+}

package/src/source/graphiql.ts

@@ -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

@@ -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

@@ -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

@@ -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/ssr-render-worker.ts

@@ -58,12 +58,14 @@ async function runFullLifecycle(serialReq: SerializableRequest) {
     let props: any = {
         ...(getInitProps ? await getInitProps(parsedReq) : {}),
         location: serialReq.location,
-        context,
     };
 
     // Create per-request cache for useServerData, active for all renders.
     const unsuspend = { cache: new Map<string, any>() };
     (globalThis as any).__hadarsUnsuspend = unsuspend;
+    // Expose the head context so HadarsHead can write into it without needing
+    // the user to manually wrap their App with HadarsContext.
+    (globalThis as any).__hadarsContext = context;
 
     // Single pass — component-level self-retry resolves all useServerData inline.
     // context.head is fully populated by the time renderToString returns.
@@ -72,6 +74,7 @@ async function runFullLifecycle(serialReq: SerializableRequest) {
         appHtml = await renderToString(createElement(Component, props));
     } finally {
         (globalThis as any).__hadarsUnsuspend = null;
+        (globalThis as any).__hadarsContext = null;
     }
     // Head is captured after the render — all components have run.
     const headHtml = buildHeadHtml(context.head);