@soederpop/luca 0.1.2 → 0.2.1

package/dist/node/features/container-link.d.ts

@@ -0,0 +1,213 @@
+import { z } from 'zod';
+import { Feature } from '../feature.js';
+export declare const MessageTypes: {
+    readonly register: "register";
+    readonly registered: "registered";
+    readonly eval: "eval";
+    readonly evalResult: "evalResult";
+    readonly event: "event";
+    readonly ping: "ping";
+    readonly pong: "pong";
+    readonly disconnect: "disconnect";
+    readonly error: "error";
+};
+export type MessageType = typeof MessageTypes[keyof typeof MessageTypes];
+export interface LinkMessage<T = any> {
+    type: MessageType;
+    id: string;
+    timestamp: number;
+    token?: string;
+    data?: T;
+}
+export interface RegisterData {
+    uuid: string;
+    url?: string;
+    capabilities?: string[];
+    meta?: Record<string, any>;
+}
+export interface RegisteredData {
+    token: string;
+    hostId: string;
+}
+export interface EvalData {
+    code: string;
+    context?: Record<string, any>;
+    requestId: string;
+    timeout?: number;
+}
+export interface EvalResultData {
+    requestId: string;
+    result?: any;
+    error?: string;
+}
+export interface EventData {
+    eventName: string;
+    data?: any;
+}
+export interface ConnectedContainer {
+    uuid: string;
+    url?: string;
+    capabilities?: string[];
+    meta?: Record<string, any>;
+    ws: any;
+    token: string;
+    missedHeartbeats: number;
+}
+export declare const ContainerLinkStateSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    connectionCount: z.ZodDefault<z.ZodNumber>;
+    port: z.ZodOptional<z.ZodNumber>;
+    listening: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$loose>;
+export type ContainerLinkState = z.infer<typeof ContainerLinkStateSchema>;
+export declare const ContainerLinkOptionsSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    _cacheKey: z.ZodOptional<z.ZodString>;
+    cached: z.ZodOptional<z.ZodBoolean>;
+    enable: z.ZodOptional<z.ZodBoolean>;
+    port: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    heartbeatInterval: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    maxMissedHeartbeats: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, z.core.$strip>;
+export type ContainerLinkOptions = z.infer<typeof ContainerLinkOptionsSchema>;
+export declare const ContainerLinkEventsSchema: z.ZodObject<{
+    stateChange: z.ZodTuple<[z.ZodAny], null>;
+    enabled: z.ZodTuple<[], null>;
+    connection: z.ZodTuple<[z.ZodString, z.ZodAny], null>;
+    disconnection: z.ZodTuple<[z.ZodString, z.ZodOptional<z.ZodString>], null>;
+    event: z.ZodTuple<[z.ZodString, z.ZodString, z.ZodAny], null>;
+    evalResult: z.ZodTuple<[z.ZodString, z.ZodAny], null>;
+}, z.core.$strip>;
+/**
+ * ContainerLink (Node-side) — WebSocket host for remote web containers.
+ *
+ * Creates a WebSocket server that web containers connect to. The host can evaluate
+ * code in connected web containers and receive structured events back.
+ * Trust is strictly one-way: the node side can eval in web containers,
+ * but web containers can NEVER eval in the node container.
+ *
+ * @example
+ * ```typescript
+ * const link = container.feature('containerLink', { enable: true, port: 8089 })
+ * await link.start()
+ *
+ * // When a web container connects:
+ * link.on('connection', (uuid, meta) => {
+ *   console.log('Connected:', uuid)
+ * })
+ *
+ * // Eval code in a specific web container
+ * const result = await link.eval(uuid, 'document.title')
+ *
+ * // Broadcast eval to all connected containers
+ * const results = await link.broadcast('navigator.userAgent')
+ *
+ * // Listen for events from web containers
+ * link.on('event', (uuid, eventName, data) => {
+ *   console.log(`Event from ${uuid}: ${eventName}`, data)
+ * })
+ * ```
+ */
+export declare class ContainerLink extends Feature<ContainerLinkState, ContainerLinkOptions> {
+    static shortcut: "features.containerLink";
+    static stateSchema: z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        connectionCount: z.ZodDefault<z.ZodNumber>;
+        port: z.ZodOptional<z.ZodNumber>;
+        listening: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$loose>;
+    static optionsSchema: z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        _cacheKey: z.ZodOptional<z.ZodString>;
+        cached: z.ZodOptional<z.ZodBoolean>;
+        enable: z.ZodOptional<z.ZodBoolean>;
+        port: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        heartbeatInterval: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        maxMissedHeartbeats: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    }, z.core.$strip>;
+    static eventsSchema: z.ZodObject<{
+        stateChange: z.ZodTuple<[z.ZodAny], null>;
+        enabled: z.ZodTuple<[], null>;
+        connection: z.ZodTuple<[z.ZodString, z.ZodAny], null>;
+        disconnection: z.ZodTuple<[z.ZodString, z.ZodOptional<z.ZodString>], null>;
+        event: z.ZodTuple<[z.ZodString, z.ZodString, z.ZodAny], null>;
+        evalResult: z.ZodTuple<[z.ZodString, z.ZodAny], null>;
+    }, z.core.$strip>;
+    private _wss?;
+    private _connections;
+    private _pendingEvals;
+    private _heartbeatTimer?;
+    get initialState(): ContainerLinkState;
+    /** Whether the WebSocket server is currently listening. */
+    get isListening(): boolean;
+    /** Number of currently connected web containers. */
+    get connectionCount(): number;
+    /**
+     * Start the WebSocket server and begin accepting connections.
+     *
+     * @returns This feature instance for chaining
+     */
+    start(): Promise<this>;
+    /**
+     * Stop the WebSocket server and disconnect all clients.
+     *
+     * @returns This feature instance for chaining
+     */
+    stop(): Promise<this>;
+    /**
+     * Evaluate code in a specific connected web container.
+     *
+     * @param containerId - UUID of the target web container
+     * @param code - JavaScript code to evaluate
+     * @param context - Optional context variables to inject
+     * @param timeout - Timeout in ms (default 10000)
+     * @returns The eval result
+     */
+    eval<T = any>(containerId: string, code: string, context?: Record<string, any>, timeout?: number): Promise<T>;
+    /**
+     * Evaluate code in all connected web containers.
+     *
+     * @param code - JavaScript code to evaluate
+     * @param context - Optional context variables to inject
+     * @param timeout - Timeout in ms (default 10000)
+     * @returns Map of containerId → result or Error
+     */
+    broadcast<T = any>(code: string, context?: Record<string, any>, timeout?: number): Promise<Map<string, T | Error>>;
+    /**
+     * Get metadata of all connected containers.
+     *
+     * @returns Array of connection metadata (without ws reference)
+     */
+    getConnections(): Array<Omit<ConnectedContainer, 'ws' | 'token'>>;
+    /**
+     * Disconnect a specific web container.
+     *
+     * @param containerId - UUID of the container to disconnect
+     * @param reason - Optional reason string
+     */
+    disconnect(containerId: string, reason?: string): void;
+    private handleMessage;
+    private handleRegister;
+    private handleEvalResult;
+    private handleEvent;
+    private handlePong;
+    private handleClientDisconnect;
+    /** Generate a cryptographically random token for connection auth. */
+    generateToken(): string;
+    /** Create a link protocol message with a unique ID. */
+    private createMessage;
+    private sendToWs;
+    /**
+     * Send a message to a specific connected container by UUID.
+     *
+     * @param containerId - UUID of the target container
+     * @param msg - The message to send
+     */
+    sendTo(containerId: string, msg: LinkMessage): void;
+    private findConnectionByWs;
+    private findConnectionByToken;
+    private startHeartbeat;
+    private stopHeartbeat;
+}
+export default ContainerLink;
+//# sourceMappingURL=container-link.d.ts.map

