@monoes/monograph 1.1.0 → 1.2.1

package/dist/src/search/hybrid-query.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Hybrid BM25 + vector search with Reciprocal Rank Fusion.
+ *
+ * When MONOGRAPH_EMBEDDINGS=true (or an embedder is provided), the query is
+ * embedded and cosine similarity is computed in JavaScript against all stored
+ * vectors.  Both result lists are merged via RRF(K=60).
+ *
+ * If embeddings are unavailable (table empty, env not set, no embedder),
+ * the function falls back to BM25 only — same behaviour as before.
+ */
+import type Database from 'better-sqlite3';
+import type { EmbedderFn } from './embedder.js';
+import { type RankedResult } from './rrf.js';
+export interface HybridQueryOptions {
+    limit?: number;
+    label?: string;
+    /** Explicit embedder — overrides MONOGRAPH_EMBEDDINGS env check */
+    embedder?: EmbedderFn;
+}
+export interface HybridResult extends RankedResult {
+    id: string;
+    name: string;
+    normLabel: string;
+    filePath: string | null;
+    label: string;
+    score: number;
+    /** First line of the symbol in its source file (1-based, null if unknown). */
+    startLine?: number | null;
+    /** Last line of the symbol in its source file (1-based, null if unknown). */
+    endLine?: number | null;
+}
+/**
+ * Run a hybrid BM25 + cosine search.
+ *
+ * Falls back to BM25-only when:
+ *  - MONOGRAPH_EMBEDDINGS env var is not 'true' AND no explicit embedder is given
+ *  - The embeddings table is empty
+ *  - Embedding the query string fails
+ */
+export declare function hybridQuery(db: Database.Database, query: string, options?: HybridQueryOptions): Promise<HybridResult[]>;
+//# sourceMappingURL=hybrid-query.d.ts.map

package/dist/src/search/hybrid-query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hybrid-query.d.ts","sourceRoot":"","sources":["../../../src/search/hybrid-query.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAC3C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAc,KAAK,YAAY,EAAE,MAAM,UAAU,CAAC;AAMzD,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,QAAQ,CAAC,EAAE,UAAU,CAAC;CACvB;AAED,MAAM,WAAW,YAAa,SAAQ,YAAY;IAChD,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,8EAA8E;IAC9E,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,6EAA6E;IAC7E,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAC/B,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,YAAY,EAAE,CAAC,CA2GzB"}

package/dist/src/search/hybrid-query.js

