luca 2.0.0 → 3.0.2

package/src/endpoint.ts

@@ -0,0 +1,365 @@
+import { Helper } from './helper.js'
+import type { Container, ContainerContext } from './container.js'
+import { Registry } from './registry.js'
+import { z } from 'zod'
+import { EndpointStateSchema, EndpointOptionsSchema, EndpointEventsSchema } from './schemas/base.js'
+
+export interface AvailableEndpoints {}
+
+export type EndpointState = z.infer<typeof EndpointStateSchema>
+export type EndpointOptions = z.infer<typeof EndpointOptionsSchema>
+
+export type EndpointHandler = (
+  parameters: Record<string, any>,
+  context: EndpointContext
+) => Promise<any> | any
+
+export type EndpointContext = {
+  container: Container<any>
+  request: any
+  response: any
+  query: Record<string, any>
+  body: Record<string, any>
+  params: Record<string, any>
+}
+
+export interface EndpointRateLimit {
+  /** Maximum requests allowed per window */
+  maxRequests: number
+  /** Window size in seconds (default: 1) */
+  windowSeconds?: number
+}
+
+export interface EndpointModule {
+  path: string
+  get?: EndpointHandler
+  post?: EndpointHandler
+  put?: EndpointHandler
+  patch?: EndpointHandler
+  delete?: EndpointHandler
+  getSchema?: z.ZodType
+  postSchema?: z.ZodType
+  putSchema?: z.ZodType
+  patchSchema?: z.ZodType
+  deleteSchema?: z.ZodType
+  /** Rate limit applied to all methods on this endpoint */
+  rateLimit?: EndpointRateLimit
+  /** Per-method rate limits (overrides the endpoint-level rateLimit) */
+  getRateLimit?: EndpointRateLimit
+  postRateLimit?: EndpointRateLimit
+  putRateLimit?: EndpointRateLimit
+  patchRateLimit?: EndpointRateLimit
+  deleteRateLimit?: EndpointRateLimit
+  description?: string
+  tags?: string[]
+}
+
+const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete'] as const
+
+/** All recognized exports on an endpoint module */
+const KNOWN_EXPORTS = new Set([
+  'path', 'description', 'tags', 'default', 'rateLimit',
+  ...HTTP_METHODS,
+  ...HTTP_METHODS.map(m => `${m}Schema`),
+  ...HTTP_METHODS.map(m => `${m}RateLimit`),
+])
+
+/**
+ * Sliding-window rate limiter keyed by IP address.
+ * Tracks timestamps of requests and prunes entries older than the window.
+ */
+class RateLimiter {
+  private _windows = new Map<string, number[]>()
+
+  /** Returns true if the request is allowed, false if rate-limited. */
+  allow(key: string, maxRequests: number, windowMs: number): boolean {
+    const now = Date.now()
+    let timestamps = this._windows.get(key)
+
+    if (!timestamps) {
+      timestamps = []
+      this._windows.set(key, timestamps)
+    }
+
+    // Prune timestamps outside the window
+    while (timestamps.length > 0 && (timestamps[0] ?? 0) <= now - windowMs) {
+      timestamps.shift()
+    }
+
+    if (timestamps.length >= maxRequests) {
+      return false
+    }
+
+    timestamps.push(now)
+    return true
+  }
+
+  /** Clear all tracking state */
+  reset(): void {
+    this._windows.clear()
+  }
+}
+
+export type EndpointFactory = <T extends keyof AvailableEndpoints>(
+  key: T,
+  options?: ConstructorParameters<AvailableEndpoints[T]>[0]
+) => NonNullable<InstanceType<AvailableEndpoints[T]>>
+
+export interface EndpointsInterface {
+  endpoints: EndpointsRegistry
+  endpoint: EndpointFactory
+}
+
+export class Endpoint<
+  T extends EndpointState = EndpointState,
+  K extends EndpointOptions = EndpointOptions
+> extends Helper<T, K> {
+  static override shortcut = 'endpoints.base'
+  static override description = 'File-based HTTP endpoint with Remix-like DX'
+  static override stateSchema = EndpointStateSchema
+  static override optionsSchema = EndpointOptionsSchema
+  static override eventsSchema = EndpointEventsSchema
+
+  private _module: EndpointModule | null = null
+  private _rateLimiter = new RateLimiter()
+
+  static attach(container: Container & EndpointsInterface): any {
+    Object.assign(container, {
+      get endpoints() {
+        return endpoints
+      },
+
+      endpoint<T extends keyof AvailableEndpoints>(
+        id: T,
+        options?: ConstructorParameters<AvailableEndpoints[T]>[0]
+      ): InstanceType<AvailableEndpoints[T]> {
+        const BaseClass = endpoints.lookup(id as string) as any
+
+        return container.createHelperInstance({
+          cache: helperCache,
+          type: 'endpoint',
+          id: String(id),
+          BaseClass,
+          options,
+          fallbackName: String(id),
+        }) as InstanceType<AvailableEndpoints[T]>
+      },
+    })
+
+    container.registerHelperType('endpoints', 'endpoint')
+
+    return container
+  }
+
+  override get initialState(): T {
+    return ({
+      mounted: false,
+      path: this.options.path || '',
+      methods: [],
+      requestCount: 0,
+    } as unknown) as T
+  }
+
+  get path() {
+    return this.options.path
+  }
+
+  get module() {
+    return this._module
+  }
+
+  get methods(): string[] {
+    if (!this._module) return []
+    return HTTP_METHODS.filter((m) => typeof (this._module as any)[m] === 'function')
+  }
+
+  get isMounted() {
+    return !!this.state.get('mounted')
+  }
+
+  async load(mod?: EndpointModule): Promise<this> {
+    if (mod) {
+      this._module = mod
+    } else if (this.options.filePath) {
+      const imported = await import(`${this.options.filePath}?t=${Date.now()}`)
+      this._module = imported.default || imported
+    }
+
+    // Note: DELETE handlers should be exported as `export { del as delete }`.
+    // We no longer remap `destroy` → `delete` because ESM namespace objects
+    // are frozen and the mutation throws on Bun.
+
+    this.state.set('methods', this.methods)
+    this.state.set('path', this.path)
+    this.emit('loaded', this._module)
+    return this
+  }
+
+  async reload(): Promise<this> {
+    this._module = null
+    if (this.options.filePath) {
+      const helpers = this.container.feature('helpers') as any
+      const mod = await helpers.loadModuleExports(this.options.filePath, { cacheBust: true })
+      const endpointModule: EndpointModule = mod.default || mod
+      return this.load(endpointModule)
+    }
+    return this.load()
+  }
+
+  handler(method: string): EndpointHandler | undefined {
+    return this._module?.[method as keyof EndpointModule] as EndpointHandler | undefined
+  }
+
+  schema(method: string): z.ZodType | undefined {
+    return this._module?.[`${method}Schema` as keyof EndpointModule] as z.ZodType | undefined
+  }
+
+  /** Returns the rate limit config for a given method, or undefined if none. */
+  rateLimitFor(method: string): EndpointRateLimit | undefined {
+    const perMethod = this._module?.[`${method}RateLimit` as keyof EndpointModule] as EndpointRateLimit | undefined
+    return perMethod || this._module?.rateLimit
+  }
+
+  /** Access the rate limiter instance (useful for testing or manual resets) */
+  get rateLimiter(): RateLimiter {
+    return this._rateLimiter
+  }
+
+  mount(app: any): this {
+    for (const method of this.methods) {
+      const endpoint = this
+
+      app[method](this.path, async (req: any, res: any) => {
+        try {
+          // Rate limit check
+          const limit = endpoint.rateLimitFor(method)
+          if (limit) {
+            const ip = req.ip || req.socket?.remoteAddress || 'unknown'
+            const key = `${method}:${ip}`
+            const windowMs = (limit.windowSeconds ?? 1) * 1000
+            if (!endpoint._rateLimiter.allow(key, limit.maxRequests, windowMs)) {
+              endpoint.emit('error', new Error(`Rate limit exceeded for ${method.toUpperCase()} ${endpoint.path}`))
+              res.status(429).json({ error: 'Too Many Requests' })
+              return
+            }
+          }
+
+          const currentHandler = endpoint.handler(method)
+          if (!currentHandler) {
+            res.status(404).json({ error: 'Not found' })
+            return
+          }
+
+          const parameters = { ...req.query, ...req.body, ...req.params }
+          const currentSchema = endpoint.schema(method)
+          const validated = currentSchema ? currentSchema.parse(parameters) : parameters
+
+          const ctx: EndpointContext = {
+            container: endpoint.container,
+            request: req,
+            response: res,
+            query: req.query || {},
+            body: req.body || {},
+            params: req.params || {},
+          }
+
+          const result = await currentHandler(validated, ctx)
+          endpoint.state.set('requestCount', (endpoint.state.get('requestCount') || 0) + 1)
+          endpoint.emit('request', method, endpoint.path, parameters)
+
+          if (!res.headersSent) {
+            res.json(result)
+          }
+        } catch (err: any) {
+          endpoint.emit('error', err)
+          if (!res.headersSent) {
+            if (err.name === 'ZodError') {
+              const issues = err.issues || err.errors || []
+              const details = issues.map((e: any) => `${(e.path || []).join('.')}: ${e.message}`).join(', ')
+              console.error(`[${method.toUpperCase()} ${endpoint.path}] Validation failed: ${details}`)
+              res.status(400).json({ error: `Validation failed: ${details}`, details: issues })
+            } else {
+              console.error(`[${method.toUpperCase()} ${endpoint.path}] ${err.message}`)
+              res.status(500).json({ error: err.message })
+            }
+          }
+        }
+      })
+    }
+
+    this.state.set('mounted', true)
+    this.emit('mounted', this.path)
+    return this
+  }
+
+  toOpenAPIPathItem(): Record<string, any> {
+    const pathItem: Record<string, any> = {}
+
+    for (const method of this.methods) {
+      const methodSchema = this.schema(method)
+      const operationId = `${method}_${this.path.replace(/\//g, '_').replace(/^_/, '')}`
+
+      const operation: Record<string, any> = {
+        operationId,
+        summary: this._module?.description || `${method.toUpperCase()} ${this.path}`,
+        tags: this._module?.tags || [],
+        responses: {
+          '200': {
+            description: 'Successful response',
+            content: { 'application/json': { schema: { type: 'object' } } },
+          },
+          ...(this.rateLimitFor(method) ? { '429': { description: 'Rate limit exceeded' } } : {}),
+          '400': { description: 'Validation error' },
+          '500': { description: 'Server error' },
+        },
+      }
+
+      if (methodSchema) {
+        try {
+          const jsonSchema = (methodSchema as any).toJSONSchema()
+
+          if (method === 'get' || method === 'delete') {
+            operation.parameters = Object.entries((jsonSchema as any).properties || {}).map(
+              ([name, prop]: [string, any]) => ({
+                name,
+                in: 'query',
+                required: (jsonSchema as any).required?.includes(name) || false,
+                schema: prop,
+                description: prop.description || '',
+              })
+            )
+          } else {
+            operation.requestBody = {
+              required: true,
+              content: { 'application/json': { schema: jsonSchema } },
+            }
+          }
+        } catch {
+          // Schema conversion failed, serve without parameter docs
+        }
+      }
+
+      pathItem[method] = operation
+    }
+
+    return pathItem
+  }
+}
+
+export function warnUnknownExports(mod: Record<string, any>, filePath: string): void {
+  const unknown = Object.keys(mod).filter(k => !k.startsWith('__') && !KNOWN_EXPORTS.has(k))
+  if (unknown.length > 0) {
+    console.warn(`[endpoint] ${filePath}: unknown exports: ${unknown.join(', ')}`)
+  }
+}
+
+export class EndpointsRegistry extends Registry<Endpoint<any>> {
+  override scope = 'endpoints'
+  override baseClass = Endpoint
+}
+
+export const endpoints = new EndpointsRegistry()
+
+export const helperCache = new Map()
+
+export default Endpoint

