@rkarim08/sia 1.0.0

package/src/mcp/tools/sia-stats.ts

@@ -0,0 +1,63 @@
+// Module: sia-stats — Graph metrics: node/edge counts by type, optional session stats
+
+import type { z } from "zod";
+import type { SiaDb } from "@/graph/db-interface";
+import type { SiaStatsInput } from "@/mcp/server";
+
+export interface SiaStatsResult {
+	nodes: Record<string, number>;
+	edges: Record<string, number>;
+	session?: { callCounts: Record<string, number> };
+	error?: string;
+}
+
+/**
+ * Return graph metrics: active node counts by type, active edge counts by type,
+ * and optionally the per-tool call counts for the current session from search_throttle.
+ */
+export async function handleSiaStats(
+	db: SiaDb,
+	input: z.infer<typeof SiaStatsInput>,
+	sessionId?: string,
+): Promise<SiaStatsResult> {
+	try {
+		// Node counts by type (active only)
+		const { rows: nodeRows } = await db.execute(
+			"SELECT type, COUNT(*) as count FROM graph_nodes WHERE t_expired IS NULL GROUP BY type",
+		);
+
+		const nodes: Record<string, number> = {};
+		for (const row of nodeRows) {
+			nodes[row.type as string] = row.count as number;
+		}
+
+		// Edge counts by type (active only)
+		const { rows: edgeRows } = await db.execute(
+			"SELECT type, COUNT(*) as count FROM graph_edges WHERE t_expired IS NULL GROUP BY type",
+		);
+
+		const edges: Record<string, number> = {};
+		for (const row of edgeRows) {
+			edges[row.type as string] = row.count as number;
+		}
+
+		// Optional session stats from search_throttle
+		if (input.include_session && sessionId) {
+			const { rows: throttleRows } = await db.execute(
+				"SELECT tool_name, call_count FROM search_throttle WHERE session_id = ?",
+				[sessionId],
+			);
+
+			const callCounts: Record<string, number> = {};
+			for (const row of throttleRows) {
+				callCounts[row.tool_name as string] = row.call_count as number;
+			}
+
+			return { nodes, edges, session: { callCounts } };
+		}
+
+		return { nodes, edges };
+	} catch (err) {
+		return { nodes: {}, edges: {}, error: `Stats query failed: ${(err as Error).message}` };
+	}
+}

package/src/mcp/tools/sia-sync-status.ts

@@ -0,0 +1,44 @@
+// Module: sia-sync-status — MCP tool handler for team sync status.
+//
+// Returns the current sync configuration and status.
+// Read-only — does not require a database connection.
+
+import { getConfig, resolveSiaHome } from "@/shared/config";
+
+export interface SiaSyncStatusResult {
+	enabled: boolean;
+	status: "not_configured" | "active" | "error";
+	server_url?: string;
+	developer_id?: string;
+	sync_interval_seconds?: number;
+	error?: string;
+}
+
+/**
+ * Check the current team sync configuration and status.
+ */
+export async function handleSiaSyncStatus(): Promise<SiaSyncStatusResult> {
+	try {
+		const config = getConfig(resolveSiaHome());
+		const sync = config.sync;
+
+		if (!sync.enabled || !sync.serverUrl) {
+			return { enabled: false, status: "not_configured" };
+		}
+
+		return {
+			enabled: true,
+			status: "active",
+			server_url: sync.serverUrl,
+			developer_id: sync.developerId ?? undefined,
+			sync_interval_seconds: sync.syncInterval,
+		};
+	} catch (err) {
+		console.error("[sia] sia_sync_status error:", err);
+		return {
+			enabled: false,
+			status: "error",
+			error: err instanceof Error ? err.message : String(err),
+		};
+	}
+}

package/src/mcp/tools/sia-upgrade.ts

