@indianic/dialout 1.12.0 → 1.13.0

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;
+}

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

@@ -46,3 +46,54 @@ export function shouldNotifyPrompt(
   if (lastNotifiedAt && nowMs - lastNotifiedAt < NOTIFY_COOLDOWN_MS) return false;
   return true;
 }
+
+/** Which events a user wants pushed. One flag per event, no nesting. */
+export interface PushPrefs {
+  aiQuestions: boolean;
+  newTerminal: boolean;
+  newAiSession: boolean;
+  announcements: boolean;
+}
+
+/**
+ * Per-subscription, not per-session: whether a session is worth announcing
+ * depends on which device is being told.
+ *
+ * `createdByInstallId` is null for a native tmux shell the agent merely found,
+ * which is the case most worth announcing — so a null creator always notifies,
+ * whatever the subscriber knows about itself. An unknown subscriber (one
+ * registered before install ids existed) also notifies: a missed notification
+ * is a worse failure than one extra.
+ */
+function notifyNewSession(
+  enabled: boolean,
+  subscriberInstallId: string | null,
+  createdByInstallId: string | null,
+  lastNotifiedAt: number | undefined,
+  nowMs: number,
+): boolean {
+  if (!enabled) return false;
+  if (createdByInstallId !== null && subscriberInstallId === createdByInstallId) return false;
+  if (lastNotifiedAt && nowMs - lastNotifiedAt < NOTIFY_COOLDOWN_MS) return false;
+  return true;
+}
+
+export function shouldNotifyNewTerminal(
+  prefs: PushPrefs,
+  subscriberInstallId: string | null,
+  createdByInstallId: string | null,
+  lastNotifiedAt: number | undefined,
+  nowMs: number,
+): boolean {
+  return notifyNewSession(prefs.newTerminal, subscriberInstallId, createdByInstallId, lastNotifiedAt, nowMs);
+}
+
+export function shouldNotifyNewAiSession(
+  prefs: PushPrefs,
+  subscriberInstallId: string | null,
+  createdByInstallId: string | null,
+  lastNotifiedAt: number | undefined,
+  nowMs: number,
+): boolean {
+  return notifyNewSession(prefs.newAiSession, subscriberInstallId, createdByInstallId, lastNotifiedAt, nowMs);
+}

package/node_modules/@indianic/dialout-shared/src/session-announce.test.ts

@@ -0,0 +1,48 @@
+import { describe, it, expect } from 'vitest';
+import { shouldAnnounceSession } from './session-announce';
+
+describe('shouldAnnounceSession', () => {
+  it('announces a session with no prior row at all', () => {
+    expect(shouldAnnounceSession(null, '2026-10-29T09:00:00Z')).toBe(true);
+    expect(shouldAnnounceSession(null, null)).toBe(true);
+  });
+
+  // The reported bug. The agent reconnects, the row was marked ended, and the
+  // same tmux session is re-reported — it is not news.
+  it('stays quiet when the prior row is the same session by creation time', () => {
+    expect(shouldAnnounceSession(
+      { endedAt: '2026-10-29T08:00:00Z', createdLocal: '2026-10-29T07:00:00Z', notifiedAt: null },
+      '2026-10-29T07:00:00Z',
+    )).toBe(false);
+  });
+
+  it('announces a genuinely new session that reuses a name', () => {
+    expect(shouldAnnounceSession(
+      { endedAt: '2026-10-29T08:00:00Z', createdLocal: '2026-10-29T07:00:00Z', notifiedAt: '2026-10-29T07:00:01Z' },
+      '2026-10-29T09:30:00Z',
+    )).toBe(true);
+  });
+
+  // Durable suppression: lastNewNotifiedAt is in memory, so a ws-server
+  // restart must not replay an announcement the database already recorded.
+  it('stays quiet when the prior row was already announced and is still live', () => {
+    expect(shouldAnnounceSession(
+      { endedAt: null, createdLocal: '2026-10-29T07:00:00Z', notifiedAt: '2026-10-29T07:00:01Z' },
+      '2026-10-29T07:00:00Z',
+    )).toBe(false);
+  });
+
+  // The documented reversal of the original push spec. Without a creation time
+  // there is no way to tell a revival from a new session, and the complaint is
+  // bursts, so silence is the right direction here.
+  it('treats a missing creation time on either side as the same session', () => {
+    expect(shouldAnnounceSession(
+      { endedAt: '2026-10-29T08:00:00Z', createdLocal: null, notifiedAt: null },
+      '2026-10-29T09:00:00Z',
+    )).toBe(false);
+    expect(shouldAnnounceSession(
+      { endedAt: '2026-10-29T08:00:00Z', createdLocal: '2026-10-29T07:00:00Z', notifiedAt: null },
+      null,
+    )).toBe(false);
+  });
+});

