@graphmemory/server 1.1.0

package/dist/lib/access.js

@@ -0,0 +1,67 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveAccess = resolveAccess;
+exports.resolveUserFromApiKey = resolveUserFromApiKey;
+exports.canRead = canRead;
+exports.canWrite = canWrite;
+const crypto_1 = __importDefault(require("crypto"));
+/**
+ * Resolve access level for a user on a specific graph.
+ *
+ * Resolution chain (first match wins):
+ *   graph.access[userId] → project.access[userId] → workspace.access[userId]
+ *   → server.access[userId] → server.defaultAccess
+ */
+function resolveAccess(userId, graphName, projectConfig, serverConfig, workspaceConfig) {
+    if (!userId)
+        return serverConfig.defaultAccess;
+    // 1. Graph-level
+    const graphAccess = projectConfig.graphConfigs[graphName].access?.[userId];
+    if (graphAccess)
+        return graphAccess;
+    // 2. Project-level
+    const projectAccess = projectConfig.access?.[userId];
+    if (projectAccess)
+        return projectAccess;
+    // 3. Workspace-level
+    if (workspaceConfig) {
+        const wsAccess = workspaceConfig.access?.[userId];
+        if (wsAccess)
+            return wsAccess;
+    }
+    // 4. Server-level
+    const serverAccess = serverConfig.access?.[userId];
+    if (serverAccess)
+        return serverAccess;
+    // 5. Default
+    return serverConfig.defaultAccess;
+}
+/**
+ * Look up a user by API key.
+ * Returns { userId, user } or undefined if not found.
+ */
+function resolveUserFromApiKey(apiKey, users) {
+    const keyBuf = Buffer.from(apiKey);
+    for (const [userId, user] of Object.entries(users)) {
+        const userKeyBuf = Buffer.from(user.apiKey);
+        if (keyBuf.length === userKeyBuf.length && crypto_1.default.timingSafeEqual(keyBuf, userKeyBuf)) {
+            return { userId, user };
+        }
+    }
+    return undefined;
+}
+/**
+ * Check if an access level allows read operations.
+ */
+function canRead(level) {
+    return level === 'r' || level === 'rw';
+}
+/**
+ * Check if an access level allows write operations.
+ */
+function canWrite(level) {
+    return level === 'rw';
+}

package/dist/lib/embedder.js

