@ghl-ai/aw 0.1.44-beta.1 → 0.1.44-beta.2

package/c4/index.mjs

@@ -0,0 +1,64 @@
+/**
+ * c4/index.mjs — public barrel.
+ *
+ * Re-exports every named symbol from every c4/ module so the orchestrator
+ * (and tests, and downstream tools that want to compose c4 primitives)
+ * can do:
+ *
+ *   import * as c4 from './c4/index.mjs';
+ *   c4.detectHarness();
+ *   c4.runPreflight({...});
+ *   c4.summarizeAsOneLine({...});
+ *
+ * Strict re-exports only — no logic, no defaults, no aggregations. Adding
+ * a new c4 primitive means adding one line here.
+ *
+ * Contract: tasks.md::4.3.
+ */
+
+export { detectHarness, HARNESSES } from './detect.mjs';
+export { getGithubToken, maskToken } from './secrets.mjs';
+export { ensureGhCli } from './ghCli.mjs';
+export {
+  clearAllGitHubAuthState,
+  installPatInsteadOf,
+  installCredentialHelperStore,
+  ghAuthLoginWithToken,
+  ghAuthSetupGit,
+  ensureOriginRemote,
+  verifyAuth,
+  preflightPlatformDocs,
+} from './gitAuth.mjs';
+export { applyEccRegistryBridge } from './eccRegistryBridge.mjs';
+export {
+  SLIM_CARD_HARD_CEILING_BYTES,
+  REQUIRED_ENFORCEMENT_PHRASES,
+  REQUIRED_STAGE_MARKERS_CLAUDE,
+  REQUIRED_STAGE_MARKERS_CURSOR,
+  SLIM_CARD_CLAUDE,
+  SLIM_CARD_CURSOR,
+  buildSlimRouterCard,
+  installSlimRouter,
+} from './slimRouter.mjs';
+export { defaultHookPath, installCodexPromptInjector } from './codexPromptInjector.mjs';
+export {
+  MCP_URL_DEFAULT as CODEX_MCP_URL_DEFAULT,
+  ensureCodexHooksFlag,
+  ensureCodexMcpServer,
+} from './codexConfig.mjs';
+export { MCP_URL_DEFAULT, registerGhlAiMcp } from './mcpServer.mjs';
+export { probeMcpServer } from './mcpSmokeProbe.mjs';
+export { ensureClaudeMarketplace } from './claudePluginRegistry.mjs';
+export { ensureCommandSurface, diagnoseCommandResolution } from './commandSurface.mjs';
+export { ensureRepoLocalClaudeSettings } from './repoLocalClaudeSettings.mjs';
+export { copyRepoRootInstructions } from './repoRootInstructions.mjs';
+export { ensureRepoLocalIgnore } from './repoLocalIgnore.mjs';
+export { jsonMergeWithDedup, claudeHooksMerge } from './jsonMerge.mjs';
+export { runPreflight } from './preflight.mjs';
+export {
+  summarizeAsOneLine,
+  diagnoseAwRouterView,
+  diagnosePromptRouterInjection,
+  diagnoseSkillResolution,
+  dumpPostInitState,
+} from './diagnostics.mjs';

package/c4/jsonMerge.mjs

