Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

feat(console): What's new page under TOOLS, plugin changelog parser and marker (ADR-478), console 0.38.0

ruv9cef4cb07024
diff --git a/plugins/ruflo-console/.claude-plugin/plugin.json b/plugins/ruflo-console/.claude-plugin/plugin.json
index eb4dab3a52..6b3c823d13 100644
--- a/plugins/ruflo-console/.claude-plugin/plugin.json
+++ b/plugins/ruflo-console/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "ruflo-console",
"description": "ruflo's cockpit inside Claude Code and the one /ruflo command for every ruflo mod (function hooks, early access). Views: overview with health alerts, swarm topology graph, claims flow with TTL rings, federation map, plugin health matrix, learning curve and pipeline, MetaHarness radar and audit trend, memory, cost gauge, agent timeline, approvals queue, event stream, a main menu, an x.ruv.io federation board, an AI terminal (codex, claude or both in remembered sessions, streamed), Skills (npx skills), a Hive-Mind view, a MetaHarness lab, agent drill-down; a command palette for confirm-gated actions through the ruflo CLI; a band above the prompt. Reads ruflo's files and the CLI's local JSON; anything not measured reads n/a. The one network call it makes by itself is a daily read of the published plugin.json at github.com/ruvnet/ruflo to offer an update (Settings → Updates: ask, auto, or off); it installs only through Claude Code's own claude plugin update, and never a new major version without asking.",
- "version": "0.37.0",
+ "version": "0.38.0",
"author": {
"name": "ruvnet",
"url": "https://github.com/ruvnet"
diff --git a/plugins/ruflo-console/hooks/ask-claude.ts b/plugins/ruflo-console/hooks/ask-claude.ts
index c52223cad5..4da24e5ddf 100644
--- a/plugins/ruflo-console/hooks/ask-claude.ts
+++ b/plugins/ruflo-console/hooks/ask-claude.ts
@@ -49,6 +49,7 @@ export const VIEW_ASK: Record<ViewId, ViewAsk> = {
devtools: { default: 'Which of these tools should I use for the change I am making?', slash: 'ruflo-jujutsu:jujutsu' },
sandbox: { default: 'Which sandbox fits what I want to try, and is anything running here I should end?', slash: 'ruflo-rvf:rvf' },
market: { default: 'Which of these plugins would help most for what I am doing?' },
+ whatsnew: { default: 'Which of these plugin changes matter for how I work, and does any breaking change need action from me?' },
settings: { default: 'Which of these settings should I change for how I work?' },
agent: { default: 'What is this agent doing, and is anything wrong with it?' },
}
diff --git a/plugins/ruflo-console/hooks/bindings.ts b/plugins/ruflo-console/hooks/bindings.ts
index 5a4a5f6e40..e97c194ac3 100644
--- a/plugins/ruflo-console/hooks/bindings.ts
+++ b/plugins/ruflo-console/hooks/bindings.ts
@@ -41,6 +41,7 @@ import { runUpdateCheck } from './update-flow'
import { claudeActions } from './mission-claude'
import { UPDATES_KEY } from './updates'
import { setToastMode, toggleToastMute } from './toasts'
+import { whatsnewActions } from './whatsnew'
import { vectorActions } from './vector'
import type { Actions } from './views/common'
import { openTasks, selection } from './views/select'
@@ -121,6 +122,7 @@ export function actionsOf(state: State, host: Host, runner: Runner, steps: Steps
mode: mode => setToastMode(state, host, mode),
mute: source => toggleToastMute(state, host, source),
},
+ whatsnew: whatsnewActions(state, host),
checkUpdates: () => {
state.updateNote = 'checking…'
host.invalidate()
diff --git a/plugins/ruflo-console/hooks/controller.ts b/plugins/ruflo-console/hooks/controller.ts
index b916790df7..1729fef545 100644
--- a/plugins/ruflo-console/hooks/controller.ts
+++ b/plugins/ruflo-console/hooks/controller.ts
@@ -31,6 +31,7 @@ import type { Actions } from './views/common'
import { picturesOf } from './views/frames'
import { pulseDue } from './pulse'
import { refreshWorkflows } from './wf-live'
+import { syncWhatsNew } from './whatsnew'
const ACTIVITY_BUCKET_MS = 5_000
const PANE_WATCH_MS = 1_000
@@ -129,6 +130,7 @@ export function createController(state: State, host: Host): Controller {
const before = previous === null ? null : factsOf(state, now)
state.snapshot = snapshot
+ syncWhatsNew(state, host)
record(state.events, diffEvents(previous, snapshot, now))
// A mission that finished or lost a task is said in a toast too: the band's notice row reaches only a person looking at the console.
diff --git a/plugins/ruflo-console/hooks/data/changelog.ts b/plugins/ruflo-console/hooks/data/changelog.ts
new file mode 100644
index 0000000000..2301f67a40
--- /dev/null
+++ b/plugins/ruflo-console/hooks/data/changelog.ts
@@ -0,0 +1,121 @@
+/**
+ * A plugin's bundled CHANGELOG.md, parsed for the What's new page (ADR-478). Pure: no host, no network, no clock.
+ *
+ * The format is deliberately narrow, so a person and a machine read the same thing:
+ *
+ * ## 0.38.0 — 2026-10-07
+ * - feat: What's new page
+ * - fix: a thing that was broken
+ * - breaking: something that changes what you do
+ * - chore: housekeeping
+ *
+ * Every line of the file is untrusted text (a plugin can ship anything). Parsing is bounded in bytes, lines, entries and bullets, uses
+ * only anchored, linear patterns on a clipped line, and every kept line goes through `maskLine`: escape sequences, control and bidi
+ * characters are dropped, credential-shaped text is masked, and the line is cut to a fixed width. Nothing here throws.
+ */
+import { maskLine } from './event-mask'
+
+export type ChangeKind = 'fix' | 'feat' | 'breaking' | 'chore'
+export const CHANGE_KINDS: readonly ChangeKind[] = ['breaking', 'feat', 'fix', 'chore']
+
+export type Change = { kind: ChangeKind; text: string }
+export type ChangeEntry = { version: string; date: string; changes: Change[]; /** Bullets past the per-entry cap, counted not kept. */ more: number }
+
+/** The bounds. A file past `bytes` is cut there, never refused, and the cut is said (`truncated`). */
+export const LIMITS = { bytes: 64 * 1024, lines: 2_000, entries: 40, changes: 12, line: 160, header: 64, bullet: 600 } as const
+
+export type ParsedChangelog =
+ | { ok: true; entries: ChangeEntry[]; /** Anything was dropped: the file is longer than the bounds, or entries repeat a version. */ truncated: boolean }
+ | { ok: false; reason: 'empty' | 'garbled' }
+
+/** `## 1.2.3 — 2026-10-07` (an em dash, an en dash or a hyphen): anchored, no nested quantifiers. */
+const HEADER = /^## (\d{1,4})\.(\d{1,4})\.(\d{1,4}) [—–-] (\d{4})-(\d{2})-(\d{2})[ \t]*$/
+/** `- fix: text` (a `*` bullet too). */
+const BULLET = /^[-*] (fix|feat|breaking|chore):[ \t]*(.*)$/
+
+export type Semver = readonly [number, number, number]
+
+/** `major.minor.patch` and nothing else, as a tuple; null for anything else (a pre-release is never ordered). */
+export function semverOf(text: string): Semver | null {
+ const match = /^(\d{1,4})\.(\d{1,4})\.(\d{1,4})$/.exec(text)
+
+ return match === null ? null : [Number(match[1]), Number(match[2]), Number(match[3])]
+}
+
+/** Negative when `a` is older than `b`, positive when newer, 0 when equal; a non-version sorts as older than any version. */
+export function compareVersions(a: string, b: string): number {
+ const x = semverOf(a)
+ const y = semverOf(b)
+
+ if (x === null || y === null) return x === y ? 0 : x === null ? -1 : 1
+
+ for (let i = 0; i < 3; i++) if (x[i] !== y[i]) return (x[i] as number) - (y[i] as number)
+
+ return 0
+}
+
+const dateOk = (month: number, day: number): boolean => month >= 1 && month <= 12 && day >= 1 && day <= 31
+
+/** Parses `text`, newest version first. An unrecognised line is ignored, never an error; a file with no entry at all is `garbled` (or `empty`). */
+export function parseChangelog(text: unknown): ParsedChangelog {
+ if (typeof text !== 'string' || text.trim() === '') return { ok: false, reason: 'empty' }
+
+ const cut = text.length > LIMITS.bytes
+ const lines = text.slice(0, LIMITS.bytes).split('\n', LIMITS.lines + 1)
+ const entries: ChangeEntry[] = []
+ const seen = new Set<string>()
+ let truncated = cut || lines.length > LIMITS.lines
+ let current: ChangeEntry | null = null
+
+ for (const raw of lines.slice(0, LIMITS.lines)) {
+ const line = raw.endsWith('\r') ? raw.slice(0, -1) : raw
+ const head = line.startsWith('## ') ? HEADER.exec(line.slice(0, LIMITS.header)) : null
+
+ if (head !== null) {
+ const version = `${Number(head[1])}.${Number(head[2])}.${Number(head[3])}`
+
+ if (seen.has(version) || !dateOk(Number(head[5]), Number(head[6]))) {
+ // A repeated or impossible header starts nothing: its bullets belong to no entry.
+ truncated = truncated || seen.has(version)
+ current = null
+ continue
+ }
+
+ if (entries.length >= LIMITS.entries) {
+ truncated = true
+ current = null
+ break
+ }
+
+ seen.add(version)
+ current = { version, date: `${head[4]}-${head[5]}-${head[6]}`, changes: [], more: 0 }
+ entries.push(current)
+ continue
+ }
+
+ if (current === null || line.length < 8) continue
+
+ const bullet = BULLET.exec(line.slice(0, LIMITS.bullet))
+
+ if (bullet === null) continue
+
+ const words = maskLine(bullet[2], LIMITS.line)
+
+ if (words === '') continue
+ if (current.changes.length >= LIMITS.changes) current.more += 1
+ else current.changes.push({ kind: bullet[1] as ChangeKind, text: words })
+ }
+
+ if (entries.length === 0) return { ok: false, reason: 'garbled' }
+
+ // File order is the author's; the page's order is the version's (a hand-edited file may be out of order).
+ entries.sort((a, b) => compareVersions(b.version, a.version))
+
+ return { ok: true, entries, truncated }
+}
+
+/** The entries newer than `seenVersion` (every entry when it is absent or not a version). */
+export const entriesAfter = (entries: readonly ChangeEntry[], seenVersion: string | undefined): ChangeEntry[] => (seenVersion === undefined ? [...entries] : entries.filter(entry => compareVersions(entry.version, seenVersion) > 0))
+
+/** The words of a kind, as the page marks it. */
+export const MARK: Readonly<Record<ChangeKind, string>> = { breaking: '‼ BREAKING', feat: '+ new', fix: '✓ fix', chore: '· chore' }
diff --git a/plugins/ruflo-console/hooks/gfx/boot.ts b/plugins/ruflo-console/hooks/gfx/boot.ts
index c7c0353ea4..64d34cd67d 100644
--- a/plugins/ruflo-console/hooks/gfx/boot.ts
+++ b/plugins/ruflo-console/hooks/gfx/boot.ts
@@ -58,6 +58,7 @@ export const BOOT_MODULES: readonly { name: string; note: string }[] = [
{ name: 'The Room', note: 'who says and does what, and what waits for a yes' },
{ name: 'Performance', note: 'metrics and bottlenecks' },
{ name: 'AI Terminal', note: 'ruflo, codex, claude' },
+ { name: 'What’s new', note: 'changes in your plugins' },
{ name: 'Settings', note: 'every option a button' },
]
const NAME_WIDTH = 15
diff --git a/plugins/ruflo-console/hooks/help-docs.ts b/plugins/ruflo-console/hooks/help-docs.ts
index cf04a21ccd..5dccbc6354 100644
--- a/plugins/ruflo-console/hooks/help-docs.ts
+++ b/plugins/ruflo-console/hooks/help-docs.ts
@@ -67,6 +67,7 @@ export const VIEW_TOPIC: Partial<Record<ViewId, string>> = {
devtools: 'devtools',
sandbox: 'sandbox',
settings: 'settings',
+ whatsnew: 'whatsnew',
timeline: 'watch',
events: 'watch',
room: 'room',
diff --git a/plugins/ruflo-console/hooks/help-topics-more.ts b/plugins/ruflo-console/hooks/help-topics-more.ts
index 8f89ce86f8..a105fdb5c2 100644
--- a/plugins/ruflo-console/hooks/help-topics-more.ts
+++ b/plugins/ruflo-console/hooks/help-topics-more.ts
@@ -229,9 +229,23 @@ export const MORE_TOPICS: readonly HelpTopic[] = [
{ text: 'Settings has an Updates row: choose ask or auto, and press “check for an update now”.', go: { view: 'settings' } },
{ text: 'Restart Claude Code after an update so the new version loads.' },
],
- related: ['settings', 'plugins'],
+ related: ['settings', 'plugins', 'whatsnew'],
keywords: ['version', 'upgrade', 'newer', 'auto-update'],
},
+ {
+ id: 'whatsnew',
+ title: 'What’s new in your plugins',
+ group: 'Console',
+ summary: 'the changes in each installed ruflo plugin, newest first',
+ steps: [
+ { text: 'Open What’s new (TOOLS group, or /ruflo whatsnew). Each plugin’s own CHANGELOG.md is read from disk; nothing is fetched.', go: { view: 'whatsnew' } },
+ { text: 'Entries under “Since you last looked” are the ones you have not seen; the divider marks where you left off.' },
+ { text: 'A breaking change stays pinned at the top until you dismiss it.' },
+ { text: 'The “toast when something new lands” switch shows one short message per new version.' },
+ ],
+ related: ['updates', 'plugins'],
+ keywords: ['changelog', 'release', 'notes', 'new', 'breaking', 'version', 'changes'],
+ },
{
id: 'headless',
title: 'Commands without the pane',
diff --git a/plugins/ruflo-console/hooks/menu-style.ts b/plugins/ruflo-console/hooks/menu-style.ts
index 5b54861211..63e7ba30a3 100644
--- a/plugins/ruflo-console/hooks/menu-style.ts
+++ b/plugins/ruflo-console/hooks/menu-style.ts
@@ -10,6 +10,7 @@ import { activeMission, progressOf } from './mission-control'
import { alertsOf, approvalsOf } from './data/alerts'
import { secMemo } from './secure'
import type { State, ViewId } from './state'
+import { hasUnseen } from './whatsnew'
import { money } from './views/bar'
export { ACCENT, chip, LOUD, MUTED, PALETTE } from './menu-colors'
@@ -44,6 +45,7 @@ export function badgesOf(state: State, nowMs: number): Partial<Record<ViewId, Ba
if (findings !== null && serious > 0) out.secure = { text: `🔒 ${serious}`, tone: findings.counts.critical > 0 ? 'attention' : 'plain' }
if (state.usage?.costUsd !== undefined && state.usage.costUsd >= 0.01) out.cost = { text: money(state.usage.costUsd), tone: 'plain' }
if (state.terminal.runs.size > 0) out.terminal = { text: '●', tone: 'plain' }
+ if (hasUnseen(state)) out.whatsnew = { text: 'new', tone: 'attention' }
if (state.updateAvailable !== '') out.settings = { text: `⬆ ${state.updateAvailable}`, tone: 'attention' }
return out
diff --git a/plugins/ruflo-console/hooks/nav-state.ts b/plugins/ruflo-console/hooks/nav-state.ts
index 1d2dcae2e9..357ac84d56 100644
--- a/plugins/ruflo-console/hooks/nav-state.ts
+++ b/plugins/ruflo-console/hooks/nav-state.ts
@@ -12,7 +12,7 @@ export const NAV_GROUPS: readonly { title: string; icon: string; rows: readonly
{ title: 'MIND', icon: '🧠', rows: [['learning', 'neural', 'metaharness', 'evolve', 'memory', 'vector']] },
{ title: 'SAFETY', icon: '🛡️', rows: [['secure', 'cost', 'perf', 'timeline', 'events', 'room']] },
{ title: 'NETWORK', icon: '🌐', rows: [['federation', 'xruv', 'sandbox', 'skills', 'market']] },
- { title: 'TOOLS', icon: '🛠️', rows: [['terminal', 'automate', 'devtools', 'plugins', 'settings']] },
+ { title: 'TOOLS', icon: '🛠️', rows: [['terminal', 'automate', 'devtools', 'plugins', 'whatsnew', 'settings']] },
]
export const groupOf = (view: ViewId): string | null => NAV_GROUPS.find(group => group.rows.some(row => row.includes(view)))?.title ?? null
diff --git a/plugins/ruflo-console/hooks/register.ts b/plugins/ruflo-console/hooks/register.ts
index 8eef875fbe..dea53ec2e3 100644
--- a/plugins/ruflo-console/hooks/register.ts
+++ b/plugins/ruflo-console/hooks/register.ts
@@ -17,6 +17,7 @@ import { buildOf, isOurCheckout, setBuild } from './build'
import { runUpdateCheck } from './update-flow'
import { announceModelTools, parseControlEnv, serveModelTools } from './model-tools'
import { loadAiPrefs, setControlCap } from './settings'
+import { hydrateWhatsNew } from './whatsnew'
import { prefsFromStore, recordToast, saveToastPrefs, TOASTS_KEY } from './toasts'
import { contextSection, onPromptSubmit, onTurnComplete } from './mission-claude'
import { parseMode, RECHECK_EVERY_MS, UPDATES_KEY } from './updates'
@@ -202,7 +203,11 @@ export const register: Register = (on, raw: PluginOptions) => {
() => undefined,
)
+ // What's new (ADR-478): the record of what was looked at, read once; the controller's first disk read then takes the baseline.
+ const looked = hydrateWhatsNew(state, here).catch(() => undefined)
+
void toasted
+ void looked
void Promise.all([built, moded]).then(() => {
if (!state.isInteractive) return
diff --git a/plugins/ruflo-console/hooks/self-check.ts b/plugins/ruflo-console/hooks/self-check.ts
index 7c3696b795..4e8815046b 100644
--- a/plugins/ruflo-console/hooks/self-check.ts
+++ b/plugins/ruflo-console/hooks/self-check.ts
@@ -22,11 +22,11 @@ export const AREA_VIEW: Record<string, ViewId> = {
Missions: 'missions', Overview: 'overview', Swarm: 'swarm', Workflows: 'workflows', 'Hive-Mind': 'hive', Claims: 'claims', Approvals: 'approvals', Automation: 'automate',
Learning: 'learning', Neural: 'neural', 'Vector Lab': 'vector', 'Memory Lab': 'memory', MetaHarness: 'metaharness', 'Self-Evolution': 'evolve',
Security: 'secure', Federation: 'federation', 'x.ruv.io': 'xruv', 'Plugins & Mods': 'plugins', Skills: 'skills', 'Plugin Catalog': 'market',
- 'Dev Tools': 'devtools', Sandbox: 'sandbox', 'Cost & Budget': 'cost', Timeline: 'timeline', Events: 'events', 'The Room': 'room', Performance: 'perf', 'AI Terminal': 'terminal', Settings: 'settings',
+ 'Dev Tools': 'devtools', Sandbox: 'sandbox', 'Cost & Budget': 'cost', Timeline: 'timeline', Events: 'events', 'The Room': 'room', Performance: 'perf', 'AI Terminal': 'terminal', 'What’s new': 'whatsnew', Settings: 'settings',
}
/** Pages with no hotkey on purpose (every letter is taken): reached from the menu, the nav, the palette or by name. */
-const NAMED_ONLY: ReadonlySet<string> = new Set(['sandbox', 'room', 'workflows'])
+const NAMED_ONLY: ReadonlySet<string> = new Set(['sandbox', 'room', 'workflows', 'whatsnew'])
export type Registries = { secure: readonly SecEntry[]; secureText: readonly SecText[]; perf: readonly PerfEntry[]; dev: readonly DevEntry[]; lab: readonly LabEntry[] }
export const REGISTRIES: Registries = { secure: SECURE, secureText: SECURE_TEXT, perf: PERF, dev: DEV, lab: LAB }
diff --git a/plugins/ruflo-console/hooks/state.ts b/plugins/ruflo-console/hooks/state.ts
index 6a43fb2738..c8a196a2a5 100644
--- a/plugins/ruflo-console/hooks/state.ts
+++ b/plugins/ruflo-console/hooks/state.ts
@@ -11,6 +11,7 @@ import { emptyEvolve, type EvolveState } from './data/evolve'
import { emptySkills, type SkillsState } from './data/skills'
import type { UpdatesMode } from './updates'
import type { Digest, ToastPrefs } from './toast-policy'
+import { newWhatsNew, type WhatsNewState } from './whatsnew'
import { emptyMemoryLab, type MemoryLabState } from './memory-lab'
import { emptyVector, type VectorState } from './data/vector'
import type { Snapshot } from './data/snapshot'
@@ -26,7 +27,7 @@ export type NavStyle = 'auto' | 'icons' | 'brief' | 'full'
export const NAV_STYLES: readonly NavStyle[] = ['auto', 'icons', 'brief', 'full']
export const NAV_KEY = 'nav-style'
-export type ViewId = 'menu' | 'overview' | 'swarm' | 'workflows' | 'hive' | 'claims' | 'federation' | 'plugins' | 'learning' | 'metaharness' | 'memory' | 'cost' | 'timeline' | 'approvals' | 'events' | 'room' | 'missions' | 'xruv' | 'terminal' | 'skills' | 'agent' | 'secure' | 'perf' | 'automate' | 'neural' | 'vector' | 'evolve' | 'devtools' | 'sandbox' | 'market' | 'settings'
+export type ViewId = 'menu' | 'overview' | 'swarm' | 'workflows' | 'hive' | 'claims' | 'federation' | 'plugins' | 'learning' | 'metaharness' | 'memory' | 'cost' | 'timeline' | 'approvals' | 'events' | 'room' | 'missions' | 'xruv' | 'terminal' | 'skills' | 'agent' | 'secure' | 'perf' | 'automate' | 'neural' | 'vector' | 'evolve' | 'devtools' | 'sandbox' | 'market' | 'settings' | 'whatsnew'
/**
* The views in tab order, each with its hotkey and the inline height it asks for. Digits are the first nine; the three
@@ -69,6 +70,7 @@ export const VIEWS: readonly { id: ViewId; key: string; label: string; short: st
{ id: 'devtools', key: 'd', label: 'Dev Tools', short: 'Dev', icon: '🔧', blurb: 'the integration surface: GitHub, diff analysis, agenticow, WASM, browser, terminal, providers, maintenance', rows: 40 },
{ id: 'sandbox', key: '', label: 'Sandbox', short: 'Sbx', icon: '🧫', blurb: 'isolated places to try things: tmux sessions, RVF copy-on-write branches, RVM', rows: 40 },
{ id: 'market', key: 'm', label: 'Plugin Catalog', short: 'Cat', icon: '📦', blurb: 'every ruflo plugin, mod and skill: what it ships, install, enable, disable, update, view and use', rows: 50 },
+ { id: 'whatsnew', key: '', label: 'What’s new', short: 'New', icon: '🆕', blurb: 'what changed in your ruflo plugins, newest first: from each plugin’s own CHANGELOG, breaking changes pinned until you dismiss them', rows: 40 },
{ id: 'settings', key: 's', label: 'Settings', short: 'Set', icon: '⚙️', blurb: 'simple to advanced settings: plugin options, ruflo config, updates, and the AI terminal’s model and budget, each edited in place', rows: 50 },
]
@@ -233,6 +235,8 @@ export type State = {
toastPrefs: ToastPrefs
/** The console's own toasts, drawn or not, until the Events pass takes them in (bounded). */
toastLog: Digest[]
+ /** What's new (ADR-478): the record of what was looked at, the changelogs read when the page opens. */
+ whatsnew: WhatsNewState
/** What the last update check found, in a line, for Settings; empty until one has run. */
updateNote: string
/** A published version the person has not taken ("Not now"), shown on the band as a link to Settings; empty when there is none. */
@@ -359,6 +363,7 @@ export function newState(raw: PluginOptions | undefined): State {
updates: 'ask',
toastPrefs: { mode: 'all', muted: [] },
toastLog: [],
+ whatsnew: newWhatsNew(),
updateNote: '',
updateAvailable: '',
navPick: null,
diff --git a/plugins/ruflo-console/hooks/version.ts b/plugins/ruflo-console/hooks/version.ts
index ec977ec469..d8757c9e58 100644
--- a/plugins/ruflo-console/hooks/version.ts
+++ b/plugins/ruflo-console/hooks/version.ts
@@ -2,4 +2,4 @@
* The console's version, shown on the header so a person can tell which build is running. Kept equal to the plugin's manifest
* (`.claude-plugin/plugin.json`); tests/version.spec.ts fails if the two drift.
*/
-export const CONSOLE_VERSION = '0.37.0'
+export const CONSOLE_VERSION = '0.38.0'
diff --git a/plugins/ruflo-console/hooks/view-open.ts b/plugins/ruflo-console/hooks/view-open.ts
index 65f28bdfd3..3e77bd1ec3 100644
--- a/plugins/ruflo-console/hooks/view-open.ts
+++ b/plugins/ruflo-console/hooks/view-open.ts
@@ -9,10 +9,15 @@ import { loadCatalog } from './plugin-catalog'
import { probeTmux } from './sandbox'
import { loadAiPrefs, loadCore, loadPlugin, settingsOf } from './settings'
import { CLI_PREFIXES, type State } from './state'
+import { closeWhatsNew, openWhatsNew } from './whatsnew'
import { loadCommandNames } from './mission-skills'
export function openLoaders(state: State, host: Host, view: State['view']): void {
+ // What's new reads each plugin's bundled CHANGELOG.md (local files, no network) when it opens, and forgets the divider when it is left.
+ if (view === 'whatsnew') void openWhatsNew(state, host)
+ else closeWhatsNew(state)
+
// Mission Control asks the session which slash commands it offers (the ruflo-goals skills among them).
// Every section can offer the slash command of the plugin that fits it, so the session's commands are read once.
if (view === 'missions' || state.commandNames.length === 0) void loadCommandNames(state, host)
diff --git a/plugins/ruflo-console/hooks/views/common.ts b/plugins/ruflo-console/hooks/views/common.ts
index 9baf5a81a6..750bae7358 100644
--- a/plugins/ruflo-console/hooks/views/common.ts
+++ b/plugins/ruflo-console/hooks/views/common.ts
@@ -8,6 +8,7 @@ import type { OptimizerActions } from '../optimizer'
import { askedBy } from '../data/room'
import type { RoomActions } from '../room'
import type { WatchActions } from '../watch'
+import type { WhatsNewActions } from '../whatsnew'
import type { EventsActions } from '../events-ui'
import type { TimelineActions } from '../timeline-ui'
import type { Attention } from './attention'
@@ -128,6 +129,8 @@ export type Actions = {
checkUpdates: () => void
/** The Toasts setting (ADR-477): which levels draw (all, important, off), and muting or unmuting one source's toasts (saved; every toast is still recorded). */
toasts: { mode: (mode: ToastMode) => void; mute: (source: string) => void }
+ /** What's new (ADR-478): dismiss a pinned breaking change (or all of them), toggle the toast for a new version. */
+ whatsnew: WhatsNewActions
/** Opens or closes a collapsible section (`<view>/<id>`). */
toggle: (key: string) => void
/** The Workflows page: cursor keys, the inspector's tab, the confirm-gated ruflo agent verbs, and naming a transcript's path. */
diff --git a/plugins/ruflo-console/hooks/views/menu.ts b/plugins/ruflo-console/hooks/views/menu.ts
index 729d7b2172..ccf058530f 100644
--- a/plugins/ruflo-console/hooks/views/menu.ts
+++ b/plugins/ruflo-console/hooks/views/menu.ts
@@ -52,7 +52,7 @@ export const GROUPS: readonly { title: string; sections: readonly { name: string
},
{
title: 'TOOLS',
- sections: [{ name: 'tools', items: [{ label: 'AI Terminal', go: 'terminal' }, { label: 'Automation', go: 'automate' }, { label: 'Dev Tools', go: 'devtools' }, { label: 'Plugins & Mods', go: 'plugins' }, { label: 'Settings', go: 'settings' }, { label: 'Command Palette', go: 'palette' }, { label: 'Help', go: 'help' }, { label: 'Log Off', go: 'close' }] }],
+ sections: [{ name: 'tools', items: [{ label: 'AI Terminal', go: 'terminal' }, { label: 'Automation', go: 'automate' }, { label: 'Dev Tools', go: 'devtools' }, { label: 'Plugins & Mods', go: 'plugins' }, { label: 'What’s new', go: 'whatsnew' }, { label: 'Settings', go: 'settings' }, { label: 'Command Palette', go: 'palette' }, { label: 'Help', go: 'help' }, { label: 'Log Off', go: 'close' }] }],
},
]
diff --git a/plugins/ruflo-console/hooks/views/nav.ts b/plugins/ruflo-console/hooks/views/nav.ts
index 9b4970dbb9..9443501601 100644
--- a/plugins/ruflo-console/hooks/views/nav.ts
+++ b/plugins/ruflo-console/hooks/views/nav.ts
@@ -10,7 +10,7 @@ import type { RenderElement } from 'claude-code'
import { chip, NAV_ACCENT } from '../menu-colors'
import { badgesOf } from '../menu-style'
-import { accentOfView, findPages, NAV_GROUPS, shownGroup } from '../nav-state'
+import { accentOfView, findPages, groupOf, NAV_GROUPS, shownGroup } from '../nav-state'
import { VIEWS, type ViewId } from '../state'
import { CARD_COLUMNS } from './card'
import { isBbs, THEME, type Ctx } from './common'
@@ -36,6 +36,8 @@ export function groupedTabs(ctx: Ctx, hasHotkey: (view: View) => boolean): Rende
const spell = (view: View, form: string) => (form === 'icons' ? view.icon : form === 'brief' ? `${view.icon} ${view.short}` : `${view.icon} ${view.label}`)
// The same badges the menu carries (approvals waiting, findings, an update ...), so the nav says what is going on behind a page too.
const badges = badgesOf(state, ctx.nowMs)
+ // A group whose page has something new carries a dot while its pages are not showing (the page's own entry says `new` once the group is open).
+ const newGroup = badges.whatsnew === undefined ? null : groupOf('whatsnew')
const badgeText = (view: View): string => (badges[view.id] === undefined ? '' : ` ${badges[view.id]?.text}`)
// The open page always spells out its whole name, whatever the form (see `tab`), so that is how wide it is.
// (On the main menu of a narrow card the chip says MENU, so it is not cut to "MAIN M…" beside the groups.)
@@ -80,7 +82,7 @@ export function groupedTabs(ctx: Ctx, hasHotkey: (view: View) => boolean): Rende
const chips = NAV_GROUPS.map(group =>
group.title === shown && found === null && !isMenuIdle
? ctx.kit.Box({ key: `nav-group-${group.title}`, children: [ctx.kit.Text({ ...(isBbs() ? chip(NAV_ACCENT[group.title] ?? THEME.head) : { bold: true, color: THEME.head }), children: `[${icons ? `${group.icon} ` : ''}${group.title}${inner < 72 ? '' : ' ▾'}]` })] })
- : ctx.kit.Button({ key: `nav-group-${group.title}`, label: ` ${icons ? `${group.icon} ` : ''}${group.title} `, plain: true, dimColor: true, onPress: () => ctx.act.navigator.group(group.title) }),
+ : ctx.kit.Button({ key: `nav-group-${group.title}`, label: ` ${icons ? `${group.icon} ` : ''}${group.title}${group.title === newGroup ? ' •' : ''} `, plain: true, dimColor: true, onPress: () => ctx.act.navigator.group(group.title) }),
)
// On the main menu a picked group's pages are open: a ✕ beside the chips closes them again.
const closePick = open === 'menu' && !isMenuIdle ? [ctx.kit.Button({ key: 'nav-pick-close', label: ' ✕ ', plain: true, dimColor: true, onPress: () => ctx.act.navigator.group(shown) })] : []
diff --git a/plugins/ruflo-console/hooks/views/pane.ts b/plugins/ruflo-console/hooks/views/pane.ts
index f3b4182a79..682b884f03 100644
--- a/plugins/ruflo-console/hooks/views/pane.ts
+++ b/plugins/ruflo-console/hooks/views/pane.ts
@@ -26,6 +26,7 @@ import { costView } from './cost'
import { evolveResult, evolveView } from './evolve'
import { catalogView } from './plugin-catalog'
import { settingsView } from './settings'
+import { whatsnewView } from './whatsnew'
import { devtoolsResult, devtoolsView } from './devtools'
import { sandboxView } from './sandbox'
import { federationView } from './federation'
@@ -96,6 +97,7 @@ const BODIES: Record<ViewId, (ctx: Ctx) => RenderElement> = {
sandbox: sandboxView,
market: catalogView,
settings: settingsView,
+ whatsnew: whatsnewView,
agent: agentView,
}
diff --git a/plugins/ruflo-console/hooks/views/whatsnew.ts b/plugins/ruflo-console/hooks/views/whatsnew.ts
new file mode 100644
index 0000000000..97c869025d
--- /dev/null
+++ b/plugins/ruflo-console/hooks/views/whatsnew.ts
@@ -0,0 +1,99 @@
+/**
+ * What's new (ADR-478): what changed in the ruflo plugins installed here, newest first, from each plugin's own bundled CHANGELOG.md.
+ * Breaking changes are pinned at the top until dismissed; a divider marks where the person last looked; nothing is fetched (a newer
+ * published ruflo-console is named from the daily update check's own result, with the place to read its notes as plain text).
+ * Every line shown was washed when the file was parsed (hooks/data/changelog.ts); this view only lays it out.
+ */
+import type { RenderElement } from 'claude-code'
+
+import { compareVersions, entriesAfter, MARK, type ChangeEntry, type ChangeKind } from '../data/changelog'
+import { tidy } from '../toast-policy'
+import { CONSOLE_VERSION } from '../version'
+import { CONSOLE_NAME, NOTES_URL, pinnedOf, RELEASES_URL, type Log } from '../whatsnew'
+import { button, col, row, rule, section, text, THEME, type Ctx } from './common'
+
+const MAX_NEW = 40
+const MAX_EARLIER = 24
+const PER_ENTRY = 6
+
+type Shown = { name: string; entry: ChangeEntry }
+
+const colorOf = (kind: ChangeKind): { color?: string; bold?: boolean; dimColor?: boolean } => (kind === 'breaking' ? { color: THEME.bad, bold: true } : kind === 'feat' ? { color: THEME.ok } : kind === 'fix' ? { color: THEME.info } : { dimColor: true })
+
+const newest = (a: Shown, b: Shown): number => (a.entry.date === b.entry.date ? compareVersions(b.entry.version, a.entry.version) || a.name.localeCompare(b.name) : a.entry.date < b.entry.date ? 1 : -1)
+
+/** One entry: its heading, then its changes (a few, the rest counted). */
+function entryRows(ctx: Ctx, name: string, entry: ChangeEntry): RenderElement[] {
+ const shown = entry.changes.slice(0, PER_ENTRY)
+ const rest = entry.changes.length - shown.length + entry.more
+
+ return [
+ text(ctx, ` ${name} ${entry.version} · ${entry.date}`, { bold: true, color: THEME.head }),
+ ...shown.map(change => text(ctx, ` ${MARK[change.kind].padEnd(10)} ${change.text}`, colorOf(change.kind))),
+ ...(rest > 0 ? [text(ctx, ` … ${rest} more in the full notes`, { dimColor: true })] : []),
+ ]
+}
+
+const okLogs = (logs: readonly Log[]): (Log & { result: { ok: true; entries: ChangeEntry[]; truncated: boolean } })[] => logs.filter((log): log is Log & { result: { ok: true; entries: ChangeEntry[]; truncated: boolean } } => log.result.ok)
+
+/** The entries the person has not looked at: those past the version last seen (a plugin first seen shows its newest entry only). */
+function freshOf(log: ReturnType<typeof okLogs>[number], before: Record<string, string> | null): ChangeEntry[] {
+ if (before === null) return []
+
+ const seen = before[log.name]
+
+ return seen === undefined ? log.result.entries.slice(0, 1) : entriesAfter(log.result.entries, seen)
+}
+
+const reasonOf = (log: Log): string => (log.result.ok ? '' : log.result.reason === 'garbled' || log.result.reason === 'empty' ? 'its CHANGELOG.md is not in the expected format' : log.result.reason === 'too-large' ? 'its CHANGELOG.md is too large to read' : log.result.reason === 'unreadable' ? 'its CHANGELOG.md could not be read' : 'no CHANGELOG.md bundled')
+
+export function whatsnewView(ctx: Ctx): RenderElement {
+ const { state } = ctx
+ const wn = state.whatsnew
+ const ok = okLogs(wn.logs)
+ const fresh: Shown[] = ok.flatMap(log => freshOf(log, wn.before).map(entry => ({ name: log.name, entry }))).sort(newest)
+ const freshKeys = new Set(fresh.map(item => `${item.name}@${item.entry.version}`))
+ const earlier: Shown[] = ok.flatMap(log => log.result.entries.filter(entry => !freshKeys.has(`${log.name}@${entry.version}`)).slice(0, 2).map(entry => ({ name: log.name, entry }))).sort(newest)
+ const pins = pinnedOf(state)
+ const missing = wn.logs.filter(log => !log.result.ok)
+ const toastOn = wn.rec?.toast !== false
+ const parts: RenderElement[] = [rule(ctx, 'What’s new', `${CONSOLE_NAME} ${CONSOLE_VERSION}`)]
+
+ parts.push(
+ state.updateAvailable === ''
+ ? text(ctx, ` no newer ${CONSOLE_NAME} is known${state.updateNote === '' ? '' : `: ${tidy(state.updateNote, 100)}`}`, { dimColor: true })
+ : col(ctx, [text(ctx, ` ⬆ ${CONSOLE_NAME} ${tidy(state.updateAvailable, 20)} is published (you run ${CONSOLE_VERSION}); Settings → Updates installs it.`, { color: THEME.warn }), text(ctx, ` Its notes are not fetched here: read them at ${RELEASES_URL}`, { dimColor: true })], 'whatsnew-update'),
+ row(
+ ctx,
+ [
+ button(ctx, 'whatsnew-check', '↻ check for an update now', () => ctx.act.checkUpdates()),
+ text(ctx, ' '),
+ button(ctx, 'whatsnew-toast', `${toastOn ? '☑' : '☐'} toast when something new lands`, () => ctx.act.whatsnew.toggleToast()),
+ ],
+ 'whatsnew-actions',
+ ),
+ )
+
+ if (pins.length > 0) {
+ const pinRows = pins.flatMap(pin => [
+ row(ctx, [text(ctx, ` ‼ ${pin.name} ${pin.version}`, { bold: true, color: THEME.bad }), text(ctx, ' '), button(ctx, `whatsnew-dismiss-${pin.name}-${pin.version}`, '✕ dismiss', () => ctx.act.whatsnew.dismiss(pin.key))], `whatsnew-pin-${pin.key}`),
+ ...(pin.texts.length === 0 ? [text(ctx, ' breaking changes: see the full notes', { dimColor: true })] : pin.texts.slice(0, PER_ENTRY).map(words => text(ctx, ` ${words}`, { color: THEME.bad }))),
+ ])
+
+ parts.push(...section(ctx, 'pinned', 'Breaking changes', `${pins.length} pinned until you dismiss`, [...pinRows, ...(pins.length > 1 ? [button(ctx, 'whatsnew-dismiss-all', '✕ dismiss all', () => ctx.act.whatsnew.dismissAll())] : [])]))
+ }
+
+ if (wn.isLoading && wn.logs.length === 0) parts.push(text(ctx, ' reading the changelogs…', { dimColor: true }))
+ else if (ok.length === 0) parts.push(text(ctx, ` No installed ruflo plugin ships a readable CHANGELOG.md yet (${missing.length} checked). Versions published from now on include one.`, { color: THEME.warn }))
+
+ if (ok.length > 0) {
+ parts.push(...section(ctx, 'new', 'Since you last looked', fresh.length === 0 ? 'nothing new' : `${fresh.length} update${fresh.length === 1 ? '' : 's'}`, fresh.length === 0 ? [text(ctx, ' nothing has changed since you last opened this page', { dimColor: true })] : fresh.slice(0, MAX_NEW).flatMap(item => entryRows(ctx, item.name, item.entry))))
+ parts.push(text(ctx, ` ${'─'.repeat(6)} you last looked here ${'─'.repeat(6)}`, { dimColor: true }))
+ parts.push(...section(ctx, 'earlier', 'Earlier', `${Math.min(earlier.length, MAX_EARLIER)} shown`, earlier.slice(0, MAX_EARLIER).flatMap(item => entryRows(ctx, item.name, item.entry)), true))
+ parts.push(...section(ctx, 'notes', 'Full notes', 'files and addresses, as text', ok.slice(0, 60).flatMap(log => [text(ctx, ` ${log.name} ${log.version}${log.result.truncated ? ' (long: the page shows the newest entries)' : ''}`, { bold: true }), text(ctx, ` ${log.path === null ? 'bundled with the plugin' : `${tidy(log.path, 140)}/CHANGELOG.md`}`, { dimColor: true }), text(ctx, ` ${NOTES_URL(log.name)}`, { dimColor: true })]), false))
+ }
+
+ if (missing.length > 0) parts.push(...section(ctx, 'missing', 'Without notes', `${missing.length} plugin${missing.length === 1 ? '' : 's'}`, missing.slice(0, 30).map(log => text(ctx, ` ${log.name} ${log.version}: ${reasonOf(log)}`, { dimColor: true })), false))
+
+ return col(ctx, parts, 'whatsnew')
+}
diff --git a/plugins/ruflo-console/hooks/whatsnew.ts b/plugins/ruflo-console/hooks/whatsnew.ts
new file mode 100644
index 0000000000..aad3e31c2a
--- /dev/null
+++ b/plugins/ruflo-console/hooks/whatsnew.ts
@@ -0,0 +1,292 @@
+/**
+ * What's new (ADR-478), the logic: which installed ruflo plugins moved since the person last looked, the bundled CHANGELOG.md of each
+ * (read only when the page opens, local files, no network), the breaking changes pinned until dismissed, and the one info toast per new
+ * version. The page that draws it is views/whatsnew.ts. Every read and write may fail; none throws.
+ *
+ * What is remembered (one JSON string under the plugin-store key `whatsnew`): the version of each plugin the person last looked at
+ * (`seen`), the versions already toasted, the breaking entries still pinned and the ones dismissed, and whether to toast. Nothing else.
+ * With no record yet, the first sight of the installed versions is the baseline: nothing is new, nothing is toasted.
+ */
+import { compareVersions, entriesAfter, parseChangelog, semverOf, type ChangeEntry, type ParsedChangelog } from './data/changelog'
+import { safeInstallPath } from './data/cost-ledger'
+import { readBounded, type ReadCache } from './data/files'
+import { RUFLO_MARKET } from './data/snapshot'
+import type { Host } from './host'
+import type { State } from './state'
+import { tidy } from './toast-policy'
+import { CONSOLE_VERSION } from './version'
+
+export const WHATSNEW_KEY = 'whatsnew'
+export const CONSOLE_NAME = 'ruflo-console'
+/** Where a person reads the whole file when this page shows only headlines. */
+export const NOTES_URL = (name: string): string => `https://github.com/ruvnet/ruflo/blob/main/plugins/${name}/CHANGELOG.md`
+export const RELEASES_URL = 'https://github.com/ruvnet/ruflo/releases'
+
+const MAX_PLUGINS = 60
+const MAX_RECORD = 200
+const FILE_MAX = 256 * 1024
+const NAME = /^[A-Za-z0-9._-]{1,80}$/
+
+export type WhatsRecord = { seen: Record<string, string>; toasted: Record<string, string>; pinned: string[]; dismissed: string[]; toast: boolean }
+export type Row = { name: string; version: string; path: string | null }
+export type Log = { name: string; version: string; path: string | null; result: ParsedChangelog | { ok: false; reason: 'missing' | 'too-large' | 'unreadable' } }
+
+export type WhatsNewState = {
+ /** The store has been read (until then nothing is new and nothing is toasted). */
+ hydrated: boolean
+ /** The record; null while the store has none (the first sight of the installed versions then becomes the baseline). */
+ rec: WhatsRecord | null
+ /** The page is the open view. */
+ isOpen: boolean
+ /** The versions seen before this opening: the divider's place. Kept while the page stays open. */
+ before: Record<string, string> | null
+ logs: Log[]
+ /** A read of the files is under way, or none has finished since the page opened. */
+ isLoading: boolean
+ loadedAtMs: number
+ cache: ReadCache
+}
+
+export const newWhatsNew = (): WhatsNewState => ({ hydrated: false, rec: null, isOpen: false, before: null, logs: [], isLoading: false, loadedAtMs: 0, cache: new Map() })
+
+export const emptyRecord = (): WhatsRecord => ({ seen: {}, toasted: {}, pinned: [], dismissed: [], toast: true })
+
+/** A record that takes the installed versions as already seen and toasted: the first sight, so nothing is new. */
+export const baselineOf = (rows: readonly { name: string; version: string }[]): WhatsRecord => ({ ...emptyRecord(), seen: Object.fromEntries(rows.map(row => [row.name, row.version])), toasted: Object.fromEntries(rows.map(row => [row.name, row.version])) })
+
+function versions(value: unknown): Record<string, string> {
+ const out: Record<string, string> = {}
+
+ if (typeof value !== 'object' || value === null || Array.isArray(value)) return out
+
+ for (const [name, version] of Object.entries(value).slice(0, MAX_RECORD)) if (NAME.test(name) && typeof version === 'string' && semverOf(version) !== null) out[name] = version
+
+ return out
+}
+
+const keys = (value: unknown): string[] => (Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === 'string' && /^[A-Za-z0-9._-]{1,80}@\d{1,4}\.\d{1,4}\.\d{1,4}$/.test(entry)).slice(-MAX_RECORD) : [])
+
+/** The record from what the store held: anything unreadable is null (no record). */
+export function parseRecord(value: unknown): WhatsRecord | null {
+ if (typeof value !== 'string' || value.length > 64 * 1024) return null
+
+ try {
+ const parsed = JSON.parse(value) as Record<string, unknown>
+
+ if (typeof parsed !== 'object' || parsed === null) return null
+
+ return { seen: versions(parsed.seen), toasted: versions(parsed.toasted), pinned: keys(parsed.pinned), dismissed: keys(parsed.dismissed), toast: parsed.toast !== false }
+ } catch {
+ return null
+ }
+}
+
+export const encodeRecord = (rec: WhatsRecord): string => JSON.stringify({ v: 1, seen: rec.seen, toasted: rec.toasted, pinned: rec.pinned.slice(-MAX_RECORD), dismissed: rec.dismissed.slice(-MAX_RECORD), toast: rec.toast })
+
+/** The ruflo plugins installed here, the console at the version in its own header or newer. Capped; names are validated. */
+export function rowsOf(state: Pick<State, 'snapshot'>, pluginRoot: string | null = null): Row[] {
+ const installed = state.snapshot?.plugins.installed ?? []
+ const rows: Row[] = installed
+ .filter(entry => entry.marketplace === RUFLO_MARKET && NAME.test(entry.name) && semverOf(entry.version) !== null)
+ .slice(0, MAX_PLUGINS)
+ .map(entry => ({ name: entry.name, version: entry.version, path: safeInstallPath(entry.installPath) ?? null }))
+ const own = rows.find(row => row.name === CONSOLE_NAME)
+
+ // The console is always listed: it is running, even where no install record names it (a development checkout).
+ if (own === undefined) rows.unshift({ name: CONSOLE_NAME, version: CONSOLE_VERSION, path: pluginRoot !== null ? (safeInstallPath(pluginRoot) ?? null) : null })
+ else if (compareVersions(CONSOLE_VERSION, own.version) > 0) own.version = CONSOLE_VERSION
+
+ return rows
+}
+
+/** The plugins whose installed version is newer than the one last looked at (a plugin never looked at counts once, at its version). */
+export function unseenRows(rows: readonly Row[], rec: WhatsRecord | null): Row[] {
+ if (rec === null) return []
+
+ return rows.filter(row => rec.seen[row.name] === undefined || compareVersions(row.version, rec.seen[row.name] as string) > 0)
+}
+
+/** Whether the page has anything the person has not looked at: the nav's and the menu's "new" marker. */
+export const hasUnseen = (state: Pick<State, 'snapshot' | 'whatsnew'>): boolean => state.whatsnew.hydrated && unseenRows(rowsOf(state), state.whatsnew.rec).length > 0
+
+/** The line a toast says: the first names, then a count. */
+export function toastLine(rows: readonly Row[]): string {
+ const named = rows.slice(0, 2).map(row => `${row.name} ${row.version}`)
+ const rest = rows.length - named.length
+
+ return tidy(`What's new: ${named.join(', ')}${rest > 0 ? ` and ${rest} more` : ''} (TOOLS → What's new)`, 118)
+}
+
+const persist = (state: State, host: Pick<Host, 'storeSet'>): void => {
+ if (state.whatsnew.rec !== null) void host.storeSet(WHATSNEW_KEY, encodeRecord(state.whatsnew.rec)).catch(() => undefined)
+}
+
+/** Reads the record once per session. */
+export async function hydrateWhatsNew(state: State, host: Pick<Host, 'storeGet' | 'invalidate'>): Promise<void> {
+ if (state.whatsnew.hydrated) return
+
+ state.whatsnew.rec = await host.storeGet(WHATSNEW_KEY).then(parseRecord, () => null)
+ state.whatsnew.hydrated = true
+ host.invalidate()
+}
+
+/**
+ * Called from the controller after each disk read, and cheap when nothing moved. Takes the baseline on first sight; while the page is open
+ * a version that lands is looked at at once; otherwise one info toast per version not yet toasted (never again for the same one).
+ */
+export function syncWhatsNew(state: State, host: Pick<Host, 'storeSet' | 'toast' | 'invalidate' | 'pluginRoot'>): void {
+ const wn = state.whatsnew
+
+ if (!wn.hydrated || state.snapshot === null) return
+
+ const rows = rowsOf(state, host.pluginRoot)
+
+ if (wn.rec === null) {
+ wn.rec = baselineOf(rows)
+ persist(state, host)
+
+ return
+ }
+
+ const unseen = unseenRows(rows, wn.rec)
+
+ if (unseen.length === 0) return
+
+ if (wn.isOpen) {
+ for (const row of unseen) wn.rec.seen[row.name] = row.version
+ persist(state, host)
+ host.invalidate()
+
+ return
+ }
+
+ const fresh = unseen.filter(row => wn.rec !== null && (wn.rec.toasted[row.name] === undefined || compareVersions(row.version, wn.rec.toasted[row.name] as string) > 0))
+
+ if (fresh.length === 0) return
+
+ for (const row of fresh) wn.rec.toasted[row.name] = row.version
+ persist(state, host)
+ if (wn.rec.toast && state.isInteractive) host.toast(toastLine(fresh), 9_000, 'info')
+ host.invalidate()
+}
+
+const breaking = (entry: ChangeEntry): boolean => entry.changes.some(change => change.kind === 'breaking')
+
+/** Reads each plugin's bundled CHANGELOG.md (regular files only, size-bounded) and parses it. */
+export async function readLogs(host: Pick<Host, 'fs'>, cache: ReadCache, rows: readonly Row[]): Promise<Log[]> {
+ const one = async (row: Row): Promise<Log> => {
+ if (row.path === null) return { ...row, result: { ok: false, reason: 'missing' } }
+
+ const read = await readBounded(host.fs, cache, `${row.path.replace(/\/+$/, '')}/CHANGELOG.md`, FILE_MAX, true).catch(() => null)
+
+ if (read === null) return { ...row, result: { ok: false, reason: 'unreadable' } }
+ if (read.text === null) return { ...row, result: { ok: false, reason: read.reason === 'too-large' ? 'too-large' : read.reason === 'missing' ? 'missing' : 'unreadable' } }
+
+ return { ...row, result: parseChangelog(read.text) }
+ }
+ const out: Log[] = []
+
+ for (let i = 0; i < rows.length; i += 8) out.push(...(await Promise.all(rows.slice(i, i + 8).map(one))))
+
+ return out
+}
+
+/**
+ * The page opens: the divider stays where the last look left it, the files are read, any breaking change among the new entries is pinned
+ * (and stays pinned across sessions until dismissed), and everything counts as looked at. Local reads only.
+ */
+export async function openWhatsNew(state: State, host: Pick<Host, 'fs' | 'storeGet' | 'storeSet' | 'invalidate' | 'pluginRoot'>): Promise<void> {
+ const wn = state.whatsnew
+
+ if (wn.isOpen) return
+
+ wn.isOpen = true
+ wn.isLoading = true
+ host.invalidate()
+ await hydrateWhatsNew(state, host)
+
+ const rows = rowsOf(state, host.pluginRoot)
+
+ if (wn.rec === null) wn.rec = baselineOf(rows)
+
+ wn.before = { ...wn.rec.seen }
+
+ const before = wn.before
+ const rec = wn.rec
+ const logs = await readLogs(host, wn.cache, rows)
+
+ if (!wn.isOpen) return
+
+ wn.logs = logs
+
+ for (const log of logs) {
+ if (!log.result.ok) continue
+
+ for (const entry of entriesAfter(log.result.entries, before[log.name])) {
+ const key = `${log.name}@${entry.version}`
+
+ if (breaking(entry) && !rec.pinned.includes(key) && !rec.dismissed.includes(key) && before[log.name] !== undefined) rec.pinned.push(key)
+ }
+ }
+
+ for (const row of rows) rec.seen[row.name] = row.version
+ wn.isLoading = false
+ wn.loadedAtMs = Date.now()
+ persist(state, host as Pick<Host, 'storeSet'>)
+ host.invalidate()
+}
+
+/** The page is left: the divider is forgotten. */
+export function closeWhatsNew(state: State): void {
+ state.whatsnew.isOpen = false
+ state.whatsnew.before = null
+}
+
+/** The breaking changes still pinned: from the record, with the entry's words when its file has been read this session. */
+export function pinnedOf(state: Pick<State, 'whatsnew'>): { key: string; name: string; version: string; texts: string[] }[] {
+ const { rec, logs } = state.whatsnew
+
+ if (rec === null) return []
+
+ return rec.pinned
+ .filter(key => !rec.dismissed.includes(key))
+ .map(key => {
+ const [name = '', version = ''] = key.split('@')
+ const entry = logs.find(log => log.name === name && log.result.ok)?.result
+ const found = entry !== undefined && entry.ok ? entry.entries.find(each => each.version === version) : undefined
+
+ return { key, name, version, texts: found === undefined ? [] : found.changes.filter(change => change.kind === 'breaking').map(change => change.text) }
+ })
+ .slice(0, 20)
+}
+
+export type WhatsNewActions = { dismiss: (key: string) => void; dismissAll: () => void; toggleToast: () => void }
+
+/** Dismissing is remembered: the entry is not pinned again. */
+export function whatsnewActions(state: State, host: Pick<Host, 'storeSet' | 'invalidate' | 'pluginRoot'>): WhatsNewActions {
+ const save = () => {
+ persist(state, host)
+ host.invalidate()
+ }
+ const dismiss = (key: string) => {
+ const rec = state.whatsnew.rec
+
+ if (rec === null) return
+
+ rec.pinned = rec.pinned.filter(each => each !== key)
+ if (!rec.dismissed.includes(key)) rec.dismissed.push(key)
+ save()
+ }
+
+ return {
+ dismiss,
+ dismissAll: () => {
+ for (const pin of pinnedOf(state)) dismiss(pin.key)
+ },
+ toggleToast: () => {
+ state.whatsnew.rec ??= baselineOf(rowsOf(state, host.pluginRoot))
+ state.whatsnew.rec.toast = !state.whatsnew.rec.toast
+ save()
+ },
+ }
+}
diff --git a/plugins/ruflo-console/scripts/smoke.sh b/plugins/ruflo-console/scripts/smoke.sh
index c6b865675b..570d03a649 100755
--- a/plugins/ruflo-console/scripts/smoke.sh
+++ b/plugins/ruflo-console/scripts/smoke.sh
@@ -11,9 +11,9 @@ step() { printf "→ %s ... " "$1"; }
ok() { printf "PASS\n"; PASS=$((PASS+1)); }
bad() { printf "FAIL: %s\n" "$1"; FAIL=$((FAIL+1)); }
-step "1. plugin.json declares ruflo-console 0.37.0"
+step "1. plugin.json declares ruflo-console 0.38.0"
grep -q '"name": "ruflo-console"' "$ROOT/.claude-plugin/plugin.json" \
- && grep -q '"version": "0.37.0"' "$ROOT/.claude-plugin/plugin.json" && ok || bad "name/version"
+ && grep -q '"version": "0.38.0"' "$ROOT/.claude-plugin/plugin.json" && ok || bad "name/version"
step "2. hooks.json names exactly one module and no classic hook commands"
grep -q '"modules": \["./register.ts"\]' "$HOOKS/hooks.json" && ! grep -q '"command"' "$HOOKS/hooks.json" \
@@ -112,5 +112,10 @@ if [[ ! -f "$ROOT/../ruflo-mods/hooks/toast/policy.ts" ]]; then printf "SKIP (ru
elif cmp -s "$ROOT/../ruflo-mods/hooks/toast/policy.ts" "$HOOKS/toast-policy.ts"; then ok
else bad "differs from ruflo-mods/hooks/toast/policy.ts: node scripts/sync-toast-policy.mjs"; fi
+step "18. CHANGELOG.md has an entry for the manifest version, and the What's new page makes no request of its own (ADR-478)"
+version=$(sed -n 's/^ "version": "\([0-9.]*\)".*/\1/p' "$ROOT/.claude-plugin/plugin.json" | head -1)
+if grep -qE "^## ${version//./\\.} [—–-] [0-9]{4}-[0-9]{2}-[0-9]{2}\s*$" "$ROOT/CHANGELOG.md" 2>/dev/null \
+ && ! grep -qE "fetchText|httpSend|\\.run\(|spawn" "$HOOKS/whatsnew.ts" "$HOOKS/views/whatsnew.ts" "$HOOKS/data/changelog.ts"; then ok; else bad "CHANGELOG.md lacks ## $version, or whatsnew code reaches the network"; fi
+
printf "\n%d passed, %d failed\n" "$PASS" "$FAIL"
[[ $FAIL -eq 0 ]]
diff --git a/plugins/ruflo-console/tests/boot-cyber.spec.ts b/plugins/ruflo-console/tests/boot-cyber.spec.ts
index 0094c9d1bd..d21deeee2c 100644
--- a/plugins/ruflo-console/tests/boot-cyber.spec.ts
+++ b/plugins/ruflo-console/tests/boot-cyber.spec.ts
@@ -59,7 +59,7 @@ describe('the cyberpunk log', () => {
expect(text).toContain('RUV.NET // RUVECTOR CONSTELLATION')
expect(text).toContain('rUv · ruflo v0.26.0 · abc123')
expect(text).toContain('ruvector')
- expect(text).toMatch(/\[WARN\] READY · 29 of 29 areas verified · \d+ stars? dark/)
+ expect(text).toMatch(/\[WARN\] READY · 30 of 30 areas verified · \d+ stars? dark/)
expect(text).not.toContain('ALL STARS ALIGNED')
})
@@ -76,7 +76,7 @@ describe('the cyberpunk log', () => {
const failed = textOf(bootPicture('p', 90, 6000, 10, 10, rowsFor, failing, bootFacts(lit, '1', '')))
expect(failed).not.toContain('ALL STARS ALIGNED')
- expect(failed).toMatch(/\[FAIL\] READY · 28 of 29 areas verified · 1 failed/)
+ expect(failed).toMatch(/\[FAIL\] READY · 29 of 30 areas verified · 1 failed/)
})
it('shows the easter egg only in its window, and it decodes to rUv', () => {
@@ -97,7 +97,7 @@ describe('the cyberpunk log', () => {
it('falls back to the plain log in a narrow or short pane', () => {
const facts = bootFacts(withPlugins([]), '1', '')
- expect(textOf(bootPicture('p', 44, 6000, 10, 10, rowsFor, allOk, facts))).toContain('[ OK ] READY 29 of 29 areas verified')
+ expect(textOf(bootPicture('p', 44, 6000, 10, 10, rowsFor, allOk, facts))).toContain('[ OK ] READY 30 of 30 areas verified')
expect(textOf(bootPicture('p', 90, 6000, 10, 10, BOOT_ROWS + 6, allOk, facts))).not.toContain('RUV.NET')
})
})
diff --git a/plugins/ruflo-console/tests/nav.spec.ts b/plugins/ruflo-console/tests/nav.spec.ts
index e027e62712..0d2c077ac3 100644
--- a/plugins/ruflo-console/tests/nav.spec.ts
+++ b/plugins/ruflo-console/tests/nav.spec.ts
@@ -12,7 +12,7 @@ describe('main nav hotkeys', () => {
expect(keys.every(key => /^[0-9a-z]$/.test(key))).toBe(true)
expect(new Set(keys).size).toBe(keys.length)
- expect(VIEWS.filter(view => view.key === '').map(view => view.id)).toEqual(['workflows', 'room', 'sandbox'])
+ expect(VIEWS.filter(view => view.key === '').map(view => view.id)).toEqual(['workflows', 'room', 'sandbox', 'whatsnew'])
})
it('none takes a key the footer, the confirm row, scrolling or the menu prompt owns', () => {
diff --git a/plugins/ruflo-console/tests/whatsnew.spec.ts b/plugins/ruflo-console/tests/whatsnew.spec.ts
new file mode 100644
index 0000000000..2cb2ee5990
--- /dev/null
+++ b/plugins/ruflo-console/tests/whatsnew.spec.ts
@@ -0,0 +1,453 @@
+/**
+ * What's new (ADR-478): the changelog parser and its bounds, the record of what was looked at, the marker, the one toast per new
+ * version, the pinned breaking changes, and the page drawn from real state in both looks, with hostile files. No host, no network:
+ * the fake host counts every fetch so the page is shown to make none. Run with
+ * npx vitest run plugins/ruflo-console/tests/whatsnew.spec.ts
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { afterAll, describe, expect, it } from 'vitest'
+
+import { compareVersions, entriesAfter, LIMITS, parseChangelog, semverOf } from '../hooks/data/changelog'
+import { newState, type State } from '../hooks/state'
+import { setLook, type Actions } from '../hooks/views/common'
+import { viewText } from '../hooks/views/pane'
+import { CONSOLE_VERSION } from '../hooks/version'
+import { baselineOf, encodeRecord, hasUnseen, hydrateWhatsNew, openWhatsNew, parseRecord, pinnedOf, readLogs, rowsOf, syncWhatsNew, toastLine, unseenRows, whatsnewActions, WHATSNEW_KEY } from '../hooks/whatsnew'
+
+const ESC = '\u001b'
+const file = (...blocks: string[]) => blocks.join('\n')
+const entry = (version: string, date: string, ...bullets: string[]) => `## ${version} — ${date}\n${bullets.map(bullet => `- ${bullet}`).join('\n')}\n`
+
+afterAll(() => setLook('plain'))
+
+describe('the changelog format', () => {
+ it('reads versions newest first whatever the file order, with the kind of each bullet', () => {
+ const parsed = parseChangelog(file(entry('0.2.0', '2026-09-01', 'fix: a', 'feat: b'), entry('0.10.0', '2026-10-01', 'breaking: c', 'chore: d'), entry('0.9.1', '2026-09-20', 'fix: e')))
+
+ expect(parsed.ok).toBe(true)
+ if (!parsed.ok) return
+ expect(parsed.entries.map(each => each.version)).toEqual(['0.10.0', '0.9.1', '0.2.0'])
+ expect(parsed.entries[0]?.changes).toEqual([{ kind: 'breaking', text: 'c' }, { kind: 'chore', text: 'd' }])
+ expect(parsed.entries[0]?.date).toBe('2026-10-01')
+ expect(parsed.truncated).toBe(false)
+ })
+
+ it('takes an em dash, an en dash or a hyphen in the header, CRLF line ends and * bullets; anything else is ignored', () => {
+ const parsed = parseChangelog('# Changelog\r\nintro text\r\n## 1.0.0 – 2026-01-02\r\n* feat: star\r\n- note: not a kind\r\n- fix:\r\n- fix: kept\r\n## 0.9.0 - 2025-12-31\r\n- chore: old\r\n## v0.8.0 — 2025-12-01\r\n- fix: no v allowed\r\n## 0.7.0-rc1 — 2025-11-01\r\n- fix: not a plain semver\r\n')
+
+ expect(parsed).toMatchObject({ ok: true })
+ if (!parsed.ok) return
+ expect(parsed.entries.map(each => each.version)).toEqual(['1.0.0', '0.9.0'])
+ expect(parsed.entries[0]?.changes.map(change => change.text)).toEqual(['star', 'kept'])
+ })
+
+ it('a repeated version and an impossible date start nothing, and their bullets belong to no entry', () => {
+ const parsed = parseChangelog(file(entry('1.0.0', '2026-01-02', 'fix: first'), entry('1.0.0', '2026-01-03', 'fix: second'), entry('0.9.0', '2026-13-40', 'fix: third')))
+
+ expect(parsed).toMatchObject({ ok: true, truncated: true })
+ if (!parsed.ok) return
+ expect(parsed.entries).toHaveLength(1)
+ expect(parsed.entries[0]?.changes).toEqual([{ kind: 'fix', text: 'first' }])
+ })
+
+ it('a month or day out of range starts no entry', () => {
+ for (const date of ['2026-00-10', '2026-13-01', '2026-12-32', '2026-01-00']) expect(parseChangelog(entry('1.0.0', date, 'fix: x'))).toEqual({ ok: false, reason: 'garbled' })
+ expect(parseChangelog(entry('1.0.0', '2026-12-31', 'fix: x'))).toMatchObject({ ok: true })
+ })
+
+ it('a file with no entry is garbled, an empty or non-text one is empty: a reason, never a throw', () => {
+ expect(parseChangelog('just some prose\n- fix: but no header')).toEqual({ ok: false, reason: 'garbled' })
+ expect(parseChangelog(' \n')).toEqual({ ok: false, reason: 'empty' })
+ expect(parseChangelog(undefined)).toEqual({ ok: false, reason: 'empty' })
+ expect(parseChangelog({ not: 'text' })).toEqual({ ok: false, reason: 'empty' })
+ expect(parseChangelog('\u0000\u0001\u0002 binary')).toEqual({ ok: false, reason: 'garbled' })
+ })
+
+ it('compares versions as numbers, and a non-version sorts before any version', () => {
+ expect(compareVersions('0.10.0', '0.9.9')).toBeGreaterThan(0)
+ expect(compareVersions('1.0.0', '1.0.0')).toBe(0)
+ expect(compareVersions('abc', '0.0.1')).toBeLessThan(0)
+ expect(semverOf('1.2.3-rc1')).toBeNull()
+ expect(semverOf('12345.0.0')).toBeNull()
+ expect(entriesAfter([{ version: '0.3.0', date: '', changes: [], more: 0 }, { version: '0.2.0', date: '', changes: [], more: 0 }], '0.2.0').map(each => each.version)).toEqual(['0.3.0'])
+ })
+})
+
+describe('the bounds', () => {
+ it('10,000 entries keep the newest 40, and the file is said to be cut', () => {
+ const big = Array.from({ length: 10_000 }, (_, i) => entry(`0.${i}.0`, '2026-01-01', 'fix: x')).join('')
+ const parsed = parseChangelog(big)
+
+ expect(parsed.ok).toBe(true)
+ if (!parsed.ok) return
+ expect(parsed.entries.length).toBeLessThanOrEqual(LIMITS.entries)
+ expect(parsed.truncated).toBe(true)
+ })
+
+ it('bullets past the cap are counted, not kept; a line is cut to the line limit', () => {
+ const many = Array.from({ length: 30 }, (_, i) => `fix: item ${i}`)
+ const parsed = parseChangelog(file(entry('1.0.0', '2026-01-01', `feat: ${'word '.repeat(1_000)}`, ...many)))
+
+ expect(parsed.ok).toBe(true)
+ if (!parsed.ok) return
+ expect(parsed.entries[0]?.changes).toHaveLength(LIMITS.changes)
+ expect(parsed.entries[0]?.more).toBe(31 - LIMITS.changes)
+ expect(parsed.entries[0]?.changes[0]?.text).toHaveLength(LIMITS.line)
+ expect(parsed.entries[0]?.changes.every(change => change.text.length <= LIMITS.line)).toBe(true)
+ })
+
+ it('a megabyte of file, a megabyte of one line and a million-step header all finish quickly', () => {
+ const started = Date.now()
+
+ parseChangelog(`${entry('1.0.0', '2026-01-01', 'fix: a')}${'x'.repeat(1_000_000)}`)
+ parseChangelog(`## 1.0.0 — 2026-01-01\n- fix: ${' '.repeat(1_000_000)}end`)
+ parseChangelog(`## ${'1.'.repeat(500_000)} — 2026-01-01\n- fix: a`)
+ parseChangelog(`- fix: ${'a'.repeat(200_000)}\n`.repeat(30))
+ parseChangelog('\n'.repeat(1_000_000))
+ expect(Date.now() - started).toBeLessThan(1_500)
+ })
+
+ it('lines past the line limit are not parsed either, and the cut is said', () => {
+ const parsed = parseChangelog(`${entry('2.0.0', '2026-01-01', 'fix: early')}${'x\n'.repeat(LIMITS.lines + 500)}${entry('9.9.9', '2026-01-01', 'fix: late')}`)
+
+ expect(parsed.ok && parsed.entries.map(each => each.version)).toEqual(['2.0.0'])
+ expect(parsed.ok && parsed.truncated).toBe(true)
+ })
+
+ it('text past the byte limit is not parsed, so an entry placed beyond it never appears', () => {
+ const parsed = parseChangelog(`${entry('2.0.0', '2026-01-01', 'fix: early')}${'x'.repeat(LIMITS.bytes)}\n${entry('9.9.9', '2026-01-01', 'fix: late')}`)
+
+ expect(parsed.ok && parsed.entries.map(each => each.version)).toEqual(['2.0.0'])
+ expect(parsed.ok && parsed.truncated).toBe(true)
+ })
+})
+
+describe('hostile text', () => {
+ const BAD = /[\u001b\u0007\u009b\u009d‪-‮⁠-؜-​-‏\u{e0000}-\u{e0fff}\u0000-\u0008\u000e-\u001f]/u
+
+ it('escape sequences, OSC links and clipboard writes, bidi and tag characters, and control characters never survive', () => {
+ const lines = [`${ESC}]8;;https://evil.example${ESC}\\click${ESC}]8;;${ESC}\\`, `${ESC}]52;c;ZXZpbA==\u0007clip`, `${ESC}[31mred${ESC}[0m`, '‮exe.txt', 'a\u0000b\u0001c', '\u{e0041}tag', '⁦iso⁩', 'zero​width']
+ const parsed = parseChangelog(entry('1.0.0', '2026-01-01', ...lines.map(line => `fix: ${line}`)))
+
+ expect(parsed.ok).toBe(true)
+ if (!parsed.ok) return
+ for (const change of parsed.entries[0]?.changes ?? []) expect(change.text).not.toMatch(BAD)
+ })
+
+ it('credentials are masked, and one split by a control character is still one credential', () => {
+ const parsed = parseChangelog(entry('1.0.0', '2026-01-01', 'fix: leaked sk-ant-api03-AAAAAAAAAAAAAAAAAAAA here', 'fix: token=hunter2secret', `fix: ghp_AAAAAAAA\u0000BBBBBBBBBBBB`, 'fix: Authorization: Bearer abcdefghijklmnop', 'fix: mail me at [email protected] from /home/ruv/secret'))
+
+ expect(parsed.ok).toBe(true)
+ if (!parsed.ok) return
+
+ const text = parsed.entries[0]?.changes.map(change => change.text).join('\n') ?? ''
+
+ expect(text).not.toMatch(/sk-ant|hunter2|ghp_|BBBBBBBB|abcdefghijklmnop|someone@example|\/home\/ruv/)
+ expect(text).toContain('‹masked›')
+ })
+
+ it('markdown and html stay plain characters: nothing here is rendered as anything but text', () => {
+ const parsed = parseChangelog(entry('1.0.0', '2026-01-01', 'fix: [click](https://evil.example) <script>alert(1)</script> **bold**'))
+
+ expect(parsed.ok && parsed.entries[0]?.changes[0]?.text).toBe('[click](https://evil.example) <script>alert(1)</script> **bold**')
+ })
+})
+
+/** A file system holding `files`, as the host's `fs` answers (a regular file each). */
+const fsOf = (files: Record<string, string>, links: string[] = []) => ({
+ read: async (path: string) => files[path] ?? Promise.reject(new Error('ENOENT')),
+ stat: async (path: string) => (files[path] === undefined ? Promise.reject(new Error('ENOENT')) : { kind: 'file', size: (files[path] as string).length, mtimeMs: 1, isLink: links.includes(path) }),
+ list: async () => [],
+})
+
+type Fake = ReturnType<typeof fake>
+
+function fake(files: Record<string, string> = {}, stored: Record<string, unknown> = {}, links: string[] = []) {
+ const store = new Map<string, unknown>(Object.entries(stored))
+ const log = { toasts: [] as { text: string; level: string | undefined }[], fetches: 0, invalidations: 0 }
+ const host = {
+ fs: fsOf(files, links),
+ storeGet: async (key: string) => store.get(key),
+ storeSet: async (key: string, value: unknown) => void store.set(key, value),
+ toast: (text: string, _ms?: number, level?: string) => void log.toasts.push({ text, level }),
+ invalidate: () => void (log.invalidations += 1),
+ fetchText: async () => (log.fetches += 1, { ok: true, status: 200, text: '' }),
+ run: async () => (log.fetches += 1, { exitCode: 0, stdout: '', stderr: '' }),
+ pluginRoot: '/plugin',
+ }
+
+ return { host, store, log }
+}
+
+const install = (state: State, plugins: Record<string, string>) => {
+ state.snapshot = { plugins: { installed: Object.entries(plugins).map(([name, version]) => ({ id: `${name}@ruflo`, name, marketplace: 'ruflo', version, scope: 'user', installPath: `/cache/${name}/${version}` })) } } as never
+}
+
+const stateWith = (plugins: Record<string, string>): State => {
+ const state = newState({})
+
+ install(state, plugins)
+ state.isInteractive = true
+
+ return state
+}
+
+const record = (fakeHost: Fake) => parseRecord(fakeHost.store.get(WHATSNEW_KEY))
+
+describe('what was looked at', () => {
+ it('the record survives a round trip, and anything unreadable is no record', () => {
+ const rec = { ...baselineOf([{ name: 'ruflo-swarm', version: '0.4.0' }]), pinned: ['[email protected]'], dismissed: ['[email protected]'], toast: false }
+
+ expect(parseRecord(encodeRecord(rec))).toEqual(rec)
+ expect(parseRecord('{nope')).toBeNull()
+ expect(parseRecord(42)).toBeNull()
+ expect(parseRecord('x'.repeat(70_000))).toBeNull()
+ expect(parseRecord(JSON.stringify({ seen: { 'bad name!': '1.0.0', ok: '1.0.0', worse: '1.0' }, pinned: ['[email protected]', 'nope', 7] }))).toMatchObject({ seen: { ok: '1.0.0' }, pinned: ['[email protected]'], toast: true })
+ })
+
+ it('the first sight of the installed versions is a baseline: nothing is new and nothing is toasted', async () => {
+ const world = fake()
+ const state = stateWith({ 'ruflo-swarm': '0.4.0' })
+
+ await hydrateWhatsNew(state, world.host as never)
+ syncWhatsNew(state, world.host as never)
+ expect(hasUnseen(state)).toBe(false)
+ expect(world.log.toasts).toEqual([])
+ expect(record(world)?.seen).toMatchObject({ 'ruflo-swarm': '0.4.0', 'ruflo-console': CONSOLE_VERSION })
+ })
+
+ it('a version that lands is marked new, toasted once at the info level, and not again, even after a restart', async () => {
+ const world = fake()
+ const state = stateWith({ 'ruflo-swarm': '0.4.0' })
+
+ await hydrateWhatsNew(state, world.host as never)
+ syncWhatsNew(state, world.host as never)
+ install(state, { 'ruflo-swarm': '0.5.0' })
+ expect(hasUnseen(state)).toBe(true)
+ syncWhatsNew(state, world.host as never)
+ syncWhatsNew(state, world.host as never)
+ expect(world.log.toasts).toHaveLength(1)
+ expect(world.log.toasts[0]).toMatchObject({ level: 'info' })
+ expect(world.log.toasts[0]?.text).toContain('ruflo-swarm 0.5.0')
+ // Still unseen (the page was not opened) but toasted: a new session does not say it again.
+
+ const again = stateWith({ 'ruflo-swarm': '0.5.0' })
+ const later = fake({}, { [WHATSNEW_KEY]: world.store.get(WHATSNEW_KEY) })
+
+ await hydrateWhatsNew(again, later.host as never)
+ syncWhatsNew(again, later.host as never)
+ expect(hasUnseen(again)).toBe(true)
+ expect(later.log.toasts).toEqual([])
+ })
+
+ it('the switch turns the toast off (the marker still shows) and back on; many new versions make one toast with a count', async () => {
+ const world = fake()
+ const state = stateWith({ a: '0.1.0', b: '0.1.0', c: '0.1.0' })
+
+ await hydrateWhatsNew(state, world.host as never)
+ syncWhatsNew(state, world.host as never)
+ whatsnewActions(state, world.host as never).toggleToast()
+ expect(record(world)?.toast).toBe(false)
+ install(state, { a: '0.2.0', b: '0.2.0', c: '0.2.0' })
+ syncWhatsNew(state, world.host as never)
+ expect(world.log.toasts).toEqual([])
+ expect(hasUnseen(state)).toBe(true)
+ whatsnewActions(state, world.host as never).toggleToast()
+ install(state, { a: '0.3.0', b: '0.3.0', c: '0.3.0' })
+ syncWhatsNew(state, world.host as never)
+ expect(world.log.toasts).toHaveLength(1)
+ expect(world.log.toasts[0]?.text).toMatch(/and \d+ more/)
+ })
+
+ it('a session nobody can see (not interactive) toasts nothing but still records it', async () => {
+ const world = fake()
+ const state = stateWith({ a: '0.1.0' })
+
+ await hydrateWhatsNew(state, world.host as never)
+ syncWhatsNew(state, world.host as never)
+ state.isInteractive = false
+ install(state, { a: '0.2.0' })
+ syncWhatsNew(state, world.host as never)
+ expect(world.log.toasts).toEqual([])
+ expect(record(world)?.toasted.a).toBe('0.2.0')
+ })
+
+ it('a downgrade, an equal version and a pre-release are never new', () => {
+ const rec = baselineOf([{ name: 'a', version: '1.0.0' }, { name: 'ruflo-console', version: CONSOLE_VERSION }])
+ const state = stateWith({ a: '0.9.0' })
+
+ expect(unseenRows(rowsOf(state), rec).map(row => row.name)).toEqual([])
+ install(state, { a: '1.0.0' })
+ expect(unseenRows(rowsOf(state), rec)).toEqual([])
+ install(state, { a: '1.1.0-rc1' })
+ expect(unseenRows(rowsOf(state), rec)).toEqual([])
+ })
+
+ it('only ruflo-marketplace plugins with a plain version and a safe name are listed, and the console is always there', () => {
+ const state = newState({})
+
+ state.snapshot = { plugins: { installed: [{ id: 'x@other', name: 'x', marketplace: 'other', version: '1.0.0', scope: 'user' }, { id: 'ruflo-a@ruflo', name: 'ruflo-a', marketplace: 'ruflo', version: '1.0.0', scope: 'user', installPath: '/p/a' }, { id: 'bad@ruflo', name: 'bad name', marketplace: 'ruflo', version: '1.0.0', scope: 'user' }, { id: 'pre@ruflo', name: 'pre', marketplace: 'ruflo', version: '1.0.0-rc', scope: 'user' }] } } as never
+ expect(rowsOf(state, '/plugin').map(row => row.name)).toEqual(['ruflo-console', 'ruflo-a'])
+ expect(rowsOf(state, '/plugin')[0]).toMatchObject({ version: CONSOLE_VERSION, path: '/plugin' })
+ })
+
+ it('the toast line is one short clean line', () => {
+ const line = toastLine([{ name: 'a', version: '1.0.0', path: null }, { name: 'b', version: '2.0.0', path: null }, { name: 'c', version: '3.0.0', path: null }])
+
+ expect(line).toBe('What\'s new: a 1.0.0, b 2.0.0 and 1 more (TOOLS → What\'s new)')
+ expect(line.length).toBeLessThanOrEqual(118)
+ })
+})
+
+const NOTES = '## 0.5.0 — 2026-10-05\n- breaking: the flag --old is gone\n- feat: the new thing\n- fix: a crash\n## 0.4.0 — 2026-09-01\n- feat: older thing\n## 0.3.0 — 2026-08-01\n- chore: oldest\n'
+
+async function opened(files: Record<string, string>, seen: Record<string, string>, installed: Record<string, string>, links: string[] = []) {
+ const world = fake(files, { [WHATSNEW_KEY]: encodeRecord({ ...baselineOf([]), seen, toasted: seen }) }, links)
+ const state = stateWith(installed)
+
+ await hydrateWhatsNew(state, world.host as never)
+ await openWhatsNew(state, world.host as never)
+
+ return { world, state }
+}
+
+describe('opening the page', () => {
+ it('reads each plugin changelog from its install path, keeps the divider where the last look was, then counts everything as looked at', async () => {
+ const { world, state } = await opened({ '/cache/ruflo-swarm/0.5.0/CHANGELOG.md': NOTES }, { 'ruflo-swarm': '0.4.0' }, { 'ruflo-swarm': '0.5.0' })
+
+ expect(state.whatsnew.before).toEqual({ 'ruflo-swarm': '0.4.0' })
+ expect(record(world)?.seen['ruflo-swarm']).toBe('0.5.0')
+ expect(hasUnseen(state)).toBe(false)
+
+ const text = viewText({ state, nowMs: 5_000, columns: 120, act: noAct }, 'whatsnew')
+
+ expect(text.indexOf('ruflo-swarm 0.5.0')).toBeGreaterThan(-1)
+ expect(text.indexOf('ruflo-swarm 0.5.0')).toBeLessThan(text.indexOf('you last looked here'))
+ expect(text.indexOf('you last looked here')).toBeLessThan(text.indexOf('ruflo-swarm 0.4.0'))
+ expect(text.indexOf('ruflo-swarm 0.4.0')).toBeLessThan(text.indexOf('ruflo-swarm 0.3.0'))
+ expect(text).toContain('the new thing')
+ expect(world.log.fetches).toBe(0)
+ })
+
+ it('a breaking change among the new entries is pinned at the top, stays pinned in the next session, and goes only when dismissed', async () => {
+ const { world, state } = await opened({ '/cache/ruflo-swarm/0.5.0/CHANGELOG.md': NOTES }, { 'ruflo-swarm': '0.4.0' }, { 'ruflo-swarm': '0.5.0' })
+
+ expect(pinnedOf(state)).toEqual([{ key: '[email protected]', name: 'ruflo-swarm', version: '0.5.0', texts: ['the flag --old is gone'] }])
+
+ const top = viewText({ state, nowMs: 5_000, columns: 120, act: noAct }, 'whatsnew')
+
+ expect(top.indexOf('pinned until you dismiss')).toBeGreaterThan(-1)
+ expect(top.indexOf('the flag --old is gone')).toBeLessThan(top.indexOf('Since you last looked'))
+
+ // Leave, come back in a fresh session: the page opens with nothing new, and the pin is still there.
+ const next = stateWith({ 'ruflo-swarm': '0.5.0' })
+ const later = fake({ '/cache/ruflo-swarm/0.5.0/CHANGELOG.md': NOTES }, { [WHATSNEW_KEY]: world.store.get(WHATSNEW_KEY) })
+
+ await hydrateWhatsNew(next, later.host as never)
+ await openWhatsNew(next, later.host as never)
+ expect(pinnedOf(next)).toHaveLength(1)
+ whatsnewActions(next, later.host as never).dismiss('[email protected]')
+ expect(pinnedOf(next)).toEqual([])
+ expect(parseRecord(later.store.get(WHATSNEW_KEY))?.dismissed).toEqual(['[email protected]'])
+
+ // Dismissed means dismissed: opening again never pins it back.
+ const third = stateWith({ 'ruflo-swarm': '0.5.0' })
+ const last = fake({ '/cache/ruflo-swarm/0.5.0/CHANGELOG.md': NOTES }, { [WHATSNEW_KEY]: encodeRecord({ ...baselineOf([]), seen: { 'ruflo-swarm': '0.4.0' }, dismissed: ['[email protected]'] }) })
+
+ await hydrateWhatsNew(third, last.host as never)
+ await openWhatsNew(third, last.host as never)
+ expect(pinnedOf(third)).toEqual([])
+ })
+
+ it('a plugin with no changelog, a garbled one, an oversize one and a symlink each say so and break nothing', async () => {
+ const { state } = await opened(
+ { '/cache/a/1.0.0/CHANGELOG.md': 'no entries here', '/cache/c/1.0.0/CHANGELOG.md': 'x'.repeat(300_000), '/cache/d/1.0.0/CHANGELOG.md': NOTES, '/cache/e/1.0.0/CHANGELOG.md': entry('1.0.0', '2026-01-01', 'fix: fine') },
+ { e: '0.9.0' },
+ { a: '1.0.0', b: '1.0.0', c: '1.0.0', d: '1.0.0', e: '1.0.0' },
+ ['/cache/d/1.0.0/CHANGELOG.md'],
+ )
+ const text = viewText({ state, nowMs: 5_000, columns: 120, act: noAct }, 'whatsnew')
+
+ expect(text).toContain('fine')
+ expect(state.whatsnew.logs.map(log => [log.name, log.result.ok ? 'ok' : log.result.reason])).toEqual([['ruflo-console', 'missing'], ['a', 'garbled'], ['b', 'missing'], ['c', 'too-large'], ['d', 'unreadable'], ['e', 'ok']])
+ expect(readLogs).toBeTypeOf('function')
+ })
+
+ it('with no changelog anywhere the page says so in one clear line instead of drawing an empty list', async () => {
+ const { state } = await opened({}, { a: '1.0.0' }, { a: '1.0.0' })
+ const text = viewText({ state, nowMs: 5_000, columns: 100, act: noAct }, 'whatsnew')
+
+ expect(text).toContain('No installed ruflo plugin ships a readable CHANGELOG.md yet')
+ expect(text).not.toMatch(/\bundefined\b|\[object Object\]|NaN/)
+ })
+
+ it('a newer ruflo-console known from the update check is named with where to read its notes, and the page asks nothing of the network', async () => {
+ const { world, state } = await opened({}, { a: '1.0.0' }, { a: '1.0.0' })
+
+ state.updateAvailable = '9.9.9'
+
+ const text = viewText({ state, nowMs: 5_000, columns: 120, act: noAct }, 'whatsnew')
+
+ expect(text).toContain('9.9.9 is published')
+ expect(text).toContain('Its notes are not fetched here')
+ expect(text).toContain('https://github.com/ruvnet/ruflo/releases')
+ expect(world.log.fetches).toBe(0)
+ })
+
+ it('hostile files draw as clean text in both looks at narrow and wide widths', async () => {
+ const evil = `## 1.0.0 — 2026-10-05\n- breaking: ${ESC}[2J${ESC}]52;c;ZXZpbA==\u0007 wipe ‮ sk-ant-api03-AAAAAAAAAAAAAAAAAAAA\n- fix: ${'w'.repeat(5_000)}\n`
+ const { state } = await opened({ '/cache/ruflo-swarm/1.0.0/CHANGELOG.md': evil + Array.from({ length: 5_000 }, (_, i) => `## 0.${i}.0 — 2026-01-01\n- fix: n\n`).join('') }, { 'ruflo-swarm': '0.0.1' }, { 'ruflo-swarm': '1.0.0' })
+
+ for (const look of ['bbs', 'plain'] as const) {
+ setLook(look)
+
+ for (const columns of [44, 100, 200]) {
+ const text = viewText({ state, nowMs: 5_000, columns, act: noAct }, 'whatsnew')
+
+ expect(text).not.toMatch(/[\u001b\u0007‮]|sk-ant/)
+ expect(text.split('\n').length).toBeLessThan(400)
+ }
+ }
+ })
+
+ it('leaving the page forgets the divider; the toast switch shows its state', async () => {
+ const { state } = await opened({}, { a: '1.0.0' }, { a: '1.0.0' })
+
+ expect(viewText({ state, nowMs: 5_000, columns: 100, act: noAct }, 'whatsnew')).toContain('☑ toast when something new lands')
+ state.whatsnew.rec = { ...(state.whatsnew.rec as NonNullable<typeof state.whatsnew.rec>), toast: false }
+ expect(viewText({ state, nowMs: 5_000, columns: 100, act: noAct }, 'whatsnew')).toContain('☐ toast when something new lands')
+ })
+})
+
+const noAct = new Proxy(() => undefined, { get: (_t, key) => (key === 'then' ? undefined : noAct), apply: () => undefined }) as unknown as Actions
+
+describe('the plugins’ own changelogs (ADR-478)', () => {
+ const plugins = join(fileURLToPath(import.meta.url), '..', '..', '..')
+ const names = readdirSync(plugins).filter(name => existsSync(join(plugins, name, '.claude-plugin', 'plugin.json')))
+ const GATED = ['ruflo-console', 'ruflo-mods', 'ruflo-swarm', 'ruflo-protector']
+
+ it('every plugin ships a CHANGELOG.md the page can read (a pre-release manifest is listed for people, not parsed)', () => {
+ expect(names.length).toBeGreaterThan(20)
+
+ for (const name of names) {
+ const version = (JSON.parse(readFileSync(join(plugins, name, '.claude-plugin', 'plugin.json'), 'utf8')) as { version?: string }).version ?? ''
+ const text = existsSync(join(plugins, name, 'CHANGELOG.md')) ? readFileSync(join(plugins, name, 'CHANGELOG.md'), 'utf8') : null
+ const parsed = parseChangelog(text)
+
+ expect(text, `${name} has no CHANGELOG.md`).not.toBeNull()
+ if (semverOf(version) !== null) expect(parsed.ok, `${name} CHANGELOG.md does not parse`).toBe(true)
+ }
+ })
+
+ it('the plugins that bump on their own cadence have an entry for their manifest version, which is the newest', () => {
+ for (const name of GATED) {
+ const version = (JSON.parse(readFileSync(join(plugins, name, '.claude-plugin', 'plugin.json'), 'utf8')) as { version: string }).version
+ const parsed = parseChangelog(readFileSync(join(plugins, name, 'CHANGELOG.md'), 'utf8'))
+
+ expect(parsed.ok && parsed.entries[0]?.version, `${name}: newest entry is not ${version}`).toBe(version)
+ }
+ })
+})
diff --git a/plugins/ruflo-console/tests/whatsnew.test.ts b/plugins/ruflo-console/tests/whatsnew.test.ts
new file mode 100644
index 0000000000..a9c16a7beb
--- /dev/null
+++ b/plugins/ruflo-console/tests/whatsnew.test.ts
@@ -0,0 +1,191 @@
+/**
+ * What's new (ADR-478) through the real console: the page under the TOOLS group, reached by the nav, the search, the menu and /ruflo; the
+ * entries read from each plugin's own CHANGELOG.md; the "new" marker that appears and clears; one toast per new version; the switch;
+ * the pinned breaking change and its dismissal; and a hostile changelog. The page's drawing in both looks is covered in
+ * tests/whatsnew.spec.ts. Run with
+ * scripts/kit-seq.sh whatsnew
+ */
+import type { TestBody } from 'claude-code/testing'
+import { describe, expect, mock, test } from 'claude-code/testing'
+
+import { RUFLO_FILES } from './fixtures/ruflo-run'
+import { command, elementsOf, keyOf, paneAt, PLUGIN, SESSION, textOf as rawText, worldOf } from './fixtures/world'
+
+/** The BBS look draws headers in capitals, so the page's words are compared in lower case. */
+const textOf = (tree: Parameters<typeof rawText>[0]) => rawText(tree).toLowerCase()
+
+type Body = Parameters<TestBody>
+
+const ESC = '\u001b'
+const CACHE = '/home/dev/.claude/plugins/cache/ruflo'
+const installed = (swarm: string) =>
+ JSON.stringify({
+ version: 2,
+ plugins: {
+ 'ruflo-swarm@ruflo': [{ scope: 'user', version: swarm, installPath: `${CACHE}/ruflo-swarm/${swarm}` }],
+ 'ruflo-core@ruflo': [{ scope: 'user', version: '0.2.6', installPath: `${CACHE}/ruflo-core/0.2.6` }],
+ },
+ })
+const NOTES = '## 0.5.0 — 2026-10-05\n- breaking: the --old flag is gone\n- feat: the new thing\n- fix: a crash\n## 0.4.0 — 2026-09-01\n- feat: older thing\n'
+const HOSTILE = `## 0.5.0 — 2026-10-05\n- fix: ${ESC}[2J${ESC}]52;c;ZXZpbA==\u0007 wiped ‮ sk-ant-api03-AAAAAAAAAAAAAAAAAAAA\n- feat: ${'w'.repeat(9_000)}\n`
+
+/** The console with ruflo-swarm at `version`, its CHANGELOG at the install path, and the store holding what was last looked at. */
+async function start($: Body[0], on: Body[1], options: { swarm?: string; notes?: string; seen?: Record<string, string> | null; toasted?: Record<string, string> } = {}) {
+ const swarm = options.swarm ?? '0.5.0'
+ const world = worldOf(on, RUFLO_FILES, {
+ home: { '.claude/plugins/installed_plugins.json': installed(swarm), [`.claude/plugins/cache/ruflo/ruflo-swarm/${swarm}/CHANGELOG.md`]: options.notes ?? NOTES },
+ })
+ const clock = mock.clock(on)
+
+ if (options.seen !== null) world.stored.set('whatsnew', JSON.stringify({ v: 1, seen: options.seen ?? { 'ruflo-swarm': '0.4.0', 'ruflo-core': '0.2.6', 'ruflo-console': '0.38.0' }, toasted: options.toasted ?? { 'ruflo-swarm': '0.5.0', 'ruflo-core': '0.2.6', 'ruflo-console': '0.38.0' }, pinned: [], dismissed: [], toast: true }))
+
+ let fetches = 0
+
+ on('http.fetch', () => (fetches += 1, { deny: 'no network in this test' }) as never)
+ await $.session.start(SESSION)
+
+ return { world, clock, fetches: () => fetches }
+}
+
+async function mounted($: Body[0], view: string, columns = 130) {
+ await $.command.run(command(view))
+
+ const pane = await $.ui.mount({ ...paneAt(columns), surface: 'terminal' as const, plugin: PLUGIN })
+
+ await pane.drawn()
+
+ return pane
+}
+
+describe('What’s new, end to end', () => {
+ test('opens from /ruflo whatsnew: newest entries above the divider, the earlier ones below, nothing fetched', { options: { boot: false } }, async ($, on) => {
+ const { fetches, clock } = await start($, on)
+ const pane = await mounted($, 'whatsnew')
+
+ await clock.advance(1_600)
+
+ const tree = await pane.drawn()
+ const text = textOf(tree)
+
+ expect(text).toContain('what’s new')
+ expect(text).toContain('ruflo-swarm 0.5.0')
+ expect(text).toContain('the new thing')
+ expect(text.indexOf('ruflo-swarm 0.5.0')).toBeLessThan(text.indexOf('you last looked here'))
+ expect(text.indexOf('you last looked here')).toBeLessThan(text.indexOf('ruflo-swarm 0.4.0'))
+ expect(elementsOf(tree, 'Button').map(keyOf)).toEqual(expect.arrayContaining(['whatsnew-check', 'whatsnew-toast', 'whatsnew-dismiss-ruflo-swarm-0.5.0']))
+ expect(fetches()).toBe(0)
+ await pane.unmount()
+ })
+
+ test('is reached by the nav (the TOOLS group and by its search), by the menu entry, and has no hotkey of its own', { options: { boot: false } }, async ($, on) => {
+ await start($, on)
+
+ const pane = await mounted($, 'overview')
+
+ await pane.press({ key: 'nav-group-TOOLS' })
+ expect(elementsOf(await pane.drawn(), 'Button').map(keyOf)).toContain('tab-whatsnew')
+ await pane.press({ key: 'tab-whatsnew' })
+ expect(textOf(await pane.drawn())).toContain('what’s new')
+
+ await pane.press({ key: 'tab-menu' })
+ // One match opens the page, as a search does for any page.
+ await pane.input({ key: 'nav-find', text: 'changelog', kind: 'submit' })
+ expect(textOf(await pane.drawn())).toContain('since you last looked')
+ await pane.unmount()
+ })
+
+ test('the new marker is on the page and on the TOOLS group while a version is unseen, and clears once the page has been opened', { options: { boot: false } }, async ($, on) => {
+ await start($, on)
+
+ const pane = await mounted($, 'overview')
+ const before = await pane.drawn()
+
+ expect(textOf(before)).toContain('tools •')
+ await pane.press({ key: 'nav-group-TOOLS' })
+ expect(textOf(await pane.drawn())).toContain('new')
+ await pane.press({ key: 'tab-whatsnew' })
+ await pane.drawn()
+ await pane.press({ key: 'tab-overview' })
+
+ const after = await pane.drawn()
+
+ expect(textOf(after)).not.toContain('tools •')
+ await pane.unmount()
+ })
+
+ test('one info toast when a new version is found, none for the same version again, and none when the switch is off', { options: { boot: false } }, async ($, on) => {
+ const { world, clock } = await start($, on, { toasted: { 'ruflo-swarm': '0.4.0', 'ruflo-core': '0.2.6', 'ruflo-console': '0.38.0' } })
+
+ const pane = await mounted($, 'overview')
+
+ for (let i = 0; i < 4; i += 1) await clock.advance(3_100)
+ expect(world.toasts.filter(line => line.includes('new:'))).toEqual(['› What\'s new: ruflo-swarm 0.5.0 (TOOLS → What\'s new)'])
+ for (let i = 0; i < 4; i += 1) await clock.advance(3_100)
+ expect(world.toasts.filter(line => line.includes('new:'))).toHaveLength(1)
+ await pane.unmount()
+ })
+
+ test('the toast switch is a button that saves, and pressing it twice is back where it began', { options: { boot: false } }, async ($, on) => {
+ const { world } = await start($, on)
+ const pane = await mounted($, 'whatsnew')
+
+ await pane.press({ key: 'whatsnew-toast' })
+ expect(textOf(await pane.drawn())).toContain('☐ toast when something new lands')
+ expect(JSON.parse(String(world.stored.get('whatsnew'))).toast).toBe(false)
+ await pane.press({ key: 'whatsnew-toast' })
+ expect(textOf(await pane.drawn())).toContain('☑ toast when something new lands')
+ await pane.unmount()
+ })
+
+ test('a breaking change is pinned and stays until dismissed; the dismissal is remembered', { options: { boot: false } }, async ($, on) => {
+ const { world, clock } = await start($, on)
+ const pane = await mounted($, 'whatsnew')
+
+ await clock.advance(1_600)
+
+ const tree = await pane.drawn()
+
+ expect(textOf(tree)).toContain('pinned until you dismiss')
+ expect(textOf(tree).indexOf('the --old flag is gone')).toBeLessThan(textOf(tree).indexOf('since you last looked'))
+ await pane.press({ key: 'whatsnew-dismiss-ruflo-swarm-0.5.0' })
+ expect(textOf(await pane.drawn())).not.toContain('pinned until you dismiss')
+ expect(JSON.parse(String(world.stored.get('whatsnew'))).dismissed).toEqual(['[email protected]'])
+ await pane.unmount()
+ })
+
+ test('a changelog that is not the format, or missing, says so plainly and the rest of the page still draws', { options: { boot: false } }, async ($, on) => {
+ await start($, on, { notes: 'this is not a changelog' })
+
+ const pane = await mounted($, 'whatsnew')
+ const text = textOf(await pane.drawn())
+
+ expect(text).toContain('no installed ruflo plugin ships a readable changelog.md yet')
+ expect(text).toContain('check for an update now')
+ await pane.unmount()
+ })
+
+ test('a hostile changelog draws as clean, bounded text', { options: { boot: false } }, async ($, on) => {
+ const { clock } = await start($, on, { notes: HOSTILE })
+ const pane = await mounted($, 'whatsnew')
+
+ await clock.advance(1_600)
+
+ const text = textOf(await pane.drawn())
+
+ expect(text).toContain('wiped')
+ expect(text).not.toMatch(/[\u001b\u0007‮]|sk-ant-api03/)
+ expect(Math.max(...text.split('\n').map(line => line.length))).toBeLessThan(400)
+ await pane.unmount()
+ })
+
+ test('the check-now button is the update flow’s own action and nothing else reaches out', { options: { boot: false } }, async ($, on) => {
+ const { world, clock } = await start($, on)
+ const pane = await mounted($, 'whatsnew')
+
+ await pane.press({ key: 'whatsnew-check' })
+ await clock.advance(1_600)
+ expect(textOf(await pane.drawn())).toContain('what’s new')
+ expect(world.runs.every(argv => argv[0] !== 'curl' && argv[0] !== 'wget')).toBe(true)
+ await pane.unmount()
+ })
+})
diff --git a/scripts/ci-test-excluded.txt b/scripts/ci-test-excluded.txt
index aaec263a5f..f4e340ecf3 100644
--- a/scripts/ci-test-excluded.txt
+++ b/scripts/ci-test-excluded.txt
@@ -80,6 +80,7 @@ tests/check-guard-tool-names.test.mjs
tests/check-status-forwarding.test.mjs
plugins/ruflo-console/tests/result-display.test.ts
plugins/ruflo-console/tests/toasts.test.ts
+plugins/ruflo-console/tests/whatsnew.test.ts
plugins/ruflo-protector/tests/corpus.test.ts
plugins/ruflo-protector/tests/mod.test.ts
plugins/ruflo-protector/tests/rules.test.ts
diff --git a/scripts/smoke-all-plugins.mjs b/scripts/smoke-all-plugins.mjs
index 020a4ecf6b..acdaa02a1c 100755
--- a/scripts/smoke-all-plugins.mjs
+++ b/scripts/smoke-all-plugins.mjs
@@ -24,7 +24,7 @@
// 2 config error (e.g. invalid CLI args)
// 3 no smoke scripts found (likely repo-layout drift — fail closed)
-import { readdirSync, existsSync, statSync } from 'node:fs';
+import { readdirSync, existsSync, statSync, readFileSync } from 'node:fs';
import { spawn, spawnSync } from 'node:child_process';
import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';
@@ -183,6 +183,28 @@ function runGuardProbe() {
return row;
}
+/**
+ * The changelog contract (ADR-478): a plugin that ships a What's new page's data keeps a CHANGELOG.md with an entry for the version in its
+ * manifest, `## <version> — <date>` then `fix:`/`feat:`/`breaking:`/`chore:` bullets. Enforced for the plugins that bump on their own cadence
+ * (console, mods, swarm, protector); every other plugin ships a CHANGELOG.md too, but is not gated until its release flow writes one.
+ */
+const CHANGELOG_CONTRACT = ['ruflo-console', 'ruflo-mods', 'ruflo-swarm', 'ruflo-protector'];
+function runChangelogContract() {
+ const t0 = Date.now();
+ const names = CHANGELOG_CONTRACT.filter((n) => (!ARGS.only || ARGS.only.has(n)) && !ARGS.skip.has(n) && existsSync(join(PLUGINS_DIR, n)));
+ const failingSteps = [];
+ for (const name of names) {
+ let version = null;
+ try { version = JSON.parse(readFileSync(join(PLUGINS_DIR, name, '.claude-plugin', 'plugin.json'), 'utf8')).version; } catch { /* reported below */ }
+ if (typeof version !== 'string') { failingSteps.push({ step: `${name}: plugin.json has no version` }); continue; }
+ let text = '';
+ try { text = readFileSync(join(PLUGINS_DIR, name, 'CHANGELOG.md'), 'utf8').slice(0, 262144); } catch { failingSteps.push({ step: `${name}: no CHANGELOG.md` }); continue; }
+ const headers = text.split('\n').filter((l) => l.startsWith('## ')).map((l) => /^## (\d{1,4}\.\d{1,4}\.\d{1,4}) [—–-] \d{4}-\d{2}-\d{2}\s*$/.exec(l.replace(/\r$/, '').slice(0, 64)));
+ if (!headers.some((m) => m && m[1] === version)) failingSteps.push({ step: `${name}: CHANGELOG.md has no "## ${version} — <date>" entry` });
+ }
+ return { name: 'changelog contract', exitCode: failingSteps.length ? 1 : 0, ok: failingSteps.length === 0, timedOut: false, aborted: false, terminationReason: null, passed: names.length - failingSteps.length, failed: failingSteps.length, durationMs: Date.now() - t0, failingSteps, stderrTail: '' };
+}
+
async function main() {
const plugins = discoverPlugins();
if (plugins.length === 0) {
@@ -223,6 +245,7 @@ async function main() {
results = await Promise.all(pending);
}
+ results.push(runChangelogContract());
if (ARGS.guardProbe && !abortController?.signal.aborted) results.push(runGuardProbe());
const okCount = results.filter((r) => r.ok).length;