@rkarim08/sia 1.0.0

package/src/cli/commands/qa-report.ts

@@ -0,0 +1,278 @@
+// Module: qa-report — Generate QA-focused testing intelligence report
+//
+// Queries the graph for bugs, solutions, decisions, and recent changes,
+// then produces a markdown report grouped by risk level with test
+// recommendations derived from bug history.
+
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { SiaDb } from "@/graph/db-interface";
+
+export interface QaReportOptions {
+	since?: number;
+	outputPath?: string;
+}
+
+interface EntityRow {
+	id: string;
+	type: string;
+	name: string;
+	content: string;
+	summary: string | null;
+	trust_tier: number;
+	importance: number;
+	created_at: number;
+	file_paths: string | null;
+	edge_count: number;
+}
+
+function formatDate(ms: number): string {
+	return new Date(ms).toISOString().split("T")[0];
+}
+
+function riskLevel(
+	bugCount: number,
+	recentCount: number,
+	edgeCount: number,
+): { label: string; score: number } {
+	// Weighted score: bug density 40%, change velocity 35%, dependency fan-out 25%
+	const bugScore = Math.min(bugCount * 20, 100);
+	const changeScore = Math.min(recentCount * 15, 100);
+	const edgeScore = Math.min(edgeCount * 5, 100);
+	const score = Math.round(bugScore * 0.4 + changeScore * 0.35 + edgeScore * 0.25);
+
+	if (score > 70) return { label: "HIGH", score };
+	if (score >= 40) return { label: "MEDIUM", score };
+	return { label: "LOW", score };
+}
+
+export async function generateQaReport(db: SiaDb, opts: QaReportOptions = {}): Promise<string> {
+	const since = opts.since ?? Date.now() - 86400000 * 14; // default: 14 days
+
+	// Query all active entities
+	const allResult = await db.execute(
+		"SELECT COUNT(*) as cnt FROM graph_nodes WHERE t_valid_until IS NULL AND archived_at IS NULL",
+	);
+	const totalEntities = (allResult.rows[0] as any).cnt;
+
+	if (totalEntities === 0) {
+		return `# QA Report\n\n*No entities in the knowledge graph yet. Run \`/sia-learn\` to build the graph.*\n`;
+	}
+
+	// Query bugs
+	const bugsResult = await db.execute(
+		`SELECT id, type, name, content, summary, trust_tier, importance, created_at, file_paths, edge_count
+		 FROM graph_nodes
+		 WHERE type = 'Bug' AND t_valid_until IS NULL AND archived_at IS NULL
+		 ORDER BY created_at DESC
+		 LIMIT 50`,
+	);
+	const bugs = bugsResult.rows as unknown as EntityRow[];
+
+	// Query solutions
+	const solutionsResult = await db.execute(
+		`SELECT id, type, name, content, summary, trust_tier, importance, created_at, file_paths, edge_count
+		 FROM graph_nodes
+		 WHERE type = 'Solution' AND t_valid_until IS NULL AND archived_at IS NULL
+		 ORDER BY created_at DESC
+		 LIMIT 50`,
+	);
+	const solutions = solutionsResult.rows as unknown as EntityRow[];
+
+	// Query recent decisions
+	const decisionsResult = await db.execute(
+		`SELECT id, type, name, content, summary, trust_tier, importance, created_at, file_paths, edge_count
+		 FROM graph_nodes
+		 WHERE type = 'Decision' AND t_valid_until IS NULL AND archived_at IS NULL AND created_at >= ?
+		 ORDER BY created_at DESC
+		 LIMIT 50`,
+		[since],
+	);
+	const recentDecisions = decisionsResult.rows as unknown as EntityRow[];
+
+	// Recent entities (all types)
+	const recentResult = await db.execute(
+		`SELECT id, type, name, content, summary, trust_tier, importance, created_at, file_paths, edge_count
+		 FROM graph_nodes
+		 WHERE t_valid_until IS NULL AND archived_at IS NULL AND created_at >= ?
+		 ORDER BY created_at DESC
+		 LIMIT 100`,
+		[since],
+	);
+	const recentEntities = recentResult.rows as unknown as EntityRow[];
+
+	const recentBugs = bugs.filter((b) => b.created_at >= since);
+	const totalEdgeCount = bugs.reduce((sum, b) => sum + (b.edge_count || 0), 0);
+
+	const risk = riskLevel(bugs.length, recentEntities.length, totalEdgeCount);
+
+	const sections: string[] = [];
+
+	// Header
+	sections.push("# QA Report");
+	sections.push(
+		`\n*Generated on ${formatDate(Date.now())} | Since: ${formatDate(since)} | ${totalEntities} total entities*\n`,
+	);
+	sections.push("---\n");
+
+	// Summary
+	sections.push("## Summary\n");
+	sections.push(`| Metric | Count |`);
+	sections.push(`|---|---|`);
+	sections.push(`| Total entities | ${totalEntities} |`);
+	sections.push(`| Recent changes (since ${formatDate(since)}) | ${recentEntities.length} |`);
+	sections.push(`| Total bugs | ${bugs.length} |`);
+	sections.push(`| Recent bugs | ${recentBugs.length} |`);
+	sections.push(`| Solutions | ${solutions.length} |`);
+	sections.push(`| Recent decisions | ${recentDecisions.length} |`);
+	sections.push(`| Overall risk | **${risk.label}** (score: ${risk.score}) |`);
+	sections.push("");
+
+	// High-Risk Areas
+	sections.push("## High-Risk Areas\n");
+	if (bugs.length === 0 && recentEntities.length === 0) {
+		sections.push("*No risk areas identified — no bugs or recent changes.*\n");
+	} else {
+		// Group bugs by file path to identify risky areas
+		const areaMap = new Map<string, { bugs: number; recent: number; edges: number }>();
+		for (const bug of bugs) {
+			const area = bug.file_paths && bug.file_paths !== "[]" ? bug.file_paths : "Unknown";
+			const entry = areaMap.get(area) ?? { bugs: 0, recent: 0, edges: 0 };
+			entry.bugs++;
+			entry.edges += bug.edge_count || 0;
+			if (bug.created_at >= since) entry.recent++;
+			areaMap.set(area, entry);
+		}
+
+		if (areaMap.size > 0) {
+			const sorted = [...areaMap.entries()].sort((a, b) => {
+				const riskA = riskLevel(a[1].bugs, a[1].recent, a[1].edges);
+				const riskB = riskLevel(b[1].bugs, b[1].recent, b[1].edges);
+				return riskB.score - riskA.score;
+			});
+
+			sections.push("| Area | Bugs | Recent Changes | Risk |");
+			sections.push("|---|---|---|---|");
+			for (const [area, data] of sorted) {
+				const r = riskLevel(data.bugs, data.recent, data.edges);
+				sections.push(`| ${area} | ${data.bugs} | ${data.recent} | **${r.label}** (${r.score}) |`);
+			}
+			sections.push("");
+		} else {
+			sections.push("*No bug-affected areas found.*\n");
+		}
+	}
+
+	// Bug Activity
+	sections.push("## Bug Activity\n");
+	if (bugs.length === 0) {
+		sections.push("*No bugs recorded in the knowledge graph.*\n");
+	} else {
+		sections.push(`| Bug | Date | Trust | Files |`);
+		sections.push(`|---|---|---|---|`);
+		for (const bug of bugs) {
+			const date = formatDate(bug.created_at);
+			const tier =
+				bug.trust_tier === 1 ? "verified" : bug.trust_tier === 2 ? "code-derived" : "inferred";
+			const files = bug.file_paths && bug.file_paths !== "[]" ? bug.file_paths : "—";
+			sections.push(`| ${bug.name} | ${date} | ${tier} | ${files} |`);
+		}
+		sections.push("");
+	}
+
+	// Solutions
+	if (solutions.length > 0) {
+		sections.push("## Solutions Applied\n");
+		sections.push(`| Solution | Date | Files |`);
+		sections.push(`|---|---|---|`);
+		for (const sol of solutions) {
+			const date = formatDate(sol.created_at);
+			const files = sol.file_paths && sol.file_paths !== "[]" ? sol.file_paths : "—";
+			sections.push(`| ${sol.name} | ${date} | ${files} |`);
+		}
+		sections.push("");
+	}
+
+	// Recent Decisions
+	if (recentDecisions.length > 0) {
+		sections.push("## Recent Decisions\n");
+		for (const dec of recentDecisions) {
+			sections.push(`### ${dec.name}`);
+			sections.push(`*${formatDate(dec.created_at)}*\n`);
+			if (dec.content) sections.push(`${dec.content.slice(0, 300)}\n`);
+		}
+	}
+
+	// Test Recommendations
+	sections.push("## Test Recommendations\n");
+	if (bugs.length === 0) {
+		sections.push("*No bugs in the graph — no specific test cases to recommend.*\n");
+	} else {
+		sections.push("Based on bug history, prioritize testing these scenarios:\n");
+		for (let i = 0; i < bugs.length; i++) {
+			const bug = bugs[i];
+			sections.push(`${i + 1}. **${bug.name}** — ${bug.content.slice(0, 150)}`);
+		}
+		sections.push("");
+	}
+
+	// Coverage Gaps
+	sections.push("## Coverage Gaps\n");
+	const codeEntitiesResult = await db.execute(
+		`SELECT COUNT(*) as cnt FROM graph_nodes
+		 WHERE type = 'CodeEntity' AND t_valid_until IS NULL AND archived_at IS NULL`,
+	);
+	const codeCount = (codeEntitiesResult.rows[0] as any).cnt;
+	if (codeCount > 0 && bugs.length > 0) {
+		sections.push(`- ${codeCount} code entities tracked, ${bugs.length} bugs found`);
+		sections.push(`- Areas with bugs but no corresponding solutions may indicate coverage gaps`);
+		const unresolvedCount = bugs.length - solutions.length;
+		if (unresolvedCount > 0) {
+			sections.push(
+				`- **${unresolvedCount} bugs without matching solutions** — potential untested areas`,
+			);
+		}
+	} else if (codeCount === 0) {
+		sections.push("*No code entities indexed yet — run `/sia-learn` for coverage analysis.*");
+	} else {
+		sections.push("*No bugs recorded — coverage analysis not applicable.*");
+	}
+	sections.push("");
+
+	// Footer
+	sections.push("---\n");
+	sections.push("*Generated by SIA QA Report — run `/sia-qa-report` to regenerate.*");
+
+	return sections.join("\n");
+}
+
+export async function runQaReport(args: string[]): Promise<void> {
+	const { resolveRepoHash } = await import("@/capture/hook");
+	const { openGraphDb } = await import("@/graph/semantic-db");
+	const { resolveSiaHome } = await import("@/shared/config");
+
+	let outputPath = "QA-REPORT.md";
+	let since: number | undefined;
+
+	for (let i = 0; i < args.length; i++) {
+		if (args[i] === "--output" && args[i + 1]) outputPath = args[++i];
+		if (args[i] === "--since" && args[i + 1]) {
+			const parsed = Date.parse(args[++i]);
+			if (!Number.isNaN(parsed)) since = parsed;
+		}
+	}
+
+	const cwd = process.cwd();
+	const repoHash = resolveRepoHash(cwd);
+	const siaHome = resolveSiaHome();
+	const db = openGraphDb(repoHash, siaHome);
+
+	try {
+		const markdown = await generateQaReport(db, { since, outputPath });
+		const fullPath = join(cwd, outputPath);
+		writeFileSync(fullPath, markdown, "utf-8");
+		console.log(`QA report written to ${outputPath} (${markdown.length} chars)`);
+	} finally {
+		await db.close();
+	}
+}

