@rkarim08/sia 1.0.0

package/src/shared/config.ts

@@ -0,0 +1,302 @@
+// Module: config — SIA_HOME constant, SiaConfig, and config loading
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join } from "node:path";
+
+/**
+ * Resolve the SIA home directory.
+ * In Claude Code plugin mode, uses CLAUDE_PLUGIN_DATA for persistent storage.
+ * In standalone mode, falls back to ~/.sia.
+ *
+ * Note: SIA_HOME is evaluated once at module load time. If using
+ * CLAUDE_PLUGIN_DATA, ensure it is set before this module is first imported.
+ */
+export function resolveSiaHome(): string {
+	const pluginData = process.env.CLAUDE_PLUGIN_DATA;
+	if (pluginData !== undefined && pluginData !== "") {
+		if (!isAbsolute(pluginData)) {
+			throw new Error(`CLAUDE_PLUGIN_DATA must be an absolute path, got: "${pluginData}"`);
+		}
+		return pluginData;
+	}
+	return join(homedir(), ".sia");
+}
+
+export const SIA_HOME: string = resolveSiaHome();
+
+/** Configuration for optional sync/replication via @libsql/client. */
+export interface SyncConfig {
+	enabled: boolean;
+	serverUrl: string | null;
+	developerId: string | null;
+	syncInterval: number;
+}
+
+/** Default SyncConfig — sync disabled, no remote. */
+export const DEFAULT_SYNC_CONFIG: SyncConfig = {
+	enabled: false,
+	serverUrl: null,
+	developerId: null,
+	syncInterval: 30,
+};
+
+/** Decay half-life configuration keyed by entity type. */
+export interface DecayHalfLife {
+	default: number;
+	Decision: number;
+	Convention: number;
+	Bug: number;
+	Solution: number;
+}
+
+/** Additional language definition for the language registry. */
+export interface AdditionalLanguage {
+	name: string;
+	extensions: string[];
+	grammar: string;
+	tier: string;
+}
+
+/** Configuration for the tree-sitter parser integration. */
+export interface TreeSitterConfig {
+	enabled: boolean;
+	preferNative: boolean;
+	parseTimeoutMs: number;
+	maxCachedTrees: number;
+	wasmDir: string;
+	queryDir: string;
+}
+
+/** Full Sia configuration matching ARCHI section 11. */
+export interface SiaConfig {
+	repoDir: string;
+	modelPath: string;
+	astCacheDir: string;
+	snapshotDir: string;
+	logDir: string;
+	excludePaths?: string[];
+
+	captureModel: string;
+	minExtractConfidence: number;
+	stagingPromotionConfidence: number;
+
+	decayHalfLife: DecayHalfLife;
+	archiveThreshold: number;
+	maxResponseTokens: number;
+	workingMemoryTokenBudget: number;
+	communityTriggerNodeCount: number;
+	communityMinGraphSize: number;
+
+	paranoidCapture: boolean;
+
+	enableFlagging: boolean;
+	flaggedConfidenceThreshold: number;
+	flaggedImportanceBoost: number;
+
+	airGapped: boolean;
+
+	/** Maintenance scheduler: time threshold before startup catchup triggers (ms). Default 24h. */
+	maintenanceInterval: number;
+	/** Maintenance scheduler: idle gap before opportunistic maintenance starts (ms). Default 60s. */
+	idleTimeoutMs: number;
+	/** Maintenance scheduler: minimum gap between LLM deep validation calls (ms). Default 5s. */
+	deepValidationRateMs: number;
+
+	additionalLanguages: AdditionalLanguage[];
+
+	treeSitter?: TreeSitterConfig;
+
+	claudeMdUpdatedAt: string | null;
+
+	sync: SyncConfig;
+
+	// Sandbox execution
+	sandboxTimeoutMs: number;
+	sandboxOutputMaxBytes: number;
+	contextModeThreshold: number;
+	contextModeTopK: number;
+	// Throttle
+	throttleNormalMax: number;
+	throttleReducedMax: number;
+	// Upgrade
+	upgradeReleaseUrl: string | null;
+}
+
+/** Valid keys for the decayHalfLife object. */
+const VALID_DECAY_KEYS: ReadonlySet<string> = new Set([
+	"default",
+	"Decision",
+	"Convention",
+	"Bug",
+	"Solution",
+]);
+
+/** Default configuration matching ARCHI section 11 values. */
+export const DEFAULT_CONFIG: SiaConfig = {
+	repoDir: join(SIA_HOME, "repos"),
+	modelPath: join(SIA_HOME, "models", "all-MiniLM-L6-v2.onnx"),
+	astCacheDir: join(SIA_HOME, "ast-cache"),
+	snapshotDir: join(SIA_HOME, "snapshots"),
+	logDir: join(SIA_HOME, "logs"),
+	excludePaths: [],
+
+	captureModel: "claude-haiku-4-5-20251001",
+	minExtractConfidence: 0.6,
+	stagingPromotionConfidence: 0.75,
+
+	decayHalfLife: {
+		default: 30,
+		Decision: 90,
+		Convention: 60,
+		Bug: 45,
+		Solution: 45,
+	},
+	archiveThreshold: 0.05,
+	maxResponseTokens: 1500,
+	workingMemoryTokenBudget: 8000,
+	communityTriggerNodeCount: 20,
+	communityMinGraphSize: 100,
+
+	paranoidCapture: false,
+
+	enableFlagging: false,
+	flaggedConfidenceThreshold: 0.4,
+	flaggedImportanceBoost: 0.15,
+
+	airGapped: false,
+
+	maintenanceInterval: 86400000, // 24 hours
+	idleTimeoutMs: 60000, // 60 seconds
+	deepValidationRateMs: 5000, // 5 seconds
+
+	additionalLanguages: [],
+
+	treeSitter: {
+		enabled: true,
+		preferNative: true,
+		parseTimeoutMs: 5000,
+		maxCachedTrees: 500,
+		wasmDir: join(__dirname, "../../grammars/wasm"),
+		queryDir: join(__dirname, "../../grammars/queries"),
+	},
+
+	claudeMdUpdatedAt: null,
+
+	sync: { ...DEFAULT_SYNC_CONFIG },
+
+	sandboxTimeoutMs: 30_000,
+	sandboxOutputMaxBytes: 1_048_576,
+	contextModeThreshold: 10_240,
+	contextModeTopK: 5,
+	throttleNormalMax: 3,
+	throttleReducedMax: 8,
+	upgradeReleaseUrl: null,
+};
+
+/**
+ * Deep-merge source into target, returning a new object.
+ * Arrays from source replace target arrays (no concatenation).
+ */
+function deepMerge<T extends Record<string, unknown>>(
+	target: T,
+	source: Record<string, unknown>,
+): T {
+	const result = { ...target } as Record<string, unknown>;
+	for (const key of Object.keys(source)) {
+		const srcVal = source[key];
+		const tgtVal = (target as Record<string, unknown>)[key];
+		if (
+			srcVal !== null &&
+			typeof srcVal === "object" &&
+			!Array.isArray(srcVal) &&
+			tgtVal !== null &&
+			typeof tgtVal === "object" &&
+			!Array.isArray(tgtVal)
+		) {
+			result[key] = deepMerge(tgtVal as Record<string, unknown>, srcVal as Record<string, unknown>);
+		} else {
+			result[key] = srcVal;
+		}
+	}
+	return result as T;
+}
+
+/**
+ * Validate decayHalfLife keys. Warns on invalid keys such as 'Architecture'.
+ */
+function validateDecayHalfLife(decayHalfLife: Record<string, unknown>): void {
+	for (const key of Object.keys(decayHalfLife)) {
+		if (!VALID_DECAY_KEYS.has(key)) {
+			if (key === "Architecture") {
+				console.warn(
+					"Architecture is not a valid entity type. Use Concept with tags: ['architecture'].",
+				);
+			} else {
+				console.warn(
+					`Invalid decayHalfLife key: '${key}'. Valid keys are: ${[...VALID_DECAY_KEYS].join(", ")}.`,
+				);
+			}
+		}
+	}
+}
+
+/**
+ * Load Sia configuration from disk, merging with defaults.
+ * If the config file does not exist, returns DEFAULT_CONFIG.
+ */
+export function getConfig(siaHome: string = SIA_HOME): SiaConfig {
+	const configPath = join(siaHome, "config.json");
+
+	if (!existsSync(configPath)) {
+		return { ...DEFAULT_CONFIG, sync: { ...DEFAULT_SYNC_CONFIG } };
+	}
+
+	const raw = readFileSync(configPath, "utf-8");
+	let parsed: Record<string, unknown>;
+	try {
+		parsed = JSON.parse(raw) as Record<string, unknown>;
+	} catch (err) {
+		throw new Error(
+			`Failed to parse Sia config at ${configPath}: ${err instanceof Error ? err.message : String(err)}. Delete or fix the file to use defaults.`,
+		);
+	}
+
+	if (
+		parsed.decayHalfLife &&
+		typeof parsed.decayHalfLife === "object" &&
+		!Array.isArray(parsed.decayHalfLife)
+	) {
+		validateDecayHalfLife(parsed.decayHalfLife as Record<string, unknown>);
+	}
+
+	return deepMerge({ ...DEFAULT_CONFIG, sync: { ...DEFAULT_SYNC_CONFIG } }, parsed);
+}
+
+/**
+ * Write a partial config update to disk.
+ * Reads existing config, deep-merges the partial, and writes the result.
+ * Creates the directory and file if they do not exist.
+ */
+export function writeConfig(partial: Partial<SiaConfig>, siaHome: string = SIA_HOME): void {
+	const configPath = join(siaHome, "config.json");
+	const dir = dirname(configPath);
+
+	if (!existsSync(dir)) {
+		mkdirSync(dir, { recursive: true });
+	}
+
+	let existing: Record<string, unknown> = {};
+	if (existsSync(configPath)) {
+		const raw = readFileSync(configPath, "utf-8");
+		try {
+			existing = JSON.parse(raw) as Record<string, unknown>;
+		} catch (err) {
+			throw new Error(
+				`Failed to parse existing Sia config at ${configPath}: ${err instanceof Error ? err.message : String(err)}. Delete or fix the file before writing new config.`,
+			);
+		}
+	}
+
+	const merged = deepMerge(existing, partial as Record<string, unknown>);
+	writeFileSync(configPath, JSON.stringify(merged, null, 2), "utf-8");
+}

