@buoy-gg/shared-ui 7.0.40 → 7.0.42

package/lib/module/sync/toolAttention.test.js

@@ -1,50 +1 @@
-"use strict";
-
-/**
- * The attention badge seam: a tool says "I need you" and the rail hears it.
- */
-import { describe, expect, it, vi } from "vitest";
-import { getToolAttention, setToolAttention, subscribeToolAttention } from "./toolUiBridge.js";
-describe("toolAttention", () => {
-  it("stores, replaces and clears a badge, notifying once per change", () => {
-    const fn = vi.fn();
-    const off = subscribeToolAttention(fn);
-    setToolAttention("ask-buoy", {
-      kind: "needsInput",
-      label: "Needs your approval"
-    });
-    expect(getToolAttention("ask-buoy")).toEqual({
-      kind: "needsInput",
-      label: "Needs your approval"
-    });
-    expect(fn).toHaveBeenCalledTimes(1);
-    // Same value again is not a change.
-    setToolAttention("ask-buoy", {
-      kind: "needsInput",
-      label: "Needs your approval"
-    });
-    expect(fn).toHaveBeenCalledTimes(1);
-    setToolAttention("ask-buoy", {
-      kind: "done",
-      label: "Finished"
-    });
-    expect(fn).toHaveBeenCalledTimes(2);
-    setToolAttention("ask-buoy", null);
-    expect(getToolAttention("ask-buoy")).toBeNull();
-    expect(fn).toHaveBeenCalledTimes(3);
-    // Clearing what is already clear is silent.
-    setToolAttention("ask-buoy", null);
-    expect(fn).toHaveBeenCalledTimes(3);
-    off();
-  });
-  it("keeps tools apart", () => {
-    setToolAttention("a", {
-      kind: "failed",
-      label: "x"
-    });
-    setToolAttention("b", null);
-    expect(getToolAttention("a")?.kind).toBe("failed");
-    expect(getToolAttention("b")).toBeNull();
-    setToolAttention("a", null);
-  });
-});
+"use strict";import{describe as s,expect as e,it as n,vi as i}from"vitest";import{getToolAttention as a,setToolAttention as o,subscribeToolAttention as d}from"./toolUiBridge.js";s("toolAttention",()=>{n("stores, replaces and clears a badge, notifying once per change",()=>{const l=i.fn();const t=d(l);o("ask-buoy",{kind:"needsInput",label:"Needs your approval"});e(a("ask-buoy")).toEqual({kind:"needsInput",label:"Needs your approval"});e(l).toHaveBeenCalledTimes(1);o("ask-buoy",{kind:"needsInput",label:"Needs your approval"});e(l).toHaveBeenCalledTimes(1);o("ask-buoy",{kind:"done",label:"Finished"});e(l).toHaveBeenCalledTimes(2);o("ask-buoy",null);e(a("ask-buoy")).toBeNull();e(l).toHaveBeenCalledTimes(3);o("ask-buoy",null);e(l).toHaveBeenCalledTimes(3);t()});n("keeps tools apart",()=>{o("a",{kind:"failed",label:"x"});o("b",null);e(a("a")?.kind).toBe("failed");e(a("b")).toBeNull();o("a",null)})});

package/lib/module/sync/toolSyncAdapter.js

