octwin-cli 0.8.13 → 0.8.14

package/dist/lib/media-lines.js

@@ -0,0 +1,36 @@
+/**
+ * The pictures, files, voice notes and map pins a render carries, as lines a reader can see.
+ *
+ * A render's body and buttons were printed, its media were not — so a reply that SENT the full menu
+ * as a picture read as "📋 Our full menu — save the picture" with nothing under it, and a tester
+ * (the AI Author's reviewer, 2026-09-28) reported "no picture appeared" for a picture that was there.
+ * A carousel card gets a short `(image)` mark rather than its URL: a menu of seven dishes is shown
+ * many times in a test, and the mark is what a reader needs.
+ *
+ * Twin of the AI Author's test-chat printer (`src/routes/ai-author/_media-lines.ts` in the platform
+ * repo) — the same lines in `octwin chat` and in the AI Author's `chat`; change both.
+ */
+const obj = (v) => (v && typeof v === 'object' && !Array.isArray(v) ? v : {});
+const str = (v) => (typeof v === 'string' ? v : v == null ? '' : String(v));
+/** A media URL without its signed query (`?exp=…&token=…`) — the part that names the file. */
+const where = (url) => str(url).split('?')[0];
+/** The lines for a render's own media — a header picture, a file, a voice note, a pin. */
+export function mediaLines(hint) {
+    const h = obj(hint);
+    const out = [];
+    if (h.header_image)
+        out.push(`[image] ${where(h.header_image)}`);
+    if (h.type === 'document')
+        out.push(`[file] ${str(h.filename) || 'a file'} → ${where(h.url)}`);
+    if (h.type === 'audio')
+        out.push(`[voice note]${typeof h.duration_sec === 'number' ? ` ${h.duration_sec}s` : ''} → ${where(h.url)}`);
+    if (h.type === 'location') {
+        const label = [str(h.name), str(h.address)].filter(Boolean).join(' — ');
+        out.push(`[location] ${label ? `${label} ` : ''}(${str(h.latitude)}, ${str(h.longitude)})`);
+    }
+    return out;
+}
+/** A carousel card's mark: `(image) ` when it carries a picture. */
+export function cardImageMark(card) {
+    return obj(card).image_url ? '(image) ' : '';
+}

package/dist/lib/output.js

