@qaecy/cue-cli 0.0.46 → 0.0.47

package/main.js

@@ -372,7 +372,7 @@ var init_md5_builder_node = __esm({
 });
 
 // apps/desktop/cue-cli/src/main.ts
-var import_commander = require("commander");
+var import_commander2 = require("commander");
 var import_fs8 = require("fs");
 var import_path4 = require("path");
 
@@ -4721,6 +4721,53 @@ var prefixCC = {
   rex: "http://purl.obolibrary.org/obo/REX_"
 };
 
+// libs/js/prefixes/src/lib/compact-expand.ts
+var CompactExpand = class _CompactExpand {
+  static _instance;
+  // Opposite map is built once
+  _nsMap;
+  static getInstance() {
+    if (this._instance) {
+      return this._instance;
+    }
+    this._instance = new _CompactExpand();
+    return this._instance;
+  }
+  compactIRI(iri) {
+    let nsMap = this._nsMap;
+    if (nsMap === void 0)
+      nsMap = this._buildNSMap();
+    let ns = iri;
+    if (iri.includes("#"))
+      ns = `${iri.split("#")[0]}#`;
+    else {
+      const parts = iri.split("/");
+      parts.pop();
+      ns = parts.join("/") + "/";
+    }
+    if (ns === void 0)
+      return iri;
+    const pfx = nsMap[ns];
+    if (pfx === void 0)
+      return iri;
+    return iri.replace(ns, `${pfx}:`);
+  }
+  expandIRI(iri) {
+    const prefix = iri.split(":")[0];
+    const ns = prefixCC[prefix] ?? qaecyPrefixes[prefix];
+    return iri.replace(`${prefix}:`, ns);
+  }
+  _buildNSMap() {
+    const map = {};
+    Object.keys(prefixCC).forEach((key) => map[prefixCC[key]] = key);
+    Object.keys(qaecyPrefixes).forEach(
+      (key) => map[qaecyPrefixes[key]] = key
+    );
+    this._nsMap = map;
+    return map;
+  }
+};
+
 // libs/js/sync-tools/src/lib/list-remote-files.ts
 async function listRemoteFiles(spaceId, providerId, queryHandler2, verbose = false) {
   const firebase = CueFirebase.getInstance();
@@ -5097,8 +5144,10 @@ var ENDPOINT_CREATE_PROJECT = "/commands/admin/project";
 var ENDPOINT_SEARCH = "/assistant/search";
 var ENDPOINT_FUSEKI_QUERY = "/triplestore/query";
 var ENDPOINT_FUSEKI_UPDATE = "/triplestore/update";
+var ENDPOINT_FUSEKI_SHACL = "/triplestore/shacl";
 var ENDPOINT_QLEVER_QUERY = "/qlever-server/qlever/query";
 var ENDPOINT_QLEVER_UPDATE = "/qlever-server/qlever/update";
+var ENDPOINT_QLEVER_SHACL = "/qlever-server/qlever/shacl";
 var ENDPOINT_FSS_BATCH = "/commands/file-system-structure/batch";
 var MICROSOFT_PROVIDER_ID = "microsoft.com";
 var SUPERADMIN_ROLE = "superadmin";
@@ -5290,6 +5339,49 @@ var CueAuth = class {
   }
 };
 
