@hatk/hatk 0.0.1-alpha.9 → 0.0.1-alpha.92

package/dist/config.d.ts

@@ -20,28 +20,172 @@ export interface OAuthConfig {
     issuer: string;
     scopes: string[];
     clients: OAuthClientConfig[];
+    cookieName?: string;
+    /**
+     * Scopes requested only from PDSes that serve `whenMethod`, discovered
+     * through `community.lexicon.service.describe` before the authorization
+     * request is pushed.
+     *
+     * For optional protocol features — permissioned spaces (proposal 0016) being
+     * the first — where asking every PDS for the scope would put a permission on
+     * the consent screen that most servers cannot honor.
+     */
+    conditionalScopes?: ConditionalScopeConfig[];
+}
+export interface ConditionalScopeConfig {
+    /** An XRPC method whose presence means the PDS implements the feature. */
+    whenMethod: string;
+    scopes: string[];
+}
+/**
+ * A record that names another repo worth tracking.
+ *
+ * Backfill and the stream find repos by what they write into the signal
+ * collections. Some repos matter because a record points at them instead: a
+ * community's roster names its members, and a member's own repo — their
+ * profile first of all — is what puts a name and a face on everything they
+ * write. Each reference says which collection carries such a record and which
+ * field holds the DID.
+ */
+export interface RepoReference {
+    collection: string;
+    /** Dot path to the DID inside the record, or `$rkey` when the record key is the DID. */
+    field: string;
 }
 export interface BackfillConfig {
     signalCollections?: string[];
     repos?: string[];
+    /** Records that name repos to track; see {@link RepoReference}. */
+    references?: RepoReference[];
     fullNetwork: boolean;
     parallelism: number;
     fetchTimeout: number;
     maxRetries: number;
 }
+export interface ApnsPushConfig {
+    keyFile: string;
+    keyId: string;
+    teamId: string;
+    bundleId: string;
+    production?: boolean;
+}
+/**
+ * Firebase Cloud Messaging, for Android devices.
+ *
+ * `keyFile` is a Google service-account JSON carrying the Firebase Messaging
+ * role, resolved relative to the config file like the APNs key. The project id
+ * comes from that file unless it's overridden here.
+ */
+export interface FcmPushConfig {
+    keyFile: string;
+    projectId?: string;
+}
+/** Either transport may stand alone; a platform without one simply isn't sent to. */
+export interface PushConfig {
+    apns?: ApnsPushConfig;
+    fcm?: FcmPushConfig;
+}
+export interface CdnConfig {
+    url: string;
+    key: string;
+    salt: string;
+}
+/**
+ * Indexing permissioned spaces (proposal 0016).
+ *
+ * A space's records never reach a firehose, so they are read from the
+ * authority and each writer's own host instead. Doing that at all requires
+ * `oauth`: hatk is a member of nothing and borrows a signed-in member's
+ * delegation to get a credential, so with no sessions there is no way in.
+ *
+ * Absent by default. An instance that does not set this indexes nothing from a
+ * space and serves no space rows, which is what every existing deployment does
+ * today.
+ */
+export interface SpacesConfig {
+    /**
+     * Space type NSIDs to follow. A space of any other type is refused rather
+     * than indexed, so a lexicon vendored for reference cannot quietly become a
+     * subscription.
+     */
+    types: string[];
+    /** Space refs to follow at boot, for the spaces an instance always wants. */
+    watch?: string[];
+    /**
+     * Seconds between reconcile sweeps. Write notices are best-effort — the
+     * reference host forwards each once and logs the failure — so the sweep is
+     * what makes sync correct rather than merely prompt.
+     */
+    reconcileInterval?: number;
+    /**
+     * This instance's own DID, for receiving write notices — e.g.
+     * `did:web:appview.example.com`. hatk serves the matching document at
+     * `/.well-known/did.json`, so the DID has to resolve to this origin.
+     *
+     * Without it the sweep is the only thing that notices a write, which is
+     * correct but no faster than the interval. The DID publishes no signing key:
+     * notices are only ever verified here, never signed.
+     */
+    serviceDid?: string;
+    /**
+     * The service entry notices are delivered to, named in the DID document and
+     * in every registration. Its own fragment rather than the bare DID, so a
+     * notice cannot be confused with one addressed to an account.
+     */
+    serviceFragment?: string;
+}
+export interface JetstreamConfig {
+    /** Instance base URL, e.g. `wss://jetstream.us-east.bsky.network`. */
+    url: string;
+}
 export interface HatkConfig {
     relay: string;
+    /**
+     * Additional `subscribeRepos` sources tailed alongside `relay`, each with
+     * its own cursor. For repos whose PDS is not behind the relay — a dev stack
+     * with more than one PDS, a self-hosted network — tail the PDS directly
+     * instead of standing up a relay to merge the streams. Ignored when
+     * `jetstream` is set (Jetstream is the sole source then).
+     */
+    relays: string[];
+    /**
+     * Consume the stream from a Jetstream v2 instance instead of `relay`.
+     *
+     * Jetstream filters server-side and delivers records as decoded JSON, so an
+     * AppView tracking a few collections stops paying to decode the whole
+     * network. Not every deployment has one — a local PDS or self-hosted relay
+     * won't — so `relay` stays the default.
+     */
+    jetstream: JetstreamConfig | null;
     plc: string;
     port: number;
+    cdn: CdnConfig | null;
+    databaseEngine: 'duckdb' | 'sqlite';
     database: string;
     publicDir: string | null;
     collections: string[];
+    privateCollections: string[];
     backfill: BackfillConfig;
     ftsRebuildInterval: number;
     oauth: OAuthConfig | null;
+    push: PushConfig | null;
     admins: string[];
+    spaces: SpacesConfig | null;
 }
