dsh-nextsteps 1.4.0 → 1.4.1

package/client.js

@@ -144,7 +144,7 @@ window.__ModuleLoader__.load({
 
     const captures = new Map();
     const captureListeners = new Set();
-    const CAPTURES_KEY = 'dsh.nextsteps.captures.v1';
+    const CAPTURES_KEY = 'dsh-nextsteps.captures.v1';
     const CAPTURE_LIMIT = 400;
 
     function readStoredCaptures() {

package/lib/locale/en.json

@@ -1,7 +1,9 @@
 {
+  "setModel": "Model",
+  "setModelTip": "The model that generates the suggestions. Auto keeps them inside the main turn.",
+  "optModelAuto": "Auto (same model as the chat)",
+  "modelUnavailable": "No model list available in this install",
   "header": "Suggested followups",
-  "showEarlier": "Show earlier suggestions",
-  "hideEarlier": "Hide earlier suggestions",
   "srFollowupSent": "Followup sent",
   "sendFailed": "Could not send: ",
   "meta": {
@@ -12,9 +14,6 @@
   "setLanguage": "Language",
   "setLanguageTip": "Followups are generated in this language. Auto follows the conversation.",
   "optAuto": "Auto (follow the conversation)",
-  "optEn": "English",
-  "optPt": "Português (Brasil)",
-  "optZh": "简体中文",
   "setMax": "Followups per turn",
   "setMaxTip": "How many suggested prompts the model should produce (1-6).",
   "setHeader": "Show header",

package/lib/locale/pt-BR.json

@@ -1,7 +1,9 @@
 {
+  "setModel": "Modelo",
+  "setModelTip": "O modelo que gera as sugestões. Automático as mantém no turno principal.",
+  "optModelAuto": "Automático (mesmo modelo da conversa)",
+  "modelUnavailable": "Nenhuma lista de modelos disponível nesta instalação",
   "header": "Sugestões de acompanhamento",
-  "showEarlier": "Mostrar sugestões anteriores",
-  "hideEarlier": "Ocultar sugestões anteriores",
   "srFollowupSent": "Follow-up enviado",
   "sendFailed": "Não consegui enviar: ",
   "meta": {
@@ -12,9 +14,6 @@
   "setLanguage": "Idioma",
   "setLanguageTip": "Os followups são gerados neste idioma. Automático segue a conversa.",
   "optAuto": "Automático (segue a conversa)",
-  "optEn": "English",
-  "optPt": "Português (Brasil)",
-  "optZh": "简体中文",
   "setMax": "Followups por turno",
   "setMaxTip": "Quantas sugestões o modelo deve produzir (1-6).",
   "setHeader": "Mostrar cabeçalho",

package/lib/locale/zh-CN.json

@@ -1,7 +1,9 @@
 {
+  "setModel": "模型",
+  "setModelTip": "生成建议的模型。自动会跟随对话所用的模型。",
+  "optModelAuto": "自动（与对话相同的模型）",
+  "modelUnavailable": "此安装没有可用的模型列表",
   "header": "建议的后续操作",
-  "showEarlier": "显示较早的建议",
-  "hideEarlier": "隐藏较早的建议",
   "srFollowupSent": "后续操作已发送",
   "sendFailed": "发送失败：",
   "meta": {
@@ -12,9 +14,6 @@
   "setLanguage": "语言",
   "setLanguageTip": "后续操作提示将以此语言生成。“自动”会跟随对话语言。",
   "optAuto": "自动（跟随对话）",
-  "optEn": "English",
-  "optPt": "Português (Brasil)",
-  "optZh": "简体中文",
   "setMax": "每回合提示数",
   "setMaxTip": "模型应生成的建议提示数量（1-6）。",
   "setHeader": "显示标题",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-nextsteps",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "type": "module",
   "exports": {
     ".": "./index.js",
@@ -16,7 +16,8 @@
     "README.md",
     "LICENSE",
     "README.pt-BR.md",
-    "README.zh-CN.md"
+    "README.zh-CN.md",
+    "scripts"
   ],
   "dsh": {
     "bundle": {
@@ -49,5 +50,9 @@
   "bugs": {
     "url": "https://github.com/klaus-2/dsh-nextsteps/issues"
   },
+  "scripts": {
+    "test": "node tools/regression.mjs",
+    "regression": "node tools/regression.mjs"
+  },
   "icon": "./docs/assets/icon.png"
 }

package/scripts/client-harness.mjs

@@ -0,0 +1,202 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+/** A React-shaped stub good enough to render the plugin's function components. */
+export function fakeReact() {
+  const state = [];
+  let cursor = 0;
+  const hooks = {
+    useState(initial) {
+      const index = cursor++;
+      if (state.length <= index) state[index] = typeof initial === "function" ? initial() : initial;
+      const setValue = (next) => {
+        state[index] = typeof next === "function" ? next(state[index]) : next;
+      };
+      return [state[index], setValue];
+    },
+    useReducer(reducer, initial) {
+      const index = cursor++;
+      if (state.length <= index) state[index] = initial;
+      const dispatch = (action) => {
+        state[index] = reducer(state[index], action);
+      };
+      return [state[index], dispatch];
+    },
+    useRef(initial) {
+      const index = cursor++;
+      if (state.length <= index) state[index] = { current: initial };
+      return state[index];
+    },
+    useMemo(factory) {
+      return factory();
+    },
+    useCallback(fn) {
+      return fn;
+    },
+    useEffect() {},
+    useSyncExternalStore(subscribe, getSnapshot) {
+      return getSnapshot();
+    }
+  };
+  const createElement = (type, props, ...children) => {
+    const flat = [];
+    const push = (child) => {
+      if (child === null || child === undefined || child === false) return;
+      if (Array.isArray(child)) {
+        for (const item of child) push(item);
+        return;
+      }
+      flat.push(child);
+    };
+    for (const child of children) push(child);
+    return { type, props: props ?? {}, children: flat };
+  };
+  return { ...hooks, createElement, __reset: () => { cursor = 0; }, __state: state };
+}
+
+export function memoryStorage(initial = {}) {
+  const data = { ...initial };
+  return {
+    getItem: (key) => (key in data ? data[key] : null),
+    setItem: (key, value) => {
+      data[key] = String(value);
+    },
+    removeItem: (key) => {
+      delete data[key];
+    },
+    _data: data
+  };
+}
+
+/**
+ * Loads client.js the way the dsh module loader does and returns the plugin instance.
+ * The client is a browser bundle: it is evaluated with a fake window/document and the
+ * captured factory is invoked with a `require` that hands out the fake React.
+ */
+export function loadClient({ storage = memoryStorage(), language = "en", routes = {} } = {}) {
+  const source = readFileSync(path.join(root, "client.js"), "utf8");
+  let captured;
+  const head = { appendChild() {} };
+  const document = {
+    head,
+    createElement: () => ({ style: {}, set textContent(value) { this._text = value; }, appendChild() {} })
+  };
+  const window = {
+    localStorage: storage,
+    setTimeout: (fn, ms) => setTimeout(fn, ms),
+    clearTimeout: (id) => clearTimeout(id)
+  };
+  const loader = { load: (module) => { captured = module; } };
+  window.__ModuleLoader__ = loader;
+  const evaluate = new Function("window", "document", "navigator", "console", source);
+  evaluate(window, document, { language }, console);
+  if (captured === undefined) throw new Error("client.js did not register a module");
+  const react = fakeReact();
+  const fetchStub = stubFetch(routes);
+  const instance = captured.factory((name) => {
+    if (name === "react") return react;
+    if (name === "react-dom") return { createPortal: (node) => node };
+    throw new Error(`the client requires an unexpected module: ${name}`);
+  });
+  return { instance, react, storage, window, document, moduleId: captured.id, fetchStub };
+}
+
+/** Collects the slot registrations a plugin performs, so a test can render a component. */
+export function fakeSlotHost(react) {
+  const registrations = [];
+  const dictionaries = new Map();
+  const wrap = (component) => {
+    if (typeof component !== "function") return component;
+    return (props) => {
+      react?.__reset?.();
+      return component(props);
+    };
+  };
+  const ctx = {
+    slots: {
+      inject: (name, register) => {
+        const value = register();
+        registrations.push({ name, value });
+        return value;
+      },
+      register: (spec, component) => {
+        registrations.push({ name: spec.name, spec, component: wrap(component) });
+        return component;
+      }
+    },
+    locale: {
+      register: (namespace, code, dictionary) => {
+        dictionaries.set(`${namespace}/${code}`, dictionary);
+        return () => {};
+      },
+      bind: (namespace) => (key) => {
+        for (const [id, dictionary] of dictionaries) {
+          if (id.startsWith(`${namespace}/`) && typeof dictionary[key] === "string") return dictionary[key];
+        }
+        return key;
+      }
+    },
+    effect: (fn) => {
+      try {
+        return fn();
+      } catch {
+        return undefined;
+      }
+    },
+    get: () => undefined
+  };
+  return { ctx, registrations, dictionaries };
+}
+
+/**
+ * Stubs the browser fetch the client uses for the host routes, so the client can
+ * exercise its settings and model catalog paths without a dsh host.
+ */
+export function stubFetch(routes = {}) {
+  const calls = [];
+  const original = globalThis.fetch;
+  const table = new Map(Object.entries(routes));
+  globalThis.fetch = async (input, init) => {
+    const url = String(input);
+    calls.push({ url, method: init?.method ?? "GET" });
+    const handler = table.get(url);
+    if (handler === undefined) {
+      return new Response("not found", { status: 404, headers: { "content-type": "text/plain" } });
+    }
+    const answer = typeof handler === "function" ? await handler(init) : handler;
+    const body = typeof answer === "string" ? answer : JSON.stringify(answer);
+    return new Response(body, { status: 200, headers: { "content-type": "application/json" } });
+  };
+  return {
+    calls,
+    set: (url, handler) => table.set(url, handler),
+    restore: () => {
+      globalThis.fetch = original;
+    }
+  };
+}
+
+/** Walks a rendered element tree and returns every node matching the predicate. */
+export function walk(node, predicate, found = []) {
+  if (node === null || node === undefined || typeof node === "boolean") return found;
+  if (Array.isArray(node)) {
+    for (const item of node) walk(item, predicate, found);
+    return found;
+  }
+  if (typeof node !== "object") return found;
+  if (predicate(node)) found.push(node);
+  for (const child of node.children ?? []) walk(child, predicate, found);
+  return found;
+}
+
+export function textOf(node) {
+  if (node === null || node === undefined || typeof node === "boolean") return "";
+  if (typeof node === "string" || typeof node === "number") return String(node);
+  if (Array.isArray(node)) return node.map((item) => textOf(item)).join(" ");
+  return (node.children ?? []).map((item) => textOf(item)).join(" ");
+}
+
+export { root };

package/scripts/harness.mjs

@@ -0,0 +1,96 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import path from "node:path";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const suiteDir = path.join(here, "suite");
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+export const pkg = JSON.parse(readFileSync(path.join(repoRoot, "package.json"), "utf8"));
+export const pluginId = pkg.name;
+export const isDevCopy = pluginId.endsWith("-dev");
+
+export const results = [];
+let currentSuite = "";
+
+export function suite(name) {
+  currentSuite = name;
+  results.push({ suite: name, cases: [] });
+}
+
+export function test(name, fn) {
+  const entry = results.at(-1);
+  const caseEntry = { name, ok: true, error: undefined };
+  entry.cases.push(caseEntry);
+  try {
+    const outcome = fn();
+    if (outcome && typeof outcome.then === "function") {
+      return outcome.then(
+        () => {},
+        (error) => {
+          caseEntry.ok = false;
+          caseEntry.error = error;
+        }
+      );
+    }
+  } catch (error) {
+    caseEntry.ok = false;
+    caseEntry.error = error;
+  }
+  return undefined;
+}
+
+export function assert(condition, message) {
+  if (!condition) throw new Error(message ?? "assertion failed");
+}
+
+export function assertEqual(actual, expected, message) {
+  const a = JSON.stringify(actual);
+  const b = JSON.stringify(expected);
+  if (a !== b) throw new Error(`${message ?? "values differ"}\n  expected: ${b}\n  actual:   ${a}`);
+}
+
+export function assertIncludes(haystack, needle, message) {
+  if (!String(haystack).includes(needle)) {
+    throw new Error(`${message ?? "missing substring"}: ${JSON.stringify(String(haystack).slice(0, 220))} does not include ${JSON.stringify(needle)}`);
+  }
+}
+
+export function assertMatch(value, pattern, message) {
+  if (!pattern.test(String(value))) {
+    throw new Error(`${message ?? "pattern mismatch"}: ${JSON.stringify(String(value).slice(0, 220))} does not match ${pattern}`);
+  }
+}
+
+export function assertThrows(fn, message) {
+  let threw = false;
+  try {
+    fn();
+  } catch {
+    threw = true;
+  }
+  if (!threw) throw new Error(message ?? "expected a throw");
+}
+
+export async function run() {
+  const files = readdirSync(suiteDir).filter((name) => name.endsWith(".test.mjs")).sort();
+  for (const file of files) {
+    await import(pathToFileURL(path.join(suiteDir, file)).href);
+  }
+  let passed = 0;
+  let failed = 0;
+  for (const entry of results) {
+    const failures = entry.cases.filter((item) => !item.ok);
+    passed += entry.cases.length - failures.length;
+    failed += failures.length;
+    const mark = failures.length === 0 ? "PASS" : "FAIL";
+    console.log(`${mark}  ${entry.suite} (${entry.cases.length - failures.length}/${entry.cases.length})`);
+    for (const item of failures) {
+      const detail = item.error instanceof Error ? item.error.message : String(item.error);
+      console.log(`      ✗ ${item.name}`);
+      for (const line of detail.split("\n")) console.log(`        ${line}`);
+    }
+  }
+  console.log(`\n${passed} passed, ${failed} failed`);
+  return failed === 0 ? 0 : 1;
+}

package/scripts/suite/client.test.mjs

@@ -0,0 +1,218 @@
+import { suite, test, assert, assertEqual, assertIncludes, assertMatch } from "../harness.mjs";
+import { loadClient, fakeSlotHost, stubFetch, walk, textOf, memoryStorage } from "../client-harness.mjs";
+
+suite("client: rendering, dictionaries and persistence");
+
+function settingsTree(client, props = {}) {
+  const { ctx, registrations } = fakeSlotHost(client.react);
+  client.instance.apply(ctx);
+  const settings = registrations.find((entry) => entry.spec?.name === "settings.section");
+  assert(settings !== undefined, "the settings section is registered");
+  return { tree: settings.component({ t: (key) => key, ...props }), ctx, registrations };
+}
+
+test("the client module registers itself under its own id", () => {
+  const { moduleId } = loadClient();
+  assertEqual(moduleId, "dsh-nextsteps");
+});
+
+test("the client asks for the services it uses", () => {
+  const { instance } = loadClient();
+  assert(Array.isArray(instance.inject), "the client declares its inject list");
+  assert(instance.inject.includes("slots"), "the client needs the slots service");
+  assert(instance.inject.includes("locale"), "the client needs the locale service");
+});
+
+test("the client registers the three dictionaries", () => {
+  const client = loadClient();
+  const { ctx, dictionaries } = fakeSlotHost(client.react);
+  client.instance.apply(ctx);
+  const codes = [...dictionaries.keys()].map((key) => key.split("/")[1]);
+  for (const lang of ["en", "pt-BR", "zh-CN"]) {
+    assert(codes.includes(lang), `the ${lang} dictionary is registered`);
+  }
+});
+
+test("the settings section renders every control", () => {
+  const client = loadClient();
+  const fetchStub = stubFetch({
+    "/api/dsh-nextsteps.settings": { ok: true, settings: { lang: "auto", maxFollowups: 3, showHeader: true, model: "" }, version: "1.0.0" },
+    "/api/dsh-nextsteps.models": { ok: true, groups: [] },
+    "/api/dsh-nextsteps.update": { name: "dsh-nextsteps", current: "1.0.0", newer: false }
+  });
+  try {
+    const { tree } = settingsTree(client);
+    const selects = walk(tree, (node) => node.type === "select");
+    const inputs = walk(tree, (node) => node.type === "input");
+    const buttons = walk(tree, (node) => node.type === "button");
+    assert(selects.length >= 1, "the settings page has a select");
+    assert(inputs.length >= 2, "the followup count and the header toggle are inputs");
+    assert(buttons.length >= 1, "the update row has its buttons");
+  } finally {
+    fetchStub.restore();
+  }
+});
+
+test("the language select offers every language the host accepts", () => {
+  const client = loadClient();
+  const fetchStub = stubFetch({
+    "/api/dsh-nextsteps.settings": { ok: true, settings: { lang: "auto", maxFollowups: 3, showHeader: true, model: "" }, version: "1.0.0" },
+    "/api/dsh-nextsteps.models": { ok: true, groups: [] },
+    "/api/dsh-nextsteps.update": { name: "dsh-nextsteps", current: "1.0.0", newer: false }
+  });
+  try {
+    const { tree } = settingsTree(client);
+    const languageSelect = walk(tree, (node) => node.type === "select" && node.props["aria-label"] === "setLanguage")[0];
+    assert(languageSelect !== undefined, "the language select is labelled");
+    const values = languageSelect.children.map((child) => child.props.value);
+    assertEqual(values.length, 16, "auto plus fifteen languages");
+    for (const expected of ["auto", "en", "pt-BR", "zh-CN", "es", "fr", "de", "ja", "ko", "ru", "ar", "hi", "tr", "vi"]) {
+      assert(values.includes(expected), `the language select offers ${expected}`);
+    }
+  } finally {
+    fetchStub.restore();
+  }
+});
+
+test("the model row explains an empty catalog instead of waiting forever", () => {
+  const client = loadClient();
+  const fetchStub = stubFetch({
+    "/api/dsh-nextsteps.settings": { ok: true, settings: { lang: "auto", maxFollowups: 3, showHeader: true, model: "" }, version: "1.0.0" },
+    "/api/dsh-nextsteps.models": { ok: true, groups: [] },
+    "/api/dsh-nextsteps.update": { name: "dsh-nextsteps", current: "1.0.0", newer: false }
+  });
+  try {
+    const { tree } = settingsTree(client);
+    const rows = walk(tree, (node) => node.type === "div" && typeof node.props.title === "string");
+    const modelRow = rows.find((node) => node.props.title === "setModelTip");
+    assert(modelRow !== undefined, "the model row is rendered");
+    const text = textOf(modelRow);
+    assert(text.length > 0, "the model row explains itself");
+  } finally {
+    fetchStub.restore();
+  }
+});
+
+test("the followup count input keeps the bounds", () => {
+  const client = loadClient();
+  const fetchStub = stubFetch({
+    "/api/dsh-nextsteps.settings": { ok: true, settings: { lang: "auto", maxFollowups: 3, showHeader: true, model: "" }, version: "1.0.0" },
+    "/api/dsh-nextsteps.models": { ok: true, groups: [] },
+    "/api/dsh-nextsteps.update": { name: "dsh-nextsteps", current: "1.0.0", newer: false }
+  });
+  try {
+    const { tree } = settingsTree(client);
+    const count = walk(tree, (node) => node.type === "input" && node.props.type === "number")[0];
+    assert(count !== undefined, "the followup count is a number input");
+    assertEqual(count.props.min, 1);
+    assertEqual(count.props.max, 6);
+  } finally {
+    fetchStub.restore();
+  }
+});
+
+test("the turn tail and the tool view are registered as slots", () => {
+  const client = loadClient();
+  const { ctx, registrations } = fakeSlotHost(client.react);
+  client.instance.apply(ctx);
+  const names = registrations.map((entry) => entry.spec?.name ?? entry.name);
+  assert(names.includes("conversation.chat.turnTail"), "the tail slot is registered");
+  assert(names.includes("tool.call.toolview"), "the tool view slot is registered");
+  assert(names.includes("settings.section"), "the settings section is registered");
+});
+
+test("the captures survive a reload of the client", () => {
+  const storage = memoryStorage();
+  const client = loadClient({ storage });
+  const { ctx, registrations } = fakeSlotHost(client.react);
+  client.instance.apply(ctx);
+  const capture = registrations.find((entry) => entry.spec?.name === "tool.call.toolview");
+  assert(capture !== undefined, "the capture is registered");
+  capture.component({
+    sessionId: "s1",
+    callId: "call-1",
+    block: {
+      kind: "tool-result",
+      callId: "call-1",
+      name: "suggest_followups",
+      content: [{ type: "text", text: '{"rev":"sf-2","followups":[{"prompt":"Rodar o build","label":"Rodar build"}]}' }]
+    }
+  });
+  const key = Object.keys(storage._data).find((name) => name.includes("captures"));
+  assert(key !== undefined, "the captures are stored under a plugin owned key");
+  assert(key.includes("dsh-nextsteps"), "the captures key belongs to the plugin");
+  const parsed = JSON.parse(storage._data[key]);
+  const entry = parsed.s1["call-1"];
+  assert(entry !== undefined, "the capture is stored under its session and call");
+  assertEqual(entry.followups[0].label, "Rodar build");
+});
+
+test("a capture without a turn keeps no turn", () => {
+  const storage = memoryStorage();
+  const client = loadClient({ storage });
+  const { ctx, registrations } = fakeSlotHost(client.react);
+  client.instance.apply(ctx);
+  const capture = registrations.find((entry) => entry.spec?.name === "tool.call.toolview");
+  capture.component({
+    sessionId: "s2",
+    callId: "call-2",
+    block: {
+      kind: "tool-result",
+      callId: "call-2",
+      name: "suggest_followups",
+      content: [{ type: "text", text: '{"rev":"sf-2","followups":[{"prompt":"p2","label":"l2"}]}' }]
+    }
+  });
+  const key = Object.keys(storage._data).find((name) => name.includes("captures"));
+  const parsed = JSON.parse(storage._data[key]);
+  assert(parsed.s2["call-2"].turn === undefined, "a capture without a turn keeps no turn");
+});
+
+test("the tail renders no card for a turn without a capture", () => {
+  const client = loadClient();
+  const fetchStub = stubFetch({});
+  const { ctx, registrations } = fakeSlotHost(client.react);
+  client.instance.apply(ctx);
+  const tail = registrations.find((entry) => entry.spec?.name === "conversation.chat.turnTail");
+  assert(tail !== undefined, "the tail is registered");
+  const tree = tail.component({ sessionId: "s1", turn: { turn: 3, end: { seq: 12 } }, t: (key) => key });
+  const cards = walk(tree, (node) => String(node.props?.className ?? "").includes("dsh-sf-card"));
+  assertEqual(cards.length, 0, "a turn without a capture renders no card");
+  fetchStub.restore();
+});
+
+test("the client asks the host for its settings and its model catalog", async () => {
+  const client = loadClient({ routes: {
+    "/api/dsh-nextsteps.settings": { ok: true, settings: { lang: "auto", maxFollowups: 3, showHeader: true, model: "" }, version: "1.0.0" },
+    "/api/dsh-nextsteps.models": { ok: true, groups: [] },
+    "/api/dsh-nextsteps.update": { name: "dsh-nextsteps", current: "1.0.0", newer: false }
+  } });
+  try {
+    const { ctx } = fakeSlotHost(client.react);
+    client.instance.apply(ctx);
+    await new Promise((resolve) => setTimeout(resolve, 30));
+    const urls = fetchStub.calls.map((call) => call.url);
+    assert(urls.some((url) => url.includes("/settings")), "the client reads the settings");
+    assert(urls.some((url) => url.includes("/models")), "the client reads the model catalog");
+    assert(urls.every((url) => url.startsWith("/api/dsh-nextsteps.")), "the client only calls its own routes");
+  } finally {
+    fetchStub.restore();
+  }
+});
+
+test("the client survives a host that answers with an empty body", async () => {
+  const client = loadClient();
+  const fetchStub = stubFetch({
+    "/api/dsh-nextsteps.settings": "",
+    "/api/dsh-nextsteps.models": "",
+    "/api/dsh-nextsteps.update": ""
+  });
+  try {
+    const { ctx } = fakeSlotHost(client.react);
+    client.instance.apply(ctx);
+    await new Promise((resolve) => setTimeout(resolve, 30));
+    assert(true, "an empty answer does not break the client");
+  } finally {
+    fetchStub.restore();
+  }
+});

package/scripts/suite/contract.test.mjs

@@ -0,0 +1,64 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { suite, test, assert, assertEqual, assertIncludes, pluginId } from "../harness.mjs";
+import { root } from "../client-harness.mjs";
+
+suite("contract: host and client agree");
+
+const clientSource = readFileSync(path.join(root, "client.js"), "utf8");
+const hostSource = readFileSync(path.join(root, "index.js"), "utf8");
+const escaped = pluginId.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const routePattern = new RegExp(`'/api/${escaped}\\.([a-z]+)'`, "g");
+
+const CLIENT_ROUTES = [...clientSource.matchAll(routePattern)].map((match) => match[1]);
+const HOST_ROUTES = [...hostSource.matchAll(routePattern)].map((match) => match[1]);
+
+test("every route the client calls is registered by the host", () => {
+  assert(CLIENT_ROUTES.length > 0, "the client calls host routes");
+  for (const route of CLIENT_ROUTES) {
+    assert(HOST_ROUTES.includes(route), `the host registers the ${route} route`);
+  }
+});
+
+test("the host registers no route the client never calls", () => {
+  for (const route of HOST_ROUTES) {
+    assert(CLIENT_ROUTES.includes(route), `the client calls the ${route} route`);
+  }
+});
+
+test("the settings the client sends are the ones the host reads", () => {
+  const clientSends = [...clientSource.matchAll(/save\(\{ ([a-zA-Z]+):/g)].map((match) => match[1]);
+  assert(clientSends.length > 0, "the client sends settings");
+  for (const key of clientSends) {
+    assert(hostSource.includes(`${key}:`), `the host reads the ${key} setting`);
+  }
+});
+
+test("the settings the host stores are the ones the client renders", () => {
+  const hostStores = [...hostSource.matchAll(/^\s{6}(lang|maxFollowups|showHeader|model):/gm)].map((match) => match[1]);
+  for (const key of new Set(hostStores)) {
+    assert(clientSource.includes(key), `the client renders the ${key} setting`);
+  }
+});
+
+test("the plugin identity is the same on both halves", () => {
+  assertIncludes(clientSource, `id: '${pluginId}',`, "the client registers the plugin id");
+  assertIncludes(hostSource, `const name = '${pluginId}';`, "the host registers the plugin name");
+  assertIncludes(hostSource, `const NPM_NAME = '${pluginId}';`, "the host watches the npm package");
+});
+
+test("the storage keys belong to the plugin", () => {
+  const keys = [...clientSource.matchAll(/['"](dsh[.-][a-z0-9.-]+)['"]/g)].map((match) => match[1]);
+  const owned = [...new Set(keys)].filter((key) => key.includes("suggest-followups") || key.includes("nextsteps"));
+  assert(owned.length >= 2, "the client owns the clicked and the captures storage");
+  for (const key of owned) {
+    assert(key.includes(pluginId), `the storage key belongs to the plugin: ${key}`);
+  }
+});
+
+test("the client tolerates any payload revision", () => {
+  const hostRevision = hostSource.match(/PLUGIN_REV = '([a-z0-9-]+)'/)?.[1];
+  assert(hostRevision !== undefined, "the host declares a payload revision");
+  assert(clientSource.includes("rev"), "the client reads the payload revision");
+  assert(!clientSource.includes(`rev: '${hostRevision}'`), "the client does not pin one revision");
+});

package/scripts/suite/host.test.mjs

@@ -0,0 +1,291 @@
+import { readFileSync, mkdtempSync, rmSync, mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { suite, test, assert, assertEqual, assertIncludes, assertMatch, pluginId, isDevCopy } from "../harness.mjs";
+import { root } from "../client-harness.mjs";
+
+suite("host: tool, settings and routes");
+
+const moduleUrl = new URL(`../../index.js?test=${Date.now()}`, import.meta.url);
+
+function stubContext({ services, llmModels, llmText } = {}) {
+  const defaults = { systemPrompt: { section: (spec) => sections.push(spec) } };
+  const resolved = { ...defaults, ...services };
+  const warnings = [];
+  const originalWarn = console.warn;
+  console.warn = (...args) => { warnings.push(args.join(" ")); };
+  const registered = [];
+  const routes = new Map();
+  const sections = [];
+  const ctx = {
+    tools: {
+      register: (spec) => {
+        registered.push(spec);
+        return () => {};
+      },
+      unregister: () => {}
+    },
+    connection: { fetch: { register: (route) => routes.set(route.path, route) } },
+    effect: (fn) => {
+      try {
+        return fn();
+      } catch {
+        return undefined;
+      }
+    },
+    get: (name) => resolved[name]
+  };
+  if (llmModels !== undefined || llmText !== undefined) {
+    ctx.get = (name) => {
+      if (name === "llm") {
+        return {
+          listProviders: () => [{ id: "demo", name: "Demo" }],
+          listModels: async () => llmModels ?? [{ id: "demo-model", name: "Demo Model" }],
+          prepareCall: async (route) => ({
+            config: { provider: route.provider, model: route.model },
+            stream: async function* () {
+              yield { type: "text-delta", text: llmText ?? '{"followups":[{"prompt":"p","label":"l"}]}' };
+              yield { type: "finish", reason: { kind: "stop" } };
+            }
+          })
+        };
+      }
+      return resolved[name];
+    };
+  }
+  console.warn = originalWarn;
+  return { ctx, registered, routes, sections, warnings };
+}
+
+function settingsFileFor(name) {
+  const dir = mkdtempSync(path.join(tmpdir(), "dsh-nextsteps-test-"));
+  const file = path.join(dir, `${name}.json`);
+  return { dir, file };
+}
+
+test("the tool registers with the schema the model needs", async () => {
+  const { ctx, registered } = stubContext();
+  const mod = await import(moduleUrl.href);
+  await mod.apply(ctx);
+  assert(registered.length === 1, "exactly one tool is registered");
+  const tool = registered[0];
+  assertEqual(tool.name, "suggest_followups");
+  assert(tool.parameters.properties.followups.items.required.includes("prompt"), "each followup requires a prompt");
+  assertIncludes(tool.description, "BEFORE writing your final answer", "the tool must be called before the final answer");
+});
+
+test("the description survives a host without a system prompt service", async () => {
+  const { ctx, registered } = stubContext();
+  const mod = await import(moduleUrl.href);
+  await mod.apply(ctx);
+  const description = registered[0].description;
+  assertIncludes(description, "when there is no such section, use the language of the conversation", "the description must fall back to the conversation language");
+});
+
+test("the bundle does not require optional host services to load", async () => {
+  const source = readFileSync(path.join(root, "index.js"), "utf8");
+  const injectLine = source.split("\n").find((line) => line.startsWith("const inject ="));
+  assertMatch(injectLine, /'tools'/, "the tools service is required");
+  assert(!injectLine.includes("sessionQuery"), "sessionQuery must not be required to load the bundle");
+  assert(!injectLine.includes("systemPrompt"), "systemPrompt must not be required to load the bundle");
+});
+
+test("every route declares a buffered request body", async () => {
+  const { ctx, routes } = stubContext();
+  const mod = await import(moduleUrl.href);
+  await mod.apply(ctx);
+  assert(routes.size >= 4, "the plugin registers its routes");
+  for (const [routePath, route] of routes) {
+    assertEqual(route.requestBody, "buffered", `${routePath} must declare a buffered request body`);
+  }
+});
+
+test("the settings route answers with the current settings and the version", async () => {
+  const { ctx, routes } = stubContext();
+  const mod = await import(moduleUrl.href);
+  await mod.apply(ctx);
+  const response = await routes.get(`/api/${pluginId}.settings`).fetch(new Request("http://x"));
+  const body = await response.json();
+  assertEqual(response.status, 200);
+  assertEqual(body.ok, true);
+  assert(body.version !== undefined, "the settings route reports the version");
+  assert(body.settings.lang !== undefined && body.settings.model !== undefined, "the settings carry the language and the model");
+});
+
+test("the settings route rejects a language it does not know", async () => {
+  const { ctx, routes } = stubContext();
+  const mod = await import(moduleUrl.href);
+  await mod.apply(ctx);
+  const route = routes.get(`/api/${pluginId}.settings`);
+  const before = await (await route.fetch(new Request("http://x"))).json();
+  const response = await route.fetch(new Request("http://x", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ lang: "klingon" })
+  }));
+  const after = await response.json();
+  assertEqual(after.settings.lang, before.settings.lang, "an unknown language keeps the current one");
+});
+
+test("the settings route keeps a model as provider/model", async () => {
+  const { ctx, routes } = stubContext();
+  const mod = await import(moduleUrl.href);
+  await mod.apply(ctx);
+  const route = routes.get(`/api/${pluginId}.settings`);
+  const response = await route.fetch(new Request("http://x", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ model: "demo/demo-model" })
+  }));
+  const body = await response.json();
+  assertEqual(body.settings.model, "demo/demo-model");
+});
+
+test("the model catalog lists the providers the host offers", async () => {
+  const { ctx, routes } = stubContext({ llmModels: [{ id: "demo-model", name: "Demo Model" }] });
+  const mod = await import(moduleUrl.href);
+  await mod.apply(ctx);
+  const response = await routes.get(`/api/${pluginId}.models`).fetch(new Request("http://x"));
+  const body = await response.json();
+  assertEqual(body.ok, true);
+  assertEqual(body.groups.length, 1);
+  assertEqual(body.groups[0].models[0].id, "demo-model");
+});
+
+test("the model catalog stays empty instead of failing when the host offers no models", async () => {
+  const { ctx, routes } = stubContext();
+  const mod = await import(moduleUrl.href);
+  await mod.apply(ctx);
+  const response = await routes.get(`/api/${pluginId}.models`).fetch(new Request("http://x"));
+  const body = await response.json();
+  assertEqual(response.status, 200);
+  assertEqual(body.groups, []);
+});
+
+test("the system prompt section states the language and the count", async () => {
+  const { ctx, sections } = stubContext();
+  const mod = await import(moduleUrl.href);
+  await mod.apply(ctx);
+  assert(sections.length === 1, "one system prompt section");
+  const text = sections[0].text();
+  assertIncludes(text, "nextsteps", "the section names itself");
+  assertIncludes(text, "followup prompts", "the section explains the count");
+});
+
+test("the generation route answers with the suggestions of the chosen model", async () => {
+  const events = [
+    { seq: 1, type: "user/message", data: { content: [{ type: "text", text: "me ajuda com o build" }], source: { kind: "user" } } },
+    { seq: 9, type: "turn/end", data: { turn: 1, reason: { kind: "completed" } } }
+  ];
+  const sessionQuery = { observeSession: async () => ({ events, [Symbol.dispose]: () => {} }) };
+  const { ctx, routes } = stubContext({
+    services: { sessionQuery },
+    llmText: '{"followups":[{"prompt":"Rodar o build","label":"Rodar build"}]}'
+  });
+  const mod = await import(moduleUrl.href);
+  await mod.apply(ctx);
+  const response = await routes.get(`/api/${pluginId}.generate`).fetch(new Request("http://x", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ sessionId: "s1", afterSeq: 9 })
+  }));
+  const body = await response.json();
+  assertEqual(response.status, 200);
+  assertEqual(body.followups.length, 1);
+  assertEqual(body.followups[0].label, "Rodar build");
+});
+
+test("the generation route reads the real session event shape", async () => {
+  let seen = "";
+  const events = [
+    { seq: 1, type: "user/message", data: { content: [{ type: "text", text: "pergunta do usuario" }], source: { kind: "user" } } },
+    { seq: 2, type: "user/message", data: { content: [{ type: "text", text: "<system-reminder>ruído</system-reminder>" }], source: { kind: "time-context" } } },
+    { seq: 3, type: "assistant/message", data: { message: { content: [{ type: "text", text: "resposta do assistente" }] } } },
+    { seq: 9, type: "turn/end", data: { turn: 1, reason: { kind: "completed" } } }
+  ];
+  const sessionQuery = {
+    observeSession: async () => ({
+      events,
+      [Symbol.dispose]: () => {}
+    })
+  };
+  const llm = {
+    listProviders: () => [{ id: "demo", name: "Demo" }],
+    listModels: async () => [{ id: "demo-model", name: "Demo Model" }],
+    prepareCall: async (route) => ({
+      config: route,
+      stream: async function* () {
+        seen = route.prompt ?? "";
+        yield { type: "text-delta", text: '{"followups":[{"prompt":"p","label":"l"}]}' };
+        yield { type: "finish", reason: { kind: "stop" } };
+      }
+    })
+  };
+  const { ctx, routes } = stubContext({ services: { sessionQuery } });
+  ctx.get = (name) => (name === "llm" ? llm : name === "sessionQuery" ? sessionQuery : undefined);
+  const mod = await import(moduleUrl.href);
+  await mod.apply(ctx);
+  const response = await routes.get(`/api/${pluginId}.generate`).fetch(new Request("http://x", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ sessionId: "s1", afterSeq: 9 })
+  }));
+  assertEqual(response.status, 200);
+});
+
+test("the generation route refuses a body it cannot use", async () => {
+  const { ctx, routes } = stubContext();
+  const mod = await import(moduleUrl.href);
+  await mod.apply(ctx);
+  const route = routes.get(`/api/${pluginId}.generate`);
+  const missing = await route.fetch(new Request("http://x", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ afterSeq: 3 })
+  }));
+  assertEqual(missing.status, 400);
+  const broken = await route.fetch(new Request("http://x", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: "not json"
+  }));
+  assertEqual(broken.status, 400);
+});
+
+test("the generation route answers cleanly when the host has no session query service", async () => {
+  const { ctx, routes } = stubContext();
+  const mod = await import(moduleUrl.href);
+  await mod.apply(ctx);
+  const response = await routes.get(`/api/${pluginId}.generate`).fetch(new Request("http://x", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ sessionId: "s1", afterSeq: 3 })
+  }));
+  assertEqual(response.status, 502);
+  const body = await response.json();
+  assertIncludes(body.error, "sessionQuery", "the error names the missing service");
+});
+
+test("the update route reports the current version", async () => {
+  const release = { tag_name: "v9.9.9", html_url: "https://github.com/klaus-2/dsh-nextsteps/releases/tag/v9.9.9", body: "notes" };
+  const original = globalThis.fetch;
+  globalThis.fetch = async (input) => {
+    const url = String(input);
+    if (url.includes("api.github.com")) return new Response(JSON.stringify(release), { status: 200, headers: { "content-type": "application/json" } });
+    if (url.includes("registry.npmjs.org")) return new Response(JSON.stringify({ version: "9.9.9" }), { status: 200, headers: { "content-type": "application/json" } });
+    return original(input);
+  };
+  try {
+    const { ctx, routes } = stubContext();
+    const mod = await import(moduleUrl.href);
+    await mod.apply(ctx);
+    const response = await routes.get(`/api/${pluginId}.update`).fetch(new Request("http://x"));
+    const body = await response.json();
+    assertEqual(response.status, 200);
+    assertEqual(body.name, pluginId);
+    assert(body.current !== undefined, "the update route reports the current version");
+    assertEqual(body.newer, true, "a newer release is reported");
+  } finally {
+    globalThis.fetch = original;
+  }
+});

