@rkarim08/sia 1.0.0

package/src/cli/commands/conflicts.ts

@@ -0,0 +1,41 @@
+// Module: conflicts — conflict listing and resolution
+
+import type { SiaDb } from "@/graph/db-interface";
+import { invalidateEntity } from "@/graph/entities";
+
+export async function listConflicts(db: SiaDb): Promise<Record<string, string[]>> {
+	const rows = await db.execute(
+		"SELECT conflict_group_id, id FROM graph_nodes WHERE conflict_group_id IS NOT NULL AND archived_at IS NULL AND t_valid_until IS NULL",
+	);
+	const groups: Record<string, string[]> = {};
+	for (const row of rows.rows as Array<{ conflict_group_id: string; id: string }>) {
+		if (!groups[row.conflict_group_id]) groups[row.conflict_group_id] = [];
+		groups[row.conflict_group_id].push(row.id);
+	}
+	return groups;
+}
+
+export async function resolveConflict(
+	db: SiaDb,
+	groupId: string,
+	keepEntityId: string,
+): Promise<void> {
+	const keepRow = await db.execute(
+		"SELECT id FROM graph_nodes WHERE id = ? AND conflict_group_id = ?",
+		[keepEntityId, groupId],
+	);
+	if (keepRow.rows.length === 0) {
+		throw new Error(`Entity '${keepEntityId}' not found in conflict group '${groupId}'`);
+	}
+
+	const rows = await db.execute("SELECT id FROM graph_nodes WHERE conflict_group_id = ?", [
+		groupId,
+	]);
+	for (const row of rows.rows as Array<{ id: string }>) {
+		if (row.id === keepEntityId) continue;
+		await invalidateEntity(db, row.id);
+	}
+	await db.execute("UPDATE graph_nodes SET conflict_group_id = NULL WHERE conflict_group_id = ?", [
+		groupId,
+	]);
+}

package/src/cli/commands/digest.ts