@@ -0,0 +1,247 @@
+// Module: sia-upgrade — Self-update handler with npm/git/binary strategies
+
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { z } from "zod";
+import type { SiaDb } from "@/graph/db-interface";
+import type { SiaUpgradeInput } from "@/mcp/server";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type InstallationType = "npm" | "git" | "binary";
+
+export interface UpdateStrategy {
+	name: InstallationType;
+	detect(): boolean;
+	currentVersion(): string;
+	update(target: string): void;
+	rollback(snapshot: string): void;
+}
+
+export interface SiaUpgradeResult {
+	previousVersion?: string;
+	newVersion?: string;
+	strategy?: string;
+	migrationsRun?: number;
+	hooksReconfigured?: boolean;
+	vssRebuilt?: boolean;
+	dryRun?: boolean;
+	error?: string;
+}
+
+// ---------------------------------------------------------------------------
+// NpmUpdateStrategy
+// ---------------------------------------------------------------------------
+
+export class NpmUpdateStrategy implements UpdateStrategy {
+	name: InstallationType = "npm";
+
+	constructor(private readonly siaRoot: string) {}
+
+	detect(): boolean {
+		return existsSync(join(this.siaRoot, "node_modules", "sia"));
+	}
+
+	currentVersion(): string {
+		const pkgPath = join(this.siaRoot, "node_modules", "sia", "package.json");
+		if (existsSync(pkgPath)) {
+			try {
+				const pkg = JSON.parse(readFileSync(pkgPath, "utf-8")) as { version?: string };
+				return pkg.version ?? "unknown";
+			} catch (err) {
+				console.error(`[sia-upgrade] Failed to read version: ${(err as Error).message}`);
+				return "unknown";
+			}
+		}
+		return "unknown";
+	}
+
+	update(target: string): void {
+		const pkg = target ? `sia@${target}` : "sia";
+		const result = spawnSync("bun", ["update", pkg], { encoding: "utf-8" });
+		if (result.status !== 0) {
+			throw new Error(result.stderr ?? "bun update failed");
+		}
+	}
+
+	rollback(snapshot: string): void {
+		const result = spawnSync("bun", ["add", `sia@${snapshot}`], { encoding: "utf-8" });
+		if (result.status !== 0) {
+			throw new Error(result.stderr ?? "bun add rollback failed");
+		}
+	}
+}
+
+// ---------------------------------------------------------------------------
+// GitUpdateStrategy
+// ---------------------------------------------------------------------------
+
+export class GitUpdateStrategy implements UpdateStrategy {
+	name: InstallationType = "git";
+
+	constructor(private readonly siaRoot: string) {}
+
+	detect(): boolean {
+		return existsSync(join(this.siaRoot, ".git"));
+	}
+
+	currentVersion(): string {
+		const result = spawnSync("git", ["rev-parse", "--short", "HEAD"], {
+			cwd: this.siaRoot,
+			encoding: "utf-8",
+		});
+		if (result.status === 0 && result.stdout) {
+			return result.stdout.trim();
+		}
+		console.error(
+			`[sia-upgrade] Failed to read version: ${result.stderr?.trim() ?? "git rev-parse failed"}`,
+		);
+		return "unknown";
+	}
+
+	update(_target: string): void {
+		const pull = spawnSync("git", ["pull", "origin", "main"], {
+			cwd: this.siaRoot,
+			encoding: "utf-8",
+		});
+		if (pull.status !== 0) {
+			throw new Error(pull.stderr ?? "git pull failed");
+		}
+
+		const install = spawnSync("bun", ["install"], {
+			cwd: this.siaRoot,
+			encoding: "utf-8",
+		});
+		if (install.status !== 0) {
+			throw new Error(install.stderr ?? "bun install failed");
+		}
+	}
+
+	rollback(snapshot: string): void {
+		const result = spawnSync("git", ["reset", "--hard", snapshot], {
+			cwd: this.siaRoot,
+			encoding: "utf-8",
+		});
+		if (result.status !== 0) {
+			throw new Error(result.stderr ?? "git reset failed");
+		}
+	}
+}
+
+// ---------------------------------------------------------------------------
+// BinaryUpdateStrategy
+// ---------------------------------------------------------------------------
+
+export class BinaryUpdateStrategy implements UpdateStrategy {
+	name: InstallationType = "binary";
+
+	detect(): boolean {
+		// fallback — always detects
+		return true;
+	}
+
+	currentVersion(): string {
+		return "unknown";
+	}
+
+	update(_target: string): void {
+		throw new Error("not yet implemented");
+	}
+
+	rollback(_snapshot: string): void {
+		throw new Error("not yet implemented");
+	}
+}
+
+// ---------------------------------------------------------------------------
+// detectInstallationType
+// ---------------------------------------------------------------------------
+
+export function detectInstallationType(siaRoot: string): InstallationType {
+	// npm preferred over git when both exist
+	const npm = new NpmUpdateStrategy(siaRoot);
+	if (npm.detect()) return "npm";
+
+	const git = new GitUpdateStrategy(siaRoot);
+	if (git.detect()) return "git";
+
+	return "binary";
+}
+
+// ---------------------------------------------------------------------------
+// handleSiaUpgrade
+// ---------------------------------------------------------------------------
+
+export async function handleSiaUpgrade(
+	_db: SiaDb,
+	input: z.infer<typeof SiaUpgradeInput>,
+	config?: { siaRoot?: string; upgradeReleaseUrl?: string },
+): Promise<SiaUpgradeResult> {
+	const siaRoot = config?.siaRoot ?? process.cwd();
+	const targetVersion = input.target_version ?? "";
+	const dryRun = input.dry_run ?? false;
+
+	// 1. Auto-detect installation type
+	const type = detectInstallationType(siaRoot);
+
+	// Build the strategy instance
+	let strategy: UpdateStrategy;
+	if (type === "npm") {
+		strategy = new NpmUpdateStrategy(siaRoot);
+	} else if (type === "git") {
+		strategy = new GitUpdateStrategy(siaRoot);
+	} else {
+		strategy = new BinaryUpdateStrategy();
+	}
+
+	// 2. Snapshot current version
+	const previousVersion = strategy.currentVersion();
+
+	// 3. If dry_run → return early
+	if (dryRun) {
+		return { previousVersion, strategy: type, dryRun: true };
+	}
+
+	// Guard: if version is unknown, rollback would be impossible
+	if (previousVersion === "unknown") {
+		return {
+			previousVersion,
+			strategy: type,
+			error: "Cannot determine current version — rollback would be impossible. Aborting upgrade.",
+		};
+	}
+
+	// 4. Try update → on failure, try rollback
+	try {
+		strategy.update(targetVersion);
+	} catch (updateErr) {
+		// Attempt rollback
+		let rollbackMsg = "";
+		try {
+			strategy.rollback(previousVersion);
+			rollbackMsg = " (rolled back to previous version)";
+		} catch (rollbackErr) {
+			rollbackMsg = ` (rollback also failed: ${rollbackErr instanceof Error ? rollbackErr.message : String(rollbackErr)})`;
+		}
+
+		return {
+			previousVersion,
+			strategy: type,
+			error: `${updateErr instanceof Error ? updateErr.message : String(updateErr)}${rollbackMsg}`,
+		};
+	}
+
+	// 5. Return success result
+	const newVersion = strategy.currentVersion();
+	return {
+		previousVersion,
+		newVersion,
+		strategy: type,
+		migrationsRun: 0,
+		hooksReconfigured: false,
+		vssRebuilt: false,
+	};
+}

