reis-mobile 0.7.3 → 0.9.0

package/core/providers/consult.mjs

@@ -0,0 +1,220 @@
+import { spawn } from 'node:child_process';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { redactSecrets } from '../security/redact.mjs';
+import { findProvider } from './catalog.mjs';
+
+export const DEFAULT_TIMEOUT_MS = 120_000;
+const MAX_OUTPUT_BYTES = 2_000_000;
+const ERROR_BODY_CHARS = 300;
+
+/**
+ * Asks each provider the same question, in parallel, and returns one result per requested
+ * provider.
+ *
+ * The core makes the call instead of handing the model a command to run: a credential must
+ * never reach a transcript or a tool log. The prompt is redacted on the way out — a
+ * third-party provider is exactly the boundary `redactSecrets` exists for — and every answer
+ * is redacted on the way in, because a provider can echo back what it was given.
+ *
+ * Statuses: `ok`, `unavailable` (the provider cannot be reached at all), `no-model`,
+ * `timeout`, `error`.
+ */
+export async function consult({
+  prompt,
+  providers,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  env = process.env,
+  fetchImpl = globalThis.fetch,
+  runCommand = spawnCommand,
+} = {}) {
+  const text = redactSecrets(String(prompt ?? ''));
+  if (!text.trim()) throw new Error('consult needs a prompt. Pass it as an argument, with --file, or on stdin.');
+
+  const results = await Promise.all(
+    providers.map((resolved) => askOne({ resolved, prompt: text, timeoutMs, env, fetchImpl, runCommand })),
+  );
+  return {
+    prompt: { chars: text.length, redacted: text !== String(prompt ?? '') },
+    timeoutMs,
+    results,
+  };
+}
+
+async function askOne({ resolved, prompt, timeoutMs, env, fetchImpl, runCommand }) {
+  const base = {
+    provider: resolved.id,
+    label: resolved.label,
+    kind: resolved.kind,
+    model: resolved.model,
+    status: 'error',
+    text: '',
+    error: null,
+    durationMs: 0,
+  };
+  if (!resolved.selectable) return { ...base, status: 'unavailable', error: resolved.detail };
+  if (resolved.needsModel && !resolved.model) {
+    const provider = findProvider(resolved.id);
+    return {
+      ...base,
+      status: 'no-model',
+      error: `no model configured. Set ${provider.modelEnv}, or providers.${resolved.id}.model in the config file, or pass --model. Run \`reis-mobile providers --models --providers ${resolved.id}\` to see what it serves.`,
+    };
+  }
+
+  const started = Date.now();
+  const outcome = await (resolved.kind === 'cli'
+    ? askCli({ resolved, prompt, timeoutMs, env, runCommand })
+    : askHttp({ resolved, prompt, timeoutMs, env, fetchImpl }));
+  return { ...base, ...outcome, durationMs: Date.now() - started };
+}
+
+async function askHttp({ resolved, prompt, timeoutMs, env, fetchImpl }) {
+  const provider = findProvider(resolved.id);
+  const { url, init } = provider.chat({ prompt, model: resolved.model, env });
+  const response = await withTimeout(timeoutMs, (signal) => fetchImpl(url, { ...init, signal }));
+  if (response.timedOut) return { status: 'timeout', error: `no answer in ${timeoutMs} ms` };
+  if (response.failed) return { status: 'error', error: safe(response.error) };
+
+  if (!response.value.ok) {
+    const body = await readBody(response.value);
+    return { status: 'error', error: safe(`HTTP ${response.value.status}${body ? `: ${body.slice(0, ERROR_BODY_CHARS)}` : ''}`) };
+  }
+  let payload;
+  try {
+    payload = await response.value.json();
+  } catch {
+    return { status: 'error', error: 'the answer was not JSON' };
+  }
+  const text = safe(provider.readChat(payload));
+  return text.trim() ? { status: 'ok', text } : { status: 'error', error: 'the provider returned no text' };
+}
+
+/**
+ * CLI providers run in a throwaway directory. `codex exec --full-auto` and `gemini
+ * --approval-mode yolo` may write files, and the briefing already carries every file they
+ * need to read, so there is no reason to give them the user's repository as a workspace.
+ */
+async function askCli({ resolved, prompt, timeoutMs, env, runCommand }) {
+  const provider = findProvider(resolved.id);
+  const workdir = await mkdtemp(join(tmpdir(), 'reis-mobile-consult-'));
+  try {
+    const result = await runCommand({
+      command: provider.command,
+      args: provider.argv({ prompt }),
+      stdin: provider.stdin({ prompt }),
+      cwd: workdir,
+      timeoutMs,
+      env,
+    });
+    if (result.status === 'timeout') return { status: 'timeout', error: `no answer in ${timeoutMs} ms` };
+    if (result.status === 'error') return { status: 'error', error: safe(result.error) };
+    const text = safe(result.stdout).trim();
+    return text ? { status: 'ok', text } : { status: 'error', error: 'the provider returned no text' };
+  } finally {
+    await rm(workdir, { recursive: true, force: true });
+  }
+}
+
+/** What each selected provider says it serves, so reis-mobile never invents a model id. */
+export async function listProviderModels({ providers, env = process.env, fetchImpl = globalThis.fetch, timeoutMs = 30_000 } = {}) {
+  return Promise.all(
+    providers.map(async (resolved) => {
+      const base = { provider: resolved.id, label: resolved.label, kind: resolved.kind, models: [], status: 'error', error: null };
+      if (resolved.kind === 'cli') return { ...base, status: 'unsupported', error: 'a CLI provider uses the model it is configured with' };
+      if (!resolved.selectable) return { ...base, status: 'unavailable', error: resolved.detail };
+
+      const provider = findProvider(resolved.id);
+      const { url, init } = provider.catalog({ env });
+      const response = await withTimeout(timeoutMs, (signal) => fetchImpl(url, { ...init, signal }));
+      if (response.timedOut) return { ...base, status: 'timeout', error: `no answer in ${timeoutMs} ms` };
+      if (response.failed) return { ...base, status: 'error', error: safe(response.error) };
+      if (!response.value.ok) return { ...base, status: 'error', error: safe(`HTTP ${response.value.status}`) };
+      try {
+        return { ...base, status: 'ok', models: provider.readCatalog(await response.value.json()) };
+      } catch {
+        return { ...base, status: 'error', error: 'the answer was not JSON' };
+      }
+    }),
+  );
+}
+
+async function withTimeout(timeoutMs, call) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    return { value: await call(controller.signal) };
+  } catch (error) {
+    return controller.signal.aborted ? { timedOut: true } : { failed: true, error: error.message };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function readBody(response) {
+  try {
+    return (await response.text()).trim().replace(/\s+/g, ' ');
+  } catch {
+    return '';
+  }
+}
+
+/** Collects stdout instead of using execFile, which cannot write to stdin. */
+export function spawnCommand({ command, args, stdin, cwd, timeoutMs, env }) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(command, args, { cwd, env, stdio: ['pipe', 'pipe', 'pipe'] });
+    } catch (error) {
+      resolve({ status: 'error', error: error.message });
+      return;
+    }
+    let stdout = '';
+    let stderr = '';
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill('SIGKILL');
+    }, timeoutMs);
+
+    child.stdout.on('data', (chunk) => {
+      if (stdout.length < MAX_OUTPUT_BYTES) stdout += chunk;
+    });
+    child.stderr.on('data', (chunk) => {
+      if (stderr.length < MAX_OUTPUT_BYTES) stderr += chunk;
+    });
+    child.stdin.on('error', () => {
+      // The provider closed stdin before reading the prompt; the exit code reports it.
+    });
+    child.on('error', (error) => {
+      clearTimeout(timer);
+      resolve({ status: 'error', error: error.code === 'ENOENT' ? `${command} not found in PATH` : error.message });
+    });
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      if (timedOut) resolve({ status: 'timeout' });
+      else if (code === 0) resolve({ status: 'ok', stdout });
+      else resolve({ status: 'error', error: failureLine(stderr) || `${command} exited with code ${code}` });
+    });
+    child.stdin.end(stdin ?? '');
+  });
+}
+
+/** Nothing leaves this module without passing the redaction layer. */
+function safe(value) {
+  return redactSecrets(String(value ?? ''));
+}
+
+/**
+ * The line of stderr that explains the failure. Agentic CLIs open with banners and notices,
+ * so the first line is usually noise and the cause is further down.
+ */
+function failureLine(text) {
+  const lines = String(text ?? '')
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean);
+  return lines.find((line) => /\b(error|failed|failure|unauthorized|forbidden|quota|unexpected|not found|invalid|denied)\b/i.test(line)) ?? lines.at(-1) ?? '';
+}

