mcard-js 2.1.41 → 2.1.43

package/dist/chunk-BFD4WSWU.js

@@ -0,0 +1,497 @@
+import {
+  createPage
+} from "./chunk-3EIBJPNF.js";
+import {
+  init_Handle,
+  validateHandle
+} from "./chunk-ADV52544.js";
+import {
+  DEFAULT_PAGE_SIZE
+} from "./chunk-A5S2PI37.js";
+
+// src/storage/schema.ts
+import { get_core_schema, get_vector_schema } from "mcard-wasm";
+var TABLE_LAYERS = {
+  // Layer 1: Core
+  "card": "core",
+  // Layer 2: Handle System
+  "handle_registry": "handle",
+  "handle_history": "handle",
+  // Layer 3: Vector Storage
+  "mcard_vector_metadata": "vector",
+  "mcard_embeddings": "vector",
+  "mcard_fts": "vector",
+  // Layer 4: Semantic Versioning
+  "handle_version_vectors": "semantic",
+  "version_similarity_cache": "semantic",
+  // Layer 5: Knowledge Graph
+  "graph_entities": "graph",
+  "graph_relationships": "graph",
+  "graph_communities": "graph",
+  "graph_extractions": "graph",
+  // Metadata
+  "schema_version": "metadata"
+};
+var MCardSchema = class _MCardSchema {
+  static instance = null;
+  schemaPath = "";
+  rawSql = "";
+  statements = [];
+  tables = /* @__PURE__ */ new Map();
+  indexes = /* @__PURE__ */ new Map();
+  loaded = false;
+  constructor() {
+  }
+  /**
+   * Get the singleton instance.
+   */
+  static getInstance() {
+    if (!_MCardSchema.instance) {
+      _MCardSchema.instance = new _MCardSchema();
+      _MCardSchema.instance.load();
+    }
+    return _MCardSchema.instance;
+  }
+  /**
+   * Reset the singleton (for testing).
+   */
+  static resetInstance() {
+    _MCardSchema.instance = null;
+  }
+  load() {
+    if (this.loaded) return;
+    this.schemaPath = "WASM_MEMORY_SPACE";
+    this.rawSql = get_core_schema();
+    const vectorSql = get_vector_schema();
+    if (vectorSql) {
+      this.rawSql += "\n\n" + vectorSql;
+    }
+    this.statements = this.parseStatements(this.rawSql);
+    for (const stmt of this.statements) {
+      const name = this.extractName(stmt);
+      if (name) {
+        const upper = stmt.toUpperCase();
+        if (upper.includes("CREATE TABLE") || upper.includes("CREATE VIRTUAL TABLE")) {
+          this.tables.set(name.toLowerCase(), stmt);
+        } else if (upper.includes("CREATE INDEX")) {
+          this.indexes.set(name.toLowerCase(), stmt);
+        }
+      }
+    }
+    this.loaded = true;
+  }
+  parseStatements(sql) {
+    sql = sql.replace(/\/\*[\s\S]*?\*\//g, "");
+    const statements = [];
+    let current = [];
+    for (const line of sql.split("\n")) {
+      const stripped = line.split("--")[0].trim();
+      if (!stripped) continue;
+      current.push(stripped);
+      if (stripped.endsWith(";")) {
+        const statement = current.join(" ");
+        if (!statement.trim().toUpperCase().startsWith("INSERT")) {
+          statements.push(statement);
+        }
+        current = [];
+      }
+    }
+    return statements.filter((s) => s.trim());
+  }
+  extractName(statement) {
+    let match = statement.match(/CREATE\s+(?:VIRTUAL\s+)?TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?(\w+)/i);
+    if (match) return match[1];
+    match = statement.match(/CREATE\s+INDEX\s+(?:IF\s+NOT\s+EXISTS\s+)?(\w+)/i);
+    if (match) return match[1];
+    return null;
+  }
+  // ─────────────────────────────────────────────────────────────────────────
+  // Schema Access
+  // ─────────────────────────────────────────────────────────────────────────
+  getSchemaPath() {
+    return this.schemaPath;
+  }
+  getTable(tableName) {
+    return this.tables.get(tableName.toLowerCase());
+  }
+  getIndex(indexName) {
+    return this.indexes.get(indexName.toLowerCase());
+  }
+  getAllTables() {
+    return new Map(this.tables);
+  }
+  getAllIndexes() {
+    return new Map(this.indexes);
+  }
+  getAllStatements() {
+    return [...this.statements];
+  }
+  getTablesByLayer(layer) {
+    return Object.entries(TABLE_LAYERS).filter(([_, l]) => l === layer).map(([name, _]) => name);
+  }
+  getLayerStatements(layer) {
+    const statements = [];
+    const tables = this.getTablesByLayer(layer);
+    for (const table of tables) {
+      const stmt = this.getTable(table);
+      if (stmt) statements.push(stmt);
+    }
+    for (const [_, stmt] of this.indexes) {
+      const match = stmt.match(/ON\s+(\w+)/i);
+      if (match && tables.includes(match[1].toLowerCase())) {
+        statements.push(stmt);
+      }
+    }
+    return statements;
+  }
+  // ─────────────────────────────────────────────────────────────────────────
+  // Database Initialization
+  // ─────────────────────────────────────────────────────────────────────────
+  execStatements(db, statements) {
+    for (const stmt of statements) {
+      db.exec(stmt);
+    }
+    return statements.length;
+  }
+  initLayer(db, layer) {
+    return this.execStatements(db, this.getLayerStatements(layer));
+  }
+  initCoreTables(db) {
+    return this.initLayer(db, "core");
+  }
+  initHandleTables(db) {
+    return this.initLayer(db, "handle");
+  }
+  initVectorTables(db, enableFts = true) {
+    const statements = this.getLayerStatements("vector").filter((s) => enableFts || !s.toLowerCase().includes("fts"));
+    return this.execStatements(db, statements);
+  }
+  initSemanticTables(db) {
+    return this.initLayer(db, "semantic");
+  }
+  initGraphTables(db) {
+    return this.initLayer(db, "graph");
+  }
+  initAllTables(db, options = {}) {
+    const { enableFts = true, enableGraph = true, enableSemantic = true } = options;
+    let count = 0;
+    count += this.initCoreTables(db);
+    count += this.initHandleTables(db);
+    count += this.initVectorTables(db, enableFts);
+    if (enableSemantic) {
+      count += this.initSemanticTables(db);
+    }
+    if (enableGraph) {
+      count += this.initGraphTables(db);
+    }
+    return count;
+  }
+  initVec0Table(db, dimensions) {
+    db.exec(`
+            CREATE VIRTUAL TABLE IF NOT EXISTS mcard_vec USING vec0(
+                metadata_id INTEGER PRIMARY KEY,
+                embedding float[${dimensions}]
+            )
+        `);
+  }
+};
+function getSchemaInstance() {
+  return MCardSchema.getInstance();
+}
+var CARD_TABLE_SCHEMA = getSchemaInstance().getTable("card") || "";
+var HANDLE_REGISTRY_SCHEMA = getSchemaInstance().getTable("handle_registry") || "";
+var HANDLE_HISTORY_SCHEMA = getSchemaInstance().getTable("handle_history") || "";
+var HANDLE_INDEX_SCHEMA = getSchemaInstance().getIndex("idx_handle_current_hash") || "";
+var VECTOR_METADATA_SCHEMA = getSchemaInstance().getTable("mcard_vector_metadata") || "";
+var VECTOR_METADATA_INDEX = getSchemaInstance().getIndex("idx_vector_metadata_hash") || "";
+var VECTOR_EMBEDDINGS_SCHEMA = getSchemaInstance().getTable("mcard_embeddings") || "";
+var VECTOR_FTS_SCHEMA = getSchemaInstance().getTable("mcard_fts") || "";
+var HANDLE_VERSION_VECTORS_SCHEMA = getSchemaInstance().getTable("handle_version_vectors") || "";
+var HANDLE_VERSION_VECTORS_INDEXES = [
+  getSchemaInstance().getIndex("idx_hvv_handle"),
+  getSchemaInstance().getIndex("idx_hvv_hash"),
+  getSchemaInstance().getIndex("idx_hvv_current"),
+  getSchemaInstance().getIndex("idx_hvv_parent")
+].filter(Boolean).join("; ");
+var VERSION_SIMILARITY_CACHE_SCHEMA = getSchemaInstance().getTable("version_similarity_cache") || "";
+var VERSION_SIMILARITY_CACHE_INDEX = getSchemaInstance().getIndex("idx_vsc_handle") || "";
+var GRAPH_ENTITY_SCHEMA = getSchemaInstance().getTable("graph_entities") || "";
+var GRAPH_ENTITY_INDEX_NAME = getSchemaInstance().getIndex("idx_entity_name") || "";
+var GRAPH_ENTITY_INDEX_TYPE = getSchemaInstance().getIndex("idx_entity_type") || "";
+var GRAPH_ENTITY_INDEX_SOURCE = getSchemaInstance().getIndex("idx_entity_source") || "";
+var GRAPH_RELATIONSHIP_SCHEMA = getSchemaInstance().getTable("graph_relationships") || "";
+var GRAPH_RELATIONSHIP_INDEX_SOURCE = getSchemaInstance().getIndex("idx_rel_source") || "";
+var GRAPH_RELATIONSHIP_INDEX_TARGET = getSchemaInstance().getIndex("idx_rel_target") || "";
+var GRAPH_COMMUNITY_SCHEMA = getSchemaInstance().getTable("graph_communities") || "";
+var GRAPH_COMMUNITY_INDEX_LEVEL = getSchemaInstance().getIndex("idx_community_level") || "";
+var GRAPH_EXTRACTION_SCHEMA = getSchemaInstance().getTable("graph_extractions") || "";
+var CORE_SCHEMAS = {
+  card: CARD_TABLE_SCHEMA,
+  handleRegistry: HANDLE_REGISTRY_SCHEMA,
+  handleHistory: HANDLE_HISTORY_SCHEMA,
+  handleIndex: HANDLE_INDEX_SCHEMA
+};
+function initCoreSchemas(db) {
+  const schema = MCardSchema.getInstance();
+  schema.initCoreTables(db);
+  schema.initHandleTables(db);
+}
+
+// src/storage/engines/AbstractSqlEngine.ts
+init_Handle();
+var AbstractSqlEngine = class {
+  /**
+   * SQL expression for casting content to text in search queries.
+   * Override in subclasses: SQLite uses 'TEXT', DuckDB uses 'VARCHAR'.
+   */
+  get castContentAs() {
+    return "TEXT";
+  }
+  // ======================================================================
+  // Concrete: Card Operations (shared across all SQL engines)
+  // ======================================================================
+  /**
+   * Add a card. Default uses INSERT OR REPLACE (SQLite).
+   * DuckDB overrides with DELETE + INSERT.
+   */
+  async add(card) {
+    const contentBytes = card.content instanceof Uint8Array ? card.content : new TextEncoder().encode(String(card.content));
+    await this.execSql(
+      "INSERT OR REPLACE INTO card (hash, content, g_time) VALUES (?, ?, ?)",
+      card.hash,
+      contentBytes,
+      card.g_time
+    );
+    return card.hash;
+  }
+  async get(hash) {
+    const rows = await this.queryRows(
+      "SELECT hash, content, g_time FROM card WHERE hash = ?",
+      hash
+    );
+    if (rows.length === 0) return null;
+    return this.rowToCard(rows[0]);
+  }
+  async delete(hash) {
+    await this.execSql("DELETE FROM card WHERE hash = ?", hash);
+  }
+  async getPage(pageNumber = 1, pageSize = DEFAULT_PAGE_SIZE) {
+    if (pageNumber < 1) throw new Error("Page number must be >= 1");
+    if (pageSize < 1) throw new Error("Page size must be >= 1");
+    const totalItems = await this.count();
+    const offset = (pageNumber - 1) * pageSize;
+    const rows = await this.queryRows(
+      "SELECT hash, content, g_time FROM card ORDER BY g_time DESC LIMIT ? OFFSET ?",
+      pageSize,
+      offset
+    );
+    const items = rows.map((r) => this.rowToCard(r));
+    return createPage(items, totalItems, pageNumber, pageSize);
+  }
+  async count() {
+    const rows = await this.queryRows("SELECT COUNT(*) as cnt FROM card");
+    return Number(rows[0]?.cnt ?? 0);
+  }
+  async searchByHash(hashPrefix) {
+    const rows = await this.queryRows(
+      "SELECT hash, content, g_time FROM card WHERE hash LIKE ?",
+      `${hashPrefix}%`
+    );
+    return rows.map((r) => this.rowToCard(r));
+  }
+  async search(queryStr, pageNumber = 1, pageSize = DEFAULT_PAGE_SIZE) {
+    if (pageNumber < 1) throw new Error("Page number must be >= 1");
+    if (pageSize < 1) throw new Error("Page size must be >= 1");
+    const offset = (pageNumber - 1) * pageSize;
+    const pattern = `%${queryStr}%`;
+    const cast = this.castContentAs;
+    const countRows = await this.queryRows(
+      `SELECT COUNT(*) as cnt FROM card WHERE CAST(content AS ${cast}) LIKE ?`,
+      pattern
+    );
+    const totalItems = Number(countRows[0]?.cnt ?? 0);
+    const rows = await this.queryRows(
+      `SELECT hash, content, g_time FROM card WHERE CAST(content AS ${cast}) LIKE ? ORDER BY g_time DESC LIMIT ? OFFSET ?`,
+      pattern,
+      pageSize,
+      offset
+    );
+    const items = rows.map((r) => this.rowToCard(r));
+    return createPage(items, totalItems, pageNumber, pageSize);
+  }
+  async getAll() {
+    const rows = await this.queryRows("SELECT hash, content, g_time FROM card ORDER BY g_time DESC");
+    return rows.map((r) => this.rowToCard(r));
+  }
+  // ======================================================================
+  // Concrete: clear (FK-safe delete order)
+  // ======================================================================
+  async clear() {
+    await this.execSql("DELETE FROM handle_history");
+    await this.execSql("DELETE FROM handle_registry");
+    await this.execSql("DELETE FROM card");
+  }
+  // ======================================================================
+  // Concrete: Handle Operations
+  // ======================================================================
+  async registerHandle(handle, hash) {
+    const normalized = validateHandle(handle);
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const existing = await this.queryRows(
+      "SELECT handle FROM handle_registry WHERE handle = ?",
+      normalized
+    );
+    if (existing.length > 0) {
+      throw new Error(`Handle '${handle}' already exists.`);
+    }
+    await this.execSql(
+      "INSERT INTO handle_registry (handle, current_hash, created_at, updated_at) VALUES (?, ?, ?, ?)",
+      normalized,
+      hash,
+      now,
+      now
+    );
+  }
+  async resolveHandle(handle) {
+    const normalized = validateHandle(handle);
+    const rows = await this.queryRows(
+      "SELECT current_hash FROM handle_registry WHERE handle = ?",
+      normalized
+    );
+    if (rows.length === 0) return null;
+    return String(rows[0].current_hash);
+  }
+  async getByHandle(handle) {
+    const hash = await this.resolveHandle(handle);
+    if (!hash) return null;
+    return this.get(hash);
+  }
+  async updateHandle(handle, newHash) {
+    const normalized = validateHandle(handle);
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const rows = await this.queryRows(
+      "SELECT current_hash FROM handle_registry WHERE handle = ?",
+      normalized
+    );
+    if (rows.length === 0) {
+      throw new Error(`Handle '${handle}' not found.`);
+    }
+    const previousHash = String(rows[0].current_hash);
+    await this.execSql(
+      "INSERT INTO handle_history (handle, previous_hash, changed_at) VALUES (?, ?, ?)",
+      normalized,
+      previousHash,
+      now
+    );
+    await this.execSql(
+      "UPDATE handle_registry SET current_hash = ?, updated_at = ? WHERE handle = ?",
+      newHash,
+      now,
+      normalized
+    );
+    return previousHash;
+  }
+  async getHandleHistory(handle) {
+    const normalized = validateHandle(handle);
+    const rows = await this.queryRows(
+      "SELECT previous_hash, changed_at FROM handle_history WHERE handle = ? ORDER BY id DESC",
+      normalized
+    );
+    return rows.map((r) => ({
+      previousHash: String(r.previous_hash),
+      changedAt: String(r.changed_at)
+    }));
+  }
+  async pruneHandleHistory(handle, options = {}) {
+    const normalized = validateHandle(handle);
+    if (options.deleteAll) {
+      return this.execSql("DELETE FROM handle_history WHERE handle = ?", normalized);
+    } else if (options.olderThan) {
+      return this.execSql(
+        "DELETE FROM handle_history WHERE handle = ? AND changed_at < ?",
+        normalized,
+        options.olderThan
+      );
+    }
+    return 0;
+  }
+  // ======================================================================
+  // Concrete: Handle Management Operations
+  // ======================================================================
+  async getAllHandles() {
+    const rows = await this.queryRows("SELECT handle, current_hash FROM handle_registry");
+    return rows.map((r) => ({
+      handle: String(r.handle),
+      hash: String(r.current_hash)
+    }));
+  }
+  async removeHandle(handle) {
+    const normalized = validateHandle(handle);
+    await this.execSql("DELETE FROM handle_history WHERE handle = ?", normalized);
+    await this.execSql("DELETE FROM handle_registry WHERE handle = ?", normalized);
+  }
+  async renameHandle(oldHandle, newHandle) {
+    const normalizedOld = validateHandle(oldHandle);
+    const normalizedNew = validateHandle(newHandle);
+    if (normalizedOld === normalizedNew) return;
+    const existsOld = await this.queryRows(
+      "SELECT handle FROM handle_registry WHERE handle = ?",
+      normalizedOld
+    );
+    if (existsOld.length === 0) throw new Error(`Handle '${oldHandle}' not found.`);
+    const existsNew = await this.queryRows(
+      "SELECT handle FROM handle_registry WHERE handle = ?",
+      normalizedNew
+    );
+    if (existsNew.length > 0) throw new Error(`Handle '${newHandle}' already exists.`);
+    const oldRow = await this.queryRows(
+      "SELECT current_hash, created_at, updated_at FROM handle_registry WHERE handle = ?",
+      normalizedOld
+    );
+    await this.execSql(
+      "INSERT INTO handle_registry (handle, current_hash, created_at, updated_at) VALUES (?, ?, ?, ?)",
+      normalizedNew,
+      String(oldRow[0].current_hash),
+      String(oldRow[0].created_at),
+      String(oldRow[0].updated_at)
+    );
+    await this.execSql(
+      "UPDATE handle_history SET handle = ? WHERE handle = ?",
+      normalizedNew,
+      normalizedOld
+    );
+    await this.execSql(
+      "DELETE FROM handle_registry WHERE handle = ?",
+      normalizedOld
+    );
+  }
+  async deleteHistoryEntry(handle, previousHash) {
+    const normalized = validateHandle(handle);
+    const rOutRows = await this.queryRows(
+      "SELECT id, previous_hash FROM handle_history WHERE handle = ? AND previous_hash = ? ORDER BY id DESC LIMIT 1",
+      normalized,
+      previousHash
+    );
+    if (rOutRows.length === 0) return;
+    const rOutId = Number(rOutRows[0].id);
+    const rInRows = await this.queryRows(
+      "SELECT id, previous_hash FROM handle_history WHERE handle = ? AND id < ? ORDER BY id DESC LIMIT 1",
+      normalized,
+      rOutId
+    );
+    if (rInRows.length > 0) {
+      const rInId = Number(rInRows[0].id);
+      const rInPrevHash = String(rInRows[0].previous_hash);
+      await this.execSql("UPDATE handle_history SET previous_hash = ? WHERE id = ?", rInPrevHash, rOutId);
+      await this.execSql("DELETE FROM handle_history WHERE id = ?", rInId);
+    } else {
+      await this.execSql("DELETE FROM handle_history WHERE id = ?", rOutId);
+    }
+  }
+};
+
+export {
+  CORE_SCHEMAS,
+  initCoreSchemas,
+  AbstractSqlEngine
+};

package/dist/chunk-BSEFN25Q.js

@@ -0,0 +1,32 @@
+// src/config/constants.ts
+var DEFAULT_PAGE_SIZE = 10;
+var MAX_FILE_SIZE = 50 * 1024 * 1024;
+var KNOWN_TYPE_SIZE_LIMIT = 1024 * 1024;
+var BINARY_CHECK_SAMPLE_SIZE = 32 * 1024;
+var CONTENT_DETECTION_SAMPLE_SIZE = 1024 * 1024;
+var DEFAULT_MAX_PROBLEM_BYTES = 2 * 1024 * 1024;
+var INDEXEDDB_DEFAULT_DB_NAME = "mcard-db";
+var INDEXEDDB_DEFAULT_DB_VERSION = 1;
+var SQLITE_BUSY_TIMEOUT_MS = 5e3;
+var getEnvUrl = (key, fallback) => {
+  try {
+    if (typeof process !== "undefined" && process.env && process.env[key]) {
+      return process.env[key];
+    }
+  } catch (e) {
+  }
+  return fallback;
+};
+var DEFAULT_OLLAMA_BASE_URL = getEnvUrl("OLLAMA_BASE_URL", "http://localhost:11434");
+var DEFAULT_OTLP_ENDPOINT = getEnvUrl("OTLP_ENDPOINT", "http://localhost:4317");
+var DEFAULT_VLLM_BASE_URL = getEnvUrl("VLLM_BASE_URL", "http://localhost:8000");
+var DEFAULT_LMSTUDIO_BASE_URL = getEnvUrl("LMSTUDIO_BASE_URL", "http://localhost:1234");
+var DEFAULT_SQLJS_WASM_URL = "https://sql.js.org/dist/";
+
+export {
+  DEFAULT_PAGE_SIZE,
+  INDEXEDDB_DEFAULT_DB_NAME,
+  INDEXEDDB_DEFAULT_DB_VERSION,
+  SQLITE_BUSY_TIMEOUT_MS,
+  DEFAULT_SQLJS_WASM_URL
+};

package/dist/{chunk-3LPY36OG.js → chunk-CBEVE7RG.js}

@@ -1,7 +1,7 @@
 import {
   ContentTypeInterpreter,
   MCard
-} from "./chunk-3MMMJ7NH.js";
+} from "./chunk-2NFGZ6PA.js";
 import {
   __export
 } from "./chunk-PNKVD2UK.js";
