simframe 0.13.0 → 0.14.1

package/src/platform/ios.js

@@ -9,9 +9,50 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { promisify } from 'node:util';
+import * as plist from './plist.js';
 
 const run = promisify(execFile);
 
+/**
+ * How long a `simctl` verb may take before we stop waiting.
+ *
+ * **It was 20s, and that was below what a loaded runner actually needs.** Item
+ * 142 recorded `simctl launch` "taking 47-55s" on a hosted runner and filed it
+ * under a boot that had not finished; the launches were real and the budget was
+ * simply shorter than they were. The same 20s sat on `openurl`, which is the
+ * failure class that item listed four runs of, and on `terminate`. One number,
+ * three symptoms, and every one of them read as the command refusing rather
+ * than as us leaving.
+ *
+ * 90s is chosen against that measurement — comfortably past the observed 55s
+ * worst case — and not for feel. A `simctl` verb that has not returned in
+ * ninety seconds is genuinely wrong, and says so below instead of being
+ * indistinguishable from a rejection.
+ */
+const SIMCTL_TIMEOUT_MS = 90_000;
+
+/** A local file decode, which owes nothing to device latency. */
+const PLUTIL_TIMEOUT_MS = 20_000;
+
+/**
+ * What actually went wrong, including the case that has been invisible.
+ *
+ * On a timeout `execFile` kills the child, so `stderr` is EMPTY and `message`
+ * is the bare "Command failed: xcrun simctl ..." — which reads exactly like
+ * simctl rejecting the request. Three separate investigations have started from
+ * that sentence and gone looking for a broken device. The timeout has to name
+ * itself, or the next one starts in the same wrong place.
+ */
+function simctlFailure(err, what) {
+  const detail = (err.stderr || '').trim().split('\n').filter(Boolean).pop();
+  if (detail) return `${what}: ${detail}`;
+  if (err.killed || err.signal === 'SIGTERM') {
+    return `${what}: simctl did not return within ${Math.round(SIMCTL_TIMEOUT_MS / 1000)}s`
+      + ' (killed by simframe, not refused by simctl — the host is loaded or the device is not answering)';
+  }
+  return `${what}: ${err.message}`;
+}
+
 // `simctl list` costs ~130ms, which would otherwise dominate every warm read,
 // so the parsed list is cached for a few seconds.
 const DEVICE_CACHE_MS = 4000;