@@ -0,0 +1,197 @@
+// Module: digest — Knowledge digest generator for graph activity summaries
+
+import type { SiaDb } from "@/graph/db-interface";
+
+export type DigestPeriod = "daily" | "weekly" | "monthly" | "custom";
+
+export interface DigestOpts {
+	period?: DigestPeriod;
+	startDate?: number; // Unix ms
+	endDate?: number; // Unix ms
+}
+
+export interface DigestSection {
+	title: string;
+	items: DigestItem[];
+}
+
+export interface DigestItem {
+	id: string;
+	name: string;
+	type: string;
+	summary: string;
+	created_at: number;
+}
+
+export interface DigestResult {
+	period: DigestPeriod;
+	startDate: number;
+	endDate: number;
+	sections: DigestSection[];
+	totalEntities: number;
+}
+
+/** Map entity type to human-readable section title. */
+const TYPE_TITLES: Record<string, string> = {
+	Decision: "Decisions Captured",
+	Convention: "Conventions Established",
+	Bug: "Bugs Identified",
+	Solution: "Solutions Found",
+	Concept: "Concepts Added",
+	FileNode: "Files Indexed",
+	ContentChunk: "Documentation Chunks",
+};
+
+/** Ordered list of types so sections appear in a stable order. */
+const TYPE_ORDER: string[] = [
+	"Decision",
+	"Convention",
+	"Bug",
+	"Solution",
+	"Concept",
+	"FileNode",
+	"ContentChunk",
+];
+
+const MS_PER_DAY = 86_400_000;
+
+/**
+ * Compute the start/end timestamps for a named period.
+ * "custom" requires explicit startDate/endDate in opts.
+ */
+function resolveTimeRange(opts?: DigestOpts): {
+	period: DigestPeriod;
+	startDate: number;
+	endDate: number;
+} {
+	const now = Date.now();
+	const period = opts?.period ?? "weekly";
+	const endDate = opts?.endDate ?? now;
+
+	if (period === "custom") {
+		if (opts?.startDate == null || opts?.endDate == null) {
+			throw new Error("Custom period requires both startDate and endDate");
+		}
+		return { period, startDate: opts.startDate, endDate: opts.endDate };
+	}
+
+	let startDate: number;
+	switch (period) {
+		case "daily":
+			startDate = endDate - MS_PER_DAY;
+			break;
+		case "monthly":
+			startDate = endDate - 30 * MS_PER_DAY;
+			break;
+		default:
+			startDate = endDate - 7 * MS_PER_DAY;
+			break;
+	}
+
+	return { period, startDate, endDate };
+}
+
+/**
+ * Generate a knowledge digest for the specified time period.
+ * Queries the graph for entities created within the period, grouped by type.
+ */
+export async function generateDigest(db: SiaDb, opts?: DigestOpts): Promise<DigestResult> {
+	const { period, startDate, endDate } = resolveTimeRange(opts);
+
+	const { rows } = await db.execute(
+		`SELECT id, type, name, summary, created_at FROM graph_nodes
+		 WHERE created_at >= ? AND created_at <= ?
+		   AND t_valid_until IS NULL AND archived_at IS NULL
+		 ORDER BY type, importance DESC`,
+		[startDate, endDate],
+	);
+
+	// Group rows by type
+	const grouped = new Map<string, DigestItem[]>();
+	for (const row of rows) {
+		const type = row.type as string;
+		const item: DigestItem = {
+			id: row.id as string,
+			name: row.name as string,
+			type,
+			summary: row.summary as string,
+			created_at: row.created_at as number,
+		};
+		const list = grouped.get(type);
+		if (list) {
+			list.push(item);
+		} else {
+			grouped.set(type, [item]);
+		}
+	}
+
+	// Build sections in stable order, only including non-empty ones
+	const sections: DigestSection[] = [];
+	for (const type of TYPE_ORDER) {
+		const items = grouped.get(type);
+		if (items && items.length > 0) {
+			sections.push({
+				title: TYPE_TITLES[type] ?? type,
+				items,
+			});
+		}
+	}
+
+	// Include any types not in TYPE_ORDER (future entity types)
+	for (const [type, items] of grouped) {
+		if (!TYPE_ORDER.includes(type) && items.length > 0) {
+			sections.push({
+				title: TYPE_TITLES[type] ?? type,
+				items,
+			});
+		}
+	}
+
+	const totalEntities = rows.length;
+
+	return {
+		period,
+		startDate,
+		endDate,
+		sections,
+		totalEntities,
+	};
+}
+
+/**
+ * Format a Unix-ms timestamp as an ISO date string (date portion only).
+ */
+function formatDate(ms: number): string {
+	return new Date(ms).toISOString().slice(0, 10);
+}
+
+/**
+ * Render a digest as markdown text.
+ */
+export function renderDigestMarkdown(digest: DigestResult): string {
+	const lines: string[] = [];
+
+	lines.push(`# Knowledge Digest — ${digest.period}`);
+	lines.push("");
+	lines.push(`**Period:** ${formatDate(digest.startDate)} to ${formatDate(digest.endDate)}`);
+	lines.push("");
+	lines.push(`**Total new entities:** ${digest.totalEntities}`);
+
+	for (const section of digest.sections) {
+		const items = section.items.slice(0, 10);
+		lines.push("");
+		lines.push(`## ${section.title} (${section.items.length})`);
+		lines.push("");
+		lines.push("| Name | Summary |");
+		lines.push("|------|---------|");
+		for (const item of items) {
+			// Escape pipes in name/summary to avoid breaking the table
+			const name = item.name.replace(/\|/g, "\\|");
+			const summary = item.summary.replace(/\|/g, "\\|");
+			lines.push(`| ${name} | ${summary} |`);
+		}
+	}
+
+	lines.push("");
+	return lines.join("\n");
+}

package/src/cli/commands/disable-flagging.ts