@@ -0,0 +1,235 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadModel = loadModel;
+exports.embed = embed;
+exports.embedQuery = embedQuery;
+exports.embedBatch = embedBatch;
+exports.resetEmbedder = resetEmbedder;
+exports.cosineSimilarity = cosineSimilarity;
+const transformers_1 = require("@huggingface/transformers");
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+// ---------------------------------------------------------------------------
+// LRU cache for embedding vectors (avoids re-computing identical texts)
+// ---------------------------------------------------------------------------
+const DEFAULT_CACHE_SIZE = 10_000;
+class LruCache {
+    maxSize;
+    map = new Map();
+    constructor(maxSize) {
+        this.maxSize = maxSize;
+    }
+    get(key) {
+        const v = this.map.get(key);
+        if (v !== undefined) {
+            // Move to end (most recently used)
+            this.map.delete(key);
+            this.map.set(key, v);
+        }
+        return v;
+    }
+    set(key, value) {
+        if (this.map.has(key))
+            this.map.delete(key);
+        this.map.set(key, value);
+        if (this.map.size > this.maxSize) {
+            // Evict oldest (first key)
+            const first = this.map.keys().next().value;
+            this.map.delete(first);
+        }
+    }
+    clear() { this.map.clear(); }
+}
+const _models = new Map(); // name → { pipe, model, embedding }
+const _pipeCache = new Map(); // "model|dtype" → pipe (dedup)
+function validateRemoteUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new Error(`Invalid remote embedding URL: ${url}`);
+    }
+    if (!['http:', 'https:'].includes(parsed.protocol)) {
+        throw new Error(`Remote embedding URL must use http or https: ${url}`);
+    }
+}
+async function loadModel(model, embedding, modelsDir, name = 'default') {
+    const maxChars = embedding.maxChars;
+    const cacheSize = embedding.cacheSize ?? DEFAULT_CACHE_SIZE;
+    // Remote embedding: register proxy, skip ONNX loading
+    if (embedding.remote) {
+        validateRemoteUrl(embedding.remote);
+        _models.set(name, { pipe: null, model, embedding, maxChars, cache: new LruCache(cacheSize), remote: { url: embedding.remote, apiKey: embedding.remoteApiKey } });
+        process.stderr.write(`[embedder] Model "${name}" using remote endpoint ${embedding.remote}\n`);
+        return;
+    }
+    // Cache key includes dtype since same model with different dtype = different pipeline
+    const cacheKey = `${model.name}|${model.dtype ?? ''}`;
+    // Reuse pipeline if same model+dtype already loaded
+    const cached = _pipeCache.get(cacheKey);
+    if (cached) {
+        _models.set(name, { pipe: cached, model, embedding, maxChars, cache: new LruCache(cacheSize) });
+        process.stderr.write(`[embedder] Reusing model ${model.name} for "${name}"\n`);
+        return;
+    }
+    transformers_1.env.cacheDir = modelsDir;
+    const modelDir = path_1.default.join(modelsDir, model.name.replace('/', path_1.default.sep));
+    if (fs_1.default.existsSync(modelDir)) {
+        transformers_1.env.allowRemoteModels = false;
+        process.stderr.write(`[embedder] Using local model at ${modelDir}\n`);
+    }
+    else {
+        transformers_1.env.allowRemoteModels = true;
+        process.stderr.write(`[embedder] Downloading model ${model.name} to ${modelsDir}...\n`);
+    }
+    const pipeOpts = {};
+    if (model.dtype)
+        pipeOpts.dtype = model.dtype;
+    const pipe = await (0, transformers_1.pipeline)('feature-extraction', model.name, pipeOpts);
+    _pipeCache.set(cacheKey, pipe);
+    _models.set(name, { pipe, model, embedding, maxChars, cache: new LruCache(cacheSize) });
+    process.stderr.write(`[embedder] Model "${name}" ready\n`);
+}
+// ---------------------------------------------------------------------------
+// Remote embedding HTTP client
+// ---------------------------------------------------------------------------
+const REMOTE_MAX_RETRIES = 3;
+const REMOTE_BASE_DELAY_MS = 200;
+async function remoteEmbed(url, texts, apiKey) {
+    const headers = { 'Content-Type': 'application/json' };
+    if (apiKey)
+        headers['Authorization'] = `Bearer ${apiKey}`;
+    const body = JSON.stringify({ texts });
+    for (let attempt = 0; attempt < REMOTE_MAX_RETRIES; attempt++) {
+        let resp;
+        try {
+            resp = await fetch(url, { method: 'POST', headers, body });
+        }
+        catch (err) {
+            // Network error — retry
+            if (attempt < REMOTE_MAX_RETRIES - 1) {
+                const delay = REMOTE_BASE_DELAY_MS * 2 ** attempt;
+                await new Promise(r => setTimeout(r, delay));
+                continue;
+            }
+            throw new Error(`Remote embed network error after ${REMOTE_MAX_RETRIES} attempts: ${err}`);
+        }
+        if (resp.ok) {
+            const data = await resp.json();
+            return data.embeddings;
+        }
+        // Client errors (4xx) — don't retry
+        if (resp.status < 500) {
+            const respBody = (await resp.text()).slice(0, 500);
+            throw new Error(`Remote embed failed (${resp.status}): ${respBody}`);
+        }
+        // Server errors (5xx) — retry
+        if (attempt < REMOTE_MAX_RETRIES - 1) {
+            const delay = REMOTE_BASE_DELAY_MS * 2 ** attempt;
+            await new Promise(r => setTimeout(r, delay));
+            continue;
+        }
+        const respBody = (await resp.text()).slice(0, 500);
+        throw new Error(`Remote embed failed after ${REMOTE_MAX_RETRIES} attempts (${resp.status}): ${respBody}`);
+    }
+    throw new Error('Remote embed: unreachable');
+}
+function getEntry(modelName) {
+    const entry = _models.get(modelName);
+    if (!entry)
+        throw new Error(`Model "${modelName}" not loaded. Call loadModel() first.`);
+    return entry;
+}
+/** Embed a document (indexing). Applies documentPrefix and configured pooling. */
+async function embed(title, content, modelName = 'default') {
+    const entry = getEntry(modelName);
+    const raw = `${title}\n${content}`;
+    const text = `${entry.model.documentPrefix}${raw}`.slice(0, entry.maxChars);
+    const cached = entry.cache.get(text);
+    if (cached)
+        return cached;
+    let vec;
+    if (entry.remote) {
+        [vec] = await remoteEmbed(entry.remote.url, [text], entry.remote.apiKey);
+    }
+    else {
+        const tensor = await entry.pipe._call(text, { pooling: entry.model.pooling, normalize: entry.model.normalize });
+        vec = Array.from(tensor.data);
+    }
+    entry.cache.set(text, vec);
+    return vec;
+}
+/** Embed a search query. Applies queryPrefix and configured pooling. */
+async function embedQuery(query, modelName = 'default') {
+    const entry = getEntry(modelName);
+    const text = `${entry.model.queryPrefix}${query}`.slice(0, entry.maxChars);
+    const cached = entry.cache.get(text);
+    if (cached)
+        return cached;
+    let vec;
+    if (entry.remote) {
+        [vec] = await remoteEmbed(entry.remote.url, [text], entry.remote.apiKey);
+    }
+    else {
+        const tensor = await entry.pipe._call(text, { pooling: entry.model.pooling, normalize: entry.model.normalize });
+        vec = Array.from(tensor.data);
+    }
+    entry.cache.set(text, vec);
+    return vec;
+}
+/** Batch-embed documents (indexing). Applies documentPrefix and configured pooling. */
+async function embedBatch(inputs, modelName = 'default') {
+    const entry = getEntry(modelName);
+    if (inputs.length === 0)
+        return [];
+    if (inputs.length === 1)
+        return [await embed(inputs[0].title, inputs[0].content, modelName)];
+    const texts = inputs.map(({ title, content }) => `${entry.model.documentPrefix}${title}\n${content}`.slice(0, entry.maxChars));
+    // Check cache: split into hits and misses
+    const result = texts.map(t => entry.cache.get(t) ?? null);
+    const missIndices = result.map((v, i) => v === null ? i : -1).filter(i => i >= 0);
+    if (missIndices.length === 0)
+        return result;
+    const missTexts = missIndices.map(i => texts[i]);
+    let missVecs;
+    if (entry.remote) {
+        missVecs = await remoteEmbed(entry.remote.url, missTexts, entry.remote.apiKey);
+    }
+    else {
+        missVecs = [];
+        const batchSize = entry.embedding.batchSize;
+        for (let start = 0; start < missTexts.length; start += batchSize) {
+            const chunk = missTexts.slice(start, start + batchSize);
+            const tensor = await entry.pipe._call(chunk, { pooling: entry.model.pooling, normalize: entry.model.normalize });
+            const dim = tensor.dims[1];
+            const data = tensor.data;
+            for (let i = 0; i < chunk.length; i++) {
+                missVecs.push(Array.from(data.slice(i * dim, (i + 1) * dim)));
+            }
+        }
+    }
+    // Fill results and populate cache
+    for (let j = 0; j < missIndices.length; j++) {
+        const idx = missIndices[j];
+        result[idx] = missVecs[j];
+        entry.cache.set(texts[idx], missVecs[j]);
+    }
+    return result;
+}
+function resetEmbedder() {
+    _models.clear();
+    _pipeCache.clear();
+}
+// Vectors are L2-normalized → dot product = cosine similarity
+function cosineSimilarity(a, b) {
+    if (a.length !== b.length)
+        return 0;
+    let dot = 0;
+    for (let i = 0; i < a.length; i++)
+        dot += a[i] * b[i];
+    return dot;
+}

