octwin-cli 0.6.0 → 0.7.0

package/dist/lib/net-hint.js

@@ -0,0 +1,57 @@
+/**
+ * Turn "the platform is unreachable" into a hint the author can act on.
+ *
+ * ## Why this exists
+ *
+ * `fetch('http://localhost:3000')` can be refused while the platform is running
+ * and answering. The server binds IPv4-only (`host: '0.0.0.0'` in `src/server.ts`),
+ * Node resolves `localhost` to `::1` first, and whether the connection then falls
+ * back to `127.0.0.1` is decided by Node's `autoSelectFamily`, NOT by our code.
+ *
+ * Measured on node v24.12.0, fetching an IPv4-only bind over `localhost`:
+ *
+ *   autoSelectFamily=true  (the default here) -> 200
+ *   autoSelectFamily=false                    -> fetch failed / ECONNREFUSED
+ *
+ * So on a runtime where that default is off — or with
+ * `--no-network-family-autoselection` / that flag in `NODE_OPTIONS` — every command
+ * reports the platform as down while `--url http://127.0.0.1:3000` and `curl` both
+ * work. That reading is what costs the time: a pack author's first act is to run the
+ * platform locally, and "unreachable" sends them to look at the server.
+ *
+ * This module only explains; it changes no addresses. Rewriting the host inside
+ * `readTarget` would also change the key saved credentials are stored under, and
+ * moving the server to `host: '::'` can fail to bind where IPv6 is disabled — so
+ * neither belongs in a diagnostic path.
+ */
+/** A `localhost` HTTP(S) origin — the only case where the IPv4/IPv6 split applies. */
+function isLocalhostUrl(url) {
+    try {
+        return new URL(url).hostname.toLowerCase() === 'localhost';
+    }
+    catch {
+        return false; // not a URL we can reason about; no hint to give
+    }
+}
+/** Did the connection get refused, as opposed to timing out / DNS / TLS? */
+function isConnectionRefused(err) {
+    const seen = new Set();
+    for (let e = err; e && !seen.has(e); e = e.cause) {
+        seen.add(e);
+        if (e.code === 'ECONNREFUSED' || e.code === 'ECONNRESET')
+            return true;
+    }
+    return false;
+}
+/**
+ * The extra sentence to append when a failure looks like the IPv6-`localhost`
+ * trap, or `null` when it does not — a hint printed on unrelated failures (a
+ * genuinely stopped server, a wrong port) is worse than none, because it sends
+ * the author to fix an address that was never the problem.
+ */
+export function localhostFamilyHint(url, err) {
+    if (!isLocalhostUrl(url) || !isConnectionRefused(err))
+        return null;
+    const ipv4 = url.replace(/(^https?:\/\/)localhost\b/i, '$1127.0.0.1');
+    return `if the platform IS running, this is the IPv6 'localhost' trap — Node tried ::1 and the server binds IPv4 only. Retry with --url ${ipv4}`;
+}

package/dist/lib/render-check.js

@@ -30,9 +30,10 @@ import { lookupKbSubdir, isEntryFile } from './kb-path.js';
  * "checked, nothing wrong" from "could not check". See `kb-path.ts`.
  */
 export function loadAllowedRenderKeys(packDir) {
+    const nested = new Map();
     const lookup = lookupKbSubdir(packDir, 'render-intents', dir => readdirSync(dir).some(isEntryFile));
     if (lookup.state !== 'ok')
-        return { lookup, keys: null };
+        return { lookup, keys: null, nested };
     const dir = lookup.dir;
     const out = new Map();
     try {
@@ -42,16 +43,20 @@ export function loadAllowedRenderKeys(packDir) {
             const entry = JSON.parse(readFileSync(join(dir, file), 'utf8'));
             if (entry.render_intent && Array.isArray(entry.allowed_keys)) {
                 out.set(entry.render_intent, entry.allowed_keys);
+                // Optional: a KB pulled before 2026-08-09 has no nested sets, and the nested check simply
+                // does not run for that intent. Absent is skipped, never treated as "nothing is allowed".
+                if (entry.nested_allowed_keys)
+                    nested.set(entry.render_intent, entry.nested_allowed_keys);
             }
         }
     }
     catch (err) {
-        return { lookup: { state: 'malformed', dir, reason: String(err?.message ?? err) }, keys: null };
+        return { lookup: { state: 'malformed', dir, reason: String(err?.message ?? err) }, keys: null, nested };
     }
     if (out.size === 0) {
-        return { lookup: { state: 'malformed', dir, reason: 'no render-intent entries parsed' }, keys: null };
+        return { lookup: { state: 'malformed', dir, reason: 'no render-intent entries parsed' }, keys: null, nested };
     }
-    return { lookup, keys: out };
+    return { lookup, keys: out, nested };
 }
 /**
  * Walk parsed YAML for objects carrying `render_intent` and report keys outside
@@ -59,8 +64,32 @@ export function loadAllowedRenderKeys(packDir) {
  * nodes: intents nest (an `auto_collection` carries `empty`/`single`/`multi`
  * sub-intents), and a stray key is just as invisible there.
  */