package/src/mcp/truncate.ts

@@ -0,0 +1,231 @@
+// Module: truncate — Bounds MCP tool response payloads to a character budget.
+//
+// MCP tool responses are injected into the Claude context window. Unbounded
+// responses from large graph queries can consume thousands of tokens.
+// This utility truncates responses to a configurable character limit.
+
+const DEFAULT_MAX_CHARS = 8000;
+const MIN_MAX_CHARS = 100;
+
+/** Describes a truncatable collection found on the response object. */
+interface TruncatableField {
+	key: string;
+	items: unknown[];
+	/** True when the original property was a Record<string, T[]> that we flattened. */
+	flattened: boolean;
+	/** When flattened, records original group keys and their item counts. */
+	originalGroups?: Record<string, number>;
+}
+
+/**
+ * Find the largest truncatable collection on an object.
+ *
+ * First pass: direct array properties (e.g. `entities`, `communities`, `results`).
+ * Picks the **largest** non-empty array by item count, so multi-array responses
+ * like sia_expand (neighbors + edges) truncate the dominant collection.
+ *
+ * Second pass (if no arrays found): grouped collections — plain objects whose
+ * values are all arrays and that have >= 2 groups (e.g. `backlinks:
+ * Record<string, BacklinkEntry[]>`). The >= 2 group threshold avoids
+ * false-positives on objects that happen to have a single array-valued property.
+ * These are flattened into a single array so the binary search can trim them
+ * uniformly, with `_original_groups` metadata for consumer reconstruction.
+ */
+function findTruncatableField(obj: Record<string, unknown>): TruncatableField | null {
+	// First pass: find the largest direct array property
+	let best: TruncatableField | null = null;
+	for (const [key, val] of Object.entries(obj)) {
+		if (Array.isArray(val) && val.length > 0) {
+			if (!best || val.length > best.items.length) {
+				best = { key, items: val, flattened: false };
+			}
+		}
+	}
+	if (best) return best;
+
+	// Second pass: Record<string, T[]> grouped collections (>= 2 groups to avoid false positives)
+	for (const [key, val] of Object.entries(obj)) {
+		if (val !== null && typeof val === "object" && !Array.isArray(val)) {
+			const nested = val as Record<string, unknown>;
+			const nestedEntries = Object.entries(nested);
+			if (nestedEntries.length >= 2 && nestedEntries.every(([, v]) => Array.isArray(v))) {
+				const originalGroups: Record<string, number> = {};
+				const flatItems: unknown[] = [];
+				for (const [groupKey, groupVal] of nestedEntries) {
+					const arr = groupVal as unknown[];
+					originalGroups[groupKey] = arr.length;
+					flatItems.push(...arr);
+				}
+				if (flatItems.length > 0) {
+					return { key, items: flatItems, flattened: true, originalGroups };
+				}
+			}
+		}
+	}
+
+	return null;
+}
+
+/**
+ * Binary-search for the max items from a bare array that fit within budget.
+ * Wraps the result in an envelope with truncation metadata.
+ */
+function truncateArray(items: unknown[], serialized: string, maxChars: number): unknown {
+	const originalCount = items.length;
+
+	let lo = 0;
+	let hi = items.length;
+	while (lo < hi) {
+		const mid = Math.ceil((lo + hi) / 2);
+		const candidate = {
+			items: items.slice(0, mid),
+			_truncated: true,
+			_original_count: originalCount,
+			_showing: mid,
+		};
+		if (JSON.stringify(candidate).length <= maxChars) {
+			lo = mid;
+		} else {
+			hi = mid - 1;
+		}
+	}
+
+	const showing = Math.max(lo, 1);
+	const result = {
+		items: items.slice(0, showing),
+		_truncated: true,
+		_original_count: originalCount,
+		_showing: showing,
+	};
+
+	if (lo === 0 && JSON.stringify(result).length > maxChars) {
+		return {
+			_truncated: true,
+			_original_count: originalCount,
+			_original_size: serialized.length,
+			_max_chars: maxChars,
+			_message: `Response too large: array has ${originalCount} items but even 1 exceeds the ${maxChars}-char budget. Use more specific query parameters.`,
+		};
+	}
+
+	return result;
+}
+
+/**
+ * Truncate an MCP tool response to fit within a character budget.
+ *
+ * Strategy (in execution order):
+ * 1. null/undefined — pass through unchanged.
+ * 2. maxChars below MIN_MAX_CHARS (100) — pass through unchanged to avoid
+ *    degenerate truncation.
+ * 3. Serialization failure (e.g. circular references) — return a
+ *    `_serialization_error` envelope.
+ * 4. Serialized response fits within budget — return unchanged.
+ * 5. String response — return a truncation envelope object (not a raw
+ *    string, to avoid double-encoding when the caller JSON.stringify's).
+ * 6. Bare array (e.g. sia_search returns T[]) — binary-search for max
+ *    items that fit, wrapped in an `{items, _truncated}` envelope.
+ * 7. Object with an array property (or grouped Record<string, T[]>) —
+ *    binary-search for the max items that fit, add truncation metadata.
+ *    If even 1 item exceeds the budget, an overflow envelope (with no
+ *    items) is returned instead.
+ * 8. Object with no truncatable collection — return a structured overflow envelope.
+ */
+export function truncateResponse(response: unknown, maxChars: number = DEFAULT_MAX_CHARS): unknown {
+	if (response === null || response === undefined) return response;
+	if (maxChars < MIN_MAX_CHARS) return response;
+
+	let serialized: string;
+	try {
+		serialized = JSON.stringify(response);
+	} catch (err) {
+		return {
+			_truncated: true,
+			_serialization_error: true,
+			_message: `Response could not be serialized: ${err instanceof Error ? err.message : String(err)}`,
+		};
+	}
+	if (serialized.length <= maxChars) return response;
+
+	// String: return structured envelope to avoid double-encoding
+	// Reserve ~200 chars for the JSON envelope keys (_truncated, _original_size, text, quotes, braces)
+	if (typeof response === "string") {
+		return {
+			_truncated: true,
+			_original_size: response.length,
+			text: response.slice(0, Math.max(maxChars - 200, MIN_MAX_CHARS)),
+		};
+	}
+
+	// Bare array (e.g. sia_search returns SiaSearchResult[]): truncate directly
+	if (Array.isArray(response)) {
+		return truncateArray(response, serialized, maxChars);
+	}
+
+	// Object: find the dominant truncatable collection and binary-search for max items that fit
+	if (typeof response === "object") {
+		const obj = response as Record<string, unknown>;
+		const field = findTruncatableField(obj);
+
+		if (field) {
+			const { key: arrayKey, items, flattened, originalGroups } = field;
+			const originalCount = items.length;
+			const flatMeta = flattened
+				? { _flattened: true, ...(originalGroups ? { _original_groups: originalGroups } : {}) }
+				: {};
+
+			let lo = 0;
+			let hi = items.length;
+			while (lo < hi) {
+				const mid = Math.ceil((lo + hi) / 2);
+				const candidate = {
+					...obj,
+					[arrayKey]: items.slice(0, mid),
+					_truncated: true,
+					_original_count: originalCount,
+					_showing: mid,
+					...flatMeta,
+				};
+				if (JSON.stringify(candidate).length <= maxChars) {
+					lo = mid;
+				} else {
+					hi = mid - 1;
+				}
+			}
+
+			const showing = Math.max(lo, 1);
+			const result = {
+				...obj,
+				[arrayKey]: items.slice(0, showing),
+				_truncated: true,
+				_original_count: originalCount,
+				_showing: showing,
+				...flatMeta,
+			};
+
+			// If even 1 item exceeds budget, return an overflow envelope
+			if (lo === 0 && JSON.stringify(result).length > maxChars) {
+				return {
+					_truncated: true,
+					_original_count: originalCount,
+					_original_size: serialized.length,
+					_max_chars: maxChars,
+					_message: `Response too large: '${arrayKey}' has ${originalCount} items but even 1 exceeds the ${maxChars}-char budget. Use more specific query parameters.`,
+				};
+			}
+
+			return result;
+		}
+
+		// No truncatable collection — overflow envelope
+		return {
+			_truncated: true,
+			_original_size: serialized.length,
+			_max_chars: maxChars,
+			_message:
+				"Response exceeded size limit. Use more specific query parameters to narrow results.",
+		};
+	}
+
+	return response;
+}