lmgrep 0.1.18 → 0.2.1

package/dist/infrastructure/p2p/SecureChannel.js

@@ -0,0 +1,71 @@
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+/**
+ * Authenticated encryption and message framing over a raw peer socket.
+ *
+ * AES-256-GCM, so a tampered payload fails to decrypt rather than being parsed
+ * — a peer discovered over a public DHT is not trusted. Frames carry an
+ * explicit length prefix because a stream socket splits and merges writes
+ * arbitrarily, and JSON alone gives no way to find a message boundary.
+ */
+export class SecureChannel {
+    key;
+    static IV_BYTES = 12;
+    static TAG_BYTES = 16;
+    static LENGTH_PREFIX_BYTES = 4;
+    constructor(key) {
+        this.key = key;
+    }
+    send(socket, message) {
+        const encrypted = this.encrypt(Buffer.from(JSON.stringify(message)));
+        const frame = Buffer.alloc(SecureChannel.LENGTH_PREFIX_BYTES + encrypted.length);
+        frame.writeUInt32BE(encrypted.length, 0);
+        encrypted.copy(frame, SecureChannel.LENGTH_PREFIX_BYTES);
+        socket.write(frame);
+    }
+    /**
+     * A stateful reader: feed it raw socket chunks, and it emits whole
+     * messages as their frames complete.
+     */
+    reader(onMessage) {
+        let buffered = Buffer.alloc(0);
+        return (chunk) => {
+            buffered = Buffer.concat([buffered, chunk]);
+            while (buffered.length >= SecureChannel.LENGTH_PREFIX_BYTES) {
+                const length = buffered.readUInt32BE(0);
+                if (buffered.length < SecureChannel.LENGTH_PREFIX_BYTES + length) {
+                    break;
+                }
+                const frame = buffered.subarray(SecureChannel.LENGTH_PREFIX_BYTES, SecureChannel.LENGTH_PREFIX_BYTES + length);
+                buffered = buffered.subarray(SecureChannel.LENGTH_PREFIX_BYTES + length);
+                onMessage(JSON.parse(this.decrypt(frame).toString()));
+            }
+        };
+    }
+    /** Resolve once a message of the expected type arrives. */
+    await(socket, expected) {
+        return new Promise((resolve, reject) => {
+            const read = this.reader((message) => {
+                if (message.type === expected)
+                    resolve(message);
+            });
+            socket.on("data", read);
+            socket.on("error", reject);
+            socket.on("close", () => reject(new Error("Connection closed")));
+        });
+    }
+    encrypt(plaintext) {
+        const iv = randomBytes(SecureChannel.IV_BYTES);
+        const cipher = createCipheriv("aes-256-gcm", this.key, iv);
+        const body = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+        return Buffer.concat([iv, cipher.getAuthTag(), body]);
+    }
+    decrypt(data) {
+        const iv = data.subarray(0, SecureChannel.IV_BYTES);
+        const tag = data.subarray(SecureChannel.IV_BYTES, SecureChannel.IV_BYTES + SecureChannel.TAG_BYTES);
+        const body = data.subarray(SecureChannel.IV_BYTES + SecureChannel.TAG_BYTES);
+        const decipher = createDecipheriv("aes-256-gcm", this.key, iv);
+        decipher.setAuthTag(tag);
+        return Buffer.concat([decipher.update(body), decipher.final()]);
+    }
+}
+//# sourceMappingURL=SecureChannel.js.map

