freesail 0.0.1 → 0.1.0

package/packages/lit-ui/src/utils/define-props.ts

@@ -0,0 +1,157 @@
+/**
+ * defineProps Utility
+ * 
+ * Hydrates Lit component properties directly from the Catalog JSON.
+ * This is the core of the "Dry" Law - Schema-First Components.
+ */
+
+import type { PropertyDeclaration } from 'lit';
+import type { CatalogDefinition, PropertyDefinition } from '../types.js';
+
+/**
+ * Convert JSON Schema type to Lit property type
+ */
+function schemaTypeToLitType(schemaProp: PropertyDefinition): PropertyDeclaration {
+  let type: typeof String | typeof Number | typeof Boolean | typeof Array | typeof Object = String;
+
+  switch (schemaProp.type) {
+    case 'string':
+      type = String;
+      break;
+    case 'number':
+    case 'integer':
+      type = Number;
+      break;
+    case 'boolean':
+      type = Boolean;
+      break;
+    case 'array':
+      type = Array;
+      break;
+    case 'object':
+      type = Object;
+      break;
+    default:
+      type = String;
+  }
+
+  return {
+    type,
+    reflect: schemaProp.reflect ?? false,
+  };
+}
+
+/**
+ * Generate Lit property declarations from a catalog component definition
+ * 
+ * @param catalog - The catalog JSON object
+ * @param componentName - Name of the component in the catalog
+ * @returns Property declarations for use with Lit's static properties
+ * 
+ * @example
+ * ```ts
+ * import catalog from './catalog.json';
+ * 
+ * export class FreesailText extends LitElement {
+ *   static properties = defineProps(catalog, 'Text');
+ * }
+ * ```
+ */
+export function defineProps(
+  catalog: CatalogDefinition,
+  componentName: string
+): Record<string, PropertyDeclaration> {
+  const componentDef = catalog.components?.[componentName];
+  
+  if (!componentDef) {
+    console.warn(`[defineProps] Component "${componentName}" not found in catalog`);
+    return {};
+  }
+
+  const properties: Record<string, PropertyDeclaration> = {};
+
+  // Process component properties
+  if (componentDef.properties) {
+    for (const [propName, propDef] of Object.entries(componentDef.properties)) {
+      properties[propName] = schemaTypeToLitType(propDef);
+    }
+  }
+
+  return properties;
+}
+
+/**
+ * Get default values for a component from the catalog
+ */
+export function getDefaults(
+  catalog: CatalogDefinition,
+  componentName: string
+): Record<string, unknown> {
+  const componentDef = catalog.components?.[componentName];
+  
+  if (!componentDef) {
+    return {};
+  }
+
+  const defaults: Record<string, unknown> = {};
+
+  if (componentDef.properties) {
+    for (const [propName, propDef] of Object.entries(componentDef.properties)) {
+      if (propDef.default !== undefined) {
+        defaults[propName] = propDef.default;
+      }
+    }
+  }
+
+  return defaults;
+}
+
+/**
+ * Validate a component's properties against the catalog schema
+ */
+export function validateProps(
+  catalog: CatalogDefinition,
+  componentName: string,
+  props: Record<string, unknown>
+): { valid: boolean; errors: string[] } {
+  const componentDef = catalog.components?.[componentName];
+  const errors: string[] = [];
+
+  if (!componentDef) {
+    errors.push(`Component "${componentName}" not found in catalog`);
+    return { valid: false, errors };
+  }
+
+  // Check required properties
+  if (componentDef.required) {
+    for (const required of componentDef.required) {
+      if (props[required] === undefined || props[required] === null) {
+        errors.push(`Missing required property: ${required}`);
+      }
+    }
+  }
+
+  // Type check properties
+  if (componentDef.properties) {
+    for (const [propName, propValue] of Object.entries(props)) {
+      const propDef = componentDef.properties[propName];
+      
+      if (!propDef) {
+        // Allow additional properties unless explicitly forbidden
+        continue;
+      }
+
+      const actualType = Array.isArray(propValue) ? 'array' : typeof propValue;
+      const expectedType = propDef.type;
+
+      if (actualType !== expectedType && 
+          !(expectedType === 'integer' && actualType === 'number')) {
+        errors.push(
+          `Property "${propName}" expected ${expectedType}, got ${actualType}`
+        );
+      }
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}

package/packages/lit-ui/src/utils/index.ts

@@ -0,0 +1,2 @@
+export { defineProps, getDefaults, validateProps } from './define-props.js';
+export { ComponentRegistry, registry } from './registry.js';

package/packages/lit-ui/src/utils/registry.ts

@@ -0,0 +1,139 @@
+/**
+ * Component Registry
+ * 
+ * Manages the registration and retrieval of Web Components
+ * based on catalog definitions.
+ */
+
+import type { LitElement } from 'lit';
+import type { CatalogDefinition } from '../types.js';
+
+type ComponentConstructor = typeof LitElement;
+
+interface RegisteredCatalog {
+  definition: CatalogDefinition;
+  components: Map<string, ComponentConstructor>;
+  prefix: string;
+}
+
+/**
+ * ComponentRegistry manages Web Component registration by catalog.
+ * It ensures components are properly registered with unique prefixes
+ * and handles dynamic component resolution.
+ */
+export class ComponentRegistry {
+  private catalogs: Map<string, RegisteredCatalog> = new Map();
+  private globalComponents: Map<string, ComponentConstructor> = new Map();
+
+  /**
+   * Register a catalog and its components
+   */
+  registerCatalog(
+    catalogId: string,
+    definition: CatalogDefinition,
+    components: Map<string, ComponentConstructor>,
+    prefix: string = 'fs'
+  ): void {
+    // Validate catalog
+    if (!definition.id || !definition.version) {
+      console.warn(`[Registry] Invalid catalog definition for ${catalogId}`);
+    }
+
+    // Store catalog
+    this.catalogs.set(catalogId, {
+      definition,
+      components,
+      prefix,
+    });
+
+    // Register each component as a custom element
+    for (const [componentName, ComponentClass] of components) {
+      const tagName = this.getTagName(prefix, componentName);
+      
+      if (!customElements.get(tagName)) {
+        try {
+          customElements.define(tagName, ComponentClass);
+        } catch (error) {
+          console.error(`[Registry] Failed to register ${tagName}:`, error);
+        }
+      }
+
+      // Also store in global lookup
+      this.globalComponents.set(`${catalogId}:${componentName}`, ComponentClass);
+    }
+  }
+
+  /**
+   * Get a component class by catalog and name
+   */
+  getComponent(catalogId: string, componentName: string): ComponentConstructor | undefined {
+    const catalog = this.catalogs.get(catalogId);
+    return catalog?.components.get(componentName);
+  }
+
+  /**
+   * Get the HTML tag name for a component
+   */
+  getTagName(prefix: string, componentName: string): string {
+    // Convert PascalCase to kebab-case
+    const kebab = componentName
+      .replace(/([a-z])([A-Z])/g, '$1-$2')
+      .toLowerCase();
+    return `${prefix}-${kebab}`;
+  }
+
+  /**
+   * Get tag name for a component in a specific catalog
+   */
+  getTagNameForCatalog(catalogId: string, componentName: string): string | undefined {
+    const catalog = this.catalogs.get(catalogId);
+    if (!catalog) return undefined;
+    return this.getTagName(catalog.prefix, componentName);
+  }
+
+  /**
+   * Check if a catalog is registered
+   */
+  hasCatalog(catalogId: string): boolean {
+    return this.catalogs.has(catalogId);
+  }
+
+  /**
+   * Get catalog definition
+   */
+  getCatalogDefinition(catalogId: string): CatalogDefinition | undefined {
+    return this.catalogs.get(catalogId)?.definition;
+  }
+
+  /**
+   * Get all registered catalog IDs
+   */
+  getCatalogIds(): string[] {
+    return Array.from(this.catalogs.keys());
+  }
+
+  /**
+   * Get all component names in a catalog
+   */
+  getComponentNames(catalogId: string): string[] {
+    const catalog = this.catalogs.get(catalogId);
+    return catalog ? Array.from(catalog.components.keys()) : [];
+  }
+
+  /**
+   * Unregister a catalog (components remain in DOM but won't be found)
+   */
+  unregisterCatalog(catalogId: string): void {
+    const catalog = this.catalogs.get(catalogId);
+    if (catalog) {
+      // Remove from global lookup
+      for (const componentName of catalog.components.keys()) {
+        this.globalComponents.delete(`${catalogId}:${componentName}`);
+      }
+      this.catalogs.delete(catalogId);
+    }
+  }
+}
+
+// Singleton instance
+export const registry = new ComponentRegistry();

package/packages/lit-ui/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "composite": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*", "src/**/*.json"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}

package/packages/server/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@freesail/server",
+  "version": "0.1.0",
+  "description": "Freesail Server - SSE Stream Engine & Framework Adapters",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./adapters/langchain": {
+      "types": "./dist/adapters/langchain.d.ts",
+      "import": "./dist/adapters/langchain.js"
+    },
+    "./adapters/openai": {
+      "types": "./dist/adapters/openai.d.ts",
+      "import": "./dist/adapters/openai.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src --ext .ts"
+  },
+  "dependencies": {
+    "@freesail/core": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "typescript": "^5.3.3",
+    "vitest": "^1.2.0"
+  },
+  "peerDependencies": {
+    "langchain": ">=0.1.0",
+    "openai": ">=4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "langchain": {
+      "optional": true
+    },
+    "openai": {
+      "optional": true
+    }
+  },
+  "keywords": [
+    "sse",
+    "stream",
+    "langchain",
+    "openai",
+    "a2ux"
+  ],
+  "license": "MIT"
+}