@@ -0,0 +1,229 @@
+/**
+ * c4/jsonMerge.mjs — JSON-config merge helpers used by harness installers.
+ *
+ * Two flavors are exported because harness shapes diverge:
+ *   - jsonMergeWithDedup  — flat array-of-entries (Cursor hooks.json, mcp.json,
+ *                           Claude mcpServers, permissions.allow extension).
+ *   - claudeHooksMerge    — Claude's nested hook-groups: each event maps to an
+ *                           array of GROUPS, each group has matcher? + inner
+ *                           hooks[]. Stripping AW entries means filtering inner
+ *                           hooks[] and dropping groups that become empty.
+ *
+ * Both perform an atomic write (tmp file + rename) and chmod the final file
+ * to 0600. Idempotency is achieved by stripping pre-existing entries that
+ * match a `commandPatterns` substring list before appending the new entry,
+ * then comparing serialized JSON before writing.
+ */
+
+import { existsSync, readFileSync, writeFileSync, renameSync, chmodSync, unlinkSync } from 'node:fs';
+import { dirname, basename, join } from 'node:path';
+
+const FILE_MODE = 0o600;
+
+/**
+ * @param {string} pointer  RFC 6901 pointer, e.g. "/hooks/sessionStart"
+ * @returns {string[]}      Path tokens (empty array for "/")
+ */
+function parseJsonPointer(pointer) {
+  if (pointer === '' || pointer === '/') return [];
+  if (!pointer.startsWith('/')) {
+    throw new Error(`Invalid JSON pointer: ${pointer} (must start with "/")`);
+  }
+  return pointer
+    .slice(1)
+    .split('/')
+    .map((token) => token.replace(/~1/g, '/').replace(/~0/g, '~'));
+}
+
+/**
+ * Walk a JSON pointer to its parent and key, creating intermediate objects.
+ * Returns { parent, key } so the caller can read/write `parent[key]`.
+ */
+function walkAndCreate(root, tokens) {
+  if (tokens.length === 0) {
+    throw new Error('jsonMergeWithDedup: pointer must target a child key, not the root');
+  }
+  let cursor = root;
+  for (let i = 0; i < tokens.length - 1; i += 1) {
+    const t = tokens[i];
+    if (cursor[t] == null || typeof cursor[t] !== 'object' || Array.isArray(cursor[t])) {
+      cursor[t] = {};
+    }
+    cursor = cursor[t];
+  }
+  return { parent: cursor, key: tokens[tokens.length - 1] };
+}
+
+/**
+ * Atomically write JSON to `filePath` with mode 0600.
+ * No-op if `serialized` matches the existing file content byte-for-byte.
+ *
+ * @returns {boolean} true if the file changed, false if no write occurred.
+ */
+function atomicWriteIfChanged(filePath, serialized) {
+  if (existsSync(filePath)) {
+    const prev = readFileSync(filePath, 'utf8');
+    if (prev === serialized) return false;
+  }
+
+  const tmp = join(
+    dirname(filePath),
+    `.${basename(filePath)}.tmp.${process.pid}.${Math.random().toString(36).slice(2)}`
+  );
+
+  try {
+    writeFileSync(tmp, serialized, { mode: FILE_MODE });
+    renameSync(tmp, filePath);
+  } catch (err) {
+    if (existsSync(tmp)) {
+      try { unlinkSync(tmp); } catch { /* best-effort */ }
+    }
+    throw err;
+  }
+
+  try { chmodSync(filePath, FILE_MODE); } catch { /* best-effort */ }
+  return true;
+}
+
+function readJsonOrEmpty(filePath) {
+  if (!existsSync(filePath)) return {};
+  const raw = readFileSync(filePath, 'utf8');
+  if (raw.trim() === '') return {};
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`Failed to parse JSON at ${filePath}: ${err.message}`);
+  }
+}
+
+function commandMatchesAnyPattern(command, patterns) {
+  if (typeof command !== 'string') return false;
+  return patterns.some((p) => typeof p === 'string' && p.length > 0 && command.includes(p));
+}
+
+/**
+ * Merge a flat array-of-entries JSON config with command-pattern dedup.
+ *
+ * @param {object} opts
+ * @param {string} opts.filePath
+ * @param {string} opts.jsonPointer        RFC 6901 pointer to the array.
+ * @param {object} opts.newEntry           Entry to append after dedup.
+ * @param {string[]} opts.commandPatterns  Substrings; existing entries with
+ *                                         a matching `command` field are stripped.
+ * @returns {{ changed: boolean, prevEntriesRemoved: number }}
+ */
+export function jsonMergeWithDedup({ filePath, jsonPointer, newEntry, commandPatterns }) {
+  if (!filePath || typeof filePath !== 'string') throw new Error('filePath is required');
+  if (typeof jsonPointer !== 'string') throw new Error('jsonPointer is required');
+  if (newEntry == null || typeof newEntry !== 'object') throw new Error('newEntry must be an object');
+  const patterns = Array.isArray(commandPatterns) ? commandPatterns : [];
+
+  const root = readJsonOrEmpty(filePath);
+  const tokens = parseJsonPointer(jsonPointer);
+  const { parent, key } = walkAndCreate(root, tokens);
+
+  const existing = parent[key];
+  let arr;
+  if (existing == null) {
+    arr = [];
+  } else if (Array.isArray(existing)) {
+    arr = existing;
+  } else {
+    throw new Error(`jsonMergeWithDedup: expected array at pointer ${jsonPointer}, got ${typeof existing}`);
+  }
+
+  const before = arr.length;
+  const filtered = arr.filter((entry) => {
+    if (entry == null || typeof entry !== 'object') return true;
+    return !commandMatchesAnyPattern(entry.command, patterns);
+  });
+  const prevEntriesRemoved = before - filtered.length;
+
+  filtered.push(newEntry);
+  parent[key] = filtered;
+
+  const serialized = JSON.stringify(root, null, 2) + '\n';
+  const changed = atomicWriteIfChanged(filePath, serialized);
+
+  return { changed, prevEntriesRemoved };
+}
+
+/**
+ * Merge a hook-group entry into Claude's nested settings.json shape.
+ *
+ *   settings.hooks[eventName] = [
+ *     { matcher?, description?, hooks: [{ type:'command', command, description }, ...] },
+ *     ...
+ *   ]
+ *
+ * Strips inner hooks[] entries by command-pattern, drops groups whose inner
+ * hooks[] becomes empty, then appends a fresh group for the new entry.
+ *
+ * @param {object} opts
+ * @param {string} opts.settingsPath
+ * @param {string} opts.eventName            'SessionStart' | 'UserPromptSubmit' | ...
+ * @param {string} [opts.matcher]            Optional matcher string for the new group.
+ * @param {string} opts.command              Command for the new inner hook entry.
+ * @param {string} [opts.description]        Description (used at both group + inner levels).
+ * @param {string[]} opts.commandPatterns    Substrings to strip prior entries.
+ * @returns {{ changed: boolean, prevGroupsRemoved: number }}
+ */
+export function claudeHooksMerge({
+  settingsPath,
+  eventName,
+  matcher,
+  command,
+  description,
+  commandPatterns,
+}) {
+  if (!settingsPath || typeof settingsPath !== 'string') throw new Error('settingsPath is required');
+  if (!eventName || typeof eventName !== 'string') throw new Error('eventName is required');
+  if (!command || typeof command !== 'string') throw new Error('command is required');
+  const patterns = Array.isArray(commandPatterns) ? commandPatterns : [];
+
+  const root = readJsonOrEmpty(settingsPath);
+  if (root.hooks == null || typeof root.hooks !== 'object' || Array.isArray(root.hooks)) {
+    root.hooks = {};
+  }
+
+  const existingGroups = Array.isArray(root.hooks[eventName]) ? root.hooks[eventName] : [];
+
+  let prevGroupsRemoved = 0;
+  const survivingGroups = [];
+  for (const group of existingGroups) {
+    if (group == null || typeof group !== 'object') {
+      survivingGroups.push(group);
+      continue;
+    }
+    const innerHooks = Array.isArray(group.hooks) ? group.hooks : [];
+    const filteredInner = innerHooks.filter((h) => {
+      if (h == null || typeof h !== 'object') return true;
+      return !commandMatchesAnyPattern(h.command, patterns);
+    });
+
+    if (filteredInner.length === 0 && innerHooks.length > 0) {
+      prevGroupsRemoved += 1;
+      continue;
+    }
+    survivingGroups.push({ ...group, hooks: filteredInner });
+  }
+
+  const newGroup = {
+    ...(matcher !== undefined ? { matcher } : {}),
+    ...(description !== undefined ? { description } : {}),
+    hooks: [
+      {
+        type: 'command',
+        command,
+        ...(description !== undefined ? { description } : {}),
+      },
+    ],
+  };
+  survivingGroups.push(newGroup);
+  root.hooks[eventName] = survivingGroups;
+
+  const serialized = JSON.stringify(root, null, 2) + '\n';
+  const changed = atomicWriteIfChanged(settingsPath, serialized);
+
+  return { changed, prevGroupsRemoved };
+}