package/dist/infrastructure/p2p/SecureChannel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SecureChannel.js","sourceRoot":"","sources":["../../../src/infrastructure/p2p/SecureChannel.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AA8B5E;;;;;;;GAOG;AACH,MAAM,OAAO,aAAa;IAKI;IAJrB,MAAM,CAAU,QAAQ,GAAG,EAAE,CAAC;IAC9B,MAAM,CAAU,SAAS,GAAG,EAAE,CAAC;IAC/B,MAAM,CAAU,mBAAmB,GAAG,CAAC,CAAC;IAEhD,YAA6B,GAAW;QAAX,QAAG,GAAH,GAAG,CAAQ;IAAG,CAAC;IAE5C,IAAI,CAAC,MAAwC,EAAE,OAAqB;QACnE,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;QACrE,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CACzB,aAAa,CAAC,mBAAmB,GAAG,SAAS,CAAC,MAAM,CACpD,CAAC;QACF,KAAK,CAAC,aAAa,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;QACzC,SAAS,CAAC,IAAI,CAAC,KAAK,EAAE,aAAa,CAAC,mBAAmB,CAAC,CAAC;QACzD,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACrB,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,SAA0C;QAChD,IAAI,QAAQ,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAC/B,OAAO,CAAC,KAAa,EAAE,EAAE;YACxB,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC;YAC5C,OAAO,QAAQ,CAAC,MAAM,IAAI,aAAa,CAAC,mBAAmB,EAAE,CAAC;gBAC7D,MAAM,MAAM,GAAG,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;gBACxC,IAAI,QAAQ,CAAC,MAAM,GAAG,aAAa,CAAC,mBAAmB,GAAG,MAAM,EAAE,CAAC;oBAClE,MAAM;gBACP,CAAC;gBACD,MAAM,KAAK,GAAG,QAAQ,CAAC,QAAQ,CAC9B,aAAa,CAAC,mBAAmB,EACjC,aAAa,CAAC,mBAAmB,GAAG,MAAM,CAC1C,CAAC;gBACF,QAAQ,GAAG,QAAQ,CAAC,QAAQ,CAC3B,aAAa,CAAC,mBAAmB,GAAG,MAAM,CAC1C,CAAC;gBACF,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;YACvD,CAAC;QACF,CAAC,CAAC;IACH,CAAC;IAED,2DAA2D;IAC3D,KAAK,CACJ,MAAoB,EACpB,QAA8B;QAE9B,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACtC,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE;gBACpC,IAAI,OAAO,CAAC,IAAI,KAAK,QAAQ;oBAAE,OAAO,CAAC,OAAO,CAAC,CAAC;YACjD,CAAC,CAAC,CAAC;YACH,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;YACxB,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;YAC3B,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC;QAClE,CAAC,CAAC,CAAC;IACJ,CAAC;IAEO,OAAO,CAAC,SAAiB;QAChC,MAAM,EAAE,GAAG,WAAW,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;QAC/C,MAAM,MAAM,GAAG,cAAc,CAAC,aAAa,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QAC3D,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QACvE,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,MAAM,CAAC,UAAU,EAAE,EAAE,IAAI,CAAC,CAAC,CAAC;IACvD,CAAC;IAEO,OAAO,CAAC,IAAY;QAC3B,MAAM,EAAE,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;QACpD,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CACxB,aAAa,CAAC,QAAQ,EACtB,aAAa,CAAC,QAAQ,GAAG,aAAa,CAAC,SAAS,CAChD,CAAC;QACF,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CACzB,aAAa,CAAC,QAAQ,GAAG,aAAa,CAAC,SAAS,CAChD,CAAC;QACF,MAAM,QAAQ,GAAG,gBAAgB,CAAC,aAAa,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QAC/D,QAAQ,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;QACzB,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IACjE,CAAC"}

package/dist/infrastructure/p2p/ShareCode.d.ts

@@ -0,0 +1,25 @@
+/**
+ * A human-transcribable one-time code that both names a rendezvous topic and
+ * derives the encryption key for a share.
+ *
+ * Three words plus hex: short enough to read aloud, with 40 bits of entropy in
+ * the suffix so a code cannot be guessed within its lifetime.
+ *
+ * Topic and key are derived from the code by *separate* HKDF labels. That
+ * separation is the point — peer discovery necessarily publishes the topic, and
+ * it must not leak anything about the key protecting the payload.
+ */
+export declare class ShareCode {
+    readonly value: string;
+    private static readonly WORDS;
+    static readonly PATTERN: RegExp;
+    private constructor();
+    static generate(): ShareCode;
+    static parse(value: string): ShareCode | undefined;
+    static looksLikeCode(value: string): boolean;
+    toString(): string;
+    /** Rendezvous topic for peer discovery. Public by nature. */
+    toTopic(): Buffer;
+    /** AES-256 key for the payload. Never derivable from the topic. */
+    toEncryptionKey(): Buffer;
+}

