@hatk/hatk 0.0.1-alpha.20 → 0.0.1-alpha.22

package/dist/backfill.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"backfill.d.ts","sourceRoot":"","sources":["../src/backfill.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAEjD,6CAA6C;AAC7C,UAAU,YAAY;IACpB,wFAAwF;IACxF,MAAM,EAAE,MAAM,CAAA;IACd,8FAA8F;IAC9F,MAAM,EAAE,MAAM,CAAA;IACd,yEAAyE;IACzE,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IACxB,wDAAwD;IACxD,MAAM,EAAE,cAAc,CAAA;CACvB;AAuGD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAsJ/G;AAgCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAkIrE"}
+{"version":3,"file":"backfill.d.ts","sourceRoot":"","sources":["../src/backfill.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAEjD,6CAA6C;AAC7C,UAAU,YAAY;IACpB,wFAAwF;IACxF,MAAM,EAAE,MAAM,CAAA;IACd,8FAA8F;IAC9F,MAAM,EAAE,MAAM,CAAA;IACd,yEAAyE;IACzE,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IACxB,wDAAwD;IACxD,MAAM,EAAE,cAAc,CAAA;CACvB;AAoGD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAsJ/G;AA8BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAkIrE"}

package/dist/car.js

@@ -107,7 +107,7 @@ export async function parseCarStream(body) {
         while (len - pos < need) {
             const { done, value } = await reader.read();
             if (done)
-                return (len - pos) >= need;
+                return len - pos >= need;
             byteLength += value.length;
             // Compact: shift remaining data to front when read cursor passes midpoint
             if (pos > 0 && pos > buf.length >>> 1) {

package/dist/cli.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 import { mkdirSync, writeFileSync, existsSync, unlinkSync, readdirSync, readFileSync } from 'node:fs';
-import { resolve, join } from 'node:path';
-import { execSync } from 'node:child_process';
-import { loadLexicons } from "./schema.js";
+import { resolve, join, dirname } from 'node:path';
+import { execSync, spawn } from 'node:child_process';
+import { loadLexicons, discoverCollections, buildSchemas } from "./schema.js";
 import { loadConfig } from "./config.js";
 const args = process.argv.slice(2);
 const command = args[0];
@@ -34,6 +34,31 @@ async function ensurePds() {
     console.error('[dev] PDS failed to start');
     process.exit(1);
 }
+/** Spawn a long-running process and forward SIGINT/SIGTERM for clean shutdown. */
+function spawnForward(cmd, args, env) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(cmd, args, {
+            stdio: 'inherit',
+            cwd: process.cwd(),
+            env: { ...process.env, ...env },
+        });
+        const onSignal = (sig) => {
+            child.kill(sig);
+        };
+        process.on('SIGINT', onSignal);
+        process.on('SIGTERM', onSignal);
+        child.on('close', (code, signal) => {
+            process.removeListener('SIGINT', onSignal);
+            process.removeListener('SIGTERM', onSignal);
+            if (signal === 'SIGINT' || signal === 'SIGTERM')
+                process.exit(0);
+            if (code === 0 || code === null)
+                resolve();
+            else
+                reject(new Error(`Process exited with code ${code}`));
+        });
+    });
+}
 function runSeed() {
     const seedFile = resolve('seeds/seed.ts');
     if (!existsSync(seedFile))
@@ -511,6 +536,14 @@ export default defineConfig({
                         properties: {
                             uri: { type: 'string', format: 'at-uri' },
                             cid: { type: 'string', format: 'cid' },
+                            commit: {
+                                type: 'object',
+                                properties: {
+                                    cid: { type: 'string', format: 'cid' },
+                                    rev: { type: 'string' },
+                                },
+                            },
+                            validationStatus: { type: 'string' },
                         },
                     },
                 },
@@ -566,6 +599,14 @@ export default defineConfig({
                         properties: {
                             uri: { type: 'string', format: 'at-uri' },
                             cid: { type: 'string', format: 'cid' },
+                            commit: {
+                                type: 'object',
+                                properties: {
+                                    cid: { type: 'string', format: 'cid' },
+                                    rev: { type: 'string' },
+                                },
+                            },
+                            validationStatus: { type: 'string' },
                         },
                     },
                 },
@@ -897,7 +938,7 @@ CMD ["node", "--experimental-strip-types", "--max-old-space-size=512", "node_mod
             allowImportingTsExtensions: true,
             resolveJsonModule: true,
         },
-        include: ['feeds', 'xrpc', 'og', 'seeds', 'labels', 'jobs', 'setup', 'hatk.generated.ts'],
+        include: ['feeds', 'xrpc', 'og', 'seeds', 'labels', 'jobs', 'setup', 'hatk.generated.ts', 'hatk.config.ts'],
     }, null, 2) + '\n');
     writeFileSync(join(dir, 'playwright.config.ts'), `import { defineConfig } from '@playwright/test'
 
@@ -1082,6 +1123,43 @@ a {
 </div>
 `);
     }