package/src/cli/commands/reindex.ts

@@ -0,0 +1,104 @@
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { type IndexResult, indexRepository } from "@/ast/indexer";
+import { openMetaDb, registerRepo } from "@/graph/meta-db";
+import { openGraphDb } from "@/graph/semantic-db";
+import { getConfig } from "@/shared/config";
+import { detectApiContracts, writeDetectedContracts } from "@/workspace/api-contracts";
+import { detectMonorepoPackages, registerMonorepoPackages } from "@/workspace/detector";
+
+export interface ReindexOptions {
+	cwd?: string;
+	siaHome?: string;
+	dryRun?: boolean;
+}
+
+export interface ReindexResult extends IndexResult {
+	repoHash: string;
+	dryRun: boolean;
+	packagesDetected: number;
+	contractsDetected: number;
+}
+
+function findRepoRoot(startDir: string): string | null {
+	let dir = resolve(startDir);
+	const root = resolve("/");
+	while (dir !== root) {
+		if (existsSync(join(dir, ".git"))) {
+			return dir;
+		}
+		const parent = resolve(dir, "..");
+		if (parent === dir) break;
+		dir = parent;
+	}
+	if (existsSync(join(dir, ".git"))) {
+		return dir;
+	}
+	return null;
+}
+
+export async function siaReindex(opts: ReindexOptions = {}): Promise<ReindexResult> {
+	const cwd = opts.cwd ?? process.cwd();
+	const repoRoot = findRepoRoot(cwd);
+	if (!repoRoot) {
+		throw new Error(`No .git directory found from ${cwd}`);
+	}
+
+	const resolvedRoot = resolve(repoRoot);
+	const repoHash = createHash("sha256").update(resolvedRoot).digest("hex");
+	const isDryRun = opts.dryRun ?? false;
+	const prefix = isDryRun ? "(dry-run) " : "";
+
+	const config = getConfig(opts.siaHome);
+	const db = openGraphDb(repoHash, opts.siaHome);
+
+	let packagesDetected = 0;
+	let contractsDetected = 0;
+
+	try {
+		// Re-detect monorepo structure and API contracts
+		if (!isDryRun) {
+			const metaDb = openMetaDb(opts.siaHome);
+			try {
+				const repoId = await registerRepo(metaDb, resolvedRoot);
+
+				const packages = await detectMonorepoPackages(resolvedRoot);
+				if (packages.length > 0) {
+					await registerMonorepoPackages(metaDb, repoId, resolvedRoot, packages);
+					packagesDetected = packages.length;
+				}
+
+				const contracts = await detectApiContracts(resolvedRoot);
+				if (contracts.length > 0) {
+					await writeDetectedContracts(metaDb, repoId, contracts);
+					contractsDetected = contracts.length;
+				}
+			} finally {
+				await metaDb.close();
+			}
+		}
+
+		const result = await indexRepository(resolvedRoot, db, config, {
+			dryRun: isDryRun,
+			repoHash,
+			onProgress: ({ filesProcessed, entitiesCreated, file }) => {
+				console.log(`${prefix}[${filesProcessed}] ${file ?? "..."} (${entitiesCreated} entities)`);
+			},
+		});
+
+		console.log(
+			`${prefix}Reindex complete: ${result.filesProcessed} files, ${result.entitiesCreated} entities, ${packagesDetected} packages, ${contractsDetected} contracts.`,
+		);
+
+		return {
+			...result,
+			repoHash,
+			dryRun: isDryRun,
+			packagesDetected,
+			contractsDetected,
+		};
+	} finally {
+		await db.close();
+	}
+}