package/packages/server/src/adapters/index.ts

@@ -0,0 +1,5 @@
+export { createLangChainTools, createLangChainRenderUITool, createLangChainUpdateDataTool } from './langchain.js';
+export type { LangChainAdapterOptions } from './langchain.js';
+
+export { OpenAIAdapter, createOpenAIAdapter, processOpenAIResponse } from './openai.js';
+export type { OpenAIAdapterOptions, ToolCallResult } from './openai.js';

package/packages/server/src/adapters/langchain.ts

@@ -0,0 +1,175 @@
+/**
+ * LangChain Adapter
+ * 
+ * Converts Freesail tools to LangChain DynamicStructuredTool format.
+ * This adapter allows using Freesail with LangChain agents.
+ * 
+ * NOTE: This adapter requires 'langchain' as a peer dependency.
+ */
+
+import type { ToolSchema } from '../catalog-loader.js';
+import type { FreesailStream } from '../stream.js';
+import { toolCallToMessages, updateDataToMessage } from '../catalog-loader.js';
+
+// =============================================================================
+// Types (Minimal LangChain interfaces to avoid direct import)
+// =============================================================================
+
+interface LangChainToolInput {
+  name: string;
+  description: string;
+  schema: unknown; // Zod schema
+  func: (input: unknown) => Promise<string>;
+}
+
+interface ZodObjectLike {
+  parse: (input: unknown) => unknown;
+}
+
+// =============================================================================
+// LangChain Adapter
+// =============================================================================
+
+export interface LangChainAdapterOptions {
+  /** The SSE stream to send messages to */
+  stream: FreesailStream;
+  /** Catalog ID being used */
+  catalogId: string;
+  /** Callback after UI is rendered */
+  onRenderUI?: (surfaceId: string) => void;
+  /** Callback after data is updated */
+  onUpdateData?: (surfaceId: string) => void;
+}
+
+/**
+ * Creates a LangChain DynamicStructuredTool configuration for render_ui
+ */
+export function createLangChainRenderUITool(
+  toolSchema: ToolSchema,
+  options: LangChainAdapterOptions,
+  z: { object: Function; string: Function; array: Function; any: Function }
+): LangChainToolInput {
+  const { stream, catalogId, onRenderUI } = options;
+
+  // Build Zod schema from tool schema
+  const zodSchema = buildZodSchema(toolSchema.parameters, z);
+
+  return {
+    name: toolSchema.name,
+    description: toolSchema.description,
+    schema: zodSchema,
+    func: async (input: unknown) => {
+      const { surfaceId, components } = input as { 
+        surfaceId: string; 
+        components: Array<{ id: string; component: string; [key: string]: unknown }>;
+      };
+
+      // Convert to A2UX messages and send
+      const messages = toolCallToMessages({ surfaceId, components }, catalogId);
+      
+      for (const message of messages) {
+        stream.send(message);
+      }
+
+      onRenderUI?.(surfaceId);
+
+      return `UI surface "${surfaceId}" created with ${components.length} components.`;
+    },
+  };
+}
+
+/**
+ * Creates a LangChain DynamicStructuredTool configuration for update_data
+ */
+export function createLangChainUpdateDataTool(
+  toolSchema: ToolSchema,
+  options: LangChainAdapterOptions,
+  z: { object: Function; string: Function; optional: Function; any: Function; enum: Function }
+): LangChainToolInput {
+  const { stream, onUpdateData } = options;
+
+  // Build Zod schema
+  const zodSchema = z.object({
+    surfaceId: z.string(),
+    path: z.string().optional(),
+    value: z.any(),
+    operation: z.enum(['add', 'replace', 'remove']).optional(),
+  });
+
+  return {
+    name: toolSchema.name,
+    description: toolSchema.description,
+    schema: zodSchema,
+    func: async (input: unknown) => {
+      const toolCall = input as { 
+        surfaceId: string; 
+        path?: string; 
+        value: unknown; 
+        operation?: string;
+      };
+
+      const message = updateDataToMessage(toolCall);
+      stream.send(message);
+
+      onUpdateData?.(toolCall.surfaceId);
+
+      return `Data updated at path "${toolCall.path || '/'}" in surface "${toolCall.surfaceId}".`;
+    },
+  };
+}
+
+/**
+ * Create all Freesail tools for LangChain
+ * 
+ * @example
+ * ```ts
+ * import { z } from 'zod';
+ * import { DynamicStructuredTool } from 'langchain/tools';
+ * 
+ * const toolConfigs = createLangChainTools(converter, catalogId, { stream, catalogId }, z);
+ * const tools = toolConfigs.map(config => new DynamicStructuredTool(config));
+ * ```
+ */
+export function createLangChainTools(
+  converter: { generateRenderUITool: (id: string) => ToolSchema; generateUpdateDataTool: () => ToolSchema },
+  catalogId: string,
+  options: LangChainAdapterOptions,
+  z: unknown // Zod instance
+): LangChainToolInput[] {
+  const zod = z as { object: Function; string: Function; array: Function; any: Function; optional: Function; enum: Function };
+  
+  return [
+    createLangChainRenderUITool(converter.generateRenderUITool(catalogId), options, zod),
+    createLangChainUpdateDataTool(converter.generateUpdateDataTool(), options, zod),
+  ];
+}
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+function buildZodSchema(
+  schema: ToolSchema['parameters'],
+  z: { object: Function; string: Function; array: Function; any: Function; enum?: Function }
+): ZodObjectLike {
+  const properties: Record<string, unknown> = {};
+
+  for (const [key, value] of Object.entries(schema.properties)) {
+    const prop = value as { type: string; enum?: string[]; items?: unknown };
+    
+    if (prop.type === 'string') {
+      properties[key] = (prop.enum && z.enum) ? z.enum(prop.enum as [string, ...string[]]) : z.string();
+    } else if (prop.type === 'array') {
+      properties[key] = z.array(z.any());
+    } else {
+      properties[key] = z.any();
+    }
+
+    // Make optional if not required
+    if (!schema.required.includes(key)) {
+      properties[key] = (properties[key] as { optional?: Function }).optional?.() ?? properties[key];
+    }
+  }
+
+  return z.object(properties) as ZodObjectLike;
+}