luca 2.0.0 → 3.0.0

package/dist/hash-object.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Browser-compatible object hashing. Produces a deterministic string signature
+ * for any JavaScript value, suitable for use as a cache key or identity check.
+ *
+ * Replaces the `object-hash` npm package which has Node.js-specific dependencies.
+ */
+export default function hashObject(value: any): string;
+//# sourceMappingURL=hash-object.d.ts.map

package/dist/hash-object.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash-object.d.ts","sourceRoot":"","sources":["../src/hash-object.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAwFH,MAAM,CAAC,OAAO,UAAU,UAAU,CAAC,KAAK,EAAE,GAAG,GAAG,MAAM,CAGrD"}

package/dist/helper.d.ts

@@ -0,0 +1,209 @@
+import { Bus, type EventMap } from "./bus.js";
+import { type SetStateValue, State } from "./state.js";
+import type { ContainerContext } from './container.js';
+import { type HelperIntrospection, type IntrospectionSection } from "./introspection/index.js";
+import { z } from 'zod';
+import { HelperStateSchema, HelperOptionsSchema } from './schemas/base.js';
+export type HelperState = z.infer<typeof HelperStateSchema>;
+export type HelperOptions = z.infer<typeof HelperOptionsSchema>;
+/**
+ * Helpers are used to represent types of modules.
+ *
+ * You don't create instances of helpers directly, the container creates instances through
+ * factory functions that use the subclasses of Helper as a template.  The container
+ * provides dependency injection and injects a context object into the Helper constructor.
+ *
+ * A Helper is something that can be introspected at runtime to learn about the interface.
+ *
+ * A helper has state.
+ *
+ * A helper is an event bus.
+ *
+ * A helper is connected to the container and can access the container's state, events, shared context, or
+ * other helpers and features in the container's registry.
+ */
+export declare abstract class Helper<T extends HelperState = HelperState, K extends HelperOptions = any, E extends EventMap = EventMap> {
+    static shortcut: string;
+    static description: string;
+    static envVars: string[];
+    static stateSchema: z.ZodType;
+    static optionsSchema: z.ZodType;
+    static eventsSchema: z.ZodType;
+    static tools: Record<string, {
+        schema: z.ZodType;
+        handler?: Function;
+    }>;
+    protected readonly _context: ContainerContext;
+    protected readonly _events: Bus<E>;
+    protected readonly _options: K;
+    protected readonly _instanceTools: Record<string, {
+        schema: z.ZodType;
+        handler?: Function;
+    }>;
+    readonly state: State<T>;
+    readonly uuid: string;
+    get initialState(): T;
+    static introspect(section?: IntrospectionSection): HelperIntrospection | undefined;
+    static introspectAsText(sectionOrDepth?: IntrospectionSection | number, startHeadingDepth?: number): string;
+    /**
+     * 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').introspectAsType())
+     * // interface FS {
+     * //   readonly cwd: string;
+     * //   readFile(path: string): Promise<string>;
+     * //   ...
+     * // }
+     * ```
+     */
+    static introspectAsType(section?: IntrospectionSection): string;
+    /**
+     * All Helpers can be introspect()ed and, assuming the introspection data has been loaded into the registry,
+     * will report information about the Helper that can only get extracted by reading the code, e.g. the type interfaces
+     * for the helper's options, state, and the events it emits, as well as the documentation from the helpers code for
+     * each of the methods and properties.
+     *
+     * Pass a section name to get only that section: `'methods'`, `'getters'`, `'events'`, `'state'`, `'options'`, `'envVars'`
+    */
+    introspect(section?: IntrospectionSection): HelperIntrospection | undefined;
+    /**
+     * Returns the introspection data formatted as a markdown string.
+     *
+     * The first argument can be a section name (`'methods'`, `'getters'`, etc.) to render only
+     * that section, or a number for the starting heading depth (backward compatible).
+     */
+    introspectAsText(sectionOrDepth?: IntrospectionSection | number, startHeadingDepth?: number): string;
+    /**
+     * 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;
+    constructor(options: K, context: ContainerContext);
+    /**
+     * Returns the names of the methods for this helper.
+    */
+    get $methods(): string[];
+    /**
+     * Returns the names of the getters for this helper.
+    */
+    get $getters(): string[];
+    /**
+     * The static shortcut identifier for this helper type, e.g. "features.assistant".
+    */
+    get shortcut(): string;
+    /**
+     * Every helper has a cache key which is computed at the time it is created through the container.
+     *
+     * This ensures only a single instance of the helper exists for the requested options.
+    */
+    get cacheKey(): string | undefined;
+    /**
+     * This method will get called in the constructor and can be used instead of overriding the constructor
+     * in your helper subclases.
+    */
+    afterInitialize(): void;
+    setState(newState: SetStateValue<T>): this;
+    /**
+     * Convenience method for putting properties on the helper that aren't enumerable,
+     * which is a convenience for the REPL mainly.
+    */
+    hide(...propNames: string[]): this;
+    /**
+     * python / lodash style get method, which will get a value from the container using dot notation
+     * and will return a default value if the value is not found.
+    */
+    tryGet<K extends (string | string[]), T extends object = any>(key: K, defaultValue?: T): any;
+    /**
+     * Register a tool on this instance at runtime. Instance tools take precedence
+     * over class-level static tools in toTools().
+     */
+    tool(name: string, options: {
+        schema: z.ZodType;
+        handler?: Function;
+    }): this;
+    /**
+     * Called when another helper (e.g. an assistant) consumes this helper's
+     * tools via `use()`. Override this to detect the consumer type and react —
+     * for example, adding system prompt extensions to an assistant.
+     *
+     * Use `consumer.shortcut` to identify the consumer type:
+     * ```typescript
+     * override setupToolsConsumer(consumer: Helper) {
+     *   if (consumer.shortcut === 'features.assistant') {
+     *     (consumer as any).addSystemPromptExtension('myFeature', 'usage hints here')
+     *   }
+     * }
+     * ```
+     *
+     * The default implementation is a no-op.
+     *
+     * @param consumer - The helper instance that is consuming this helper's tools
+     */
+    setupToolsConsumer(consumer: Helper): void;
+    /**
+     * Collect all tools from the inheritance chain and instance, returning
+     * { schemas, handlers } with matching keys. Walks the prototype chain
+     * so subclass tools override parent tools. Instance tools win over all.
+     *
+     * If a tool has no explicit handler but this instance has a method with
+     * the same name, a handler is auto-generated that delegates to that method.
+     */
+    toTools(options?: {
+        only?: string[];
+        except?: string[];
+    }): {
+        schemas: Record<string, z.ZodType>;
+        handlers: Record<string, Function>;
+    };
+    /**
+     * The options passed to the helper when it was created.
+    */
+    get options(): K;
+    /**
+     * The context object that was passed to the helper when it was created, this is decided by the container
+     * and not something you would manipulate.
+    */
+    get context(): ContainerContext<any>;
+    /**
+     * The container that the helper is connected to.
+    */
+    get container(): import("./container.js").Container<any, any>;
+    emit<Ev extends string & keyof E>(event: Ev, ...args: E[Ev]): this;
+    on(event: '*', listener: (event: string, ...args: any[]) => void): this;
+    on<Ev extends string & keyof E>(event: Ev, listener: (...args: E[Ev]) => void): this;
+    off(event: '*', listener?: (event: string, ...args: any[]) => void): this;
+    off<Ev extends string & keyof E>(event: Ev, listener?: (...args: E[Ev]) => void): this;
+    once<Ev extends string & keyof E>(event: Ev, listener: (...args: E[Ev]) => void): this;
+    waitFor<Ev extends string & keyof E>(event: Ev): Promise<E[Ev]>;
+}
+export { presentIntrospectionJSONAsMarkdown as presentIntrospectionAsMarkdown };
+export { presentIntrospectionAsTypeScript, renderTypeScriptParams, normalizeTypeString, isGenericObjectType };
+declare function presentIntrospectionJSONAsMarkdown(introspection: HelperIntrospection, startHeadingDepth?: number, section?: IntrospectionSection): string;
+/**
+ * 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.
+ */
+declare function presentIntrospectionAsTypeScript(introspection: HelperIntrospection, section?: IntrospectionSection): string;
+/** Build a TypeScript parameter list string from method introspection */
+declare function renderTypeScriptParams(method: {
+    parameters: Record<string, {
+        type: string;
+        description?: string;
+        properties?: Record<string, {
+            type: string;
+            description?: string;
+        }>;
+    }>;
+    required: string[];
+}): string;
+/** Returns true if the type string looks like a generic object type that sub-properties would refine */
+declare function isGenericObjectType(type: string): boolean;
+/** Clean up type strings from introspection data for use in interface declarations */
+declare function normalizeTypeString(type: string): string;
+//# sourceMappingURL=helper.d.ts.map

package/dist/helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helper.d.ts","sourceRoot":"","sources":["../src/helper.ts"],"names":[],"mappings":"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"}