package/core/providers/providers.mjs

@@ -0,0 +1,156 @@
+import { accessSync, constants } from 'node:fs';
+import { join } from 'node:path';
+
+import { configPath, readConfig } from '../config/language.mjs';
+import { PROVIDERS, PROVIDER_IDS, findProvider, providerEndpoint, unknownProviderMessage } from './catalog.mjs';
+
+export { PROVIDERS, PROVIDER_IDS, findProvider, unknownProviderMessage } from './catalog.mjs';
+
+/**
+ * Status of a provider, decided without a single network call so `doctor` and `providers`
+ * stay offline:
+ *
+ * - `ready`     the executable is on PATH, or the credential is set
+ * - `local`     keyless local server: selectable, proven only by an actual request
+ * - `missing`   no executable and no credential
+ * - `disabled`  turned off in the user config
+ * - `blocked`   not in the `providers:` allowlist of .reis-mobile/config.yaml
+ */
+const SELECTABLE = new Set(['ready', 'local']);
+
+/**
+ * Finds an executable by scanning PATH instead of shelling out to `which`: one less
+ * subprocess, and a platform the tests can inject.
+ */
+export function findExecutable(command, { env = process.env, platform = process.platform } = {}) {
+  const separator = platform === 'win32' ? ';' : ':';
+  const extensions = platform === 'win32' ? (env.PATHEXT || '.COM;.EXE;.BAT;.CMD').split(';') : [''];
+  for (const directory of String(env.PATH || '').split(separator).filter(Boolean)) {
+    for (const extension of extensions) {
+      const candidate = join(directory, `${command}${extension}`);
+      try {
+        accessSync(candidate, platform === 'win32' ? constants.F_OK : constants.X_OK);
+        return candidate;
+      } catch {
+        // Not here; keep scanning.
+      }
+    }
+  }
+  return null;
+}
+
+/** The allowlist a team commits in `.reis-mobile/config.yaml`, or null when absent. */
+export function providerAllowlist(projectConfig) {
+  const value = projectConfig?.data?.providers;
+  if (value === undefined) return null;
+  const list = (Array.isArray(value) ? value : [value]).map((item) => String(item).trim()).filter(Boolean);
+  const unknown = list.filter((id) => !PROVIDER_IDS.includes(id));
+  if (unknown.length) {
+    return { ids: list.filter((id) => PROVIDER_IDS.includes(id)), warnings: unknown.map((id) => `${projectConfig.path}: ${unknownProviderMessage(id)}`) };
+  }
+  return { ids: list, warnings: [] };
+}
+
+/**
+ * Every provider with its status, resolved model and the evidence that decided both.
+ * `model` precedence: the `--model` flag, then the provider's model variable, then
+ * `providers.<id>.model` in the user config. CLI providers resolve no model: the spelling
+ * of their model flag is not verified here, so they keep the one they are configured with.
+ */
+export async function resolveProviders({
+  env = process.env,
+  platform = process.platform,
+  model: flagModel,
+  allow = null,
+  config,
+  path = configPath({ env }),
+} = {}) {
+  const settings = config ?? (await readConfig(path));
+  const providerSettings = settings.providers ?? {};
+  const warnings = [...(allow?.warnings ?? [])];
+
+  const providers = PROVIDERS.map((provider) => {
+    const setting = providerSettings[provider.id] ?? {};
+    const resolved = {
+      id: provider.id,
+      label: provider.label,
+      kind: provider.kind,
+      endpoint: providerEndpoint(provider, env),
+      docs: provider.docs,
+      needsModel: provider.needsModel === true,
+      model: null,
+      modelSource: null,
+      status: 'missing',
+      detail: '',
+    };
+
+    if (provider.kind === 'cli') {
+      const executable = findExecutable(provider.command, { env, platform });
+      resolved.status = executable ? 'ready' : 'missing';
+      resolved.detail = executable ?? `${provider.command} not found in PATH`;
+      resolved.model = null;
+      resolved.modelSource = 'provider';
+      if (setting.model || (flagModel && executable)) {
+        warnings.push(`${provider.id}: reis-mobile does not set the model of a CLI provider; it uses its own configuration`);
+      }
+    } else {
+      const key = provider.keys.find((candidate) => env[candidate]);
+      if (provider.local) {
+        resolved.status = 'local';
+        resolved.detail = `requires a server at ${resolved.endpoint}`;
+      } else {
+        resolved.status = key ? 'ready' : 'missing';
+        resolved.detail = key ? `${key} set` : `set ${provider.keys.join(' or ')}`;
+      }
+      const [value, source] = flagModel
+        ? [flagModel, '--model']
+        : env[provider.modelEnv]
+          ? [env[provider.modelEnv], provider.modelEnv]
+          : setting.model
+            ? [setting.model, `providers.${provider.id}.model`]
+            : [null, null];
+      resolved.model = value;
+      resolved.modelSource = source;
+    }
+
+    if (setting.enabled === false) {
+      resolved.status = 'disabled';
+      resolved.detail = `providers.${provider.id}.enabled is false`;
+    } else if (allow && !allow.ids.includes(provider.id)) {
+      resolved.status = 'blocked';
+      resolved.detail = 'not listed in the project providers allowlist';
+    }
+
+    resolved.selectable = SELECTABLE.has(resolved.status);
+    // A provider that needs a model and has none is selectable but not runnable: asking for
+    // it explicitly reports `no-model`, while the default selection leaves it out.
+    resolved.runnable = resolved.selectable && (!resolved.needsModel || Boolean(resolved.model));
+    if (resolved.selectable && !resolved.runnable) resolved.detail = `${resolved.detail} · no model configured`;
+    return resolved;
+  });
+
+  return { providers, warnings, configPath: path };
+}
+
+/**
+ * The providers a run should talk to. Requested ids that are not usable are kept in the
+ * result with their status instead of being dropped: a missing provider is information the
+ * caller has to report, not an error to swallow.
+ */
+export function selectProviders(providers, requested, { requireModel = true } = {}) {
+  if (!requested || requested.length === 0) {
+    return providers.filter((provider) => (requireModel ? provider.runnable : provider.selectable));
+  }
+  const unknown = requested.filter((id) => !PROVIDER_IDS.includes(id));
+  if (unknown.length) throw new Error(unknownProviderMessage(unknown[0]));
+  return requested.map((id) => providers.find((provider) => provider.id === id));
+}
+
+/** `--providers codex,openai` */
+export function parseProviderList(value) {
+  if (value === undefined || value === null) return null;
+  return String(value)
+    .split(',')
+    .map((item) => item.trim())
+    .filter(Boolean);
+}

