octwin-cli 0.8.11 → 0.8.13

package/dist/lib/args-check.js

@@ -58,6 +58,11 @@ export function loadPrimitiveArgSpecs(packDir) {
                 required: Array.isArray(schema.required) ? schema.required : [],
                 open: ap !== undefined && ap !== false,
                 requiresOneOf: Array.isArray(entry.requiresOneOf) ? entry.requiresOneOf : [],
+                // Kept only when BOTH halves are present. A pair with no message would print a warning
+                // that names two argument keys and says nothing about why they are a trap — which is the
+                // sort of warning authors learn to scroll past.
+                warnsTogether: (entry.warnsTogether ?? [])
+                    .filter((w) => Array.isArray(w?.args) && w.args.length > 0 && typeof w?.message === 'string' && w.message.length > 0),
             });
         }
     }
@@ -74,6 +79,10 @@ export function loadPrimitiveArgSpecs(packDir) {
  * primitive's declared set. Walks the whole document rather than just `steps:`
  * — a `do:` is legal in a `foreach` body, a `collect` hook, an `outputs:` port
  * body and `require:`, and a dropped argument is just as invisible there.
+ *
+ * Warnings come back on their own list rather than mixed into `ArgFinding`. They have a different
+ * severity, a different exit code, and a different sentence — folding them together would have
+ * meant either failing a build over a warning or hiding an error inside a warning count.
  */
 export function findArgViolations(doc, file, specs) {
     const findings = [];
@@ -107,6 +116,52 @@ export function findArgViolations(doc, file, specs) {
     walk(doc, []);
     return findings;
 }
+/**
+ * Walk for `do:` nodes whose `args:` supply every member of a declared `warnsTogether` pair.
+ *
+ * A separate walk rather than a second output of `findArgViolations`, on purpose: that function
+ * skips a primitive whose schema is OPEN (`!spec.open`), because an open schema makes "unknown
+ * key" unanswerable. A `warnsTogether` pair is answerable either way — it names two keys that ARE
+ * declared — so gating it on closedness would silently drop the check for every passthrough
+ * primitive, which is exactly the shape of hole a scan grows without anyone noticing.
+ */
+export function findArgWarnings(doc, file, specs) {
+    const warnings = [];
+    const walk = (node, path) => {
+        if (Array.isArray(node)) {
+            node.forEach((v, i) => walk(v, [...path, i]));
+            return;
+        }
+        if (!node || typeof node !== 'object')
+            return;
+        const obj = node;
+        if (typeof obj.do === 'string') {
+            const spec = specs.get(obj.do);
+            if (spec?.warnsTogether.length) {
+                const args = (obj.args && typeof obj.args === 'object' && !Array.isArray(obj.args))
+                    ? obj.args
+                    : {};
+                for (const pair of spec.warnsTogether) {
+                    // KEY PRESENCE only, matching the platform's own `checkPrimitiveArgs`. The values are
+                    // almost always expressions (`record_id: '$found.record_id'`), so judging them would
+                    // mean judging a string — and the trap is about the combination, not the values.
+                    if (pair.args.every(k => k in args)) {
+                        warnings.push({ file, primitive: obj.do, path: [...path], args: [...pair.args], message: pair.message });
+                    }
+                }
+            }
+        }
+        for (const [k, v] of Object.entries(obj))
+            walk(v, [...path, k]);
+    };
+    walk(doc, []);
+    return warnings;
+}
+/** One line per warning: where, which pair, and the primitive's own reason. */
+export function describeArgWarning(w) {
+    const at = w.line ? `${w.file}:${w.line}` : w.file;
+    return `${at}: \`${w.primitive}\` passes ${w.args.map(a => `'${a}'`).join(' + ')} together — ${w.message}`;
+}
 /** One-line human message per finding. */
 export function describeArgFinding(f) {
     const parts = [];

package/dist/lib/chat-line.js

@@ -0,0 +1,44 @@
+/**
+ * Who sent a render on the chat stream — and whether it answers the turn.
+ *
+ * `octwin chat` reads ONE stream for a conversation, and more than the AI Agent writes to it:
+ *
+ *   - a `notify` send — a `schedule_notify` reminder, a reaction's notification, a queued
+ *     briefing — which answers nothing the author just sent (`source: 'notify'` on the web
+ *     envelope);
+ *   - a person holding the conversation in Live chat (`author.kind: 'human'`, with a name);
+ *   - a platform line such as a handoff's join / return copy (`author.kind: 'system'`).
+ *
+ * Every one of them used to print as `← <body>`, exactly like the AI Agent's reply. The case
+ * that cost an author real time (chughtai, 2026-09-23): a reminder fired mid `--script`, the CLI
+ * took it for the turn's reply and ended the turn on it, and the real reply — which `octwin logs`
+ * showed the flow had produced correctly — looked lost.
+ *
+ * Kept free of I/O so the rules can be tested without a stream.
+ */
+export function chatSender(ev) {
+    if (ev.source === 'notify')
+        return 'notify';
+    if (ev.author?.kind === 'human')
+        return 'operator';
+    if (ev.author?.kind === 'system')
+        return 'platform';
+    return 'agent';
+}
+/** The label printed before the body — empty for the AI Agent, whose replies stay `← …`. */
+export function chatLabel(ev) {
+    switch (chatSender(ev)) {
+        case 'notify': return '[notify] ';
+        case 'operator': return ev.author?.name ? `[operator: ${ev.author.name}] ` : '[operator] ';
+        case 'platform': return '[platform] ';
+        default: return '';
+    }
+}
+/**
+ * Whether this render is an ANSWER to the message the author just sent — what ends a turn's wait.
+ * A notify is not: it would have been sent whether or not the author wrote anything. An operator's
+ * line and a platform line are: in a held conversation they ARE the reply.
+ */
+export function answersTheTurn(ev) {
+    return chatSender(ev) !== 'notify';
+}

package/dist/lib/outcome.js

@@ -56,6 +56,17 @@ export function reportChecks(checks, io) {
                 io.die(outcome.hint);
             }
             // eslint-disable-next-line no-fallthrough -- `die` returns never; the case above cannot exit.
+            case 'warnings': {
+                // On `log`, not `err`, and the run CONTINUES. A warning that stopped the run, or that
+                // arrived on the error stream, would be an error wearing a different word — and the next
+                // check is the one the author was actually waiting for.
+                const n = outcome.lines.length;
+                io.log(`⚠ ${n} ${outcome.noun}${n === 1 ? '' : 's'} — not fatal:`);
+                for (const line of outcome.lines)
+                    io.log(`  ⚠ ${line}`);
+                io.log(`  ${outcome.hint}`);
+                break;
+            }
             case 'not-run':
                 notRun.push({ label: check.label, lookup: outcome.lookup });
                 break;

package/dist/lib/template-check.js

@@ -9,7 +9,7 @@
  * platform's own `approve_apply` is the common case: `confirm_title` misspelled
  * silently falls back to the hardcoded Arabic default.
  *
- * PACK TEMPLATES SHADOW PLATFORM ONES. A pack may ship `templates/<name>.yaml`
+ * PACK TEMPLATES SHADOW PLATFORM ONES. A pack may ship `templates/<name>.template.yaml`
  * of its own, and a pack template of the same name wins. So the caller passes
  * the pack's own template names and this check stays silent about them entirely
  * — it has no schema for a template it did not publish, and inventing one would
@@ -96,7 +96,9 @@ export function describeTemplateFinding(f) {
     switch (f.kind) {
         case 'unknown':
             return `${f.file}: \`use: ${f.template}\` — no such template. Platform templates: ${f.known.join(', ')}`
-                + `. (A template of your own must live at templates/${f.template}.yaml in the pack.)`;
+                // `.template.yaml`, not `.yaml`: the platform loads only that suffix, so a template saved
+                // as this hint used to say was silently ignored and the `use:` stayed unresolved.
+                + `. (A template of your own must live at templates/${f.template}.template.yaml in the pack.)`;
         case 'unknown-param':
             return `${f.file}: \`use: ${f.template}\` passes ${f.keys.map(k => `'${k}'`).join(', ')}, which the template declares no param for `
                 + `— dropped in silence, and the body sees undefined. Params: ${f.params.join(', ')}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "octwin-cli",
-  "version": "0.8.11",
+  "version": "0.8.13",
   "description": "Octwin external-pack developer CLI (by CEQUENS) — scaffold, validate, deploy, and check pure-YAML packs on your tenant.",
   "type": "module",
   "bin": {
@@ -41,6 +41,6 @@
     "yaml"
   ],
   "author": "CEQUENS",
-  "homepage": "https://www.npmjs.com/package/octwin-cli",
+  "homepage": "https://octwin.ai",
   "license": "MIT"
 }

package/templates/starter/flows/tools/browse.flow.yaml

@@ -1,6 +1,13 @@
+# EXAMPLE — replace it or delete it; do not leave it behind.
 # An example capability the home hub invokes. Replace this with your real tool
 # (record_list + a carousel, a collect: intake, a case_open, …). Kept trivial here
 # so the scaffold is chattable end-to-end: home menu → tap "browse" → this renders.
+#
+# If you do not keep it, delete THREE things together: this file, every
+# `browse.locale.<lang>.yaml` beside it, and the `browse` line in manifest.yaml
+# `flows:` (plus the home menu row that invokes it). A file left here with its
+# manifest line removed never loads — but its copy is still checked, so a pack that
+# adds a second language fails validation over a flow nobody uses.
 flow_id:     browse
 version:     1
 description: An example capability, reached from the home menu. Replace with your real tool.

package/templates/starter/flows/tools/browse.locale.ar.yaml

@@ -1,3 +1,4 @@
+# EXAMPLE copy for the example `browse` flow — delete it together with browse.flow.yaml.
 flow_id: browse
 
 strings:

package/templates/starter/manifest.yaml

@@ -33,7 +33,7 @@ default_settings:
 # front door; add each new tool here as you build it.
 flows:
   - home      # the menu / navigation hub (see references/ux-patterns.md)
-  - browse    # an example tool the hub invokes — replace with your real capability
+  - browse    # an EXAMPLE tool the hub invokes — replace it, or delete this line AND flows/tools/browse.*
 
 # One agent. The platform's universal agent protocol is auto-appended by
 # `createPackAgents` — `instructions:` carries only pack-supplied parts.