@@ -0,0 +1,99 @@
+/**
+ * Where everything this CLI prints goes — the ONE module allowed to write to stdout or stderr
+ * (eslint `no-console` holds the rest of `src/` to it).
+ *
+ * ## The contract `--json` makes
+ *
+ * Under `--json`, **stdout carries the command's result and nothing else**, so a script can
+ * `JSON.parse` it. Everything a person reads — the `→ Reading …` progress line, a table, a hint, a
+ * warning — goes to stderr instead. That is decided HERE, by `print`, not by each command remembering
+ * an `if (!asJson)` guard: a 5,600-line CLI with 486 `console.log` calls forgot it often enough that
+ * three commands were reported unparseable in one round (`records --json`, `projects create --json`,
+ * `logs --json` with nothing to list — 2026-10-01).
+ *
+ * - `print`  — prose. stdout normally; stderr under `--json`.
+ * - `err`    — a warning or an error. Always stderr.
+ * - `result` — the command's DATA. Under `--json`, the one thing on stdout (one pretty document, or
+ *              one compact line per call for a streaming command); otherwise `human` renders it, or
+ *              it prints as pretty JSON.
+ *
+ * A command declares which `--json` shape it has in the `COMMANDS` table (`cli.ts`); `runCli` then
+ * refuses `--json` on a command with none, and fails loudly when a `document` command ends without
+ * its result — the second half of the reported bug: `logs --json` with no conversations printed a
+ * sentence and no JSON at all.
+ */
+import { format } from 'node:util';
+import { writeSync } from 'node:fs';
+/**
+ * The process's streams. stderr is written synchronously (`writeSync(2, …)`) so a notice printed just
+ * before the process ends is never lost — the reason `flushNotices` always wrote that way.
+ */
+export const processIo = {
+    stdout: text => { process.stdout.write(text); },
+    stderr: text => {
+        try {
+            writeSync(2, text);
+        }
+        catch {
+            process.stderr.write(text);
+        }
+    },
+};
+export class Out {
+    io;
+    json;
+    results = 0;
+    code = 0;
+    constructor(io, json) {
+        this.io = io;
+        this.json = json;
+    }
+    /** `--json` was asked for, and this command has a JSON shape. */
+    get asJson() { return this.json !== false; }
+    /** Prose for a person. stdout normally; stderr under `--json`, so stdout carries only the result. */
+    print(...args) {
+        const line = format(...args) + '\n';
+        if (this.asJson)
+            this.io.stderr(line);
+        else
+            this.io.stdout(line);
+    }
+    /** A warning or an error — always stderr. */
+    err(...args) {
+        this.io.stderr(format(...args) + '\n');
+    }
+    /** Raw text to stderr, as given (no newline added) — the notice block writes its own. */
+    errRaw(text) {
+        this.io.stderr(text);
+    }
+    /**
+     * The command's data. Under `--json` the one thing on stdout: a `document` command emits it once
+     * (a second call is a bug in the command, and throws); a `lines` command emits one compact line per
+     * call. Otherwise `human` renders it — or, with none, it prints as pretty JSON, which is how a
+     * command with no table of its own shows a record.
+     */
+    result(value, human) {
+        if (this.json === 'document') {
+            if (this.results > 0)
+                throw new Error('this command emitted a second --json result; a document has exactly one');
+            this.results++;
+            this.io.stdout(JSON.stringify(value ?? null, null, 2) + '\n');
+            return;
+        }
+        if (this.json === 'lines') {
+            this.results++;
+            this.io.stdout(JSON.stringify(value ?? null) + '\n');
+            return;
+        }
+        if (human)
+            human();
+        else
+            this.io.stdout(JSON.stringify(value ?? null, null, 2) + '\n');
+    }
+    /** How many results were emitted — `runCli` checks a `document` command emitted its one. */
+    get emitted() { return this.results; }
+    /** End this run non-zero without unwinding — a command that printed a full report of a failure. */
+    fail(code = 1) { this.code = code; }
+    /** The exit code a command chose with `fail`, else 0. */
+    get exitCode() { return this.code; }
+}

package/dist/lib/press.js