+    writeFileSync(join(dir, 'AGENTS.md'), `# hatk project
+
+This is an AT Protocol application built with [hatk](https://github.com/hatk-dev/hatk).
+Read the project's lexicons in \`lexicons/\` to understand the data model.
+Types are generated from lexicons into \`hatk.generated.ts\` — never edit this file directly.
+
+## Project structure
+
+| Directory    | Purpose                                              |
+|-------------|------------------------------------------------------|
+| \`lexicons/\`  | AT Protocol lexicon schemas (JSON). Defines collections and XRPC methods |
+| \`feeds/\`     | Feed generators — each file exports a feed via \`defineFeed\` |
+| \`xrpc/\`      | XRPC method handlers — directory nesting maps to NSID segments |
+| \`labels/\`    | Label definitions and rules for moderation            |
+| \`setup/\`     | Boot-time scripts (run before server starts). Prefix with numbers for ordering |
+| \`seeds/\`     | Test data seeding scripts for local development       |
+| \`hooks/\`     | Lifecycle hooks (e.g. \`on-login.ts\`)                  |
+| \`og/\`        | OpenGraph image routes                                |
+| \`jobs/\`      | Periodic background tasks                             |
+| \`test/\`      | Test files (vitest). Run with \`hatk test\`              |
+| \`public/\`    | Static files served at the root                       |
+
+## Key files
+
+- \`hatk.config.ts\` — project configuration (see \`defineConfig\` for type info)
+- \`hatk.generated.ts\` — auto-generated types and typed helpers. Regenerate with \`hatk generate types\`
+
+## Commands
+
+Run \`npx hatk --help\` for the full list of commands.
+
+Use \`npx hatk generate\` to scaffold new feeds, xrpc handlers, labels, and lexicons
+rather than creating files manually. These generate files with the correct imports
+from \`hatk.generated.ts\`.
+
+After modifying lexicons, always run \`npx hatk generate types\` to update the generated types.
+`);
     console.log(`Created ${name}/`);
     console.log(`  hatk.config.ts`);
     console.log(`  lexicons/   — lexicon JSON files (core + your own)`);