@@ -0,0 +1,120 @@
+/**
+ * Hybrid BM25 + vector search with Reciprocal Rank Fusion.
+ *
+ * When MONOGRAPH_EMBEDDINGS=true (or an embedder is provided), the query is
+ * embedded and cosine similarity is computed in JavaScript against all stored
+ * vectors.  Both result lists are merged via RRF(K=60).
+ *
+ * If embeddings are unavailable (table empty, env not set, no embedder),
+ * the function falls back to BM25 only — same behaviour as before.
+ */
+import { mergeRanks } from './rrf.js';
+import { getAllEmbeddings, countEmbeddings } from '../storage/embedding-store.js';
+import { embedText } from './embedder.js';
+import { ftsSearch } from '../storage/fts-store.js';
+import { normalizeSearchTerm } from './diacritic.js';
+/**
+ * Run a hybrid BM25 + cosine search.
+ *
+ * Falls back to BM25-only when:
+ *  - MONOGRAPH_EMBEDDINGS env var is not 'true' AND no explicit embedder is given
+ *  - The embeddings table is empty
+ *  - Embedding the query string fails
+ */
+export async function hybridQuery(db, query, options = {}) {
+    const { limit = 20, label, embedder } = options;
+    // Normalize the query for text-based lookups (strip diacritics, lowercase, trim)
+    const normalizedQuery = normalizeSearchTerm(query);
+    // ── BM25 via FTS5 ──────────────────────────────────────────────────────────
+    const bm25Limit = 50;
+    const bm25Raw = ftsSearch(db, normalizedQuery, bm25Limit, label);
+    const bm25Results = bm25Raw.map((r) => ({
+        id: r.id,
+        name: r.name,
+        normLabel: r.normLabel,
+        filePath: r.filePath,
+        label: r.label,
+        score: r.rank,
+        startLine: r.startLine,
+        endLine: r.endLine,
+    }));
+    // ── Decide whether to add vector results ──────────────────────────────────
+    const embeddingsEnabled = embedder !== undefined || process.env['MONOGRAPH_EMBEDDINGS'] === 'true';
+    if (!embeddingsEnabled)
+        return sliceHybrid(bm25Results, limit);
+    const embeddingCount = countEmbeddings(db);
+    if (embeddingCount === 0)
+        return sliceHybrid(bm25Results, limit);
+    // ── Embed the query ────────────────────────────────────────────────────────
+    let queryVec;
+    try {
+        const fn = embedder ?? (await import('./embedder.js').then((m) => m.getEmbedder()));
+        queryVec = await embedText(normalizedQuery, fn);
+    }
+    catch {
+        // Embedding failed — degrade gracefully to BM25
+        return sliceHybrid(bm25Results, limit);
+    }
+    // ── Cosine similarity against stored vectors ──────────────────────────────
+    const allVecs = getAllEmbeddings(db);
+    const vectorScored = [];
+    for (const [nodeId, vec] of allVecs) {
+        const sim = dotProduct(queryVec, vec); // valid because vectors are L2-normalised
+        vectorScored.push({ id: nodeId, cosine: sim });
+    }
+    // Sort descending by cosine similarity
+    vectorScored.sort((a, b) => b.cosine - a.cosine);
+    // Build vector RankedResult list with node metadata joined from BM25 cache
+    const bm25ById = new Map(bm25Results.map((r) => [r.id, r]));
+    const vectorResults = vectorScored.map((vs) => {
+        const meta = bm25ById.get(vs.id);
+        return {
+            id: vs.id,
+            name: meta?.name ?? '',
+            normLabel: meta?.normLabel ?? '',
+            filePath: meta?.filePath ?? null,
+            label: meta?.label ?? '',
+            score: vs.cosine,
+        };
+    });
+    // ── Merge via RRF ──────────────────────────────────────────────────────────
+    const merged = mergeRanks(bm25Results, vectorResults);
+    // Enrich nodes not in bm25 cache with a DB lookup
+    const enrichable = merged;
+    const unknownIds = enrichable
+        .filter((r) => !r.name)
+        .map((r) => r.id);
+    if (unknownIds.length > 0) {
+        const placeholders = unknownIds.map(() => '?').join(',');
+        const rows = db
+            .prepare(`SELECT id, name, norm_label, file_path, label, start_line, end_line FROM nodes WHERE id IN (${placeholders})`)
+            .all(...unknownIds);
+        const rowMap = new Map(rows.map((r) => [r.id, r]));
+        for (const item of enrichable) {
+            if (!item.name) {
+                const row = rowMap.get(item.id);
+                if (row) {
+                    item.name = row.name;
+                    item.normLabel = row.norm_label;
+                    item.filePath = row.file_path;
+                    item.label = row.label;
+                    item.startLine = row.start_line;
+                    item.endLine = row.end_line;
+                }
+            }
+        }
+    }
+    return sliceHybrid(merged, limit);
+}
+// ── Helpers ───────────────────────────────────────────────────────────────────
+function sliceHybrid(results, limit) {
+    return results.slice(0, limit);
+}
+function dotProduct(a, b) {
+    let sum = 0;
+    const len = Math.min(a.length, b.length);
+    for (let i = 0; i < len; i++)
+        sum += a[i] * b[i];
+    return sum;
+}
+//# sourceMappingURL=hybrid-query.js.map

package/dist/src/search/hybrid-query.js.map

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

package/dist/src/search/rrf.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Reciprocal Rank Fusion (RRF)
+ *
+ * Merges two ranked result lists using the formula:
+ *   score(d) = sum over each list of: 1 / (K + rank_of_d_in_list)
+ *
+ * where rank is 1-based.
+ *
+ * Reference: Cormack, Clarke & Buettcher (SIGIR 2009).
+ */
+export interface RankedResult {
+    id: string;
+    score: number;
+    [key: string]: unknown;
+}
+/**
+ * Merge two ranked lists via RRF and return results sorted by fused score descending.
+ *
+ * @param list1 - First ranked list (ordered by relevance, best first)
+ * @param list2 - Second ranked list (ordered by relevance, best first)
+ * @param K     - RRF constant (default 60, per the original paper)
+ */
+export declare function mergeRanks(list1: RankedResult[], list2: RankedResult[], K?: number): RankedResult[];
+//# sourceMappingURL=rrf.d.ts.map

package/dist/src/search/rrf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rrf.d.ts","sourceRoot":"","sources":["../../../src/search/rrf.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,YAAY,EAAE,EACrB,KAAK,EAAE,YAAY,EAAE,EACrB,CAAC,SAAK,GACL,YAAY,EAAE,CAsBhB"}

package/dist/src/search/rrf.js