package/c4/mcpServer.mjs

@@ -0,0 +1,160 @@
+/**
+ * c4/mcpServer.mjs — register the `ghl-ai` MCP server across all three
+ * harnesses with the canonical MCP_URL_DEFAULT and Bearer auth.
+ *
+ * Per harness, the MCP config lives in a different file:
+ *   - claude-web    → ~/.claude/settings.json::mcpServers["ghl-ai"]
+ *   - cursor-cloud  → ~/.cursor/mcp.json::mcpServers["ghl-ai"]    (separate file!)
+ *   - codex-web     → ~/.codex/config.toml::[mcp_servers.ghl-ai]   (delegates to codexConfig)
+ *
+ * URL is overridable via env MCP_URL for staging environments. Bearer token
+ * is the harness's GitHub PAT (resolved upstream by secrets.mjs). Idempotent
+ * via deep-equality byte compare in the underlying writer.
+ *
+ * Contract: spec.md::§"c4/mcpServer.mjs", tasks.md::3.4.
+ */
+
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  renameSync,
+  chmodSync,
+  mkdirSync,
+  unlinkSync,
+} from 'node:fs';
+import { dirname, basename, join } from 'node:path';
+import { ensureCodexMcpServer } from './codexConfig.mjs';
+
+export const MCP_URL_DEFAULT =
+  'https://services.leadconnectorhq.com/agentic-workspace/mcp';
+
+const FILE_MODE = 0o600;
+
+function resolveUrl(opts) {
+  return opts?.mcpUrl ?? process.env.MCP_URL ?? MCP_URL_DEFAULT;
+}
+
+function ensureDir(d) {
+  mkdirSync(d, { recursive: true });
+}
+
+function readJsonOrEmpty(filePath) {
+  if (!existsSync(filePath)) return {};
+  const raw = readFileSync(filePath, 'utf8');
+  if (raw.trim() === '') return {};
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`Failed to parse JSON at ${filePath}: ${err.message}`);
+  }
+}
+
+function atomicWriteIfChanged(filePath, serialized) {
+  if (existsSync(filePath)) {
+    const prev = readFileSync(filePath, 'utf8');
+    if (prev === serialized) return false;
+  }
+
+  ensureDir(dirname(filePath));
+
+  const tmp = join(
+    dirname(filePath),
+    `.${basename(filePath)}.tmp.${process.pid}.${Math.random().toString(36).slice(2)}`
+  );
+
+  try {
+    writeFileSync(tmp, serialized, { mode: FILE_MODE });
+    renameSync(tmp, filePath);
+  } catch (err) {
+    if (existsSync(tmp)) {
+      try { unlinkSync(tmp); } catch { /* best-effort */ }
+    }
+    throw err;
+  }
+
+  try { chmodSync(filePath, FILE_MODE); } catch { /* best-effort */ }
+  return true;
+}
+
+/**
+ * Mutate root.mcpServers["ghl-ai"] for Claude/Cursor JSON-shaped configs.
+ * Other entries in mcpServers are preserved verbatim.
+ */
+function setGhlAiInJsonConfig({ filePath, url, token }) {
+  const root = readJsonOrEmpty(filePath);
+  if (
+    root.mcpServers == null ||
+    typeof root.mcpServers !== 'object' ||
+    Array.isArray(root.mcpServers)
+  ) {
+    root.mcpServers = {};
+  }
+  const prevHeaders = root.mcpServers['ghl-ai']?.headers;
+  root.mcpServers['ghl-ai'] = {
+    type: 'http',
+    url,
+    headers: {
+      ...(typeof prevHeaders === 'object' && prevHeaders !== null && !Array.isArray(prevHeaders)
+        ? prevHeaders
+        : {}),
+      Authorization: `Bearer ${token}`,
+    },
+  };
+
+  const serialized = JSON.stringify(root, null, 2) + '\n';
+  return atomicWriteIfChanged(filePath, serialized);
+}
+
+/**
+ * Register the ghl-ai MCP server in the harness-appropriate config file.
+ *
+ * @param {'claude-web'|'cursor-cloud'|'codex-web'} harness
+ * @param {string} home
+ * @param {string} token
+ * @param {{ mcpUrl?: string }} [opts]
+ * @returns {{ configPath: string, changed: boolean }}
+ */
+export function registerGhlAiMcp(harness, home, token, opts = {}) {
+  if (!home || typeof home !== 'string') {
+    throw new Error('registerGhlAiMcp: home is required');
+  }
+  if (!token || typeof token !== 'string') {
+    throw new Error('registerGhlAiMcp: token is required');
+  }
+
+  const url = resolveUrl(opts);
+
+  if (harness === 'claude-web') {
+    const configPath = join(home, '.claude/settings.json');
+    const changed = setGhlAiInJsonConfig({ filePath: configPath, url, token });
+    return { configPath, changed };
+  }
+
+  if (harness === 'cursor-cloud') {
+    const configPath = join(home, '.cursor/mcp.json');
+    const changed = setGhlAiInJsonConfig({ filePath: configPath, url, token });
+    return { configPath, changed };
+  }
+
+  if (harness === 'codex-web') {
+    const configPath = join(home, '.codex/config.toml');
+    // codexConfig honors process.env.MCP_URL itself; if a caller passed
+    // opts.mcpUrl, propagate via env temporarily to keep the contract simple.
+    if (opts.mcpUrl !== undefined) {
+      const prev = process.env.MCP_URL;
+      process.env.MCP_URL = opts.mcpUrl;
+      try {
+        const { changed } = ensureCodexMcpServer(home, token);
+        return { configPath, changed };
+      } finally {
+        if (prev === undefined) delete process.env.MCP_URL;
+        else process.env.MCP_URL = prev;
+      }
+    }
+    const { changed } = ensureCodexMcpServer(home, token);
+    return { configPath, changed };
+  }
+
+  throw new Error(`registerGhlAiMcp: unsupported harness "${harness}"`);
+}