package/src/cli/commands/rollback.ts

@@ -0,0 +1,70 @@
+// Module: rollback — restore graph from a snapshot
+
+import { readFileSync } from "node:fs";
+import type { SiaDb } from "@/graph/db-interface";
+import type { SnapshotData } from "@/graph/snapshots";
+import { findNearestSnapshot, listSnapshots, restoreSnapshot } from "@/graph/snapshots";
+
+export interface RollbackOpts {
+	/** Target date string (YYYY-MM-DD) or timestamp to roll back to. */
+	target?: string | number;
+	/** Override SIA_HOME. */
+	siaHome?: string;
+}
+
+export interface RollbackResult {
+	snapshotUsed: string;
+	restoredEntities: number;
+	restoredEdges: number;
+}
+
+/**
+ * Roll back the graph database to a previous snapshot.
+ *
+ * - If `opts.target` is a YYYY-MM-DD string, it is parsed to a UTC timestamp.
+ * - If `opts.target` is a number, it is used directly as a timestamp.
+ * - If no target is provided, the most recent snapshot is used.
+ */
+export async function rollbackGraph(
+	db: SiaDb,
+	repoHash: string,
+	opts?: RollbackOpts,
+): Promise<RollbackResult> {
+	const siaHome = opts?.siaHome;
+	let snapshotPath: string | null = null;
+
+	if (opts?.target != null) {
+		const targetTs =
+			typeof opts.target === "string" ? new Date(opts.target).getTime() : opts.target;
+
+		snapshotPath = findNearestSnapshot(repoHash, targetTs, siaHome);
+	} else {
+		// No target — use the most recent snapshot (last item)
+		const all = listSnapshots(repoHash, siaHome);
+		snapshotPath = all.length > 0 ? all[all.length - 1] : null;
+	}
+
+	if (!snapshotPath) {
+		throw new Error("No snapshot found for the specified date");
+	}
+
+	// Restore the snapshot into the database
+	await restoreSnapshot(db, snapshotPath, repoHash, siaHome);
+
+	// Read the snapshot file to count entities and edges
+	const raw = readFileSync(snapshotPath, "utf-8");
+	const data = JSON.parse(raw) as SnapshotData;
+
+	return {
+		snapshotUsed: snapshotPath,
+		restoredEntities: data.entities.length,
+		restoredEdges: data.edges.length,
+	};
+}
+
+/**
+ * List all available snapshot file paths for a repo, sorted oldest-first.
+ */
+export function listAvailableSnapshots(repoHash: string, siaHome?: string): string[] {
+	return listSnapshots(repoHash, siaHome);
+}

