@datasynx/agentic-ai-cartography 1.1.0 → 2.0.0

package/dist/index.d.cts

@@ -0,0 +1,734 @@
+import Database from 'better-sqlite3';
+import { z } from 'zod';
+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<{
+    id: z.ZodString;
+    type: z.ZodEnum<{
+        host: "host";
+        database_server: "database_server";
+        database: "database";
+        table: "table";
+        web_service: "web_service";
+        api_endpoint: "api_endpoint";
+        cache_server: "cache_server";
+        message_broker: "message_broker";
+        queue: "queue";
+        topic: "topic";
+        container: "container";
+        pod: "pod";
+        k8s_cluster: "k8s_cluster";
+        config_file: "config_file";
+        saas_tool: "saas_tool";
+        unknown: "unknown";
+    }>;
+    name: z.ZodString;
+    discoveredVia: z.ZodString;
+    confidence: z.ZodDefault<z.ZodNumber>;
+    metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    domain: z.ZodOptional<z.ZodString>;
+    subDomain: z.ZodOptional<z.ZodString>;
+    qualityScore: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+type DiscoveryNode = z.infer<typeof NodeSchema>;
+declare const EdgeSchema: z.ZodObject<{
+    sourceId: z.ZodString;
+    targetId: z.ZodString;
+    relationship: z.ZodEnum<{
+        connects_to: "connects_to";
+        reads_from: "reads_from";
+        writes_to: "writes_to";
+        calls: "calls";
+        contains: "contains";
+        depends_on: "depends_on";
+    }>;
+    evidence: z.ZodString;
+    confidence: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+type DiscoveryEdge = z.infer<typeof EdgeSchema>;
+declare const DataAssetSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    domain: z.ZodString;
+    subDomain: z.ZodOptional<z.ZodString>;
+    qualityScore: z.ZodOptional<z.ZodNumber>;
+    metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    position: z.ZodObject<{
+        q: z.ZodNumber;
+        r: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+type DataAsset = z.infer<typeof DataAssetSchema>;
+declare const ClusterSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    domain: z.ZodString;
+    color: z.ZodString;
+    assetIds: z.ZodArray<z.ZodString>;
+    centroid: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+type Cluster = z.infer<typeof ClusterSchema>;
+declare const ConnectionSchema: z.ZodObject<{
+    id: z.ZodString;
+    sourceAssetId: z.ZodString;
+    targetAssetId: z.ZodString;
+    type: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type Connection = z.infer<typeof ConnectionSchema>;
+interface CartographyMapData {
+    assets: DataAsset[];
+    clusters: Cluster[];
+    connections: Connection[];
+    meta: {
+        exportedAt: string;
+        theme: 'light' | 'dark';
+    };
+}
+/** Navy → medium blue → periwinkle → teal/cyan palette */
+declare const DOMAIN_COLORS: Record<string, string>;
+/** Ordered palette for dynamic domain assignment */
+declare const DOMAIN_PALETTE: readonly ["#1a2e5a", "#1e3a8a", "#1d4ed8", "#2563eb", "#3b82f6", "#6366f1", "#818cf8", "#7c9fc3", "#0e7490", "#0891b2", "#06b6d4", "#22d3ee", "#0d9488", "#14b8a6", "#2dd4bf", "#5eead4"];
+interface NodeRow extends DiscoveryNode {
+    sessionId: string;
+    discoveredAt: string;
+    depth: number;
+    pathId?: string;
+}
+interface EdgeRow extends DiscoveryEdge {
+    id: string;
+    sessionId: string;
+    discoveredAt: string;
+    pathId?: string;
+}
+interface SessionRow {
+    id: string;
+    mode: 'discover';
+    startedAt: string;
+    completedAt?: string;
+    config: string;
+}
+interface CartographyConfig {
+    maxDepth: number;
+    maxTurns: number;
+    entryPoints: string[];
+    agentModel: string;
+    organization?: string;
+    outputDir: string;
+    dbPath: string;
+    verbose: boolean;
+}
+declare function defaultConfig(overrides?: Partial<CartographyConfig>): CartographyConfig;
+
+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;
+    taskId?: string;
+    timestamp: string;
+    eventType: string;
+    process: string;
+    pid: number;
+    target?: string;
+    targetType?: string;
+    port?: number;
+    durationMs?: number;
+}
+interface TaskRow {
+    id: string;
+    sessionId: string;
+    description?: string;
+    startedAt: string;
+    completedAt?: string;
+    steps: string;
+    involvedServices: string;
+    status: 'active' | 'completed' | 'cancelled';
+}
+interface WorkflowRow {
+    id: string;
+    sessionId: string;
+    name?: string;
+    pattern: string;
+    taskIds: string;
+    occurrences: number;
+    firstSeen: string;
+    lastSeen: string;
+    avgDurationMs: number;
+    involvedServices: string;
+}
+declare class CartographyDB {
+    private db;
+    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;
+    getLatestSession(mode?: string): SessionRow | undefined;
+    getSessions(): SessionRow[];
+    private mapSession;
+    upsertNode(sessionId: string, node: DiscoveryNode, depth?: number): void;
+    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, 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;
+    endCurrentTask(sessionId: string): void;
+    updateTaskDescription(sessionId: string, description: string): void;
+    getActiveTask(sessionId: string): TaskRow | undefined;
+    getTasks(sessionId: string): TaskRow[];
+    private mapTask;
+    insertWorkflow(sessionId: string, data: Omit<WorkflowRow, 'id'>): void;
+    getWorkflows(sessionId: string): WorkflowRow[];
+    upsertConnection(sessionId: string, conn: Omit<Connection, 'id'>): string;
+    getConnections(sessionId: string): ConnectionRow[];
+    deleteConnection(sessionId: string, connectionId: string): void;
+    setApproval(pattern: string, action: 'save' | 'ignore' | 'auto'): void;
+    getApproval(pattern: string): string | undefined;
+    /**
+     * Delete a session and all its associated data (nodes, edges, events, tasks, workflows, connections).
+     */
+    deleteSession(sessionId: string): void;
+    /**
+     * 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;
+        events: number;
+        tasks: number;
+    };
+}
+
+/**
+ * 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<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;
+} | {
+    kind: 'tool_call';
+    tool: string;
+    input: Record<string, unknown>;
+} | {
+    kind: 'tool_result';
+    tool: string;
+    output: string;
+} | {
+    kind: 'turn';
+    turn: number;
+} | {
+    kind: 'error';
+    text: string;
+} | {
+    kind: 'done';
+};
+type AskUserFn = (question: string, context?: string) => Promise<string>;
+declare function runDiscovery(config: CartographyConfig, db: CartographyDB, sessionId: string, onEvent?: (event: DiscoveryEvent) => void, onAskUser?: AskUserFn, hint?: string): Promise<void>;
+
+declare function generateTopologyMermaid(nodes: NodeRow[], edges: EdgeRow[]): string;
+declare function generateDependencyMermaid(nodes: NodeRow[], edges: EdgeRow[]): string;
+declare function exportBackstageYAML(nodes: NodeRow[], edges: EdgeRow[], org?: string): string;
+declare function exportJSON(db: CartographyDB, sessionId: string): string;
+declare function exportDiscoveryApp(nodes: NodeRow[], edges: EdgeRow[], options?: {
+    theme?: 'light' | 'dark';
+}): string;
+declare function exportJGF(nodes: NodeRow[], edges: EdgeRow[]): string;
+declare function exportAll(db: CartographyDB, sessionId: string, outputDir: string, formats?: string[]): void;
+
+/**
+ * Hex Grid Engine — flat-top axial coordinate system.
+ * Reference: https://www.redblobgames.com/grids/hexagons/
+ */
+interface AxialCoord {
+    q: number;
+    r: number;
+}
+interface PixelCoord {
+    x: number;
+    y: number;
+}
+/**
+ * Convert axial hex coordinates to pixel coordinates (flat-top).
+ */
+declare function hexToPixel(q: number, r: number, size: number): PixelCoord;
+/**
+ * Convert pixel coordinates to nearest axial hex (flat-top).
+ */
+declare function pixelToHex(x: number, y: number, size: number): AxialCoord;
+/**
+ * Return the 6 pixel corners of a flat-top hexagon.
+ */
+declare function hexCorners(cx: number, cy: number, size: number): PixelCoord[];
+declare function hexNeighbors(q: number, r: number): AxialCoord[];
+declare function hexDistance(a: AxialCoord, b: AxialCoord): number;
+/**
+ * Generate all hex coordinates on a given ring around center.
+ */
+declare function hexRing(center: AxialCoord, radius: number): AxialCoord[];
+/**
+ * Generate a spiral sequence of hex positions (ring 0, ring 1, ring 2, …).
+ * Returns exactly `count` positions.
+ */
+declare function hexSpiral(center: AxialCoord, count: number): AxialCoord[];
+
+/**
+ * Domain-based clustering and hex grid positioning.
+ * Groups data assets by domain, assigns organic hex positions via spiral fill,
+ * computes cluster centroids and assigns colors from the domain palette.
+ */
+
+/**
+ * Assign colors to all domains in the dataset.
+ */
+declare function assignColors(domains: string[]): Record<string, string>;
+/**
+ * Generate a slightly lighter shade of a hex color string.
+ */
+declare function shadeVariant(hex: string, amount: number): string;
+/**
+ * Group assets by their `domain` field.
+ */
+declare function groupByDomain(assets: DataAsset[]): Map<string, DataAsset[]>;
+/**
+ * Arrange domain clusters on the hex grid without overlap.
+ * Places largest clusters first at the origin, subsequent clusters spiral outward.
+ */
+declare function layoutClusters(groups: Map<string, DataAsset[]>, hexSize: number): {
+    clusters: Cluster[];
+    assets: DataAsset[];
+};
+declare function computeCentroid(positions: AxialCoord[], hexSize: number): {
+    x: number;
+    y: number;
+};
+declare function computeClusterBounds(assets: DataAsset[], hexSize: number): {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+};
+
+/**
+ * Node-to-Asset Mapping.
+ * Converts existing DiscoveryNode/Edge data into the CartographyMap data model.
+ */
+
+/**
+ * Convert NodeRow[] to DataAsset[].
+ */
+declare function nodesToAssets(nodes: NodeRow[]): DataAsset[];
+/**
+ * Convert EdgeRow[] to Connection[].
+ */
+declare function edgesToConnections(edges: EdgeRow[]): Connection[];
+/**
+ * Build a complete CartographyMapData from raw nodes and edges.
+ */
+declare function buildMapData(nodes: NodeRow[], edges: EdgeRow[], options?: {
+    theme?: 'light' | 'dark';
+}): CartographyMapData;
+
+declare function checkPrerequisites(): void;
+
+/**
+ * Remove orphaned temp files from previous bookmark/history scans.
+ * Call at startup to prevent /tmp accumulation after crashes.
+ */
+declare function cleanupTempFiles(): number;
+
+/**
+ * Structured logging for enterprise observability.
+ * Outputs JSON to stderr for compatibility with ELK, Datadog, Splunk, CloudWatch.
+ */
+type LogLevel = 'DEBUG' | 'INFO' | 'WARN' | 'ERROR';
+interface LogEntry {
+    timestamp: string;
+    level: LogLevel;
+    message: string;
+    context?: Record<string, unknown>;
+}
+declare function setVerbose(v: boolean): void;
+declare function log(level: LogLevel, message: string, context?: Record<string, unknown>): void;
+declare function logDebug(message: string, context?: Record<string, unknown>): void;
+declare function logInfo(message: string, context?: Record<string, unknown>): void;
+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, 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 };