package/dist/node/features/container-link.d.ts.map

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

package/dist/node/features/content-db.d.ts

@@ -0,0 +1,354 @@
+import { Feature } from '../feature.js';
+import * as contentbaseExports from 'contentbase';
+import { Collection, type ModelDefinition } from 'contentbase';
+import { z } from 'zod';
+import type { GrepOptions } from './grep.js';
+export declare const ContentDbStateSchema: contentbaseExports.z.ZodObject<{
+    enabled: contentbaseExports.z.ZodDefault<contentbaseExports.z.ZodBoolean>;
+    loaded: contentbaseExports.z.ZodDefault<contentbaseExports.z.ZodBoolean>;
+    tableOfContents: contentbaseExports.z.ZodDefault<contentbaseExports.z.ZodString>;
+    modelSummary: contentbaseExports.z.ZodDefault<contentbaseExports.z.ZodString>;
+}, contentbaseExports.z.core.$loose>;
+export declare const ContentDbOptionsSchema: contentbaseExports.z.ZodObject<{
+    name: contentbaseExports.z.ZodOptional<contentbaseExports.z.ZodString>;
+    _cacheKey: contentbaseExports.z.ZodOptional<contentbaseExports.z.ZodString>;
+    cached: contentbaseExports.z.ZodOptional<contentbaseExports.z.ZodBoolean>;
+    enable: contentbaseExports.z.ZodOptional<contentbaseExports.z.ZodBoolean>;
+    rootPath: contentbaseExports.z.ZodString;
+}, contentbaseExports.z.core.$strip>;
+export type ContentDbState = z.infer<typeof ContentDbStateSchema>;
+export type ContentDbOptions = z.infer<typeof ContentDbOptionsSchema>;
+export declare const ContentDbEventsSchema: contentbaseExports.z.ZodObject<{
+    stateChange: contentbaseExports.z.ZodTuple<[contentbaseExports.z.ZodAny], null>;
+    enabled: contentbaseExports.z.ZodTuple<[], null>;
+    reloaded: contentbaseExports.z.ZodTuple<[], null>;
+}, contentbaseExports.z.core.$strip>;
+/**
+ * Provides access to a Contentbase Collection for a folder of structured markdown files.
+ *
+ * Models are defined in the collection's models.ts file and auto-discovered on load.
+ * This feature is a thin wrapper that manages the collection lifecycle and provides
+ * convenience accessors for models and documents.
+ *
+ * @extends Feature
+ * @example
+ * ```typescript
+ * const contentDb = container.feature('contentDb', { rootPath: './docs' })
+ * await contentDb.load()
+ * console.log(contentDb.modelNames) // ['Article', 'Page', ...]
+ * ```
+ */
+export declare class ContentDb extends Feature<ContentDbState, ContentDbOptions> {
+    static shortcut: "features.contentDb";
+    static stateSchema: contentbaseExports.z.ZodObject<{
+        enabled: contentbaseExports.z.ZodDefault<contentbaseExports.z.ZodBoolean>;
+        loaded: contentbaseExports.z.ZodDefault<contentbaseExports.z.ZodBoolean>;
+        tableOfContents: contentbaseExports.z.ZodDefault<contentbaseExports.z.ZodString>;
+        modelSummary: contentbaseExports.z.ZodDefault<contentbaseExports.z.ZodString>;
+    }, contentbaseExports.z.core.$loose>;
+    static optionsSchema: contentbaseExports.z.ZodObject<{
+        name: contentbaseExports.z.ZodOptional<contentbaseExports.z.ZodString>;
+        _cacheKey: contentbaseExports.z.ZodOptional<contentbaseExports.z.ZodString>;
+        cached: contentbaseExports.z.ZodOptional<contentbaseExports.z.ZodBoolean>;
+        enable: contentbaseExports.z.ZodOptional<contentbaseExports.z.ZodBoolean>;
+        rootPath: contentbaseExports.z.ZodString;
+    }, contentbaseExports.z.core.$strip>;
+    static eventsSchema: contentbaseExports.z.ZodObject<{
+        stateChange: contentbaseExports.z.ZodTuple<[contentbaseExports.z.ZodAny], null>;
+        enabled: contentbaseExports.z.ZodTuple<[], null>;
+        reloaded: contentbaseExports.z.ZodTuple<[], null>;
+    }, contentbaseExports.z.core.$strip>;
+    /** Tools that any assistant can use to progressively explore this collection. */
+    static tools: Record<string, {
+        schema: z.ZodType;
+        handler?: Function;
+    }>;
+    get initialState(): ContentDbState;
+    /** Whether the content database has been loaded. */
+    get isLoaded(): boolean;
+    _collection?: Collection;
+    private _contentbaseSeeded;
+    /** Returns the lazily-initialized Collection instance for the configured rootPath. */
+    get collection(): Collection;
+    /** Check if contentbase is resolvable via native import from the project root */
+    private _canNativeImportContentbase;
+    /** Seed the VM with virtual modules so models.ts can import from 'contentbase', 'zod', etc. */
+    private _seedContentbaseVirtualModules;
+    /** Returns the absolute resolved path to the collection root directory. */
+    get collectionPath(): string;
+    /** Returns an object mapping model names to their model definitions, sourced from the collection. */
+    get models(): Record<string, ModelDefinition>;
+    /** Returns an array of all registered model names from the collection. */
+    get modelNames(): string[];
+    /**
+     * Returns the available document ids in the collection
+    */
+    get available(): string[];
+    /**
+     * Render a tree view of the collection directory structure.
+     * Built with container.fs so it works without the `tree` binary.
+     */
+    renderTree(options?: {
+        depth?: number;
+        dirsOnly?: boolean;
+    }): string;
+    grep(options: string | GrepOptions): Promise<import("./grep.js").GrepMatch[]>;
+    /**
+     * Query documents belonging to a specific model definition.
+     *
+     * @param model - The model definition to query against
+     * @returns A query builder scoped to the given model's documents
+     * @example
+     * ```typescript
+     * const contentDb = container.feature('contentDb', { rootPath: './docs' })
+     * await contentDb.load()
+     * const articles = await contentDb.query(contentDb.models.Article).fetchAll()
+     * ```
+     */
+    query<T extends ModelDefinition>(model: T): contentbaseExports.CollectionQuery<T>;
+    /**
+     * Parse a markdown file at the given path without loading the full collection.
+     *
+     * @param path - Absolute or relative path to the markdown file
+     * @returns The parsed markdown document with frontmatter and content
+     * @example
+     * ```typescript
+     * const doc = contentDb.parseMarkdownAtPath('./docs/getting-started.md')
+     * console.log(doc.frontmatter, doc.content)
+     * ```
+     */
+    parseMarkdownAtPath(path: string): Promise<contentbaseExports.ParsedDocument>;
+    /**
+     * Load the collection, discovering models from models.ts and parsing all documents.
+     *
+     * @returns This ContentDb instance for chaining
+     * @example
+     * ```typescript
+     * const contentDb = container.feature('contentDb', { rootPath: './docs' })
+     * await contentDb.load()
+     * console.log(contentDb.isLoaded) // true
+     * ```
+     */
+    load(): Promise<ContentDb>;
+    /** Force-reload the collection from disk, picking up new/changed/deleted documents. */
+    reload(): Promise<ContentDb>;
+    /**
+     * Read a single document by its path ID, optionally filtering to specific sections.
+     *
+     * The document title (H1) is always included in the output. When using `include`,
+     * the leading content (paragraphs between the H1 and first H2) is also included
+     * by default, controlled by the `leadingContent` option.
+     *
+     * When `include` is provided, only those sections are returned (via extractSections in flat mode).
+     * When `exclude` is provided, those sections are removed from the full document.
+     * If both are set, `include` takes precedence.
+     *
+     * @param idStringOrObject - Document path ID string, or an object with an `id` property
+     * @param options - Optional filtering and formatting options
+     * @param options.include - Only return sections matching these heading names
+     * @param options.exclude - Remove sections matching these heading names
+     * @param options.meta - Whether to include YAML frontmatter in the output (default: false)
+     * @param options.leadingContent - Include content between the H1 and first H2 when using include filter (default: true)
+     * @returns The document content as a markdown string
+     * @example
+     * ```typescript
+     * await contentDb.read('guides/intro')
+     * await contentDb.read('guides/intro', { include: ['Installation', 'Usage'] })
+     * await contentDb.read('guides/intro', { exclude: ['Changelog'], meta: true })
+     * await contentDb.read('guides/intro', { include: ['API'], leadingContent: false })
+     * ```
+     */
+    read(idStringOrObject: string | {
+        id: string;
+    }, options?: {
+        exclude?: string[];
+        include?: string[];
+        meta?: boolean;
+        leadingContent?: boolean;
+    }): Promise<string>;
+    /**
+     * Read multiple documents by their path IDs, concatenated into a single string.
+     *
+     * By default each document is wrapped in `<!-- BEGIN: id -->` / `<!-- END: id -->`
+     * dividers for easy identification. Supports the same filtering options as {@link read}.
+     *
+     * @param ids - Array of document path ID strings or objects with `id` properties
+     * @param options - Optional filtering and formatting options (applied to each document)
+     * @param options.dividers - Wrap each document in BEGIN/END comment dividers showing the ID (default: true)
+     * @returns The concatenated document contents as a single markdown string
+     * @example
+     * ```typescript
+     * await contentDb.readMultiple(['guides/intro', 'guides/setup'])
+     * await contentDb.readMultiple([{ id: 'guides/intro' }], { include: ['Overview'], dividers: false })
+     * ```
+     */
+    readMultiple(ids: string[] | {
+        id: string;
+    }[], options?: {
+        exclude?: string[];
+        include?: string[];
+        meta?: boolean;
+        leadingContent?: boolean;
+        dividers?: boolean;
+    }): Promise<string>;
+    /**
+     * Extracts the content between the H1 heading and the first H2 heading.
+     * Returns an empty string if there's no leading content or no H2 sections.
+     */
+    private _getLeadingContent;
+    generateTableOfContents(): Promise<string>;
+    generateModelSummary(options: any): Promise<string>;
+    get modelDefinitionTable(): Record<string, {
+        description: string;
+        glob: string;
+        routePatterns: string[];
+    }>;
+    get fileTree(): string;
+    private _semanticSearch;
+    /**
+     * Lazily initialize the semanticSearch feature, attaching it to the container if needed.
+     * The dbPath defaults to `~/.luca/contentbase/{hash}/search.sqlite` where hash is derived from the resolved collection path.
+     */
+    private _getSemanticSearch;
+    /**
+     * Check if a search index exists for this collection.
+     */
+    private _hasSearchIndex;
+    /**
+     * BM25 keyword search across indexed documents.
+     * If no search index exists, throws with an actionable message.
+     */
+    search(query: string, options?: {
+        limit?: number;
+        model?: string;
+        where?: Record<string, any>;
+    }): Promise<any>;
+    /**
+     * Vector similarity search using embeddings.
+     * Finds conceptually related documents even without keyword matches.
+     */
+    vectorSearch(query: string, options?: {
+        limit?: number;
+        model?: string;
+        where?: Record<string, any>;
+    }): Promise<any>;
+    /**
+     * Combined keyword + semantic search with Reciprocal Rank Fusion.
+     * Best for general questions about the collection.
+     */
+    hybridSearch(query: string, options?: {
+        limit?: number;
+        model?: string;
+        where?: Record<string, any>;
+        ftsWeight?: number;
+        vecWeight?: number;
+    }): Promise<any>;
+    /**
+     * Build the search index from all documents in the collection.
+     * Chunks documents and generates embeddings.
+     */
+    buildSearchIndex(options?: {
+        force?: boolean;
+        embeddingProvider?: string;
+        embeddingModel?: string;
+        onProgress?: (indexed: number, total: number) => void;
+    }): Promise<{
+        indexed: number;
+        total: number;
+    }>;
+    /**
+     * Rebuild the entire search index from scratch.
+     */
+    rebuildSearchIndex(options?: {
+        embeddingProvider?: string;
+        embeddingModel?: string;
+        onProgress?: (indexed: number, total: number) => void;
+    }): Promise<{
+        indexed: number;
+        total: number;
+    }>;
+    /**
+     * Get the current search index status.
+     */
+    get searchIndexStatus(): {
+        exists: boolean;
+        documentCount: number;
+        chunkCount: number;
+        embeddingCount: number;
+        lastIndexedAt: any;
+        provider: any;
+        model: any;
+        dimensions: number;
+        dbSizeBytes: number;
+    };
+    /**
+     * Convert collection documents to DocumentInput format for the semantic search feature.
+     */
+    private _collectDocumentInputs;
+    /**
+     * Returns an object with query builders keyed by model name (singular and plural, lowercased).
+     *
+     * Provides a convenient shorthand for querying without looking up model definitions manually.
+     *
+     * @example
+     * ```typescript
+     * const contentDb = container.feature('contentDb', { rootPath: './docs' })
+     * await contentDb.load()
+     * const allArticles = await contentDb.queries.articles.fetchAll()
+     * const firstTask = await contentDb.queries.task.first()
+     * ```
+     */
+    get queries(): Record<string, ReturnType<typeof this.query>>;
+    /** Returns a high-level overview of the collection. */
+    getCollectionOverview(): Promise<{
+        rootPath: string;
+        totalDocuments: number;
+        models: Record<string, number>;
+        tree: string;
+        hasSearchIndex: boolean;
+    }>;
+    /** List document IDs, optionally filtered by model or glob. */
+    listDocuments(args: {
+        model?: string;
+        glob?: string;
+    }): Promise<string[] | {
+        error: string;
+    }>;
+    /** Read a single document with optional section filtering. */
+    readDocument(args: {
+        id: string;
+        include?: string[];
+        exclude?: string[];
+        meta?: boolean;
+    }): Promise<string>;
+    /** Read multiple documents with optional section filtering. */
+    readMultipleDocuments(args: {
+        ids: string[];
+        include?: string[];
+        exclude?: string[];
+        meta?: boolean;
+    }): Promise<string>;
+    /** Query documents by model with filters, sort, limit. */
+    queryDocuments(args: {
+        model: string;
+        where?: string;
+        sort?: string;
+        limit?: number;
+        offset?: number;
+        select?: string[];
+    }): Promise<any[] | {
+        error: string;
+    }>;
+    /** Grep/text search across the collection. */
+    searchContent(args: {
+        pattern: string;
+        caseSensitive?: boolean;
+    }): Promise<import("./grep.js").GrepMatch[]>;
+    /** Hybrid semantic search with graceful fallback to grep. */
+    semanticSearch(args: {
+        query: string;
+        limit?: number;
+    }): Promise<any>;
+}
+export default ContentDb;
+//# sourceMappingURL=content-db.d.ts.map

package/dist/node/features/content-db.d.ts.map

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