package/src/entity.ts

@@ -0,0 +1,173 @@
+import { Bus, type EventMap } from './bus.js'
+import { State, type SetStateValue } from './state.js'
+import type { Container } from './container.js'
+import uuid from 'node-uuid'
+import { z } from 'zod'
+
+/**
+ * An Entity is a lightweight, composable object with observable state, a typed event bus,
+ * and a reference to the container. Unlike Helpers, Entities are not class-based — they
+ * are plain objects created directly via `container.entity()` and extended via `.extend()`.
+ *
+ * Same id + options always returns the same underlying state/bus instance (cached).
+ *
+ * @template TState   - Shape of the entity's observable state
+ * @template TOptions - Shape of the options passed at construction
+ * @template TEvents  - Event map for the typed event bus
+ */
+export type Entity<
+  TState extends Record<string, any> = Record<string, any>,
+  TOptions extends Record<string, any> = Record<string, any>,
+  TEvents extends EventMap = EventMap,
+> = {
+  /** The id passed to container.entity() */
+  readonly id: string
+  /** Per-instance UUID */
+  readonly uuid: string
+  /** The options the entity was created with */
+  readonly options: TOptions
+  /** Observable state */
+  readonly state: State<TState>
+  /** The container this entity belongs to */
+  readonly container: Container<any>
+
+  on<E extends keyof TEvents>(event: E, listener: (...args: TEvents[E]) => void): void
+  off<E extends keyof TEvents>(event: E, listener?: (...args: TEvents[E]) => void): void
+  once<E extends keyof TEvents>(event: E, listener: (...args: TEvents[E]) => void): void
+  emit<E extends keyof TEvents>(event: E, ...args: TEvents[E]): void
+  waitFor<E extends keyof TEvents>(event: E): Promise<TEvents[E]>
+  setState(value: SetStateValue<TState>): void
+
+  /**
+   * Graft an object of functions and getters onto this entity, returning a new type-safe
+   * object. The base entity (state, events, container, options) is accessible via `this`
+   * in all grafted methods and getters. Chaining `.extend()` on the result works correctly —
+   * each layer has access to everything in the layers below it.
+   *
+   * @example
+   * ```ts
+   * const session = container.entity('session:abc', { userId: '42' })
+   * const rich = session.extend({
+   *   greet() { return `Hello user ${this.options.userId}` },
+   *   get label() { return `Session ${this.id}` },
+   * })
+   * rich.greet() // "Hello user 42"
+   * ```
+   */
+  extend<Ext extends Record<string, any>>(
+    extensions: Ext & ThisType<Entity<TState, TOptions, TEvents> & Ext>
+  ): Entity<TState, TOptions, TEvents> & Ext
+
+  /**
+   * Register a method on this entity as an AI tool with the given Zod schema.
+   * Chainable — returns `this` so you can stack multiple `.expose()` calls.
+   *
+   * @example
+   * ```ts
+   * const agent = container.entity('agent', {})
+   *   .extend({ search({ query }: { query: string }) { ... } })
+   *   .expose('search', z.object({ query: z.string() }))
+   *
+   * assistant.addTools(agent)
+   * ```
+   */
+  expose(this: Entity<TState, TOptions, TEvents>, functionName: string, schema: z.ZodType): Entity<TState, TOptions, TEvents>
+
+  /**
+   * Returns `{ schemas, handlers }` for all tools registered via `.expose()`.
+   * Compatible with `assistant.addTools()` and the standard `toTools` contract.
+   */
+  toTools(): { schemas: Record<string, z.ZodType>; handlers: Record<string, Function> }
+}
+
+/** @internal */
+export function createEntityObject<
+  TState extends Record<string, any> = Record<string, any>,
+  TOptions extends Record<string, any> = Record<string, any>,
+  TEvents extends EventMap = EventMap,
+>(
+  id: string,
+  container: Container<any>,
+  options: TOptions,
+): Entity<TState, TOptions, TEvents> {
+  const _events = new Bus<TEvents>()
+  const _state = new State<TState>()
+
+  const _exposed = new Map<string, z.ZodType>()
+
+  const entity: Entity<TState, TOptions, TEvents> = {
+    id,
+    uuid: (uuid as any).v4(),
+    options,
+    state: _state,
+    container,
+    on(event: any, listener: any) { _events.on(event, listener) },
+    off(event: any, listener?: any) { _events.off(event, listener) },
+    once(event: any, listener: any) { _events.once(event, listener) },
+    emit(event: any, ...args: any[]) { _events.emit(event, ...args as any) },
+    waitFor(event: any) { return _events.waitFor(event) },
+    setState(value: any) { _state.setState(value) },
+    extend(extensions: any) { return applyExtensions(this as any, extensions) },
+    expose(functionName: string, schema: z.ZodType) {
+      // Each prototype layer gets its own _exposed map (lazy-created on write)
+      if (!Object.prototype.hasOwnProperty.call(this, '_exposed')) {
+        ;(this as any)._exposed = new Map<string, z.ZodType>()
+      }
+      ;(this as any)._exposed.set(functionName, schema)
+      return this
+    },
+    toTools() {
+      const schemas: Record<string, z.ZodType> = {}
+      const handlers: Record<string, Function> = {}
+
+      // Walk the prototype chain collecting _exposed maps; shallower layers win
+      let obj: any = this
+      while (obj !== null) {
+        if (Object.prototype.hasOwnProperty.call(obj, '_exposed')) {
+          for (const [name, schema] of (obj._exposed as Map<string, z.ZodType>)) {
+            if (!(name in schemas)) {
+              schemas[name] = schema
+              handlers[name] = (args: any) => (this as any)[name](args)
+            }
+          }
+        }
+        obj = Object.getPrototypeOf(obj)
+      }
+
+      return { schemas, handlers }
+    },
+  }
+
+  ;(entity as any)._exposed = _exposed
+
+  return entity
+}
+
+/**
+ * Graft extensions onto an entity via prototype delegation.
+ *
+ * The extended object's prototype is `base`, so all base properties (state, container,
+ * on/off/emit, etc.) are reachable through `this` in any grafted method or getter.
+ * Calling `.extend()` on the result correctly uses the extended object as the new base.
+ */
+function applyExtensions<
+  TState extends Record<string, any>,
+  TOptions extends Record<string, any>,
+  TEvents extends EventMap,
+  Ext extends Record<string, any>,
+>(
+  base: Entity<TState, TOptions, TEvents>,
+  extensions: Ext,
+): Entity<TState, TOptions, TEvents> & Ext {
+  const extended = Object.create(base) as Entity<TState, TOptions, TEvents> & Ext
+
+  for (const key of Object.getOwnPropertyNames(extensions)) {
+    const descriptor = Object.getOwnPropertyDescriptor(extensions, key)!
+    Object.defineProperty(extended, key, {
+      ...descriptor,
+      configurable: true,
+    })
+  }
+
+  return extended
+}