package/src/shared/diagnostics.ts

@@ -0,0 +1,210 @@
+// Module: diagnostics — Reusable diagnostic check functions for sia_doctor
+
+import { spawn } from "node:child_process";
+import type { SiaDb } from "@/graph/db-interface";
+
+// ---------------------------------------------------------------------------
+// DiagnosticCheck interface
+// ---------------------------------------------------------------------------
+
+export interface DiagnosticCheck {
+	name: string;
+	category: string;
+	status: "ok" | "warn" | "error";
+	message: string;
+	version?: string;
+}
+
+// ---------------------------------------------------------------------------
+// checkRuntime — spawn <binary> --version with 5s timeout
+// ---------------------------------------------------------------------------
+
+export async function checkRuntime(name: string, binary: string): Promise<DiagnosticCheck> {
+	return new Promise((resolve) => {
+		let timedOut = false;
+		let stdout = "";
+		let stderr = "";
+
+		const child = spawn(binary, ["--version"], {
+			stdio: ["ignore", "pipe", "pipe"],
+		});
+
+		const timer = setTimeout(() => {
+			timedOut = true;
+			child.kill("SIGKILL");
+		}, 5000);
+
+		child.stdout.on("data", (chunk: Buffer) => {
+			stdout += chunk.toString();
+		});
+
+		child.stderr.on("data", (chunk: Buffer) => {
+			stderr += chunk.toString();
+		});
+
+		child.on("close", (code) => {
+			clearTimeout(timer);
+
+			if (timedOut) {
+				resolve({
+					name,
+					category: "runtimes",
+					status: "warn",
+					message: `${binary} timed out after 5s`,
+				});
+				return;
+			}
+
+			if (code === 0 || stdout.length > 0 || stderr.length > 0) {
+				// Many tools print version to stderr (e.g. go, rustc)
+				const raw = (stdout || stderr).trim();
+				// Extract first line as version string
+				const version = raw.split("\n")[0]?.trim() ?? raw;
+
+				if (code === 0 || version.length > 0) {
+					resolve({
+						name,
+						category: "runtimes",
+						status: "ok",
+						message: `${binary} is available`,
+						version: version || undefined,
+					});
+					return;
+				}
+			}
+
+			resolve({
+				name,
+				category: "runtimes",
+				status: "warn",
+				message: `${binary} not found or returned exit code ${code}`,
+			});
+		});
+
+		child.on("error", () => {
+			clearTimeout(timer);
+			resolve({
+				name,
+				category: "runtimes",
+				status: "warn",
+				message: `${binary} not found`,
+			});
+		});
+	});
+}
+
+// ---------------------------------------------------------------------------
+// checkFts5 — verify FTS5 virtual table is accessible
+// ---------------------------------------------------------------------------
+
+export async function checkFts5(db: SiaDb): Promise<DiagnosticCheck> {
+	// Try graph_nodes_fts first (v5 schema), fallback to entities_fts (v1 schema)
+	for (const table of ["graph_nodes_fts", "entities_fts"]) {
+		try {
+			await db.execute(`SELECT * FROM ${table} LIMIT 1`);
+			return {
+				name: "fts5",
+				category: "fts5",
+				status: "ok",
+				message: `FTS5 index (${table}) is accessible`,
+			};
+		} catch (err: unknown) {
+			const msg = (err as Error).message ?? String(err);
+			if (!msg.includes("no such table")) {
+				return {
+					name: "fts5",
+					category: "fts5",
+					status: "error",
+					message: `FTS5 check failed: ${msg}`,
+				};
+			}
+			// Table doesn't exist — try next table
+		}
+	}
+
+	return {
+		name: "fts5",
+		category: "fts5",
+		status: "warn",
+		message: "FTS5 index not found (neither graph_nodes_fts nor entities_fts exists)",
+	};
+}
+
+// ---------------------------------------------------------------------------
+// checkOrphanEdges — count edges where from_id/to_id don't exist in graph_nodes
+// ---------------------------------------------------------------------------
+
+export async function checkOrphanEdges(db: SiaDb): Promise<DiagnosticCheck> {
+	try {
+		const { rows } = await db.execute(`
+			SELECT COUNT(*) as count FROM graph_edges
+			WHERE from_id NOT IN (SELECT id FROM graph_nodes)
+			   OR to_id   NOT IN (SELECT id FROM graph_nodes)
+		`);
+
+		const count = (rows[0]?.count as number) ?? 0;
+
+		if (count > 0) {
+			return {
+				name: "orphan_edges",
+				category: "graph_integrity",
+				status: "warn",
+				message: `${count} edge(s) reference nonexistent graph_nodes`,
+			};
+		}
+
+		return {
+			name: "orphan_edges",
+			category: "graph_integrity",
+			status: "ok",
+			message: "No orphan edges found",
+		};
+	} catch (err) {
+		return {
+			name: "orphan_edges",
+			category: "graph_integrity",
+			status: "error",
+			message: `Failed to check: ${(err as Error).message}`,
+		};
+	}
+}
+
+// ---------------------------------------------------------------------------
+// checkTemporalInvariants — count nodes where t_valid_from > t_valid_until
+// ---------------------------------------------------------------------------
+
+export async function checkTemporalInvariants(db: SiaDb): Promise<DiagnosticCheck> {
+	try {
+		const { rows } = await db.execute(`
+			SELECT COUNT(*) as count FROM graph_nodes
+			WHERE t_valid_from IS NOT NULL
+			  AND t_valid_until IS NOT NULL
+			  AND t_valid_from > t_valid_until
+		`);
+
+		const count = (rows[0]?.count as number) ?? 0;
+
+		if (count > 0) {
+			return {
+				name: "temporal_invariants",
+				category: "graph_integrity",
+				status: "error",
+				message: `${count} node(s) have t_valid_from > t_valid_until (temporal invariant violated)`,
+			};
+		}
+
+		return {
+			name: "temporal_invariants",
+			category: "graph_integrity",
+			status: "ok",
+			message: "Temporal invariants are valid",
+		};
+	} catch (err) {
+		return {
+			name: "temporal_invariants",
+			category: "graph_integrity",
+			status: "error",
+			message: `Failed to check: ${(err as Error).message}`,
+		};
+	}
+}

