@rkarim08/sia 1.0.0

package/src/cli/commands/stats.ts

@@ -0,0 +1,79 @@
+// Module: stats — graph statistics
+
+import type { SiaDb } from "@/graph/db-interface";
+
+export interface GraphStats {
+	totalEntitiesByType: Record<string, number>;
+	archivedCount: number;
+	invalidatedCount: number;
+	activeEdgesByType: Record<string, number>;
+	communityCount: number;
+	episodeCount: number;
+	pendingConflicts: number;
+}
+
+/**
+ * Gather aggregate statistics from the graph, episodic, and meta databases.
+ */
+export async function getStats(
+	graphDb: SiaDb,
+	episodicDb?: SiaDb,
+	_metaDb?: SiaDb,
+): Promise<GraphStats> {
+	// --- Active entities by type ---
+	const totalEntitiesByType: Record<string, number> = {};
+	const { rows: entityTypeRows } = await graphDb.execute(
+		"SELECT type, COUNT(*) AS cnt FROM graph_nodes WHERE t_valid_until IS NULL AND archived_at IS NULL GROUP BY type",
+	);
+	for (const row of entityTypeRows) {
+		totalEntitiesByType[row.type as string] = row.cnt as number;
+	}
+
+	// --- Archived count ---
+	const { rows: archivedRows } = await graphDb.execute(
+		"SELECT COUNT(*) AS cnt FROM graph_nodes WHERE archived_at IS NOT NULL",
+	);
+	const archivedCount = (archivedRows[0]?.cnt as number) ?? 0;
+
+	// --- Invalidated count ---
+	const { rows: invalidatedRows } = await graphDb.execute(
+		"SELECT COUNT(*) AS cnt FROM graph_nodes WHERE t_valid_until IS NOT NULL",
+	);
+	const invalidatedCount = (invalidatedRows[0]?.cnt as number) ?? 0;
+
+	// --- Active edges by type ---
+	const activeEdgesByType: Record<string, number> = {};
+	const { rows: edgeTypeRows } = await graphDb.execute(
+		"SELECT type, COUNT(*) AS cnt FROM graph_edges WHERE t_valid_until IS NULL GROUP BY type",
+	);
+	for (const row of edgeTypeRows) {
+		activeEdgesByType[row.type as string] = row.cnt as number;
+	}
+
+	// --- Community count ---
+	const { rows: communityRows } = await graphDb.execute("SELECT COUNT(*) AS cnt FROM communities");
+	const communityCount = (communityRows[0]?.cnt as number) ?? 0;
+
+	// --- Episode count (from episodicDb if provided) ---
+	let episodeCount = 0;
+	if (episodicDb) {
+		const { rows: episodeRows } = await episodicDb.execute("SELECT COUNT(*) AS cnt FROM episodes");
+		episodeCount = (episodeRows[0]?.cnt as number) ?? 0;
+	}
+
+	// --- Pending conflicts ---
+	const { rows: conflictRows } = await graphDb.execute(
+		"SELECT COUNT(DISTINCT conflict_group_id) AS cnt FROM graph_nodes WHERE conflict_group_id IS NOT NULL AND t_valid_until IS NULL",
+	);
+	const pendingConflicts = (conflictRows[0]?.cnt as number) ?? 0;
+
+	return {
+		totalEntitiesByType,
+		archivedCount,
+		invalidatedCount,
+		activeEdgesByType,
+		communityCount,
+		episodeCount,
+		pendingConflicts,
+	};
+}

package/src/cli/commands/status.ts