@@ -1,58 +1 @@
-"use strict";
-
-/**
- * ToolSyncAdapter — the contract a tool implements to sync to Buoy Desktop /
- * the MCP server, plus `createSyncAdapter`, the one way to build one.
- *
- * Every tool package used to declare its adapter as a bare object literal
- * with the comment "structurally matches external-sync's ToolSyncAdapter so
- * this package doesn't need a dependency on it". That kept the packages
- * decoupled but left the contract unchecked: storage shipped `version: 3`
- * while every sibling was on 2 and nothing noticed. The type now lives here,
- * in shared (which every tool already depends on), and external-sync
- * re-exports it — one definition, checked everywhere.
- *
- * `createSyncAdapter` is deliberately thin. It:
- *  - type-checks the literal against the contract (a wrong `subscribe`
- *    signature or a non-function action fails at compile time),
- *  - keeps the CONCRETE `actions` type, so `adapter.actions.getChangeDetail()`
- *    stays typed for tests and callers,
- *  - merges several change sources into one `subscribe` (a store plus its
- *    registry, envelopes plus drops) — the second most-copied block.
- */
-
-/** A remote-invocable action. Thrown errors are reported back to the dashboard. */
-
-/** Anything that can tell the bridge "something changed". */
-
-/**
- * The contract each dev tool implements to become remotely syncable.
- * Works with BaseEventStore, ChangeLog, createToolStore, or any pattern
- * exposing subscribe + getSnapshot.
- *
- * Payloads (snapshots and action results) must be JSON-serializable —
- * no functions, circular references, or class instances.
- */
-
-/** Subscribe to every source; the returned function unsubscribes from all. */
-export function mergeChangeSources(sources) {
-  if (sources.length === 1) return sources[0];
-  return onChange => {
-    const offs = sources.map(source => source(onChange));
-    return () => {
-      for (const off of offs) off();
-    };
-  };
-}
-export function createSyncAdapter(definition) {
-  const subscribe = Array.isArray(definition.subscribe) ? mergeChangeSources(definition.subscribe) : definition.subscribe;
-  const adapter = {
-    version: definition.version,
-    getSnapshot: definition.getSnapshot,
-    subscribe,
-    ...(definition.actions ? {
-      actions: definition.actions
-    } : {})
-  };
-  return adapter;
-}
+"use strict";export function mergeChangeSources(r){if(r.length===1)return r[0];return s=>{const t=r.map(e=>e(s));return()=>{for(const e of t)e()}}}export function createSyncAdapter(r){const s=Array.isArray(r.subscribe)?mergeChangeSources(r.subscribe):r.subscribe;const t={version:r.version,getSnapshot:r.getSnapshot,subscribe:s,...r.actions?{actions:r.actions}:{}};return t}

package/lib/module/sync/toolUiBridge.js

