octwin-cli 0.6.1 → 0.7.1

package/dist/index.js

@@ -620,6 +620,54 @@ async function notifyIfKbStale(flags) {
     }
     catch { /* a KB check must never break the CLI */ }
 }
+/**
+ * Nudge (to stderr) when the platform has memos this workspace has not read — a reply to
+ * a `octwin feedback` report, or a notice we published (new capability, deprecation,
+ * breaking change).
+ *
+ * The sibling of `notifyIfKbStale`, and the same three decisions apply for the same
+ * reasons: it rides commands that ALREADY hit the platform so it costs one tiny GET on
+ * top of networked work; it never throws, because observing must not break a command;
+ * and it is **deliberately not TTY-gated**, because the primary reader of this CLI is an
+ * authoring agent whose output is piped — the one reader that cannot notice an unread
+ * reply on its own would otherwise be the only one never told.
+ *
+ * WHY THIS EXISTS AT ALL. `octwin feedback` was one-way. Measured 2026-08-18: four
+ * reports sat unread for nine days, and one author hardcoded English across 16 flows to
+ * work around a bug that had been fixed two days earlier, because nothing could tell
+ * them. A nudge that does not name the command to run does not motivate an agent, so the
+ * line always ends in `octwin memos`.
+ *
+ * Unlike the KB check there is NO local state to compare: read state is per-tenant on the
+ * platform, so an agent on a fresh machine or in a fresh container still learns about an
+ * unread memo. That is the whole reason it is not a local marker file.
+ */
+async function notifyIfMemosWaiting(flags) {
+    try {
+        const t = resolveTargetOrNull(flags);
+        if (!t)
+            return;
+        const { status, json } = await apiGet(`${t.url}/api/self/p/memos?meta=1`, t);
+        // Silent on ANY failure — an older platform has no such route, and a nudge is never
+        // worth a diagnostic of its own. Unlike the KB poll there is no scope to explain: the
+        // route is gated on tenant access precisely so every token can answer it.
+        if (status !== 200 || !json || typeof json !== 'object')
+            return;
+        const unread = Number(json.unread ?? 0);
+        if (!Number.isFinite(unread) || unread <= 0)
+            return;
+        const actionable = Number(json.unread_actionable ?? 0);
+        const what = unread === 1 ? '1 memo' : `${unread} memos`;
+        const tail = actionable > 0 ? ` (${actionable} needing action)` : '';
+        console.error(`\n✉ ${what} from the platform${tail} — read them: octwin memos`);
+        if (actionable > 0) {
+            // Said separately, because the whole point of the severity axis is that an agent
+            // mid-build should stop and read rather than finish first.
+            console.error('  One or more may change what you are building — read before continuing.');
+        }
+    }
+    catch { /* a memo check must never break the CLI */ }
+}
 /** Which commands already made a platform call, so the trailing KB-drift poll
  *  rides on existing network work (never on offline `validate` / `init`;
  *  `platform-kb` refreshes the reference itself, so it needs no nudge). */
@@ -632,6 +680,9 @@ function commandTouchesPlatform(command, flags) {
         case 'chat':
         case 'media':
         case 'pull':
+        // `memos` is networked but needs NO memo nudge — it just read them. It still gets the
+        // KB drift check, which is a different question.
+        case 'memos': return true;
         case 'records':
         case 'work':
         case 'logs':
@@ -1908,11 +1959,11 @@ async function cmdRecordsWrite(flags) {
         if (json?.has_xrm === false)
             die('this pack declares no XRM entities');
         const rec = json?.record ?? {};
-        // 200 = the dedupe key matched an existing row; 201 = genuinely new. Saying
-        // "created" for a match would misreport what the pack's `dedupe_by` did.
+        // 200 = the entity's identity matched an existing row; 201 = genuinely new.
+        // Saying "created" for a match would misreport what the save actually did.
         console.log(status === 201
             ? `✓ Created #${rec.record_number ?? '?'}  ${rec.id ?? ''}`
-            : `✓ Matched an EXISTING record (the entity's dedupe key hit) — #${rec.record_number ?? '?'}  ${rec.id ?? ''}`);
+            : `✓ Matched an EXISTING record (its unique constraint identified it) — #${rec.record_number ?? '?'}  ${rec.id ?? ''}`);
         if (rec.id)
             readBack(rec.id);
         return;
@@ -2058,6 +2109,60 @@ async function cmdFeedback(flags) {
         console.log('  ⓘ no local capability reference found, so the report carries no KB version.');
         console.log('    Pull it before your next session: octwin platform-kb');
     }
+    console.log('  A reply arrives as a memo — this CLI will tell you when one is waiting.');
+}
+/**
+ * `octwin memos [--json] [--all]` — read what the platform has told you.
+ *
+ * The other half of `octwin feedback`. Two kinds arrive here: a REPLY to a report you
+ * sent, and a NOTICE we published to every author (a new capability, a deprecation, a
+ * breaking change). Both are markdown, printed in full — this is a channel for reading,
+ * not a list to page through, so there is no `show <id>`.
+ *
+ * Reading ACKS: the default prints unread memos and marks them read, so the nudge stops.
+ * `--all` re-reads history and acks nothing, which is also the escape hatch if a piped
+ * `--json` consumer crashed halfway through.
+ */
+async function cmdMemos(flags) {
+    const t = resolveTarget(flags);
+    const all = flags.all === true;
+    const { status, json } = await apiGet(`${t.url}/api/self/p/memos${all ? '?all=1' : ''}`, t);
+    if (status !== 200) {
+        die(`could not read memos (HTTP ${status})${errDetail(json)}${authFailureDetail(status, t.url)}`);
+    }
+    const rows = (json?.rows ?? []);
+    if (flags.json === true) {
+        console.log(JSON.stringify(rows, null, 2));
+        return;
+    }
+    if (rows.length === 0) {
+        console.log(all ? 'No memos yet.' : 'No unread memos.  (History: octwin memos --all)');
+        return;
+    }
+    const mark = (s) => s === 'breaking' ? '⛔ BREAKING' : s === 'action_required' ? '⚠ ACTION' : 'ⓘ';
+    for (const m of rows) {
+        const when = String(m.published_at ?? '').slice(0, 10);
+        const about = m.pack_id ? ` · ${m.pack_id}` : '';
+        const seen = m.read_at ? ' · (already read)' : '';
+        console.log(`\n${'─'.repeat(72)}`);
+        console.log(`${mark(m.severity)}  ${m.title}`);
+        console.log(`${m.kind === 'reply' ? 'reply to your report' : 'platform notice'} · ${when}${about}${seen}`);
+        console.log(`${'─'.repeat(72)}\n`);
+        console.log(m.body_md.trimEnd());
+    }
+    console.log();
+    // Ack only what we just showed as unread, and only on the default path — `--all`
+    // deliberately leaves read state alone so history can be re-read any number of times.
+    if (!all) {
+        const ids = rows.filter(m => !m.read_at).map(m => m.id);
+        if (ids.length > 0) {
+            const res = await apiSend('POST', `${t.url}/api/self/p/memos/read`, { ids }, t);
+            // A failed ack is not a failed command — the author HAS read them. Say so rather
+            // than dying after printing everything, and the nudge simply fires again.
+            if (res.status !== 200)
+                console.error(`ⓘ could not mark them read (HTTP ${res.status}) — they will be offered again.`);
+        }
+    }
 }
 /** `octwin logs [conversationId] [--as <handle>] [--json]` — list conversations
  *  or show one's event timeline (full text + the renders each turn produced). */
