@soederpop/luca 0.1.2 → 0.2.1

package/dist/node/features/semantic-search.d.ts

@@ -0,0 +1,207 @@
+import { z } from 'zod';
+import { Feature } from '../feature.js';
+import { Database } from 'bun:sqlite';
+declare module '@soederpop/luca/feature' {
+    interface AvailableFeatures {
+        semanticSearch: typeof SemanticSearch;
+    }
+}
+export declare const SemanticSearchOptionsSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    _cacheKey: z.ZodOptional<z.ZodString>;
+    cached: z.ZodOptional<z.ZodBoolean>;
+    enable: z.ZodOptional<z.ZodBoolean>;
+    dbPath: z.ZodDefault<z.ZodString>;
+    embeddingModel: z.ZodDefault<z.ZodString>;
+    embeddingProvider: z.ZodDefault<z.ZodEnum<{
+        local: "local";
+        openai: "openai";
+    }>>;
+    chunkStrategy: z.ZodDefault<z.ZodEnum<{
+        fixed: "fixed";
+        section: "section";
+        document: "document";
+    }>>;
+    chunkSize: z.ZodDefault<z.ZodNumber>;
+    chunkOverlap: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const SemanticSearchStateSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    indexed: z.ZodDefault<z.ZodNumber>;
+    embedded: z.ZodDefault<z.ZodNumber>;
+    lastIndexedAt: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    dbReady: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$loose>;
+export type SemanticSearchOptions = z.infer<typeof SemanticSearchOptionsSchema>;
+export type SemanticSearchState = z.infer<typeof SemanticSearchStateSchema>;
+export declare const SemanticSearchEventsSchema: z.ZodObject<{
+    stateChange: z.ZodTuple<[z.ZodAny], null>;
+    enabled: z.ZodTuple<[], null>;
+    modelLoaded: z.ZodTuple<[], null>;
+    dbReady: z.ZodTuple<[], null>;
+    indexed: z.ZodTuple<[z.ZodObject<{
+        documents: z.ZodNumber;
+        chunks: z.ZodNumber;
+    }, z.core.$strip>], null>;
+    modelDisposed: z.ZodTuple<[], null>;
+}, z.core.$strip>;
+export interface Chunk {
+    pathId: string;
+    section?: string;
+    headingPath?: string;
+    seq: number;
+    content: string;
+    contentHash: string;
+}
+export interface SearchResult {
+    pathId: string;
+    model: string;
+    title: string;
+    meta: Record<string, any>;
+    score: number;
+    snippet: string;
+    matchedSection?: string;
+    headingPath?: string;
+}
+export interface SearchOptions {
+    limit?: number;
+    model?: string;
+    where?: Record<string, any>;
+}
+export interface HybridSearchOptions extends SearchOptions {
+    ftsWeight?: number;
+    vecWeight?: number;
+}
+export interface IndexStatus {
+    documentCount: number;
+    chunkCount: number;
+    embeddingCount: number;
+    lastIndexedAt: string | null;
+    provider: string;
+    model: string;
+    dimensions: number;
+    dbSizeBytes: number;
+}
+export interface DocumentInput {
+    pathId: string;
+    model?: string;
+    title?: string;
+    slug?: string;
+    meta?: Record<string, any>;
+    content: string;
+    sections?: Array<{
+        heading: string;
+        headingPath: string;
+        content: string;
+        level: number;
+    }>;
+}
+/**
+ * Semantic search feature providing BM25 keyword search, vector similarity search,
+ * and hybrid search with Reciprocal Rank Fusion over a SQLite-backed index.
+ *
+ * Uses bun:sqlite for FTS5 keyword search and BLOB-stored embeddings with
+ * JavaScript cosine similarity for vector search.
+ *
+ * @extends Feature
+ *
+ * @example
+ * ```typescript
+ * const search = container.feature('semanticSearch', {
+ *   dbPath: '.contentbase/search.sqlite',
+ *   embeddingProvider: 'local',
+ * })
+ * await search.initDb()
+ * await search.indexDocuments(docs)
+ * const results = await search.hybridSearch('how does authentication work')
+ * ```
+ */
+export declare class SemanticSearch extends Feature<SemanticSearchState, SemanticSearchOptions> {
+    static stateSchema: z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        indexed: z.ZodDefault<z.ZodNumber>;
+        embedded: z.ZodDefault<z.ZodNumber>;
+        lastIndexedAt: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        dbReady: 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>;
+        dbPath: z.ZodDefault<z.ZodString>;
+        embeddingModel: z.ZodDefault<z.ZodString>;
+        embeddingProvider: z.ZodDefault<z.ZodEnum<{
+            local: "local";
+            openai: "openai";
+        }>>;
+        chunkStrategy: z.ZodDefault<z.ZodEnum<{
+            fixed: "fixed";
+            section: "section";
+            document: "document";
+        }>>;
+        chunkSize: z.ZodDefault<z.ZodNumber>;
+        chunkOverlap: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>;
+    static eventsSchema: z.ZodObject<{
+        stateChange: z.ZodTuple<[z.ZodAny], null>;
+        enabled: z.ZodTuple<[], null>;
+        modelLoaded: z.ZodTuple<[], null>;
+        dbReady: z.ZodTuple<[], null>;
+        indexed: z.ZodTuple<[z.ZodObject<{
+            documents: z.ZodNumber;
+            chunks: z.ZodNumber;
+        }, z.core.$strip>], null>;
+        modelDisposed: z.ZodTuple<[], null>;
+    }, z.core.$strip>;
+    static shortcut: "features.semanticSearch";
+    private _db;
+    private _llamaContext;
+    private _llamaModel;
+    private _llamaInstance;
+    private _idleTimer;
+    private _dimensions;
+    get initialState(): SemanticSearchState;
+    constructor(options: SemanticSearchOptions, context: any);
+    private get resolvedDbPath();
+    get db(): Database;
+    get dimensions(): number;
+    initDb(): Promise<void>;
+    private _createTables;
+    private _writeMeta;
+    private _verifyMeta;
+    insertDocument(doc: DocumentInput): void;
+    insertChunk(chunk: Chunk, embedding: Float32Array): void;
+    removeDocument(pathId: string): void;
+    getStats(): IndexStatus;
+    embed(texts: string[]): Promise<number[][]>;
+    private _embedLocal;
+    private _embedOpenAI;
+    ensureModel(): Promise<void>;
+    private _ensureLocalModel;
+    private _resetIdleTimer;
+    disposeModel(): Promise<void>;
+    getDimensions(): number;
+    chunkDocument(doc: DocumentInput, strategy?: 'section' | 'fixed' | 'document'): Chunk[];
+    search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+    vectorSearch(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+    hybridSearch(query: string, options?: HybridSearchOptions): Promise<SearchResult[]>;
+    deepSearch(_query: string, _options?: SearchOptions): Promise<SearchResult[]>;
+    private _fuseRRF;
+    private _buildWhereClause;
+    private _matchesFilters;
+    indexDocuments(docs: DocumentInput[]): Promise<void>;
+    reindex(pathIds?: string[]): Promise<void>;
+    removeStale(currentPathIds: string[]): void;
+    needsReindex(doc: DocumentInput): boolean;
+    status(): IndexStatus;
+    static readonly PINNED_LLAMA_VERSION = "3.17.1";
+    /**
+     * Install node-llama-cpp into the user's project for local embedding support.
+     * Detects package manager from lockfile presence and verifies the native addon loads.
+     */
+    installLocalEmbeddings(cwd: string): Promise<void>;
+    close(): Promise<void>;
+}
+export default SemanticSearch;
+//# sourceMappingURL=semantic-search.d.ts.map

package/dist/node/features/semantic-search.d.ts.map

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

package/dist/node/features/sqlite.d.ts

@@ -0,0 +1,180 @@
+import { z } from 'zod';
+import { Database } from 'bun:sqlite';
+import { Feature } from '../feature.js';
+import type { ContainerContext } from '../../container.js';
+type SqlValue = string | number | boolean | bigint | Uint8Array | Buffer | null;
+export declare const SqliteStateSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    connected: z.ZodDefault<z.ZodBoolean>;
+    path: z.ZodDefault<z.ZodString>;
+    lastQuery: z.ZodOptional<z.ZodString>;
+    lastChanges: z.ZodOptional<z.ZodNumber>;
+    lastInsertRowid: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodBigInt]>>;
+    lastError: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+export declare const SqliteOptionsSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    _cacheKey: z.ZodOptional<z.ZodString>;
+    cached: z.ZodOptional<z.ZodBoolean>;
+    enable: z.ZodOptional<z.ZodBoolean>;
+    path: z.ZodOptional<z.ZodString>;
+    readonly: z.ZodOptional<z.ZodBoolean>;
+    readwrite: z.ZodOptional<z.ZodBoolean>;
+    create: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type SqliteState = z.infer<typeof SqliteStateSchema>;
+export type SqliteOptions = z.infer<typeof SqliteOptionsSchema>;
+export declare const SqliteEventsSchema: z.ZodObject<{
+    stateChange: z.ZodTuple<[z.ZodAny], null>;
+    enabled: z.ZodTuple<[], null>;
+    query: z.ZodTuple<[z.ZodString, z.ZodArray<z.ZodAny>, z.ZodNumber], null>;
+    execute: z.ZodTuple<[z.ZodString, z.ZodArray<z.ZodAny>, z.ZodNumber], null>;
+    error: z.ZodTuple<[z.ZodAny], null>;
+    closed: z.ZodTuple<[], null>;
+}, z.core.$strip>;
+/**
+ * SQLite feature for safe SQL execution through Bun's native sqlite binding.
+ *
+ * Supports:
+ * - parameterized query execution (`query` / `execute`)
+ * - tagged-template query execution (`sql`) to avoid manual placeholder wiring
+ *
+ * @example
+ * ```typescript
+ * const sqlite = container.feature('sqlite', { path: 'data/app.db' })
+ *
+ * await sqlite.execute(
+ *   'create table if not exists users (id integer primary key, email text not null unique)'
+ * )
+ *
+ * await sqlite.execute('insert into users (email) values (?)', ['hello@example.com'])
+ *
+ * const users = await sqlite.sql<{ id: number; email: string }>`
+ *   select id, email from users where email = ${'hello@example.com'}
+ * `
+ * ```
+ */
+export declare class Sqlite extends Feature<SqliteState, SqliteOptions> {
+    static shortcut: "features.sqlite";
+    static stateSchema: z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        connected: z.ZodDefault<z.ZodBoolean>;
+        path: z.ZodDefault<z.ZodString>;
+        lastQuery: z.ZodOptional<z.ZodString>;
+        lastChanges: z.ZodOptional<z.ZodNumber>;
+        lastInsertRowid: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodBigInt]>>;
+        lastError: z.ZodOptional<z.ZodString>;
+    }, 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>;
+        path: z.ZodOptional<z.ZodString>;
+        readonly: z.ZodOptional<z.ZodBoolean>;
+        readwrite: z.ZodOptional<z.ZodBoolean>;
+        create: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>;
+    static eventsSchema: z.ZodObject<{
+        stateChange: z.ZodTuple<[z.ZodAny], null>;
+        enabled: z.ZodTuple<[], null>;
+        query: z.ZodTuple<[z.ZodString, z.ZodArray<z.ZodAny>, z.ZodNumber], null>;
+        execute: z.ZodTuple<[z.ZodString, z.ZodArray<z.ZodAny>, z.ZodNumber], null>;
+        error: z.ZodTuple<[z.ZodAny], null>;
+        closed: z.ZodTuple<[], null>;
+    }, z.core.$strip>;
+    private _db;
+    /**
+     * Default state for the SQLite feature before a database is opened.
+     * @returns The initial SqliteState with `connected: false` and in-memory path
+     */
+    get initialState(): SqliteState;
+    constructor(options: SqliteOptions, context: ContainerContext);
+    /** Returns the underlying Bun sqlite database instance. */
+    get db(): Database;
+    /**
+     * Executes a SELECT-like query and returns result rows.
+     *
+     * Use sqlite placeholders (`?`) for `params`.
+     *
+     * @param queryText - The SQL query string with optional `?` placeholders
+     * @param params - Ordered array of values to bind to the placeholders
+     * @returns Promise resolving to an array of typed result rows
+     * @throws {Error} When query text is empty or params contain `undefined`
+     *
+     * @example
+     * ```typescript
+     * const db = container.feature('sqlite', { path: 'app.db' })
+     * const users = await db.query<{ id: number; email: string }>(
+     *   'SELECT id, email FROM users WHERE active = ?',
+     *   [1]
+     * )
+     * ```
+     */
+    query<T extends object = Record<string, unknown>>(queryText: string, params?: SqlValue[]): Promise<T[]>;
+    /**
+     * Executes a write/update/delete statement and returns metadata.
+     *
+     * Use sqlite placeholders (`?`) for `params`.
+     *
+     * @param queryText - The SQL statement string with optional `?` placeholders
+     * @param params - Ordered array of values to bind to the placeholders
+     * @returns Promise resolving to `{ changes, lastInsertRowid }` metadata
+     * @throws {Error} When query text is empty or params contain `undefined`
+     *
+     * @example
+     * ```typescript
+     * const db = container.feature('sqlite', { path: 'app.db' })
+     * const { changes, lastInsertRowid } = await db.execute(
+     *   'INSERT INTO users (email) VALUES (?)',
+     *   ['hello@example.com']
+     * )
+     * console.log(`Inserted row ${lastInsertRowid}, ${changes} change(s)`)
+     * ```
+     */
+    execute(queryText: string, params?: SqlValue[]): Promise<{
+        changes: number;
+        lastInsertRowid: number | bigint | null;
+    }>;
+    /**
+     * Safe tagged-template SQL helper.
+     *
+     * Values become bound parameters automatically, preventing SQL injection.
+     *
+     * @param strings - Template literal string segments
+     * @param values - Interpolated values that become bound `?` parameters
+     * @returns Promise resolving to an array of typed result rows
+     *
+     * @example
+     * ```typescript
+     * const db = container.feature('sqlite', { path: 'app.db' })
+     * const email = 'hello@example.com'
+     * const rows = await db.sql<{ id: number }>`
+     *   SELECT id FROM users WHERE email = ${email}
+     * `
+     * ```
+     */
+    sql<T extends object = Record<string, unknown>>(strings: TemplateStringsArray, ...values: SqlValue[]): Promise<T[]>;
+    /**
+     * Closes the sqlite database and updates feature state.
+     *
+     * Emits `closed` after the database handle is released.
+     *
+     * @returns This Sqlite feature instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * const db = container.feature('sqlite', { path: 'app.db' })
+     * // ... run queries ...
+     * db.close()
+     * ```
+     */
+    close(): this;
+}
+export default Sqlite;
+declare module '../../feature.js' {
+    interface AvailableFeatures {
+        sqlite: typeof Sqlite;
+    }
+}
+//# sourceMappingURL=sqlite.d.ts.map

