wldx-cli 0.1.0 → 1.0.0

package/src/commands/user.mjs

@@ -0,0 +1,130 @@
+// wx user: people of the corporate directory on the stream service (the agent skill's users.sh and search.sh
+// users): who you are, a colleague by name (any script, typos, as it sounds), e-mail or phone.
+import {jwtClaims} from '../auth.mjs';
+import {UsageError} from '../errors.mjs';
+import {paint, table} from '../format.mjs';
+import {query} from '../http.mjs';
+import {nextPage, userLine} from '../chat/format.mjs';
+import {api, checkId, checkInt, displayName} from '../chat/lib.mjs';
+
+const me = {
+  summary: 'the logged-in user: id, name, e-mail, extension',
+  usage: 'wx user me',
+  options: {},
+  args: [0, 0],
+  async run(ctx) {
+    const email = jwtClaims(ctx.token).email;
+    if (!email) throw new Error('The login token carries no e-mail');
+    const r = await api(ctx).call('POST', '/users/query', {query: {emails: [email]}});
+    return r?.users?.[0] ?? null;
+  },
+  text(u, ctx) {
+    if (!u) return 'Not found in the chat directory.';
+    const rows = [['Name', paint(ctx).bold(displayName(u) ?? '')], ['Id', u.id], ['E-mail', u.email ?? '']];
+    if (u.pbxExtension) rows.push(['Extension', u.pbxExtension]);
+    if (u.timeZone) rows.push(['Time zone', u.timeZone]);
+    if (u.locale) rows.push(['Locale', u.locale]);
+    return table(rows);
+  },
+};
+
+const brief = (r) => ({
+  margin: r?.margin,
+  nextCursor: r?.nextCursor,
+  results: (r?.results ?? []).map((x) => ({id: x.user?.id, name: x.user?.displayName, email: x.user?.email, extension: x.user?.pbxExtension, bot: x.user?.bot, confidence: x.confidence, matchedOn: x.matchedOn})),
+});
+
+const find = {
+  summary: 'find a colleague by name (any script, typos, as it sounds), e-mail or phone',
+  usage: 'wx user find <query> [--mode auto|name|email|phone] [--kind human|bot|all] [--with-extension] [--min-confidence 0..1] [--brief] [--size 1-50] [--cursor C]',
+  details: [
+    'An e-mail or a phone number (with its country code, +…) is looked up exactly (confidence 1). confidence (0..1)',
+    'is how much the query looks like the name, not the probability that it is the right person (default cut 0.5;',
+    '--min-confidence 0 shows every candidate). margin is the confidence of the first hit minus the second: near 0,',
+    'the answer is ambiguous: ask which one, never guess. --brief keeps id, name, email, extension, bot, confidence,',
+    'matchedOn (JSON).',
+  ].join('\n'),
+  options: {
+    mode: {type: 'string', choices: ['auto', 'name', 'email', 'phone'], description: 'what the query is (auto by default)'},
+    kind: {type: 'string', choices: ['human', 'bot', 'all'], description: 'people (default), bots or both'},
+    'with-extension': {type: 'boolean', description: 'only people with a PBX extension'},
+    'min-confidence': {type: 'string', placeholder: '0..1', description: 'drop hits below this confidence (default 0.5)'},
+    brief: {type: 'boolean', description: 'only the fields needed to pick a person'},
+    size: {type: 'string', placeholder: '1-50', description: 'results per page (default 20)'},
+    cursor: {type: 'string', description: 'the next page (nextCursor of the previous one)'},
+  },
+  args: [1, 1],
+  async run(ctx) {
+    const {values} = ctx;
+    const minc = values['min-confidence'];
+    if (minc !== undefined && !/^(0|1|0?\.[0-9]+|1\.0+)$/.test(minc)) throw new UsageError(`--min-confidence is a number from 0 to 1: ${minc}`);
+    const q = query({
+      q: ctx.positionals[0],
+      mode: values.mode,
+      kind: values.kind,
+      withExtensionOnly: values['with-extension'] && 'true',
+      minConfidence: minc,
+      size: checkInt('size', values.size, 1, 50),
+      cursor: values.cursor,
+    });
+    const r = await api(ctx).call('GET', `/search/users${q}`);
+    return values.brief ? brief(r) : r;
+  },
+  text(r, ctx) {
+    const c = paint(ctx);
+    const hits = r?.results ?? [];
+    if (!hits.length) return 'Nobody found.';
+    const rows = hits.map((x) => {
+      const u = x.user ?? {id: x.id, displayName: x.name, email: x.email, pbxExtension: x.extension, bot: x.bot};
+      return [...userLine(u, c), `${Number(x.confidence ?? 0).toFixed(2)} ${x.matchedOn ?? ''}`.trim()];
+    });
+    const lines = table(rows);
+    if (hits.length > 1 && typeof r.margin === 'number') lines.push(r.margin < 0.1 ? c.yellow(`Ambiguous (margin ${r.margin.toFixed(2)}): several people fit, ask which one`) : c.dim(`margin ${r.margin.toFixed(2)}`));
+    return [...lines, ...nextPage(r.nextCursor, c)];
+  },
+};
+
+const EMAIL = /@/;
+const PHONE = /^\+?[0-9]{4,17}$/;
+
+const get = {
+  summary: 'people by user id, e-mail or phone (exact lookup)',
+  usage: 'wx user get [<id|email|phone>...] [--id USERID]... [--email EMAIL]... [--phone PHONE]...',
+  details: 'A value given without an option is an e-mail when it has "@", a phone when it is digits (+ allowed), else a user id. For a search by name: wx user find.',
+  options: {
+    id: {type: 'string', multiple: true, placeholder: 'USERID', description: 'a user id'},
+    email: {type: 'string', multiple: true, placeholder: 'EMAIL', description: 'an e-mail address'},
+    phone: {type: 'string', multiple: true, placeholder: 'PHONE', description: 'a phone number'},
+  },
+  args: [0, 100],
+  async run(ctx) {
+    const {values} = ctx;
+    const ids = [...(values.id ?? [])];
+    const emails = [...(values.email ?? [])];
+    const phones = [...(values.phone ?? [])];
+    for (const v of ctx.positionals) {
+      if (EMAIL.test(v)) emails.push(v);
+      else if (PHONE.test(v.replace(/[\s()-]/g, ''))) phones.push(v.replace(/[\s()-]/g, ''));
+      else ids.push(v);
+    }
+    const q = {};
+    if (ids.length) q.ids = ids.map((id) => checkId('The user id', id));
+    if (emails.length) q.emails = emails;
+    if (phones.length) q.phones = phones;
+    if (!Object.keys(q).length) throw new UsageError('Give a user id, an e-mail or a phone (or --id, --email, --phone)', ctx.usage());
+    return api(ctx).call('POST', '/users/query', {query: q});
+  },
+  text(r, ctx) {
+    const c = paint(ctx);
+    const list = r?.users ?? [];
+    return list.length ? table(list.map((u) => userLine(u, c))) : 'Nobody found.';
+  },
+};
+
+const user = {
+  summary: 'people: you, a colleague by name, e-mail or phone',
+  auth: true,
+  commands: {me, find, get},
+};
+
+export const groups = {user};