@@ -0,0 +1,34 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { getConfig, writeConfig } from "@/shared/config";
+
+/**
+ * Disable the sia_flag capture pathway.
+ *
+ * 1. Persists `enableFlagging: false` in config.
+ * 2. Swaps the installed CLAUDE.md back to the base template
+ *    (Step 4 reverts to the conditional check).
+ *
+ * Idempotent — running twice is a no-op.
+ */
+export async function disableFlagging(opts?: { siaHome?: string; cwd?: string }): Promise<void> {
+	const config = getConfig(opts?.siaHome);
+
+	if (config.enableFlagging === false) {
+		return;
+	}
+
+	writeConfig({ enableFlagging: false }, opts?.siaHome);
+
+	// Resolve the base template relative to *this* file's directory.
+	const templatePath = resolve(import.meta.dirname, "../../agent/claude-md-template.md");
+	const template = readFileSync(templatePath, "utf-8");
+
+	const cwd = opts?.cwd ?? process.cwd();
+	const claudeDir = join(cwd, ".claude");
+	mkdirSync(claudeDir, { recursive: true });
+
+	writeFileSync(join(claudeDir, "CLAUDE.md"), template, "utf-8");
+
+	console.log("Flagging disabled. CLAUDE.md restored to base template.");
+}

package/src/cli/commands/doctor.ts