package/dist/lib/events-log.js

@@ -0,0 +1,401 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.appendEvent = appendEvent;
+exports.readEvents = readEvents;
+exports.replayNoteEvents = replayNoteEvents;
+exports.replayTaskEvents = replayTaskEvents;
+exports.replaySkillEvents = replaySkillEvents;
+exports.ensureGitignore = ensureGitignore;
+exports.ensureGitattributes = ensureGitattributes;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+// ---------------------------------------------------------------------------
+// Core functions
+// ---------------------------------------------------------------------------
+/** Append a single event as a JSON line to the events.jsonl file. */
+function appendEvent(eventsPath, event) {
+    try {
+        const line = JSON.stringify({ ts: new Date().toISOString(), ...event }) + '\n';
+        fs.appendFileSync(eventsPath, line, 'utf-8');
+    }
+    catch (err) {
+        process.stderr.write(`[events-log] failed to append event: ${err}\n`);
+    }
+}
+/** Read and parse all events from a JSONL file. Invalid lines are skipped. */
+function readEvents(eventsPath) {
+    try {
+        if (!fs.existsSync(eventsPath))
+            return [];
+        const content = fs.readFileSync(eventsPath, 'utf-8');
+        const events = [];
+        for (const line of content.split('\n')) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            try {
+                events.push(JSON.parse(trimmed));
+            }
+            catch { /* skip invalid lines */ }
+        }
+        return events;
+    }
+    catch {
+        return [];
+    }
+}
+/** Sort events by timestamp (ISO strings are lexicographically sortable). */
+function sortByTs(events) {
+    return [...events].sort((a, b) => (a.ts < b.ts ? -1 : a.ts > b.ts ? 1 : 0));
+}
+function isoToMs(value) {
+    if (value == null)
+        return null;
+    const d = new Date(value);
+    return isNaN(d.getTime()) ? null : d.getTime();
+}
+// ---------------------------------------------------------------------------
+// Replay functions
+// ---------------------------------------------------------------------------
+/**
+ * Replay note events + content to reconstruct a ParsedNoteFile.
+ * Returns null if no 'created' event is found.
+ */
+function replayNoteEvents(events, content) {
+    const sorted = sortByTs(events);
+    const created = sorted.find(e => e.op === 'created');
+    if (!created)
+        return null;
+    let title = created.title;
+    let tags = created.tags ?? [];
+    let updatedBy = null;
+    const relations = [];
+    const attachments = [];
+    for (const ev of sorted) {
+        if (ev.op === 'update') {
+            const u = ev;
+            if (typeof u.title === 'string')
+                title = u.title;
+            if (Array.isArray(u.tags))
+                tags = u.tags;
+            if (typeof u.by === 'string')
+                updatedBy = u.by;
+        }
+        else if (ev.op === 'relation') {
+            const r = ev;
+            const key = `${r.to}:${r.kind}:${r.graph ?? ''}`;
+            if (r.action === 'add') {
+                if (!relations.some(x => `${x.to}:${x.kind}:${x.graph ?? ''}` === key)) {
+                    const entry = { to: r.to, kind: r.kind };
+                    if (r.graph)
+                        entry.graph = r.graph;
+                    relations.push(entry);
+                }
+            }
+            else {
+                const idx = relations.findIndex(x => `${x.to}:${x.kind}:${x.graph ?? ''}` === key);
+                if (idx !== -1)
+                    relations.splice(idx, 1);
+            }
+        }
+        else if (ev.op === 'attachment') {
+            const a = ev;
+            if (a.action === 'add') {
+                if (!attachments.some(x => x.filename === a.file)) {
+                    attachments.push({ filename: a.file, mimeType: 'application/octet-stream', size: 0, addedAt: 0 });
+                }
+            }
+            else {
+                const idx = attachments.findIndex(x => x.filename === a.file);
+                if (idx !== -1)
+                    attachments.splice(idx, 1);
+            }
+        }
+    }
+    const version = sorted.length;
+    // updatedAt = ts of last event; createdAt from created event
+    const lastEvent = sorted[sorted.length - 1];
+    const updatedAt = isoToMs(lastEvent?.ts);
+    const createdAt = isoToMs(created.ts) ?? created.createdAt;
+    return {
+        id: created.id,
+        title,
+        content,
+        tags,
+        createdAt: created.createdAt ?? createdAt,
+        updatedAt: updatedAt ?? created.createdAt,
+        version,
+        createdBy: created.createdBy ?? null,
+        updatedBy,
+        relations,
+        attachments,
+    };
+}
+/**
+ * Replay task events + description to reconstruct a ParsedTaskFile.
+ * Returns null if no 'created' event is found.
+ */
+function replayTaskEvents(events, description) {
+    const sorted = sortByTs(events);
+    const created = sorted.find(e => e.op === 'created');
+    if (!created)
+        return null;
+    let title = created.title;
+    let status = created.status;
+    let priority = created.priority;
+    let tags = created.tags ?? [];
+    let dueDate = created.dueDate;
+    let estimate = created.estimate;
+    let completedAt = created.completedAt;
+    let updatedBy = null;
+    const relations = [];
+    const attachments = [];
+    for (const ev of sorted) {
+        if (ev.op === 'update') {
+            const u = ev;
+            if (typeof u.title === 'string')
+                title = u.title;
+            if (typeof u.status === 'string')
+                status = u.status;
+            if (typeof u.priority === 'string')
+                priority = u.priority;
+            if (Array.isArray(u.tags))
+                tags = u.tags;
+            if ('dueDate' in u)
+                dueDate = u.dueDate;
+            if ('estimate' in u)
+                estimate = u.estimate;
+            if ('completedAt' in u)
+                completedAt = u.completedAt;
+            if (typeof u.by === 'string')
+                updatedBy = u.by;
+        }
+        else if (ev.op === 'relation') {
+            const r = ev;
+            const key = `${r.to}:${r.kind}:${r.graph ?? ''}`;
+            if (r.action === 'add') {
+                if (!relations.some(x => `${x.to}:${x.kind}:${x.graph ?? ''}` === key)) {
+                    const entry = { to: r.to, kind: r.kind };
+                    if (r.graph)
+                        entry.graph = r.graph;
+                    relations.push(entry);
+                }
+            }
+            else {
+                const idx = relations.findIndex(x => `${x.to}:${x.kind}:${x.graph ?? ''}` === key);
+                if (idx !== -1)
+                    relations.splice(idx, 1);
+            }
+        }
+        else if (ev.op === 'attachment') {
+            const a = ev;
+            if (a.action === 'add') {
+                if (!attachments.some(x => x.filename === a.file)) {
+                    attachments.push({ filename: a.file, mimeType: 'application/octet-stream', size: 0, addedAt: 0 });
+                }
+            }
+            else {
+                const idx = attachments.findIndex(x => x.filename === a.file);
+                if (idx !== -1)
+                    attachments.splice(idx, 1);
+            }
+        }
+    }
+    const version = sorted.length;
+    const lastEvent = sorted[sorted.length - 1];
+    const updatedAt = isoToMs(lastEvent?.ts);
+    return {
+        id: created.id,
+        title,
+        description,
+        status,
+        priority,
+        tags,
+        dueDate,
+        estimate,
+        completedAt,
+        assignee: null,
+        createdAt: created.createdAt,
+        updatedAt: updatedAt ?? created.createdAt,
+        version,
+        createdBy: created.createdBy ?? null,
+        updatedBy,
+        relations,
+        attachments,
+    };
+}
+/**
+ * Replay skill events + description to reconstruct a ParsedSkillFile.
+ * Returns null if no 'created' event is found.
+ */
+function replaySkillEvents(events, description) {
+    const sorted = sortByTs(events);
+    const created = sorted.find(e => e.op === 'created');
+    if (!created)
+        return null;
+    let title = created.title;
+    let tags = created.tags ?? [];
+    let steps = created.steps ?? [];
+    let triggers = created.triggers ?? [];
+    let inputHints = created.inputHints ?? [];
+    let filePatterns = created.filePatterns ?? [];
+    let source = created.source;
+    let confidence = created.confidence;
+    let usageCount = created.usageCount;
+    let lastUsedAt = created.lastUsedAt;
+    let updatedBy = null;
+    const relations = [];
+    const attachments = [];
+    for (const ev of sorted) {
+        if (ev.op === 'update') {
+            const u = ev;
+            if (typeof u.title === 'string')
+                title = u.title;
+            if (Array.isArray(u.tags))
+                tags = u.tags;
+            if (Array.isArray(u.steps))
+                steps = u.steps;
+            if (Array.isArray(u.triggers))
+                triggers = u.triggers;
+            if (Array.isArray(u.inputHints))
+                inputHints = u.inputHints;
+            if (Array.isArray(u.filePatterns))
+                filePatterns = u.filePatterns;
+            if (typeof u.source === 'string')
+                source = u.source;
+            if (typeof u.confidence === 'number')
+                confidence = u.confidence;
+            if (typeof u.usageCount === 'number')
+                usageCount = u.usageCount;
+            if ('lastUsedAt' in u)
+                lastUsedAt = u.lastUsedAt;
+            if (typeof u.by === 'string')
+                updatedBy = u.by;
+        }
+        else if (ev.op === 'relation') {
+            const r = ev;
+            const key = `${r.to}:${r.kind}:${r.graph ?? ''}`;
+            if (r.action === 'add') {
+                if (!relations.some(x => `${x.to}:${x.kind}:${x.graph ?? ''}` === key)) {
+                    const entry = { to: r.to, kind: r.kind };
+                    if (r.graph)
+                        entry.graph = r.graph;
+                    relations.push(entry);
+                }
+            }
+            else {
+                const idx = relations.findIndex(x => `${x.to}:${x.kind}:${x.graph ?? ''}` === key);
+                if (idx !== -1)
+                    relations.splice(idx, 1);
+            }
+        }
+        else if (ev.op === 'attachment') {
+            const a = ev;
+            if (a.action === 'add') {
+                if (!attachments.some(x => x.filename === a.file)) {
+                    attachments.push({ filename: a.file, mimeType: 'application/octet-stream', size: 0, addedAt: 0 });
+                }
+            }
+            else {
+                const idx = attachments.findIndex(x => x.filename === a.file);
+                if (idx !== -1)
+                    attachments.splice(idx, 1);
+            }
+        }
+    }
+    const version = sorted.length;
+    const lastEvent = sorted[sorted.length - 1];
+    const updatedAt = isoToMs(lastEvent?.ts);
+    return {
+        id: created.id,
+        title,
+        description,
+        steps,
+        triggers,
+        inputHints,
+        filePatterns,
+        tags,
+        source,
+        confidence,
+        usageCount,
+        lastUsedAt,
+        createdAt: created.createdAt,
+        updatedAt: updatedAt ?? created.createdAt,
+        version,
+        createdBy: created.createdBy ?? null,
+        updatedBy,
+        relations,
+        attachments,
+    };
+}
+// ---------------------------------------------------------------------------
+// Git helpers
+// ---------------------------------------------------------------------------
+/** Ensure a .gitignore file in parentDir contains the given pattern line. */
+function ensureGitignore(parentDir, pattern) {
+    try {
+        const gitignorePath = path.join(parentDir, '.gitignore');
+        let content = '';
+        if (fs.existsSync(gitignorePath)) {
+            content = fs.readFileSync(gitignorePath, 'utf-8');
+        }
+        if (!content.split('\n').some(l => l.trim() === pattern)) {
+            fs.mkdirSync(parentDir, { recursive: true });
+            fs.writeFileSync(gitignorePath, content + (content && !content.endsWith('\n') ? '\n' : '') + pattern + '\n', 'utf-8');
+        }
+    }
+    catch (err) {
+        process.stderr.write(`[events-log] failed to write .gitignore: ${err}\n`);
+    }
+}
+/** Ensure a .gitattributes file in entityParentDir contains the merge=union line for events.jsonl. */
+function ensureGitattributes(entityParentDir) {
+    const pattern = '*/events.jsonl merge=union';
+    try {
+        const gitattrsPath = path.join(entityParentDir, '.gitattributes');
+        let content = '';
+        if (fs.existsSync(gitattrsPath)) {
+            content = fs.readFileSync(gitattrsPath, 'utf-8');
+        }
+        if (!content.split('\n').some(l => l.trim() === pattern)) {
+            fs.mkdirSync(entityParentDir, { recursive: true });
+            fs.writeFileSync(gitattrsPath, content + (content && !content.endsWith('\n') ? '\n' : '') + pattern + '\n', 'utf-8');
+        }
+    }
+    catch (err) {
+        process.stderr.write(`[events-log] failed to write .gitattributes: ${err}\n`);
+    }
+}