@donghanh/core 0.1.0

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@donghanh/core",
+  "version": "0.1.0",
+  "description": "Custom JSX runtime for conversational UI — primitives, registry, executor",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./jsx-runtime": "./src/jsx-runtime.ts",
+    "./jsx-dev-runtime": "./src/jsx-dev-runtime.ts"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rezzahub/donghanh",
+    "directory": "packages/core"
+  },
+  "peerDependencies": {
+    "typescript": "^5.0.0"
+  }
+}

package/src/execute.ts

@@ -0,0 +1,30 @@
+import type { ChatNode } from "./primitives";
+import type { Registry } from "./registry";
+import type { Executor, ExecutorContext } from "./types";
+
+export interface ExecuteResult {
+  data: unknown;
+  brief: ChatNode;
+}
+
+export async function executeOperation(opts: {
+  registry: Registry;
+  operationId: string;
+  variables: Record<string, unknown>;
+  executor: Executor;
+  context: ExecutorContext;
+}): Promise<ExecuteResult> {
+  const { registry, operationId, variables, executor, context } = opts;
+
+  const operation = registry.get(operationId);
+  if (!operation) {
+    throw new Error(
+      `Unknown operation "${operationId}". Call GET /api/gpt/operations to discover available operations.`,
+    );
+  }
+
+  const data = await executor(operationId, variables, context);
+  const brief = operation({ data, variables });
+
+  return { data, brief };
+}

package/src/index.ts

@@ -0,0 +1,34 @@
+export type { ExecuteResult } from "./execute";
+export { executeOperation } from "./execute";
+export type {
+  ActionNode,
+  AppNode,
+  BriefNode,
+  ChatNode,
+  ContextNode,
+  DisplayNode,
+  FieldDef,
+  FormNode,
+  MessageNode,
+} from "./primitives";
+export {
+  Action,
+  App,
+  Brief,
+  Context,
+  Display,
+  Form,
+  Message,
+} from "./primitives";
+export type { CompactOperation, OperationDetail, Registry } from "./registry";
+export { buildRegistry } from "./registry";
+export type { Renderer } from "./render";
+export { renderNode } from "./render";
+export type {
+  Executor,
+  ExecutorContext,
+  OperationComponent,
+  OperationConfig,
+  OperationProps,
+} from "./types";
+export { registerOperation } from "./types";

package/src/jsx-dev-runtime.ts

@@ -0,0 +1,12 @@
+import type { ChatNode } from "./primitives";
+
+type ComponentFn = (props: Record<string, unknown>) => ChatNode;
+
+export function jsxDEV(
+  type: ComponentFn,
+  props: Record<string, unknown>,
+): ChatNode {
+  return type(props);
+}
+
+export { Fragment } from "./jsx-runtime";

package/src/jsx-runtime.ts

@@ -0,0 +1,24 @@
+import type { ChatNode } from "./primitives";
+
+type ComponentFn = (props: Record<string, unknown>) => ChatNode;
+
+export function jsx(
+  type: ComponentFn,
+  props: Record<string, unknown>,
+): ChatNode {
+  return type(props);
+}
+
+export function jsxs(
+  type: ComponentFn,
+  props: Record<string, unknown>,
+): ChatNode {
+  return type(props);
+}
+
+export function Fragment(props: {
+  children?: ChatNode | ChatNode[];
+}): ChatNode[] {
+  if (!props.children) return [];
+  return Array.isArray(props.children) ? props.children : [props.children];
+}

package/src/jsx.d.ts

@@ -0,0 +1,9 @@
+declare namespace JSX {
+  type Element = import("./primitives").ChatNode;
+  // biome-ignore lint/complexity/noBannedTypes: required for JSX IntrinsicElements
+  type IntrinsicElements = {};
+
+  interface ElementChildrenAttribute {
+    children: unknown;
+  }
+}

package/src/primitives.test.ts