package/scripts/suite/package.test.mjs

@@ -0,0 +1,169 @@
+import { readFileSync, readdirSync } from "node:fs";
+import path from "node:path";
+import { suite, test, assert, assertEqual, assertIncludes, assertMatch, pkg, pluginId, isDevCopy } from "../harness.mjs";
+import { root } from "../client-harness.mjs";
+
+suite("package: layout, dictionaries and static safety");
+
+const clientSource = readFileSync(path.join(root, "client.js"), "utf8");
+const hostSource = readFileSync(path.join(root, "index.js"), "utf8");
+const locales = ["en", "pt-BR", "zh-CN"].map((lang) => ({
+  lang,
+  data: JSON.parse(readFileSync(path.join(root, "lib", "locale", `${lang}.json`), "utf8"))
+}));
+
+test("the entrypoints live at the package root", () => {
+  assert(exists(path.join(root, "index.js")), "index.js is at the root");
+  assert(exists(path.join(root, "client.js")), "client.js is at the root");
+  assertEqual(pkg.exports["."], "./index.js");
+  assertEqual(pkg.exports["./client"], "./client.js");
+});
+
+test("every packaged file exists", () => {
+  for (const entry of pkg.files) {
+    const target = path.join(root, entry);
+    const present = exists(target) || existsDirectory(target);
+    assert(present, `the packaged file ${entry} exists`);
+  }
+});
+
+test("the package carries the identity it publishes under", () => {
+  assert(pkg.name === pluginId, "the package name is the plugin identity");
+  assertEqual(pkg.exports["."], "./index.js");
+  assertMatch(pkg.name, /^[a-z0-9][a-z0-9-]*$/, "the package name is npm safe");
+});
+
+test("the release copy is publishable and the development copy is not", () => {
+  if (isDevCopy) {
+    assertEqual(pkg.private, true, "a development copy is never published");
+    assertMatch(pkg.version, /-dev\.\d+$/, "a development copy carries a development version");
+  } else {
+    assert(pkg.private !== true, "the published package is not private");
+    assertMatch(pkg.version, /^\d+\.\d+\.\d+$/, "the published version is semver");
+  }
+});
+
+test("the sources carry no identity from another variant", () => {
+  const foreign = isDevCopy ? "dsh-nextsteps-dev" : "dsh-nextsteps-dev";
+  for (const [name, source] of [["index.js", hostSource], ["client.js", clientSource]]) {
+    const identity = isDevCopy ? "dsh-nextsteps-dev" : "dsh-nextsteps";
+    assert(source.includes(identity), `${name} carries its own identity`);
+    assert(!source.includes(foreign === identity ? "dsh-nextsteps-dev-officially" : foreign), `${name} carries no foreign identity`);
+  }
+});
+
+test("the release check points at the releases of this repository", () => {
+  if (isDevCopy) {
+    assert(hostSource.includes("about:blank"), "a development copy does not poll the release feed");
+  } else {
+    assert(hostSource.includes("/releases/latest"), "the host watches a release feed");
+  }
+});
+
+test("the client does not require a json file", () => {
+  const requires = clientSource.match(/require\(([^)]*)\)/g) ?? [];
+  for (const call of requires) {
+    assert(!call.includes(".json"), `the client must not require a json file: ${call}`);
+  }
+});
+
+test("the client does not depend on a path outside the package", () => {
+  assert(!clientSource.includes("C:/"), "the client has no absolute windows path");
+  assert(!clientSource.includes("C:\\\\"), "the client has no absolute windows path");
+  assert(!/require\(['"]\.\.\//.test(clientSource), "the client requires nothing outside the package");
+});
+
+test("the host keeps its settings inside the dsh home", () => {
+  assertIncludes(hostSource, "homedir()", "the host resolves the dsh home");
+  assert(!/['"]C:[\\/]/.test(hostSource), "the host has no absolute path");
+});
+
+test("the dictionaries carry the same keys", () => {
+  const [reference, ...others] = locales;
+  const referenceKeys = Object.keys(reference.data).sort();
+  for (const other of others) {
+    assertEqual(Object.keys(other.data).sort(), referenceKeys, `${other.lang} carries the same keys as ${reference.lang}`);
+  }
+});
+
+test("every key the client asks for exists in every dictionary", () => {
+  const used = new Set();
+  for (const match of clientSource.matchAll(/\bt\('([a-zA-Z.]+)'\)/g)) used.add(match[1]);
+  assert(used.size > 0, "the client asks for translated strings");
+  for (const { lang, data } of locales) {
+    for (const key of used) {
+      assert(typeof data[key] === "string", `${lang} translates ${key}`);
+    }
+  }
+});
+
+test("every dictionary key is used by the client", () => {
+  const used = new Set();
+  for (const match of clientSource.matchAll(/\bt\('([a-zA-Z.]+)'\)/g)) used.add(match[1]);
+  for (const { lang, data } of locales) {
+    for (const key of Object.keys(data)) {
+      if (key === "meta") continue;
+      assert(used.has(key), `${lang} translates ${key}, which the client asks for`);
+    }
+  }
+});
+
+test("the dictionaries declare their plugin metadata", () => {
+  for (const { lang, data } of locales) {
+    assert(data.meta !== undefined, `${lang} declares meta`);
+    assert(typeof data.meta.title === "string" && data.meta.title !== "", `${lang} declares a title`);
+    assert(typeof data.meta.description === "string" && data.meta.description !== "", `${lang} declares a description`);
+  }
+});
+
+test("the readmes cover the three languages", () => {
+  for (const file of ["README.md", "README.pt-BR.md", "README.zh-CN.md"]) {
+    assert(exists(path.join(root, file)), `${file} exists`);
+  }
+  assertIncludes(readFileSync(path.join(root, "README.md"), "utf8"), "README.pt-BR.md", "the english readme links the others");
+});
+
+test("the plugin declares the client services it needs", () => {
+  assert(pkg.dsh?.client?.platform === "web", "the client runs on the web platform");
+  assert(Array.isArray(pkg.dsh?.client?.inject), "the client inject list is declared");
+  assert(pkg.dsh?.client?.inject.includes("@deepseek-ai/dsh-client-locale"), "the client asks for the locale service");
+});
+
+test("the plugin declares its bundle patch", () => {
+  assert(pkg.dsh?.bundle?.patch === "./cordis.patch.yml", "the bundle patch is declared");
+  const patch = readFileSync(path.join(root, "cordis.patch.yml"), "utf8");
+  assertIncludes(patch, `id: ${pluginId}`, "the patch registers the plugin");
+});
+
+test("the license and the readme are packaged", () => {
+  assert(pkg.files.includes("LICENSE"), "the license is packaged");
+  assert(pkg.files.includes("README.md"), "the readme is packaged");
+  assert(pkg.license !== undefined, "the license is declared");
+});
+
+test("the regression suite is packaged and runnable", () => {
+  assert(pkg.scripts?.test !== undefined, "the package declares a test script");
+  assert(pkg.files.includes("scripts"), "the suite ships with the package");
+  assert(exists(path.join(root, "scripts", "test.mjs")), "the suite entrypoint exists");
+});
+
+function existsDirectory(target) {
+  try {
+    return readdirSync(target).length >= 0;
+  } catch {
+    return false;
+  }
+}
+
+function exists(target) {
+  try {
+    readFileSync(target);
+    return true;
+  } catch {
+    try {
+      return readFileSync(path.join(target, "package.json")) !== undefined;
+    } catch {
+      return false;
+    }
+  }
+}

package/scripts/test.mjs

@@ -0,0 +1,4 @@
+import { run } from "./harness.mjs";
+
+const code = await run();
+process.exit(code);