@@ -1486,25 +1564,14 @@ else if (command === 'destroy') {
 else if (command === 'dev') {
     await ensurePds();
     runSeed();
-    try {
-        if (existsSync(resolve('svelte.config.js')) && existsSync(resolve('src/app.html'))) {
-            // SvelteKit project — vite dev starts the hatk server via the plugin
-            execSync('npx vite dev', { stdio: 'inherit', cwd: process.cwd() });
-        }
-        else {
-            // No frontend — just run the hatk server directly
-            const mainPath = resolve(import.meta.dirname, 'main.js');
-            execSync(`npx tsx ${mainPath} hatk.config.ts`, {
-                stdio: 'inherit',
-                cwd: process.cwd(),
-                env: { ...process.env, DEV_MODE: '1' },
-            });
-        }
+    if (existsSync(resolve('svelte.config.js')) && existsSync(resolve('src/app.html'))) {
+        // SvelteKit project — vite dev starts the hatk server via the plugin
+        await spawnForward('npx', ['vite', 'dev']);
     }
-    catch (e) {
-        if (e.signal === 'SIGINT' || e.signal === 'SIGTERM')
-            process.exit(0);
-        throw e;
+    else {
+        // No frontend — just run the hatk server directly
+        const mainPath = resolve(import.meta.dirname, 'main.js');
+        await spawnForward('npx', ['tsx', mainPath, 'hatk.config.ts'], { DEV_MODE: '1' });
     }
 }
 else if (command === 'format' || command === 'fmt') {
@@ -1689,10 +1756,19 @@ else if (command === 'schema') {
         console.error('No database file configured (database is :memory:)');
         process.exit(1);
     }
+    // Init DB from lexicons if it doesn't exist yet
     if (!existsSync(config.database)) {
-        console.error(`Database not found: ${config.database}`);
-        console.error('Run "hatk dev" first to create it.');
-        process.exit(1);
+        const configDir = resolve('.');
+        const lexicons = loadLexicons(resolve(configDir, 'lexicons'));
+        const collections = config.collections.length > 0 ? config.collections : discoverCollections(lexicons);
+        if (collections.length === 0) {
+            console.error('No record collections found. Add record lexicons to the lexicons/ directory.');
+            process.exit(1);
+        }
+        mkdirSync(dirname(config.database), { recursive: true });
+        const { initDatabase } = await import("./db.js");
+        const { schemas, ddlStatements } = buildSchemas(lexicons, collections);
+        await initDatabase(config.database, schemas, ddlStatements);
     }
     const { DuckDBInstance } = await import('@duckdb/node-api');
     const instance = await DuckDBInstance.create(config.database);
@@ -1709,15 +1785,8 @@ else if (command === 'schema') {
     }
 }
 else if (command === 'start') {
-    try {
-        const mainPath = resolve(import.meta.dirname, 'main.js');
-        execSync(`npx tsx ${mainPath} hatk.config.ts`, { stdio: 'inherit', cwd: process.cwd() });
-    }
-    catch (e) {
-        if (e.signal === 'SIGINT' || e.signal === 'SIGTERM')
-            process.exit(0);
-        throw e;
-    }
+    const mainPath = resolve(import.meta.dirname, 'main.js');
+    await spawnForward('npx', ['tsx', mainPath, 'hatk.config.ts']);
 }
 else {
     usage();

package/dist/config.d.ts

@@ -41,8 +41,15 @@ export interface HatkConfig {
     oauth: OAuthConfig | null;
     admins: string[];
 }
+/** Input type for defineConfig — fields that have defaults are optional. */
+export type HatkConfigInput = Partial<Omit<HatkConfig, 'oauth' | 'backfill'>> & {
+    oauth?: (Partial<OAuthConfig> & {
+        clients: OAuthClientConfig[];
+    }) | null;
+    backfill?: Partial<BackfillConfig>;
+};
 /** Identity function that provides type inference for hatk config files. */
-export declare function defineConfig(config: Partial<HatkConfig>): Partial<HatkConfig>;
+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): Promise<HatkConfig>;

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAGA,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,4EAA4E;AAC5E,wBAAgB,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC,CAE7E;AAED,yEAAyE;AACzE,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,wBAAsB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAuDxE"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAGA,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,4EAA4E;AAC5E,MAAM,MAAM,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,UAAU,EAAE,OAAO,GAAG,UAAU,CAAC,CAAC,GAAG;IAC9E,KAAK,CAAC,EAAE,CAAC,OAAO,CAAC,WAAW,CAAC,GAAG;QAAE,OAAO,EAAE,iBAAiB,EAAE,CAAA;KAAE,CAAC,GAAG,IAAI,CAAA;IACxE,QAAQ,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,CAAA;CACnC,CAAA;AAED,4EAA4E;AAC5E,wBAAgB,YAAY,CAAC,MAAM,EAAE,eAAe,GAAG,eAAe,CAErE;AAED,yEAAyE;AACzE,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,wBAAsB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAuDxE"}

package/dist/hooks.d.ts

@@ -0,0 +1,15 @@
+/** Context passed to the on-login hook after a successful OAuth login. */
+export type OnLoginCtx = {
+    /** DID of the user who just logged in. */
+    did: string;
+    /** Trigger a backfill for a DID if it hasn't been indexed yet. */
+    ensureRepo: (did: string) => Promise<void>;
+};
+/**
+ * Discover and load the on-login hook from the project's `hooks/` directory.
+ * Looks for `on-login.ts` or `on-login.js`. Safe to call if no hook exists.
+ */
+export declare function loadOnLoginHook(hooksDir: string): Promise<void>;
+/** Fire the on-login hook if loaded. Errors are logged but never block login. */
+export declare function fireOnLoginHook(did: string): Promise<void>;
+//# sourceMappingURL=hooks.d.ts.map

package/dist/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AA2BA,0EAA0E;AAC1E,MAAM,MAAM,UAAU,GAAG;IACvB,0CAA0C;IAC1C,GAAG,EAAE,MAAM,CAAA;IACX,kEAAkE;IAClE,UAAU,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAC3C,CAAA;AAMD;;;GAGG;AACH,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAQrE;AAQD,iFAAiF;AACjF,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAOhE"}

package/dist/hooks.js

@@ -0,0 +1,65 @@
+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;
+};
+/**
+ * Lifecycle hooks that run in response to server events.
+ *
+ * Place hook modules in the `hooks/` directory. Currently supported hooks:
+ *
+ * - `on-login.ts` — called after each successful OAuth login
+ *
+ * Each hook default-exports an async function that receives an event-specific
+ * context object.
+ *
+ * @example
+ * ```ts
+ * // hooks/on-login.ts
+ * import type { OnLoginCtx } from '@hatk/hatk/hooks'
+ *
+ * export default async function (ctx: OnLoginCtx) {
+ *   // Ensure the user's repo is backfilled on first login
+ *   await ctx.ensureRepo(ctx.did)
+ * }
+ * ```
+ */
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { log } from "./logger.js";
+import { setRepoStatus } from "./db.js";
+import { triggerAutoBackfill } from "./indexer.js";
+let onLoginHook = null;
+/**
+ * Discover and load the on-login hook from the project's `hooks/` directory.
+ * Looks for `on-login.ts` or `on-login.js`. Safe to call if no hook exists.
+ */
+export async function loadOnLoginHook(hooksDir) {
+    const tsPath = resolve(hooksDir, 'on-login.ts');
+    const jsPath = resolve(hooksDir, 'on-login.js');
+    const path = existsSync(tsPath) ? tsPath : existsSync(jsPath) ? jsPath : null;
+    if (!path)
+        return;
+    const mod = await import(__rewriteRelativeImportExtension(path));
+    onLoginHook = mod.default;
+    log('[hooks] on-login hook loaded');
+}
+/** Mark a DID as pending and trigger auto-backfill. */
+async function ensureRepo(did) {
+    await setRepoStatus(did, 'pending');
+    triggerAutoBackfill(did);
+}
+/** Fire the on-login hook if loaded. Errors are logged but never block login. */
+export async function fireOnLoginHook(did) {
+    if (!onLoginHook)
+        return;
+    try {
+        await onLoginHook({ did, ensureRepo });
+    }
+    catch (err) {
+        console.error('[hooks] onLogin hook error:', err.message);
+    }
+}

package/dist/indexer.d.ts

@@ -1,4 +1,13 @@
+/**
+ * Auto-backfill a DID's repo when first seen on the firehose.
+ *
+ * Fetches the full repo via CAR export, inserts all records, then replays any
+ * firehose events that arrived during the backfill. Concurrency is capped at
+ * `maxConcurrentBackfills`. Failed backfills retry with exponential delay up
+ * to `maxRetries`.
+ */
 export declare function triggerAutoBackfill(did: string, attempt?: number): Promise<void>;
+/** Configuration for the firehose indexer. */
 interface IndexerOpts {
     relayUrl: string;
     collections: Set<string>;
@@ -10,6 +19,16 @@ interface IndexerOpts {
     parallelism?: number;
     ftsRebuildInterval?: number;
 }
+/**
+ * Connect to the AT Protocol relay firehose and begin indexing.
+ *
+ * Opens a WebSocket to `subscribeRepos`, processes commit messages synchronously
+ * on the event loop to minimize backpressure, and batches writes through
+ * {@link flushBuffer}. New DIDs trigger auto-backfill via {@link triggerAutoBackfill}.
+ * Reconnects automatically on disconnect after a 3s delay.
+ *
+ * @returns The WebSocket connection (for shutdown coordination)
+ */
 export declare function startIndexer(opts: IndexerOpts): Promise<WebSocket>;
 export {};
 //# sourceMappingURL=indexer.d.ts.map

package/dist/indexer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"indexer.d.ts","sourceRoot":"","sources":["../src/indexer.ts"],"names":[],"mappings":"AAmIA,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,SAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAgEjF;AAED,UAAU,WAAW;IACnB,QAAQ,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IACxB,iBAAiB,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IAC/B,WAAW,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IACzB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,YAAY,EAAE,MAAM,CAAA;IACpB,UAAU,EAAE,MAAM,CAAA;IAClB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAC5B;AAyBD,wBAAsB,YAAY,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,CAAC,CAmDxE"}
+{"version":3,"file":"indexer.d.ts","sourceRoot":"","sources":["../src/indexer.ts"],"names":[],"mappings":"AA2IA;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,SAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAgEjF;AAED,8CAA8C;AAC9C,UAAU,WAAW;IACnB,QAAQ,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IACxB,iBAAiB,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IAC/B,WAAW,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IACzB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,YAAY,EAAE,MAAM,CAAA;IACpB,UAAU,EAAE,MAAM,CAAA;IAClB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAC5B;AAyBD;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,CAAC,CAmDxE"}

package/dist/indexer.js

@@ -28,6 +28,11 @@ let indexerPinnedRepos = null;
 let indexerFetchTimeout;
 let indexerMaxRetries;
 let maxConcurrentBackfills = 3;
+/**
+ * Flush the write buffer — insert all buffered records, update the relay cursor,
+ * run label rules on inserted records, and trigger FTS rebuilds when the write
+ * threshold is reached. Emits a wide event with batch stats.
+ */
 async function flushBuffer() {
     if (buffer.length === 0)
         return;
@@ -90,6 +95,7 @@ async function flushBuffer() {
         rebuildAllIndexes([...indexerCollections]).catch(() => { });
     }
 }
+/** Schedule a flush after FLUSH_INTERVAL_MS if one isn't already pending. */
 function scheduleFlush() {
     if (flushTimer)
         return;
@@ -98,6 +104,7 @@ function scheduleFlush() {
         await flushBuffer();
     }, FLUSH_INTERVAL_MS);
 }
