@indianic/dialout 1.12.1 → 1.13.0

package/node_modules/@indianic/dialout-shared/src/notify-template.test.ts

@@ -0,0 +1,352 @@
+// packages/devdash-shared/src/notify-template.test.ts
+import { describe, it, expect } from 'vitest';
+import {
+  renderNotification, parseActions, categoryId, DEFAULT_TEMPLATES,
+  TEMPLATE_VARIABLES, NOTIFICATION_TYPES, parseTemplatePatch, shouldSendNotification,
+  folderLabel, isSendable,
+} from './notify-template';
+
+describe('renderNotification', () => {
+  // The old hardcoded title chose between these two; a single template string
+  // cannot, so {what} carries it. Guards against "finished" reading as blocked.
+  it('default ai_question title keeps "needs you" distinct from "finished"', () => {
+    const t = DEFAULT_TEMPLATES.ai_question;
+    expect(renderNotification(t, { agent: 'Claude', what: 'needs you' }, 'UTC').title).toBe('Claude needs you');
+    expect(renderNotification(t, { agent: 'Claude', what: 'finished' }, 'UTC').title).toBe('Claude finished');
+  });
+
+  // The old hardcoded body had a fallback for each missing half; the values
+  // now carry them (folder -> 'session'), so no case may render empty and a
+  // finished session must still name its CLI.
+  it('default ai_question body is never empty and always names the CLI', () => {
+    const t = DEFAULT_TEMPLATES.ai_question;
+    const body = (question: string, folder: string) =>
+      renderNotification(t, { agent: 'Claude', what: 'finished', kind: 'claude', question, folder }, 'UTC').body;
+    expect(body('Q', 'dialout')).toBe('Q · claude · dialout');
+    expect(body('Q', 'session')).toBe('Q · claude · session');
+    expect(body('', 'dialout')).toBe('claude · dialout');
+    expect(body('', 'session')).toBe('claude · session');
+  });
+
+  it('substitutes the variables it is given', () => {
+    expect(renderNotification(
+      { title: '{agent} needs you', body: '{question} · {folder}' },
+      { agent: 'Claude', question: 'Run the migration?', folder: 'dialout' },
+      'UTC',
+    )).toEqual({ title: 'Claude needs you', body: 'Run the migration? · dialout' });
+  });
+
+  // A notification showing its own template syntax on a lock screen is worse
+  // than one with a gap in it.
+  it('renders an unknown or missing variable as empty, never as its own name', () => {
+    const r = renderNotification({ title: 'Hi {nobody}', body: '{alsoNobody}' }, {}, 'UTC');
+    expect(r.title).toBe('Hi');
+    expect(r.body).toBe('');
+    expect(r.title).not.toContain('{');
+  });
+
+  it('treats a null or undefined value as missing', () => {
+    expect(renderNotification({ title: 'a{x}b', body: '' }, { x: null }, 'UTC').title).toBe('ab');
+    expect(renderNotification({ title: 'a{x}b', body: '' }, { x: undefined }, 'UTC').title).toBe('ab');
+  });
+
+  // Emptying a variable otherwise strands the separator that was joining it to
+  // the next thing, and "Run it? · " reads as truncation.
+  it('collapses a separator left stranded by an empty variable', () => {
+    expect(renderNotification(
+      { title: 'x', body: '{question} · {folder}' },
+      { question: 'Run it?' },
+      'UTC',
+    ).body).toBe('Run it?');
+    expect(renderNotification(
+      { title: 'x', body: '{a} · {b} · {c}' },
+      { b: 'middle' },
+      'UTC',
+    ).body).toBe('middle');
+  });
+
+  it('collapses runs of whitespace', () => {
+    expect(renderNotification({ title: 'a  {x}   b', body: '' }, {}, 'UTC').title).toBe('a b');
+  });
+
+  it('formats time and date in the given timezone', () => {
+    const vars = { at: '2026-10-29T18:30:00Z' };
+    const utc = renderNotification({ title: '{time}', body: '{date}' }, vars, 'UTC');
+    const ist = renderNotification({ title: '{time}', body: '{date}' }, vars, 'Asia/Kolkata');
+    expect(utc.title).not.toBe(ist.title);
+    expect(ist.title).toMatch(/\d/);
+  });
+
+  // An unknown zone throws inside Intl, and this runs on the notify path.
+  it('falls back to UTC rather than throwing on an unknown timezone', () => {
+    expect(() => renderNotification(
+      { title: '{time}', body: '' }, { at: '2026-10-29T18:30:00Z' }, 'Mars/Olympus',
+    )).not.toThrow();
+  });
+
+  it('caps the title at 80 and the body at 240', () => {
+    const r = renderNotification({ title: '{x}', body: '{x}' }, { x: 'y'.repeat(500) }, 'UTC');
+    expect(r.title).toHaveLength(80);
+    expect(r.body).toHaveLength(240);
+  });
+
+  it('never throws on a template that is not a string', () => {
+    expect(() => renderNotification(
+      { title: undefined as unknown as string, body: null as unknown as string }, {}, 'UTC',
+    )).not.toThrow();
+  });
+
+describe('renderNotification: names that were never supplied', () => {
+  it.each(['constructor', '__proto__', 'toString', 'hasOwnProperty'])(
+    'renders {%s} as nothing',
+    (name) => {
+      expect(renderNotification({ title: `a{${name}}b`, body: `{${name}}` }, {}, 'UTC'))
+        .toEqual({ title: 'ab', body: '' });
+    },
+  );
+
+  it('renders a supplied value that is not a string or number as nothing, without throwing', () => {
+    const vars = { x: { nested: 1 }, y: ['a'], z: true } as unknown as Record<string, string>;
+    expect(renderNotification({ title: 'a{x}b{y}c{z}d', body: '' }, vars, 'UTC').title).toBe('abcd');
+  });
+
+  it('still substitutes a supplied number', () => {
+    const vars = { n: 3 } as unknown as Record<string, string>;
+    expect(renderNotification({ title: 'n={n}', body: '' }, vars, 'UTC').title).toBe('n=3');
+  });
+});
+
+// These guard the marker indirection specifically (surviving placeholders are
+// swapped for private-use markers while the skeleton is tidied). They look
+// redundant next to the verbatim-value tests; do not delete them as such.
+describe('renderNotification: marker indirection', () => {
+  const E0 = '';
+  const E1 = '';
+
+  it('renders values when the template itself contains marker characters, and emits none', () => {
+    const r = renderNotification(
+      { title: `a${E0}{x}${E1}b${E0}0${E1}`, body: `${E0}{y}` }, { x: 'X', y: 'Y' }, 'UTC',
+    );
+    expect(r.title).toBe('aXb0');
+    expect(r.body).toBe('Y');
+    expect(r.title + r.body).not.toMatch(/[]/);
+  });
+
+  it('renders marker-shaped text inside a value literally, without re-scanning it', () => {
+    const lookalike = `${E0}1${E1}`;
+    const r = renderNotification({ title: '', body: '{a} {b}' }, { a: lookalike, b: 'B' }, 'UTC');
+    expect(r.body).toBe(`${lookalike} B`);
+  });
+
+  it('keeps twelve placeholders in their own slots, including adjacent ones', () => {
+    const names = 'abcdefghijkl'.split('');
+    const vars = Object.fromEntries(names.map((n, i) => [n, `v${i}`]));
+    const template = '{a}{b} {c} {d} {e} {f} {g} {h} {i} {j} {k} {l}';
+    const r = renderNotification({ title: '', body: template }, vars, 'UTC');
+    expect(r.body).toBe('v0v1 v2 v3 v4 v5 v6 v7 v8 v9 v10 v11');
+  });
+
+  it('substitutes values verbatim, including surrounding whitespace and newlines', () => {
+    const r = renderNotification({ title: '', body: '[{x}]' }, { x: '  a\nb  ' }, 'UTC');
+    expect(r.body).toBe('[  a\nb  ]');
+  });
+});
+
+describe('renderNotification: vars that are not an object', () => {
+  it.each([null, undefined, 'str', 42, true, ['a']])('does not throw for vars = %j', (v) => {
+    const r = renderNotification({ title: 'a{question}b', body: '{time}' }, v as never, 'UTC');
+    expect(r.title).toBe('ab');
+    expect(r.body).toMatch(/^\d{2}:\d{2}$/);
+  });
+});
+
+describe('renderNotification: a value is never tidied', () => {
+  it.each([
+    'Should I run git push --force?',
+    'Use the --no-verify flag',
+    'Run cmd1 || cmd2 ?',
+    '-rf flag is set',
+    'ends with a dash -',
+    '  spaced   out  ',
+    'a · · b',
+  ])('keeps %j character for character', (q) => {
+    expect(renderNotification({ title: '', body: '{question}' }, { question: q }, 'UTC').body).toBe(q);
+  });
+
+  it('does not let a value inject a placeholder', () => {
+    expect(renderNotification({ title: '', body: '{a}' }, { a: '{b}', b: 'no' }, 'UTC').body).toBe('{b}');
+  });
+
+  it('still tidies the skeleton around a verbatim value', () => {
+    expect(renderNotification({ title: '', body: '{question} · {folder}' }, { question: 'git push --force?' }, 'UTC').body)
+      .toBe('git push --force?');
+    expect(renderNotification({ title: '', body: '{folder} · {question}' }, { question: '-rf' }, 'UTC').body)
+      .toBe('-rf');
+  });
+});
+});
+
+describe('DEFAULT_TEMPLATES', () => {
+  it('covers every type', () => {
+    for (const t of NOTIFICATION_TYPES) expect(DEFAULT_TEMPLATES[t]).toBeDefined();
+  });
+
+  // A template may only use variables its own type supplies, or it renders a
+  // gap on every send.
+  it('only uses variables its own type offers', () => {
+    for (const t of NOTIFICATION_TYPES) {
+      const used = `${DEFAULT_TEMPLATES[t].title} ${DEFAULT_TEMPLATES[t].body}`
+        .match(/\{(\w+)\}/g)?.map((m) => m.slice(1, -1)) ?? [];
+      for (const v of used) expect(TEMPLATE_VARIABLES[t], `${t} uses {${v}}`).toContain(v);
+    }
+  });
+});
+
+describe('categoryId', () => {
+  // SDK 57: a category identifier may contain no ':' or '-', and a hyphen
+  // silently costs the action buttons. ai_question must land on exactly the
+  // string AI_CATEGORY already holds, so notifications in flight during the
+  // deploy keep their Reply button.
+  it('strips underscores and hyphens', () => {
+    expect(categoryId('ai_question')).toBe('aiquestion');
+    expect(categoryId('new_terminal')).toBe('newterminal');
+    expect(categoryId('new_ai_session')).toBe('newaisession');
+    expect(categoryId('announcement')).toBe('announcement');
+  });
+
+  it('never produces an id with a character the SDK rejects', () => {
+    for (const t of NOTIFICATION_TYPES) {
+      expect(categoryId(t)).not.toMatch(/[:-]/);
+    }
+  });
+});
+
+describe('parseActions', () => {
+  it('keeps well-formed actions', () => {
+    expect(parseActions([{ id: 'reply', label: 'Reply', kind: 'reply' }]))
+      .toEqual([{ id: 'reply', label: 'Reply', kind: 'reply' }]);
+  });
+
+  it('parses a JSON string, which is what the jsonb column may hand back', () => {
+    expect(parseActions('[{"id":"open","label":"Open","kind":"open"}]'))
+      .toEqual([{ id: 'open', label: 'Open', kind: 'open' }]);
+  });
+
+  // kind is a closed set so a button cannot be configured to do something the
+  // app has no code for.
+  it('drops an action with an unknown kind', () => {
+    expect(parseActions([{ id: 'x', label: 'X', kind: 'launchMissiles' }])).toEqual([]);
+  });
+
+  it('drops an action missing an id or a label', () => {
+    expect(parseActions([{ label: 'X', kind: 'open' }, { id: 'y', kind: 'open' }])).toEqual([]);
+  });
+
+  it('returns an empty array for anything unusable', () => {
+    for (const bad of [null, undefined, 42, 'not json', {}]) {
+      expect(parseActions(bad)).toEqual([]);
+    }
+  });
+
+  it('caps the list at four, which is what iOS shows', () => {
+    const many = Array.from({ length: 9 }, (_, i) => ({ id: `a${i}`, label: 'A', kind: 'open' }));
+    expect(parseActions(many)).toHaveLength(4);
+  });
+
+  it('drops a duplicate id, which would collide in the response handler', () => {
+    expect(parseActions([
+      { id: 'open', label: 'Open', kind: 'open' },
+      { id: 'open', label: 'Again', kind: 'open' },
+    ])).toHaveLength(1);
+  });
+});
+
+describe('shouldSendNotification', () => {
+  // The feature's central rule, and the one most likely to be re-implemented
+  // wrongly at a third call site. The repo has no route tests — the convention
+  // is pure-logic tests in src/lib/__tests__ — so this is where the gate is
+  // pinned.
+  it('needs both gates to say yes', () => {
+    expect(shouldSendNotification(true, true)).toBe(true);
+  });
+
+  it('sends nothing when the admin has switched the type off', () => {
+    expect(shouldSendNotification(false, true)).toBe(false);
+  });
+
+  it('sends nothing to a device whose owner opted out', () => {
+    expect(shouldSendNotification(true, false)).toBe(false);
+  });
+
+  it('is false when neither says yes', () => {
+    expect(shouldSendNotification(false, false)).toBe(false);
+  });
+});
+
+describe('parseTemplatePatch', () => {
+  it('accepts a partial patch', () => {
+    const r = parseTemplatePatch({ enabled: false, title: ' Hi ' });
+    expect(r).toEqual({ ok: true, patch: { enabled: false, title: 'Hi' } });
+  });
+
+  it('rejects a body that is not an object', () => {
+    expect(parseTemplatePatch(null).ok).toBe(false);
+  });
+
+  it('caps title and body rather than rejecting them', () => {
+    const r = parseTemplatePatch({ title: 'x'.repeat(300), body: 'y'.repeat(900) });
+    expect(r.ok).toBe(true);
+    if (r.ok) {
+      expect(r.patch.title).toHaveLength(80);
+      expect(r.patch.body).toHaveLength(240);
+    }
+  });
+
+  it('normalises actions through parseActions', () => {
+    const r = parseTemplatePatch({ actions: [{ id: 'x', label: 'X', kind: 'nope' }] });
+    expect(r.ok).toBe(true);
+    if (r.ok) expect(r.patch.actions).toEqual([]);
+  });
+});
+
+// The push this wording replaced named a terminal by its folder and fell back
+// to the tmux name. For a browser session the tmux name is dd-<uuid>, so a
+// default built on {terminal} would turn "dialout" into an opaque id.
+describe('default wording for a new session', () => {
+  const tz = 'UTC';
+
+  it('new_terminal names the folder, not the tmux name', () => {
+    const r = renderNotification(DEFAULT_TEMPLATES.new_terminal, {
+      terminal: 'dd-7f3a9c2b4e', folder: 'dialout', machine: 'MacBook Pro',
+    }, tz);
+    expect(r.body).toBe('dialout on MacBook Pro');
+  });
+
+  it('new_ai_session never leaves a gap when the sender has no folder', () => {
+    const vars = { agent: 'dd-ai-x', machine: 'MacBook Pro', folder: folderLabel(null, 'session') };
+    expect(renderNotification(DEFAULT_TEMPLATES.new_ai_session, vars, tz).body)
+      .toBe('dd-ai-x in session on MacBook Pro');
+  });
+});
+
+describe('folderLabel', () => {
+  it('uses the folder when there is one', () => {
+    expect(folderLabel('dialout', 'dd-abc')).toBe('dialout');
+  });
+  it('falls back for null, undefined, empty and whitespace', () => {
+    for (const f of [null, undefined, '', '   ']) expect(folderLabel(f, 'dd-abc')).toBe('dd-abc');
+  });
+});
+
+// A cleared title or body is a deliberate choice, so the sender has to decide
+// what an empty one means rather than discovering it on a lock screen.
+describe('isSendable', () => {
+  it('sends a notification with only a body or only a title', () => {
+    expect(isSendable({ title: '', body: 'Run it?' })).toBe(true);
+    expect(isSendable({ title: 'Agent needs you', body: '' })).toBe(true);
+  });
+  it('does not send one with neither', () => {
+    expect(isSendable({ title: '', body: '' })).toBe(false);
+    expect(isSendable({ title: '  ', body: ' ' })).toBe(false);
+  });
+});

