octwin-cli 0.1.12 → 0.1.13

package/CHANGELOG.md

@@ -5,6 +5,28 @@ Format: [Keep a Changelog](https://keepachangelog.com/) — newest first, bucket
 **Added · Changed · Deprecated · Removed · Fixed · Security**. The platform-wide view lives in the
 repo root [`CHANGELOG.md`](../../CHANGELOG.md); this file is the CLI-only cut that ships with the package.
 
+## [0.1.13] - 2026-07-22
+
+### Added
+- **A headless media loop — produce + send.** Two paired additions close the coverage hole where any
+  media-collect flow (e.g. `activate-app`'s registration / ID uploads) stalled at the upload prompt
+  because the CLI could neither *make* nor *send* an image:
+  - `octwin media generate "<prompt>" [--out <file.png>] [--size 1024x1024] [--json]` — AI-generates an
+    image on the platform (needs a `media:generate`-scoped token), stores it as a public asset, and prints
+    its `MEDIA-` handle + serve URL. `--out` downloads the bytes to a file (WhatsApp renders only
+    `.png`/`.jpg`); `--json` emits `{ media_id, url, mime, width, height, bytes }`.
+  - `octwin chat --media <file|media-id>` — uploads a local file (or a media id from
+    `media generate --json`) as an image/document/audio inbound; any accompanying `"message"` rides as
+    its caption. The platform's media pipeline folds the upload into a running collect, so media flows
+    are now fully drivable headlessly.
+
+### Changed
+- **The KB-drift nudge now names what changed.** With the platform serving per-entry content hashes, the
+  post-command nudge appends a `(N changed · M added · K removed)` summary instead of a bare hash pair.
+- **`octwin platform-kb` prints a changelog on pull.** Instead of only a doc/catalog count, the pull now
+  diffs the fresh index against your last pull and lists exactly which docs/catalogs were added (`+`),
+  changed (`~`), or removed (`-`) — so a replaced schema shape is visible, not silent.
+
 ## [0.1.12] - 2026-07-22
 
 ### Fixed

package/dist/index.js

@@ -17,7 +17,8 @@
  *   octwin records [entity] [id]    # inspect the pack's XRM data (records:read token)
  *   octwin cases   [caseId] [--queues]     # inspect casework (support tickets) — list / one case + timeline
  *   octwin logs    [conversationId] [--as h] [--json]  # list conversations / show one's timeline
- *   octwin chat    "msg" [--as h] [--tap <tap-id>] [--json]  # drive a turn via the web channel
+ *   octwin chat    "msg" [--as h] [--tap <tap-id>] [--media <file|id>] [--json]  # drive a turn via the web channel (+ send media)
+ *   octwin media   generate "<prompt>" [--out <file.png>] [--size 1024x1024] [--json]  # AI-generate an image → MEDIA- handle (media:generate scope)
  *   octwin platform-kb [pull] [--dir .]  # pull the platform capability reference for the authoring skill
  *   octwin test    [--dir .]        # = validate --remote (the full platform check)
  *
@@ -35,7 +36,7 @@
  * (pure-YAML enforcement + manifest/flow Zod) and installs it onto the project.
  */
 import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, statSync, cpSync } from 'node:fs';
-import { join, resolve, dirname } from 'node:path';
+import { join, resolve, dirname, basename } from 'node:path';
 import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { parse as parseYaml } from 'yaml';
@@ -112,6 +113,50 @@ function errDetail(json) {
     const msg = typeof json === 'string' ? json : (json.error ?? json.message ?? JSON.stringify(json));
     return msg ? ` — ${msg}` : '';
 }
+// ── media helpers (produce/send loop) ───────────────────────────────────────
+/** Extension → MIME for local files the `chat --media` sender uploads (mirrors
+ *  the platform's accepted image/document/audio MIME sets). */
+const MEDIA_MIME_BY_EXT = {
+    '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.png': 'image/png', '.gif': 'image/gif', '.webp': 'image/webp',
+    '.pdf': 'application/pdf', '.txt': 'text/plain',
+    '.doc': 'application/msword',
+    '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    '.ogg': 'audio/ogg', '.mp3': 'audio/mpeg', '.m4a': 'audio/mp4', '.wav': 'audio/wav', '.webm': 'audio/webm', '.aac': 'audio/aac',
+};
+/** MIME → file extension (for naming a fetched-by-id media part). */
+const EXT_BY_MEDIA_MIME = {
+    'image/jpeg': 'jpg', 'image/png': 'png', 'image/gif': 'gif', 'image/webp': 'webp', 'application/pdf': 'pdf',
+};
+/** The inbound `type` the platform expects for a MIME (image/document/audio). */
+function mediaKindOf(mime) {
+    if (mime.startsWith('image/'))
+        return 'image';
+    if (mime.startsWith('audio/'))
+        return 'audio';
+    return 'document';
+}
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Resolve a `--media` argument to an uploadable part: a local file path, OR a
+ *  media UUID (as returned by `octwin media generate --json`) fetched from the
+ *  public serve route. The cosmetic `MEDIA-…` handle is NOT fetchable (the serve
+ *  route is UUID-keyed) — use the file written by `--out`, or the `media_id`. */
+async function resolveMediaPart(url, arg) {
+    if (existsSync(arg)) {
+        const buffer = readFileSync(arg);
+        const ext = arg.slice(arg.lastIndexOf('.')).toLowerCase();
+        const mime = MEDIA_MIME_BY_EXT[ext] ?? 'application/octet-stream';
+        return { blob: new Blob([buffer], { type: mime }), kind: mediaKindOf(mime), filename: basename(arg) };
+    }
+    if (UUID_RE.test(arg)) {
+        const res = await fetchOrDie(`${url}/api/media/${arg}`, undefined, 'fetch media');
+        if (!res.ok)
+            die(`--media '${arg}' not found (HTTP ${res.status}) — pass a local file path, or a media id from 'octwin media generate --json'`);
+        const mime = res.headers.get('content-type') ?? 'application/octet-stream';
+        const buffer = Buffer.from(await res.arrayBuffer());
+        return { blob: new Blob([buffer], { type: mime }), kind: mediaKindOf(mime), filename: `${arg}.${EXT_BY_MEDIA_MIME[mime] ?? 'bin'}` };
+    }
+    die(`--media '${arg}' is neither an existing file nor a media id (UUID). The cosmetic MEDIA-… handle isn't fetchable — send the file written by 'octwin media generate --out', or pass the media_id from '--json'.`);
+}
 // ── bundle collection ───────────────────────────────────────────────────────
 const SKIP_DIRS = new Set(['.git', 'node_modules', '.pack-bundles', 'dist', '.mastra']);
 /** Collect every text file under `packDir` into a `{ relPath: content }` map. */
@@ -243,18 +288,34 @@ async function notifyIfOutdated() {
     }
     catch { /* a version check must never break the CLI */ }
 }