+/** Add a record to the write buffer. Flushes immediately if BATCH_SIZE is reached. */
 function bufferWrite(item) {
     buffer.push(item);
     if (buffer.length >= BATCH_SIZE) {
@@ -111,6 +118,14 @@ function bufferWrite(item) {
         scheduleFlush();
     }
 }
+/**
+ * Auto-backfill a DID's repo when first seen on the firehose.
+ *
+ * Fetches the full repo via CAR export, inserts all records, then replays any
+ * firehose events that arrived during the backfill. Concurrency is capped at
+ * `maxConcurrentBackfills`. Failed backfills retry with exponential delay up
+ * to `maxRetries`.
+ */
 export async function triggerAutoBackfill(did, attempt = 0) {
     if (backfillInFlight.has(did))
         return;
@@ -173,7 +188,7 @@ export async function triggerAutoBackfill(did, attempt = 0) {
         }, delayMs);
     }
 }
-// Periodic memory diagnostics
+/** Emit a memory diagnostics wide event every 30s for observability. */
 function startMemoryDiagnostics() {
     setInterval(() => {
         const mem = process.memoryUsage();
@@ -195,6 +210,16 @@ function startMemoryDiagnostics() {
         });
     }, 30_000);
 }
+/**
+ * Connect to the AT Protocol relay firehose and begin indexing.
+ *
+ * Opens a WebSocket to `subscribeRepos`, processes commit messages synchronously
+ * on the event loop to minimize backpressure, and batches writes through
+ * {@link flushBuffer}. New DIDs trigger auto-backfill via {@link triggerAutoBackfill}.
+ * Reconnects automatically on disconnect after a 3s delay.
+ *
+ * @returns The WebSocket connection (for shutdown coordination)
+ */
 export async function startIndexer(opts) {
     const { relayUrl, collections, cursor, fetchTimeout } = opts;
     if (opts.ftsRebuildInterval != null)
@@ -243,6 +268,11 @@ export async function startIndexer(opts) {
     });
     return ws;
 }