package/src/shared/errors.ts

@@ -0,0 +1,48 @@
+// Module: errors — Result type for fallible operations
+
+/** Structured error type for all Sia operations. */
+export interface SiaError {
+	code: string;
+	module: string;
+	operation: string;
+	message: string;
+	cause?: unknown;
+}
+
+/** Discriminated union: either success with data, or failure with error. */
+export type Result<T, E = SiaError> = { ok: true; value: T } | { ok: false; error: E };
+
+/** Create a successful result. */
+export function ok<T>(value: T): Result<T, never> {
+	return { ok: true, value };
+}
+
+/** Create a failure result. */
+export function err<E = SiaError>(error: E): Result<never, E> {
+	return { ok: false, error };
+}
+
+/** Create a SiaError. */
+export function siaError(
+	code: string,
+	module: string,
+	operation: string,
+	message: string,
+	cause?: unknown,
+): SiaError {
+	return { code, module, operation, message, cause };
+}
+
+/** Wrap a promise in a Result, catching any thrown error. */
+export async function tryCatch<T>(
+	fn: () => Promise<T>,
+	module: string,
+	operation: string,
+): Promise<Result<T>> {
+	try {
+		return ok(await fn());
+	} catch (cause) {
+		const message = cause instanceof Error ? cause.message : String(cause);
+		return err(siaError("UNHANDLED", module, operation, message, cause));
+	}
+}