package/dist/infrastructure/p2p/ShareCode.js

@@ -0,0 +1,304 @@
+import { hkdfSync, randomBytes } from "node:crypto";
+/**
+ * A human-transcribable one-time code that both names a rendezvous topic and
+ * derives the encryption key for a share.
+ *
+ * Three words plus hex: short enough to read aloud, with 40 bits of entropy in
+ * the suffix so a code cannot be guessed within its lifetime.
+ *
+ * Topic and key are derived from the code by *separate* HKDF labels. That
+ * separation is the point — peer discovery necessarily publishes the topic, and
+ * it must not leak anything about the key protecting the payload.
+ */
+export class ShareCode {
+    value;
+    static WORDS = [
+        "acid",
+        "acme",
+        "aged",
+        "also",
+        "arch",
+        "area",
+        "army",
+        "away",
+        "back",
+        "bail",
+        "bake",
+        "band",
+        "bank",
+        "barn",
+        "base",
+        "bath",
+        "beam",
+        "bean",
+        "bear",
+        "beat",
+        "beef",
+        "beer",
+        "bell",
+        "belt",
+        "bend",
+        "bike",
+        "bird",
+        "bite",
+        "blow",
+        "blue",
+        "boat",
+        "body",
+        "bolt",
+        "bomb",
+        "bond",
+        "bone",
+        "book",
+        "boot",
+        "born",
+        "boss",
+        "bowl",
+        "bulk",
+        "bull",
+        "burn",
+        "cage",
+        "cake",
+        "calm",
+        "came",
+        "camp",
+        "cape",
+        "card",
+        "care",
+        "cart",
+        "case",
+        "cash",
+        "cast",
+        "cave",
+        "chef",
+        "chip",
+        "city",
+        "clan",
+        "clay",
+        "clip",
+        "club",
+        "clue",
+        "coal",
+        "coat",
+        "code",
+        "coil",
+        "coin",
+        "cold",
+        "come",
+        "cook",
+        "cool",
+        "cope",
+        "copy",
+        "cord",
+        "core",
+        "corn",
+        "cost",
+        "crew",
+        "crop",
+        "crow",
+        "cure",
+        "curl",
+        "cute",
+        "dame",
+        "damp",
+        "dare",
+        "dark",
+        "dash",
+        "data",
+        "dawn",
+        "deal",
+        "dean",
+        "deck",
+        "deep",
+        "deer",
+        "demo",
+        "desk",
+        "dial",
+        "dice",
+        "diet",
+        "dirt",
+        "disk",
+        "dock",
+        "door",
+        "dose",
+        "down",
+        "draw",
+        "drop",
+        "drum",
+        "dual",
+        "duck",
+        "dull",
+        "dump",
+        "dune",
+        "dust",
+        "duty",
+        "each",
+        "earl",
+        "earn",
+        "ease",
+        "east",
+        "edge",
+        "else",
+        "epic",
+        "even",
+        "ever",
+        "exam",
+        "exit",
+        "face",
+        "fact",
+        "fade",
+        "fail",
+        "fair",
+        "fall",
+        "fame",
+        "farm",
+        "fast",
+        "fate",
+        "fawn",
+        "feed",
+        "feel",
+        "file",
+        "film",
+        "find",
+        "fine",
+        "fire",
+        "firm",
+        "fish",
+        "flag",
+        "flat",
+        "fled",
+        "flip",
+        "flow",
+        "foam",
+        "fold",
+        "folk",
+        "fond",
+        "food",
+        "fool",
+        "fork",
+        "form",
+        "fort",
+        "foul",
+        "four",
+        "free",
+        "frog",
+        "fuel",
+        "full",
+        "fund",
+        "fury",
+        "fuse",
+        "gain",
+        "gale",
+        "game",
+        "gang",
+        "gate",
+        "gave",
+        "gaze",
+        "gear",
+        "gene",
+        "gift",
+        "glad",
+        "glow",
+        "glue",
+        "goat",
+        "gold",
+        "golf",
+        "gone",
+        "good",
+        "grab",
+        "gray",
+        "grid",
+        "grip",
+        "grow",
+        "gulf",
+        "guru",
+        "gust",
+        "hack",
+        "half",
+        "hall",
+        "halt",
+        "hand",
+        "hang",
+        "hare",
+        "harm",
+        "harp",
+        "hash",
+        "hate",
+        "haul",
+        "have",
+        "hawk",
+        "haze",
+        "head",
+        "heap",
+        "heat",
+        "held",
+        "helm",
+        "help",
+        "herb",
+        "herd",
+        "here",
+        "hero",
+        "hide",
+        "high",
+        "hike",
+        "hill",
+        "hilt",
+        "hint",
+        "hire",
+        "hold",
+        "hole",
+        "holy",
+        "home",
+        "hood",
+        "hook",
+        "hope",
+        "horn",
+        "host",
+        "hour",
+        "huge",
+        "hull",
+        "hung",
+        "hunt",
+        "hurt",
+        "icon",
+        "idea",
+        "inch",
+        "info",
+        "iron",
+        "isle",
+        "item",
+        "jack",
+        "jade",
+    ];
+    static PATTERN = /^lmgrep[a-z]+[0-9a-f]{10}$/;
+    constructor(value) {
+        this.value = value;
+    }
+    static generate() {
+        const bytes = randomBytes(16);
+        const words = [
+            ShareCode.WORDS[bytes[0]],
+            ShareCode.WORDS[bytes[1]],
+            ShareCode.WORDS[bytes[2]],
+        ].join("");
+        return new ShareCode(`lmgrep${words}${bytes.subarray(3, 8).toString("hex")}`);
+    }
+    static parse(value) {
+        return ShareCode.looksLikeCode(value) ? new ShareCode(value) : undefined;
+    }
+    static looksLikeCode(value) {
+        return ShareCode.PATTERN.test(value);
+    }
+    toString() {
+        return this.value;
+    }
+    /** Rendezvous topic for peer discovery. Public by nature. */
+    toTopic() {
+        return Buffer.from(hkdfSync("sha256", this.value, "lmgrep-topic", "topic", 32));
+    }
+    /** AES-256 key for the payload. Never derivable from the topic. */
+    toEncryptionKey() {
+        return Buffer.from(hkdfSync("sha256", this.value, "lmgrep-key", "encryption", 32));
+    }
+}
+//# sourceMappingURL=ShareCode.js.map