+/**
+ * Process a single firehose message. Decodes the CBOR header/body, filters
+ * for relevant collections, validates records against lexicons, and routes
+ * writes to the buffer (or pending buffer if the DID is mid-backfill).
+ */
 function processMessage(bytes, collections) {
     const header = cborDecode(bytes, 0);
     const body = cborDecode(bytes, header.offset);

package/dist/labels.d.ts

@@ -13,7 +13,20 @@ export interface LabelRuleContext {
         value: Record<string, any>;
     };
 }
+/**
+ * Discover and load label rule modules from the `labels/` directory.
+ *
+ * Each module should default-export an object with an optional `definition`
+ * (label metadata like severity and blur behavior) and an optional `evaluate`
+ * function that returns label values to apply to a record.
+ *
+ * @param labelsDir - Absolute path to the `labels/` directory
+ */
 export declare function initLabels(labelsDir: string): Promise<void>;
+/**
+ * Evaluate all loaded label rules against a record and persist any resulting labels.
+ * Called after each record is indexed. Rule errors are logged but never block indexing.
+ */
 export declare function runLabelRules(record: {
     uri: string;
     cid: string;
@@ -21,9 +34,16 @@ export declare function runLabelRules(record: {
     collection: string;
     value: Record<string, any>;
 }): Promise<void>;
+/**
+ * Re-evaluate all label rules against every existing record in the given collections.
+ * Used by `/admin/rescan-labels` to apply new or updated rules retroactively.
+ *
+ * @returns Count of records scanned and new labels applied
+ */
 export declare function rescanLabels(collections: string[]): Promise<{
     scanned: number;
     labeled: number;
 }>;
+/** Return all label definitions discovered during {@link initLabels}. */
 export declare function getLabelDefinitions(): LabelDefinition[];
 //# sourceMappingURL=labels.d.ts.map

package/dist/labels.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"labels.d.ts","sourceRoot":"","sources":["../src/labels.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAIlD,wDAAwD;AACxD,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE;QACF,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,EAAE,CAAC,CAAA;QACtD,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;KACtD,CAAA;IACD,MAAM,EAAE;QACN,GAAG,EAAE,MAAM,CAAA;QACX,GAAG,EAAE,MAAM,CAAA;QACX,GAAG,EAAE,MAAM,CAAA;QACX,UAAU,EAAE,MAAM,CAAA;QAClB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;KAC3B,CAAA;CACF;AAWD,wBAAsB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAmCjE;AAED,wBAAsB,aAAa,CAAC,MAAM,EAAE;IAC1C,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CAC3B,GAAG,OAAO,CAAC,IAAI,CAAC,CAyBhB;AAED,wBAAsB,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAuCvG;AAED,wBAAgB,mBAAmB,IAAI,eAAe,EAAE,CAEvD"}
+{"version":3,"file":"labels.d.ts","sourceRoot":"","sources":["../src/labels.ts"],"names":[],"mappings":"AA8BA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAIlD,wDAAwD;AACxD,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE;QACF,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,EAAE,CAAC,CAAA;QACtD,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;KACtD,CAAA;IACD,MAAM,EAAE;QACN,GAAG,EAAE,MAAM,CAAA;QACX,GAAG,EAAE,MAAM,CAAA;QACX,GAAG,EAAE,MAAM,CAAA;QACX,UAAU,EAAE,MAAM,CAAA;QAClB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;KAC3B,CAAA;CACF;AAYD;;;;;;;;GAQG;AACH,wBAAsB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAmCjE;AAED;;;GAGG;AACH,wBAAsB,aAAa,CAAC,MAAM,EAAE;IAC1C,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CAC3B,GAAG,OAAO,CAAC,IAAI,CAAC,CAyBhB;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAuCvG;AAED,yEAAyE;AACzE,wBAAgB,mBAAmB,IAAI,eAAe,EAAE,CAEvD"}

package/dist/labels.js

@@ -6,6 +6,34 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     }
     return path;
 };