@@ -0,0 +1,139 @@
+import { describe, expect, test } from "bun:test";
+import type { ChatNode, Renderer } from "./index";
+import { Fragment, jsx, jsxs } from "./jsx-runtime";
+// Test the JSX runtime + primitives by simulating what the transpiler produces
+import { Action, Brief, Display } from "./primitives";
+import { renderNode } from "./render";
+
+// Simple renderer that collects node types for verification
+const collectTypes: Renderer<string[]> = {
+  brief(_node, children) {
+    return children.flat();
+  },
+  message(node) {
+    return [`message:${node.content}`];
+  },
+  action(node) {
+    return [`action:${node.operation}`];
+  },
+  form() {
+    return ["form"];
+  },
+  display() {
+    return ["display"];
+  },
+  context() {
+    return ["context"];
+  },
+};
+
+describe("Brief with nested fragments from map", () => {
+  test("map returning fragments produces valid children", () => {
+    // Simulates what JSX transpiler produces for:
+    //   <Brief>
+    //     Some text
+    //     {items.map(item => (
+    //       <>
+    //         <Display data={item.data} />
+    //         <Action operation={item.op} label={item.label} />
+    //       </>
+    //     ))}
+    //   </Brief>
+
+    const items = [
+      { data: "balance1", op: "settle-1", label: "Settle 1" },
+      { data: "balance2", op: "settle-2", label: "Settle 2" },
+    ];
+
+    // Fragment produces ChatNode[]
+    const fragments = items.map((item) =>
+      jsx(Fragment as any, {
+        children: [
+          jsx(Display as any, { data: item.data }),
+          jsx(Action as any, { operation: item.op, label: item.label }),
+        ],
+      }),
+    );
+
+    // Brief receives [string, ...ChatNode[][]] as children
+    const brief = jsxs(Brief as any, {
+      children: ["Some text", ...fragments],
+    });
+
+    // This should not throw — all children should be valid ChatNode objects
+    expect(brief.type).toBe("brief");
+
+    const types = renderNode(brief as ChatNode, collectTypes);
+    expect(types).toContain("message:Some text");
+    expect(types).toContain("display");
+    expect(types).toContain("action:settle-1");
+    expect(types).toContain("action:settle-2");
+  });
+
+  test("deeply nested arrays from map+filter+map are flattened", () => {
+    // Simulates:
+    //   <Brief>
+    //     {groups.map(group => (
+    //       <>
+    //         <Display data={group.display} />
+    //         {group.debts.filter(...).map(debt => (
+    //           <Action operation="settle" label={debt.label} />
+    //         ))}
+    //       </>
+    //     ))}
+    //   </Brief>
+
+    const groups = [
+      {
+        display: "Group 1 balances",
+        debts: [{ label: "Debt A" }, { label: "Debt B" }],
+      },
+    ];
+
+    const fragments = groups.map((group) => {
+      const debtActions = group.debts.map((debt) =>
+        jsx(Action as any, { operation: "settle", label: debt.label }),
+      );
+      return jsx(Fragment as any, {
+        children: [
+          jsx(Display as any, { data: group.display }),
+          ...debtActions,
+        ],
+      });
+    });
+
+    const brief = jsxs(Brief as any, {
+      children: [...fragments],
+    });
+
+    expect(brief.type).toBe("brief");
+
+    const types = renderNode(brief as ChatNode, collectTypes);
+    expect(types).toContain("display");
+    expect(types).toContain("action:settle");
+    expect(types).toHaveLength(3); // 1 display + 2 actions
+  });
+
+  test("null and undefined children from conditional rendering are filtered", () => {
+    // Simulates:
+    //   <Brief>
+    //     {condition && <Display data="x" />}
+    //     <Action operation="a" label="A" />
+    //   </Brief>
+
+    const brief = jsxs(Brief as any, {
+      children: [
+        false, // condition && <Display />
+        null,
+        undefined,
+        jsx(Action as any, { operation: "a", label: "A" }),
+      ],
+    });
+
+    expect(brief.type).toBe("brief");
+
+    // Should not throw on null/undefined/false children
+    const types = renderNode(brief as ChatNode, collectTypes);
+    expect(types).toContain("action:a");
+  });
+});

package/src/primitives.ts

@@ -0,0 +1,129 @@
+// --- Node types ---
+
+export interface BriefNode {
+  type: "brief";
+  children: ChatNode[];
+}
+
+export interface MessageNode {
+  type: "message";
+  content: string;
+}
+
+export interface ActionNode {
+  type: "action";
+  operation: string;
+  label: string;
+  variables?: Record<string, unknown>;
+}
+
+export interface FormNode {
+  type: "form";
+  fields: FieldDef[];
+  operation: string;
+}
+
+export interface DisplayNode {
+  type: "display";
+  data: unknown;
+}
+
+export interface ContextNode {
+  type: "context";
+  value: unknown;
+}
+
+export interface AppNode {
+  type: "app";
+  operations: OperationRef[];
+}
+
+export interface FieldDef {
+  name: string;
+  type: string;
+  label?: string;
+  required?: boolean;
+}
+
+export interface OperationRef {
+  component: OperationComponentAny;
+}
+
+export type ChatNode =
+  | BriefNode
+  | MessageNode
+  | ActionNode
+  | FormNode
+  | DisplayNode
+  | ContextNode;
+
+// Minimal type for OperationComponent used in primitives (avoids circular dep)
+interface OperationComponentAny {
+  operationConfig: { id: string };
+}
+
+// --- Helpers ---
+
+function flatChildren(children: Child | Child[]): (ChatNode | string)[] {
+  if (children == null || typeof children === "boolean") return [];
+  if (Array.isArray(children))
+    return (children.flat(Infinity) as unknown[]).filter(
+      (c): c is ChatNode | string => c != null && typeof c !== "boolean",
+    );
+  return [children];
+}
+
+function toNode(child: ChatNode | string): ChatNode {
+  if (typeof child === "string") return { type: "message", content: child };
+  return child;
+}
+
+// --- Component functions ---
+
+type Child = ChatNode | ChatNode[] | string | boolean | undefined | null;
+
+export function Brief(props: { children?: Child | Child[] }): BriefNode {
+  const flat = flatChildren(props.children);
+  return { type: "brief", children: flat.map(toNode) };
+}
+
+export function Message(props: { children?: string }): MessageNode {
+  return { type: "message", content: props.children ?? "" };
+}
+
+export function Action(props: {
+  operation: string;
+  label: string;
+  variables?: Record<string, unknown>;
+}): ActionNode {
+  return {
+    type: "action",
+    operation: props.operation,
+    label: props.label,
+    variables: props.variables,
+  };
+}
+
+export function Form(props: {
+  fields: FieldDef[];
+  operation: string;
+}): FormNode {
+  return { type: "form", fields: props.fields, operation: props.operation };
+}
+
+export function Display(props: { data: unknown }): DisplayNode {
+  return { type: "display", data: props.data };
+}
+
+export function Context(props: { value: unknown }): ContextNode {
+  return { type: "context", value: props.value };
+}
+
+export function App(props: {
+  operations: Record<string, OperationComponentAny>;
+}): AppNode {
+  const ops = Object.values(props.operations).map((component) => ({
+    component,
+  }));
+  return { type: "app", operations: ops };
+}