package/core/router/intents.mjs

@@ -28,6 +28,21 @@ export const INTENTS = {
     'feature first', 'estrutura de pastas', 'state management', 'gerenciamento de estado',
     'injecao de dependencia', 'dependency injection', 'design pattern', 'camada',
   ],
+  offline: [
+    'offline', 'off-line', 'sem conexao', 'sem internet', 'sem rede', 'modo aviao',
+    'airplane mode', 'sincroniza', 'sync', 'dessincroniz', 'out of sync', 'conflito',
+    'conflict', 'idempot', 'fila de operac', 'operation queue', 'outbox', 'reconect',
+    'reconnect', 'local-first', 'local first', 'cache local', 'last write wins',
+    'ultima escrita vence', 'replica',
+  ],
+  observability: [
+    'observab', 'telemetri', 'telemetry', 'opentelemetry', 'crashlytics', 'sentry',
+    'datadog', 'new relic', 'firebase analytics', 'analytics', 'monitorament', 'monitoring',
+    'structured log', 'log estruturad', 'logging', 'alerta', 'alert', 'sampling',
+    'amostragem', 'distributed trac', 'trace distribu', 'correlation id', 'correlation-id',
+    'crash-free', 'crash free', 'error reporting', 'relatorio de erro', 'breadcrumb',
+    'slo', 'sli',
+  ],
   release: [
     'release', 'publica', 'publish', 'loja', 'app store', 'play store', 'testflight',
     'lancamento', 'submission', 'store review', 'rejeita', 'reject',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reis-mobile",
-  "version": "0.7.3",
+  "version": "0.9.0",
   "description": "AI agents and skills for Flutter, Android, iOS, React Native and Kotlin Multiplatform — a Claude Code and Codex plugin for reviews, debugging, tests, architecture, security and Firebase.",
   "type": "module",
   "license": "MIT",

package/skills/mobile-accessibility/SKILL.md

@@ -18,9 +18,12 @@ One accessibility process for every mobile stack. This file holds what is true e
 | Native iOS: SwiftUI or UIKit | [references/ios.md](references/ios.md) |
 | React Native or Expo | [references/react-native.md](references/react-native.md) |
 | Kotlin Multiplatform with shared Compose UI or native host UI | [references/kotlin-multiplatform.md](references/kotlin-multiplatform.md) |
+| Localization, plurals, formatting and right-to-left layout, on any stack | [references/localization.md](references/localization.md) |
 
 In Flutter and React Native apps, the native reference applies only to screens or components written natively (platform views, native modules with UI).
 
+Localization is reviewed with accessibility because it breaks the same things — a layout that assumed one text length, a fixed-height label, text baked into an image. When the app ships in more than one language, or in a right-to-left one, read [references/localization.md](references/localization.md) alongside this file.
+
 ## 2. What a screen reader user needs
 
 Every interactive element exposes four things to the accessibility tree. Check them in this order:

package/skills/mobile-accessibility/references/localization.md

@@ -0,0 +1,77 @@
+# Localization and internationalization
+
+Applies to every stack. Localization sits next to accessibility because it breaks the same things: a layout that assumed one text length, a string that assumed one grammar, and a date that assumed one calendar. An app that survives the largest accessibility font size usually survives German; one that does not, does not.
+
+## The rules that hold on every platform
+
+**No user-visible string in code.** Every string lives in the platform's resource system, keyed, with the source language as the base. A hard-coded string is not translatable and will not be found by review; grep for string literals inside UI code as the first pass of an audit.
+
+**Never build a sentence by concatenation.** `"You have " + n + " messages"` cannot be translated: word order, pluralization and grammatical gender all differ. Use a parameterized string with named placeholders, so the translator can reorder them:
+
+```
+"order_shipped_on": "Your order {orderId} ships on {date}"
+```
+
+**Plurals are a category, not a number.** English has two forms; Polish has four; Arabic has six; Japanese has one. `if (n == 1)` is wrong in most languages. Every platform implements the CLDR plural categories (`zero`, `one`, `two`, `few`, `many`, `other`) — use them:
+
+| Stack | Mechanism |
+|---|---|
+| Android | `<plurals>` resources and `getQuantityString` |
+| iOS | A stringsdict / the `String Catalog`'s plural variations, with `NSLocalizedString` |
+| Flutter | ICU message syntax in ARB files (`{count, plural, =0{...} one{...} other{...}}`) with `flutter_localizations` and `gen_l10n` |
+| React Native | `i18next` with the ICU or plural suffix conventions, `react-intl`, or `Intl.PluralRules` directly |
+| Kotlin Multiplatform | Compose Multiplatform resources, or host resources through `expect`/`actual` — check the plural support of the version in use |
+
+**Never format data by hand.** Dates, times, numbers, currencies, percentages, lists and relative times all have locale rules, and `"$" + amount` is wrong in most of the world. Use the platform formatter (`NumberFormat`/`DateTimeFormatter`, `Intl.*`, `NumberFormat`/`DateFormat` in Dart's `intl`, `FormatStyle` in Swift). Currency in particular: the symbol, its position, the decimal separator and the number of decimal places are all per-locale, and the currency itself is a property of the *price*, not of the user.
+
+**Device locale, app language, and region are three things.** A user can read Portuguese, live in Japan and want metric units. Recent platforms support a per-app language setting (Android's per-app language preferences, iOS's app language in Settings) — support it rather than reading only the device's first locale, and never infer language from the country or from a SIM.
+
+## Right-to-left
+
+Arabic, Hebrew, Persian and Urdu mirror the interface. Getting this right is mostly a matter of never expressing a direction as "left" or "right":
+
+- Use **start/end** everywhere: `paddingStart`, `layoutDirection`-aware `EdgeInsets.directional`, `marginStart`, SwiftUI's automatic leading/trailing. A `paddingLeft` is a bug in RTL.
+- **Icons that imply direction mirror; icons that depict objects do not.** A back arrow and a progress chevron mirror; a play button, a clock and a logo do not. Both platforms have a flag for automatic mirroring (`autoMirrored` in Android vector drawables and Material icons, `flipsForRightToLeftLayoutDirection` on iOS images, `matchTextDirection` in Flutter); set it deliberately per icon.
+- **Numbers and embedded Latin text inside RTL** follow the bidirectional algorithm and can render in a surprising order. Test with real strings containing a phone number, a price and a URL.
+- Test it without waiting for a translation: Android's "Force RTL layout direction" developer option, Xcode's right-to-left pseudolanguage, and Flutter's `Directionality` widget in a test all show the layout before any Arabic exists.
+
+## Layout that survives translation
+
+- **Assume text grows.** German, Finnish and Russian commonly run 30–50% longer than English, and short strings grow proportionally more. Buttons and tabs with fixed widths, and single-line labels with `maxLines: 1` and no ellipsis, are where this shows.
+- **No fixed heights on text containers**, for the same reason as text scaling in [the accessibility checklist](../SKILL.md).
+- **Do not put text into images.** It cannot be translated, it does not scale with the font size setting, and screen readers cannot read it.
+- **Pseudolocalization** finds these before translation exists: both platforms can render the app in an accented, expanded pseudo-language that makes truncation and hard-coded strings obvious at a glance. Run it in the normal review pass.
+
+## Giving translators what they need
+
+A translator sees a key and a string, not the screen. Ambiguous strings become wrong translations:
+
+- **Comments on every non-obvious string.** "Open" as a verb on a button and "Open" as a status adjective are different words in most languages, and the resource comment is the only way the translator knows which.
+- **Character limits** where the UI constrains the text, declared with the string.
+- **Stable keys** that describe the role (`checkout_confirm_button`), not the English text — renaming the English copy should not orphan the translation.
+- **Keep the placeholders documented**: what `{count}` counts, what `{name}` names.
+
+## Reviewing
+
+- [ ] No user-visible string literals in UI code.
+- [ ] No sentence assembled by concatenation or string interpolation of fragments.
+- [ ] Plurals use the platform's plural resources, not `if (n == 1)`.
+- [ ] Dates, numbers and currencies use a locale-aware formatter; no manual symbol or separator.
+- [ ] Layout uses start/end, not left/right; directional icons are marked as mirrorable.
+- [ ] No fixed widths or heights on text containers; no text baked into images.
+- [ ] The per-app language setting is supported, and the app does not infer language from the region.
+- [ ] Strings carry comments and, where relevant, length limits.
+- [ ] The app has been seen in pseudolocale and in forced RTL, at the largest font size.
+- [ ] Anything untranslated falls back to the base language rather than showing a key.
+
+The last three are the ones that catch real defects. Everything else can pass review and still produce a broken screen in Arabic at 200% font size, which is why the check is visual.
+
+## Official documentation
+
+- Android localization: https://developer.android.com/guide/topics/resources/localization
+- Android per-app language preferences: https://developer.android.com/guide/topics/resources/app-languages
+- Android bidirectional text support: https://developer.android.com/training/basics/supporting-devices/languages
+- Apple localization: https://developer.apple.com/documentation/xcode/localization
+- Flutter internationalization: https://docs.flutter.dev/ui/accessibility-and-internationalization/internationalization
+- React Native right-to-left and localization: https://reactnative.dev/blog/2016/08/19/right-to-left-support-for-react-native-apps
+- Unicode CLDR plural rules: https://cldr.unicode.org/index/cldr-spec/plural-rules

package/skills/mobile-observability/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: mobile-observability
+description: Designs and reviews production observability for mobile apps on every stack — Flutter, native Android, native iOS, React Native and Kotlin Multiplatform. Covers crash and error reporting with usable context, breadcrumbs, structured logs, traces and custom metrics, release and cohort segmentation, correlation with backend requests, alerting thresholds, sampling and cost, and what must never be collected. Use when production problems cannot be explained from the available data, when setting up crash reporting or telemetry, or when defining release health alerts.
+intents: [observability]
+stacks: ["*"]
+---
+
+# Mobile Observability
+
+What you can learn about the app after it has shipped, on every stack. This file holds the model, the segmentation rules and the privacy limits; each platform's SDKs, symbol upload and field-metric sources live in its reference.
+
+## 1. Pick the reference
+
+| Project | Read |
+|---|---|
+| Flutter | [references/flutter.md](references/flutter.md) |
+| Native Android | [references/android.md](references/android.md) |
+| Native iOS | [references/ios.md](references/ios.md) |
+| React Native or Expo | [references/react-native.md](references/react-native.md) |
+| Kotlin Multiplatform | [references/kotlin-multiplatform.md](references/kotlin-multiplatform.md) |
+
+Firebase Crashlytics, Analytics and Performance Monitoring setup per stack is in [mobile-firebase](../mobile-firebase/SKILL.md). Release gating on these signals is in [mobile-release](../mobile-release/SKILL.md); the lab counterpart of the performance metrics is in [mobile-performance](../mobile-performance/SKILL.md).
+
+## 2. Mobile is not a server
+
+Everything below follows from four differences, and ignoring them is what produces a telemetry setup that costs money and answers nothing:
+
+1. **You cannot log in to the device.** There is no `kubectl logs`. If the data was not collected and sent before the user gave up, it does not exist.
+2. **The old version never goes away.** A server rolls back in minutes; an app version lives on devices for months. Every signal must be sliced by app version, or a fixed bug and a live bug look identical in the aggregate.
+3. **The device is the constraint.** Telemetry costs the user's battery, data plan and storage. A payload sent per event is a wakeup per event — see [background.md](../mobile-performance/references/background.md).
+4. **Reports arrive late and out of order.** A crash is reported on the *next* launch; a device offline for a week uploads a week later. Never read the last hour of a metric as "what is happening now" without accounting for the reporting delay.
+
+## 3. The signals, and what each one answers
+
+| Signal | Answers | Usual failure |
+|---|---|---|
+| **Crashes** | The process died. Where, on which OS/device/version | Obfuscated stack traces — symbols not uploaded |
+| **Non-fatal errors** | A caught failure the user saw as a broken screen | Everything caught and logged, so the important one is invisible |
+| **ANRs / hangs / terminations** | The app froze or was killed, without a crash report | Only watching crashes and missing the majority of bad sessions |
+| **Breadcrumbs** | What the user did in the seconds before the failure | Free text with no structure, useless for grouping |
+| **Structured logs** | The detail behind one session | Sent for every session, at full volume, at full cost |
+| **Traces / spans** | Where the time went in one flow, across app and backend | Instrumented only in the app, so the backend half is invisible |
+| **Metrics** | The aggregate: latency percentiles, success rates, adoption | Averages instead of percentiles |
+| **Product analytics** | Whether the user completed the journey at all | Treated as observability; it shows the drop, never the cause |
+
+A production incident needs at least three of these to be explainable: **what broke** (crash/error), **what led to it** (breadcrumbs/logs), and **how many users** (metrics segmented by version).
+
+## 4. Segmentation: the dimensions that must be on every signal
+
+Attach these to every crash, error, span and metric, or the data cannot be sliced when it matters:
+
+- **App version and build number** — non-negotiable; every comparison is version-over-version.
+- **OS version and device model** — most "random" crashes are one OS version or one manufacturer.
+- **Release channel / rollout stage** — internal, beta, staged rollout percentage, full.
+- **A stable install id**, not a user id, for counting affected users. It must be resettable and must not follow the person across reinstalls or apps (see §8).
+- **Locale and region** where formatting, right-to-left layout or regulation differ.
+- **Connectivity class** at the time (offline, cellular, Wi-Fi) for anything network-related.
+- **Feature flag / experiment state** for flags that change the code path. A crash present only in one variant is otherwise unattributable.
+
+Keep the cardinality bounded. A dimension whose value is a user id, a timestamp or a free-text message turns a metric into millions of series and is the standard way to make an observability bill unpayable.
+
+## 5. Error context: make one report enough
+
+A stack trace alone rarely explains a mobile failure. A report is useful when it carries:
+
+- **The stack trace, symbolicated.** Verify symbol upload in CI for every build variant — an unsymbolicated release build is the most common and most expensive gap. The reference names the mechanism per stack.
+- **Custom keys** for the state that decides the code path: the screen, the entity id being acted on, the auth state, whether the outbox was non-empty, the flag values.
+- **Breadcrumbs as structured events**, not sentences: `screen_view{name}`, `network{method, host, status, ms}`, `tap{target}`, `state_change{from, to}`. Cap them (the last 50–100) and drop the payloads.
+- **The grouping key.** Reports group by stack signature; a generic wrapper (`throw AppException(e)`) collapses a hundred distinct causes into one issue and hides all of them. Preserve the cause chain, and put the variable detail in keys, not in the exception message.
+- **A correlation id** shared with the backend (§6).
+- **Whether the user saw it.** A caught-and-recovered error and a blank screen are different severities and should be distinguishable without reading code.
+
+## 6. Correlation with the backend
+
+Mobile latency is mostly backend latency, and the app's "the request was slow" is unactionable on its own.
+
+- Generate a **request id** per outbound call on the device, send it in a header, log it on both sides, and put it on the client-side span and on any error report from that call. One id makes "slow for this user at that minute" a single backend query instead of a guess.
+- Use **W3C Trace Context** (`traceparent`) when the backend is already traced, so the mobile span is the parent of the server spans rather than a disconnected record. OpenTelemetry clients exist for mobile; the reference names the current state per stack.
+- Attach a **session id** that spans the app session, so several failing calls can be recognized as one bad session.
+- **Propagate nothing sensitive** in these headers, and never put a token in a trace attribute.
+
+Without correlation, the mobile team and the backend team argue from two datasets. With it, the argument is a join.
+
+## 7. Alerting: on the few things that mean "stop the rollout"
+
+Most mobile alerts are noise because they fire on a raw count that tracks daily usage. Alert on **rates**, segmented by version, with the reporting delay in mind:
+
+| Alert | Reasonable shape |
+|---|---|
+| Crash-free sessions drop | Below your baseline (commonly 99.5%+ for a mature app) **for the new version**, compared against the previous one |
+| ANR / hang rate | Above the platform's own bad-behaviour threshold; both stores act on this |
+| New issue in a new release | Any issue whose first occurrence is this version and which affects more than N users — this is the one that stops a staged rollout |
+| Critical journey success rate | Login, checkout, sync drain: success percentage per version, not per absolute count |
+| Startup and key-screen latency | P90, per version, against the previous release's value |
+
+Rules that keep alerts trustworthy: compare a version against the previous version and not against last week; require a minimum session count before a percentage can fire; suppress alerts during the first minutes of a rollout when the denominator is tiny; and route each alert to someone who can act — a page for release health, a dashboard for everything else. An alert nobody acts on should be deleted, not muted.
+
+## 8. Sampling and cost
+
+Full-fidelity telemetry from every session is neither affordable nor kind to the device.
+
+- **Never sample crashes, ANRs or fatal errors.** They are rare and each one matters.
+- **Sample traces and verbose logs** — a small percentage of sessions at full detail answers most questions. Make the decision **per session, not per event**, so a sampled session is complete and readable end to end.
+- **Always keep the sessions that failed.** Sampling that discards the broken session is worse than no sampling: raise the rate for sessions with an error, or buffer locally and upload only on failure.
+- **Batch uploads**, with a size and a time bound, and flush on background/terminate. One flush per event is a radio wakeup per event.
+- **Bound the local buffer** and drop the oldest when it is full; an unbounded telemetry queue fills the device and turns a monitoring feature into a support ticket.
+- **Respect the network.** Do not upload telemetry on metered or constrained connections unless it is a crash report.
+- **Record the sampling rate with the data.** A percentile computed from a sampled set without knowing the rate is wrong, and someone will read it as absolute.
+
+## 9. What must never be collected
+
+Observability is where privacy violations happen by accident, because logging "the request" logs whatever was in it.
+
+- **Never log:** passwords, tokens, refresh tokens, API keys, full payment data, government ids, health data, precise location, message or document contents, or full request/response bodies from authenticated endpoints.
+- **Redact at the source**, in the SDK's callback before send (every reporter has one), not in the backend pipeline. Data that left the device is already disclosed.
+- **URLs carry secrets** in query strings — strip query parameters, or allow-list them. A URL is an attribute, not a free-text field.
+- **Crash reports include more than you sent**: register values, thread names, and sometimes fragments of memory in native crashes. Treat the whole report as sensitive and restrict who can read it.
+- **Consent gates collection.** On both stores, telemetry and analytics must match the declared data-safety/privacy-nutrition disclosures and the app's consent state. A user who declined analytics must not have analytics sent, and the SDK must be initialized accordingly — not initialized and then asked to stay quiet.
+- **Prefer aggregation and short retention** for anything user-linked, and be able to delete a person's data on request, which requires the install id to be mappable and resettable.
+
+This overlaps with [mobile-security](../mobile-security/SKILL.md); when in doubt, the answer is to send less.
+
+## 10. Reviewing an existing setup
+
+- [ ] Symbol/mapping upload happens in CI for every shipped variant, and a release build's crash is verifiably readable.
+- [ ] App version, OS, device, channel and flag state are on every signal.
+- [ ] ANRs, hangs and background terminations are collected, not just crashes.
+- [ ] Caught errors are distinguishable from user-visible failures, and grouping is not collapsed by a generic wrapper.
+- [ ] Breadcrumbs are structured and capped; logs are sampled; crashes are not.
+- [ ] A client-generated correlation id reaches the backend and appears in error reports.
+- [ ] Alerts are rate-based, per version, with a minimum-volume guard, and each one has an owner.
+- [ ] Telemetry uploads are batched, bounded, flushed on background, and off on metered connections.
+- [ ] A redaction callback exists and is tested; no secrets, bodies or precise location are sent.
+- [ ] Collection respects consent and matches the store privacy declarations.
+- [ ] Someone can answer "how many users on 4.2.0 hit this, and what were they doing" without adding code.
+
+The last line is the real test. If answering an ordinary production question requires shipping a new build and waiting two weeks for adoption, the setup has failed regardless of how many SDKs are installed.