@@ -0,0 +1,176 @@
+// Module: status — knowledge graph health dashboard
+
+import type { SiaDb } from "@/graph/db-interface";
+
+export interface GraphHealth {
+	totalEntities: number;
+	totalEdges: number;
+	totalCommunities: number;
+	byType: Record<string, number>;
+	byTier: Record<number, number>;
+	byKind: Record<string, number>;
+	conflictGroups: number;
+	archivedEntities: number;
+	recentEntities24h: number;
+	oldestEntity: string | null;
+	newestEntity: string | null;
+}
+
+const TIER_LABELS: Record<number, string> = {
+	1: "User-Direct  ",
+	2: "Code-Analysis",
+	3: "LLM-Inferred ",
+	4: "External     ",
+};
+
+/**
+ * Gather health metrics from the knowledge graph.
+ */
+export async function getGraphHealth(db: SiaDb): Promise<GraphHealth> {
+	// Active entities total
+	const { rows: totalRows } = await db.execute(
+		"SELECT COUNT(*) AS cnt FROM graph_nodes WHERE t_valid_until IS NULL AND archived_at IS NULL",
+	);
+	const totalEntities = (totalRows[0]?.cnt as number) ?? 0;
+
+	// By type
+	const byType: Record<string, number> = {};
+	const { rows: typeRows } = await db.execute(
+		"SELECT type, COUNT(*) AS cnt FROM graph_nodes WHERE t_valid_until IS NULL AND archived_at IS NULL GROUP BY type",
+	);
+	for (const row of typeRows) {
+		byType[row.type as string] = row.cnt as number;
+	}
+
+	// By trust tier
+	const byTier: Record<number, number> = {};
+	const { rows: tierRows } = await db.execute(
+		"SELECT trust_tier, COUNT(*) AS cnt FROM graph_nodes WHERE t_valid_until IS NULL AND archived_at IS NULL GROUP BY trust_tier",
+	);
+	for (const row of tierRows) {
+		byTier[row.trust_tier as number] = row.cnt as number;
+	}
+
+	// By kind
+	const byKind: Record<string, number> = {};
+	const { rows: kindRows } = await db.execute(
+		"SELECT kind, COUNT(*) AS cnt FROM graph_nodes WHERE t_valid_until IS NULL AND archived_at IS NULL AND kind IS NOT NULL GROUP BY kind",
+	);
+	for (const row of kindRows) {
+		byKind[row.kind as string] = row.cnt as number;
+	}
+
+	// Total edges
+	const { rows: edgeRows } = await db.execute(
+		"SELECT COUNT(*) AS cnt FROM graph_edges WHERE t_valid_until IS NULL",
+	);
+	const totalEdges = (edgeRows[0]?.cnt as number) ?? 0;
+
+	// Communities
+	const { rows: communityRows } = await db.execute("SELECT COUNT(*) AS cnt FROM communities");
+	const totalCommunities = (communityRows[0]?.cnt as number) ?? 0;
+
+	// Conflict groups
+	const { rows: conflictRows } = await db.execute(
+		"SELECT COUNT(DISTINCT conflict_group_id) AS cnt FROM graph_nodes WHERE conflict_group_id IS NOT NULL AND t_valid_until IS NULL",
+	);
+	const conflictGroups = (conflictRows[0]?.cnt as number) ?? 0;
+
+	// Archived
+	const { rows: archivedRows } = await db.execute(
+		"SELECT COUNT(*) AS cnt FROM graph_nodes WHERE archived_at IS NOT NULL",
+	);
+	const archivedEntities = (archivedRows[0]?.cnt as number) ?? 0;
+
+	// Recent (24h)
+	const oneDayAgo = Date.now() - 86_400_000;
+	const { rows: recentRows } = await db.execute(
+		"SELECT COUNT(*) AS cnt FROM graph_nodes WHERE created_at > ? AND t_valid_until IS NULL AND archived_at IS NULL",
+		[oneDayAgo],
+	);
+	const recentEntities24h = (recentRows[0]?.cnt as number) ?? 0;
+
+	// Oldest / newest
+	const { rows: oldestRows } = await db.execute(
+		"SELECT MIN(created_at) AS ts FROM graph_nodes WHERE t_valid_until IS NULL AND archived_at IS NULL",
+	);
+	const oldestTs = oldestRows[0]?.ts as number | null;
+	const oldestEntity = oldestTs ? new Date(oldestTs).toISOString() : null;
+
+	const { rows: newestRows } = await db.execute(
+		"SELECT MAX(created_at) AS ts FROM graph_nodes WHERE t_valid_until IS NULL AND archived_at IS NULL",
+	);
+	const newestTs = newestRows[0]?.ts as number | null;
+	const newestEntity = newestTs ? new Date(newestTs).toISOString() : null;
+
+	return {
+		totalEntities,
+		totalEdges,
+		totalCommunities,
+		byType,
+		byTier,
+		byKind,
+		conflictGroups,
+		archivedEntities,
+		recentEntities24h,
+		oldestEntity,
+		newestEntity,
+	};
+}
+
+/**
+ * Format GraphHealth as a human-friendly terminal string.
+ */
+export function formatHealth(health: GraphHealth): string {
+	const lines: string[] = [];
+
+	lines.push("=== SIA Knowledge Graph Health ===");
+	lines.push(`Total entities:  ${health.totalEntities}`);
+	lines.push(`Total edges:     ${health.totalEdges}`);
+	lines.push(`Communities:     ${health.totalCommunities}`);
+	lines.push(
+		`Conflicts:       ${health.conflictGroups} group${health.conflictGroups !== 1 ? "s" : ""}`,
+	);
+	lines.push(`Archived:        ${health.archivedEntities}`);
+	lines.push(`Recent (24h):    ${health.recentEntities24h}`);
+
+	if (health.oldestEntity && health.newestEntity) {
+		const oldestDate = new Date(health.oldestEntity);
+		const newestDate = new Date(health.newestEntity);
+		const ageDays = Math.round((newestDate.getTime() - oldestDate.getTime()) / 86_400_000);
+		lines.push(`Graph age:       ${ageDays} day${ageDays !== 1 ? "s" : ""}`);
+	}
+
+	// By type
+	const typeEntries = Object.entries(health.byType).sort((a, b) => b[1] - a[1]);
+	if (typeEntries.length > 0) {
+		lines.push("");
+		lines.push("--- By Type ---");
+		for (const [type, count] of typeEntries) {
+			lines.push(`  ${type.padEnd(21)}${count}`);
+		}
+	}
+
+	// By tier
+	const tierEntries = Object.entries(health.byTier)
+		.map(([tier, count]) => [Number(tier), count] as [number, number])
+		.sort((a, b) => a[0] - b[0]);
+	if (tierEntries.length > 0) {
+		lines.push("");
+		lines.push("--- By Trust Tier ---");
+		for (const [tier, count] of tierEntries) {
+			const label = TIER_LABELS[tier] ?? `Tier ${tier}      `;
+			lines.push(`  Tier ${tier} (${label}) ${count}`);
+		}
+	}
+
+	return lines.join("\n");
+}
+
+/**
+ * CLI entry point for `sia status`.
+ */
+export async function runStatus(db: SiaDb): Promise<void> {
+	const health = await getGraphHealth(db);
+	console.log(formatHealth(health));
+}