@@ -0,0 +1,39 @@
+/**
+ * Reciprocal Rank Fusion (RRF)
+ *
+ * Merges two ranked result lists using the formula:
+ *   score(d) = sum over each list of: 1 / (K + rank_of_d_in_list)
+ *
+ * where rank is 1-based.
+ *
+ * Reference: Cormack, Clarke & Buettcher (SIGIR 2009).
+ */
+/**
+ * Merge two ranked lists via RRF and return results sorted by fused score descending.
+ *
+ * @param list1 - First ranked list (ordered by relevance, best first)
+ * @param list2 - Second ranked list (ordered by relevance, best first)
+ * @param K     - RRF constant (default 60, per the original paper)
+ */
+export function mergeRanks(list1, list2, K = 60) {
+    const scoreMap = new Map();
+    const addList = (list) => {
+        list.forEach((item, idx) => {
+            const rank = idx + 1; // 1-based
+            const contribution = 1 / (K + rank);
+            const existing = scoreMap.get(item.id);
+            if (existing) {
+                existing.rrf += contribution;
+            }
+            else {
+                scoreMap.set(item.id, { rrf: contribution, payload: item });
+            }
+        });
+    };
+    addList(list1);
+    addList(list2);
+    return [...scoreMap.values()]
+        .sort((a, b) => b.rrf - a.rrf)
+        .map(({ rrf, payload }) => ({ ...payload, score: rrf }));
+}
+//# sourceMappingURL=rrf.js.map

package/dist/src/search/rrf.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rrf.js","sourceRoot":"","sources":["../../../src/search/rrf.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAQH;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CACxB,KAAqB,EACrB,KAAqB,EACrB,CAAC,GAAG,EAAE;IAEN,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAkD,CAAC;IAE3E,MAAM,OAAO,GAAG,CAAC,IAAoB,EAAE,EAAE;QACvC,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE;YACzB,MAAM,IAAI,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,UAAU;YAChC,MAAM,YAAY,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;YACpC,MAAM,QAAQ,GAAG,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACvC,IAAI,QAAQ,EAAE,CAAC;gBACb,QAAQ,CAAC,GAAG,IAAI,YAAY,CAAC;YAC/B,CAAC;iBAAM,CAAC;gBACN,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,GAAG,EAAE,YAAY,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;YAC9D,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC,CAAC;IAEF,OAAO,CAAC,KAAK,CAAC,CAAC;IACf,OAAO,CAAC,KAAK,CAAC,CAAC;IAEf,OAAO,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC;SAC1B,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC;SAC7B,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;AAC7D,CAAC"}

package/dist/src/security/safe-fetch.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Returns true if the given URL resolves to a private, loopback, or cloud
+ * metadata address that should be blocked to prevent SSRF attacks.
+ */
+export declare function isPrivateUrl(rawUrl: string): boolean;
+/**
+ * Validates that a URL is safe to fetch: must use http/https and must not
+ * resolve to a private or reserved address.
+ * @throws {Error} if the URL is invalid, uses an unsupported scheme, or is private
+ */
+export declare function validateUrl(rawUrl: string): void;
+/**
+ * Fetches the content of a URL after validating it is safe (not private/internal).
+ * Enforces a maximum response size and request timeout.
+ *
+ * @param rawUrl - The URL to fetch
+ * @param opts.maxBytes - Maximum allowed response size in bytes (default 10 MB)
+ * @param opts.timeoutMs - Request timeout in milliseconds (default 10 000)
+ * @returns The response body as a string
+ * @throws {Error} if the URL is unsafe, the request fails, or the response is too large
+ */
+export declare function safeFetch(rawUrl: string, opts?: {
+    maxBytes?: number;
+    timeoutMs?: number;
+}): Promise<string>;
+//# sourceMappingURL=safe-fetch.d.ts.map

package/dist/src/security/safe-fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-fetch.d.ts","sourceRoot":"","sources":["../../../src/security/safe-fetch.ts"],"names":[],"mappings":"AAoBA;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAWpD;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAahD;AAED;;;;;;;;;GASG;AACH,wBAAsB,SAAS,CAC7B,MAAM,EAAE,MAAM,EACd,IAAI,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GACnD,OAAO,CAAC,MAAM,CAAC,CA0CjB"}

package/dist/src/security/safe-fetch.js