package/src/completion.mjs

@@ -1,9 +1,9 @@
 // Shell completion. `wx completion <shell>` prints a small script; on every Tab it runs
 // `wx __complete -- <words after wx, the last one being the word under the cursor>`, which prints the candidates,
 // one per line as "value<TAB>description". The candidates come from the command definitions (and the saved
-// accounts for --account), so completion follows the commands without a regenerated script. No network.
+// profiles for --profile), so completion follows the commands without a regenerated script. No network.
 import {sessions} from './auth.mjs';
-import {COMMON_OPTIONS, GROUPS, commandOf, groupOf} from './commands/index.mjs';
+import {COMMON_OPTIONS, GLOBAL_OPTIONS, REGISTRY, commandOf, groupOf, singleOf} from './commands/index.mjs';
 
 export const SHELLS = ['bash', 'zsh', 'fish'];
 
@@ -11,60 +11,87 @@ export const TOP_LEVEL = {
   completion: 'print the shell completion script (bash, zsh, fish)',
 };
 
-const TOP_OPTIONS = {'--help': 'help of wx', '--version': 'the version of wx'};
+const TOP_OPTIONS = {'--help': 'help of wx', '--version': 'the version of wx', '--profile': 'the profile (a logged-in e-mail) to use', '--output': 'text or json'};
 
 function valuesOf(option, env) {
   if (option.choices) return option.choices.map((v) => [v]);
-  if (option.complete === 'accounts') return sessions(env).map((s) => [s.email]);
+  if (option.complete === 'profiles') return sessions(env).map((s) => [s.email]);
   return [];
 }
 
 // The candidates for the word under the cursor: ["value\tdescription", ...].