@@ -1,123 +1 @@
-"use strict";
-
-/**
- * toolUiBridge — let a tool ask the host to bring another tool back on screen.
- *
- * WHY THIS EXISTS. Buoy's tool overlays (the SIMULATED banner, the recording
- * banner, the perf HUD) render as siblings of `AppHostProvider`, not inside it,
- * so none of them can reach the host that knows how to open and restore tools.
- * That is usually fine — an overlay's job is to be seen, not to navigate. It
- * stops being fine the moment an overlay is the ONLY thing on screen and the
- * next step lives inside a tool: the macro recorder minimizes Scenarios so a
- * tester can drive the app, and when they stop, the review screen they need is
- * behind a tool icon they have to know to hunt for.
- *
- * The alternative was moving every overlay inside the provider, which would
- * re-order the stacking of six unrelated tools to fix one banner's button. This
- * is the same global-seam shape `toolActionRegistry` already uses for the same
- * reason: the capability lives inside a component tree, the caller must not
- * import `@buoy-gg/core` (that package imports the tools, and a tool importing
- * it back is a require cycle), so it is published through a global.
- *
- * A SET of openers, not one slot, for the reason the action registry keeps one:
- * React can briefly mount two providers, or re-run an effect's setup before the
- * previous cleanup, and a last-writer-wins slot lets the second registration
- * silently blank the first.
- */
-
-const BRIDGE_KEY = "__buoyToolUiBridge";
-
-/** Returns true when the tool was actually brought back on screen. */
-
-function openers() {
-  const g = globalThis;
-  if (!g[BRIDGE_KEY]) g[BRIDGE_KEY] = new Set();
-  return g[BRIDGE_KEY];
-}
-
-/** Published by the host, inside the provider that owns open tools. */
-export function registerToolOpener(opener) {
-  const set = openers();
-  set.add(opener);
-  return () => {
-    set.delete(opener);
-  };
-}
-
-/**
- * Ask the host to show a tool.
- *
- * Returns false when nothing could do it — no host mounted, or the tool isn't
- * open for it to restore. Callers must treat that as a real answer and say so,
- * rather than rendering a button that silently does nothing.
- */
-export function openBuoyTool(toolId) {
-  for (const opener of openers()) {
-    try {
-      if (opener(toolId)) return true;
-    } catch {
-      // A host that throws must not stop another from answering.
-    }
-  }
-  return false;
-}
-
-/** True when some host is listening — for deciding whether to offer the button. */
-export function canOpenBuoyTools() {
-  return openers().size > 0;
-}
-
-// ─── Attention ───────────────────────────────────────────────────────────────
-
-/**
- * "This tool needs you" — shown as a badge on its chip in the minimized rail.
- *
- * The case: Ask Buoy is minimized so a tester can watch the app, and the
- * agent hits a step that needs a tap. Nobody can see the card. The sheet used
- * to fail safe by DECLINING the change and ending the turn — which made
- * minimize mean "stop", the opposite of what it is for. Now the approval
- * holds, the chip gets a badge, and tapping the chip (the existing restore
- * path) brings the card back. Same seam shape as the opener above: the rail
- * lives inside the host, the tool cannot import the host, so it publishes
- * through a global.
- *
- * `done` and `failed` cover the other thing a hidden tool cannot say — that
- * the work you minimized it to wait for has finished.
- */
-
-const ATTENTION_KEY = "__buoyToolAttention";
-function attention() {
-  const g = globalThis;
-  if (!g[ATTENTION_KEY]) g[ATTENTION_KEY] = {
-    byTool: new Map(),
-    listeners: new Set()
-  };
-  return g[ATTENTION_KEY];
-}
-
-/** Set, replace or (with null) clear a tool's badge. No-op when nothing changed. */
-export function setToolAttention(toolId, next) {
-  const store = attention();
-  const prev = store.byTool.get(toolId) ?? null;
-  if (prev === next || prev && next && prev.kind === next.kind && prev.label === next.label) return;
-  if (next) store.byTool.set(toolId, next);else store.byTool.delete(toolId);
-  for (const fn of store.listeners) {
-    try {
-      fn();
-    } catch {
-      // A throwing subscriber must not stop the others from hearing.
-    }
-  }
-}
-export function getToolAttention(toolId) {
-  return attention().byTool.get(toolId) ?? null;
-}
-
-/** For `useSyncExternalStore` in the rail. */
-export function subscribeToolAttention(fn) {
-  const store = attention();
-  store.listeners.add(fn);
-  return () => {
-    store.listeners.delete(fn);
-  };
-}
+"use strict";const r="__buoyToolUiBridge";function s(){const t=globalThis;if(!t[r])t[r]=new Set;return t[r]}export function registerToolOpener(t){const o=s();o.add(t);return()=>{o.delete(t)}}export function openBuoyTool(t){for(const o of s()){try{if(o(t))return true}catch{}}return false}export function canOpenBuoyTools(){return s().size>0}const i="__buoyToolAttention";function l(){const t=globalThis;if(!t[i])t[i]={byTool:new Map,listeners:new Set};return t[i]}export function setToolAttention(t,o){const e=l();const n=e.byTool.get(t)??null;if(n===o||n&&o&&n.kind===o.kind&&n.label===o.label)return;if(o)e.byTool.set(t,o);else e.byTool.delete(t);for(const u of e.listeners){try{u()}catch{}}}export function getToolAttention(t){return l().byTool.get(t)??null}export function subscribeToolAttention(t){const o=l();o.listeners.add(t);return()=>{o.listeners.delete(t)}}

package/lib/module/sync/typedEdit.js