package/dist/node/features/sqlite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite.d.ts","sourceRoot":"","sources":["../../../src/node/features/sqlite.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AAEvC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AAE1D,KAAK,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,UAAU,GAAG,MAAM,GAAG,IAAI,CAAA;AAE/E,eAAO,MAAM,iBAAiB;;;;;;;;iBAO5B,CAAA;AAEF,eAAO,MAAM,mBAAmB;;;;;;;;;iBAK9B,CAAA;AAEF,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAA;AAC3D,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAA;AAE/D,eAAO,MAAM,kBAAkB;;;;;;;iBAe7B,CAAA;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,MAAO,SAAQ,OAAO,CAAC,WAAW,EAAE,aAAa,CAAC;IAC7D,OAAgB,QAAQ,EAAG,iBAAiB,CAAS;IACrD,OAAgB,WAAW;;;;;;;;sBAAoB;IAC/C,OAAgB,aAAa;;;;;;;;;sBAAsB;IACnD,OAAgB,YAAY;;;;;;;sBAAqB;IAGjD,OAAO,CAAC,GAAG,CAAU;IAErB;;;OAGG;IACH,IAAa,YAAY,IAAI,WAAW,CAMvC;gBAEW,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,gBAAgB;IAiB7D,2DAA2D;IAC3D,IAAI,EAAE,aAEL;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACG,KAAK,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,GAAE,QAAQ,EAAO,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IA0BjH;;;;;;;;;;;;;;;;;;;OAmBG;IACG,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,GAAE,QAAQ,EAAO,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IA+BhI;;;;;;;;;;;;;;;;;OAiBG;IACG,GAAG,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,oBAAoB,EAAE,GAAG,MAAM,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAKzH;;;;;;;;;;;;;OAaG;IACH,KAAK;CAMN;AAED,eAAe,MAAM,CAAA;AACrB,OAAO,QAAQ,kBAAkB,CAAC;IAChC,UAAU,iBAAiB;QACzB,MAAM,EAAE,OAAO,MAAM,CAAA;KACtB;CACF"}