package/node_modules/@indianic/dialout-shared/src/notify-template.ts

@@ -0,0 +1,319 @@
+// packages/devdash-shared/src/notify-template.ts
+
+/**
+ * What an automatic notification says, and the buttons it carries.
+ *
+ * Pure, and here rather than in the ws-server for the same reason the
+ * shouldNotify* family is: src/ws-server/index.ts is one deliberately large
+ * file with no unit seams, so decision and rendering logic added inline there
+ * would be untestable. The ws-server stays the only side-effecting caller.
+ */
+
+export const NOTIFICATION_TYPES = [
+  'ai_question', 'new_terminal', 'new_ai_session', 'announcement',
+] as const;
+export type NotificationType = (typeof NOTIFICATION_TYPES)[number];
+
+/** A closed set, so a configured button cannot ask for behaviour the app lacks. */
+export const ACTION_KINDS = ['open', 'reply'] as const;
+export type ActionKind = (typeof ACTION_KINDS)[number];
+
+export interface NotificationAction {
+  id: string;
+  label: string;
+  kind: ActionKind;
+}
+
+export interface NotificationTemplate {
+  type: NotificationType;
+  enabled: boolean;
+  title: string;
+  body: string;
+  actions: NotificationAction[];
+}
+
+/** Matches src/app/api/push/broadcast/route.ts, and both platforms truncate anyway. */
+export const TITLE_MAX = 80;
+export const BODY_MAX = 240;
+/** iOS shows four actions on an expanded notification. */
+export const MAX_ACTIONS = 4;
+
+/**
+ * Which variables each type can supply. Per type, not global, because they are
+ * not interchangeable: {question} exists for an agent question and not for a
+ * new terminal, and offering it everywhere would produce templates that render
+ * a gap on every send.
+ */
+export const TEMPLATE_VARIABLES: Record<NotificationType, string[]> = {
+  ai_question: ['agent', 'what', 'kind', 'question', 'folder', 'branch', 'machine', 'session', 'time', 'date'],
+  new_terminal: ['machine', 'terminal', 'folder', 'branch', 'time', 'date'],
+  new_ai_session: ['agent', 'machine', 'session', 'folder', 'time', 'date'],
+  // An announcement has no machine, terminal or session behind it. {title} and
+  // {body} are what the admin typed in the compose form; the template supplies
+  // the wrapper and the buttons.
+  announcement: ['title', 'body', 'user', 'time', 'date'],
+};
+
+/**
+ * Today's hardcoded wording, so shipping the feature changes nothing about
+ * what anyone receives. Mirrored in scripts/apply-notification-templates.mjs,
+ * which cannot import the built package — a drift between the two is a visible
+ * difference in a notification rather than a silent failure.
+ */
+export const DEFAULT_TEMPLATES: Record<NotificationType, Omit<NotificationTemplate, 'type'>> = {
+  ai_question: {
+    enabled: true,
+    // {what} is "needs you" or "finished". One template string cannot branch, so
+    // the distinction is a variable: a finished job must not read as a blocked one.
+    title: '{agent} {what}',
+    body: '{question} · {kind} · {folder}',
+    actions: [
+      { id: 'reply', label: 'Reply', kind: 'reply' },
+      { id: 'open', label: 'Open', kind: 'open' },
+    ],
+  },
+  new_terminal: {
+    enabled: true,
+    title: 'New terminal',
+    // {folder}, not {terminal}: the push this replaced named a terminal by its
+    // folder, and for a browser session the tmux name is an opaque dd-<uuid>.
+    // The sender passes folderLabel(folder, tmuxName), so a session with no
+    // folder still reads as its tmux name. {terminal} stays available for an
+    // admin who wants the raw name. These defaults are seeded with DO NOTHING
+    // (scripts/apply-notification-templates.mjs), so a later wording change
+    // never reaches an existing row.
+    body: '{folder} on {machine}',
+    actions: [{ id: 'open', label: 'Open', kind: 'open' }],
+  },
+  new_ai_session: {
+    enabled: true,
+    title: 'New agent session',
+    body: '{agent} in {folder} on {machine}',
+    actions: [{ id: 'open', label: 'Open', kind: 'open' }],
+  },
+  announcement: {
+    enabled: true,
+    title: '{title}',
+    body: '{body}',
+    actions: [],
+  },
+};
+
+/**
+ * The notification category a type registers under.
+ *
+ * Expo SDK 57's setNotificationCategoryAsync documents that an identifier may
+ * contain no `:` or `-`, and the failure is silent — the notification arrives
+ * with no buttons and nothing logs why. Stripping both from the type name
+ * makes `ai_question` land on exactly `aiquestion`, which is the string
+ * AI_CATEGORY already holds and the ws-server already sends, so notifications
+ * in flight during a deploy keep their Reply button.
+ */
+export function categoryId(type: NotificationType): string {
+  return type.replace(/[_:-]/g, '');
+}
+
+/**
+ * The folder a notification should name, or `fallback` when there is none.
+ *
+ * Lives in the sender's vars rather than in the renderer on purpose. The
+ * renderer's rule for an empty variable is "render nothing and take the
+ * neighbouring separator with it", which cannot mend an English word stranded
+ * between two spaces ("agent in  on Mac"). Only the sender knows what a sensible
+ * stand-in is for its type (a tmux name for a terminal, the word "session" for
+ * an agent), so every sender goes through this one function and none passes a
+ * raw nullable folder.
+ */
+export function folderLabel(folder: string | null | undefined, fallback: string): string {
+  return typeof folder === 'string' && folder.trim() !== '' ? folder : fallback;
+}
+
+/**
+ * Whether a rendered notification is worth sending. A title alone or a body
+ * alone is a legitimate choice (an admin can clear either field), but with
+ * neither there is nothing to show: a blank banner is noise, so the sender
+ * skips it instead of discovering the case on a lock screen.
+ */
+export function isSendable(rendered: { title: string; body: string }): boolean {
+  return rendered.title.trim() !== '' || rendered.body.trim() !== '';
+}
+
+export type TemplateVars = Record<string, string | null | undefined>;
+
+function formatIn(iso: string, timezone: string, opts: Intl.DateTimeFormatOptions): string {
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return '';
+  try {
+    return new Intl.DateTimeFormat('en-GB', { ...opts, timeZone: timezone }).format(d);
+  } catch {
+    // An unknown zone throws, and this runs while a push is being rendered.
+    return new Intl.DateTimeFormat('en-GB', { ...opts, timeZone: 'UTC' }).format(d);
+  }
+}
+
+/**
+ * Renders a template's title and body.
+ *
+ * Never throws: it is called on the ws-server's notify path, where an
+ * exception would break the registry upsert chain whose ordering other
+ * sessions depend on.
+ *
+ * `vars.at` is an ISO timestamp used for {time} and {date}; every other key is
+ * substituted literally. An unknown or empty variable renders as nothing and
+ * takes any separator stranded beside it with it.
+ */
+export function renderNotification(
+  template: { title: string; body: string },
+  rawVars: TemplateVars,
+  timezone: string,
+): { title: string; body: string } {
+  // The type forbids null, but "never throws" is this function's contract and
+  // a JS caller or a spread of a possibly-undefined object would otherwise
+  // throw on the ws-server's notify path.
+  const vars: TemplateVars =
+    rawVars && typeof rawVars === 'object' && !Array.isArray(rawVars) ? rawVars : {};
+  const at = typeof vars.at === 'string' ? vars.at : new Date().toISOString();
+  const resolved: TemplateVars = {
+    ...vars,
+    time: formatIn(at, timezone, { hour: '2-digit', minute: '2-digit' }),
+    date: formatIn(at, timezone, { day: 'numeric', month: 'short' }),
+  };
+
+  // Only a value that was explicitly supplied counts, and only a string or a
+  // number. `resolved` is a plain object, so without the own-property check
+  // `{constructor}` or `{__proto__}` would resolve to Object.prototype members
+  // and render "function Object() { [native code] }" on a lock screen.
+  const lookup = (name: string): string => {
+    if (!Object.prototype.hasOwnProperty.call(resolved, name)) return '';
+    const v: unknown = resolved[name];
+    if (typeof v === 'string') return v.trim() === '' ? '' : v;
+    if (typeof v === 'number' && Number.isFinite(v)) return String(v);
+    return '';
+  };
+
+  const one = (raw: unknown, max: number): string => {
+    if (typeof raw !== 'string') return '';
+    // Tidy the template skeleton, then substitute values verbatim. The order is
+    // the point: tidy() collapses "-", "--", "||" and trims leading/trailing
+    // separators, which it cannot tell apart from the same characters inside a
+    // value. Run after substitution it turned an agent's question
+    // "git push --force?" into "git push - force?", so the lock screen showed a
+    // different command from the one being approved, next to a Reply button.
+    // Surviving placeholders stand in as opaque markers while the skeleton is
+    // tidied, and empty ones are dropped with their neighbouring separator.
+    const values: string[] = [];
+    const skeleton = raw
+      .replace(new RegExp(`[${MARK_OPEN}${MARK_CLOSE}]`, 'g'), '')
+      .replace(/\{(\w+)\}/g, (_, name: string) => {
+        const value = lookup(name);
+        if (value === '') return '';
+        values.push(value);
+        return `${MARK_OPEN}${values.length - 1}${MARK_CLOSE}`;
+      });
+    // One pass over the tidied skeleton, never a re-scan of inserted text, so a
+    // value containing "{other}" cannot pull in another variable.
+    const markerRe = new RegExp(`${MARK_OPEN}(\\d+)${MARK_CLOSE}`, 'g');
+    const rendered = tidy(skeleton).replace(markerRe, (_, i: string) => values[Number(i)] ?? '');
+    return rendered.slice(0, max);
+  };
+
+  return { title: one(template?.title, TITLE_MAX), body: one(template?.body, BODY_MAX) };
+}
+
+/** Private-use code points that bracket a surviving placeholder while the skeleton is tidied. */
+const MARK_OPEN = '\uE000';
+const MARK_CLOSE = '\uE001';
+
+/**
+ * Removes what an emptied variable leaves behind. "{question} · {folder}" with
+ * no folder would otherwise end "Run it? · ", which reads as truncation rather
+ * than as an absent field.
+ */
+function tidy(s: string): string {
+  return s
+    // A separator with nothing on one side of it.
+    .replace(/\s*[·|–—-]\s*(?=$)/g, '')
+    .replace(/(?<=^)\s*[·|–—-]\s*/g, '')
+    // A separator with nothing between it and the next one.
+    .replace(/\s*([·|–—-])\s*\1\s*/g, ' $1 ')
+    .replace(/\s*[·|–—-]\s*[·|–—-]\s*/g, ' · ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .replace(/\s*[·|–—-]$/, '')
+    .replace(/^[·|–—-]\s*/, '')
+    .trim();
+}
+
+/** Normalises whatever the jsonb column or a request body hands over. */
+export function parseActions(raw: unknown): NotificationAction[] {
+  let value = raw;
+  if (typeof value === 'string') {
+    try { value = JSON.parse(value); } catch { return []; }
+  }
+  if (!Array.isArray(value)) return [];
+
+  const out: NotificationAction[] = [];
+  const seen = new Set<string>();
+  for (const item of value) {
+    if (!item || typeof item !== 'object') continue;
+    const a = item as Record<string, unknown>;
+    const id = typeof a.id === 'string' ? a.id.trim() : '';
+    const label = typeof a.label === 'string' ? a.label.trim() : '';
+    const kind = a.kind;
+    if (!id || !label) continue;
+    if (!(ACTION_KINDS as readonly unknown[]).includes(kind)) continue;
+    // A duplicate id would collide in the response handler, which switches on
+    // actionIdentifier.
+    if (seen.has(id)) continue;
+    seen.add(id);
+    out.push({ id, label: label.slice(0, 32), kind: kind as ActionKind });
+    if (out.length === MAX_ACTIONS) break;
+  }
+  return out;
+}
+
+export type TemplatePatch = Partial<Pick<NotificationTemplate, 'enabled' | 'title' | 'body' | 'actions'>>;
+
+export type TemplateParseResult =
+  | { ok: true; patch: TemplatePatch }
+  | { ok: false; error: string };
+
+/**
+ * Validates an edit. Text is capped rather than rejected: a long title is the
+ * author's problem to see in the preview, not a reason to refuse the save.
+ */
+export function parseTemplatePatch(body: unknown): TemplateParseResult {
+  if (!body || typeof body !== 'object' || Array.isArray(body)) {
+    return { ok: false, error: 'Expected an object' };
+  }
+  const b = body as Record<string, unknown>;
+  const patch: TemplatePatch = {};
+  if (typeof b.enabled === 'boolean') patch.enabled = b.enabled;
+  if (typeof b.title === 'string') patch.title = b.title.trim().slice(0, TITLE_MAX);
+  if (typeof b.body === 'string') patch.body = b.body.trim().slice(0, BODY_MAX);
+  if ('actions' in b) patch.actions = parseActions(b.actions);
+  return { ok: true, patch };
+}
+
+export function isNotificationType(t: string): t is NotificationType {
+  return (NOTIFICATION_TYPES as readonly string[]).includes(t);
+}
+
+/**
+ * Whether this notification reaches this device. Both gates must say yes.
+ *
+ * `enabled` is the admin's instance-wide switch from notification_templates;
+ * `userOptedIn` is the recipient's own per-device switch from user_settings.
+ * Admin-off means nobody receives the type; user-off means that one device
+ * does not.
+ *
+ * The per-device opt-out is kept deliberately rather than replaced by the
+ * admin switch: App Store guideline 4.5.4 and Play policy both require
+ * announcement push to be refusable, and removing it risks a rejection.
+ *
+ * Trivial on purpose. It exists so the rule has one name and one test instead
+ * of being spelled out at each of the three senders.
+ */
+export function shouldSendNotification(enabled: boolean, userOptedIn: boolean): boolean {
+  return enabled && userOptedIn;
+}