package/src/cli/commands/search.ts

@@ -0,0 +1,103 @@
+// Module: search — CLI search against the knowledge graph
+
+import type { SiaDb } from "@/graph/db-interface";
+
+export interface SearchOpts {
+	limit?: number;
+	taskType?: string;
+	packagePath?: string;
+}
+
+export interface SearchResultItem {
+	id: string;
+	name: string;
+	type: string;
+	content: string;
+	summary: string;
+	importance: number;
+	confidence: number;
+	trustTier: number;
+	score: number;
+}
+
+/**
+ * Sanitize an FTS5 query string: strip special characters and wrap tokens
+ * in double-quotes so SQLite treats them as literals.
+ */
+function sanitizeFtsQuery(query: string): string {
+	// Remove FTS5 operators and special chars, keep alphanumerics, underscores, hyphens, spaces
+	const cleaned = query.replace(/[^a-zA-Z0-9_\- ]/g, " ").trim();
+	if (cleaned.length === 0) return '""';
+
+	// Wrap each token in double-quotes to avoid FTS5 syntax errors
+	const tokens = cleaned.split(/\s+/).filter(Boolean);
+	return tokens.map((t) => `"${t}"`).join(" ");
+}
+
+/**
+ * Map a raw database row to a SearchResultItem.
+ */
+function rowToItem(row: Record<string, unknown>, score: number): SearchResultItem {
+	return {
+		id: String(row.id ?? ""),
+		name: String(row.name ?? ""),
+		type: String(row.type ?? ""),
+		content: String(row.content ?? ""),
+		summary: String(row.summary ?? ""),
+		importance: Number(row.importance ?? 0),
+		confidence: Number(row.confidence ?? 0),
+		trustTier: Number(row.trust_tier ?? 0),
+		score,
+	};
+}
+
+/**
+ * Search the knowledge graph for entities matching the given query.
+ *
+ * Tries FTS5 first for ranked full-text search; falls back to a LIKE-based
+ * query if the FTS5 virtual table is unavailable or the query fails.
+ */
+export async function searchGraph(
+	db: SiaDb,
+	query: string,
+	opts?: SearchOpts,
+): Promise<SearchResultItem[]> {
+	const limit = opts?.limit ?? 20;
+
+	// --- Attempt FTS5 search ---
+	try {
+		const ftsQuery = sanitizeFtsQuery(query);
+		const result = await db.execute(
+			`SELECT graph_nodes.id, graph_nodes.name, graph_nodes.type, graph_nodes.content,
+				graph_nodes.summary, graph_nodes.importance, graph_nodes.confidence,
+				graph_nodes.trust_tier, graph_nodes_fts.rank
+			FROM graph_nodes_fts
+			JOIN graph_nodes ON graph_nodes.rowid = graph_nodes_fts.rowid
+			WHERE graph_nodes_fts MATCH ?
+				AND graph_nodes.t_valid_until IS NULL
+				AND graph_nodes.archived_at IS NULL
+			ORDER BY rank
+			LIMIT ?`,
+			[ftsQuery, limit],
+		);
+
+		return result.rows.map((row) => rowToItem(row, Number(row.rank ?? 0)));
+	} catch {
+		// FTS5 table missing or query error — fall through to LIKE search
+	}
+
+	// --- Fallback: LIKE search ---
+	const likePattern = `%${query}%`;
+	const result = await db.execute(
+		`SELECT id, name, type, content, summary, importance, confidence, trust_tier
+		FROM graph_nodes
+		WHERE (name LIKE ? OR content LIKE ?)
+			AND t_valid_until IS NULL
+			AND archived_at IS NULL
+		ORDER BY importance DESC
+		LIMIT ?`,
+		[likePattern, likePattern, limit],
+	);
+
+	return result.rows.map((row) => rowToItem(row, Number(row.importance ?? 0)));
+}