package/dist/node/features/telegram.d.ts

@@ -0,0 +1,173 @@
+import { z } from 'zod';
+import { Feature } from '../feature.js';
+import { Bot, type Context, type Middleware } from 'grammy';
+type UserFromGetMe = Awaited<ReturnType<Bot['api']['getMe']>>;
+export declare const TelegramBotInfoSchema: z.ZodObject<{
+    id: z.ZodNumber;
+    firstName: z.ZodString;
+    username: z.ZodOptional<z.ZodString>;
+    canJoinGroups: z.ZodOptional<z.ZodBoolean>;
+    canReadAllGroupMessages: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const TelegramStateSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    mode: z.ZodDefault<z.ZodEnum<{
+        polling: "polling";
+        webhook: "webhook";
+        idle: "idle";
+    }>>;
+    isRunning: z.ZodDefault<z.ZodBoolean>;
+    webhookUrl: z.ZodOptional<z.ZodString>;
+    commandsRegistered: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    lastError: z.ZodOptional<z.ZodString>;
+    botInfo: z.ZodOptional<z.ZodObject<{
+        id: z.ZodNumber;
+        firstName: z.ZodString;
+        username: z.ZodOptional<z.ZodString>;
+        canJoinGroups: z.ZodOptional<z.ZodBoolean>;
+        canReadAllGroupMessages: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+}, z.core.$loose>;
+export type TelegramState = z.infer<typeof TelegramStateSchema>;
+export declare const TelegramOptionsSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    _cacheKey: z.ZodOptional<z.ZodString>;
+    cached: z.ZodOptional<z.ZodBoolean>;
+    enable: z.ZodOptional<z.ZodBoolean>;
+    token: z.ZodOptional<z.ZodString>;
+    mode: z.ZodDefault<z.ZodEnum<{
+        polling: "polling";
+        webhook: "webhook";
+    }>>;
+    webhookUrl: z.ZodOptional<z.ZodString>;
+    webhookPath: z.ZodDefault<z.ZodString>;
+    webhookPort: z.ZodOptional<z.ZodNumber>;
+    autoStart: z.ZodOptional<z.ZodBoolean>;
+    dropPendingUpdates: z.ZodOptional<z.ZodBoolean>;
+    pollingTimeout: z.ZodDefault<z.ZodNumber>;
+    pollingLimit: z.ZodOptional<z.ZodNumber>;
+    allowedUpdates: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type TelegramOptions = z.infer<typeof TelegramOptionsSchema>;
+export declare const TelegramEventsSchema: z.ZodObject<{
+    stateChange: z.ZodTuple<[z.ZodAny], null>;
+    enabled: z.ZodTuple<[], null>;
+    started: z.ZodTuple<[z.ZodObject<{
+        mode: z.ZodString;
+    }, z.core.$strip>], null>;
+    stopped: z.ZodTuple<[], null>;
+    error: z.ZodTuple<[z.ZodAny], null>;
+    command: z.ZodTuple<[z.ZodString, z.ZodAny], null>;
+    webhook_ready: z.ZodTuple<[z.ZodString], null>;
+}, z.core.$strip>;
+/**
+ * Telegram bot feature powered by grammY.
+ *
+ * Supports both long-polling and webhook modes. Exposes the grammY Bot instance
+ * directly for full API access while bridging events to Luca's event bus.
+ *
+ * @example
+ * ```typescript
+ * const tg = container.feature('telegram', { autoStart: true })
+ * tg.command('start', (ctx) => ctx.reply('Hello!'))
+ * tg.handle('message:text', (ctx) => ctx.reply(`Echo: ${ctx.message.text}`))
+ * ```
+ */
+export declare class Telegram extends Feature<TelegramState, TelegramOptions> {
+    static shortcut: "features.telegram";
+    static envVars: string[];
+    static stateSchema: z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        mode: z.ZodDefault<z.ZodEnum<{
+            polling: "polling";
+            webhook: "webhook";
+            idle: "idle";
+        }>>;
+        isRunning: z.ZodDefault<z.ZodBoolean>;
+        webhookUrl: z.ZodOptional<z.ZodString>;
+        commandsRegistered: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        lastError: z.ZodOptional<z.ZodString>;
+        botInfo: z.ZodOptional<z.ZodObject<{
+            id: z.ZodNumber;
+            firstName: z.ZodString;
+            username: z.ZodOptional<z.ZodString>;
+            canJoinGroups: z.ZodOptional<z.ZodBoolean>;
+            canReadAllGroupMessages: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>;
+    }, 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>;
+        token: z.ZodOptional<z.ZodString>;
+        mode: z.ZodDefault<z.ZodEnum<{
+            polling: "polling";
+            webhook: "webhook";
+        }>>;
+        webhookUrl: z.ZodOptional<z.ZodString>;
+        webhookPath: z.ZodDefault<z.ZodString>;
+        webhookPort: z.ZodOptional<z.ZodNumber>;
+        autoStart: z.ZodOptional<z.ZodBoolean>;
+        dropPendingUpdates: z.ZodOptional<z.ZodBoolean>;
+        pollingTimeout: z.ZodDefault<z.ZodNumber>;
+        pollingLimit: z.ZodOptional<z.ZodNumber>;
+        allowedUpdates: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>;
+    static eventsSchema: z.ZodObject<{
+        stateChange: z.ZodTuple<[z.ZodAny], null>;
+        enabled: z.ZodTuple<[], null>;
+        started: z.ZodTuple<[z.ZodObject<{
+            mode: z.ZodString;
+        }, z.core.$strip>], null>;
+        stopped: z.ZodTuple<[], null>;
+        error: z.ZodTuple<[z.ZodAny], null>;
+        command: z.ZodTuple<[z.ZodString, z.ZodAny], null>;
+        webhook_ready: z.ZodTuple<[z.ZodString], null>;
+    }, z.core.$strip>;
+    private _bot?;
+    get initialState(): TelegramState;
+    /** Bot token from options or TELEGRAM_BOT_TOKEN env var. */
+    get token(): string;
+    /** The grammY Bot instance. Created lazily on first access. */
+    get bot(): Bot;
+    /** Whether the bot is currently receiving updates. */
+    get isRunning(): boolean;
+    /** Current operation mode: 'polling', 'webhook', or 'idle'. */
+    get mode(): 'polling' | 'webhook' | 'idle';
+    /** Access chalk colors via the container's UI feature. */
+    private get c();
+    enable(options?: any): Promise<this>;
+    /** Start the bot in the configured mode (polling or webhook). */
+    start(): Promise<this>;
+    /** Stop the bot gracefully. */
+    stop(): Promise<this>;
+    /** Register a command handler. Also emits 'command' on the Luca event bus. */
+    command(name: string, handler: (ctx: Context) => any): this;
+    /**
+     * Register a grammY update handler (filter query).
+     * Named 'handle' to avoid collision with the inherited on() event bus method.
+     *
+     * @example
+     * ```typescript
+     * tg.handle('message:text', (ctx) => ctx.reply('Got text'))
+     * tg.handle('callback_query:data', (ctx) => ctx.answerCallbackQuery('Clicked'))
+     * ```
+     */
+    handle(filter: Parameters<Bot['on']>[0], handler: (ctx: any) => any): this;
+    /** Add grammY middleware. */
+    use(...middleware: Middleware[]): this;
+    /** Start long-polling mode. */
+    startPolling(dropPendingUpdates?: boolean): Promise<this>;
+    /** Set up webhook mode with an Express server. */
+    setupWebhook(url?: string, path?: string): Promise<this>;
+    /** Remove the webhook from Telegram. */
+    deleteWebhook(): Promise<this>;
+    /** Get bot info from Telegram API. */
+    getMe(): Promise<UserFromGetMe>;
+    /** Print a diagnostic summary of the bot's current state. */
+    diagnostics(): this;
+    private _setupErrorHandling;
+}
+export default Telegram;
+//# sourceMappingURL=telegram.d.ts.map

package/dist/node/features/telegram.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telegram.d.ts","sourceRoot":"","sources":["../../../src/node/features/telegram.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AACvC,OAAO,EAAE,GAAG,EAAmB,KAAK,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,QAAQ,CAAA;AAE5E,KAAK,aAAa,GAAG,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAA;AAE7D,eAAO,MAAM,qBAAqB;;;;;;iBAMhC,CAAA;AAEF,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;iBAa9B,CAAA;AACF,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAA;AAE/D,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;iBAqBhC,CAAA;AACF,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAA;AAEnE,eAAO,MAAM,oBAAoB;;;;;;;;;;iBAM/B,CAAA;AAEF;;;;;;;;;;;;GAYG;AACH,qBAAa,QAAS,SAAQ,OAAO,CAAC,aAAa,EAAE,eAAe,CAAC;IACnE,OAAgB,QAAQ,EAAG,mBAAmB,CAAS;IACvD,OAAgB,OAAO,WAAyB;IAChD,OAAgB,WAAW;;;;;;;;;;;;;;;;;;sBAAsB;IACjD,OAAgB,aAAa;;;;;;;;;;;;;;;;;;sBAAwB;IACrD,OAAgB,YAAY;;;;;;;;;;sBAAuB;IAGnD,OAAO,CAAC,IAAI,CAAC,CAAK;IAElB,IAAa,YAAY,IAAI,aAAa,CAOzC;IAED,4DAA4D;IAC5D,IAAI,KAAK,IAAI,MAAM,CAMlB;IAED,+DAA+D;IAC/D,IAAI,GAAG,IAAI,GAAG,CAMb;IAED,sDAAsD;IACtD,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,+DAA+D;IAC/D,IAAI,IAAI,IAAI,SAAS,GAAG,SAAS,GAAG,MAAM,CAEzC;IAED,0DAA0D;IAC1D,OAAO,KAAK,CAAC,GAEZ;IAEc,MAAM,CAAC,OAAO,GAAE,GAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAiCvD,iEAAiE;IAC3D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAY5B,+BAA+B;IACzB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAgB3B,8EAA8E;IAC9E,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,GAAG,GAAG,IAAI;IAa3D;;;;;;;;;OASG;IACH,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,GAAG,GAAG,IAAI;IAK1E,6BAA6B;IAC7B,GAAG,CAAC,GAAG,UAAU,EAAE,UAAU,EAAE,GAAG,IAAI;IAOtC,+BAA+B;IACzB,YAAY,CAAC,kBAAkB,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IA2B/D,kDAAkD;IAC5C,YAAY,CAAC,GAAG,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAsC9D,wCAAwC;IAClC,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;IAMpC,sCAAsC;IAChC,KAAK,IAAI,OAAO,CAAC,aAAa,CAAC;IAIrC,6DAA6D;IAC7D,WAAW,IAAI,IAAI;IAyBnB,OAAO,CAAC,mBAAmB;CAO5B;AAED,eAAe,QAAQ,CAAA"}

package/dist/node/features/transpiler.d.ts

@@ -0,0 +1,51 @@
+import { Feature } from '../feature.js';
+export interface TransformOptions {
+    loader?: 'ts' | 'tsx' | 'jsx' | 'js';
+    format?: 'esm' | 'cjs';
+    minify?: boolean;
+}
+export interface TransformResult {
+    code: string;
+    map: string;
+    warnings: any[];
+}
+/**
+ * Transpile TypeScript, TSX, and JSX to JavaScript at runtime using Bun's
+ * built-in transpiler. Compile code strings on the fly without touching the
+ * filesystem or spawning external processes.
+ *
+ * @example
+ * ```typescript
+ * const transpiler = container.feature('transpiler')
+ * const result = transpiler.transformSync('const x: number = 1')
+ * console.log(result.code) // 'const x = 1;\n'
+ * ```
+ */
+export declare class Transpiler extends Feature {
+    static shortcut: "features.transpiler";
+    static stateSchema: import("zod").ZodObject<{
+        enabled: import("zod").ZodDefault<import("zod").ZodBoolean>;
+    }, import("zod/v4/core").$loose>;
+    static optionsSchema: import("zod").ZodObject<{
+        name: import("zod").ZodOptional<import("zod").ZodString>;
+        _cacheKey: import("zod").ZodOptional<import("zod").ZodString>;
+        cached: import("zod").ZodOptional<import("zod").ZodBoolean>;
+        enable: import("zod").ZodOptional<import("zod").ZodBoolean>;
+    }, import("zod/v4/core").$strip>;
+    /**
+     * Transform code synchronously
+     * @param code - The code to transform
+     * @param options - Transform options (loader, format, minify)
+     * @returns The transformed code as { code, map, warnings }
+     */
+    transformSync(code: string, options?: TransformOptions): TransformResult;
+    /**
+     * Transform code asynchronously
+     * @param code - The code to transform
+     * @param options - Transform options (loader, format, minify)
+     * @returns The transformed code as { code, map, warnings }
+     */
+    transform(code: string, options?: TransformOptions): Promise<TransformResult>;
+}
+export default Transpiler;
+//# sourceMappingURL=transpiler.d.ts.map

package/dist/node/features/transpiler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transpiler.d.ts","sourceRoot":"","sources":["../../../src/node/features/transpiler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AAGvC,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,EAAE,IAAI,GAAG,KAAK,GAAG,KAAK,GAAG,IAAI,CAAA;IACpC,MAAM,CAAC,EAAE,KAAK,GAAG,KAAK,CAAA;IACtB,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;IACX,QAAQ,EAAE,GAAG,EAAE,CAAA;CAChB;AA+DD;;;;;;;;;;;GAWG;AACH,qBAAa,UAAW,SAAQ,OAAO;IACrC,OAAgB,QAAQ,EAAG,qBAAqB,CAAS;IACzD,OAAgB,WAAW;;qCAAqB;IAChD,OAAgB,aAAa;;;;;qCAAuB;IAGpD;;;;;OAKG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,GAAG,eAAe;IAc5E;;;;;OAKG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,eAAe,CAAC;CAaxF;AAED,eAAe,UAAU,CAAA"}