@@ -0,0 +1,240 @@
+// Module: doctor — System health check with hook + provider diagnostics
+//
+// `npx sia doctor` reports overall system health.
+// `npx sia doctor --providers` adds LLM provider connectivity checks.
+//
+// Checks: runtimes, hooks, capture mode, FTS5, ONNX model, native module,
+// community detection backend, graph integrity, inverted dependency index,
+// and (optionally) LLM provider health.
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import type { SiaDb } from "@/graph/db-interface";
+import { detectAgent, getRecommendedCaptureMode } from "@/hooks/agent-detect";
+import { getHookConfig } from "@/hooks/event-router";
+import { getDefaultLlmConfig } from "@/llm/config";
+import type { OperationRole } from "@/llm/provider-registry";
+import { isNativeAvailable } from "@/native/bridge";
+
+export interface DoctorCheck {
+	name: string;
+	status: "ok" | "warn" | "error";
+	message: string;
+}
+
+export interface DoctorReport {
+	checks: DoctorCheck[];
+	captureMode: string;
+	agent: string;
+	nativeModule: string;
+	communityBackend: string;
+	hookHealth: Array<{ event: string; type: string; status: string }>;
+	providerHealth: Array<{
+		role: string;
+		provider: string;
+		model: string;
+		status: string;
+	}>;
+}
+
+/**
+ * Run the full doctor diagnostic suite.
+ */
+export async function runDoctor(
+	db: SiaDb | null,
+	cwd: string,
+	options?: { providers?: boolean },
+): Promise<DoctorReport> {
+	const checks: DoctorCheck[] = [];
+
+	// 1. Detect agent
+	const agent = detectAgent(cwd);
+	const captureMode = getRecommendedCaptureMode(agent);
+	checks.push({
+		name: "Agent detection",
+		status: "ok",
+		message: `Detected: ${agent} (capture mode: ${captureMode})`,
+	});
+
+	// 2. Native module
+	const nativeStatus = isNativeAvailable();
+	checks.push({
+		name: "Native module",
+		status: nativeStatus === "typescript" ? "warn" : "ok",
+		message:
+			nativeStatus === "typescript"
+				? "Using TypeScript fallbacks (install @sia/native for 5-20x faster AST diffing)"
+				: `Loaded: ${nativeStatus}`,
+	});
+
+	// 3. Community detection backend
+	const communityBackend =
+		nativeStatus !== "typescript" ? "Rust Leiden via graphrs" : "JavaScript Louvain (in-process)";
+	checks.push({
+		name: "Community detection",
+		status: "ok",
+		message: communityBackend,
+	});
+
+	// 4. ONNX model
+	const modelPath = join(
+		process.env.SIA_HOME ?? join(process.env.HOME ?? "~", ".sia"),
+		"models",
+		"all-MiniLM-L6-v2.onnx",
+	);
+	const modelExists = existsSync(modelPath);
+	checks.push({
+		name: "ONNX embedding model",
+		status: modelExists ? "ok" : "warn",
+		message: modelExists
+			? `Found at ${modelPath}`
+			: `Not found at ${modelPath} — run npx sia download-model`,
+	});
+
+	// 5. Graph integrity (if DB available)
+	if (db) {
+		try {
+			const { rows: entityCount } = await db.execute("SELECT COUNT(*) as cnt FROM graph_nodes", []);
+			const { rows: edgeCount } = await db.execute("SELECT COUNT(*) as cnt FROM graph_edges", []);
+			const entities = (entityCount[0] as { cnt: number }).cnt;
+			const edges = (edgeCount[0] as { cnt: number }).cnt;
+			checks.push({
+				name: "Graph integrity",
+				status: "ok",
+				message: `${entities} entities, ${edges} edges`,
+			});
+
+			// Check for orphan edges
+			const { rows: orphans } = await db.execute(
+				`SELECT COUNT(*) as cnt FROM graph_edges e
+				 WHERE NOT EXISTS (SELECT 1 FROM graph_nodes WHERE id = e.from_id)
+				    OR NOT EXISTS (SELECT 1 FROM graph_nodes WHERE id = e.to_id)`,
+				[],
+			);
+			const orphanCount = (orphans[0] as { cnt: number }).cnt;
+			if (orphanCount > 0) {
+				checks.push({
+					name: "Orphan edges",
+					status: "warn",
+					message: `${orphanCount} edges reference non-existent entities`,
+				});
+			}
+
+			// Check FTS5
+			try {
+				await db.execute("SELECT COUNT(*) FROM graph_nodes_fts", []);
+				checks.push({ name: "FTS5 index", status: "ok", message: "Operational" });
+			} catch {
+				checks.push({ name: "FTS5 index", status: "error", message: "Not available" });
+			}
+
+			// Check source_deps (inverted index)
+			try {
+				const { rows: depCount } = await db.execute("SELECT COUNT(*) as cnt FROM source_deps", []);
+				const deps = (depCount[0] as { cnt: number }).cnt;
+				checks.push({
+					name: "Inverted dependency index",
+					status: deps > 0 ? "ok" : "warn",
+					message: `${deps} source-to-node mappings`,
+				});
+			} catch {
+				checks.push({
+					name: "Inverted dependency index",
+					status: "warn",
+					message: "source_deps table not found — run npx sia reindex",
+				});
+			}
+		} catch (err) {
+			checks.push({
+				name: "Graph integrity",
+				status: "error",
+				message: `Failed to query graph: ${err instanceof Error ? err.message : String(err)}`,
+			});
+		}
+	}
+
+	// 6. Hook health
+	const hookConfig = getHookConfig();
+	const hookHealth = Object.entries(hookConfig).map(([event, configs]) => {
+		const config = configs[0] as Record<string, unknown>;
+		const type = config.type as string;
+		// We can't actually test HTTP connectivity here without the server running,
+		// so we report the configuration status
+		return {
+			event,
+			type,
+			status:
+				type === "command"
+					? "configured (command)"
+					: `configured (${config.async ? "async" : "sync"})`,
+		};
+	});
+
+	// 7. Provider health (only if --providers flag)
+	const providerHealth: DoctorReport["providerHealth"] = [];
+	if (options?.providers) {
+		const config = getDefaultLlmConfig();
+		const roles: OperationRole[] = ["summarize", "validate", "extract", "consolidate"];
+
+		for (const role of roles) {
+			const providerConfig = config.providers[role];
+			const isStandby = captureMode === "hooks" && (role === "extract" || role === "consolidate");
+
+			providerHealth.push({
+				role,
+				provider: providerConfig?.provider ?? "not configured",
+				model: providerConfig?.model ?? "not configured",
+				status: isStandby ? "standby (hooks active)" : "configured",
+			});
+		}
+	}
+
+	return {
+		checks,
+		captureMode,
+		agent,
+		nativeModule: nativeStatus,
+		communityBackend,
+		hookHealth,
+		providerHealth,
+	};
+}
+
+/**
+ * Format the doctor report as human-readable output.
+ */
+export function formatDoctorReport(report: DoctorReport): string {
+	const lines: string[] = [];
+
+	lines.push("Sia Doctor Report");
+	lines.push("═".repeat(50));
+	lines.push(`Capture Mode: ${report.captureMode} (${report.agent} detected)`);
+	lines.push("");
+
+	// Checks
+	for (const check of report.checks) {
+		const icon = check.status === "ok" ? "✓" : check.status === "warn" ? "⚠" : "✗";
+		lines.push(`  ${icon} ${check.name}: ${check.message}`);
+	}
+
+	// Hook configuration
+	lines.push("");
+	lines.push("Hook Configuration:");
+	for (const hook of report.hookHealth) {
+		lines.push(`  ✓ ${hook.event}: ${hook.status}`);
+	}
+
+	// Provider health (if checked)
+	if (report.providerHealth.length > 0) {
+		lines.push("");
+		lines.push("LLM Providers:");
+		for (const provider of report.providerHealth) {
+			const icon = provider.status.includes("standby") ? "⚡" : "✓";
+			lines.push(
+				`  ${icon} ${provider.role}: ${provider.provider} / ${provider.model} — ${provider.status}`,
+			);
+		}
+	}
+
+	return lines.join("\n");
+}

