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

package/dist/main.js

@@ -3,7 +3,7 @@ import { mkdirSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { log } from "./logger.js";
 import { loadConfig } from "./config.js";
-import { loadLexicons, storeLexicons, discoverCollections, generateTableSchema, generateCreateTableSQL, } from "./schema.js";
+import { loadLexicons, storeLexicons, discoverCollections, buildSchemas, } from "./schema.js";
 import { discoverViews } from "./views.js";
 import { initDatabase, getCursor, querySQL } from "./db.js";
 import { initFeeds, listFeeds } from "./feeds.js";
@@ -17,7 +17,7 @@ import { validateLexicons } from '@bigmoves/lexicon';
 import { relayHttpUrl } from "./config.js";
 import { runBackfill } from "./backfill.js";
 import { initOAuth } from "./oauth/server.js";
-import { loadOnLoginHook } from "./oauth/hooks.js";
+import { loadOnLoginHook } from "./hooks.js";
 import { initSetup } from "./setup.js";
 function logMemory(phase) {
     const mem = process.memoryUsage();
@@ -50,29 +50,14 @@ log(`[main] Loaded config: ${collections.length} collections`);
 // Discover view defs from lexicons
 discoverViews();
 await loadOnLoginHook(resolve(configDir, 'hooks'));
-const schemas = [];
-const ddlStatements = [];
-for (const nsid of collections) {
-    const lexicon = lexicons.get(nsid);
-    if (!lexicon) {
-        log(`[main] No lexicon found for ${nsid}, using generic JSON storage`);
-        const genericDDL = `CREATE TABLE IF NOT EXISTS "${nsid}" (
-      uri TEXT PRIMARY KEY,
-      cid TEXT,
-      did TEXT NOT NULL,
-      indexed_at TIMESTAMP NOT NULL,
-      data JSON
-    );
-    CREATE INDEX IF NOT EXISTS idx_${nsid.replace(/\./g, '_')}_indexed ON "${nsid}"(indexed_at DESC);
-    CREATE INDEX IF NOT EXISTS idx_${nsid.replace(/\./g, '_')}_author ON "${nsid}"(did);`;
-        schemas.push({ collection: nsid, tableName: `"${nsid}"`, columns: [], refColumns: [], children: [], unions: [] });
-        ddlStatements.push(genericDDL);
-        continue;
+const { schemas, ddlStatements } = buildSchemas(lexicons, collections);
+for (const s of schemas) {
+    if (s.columns.length === 0) {
+        log(`[main] No lexicon found for ${s.collection}, using generic JSON storage`);
+    }
+    else {
+        log(`[main] Schema for ${s.collection}: ${s.columns.length} columns, ${s.unions.length} unions`);
     }
-    const schema = generateTableSchema(nsid, lexicon, lexicons);
-    schemas.push(schema);
-    ddlStatements.push(generateCreateTableSQL(schema));
-    log(`[main] Schema for ${nsid}: ${schema.columns.length} columns, ${schema.unions.length} unions`);
 }
 // 3. Ensure data directory exists and initialize DuckDB
 if (config.database !== ':memory:') {

package/dist/mst.d.ts

@@ -1,7 +1,22 @@
+/** A single entry from a Merkle Search Tree — a record path paired with its content CID. */
 export interface MstEntry {
+    /** Record path, e.g. "xyz.marketplace.listing/3mfniulnr7c2g" */
     path: string;
+    /** CID of the record's CBOR block */
     cid: string;
 }
+/**
+ * Walk an AT Protocol Merkle Search Tree (MST) in key order, yielding every record entry.
+ *
+ * The MST is a prefix-compressed B+ tree used by AT Protocol repositories to map
+ * record paths to CIDs. Each node contains a left subtree pointer, an array of entries
+ * (each with a prefix length, key suffix, value CID, and right subtree pointer), and
+ * keys are reconstructed by combining the prefix of the previous key with the suffix.
+ *
+ * @param blocks - Block store that resolves CIDs to raw CBOR bytes
+ * @param rootCid - CID of the MST root node
+ * @yields {MstEntry} Record entries in lexicographic key order
+ */
 export declare function walkMst(blocks: {
     get(cid: string): Uint8Array | undefined;
 }, rootCid: string): Generator<MstEntry>;

package/dist/mst.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mst.d.ts","sourceRoot":"","sources":["../src/mst.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;CACZ;AAED,wBAAiB,OAAO,CAAC,MAAM,EAAE;IAAE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAAA;CAAE,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC,QAAQ,CAAC,CA8BnH"}
+{"version":3,"file":"mst.d.ts","sourceRoot":"","sources":["../src/mst.ts"],"names":[],"mappings":"AAEA,4FAA4F;AAC5F,MAAM,WAAW,QAAQ;IACvB,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAA;IACZ,qCAAqC;IACrC,GAAG,EAAE,MAAM,CAAA;CACZ;AAED;;;;;;;;;;;GAWG;AACH,wBAAiB,OAAO,CAAC,MAAM,EAAE;IAAE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAAA;CAAE,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC,QAAQ,CAAC,CA+BnH"}

package/dist/mst.js

@@ -1,5 +1,18 @@
 import { cborDecode } from "./cbor.js";
+/**
+ * Walk an AT Protocol Merkle Search Tree (MST) in key order, yielding every record entry.
+ *
+ * The MST is a prefix-compressed B+ tree used by AT Protocol repositories to map
+ * record paths to CIDs. Each node contains a left subtree pointer, an array of entries
+ * (each with a prefix length, key suffix, value CID, and right subtree pointer), and
+ * keys are reconstructed by combining the prefix of the previous key with the suffix.
+ *
+ * @param blocks - Block store that resolves CIDs to raw CBOR bytes
+ * @param rootCid - CID of the MST root node
+ * @yields {MstEntry} Record entries in lexicographic key order
+ */
 export function* walkMst(blocks, rootCid) {
+    /** Recursively visit an MST node, reconstructing full keys from prefix-compressed entries. */
     function* visit(cid, prefix) {
         const data = blocks.get(cid);
         if (!data)

package/dist/oauth/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/oauth/server.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AA0E/C,wBAAsB,SAAS,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAmBrG;AAID,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW;;;;;;;;;;;;;;;;;;;EAqBxE;AAED,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW;;;;;EAO/E;AAED,wBAAgB,OAAO;;;;;;;;;;;;;;;;;;;;;;EAWtB;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW;;;;;;;;;EAcpE;AAID,wBAAsB,SAAS,CAC7B,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,CAuItD;AAID,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,GAAG,GAAG,MAAM,CAShF;AAID,wBAAsB,cAAc,CAClC,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,GAAG,IAAI,EACpB,GAAG,EAAE,MAAM,GAAG,IAAI,GACjB,OAAO,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,iBAAiB,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC,CAyHxF;AAID,wBAAsB,WAAW,CAC/B,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,GAAG,CAAC,CAUd;AA0JD,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACtF,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CAmEpF;AAID,wBAAsB,YAAY,CAChC,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,GACV,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CA0BjC"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/oauth/server.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AA0E/C,wBAAsB,SAAS,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAmBrG;AAID,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW;;;;;;;;;;;;;;;;;;;EAqBxE;AAED,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW;;;;;EAO/E;AAED,wBAAgB,OAAO;;;;;;;;;;;;;;;;;;;;;;EAWtB;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW;;;;;;;;;EAcpE;AAID,wBAAsB,SAAS,CAC7B,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,CA2ItD;AAID,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,GAAG,GAAG,MAAM,CAShF;AAID,wBAAsB,cAAc,CAClC,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,GAAG,IAAI,EACpB,GAAG,EAAE,MAAM,GAAG,IAAI,GACjB,OAAO,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,iBAAiB,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC,CAyHxF;AAID,wBAAsB,WAAW,CAC/B,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,GAAG,CAAC,CAUd;AA0JD,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACtF,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CAmEpF;AAID,wBAAsB,YAAY,CAChC,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,GACV,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CA0BjC"}

package/dist/oauth/server.js

@@ -6,7 +6,7 @@ import { discoverAuthServer, resolveHandle } from "./discovery.js";
 import { getServerKey, storeServerKey, storeOAuthRequest, getOAuthRequest, deleteOAuthRequest, storeAuthCode, consumeAuthCode, storeSession, checkAndStoreDpopJti, cleanupExpiredOAuth, storeRefreshToken, getRefreshToken, revokeRefreshToken, } from "./db.js";
 import { emit } from "../logger.js";
 import { querySQL } from "../db.js";
-import { fireOnLoginHook } from "./hooks.js";
+import { fireOnLoginHook } from "../hooks.js";
 const SERVER_KEY_KID = 'appview-oauth-key';
 async function resolveHandleForDid(did) {
     const rows = (await querySQL('SELECT handle FROM _repos WHERE did = $1', [did]));
@@ -146,7 +146,12 @@ export async function handlePar(config, body, dpopHeader, requestUrl) {
     // Resolve DID from login_hint
     let did = body.login_hint;
     if (did && !did.startsWith('did:')) {
-        did = await resolveHandle(did, _relayUrl);
+        try {
+            did = await resolveHandle(did, _relayUrl);
+        }
+        catch {
+            throw new Error('Handle not found');
+        }
     }
     // Discover user's PDS auth server
     let pdsRequestUri;

package/dist/schema.d.ts

@@ -48,4 +48,12 @@ export declare function getAllLexicons(): Array<{
 export declare function getLexiconArray(): any[];
 export declare function generateTableSchema(nsid: string, lexicon: any, lexicons?: Map<string, any>): TableSchema;
 export declare function generateCreateTableSQL(schema: TableSchema): string;
+/**
+ * Build table schemas and DDL from lexicons and collections.
+ * Shared by main.ts (server boot) and cli.ts (hatk schema command).
+ */
+export declare function buildSchemas(lexicons: Map<string, any>, collections: string[]): {
+    schemas: TableSchema[];
+    ddlStatements: string[];
+};
 //# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,YAAY,EAAE,MAAM,CAAA;IACpB,UAAU,EAAE,MAAM,CAAA;IAClB,OAAO,EAAE,OAAO,CAAA;IAChB,KAAK,EAAE,OAAO,CAAA;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,SAAS,EAAE,CAAA;IACpB,OAAO,EAAE,OAAO,CAAA;IAChB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,iBAAiB,EAAE,CAAA;CAC9B;AAED,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,SAAS,EAAE,CAAA;IACpB,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB,QAAQ,EAAE,gBAAgB,EAAE,CAAA;IAC5B,MAAM,EAAE,gBAAgB,EAAE,CAAA;CAC3B;AAED,MAAM,WAAW,gBAAgB;IAC/B,gBAAgB,EAAE,MAAM,CAAA;IACxB,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,SAAS,EAAE,CAAA;CACrB;AAGD,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE/C;AA8CD,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,CASlE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,EAAE,CASxE;AAID,wBAAgB,aAAa,CAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAI9D;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,GAAG,SAAS,CAExD;AAED,wBAAgB,cAAc,IAAI,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,GAAG,CAAA;CAAE,CAAC,CAEtE;AAED,iFAAiF;AACjF,wBAAgB,eAAe,IAAI,GAAG,EAAE,CAEvC;AAuHD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,WAAW,CA0GxG;AAGD,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAoElE"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,YAAY,EAAE,MAAM,CAAA;IACpB,UAAU,EAAE,MAAM,CAAA;IAClB,OAAO,EAAE,OAAO,CAAA;IAChB,KAAK,EAAE,OAAO,CAAA;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,SAAS,EAAE,CAAA;IACpB,OAAO,EAAE,OAAO,CAAA;IAChB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,iBAAiB,EAAE,CAAA;CAC9B;AAED,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,SAAS,EAAE,CAAA;IACpB,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB,QAAQ,EAAE,gBAAgB,EAAE,CAAA;IAC5B,MAAM,EAAE,gBAAgB,EAAE,CAAA;CAC3B;AAED,MAAM,WAAW,gBAAgB;IAC/B,gBAAgB,EAAE,MAAM,CAAA;IACxB,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,SAAS,EAAE,CAAA;CACrB;AAGD,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE/C;AA8CD,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,CASlE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,EAAE,CASxE;AAID,wBAAgB,aAAa,CAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAI9D;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,GAAG,SAAS,CAExD;AAED,wBAAgB,cAAc,IAAI,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,GAAG,CAAA;CAAE,CAAC,CAEtE;AAED,iFAAiF;AACjF,wBAAgB,eAAe,IAAI,GAAG,EAAE,CAEvC;AAuHD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,WAAW,CA0GxG;AAGD,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAoElE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,EAC1B,WAAW,EAAE,MAAM,EAAE,GACpB;IAAE,OAAO,EAAE,WAAW,EAAE,CAAC;IAAC,aAAa,EAAE,MAAM,EAAE,CAAA;CAAE,CA2BrD"}

package/dist/schema.js

@@ -356,3 +356,32 @@ export function generateCreateTableSQL(schema) {
     }
     return [createTable, ...indexes, ...childDDL].join('\n');
 }
+/**
+ * Build table schemas and DDL from lexicons and collections.
+ * Shared by main.ts (server boot) and cli.ts (hatk schema command).
+ */
+export function buildSchemas(lexicons, collections) {
+    const schemas = [];
+    const ddlStatements = [];
+    for (const nsid of collections) {
+        const lexicon = lexicons.get(nsid);
+        if (!lexicon) {
+            const genericDDL = `CREATE TABLE IF NOT EXISTS "${nsid}" (
+      uri TEXT PRIMARY KEY,
+      cid TEXT,
+      did TEXT NOT NULL,
+      indexed_at TIMESTAMP NOT NULL,
+      data JSON
+    );
+    CREATE INDEX IF NOT EXISTS idx_${nsid.replace(/\./g, '_')}_indexed ON "${nsid}"(indexed_at DESC);
+    CREATE INDEX IF NOT EXISTS idx_${nsid.replace(/\./g, '_')}_author ON "${nsid}"(did);`;
+            schemas.push({ collection: nsid, tableName: `"${nsid}"`, columns: [], refColumns: [], children: [], unions: [] });
+            ddlStatements.push(genericDDL);
+            continue;
+        }
+        const schema = generateTableSchema(nsid, lexicon, lexicons);
+        schemas.push(schema);
+        ddlStatements.push(generateCreateTableSQL(schema));
+    }
+    return { schemas, ddlStatements };
+}

package/dist/seed.d.ts

@@ -1,8 +1,10 @@
+/** Authenticated PDS session — returned by {@link seed.createAccount}. */
 export type Session = {
     did: string;
     accessJwt: string;
     handle: string;
 };
+/** AT Protocol blob reference, as returned by `com.atproto.repo.uploadBlob`. */
 export type BlobRef = {
     $type: 'blob';
     ref: {
@@ -11,11 +13,23 @@ export type BlobRef = {
     mimeType: string;
     size: number;
 };
+/** Options for the seed helper. All fields fall back to env vars or sensible defaults. */
 export type SeedOpts = {
     pds?: string;
     password?: string;
     lexicons?: string;
 };
+/**
+ * Create a seed helper for populating a local PDS with test data.
+ *
+ * Returns `createAccount`, `createRecord`, and `uploadBlob` functions bound to
+ * the target PDS. Records are validated against the project's lexicons before
+ * being written. Generic parameter `R` maps collection NSIDs to their record types
+ * for type-safe seeding.
+ *
+ * @typeParam R - Map of collection NSID → record type (defaults to untyped)
+ * @param opts - PDS URL, password, and lexicon directory overrides
+ */
 export declare function seed<R extends Record<string, unknown> = Record<string, unknown>>(opts?: SeedOpts): {
     createAccount: (handle: string) => Promise<Session>;
     createRecord: <K extends keyof R & string>(session: Session, collection: K, record: R[K] extends Record<string, unknown> ? R[K] : Record<string, unknown>, opts: {
@@ -23,6 +37,11 @@ export declare function seed<R extends Record<string, unknown> = Record<string,
     }) => Promise<{
         uri: string;
         cid: string;
+        commit: {
+            cid: string;
+            rev: string;
+        };
+        validationStatus: string;
     }>;
     uploadBlob: (session: Session, filePath: string) => Promise<BlobRef>;
 };

package/dist/seed.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"seed.d.ts","sourceRoot":"","sources":["../src/seed.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,OAAO,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AACxE,MAAM,MAAM,OAAO,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAA;AAC/F,MAAM,MAAM,QAAQ,GAAG;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AAE7E,wBAAgB,IAAI,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,EAAE,QAAQ;4BAM1D,MAAM,KAAG,OAAO,CAAC,OAAO,CAAC;mBA4BlC,CAAC,SAAS,MAAM,CAAC,GAAG,MAAM,WAC3C,OAAO,cACJ,CAAC,UACL,CAAC,CAAC,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,QACvE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,KACrB,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;0BA4BL,OAAO,YAAY,MAAM,KAAG,OAAO,CAAC,OAAO,CAAC;EA4BhF"}
+{"version":3,"file":"seed.d.ts","sourceRoot":"","sources":["../src/seed.ts"],"names":[],"mappings":"AA8BA,0EAA0E;AAC1E,MAAM,MAAM,OAAO,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAExE,gFAAgF;AAChF,MAAM,MAAM,OAAO,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAA;AAE/F,0FAA0F;AAC1F,MAAM,MAAM,QAAQ,GAAG;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AAE7E;;;;;;;;;;GAUG;AACH,wBAAgB,IAAI,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,EAAE,QAAQ;4BAO1D,MAAM,KAAG,OAAO,CAAC,OAAO,CAAC;mBA6BlC,CAAC,SAAS,MAAM,CAAC,GAAG,MAAM,WAC3C,OAAO,cACJ,CAAC,UACL,CAAC,CAAC,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,QACvE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,KACrB,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE;YAAE,GAAG,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,CAAA;SAAE,CAAC;QAAC,gBAAgB,EAAE,MAAM,CAAA;KAAE,CAAC;0BAkCrE,OAAO,YAAY,MAAM,KAAG,OAAO,CAAC,OAAO,CAAC;EA4BhF"}

package/dist/seed.js

@@ -1,12 +1,49 @@
+/**
+ * Test data seeding helpers for populating a local PDS.
+ *
+ * Place a seed script at `seeds/seed.ts`. It runs during `hatk dev` to create
+ * accounts and records against your local PDS. Records are validated against
+ * your project's lexicons before being written.
+ *
+ * @example
+ * ```ts
+ * // seeds/seed.ts
+ * import { seed } from '../hatk.generated.ts'
+ *
+ * const { createAccount, createRecord } = seed()
+ *
+ * const alice = await createAccount('alice.test')
+ * const bob = await createAccount('bob.test')
+ *
+ * await createRecord(
+ *   alice,
+ *   'xyz.statusphere.status',
+ *   { status: '👍', createdAt: new Date().toISOString() },
+ *   { rkey: 'status1' },
+ * )
+ * ```
+ */
 import { loadLexicons } from "./schema.js";
 import { validateRecord } from '@bigmoves/lexicon';
 import { resolve } from 'node:path';
 import { readFileSync } from 'node:fs';
+/**
+ * Create a seed helper for populating a local PDS with test data.
+ *
+ * Returns `createAccount`, `createRecord`, and `uploadBlob` functions bound to
+ * the target PDS. Records are validated against the project's lexicons before
+ * being written. Generic parameter `R` maps collection NSIDs to their record types
+ * for type-safe seeding.
+ *
+ * @typeParam R - Map of collection NSID → record type (defaults to untyped)
+ * @param opts - PDS URL, password, and lexicon directory overrides
+ */
 export function seed(opts) {
     const pdsUrl = opts?.pds || process.env.PDS_URL || 'http://localhost:2583';
     const password = opts?.password || process.env.SEED_PASSWORD || 'password';
     const lexiconsDir = resolve(opts?.lexicons || 'lexicons');
     const lexiconArray = [...loadLexicons(lexiconsDir).values()];
+    /** Create a PDS account (or reuse an existing one) and return an authenticated session. */
     async function createAccount(handle) {
         const res = await fetch(`${pdsUrl}/xrpc/com.atproto.server.createAccount`, {
             method: 'POST',
@@ -34,6 +71,7 @@ export function seed(opts) {
         const session = (await sessionRes.json());
         return { ...session, handle };
     }
+    /** Validate a record against its lexicon and write it to the PDS via `putRecord`. */
     async function createRecord(session, collection, record, opts) {
         const error = validateRecord(lexiconArray, collection, record);
         if (error) {
@@ -53,10 +91,11 @@ export function seed(opts) {
         if (!res.ok) {
             throw new Error(`[seed] [${session.handle}] failed to create ${collection}: ${await res.text()}`);
         }
-        const { uri, cid } = (await res.json());
-        console.log(`[seed] [${session.handle}] ${collection} → ${uri}`);
-        return { uri, cid };
+        const result = (await res.json());
+        console.log(`[seed] [${session.handle}] ${collection} → ${result.uri}`);
+        return result;
     }
+    /** Upload a file to the PDS as a blob. MIME type is inferred from the file extension. */
     async function uploadBlob(session, filePath) {
         const data = readFileSync(resolve(filePath));
         const ext = filePath.split('.').pop()?.toLowerCase() || '';

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,MAAM,EAAE,KAAK,eAAe,EAAE,MAAM,WAAW,CAAA;AAmD3E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AA2B9C,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EAAE,EACrB,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,KAAK,EAAE,WAAW,GAAG,IAAI,EACzB,MAAM,GAAE,MAAM,EAAO,EACrB,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,EAChE,QAAQ,CAAC,EAAE,MAAM,IAAI,GACpB,MAAM,CA28BR"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,MAAM,EAAE,KAAK,eAAe,EAAE,MAAM,WAAW,CAAA;AAmD3E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AA2B9C,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EAAE,EACrB,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,KAAK,EAAE,WAAW,GAAG,IAAI,EACzB,MAAM,GAAE,MAAM,EAAO,EACrB,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,EAChE,QAAQ,CAAC,EAAE,MAAM,IAAI,GACpB,MAAM,CAg9BR"}

package/dist/server.js

@@ -597,8 +597,14 @@ export function startServer(port, collections, publicDir, oauth, admins = [], re
                     jsonError(res, 400, 'DPoP header required');
                     return;
                 }
-                const result = await handlePar(oauth, body, dpopHeader, `${requestOrigin}/oauth/par`);
-                jsonResponse(res, result);
+                try {
+                    const result = await handlePar(oauth, body, dpopHeader, `${requestOrigin}/oauth/par`);
+                    jsonResponse(res, result);
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : 'Unknown error';
+                    jsonError(res, 400, message);
+                }
                 return;
             }
             // OAuth Authorize

package/dist/setup.d.ts

@@ -1,8 +1,19 @@
+/** Context passed to each setup script's handler function. */
 export interface SetupContext {
     db: {
         query: (sql: string, params?: any[]) => Promise<any[]>;
         run: (sql: string, ...params: any[]) => Promise<void>;
     };
 }
+/**
+ * Run all setup scripts in the given directory on server boot.
+ *
+ * Each script should export a default handler function (or `{ handler }`) that
+ * receives a {@link SetupContext} with database access. Scripts run in sorted
+ * filename order — prefix with numbers (e.g. `01-create-tables.ts`) to control
+ * execution order. Files starting with `_` are ignored.
+ *
+ * @param setupDir - Absolute path to the `setup/` directory
+ */
 export declare function initSetup(setupDir: string): Promise<void>;
 //# sourceMappingURL=setup.d.ts.map

package/dist/setup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../src/setup.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,YAAY;IAC3B,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;CACF;AAiBD,wBAAsB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAqB/D"}
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../src/setup.ts"],"names":[],"mappings":"AA6BA,8DAA8D;AAC9D,MAAM,WAAW,YAAY;IAC3B,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;CACF;AAkBD;;;;;;;;;GASG;AACH,wBAAsB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAqB/D"}

package/dist/setup.js

@@ -6,10 +6,35 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     }
     return path;
 };
+/**
+ * Setup scripts that run once on server boot for initializing custom tables,
+ * views, or other database state.
+ *
+ * Place scripts in the `setup/` directory. Each module default-exports a handler
+ * function (or `{ handler }`) that receives a {@link SetupContext} with database
+ * access. Scripts run in sorted filename order — prefix with numbers to control
+ * execution order. Files starting with `_` are ignored.
+ *
+ * @example
+ * ```ts
+ * // setup/01-leaderboard.ts
+ * import type { SetupContext } from '@hatk/hatk/setup'
+ *
+ * export default async function (ctx: SetupContext) {
+ *   await ctx.db.run(`
+ *     CREATE TABLE IF NOT EXISTS leaderboard (
+ *       did TEXT PRIMARY KEY,
+ *       score INTEGER DEFAULT 0
+ *     )
+ *   `)
+ * }
+ * ```
+ */
 import { resolve, relative } from 'node:path';
 import { readdirSync, statSync } from 'node:fs';
 import { log } from "./logger.js";
 import { querySQL, runSQL } from "./db.js";
+/** Recursively collect .ts/.js files in a directory, skipping files prefixed with `_`. */
 function walkDir(dir) {
     const results = [];
     try {
@@ -26,6 +51,16 @@ function walkDir(dir) {
     catch { }
     return results.sort();
 }
+/**
+ * Run all setup scripts in the given directory on server boot.
+ *
+ * Each script should export a default handler function (or `{ handler }`) that
+ * receives a {@link SetupContext} with database access. Scripts run in sorted
+ * filename order — prefix with numbers (e.g. `01-create-tables.ts`) to control
+ * execution order. Files starting with `_` are ignored.
+ *
+ * @param setupDir - Absolute path to the `setup/` directory
+ */
 export async function initSetup(setupDir) {
     const files = walkDir(setupDir);
     if (files.length === 0)

package/dist/test.js

@@ -9,7 +9,7 @@ import { initXrpc, executeXrpc, listXrpc, configureRelay } from "./xrpc.js";
 import { initOpengraph } from "./opengraph.js";
 import { initLabels } from "./labels.js";
 import { discoverViews } from "./views.js";
-import { loadOnLoginHook } from "./oauth/hooks.js";
+import { loadOnLoginHook } from "./hooks.js";
 import { validateLexicons } from '@bigmoves/lexicon';
 import { packCursor, unpackCursor, isTakendownDid, filterTakendownDids } from "./db.js";
 import { seed as createSeedHelpers } from "./seed.js";

package/dist/xrpc.d.ts

@@ -1,14 +1,25 @@
 import type { Row, FlatRow } from './lex-types.ts';
 export type { Row, FlatRow };
+/** Thrown from XRPC handlers to return a 400 response with an error message. */
 export declare class InvalidRequestError extends Error {
     status: number;
     errorName?: string;
     constructor(message: string, errorName?: string);
 }
+/** Thrown from XRPC handlers to return a 404 response. */
 export declare class NotFoundError extends InvalidRequestError {
     status: number;
     constructor(message?: string);
 }
+/**
+ * Context passed to every XRPC handler. Provides database access, pagination
+ * helpers, viewer auth, record resolution, full-text search, label queries,
+ * and blob URL generation.
+ *
+ * @typeParam P - Query parameter types (derived from lexicon)
+ * @typeParam Records - Map of collection NSID → record type (from generated types)
+ * @typeParam I - Input body type for procedure calls
+ */
 export interface XrpcContext<P = Record<string, string>, Records extends Record<string, any> = Record<string, any>, I = unknown> {
     db: {
         query: (sql: string, params?: any[]) => Promise<any[]>;
@@ -43,11 +54,23 @@ export interface XrpcContext<P = Record<string, string>, Records extends Record<
     labels: (uris: string[]) => Promise<Map<string, any[]>>;
     blobUrl: (did: string, ref: unknown, preset?: 'avatar' | 'banner' | 'feed_thumbnail' | 'feed_fullsize') => string | undefined;
 }
+/** Set the relay URL used for blob URL generation. Called once during boot. */
 export declare function configureRelay(relay: string): void;
+/**
+ * Generate a CDN URL for a blob ref. Uses the PDS directly in local dev,
+ * or the Bluesky CDN (`cdn.bsky.app`) in production.
+ */
 export declare function blobUrl(did: string, ref: unknown, preset?: 'avatar' | 'banner' | 'feed_thumbnail' | 'feed_fullsize'): string | undefined;
+/**
+ * Discover and load XRPC handler modules from the `xrpc/` directory.
+ * Directory nesting maps to NSID segments. Parameters are validated and
+ * coerced against the matching lexicon definition.
+ */
 export declare function initXrpc(xrpcDir: string): Promise<void>;
+/** Execute a registered XRPC handler by name. Returns null if no handler matches. */
 export declare function executeXrpc(name: string, params: Record<string, string>, cursor: string | undefined, limit: number, viewer?: {
     did: string;
 } | null, input?: unknown): Promise<any | null>;
+/** Return all registered XRPC method names. */
 export declare function listXrpc(): string[];
 //# sourceMappingURL=xrpc.d.ts.map

package/dist/xrpc.d.ts.map

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

package/dist/xrpc.js

@@ -6,12 +6,33 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     }
     return path;
 };
+/**
+ * XRPC method handler system for serving AT Protocol endpoints.
+ *
+ * Place handler modules in the `xrpc/` directory, nested by NSID segments
+ * (e.g. `xrpc/app/bsky/feed/getAuthorFeed.ts` → `app.bsky.feed.getAuthorFeed`).
+ * Each module default-exports a `{ handler }` function that receives an
+ * {@link XrpcContext} with database access, query params, pagination, and
+ * viewer auth.
+ *
+ * @example
+ * ```ts
+ * // xrpc/xyz/statusphere/getStatuses.ts
+ * import { defineXrpc } from '../../hatk.generated.ts'
+ *
+ * export default defineXrpc('xyz.statusphere.getStatuses', async (ctx) => {
+ *   const rows = await ctx.db.query('SELECT * FROM statusphere_status LIMIT ?', [ctx.limit])
+ *   return { statuses: rows }
+ * })
+ * ```
+ */
 import { resolve, relative } from 'node:path';
 import { readdirSync, statSync } from 'node:fs';
 import { log } from "./logger.js";
 import { querySQL, runSQL, packCursor, unpackCursor, isTakendownDid, filterTakendownDids, searchRecords, findUriByFields, lookupByFieldBatch, countByFieldBatch, queryLabelsForUris, } from "./db.js";
 import { resolveRecords } from "./hydrate.js";
 import { getLexicon } from "./schema.js";
+/** Thrown from XRPC handlers to return a 400 response with an error message. */
 export class InvalidRequestError extends Error {
     status = 400;
     errorName;
@@ -20,6 +41,7 @@ export class InvalidRequestError extends Error {
         this.errorName = errorName;
     }
 }
+/** Thrown from XRPC handlers to return a 404 response. */
 export class NotFoundError extends InvalidRequestError {
     status = 404;
     constructor(message = 'Not found') {
@@ -27,9 +49,14 @@ export class NotFoundError extends InvalidRequestError {
     }
 }
 let _relayUrl = '';
+/** Set the relay URL used for blob URL generation. Called once during boot. */
 export function configureRelay(relay) {
     _relayUrl = relay;
 }
+/**
+ * Generate a CDN URL for a blob ref. Uses the PDS directly in local dev,
+ * or the Bluesky CDN (`cdn.bsky.app`) in production.
+ */
 export function blobUrl(did, ref, preset = 'avatar') {
     if (!ref)
         return undefined;
@@ -42,6 +69,7 @@ export function blobUrl(did, ref, preset = 'avatar') {
     return `https://cdn.bsky.app/img/${preset}/plain/${did}/${p.ref.$link}@jpeg`;
 }
 const handlers = new Map();
+/** Recursively collect .ts/.js files in a directory, skipping files prefixed with `_`. */
 function walkDir(dir) {
     const results = [];
     try {
@@ -58,6 +86,11 @@ function walkDir(dir) {
     catch { }
     return results.sort();
 }
+/**
+ * Discover and load XRPC handler modules from the `xrpc/` directory.
+ * Directory nesting maps to NSID segments. Parameters are validated and
+ * coerced against the matching lexicon definition.
+ */
 export async function initXrpc(xrpcDir) {
     const files = walkDir(xrpcDir);
     if (files.length === 0)
@@ -128,12 +161,14 @@ export async function initXrpc(xrpcDir) {
         log(`[xrpc] discovered: ${name}`);
     }
 }
+/** Execute a registered XRPC handler by name. Returns null if no handler matches. */
 export async function executeXrpc(name, params, cursor, limit, viewer, input) {
     const handler = handlers.get(name);
     if (!handler)
         return null;
     return handler.execute(params, cursor, limit, viewer || null, input);
 }
+/** Return all registered XRPC method names. */
 export function listXrpc() {
     return Array.from(handlers.keys());
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hatk/hatk",
-  "version": "0.0.1-alpha.20",
+  "version": "0.0.1-alpha.22",
   "license": "MIT",
   "bin": {
     "hatk": "dist/cli.js"