+/**
+ * Label system for applying moderation labels to records as they are indexed.
+ *
+ * Place label modules in the `labels/` directory. Each module default-exports
+ * an object with a `definition` (label metadata) and/or an `evaluate` function
+ * (rule that returns label values for a given record).
+ *
+ * @example
+ * ```ts
+ * // labels/nsfw.ts
+ * import type { LabelRuleContext } from '@hatk/hatk/labels'
+ *
+ * export default {
+ *   definition: {
+ *     identifier: 'nsfw',
+ *     severity: 'alert',
+ *     blurs: 'media',
+ *     defaultSetting: 'warn',
+ *     locales: [{ lang: 'en', name: 'NSFW', description: 'Not safe for work' }],
+ *   },
+ *
+ *   async evaluate(ctx: LabelRuleContext): Promise<string[]> {
+ *     if (ctx.record.value.nsfw === true) return ['nsfw']
+ *     return []
+ *   },
+ * }
+ * ```
+ */
 import { resolve } from 'node:path';
 import { readdirSync } from 'node:fs';
 import { querySQL, runSQL, insertLabels, getSchema } from "./db.js";
@@ -13,6 +41,15 @@ import { log, emit } from "./logger.js";
 const rules = [];
 let labelDefs = [];
 let labelSrc = 'self';