package/src/registry.ts

@@ -0,0 +1,63 @@
+import type { AppNode } from "./primitives";
+import type { OperationComponent } from "./types";
+
+export interface CompactOperation {
+  id: string;
+  type: "query" | "mutation";
+  description: string;
+}
+
+export interface OperationDetail {
+  id: string;
+  type: "query" | "mutation";
+  description: string;
+  instruction: string;
+  input: object;
+  response?: object;
+}
+
+export interface Registry {
+  list(): CompactOperation[];
+  detail(name: string): OperationDetail | null;
+  get(name: string): OperationComponent | undefined;
+}
+
+export function buildRegistry(
+  appNode: AppNode,
+  responseSchemas?: Record<string, object>,
+): Registry {
+  const map = new Map<string, OperationComponent>();
+
+  for (const ref of appNode.operations) {
+    const op = ref.component as OperationComponent;
+    map.set(op.operationConfig.id, op);
+  }
+
+  return {
+    list(): CompactOperation[] {
+      return Array.from(map.values()).map((op) => ({
+        id: op.operationConfig.id,
+        type: op.operationConfig.type,
+        description: op.operationConfig.description,
+      }));
+    },
+
+    detail(name: string): OperationDetail | null {
+      const op = map.get(name);
+      if (!op) return null;
+      const config = op.operationConfig;
+      return {
+        id: config.id,
+        type: config.type,
+        description: config.description,
+        instruction: config.instruction,
+        input: config.input,
+        response: responseSchemas?.[name],
+      };
+    },
+
+    get(name: string): OperationComponent | undefined {
+      return map.get(name);
+    },
+  };
+}

package/src/render.ts

@@ -0,0 +1,39 @@
+import type {
+  ActionNode,
+  BriefNode,
+  ChatNode,
+  ContextNode,
+  DisplayNode,
+  FormNode,
+  MessageNode,
+} from "./primitives";
+
+export interface Renderer<T> {
+  brief(node: BriefNode, children: T[]): T;
+  message(node: MessageNode): T;
+  action(node: ActionNode): T;
+  form(node: FormNode): T;
+  display(node: DisplayNode): T;
+  context(node: ContextNode): T;
+}
+
+export function renderNode<T>(node: ChatNode, renderer: Renderer<T>): T {
+  switch (node.type) {
+    case "brief": {
+      const children = node.children.map((child) =>
+        renderNode(child, renderer),
+      );
+      return renderer.brief(node, children);
+    }
+    case "message":
+      return renderer.message(node);
+    case "action":
+      return renderer.action(node);
+    case "form":
+      return renderer.form(node);
+    case "display":
+      return renderer.display(node);
+    case "context":
+      return renderer.context(node);
+  }
+}

package/src/types.ts

@@ -0,0 +1,40 @@
+import type { ChatNode } from "./primitives";
+
+export interface OperationProps<T = any> {
+  data: T;
+  variables: Record<string, unknown>;
+}
+
+export interface OperationConfig {
+  id: string;
+  type: "query" | "mutation";
+  description: string;
+  instruction: string;
+  input: object;
+  responseKey: string;
+}
+
+export interface OperationComponent<T = any> {
+  (props: OperationProps<T>): ChatNode;
+  operationConfig: OperationConfig;
+}
+
+export function registerOperation<T = any>(
+  component: (props: OperationProps<T>) => ChatNode,
+  config: OperationConfig,
+): OperationComponent<T> {
+  const op = component as OperationComponent<T>;
+  op.operationConfig = config;
+  return op;
+}
+
+export type Executor = (
+  operationId: string,
+  variables: Record<string, unknown>,
+  context: ExecutorContext,
+) => Promise<unknown>;
+
+export interface ExecutorContext {
+  userId: string;
+  request: Request;
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "jsxImportSource": "@donghanh/core",
+    "skipLibCheck": true
+  },
+  "include": ["src"]
+}