-// ── platform-KB drift check (observe the pulled reference, TTY-only, fail-silent) ──
-/** The `content_hash` of a previously-pulled KB in `<packDir>/.octwin/platform-kb/`,
- *  or null if nothing has been pulled yet. */
-function readLocalKbHash(packDir) {
+/** A previously-pulled KB's identity in `<packDir>/.octwin/platform-kb/index.json`
+ *  (content hash + per-entry index), or null if nothing has been pulled yet. */
+function readLocalKb(packDir) {
     try {
         const idx = JSON.parse(readFileSync(join(packDir, '.octwin', 'platform-kb', 'index.json'), 'utf8'));
-        return typeof idx.content_hash === 'string' ? idx.content_hash : null;
+        return {
+            content_hash: typeof idx.content_hash === 'string' ? idx.content_hash : null,
+            index: Array.isArray(idx.index) ? idx.index : [],
+        };
     }
     catch {
         return null;
     }
 }
+/** Diff two KB indexes by key + per-entry `hash` → added / removed / changed keys. */
+function diffKbIndex(prev, next) {
+    const prevMap = new Map(prev.map(e => [e.key, e.hash]));
+    const nextKeys = new Set(next.map(e => e.key));
+    const added = [], changed = [];
+    for (const e of next) {
+        if (!prevMap.has(e.key))
+            added.push(e.key);
+        else if (prevMap.get(e.key) !== e.hash)
+            changed.push(e.key);
+    }
+    const removed = prev.filter(e => !nextKeys.has(e.key)).map(e => e.key);
+    return { added, removed, changed };
+}
 /** Nudge (to stderr) when the platform's capability KB has changed since the last
  *  `octwin platform-kb pull`. The sibling of `notifyIfOutdated`, for the KB instead
  *  of the CLI: run only after commands that already hit the platform, so this adds
@@ -266,8 +327,8 @@ async function notifyIfKbStale(flags) {
         return;
     try {
         const packDir = resolve(flags.dir ?? '.');
-        const localHash = readLocalKbHash(packDir);
-        if (!localHash)
+        const local = readLocalKb(packDir);
+        if (!local?.content_hash)
             return; // never pulled → the skill already says to pull
         const t = resolveTargetOrNull(flags, packDir);
         if (!t)
@@ -281,8 +342,21 @@ async function notifyIfKbStale(flags) {
         if (!res.ok)
             return;
         const meta = await res.json();
-        if (meta.content_hash && meta.content_hash !== localHash) {
-            console.error(`\n⬆ the platform capability reference changed since you last pulled it (${localHash} → ${meta.content_hash}).`);
+        if (meta.content_hash && meta.content_hash !== local.content_hash) {
+            // Per-entry summary (now that the index carries per-entry hashes) — the
+            // exact list of what changed is one `octwin platform-kb` away.
+            let summary = '';
+            if (Array.isArray(meta.index) && local.index.length) {
+                const { added, removed, changed } = diffKbIndex(local.index, meta.index);
+                const parts = [
+                    changed.length && `${changed.length} changed`,
+                    added.length && `${added.length} added`,
+                    removed.length && `${removed.length} removed`,
+                ].filter(Boolean);
+                if (parts.length)
+                    summary = ` (${parts.join(' · ')})`;
+            }
+            console.error(`\n⬆ the platform capability reference changed since you last pulled it${summary}.`);
             console.error('  Refresh it: octwin platform-kb');
         }
     }
@@ -298,6 +372,7 @@ function commandTouchesPlatform(command, flags) {
         case 'status':
         case 'test':
         case 'chat':
+        case 'media':
         case 'records':
         case 'cases':
         case 'logs':
@@ -631,6 +706,9 @@ async function cmdPlatformKb(flags) {
         process.exit(1);
     }
     const bundle = JSON.parse(text);
+    // Snapshot the prior pull's index BEFORE overwriting it, so we can show the
+    // author EXACTLY what changed (not just a count).
+    const prior = readLocalKb(packDir);
     // Write the reference into <packDir>/.octwin/platform-kb/ — markdown docs (the
     // skill reads these first) + JSON catalogs (precise field schemas). Gitignored.
     const outDir = join(packDir, '.octwin', 'platform-kb');
@@ -654,6 +732,23 @@ async function cmdPlatformKb(flags) {
     writeFileSync(join(outDir, 'index.json'), JSON.stringify({ version: bundle.version, content_hash: bundle.content_hash, generated_at: bundle.generated_at, index: bundle.index }, null, 2) + '\n', 'utf8');
     console.log(`✓ Pulled the Octwin platform KB → ${outDir}`);
     console.log(`  ${mdCount} markdown docs + ${jsonCount} JSON catalogs (reference version ${bundle.version ?? '?'})`);
+    // Changelog since the last pull — per-entry hashes tell us WHICH docs/catalogs
+    // moved (a schema shape being replaced shows as a `~ changed`), not just a count.
+    if (prior?.content_hash) {
+        if (prior.content_hash === bundle.content_hash) {
+            console.log('  (no content changes since your last pull)');
+        }
+        else {
+            const { added, removed, changed } = diffKbIndex(prior.index, bundle.index ?? []);
+            console.log(`  Δ changes since your last pull (${prior.content_hash} → ${bundle.content_hash ?? '?'}):`);
+            for (const k of added)
+                console.log(`    + ${k} (new)`);
+            for (const k of changed)
+                console.log(`    ~ ${k} (changed)`);
+            for (const k of removed)
+                console.log(`    - ${k} (removed)`);
+        }
+    }
     console.log('  The octwin-pack authoring skill reads these as the source of truth for what the platform supports.');
 }
 // ── records / cases / logs / chat — headless inspect + test with the deploy token ────
@@ -931,9 +1026,10 @@ async function cmdChat(flags) {
     const from = flags.as ?? 'cli-tester';
     const asJson = flags.json === true;
     const tapId = typeof flags.tap === 'string' ? flags.tap : undefined;
+    const mediaArg = typeof flags.media === 'string' ? flags.media : undefined;
     const message = flags._[0];
-    if (!message && !tapId)
-        die('usage: octwin chat "your message" [--as <handle>] [--tap <tap-id>] [--json]');
+    if (!message && !tapId && !mediaArg)
+        die('usage: octwin chat "your message" [--as <handle>] [--tap <tap-id>] [--media <file|id>] [--json]');
     // Fresh idempotency key per call (see the command doc above).
     const localId = `cli-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
     if (!asJson)
@@ -957,16 +1053,35 @@ async function cmdChat(flags) {
         if (f.id != null && f.id > boundary)
             boundary = f.id;
     }
-    // Phase 2 — send the inbound (text, or an interactive tap).
-    console.log(`→ [${from}] ${tapId ? `(tap) ${tapId}` : message}`);
-    const body = tapId
-        ? { type: 'interactive', from, tap_id: tapId, ...(message ? { raw_title: message } : {}), local_id: localId }
-        : { type: 'text', from, text: message, local_id: localId };
-    const postRes = await fetchOrDie(`${url}/api/web/inbound/${tenant}/${project}`, {
-        method: 'POST',
-        headers: { 'content-type': 'application/json' },
-        body: JSON.stringify(body),
-    }, 'send message');
+    // Phase 2 — send the inbound (media upload, an interactive tap, or text).
+    const inbound = `${url}/api/web/inbound/${tenant}/${project}`;
+    let postRes;
+    if (mediaArg && !tapId) {
+        // Multipart upload → the platform's media pipeline sets $inbound_media, which
+        // a running collect folds into $state.<field> (docs/19 §8a). Any accompanying
+        // message rides as the media caption.
+        const { blob, kind, filename } = await resolveMediaPart(url, mediaArg);
+        console.log(`→ [${from}] (media:${kind}) ${filename}${message ? ` — "${message}"` : ''}`);
+        const form = new FormData();
+        form.append('type', kind);
+        form.append('from', from);
+        form.append('local_id', localId);
+        if (message)
+            form.append('caption', message);
+        form.append('file', blob, filename);
+        postRes = await fetchOrDie(inbound, { method: 'POST', body: form }, 'send media'); // fetch sets the multipart boundary
+    }
+    else {
+        console.log(`→ [${from}] ${tapId ? `(tap) ${tapId}` : message}`);
+        const body = tapId
+            ? { type: 'interactive', from, tap_id: tapId, ...(message ? { raw_title: message } : {}), local_id: localId }
+            : { type: 'text', from, text: message, local_id: localId };
+        postRes = await fetchOrDie(inbound, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(body),
+        }, 'send message');
+    }
     if (!postRes.ok) {
         await cancel();
         die(`send rejected (HTTP ${postRes.status}): ${await postRes.text()}`);
@@ -1011,6 +1126,67 @@ async function cmdChat(flags) {
     }
     console.log(`\n(same --as '${from}' continues this conversation — timeline: octwin logs --as ${from})`);
 }
+/** `octwin media generate "<prompt>" [--out <file.png>] [--size 1024x1024] [--json]`
+ *  — AI-generate an image on the platform (needs a `media:generate`-scoped token),
+ *  store it as a public asset, and return its `MEDIA-` handle + serve URL. `--out`
+ *  downloads the bytes to a file (WhatsApp renders only `.png`/`.jpg`); the paired
+ *  `octwin chat --media <file|id>` feeds it into a running media-collect flow. */
+async function cmdMedia(flags) {
+    const sub = flags._[0];
+    if (sub !== 'generate')
+        die('usage: octwin media generate "<prompt>" [--out <file.png>] [--size 1024x1024] [--json]');
+    const packDir = resolve(flags.dir ?? '.');
+    const { url, tenant, project, token } = resolveTarget(flags, packDir);
+    const prompt = flags._[1];
+    if (!prompt)
+        die('usage: octwin media generate "<prompt>" [--out <file.png>] [--size 1024x1024] [--json]');
+    const asJson = flags.json === true;
+    const size = typeof flags.size === 'string' ? flags.size : undefined;
+    const out = typeof flags.out === 'string' ? flags.out : undefined;
+    if (!asJson)
+        console.log(`→ Generating an image on '${tenant}/${project}' @ ${url} …`);
+    const res = await fetchOrDie(`${url}/api/admin/tenants/${tenant}/projects/${project}/media/generate`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', authorization: `Bearer ${token}` },
+        body: JSON.stringify({ prompt, ...(size ? { size } : {}) }),
+    }, 'media generate');
+    const text = await res.text();
+    if (!res.ok) {
+        let j;
+        try {
+            j = JSON.parse(text);
+        }
+        catch {
+            j = text;
+        }
+        console.error(`✗ media generate failed (HTTP ${res.status})${errDetail(j)}`);
+        printAuthHint(res.status, url);
+        process.exit(1);
+    }
+    const r = JSON.parse(text);
+    const absUrl = /^https?:/i.test(r.url) ? r.url : `${url}${r.url}`;
+    // --out → download the bytes so the paired `chat --media <file>` can send them.
+    if (out) {
+        const dl = await fetchOrDie(absUrl, undefined, 'download generated image');
+        if (!dl.ok)
+            die(`could not download the generated image (HTTP ${dl.status})`);
+        writeFileSync(out, Buffer.from(await dl.arrayBuffer()));
+        const ext = out.slice(out.lastIndexOf('.')).toLowerCase();
+        if (ext !== '.png' && ext !== '.jpg' && ext !== '.jpeg') {
+            console.error(`  ⚠ '${out}' isn't a .png/.jpg — WhatsApp only renders those extensions.`);
+        }
+    }
+    if (asJson) {
+        console.log(JSON.stringify({ media_id: r.media_id, url: absUrl, mime: r.mime, width: r.width, height: r.height, bytes: r.bytes }));
+        return;
+    }
+    console.log(`✓ Generated ${r.media_ref} (${r.width}×${r.height}, ${r.mime}, ${r.bytes} bytes)`);
+    console.log(`  id:  ${r.media_id}`);
+    console.log(`  url: ${absUrl}`);
+    if (out)
+        console.log(`  saved → ${out}`);
+    console.log(`  Send it into a chat: octwin chat "here you go" --media ${out ?? r.media_id} --as <handle>`);
+}
 /** `octwin cases [caseId] [--queues]` — inspect casework (support tickets):
  *  the aggregate inbox, one case + its timeline, or the queue list. */
 async function cmdCases(flags) {
@@ -1106,7 +1282,8 @@ function help() {
   octwin records [entity] [id]                           # inspect the pack's XRM data (needs a records:read token)
   octwin cases   [caseId] [--queues] [--json]            # inspect casework (support tickets) + timelines
   octwin logs    [conversationId] [--as <handle>] [--json]  # list conversations / show one's event timeline
-  octwin chat    "message" [--as <handle>] [--tap <tap-id>] [--json]  # drive a turn + print every render
+  octwin chat    "message" [--as <handle>] [--tap <tap-id>] [--media <file|id>] [--json]  # drive a turn (+ send media) + print every render
+  octwin media   generate "<prompt>" [--out <file.png>] [--size 1024x1024] [--json]  # AI-generate an image → MEDIA- handle (needs media:generate scope)
   octwin platform-kb [pull] [--dir .] [--url <url>] [--tenant <slug>] [--token <t>]
   octwin test    [--dir .]                               # = validate --remote (the full platform check)
 
@@ -1145,11 +1322,19 @@ const COMMAND_HELP = {
   No id = recent conversations (handle, status, last activity; --as filters).
   With id = the full event timeline including what each turn rendered.
   --json = raw events (verbatim payloads).`,
-    chat: `octwin chat "message" [--as <handle>] [--tap <tap-id>] [--json]
+    chat: `octwin chat "message" [--as <handle>] [--tap <tap-id>] [--media <file|id>] [--json]
   Drive one turn through the dev web channel and print every render with its
   tap ids. Same --as handle = same conversation (multi-turn works).
   --tap presses a rendered button/list row instead of sending text.
+  --media uploads a local file (or a media id from 'media generate --json') as
+  an image/document/audio inbound — any "message" rides as its caption; feeds a
+  running media-collect flow (e.g. activate-app).
   --json dumps the raw SSE envelopes for the turn.`,
+    media: `octwin media generate "<prompt>" [--out <file.png>] [--size 1024x1024] [--json]
+  AI-generate an image (needs a media:generate-scoped token), store it as a
+  public asset, and print its MEDIA- handle + serve URL. --out downloads the
+  bytes (WhatsApp renders only .png/.jpg); --json emits { media_id, url, mime,
+  width, height, bytes }. Pair with 'octwin chat --media' to drive media flows.`,
     'platform-kb': `octwin platform-kb [pull] [--dir .] [--url <url>] [--tenant <slug>] [--token <t>]
   Pull the platform capability reference (markdown + JSON catalogs) into
   .octwin/platform-kb/ for the octwin-pack authoring skill.`,
@@ -1196,6 +1381,9 @@ async function main() {
         case 'chat':
             await cmdChat(flags);
             break;
+        case 'media':
+            await cmdMedia(flags);
+            break;
         case 'platform-kb':
             await cmdPlatformKb(flags);
             break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "octwin-cli",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "description": "Octwin external-pack developer CLI (by CEQUENS) — scaffold, validate, deploy, and check pure-YAML packs on your tenant.",
   "type": "module",
   "bin": {