+/** Input type for defineConfig — fields that have defaults are optional. */
+export type HatkConfigInput = Partial<Omit<HatkConfig, 'oauth' | 'backfill' | 'push' | 'cdn' | 'jetstream' | 'spaces'>> & {
+    cdn?: CdnConfig | null;
+    oauth?: (Partial<OAuthConfig> & {
+        clients: OAuthClientConfig[];
+    }) | null;
+    backfill?: Partial<BackfillConfig>;
+    push?: PushConfig | null;
+    jetstream?: JetstreamConfig | null;
+    spaces?: SpacesConfig | null;
+};
+/** Identity function that provides type inference for hatk config files. */
+export declare function defineConfig(config: HatkConfigInput): HatkConfigInput;
 /** Derive HTTP URL from relay WebSocket URL (ws://host → http://host) */
 export declare function relayHttpUrl(relay: string): string;
-export declare function loadConfig(configPath: string): HatkConfig;
+export declare function loadConfig(configPath: string): Promise<HatkConfig>;
 //# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAA;IACrC,KAAK,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAAA;IACnC,cAAc,EAAE,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAA;IAC1C,OAAO,CAAC,EAAE,WAAW,EAAE,CAAA;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,EAAE,MAAM,CAAA;IACnB,aAAa,EAAE,MAAM,EAAE,CAAA;IACvB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,OAAO,EAAE,iBAAiB,EAAE,CAAA;CAC7B;AAED,MAAM,WAAW,cAAc;IAC7B,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAA;IAC5B,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;IAChB,WAAW,EAAE,OAAO,CAAA;IACpB,WAAW,EAAE,MAAM,CAAA;IACnB,YAAY,EAAE,MAAM,CAAA;IACpB,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAA;IACb,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,QAAQ,EAAE,cAAc,CAAA;IACxB,kBAAkB,EAAE,MAAM,CAAA;IAC1B,KAAK,EAAE,WAAW,GAAG,IAAI,CAAA;IACzB,MAAM,EAAE,MAAM,EAAE,CAAA;CACjB;AAED,yEAAyE;AACzE,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,UAAU,CAyCzD"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/config.js