@@ -0,0 +1,72 @@
+/**
+ * `press:` — tap a button by the LABEL the customer sees, not by its tap id.
+ *
+ * A form or checkout button carries its run's id (`t:resume:basket:run_id=R1;area=maadi`), which exists
+ * only once the reply arrives — so a `--script` could not reach past the first form step: `tap:` needs
+ * an id nobody can write in advance. `press:<label>` reads the reply the script just got and taps the
+ * button with that label, so a whole checkout is one script.
+ *
+ * Deterministic on purpose: a test must FAIL when the button it expects is gone, not have a guess work
+ * around it. Twin of the AI Author's `press` (`src/platform/core/ai-author/press.ts` in the platform
+ * repo) — the same rules, so a script means the same thing in both; change both.
+ */
+const obj = (v) => (v && typeof v === 'object' && !Array.isArray(v) ? v : {});
+const str = (v) => (typeof v === 'string' ? v : '');
+/** Every tappable button and list row in a render — never a link, which opens a URL instead. */
+export function tapsOfHint(hint) {
+    const h = obj(hint);
+    const out = [];
+    const add = (b, kind) => {
+        const x = obj(b);
+        if (x.type === 'url' || !str(x.id) || !str(x.title))
+            return;
+        out.push({ id: str(x.id), title: str(x.title), kind });
+    };
+    for (const b of h.buttons ?? [])
+        add(b, 'button');
+    for (const s of h.sections ?? [])
+        for (const r of obj(s).rows ?? [])
+            add(r, 'row');
+    for (const c of h.cards ?? [])
+        for (const b of obj(c).buttons ?? [])
+            add(b, 'button');
+    return out;
+}
+/** A label as a customer would say it: no emoji or symbols, no case, single spaces — any script. */
+export function pressKey(s) {
+    return s.normalize('NFKC').toLowerCase()
+        .replace(/[\p{Extended_Pictographic}‍️]/gu, '')
+        .replace(/[^\p{L}\p{N}]+/gu, ' ')
+        .trim();
+}
+/**
+ * The one button a label names, trying in order: the exact label; the same words without emoji or
+ * case; the one label that contains those words. None, or several different buttons, is a stop.
+ */
+export function pickTap(taps, label) {
+    const buttons = [...new Set(taps.map(t => t.title))];
+    const one = (found, how) => {
+        const ids = [...new Set(found.map(t => t.id))];
+        if (ids.length === 1)
+            return { ok: true, tap: found[0], how };
+        if (ids.length > 1)
+            return { ok: false, reason: 'several', buttons };
+        return null;
+    };
+    const exact = one(taps.filter(t => t.title.trim() === label.trim()), 'exact');
+    if (exact)
+        return exact;
+    const key = pressKey(label);
+    if (!key)
+        return { ok: false, reason: 'none', buttons };
+    return one(taps.filter(t => pressKey(t.title) === key), 'same words')
+        ?? one(taps.filter(t => pressKey(t.title).includes(key)), 'contains')
+        ?? { ok: false, reason: 'none', buttons };
+}
+/** Why a script stopped at a `press:`, and what the last reply offered instead. */
+export function pressStopLine(label, picked) {
+    const shown = picked.buttons.length ? `The last reply's buttons: ${picked.buttons.map(b => `"${b}"`).join(' · ')}.` : 'The last reply had no buttons.';
+    return picked.reason === 'several'
+        ? `press "${label}" matches more than one button. ${shown} Use the exact label, or tap its id.`
+        : `press "${label}": no button with that label. ${shown}`;
+}

package/package.json

