@kweaver-ai/kweaver-sdk 0.5.2 → 0.6.0

package/dist/templates/explorer/vega.js

@@ -0,0 +1,291 @@
+// ── Vega Tab ─────────────────────────────────────────────────────────────────
+
+// Caches
+const vegaCatalogCache = {};
+const vegaResourcesCache = {};
+const vegaDataCache = {};
+
+// ── API wrappers ──────────────────────────────────────────────────────────────
+
+async function vegaLoadCatalogs() {
+  return cachedFetch(vegaCatalogCache, "all", () => api("GET", "/api/vega/catalogs"));
+}
+
+async function vegaLoadResources(catalogId) {
+  return cachedFetch(vegaResourcesCache, catalogId, () =>
+    api("GET", `/api/vega/catalog-resources?catalogId=${enc(catalogId)}`),
+  );
+}
+
+async function vegaQueryData(resourceId, query) {
+  const key = `${resourceId}::${JSON.stringify(query ?? {})}`;
+  return cachedFetch(vegaDataCache, key, () =>
+    api("POST", "/api/vega/query", { resourceId, query: query ?? {} }),
+  );
+}
+
+// ── Health indicator ──────────────────────────────────────────────────────────
+
+function vegaHealthDot(status) {
+  if (!status) return '<span class="health-dot unknown" title="Unknown"></span>';
+  const s = String(status).toLowerCase();
+  if (s === "healthy" || s === "ok" || s === "active") return '<span class="health-dot healthy" title="Healthy"></span>';
+  if (s === "unhealthy" || s === "error" || s === "failed") return '<span class="health-dot unhealthy" title="Unhealthy"></span>';
+  return `<span class="health-dot unknown" title="${esc(status)}"></span>`;
+}
+
+function vegaGetHealth(health, catalogId) {
+  if (!health || health.error) return null;
+  // health may be an object keyed by catalog id, or an array of { id, status } items
+  if (Array.isArray(health)) {
+    const entry = health.find(h => h.id === catalogId || h.catalog_id === catalogId);
+    return entry ? (entry.status ?? entry.health_status ?? null) : null;
+  }
+  if (typeof health === "object") {
+    const entry = health[catalogId];
+    if (entry && typeof entry === "object") return entry.status ?? entry.health_status ?? null;
+    if (typeof entry === "string") return entry;
+    // Try nested data / entries
+    const items = health.data ?? health.entries ?? health.items;
+    if (Array.isArray(items)) {
+      const found = items.find(h => h.id === catalogId || h.catalog_id === catalogId);
+      return found ? (found.status ?? found.health_status ?? null) : null;
+    }
+  }
+  return null;
+}
+
+// ── Catalog list view ─────────────────────────────────────────────────────────
+
+function vegaRenderCatalogList($el, data) {
+  const { catalogs, health } = data;
+  const items = extractList(catalogs);
+
+  if (items.length === 0) {
+    $el.innerHTML = `
+      <div class="section-header"><h2>Vega Catalogs</h2></div>
+      <div class="empty-state">No catalogs found.</div>`;
+    return;
+  }
+
+  const cards = items.map(cat => {
+    const healthStatus = vegaGetHealth(health, cat.id);
+    const dot = vegaHealthDot(healthStatus);
+    const name = esc(cat.name ?? cat.id);
+    const connType = esc(cat.connector_type ?? cat.type ?? "—");
+    return `
+      <a class="catalog-card" href="#/vega/${enc(cat.id)}">
+        <div class="catalog-card-header">
+          <span class="health-indicator">${dot}</span>
+          <span class="catalog-name">${name}</span>
+        </div>
+        <div class="catalog-meta">${connType}</div>
+      </a>`;
+  });
+
+  $el.innerHTML = `
+    <div class="vega-view">
+      <h2>Vega Catalogs <span style="color:var(--text-secondary);font-weight:400">(${items.length})</span></h2>
+      <div class="catalog-grid">${cards.join("")}</div>
+    </div>`;
+}
+
+// ── Resource list view ────────────────────────────────────────────────────────
+
+function vegaRenderResourceList($el, catalogId, data) {
+  const items = extractList(data);
+
+  const breadcrumb = `
+    <div class="breadcrumb">
+      <a href="#/vega">Catalogs</a> / <strong>${esc(catalogId)}</strong>
+    </div>`;
+
+  if (items.length === 0) {
+    $el.innerHTML = `${breadcrumb}
+      <div class="section-header"><h2>Resources</h2></div>
+      <div class="empty-state">No resources found in this catalog.</div>`;
+    return;
+  }
+
+  const rows = items.map(r => {
+    const name = esc(r.name ?? r.id);
+    const rtype = esc(r.category ?? r.type ?? r.resource_type ?? "—");
+    const fields = r.schema?.fields?.length ?? r.fields?.length ?? r.field_count ?? "—";
+    return `
+      <tr style="cursor:pointer" onclick="location.hash='/vega/${enc(catalogId)}/${enc(r.id)}'">
+        <td>${name}</td>
+        <td>${esc(r.id)}</td>
+        <td>${rtype}</td>
+        <td>${esc(String(fields))}</td>
+      </tr>`;
+  });
+
+  $el.innerHTML = `
+    ${breadcrumb}
+    <div class="section-header"><h2>Resources <span class="count">(${items.length})</span></h2></div>
+    <table>
+      <thead><tr><th>Name</th><th>ID</th><th>Type</th><th>Fields</th></tr></thead>
+      <tbody>${rows.join("")}</tbody>
+    </table>`;
+}
+
+// ── Resource detail / data preview ───────────────────────────────────────────
+
+function vegaRenderSchema(fields) {
+  if (!Array.isArray(fields) || fields.length === 0) return "";
+  const rows = fields.map(f => `
+    <tr>
+      <td>${esc(f.name ?? f.field_name ?? "—")}</td>
+      <td>${esc(f.type ?? f.data_type ?? "—")}</td>
+      <td>${esc(f.description ?? "")}</td>
+    </tr>`).join("");
+  return `
+    <div class="section-header" style="margin-top:1.5rem"><h3>Schema Fields <span class="count">(${fields.length})</span></h3></div>
+    <table>
+      <thead><tr><th>Name</th><th>Type</th><th>Description</th></tr></thead>
+      <tbody>${rows}</tbody>
+    </table>`;
+}
+
+function vegaRenderDataPreview(rawData, fields) {
+  let rows = [];
+  if (Array.isArray(rawData)) {
+    rows = rawData;
+  } else if (rawData && typeof rawData === "object") {
+    rows = rawData.data ?? rawData.entries ?? rawData.rows ?? rawData.items ?? [];
+  }
+  if (!Array.isArray(rows) || rows.length === 0) {
+    return '<div class="empty-state">No data rows available.</div>';
+  }
+
+  const preview = rows.slice(0, 20);
+
+  // Determine columns: from schema fields or from first row keys
+  let cols;
+  if (Array.isArray(fields) && fields.length > 0) {
+    cols = fields.map(f => f.name ?? f.field_name).filter(Boolean);
+  } else if (typeof preview[0] === "object" && preview[0] !== null) {
+    cols = Object.keys(preview[0]);
+  } else {
+    cols = ["value"];
+  }
+
+  const headers = cols.map(c => `<th>${esc(c)}</th>`).join("");
+  const dataRows = preview.map(row => {
+    const cells = cols.map(c => {
+      const v = typeof row === "object" && row !== null ? row[c] : row;
+      return `<td>${formatValue(v)}</td>`;
+    });
+    return `<tr>${cells.join("")}</tr>`;
+  }).join("");
+
+  return `
+    <div class="section-header" style="margin-top:1.5rem">
+      <h3>Data Preview <span class="count">(first ${preview.length} rows)</span></h3>
+    </div>
+    <div style="overflow-x:auto">
+      <table>
+        <thead><tr>${headers}</tr></thead>
+        <tbody>${dataRows}</tbody>
+      </table>
+    </div>`;
+}
+
+async function vegaRenderResourceDetail($el, catalogId, resourceId) {
+  const breadcrumb = `
+    <div class="breadcrumb">
+      <a href="#/vega">Catalogs</a> /
+      <a href="#/vega/${enc(catalogId)}">${esc(catalogId)}</a> /
+      <strong>${esc(resourceId)}</strong>
+    </div>`;
+
+  $el.innerHTML = `${breadcrumb}<div class="loading-skeleton"><div class="skeleton skeleton-title"></div><div class="skeleton skeleton-list-item"></div><div class="skeleton skeleton-list-item"></div></div>`;
+
+  // Load resources list to get schema for this resource
+  let schemaFields = [];
+  try {
+    const resourcesData = await vegaLoadResources(catalogId);
+    const items = extractList(resourcesData);
+    const res = items.find(r => r.id === resourceId);
+    if (res) {
+      schemaFields = res.schema?.fields ?? res.fields ?? [];
+    }
+  } catch { /* schema is best-effort */ }
+
+  // Query first 20 rows
+  let dataPreviewHtml = "";
+  try {
+    const rawData = await vegaQueryData(resourceId, { limit: 20 });
+    dataPreviewHtml = vegaRenderDataPreview(rawData, schemaFields);
+  } catch (e) {
+    dataPreviewHtml = `
+      <div class="error-boundary">
+        <div class="error-icon">⚠️</div>
+        <h3>Failed to load data</h3>
+        <p>${esc(String(e))}</p>
+        <button class="retry-btn" onclick="location.reload()">Retry</button>
+      </div>`;
+  }
+
+  $el.innerHTML = `
+    ${breadcrumb}
+    <div class="section-header"><h2>${esc(resourceId)}</h2></div>
+    ${vegaRenderSchema(schemaFields)}
+    ${dataPreviewHtml}`;
+}
+
+// ── Main dispatcher ───────────────────────────────────────────────────────────
+
+async function renderVega($el, parts, _params) {
+  const myGen = navGeneration;
+
+  // parts = []              → catalog list + discover tasks
+  // parts = [catalogId]     → resources in that catalog
+  // parts = [catalogId, resourceId] → resource detail + data preview
+
+  if (parts.length === 0) {
+    $el.innerHTML = '<div class="loading-skeleton"><div class="skeleton skeleton-title"></div><div class="loading-skeleton grid"><div class="skeleton skeleton-card"></div><div class="skeleton skeleton-card"></div></div></div>';
+    try {
+      const data = await vegaLoadCatalogs();
+      if (navGeneration !== myGen) return;
+      vegaRenderCatalogList($el, data);
+    } catch (e) {
+      if (navGeneration !== myGen) return;
+      $el.innerHTML = `
+        <div class="error-boundary">
+          <div class="error-icon">⚠️</div>
+          <h3>Failed to load catalogs</h3>
+          <p>${esc(String(e))}</p>
+          <button class="retry-btn" onclick="location.reload()">Retry</button>
+        </div>`;
+    }
+    return;
+  }
+
+  const [catalogId, resourceId] = parts;
+
+  if (!resourceId) {
+    $el.innerHTML = `
+      <div class="breadcrumb"><a href="#/vega">Catalogs</a> / <strong>${esc(catalogId)}</strong></div>
+      <div class="loading-skeleton"><div class="skeleton skeleton-title"></div><div class="skeleton skeleton-list-item"></div><div class="skeleton skeleton-list-item"></div></div>`;
+    try {
+      const data = await vegaLoadResources(catalogId);
+      if (navGeneration !== myGen) return;
+      vegaRenderResourceList($el, catalogId, data);
+    } catch (e) {
+      if (navGeneration !== myGen) return;
+      $el.innerHTML = `
+        <div class="breadcrumb"><a href="#/vega">Catalogs</a> / <strong>${esc(catalogId)}</strong></div>
+        <div class="error-boundary">
+          <div class="error-icon">🔒</div>
+          <h3>Permission Denied or Failed to Load Resources</h3>
+          <p>${esc(String(e))}</p>
+          <button class="retry-btn" onclick="location.reload()">Retry</button>
+        </div>`;
+    }
+    return;
+  }
+
+  // Resource detail
+  await vegaRenderResourceDetail($el, catalogId, resourceId);
+}