package/src/cli/commands/server.ts

@@ -0,0 +1,91 @@
+import { execFileSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { SIA_HOME } from "@/shared/config";
+
+const SERVER_DIR = join(SIA_HOME, "server");
+const CONFIG_PATH = join(SERVER_DIR, "server.json");
+const ENV_PATH = join(SERVER_DIR, ".env");
+const COMPOSE_PATH = join(SERVER_DIR, "docker-compose.yml");
+
+interface ServerConfig {
+	url: string;
+	running: boolean;
+	startedAt: number | null;
+}
+
+function readConfig(): ServerConfig {
+	if (!existsSync(CONFIG_PATH)) {
+		return { url: "", running: false, startedAt: null };
+	}
+	try {
+		return JSON.parse(readFileSync(CONFIG_PATH, "utf-8")) as ServerConfig;
+	} catch {
+		return { url: "", running: false, startedAt: null };
+	}
+}
+
+function writeServerConfig(config: ServerConfig): void {
+	mkdirSync(SERVER_DIR, { recursive: true });
+	writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2), "utf-8");
+}
+
+const COMPOSE_TEMPLATE = `version: "3.8"
+services:
+  sqld:
+    image: ghcr.io/tursodatabase/libsql-server:latest
+    ports:
+      - "8080:8080"
+    env_file:
+      - .env
+    volumes:
+      - sqld-data:/var/lib/sqld
+volumes:
+  sqld-data:
+`;
+
+export function serverStart(opts?: { port?: number }): ServerConfig {
+	const port = opts?.port ?? 8080;
+	mkdirSync(SERVER_DIR, { recursive: true });
+
+	// Generate JWT secret
+	const jwtSecret = randomBytes(32).toString("hex");
+	writeFileSync(ENV_PATH, `SQLD_AUTH_JWT_KEY=${jwtSecret}\n`, { encoding: "utf-8", mode: 0o600 });
+
+	// Write docker-compose.yml
+	const compose = COMPOSE_TEMPLATE.replace("8080:8080", `${port}:8080`);
+	writeFileSync(COMPOSE_PATH, compose, "utf-8");
+
+	// Start container
+	try {
+		execFileSync("docker", ["compose", "-f", COMPOSE_PATH, "up", "-d"], { stdio: "pipe" });
+	} catch (err) {
+		throw new Error(`Failed to start server: ${(err as Error).message}`);
+	}
+
+	const config: ServerConfig = {
+		url: `http://localhost:${port}`,
+		running: true,
+		startedAt: Date.now(),
+	};
+	writeServerConfig(config);
+	return config;
+}
+
+export function serverStop(): ServerConfig {
+	try {
+		if (existsSync(COMPOSE_PATH)) {
+			execFileSync("docker", ["compose", "-f", COMPOSE_PATH, "down"], { stdio: "pipe" });
+		}
+	} catch {
+		// Container may not be running
+	}
+	const config: ServerConfig = { url: "", running: false, startedAt: null };
+	writeServerConfig(config);
+	return config;
+}
+
+export function serverStatus(): ServerConfig {
+	return readConfig();
+}