package/src/cli/commands/download-model.ts

@@ -0,0 +1,161 @@
+// Module: download-model — downloads the all-MiniLM-L6-v2 ONNX model and tokenizer
+import { createHash } from "node:crypto";
+import {
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	renameSync,
+	statSync,
+	unlinkSync,
+	writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { SIA_HOME } from "@/shared/config";
+
+const MODEL_URL =
+	"https://huggingface.co/Xenova/all-MiniLM-L6-v2/resolve/main/onnx/model_quantized.onnx";
+const TOKENIZER_URL = "https://huggingface.co/Xenova/all-MiniLM-L6-v2/resolve/main/tokenizer.json";
+
+const MODEL_FILENAME = "all-MiniLM-L6-v2.onnx";
+const TOKENIZER_FILENAME = "tokenizer.json";
+
+/**
+ * Download a single file from `url` to `destPath`.
+ * Writes to a temporary file first, then renames to the final destination.
+ */
+async function downloadFile(url: string, destPath: string): Promise<void> {
+	const response = await fetch(url);
+	if (!response.ok) {
+		throw new Error(`Failed to download ${url}: ${response.status} ${response.statusText}`);
+	}
+
+	const contentLength = Number(response.headers.get("content-length") ?? 0);
+	const reader = response.body?.getReader();
+	if (!reader) {
+		throw new Error(`No response body for ${url}`);
+	}
+
+	const chunks: Uint8Array[] = [];
+	let received = 0;
+	let lastPercent = -1;
+
+	while (true) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		chunks.push(value);
+		received += value.length;
+
+		if (contentLength > 0) {
+			const percent = Math.floor((received / contentLength) * 100);
+			if (percent !== lastPercent && percent % 10 === 0) {
+				console.log(`Downloading ${destPath}... ${percent}%`);
+				lastPercent = percent;
+			}
+		}
+	}
+
+	// Concatenate chunks into a single buffer
+	const buffer = new Uint8Array(received);
+	let offset = 0;
+	for (const chunk of chunks) {
+		buffer.set(chunk, offset);
+		offset += chunk.length;
+	}
+
+	// Write to temp file first, then rename for atomicity
+	const tempPath = `${destPath}.tmp`;
+	writeFileSync(tempPath, buffer);
+	renameSync(tempPath, destPath);
+
+	console.log(`Downloaded ${destPath} (${received} bytes)`);
+}
+
+/**
+ * Verify the SHA-256 checksum of a file against an expected hash.
+ *
+ * If the hashes match, returns without error.
+ * If the hashes do not match, deletes the file and throws an error.
+ *
+ * @param filePath     Path to the file to verify.
+ * @param expectedHash Hex-encoded SHA-256 digest to compare against.
+ */
+export function verifyModelChecksum(filePath: string, expectedHash: string): void {
+	const fileBuffer = readFileSync(filePath);
+	const actualHash = createHash("sha256").update(fileBuffer).digest("hex");
+	if (actualHash !== expectedHash) {
+		unlinkSync(filePath);
+		throw new Error(
+			`Checksum mismatch for ${filePath}: expected ${expectedHash}, got ${actualHash}`,
+		);
+	}
+}
+
+/**
+ * Check whether a file exists and has size > 0.
+ */
+function fileExistsWithContent(filePath: string): boolean {
+	if (!existsSync(filePath)) return false;
+	const stats = statSync(filePath);
+	return stats.size > 0;
+}
+
+/**
+ * Download the all-MiniLM-L6-v2 ONNX model and its tokenizer.
+ *
+ * Files are saved to `{siaHome}/models/`.
+ * If both files already exist with size > 0, the download is skipped.
+ *
+ * @returns The path to the downloaded model file.
+ */
+export async function downloadModel(siaHome: string = SIA_HOME): Promise<string> {
+	const modelsDir = join(siaHome, "models");
+	const modelPath = join(modelsDir, MODEL_FILENAME);
+	const tokenizerPath = join(modelsDir, TOKENIZER_FILENAME);
+
+	// Ensure models directory exists
+	if (!existsSync(modelsDir)) {
+		mkdirSync(modelsDir, { recursive: true });
+	}
+
+	// Check if model already exists
+	if (fileExistsWithContent(modelPath) && fileExistsWithContent(tokenizerPath)) {
+		console.log("Model already downloaded");
+		return modelPath;
+	}
+
+	// Download model if needed
+	if (!fileExistsWithContent(modelPath)) {
+		console.log("Downloading ONNX model...");
+		await downloadFile(MODEL_URL, modelPath);
+		// TODO: Replace placeholder with the real SHA-256 hash from the HuggingFace model card:
+		// https://huggingface.co/Xenova/all-MiniLM-L6-v2/blob/main/onnx/model_quantized.onnx
+		const MODEL_EXPECTED_HASH = "CHECKSUM_NOT_YET_KNOWN";
+		if (MODEL_EXPECTED_HASH !== "CHECKSUM_NOT_YET_KNOWN") {
+			verifyModelChecksum(modelPath, MODEL_EXPECTED_HASH);
+		} else {
+			console.warn(
+				"[warn] Model checksum not configured — skipping integrity verification. " +
+					"Set the real SHA-256 hash in download-model.ts to enable verification.",
+			);
+		}
+	}
+
+	// Download tokenizer if needed
+	if (!fileExistsWithContent(tokenizerPath)) {
+		console.log("Downloading tokenizer...");
+		await downloadFile(TOKENIZER_URL, tokenizerPath);
+		// TODO: Replace placeholder with the real SHA-256 hash from the HuggingFace model card:
+		// https://huggingface.co/Xenova/all-MiniLM-L6-v2/blob/main/tokenizer.json
+		const TOKENIZER_EXPECTED_HASH = "CHECKSUM_NOT_YET_KNOWN";
+		if (TOKENIZER_EXPECTED_HASH !== "CHECKSUM_NOT_YET_KNOWN") {
+			verifyModelChecksum(tokenizerPath, TOKENIZER_EXPECTED_HASH);
+		} else {
+			console.warn(
+				"[warn] Tokenizer checksum not configured — skipping integrity verification. " +
+					"Set the real SHA-256 hash in download-model.ts to enable verification.",
+			);
+		}
+	}
+
+	return modelPath;
+}