@@ -0,0 +1,112 @@
+const PRIVATE_IP_PATTERNS = [
+    /^127\./,
+    /^10\./,
+    /^192\.168\./,
+    /^172\.(1[6-9]|2\d|3[01])\./,
+    /^169\.254\./,
+    /^::1$|\[::1\]/,
+    /^fc00:|^\[fc00:/i,
+    /^fe80:|^\[fe80:/i,
+    // IPv4-mapped IPv6 (e.g. ::ffff:192.168.1.1) — covers private ranges via mapped form
+    /^::ffff:/i,
+    /^\[::ffff:/i,
+];
+const CLOUD_METADATA_HOSTS = new Set([
+    'metadata.google.internal',
+    'metadata.goog',
+    '169.254.169.254',
+]);
+/**
+ * Returns true if the given URL resolves to a private, loopback, or cloud
+ * metadata address that should be blocked to prevent SSRF attacks.
+ */
+export function isPrivateUrl(rawUrl) {
+    let url;
+    try {
+        url = new URL(rawUrl);
+    }
+    catch {
+        return false;
+    }
+    const host = url.hostname;
+    if (host === 'localhost')
+        return true;
+    if (CLOUD_METADATA_HOSTS.has(host))
+        return true;
+    return PRIVATE_IP_PATTERNS.some(p => p.test(host));
+}
+/**
+ * Validates that a URL is safe to fetch: must use http/https and must not
+ * resolve to a private or reserved address.
+ * @throws {Error} if the URL is invalid, uses an unsupported scheme, or is private
+ */
+export function validateUrl(rawUrl) {
+    let url;
+    try {
+        url = new URL(rawUrl);
+    }
+    catch {
+        throw new Error(`Invalid URL: ${rawUrl}`);
+    }
+    if (!['http:', 'https:'].includes(url.protocol)) {
+        throw new Error(`Unsupported scheme: ${url.protocol}`);
+    }
+    if (isPrivateUrl(rawUrl)) {
+        throw new Error(`URL resolves to private/reserved address: ${url.hostname}`);
+    }
+}
+/**
+ * Fetches the content of a URL after validating it is safe (not private/internal).
+ * Enforces a maximum response size and request timeout.
+ *
+ * @param rawUrl - The URL to fetch
+ * @param opts.maxBytes - Maximum allowed response size in bytes (default 10 MB)
+ * @param opts.timeoutMs - Request timeout in milliseconds (default 10 000)
+ * @returns The response body as a string
+ * @throws {Error} if the URL is unsafe, the request fails, or the response is too large
+ */
+export async function safeFetch(rawUrl, opts = {}) {
+    validateUrl(rawUrl);
+    const { maxBytes = 10 * 1024 * 1024, timeoutMs = 10_000 } = opts;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetch(rawUrl, { signal: controller.signal });
+        if (!res.ok)
+            throw new Error(`HTTP ${res.status}: ${rawUrl}`);
+        // Stream the body incrementally so we can enforce maxBytes before
+        // the full response is loaded into memory (prevents memory exhaustion
+        // on large/malicious payloads).
+        if (!res.body) {
+            throw new Error(`Response body is missing: ${rawUrl}`);
+        }
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        const chunks = [];
+        let totalBytes = 0;
+        try {
+            while (true) {
+                const { value, done } = await reader.read();
+                if (done)
+                    break;
+                if (value) {
+                    totalBytes += value.byteLength;
+                    if (totalBytes > maxBytes) {
+                        throw new Error(`Response exceeds ${maxBytes} bytes: ${rawUrl}`);
+                    }
+                    chunks.push(decoder.decode(value, { stream: true }));
+                }
+            }
+            // Flush any remaining bytes held in the decoder
+            chunks.push(decoder.decode());
+        }
+        finally {
+            reader.releaseLock();
+        }
+        return chunks.join('');
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=safe-fetch.js.map

package/dist/src/security/safe-fetch.js.map

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

package/dist/src/security/sensitive-files.d.ts

@@ -0,0 +1,2 @@
+export declare function isSensitiveFile(filePath: string): boolean;
+//# sourceMappingURL=sensitive-files.d.ts.map

package/dist/src/security/sensitive-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sensitive-files.d.ts","sourceRoot":"","sources":["../../../src/security/sensitive-files.ts"],"names":[],"mappings":"AAoBA,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAGzD"}

package/dist/src/security/sensitive-files.js

@@ -0,0 +1,23 @@
+import { basename as pathBasename } from 'path';
+const SENSITIVE_PATTERNS = [
+    /^\.env(\.|$)/i,
+    /^\.netrc$/i,
+    /\baws_credentials\b/i,
+    /\bcredentials?\b.*\.(json|yaml|yml|toml|ini|cfg)$/i,
+    /\bsecrets?\b.*\.(json|yaml|yml|toml|ini|cfg)$/i,
+    /\bsecret[_-]?key\b/i,
+    /\bapi[_-]?key\b.*\.(json|txt)$/i,
+    /\bpasswd\b/i,
+    /\bpassword[s]?\b.*\.(txt|json|yaml|yml)$/i,
+    /\btoken\b.*\.(txt|json|env)$/i,
+    /\b(id_rsa|id_dsa|id_ecdsa|id_ed25519)(\.pub)?$/i,
+    /\.(pem|key|pfx|p12|p8|pkcs8)$/i,
+    /\bservice[_-]?account\b.*\.json$/i,
+    /\bkeystore\b/i,
+    /\bvault[_-]?token\b/i,
+];
+export function isSensitiveFile(filePath) {
+    const base = pathBasename(filePath);
+    return SENSITIVE_PATTERNS.some(p => p.test(base) || p.test(filePath));
+}
+//# sourceMappingURL=sensitive-files.js.map

package/dist/src/security/sensitive-files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sensitive-files.js","sourceRoot":"","sources":["../../../src/security/sensitive-files.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,IAAI,YAAY,EAAE,MAAM,MAAM,CAAC;AAEhD,MAAM,kBAAkB,GAAa;IACnC,eAAe;IACf,YAAY;IACZ,sBAAsB;IACtB,oDAAoD;IACpD,gDAAgD;IAChD,qBAAqB;IACrB,iCAAiC;IACjC,aAAa;IACb,2CAA2C;IAC3C,+BAA+B;IAC/B,iDAAiD;IACjD,gCAAgC;IAChC,mCAAmC;IACnC,eAAe;IACf,sBAAsB;CACvB,CAAC;AAEF,MAAM,UAAU,eAAe,CAAC,QAAgB;IAC9C,MAAM,IAAI,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;IACpC,OAAO,kBAAkB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;AACxE,CAAC"}

package/dist/src/skills/platform-skills.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Multi-platform IDE Skill File Installer
+ *
+ * Generates and installs per-community skill files for various IDE/platform
+ * targets (Claude, Cursor, VS Code, Zed, Codex, Gemini, Aider, Copilot, Kiro).
+ * Each platform gets one file per community describing exported symbols from
+ * that community.
+ */
+export type SkillPlatform = 'claude' | 'cursor' | 'vscode' | 'zed' | 'codex' | 'gemini' | 'aider' | 'copilot' | 'kiro';
+export interface PlatformSkillConfig {
+    platform: SkillPlatform;
+    /** Override output directory. Default: platform-specific. */
+    outputDir?: string;
+}
+export interface SkillInstallResult {
+    platform: SkillPlatform;
+    filesWritten: string[];
+    outputDir: string;
+}
+export interface SyncSkillInstallResult {
+    filesWritten: string[];
+}
+export declare const SUPPORTED_PLATFORMS: string[];
+/**
+ * Synchronously install a skill file for a specific platform into the repo.
+ * Returns { filesWritten } where filesWritten contains absolute paths to written files.
+ *
+ * New single-file platforms (codex, gemini, aider, copilot, kiro) always write
+ * one file regardless of communities. Existing multi-file platforms write one
+ * file per community entry.
+ */
+export declare function installPlatformSkill(repoPath: string, platform: string, communities: Array<{
+    name: string;
+    symbols: string[];
+} | string>): SyncSkillInstallResult;
+/**
+ * Install skill files for a specific platform into the repo.
+ *
+ * Platform output directories (relative to repoPath):
+ *   claude  → .claude/skills/
+ *   cursor  → .cursor/rules/
+ *   vscode  → .vscode/
+ *   zed     → .zed/
+ *
+ * Each platform gets one file per community. File names use the community name.
+ * Format:
+ *   claude/cursor/zed → <communityName>-skills.md
+ *   vscode            → <communityName>-skills.json (VS Code snippets format)
+ */
+export declare function installSkillsForPlatform(repoPath: string, communities: Array<{
+    name: string;
+    symbols: string[];
+}>, config: PlatformSkillConfig): Promise<SkillInstallResult>;
+//# sourceMappingURL=platform-skills.d.ts.map

package/dist/src/skills/platform-skills.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-skills.d.ts","sourceRoot":"","sources":["../../../src/skills/platform-skills.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAUH,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAEvH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,aAAa,CAAC;IACxB,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,aAAa,CAAC;IACxB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,sBAAsB;IACrC,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAMD,eAAO,MAAM,mBAAmB,EAAE,MAAM,EAUvC,CAAC;AAkCF;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG,MAAM,CAAC,GAC/D,sBAAsB,CA0CxB;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,wBAAwB,CAC5C,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,EACvD,MAAM,EAAE,mBAAmB,GAC1B,OAAO,CAAC,kBAAkB,CAAC,CA6B7B"}