@soederpop/luca 0.0.29 → 0.0.31

package/src/endpoint.ts

@@ -197,6 +197,12 @@ export class Endpoint<
 
   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()
   }
 

package/src/helper.ts

@@ -73,6 +73,31 @@ export abstract class Helper<T extends HelperState = HelperState, K extends Help
     return presentIntrospectionJSONAsMarkdown(introspection, depth, section)
   }
 
+  /**
+   * Returns the introspection data formatted as a TypeScript interface declaration.
+   * Useful for AI agents that reason better with structured type information,
+   * or for generating `.d.ts` files that accurately describe a helper's public API.
+   *
+   * @example
+   * ```ts
+   * console.log(container.feature('fs').inspectAsType())
+   * // interface FS {
+   * //   readonly cwd: string;
+   * //   readFile(path: string): Promise<string>;
+   * //   ...
+   * // }
+   * ```
+   */
+  static inspectAsType(section?: IntrospectionSection) : string {
+    return this.introspectAsType(section)
+  }
+
+  static introspectAsType(section?: IntrospectionSection) : string {
+    const introspection = this.introspect()
+    if (!introspection) return ''
+    return presentIntrospectionAsTypeScript(introspection, section)
+  }
+
 
   /**
    * All Helpers can be introspect()ed and, assuming the introspection data has been loaded into the registry,
@@ -90,8 +115,8 @@ export abstract class Helper<T extends HelperState = HelperState, K extends Help
 
   /** Alias for introspect */
   inspect(section?: IntrospectionSection) : HelperIntrospection | undefined {
-    return this.introspect()
-  } 
+    return this.introspect(section)
+  }
 
   /**
    * Returns the introspection data formatted as a markdown string.
@@ -110,7 +135,23 @@ export abstract class Helper<T extends HelperState = HelperState, K extends Help
   inspectAsText(sectionOrDepth?: IntrospectionSection | number, startHeadingDepth?: number) : string {
     return this.introspectAsText(sectionOrDepth, startHeadingDepth)
   }
-  
+
+  /**
+   * Returns the introspection data formatted as a TypeScript interface declaration.
+   * Useful for AI agents that reason better with structured type information,
+   * or for generating `.d.ts` files that accurately describe a helper's public API.
+   */
+  introspectAsType(section?: IntrospectionSection) : string {
+    const introspection = this.introspect()
+    if (!introspection) return ''
+    return presentIntrospectionAsTypeScript(introspection, section)
+  }
+
+  /** Alias for introspectAsType */
+  inspectAsType(section?: IntrospectionSection) : string {
+    return this.introspectAsType(section)
+  }
+
   constructor(options: K, context: ContainerContext) {
     const optionSchema = (this.constructor as any).optionsSchema
     if (optionSchema && typeof optionSchema.safeParse === 'function') {
@@ -226,7 +267,7 @@ export abstract class Helper<T extends HelperState = HelperState, K extends Help
    */
   toTools(): { schemas: Record<string, z.ZodType>, handlers: Record<string, Function> } {
     // Walk the prototype chain collecting static tools (parent-first, child overwrites)
-    const merged: Record<string, { schema: z.ZodType, handler?: Function }> = {}
+    const merged: Record<string, { schema: z.ZodType, description?: string, handler?: Function }> = {}
     const chain: Function[] = []
 
     let current = this.constructor as any
@@ -248,7 +289,11 @@ export abstract class Helper<T extends HelperState = HelperState, K extends Help
     const handlers: Record<string, Function> = {}
 
     for (const [name, entry] of Object.entries(merged)) {
-      schemas[name] = entry.schema
+      // If the tool entry has a description but the schema doesn't, attach it
+      // so addTool() picks it up from jsonSchema.description.
+      schemas[name] = entry.description && !entry.schema.description
+        ? entry.schema.describe(entry.description)
+        : entry.schema
       if (entry.handler) {
         handlers[name] = (args: any) => entry.handler!(args, this)
       } else if (typeof (this as any)[name] === 'function') {
@@ -589,6 +634,7 @@ function normalizeLang(lang: string): string {
 }
 
 export { presentIntrospectionJSONAsMarkdown as presentIntrospectionAsMarkdown }
+export { presentIntrospectionAsTypeScript, renderTypeScriptParams, normalizeTypeString, isGenericObjectType }
 
 function presentIntrospectionJSONAsMarkdown(introspection: HelperIntrospection, startHeadingDepth: number = 1, section?: IntrospectionSection) {
   const sections: string[] = []
@@ -622,3 +668,178 @@ function presentIntrospectionJSONAsMarkdown(introspection: HelperIntrospection,
 
   return sections.join('\n\n')
 }
+
+/**
+ * Renders introspection data as a TypeScript interface declaration.
+ * Produces a valid interface string that describes the helper's public API —
+ * getters, methods, state shape, options shape, and event listener signatures.
+ */
+function presentIntrospectionAsTypeScript(introspection: HelperIntrospection, section?: IntrospectionSection): string {
+  const interfaceName = introspection.className || introspection.id.split('.').pop() || 'Unknown'
+  const members: string[] = []
+
+  const shouldRender = (s: IntrospectionSection) => !section || section === s
+
+  // Getters
+  if (shouldRender('getters') && introspection.getters && Object.keys(introspection.getters).length > 0) {
+    for (const [name, info] of Object.entries(introspection.getters)) {
+      const returnType = normalizeTypeString(info.returns || 'any')
+      if (info.description) {
+        members.push(`  /** ${info.description} */`)
+      }
+      members.push(`  readonly ${name}: ${returnType};`)
+    }
+  }
+
+  // Methods
+  if (shouldRender('methods') && introspection.methods && Object.keys(introspection.methods).length > 0) {
+    if (members.length > 0) members.push('')
+    for (const [name, info] of Object.entries(introspection.methods)) {
+      if (info.description) {
+        members.push(`  /** ${info.description} */`)
+      }
+      const params = renderTypeScriptParams(info)
+      const returnType = normalizeTypeString(info.returns || 'void')
+      members.push(`  ${name}(${params}): ${returnType};`)
+    }
+  }
+
+  // State — render as the observable State<T> object, not just currentState
+  if (shouldRender('state') && introspection.state && Object.keys(introspection.state).length > 0) {
+    if (members.length > 0) members.push('')
+    const stateMembers = Object.entries(introspection.state)
+      .map(([name, info]) => {
+        const comment = info.description ? `      /** ${info.description} */\n` : ''
+        return `${comment}      ${name}: ${normalizeTypeString(info.type || 'any')};`
+      })
+      .join('\n')
+    const stateShape = `{\n${stateMembers}\n    }`
+    members.push(`  state: {`)
+    members.push(`    /** The current version number, incremented on each change */`)
+    members.push(`    readonly version: number;`)
+    members.push(`    /** Get the value of a state key */`)
+    members.push(`    get<K extends keyof T>(key: K): T[K] | undefined;`)
+    members.push(`    /** Set a state key to a new value, notifying observers */`)
+    members.push(`    set<K extends keyof T>(key: K, value: T[K]): this;`)
+    members.push(`    /** Delete a state key, notifying observers */`)
+    members.push(`    delete<K extends keyof T>(key: K): this;`)
+    members.push(`    /** Check if a state key exists */`)
+    members.push(`    has<K extends keyof T>(key: K): boolean;`)
+    members.push(`    /** Get all state keys */`)
+    members.push(`    keys(): string[];`)
+    members.push(`    /** Get the current state snapshot */`)
+    members.push(`    readonly current: ${stateShape};`)
+    members.push(`    /** Get all entries as [key, value] pairs */`)
+    members.push(`    entries(): [string, any][];`)
+    members.push(`    /** Get all state values */`)
+    members.push(`    values(): any[];`)
+    members.push(`    /** Register an observer callback for state changes. Returns an unsubscribe function. */`)
+    members.push(`    observe(callback: (changeType: 'add' | 'update' | 'delete', key: string, value?: any) => void): () => void;`)
+    members.push(`    /** Merge partial state, notifying observers for each changed key */`)
+    members.push(`    setState(value: Partial<${stateShape}> | ((current: ${stateShape}, state: this) => Partial<${stateShape}>)): void;`)
+    members.push(`    /** Clear all state, notifying observers */`)
+    members.push(`    clear(): void;`)
+    members.push(`  };`)
+  }
+
+  // Options
+  if (shouldRender('options') && introspection.options && Object.keys(introspection.options).length > 0) {
+    if (members.length > 0) members.push('')
+    const optionMembers = Object.entries(introspection.options)
+      .map(([name, info]) => {
+        const comment = info.description ? `    /** ${info.description} */\n` : ''
+        return `${comment}    ${name}?: ${normalizeTypeString(info.type || 'any')};`
+      })
+      .join('\n')
+    members.push(`  options: {\n${optionMembers}\n  };`)
+  }
+
+  // Events — rendered as on() overloads
+  if (shouldRender('events') && introspection.events && Object.keys(introspection.events).length > 0) {
+    if (members.length > 0) members.push('')
+    for (const [eventName, eventInfo] of Object.entries(introspection.events)) {
+      const args = Object.entries(eventInfo.arguments || {})
+      const listenerParams = args.length > 0
+        ? args.map(([argName, argInfo]) => `${argName}: ${normalizeTypeString(argInfo.type || 'any')}`).join(', ')
+        : ''
+      if (eventInfo.description) {
+        members.push(`  /** ${eventInfo.description} */`)
+      }
+      members.push(`  on(event: '${eventName}', listener: (${listenerParams}) => void): this;`)
+    }
+  }
+
+  const description = introspection.description
+    ? `/**\n * ${introspection.description.split('\n').join('\n * ')}\n */\n`
+    : ''
+
+  const mainInterface = `${description}interface ${interfaceName} {\n${members.join('\n')}\n}`
+
+  // Emit referenced type declarations above the main interface
+  const types = introspection.types
+  if (types && Object.keys(types).length > 0) {
+    const typeDeclarations = Object.entries(types).map(([typeName, typeInfo]) => {
+      const typeDesc = typeInfo.description
+        ? `/**\n * ${typeInfo.description.split('\n').join('\n * ')}\n */\n`
+        : ''
+      const props = Object.entries(typeInfo.properties)
+        .map(([propName, propInfo]) => {
+          const comment = propInfo.description ? `  /** ${propInfo.description} */\n` : ''
+          const opt = propInfo.optional ? '?' : ''
+          return `${comment}  ${propName}${opt}: ${normalizeTypeString(propInfo.type || 'any')};`
+        })
+        .join('\n')
+      return `${typeDesc}interface ${typeName} {\n${props}\n}`
+    })
+
+    return typeDeclarations.join('\n\n') + '\n\n' + mainInterface
+  }
+
+  return mainInterface
+}
+
+/** Build a TypeScript parameter list string from method introspection */
+function renderTypeScriptParams(method: { parameters: Record<string, { type: string, description?: string, properties?: Record<string, { type: string, description?: string }> }>, required: string[] }): string {
+  const entries = Object.entries(method.parameters || {})
+  if (entries.length === 0) return ''
+
+  return entries.map(([name, info]) => {
+    const isRequired = (method.required || []).includes(name)
+    let type = normalizeTypeString(info.type || 'any')
+
+    // If the parameter has expanded sub-properties but a generic type string,
+    // render an inline object type from those properties instead
+    if (info.properties && Object.keys(info.properties).length > 0 && isGenericObjectType(type)) {
+      const props = Object.entries(info.properties)
+        .map(([propName, propInfo]) => `${propName}?: ${normalizeTypeString(propInfo.type || 'any')}`)
+        .join('; ')
+      type = `{ ${props} }`
+    }
+
+    return `${name}${isRequired ? '' : '?'}: ${type}`
+  }).join(', ')
+}
+
+/** Returns true if the type string looks like a generic object type that sub-properties would refine */
+function isGenericObjectType(type: string): boolean {
+  const lower = type.toLowerCase()
+  return lower === 'object' || lower === 'any' || lower === 'record<string, any>' || lower === '{}'
+}
+
+/** Clean up type strings from introspection data for use in interface declarations */
+function normalizeTypeString(type: string): string {
+  if (!type) return 'any'
+  // The AST scanner sometimes wraps types in quotes
+  type = type.replace(/^["']|["']$/g, '')
+  // Convert internal ReturnType<typeof this.container.feature<'name'>> to a clean import reference
+  // e.g. ReturnType<typeof this.container.feature<'proc'>> → import('luca').Proc
+  type = type.replace(
+    /ReturnType<typeof this\.container\.(feature|client|server)<'([^']+)'>>/g,
+    (_match, _kind, name) => {
+      // Convert shortcut name to PascalCase class name
+      const className = name.replace(/(^|[-_])(\w)/g, (_: string, _sep: string, ch: string) => ch.toUpperCase())
+      return `import('@soederpop/luca').${className}`
+    }
+  )
+  return type
+}