package/dist/infrastructure/p2p/ShareCode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ShareCode.js","sourceRoot":"","sources":["../../../src/infrastructure/p2p/ShareCode.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAEpD;;;;;;;;;;GAUG;AACH,MAAM,OAAO,SAAS;IAsQQ;IArQrB,MAAM,CAAU,KAAK,GAAG;QAC/B,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;QACN,MAAM;KACN,CAAC;IAEF,MAAM,CAAU,OAAO,GAAG,4BAA4B,CAAC;IAEvD,YAA6B,KAAa;QAAb,UAAK,GAAL,KAAK,CAAQ;IAAG,CAAC;IAE9C,MAAM,CAAC,QAAQ;QACd,MAAM,KAAK,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC;QAC9B,MAAM,KAAK,GAAG;YACb,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YACzB,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YACzB,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;SACzB,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACX,OAAO,IAAI,SAAS,CACnB,SAAS,KAAK,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CACvD,CAAC;IACH,CAAC;IAED,MAAM,CAAC,KAAK,CAAC,KAAa;QACzB,OAAO,SAAS,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC1E,CAAC;IAED,MAAM,CAAC,aAAa,CAAC,KAAa;QACjC,OAAO,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACtC,CAAC;IAED,QAAQ;QACP,OAAO,IAAI,CAAC,KAAK,CAAC;IACnB,CAAC;IAED,6DAA6D;IAC7D,OAAO;QACN,OAAO,MAAM,CAAC,IAAI,CACjB,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,EAAE,CAAC,CAC3D,CAAC;IACH,CAAC;IAED,mEAAmE;IACnE,eAAe;QACd,OAAO,MAAM,CAAC,IAAI,CACjB,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,EAAE,CAAC,CAC9D,CAAC;IACH,CAAC"}