@@ -1,46 +1,46 @@
-{
-  "name": "octwin-cli",
-  "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": {
-    "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://octwin.ai",
-  "license": "MIT"
-}
+{
+  "name": "octwin-cli",
+  "version": "0.8.14",
+  "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://octwin.ai",
+  "license": "MIT"
+}

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

@@ -1,31 +1,31 @@
-# 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.
-
-input:
-  message:
-    type:     string
-    optional: true
-    describe: 'Optional note from the user.'
-
-entry:
-  - else: true
-    goto: show
-
-steps:
-  show:
-    - render:
-        render_intent: text_card
-        body: '{$t("browse.body")}'
-      memory_note: '{$t("browse.memory_note")}'
-    - end: applied
+# 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.
+
+input:
+  message:
+    type:     string
+    optional: true
+    describe: 'Optional note from the user.'
+
+entry:
+  - else: true
+    goto: show
+
+steps:
+  show:
+    - render:
+        render_intent: text_card
+        body: '{$t("browse.body")}'
+      memory_note: '{$t("browse.memory_note")}'
+    - end: applied

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

@@ -1,6 +1,6 @@
-# EXAMPLE copy for the example `browse` flow — delete it together with browse.flow.yaml.
-flow_id: browse
-
-strings:
-  body:        'هنا يظهر المحتوى ✨ عدّل أداة "browse" لتبني ميزتك الحقيقية.'
-  memory_note: 'Showed the browse example.'
+# EXAMPLE copy for the example `browse` flow — delete it together with browse.flow.yaml.
+flow_id: browse
+
+strings:
+  body:        'هنا يظهر المحتوى ✨ عدّل أداة "browse" لتبني ميزتك الحقيقية.'
+  memory_note: 'Showed the browse example.'

package/templates/starter/manifest.yaml

@@ -1,65 +1,65 @@
-# manifest.yaml — your pack is declared entirely by this one file. Required:
-# id, version (a STRING, e.g. '1.0.0'), description. Everything else is optional
-# and grows with your domain. `octwin validate` checks it locally; the platform
-# re-validates the full schema on `octwin deploy`.
-
-id:          starter-kit
-version:     1.0.0
-description: 'A hello bot — edit this to build your pack.'
-
-# Channels this pack supports + platform capabilities it needs. A pack with
-# no media or search only needs `messaging`. Add embedding / vision / storage
-# as your domain grows. (Your data model goes in `xrm.yaml` — packs have no
-# database of their own.)
-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
-
-# Agent-callable flow tools. Each id maps to `flows/tools/<id>.flow.yaml`
-# (+ its `<id>.locale.<lang>.yaml`). List the HOME hub first — it's the pack's
-# 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 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.
-agents:
-  - id:                assistant
-    display_name:      'Starter Assistant'
-    # `openrouter/` prefix routes via OpenRouter. Operators override the
-    # model per-project from the console.
-    default_model:     'openrouter/google/gemini-3.1-flash-lite-preview'
-    # Flow tools this agent can call (subset of `flows:` above; hub first).
-    tools:
-      - home
-      - browse
-    include_platform_protocol: true
-    # Instruction parts, joined with '\n\n'. `file:` paths are pack-root
-    # relative; `.md` files may use built-in placeholders like {{pack.id}}.
-    instructions:
-      - file: prompts/identity.md
-    # No working_memory block — deliberate, and you should keep it that way.
-    # Declaring one makes the platform add Mastra's updateWorkingMemory tool +
-    # a "call it every turn" instruction: an extra LLM generation on most turns,
-    # and small models (like the lite default above) parrot the
-    # <working_memory_data> envelope straight into user-visible replies. Session
-    # identity (name/lang/phone) already reaches the model via the platform's
-    # first-turn [ctx: …] header, and tools read it from the request context —
-    # so you gain nothing here. Leave it off unless you're on a large model and
-    # have a concrete slot schema to maintain.
-    default_memory:
-      lastMessages: 10   # size of the recalled message window
+# manifest.yaml — your pack is declared entirely by this one file. Required:
+# id, version (a STRING, e.g. '1.0.0'), description. Everything else is optional
+# and grows with your domain. `octwin validate` checks it locally; the platform
+# re-validates the full schema on `octwin deploy`.
+
+id:          starter-kit
+version:     1.0.0
+description: 'A hello bot — edit this to build your pack.'
+
+# Channels this pack supports + platform capabilities it needs. A pack with
+# no media or search only needs `messaging`. Add embedding / vision / storage
+# as your domain grows. (Your data model goes in `xrm.yaml` — packs have no
+# database of their own.)
+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
+
+# Agent-callable flow tools. Each id maps to `flows/tools/<id>.flow.yaml`
+# (+ its `<id>.locale.<lang>.yaml`). List the HOME hub first — it's the pack's
+# 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 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.
+agents:
+  - id:                assistant
+    display_name:      'Starter Assistant'
+    # `openrouter/` prefix routes via OpenRouter. Operators override the
+    # model per-project from the console.
+    default_model:     'openrouter/google/gemini-3.1-flash-lite-preview'
+    # Flow tools this agent can call (subset of `flows:` above; hub first).
+    tools:
+      - home
+      - browse
+    include_platform_protocol: true
+    # Instruction parts, joined with '\n\n'. `file:` paths are pack-root
+    # relative; `.md` files may use built-in placeholders like {{pack.id}}.
+    instructions:
+      - file: prompts/identity.md
+    # No working_memory block — deliberate, and you should keep it that way.
+    # Declaring one makes the platform add Mastra's updateWorkingMemory tool +
+    # a "call it every turn" instruction: an extra LLM generation on most turns,
+    # and small models (like the lite default above) parrot the
+    # <working_memory_data> envelope straight into user-visible replies. Session
+    # identity (name/lang/phone) already reaches the model via the platform's
+    # first-turn [ctx: …] header, and tools read it from the request context —
+    # so you gain nothing here. Leave it off unless you're on a large model and
+    # have a concrete slot schema to maintain.
+    default_memory:
+      lastMessages: 10   # size of the recalled message window