@@ -1,35 +1,87 @@
-import { readFileSync } from 'node:fs';
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
 import { resolve, dirname } from 'node:path';
-import YAML from 'yaml';
+import { existsSync } from 'node:fs';
+/** Identity function that provides type inference for hatk config files. */
+export function defineConfig(config) {
+    return config;
+}
 /** Derive HTTP URL from relay WebSocket URL (ws://host → http://host) */
 export function relayHttpUrl(relay) {
     return relay.replace(/^ws(s?):\/\//, 'http$1://');
 }
-export function loadConfig(configPath) {
-    const raw = readFileSync(configPath, 'utf-8');
-    const parsed = YAML.parse(raw);
-    const configDir = dirname(resolve(configPath));
+export async function loadConfig(configPath) {
+    const resolved = resolve(configPath);
+    if (!existsSync(resolved)) {
+        console.error(`Config file not found: ${resolved}`);
+        console.error(`hatk now uses hatk.config.ts instead of config.yaml.`);
+        console.error(`Create a hatk.config.ts file or run 'hatk new' to scaffold a project.`);
+        process.exit(1);
+    }
+    const configDir = dirname(resolved);
+    let mod;
+    try {
+        mod = await import(__rewriteRelativeImportExtension(/* @vite-ignore */ resolved));
+    }
+    catch (err) {
+        console.error(`Failed to load config file: ${resolved}`);
+        console.error(err.message || err);
+        process.exit(1);
+    }
+    const parsed = mod.default || {};
     const backfillRaw = parsed.backfill || {};
     const env = process.env;
     const database = env.DATABASE || parsed.database;
     const config = {
         relay: env.RELAY || parsed.relay || 'ws://localhost:2583',
+        relays: env.RELAYS
+            ? env.RELAYS.split(',')
+                .map((s) => s.trim())
+                .filter(Boolean)
+            : parsed.relays || [],
+        jetstream: env.JETSTREAM_URL ? { url: env.JETSTREAM_URL } : parsed.jetstream || null,
         plc: env.DID_PLC_URL || parsed.plc || 'https://plc.directory',
         port: parseInt(env.PORT || '') || parsed.port || 3000,
+        databaseEngine: (env.DATABASE_ENGINE || parsed.databaseEngine || 'sqlite'),
         database: database ? resolve(configDir, database) : ':memory:',
-        publicDir: parsed.public === false ? null : resolve(configDir, parsed.public || './public'),
+        publicDir: parsed.publicDir === null ? null : resolve(configDir, parsed.publicDir || './public'),
         collections: parsed.collections || [],
+        privateCollections: parsed.privateCollections || [],
         backfill: {
             signalCollections: backfillRaw.signalCollections || undefined,
+            references: backfillRaw.references || undefined,
             repos: env.BACKFILL_REPOS ? env.BACKFILL_REPOS.split(',').map((s) => s.trim()) : backfillRaw.repos || undefined,
             fullNetwork: env.BACKFILL_FULL_NETWORK ? env.BACKFILL_FULL_NETWORK === 'true' : backfillRaw.fullNetwork || false,
             parallelism: parseInt(env.BACKFILL_PARALLELISM || '') || backfillRaw.parallelism || 3,
             fetchTimeout: parseInt(env.BACKFILL_FETCH_TIMEOUT || '') || backfillRaw.fetchTimeout || 300,
             maxRetries: parseInt(env.BACKFILL_MAX_RETRIES || '') || backfillRaw.maxRetries || 5,
         },
-        ftsRebuildInterval: parseInt(env.FTS_REBUILD_INTERVAL || '') || parsed.ftsRebuildInterval || 500,
+        ftsRebuildInterval: parseInt(env.FTS_REBUILD_INTERVAL || '') || parsed.ftsRebuildInterval || 5000,
+        cdn: env.CDN_URL && env.CDN_KEY && env.CDN_SALT
+            ? { url: env.CDN_URL, key: env.CDN_KEY, salt: env.CDN_SALT }
+            : parsed.cdn || null,
         oauth: null,
+        push: parsed.push || null,
         admins: env.ADMINS ? env.ADMINS.split(',').map((s) => s.trim()) : parsed.admins || [],
+        spaces: parsed.spaces
+            ? {
+                types: parsed.spaces.types || [],
+                watch: env.SPACES_WATCH
+                    ? env.SPACES_WATCH.split(',')
+                        .map((s) => s.trim())
+                        .filter(Boolean)
+                    : parsed.spaces.watch || [],
+                reconcileInterval: parseInt(env.SPACES_RECONCILE_INTERVAL || '') || parsed.spaces.reconcileInterval || 300,
+                serviceDid: env.SPACES_SERVICE_DID || parsed.spaces.serviceDid || undefined,
+                serviceFragment: parsed.spaces.serviceFragment || 'atproto_space_syncer',
+            }
+            : null,
     };
     const oauthRaw = parsed.oauth;
     if (oauthRaw) {
@@ -37,6 +89,7 @@ export function loadConfig(configPath) {
             issuer: process.env.OAUTH_ISSUER || oauthRaw.issuer || `http://127.0.0.1:${config.port}`,
             scopes: oauthRaw.scopes || ['atproto'],
             clients: oauthRaw.clients || [],
+            conditionalScopes: oauthRaw.conditionalScopes || [],
         };
     }
     return config;

package/dist/database/adapter-factory.d.ts

@@ -0,0 +1,6 @@
+import type { DatabasePort, SearchPort } from './ports.ts';
+export declare function createAdapter(engine: 'duckdb' | 'sqlite'): Promise<{
+    adapter: DatabasePort;
+    searchPort: SearchPort | null;
+}>;
+//# sourceMappingURL=adapter-factory.d.ts.map

package/dist/database/adapter-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-factory.d.ts","sourceRoot":"","sources":["../../src/database/adapter-factory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAE1D,wBAAsB,aAAa,CAAC,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAC;IACxE,OAAO,EAAE,YAAY,CAAA;IACrB,UAAU,EAAE,UAAU,GAAG,IAAI,CAAA;CAC9B,CAAC,CAmBD"}

package/dist/database/adapter-factory.js

@@ -0,0 +1,20 @@
+export async function createAdapter(engine) {
+    switch (engine) {
+        case 'duckdb': {
+            const { DuckDBAdapter } = await import("./adapters/duckdb.js");
+            const { DuckDBSearchPort } = await import("./adapters/duckdb-search.js");
+            const adapter = new DuckDBAdapter();
+            const searchPort = new DuckDBSearchPort(adapter);
+            return { adapter, searchPort };
+        }
+        case 'sqlite': {
+            const { SQLiteAdapter } = await import("./adapters/sqlite.js");
+            const { SQLiteSearchPort } = await import("./adapters/sqlite-search.js");
+            const adapter = new SQLiteAdapter();
+            const searchPort = new SQLiteSearchPort(adapter);
+            return { adapter, searchPort };
+        }
+        default:
+            throw new Error(`Unsupported database engine: ${engine}`);
+    }
+}

package/dist/database/adapters/duckdb-search.d.ts

@@ -0,0 +1,12 @@
+import type { SearchPort } from '../ports.ts';
+import type { DatabasePort } from '../ports.ts';
+export declare class DuckDBSearchPort implements SearchPort {
+    private port;
+    constructor(port: DatabasePort);
+    buildIndex(shadowTable: string, sourceQuery: string, searchColumns: string[]): Promise<void>;
+    search(shadowTable: string, query: string, searchColumns: string[], limit: number, offset: number): Promise<Array<{
+        uri: string;
+        score: number;
+    }>>;
+}
+//# sourceMappingURL=duckdb-search.d.ts.map

package/dist/database/adapters/duckdb-search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"duckdb-search.d.ts","sourceRoot":"","sources":["../../../src/database/adapters/duckdb-search.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAC7C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE/C,qBAAa,gBAAiB,YAAW,UAAU;IACrC,OAAO,CAAC,IAAI;gBAAJ,IAAI,EAAE,YAAY;IAEhC,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAiB5F,MAAM,CACV,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,MAAM,EAAE,EACvB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CASlD"}

package/dist/database/adapters/duckdb-search.js

@@ -0,0 +1,27 @@
+export class DuckDBSearchPort {
+    port;
+    constructor(port) {
+        this.port = port;
+    }
+    async buildIndex(shadowTable, sourceQuery, searchColumns) {
+        // Create shadow table
+        await this.port.execute(`CREATE OR REPLACE TABLE ${shadowTable} AS ${sourceQuery}`, []);
+        // Drop existing index
+        try {
+            await this.port.execute(`PRAGMA drop_fts_index('${shadowTable}')`, []);
+        }
+        catch { }
+        // Build FTS index
+        const colList = searchColumns.map((c) => `'${c}'`).join(', ');
+        await this.port.execute(`PRAGMA create_fts_index('${shadowTable}', 'uri', ${colList}, stemmer='porter', stopwords='english', strip_accents=1, lower=1, overwrite=1)`, []);
+    }
+    async search(shadowTable, query, searchColumns, limit, offset) {
+        const ftsSchema = `fts_main_${shadowTable}`;
+        const sql = `SELECT uri, ${ftsSchema}.match_bm25(uri, $1) AS score
+      FROM ${shadowTable}
+      WHERE score IS NOT NULL
+      ORDER BY score DESC
+      LIMIT $2 OFFSET $3`;
+        return this.port.query(sql, [query, limit, offset]);
+    }
+}

package/dist/database/adapters/duckdb.d.ts

@@ -0,0 +1,25 @@
+import type { DatabasePort, BulkInserter, Dialect } from '../ports.ts';
+export declare class DuckDBAdapter implements DatabasePort {
+    dialect: Dialect;
+    private instance;
+    private writeCon;
+    private readCon;
+    private writeQueue;
+    private readQueue;
+    open(path: string): Promise<void>;
+    close(): void;
+    query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
+    execute(sql: string, params?: unknown[]): Promise<void>;
+    executeMultiple(sql: string): Promise<void>;
+    beginTransaction(): Promise<void>;
+    commit(): Promise<void>;
+    rollback(): Promise<void>;
+    createBulkInserter(table: string, _columns: string[], _options?: {
+        onConflict?: 'ignore' | 'replace';
+        batchSize?: number;
+    }): Promise<BulkInserter>;
+    /** Enqueue a read or write operation for serialization */
+    private enqueue;
+    private bindParams;
+}
+//# sourceMappingURL=duckdb.d.ts.map

package/dist/database/adapters/duckdb.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"duckdb.d.ts","sourceRoot":"","sources":["../../../src/database/adapters/duckdb.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AAEtE,qBAAa,aAAc,YAAW,YAAY;IAChD,OAAO,EAAE,OAAO,CAAW;IAE3B,OAAO,CAAC,QAAQ,CAAiB;IACjC,OAAO,CAAC,QAAQ,CAAiD;IACjE,OAAO,CAAC,OAAO,CAAiD;IAChE,OAAO,CAAC,UAAU,CAAoB;IACtC,OAAO,CAAC,SAAS,CAAoB;IAE/B,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMvC,KAAK,IAAI,IAAI;IAYP,KAAK,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,OAAO,EAAO,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAarF,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,OAAO,EAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAY3D,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ3C,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC;IAMjC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAMvB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAMzB,kBAAkB,CACtB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAAE,EAClB,QAAQ,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GACnE,OAAO,CAAC,YAAY,CAAC;IAqCxB,0DAA0D;IAC1D,OAAO,CAAC,OAAO;IAkBf,OAAO,CAAC,UAAU;CAyBnB"}

package/dist/database/adapters/duckdb.js

@@ -0,0 +1,161 @@
+import { DuckDBInstance } from '@duckdb/node-api';
+export class DuckDBAdapter {
+    dialect = 'duckdb';
+    instance;
+    writeCon;
+    readCon;
+    writeQueue = Promise.resolve();
+    readQueue = Promise.resolve();
+    async open(path) {
+        this.instance = await DuckDBInstance.create(path === ':memory:' ? undefined : path);
+        this.writeCon = await this.instance.connect();
+        this.readCon = await this.instance.connect();
+    }
+    close() {
+        try {
+            this.readCon?.closeSync();
+        }
+        catch { }
+        try {
+            this.writeCon?.closeSync();
+        }
+        catch { }
+        try {
+            this.instance?.closeSync();
+        }
+        catch { }
+    }
+    async query(sql, params = []) {
+        return this.enqueue('read', async () => {
+            if (params.length === 0) {
+                const reader = await this.readCon.runAndReadAll(sql);
+                return reader.getRowObjects();
+            }
+            const prepared = await this.readCon.prepare(sql);
+            this.bindParams(prepared, params);
+            const reader = await prepared.runAndReadAll();
+            return reader.getRowObjects();
+        });
+    }
+    async execute(sql, params = []) {
+        return this.enqueue('write', async () => {
+            if (params.length === 0) {
+                await this.writeCon.run(sql);
+                return;
+            }
+            const prepared = await this.writeCon.prepare(sql);
+            this.bindParams(prepared, params);
+            await prepared.run();
+        });
+    }
+    async executeMultiple(sql) {
+        return this.enqueue('write', async () => {
+            for (const statement of sql.split(';').filter((s) => s.trim())) {
+                await this.writeCon.run(statement);
+            }
+        });
+    }
+    async beginTransaction() {
+        return this.enqueue('write', async () => {
+            await this.writeCon.run('BEGIN TRANSACTION');
+        });
+    }
+    async commit() {
+        return this.enqueue('write', async () => {
+            await this.writeCon.run('COMMIT');
+        });
+    }
+    async rollback() {
+        return this.enqueue('write', async () => {
+            await this.writeCon.run('ROLLBACK');
+        });
+    }
+    async createBulkInserter(table, _columns, _options) {
+        const appender = await this.writeCon.createAppender(table.replace(/"/g, ''));
+        return {
+            append(values) {
+                for (const value of values) {
+                    if (value === null || value === undefined) {
+                        appender.appendNull();
+                    }
+                    else if (typeof value === 'string') {
+                        appender.appendVarchar(value);
+                    }
+                    else if (typeof value === 'number') {
+                        if (Number.isInteger(value)) {
+                            appender.appendInteger(value);
+                        }
+                        else {
+                            appender.appendDouble(value);
+                        }
+                    }
+                    else if (typeof value === 'boolean') {
+                        appender.appendBoolean(value);
+                    }
+                    else if (typeof value === 'bigint') {
+                        appender.appendBigInt(value);
+                    }
+                    else if (value instanceof Uint8Array) {
+                        appender.appendBlob(value);
+                    }
+                    else {
+                        appender.appendVarchar(String(value));
+                    }
+                }
+                appender.endRow();
+            },
+            async flush() {
+                appender.flushSync();
+            },
+            async close() {
+                appender.flushSync();
+                appender.closeSync();
+            },
+        };
+    }
+    /** Enqueue a read or write operation for serialization */
+    enqueue(queue, fn) {
+        if (queue === 'write') {
+            const p = this.writeQueue.then(fn);
+            this.writeQueue = p.then(() => { }, () => { });
+            return p;
+        }
+        else {
+            const p = this.readQueue.then(fn);
+            this.readQueue = p.then(() => { }, () => { });
+            return p;
+        }
+    }
+    bindParams(prepared, params) {
+        for (let i = 0; i < params.length; i++) {
+            const idx = i + 1;
+            const value = params[i];
+            if (value === null || value === undefined) {
+                prepared.bindNull(idx);
+            }
+            else if (typeof value === 'string') {
+                prepared.bindVarchar(idx, value);
+            }
+            else if (typeof value === 'number') {
+                if (Number.isInteger(value)) {
+                    prepared.bindInteger(idx, value);
+                }
+                else {
+                    prepared.bindDouble(idx, value);
+                }
+            }
+            else if (typeof value === 'boolean') {
+                prepared.bindBoolean(idx, value);
+            }
+            else if (typeof value === 'bigint') {
+                prepared.bindBigInt(idx, value);
+            }
+            else if (value instanceof Uint8Array) {
+                prepared.bindBlob(idx, value);
+            }
+            else {
+                prepared.bindVarchar(idx, String(value));
+            }
+        }
+    }
+}

package/dist/database/adapters/sqlite-search.d.ts

@@ -0,0 +1,16 @@
+import type { SearchPort } from '../ports.ts';
+import type { DatabasePort } from '../ports.ts';
+export declare class SQLiteSearchPort implements SearchPort {
+    private port;
+    constructor(port: DatabasePort);
+    indexExists(shadowTable: string): Promise<boolean>;
+    buildIndex(shadowTable: string, sourceQuery: string, searchColumns: string[]): Promise<void>;
+    updateIndex(shadowTable: string, uri: string, row: Record<string, string | null>, searchColumns: string[]): Promise<void>;
+    deleteFromIndex(shadowTable: string, uri: string, searchColumns: string[]): Promise<void>;
+    private _deleteFromFts;
+    search(shadowTable: string, query: string, _searchColumns: string[], limit: number, offset: number): Promise<Array<{
+        uri: string;
+        score: number;
+    }>>;
+}
+//# sourceMappingURL=sqlite-search.d.ts.map

package/dist/database/adapters/sqlite-search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite-search.d.ts","sourceRoot":"","sources":["../../../src/database/adapters/sqlite-search.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAC7C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAY/C,qBAAa,gBAAiB,YAAW,UAAU;IACrC,OAAO,CAAC,IAAI;gBAAJ,IAAI,EAAE,YAAY;IAEhC,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAQlD,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAuB5F,WAAW,CACf,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,EAClC,aAAa,EAAE,MAAM,EAAE,GACtB,OAAO,CAAC,IAAI,CAAC;IA2BV,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;YAKjF,cAAc;IAatB,MAAM,CACV,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,MAAM,EACb,cAAc,EAAE,MAAM,EAAE,EACxB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAWlD"}

package/dist/database/adapters/sqlite-search.js

@@ -0,0 +1,76 @@
+/**
+ * SQLite FTS5-based search port with incremental updates.
+ *
+ * Uses external content FTS5 tables (content=shadowTable) so the FTS index
+ * references the shadow data table. Updates happen incrementally per-record
+ * instead of dropping and rebuilding the entire index.
+ */
+/** Quote an identifier. Lexicon property names are SQL-agnostic (`group`, `order`, `from` are all legal), so every column is quoted. */
+const q = (name) => `"${name.replace(/"/g, '""')}"`;
+export class SQLiteSearchPort {
+    port;
+    constructor(port) {
+        this.port = port;
+    }
+    async indexExists(shadowTable) {
+        const rows = await this.port.query(`SELECT 1 FROM sqlite_master WHERE type='table' AND name IN ($1, $2)`, [
+            shadowTable,
+            `${shadowTable}_fts`,
+        ]);
+        return rows.length >= 2;
+    }
+    async buildIndex(shadowTable, sourceQuery, searchColumns) {
+        await this.port.execute(`DROP TABLE IF EXISTS ${shadowTable}_fts`, []);
+        await this.port.execute(`DROP TABLE IF EXISTS ${shadowTable}`, []);
+        // Create shadow data table from source query
+        await this.port.execute(`CREATE TABLE ${shadowTable} AS ${sourceQuery}`, []);
+        await this.port.execute(`CREATE UNIQUE INDEX IF NOT EXISTS ${shadowTable}_uri ON ${shadowTable}(uri)`, []);
+        // Create FTS5 virtual table with external content pointing to shadow table
+        const colList = searchColumns.map(q).join(', ');
+        await this.port.execute(`CREATE VIRTUAL TABLE ${shadowTable}_fts USING fts5(uri UNINDEXED, ${colList}, content=${shadowTable}, content_rowid=rowid, tokenize='porter unicode61 remove_diacritics 2')`, []);
+        // Populate FTS from shadow table
+        const selectCols = ['uri', ...searchColumns].map((c) => `COALESCE(CAST(${q(c)} AS TEXT), '')`);
+        await this.port.execute(`INSERT INTO ${shadowTable}_fts (uri, ${colList}) SELECT ${selectCols.join(', ')} FROM ${shadowTable}`, []);
+    }
+    async updateIndex(shadowTable, uri, row, searchColumns) {
+        const colList = searchColumns.map(q).join(', ');
+        // Remove old FTS entry if record already indexed
+        await this._deleteFromFts(shadowTable, uri, searchColumns);
+        // Upsert shadow table
+        const placeholders = searchColumns.map((_, i) => `$${i + 2}`);
+        const setClauses = searchColumns.map((c, i) => `${q(c)} = $${i + 2}`);
+        const values = [uri, ...searchColumns.map((c) => row[c] ?? null)];
+        await this.port.execute(`INSERT INTO ${shadowTable} (uri, ${colList}) VALUES ($1, ${placeholders.join(', ')}) ON CONFLICT(uri) DO UPDATE SET ${setClauses.join(', ')}`, values);
+        // Read back rowid and insert new FTS entry
+        const rows = await this.port.query(`SELECT rowid FROM ${shadowTable} WHERE uri = $1`, [uri]);
+        if (rows.length > 0) {
+            const rowid = rows[0].rowid;
+            const ftsPlaceholders = searchColumns.map((_, i) => `$${i + 3}`);
+            await this.port.execute(`INSERT INTO ${shadowTable}_fts(rowid, uri, ${colList}) VALUES($1, $2, ${ftsPlaceholders.join(', ')})`, [rowid, uri, ...searchColumns.map((c) => row[c] ?? '')]);
+        }
+    }
+    async deleteFromIndex(shadowTable, uri, searchColumns) {
+        await this._deleteFromFts(shadowTable, uri, searchColumns);
+        await this.port.execute(`DELETE FROM ${shadowTable} WHERE uri = $1`, [uri]);
+    }
+    async _deleteFromFts(shadowTable, uri, searchColumns) {
+        const colList = searchColumns.map(q).join(', ');
+        const rows = await this.port.query(`SELECT rowid, uri, ${colList} FROM ${shadowTable} WHERE uri = $1`, [uri]);
+        if (rows.length === 0)
+            return;
+        const old = rows[0];
+        const placeholders = searchColumns.map((_, i) => `$${i + 3}`);
+        await this.port.execute(`INSERT INTO ${shadowTable}_fts(${shadowTable}_fts, rowid, uri, ${colList}) VALUES('delete', $1, $2, ${placeholders.join(', ')})`, [old.rowid, uri, ...searchColumns.map((c) => old[c] ?? '')]);
+    }
+    async search(shadowTable, query, _searchColumns, limit, offset) {
+        const escaped = query.replace(/['"*(){}[\]^~\\:.]/g, ' ').trim();
+        if (!escaped)
+            return [];
+        const sql = `SELECT uri, -bm25(${shadowTable}_fts) AS score
+      FROM ${shadowTable}_fts
+      WHERE ${shadowTable}_fts MATCH $1
+      ORDER BY score DESC
+      LIMIT $2 OFFSET $3`;
+        return this.port.query(sql, [escaped, limit, offset]);
+    }
+}