@@ -239,24 +280,33 @@ async function launchApp(udid, bundleId, { args = [], env = {}, terminateFirst =
   for (const [k, v] of Object.entries(env)) childEnv[`SIMCTL_CHILD_${k}`] = String(v);
   try {
     await run('xcrun', ['simctl', 'launch', udid, bundleId, ...args.map(String)], {
-      timeout: 20_000,
+      timeout: SIMCTL_TIMEOUT_MS,
       env: childEnv,
     });
   } catch (err) {
     // execFile's message is just "Command failed: ..." with simctl's actual
     // complaint left in stderr. A CI run failed here and said nothing about
     // why, which is the same sin as a silent fallback.
-    const detail = (err.stderr || '').trim().split('\n').filter(Boolean).pop();
-    throw new Error(detail ? `could not launch ${bundleId}: ${detail}` : `could not launch ${bundleId}: ${err.message}`);
+    throw new Error(simctlFailure(err, `could not launch ${bundleId}`));
   }
 }
 
 async function terminateApp(udid, bundleId) {
-  await run('xcrun', ['simctl', 'terminate', udid, bundleId], { timeout: 20_000 });
+  try {
+    await run('xcrun', ['simctl', 'terminate', udid, bundleId], { timeout: SIMCTL_TIMEOUT_MS });
+  } catch (err) {
+    throw new Error(simctlFailure(err, `could not terminate ${bundleId}`));
+  }
 }
 
 async function openUrl(udid, url) {
-  await run('xcrun', ['simctl', 'openurl', udid, url], { timeout: 20_000 });
+  // The same budget and the same reporting as `launch`, because it was the same
+  // 20s and it is the failure class item 142 counted four runs of.
+  try {
+    await run('xcrun', ['simctl', 'openurl', udid, url], { timeout: SIMCTL_TIMEOUT_MS });
+  } catch (err) {
+    throw new Error(simctlFailure(err, 'could not open the url'));
+  }
 }
 
 /**
@@ -304,10 +354,9 @@ async function setPermission(udid, action, service, bundleId) {
   const args = ['simctl', 'privacy', udid, verb, service];
   if (bundleId) args.push(bundleId);
   try {
-    await run('xcrun', args, { timeout: 20_000 });
+    await run('xcrun', args, { timeout: SIMCTL_TIMEOUT_MS });
   } catch (err) {
-    const detail = (err.stderr || '').trim().split('\n').filter(Boolean).pop();
-    throw new Error(`could not ${verb} ${service}: ${detail || err.message}`);
+    throw new Error(simctlFailure(err, `could not ${verb} ${service}`));
   }
   return `${verb === 'reset' ? 'reset' : verb + 'ed'} ${service}${bundleId ? ` for ${bundleId}` : ''}`;
 }
@@ -334,6 +383,104 @@ function ownsUdid(udid) {
   return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(String(udid ?? ''));
 }
 
+/**
+ * Where CoreSimulator keeps a device's data.
+ *
+ * Read straight off disk, and that is the whole point of this family rather
+ * than an optimisation. Measured on this Xcode: `simctl get_app_container` and
+ * `simctl listapps` **both** fail on a device that is not running —
+ * `Unable to lookup in current state: Shutdown`. The field report that asked
+ * for this feature rated it highest-leverage precisely because it answered
+ * "what did the app save?" *before the device was booted*, and simctl cannot do
+ * that. The filesystem can, so this reads the filesystem.
+ */
+const deviceRoot = (udid) =>
+  path.join(os.homedir(), 'Library/Developer/CoreSimulator/Devices', String(udid));
+
+const containerRoot = (udid) => path.join(deviceRoot(udid), 'data/Containers/Data/Application');
+
+/** The per-container metadata file that says which app owns it. */
+const METADATA = '.com.apple.mobile_container_manager.metadata.plist';
+
+/**
+ * Every app with a data container on this device, booted or not.
+ *
+ * The bundle id lives in `MCMMetadataIdentifier` in each container's metadata
+ * plist. It is *not* recoverable by grepping the file — the binary plist
+ * encodes strings in a way that does not leave the id as a plain substring, and
+ * an early version of this that tried to pre-filter that way matched nothing.
+ * So each metadata file is asked properly. Measured at **0.52s for 150
+ * containers**, which is a listing cost rather than a per-read one.
+ */
+async function listApps(udid) {
+  const root = containerRoot(udid);
+  let entries;
+  try {
+    entries = await fs.promises.readdir(root, { withFileTypes: true });
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      const exists = fs.existsSync(deviceRoot(udid));
+      throw new Error(exists
+        ? `device ${udid} has no app data containers yet — nothing has been installed on it`
+        : `no simulator data directory for ${udid} (looked in ${root})`);
+    }
+    throw err;
+  }
+  const apps = [];
+  await Promise.all(entries.filter((e) => e.isDirectory()).map(async (e) => {
+    const dir = path.join(root, e.name);
+    try {
+      const { stdout } = await run('plutil',
+        ['-extract', 'MCMMetadataIdentifier', 'raw', '-o', '-', path.join(dir, METADATA)],
+        { timeout: 10_000 });
+      const bundleId = stdout.trim();
+      if (bundleId) apps.push({ bundleId, container: dir });
+    } catch {
+      // A container without readable metadata is not an app we can name, and
+      // naming it by its UUID would be offering an id nobody can use.
+    }
+  }));
+  return apps.sort((a, b) => a.bundleId.localeCompare(b.bundleId));
+}
+
+/** The data container for one app, or a listing of what is there instead. */
+async function appContainer(udid, bundleId) {
+  const apps = await listApps(udid);
+  const hit = apps.find((a) => a.bundleId === bundleId);
+  if (hit) return hit.container;
+  // Near misses first: the id is the thing people get wrong, and a bare "not
+  // installed" on a device with the app under a slightly different id is the
+  // least useful true sentence available.
+  const needle = String(bundleId).toLowerCase();
+  const near = apps.filter((a) => a.bundleId.toLowerCase().includes(needle)
+    || needle.includes(a.bundleId.toLowerCase())).slice(0, 5);
+  throw new Error(
+    `"${bundleId}" has no data container on ${udid}`
+    + (near.length ? ` — did you mean ${near.map((a) => a.bundleId).join(', ')}?` : '')
+    + ` (${apps.length} app(s) have one)`,
+  );
+}
+
+/**
+ * Read a property list, whatever it contains.
+ *
+ * `-convert xml1` and not `json`: six of the twenty real preference plists on
+ * the bench device cannot be represented as JSON at all, because `<data>` and
+ * `<date>` have no JSON form and plutil refuses rather than inventing one. See
+ * the note at the top of plist.js.
+ */
+async function readPropertyList(file) {
+  // Its own budget, deliberately not the simctl one. This reads a local file
+  // and never speaks to a device, so it has none of the latency the simctl
+  // budget exists to absorb — and a plist that takes twenty seconds to decode
+  // is a problem worth hearing about promptly.
+  const { stdout } = await run('plutil', ['-convert', 'xml1', '-o', '-', file], {
+    timeout: PLUTIL_TIMEOUT_MS,
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  return plist.parse(stdout);
+}
+
 /**
  * The prerequisites `simframe doctor` reports for this backend. Returned rather
  * than printed so doctor stays one renderer: a backend says what it needs, and
@@ -440,6 +587,9 @@ export const platform = {
   terminateApp,
   openUrl,
   restartDevice,
+  listApps,
+  appContainer,
+  readPropertyList,
   setPermission,
   setPasteboard,
   permissionServices: () => PERMISSION_SERVICES,

package/src/platform/plist.js

@@ -0,0 +1,156 @@
+// Property lists, parsed without a dependency.
+//
+// Below the platform boundary on purpose. A plist is not a neutral file format
+// this project happens to read — it is how one platform stores what an app
+// believes, and `plutil` is that platform's tool. Android's answer to the same
+// question is a different file in a different shape, which is why the parsing
+// lives beside the backend that needs it rather than above the seam.
+//
+// **Why XML and not JSON.** `plutil -convert json` is the obvious route and it
+// does not work: measured across the twenty real `Library/Preferences` plists
+// on the bench device, **six of them failed to convert** — 30%, because JSON
+// has no representation for `<data>` or `<date>` and plutil refuses rather than
+// inventing one. `-convert xml1` succeeded on all twenty. A format that drops
+// three in ten real files is not a parser, it is a sampler.
+//
+// The XML here is machine-written by plutil, so this is a reader for that
+// output and not a general XML parser: no namespaces, no processing
+// instructions beyond the declaration, no mixed content. It is strict about
+// what it does not understand — an unknown tag throws rather than being skipped,
+// because a silently dropped key in a store read is a wrong answer about what
+// an app believes, and this whole feature exists to be trusted on that point.
+
+const ENTITIES = { lt: '<', gt: '>', amp: '&', quot: '"', apos: "'" };
+
+/** Decode the five XML entities plutil emits, plus numeric escapes. */
+export function decodeEntities(s) {
+  return String(s).replace(/&(#x?[0-9a-fA-F]+|[a-z]+);/g, (whole, body) => {
+    if (body[0] === '#') {
+      const code = body[1] === 'x' || body[1] === 'X'
+        ? parseInt(body.slice(2), 16)
+        : parseInt(body.slice(1), 10);
+      return Number.isFinite(code) ? String.fromCodePoint(code) : whole;
+    }
+    return ENTITIES[body] ?? whole;
+  });
+}
+
+/**
+ * A `<data>` value.
+ *
+ * Kept as a tagged object rather than decoded to a Buffer or dropped. The
+ * caller is usually a human asking what an app persisted, and "a 4 KB blob"
+ * is a real and often sufficient answer — while silently omitting the key
+ * would misreport the store as not having it.
+ */
+const dataValue = (base64) => {
+  const clean = base64.replace(/\s+/g, '');
+  return {
+    __type: 'data',
+    bytes: Math.floor((clean.length * 3) / 4) - (clean.endsWith('==') ? 2 : clean.endsWith('=') ? 1 : 0),
+    base64: clean,
+  };
+};
+
+/**
+ * Parse the XML property list plutil writes.
+ *
+ * @param {string} xml output of `plutil -convert xml1 -o -`
+ * @returns {*} the plist's root value — normally an object
+ */
+export function parse(xml) {
+  const src = String(xml);
+  // Everything before <plist> is the declaration and the DOCTYPE, neither of
+  // which carries data.
+  const start = src.indexOf('<plist');
+  if (start < 0) throw new Error('not an XML property list (no <plist> element)');
+  let i = src.indexOf('>', start);
+  if (i < 0) throw new Error('not an XML property list (unterminated <plist>)');
+  i += 1;
+
+  /** The next tag at or after `i`, skipping text that is only whitespace. */
+  const nextTag = () => {
+    const open = src.indexOf('<', i);
+    if (open < 0) return null;
+    const close = src.indexOf('>', open);
+    if (close < 0) throw new Error('unterminated tag in property list');
+    const raw = src.slice(open + 1, close);
+    i = close + 1;
+    const selfClosing = raw.endsWith('/');
+    const name = raw.replace(/\/$/, '').trim().split(/\s/)[0];
+    return { name: name.replace(/^\//, ''), closing: raw.startsWith('/'), selfClosing };
+  };
+
+  /** Text up to the matching close tag, which plutil never nests inside a leaf. */
+  const textUntilClose = (tag) => {
+    const close = src.indexOf(`</${tag}>`, i);
+    if (close < 0) throw new Error(`unterminated <${tag}> in property list`);
+    const text = src.slice(i, close);
+    i = close + tag.length + 3;
+    return text;
+  };
+
+  const readValue = (tag) => {
+    switch (tag.name) {
+      case 'true': return true;
+      case 'false': return false;
+      case 'string': return tag.selfClosing ? '' : decodeEntities(textUntilClose('string'));
+      case 'integer': {
+        const text = textUntilClose('integer').trim();
+        const n = Number(text);
+        // A plist integer is 64-bit and JavaScript's is not. Returning a
+        // silently-rounded number would be a wrong answer about a stored value,
+        // so the exact digits survive as a string and the shape says why.
+        if (!Number.isSafeInteger(n)) return { __type: 'integer', exact: text };
+        return n;
+      }
+      case 'real': return Number(textUntilClose('real').trim());
+      case 'date': return { __type: 'date', iso: textUntilClose('date').trim() };
+      case 'data': return dataValue(textUntilClose('data'));
+      case 'dict': {
+        if (tag.selfClosing) return {};
+        const out = {};
+        for (;;) {
+          const t = nextTag();
+          if (!t) throw new Error('unterminated <dict> in property list');
+          if (t.closing && t.name === 'dict') return out;
+          if (t.name !== 'key') throw new Error(`expected <key> in <dict>, found <${t.name}>`);
+          const key = t.selfClosing ? '' : decodeEntities(textUntilClose('key'));
+          const vt = nextTag();
+          if (!vt) throw new Error(`<key>${key}</key> has no value`);
+          out[key] = readValue(vt);
+        }
+      }
+      case 'array': {
+        if (tag.selfClosing) return [];
+        const out = [];
+        for (;;) {
+          const t = nextTag();
+          if (!t) throw new Error('unterminated <array> in property list');
+          if (t.closing && t.name === 'array') return out;
+          out.push(readValue(t));
+        }
+      }
+      default:
+        // Deliberately not a skip. See the note at the top of this file.
+        throw new Error(`unsupported property-list element <${tag.name}>`);
+    }
+  };
+
+  const root = nextTag();
+  if (!root || root.closing) return null;
+  return readValue(root);
+}
+
+/**
+ * What kind of thing a parsed value is, in one word, for a listing.
+ *
+ * `typeof` is not enough: the tagged shapes above are objects, and calling a
+ * date "object" in a store listing tells the reader nothing they wanted.
+ */
+export function typeOf(value) {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'array';
+  if (typeof value === 'object') return value.__type ?? 'dict';
+  return typeof value;
+}

package/src/storage.js

@@ -0,0 +1,201 @@
+// What the app believes.
+//
+// The perception tools answer "what is drawn". This answers "what did the app
+// save", and the field report that asked for it put the pairing better than we
+// did: *"`sim_ui` says what is drawn, `sim_storage` says what the app
+// believes."* Their highest-leverage moment in a whole session was not a
+// simframe call at all — they read the persisted store straight out of the data
+// container, found the exact wrong value the app had written, and proved the bug
+// with no live session, no login, and the device not yet booted.
+//
+// That last property is the design constraint, not a bonus. Measured on this
+// Xcode, `simctl get_app_container` and `simctl listapps` both refuse on a
+// device that is not running. So nothing here goes through the device: the
+// backend reads the container off the host filesystem, and a shut-down device
+// answers exactly as well as a running one.
+//
+// Nothing in this file knows which platform it is on. Where a container lives
+// and how a property list is decoded are the backend's business; what a store
+// is, and how to say what is in one, are this file's.
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import * as platform from './platform/index.js';
+
+/**
+ * How much of a single value is printed before the rest is summarised.
+ *
+ * Generous on purpose — the whole point is to see what the app actually wrote,
+ * and a value clipped to eighty characters answers nothing. What this must
+ * never do is clip *silently*: item 141 in DEFERRED is a harness that cut a
+ * failure report one character before the only content that mattered, and the
+ * lesson was that a reader who is not told about a cut reads the fragment as
+ * the whole. So past this, the text says how many bytes it is not showing and
+ * how to get them.
+ */
+export const VALUE_PREVIEW_BYTES = 4096;
+
+/** React Native's own store, in the layout its iOS implementation writes. */
+const ASYNC_STORAGE_DIR = 'RCTAsyncLocalStorage_V1';
+const ASYNC_STORAGE_MANIFEST = 'manifest.json';
+
+/** Files that are plainly a store but that nothing here can decode yet. */
+const OPAQUE_STORES = /\.(sqlite3?|db|realm|leveldb|mmkv)$/i;
+
+const readJson = (file) => JSON.parse(fs.readFileSync(file, 'utf8'));
+const sizeOf = (file) => { try { return fs.statSync(file).size; } catch { return null; } };
+
+/** Every app with a data container on the device, whether or not it is running. */
+export async function apps(udid) {
+  return platform.listApps(udid);
+}
+
+/**
+ * React Native's AsyncStorage.
+ *
+ * The manifest holds small values inline. A value past RN's inline threshold is
+ * stored as `null` in the manifest and written to a file beside it named by the
+ * MD5 of the key — so a manifest full of nulls is not an empty store, and
+ * reporting it as one would be the exact class of wrong answer this feature
+ * exists to stop.
+ */
+export function readAsyncStorage(container) {
+  const dir = path.join(container, 'Documents', ASYNC_STORAGE_DIR);
+  const manifestPath = path.join(dir, ASYNC_STORAGE_MANIFEST);
+  if (!fs.existsSync(manifestPath)) return null;
+  const manifest = readJson(manifestPath);
+  const entries = [];
+  for (const [key, inline] of Object.entries(manifest)) {
+    if (inline !== null && inline !== undefined) {
+      entries.push({ key, value: inline, type: typeof inline, where: 'manifest' });
+      continue;
+    }
+    const spilled = path.join(dir, crypto.createHash('md5').update(key).digest('hex'));
+    if (fs.existsSync(spilled)) {
+      const value = fs.readFileSync(spilled, 'utf8');
+      entries.push({ key, value, type: 'string', bytes: sizeOf(spilled), where: 'spilled to its own file' });
+    } else {
+      // Say which of the two this is. "Null" and "too big to inline, and the
+      // file is missing" are different facts about the app.
+      entries.push({ key, value: null, type: 'null', where: 'manifest says null and no spill file exists' });
+    }
+  }
+  return { name: 'AsyncStorage', source: dir, entries };
+}
+
+/**
+ * Preference plists in the container.
+ *
+ * The one named after the bundle id is the app's own `UserDefaults`; the others
+ * are real and are named rather than hidden, because a framework writing its
+ * state beside the app's is often exactly what the reader is hunting.
+ */
+async function readPreferences(udid, container, bundleId) {
+  const dir = path.join(container, 'Library', 'Preferences');
+  let files;
+  try {
+    files = fs.readdirSync(dir).filter((f) => f.endsWith('.plist'));
+  } catch {
+    return [];
+  }
+  const stores = [];
+  for (const file of files.sort()) {
+    const full = path.join(dir, file);
+    const own = file === `${bundleId}.plist`;
+    try {
+      const parsed = await platform.readPropertyList(udid, full);
+      stores.push({
+        name: own ? 'UserDefaults' : `UserDefaults (${file.replace(/\.plist$/, '')})`,
+        source: full,
+        entries: Object.entries(parsed ?? {}).map(([key, value]) => ({ key, value, type: typeOf(value) })),
+      });
+    } catch (err) {
+      // Degrade rather than fail: one unreadable plist must not cost the
+      // reader every other store in the container.
+      stores.push({ name: own ? 'UserDefaults' : file, source: full, entries: [], error: err.message });
+    }
+  }
+  // The app's own defaults first; that is what was asked about.
+  return stores.sort((a, b) => Number(b.name === 'UserDefaults') - Number(a.name === 'UserDefaults'));
+}
+
+/** Stores that are plainly present and that nothing here can decode. */
+export function opaqueStores(container) {
+  const found = [];
+  const walk = (dir, depth) => {
+    if (depth > 3) return;
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) walk(full, depth + 1);
+      else if (OPAQUE_STORES.test(e.name)) found.push({ file: path.relative(container, full), bytes: sizeOf(full) });
+    }
+  };
+  walk(container, 0);
+  return found;
+}
+
+/** One word for what a value is, including the tagged shapes a plist produces. */
+export function typeOf(value) {
+  if (value === null || value === undefined) return 'null';
+  if (Array.isArray(value)) return 'array';
+  if (typeof value === 'object') return value.__type ?? 'dict';
+  return typeof value;
+}
+
+/**
+ * Everything one app has persisted that this can read, and an honest list of
+ * what it could not.
+ */
+export async function read(udid, bundleId) {
+  const container = await platform.appContainer(udid, bundleId);
+  const stores = await readPreferences(udid, container, bundleId);
+  const async_ = readAsyncStorage(container);
+  if (async_) stores.push(async_);
+  return { bundleId, container, stores, opaque: opaqueStores(container) };
+}
+
+/** One value, rendered for reading, saying so whenever it is not the whole thing. */
+export function renderValue(value) {
+  if (value && typeof value === 'object' && value.__type === 'data') {
+    return `<${value.bytes} bytes of data> ${value.base64.slice(0, 64)}${value.base64.length > 64 ? '…' : ''}`;
+  }
+  if (value && typeof value === 'object' && value.__type === 'date') return value.iso;
+  if (value && typeof value === 'object' && value.__type === 'integer') return value.exact;
+  const text = typeof value === 'string' ? value : JSON.stringify(value);
+  if (text == null) return String(value);
+  if (text.length <= VALUE_PREVIEW_BYTES) return text;
+  // Announced, never silent. See VALUE_PREVIEW_BYTES.
+  return `${text.slice(0, VALUE_PREVIEW_BYTES)}\n    … ${text.length - VALUE_PREVIEW_BYTES} more character(s) not shown`
+    + ' — read the file named under `from:` for the whole value';
+}
+
+/** The text form: what the app believes, one store at a time. */
+export function format(result) {
+  const lines = [`${result.bundleId}`, `  container ${result.container}`];
+  if (!result.stores.length) lines.push('  no readable store — the app has persisted nothing this can decode');
+  for (const store of result.stores) {
+    lines.push('');
+    lines.push(`  ${store.name} — ${store.entries.length} key(s)`);
+    lines.push(`  from: ${store.source}`);
+    if (store.error) lines.push(`    unreadable: ${store.error}`);
+    for (const e of store.entries) {
+      const where = e.where && e.where !== 'manifest' ? `  (${e.where})` : '';
+      lines.push(`    ${e.key}  [${e.type}]${where}`);
+      lines.push(`      ${renderValue(e.value).split('\n').join('\n      ')}`);
+    }
+  }
+  if (result.opaque?.length) {
+    lines.push('');
+    lines.push(`  ${result.opaque.length} store(s) present that this cannot decode yet:`);
+    for (const o of result.opaque) lines.push(`    ${o.file}  ${o.bytes} bytes`);
+  }
+  return lines.join('\n');
+}
+
+/** The listing form. */
+export function formatApps(list) {
+  if (!list.length) return 'no app has a data container on this device';
+  return [`${list.length} app(s) with a data container`, ...list.map((a) => `  ${a.bundleId}`)].join('\n');
+}