package/src/shared/git-utils.ts

@@ -0,0 +1,143 @@
+// Module: git-utils — Git worktree detection and path resolution
+
+import { execFileSync } from "node:child_process";
+import { join } from "node:path";
+
+/**
+ * Resolve the root directory of the current git worktree (or main checkout).
+ * Uses `git rev-parse --show-toplevel` which returns the worktree root
+ * when inside a worktree, or the main checkout root in a normal repo.
+ * Returns null if not in a git repo.
+ */
+export function resolveWorktreeRoot(cwd?: string): string | null {
+	try {
+		return execFileSync("git", ["rev-parse", "--show-toplevel"], {
+			cwd: cwd ?? process.cwd(),
+			encoding: "utf-8",
+			stdio: ["pipe", "pipe", "pipe"],
+		}).trim();
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Check if the current directory is inside a git worktree (not the main checkout).
+ * Compares --git-dir with --git-common-dir. In a worktree, git-dir points to
+ * .git/worktrees/<name> while git-common-dir points to the main .git.
+ */
+export function isWorktree(cwd?: string): boolean {
+	try {
+		const execOpts = {
+			cwd: cwd ?? process.cwd(),
+			encoding: "utf-8" as const,
+			stdio: ["pipe", "pipe", "pipe"] as ["pipe", "pipe", "pipe"],
+		};
+		const gitDir = execFileSync("git", ["rev-parse", "--git-dir"], execOpts).trim();
+		const commonDir = execFileSync("git", ["rev-parse", "--git-common-dir"], execOpts).trim();
+		return gitDir !== commonDir && !gitDir.endsWith("/.git") && gitDir !== ".git";
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Get the current branch name.
+ * Returns empty string for detached HEAD.
+ */
+export function currentBranch(cwd?: string): string {
+	try {
+		return execFileSync("git", ["branch", "--show-current"], {
+			cwd: cwd ?? process.cwd(),
+			encoding: "utf-8",
+			stdio: ["pipe", "pipe", "pipe"],
+		}).trim();
+	} catch {
+		return "";
+	}
+}
+
+/**
+ * Get the previous branch name (the branch checked out before the current one).
+ * Uses `git rev-parse --abbrev-ref @{-1}` which reads the reflog.
+ * Returns empty string if unavailable (e.g., fresh repo, no prior checkout).
+ */
+export function previousBranch(cwd?: string): string {
+	try {
+		return execFileSync("git", ["rev-parse", "--abbrev-ref", "@{-1}"], {
+			cwd: cwd ?? process.cwd(),
+			encoding: "utf-8",
+			stdio: ["pipe", "pipe", "pipe"],
+		}).trim();
+	} catch {
+		return "";
+	}
+}
+
+/**
+ * Get the current HEAD commit hash (short form).
+ * Returns empty string if not in a git repo or on error.
+ */
+export function currentCommit(cwd?: string): string {
+	try {
+		return execFileSync("git", ["rev-parse", "--short", "HEAD"], {
+			cwd: cwd ?? process.cwd(),
+			encoding: "utf-8",
+			stdio: ["pipe", "pipe", "pipe"],
+		}).trim();
+	} catch {
+		return "";
+	}
+}
+
+/**
+ * Resolve the project-local graph database directory.
+ * Always `<worktree-root>/.sia-graph/`. Each worktree gets its own
+ * independent graph directory so parallel worktrees don't collide.
+ * Returns null if not inside a git repo.
+ */
+export function resolveProjectGraphDir(cwd?: string): string | null {
+	const root = resolveWorktreeRoot(cwd);
+	if (!root) return null;
+	return join(root, ".sia-graph");
+}
+
+/**
+ * Get the list of files changed between two refs (or between HEAD~1 and HEAD).
+ * Uses `git diff --name-status` which handles adds, mods, deletes, and renames.
+ */
+export function getChangedFiles(
+	fromRef?: string,
+	toRef?: string,
+	cwd?: string,
+): Array<{ status: string; path: string; oldPath?: string }> {
+	try {
+		const args = ["diff", "--name-status"];
+		if (fromRef && toRef) {
+			args.push(fromRef, toRef);
+		} else if (fromRef) {
+			args.push(fromRef, "HEAD");
+		} else {
+			args.push("HEAD~1", "HEAD");
+		}
+
+		const output = execFileSync("git", args, {
+			cwd: cwd ?? process.cwd(),
+			encoding: "utf-8",
+			stdio: ["pipe", "pipe", "pipe"],
+		}).trim();
+
+		if (!output) return [];
+
+		return output.split("\n").map((line) => {
+			const parts = line.split("\t");
+			const status = parts[0].charAt(0);
+			if (status === "R" && parts.length >= 3) {
+				return { status, path: parts[2], oldPath: parts[1] };
+			}
+			return { status, path: parts[1] ?? parts[0] };
+		});
+	} catch {
+		return [];
+	}
+}