+// libs/js/cue-sdk/src/lib/tables.ts
+var ENDPOINT_DATA_VIEWS_TABLES = "/data-views/tables";
+var ENDPOINT_COMMANDS_TABLES = "/commands/tables";
+var CueTables = class {
+  constructor(_auth, _gatewayUrl) {
+    this._auth = _auth;
+    this._gatewayUrl = _gatewayUrl;
+  }
+  async listTables(projectId) {
+    const response = await this._auth.authenticatedFetch(
+      `${this._gatewayUrl}${ENDPOINT_DATA_VIEWS_TABLES}`,
+      {
+        headers: {
+          "Content-Type": "application/json",
+          "x-project-id": projectId,
+          "cue-project-id": projectId
+        }
+      }
+    );
+    if (!response.ok) {
+      throw new Error(`Failed to list tables: ${response.status} ${response.statusText}`);
+    }
+    return response.json();
+  }
+  async saveTables(tables, projectId) {
+    const response = await this._auth.authenticatedFetch(
+      `${this._gatewayUrl}${ENDPOINT_COMMANDS_TABLES}`,
+      {
+        method: "PUT",
+        headers: {
+          "Content-Type": "application/json",
+          "x-project-id": projectId,
+          "cue-project-id": projectId
+        },
+        body: JSON.stringify(tables)
+      }
+    );
+    if (!response.ok) {
+      throw new Error(`Failed to save tables: ${response.status} ${response.statusText}`);
+    }
+  }
+};
+
 // libs/js/cue-sdk/src/lib/api.ts
 var CueApi = class {
   constructor(_auth, _gatewayUrl, projects, sync) {
@@ -5297,6 +5389,14 @@ var CueApi = class {
     this._gatewayUrl = _gatewayUrl;
     this.projects = projects;
     this.sync = sync;
+    this.tables = new CueTables(_auth, _gatewayUrl);
+  }
+  tables;
+  /** Active language used for language-sensitive SPARQL queries across all project classes. */
+  language = "en";
+  /** Updates the active language. All project classes (`CueProjectSchema`, `CueProjectDocuments`, `CueProjectEntities`) read this at query time. */
+  setLanguage(lang) {
+    this.language = lang;
   }
   /**
    * Returns standard authentication headers for the current user.
@@ -5368,6 +5468,57 @@ var CueApi = class {
     }
     return response.json();
   }
+  /**
+   * Validate a SHACL shape against the project's triplestore.
+   *
+   * @param shape     - SHACL shapes graph in Turtle syntax.
+   * @param projectId - Project to validate against.
+   * @param options   - `format`: `'json-ld'` (default, structured result) or `'turtle'` (raw string).
+   *                    `verbose`: include server-side timing logs.
+   *
+   * Returns a {@link ShaclValidationReport} for JSON-LD, or a Turtle string.
+   */
+  async shacl(shape, projectId, options) {
+    const fmt = options?.format ?? "json-ld";
+    const accept = fmt === "turtle" ? "text/turtle" : "application/ld+json";
+    if (options?.graphType === "fuseki") {
+      const response2 = await this._auth.authenticatedFetch(
+        `${this._gatewayUrl}${ENDPOINT_FUSEKI_SHACL}`,
+        {
+          method: "POST",
+          headers: {
+            "Content-Type": "text/turtle",
+            "Accept": accept,
+            "x-project-id": projectId,
+            "cue-project-id": projectId
+          },
+          body: shape
+        }
+      );
+      if (!response2.ok) {
+        const msg = await response2.text().catch(() => "");
+        throw new Error(`SHACL validation failed: ${response2.status} ${response2.statusText}${msg ? " \u2014 " + msg.slice(0, 200) : ""}`);
+      }
+      return fmt === "turtle" ? response2.text() : response2.json();
+    }
+    const url = `${this._gatewayUrl}${ENDPOINT_QLEVER_SHACL}${options?.verbose ? "?verbose=true" : ""}`;
+    const body = new URLSearchParams({ shape });
+    const response = await this._auth.authenticatedFetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        "Accept": accept,
+        "x-project-id": projectId,
+        "cue-project-id": projectId
+      },
+      body
+    });
+    if (!response.ok) {
+      const msg = await response.text().catch(() => "");
+      throw new Error(`SHACL validation failed: ${response.status} ${response.statusText}${msg ? " \u2014 " + msg.slice(0, 200) : ""}`);
+    }
+    return fmt === "turtle" ? response.text() : response.json();
+  }
   async getConsumption(projectId) {
     const response = await this._auth.authenticatedFetch(
       `${this._gatewayUrl}${ENDPOINT_CONSUMPTION}`,
@@ -7552,19 +7703,20 @@ var CueProjectSchema = class {
     this._projectId = _projectId;
     this._queryCache = _queryCache;
     this._graphType = _graphType;
-    this._language = new CueSignal(language);
+    this._currentLang = language;
+    this._api.setLanguage(language);
     this._contentCategories = new CueSignal([]);
     this._entityCategories = new CueSignal([]);
     this._relationships = new CueSignal([]);
     this.availableContentCategories = this._contentCategories.asReadonly();
     this.availableEntityCategories = this._entityCategories.asReadonly();
     this.availableEntityRelationships = this._relationships.asReadonly();
-    this._load(language).catch(
+    this.ready = this._load(language).catch(
       (err) => console.error("[CueProjectSchema] Initial load failed:", err)
     );
   }
   _cache = /* @__PURE__ */ new Map();
-  _language;
+  _currentLang;
   _contentCategories;
   _entityCategories;
   _relationships;
@@ -7574,9 +7726,14 @@ var CueProjectSchema = class {
   availableEntityCategories;
   /** Currently active entity relationship types for the selected language. */
   availableEntityRelationships;
+  /**
+   * Resolves when the initial schema load for the constructor language has
+   * completed (or failed). Await this before reading signal values imperatively.
+   */
+  ready;
   /** Returns the currently active language. */
   get language() {
-    return this._language.get();
+    return this._api.language;
   }
   /**
    * Switch the active language. If the data for this language has already been
@@ -7584,9 +7741,10 @@ var CueProjectSchema = class {
    * is triggered.
    */
   setLanguage(lang) {
-    if (this._language.get() === lang)
+    if (this._currentLang === lang)
       return;
-    this._language.set(lang);
+    this._currentLang = lang;
+    this._api.setLanguage(lang);
     this._load(lang).catch(
       (err) => console.error("[CueProjectSchema] Language switch failed:", err)
     );
@@ -7596,7 +7754,7 @@ var CueProjectSchema = class {
    * Useful when the triplestore data has changed.
    */
   async refresh() {
-    const lang = this._language.get();
+    const lang = this._api.language;
     this._cache.delete(lang);
     await this._load(lang);
   }
@@ -7622,7 +7780,7 @@ var CueProjectSchema = class {
       },
       (snapshot) => {
         this._cache.set(lang, snapshot);
-        if (this._language.get() === lang)
+        if (this._currentLang === lang)
           this._apply(snapshot);
       },
       this._queryCache
@@ -7711,7 +7869,9 @@ var CueProjectEntities = class {
   baseURL;
   // ── Internal writable slices ───────────────────────────────────────────────
   _entityDetails = new CueSignal({});
-  _entityDocuments = new CueSignal({});
+  _entityDocuments = new CueSignal(
+    {}
+  );
   _entityRelationships = new CueSignal({});
   _entityOSMMap = new CueSignal({});
   _osmWKTMap = new CueSignal({});
@@ -7753,7 +7913,10 @@ var CueProjectEntities = class {
     this._entityGraph.set(void 0);
     this._fetchingOSMIds.clear();
     this._fetchEntityGraph().catch(
-      (err) => console.error("[CueProjectEntities] Entity graph fetch failed after reset:", err)
+      (err) => console.error(
+        "[CueProjectEntities] Entity graph fetch failed after reset:",
+        err
+      )
     );
   }
   // ── Public imperative API ──────────────────────────────────────────────────
@@ -7764,7 +7927,9 @@ var CueProjectEntities = class {
    * Data is merged into `entityInfoMap` once the SPARQL response arrives.
    */
   requestEntityData(uuids, includeMentionCount = false) {
-    const newUUIDs = uuids.filter((id) => this._entityDetails.get()[id] === void 0);
+    const newUUIDs = uuids.filter(
+      (id) => this._entityDetails.get()[id] === void 0
+    );
     if (newUUIDs.length === 0)
       return;
     const values = newUUIDs.map((id) => `r:${id}`).join(" ");
@@ -7782,7 +7947,9 @@ WHERE {
 GROUP BY ?id ?mentionCount`;
     this._api.sparql(q, this._projectId, this._graphType).then((data) => {
       const result = data;
-      const updates = { ...this._entityDetails.get() };
+      const updates = {
+        ...this._entityDetails.get()
+      };
       result.results.bindings.forEach((b) => {
         if (!b["id"])
           return;
@@ -7806,7 +7973,9 @@ GROUP BY ?id ?mentionCount`;
    * query and merged into `entityInfoMap` reactively once it arrives.
    */
   async requestEntityLocations(uuids) {
-    const newUUIDs = uuids.filter((id) => this._entityOSMMap.get()[id] === void 0);
+    const newUUIDs = uuids.filter(
+      (id) => this._entityOSMMap.get()[id] === void 0
+    );
     if (newUUIDs.length === 0)
       return;
     const osmInit = { ...this._entityOSMMap.get() };
@@ -7842,7 +8011,11 @@ WHERE {
   }
   BIND(REPLACE(STR(?iri), "^.*/([^/]*)$", "$1") AS ?id)
 }`;
-    const data = await this._api.sparql(q, this._projectId, this._graphType);
+    const data = await this._api.sparql(
+      q,
+      this._projectId,
+      this._graphType
+    );
     const update = { ...this._entityOSMMap.get() };
     data.results.bindings.forEach((b) => {
       if (!b["id"] || !b["osm"])
@@ -7881,7 +8054,10 @@ WHERE {
       this._fetchIncomingRelationships(iri)
     ]);
     const result = { outgoing, incoming };
-    this._entityRelationships.set({ ...this._entityRelationships.get(), [uuid]: result });
+    this._entityRelationships.set({
+      ...this._entityRelationships.get(),
+      [uuid]: result
+    });
     return result;
   }
   /**
@@ -7905,11 +8081,111 @@ WHERE {
          qcy:about ?iri .
     BIND(REPLACE(STR(?doc), "^.*/([^/]*)$", "$1") AS ?id)
 }`;
-    const data = await this._api.sparql(q, this._projectId, this._graphType);
+    const data = await this._api.sparql(
+      q,
+      this._projectId,
+      this._graphType
+    );
     const ids = data.results.bindings.filter((b) => b["id"] !== void 0).map((b) => b["id"].value);
     this._entityDocuments.set({ ...this._entityDocuments.get(), [uuid]: ids });
     return ids;
   }
+  /**
+   * Fetches all `qcy:EntityCategory` IRIs and their preferred labels for this
+   * project. Uses `api.language` (default `'en'`);
+   * falls back to an untagged label when no match is found.
+   */
+  async contentCategoriesInProject(orderByOccurences = true) {
+    const language = this._api.language;
+    const q = `PREFIX qcy: <${qaecyPrefixes["qcy"]}>
+PREFIX skos: <${prefixCC["skos"]}>
+SELECT ?iri (SAMPLE(?l) AS ?label) ?count
+WHERE {
+    ?iri a qcy:EntityCategory .
+    OPTIONAL { ?iri skos:prefLabel ?lang_label FILTER(LANG(?lang_label) = "${language}") }
+    OPTIONAL { ?iri skos:prefLabel ?no_lang_label }
+    BIND(COALESCE(?lang_label, ?no_lang_label) AS ?l)
+    ${orderByOccurences ? "{ SELECT (COUNT(?x) AS ?count) ?iri where { ?x a qcy:CanonicalEntity ; qcy:hasEntityCategory ?iri } GROUP BY ?iri }" : ""}
+}
+GROUP BY ?iri ?count
+ORDER BY ${orderByOccurences ? "DESC(?count)" : "ASC(?label)"}`;
+    const data = await this._api.sparql(
+      q,
+      this._projectId,
+      this._graphType
+    );
+    return data.results.bindings.filter((b) => b["iri"] !== void 0).map((b) => {
+      const count = b["count"] ? parseInt(b["count"].value, 10) : 0;
+      const label = b["label"]?.value ?? b["iri"].value.split("#").at(-1);
+      const labelWithCount = count > 0 ? `${label} (${count})` : label ?? "";
+      return {
+        iri: b["iri"].value,
+        label: labelWithCount
+      };
+    });
+  }
+  async buildSummaryGraph(format) {
+    const q = `PREFIX qcy: <${qaecyPrefixes["qcy"]}>
+SELECT
+  ?sourceCat
+  ?predicate
+  ?targetCat
+  (COUNT(*) AS ?weight)
+WHERE {
+  ?s a qcy:CanonicalEntity ;
+       qcy:hasEntityCategory ?sourceCat .
+  ?o a qcy:CanonicalEntity ;
+       qcy:hasEntityCategory ?targetCat .
+  ?s ?predicate ?o .
+  FILTER(isIRI(?s) && isIRI(?o))
+  FILTER(?predicate != qcy:relatedEntity)
+}
+GROUP BY ?sourceCat ?predicate ?targetCat
+ORDER BY DESC(?weight)`;
+    const data = await this._api.sparql(
+      q,
+      this._projectId,
+      this._graphType
+    );
+    const bindings = data.results.bindings.filter(
+      (b) => b["sourceCat"] && b["predicate"] && b["targetCat"]
+    );
+    if (format === "graph") {
+      const irisSet = /* @__PURE__ */ new Set();
+      const relations = [];
+      for (const b of bindings) {
+        const sourceID = b["sourceCat"].value;
+        const predicate = b["predicate"].value;
+        const targetID = b["targetCat"].value;
+        const weight = parseInt(b["weight"].value, 10);
+        irisSet.add(sourceID);
+        irisSet.add(targetID);
+        relations.push({ sourceID, predicate, targetID, weight });
+      }
+      return {
+        entities: Array.from(irisSet).map((iri) => ({ iri })),
+        relations
+      };
+    }
+    if (format === "md") {
+      const ce = CompactExpand.getInstance();
+      const rows = bindings.map((b) => ({
+        src: ce.compactIRI(b["sourceCat"].value),
+        pred: ce.compactIRI(b["predicate"].value),
+        tgt: ce.compactIRI(b["targetCat"].value),
+        weight: parseInt(b["weight"].value, 10)
+      }));
+      if (rows.length === 0)
+        return "(no results)";
+      const maxSrc = Math.max(...rows.map((r) => r.src.length));
+      const maxPred = Math.max(...rows.map((r) => r.pred.length));
+      const maxTgt = Math.max(...rows.map((r) => r.tgt.length));
+      return rows.map(
+        (r) => `${r.src.padEnd(maxSrc)} -> ${r.pred.padEnd(maxPred)} -> ${r.tgt.padEnd(maxTgt)}  (${r.weight})`
+      ).join("\n");
+    }
+    return data;
+  }
   // ── Private helpers ────────────────────────────────────────────────────────
   _computeEntityInfoMap() {
     const details = this._entityDetails.get();
@@ -7983,7 +8259,11 @@ WHERE {
     FILTER(?rel != qcy:relatedEntity)
 }
 GROUP BY ?rel ?related`;
-    const data = await this._api.sparql(q, this._projectId, this._graphType);
+    const data = await this._api.sparql(
+      q,
+      this._projectId,
+      this._graphType
+    );
     const result = [];
     const detailsUpdate = { ...this._entityDetails.get() };
     data.results.bindings.forEach((b) => {
@@ -8017,7 +8297,11 @@ WHERE {
     FILTER(?rel != qcy:relatedEntity)
 }
 GROUP BY ?rel ?relating`;
-    const data = await this._api.sparql(q, this._projectId, this._graphType);
+    const data = await this._api.sparql(
+      q,
+      this._projectId,
+      this._graphType
+    );
     const result = [];
     const detailsUpdate = { ...this._entityDetails.get() };
     data.results.bindings.forEach((b) => {
@@ -8052,7 +8336,11 @@ GROUP BY ?e1Cat ?e2Cat`;
     await staleWhileRevalidate(
       q,
       async () => {
-        const data = await this._api.sparql(q, this._projectId, this._graphType);
+        const data = await this._api.sparql(
+          q,
+          this._projectId,
+          this._graphType
+        );
         const entities = [];
         const relations = [];
         data.results.bindings.forEach((b) => {
@@ -8109,7 +8397,11 @@ SELECT * WHERE {
         ?s geo:hasGeometry/geo:asWKT ?wkt
     }
 }`;
-    const data = await this._api.sparql(q, this._projectId, this._graphType);
+    const data = await this._api.sparql(
+      q,
+      this._projectId,
+      this._graphType
+    );
     const update = { ...this._osmWKTMap.get() };
     data.results.bindings.forEach((b) => {
       if (!b["s"] || !b["wkt"])
@@ -8129,13 +8421,14 @@ var CueProjectDocuments = class {
     this._queryCache = _queryCache;
     this._graphType = _graphType;
     this.baseURL = `${rdfBase}${_projectId}/`;
-    this._language = language;
+    this._currentLang = language ?? this._api.language;
     this.documentInfoMap = this._documentInfoMap.asReadonly();
     this.projectDocumentsData = this._projectDocumentsData.asReadonly();
   }
   /** Full RDF base URL for this project, e.g. `https://cue.qaecy.com/r/{pid}/` */
   baseURL;
-  _language;
+  /** Tracks the language for which `_documentInfoMap` is currently populated. */
+  _currentLang;
   _documentInfoMap = new CueSignal({});
   _projectDocumentsData = new CueSignal({
     duplicateCount: 0,
@@ -8165,9 +8458,10 @@ var CueProjectDocuments = class {
    * `requestDocumentData()` call.
    */
   setLanguage(lang) {
-    if (this._language === lang)
+    if (this._currentLang === lang)
       return;
-    this._language = lang;
+    this._currentLang = lang;
+    this._api.setLanguage(lang);
     this._documentInfoMap.set({});
   }
   // ── Public API ─────────────────────────────────────────────────────────────
@@ -8209,7 +8503,7 @@ var CueProjectDocuments = class {
     if (newUUIDs.length === 0)
       return;
     const values = newUUIDs.map((id) => `r:${id}`).join(" ");
-    const lang = this._language;
+    const lang = this._api.language;
     const q = `PREFIX qcy: <${qaecyPrefixes["qcy"]}>
 PREFIX r: <${this.baseURL}>
 SELECT ?id ?contentIRI ?suffix ?size ?subject ?summary
@@ -8262,6 +8556,21 @@ GROUP BY ?id ?contentIRI ?suffix ?size ?subject ?summary`;
       (err) => console.error("[CueProjectDocuments] requestDocumentData failed:", err)
     );
   }
+  /**
+   * 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 ────────────────────────────────────────────────────────
   async _fetchDocumentsBySuffix() {
     return this._runDocumentsBySuffixQuery(this._buildDocumentsBySuffixQuery());
@@ -8364,6 +8673,7 @@ var CueProjectView = class {
     this.availableContentCategories = this.schema.availableContentCategories;
     this.availableEntityCategories = this.schema.availableEntityCategories;
     this.availableEntityRelationships = this.schema.availableEntityRelationships;
+    this.schemaReady = this.schema.ready;
     this.entityInfoMap = this.entities.entityInfoMap;
     this.entityGraph = this.entities.entityGraph;
     this.documentInfoMap = this.documents.documentInfoMap;
@@ -8384,6 +8694,11 @@ var CueProjectView = class {
   availableEntityCategories;
   /** Available entity relationship types. Auto-fetched on init. */
   availableEntityRelationships;
+  /**
+   * Resolves when the initial schema load has completed. Await before reading
+   * schema signal values imperatively.
+   */
+  schemaReady;
   /** Merged per-entity detail map. Populated lazily via `requestEntityData()` etc. */
   entityInfoMap;
   /** Project-level entity co-occurrence graph. Fetched once on init. */
@@ -11201,10 +11516,17 @@ async function syncHandler(options) {
     process.exit(0);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
+    const cause = err instanceof Error ? err.cause : void 0;
+    const causeCode = cause instanceof Error ? cause.code : void 0;
+    const causeMsg = cause instanceof Error ? cause.message : void 0;
+    const isTimeout = causeCode === "UND_ERR_HEADERS_TIMEOUT" || causeCode === "UND_ERR_BODY_TIMEOUT" || causeCode === "UND_ERR_CONNECT_TIMEOUT" || causeMsg?.includes("Timeout") || msg.includes("fetch failed");
     if (msg.includes("GRAPH_UNAVAILABLE")) {
       console.error("The knowledge graph for this project has no database configured. Contact your administrator or check the project setup.");
-    } else if (msg.includes("GRAPH_TIMEOUT")) {
-      console.error("Could not reach the knowledge graph. Make sure all required services are running.");
+    } else if (msg.includes("GRAPH_TIMEOUT") || isTimeout) {
+      console.error("Could not reach the QAECY API \u2014 the request timed out or the server could not be reached.");
+      console.error("Check your internet connection and try again. If the problem persists, the service may be temporarily unavailable.");
+      if (verbose && causeCode)
+        console.error(`  Cause: ${causeMsg ?? causeCode}`);
     } else if (msg.includes("METADATA_SYNC_FAILED")) {
       console.error("Metadata sync failed. Try again.");
     } else if (msg.includes("LEDGER_WRITE_FAILED") || msg.includes("File structure batch POST failed")) {
@@ -11212,7 +11534,13 @@ async function syncHandler(options) {
         "Failed communication with the knowledge graph. The files are up to date but metadata is not. Run the tool again to sync metadata. This is a swift job."
       );
     } else {
-      console.error("[syncHandler] Unexpected error:", err);
+      console.error("An unexpected error occurred during sync.");
+      if (verbose) {
+        console.error("Details:", err);
+      } else {
+        console.error(`  ${msg}`);
+        console.error("Re-run with --verbose for more details.");
+      }
     }
     process.exit(1);
   }
@@ -11675,6 +12003,97 @@ Project created \u2705`);
   }
 }
 
+// apps/desktop/cue-cli/src/cue-cli-app-builder-tools.ts
+var import_commander = require("commander");
+async function buildCueClient(options) {
+  const key = options.key ?? process.env["CUE_API_KEY"];
+  if (!key) {
+    console.error("API key is required. Provide it via --key or CUE_API_KEY env variable.");
+    process.exit(1);
+  }
+  const cue = new CueNode({
+    apiKey: FIREBASE_CONFIG().apiKey,
+    appId: FIREBASE_CONFIG().appId,
+    measurementId: FIREBASE_CONFIG().measurementId,
+    environment: options.emulators ? "emulator" : "production",
+    ...options.emulators ? { endpoints: getEmulatorEndpoints() } : {}
+  });
+  await cue.auth.signInWithApiKey(key);
+  return cue;
+}
+async function listProjectsHandler(options) {
+  try {
+    const cue = await buildCueClient(options);
+    if (options.verbose)
+      console.error("Fetching projects...");
+    const projects = await cue.api.projects.listProjects();
+    const output = projects.map((p) => ({
+      id: p.id,
+      name: p.name,
+      organizationID: p.organizationID,
+      isPublic: p.isPublic,
+      graphType: p.projectSettings?.graph?.type ?? "qlever",
+      lastSync: p.lastSync
+    }));
+    console.log(JSON.stringify(output, null, 2));
+  } catch (err) {
+    console.error("Error:", err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+}
+async function entitySummaryGraphHandler(options) {
+  try {
+    const cue = await buildCueClient(options);
+    if (options.verbose)
+      console.error(`Fetching entity summary graph for project ${options.space}...`);
+    const entities = new CueProjectEntities(cue.api, options.space);
+    if (options.format === "graph") {
+      const graph = await entities.buildSummaryGraph("graph");
+      console.log(JSON.stringify(graph, null, 2));
+    } else if (options.format === "md") {
+      const md = await entities.buildSummaryGraph("md");
+      console.log(md);
+    } else {
+      const raw = await entities.buildSummaryGraph();
+      console.log(JSON.stringify(raw, null, 2));
+    }
+  } catch (err) {
+    console.error("Error:", err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+}
+async function sparqlHandler(options) {
+  try {
+    let sparqlQuery = options.query;
+    if (!sparqlQuery) {
+      if (process.stdin.isTTY) {
+        console.error("Provide a SPARQL query via --query or pipe it via stdin.");
+        process.exit(1);
+      }
+      const chunks = [];
+      for await (const chunk of process.stdin)
+        chunks.push(chunk);
+      sparqlQuery = Buffer.concat(chunks).toString("utf8").trim();
+    }
+    if (!sparqlQuery) {
+      console.error("SPARQL query is empty.");
+      process.exit(1);
+    }
+    const cue = await buildCueClient(options);
+    if (options.verbose)
+      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));
+  } catch (err) {
+    console.error("Error:", err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+}
+var appBuilderToolsCommand = new import_commander.Command("app-builder-tools").description("Tools for agent-assisted Cue app development. Outputs JSON for machine consumption.");
+appBuilderToolsCommand.command("list-projects").description("List all projects accessible to the authenticated user").option("-k, --key <api-key>", "Specify the API key (or set CUE_API_KEY env variable)").option("-e, --emulators", "Use emulators", false).option("-v, --verbose", "Enable verbose output", false).action(listProjectsHandler);
+appBuilderToolsCommand.command("entity-summary-graph").description("Fetch the entity category relationship summary graph for a project").requiredOption("-s, --space <id>", "Project ID (required)").option("-k, --key <api-key>", "Specify the API key (or set CUE_API_KEY env variable)").option("-e, --emulators", "Use emulators", false).option("-f, --format <format>", "Output format: md (aligned text), graph (JSON nodes+edges), json (raw SPARQL)", "md").option("-v, --verbose", "Enable verbose output", false).action(entitySummaryGraphHandler);
+appBuilderToolsCommand.command("sparql").description("Execute a SPARQL SELECT query against a project triplestore. Query via --query or stdin.").requiredOption("-s, --space <id>", "Project ID (required)").option("-q, --query <sparql>", "SPARQL query string (or pipe query via stdin)").option("-k, --key <api-key>", "Specify the API key (or set CUE_API_KEY env variable)").option("-e, --emulators", "Use emulators", false).option("-v, --verbose", "Enable verbose output", false).action(sparqlHandler);
+
 // apps/desktop/cue-cli/src/main.ts
 var packageJson;
 try {
@@ -11687,7 +12106,7 @@ try {
     console.warn("Could not find package.json, using fallback version");
   }
 }
-var program = new import_commander.Command();
+var program = new import_commander2.Command();
 program.name("cue-cli").description("Cue Command Line Interface").version(packageJson.version);
 program.command("sync").description("Sync files to Cue").option("-s, --space <id>", "Specify the space ID (omit to pick interactively)").requiredOption("-p, --path <id>", "Specify the folder path (required)").option("-k, --key <api-key>", "Specify the API key (or set CUE_API_KEY env variable)").option("--provider <provider ID>", "Specify the provider ID (eg. sharepoint, drive, dropbox) or leave empty for default provider", "").option("-v, --verbose", "Enable verbose output", false).option("-e, --emulators", "Uses emulators for sync", false).option("-z, --zip", 'Include zipped content (will be unzipped to path "<zip_path>_unzipped". Max uncompressed size: 500 MB, max recursion depth: 3)', false).option("--legacy", "Write RDF as BLOBs to the processed bucket instead of patching the graph directly", false).option("--metadata-only", "Push filesystem-structure metadata for all local files without checking credits or remote state", false).action(syncHandler);
 program.command("dump").description("Dump Cue Knowledge Graph data to file\n				Examples:\n				$ cue-cli dump -s <space_id> -l -v\n				$ cue-cli dump -s <space_id> -j -v").requiredOption("-s, --space <id>", "Specify the space ID (required)").option("-k, --key <api-key>", "Specify the API key (or set CUE_API_KEY env variable)").option("-v, --verbose", "Enable verbose output", false).option("-e, --emulators", "Uses emulators for sync", false).option("-q, --query", "Uses a construct query to get the dump rather than using the /data endpoint", false).option("-j, --jelly", "Downloads a Jelly file rather than the standard Gzipped NQuads format", false).option("-l, --load", "Loads the dumped file into a local triplestore (requires emulators)", false).action(dumpHandler);
@@ -11697,4 +12116,5 @@ program.command("repair-ttl").description("Repair TTL files in the specified spa
 program.command("util-rdf-compare").description("Compare two Turtle (.ttl) files and report semantic differences").requiredOption("--file1 <path>", "Path to the first TTL file").requiredOption("--file2 <path>", "Path to the second TTL file").option("-v, --verbose", "Enable verbose output", false).action(utilRdfCompareHandler);
 program.command("util-remove-rdf-star").description("Remove RDF-star (quoted) triples from an NQuads file. Supports .nq and .nq.gz input/output.").requiredOption("-i, --input <path>", "Input file path (.nq or .nq.gz)").requiredOption("-o, --output <path>", "Output file path (.nq or .nq.gz)").option("-v, --verbose", "Enable verbose output", false).action(utilRemoveRdfStarHandler);
 program.command("create-project").description("Interactively create a new project under an organisation").option("-k, --key <api-key>", "Specify the API key (or set CUE_API_KEY env variable)").option("-e, --emulators", "Uses emulators", false).option("-v, --verbose", "Enable verbose output", false).action(createProjectHandler);
+program.addCommand(appBuilderToolsCommand);
 program.parse(process.argv);

package/package.json

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

package/readme.md

@@ -35,6 +35,42 @@ To sync the current dir to the space with id `<space-id>` under the provider id
 | `--legacy`            | Write RDF metadata as serialised Turtle BLOBs to the processed storage bucket instead of patching the knowledge graph directly. Use this when the ledger and graph services are not yet available for the target environment. | `false` |
 | `--metadata-only`     | Push filesystem-structure metadata for every local file directly to the commands API, without checking what is already on the remote, running a credit estimate, or uploading any file content. Useful for repairing missing graph metadata after a migration or interrupted sync. Can be combined with `--legacy` to write the metadata as BLOBs. | `false` |
 
+### app-builder-tools
+
+A set of JSON-output commands designed for agent-assisted Cue app development. All sub-commands accept `-k/--key` (or `CUE_API_KEY`), `-e/--emulators`, and `-v/--verbose`.
+
+#### list-projects
+
+List all projects accessible to the authenticated user.
+
+`npx @qaecy/cue-cli app-builder-tools list-projects`
+
+Outputs a JSON array with `id`, `name`, `organizationID`, `isPublic`, `graphType`, and `lastSync` for each project.
+
+#### entity-summary-graph
+
+Fetch the entity category relationship summary graph for a project — useful for understanding the knowledge graph schema before writing queries.
+
+`npx @qaecy/cue-cli app-builder-tools entity-summary-graph -s <project-id>`
+
+| Option               | Description                                                                                  | Default |
+|----------------------|----------------------------------------------------------------------------------------------|---------|
+| `-s, --space <id>`   | Project ID (required)                                                                        | N/A     |
+| `-f, --format <fmt>` | Output format: `md` (aligned text table), `graph` (JSON nodes + weighted edges), `json` (raw SPARQL result) | `md` |
+
+#### sparql
+
+Execute a SPARQL SELECT query against a project triplestore. The query can be passed inline or piped via stdin. Outputs raw SPARQL JSON results.
+
+`npx @qaecy/cue-cli app-builder-tools sparql -s <project-id> -q "SELECT * WHERE { ?s ?p ?o } LIMIT 10"`
+
+`echo "SELECT * WHERE { ?s ?p ?o } LIMIT 10" | npx @qaecy/cue-cli app-builder-tools sparql -s <project-id>`
+
+| Option              | Description                                               | Default |
+|---------------------|-----------------------------------------------------------|---------|
+| `-s, --space <id>`  | Project ID (required)                                     | N/A     |
+| `-q, --query <sparql>` | SPARQL query string (or pipe query via stdin)          | N/A     |
+
 ### util-remove-rdf-star
 
 Remove RDF-star (quoted triple) statements from an NQuads file. Supports both plain `.nq` and gzipped `.nq.gz` files. If the input is gzipped the output will also be gzipped.