@@ -183,6 +183,14 @@ async function processFileContent(filePath, options = {}) {
 var DEFAULT_MAX_PROBLEM_BYTES = 2 * 1024 * 1024;
 var WRAP_WIDTH_KNOWN = 1e3;
 var WRAP_WIDTH_DEFAULT = 80;
+var Logger = {
+  info: (...args) => console.log("[Loader]", ...args),
+  warn: (...args) => console.warn("[Loader]", ...args),
+  error: (...args) => console.error("[Loader]", ...args),
+  debug: (...args) => {
+    if (process.env.DEBUG) console.log("[Loader]", ...args);
+  }
+};
 async function processAndStoreFile(filePath, collection, options = {}) {
   const {
     allowProblematic = false,
@@ -194,13 +202,13 @@ async function processAndStoreFile(filePath, collection, options = {}) {
     let fileInfo;
     if (await isProblematicFile(filePath)) {
       if (!allowProblematic) {
-        console.warn(`Skipping problematic file: ${filePath}`);
+        Logger.warn(`Skipping problematic file: ${filePath}`);
         return null;
       }
       const extension = path2.extname(filePath).toLowerCase();
       const isKnownType = ContentTypeInterpreter.isKnownLongLineExtension(extension);
       const wrapWidth = isKnownType ? WRAP_WIDTH_KNOWN : WRAP_WIDTH_DEFAULT;
-      console.warn(`Problematic file detected, processing as safe text: ${filePath}`);
+      Logger.warn(`Problematic file detected, processing as safe text: ${filePath}`);
       try {
         const streamed = await streamReadNormalizedText(filePath, {
           byteCap: maxBytesOnProblem,
@@ -219,7 +227,7 @@ async function processAndStoreFile(filePath, collection, options = {}) {
           wrapWidth
         };
       } catch (e) {
-        console.warn(`Safe text processing failed, falling back to capped binary: ${filePath}`);
+        Logger.warn(`Safe text processing failed, falling back to capped binary: ${filePath}`, e);
         fileInfo = await processFileContent(filePath, {
           forceBinary: true,
           allowPathological: true,
@@ -227,15 +235,13 @@ async function processAndStoreFile(filePath, collection, options = {}) {
         });
       }
     } else {
-      console.log(`Processing file: ${filePath}`);
+      Logger.info(`Processing file: ${filePath}`);
       fileInfo = await processFileContent(filePath);
     }
     if (!fileInfo) return null;
     const content = fileInfo.content;
     if (!content || typeof content === "string" && content.length === 0 || content instanceof Uint8Array && content.length === 0) {
-      if (process.env.DEBUG) {
-        console.log(`Skipping empty file: ${filePath} (empty files cannot be stored as MCards)`);
-      }
+      Logger.debug(`Skipping empty file: ${filePath} (empty files cannot be stored as MCards)`);
       return {
         hash: "",
         contentType: fileInfo.mimeType,
@@ -263,11 +269,9 @@ async function processAndStoreFile(filePath, collection, options = {}) {
               await collection.addWithHandle(mcard, relPath);
               registered = true;
             } catch (e2) {
-              if (process.env.DEBUG) {
-                console.log(
-                  `Handle name '${handle}' already in use (common for files like README.md, LICENSE). MCard stored successfully with hash ${mcard.hash.slice(0, 8)}... (accessible by hash, not by handle)`
-                );
-              }
+              Logger.debug(
+                `Handle name '${handle}' already in use (common for files like README.md, LICENSE). MCard stored successfully with hash ${mcard.hash.slice(0, 8)}... (accessible by hash, not by handle)`
+              );
             }
           }
         }
@@ -275,6 +279,7 @@ async function processAndStoreFile(filePath, collection, options = {}) {
           try {
             await collection.add(mcard);
           } catch (e3) {
+            Logger.warn(`Hash fallback also failed for ${handle}:`, e3);
           }
         }
       }
@@ -292,7 +297,7 @@ async function processAndStoreFile(filePath, collection, options = {}) {
     if (metadataOnly && isProblematic) result.metadataOnly = true;
     return result;
   } catch (e) {
-    console.error(`Error processing ${filePath}:`, e);
+    Logger.error(`Error processing ${filePath}:`, e);
     return null;
   }
 }
@@ -334,7 +339,7 @@ async function loadFileToCollection(targetPath, collection, options = {}) {
     directoriesCount: uniqueDirs.size,
     directoryLevels: maxDepth
   };
-  console.log(`About to process ${files.length} files`);
+  Logger.info(`About to process ${files.length} files`);
   for (const file of files) {
     const result = await processAndStoreFile(file, collection, {
       allowProblematic: includeProblematic,