package/src/cli/commands/sync.ts

@@ -0,0 +1,96 @@
+// Module: sync — CLI command for manual team sync push/pull
+//
+// Usage:
+//   sia sync         — push then pull
+//   sia sync push    — push local knowledge to server
+//   sia sync pull    — pull team knowledge from server
+
+import { resolveRepoHash } from "@/capture/hook";
+import type { SiaDb } from "@/graph/db-interface";
+import { getConfig, resolveSiaHome } from "@/shared/config";
+
+function printUsage(): void {
+	console.log(`Usage: sia sync [push|pull]
+
+  sia sync         Push then pull (default)
+  sia sync push    Push local knowledge to team server
+  sia sync pull    Pull team knowledge from server
+`);
+}
+
+export async function runSync(args: string[]): Promise<void> {
+	const subcommand = args[0] ?? "both";
+
+	if (subcommand === "--help" || subcommand === "-h") {
+		printUsage();
+		return;
+	}
+
+	const validSubcommands = ["push", "pull", "both"];
+	if (!validSubcommands.includes(subcommand)) {
+		console.error(`Unknown subcommand: ${subcommand}`);
+		printUsage();
+		process.exit(1);
+	}
+
+	const siaHome = resolveSiaHome();
+	const config = getConfig(siaHome);
+
+	if (!config.sync.enabled || !config.sync.serverUrl) {
+		console.error("Sync not configured. Run 'sia team join <url> <token>' first.");
+		process.exit(1);
+	}
+
+	const cwd = process.cwd();
+	const repoHash = resolveRepoHash(cwd);
+
+	let syncDb: SiaDb | undefined;
+	let bridgeDb: SiaDb | undefined;
+	let metaDb: SiaDb | undefined;
+
+	try {
+		const { createSiaDb } = await import("@/sync/client");
+		const { openBridgeDb } = await import("@/graph/bridge-db");
+		const { openMetaDb } = await import("@/graph/meta-db");
+
+		syncDb = await createSiaDb(repoHash, config.sync, { siaHome });
+		bridgeDb = openBridgeDb(siaHome);
+		metaDb = openMetaDb(siaHome);
+
+		if (subcommand === "push" || subcommand === "both") {
+			const { pushChanges } = await import("@/sync/push");
+			const result = await pushChanges(syncDb, config.sync, bridgeDb, repoHash, siaHome);
+			process.stdout.write(
+				`Push: ${result.entitiesPushed} entities, ${result.edgesPushed} edges, ${result.bridgeEdgesPushed} bridge edges\n`,
+			);
+		}
+
+		if (subcommand === "pull" || subcommand === "both") {
+			const { pullChanges } = await import("@/sync/pull");
+			const result = await pullChanges(syncDb, bridgeDb, config.sync, repoHash, siaHome, metaDb);
+			process.stdout.write(
+				`Pull: ${result.entitiesReceived} entities, ${result.edgesReceived} edges, ${result.vssRefreshed} VSS refreshed\n`,
+			);
+		}
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		console.error(`Sync failed: ${msg}`);
+		process.exit(1);
+	} finally {
+		try {
+			await syncDb?.close();
+		} catch (e) {
+			console.error("[sia] warning: failed to close sync db:", e);
+		}
+		try {
+			await bridgeDb?.close();
+		} catch (e) {
+			console.error("[sia] warning: failed to close bridge db:", e);
+		}
+		try {
+			await metaDb?.close();
+		} catch (e) {
+			console.error("[sia] warning: failed to close meta db:", e);
+		}
+	}
+}