package/c4/mcpSmokeProbe.mjs

@@ -0,0 +1,201 @@
+/**
+ * c4/mcpSmokeProbe.mjs — best-effort live MCP Bearer probe (G5).
+ *
+ * Why: writing the MCP config (mcpServer.mjs) confirms the JSON shape, not
+ * that the server validates the Bearer header against this PAT's scopes. A
+ * user with a scope-limited PAT sees green install and red MCP calls at
+ * runtime. This probe surfaces that gap in the install log.
+ *
+ * Best-effort: NEVER throws on transport / response failures. Argument
+ * validation errors (missing url/token) DO throw because they are caller
+ * bugs, not server failures.
+ *
+ * Returns one of:
+ *   - 'ok'             200 + valid JSON-RPC tools/list response
+ *   - 'invalid-token'  401
+ *   - 'unauthorized'   403 (PAT lacks scope)
+ *   - 'unreachable'    timeout / network error
+ *   - 'unknown'        200 with unexpected body, 426 Upgrade, SSE handshake,
+ *                      generic non-2xx, or any unrecognized condition
+ *
+ * Contract: spec.md::§"c4/mcpSmokeProbe.mjs", tasks.md::3.8.
+ */
+
+const DEFAULT_TIMEOUT_MS = 5000;
+
+/**
+ * @typedef {object} McpSmokeResult
+ * @property {string} url
+ * @property {boolean} reachable        HTTP response was received (any status).
+ * @property {number}  [toolCount]      Number of tools when authStatus === 'ok'.
+ * @property {'ok'|'invalid-token'|'unauthorized'|'unreachable'|'unknown'} authStatus
+ * @property {string}  [error]          Protocol-mismatch / status excerpt.
+ */
+
+/**
+ * Probe an MCP HTTP endpoint with a JSON-RPC tools/list request.
+ *
+ * @param {object} opts
+ * @param {string} opts.url
+ * @param {string} opts.token
+ * @param {number} [opts.timeoutMs]
+ * @param {(input: string, init?: RequestInit) => Promise<Response>} [opts.fetchImpl]
+ *   Optional fetch override; defaults to globalThis.fetch.
+ * @returns {Promise<McpSmokeResult>}
+ */
+export async function probeMcpServer(opts) {
+  if (!opts || typeof opts !== 'object') {
+    throw new Error('probeMcpServer: opts object is required');
+  }
+  const { url, token } = opts;
+  if (!url || typeof url !== 'string') {
+    throw new Error('probeMcpServer: opts.url is required');
+  }
+  if (!token || typeof token !== 'string') {
+    throw new Error('probeMcpServer: opts.token is required');
+  }
+
+  const timeoutMs = typeof opts.timeoutMs === 'number' && opts.timeoutMs > 0
+    ? opts.timeoutMs
+    : DEFAULT_TIMEOUT_MS;
+  const fetchImpl = typeof opts.fetchImpl === 'function'
+    ? opts.fetchImpl
+    : globalThis.fetch;
+  if (typeof fetchImpl !== 'function') {
+    return { url, reachable: false, authStatus: 'unreachable', error: 'fetch unavailable' };
+  }
+
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), timeoutMs);
+
+  let response;
+  try {
+    response = await fetchImpl(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${token}`,
+      },
+      body: JSON.stringify({
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'tools/list',
+        params: {},
+      }),
+      signal: ac.signal,
+    });
+  } catch (err) {
+    clearTimeout(timer);
+    return classifyTransportError(url, err);
+  }
+  clearTimeout(timer);
+
+  if (response == null || typeof response !== 'object') {
+    return { url, reachable: false, authStatus: 'unknown', error: 'no response object' };
+  }
+
+  return await classifyResponse(url, response);
+}
+
+/**
+ * Map a thrown transport error to a structured result.
+ */
+function classifyTransportError(url, err) {
+  const name = err?.name ?? '';
+  const msg = err?.message ?? String(err);
+  if (name === 'AbortError') {
+    return { url, reachable: false, authStatus: 'unreachable', error: `timeout: ${msg}` };
+  }
+  // Most undici / native fetch network errors throw TypeError("fetch failed").
+  return { url, reachable: false, authStatus: 'unreachable', error: msg };
+}
+
+/**
+ * Map an HTTP response to a structured result.
+ */
+async function classifyResponse(url, response) {
+  const status = typeof response.status === 'number' ? response.status : 0;
+  const contentType = readHeader(response, 'content-type') ?? '';
+
+  // Streamable-HTTP / SSE: documented fallback per spec §"Streamable-HTTP fallback path".
+  if (status === 426 || contentType.includes('text/event-stream')) {
+    return {
+      url,
+      reachable: true,
+      authStatus: 'unknown',
+      error: `streamable-http transport detected (status=${status}; content-type=${contentType || 'unknown'})`,
+    };
+  }
+
+  if (status === 401) return { url, reachable: true, authStatus: 'invalid-token' };
+  if (status === 403) return { url, reachable: true, authStatus: 'unauthorized' };
+
+  if (status >= 200 && status < 300) {
+    let bodyText = '';
+    try {
+      bodyText = await response.text();
+    } catch (err) {
+      return {
+        url,
+        reachable: true,
+        authStatus: 'unknown',
+        error: `body read failed: ${err?.message ?? String(err)}`,
+      };
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(bodyText);
+    } catch {
+      return {
+        url,
+        reachable: true,
+        authStatus: 'unknown',
+        error: `unexpected body shape (not JSON): ${truncate(bodyText, 80)}`,
+      };
+    }
+    const tools = parsed?.result?.tools;
+    if (!Array.isArray(tools)) {
+      return {
+        url,
+        reachable: true,
+        authStatus: 'unknown',
+        error: `unexpected body shape (missing result.tools)`,
+      };
+    }
+    return { url, reachable: true, authStatus: 'ok', toolCount: tools.length };
+  }
+
+  // Any other status is unknown — surface what we have for the operator.
+  return {
+    url,
+    reachable: true,
+    authStatus: 'unknown',
+    error: `status=${status}; content-type=${contentType || 'unknown'}`,
+  };
+}
+
+/**
+ * Read a header from a Response-like object regardless of whether headers is
+ * a Headers instance, a Map, or a plain object.
+ */
+function readHeader(response, name) {
+  const target = name.toLowerCase();
+  const h = response.headers;
+  if (!h) return null;
+  if (typeof h.get === 'function') {
+    const v = h.get(target) ?? h.get(name);
+    return v == null ? null : String(v);
+  }
+  if (h instanceof Map) {
+    return h.get(target) ?? h.get(name) ?? null;
+  }
+  for (const k of Object.keys(h)) {
+    if (k.toLowerCase() === target) return String(h[k]);
+  }
+  return null;
+}
+
+function truncate(s, n) {
+  if (typeof s !== 'string') return '';
+  return s.length > n ? `${s.slice(0, n)}…` : s;
+}