@meshxdata/fops 0.1.31 → 0.1.34

package/src/plugins/bundled/fops-plugin-foundation/lib/align.js

@@ -0,0 +1,183 @@
+/**
+ * Column alignment: maps source CSV column names to expected schema column names.
+ * Three-pass: exact → embedding (if model available) → Levenshtein ratio fallback.
+ */
+
+export function normalizeColName(s) {
+  return String(s || "")
+    .toLowerCase()
+    .replace(/\s+/g, "_")
+    .replace(/[^a-z0-9_]/g, "");
+}
+
+function cosineSimilarity(a, b) {
+  let dot = 0, na = 0, nb = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i];
+    na += a[i] * a[i];
+    nb += b[i] * b[i];
+  }
+  const denom = Math.sqrt(na) * Math.sqrt(nb);
+  return denom === 0 ? 0 : dot / denom;
+}
+
+export function levenshteinRatio(a, b) {
+  const x = String(a || "");
+  const y = String(b || "");
+  if (x === y) return 1;
+  const m = x.length, n = y.length;
+  if (m === 0 || n === 0) return 0;
+  const dp = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(0));
+  for (let i = 0; i <= m; i++) dp[i][0] = i;
+  for (let j = 0; j <= n; j++) dp[0][j] = j;
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      const cost = x[i - 1] === y[j - 1] ? 0 : 1;
+      dp[i][j] = Math.min(dp[i - 1][j] + 1, dp[i][j - 1] + 1, dp[i - 1][j - 1] + cost);
+    }
+  }
+  return 1 - dp[m][n] / Math.max(m, n);
+}
+
+/**
+ * Align source column names to expected column names using three passes.
+ *
+ * @param {string[]} sourceColumns
+ * @param {string[]} expectedColumns
+ * @param {{ embedTexts?: Function, threshold?: number }} opts
+ * @returns {Promise<{ mappings, unmappedSource, unmappedExpected, suggestedTransformation? }>}
+ */
+export async function alignColumns(sourceColumns, expectedColumns, { embedTexts, threshold = 0.7 } = {}) {
+  const mappings = [];
+  const unmappedSrc = new Set(sourceColumns);
+  const unmappedExp = new Set(expectedColumns);
+
+  // Pass 1 — Exact (normalized)
+  for (const src of sourceColumns) {
+    const normSrc = normalizeColName(src);
+    for (const exp of [...unmappedExp]) {
+      if (normalizeColName(exp) === normSrc) {
+        mappings.push({ sourceColumn: src, expectedColumn: exp, confidence: 1.0, method: "exact" });
+        unmappedSrc.delete(src);
+        unmappedExp.delete(exp);
+        break;
+      }
+    }
+  }
+
+  // Helpers shared by embedding and Levenshtein passes
+  // Expand common opaque abbreviations so the embedding sees real words
+  const ABBREV = {
+    ccy: "currency code", cust: "customer", amt: "amount", qty: "quantity",
+    dt: "date", desc: "description", num: "number", addr: "address",
+    prod: "product", yr: "year", mo: "month", cnt: "count",
+    avg: "average", pct: "percent", dept: "department",
+  };
+  // Suffixes that strongly constrain a column's semantic role
+  const SEMANTIC_SUFFIXES = new Set([
+    "id", "date", "status", "name", "type", "code", "key",
+    "region", "currency", "amount", "count", "number",
+  ]);
+  const toHuman = (s) => {
+    const parts = normalizeColName(s).split("_").filter(Boolean);
+    return parts.map((p) => ABBREV[p] || p).join(" ");
+  };
+  const getSuffix = (s) => {
+    const parts = normalizeColName(s).split("_").filter(Boolean);
+    const last = parts[parts.length - 1];
+    return SEMANTIC_SUFFIXES.has(last) ? last : null;
+  };
+  // Adjust a raw similarity score by structural compatibility:
+  //   containment:    source name IS the last token of expected → +0.30 (e.g. "id" → "order_id")
+  //   same suffix:    both end with same known suffix → +0.10 (confirms alignment)
+  //   suffix mismatch: both have different known suffixes → -0.15 (strong signal of mismatch)
+  const adjustScore = (raw, src, exp) => {
+    let score = raw;
+    const ss = getSuffix(src), es = getSuffix(exp);
+    if (ss && es) score = ss === es ? Math.min(1, score + 0.1) : Math.max(0, score - 0.15);
+    // Containment: "id" IS the last token of "order_id" → strong structural match
+    const normSrc = normalizeColName(src);
+    const expParts = normalizeColName(exp).split("_").filter(Boolean);
+    if (expParts.length > 1 && expParts[expParts.length - 1] === normSrc) {
+      score = Math.min(1, score + 0.3);
+    }
+    return score;
+  };
+
+  // Pass 2 — Embedding (if embedTexts provided)
+  if (typeof embedTexts === "function" && unmappedSrc.size > 0 && unmappedExp.size > 0) {
+    try {
+      const srcList = [...unmappedSrc];
+      const expList = [...unmappedExp];
+      const srcTexts = srcList.map(toHuman);
+      const expTexts = expList.map(toHuman);
+
+      const allVecs = await embedTexts([...srcTexts, ...expTexts]);
+      if (allVecs && allVecs.length === srcTexts.length + expTexts.length) {
+        const srcVecs = allVecs.slice(0, srcTexts.length);
+        const expVecs = allVecs.slice(srcTexts.length);
+
+        // Build score matrix and collect all pairs above threshold
+        const candidates = [];
+        for (let i = 0; i < srcList.length; i++) {
+          for (let j = 0; j < expList.length; j++) {
+            const score = adjustScore(cosineSimilarity(srcVecs[i], expVecs[j]), srcList[i], expList[j]);
+            if (score >= threshold) candidates.push({ i, j, score });
+          }
+        }
+        // Greedy assign highest-confidence pairs first
+        candidates.sort((a, b) => b.score - a.score);
+        const usedSrc = new Set(), usedExp = new Set();
+        for (const { i, j, score } of candidates) {
+          if (usedSrc.has(i) || usedExp.has(j)) continue;
+          usedSrc.add(i);
+          usedExp.add(j);
+          mappings.push({ sourceColumn: srcList[i], expectedColumn: expList[j], confidence: score, method: "embedding" });
+          unmappedSrc.delete(srcList[i]);
+          unmappedExp.delete(expList[j]);
+        }
+      }
+    } catch { /* model not ready — fall through to pass 3 */ }
+  }
+
+  // Pass 3 — Levenshtein ratio fallback
+  if (unmappedSrc.size > 0 && unmappedExp.size > 0) {
+    const srcList = [...unmappedSrc];
+    const expList = [...unmappedExp];
+    const candidates = [];
+    for (const src of srcList) {
+      for (const exp of expList) {
+        const score = adjustScore(levenshteinRatio(normalizeColName(src), normalizeColName(exp)), src, exp);
+        if (score >= threshold) candidates.push({ src, exp, score });
+      }
+    }
+    candidates.sort((a, b) => b.score - a.score);
+    const usedSrc = new Set(), usedExp = new Set();
+    for (const { src, exp, score } of candidates) {
+      if (usedSrc.has(src) || usedExp.has(exp)) continue;
+      usedSrc.add(src);
+      usedExp.add(exp);
+      mappings.push({ sourceColumn: src, expectedColumn: exp, confidence: score, method: "levenshtein" });
+      unmappedSrc.delete(src);
+      unmappedExp.delete(exp);
+    }
+  }
+
+  const result = {
+    mappings,
+    unmappedSource: [...unmappedSrc],
+    unmappedExpected: [...unmappedExp],
+  };
+
+  if (mappings.length > 0) {
+    const renameMapping = {};
+    for (const { sourceColumn, expectedColumn } of mappings) {
+      if (sourceColumn !== expectedColumn) renameMapping[sourceColumn] = expectedColumn;
+    }
+    if (Object.keys(renameMapping).length > 0) {
+      result.suggestedTransformation = { transform: "rename_column", mapping: renameMapping };
+    }
+  }
+
+  return result;
+}