-export function complete(words, env = process.env) {
+export function complete(words, env = process.env, registry = REGISTRY) {
   const cur = words.length ? words[words.length - 1] : '';
-  const done = words.slice(0, -1);
   const offer = (pairs) => pairs.filter(([v]) => v.startsWith(cur)).map(([v, d]) => (d ? `${v}\t${d}` : v));
+  // The global options may stand anywhere: the value of one is offered, and they are left out of what names the
+  // command (wx --profile a@b.c chat <Tab> completes like wx chat <Tab>).
+  const globalOf = (word) => {
+    const name = word?.startsWith('--') ? word.slice(2).split('=')[0] : undefined;
+    return name && Object.hasOwn(GLOBAL_OPTIONS, name) ? name : undefined;
+  };
+  const before = words.slice(0, -1);
+  const last = before[before.length - 1];
+  if (globalOf(last) && !last.includes('=') && GLOBAL_OPTIONS[globalOf(last)].type === 'string') {
+    return offer(valuesOf(GLOBAL_OPTIONS[globalOf(last)], env));
+  }
+  const done = [];
+  for (let i = 0; i < before.length; i += 1) {
+    const name = globalOf(before[i]);
+    if (name) {
+      if (GLOBAL_OPTIONS[name].type === 'string' && !before[i].includes('=')) i += 1;
+      continue;
+    }
+    done.push(before[i]);
+  }
 
   if (done.length === 0) {
     return offer([
-      ...Object.entries(GROUPS).map(([name, g]) => [name, g.summary]),
+      ...Object.entries(registry.groups).map(([name, g]) => [name, g.summary]),
+      ...Object.entries(registry.commands).map(([name, c]) => [name, c.summary]),
       ...Object.entries(TOP_LEVEL),
       ...(cur.startsWith('-') ? Object.entries(TOP_OPTIONS) : []),
     ]);
   }
   if (done[0] === 'completion') return done.length === 1 ? offer(SHELLS.map((s) => [s, `the script for ${s}`])) : [];
 
-  const group = groupOf(done[0]);
-  if (!group) return [];
-  if (done.length === 1) return offer(Object.entries(group.commands).map(([name, cmd]) => [name, cmd.summary]));
-
-  const cmd = commandOf(group, done[1]);
+  // The command and how many words name it: 1 for a single command, 2 for a group and its command.
+  let cmd = singleOf(done[0], registry);
+  let depth = 1;
+  if (!cmd) {
+    const group = groupOf(done[0], registry);
+    if (!group) return [];
+    if (done.length === 1) return offer(Object.entries(group.commands).map(([name, c]) => [name, c.summary]));
+    cmd = commandOf(group, done[1]);
+    depth = 2;
+  }
   if (!cmd) return [];
-  const options = {...cmd.options, ...COMMON_OPTIONS};
+  const options = {...cmd.options, ...COMMON_OPTIONS, ...GLOBAL_OPTIONS};
   const prev = done[done.length - 1];
-  if (done.length > 2 && prev.startsWith('--')) {
+  if (done.length > depth && prev.startsWith('--')) {
     const option = Object.hasOwn(options, prev.slice(2)) ? options[prev.slice(2)] : undefined;
     if (option?.type === 'string') return offer(valuesOf(option, env));
   }
   if (cur.startsWith('-')) {
-    const used = new Set(done.slice(2).filter((w) => w.startsWith('--')).map((w) => w.slice(2)));
+    const used = new Set(done.slice(depth).filter((w) => w.startsWith('--')).map((w) => w.slice(2)));
     return offer(Object.entries(options).filter(([name, o]) => o.multiple || !used.has(name)).map(([name, o]) => [`--${name}`, o.description]));
   }
+  // A command whose argument is a profile (wx profile use <Tab>).
+  if (cmd.complete === 'profiles') return offer(valuesOf({complete: 'profiles'}, env));
   return [];
 }
 
 const SCRIPTS = {
   bash: `# wx completion for bash. Add to ~/.bashrc:  eval "$(wx completion bash)"
 _wx_complete() {
-  # The words are taken before IFS changes: bash 3.2 (macOS) joins the elements of a quoted array slice when IFS
+  # The words are taken as an array first: bash 3.2 (macOS) joins the elements of a quoted array slice when IFS
   # is a newline.
   local words=("\${COMP_WORDS[@]:1:COMP_CWORD}") out line
   COMPREPLY=()
   out=$(wx __complete -- "\${words[@]}" 2>/dev/null) || return 0
-  local IFS=$'\\n'
-  for line in $out; do
-    COMPREPLY+=("\${line%%$'\\t'*}")
-  done
+  # Line by line from a here-string: no word splitting and no glob expansion of the candidates.
+  while IFS= read -r line; do
+    [[ -n $line ]] && COMPREPLY+=("\${line%%$'\\t'*}")
+  done <<< "$out"
 }
 complete -F _wx_complete wx
 `,

package/src/files.mjs

@@ -0,0 +1,98 @@
+// Local files that commands read or write on behalf of the user, where the path may have come from fetched text
+// (an agent asked to "save the attachment to …" or to "attach …"): the guards that keep secrets in and startup
+// files out.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {configDir} from './auth.mjs';
+import {UsageError} from './errors.mjs';
+
+// macOS and Windows file systems ignore case by default: compare paths without it there.
+const FOLD = process.platform === 'darwin' || process.platform === 'win32';
+const norm = (p) => (FOLD ? p.toLowerCase() : p);
+const within = (child, parent) => norm(child) === norm(parent) || norm(child).startsWith(norm(parent) + path.sep);
+
+// The real path (symlinks resolved, true case on macOS) of a path that may not exist yet: the nearest existing
+// ancestor resolved, the rest appended.
+export function realPath(p) {
+  const abs = path.resolve(p);
+  let head = abs;
+  const rest = [];
+  for (;;) {
+    try {
+      return path.join(fs.realpathSync.native(head), ...rest);
+    } catch (e) {
+      if (e.code !== 'ENOENT' && e.code !== 'ENOTDIR') throw e;
+      const up = path.dirname(head);
+      if (up === head) return abs;
+      rest.unshift(path.basename(head));
+      head = up;
+    }
+  }
+}
+
+const homeOf = (env) => env.HOME || os.homedir();
+
+// Where a file written for the user must never land: anything hidden (a segment that starts with ".": ~/.ssh,
+// ~/.zshenv, .git/hooks, node_modules/.bin…) and the macOS startup folders. A downloaded file there could give
+// someone a login or run code; a person who really wants it there can move it.
+const STARTUP = ['Library/LaunchAgents', 'Library/LaunchDaemons', 'Library/StartupItems'];
+
+// Returns the real path; throws a UsageError for a path that is refused.
+export function refuseUnsafeWrite(target, env = process.env) {
+  const real = realPath(target);
+  const hidden = real.split(path.sep).find((s) => s.startsWith('.') && s !== '.' && s !== '..');
+  if (hidden) throw new UsageError(`Refusing to write into a hidden file or folder (${hidden}): ${target}. Choose a visible path.`);
+  const homes = [homeOf(env), realPath(homeOf(env))];
+  if (homes.some((h) => STARTUP.some((d) => within(real, path.join(h, d)) || within(real, path.join('/', d))))) {
+    throw new UsageError(`Refusing to write into a startup folder: ${target}`);
+  }
+  return real;
+}
+
+// Credentials: folders and files that hold keys and tokens, and names that look like secrets.
+const SECRET_FOLDERS = ['.wildix', '.ssh', '.aws', '.gnupg', '.config/gcloud', '.kube', '.docker', '.claude', '.agents'];
+const SECRET_FILES = ['.netrc', '.npmrc'];
+const SECRET_NAME = /^(\.env|\.env\..*|.*\.pem|.*\.key|.*\.p12|.*\.pfx|id_rsa.*|id_ed25519.*|id_ecdsa.*|.*\.kdbx|credentials.*\.json|.*secret.*|.*\.token)$/is;
+
+// A file to send out of the machine (an attachment) is refused when it is, or points to, a credential: its real
+// path (symlinks resolved, true case) in a credentials folder, a secret-looking name (given or real), or a file with
+// other hard links (which could be one). The user can copy the file elsewhere if they really mean it.
+export function refuseSecretPath(file, env = process.env) {
+  let real;
+  let stat;
+  try {
+    real = fs.realpathSync.native(file);
+    stat = fs.statSync(real);
+  } catch {
+    real = realPath(file); // not there (yet): its folder still counts
+  }
+  const home = homeOf(env);
+  const roots = [home, realPath(home)];
+  const folders = [configDir(env), realPath(configDir(env)), ...roots.flatMap((h) => SECRET_FOLDERS.map((d) => path.join(h, d)))];
+  const files = roots.flatMap((h) => SECRET_FILES.map((f) => path.join(h, f)));
+  if (folders.some((d) => within(real, d)) || files.some((f) => norm(f) === norm(real))) {
+    throw new UsageError(`Refusing to attach a file from a credentials folder: ${file}`);
+  }
+  for (const name of new Set([path.basename(file), path.basename(real)])) {
+    if (SECRET_NAME.test(name)) throw new UsageError(`Refusing to attach what looks like a secret: ${name}`);
+  }
+  if (stat?.isFile() && stat.nlink > 1) throw new UsageError(`Refusing to attach a file with other hard links (it could be a credential): ${file}`);
+  return {real, stat};
+}
+
+// Reads a file to send out: checked with refuseSecretPath, then read from the descriptor that was opened, which
+// must still be the file that was checked (nothing can be swapped in between).
+export function readForUpload(file, env = process.env) {
+  const {real, stat} = refuseSecretPath(file, env);
+  if (!stat) throw new UsageError(`File not found: ${file}`);
+  if (!stat.isFile()) throw new UsageError(`Not a file: ${file}`);
+  const fd = fs.openSync(real, 'r');
+  try {
+    const now = fs.fstatSync(fd);
+    if (now.ino !== stat.ino || now.dev !== stat.dev || now.nlink > 1) throw new UsageError(`The file changed while it was checked: ${file}`);
+    return fs.readFileSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+}

package/src/format.mjs

@@ -0,0 +1,82 @@
+// Text output: what `--output text` (the default) prints. A command gives `text(result, ctx)` (and `textEvent(event,
+// ctx)` for a streaming one) returning a string or an array of lines; without one, toText() prints the data as
+// indented "key: value" lines. Helpers for formatters: colors (only on a terminal), times, tables.
+
+// Colors: on when ctx.color (a terminal, no --no-color, no NO_COLOR).
+const CODES = {bold: [1, 22], dim: [2, 22], red: [31, 39], green: [32, 39], yellow: [33, 39], blue: [34, 39], cyan: [36, 39]};
+export function paint(ctx) {
+  const on = Boolean(ctx?.color);
+  return Object.fromEntries(Object.entries(CODES).map(([name, [a, b]]) => [name, (s) => (on ? `\x1b[${a}m${s}\x1b[${b}m` : String(s))]));
+}
+
+const pad2 = (n) => String(n).padStart(2, '0');
+
+// "2026-11-07 10:23" in the local time zone of the machine (ISO string or ms); '' for nothing.
+export function localTime(value, {seconds = false} = {}) {
+  if (value === undefined || value === null || value === '') return '';
+  const d = new Date(typeof value === 'number' || /^\d+$/.test(String(value)) ? Number(value) : value);
+  if (Number.isNaN(d.getTime())) return String(value);
+  const t = `${d.getFullYear()}-${pad2(d.getMonth() + 1)}-${pad2(d.getDate())} ${pad2(d.getHours())}:${pad2(d.getMinutes())}`;
+  return seconds ? `${t}:${pad2(d.getSeconds())}` : t;
+}
+
+// "1:05:09" / "5:09" from seconds.
+export function duration(seconds) {
+  if (!Number.isFinite(seconds)) return '';
+  const s = Math.max(0, Math.round(seconds));
+  const h = Math.floor(s / 3600);
+  const m = Math.floor((s % 3600) / 60);
+  return h ? `${h}:${pad2(m)}:${pad2(s % 60)}` : `${m}:${pad2(s % 60)}`;
+}
+
+// One line: newlines folded, cut to max characters.
+export function oneLine(text, max = 120) {
+  const s = String(text ?? '').replace(/\s+/g, ' ').trim();
+  return s.length > max ? `${s.slice(0, max - 1)}…` : s;
+}
+
+// Aligned columns: rows are arrays of cells; the last column is not padded. Colors in cells are not counted.
+export function table(rows) {
+  const visible = (s) => String(s ?? '').replace(/\x1b\[\d+m/g, '').length;
+  const widths = [];
+  for (const row of rows) row.forEach((c, i) => (widths[i] = Math.max(widths[i] ?? 0, visible(c))));
+  return rows.map((row) => row.map((c, i) => (i === row.length - 1 ? String(c ?? '') : String(c ?? '') + ' '.repeat(widths[i] - visible(c)))).join('  ').trimEnd());
+}
+
+const scalar = (v) => v === null || typeof v !== 'object';
+
+// Any data as indented "key: value" lines (the fallback of commands without a formatter).
+export function toText(value, indent = '') {
+  if (value === undefined) return [];
+  if (scalar(value)) return [`${indent}${value}`];
+  const lines = [];
+  if (Array.isArray(value)) {
+    if (value.every(scalar)) return [`${indent}${value.join(', ')}`];
+    value.forEach((item, i) => {
+      if (i && !scalar(item)) lines.push('');
+      lines.push(...toText(item, indent));
+    });
+    return lines;
+  }
+  for (const [k, v] of Object.entries(value)) {
+    if (v === undefined) continue;
+    if (scalar(v)) lines.push(`${indent}${k}: ${v}`);
+    else if (Array.isArray(v) && v.every(scalar)) lines.push(`${indent}${k}: ${v.join(', ')}`);
+    else if (Array.isArray(v) && !v.length) lines.push(`${indent}${k}: (none)`);
+    else lines.push(`${indent}${k}:`, ...toText(v, `${indent}  `));
+  }
+  return lines;
+}
+
+// Text for a terminal from data that may hold control sequences (a message, a name, an error of a service): kept
+// are newlines, tabs and the color codes paint() itself writes; every other control character is dropped, so a
+// fetched text cannot write the clipboard (OSC 52), move the cursor, rewrite lines or hide text.
+const OWN_SGR = new Set(Object.values(CODES).flat().map(String));
+export function clean(text) {
+  // NUL goes first: it then marks the color codes that are kept, and no input can forge such a mark.
+  return String(text)
+    .replace(/\u0000/g, '')
+    .replace(/\x1b\[(\d+)m/g, (m, code) => (OWN_SGR.has(code) ? `\u0000${code}\u0000` : ''))
+    .replace(/[\x01-\x08\x0b-\x1f\x7f-\x9f]/g, '')
+    .replace(/\u0000(\d+)\u0000/g, '\x1b[$1m');
+}

package/src/history/text.mjs

@@ -0,0 +1,60 @@
+// Text formatters shared by wx calls, meetings and conversations: the AI summary, the insights, the people of a call.
+import {duration, oneLine} from '../format.mjs';
+
+const SECTIONS = ['topics', 'keyPoints', 'review', 'decisions', 'progress', 'issues', 'actionItems', 'nextSteps', 'customerInsights', 'customerResponse', 'salesProposals', 'competitiveInformation', 'implementationTimeline', 'budget', 'tags'];
+
+// "actionItems" -> "Action items"
+export const label = (key) => {
+  const words = key.replace(/([a-z])([A-Z])/g, '$1 $2').toLowerCase();
+  return words.charAt(0).toUpperCase() + words.slice(1);
+};
+
+const valueText = (v) => (v === null || v === undefined ? '' : typeof v === 'object' ? (Array.isArray(v) && v.every((x) => typeof x !== 'object') ? v.join('; ') : JSON.stringify(v)) : String(v));
+
+function bullets(title, items, indent = '') {
+  const list = (items ?? []).filter((x) => x !== null && x !== undefined && x !== '');
+  if (!list.length) return [];
+  return [`${indent}${title}:`, ...list.map((x) => `${indent}  - ${oneLine(valueText(x), 400)}`)];
+}
+
+// The sections of a summary ({topics: [...], decisions: [...], ...}) as bullet lists.
+export function sectionLines(json, indent = '') {
+  const lines = [];
+  for (const key of SECTIONS) if (Array.isArray(json?.[key])) lines.push(...bullets(label(key), json[key], indent));
+  if (json?.csat && (json.csat.score || json.csat.reason)) lines.push(`${indent}CSAT: ${[json.csat.score, json.csat.reason && oneLine(json.csat.reason, 300)].filter(Boolean).join(' · ')}`);
+  return lines;
+}
+
+// GET .../summary: {status, summary: {title, brief, json}}.
+export function summaryLines(r) {
+  if (r?.status !== 'SUCCEEDED') return [`No summary: ${r?.status ?? 'UNKNOWN'}`];
+  const s = r.summary ?? {};
+  const lines = [];
+  if (s.title) lines.push(oneLine(s.title, 200));
+  if (s.brief) lines.push(oneLine(s.brief, 2000));
+  const sections = sectionLines(s.json);
+  if (sections.length) lines.push('', ...sections);
+  return lines;
+}
+
+// {projectionId: {fieldId: value}} as "projection" lines with indented "field: value".
+export function insightLines(compact, indent = '') {
+  const lines = [];
+  for (const [id, fields] of Object.entries(compact ?? {})) {
+    lines.push(`${indent}${id}:`);
+    for (const [f, v] of Object.entries(fields ?? {})) lines.push(`${indent}  ${f}: ${oneLine(valueText(v), 300)}`);
+  }
+  return lines;
+}
+
+// A party of a call: "Name (ext 201) +3902…", whatever is known.
+export function party(p) {
+  if (!p) return '';
+  const ext = p.userExtension ?? p.extension;
+  return [p.name, ext && `(${ext})`, p.phone && p.phone !== ext ? p.phone : undefined].filter(Boolean).join(' ');
+}
+
+// Seconds or milliseconds as "m:ss".
+export const secs = (s) => (Number.isFinite(s) ? duration(s) : '');
+// A duration from milliseconds; '—' when there is none (no calls in the window).
+export const millis = (ms) => (Number.isFinite(ms) ? duration(ms / 1000) : '—');

package/src/history/wda.mjs

@@ -0,0 +1,161 @@
+// Wildix Data Analytics (https://wda.wildix.com/v2): the history of calls and conferences, their AI insights, the
+// search over conversations and the queue reports (x-caracal). A client bound to the token, and the helpers the
+// commands of wx calls, meetings, conversations and reports share (ids, numbers, dates, the shapes of the skill).
+import fs from 'node:fs';
+import path from 'node:path';
+import {HttpError, UsageError} from '../errors.mjs';
+import {refuseUnsafeWrite} from '../files.mjs';
+import {request} from '../http.mjs';
+import {wdaUrl} from '../services.mjs';
+
+const FORBIDDEN_HINT = 'The login has no access to this record (a meeting or call of other people, or a role without the right).';
+
+// wdaClient({token, env, fetchImpl}) (for ctx.client): get(path), post(path, body), soft(path) (null on a 404).
+// The path is relative to /v2 and built with apiPath`` by the caller.
+export function wdaClient({token, env, fetchImpl}) {
+  const root = `${wdaUrl(env)}/v2`;
+  async function call(method, p, body) {
+    try {
+      return await request(root + p, {method, token, body, fetchImpl, service: 'WDA'});
+    } catch (e) {
+      if (e instanceof HttpError && e.status === 403) e.message += `\n${FORBIDDEN_HINT}`;
+      throw e;
+    }
+  }
+  return {
+    get: (p) => call('GET', p),
+    post: (p, body) => call('POST', p, body),
+    async soft(p) {
+      try {
+        return await call('GET', p);
+      } catch (e) {
+        if (e instanceof HttpError && e.status === 404) return null;
+        throw e;
+      }
+    },
+  };
+}
+
+// An optional part of a readable card (a summary, insights): null when it is not there (404); another failure is
+// told on stderr and the card goes on without it (as the scripts of the skill do).
+export async function optional(promise, info) {
+  try {
+    return await promise;
+  } catch (e) {
+    if (!(e instanceof HttpError && e.status === 404)) info(`Warning: ${e.message.split('\n')[0]}`);
+    return null;
+  }
+}
+
+// Nothing to show: no transcription, or no such record. Exit code 3, as in the scripts of the skill.
+export class NoDataError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'NoDataError';
+    this.exitCode = 3;
+  }
+}
+
+const ID = /^[A-Za-z0-9_+][A-Za-z0-9_.:+-]*$/;
+
+// An id that goes into a request path (a call id, a queue id, a file id).
+export function checkId(what, value) {
+  const v = String(value ?? '');
+  if (!ID.test(v) || v.includes('..')) throw new UsageError(`${what} is not a valid id: ${value}`);
+  return v;
+}
+
+// A conference id from an id or a link (the last path segment of .../insights/conferences/<id>).
+export function conferenceId(input) {
+  const v = String(input).split(/[?#]/)[0].replace(/\/$/, '').split('/').pop();
+  if (!/^[A-Za-z0-9_][A-Za-z0-9_.-]*$/.test(v) || v.includes('..') || v === 'conferences') throw new UsageError(`not a conference id: ${input}`);
+  return v;
+}
+
+// A call: the call id and the flow index (a transferred call has several flows; the first is 0).
+export function callFlow(positionals) {
+  const [id, flow = '0'] = positionals;
+  if (!/^\d{1,9}$/.test(flow)) throw new UsageError(`the flow index must be a number: ${flow}`);
+  return {callId: checkId('the call id', id), flow: Number(flow)};
+}
+
+// A whole number from min to max (the services refuse anything else with a 400 that tells little).
+export function intOption(name, value, min, max) {
+  if (value === undefined) return undefined;
+  if (!/^\d{1,12}$/.test(value) || Number(value) < min || Number(value) > max) throw new UsageError(`${name} must be a whole number from ${min} to ${max}: ${value}`);
+  return Number(value);
+}
+
+export function checkZone(value) {
+  if (value === undefined) return undefined;
+  if (!/^[A-Za-z][A-Za-z0-9_+/-]{0,63}$/.test(value)) throw new UsageError(`not a time zone: ${value}`);
+  return value;
+}
+
+// An ISO time given to a filter (--from, --to of the call history and the search): passed on as it is, once it
+// is a time at all.
+export function checkIso(name, value) {
+  if (value === undefined) return undefined;
+  if (!/^\d{4}-\d{2}-\d{2}/.test(value) || Number.isNaN(Date.parse(value))) throw new UsageError(`${name} must be an ISO time (2026-11-07 or 2026-11-07T09:00:00Z): ${value}`);
+  return value;
+}
+
+// The local IANA time zone (TZ, else the zone of the machine).
+export const localZone = (env) => env.TZ || Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC';
+
+// jq's todate: "2026-11-05T11:21:29Z" from milliseconds.
+export const isoSeconds = (ms) => new Date(Math.floor((ms || 0) / 1000) * 1000).toISOString().replace(/\.\d{3}Z$/, 'Z');
+
+// jq's `a // b // c`: the first value that is not null, undefined or false.
+export const alt = (...values) => values.find((v) => v !== null && v !== undefined && v !== false) ?? null;
+
+// {k: obj[k] ?? null} for the keys (jq's `{a, b}`).
+export const pick = (obj, keys) => Object.fromEntries(keys.map((k) => [k, obj?.[k] ?? null]));
+
+// jq's `unique`: sorted, no repeats.
+export const unique = (values) => [...new Set(values)].sort();
+
+// The insights that succeeded, as {projectionId: {fieldId: value}}.
+export function compactInsights(r) {
+  const out = {};
+  for (const p of r?.insights ?? []) {
+    if (p.status !== 'SUCCEEDED' || !(p.fields ?? []).length) continue;
+    out[p.id] = Object.fromEntries(p.fields.map((f) => [f.id, f.value ?? null]));
+  }
+  return out;
+}
+
+// The participants of a conference by name (or e-mail), each once.
+export const participantNames = (conference) =>
+  unique((conference?.participants ?? []).map((p) => alt(p.info?.name, p.info?.email)).filter((n) => n !== null).map((n) => String(n).replace(/\s+/g, ' ').trim()));
+
+// Writes a transcript to a private file (folders 0700, file 0600) and returns its absolute path. An existing path
+// is replaced only when it is a transcript of the same conference written earlier (its second line is
+// "# conferenceId: <id>"): the path may have come from fetched text, so nothing else is touched.
+export function writePrivate(file, content, {cwd, conferenceId: id, env = process.env} = {}) {
+  if (!file) throw new UsageError('empty output path');
+  const target = path.resolve(cwd ?? process.cwd(), file);
+  refuseUnsafeWrite(target, env);
+  let exists = false;
+  try {
+    fs.lstatSync(target);
+    exists = true;
+  } catch (e) {
+    if (e.code !== 'ENOENT') throw e;
+  }
+  if (exists) {
+    let second;
+    try {
+      second = fs.readFileSync(target, 'utf8').slice(0, 8192).split('\n')[1];
+    } catch {
+      second = undefined;
+    }
+    if (!id || second !== `# conferenceId: ${id}`) throw new Error(`${file} exists: choose another path (nothing was overwritten)`);
+  }
+  fs.mkdirSync(path.dirname(target), {recursive: true, mode: 0o700});
+  fs.writeFileSync(target, content, {mode: 0o600, flag: exists ? 'w' : 'wx'});
+  return target;
+}
+
+// "1 queue", "2 queues".
+export const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;