package/dist/utils/http.d.ts

@@ -11,6 +11,9 @@ export declare class NetworkRequestError extends Error {
     readonly hint: string;
     constructor(method: string, url: string, causeMessage: string, hint: string);
 }
+/** fetch() with automatic retry on transient network errors (TLS, socket, DNS).
+ *  Only retries safe (idempotent) HTTP methods by default. */
+export declare function fetchWithRetry(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
 export declare function fetchTextOrThrow(input: RequestInfo | URL, init?: RequestInit): Promise<{
     response: Response;
     body: string;

package/dist/utils/http.js

@@ -45,10 +45,46 @@ function buildNetworkHint(causeMessage) {
     }
     return "Check whether the platform URL is correct and whether it exposes /oauth2/clients over HTTPS.";
 }
+function isTransientNetworkError(error) {
+    if (!(error instanceof Error))
+        return false;
+    const msg = ("cause" in error && error.cause instanceof Error
+        ? error.cause.message
+        : error.message).toLowerCase();
+    return (msg.includes("tls") ||
+        msg.includes("socket") ||
+        msg.includes("econnreset") ||
+        msg.includes("econnrefused") ||
+        msg.includes("certificate") ||
+        msg.includes("disconnect") ||
+        msg.includes("etimedout") ||
+        msg.includes("eai_again"));
+}
+const RETRY_DELAYS = [300, 800];
+const SAFE_RETRY_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
+/** fetch() with automatic retry on transient network errors (TLS, socket, DNS).
+ *  Only retries safe (idempotent) HTTP methods by default. */
+export async function fetchWithRetry(input, init) {
+    const method = (init?.method ?? "GET").toUpperCase();
+    const canRetry = SAFE_RETRY_METHODS.has(method);
+    let lastError;
+    for (let attempt = 0; attempt <= RETRY_DELAYS.length; attempt++) {
+        try {
+            return await fetch(input, init);
+        }
+        catch (error) {
+            lastError = error;
+            if (!canRetry || !isTransientNetworkError(error) || attempt === RETRY_DELAYS.length)
+                break;
+            await new Promise((r) => setTimeout(r, RETRY_DELAYS[attempt]));
+        }
+    }
+    throw lastError;
+}
 export async function fetchTextOrThrow(input, init) {
     let response;
     try {
-        response = await fetch(input, init);
+        response = await fetchWithRetry(input, init);
     }
     catch (error) {
         const url = typeof input === "string"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kweaver-ai/kweaver-sdk",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "KWeaver TypeScript SDK — CLI tool and programmatic API for knowledge networks and Decision Agents.",
   "type": "module",
   "main": "./dist/index.js",
@@ -24,12 +24,12 @@
   ],
   "scripts": {
     "dev": "tsx watch src/cli.ts",
-    "build": "tsc -p tsconfig.json",
+    "build": "tsc -p tsconfig.json && (cp -r src/templates dist/ 2>/dev/null || true)",
     "start": "node ./dist/cli.js",
     "lint": "tsc --noEmit -p tsconfig.json",
     "test": "node --import tsx --test test/*.test.ts",
-    "test:e2e": "node --import tsx test/e2e/ensure-token.ts && node --import tsx --test --test-concurrency=1 test/e2e/**/*.test.ts",
-    "test:e2e:strict": "node test/e2e/run-e2e-strict.mjs",
+    "test:e2e": "node --import tsx --test test/e2e/*.test.ts",
+    "test:e2e:live": "KWEAVER_BASE_URL=${KWEAVER_BASE_URL:-https://43.129.210.161} KWEAVER_NO_AUTH=1 KWEAVER_TLS_INSECURE=1 node --import tsx --test test/e2e/*.test.ts",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -51,6 +51,7 @@
   "devDependencies": {
     "@types/node": "^24.6.0",
     "@types/react": "^19.2.14",
+    "@types/yargs": "^17.0.35",
     "playwright": "^1.58.2",
     "tsx": "^4.20.5",
     "typescript": "^5.9.3"
@@ -67,12 +68,15 @@
     "@kweaver-ai/bkn": "^0.1.0",
     "@playwright/test": "^1.58.2",
     "chardet": "^2.1.1",
+    "columnify": "^1.6.0",
     "csv-parse": "^6.2.1",
     "iconv-lite": "^0.7.2",
     "ink": "^6.8.0",
     "ink-spinner": "^5.0.0",
     "ink-text-input": "^6.0.0",
     "marked": "^11.2.0",
-    "react": "^19.2.4"
+    "react": "^19.2.4",
+    "string-width": "^8.2.0",
+    "yargs": "^18.0.0"
   }
 }