@aihu/magna 0.2.5

package/README.md

@@ -0,0 +1,107 @@
+# @aihu/magna
+
+> **Aihu** — agentic discovery and interaction, for human purpose.
+
+aihu bridge for Magna GraphQL — dep-free fetch, resource composition, JWT relay
+
+Held-private workspace package. Not yet published to npm.
+
+> **Status:** Held private — not yet published to npm. See [v1.1 roadmap](../../docs/roadmap/SUMMARY.md) for ratification gating (e.g. RFC #56 live-binding for `@aihu/plugin` enforcement).
+
+<!-- BEGIN_HANDWRITTEN: prose -->
+# optional, build-time only — graceful-skips if absent
+bun add @aihu/magna-gqlmin
+```
+
+Full documentation: see `apps/docs/src/content/docs/packages/magna.md` (filed as A1 issue).
+<!-- END_HANDWRITTEN: prose -->
+
+## Install
+
+<!-- BEGIN_AUTOGEN: install -->
+<!-- regenerate: bun scripts/sync-readme.ts (also runs in pre-commit + CI) -->
+
+```bash
+npm install @aihu/magna
+# or
+bun add @aihu/magna
+```
+
+<sub><i>Auto-generated against `@aihu/magna@0.2.5`.</i></sub>
+
+<!-- END_AUTOGEN: install -->
+
+## Package facts
+
+<!-- BEGIN_AUTOGEN: stats -->
+<!-- regenerate: bun scripts/sync-readme.ts (also runs in pre-commit + CI) -->
+
+| | |
+|---|---|
+| **Version** | `0.2.5` |
+| **Tier** | B — Meta-framework — dep-free Magna GraphQL bridge (resources + JWT relay) |
+| **Bundle size** | 758 B (gz) — limit 1.8 KB |
+| **Published files** | 2 entries |
+| **License** | MIT |
+
+<sub><i>Auto-generated against `@aihu/magna@0.2.5`.</i></sub>
+
+<!-- END_AUTOGEN: stats -->
+
+## Exports
+
+<!-- BEGIN_AUTOGEN: exports -->
+<!-- regenerate: bun scripts/sync-readme.ts (also runs in pre-commit + CI) -->
+
+| Subpath | ESM | CJS |
+|---|---|---|
+| `.` | `./dist/index.js` | `—` |
+| `./codegen` | `./dist/codegen.js` | `—` |
+
+<sub><i>Auto-generated against `@aihu/magna@0.2.5`.</i></sub>
+
+<!-- END_AUTOGEN: exports -->
+
+## Dependencies
+
+<!-- BEGIN_AUTOGEN: deps -->
+<!-- regenerate: bun scripts/sync-readme.ts (also runs in pre-commit + CI) -->
+
+**Dependencies:**
+
+- `@aihu/signals` — `workspace:*`
+- `@aihu/plugin` — `workspace:*`
+- `@aihu/context` — `workspace:*`
+- `@aihu-plugin/data` — `workspace:*`
+
+**Optional dependencies (platform-specific):**
+
+- `@aihu/magna-gqlmin` — `^0.2.0`
+
+<sub><i>Auto-generated against `@aihu/magna@0.2.5`.</i></sub>
+
+<!-- END_AUTOGEN: deps -->
+
+## See also
+
+<!-- BEGIN_AUTOGEN: see-also -->
+<!-- regenerate: bun scripts/sync-readme.ts (also runs in pre-commit + CI) -->
+
+- [@aihu-plugin/data](../plugin-data)
+- [@aihu/server](../server)
+- [Aihu framework root](../../README.md)
+
+<sub><i>Auto-generated against `@aihu/magna@0.2.5`.</i></sub>
+
+<!-- END_AUTOGEN: see-also -->
+
+## License
+
+<!-- BEGIN_AUTOGEN: license -->
+<!-- regenerate: bun scripts/sync-readme.ts (also runs in pre-commit + CI) -->
+
+MIT — see [LICENSE](../../LICENSE).
+
+<sub><i>Auto-generated against `@aihu/magna@0.2.5`.</i></sub>
+
+<!-- END_AUTOGEN: license -->

package/dist/codegen.d.ts

@@ -0,0 +1,42 @@
+import { i as MagnaPluginOptions, t as MagnaBuildContext } from "./types-BNK5lubM.js";
+import { Plugin } from "@aihu/plugin";
+
+//#region src/codegen.d.ts
+/**
+ * Run the beforeCompile SDL pipeline.
+ *
+ * All failures are handled gracefully — the build is never aborted; instead
+ * a warning is recorded and `magna.untyped` is set to `true` so consumers
+ * know typed generation was skipped.
+ */
+declare function beforeCompile(ctx: MagnaBuildContext): Promise<void>;
+//#endregion
+//#region src/plugin.d.ts
+/**
+ * Create the @aihu/magna plugin.
+ *
+ * Wires the SDL validation pipeline into the `beforeCompile` hook so that
+ * typed GraphQL bindings are generated (or gracefully skipped) at build time.
+ */
+declare function magna(options: MagnaPluginOptions): Plugin;
+//#endregion
+//#region src/warnings.d.ts
+/**
+ * Append `message` to `<outputDir>/.aihu/magna-warnings.json` unless it is
+ * already present (coalesce duplicate warnings across multiple build runs or
+ * hook invocations within the same run).
+ *
+ * File format: `{ "messages": ["..."] }`
+ */
+declare function writeWarnOnce(outputDir: string, message: string): void;
+/**
+ * Deep-merge `value` into `<outputDir>/.aihu/build-flags.json` at the given
+ * dot-notation `key` (e.g. `'magna.untyped'` → `{ magna: { untyped: value } }`).
+ *
+ * Existing sibling keys at each nesting level are preserved; only the target
+ * leaf is overwritten.
+ */
+declare function setBuildFlag(outputDir: string, key: string, value: unknown): void;
+//#endregion
+export { beforeCompile, magna, setBuildFlag, writeWarnOnce };
+//# sourceMappingURL=codegen.d.ts.map

package/dist/codegen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codegen.d.ts","names":[],"sources":["../src/codegen.ts","../src/plugin.ts","../src/warnings.ts"],"mappings":";;;;;;;AAgCA;;;;iBAAsB,aAAA,CAAc,GAAA,EAAK,iBAAA,GAAoB,OAAO;;;;;;;;ACHV;iBAA1C,KAAA,CAAM,OAAA,EAAS,kBAAA,GAAqB,MAAM;;;;;;;ADG1D;;;iBEQgB,aAAA,CAAc,SAAA,UAAmB,OAAe;;;;;AFRI;;;iBE4BpD,YAAA,CAAa,SAAA,UAAmB,GAAA,UAAa,KAAA"}

package/dist/codegen.js

@@ -0,0 +1,3 @@
+import{existsSync as e,mkdirSync as t,readFileSync as n,writeFileSync as r}from"node:fs";import{dirname as i,isAbsolute as a,join as o}from"node:path";import{definePlugin as s}from"@aihu/plugin";function c(e){return o(e,`.aihu`)}function l(n){e(n)||t(n,{recursive:!0})}function u(t,r){if(!e(t))return r;try{return JSON.parse(n(t,`utf8`))}catch{return r}}function d(e,t){let n=c(e);l(n);let i=o(n,`magna-warnings.json`),a=u(i,{messages:[]});a.messages.includes(t)||(a.messages.push(t),r(i,JSON.stringify(a,null,2),`utf8`))}function f(e,t,n){let a=c(e);l(a);let s=u(o(a,`build-flags.json`),{}),d=t.split(`.`),f=s;for(let e=0;e<d.length-1;e++){let t=d[e];(typeof f[t]!=`object`||f[t]===null||Array.isArray(f[t]))&&(f[t]={}),f=f[t]}let p=d[d.length-1];f[p]=n;let m=o(c(e),`build-flags.json`);l(i(m)),r(m,JSON.stringify(s,null,2),`utf8`)}async function p(s){let{outputDir:c,projectRoot:l}=s,{options:u,outputPath:p}=s.magna,m=u.schemaPath??`schema.graphql`,h=a(m)?m:o(l,m),g;try{g=await import(`@aihu/magna-gqlmin`)}catch{d(c,`gqlmin not installed; SDL validation skipped. createMagnaResource will use untyped string-template GraphQL.`),f(c,`magna.untyped`,!0);return}if(!e(h)){d(c,`schema not found at ${h}; resources will be untyped.`),f(c,`magna.untyped`,!0);return}let _=n(h,`utf8`);try{g.parseSchema(_)}catch(e){d(c,`SDL parse error in ${h}: ${e.message??String(e)}; resources will be untyped.`),f(c,`magna.untyped`,!0);return}let v=a(p)?p:o(l,p);t(i(v),{recursive:!0}),r(v,[`// AUTO-GENERATED by @aihu/magna beforeCompile. Do not edit.`,`// Schema: ${h}`,`// Generated: ${new Date().toISOString()}`,``,`// Typed bindings will be populated when @aihu/magna-gqlmin codegen is implemented.`,`export {}`,``].join(`
+`),`utf8`),f(c,`magna.untyped`,!1)}function m(e){return s({name:`@aihu/magna`,version:`0.1.0`,namespace:`magna`,aihuVersion:`^0.2.0`,hooks:{beforeCompile:async t=>{await p({...t,magna:{options:e,untyped:!1,outputPath:`src/generated/magna.ts`,warnings:[]}})}}})}export{p as beforeCompile,m as magna,f as setBuildFlag,d as writeWarnOnce};
+//# sourceMappingURL=codegen.js.map

package/dist/codegen.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codegen.js","names":[],"sources":["../src/warnings.ts","../src/codegen.ts","../src/plugin.ts"],"sourcesContent":["/**\n * @aihu/magna — build-time warning and flag helpers.\n *\n * This module is build-time ONLY. It uses Node.js `node:fs` to read and write\n * JSON files in the output directory. It MUST NOT be imported in browser bundles.\n *\n * Two helpers:\n *   writeWarnOnce  — coalescing warn logger (deduplicates messages)\n *   setBuildFlag   — deep-merge key/value into build-flags.json\n */\nimport { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'\nimport { dirname, join } from 'node:path'\n\n/** Absolute path to the .aihu/ directory inside outputDir. */\nfunction aihuDir(outputDir: string): string {\n  return join(outputDir, '.aihu')\n}\n\nfunction ensureDir(dir: string): void {\n  if (!existsSync(dir)) {\n    mkdirSync(dir, { recursive: true })\n  }\n}\n\nfunction readJson<T>(filePath: string, fallback: T): T {\n  if (!existsSync(filePath)) return fallback\n  try {\n    return JSON.parse(readFileSync(filePath, 'utf8')) as T\n  } catch {\n    return fallback\n  }\n}\n\n/**\n * Append `message` to `<outputDir>/.aihu/magna-warnings.json` unless it is\n * already present (coalesce duplicate warnings across multiple build runs or\n * hook invocations within the same run).\n *\n * File format: `{ \"messages\": [\"...\"] }`\n */\nexport function writeWarnOnce(outputDir: string, message: string): void {\n  const dir = aihuDir(outputDir)\n  ensureDir(dir)\n\n  const filePath = join(dir, 'magna-warnings.json')\n  const data = readJson<{ messages: string[] }>(filePath, { messages: [] })\n\n  if (!data.messages.includes(message)) {\n    data.messages.push(message)\n    writeFileSync(filePath, JSON.stringify(data, null, 2), 'utf8')\n  }\n}\n\n/**\n * Deep-merge `value` into `<outputDir>/.aihu/build-flags.json` at the given\n * dot-notation `key` (e.g. `'magna.untyped'` → `{ magna: { untyped: value } }`).\n *\n * Existing sibling keys at each nesting level are preserved; only the target\n * leaf is overwritten.\n */\nexport function setBuildFlag(outputDir: string, key: string, value: unknown): void {\n  const dir = aihuDir(outputDir)\n  ensureDir(dir)\n\n  const filePath = join(dir, 'build-flags.json')\n  const root = readJson<Record<string, unknown>>(filePath, {})\n\n  // Walk dot-notation segments and deep-merge.\n  const segments = key.split('.')\n  let cursor: Record<string, unknown> = root\n\n  for (let i = 0; i < segments.length - 1; i++) {\n    const seg = segments[i] as string\n    if (typeof cursor[seg] !== 'object' || cursor[seg] === null || Array.isArray(cursor[seg])) {\n      cursor[seg] = {}\n    }\n    cursor = cursor[seg] as Record<string, unknown>\n  }\n\n  const leaf = segments[segments.length - 1] as string\n  cursor[leaf] = value\n\n  const absPath = join(aihuDir(outputDir), 'build-flags.json')\n  ensureDir(dirname(absPath))\n  writeFileSync(absPath, JSON.stringify(root, null, 2), 'utf8')\n}\n","/**\n * @aihu/magna — beforeCompile SDL pipeline.\n *\n * Implements the SDL validation + typed-binding generation step that runs during\n * the aihu build phase. Gracefully skips when @aihu/magna-gqlmin is absent.\n *\n * Pipeline (per brief):\n *   1. Resolve schemaPath (default 'schema.graphql') against ctx.projectRoot.\n *   2. Try to import @aihu/magna-gqlmin. On failure → warn + untyped=true, return.\n *   3. Check if schema file exists. If not → warn + untyped=true, return.\n *   4. Parse SDL via gqlmin.parseSchema(). On parse error → warn + untyped=true, return.\n *   5. Emit typed bindings to outputPath (default 'src/generated/magna.ts').\n *   6. setBuildFlag(magna.untyped, false).\n *\n * This module is build-time ONLY (uses node:fs). Never imported in browser bundles.\n */\nimport { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'\nimport { dirname, isAbsolute, join } from 'node:path'\nimport type { MagnaBuildContext } from './types.js'\nimport { setBuildFlag, writeWarnOnce } from './warnings.js'\n\ninterface GqlminModule {\n  parseSchema: (sdl: string) => unknown\n}\n\n/**\n * Run the beforeCompile SDL pipeline.\n *\n * All failures are handled gracefully — the build is never aborted; instead\n * a warning is recorded and `magna.untyped` is set to `true` so consumers\n * know typed generation was skipped.\n */\nexport async function beforeCompile(ctx: MagnaBuildContext): Promise<void> {\n  const { outputDir, projectRoot } = ctx\n  const { options, outputPath } = ctx.magna\n\n  // 1. Resolve schemaPath\n  const rawPath = options.schemaPath ?? 'schema.graphql'\n  const schemaAbsPath = isAbsolute(rawPath) ? rawPath : join(projectRoot, rawPath)\n\n  // 2. Try to import @aihu/magna-gqlmin\n  let gqlmin: GqlminModule\n  try {\n    // @ts-expect-error — @aihu/magna-gqlmin is optional; graceful-skip when absent\n    // eslint-disable-next-line\n    gqlmin = (await import(/* @vite-ignore */ '@aihu/magna-gqlmin')) as GqlminModule\n  } catch {\n    writeWarnOnce(\n      outputDir,\n      'gqlmin not installed; SDL validation skipped. createMagnaResource will use untyped string-template GraphQL.',\n    )\n    setBuildFlag(outputDir, 'magna.untyped', true)\n    return\n  }\n\n  // 3. Check if schema file exists\n  if (!existsSync(schemaAbsPath)) {\n    writeWarnOnce(outputDir, `schema not found at ${schemaAbsPath}; resources will be untyped.`)\n    setBuildFlag(outputDir, 'magna.untyped', true)\n    return\n  }\n\n  // 4. Parse the SDL\n  const sdl = readFileSync(schemaAbsPath, 'utf8')\n  let _ast: unknown\n  try {\n    _ast = gqlmin.parseSchema(sdl)\n  } catch (err) {\n    writeWarnOnce(\n      outputDir,\n      `SDL parse error in ${schemaAbsPath}: ${(err as Error).message ?? String(err)}; resources will be untyped.`,\n    )\n    setBuildFlag(outputDir, 'magna.untyped', true)\n    return\n  }\n\n  // 5. Emit typed bindings\n  const absOutputPath = isAbsolute(outputPath) ? outputPath : join(projectRoot, outputPath)\n  mkdirSync(dirname(absOutputPath), { recursive: true })\n  writeFileSync(\n    absOutputPath,\n    [\n      '// AUTO-GENERATED by @aihu/magna beforeCompile. Do not edit.',\n      `// Schema: ${schemaAbsPath}`,\n      `// Generated: ${new Date().toISOString()}`,\n      '',\n      '// Typed bindings will be populated when @aihu/magna-gqlmin codegen is implemented.',\n      'export {}',\n      '',\n    ].join('\\n'),\n    'utf8',\n  )\n\n  // 6. Mark as typed\n  setBuildFlag(outputDir, 'magna.untyped', false)\n}\n","/**\n * @aihu/magna — plugin factory.\n *\n * `magna(options)` returns a `Plugin` that wires the SDL pipeline into the\n * aihu `beforeCompile` build hook. Register it in `defineAihuConfig`:\n *\n * @example\n * // aihu.config.ts\n * import { magna } from '@aihu/magna'\n * import { defineAihuConfig } from '@aihu/server'\n *\n * export default defineAihuConfig({\n *   plugins: [\n *     magna({ url: process.env.MAGNA_GRAPHQL_URL! }),\n *   ],\n * })\n */\n\nimport type { Plugin } from '@aihu/plugin'\nimport { definePlugin } from '@aihu/plugin'\nimport { beforeCompile } from './codegen.js'\nimport type { MagnaBuildContext, MagnaPluginOptions } from './types.js'\n\n/**\n * Create the @aihu/magna plugin.\n *\n * Wires the SDL validation pipeline into the `beforeCompile` hook so that\n * typed GraphQL bindings are generated (or gracefully skipped) at build time.\n */\nexport function magna(options: MagnaPluginOptions): Plugin {\n  return definePlugin({\n    name: '@aihu/magna',\n    version: '0.1.0',\n    namespace: 'magna',\n    aihuVersion: '^0.2.0',\n    hooks: {\n      beforeCompile: async (ctx) => {\n        const magnaCtx: MagnaBuildContext = {\n          ...ctx,\n          magna: {\n            options,\n            untyped: false,\n            outputPath: 'src/generated/magna.ts',\n            warnings: [],\n          },\n        }\n        await beforeCompile(magnaCtx)\n      },\n    },\n  })\n}\n"],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,71 @@
+import { a as MagnaResource, i as MagnaPluginOptions, n as MagnaFetch, o as MagnaSubscriptionHandle, r as MagnaJwtRelay, t as MagnaBuildContext } from "./types-BNK5lubM.js";
+import { Signal } from "@aihu/signals";
+import { ResourceOptions } from "@aihu-plugin/data";
+
+//#region ../context/src/index.d.ts
+/**
+ * @aihu/context — zero-dependency, DOM-free context system.
+ *
+ * Provides a React-style context API suitable for both SSR (via
+ * setSsrContextMap / clearSsrContextMap / runWithContext) and client-side
+ * usage. No external imports; no DOM references.
+ */
+/**
+ * Opaque token that identifies a context slot and carries its default value.
+ */
+interface ContextToken<T> {
+  readonly _id: symbol;
+  readonly _default: T | undefined;
+}
+//#endregion
+//#region src/context.d.ts
+declare const MagnaFetchToken: ContextToken<MagnaFetch>;
+//#endregion
+//#region src/fetch.d.ts
+/**
+ * Create a typed GraphQL fetch function bound to the given options.
+ *
+ * JWT relay: reads `options.getToken?.()` per request. When the getter
+ * returns a non-null string the Authorization header is added; when it
+ * returns null the header is omitted entirely (per relay spec).
+ *
+ * Static headers in `options.headers` are merged before the per-call
+ * Authorization header so callers can override if needed.
+ *
+ * Network failures propagate as thrown errors. GraphQL-level errors are
+ * returned inside the response envelope (`{ data: null, errors: [...] }`).
+ */
+declare function createMagnaFetch(options: MagnaPluginOptions): MagnaFetch;
+//#endregion
+//#region src/resource.d.ts
+/**
+ * Create a reactive Magna GraphQL resource.
+ *
+ * @param fetch      Magna fetch function (from createMagnaFetch).
+ * @param operation  GraphQL operation string (query/mutation).
+ * @param variables  Optional reactive signal whose value is passed as variables.
+ *                   When the signal value changes the resource automatically
+ *                   re-fetches with the new variables. A null signal value puts
+ *                   the resource into idle state (no fetch).
+ * @param options    Optional ResourceOptions forwarded to createResource
+ *                   (initialData, dehydrate, store).
+ *
+ * Returns a Resource<T> (state, refetch, invalidate).
+ */
+declare function createMagnaResource<T>(fetch: MagnaFetch, operation: string, variables?: Signal<Readonly<Record<string, unknown>> | null>, options?: ResourceOptions<T>): MagnaResource<T>;
+//#endregion
+//#region src/subscription.d.ts
+/**
+ * Return a degraded subscription handle.
+ *
+ * The handle contains:
+ *   - `state`: a signal always holding null (no streaming data yet).
+ *   - `close`: idempotent no-op.
+ *   - `degraded`: always true in v0.1.
+ *
+ * A warn-once message is emitted via console.warn on first call.
+ */
+declare function useMagnaSubscription<T>(): MagnaSubscriptionHandle<T>;
+//#endregion
+export { type MagnaBuildContext, type MagnaFetch, MagnaFetchToken, type MagnaJwtRelay, type MagnaPluginOptions, type MagnaResource, type MagnaSubscriptionHandle, createMagnaFetch, createMagnaResource, useMagnaSubscription };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../context/src/index.ts","../src/context.ts","../src/fetch.ts","../src/resource.ts","../src/subscription.ts"],"mappings":";;;;;;;;;;AAWA;;;;;UAAiB,YAAA;EAAA,SACN,GAAA;EAAA,SACA,QAAA,EAAU,CAAC;AAAA;;;cCMT,eAAA,EAAe,YAAA,CAAA,UAAA;;;;;;;;;;ADNN;;;;ACMtB;;iBCEgB,gBAAA,CAAiB,OAAA,EAAS,kBAAA,GAAqB,UAAU;;;;;ADFzE;;;;AAA4B;;;;ACE5B;;;;iBCsCgB,mBAAA,GAAA,CACd,KAAA,EAAO,UAAA,EACP,SAAA,UACA,SAAA,GAAY,MAAA,CAAO,QAAA,CAAS,MAAA,4BAC5B,OAAA,GAAU,eAAA,CAAgB,CAAA,IACzB,aAAA,CAAc,CAAA;;;;;;;AHnDK;;;;ACMtB;;iBGOgB,oBAAA,GAAA,CAAA,GAA2B,uBAAuB,CAAC,CAAA"}

package/dist/index.js

@@ -0,0 +1,2 @@
+import{signal as e}from"@aihu/signals";import{createResource as t}from"@aihu-plugin/data";function n(e){return{_id:Symbol(`aihu.context`),_default:e}}const r=n();function i(e){let t=e.fetch??globalThis.fetch;return async function(n,r){let i={"content-type":`application/json`,...e.headers},a=e.getToken?.()??null;a!==null&&(i.authorization=`Bearer ${a}`);let o=JSON.stringify({query:n,...r===void 0?{}:{variables:r}}),s=await(await t(e.url,{method:`POST`,headers:i,body:o})).json();return{data:s.data??null,...s.errors?{errors:s.errors}:{}}}}function a(e){if(e==null)return`{}`;let t={};for(let n of Object.keys(e).sort())t[n]=e[n];return JSON.stringify(t)}function o(e,t){return`${e}|${a(t)}`}function s(n,r,i,a){let[s,c]=e(i?o(r,i[0]()):o(r,void 0)),l=i?[()=>{let e=i[0]();return e===null?null:o(r,e)},c]:[()=>s(),c];async function u(e){let t=await n(r,i?i[0]()??void 0:void 0);if(t.errors&&t.errors.length>0){let e=t.errors.map(e=>e.message).join(`; `);throw Error(`GraphQL error: ${e}`)}return t.data}return t(l,u,a)}let c=!1;function l(){c||(c=!0,console.warn(`magna subscriptions require v0.2 streaming; returning degraded handle`));let[t]=e(null);return{state:[t,()=>{}],close(){},degraded:!0}}export{r as MagnaFetchToken,i as createMagnaFetch,s as createMagnaResource,l as useMagnaSubscription};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../context/src/index.ts","../src/context.ts","../src/fetch.ts","../src/resource.ts","../src/subscription.ts"],"sourcesContent":["/**\n * @aihu/context — zero-dependency, DOM-free context system.\n *\n * Provides a React-style context API suitable for both SSR (via\n * setSsrContextMap / clearSsrContextMap / runWithContext) and client-side\n * usage. No external imports; no DOM references.\n */\n\n/**\n * Opaque token that identifies a context slot and carries its default value.\n */\nexport interface ContextToken<T> {\n  readonly _id: symbol\n  readonly _default: T | undefined\n}\n\n/**\n * Module-level active context map. Set by setSsrContextMap or runWithContext;\n * cleared by clearSsrContextMap. null means no map is active.\n *\n * This is the FLAT, SSR-oriented path — one map per request, no tree scoping.\n * Left unchanged so existing SSR consumers keep working.\n */\nlet _activeContextMap: Map<symbol, unknown> | null = null\n\n/**\n * Client hierarchical path. During a component's setup the runtime installs that\n * component's `provides` object here — a plain object whose prototype chain IS\n * the ancestor context tree (each subtree that provides does `Object.create` of\n * its parent's object). `inject` becomes a single prototype-chain lookup, and an\n * ancestor's provide is visible to descendants but not to siblings.\n *\n * `_ownProvides` tracks whether the active object is THIS owner's own (already\n * `Object.create`d) or still a shared reference to the parent's — so the first\n * `provide()` allocates exactly once and hands the new object back to the runtime\n * to store on the instance for descendants to inherit.\n *\n * Null when not inside a client component setup (then the SSR map, or the token\n * default, applies) — so nothing changes for SSR or standalone use.\n */\nlet _activeProvides: Record<symbol, unknown> | null = null\nlet _ownProvides = false\nlet _onOwnProvides: ((own: Record<symbol, unknown>) => void) | null = null\n\n/**\n * Create a new context token. Optionally provide a default value that\n * inject() returns when no value has been provided for this token.\n */\nexport function createContext<T>(defaultValue?: T): ContextToken<T> {\n  return {\n    _id: Symbol('aihu.context'),\n    _default: defaultValue,\n  }\n}\n\n/**\n * Interned string-key → token map for `contextKey`. Module-global on purpose:\n * every component in the app must agree on the token for a given key.\n */\nconst _stringTokens = new Map<string, ContextToken<unknown>>()\n\n/**\n * Intern a stable context token for a string key, so the compiler-lowered\n * `$context` provide/consume (which are string-keyed) resolve to one shared\n * token app-wide. Module-global, so every component agrees on the token for a\n * key.\n */\nexport function contextKey(key: string): ContextToken<unknown> {\n  let t = _stringTokens.get(key)\n  if (t === undefined) {\n    t = createContext<unknown>()\n    _stringTokens.set(key, t)\n  }\n  return t\n}\n\n/**\n * Write a value for the given token into the active context map.\n * If no map is currently active, this is a no-op.\n */\nexport function provide<T>(token: ContextToken<T>, value: T): void {\n  // Client hierarchical path takes precedence when a component setup is active.\n  if (_activeProvides !== null || _onOwnProvides !== null) {\n    if (!_ownProvides) {\n      // First provide by this owner: allocate its own object inheriting the\n      // parent's, and hand it back so the runtime stores it on the instance for\n      // descendants to inherit. `?? null` roots the chain when there is no parent.\n      _activeProvides = Object.create(_activeProvides ?? null) as Record<symbol, unknown>\n      _ownProvides = true\n      _onOwnProvides?.(_activeProvides)\n    }\n    _activeProvides![token._id] = value\n    return\n  }\n  if (_activeContextMap === null) return\n  _activeContextMap.set(token._id, value)\n}\n\n/**\n * Read a value for the given token. On the client hierarchical path this is a\n * single prototype-chain lookup (an ancestor's provide is visible here). Falls\n * back to the flat SSR map, then the token default.\n */\nexport function inject<T>(token: ContextToken<T>): T | undefined {\n  if (_activeProvides !== null) {\n    return (token._id in _activeProvides ? _activeProvides[token._id] : token._default) as\n      | T\n      | undefined\n  }\n  if (_activeContextMap === null) return token._default\n  if (_activeContextMap.has(token._id)) {\n    return _activeContextMap.get(token._id) as T\n  }\n  return token._default\n}\n\n/**\n * @internal — runtime hook. Enter a component's context scope for the duration of\n * its setup: `parent` is the resolved ancestor `provides` object (or null at the\n * root), and `onOwn` is called with this owner's own object the first time it\n * `provide`s, so the runtime can store it on the instance for descendants.\n * Returns the previous scope for `_exitContext` to restore (setups nest).\n */\nexport function _enterContext(\n  parent: Record<symbol, unknown> | null,\n  onOwn: (own: Record<symbol, unknown>) => void,\n): [Record<symbol, unknown> | null, boolean, ((own: Record<symbol, unknown>) => void) | null] {\n  const prev: [\n    Record<symbol, unknown> | null,\n    boolean,\n    ((own: Record<symbol, unknown>) => void) | null,\n  ] = [_activeProvides, _ownProvides, _onOwnProvides]\n  _activeProvides = parent\n  _ownProvides = false\n  _onOwnProvides = onOwn\n  return prev\n}\n\n/** @internal — restore the scope captured by `_enterContext`. */\nexport function _exitContext(\n  prev: [Record<symbol, unknown> | null, boolean, ((own: Record<symbol, unknown>) => void) | null],\n): void {\n  _activeProvides = prev[0]\n  _ownProvides = prev[1]\n  _onOwnProvides = prev[2]\n}\n\n/**\n * Set the active context map (SSR entry point).\n * Replaces any previously active map.\n */\nexport function setSsrContextMap(map: Map<symbol, unknown>): void {\n  _activeContextMap = map\n}\n\n/**\n * Clear the active context map (SSR teardown).\n */\nexport function clearSsrContextMap(): void {\n  _activeContextMap = null\n}\n\n/**\n * Run fn() with the given map as the active context map, then restore\n * the previous state (null) in a finally block.\n *\n * This is the recommended SSR entry point: each request gets its own\n * Map; context leakage between requests is impossible.\n */\nexport function runWithContext<R>(map: Map<symbol, unknown>, fn: () => R): R {\n  setSsrContextMap(map)\n  try {\n    return fn()\n  } finally {\n    clearSsrContextMap()\n  }\n}\n","/**\n * @aihu/magna — injection token for the Magna fetch function.\n *\n * The compiler lowers `$query name = data.X.query(vars)` (and magna-origin\n * `$resource` entries) to\n * `const name = createMagnaResource(inject(MagnaFetchToken), data.X.query(vars))`.\n * `MagnaFetchToken` is the context token that `inject(...)` resolves at\n * component setup so `createMagnaResource` receives its `MagnaFetch`.\n *\n * Provide at app root: `provide(MagnaFetchToken, createMagnaFetch(options))`.\n * Inject in setup:    `const fetch = inject(MagnaFetchToken)`.\n *\n * Mirrors the @aihu-plugin/data `ResourceStoreToken` pattern\n * (packages/plugin-data/src/store.ts). No default value — `inject` returns\n * `undefined` when no fetch is provided.\n */\nimport { createContext } from '@aihu/context'\nimport type { MagnaFetch } from './types.js'\n\nexport const MagnaFetchToken = createContext<MagnaFetch>()\n","/**\n * @aihu/magna — dep-free GraphQL fetch with JWT relay.\n *\n * createMagnaFetch builds a typed GraphQL POST wrapper. No external deps;\n * uses globalThis.fetch (or options.fetch for testing/edge environments).\n */\nimport type { MagnaFetch, MagnaPluginOptions } from './types.js'\n\n/**\n * Create a typed GraphQL fetch function bound to the given options.\n *\n * JWT relay: reads `options.getToken?.()` per request. When the getter\n * returns a non-null string the Authorization header is added; when it\n * returns null the header is omitted entirely (per relay spec).\n *\n * Static headers in `options.headers` are merged before the per-call\n * Authorization header so callers can override if needed.\n *\n * Network failures propagate as thrown errors. GraphQL-level errors are\n * returned inside the response envelope (`{ data: null, errors: [...] }`).\n */\nexport function createMagnaFetch(options: MagnaPluginOptions): MagnaFetch {\n  const fetchImpl = options.fetch ?? globalThis.fetch\n\n  return async function magnaFetch<TData = unknown>(\n    operation: string,\n    variables?: Readonly<Record<string, unknown>>,\n  ): Promise<{\n    readonly data: TData | null\n    readonly errors?: ReadonlyArray<{ readonly message: string }>\n  }> {\n    const headers: Record<string, string> = {\n      'content-type': 'application/json',\n      ...options.headers,\n    }\n\n    const token = options.getToken?.() ?? null\n    if (token !== null) {\n      headers.authorization = `Bearer ${token}`\n    }\n\n    const body = JSON.stringify({\n      query: operation,\n      ...(variables !== undefined ? { variables } : {}),\n    })\n\n    const response = await fetchImpl(options.url, {\n      method: 'POST',\n      headers,\n      body,\n    })\n\n    const json = (await response.json()) as {\n      data?: TData | null\n      errors?: Array<{ message: string }>\n    }\n\n    return {\n      data: json.data ?? null,\n      ...(json.errors ? { errors: json.errors } : {}),\n    }\n  }\n}\n","/**\n * @aihu/magna — resource composition over @aihu-plugin/data.\n *\n * createMagnaResource wraps createResource with a cache-key strategy that\n * combines the GraphQL operation string + serialised variables. The key signal\n * is derived from an optional reactive variables signal so queries automatically\n * re-fetch when variables change.\n *\n * Cache-key strategy (Builder-time decision): alphabetically-sorted key\n * serialisation via JSON.stringify — dep-free, ~15 LOC, deterministic.\n * Variables `{ b: 2, a: 1 }` and `{ a: 1, b: 2 }` produce the same key,\n * preventing spurious cache misses from object-property-ordering differences.\n */\n\nimport type { Signal } from '@aihu/signals'\nimport { signal } from '@aihu/signals'\nimport type { ResourceOptions } from '@aihu-plugin/data'\nimport { createResource } from '@aihu-plugin/data'\nimport type { MagnaFetch, MagnaResource } from './types.js'\n\n/**\n * Alphabetically-sorted JSON serialisation of an object.\n * Produces a stable string regardless of property insertion order.\n * Returns '{}' for null/undefined input (maps to \"no variables\").\n */\nfunction stableSerialise(obj: Readonly<Record<string, unknown>> | null | undefined): string {\n  if (obj == null) return '{}'\n  const sorted: Record<string, unknown> = {}\n  for (const k of Object.keys(obj).sort()) {\n    sorted[k] = obj[k]\n  }\n  return JSON.stringify(sorted)\n}\n\n/**\n * Build a stable cache key from the operation string and current variables.\n * Format: `<operation>|<sorted-vars-json>` — unique per query+variable pair.\n */\nfunction buildCacheKey(\n  operation: string,\n  vars: Readonly<Record<string, unknown>> | null | undefined,\n): string {\n  return `${operation}|${stableSerialise(vars)}`\n}\n\n/**\n * Create a reactive Magna GraphQL resource.\n *\n * @param fetch      Magna fetch function (from createMagnaFetch).\n * @param operation  GraphQL operation string (query/mutation).\n * @param variables  Optional reactive signal whose value is passed as variables.\n *                   When the signal value changes the resource automatically\n *                   re-fetches with the new variables. A null signal value puts\n *                   the resource into idle state (no fetch).\n * @param options    Optional ResourceOptions forwarded to createResource\n *                   (initialData, dehydrate, store).\n *\n * Returns a Resource<T> (state, refetch, invalidate).\n */\nexport function createMagnaResource<T>(\n  fetch: MagnaFetch,\n  operation: string,\n  variables?: Signal<Readonly<Record<string, unknown>> | null>,\n  options?: ResourceOptions<T>,\n): MagnaResource<T> {\n  // Build a stable key signal from the operation + current variables value.\n  // null variables → null key → idle state (no fetch fired).\n  const [getKey, setKey] = signal<string | null>(\n    variables ? buildCacheKey(operation, variables[0]()) : buildCacheKey(operation, undefined),\n  )\n\n  // When variables signal changes, recompute the key.\n  // We wire this as an effect-like subscription via the createResource key signal.\n  // The key signal passed to createResource is a derived value that reads the\n  // variables signal (or a static key when variables is undefined).\n  const keySignal: Signal<string | null | undefined> = variables\n    ? ([\n        () => {\n          const vars = variables[0]()\n          return vars === null ? null : buildCacheKey(operation, vars)\n        },\n        setKey,\n      ] as unknown as Signal<string | null | undefined>)\n    : ([() => getKey(), setKey] as unknown as Signal<string | null | undefined>)\n\n  // Fetcher: call the magna fetch function, throw on GraphQL errors\n  // (drives the resource into 'error' state).\n  async function fetcher(_key: string): Promise<T> {\n    // Extract variables from the key is not needed — we re-read them from the signal.\n    const vars = variables ? (variables[0]() ?? undefined) : undefined\n    const result = await fetch(operation, vars)\n    if (result.errors && result.errors.length > 0) {\n      const msgs = result.errors.map((e) => e.message).join('; ')\n      throw new Error(`GraphQL error: ${msgs}`)\n    }\n    return result.data as T\n  }\n\n  return createResource<T>(keySignal, fetcher, options)\n}\n","/**\n * @aihu/magna — useMagnaSubscription v0.1 degraded shim.\n *\n * v0.2 will introduce real WebSocket/SSE streaming. Until then this shim\n * returns a handle with `degraded: true` so consumers can branch on that flag\n * without breaking when streaming lands.\n *\n * A warn-once message is emitted on first call via console.warn.\n */\n\nimport type { Signal } from '@aihu/signals'\nimport { signal } from '@aihu/signals'\nimport type { MagnaSubscriptionHandle } from './types.js'\n\nlet _warned = false\n\n/**\n * Return a degraded subscription handle.\n *\n * The handle contains:\n *   - `state`: a signal always holding null (no streaming data yet).\n *   - `close`: idempotent no-op.\n *   - `degraded`: always true in v0.1.\n *\n * A warn-once message is emitted via console.warn on first call.\n */\nexport function useMagnaSubscription<T>(): MagnaSubscriptionHandle<T> {\n  if (!_warned) {\n    _warned = true\n    console.warn('magna subscriptions require v0.2 streaming; returning degraded handle')\n  }\n\n  const [getState] = signal<T | null>(null)\n\n  const noop = (): void => {\n    // no-op setter — degraded handles do not accept external writes\n  }\n\n  return {\n    state: [getState, noop] as unknown as Signal<T | null>,\n    close(): void {\n      // Idempotent no-op in v0.1.\n    },\n    degraded: true,\n  }\n}\n"],"mappings":"0FAgDA,SAAgB,EAAiB,EAAmC,CAClE,MAAO,CACL,IAAK,OAAO,cAAc,EAC1B,SAAU,CACZ,CACF,CClCA,MAAa,EAAkB,EAA0B,ECEzD,SAAgB,EAAiB,EAAyC,CACxE,IAAM,EAAY,EAAQ,OAAS,WAAW,MAE9C,OAAO,eACL,EACA,EAIC,CACD,IAAM,EAAkC,CACtC,eAAgB,mBAChB,GAAG,EAAQ,OACb,EAEM,EAAQ,EAAQ,WAAW,GAAK,KAClC,IAAU,OACZ,EAAQ,cAAgB,UAAU,KAGpC,IAAM,EAAO,KAAK,UAAU,CAC1B,MAAO,EACP,GAAI,IAAc,IAAA,GAA4B,CAAC,EAAjB,CAAE,WAAU,CAC5C,CAAC,EAQK,EAAQ,MAAM,MANG,EAAU,EAAQ,IAAK,CAC5C,OAAQ,OACR,UACA,MACF,CAAC,GAE4B,KAAK,EAKlC,MAAO,CACL,KAAM,EAAK,MAAQ,KACnB,GAAI,EAAK,OAAS,CAAE,OAAQ,EAAK,MAAO,EAAI,CAAC,CAC/C,CACF,CACF,CCrCA,SAAS,EAAgB,EAAmE,CAC1F,GAAI,GAAO,KAAM,MAAO,KACxB,IAAM,EAAkC,CAAC,EACzC,IAAK,IAAM,KAAK,OAAO,KAAK,CAAG,EAAE,KAAK,EACpC,EAAO,GAAK,EAAI,GAElB,OAAO,KAAK,UAAU,CAAM,CAC9B,CAMA,SAAS,EACP,EACA,EACQ,CACR,MAAO,GAAG,EAAU,GAAG,EAAgB,CAAI,GAC7C,CAgBA,SAAgB,EACd,EACA,EACA,EACA,EACkB,CAGlB,GAAM,CAAC,EAAQ,GAAU,EACvB,EAAY,EAAc,EAAW,EAAU,GAAG,CAAC,EAAI,EAAc,EAAW,IAAA,EAAS,CAC3F,EAMM,EAA+C,EAChD,KACO,CACJ,IAAM,EAAO,EAAU,GAAG,EAC1B,OAAO,IAAS,KAAO,KAAO,EAAc,EAAW,CAAI,CAC7D,EACA,CACF,EACC,KAAO,EAAO,EAAG,CAAM,EAI5B,eAAe,EAAQ,EAA0B,CAG/C,IAAM,EAAS,MAAM,EAAM,EADd,EAAa,EAAU,GAAG,GAAK,IAAA,GAAa,IAAA,EACf,EAC1C,GAAI,EAAO,QAAU,EAAO,OAAO,OAAS,EAAG,CAC7C,IAAM,EAAO,EAAO,OAAO,IAAK,GAAM,EAAE,OAAO,EAAE,KAAK,IAAI,EAC1D,MAAU,MAAM,kBAAkB,GAAM,CAC1C,CACA,OAAO,EAAO,IAChB,CAEA,OAAO,EAAkB,EAAW,EAAS,CAAO,CACtD,CCrFA,IAAI,EAAU,GAYd,SAAgB,GAAsD,CAC/D,IACH,EAAU,GACV,QAAQ,KAAK,uEAAuE,GAGtF,GAAM,CAAC,GAAY,EAAiB,IAAI,EAMxC,MAAO,CACL,MAAO,CAAC,MALe,CAEzB,CAGwB,EACtB,OAAc,CAEd,EACA,SAAU,EACZ,CACF"}

package/dist/types-BNK5lubM.d.ts

@@ -0,0 +1,81 @@
+import { Signal } from "@aihu/signals";
+import { Resource } from "@aihu-plugin/data";
+import { BuildContext } from "@aihu/plugin";
+
+//#region src/types.d.ts
+/** Configuration options for the magna GraphQL plugin. */
+interface MagnaPluginOptions {
+  /** Magna GraphQL endpoint URL (e.g., https://magna.example.com/graphql). */
+  readonly url: string;
+  /** Path to the GraphQL SDL schema file. Default: 'schema.graphql'. */
+  readonly schemaPath?: string;
+  /** Static headers merged into every request. */
+  readonly headers?: Readonly<Record<string, string>>;
+  /** Git revision (informational; injected into build metadata). */
+  readonly gitRev?: string;
+  /**
+   * Getter for the current JWT. Called per-request.
+   * Return null to omit the Authorization header entirely.
+   */
+  readonly getToken?: () => string | null;
+  /**
+   * Custom fetch implementation. Defaults to globalThis.fetch.
+   * Useful for testing or non-standard environments.
+   */
+  readonly fetch?: typeof globalThis.fetch;
+}
+/**
+ * Typed fetch wrapper for Magna GraphQL operations.
+ * Sends a POST with the GraphQL envelope; returns the parsed response.
+ * Network failures throw; GraphQL errors are returned in the envelope.
+ */
+type MagnaFetch = <TData = unknown>(operation: string, variables?: Readonly<Record<string, unknown>>) => Promise<{
+  readonly data: TData | null;
+  readonly errors?: ReadonlyArray<{
+    readonly message: string;
+  }>;
+}>;
+/** Reactive resource handle wrapping a Magna GraphQL query. */
+type MagnaResource<T> = Resource<T>;
+/**
+ * Handle returned by `useMagnaSubscription`.
+ * In v0.1 this is a degraded shim: subscriptions are not yet streamed.
+ */
+interface MagnaSubscriptionHandle<T> {
+  /** Current value signal. Always starts as null in the v0.1 shim. */
+  readonly state: Signal<T | null>;
+  /** Idempotent close. No-op in v0.1. */
+  readonly close: () => void;
+  /**
+   * True when streaming is not available and the handle is a degraded fallback.
+   * Always true in v0.1.
+   */
+  readonly degraded: boolean;
+}
+/** Extended build context passed to the magna beforeCompile hook. */
+interface MagnaBuildContext extends BuildContext {
+  readonly magna: {
+    readonly options: MagnaPluginOptions;
+    readonly untyped: boolean;
+    readonly outputPath: string;
+    readonly warnings: ReadonlyArray<string>;
+  };
+}
+/**
+ * JWT relay documentation artifact — describes where tokens originate in SSR
+ * and client contexts. This interface is never instantiated at runtime; it
+ * exists for IDE discoverability and schema generation.
+ */
+interface MagnaJwtRelay {
+  readonly ssr: {
+    readonly source: 'request-context';
+    readonly extractor: 'requireAuth(req) → token → wrap in getToken closure';
+  };
+  readonly client: {
+    readonly source: 'cookie-backed-auth-signal';
+    readonly extractor: '@aihu/auth ScopeSignal layer reads cookie → getToken returns live value';
+  };
+}
+//#endregion
+export { MagnaResource as a, MagnaPluginOptions as i, MagnaFetch as n, MagnaSubscriptionHandle as o, MagnaJwtRelay as r, MagnaBuildContext as t };
+//# sourceMappingURL=types-BNK5lubM.d.ts.map

package/dist/types-BNK5lubM.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types-BNK5lubM.d.ts","names":[],"sources":["../src/types.ts"],"mappings":";;;;;;UAYiB,kBAAA;EAkByB;EAAA,SAhB/B,GAAA;EAEA;EAAA,SAAA,UAAA;EAEU;EAAA,SAAV,OAAA,GAAU,QAAA,CAAS,MAAA;EAEnB;EAAA,SAAA,MAAA;EAUA;;;;EAAA,SALA,QAAA;EAaC;;;;EAAA,SARD,KAAA,UAAe,UAAA,CAAW,KAAA;AAAA;;;;;;KAQzB,UAAA,qBACV,SAAA,UACA,SAAA,GAAY,QAAA,CAAS,MAAA,uBAClB,OAAA;EAAA,SACM,IAAA,EAAM,KAAA;EAAA,SACN,MAAA,GAAS,aAAA;IAAA,SAAyB,OAAA;EAAA;AAAA;;KAIjC,aAAA,MAAmB,QAAQ,CAAC,CAAA;;;;AAJY;UAUnC,uBAAA;EANQ;EAAA,SAQd,KAAA,EAAO,MAAM,CAAC,CAAA;EARc;EAAA,SAU5B,KAAA;EAVoB;;;AAAU;EAAV,SAepB,QAAA;AAAA;;UAIM,iBAAA,SAA0B,YAAA;EAAA,SAChC,KAAA;IAAA,SACE,OAAA,EAAS,kBAAA;IAAA,SACT,OAAA;IAAA,SACA,UAAA;IAAA,SACA,QAAA,EAAU,aAAA;EAAA;AAAA;AATJ;AAInB;;;;AAJmB,UAkBF,aAAA;EAAA,SACN,GAAA;IAAA,SACE,MAAA;IAAA,SACA,SAAA;EAAA;EAAA,SAEF,MAAA;IAAA,SACE,MAAA;IAAA,SACA,SAAA;EAAA;AAAA"}

package/install-manifest.json

@@ -0,0 +1,21 @@
+{
+  "pluginName": "@aihu/magna",
+  "pluginVersion": "0.2.0",
+  "aihuVersion": "^0.2.0",
+  "installSteps": [
+    {
+      "kind": "register-plugin",
+      "description": "Register magna plugin in aihu.config.ts"
+    },
+    {
+      "kind": "scaffold-env",
+      "description": "Add MAGNA_GRAPHQL_URL to .env.example"
+    }
+  ],
+  "requiredEnv": [
+    {
+      "name": "MAGNA_GRAPHQL_URL",
+      "description": "Magna GraphQL endpoint (e.g., https://magna.example.com/graphql)"
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@aihu/magna",
+  "version": "0.2.5",
+  "description": "aihu bridge for Magna GraphQL — dep-free fetch, resource composition, JWT relay",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./codegen": {
+      "import": "./dist/codegen.js",
+      "types": "./dist/codegen.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "install-manifest.json"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "rolldown -c rolldown.config.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "bun run build"
+  },
+  "dependencies": {
+    "@aihu/signals": "0.5.0",
+    "@aihu/plugin": "0.1.0",
+    "@aihu/context": "0.2.0",
+    "@aihu-plugin/data": "2.0.5"
+  },
+  "optionalDependencies": {
+    "@aihu/magna-gqlmin": "^0.2.0"
+  },
+  "devDependencies": {
+    "rolldown": "^1.0.0-rc.17",
+    "rolldown-plugin-dts": "^0.23.2",
+    "typescript": "^5.6.2",
+    "vitest": "^3.2.6"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fellwork/aihu.git",
+    "directory": "packages/magna"
+  },
+  "homepage": "https://github.com/fellwork/aihu/tree/main/packages/magna#readme",
+  "bugs": "https://github.com/fellwork/aihu/issues",
+  "publishConfig": {
+    "access": "public"
+  }
+}