package/src/cli/commands/enable-flagging.ts

@@ -0,0 +1,34 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { getConfig, writeConfig } from "@/shared/config";
+
+/**
+ * Enable the sia_flag capture pathway.
+ *
+ * 1. Persists `enableFlagging: true` in config.
+ * 2. Swaps the installed CLAUDE.md to the flagging-enabled template
+ *    (contains the expanded sia_flag section in Step 4).
+ *
+ * Idempotent — running twice is a no-op.
+ */
+export async function enableFlagging(opts?: { siaHome?: string; cwd?: string }): Promise<void> {
+	const config = getConfig(opts?.siaHome);
+
+	if (config.enableFlagging === true) {
+		return;
+	}
+
+	writeConfig({ enableFlagging: true }, opts?.siaHome);
+
+	// Resolve the flagging template relative to *this* file's directory.
+	const templatePath = resolve(import.meta.dirname, "../../agent/claude-md-template-flagging.md");
+	const template = readFileSync(templatePath, "utf-8");
+
+	const cwd = opts?.cwd ?? process.cwd();
+	const claudeDir = join(cwd, ".claude");
+	mkdirSync(claudeDir, { recursive: true });
+
+	writeFileSync(join(claudeDir, "CLAUDE.md"), template, "utf-8");
+
+	console.log("Flagging enabled. CLAUDE.md updated with sia_flag section.");
+}