@compilr-dev/sdk 0.10.11 → 0.10.12

package/dist/tools/interactive-flow-tool.js

@@ -38,6 +38,16 @@ const SUMMARY_RENDERERS = ['compact', 'detailed'];
  * slug doesn't map to a component.
  */
 const ICON_NAME_RE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+/* eslint-disable @typescript-eslint/no-unnecessary-condition, @typescript-eslint/no-unnecessary-type-conversion --
+ * The entire validator section runs DEFENSIVE runtime checks against agent
+ * JSON arriving over IPC. TypeScript types are lies at this boundary — an
+ * agent's malformed input can have any field missing or wrong-typed, and we
+ * must return structured errors rather than throw. The "always-falsy" and
+ * "redundant String()" warnings would be true if we only saw type-safe
+ * callers, but our caller is `JSON.parse(IPC payload)` cast to Flow. The
+ * pragmatic alternative (passing `unknown` through every helper signature)
+ * would be a much larger refactor for no behavioral gain.
+ */
 /**
  * Validate a flow. Accepts `unknown` because inputs flow in as JSON from the
  * agent and TS types are lies at the boundary — runtime defensive checks
@@ -75,10 +85,18 @@ export function validateFlow(flowInput) {
     // 2. Each node's id must match the key it lives under
     for (const id of nodeIds) {
         const node = flow.nodes[id];
+        if (!node || typeof node !== 'object') {
+            errors.push({
+                code: 'INVALID_NODE_TYPE',
+                message: `flow.nodes['${id}'] is null or not an object`,
+                nodeId: id,
+            });
+            continue;
+        }
         if (node.id !== id) {
             errors.push({
                 code: 'DUPLICATE_NODE_ID',
-                message: `Node key '${id}' does not match node.id '${node.id}'`,
+                message: `Node key '${id}' does not match node.id '${String(node.id)}'`,
                 nodeId: id,
             });
         }
@@ -86,6 +104,8 @@ export function validateFlow(flowInput) {
     // 3. Per-node validation: type, references, icons, renderers, conditions
     for (const id of nodeIds) {
         const node = flow.nodes[id];
+        if (!node || typeof node !== 'object')
+            continue; // already flagged above
         validateNode(node, flow.nodes, errors);
     }
     // 4. Reachability — warn on orphans
@@ -125,6 +145,16 @@ function validateNode(node, allNodes, errors) {
     }
 }
 function validateQuestion(node, allNodes, errors) {
+    // Defensive: agent JSON may omit required nested fields. Surface as
+    // structured errors rather than letting the validator throw.
+    if (!node.input || typeof node.input !== 'object') {
+        errors.push({
+            code: 'INVALID_NODE_TYPE',
+            message: `Question node '${node.id}' is missing the required 'input' object (must contain 'mode' and choices/options/etc.)`,
+            nodeId: node.id,
+        });
+        return;
+    }
     // Input mode must have a valid renderer if specified. The lookup CAN miss
     // at runtime if the agent passed an unknown mode in the JSON — TS narrowing
     // doesn't help us across the boundary, hence the explicit widened type.
@@ -132,7 +162,7 @@ function validateQuestion(node, allNodes, errors) {
     if (!validRenderers) {
         errors.push({
             code: 'INVALID_NODE_TYPE',
-            message: `Unknown question input mode '${node.input.mode}'`,
+            message: `Unknown question input mode '${String(node.input.mode)}' for node '${node.id}' (expected: single, multi, text, or proposal)`,
             nodeId: node.id,
         });
         return;
@@ -144,23 +174,67 @@ function validateQuestion(node, allNodes, errors) {
             nodeId: node.id,
         });
     }
-    // Validate icons on choices/proposals
+    // Validate choices/options arrays are present and well-formed
     if (node.input.mode === 'single' || node.input.mode === 'multi') {
-        for (const choice of node.input.choices) {
-            if (choice.icon !== undefined)
-                checkIcon(choice.icon, node.id, errors);
+        if (!Array.isArray(node.input.choices)) {
+            errors.push({
+                code: 'INVALID_NODE_TYPE',
+                message: `Question '${node.id}' with mode '${node.input.mode}' requires a 'choices' array`,
+                nodeId: node.id,
+            });
+        }
+        else {
+            for (const choice of node.input.choices) {
+                if (!choice || typeof choice !== 'object')
+                    continue;
+                if (choice.icon !== undefined)
+                    checkIcon(choice.icon, node.id, errors);
+            }
         }
     }
     else if (node.input.mode === 'proposal') {
-        for (const opt of node.input.options) {
-            if (opt.icon !== undefined)
-                checkIcon(opt.icon, node.id, errors);
+        if (!Array.isArray(node.input.options)) {
+            errors.push({
+                code: 'INVALID_NODE_TYPE',
+                message: `Question '${node.id}' with mode 'proposal' requires an 'options' array`,
+                nodeId: node.id,
+            });
+        }
+        else {
+            for (const opt of node.input.options) {
+                if (!opt || typeof opt !== 'object')
+                    continue;
+                if (opt.icon !== undefined)
+                    checkIcon(opt.icon, node.id, errors);
+            }
         }
     }
-    // Validate next references
+    // Validate next references (defensive — `next` might be undefined)
+    if (node.next === undefined || node.next === null) {
+        errors.push({
+            code: 'UNRESOLVED_NEXT',
+            message: `Question node '${node.id}' is missing the required 'next' field (string nodeId or { byAnswer: ... })`,
+            nodeId: node.id,
+        });
+        return;
+    }
     validateNextRef(node.next, node, allNodes, errors);
 }
 function validateInfo(node, allNodes, errors) {
+    if (typeof node.title !== 'string' || node.title.length === 0) {
+        errors.push({
+            code: 'INVALID_NODE_TYPE',
+            message: `Info node '${node.id}' is missing required 'title' string`,
+            nodeId: node.id,
+        });
+    }
+    if (typeof node.body !== 'string') {
+        errors.push({
+            code: 'INVALID_NODE_TYPE',
+            message: `Info node '${node.id}' is missing required 'body' string (markdown content)`,
+            nodeId: node.id,
+        });
+    }
     if (node.render && !INFO_RENDERERS.includes(node.render)) {
         errors.push({
             code: 'INVALID_RENDERER',
@@ -168,31 +242,56 @@ function validateInfo(node, allNodes, errors) {
             nodeId: node.id,
         });
     }
+    if (node.next === undefined || node.next === null) {
+        errors.push({
+            code: 'UNRESOLVED_NEXT',
+            message: `Info node '${node.id}' is missing the required 'next' field`,
+            nodeId: node.id,
+        });
+        return;
+    }
     validateNextRef(node.next, node, allNodes, errors);
 }
 function validateBranch(node, allNodes, errors) {
-    // All routes must reference existing nodes and use valid conditions
-    for (let i = 0; i < node.routes.length; i++) {
-        const route = node.routes[i];
-        if (!isValidCondition(route.when)) {
-            errors.push({
-                code: 'INVALID_CONDITION',
-                message: `Branch route ${String(i)} has an invalid condition shape`,
-                nodeId: node.id,
-            });
-        }
-        if (!(route.goto in allNodes)) {
-            errors.push({
-                code: 'UNRESOLVED_BRANCH',
-                message: `Branch route ${String(i)} goto '${route.goto}' is not defined in flow.nodes`,
-                nodeId: node.id,
-            });
+    // Defensive: routes might be missing or non-array
+    if (!Array.isArray(node.routes)) {
+        errors.push({
+            code: 'INVALID_NODE_TYPE',
+            message: `Branch node '${node.id}' requires a 'routes' array (each item: { when: ..., goto: nodeId })`,
+            nodeId: node.id,
+        });
+    }
+    else {
+        for (let i = 0; i < node.routes.length; i++) {
+            const route = node.routes[i];
+            if (!route || typeof route !== 'object') {
+                errors.push({
+                    code: 'INVALID_CONDITION',
+                    message: `Branch route ${String(i)} on node '${node.id}' is null or not an object`,
+                    nodeId: node.id,
+                });
+                continue;
+            }
+            if (!isValidCondition(route.when)) {
+                errors.push({
+                    code: 'INVALID_CONDITION',
+                    message: `Branch route ${String(i)} has an invalid condition shape`,
+                    nodeId: node.id,
+                });
+            }
+            if (typeof route.goto !== 'string' || !(route.goto in allNodes)) {
+                errors.push({
+                    code: 'UNRESOLVED_BRANCH',
+                    message: `Branch route ${String(i)} goto '${String(route.goto)}' is not defined in flow.nodes`,
+                    nodeId: node.id,
+                });
+            }
         }
     }
-    if (!node.default || !(node.default in allNodes)) {
+    if (!node.default || typeof node.default !== 'string' || !(node.default in allNodes)) {
         errors.push({
             code: 'UNRESOLVED_BRANCH',
-            message: `Branch default '${node.default}' is not defined in flow.nodes`,
+            message: `Branch default '${String(node.default)}' is not defined in flow.nodes`,
             nodeId: node.id,
         });
     }
@@ -218,12 +317,20 @@ function validateNextRef(next, node, allNodes, errors) {
         }
         return;
     }
-    // byAnswer object
+    // byAnswer object — defensive on shape
+    if (!next || typeof next !== 'object' || !next.byAnswer || typeof next.byAnswer !== 'object') {
+        errors.push({
+            code: 'UNRESOLVED_NEXT',
+            message: `Node '${node.id}' next is not a valid NextRef (expected string nodeId or { byAnswer: { ... } })`,
+            nodeId: node.id,
+        });
+        return;
+    }
     for (const [answer, target] of Object.entries(next.byAnswer)) {
-        if (!(target in allNodes)) {
+        if (typeof target !== 'string' || !(target in allNodes)) {
             errors.push({
                 code: 'UNRESOLVED_NEXT',
-                message: `Node '${node.id}' next.byAnswer['${answer}'] references '${target}' which is not defined in flow.nodes`,
+                message: `Node '${node.id}' next.byAnswer['${answer}'] references '${String(target)}' which is not defined in flow.nodes`,
                 nodeId: node.id,
             });
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/sdk",
-  "version": "0.10.11",
+  "version": "0.10.12",
   "description": "Universal agent runtime for building AI-powered applications",
   "type": "module",
   "main": "dist/index.js",