package/dist/infrastructure/process/ProcessRegistry.d.ts

@@ -0,0 +1,50 @@
+import type { StateDirectoryPort } from "../../domain/ports/StateDirectoryPort.js";
+/** What kind of lmgrep invocation a process is. */
+export type ProcessKind = "mcp" | "serve" | "cli";
+/** A live lmgrep process holding a database's maintainer lock. */
+export interface RunningProcess {
+    pid: number;
+    /** Process title from /proc/<pid>/comm (e.g. "lmgrep-mcp"). */
+    processName: string;
+    cmdline: string;
+    kind: ProcessKind;
+    /** Working tree this process watches. */
+    projectRoot?: string;
+    /** Database it holds. */
+    databasePath?: string;
+    /** Whether this process is watching the index for changes. */
+    watching: boolean;
+}
+/**
+ * Discovers which lmgrep processes are alive and what they hold.
+ *
+ * Maintainer lock files double as the registry: each records its owner's pid,
+ * worktree and database, so scanning them and testing liveness gives an
+ * accurate picture without any separate bookkeeping that could drift from
+ * reality.
+ */
+export declare class ProcessRegistry {
+    private readonly state;
+    private static readonly LOCK_SUFFIX;
+    constructor(state: StateDirectoryPort);
+    discoverRunning(): RunningProcess[];
+    /**
+     * Lock files, from the locks directory and from the state root.
+     *
+     * The root is scanned too because a watcher started before locks moved is
+     * still running and still holds its database — reporting "no running
+     * processes" right after an upgrade would be wrong in exactly the moment
+     * someone is most likely to check.
+     */
+    private lockFiles;
+    private inspect;
+    /**
+     * What kind of process this is, from its title.
+     *
+     * The title is the only reliable signal: `process.title` rewrites the argv
+     * buffer, so /proc/<pid>/cmdline reads back as the title alone and carries
+     * no subcommand. The MCP entry point titles itself distinctly; anything
+     * else holding a maintainer lock reached it through `lmgrep serve`.
+     */
+    private classify;
+}

package/dist/infrastructure/process/ProcessRegistry.js