-export function findRenderKeyViolations(doc, file, allowedByIntent) {
+export function findRenderKeyViolations(doc, file, allowedByIntent, nestedByIntent = new Map()) {
     const findings = [];
+    /**
+     * Descend a declared nested path, mirroring the platform's `checkNested`.
+     *
+     * Descends only where the KB DECLARES a shape, and skips non-objects — so an expression string
+     * (`item_template: '$tpl'`) and an undeclared bag (`items:`, pack-supplied records) are both left
+     * alone, exactly as at load time.
+     */
+    const walkNested = (value, intent, at, sets, path) => {
+        if (Array.isArray(value)) {
+            value.forEach((v, i) => walkNested(v, intent, `${at}[]`, sets, [...path, i]));
+            return;
+        }
+        if (!value || typeof value !== 'object')
+            return;
+        const obj = value;
+        const allowed = sets[at];
+        if (allowed) {
+            const bad = Object.keys(obj).filter(k => !allowed.includes(k));
+            if (bad.length)
+                findings.push({ file, path: [...path], intent, keys: bad, allowed, nestedAt: at });
+        }
+        for (const [k, v] of Object.entries(obj))
+            walkNested(v, intent, `${at}.${k}`, sets, [...path, k]);
+    };
     const walk = (node, path) => {
         if (Array.isArray(node)) {
             node.forEach((v, i) => walk(v, [...path, i]));
@@ -78,6 +107,14 @@ export function findRenderKeyViolations(doc, file, allowedByIntent) {
                 const bad = Object.keys(obj).filter(k => !allowed.includes(k));
                 if (bad.length)
                     findings.push({ file, path: [...path], intent: obj.render_intent, keys: bad, allowed });
+                const sets = nestedByIntent.get(obj.render_intent);
+                if (sets) {
+                    for (const [k, v] of Object.entries(obj)) {
+                        if (k === 'render_intent' || !allowed.includes(k))
+                            continue;
+                        walkNested(v, obj.render_intent, k, sets, [...path, k]);
+                    }
+                }
             }
         }
         for (const [k, v] of Object.entries(obj))
@@ -93,6 +130,7 @@ export function describeRenderFinding(f) {
         return `${f.file}${at}: unknown render_intent '${f.intent}' — known intents: ${f.allowed.join(', ')}`;
     }
     const plural = f.keys.length === 1 ? 'field' : 'fields';
-    return `${f.file}${at}: render_intent '${f.intent}' has unknown ${plural} ${f.keys.map(k => `'${k}'`).join(', ')} ` +
+    const where = f.nestedAt ? `'${f.intent}' at '${f.nestedAt}'` : `'${f.intent}'`;
+    return `${f.file}${at}: render_intent ${where} has unknown ${plural} ${f.keys.map(k => `'${k}'`).join(', ')} ` +
         `— silently dropped at render. Allowed: ${f.allowed.join(', ')}`;
 }

package/package.json

@@ -1,37 +1,37 @@
-{
-  "name": "octwin-cli",
-  "version": "0.6.0",
-  "description": "Octwin external-pack developer CLI (by CEQUENS) — scaffold, validate, deploy, and check pure-YAML packs on your tenant.",
-  "type": "module",
-  "bin": {
-    "octwin": "dist/index.js"
-  },
-  "files": [
-    "dist",
-    "templates",
-    "README.md",
-    "CHANGELOG.md",
-    "LICENSE"
-  ],
-  "engines": {
-    "node": ">=20"
-  },
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "prepublishOnly": "npm run build"
-  },
-  "dependencies": {
-    "yaml": "^2.6.0"
-  },
-  "devDependencies": {
-    "@types/node": "^22.0.0",
-    "typescript": "^5.7.0"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "keywords": ["octwin", "cequens", "cli", "whatsapp", "chatbot", "pack", "conversational-ai", "yaml"],
-  "author": "CEQUENS",
-  "homepage": "https://www.npmjs.com/package/octwin-cli",
-  "license": "MIT"
-}
+{
+  "name": "octwin-cli",
+  "version": "0.7.0",
+  "description": "Octwin external-pack developer CLI (by CEQUENS) — scaffold, validate, deploy, and check pure-YAML packs on your tenant.",
+  "type": "module",
+  "bin": {
+    "octwin": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "yaml": "^2.6.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": ["octwin", "cequens", "cli", "whatsapp", "chatbot", "pack", "conversational-ai", "yaml"],
+  "author": "CEQUENS",
+  "homepage": "https://www.npmjs.com/package/octwin-cli",
+  "license": "MIT"
+}

package/templates/starter/manifest.yaml

@@ -14,6 +14,16 @@ description: 'A hello bot — edit this to build your pack.'
 supported_channels: [whatsapp, web]
 required_adapters:  [messaging]
 
+# What to do with a VOICE NOTE. WhatsApp cannot stop customers sending them, and an
+# ABSENT block is not "nothing happens" — it means `passthrough`, i.e. no
+# speech-to-text, so the agent gets "a voice message arrived, no transcript" and has
+# to improvise. `transcribe` is the right default for a conversational pack; use
+# `passthrough` when you handle the audio ref yourself, or `decline` (with a
+# `notice:`) to ask for text instead.
+inbound_preprocessing:
+  voicenote:
+    mode: transcribe
+
 # Default locale for platform-emitted copy + this pack's `$t()` lookups.
 default_settings:
   locale: ar