hadars 0.2.1 → 0.2.2-rc.0

package/dist/{hadars-DEBSYAQl.d.cts → hadars-mKu5txjW.d.cts}

@@ -1,4 +1,33 @@
-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;
+ * ```
+ */
+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.
+ */
+interface HadarsStaticContext {
+    graphql: GraphQLExecutor;
+}
+type HadarsGetInitialProps<T extends {}> = (req: HadarsRequest, ctx?: HadarsStaticContext) => Promise<T> | T;
 type HadarsGetClientProps<T extends {}> = (props: T) => Promise<T> | T;
 type HadarsGetFinalProps<T extends {}> = (props: HadarsProps<T>) => Promise<T> | T;
 type HadarsApp<T extends {}> = React.FC<HadarsProps<T>>;
@@ -148,6 +177,68 @@ interface HadarsOptions {
         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`.
+ */
+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>;
 }
 type SwcPluginItem = string | [string, Record<string, unknown>] | {
     path: string;
@@ -161,4 +252,4 @@ interface HadarsRequest extends Request {
     cookies: Record<string, string>;
 }
 
-export type { HadarsEntryModule as H, HadarsOptions as a, HadarsApp as b, HadarsGetClientProps as c, HadarsGetFinalProps as d, HadarsGetInitialProps as e, HadarsProps as f, HadarsRequest as g };
+export type { GraphQLExecutor as G, HadarsEntryModule as H, HadarsOptions as a, HadarsApp as b, HadarsGetClientProps as c, HadarsGetFinalProps as d, HadarsGetInitialProps as e, HadarsProps as f, HadarsRequest as g, HadarsSourceEntry as h, HadarsStaticContext as i };

package/dist/{hadars-DEBSYAQl.d.ts → hadars-mKu5txjW.d.ts}

@@ -1,4 +1,33 @@
-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;
+ * ```
+ */
+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.
+ */
+interface HadarsStaticContext {
+    graphql: GraphQLExecutor;
+}
+type HadarsGetInitialProps<T extends {}> = (req: HadarsRequest, ctx?: HadarsStaticContext) => Promise<T> | T;
 type HadarsGetClientProps<T extends {}> = (props: T) => Promise<T> | T;
 type HadarsGetFinalProps<T extends {}> = (props: HadarsProps<T>) => Promise<T> | T;
 type HadarsApp<T extends {}> = React.FC<HadarsProps<T>>;
@@ -148,6 +177,68 @@ interface HadarsOptions {
         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`.
+ */
+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>;
 }
 type SwcPluginItem = string | [string, Record<string, unknown>] | {
     path: string;
@@ -161,4 +252,4 @@ interface HadarsRequest extends Request {
     cookies: Record<string, string>;
 }
 
-export type { HadarsEntryModule as H, HadarsOptions as a, HadarsApp as b, HadarsGetClientProps as c, HadarsGetFinalProps as d, HadarsGetInitialProps as e, HadarsProps as f, HadarsRequest as g };
+export type { GraphQLExecutor as G, HadarsEntryModule as H, HadarsOptions as a, HadarsApp as b, HadarsGetClientProps as c, HadarsGetFinalProps as d, HadarsGetInitialProps as e, HadarsProps as f, HadarsRequest as g, HadarsSourceEntry as h, HadarsStaticContext as i };

package/dist/index.cjs

@@ -226,14 +226,17 @@ function useServerData(key, fn) {
       pendingDataFetch.set(pathKey, p);
       queueMicrotask(async () => {
         try {
-          const res = await fetch(pathKey, {
-            headers: { "Accept": "application/json" }
-          });
-          if (res.ok) {
-            const json = await res.json();
-            for (const [k, v] of Object.entries(json.serverData ?? {})) {
-              clientServerDataCache.set(k, v);
-            }
+          let json = null;
+          if (globalThis.__hadarsStatic) {
+            const sidecarUrl = pathKey.replace(/\/$/, "") + "/index.json";
+            const res = await fetch(sidecarUrl).catch(() => null);
+            if (res?.ok) json = await res.json().catch(() => null);
+          } else {
+            const res = await fetch(pathKey, { headers: { "Accept": "application/json" } });
+            if (res.ok) json = await res.json();
+          }
+          for (const [k, v] of Object.entries(json?.serverData ?? {})) {
+            clientServerDataCache.set(k, v);
           }
         } finally {
           fetchedPaths.add(pathKey);

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-export { b as HadarsApp, H as HadarsEntryModule, c as HadarsGetClientProps, d as HadarsGetFinalProps, e as HadarsGetInitialProps, a as HadarsOptions, f as HadarsProps, g as HadarsRequest } from './hadars-DEBSYAQl.cjs';
+export { G as GraphQLExecutor, b as HadarsApp, H as HadarsEntryModule, c as HadarsGetClientProps, d as HadarsGetFinalProps, e as HadarsGetInitialProps, a as HadarsOptions, f as HadarsProps, g as HadarsRequest, h as HadarsSourceEntry, i as HadarsStaticContext } from './hadars-mKu5txjW.cjs';
 import React from 'react';
 
 /** Call this before hydrating to seed the client cache from the server's data.

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { b as HadarsApp, H as HadarsEntryModule, c as HadarsGetClientProps, d as HadarsGetFinalProps, e as HadarsGetInitialProps, a as HadarsOptions, f as HadarsProps, g as HadarsRequest } from './hadars-DEBSYAQl.js';
+export { G as GraphQLExecutor, b as HadarsApp, H as HadarsEntryModule, c as HadarsGetClientProps, d as HadarsGetFinalProps, e as HadarsGetInitialProps, a as HadarsOptions, f as HadarsProps, g as HadarsRequest, h as HadarsSourceEntry, i as HadarsStaticContext } from './hadars-mKu5txjW.js';
 import React from 'react';
 
 /** Call this before hydrating to seed the client cache from the server's data.

package/dist/index.js

@@ -187,14 +187,17 @@ function useServerData(key, fn) {
       pendingDataFetch.set(pathKey, p);
       queueMicrotask(async () => {
         try {
-          const res = await fetch(pathKey, {
-            headers: { "Accept": "application/json" }
-          });
-          if (res.ok) {
-            const json = await res.json();
-            for (const [k, v] of Object.entries(json.serverData ?? {})) {
-              clientServerDataCache.set(k, v);
-            }
+          let json = null;
+          if (globalThis.__hadarsStatic) {
+            const sidecarUrl = pathKey.replace(/\/$/, "") + "/index.json";
+            const res = await fetch(sidecarUrl).catch(() => null);
+            if (res?.ok) json = await res.json().catch(() => null);
+          } else {
+            const res = await fetch(pathKey, { headers: { "Accept": "application/json" } });
+            if (res.ok) json = await res.json();
+          }
+          for (const [k, v] of Object.entries(json?.serverData ?? {})) {
+            clientServerDataCache.set(k, v);
           }
         } finally {
           fetchedPaths.add(pathKey);

package/dist/lambda.cjs

@@ -1226,7 +1226,7 @@ var getReactResponse = async (req, opts) => {
     head: { title: "Hadars App", meta: {}, link: {}, style: {}, script: {}, status: 200 }
   };
   let props = {
-    ...getInitProps ? await getInitProps(req) : {},
+    ...getInitProps ? await getInitProps(req, opts.staticCtx) : {},
     location: req.location,
     context
   };
@@ -1252,7 +1252,7 @@ var getReactResponse = async (req, opts) => {
     }
   };
   const finalize = async () => {
-    const { context: _, ...restProps } = getFinalProps ? await getFinalProps(props) : props;
+    const restProps = getFinalProps ? await getFinalProps(props) : props;
     const serverData = {};
     let hasServerData = false;
     for (const [key, entry] of unsuspend.cache) {

package/dist/lambda.d.cts

@@ -1,4 +1,4 @@
-import { H as HadarsEntryModule, a as HadarsOptions } from './hadars-DEBSYAQl.cjs';
+import { H as HadarsEntryModule, a as HadarsOptions } from './hadars-mKu5txjW.cjs';
 
 /**
  * AWS Lambda adapter for hadars.

package/dist/lambda.d.ts

@@ -1,4 +1,4 @@
-import { H as HadarsEntryModule, a as HadarsOptions } from './hadars-DEBSYAQl.js';
+import { H as HadarsEntryModule, a as HadarsOptions } from './hadars-mKu5txjW.js';
 
 /**
  * AWS Lambda adapter for hadars.

package/dist/lambda.js

@@ -6,7 +6,7 @@ import {
   getReactResponse,
   makePrecontentHtmlGetter,
   parseRequest
-} from "./chunk-HWOLYLPF.js";
+} from "./chunk-H72BZXOA.js";
 import "./chunk-LY5MTHFV.js";
 import "./chunk-OS3V4CPN.js";
 

package/dist/utils/Head.tsx

@@ -246,14 +246,23 @@ export function useServerData<T>(key: string | string[], fn: () => Promise<T> |
             // render is registered against the same deferred before the fetch starts.
             queueMicrotask(async () => {
                 try {
-                    const res = await fetch(pathKey, {
-                        headers: { 'Accept': 'application/json' },
-                    });
-                    if (res.ok) {
-                        const json = await res.json() as { serverData: Record<string, unknown> };
-                        for (const [k, v] of Object.entries(json.serverData ?? {})) {
-                            clientServerDataCache.set(k, v);
-                        }
+                    let json: { serverData: Record<string, unknown> } | null = null;
+
+                    if ((globalThis as any).__hadarsStatic) {
+                        // Static export: the __hadarsStatic flag was embedded in the
+                        // page by `hadars export static`. Fetch the pre-generated
+                        // index.json sidecar directly — no live SSR server exists.
+                        const sidecarUrl = pathKey.replace(/\/$/, '') + '/index.json';
+                        const res = await fetch(sidecarUrl).catch(() => null);
+                        if (res?.ok) json = await res.json().catch(() => null);
+                    } else {
+                        // Live server: request the current URL with Accept: application/json.
+                        const res = await fetch(pathKey, { headers: { 'Accept': 'application/json' } });
+                        if (res.ok) json = await res.json();
+                    }
+
+                    for (const [k, v] of Object.entries(json?.serverData ?? {})) {
+                        clientServerDataCache.set(k, v);
                     }
                 } finally {
                     fetchedPaths.add(pathKey);

package/dist/utils/clientScript.tsx

@@ -22,6 +22,15 @@ const getProps = () => {
 const main = async () => {
     let props = getProps();
 
+    // Extract the static-export flag before it reaches user code. When set,
+    // useServerData fetches index.json sidecars directly on client navigation
+    // instead of requesting the live SSR server with Accept: application/json.
+    if ((props as any).__hadarsStatic) {
+        (globalThis as any).__hadarsStatic = true;
+        const { __hadarsStatic: _, ...rest } = props as any;
+        props = rest;
+    }
+
     // Seed the useServerData client cache from server-resolved values before
     // hydration so that hooks return the same data on the first render.
     if (props.__serverData && typeof props.__serverData === 'object') {

package/index.ts

@@ -10,5 +10,8 @@ export type {
     HadarsGetClientProps,
     HadarsEntryModule,
     HadarsApp,
+    HadarsStaticContext,
+    GraphQLExecutor,
+    HadarsSourceEntry,
 } from "./src/types/hadars";
 export { HadarsHead, HadarsContext, loadModule } from "./src/index";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hadars",
-  "version": "0.2.1",
+  "version": "0.2.2-rc.0",
   "description": "Minimal SSR framework for React — rspack, HMR, TypeScript, Bun/Node/Deno",
   "module": "./dist/index.js",
   "type": "module",

package/src/build.ts

@@ -20,6 +20,9 @@ import {
     buildSsrResponse, makePrecontentHtmlGetter,
     type CacheFetchHandler, createRenderCache,
 } from './utils/ssrHandler';
+import { runSources } from './source/runner';
+import { buildSchemaExecutor } from './source/inference';
+import { createGraphiqlHandler, GRAPHQL_PATH } from './source/graphiql';
 
 /**
  * Reads an HTML template, processes any `<style>` blocks through PostCSS
@@ -295,6 +298,26 @@ export const dev = async (options: HadarsRuntimeOptions) => {
     const handleWS = upgradeHandler(options);
     const handler = options.fetch;
 
+    // Run source plugins and set up GraphiQL if config.sources is present.
+    let handleGraphiql: ((req: Request) => Promise<Response | undefined>) | null = null;
+    let devStaticCtx: { graphql: import('./types/hadars').GraphQLExecutor } | undefined;
+    if (options.sources && options.sources.length > 0) {
+        console.log(`[hadars] Running ${options.sources.length} source plugin(s)…`);
+        try {
+            const store = await runSources(options.sources);
+            const executor = await buildSchemaExecutor(store);
+            if (executor) {
+                devStaticCtx = { graphql: executor };
+                handleGraphiql = createGraphiqlHandler(executor);
+                console.log(`[hadars] GraphiQL available at http://localhost:${port}${GRAPHQL_PATH}`);
+            } else {
+                console.warn('[hadars] `graphql` package not found — GraphiQL disabled. Run: npm install graphql');
+            }
+        } catch (err) {
+            console.error('[hadars] Source plugin error:', err);
+        }
+    }
+
     const entry = pathMod.resolve(__dirname, options.entry);
     const hmrPort = options.hmrPort ?? port + 1;
 
@@ -491,6 +514,11 @@ export const dev = async (options: HadarsRuntimeOptions) => {
         }
         if (handleWS && handleWS(request, ctx)) return undefined;
 
+        if (handleGraphiql) {
+            const graphiqlRes = await handleGraphiql(req);
+            if (graphiqlRes) return graphiqlRes;
+        }
+
         const proxied = await handleProxy(request);
         if (proxied) return proxied;
 
@@ -525,6 +553,7 @@ export const dev = async (options: HadarsRuntimeOptions) => {
                     getInitProps,
                     getFinalProps,
                 },
+                staticCtx: devStaticCtx,
             });
 
             // Content negotiation: if the client only accepts JSON (client-side

package/src/index.tsx

@@ -7,6 +7,9 @@ export type {
     HadarsGetClientProps,
     HadarsEntryModule,
     HadarsApp,
+    HadarsStaticContext,
+    GraphQLExecutor,
+    HadarsSourceEntry,
 } from "./types/hadars";
 export { Head as HadarsHead, useServerData, initServerDataCache } from './utils/Head';
 

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,
+    };
+}