package/src/cli/commands/team.ts

@@ -0,0 +1,118 @@
+// Module: team — team sync CLI helpers
+
+import { randomUUID } from "node:crypto";
+import type { SiaDb } from "@/graph/db-interface";
+import { getConfig, type SiaConfig, writeConfig } from "@/shared/config";
+import { deleteToken, storeToken } from "@/sync/keychain";
+import { pullChanges } from "@/sync/pull";
+
+export interface TeamStatus {
+	enabled: boolean;
+	serverUrl: string | null;
+	developerId: string | null;
+	syncInterval: number;
+	peerCount: number;
+	pendingConflicts: number;
+	lastSyncAt: number | null;
+}
+
+function ensureDeveloperId(config: SiaConfig): string {
+	if (config.sync.developerId) return config.sync.developerId;
+	const id = randomUUID();
+	writeConfig({
+		sync: {
+			developerId: id,
+			enabled: false,
+			serverUrl: null,
+			syncInterval: 0,
+		},
+	});
+	return id;
+}
+
+export async function teamJoin(
+	serverUrl: string,
+	token: string,
+	opts: {
+		syncInterval?: number;
+		siaHome?: string;
+		repoHash?: string;
+		db?: SiaDb;
+		bridgeDb?: SiaDb;
+	} = {},
+): Promise<void> {
+	await storeToken(serverUrl, token);
+
+	const config = getConfig(opts.siaHome);
+	const developerId = ensureDeveloperId(config);
+
+	writeConfig(
+		{
+			sync: {
+				enabled: true,
+				serverUrl,
+				developerId,
+				syncInterval: opts.syncInterval ?? config.sync.syncInterval,
+			},
+		},
+		opts.siaHome,
+	);
+
+	if (opts.db && opts.bridgeDb) {
+		await pullChanges(opts.db, opts.bridgeDb, {
+			enabled: true,
+			serverUrl,
+			developerId,
+			syncInterval: opts.syncInterval ?? config.sync.syncInterval,
+		});
+	}
+}
+
+export async function teamLeave(opts: { siaHome?: string; db?: SiaDb } = {}): Promise<void> {
+	const config = getConfig(opts.siaHome);
+	if (config.sync.serverUrl) {
+		await deleteToken(config.sync.serverUrl);
+	}
+
+	writeConfig(
+		{
+			sync: {
+				enabled: false,
+				serverUrl: null,
+				developerId: config.sync.developerId,
+				syncInterval: config.sync.syncInterval,
+			},
+		},
+		opts.siaHome,
+	);
+
+	if (opts.db) {
+		await opts.db.execute(
+			"UPDATE graph_nodes SET visibility = 'private', workspace_scope = NULL, synced_at = NULL",
+		);
+	}
+}
+
+export async function teamStatus(opts: { siaHome?: string; db?: SiaDb } = {}): Promise<TeamStatus> {
+	const config = getConfig(opts.siaHome);
+	const peerCount = 0;
+	let pendingConflicts = 0;
+	const lastSyncAt: number | null = null;
+
+	if (opts.db) {
+		const conflicts = await opts.db.execute(
+			"SELECT COUNT(DISTINCT conflict_group_id) as cnt FROM graph_nodes WHERE conflict_group_id IS NOT NULL AND t_valid_until IS NULL",
+		);
+		pendingConflicts = (conflicts.rows[0]?.cnt as number) ?? 0;
+	}
+
+	return {
+		enabled: config.sync.enabled,
+		serverUrl: config.sync.serverUrl,
+		developerId: config.sync.developerId,
+		syncInterval: config.sync.syncInterval,
+		peerCount,
+		pendingConflicts,
+		lastSyncAt,
+	};
+}