@@ -0,0 +1,109 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { PidFileLock } from "../fs/PidFileLock.js";
+/**
+ * Discovers which lmgrep processes are alive and what they hold.
+ *
+ * Maintainer lock files double as the registry: each records its owner's pid,
+ * worktree and database, so scanning them and testing liveness gives an
+ * accurate picture without any separate bookkeeping that could drift from
+ * reality.
+ */
+export class ProcessRegistry {
+    state;
+    static LOCK_SUFFIX = ".lock";
+    constructor(state) {
+        this.state = state;
+    }
+    discoverRunning() {
+        const results = [];
+        // One process can hold several databases; report it once.
+        const seen = new Set();
+        for (const path of this.lockFiles()) {
+            const owner = new PidFileLock(path).read();
+            if (owner === undefined)
+                continue;
+            if (!PidFileLock.isAlive(owner.pid) || seen.has(owner.pid))
+                continue;
+            seen.add(owner.pid);
+            const info = this.inspect(owner.pid);
+            if (!info)
+                continue;
+            results.push({
+                pid: owner.pid,
+                processName: info.name,
+                cmdline: info.cmdline,
+                kind: this.classify(info),
+                // The lock records the worktree its owner actually watches,
+                // which is what the user wants to see — several worktrees can
+                // share one database, so the database's own recorded root
+                // would name the wrong tree.
+                projectRoot: owner.root,
+                databasePath: owner.database,
+                // Every lock in this scan is a maintainer lock, and only a
+                // watcher ever takes one — so holding it *is* watching. This
+                // used to be inferred from the command line, which cannot
+                // work: setting process.title overwrites that buffer, so the
+                // subcommand a process was launched with is no longer there
+                // to match against.
+                watching: true,
+            });
+        }
+        return results;
+    }
+    /**
+     * Lock files, from the locks directory and from the state root.
+     *
+     * The root is scanned too because a watcher started before locks moved is
+     * still running and still holds its database — reporting "no running
+     * processes" right after an upgrade would be wrong in exactly the moment
+     * someone is most likely to check.
+     */
+    lockFiles() {
+        const out = [];
+        for (const directory of [this.state.locksDirectory(), this.state.root()]) {
+            let entries;
+            try {
+                entries = readdirSync(directory);
+            }
+            catch {
+                continue;
+            }
+            for (const entry of entries) {
+                if (entry.endsWith(ProcessRegistry.LOCK_SUFFIX)) {
+                    out.push(join(directory, entry));
+                }
+            }
+        }
+        return out;
+    }
+    inspect(pid) {
+        try {
+            return {
+                name: readFileSync(`/proc/${pid}/comm`, "utf-8").trim(),
+                cmdline: readFileSync(`/proc/${pid}/cmdline`, "utf-8")
+                    .replace(/\0/g, " ")
+                    .trim(),
+            };
+        }
+        catch {
+            // No procfs (macOS) or the process exited mid-scan.
+            return undefined;
+        }
+    }
+    /**
+     * What kind of process this is, from its title.
+     *
+     * The title is the only reliable signal: `process.title` rewrites the argv
+     * buffer, so /proc/<pid>/cmdline reads back as the title alone and carries
+     * no subcommand. The MCP entry point titles itself distinctly; anything
+     * else holding a maintainer lock reached it through `lmgrep serve`.
+     */
+    classify(info) {
+        if (info.name === "lmgrep-mcp" || info.cmdline.includes("mcp")) {
+            return "mcp";
+        }
+        return "serve";
+    }
+}
+//# sourceMappingURL=ProcessRegistry.js.map

package/dist/infrastructure/process/ProcessRegistry.js.map

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

package/dist/infrastructure/treesitter/ChunkContextBuilder.d.ts

@@ -0,0 +1,45 @@
+import type { Node } from "web-tree-sitter";
+import type { LanguageConfig } from "./LanguageCatalog.js";
+/** What kind of thing a chunk is, structurally. */
+export type StructuralRole = "definition" | "orchestration" | "implementation";
+/** One enclosing scope, e.g. `class Foo`. */
+export interface ScopeEntry {
+    kind: string;
+    name: string;
+}
+/**
+ * Builds the context header prepended to a chunk before embedding.
+ *
+ * The header is what makes an isolated function retrievable: on its own,
+ * `async function handle(req)` shares little vocabulary with "how are webhooks
+ * authenticated", but stamped with its file, enclosing class and doc comment
+ * it does. Retrieval quality depends on this at least as much as on the text.
+ */
+export declare class ChunkContextBuilder {
+    /** How far above a node to look for its doc comment. */
+    private static readonly MAX_COMMENT_LOOKBACK;
+    /** AST node type -> the word used for it in the header. */
+    private static readonly SCOPE_KINDS;
+    /** Node types that declare a shape rather than behaviour. */
+    private static readonly DEFINITION_TYPES;
+    /** Node types that wire things together rather than implement them. */
+    private static readonly ORCHESTRATION_TYPES;
+    /** The full header for one chunk. */
+    build(node: Node, filePath: string, source: string, language: LanguageConfig): string;
+    /** The minimal header for a file with no parsed structure. */
+    buildFileOnly(filePath: string): string;
+    /** Walk up from a node collecting the named scopes that enclose it. */
+    extractScope(node: Node, language: LanguageConfig): ScopeEntry[];
+    /**
+     * Collect the comment block or decorators immediately above a node.
+     *
+     * A blank line ends the block only once something has been collected, so a
+     * comment separated from its node by whitespace is still picked up, while
+     * unrelated code above it is not.
+     */
+    extractLeadingComment(node: Node, source: string): string | null;
+    classifyRole(node: Node): StructuralRole;
+    /** Comment syntax across every supported language, plus decorators. */
+    private looksLikeCommentOrDecorator;
+    private nodeName;
+}