+/**
+ * Discover and load label rule modules from the `labels/` directory.
+ *
+ * Each module should default-export an object with an optional `definition`
+ * (label metadata like severity and blur behavior) and an optional `evaluate`
+ * function that returns label values to apply to a record.
+ *
+ * @param labelsDir - Absolute path to the `labels/` directory
+ */
 export async function initLabels(labelsDir) {
     let files;
     try {
@@ -45,6 +82,10 @@ export async function initLabels(labelsDir) {
         log(`[labels] ${labelDefs.length} label definitions loaded`);
     }
 }
+/**
+ * Evaluate all loaded label rules against a record and persist any resulting labels.
+ * Called after each record is indexed. Rule errors are logged but never block indexing.
+ */
 export async function runLabelRules(record) {
     if (rules.length === 0)
         return;
@@ -69,6 +110,12 @@ export async function runLabelRules(record) {
         emit('labels', 'applied', { count: allLabels.length, uri: record.uri, vals: allLabels.map((l) => l.val) });
     }
 }
+/**
+ * Re-evaluate all label rules against every existing record in the given collections.
+ * Used by `/admin/rescan-labels` to apply new or updated rules retroactively.
+ *
+ * @returns Count of records scanned and new labels applied
+ */
 export async function rescanLabels(collections) {
     const beforeRows = await querySQL(`SELECT COUNT(*) as count FROM _labels`);
     const beforeCount = Number(beforeRows[0]?.count || 0);
@@ -106,6 +153,7 @@ export async function rescanLabels(collections) {
     const afterCount = Number(afterRows[0]?.count || 0);
     return { scanned, labeled: afterCount - beforeCount };
 }
+/** Return all label definitions discovered during {@link initLabels}. */
 export function getLabelDefinitions() {
     return labelDefs;
 }

package/dist/logger.d.ts

@@ -1,4 +1,33 @@
+/**
+ * Unstructured debug log — use sparingly for human-readable dev output.
+ * Prefer {@link emit} for anything that should be queryable in production.
+ * Disabled when `DEBUG=0`.
+ */
 export declare function log(...args: unknown[]): void;
+/**
+ * Emit a structured wide event as a single JSON line to stdout.
+ *
+ * Each call produces one canonical log line with a timestamp, module, operation,
+ * and arbitrary key-value fields — designed for columnar search and aggregation,
+ * not string grep. Pack as much context as possible into `fields` (request IDs,
+ * durations, status codes, user DIDs, counts) so a single event tells the full
+ * story. See https://loggingsucks.com for the philosophy behind this approach.
+ *
+ * Disabled when `DEBUG=0`.
+ *
+ * @param module - Subsystem emitting the event (e.g. "server", "indexer", "backfill")
+ * @param op - Operation name (e.g. "request", "commit", "memory")
+ * @param fields - High-cardinality key-value context — include everything relevant
+ */
 export declare function emit(module: string, op: string, fields: Record<string, unknown>): void;
+/**
+ * Start a millisecond timer. Call the returned function to get elapsed ms.
+ * Use with {@link emit} to add `duration_ms` to wide events.
+ *
+ * @example
+ * const elapsed = timer()
+ * await doWork()
+ * emit('server', 'request', { path, status_code, duration_ms: elapsed() })
+ */
 export declare function timer(): () => number;
 //# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA,wBAAgB,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAG5C;AAED,wBAAgB,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAWtF;AAED,wBAAgB,KAAK,IAAI,MAAM,MAAM,CAGpC"}
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAG5C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAWtF;AAED;;;;;;;;GAQG;AACH,wBAAgB,KAAK,IAAI,MAAM,MAAM,CAGpC"}

package/dist/logger.js

@@ -1,8 +1,28 @@
+/**
+ * Unstructured debug log — use sparingly for human-readable dev output.
+ * Prefer {@link emit} for anything that should be queryable in production.
+ * Disabled when `DEBUG=0`.
+ */
 export function log(...args) {
     if (process.env.DEBUG === '0')
         return;
     console.log(...args);
 }
+/**
+ * Emit a structured wide event as a single JSON line to stdout.
+ *
+ * Each call produces one canonical log line with a timestamp, module, operation,
+ * and arbitrary key-value fields — designed for columnar search and aggregation,
+ * not string grep. Pack as much context as possible into `fields` (request IDs,
+ * durations, status codes, user DIDs, counts) so a single event tells the full
+ * story. See https://loggingsucks.com for the philosophy behind this approach.
+ *
+ * Disabled when `DEBUG=0`.
+ *
+ * @param module - Subsystem emitting the event (e.g. "server", "indexer", "backfill")
+ * @param op - Operation name (e.g. "request", "commit", "memory")
+ * @param fields - High-cardinality key-value context — include everything relevant
+ */
 export function emit(module, op, fields) {
     if (process.env.DEBUG === '0')
         return;
@@ -17,6 +37,15 @@ export function emit(module, op, fields) {
     }
     process.stdout.write(JSON.stringify(entry) + '\n');
 }
+/**
+ * Start a millisecond timer. Call the returned function to get elapsed ms.
+ * Use with {@link emit} to add `duration_ms` to wide events.
+ *
+ * @example
+ * const elapsed = timer()
+ * await doWork()
+ * emit('server', 'request', { path, status_code, duration_ms: elapsed() })
+ */
 export function timer() {
     const start = performance.now();
     return () => Math.round(performance.now() - start);