@@ -2642,10 +2747,17 @@ async function cmdWorkWrite(flags) {
     }
     if (dryRun) {
         console.log('Preview (nothing was committed):');
+        // Stated in words BEFORE the dump. `to_stage: null` is already in the JSON below, but a null
+        // among twenty keys is not an answer anyone reads — a pack author previewed exactly this,
+        // shipped an action with no `to_stage`, and lost the `awaiting_customer` their whole
+        // reply-capture branched on. Same reason the console preview now says it too.
+        console.log(json?.to_stage
+            ? `  → moves the record to '${json.to_stage}'.`
+            : '  → does NOT change the status (this action only records a decision).');
         console.log(JSON.stringify(json, null, 2));
         return;
     }
-    console.log(`✓ Applied '${action}'${json?.to_stage ? ` — record is now '${json.to_stage}'` : ''}.`);
+    console.log(`✓ Applied '${action}'${json?.to_stage ? ` — record is now '${json.to_stage}'` : ' — status unchanged (the action declares no to_stage)'}.`);
     // `relayed`/`notified` are the customer-facing half; silence here usually means
     // the action had no message template, which is easy to mistake for a failure.
     const reached = json?.relayed || json?.notified;
@@ -3751,6 +3863,7 @@ function help() {
   octwin platform-kb [pull] [--if-stale|--check] [--dir .] [--url <url>]  # no token needed
   octwin test    [--dir .]                               # = validate --remote (the full platform check)
   octwin feedback [--dir .]                              # submit this pack's FEEDBACK.md to the platform team
+  octwin memos   [--all] [--json]                        # read the platform's replies + notices (a reply to your feedback lands here)
 
 Writes — exercise the state your pack creates (each needs the matching :write scope):
   octwin records create <entity> --set field=value …     # also: patch <id> --entity <e>, stage <id> --to <s>, note <id> "…"
@@ -3980,6 +4093,13 @@ octwin projects rm <slug> [--yes]
                agent loops that want to branch without parsing prose.`,
     test: `octwin test [--dir .]
   Alias for \`octwin validate --remote\` — the full platform check.`,
+    memos: `octwin memos [--all] [--json]
+  Read what the platform has told you: a REPLY to a report you sent with
+  \`octwin feedback\`, or a NOTICE published to every author (a new capability,
+  a deprecation, a breaking change). Bodies are printed in full.
+  Reading marks them read, so the reminder stops. --all re-reads history and
+  acks nothing. --json to branch on \`severity\`
+  (info | action_required | breaking).`,
     feedback: `octwin feedback [--dir .]
   Submit this pack's FEEDBACK.md to the platform team.
   The octwin-pack skill writes that file in its last step — findings grouped by
@@ -4070,6 +4190,9 @@ async function main() {
         case 'feedback':
             await cmdFeedback(flags);
             break;
+        case 'memos':
+            await cmdMemos(flags);
+            break;
         case 'test':
             await cmdValidate({ ...flags, remote: true });
             break; // A6: `test` = the full remote validate, not a validate-clone
@@ -4091,6 +4214,8 @@ async function main() {
     // offline paths); CLI-upgrade always.
     if (commandTouchesPlatform(command, flags))
         await notifyIfKbStale(flags);
+    if (commandTouchesPlatform(command, flags))
+        await notifyIfMemosWaiting(flags);
     await notifyIfOutdated();
 }
 main().catch((err) => die(err?.message ?? String(err)));

package/package.json

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