@qaecy/cue-cli 0.0.47 → 0.0.48

package/assets/wasm/dir_scanner_wasm.js

@@ -0,0 +1,461 @@
+/* @ts-self-types="./dir_scanner_wasm.d.ts" */
+
+/**
+ * Attempts to extract the unit count from any supported file and returns a plain JS
+ * object `{ units: number, error: string | null }`.
+ *
+ * `original_path` is used only for extension detection.
+ *
+ * ```js
+ * const buf = await file.arrayBuffer();
+ * const result = debug_file(file.name, new Uint8Array(buf));
+ * console.log(result); // { units: 12, error: null }
+ * ```
+ * @param {string} original_path
+ * @param {Uint8Array} data
+ * @returns {any}
+ */
+export function debug_file(original_path, data) {
+    const ptr0 = passStringToWasm0(original_path, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ret = wasm.debug_file(ptr0, len0, data);
+    return ret;
+}
+
+/**
+ * Scans a list of in-memory files and returns per-extension metrics sorted by
+ * file count descending.
+ *
+ * Each element of `files` must be a plain JS object with:
+ * - `originalPath` (string) — used for extension detection
+ * - `data` (Uint8Array | ArrayBuffer) — raw file bytes
+ *
+ * Returns a JS array of metric objects, or throws on invalid input.
+ *
+ * # Example (JavaScript)
+ * ```js
+ * import init, { scan } from './pkg/dir_scanner_wasm.js';
+ * await init();
+ *
+ * const response = await fetch('/docs/report.pdf');
+ * const data = new Uint8Array(await response.arrayBuffer());
+ *
+ * const metrics = scan([{ originalPath: 'report.pdf', data }]);
+ * console.log(metrics);
+ * // [{ ext: 'pdf', count: 1, percentOfFiltered: 100, percentOfAll: 100, units: 5, sizeMb: 0.12 }]
+ * ```
+ * @param {Array<any>} files
+ * @returns {any}
+ */
+export function scan(files) {
+    const ret = wasm.scan(files);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+
+/**
+ * Returns a plain JS object mapping each file's original path to its unit count.
+ *
+ * Accepts the same `files` array as [`scan`].
+ *
+ * # Example (JavaScript)
+ * ```js
+ * const fileMap = scan_file_map(files);
+ * // { "docs/report.pdf": 5, "slides/deck.pptx": 12 }
+ * ```
+ * @param {Array<any>} files
+ * @returns {any}
+ */
+export function scan_file_map(files) {
+    const ret = wasm.scan_file_map(files);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+function __wbg_get_imports() {
+    const import0 = {
+        __proto__: null,
+        __wbg_Error_960c155d3d49e4c2: function(arg0, arg1) {
+            const ret = Error(getStringFromWasm0(arg0, arg1));
+            return ret;
+        },
+        __wbg_String_8564e559799eccda: function(arg0, arg1) {
+            const ret = String(arg1);
+            const ptr1 = passStringToWasm0(ret, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+            const len1 = WASM_VECTOR_LEN;
+            getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
+            getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
+        },
+        __wbg___wbindgen_debug_string_ab4b34d23d6778bd: function(arg0, arg1) {
+            const ret = debugString(arg1);
+            const ptr1 = passStringToWasm0(ret, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+            const len1 = WASM_VECTOR_LEN;
+            getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
+            getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
+        },
+        __wbg___wbindgen_string_get_7ed5322991caaec5: function(arg0, arg1) {
+            const obj = arg1;
+            const ret = typeof(obj) === 'string' ? obj : undefined;
+            var ptr1 = isLikeNone(ret) ? 0 : passStringToWasm0(ret, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+            var len1 = WASM_VECTOR_LEN;
+            getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
+            getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
+        },
+        __wbg___wbindgen_throw_6b64449b9b9ed33c: function(arg0, arg1) {
+            throw new Error(getStringFromWasm0(arg0, arg1));
+        },
+        __wbg_get_6011fa3a58f61074: function() { return handleError(function (arg0, arg1) {
+            const ret = Reflect.get(arg0, arg1);
+            return ret;
+        }, arguments); },
+        __wbg_get_unchecked_17f53dad852b9588: function(arg0, arg1) {
+            const ret = arg0[arg1 >>> 0];
+            return ret;
+        },
+        __wbg_length_3d4ecd04bd8d22f1: function(arg0) {
+            const ret = arg0.length;
+            return ret;
+        },
+        __wbg_length_9f1775224cf1d815: function(arg0) {
+            const ret = arg0.length;
+            return ret;
+        },
+        __wbg_log_7e1aa9064a1dbdbd: function(arg0) {
+            console.log(arg0);
+        },
+        __wbg_new_0c7403db6e782f19: function(arg0) {
+            const ret = new Uint8Array(arg0);
+            return ret;
+        },
+        __wbg_new_682678e2f47e32bc: function() {
+            const ret = new Array();
+            return ret;
+        },
+        __wbg_new_aa8d0fa9762c29bd: function() {
+            const ret = new Object();
+            return ret;
+        },
+        __wbg_prototypesetcall_a6b02eb00b0f4ce2: function(arg0, arg1, arg2) {
+            Uint8Array.prototype.set.call(getArrayU8FromWasm0(arg0, arg1), arg2);
+        },
+        __wbg_set_022bee52d0b05b19: function() { return handleError(function (arg0, arg1, arg2) {
+            const ret = Reflect.set(arg0, arg1, arg2);
+            return ret;
+        }, arguments); },
+        __wbg_set_3bf1de9fab0cd644: function(arg0, arg1, arg2) {
+            arg0[arg1 >>> 0] = arg2;
+        },
+        __wbg_set_6be42768c690e380: function(arg0, arg1, arg2) {
+            arg0[arg1] = arg2;
+        },
+        __wbg_warn_3cc416af27dbdc02: function(arg0) {
+            console.warn(arg0);
+        },
+        __wbindgen_cast_0000000000000001: function(arg0) {
+            // Cast intrinsic for `F64 -> Externref`.
+            const ret = arg0;
+            return ret;
+        },
+        __wbindgen_cast_0000000000000002: function(arg0, arg1) {
+            // Cast intrinsic for `Ref(String) -> Externref`.
+            const ret = getStringFromWasm0(arg0, arg1);
+            return ret;
+        },
+        __wbindgen_cast_0000000000000003: function(arg0) {
+            // Cast intrinsic for `U64 -> Externref`.
+            const ret = BigInt.asUintN(64, arg0);
+            return ret;
+        },
+        __wbindgen_init_externref_table: function() {
+            const table = wasm.__wbindgen_externrefs;
+            const offset = table.grow(4);
+            table.set(0, undefined);
+            table.set(offset + 0, undefined);
+            table.set(offset + 1, null);
+            table.set(offset + 2, true);
+            table.set(offset + 3, false);
+        },
+    };
+    return {
+        __proto__: null,
+        "./dir_scanner_wasm_bg.js": import0,
+    };
+}
+
+function addToExternrefTable0(obj) {
+    const idx = wasm.__externref_table_alloc();
+    wasm.__wbindgen_externrefs.set(idx, obj);
+    return idx;
+}
+
+function debugString(val) {
+    // primitive types
+    const type = typeof val;
+    if (type == 'number' || type == 'boolean' || val == null) {
+        return  `${val}`;
+    }
+    if (type == 'string') {
+        return `"${val}"`;
+    }
+    if (type == 'symbol') {
+        const description = val.description;
+        if (description == null) {
+            return 'Symbol';
+        } else {
+            return `Symbol(${description})`;
+        }
+    }
+    if (type == 'function') {
+        const name = val.name;
+        if (typeof name == 'string' && name.length > 0) {
+            return `Function(${name})`;
+        } else {
+            return 'Function';
+        }
+    }
+    // objects
+    if (Array.isArray(val)) {
+        const length = val.length;
+        let debug = '[';
+        if (length > 0) {
+            debug += debugString(val[0]);
+        }
+        for(let i = 1; i < length; i++) {
+            debug += ', ' + debugString(val[i]);
+        }
+        debug += ']';
+        return debug;
+    }
+    // Test for built-in
+    const builtInMatches = /\[object ([^\]]+)\]/.exec(toString.call(val));
+    let className;
+    if (builtInMatches && builtInMatches.length > 1) {
+        className = builtInMatches[1];
+    } else {
+        // Failed to match the standard '[object ClassName]'
+        return toString.call(val);
+    }
+    if (className == 'Object') {
+        // we're a user defined class or Object
+        // JSON.stringify avoids problems with cycles, and is generally much
+        // easier than looping through ownProperties of `val`.
+        try {
+            return 'Object(' + JSON.stringify(val) + ')';
+        } catch (_) {
+            return 'Object';
+        }
+    }
+    // errors
+    if (val instanceof Error) {
+        return `${val.name}: ${val.message}\n${val.stack}`;
+    }
+    // TODO we could test for more things here, like `Set`s and `Map`s.
+    return className;
+}
+
+function getArrayU8FromWasm0(ptr, len) {
+    ptr = ptr >>> 0;
+    return getUint8ArrayMemory0().subarray(ptr / 1, ptr / 1 + len);
+}
+
+let cachedDataViewMemory0 = null;
+function getDataViewMemory0() {
+    if (cachedDataViewMemory0 === null || cachedDataViewMemory0.buffer.detached === true || (cachedDataViewMemory0.buffer.detached === undefined && cachedDataViewMemory0.buffer !== wasm.memory.buffer)) {
+        cachedDataViewMemory0 = new DataView(wasm.memory.buffer);
+    }
+    return cachedDataViewMemory0;
+}
+
+function getStringFromWasm0(ptr, len) {
+    ptr = ptr >>> 0;
+    return decodeText(ptr, len);
+}
+
+let cachedUint8ArrayMemory0 = null;
+function getUint8ArrayMemory0() {
+    if (cachedUint8ArrayMemory0 === null || cachedUint8ArrayMemory0.byteLength === 0) {
+        cachedUint8ArrayMemory0 = new Uint8Array(wasm.memory.buffer);
+    }
+    return cachedUint8ArrayMemory0;
+}
+
+function handleError(f, args) {
+    try {
+        return f.apply(this, args);
+    } catch (e) {
+        const idx = addToExternrefTable0(e);
+        wasm.__wbindgen_exn_store(idx);
+    }
+}
+
+function isLikeNone(x) {
+    return x === undefined || x === null;
+}
+
+function passStringToWasm0(arg, malloc, realloc) {
+    if (realloc === undefined) {
+        const buf = cachedTextEncoder.encode(arg);
+        const ptr = malloc(buf.length, 1) >>> 0;
+        getUint8ArrayMemory0().subarray(ptr, ptr + buf.length).set(buf);
+        WASM_VECTOR_LEN = buf.length;
+        return ptr;
+    }
+
+    let len = arg.length;
+    let ptr = malloc(len, 1) >>> 0;
+
+    const mem = getUint8ArrayMemory0();
+
+    let offset = 0;
+
+    for (; offset < len; offset++) {
+        const code = arg.charCodeAt(offset);
+        if (code > 0x7F) break;
+        mem[ptr + offset] = code;
+    }
+    if (offset !== len) {
+        if (offset !== 0) {
+            arg = arg.slice(offset);
+        }
+        ptr = realloc(ptr, len, len = offset + arg.length * 3, 1) >>> 0;
+        const view = getUint8ArrayMemory0().subarray(ptr + offset, ptr + len);
+        const ret = cachedTextEncoder.encodeInto(arg, view);
+
+        offset += ret.written;
+        ptr = realloc(ptr, len, offset, 1) >>> 0;
+    }
+
+    WASM_VECTOR_LEN = offset;
+    return ptr;
+}
+
+function takeFromExternrefTable0(idx) {
+    const value = wasm.__wbindgen_externrefs.get(idx);
+    wasm.__externref_table_dealloc(idx);
+    return value;
+}
+
+let cachedTextDecoder = new TextDecoder('utf-8', { ignoreBOM: true, fatal: true });
+cachedTextDecoder.decode();
+const MAX_SAFARI_DECODE_BYTES = 2146435072;
+let numBytesDecoded = 0;
+function decodeText(ptr, len) {
+    numBytesDecoded += len;
+    if (numBytesDecoded >= MAX_SAFARI_DECODE_BYTES) {
+        cachedTextDecoder = new TextDecoder('utf-8', { ignoreBOM: true, fatal: true });
+        cachedTextDecoder.decode();
+        numBytesDecoded = len;
+    }
+    return cachedTextDecoder.decode(getUint8ArrayMemory0().subarray(ptr, ptr + len));
+}
+
+const cachedTextEncoder = new TextEncoder();
+
+if (!('encodeInto' in cachedTextEncoder)) {
+    cachedTextEncoder.encodeInto = function (arg, view) {
+        const buf = cachedTextEncoder.encode(arg);
+        view.set(buf);
+        return {
+            read: arg.length,
+            written: buf.length
+        };
+    };
+}
+
+let WASM_VECTOR_LEN = 0;
+
+let wasmModule, wasm;
+function __wbg_finalize_init(instance, module) {
+    wasm = instance.exports;
+    wasmModule = module;
+    cachedDataViewMemory0 = null;
+    cachedUint8ArrayMemory0 = null;
+    wasm.__wbindgen_start();
+    return wasm;
+}
+
+async function __wbg_load(module, imports) {
+    if (typeof Response === 'function' && module instanceof Response) {
+        if (typeof WebAssembly.instantiateStreaming === 'function') {
+            try {
+                return await WebAssembly.instantiateStreaming(module, imports);
+            } catch (e) {
+                const validResponse = module.ok && expectedResponseType(module.type);
+
+                if (validResponse && module.headers.get('Content-Type') !== 'application/wasm') {
+                    console.warn("`WebAssembly.instantiateStreaming` failed because your server does not serve Wasm with `application/wasm` MIME type. Falling back to `WebAssembly.instantiate` which is slower. Original error:\n", e);
+
+                } else { throw e; }
+            }
+        }
+
+        const bytes = await module.arrayBuffer();
+        return await WebAssembly.instantiate(bytes, imports);
+    } else {
+        const instance = await WebAssembly.instantiate(module, imports);
+
+        if (instance instanceof WebAssembly.Instance) {
+            return { instance, module };
+        } else {
+            return instance;
+        }
+    }
+
+    function expectedResponseType(type) {
+        switch (type) {
+            case 'basic': case 'cors': case 'default': return true;
+        }
+        return false;
+    }
+}
+
+function initSync(module) {
+    if (wasm !== undefined) return wasm;
+
+
+    if (module !== undefined) {
+        if (Object.getPrototypeOf(module) === Object.prototype) {
+            ({module} = module)
+        } else {
+            console.warn('using deprecated parameters for `initSync()`; pass a single object instead')
+        }
+    }
+
+    const imports = __wbg_get_imports();
+    if (!(module instanceof WebAssembly.Module)) {
+        module = new WebAssembly.Module(module);
+    }
+    const instance = new WebAssembly.Instance(module, imports);
+    return __wbg_finalize_init(instance, module);
+}
+
+async function __wbg_init(module_or_path) {
+    if (wasm !== undefined) return wasm;
+
+
+    if (module_or_path !== undefined) {
+        if (Object.getPrototypeOf(module_or_path) === Object.prototype) {
+            ({module_or_path} = module_or_path)
+        } else {
+            console.warn('using deprecated parameters for the initialization function; pass a single object instead')
+        }
+    }
+
+    if (module_or_path === undefined) {
+        module_or_path = new URL('dir_scanner_wasm_bg.wasm', import.meta.url);
+    }
+    const imports = __wbg_get_imports();
+
+    if (typeof module_or_path === 'string' || (typeof Request === 'function' && module_or_path instanceof Request) || (typeof URL === 'function' && module_or_path instanceof URL)) {
+        module_or_path = fetch(module_or_path);
+    }
+
+    const { instance, module } = await __wbg_load(await module_or_path, imports);
+
+    return __wbg_finalize_init(instance, module);
+}
+
+export { initSync, __wbg_init as default };

package/main.js

@@ -5339,6 +5339,46 @@ var CueAuth = class {
   }
 };
 
+// libs/js/cue-sdk/src/lib/storage.ts
+var CueStorage = class {
+  constructor(_blob) {
+    this._blob = _blob;
+  }
+  /**
+   * Returns a Firebase authenticated download URL for a document stored in Cue.
+   *
+   * The storage path is `{projectId}/{uuid}{suffix}`, e.g. `my-project/abc-123.pdf`.
+   *
+   * @param projectId - The Cue project (space) ID.
+   * @param uuid - The document UUID.
+   * @param suffix - File suffix including the leading dot, e.g. `'.pdf'`, `'.ifc'`.
+   * @param bucket - `'raw'` (default, original uploads) or `'processed'` (derived artefacts).
+   */
+  async getDownloadUrl(projectId, uuid, suffix, bucket = "raw") {
+    const path = `${projectId}/${uuid}${suffix}`;
+    const url = await this._blob.getDownloadURL(bucket, path);
+    if (!url)
+      throw new Error(`File not found in storage: ${path} (bucket: ${bucket})`);
+    return url;
+  }
+  /**
+   * Returns a Firebase authenticated download URL for an alternative representation
+   * using its full `qcy:remoteRelativePath` stored in the processed bucket.
+   *
+   * Use this instead of `getDownloadUrl` when the document info was obtained via
+   * `fetchAlternativeRepresentations` and carries a `remoteRelativePath`.
+   *
+   * @param remoteRelativePath - The full path in the processed bucket,
+   *   e.g. `{projectId}/fragments/{uuid}.fragments`.
+   */
+  async getAltRepDownloadUrl(remoteRelativePath) {
+    const url = await this._blob.getDownloadURL("processed", remoteRelativePath);
+    if (!url)
+      throw new Error(`Alternative representation not found in storage: ${remoteRelativePath}`);
+    return url;
+  }
+};
+
 // libs/js/cue-sdk/src/lib/tables.ts
 var ENDPOINT_DATA_VIEWS_TABLES = "/data-views/tables";
 var ENDPOINT_COMMANDS_TABLES = "/commands/tables";
@@ -8502,7 +8542,127 @@ var CueProjectDocuments = class {
     const newUUIDs = uuids.filter((id) => this._documentInfoMap.get()[id] === void 0);
     if (newUUIDs.length === 0)
       return;
-    const values = newUUIDs.map((id) => `r:${id}`).join(" ");
+    this._fetchDocumentInfoBatch(newUUIDs).catch(
+      (err) => console.error("[CueProjectDocuments] requestDocumentData failed:", err)
+    );
+  }
+  /**
+   * Promise-based alternative to {@link requestDocumentData} for non-reactive contexts.
+   *
+   * Resolves with the `DocumentInfo` entries for every requested UUID once the
+   * SPARQL response arrives. UUIDs already present in the cache are returned
+   * immediately without a network request. The result is also written into
+   * `documentInfoMap` so reactive consumers stay in sync.
+   *
+   * UUIDs not found in the triplestore are omitted from the returned map.
+   *
+   * @example
+   * ```ts
+   * const docs = await cueProjectDocs.fetchDocumentData(['uuid1', 'uuid2']);
+   * console.log(docs['uuid1'].subject);
+   * ```
+   */
+  async fetchDocumentData(uuids) {
+    const current = this._documentInfoMap.get();
+    const newUUIDs = uuids.filter((id) => current[id] === void 0);
+    if (newUUIDs.length > 0) {
+      await this._fetchDocumentInfoBatch(newUUIDs);
+    }
+    const updated = this._documentInfoMap.get();
+    return Object.fromEntries(
+      uuids.filter((id) => updated[id] !== void 0).map((id) => [id, updated[id]])
+    );
+  }
+  /**
+   * Fetches a lightweight document metadata shape (id/path/suffix/size) for
+   * the given UUIDs and merges the results into `documentInfoMap`.
+   *
+   * This is useful for list/table contexts that do not need language-tagged
+   * fields (`subject`, `summary`) or category/tag enrichment.
+   *
+   * UUIDs already present in `documentInfoMap` are skipped.
+   */
+  async fetchDocumentDataSimple(uuids) {
+    const current = this._documentInfoMap.get();
+    const newUUIDs = uuids.filter((id) => current[id] === void 0);
+    if (newUUIDs.length > 0) {
+      await this._fetchSimpleDocumentInfoBatch(newUUIDs);
+    }
+    const updated = this._documentInfoMap.get();
+    return Object.fromEntries(
+      uuids.filter((id) => updated[id] !== void 0).map((id) => [id, updated[id]])
+    );
+  }
+  /**
+   * Returns the alternative representations of the given document UUID.
+   *
+   * Alternative representations are derived artefacts stored under
+   * `qcy:alternativeRepresentation` in the triplestore — for example a
+   * `.fragments` BIM tile derived from an `.ifc` source file.
+   *
+   * The returned `DocumentInfo` entries are also merged into
+   * `documentInfoMap` so reactive consumers stay in sync.
+   *
+   * @example
+   * ```ts
+   * const alts = await docs.fetchAlternativeRepresentations('abc-123');
+   * // alts[0].suffix => '.fragments'
+   * ```
+   */
+  async fetchAlternativeRepresentations(uuid) {
+    const q = `PREFIX qcy: <${qaecyPrefixes["qcy"]}>
+PREFIX r: <${this.baseURL}>
+SELECT ?altId ?contentIRI ?suffix ?rrp
+WHERE {
+  r:${uuid} qcy:alternativeRepresentation ?contentIRI .
+  BIND(REPLACE(STR(?contentIRI), "^.*/([^/]*)$", "$1") AS ?altId)
+  ?contentIRI qcy:hasFileLocation ?loc .
+  ?loc qcy:suffix ?suffix .
+  OPTIONAL { ?loc qcy:remoteRelativePath ?rrp }
+}`;
+    const data = await this._api.sparql(q, this._projectId, this._graphType);
+    const updates = { ...this._documentInfoMap.get() };
+    const alts = [];
+    data.results.bindings.forEach((b) => {
+      if (!b["altId"] || !b["contentIRI"])
+        return;
+      const id = b["altId"].value;
+      const info = {
+        id,
+        contentIRI: b["contentIRI"].value,
+        path: "",
+        suffix: b["suffix"]?.value ?? "",
+        size: 0,
+        tags: [],
+        categories: [],
+        remoteRelativePath: b["rrp"]?.value
+      };
+      updates[id] = info;
+      alts.push(info);
+    });
+    this._documentInfoMap.set(updates);
+    return alts;
+  }
+  /**
+   * Returns a single arbitrary file path from the project's triplestore.
+   * Useful for pre-filling path-based query inputs with a realistic example.
+   */
+  async randomFilePath() {
+    const q = `PREFIX qcy: <${qaecyPrefixes["qcy"]}>
+SELECT ?path
+WHERE {
+    ?fl a qcy:FileLocation ;
+        qcy:filePath ?path .
+}
+LIMIT 1`;
+    const data = await this._api.sparql(q, this._projectId, this._graphType);
+    return data.results.bindings[0]?.["path"]?.value ?? null;
+  }
+  // ── Private helpers ────────────────────────────────────────────────────────
+  /** Executes the document-info SPARQL query for the given UUIDs, merges results
+   * into `documentInfoMap`, and returns the newly fetched entries. */
+  async _fetchDocumentInfoBatch(uuids) {
+    const values = uuids.map((id) => `r:${id}`).join(" ");
     const lang = this._api.language;
     const q = `PREFIX qcy: <${qaecyPrefixes["qcy"]}>
 PREFIX r: <${this.baseURL}>
@@ -8531,47 +8691,73 @@ WHERE {
     BIND(REPLACE(STR(?contentIRI), "^.*/([^/]*)$", "$1") AS ?id)
 }
 GROUP BY ?id ?contentIRI ?suffix ?size ?subject ?summary`;
-    this._api.sparql(q, this._projectId).then((data) => {
-      const result = data;
-      const updates = { ...this._documentInfoMap.get() };
-      result.results.bindings.forEach((b) => {
-        if (!b["id"] || !b["contentIRI"])
-          return;
-        const id = b["id"].value;
-        updates[id] = {
-          id,
-          contentIRI: b["contentIRI"].value,
-          path: b["path"]?.value ?? "",
-          suffix: b["suffix"]?.value ?? "",
-          size: b["size"] ? parseInt(b["size"].value, 10) : 0,
-          tags: b["tags"]?.value?.split(";").filter(Boolean) ?? [],
-          categories: b["categories"]?.value?.split(";").filter(Boolean) ?? [],
-          subject: b["subject"]?.value,
-          summary: b["summary"]?.value,
-          providerId: b["pid"]?.value
-        };
-      });
-      this._documentInfoMap.set(updates);
-    }).catch(
-      (err) => console.error("[CueProjectDocuments] requestDocumentData failed:", err)
-    );
+    const result = await this._api.sparql(q, this._projectId);
+    const updates = { ...this._documentInfoMap.get() };
+    const fetched = {};
+    result.results.bindings.forEach((b) => {
+      if (!b["id"] || !b["contentIRI"])
+        return;
+      const id = b["id"].value;
+      const info = {
+        id,
+        contentIRI: b["contentIRI"].value,
+        path: b["path"]?.value ?? "",
+        suffix: b["suffix"]?.value ?? "",
+        size: b["size"] ? parseInt(b["size"].value, 10) : 0,
+        tags: b["tags"]?.value?.split(";").filter(Boolean) ?? [],
+        categories: b["categories"]?.value?.split(";").filter(Boolean) ?? [],
+        subject: b["subject"]?.value,
+        summary: b["summary"]?.value,
+        providerId: b["pid"]?.value
+      };
+      updates[id] = info;
+      fetched[id] = info;
+    });
+    this._documentInfoMap.set(updates);
+    return fetched;
   }
-  /**
-   * Returns a single arbitrary file path from the project's triplestore.
-   * Useful for pre-filling path-based query inputs with a realistic example.
-   */
-  async randomFilePath() {
+  /** Executes a reduced document-info query (id/path/suffix/size only), merges
+   * into `documentInfoMap`, and returns newly fetched entries. */
+  async _fetchSimpleDocumentInfoBatch(uuids) {
+    const values = uuids.map((id) => `r:${id}`).join(" ");
     const q = `PREFIX qcy: <${qaecyPrefixes["qcy"]}>
-SELECT ?path
+PREFIX r: <${this.baseURL}>
+SELECT ?id ?contentIRI ?suffix ?size (SAMPLE(?fp) AS ?path)
 WHERE {
-    ?fl a qcy:FileLocation ;
-        qcy:filePath ?path .
+    VALUES ?contentIRI { ${values} }
+    ?contentIRI qcy:sizeBytes ?size ;
+                qcy:hasFileLocation ?loc .
+    ?loc qcy:filePath ?fp ;
+         qcy:suffix ?suffix .
+    BIND(REPLACE(STR(?contentIRI), "^.*/([^/]*)$", "$1") AS ?id)
 }
-LIMIT 1`;
-    const data = await this._api.sparql(q, this._projectId, this._graphType);
-    return data.results.bindings[0]?.["path"]?.value ?? null;
+GROUP BY ?id ?contentIRI ?suffix ?size`;
+    const result = await this._api.sparql(q, this._projectId, this._graphType);
+    const updates = { ...this._documentInfoMap.get() };
+    const fetched = {};
+    result.results.bindings.forEach((b) => {
+      if (!b["id"])
+        return;
+      const id = b["id"].value;
+      const existing = updates[id];
+      const info = {
+        id,
+        contentIRI: b["contentIRI"]?.value ?? existing?.contentIRI ?? id,
+        path: b["path"]?.value ?? existing?.path ?? id,
+        suffix: b["suffix"]?.value ?? existing?.suffix ?? "",
+        size: b["size"] ? parseInt(b["size"].value, 10) : existing?.size ?? 0,
+        tags: existing?.tags ?? [],
+        categories: existing?.categories ?? [],
+        subject: existing?.subject,
+        summary: existing?.summary,
+        providerId: existing?.providerId
+      };
+      updates[id] = info;
+      fetched[id] = info;
+    });
+    this._documentInfoMap.set(updates);
+    return fetched;
   }
-  // ── Private helpers ────────────────────────────────────────────────────────
   async _fetchDocumentsBySuffix() {
     return this._runDocumentsBySuffixQuery(this._buildDocumentsBySuffixQuery());
   }
@@ -10506,10 +10692,14 @@ var Cue = class _Cue {
   profile;
   privileges;
   cache;
+  storage;
   _app;
   _endpoints;
   _isEmulator;
+  _storageRaw;
+  _storageProcessed;
   _gis = null;
+  _projectDocuments = /* @__PURE__ */ new Map();
   /**
    * Reactive GIS service. Lazily constructed on first access.
    *
@@ -10553,7 +10743,26 @@ var Cue = class _Cue {
     });
     this.auth = new CueAuth(this._app, this._isEmulator, this._endpoints);
     this.projects = new CueProjects(this.auth, this._app, this._isEmulator, this._endpoints);
+    this._storageRaw = (0, import_storage5.getStorage)(this._app, BUCKET_RAW2);
+    this._storageProcessed = (0, import_storage5.getStorage)(this._app, BUCKET_PROCESSED2);
+    const storagePublic = (0, import_storage5.getStorage)(this._app, BUCKET_PUBLIC2);
+    const storageLogs = (0, import_storage5.getStorage)(this._app, BUCKET_LOGS2);
+    const storageChatSessions = (0, import_storage5.getStorage)(this._app, BUCKET_CHAT_SESSIONS2);
+    const storagePersistence = (0, import_storage5.getStorage)(this._app, BUCKET_PERSISTENCE2);
+    if (this._isEmulator) {
+      (0, import_storage5.connectStorageEmulator)(this._storageRaw, this._endpoints.storageEmulatorHost, this._endpoints.storageEmulatorPort);
+      (0, import_storage5.connectStorageEmulator)(this._storageProcessed, this._endpoints.storageEmulatorHost, this._endpoints.storageEmulatorPort);
+    }
     this.api = this._buildApi(this.projects);
+    const blob = new CueBlobStorage({
+      storageRaw: this._storageRaw,
+      storageProcessed: this._storageProcessed,
+      storagePublic,
+      storageLogs,
+      storageChatSessions,
+      storagePersistence
+    });
+    this.storage = new CueStorage(blob);
     this.profile = new CueProfile(
       this.auth,
       this._app,
@@ -10561,7 +10770,6 @@ var Cue = class _Cue {
       this._endpoints.gatewayUrl
     );
     this.privileges = new CuePrivileges(this.auth.isSuperAdmin);
-    const storagePersistence = (0, import_storage5.getStorage)(this._app, BUCKET_PERSISTENCE2);
     if (this._isEmulator) {
       (0, import_storage5.connectStorageEmulator)(storagePersistence, this._endpoints.storageEmulatorHost, this._endpoints.storageEmulatorPort);
     }
@@ -10609,16 +10817,20 @@ var Cue = class _Cue {
     const instance = Object.create(_Cue.prototype);
     const privileges = new CuePrivileges(auth.isSuperAdmin);
     const cache = new CueCache(storagePersistence);
+    const storage = new CueStorage(blob);
     Object.assign(instance, {
       _app: app,
       _endpoints: endpoints,
       _isEmulator: env === "emulator",
+      _storageRaw: storageRaw,
+      _storageProcessed: storageProcessed,
       auth,
       api,
       projects,
       profile,
       privileges,
-      cache
+      cache,
+      storage
     });
     return instance;
   }
@@ -10651,27 +10863,105 @@ var Cue = class _Cue {
     };
     return new CueProjectView(this.api, projectId, { ...opts, queryCache });
   }
+  /**
+   * Creates a `CueProjectEntities` instance for the given project, with the
+   * SDK query cache wired automatically.
+   *
+   * Prefer this over `new CueProjectEntities(cue.api, projectId)` — it avoids
+   * the manual cache setup and keeps the instance bound to the correct API.
+   *
+   * @example
+   * ```ts
+   * const entities = cue.createProjectEntities('my-project');
+   * entities.requestEntityData(['uuid1']);
+   * const info = entities.entityInfoMap.get()['uuid1'];
+   *
+   * // Promise-based (no signal polling needed):
+   * const graph = await entities.buildSummaryGraph('graph');
+   * ```
+   */
+  createProjectEntities(projectId, opts) {
+    const queryCache = opts?.queryCache ?? {
+      get: (key) => this.cache.getQueryCache(projectId, key).then((entry) => entry?.results),
+      set: (key, data) => this.cache.setQueryCache(projectId, key, { query: key, results: data })
+    };
+    return new CueProjectEntities(
+      this.api,
+      projectId,
+      opts?.rdfBase,
+      queryCache,
+      opts?.graphType
+    );
+  }
+  /**
+   * Creates a `CueProjectDocuments` instance for the given project, with the
+   * SDK query cache wired automatically.
+   *
+   * Prefer this over `new CueProjectDocuments(cue.api, projectId)` — it avoids
+   * the manual cache setup and keeps the instance bound to the correct API.
+   *
+   * @example
+   * ```ts
+   * const docs = cue.createProjectDocuments('my-project');
+   * await docs.fetchOverview();
+   * const data = await docs.fetchDocumentData(['uuid1', 'uuid2']);
+   * ```
+   */
+  createProjectDocuments(projectId, opts) {
+    const hasCustomOptions = opts?.language !== void 0 || opts?.rdfBase !== void 0 || opts?.graphType !== void 0 || opts?.queryCache !== void 0;
+    if (!hasCustomOptions) {
+      const existing = this._projectDocuments.get(projectId);
+      if (existing) {
+        existing.setLanguage(this.api.language);
+        return existing;
+      }
+      const queryCache2 = {
+        get: (key) => this.cache.getQueryCache(projectId, key).then((entry) => entry?.results),
+        set: (key, data) => this.cache.setQueryCache(projectId, key, { query: key, results: data })
+      };
+      const docs = new CueProjectDocuments(
+        this.api,
+        projectId,
+        this.api.language,
+        void 0,
+        queryCache2,
+        void 0
+      );
+      this._projectDocuments.set(projectId, docs);
+      return docs;
+    }
+    const queryCache = opts?.queryCache ?? {
+      get: (key) => this.cache.getQueryCache(projectId, key).then((entry) => entry?.results),
+      set: (key, data) => this.cache.setQueryCache(projectId, key, { query: key, results: data })
+    };
+    return new CueProjectDocuments(
+      this.api,
+      projectId,
+      opts?.language ?? this.api.language,
+      opts?.rdfBase,
+      queryCache,
+      opts?.graphType
+    );
+  }
 };
 
 // libs/js/cue-sdk/src/lib/cue-node.ts
-var import_storage6 = require("firebase/storage");
+var import_storage8 = require("firebase/storage");
 var CueNode = class extends Cue {
   constructor(config) {
     super(config);
   }
   _buildApi(projects) {
-    const storageChatSessions = (0, import_storage6.getStorage)(this._app, BUCKET_CHAT_SESSIONS2);
-    const storageLogs = (0, import_storage6.getStorage)(this._app, BUCKET_LOGS2);
-    const storageRaw = (0, import_storage6.getStorage)(this._app, BUCKET_RAW2);
-    const storagePersistence = (0, import_storage6.getStorage)(this._app, BUCKET_PERSISTENCE2);
-    const storageProcessed = (0, import_storage6.getStorage)(this._app, BUCKET_PROCESSED2);
-    const storagePublic = (0, import_storage6.getStorage)(this._app, BUCKET_PUBLIC2);
+    const storageChatSessions = (0, import_storage8.getStorage)(this._app, BUCKET_CHAT_SESSIONS2);
+    const storageLogs = (0, import_storage8.getStorage)(this._app, BUCKET_LOGS2);
+    const storageRaw = this._storageRaw;
+    const storagePersistence = (0, import_storage8.getStorage)(this._app, BUCKET_PERSISTENCE2);
+    const storageProcessed = this._storageProcessed;
+    const storagePublic = (0, import_storage8.getStorage)(this._app, BUCKET_PUBLIC2);
     if (this._isEmulator) {
       const storageHost = this._endpoints.storageEmulatorHost;
       const storagePort = this._endpoints.storageEmulatorPort;
-      (0, import_storage6.connectStorageEmulator)(storageRaw, storageHost, storagePort);
-      (0, import_storage6.connectStorageEmulator)(storageProcessed, storageHost, storagePort);
-      (0, import_storage6.connectStorageEmulator)(storagePublic, storageHost, storagePort);
+      (0, import_storage8.connectStorageEmulator)(storagePublic, storageHost, storagePort);
     }
     const blob = new CueBlobStorage({
       storageChatSessions,
@@ -10834,21 +11124,21 @@ async function compareHandler(options) {
 }
 
 // apps/desktop/cue-cli/src/helpers/get-files-containing-substring.ts
-var import_storage7 = require("firebase/storage");
+var import_storage9 = require("firebase/storage");
 var import_path2 = require("path");
 var import_promises = require("fs/promises");
 async function getFilesContainingSubstring(bucket, subDir = "", subString = "") {
   const firebase = CueFirebase.getInstance();
   const storage = bucket === "raw" ? firebase.storageRaw : firebase.storageProcessed;
   console.log("Fetching files from storage bucket:", bucket, "in subdir:", subDir, "containing substring:", subString);
-  const listResult = await (0, import_storage7.listAll)((0, import_storage7.ref)(storage, subDir));
+  const listResult = await (0, import_storage9.listAll)((0, import_storage9.ref)(storage, subDir));
   const outputDir = (0, import_path2.join)(process.cwd(), "downloaded_blobs", bucket, subDir);
   await (0, import_promises.mkdir)(outputDir, { recursive: true });
   for (const fileRef of listResult.items) {
     console.log(fileRef.name);
     if (subDir && !fileRef.name.includes(subString))
       continue;
-    const bytes = await (0, import_storage7.getBytes)(fileRef);
+    const bytes = await (0, import_storage9.getBytes)(fileRef);
     const outputPath = (0, import_path2.join)(outputDir, fileRef.name);
     await (0, import_promises.writeFile)(outputPath, Buffer.from(bytes));
     console.log(`Downloaded ${fileRef.name} to ${outputPath} \u2705`);
@@ -11242,16 +11532,16 @@ async function dumpHandler(options) {
 }
 
 // apps/desktop/cue-cli/src/helpers/repair-remote-ttl.ts
-var import_storage8 = require("firebase/storage");
+var import_storage10 = require("firebase/storage");
 async function repairRemoteTTL(space, subString, regex, substituteString) {
   const firebase = CueFirebase.getInstance();
   const storage = firebase.storageProcessed;
   console.log("Fetching files from storage bucket 'triples' containing substring:", subString);
-  const listResult = await (0, import_storage8.listAll)((0, import_storage8.ref)(storage, `${space}/triples`));
+  const listResult = await (0, import_storage10.listAll)((0, import_storage10.ref)(storage, `${space}/triples`));
   for (const fileRef of listResult.items) {
     if (subString && !fileRef.name.match(subString))
       continue;
-    const stream = await (0, import_storage8.getStream)(fileRef);
+    const stream = await (0, import_storage10.getStream)(fileRef);
     const reader = stream.getReader();
     const chunks = [];
     let done = false;
@@ -11275,13 +11565,13 @@ async function repairRemoteTTL(space, subString, regex, substituteString) {
       const buffer = Buffer.from(fileContent, "utf8");
       let existingMetadata = {};
       try {
-        existingMetadata = await (0, import_storage8.getMetadata)(fileRef);
+        existingMetadata = await (0, import_storage10.getMetadata)(fileRef);
       } catch (err) {
         console.warn(`Could not fetch metadata for ${fileRef.name}, proceeding with default.`);
       }
       const customMetadata = { ...existingMetadata.customMetadata || {}, stored: "False" };
       const metadata = { customMetadata };
-      await (0, import_storage8.uploadBytesResumable)((0, import_storage8.ref)(storage, `${space}/triples/${fileRef.name}`), buffer, metadata);
+      await (0, import_storage10.uploadBytesResumable)((0, import_storage10.ref)(storage, `${space}/triples/${fileRef.name}`), buffer, metadata);
       console.log(`Fixed ${fileRef.name} \u2705`);
     } else {
       console.log(`No changes for ${fileRef.name}`);
@@ -12036,6 +12326,7 @@ async function listProjectsHandler(options) {
       lastSync: p.lastSync
     }));
     console.log(JSON.stringify(output, null, 2));
+    process.exit(0);
   } catch (err) {
     console.error("Error:", err instanceof Error ? err.message : String(err));
     process.exit(1);
@@ -12057,6 +12348,7 @@ async function entitySummaryGraphHandler(options) {
       const raw = await entities.buildSummaryGraph();
       console.log(JSON.stringify(raw, null, 2));
     }
+    process.exit(0);
   } catch (err) {
     console.error("Error:", err instanceof Error ? err.message : String(err));
     process.exit(1);
@@ -12084,6 +12376,7 @@ async function sparqlHandler(options) {
       console.error(`Executing SPARQL query against project ${options.space}...`);
     const result = await cue.api.sparql(sparqlQuery, options.space);
     console.log(JSON.stringify(result, null, 2));
+    process.exit(0);
   } catch (err) {
     console.error("Error:", err instanceof Error ? err.message : String(err));
     process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qaecy/cue-cli",
-  "version": "0.0.47",
+  "version": "0.0.48",
   "description": "Cue CLI for QAECY platform",
   "main": "main.js",
   "bin": {