package/src/plugins/bundled/fops-plugin-foundation/lib/apply.js

@@ -324,8 +324,9 @@ export function parseYamlContent(content) {
       throw err;
     }
   }
-  if (!parsed || !parsed.mesh) {
-    throw new Error("No mesh block found in YAML content");
+  const hasRootEntities = ENTITY_ORDER.slice(1).some((t) => parsed?.[t]);
+  if (!parsed || (!parsed.mesh && !hasRootEntities)) {
+    throw new Error("No mesh block or entity blocks found in YAML content");
   }
   return { operations: parseYamlOperations(parsed), fileName: "inline.yaml" };
 }
@@ -348,8 +349,9 @@ export function parseYamlLandscape(filePath) {
     }
   }
 
-  if (!parsed || !parsed.mesh) {
-    throw new Error("No mesh block found in YAML file");
+  const hasRootEntities = ENTITY_ORDER.slice(1).some((t) => parsed?.[t]);
+  if (!parsed || (!parsed.mesh && !hasRootEntities)) {
+    throw new Error("No mesh block or entity blocks found in YAML file");
   }
 
   return { operations: parseYamlOperations(parsed), fileName: path.basename(filePath) };
@@ -377,6 +379,43 @@ function parseYamlOperations(parsed) {
     ENTITY_ORDER.slice(1).map((type) => [type, parsed[type]]),
   );
 
+  function parseEntityBlock(entityType, entityName, eBlock, meshName) {
+    const props = {};
+    const refs = {};
+    const op = { type: entityType, name: entityName, props, mesh: meshName || null };
+
+    for (const [k, v] of Object.entries(eBlock)) {
+      if (k === "connection" && typeof v === "object" && !Array.isArray(v)) {
+        op.connection = v;
+      } else if (k === "config" && typeof v === "object" && !Array.isArray(v)) {
+        op.config = v;
+      } else if (k === "template") {
+        op.template = v;
+      } else if (k === "select_columns") {
+        op.selectColumns = v;
+      } else if (k === "cast_changes") {
+        op.castChanges = Array.isArray(v) ? v : [v];
+      } else if (k === "schema" && Array.isArray(v)) {
+        op.schema = v;
+      } else if (k === "pipeline" && typeof v === "object" && !Array.isArray(v)) {
+        op.pipeline = parseYamlPipeline(v);
+      } else if (k === "secret" && typeof v === "object" && !Array.isArray(v)) {
+        op.secret = v;
+      } else if (REF_TO_TYPE[k]) {
+        const ref = parseYamlRef(v);
+        if (ref) refs[k] = ref;
+      } else if (!SPECIAL_KEYS.has(k)) {
+        props[k] = v;
+      }
+    }
+
+    if (refs.system) op.parent = refs.system;
+    else if (refs.source) op.parent = refs.source;
+    else if (refs.object) op.parent = refs.object;
+
+    return op;
+  }
+
   for (const [meshName, meshBlock] of meshEntries) {
     if (!meshBlock || typeof meshBlock !== "object" || Array.isArray(meshBlock)) continue;
     const meshProps = {};
@@ -397,40 +436,19 @@ function parseYamlOperations(parsed) {
 
       for (const [entityName, eBlock] of Object.entries(group)) {
         if (!eBlock || typeof eBlock !== "object" || Array.isArray(eBlock)) continue;
-        const props = {};
-        const refs = {};
-        const op = { type: entityType, name: entityName, props, mesh: meshName };
-
-        for (const [k, v] of Object.entries(eBlock)) {
-          if (k === "connection" && typeof v === "object" && !Array.isArray(v)) {
-            op.connection = v;
-          } else if (k === "config" && typeof v === "object" && !Array.isArray(v)) {
-            op.config = v;
-          } else if (k === "template") {
-            op.template = v;
-          } else if (k === "select_columns") {
-            op.selectColumns = v;
-          } else if (k === "cast_changes") {
-            op.castChanges = Array.isArray(v) ? v : [v];
-          } else if (k === "schema" && Array.isArray(v)) {
-            op.schema = v;
-          } else if (k === "pipeline" && typeof v === "object" && !Array.isArray(v)) {
-            op.pipeline = parseYamlPipeline(v);
-          } else if (k === "secret" && typeof v === "object" && !Array.isArray(v)) {
-            op.secret = v;
-          } else if (REF_TO_TYPE[k]) {
-            const ref = parseYamlRef(v);
-            if (ref) refs[k] = ref;
-          } else if (!SPECIAL_KEYS.has(k)) {
-            props[k] = v;
-          }
-        }
-
-        if (refs.system) op.parent = refs.system;
-        else if (refs.source) op.parent = refs.source;
-        else if (refs.object) op.parent = refs.object;
+        operations.push(parseEntityBlock(entityType, entityName, eBlock, meshName));
+      }
+    }
+  }
 
-        operations.push(op);
+  // Handle root-level entity blocks with no mesh context (e.g. UUID-keyed updates)
+  if (meshEntries.length === 0) {
+    for (const entityType of ENTITY_ORDER.slice(1)) {
+      const group = rootEntityGroups[entityType];
+      if (!group || typeof group !== "object") continue;
+      for (const [entityName, eBlock] of Object.entries(group)) {
+        if (!eBlock || typeof eBlock !== "object" || Array.isArray(eBlock)) continue;
+        operations.push(parseEntityBlock(entityType, entityName, eBlock, null));
       }
     }
   }
@@ -591,12 +609,21 @@ async function deleteEntity(client, type, identifier) {
 /**
  * Search for an existing entity by type and name. Returns its identifier or null.
  */
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
 async function findEntity(client, type, name) {
+  // If name is a UUID, look up directly by identifier
+  if (UUID_RE.test(name)) {
+    try {
+      const res = await client.get(`/data/${type}/${name}`);
+      if (res?.identifier) return res.identifier;
+    } catch { /* fall through */ }
+  }
   try {
     // Use type-specific list endpoint for reliable lookup
     const res = await client.get(`/data/${type}/list?per_page=100`);
     const entities = parseListResponse(res);
-    const match = entities.find((e) => e.name === name);
+    const match = entities.find((e) => e.name === name || (UUID_RE.test(name) && e.identifier === name));
     if (match) return match.identifier;
   } catch { /* fall through */ }
   try {
@@ -891,7 +918,8 @@ async function runSubActions(client, op, uuid, refs) {
  */
 async function applyPipelineOp(client, op, uuid, refs) {
   const pipelineInputs = op.pipeline.inputs.map((inp) => {
-    const inputUuid = refs[inp.ref];
+    // Allow raw UUIDs as refs (e.g. from FCL patch) — no lookup needed
+    const inputUuid = refs[inp.ref] ?? (UUID_RE.test(inp.ref) ? inp.ref : null);
     if (!inputUuid) throw new Error(`unresolved pipeline input ref: ${inp.ref}`);
     return { input_type: inp.type, identifier: inputUuid };
   });
@@ -899,7 +927,7 @@ async function applyPipelineOp(client, op, uuid, refs) {
   // Build refToKey map for resolving transform "other" refs
   const refToKey = {};
   for (const inp of op.pipeline.inputs) {
-    const inputUuid = refs[inp.ref];
+    const inputUuid = refs[inp.ref] ?? (UUID_RE.test(inp.ref) ? inp.ref : null);
     if (inputUuid) refToKey[inp.ref] = `input_${inputUuid.replace(/-/g, "_")}`;
   }
 
@@ -931,6 +959,18 @@ async function applyPipelineOp(client, op, uuid, refs) {
     if (cols && cols.length > 0) slotCols[slot] = cols;
   }
   if (Object.keys(slotCols).length > 0) {
+    // Prune rename_column steps: remove entries whose source column doesn't exist
+    // in any slot (data is already named correctly — mapping was generated from a
+    // raw file whose column names differ from the ingested data object schema).
+    const allSlotCols = new Set(Object.values(slotCols).flat());
+    builderBody.transformations = (builderBody.transformations || []).flatMap((t) => {
+      if (t.transform !== "rename_column") return [t];
+      const changes = Object.fromEntries(
+        Object.entries(t.changes || {}).filter(([from]) => allSlotCols.has(from))
+      );
+      if (Object.keys(changes).length === 0) return []; // step is a no-op — drop it
+      return [{ ...t, changes }];
+    });
     const flowErr = validateTransformColumnFlow(slotCols, builderBody.transformations || []);
     if (flowErr) throw new Error(flowErr);
   }
@@ -998,7 +1038,9 @@ export async function applyLandscape(client, operations, opts = {}) {
     const existing = await findEntity(client, op.type, op.name);
     if (existing) {
       let recreateFallThrough = false;
-      if (recreateBroken && (op.type === "data_product" || op.type === "data_object" || op.type === "data_source")) {
+      // When op.name is a UUID, we're targeting an existing entity by identifier — never delete/recreate.
+      const opNameIsUuid = UUID_RE.test(op.name);
+      if (!opNameIsUuid && recreateBroken && (op.type === "data_product" || op.type === "data_object" || op.type === "data_source")) {
         const broken = await isEntityBroken(client, op.type, existing, op);
         if (broken) {
           const deleted = await deleteEntity(client, op.type, existing);

package/src/plugins/bundled/fops-plugin-foundation/lib/client.js

@@ -5,6 +5,8 @@ import path from "node:path";
 
 const DEFAULT_BASE_URL = "http://127.0.0.1:9001/api";
 const TOKEN_TTL_MS = 30 * 60 * 1000; // 30 minutes
+const RETRY_COUNT = 3;
+const RETRY_DELAY_MS = 10_000;
 
 /** Resolve API base URL: config.apiUrl, FOUNDATION_API_URL, or default. Ensures path ends with /api. */
 function resolveBaseUrl(config) {
@@ -18,6 +20,18 @@ function resolveBaseUrl(config) {
   return url.endsWith("/api") ? url : `${url}/api`;
 }
 
+/** Resolve x-org header value: config.orgId, ORG_ID env, ORG_NAME env, root .env, or "root". */
+function resolveOrgId(config, rootEnv = {}) {
+  return (
+    config?.orgId?.trim() ||
+    process.env.ORG_ID?.trim() ||
+    rootEnv.ORG_ID?.trim() ||
+    process.env.ORG_NAME?.trim() ||
+    rootEnv.ORG_NAME?.trim() ||
+    "root"
+  );
+}
+
 function isValidJwt(token) {
   if (!token) return false;
   const parts = token.split(".");
@@ -47,7 +61,6 @@ function request(method, url, headers = {}, body, timeoutMs = 15_000) {
       method,
       headers: {
         "Content-Type": "application/json",
-        "x-org": "root",
         ...headers,
       },
       timeout: timeoutMs,
@@ -73,6 +86,28 @@ function request(method, url, headers = {}, body, timeoutMs = 15_000) {
   });
 }
 
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/** Like request() but retries on network errors and 5xx responses. */
+async function requestWithRetries(method, url, headers, body, timeoutMs, maxRetries = RETRY_COUNT, delayMs = RETRY_DELAY_MS) {
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    let res;
+    try {
+      res = await request(method, url, headers, body, timeoutMs);
+    } catch (e) {
+      if (attempt < maxRetries) { await sleep(delayMs); continue; }
+      throw new Error(`Request failed after ${maxRetries} attempts: ${e.message}`);
+    }
+    if (res.status >= 500 && attempt < maxRetries) {
+      await sleep(delayMs);
+      continue;
+    }
+    return res;
+  }
+}
+
 /**
  * Like request() but returns response headers, does NOT follow redirects,
  * and supports both JSON and url-encoded bodies.
@@ -251,6 +286,7 @@ export class FoundationClient {
   constructor(config = {}, opts = {}) {
     this._config = { ...config };
     this._baseUrl = resolveBaseUrl(config);
+    this._org = resolveOrgId(config, loadRootProjectEnv());
     this._getCredentials = opts.getCredentials || null;
     this._token = null;
     this._tokenExpiry = 0;
@@ -501,7 +537,7 @@ export class FoundationClient {
    */
   async _request(method, apiPath, body) {
     const url = apiPath.startsWith("http") ? apiPath : `${this._baseUrl}${apiPath}`;
-    const headers = {};
+    const headers = { "x-org": this._org };
 
     await this.ensureAuth();
     headers.Authorization = `Bearer ${this._token}`;
@@ -526,7 +562,7 @@ export class FoundationClient {
       headers["CF-Access-Client-Secret"] = cfSecret;
     }
 
-    let res = await request(method, url, headers, body, this._timeoutMs);
+    let res = await requestWithRetries(method, url, headers, body, this._timeoutMs);
 
     if (res.status === 401) {
       this._token = null;
@@ -537,7 +573,7 @@ export class FoundationClient {
       headers.Authorization = `Bearer ${this._token}`;
       if (this._cfJwt) headers.Cookie = `CF_Authorization=${this._cfJwt}`;
       else delete headers.Cookie;
-      res = await request(method, url, headers, body, this._timeoutMs);
+      res = await requestWithRetries(method, url, headers, body, this._timeoutMs);
     }
 
     if (res.status >= 400) {

package/src/plugins/bundled/fops-plugin-foundation/lib/stack-apply.js

@@ -70,10 +70,13 @@ export function parseStackFile(filePath) {
   const parsed = yaml.load(content);
   if (!parsed) return { stack: null, hasStack: false, hasMesh: false };
 
+  const ENTITY_TYPES = ["data_system", "data_source", "data_object", "data_product", "application"];
+  const hasMesh = !!parsed.mesh || ENTITY_TYPES.some((t) => !!parsed[t]);
+
   return {
     stack: parsed.stack ? parseStackBlock(parsed.stack) : null,
     hasStack: !!parsed.stack,
-    hasMesh: !!parsed.mesh,
+    hasMesh,
   };
 }
 

package/src/plugins/bundled/fops-plugin-foundation/lib/tools-write.js

@@ -2440,6 +2440,52 @@ export function registerWriteTools(api, client) {
         return `Unknown scope: ${raw.scope}`;
       },
     },
+    // foundation_align
+    {
+      name: "foundation_align",
+      description: "Align source CSV column names to expected schema column names using exact, embedding, and Levenshtein matching. Returns mappings and a ready-to-use rename_column transformation.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          source_columns: { type: "array", items: { type: "string" }, description: "Raw source column names (e.g. from a CSV header)" },
+          expected_columns: { type: "array", items: { type: "string" }, description: "Target schema column names (e.g. from a data product schema)" },
+          source_identifier: { type: "string", description: "Entity identifier to fetch source columns from (data_object or data_product)" },
+          target_identifier: { type: "string", description: "Entity identifier to fetch expected columns from (data_object or data_product)" },
+          threshold: { type: "number", description: "Minimum similarity score 0–1 (default 0.7)" },
+        },
+      },
+      async execute(input) {
+        const { alignColumns } = await import("./align.js");
+        let sourceCols = input.source_columns;
+        let expectedCols = input.expected_columns;
+
+        if (!sourceCols && input.source_identifier) {
+          const cols = await fetchEntityColumns(client, input.source_identifier, "data_object");
+          if (!cols) return `Error: could not fetch columns for source identifier "${input.source_identifier}"`;
+          sourceCols = cols;
+        }
+        if (!expectedCols && input.target_identifier) {
+          const cols = await fetchEntityColumns(client, input.target_identifier, "data_product");
+          if (!cols) return `Error: could not fetch columns for target identifier "${input.target_identifier}"`;
+          expectedCols = cols;
+        }
+
+        if (!sourceCols || sourceCols.length === 0) return "Error: source_columns or source_identifier required";
+        if (!expectedCols || expectedCols.length === 0) return "Error: expected_columns or target_identifier required";
+
+        let embedTexts;
+        try {
+          const embSvc = typeof api.getService === "function" && api.getService("embeddings:search");
+          if (embSvc?.embedTexts) embedTexts = embSvc.embedTexts.bind(embSvc);
+        } catch { /* embeddings not available */ }
+
+        const result = await alignColumns(sourceCols, expectedCols, {
+          embedTexts,
+          threshold: typeof input.threshold === "number" ? input.threshold : 0.7,
+        });
+        return fmt(result);
+      },
+    },
   ];
 
   return tools;

package/src/plugins/bundled/fops-plugin-foundation-graphql/index.js

@@ -81,7 +81,7 @@ export function register(api) {
     },
   });
 
-  // ─── CLI Command: fops foundation query ──────────────────────────────────
+  // ─── CLI Commands: fops foundation graphql / query ───────────────────────
   api.registerCommand((program) => {
     // Find or create the 'foundation' parent command
     let foundation = program.commands.find((c) => c.name() === "foundation");
@@ -89,6 +89,44 @@ export function register(api) {
       foundation = program.command("foundation").description("Foundation platform operations");
     }
 
+    foundation
+      .command("graphql")
+      .description("Start a local GraphiQL explorer for the Foundation GraphQL API")
+      .option("--port <port>", "Port to listen on (default: random)", "0")
+      .action(async (opts) => {
+        try {
+          const facade = await getFacade();
+          const { createGraphQLRoute } = await import("./lib/graphql/hono-route.js");
+          const { serve } = await import("@hono/node-server");
+          const { exec } = await import("node:child_process");
+
+          const route = createGraphQLRoute(facade);
+          const port = parseInt(opts.port, 10) || 0;
+
+          const server = serve({ fetch: route.fetch, port }, (info) => {
+            const url = `http://127.0.0.1:${info.port}`;
+            console.log(chalk.cyan(`\n  ── Foundation GraphQL Explorer ${"─".repeat(18)}`));
+            console.log(`  ${chalk.green("✓")} Listening on ${chalk.bold(url)}`);
+            console.log(chalk.dim("  Press Ctrl+C to stop\n"));
+
+            // Open browser with platform-specific command
+            const opener =
+              process.platform === "darwin" ? "open" :
+              process.platform === "win32" ? "start" : "xdg-open";
+            exec(`${opener} ${url}`);
+          });
+
+          // Keep alive until Ctrl+C
+          await new Promise((resolve) => {
+            process.on("SIGINT", () => { server.close(); resolve(); });
+            process.on("SIGTERM", () => { server.close(); resolve(); });
+          });
+        } catch (err) {
+          console.error(chalk.red(`  ${err.message}`));
+          process.exitCode = 1;
+        }
+      });
+
     foundation
       .command("query <graphql>")
       .description("Execute an ad-hoc GraphQL query against the Foundation API")

package/src/plugins/bundled/fops-plugin-foundation-graphql/lib/graphql/resolvers/data-object.js

@@ -28,12 +28,15 @@ export const dataObjectResolvers = {
         // Normalize: the API may return { fields: [...] } or { schema: { fields: [...] } }
         const fields = res?.fields || res?.schema?.fields || [];
         return {
-          fields: fields.map((f) => ({
-            name: f.name || f.column_name,
-            dataType: f.data_type || f.dataType || f.type,
-            primary: f.primary ?? f.is_primary ?? false,
-            nullable: f.nullable ?? f.is_nullable ?? true,
-          })),
+          fields: fields.map((f) => {
+            const raw = f.data_type || f.dataType || f.type;
+            return {
+              name: f.name || f.column_name,
+              dataType: raw && typeof raw === "object" ? raw.column_type ?? null : raw ?? null,
+              primary: f.primary ?? f.is_primary ?? false,
+              nullable: f.nullable ?? f.is_nullable ?? true,
+            };
+          }),
         };
       } catch { return null; }
     },

package/src/plugins/bundled/fops-plugin-foundation-graphql/lib/graphql/resolvers/data-product.js

@@ -29,12 +29,15 @@ export const dataProductResolvers = {
         const res = await loaders.dataProductSchema.load(id);
         if (res instanceof Error) return null;
         const details = res?.details || res?.schema || res;
-        const columns = (res?.columns || res?.fields || []).map((f) => ({
-          name: f.name || f.column_name,
-          dataType: f.data_type || f.dataType || f.type,
-          primary: f.primary ?? f.is_primary ?? false,
-          nullable: f.nullable ?? f.is_nullable ?? true,
-        }));
+        const columns = (res?.columns || res?.fields || []).map((f) => {
+          const raw = f.data_type || f.dataType || f.type;
+          return {
+            name: f.name || f.column_name,
+            dataType: raw && typeof raw === "object" ? raw.column_type ?? null : raw ?? null,
+            primary: f.primary ?? f.is_primary ?? false,
+            nullable: f.nullable ?? f.is_nullable ?? true,
+          };
+        });
         return { details, columns };
       } catch { return null; }
     },