package/src/cli/commands/tour.ts

@@ -0,0 +1,157 @@
+// Module: tour — Interactive guided walkthrough of the knowledge graph
+
+import type { SiaDb } from "@/graph/db-interface";
+
+export interface TourSection {
+	title: string;
+	content: string;
+	entityCount: number;
+}
+
+export interface TourResult {
+	totalEntities: number;
+	totalEdges: number;
+	sections: TourSection[];
+}
+
+export async function generateTour(db: SiaDb): Promise<TourResult> {
+	// Count totals
+	const entityCount = await db.execute(
+		"SELECT COUNT(*) as cnt FROM graph_nodes WHERE t_valid_until IS NULL AND archived_at IS NULL",
+	);
+	const edgeCount = await db.execute(
+		"SELECT COUNT(*) as cnt FROM graph_edges WHERE t_valid_until IS NULL",
+	);
+
+	const totalEntities = (entityCount.rows[0] as any).cnt;
+	const totalEdges = (edgeCount.rows[0] as any).cnt;
+
+	const sections: TourSection[] = [];
+
+	// Section 1: Architecture Overview (from communities)
+	const communities = await db.execute(
+		"SELECT id, summary, member_count FROM communities WHERE level = 2 ORDER BY member_count DESC LIMIT 5",
+	);
+	if ((communities.rows as any[]).length > 0) {
+		const content = (communities.rows as any[])
+			.map(
+				(c) =>
+					`- **${c.summary?.slice(0, 100) || "Unnamed community"}** (${c.member_count} members)`,
+			)
+			.join("\n");
+		sections.push({
+			title: "Architecture Overview",
+			content: `Your codebase has ${(communities.rows as any[]).length} major modules:\n\n${content}`,
+			entityCount: (communities.rows as any[]).length,
+		});
+	}
+
+	// Section 2: Key Decisions
+	const decisions = await db.execute(
+		`SELECT name, summary FROM graph_nodes
+		 WHERE type = 'Decision' AND t_valid_until IS NULL AND archived_at IS NULL
+		 ORDER BY importance DESC LIMIT 5`,
+	);
+	if ((decisions.rows as any[]).length > 0) {
+		const content = (decisions.rows as any[])
+			.map((d) => `- **${d.name}**: ${d.summary?.slice(0, 120) || "no summary"}`)
+			.join("\n");
+		sections.push({
+			title: "Key Decisions",
+			content: `${(decisions.rows as any[]).length} architectural decisions captured:\n\n${content}`,
+			entityCount: (decisions.rows as any[]).length,
+		});
+	}
+
+	// Section 3: Active Conventions
+	const conventions = await db.execute(
+		`SELECT name, summary FROM graph_nodes
+		 WHERE type = 'Convention' AND t_valid_until IS NULL AND archived_at IS NULL
+		 ORDER BY importance DESC LIMIT 10`,
+	);
+	if ((conventions.rows as any[]).length > 0) {
+		const content = (conventions.rows as any[])
+			.map((c) => `- **${c.name}**: ${c.summary?.slice(0, 120) || "no summary"}`)
+			.join("\n");
+		sections.push({
+			title: "Coding Conventions",
+			content: `${(conventions.rows as any[]).length} conventions to follow:\n\n${content}`,
+			entityCount: (conventions.rows as any[]).length,
+		});
+	}
+
+	// Section 4: Known Issues
+	const bugs = await db.execute(
+		`SELECT name, summary FROM graph_nodes
+		 WHERE type = 'Bug' AND t_valid_until IS NULL AND archived_at IS NULL
+		 ORDER BY created_at DESC LIMIT 5`,
+	);
+	if ((bugs.rows as any[]).length > 0) {
+		const content = (bugs.rows as any[])
+			.map((b) => `- **${b.name}**: ${b.summary?.slice(0, 120) || "no summary"}`)
+			.join("\n");
+		sections.push({
+			title: "Known Issues",
+			content: `${(bugs.rows as any[]).length} known bugs to be aware of:\n\n${content}`,
+			entityCount: (bugs.rows as any[]).length,
+		});
+	}
+
+	// Section 5: Documentation
+	const docs = await db.execute(
+		`SELECT name, summary FROM graph_nodes
+		 WHERE type = 'FileNode' AND tags LIKE '%project-docs%' AND t_valid_until IS NULL
+		 ORDER BY importance DESC LIMIT 10`,
+	);
+	if ((docs.rows as any[]).length > 0) {
+		const content = (docs.rows as any[]).map((d) => `- ${d.name}`).join("\n");
+		sections.push({
+			title: "Ingested Documentation",
+			content: `${(docs.rows as any[]).length} docs in the knowledge graph:\n\n${content}`,
+			entityCount: (docs.rows as any[]).length,
+		});
+	}
+
+	return { totalEntities, totalEdges, sections };
+}
+
+export function formatTour(tour: TourResult): string {
+	const lines: string[] = [];
+	lines.push("=== SIA Knowledge Graph Tour ===\n");
+	lines.push(`Total: ${tour.totalEntities} entities, ${tour.totalEdges} edges\n`);
+
+	for (const section of tour.sections) {
+		lines.push(`--- ${section.title} ---`);
+		lines.push(section.content);
+		lines.push("");
+	}
+
+	if (tour.sections.length === 0) {
+		lines.push("The knowledge graph is empty. Run /sia-learn to populate it.");
+	}
+
+	lines.push("--- Next Steps ---");
+	lines.push("- Ask any question — SIA tools activate automatically");
+	lines.push("- /sia-search — search the knowledge graph");
+	lines.push("- /sia-status — detailed graph health");
+	lines.push("- /sia-visualize-live — interactive browser visualization");
+
+	return lines.join("\n");
+}
+
+export async function runTour(_args: string[]): Promise<void> {
+	const { resolveRepoHash } = await import("@/capture/hook");
+	const { openGraphDb } = await import("@/graph/semantic-db");
+	const { resolveSiaHome } = await import("@/shared/config");
+
+	const repoHash = resolveRepoHash(process.cwd());
+	const siaHome = resolveSiaHome();
+	const db = openGraphDb(repoHash, siaHome);
+
+	try {
+		const tour = await generateTour(db);
+		console.log(formatTour(tour));
+	} finally {
+		await db.close();
+	}
+}