@know-graph/core 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KnowGraph Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,47 @@
+# @know-graph/core
+
+Core library for [KnowGraph](https://github.com/idosams/know-know) — parsers, indexer, query engine, and type definitions.
+
+## Installation
+
+```bash
+npm install @know-graph/core
+```
+
+## What's Included
+
+- **Parsers** — Language-specific parsers for Python, TypeScript/JavaScript, and a generic comment parser
+- **Metadata Extractor** — Extracts and validates `@knowgraph` YAML metadata from code comments
+- **Indexer** — SQLite-backed indexer with FTS5 full-text search
+- **Query Engine** — Search and filter indexed entities by text, owner, tags, type, and status
+- **Types** — Zod schemas and TypeScript types for entities, metadata, and manifests
+
+## Usage
+
+```typescript
+import {
+  createDefaultRegistry,
+  createIndexer,
+  createQueryEngine,
+} from '@know-graph/core';
+
+// Parse files
+const registry = createDefaultRegistry();
+const results = registry.parse(fileContent, 'src/auth.ts');
+
+// Index a project
+const indexer = createIndexer({ dbPath: '.knowgraph/knowgraph.db' });
+await indexer.indexDirectory('./src');
+
+// Query the index
+const engine = createQueryEngine('.knowgraph/knowgraph.db');
+const entities = engine.search('authentication', { owner: 'auth-team' });
+```
+
+## Documentation
+
+See the [main repository](https://github.com/idosams/know-know) for full documentation, annotation format, and examples.
+
+## License
+
+MIT

package/dist/connectors/cache.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @knowgraph
+ * type: module
+ * description: In-memory TTL cache for connector API responses to reduce external calls
+ * owner: knowgraph-core
+ * status: experimental
+ * tags: [connector, cache, ttl, performance]
+ * context:
+ *   business_goal: Reduce API calls to external services by caching responses
+ *   domain: connectors
+ */
+export interface ConnectorCache<T = unknown> {
+    get(key: string): T | undefined;
+    set(key: string, value: T): void;
+    has(key: string): boolean;
+    delete(key: string): boolean;
+    clear(): void;
+    size(): number;
+}
+export interface CacheOptions {
+    readonly ttlMs: number;
+    readonly maxEntries?: number;
+}
+export declare function createCache<T = unknown>(options: CacheOptions): ConnectorCache<T>;
+//# sourceMappingURL=cache.d.ts.map

package/dist/connectors/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/connectors/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAOH,MAAM,WAAW,cAAc,CAAC,CAAC,GAAG,OAAO;IACzC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAAC;IAChC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IACjC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1B,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC7B,KAAK,IAAI,IAAI,CAAC;IACd,IAAI,IAAI,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,wBAAgB,WAAW,CAAC,CAAC,GAAG,OAAO,EAAE,OAAO,EAAE,YAAY,GAAG,cAAc,CAAC,CAAC,CAAC,CAkEjF"}

package/dist/connectors/cache.js

@@ -0,0 +1,73 @@
+/**
+ * @knowgraph
+ * type: module
+ * description: In-memory TTL cache for connector API responses to reduce external calls
+ * owner: knowgraph-core
+ * status: experimental
+ * tags: [connector, cache, ttl, performance]
+ * context:
+ *   business_goal: Reduce API calls to external services by caching responses
+ *   domain: connectors
+ */
+export function createCache(options) {
+    const { ttlMs, maxEntries = 1000 } = options;
+    const entries = new Map();
+    function isExpired(entry) {
+        return Date.now() >= entry.expiresAt;
+    }
+    function evictExpired() {
+        for (const [key, entry] of entries) {
+            if (isExpired(entry)) {
+                entries.delete(key);
+            }
+        }
+    }
+    function evictOldest() {
+        if (entries.size <= maxEntries)
+            return;
+        const firstKey = entries.keys().next().value;
+        if (firstKey !== undefined) {
+            entries.delete(firstKey);
+        }
+    }
+    return {
+        get(key) {
+            const entry = entries.get(key);
+            if (!entry)
+                return undefined;
+            if (isExpired(entry)) {
+                entries.delete(key);
+                return undefined;
+            }
+            return entry.value;
+        },
+        set(key, value) {
+            entries.set(key, {
+                value,
+                expiresAt: Date.now() + ttlMs,
+            });
+            evictOldest();
+        },
+        has(key) {
+            const entry = entries.get(key);
+            if (!entry)
+                return false;
+            if (isExpired(entry)) {
+                entries.delete(key);
+                return false;
+            }
+            return true;
+        },
+        delete(key) {
+            return entries.delete(key);
+        },
+        clear() {
+            entries.clear();
+        },
+        size() {
+            evictExpired();
+            return entries.size;
+        },
+    };
+}
+//# sourceMappingURL=cache.js.map

package/dist/connectors/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/connectors/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAqBH,MAAM,UAAU,WAAW,CAAc,OAAqB;IAC5D,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,IAAI,EAAE,GAAG,OAAO,CAAC;IAC7C,MAAM,OAAO,GAAG,IAAI,GAAG,EAAyB,CAAC;IAEjD,SAAS,SAAS,CAAC,KAAoB;QACrC,OAAO,IAAI,CAAC,GAAG,EAAE,IAAI,KAAK,CAAC,SAAS,CAAC;IACvC,CAAC;IAED,SAAS,YAAY;QACnB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,OAAO,EAAE,CAAC;YACnC,IAAI,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;gBACrB,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACtB,CAAC;QACH,CAAC;IACH,CAAC;IAED,SAAS,WAAW;QAClB,IAAI,OAAO,CAAC,IAAI,IAAI,UAAU;YAAE,OAAO;QACvC,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC;QAC7C,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC3B,CAAC;IACH,CAAC;IAED,OAAO;QACL,GAAG,CAAC,GAAW;YACb,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAC/B,IAAI,CAAC,KAAK;gBAAE,OAAO,SAAS,CAAC;YAC7B,IAAI,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;gBACrB,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBACpB,OAAO,SAAS,CAAC;YACnB,CAAC;YACD,OAAO,KAAK,CAAC,KAAK,CAAC;QACrB,CAAC;QAED,GAAG,CAAC,GAAW,EAAE,KAAQ;YACvB,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE;gBACf,KAAK;gBACL,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK;aAC9B,CAAC,CAAC;YACH,WAAW,EAAE,CAAC;QAChB,CAAC;QAED,GAAG,CAAC,GAAW;YACb,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAC/B,IAAI,CAAC,KAAK;gBAAE,OAAO,KAAK,CAAC;YACzB,IAAI,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;gBACrB,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBACpB,OAAO,KAAK,CAAC;YACf,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC;QAED,MAAM,CAAC,GAAW;YAChB,OAAO,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC7B,CAAC;QAED,KAAK;YACH,OAAO,CAAC,KAAK,EAAE,CAAC;QAClB,CAAC;QAED,IAAI;YACF,YAAY,EAAE,CAAC;YACf,OAAO,OAAO,CAAC,IAAI,CAAC;QACtB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/connectors/index.d.ts

@@ -0,0 +1,12 @@
+export type { Connector, ConnectorRegistry, ConnectorSyncOptions, ConnectorSyncResult, ConnectorError, ConnectorValidationResult, ConnectorValidationIssue, SyncAllOptions, } from './types.js';
+export { ConnectorValidationIssueSchema, ConnectorValidationResultSchema, ConnectorErrorSchema, ConnectorSyncResultSchema, } from './types.js';
+export { createConnectorRegistry, createDefaultConnectorRegistry, } from './registry.js';
+export type { ConnectorCache, CacheOptions } from './cache.js';
+export { createCache } from './cache.js';
+export type { RateLimiter, RateLimiterOptions } from './rate-limiter.js';
+export { createRateLimiter } from './rate-limiter.js';
+export type { NotionPage, NotionApiClient } from './notion-connector.js';
+export { createNotionConnector, isNotionUrl, extractNotionPageId, } from './notion-connector.js';
+export type { JiraIssue, JiraApiClient } from './jira-connector.js';
+export { createJiraConnector, isJiraUrl, extractJiraIssueKey, } from './jira-connector.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/connectors/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/connectors/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,SAAS,EACT,iBAAiB,EACjB,oBAAoB,EACpB,mBAAmB,EACnB,cAAc,EACd,yBAAyB,EACzB,wBAAwB,EACxB,cAAc,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,8BAA8B,EAC9B,+BAA+B,EAC/B,oBAAoB,EACpB,yBAAyB,GAC1B,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,uBAAuB,EACvB,8BAA8B,GAC/B,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/D,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,YAAY,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACzE,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACzE,OAAO,EACL,qBAAqB,EACrB,WAAW,EACX,mBAAmB,GACpB,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpE,OAAO,EACL,mBAAmB,EACnB,SAAS,EACT,mBAAmB,GACpB,MAAM,qBAAqB,CAAC"}

package/dist/connectors/index.js

@@ -0,0 +1,7 @@
+export { ConnectorValidationIssueSchema, ConnectorValidationResultSchema, ConnectorErrorSchema, ConnectorSyncResultSchema, } from './types.js';
+export { createConnectorRegistry, createDefaultConnectorRegistry, } from './registry.js';
+export { createCache } from './cache.js';
+export { createRateLimiter } from './rate-limiter.js';
+export { createNotionConnector, isNotionUrl, extractNotionPageId, } from './notion-connector.js';
+export { createJiraConnector, isJiraUrl, extractJiraIssueKey, } from './jira-connector.js';
+//# sourceMappingURL=index.js.map

package/dist/connectors/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/connectors/index.ts"],"names":[],"mappings":"AAUA,OAAO,EACL,8BAA8B,EAC9B,+BAA+B,EAC/B,oBAAoB,EACpB,yBAAyB,GAC1B,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,uBAAuB,EACvB,8BAA8B,GAC/B,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzC,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEtD,OAAO,EACL,qBAAqB,EACrB,WAAW,EACX,mBAAmB,GACpB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,mBAAmB,EACnB,SAAS,EACT,mBAAmB,GACpB,MAAM,qBAAqB,CAAC"}

package/dist/connectors/jira-connector.d.ts

@@ -0,0 +1,26 @@
+import type { Connector } from './types.js';
+import type { ConnectorCache } from './cache.js';
+import type { RateLimiter } from './rate-limiter.js';
+export interface JiraIssue {
+    readonly key: string;
+    readonly url: string;
+    readonly summary: string;
+    readonly status: string;
+    readonly assignee?: string;
+    readonly priority?: string;
+    readonly lastUpdated: string;
+}
+export interface JiraApiClient {
+    getIssue(issueKey: string): Promise<JiraIssue>;
+    searchIssues(jql: string): Promise<readonly JiraIssue[]>;
+}
+export declare function isJiraUrl(url: string): boolean;
+export declare function extractJiraIssueKey(url: string): string | undefined;
+export declare function createJiraApiClient(baseUrl: string, apiKey: string, email?: string): JiraApiClient;
+export interface JiraConnectorDeps {
+    readonly apiClient?: JiraApiClient;
+    readonly cache?: ConnectorCache<JiraIssue>;
+    readonly rateLimiter?: RateLimiter;
+}
+export declare function createJiraConnector(deps?: JiraConnectorDeps): Connector;
+//# sourceMappingURL=jira-connector.d.ts.map

package/dist/connectors/jira-connector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jira-connector.d.ts","sourceRoot":"","sources":["../../src/connectors/jira-connector.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EACV,SAAS,EAKV,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAMrD,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IAC/C,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,SAAS,EAAE,CAAC,CAAC;CAC1D;AAQD,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE9C;AAED,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGnE;AAID,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,KAAK,CAAC,EAAE,MAAM,GACb,aAAa,CAoEf;AAID,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,SAAS,CAAC,EAAE,aAAa,CAAC;IACnC,QAAQ,CAAC,KAAK,CAAC,EAAE,cAAc,CAAC,SAAS,CAAC,CAAC;IAC3C,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC;CACpC;AAsFD,wBAAgB,mBAAmB,CAAC,IAAI,GAAE,iBAAsB,GAAG,SAAS,CAmI3E"}

package/dist/connectors/jira-connector.js

@@ -0,0 +1,234 @@
+import { createCache } from './cache.js';
+import { createRateLimiter } from './rate-limiter.js';
+// --- Jira URL Utilities ---
+const JIRA_ISSUE_PATTERN = /\/browse\/([A-Z][A-Z0-9_]+-\d+)/;
+const JIRA_URL_PATTERN = /^https?:\/\/[^/]+\.(atlassian\.net|jira\.[^/]+)\/browse\//;
+export function isJiraUrl(url) {
+    return JIRA_URL_PATTERN.test(url);
+}
+export function extractJiraIssueKey(url) {
+    const match = url.match(JIRA_ISSUE_PATTERN);
+    return match?.[1];
+}
+// --- Fetch-based Jira API Client ---
+export function createJiraApiClient(baseUrl, apiKey, email) {
+    const apiBase = baseUrl.replace(/\/$/, '');
+    const authHeader = email
+        ? `Basic ${Buffer.from(`${email}:${apiKey}`).toString('base64')}`
+        : `Bearer ${apiKey}`;
+    const headers = {
+        Authorization: authHeader,
+        Accept: 'application/json',
+        'Content-Type': 'application/json',
+    };
+    function parseIssue(data, issueBaseUrl) {
+        const fields = data.fields;
+        const status = fields.status;
+        const assignee = fields.assignee;
+        const priority = fields.priority;
+        return {
+            key: data.key,
+            url: `${issueBaseUrl}/browse/${data.key}`,
+            summary: fields.summary ?? '',
+            status: status?.name ?? 'Unknown',
+            assignee: assignee?.displayName,
+            priority: priority?.name,
+            lastUpdated: fields.updated ?? '',
+        };
+    }
+    return {
+        async getIssue(issueKey) {
+            const response = await fetch(`${apiBase}/rest/api/3/issue/${issueKey}?fields=summary,status,assignee,priority,updated`, { headers });
+            if (!response.ok) {
+                throw new Error(`Jira API error: ${response.status} ${response.statusText}`);
+            }
+            const data = (await response.json());
+            return parseIssue(data, apiBase);
+        },
+        async searchIssues(jql) {
+            const response = await fetch(`${apiBase}/rest/api/3/search`, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify({
+                    jql,
+                    maxResults: 10,
+                    fields: ['summary', 'status', 'assignee', 'priority', 'updated'],
+                }),
+            });
+            if (!response.ok) {
+                throw new Error(`Jira API error: ${response.status} ${response.statusText}`);
+            }
+            const data = (await response.json());
+            return data.issues.map((issue) => parseIssue(issue, apiBase));
+        },
+    };
+}
+function getAllEntities(dbManager) {
+    const rows = dbManager.db
+        .prepare('SELECT * FROM entities ORDER BY name ASC')
+        .all();
+    return rows.map((row) => {
+        const tags = dbManager.db
+            .prepare('SELECT tag FROM tags WHERE entity_id = ?')
+            .all(row.id).map((t) => t.tag);
+        const links = dbManager.db
+            .prepare('SELECT link_type, url, title FROM links WHERE entity_id = ?')
+            .all(row.id).map((l) => ({
+            type: l.link_type,
+            url: l.url,
+            title: l.title ?? undefined,
+        }));
+        return {
+            id: row.id,
+            filePath: row.file_path,
+            name: row.name,
+            entityType: row.entity_type,
+            description: row.description,
+            rawDocstring: row.raw_docstring,
+            signature: row.signature,
+            parent: row.parent,
+            language: row.language,
+            line: row.line,
+            column: row.column_num,
+            owner: row.owner,
+            status: row.status,
+            metadata: JSON.parse(row.metadata_json),
+            tags,
+            links,
+            fileHash: row.file_hash,
+            createdAt: row.created_at,
+            updatedAt: row.updated_at,
+        };
+    });
+}
+function filterEntities(entities, filter) {
+    if (!filter)
+        return entities;
+    return entities.filter((entity) => {
+        if (filter.owner && entity.owner !== filter.owner)
+            return false;
+        if (filter.tags && filter.tags.length > 0) {
+            const hasMatchingTag = filter.tags.some((t) => entity.tags.includes(t));
+            if (!hasMatchingTag)
+                return false;
+        }
+        return true;
+    });
+}
+export function createJiraConnector(deps = {}) {
+    const cache = deps.cache ?? createCache({ ttlMs: 5 * 60 * 1000 });
+    const rateLimiter = deps.rateLimiter ??
+        createRateLimiter({
+            maxTokens: 10,
+            refillRate: 10,
+            refillIntervalMs: 1000,
+        });
+    return {
+        name: 'jira',
+        supportedLinkTypes: ['jira'],
+        validate(config) {
+            const issues = [];
+            if (!config.base_url) {
+                issues.push({
+                    field: 'base_url',
+                    message: 'base_url is required (Jira instance URL)',
+                });
+            }
+            if (!config.api_key_env) {
+                issues.push({
+                    field: 'api_key_env',
+                    message: 'api_key_env is required (env variable name for Jira API key)',
+                });
+            }
+            else if (!process.env[config.api_key_env]) {
+                issues.push({
+                    field: 'api_key_env',
+                    message: `Environment variable "${config.api_key_env}" is not set`,
+                });
+            }
+            return { valid: issues.length === 0, issues };
+        },
+        async sync(options) {
+            const startTime = Date.now();
+            const { dbManager, config, entityFilter, dryRun } = options;
+            const errors = [];
+            const linksAdded = 0;
+            let linksUpdated = 0;
+            const apiKey = config.api_key_env
+                ? process.env[config.api_key_env]
+                : undefined;
+            if (!apiKey || !config.base_url) {
+                return {
+                    connector: 'jira',
+                    entitiesProcessed: 0,
+                    linksAdded: 0,
+                    linksUpdated: 0,
+                    errors: [
+                        {
+                            entityId: '',
+                            message: 'Jira API key or base URL not configured',
+                            code: 'AUTH_MISSING',
+                        },
+                    ],
+                    duration: Date.now() - startTime,
+                };
+            }
+            const apiClient = deps.apiClient ?? createJiraApiClient(config.base_url, apiKey);
+            const allEntities = getAllEntities(dbManager);
+            const entities = filterEntities(allEntities, entityFilter);
+            for (const entity of entities) {
+                const jiraLinks = entity.links.filter((l) => l.type === 'jira' || (l.url && isJiraUrl(l.url)));
+                for (const link of jiraLinks) {
+                    const issueKey = extractJiraIssueKey(link.url);
+                    if (!issueKey)
+                        continue;
+                    try {
+                        const cached = cache.get(issueKey);
+                        let issue;
+                        if (cached) {
+                            issue = cached;
+                        }
+                        else {
+                            await rateLimiter.acquire();
+                            issue = await apiClient.getIssue(issueKey);
+                            cache.set(issueKey, issue);
+                        }
+                        const title = `[${issue.status}] ${issue.summary}`;
+                        if (!dryRun) {
+                            dbManager.db
+                                .prepare('DELETE FROM links WHERE entity_id = ? AND url = ?')
+                                .run(entity.id, link.url);
+                            dbManager.insertLinks(entity.id, [
+                                {
+                                    type: 'jira',
+                                    url: link.url,
+                                    title,
+                                },
+                            ]);
+                            linksUpdated++;
+                        }
+                        else {
+                            linksUpdated++;
+                        }
+                    }
+                    catch (err) {
+                        errors.push({
+                            entityId: entity.id,
+                            message: `Failed to fetch Jira issue ${issueKey}: ${err instanceof Error ? err.message : String(err)}`,
+                            code: 'FETCH_ERROR',
+                        });
+                    }
+                }
+            }
+            return {
+                connector: 'jira',
+                entitiesProcessed: entities.length,
+                linksAdded,
+                linksUpdated,
+                errors,
+                duration: Date.now() - startTime,
+            };
+        },
+    };
+}
+//# sourceMappingURL=jira-connector.js.map

package/dist/connectors/jira-connector.js.map

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

package/dist/connectors/notion-connector.d.ts

@@ -0,0 +1,24 @@
+import type { Connector } from './types.js';
+import type { ConnectorCache } from './cache.js';
+import type { RateLimiter } from './rate-limiter.js';
+export interface NotionPage {
+    readonly id: string;
+    readonly url: string;
+    readonly title: string;
+    readonly lastEditedTime: string;
+    readonly status?: string;
+}
+export interface NotionApiClient {
+    getPage(pageId: string): Promise<NotionPage>;
+    searchPages(query: string): Promise<readonly NotionPage[]>;
+}
+export declare function isNotionUrl(url: string): boolean;
+export declare function extractNotionPageId(url: string): string | undefined;
+export declare function createNotionApiClient(apiKey: string): NotionApiClient;
+export interface NotionConnectorDeps {
+    readonly apiClient?: NotionApiClient;
+    readonly cache?: ConnectorCache<NotionPage>;
+    readonly rateLimiter?: RateLimiter;
+}
+export declare function createNotionConnector(deps?: NotionConnectorDeps): Connector;
+//# sourceMappingURL=notion-connector.d.ts.map

package/dist/connectors/notion-connector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notion-connector.d.ts","sourceRoot":"","sources":["../../src/connectors/notion-connector.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EACV,SAAS,EAKV,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAMrD,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAC7C,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,UAAU,EAAE,CAAC,CAAC;CAC5D;AAOD,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEhD;AAED,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAInE;AAID,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,CAiFrE;AAID,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,SAAS,CAAC,EAAE,eAAe,CAAC;IACrC,QAAQ,CAAC,KAAK,CAAC,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;IAC5C,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC;CACpC;AAsFD,wBAAgB,qBAAqB,CACnC,IAAI,GAAE,mBAAwB,GAC7B,SAAS,CAsHX"}