@@ -1,220 +1 @@
-"use strict";
-
-/**
- * The typed-edit guard — ONE implementation, for every surface that takes a
- * merge patch from a remote caller.
- *
- * The rule, which is the React Query devtools value-editor rule: you may change
- * the VALUE of a field that already exists, to the same kind of thing. You may
- * not add a field, change a field's type, or null a list or object the screen
- * renders. A list may grow or shrink — carts are lists you add to — but every
- * item in it must have the same fields as the items already there, because an
- * item missing a field the others have is what crashes the list on render.
- *
- * WHY IT LIVES HERE. This existed twice, once in the zustand adapter and once in
- * react-query, drifting slightly (one said "the ones already in the list", the
- * other "the items"; only one had the did-you-mean hint). Jotai had NO copy at
- * all, so `setAtom` accepted a string over a number or a one-item array over a
- * fifty-item one with nothing to stop it. Three copies of a data-destroying
- * safety rule is two more than anyone can keep in step — the same argument
- * `keyedArrays.ts` makes about the expansion it owns.
- *
- * The one behavioural knob is `noun`: what to call the thing being edited in a
- * refusal ("this store", "this data", "this atom"). Everything else is shared,
- * deliberately — a rule that differs per surface is a rule nobody can state.
- */
-
-const isPlainObject = v => !!v && typeof v === "object" && !Array.isArray(v);
-
-/** The shape category the screen depends on: array vs object vs the rest. */
-export function shapeKind(v) {
-  if (Array.isArray(v)) return "array";
-  if (v === null) return "null";
-  if (typeof v === "object") return "object";
-  return typeof v;
-}
-const SCALARS = ["string", "number", "boolean"];
-
-/**
- * Where a key actually lives in a nested value, as a dotted path — first match,
- * breadth-first, capped so a huge payload cannot stall the walk.
- *
- * This is what turns "you put `name` at the top" into "`name` lives at
- * `item.name`", which is the difference between a caller that gives up and one
- * that fixes it. Ten of eleven measured `query` write failures were this exact
- * mistake.
- */
-export function findKeyPath(obj, key, maxNodes = 2000) {
-  const queue = [{
-    node: obj,
-    path: ""
-  }];
-  let seen = 0;
-  while (queue.length && seen < maxNodes) {
-    const {
-      node,
-      path
-    } = queue.shift();
-    seen++;
-    if (Array.isArray(node)) {
-      node.slice(0, 20).forEach((v, i) => queue.push({
-        node: v,
-        path: `${path}[${i}]`
-      }));
-    } else if (isPlainObject(node)) {
-      for (const [k, v] of Object.entries(node)) {
-        const p = path ? `${path}.${k}` : k;
-        if (k === key && path) return p; // path set => nested, not the top level
-        if (isPlainObject(v) || Array.isArray(v)) queue.push({
-          node: v,
-          path: p
-        });
-      }
-    }
-  }
-  return undefined;
-}
-/**
- * Every way this patch would break the value it is merged into. Empty means the
- * edit is safe to apply.
- */
-export function typedEditViolations(current, patch, opts = {}, root = current, path = "", out = []) {
-  const noun = opts.noun ?? "data";
-  const here = path || "(root)";
-  if (Array.isArray(patch)) {
-    if (!Array.isArray(current)) {
-      out.push({
-        path: here,
-        kind: "type-change",
-        detail: `${shapeKind(current)} → array`
-      });
-      return out;
-    }
-    // Length may change — a cart is a list you add to and remove from — but each
-    // item must match the shape of the ones already there. The first item is the
-    // template; an added item missing a field the others have is what makes the
-    // list throw when it renders that field.
-    const template = current.length ? current[0] : undefined;
-    if (template !== undefined && (isPlainObject(template) || Array.isArray(template))) {
-      patch.forEach((el, i) => {
-        const ep = `${path}[${i}]`;
-        if (isPlainObject(template) && isPlainObject(el)) {
-          for (const k of Object.keys(template)) {
-            if (!(k in el)) {
-              out.push({
-                path: `${ep}.${k}`,
-                kind: "missing-key",
-                detail: `list items need \`${k}\` — the items already in the list have it`
-              });
-            }
-          }
-        }
-        typedEditViolations(template, el, opts, root, ep, out);
-      });
-    }
-    return out;
-  }
-  if (isPlainObject(patch)) {
-    if (!isPlainObject(current)) {
-      out.push({
-        path: here,
-        kind: "type-change",
-        detail: `${shapeKind(current)} → object`
-      });
-      return out;
-    }
-    for (const [k, v] of Object.entries(patch)) {
-      const p = path ? `${path}.${k}` : k;
-      if (!(k in current)) {
-        const elsewhere = findKeyPath(root, k);
-        out.push({
-          path: p,
-          kind: "add-key",
-          detail: elsewhere ? `no such field here — did you mean \`${elsewhere}\`?` : `no field named \`${k}\` exists in this ${noun}`,
-          ...(elsewhere ? {
-            movedTo: elsewhere
-          } : {})
-        });
-      } else {
-        typedEditViolations(current[k], v, opts, root, p, out);
-      }
-    }
-    return out;
-  }
-
-  // A leaf: the edit itself.
-  const ck = shapeKind(current);
-  const pk = shapeKind(patch);
-  // Filling an empty field and CLEARING one are the same kind of edit, and this
-  // guard used to allow only the first. That asymmetry had a cost: "take the
-  // promo off my bag" is `string → null`, the refusal named `force: true` as the
-  // only way through, and a model that anticipated it wrote the forced call
-  // pre-emptively — reaching for the one parameter that bypasses EVERY
-  // protection in order to do something completely ordinary. Measured on
-  // `cart/take-promo-off`: an S1 on an otherwise correct flow.
-  //
-  // Nulling a LIST or OBJECT the screen renders stays refused. That is the crash
-  // this guard exists for (`sizes.map` on null); a null scalar renders as empty.
-  const fillingNull = ck === "null" && SCALARS.includes(pk);
-  const clearingScalar = pk === "null" && SCALARS.includes(ck);
-  if (ck !== pk && !fillingNull && !clearingScalar) {
-    out.push({
-      path: here,
-      kind: "type-change",
-      detail: `${ck} → ${pk}`
-    });
-  }
-  return out;
-}
-
-/**
- * The patch the caller should have sent, when every problem was a field written
- * at the wrong DEPTH.
- *
- * The guard already worked out where each field really lives in order to say
- * "did you mean `item.name`?", so it can rebuild the patch instead of leaving
- * the caller to re-derive it from prose. Returns undefined unless EVERY
- * violation is a relocatable add-key: a partial suggestion that silently drops
- * the parts we could not fix would be worse than none, because the caller would
- * send it, be refused again, and learn nothing.
- */
-export function suggestedPatch(patch, violations) {
-  if (!violations.length || !violations.every(v => v.kind === "add-key" && v.movedTo)) return undefined;
-  const out = {};
-  for (const v of violations) {
-    const value = getAtDotted(patch, v.path);
-    if (value === undefined) return undefined;
-    // `movedTo` can name a list element (`results[0].name`); a merge patch
-    // cannot address one by index, and rewriting it to the id-addressed form
-    // needs the list itself. Leave those to the prose rather than suggest
-    // something that will not apply.
-    if (v.movedTo.includes("[")) return undefined;
-    let node = out;
-    const segs = v.movedTo.split(".");
-    segs.slice(0, -1).forEach(seg => {
-      node[seg] ??= {};
-      node = node[seg];
-    });
-    node[segs[segs.length - 1]] = value;
-  }
-  return out;
-}
-function getAtDotted(obj, path) {
-  let cur = obj;
-  for (const seg of path.split(".")) {
-    if (!isPlainObject(cur)) return undefined;
-    cur = cur[seg];
-  }
-  return cur;
-}
-
-/**
- * The sentence a refusal ends with. Shared so every surface refuses in the same
- * words — a caller that learns the rule on one tool should recognise it on the
- * next.
- */
-export function refusalText(violations, noun, suggestion) {
-  const listed = violations.slice(0, 6).map(v => `\`${v.path}\`: ${v.detail}`).join("; ");
-  const more = violations.length > 6 ? `; +${violations.length - 6} more` : "";
-  return `Refused: this isn't a same-type edit of existing fields (the rule the React Query devtools enforces). ${listed}${more}. ` + `You can only change the VALUE of a field that already exists, to the same type — you can't add fields, change a field's type, ` + `or null a list/object the screen renders. Clearing a scalar to null is fine. Send just the field(s) you're changing, nested to ` + `match the current shape of this ${noun}. Use force:true only to deliberately break that.` + (suggestion ? ` This is the same edit at the right depth — send it as the patch: ${JSON.stringify(suggestion)}` : "");
-}
+"use strict";const l=e=>!!e&&typeof e==="object"&&!Array.isArray(e);export function shapeKind(e){if(Array.isArray(e))return"array";if(e===null)return"null";if(typeof e==="object")return"object";return typeof e}const $=["string","number","boolean"];export function findKeyPath(e,s,i=2e3){const n=[{node:e,path:""}];let a=0;while(n.length&&a<i){const{node:t,path:o}=n.shift();a++;if(Array.isArray(t)){t.slice(0,20).forEach((d,f)=>n.push({node:d,path:`${o}[${f}]`}))}else if(l(t)){for(const[d,f]of Object.entries(t)){const c=o?`${o}.${d}`:d;if(d===s&&o)return c;if(l(f)||Array.isArray(f))n.push({node:f,path:c})}}}return void 0}export function typedEditViolations(e,s,i={},n=e,a="",t=[]){const o=i.noun??"data";const d=a||"(root)";if(Array.isArray(s)){if(!Array.isArray(e)){t.push({path:d,kind:"type-change",detail:`${shapeKind(e)} \u2192 array`});return t}const r=e.length?e[0]:void 0;if(r!==void 0&&(l(r)||Array.isArray(r))){s.forEach((u,y)=>{const h=`${a}[${y}]`;if(l(r)&&l(u)){for(const p of Object.keys(r)){if(!(p in u)){t.push({path:`${h}.${p}`,kind:"missing-key",detail:`list items need \`${p}\` \u2014 the items already in the list have it`})}}}typedEditViolations(r,u,i,n,h,t)})}return t}if(l(s)){if(!l(e)){t.push({path:d,kind:"type-change",detail:`${shapeKind(e)} \u2192 object`});return t}for(const[r,u]of Object.entries(s)){const y=a?`${a}.${r}`:r;if(!(r in e)){const h=findKeyPath(n,r);t.push({path:y,kind:"add-key",detail:h?`no such field here \u2014 did you mean \`${h}\`?`:`no field named \`${r}\` exists in this ${o}`,...h?{movedTo:h}:{}})}else{typedEditViolations(e[r],u,i,n,y,t)}}return t}const f=shapeKind(e);const c=shapeKind(s);const g=f==="null"&&$.includes(c);const m=c==="null"&&$.includes(f);if(f!==c&&!g&&!m){t.push({path:d,kind:"type-change",detail:`${f} \u2192 ${c}`})}return t}export function suggestedPatch(e,s){if(!s.length||!s.every(n=>n.kind==="add-key"&&n.movedTo))return void 0;const i={};for(const n of s){const a=A(e,n.path);if(a===void 0)return void 0;if(n.movedTo.includes("["))return void 0;let t=i;const o=n.movedTo.split(".");o.slice(0,-1).forEach(d=>{t[d]??={};t=t[d]});t[o[o.length-1]]=a}return i}function A(e,s){let i=e;for(const n of s.split(".")){if(!l(i))return void 0;i=i[n]}return i}export function refusalText(e,s,i){const n=e.slice(0,6).map(t=>`\`${t.path}\`: ${t.detail}`).join("; ");const a=e.length>6?`; +${e.length-6} more`:"";return`Refused: this isn't a same-type edit of existing fields (the rule the React Query devtools enforces). ${n}${a}. You can only change the VALUE of a field that already exists, to the same type \u2014 you can't add fields, change a field's type, or null a list/object the screen renders. Clearing a scalar to null is fine. Send just the field(s) you're changing, nested to match the current shape of this ${s}. Use force:true only to deliberately break that.`+(i?` This is the same edit at the right depth \u2014 send it as the patch: ${JSON.stringify(i)}`:"")}