package/src/cli/commands/share.ts

@@ -0,0 +1,33 @@
+// Module: share — adjust entity visibility for sharing
+
+import type { SiaDb } from "@/graph/db-interface";
+import { updateEntity } from "@/graph/entities";
+import { openMetaDb, resolveWorkspaceName } from "@/graph/meta-db";
+import type { SyncConfig } from "@/shared/config";
+import { pushChanges } from "@/sync/push";
+
+export async function shareEntity(
+	db: SiaDb,
+	entityId: string,
+	opts: { team?: boolean; project?: string | null; siaHome?: string; syncConfig?: SyncConfig } = {},
+): Promise<void> {
+	let workspaceScope: string | null = null;
+	if (opts.project) {
+		const metaDb = openMetaDb(opts.siaHome);
+		try {
+			const wsId = await resolveWorkspaceName(metaDb, opts.project);
+			if (!wsId) throw new Error(`Workspace '${opts.project}' not found`);
+			workspaceScope = wsId;
+		} finally {
+			await metaDb.close();
+		}
+	}
+
+	const visibility = opts.team ? "team" : opts.project ? "project" : "private";
+	await updateEntity(db, entityId, { visibility, workspace_scope: workspaceScope });
+
+	// Trigger immediate push
+	if (opts.syncConfig?.enabled) {
+		await pushChanges(db, opts.syncConfig);
+	}
+}