@datasynx/agentic-ai-cartography 1.1.1 → 2.0.0

package/dist/index.d.ts

@@ -1,8 +1,24 @@
+import Database from 'better-sqlite3';
 import { z } from 'zod';
-import { HookCallback } from '@anthropic-ai/claude-agent-sdk';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import http from 'node:http';
+import { McpServerConfig, HookCallback } from '@anthropic-ai/claude-agent-sdk';
 
 declare const NODE_TYPES: readonly ["host", "database_server", "database", "table", "web_service", "api_endpoint", "cache_server", "message_broker", "queue", "topic", "container", "pod", "k8s_cluster", "config_file", "saas_tool", "unknown"];
 type NodeType = typeof NODE_TYPES[number];
+/**
+ * Semantic groupings of node types — the single source of truth shared by the MCP
+ * resource layer (services/databases) and the exporters (layer assignment). Each
+ * node type belongs to at most one group; anything ungrouped is treated as "other".
+ */
+declare const NODE_TYPE_GROUPS: {
+    readonly saas: readonly ["saas_tool"];
+    readonly web: readonly ["web_service", "api_endpoint"];
+    readonly data: readonly ["database_server", "database", "table", "cache_server"];
+    readonly messaging: readonly ["message_broker", "queue", "topic"];
+    readonly infra: readonly ["host", "container", "pod", "k8s_cluster"];
+    readonly config: readonly ["config_file"];
+};
 declare const EDGE_RELATIONSHIPS: readonly ["connects_to", "reads_from", "writes_to", "calls", "contains", "depends_on"];
 type EdgeRelationship = typeof EDGE_RELATIONSHIPS[number];
 declare const NodeSchema: z.ZodObject<{
@@ -130,6 +146,33 @@ interface ConnectionRow extends Connection {
     sessionId: string;
     createdAt: string;
 }
+/** Aggregate, low-token index of a topology — used for progressive disclosure. */
+interface GraphSummary {
+    sessionId: string;
+    totals: {
+        nodes: number;
+        edges: number;
+    };
+    nodesByType: Record<string, number>;
+    nodesByDomain: Record<string, number>;
+    edgesByRelationship: Record<string, number>;
+    topConnected: Array<{
+        id: string;
+        name: string;
+        type: string;
+        degree: number;
+    }>;
+}
+/** Result of a recursive dependency traversal. */
+interface TraversalResult {
+    root?: NodeRow;
+    direction: 'downstream' | 'upstream' | 'both';
+    maxDepth: number;
+    nodes: Array<NodeRow & {
+        depth: number;
+    }>;
+    edges: EdgeRow[];
+}
 interface EventRow {
     id: string;
     sessionId: string;
@@ -170,6 +213,12 @@ declare class CartographyDB {
     constructor(dbPath: string);
     private migrate;
     close(): void;
+    /**
+     * Advanced: the underlying better-sqlite3 connection. Used by the optional
+     * semantic-search layer to load the `sqlite-vec` extension and manage its
+     * virtual table. Prefer the typed methods above for everything else.
+     */
+    rawConnection(): Database.Database;
     createSession(mode: 'discover', config: CartographyConfig): string;
     endSession(id: string): void;
     getSession(id: string): SessionRow | undefined;
@@ -177,11 +226,18 @@ declare class CartographyDB {
     getSessions(): SessionRow[];
     private mapSession;
     upsertNode(sessionId: string, node: DiscoveryNode, depth?: number): void;
-    getNodes(sessionId: string): NodeRow[];
+    getNodes(sessionId: string, opts?: {
+        limit?: number;
+        offset?: number;
+    }): NodeRow[];
+    getNodeCount(sessionId: string): number;
     private mapNode;
     deleteNode(sessionId: string, nodeId: string): void;
     insertEdge(sessionId: string, edge: DiscoveryEdge): void;
-    getEdges(sessionId: string): EdgeRow[];
+    getEdges(sessionId: string, opts?: {
+        limit?: number;
+        offset?: number;
+    }): EdgeRow[];
     insertEvent(sessionId: string, event: Pick<EventRow, 'eventType' | 'process' | 'pid' | 'target' | 'targetType' | 'port'>, taskId?: string): void;
     getEvents(sessionId: string, since?: string): EventRow[];
     startTask(sessionId: string, description?: string): string;
@@ -205,6 +261,31 @@ declare class CartographyDB {
      * Prune sessions older than the given ISO date string. Returns count of deleted sessions.
      */
     pruneSessions(olderThan: string): number;
+    /** Fetch a single node by id within a session. */
+    getNode(sessionId: string, nodeId: string): NodeRow | undefined;
+    /** Batch-fetch nodes by id, keyed for O(1) lookup. Chunked to stay under SQLite's bind-variable limit. */
+    getNodesByIds(sessionId: string, ids: readonly string[]): Map<string, NodeRow>;
+    /** Fetch all nodes of one or more types. */
+    getNodesByType(sessionId: string, types: readonly string[]): NodeRow[];
+    /**
+     * Lexical search over node id, name, domain, sub-domain and tags.
+     * Case-insensitive substring match — the deterministic fallback for semantic search.
+     */
+    searchNodes(sessionId: string, query: string, opts?: {
+        types?: readonly string[];
+        limit?: number;
+    }): NodeRow[];
+    /**
+     * Traverse the dependency graph from a node using a recursive CTE with a
+     * path-based cycle guard. `downstream` follows source→target (what the node
+     * depends on / points to); `upstream` follows target→source (what depends on it).
+     */
+    getDependencies(sessionId: string, nodeId: string, opts?: {
+        direction?: 'downstream' | 'upstream' | 'both';
+        maxDepth?: number;
+    }): TraversalResult;
+    /** Lightweight aggregate index of the whole topology — the progressive-disclosure summary. */
+    getGraphSummary(sessionId: string): GraphSummary;
     getStats(sessionId: string): {
         nodes: number;
         edges: number;
@@ -213,16 +294,291 @@ declare class CartographyDB {
     };
 }
 
-type McpServer = any;
+/**
+ * The Cartography MCP server — the package's primary, LLM-agnostic interface.
+ *
+ * It exposes the discovered infrastructure topology as Model Context Protocol
+ * **Resources** (read-only context, progressive disclosure), a small set of query
+ * **Tools** (parameterized lookups), and reusable **Prompts**. Any MCP host —
+ * Claude Code, Cursor, Cline, Windsurf, the Vercel AI SDK, LangGraph — can drive
+ * it; the package never needs to know which model is in use.
+ */
+
+/** A pluggable search backend; defaults to lexical search, can be upgraded to semantic. */
+type SearchFn = (db: CartographyDB, sessionId: string, query: string, opts: {
+    types?: readonly string[];
+    limit: number;
+}) => Promise<Array<{
+    node: NodeRow;
+    score?: number;
+}>>;
+/** A pluggable discovery backend invoked by the `run_discovery` tool. */
+type DiscoveryFn = (db: CartographyDB, sessionId: string, opts: {
+    hint?: string;
+}) => Promise<{
+    nodes: number;
+    edges: number;
+}>;
+interface CreateMcpServerOptions {
+    /** Database instance. If omitted, one is opened at `config.dbPath`. */
+    db?: CartographyDB;
+    /** Path to the SQLite catalog (used when `db` is not provided). */
+    dbPath?: string;
+    /** Session to serve: a session id, or `'latest'` (default) for the newest discovery. */
+    session?: string | 'latest';
+    /** Semantic/lexical search backend. Defaults to lexical `searchNodes`. */
+    search?: SearchFn;
+    /** Discovery backend for `run_discovery`/`refresh`. Optional. */
+    discovery?: DiscoveryFn;
+}
+/**
+ * Build a fully-configured Cartography MCP server. Call `.connect(transport)` to run it.
+ */
+declare function createMcpServer(opts?: CreateMcpServerOptions): McpServer;
+
+/**
+ * Transport bindings for the Cartography MCP server.
+ *
+ * - **stdio**: the local-first default — zero network, every client supports it.
+ * - **Streamable HTTP**: a single `/mcp` endpoint for team/remote use, bound to
+ *   localhost with DNS-rebinding protection. The deprecated SSE transport is not used.
+ */
+
+/** Connect a server over stdio (resolves when the transport closes). */
+declare function runStdio(server: McpServer): Promise<void>;
+interface HttpOptions {
+    port?: number;
+    host?: string;
+    /** Extra allowed Host headers (defaults to localhost:port variants). */
+    allowedHosts?: string[];
+    /** Allowed Origin headers (defaults to none → same-origin only). */
+    allowedOrigins?: string[];
+}
+/**
+ * Start a Streamable HTTP server. A fresh MCP server instance is created per
+ * session via `factory`, so multiple clients can connect concurrently.
+ */
+declare function runHttp(factory: () => McpServer, opts?: HttpOptions): Promise<http.Server>;
+
+/**
+ * Cross-platform utilities for Linux, macOS, and Windows.
+ * Centralizes all OS-specific logic so scanning tools work everywhere.
+ */
+type Platform = 'linux' | 'darwin' | 'win32';
+declare function safeEnv(): NodeJS.ProcessEnv;
+
+/**
+ * Scanner plugin contract.
+ *
+ * A scanner detects whether it applies to the current machine, then produces a
+ * read-only {@link ScanResult}: deterministic nodes/edges where the data is
+ * structured enough, plus an optional raw report for an LLM to classify further.
+ *
+ * Modeled on Steampipe plugins / Backstage processors: new sources can be added
+ * (in-tree or via `@datasynx/scanner-*` packages) and registered without forking
+ * the core. Each scanner declares the commands it needs, feeding the safety layer.
+ */
+
+interface ScanContext {
+    /** Optional focus hint from the caller (e.g. tool names to look for). */
+    hint?: string;
+    /** The current platform. */
+    platform: Platform;
+    /** Allowlist-gated command runner (returns '' on error/blocked). */
+    run: (cmd: string, opts?: {
+        timeout?: number;
+        env?: NodeJS.ProcessEnv;
+    }) => string;
+}
+interface ScanResult {
+    /** Deterministically classified nodes. */
+    nodes: DiscoveryNode[];
+    /** Deterministically classified edges. */
+    edges: DiscoveryEdge[];
+    /** Optional raw text report for LLM-driven classification. */
+    report?: string;
+}
+interface Scanner {
+    /** Stable id, e.g. "bookmarks", "installed-apps", "cloud-aws". */
+    id: string;
+    /** Human-readable title. */
+    title: string;
+    /** Platforms this scanner supports, or 'all'. */
+    platforms: Platform[] | 'all';
+    /** Read-only commands this scanner may run (declared for the safety layer/docs). */
+    allowedCommands?: string[];
+    /** Cheap check whether the scanner applies here (e.g. a CLI is installed). */
+    detect(ctx: ScanContext): boolean | Promise<boolean>;
+    /** Perform the read-only scan. */
+    scan(ctx: ScanContext): Promise<ScanResult>;
+}
+/** A typed registry of scanners with lazy, platform-aware selection. */
+declare class ScannerRegistry {
+    private scanners;
+    register(scanner: Scanner): this;
+    get(id: string): Scanner | undefined;
+    list(): Scanner[];
+    /** Scanners whose `platforms` include the given platform. */
+    forPlatform(platform: Platform): Scanner[];
+}
+
+declare const bookmarksScanner: Scanner;
+
+declare const installedAppsScanner: Scanner;
+
+/** Extract distinct listening port numbers from ss/lsof/PowerShell output. */
+declare function extractListeningPorts(raw: string): number[];
+declare const portsScanner: Scanner;
+
+/** A registry pre-loaded with the built-in deterministic scanners. */
+declare function defaultRegistry(): ScannerRegistry;
+
+/**
+ * Deterministic, LLM-free local discovery.
+ *
+ * Runs every applicable scanner from a {@link ScannerRegistry}, deduplicates and
+ * persists the resulting nodes/edges, and returns counts. This is what powers the
+ * MCP `run_discovery` tool without requiring any model — the host LLM can then
+ * enrich the catalog via the read tools. (The Claude-driven loop in agent.ts
+ * remains available as the optional, richer turnkey path.)
+ */
+
+interface LocalDiscoveryOptions {
+    hint?: string;
+    registry?: ScannerRegistry;
+    /** Called after each scanner with a short progress line. */
+    onProgress?: (line: string) => void;
+}
+declare function runLocalDiscovery(db: CartographyDB, sessionId: string, opts?: LocalDiscoveryOptions): Promise<{
+    nodes: number;
+    edges: number;
+    scanners: string[];
+}>;
+/** Adapter matching the MCP `DiscoveryFn` signature. */
+declare function localDiscoveryFn(registry?: ScannerRegistry): (db: CartographyDB, sessionId: string, opts: {
+    hint?: string;
+}) => Promise<{
+    nodes: number;
+    edges: number;
+}>;
+
+/**
+ * Embedding providers for semantic search.
+ *
+ * The default provider runs a small sentence-transformer locally via
+ * `@huggingface/transformers` (no API key, offline after first download), keeping
+ * the package LLM-agnostic. Everything is a lazy import so installs that never use
+ * semantic search pay no cost and need no native model.
+ */
+/** Produces fixed-dimension embeddings for a batch of texts. */
+interface EmbeddingProvider {
+    readonly id: string;
+    readonly dimensions: number;
+    embed(texts: string[]): Promise<Float32Array[]>;
+}
+/**
+ * Local sentence-transformer embedder (Xenova/all-MiniLM-L6-v2, 384 dims).
+ * Returns `undefined` if `@huggingface/transformers` is not installed or the
+ * model cannot be loaded, so callers can fall back to lexical search.
+ */
+declare function createLocalEmbedder(model?: string): Promise<EmbeddingProvider | undefined>;
+/**
+ * A deterministic, dependency-free hashing embedder (bag-of-character-ngrams).
+ * Not as good as a transformer, but offline, instant, and useful as a fallback
+ * and for tests. Produces L2-normalized vectors.
+ */
+declare function createHashEmbedder(dimensions?: number): EmbeddingProvider;
+
+/**
+ * Vector store backed by `sqlite-vec`. Stores one embedding per node in a `vec0`
+ * virtual table living inside the same SQLite catalog, with incremental indexing
+ * (content-hashed) so re-runs only embed what changed.
+ */
+
+declare class VectorStore {
+    private db;
+    private embedder;
+    private loaded;
+    constructor(db: CartographyDB, embedder: EmbeddingProvider);
+    /** Load sqlite-vec and ensure the schema exists. Returns false if unavailable. */
+    init(): Promise<boolean>;
+    /** Incrementally embed and index any new/changed nodes for a session. */
+    index(sessionId: string): Promise<{
+        embedded: number;
+        total: number;
+    }>;
+    /** k-nearest-neighbour search within a session. Returns node ids + distances. */
+    search(sessionId: string, query: string, k: number): Promise<Array<{
+        nodeId: string;
+        distance: number;
+    }>>;
+}
+
+/**
+ * Semantic search backend for the MCP server. Wraps a {@link VectorStore} and
+ * degrades gracefully to lexical search when embeddings/sqlite-vec are unavailable
+ * or return nothing.
+ */
+
+/**
+ * Build a {@link SearchFn} that prefers semantic (vector) search and falls back to
+ * lexical. Pass an explicit embedder, or let it lazily load the local transformer
+ * (returns a lexical-only function if none is available).
+ */
+declare function createSemanticSearch(db: CartographyDB, embedder?: EmbeddingProvider): Promise<SearchFn>;
+
+/**
+ * Circuit breaker for sequential CLI scans.
+ * After `threshold` consecutive failures, remaining commands are skipped.
+ */
+declare function createScanRunner(runFn: (cmd: string, opts?: {
+    timeout?: number;
+    env?: NodeJS.ProcessEnv;
+}) => string, opts?: {
+    timeout?: number;
+    env?: NodeJS.ProcessEnv;
+    threshold?: number;
+}): (cmd: string) => string;
 interface CartographyToolsOptions {
     /** Called when the agent needs a human answer. Return the user's response. */
     onAskUser?: (question: string, context?: string) => Promise<string>;
 }
 declare function stripSensitive(target: string): string;
-declare function createCartographyTools(db: CartographyDB, sessionId: string, opts?: CartographyToolsOptions): Promise<McpServer>;
+declare function createCartographyTools(db: CartographyDB, sessionId: string, opts?: CartographyToolsOptions): Promise<McpServerConfig>;
 
 declare const safetyHook: HookCallback;
 
+/**
+ * Read-only command policy — a strict allowlist.
+ *
+ * Unlike a denylist (which is inherently leaky — novel destructive commands slip
+ * through), this module permits only commands that are known to be read-only and
+ * rejects everything else. It is the authoritative safety boundary for every
+ * command the package spawns, independent of which agent or LLM is driving.
+ *
+ * The check is shell-aware: it splits a command line into segments on the control
+ * operators `|`, `&&`, `||`, `;` (respecting single/double quotes), then validates
+ * the leading executable of each segment plus its sub-command/arguments.
+ */
+interface PolicyResult {
+    allowed: boolean;
+    reason?: string;
+}
+type ShellKind = 'posix' | 'powershell';
+/** Split a command line on shell control operators, honoring single/double quotes. */
+declare function splitSegments(cmd: string): string[];
+/**
+ * Decide whether a command line is read-only and therefore safe to execute.
+ * Returns `{ allowed: false, reason }` for anything not explicitly permitted.
+ */
+declare function checkReadOnly(command: string, opts?: {
+    shell?: ShellKind;
+}): PolicyResult;
+/** Convenience boolean form. */
+declare function isReadOnlyCommand(command: string): boolean;
+/** Throwing form for guard sites that prefer exceptions. */
+declare function assertReadOnly(command: string): void;
+
 type DiscoveryEvent = {
     kind: 'thinking';
     text: string;
@@ -330,7 +686,7 @@ declare function computeClusterBounds(assets: DataAsset[], hexSize: number): {
 };
 
 /**
- * Node-zu-Asset Mapping.
+ * Node-to-Asset Mapping.
  * Converts existing DiscoveryNode/Edge data into the CartographyMap data model.
  */
 
@@ -375,4 +731,4 @@ declare function logInfo(message: string, context?: Record<string, unknown>): vo
 declare function logWarn(message: string, context?: Record<string, unknown>): void;
 declare function logError(message: string, context?: Record<string, unknown>): void;
 
-export { type CartographyConfig, CartographyDB, type CartographyMapData, type Cluster, ClusterSchema, type Connection, ConnectionSchema, DOMAIN_COLORS, DOMAIN_PALETTE, type DataAsset, DataAssetSchema, type DiscoveryEdge, type DiscoveryEvent, type DiscoveryNode, EDGE_RELATIONSHIPS, type EdgeRelationship, type EdgeRow, EdgeSchema, type LogEntry, type LogLevel, NODE_TYPES, type NodeRow, NodeSchema, type NodeType, type SessionRow, assignColors, buildMapData, checkPrerequisites, cleanupTempFiles, computeCentroid, computeClusterBounds, createCartographyTools, CartographyDB as default, defaultConfig, edgesToConnections, exportAll, exportBackstageYAML, exportDiscoveryApp, exportJGF, exportJSON, generateDependencyMermaid, generateTopologyMermaid, groupByDomain, hexCorners, hexDistance, hexNeighbors, hexRing, hexSpiral, hexToPixel, layoutClusters, log, logDebug, logError, logInfo, logWarn, nodesToAssets, pixelToHex, runDiscovery, safetyHook, setVerbose, shadeVariant, stripSensitive };
+export { type CartographyConfig, CartographyDB, type CartographyMapData, type Cluster, ClusterSchema, type Connection, ConnectionSchema, type CreateMcpServerOptions, DOMAIN_COLORS, DOMAIN_PALETTE, type DataAsset, DataAssetSchema, type DiscoveryEdge, type DiscoveryEvent, type DiscoveryFn, type DiscoveryNode, EDGE_RELATIONSHIPS, type EdgeRelationship, type EdgeRow, EdgeSchema, type EmbeddingProvider, type GraphSummary, type HttpOptions, type LocalDiscoveryOptions, type LogEntry, type LogLevel, NODE_TYPES, NODE_TYPE_GROUPS, type NodeRow, NodeSchema, type NodeType, type PolicyResult, type ScanContext, type ScanResult, type Scanner, ScannerRegistry, type SearchFn, type SessionRow, type ShellKind, type TraversalResult, VectorStore, assertReadOnly, assignColors, bookmarksScanner, buildMapData, checkPrerequisites, checkReadOnly, cleanupTempFiles, computeCentroid, computeClusterBounds, createCartographyTools, createHashEmbedder, createLocalEmbedder, createMcpServer, createScanRunner, createSemanticSearch, defaultConfig, defaultRegistry, edgesToConnections, exportAll, exportBackstageYAML, exportDiscoveryApp, exportJGF, exportJSON, extractListeningPorts, generateDependencyMermaid, generateTopologyMermaid, groupByDomain, hexCorners, hexDistance, hexNeighbors, hexRing, hexSpiral, hexToPixel, installedAppsScanner, isReadOnlyCommand, layoutClusters, localDiscoveryFn, log, logDebug, logError, logInfo, logWarn, nodesToAssets, pixelToHex, portsScanner, runDiscovery, runHttp, runLocalDiscovery, runStdio, safeEnv, safetyHook, setVerbose, shadeVariant, splitSegments, stripSensitive };