amalfa 1.0.30 → 1.0.33

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "amalfa",
-	"version": "1.0.30",
+	"version": "1.0.33",
 	"description": "Local-first knowledge graph engine for AI agents. Transforms markdown into searchable memory with MCP protocol.",
 	"license": "MIT",
 	"homepage": "https://github.com/pjsvis/amalfa#readme",
@@ -16,6 +16,7 @@
 	"type": "module",
 	"files": [
 		"src",
+		"tsconfig.json",
 		"README.md",
 		"LICENSE"
 	],
@@ -45,7 +46,8 @@
 		"@biomejs/biome": "2.3.8",
 		"@types/bun": "1.3.4",
 		"only-allow": "^1.2.2",
-		"pino-pretty": "^13.1.3"
+		"pino-pretty": "^13.1.3",
+		"typescript": "^5.9.3"
 	},
 	"scripts": {
 		"precommit": "bun run scripts/maintenance/pre-commit.ts",
@@ -58,8 +60,7 @@
 		"stats": "bun run src/cli.ts stats",
 		"doctor": "bun run src/cli.ts doctor",
 		"daemon": "bun run src/cli.ts daemon status",
-		"help": "bun run src/cli.ts --help",
-		"publish": "npm publish"
+		"help": "bun run src/cli.ts --help"
 	},
 	"dependencies": {
 		"@modelcontextprotocol/sdk": "1.25.2",

package/src/cli/sonar-chat.ts

@@ -1,5 +1,5 @@
 // import { Command } from "commander";
-import { createInterface } from "readline";
+import { createInterface } from "node:readline";
 import { DaemonManager } from "../utils/DaemonManager";
 
 export async function chatLoop() {

package/src/cli.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
-import { existsSync, statSync } from "fs";
-import { join } from "path";
-import { spawn } from "child_process";
+import { spawn } from "node:child_process";
+import { existsSync, statSync } from "node:fs";
+import { join } from "node:path";
 import pkg from "../package.json" with { type: "json" };
 
 const VERSION = pkg.version;
@@ -13,6 +13,26 @@ let DB_PATH: string | null = null;
 const args = process.argv.slice(2);
 const command = args[0];
 
+// FIX: If running from system root (common in some MCP clients), try to find project root
+if (process.cwd() === "/") {
+	const { resolve, join } = await import("node:path");
+	const { existsSync } = await import("node:fs");
+
+	// Try to find package.json relative to this script
+	// src/cli.ts -> .. -> project root
+	const scriptBasedRoot = resolve(import.meta.dir, "..");
+	if (existsSync(join(scriptBasedRoot, "package.json"))) {
+		try {
+			console.error(
+				`⚠️  Detected CWD as system root. Switching to: ${scriptBasedRoot}`,
+			);
+			process.chdir(scriptBasedRoot);
+		} catch (e) {
+			console.error("Failed to switch CWD:", e);
+		}
+	}
+}
+
 function showHelp() {
 	console.log(`
 AMALFA v${VERSION} - A Memory Layer For Agents
@@ -69,6 +89,7 @@ async function checkDatabase(): Promise<boolean> {
 	if (!existsSync(dbPath)) {
 		console.error(`
 ❌ Database not found at: ${dbPath}
+   (CWD: ${process.cwd()})
 
 To initialize AMALFA:
 1. Create markdown files in ./docs/ (or your preferred location)
@@ -530,7 +551,7 @@ async function cmdSetupMcp() {
 		mcpServers: {
 			amalfa: {
 				command: "bun",
-				args: ["run", mcpScript],
+				args: ["run", "--cwd", cwd, mcpScript],
 				env: {
 					PATH: minimalPath,
 				},

package/src/config/defaults.ts

@@ -3,8 +3,8 @@
  * Default settings that can be overridden via amalfa.config.{ts,js,json}
  */
 
-import { mkdirSync, existsSync } from "fs";
-import { join } from "path";
+import { existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
 
 /** AMALFA directory structure */
 export const AMALFA_DIRS = {
@@ -289,10 +289,7 @@ export async function loadConfig(): Promise<AmalfaConfig> {
 
 				return merged;
 			}
-		} catch (e) {
-			// Silently continue to next config file
-			continue;
-		}
+		} catch (_e) {}
 	}
 
 	// Return defaults if no config found

package/src/core/EdgeWeaver.ts

@@ -134,7 +134,7 @@ export class EdgeWeaver {
 
 		for (const match of matches) {
 			if (!match[2]) continue;
-			let linkPath = match[2].trim();
+			const linkPath = match[2].trim();
 
 			// Skip external links (http/https)
 			if (linkPath.startsWith("http://") || linkPath.startsWith("https://")) {

package/src/core/GraphEngine.ts

@@ -1,11 +1,11 @@
 import type { Database } from "bun:sqlite";
+import { getLogger } from "@src/utils/Logger";
 import { MultiDirectedGraph } from "graphology";
-import { bidirectional as shortestPath } from "graphology-shortest-path/unweighted";
 import communitiesLouvain from "graphology-communities-louvain";
-import pagerank from "graphology-metrics/centrality/pagerank";
-import betweenness from "graphology-metrics/centrality/betweenness";
 import { connectedComponents } from "graphology-components";
-import { getLogger } from "@src/utils/Logger";
+import betweenness from "graphology-metrics/centrality/betweenness";
+import pagerank from "graphology-metrics/centrality/pagerank";
+import { bidirectional as shortestPath } from "graphology-shortest-path/unweighted";
 
 const log = getLogger("GraphEngine");
 

package/src/core/MarkdownMasker.ts

@@ -1,4 +1,4 @@
-import { randomUUID } from "crypto";
+import { randomUUID } from "node:crypto";
 
 export class MarkdownMasker {
 	private stash: Map<string, string> = new Map();

package/src/daemon/index.ts

@@ -1,22 +1,22 @@
 #!/usr/bin/env bun
+
 /**
  * AMALFA Daemon
  * File watcher for incremental database updates
  */
 
-import { existsSync } from "fs";
-import { watch } from "fs";
-import { join } from "path";
+import { existsSync, watch } from "node:fs";
+import { join } from "node:path";
 import {
-	loadConfig,
 	AMALFA_DIRS,
 	type AmalfaConfig,
+	loadConfig,
 } from "@src/config/defaults";
 import { AmalfaIngestor } from "@src/pipeline/AmalfaIngestor";
 import { ResonanceDB } from "@src/resonance/db";
 import { getLogger } from "@src/utils/Logger";
-import { ServiceLifecycle } from "@src/utils/ServiceLifecycle";
 import { sendNotification } from "@src/utils/Notifications";
+import { ServiceLifecycle } from "@src/utils/ServiceLifecycle";
 
 const args = process.argv.slice(2);
 const command = args[0] || "serve";
@@ -101,7 +101,7 @@ function startWatcher(sourceDir: string, debounceMs: number) {
 	try {
 		watch(watchPath, { recursive: true }, (event, filename) => {
 			// Only process markdown files
-			if (filename && filename.endsWith(".md")) {
+			if (filename?.endsWith(".md")) {
 				const fullPath = join(watchPath, filename);
 
 				log.debug(

package/src/daemon/sonar-agent.ts

@@ -21,6 +21,7 @@ import {
 	discoverOllamaCapabilities,
 } from "@src/utils/ollama-discovery";
 import { ServiceLifecycle } from "@src/utils/ServiceLifecycle";
+import { inferenceState } from "./sonar-inference";
 import {
 	handleBatchEnhancement,
 	handleChat,
@@ -44,7 +45,6 @@ import type {
 	SearchRerankRequest,
 	SonarTask,
 } from "./sonar-types";
-import { inferenceState } from "./sonar-inference";
 
 const args = process.argv.slice(2);
 const command = args[0] || "serve";

package/src/daemon/sonar-inference.ts

@@ -1,4 +1,4 @@
-import { AMALFA_DIRS, loadConfig } from "@src/config/defaults";
+import { loadConfig } from "@src/config/defaults";
 import { getLogger } from "@src/utils/Logger";
 import type { Message, RequestOptions } from "./sonar-types";
 

package/src/daemon/sonar-strategies.ts

@@ -1,7 +1,6 @@
 import { loadConfig } from "@src/config/defaults";
 import { getLogger } from "@src/utils/Logger";
 import { callOllama, inferenceState } from "./sonar-inference";
-import type { SonarTask } from "./sonar-types";
 
 const log = getLogger("SonarStrategies");
 

package/src/mcp/index.ts

@@ -1,5 +1,5 @@
-import { appendFileSync } from "fs";
-import { join } from "path";
+import { appendFileSync } from "node:fs";
+import { join } from "node:path";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import {
@@ -200,7 +200,7 @@ async function runServer() {
 					let queryAnalysis: Awaited<
 						ReturnType<typeof sonarClient.analyzeQuery>
 					> | null = null;
-					let queryIntent: string | undefined = undefined;
+					let queryIntent: string | undefined;
 
 					if (sonarAvailable) {
 						log.info({ query }, "🔍 Analyzing query with Sonar");

package/src/pipeline/AmalfaIngestor.ts

@@ -4,7 +4,7 @@
  * No Persona/CDA complexity - just pure markdown → knowledge graph
  */
 
-import { join } from "path";
+import { join } from "node:path";
 import type { AmalfaConfig } from "@src/config/defaults";
 import { EdgeWeaver } from "@src/core/EdgeWeaver";
 import type { Node, ResonanceDB } from "@src/resonance/db";

package/src/pipeline/PreFlightAnalyzer.ts

@@ -1,20 +1,27 @@
 /**
  * PreFlightAnalyzer
- * 
+ *
  * Validates source directories before ingestion to detect issues:
  * - Large files that need splitting
  * - Symlinks and circular references
  * - Empty or invalid files
  * - Estimated resource usage
- * 
+ *
  * Generates .amalfa/logs/pre-flight.log with recommendations.
  */
 
-import { existsSync, lstatSync, readdirSync, realpathSync, statSync, writeFileSync } from "fs";
-import { join, relative } from "path";
-import { getLogger } from "@src/utils/Logger";
+import {
+	existsSync,
+	lstatSync,
+	readdirSync,
+	realpathSync,
+	statSync,
+	writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
 import type { AmalfaConfig } from "@src/config/defaults";
-import { AMALFA_DIRS, initAmalfaDirs } from "@src/config/defaults";
+import { initAmalfaDirs } from "@src/config/defaults";
+import { getLogger } from "@src/utils/Logger";
 
 const log = getLogger("PreFlightAnalyzer");
 
@@ -27,7 +34,13 @@ const WARN_TOTAL_SIZE_MB = 100;
 
 export interface FileIssue {
 	path: string;
-	issue: "too_large" | "too_small" | "symlink" | "circular_ref" | "empty" | "non_markdown";
+	issue:
+		| "too_large"
+		| "too_small"
+		| "symlink"
+		| "circular_ref"
+		| "empty"
+		| "non_markdown";
 	severity: "error" | "warning" | "info";
 	details: string;
 	recommendation?: string;
@@ -49,7 +62,6 @@ export class PreFlightAnalyzer {
 	private config: AmalfaConfig;
 	private visitedPaths = new Set<string>();
 	private issues: FileIssue[] = [];
-	private logPath = join(AMALFA_DIRS.logs, "pre-flight.log");
 
 	constructor(config: AmalfaConfig) {
 		this.config = config;
@@ -181,13 +193,14 @@ export class PreFlightAnalyzer {
 							issue: "circular_ref",
 							severity: "error",
 							details: "Circular symlink reference detected",
-							recommendation: "Remove circular symlink to prevent infinite loops",
+							recommendation:
+								"Remove circular symlink to prevent infinite loops",
 						});
 						return { valid: false, size: 0 };
 					}
 
 					this.visitedPaths.add(realPath);
-				} catch (err) {
+				} catch (_err) {
 					this.issues.push({
 						path: filePath,
 						issue: "circular_ref",
@@ -416,7 +429,9 @@ export class PreFlightAnalyzer {
 		lines.push("");
 		lines.push("Why this limit exists:");
 		lines.push("- Prevents excessive memory usage during embedding generation");
-		lines.push("- Ensures good search quality (large files = poor granularity)");
+		lines.push(
+			"- Ensures good search quality (large files = poor granularity)",
+		);
 		lines.push("- Maintains reasonable graph structure");
 		lines.push("");
 		lines.push("How to handle large files:");

package/src/pipeline/SemanticHarvester.ts

@@ -10,8 +10,8 @@
  * await harvester.loadIntoResonance(graph);
  */
 
-import { existsSync } from "fs";
-import { join } from "path";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
 import { getLogger } from "@src/utils/Logger";
 import { $ } from "bun";
 

package/src/resonance/DatabaseFactory.ts

@@ -15,7 +15,10 @@ export const DatabaseFactory = {
 	 * Connects specifically to the main Resonance Graph database.
 	 * @deprecated Use connect() with explicit path from config instead.
 	 */
-	connectToResonance(dbPath: string = ".amalfa/resonance.db", options: { readonly?: boolean } = {}): Database {
+	connectToResonance(
+		dbPath: string = ".amalfa/resonance.db",
+		options: { readonly?: boolean } = {},
+	): Database {
 		return DatabaseFactory.connect(dbPath, options);
 	},
 	/**

package/src/resonance/services/embedder.ts

@@ -1,4 +1,4 @@
-import { join } from "path";
+import { join } from "node:path";
 import { toFafcas } from "@src/resonance/db";
 import { EmbeddingModel, FlagEmbedding } from "fastembed";
 

package/src/resonance/services/simpleTokenizer.ts

@@ -59,18 +59,18 @@ export class SimpleTokenizerService {
 					const realTerm = match ? match[0] : term;
 
 					if (tag === "Protocol") {
-						if (!result.protocols!.includes(realTerm))
-							result.protocols!.push(realTerm);
+						if (!result.protocols?.includes(realTerm))
+							result.protocols?.push(realTerm);
 					} else if (tag === "Concept") {
-						if (!result.concepts!.includes(realTerm))
-							result.concepts!.push(realTerm);
+						if (!result.concepts?.includes(realTerm))
+							result.concepts?.push(realTerm);
 					} else if (tag === "Organization") {
 						if (!result.organizations.includes(realTerm))
 							result.organizations.push(realTerm);
 					} else {
 						// Default to concepts
-						if (!result.concepts!.includes(realTerm))
-							result.concepts!.push(realTerm);
+						if (!result.concepts?.includes(realTerm))
+							result.concepts?.push(realTerm);
 					}
 				}
 			}

package/src/resonance/services/vector-daemon.ts

@@ -1,16 +1,17 @@
 #!/usr/bin/env bun
+
 /**
  * Vector Daemon - HTTP server for fast embedding generation
  * Keeps FastEmbed model loaded in memory for <100ms embedding lookups
  */
 
-import { serve } from "bun";
-import { join } from "path";
-import { EmbeddingModel, FlagEmbedding } from "fastembed";
+import { join } from "node:path";
+import { AMALFA_DIRS } from "@src/config/defaults";
 import { toFafcas } from "@src/resonance/db";
 import { getLogger } from "@src/utils/Logger";
 import { ServiceLifecycle } from "@src/utils/ServiceLifecycle";
-import { AMALFA_DIRS } from "@src/config/defaults";
+import { serve } from "bun";
+import { EmbeddingModel, FlagEmbedding } from "fastembed";
 
 const log = getLogger("VectorDaemon");
 const PORT = Number(process.env.VECTOR_PORT || 3010);
@@ -33,16 +34,16 @@ const currentModel = EmbeddingModel.BGESmallENV15;
 async function initEmbedder() {
 	if (!embedder) {
 		log.info({ model: currentModel }, "🔄 Initializing embedding model...");
-		
+
 		// Ensure cache directory exists
 		const cacheDir = ".amalfa/cache";
 		const { mkdir } = await import("node:fs/promises");
 		try {
 			await mkdir(cacheDir, { recursive: true });
-		} catch (e) {
+		} catch (_e) {
 			// Directory might already exist, that's fine
 		}
-		
+
 		embedder = await FlagEmbedding.init({
 			model: currentModel,
 			cacheDir,
@@ -60,7 +61,7 @@ async function runServer() {
 	await initEmbedder();
 
 	// Start HTTP server
-	const server = serve({
+	const _server = serve({
 		port: PORT,
 		async fetch(req) {
 			const url = new URL(req.url);

package/src/utils/DaemonManager.ts

@@ -1,7 +1,7 @@
-import { existsSync } from "fs";
-import { join } from "path";
-import { ServiceLifecycle } from "./ServiceLifecycle";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
 import { AMALFA_DIRS } from "@src/config/defaults";
+import { ServiceLifecycle } from "./ServiceLifecycle";
 
 export interface DaemonStatus {
 	running: boolean;

package/src/utils/Notifications.ts

@@ -1,5 +1,5 @@
-import { spawn } from "child_process";
-import { platform } from "os";
+import { spawn } from "node:child_process";
+import { platform } from "node:os";
 
 /**
  * Send a native desktop notification

package/src/utils/ServiceLifecycle.ts

@@ -1,7 +1,6 @@
-import { existsSync } from "fs";
-import { unlink } from "fs/promises";
-import { join } from "path";
-import { AMALFA_DIRS, initAmalfaDirs } from "@src/config/defaults";
+import { existsSync } from "node:fs";
+import { unlink } from "node:fs/promises";
+import { initAmalfaDirs } from "@src/config/defaults";
 
 export interface ServiceConfig {
 	name: string; // e.g. "Daemon"

package/src/utils/StatsTracker.ts

@@ -1,5 +1,5 @@
-import { existsSync, mkdirSync } from "fs";
-import { join } from "path";
+import { existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
 import { AMALFA_DIRS } from "@src/config/defaults";
 
 export interface DatabaseSnapshot {

package/src/utils/TagInjector.ts

@@ -1,4 +1,4 @@
-import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { getLogger } from "@src/utils/Logger";
 
 const log = getLogger("TagInjector");
@@ -79,7 +79,7 @@ export class TagInjector {
 
 			if (content.includes(link)) return true;
 
-			content = content.trimEnd() + `\n\nSee also: ${link}\n`;
+			content = `${content.trimEnd()}\n\nSee also: ${link}\n`;
 			writeFileSync(filePath, content, "utf-8");
 			return true;
 		} catch (error) {

package/src/utils/ollama-discovery.ts

@@ -128,7 +128,7 @@ export async function discoverOllamaCapabilities(): Promise<OllamaCapabilities>
 		}
 
 		// Get model details for the selected model
-		const phi3 = models.find((m) => m.name === "phi3:latest");
+		const _phi3 = models.find((m) => m.name === "phi3:latest");
 
 		let modelInfo: unknown = null;
 		try {
@@ -136,7 +136,7 @@ export async function discoverOllamaCapabilities(): Promise<OllamaCapabilities>
 			if (showResult.exitCode === 0) {
 				modelInfo = parseModelInfo(showResult.stdout?.toString() ?? "");
 			}
-		} catch (e) {
+		} catch (_e) {
 			log.warn(`⚠️  Could not get details for ${searchModel}`);
 		}
 

package/src/utils/sonar-client.ts

@@ -35,7 +35,7 @@ export interface SonarClient {
 		result: { id: string; content: string },
 		query: string,
 	): Promise<{ snippet: string; context: string; confidence: number } | null>;
-	getGaps(limit?: number): Promise<any[]>;
+	getGaps(limit?: number): Promise<unknown[]>;
 }
 
 /**
@@ -56,7 +56,6 @@ export async function createSonarClient(): Promise<SonarClient> {
 
 	// Check if Sonar is enabled
 	// Checking both for backward compatibility or migration
-	// @ts-ignore
 	const isEnabled = config.sonar?.enabled ?? config.phi3?.enabled;
 
 	if (!isEnabled) {
@@ -64,9 +63,8 @@ export async function createSonarClient(): Promise<SonarClient> {
 		return createDisabledClient();
 	}
 
-	// @ts-ignore
 	const hostArgs = config.sonar || config.phi3 || {};
-	const host = hostArgs.host || "localhost:11434";
+	const _host = hostArgs.host || "localhost:11434";
 	const port = hostArgs.port || 3012;
 	const baseUrl = `http://localhost:${port}`;
 	const timeout = hostArgs.tasks?.search?.timeout || 5000;
@@ -257,12 +255,12 @@ export async function createSonarClient(): Promise<SonarClient> {
 			}
 		},
 
-		async getGaps(limit?: number): Promise<any[]> {
+		async getGaps(_limit?: number): Promise<unknown[]> {
 			if (!(await isAvailable())) return [];
 			try {
 				const response = await fetch(`${baseUrl}/graph/explore`);
 				if (!response.ok) return [];
-				const data = (await response.json()) as { gaps?: any[] };
+				const data = (await response.json()) as { gaps?: unknown[] };
 				return data.gaps || [];
 			} catch (error) {
 				log.error({ error }, "Failed to fetch gaps");
@@ -304,7 +302,7 @@ function createDisabledClient(): SonarClient {
 		} | null> {
 			return null;
 		},
-		async getGaps(): Promise<any[]> {
+		async getGaps(): Promise<unknown[]> {
 			return [];
 		},
 	};

package/tsconfig.json

@@ -0,0 +1,48 @@
+{
+	"compilerOptions": {
+		// Environment setup & latest features
+		"lib": ["ESNext"],
+		"target": "ESNext",
+		"module": "Preserve",
+		"moduleDetection": "force",
+		"jsx": "react-jsx",
+		"allowJs": true,
+
+		// Bundler mode
+		"moduleResolution": "bundler",
+		"allowImportingTsExtensions": true,
+		"verbatimModuleSyntax": true,
+		"noEmit": true,
+
+		// Best practices
+		"strict": true,
+		"skipLibCheck": true,
+		"noFallthroughCasesInSwitch": true,
+		"noUncheckedIndexedAccess": true,
+		"noImplicitOverride": true,
+
+		// Some stricter flags (disabled by default)
+		"noUnusedLocals": false,
+		"noUnusedParameters": false,
+		"noPropertyAccessFromIndexSignature": false,
+		"baseUrl": ".",
+		"paths": {
+			"@src/*": ["./src/*"],
+			"@scripts/*": ["./scripts/*"],
+			"@resonance/*": ["./src/resonance/*"],
+			"@/*": ["./*"]
+		}
+	},
+	"exclude": [
+		"public/docs",
+		"docs/webdocs",
+		"node_modules",
+		"dist",
+		".resonance",
+		"briefs",
+		"examples",
+		"experiments",
+		"scripts/lab",
+		"scripts/legacy"
+	]
+}