package/src/feature.ts

@@ -0,0 +1,118 @@
+import { Helper } from './helper.js';
+import { Registry } from './registry.js'
+import type { ContainerContext } from './container.js'
+import { kebabCase, camelCase } from 'lodash-es'
+import type { YAML } from './node/features/yaml.js';
+import { z } from 'zod'
+import { FeatureStateSchema, FeatureOptionsSchema, FeatureEventsSchema } from './schemas/base.js'
+
+/**
+ * Use module augmentation to register features, the same way you would register
+ * them at runtime.  This will help developers get autocomplete etc.
+*/
+export interface AvailableFeatures {
+    yaml: typeof YAML
+}
+
+export type FeatureOptions = z.infer<typeof FeatureOptionsSchema>
+export type FeatureState = z.infer<typeof FeatureStateSchema>
+
+export abstract class Feature<T extends FeatureState = FeatureState, K extends FeatureOptions = FeatureOptions> extends Helper<T, K> {
+    static override stateSchema = FeatureStateSchema
+    static override optionsSchema = FeatureOptionsSchema
+    static override eventsSchema = FeatureEventsSchema
+
+    /** Self-register a Feature subclass from a static initialization block. */
+    static register: (SubClass: abstract new (options: any, context: any) => Feature, id?: string) => abstract new (options: any, context: any) => Feature
+
+    override get shortcut() {
+        return (this.constructor as any).shortcut as string
+    }
+
+    get isEnabled() {
+        return this.state.get('enabled')
+    }    
+   
+    constructor(options: K, context: ContainerContext) {
+        super(options, context)
+
+        if(typeof context.container !== 'object') {
+            console.error(this, options, context)
+            throw new Error('You should not instantiate a feature directly. Use container.feature() instead.')
+        }
+
+
+        if(options?.enable) {
+          this.enable()
+        }
+    }
+
+    /** 
+     * For features where there only needs to be a single instance, you
+     * can use this method to attach the feature to the container.
+    */
+    protected attachToContainer() {
+        Object.defineProperty(this.container, this.shortcut.split('.').pop()!, {
+            get: () => this,
+            configurable: true,
+            enumerable: true,
+        })        
+    }
+
+    async enable(options: any = {}) : Promise<this> {
+        this.attachToContainer()
+        this.emit('enabled')
+        this.state.set('enabled', true)
+        
+        this.container.emit('featureEnabled', this.shortcut, this)
+
+        return this
+    }
+}
+
+export class FeaturesRegistry extends Registry<Feature<any, any>> {
+    override scope = "features"
+    override baseClass = Feature as any
+}
+
+export const features = new FeaturesRegistry()
+
+/**
+ * Self-register a Feature subclass from a static initialization block.
+ * IMPORTANT: Place the static block AFTER all static override declarations
+ * so schemas, envVars, and other metadata are set before interceptRegistration fires.
+ *
+ * @example
+ * ```typescript
+ * export default class DNS extends Feature<DnsState, DnsOptions> {
+ *   static override stateSchema = DnsStateSchema
+ *   static override optionsSchema = DnsOptionsSchema
+ *   static { Feature.register(this, 'dns') }  // must come last
+ * }
+ * ```
+ */
+Feature.register = function registerFeature(
+  SubClass: abstract new (options: any, context: any) => Feature,
+  id?: string,
+) {
+  const registryId = id ?? SubClass.name[0]!.toLowerCase() + SubClass.name.slice(1)
+
+  // Auto-set shortcut if not explicitly overridden on this class
+  if (!Object.getOwnPropertyDescriptor(SubClass, 'shortcut')?.value ||
+      (SubClass as any).shortcut === 'unspecified') {
+    ;(SubClass as any).shortcut = `features.${registryId}` as const
+  }
+
+  // Register in the features registry (interceptRegistration sees all statics above)
+  features.register(registryId, SubClass as any)
+
+  // Generate default attach() if not explicitly overridden on this class
+  if (!Object.getOwnPropertyDescriptor(SubClass, 'attach')) {
+    ;(SubClass as any).attach = (container: any) => {
+      features.register(registryId, SubClass as any)
+      return container
+    }
+  }
+
+  return SubClass
+}