package/node_modules/@indianic/dialout-shared/src/session-announce.ts

@@ -0,0 +1,40 @@
+// packages/devdash-shared/src/session-announce.ts
+
+/**
+ * Whether a tmux session the agent just reported is news.
+ *
+ * The bug this exists to kill: the daemon's close handler used to set
+ * `ended_at` on every session, so a reconnect made the registry's UPDATE miss,
+ * take the INSERT branch, and push "New terminal" for every terminal that was
+ * already open. Task 2 stops writing `ended_at` there; this is the second
+ * line of defence, for a session the vanish-pass legitimately ended and that
+ * then came back.
+ */
+export interface PriorSession {
+  /** Null while the session is live. */
+  endedAt: string | null;
+  /** When tmux created the session, as the agent reported it. */
+  createdLocal: string | null;
+  /** When a push for this row went out, or null if none ever did. */
+  notifiedAt: string | null;
+}
+
+export function shouldAnnounceSession(
+  prior: PriorSession | null,
+  createdLocal: string | null,
+): boolean {
+  // Never seen on this machine under this name: unambiguously new.
+  if (!prior) return true;
+
+  // Both creation times known and different: tmux really did make a new
+  // session that happens to reuse the name.
+  if (prior.createdLocal && createdLocal && prior.createdLocal !== createdLocal) return true;
+
+  // Everything else is the same session returning — including the case where
+  // either creation time is missing. The original push spec said a missed
+  // notification is worse than an extra one; for this trigger that is
+  // backwards, because the failure being fixed is a burst. The cost is that an
+  // agent too old to report a creation time cannot announce a genuinely new
+  // session that reuses an old name.
+  return false;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indianic/dialout",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "description": "Dialout agent — reach your office, home or build machine from any browser or phone. Remote tmux terminals, live port checks, filesystem browsing, process control and HTTP tunnels. The agent dials out: no inbound ports, no VPN, no port forwarding.",
   "bin": {
     "dialout": "./bin/devdash-agent.js"

package/scripts/postinstall.js

@@ -1,6 +1,5 @@
 #!/usr/bin/env node
 
-const { execSync } = require('child_process');
 const os = require('os');
 
 const GREEN = '\x1b[32m';
@@ -51,7 +50,7 @@ console.log('');
 
 if (!ptyOk) {
   console.log(`${YELLOW}  node-pty failed to load. Try rebuilding:${NC}`);
-  console.log(`  npm rebuild node-pty`);
+  console.log('  npm rebuild node-pty');
   console.log('');
 }
 
@@ -64,16 +63,16 @@ if (nodeOk && platformOk && ptyOk) {
 console.log('');
 console.log(`${CYAN}Next steps:${NC}`);
 console.log('');
-console.log('  1. Generate an API key in the DevDash web UI (MACHINES tab)');
+console.log('  1. Generate an API key in Dialout (Settings → Machines)');
 console.log('');
-console.log('  2. Configure the agent:');
-console.log(`     ${BOLD}devdash-agent init${NC}`);
+console.log('  2. Configure the agent (includes remote-control setup):');
+console.log(`     ${BOLD}dialout init${NC}`);
 console.log('');
-console.log('  3. Start the agent:');
-console.log(`     ${BOLD}devdash-agent start${NC}`);
+console.log('  3. Or wrap terminals later:');
+console.log(`     ${BOLD}dialout rc${NC}`);
 console.log('');
-console.log('  4. Install as service (auto-start on boot):');
-console.log(`     ${BOLD}devdash-agent install-service${NC}`);
+console.log('  4. Install as a service (auto-start):');
+console.log(`     ${BOLD}dialout install-service${NC}`);
 console.log('');
 console.log(`${BOLD}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}`);
 console.log('');